Documentation — Spybara

admin-setup.md +3 −3

Details

94受管設定可以鎖定工具、沙箱執行、限制 MCP 伺服器和外掛程式來源，以及控制哪些 hooks 執行。每一行都是一個控制表面，具有驅動它的設定鍵。94受管設定可以鎖定工具、沙箱執行、限制 MCP 伺服器和外掛程式來源，以及控制哪些 hooks 執行。每一行都是一個控制表面，具有驅動它的設定鍵。

95 95

96| 控制 | 它的作用 | 關鍵設定 |96| 控制 | 它的作用 | 關鍵設定 |

97| :---------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |97| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |

99| [Permission lockdown](/docs/zh-TW/permissions#managed-only-settings) | 使受管設定成為[唯一的權限規則設定來源](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly)。禁用 `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |99| [Permission lockdown](/docs/zh-TW/permissions#managed-only-settings) | 使受管設定成為[唯一的權限規則設定來源](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly)。禁用 `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |

100| [Starting permission mode](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in) | 選擇開發人員終端會話啟動時的權限模式，而不是內建的啟動權限模式，或移除自動模式。VS Code 擴充功能僅在 Pro、Max 和 Team 方案上讀取您設定的 `defaultMode`；[切換權限模式](/docs/zh-TW/permission-modes#switch-permission-modes)列出擴充功能讀取的內容 | `permissions.defaultMode`、`permissions.disableAutoMode` |100| [Starting permission mode](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in) | 選擇開發人員終端會話啟動時的權限模式，而不是內建的啟動權限模式，或移除自動模式。VS Code 擴充功能僅在 Pro、Max 和 Team 方案上讀取您設定的 `defaultMode`；[切換權限模式](/docs/zh-TW/permission-modes#switch-permission-modes)列出擴充功能讀取的內容 | `permissions.defaultMode`、`permissions.disableAutoMode` |

103| [MCP server control](/docs/zh-TW/managed-mcp) | 限制使用者可以新增或連接的 MCP 伺服器、部署固定集合，或為每個使用者提供遠端伺服器以及他們自己的伺服器 | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly`、`managedMcpServers`，或已部署的 `managed-mcp.json` 檔案 |103| [MCP server control](/docs/zh-TW/managed-mcp) | 限制使用者可以新增或連接的 MCP 伺服器、部署固定集合，或為每個使用者提供遠端伺服器以及他們自己的伺服器 | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly`、`managedMcpServers`，或已部署的 `managed-mcp.json` 檔案 |

104| [Plugin marketplace control](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | 限制使用者可以新增和安裝的市場來源、拒絕為單次執行側載外掛程式、agents 和 MCP 伺服器的 CLI 旗標、阻止[`command` 外掛程式來源](/docs/zh-TW/plugin-marketplaces#command-sources)，以及允許清單哪些市場的外掛程式可以被建議 | `strictKnownMarketplaces`、`blockedMarketplaces`、`disableSideloadFlags`、`disableCommandPluginSources`、`pluginSuggestionMarketplaces` |104| [Plugin marketplace control](/docs/zh-TW/plugins/org#restrict-what-users-can-install) | 限制使用者可以新增和安裝的市場來源、拒絕為單次執行側載外掛程式、agents 和 MCP 伺服器的 CLI 旗標、阻止[`command` 外掛程式來源](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)，以及允許清單哪些市場的外掛程式可以被建議 | `strictKnownMarketplaces`、`blockedMarketplaces`、`disableSideloadFlags`、`disableCommandPluginSources`、`pluginSuggestionMarketplaces` |

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

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

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

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

agent-sdk/permissions.md +1 −1

Details

281 略過權限模式（`bypassPermissions`）281 略過權限模式（`bypassPermissions`）

282</h4>282</h4>

283 283

284自動核准工具使用而不提示，除了下面警告中列出的情況。鉤子仍然執行，如果需要可以阻止操作。284自動核准工具使用而不提示，除了下面警告中列出的情況。鉤子仍然執行，如果需要可以阻止操作。在 Linux 和 macOS 上，Claude Code 拒絕在此模式下以 root 身份或在[已識別的沙箱](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)外的 `sudo` 下啟動，查詢在第一個回合之前失敗。

285 285

286<Warning>286<Warning>

287 請極其謹慎使用。Claude 在此模式中具有完整的系統存取權。僅在您信任所有可能操作的受控環境中使用。287 請極其謹慎使用。Claude 在此模式中具有完整的系統存取權。僅在您信任所有可能操作的受控環境中使用。

agent-sdk/plugins.md +7 −7

Details

13* **Hooks**：響應工具使用和其他事件的事件處理程序13* **Hooks**：響應工具使用和其他事件的事件處理程序

14* **MCP servers**：通過 Model Context Protocol 的外部工具集成14* **MCP servers**：通過 Model Context Protocol 的外部工具集成

15 15

~~16有關 plugin 結構和如何創建 plugins 的完整資訊，請參閱 [Plugins](/docs/zh-TW/plugins)。~~16有關 plugin 結構和如何創建 plugins 的完整資訊，請參閱 [Plugins](/docs/zh-TW/plugins/overview)。

17 17

18<h2 id="loading-plugins">18<h2 id="loading-plugins">

19 加載 plugins19 加載 plugins

20</h2>20</h2>

21 21

~~22通過在選項配置中提供本地文件系統路徑來加載 plugins。`type` 字段必須是 `"local"`，這是 SDK 接受的唯一值。SDK 支持從不同位置加載多個 plugins。~~22通過在選項設定中提供本地檔案系統路徑來加載 plugins。`type` 欄位必須是 `"local"`，這是 SDK 接受的唯一值。SDK 支援從不同位置加載多個 plugins。

23 23

24若要使用通過 [marketplace](/docs/zh-TW/plugin-marketplaces) 或遠程存儲庫分發的 plugin，請先下載它並提供本地目錄路徑。有關 plugin 需要的目錄佈局，請參閱下面的 [Plugin 結構參考](#plugin-structure-reference)。24若要使用通過 [marketplace](/docs/zh-TW/plugins/overview) 或遠端存儲庫分發的 plugin，請先下載它並提供本地目錄路徑。有關 plugin 需要的目錄佈局，請參閱下面的 [Plugin 結構參考](#plugin-structure-reference)。

25 25

26<CodeGroup>26<CodeGroup>

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

70Plugin 路徑可以是：70Plugin 路徑可以是：

71 71

72* **相對路徑**：相對於 `cwd` 選項解析（例如，`"./plugins/my-plugin"`）72* **相對路徑**：相對於 `cwd` 選項解析（例如，`"./plugins/my-plugin"`）

~~73* **絕對路徑**：完整文件系統路徑（例如，`"/home/user/plugins/my-plugin"`）~~73* **絕對路徑**：完整檔案系統路徑（例如，`"/home/user/plugins/my-plugin"`）

74 74

75<Note>75<Note>

76 路徑應指向 plugin 的根目錄：`skills/`、`agents/`、`hooks/`、`commands/` 或 `.claude-plugin/` 的父目錄。76 路徑應指向 plugin 的根目錄：`skills/`、`agents/`、`hooks/`、`commands/` 或 `.claude-plugin/` 的父目錄。

138 ```138 ```

139</CodeGroup>139</CodeGroup>

140 140

141<h2 id="using-plugin-skills">141<h2 id="use-plugin-skills">

142 使用 plugin skills142 使用 plugin skills

143</h2>143</h2>

144 144

352 另請參閱352 另請參閱

353</h2>353</h2>

354 354

355* [Plugins](/docs/zh-TW/plugins) - 完整的 plugin 開發指南355* [Plugins](/docs/zh-TW/plugins/overview) - 完整的 plugin 開發指南

356* [Plugins reference](/docs/zh-TW/plugins-reference) - 技術規範356* [Plugins reference](/docs/zh-TW/plugins/manifest-reference) - 技術規範

357* [Commands](/docs/zh-TW/agent-sdk/skills#dispatch-commands-by-name) - 在 SDK 中分派命令357* [Commands](/docs/zh-TW/agent-sdk/skills#dispatch-commands-by-name) - 在 SDK 中分派命令

358* [Subagents](/docs/zh-TW/agent-sdk/subagents) - 使用專門的 agents358* [Subagents](/docs/zh-TW/agent-sdk/subagents) - 使用專門的 agents

359* [Skills](/docs/zh-TW/agent-sdk/skills) - 使用 Agent Skills359* [Skills](/docs/zh-TW/agent-sdk/skills) - 使用 Agent Skills

agent-sdk/python.md +83 −83

Details

779 annotations: ToolAnnotations | None = None779 annotations: ToolAnnotations | None = None

780```780```

781 781

782| 屬性 | 類型 | 描述 |782| 屬性 | 類型 | 說明 |

783| :------------- | :---------------------------------------------- | :-------------------------------------------------------------------------------- |783| :------------- | :---------------------------------------------- | :-------------------------------------------------------------------------------- |

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

785| `description` | `str` | 人類可讀的描述 |785| `description` | `str` | 人類可讀的說明 |

791 `Transport`791 `Transport`

792</h3>792</h3>

793 793

794自訂傳輸實作的抽象基類。使用此類別透過自訂通道與 Claude 程序通訊（例如，遠端連線而不是本機子程序）。794自訂傳輸實作的抽象基底類別。使用此類別透過自訂通道與 Claude 程序通訊（例如，遠端連線而不是本機子程序）。

795 795

796<Warning>796<Warning>

797 這是低階內部 API。介面可能在未來版本中變更。自訂實作必須更新以符合任何介面變更。797 這是低階內部 API。介面可能在未來版本中變更。自訂實作必須更新以符合任何介面變更。

823 async def end_input(self) -> None: ...823 async def end_input(self) -> None: ...

824```824```

825 825

826| 方法 | 描述 |826| 方法 | 說明 |

827| :---------------- | :------------------------ |827| :---------------- | :------------------------ |

893 task_budget: TaskBudget | None = None893 task_budget: TaskBudget | None = None

894```894```

895 895

896| 屬性 | 類型 | 預設值 | 描述 |896| 屬性 | 類型 | 預設值 | 說明 |

897| :---------------------------- | :--------------------------------------------------------------------------------------- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |897| :---------------------------- | :--------------------------------------------------------------------------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

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

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

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

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

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

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

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

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

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

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

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

946 946

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

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

962)962)

963```963```

964 964

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

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

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

968 968

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

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

971 971

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

973 973

974<h3 id="outputformat">974<h3 id="outputformat">

975 `OutputFormat`975 `OutputFormat`

985}985}

986```986```

987 987

988| 欄位 | 必要 | 描述 |988| 欄位 | 必要 | 說明 |

989| :------- | :- | :------------------------------------- |989| :------- | :- | :------------------------------------- |

990| `type` | 是 | 必須是 `"json_schema"` 以進行 JSON Schema 驗證 |990| `type` | 是 | 必須為 `"json_schema"` 以進行 JSON Schema 驗證 |

991| `schema` | 是 | 用於輸出驗證的 JSON Schema 定義 |991| `schema` | 是 | 用於輸出驗證的 JSON Schema 定義 |

992 992

993<h3 id="systempromptpreset">993<h3 id="systempromptpreset">

1005 snapshot: NotRequired[bool]1005 snapshot: NotRequired[bool]

1006```1006```

1007 1007

1008| 欄位 | 必要 | 描述 |1008| 欄位 | 必要 | 說明 |

1009| :------------------------- | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1009| :------------------------- | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

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

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

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

1015 1015

1016<h3 id="systempromptcustom">1016<h3 id="systempromptcustom">

1017 `SystemPromptCustom`1017 `SystemPromptCustom`

1026 snapshot: NotRequired[bool]1026 snapshot: NotRequired[bool]

1027```1027```

1028 1028

1029| 欄位 | 必要 | 描述 |1029| 欄位 | 必要 | 說明 |

1030| :--------- | :- | :--------------------------------------------------------------------- |1030| :--------- | :- | :--------------------------------------------------------------------- |

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

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

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

1034 1034

1035<h3 id="systempromptfile">1035<h3 id="systempromptfile">

1036 `SystemPromptFile`1036 `SystemPromptFile`

1037</h3>1037</h3>

1038 1038

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

1040 1040

1041```python theme={null}1041```python theme={null}

1042class SystemPromptFile(TypedDict):1042class SystemPromptFile(TypedDict):

1044 path: str1044 path: str

1045```1045```

1046 1046

1047| 欄位 | 必要 | 描述 |1047| 欄位 | 必要 | 說明 |

1048| :----- | :- | :-------------------- |1048| :----- | :- | :-------------------- |

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

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

1051 1051

1052<h3 id="settingsource">1052<h3 id="settingsource">

1053 `SettingSource`1053 `SettingSource`

1054</h3>1054</h3>

1055 1055

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

1057 1057

1058```python theme={null}1058```python theme={null}

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

1060```1060```

1061 1061

1062| 值 | 描述 | 位置 |1062| 值 | 說明 | 位置 |

1063| :---------- | :---------------------------------------- | :---------------------------- |1063| :---------- | :---------------------------------------- | :---------------------------- |

1067 1067

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

1069 預設行為1069 預設行為

1078**停用檔案系統設定：**1078**停用檔案系統設定：**

1079 1079

1080```python theme={null}1080```python theme={null}

1081# 不從磁碟載入使用者、專案或本機設定1081# 不要從磁碟載入使用者、專案或本機設定

1082import asyncio1082import asyncio

1083from claude_agent_sdk import query, ClaudeAgentOptions1083from claude_agent_sdk import query, ClaudeAgentOptions

1084 1084

1097```1097```

1098 1098

1099<Note>1099<Note>

1100 在 Python SDK 0.1.59 及更早版本中，空清單的處理方式與省略選項相同，因此 `setting_sources=[]` 未停用檔案系統設定。如果您需要空清單生效，請升級至較新版本。TypeScript SDK 不受影響。1100 在 Python SDK 0.1.59 及更早版本中，空清單的處理方式與省略選項相同，因此 `setting_sources=[]` 未停用檔案系統設定。如果您需要空清單生效，請升級到較新版本。TypeScript SDK 不受影響。

1101</Note>1101</Note>

1102 1102

1103**僅載入特定設定來源：**1103**僅載入特定設定來源：**

1156 設定優先順序1156 設定優先順序

1157</h4>1157</h4>

1158 1158

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

1160 1160

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

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

1168 `AgentDefinition`1168 `AgentDefinition`

1169</h3>1169</h3>

1170 1170

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

1172 1172

1173```python theme={null}1173```python theme={null}

1174@dataclass1174@dataclass

1188 permissionMode: PermissionMode | None = None1188 permissionMode: PermissionMode | None = None

1189```1189```

1190 1190

1191| 欄位 | 必要 | 描述 |1191| 欄位 | 必要 | 說明 |

1192| :---------------- | :- | :--------------------------------------------------------------------------------------------------------------------------------------- |1192| :---------------- | :- | :--------------------------------------------------------------------------------------------------------------------------------------- |

1193| `description` | 是 | 何時使用此代理的自然語言描述 |1193| `description` | 是 | 何時使用此代理的自然語言說明 |

1194| `prompt` | 是 | 代理的系統提示 |1194| `prompt` | 是 | 代理的系統提示 |

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

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

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

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

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

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

1201| `initialPrompt` | 否 | 當此代理作為主執行緒代理執行時自動提交為第一個使用者轉數 |1201| `initialPrompt` | 否 | 當此代理作為主執行緒代理執行時自動提交為第一個使用者轉 |

1202| `maxTurns` | 否 | 代理停止前的最大代理轉數 |1202| `maxTurns` | 否 | 代理停止前的最大代理轉數 |

1203| `background` | 否 | 叫用時將此代理作為非阻塞背景任務執行 |1203| `background` | 否 | 叫用時以非封鎖背景工作執行此代理 |

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

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

1206 1206

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

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

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

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

1240 "max", # 最大努力1240 "max", # 最大努力

1241]1241]

1242```1242```

1261 1261

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

1263 1263

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

1265 1265

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

1267 1267

1268<h3 id="toolpermissioncontext">1268<h3 id="toolpermissioncontext">

1269 `ToolPermissionContext`1269 `ToolPermissionContext`

1285 description: str | None = None1285 description: str | None = None

1286```1286```

1287 1287

1288| 欄位 | 類型 | 描述 |1288| 欄位 | 類型 | 說明 |

1289| :---------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------ |1289| :---------------- | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------- |

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

1321 updated_permissions: list[PermissionUpdate] | None = None1321 updated_permissions: list[PermissionUpdate] | None = None

1322```1322```

1323 1323

1324| 欄位 | 類型 | 預設值 | 描述 |1324| 欄位 | 類型 | 預設值 | 說明 |

1325| :-------------------- | :------------------------------- | :-------- | :-------------- |1325| :-------------------- | :------------------------------- | :-------- | :-------------- |

1329 1329

1341 interrupt: bool = False1341 interrupt: bool = False

1342```1342```

1343 1343

1344| 欄位 | 類型 | 預設值 | 描述 |1344| 欄位 | 類型 | 預設值 | 說明 |

1345| :---------- | :---------------- | :------- | :----------- |1345| :---------- | :---------------- | :------- | :----------- |

1347| `message` | `str` | `""` | 說明為什麼拒絕工具的訊息 |1347| `message` | `str` | `""` | 說明為什麼拒絕工具的訊息 |

1349 1349

1373 ) = None1373 ) = None

1374```1374```

1375 1375

1376| 欄位 | 類型 | 描述 |1376| 欄位 | 類型 | 說明 |

1377| :------------ | :---------------------------------------- | :-------------- |1377| :------------ | :---------------------------------------- | :-------------- |

1386 `PermissionRuleValue`1386 `PermissionRuleValue`

1387</h3>1387</h3>

1388 1388

1389在權限更新中新增、取代或移除的規則。1389要在權限更新中新增、取代或移除的規則。

1390 1390

1391```python theme={null}1391```python theme={null}

1392@dataclass1392@dataclass

1435ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled1435ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled

1436```1436```

1437 1437

1438| 變體 | 欄位 | 描述 |1438| 變體 | 欄位 | 說明 |

1439| :--------- | :------------------------------- | :--------------- |1439| :--------- | :------------------------------- | :--------------- |

1448```python theme={null}1448```python theme={null}

1449from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled1449from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled

1450 1450

1451# 選項 1：字典常值（建議，無需匯入）1451# 選項 1：字典常值（建議，不需要匯入）

1452options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})1452options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})

1453 1453

1454# 選項 2：建構函式樣式（傳回純字典）1454# 選項 2：建構函式樣式（傳回純字典）

1461 `TaskBudget`1461 `TaskBudget`

1462</h3>1462</h3>

1463 1463

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

1465 1465

1466```python theme={null}1466```python theme={null}

1467class TaskBudget(TypedDict):1467class TaskBudget(TypedDict):

1468 total: int1468 total: int

1469```1469```

1470 1470

1471| 欄位 | 類型 | 描述 |1471| 欄位 | 類型 | 說明 |

1472| :------ | :---- | :------- |1472| :------ | :---- | :------- |

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

1474 1474

1487與 `ClaudeAgentOptions` 中的 `betas` 欄位搭配使用以啟用測試版功能。1487與 `ClaudeAgentOptions` 中的 `betas` 欄位搭配使用以啟用測試版功能。

1488 1488

1489<Warning>1489<Warning>

1490 `context-1m-2025-08-07` 測試版自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 傳遞此標頭無效，超過標準 200k 權杖內容視窗的請求會傳回錯誤。若要使用 1M 權杖內容視窗，請遷移至 [Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)，這些包含標準定價的 1M 內容，無需測試版標頭。1490 `context-1m-2025-08-07` 測試版自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 傳遞此標頭無效，超過標準 200k 權杖內容視窗的要求會傳回錯誤。若要使用 1M 權杖內容視窗，請遷移至 [Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)，其中包括標準定價的 1M 內容，無需測試版標頭。

1491</Warning>1491</Warning>

1492 1492

1493<h3 id="mcpsdkserverconfig">1493<h3 id="mcpsdkserverconfig">

1494 `McpSdkServerConfig`1494 `McpSdkServerConfig`

1495</h3>1495</h3>

1496 1496

1497使用 `create_sdk_mcp_server()` 建立的 SDK MCP 伺服器的設定。1497使用 `create_sdk_mcp_server()` 建立的 SDK MCP 伺服器設定。

1498 1498

1499```python theme={null}1499```python theme={null}

1500class McpSdkServerConfig(TypedDict):1500class McpSdkServerConfig(TypedDict):

1521 1521

1522```python theme={null}1522```python theme={null}

1523class McpStdioServerConfig(TypedDict):1523class McpStdioServerConfig(TypedDict):

1524 type: NotRequired[Literal["stdio"]] # 為了向後相容性而選用1524 type: NotRequired[Literal["stdio"]] # 為了向後相容性為選用

1525 command: str1525 command: str

1526 args: NotRequired[list[str]]1526 args: NotRequired[list[str]]

1527 env: NotRequired[dict[str, str]]1527 env: NotRequired[dict[str, str]]

1553 `McpServerStatusConfig`1553 `McpServerStatusConfig`

1554</h3>1554</h3>

1555 1555

1556由 [`get_mcp_status()`](#methods) 報告的 MCP 伺服器設定。這是所有 [`McpServerConfig`](#mcpserverconfig) 傳輸變體加上用於透過 claude.ai 代理的伺服器的輸出專用 `claudeai-proxy` 變體的聯合。1556由 [`get_mcp_status()`](#methods) 報告的 MCP 伺服器設定。這是所有 [`McpServerConfig`](#mcpserverconfig) 傳輸變體加上用於透過 claude.ai 代理的伺服器的僅輸出 `claudeai-proxy` 變體的聯合。

1557 1557

1558```python theme={null}1558```python theme={null}

1559McpServerStatusConfig = (1559McpServerStatusConfig = (

1565)1565)

1566```1566```

1567 1567

1568`McpSdkServerConfigStatus` 是 [`McpSdkServerConfig`](#mcpsdkserverconfig) 的可序列化形式，僅包含 `type`（`"sdk"`）和 `name`（`str`）欄位；進程內 `instance` 被省略。`McpClaudeAIProxyServerConfig` 具有 `type`（`"claudeai-proxy"`）、`url`（`str`）和 `id`（`str`）欄位。1568`McpSdkServerConfigStatus` 是 [`McpSdkServerConfig`](#mcpsdkserverconfig) 的可序列化形式，僅包含 `type`（`"sdk"`）和 `name`（`str`）欄位；程序內 `instance` 被省略。`McpClaudeAIProxyServerConfig` 具有 `type`（`"claudeai-proxy"`）、`url`（`str`）和 `id`（`str`）欄位。

1569 1569

1570<h3 id="mcpstatusresponse">1570<h3 id="mcpstatusresponse">

1571 `McpStatusResponse`1571 `McpStatusResponse`

1595 tools: NotRequired[list[McpToolInfo]]1595 tools: NotRequired[list[McpToolInfo]]

1596```1596```

1597 1597

1598| 欄位 | 類型 | 描述 |1598| 欄位 | 類型 | 說明 |

1599| :----------- | :---------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |1599| :----------- | :---------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |

1600| `name` | `str` | 伺服器名稱 |1600| `name` | `str` | 伺服器名稱 |

1601| `status` | `str` | `"connected"`、`"failed"`、`"needs-auth"`、`"pending"` 或 `"disabled"` 之一 |1601| `status` | `str` | `"connected"`、`"failed"`、`"needs-auth"`、`"pending"` 或 `"disabled"` 之一 |

1617 path: str1617 path: str

1618```1618```

1619 1619

1620| 欄位 | 類型 | 描述 |1620| 欄位 | 類型 | 說明 |

1621| :----- | :----------------- | :------------------------- |1621| :----- | :----------------- | :------------------------- |

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

1624 1624

1625**範例：**1625**範例：**

1885```1885```

1886 1886

1887| 欄位 | 類型 | 描述 |1887| 欄位 | 類型 | 描述 |

1888| :------------------------ | :------------------------ | :-------------------------------------------------- |1888| :------------------------ | :------------------------ | :---------------------------------------------------------------------------------------------------- |

agent-sdk/quickstart.md +4 −2

Details

275這就是 Agent SDK 的不同之處：Claude 直接執行工具，而不是要求您實作它們。275這就是 Agent SDK 的不同之處：Claude 直接執行工具，而不是要求您實作它們。

276 276

277<Note>277<Note>

278 如果您看到驗證錯誤，例如 `Not logged in` 或 `Invalid API key`，請確保您已在執行代理的 shell 中設定 `ANTHROPIC_API_KEY` 環境變數。SDK 不會自動載入 `.env` 檔案。如需更多協助，請參閱[完整疑難排解指南](/docs/zh-TW/troubleshooting)。278 如果您看到驗證錯誤，例如 `Not logged in` 或 `Invalid API key`，請確保您已在執行代理的 shell 中設定 `ANTHROPIC_API_KEY` 環境變數。SDK 不會自動載入 `.env` 檔案。

279

280 如需這些和其他驗證錯誤的原因和修復方法，請參閱錯誤參考中的[驗證錯誤](/docs/zh-TW/errors#authentication-errors)。

279</Note>281</Note>

280 282

281<h3 id="try-other-prompts">283<h3 id="try-other-prompts">

385* **[MCP servers](/docs/zh-TW/agent-sdk/mcp)**：連接到資料庫、瀏覽器、API 和其他外部系統387* **[MCP servers](/docs/zh-TW/agent-sdk/mcp)**：連接到資料庫、瀏覽器、API 和其他外部系統

386* **[Hosting](/docs/zh-TW/agent-sdk/hosting)**：將代理程式部署到 Docker、雲端和 CI/CD388* **[Hosting](/docs/zh-TW/agent-sdk/hosting)**：將代理程式部署到 Docker、雲端和 CI/CD

387* **[Example agents](https://github.com/anthropics/claude-agent-sdk-demos)**：查看完整範例：電子郵件助手、研究代理程式等389* **[Example agents](https://github.com/anthropics/claude-agent-sdk-demos)**：查看完整範例：電子郵件助手、研究代理程式等

388* **[Troubleshooting](/docs/zh-TW/agent-sdk/troubleshooting)**：根據您看到的確切訊息修復 Agent SDK 錯誤390* **[Troubleshooting](/docs/zh-TW/agent-sdk/troubleshooting)**：修復 CLI 無法啟動或退出時的錯誤，或結果未能以結構化輸出形式到達時的問題

agent-sdk/troubleshooting.md +17 −3

Details

4 4

5# 排除 Agent SDK 的故障5# 排除 Agent SDK 的故障

6 6

~~7> 根據您看到的確切錯誤訊息修復 Agent SDK 錯誤，包括 TypeScript 和 Python SDK 中每個錯誤的原因和修復方法。~~7> 當 Claude Code CLI 無法啟動、CLI 程序退出或成功結果到達但沒有結構化輸出時，修復 Agent SDK 錯誤。

8 8

~~9此頁面上的項目按您看到的錯誤進行分類。每個項目都說明原因和解決方法。~~9此頁面涵蓋 CLI 啟動、CLI 程序退出和結構化輸出中的 Agent SDK 錯誤。此頁面上的項目按您看到的錯誤進行分類。每個項目都說明原因和解決方法。

11與功能相關的症狀，例如 hook 未觸發或 skill 未被使用，在該功能的頁面上有故障排除部分。下表列出涵蓋每個症狀的部分或頁面：

13| 症狀 | 前往 |

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

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

16| MCP 伺服器顯示 `failed` 狀態、工具未被呼叫、連線逾時、工具輸出超過允許的最大令牌數 | [MCP 故障排除](/docs/zh-TW/agent-sdk/mcp#troubleshooting) |

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

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

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

20| Hook 未觸發、matcher 未如預期篩選、hook 逾時、工具意外被阻止、修改的輸入未被應用、Python 中無法使用工作階段 hooks、子代理權限提示增加、子代理的遞迴 hook 迴圈、`systemMessage` 未出現在輸出中 | [修復常見問題](/docs/zh-TW/agent-sdk/hooks#fix-common-issues)（在 hooks 頁面上） |

21| 在您的機器上運作的代理在已部署的服務或容器中失敗 | [故障排除部署失敗](/docs/zh-TW/agent-sdk/hosting#troubleshoot-deployment-failures) |

22| `Not logged in`、`Invalid API key`、`API Error`、`429`、`There's an issue with the selected model` | [錯誤參考](/docs/zh-TW/errors#find-your-error) |

23| `CLINotFoundError`、`CLIConnectionError`、`ProcessError`、`Claude Code process exited with code N`、`Claude Code returned an error result`、`structured_output` 是 `None` | 此頁面上的 [CLI 啟動](#cli-startup)、[CLI 程序退出](#cli-process-exit) 和 [結構化輸出](#structured-outputs) |

10 24

11<h2 id="cli-startup">25<h2 id="cli-startup">

12 CLI 啟動26 CLI 啟動

agent-teams.md +1 −1

Details

118 118

119預設值是 `"in-process"`。設定 `"auto"` 以在您已在 tmux 工作階段內運行或您的終端是已安裝 `it2` CLI 的 iTerm2 時啟用分割窗格，否則回退到 in-process。`"tmux"` 設定啟用分割窗格模式，並根據您的終端自動偵測是否使用 tmux 或 iTerm2。119預設值是 `"in-process"`。設定 `"auto"` 以在您已在 tmux 工作階段內運行或您的終端是已安裝 `it2` CLI 的 iTerm2 時啟用分割窗格，否則回退到 in-process。`"tmux"` 設定啟用分割窗格模式，並根據您的終端自動偵測是否使用 tmux 或 iTerm2。

120 120

121自 v2.1.186 起，設定 `"iterm2"` 以明確使用 iTerm2 原生分割窗格。此模式需要 [`it2` CLI](https://github.com/mkusaka/it2)，如果 `it2` 遺失，會顯示帶有安裝命令的錯誤。當您的終端是 iTerm2 且 tmux 可作為備用方案時，在 `"auto"` 或 `"tmux"` 下會出現提供安裝 `it2` 或切換到 tmux 的設定提示。121設定 `"iterm2"` 以明確使用 iTerm2 原生分割窗格。此模式需要 [`it2` CLI](https://github.com/mkusaka/it2)，如果 `it2` 遺失，會顯示帶有安裝命令的錯誤。當您的終端是 iTerm2 且 tmux 可作為備用方案時，在 `"auto"` 或 `"tmux"` 下會出現提供安裝 `it2` 或切換到 tmux 的設定提示。

122 122

123若要覆蓋預設值，請在 `~/.claude/settings.json` 中設定 [`teammateMode`](/docs/zh-TW/settings-reference#teammatemode)：123若要覆蓋預設值，請在 `~/.claude/settings.json` 中設定 [`teammateMode`](/docs/zh-TW/settings-reference#teammatemode)：

124 124

agent-view.md +2 −2

Details

724| :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |724| :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |

726| [`--add-dir <path>`](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | 授予對額外目錄的檔案存取權限 |726| [`--add-dir <path>`](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | 授予對額外目錄的檔案存取權限 |

729| `--strict-mcp-config` | 僅使用來自 `--mcp-config` 的 MCP servers，忽略其他 MCP 配置。請參閱[使用 managed-mcp.json 的獨佔控制](/docs/zh-TW/managed-mcp#exclusive-control-with-managed-mcp-json)以了解該標誌在受管 MCP 檔案下做什麼 |729| `--strict-mcp-config` | 僅使用來自 `--mcp-config` 的 MCP servers，忽略其他 MCP 配置。請參閱[使用 managed-mcp.json 的獨佔控制](/docs/zh-TW/managed-mcp#exclusive-control-with-managed-mcp-json)以了解該標誌在受管 MCP 檔案下做什麼 |

730 730

1062| v2.1.257 | 在開啟的背景工作階段內使用 `Ctrl+S` 隱藏的提示[與工作階段一起保留](#what-persists-across-restarts)，所以 `Ctrl+S` 在工作階段的程序停止並再次啟動後恢復它。在此版本之前，隱藏只存在於執行中的程序中，當工作階段閒置足夠長的時間以至於其程序停止時，或當它停止然後重新開啟時會遺失。 |1062| v2.1.257 | 在開啟的背景工作階段內使用 `Ctrl+S` 隱藏的提示[與工作階段一起保留](#what-persists-across-restarts)，所以 `Ctrl+S` 在工作階段的程序停止並再次啟動後恢復它。在此版本之前，隱藏只存在於執行中的程序中，當工作階段閒置足夠長的時間以至於其程序停止時，或當它停止然後重新開啟時會遺失。 |

1063| v2.1.251 | 在尚未[移入 worktree](#how-file-edits-are-isolated) 的背景工作階段中，Claude 和它生成的子代理可以編輯連結 git worktree 內的檔案。 |1063| v2.1.251 | 在尚未[移入 worktree](#how-file-edits-are-isolated) 的背景工作階段中，Claude 和它生成的子代理可以編輯連結 git worktree 內的檔案。 |

1064| v2.1.251 | Claude Code 轉發在您分派的 shell 中匯出的雲端提供者閘道，例如 `ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 及其驗證繞過旗標，到[工作階段的工作程序](#llm-gateway)，條件與 `ANTHROPIC_BASE_URL` 相同。在此版本之前，如果您只透過這樣的閘道背景化或分派，工作階段進行的每個請求都失敗，因為端點和旗標從其環境中被丟棄。 |1064| v2.1.251 | Claude Code 轉發在您分派的 shell 中匯出的雲端提供者閘道，例如 `ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 及其驗證繞過旗標，到[工作階段的工作程序](#llm-gateway)，條件與 `ANTHROPIC_BASE_URL` 相同。在此版本之前，如果您只透過這樣的閘道背景化或分派，工作階段進行的每個請求都失敗，因為端點和旗標從其環境中被丟棄。 |

1065| v2.1.251 | 當背景工作階段在另一個 Claude Code 程序重新整理[外掛程式市場](/docs/zh-TW/plugin-marketplaces)時啟動，例如執行[市場自動更新](/docs/zh-TW/discover-plugins#configure-auto-updates)的同級工作階段，Claude Code 保持該市場的外掛程式可用。在此版本之前，這樣的工作階段可能在沒有該市場的任何技能、代理、hooks 和 MCP 伺服器的情況下啟動，並在其整個執行期間保持這樣。 |1065| v2.1.251 | 當背景工作階段在另一個 Claude Code 程序重新整理[外掛程式市場](/docs/zh-TW/plugins/overview)時啟動，例如執行[市場自動更新](/docs/zh-TW/plugins/install#keep-plugins-updated)的同級工作階段，Claude Code 保持該市場的外掛程式可用。在此版本之前，這樣的工作階段可能在沒有該市場的任何技能、代理、hooks 和 MCP 伺服器的情況下啟動，並在其整個執行期間保持這樣。 |

1066| v2.1.248 | [分派輸入](#keyboard-shortcuts)中的 `Shift+Enter` 插入換行符，符合主提示，`Ctrl+Enter` 在 `?` 覆蓋層列出 `ctrl+enter to start and open` 的終端中立即分派並附加。在此版本之前，`Shift+Enter` 分派並附加。 |1066| v2.1.248 | [分派輸入](#keyboard-shortcuts)中的 `Shift+Enter` 插入換行符，符合主提示，`Ctrl+Enter` 在 `?` 覆蓋層列出 `ctrl+enter to start and open` 的終端中立即分派並附加。在此版本之前，`Shift+Enter` 分派並附加。 |

1067| v2.1.248 | [刪除工作階段](#what-deleting-a-session-removes)在 worktree 的提交已在您的 `origin` 遠端預設分支的本機副本上且您的主簽出已簽出該分支時成功；在此版本之前，刪除被拒絕，出現 `has commits that are not pushed anywhere`。 |1067| v2.1.248 | [刪除工作階段](#what-deleting-a-session-removes)在 worktree 的提交已在您的 `origin` 遠端預設分支的本機副本上且您的主簽出已簽出該分支時成功；在此版本之前，刪除被拒絕，出現 `has commits that are not pushed anywhere`。 |

1068| v2.1.248 | 使用 `←` 或 `/background` 背景化的工作階段在執行時持有其 worktree 上的 [`git worktree lock`](/docs/zh-TW/worktrees#clean-up-subagent-and-background-session-worktrees)；在此版本之前，背景化釋放鎖定，清理或 `git worktree remove` 可以在執行中的工作階段下移除 worktree。 |1068| v2.1.248 | 使用 `←` 或 `/background` 背景化的工作階段在執行時持有其 worktree 上的 [`git worktree lock`](/docs/zh-TW/worktrees#clean-up-subagent-and-background-session-worktrees)；在此版本之前，背景化釋放鎖定，清理或 `git worktree remove` 可以在執行中的工作階段下移除 worktree。 |

agents.md +1 −1

Details

22 22

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

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

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

26 26

27還有一些其他功能在您不驅動每個步驟的情況下執行 Claude，但它們解決的問題與跨代理分割工作不同：27還有一些其他功能在您不驅動每個步驟的情況下執行 Claude，但它們解決的問題與跨代理分割工作不同：

28 28

amazon-bedrock.md +7 −2

Details

518 使用 Mantle 端點518 使用 Mantle 端點

519</h2>519</h2>

520 520

521Mantle 是一個 Amazon Bedrock 端點，透過原生 Anthropic API 形狀而不是 Amazon Bedrock Invoke API 提供 Claude 模型。它使用相同的 [AWS 認證](#2-configure-aws-credentials)、[IAM 權限](#iam-configuration) 和 [`awsAuthRefresh` 設定](#advanced-credential-configuration)。521Mantle 是一個 Amazon Bedrock 端點，透過原生 Anthropic API 形狀而不是 Amazon Bedrock Invoke API 提供 Claude 模型。它使用相同的 [AWS 認證](#2-configure-aws-credentials) 和 [`awsAuthRefresh` 設定](#advanced-credential-configuration)。

522

523Mantle 在 `bedrock-mantle:` 前綴下有其自己的 IAM 動作，因此 [IAM 設定](#iam-configuration) 中的 `bedrock:` 動作不涵蓋它。為推論授予您的 IAM 身分 `bedrock-mantle:CreateInference`，為權杖計數授予 `bedrock-mantle:CountTokens`。請參閱 AWS 文件中的[進行推論請求](https://docs.aws.amazon.com/bedrock/latest/userguide/inference.html)和[計數權杖](https://docs.aws.amazon.com/bedrock/latest/userguide/count-tokens.html)，以及[服務授權參考](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrockpoweredbyawsmantle.html)以了解每個 Mantle 動作。

522 524

523<h3 id="enable-mantle">525<h3 id="enable-mantle">

524 啟用 Mantle526 啟用 Mantle

670 672

671如果在設定 `CLAUDE_CODE_USE_MANTLE` 後 `/status` 未顯示 `Amazon Bedrock (Mantle)`，則該變數未到達程序。確認它已在您啟動 `claude` 的 shell 中匯出，或在[設定檔](/docs/zh-TW/settings)的 `env` 區塊中設定它。673如果在設定 `CLAUDE_CODE_USE_MANTLE` 後 `/status` 未顯示 `Amazon Bedrock (Mantle)`，則該變數未到達程序。確認它已在您啟動 `claude` 的 shell 中匯出，或在[設定檔](/docs/zh-TW/settings)的 `env` 區塊中設定它。

672 674

673來自 Mantle 端點的 `403`（具有有效認證）表示您的 AWS 帳戶尚未被授予存取您要求的模型的權限。請聯絡您的 AWS 帳戶團隊以要求存取。675來自 Mantle 端點的 `403` 的含義取決於錯誤是否命名 IAM 動作：

676

677* 如果錯誤命名 `bedrock-mantle:` 動作，請授予您的 IAM 身分該動作。

678* 如果錯誤未命名任何動作且您的認證有效，您的 AWS 帳戶尚未被授予存取您要求的模型的權限。請聯絡您的 AWS 帳戶團隊以要求存取。

674 679

675命名模型 ID 的 `400` 表示該模型未在 Mantle 上提供。Mantle 有其自己的模型陣容，與標準 Amazon Bedrock 目錄分開，因此推論設定檔 ID（例如 `us.anthropic.claude-sonnet-4-6`）將無法運作。使用 Mantle 格式的 ID，或啟用[兩個端點](#run-mantle-alongside-the-invoke-api)，以便 Claude Code 將每個請求路由到模型可用的端點。680命名模型 ID 的 `400` 表示該模型未在 Mantle 上提供。Mantle 有其自己的模型陣容，與標準 Amazon Bedrock 目錄分開，因此推論設定檔 ID（例如 `us.anthropic.claude-sonnet-4-6`）將無法運作。使用 Mantle 格式的 ID，或啟用[兩個端點](#run-mantle-alongside-the-invoke-api)，以便 Claude Code 將每個請求路由到模型可用的端點。

676 681

best-practices.md +2 −2

Details

334 執行 `/plugin` 以瀏覽市場。外掛程式無需設定即可添加技能、工具和整合。334 執行 `/plugin` 以瀏覽市場。外掛程式無需設定即可添加技能、工具和整合。

335</Tip>335</Tip>

336 336

337[外掛程式](/docs/zh-TW/plugins)將技能、hooks、子代理和 MCP 伺服器從社群和 Anthropic 捆綁到單個可安裝單位中。如果你使用型別語言，請安裝[程式碼智慧外掛程式](/docs/zh-TW/discover-plugins#code-intelligence)，以提供 Claude 精確的符號導航和編輯後的自動錯誤偵測。337[外掛程式](/docs/zh-TW/plugins/overview)將技能、hooks、子代理和 MCP 伺服器從社群和 Anthropic 捆綁到單個可安裝單位中。如果你使用型別語言，請安裝[程式碼智慧外掛程式](/docs/zh-TW/plugins/code-intelligence)，以提供 Claude 精確的符號導航和編輯後的自動錯誤偵測。

338 338

339如需有關在技能、子代理、hooks 和 MCP 之間選擇的指導，請參閱[擴充 Claude Code](/docs/zh-TW/features-overview#match-features-to-your-goal)。339如需有關在技能、子代理、hooks 和 MCP 之間選擇的指導，請參閱[擴充 Claude Code](/docs/zh-TW/features-overview#match-features-to-your-goal)。

340 340

541 循環遍歷任務，為每個任務調用 `claude -p`。使用 `--allowedTools` 為批量操作限定權限。541 循環遍歷任務，為每個任務調用 `claude -p`。使用 `--allowedTools` 為批量操作限定權限。

542</Tip>542</Tip>

543 543

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

545 545

546<Steps>546<Steps>

547 <Step title="生成任務列表">547 <Step title="生成任務列表">

channels.md +6 −6

Details

45 如果安裝失敗，請符合 Claude Code 報告的訊息：45 如果安裝失敗，請符合 Claude Code 報告的訊息：

46 46

47 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。47 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。

~~48 * 外掛程式[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。~~48 * 外掛程式[在市場中找不到](/docs/zh-TW/plugins/install#install-a-plugin)：檢查外掛程式名稱。

49 49

50 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。檢查安裝摘要：如果報告 `Run /reload-plugins to activate.`，請參閱[在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)以使外掛程式的設定命令可用。50 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。檢查安裝摘要：如果報告 `Run /reload-plugins to activate.`，請參閱[在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/plugins/cli-reference#reload-plugins)以使外掛程式的設定命令可用。

51 </Step>51 </Step>

52 52

53 <Step title="設定您的權杖">53 <Step title="設定您的權杖">

123 如果安裝失敗，請符合 Claude Code 報告的訊息：123 如果安裝失敗，請符合 Claude Code 報告的訊息：

124 124

125 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。125 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。

126 * 外掛程式[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。126 * 外掛程式[在市場中找不到](/docs/zh-TW/plugins/install#install-a-plugin)：檢查外掛程式名稱。

127 127

128 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。檢查安裝摘要：如果報告 `Run /reload-plugins to activate.`，請參閱[在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)以使外掛程式的設定命令可用。128 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。檢查安裝摘要：如果報告 `Run /reload-plugins to activate.`，請參閱[在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/plugins/cli-reference#reload-plugins)以使外掛程式的設定命令可用。

129 </Step>129 </Step>

130 130

131 <Step title="設定您的權杖">131 <Step title="設定您的權杖">

188 如果安裝失敗，請符合 Claude Code 報告的訊息：188 如果安裝失敗，請符合 Claude Code 報告的訊息：

189 189

190 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。190 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。

191 * 外掛程式[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。191 * 外掛程式[在市場中找不到](/docs/zh-TW/plugins/install#install-a-plugin)：檢查外掛程式名稱。

192 192

193 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。如果安裝摘要報告 `Run /reload-plugins to activate.`，您可以在此跳過，因為下一步中的重新啟動會選取外掛程式。193 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。如果安裝摘要報告 `Run /reload-plugins to activate.`，您可以在此跳過，因為下一步中的重新啟動會選取外掛程式。

194 </Step>194 </Step>

245 如果安裝失敗，請符合 Claude Code 報告的訊息：245 如果安裝失敗，請符合 Claude Code 報告的訊息：

246 246

247 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。247 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。

248 * 外掛程式[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。248 * 外掛程式[在市場中找不到](/docs/zh-TW/plugins/install#install-a-plugin)：檢查外掛程式名稱。

249 249

250 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。如果安裝摘要報告 `Run /reload-plugins to activate.`，您可以在此跳過，因為下一步中的重新啟動會選取外掛程式。250 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。如果安裝摘要報告 `Run /reload-plugins to activate.`，您可以在此跳過，因為下一步中的重新啟動會選取外掛程式。

251 </Step>251 </Step>

channels-reference.md +4 −4

Details

191claude --dangerously-load-development-channels server:webhook191claude --dangerously-load-development-channels server:webhook

192```192```

193 193

194繞過是按項目進行的。將此旗標與 `--channels` 結合不會將繞過擴展到 `--channels` 項目。在研究預覽期間，核准允許清單由 Anthropic 策劃，因此您的 channel 在您建立和測試時保持在開發旗標上。194繞過是按項目進行的。將此旗標與 `--channels` 結合不會將繞過擴展到 `--channels` 項目。在研究預覽期間，您的 channel 不在核准允許清單上，因此在您建立和測試時保持在開發旗標上。

195 195

196<Note>196<Note>

197 此旗標僅跳過允許清單。`channelsEnabled` 組織政策仍然適用。不要使用它來執行來自不受信任來源的 channels。197 此旗標僅跳過允許清單。`channelsEnabled` 組織政策仍然適用。不要使用它來執行來自不受信任來源的 channels。

801 打包為外掛程式801 打包為外掛程式

802</h2>802</h2>

803 803

804若要使您的 channel 可安裝和可共享，請將其包裝在[外掛程式](/docs/zh-TW/plugins)中並將其發佈到[市場](/docs/zh-TW/plugin-marketplaces)。使用者使用 `/plugin install` 安裝它，然後使用 `--channels plugin:<name>@<marketplace>` 按工作階段啟用它。804若要使您的 channel 可安裝和可共享，請將其包裝在[外掛程式](/docs/zh-TW/plugins/overview)中並將其發佈到[市場](/docs/zh-TW/plugins/overview)。使用者使用 `/plugin install` 安裝它，然後使用 `--channels plugin:<name>@<marketplace>` 按工作階段啟用它。

805 805

806發佈到您自己的市場的 channel 仍然需要 `--dangerously-load-development-channels` 才能執行，因為它不在[核准允許清單](/docs/zh-TW/channels#supported-channels)上。預設允許清單是 `claude-plugins-official` 中的 channel 外掛程式，Anthropic 自行策劃。[應用內提交表單](/docs/zh-TW/plugins#submit-your-plugin-to-the-community-marketplace)將外掛程式新增到社群市場，該市場不在 channel 允許清單上。806發佈到您自己的市場的 channel 仍然需要 `--dangerously-load-development-channels` 才能執行，因為它不在[核准允許清單](/docs/zh-TW/channels#supported-channels)上。預設允許清單是 `claude-plugins-official` 中的 channel 外掛程式。[應用內提交表單](/docs/zh-TW/plugins/publish#submit-to-the-community-marketplace)將外掛程式新增到社群市場，該市場不在 channel 允許清單上。

807 807

808如果您正在與 Anthropic 合作夥伴聯絡，請與他們聯繫以協調官方市場列表。在 Team 和 Enterprise 計劃上，管理員可以改為將您的外掛程式包含在組織自己的 [`allowedChannelPlugins`](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run) 清單中，該清單取代預設 Anthropic 允許清單。808如果您正在與 Anthropic 合作夥伴聯絡，請與他們聯繫以協調官方市場列表。在 Team 和 Enterprise 計劃上，管理員可以改為將您的外掛程式包含在組織自己的 [`allowedChannelPlugins`](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run) 清單中，該清單取代預設 Anthropic 允許清單。

809 809

814* [Channels](/docs/zh-TW/channels) 安裝並使用 Telegram、Discord、iMessage 或 fakechat 演示，以及為 Team 或 Enterprise 組織啟用 channels814* [Channels](/docs/zh-TW/channels) 安裝並使用 Telegram、Discord、iMessage 或 fakechat 演示，以及為 Team 或 Enterprise 組織啟用 channels

815* [工作 channel 實現](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins)以取得具有配對流程、回覆工具和檔案附件的完整伺服器程式碼815* [工作 channel 實現](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins)以取得具有配對流程、回覆工具和檔案附件的完整伺服器程式碼

816* [MCP](/docs/zh-TW/mcp) 用於 channel 伺服器實現的基礎協議816* [MCP](/docs/zh-TW/mcp) 用於 channel 伺服器實現的基礎協議

817* [外掛程式](/docs/zh-TW/plugins) 打包您的 channel，以便使用者可以使用 `/plugin install` 安裝它817* [外掛程式](/docs/zh-TW/plugins/overview) 打包您的 channel，以便使用者可以使用 `/plugin install` 安裝它

checkpointing.md +1 −1

Details

54 回溯過去已清除的對話54 回溯過去已清除的對話

55</h4>55</h4>

56 56

57如果您在同一個 Claude Code 程序中較早執行了 `/clear`，回溯選單會在清單頂部顯示一個額外的項目，標記為 `/resume <session-id> (previous session)`。選擇它以恢復在 `/clear` 執行前活躍的對話。該項目在您退出 Claude Code 或恢復不同會話之前可用，並且需要 Claude Code v2.1.191 或更新版本。在較早的版本上，執行 `/resume` 並從清單中選擇前一個會話。57如果您在同一個 Claude Code 程序中較早執行了 `/clear`，回溯選單會在清單頂部顯示一個額外的項目，標記為 `/resume <session-id> (previous session)`。選擇它以恢復在 `/clear` 執行前活躍的對話。該項目在您退出 Claude Code 或恢復不同會話之前可用。

58 58

59<h4 id="guide-a-summary">59<h4 id="guide-a-summary">

60 引導摘要60 引導摘要

claude-apps-gateway.md +3 −1

Details

448 鎖定不涵蓋的設定448 鎖定不涵蓋的設定

449</h4>449</h4>

450 450

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

452 452

453* **`forceLoginOrgUUID`**：當最高優先級管理員來源未設定組織 UUID 時，Claude Code 會接受父提供的值。閘道登入不檢查此金鑰，因此它僅對也使用第一方 Anthropic 登入的機隊重要。最高優先級管理員來源中的組織 UUID 會阻止父項的值，是 Claude Code 強制執行的值，因此在那裡設定 `forceLoginOrgUUID`。453* **`forceLoginOrgUUID`**：當最高優先級管理員來源未設定組織 UUID 時，Claude Code 會接受父提供的值。閘道登入不檢查此金鑰，因此它僅對也使用第一方 Anthropic 登入的機隊重要。最高優先級管理員來源中的組織 UUID 會阻止父項的值，是 Claude Code 強制執行的值，因此在那裡設定 `forceLoginOrgUUID`。

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

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

456* **`strictKnownMarketplaces`**：當獲勝的受管來源未設定外掛程式市集允許清單時，Claude Code 會接受父提供的外掛程式市集允許清單。如果您的機隊限制市集，在獲勝的來源中設定 `strictKnownMarketplaces`。需要 Claude Code v2.1.282 或更新版本。

457* **`blockedMarketplaces`**：父提供的市集封鎖清單通過並新增至任何受管來源設定的封鎖清單，因為封鎖清單只能進一步限制。需要 Claude Code v2.1.282 或更新版本。

456* **`strictPluginOnlyCustomization`**：此金鑰無論任何鎖定都通過篩選器，它使 Claude Code 忽略開發人員自己的自訂，包括保護性 hooks。沒有鎖定阻止它。458* **`strictPluginOnlyCustomization`**：此金鑰無論任何鎖定都通過篩選器，它使 Claude Code 忽略開發人員自己的自訂，包括保護性 hooks。沒有鎖定阻止它。

457 459

458<h3 id="connect-claude-desktop">460<h3 id="connect-claude-desktop">

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

Details

35* [`managed`](#managed)：按 IdP 群組的受管設定原則35* [`managed`](#managed)：按 IdP 群組的受管設定原則

36* [`telemetry`](#telemetry)：OTLP 轉發到您的可觀測性堆疊36* [`telemetry`](#telemetry)：OTLP 轉發到您的可觀測性堆疊

37* [`access_control`、`limits`、`timeouts`、`rate_limits`](#http-tuning)：IP 允許/拒絕、請求大小上限、上游首位元組時間，以及每個 IP 的登入限制37* [`access_control`、`limits`、`timeouts`、`rate_limits`](#http-tuning)：IP 允許/拒絕、請求大小上限、上游首位元組時間，以及每個 IP 的登入限制

38* [`load_test_mode`](#load_test_mode)：在不呼叫模型提供者的情況下對閘道器進行負載測試

38 39

39<h2 id="secret-expansion">40<h2 id="secret-expansion">

40 祕密擴展41 祕密擴展

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

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

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

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

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

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

98 99

104 105

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

106 107

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

109

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

111 Proxy-only egress

112</h4>

113

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

115

116```bash theme={null}

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

118export NO_PROXY=

119export no_proxy=

120export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

121```

122

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

124

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

126

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

128| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------- |

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

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

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

132

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

134

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

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

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

138

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

140

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

142

143<Warning>

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

145</Warning>

146

107<h3 id="session">147<h3 id="session">

108 `session`148 `session`

109</h3>149</h3>

122`store` 區塊將閘道指向其 PostgreSQL 資料庫，該資料庫保存裝置授權和速率限制計數器。162`store` 區塊將閘道指向其 PostgreSQL 資料庫，該資料庫保存裝置授權和速率限制計數器。

123 163

124| 欄位 | 必需 | 說明 |164| 欄位 | 必需 | 說明 |

125| ----------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |165| ------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

127| `username` | 否 | 覆蓋 `postgres_url` 中的使用者 |167| `username` | 否 | 覆蓋 `postgres_url` 中的使用者 |

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

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

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

130 171

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

132 173

364| 其他任何地方 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`。在 `{ }` 內引用 `${…}`。 |405| 其他任何地方 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`。在 `{ }` 內引用 `${…}`。 |

365 406

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

408 上游請求上的靜態標頭

409</h4>

410

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

412

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

414

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

416

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

418

419```yaml theme={null}

420upstreams:

421 - provider: vertex

422 region: us-east5

423 project_id: example-prod

424 base_url: https://upstream-proxy.internal.example.com

425 auth: {}

426 headers:

427 x-source: claude-apps-gateway

428 x-proxy-token: ${PROXY_TOKEN}

429```

430

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

432

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

434

435`headers:` 適用於每個提供者，每個上游僅傳送自己的。

436

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

438

439| 閘道傳送到此上游的請求 | 攜帶 `headers:` |

440| ---------------------------------------------------- | ------------------ |

441| `/v1/messages`、串流或不串流，以及 `/v1/messages/count_tokens` | 是 |

442| 從另一個上游故障轉移的請求 | 是，僅此上游的 `headers:` |

443| Amazon Bedrock 的 `CountTokens` 呼叫用於用戶端放棄的請求 | 否 |

444| Workload Identity Federation 令牌交換 | 否 |

445

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

447

448如果您使用閘道保留的名稱，它拒絕啟動，啟動錯誤命名標頭。保留名稱包括：

449

450* `authorization` 和 `x-api-key`

451* `host`、`content-type` 和 `user-agent`

452* 任何以 `anthropic-`、`x-goog-`、`x-amz-` 或 `x-amzn-` 開頭的名稱

453

366<h4 id="multiple-upstreams">454<h4 id="multiple-upstreams">

367 多個上游455 多個上游

368</h4>456</h4>

373 461

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

375 463

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

465

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

467

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

469

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

377 471

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

795 889

796[Claude Desktop](#claude-desktop-overlay) 和透過 gateway 登入的 Cowork 工作階段使用 `user.email` 和 `user.groups` 以及 `enduser.id` 為其遙測加上時間戳，因此您可以使用一個 `user.email` 或 `user.groups` 查詢涵蓋終端、Desktop 和 Cowork 使用。`user.groups` 是逗號分隔的 IdP 群組清單。890[Claude Desktop](#claude-desktop-overlay) 和透過 gateway 登入的 Cowork 工作階段使用 `user.email` 和 `user.groups` 以及 `enduser.id` 為其遙測加上時間戳，因此您可以使用一個 `user.email` 或 `user.groups` 查詢涵蓋終端、Desktop 和 Cowork 使用。`user.groups` 是逗號分隔的 IdP 群組清單。

797 891

892Desktop 和 Cowork 遙測也帶有 `enduser.sub`，您的身分提供者為使用者簽發的 `sub` 宣告，當使用者的電子郵件變更時保持相同。終端工作階段在 `user.id` 下加上相同值，因此匹配 `enduser.sub` 對終端 `user.id` 的查詢涵蓋一位使用者的終端、Desktop 和 Cowork 使用。在 Desktop 和 Cowork 匯出上，`user.id` 是匿名識別碼，不是主體。

893

798與來自 Claude Code 的所有 OpenTelemetry 資料一樣，這些屬性只進入您的組織設定的目的地，永遠不進入 Anthropic。894與來自 Claude Code 的所有 OpenTelemetry 資料一樣，這些屬性只進入您的組織設定的目的地，永遠不進入 Anthropic。

799 895

800如果使用者的群組清單在百分比編碼後超過 255 個字元，或群組名稱包含逗號或等號，gateway 會從該使用者的 Desktop 和 Cowork 遙測中省略 `user.groups`，而不是截斷它。該使用者的終端工作階段仍帶有完整清單。896如果使用者的群組清單在百分比編碼後超過 255 個字元，或群組名稱包含逗號或等號，gateway 會從該使用者的 Desktop 和 Cowork 遙測中省略 `user.groups`，而不是截斷它。該使用者的終端工作階段仍帶有完整清單。

801 897

898當主體在百分比編碼後超過 255 個字元，或包含空格、可列印 ASCII 外的字元，或 `,` `;` `=` `\` `"` `%` 之一時，gateway 會省略 `enduser.sub`。該使用者的 Desktop 和 Cowork 遙測保留其他屬性。

899

802您需要 gateway 伺服器上的 Claude Code v2.1.265 或更新版本，以在 Desktop 和 Cowork 遙測上使用 `user.email` 和 `user.groups`，以及每位開發者機器上的 Claude Desktop 1.24012 或更新版本，以使用 `user.groups`。900您需要 gateway 伺服器上的 Claude Code v2.1.265 或更新版本，以在 Desktop 和 Cowork 遙測上使用 `user.email` 和 `user.groups`，以及每位開發者機器上的 Claude Desktop 1.24012 或更新版本，以使用 `user.groups`。

803 901

902您需要 gateway 伺服器上的 Claude Code v2.1.274 或更新版本，以使用 `enduser.sub`。

903

804```yaml theme={null}904```yaml theme={null}

805telemetry:905telemetry:

806 forward_to:906 forward_to:

832 932

833對於叢集內收集器，在其自己的內部位址上公開 HTTPS，或以設定變數的方式將其作為邊車執行。933對於叢集內收集器，在其自己的內部位址上公開 HTTPS，或以設定變數的方式將其作為邊車執行。

834 934

935當 `HTTPS_PROXY` 被設定時，gateway 透過該代理傳送匯出。

936

937要直接到達內部收集器，透過主機名稱或具有前導點的網域（例如 `.internal.example.com`）將其新增到 `NO_PROXY`，這需要 gateway 伺服器上的 Claude Code v2.1.277 或更新版本。確保 gateway 可以在沒有代理的情況下到達收集器。沒有前導點的項目只匹配該確切名稱，不匹配其下的名稱。CIDR 範圍不匹配。

938

939啟用[僅代理出口](#proxy-only-egress)時，改為在代理中允許收集器，因為任何 `NO_PROXY` 項目會關閉僅代理出口。

940

835遙測在 CLI 中預設關閉。當您同時設定 `telemetry.forward_to` 和 `listen.public_url` 時，gateway 透過 `/managed/settings` 推送六個環境變數來為連接的用戶端開啟它：941遙測在 CLI 中預設關閉。當您同時設定 `telemetry.forward_to` 和 `listen.public_url` 時，gateway 透過 `/managed/settings` 推送六個環境變數來為連接的用戶端開啟它：

836 942

837* `CLAUDE_CODE_ENABLE_TELEMETRY=1`943* `CLAUDE_CODE_ENABLE_TELEMETRY=1`

909| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未驗證裝置授權端點上的每 IP 速率限制。為共享出口 IP 或 NAT 後面的大型組織提高。這些限制僅適用於裝置授予登入流程，不適用於 `/v1/messages` 推論。請參閱[使用者代碼暴力破解抵抗](/docs/zh-TW/claude-apps-gateway-deploy#user-code-brute-force-resistance)。 |1015| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未驗證裝置授權端點上的每 IP 速率限制。為共享出口 IP 或 NAT 後面的大型組織提高。[大型推出](/docs/zh-TW/claude-apps-gateway-deploy#large-rollouts)顯示如何調整大小。這些限制僅適用於裝置授予登入流程，不適用於 `/v1/messages` 推論。請參閱[使用者代碼暴力破解抵抗](/docs/zh-TW/claude-apps-gateway-deploy#user-code-brute-force-resistance)。 |

911 1017

912如果您將兩個 `access_control` 清單都留空（這是預設值），gateway 為任何用戶端位址提供服務，因此只有您的網路限制誰可以到達它。這很重要，因為 gateway 可以推送[受管設定](#managed)，在開發者機器上執行命令。1018如果您將兩個 `access_control` 清單都留空（這是預設值），gateway 為任何用戶端位址提供服務，因此只有您的網路限制誰可以到達它。這很重要，因為 gateway 可以推送[受管設定](#managed)，在開發者機器上執行命令。

913 1019

920 1026

921在這樣的前端後面，首先設定 [`listen.trusted_proxies`](#listen)，以便 gateway 看到真實用戶端位址，並無論如何保持 gateway 和其前面的所有東西無法從公開網際網路到達。1027在這樣的前端後面，首先設定 [`listen.trusted_proxies`](#listen)，以便 gateway 看到真實用戶端位址，並無論如何保持 gateway 和其前面的所有東西無法從公開網際網路到達。

922 1028

1029<h3 id="load_test_mode">

1030 `load_test_mode`

1031</h3>

1032

1033`load_test_mode` 區塊讓您負載測試 gateway，而不呼叫模型提供者。啟用時，gateway 建立和簽署每個提供者請求如常，丟棄它而不是傳送它，並透過其正常回應路徑流式傳輸罐裝回覆。回覆是填充文字，開始於說它是罐裝的句子。

1034

1035需要 v2.1.283 或更新版本。較早版本在設定金鑰時拒絕啟動，因此在新增區塊之前升級每個複本，並在回滾之前移除它。

1036

1037下面的範例以預設值開啟模式，回覆為 750 個輸出 token，在大約 10 秒內流式傳輸：

1038

1039```yaml theme={null}

1040load_test_mode:

1041 enabled: true

1042 reply_tokens: 750 # roughly how many tokens of text each canned reply carries

1043 reply_seconds: 9.5 # how long a streamed reply takes

1044```

1045

1046| 欄位 | 必要 | 說明 |

1047| --------------- | -- | ------------------------------------------------------------ |

1048| `enabled` | 是 | `true` 開啟模式。`false` 保留您的數字在檔案中，模式關閉。如果區塊存在而沒有它，gateway 拒絕啟動。 |

1049| `reply_tokens` | 否 | 預設 `750`。大約每個罐裝回覆帶有多少個文字 token，從 1 到 100000 的整數。 |

1050| `reply_seconds` | 否 | 預設 `9.5`。流式回覆需要多長時間，從 0 到 600。`0` 一次傳送整個回覆。對非流式請求的回覆總是一次回來。 |

1051

1052此模式中的負載測試涵蓋 gateway、您的 Postgres 和 gateway 前面的所有東西。它不涵蓋提供者的限制、速度或網路路徑。

1053

1054啟用模式時，請求可以帶有 `x-load-test-user` 標頭，保存最多七位數的整數，gateway 將每個數字計為具有請求附帶的令牌的開發者的電子郵件和群組的單獨開發者。為負載測試部署提供自己的空資料庫，因為如果任何開發者已經花費任何東西，gateway 拒絕以模式啟動。

1055

1056<Warning>

1057 永遠不要為開發者使用的 gateway 開啟此。每個請求獲得罐裝回覆，沒有模型被呼叫。gateway 在啟動時記錄 `load_test_mode is on` 警告，並在模式啟用時使用 `load_test: true` 標記每個 `inference` [稽核事件](/docs/zh-TW/claude-apps-gateway-deploy#logs)。

1058</Warning>

1059

923<h2 id="complete-example">1060<h2 id="complete-example">

924 完整範例1061 完整範例

925</h2>1062</h2>

971store:1108store:

972 postgres_url: ${GATEWAY_POSTGRES_URL}1109 postgres_url: ${GATEWAY_POSTGRES_URL}

973 # max_connections: 51110 # max_connections: 5

1111 # connect_timeout_seconds: 5

974 1112

975# 啟用 /v1/organizations/spend_limits（鏡像 Anthropic Admin API）1113# 啟用 /v1/organizations/spend_limits（鏡像 Anthropic Admin API）

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

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

Details

219* **[支出限制強制執行](/docs/zh-TW/claude-apps-gateway-spend-limits#postgres-availability)**：在中斷期間預設失敗開啟，因此推論仍流動；如果您寧願阻止而不是無計量執行，請將其翻轉為失敗關閉219* **[支出限制強制執行](/docs/zh-TW/claude-apps-gateway-spend-limits#postgres-availability)**：在中斷期間預設失敗開啟，因此推論仍流動；如果您寧願阻止而不是無計量執行，請將其翻轉為失敗關閉

220* **就緒性**：`/readyz` 在中斷期間報告未就緒，因此在就緒性上閘道流量的協調器立即從輪換中移除每個複本。在該拓撲中，所有流量（包括閘道仍可提供的推論）在負載平衡器處失敗，直到 Postgres 恢復。`/healthz` 上的活躍性探測保持通過，因此複本不被重新啟動。如果您寧願已登入的開發人員在存放區中斷期間繼續工作，請將就緒性探測指向 `/healthz`；代價是新登入對仍報告就緒的複本失敗。220* **就緒性**：`/readyz` 在中斷期間報告未就緒，因此在就緒性上閘道流量的協調器立即從輪換中移除每個複本。在該拓撲中，所有流量（包括閘道仍可提供的推論）在負載平衡器處失敗，直到 Postgres 恢復。`/healthz` 上的活躍性探測保持通過，因此複本不被重新啟動。如果您寧願已登入的開發人員在存放區中斷期間繼續工作，請將就緒性探測指向 `/healthz`；代價是新登入對仍報告就緒的複本失敗。

221 221

222如果您的 IdP 宕機，現有工作階段工作直到 `ttl_hours`，新登入和重新整理失敗。如果您的 IdP 有頻繁的維護視窗，請設定更長的 `ttl_hours`。222如果您的 IdP 宕機，現有工作階段工作直到 `ttl_hours`，新登入失敗，工作階段重新整理獲得重試答案並在 IdP 恢復後進行一次。如果您的 IdP 有頻繁的維護視窗，請設定更長的 `ttl_hours`。

223 223

224<h3 id="jwt-secret-rotation">224<h3 id="jwt-secret-rotation">

225 JWT 密鑰輪換225 JWT 密鑰輪換

claude-code-on-the-web.md +2 −2

Details

218傳送在恢復工作階段之前檢查這些要求。如果任何要求未滿足，您會看到錯誤或被提示解決問題。218傳送在恢復工作階段之前檢查這些要求。如果任何要求未滿足，您會看到錯誤或被提示解決問題。

219 219

220| 要求 | 詳細資訊 |220| 要求 | 詳細資訊 |

221| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |221| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

224| 分支可用 | 雲端工作階段中的分支必須已推送到遠端。傳送會自動取得並簽出它。 |224| 分支可用 | 雲端工作階段中的分支必須已推送到遠端。傳送會自動取得並簽出它。 |

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

226 226

claude-directory.md +6 −6

Details

1451探索器涵蓋您編寫和編輯的檔案。一些相關檔案位於其他位置：1451探索器涵蓋您編寫和編輯的檔案。一些相關檔案位於其他位置：

1452 1452

1453| 檔案 | 位置 | 用途 |1453| 檔案 | 位置 | 用途 |

1454| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1454| ----------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

1459 1459

1460`~/.claude` 也保存 Claude Code 在您工作時寫入的資料：文字記錄、提示歷史記錄、檔案快照、快取和日誌。請參閱下方的[應用程式資料](#application-data)。1460`~/.claude` 也保存 Claude Code 在您工作時寫入的資料：文字記錄、提示歷史記錄、檔案快照、快取和日誌。請參閱下方的[應用程式資料](#application-data)。

1461 1461

1529| `output-styles/*.md` | `name`, `description`, `keep-coding-instructions`, `force-for-plugin` | [Output style frontmatter](/docs/zh-TW/output-styles#frontmatter) |1529| `output-styles/*.md` | `name`, `description`, `keep-coding-instructions`, `force-for-plugin` | [Output style frontmatter](/docs/zh-TW/output-styles#frontmatter) |

1530| `rules/*.md` | `paths` | [Rule frontmatter](/docs/zh-TW/memory#rules-frontmatter-reference) |1530| `rules/*.md` | `paths` | [Rule frontmatter](/docs/zh-TW/memory#rules-frontmatter-reference) |

1531 1531

1532在 [plugin](/docs/zh-TW/plugins-reference#plugin-agent-frontmatter) 中提供的代理遵守子代理欄位的子集。1532在 [plugin](/docs/zh-TW/plugins/components#agents) 中提供的代理遵守子代理欄位的子集。

1533 1533

1534<h2 id="troubleshoot-configuration">1534<h2 id="troubleshoot-configuration">

1535 疑難排解設定1535 疑難排解設定

1569| `feedback/drafts/` | 排隊的 [Claude 起草的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior) 等待您在 `/feedback` 中審查。在 `cleanupPeriodDays` 或 30 天後掃描，以較短者為準。當佇列達到其 10 份草稿限制時，Claude Code 會刪除最舊的草稿以騰出空間。 |1569| `feedback/drafts/` | 排隊的 [Claude 起草的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior) 等待您在 `/feedback` 中審查。在 `cleanupPeriodDays` 或 30 天後掃描，以較短者為準。當佇列達到其 10 份草稿限制時，Claude Code 會刪除最舊的草稿以騰出空間。 |

1570| `usage-data/` | 由 [`/insights`](/docs/zh-TW/costs#analyze-your-usage-patterns) 寫入的 `report.html` 和時間戳記報告副本，加上用於建立它們的快取每個工作階段分析資料 |1570| `usage-data/` | 由 [`/insights`](/docs/zh-TW/costs#analyze-your-usage-patterns) 寫入的 `report.html` 和時間戳記報告副本，加上用於建立它們的快取每個工作階段分析資料 |

1571| `skills/.trash/`、`plugins/.trash/` | claude.ai 同步移除的 [Skills](/docs/zh-TW/skills#how-synced-skills-behave) 和 [plugins](/docs/zh-TW/plugins-reference#synced-plugins)，例如在您在 claude.ai 上關閉一個或停止同步後。檔案保留在此處，以便您可以復原它們，直到掃描刪除它們 |1571| `skills/.trash/`、`plugins/.trash/` | claude.ai 同步移除的 [Skills](/docs/zh-TW/skills#how-synced-skills-behave) 和 [plugins](/docs/zh-TW/plugins/loading#synced-plugins)，例如在您在 claude.ai 上關閉一個或停止同步後。檔案保留在此處，以便您可以復原它們，直到掃描刪除它們 |

1573 1573

1574`sessions/` 中的工作階段檔案、自動記憶和 Claude Desktop 和 Cowork 文字記錄各自遵循自己的保留規則：1574`sessions/` 中的工作階段檔案、自動記憶和 Claude Desktop 和 Cowork 文字記錄各自遵循自己的保留規則：

1678您也可以手動刪除上述任何應用程式資料路徑，除了 [state files to keep](#state-files-to-keep)。新工作階段不受影響。下表顯示您對過去工作階段失去的內容。1678您也可以手動刪除上述任何應用程式資料路徑，除了 [state files to keep](#state-files-to-keep)。新工作階段不受影響。下表顯示您對過去工作階段失去的內容。

1679 1679

1680| 刪除 | 您失去 |1680| 刪除 | 您失去 |

1681| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |1681| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |

1695| `~/.claude/skills/.trash/`、`~/.claude/plugins/.trash/` | 復原 Claude Code 移除的 [synced skills](/docs/zh-TW/skills#how-synced-skills-behave) 和 [synced plugins](/docs/zh-TW/plugins-reference#synced-plugins) 的機會 |1695| `~/.claude/skills/.trash/`、`~/.claude/plugins/.trash/` | 復原 Claude Code 移除的 [synced skills](/docs/zh-TW/skills#how-synced-skills-behave) 和 [synced plugins](/docs/zh-TW/plugins/loading#synced-plugins) 的機會 |

1696| `~/.claude/debug/`、`~/.claude/plans/`、`~/.claude/session-env/`、`~/.claude/shell-snapshots/`、`~/.claude/backups/` | 無使用者面向的內容 |1696| `~/.claude/debug/`、`~/.claude/plans/`、`~/.claude/session-env/`、`~/.claude/shell-snapshots/`、`~/.claude/backups/` | 無使用者面向的內容 |

1698 1698

claude-platform-on-aws.md +1 −1

Details

242 242

243Claude Code 也會在啟動時執行此命令，當它無法驗證您現有的 AWS 認證時，並在 `Authentication` 面板中顯示命令的輸出，直到登入完成。243Claude Code 也會在啟動時執行此命令，當它無法驗證您現有的 AWS 認證時，並在 `Authentication` 面板中顯示命令的輸出，直到登入完成。

244 244

245設定 `awsAuthRefresh` 後，執行 `/login`，選取**第三方平台**，然後在**使用第三方平台**下選取 **Claude Platform on AWS · 重新整理認證**。Claude Code 會執行已設定的命令，並重新讀取您的 AWS 認證，而無需重新啟動。此選項需要 Claude Code v2.1.186 或更新版本。245設定 `awsAuthRefresh` 後，執行 `/login`，選取**第三方平台**，然後在**使用第三方平台**下選取 **Claude Platform on AWS · 重新整理認證**。Claude Code 會執行已設定的命令，並重新讀取您的 AWS 認證，而無需重新啟動。

246 246

247**選項 B：工作區 API 金鑰**247**選項 B：工作區 API 金鑰**

248 248

claude-projects.md +38 −36

Details

10 Projects 在 Pro 和 Max 方案上處於公開測試版，並逐步推出，首先針對已使用 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 且在 claude.ai 聊天或 Cowork 中沒有現有專案的帳戶。目前在 Team 或 Enterprise 方案上還不可用。如果 **Projects** 沒有出現在 [claude.ai/code](https://claude.ai/code) 的側邊欄中或 [桌面應用程式](/docs/zh-TW/desktop) 的 Code 標籤中，表示推出尚未到達您的帳戶，您可以 [加入等候清單](https://claude.com/form/projects)。[平行執行代理](/docs/zh-TW/agents) 列出了您在此期間可以使用的內容。10 Projects 在 Pro 和 Max 方案上處於公開測試版，並逐步推出，首先針對已使用 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 且在 claude.ai 聊天或 Cowork 中沒有現有專案的帳戶。目前在 Team 或 Enterprise 方案上還不可用。如果 **Projects** 沒有出現在 [claude.ai/code](https://claude.ai/code) 的側邊欄中或 [桌面應用程式](/docs/zh-TW/desktop) 的 Code 標籤中，表示推出尚未到達您的帳戶，您可以 [加入等候清單](https://claude.com/form/projects)。[平行執行代理](/docs/zh-TW/agents) 列出了您在此期間可以使用的內容。

11</Note>11</Note>

12 12

13專案是一個進行中的對話，Claude 在其中為您協調一系列相關工作。您告訴它需要做什麼，它會為每個任務啟動一個執行緒。每個執行緒都是一個 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)：Claude Code 在雲端而不是在您的機器上執行。執行緒平行執行，並在您關閉筆記型電腦後繼續進行，您可以從您的手機檢查它們並引導它們。13專案是一個進行中的對話，Claude 在其中為您協調一系列相關工作。您告訴它需要做什麼，它會為每個任務啟動一個執行緒。

15每個執行緒通常是一個 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)：Claude Code 在雲端而不是在您的機器上執行。當任務需要只有您的電腦才有的東西時，您可以要求 Claude 改為透過 [Remote Control](/docs/zh-TW/remote-control) 在您的電腦上執行該執行緒。執行緒平行執行，您可以從您的手機檢查它們並引導它們。雲端執行緒在您關閉筆記型電腦後會繼續進行。

14 16

15沒有專案的情況下，執行多個工作階段意味著自己進行協調：您決定每個工作階段要處理什麼，在每個工作階段的開始重複相同的背景資訊，並檢查哪個已完成或需要答案。使用專案，您可以改為：17沒有專案的情況下，執行多個工作階段意味著自己進行協調：您決定每個工作階段要處理什麼，在每個工作階段的開始重複相同的背景資訊，並檢查哪個已完成或需要答案。使用專案，您可以改為：

16 18

17* **將工作發送到一個地方**：每當出現時，將錯誤報告、堆疊追蹤或任務清單貼到對話中。Claude 為每個工作片段啟動一個執行緒，或將其傳遞給已在該區域工作的執行緒，並就地回答快速問題。19* **將工作發送到一個地方**：每當出現時，將錯誤報告、堆疊追蹤或任務清單貼到對話中。Claude 為每個工作片段啟動一個執行緒，或將其傳遞給已在該區域工作的執行緒，並就地回答快速問題。

~~18* **設定一次背景資訊**：每個新執行緒都以專案的儲存庫、指示和記憶開始，因此您陳述一次的規則（例如要針對的分支）會到達所有執行緒。~~20* **設定一次背景資訊**：每個新執行緒都以專案的指示開始，因此您陳述一次的規則（例如要針對的分支）會到達所有執行緒。

19* **離開並返回已完成的工作**：當您一小時後或第二天早上回來時，**Overview** 窗格會顯示哪些執行緒已完成、哪些提取請求已準備好供審查，以及哪個執行緒正在等待您的答案。21* **離開並返回已完成的工作**：當您一小時後或第二天早上回來時，**Overview** 窗格會顯示哪些執行緒已完成、哪些提取請求已準備好供審查，以及哪個執行緒正在等待您的答案。

20 22

21如果您已經知道希望專案執行的工作，請直接前往 [建立專案](#create-a-project)。23如果您已經知道希望專案執行的工作，請直接前往 [建立專案](#create-a-project)。

37 何時其他方式更合適39 何時其他方式更合適

38</h3>40</h3>

39 41

40執行緒在 GitHub 儲存庫以及您上傳到 project 的檔案、資料夾和 Google Drive 資料夾上工作，而不是在僅存在於您機器上的檔案或工具上。在這些情況下，其他方式更合適：42Cloud threads 在 GitHub 儲存庫以及您上傳到 project 的檔案、資料夾和 Google Drive 資料夾上工作，而不是在僅存在於您機器上的檔案或工具上。如果任務需要您的機器，請透過 [Remote Control](/docs/zh-TW/remote-control) 要求 Claude 在那裡執行其執行緒。[Limitations](#limitations) 列出了這需要什麼。在這些情況下，其他方式更合適：

41 43

42* **一個適合工作階段的任務**："修復不穩定的登入測試。" 自己啟動 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)。44* **一個適合工作階段的任務**："修復不穩定的登入測試。" 自己啟動 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)。

43* **需要只有您的機器才能到達的工具或服務的工作**：本地資料庫、設備模擬器、您 VPN 後面的 API。使用本地工作階段，或 [代理檢視](/docs/zh-TW/agent-view) 同時執行多個。如果工作只需要本地檔案，請改為將它們上傳到 project。45* **每個任務都需要您的機器的工作**：本地資料庫、設備模擬器或您 VPN 後面的 API。使用本地工作階段，或 [agent view](/docs/zh-TW/agent-view) 同時執行多個。如果工作只需要本地檔案，請改為將它們上傳到 project。

44* **一個按時間表重複的任務，周圍沒有對話**："每週一發佈依賴報告。" 自己建立 [routine](/docs/zh-TW/routines)。46* **一個按時間表重複的任務，周圍沒有對話**："每週一發佈依賴報告。" 自己建立 [routine](/docs/zh-TW/routines)。

45* **多個人在 Slack 頻道中給 Claude 工作並一起引導它**：請參閱 [Claude Tag](https://claude.com/docs/claude-tag/overview)。47* **多個人在 Slack 頻道中給 Claude 工作並一起引導它**：請參閱 [Claude Tag](https://claude.com/docs/claude-tag/overview)。

46 48

53Project 是一個協調對話加上它啟動的執行緒來完成工作。這些是它的部分：55Project 是一個協調對話加上它啟動的執行緒來完成工作。這些是它的部分：

54 56

55* **project 對話**：一個長期執行的工作階段，Claude 充當協調者。它接收您發送的內容，決定什麼成為執行緒，並跟蹤它啟動的每個執行緒。它看到執行緒報告回來的內容，而不是它們採取的每一步。57* **project 對話**：一個長期執行的工作階段，Claude 充當協調者。它接收您發送的內容，決定什麼成為執行緒，並跟蹤它啟動的每個執行緒。它看到執行緒報告回來的內容，而不是它們採取的每一步。

56* **執行緒**：工作者。每個都是一個單獨的 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，有自己的上下文視窗，在自己的分支上完成一項工作，在工作需要時打開提取請求，並在完成時報告回對話。58* **執行緒**：工作者。每個都是一個單獨的工作階段，有自己的上下文視窗，完成一項工作並在完成時報告回對話。雲端執行緒在自己的分支上工作，並在工作需要時打開提取請求。

~~57* **每個執行緒開始時的內容**：~~59* **每個雲端執行緒開始時的內容**：

58 * project 的儲存庫和檔案，加上其 [指示和記憶](#give-a-project-standing-context)60 * project 的儲存庫和檔案，加上其 [指示和記憶](#give-a-project-standing-context)

59 * `CLAUDE.md`、skills 和 [project 每個儲存庫](#what-threads-pick-up-from-your-repositories) 中的 plugins，以及在有一個儲存庫的 project 中，該儲存庫的權限規則和 hooks61 * `CLAUDE.md` 和 [project 每個儲存庫](#what-threads-pick-up-from-your-repositories) 中的 skills，以及在有一個儲存庫的 project 中，該儲存庫的權限規則和 hooks

60 * 您 claude.ai 帳戶上的 [connectors](#get-skills-plugins-connectors-and-tools-into-threads)62 * 您 claude.ai 帳戶上的 [connectors](#get-skills-plugins-connectors-and-tools-into-threads)

61 * 一個 [雲端環境](#choose-an-environment-for-threads)，設定其網路存取、環境變數、API 認證和已安裝的工具63 * 一個 [雲端環境](#choose-an-environment-for-threads)，設定其網路存取、環境變數、API 認證和已安裝的工具

62* **Overview 窗格**：您在其中 [一次看到所有執行緒](#see-what-needs-you-in-overview) 以及其中哪些需要您。其他標籤是 **Library** 用於您添加的檔案和執行緒產生的檔案，**Pull requests** 用於執行緒開啟的提取請求，**Routines** 用於 project 中的排程工作。64* **Overview 窗格**：您在其中 [一次看到所有執行緒](#see-what-needs-you-in-overview) 以及其中哪些需要您。其他標籤是 **Library** 用於您添加的檔案和執行緒產生的檔案，**Pull requests** 用於執行緒開啟的提取請求，**Routines** 用於 project 中的排程工作。

63 65

64執行緒不會從您自己機器上的 Claude Code 設定中選擇任何內容。[將 skills、plugins、connectors 和工具放入執行緒](#get-skills-plugins-connectors-and-tools-into-threads) 涵蓋了如何給予它們否則會缺少的內容。66雲端執行緒不會從您自己機器上的 Claude Code 設定中選擇任何內容。[將 skills、plugins、connectors 和工具放入執行緒](#get-skills-plugins-connectors-and-tools-into-threads) 涵蓋了如何給予它們否則會缺少的內容。

65 67

66以下是這些部分如何連接的方式，從您通過對話到執行工作的執行緒，**Overview** 跟蹤其狀態：68以下是這些部分如何連接的方式，從您通過對話到執行工作的執行緒，**Overview** 跟蹤其狀態：

67 69

68<Frame>70<Frame>

69 <img src="https://mintcdn.com/claude-code/e8CLbxM17eD7cAiv/images/claude-projects-overview.svg?fit=max&auto=format&n=e8CLbxM17eD7cAiv&q=85&s=dbf446f69f0bbdb9961d21af207cb93b" className="dark:hidden" alt="Project 的圖表。您在 project 對話中寫入，Claude 回答或啟動執行緒。每個執行緒是在自己的分支和提取請求上工作的雲端工作階段。Overview 窗格按狀態列出執行緒，例如準備好供審查、等待您和工作中。" width="600" height="250" data-path="images/claude-projects-overview.svg" />71 <img src="https://mintcdn.com/claude-code/e8CLbxM17eD7cAiv/images/claude-projects-overview.svg?fit=max&auto=format&n=e8CLbxM17eD7cAiv&q=85&s=dbf446f69f0bbdb9961d21af207cb93b" className="dark:hidden" alt="Project 的圖表。您在 project 對話中寫入，Claude 回答或啟動執行緒。每個雲端執行緒在自己的分支和提取請求上工作。Overview 窗格按狀態列出執行緒，例如準備好供審查、等待您和工作中。" width="600" height="250" data-path="images/claude-projects-overview.svg" />

70 72

71 <img src="https://mintcdn.com/claude-code/e8CLbxM17eD7cAiv/images/claude-projects-overview-dark.svg?fit=max&auto=format&n=e8CLbxM17eD7cAiv&q=85&s=549a5ba9fea8433729babc37a1f6e9c8" className="hidden dark:block" alt="Project 的圖表。您在 project 對話中寫入，Claude 回答或啟動執行緒。每個執行緒是在自己的分支和提取請求上工作的雲端工作階段。Overview 窗格按狀態列出執行緒，例如準備好供審查、等待您和工作中。" width="600" height="250" data-path="images/claude-projects-overview-dark.svg" />73 <img src="https://mintcdn.com/claude-code/e8CLbxM17eD7cAiv/images/claude-projects-overview-dark.svg?fit=max&auto=format&n=e8CLbxM17eD7cAiv&q=85&s=549a5ba9fea8433729babc37a1f6e9c8" className="hidden dark:block" alt="Project 的圖表。您在 project 對話中寫入，Claude 回答或啟動執行緒。每個雲端執行緒在自己的分支和提取請求上工作。Overview 窗格按狀態列出執行緒，例如準備好供審查、等待您和工作中。" width="600" height="250" data-path="images/claude-projects-overview-dark.svg" />

72</Frame>74</Frame>

73 75

74<h2 id="create-a-project">76<h2 id="create-a-project">

279 為專案提供常設背景281 為專案提供常設背景

280</h2>282</h2>

281 283

282專案記憶、專案指示，以及專案的儲存庫、檔案和環境會跨執行緒攜帶背景。您設定每一個一次，它就會套用到每個新執行緒。284專案記憶、專案指示，以及專案的儲存庫、檔案和環境會跨執行緒攜帶背景。您設定每一個一次。

283 285

284| 背景 | 它攜帶什麼 | 您如何設定它 |286| 背景 | 它攜帶什麼 | 您如何設定它 |

285| :-------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |287| :-------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |

289 291

290**專案設定 > 記憶**在**自動記憶**下列出這些檔案，因為 Claude 在專案中工作時自己寫入它們。它們與 Claude Code 在您的機器上保留的[自動記憶](/docs/zh-TW/memory)分開，儘管兩者都使用 `MEMORY.md` 索引。專案記憶也與專案儲存庫中的 `CLAUDE.md` 檔案分開。每個執行緒在啟動時仍然從其複製讀取這些 `CLAUDE.md` 檔案，因此將關於儲存庫的指示放在其 `CLAUDE.md` 中，將關於專案的筆記放在專案記憶中。292**專案設定 > 記憶**在**自動記憶**下列出這些檔案，因為 Claude 在專案中工作時自己寫入它們。它們與 Claude Code 在您的機器上保留的[自動記憶](/docs/zh-TW/memory)分開，儘管兩者都使用 `MEMORY.md` 索引。專案記憶也與專案儲存庫中的 `CLAUDE.md` 檔案分開。每個雲端執行緒在啟動時仍然從其複製讀取這些 `CLAUDE.md` 檔案，因此將關於儲存庫的指示放在其 `CLAUDE.md` 中，將關於專案的筆記放在專案記憶中。

291 293

292<h3 id="write-project-instructions">294<h3 id="write-project-instructions">

293 寫入專案指示295 寫入專案指示

312- 不要在沒有在執行緒中詢問我的情況下合併、強制推送或變更 CI 設定。314- 不要在沒有在執行緒中詢問我的情況下合併、強制推送或變更 CI 設定。

313```315```

314 316

315關於一個儲存庫的規則，例如其建置命令，屬於該儲存庫的 `CLAUDE.md`，每個執行緒在儲存庫是專案的一部分時讀取。一旦工作開始，當您更正執行緒時，也要告訴 Claude 記住更正：它進入[專案記憶](#give-a-project-standing-context)，稍後的執行緒開始時會有它。317關於一個儲存庫的規則，例如其建置命令，屬於該儲存庫的 `CLAUDE.md`，每個雲端執行緒在儲存庫是專案的一部分時讀取。一旦工作開始，當您更正執行緒時，也要告訴 Claude 記住更正：它進入[專案記憶](#give-a-project-standing-context)，稍後的雲端執行緒開始時會有它。

316 318

317<h3 id="decide-which-repositories-to-add">319<h3 id="decide-which-repositories-to-add">

318 決定要新增哪些儲存庫320 決定要新增哪些儲存庫

319</h3>321</h3>

320 322

321您新增到專案的儲存庫在每個執行緒中都帶有其中的所有內容、其程式碼、`CLAUDE.md` 和技能。您不新增的儲存庫仍在範圍內：執行緒在其任務需要時可以將其新增到自己。大多數專案同時使用兩者：323您新增到專案的儲存庫在每個雲端執行緒中都帶有其中的所有內容、其程式碼、`CLAUDE.md` 和技能。您不新增的儲存庫仍在範圍內：雲端執行緒在其任務需要時可以將其新增到自己。大多數專案同時使用兩者：

322 324

323* **將其新增到專案**，在**新專案**對話中、在**專案設定 > 環境**中，或通過在對話中要求 Claude 將其新增到專案。從那時起，每個執行緒都會複製它並開始使用其 `CLAUDE.md` 和技能，無論任務是否涉及它。從一個儲存庫轉到多個儲存庫也會改變執行緒從每個儲存庫的 `.claude/settings.json` 中取得的內容；請參閱[執行緒從您的儲存庫中取得什麼](#what-threads-pick-up-from-your-repositories)。325* **將其新增到專案**，在**新專案**對話中、在**專案設定 > 環境**中，或通過在對話中要求 Claude 將其新增到專案。從那時起，每個雲端執行緒都會複製它並開始使用其 `CLAUDE.md` 和技能，無論任務是否涉及它。從一個儲存庫轉到多個儲存庫也會改變執行緒從每個儲存庫的 `.claude/settings.json` 中取得的內容；請參閱[執行緒從您的儲存庫中取得什麼](#what-threads-pick-up-from-your-repositories)。

324* **不要新增它，讓執行緒在需要時自行新增。** 其任務需要專案沒有的儲存庫的執行緒可以將其新增到自己，執行緒中的筆記表示它僅被新增到此執行緒。複製發生在任務進行中途，因此該儲存庫的 `CLAUDE.md` 和技能在執行緒啟動時不存在。下一個執行緒再次啟動時沒有它。執行緒新增的儲存庫需要與專案儲存庫相同的[先決條件](#check-the-prerequisites)：在其上安裝的 Claude GitHub App 和來自您的 GitHub 帳戶的推送存取。326* **不要新增它，讓執行緒在需要時自行新增。** 其任務需要專案沒有的儲存庫的雲端執行緒可以將其新增到自己，執行緒中的筆記表示它僅被新增到此執行緒。複製發生在任務進行中途，因此該儲存庫的 `CLAUDE.md` 和技能在執行緒啟動時不存在。下一個執行緒再次啟動時沒有它。執行緒新增的儲存庫需要與專案儲存庫相同的[先決條件](#check-the-prerequisites)：在其上安裝的 Claude GitHub App 和來自您的 GitHub 帳戶的推送存取。

325 327

326專案根本不需要儲存庫。其執行緒仍然可以進行研究、寫入文件，以及在自己的沙箱中寫入和執行程式碼，並將檔案傳遞到**程式庫**標籤。那裡的執行緒也可以在任務需要時將儲存庫新增到自己。328專案根本不需要儲存庫。其雲端執行緒仍然可以進行研究、寫入文件，以及在自己的沙箱中寫入和執行程式碼，並將檔案傳遞到**程式庫**標籤。那裡的任何雲端執行緒也可以在任務需要時將儲存庫新增到自己。

327 329

328一旦專案有了儲存庫，Claude 只能從專案已經使用的 GitHub 擁有者新增儲存庫，無論它是將其新增到專案還是執行緒將其新增到自己。要引入來自不同擁有者的儲存庫，請在**專案設定 > 環境**中自己新增它。330一旦專案有了儲存庫，Claude 只能從專案已經使用的 GitHub 擁有者新增儲存庫，無論它是將其新增到專案還是執行緒將其新增到自己。要引入來自不同擁有者的儲存庫，請在**專案設定 > 環境**中自己新增它。

329 331

333 執行緒從您的儲存庫中取得什麼335 執行緒從您的儲存庫中取得什麼

334</h3>336</h3>

335 337

336每個執行緒複製專案中的每個儲存庫，並從所有儲存庫載入 `CLAUDE.md` 和技能。權限規則、hooks 和 `env` 僅來自執行緒啟動所在目錄中的 `.claude/settings.json`：當專案有一個時在儲存庫內，當它有多個時在複製上方，其中沒有儲存庫的檔案被讀取用於它們。338每個雲端執行緒複製專案中的每個儲存庫，並從所有儲存庫載入 `CLAUDE.md` 和技能。權限規則、hooks 和 `env` 僅來自執行緒啟動所在目錄中的 `.claude/settings.json`：當專案有一個時在儲存庫內，當它有多個時在複製上方，其中沒有儲存庫的檔案被讀取用於它們。

337 339

339| :----------------------------------------------- | :------------------------------------------------------------------------------------------ | :---------------------------- |341| :----------------------------------------------- | :------------------------------------------------------------------------------------------ | :---------------------------- |

348 為執行緒選擇環境350 為執行緒選擇環境

349</h3>351</h3>

350 352

351每個新執行緒在專案的[雲端環境](/docs/zh-TW/cloud-environments)中啟動。環境設定執行緒可以到達哪些網域、它們有哪些環境變數、哪些 API 認證被新增到它們的請求，以及設定指令碼在 Claude 啟動前安裝什麼。執行緒使用預設的 Anthropic 託管環境，直到您在**專案設定 > 環境**中選擇一個。353每個新雲端執行緒在專案的[雲端環境](/docs/zh-TW/cloud-environments)中啟動。環境設定執行緒可以到達哪些網域、它們有哪些環境變數、哪些 API 認證被新增到它們的請求，以及設定指令碼在 Claude 啟動前安裝什麼。雲端執行緒使用預設的 Anthropic 託管環境，直到您在**專案設定 > 環境**中選擇一個。

352 354

353如果執行緒需要到達內部 API 或私有套件登錄，或需要您的機器通常持有的令牌，請變更環境而不是專案：請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)、[新增 API 認證](/docs/zh-TW/cloud-environments#add-api-credentials)和[設定指令碼](/docs/zh-TW/cloud-environments#setup-scripts)。355如果雲端執行緒需要到達內部 API 或私有套件登錄，或需要您的機器通常持有的令牌，請變更環境而不是專案：請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)、[新增 API 認證](/docs/zh-TW/cloud-environments#add-api-credentials)和[設定指令碼](/docs/zh-TW/cloud-environments#setup-scripts)。

354 356

355<h3 id="get-skills-plugins-connectors-and-tools-into-threads">357<h3 id="get-skills-plugins-connectors-and-tools-into-threads">

356 將技能、外掛程式、連接器和工具引入執行緒358 將技能、外掛程式、連接器和工具引入執行緒

357</h3>359</h3>

358 360

359執行緒是雲端工作階段，因此它們沒有僅在您的機器上安裝的技能、MCP 伺服器、外掛程式和工具。要使這些中的每一個對執行緒可用：361雲端執行緒沒有僅在您的機器上安裝的技能、MCP 伺服器、外掛程式和工具。通過[遠端控制](/docs/zh-TW/remote-control)在您的機器上執行的執行緒使用那裡安裝的內容。要使這些中的每一個對雲端執行緒可用：

360 362

361* 技能、子代理和命令：將它們提交到您新增到專案的儲存庫，例如 `.claude/skills/<skill-name>/SKILL.md` 中的技能。每個執行緒複製專案中的每個儲存庫，並從每個儲存庫載入 `.claude/skills/`、`.claude/agents/` 和 `.claude/commands/`，因此提交到一個儲存庫的技能在每個新執行緒中可用。執行緒也載入您為 claude.ai 帳戶啟用的技能。363* 技能、子代理和命令：將它們提交到您新增到專案的儲存庫，例如 `.claude/skills/<skill-name>/SKILL.md` 中的技能。每個雲端執行緒複製專案中的每個儲存庫，並從每個儲存庫載入 `.claude/skills/`、`.claude/agents/` 和 `.claude/commands/`，因此提交到一個儲存庫的技能在每個雲端執行緒中可用。雲端執行緒也載入您為 claude.ai 帳戶啟用的技能。

362* 外掛程式：在**專案設定 > 外掛程式**中新增它們；它們載入到每個新執行緒。儲存庫在其 `.claude/settings.json` 中宣告的外掛程式[不會在執行緒中載入](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)，因為執行緒是雲端工作階段。364* 外掛程式：在**專案設定 > 外掛程式**中新增它們；它們載入到每個新雲端執行緒。儲存庫在其 `.claude/settings.json` 中宣告的外掛程式[不會在雲端執行緒中載入](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)。

363* MCP 伺服器：執行緒從您的 claude.ai 帳戶上的連接器獲取其 MCP 工具，這些是您在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 或通過**專案設定 > 環境**中的**管理連接器**連結連接一次的 MCP 伺服器。每個執行緒可以使用所有它們，無需每個專案的設定。專案對話本身沒有連接器，因此將需要連接器的工作作為執行緒的任務傳送。在具有一個儲存庫的專案中，執行緒也從該儲存庫的 [`.mcp.json`](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 載入 MCP 伺服器。[連接器如何到達 Claude Code](/docs/zh-TW/mcp#how-connectors-reach-claude-code) 列出雲端工作階段的規則和關閉連接器的設定。365* MCP 伺服器：雲端執行緒從您的 claude.ai 帳戶上的連接器獲取其 MCP 工具，這些是您在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 或通過**專案設定 > 環境**中的**管理連接器**連結連接一次的 MCP 伺服器。每個雲端執行緒可以使用所有它們，無需每個專案的設定。專案對話本身沒有連接器，因此將需要連接器的工作作為雲端執行緒的任務傳送。在具有一個儲存庫的專案中，雲端執行緒也從該儲存庫的 [`.mcp.json`](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 載入 MCP 伺服器。[連接器如何到達 Claude Code](/docs/zh-TW/mcp#how-connectors-reach-claude-code) 列出雲端工作階段的規則和關閉連接器的設定。

364* 命令列工具和套件：在環境的[設定指令碼](/docs/zh-TW/cloud-environments#setup-scripts)中安裝它們。366* 命令列工具和套件：在環境的[設定指令碼](/docs/zh-TW/cloud-environments#setup-scripts)中安裝它們。

365 367

366要查看執行中的執行緒在 claude.ai/code 有哪些連接器，請開啟執行緒並從其訊息框旁邊的 **+** 功能表中選擇**連接器**。關閉連接器會將其從該執行緒中移除，並將其儲存為您的帳戶預設值，因此新執行緒和 claude.ai 聊天在您重新開啟它之前開始時沒有它。執行緒在您傳送給它的下一條訊息後取得您新增或重新連接的連接器。368要查看執行中的雲端執行緒在 claude.ai/code 有哪些連接器，請開啟執行緒並從其訊息框旁邊的 **+** 功能表中選擇**連接器**。關閉連接器會將其從該執行緒中移除，並將其儲存為您的帳戶預設值，因此新執行緒和 claude.ai 聊天在您重新開啟它之前開始時沒有它。執行緒在您傳送給它的下一條訊息後取得您新增或重新連接的連接器。

367 369

368<h2 id="project-settings-reference">370<h2 id="project-settings-reference">

369 Project 設定參考371 Project 設定參考

434 Projects 與其他 Claude Code 功能的關係436 Projects 與其他 Claude Code 功能的關係

435</h2>437</h2>

436 438

437幾個 Claude Code 功能讓多個工作階段同時工作，因此平行執行工作本身不是 project 的用途。在 project 中，Claude 啟動並跟蹤工作階段而不是您，每個都從相同的儲存庫、指示和記憶開始，工作在雲端中只要它持續就存在。以下是每個相鄰功能如何連接到 project：439幾個 Claude Code 功能讓多個工作階段同時工作，因此平行執行工作本身不是 project 的用途。在 project 中，Claude 啟動並跟蹤工作階段而不是您，每個都從相同的指示開始。以下是每個相鄰功能如何連接到 project：

438 440

439* **Claude Tag**：[Claude Tag](https://claude.com/docs/claude-tag/overview) 是您團隊 Slack 頻道中的 Claude，在 Team 和 Enterprise 方案上。頻道中的任何人都可以給它工作，頻道中的每個人都看到並引導它，它使用管理員為該頻道設定的連接。project 是您的：您是唯一給它工作或看到其執行緒的人，它使用您自己的 GitHub 存取和 connectors，它在 Pro 和 Max 上。[Claude Tag 與 Cowork 和 Claude Code 的不同之處](https://claude.com/docs/claude-tag/concepts/how-it-works#how-claude-tag-differs-from-cowork-and-claude-code) 有並排比較。441* **Claude Tag**：[Claude Tag](https://claude.com/docs/claude-tag/overview) 是您團隊 Slack 頻道中的 Claude，在 Team 和 Enterprise 方案上。頻道中的任何人都可以給它工作，頻道中的每個人都看到並引導它，它使用管理員為該頻道設定的連接。project 是您的：您是唯一給它工作或看到其執行緒的人，它使用您自己的 GitHub 存取和 connectors，它在 Pro 和 Max 上。[Claude Tag 與 Cowork 和 Claude Code 的不同之處](https://claude.com/docs/claude-tag/concepts/how-it-works#how-claude-tag-differs-from-cowork-and-claude-code) 有並排比較。

440* **雲端工作階段**：每個執行緒是一個 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，由 Claude 而不是您啟動和跟蹤。您自己啟動的雲端工作階段可以通過 [**Continue as a project** 或 **Move to project**](#start-from-an-existing-cloud-session) 成為 project 或提供一個。442* **雲端工作階段**：每個執行緒是一個 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，除非您要求 Claude 在您的機器上執行它。無論哪種方式，Claude 啟動並跟蹤它而不是您。您自己啟動的雲端工作階段可以通過 [**Continue as a project** 或 **Move to project**](#start-from-an-existing-cloud-session) 成為 project 或提供一個。

441* **Routines**：當您在 project 中要求排程工作時，Claude 建立一個 [routine](/docs/zh-TW/routines)，在該 project 中作為執行緒執行，並出現在其 **Routines** 標籤上。您在 project 外建立的 Routines 保持自己工作。443* **Routines**：當您在 project 中要求排程工作時，Claude 建立一個 [routine](/docs/zh-TW/routines)，在該 project 中作為執行緒執行，並出現在其 **Routines** 標籤上。您在 project 外建立的 Routines 保持自己工作。

442* **本地工作階段和代理檢視**：您終端、IDE 或桌面應用程式本地環境中的工作階段在您的機器上執行，無法成為 project 的一部分。[代理檢視](/docs/zh-TW/agent-view) 是用於跟蹤多個那些本地工作階段的螢幕；它沒有協調者。444* **本地工作階段和代理檢視**：您在終端、IDE 或桌面應用程式的本地環境中啟動的工作階段無法新增到 project。project 只能通過執行執行緒在您的機器上透過 [Remote Control](/docs/zh-TW/remote-control) 到達您的機器。[代理檢視](/docs/zh-TW/agent-view) 是用於跟蹤您自己啟動的多個本地工作階段的螢幕；它沒有協調者。

443* **Worktrees**：[worktree](/docs/zh-TW/worktrees) 給每個本地工作階段其自己的儲存庫工作副本，因此您機器上的平行工作階段不會相互覆蓋。執行緒不需要它們：每個執行緒將其儲存庫克隆到其自己的雲端沙箱中，並在自己的分支上工作。445* **Worktrees**：[worktree](/docs/zh-TW/worktrees) 給每個本地工作階段其自己的儲存庫工作副本，因此您機器上的平行工作階段不會相互覆蓋。雲端執行緒不需要它們：每個執行緒將其儲存庫克隆到其自己的雲端沙箱中，並在自己的分支上工作。

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

445* **claude.ai 聊天和 Cowork 中的 Projects**：[早期 Projects 體驗](https://support.claude.com/en/articles/9517075-what-are-projects)，它對話和參考檔案進行分組，沒有執行緒或協調者。那些 projects 保持今天的工作方式，直到重新設計的體驗到達它們。447* **claude.ai 聊天和 Cowork 中的 Projects**：[早期 Projects 體驗](https://support.claude.com/en/articles/9517075-what-are-projects)，它對話和參考檔案進行分組，沒有執行緒或協調者。那些 projects 保持今天的工作方式，直到重新設計的體驗到達它們。

446 448

451</h2>453</h2>

452 454

453* Projects 在 claude.ai/code、桌面應用程式和 Claude 行動應用程式中可用，不在終端 CLI 或通過 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 中。CLI 的 [`claude project`](/docs/zh-TW/cli-reference) 命令，它管理目錄的本地 Claude Code 狀態，是無關的。455* Projects 在 claude.ai/code、桌面應用程式和 Claude 行動應用程式中可用，不在終端 CLI 或通過 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 中。CLI 的 [`claude project`](/docs/zh-TW/cli-reference) 命令，它管理目錄的本地 Claude Code 狀態，是無關的。

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

455* 本地工作階段無法成為 project 的一部分。457* 您無法將自己在機器上啟動的工作階段新增到 project。若要讓 project 在您的機器上執行執行緒，請通過 [Remote Control](/docs/zh-TW/remote-control#requirements) 連線它應該在其中工作的資料夾：在 Claude 桌面應用程式的 **Settings > Claude Code** 下開啟 Remote Control，或在資料夾中執行 `claude remote-control` 並讓它保持執行。該機器需要 Claude Code v2.1.280 或更新版本。當您的 claude.ai 設定中的 **Require trusted devices** 開啟時，project 也無法在您的機器上執行執行緒。

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

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

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

459 461

467 執行緒看起來卡住了469 執行緒看起來卡住了

468</h3>470</h3>

469 471

470Claude 不發佈執行緒採取的每一步，因此顯示為執行中且 project 對話中沒有新訊息的執行緒通常仍在工作。新執行緒也在 Claude 開始之前配置其 [雲端環境](/docs/zh-TW/cloud-environments)，因此其第一次更新需要片刻。打開執行緒讀取其記錄。如果執行緒正在等待權限提示，在那裡回答它。472Claude 不發佈執行緒採取的每一步，因此顯示為執行中且 project 對話中沒有新訊息的執行緒通常仍在工作。新雲端執行緒也在 Claude 開始之前配置其 [雲端環境](/docs/zh-TW/cloud-environments)，因此其第一次更新需要片刻。打開執行緒讀取其記錄。如果執行緒正在等待權限提示，在那裡回答它。

471 473

472<h3 id="threads-guessed-or-stalled-instead-of-asking">474<h3 id="threads-guessed-or-stalled-instead-of-asking">

473 執行緒猜測或停滯而不是詢問475 執行緒猜測或停滯而不是詢問

489 儲存庫存取錯誤491 儲存庫存取錯誤

490</h3>492</h3>

491 493

492三條訊息意味著執行緒或 project 無法到達其儲存庫之一。project 執行緒需要 [GitHub 先決條件](#check-the-prerequisites)，即使您的其他雲端工作階段克隆相同儲存庫而沒有麻煩。494三條訊息意味著執行緒或 project 無法到達其儲存庫之一。project 的雲端執行緒需要 [GitHub 先決條件](#check-the-prerequisites)，即使您的其他雲端工作階段克隆相同儲存庫而沒有麻煩。

493 495

494* **「Couldn't start the session — Claude doesn't have GitHub access to this project's repository」**，在執行緒啟動之前報告，當 Claude GitHub App 未安裝在該儲存庫上、已暫停或未連結到您連接的 GitHub 帳戶時。496* **「Couldn't start the session — Claude doesn't have GitHub access to this project's repository」**，在執行緒啟動之前報告，當 Claude GitHub App 未安裝在該儲存庫上、已暫停或未連結到您連接的 GitHub 帳戶時。

495* **「Unable to access your repository」**，由執行緒報告，當其克隆失敗時：GitHub 拒絕克隆、在 project 具有的名稱下找不到儲存庫，或執行緒被要求啟動的分支不存在。497* **「Unable to access your repository」**，由執行緒報告，當其克隆失敗時：GitHub 拒絕克隆、在 project 具有的名稱下找不到儲存庫，或執行緒被要求啟動的分支不存在。

claude-security.md +5 −5

Details

27 安裝外掛程式27 安裝外掛程式

28</h2>28</h2>

29 29

~~30在 Claude Code 工作階段中，從[官方 Anthropic 市集](/docs/zh-TW/discover-plugins#official-anthropic-marketplace)安裝：~~30在 Claude Code 工作階段中，從[官方 Anthropic 市集](/docs/zh-TW/plugins/anthropic-marketplaces)安裝：

31 31

32```text theme={null}32```text theme={null}

33/plugin install claude-security@claude-plugins-official33/plugin install claude-security@claude-plugins-official

34```34```

35 35

~~36該命令會開啟外掛程式的詳細資訊，您可以在其中選擇[安裝範圍](/docs/zh-TW/discover-plugins#install-plugins)以開始安裝。~~36該命令會開啟外掛程式的詳細資訊，您可以在其中選擇[安裝範圍](/docs/zh-TW/plugins/install#install-a-plugin)以開始安裝。

37 37

38如果安裝失敗，修復方法取決於 Claude Code 報告的訊息：38如果安裝失敗，修復方法取決於 Claude Code 報告的訊息：

39 39

40* 如果它報告 `Marketplace "claude-plugins-official" not found`，使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市集，然後重試安裝。40* 如果它報告 `Marketplace "claude-plugins-official" not found`，使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市集，然後重試安裝。

~~41* 如果它報告[在市集中找不到外掛程式](/docs/zh-TW/discover-plugins#install-plugins)，檢查外掛程式名稱是否有拼寫錯誤。~~41* 如果它報告[在市集中找不到外掛程式](/docs/zh-TW/plugins/install#install-a-plugin)，檢查外掛程式名稱是否有拼寫錯誤。

42 42

43檢查安裝摘要。如果它報告 `Run /reload-plugins to activate.`，請參閱[在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)以在您目前的工作階段中啟用外掛程式。43檢查安裝摘要。如果它報告 `Run /reload-plugins to activate.`，請參閱[在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/plugins/cli-reference#reload-plugins)以在您目前的工作階段中啟用外掛程式。

44 44

45外掛程式啟用後，您已準備好[掃描和修復您的程式碼庫](#scan-and-fix-your-codebase)。45外掛程式啟用後，您已準備好[掃描和修復您的程式碼庫](#scan-and-fix-your-codebase)。

46 46

168* [Code Review](/docs/zh-TW/code-review)：設定 PR 時間多代理檢查168* [Code Review](/docs/zh-TW/code-review)：設定 PR 時間多代理檢查

169* [Claude Security](https://claude.com/product/claude-security)：監控連接儲存庫的受管服務169* [Claude Security](https://claude.com/product/claude-security)：監控連接儲存庫的受管服務

170* [Claude Code 安全](/docs/zh-TW/security)：Claude Code 如何處理信任、權限和保護措施170* [Claude Code 安全](/docs/zh-TW/security)：Claude Code 如何處理信任、權限和保護措施

171* [探索和安裝外掛程式](/docs/zh-TW/discover-plugins#official-anthropic-marketplace)：瀏覽其他官方外掛程式171* [安裝和管理外掛程式](/docs/zh-TW/plugins/install)：從官方市集尋找和安裝其他外掛程式

claude-tag.md +0 −11 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Claude Tag~~

~~7> 透過 Claude Tag 將 Claude 帶入您的團隊 Slack 頻道，並在 claude.com 上找到其設定和使用文件。~~

9[Claude Tag](https://claude.com/product/tag) 是一個 Slack 整合，在您的團隊頻道中以組織的共享身份執行 `@Claude`，具有管理員配置的存取權限。頻道中的任何人都可以在執行緒中標記 `@Claude` 並為其指派任務。請閱讀 claude.com 上的 [Claude Tag 文件](https://claude.com/docs/claude-tag/overview)，以設定並開始使用它。

11Claude Tag 適用於 Team 和 Enterprise 方案，與較早的 [Claude Code in Slack](/docs/zh-TW/slack) 不同，後者在個別使用者的帳戶下執行每個工作階段。在 Pro 和 Max 方案上，Claude Tag 不可用，Claude Code in Slack 仍然是設定路徑。

cli-reference.md +101 −101

Details

12 12

13您可以使用這些命令來啟動工作階段、管道內容、繼續對話和管理更新：13您可以使用這些命令來啟動工作階段、管道內容、繼續對話和管理更新：

14 14

15| 命令 | 描述 | 範例 |15| 命令 | 說明 | 範例 |

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

25| `claude gateway` | 啟動自託管 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 伺服器，供在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上部署 SSO 和原則在 Claude Code 前面的管理員使用。需要 `--config` 指向 [`gateway.yaml`](/docs/zh-TW/claude-apps-gateway-config)。在 Claude Code v2.1.195 及更新版本中可用。 | `claude gateway --config gateway.yaml` |25| `claude gateway` | 啟動自託管 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) 伺服器，供在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上部署 SSO 和原則在 Claude Code 前面的管理員使用。需要 `--config` 指向 [`gateway.yaml`](/docs/zh-TW/claude-apps-gateway-config)。在 Claude Code v2.1.195 及更新版本中可用。 | `claude gateway --config gateway.yaml` |

27| `claude auth login` | 登入您的 Anthropic 帳戶。使用 `--email` 預先填入您的電子郵件地址，使用 `--sso` 強制進行 SSO 驗證，使用 `--console` 以 Anthropic Console 登入以進行 API 使用計費，而不是 Claude 訂閱 | `claude auth login --console` |27| `claude auth login` | 登入您的 Anthropic 帳戶。使用 `--email` 預先填入您的電子郵件地址，`--sso` 強制 SSO 驗證，`--console` 使用 Anthropic Console 登入以進行 API 使用計費而非 Claude 訂閱 | `claude auth login --console` |

30| `claude agents` | 開啟 [agent view](/docs/zh-TW/agent-view) 以監控和分派平行背景工作階段。使用 `--cwd <path>` 僅顯示在該目錄下啟動的工作階段，或使用 `--json` 將即時工作階段列印為 JSON 陣列以供指令碼使用（`--json --all` 也包括已完成的背景工作階段）。傳遞 `--permission-mode`、`--model`、`--effort` 或 `--agent` 以設定 [分派工作階段的預設值](/docs/zh-TW/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如同頂層 `claude` 命令。開啟 agent view 需要互動式終端 | `claude agents --json` |30| `claude agents` | 開啟 [代理程式檢視](/docs/zh-TW/agent-view) 以監控和分派平行背景工作階段。使用 `--cwd <path>` 僅顯示在該目錄下啟動的工作階段，或使用 `--json` 將作用中工作階段列印為 JSON 陣列以供指令碼使用（`--json --all` 也包括已完成的背景工作階段）。傳遞 `--permission-mode`、`--model`、`--effort` 或 `--agent` 以設定 [分派工作階段的預設值](/docs/zh-TW/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如同頂層 `claude` 命令。開啟代理程式檢視需要互動式終端 | `claude agents --json` |

32| `claude auto-mode defaults` | 以 JSON 格式列印內建的 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看您的有效設定及套用的設定。`--label <prefix>` 列印標籤以該前綴開頭的規則，不區分大小寫匹配。需要 Claude Code v2.1.208 或更新版本 | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | 以 JSON 格式列印內建 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看應用了設定的有效設定。使用 `--label <prefix>` 僅列印標籤以該前綴開頭的規則，不區分大小寫。需要 Claude Code v2.1.208 或更新版本 | `claude auto-mode defaults --label 'Git Destructive'` |

33| `claude auto-mode reset` | 透過從您的使用者設定檔中移除 `autoMode` 部分來復原預設的 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 設定。在寫入前提示確認；傳遞 `-y`/`--yes` 以跳過提示。來自 [受管設定](/docs/zh-TW/server-managed-settings) 或 `--settings` 旗標的規則仍然適用。需要 Claude Code v2.1.212 或更新版本。請參閱 [檢查預設值和您的有效設定](/docs/zh-TW/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |33| `claude auto-mode reset` | 透過從使用者設定檔案中移除 `autoMode` 部分來還原預設 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 設定。在寫入前提示確認；傳遞 `-y`/`--yes` 以跳過提示。來自 [受管設定](/docs/zh-TW/server-managed-settings) 或 `--settings` 旗標的規則仍然適用。需要 Claude Code v2.1.212 或更新版本。請參閱 [檢查預設值和您的有效設定](/docs/zh-TW/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |

35| `claude daemon stop --any` | 停止背景工作階段 [supervisor](/docs/zh-TW/agent-view#the-supervisor-process) 及其託管的工作階段。傳遞 `--keep-workers` 以保持背景工作階段執行中，以便下一個 supervisor 重新連接到它們。`--any` 確認停止隨選 supervisor，這是預設值。使用此命令以從 [無回應的 supervisor](/docs/zh-TW/agent-view#agent-view-says-the-background-service-did-not-respond) 復原 | `claude daemon stop --any --keep-workers` |35| `claude daemon stop --any` | 停止背景工作階段 [監督程序](/docs/zh-TW/agent-view#the-supervisor-process) 及其託管的工作階段。傳遞 `--keep-workers` 以保持背景工作階段執行，以便下一個監督程序重新連接到它們。`--any` 確認停止隨需監督程序，這是預設值。使用此命令從 [無回應的監督程序](/docs/zh-TW/agent-view#agent-view-says-the-background-service-did-not-respond) 復原 | `claude daemon stop --any --keep-workers` |

37| `claude import [source]` | 啟動互動式工作階段，執行 [`/import`](/docs/zh-TW/commands#all-commands) 以將來自其他編碼代理的設定帶入 Claude Code。接受與命令相同的 `--dry-run` 和 `--yes` 選項。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上不可用。當您關閉 [功能旗標擷取](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching) 時也不可用。需要 Claude Code v2.1.213 或更新版本 | `claude import codex --dry-run` |37| `claude import [source]` | 啟動互動式工作階段，執行 [`/import`](/docs/zh-TW/commands#all-commands) 以將其他編碼代理程式的設定帶入 Claude Code。接受與命令相同的 `--dry-run` 和 `--yes` 選項。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上不可用。當您關閉 [功能旗標擷取](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching) 時也不可用。需要 Claude Code v2.1.213 或更新版本 | `claude import codex --dry-run` |

40| `claude mcp login <name>` | 執行已設定的 MCP 伺服器的 OAuth 流程而不開啟互動式 `/mcp` 面板。適用於 HTTP、SSE 和 claude.ai 連接器伺服器。在 SSH 上新增 `--no-browser` 以列印授權 URL 而不是開啟瀏覽器，然後將重新導向 URL 貼回提示。需要 Claude Code v2.1.186 或更新版本。請參閱 [從命令列驗證](/docs/zh-TW/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |40| `claude mcp login <name>` | 執行已設定 MCP 伺服器的 OAuth 流程，無需開啟互動式 `/mcp` 面板。適用於 HTTP、SSE 和 claude.ai 連接器伺服器。在 SSH 上新增 `--no-browser` 以列印授權 URL 而非開啟瀏覽器，然後將重新導向 URL 貼回提示。請參閱 [從命令列驗證](/docs/zh-TW/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |

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

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

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

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

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

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

50| `claude ultrareview [target]` | 非互動式執行 [ultrareview](/docs/zh-TW/ultrareview#run-ultrareview-non-interactively)。將發現列印到標準輸出，成功時以代碼 0 退出，失敗時以代碼 1 退出。使用 `--json` 取得原始承載，使用 `--timeout <minutes>` 覆蓋 45 分鐘的預設值。在 `github.com` pull request 目標上使用 `--post` 以將完成的發現作為您 GitHub 帳戶的一個純文字評論發佈到 PR。`--no-post` 是預設值。`--post` 和 `--no-post` 需要 Claude Code v2.1.227 或更新版本。請參閱 [將發現發佈到 pull request](/docs/zh-TW/ultrareview#post-findings-to-the-pull-request) | `claude ultrareview 1234 --json` |50| `claude ultrareview [target]` | 非互動式執行 [ultrareview](/docs/zh-TW/ultrareview#run-ultrareview-non-interactively)。將發現列印到 stdout，成功時退出代碼 0，失敗時退出代碼 1。使用 `--json` 以取得原始承載，使用 `--timeout <minutes>` 以覆蓋 45 分鐘的預設值。在 `github.com` 拉取請求目標上使用 `--post` 以將完成的發現作為來自您 GitHub 帳戶的一個純文字註解發佈到 PR。`--no-post` 是預設值。`--post` 和 `--no-post` 需要 Claude Code v2.1.227 或更新版本。請參閱 [將發現發佈到拉取請求](/docs/zh-TW/ultrareview#post-findings-to-the-pull-request) | `claude ultrareview 1234 --json` |

51 51

~~52如果您輸入錯誤的子命令，Claude Code 會建議最接近的匹配項並退出而不啟動工作階段。例如，`claude udpate` 會列印 `Did you mean claude update?`。~~52如果您輸入錯誤的子命令，Claude Code 會建議最接近的符合項並退出而不啟動工作階段。例如，`claude udpate` 會列印 `Did you mean claude update?`。

53 53

54自 v2.1.199 起，`claude --dangerously-skip-permissions daemon <subcommand>` 執行 `daemon` 子命令。較早的版本將 `daemon <subcommand>` 視為新互動式工作階段的提示，因此當旗標在前面時子命令永遠不會執行，這是 `claude` 別名為包含該旗標時的常見設定。只有前導 `--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 會以這種方式路由到 `daemon`；任何其他前導旗標仍會啟動互動式工作階段。54自 v2.1.199 起，`claude --dangerously-skip-permissions daemon <subcommand>` 執行 `daemon` 子命令。較早版本將 `daemon <subcommand>` 視為新互動式工作階段的提示，因此當旗標在前面時子命令永遠不會執行，這是 `claude` 別名為包含旗標時的常見設定。只有前導 `--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 以這種方式路由到 `daemon`；任何其他前導旗標仍然啟動互動式工作階段。

55 55

56<h2 id="cli-flags">56<h2 id="cli-flags">

57 CLI 旗標57 CLI 旗標

58</h2>58</h2>

59 59

~~60使用這些命令列旗標自訂 Claude Code 的行為。`claude --help` 不會列出每個旗標，因此旗標在 `--help` 中的缺失並不表示它無法使用。~~60使用這些命令列旗標自訂 Claude Code 的行為。`claude --help` 不會列出每個旗標，所以旗標在 `--help` 中缺失並不表示它無法使用。

61 61

62| 旗標 | 描述 | 範例 |62| 旗標 | 說明 | 範例 |

63| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |63| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- |

64| `--add-dir` | 新增額外的工作目錄供 Claude 讀取和編輯檔案。授予檔案存取權；Claude Code [不會從這些目錄探索](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)大多數 `.claude/` 設定。驗證每個路徑是否存在為目錄。您無法新增大多數[網路路徑](/docs/zh-TW/errors#working-directory-is-a-network-path)，例如 `\\server\share`。若要在工作階段之間持久化這些目錄，請在設定中設定 [`permissions.additionalDirectories`](/docs/zh-TW/settings-reference#permissions-additionaldirectories) | `claude --add-dir ../apps ../lib` |64| `--add-dir` | 新增額外的工作目錄供 Claude 讀取和編輯檔案。授予檔案存取權限；Claude Code [不會探索](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)這些目錄中的大多數 `.claude/` 設定。驗證每個路徑都存在為目錄。您無法新增大多數[網路路徑](/docs/zh-TW/errors#working-directory-is-a-network-path)，例如 `\\server\share`。若要在工作階段之間保留這些目錄，請在設定中設定 [`permissions.additionalDirectories`](/docs/zh-TW/settings-reference#permissions-additionaldirectories) | `claude --add-dir ../apps ../lib` |

65| `--advisor <model>` | 使用模型別名啟用此工作階段的伺服器端 [advisor tool](/docs/zh-TW/advisor)：`fable`、`opus` 或 `sonnet`，或完整模型 ID。優先於工作階段的 `advisorModel` 設定。`fable` 需要 [Fable 存取](/docs/zh-TW/advisor#choose-an-advisor-model) | `claude --advisor opus` |65| `--advisor <model>` | 使用模型別名 `fable`、`opus` 或 `sonnet`，或完整模型 ID，為此工作階段啟用伺服器端[顧問工具](/docs/zh-TW/advisor)。優先於工作階段的 `advisorModel` 設定。`fable` 需要 [Fable 存取權](/docs/zh-TW/advisor#choose-an-advisor-model) | `claude --advisor opus` |

67| `--agents` | 透過 JSON 動態定義自訂 subagents。接受 [CLI 定義的 subagents 列出的欄位](/docs/zh-TW/sub-agents#choose-the-subagent-scope)。Claude Code 在啟動時驗證 JSON 並在無效值時退出；請參閱 [`Invalid --agents configuration`](/docs/zh-TW/errors#invalid-agents-configuration) 以了解訊息以及跳過驗證的旗標和環境變數。驗證需要 Claude Code v2.1.242 或更新版本 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |67| `--agents` | 透過 JSON 動態定義自訂子代理程式。接受 [CLI 定義的子代理程式列出的欄位](/docs/zh-TW/sub-agents#choose-the-subagent-scope)。Claude Code 在啟動時驗證 JSON 並在無效值時結束；請參閱 [`Invalid --agents configuration`](/docs/zh-TW/errors#invalid-agents-configuration) 以取得訊息以及跳過驗證的旗標和環境變數。驗證需要 Claude Code v2.1.242 或更新版本 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

68| `--allow-dangerously-skip-permissions` | 新增 `bypassPermissions` 到 `Shift+Tab` 模式循環而不立即啟動它。允許您以不同的模式（如 `plan`）開始，稍後切換到 `bypassPermissions`。請參閱 [permission modes](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |68| `--allow-dangerously-skip-permissions` | 將 `bypassPermissions` 新增至 `Shift+Tab` 模式循環而不以它開始。讓您以不同的模式（例如 `plan`）開始，稍後切換至 `bypassPermissions`。請參閱[權限模式](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

69| `--allowedTools`、`--allowed-tools` | 無需提示權限即可執行的工具。請參閱 [permission rule syntax](/docs/zh-TW/settings-reference#permission-rule-syntax) 以了解模式匹配。若要限制可用的工具，請改用 `--tools`。如果您在此命名其中一個 [task-tracking tools](/docs/zh-TW/tools-reference#task-tool-availability)，Claude Code 也會選擇加入工作階段 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |69| `--allowedTools`, `--allowed-tools` | 無需提示權限即可執行的工具。請參閱[權限規則語法](/docs/zh-TW/settings-reference#permission-rule-syntax)以進行模式比對。若要限制可用的工具，請改用 `--tools`。如果您在此命名[任務追蹤工具](/docs/zh-TW/tools-reference#task-tool-availability)之一，Claude Code 也會選擇加入工作階段 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

70| `--append-subagent-system-prompt` | 將自訂文字附加到每個 [subagent](/docs/zh-TW/sub-agents) 系統提示的末尾，包括巢狀 subagents，除了 [forked subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)，其重複使用對話自己的提示。僅適用於使用 `-p` 的非互動模式。需要 Claude Code v2.1.205 或更新版本 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |70| `--append-subagent-system-prompt` | 將自訂文字附加到每個[子代理程式](/docs/zh-TW/sub-agents)的系統提示末尾，包括巢狀子代理程式，除了[分叉的子代理程式](/docs/zh-TW/sub-agents#fork-the-current-conversation)，它會重複使用對話自己的提示。僅在非互動模式下使用 `-p` 時適用。需要 Claude Code v2.1.205 或更新版本 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |

71| `--append-subagent-system-prompt-file` | 從檔案載入文字並將其附加到 [subagent](/docs/zh-TW/sub-agents) 系統提示。`--append-subagent-system-prompt` 的替代方案，適用於太長而無法在命令列上傳遞的文字。這兩個旗標無法結合。僅適用於使用 `-p` 的非互動模式。需要 Claude Code v2.1.261 或更新版本 | `claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query"` |71| `--append-subagent-system-prompt-file` | 從檔案載入文字並將其附加到[子代理程式](/docs/zh-TW/sub-agents)系統提示。作為 `--append-subagent-system-prompt` 的替代方案，用於命令列上過長的文字。這兩個旗標無法結合。僅在非互動模式下使用 `-p` 時適用。需要 Claude Code v2.1.261 或更新版本 | `claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query"` |

74| `--autocompact <auto\|tokens>` | 為此工作階段設定 [auto-compact window](/docs/zh-TW/model-config#set-the-auto-compact-window)，而不變更您儲存的設定。接受與 `/autocompact` 相同的值；該部分涵蓋值形式以及什麼覆蓋旗標。需要 Claude Code v2.1.221 或更新版本 | `claude --autocompact 500k` |74| `--autocompact <auto\|tokens>` | 為此工作階段設定 [auto-compact 視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)而不變更已儲存的設定。接受與 `/autocompact` 相同的值；該部分涵蓋值形式以及覆蓋旗標的內容。需要 Claude Code v2.1.221 或更新版本 | `claude --autocompact 500k` |

75| `--ax-screen-reader` | 呈現螢幕閱讀器友善的輸出：平面文字，無裝飾邊框或動畫。強制使用經典渲染器，因此 [`tui`](/docs/zh-TW/settings-reference#tui) 設定在工作階段中無效；附加的 [background sessions](/docs/zh-TW/agent-view) 仍會全螢幕呈現。優先於 [`CLAUDE_AX_SCREEN_READER`](/docs/zh-TW/env-vars) 和 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 設定。需要 Claude Code v2.1.181 或更新版本 | `claude --ax-screen-reader` |75| `--ax-screen-reader` | 呈現螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。強制使用經典轉譯器，因此 [`tui`](/docs/zh-TW/settings-reference#tui) 設定無效；附加的[背景工作階段](/docs/zh-TW/agent-view)仍會全螢幕呈現。優先於 [`CLAUDE_AX_SCREEN_READER`](/docs/zh-TW/env-vars) 和 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 設定。需要 Claude Code v2.1.181 或更新版本 | `claude --ax-screen-reader` |

76| `--bare` | 最小模式：跳過 hooks、skills、custom commands、subagents、plugins、MCP servers、auto memory 和 CLAUDE.md 的自動探索，以便指令碼呼叫啟動更快。您使用 `--add-dir` 傳遞的目錄中的 Skills 仍會載入。Claude 可以存取 Bash、檔案讀取和檔案編輯工具。設定 [`CLAUDE_CODE_SIMPLE`](/docs/zh-TW/env-vars)。請參閱 [bare mode](/docs/zh-TW/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |76| `--bare` | 最小模式：跳過 hooks、skills、自訂命令、子代理程式、已安裝的 plugins、MCP 伺服器、自動記憶和 CLAUDE.md 的自動探索，以便指令碼呼叫啟動更快。您使用 `--add-dir` 傳遞的目錄中的 Skills 仍會載入。Claude 可以存取 Bash、檔案讀取和檔案編輯工具。設定 [`CLAUDE_CODE_SIMPLE`](/docs/zh-TW/env-vars)。請參閱[裸模式](/docs/zh-TW/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |

78| `--bg`、`--background` | 以 [background agent](/docs/zh-TW/agent-view) 身份啟動工作階段並立即返回。列印工作階段 ID 和管理命令。與 `--exec` 結合以執行 shell 命令作為背景工作而不是 Claude 工作階段，或與 `--agent` 結合以執行特定 subagent。無法與 `-p`/`--print` 結合；請參閱 [error reference](/docs/zh-TW/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |78| `--bg`, `--background` | 將工作階段啟動為[背景代理程式](/docs/zh-TW/agent-view)並立即返回。列印工作階段 ID 和管理命令。與 `--exec` 結合以執行 shell 命令作為背景工作而不是 Claude 工作階段，或與 `--agent` 結合以執行特定的子代理程式。無法與 `-p`/`--print` 結合；請參閱[錯誤參考](/docs/zh-TW/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |

79| `--channels` | （研究預覽）MCP servers，其 [channel](/docs/zh-TW/channels) 通知 Claude 應在此工作階段中監聽。以空格分隔的 `plugin:<name>@<marketplace>` 項目清單。需要透過 claude.ai 或 Console API 金鑰進行 Anthropic 驗證 | `claude --channels plugin:my-notifier@my-marketplace` |79| `--channels` | （研究預覽）Claude 應在此工作階段中監聽其[頻道](/docs/zh-TW/channels)通知的 MCP 伺服器。以空格分隔的 `plugin:<name>@<marketplace>` 項目清單。需要透過 claude.ai 或 Console API 金鑰進行 Anthropic 驗證 | `claude --channels plugin:my-notifier@my-marketplace` |

81| `--cloud` | 使用工作描述在 claude.ai 上建立新的 [cloud session](/docs/zh-TW/claude-code-on-the-web)。使用工作階段 ID（`session_...` 或 `cse_...`）或 claude.ai/code URL，改為使用 `-p` 將訊息佇列到該現有工作階段。請參閱 [send a follow-up message](/docs/zh-TW/claude-code-on-the-web#send-follow-ups-from-the-cli)。 | `claude --cloud "Fix the login bug"` |81| `--cloud` | 使用任務說明，建立新的[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)。使用工作階段 ID（`session_...` 或 `cse_...`）或 claude.ai/code URL，改為使用 `-p` 將訊息排入該現有工作階段。請參閱[傳送後續訊息](/docs/zh-TW/claude-code-on-the-web#send-follow-ups-from-the-cli)。 | `claude --cloud "Fix the login bug"` |

82| `--continue`、`-c` | 載入目前目錄中最近的對話，包括 [已完成的 background session](/docs/zh-TW/sessions#resume-a-session)；開啟已完成的背景工作階段需要 Claude Code v2.1.257 或更新版本。跳過使用 `claude -p` 或 Agent SDK 建立的工作階段，以及第一個提示為 `/loop` 的工作階段。`claude -p --continue` 包括 `-p`、SDK 和 `/loop` 工作階段。包括使用 `/add-dir` 新增此目錄的工作階段 | `claude --continue` |82| `--continue`, `-c` | 載入目前目錄中最近的對話，包括[已完成的背景工作階段](/docs/zh-TW/sessions#resume-a-session)；開啟已完成的背景工作階段需要 Claude Code v2.1.257 或更新版本。跳過使用 `claude -p` 或 Agent SDK 建立的工作階段，以及第一個提示為 `/loop` 的工作階段。`claude -p --continue` 包括 `-p`、SDK 和 `/loop` 工作階段。包括使用 `/add-dir` 新增此目錄的工作階段 | `claude --continue` |

83| `--dangerously-load-development-channels` | 啟用不在核准允許清單上的 [channels](/docs/zh-TW/channels-reference#test-during-the-research-preview)，用於本機開發。接受 `plugin:<name>@<marketplace>` 和 `server:<name>` 項目。提示確認 | `claude --dangerously-load-development-channels server:webhook` |83| `--dangerously-load-development-channels` | 啟用不在核准允許清單上的[頻道](/docs/zh-TW/channels-reference#test-during-the-research-preview)，用於本機開發。接受 `plugin:<name>@<marketplace>` 和 `server:<name>` 項目。提示確認 | `claude --dangerously-load-development-channels server:webhook` |

84| `--dangerously-skip-permissions` | 略過權限提示。等同於 `--permission-mode bypassPermissions`。請參閱 [permission modes](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) 以了解此操作會和不會略過的內容。對於以 `--bg` 啟動的工作階段，該模式 [在監督者重新啟動工作階段時持續](/docs/zh-TW/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |84| `--dangerously-skip-permissions` | 跳過權限提示。等同於 `--permission-mode bypassPermissions`。請參閱[權限模式](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)以了解此操作跳過和不跳過的內容。對於使用 `--bg` 啟動的工作階段，當主管重新啟動工作階段時，模式[會保留](/docs/zh-TW/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |

88| `--disallowedTools`、`--disallowed-tools` | 拒絕規則。裸工具名稱會從 Claude 的內容中移除該工具：`"Edit"` 移除 Edit、`"*"` 移除每個工具，`"mcp__*"` 移除每個 MCP 工具。範圍規則（例如 `Bash(rm *)` ）會保留工具可用，但只拒絕 [如所寫](/docs/zh-TW/permissions#bash-rule-limits)符合的呼叫。命名 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 的規則在任何其他工具保持時無法移除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |88| `--disallowedTools`, `--disallowed-tools` | 拒絕規則。裸工具名稱會從 Claude 的內容中移除相符的工具：`"Edit"` 移除 Edit、`"*"` 移除每個工具，`"mcp__*"` 移除每個 MCP 工具。範圍規則（例如 `Bash(rm *)`）會保留工具可用，並僅拒絕[如所寫](/docs/zh-TW/permissions#bash-rule-limits)相符的呼叫。命名 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 的規則在任何其他工具保持時無法移除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

89| `--effort` | 為目前工作階段設定 [effort level](/docs/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用的層級取決於模型。`ultracode` 以 `xhigh` 努力開始工作階段，並啟用 [ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更新版本。覆蓋此工作階段的 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings) 和 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel) 設定，且不會持久化 | `claude --effort high` |89| `--effort` | 為目前工作階段設定[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用的等級取決於模型。`ultracode` 要求 `xhigh` 努力並[啟用 ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更新版本。覆蓋此工作階段的 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings) 和 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel) 設定，不會保留 | `claude --effort high` |

91| `--environment <environment-id>` | 建立在 [self-hosted environment](/docs/zh-TW/self-hosted-environments) 上執行的新雲端工作階段，具有給定的 ID。環境 ID 以 `ccpool_` 開頭。請參閱 [`--environment` dispatch behavior](/docs/zh-TW/self-hosted-environments-testing#environment-dispatch-behavior) 以了解 dispatch 行為以及它拒絕的旗標組合。需要 Claude Code v2.1.224 或更新版本 | `claude -p "Fix the login bug" --environment ccpool_abc123` |91| `--environment <environment-id>` | 建立在[自託管環境](/docs/zh-TW/self-hosted-environments)上執行的新雲端工作階段，具有給定的 ID。環境 ID 以 `ccpool_` 開頭。請參閱 [`--environment` 分派行為](/docs/zh-TW/self-hosted-environments-testing#environment-dispatch-behavior)以了解分派行為和它拒絕的旗標組合。需要 Claude Code v2.1.224 或更新版本 | `claude -p "Fix the login bug" --environment ccpool_abc123` |

92| `--exclude-dynamic-system-prompt-sections` | 將每台機器的系統提示部分（工作目錄、環境資訊、記憶體路徑、git-repo 旗標）移至第一個使用者訊息。改善在執行相同工作的不同使用者和機器之間的提示快取重複使用。僅適用於預設系統提示；設定 `--system-prompt` 或 `--system-prompt-file` 時忽略。與 `-p` 搭配使用以進行指令碼化、多使用者工作負載 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |92| `--exclude-dynamic-system-prompt-sections` | 將每台機器的部分從系統提示（工作目錄、環境資訊、記憶路徑、git-repo 旗標）移至第一個使用者訊息。改善在不同使用者和執行相同任務的機器上的提示快取重複使用。僅適用於預設系統提示；當設定 `--system-prompt` 或 `--system-prompt-file` 時忽略。與 `-p` 搭配使用以進行指令碼化、多使用者工作負載 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

94| `--fallback-model` | 當主要模型過載或無法使用時啟用自動回退到指定的模型，例如已淘汰的模型。接受以逗號分隔的清單，依序嘗試。請參閱 [Fallback model chains](/docs/zh-TW/model-config#fallback-model-chains)。若要在工作階段之間持久化鏈，請使用 [`fallbackModel` 設定](/docs/zh-TW/settings-reference#fallbackmodel)，此旗標會覆蓋它 | `claude --fallback-model sonnet,haiku` |94| `--fallback-model` | 當主要模型過載或無法使用時（例如已淘汰的模型），啟用自動回退到指定的模型。接受按順序嘗試的逗號分隔清單。請參閱[回退模型鏈](/docs/zh-TW/model-config#fallback-model-chains)。若要在工作階段之間保留鏈，請使用 [`fallbackModel` 設定](/docs/zh-TW/settings-reference#fallbackmodel)，此旗標會覆蓋它 | `claude --fallback-model sonnet,haiku` |

96| `--forward-subagent-text` | 在輸出串流中發出 [subagent](/docs/zh-TW/sub-agents) 文字和思考區塊作為 `assistant` 和 `user` 訊息，並設定 `parent_tool_use_id`，以便您可以重建每個 subagent 的文字記錄。沒有此旗標，Claude Code 會省略在 [foreground](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 中執行的 subagent 的文字和思考區塊。需要 `--print` 和 `--output-format stream-json`。Claude Code 也會轉發來自 [nested subagents](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) 的訊息，將 `parent_tool_use_id` 設定為產生每個訊息的 Agent 或 Skill 工具呼叫的 ID；這需要 Claude Code v2.1.219 或更新版本，且 forked skill 產生的 subagents 訊息以及巢狀 forked skills 的訊息需要 v2.1.275 或更新版本。[`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-TW/env-vars) 環境變數啟用相同的行為。需要 Claude Code v2.1.211 或更新版本 | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |96| `--forward-subagent-text` | 在輸出串流中發出[子代理程式](/docs/zh-TW/sub-agents)文字和思考區塊作為 `assistant` 和 `user` 訊息，並設定 `parent_tool_use_id`，以便您可以重建每個子代理程式的文字記錄。沒有此旗標，Claude Code 會省略在[前景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)中執行的子代理程式的文字和思考區塊。需要 `--print` 和 `--output-format stream-json`。Claude Code 也會轉發來自[巢狀子代理程式](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)的訊息，將 `parent_tool_use_id` 設定為啟動每個子代理程式的 Agent 或 Skill 工具呼叫的 ID；這需要 Claude Code v2.1.219 或更新版本，分叉的 skill 產生的子代理程式訊息以及巢狀分叉 skills 的訊息需要 v2.1.275 或更新版本。[`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-TW/env-vars) 環境變數啟用相同的行為。需要 Claude Code v2.1.211 或更新版本 | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |

97| `--from-pr` | 開啟工作階段選擇器，篩選為連結到特定提取請求的工作階段。接受 PR 編號、GitHub 或 GitHub Enterprise PR URL、GitLab 合併請求 URL 或 Bitbucket 提取請求 URL。當 Claude 建立提取請求時，工作階段會自動連結 | `claude --from-pr 123` |97| `--from-pr` | 開啟工作階段選擇器，篩選至連結到特定提取要求的工作階段。接受 PR 編號、GitHub 或 GitHub Enterprise PR URL、GitLab 合併要求 URL 或 Bitbucket 提取要求 URL。當 Claude 建立提取要求時，工作階段會自動連結 | `claude --from-pr 123` |

98| `--ide` | 如果恰好有一個有效的 IDE 可用，在啟動時自動連線到 IDE | `claude --ide` |98| `--ide` | 如果恰好有一個有效的 IDE 可用，在啟動時自動連線到 IDE | `claude --ide` |

101| `--include-hook-events` | 在輸出串流中包含 hook 生命週期事件。`SessionStart` 和 `Setup` hook 事件始終包含，不需要此旗標。某些 hook 事件（例如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`）永遠不會產生 `hook_started` 事件，即使使用此旗標也是如此。對於這些事件，Claude Code 仍會在執行超過一秒的命令 hook 產生輸出時發出 `hook_progress`，並且僅在 [在背景執行的 hook](/docs/zh-TW/hooks#run-hooks-in-the-background) 完成時發出 `hook_response`。需要 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-hook-events "query"` |101| `--include-hook-events` | 在輸出串流中包含 hook 生命週期事件。`SessionStart` 和 `Setup` hook 事件始終包含，不需要此旗標。某些 hook 事件（例如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`）永遠不會產生 `hook_started` 事件，即使使用此旗標也是如此。對於這些事件，Claude Code 仍會在執行超過一秒的命令 hook 產生輸出時發出 `hook_progress`，並僅在[在背景執行的 hook](/docs/zh-TW/hooks#run-hooks-in-the-background)完成時發出 `hook_response`。需要 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-hook-events "query"` |

102| `--include-partial-messages` | 在輸出中包含部分串流事件。需要 `--print` 和 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |102| `--include-partial-messages` | 在輸出中包含部分串流事件。需要 `--print` 和 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |

104| `--json-schema` | 在代理程式完成其工作流程後取得符合 JSON Schema 的驗證 JSON 輸出（僅列印模式）。請參閱 [structured outputs](/docs/zh-TW/agent-sdk/structured-outputs)。Claude Code 在無效的 schema 上以錯誤退出，並接受 `format` 關鍵字作為註解而不進行用戶端驗證 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |104| `--json-schema` | 在代理程式完成其工作流程後取得符合 JSON Schema 的驗證 JSON 輸出（僅列印模式）。請參閱[結構化輸出](/docs/zh-TW/agent-sdk/structured-outputs)。Claude Code 在無效的 schema 上結束並接受 `format` 關鍵字作為註釋而不進行用戶端驗證 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

106| `--max-budget-usd` | 在停止前在 API 呼叫上花費的最大美元金額（僅列印模式）。來自 [subagents](/docs/zh-TW/sub-agents) 的支出計入上限。當您使用 `--continue` 或 `--resume` 返回對話時，[從較早執行復原](/docs/zh-TW/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)的總計不計入它。一旦支出達到上限，產生另一個 subagent 會失敗，並出現 `Budget limit reached`，Claude Code 會停止仍在執行的背景 subagents；上限強制行為需要 Claude Code v2.1.217 或更新版本 | `claude -p --max-budget-usd 5.00 "query"` |106| `--max-budget-usd` | 在停止前在 API 呼叫上花費的最大美元金額（僅列印模式）。來自[子代理程式](/docs/zh-TW/sub-agents)的支出計入上限。當您使用 `--continue` 或 `--resume` 返回對話時，[從較早的執行恢復](/docs/zh-TW/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)的總計不計入它。一旦支出達到上限，產生另一個子代理程式會失敗，出現 `Budget limit reached`，Claude Code 會停止仍在執行的背景子代理程式；上限強制行為需要 Claude Code v2.1.217 或更新版本 | `claude -p --max-budget-usd 5.00 "query"` |

108| `--mcp-config` | 從 JSON 檔案或字串載入 MCP servers（以空格分隔）。當您使用 `-p` 傳遞此旗標時，Claude Code 會等待仍待連線的伺服器連線，最多等待 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒），然後執行第一個轉數；具有 [cached tool list](/docs/zh-TW/mcp#managing-your-servers) 的伺服器會跳過等待並在首次使用時連線。等待需要 Claude Code v2.1.221 或更新版本 | `claude --mcp-config ./mcp.json` |108| `--mcp-config` | 從 JSON 檔案或字串載入 MCP 伺服器（以空格分隔）。當您使用 `-p` 傳遞此旗標時，Claude Code 會等待仍在擱置的伺服器連線，直到 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒）；具有[快取工具清單](/docs/zh-TW/mcp#managing-your-servers)的伺服器會跳過等待並在首次使用時連線。等待需要 Claude Code v2.1.221 或更新版本 | `claude --mcp-config ./mcp.json` |

109| `--model` | 使用 [model alias](/docs/zh-TW/model-config#model-aliases)（例如 `sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名稱為目前工作階段設定模型。覆蓋 [`model`](/docs/zh-TW/settings-reference#model) 設定和 [`ANTHROPIC_MODEL`](/docs/zh-TW/model-config#environment-variables) | `claude --model claude-sonnet-5` |109| `--model` | 使用[模型別名](/docs/zh-TW/model-config#model-aliases)（例如 `sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名稱為目前工作階段設定模型。覆蓋 [`model`](/docs/zh-TW/settings-reference#model) 設定和 [`ANTHROPIC_MODEL`](/docs/zh-TW/model-config#environment-variables) | `claude --model claude-sonnet-5` |

110| `--name`、`-n` | 為工作階段設定顯示名稱，顯示在 `/resume` 和終端標題中。您可以使用 `claude --resume <name>` 繼續已命名的工作階段。在互動式工作階段中，如果此機器上的另一個即時工作階段已使用該名稱，Claude Code 會應用 [其變體](/docs/zh-TW/sessions#name-your-sessions)。<br /><br />[`/rename`](/docs/zh-TW/commands) 在工作階段中途變更名稱，也會在提示列中顯示 | `claude -n "my-feature-work"` |110| `--name`, `-n` | 為工作階段設定顯示名稱，顯示在 `/resume` 和終端機標題中。您可以使用 `claude --resume <name>` 恢復命名的工作階段。在互動工作階段中，如果此機器上的另一個即時工作階段已使用該名稱，Claude Code 會改為套用[它的變體](/docs/zh-TW/sessions#name-your-sessions)。<br /><br />[`/rename`](/docs/zh-TW/commands)在工作階段中期變更名稱，也會在提示列上顯示它 | `claude -n "my-feature-work"` |

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

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

115| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式下處理權限提示。Claude Code 會等待該工具的 MCP 伺服器連線，最多等待 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒），然後執行第一個轉數。<br /><br />提示工具無法核准標記為 [requiring user interaction](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具：Claude Code 會將其 `allow` 結果轉換為拒絕。此限制需要 Claude Code v2.1.199 或更新版本 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |115| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式中處理權限提示。Claude Code 會等待該工具的 MCP 伺服器連線，直到 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒）。<br /><br />提示工具無法核准標記為[需要使用者互動](/docs/zh-TW/mcp#require-approval-for-a-specific-tool)的 MCP 工具：Claude Code 會將其 `allow` 結果轉換為拒絕。此限制需要 Claude Code v2.1.199 或更新版本 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

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

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

120| `--prompt-suggestions` | 在每個產生提示建議的轉數後發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示；非常短的對話可能不會產生任何提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。請參閱 [Prompt suggestions](/docs/zh-TW/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |120| `--prompt-suggestions` | 在產生提示建議的每個轉後發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示；非常短的對話可能不會產生任何提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。請參閱[提示建議](/docs/zh-TW/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

123| `--remote-control`、`--rc` | 啟動互動式工作階段，並啟用 [Remote Control](/docs/zh-TW/remote-control#start-a-remote-control-session)，以便您也可以從 claude.ai 或 Claude 應用程式控制它。可選擇傳遞工作階段的名稱 | `claude --remote-control "My Project"` |123| `--remote-control`, `--rc` | 啟動互動工作階段，並啟用[遠端控制](/docs/zh-TW/remote-control#start-a-remote-control-session)，以便您也可以從 claude.ai 或 Claude 應用程式控制它。可選擇傳遞工作階段的名稱 | `claude --remote-control "My Project"` |

124| `--remote-control-session-name-prefix <prefix>` | [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴，當未設定明確名稱時自動產生。預設為您的機器主機名稱，產生如 `myhost-graceful-unicorn` 的名稱。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以獲得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |124| `--remote-control-session-name-prefix <prefix>` | 當未設定明確名稱時，[遠端控制](/docs/zh-TW/remote-control)自動產生工作階段名稱的前置詞。預設為您機器的主機名稱，產生名稱如 `myhost-graceful-unicorn`。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以取得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |

125| `--replay-user-messages` | 從 stdin 重新發出使用者訊息回到 stdout 以進行確認。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |125| `--replay-user-messages` | 從 stdin 重新發出使用者訊息回到 stdout 以進行確認。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

126| `--restricted` | 以受限模式啟動。當評估工具在共享機器上驅動 `claude` 且 Claude Code 不得執行命令或讀取該機器的使用者和專案設定時使用。Claude Code 會移除執行命令或程式碼的內建工具和 WebFetch，除非您在 `--tools` 中個別命名它們，而不是透過 `default` 預設。它也會將內建檔案工具限制在 [working directories](/docs/zh-TW/permissions#working-directories)，僅載入 [managed settings](/docs/zh-TW/managed-settings) 和 `--settings`，拒絕 [`bypassPermissions`](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，並 [拒絕從受限工作階段建立雲端工作階段](/docs/zh-TW/errors#cloud-sessions-cannot-be-created-from-a-restricted-session)。需要 Claude Code v2.1.248 或更新版本 | `claude --restricted -p "query"` |126| `--restricted` | 以受限模式啟動。當評估工具在共用機器上驅動 `claude` 且 Claude Code 不得執行命令或讀取該機器的使用者和專案設定時使用。Claude Code 會移除執行命令或程式碼的內建工具以及 WebFetch，除非您在 `--tools` 中個別命名它們，而不是透過 `default` 預設集。它也會將內建檔案工具限制在[工作目錄](/docs/zh-TW/permissions#working-directories)、僅載入[受管設定](/docs/zh-TW/managed-settings)和 `--settings`、拒絕 [`bypassPermissions`](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，以及[拒絕從受限工作階段建立雲端工作階段](/docs/zh-TW/errors#cloud-sessions-cannot-be-created-from-a-restricted-session)。需要 Claude Code v2.1.248 或更新版本 | `claude --restricted -p "query"` |

127| `--resume`、`-r` | 按 ID 或名稱繼續特定工作階段，或顯示互動式選擇器以選擇工作階段。代替 ID，您可以傳遞工作階段 `.jsonl` [transcript file](/docs/zh-TW/sessions#where-transcripts-are-stored) 的絕對路徑。選擇器和名稱搜尋包括使用 `/add-dir` 新增此目錄的工作階段。當您傳遞工作階段 ID 時，Claude Code 會搜尋目前專案目錄及其 git worktrees，然後搜尋此機器上的所有其他專案。在 v2.1.223 之前，ID 搜尋僅涵蓋目前專案目錄及其 git worktrees。[Background sessions](/docs/zh-TW/agent-view) 在選擇器中出現，標記為 `bg` | `claude --resume auth-refactor` |127| `--resume`, `-r` | 按 ID 或名稱恢復特定工作階段，或顯示互動選擇器以選擇工作階段。代替 ID，您可以傳遞工作階段 `.jsonl` [文字記錄檔](/docs/zh-TW/sessions#where-transcripts-are-stored)的絕對路徑。選擇器和名稱搜尋包括使用 `/add-dir` 新增此目錄的工作階段。當您傳遞工作階段 ID 時，Claude Code 會搜尋目前專案目錄及其 git worktrees，然後搜尋此機器上的所有其他專案。在 v2.1.223 之前，ID 搜尋僅涵蓋目前專案目錄及其 git worktrees。[背景工作階段](/docs/zh-TW/agent-view)在選擇器中顯示，標記為 `bg` | `claude --resume auth-refactor` |

128| `--safe-mode` | 以所有自訂項目停用的狀態啟動以排除故障的設定：CLAUDE.md、skills、plugins、hooks、MCP servers、custom commands 和 agents、output styles、workflows、custom themes、custom keybindings、status line 和 file-suggestion commands、LSP servers 和 auto memory 不會載入。驗證、模型選擇、內建工具和權限正常運作，這與 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) 不同。受管設定原則仍然適用，包括原則設定的 hooks、status line 和 file-suggestion commands；受管 plugins、受管 skills、受管 CLAUDE.md 和原則設定的 MCP servers 不會。用於檢查自訂項目是否觸發 [automatic model fallback](/docs/zh-TW/model-config#automatic-model-fallback)。設定 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-TW/env-vars) | `claude --safe-mode` |128| `--safe-mode` | 以所有自訂停用開始以疑難排解損壞的設定：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理程式、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態列和檔案建議命令、LSP 伺服器和自動記憶不會載入。驗證、模型選擇、內建工具和權限正常運作，這與 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) 不同。受管設定原則仍適用，包括原則設定的 hooks、狀態列和檔案建議命令；受管 plugins、受管 skills、受管 CLAUDE.md 和原則設定的 MCP 伺服器不適用。用於檢查自訂是否觸發[自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)。設定 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-TW/env-vars) | `claude --safe-mode` |

131| `--settings` | 設定 JSON 檔案的路徑或內嵌 JSON 字串。您在此設定的值會覆蓋此工作階段中 `settings.json` 檔案中的相同金鑰。您省略的金鑰保留其檔案型值。檔案必須是不超過 2 MiB 的一般檔案。請參閱 [settings precedence](/docs/zh-TW/settings#settings-precedence) | `claude --settings ./settings.json` |131| `--settings` | 設定 JSON 檔案或內嵌 JSON 字串的路徑。您在此設定的值會覆蓋此工作階段的 `settings.json` 檔案中的相同金鑰。您省略的金鑰會保留其檔案型值。檔案必須是不超過 2 MiB 的一般檔案。請參閱[設定優先順序](/docs/zh-TW/settings#settings-precedence) | `claude --settings ./settings.json` |

132| `--strict-mcp-config` | 僅使用 `--mcp-config` 中的 MCP servers，忽略所有其他 MCP 設定。請參閱 [Exclusive control with managed-mcp.json](/docs/zh-TW/managed-mcp#exclusive-control-with-managed-mcp-json) 以了解旗標在受管 MCP 檔案下執行的操作 | `claude --strict-mcp-config --mcp-config ./mcp.json` |132| `--strict-mcp-config` | 僅使用 `--mcp-config` 中的 MCP 伺服器，忽略所有其他 MCP 設定。請參閱[使用 managed-mcp.json 進行獨佔控制](/docs/zh-TW/managed-mcp#exclusive-control-with-managed-mcp-json)以了解旗標在受管 MCP 檔案下執行的操作 | `claude --strict-mcp-config --mcp-config ./mcp.json` |

135| `--system-prompt-snapshot` | 傳遞 `off` 以在每個請求上重建系統提示，而不是重複使用 [在對話的第一個請求上記錄](#system-prompt-flags-in-resumed-conversations)的提示，例如當您在 `--continue` 執行中反覆進行 `--append-system-prompt` 文字時。需要 Claude Code v2.1.257 或更新版本 | `claude --system-prompt-snapshot off` |135| `--system-prompt-snapshot` | 傳遞 `off` 以在每個要求上重建系統提示，而不是重複使用[在對話的第一個要求上記錄](#system-prompt-flags-in-resumed-conversations)的提示，例如在您跨 `--continue` 執行反覆運算 `--append-system-prompt` 文字時。需要 Claude Code v2.1.257 或更新版本 | `claude --system-prompt-snapshot off` |

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

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

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

143 143

144<h3 id="system-prompt-flags">144<h3 id="system-prompt-flags">

145 系統提示旗標145 系統提示旗標

148Claude Code 提供五個旗標用於自訂系統提示。四個設定其文字，使用 `--system-prompt-snapshot` 您可以控制對話是否保留它開始時的文字。所有五個都在互動和非互動模式中運作。148Claude Code 提供五個旗標用於自訂系統提示。四個設定其文字，使用 `--system-prompt-snapshot` 您可以控制對話是否保留它開始時的文字。所有五個都在互動和非互動模式中運作。

149 149

150| 旗標 | 行為 | 範例 |150| 旗標 | 行為 | 範例 |

151| :---------------------------- | :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |151| :---------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |

156| `--system-prompt-snapshot` | 使用 `off`，在每個請求上重建提示。使用 `on`（預設），在[記錄適用](#system-prompt-flags-in-resumed-conversations)的情況下重複使用已記錄的提示 | `claude --append-system-prompt "Draft rules" --system-prompt-snapshot off` |156| `--system-prompt-snapshot` | 使用 `off`，在每個要求上重建提示。使用 `on`（預設），重複使用[記錄適用](#system-prompt-flags-in-resumed-conversations)的記錄提示 | `claude --append-system-prompt "Draft rules" --system-prompt-snapshot off` |

157 157

158`--system-prompt` 和 `--system-prompt-file` 互斥。附加旗標可以與任一取代旗標組合。158`--system-prompt` 和 `--system-prompt-file` 互斥。附加旗標可與任一取代旗標結合。

159 159

160當取代文字結合每次執行都相同的指示與每次執行都變更的內容時，在指示和內容之間新增僅包含 `__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__` 的一行。Claude Code 在第一個這樣的行處分割提示並移除該行，因此上面的部分保持快取而下面的部分變更。需要 Claude Code v2.1.275 或更新版本。[Cache the static part of a custom prompt](/docs/zh-TW/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt) 列出分割適用的設定。160當取代文字結合每次執行相同的指示與每次執行變更的內容時，在指示和內容之間新增僅包含 `__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__` 的行。Claude Code 在第一個這樣的行分割提示並移除該行，因此上面的部分保持快取而下面的部分變更。需要 Claude Code v2.1.275 或更新版本。[快取自訂提示的靜態部分](/docs/zh-TW/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)列出分割適用的設定。

161 161

162根據 Claude Code 的預設身份是否仍適合您的工作來選擇。當 Claude 應保持編碼助手身份並同時遵循您的額外規則時，請使用附加旗標：每次呼叫的指示、輸出格式或 `-p` 指令碼的領域內容。附加會保留預設工具指導、安全指示和編碼慣例，因此您只需提供不同的部分。當表面、身份或權限模型與 Claude Code 不同時，請使用取代旗標，例如管道中沒有人監看的非編碼代理程式。取代會移除整個預設提示，包括工具指導和安全指示，因此您需要負責您的工作仍然需要的任何內容。162根據 Claude Code 的預設身份是否仍適合您的任務進行選擇。當 Claude 應保持編碼助手並也遵循您的額外規則時使用附加旗標：每次呼叫指示、輸出格式或 `-p` 指令碼的網域內容。附加保留預設工具指導、安全指示和編碼慣例，因此您只需提供不同的部分。當表面、身份或權限模型與 Claude Code 的不同時使用取代旗標，例如管道中沒有人類監視的非編碼代理程式。取代會移除整個預設提示，包括工具指導和安全指示，因此您負責您的任務仍需要的任何內容。

163 163

164對於您可以在專案中切換和共享的持久人物，請使用 [output styles](/docs/zh-TW/output-styles)。對於 Claude 應始終遵循的專案慣例，請使用 [CLAUDE.md](/docs/zh-TW/memory)。[Agent SDK guide on system prompts](/docs/zh-TW/agent-sdk/modifying-system-prompts#decide-on-a-starting-point) 涵蓋了更深入的相同決策。164對於您可以在專案之間切換和共用的持續人物，請使用[輸出樣式](/docs/zh-TW/output-styles)。對於專案慣例 Claude 應始終遵循，請使用 [CLAUDE.md](/docs/zh-TW/memory)。[Agent SDK 系統提示指南](/docs/zh-TW/agent-sdk/modifying-system-prompts#decide-on-a-starting-point)涵蓋更深入的相同決定。

165 165

166<h4 id="system-prompt-flags-in-resumed-conversations">166<h4 id="system-prompt-flags-in-resumed-conversations">

167 已繼續對話中的系統提示旗標167 恢復對話中的系統提示旗標

168</h4>168</h4>

169 169

170預設情況下，Claude Code 在對話的第一個請求上建立系統提示一次，應用任何系統提示旗標中的文字，並在工作階段中記錄它。在對話被壓縮之前，每個稍後的請求都會使用該記錄的提示，包括在您使用 `--resume` 或 `--continue` 返回對話後。如果您在該稍後的啟動上傳遞不同的系統提示旗標文字或沒有，它會在對話被壓縮或您啟動新對話時生效。170預設情況下，Claude Code 在對話的第一個要求上建立系統提示一次，應用任何系統提示旗標中的文字，並在工作階段中記錄它。在對話被壓縮之前，每個稍後的要求都使用該記錄的提示，包括在您使用 `--resume` 或 `--continue` 返回對話後。如果您在該稍後的啟動上傳遞不同的系統提示旗標文字或無，它會在對話被壓縮或您啟動新對話時生效。

171 171

172在 [cloud sessions](/docs/zh-TW/cloud-environments) 之外，如果您以 [bare mode](/docs/zh-TW/headless#start-faster-with-bare-mode) 啟動 Claude Code，透過傳遞 `--bare` 或設定 `CLAUDE_CODE_SIMPLE=1`，記錄會保持關閉，除非您傳遞 `--system-prompt-snapshot on`。在 v2.1.268 之前，不 [fetch feature flags](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching) 的工作階段（包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的工作階段）在每個請求上重建提示，`--system-prompt-snapshot` 無效。172在[雲端工作階段](/docs/zh-TW/cloud-environments)之外，如果您透過傳遞 `--bare` 或設定 `CLAUDE_CODE_SIMPLE=1` 在[裸模式](/docs/zh-TW/headless#start-faster-with-bare-mode)中啟動 Claude Code，記錄會保持關閉，除非您傳遞 `--system-prompt-snapshot on`。在 v2.1.268 之前，不[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的工作階段，在每個要求上重建提示，`--system-prompt-snapshot` 無效。

173 173

174若要改為在每個請求上重建提示，例如當您在 `--continue` 執行中反覆進行其措辭時，請傳遞 `--system-prompt-snapshot off`。在 v2.1.265 之前，傳遞任何系統提示旗標也會關閉記錄，除非您傳遞 `--system-prompt-snapshot on`。174若要改為在每個要求上重建提示，例如在您跨 `--continue` 執行反覆運算其措辭時，傳遞 `--system-prompt-snapshot off`。在 v2.1.265 之前，傳遞任何系統提示旗標也會關閉記錄，除非您傳遞 `--system-prompt-snapshot on`。

175 175

176<h2 id="see-also">176<h2 id="see-also">

177 另請參閱177 另請參閱

cloud-environments.md +2 −2

Details

301| 您的儲存庫的 `.claude/rules/` | 是 | 複製的一部分 |301| 您的儲存庫的 `.claude/rules/` | 是 | 複製的一部分 |

302| 您的儲存庫的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 複製的一部分 |302| 您的儲存庫的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 複製的一部分 |

303| 在您的儲存庫的 `.claude/settings.json` 中宣告的 Plugins 和 marketplaces | 否 | 雲端工作階段不會安裝儲存庫在 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 下開啟的 plugins，包括來自它在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 下列出的 marketplaces 的 plugins。改為為您的 claude.ai 帳戶啟用 plugin，以便 Claude Code 將其載入為 [synced plugin](/docs/zh-TW/plugins-reference#synced-plugins) |303| 在您的儲存庫的 `.claude/settings.json` 中宣告的 Plugins 和 marketplaces | 否 | 雲端工作階段不會安裝儲存庫在 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 下開啟的 plugins，包括來自它在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 下列出的 marketplaces 的 plugins |

304| 您組織的 [伺服器管理的設定](/docs/zh-TW/server-managed-settings) | 是 | 在工作階段啟動時從 Anthropic 的伺服器擷取。請參閱 [Surface coverage](/docs/zh-TW/model-config#surface-coverage) 以了解 `availableModels` 在雲端工作階段中如何強制執行。透過 MDM 或管理設定檔部署到您的裝置的設定不適用，因為工作階段在 Anthropic 管理的 VM 上執行；在 [自託管環境](/docs/zh-TW/self-hosted-environments) 中，工作階段也會讀取執行器映像中的管理設定檔，根據 [Claude Code 如何結合管理來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources) |304| 您組織的 [伺服器管理的設定](/docs/zh-TW/server-managed-settings) | 是 | 在工作階段啟動時從 Anthropic 的伺服器擷取。請參閱 [Surface coverage](/docs/zh-TW/model-config#surface-coverage) 以了解 `availableModels` 在雲端工作階段中如何強制執行。透過 MDM 或管理設定檔部署到您的裝置的設定不適用，因為工作階段在 Anthropic 管理的 VM 上執行；在 [自託管環境](/docs/zh-TW/self-hosted-environments) 中，工作階段也會讀取執行器映像中的管理設定檔，根據 [Claude Code 如何結合管理來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources) |

305| 您的使用者 `~/.claude/CLAUDE.md` | 否 | 位於您的機器上，不在儲存庫中 |305| 您的使用者 `~/.claude/CLAUDE.md` | 否 | 位於您的機器上，不在儲存庫中 |

306| 您的使用者 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位於您的機器上，不在儲存庫中。改為將它們提交到儲存庫的 `.claude/` 目錄。雲端工作階段會自動載入您在 claude.ai 上啟用的技能 |306| 您的使用者 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位於您的機器上，不在儲存庫中。改為將它們提交到儲存庫的 `.claude/` 目錄。雲端工作階段會自動載入您在 claude.ai 上啟用的技能 |

307| 僅在您的使用者設定中啟用的 Plugins | 否 | 使用者範圍的 `enabledPlugins` 位於 `~/.claude/settings.json` 在您的機器上。改為為您的 claude.ai 帳戶啟用 plugin，以便 Claude Code 將其載入為 [synced plugins](/docs/zh-TW/plugins-reference#synced-plugins) |307| 僅在您的使用者設定中啟用的 Plugins | 否 | 使用者範圍的 `enabledPlugins` 位於 `~/.claude/settings.json` 在您的機器上 |

308| 您使用 `claude mcp add` 在預設本機範圍或使用者範圍新增的 MCP 伺服器 | 否 | 這些寫入您機器上的 `~/.claude.json`，不是儲存庫。使用 `claude mcp add --scope project` 新增伺服器，該伺服器寫入儲存庫的 [`.mcp.json`](/docs/zh-TW/mcp#project-scope)，並提交該檔案。具有一個儲存庫的工作階段會載入它 |308| 您使用 `claude mcp add` 在預設本機範圍或使用者範圍新增的 MCP 伺服器 | 否 | 這些寫入您機器上的 `~/.claude.json`，不是儲存庫。使用 `claude mcp add --scope project` 新增伺服器，該伺服器寫入儲存庫的 [`.mcp.json`](/docs/zh-TW/mcp#project-scope)，並提交該檔案。具有一個儲存庫的工作階段會載入它 |

309| 您的儲存庫的 `.claude/settings.json` `env` 區塊中的傳輸變數，例如 `NODE_EXTRA_CA_CERTS` 和 [mTLS 用戶端憑證變數](/docs/zh-TW/network-config#mtls-authentication) | 否 | 託管環境管理工作階段的 API 連接，因此 Claude Code 忽略這些金鑰，並在工作階段的偵錯日誌中記錄每個忽略的金鑰 |309| 您的儲存庫的 `.claude/settings.json` `env` 區塊中的傳輸變數，例如 `NODE_EXTRA_CA_CERTS` 和 [mTLS 用戶端憑證變數](/docs/zh-TW/network-config#mtls-authentication) | 否 | 託管環境管理工作階段的 API 連接，因此 Claude Code 忽略這些金鑰，並在工作階段的偵錯日誌中記錄每個忽略的金鑰 |

310| Claude 呼叫的服務的 API 金鑰和令牌 | 在 Pro 和 Max 方案上，作為 [API 認證](#add-api-credentials) | 您在環境上新增金鑰一次，代理程式代理會將其附加到您列出的主機的請求。代理程式代理 [無法附加](#requests-that-never-get-the-credential) 的金鑰，或任何 Team 或 Enterprise 方案上的金鑰，保留在環境變數中 |310| Claude 呼叫的服務的 API 金鑰和令牌 | 在 Pro 和 Max 方案上，作為 [API 認證](#add-api-credentials) | 您在環境上新增金鑰一次，代理程式代理會將其附加到您列出的主機的請求。代理程式代理 [無法附加](#requests-that-never-get-the-credential) 的金鑰，或任何 Team 或 Enterprise 方案上的金鑰，保留在環境變數中 |

commands.md +4 −4

Details

61| `/autocompact [auto\|<tokens>]` | 設定自動壓縮視窗：在 Claude Code 自動壓縮之前上下文視窗有多滿。傳遞大小（例如 `500k`）或 `auto` 以返回為您的模型調整的視窗。Claude Code 將該值保存到使用者設定並將其應用於目前工作階段。有關接受的值以及覆蓋它的內容，請參閱[設定自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)。沒有引數時，打開顯示目前視窗的對話框。需要 Claude Code v2.1.221 或更新版本 |61| `/autocompact [auto\|<tokens>]` | 設定自動壓縮視窗：在 Claude Code 自動壓縮之前上下文視窗有多滿。傳遞大小（例如 `500k`）或 `auto` 以返回為您的模型調整的視窗。Claude Code 將該值保存到使用者設定並將其應用於目前工作階段。有關接受的值以及覆蓋它的內容，請參閱[設定自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)。沒有引數時，打開顯示目前視窗的對話框。需要 Claude Code v2.1.221 或更新版本 |

62| `/autofix-pr [prompt]` | 生成一個[雲端工作階段](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)，監視目前分支的 PR 並在 CI 失敗或審查者留下評論時推送修復。使用 `gh pr view` 從您簽出的分支檢測打開的 PR；要監視不同的 PR，請先簽出其分支。預設情況下，雲端工作階段被告知修復每個 CI 失敗和審查評論；傳遞提示詞以給它不同的指示，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)的存取 |62| `/autofix-pr [prompt]` | 生成一個[雲端工作階段](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)，監視目前分支的 PR 並在 CI 失敗或審查者留下評論時推送修復。使用 `gh pr view` 從您簽出的分支檢測打開的 PR；要監視不同的 PR，請先簽出其分支。預設情況下，雲端工作階段被告知修復每個 CI 失敗和審查評論；傳遞提示詞以給它不同的指示，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)的存取 |

63| `/background [prompt]` | 分離目前工作階段以作為[背景代理](/docs/zh-TW/agent-view)運行並釋放此終端。傳遞提示詞以在分離前發送一個進一步的指示。使用 `claude agents` 監視工作階段。要將對話複製到新的背景工作階段，同時此工作階段保持運行，請使用 `/fork`。別名：`/bg` |63| `/background [prompt]` | 分離目前工作階段以作為[背景代理](/docs/zh-TW/agent-view)運行並釋放此終端。傳遞提示詞以在分離前發送一個進一步的指示。使用 `claude agents` 監視工作階段。要將對話複製到新的背景工作階段，同時此工作階段保持運行，請使用 `/fork`。別名：`/bg` |

64| `/batch <instruction>` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 跨程式碼庫並行協調大規模變更。研究程式碼庫，將工作分解為 5 到 30 個獨立單位，並呈現計畫。獲得批准後，在隔離的 [git worktree](/docs/zh-TW/worktrees) 中為每個單位生成一個[背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)。每個子代理實現其單位、運行測試並打開拉取請求。需要 git 儲存庫。範例：`/batch migrate src/ from JavaScript to TypeScript` |64| `/batch <instruction>` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 跨程式碼庫並行協調大規模變更。研究程式碼庫，將工作分解為 5 到 30 個獨立單位，並呈現計畫。獲得批准後，在隔離的 [worktree](/docs/zh-TW/worktrees) 中為每個單位生成一個[背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)。每個子代理實現其單位、運行測試並發佈其變更。需要 git 儲存庫或建立 worktrees 的 [`WorktreeCreate` hook](/docs/zh-TW/worktrees#non-git-version-control)。在 git 儲存庫外，`/batch` 需要 Claude Code v2.1.281 或更新版本。範例：`/batch migrate src/ from JavaScript to TypeScript` |

65| `/branch [name]` | 在此點建立目前對話的分支，以便您可以嘗試不同的方向而不會丟失目前的對話。切換到分支並保留原始分支，您可以使用 `/resume` 返回。要運行副本作為單獨的[背景工作階段](/docs/zh-TW/agent-view)而不是切換到它，請使用 `/fork`；要將側面任務交給[子代理](/docs/zh-TW/sub-agents)以報告回此對話，請使用 `/subtask` |65| `/branch [name]` | 在此點建立目前對話的分支，以便您可以嘗試不同的方向而不會丟失目前的對話。切換到分支並保留原始分支，您可以使用 `/resume` 返回。要運行副本作為單獨的[背景工作階段](/docs/zh-TW/agent-view)而不是切換到它，請使用 `/fork`；要將側面任務交給[子代理](/docs/zh-TW/sub-agents)以報告回此對話，請使用 `/subtask` |

66| `/btw [question]` | 詢問有關目前工作階段的[側面問題](/docs/zh-TW/interactive-mode#side-questions-with-%2Fbtw)而不添加到對話中。如果您運行 `/btw` 而沒有問題，Claude Code 會顯示您最近的側面問題，以便您可以瀏覽較早的答案；如果您還沒有提出問題，Claude Code 會列印使用行。在 v2.1.212 之前，`/btw` 需要一個問題 |66| `/btw [question]` | 詢問有關目前工作階段的[側面問題](/docs/zh-TW/interactive-mode#side-questions-with-%2Fbtw)而不添加到對話中。如果您運行 `/btw` 而沒有問題，Claude Code 會顯示您最近的側面問題，以便您可以瀏覽較早的答案；如果您還沒有提出問題，Claude Code 會列印使用行。在 v2.1.212 之前，`/btw` 需要一個問題 |

67| `/bug [report]` | 報告錯誤或分享您的對話。您選擇要包含多少工作階段歷史記錄，並在發送任何內容之前在同意螢幕上確認。當您在第一方連線上登入 Anthropic 時，報告會發送給 Anthropic；在第三方提供者上，或沒有 Anthropic 認證，Claude Code 會將報告寫入[`~/.claude/feedback-bundles/` 下的本地存檔](/docs/zh-TW/data-usage#telemetry-services)，您可以自己轉發。在 [VS Code 擴充功能](/docs/zh-TW/vs-code#use-the-prompt-box)中，`/bug` 改為打開擴充功能自己的回饋對話框；需要 Claude Code v2.1.229 或更新版本。當您在 Claude 回應時運行它時，Claude Code 會立即打開對話框。在 v2.1.232 之前，Claude Code 會將命令排隊直到輪次完成。別名：`/share`。在 v2.1.212 之前，`/bug` 和 `/share` 是 `/feedback` 的別名 |67| `/bug [report]` | 報告錯誤或分享您的對話。您選擇要包含多少工作階段歷史記錄，並在發送任何內容之前在同意螢幕上確認。當您在第一方連線上登入 Anthropic 時，報告會發送給 Anthropic；在第三方提供者上，或沒有 Anthropic 認證，Claude Code 會將報告寫入[`~/.claude/feedback-bundles/` 下的本地存檔](/docs/zh-TW/data-usage#telemetry-services)，您可以自己轉發。在 [VS Code 擴充功能](/docs/zh-TW/vs-code#use-the-prompt-box)中，`/bug` 改為打開擴充功能自己的回饋對話框；需要 Claude Code v2.1.229 或更新版本。當您在 Claude 回應時運行它時，Claude Code 會立即打開對話框。在 v2.1.232 之前，Claude Code 會將命令排隊直到輪次完成。別名：`/share`。在 v2.1.212 之前，`/bug` 和 `/share` 是 `/feedback` 的別名 |

68| `/cd <path>` | 將此工作階段移動到新的工作目錄，保持對話。輸入部分路徑以查看匹配的目錄建議；按 `Tab` 接受一個。建議需要 Claude Code v2.1.206 或更新版本。有關 Claude Code 從新目錄立即應用的內容以及 `/cd` 與 `/add-dir` 的區別，請參閱[將工作階段移動到另一個目錄](/docs/zh-TW/permissions#move-the-session-to-another-directory) |68| `/cd <path>` | 將此工作階段移動到新的工作目錄，保持對話。輸入部分路徑以查看匹配的目錄建議；按 `Tab` 接受一個。建議需要 Claude Code v2.1.206 或更新版本。有關 Claude Code 從新目錄立即應用的內容以及 `/cd` 與 `/add-dir` 的區別，請參閱[將工作階段移動到另一個目錄](/docs/zh-TW/permissions#move-the-session-to-another-directory) |

70| `/claude-api [migrate\|upgrade\|managed-agents-onboard\|prompt-audit\|cost-optimize\|build-eval\|hillclimb]` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 為您的專案語言載入 [Claude API](https://platform.claude.com/docs/en/api/overview) 和 [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) 參考資料。當您的程式碼匯入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動啟動。運行 `migrate` 以將現有 Claude API 程式碼更新到較新的模型。運行 `upgrade` 以跨主要版本移動您的專案的 Anthropic SDK 依賴項，目前是 Python `anthropic` 套件從 0.x 到 1.x。運行 `managed-agents-onboard` 以獲得建立新 Managed Agent 的逐步解說。運行 `prompt-audit` 以標記在您的提示詞、技能和工具描述中為較舊模型編寫的指示，並提議修復作為差異。運行 `cost-optimize` 以分析您的專案的 Claude API 支出流向何處，並提議從 prompt caching、修剪不需要的輸入和輸出令牌、批次處理、工作量和模型選擇等選項中節省成本，一次一個變更。運行 `build-eval` 以為您的 Claude 驅動的應用程式建立評估集，以及 `hillclimb` 以針對現有評估迭代改進應用程式。`prompt-audit` 子命令需要 Claude Code v2.1.221 或更新版本，`upgrade` 需要 v2.1.236 或更新版本，`cost-optimize` 需要 v2.1.247 或更新版本，`build-eval` 和 `hillclimb` 需要 v2.1.259 或更新版本 |70| `/claude-api [migrate\|upgrade\|managed-agents-onboard\|prompt-audit\|cost-optimize\|build-eval\|hillclimb]` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 為您的專案語言載入 [Claude API](https://platform.claude.com/docs/en/api/overview) 和 [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) 參考資料。當您的程式碼匯入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動啟動。運行 `migrate` 以將現有 Claude API 程式碼更新到較新的模型。運行 `upgrade` 以跨主要版本移動您的專案的 Anthropic SDK 依賴項，目前是 Python `anthropic` 套件從 0.x 到 1.x。運行 `managed-agents-onboard` 以獲得建立新 Managed Agent 的逐步解說。運行 `prompt-audit` 以標記在您的提示詞、技能和工具描述中為較舊模型編寫的指示，並提議修復作為差異。運行 `cost-optimize` 以分析您的專案的 Claude API 支出流向何處，並提議從 prompt caching、修剪不需要的輸入和輸出令牌、批次處理、工作量和模型選擇等選項中節省成本，一次一個變更。運行 `build-eval` 以為您的 Claude 驅動的應用程式建立評估集，以及 `hillclimb` 以針對現有評估迭代改進應用程式。`prompt-audit` 子命令需要 Claude Code v2.1.221 或更新版本，`upgrade` 需要 v2.1.236 或更新版本，`cost-optimize` 需要 v2.1.247 或更新版本，`build-eval` 和 `hillclimb` 需要 v2.1.259 或更新版本 |

71| `/clear [name]` | 使用空上下文啟動新對話。傳遞名稱以在 `/resume` 選擇器中標記先前的對話。要在繼續相同對話的同時釋放上下文，請改用 `/compact`。使用 `/resume` 恢復先前的對話，或在同一 Claude Code 程序中，從[倒帶菜單的上一個工作階段項目](/docs/zh-TW/checkpointing#rewind-past-a-cleared-conversation)恢復它。倒帶項目需要 Claude Code v2.1.191 或更新版本。別名：`/reset`、`/new` |71| `/clear [name]` | 使用空上下文啟動新對話。傳遞名稱以在 `/resume` 選擇器中標記先前的對話。要在繼續相同對話的同時釋放上下文，請改用 `/compact`。使用 `/resume` 恢復先前的對話，或在同一 Claude Code 程序中，從[倒帶菜單的上一個工作階段項目](/docs/zh-TW/checkpointing#rewind-past-a-cleared-conversation)恢復它。別名：`/reset`、`/new` |

72| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 檢查目前差異或您傳遞的 PR 編號、分支或路徑，以查找正確性錯誤。根據您的模型和工作量級別，檢查也涵蓋清理機會。傳遞 `--fix` 以應用發現，`--comment` 以在 GitHub PR 或 GitLab 合併請求上發佈它們，或 `ultra` 以運行深度[雲端審查](/docs/zh-TW/ultrareview)。發佈到 GitLab 合併請求需要 Claude Code v2.1.257 或更新版本。在 `github.com` PR 目標上使用 `ultra` 時，傳遞 `--post` 以在啟動對話框中預先選擇[將完成的發現發佈到 PR](/docs/zh-TW/ultrareview#post-findings-to-the-pull-request)；`--post` 需要 Claude Code v2.1.227 或更新版本。有關工作量級別、目標設定以及它與 `/simplify` 的關係，請參閱[本地檢查差異](/docs/zh-TW/code-review#review-a-diff-locally)。別名：`/review` |72| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 檢查目前差異或您傳遞的 PR 編號、分支或路徑，以查找正確性錯誤。根據您的模型和工作量級別，檢查也涵蓋清理機會。傳遞 `--fix` 以應用發現，`--comment` 以在 GitHub PR 或 GitLab 合併請求上發佈它們，或 `ultra` 以運行深度[雲端審查](/docs/zh-TW/ultrareview)。發佈到 GitLab 合併請求需要 Claude Code v2.1.257 或更新版本。在 `github.com` PR 目標上使用 `ultra` 時，傳遞 `--post` 以在啟動對話框中預先選擇[將完成的發現發佈到 PR](/docs/zh-TW/ultrareview#post-findings-to-the-pull-request)；`--post` 需要 Claude Code v2.1.227 或更新版本。有關工作量級別、目標設定以及它與 `/simplify` 的關係，請參閱[本地檢查差異](/docs/zh-TW/code-review#review-a-diff-locally)。別名：`/review` |

73| `/color [color\|default]` | 設定目前工作階段的提示詞欄顏色。可用顏色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重置，或運行時不帶引數以選擇隨機顏色。當[遠端控制](/docs/zh-TW/remote-control)連接時，顏色會同步到 claude.ai/code。也可在非互動模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更新版本 |73| `/color [color\|default]` | 設定目前工作階段的提示詞欄顏色。可用顏色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重置，或運行時不帶引數以選擇隨機顏色。當[遠端控制](/docs/zh-TW/remote-control)連接時，顏色會同步到 claude.ai/code。也可在非互動模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更新版本 |

74| `/compact [instructions]` | 通過總結到目前為止的對話來釋放上下文。可選地傳遞焦點指示以進行摘要。請參閱[壓縮如何處理規則、技能和記憶檔案](/docs/zh-TW/context-window#what-survives-compaction) |74| `/compact [instructions]` | 通過總結到目前為止的對話來釋放上下文。可選地傳遞焦點指示以進行摘要。請參閱[壓縮如何處理規則、技能和記憶檔案](/docs/zh-TW/context-window#what-survives-compaction) |

117| `/permissions` | 管理工具權限的允許、詢問和拒絕規則。打開互動式對話框，您可以按範圍檢視規則、添加或移除規則、管理工作目錄以及檢查[最近的自動模式拒絕](/docs/zh-TW/auto-mode-config#review-denials)。您也可以從對話框的 **Auto mode** 標籤檢視和編輯[自動模式分類器規則](/docs/zh-TW/auto-mode-config#edit-rules-from-permissions)。當您在 Claude 回應時運行它時，Claude Code 會立即打開對話框並從 Claude 在同一輪中的下一個工具呼叫開始應用您的變更。在 v2.1.234 之前，Claude Code 會將命令排隊直到輪次完成。別名：`/allowed-tools` |117| `/permissions` | 管理工具權限的允許、詢問和拒絕規則。打開互動式對話框，您可以按範圍檢視規則、添加或移除規則、管理工作目錄以及檢查[最近的自動模式拒絕](/docs/zh-TW/auto-mode-config#review-denials)。您也可以從對話框的 **Auto mode** 標籤檢視和編輯[自動模式分類器規則](/docs/zh-TW/auto-mode-config#edit-rules-from-permissions)。當您在 Claude 回應時運行它時，Claude Code 會立即打開對話框並從 Claude 在同一輪中的下一個工具呼叫開始應用您的變更。在 v2.1.234 之前，Claude Code 會將命令排隊直到輪次完成。別名：`/allowed-tools` |

119| `/plugin [subcommand]` | 管理 Claude Code [plugins](/docs/zh-TW/plugins)。運行時不帶引數以打開外掛菜單，或傳遞子命令（例如 `list`、`install`、`enable` 或 `disable`）以直接執行。Claude Code 可以在安裝期間啟動外掛；[安裝摘要](/docs/zh-TW/discover-plugins#install-plugins)會告訴您它是否執行或是否運行 `/reload-plugins` |119| `/plugin [subcommand]` | 管理 Claude Code [plugins](/docs/zh-TW/plugins/overview)。運行時不帶引數以打開外掛菜單，或傳遞子命令（例如 `list`、`install`、`enable` 或 `disable`）以直接執行。Claude Code 可以在安裝期間啟動外掛；[安裝摘要](/docs/zh-TW/plugins/install#install-a-plugin)會告訴您它是否執行或是否運行 `/reload-plugins` |

121| `/pr-comments [PR]` | 在 v2.1.91 中移除。直接要求 Claude 檢視拉取請求評論。在較早版本上，擷取並顯示來自 GitHub 拉取請求的評論；自動檢測目前分支的 PR，或傳遞 PR URL 或編號。需要 `gh` CLI |121| `/pr-comments [PR]` | 在 v2.1.91 中移除。直接要求 Claude 檢視拉取請求評論。在較早版本上，擷取並顯示來自 GitHub 拉取請求的評論；自動檢測目前分支的 PR，或傳遞 PR URL 或編號。需要 `gh` CLI |

124| `/rate-limit-options` | 顯示在 claude.ai 使用限制阻止請求時保持工作的方式：等待並[在限制重置時自動繼續](/docs/zh-TW/interactive-mode#wait-for-a-usage-limit-to-reset)、添加[使用額度](/docs/zh-TW/costs#add-usage-credits-to-your-subscription)或升級您的方案。Claude Code 也可以在您在自己的終端達到限制時自行打開此菜單。請參閱[關閉自動繼續](/docs/zh-TW/interactive-mode#turn-automatic-continue-off)。需要 claude.ai 訂閱。不在命令菜單中出現；完整輸入它。等待和繼續行需要 Claude Code v2.1.234 或更新版本 |124| `/rate-limit-options` | 顯示在 claude.ai 使用限制阻止請求時保持工作的方式：等待並[在限制重置時自動繼續](/docs/zh-TW/interactive-mode#wait-for-a-usage-limit-to-reset)、添加[使用額度](/docs/zh-TW/costs#add-usage-credits-to-your-subscription)或升級您的方案。Claude Code 也可以在您在自己的終端達到限制時自行打開此菜單。請參閱[關閉自動繼續](/docs/zh-TW/interactive-mode#turn-automatic-continue-off)。需要 claude.ai 訂閱。不在命令菜單中出現；完整輸入它。等待和繼續行需要 Claude Code v2.1.234 或更新版本 |

127| `/reload-plugins [--force]` | 重新載入所有活動 [plugins](/docs/zh-TW/plugins) 以應用待處理變更而不重新啟動。報告每個重新載入元件的計數並標記任何載入錯誤。當重新載入會變更載入的 MCP 工具並使提示詞快取失效時，命令會警告並跳過，除非您傳遞 `--force`。也可在非互動模式 (`-p`)、Agent SDK 和桌面應用程式中使用，其中它僅在直接輸入到工作階段的輸入上運行且不應用外掛 MCP 伺服器變更；需要 Claude Code v2.1.260 或更新版本。請參閱[在不重新啟動的情況下應用外掛變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) |127| `/reload-plugins [--force]` | 重新載入所有活動 [plugins](/docs/zh-TW/plugins/overview) 以應用待處理變更而不重新啟動。報告每個重新載入元件的計數並標記任何載入錯誤。當重新載入會變更載入的 MCP 工具並使提示詞快取失效時，命令會警告並跳過，除非您傳遞 `--force`。也可在非互動模式 (`-p`)、Agent SDK 和桌面應用程式中使用，其中它僅在直接輸入到工作階段的輸入上運行且不應用外掛 MCP 伺服器變更；需要 Claude Code v2.1.260 或更新版本。請參閱[在不重新啟動的情況下應用外掛變更](/docs/zh-TW/plugins/cli-reference#reload-plugins) |

129| `/remote-control` | 使此工作階段可從 claude.ai 進行[遠端控制](/docs/zh-TW/remote-control)。在登出時運行它會列印遠端控制需要 claude.ai 訂閱並告訴您如何登入；在 v2.1.206 之前它報告 `Unknown command: /remote-control`。別名：`/rc` |129| `/remote-control` | 使此工作階段可從 claude.ai 進行[遠端控制](/docs/zh-TW/remote-control)。在登出時運行它會列印遠端控制需要 claude.ai 訂閱並告訴您如何登入；在 v2.1.206 之前它報告 `Unknown command: /remote-control`。別名：`/rc` |

common-workflows.md +4 −4

Details

110 110

111 * 明確說明您要尋找的內容111 * 明確說明您要尋找的內容

112 * 使用專案中的領域語言112 * 使用專案中的領域語言

113 * 為您的語言安裝[程式碼智能外掛](/docs/zh-TW/discover-plugins#code-intelligence)，以便 Claude 進行精確的'前往定義'和'尋找參考'導航113 * 為您的語言安裝[程式碼智能外掛](/docs/zh-TW/plugins/code-intelligence)，以便 Claude 進行精確的「前往定義」和「尋找參考」導航

114</Tip>114</Tip>

115 115

116***116***

313 313

314Claude Code 可在任何目錄中工作。在筆記保管庫、文件資料夾或任何 markdown 檔案集合中執行它，以搜尋、編輯和重新組織內容，就像您處理程式碼一樣。314Claude Code 可在任何目錄中工作。在筆記保管庫、文件資料夾或任何 markdown 檔案集合中執行它，以搜尋、編輯和重新組織內容，就像您處理程式碼一樣。

315 315

316`.claude/` 目錄和 `CLAUDE.md` 與其他工具的配置目錄並存，不會產生衝突。Claude 在每次工具呼叫時都會重新讀取檔案，所以它會在下次讀取該檔案時看到您在另一個應用程式中所做的編輯。316`.claude/` 目錄和 `CLAUDE.md` 與其他工具的設定目錄並存，不會產生衝突。Claude 在每次工具呼叫時都會重新讀取檔案，所以它會在下次讀取該檔案時看到您在另一個應用程式中所做的編輯。

317 317

318***318***

319 319

433| :--------------------------------------- | :------------------ | :------------------------------------------------------------------------------------------------------------- |433| :--------------------------------------- | :------------------ | :------------------------------------------------------------------------------------------------------------- |

438 438

439<Tip>439<Tip>

485 485

486 * Claude 始終可以存取最新的 Claude Code 文件，無論您使用的版本如何486 * Claude 始終可以存取最新的 Claude Code 文件，無論您使用的版本如何

487 * 提出具體問題以獲得詳細答案487 * 提出具體問題以獲得詳細答案

488 * Claude 可以解釋複雜的功能，如 MCP 整合、企業配置和進階工作流程488 * Claude 可以解釋複雜的功能，如 MCP 整合、企業設定和進階工作流程

489</Tip>489</Tip>

490 490

491***491***

costs.md +1 −1

Details

290 為型別化語言安裝程式碼智慧外掛290 為型別化語言安裝程式碼智慧外掛

291</h3>291</h3>

292 292

293[程式碼智慧外掛](/docs/zh-TW/discover-plugins#code-intelligence)為 Claude 提供精確的符號導航，而不是基於文字的搜尋，在探索不熟悉的程式碼時減少不必要的檔案讀取。單一「前往定義」呼叫取代了可能需要的 grep 後跟讀取多個候選檔案。已安裝的語言伺服器也會在編輯後自動報告型別錯誤，因此 Claude 無需執行編譯器即可捕捉錯誤。293[程式碼智慧外掛](/docs/zh-TW/plugins/code-intelligence)為 Claude 提供精確的符號導航，而不是基於文字的搜尋，在探索不熟悉的程式碼時減少不必要的檔案讀取。單一「前往定義」呼叫取代了可能需要的 grep 後跟讀取多個候選檔案。已安裝的語言伺服器也會在編輯後自動報告型別錯誤，因此 Claude 無需執行編譯器即可捕捉錯誤。

294 294

295<h3 id="offload-processing-to-hooks-and-skills">295<h3 id="offload-processing-to-hooks-and-skills">

296 將處理卸載到 hooks 和 skills296 將處理卸載到 hooks 和 skills

debug-your-config.md +2 −2

Details

105大多數設定意外可以追溯到一小組位置和語法規則。在假設有 bug 之前檢查這些：105大多數設定意外可以追溯到一小組位置和語法規則。在假設有 bug 之前檢查這些：

106 106

107| 症狀 | 原因 | 修正 |107| 症狀 | 原因 | 修正 |

108| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |108| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

112| Hook 永遠不觸發 | Hooks 在獨立檔案而不是 `settings.json` 中定義 | 專案或使用者設定沒有獨立的 hooks 檔案。在 `settings.json` 中的 `"hooks"` 鍵下定義 hooks。只有 [plugins](/docs/zh-TW/plugins-reference#hooks) 載入獨立的 `hooks/hooks.json`。請參閱 [hook 設定](/docs/zh-TW/hooks)。 |112| Hook 永遠不觸發 | Hooks 在獨立檔案而不是 `settings.json` 中定義 | 專案或使用者設定沒有獨立的 hooks 檔案。在 `settings.json` 中的 `"hooks"` 鍵下定義 hooks。只有 [plugins](/docs/zh-TW/plugins/components#hooks) 載入獨立的 `hooks/hooks.json`。請參閱 [hook 設定](/docs/zh-TW/hooks)。 |

113| 全域設定的 Permissions、hooks 或 env 被忽略 | 設定已新增到 `~/.claude.json` | `~/.claude.json` 保存應用程式狀態和 UI 切換。`permissions`、`hooks` 和 `env` 屬於 `~/.claude/settings.json`。這是兩個不同的檔案。 |113| 全域設定的 Permissions、hooks 或 env 被忽略 | 設定已新增到 `~/.claude.json` | `~/.claude.json` 保存應用程式狀態和 UI 切換。`permissions`、`hooks` 和 `env` 屬於 `~/.claude/settings.json`。這是兩個不同的檔案。 |

114| `settings.json` 值似乎被忽略 | 相同的鍵在 `settings.local.json` 中設定 | `settings.local.json` 覆蓋 `settings.json`，兩者都覆蓋 `~/.claude/settings.json`。請參閱 [settings 優先順序](/docs/zh-TW/settings#settings-precedence)。 |114| `settings.json` 值似乎被忽略 | 相同的鍵在 `settings.local.json` 中設定 | `settings.local.json` 覆蓋 `settings.json`，兩者都覆蓋 `~/.claude/settings.json`。請參閱 [settings 優先順序](/docs/zh-TW/settings#settings-precedence)。 |

desktop.md +6 −6

Details

472 472

473連接外部服務、新增可重複使用的工作流程、自訂 Claude 的行為，並配置預覽伺服器。若要在一個地方管理連接器、skills 和 plugins，請點擊側邊欄中的 **Customize**。[Cowork](https://claude.com/product/cowork) 標籤在桌面應用程式中從此 Customize 配置取得其 skills、plugins 和連接器，該配置透過您的 claude.ai 帳戶同步，而不是從 CLI 的 `~/.claude` 目錄。473連接外部服務、新增可重複使用的工作流程、自訂 Claude 的行為，並配置預覽伺服器。若要在一個地方管理連接器、skills 和 plugins，請點擊側邊欄中的 **Customize**。[Cowork](https://claude.com/product/cowork) 標籤在桌面應用程式中從此 Customize 配置取得其 skills、plugins 和連接器，該配置透過您的 claude.ai 帳戶同步，而不是從 CLI 的 `~/.claude` 目錄。

474 474

475Claude Code 也會在您使用相同帳戶登入的終端機會話中載入為您的 claude.ai 帳戶啟用的 skills 和 plugins。請參閱 [Skills synced from claude.ai](/docs/zh-TW/skills#how-synced-skills-behave) 和 [Plugins synced from claude.ai](/docs/zh-TW/plugins-reference#synced-plugins)。475Claude Code 也會在您使用相同帳戶登入的終端機會話中載入為您的 claude.ai 帳戶啟用的 skills 和 plugins。請參閱 [Skills synced from claude.ai](/docs/zh-TW/skills#how-synced-skills-behave) 和 [Plugins synced from claude.ai](/docs/zh-TW/plugins/loading#synced-plugins)。

476 476

477<h3 id="connect-external-tools">477<h3 id="connect-external-tools">

478 連接外部工具478 連接外部工具

490 使用 skills490 使用 skills

491</h3>491</h3>

492 492

493[Skills](/docs/zh-TW/skills) 擴展 Claude 可以執行的操作。Claude 在相關時自動載入它們，或者您可以直接呼叫一個：在提示框中輸入 `/` 或點擊 **+** 按鈕並選擇 **Slash commands** 以瀏覽可用的內容。這包括 [built-in commands](/docs/zh-TW/commands)、您的 [custom skills](/docs/zh-TW/skills#create-your-first-skill)、來自您程式碼庫的專案 skills，以及來自任何 [installed plugins](/docs/zh-TW/plugins) 的 skills。選擇一個，它會在輸入欄位中突出顯示。在其後輸入您的任務並照常傳送。493[Skills](/docs/zh-TW/skills) 擴展 Claude 可以執行的操作。Claude 在相關時自動載入它們，或者您可以直接呼叫一個：在提示框中輸入 `/` 或點擊 **+** 按鈕並選擇 **Slash commands** 以瀏覽可用的內容。這包括 [built-in commands](/docs/zh-TW/commands)、您的 [custom skills](/docs/zh-TW/skills#create-your-first-skill)、來自您程式碼庫的專案 skills，以及來自任何 [installed plugins](/docs/zh-TW/plugins/install) 的 skills。選擇一個，它會在輸入欄位中突出顯示。在其後輸入您的任務並照常傳送。

494 494

495您可以在 Claude 正在工作時傳送命令，就像任何其他訊息一樣，會話在回合完成後會回到閒置狀態。在 v2.1.206 之前，在回合中途傳送的命令可能會導致會話顯示為執行中，而您之後傳送的訊息未被傳遞。495您可以在 Claude 正在工作時傳送命令，就像任何其他訊息一樣，會話在回合完成後會回到閒置狀態。在 v2.1.206 之前，在回合中途傳送的命令可能會導致會話顯示為執行中，而您之後傳送的訊息未被傳遞。

496 496

502 安裝 plugins502 安裝 plugins

503</h3>503</h3>

504 504

505[Plugins](/docs/zh-TW/plugins) 是可重複使用的套件，可將 skills、agents、hooks、MCP servers 和 LSP 配置新增到 Claude Code。您可以從桌面應用程式安裝 plugins，而無需使用終端機。505[Plugins](/docs/zh-TW/plugins/overview) 是可重複使用的套件，可將 skills、agents、hooks、MCP servers 和 LSP 配置新增到 Claude Code。您可以從桌面應用程式安裝 plugins，而無需使用終端機。

506 506

507對於本機和 [SSH](#ssh-sessions) 會話，點擊提示框旁的 **+** 按鈕，然後選擇 **Plugins** 以查看您已安裝的 plugins 及其 skills。若要新增 plugin，從子選單中選擇 **Add plugin** 以開啟 plugin 瀏覽器，它顯示來自您配置的 [marketplaces](/docs/zh-TW/plugin-marketplaces)（包括官方 Anthropic 市場）的可用 plugins。選擇 **Manage plugins** 以啟用、停用或解除安裝 plugins。507對於本機和 [SSH](#ssh-sessions) 會話，點擊提示框旁的 **+** 按鈕，然後選擇 **Plugins** 以查看您已安裝的 plugins 及其 skills。若要新增 plugin，從子選單中選擇 **Add plugin** 以開啟 plugin 瀏覽器，它顯示來自您配置的 [marketplaces](/docs/zh-TW/plugins/overview)（包括官方 Anthropic 市場）的可用 plugins。選擇 **Manage plugins** 以啟用、停用或解除安裝 plugins。

508 508

509您可以將 plugins 限定於您的使用者帳戶、特定專案或僅本機。如果您的組織集中管理 plugins，這些 plugins 在桌面會話中的可用方式與在 CLI 中相同。509您可以將 plugins 限定於您的使用者帳戶、特定專案或僅本機。如果您的組織集中管理 plugins，這些 plugins 在桌面會話中的可用方式與在 CLI 中相同。

510 510

511plugin 瀏覽器在雲端會話中不可用，而且您從桌面應用程式安裝的 plugins 不適用於雲端會話。雲端會話也不會安裝儲存庫的 `.claude/settings.json` 宣告的 plugins，如 [What carries over from your setup](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 所述。若要在雲端會話中使用 plugin，請為您的 claude.ai 帳戶啟用它，以便 Claude Code 將其載入為 [synced plugin](/docs/zh-TW/plugins-reference#synced-plugins)。Plugins 在 WSL 會話中不可用。有關完整的 plugin 參考（包括建立您自己的 plugins），請參閱 [plugins](/docs/zh-TW/plugins)。511plugin 瀏覽器在雲端會話中不可用，而且您從桌面應用程式安裝的 plugins 不適用於雲端會話。雲端會話也不會安裝儲存庫的 `.claude/settings.json` 宣告的 plugins，如 [What carries over from your setup](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 所述。Plugins 在 WSL 會話中不可用。有關完整的 plugin 參考（包括建立您自己的 plugins），請參閱 [plugins](/docs/zh-TW/plugins/overview)。

512 512

513<h3 id="configure-preview-servers">513<h3 id="configure-preview-servers">

514 配置預覽伺服器514 配置預覽伺服器

1024| [第三方提供者](/docs/zh-TW/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 預設。若要進行閘道路由，請參閱[將桌面應用程式連接到閘道](/docs/zh-TW/llm-gateway-connect#desktop-app)。若要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤，請參閱 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |1024| [第三方提供者](/docs/zh-TW/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 預設。若要進行閘道路由，請參閱[將桌面應用程式連接到閘道](/docs/zh-TW/llm-gateway-connect#desktop-app)。若要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤，請參閱 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |

1027| @mention 檔案 | 文字型 | 具有自動完成；本機和 SSH 會話僅 |1027| @mention 檔案 | 文字型 | 具有自動完成；本機和 SSH 會話僅 |

1028| 檔案附件 | 不可用 | 影像、PDF |1028| 檔案附件 | 不可用 | 影像、PDF |

discover-plugins.md +0 −651 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# 透過市場探索和安裝預建外掛程式~~

~~7> 從市場探索和安裝外掛程式，以使用新技能、代理和功能擴展 Claude Code。~~

~~9外掛程式透過技能、代理、hooks 和 MCP servers 擴展 Claude Code。外掛程式市場是幫助您探索和安裝這些擴展的目錄，無需自己構建它們。~~

11您也可以在 claude.ai 上啟用外掛程式，供自己或透過您的組織使用。Claude Code 會將這些外掛程式同步到您的工作階段中，無需市場安裝，如[從 claude.ai 同步的外掛程式](/docs/zh-TW/plugins-reference#synced-plugins)所述。

~~13想要建立和分發您自己的市場？請參閱[建立和分發外掛程式市場](/docs/zh-TW/plugin-marketplaces)。~~

~~15<h2 id="how-marketplaces-work">~~

~~16 市場如何運作~~

~~17</h2>~~

~~19市場是他人建立和共享的外掛程式目錄。使用市場是一個兩步流程：~~

~~21<Steps>~~

~~22 <Step title="新增市場">~~

~~23 這會向 Claude Code 註冊目錄，以便您可以瀏覽可用內容。尚未安裝任何外掛程式。~~

~~24 </Step>~~

~~26 <Step title="安裝個別外掛程式">~~

~~27 瀏覽目錄並安裝您想要的外掛程式。~~

~~28 </Step>~~

~~29</Steps>~~

~~31<h2 id="official-anthropic-marketplace">~~

~~32 官方 Anthropic 市場~~

~~33</h2>~~

35Claude Code 在您第一次以互動方式啟動它時會自動新增官方 Anthropic 市場 (`claude-plugins-official`)。如果 Claude Code 無法新增它，例如因為您的網路阻止下載或[市場政策](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)阻止了之前的嘗試，請使用 `/plugin marketplace add anthropics/claude-plugins-official` 自行新增。

~~37若要瀏覽可用內容，請執行 `/plugin` 並前往 **Discover** 標籤，或在 [claude.com/plugins](https://claude.com/plugins) 查看目錄。~~

~~39若要從官方市場安裝外掛程式，請使用 `/plugin install <name>@claude-plugins-official`。例如，若要安裝 GitHub 整合：~~

~~41```shell theme={null}~~

~~42/plugin install github@claude-plugins-official~~

~~43```~~

~~45`/plugin` 在終端 CLI 中開啟互動式面板。如果 Claude 回覆在此環境中無法使用 `/plugin`，請使用另一種方式安裝外掛程式：~~

~~47* **Claude 桌面應用程式**：使用[外掛程式瀏覽器](/docs/zh-TW/desktop#install-plugins)。~~

~~48* **VS Code 擴充功能**：從[**管理外掛程式**對話框](/docs/zh-TW/vs-code#manage-plugins)安裝。~~

~~49* **雲端工作階段**：啟用外掛程式以供您的 claude.ai 帳戶使用，以便 Claude Code 將其載入為[同步外掛程式](/docs/zh-TW/plugins-reference#synced-plugins)。~~

~~51如果安裝失敗，請符合 Claude Code 報告的訊息：~~

~~53* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。~~

~~54* 外掛程式[在市場中找不到](#install-plugins)：檢查外掛程式名稱。~~

~~56<Note>~~

57 官方市場由 Anthropic 維護，包含由 Anthropic 自行決定。應用內提交表單會將外掛程式新增到[社群市場](#community-marketplace)，而不是官方市場。若要獨立分發外掛程式，請[建立您自己的市場](/docs/zh-TW/plugin-marketplaces)並與使用者共享。

~~58</Note>~~

~~60官方市場包括多個外掛程式類別：~~

~~62<h3 id="code-intelligence">~~

~~63 程式碼智能~~

~~64</h3>~~

66程式碼智能外掛程式啟用 Claude Code 的內建 LSP 工具，使 Claude 能夠跳轉到定義、尋找參考資料，並在編輯後立即查看類型錯誤。這些外掛程式配置[語言伺服器協議](https://microsoft.github.io/language-server-protocol/)連接，這是為 VS Code 程式碼智能提供動力的相同技術。在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，Claude Code 不會啟動外掛程式語言伺服器，因此 Claude 在那裡無法取得 LSP 工具。

68在使用這些外掛程式之前，請從下表安裝語言伺服器二進位檔；外掛程式不會為您安裝它。如果您已經安裝了語言伺服器，當您開啟專案時，Claude 可能會提示您安裝相應的外掛程式。

~~70| 語言 | 外掛程式 | 所需的二進位檔 |~~

~~71| :--------- | :------------------ | :--------------------------- |~~

~~72| C/C++ | `clangd-lsp` | `clangd` |~~

~~73| C# | `csharp-lsp` | `csharp-ls` |~~

~~74| Go | `gopls-lsp` | `gopls` |~~

~~75| Java | `jdtls-lsp` | `jdtls` |~~

~~76| Kotlin | `kotlin-lsp` | `kotlin-language-server` |~~

~~77| Lua | `lua-lsp` | `lua-language-server` |~~

~~78| PHP | `php-lsp` | `intelephense` |~~

~~79| Python | `pyright-lsp` | `pyright-langserver` |~~

~~80| Rust | `rust-analyzer-lsp` | `rust-analyzer` |~~

~~81| Swift | `swift-lsp` | `sourcekit-lsp` |~~

~~82| TypeScript | `typescript-lsp` | `typescript-language-server` |~~

~~84您也可以[為其他語言建立您自己的 LSP 外掛程式](/docs/zh-TW/plugins-reference#lsp-servers)。~~

~~86<Note>~~

~~87 如果在安裝外掛程式後在 `/plugin` Errors 標籤中看到 `Executable not found in $PATH`，請從[程式碼智能](#code-intelligence)表安裝該外掛程式所需的二進位檔。~~

~~88</Note>~~

~~90<h4 id="what-claude-gains-from-code-intelligence-plugins">~~

~~91 Claude 從程式碼智能外掛程式獲得的功能~~

~~92</h4>~~

~~94安裝程式碼智能外掛程式並且其語言伺服器二進位檔可用後，Claude 獲得兩項功能：~~

96* **自動診斷**：在 Claude 進行每次檔案編輯後，語言伺服器報告錯誤和警告，因此 Claude 看到類型錯誤、遺漏的匯入和語法問題，無需執行編譯器或 linter。如果 Claude 引入錯誤，它會注意到並在同一輪中修復它。

97* **程式碼導航**：Claude 可以使用語言伺服器跳轉到定義、尋找參考資料、懸停時取得類型資訊、列出符號、尋找實現和追蹤呼叫層次結構。這些操作為 Claude 提供比基於 grep 的搜尋更精確的導航，儘管可用性可能因語言和環境而異。

99您不需要超出安裝外掛程式的任何配置來配置診斷。若要自行讀取它們，當 Claude Code 顯示指示器（例如 **Found 3 new diagnostic issues in 2 files**）時，請按 **Ctrl+O**。

~~100~~

101如果您遇到問題，請參閱[程式碼智能故障排除](#code-intelligence-issues)。

~~102~~

103<h3 id="external-integrations">

104 外部整合

105</h3>

~~106~~

107這些外掛程式捆綁預先配置的 [MCP servers](/docs/zh-TW/mcp)，以便您可以連接 Claude 到外部服務，無需手動設定：

~~108~~

109* **原始碼控制**：`github`、`gitlab`

110* **專案管理**：`atlassian`（Jira/Confluence）、`asana`、`linear`、`notion`

111* **設計**：`figma`

112* **基礎設施**：`vercel`、`firebase`、`supabase`

113* **通訊**：`slack`

114* **監控**：`sentry`

~~115~~

116<h3 id="automatic-security-review">

117 自動安全審查

118</h3>

~~119~~

120`security-guidance` 外掛程式審查 Claude 進行的每項變更是否存在常見漏洞，並指示 Claude 在同一工作階段中修復發現的問題。請參閱[在 Claude 編寫程式碼時捕捉安全問題](/docs/zh-TW/security-guidance)以了解它檢查的內容以及如何新增專案特定的規則。

~~121~~

122<h3 id="development-workflows">

123 開發工作流程

124</h3>

~~125~~

126為常見開發任務新增技能和代理的外掛程式：

~~127~~

128* **commit-commands**：Git 提交工作流程，包括提交、推送和 PR 建立

129* **pr-review-toolkit**：用於審查拉取請求的專門代理

130* **agent-sdk-dev**：使用 Claude Agent SDK 構建的工具

131* **plugin-dev**：建立您自己的外掛程式的工具組

~~132~~

133<h3 id="output-styles">

134 輸出樣式

135</h3>

~~136~~

137自訂 Claude 的回應方式：

~~138~~

139* **explanatory-output-style**：關於實現選擇的教育見解

140* **learning-output-style**：用於技能建立的互動式學習模式

~~141~~

142<h2 id="community-marketplace">

143 社群市場

144</h2>

~~145~~

146位於 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 的社群市場託管已通過 Anthropic 自動驗證和安全篩選的第三方外掛程式。每個外掛程式都固定到目錄中的特定提交 SHA。與官方市場不同，您需要手動新增它：

~~147~~

148```shell theme={null}

149/plugin marketplace add anthropics/claude-plugins-community

150```

~~151~~

152然後使用 `claude-community` 市場名稱從中安裝外掛程式：

~~153~~

154```shell theme={null}

155/plugin install <plugin-name>@claude-community

156```

~~157~~

158若要將您自己的外掛程式提交到社群市場，請參閱建立外掛程式指南中的[將您的外掛程式提交到社群市場](/docs/zh-TW/plugins#submit-your-plugin-to-the-community-marketplace)。

~~159~~

160<h2 id="try-it-add-the-demo-marketplace">

161 試試看：新增演示市場

162</h2>

~~163~~

164Anthropic 也維護一個[演示外掛程式市場](https://github.com/anthropics/claude-code/tree/main/plugins)（`claude-code-plugins`），其中包含展示外掛程式系統可能性的範例外掛程式。與官方市場不同，您需要手動新增此市場。

~~165~~

166<Steps>

167 <Step title="新增市場">

168 在 Claude Code 中，為 `anthropics/claude-code` 市場執行 `plugin marketplace add` 命令：

~~169~~

170 ```shell theme={null}

171 /plugin marketplace add anthropics/claude-code

172 ```

~~173~~

174 這會下載市場目錄並使其外掛程式可供您使用。

175 </Step>

~~176~~

177 <Step title="瀏覽可用外掛程式">

178 執行 `/plugin` 以開啟外掛程式管理器。這會開啟一個標籤式介面，您可以使用 **Tab** 或 **Shift+Tab** 向後循環瀏覽：

~~179~~

180 * **Discover**：從所有市場瀏覽可用外掛程式

181 * **Installed**：檢視和管理已安裝的外掛程式

182 * **Marketplaces**：新增、移除或更新已新增的市場

183 * **Errors**：檢視任何外掛程式載入錯誤

184 * **Stats**：查看[您每個 skills 在內容中的成本以及使用頻率](/docs/zh-TW/skills#find-unused-skills)，在有 `/skill-doctor` 可用的工作階段中

~~185~~

186 前往 **Discover** 標籤以查看您剛新增的市場中的外掛程式。當您的管理員已透過 [`pluginSuggestionMarketplaces`](/docs/zh-TW/settings-reference#pluginsuggestionmarketplaces) 受管設定將市場加入允許清單時，標記為與您目前工作目錄相關的外掛程式會釘在頂部，並帶有 **suggested for this directory** 標籤。

187 </Step>

~~188~~

189 <Step title="安裝外掛程式">

190 選擇外掛程式以檢視其詳細資訊。詳細資訊窗格會顯示外掛程式包含的內容及其成本：

~~191~~

192 * **Context cost** 估計，讓您可以查看外掛程式每回合會為您的[內容視窗](/docs/zh-TW/features-overview#understand-context-costs)新增多少個 token

193 * 外掛程式的 **Last updated** 日期

194 * **Will install** 區段，列出外掛程式的命令、代理程式、skills、hooks 和 MCP 及 LSP 伺服器，讓您可以在安裝前檢視它新增的確切內容

~~195~~

196 並非每個外掛程式都提供這些欄位背後的資料。對於來自本機或自訂市場的外掛程式，您可能看不到 **Context cost** 和 **Last updated** 列，**Will install** 區段可能會改為顯示 **Components will be discovered at installation**。

~~197~~

198 選擇安裝範圍：

~~199~~

200 * **User scope**：在所有專案中為自己安裝

201 * **Project scope**：為此儲存庫上的所有協作者安裝

202 * **Local scope**：僅在此儲存庫中為自己安裝

~~203~~

204 例如，選擇 **commit-commands**（新增 git 工作流程 skills 的外掛程式）並將其安裝到您的使用者範圍。

~~205~~

206 您也可以直接從命令列開始安裝：

~~207~~

208 ```shell theme={null}

209 /plugin install commit-commands@claude-code-plugins

210 ```

~~211~~

212 請參閱[設定檔](/docs/zh-TW/settings#where-settings-live)以深入瞭解範圍。

213 </Step>

~~214~~

215 <Step title="使用您的新外掛程式">

216 如果安裝摘要報告 `Run /reload-plugins to activate.`，Claude Code 會為您執行該重新載入。如果重新載入警告您的下一則訊息會重新讀取對話，請執行 `/reload-plugins --force` 以啟用外掛程式。

~~217~~

218 外掛程式 skills 由外掛程式名稱命名空間，因此 **commit-commands** 提供 `/commit-commands:commit` 之類的 skills。

~~219~~

220 透過對檔案進行變更並執行以下命令來試試看：

~~221~~

222 ```shell theme={null}

223 /commit-commands:commit

224 ```

~~225~~

226 這會暫存您的變更、產生提交訊息並建立提交。

~~227~~

228 每個外掛程式的工作方式不同。檢查 **Discover** 標籤中的外掛程式詳細資訊以查看它提供的命令和 skills，或造訪其首頁以取得使用指導。

229 </Step>

230</Steps>

~~231~~

232<h2 id="add-marketplaces">

233 新增市場

234</h2>

~~235~~

236使用 `/plugin marketplace add` 命令從不同來源新增市場。

~~237~~

238<Tip>

239 **快捷方式**：您可以使用 `/plugin market` 代替 `/plugin marketplace`，以及 `rm` 代替 `remove`。

240</Tip>

~~241~~

242* **GitHub 儲存庫**：`owner/repo` 格式，例如 `anthropics/claude-code`

243* **Git URL**：任何 git 儲存庫 URL，包括 GitLab、Bitbucket 和自託管伺服器

244* **本機路徑**：目錄或 `marketplace.json` 檔案的直接路徑

245* **遠端 URL**：託管 `marketplace.json` 檔案的直接 URL

246* **claude.ai**：託管在 claude.ai 上的市場（適用於您的帳戶），例如您組織的外掛程式庫，您可以[從 **Marketplaces** 標籤或您的 shell 按名稱新增](#add-from-claude-ai)，而不是按來源新增

~~247~~

248<h3 id="add-from-github">

249 從 GitHub 新增

250</h3>

~~251~~

252使用 `owner/repo` 格式新增包含 `.claude-plugin/marketplace.json` 檔案的 GitHub 儲存庫，其中 `owner` 是 GitHub 使用者名稱或組織，`repo` 是儲存庫名稱。

~~253~~

254例如，`anthropics/claude-code` 指的是由 `anthropics` 擁有的 `claude-code` 儲存庫：

~~255~~

256```shell theme={null}

257/plugin marketplace add anthropics/claude-code

258```

~~259~~

260<h3 id="add-from-other-git-hosts">

261 從其他 Git 主機新增

262</h3>

~~263~~

264透過提供完整 URL 新增 git 市場儲存庫。對於 `https://` URL，是否包含 `.git` 後綴取決於主機：

~~265~~

266* **`github.com` 和 `gitlab.com`**：Claude Code 可識別帶有或不帶 `.git` 後綴的儲存庫 URL，並複製它。新增不帶後綴的 `gitlab.com` URL 需要 Claude Code v2.1.232 或更新版本。在 v2.1.232 之前，Claude Code 將其視為託管 `marketplace.json` 檔案的直接連結。

267* **Azure DevOps**：省略後綴。Claude Code 複製任何路徑包含 `/_git/` 的 URL。如果您在 `/_git/` 路徑後面附加 `.git`，複製會失敗。

268* **所有其他主機，包括自託管 GitLab 伺服器**：包含 `.git` 後綴，以便 Claude Code 複製儲存庫，而不是將 URL 視為託管 `marketplace.json` 檔案的直接連結。對於複製 URL 不帶後綴的主機（例如 AWS CodeCommit），請改為在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 中新增市場作為 git 項目。Claude Code 複製 git 項目時，無論其 URL 是否以 `.git` 結尾。

~~269~~

270Claude Code 也複製具有巢狀子群組的 `gitlab.com` URL，例如 `https://gitlab.com/group/subgroup/project`。

~~271~~

272包含 `https://` 前綴。Claude Code v2.1.196 及更新版本會拒絕沒有前綴的主機，例如 `gitlab.com/company/plugins.git`，視其為無效的 GitHub `owner/repo` 簡寫，錯誤訊息會告訴您新增前綴。較早的版本會將其誤讀為 GitHub 儲存庫路徑，並在複製時失敗。

~~273~~

274使用 HTTPS：

~~275~~

276```shell theme={null}

277/plugin marketplace add https://gitlab.com/company/plugins.git

278```

~~279~~

280使用 SSH：

~~281~~

282```shell theme={null}

283/plugin marketplace add git@gitlab.com:company/plugins.git

284```

~~285~~

286Claude Code 複製 SSH 位址時，無論是否以 `.git` 結尾。

~~287~~

288若要新增特定分支或標籤，請在 `#` 後面附加 ref：

~~289~~

290```shell theme={null}

291/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

292```

~~293~~

294<h3 id="add-from-local-paths">

295 從本機路徑新增

296</h3>

~~297~~

298新增包含 `.claude-plugin/marketplace.json` 檔案的本機目錄：

~~299~~

300```shell theme={null}

301/plugin marketplace add ./my-marketplace

302```

~~303~~

304您也可以新增 `marketplace.json` 檔案的直接路徑：

~~305~~

306```shell theme={null}

307/plugin marketplace add ./path/to/marketplace.json

308```

~~309~~

310<h3 id="add-from-remote-urls">

311 從遠端 URL 新增

312</h3>

~~313~~

314透過 URL 新增遠端 `marketplace.json` 檔案：

~~315~~

316```shell theme={null}

317/plugin marketplace add https://example.com/marketplace.json

318```

~~319~~

320<Note>

321 與基於 Git 的市場相比，基於 URL 的市場有一些限制。如果從基於 URL 的市場安裝外掛程式失敗，請參閱[故障排除](/docs/zh-TW/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)。

322</Note>

~~323~~

324<h3 id="add-from-claude-ai">

325 從 claude.ai 新增

326</h3>

~~327~~

328在[外掛程式從您的 claude.ai 帳戶同步](/docs/zh-TW/plugins-reference#synced-plugins)的終端機工作階段中，claude.ai 也可以為您列出市場，例如您組織的外掛程式庫和您自己的 claude.ai 上傳。`claude plugin marketplace list` 會在 `From claude.ai:` 區段中列印它們，而 `/plugin` **Marketplaces** 標籤也會列出它們。在那裡選擇一個以新增它。從 claude.ai 新增市場需要 Claude Code v2.1.273 或更新版本。

~~329~~

330若要從您的 shell 新增一個，請執行 `claude plugin marketplace add` 並使用 `--claudeai` 旗標和列表中顯示的名稱：

~~331~~

332```bash theme={null}

333claude plugin marketplace add --claudeai claudeai-organization-library

334```

~~335~~

336Claude Code 會在以 `claudeai-` 開頭的本機名稱下註冊市場，該名稱衍生自 claude.ai 列出的名稱：列為「Organization library」的市場會註冊為 `claudeai-organization-library`。使用該名稱安裝其外掛程式，例如使用 `claude plugin install <plugin>@claudeai-organization-library`。

~~337~~

338如果您登出或使用不同帳戶登入，市場會保持設定但不顯示任何外掛程式，而您已從中安裝的外掛程式會繼續載入。

~~339~~

340`From claude.ai:` 區段也可以列出透過 claude.ai 共享的基於 git 的市場。您可以使用普通的 `marketplace add` 命令新增這些市場，使用列表列印的來源。

~~341~~

342<h2 id="install-plugins">

343 安裝外掛程式

344</h2>

~~345~~

346新增市場後，您可以按名稱安裝外掛程式。對於您尚未新增的市場，您可以改為[在一個命令中新增並安裝](#add-a-marketplace-and-install-in-one-command)。

~~347~~

348若要按名稱安裝：

~~349~~

350```shell theme={null}

351/plugin install plugin-name@marketplace-name

352```

~~353~~

354該命令會開啟該外掛程式的詳細資訊，您可以在其中選擇[安裝範圍](/docs/zh-TW/settings#where-settings-live)。當您執行 `/plugin`、前往 **Discover** 標籤，並在外掛程式上按 **Enter** 時，您會看到相同的選項：

~~355~~

356* **User scope**：在所有專案中為自己安裝

357* **Project scope**：為此儲存庫上的所有協作者安裝，這會將外掛程式新增到 `.claude/settings.json`

358* **Local scope**：僅在此儲存庫中為自己安裝，不與協作者共享

~~359~~

360若要在沒有互動式步驟的情況下安裝，請使用 [`claude plugin install`](/docs/zh-TW/plugins-reference#plugin-install) shell 命令，該命令預設安裝到使用者範圍，除非您傳遞 `--scope`。對於具有[`command` 來源](/docs/zh-TW/plugin-marketplaces#how-users-accept-the-command)的外掛程式，傳遞 `--yes` 以接受它顯示的命令。

~~361~~

362您也可能看到具有 **managed** 範圍的外掛程式。這些是由管理員透過[受管設定](/docs/zh-TW/managed-settings)安裝的，無法修改。

~~363~~

364Claude Code 在其本地市場目錄副本中查詢外掛程式。您命名外掛程式的方式控制 Claude Code 是否先重新整理該副本：

~~365~~

366* **使用市場名稱**：當您安裝 `plugin-name@marketplace-name` 時，在工作階段中或使用 `claude plugin install` 時，Claude Code 會在查詢前重新整理該市場。即使您關閉了市場的[自動更新](#configure-auto-updates)或設定了 `DISABLE_AUTOUPDATER`，Claude Code 也會執行重新整理。在 v2.1.232 之前，Claude Code 在查詢前不會重新整理市場。Claude Code 在以下情況下會跳過此重新整理：

367 * 市場未[從 GitHub、其他 Git 主機、遠端 URL](#add-marketplaces)或 [claude.ai](#add-from-claude-ai) 新增。

368 * [種子目錄](/docs/zh-TW/plugin-marketplaces#pre-populate-plugins-for-containers)提供市場。

369 * Claude Code 在過去 30 秒內重新整理了市場。

370 * 您設定了 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars)。

371 * [受管設定](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)阻止市場，在這種情況下 Claude Code 也會拒絕安裝。

372* **僅外掛程式名稱**：當您在工作階段中執行 `/plugin install plugin-name` 時，Claude Code 只會重新整理它也在[背景更新](#configure-auto-updates)的市場，且僅在查詢失敗後。當您執行 `claude plugin install plugin-name` 時，Claude Code 會讀取快取的目錄而不重新整理。若要安裝在上次重新整理後發佈的外掛程式，請在工作階段中執行 `/plugin marketplace update <marketplace-name>` 或在您的 shell 中執行 [`claude plugin marketplace update <marketplace-name>`](/docs/zh-TW/plugin-marketplaces#plugin-marketplace-update)，然後重試安裝。

~~373~~

374如果命名安裝前的重新整理失敗，例如因為您離線，Claude Code 仍會在快取目錄中查詢外掛程式。`claude plugin install` 在其成功訊息中報告 `marketplace not refreshed`，而 `/plugin install` 在外掛程式詳細資訊上方或其找不到訊息中顯示失敗。

~~375~~

376當您從 `/plugin` 介面安裝時，安裝摘要會告訴您外掛程式在您目前工作階段中是否為作用中：

~~377~~

378* `Plugin is now active.`：Claude Code 在安裝過程中啟動了外掛程式。

379* `Run /reload-plugins to activate.`：外掛程式尚未作用中，因為啟動它會[使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)或因為啟動嘗試失敗。Claude Code 接著會為您執行 `/reload-plugins`。如果該重新載入警告提示快取，請執行 `/reload-plugins --force` 以[在不重新啟動的情況下啟動外掛程式](#apply-plugin-changes-without-restarting)。

380* 如果外掛程式無法載入，摘要會報告失敗，而 `/plugin` **Errors** 標籤會顯示詳細資訊。

~~381~~

382在 v2.1.221 之前，在您執行 `/reload-plugins` 或重新啟動之前，沒有安裝在目前工作階段中生效。

~~383~~

384`claude plugin install` shell 命令不在工作階段中執行，因此 Claude Code 會在您下次啟動 Claude Code 時或在已開啟的工作階段中執行 `/reload-plugins` 時載入它安裝的外掛程式。

~~385~~

386<Warning>

387 在安裝外掛程式之前，請確保您信任它。Anthropic 不控制外掛程式中包含的 MCP servers、檔案或其他軟體，也無法驗證它們是否按預期工作。檢查每個外掛程式的首頁以獲取更多資訊。

388</Warning>

~~389~~

390<h3 id="add-a-marketplace-and-install-in-one-command">

391 在一個命令中新增市場並安裝

392</h3>

~~393~~

394若要從您尚未新增的市場安裝外掛程式，請使用 `--marketplace` 命名市場來源。需要 Claude Code v2.1.275 或更新版本。

~~395~~

396```shell theme={null}

397/plugin install quality-review-plugin --marketplace your-org/plugins

398```

~~399~~

400來源採用[與 `/plugin marketplace add` 相同的形式](#add-marketplaces)，例如 GitHub `owner/repo`、git URL 或本地路徑，除了它不能包含空格。給出外掛程式名稱時不帶 `@marketplace` 後綴。

~~401~~

402Claude Code 會顯示它解析的來源，並要求您在新增市場前確認。拒絕會取消安裝並不新增任何內容。市場新增後，外掛程式的詳細資訊會開啟，您可以選擇[安裝範圍](/docs/zh-TW/settings#where-settings-live)。如果來源符合您已新增的市場，Claude Code 會跳過確認並在該市場中開啟外掛程式的詳細資訊。

~~403~~

404<h2 id="manage-installed-plugins">

405 管理已安裝的外掛程式

406</h2>

~~407~~

408執行 `/plugin` 並前往 **Installed** 標籤以檢視、啟用、停用或解除安裝外掛程式。清單按範圍分組，並排序以便您首先看到問題：具有載入錯誤或未解決依賴項的外掛程式出現在頂部，然後是您的最愛，停用的外掛程式摺疊在底部的摺疊標題後面。

~~409~~

410從清單中，您可以：

~~411~~

412* 按 `f` 以將選定的外掛程式加入最愛或取消加入最愛

413* 輸入以按外掛程式名稱或描述篩選

414* 按 Enter 以開啟外掛程式的詳細檢視並啟用、停用或解除安裝它

~~415~~

416Claude Code 也會在 **Installed** 標籤中列出[從您的 claude.ai 帳戶同步的外掛程式](/docs/zh-TW/plugins-reference#synced-plugins)，其來源為 `synced`。除非您的組織將其標記為必需，否則您可以在那裡啟用或停用一個。若要移除一個，請在 claude.ai 上將其關閉。同步的外掛程式會出現在 Claude Code v2.1.273 或更新版本的終端工作階段中。

~~417~~

418當您解除安裝專案的 `.claude/settings.json` 啟用的外掛程式時，Claude Code 會詢問您指的是哪個範圍：僅為您停用它，這會將覆寫寫入您的 `.claude/settings.local.json` 並為專案保留已安裝的外掛程式，或為所有人解除安裝它，這會將其從共用的 `.claude/settings.json` 中移除。

~~419~~

420詳細檢視會顯示外掛程式貢獻的元件：commands、skills、agents、hooks、MCP servers 和 LSP servers。相同的清單也可從命令列透過 `claude plugin details` 取得。

~~421~~

422Claude Code 也會在 **Installed** 標籤中的 **Not used recently** 標題下列出您自己安裝但至少兩週內未使用且跨越至少 10 個工作階段的 marketplace 外掛程式。詳細檢視會為每個外掛程式顯示 **Last used** 行。使用這些功能來找出您不再使用但仍在增加啟動和內容成本的外掛程式，然後停用或解除安裝它們。

~~423~~

424兩種外掛程式永遠不會列為未使用：

~~425~~

426* 您的組織管理的外掛程式或您使用 `--plugin-dir` 載入的外掛程式

427* 貢獻 theme、output style、monitor 或 workflow 的外掛程式，因為這些外掛程式提供價值而無需追蹤叫用

~~428~~

429當您的組織使用 [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) 限制 marketplaces 時，**Not used recently** 標題和 **Last used** 行都會隱藏。

~~430~~

431外掛程式的 [language server](/docs/zh-TW/plugins#add-lsp-servers-to-your-plugin) 在提供診斷或回答程式碼導覽請求時計為已使用，因此其伺服器在您的工作階段中處於活動狀態的 LSP 外掛程式不會列為未使用。在 v2.1.203 之前，無法將語言伺服器活動計為使用，因此貢獻 LSP 伺服器的外掛程式完全豁免於該群組，與 theme 和 output style 外掛程式的方式相同。

~~432~~

433在計算語言伺服器活動的版本上的第一個工作階段也會重設每個尚未記錄任何使用的 LSP 外掛程式的使用記錄，因此 Claude Code 不會根據在其伺服器活動被追蹤之前記錄的資料將您較早安裝的外掛程式判斷為未使用。

~~434~~

435當您安裝聲明依賴項的外掛程式時，安裝輸出會列出哪些依賴項與其一起自動安裝。

~~436~~

437您也可以使用直接命令管理外掛程式：

~~438~~

439* 當您執行 `/plugin disable`、`/plugin enable` 或 `/plugin uninstall` 時，Claude Code 會開啟外掛程式面板以套用變更並保持其開啟。按 **Esc** 以在輸入另一個命令之前關閉面板。[在不重新啟動的情況下套用外掛程式變更](#apply-plugin-changes-without-restarting)說明變更在您的工作階段中何時生效。

440* 對於指令碼編寫，請改用 `claude plugin` shell 命令，這些命令不會開啟面板。

~~441~~

442列出已安裝的外掛程式而不開啟選單：

~~443~~

444```shell theme={null}

445/plugin list

446```

~~447~~

448傳遞 `--enabled` 或 `--disabled` 以僅顯示處於該狀態的外掛程式。

~~449~~

450停用外掛程式而不解除安裝：

~~451~~

452```shell theme={null}

453/plugin disable plugin-name@marketplace-name

454```

~~455~~

456重新啟用已停用的外掛程式：

~~457~~

458```shell theme={null}

459/plugin enable plugin-name@marketplace-name

460```

~~461~~

462在這些識別碼中，`plugin-name` 是 [marketplace 項目](/docs/zh-TW/plugin-marketplaces#plugin-entries) 中外掛程式的 `name`，可能與外掛程式自身 `plugin.json` 中的 `name` 不同。

~~463~~

464自 Claude Code v2.1.195 起，`/plugin` 介面中的 **Enable** 和 **Disable** 適用於其兩個名稱不同的外掛程式，`/plugin enable` 和 `/plugin disable` 接受任一名稱。當您在較早版本中停用此類外掛程式時，Claude Code 會報告 `already disabled` 並保持其啟用狀態。

~~465~~

466完全移除外掛程式：

~~467~~

468```shell theme={null}

469/plugin uninstall plugin-name@marketplace-name

470```

~~471~~

472`--scope` 選項可讓您使用 CLI 命令針對特定範圍：

~~473~~

474```shell theme={null}

475claude plugin install formatter@your-org --scope project

476claude plugin uninstall formatter@your-org --scope project

477```

~~478~~

479<h3 id="apply-plugin-changes-without-restarting">

480 在不重新啟動的情況下套用外掛程式變更

481</h3>

~~482~~

483當您關閉 `/plugin` 選單時，Claude Code 會為您執行 `/reload-plugins` 以套用您在其中所做的變更，例如安裝、啟用、停用和解除安裝外掛程式。如果重新載入會[使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，它會發出警告並改為保留變更待處理；執行 `/reload-plugins --force` 以無論如何套用它們。如果 Claude 在您關閉選單時仍在回應，重新載入會在回應完成後執行。

~~484~~

485對於在選單外發生的外掛程式變更，請自行執行 `/reload-plugins`。這些變更包括：

~~486~~

487* 您在另一個終端中執行的 `claude plugin` 命令

488* 您在開發時使用 [`--plugin-dir`](/docs/zh-TW/plugins#test-your-plugins-locally) 載入的外掛程式編輯

489* 外掛程式[自動更新](#configure-auto-updates)，其通知要求您重新載入

490* [從您的 claude.ai 帳戶同步](/docs/zh-TW/plugins-reference#synced-plugins)，已新增、更新或移除外掛程式並顯示要求您重新載入的通知

491* [`--plugin-dir` 資料夾](/docs/zh-TW/plugins#test-your-plugins-locally)中的變更，Claude Code 保留該變更是因為套用它會使提示快取失效

~~492~~

493在 v2.1.268 之前，您在選單中啟用、停用或解除安裝的外掛程式，以及在安裝期間未啟動的安裝，會保持待處理狀態，直到您執行 `/reload-plugins`。

~~494~~

495`/reload-plugins` 也在沒有互動式終端的工作階段中執行，例如桌面應用程式、Agent SDK 和[非互動模式](/docs/zh-TW/headless)（使用 `-p`）。需要 Claude Code v2.1.260 或更新版本。在這些工作階段中適用兩個限制：

~~496~~

497* 命令僅在您直接將其輸入到工作階段時執行，例如在 `-p` 提示或桌面應用程式的提示框中。當您改為透過遠端連線傳送它時，例如 [Remote Control](/docs/zh-TW/remote-control) 或轉接的聊天訊息，命令會拒絕而不重新載入任何內容。

498* 重新載入不會連線或斷開外掛程式 MCP servers。這些變更會在您的下一個工作階段中生效。

~~499~~

500Claude Code 重新載入所有活動外掛程式，並顯示外掛程式、skills、agents、hooks、外掛程式 MCP servers 和外掛程式 LSP servers 的計數，在沒有互動式終端的工作階段中省略外掛程式 MCP server 計數。在 skills 計數中，Claude Code 包括外掛程式提供的每個 skill：其 `commands/` 項目和 `SKILL.md` skills。在 v2.1.246 之前，Claude Code 僅計算 `commands/` 項目，因此它可以重新載入外掛程式的 `SKILL.md` skills 並仍然在摘要中報告 `0 skills`。

~~501~~

502重新載入在下一個請求時會產生令牌成本：新載入的元件會在附加到對話的內容中宣佈自己，而現有歷史記錄仍然從提示快取讀取。提供 MCP servers 的外掛程式在其工具未被 [tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 延遲時成本更高：該變更會使快取失效，下一個請求會重新讀取整個對話。請參閱[啟用或停用外掛程式](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)以取得詳細資訊。

~~503~~

504<h2 id="manage-marketplaces">

505 管理市場

506</h2>

~~507~~

508您可以透過互動式 `/plugin` 介面或使用 CLI 命令管理市場。

~~509~~

510<h3 id="use-the-interactive-interface">

511 使用互動式介面

512</h3>

~~513~~

514執行 `/plugin` 並前往 **Marketplaces** 標籤以：

~~515~~

516* 檢視所有已新增的市場及其來源和狀態

517* 新增新市場

518* 更新市場清單以取得最新外掛程式

519* 移除您不再需要的市場

~~520~~

521<h3 id="use-cli-commands">

522 使用 CLI 命令

523</h3>

~~524~~

525您也可以使用直接命令管理市場。

~~526~~

527列出所有已配置的市場：

~~528~~

529```shell theme={null}

530/plugin marketplace list

531```

~~532~~

533從市場重新整理外掛程式清單：

~~534~~

535```shell theme={null}

536/plugin marketplace update marketplace-name

537```

~~538~~

539移除市場：

~~540~~

541```shell theme={null}

542/plugin marketplace remove marketplace-name

543```

~~544~~

545<Warning>

546 移除市場將解除安裝您從中安裝的任何外掛程式。

547</Warning>

~~548~~

549<h3 id="configure-auto-updates">

550 配置自動更新

551</h3>

~~552~~

553Claude Code 可以在啟動後自動在背景更新市場及其已安裝的外掛程式。為市場啟用自動更新後，Claude Code 會重新整理市場資料並將已安裝的外掛程式更新到其磁碟上的最新版本。

~~554~~

555Claude Code 會在您的工作階段開始後檢查市場和外掛程式更新，並隨機延遲最多十分鐘，因此執行中的工作階段會繼續使用它在啟動時載入的版本。如果任何外掛程式已更新，您將看到提示您執行 `/reload-plugins` 的通知，或新版本會在您下次啟動時載入。

~~556~~

557自動更新也會排除其市場項目宣告 `headersHelper` 的外掛程式：Claude Code [既不執行命令也不下載該路徑上的封存](/docs/zh-TW/plugin-marketplaces#installs-and-updates-that-refuse-the-command-instead-of-asking)；該部分說明 Claude Code 何時在 `/plugin` Errors 標籤中列出外掛程式，以便您可以從其自己的檢視中更新它。

~~558~~

559Claude Code 更新具有[`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)的外掛程式，其節奏與市場自動更新設定和 `DISABLE_AUTOUPDATER` 分開。相反，它[每個工作階段重新執行一次命令](/docs/zh-TW/plugin-marketplaces#when-claude-code-re-runs-the-command)，並在其[雜湊](/docs/zh-TW/plugins-reference#version-management)已變更時將輸出安裝為新的外掛程式版本。

~~560~~

561透過 UI 為個別市場切換自動更新：

~~562~~

5631. 執行 `/plugin` 以開啟外掛程式管理器

5642. 選擇 **Marketplaces**

5653. 從清單中選擇市場

5664. 選擇 **Enable auto-update** 或 **Disable auto-update**

~~567~~

568`claude-plugins-official`、大多數其他官方 Anthropic 市場，以及[從 claude.ai 新增的市場](#add-from-claude-ai)預設啟用自動更新。其他第三方市場和本機開發市場預設停用自動更新。

~~569~~

570管理員也可以在受管設定中的每個 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目上設定 `"autoUpdate": true`，以為組織市場啟用自動更新，而無需每個使用者都切換它。

~~571~~

572若要停用 Claude Code 和從市場取得的外掛程式的自動更新，請設定 `DISABLE_AUTOUPDATER` 環境變數。具有[`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)的外掛程式遵循其自己的每個工作階段一次重新解析。如需詳細資訊，請參閱[自動更新](/docs/zh-TW/setup#auto-updates)。

~~573~~

574若要在停用 Claude Code 自動更新的同時保持外掛程式自動更新啟用，請設定 `FORCE_AUTOUPDATE_PLUGINS=1` 以及 `DISABLE_AUTOUPDATER`：

~~575~~

576```bash theme={null}

577export DISABLE_AUTOUPDATER=1

578export FORCE_AUTOUPDATE_PLUGINS=1

579```

~~580~~

581<h2 id="configure-team-marketplaces">

582 配置團隊市場

583</h2>

~~584~~

585團隊管理員可以透過將市場配置新增到 `.claude/settings.json` 來為專案設定自動市場安裝。當團隊成員[信任儲存庫資料夾](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)後，Claude Code 會自動新增這些市場，無需進一步提示。

~~586~~

587自 Claude Code v2.1.195 起，新增市場不會安裝來自外部來源的外掛程式，在任何載入外掛程式的路徑上都是如此。只有專案的 `.claude/settings.json` 啟用的外掛程式，且來自外部來源（例如 GitHub 儲存庫或 npm 套件），在團隊成員安裝之前不會載入。在此之前，Claude Code 會將外掛程式報告為未安裝，並顯示要執行的 `claude plugin install` 命令。

~~588~~

589將 `extraKnownMarketplaces` 新增到您的專案的 `.claude/settings.json`：

~~590~~

591```json theme={null}

592{

593 "extraKnownMarketplaces": {

594 "my-team-tools": {

595 "source": {

596 "source": "github",

597 "repo": "your-org/claude-plugins"

598 }

599 }

600 }

601}

602```

~~603~~

604如需完整配置選項（包括 `extraKnownMarketplaces` 和 `enabledPlugins`），請參閱[外掛程式設定](/docs/zh-TW/settings-reference#plugin-settings)。

~~605~~

606<h2 id="security">

607 安全性

608</h2>

~~609~~

610外掛程式和市場是高度受信任的元件，可以使用您的使用者權限在您的機器上執行任意程式碼。僅從您信任的來源安裝外掛程式和新增市場。組織可以使用[受管市場限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)限制使用者可以新增的市場。

~~611~~

612<h2 id="troubleshooting">

613 故障排除

614</h2>

~~615~~

616<h3 id="/plugin-command-not-recognized">

617 /plugin 命令無法識別

618</h3>

~~619~~

620如果您看到「未知命令」或 `/plugin` 命令未出現：

~~621~~

6221. **檢查您的版本**：執行 `claude --version` 以查看已安裝的內容。

6232. **更新 Claude Code**：

624 * **Homebrew**：`brew upgrade claude-code`，或如果您安裝了該 cask，執行 `brew upgrade claude-code@latest`

625 * **npm**：`npm install -g @anthropic-ai/claude-code@latest`

626 * **原生安裝程式**：從[設定](/docs/zh-TW/setup)重新執行安裝命令

6273. **重新啟動 Claude Code**：更新後，重新啟動您的終端機並再次執行 `claude`。

~~628~~

629<h3 id="common-issues">

630 常見問題

631</h3>

~~632~~

633如果 plugin skills 未出現，使用 `rm -rf ~/.claude/plugins/cache` 清除快取，重新啟動 Claude Code，然後重新安裝 plugin。

~~634~~

635如需詳細的故障排除和解決方案，請參閱市場指南中的[故障排除](/docs/zh-TW/plugin-marketplaces#troubleshooting)。如需偵錯工具，請參閱[偵錯和開發工具](/docs/zh-TW/plugins-reference#debugging-and-development-tools)。

~~636~~

637<h3 id="code-intelligence-issues">

638 程式碼智能問題

639</h3>

~~640~~

641* **語言伺服器未啟動**：驗證二進位檔已安裝且在您的 `$PATH` 中可用。檢查 `/plugin` Errors 標籤以獲取詳細資訊。

642* **高記憶體使用量**：`rust-analyzer` 和 `pyright` 等語言伺服器在大型專案上可能會消耗大量記憶體。如果您遇到記憶體問題，請使用 `/plugin disable <plugin-name>` 停用外掛程式，並改為依賴 Claude 的內建搜尋工具。

643* **monorepos 中的誤報診斷**：如果工作區配置不正確，語言伺服器可能會報告內部套件的未解決匯入錯誤。這些不會影響 Claude 編輯程式碼的能力。

~~644~~

645<h2 id="next-steps">

646 後續步驟

647</h2>

~~648~~

649* **構建您自己的外掛程式**：請參閱[外掛程式](/docs/zh-TW/plugins)以建立技能、代理和 hooks

650* **建立市場**：請參閱[建立外掛程式市場](/docs/zh-TW/plugin-marketplaces)以將外掛程式分發給您的團隊或社群

651* **技術參考**：請參閱[外掛程式參考](/docs/zh-TW/plugins-reference)以取得完整規格

env-vars.md +284 −282

Details

114 114

115在設定檔中，您可以設定變數，但無法移除變數。若要覆寫無法取消設定的變數，例如由您無法控制的 shell 設定檔匯出的過時 `CLAUDE_CODE_USE_VERTEX`，請在 `env` 區塊中將其設定為空字串：`"CLAUDE_CODE_USE_VERTEX": ""`。Claude Code 將空值視為未設定以進行提供者選擇。子程序仍會繼承空值。115在設定檔中，您可以設定變數，但無法移除變數。若要覆寫無法取消設定的變數，例如由您無法控制的 shell 設定檔匯出的過時 `CLAUDE_CODE_USE_VERTEX`，請在 `env` 區塊中將其設定為空字串：`"CLAUDE_CODE_USE_VERTEX": ""`。Claude Code 將空值視為未設定以進行提供者選擇。子程序仍會繼承空值。

116 116

117在設定檔之間，`env` 值遵循 [設定優先順序](/docs/zh-TW/settings#settings-precedence)，因此受管設定項目會覆寫使用者或專案設定中的相同變數。117在設定檔之間，`env` 值遵循 [設定優先順序](/docs/zh-TW/settings#settings-precedence)，因此受管設定項目會覆寫使用者或專案設定中的相同變數。專案和本機設定無法設定某些變數，例如 `CLAUDE_CONFIG_DIR` 和 OpenTelemetry 匯出器變數。[Claude Code 在 `env` 中忽略的變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 列出它們，以及仍然適用的 OpenTelemetry 關閉值。

118 118

119環境變數如何與 CLI 旗標和工作階段內命令互動因功能而異：`--model` 和 `/model` 會覆寫 `ANTHROPIC_MODEL`，而 `CLAUDE_CODE_EFFORT_LEVEL` 會覆寫 `--effort` 和 `/effort`。當變數與另一個設定來源互動時，[變數](#variables) 列表中的其列會說明優先順序或連結到記錄該項目的頁面。119環境變數如何與 CLI 旗標和工作階段內命令互動因功能而異：`--model` 和 `/model` 會覆寫 `ANTHROPIC_MODEL`，而 `CLAUDE_CODE_EFFORT_LEVEL` 會覆寫 `--effort` 和 `/effort`。當變數與另一個設定來源互動時，[變數](#variables) 列表中的其列會說明優先順序或連結到記錄該項目的頁面。

120 120

124 變數124 變數

125</h2>125</h2>

126 126

127數值變數（例如逾時、權杖預算和重試次數）除了接受純數字外，還接受科學記號和數字分隔符拼寫，除非變數的列說明它只接受純數字。例如，Claude Code 將 `2e3` 讀作 2000，將 `64_000` 讀作 64000。在 v2.1.211 之前，這些拼寫可能會無聲地設定一個更小的值，例如 `1e6` 將逾時設定為 1。127數值變數（例如逾時、權杖預算和重試次數）除了接受純數字外，還接受科學記號和數字分隔符拼寫，除非變數的列註明只接受純數字。例如，Claude Code 將 `2e3` 讀作 2000，將 `64_000` 讀作 64000。在 v2.1.211 之前，這些拼寫可能會無聲地設定一個更小的值，例如 `1e6` 將逾時設定為 1。

128 128

129<Note>129<Note>

130 對於開啟或關閉行為的變數，設定 `1` 或 `true` 以開啟，設定 `0` 或 `false` 以關閉，不分大小寫。130 對於開啟或關閉行為的變數，設定 `1` 或 `true` 以開啟，設定 `0` 或 `false` 以關閉，不分大小寫。

138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

139 * `IS_DEMO`139 * `IS_DEMO`

140 140

141 另一個變數有自己的規則：`FORCE_HYPERLINK` 讀取一個數字，所以只有 `0` 會關閉它。每個變數的列也說明了它自己的規則。141 另一個變數有自己的規則：`FORCE_HYPERLINK` 讀取一個數字，因此只有 `0` 會關閉它。每個變數的列也說明了自己的規則。

142</Note>142</Note>

143 143

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

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

146| `ANTHROPIC_API_KEY` | 作為 `X-Api-Key` 標頭傳送的 API 金鑰。設定時，即使您已登入，此金鑰也會用於代替您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式 (`-p`) 中，金鑰存在時始終使用。在互動模式中，系統會提示您在金鑰覆蓋訂閱之前批准一次。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |146| `ANTHROPIC_API_KEY` | 作為 `X-Api-Key` 標頭傳送的 API 金鑰。設定此金鑰時，即使您已登入，此金鑰也會用於代替您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式 (`-p`) 中，金鑰存在時始終使用。在互動模式中，系統會提示您在金鑰覆蓋訂閱之前批准一次。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |

148| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，在 AWS 主控台中產生。作為 `x-api-key` 傳送，優先於 AWS SigV4 |148| `ANTHROPIC_AWS_API_KEY` | [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，在 AWS 主控台中產生。作為 `x-api-key` 傳送，優先於 AWS SigV4 |

149| `ANTHROPIC_AWS_BASE_URL` | 覆蓋 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。預設為 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 使用 [Amazon Bedrock 上的相同優先順序](/docs/zh-TW/amazon-bedrock#3-configure-claude-code) 解析區域 |149| `ANTHROPIC_AWS_BASE_URL` | 覆蓋 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。預設為 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 使用 [Amazon Bedrock 上相同的優先順序](/docs/zh-TW/amazon-bedrock#3-configure-claude-code) 解析區域 |

150| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 所需。在每個請求上作為 `anthropic-workspace-id` 標頭傳送 |150| `ANTHROPIC_AWS_WORKSPACE_ID` | [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 所需。在每個請求上作為 `anthropic-workspace-id` 標頭傳送 |

151| `ANTHROPIC_BASE_URL` | 覆蓋 API 端點以透過代理或閘道路由請求。設定為非第一方主機時，[MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 預設停用。如果您的代理轉發 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，當此指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 被停用，與其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行為相符 |151| `ANTHROPIC_BASE_URL` | 覆蓋 API 端點以透過代理或閘道路由請求。設定為非第一方主機時，[MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 預設停用。如果您的代理轉發 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。從 v2.1.196 開始，當此指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 停用，與其在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的行為相符 |

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

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

154| `ANTHROPIC_BEDROCK_REGION_PREFIX` | 跨區域推論設定檔前綴（`us`、`eu`、`apac`、`jp`、`au` 或 `global`）Claude Code 首先嘗試而不是從 AWS 區域衍生的前綴。在 AWS GovCloud 區域中被忽略。需要 Claude Code v2.1.224 或更新版本。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#cross-region-inference-profile-prefixes) |154| `ANTHROPIC_BEDROCK_REGION_PREFIX` | 跨區域推論設定檔前綴（`us`、`eu`、`apac`、`jp`、`au` 或 `global`）Claude Code 首先嘗試，而不是從 AWS 區域衍生的前綴。在 AWS GovCloud 區域中忽略。需要 Claude Code v2.1.224 或更新版本。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#cross-region-inference-profile-prefixes) |

155| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服務層](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作為 `X-Amzn-Bedrock-Service-Tier` 標頭傳送。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#service-tiers) |155| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服務層](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作為 `X-Amzn-Bedrock-Service-Tier` 標頭傳送。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#service-tiers) |

156| `ANTHROPIC_BETAS` | 逗號分隔的其他 `anthropic-beta` 標頭值列表，以包含在 API 請求中。Claude Code 已傳送它需要的測試版標頭；在 Claude Code 新增原生支援之前，使用此變數選擇加入 [Anthropic API 測試版](https://platform.claude.com/docs/en/api/beta-headers)。與 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags)（需要 API 金鑰驗證）不同，此變數適用於所有驗證方法，包括 Claude.ai 訂閱 |156| `ANTHROPIC_BETAS` | 要包含在 API 請求中的其他 `anthropic-beta` 標頭值的逗號分隔列表。Claude Code 已傳送其需要的測試版標頭；在 Claude Code 新增原生支援之前，使用此變數選擇加入 [Anthropic API 測試版](https://platform.claude.com/docs/en/api/beta-headers)。與需要 API 金鑰驗證的 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags) 不同，此變數適用於所有驗證方法，包括 Claude.ai 訂閱 |

157| `ANTHROPIC_CUSTOM_HEADERS` | 要新增至請求的自訂標頭（`Name: Value` 格式，多個標頭以換行符分隔）。如果名稱或值包含 HTTP 標頭無法攜帶的字元（例如彎引號或零寬空格），請求會失敗並出現錯誤，該錯誤按位置識別該對。需要 Claude Code v2.1.227 或更新版本。[無效的請求標頭值](/docs/zh-TW/errors#invalid-request-header-value) 列出確切的字元集和檢查執行的位置。設定認證、組織或租戶、路由或 API 行為標頭（例如 `Authorization` 或 `Host`）的值在伺服器管理的設定傳遞時計為 [需要批准的設定](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)。從專案或本機設定，此類值遵循 [何時應用 `env` 值的規則](/docs/zh-TW/settings-reference#when-claude-code-applies-env-values) |157| `ANTHROPIC_CUSTOM_HEADERS` | 要新增至請求的自訂標頭（`Name: Value` 格式，多個標頭以換行符分隔）。如果名稱或值包含 HTTP 標頭無法攜帶的字元（例如彎引號或零寬空格），請求會失敗並出現錯誤，該錯誤按位置識別該對。需要 Claude Code v2.1.227 或更新版本。[無效的請求標頭值](/docs/zh-TW/errors#invalid-request-header-value) 列出確切的字元集以及檢查執行的位置。設定認證、組織或租戶、路由或 API 行為標頭（例如 `Authorization` 或 `Host`）的值在伺服器管理的設定傳遞時計為 [需要批准的設定](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)。從專案或本機設定，此類值遵循 [何時 `env` 值適用的規則](/docs/zh-TW/settings-reference#when-claude-code-applies-env-values) |

158| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 模型 ID，作為自訂項目新增至 `/model` 選擇器。使用此選項可以選擇非標準或閘道特定的模型，而無需替換內建別名。請參閱 [模型配置](/docs/zh-TW/model-config#add-a-custom-model-option) |158| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 模型 ID，作為自訂項目新增至 `/model` 選擇器。使用此選項可使非標準或閘道特定的模型可選，而無需替換內建別名。請參閱 [模型設定](/docs/zh-TW/model-config#add-a-custom-model-option) |

160| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 選擇器中自訂模型項目的顯示名稱。未設定時，如果 Claude Code [識別 ID](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，項目會顯示模型的名稱，否則顯示模型 ID |160| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 選擇器中自訂模型項目的顯示名稱。未設定時，如果 Claude Code [識別 ID](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，項目會顯示模型的名稱，否則顯示模型 ID |

161| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 自訂模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔列表，例如 `effort,thinking`。請參閱 [模型配置](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |161| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 自訂模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔列表，例如 `effort,thinking`。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

162| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 別名解析為的模型 ID，以及 Claude Code 識別為 Fable 模型的 ID，用於第三方提供者上的 [自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)。請參閱 [模型配置](/docs/zh-TW/model-config#environment-variables) |162| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 別名解析為的模型 ID，以及 Claude Code 識別為 Fable 模型的 ID，用於第三方提供者上的 [自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)。請參閱 [模型設定](/docs/zh-TW/model-config#environment-variables) |

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

164| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 選擇器中釘選 Fable 模型的顯示名稱。未設定時，如果 Claude Code 識別釘選 ID，列會顯示模型的名稱，否則顯示釘選 ID。請參閱 [模型配置](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |164| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 選擇器中釘選 Fable 模型的顯示名稱。未設定時，如果 Claude Code 識別釘選 ID，列會顯示模型的名稱，否則顯示釘選 ID。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

165| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 釘選 Fable 模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔列表，例如 `effort,thinking`。請參閱 [模型配置](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |165| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 釘選 Fable 模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔列表，例如 `effort,thinking`。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

166| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 別名解析為的模型 ID，也用於 [背景功能](/docs/zh-TW/costs#background-token-usage)。請參閱 [模型配置](/docs/zh-TW/model-config#environment-variables) |166| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 別名解析為的模型 ID，也用於 [背景功能](/docs/zh-TW/costs#background-token-usage)。請參閱 [模型設定](/docs/zh-TW/model-config#environment-variables) |

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

168| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 選擇器中釘選 Haiku 模型的顯示名稱。未設定時，如果 Claude Code 識別釘選 ID，列會顯示模型的名稱，否則顯示釘選 ID。請參閱 [模型配置](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |168| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 選擇器中釘選 Haiku 模型的顯示名稱。未設定時，如果 Claude Code 識別釘選 ID，列會顯示模型的名稱，否則顯示釘選 ID。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 釘選 Haiku 模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔列表，例如 `effort,thinking`。請參閱 [模型配置](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 釘選 Haiku 模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔列表，例如 `effort,thinking`。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

170| `ANTHROPIC_DEFAULT_MODEL` | 新工作階段預設啟動的模型。需要 Claude Code v2.1.236 或更新版本。請參閱 [為新工作階段設定預設模型](/docs/zh-TW/model-config#set-a-default-model-for-new-sessions) |170| `ANTHROPIC_DEFAULT_MODEL` | 新工作階段預設啟動的模型。需要 Claude Code v2.1.236 或更新版本。請參閱 [為新工作階段設定預設模型](/docs/zh-TW/model-config#set-a-default-model-for-new-sessions) |

171| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 別名解析為的模型 ID，以及 Plan Mode 啟用時 `opusplan` 使用的模型 ID。請參閱 [模型配置](/docs/zh-TW/model-config#environment-variables) |171| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 別名解析為的模型 ID，以及 Plan Mode 啟用時 `opusplan` 使用的模型 ID。請參閱 [模型設定](/docs/zh-TW/model-config#environment-variables) |

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

173| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 選擇器中釘選 Opus 模型的顯示名稱。未設定時，如果 Claude Code 識別釘選 ID，列會顯示模型的名稱，否則顯示釘選 ID。請參閱 [模型配置](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |173| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 選擇器中釘選 Opus 模型的顯示名稱。未設定時，如果 Claude Code 識別釘選 ID，列會顯示模型的名稱，否則顯示釘選 ID。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

174| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 釘選 Opus 模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔列表，例如 `effort,thinking`。請參閱 [模型配置](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |174| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 釘選 Opus 模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔列表，例如 `effort,thinking`。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名解析為的模型 ID，以及 Plan Mode 未啟用時 `opusplan` 使用的模型 ID。請參閱 [模型配置](/docs/zh-TW/model-config#environment-variables) |175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名解析為的模型 ID，以及 Plan Mode 未啟用時 `opusplan` 使用的模型 ID。請參閱 [模型設定](/docs/zh-TW/model-config#environment-variables) |

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

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

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

179| `ANTHROPIC_FEDERATION_RULE_ID` | [工作負載身份聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的聯盟規則 ID。與 `ANTHROPIC_ORGANIZATION_ID` 一起設定時，Claude Code 選擇聯盟認證，其優先順序高於您的 `/login` 認證。請參閱 [驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |179| `ANTHROPIC_FEDERATION_RULE_ID` | [工作負載身份聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的聯盟規則 ID。當您將其與 `ANTHROPIC_ORGANIZATION_ID` 一起設定時，Claude Code 選擇聯盟認證，其優先於您的 `/login` 認證。請參閱 [驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

181| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Microsoft Foundry 驗證的持有人權杖，例如 Microsoft Entra 存取權杖。Claude Code 將其作為 `Authorization: Bearer` 標頭傳送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 預設認證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |181| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Microsoft Foundry 驗證的持有人權杖，例如 Microsoft Entra 存取權杖。Claude Code 將其作為 `Authorization: Bearer` 標頭傳送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 預設認證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |

182| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基礎 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。`ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |182| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基礎 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。`ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如 `my-resource`）。如果未設定 `ANTHROPIC_FOUNDRY_BASE_URL`，則為必需（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如 `my-resource`）。如果未設定 `ANTHROPIC_FOUNDRY_BASE_URL`，則為必需（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

185| `ANTHROPIC_ORGANIZATION_ID` | [工作負載身份聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的組織 ID。與 `ANTHROPIC_FEDERATION_RULE_ID` 一起設定。請參閱 [驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |185| `ANTHROPIC_ORGANIZATION_ID` | [工作負載身份聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的組織 ID。與 `ANTHROPIC_FEDERATION_RULE_ID` 一起設定。請參閱 [驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

186| `ANTHROPIC_PROFILE` | 要驗證的 Anthropic 設定檔名稱，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 建立的或透過 [登入沒有 API 金鑰的主控台帳戶](/docs/zh-TW/authentication#sign-in-without-an-api-key) 建立的。請參閱 [驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |186| `ANTHROPIC_PROFILE` | 要驗證的 Anthropic 設定檔名稱，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 建立的或透過 [登入沒有 API 金鑰的 Console 帳戶](/docs/zh-TW/authentication#sign-in-without-an-api-key) 建立的。請參閱 [驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

188| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時，覆蓋 Haiku 級模型的 AWS 區域。在 Amazon Bedrock 上，只有在同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時，此設定才會生效，因為 Amazon Bedrock 否則會在 [預設 Sonnet 模型或工作階段區域中的主要模型](/docs/zh-TW/amazon-bedrock#4-pin-model-versions) 上執行背景工作 |188| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時覆蓋 Haiku 級模型的 AWS 區域。在 Amazon Bedrock 上，只有在同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時，此設定才會生效，因為 Amazon Bedrock 否則會在工作階段區域中的 [預設 Sonnet 模型或主要模型](/docs/zh-TW/amazon-bedrock#4-pin-model-versions) 上執行背景工作 |

189| `ANTHROPIC_VERTEX_BASE_URL` | 覆蓋 Google Cloud's Agent Platform 端點 URL。用於自訂 Google Cloud's Agent Platform 端點或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |189| `ANTHROPIC_VERTEX_BASE_URL` | 覆蓋 Google Cloud 的 Agent Platform 端點 URL。用於自訂 Google Cloud 的 Agent Platform 端點或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。請參閱 [Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) |

190| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 請求所定址的 GCP 專案 ID。請參閱 [配置 GCP 認證](/docs/zh-TW/google-vertex-ai#3-configure-gcp-credentials) |190| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud 的 Agent Platform 請求所定址的 GCP 專案 ID。請參閱 [設定 GCP 認證](/docs/zh-TW/google-vertex-ai#3-configure-gcp-credentials) |

191| `ANTHROPIC_WORKSPACE_ID` | [工作負載身份聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯盟規則範圍涵蓋多個工作區時設定此項，以便權杖交換知道要定位哪個工作區 |191| `ANTHROPIC_WORKSPACE_ID` | [工作負載身份聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯盟規則範圍涵蓋多個工作區時設定此項，以便權杖交換知道要定位哪個工作區 |

192| `API_FORCE_IDLE_TIMEOUT` | 覆蓋 5 分鐘的主體閒置逾時，該逾時在沒有位元組到達時中止串流模型回應。設定為 `0` 以關閉逾時，例如當緩慢的 [閘道](/docs/zh-TW/llm-gateway) 或本機模型在區塊之間暫停超過 5 分鐘時，或設定為 `1` 以為每個提供者保持開啟。未設定時，逾時在除直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 以外的提供者上啟用。[串流看門狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) 獨立執行，即使您在此設定 `0`，也會中止長時間的無聲暫停 |192| `API_FORCE_IDLE_TIMEOUT` | 覆蓋 5 分鐘的主體閒置逾時，當沒有位元組到達時中止串流模型回應。設定為 `0` 以關閉逾時，例如當緩慢的 [閘道](/docs/zh-TW/llm-gateway) 或本機模型在區塊之間暫停超過 5 分鐘時，或設定為 `1` 以為每個提供者保持開啟。未設定時，逾時在直接 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 以外的提供者上啟用。[串流監視狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) 獨立執行，即使您在此設定 `0`，也會中止長時間的無聲暫停 |

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

196| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 讀回命令結果的 bash 輸出的最大字元數（預設：30000；最大：150000）。如果您設定 [`bashOutputMaxChars`](/docs/zh-TW/settings-reference#bashoutputmaxchars) 設定，Claude Code 會忽略此變數。請參閱 [輸出限制](/docs/zh-TW/tools-reference#output-limits) |196| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 讀回命令結果的 bash 輸出的最大字元數（預設：30000；最大：150000）。如果您設定 [`bashOutputMaxChars`](/docs/zh-TW/settings-reference#bashoutputmaxchars) 設定，Claude Code 會忽略此變數。請參閱 [輸出限制](/docs/zh-TW/tools-reference#output-limits) |

198| `BETA_TRACING_ENDPOINT` | [詳細測試版追蹤](/docs/zh-TW/monitoring-usage#traces-beta) 的 OTLP 端點：使用 `ENABLE_BETA_TRACING_DETAILED=1`，日誌和追蹤會傳送到那裡而不是配置的匯出器。在您的 shell、使用者設定或受管設定中設定。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |198| `BETA_TRACING_ENDPOINT` | [詳細測試版追蹤](/docs/zh-TW/monitoring-usage#traces-beta) 的 OTLP 端點：使用 `ENABLE_BETA_TRACING_DETAILED=1`，日誌和追蹤會傳送到那裡，而不是配置的匯出器。在您的 shell、使用者設定或受管設定中設定。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略 |

199| `CCR_FORCE_BUNDLE` | 設定為 `1` 以強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 捆綁並上傳您的本機儲存庫，而不是從其遠端複製 |199| `CCR_FORCE_BUNDLE` | 設定為 `1` 以強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 捆綁並上傳您的本機儲存庫，而不是從其遠端複製 |

200| `CLAUDECODE` | 在 Claude Code 產生的子程序中設定為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline) 命令、stdio [MCP 伺服器](/docs/zh-TW/mcp) 子程序）。IDE 擴充功能也在其整合終端中設定此項。用於偵測指令碼何時在 Claude Code 產生的子程序內執行。若要檢查目前程序是由工具呼叫或 hook 直接產生，而不是在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |200| `CLAUDECODE` | 在 Claude Code 產生的子程序中設定為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline) 命令、stdio [MCP 伺服器](/docs/zh-TW/mcp) 子程序）。IDE 擴充功能也在其整合終端中設定此項。用於偵測指令碼何時在 Claude Code 產生的子程序內執行。若要檢查目前程序是由工具呼叫或 hook 直接產生，而不是在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |

201| `CLAUDE_AFK_COUNTDOWN_MS` | 自動繼續前，螢幕上倒數計時出現在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框上的毫秒數。預設 `20000`（20 秒），上限為自動繼續逾時。除非自動繼續開啟，否則無效；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |201| `CLAUDE_AFK_COUNTDOWN_MS` | 在自動繼續前多少毫秒螢幕上的倒數計時器會出現在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話上。預設 `20000`（20 秒），上限為自動繼續逾時。除非自動繼續開啟，否則無效；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |

202| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框在沒有您的情況下自動繼續之前的閒置時間（毫秒）。自動繼續預設關閉；使用 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定選擇加入。此變數是演示和自動化測試的覆蓋：設定時，它優先於該設定，即使設定未設定或為 `never`，也會開啟自動繼續。設定 `0` 不會關閉逾時；它會立即關閉對話框。在 v2.1.198 和 v2.1.199 中，自動繼續預設開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |202| `CLAUDE_AFK_TIMEOUT_MS` | 在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話自動繼續而不需要您之前的閒置時間（毫秒）。自動繼續預設關閉；使用 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定選擇加入。此變數是演示和自動化測試的覆蓋：設定時，它優先於該設定，即使設定未設定或為 `never`，也會開啟自動繼續。設定 `0` 不會關閉逾時；它會立即關閉對話。在 v2.1.198 和 v2.1.199 中，自動繼續預設開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |

203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [子代理](/docs/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用。這也會移除 `general-purpose`，即當 Agent 工具呼叫省略 `subagent_type` 時 Claude Code 執行的子代理。此類呼叫隨後會失敗，並出現 [`subagent_type is required`](/docs/zh-TW/errors#subagent-type-is-required) |203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [子代理](/docs/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用。這也會移除 `general-purpose`，即當 Agent 工具呼叫省略 `subagent_type` 時 Claude Code 執行的子代理。此類呼叫隨後會失敗，並出現 [`subagent_type is required`](/docs/zh-TW/errors#subagent-type-is-required) |

205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滯逾時（毫秒）。預設 `600000`（10 分鐘）；如果您在串流看門狗開啟時提高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，預設會隨之上升，如 [處理緩慢或停滯的 API 回應](/docs/zh-TW/agent-sdk/typescript#handle-slow-or-stalled-api-responses) 所述。計時器在每個串流進度事件上重設；如果在視窗內沒有進度到達，Claude Code 會中止子代理並向父代報告停滯 |205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滯逾時（毫秒）。預設 `600000`（10 分鐘）；如果您在串流監視狗開啟時提高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，預設會隨之上升，如 [處理緩慢或停滯的 API 回應](/docs/zh-TW/agent-sdk/typescript#handle-slow-or-stalled-api-responses) 所述。計時器在每個串流進度事件上重設；如果在視窗內沒有進度到達，Claude Code 會中止子代理並向父代理報告停滯 |

206| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮視窗的百分比（1-100），自動壓縮在該百分比觸發。使用較低的值（如 `50`）以更早壓縮；變數無法提高閾值，因此高於預設百分比的值會被忽略。它僅適用於在模型的上下文限制之前 [壓縮](/docs/zh-TW/model-config#context-window-and-auto-compaction) 的工作階段。適用於主要對話和子代理 |206| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮視窗的百分比（1-100），自動壓縮在該百分比觸發。使用較低的值（如 `50`）以更早壓縮；變數無法提高閾值，因此高於預設百分比的值會被忽略。它僅適用於在模型的上下文限制之前 [壓縮的工作階段](/docs/zh-TW/model-config#context-window-and-auto-compaction)。適用於主要對話和子代理 |

207| `CLAUDE_AUTO_BACKGROUND_TASKS` | 設定為 `1` 以強制啟用長時間執行代理工作的自動背景化。啟用時，子代理在執行約兩分鐘後會移至背景。也在 Claude Code v2.1.212 或更新版本的非互動模式中啟用 [長 MCP 工具呼叫的自動背景化](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) |207| `CLAUDE_AUTO_BACKGROUND_TASKS` | 設定為 `1` 以強制啟用長時間執行代理工作的自動背景化。啟用時，子代理在執行約兩分鐘後會移至背景。也在 Claude Code v2.1.212 或更新版本的非互動模式中啟用 [長 MCP 工具呼叫的自動背景化](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) |

208| `CLAUDE_AX_PREPARK_MS` | 在 [螢幕閱讀器模式](/docs/zh-TW/accessibility#what-your-screen-reader-hears) 中，Claude Code 在游標位於行首時等待的毫秒數，然後才寫入新的或變更的行。預設 `50`。設定 `0` 以立即寫入。Claude Code 將等待上限設定為 `5000`。需要 Claude Code v2.1.233 或更新版本 |208| `CLAUDE_AX_PREPARK_MS` | 在 [螢幕閱讀器模式](/docs/zh-TW/accessibility#what-your-screen-reader-hears) 中，Claude Code 在游標位於行首時等待多少毫秒，然後才寫入新的或變更的行。預設 `50`。設定 `0` 以立即寫入。Claude Code 將等待上限設為 `5000`。需要 Claude Code v2.1.233 或更新版本 |

209| `CLAUDE_AX_SCREEN_READER` | 設定為 `1` 以呈現螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。設定為 `0` 以強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 為 `true`。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |209| `CLAUDE_AX_SCREEN_READER` | 設定為 `1` 以呈現螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。設定為 `0` 以強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 為 `true`。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |

210| `CLAUDE_AX_STARTUP_QUIET_MS` | 在 [螢幕閱讀器模式](/docs/zh-TW/accessibility) 中，Claude Code 在啟動確認行後保持第一個介面呈現的毫秒數，以便您的螢幕閱讀器可以在新輸出中斷之前完整說出該行。預設 `3000`。設定 `0` 以立即呈現。Claude Code 將保持上限設定為 `600000`（10 分鐘）。您的第一次按鍵會提前結束保持。需要 Claude Code v2.1.217 或更新版本 |210| `CLAUDE_AX_STARTUP_QUIET_MS` | 在 [螢幕閱讀器模式](/docs/zh-TW/accessibility) 中，Claude Code 在啟動確認行後保持第一個介面呈現多少毫秒，以便您的螢幕閱讀器可以在新輸出中斷之前完整朗讀該行。預設 `3000`。設定 `0` 以立即呈現。Claude Code 將保持上限設為 `600000`（10 分鐘）。您的第一次按鍵會提前結束保持。需要 Claude Code v2.1.217 或更新版本 |

212| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組級串流閒置看門狗的逾時（毫秒）；設定時，它優先於 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 用於該看門狗，並保持事件級看門狗不變。Claude Code 將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |212| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組級串流閒置監視狗的逾時（毫秒）；設定時，它優先於該監視狗的 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，並保持事件級監視狗不變。Claude Code 將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |

213| `CLAUDE_CLIENT_PRESENCE_FILE` | 外部工具（例如螢幕鎖定監聽器）在您解鎖螢幕時建立並在您鎖定螢幕時刪除的檔案路徑。檔案存在時，Claude Code 會跳過 [Remote Control 行動推送通知](/docs/zh-TW/remote-control#mobile-push-notifications)，因此您在主動使用電腦時不會收到推送。檔案不存在或無法讀取時，通知會正常傳送。Claude Code 每次推送觸發事件檢查一次檔案，而不是輪詢。需要 Claude Code v2.1.181 或更新版本 |213| `CLAUDE_CLIENT_PRESENCE_FILE` | 外部工具（例如螢幕鎖定監聽器）在您解鎖螢幕時建立並在您鎖定螢幕時刪除的檔案路徑。檔案存在時，Claude Code 會跳過 [Remote Control 行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)，因此當您主動使用電腦時，您會停止接收推播。檔案不存在或無法讀取時，通知會正常傳送。Claude Code 每次推播觸發事件檢查一次檔案，而不是輪詢。需要 Claude Code v2.1.181 或更新版本 |

215| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設定為 `1` 以從使用 `--add-dir` 指定的目錄載入記憶體檔案。載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。預設情況下，其他目錄不載入記憶體檔案 |215| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設定為 `1` 以從使用 `--add-dir` 指定的目錄載入記憶體檔案。載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。預設情況下，其他目錄不載入記憶體檔案 |

216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設定為 `1` 以在 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的每一幀上重新繪製整個螢幕，而不是傳送增量更新。如果全螢幕模式顯示過時或錯位的文字片段，請使用此選項。Claude Code 在 Windows 上的背景工作階段和 [代理檢視](/docs/zh-TW/agent-view) 上自動啟用此功能 |216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設定為 `1` 以在 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的每一幀上重新繪製整個螢幕，而不是傳送增量更新。如果全螢幕模式顯示過時或錯位的文字片段，請使用此選項。Claude Code 在 Windows 上的背景工作階段和 [代理檢視](/docs/zh-TW/agent-view) 上自動啟用此功能 |

217| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設定為 `1` 以在每個請求中傳送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 不識別模型 ID 為支援 effort。在透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 或第三方提供者以自訂識別碼提供模型時使用。在 API 拒絕 effort 參數的模型（包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5）仍被排除，因此請求不會失敗 |217| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設定為 `1` 以在每個請求中傳送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 不識別模型 ID 為支援 effort 的模型。在透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 或第三方提供者以自訂識別碼提供模型時使用此選項。在 API 拒絕 effort 參數的模型（包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5）仍被排除，因此請求不會失敗 |

218| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 應重新整理認證的間隔（毫秒）（使用 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 時） |218| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 應重新整理認證的間隔（毫秒）（使用 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 時） |

219| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設定為 `0` 以停止 Claude Code 在發佈新 [artifact](/docs/zh-TW/artifacts#create-an-artifact) 時自動開啟瀏覽器 |219| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設定為 `0` 以停止 Claude Code 在發佈新 [成品](/docs/zh-TW/artifacts#create-an-artifact) 時自動開啟瀏覽器 |

220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 設定為 `0` 以停止 Claude 讀取和回覆 [artifact 上的評論](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)。當 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` [關閉 artifact](/docs/zh-TW/artifacts#availability) 時無效。需要 Claude Code v2.1.221 或更新版本 |220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 設定為 `0` 以停止 Claude 讀取和回覆 [成品上的評論](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)。當 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` [關閉成品](/docs/zh-TW/artifacts#availability) 時無效。需要 Claude Code v2.1.221 或更新版本 |

221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 設定為 `0` 以停止 Claude [自動回覆傳送給它的評論](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更新版本 |221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 設定為 `0` 以停止 Claude [自行回覆傳送給它的評論](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更新版本 |

222| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以從系統提示的開頭省略 [歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)，該區塊攜帶用戶端版本和提示指紋。直接連線到 Anthropic API 的快取不受影響。在某些直接連線設定中，Claude Code 在 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器請求上保持區塊，即使您設定 `0`。在 [系統提示歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block) 中，檢查此涵蓋哪些連線和認證。在 v2.1.181 之前，該區塊在自訂基礎 URL 和 Microsoft Foundry 連線上包含每個請求的權杖，因此在這些版本上，當您的 LLM 閘道在請求主體上快取或將請求轉發給第三方提供者時，或當您直接連線到 Microsoft Foundry 時，將其設定為 `0` |222| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以從系統提示的開頭省略 [歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)，該區塊攜帶用戶端版本和提示指紋。直接連線到 Anthropic API 的快取無論如何都不受影響。在某些直接連線設定中，Claude Code 在 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器請求上保持區塊，即使您設定 `0`。在 [系統提示歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block) 中，檢查此涵蓋哪些連線和認證。在 v2.1.181 之前，該區塊在自訂基礎 URL 和 Microsoft Foundry 連線上包含每個請求的權杖，因此在這些版本上，當您的 LLM 閘道在請求主體上快取或將請求轉發給第三方提供者，或當您直接連線到 Microsoft Foundry 時，將其設定為 `0` |

223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | 啟用 `CLAUDE_AUTO_BACKGROUND_TASKS` 時，提醒 Claude 檢查仍在執行的 [背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 之間的秒數。僅接受 `1` 到 `86400` 的純整數；任何其他值或拼寫讀作未設定。未設定時，沒有檢查提醒。需要 Claude Code v2.1.248 或更新版本 |223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | 啟用 `CLAUDE_AUTO_BACKGROUND_TASKS` 時，提醒 Claude 檢查仍在執行的 [背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 之間的秒數。僅接受 `1` 到 `86400` 的純整數；任何其他值或拼寫讀作未設定。未設定時，沒有檢查提醒。需要 Claude Code v2.1.248 或更新版本 |

224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)（權杖），從 `100000` 到 `1000000`。僅接受純整數（如 `500000`）：像 `500k` 這樣的值讀作 `500` 並限制在 100K 最小值。有效視窗也上限為模型的上下文視窗。優先於 `/autocompact` 命令、`--autocompact` 旗標和 `autoCompactWindow` 設定。狀態列的 `used_percentage` 始終針對模型的完整上下文視窗進行測量，因此一旦設定此變數，該百分比不再指示何時會執行壓縮 |224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)（權杖），從 `100000` 到 `1000000`。僅接受純整數（如 `500000`）：像 `500k` 這樣的值讀作 `500` 並限制在 100K 最小值。有效視窗也上限為模型的上下文視窗。優先於 `/autocompact` 命令、`--autocompact` 旗標和 `autoCompactWindow` 設定。狀態列的 `used_percentage` 始終針對模型的完整上下文視窗進行測量，因此一旦設定此變數，該百分比不再指示何時會執行壓縮 |

225| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE 連線](/docs/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 隱藏父終端時。優先於 [`autoConnectIde`](/docs/zh-TW/settings-reference#autoconnectide) 全域配置設定 |225| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE 連線](/docs/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 隱藏父終端時。優先於 [`autoConnectIde`](/docs/zh-TW/settings-reference#autoconnectide) 全域設定 |

226| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否要求伺服器 [檢查自動模式動作](/docs/zh-TW/permission-modes#server-side-classifier-review)。未設定時，Claude Code 在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上要求伺服器，以及當您指向 `ANTHROPIC_BASE_URL` 至 LLM 閘道或代理時。設定為 `0` 以改用 Claude Code 自己的分類器請求。不在直接連線到 Anthropic API 時讀取。需要 Claude Code v2.1.271 或更新版本；預設要求伺服器需要 v2.1.278 或更新版本 |226| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否要求伺服器 [檢查自動模式動作](/docs/zh-TW/permission-modes#server-side-classifier-review)。設定為 `0` 以改用 Claude Code 自己的分類器請求。在直接連線到 Anthropic API 上，需要 v2.1.281 或更新版本。連結的部分列出當變數未設定時哪些工作階段要求伺服器，以及從哪個版本開始。需要 Claude Code v2.1.271 或更新版本 |

227| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設認證提供者鏈產生認證的時間（毫秒），然後請求失敗，並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)（預設：`60000`）。當鏈中的步驟合法需要更長時間時提高此值，例如透過 `aws-vault` 等包裝器進行基於瀏覽器的 SSO 登入（帶 MFA）。適用於 Claude Code 使用預設鏈簽署的任何地方：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 和 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更新版本 |227| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設認證提供者鏈產生認證的時間（毫秒），然後請求失敗，並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)（預設：`60000`）。當鏈中的步驟合法需要更長時間時提高此值，例如透過 `aws-vault` 等包裝器進行 MFA 的瀏覽器型 SSO 登入。適用於 Claude Code 使用預設鏈簽署的任何地方：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)、[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 和 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更新版本 |

228| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設定為 `0` 以關閉 [Bash 命令變更的檔案差異](/docs/zh-TW/hooks#bash)，或設定為 `1` 以在每個權限模式中記錄。優先於 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |228| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設定為 `0` 以關閉 [Bash 命令執行時變更的檔案的差異](/docs/zh-TW/hooks#bash)，或設定為 `1` 以在每個權限模式中記錄。優先於 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |

229| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設定為 `0` 以使非互動工作階段在每個轉結束時向其主機報告閒置狀態，即使背景工作仍在執行。預設情況下，工作階段在背景工作（例如背景代理或 [工作流程](/docs/zh-TW/workflows) 執行）仍在進行時，保持在轉結束後報告執行狀態。這可防止監視狀態的主機（例如遠端工作階段清單）在工作中途宣佈 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不保持執行狀態。執行狀態預設和 `0` 選擇退出需要 Claude Code v2.1.269 或更新版本；在較早版本上，設定 `1` 以保持執行狀態 |229| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設定為 `0` 以使非互動工作階段在每個轉向結束時向其主機報告閒置狀態，即使背景工作仍在執行。預設情況下，工作階段在背景工作（例如背景代理或 [工作流](/docs/zh-TW/workflows) 執行）仍在進行時，會在轉向結束後繼續報告執行狀態。這可防止監視狀態的主機（例如遠端工作階段列表）在工作中途宣佈 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不會保持執行狀態。執行狀態預設和 `0` 選擇退出需要 Claude Code v2.1.269 或更新版本；在較早的版本上，設定 `1` 以保持執行狀態 |

230| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 在工作階段有活躍 [Remote Control](/docs/zh-TW/remote-control) 連線時，在 Bash 工具和 [hook 命令](/docs/zh-TW/hooks) 子程序中自動設定，連線結束時移除。值是工作階段在 `session_` 形式中的 ID，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在 [雲工作階段](/docs/zh-TW/claude-code-on-the-web) 中，改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |230| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 在工作階段有活躍 [Remote Control](/docs/zh-TW/remote-control) 連線時在 Bash 工具和 [hook 命令](/docs/zh-TW/hooks) 子程序中自動設定，連線結束時移除。值是工作階段在 `session_` 形式中的 ID，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在 [雲工作階段](/docs/zh-TW/claude-code-on-the-web) 中，改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

231| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 設定為 `0` 以使 Claude Code 將 `0x08` 位元組（也寫作 `^H`）讀作純 Backspace，或設定為 `1` 以讀作 Ctrl+Backspace。任一值都會替換平台預設。預設情況下，Claude Code 在 Windows 上將其讀作 Ctrl+Backspace，除非 `TERM_PROGRAM` 是 `mintty` 或 `TERM` 是 `cygwin`，在 macOS 和 Linux 上讀作純 Backspace。在 Windows 終端中設定 `0`，其中 [Backspace 刪除整個單詞](/docs/zh-TW/terminal-config#fix-backspace-deleting-a-whole-word-on-windows) |231| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 設定為 `0` 以使 Claude Code 將 `0x08` 位元組（也寫作 `^H`）讀作純 Backspace，或設定為 `1` 以讀作 Ctrl+Backspace。任一值都會替換平台預設。預設情況下，Claude Code 在 Windows 上將其讀作 Ctrl+Backspace，除非 `TERM_PROGRAM` 是 `mintty` 或 `TERM` 是 `cygwin`，在 macOS 和 Linux 上讀作純 Backspace。在 Windows 終端中設定 `0`，其中 [Backspace 刪除整個單詞](/docs/zh-TW/terminal-config#fix-backspace-deleting-a-whole-word-on-windows) |

232| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源的逗號分隔列表。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集。`system` 是作業系統信任存放區，僅在具有 `tls.getCACertificates` 的執行時上讀取：原生二進位檔或 npm 安裝的 Node 22.15 或更新版本。請參閱 [CA 憑證存放區](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |232| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源的逗號分隔列表。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集。`system` 是作業系統信任存放區，僅在具有 `tls.getCACertificates` 的執行時上讀取：原生二進位檔或 npm 安裝的 Node 22.15 或更新版本。請參閱 [CA 憑證存放區](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |

233| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令和 [狀態列](/docs/zh-TW/statusline) 命令產生的子程序中設定為 `1`。未針對 stdio [MCP 伺服器](/docs/zh-TW/mcp) 子程序設定，這些子程序是長期存在的，並且超過產生它們的工作階段。與 `CLAUDECODE` 不同，此項僅在 Claude Code 啟動子程序時由 Claude Code 本身設定，而不是由 IDE 擴充功能設定，因此它可靠地區分嵌套工作階段與在 IDE 整合終端中啟動的頂級 `claude`。以這種方式啟動的嵌套互動 `claude` TUI 會自動從 `--resume`、`--continue`、向上箭頭歷史記錄和 `claude agents` 列表中排除。非互動 `claude -p` 工作階段仍然持續。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 以覆蓋此排除。需要 Claude Code v2.1.172 或更新版本 |233| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令和 [狀態列](/docs/zh-TW/statusline) 命令產生的子程序中設定為 `1`。未針對 stdio [MCP 伺服器](/docs/zh-TW/mcp) 子程序設定，這些子程序是長期存在的，並且超過產生它們的工作階段。與 `CLAUDECODE` 不同，此僅在 Claude Code 啟動子程序時由 Claude Code 本身設定，而不是由 IDE 擴充功能設定，因此它可靠地區分嵌套工作階段與在 IDE 整合終端中啟動的頂級 `claude`。以這種方式啟動的嵌套互動 `claude` TUI 會自動從 `--resume`、`--continue`、向上箭頭歷史記錄和 `claude agents` 列表中排除。非互動 `claude -p` 工作階段仍然持續。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 以覆蓋此排除。需要 Claude Code v2.1.172 或更新版本 |

237| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中移除，現在是無操作。以前為串流 API 請求的連線、TLS 和回應標頭階段設定單獨的逾時。使用 `API_TIMEOUT_MS` 進行每個請求的逾時。對於串流請求的回應標頭階段，請參閱 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |237| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中移除，現在是無操作。先前為串流 API 請求的連線、TLS 和回應標頭階段設定單獨的逾時。使用 `API_TIMEOUT_MS` 進行每個請求的逾時。對於串流請求的回應標頭階段，請參閱 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |

238| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆蓋偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑，而不是目錄。需要透過 `--debug`、`/debug` 或 `DEBUG` 環境變數單獨啟用偵錯模式：僅設定此變數不會啟用日誌記錄。[`--debug-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標同時執行兩者。預設為 `~/.claude/debug/<session-id>.txt` |238| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆蓋偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑，而不是目錄。需要透過 `--debug`、`/debug` 或 `DEBUG` 環境變數單獨啟用偵錯模式：僅設定此變數不會啟用日誌記錄。[`--debug-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標同時執行兩者。預設為 `~/.claude/debug/<session-id>.txt` |

239| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最小日誌級別。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 以包含高容量診斷（如完整狀態列命令輸出），或提高到 `error` 以減少雜訊 |239| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最小日誌級別。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 以包含高容量診斷（如完整狀態列命令輸出），或提高到 `error` 以減少雜訊 |

240| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 以停用 [1M 上下文視窗](/docs/zh-TW/model-config#extended-context) 支援。設定時，1M 模型變體在模型選擇器中不可用，Claude Code 將具有原生 1M 視窗的模型上的工作階段保持在 200K 視窗，例如 [Sonnet 5](/docs/zh-TW/model-config#sonnet-5-context-window) 和 Fable 模型；請參閱 [擴展上下文](/docs/zh-TW/model-config#extended-context) 以了解如何強制執行保持。對於具有合規要求的企業環境很有用。有關其在為無法識別的 `[1m]` 模型 ID 更正視窗中的角色，請參閱 [為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |240| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 以停用 [1M 上下文視窗](/docs/zh-TW/model-config#extended-context) 支援。設定時，1M 模型變體在模型選擇器中不可用，Claude Code 將具有原生 1M 視窗的模型上的工作階段保持在 200K 視窗，例如 [Sonnet 5](/docs/zh-TW/model-config#sonnet-5-context-window) 和 Fable 模型；請參閱 [擴充上下文](/docs/zh-TW/model-config#extended-context) 以了解如何強制執行保持。對於具有合規要求的企業環境很有用。對於其在為無法識別的 `[1m]` 模型 ID 更正視窗中的角色，請參閱 [為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

241| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 以停用 Opus 4.6 和 Sonnet 4.6 上的 [自適應推理](/docs/zh-TW/model-config#adjust-effort-level)，並回退到由 `MAX_THINKING_TOKENS` 控制的固定思考預算。對 [Fable 模型](/docs/zh-TW/model-config#extended-thinking)、Sonnet 5 或 Opus 4.7 及更新版本無效，它們始終使用自適應推理 |241| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 以停用 Opus 4.6 和 Sonnet 4.6 上的 [自適應推理](/docs/zh-TW/model-config#adjust-effort-level)，並回退到由 `MAX_THINKING_TOKENS` 控制的固定思考預算。對 [Fable 模型](/docs/zh-TW/model-config#extended-thinking)、Sonnet 5 或 Opus 4.7 及更新版本無效，它們始終使用自適應推理 |

242| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 設定為 `1` 以停止 Claude Code 在管理員來源之間按金鑰合併 [受管設定](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier) `env` 區塊，因此只有最高優先順序來源的整個 `env` 區塊適用，如 v2.1.223 之前一樣。在啟動 Claude Code 的環境中設定它，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.223 或更新版本 |242| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 設定為 `1` 以停止 Claude Code 在管理員來源之間按金鑰合併 [受管設定](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier) `env` 區塊，因此只有最高優先順序來源的整個 `env` 區塊適用，如 v2.1.223 之前。在啟動 Claude Code 的環境中設定它，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.223 或更新版本 |

243| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設定為 `1` 以停用 [advisor 工具](/docs/zh-TW/advisor)。`/advisor` 命令變為不可用，任何配置的 `advisorModel` 都被忽略，`--advisor` 旗標被接受但無效，因此傳遞它的現有指令碼繼續工作而不出錯 |243| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設定為 `1` 以停用 [顧問工具](/docs/zh-TW/advisor)。`/advisor` 命令變為不可用，任何配置的 `advisorModel` 都會被忽略，`--advisor` 旗標被接受但無效，因此傳遞它的現有指令碼繼續工作而不會出錯 |

244| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設定為 `1` 以關閉 [背景代理和代理檢視](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 和按需主管。等同於 [`disableAgentView`](/docs/zh-TW/settings-reference#disableagentview) 設定 |244| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設定為 `1` 以關閉 [背景代理和代理檢視](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 和隨選主管。等同於 [`disableAgentView`](/docs/zh-TW/settings-reference#disableagentview) 設定 |

245| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 並使用經典主螢幕呈現器。對話保留在您終端的原生捲軸中，因此 `Cmd+f` 和 tmux 複製模式可以正常工作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-TW/settings-reference#tui) 設定。您也可以使用 `/tui default` 切換。不適用於從 [代理檢視](/docs/zh-TW/agent-view) 開啟的背景工作階段，它們始終使用全螢幕呈現 |245| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 並使用經典主螢幕呈現器。對話保留在您終端的原生捲軸中，因此 `Cmd+f` 和 tmux 複製模式可以正常工作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-TW/settings-reference#tui) 設定。您也可以使用 `/tui default` 切換。不適用於從 [代理檢視](/docs/zh-TW/agent-view) 開啟的背景工作階段，它們始終使用全螢幕呈現 |

246| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設定為 `1` 以關閉 [Artifact](/docs/zh-TW/artifacts) 工具，該工具將工作階段輸出發佈為 claude.ai 上的私人網頁。設定後，沒有設定檔會重新開啟工具。若要改為從設定檔關閉工具，請將 [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) 設定為 `false`；已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 金鑰也會關閉它 |246| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設定為 `1` 以關閉 [成品](/docs/zh-TW/artifacts) 工具，該工具將工作階段輸出發佈為 claude.ai 上的私人網頁。一旦設定，沒有設定檔會開啟工具。若要改從設定檔關閉工具，請將 [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) 設定為 `false`；已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 金鑰也會關閉它 |

248| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 以停用 [自動記憶](/docs/zh-TW/memory#auto-memory)。設定為 `0` 以強制啟用自動記憶，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings-reference#automemoryenabled) 會停用它。停用時，Claude 不會建立或載入自動記憶檔案 |248| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 以停用 [自動記憶](/docs/zh-TW/memory#auto-memory)。設定為 `0` 以強制啟用自動記憶，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings-reference#automemoryenabled) 會否則停用它。停用時，Claude 不會建立或載入自動記憶檔案 |

250| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 設定為 `1` 以停止 Claude Code 將缺少或空的 `Content-Type` 標頭的 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應視為 Amazon Bedrock 的二進位事件串流。預設情況下，Claude Code 假設閘道從其他未修改的回應中丟棄了標頭，因此它解碼主體，串流保持工作。僅針對也將串流重新發出為伺服器傳送事件的閘道設定此項；Claude Code 隨後將無標頭主體讀作伺服器傳送事件。需要 Claude Code v2.1.239 或更新版本 |250| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 設定為 `1` 以停止 Claude Code 將缺少或空的 `Content-Type` 標頭的 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應視為 Amazon Bedrock 的二進位事件串流。預設情況下，Claude Code 假設閘道從其他未修改的回應中丟棄了標頭，因此它會解碼主體，串流會繼續工作。僅針對同時將串流重新發出為伺服器傳送事件的閘道設定此項；Claude Code 隨後將無標頭主體讀作伺服器傳送事件。需要 Claude Code v2.1.239 或更新版本 |

251| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設定為 `1` 以跳過檢查 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否攜帶 `application/vnd.amazon.eventstream` 內容類型。沒有此變數，當回應攜帶不同的內容類型時，Claude Code 會失敗請求，並出現命名該類型的錯誤，這意味著 [閘道或代理正在轉換回應](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。配置閘道以未修改地轉發 `Content-Type` 標頭和主體，而不是設定此變數。需要 Claude Code v2.1.208 或更新版本 |251| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設定為 `1` 以跳過檢查 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否攜帶 `application/vnd.amazon.eventstream` 內容類型。沒有此變數，當回應攜帶不同的內容類型時，Claude Code 會失敗請求，並出現命名該類型的錯誤，這意味著 [閘道或代理正在轉換回應](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。設定閘道以未修改地轉發 `Content-Type` 標頭和主體，而不是設定此變數。需要 Claude Code v2.1.208 或更新版本 |

252| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設定為 `1` 以停止 [背景工作階段](/docs/zh-TW/agent-view) 執行的背景 shell 命令、動態工作流程，以及自 v2.1.198 起的背景子代理，當 [主管](/docs/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新該工作階段的程序時，而不是將它們交給工作階段的下一個程序。僅影響該交接：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 背景化工作階段仍會進行中的工作，`CLAUDE_DISABLE_ADOPT` 關閉兩者。需要 Claude Code v2.1.196 或更新版本 |252| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設定為 `1` 以停止 [背景工作階段](/docs/zh-TW/agent-view) 的執行背景 shell 命令、動態工作流，以及從 v2.1.198 開始的背景子代理，當 [主管](/docs/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新該工作階段的程序時，而不是將它們交給工作階段的下一個程序。僅影響該交付：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 背景化工作階段仍會進行中的工作，`CLAUDE_DISABLE_ADOPT` 會關閉兩者。需要 Claude Code v2.1.196 或更新版本 |

253| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設定為 `1` 以停止 Claude Code 在作業系統報告記憶體壓力時終止 [背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 和 Linux 上，Claude Code 在工作階段閒置 30 分鐘且沒有轉或子代理執行時，終止在主工作階段中啟動的背景 shell。Windows 沒有記憶體壓力信號，因此此變數對其無效。需要 Claude Code v2.1.193 或更新版本 |253| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設定為 `1` 以停止 Claude Code 在記憶體壓力下終止 [背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 和 Linux 上，當作業系統報告關鍵記憶體壓力且工作階段已閒置 30 分鐘且沒有轉向或子代理執行時，Claude Code 會終止背景 shell。Windows 沒有記憶體壓力信號，因此此變數在那裡無效。需要 Claude Code v2.1.193 或更新版本 |

254| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設定為 `1` 以停用 Claude Code 包含的 [skills](/docs/zh-TW/skills) 和工作流程：捆綁的 skills 和工作流程被完全移除，而內建命令（如 `/init`）保持可輸入但對模型隱藏。`/doctor` 保持可輸入，如內建命令；使用 `DISABLE_DOCTOR_COMMAND` 隱藏它。來自外掛程式、`.claude/skills/` 和 `.claude/commands/` 的 Skills 不受影響。等同於 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定 |254| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設定為 `1` 以停用 Claude Code 包含的 [技能](/docs/zh-TW/skills) 和工作流：捆綁的技能和工作流會完全移除，而內建命令（如 `/init`）保持可輸入但對模型隱藏。`/doctor` 保持可輸入，如內建命令；使用 `DISABLE_DOCTOR_COMMAND` 隱藏它。來自外掛程式、`.claude/skills/` 和 `.claude/commands/` 的技能不受影響。等同於 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定 |

255| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 設定為 `1` 以保持 [Chrome 中的 Claude](/docs/zh-TW/chrome) 瀏覽器工具可用，同時省略系統提示的 Chrome 部分和 `/claude-in-chrome` [捆綁 skill](/docs/zh-TW/skills#bundled-skills)。適用於嵌入 Claude Code 並提供自己的瀏覽器指導的主機。需要 Claude Code v2.1.257 或更新版本 |255| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 設定為 `1` 以保持 [Chrome 中的 Claude](/docs/zh-TW/chrome) 瀏覽器工具可用，同時省略系統提示的 Chrome 部分和 `/claude-in-chrome` [捆綁技能](/docs/zh-TW/skills#bundled-skills)。適用於嵌入 Claude Code 並提供自己的瀏覽器指導的主機。需要 Claude Code v2.1.257 或更新版本 |

257| `CLAUDE_CODE_DISABLE_CRON` | 設定為 `1` 以停用 [排程工作](/docs/zh-TW/scheduled-tasks)。`/loop` skill 和 cron 工具變為不可用，任何已排程的工作停止觸發，包括已在執行的工作 |257| `CLAUDE_CODE_DISABLE_CRON` | 設定為 `1` 以停用 [排程工作](/docs/zh-TW/scheduled-tasks)。`/loop` 技能和 cron 工具變為不可用，任何已排程的工作停止觸發，包括已在工作階段中執行的工作 |

258| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 以從 API 請求中移除 Anthropic 特定的 `anthropic-beta` 請求標頭和測試版工具架構欄位（例如 `defer_loading` 和 `eager_input_streaming`）。當代理閘道拒絕請求，出現錯誤如「`anthropic-beta` 標頭的意外值」或「不允許額外輸入」時使用。標準欄位（`name`、`description`、`input_schema`、`cache_control`）被保留。[MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 被停用，所有 MCP 工具預先載入，即使您設定 `ENABLE_TOOL_SEARCH`。在 Claude Code v2.1.227 或更新版本上，[受管設定](/docs/zh-TW/managed-settings) 可以保持工具搜尋開啟。[停用預發行功能](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 涵蓋覆蓋適用的位置 |258| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 以從 API 請求中移除 Anthropic 特定的 `anthropic-beta` 請求標頭和測試版工具架構欄位（例如 `defer_loading` 和 `eager_input_streaming`）。當代理閘道拒絕請求並出現錯誤（例如「`anthropic-beta` 標頭的意外值」或「不允許額外輸入」）時使用此選項。標準欄位（`name`、`description`、`input_schema`、`cache_control`）會保留。[MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 停用，所有 MCP 工具會預先載入，即使您設定 `ENABLE_TOOL_SEARCH`。在 Claude Code v2.1.227 或更新版本上，[受管設定](/docs/zh-TW/managed-settings) 可以保持工具搜尋開啟。[停用預發行功能](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 涵蓋覆蓋適用的位置 |

259| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設定為 `1` 以停用內建 [Explore 和 Plan 子代理](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 使用其搜尋工具或通用子代理進行探索，[plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 直接讀取檔案，而不是啟動 Explore 和 Plan 代理。名為 `Explore` 或 `Plan` 的自訂子代理不受影響。若要在 Agent SDK 或非互動模式中移除每個內建子代理類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |259| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設定為 `1` 以停用內建 [Explore 和 Plan 子代理](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 改用其搜尋工具或通用子代理進行探索，[計畫模式](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 直接讀取檔案，而不是啟動 Explore 和 Plan 代理。名為 `Explore` 或 `Plan` 的自訂子代理不受影響。若要在 Agent SDK 或非互動模式中移除每個內建子代理類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |

261| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。當設定 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，調查也被停用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 選擇重新加入。若要設定樣本率而不是完全停用，請使用 [`feedbackSurveyRate`](/docs/zh-TW/settings-reference#feedbacksurveyrate) 設定。請參閱 [工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys) |261| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。當設定 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，調查也會停用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 選擇加入。若要設定樣本率而不是完全停用，請使用 [`feedbackSurveyRate`](/docs/zh-TW/settings-reference#feedbacksurveyrate) 設定。請參閱 [工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys) |

262| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設定為 `1` 以停用檔案 [checkpointing](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更。覆蓋 [`fileCheckpointingEnabled`](/docs/zh-TW/settings-reference#filecheckpointingenabled) 設定 |262| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設定為 `1` 以停用檔案 [檢查點](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更。覆蓋 [`fileCheckpointingEnabled`](/docs/zh-TW/settings-reference#filecheckpointingenabled) 設定 |

263| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以移除內建提交和 PR 工作流程指示以及 Claude 系統提示中的 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。設定時優先於 [`includeGitInstructions`](/docs/zh-TW/settings-reference#includegitinstructions) 設定 |263| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以移除內建提交和 PR 工作流指示以及 Claude 上下文中的 git 狀態快照。在使用您自己的 git 工作流技能時很有用。設定時優先於 [`includeGitInstructions`](/docs/zh-TW/settings-reference#includegitinstructions) 設定 |

264| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 到目前的 Opus 版本。當您想要故意釘選較舊的模型時使用。重新對應不在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |264| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 到目前的 Opus 版本。在您想要有意釘選較舊模型時使用。重新對應不在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上執行 |

265| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲軸仍然有效。使用此選項以保持終端的原生選擇複製行為 |265| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲軸仍然有效。使用此選項以保持終端的原生選擇複製行為 |

266| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的點擊、拖曳和懸停處理，同時保持滑鼠滾輪捲軸。當您希望滾輪捲軸在 Claude Code 內工作但不希望點擊定位游標、展開工具輸出或開啟連結時使用。設定兩者時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |266| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的點擊、拖曳和懸停處理，同時保持滑鼠滾輪捲軸。當您想要滾輪捲軸在 Claude Code 內工作但不想要點擊來定位游標、展開工具輸出或開啟連結時使用此選項。設定兩者時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |

267| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 設定為 `1` 以停止 Claude Code 在 API 請求因連線級錯誤（例如連線重設或 TLS 握手錯誤）失敗時重新讀取 [mTLS 用戶端憑證和金鑰](/docs/zh-TW/network-config#mtls-authentication)。停用重新載入後，Claude Code 僅在下次應用設定或下次啟動時載入輪換的檔案。需要 Claude Code v2.1.232 或更新版本 |267| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 設定為 `1` 以停止 Claude Code 在 API 請求因連線級錯誤（例如連線重設或 TLS 握手錯誤）失敗時重新讀取 [mTLS 用戶端憑證和金鑰](/docs/zh-TW/network-config#mtls-authentication)。停用重新載入後，Claude Code 僅在下次套用設定或下次啟動時載入輪換的檔案。需要 Claude Code v2.1.232 或更新版本 |

268| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 設定為任何非空值（例如 `1`）以停用非必要網路流量：自動更新、遙測、錯誤報告、`/feedback` 命令、[Claude 起草的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)、發行說明、[PR 和 MR 狀態徽章](/docs/zh-TW/interactive-mode#pr-review-status) 檢查以及可用性檢查（例如 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 檢查）。它也停止 [外掛程式 `command` 來源的背景執行](/docs/zh-TW/plugin-marketplaces#when-claude-code-re-runs-the-command)，這些是本機命令而不是網路流量，因為它們可以觸發依賴項安裝。**將其設定為 `0` 或 `false` 仍會停用此流量**，與大多數開啟/關閉變數不同；取消設定變數以再次允許它。也停用功能旗標擷取，這使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。官方外掛程式市場自動安裝不涵蓋；使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 停用它。不影響 [閘道模型發現](/docs/zh-TW/llm-gateway-connect#add-gateway-models-to-the-model-picker)，它有自己的選擇加入 |268| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 設定為任何非空值（例如 `1`）以停用非必要網路流量：自動更新、遙測、錯誤報告、`/feedback` 命令、[Claude 起草的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)、發行說明、[PR 和 MR 狀態徽章](/docs/zh-TW/interactive-mode#pr-review-status) 檢查以及可用性檢查（例如 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 檢查）。它也會停止 [外掛程式 `command` 來源的背景執行](/docs/zh-TW/plugins/loading#when-a-command-source-re-runs)，這些是本機命令而不是網路流量，因為它們可能會觸發相依性安裝。**將其設定為 `0` 或 `false` 仍會停用此流量**，與大多數開啟/關閉變數不同；取消設定變數以再次允許它。也停用功能旗標擷取，這使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。官方外掛程式市場自動安裝不涵蓋；使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 停用它。不影響 [閘道模型探索](/docs/zh-TW/llm-gateway-connect#add-gateway-models-to-the-model-picker)，它有自己的選擇加入 |

270| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設定為 `1` 以在您在終端中輸入或聚焦時傳送 `PushNotification` 工具的桌面通知。預設情況下，當工具偵測到最近的鍵盤活動或終端焦點時，工具會跳過桌面通知和 [行動推送](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此伺服器在偵測到您活躍時仍可以抑制行動推送。需要 Claude Code v2.1.193 或更新版本 |270| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設定為 `1` 以在您在終端中輸入或聚焦時傳送 `PushNotification` 工具的桌面通知。預設情況下，當工具偵測到最近的鍵盤活動或終端焦點時，工具會跳過桌面通知和 [行動推播](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此伺服器在偵測到您活躍時仍可以抑制行動推播。需要 Claude Code v2.1.193 或更新版本 |

271| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設定為 `1` 以停用官方外掛程式市場的自動註冊。Claude Code 在即將註冊市場時讀取變數，通常在機器的第一次互動啟動期間。如果變數在該點設定，Claude Code 會永久跳過註冊。稍後取消設定變數不會撤銷跳過。隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 以註冊市場 |271| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設定為 `1` 以停用官方外掛程式市場的自動註冊。Claude Code 在即將註冊市場時讀取變數，通常在機器的第一次互動啟動期間。如果變數在該點設定，Claude Code 會永久跳過註冊。稍後取消設定變數不會撤銷跳過。隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 以註冊市場 |

272| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 設定為 `1` 以停止 Claude Code 在 Claude Desktop 和 VS Code 擴充功能主機 Claude Code 的工作階段中為未回答的權限請求執行您的 [`Notification` hooks](/docs/zh-TW/hooks#notification)，這是 Claude Code 將它們傳送到 Agent SDK 的 `canUseTool` 回呼的方式。在終端工作階段中無效。需要 Claude Code v2.1.233 或更新版本 |272| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 設定為 `1` 以停止 Claude Code 在 Claude Code 將它們傳送到 Agent SDK 的 `canUseTool` 回呼的工作階段中執行 [未回答權限請求的 `Notification` hooks](/docs/zh-TW/hooks#notification)，這是 Claude Desktop 和 VS Code 擴充功能主機 Claude Code 的方式。在終端工作階段中無效。需要 Claude Code v2.1.233 或更新版本 |

274| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設定為 `1` 以停用基於對話上下文的自動終端標題更新。這也會跳過產生 [工作階段標題](/docs/zh-TW/sessions#name-your-sessions) 的背景小/快速模型請求 |274| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設定為 `1` 以停用基於對話上下文的自動終端標題更新。這也會跳過 [產生工作階段標題](/docs/zh-TW/sessions#name-your-sessions) 的背景小型/快速模型請求 |

275| `CLAUDE_CODE_DISABLE_THINKING` | 設定為 `1` 以從 API 請求中完全省略 `thinking` 參數。這是代理和閘道拒絕參數的相容性選項。在預設思考的模型上，省略參數意味著模型仍可能思考。若要在 Anthropic API 上明確停用 [擴展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`。兩個變數都不會在 Opus 5.5 或 Fable 模型上關閉思考，這些模型無法關閉思考。在 [第三方提供者](/docs/zh-TW/third-party-integrations) 上，`MAX_THINKING_TOKENS=0` 同樣省略參數，因此兩個變數在那裡的行為相同 |275| `CLAUDE_CODE_DISABLE_THINKING` | 設定為 `1` 以從 API 請求中完全省略 `thinking` 參數。這是代理和閘道拒絕參數的相容性選項。在預設思考的模型上，省略參數意味著模型可能仍然思考。若要在 Anthropic API 上明確停用 [擴充思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`。兩個變數都不會在 Opus 5.5 或 Fable 模型上關閉思考，它們無法關閉思考。在 [第三方提供者](/docs/zh-TW/third-party-integrations) 上，`MAX_THINKING_TOKENS=0` 同樣省略參數，因此兩個變數在那裡的行為相同 |

276| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 設定為 `1` 以在 Claude Code 不識別模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway) 別名）時跳過主動 [自動壓縮](/docs/zh-TW/costs#reduce-token-usage)。沒有此變數，Claude Code 在它為 ID 假設的上下文視窗進行壓縮。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 可以改為更正假設的視窗；請參閱 [為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) 以了解何時應用每個變數。需要 Claude Code v2.1.223 或更新版本 |276| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 設定為 `1` 以在 Claude Code 不識別模型 ID 時跳過主動 [自動壓縮](/docs/zh-TW/costs#reduce-token-usage)，例如 [LLM 閘道](/docs/zh-TW/llm-gateway) 別名。沒有此變數，Claude Code 會在它為 ID 假設的上下文視窗進行壓縮。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 可以改為更正假設的視窗；請參閱 [為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) 以了解何時應用每個變數。需要 Claude Code v2.1.223 或更新版本 |

277| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的虛擬捲軸並呈現文字記錄中的每條訊息。如果全螢幕模式中的捲軸顯示應該出現訊息的空白區域，請使用此選項 |277| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的虛擬捲軸並呈現文字記錄中的每條訊息。如果全螢幕模式中的捲軸顯示應該出現訊息的空白區域，請使用此選項 |

278| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 設定為 `1` 以在 Windows 上直接啟動 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) 命令，而不是透過 `cmd.exe` 啟動器。預設情況下，啟動器讓在背景執行的 PowerShell 命令 [進行到工作階段的下一個程序](/docs/zh-TW/agent-view#the-supervisor-process)，例如當您 [背景化工作階段](/docs/zh-TW/agent-view#from-inside-a-session) 時。如果您設定變數，背景化的 PowerShell 命令在工作階段的程序退出時停止。Bash 命令不受影響。需要 Claude Code v2.1.269 或更新版本 |278| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 設定為 `1` 以在 Windows 上直接啟動 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) 命令，而不是透過 `cmd.exe` 啟動器。預設情況下，啟動器讓在 [背景中執行](/docs/zh-TW/tools-reference#background-commands) 的 PowerShell 命令 [進行到工作階段的下一個程序](/docs/zh-TW/agent-view#the-supervisor-process)，例如當您 [背景化工作階段](/docs/zh-TW/agent-view#from-inside-a-session) 時。如果您設定變數，背景化的 PowerShell 命令會在工作階段的程序退出時停止。Bash 命令不受影響。需要 Claude Code v2.1.269 或更新版本 |

279| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設定為 `1` 以停用 [工作流程](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |279| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設定為 `1` 以停用 [工作流](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |

280| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定 effort 級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設。可用級別取決於模型。優先於 `--effort`、`/effort` 和 `modelSettings` 和 `effortLevel` 設定。[`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) 上限仍然適用。請參閱 [調整 effort 級別](/docs/zh-TW/model-config#adjust-effort-level) |280| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定 effort 級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設。可用級別取決於模型。優先於 `--effort`、`/effort` 和 `modelSettings` 和 `effortLevel` 設定。[`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) 上限仍然適用。請參閱 [調整 effort 級別](/docs/zh-TW/model-config#adjust-effort-level) |

281| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | 設定為 `1` 以啟用將額外文字附加到除 [分叉子代理](/docs/zh-TW/sub-agents#fork-the-current-conversation) 外的每個 [子代理](/docs/zh-TW/sub-agents) 的系統提示末尾。[`--append-subagent-system-prompt`](/docs/zh-TW/cli-reference#cli-flags) 和 [`--append-subagent-system-prompt-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標提供附加的文字並自動設定此變數，因此您不需要自己設定。需要 Claude Code v2.1.205 或更新版本 |281| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為了與較舊版本相容而接受，無效。自動模式在每個提供者上預設可用，包括 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) 工作階段。在 v2.1.158 到 v2.1.206 中，設定此項為 `1` 是在這些提供者上提供 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 所必需的 |

282| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為與較舊版本相容而接受，無效。自動模式在每個提供者上預設可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) 工作階段。在 v2.1.158 到 v2.1.206 中，設定此項為 `1` 是在這些提供者上提供 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 所必需的 |282| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [工作階段摘要](/docs/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制關閉摘要，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時強制開啟摘要。優先於設定和 `/config` 切換 |

283| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [工作階段摘要](/docs/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制摘要關閉，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時強制摘要開啟。優先於設定和 `/config` 切換 |283| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在背景安裝完成後在 [非互動模式](/docs/zh-TW/headless) 中的轉向邊界重新整理外掛程式狀態。預設關閉，因為重新整理會在工作階段中途變更系統提示，這會使該轉向的 [提示快取](/docs/zh-TW/prompt-caching) 失效 |

284| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在背景安裝完成後在轉邊界刷新外掛程式狀態（在 [非互動模式](/docs/zh-TW/headless) 中）。關閉預設，因為刷新在工作階段中途變更系統提示，這會使該轉的 [提示快取](/docs/zh-TW/prompt-caching) 失效 |284| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 繫結的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry 收集器](/docs/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式中，沒有調查資料傳送到 Anthropic。當設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品回饋政策優先 |

285| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 綁定的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry 收集器](/docs/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式下，沒有調查資料傳送到 Anthropic。設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品回饋政策優先 |285| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 API 產生時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成產生後到達，這可能看起來像它掛起。在 Anthropic API 上預設啟用。在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上，在部署的容器支援的每個模型上啟用。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 透過代理路由時強制開啟。在 Microsoft Foundry 和 [閘道](/docs/zh-TW/llm-gateway) 連線上預設關閉 |

286| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 產生時從 API 串流。關閉此項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成產生後到達，這可能看起來像它掛起。在 Anthropic API 上預設啟用。在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，在部署的容器支援的每個模型上啟用。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 透過代理路由時強制開啟。在 Microsoft Foundry 和 [閘道](/docs/zh-TW/llm-gateway) 連線上預設關閉 |286| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共用 API 金鑰支援的閘道會否則向每個使用者顯示金鑰可以存取的每個模型。探索的模型仍由工作階段接收的 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單篩選；透過 [MDM 或受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms) 傳遞清單，因為 [伺服器管理的傳遞在閘道設定上不可用](/docs/zh-TW/server-managed-settings#platform-availability) |

287| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會否則向每個使用者顯示金鑰可以存取的每個模型。發現的模型仍由工作階段接收的 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單篩選；透過 [MDM 或受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms) 傳遞清單，因為 [伺服器管理的傳遞在閘道配置上不可用](/docs/zh-TW/server-managed-settings#platform-availability) |

289| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以關閉提示建議，即出現在提示輸入中的灰色預測。優先於 [`promptSuggestionEnabled`](/docs/zh-TW/settings-reference#promptsuggestionenabled) 設定，這是 `/config` 中的**提示建議**切換寫入的。Claude Code 也 [在您的帳戶接近或達到使用限制時暫停建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions)。設定為 `true` 以在達到限制前保持它們開啟。需要 Claude Code v2.1.238 或更新版本。請參閱 [提示建議](/docs/zh-TW/interactive-mode#prompt-suggestions) |288| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以關閉提示建議，即出現在提示輸入中的灰色預測。優先於 [`promptSuggestionEnabled`](/docs/zh-TW/settings-reference#promptsuggestionenabled) 設定，這是 `/config` 中的**提示建議**切換寫入的。Claude Code 也會在您的帳戶接近或達到使用限制時 [暫停建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions)。設定為 `true` 以在達到限制之前保持它們開啟。需要 Claude Code v2.1.238 或更新版本。請參閱 [提示建議](/docs/zh-TW/interactive-mode#prompt-suggestions) |

290| `CLAUDE_CODE_ENABLE_TASKS` | 選擇 Claude Code 在 [具有它們的工作階段](/docs/zh-TW/tools-reference#task-tool-availability) 中提供的工作追蹤工具。預設情況下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`。設定為 `0` 以改為取得舊版 `TodoWrite` 工具。請參閱 [工作清單](/docs/zh-TW/interactive-mode#task-list) |289| `CLAUDE_CODE_ENABLE_TASKS` | 選擇 Claude Code 在 [具有它們的工作階段](/docs/zh-TW/tools-reference#task-tool-availability) 中提供的工作追蹤工具。預設情況下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`。設定為 `0` 以改為取得舊版 `TodoWrite` 工具。請參閱 [工作清單](/docs/zh-TW/interactive-mode#task-list) |

291| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設定為 `1` 以啟用指標和日誌記錄的 OpenTelemetry 資料收集。在配置 OTel 匯出器之前需要。請參閱 [監控](/docs/zh-TW/monitoring-usage) |290| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設定為 `1` 以啟用指標和日誌記錄的 OpenTelemetry 資料收集。在設定 OTel 匯出器之前需要。在您的 shell、使用者設定或受管設定中設定。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略。請參閱 [監視](/docs/zh-TW/monitoring-usage) |

292| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 設定為 `1` 以在每個模型上取得工作追蹤工具。沒有它，Claude Code 預設僅在 [工作工具可用性](/docs/zh-TW/tools-reference#task-tool-availability) 下列出的模型上提供它們。`CLAUDE_CODE_ENABLE_TASKS` 仍選擇 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更新版本 |291| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 設定為 `1` 以在每個模型上取得工作追蹤工具。沒有它，Claude Code 預設僅在 [工作工具可用性](/docs/zh-TW/tools-reference#task-tool-availability) 下列出的模型上提供它們。`CLAUDE_CODE_ENABLE_TASKS` 仍選擇 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更新版本 |

295| `CLAUDE_CODE_EXTRA_BODY` | JSON 物件以合併到每個 API 請求主體的頂級。對於傳遞 Claude Code 不直接公開的提供者特定參數很有用。在您的 shell 中匯出的值也適用於您使用 `claude agents` 或 `--bg` 分派的 [背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段忽略了 shell 匯出的值，並使用背景主管程序繼承的任何副本 |294| `CLAUDE_CODE_EXTRA_BODY` | JSON 物件以合併到每個 API 請求主體的頂層。對於傳遞 Claude Code 不直接公開的提供者特定參數很有用。在 shell 中匯出的值也適用於您使用 `claude agents` 或 `--bg` 分派的 [背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段忽略 shell 匯出的值，並使用背景主管程序繼承的任何副本 |

297| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 設定為 `1` 以強制文字記錄持續性、提示歷史記錄和 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內啟動的。當繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 `screen` 工作階段或由 Claude Code 的 Bash 工具首次啟動的背景啟動器）導致真正的頂級工作階段被誤分類為嵌套時使用。自 v2.1.178 起，Claude Code 自動偵測 tmux 情況並忽略繼承的標記，因此 tmux 不再需要此變數。也在 v2.1.169 及更早版本上受尊重；對 v2.1.170 和 v2.1.171 無效，其中它覆蓋的嵌套工作階段偵測被移除 |296| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 設定為 `1` 以強制文字記錄持續性、提示歷史記錄和 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內啟動的。當繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 `screen` 工作階段或由 Claude Code 的 Bash 工具首次啟動的背景啟動器）導致真正的頂級工作階段被誤分類為嵌套時使用。從 v2.1.178 開始，Claude Code 會自動偵測 tmux 情況並忽略繼承的標記，因此 tmux 不再需要此變數。也在 v2.1.169 及更早版本上受尊重；在 v2.1.170 和 v2.1.171 上無效，其中它覆蓋的嵌套工作階段偵測被移除 |

298| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 設定為 `1` 以在您的終端支援但未自動偵測時強制 `~~text~~` 的刪除線呈現，例如透過 SSH 而不轉發 `TERM_PROGRAM`。沒有此項，未偵測的終端會顯示文字 `~~` 標記，而不是呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |297| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 設定為 `1` 以在您的終端支援但未自動偵測時強制 `~~text~~` 的刪除線呈現，例如透過 SSH 而不轉發 `TERM_PROGRAM`。沒有此項，未偵測的終端會顯示文字刪除線標記而不是呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |

299| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設定為 `1` 以在您的終端支援但未自動偵測時強制啟用 DEC 私有模式 2026 [同步輸出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。對於實現 BSU/ESU 但不回覆功能探測的模擬器（例如 Emacs `eat`）很有用。在 tmux 下無效。與 `CLAUDE_CODE_NO_FLICKER` 不同，後者切換到 [全螢幕呈現](/docs/zh-TW/fullscreen)，這不會變更呈現器 |298| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設定為 `1` 以在您的終端支援但未自動偵測時強制啟用 DEC 私人模式 2026 [同步輸出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。對於實現 BSU/ESU 但不回覆功能探測的模擬器（例如 Emacs `eat`）很有用。在 tmux 下無效。與 [全螢幕呈現](/docs/zh-TW/fullscreen) 的 `CLAUDE_CODE_NO_FLICKER` 不同，這不會變更呈現器 |

300| `CLAUDE_CODE_FORK_SUBAGENT` | 控制 [分叉模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)，它讓 Claude 產生 [分叉子代理](/docs/zh-TW/sub-agents#fork-the-current-conversation) 本身，在互動工作階段中預設開啟。設定為 `1` 以在 `claude -p` 和 Agent SDK 中也開啟它，或設定為 `0` 以在每種工作階段中關閉它。無論分叉模式是否開啟，您都可以執行 `/subtask`。互動預設需要 Claude Code v2.1.232 或更新版本；在較早版本上，設定變數為 `1` 以開啟分叉模式 |299| `CLAUDE_CODE_FORK_SUBAGENT` | 控制 [fork 模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)，它讓 Claude 產生 [forked 子代理](/docs/zh-TW/sub-agents#fork-the-current-conversation) 本身，在互動工作階段中預設開啟。設定為 `1` 以在 `claude -p` 和 Agent SDK 中也開啟它，或設定為 `0` 以在每種工作階段中關閉它。無論 fork 模式是否開啟，您都可以執行 `/subtask`。互動預設需要 Claude Code v2.1.232 或更新版本；在較早的版本上，設定變數為 `1` 以開啟 fork 模式 |

301| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 設定為 `1` 以在 `claude -p --output-format stream-json` 輸出中發出 [子代理](/docs/zh-TW/sub-agents) 文字和思考區塊，與 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 旗標相同的行為。當啟動 `claude` 的工具無法自己傳遞旗標時使用變數。與旗標不同，旗標在非互動模式下使用 stream-json 輸出時以錯誤退出，變數在那裡被忽略，以便嵌套呼叫在全程設定時保持工作。需要 Claude Code v2.1.211 或更新版本 |300| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 設定為 `1` 以在 `claude -p --output-format stream-json` 輸出中發出 [子代理](/docs/zh-TW/sub-agents) 文字和思考區塊，與 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 旗標相同的行為。當工具呼叫 `claude` 的工具無法自己傳遞旗標時使用變數。與旗標不同，旗標在非互動模式下使用 stream-json 輸出時以錯誤退出，變數在那裡被忽略，以便嵌套呼叫在全程設定時繼續工作。需要 Claude Code v2.1.211 或更新版本 |

302| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 設定為 `1` 以在自訂代理或第三方提供者（例如 Amazon Bedrock 或 Claude Platform on AWS）上傳送 [閘道提示標頭](/docs/zh-TW/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 和 `x-claude-code-compaction`。設定為 `0` 以停止在每個連線上傳送它們，包括 Claude Code 預設傳送的直接 Anthropic API 連線。需要 Claude Code v2.1.273 或更新版本 |301| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 設定為 `1` 以在自訂代理或第三方提供者（例如 Amazon Bedrock 或 AWS 上的 Claude Platform）上傳送 [閘道提示標頭](/docs/zh-TW/llm-gateway-protocol#gateway-hint-headers)（例如 `x-claude-code-request-class` 和 `x-claude-code-compaction`）。設定為 `0` 以停止在每個連線上傳送它們，包括 Claude Code 預設傳送的直接 Anthropic API 連線。需要 Claude Code v2.1.273 或更新版本 |

303| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | [閘道模型發現](/docs/zh-TW/llm-gateway-protocol#model-discovery) 請求的逾時（毫秒），`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 開啟（預設：`3000`）。當您的閘道需要超過三秒才能在啟動時回答 `/v1/models` 時提高它。僅接受純數字；`0`、負值和其他拼寫保持預設。需要 Claude Code v2.1.269 或更新版本 |302| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | [閘道模型探索](/docs/zh-TW/llm-gateway-protocol#model-discovery) 請求的逾時（毫秒），`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 開啟（預設：`3000`）。當您的閘道需要超過三秒來回答啟動時的 `/v1/models` 時提高此值。僅接受純數字；`0`、負值和其他拼寫保持預設。需要 Claude Code v2.1.269 或更新版本 |

304| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 可執行檔 (`bash.exe`) 的路徑。當 Git Bash 已安裝但不在您的 PATH 中時使用。如果路徑不存在或檔案未命名為 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 會忽略變數並自動偵測 Git Bash，如同未設定一樣，記錄可見的警告 `--debug`。在 v2.1.219 之前，當路徑不存在時 Claude Code 在啟動時退出，並使用任何現有檔案作為 shell，而不檢查它是否為 bash 或 sh。請參閱 [Windows 設定](/docs/zh-TW/setup#set-up-on-windows) |303| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 可執行檔 (`bash.exe`) 的路徑。當 Git Bash 已安裝但不在您的 PATH 中時使用。如果路徑不存在或檔案未命名為 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 會忽略變數並自動偵測 Git Bash，如同未設定一樣，記錄 `--debug` 可見的警告。在 v2.1.219 之前，當路徑不存在時 Claude Code 在啟動時退出，並使用任何現有檔案作為 shell，而不檢查它是否為 bash 或 sh。請參閱 [Windows 設定](/docs/zh-TW/setup#set-up-on-windows) |

305| `CLAUDE_CODE_GLOB_HIDDEN` | 設定為 `false` 以在 Claude 呼叫 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior) 時從結果中排除隱藏檔案。預設包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |304| `CLAUDE_CODE_GLOB_HIDDEN` | 設定為 `false` 以在 Claude 呼叫 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior) 時從結果中排除隱藏檔案。預設包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |

306| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設定為 `false` 以使 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior) 尊重 `.gitignore` 模式。預設情況下，Glob 返回所有匹配的檔案，包括 gitignored 的檔案。不影響 `@` 檔案自動完成，它有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings-reference#respectgitignore) |305| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設定為 `false` 以使 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior) 尊重 `.gitignore` 模式。預設情況下，Glob 傳回所有符合的檔案，包括 gitignored 的檔案。不影響 `@` 檔案自動完成，它有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings-reference#respectgitignore) |

308| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 背景工作可以讓活躍目標等待多少分鐘，然後 Claude Code [要求 Claude 檢查它](/docs/zh-TW/goal#background-work-defers-evaluation)。預設 `30`。設定 `0` 以關閉檢查。給出純數字的整分鐘，最多 `10080`，即一週。Claude Code 將任何其他值視為未設定並使用預設值。需要 Claude Code v2.1.234 或更新版本 |307| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 背景工作可以讓活躍目標等待多少分鐘，然後 Claude Code [要求 Claude 檢查它](/docs/zh-TW/goal#background-work-defers-evaluation)。預設 `30`。設定 `0` 以關閉檢查。以純數字給出整分鐘，最多 `10080`，即一週。Claude Code 將任何其他值視為未設定並使用預設值。需要 Claude Code v2.1.234 或更新版本 |

311| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設定為 `1` 以跳過 IDE 擴充功能的自動安裝。等同於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設定為 `false` |310| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設定為 `1` 以跳過 IDE 擴充功能的自動安裝。等同於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設定為 `false` |

313| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 在 Agent 工具拒絕產生另一個之前，一個工作階段中可以執行多少個 [子代理](/docs/zh-TW/sub-agents#concurrent-subagent-limit)（預設：20）。接受純數字的正整數；任何其他值都被忽略，因此變數可以調整上限但無法停用它。需要 Claude Code v2.1.217 或更新版本 |312| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 在 Agent 工具拒絕產生另一個之前，一個工作階段中可以執行多少 [子代理](/docs/zh-TW/sub-agents#concurrent-subagent-limit)（預設：20）。接受純數字的正整數；任何其他值都被忽略，因此變數可以調整上限但無法停用它。需要 Claude Code v2.1.217 或更新版本 |

314| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆蓋 Claude Code 為活躍模型假設的上下文視窗大小。自 v2.1.193 起，它如何應用取決於 Claude Code 如何解析模型 ID；請參閱 [為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。當透過 `ANTHROPIC_BASE_URL` 路由到其上下文視窗與其名稱的內建大小不符的模型時使用 |313| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆蓋 Claude Code 為活躍模型假設的上下文視窗大小。從 v2.1.193 開始，它如何應用取決於 Claude Code 如何解析模型 ID；請參閱 [為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。當透過 `ANTHROPIC_BASE_URL` 路由到其上下文視窗與其名稱的內建大小不符的模型時使用此選項 |

315| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 傳送給模型的每個 MCP 工具說明和每個 MCP 伺服器指示的最大長度（字元）（預設：2048）。Claude Code [截斷較長的文字](/docs/zh-TW/mcp#for-mcp-server-authors)。接受純數字的正整數。任何其他值都被忽略，預設適用。需要 Claude Code v2.1.280 或更新版本 |314| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 傳送給模型的每個 MCP 工具說明和每個 MCP 伺服器指示的最大長度（字元）（預設：2048）。Claude Code [截斷較長的文字](/docs/zh-TW/mcp#for-mcp-server-authors)。接受純數字的正整數。任何其他值都被忽略，預設適用。需要 Claude Code v2.1.280 或更新版本 |

316| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 為大多數請求設定最大輸出權杖數。預設值和上限因模型而異；請參閱 [最大輸出權杖](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 為它不識別的模型 ID（例如閘道特定的名稱）預設為 32000，並將高於模型上限的值降低到上限。增加此值會減少 [自動壓縮](/docs/zh-TW/costs#reduce-token-usage) 觸發前可用的有效上下文視窗 |315| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 為大多數請求設定最大輸出權杖數。預設值和上限因模型而異；請參閱 [最大輸出權杖](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 為不識別的模型 ID（例如閘道特定名稱）預設為 32000，並將高於模型上限的值降低到上限。增加此值會減少 [自動壓縮](/docs/zh-TW/costs#reduce-token-usage) 觸發前可用的有效上下文視窗 |

317| `CLAUDE_CODE_MAX_RETRIES` | 覆蓋重試失敗 API 請求的次數（預設：10）。自 v2.1.186 起上限為 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 提高預設值並移除上限。對於需要等待更長中斷的無人值守工作階段，改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |316| `CLAUDE_CODE_MAX_RETRIES` | 覆蓋重試失敗 API 請求的次數（預設：10）。從 v2.1.186 開始上限為 15；從 v2.1.199 開始，`CLAUDE_CODE_RETRY_WATCHDOG` 提高預設值並移除上限。對於需要等待更長中斷的無人值守工作階段，請改設定 `CLAUDE_CODE_RETRY_WATCHDOG` |

318| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 在 v2.1.224 中移除，現在是無操作。以前上限了 Claude 可以在一個工作階段中使用 Agent 工具產生的 [子代理](/docs/zh-TW/sub-agents) 總數（預設：200）；超過上限產生失敗，並出現 `Subagent spawn limit reached`。[並行子代理限制](/docs/zh-TW/sub-agents#concurrent-subagent-limit) 和 [深度限制](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) 仍然適用 |317| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 在 v2.1.224 中移除，現在是無操作。先前上限了 Claude 可以在一個工作階段中使用 Agent 工具產生的 [子代理](/docs/zh-TW/sub-agents) 總數（預設：200）；超過上限的產生失敗，並出現 `Subagent spawn limit reached`。[並行子代理限制](/docs/zh-TW/sub-agents#concurrent-subagent-limit) 和 [深度限制](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) 仍然適用 |

319| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主要對話下方允許的 [子代理層](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) 數量（預設：3）。在預設值，子代理可以產生自己的子代理，第三層的子代理無法進一步產生；設定 `1` 以關閉嵌套。在 v2.1.217 到 v2.1.218 中，預設為 1，因此子代理無法產生自己的，除非您提高限制；v2.1.219 將預設提高到 3。接受純數字的正整數；任何其他值都被忽略，因此限制可以調整但無法移除。需要 Claude Code v2.1.217 或更新版本 |318| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主要對話下方允許的 [子代理層](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) 數（預設：3）。在預設值，子代理可以產生自己的子代理，第三層的子代理無法進一步產生；設定 `1` 以關閉嵌套。在 v2.1.217 到 v2.1.218 中，預設為 1，因此子代理無法產生自己的，除非您提高限制；v2.1.219 將預設提高到 3。接受純數字的正整數；任何其他值都被忽略，因此限制可以調整但無法移除。需要 Claude Code v2.1.217 或更新版本 |

321| `CLAUDE_CODE_MAX_TURNS` | 當沒有傳遞明確限制時，限制代理轉的數量。等同於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時被拒絕，並出現錯誤，而不是視為無上限 |320| `CLAUDE_CODE_MAX_TURNS` | 當未傳遞明確限制時，上限代理轉向數。等同於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時被拒絕並出現錯誤，而不是視為無上限 |

322| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一個工作階段可以進行的 [WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 呼叫總數的上限（預設：200）。當 Claude 達到上限時，進一步的 WebSearch 呼叫返回通知，告訴它繼續使用已經收集的資訊。接受沒有上限的正整數。任何其他值都被忽略，預設適用，因此上限可以提高但無法關閉。需要 Claude Code v2.1.212 或更新版本 |321| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一個工作階段可以進行的 [WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 呼叫總數的上限（預設：200）。當 Claude 達到上限時，進一步的 WebSearch 呼叫傳回通知，告訴它繼續使用已收集的資訊。接受沒有上限的正整數。任何其他值都被忽略，預設適用，因此上限可以提高但無法關閉。需要 Claude Code v2.1.212 或更新版本 |

324| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在執行的 MCP 工具呼叫 [移至背景工作](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) 前的經過時間（毫秒）（預設：120000，或 2 分鐘）。設定為 `0` 以關閉自動背景化。需要 Claude Code v2.1.212 或更新版本 |323| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在執行的 MCP 工具呼叫 [移至背景工作](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) 前的經過時間（毫秒）（預設：120000 或 2 分鐘）。設定為 `0` 以關閉自動背景化。需要 Claude Code v2.1.212 或更新版本 |

325| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非互動](/docs/zh-TW/headless) 工作階段的第一個轉等待仍在連線的 MCP 伺服器的毫秒數，代替預設 [第一轉等待](/docs/zh-TW/agent-sdk/mcp#connection-timing)。設定時，等待涵蓋每個待處理伺服器。設定為 `0` 以跳過等待。[`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 伺服器無論值如何都保持自己的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更新版本 |324| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非互動](/docs/zh-TW/headless) 工作階段的第一個轉向等待仍在連線的 MCP 伺服器的時間（毫秒），代替預設 [第一轉向等待](/docs/zh-TW/agent-sdk/mcp#connection-timing)。設定時，等待涵蓋每個待處理伺服器。設定為 `0` 以跳過等待。[`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 伺服器無論值如何都保持自己的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更新版本 |

326| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具呼叫的閒置逾時（毫秒）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在此長時間內沒有傳送回應和沒有進度通知時，工具呼叫中止，並出現錯誤，而不是等待整體 `MCP_TOOL_TIMEOUT`。覆蓋網路伺服器 300000（5 分鐘）和 stdio 伺服器 1800000（30 分鐘）的每個傳輸預設值。設定為 `0` 以停用閒置檢查。低於 1000 的值提高到一秒，值上限為有效 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中至少 1000 的每個伺服器 `timeout` 將該伺服器的閒置視窗提高到至少 `timeout` 值。不適用於 IDE 伺服器或 SDK 進程內伺服器。需要 Claude Code v2.1.187 或更新版本。在 v2.1.203 之前，stdio 伺服器免除閒置逾時 |325| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具呼叫的閒置逾時（毫秒）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在此長時間內傳送無回應和無進度通知時，工具呼叫會中止並出現錯誤，而不是等待整體 `MCP_TOOL_TIMEOUT`。覆蓋網路伺服器的 300000（5 分鐘）和 stdio 伺服器的 1800000（30 分鐘）的每個傳輸預設值。設定為 `0` 以停用閒置檢查。低於 1000 的值提高到一秒，值上限為有效 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中的每個伺服器 `timeout` 至少 1000 會將該伺服器的閒置視窗提高到至少 `timeout` 值。不適用於 IDE 伺服器或 SDK 進程內伺服器。需要 Claude Code v2.1.187 或更新版本。在 v2.1.203 之前，stdio 伺服器免除閒置逾時 |

327| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 設定，不由您設定：在繫結 [收件箱套接字](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 在繫結套接字時將該套接字的路徑匯出到 hooks 和 Bash 命令。在以啟用訊息傳遞開始的工作階段中，Claude Code 在任何 hook 執行前繫結套接字。機器上的其他工作階段將訊息傳遞到此路徑。每個工作階段匯出自己的套接字，而不是從父工作階段繼承的套接字，到達它的訊息會透過工作階段的 [入站控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 進行。設定 `env` 區塊無法設定它。需要 Claude Code v2.1.224 或更新版本 |326| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 設定，不由您設定：在繫結 [收件匣通訊端](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 在繫結通訊端時將該通訊端的路徑匯出到 hooks 和 Bash 命令。在以啟用傳訊開始的工作階段中，Claude Code 在任何 hook 執行之前繫結通訊端。機器上的其他工作階段將訊息傳遞到此路徑。每個工作階段匯出自己的通訊端，而不是從父工作階段繼承的通訊端，到達它的訊息會透過工作階段的 [入站控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 進行。設定 `env` 區塊無法設定它。需要 Claude Code v2.1.224 或更新版本 |

328| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 設定，不由您設定：在繫結 [收件箱套接字](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 將此每個工作階段權杖匯出到 hooks 和 Bash 命令，與 `CLAUDE_CODE_MESSAGING_SOCKET` 一起。發佈到套接字的指令碼可以傳送 `{"type":"auth","token":"<token>"}` 作為其第一行以證明它屬於工作階段。在原生 Windows 上，Claude Code 需要此行並關閉任何不以有效行開啟的連線。[自有子規則](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 說明何時 Claude Code 查詢權杖。每個工作階段匯出自己的權杖，從不從父工作階段繼承的權杖。設定 `env` 區塊無法設定它。需要 Claude Code v2.1.228 或更新版本 |327| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 設定，不由您設定：在繫結 [收件匣通訊端](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 將此每個工作階段權杖匯出到 hooks 和 Bash 命令，與 `CLAUDE_CODE_MESSAGING_SOCKET` 一起。發佈到通訊端的指令碼可以傳送 `{"type":"auth","token":"<token>"}` 作為其第一行以證明它屬於工作階段。在原生 Windows 上，Claude Code 需要此行並關閉任何未使用有效行開啟的連線。[自有子規則](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 說明 Claude Code 何時查詢權杖。每個工作階段匯出自己的權杖，絕不是從父工作階段繼承的。設定 `env` 區塊無法設定它。需要 Claude Code v2.1.228 或更新版本 |

330| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動設定流程。流程在探索程式碼庫並寫入它們之前詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks。沒有此變數，`/init` 會自動產生 CLAUDE.md，而不提示 |329| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、技能和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md，而不提示 |

331| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設定為 `1` 以透過第二個非阻塞檔案描述符寫入終端輸出，因此停止讀取的終端（例如暫停的 tmux 控制模式窗格或停滯的 SSH 連線）無法在工作階段中途凍結 Claude Code。在 macOS、Linux 和 WSL 上應用，當 stdout 是終端時。需要 Claude Code v2.1.261 或更新版本 |330| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設定為 `1` 以透過第二個非阻塞檔案描述符寫入終端輸出，因此停止讀取的終端（例如暫停的 tmux 控制模式窗格或停滯的 SSH 連線）無法在工作階段中途凍結 Claude Code。在 macOS、Linux 和 WSL 上當 stdout 是終端時適用。需要 Claude Code v2.1.261 或更新版本 |

332| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [全螢幕呈現](/docs/zh-TW/fullscreen)，一項減少閃爍並在長對話中保持記憶體平坦的研究預覽。覆蓋 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |331| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [全螢幕呈現](/docs/zh-TW/fullscreen)，一項減少閃爍並在長對話中保持記憶體平坦的研究預覽。覆蓋 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |

333| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 驗證的 OAuth 重新整理權杖。設定時，`claude auth login` 直接交換此權杖，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。對於在自動化環境中佈建驗證很有用 |332| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 驗證的 OAuth 重新整理權杖。設定時，`claude auth login` 直接交換此權杖，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。對於在自動化環境中佈建驗證很有用 |

334| `CLAUDE_CODE_OAUTH_SCOPES` | 重新整理權杖發出的空格分隔 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必需 |333| `CLAUDE_CODE_OAUTH_SCOPES` | 重新整理權杖發出時使用的空格分隔 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必需 |

335| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 驗證的 OAuth 存取權杖。`/login` 對 SDK 和自動化環境的替代方案。優先於鑰匙圈儲存的認證。使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生一個。除非您執行 [`/login`](/docs/zh-TW/authentication#authentication-precedence)，否則 Claude Code 會為整個工作階段使用您設定的權杖。若要替換過期的權杖，產生新的並重新啟動 |334| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 驗證的 OAuth 存取權杖。`/login` 對 SDK 和自動化環境的替代方案。優先於鑰匙圈儲存的認證。使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生一個。除非您執行 [`/login`](/docs/zh-TW/authentication#authentication-precedence)，Claude Code 會在整個工作階段中使用您設定的權杖。若要替換過期的權杖，產生新的並重新啟動 |

336| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 在 v2.1.160 中移除，現在是無操作。以前將 [快速模式](/docs/zh-TW/fast-mode) 釘選到 Claude Opus 4.6，而不是目前的預設。Opus 4.6 不再支援快速模式 |335| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 在 v2.1.160 中移除，現在是無操作。先前將 [快速模式](/docs/zh-TW/fast-mode) 釘選到 Claude Opus 4.6，而不是目前的預設。Opus 4.6 不再支援快速模式 |

337| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 內容承載 OpenTelemetry 屬性（模型回應、工具內容、系統提示、原始 API 主體）的最大長度，截斷標記包括在內，以 UTF-16 程式碼單位為單位（預設：61440，即 60 KB）。僅當您的遙測後端接受大於 64 KB 的屬性值時才提高它，或降低它以減少遙測量。需要 Claude Code v2.1.214 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage) |336| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 內容承載 OpenTelemetry 屬性（模型回應、工具內容、系統提示、原始 API 主體）的最大長度，截斷標記包括在內，以 UTF-16 程式碼單位計（預設：61440，即 60 KB）。僅當您的遙測後端接受大於 64 KB 的屬性值時提高它，或降低它以減少遙測量。需要 Claude Code v2.1.214 或更新版本。請參閱 [監視](/docs/zh-TW/monitoring-usage) |

338| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設定為 `1` 以將 OpenTelemetry 匯出器診斷錯誤寫入 stderr。預設情況下，這些錯誤僅與 `--debug` 一起出現，因此配置不當的匯出器（例如 Prometheus 埠衝突）否則會無聲地失敗。需要 Claude Code v2.1.179 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage) |337| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設定為 `1` 以將 OpenTelemetry 匯出器診斷錯誤寫入 stderr。預設情況下，這些錯誤僅與 `--debug` 一起出現，因此配置不當的匯出器（例如 Prometheus 埠衝突）會以其他方式無聲地失敗。需要 Claude Code v2.1.179 或更新版本。請參閱 [監視](/docs/zh-TW/monitoring-usage) |

340| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000 / 29 分鐘）。請參閱 [動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |339| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000 / 29 分鐘）。請參閱 [動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |

341| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成的逾時（毫秒）（預設：2000）。如果指標在退出時被丟棄，請增加。請參閱 [監控](/docs/zh-TW/monitoring-usage) |340| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成的逾時（毫秒）（預設：2000）。如果指標在退出時被丟棄，請增加。請參閱 [監視](/docs/zh-TW/monitoring-usage) |

342| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設定為 `1` 以讓 Claude Code 在新版本可用時在背景執行您的套件管理員的升級命令。適用於 Homebrew 和 WinGet 安裝。其他套件管理員繼續顯示升級命令而不執行它。請參閱 [自動更新](/docs/zh-TW/setup#auto-updates) |341| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設定為 `1` 以讓 Claude Code 在新版本可用時在背景執行您的套件管理器升級命令。適用於 Homebrew 和 WinGet 安裝。其他套件管理器繼續顯示升級命令而不執行它。請參閱 [自動更新](/docs/zh-TW/setup#auto-updates) |

343| `CLAUDE_CODE_PERFORCE_MODE` | 設定為 `1` 以啟用 Perforce 感知寫入保護。設定時，如果目標檔案缺少所有者寫入位元（Perforce 在同步的檔案上清除，直到 `p4 edit` 開啟它們），Edit、Write 和 NotebookEdit 會失敗，並出現 `p4 edit <file>` 提示。這可防止 Claude Code 繞過 Perforce 變更追蹤 |342| `CLAUDE_CODE_PERFORCE_MODE` | 設定為 `1` 以啟用 Perforce 感知寫入保護。設定時，如果目標檔案缺少擁有者寫入位元（Perforce 在同步檔案上清除，直到 `p4 edit` 開啟它們），Edit、Write 和 NotebookEdit 會失敗並出現 `p4 edit <file>` 提示。這可防止 Claude Code 繞過 Perforce 變更追蹤 |

345| `CLAUDE_CODE_PLUGIN_DIRS` | 要為工作階段載入的外掛程式目錄，每個載入方式為 [`--plugin-dir`](/docs/zh-TW/plugins#test-your-plugins-locally) 旗標載入。在 Unix 上以 `:` 分隔多個路徑，在 Windows 上以 `;` 分隔。將每個路徑作為絕對路徑給出或以 `~` 開頭，因為 Claude Code 跳過相對路徑。需要 Claude Code v2.1.280 或更新版本 |344| `CLAUDE_CODE_PLUGIN_DIRS` | 要為工作階段載入的外掛程式目錄，每個都以 [`--plugin-dir`](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 旗標載入的方式載入。在 Unix 上用 `:` 分隔多個路徑，在 Windows 上用 `;`。將每個路徑指定為絕對路徑或以 `~` 開頭，因為 Claude Code 會跳過相對路徑。需要 Claude Code v2.1.280 或更新版本。請參閱 [為一個工作階段載入外掛程式](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session) |

346| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安裝或更新外掛程式時 git 操作的逾時（毫秒）（預設：120000）。對於大型儲存庫或緩慢網路連線，增加此值。請參閱 [Git 操作逾時](/docs/zh-TW/plugin-marketplaces#git-operations-time-out) |345| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 複製或重新整理外掛程式市場的逾時（毫秒）（預設：120000）。對於大型儲存庫或緩慢網路連線，增加此值。請參閱 [Git 複製逾時](/docs/zh-TW/plugins/troubleshooting#git-clone-timed-out-after-120s) |

347| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設定為 `1` 以在市場刷新無法到達或驗證遠端時跳過重新複製嘗試並繼續使用現有市場簽出。在離線或隔離環境中很有用，其中重新複製會以相同方式失敗。請參閱 [市場更新在離線環境中失敗](/docs/zh-TW/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |346| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設定為 `1` 以在市場重新整理無法到達或驗證遠端時跳過重新複製嘗試，並繼續使用現有市場簽出。在無法重新複製會以相同方式失敗的離線或隔離環境中很有用。請參閱 [市場更新在離線環境中持續失敗](/docs/zh-TW/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

348| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設定為 `1` 以透過 HTTPS 而不是 SSH 複製 GitHub `owner/repo` 速記來源。適用於外掛程式安裝和更新，以及 `/plugin marketplace add` 和 `update`。在 CI 執行器、容器或任何沒有為 `github.com` 配置 SSH 金鑰的環境中很有用 |347| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設定為 `1` 以透過 HTTPS 而不是 SSH 複製 GitHub `owner/repo` 速記來源。適用於外掛程式安裝和更新，以及 `/plugin marketplace add` 和 `update`。在 CI 執行器、容器或任何沒有為 `github.com` 配置 SSH 金鑰的環境中很有用 |

349| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一個或多個唯讀外掛程式種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此選項將預先填充的外掛程式目錄捆綁到容器映像中。Claude Code 在啟動時從這些目錄註冊市場，並使用預先快取的外掛程式而不重新複製。請參閱 [為容器預先填充外掛程式](/docs/zh-TW/plugin-marketplaces#pre-populate-plugins-for-containers) |348| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一個或多個唯讀外掛程式種子目錄的路徑，在 Unix 上用 `:` 分隔，在 Windows 上用 `;`。使用此選項將預先填充的外掛程式目錄捆綁到容器映像中。Claude Code 在啟動時從這些目錄註冊市場，並使用預先快取的外掛程式而不重新複製。請參閱 [為容器預先填充外掛程式](/docs/zh-TW/plugins/org#seed-containers-and-ci) |

350| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設定為 `1` 以停止 Claude Code 在為工具呼叫、hooks 和狀態列命令產生 PowerShell 時傳遞 `-ExecutionPolicy Bypass`，並改為尊重機器的有效執行政策。預設情況下，Claude Code 在程序範圍內繞過執行政策，因此 `.ps1` 指令碼和模組匯入在預設限制的 Windows 安裝上工作。程序範圍繞過永遠不會覆蓋 Group Policy `MachinePolicy` 或 `UserPolicy`，無論此設定如何 |349| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設定為 `1` 以停止 Claude Code 在為工具呼叫、hooks 和狀態列命令產生 PowerShell 時傳遞 `-ExecutionPolicy Bypass`，並改為尊重機器的有效執行政策。預設情況下，Claude Code 在程序範圍內繞過執行政策，以便 `.ps1` 指令碼和模組匯入在預設限制的 Windows 安裝上工作。程序範圍繞過無論此設定如何都絕不會覆蓋 Group Policy `MachinePolicy` 或 `UserPolicy` |

351| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在 [非互動模式](/docs/zh-TW/headless#background-tasks-at-exit) 中使用 `-p` 旗標的最終轉後，等待背景子代理和工作流程的閒置等待上限（毫秒）。每次 Claude 轉以處理背景結果時，閒置等待重新開始。預設：`600000`，或 10 分鐘。當閒置等待達到上限時，Claude Code 停止等待剩餘的背景工作並退出。設定為 `0` 以無限期等待。此上限與適用於純背景 shell 的五秒寬限期分開。需要 Claude Code v2.1.182 或更新版本 |350| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在 [非互動模式](/docs/zh-TW/headless#background-tasks-at-exit) 中使用 `-p` 旗標在最終轉向後等待背景子代理和工作流的閒置等待上限（毫秒）。每次 Claude 採取轉向來處理背景結果時，閒置等待重新開始。預設：`600000` 或 10 分鐘。當閒置等待達到上限時，Claude Code 停止等待剩餘的背景工作並退出。設定為 `0` 以無限期等待。此上限與適用於純背景 shell 的五秒寬限期分開。需要 Claude Code v2.1.182 或更新版本 |

352| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過公司啟動器（作為 argv 前綴給出，如 `/opt/corp/launcher`）啟動 Claude Code 從其自己的二進位檔啟動的程序，例如主機 [代理檢視](/docs/zh-TW/agent-view) 工作階段的背景服務。在使用者或 [受管設定](/docs/zh-TW/managed-settings) 的 `env` 區塊中設定它，而不是作為 shell 匯出，以便分離的背景服務繼承它；專案和本機設定無法設定它。等同於 [`processWrapper` 設定](/docs/zh-TW/settings-reference#processwrapper)，需要 Claude Code v2.1.210 或更新版本；當兩者都設定時，此變數優先。VS Code 擴充功能透過其 `claudeProcessWrapper` 設定單獨配置自己的啟動器。在 Windows 上被忽略。請參閱 [在公司啟動器後執行 Claude Code](/docs/zh-TW/corporate-launcher) 以了解值格式、啟動器涵蓋的內容以及啟動器必須滿足的合約。需要 Claude Code v2.1.208 或更新版本 |351| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過公司啟動器啟動 Claude Code 從其自己的二進位檔啟動的程序，例如主機 [代理檢視](/docs/zh-TW/agent-view) 工作階段的背景服務，給定為 argv 前綴，如 `/opt/corp/launcher`。在使用者或 [受管設定](/docs/zh-TW/managed-settings) 的 `env` 區塊中設定它，而不是作為 shell 匯出，以便分離的背景服務繼承它；專案和本機設定無法設定它。等同於 [`processWrapper` 設定](/docs/zh-TW/settings-reference#processwrapper)，需要 Claude Code v2.1.210 或更新版本；當兩者都設定時，此變數優先。VS Code 擴充功能透過其 `claudeProcessWrapper` 設定單獨設定自己的啟動器。在 Windows 上忽略。請參閱 [在公司啟動器後執行 Claude Code](/docs/zh-TW/corporate-launcher) 以了解值格式、啟動器涵蓋的內容以及啟動器必須滿足的合約。需要 Claude Code v2.1.208 或更新版本 |

353| `CLAUDE_CODE_PROJECT_DIR_NAME` | 與 `CLAUDE_CONFIG_DIR` 一起設定，以選擇 Claude Code 儲存該工作階段的文字記錄和自動記憶的 `projects/` 目錄名稱，代替從工作目錄路徑衍生的名稱。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 啟動 Claude Code 將它們儲存在 `/srv/tenant-a/projects/work/` 下。當 `CLAUDE_CONFIG_DIR` 未設定時，Claude Code 會忽略此變數，並讀取它僅從您啟動 `claude` 的環境，從不從 [設定檔 `env` 區塊](#in-settings-files)。請參閱 [自己命名專案目錄](/docs/zh-TW/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更新版本 |352| `CLAUDE_CODE_PROJECT_DIR_NAME` | 與 `CLAUDE_CONFIG_DIR` 一起設定以選擇 `projects/` 目錄名稱，Claude Code 在其下儲存該工作階段的文字記錄和自動記憶，代替從工作目錄路徑衍生的名稱。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 啟動 Claude Code 會將它們儲存在 `/srv/tenant-a/projects/work/` 下。當 `CLAUDE_CONFIG_DIR` 未設定時，Claude Code 會忽略此變數，並僅從啟動 `claude` 的環境讀取它，絕不從 [設定檔 `env` 區塊](#in-settings-files)。請參閱 [自己命名專案目錄](/docs/zh-TW/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更新版本 |

354| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`，Claude Code 接受的唯一值，以選擇主要對話的 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)：您的互動、`-p` 和 SDK 轉，加上與它們內聯執行的幫助程式。優先於 `promptCacheTtl` 設定，`ENABLE_PROMPT_CACHING_1H` 和 `FORCE_PROMPT_CACHING_5M` 覆蓋它。API 以更高的速率計費 1 小時快取寫入。需要 Claude Code v2.1.242 或更新版本 |353| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`，Claude Code 接受的唯一值，以選擇主要對話的 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)：您的互動、`-p` 和 SDK 轉向，加上與它們內聯執行的幫助程式。優先於 `promptCacheTtl` 設定和 `ENABLE_PROMPT_CACHING_1H`，`FORCE_PROMPT_CACHING_5M` 覆蓋它。API 以更高的速率計費 1 小時快取寫入。需要 Claude Code v2.1.242 或更新版本 |

355| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向自訂代理時傳播 W3C 追蹤上下文。傳播涵蓋模型和 HTTP MCP 請求上的 `traceparent` 標頭以及 Bash、PowerShell 和 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，傳播僅在直接連線到 Anthropic API 時啟用。在 v2.1.152 中新增。請參閱 [追蹤（測試版）](/docs/zh-TW/monitoring-usage#traces-beta) |354| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向自訂代理時傳播 W3C 追蹤上下文。傳播涵蓋模型和 HTTP MCP 請求上的 `traceparent` 標頭以及 Bash、PowerShell 和 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，傳播僅在直接連線到 Anthropic API 時啟用。在 v2.1.152 中新增。請參閱 [追蹤（測試版）](/docs/zh-TW/monitoring-usage#traces-beta) |

356| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代表其管理模型提供者路由的主機平台設定。設定時，Claude Code 會忽略設定檔中的提供者選擇、端點和驗證變數（例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`），因此使用者設定無法覆蓋主機的路由。Claude Code 也忽略 [受管設定](/docs/zh-TW/managed-settings) 中的模型選擇金鑰（例如 `model`、`fallbackModel` 和 `modelOverrides`），無論哪個受管來源傳遞它們，因此主機的模型配置優先於過期的受管模型釘選。Claude Code 也忽略受管 `env` 區塊中的模型選擇變數（例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列）；受管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單仍然適用，除非主機提供自己的。Claude Code 也跳過它在第三方提供者（例如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry）上否則應用的自動遙測選擇退出，因此遙測遵循標準 `DISABLE_TELEMETRY` 選擇退出。請參閱 [按 API 提供者的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |355| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代表其管理模型提供者路由的主機平台設定。設定時，Claude Code 會忽略設定檔中的提供者選擇、端點和驗證變數（例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`），因此使用者設定無法覆蓋主機的路由。Claude Code 也會忽略 [受管設定](/docs/zh-TW/managed-settings) 中的模型選擇金鑰（例如 `model`、`fallbackModel` 和 `modelOverrides`），無論哪個受管來源傳遞它們，因此主機的模型設定優先於過期的受管模型釘選。Claude Code 也會忽略受管 `env` 區塊中的模型選擇變數（例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列）；受管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單仍然適用，除非主機提供自己的。Claude Code 也會跳過它在第三方提供者（例如 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 和 Microsoft Foundry）上否則應用的自動遙測選擇退出，因此遙測遵循標準 `DISABLE_TELEMETRY` 選擇退出。請參閱 [按 API 提供者的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |

358| `CLAUDE_CODE_REMOTE` | 當 Claude Code 作為 [雲工作階段](/docs/zh-TW/claude-code-on-the-web) 執行時自動設定為 `true`。從 hook 或設定指令碼讀取此項以偵測您是否在雲工作階段中 |357| `CLAUDE_CODE_REMOTE` | 當 Claude Code 作為 [雲工作階段](/docs/zh-TW/claude-code-on-the-web) 執行時自動設定為 `true`。從 hook 或設定指令碼讀取此項以偵測您是否在雲工作階段中 |

359| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [雲工作階段](/docs/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造連結回工作階段文字記錄。請參閱 [將輸出連結回工作階段](/docs/zh-TW/cloud-environments#link-output-back-to-the-session) |358| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [雲工作階段](/docs/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以建構回工作階段文字記錄的連結。請參閱 [將輸出連結回工作階段](/docs/zh-TW/cloud-environments#link-output-back-to-the-session) |

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

361| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設定為 `1` 以在上一個工作階段在轉中途結束時自動繼續。在 SDK 模式中使用，以便模型繼續而無需 SDK 重新傳送提示。若要關閉此項，取消設定變數或將其設定為 `0`。在 v2.1.221 之前，Claude Code 忽略 `0` 和其他虛假值，因此在非互動模式中設定 `0` 仍會觸發繼續，取消設定變數是關閉它的唯一方式 |360| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設定為 `1` 以在上一個工作階段在轉向中途結束時自動繼續。在 SDK 模式中使用，以便模型繼續而不需要 SDK 重新傳送提示。若要關閉此項，取消設定變數或將其設定為 `0`。在 v2.1.221 之前，Claude Code 忽略 `0` 和其他虛假值，因此在非互動模式中設定 `0` 仍會觸發繼續，取消設定變數是關閉它的唯一方法 |

362| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 在中途結束的工作階段繼續自動繼續的最後文字記錄訊息的最大年齡（毫秒）。當最後訊息比此界限更舊時，Claude Code 會跳過 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自動繼續和注入的 `CLAUDE_CODE_RESUME_PROMPT` 繼續訊息，工作階段啟動閒置，以便您明確繼續。未設定或 `0` 表示無界限；負值或非數值值應用一小時界限。長時間執行代理的產生指令碼可以設定此項，以便針對舊文字記錄的重新啟動不會重新執行過時的提示。Claude Code 在重新啟動繼承其對話的崩潰 [代理檢視](/docs/zh-TW/agent-view) 工作階段時自己設定一小時界限。需要 Claude Code v2.1.211 或更新版本 |361| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 最後文字記錄訊息的最大年齡（毫秒），以便在中途結束的工作階段在繼續時自動繼續。當最後訊息比此界限更舊時，Claude Code 會跳過 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自動繼續及其 `CLAUDE_CODE_RESUME_PROMPT` 繼續訊息，工作階段啟動閒置，以便您明確繼續。未設定或 `0` 表示無界限，除了最後請求因 API 錯誤失敗的轉向僅在該錯誤少於六小時時繼續。正值界限每個轉向，包括那些；負值或非數值值應用一小時界限。長時間執行代理的產生指令碼可以設定此項，以便針對舊文字記錄的重新啟動不會重新執行過時的提示。Claude Code 在重新啟動從互動工作階段繼承其對話的崩潰 [代理檢視](/docs/zh-TW/agent-view) 工作階段時自己設定一小時界限。需要 Claude Code v2.1.211 或更新版本 |

363| `CLAUDE_CODE_RESUME_PROMPT` | 覆蓋在繼續在轉中途結束的工作階段時注入的繼續訊息。預設為 `Continue from where you left off.`。長時間執行代理的產生指令碼可以設定此項為更具指導性的啟動訊息。空字串使用預設值 |362| `CLAUDE_CODE_RESUME_PROMPT` | 覆蓋 Claude Code 在 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 繼續中途轉向而不是重新傳送其提示時傳送給 Claude 的繼續訊息，或當您使用 `-p` 繼續 [延遲工具呼叫](/docs/zh-TW/hooks#defer-a-tool-call-for-later) 時。預設為 `Continue from where you left off.`。空字串使用預設值 |

364| `CLAUDE_CODE_RETRY_WATCHDOG` | 對於無人值守工作階段（例如評估工具、CI 工作或遠端工作者），設定為 `1`。無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 嘗試後失敗。當標準速度請求取得報告支出限制或耗盡使用額度的 `429` 時，Claude Code 立即失敗，即使來自 [閘道支出上限](/docs/zh-TW/errors#spend-limit-reached) 的按計畫重設。在 v2.1.239 之前，看門狗無限期重試這些。對於快速模式請求，請參閱 [處理速率限制](/docs/zh-TW/fast-mode#handle-rate-limits)。看門狗在嘗試之間退避最多 5 分鐘，或直到限制重設（當回應攜帶速率限制重設時間時），因此達到使用限制的工作階段會等待剩餘視窗。在 v2.1.199 或更新版本上，它也為其他暫時性錯誤（例如伺服器錯誤、逾時和丟棄的連線）提高預設重試計數為 300，大約三小時的退避，如果您明確設定該變數，則移除 15 的上限。需要 Claude Code v2.1.186 或更新版本 |363| `CLAUDE_CODE_RETRY_WATCHDOG` | 設定為 `1` 用於無人值守工作階段，例如評估工具、CI 工作或遠端工作者。無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 嘗試後失敗。當標準速度請求取得報告支出限制或耗盡使用額度的 `429`（即使來自重設時間表的 [閘道支出上限](/docs/zh-TW/errors#spend-limit-reached)）時，Claude Code 立即失敗。在 v2.1.239 之前，監視狗無限期重試這些。對於快速模式請求，請參閱 [處理速率限制](/docs/zh-TW/fast-mode#handle-rate-limits)。監視狗在嘗試之間備份最多 5 分鐘，或直到限制重設（當回應攜帶速率限制重設時間時），因此達到使用限制的工作階段會等待剩餘視窗。在 v2.1.199 或更新版本上，它也為其他暫時性錯誤（例如伺服器錯誤、逾時和丟棄的連線）提高預設重試計數為 300，大約三小時的備份，如果您明確設定該變數，則移除 `CLAUDE_CODE_MAX_RETRIES` 的 15 上限。需要 Claude Code v2.1.186 或更新版本 |

365| `CLAUDE_CODE_SAFE_MODE` | 設定為 `1` 以在安全模式中啟動：CLAUDE.md、skills、外掛程式、hooks、MCP 伺服器、自訂命令和代理、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態列和檔案建議命令、LSP 伺服器和自動記憶不載入，用於疑難排解損壞的配置。受管設定政策仍然適用，包括政策配置的 hooks、狀態列和檔案建議命令；受管外掛程式、受管 skills、受管 CLAUDE.md 和政策配置的 MCP 伺服器不適用。等同於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接產生的子程序繼承變數 |364| `CLAUDE_CODE_SAFE_MODE` | 設定為 `1` 以在安全模式中啟動：CLAUDE.md、技能、外掛程式、hooks、MCP 伺服器、自訂命令和代理、輸出樣式、工作流、自訂主題、自訂快捷鍵、狀態列和檔案建議命令、LSP 伺服器和自動記憶不載入，用於疑難排解損壞的設定。受管設定政策仍然適用，包括政策配置的 hooks、狀態列和檔案建議命令；受管外掛程式、受管技能、受管 CLAUDE.md 和政策配置的 MCP 伺服器不適用。等同於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接產生的子程序繼承變數 |

366| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，限制設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時特定指令碼在每個工作階段中可能被呼叫的次數。金鑰是針對命令文字匹配的子字串；值是整數呼叫限制。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。匹配是基於子字串的，因此 shell 擴展技巧（如 `./scripts/deploy.sh $(evil)`）仍然計入上限。透過 `xargs` 或 `find -exec` 的執行時間扇出未被偵測；這是深度防禦控制 |365| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，限制當設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時特定指令碼在每個工作階段中可能被呼叫的次數。金鑰是針對命令文字進行的子字串比對；值是整數呼叫限制。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對是基於子字串的，因此 shell 擴充技巧（如 `./scripts/deploy.sh $(evil)`）仍然計入上限。透過 `xargs` 或 `find -exec` 的執行時間扇出未被偵測；這是深度防禦控制 |

367| `CLAUDE_CODE_SCROLL_SPEED` | 在 [全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling) 中設定滑鼠滾輪捲軸乘數。接受任何正值最多 20，包括低於 1 的分數值（例如 `0.5`）以減慢已放大的觸控板和滾輪捲軸在已放大滾輪事件的終端中。設定為 `3` 以在您的終端每個缺口傳送一個滾輪事件而不放大時符合 `vim`。在 JetBrains IDE 終端中被忽略，Claude Code 使用自己的捲軸處理 |366| `CLAUDE_CODE_SCROLL_SPEED` | 在 [全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling) 中設定滑鼠滾輪捲軸乘數。接受最多 20 的任何正值，包括低於 1 的分數值（例如 `0.5`）以減慢已放大的軌跡板和滾輪捲軸在已放大滾輪事件的終端中。設定為 `3` 以符合 `vim`，如果您的終端在沒有放大的情況下每個凹槽傳送一個滾輪事件。在 JetBrains IDE 終端中忽略，Claude Code 在那裡使用自己的捲軸處理 |

368| `CLAUDE_CODE_SEND_FEEDBACK` | 設定為 `0` 以為工作階段關閉 [Claude 起草的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。設定為 `1` 以在您的帳戶已有存取權的地方開啟；變數本身無法授予存取權，關閉回饋的其他開關（例如 `DISABLE_FEEDBACK_COMMAND` 和 [`feedbackDrafts`](/docs/zh-TW/settings-reference#feedbackdrafts) 設定的 `off` 值）仍然適用 |367| `CLAUDE_CODE_SEND_FEEDBACK` | 設定為 `0` 以為工作階段關閉 [Claude 起草的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。設定為 `1` 以在您的帳戶已有存取權的地方開啟；變數本身無法授予存取權，其他關閉回饋的開關（例如 `DISABLE_FEEDBACK_COMMAND` 和 [`feedbackDrafts`](/docs/zh-TW/settings-reference#feedbackdrafts) 設定的 `off` 值）仍然適用 |

369| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆蓋 [SessionEnd](/docs/zh-TW/hooks#sessionend) hooks 的時間預算（毫秒）。值也是未設定自己 `timeout` 的每個 hook 的逾時。適用於工作階段退出、`/clear` 和透過互動 `/resume` 切換工作階段。預設情況下，預算為 1.5 秒，自動提高到設定檔中配置的最高每個 hook `timeout`，最多 60 秒。外掛程式提供的 hooks 上的逾時不會提高預算 |368| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆蓋 [SessionEnd](/docs/zh-TW/hooks#sessionend) hooks 的時間預算（毫秒）。值也是未設定自己 `timeout` 的每個 hook 的逾時。適用於工作階段退出、`/clear` 和透過互動 `/resume` 切換工作階段。預設情況下，預算為 1.5 秒，自動提高到設定檔中配置的最高每個 hook `timeout`，最多 60 秒。外掛程式提供的 hooks 上的逾時不會提高預算 |

370| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序、[hook 命令](/docs/zh-TW/hooks) 子程序和 stdio [MCP 伺服器](/docs/zh-TW/mcp) 子程序中自動設定為目前工作階段 ID。對於 Bash、PowerShell 和 hooks，這符合 hook JSON 輸入中的 `session_id` 欄位，並在 `/clear` 上更新。MCP 伺服器子程序保留它產生時的 ID。在 `--resume <session-id>` 上，它接收繼續的 ID，符合 hooks 和 Bash。在 `--continue` 或 `--resume` 沒有明確 ID 上，它可能接收初始啟動 ID。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |369| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序、[hook 命令](/docs/zh-TW/hooks) 子程序和 stdio [MCP 伺服器](/docs/zh-TW/mcp) 子程序中自動設定為目前工作階段 ID。對於 Bash、PowerShell 和 hooks，這符合 hook JSON 輸入中的 `session_id` 欄位，並在 `/clear` 上更新。MCP 伺服器子程序保留它產生時的 ID。在 `--resume <session-id>` 上，它接收繼續的 ID，符合 hooks 和 Bash。在 `--continue` 或 `--resume` 沒有明確 ID 上，它可能改為接收初始啟動 ID。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |

371| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用於執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援 `fish` 等其他 shell。如果值不是工作的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並回退到自動偵測。自動偵測在指向 `bash` 或 `zsh` 時使用您的 `$SHELL`，否則它在您的 `PATH` 和標準安裝位置上選擇第一個工作的 `zsh` 然後 `bash` |370| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用於執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援 `fish` 等其他 shell。如果值不是工作的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並回退到自動偵測。自動偵測在指向 `bash` 或 `zsh` 時使用您的 `$SHELL`，否則它選擇在您的 `PATH` 和標準安裝位置上找到的第一個工作 `zsh`，然後 `bash` |

372| `CLAUDE_CODE_SHELL_PREFIX` | 包裝 Claude Code 產生的 shell 命令的命令前綴：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline) 命令和 stdio [MCP 伺服器](/docs/zh-TW/mcp) 啟動命令。PowerShell hooks 和 exec 形式 hooks 執行時不帶前綴。對於日誌記錄或稽核很有用。設定裸可執行檔路徑（例如 `/path/to/logger.sh`）將每個命令執行為 `/path/to/logger.sh '<command>'`。包裝器在 `$1` 中接收命令列作為單個 shell 引用的引數，因此包裝器必須使用 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為裸可執行檔路徑會破壞傳遞引數的 stdio MCP 伺服器，例如 `npx -y <package>`。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組合的完整 shell 呼叫，包括環境設定，而不僅僅是 Claude 執行的命令 |371| `CLAUDE_CODE_SHELL_PREFIX` | 包裝 Claude Code 產生的 shell 命令的命令前綴：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline) 命令和 stdio [MCP 伺服器](/docs/zh-TW/mcp) 啟動命令。PowerShell hooks 和 exec 形式 hooks 執行時不帶前綴。對於日誌記錄或稽核很有用。設定裸可執行檔路徑（例如 `/path/to/logger.sh`）將每個命令執行為 `/path/to/logger.sh '<command>'`。包裝器在 `$1` 中接收命令列作為單一 shell 引用的引數，因此包裝器必須使用 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為裸可執行檔路徑會破壞傳遞引數的 stdio MCP 伺服器，例如 `npx -y <package>`。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組合的完整 shell 呼叫，包括環境設定，而不僅僅是 Claude 執行的命令 |

373| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、自訂命令、子代理、外掛程式、MCP 伺服器、自動記憶和 CLAUDE.md 的自動發現。您使用 `--add-dir` 傳遞的目錄中的 Skills 仍然載入。OAuth 權杖和鑰匙圈認證未讀取，因此 Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |372| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、技能、自訂命令、子代理、已安裝外掛程式、MCP 伺服器、自動記憶和 CLAUDE.md 的自動探索。您使用 `--add-dir` 傳遞的目錄中的技能仍然載入。OAuth 權杖和鑰匙圈認證不被讀取，因此 Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |

374| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設定為 `1` 以在任何模型上使用較短的系統提示和縮寫工具說明。設定為 `0`、`false`、`no` 或 `off` 以選擇退出，即使在實驗或伺服器配置會否則啟用它的模型上。完整工具集、hooks、MCP 伺服器和 CLAUDE.md 發現保持啟用 |373| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設定為 `1` 以在任何模型上使用較短的系統提示和縮寫工具說明。設定為 `0`、`false`、`no` 或 `off` 以選擇退出，即使實驗或伺服器設定會否則啟用它。完整工具集、hooks、MCP 伺服器和 CLAUDE.md 探索保持啟用 |

375| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳過 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的用戶端驗證，用於自己簽署請求的閘道 |374| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳過 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 的用戶端驗證，用於自己簽署請求的閘道 |

376| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設定為 `1` 以關閉 AWS 預設認證提供者鏈解析的進程內快取，所以 Claude Code 在每個 API 請求上解析鏈。停用快取後，SSO 支援的設定檔在每個請求上從 IAM Identity Center 要求認證。請參閱 [認證快取和解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |375| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設定為 `1` 以關閉從 AWS 預設認證提供者鏈解析的認證的進程內快取，以便 Claude Code 在每個 API 請求上解析鏈。快取關閉後，由 SSO 支援的設定檔在每個請求上從 IAM Identity Center 要求認證。請參閱 [認證快取和解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |

378| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 設定為 `1` 以將失敗的 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性檢查視為可用，用於阻止檢查對 `api.anthropic.com` 的直接請求的網路。Claude Code 仍然尊重「您的組織停用」回應 |377| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 設定為 `1` 以將失敗的 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性檢查視為可用，用於阻止檢查直接請求到 `api.anthropic.com` 的網路。Claude Code 仍然尊重「您的組織停用了快速模式」回應 |

379| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設定為 `1` 以跳過用戶端 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性檢查，用於攔截檢查請求的代理而不是拒絕它。API 在您的組織停用快速模式時仍會拒絕快速模式請求 |378| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設定為 `1` 以跳過用戶端 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性檢查，用於攔截檢查請求的代理。API 在您的組織停用快速模式時仍會拒絕快速模式請求 |

380| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳過 Microsoft Foundry 的 Azure 驗證，用於代理或閘道注入自己的 `Authorization` 標頭。Claude Code 傳送沒有 Azure 認證的請求並保留您提供的 `Authorization` 標頭，例如透過 `ANTHROPIC_CUSTOM_HEADERS`。設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時被忽略。在 v2.1.203 之前，此變數使 Microsoft Foundry 用戶端無法傳送請求，除非同時設定了 API 金鑰 |379| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳過 Microsoft Foundry 的 Azure 驗證，用於注入自己 `Authorization` 標頭的代理或閘道。Claude Code 傳送沒有 Azure 認證的請求並保留您提供的 `Authorization` 標頭，例如透過 `ANTHROPIC_CUSTOM_HEADERS`。當設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時忽略。在 v2.1.203 之前，此變數使 Microsoft Foundry 用戶端無法傳送請求，除非同時設定了 API 金鑰 |

382| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設定為 `1` 以跳過將提示歷史記錄和工作階段文字記錄寫入磁碟。使用此變數啟動的工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中。對於短暫的指令碼工作階段很有用 |381| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設定為 `1` 以跳過將提示歷史記錄和工作階段文字記錄寫入磁碟。使用此變數啟動的工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中。對於暫時指令碼工作階段很有用 |

384| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 設定為 `1` 以讓以 `--output-format stream-json` 啟動的工作階段寫入 [結果訊息，說明 Claude Code 為何拒絕啟動](/docs/zh-TW/agent-sdk/typescript#startup_failure_reason)，用於否則以 stderr 結束的啟動失敗。需要 Claude Code v2.1.274 或更新版本 |383| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 設定為 `1` 以讓以 `--output-format stream-json` 啟動的工作階段為啟動失敗寫入 [結果訊息，命名 Claude Code 拒絕啟動的原因](/docs/zh-TW/agent-sdk/typescript#startup_failure_reason)，否則以 stderr 結尾。需要 Claude Code v2.1.274 或更新版本 |

385| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可能連續阻止轉結束的最大次數，然後 Claude Code 覆蓋它並無論如何結束轉（預設：8）。設定為 `0` 以停用上限。如果您的 hook 合法需要更多迭代來解決，請提高此值 |384| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可能在 Claude Code 覆蓋它並結束轉向之前連續阻止轉向結束的最大次數（預設：8）。設定為 `0` 以停用上限。如果您的 hook 合法需要更多迭代來解決，請提高此值 |

386| `CLAUDE_CODE_SUBAGENT_MODEL` | [子代理](/docs/zh-TW/sub-agents#choose-a-model)、[代理團隊](/docs/zh-TW/agent-teams#specify-teammates-and-models) 隊友和 [工作流程](/docs/zh-TW/workflows) 代理的預設模型，未以其他方式指派模型。接受別名（例如 `haiku`）或完整模型名稱。兩個來源優先於它：Claude 產生代理時傳遞的模型，以及代理定義中的 `model` 欄位，包括 `inherit`。若要變更該，設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)。請參閱 [選擇模型](/docs/zh-TW/sub-agents#choose-a-model) 以了解完整順序。將其設定為 `inherit` 與保持未設定相同。在 v2.1.251 之前，此變數覆蓋了每個呼叫模型和定義的 `model` 欄位 |385| `CLAUDE_CODE_SUBAGENT_MODEL` | [子代理](/docs/zh-TW/sub-agents#choose-a-model)、[代理團隊](/docs/zh-TW/agent-teams#specify-teammates-and-models) 隊友和 [工作流](/docs/zh-TW/workflows) 代理的預設模型，這些代理未以其他方式指派模型。接受別名（例如 `haiku`）或完整模型名稱。兩個來源優先於它：Claude 產生代理時傳遞的模型，以及代理定義中的 `model` 欄位，包括 `inherit`。若要變更該項，請設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)。請參閱 [選擇模型](/docs/zh-TW/sub-agents#choose-a-model) 以了解完整順序。將其設定為 `inherit` 與保持未設定相同。在 v2.1.251 之前，此變數覆蓋了每個呼叫模型和定義的 `model` 欄位 |

387| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 設定為 `1` 以強制一個模型到子代理、隊友和工作流程代理。[在一個模型上執行每個子代理](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model) 說明那是哪個模型。需要 Claude Code v2.1.257 或更新版本 |386| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 設定為 `1` 以強制一個模型到子代理、隊友和工作流代理。[在一個模型上執行每個子代理](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model) 說明那是哪個模型。需要 Claude Code v2.1.257 或更新版本 |

388| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`，Claude Code 接受的唯一值，以選擇主要對話外請求的 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，例如 [子代理](/docs/zh-TW/sub-agents)、工作流程和背景工作。優先於 `subagentPromptCacheTtl` 設定，`ENABLE_PROMPT_CACHING_1H` 和 `FORCE_PROMPT_CACHING_5M` 覆蓋它。API 以更高的速率計費 1 小時快取寫入。需要 Claude Code v2.1.242 或更新版本 |387| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`，Claude Code 接受的唯一值，以選擇主要對話外請求的 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，例如 [子代理](/docs/zh-TW/sub-agents)、工作流和背景工作。優先於 `subagentPromptCacheTtl` 設定和 `ENABLE_PROMPT_CACHING_1H`，`FORCE_PROMPT_CACHING_5M` 覆蓋它。API 以更高的速率計費 1 小時快取寫入。需要 Claude Code v2.1.242 或更新版本 |

389| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設定為 `1` 以從子程序環境中移除認證（Bash 工具、hooks、MCP stdio 伺服器）：Anthropic 和雲提供者認證、Claude Code 識別為認證的任何其他變數，以及套件登錄 URL 中嵌入的認證。父 Claude 程序保留這些認證用於 API 呼叫，但子程序無法讀取它們，減少試圖透過 shell 擴展竊取機密的提示注入攻擊的曝光。在 v2.1.251 或更新版本上，擦除也移除 Claude Code 自己的配置存放區指標變數（例如 `CLAUDE_CONFIG_DIR`），因此子程序無法定位重新定位的配置目錄。如果子程序需要這些變數，請保持擦除未設定。在 Linux 上，這也在隔離的 PID 命名空間中執行 Bash 子程序，因此它們無法透過 `/proc` 讀取主機程序環境；作為副作用，`ps`、`pgrep` 和 `kill` 無法看到或發信號給主機程序。`claude-code-action` 在配置 `allowed_non_write_users` 時自動設定此項 |388| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設定為 `1` 以從子程序環境中移除認證（Bash 工具、hooks、MCP stdio 伺服器）：Anthropic 和雲提供者認證、Claude Code 識別為認證的任何其他變數，以及嵌入在套件登錄 URL 中的認證。父 Claude 程序保留這些認證用於 API 呼叫，但子程序無法讀取它們，減少試圖透過 shell 擴充洩露機密的提示注入攻擊的曝光。在 v2.1.251 或更新版本上，擦除也移除 Claude Code 自己的設定存放區指標變數（例如 `CLAUDE_CONFIG_DIR`），因此子程序無法找到重新定位的設定目錄。如果子程序需要這些變數，請保持擦除未設定。在 Linux 上，這也在隔離的 PID 命名空間中執行 Bash 子程序，以便它們無法透過 `/proc` 讀取主機程序環境；作為副作用，`ps`、`pgrep` 和 `kill` 無法看到或發信號給主機程序。`claude-code-action` 在設定 `allowed_non_write_users` 時自動設定此項 |

390| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設定為 `1` 以等待外掛程式安裝完成，然後才進行第一個查詢。沒有此項，外掛程式在背景安裝，可能在第一個轉上不可用。與 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 結合以限制等待 |389| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設定為 `1` 以等待外掛程式安裝完成，然後才進行第一個查詢。沒有此項，外掛程式在背景安裝，可能在第一個轉向上不可用。與 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 結合以界限等待 |

392| `CLAUDE_CODE_SYNC_SKILLS` | 在非互動模式中設定為 `1`，使用 `-p` 旗標，以使 Claude Code 在該執行中下載為您的 claude.ai 帳戶啟用的 skills，並等待它們的清單，最多 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`，然後才執行第一個查詢。下載本身在背景完成，Claude 在呼叫該 skill 時等待 skill 的下載。需要 claude.ai 驗證。您登入 claude.ai 帳戶的終端工作階段 [下載這些 skills](/docs/zh-TW/skills#where-synced-skills-load) 到 `~/.claude/skills/synced/` 並大約每 10 分鐘重新同步，沒有此變數，因此僅在 `-p` 執行需要您目前 skills 在其第一個查詢上時設定。在 v2.1.273 之前，終端工作階段僅在帶此變數集的 `-p` 執行中下載它們。`synced` 資料夾名稱 [為此下載保留](/docs/zh-TW/skills#where-skills-live)。在 v2.1.227 之前，skills 直接下載到 `~/.claude/skills/` 中。Claude Code 對下載的 skills 應用 [額外規則](/docs/zh-TW/skills#how-synced-skills-behave)，例如不在您的機器上執行它們的 `!` 命令 |391| `CLAUDE_CODE_SYNC_SKILLS` | 在非互動模式中設定為 `1`，使用 `-p` 旗標，以使 Claude Code 下載為您的 claude.ai 帳戶啟用的技能在該執行中，並等待它們的清單，最多 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`，然後才執行第一個查詢。下載本身在背景完成，Claude 在呼叫該技能時等待技能的下載。需要 claude.ai 驗證。您登入 claude.ai 帳戶的終端工作階段 [下載這些技能](/docs/zh-TW/skills#where-synced-skills-load) 到 `~/.claude/skills/synced/` 並大約每 10 分鐘重新同步，而不需要此變數，因此僅在 `-p` 執行需要您目前技能在其第一個查詢上時設定它。在 v2.1.273 之前，終端工作階段僅在帶有此變數集的 `-p` 執行中下載它們。`synced` 資料夾名稱 [保留用於此下載](/docs/zh-TW/skills#where-skills-live)。在 v2.1.227 之前，技能直接下載到 `~/.claude/skills/`。Claude Code 對下載的技能應用 [額外規則](/docs/zh-TW/skills#how-synced-skills-behave)，例如不在您的機器上執行其 `!` 命令 |

393| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 應用程式建立在 [Agent SDK](/docs/zh-TW/agent-sdk/typescript#query-object) 上重新載入 skills 時執行的 skills 重新同步的逾時（毫秒）（預設：30000）。超過時，重新載入繼續使用已到達的任何 skills，剩餘下載在背景完成 |392| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當在 [Agent SDK](/docs/zh-TW/agent-sdk/typescript#query-object) 上建立的應用程式重新載入技能時執行的技能重新同步的逾時（毫秒）（預設：30000）。超過時，重新載入繼續進行，無論已到達哪些技能，剩餘下載在背景完成 |

394| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 當設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skill 清單的逾時（毫秒）（預設：5000）。超過時，第一個查詢使用已到達的任何 skills 執行。下載無論如何都會在背景完成，Claude 在呼叫該 skill 時等待 skill 的下載 |393| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 當設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始技能清單的逾時（毫秒）（預設：5000）。超過時，第一個查詢執行，無論已到達哪些技能。下載無論如何都在背景完成，Claude 在呼叫該技能時等待技能的下載 |

395| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設定為 `false` 以停用差異輸出中的語法突出顯示。當顏色干擾您的終端設定時很有用。若要也停用程式碼區塊和檔案預覽中的突出顯示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |394| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設定為 `false` 以停用差異輸出中的語法醒目提示。當顏色干擾您的終端設定時很有用。若要也停用程式碼區塊和檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |

396| `CLAUDE_CODE_TASK_LIST_ID` | 跨工作階段共享工作清單。在多個 Claude Code 執行個體中設定相同 ID 以在 [具有 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability) 中協調共享工作清單。請參閱 [工作清單](/docs/zh-TW/interactive-mode#task-list) |395| `CLAUDE_CODE_TASK_LIST_ID` | 跨工作階段共享工作清單。在多個 Claude Code 執行個體中設定相同的 ID 以在 [具有 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability) 中協調共享工作清單。請參閱 [工作清單](/docs/zh-TW/interactive-mode#task-list) |

397| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 覆蓋非互動工作階段在退出時等待其 [代理團隊](/docs/zh-TW/agent-teams) 完成拆卸的時間（毫秒）。接受 1000 到 60000；超出範圍的值被忽略，預設 10000 適用。需要 Claude Code v2.1.206 或更新版本 |396| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 覆蓋非互動工作階段在退出時等待其 [代理團隊](/docs/zh-TW/agent-teams) 完成拆卸的時間（毫秒）。接受 1000 到 60000；超出範圍的值被忽略，預設 10000 適用。需要 Claude Code v2.1.206 或更新版本 |

398| `CLAUDE_CODE_TMPDIR` | 覆蓋用於內部臨時檔案的臨時目錄。Claude Code 在 Unix 上附加 `/claude-{uid}/` 或在 Windows 上附加 `/claude/` 到此路徑。預設：macOS 上 `/tmp`，Linux 和 Windows 上 `os.tmpdir()`。在 macOS 和 Linux 上，[沙箱化](/docs/zh-TW/sandboxing) Bash 子程序在您的覆蓋是長路徑時在系統預設下接收短回退 `$TMPDIR`，因為某些工具在臨時路徑變得太長時失敗。未沙箱化的 Bash 命令繼承您的 shell 的 `$TMPDIR` 不變。Claude Code 自己的臨時檔案始終使用您的覆蓋。在您的 shell、使用者設定或受管設定中設定它。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |397| `CLAUDE_CODE_TMPDIR` | 覆蓋用於內部暫時檔案的暫時目錄。Claude Code 在 Unix 上附加 `/claude-{uid}/`，在 Windows 上附加 `/claude/` 到此路徑。預設：macOS 上的 `/tmp`，Linux 和 Windows 上的 `os.tmpdir()`。在 macOS 和 Linux 上，[沙箱化](/docs/zh-TW/sandboxing) Bash 子程序在您的覆蓋是長路徑時在系統預設下接收短回退 `$TMPDIR`，因為某些工具在暫時路徑變得太長時失敗。未沙箱化的 Bash 命令在設定時繼承您的 shell 的 `$TMPDIR`。Claude Code 自己的暫時檔案始終使用您的覆蓋。在您的 shell、使用者設定或受管設定中設定它。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略 |

399| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設定為任何非空值（例如 `1`）以允許 tmux 內的 24 位真彩色輸出。**將其設定為 `0` 或 `false` 仍允許真彩色**，與大多數開啟/關閉變數不同；取消設定變數以恢復 256 色限制。預設情況下，當設定 `$TMUX` 時，Claude Code 限制為 256 色，因為 tmux 不會透過真彩色逃逸序列，除非配置。在將 `set -ga terminal-overrides ',*:Tc'` 新增到您的 `~/.tmux.conf` 後設定此項。請參閱 [終端配置](/docs/zh-TW/terminal-config) 以了解其他 tmux 設定 |398| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設定為任何非空值（例如 `1`）以允許 tmux 內的 24 位真彩色輸出。**將其設定為 `0` 或 `false` 仍允許真彩色**，與大多數開啟/關閉變數不同；取消設定變數以恢復 256 色限制。預設情況下，當設定 `$TMUX` 時，Claude Code 限制為 256 色，因為 tmux 不會透過真彩色逃逸序列，除非設定。在將 `set -ga terminal-overrides ',*:Tc'` 新增到您的 `~/.tmux.conf` 後設定此項。請參閱 [終端設定](/docs/zh-TW/terminal-config) 以了解其他 tmux 設定 |

400| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 和 WSL 上，設定為 Claude Code [從工具記憶體上限排除](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl) 的程序類型的逗號分隔列表，例如 `mcp` 或 `lsp`。設定 `none` 以限制每種類型，或 `all-new` 以僅限制 Bash、PowerShell 和 Monitor 工具命令。Claude Code 無論您列出什麼，都將 Bash、PowerShell 和 Monitor 工具命令保持在上限下。需要 Claude Code v2.1.246 或更新版本 |399| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 和 WSL 上，設定為 Claude Code [從工具記憶體上限排除](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl) 的程序類型的逗號分隔列表，例如 `mcp` 或 `lsp`。設定 `none` 以上限每種類型，或設定 `all-new` 以僅上限 Bash、PowerShell 和 Monitor 工具命令。Claude Code 無論您列出什麼，都會將 Bash、PowerShell 和 Monitor 工具命令保持在上限下。需要 Claude Code v2.1.246 或更新版本 |

401| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 和 WSL 上，設定為大小（例如 `4G`）以 [限制 Bash 和 PowerShell 工具命令可以使用的記憶體](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，以及 v2.1.246 或更新版本上的 Monitor 工具命令。以純數字單獨寫入大小（以位元組為單位）或帶 `K`、`M`、`G` 或 `T` 後綴。設定 `0` 或 `off` 以關閉上限。一旦 Claude Code 啟動的第一個程序已開啟或關閉上限，變更的值在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |400| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 和 WSL 上，設定為大小（例如 `4G`）以 [上限 Bash 和 PowerShell 工具命令可以使用的記憶體](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，以及 v2.1.246 或更新版本上的 Monitor 工具命令。以純數字單獨寫入大小（位元組數）或帶有 `K`、`M`、`G` 或 `T` 後綴。設定 `0` 或 `off` 以關閉上限。一旦 Claude Code 啟動的第一個程序已開啟或關閉上限，變更的值在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |

402| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消它轉發給遠端用戶端（例如 [Remote Control](/docs/zh-TW/remote-control) 或 SDK 主機）的對話框的期限（毫秒），或 [保持的跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 的批准對話框；權限提示和 `AskUserQuestion` 問題使用自己的流程，不受它管轄。在 Claude Code v2.1.236 或更新版本上，它也限制可能無人值守執行的工作階段中的中期 [Fable 使用額度同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)。[控制入站訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 和 [非互動工作階段](/docs/zh-TW/cross-session-messaging#non-interactive-sessions) 涵蓋完整的保持訊息過期規則，包括期限不適用的情況。覆蓋 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定。`0` 或負值停用期限 |401| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 在取消它轉發給遠端用戶端（例如 [Remote Control](/docs/zh-TW/remote-control) 或 SDK 主機）的對話之前的期限（毫秒），或 [保持的跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 的批准對話；權限提示和 `AskUserQuestion` 問題使用自己的流程，不受它管理。在 Claude Code v2.1.236 或更新版本上，它也界限可能無人值守執行的工作階段中的中期 [Fable 使用額度同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)。[控制入站訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 和 [非互動工作階段](/docs/zh-TW/cross-session-messaging#non-interactive-sessions) 涵蓋完整保持訊息過期規則，包括期限不適用的情況。覆蓋 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定。`0` 或負值停用期限 |

407| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設定為 `1` 以使用 Node.js 檔案 API 而不是 ripgrep 發現自訂命令、子代理和輸出樣式。如果捆綁的 ripgrep 二進位檔在您的環境中不可用或被阻止，請設定此項。不影響 Grep 或檔案搜尋工具 |406| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設定為 `1` 以使用 Node.js 檔案 API 而不是 ripgrep 探索自訂命令、子代理和輸出樣式。如果捆綁的 ripgrep 二進位檔在您的環境中不可用或被阻止，請設定此項。不影響 Grep 或檔案搜尋工具 |

408| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在沒有 Git Bash 的 Windows 上，工具自動啟用；設定為 `0` 以停用它。在安裝了 Git Bash 的 Windows 上，工具對 claude.ai 和 Console 帳戶預設開啟；設定為 `1` 以在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 工作階段中啟用它，或設定為 `0` 以關閉它。在 Linux、macOS 和 WSL 上，設定為 `1` 以啟用它，這需要您的 `PATH` 上的 `pwsh`。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不是透過 Git Bash 路由。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |407| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在沒有 Git Bash 的 Windows 上，工具自動啟用；設定為 `0` 以停用它。在安裝了 Git Bash 的 Windows 上，工具預設為 claude.ai 和 Console 帳戶開啟；設定為 `1` 以在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 工作階段中啟用它，或設定為 `0` 以關閉它。在 Linux、macOS 和 WSL 上，設定為 `1` 以啟用它，這需要您的 `PATH` 上的 `pwsh`。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不是透過 Git Bash 路由。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |

410| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 設定為 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 保持每個擷取 URL 回應快取的毫秒數。預設為 `900000`，即 15 分鐘。僅接受純數字；`0`、小數或任何其他拼寫保持預設。Claude Code 每次啟動讀取值一次，所以設定 `env` 區塊中的變更在您下次啟動 `claude` 時適用。需要 Claude Code v2.1.233 或更新版本 |409| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 設定為 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 保持每個擷取 URL 回應快取的毫秒數。預設為 `900000`，即 15 分鐘。僅接受純數字；`0`、小數或任何其他拼寫保持預設。Claude Code 每次啟動讀取值一次，因此設定 `env` 區塊中的變更在您下次啟動 `claude` 時適用。需要 Claude Code v2.1.233 或更新版本 |

411| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載的上限（毫秒），包括它遵循的任何重新導向。未在該時間完成的下載失敗，並出現期限錯誤。預設為 `300000`，即五分鐘。設定為 `0` 以移除限制。僅接受純數字；小數或任何其他拼寫保持預設。需要 Claude Code v2.1.268 或更新版本 |410| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載的上限（毫秒），包括它遵循的任何重新導向。未在該時間內完成的下載會失敗，並出現期限錯誤。預設為 `300000`，即五分鐘。設定為 `0` 以移除限制。僅接受純數字；小數或任何其他拼寫保持預設。需要 Claude Code v2.1.268 或更新版本 |

412| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 一個 [工作流程](/docs/zh-TW/workflows) 執行一次執行多少個代理，從 `1` 到 `256`。預設情況下，執行一次執行最多 16 個代理，當 Claude Code 有更少 CPU 可用時更少；排隊的 `agent()` 呼叫等待空閒槽。每個執行中代理的文字記錄保留在 Claude Code 的記憶體中，因此較高的值提高記憶體使用。僅接受純數字；超出範圍的值和其他拼寫保持預設。需要 Claude Code v2.1.269 或更新版本 |411| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 單個 [工作流](/docs/zh-TW/workflows) 執行一次執行的代理數，從 `1` 到 `256`。預設情況下，執行一次執行最多 16 個代理，當 Claude Code 有更少 CPU 可用時更少；排隊的 `agent()` 呼叫等待空閒插槽。每個執行中代理的文字記錄保留在 Claude Code 的記憶體中，因此較高的值會提高記憶體使用。僅接受純數字；超出範圍的值和其他拼寫保持預設。需要 Claude Code v2.1.269 或更新版本 |

413| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流程](/docs/zh-TW/workflows) 代理等待相同前綴同級的第一個回應開始的上限（毫秒），然後才傳送自己的第一個請求。當扇出啟動共享 [提示快取前綴](/docs/zh-TW/workflows#prompt-caching-in-a-fan-out) 的多個代理時，Claude Code 將除第一個外的所有代理保持最多此長時間，以便其餘代理讀取快取的前綴，而不是每個未快取地處理它。預設 `5000`。設定為 `0` 以停用等待。當設定 `DISABLE_PROMPT_CACHING` 時，代理永遠不會等待。需要 Claude Code v2.1.229 或更新版本 |412| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流](/docs/zh-TW/workflows) 代理等待相同前綴同級的第一個回應開始的上限（毫秒），然後才傳送自己的第一個請求。當扇出啟動共享 [提示快取前綴](/docs/zh-TW/workflows#prompt-caching-in-a-fan-out) 的多個代理時，Claude Code 將除第一個外的所有代理保持最多此長時間，以便其餘代理讀取快取的前綴，而不是每個未快取地處理它。預設 `5000`。設定為 `0` 以停用等待。當設定 `DISABLE_PROMPT_CACHING` 時，代理絕不會等待。需要 Claude Code v2.1.229 或更新版本 |

414| `CLAUDE_CONFIG_DIR` | 覆蓋配置目錄（預設：`~/.claude`）。所有設定、工作階段歷史記錄和外掛程式都儲存在此路徑下。有關認證，請參閱 [Claude Code 儲存認證的位置](/docs/zh-TW/authentication#credential-management)。對於並排執行多個帳戶很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。在您的 shell、使用者設定或受管設定中設定它。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |413| `CLAUDE_CONFIG_DIR` | 覆蓋設定目錄（預設：`~/.claude`）。所有設定、工作階段歷史記錄和外掛程式都儲存在此路徑下。對於認證，請參閱 [Claude Code 儲存認證的位置](/docs/zh-TW/authentication#credential-management)。對於並行執行多個帳戶很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。在您的 shell、使用者設定或受管設定中設定它。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略 |

415| `CLAUDE_DISABLE_ADOPT` | 設定為 `1` 以在您按 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 背景化工作階段時停止進行中的背景工作，而不是進行中的工作。Claude Code 要求您在背景化前確認，然後停止會否則進行的工作。需要 Claude Code v2.1.195 或更新版本 |414| `CLAUDE_DISABLE_ADOPT` | 設定為 `1` 以停止進行中的背景工作，而不是在您按 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 背景化工作階段時進行。Claude Code 要求您在背景化前確認，然後停止會否則進行的工作。需要 Claude Code v2.1.195 或更新版本 |

416| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中自動設定為子程序啟動時有效的 [effort 級別](/docs/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是不同的級別，報告為 `xhigh`。符合傳遞給 [hooks](/docs/zh-TW/hooks) 的 `effort.level` 欄位。僅在目前模型支援 effort 參數時設定 |415| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中自動設定為子程序啟動時生效的 [effort 級別](/docs/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是不同的級別，報告為 `xhigh`。符合傳遞給 [hooks](/docs/zh-TW/hooks) 的 `effort.level` 欄位。僅在目前模型支援 effort 參數時設定 |

417| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元組級串流閒置看門狗，或設定為 `0` 以強制停用它。`0` 也關閉執行該期限的連線上的 [第一位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)。未設定時，看門狗在直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 連線上預設啟用，以及透過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 到達的 [閘道](/docs/zh-TW/gateways) 連線上的串流回應；在 v2.1.222 之前，它在這些閘道連線上不執行，因此事件級看門狗可能在那裡報告停滯，即使保活 ping 到達。有關逾時以及計時器如何互動，請參閱 [串流閒置看門狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) |416| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元組級串流閒置監視狗，或設定為 `0` 以強制停用它。`0` 也會在執行該期限的連線上關閉 [第一位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)。未設定時，監視狗預設在直接 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 連線上啟用，以及透過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 到達的 [閘道](/docs/zh-TW/gateways) 連線上的串流回應；在 v2.1.222 之前，它不在這些閘道連線上執行，因此事件級監視狗可能在那裡報告停滯，即使保活 ping 正在到達。對於逾時以及計時器如何互動，請參閱 [串流閒置監視狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

418| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組級串流閒置看門狗，這也啟用 Bedrock 串流請求上的 [第一位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |417| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組級串流閒置監視狗，這也啟用 [第一位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs) 在 Bedrock 串流請求上。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時 |

419| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `0` 以強制停用事件級串流閒置看門狗，或設定為 `1` 以強制啟用它。未設定時，看門狗在所有提供者上預設開啟。在 v2.1.196 之前，未設定的預設在直接 Anthropic API 上由伺服器控制，在其他提供者上關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時；有關與此一起執行的其他停滯計時器，請參閱 [串流閒置看門狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) |418| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `0` 以強制停用事件級串流閒置監視狗，或設定為 `1` 以強制啟用它。未設定時，監視狗預設在所有提供者上開啟。在 v2.1.196 之前，未設定的預設在直接 Anthropic API 上由伺服器控制，在其他提供者上關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時；對於與此一起執行的其他停滯計時器，請參閱 [串流閒置監視狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

420| `CLAUDE_ENV_FILE` | shell 指令碼的路徑，其內容 Claude Code 在同一 shell 程序中的每個 Bash 命令前執行，因此檔案中的匯出對命令可見。用於在命令之間保持 virtualenv 或 conda 啟用。也由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 和 [FileChanged](/docs/zh-TW/hooks#filechanged) hooks 動態填充 |419| `CLAUDE_ENV_FILE` | shell 指令碼的路徑，其內容 Claude Code 在同一 shell 程序中的每個 Bash 命令之前執行，因此檔案中的匯出對命令可見。用於在命令之間保持 virtualenv 或 conda 啟用。也由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 和 [FileChanged](/docs/zh-TW/hooks#filechanged) hooks 動態填充 |

421| `CLAUDE_JOB_DIR` | 由 Claude Code 在每個 [背景工作階段](/docs/zh-TW/agent-view) 中設定為該工作階段的 `~/.claude/jobs/<id>` 目錄。工作階段執行的 shell 命令繼承它。將暫存檔案寫入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-TW/agent-view#where-state-is-stored)。Claude 的 `Write` 和 `Edit` 呼叫在那裡不提示權限，目錄在工作階段刪除時移除 |420| `CLAUDE_JOB_DIR` | 由 Claude Code 在每個 [背景工作階段](/docs/zh-TW/agent-view) 中設定為該工作階段的 `~/.claude/jobs/<id>` 目錄。工作階段執行的 shell 命令繼承它。將暫時檔案寫入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-TW/agent-view#where-state-is-stored)。Claude 的 `Write` 和 `Edit` 呼叫在那裡不提示權限，目錄在工作階段被刪除時移除 |

422| `CLAUDE_PID` | Claude Code 在它產生的子程序中將此設定為其自己的程序 ID：Bash 和 PowerShell 工具命令和 hook 命令。在 Linux 上，Bash 工具的 shell 整合使用它來拒絕會符合 Claude Code 程序本身的 `pkill` 模式；請參閱 [錯誤參考](/docs/zh-TW/errors#pkill-pattern-matches-the-claude-code-process)。從您自己的指令碼讀取它以故意識別或發信號給父 Claude Code 程序。需要 Claude Code v2.1.214 或更新版本 |421| `CLAUDE_PID` | Claude Code 在它產生的子程序中將此設定為自己的程序 ID：Bash 和 PowerShell 工具命令和 hook 命令。在 Linux 上，Bash 工具的 shell 整合使用它來拒絕會符合 Claude Code 程序本身的 `pkill` 模式；請參閱 [錯誤參考](/docs/zh-TW/errors#pkill-pattern-matches-the-claude-code-process)。從您自己的指令碼讀取它以有意識地識別或發信號給父 Claude Code 程序。需要 Claude Code v2.1.214 或更新版本 |

423| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 當未提供明確名稱時，[Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的自動產生前綴。預設為您機器的主機名稱，產生 `myhost-graceful-unicorn` 之類的名稱。`--remote-control-session-name-prefix` CLI 旗標為單個呼叫設定相同的值 |422| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 當未提供明確名稱時，自動產生的 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您機器的主機名稱，產生 `myhost-graceful-unicorn` 之類的名稱。`--remote-control-session-name-prefix` CLI 旗標為單一呼叫設定相同的值 |

424| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 串流請求的第一個回應位元組的期限（毫秒），在 [第一位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs) 執行的連線上。有關 Claude Code 如何限制它、它為大型請求主體新增的額外時間，以及當您保持此未設定時如何選擇期限，請參閱 [API 無回應](/docs/zh-TW/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更新版本 |423| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 串流請求的第一個回應位元組的期限（毫秒），在 [第一位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs) 執行的連線上。對於 Claude Code 如何限制它、它為大型請求主體新增的額外時間，以及當您保持此未設定時如何選擇期限，請參閱 [API 無回應](/docs/zh-TW/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更新版本 |

425| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件級和位元組級串流閒置看門狗在停滯連線前的逾時（毫秒）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值無聲地限制在吸收擴展思考暫停和代理緩衝，位元組級看門狗將值上限為 30 分鐘。`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數用於位元組級看門狗。有關每個看門狗未設定的預設值，請參閱 [串流閒置看門狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) |424| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件級和位元組級串流閒置監視狗在停滯連線前的逾時（毫秒）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會無聲地限制到吸收擴充思考暫停和代理緩衝，位元組級監視狗將值上限為 30 分鐘。`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數用於位元組級監視狗。對於每個監視狗未設定的預設值，請參閱 [串流閒置監視狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

426| `DEBUG` | 設定為 `1` 以啟用偵錯模式，等同於使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 啟動。偵錯日誌寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 設定的路徑。僅真實值 `1`、`true`、`yes` 和 `on` 啟用偵錯模式，因此為其他工具設定的命名空間模式（如 `DEBUG=express:*`）不會觸發它 |425| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 在 v2.1.260 中移除，現在是無操作。先前上限了 [背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)（[子代理](/docs/zh-TW/sub-agents) 啟動的）可以執行的時間（毫秒），預設 60 分鐘。請參閱 [背景命令生命週期規則](/docs/zh-TW/tools-reference#background-commands) |

428| `DISABLE_AUTO_COMPACT` | 設定為 `1` 以停用接近上下文限制時的自動壓縮。手動 `/compact` 命令保持可用。當您想要明確控制何時進行壓縮時使用。覆蓋 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |428| `DISABLE_AUTO_COMPACT` | 設定為 `1` 以停用接近上下文限制時的自動壓縮。手動 `/compact` 命令保持可用。當您想要明確控制何時進行壓縮時使用。覆蓋 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |

431| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 以隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。對於使用者不應從工作階段執行設定診斷的受管部署很有用。不影響 `claude doctor` 終端命令。在 v2.1.205 之前，此變數隱藏了 `/doctor` 診斷螢幕命令 |431| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 以隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查技能及其 `/checkup` 別名。對於使用者不應從工作階段執行設定診斷的受管部署很有用。不影響 `claude doctor` 終端命令。在 v2.1.205 之前，此變數隱藏了 `/doctor` 診斷螢幕命令 |

434| `DISABLE_FEEDBACK_COMMAND` | 設定為 `1` 以停用 `/feedback` 命令和 [Claude 起草的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。也停用 `/bug` 和 `/share`，它們透過相同路徑報告；在 v2.1.212 之前，它們是 `/feedback` 的別名，因此命令在每個名稱下被停用。較舊的名稱 `DISABLE_BUG_COMMAND` 也被接受 |434| `DISABLE_FEEDBACK_COMMAND` | 設定為 `1` 以停用 `/feedback` 命令和 [Claude 起草的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。也停用 `/bug` 和 `/share`，它們透過相同路徑報告；在 v2.1.212 之前，它們是 `/feedback` 的別名，因此命令在每個名稱下都被停用。較舊的名稱 `DISABLE_BUG_COMMAND` 也被接受 |

435| `DISABLE_GROWTHBOOK` | 設定為 `1` 或 `true` 以停用 GrowthBook 功能旗標擷取並為每個旗標使用程式碼預設值。這使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。將其設定為 `0` 或 `false` 保持擷取開啟。遙測事件日誌記錄保持開啟，除非 `DISABLE_TELEMETRY` 也設定 |435| `DISABLE_GROWTHBOOK` | 設定為 `1` 或 `true` 以停用 GrowthBook 功能旗標擷取並為每個旗標使用程式碼預設值。這使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。將其設定為 `0` 或 `false` 保持擷取開啟。遙測事件日誌保持開啟，除非也設定 `DISABLE_TELEMETRY` |

437| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 設定為 `1` 以隱藏 `/install-github-app` 命令。當使用第三方提供者（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）時已隱藏 |437| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 設定為 `1` 以隱藏 `/install-github-app` 命令。使用第三方提供者（Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）時已隱藏 |

438| `DISABLE_INTERLEAVED_THINKING` | 設定為 `1` 以防止傳送交錯思考測試版標頭。當您的 LLM 閘道或提供者不支援 [交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) 時很有用 |438| `DISABLE_INTERLEAVED_THINKING` | 設定為 `1` 以防止傳送交錯思考測試版標頭。當您的 LLM 閘道或提供者不支援 [交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) 時很有用 |

446| `DISABLE_TELEMETRY` | 設定為任何非空值（例如 `1`）以選擇退出遙測。**將其設定為 `0` 或 `false` 仍會選擇退出**，與大多數開啟/關閉變數不同；取消設定變數以重新開啟遙測。遙測事件不包含使用者資料，如程式碼、檔案路徑或 bash 命令。也停用功能旗標擷取，效果與 `DISABLE_GROWTHBOOK` 相同，這使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。請參閱 [為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |446| `DISABLE_TELEMETRY` | 設定為任何非空值（例如 `1`）以選擇退出遙測。**將其設定為 `0` 或 `false` 仍會選擇退出**，與大多數開啟/關閉變數不同；取消設定變數以重新開啟遙測。遙測事件不包含使用者資料，如程式碼、檔案路徑或 bash 命令。也停用功能旗標擷取，效果與 `DISABLE_GROWTHBOOK` 相同，使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。請參閱 [為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |

447| `DISABLE_UPDATES` | 設定為 `1` 以阻止所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。當透過您自己的頻道分發 Claude Code 且使用者不應自我更新時使用 |447| `DISABLE_UPDATES` | 設定為 `1` 以阻止所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。在透過您自己的通道分發 Claude Code 且使用者不應自行更新時使用 |

449| `DO_NOT_TRACK` | 設定為 `1` 以選擇退出遙測，效果與 `DISABLE_TELEMETRY` 相同，包括使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。Claude Code 將此變數讀作標準布林值，因此 `0` 保持遙測開啟，並尊重許多開發人員 CLI 識別的跨工具慣例 |449| `DO_NOT_TRACK` | 設定為 `1` 以選擇退出遙測，效果與 `DISABLE_TELEMETRY` 相同，包括使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。Claude Code 將此變數讀作標準布林值，因此 `0` 保持遙測開啟，並尊重許多開發人員 CLI 識別的跨工具慣例 |

450| `ENABLE_BETA_TRACING_DETAILED` | 與 `BETA_TRACING_ENDPOINT` 一起設定為 `1`，以開啟 [詳細測試版追蹤](/docs/zh-TW/monitoring-usage#traces-beta)，這新增內容承載跨度屬性和 `claude_code.hook` 跨度。互動 CLI 工作階段也需要您的組織被允許列出測試版。兩個變數在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |450| `ENABLE_BETA_TRACING_DETAILED` | 設定為 `1`，與 `BETA_TRACING_ENDPOINT` 一起，以開啟 [詳細測試版追蹤](/docs/zh-TW/monitoring-usage#traces-beta)，這會新增內容承載跨度屬性和 `claude_code.hook` 跨度。互動 CLI 工作階段也需要您的組織被允許列出測試版。兩個變數在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |

451| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停止 Claude Code 擷取 [claude.ai MCP 伺服器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用。若要按專案或按組織停用，改為在設定中設定 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) |451| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停止 Claude Code 擷取 [claude.ai MCP 伺服器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用。若要按專案或按組織停用，請改設定設定中的 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) |

452| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，而不是預設 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 使用者。訂閱使用者在包含的使用量內在 [主要對話](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets) 上自動接收 1 小時 TTL。訂閱使用者從 [使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 中提取可以設定它以保持 1 小時 TTL。1 小時快取寫入以更高的速率計費。若要按請求桶選擇 TTL，請改用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它們優先於此變數 |452| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，而不是預設 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 使用者。訂閱使用者在包含的使用量內會自動在 [主要對話](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets) 上接收 1 小時 TTL。訂閱使用者從 [使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 中提取可以設定它以保持 1 小時 TTL。1 小時快取寫入以更高的速率計費。若要改為按請求桶選擇 TTL，請使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它們優先於此變數 |

454| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定，Claude Code 預設延遲所有 MCP 工具。它仍在 Google Cloud's Agent Platform 模型上預先載入，早於 Claude 4.5 代，在 Azure 上託管的 Microsoft Foundry 部署上，以及當 `ANTHROPIC_BASE_URL` 指向非第一方主機時。`true` 始終延遲並傳送測試版標頭，除了在這些相同的 Agent Platform 模型和 Microsoft Foundry 部署上；請求在不支援 `tool_reference` 的代理上失敗。`auto` 在工具定義符合上下文的 10% 時預先載入。`auto:N` 設定自訂閾值，例如 5% 的 `auto:5`。`false` 預先載入所有工具。您自己設定的值在設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時被忽略。在 v2.1.221 之前，Claude Code 在 Google Cloud's Agent Platform 上為所有模型停用工具搜尋，除非您將此變數設定為 `true` |454| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定時，Claude Code 預設延遲所有 MCP 工具。它仍在早於 Claude 4.5 代的 Google Cloud 的 Agent Platform 模型上預先載入它們，在 Azure 上託管的 Microsoft Foundry 部署上，以及當 `ANTHROPIC_BASE_URL` 指向非第一方主機時。`true` 始終延遲並傳送測試版標頭，除了在這些相同的 Agent Platform 模型和 Microsoft Foundry 部署上；請求在不支援 `tool_reference` 的代理上失敗。`auto` 在工具定義符合上下文的 10% 時預先載入。`auto:N` 設定自訂閾值，例如 5% 的 `auto:5`。`false` 預先載入所有工具。您自己設定的值在設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時被忽略。在 v2.1.221 之前，Claude Code 停用了 Google Cloud 的 Agent Platform 上所有模型的工具搜尋，除非您將此變數設定為 `true` |

455| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值（例如 `1`），以使 Claude Code 在未配置回退模型時停止在重複過載錯誤上重試每個模型。**將其設定為 `0` 或 `false` 仍會啟用此項**，與大多數開啟/關閉變數不同；取消設定變數以恢復預設重試行為。沒有它，Claude Code 在您使用 API 金鑰或 [第三方提供者](/docs/zh-TW/third-party-integrations) 而不是 Claude 訂閱進行驗證時，停止在 Opus、Fable 或 Mythos 模型上以這種方式重試。在 Claude Code v2.1.160 或更新版本上，Claude Code 在任何主要模型上重複過載錯誤時切換到您配置的 [回退模型鏈](/docs/zh-TW/model-config#fallback-model-chains)，因此此變數不影響切換到回退模型 |455| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值（例如 `1`），以使 Claude Code 在未設定回退模型時停止在重複過載錯誤上重試每個模型。**將其設定為 `0` 或 `false` 仍會啟用此項**，與大多數開啟/關閉變數不同；取消設定變數以恢復預設重試行為。沒有它，Claude Code 在您使用 API 金鑰或 [第三方提供者](/docs/zh-TW/third-party-integrations) 而不是 Claude 訂閱進行驗證時，停止以此方式重試它識別為 Opus、Fable 或 Mythos 模型的重試。在 Claude Code v2.1.160 或更新版本上，Claude Code 在任何主要模型上重複過載錯誤時切換到您配置的 [回退模型鏈](/docs/zh-TW/model-config#fallback-model-chains)，因此此變數不影響切換到回退模型 |

457| `FORCE_HYPERLINK` | 設定為 `1` 以在您的終端支援但未自動偵測時啟用可點擊的 OSC 8 超連結，或設定為 `0` 以停用它們。未設定時，Claude Code 僅在偵測到終端支援時啟用超連結。Claude Code 將此值解析為數字，而不是布林值，因此 `false`、`no` 或 `off` 之類的值啟用超連結，而不是停用它們。頁腳 [PR 或合併請求徽章](/docs/zh-TW/interactive-mode#pr-review-status) 即使在 Claude Code 無法偵測終端支援時（例如透過 SSH）也呈現為超連結。設定 `0` 以呈現徽章為純文字 |457| `FORCE_HYPERLINK` | 設定為 `1` 以在您的終端支援但未自動偵測時啟用可點擊的 OSC 8 超連結，或設定為 `0` 以停用它們。未設定時，Claude Code 僅在偵測到終端支援時啟用超連結。Claude Code 將此值解析為數字，而不是布林值，因此 `false`、`no` 或 `off` 之類的值啟用超連結，而不是停用它們。頁腳 [PR 或合併請求徽章](/docs/zh-TW/interactive-mode#pr-review-status) 即使 Claude Code 無法偵測終端支援（例如透過 SSH）也呈現為超連結。設定 `0` 以將徽章呈現為純文字 |

458| `FORCE_PROMPT_CACHING_5M` | 設定為 `1` 以強制 5 分鐘提示快取 TTL，即使 1 小時 TTL 會否則適用。覆蓋 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H` 和 `promptCacheTtl` 和 `subagentPromptCacheTtl` 設定 |458| `FORCE_PROMPT_CACHING_5M` | 設定為 `1` 以強制 5 分鐘提示快取 TTL，即使 1 小時 TTL 會否則適用。覆蓋 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H` 和 `promptCacheTtl` 和 `subagentPromptCacheTtl` 設定 |

461| `IS_DEMO` | 設定為任何非空值（例如 `1`）以啟用演示模式：從標頭和 `/status` 輸出隱藏您的電子郵件和組織名稱，並跳過入門。**將其設定為 `0` 或 `false` 仍會啟用演示模式**，與大多數開啟/關閉變數不同；取消設定變數以關閉它。在串流或錄製工作階段時很有用 |461| `IS_DEMO` | 設定為任何非空值（例如 `1`）以啟用演示模式：從標頭和 `/status` 輸出隱藏您的電子郵件和組織名稱，並跳過入門。**將其設定為 `0` 或 `false` 仍會啟用演示模式**，與大多數開啟/關閉變數不同；取消設定變數以關閉它。在串流或錄製工作階段時很有用 |

462| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大權杖數。Claude Code 在輸出超過 10,000 權杖時顯示警告。聲明 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具改為對文字內容使用該字元限制，但來自這些工具的影像內容仍受此變數約束（預設：25000） |462| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大權杖數。Claude Code 在輸出超過 10,000 權杖時顯示警告。宣告 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具改為使用該字元限制用於文字內容，但來自這些工具的影像內容仍受此變數限制（預設：25000） |

463| `MAX_STRUCTURED_OUTPUT_RETRIES` | 當模型的回應無法驗證 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 時，Claude Code 在非互動模式下使用 `-p` 旗標允許的嘗試次數；在那麼多次失敗嘗試後沒有有效輸出，執行失敗。當 [工作流程](/docs/zh-TW/workflows) 子代理的結構化輸出無法驗證時，相同的上限適用。預設為 5，第一次嘗試加四次重試 |463| `MAX_STRUCTURED_OUTPUT_RETRIES` | 當模型的回應無法針對非互動模式中的 `-p` 旗標的 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 驗證時，Claude Code 允許的嘗試次數；在那麼多次失敗的嘗試後沒有有效輸出，執行失敗。當 [工作流](/docs/zh-TW/workflows) 子代理的結構化輸出無法驗證時，相同的上限適用。預設為 5，第一次嘗試加四次重試 |

464| `MAX_THINKING_TOKENS` | [擴展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 的固定權杖預算。Claude Code 將其上限設定為請求最大輸出權杖下方一個權杖，永遠不低於 1,024。請參閱 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 以了解該限制如何設定。未設定且思考啟用時，具有 [自適應推理](/docs/zh-TW/model-config#adjust-effort-level) 的模型選擇自己的思考深度，其他模型使用上限。設定為 `0` 以在 Anthropic API 上停用思考，但 Opus 5.5 和 Fable 模型除外，這些模型無法關閉思考。在 [第三方提供者](/docs/zh-TW/third-party-integrations) 上，`0` 改為省略 `thinking` 參數。在 Anthropic API 上關閉思考時，Claude Code 向它知道 [不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off) 的模型（例如 Opus 5）傳送 effort `high` 而不是更高級別。Claude Code 在自適應推理模型上忽略非零值，除了 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 關閉自適應推理的模型 |464| `MAX_THINKING_TOKENS` | [擴充思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 的固定權杖預算。Claude Code 將其上限設為請求最大輸出權杖下方一個權杖，絕不低於 1,024。請參閱 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 以了解該限制如何設定。未設定時，具有 [自適應推理](/docs/zh-TW/model-config#adjust-effort-level) 的模型選擇自己的思考深度，其他模型使用上限。設定為 `0` 以在 Anthropic API 上停用思考，除了 Opus 5.5 和 Fable 模型，它們無法關閉思考。在 [第三方提供者](/docs/zh-TW/third-party-integrations) 上，`0` 改為省略 `thinking` 參數。在 Anthropic API 上關閉思考時，Claude Code 改為傳送 effort `high` 到它知道 [不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off) 的模型，例如 Opus 5。Claude Code 在自適應推理模型上忽略非零值，除了 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 關閉自適應推理的模型 |

465| `MCP_CLIENT_SECRET` | 需要 [預先配置認證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials) 的 MCP 伺服器的 OAuth 用戶端機密。在使用 `--client-secret` 新增伺服器時避免互動提示 |465| `MCP_CLIENT_SECRET` | 需要 [預先配置認證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials) 的 MCP 伺服器的 OAuth 用戶端機密。在使用 `--client-secret` 新增伺服器時避免互動提示 |

466| `MCP_CONNECTION_NONBLOCKING` | 控制啟動是否在第一個查詢前等待 MCP 伺服器連線。MCP 啟動預設非阻塞：伺服器在背景連線，其工具在完成時變為可用。設定為 `0` 以使 Claude Code 在第一個查詢前等待伺服器連線。配置 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器仍使啟動等待，除非從 [發現快取](/docs/zh-TW/mcp#server-status-detail) 提供，因為它們的工具必須在建立第一個提示時存在。在非互動模式 (`-p`) 中，Claude Code 也在第一個轉前等待仍待處理的伺服器，無論此變數如何，當您明確傳遞 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時有更長的期限；請參閱該旗標的項目以了解快取伺服器例外 |466| `MCP_CONNECTION_NONBLOCKING` | 控制啟動是否在第一個查詢前等待 MCP 伺服器連線。MCP 啟動預設非阻塞：伺服器在背景連線，其工具在完成時變為可用。設定為 `0` 以使 Claude Code 在第一個查詢前等待伺服器連線。配置 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器仍會使啟動等待，除非從 [探索快取](/docs/zh-TW/mcp#server-status-detail) 提供，因為它們的工具必須在建立第一個提示時存在。在非互動模式 (`-p`) 中沒有 `--input-format stream-json`，Claude Code 也會在第一個轉向前等待仍待處理的伺服器，無論此變數如何。當您明確傳遞 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時，等待有更長的期限；請參閱該旗標的項目以了解快取伺服器例外 |

467| `MCP_CONNECT_TIMEOUT_MS` | 阻塞 MCP 啟動在快照工具清單前等待連線批次的時間（毫秒）（預設：5000）。當 `MCP_CONNECTION_NONBLOCKING=0` 或伺服器標記 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 時適用。仍待處理的伺服器在期限後繼續在背景連線 |467| `MCP_CONNECT_TIMEOUT_MS` | 阻塞 MCP 啟動等待連線批次的時間（毫秒），然後才拍攝工具清單快照（預設：5000）。當 `MCP_CONNECTION_NONBLOCKING=0` 或伺服器標記 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 時適用。仍待處理的伺服器在期限處繼續在背景連線。與 `MCP_TIMEOUT` 不同，後者界限個別伺服器的連線嘗試 |

468| `MCP_DISCOVERY_CACHE` | 開啟或關閉 [MCP 發現快取](/docs/zh-TW/mcp#server-status-detail)。快取開啟時，您之前使用過的遠端 HTTP 或 SSE 伺服器可以顯示 [`cached` 狀態](/docs/zh-TW/mcp#server-status-detail)，Claude Code 在其第一個工具呼叫時連線它，而不是在啟動時。快取預設關閉，除非逐步推出已為您的帳戶啟用它。設定為 `1` 以開啟它，或設定為 `0` 以保持關閉，即使推出已啟用它。在 v2.1.238 之前，快取預設開啟。`cached` 狀態需要 Claude Code v2.1.221 或更新版本 |468| `MCP_DISCOVERY_CACHE` | 開啟或關閉 [MCP 探索快取](/docs/zh-TW/mcp#server-status-detail)。快取開啟時，您之前使用過的遠端 HTTP 或 SSE 伺服器可以顯示 [`cached` 狀態](/docs/zh-TW/mcp#server-status-detail)，Claude Code 在其第一個工具呼叫時連線它，而不是在啟動時。快取預設關閉，除非漸進式推出已為您的帳戶啟用它。設定為 `1` 以開啟它，或設定為 `0` 以保持關閉，即使推出已啟用它。在 v2.1.238 之前，快取預設開啟。`cached` 狀態需要 Claude Code v2.1.221 或更新版本 |

469| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [發現快取](/docs/zh-TW/mcp#server-status-detail) 項目的最大年齡（秒）（預設：14400，或 4 小時）。在項目比該年齡更舊的啟動時，Claude Code 丟棄它並在啟動時連線伺服器，如同快取關閉一樣。Claude Code 將值上限為 7 天。在 v2.1.238 之前，預設為 86400，或 24 小時，Claude Code 未上限值 |469| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [探索快取](/docs/zh-TW/mcp#server-status-detail) 項目的最大年齡（秒）（預設：14400 或 4 小時）。在項目比該年齡更舊的啟動時，Claude Code 會丟棄它並在啟動時連線伺服器，如同快取關閉一樣。Claude Code 將值上限為 7 天。在 v2.1.238 之前，預設為 86400 或 24 小時，Claude Code 未上限值 |

470| `MCP_DISCOVERY_CACHE_STRIKES` | 在 [發現快取](/docs/zh-TW/mcp#server-status-detail) 項目比 `MCP_DISCOVERY_CACHE_TTL_S` 更舊的啟動時，Claude Code 在背景刷新它。此變數設定在 Claude Code 丟棄項目並在下一次啟動時連線伺服器前，刷新可以連續失敗多少次（預設：1）。如果您的網路連線偶爾掉線，請提高它，以便一次失敗的刷新不會丟棄項目。需要 Claude Code v2.1.238 或更新版本 |470| `MCP_DISCOVERY_CACHE_STRIKES` | 在 [探索快取](/docs/zh-TW/mcp#server-status-detail) 項目比 `MCP_DISCOVERY_CACHE_TTL_S` 更舊的啟動時，Claude Code 在背景重新整理它。此變數設定在 Claude Code 丟棄項目並在下一次啟動時連線伺服器之前，連續重新整理可以失敗多少次（預設：1）。如果您的網路連線偶爾掉線，請提高它，以便一次失敗的重新整理不會丟棄項目。需要 Claude Code v2.1.238 或更新版本 |

471| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用 [發現快取](/docs/zh-TW/mcp#server-status-detail) 項目而不刷新它的秒數（預設：900）。在項目比該年齡更舊的啟動時，Claude Code 仍使用它但在背景刷新它。一旦項目比 `MCP_DISCOVERY_CACHE_MAX_STALE_S` 更舊，Claude Code 改為丟棄它。Claude Code 將值上限為 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，預設為 4 小時。在 v2.1.238 之前，Claude Code 未上限值 |471| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用 [探索快取](/docs/zh-TW/mcp#server-status-detail) 項目而不重新整理的秒數（預設：900）。在項目比該年齡更舊的啟動時，Claude Code 仍然使用它但在背景重新整理它。一旦項目比 `MCP_DISCOVERY_CACHE_MAX_STALE_S` 更舊，Claude Code 改為丟棄它。Claude Code 將值上限為 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，預設為 4 小時。在 v2.1.238 之前，Claude Code 未上限值 |

472| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定埠，作為使用 [預先配置認證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials) 新增 MCP 伺服器時 `--callback-port` 的替代方案 |472| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定埠，作為使用 [預先配置認證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials) 新增 MCP 伺服器時 `--callback-port` 的替代方案 |

473| `MCP_PROTOCOL_NEGOTIATION` | 在 [v2 MCP 用戶端執行時](/docs/zh-TW/mcp#mcp-client-runtimes) 上，Claude Code 是否探測伺服器以了解 MCP 協議修訂 2026-07-28。設定 `auto` 以探測 HTTP、claude.ai 連接器和 stdio 伺服器；不回答探測的伺服器在較早的協議上連線，SSE 和 WebSocket 伺服器始終這樣做。設定 `legacy` 以跳過每個伺服器的探測。沒有變數，Claude Code 探測 HTTP 伺服器，並且在其 [擷取功能旗標](#features-that-need-feature-flag-fetching) 的工作階段中也探測 claude.ai 連接器伺服器。任何其他值被忽略，並在偵錯日誌中出現警告。需要 Claude Code v2.1.221 或更新版本 |473| `MCP_PROTOCOL_NEGOTIATION` | 在 [v2 MCP 用戶端執行時](/docs/zh-TW/mcp#mcp-client-runtimes) 上，Claude Code 是否探測伺服器以了解 MCP 協議修訂 2026-07-28。設定 `auto` 以探測 HTTP、claude.ai 連接器和 stdio 伺服器；不回答探測的伺服器在較早的協議上連線，SSE 和 WebSocket 伺服器始終這樣做。設定 `legacy` 以跳過每個伺服器的探測。沒有變數，Claude Code 探測 HTTP 伺服器，也在 [擷取功能旗標](#features-that-need-feature-flag-fetching) 的工作階段中探測 claude.ai 連接器伺服器。任何其他值都被忽略並在偵錯日誌中出現警告。需要 Claude Code v2.1.221 或更新版本 |

475| `MCP_SDK_GENERATION` | 釘選此程序連線 MCP 伺服器的 [MCP 用戶端執行時](/docs/zh-TW/mcp#mcp-client-runtimes)：`v1`，建立在 MCP TypeScript SDK 1.x 上，或 `v2`，建立在 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 上。沒有變數，Claude Code 使用 v2，從該部分列出的版本開始。在 Claude Code v2.1.221 或更新版本上，v2 執行時檢查 MCP OAuth 伺服器在其授權回應中返回的簽發者，並在不符合時失敗登入，並出現以 `Issuer mismatch in authorization response` 開頭的錯誤。v1 執行時不執行此檢查。如果您設定無法識別的值，Claude Code 會忽略它並在偵錯日誌中寫入警告。Claude Code 每個程序讀取值一次。需要 Claude Code v2.1.218 或更新版本 |475| `MCP_SDK_GENERATION` | 釘選此程序連線 MCP 伺服器的 [MCP 用戶端執行時](/docs/zh-TW/mcp#mcp-client-runtimes)：`v1`，建立在 MCP TypeScript SDK 1.x 上，或 `v2`，建立在 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 上。沒有變數，Claude Code 使用 v2，從該部分列出的版本開始。在 Claude Code v2.1.221 或更新版本上，v2 執行時檢查 MCP OAuth 伺服器在其授權回應中傳回的簽發者，並在不符合時失敗登入，錯誤以 `Issuer mismatch in authorization response` 開頭。v1 執行時不執行此檢查。如果您設定無法識別的值，Claude Code 會忽略它並在偵錯日誌中寫入警告。Claude Code 每個程序讀取值一次。需要 Claude Code v2.1.218 或更新版本 |

478| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（毫秒）（預設：100000000，約 28 小時）。對於 HTTP、SSE 或 claude.ai 連接器伺服器，每個請求也預設在 60 秒後逾時；將此變數或每個伺服器 `timeout` 設定為 60000 以上以提高該每個請求限制。較低的值仍會縮短整體工具執行逾時，但保持每個請求限制為 60 秒。Stdio 和 WebSocket 伺服器沒有每個請求計時器。`.mcp.json` 中的每個伺服器 `timeout` 欄位覆蓋此項用於該伺服器。至少 1000 的每個伺服器 `timeout` 也為該伺服器的工具呼叫設定最小閒置視窗，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 永遠不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於 env 變數，低於 1000 的值下限為一秒；對於每個伺服器欄位，低於 1000 的值被忽略 |478| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（毫秒）（預設：100000000，約 28 小時）。對於 HTTP、SSE 或 claude.ai 連接器伺服器，每個請求也預設在 60 秒後逾時；設定此變數或每個伺服器 `timeout` 高於 60000 以提高該每個請求限制。較低的值仍會縮短整體工具執行逾時，但保持每個請求限制在 60 秒。Stdio 和 WebSocket 伺服器沒有每個請求計時器。`.mcp.json` 中的每個伺服器 `timeout` 欄位覆蓋此項用於該伺服器。至少 1000 的每個伺服器 `timeout` 也為該伺服器的工具呼叫設定最小閒置視窗，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 絕不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於 env 變數，低於 1000 的值下限為一秒；對於每個伺服器欄位，低於 1000 的值被忽略 |

480| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 標準 OpenTelemetry SDK 屬性值長度限制。Claude Code 將內容承載遙測屬性上限為此和 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中的較小者，因此截斷標記保持在 SDK 限制內。Claude Code 以相同方式讀取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 變體，最小設定值適用於所有信號。需要 Claude Code v2.1.214 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage#common-configuration-variables) |480| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 標準 OpenTelemetry SDK 屬性值長度限制。Claude Code 將內容承載遙測屬性上限為此和 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中的較小值，因此截斷標記保持在 SDK 限制內。Claude Code 以相同方式讀取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 變體，最小設定值適用於所有信號。需要 Claude Code v2.1.214 或更新版本。請參閱 [監視](/docs/zh-TW/monitoring-usage#common-configuration-variables) |

481| `OTEL_LOG_ASSISTANT_RESPONSES` | 設定為 `1` 以在 `assistant_response` OpenTelemetry 日誌事件上包含模型的回應文字。未設定時，使用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 以保持回應被編輯，即使 `OTEL_LOG_USER_PROMPTS` 設定。需要 Claude Code v2.1.193 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage#assistant-response-event) |481| `OTEL_LOG_ASSISTANT_RESPONSES` | 設定為 `1` 以在 `assistant_response` OpenTelemetry 日誌事件上包含模型的回應文字。未設定時，Claude Code 改為使用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 以保持回應被編輯，即使設定 `OTEL_LOG_USER_PROMPTS`。在您的 shell、使用者設定或受管設定中設定。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略。需要 Claude Code v2.1.193 或更新版本。請參閱 [監視](/docs/zh-TW/monitoring-usage#assistant-response-event) |

482| `OTEL_LOG_MANAGED_SETTINGS` | 設定為 `1` 以新增編輯的受管設定和設定前編輯的 SHA-256 摘要到 `managed_settings_resolved` OpenTelemetry 日誌事件。預設停用。在您的 shell、使用者設定或受管設定中設定它；專案或本機設定中的值不會開啟它。需要 Claude Code v2.1.274 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage#managed-settings-resolved-event) |482| `OTEL_LOG_MANAGED_SETTINGS` | 設定為 `1` 以將編輯的受管設定和編輯前設定的 SHA-256 摘要新增至 `managed_settings_resolved` OpenTelemetry 日誌事件。預設停用。在您的 shell、使用者設定或受管設定中設定；專案或本機設定中的值不會開啟它。需要 Claude Code v2.1.274 或更新版本。請參閱 [監視](/docs/zh-TW/monitoring-usage#managed-settings-resolved-event) |

483| `OTEL_LOG_RAW_API_BODIES` | 發出 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件。設定為 `1` 用於在內容限制處截斷的內聯主體，或 `file:<dir>` 以將未截斷的主體寫入磁碟並改為發出 `body_ref` 路徑。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 配置內容限制，預設 60 KB。預設停用；主體包含整個對話歷史記錄。在您的 shell、使用者設定或受管設定中設定它。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中被忽略。請參閱 [監控](/docs/zh-TW/monitoring-usage#api-request-body-event) |483| `OTEL_LOG_RAW_API_BODIES` | 發出 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件。設定為 `1` 用於在內容限制處截斷的內聯主體，或設定為 `file:<dir>` 以將未截斷的主體寫入磁碟並改為發出 `body_ref` 路徑。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 設定內容限制，預設 60 KB。預設停用；主體包含整個對話歷史記錄。在您的 shell、使用者設定或受管設定中設定。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略。請參閱 [監視](/docs/zh-TW/monitoring-usage#api-request-body-event) |

484| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 以在 `tool.output` OpenTelemetry 跨度事件中包含工具內容。跨度屬性在 [自己的門下](/docs/zh-TW/monitoring-usage#new-context-gates) 攜帶工具內容。需要 [追蹤](/docs/zh-TW/monitoring-usage#traces-beta)。預設停用以保護敏感資料。請參閱 [監控](/docs/zh-TW/monitoring-usage#tool-output-span-event) |484| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 以在 `tool.output` OpenTelemetry 跨度事件上包含工具內容。跨度屬性在 [自己的門](/docs/zh-TW/monitoring-usage#new-context-gates) 下攜帶工具內容。需要 [追蹤](/docs/zh-TW/monitoring-usage#traces-beta)。預設停用以保護敏感資料。在您的 shell、使用者設定或受管設定中設定。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略，除了該部分描述的關閉值。請參閱 [監視](/docs/zh-TW/monitoring-usage#tool-output-span-event) |

485| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含工具輸入引數、MCP 伺服器名稱、使用者撰寫的工作流程名稱、工具失敗上的原始錯誤字串、`api_refusal` 事件上的拒絕 `category` 和其他工具詳細資訊。預設停用以保護 PII。請參閱 [監控](/docs/zh-TW/monitoring-usage) |485| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含工具輸入引數、MCP 伺服器名稱、使用者撰寫的工作流名稱、工具失敗上的原始錯誤字串、`api_refusal` 事件上的拒絕 `category` 和其他工具詳細資訊。預設停用以保護 PII。在您的 shell、使用者設定或受管設定中設定。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略，除了該部分描述的關閉值。請參閱 [監視](/docs/zh-TW/monitoring-usage) |

486| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含使用者提示文字。預設停用（提示被編輯）。請參閱 [監控](/docs/zh-TW/monitoring-usage) |486| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含使用者提示文字。預設停用（提示被編輯）。在您的 shell、使用者設定或受管設定中設定。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略，除了該部分描述的關閉值。請參閱 [監視](/docs/zh-TW/monitoring-usage) |

488| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設定為 `true` 以在指標屬性中包含工作階段進入點（預設：排除）。在 v2.1.152 中新增。請參閱 [監控](/docs/zh-TW/monitoring-usage) |488| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設定為 `true` 以在指標屬性中包含工作階段進入點（預設：排除）。在 v2.1.152 中新增。請參閱 [監視](/docs/zh-TW/monitoring-usage) |

489| `OTEL_METRICS_INCLUDE_REPOSITORY` | 設定為 `true` 以使用識別工作階段儲存庫的 `vcs.*` 屬性標記 OpenTelemetry 指標和事件（預設：排除）。需要 Claude Code v2.1.269 或更新版本。請參閱 [儲存庫屬性](/docs/zh-TW/monitoring-usage#repository-attributes) |489| `OTEL_METRICS_INCLUDE_REPOSITORY` | 設定為 `true` 以使用識別工作階段儲存庫的 `vcs.*` 屬性標記 OpenTelemetry 指標和事件（預設：排除）。需要 Claude Code v2.1.269 或更新版本。請參閱 [儲存庫屬性](/docs/zh-TW/monitoring-usage#repository-attributes) |

490| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 自 v2.1.161 起，Claude Code 將 `OTEL_RESOURCE_ATTRIBUTES` 金鑰附加到指標資料點標籤。設定為 `false` 以排除它們（預設：包含）。請參閱 [監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |490| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 從 v2.1.161 開始，Claude Code 將 `OTEL_RESOURCE_ATTRIBUTES` 金鑰附加到指標資料點標籤。設定為 `false` 以排除它們（預設：包含）。請參閱 [監視](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |

493| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆蓋 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill) 顯示的 skill 中繼資料的字元預算。預算在上下文視窗的 1% 處動態縮放，回退為 8,000 字元。為向後相容性保留的舊名稱 |493| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆蓋 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill) 顯示的技能中繼資料的字元預算。預算在上下文視窗的 1% 處動態縮放，回退為 8,000 字元。為了向後相容性保留舊名稱 |

494| `TASK_MAX_OUTPUT_LENGTH` | 在 v2.1.277 中移除，現在是無操作，與它調整大小的 `TaskOutput` 工具一起。以前設定 [背景工作](/docs/zh-TW/tools-reference#background-commands) 輸出的最大字元數，`TaskOutput` 工具保持。Claude 改為使用 `Read` 讀取背景工作的輸出檔案 |494| `TASK_MAX_OUTPUT_LENGTH` | 在 v2.1.277 中移除，現在是無操作，與它調整大小的 `TaskOutput` 工具一起。先前設定 [背景工作](/docs/zh-TW/tools-reference#background-commands) 輸出的最大字元數，`TaskOutput` 工具保留。Claude 改為使用 `Read` 讀取背景工作的輸出檔案 |

~~514~~ 514

515標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信號特定變體）也被支援。請參閱 [監控](/docs/zh-TW/monitoring-usage) 以了解配置詳細資訊。515標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信號特定變體）也受支援。請參閱 [監視](/docs/zh-TW/monitoring-usage) 以了解設定詳細資訊。

516

517在您的 shell、使用者設定或受管設定中設定 `CLAUDE_CODE_ENABLE_TELEMETRY` 和開啟匯出、選擇其目的地或在 OpenTelemetry 變數中擷取內容。Claude Code [在專案和本機設定中忽略它們](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)，除了該部分描述的關閉值。`OTEL_RESOURCE_ATTRIBUTES` 和匯出間隔、逾時和壓縮變數（例如 `OTEL_METRIC_EXPORT_INTERVAL`）仍從專案和本機設定適用。

516 518

517<h2 id="features-that-need-feature-flag-fetching">519<h2 id="features-that-need-feature-flag-fetching">

518 需要功能旗標擷取的功能520 需要功能旗標擷取的功能

533* [訊息工作階段超越此機器](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)；此機器上工作階段之間的訊息傳遞在擷取關閉時可運作535* [訊息工作階段超越此機器](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)；此機器上工作階段之間的訊息傳遞在擷取關閉時可運作

534* 執行 [`claude import` 或 `/import` 命令](/docs/zh-TW/cli-reference#cli-commands)536* 執行 [`claude import` 或 `/import` 命令](/docs/zh-TW/cli-reference#cli-commands)

535* 執行 [`/skill-doctor`](/docs/zh-TW/skills#find-unused-skills) 或在 `/plugin` **Stats** 標籤中開啟其報告537* 執行 [`/skill-doctor`](/docs/zh-TW/skills#find-unused-skills) 或在 `/plugin` **Stats** 標籤中開啟其報告

536* 同步為您的 claude.ai 帳戶啟用的[技能](/docs/zh-TW/skills#where-synced-skills-load)和[外掛程式](/docs/zh-TW/plugins-reference#synced-plugins)到您的終端工作階段538* 同步為您的 claude.ai 帳戶啟用的[技能](/docs/zh-TW/skills#where-synced-skills-load)和[外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)到您的終端工作階段

537* 使用[顧問工具](/docs/zh-TW/advisor#requirements)539* 使用[顧問工具](/docs/zh-TW/advisor#requirements)

538* 讀取或回覆[成品上的評論](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)540* 讀取或回覆[成品上的評論](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)

539* 讓 Claude Code 探測 claude.ai 連接器伺服器以取得 [MCP 協定修訂版本 2026-07-28](/docs/zh-TW/mcp#mcp-client-runtimes)，除非您設定 `MCP_PROTOCOL_NEGOTIATION=auto`541* 讓 Claude Code 探測 claude.ai 連接器伺服器以取得 [MCP 協定修訂版本 2026-07-28](/docs/zh-TW/mcp#mcp-client-runtimes)，除非您設定 `MCP_PROTOCOL_NEGOTIATION=auto`

errors.md +144 −15

Details

36| `Auto mode could not evaluate this action and is blocking it for safety` | [伺服器錯誤](#auto-mode-cannot-determine-the-safety-of-an-action) |36| `Auto mode could not evaluate this action and is blocking it for safety` | [伺服器錯誤](#auto-mode-cannot-determine-the-safety-of-an-action) |

38| `Agent aborted: auto mode classifier request refused by the safety safeguard` | [伺服器錯誤](#auto-mode-cannot-determine-the-safety-of-an-action) |38| `Agent aborted: auto mode classifier request refused by the safety safeguard` | [伺服器錯誤](#auto-mode-cannot-determine-the-safety-of-an-action) |

39| `The server-side auto mode classifier gave no verdict` | [伺服器錯誤](#the-server-returned-no-safety-verdict) |

40| `Auto mode is unavailable — the server returned no safety verdict for the last 10 responses` | [伺服器錯誤](#the-server-returned-no-safety-verdict) |

40| `You've hit your session limit` / `You've hit your weekly limit` / `You've hit your Opus limit` / `You've hit your Sonnet limit` | [使用限制](#youve-hit-your-session-limit) |42| `You've hit your session limit` / `You've hit your weekly limit` / `You've hit your Opus limit` / `You've hit your Sonnet limit` | [使用限制](#youve-hit-your-session-limit) |

159| `role 'system' must precede an 'assistant' message` | [請求錯誤](#role-system-must-precede-an-assistant-message) |

160| `Invalid encrypted_content in search_result block` / `Invalid encrypted_index in text block` / `Failed to decrypt web search result content` | [請求錯誤](#invalid-encrypted-content-in-search-result-block) |

159| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [請求錯誤](#usage-policy-refusal) |163| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [請求錯誤](#usage-policy-refusal) |

173| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [命令列錯誤](#the-current-directory-no-longer-exists) |177| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [命令列錯誤](#the-current-directory-no-longer-exists) |

178| `Temp directory <dir> ... Refusing to use it` / `ENOSPC: no space left on device, mkdir '<dir>'` | [命令列錯誤](#temp-directory-refused-or-cannot-be-created) |

174| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [命令列錯誤](#directory-couldnt-be-resolved-to-a-real-location) |179| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [命令列錯誤](#directory-couldnt-be-resolved-to-a-real-location) |

175| `Error: Workspace not trusted` when starting Remote Control | [命令列錯誤](#workspace-not-trusted-when-starting-remote-control) |180| `Error: Workspace not trusted` when starting Remote Control | [命令列錯誤](#workspace-not-trusted-when-starting-remote-control) |

176| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [命令列錯誤](#not-carried-over-to-the-sessions-remote-control-starts) |181| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [命令列錯誤](#not-carried-over-to-the-sessions-remote-control-starts) |

214| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [Plugin 錯誤](#plugin-eval-is-currently-in-early-access) |219| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [Plugin 錯誤](#plugin-eval-is-currently-in-early-access) |

215| `Marketplace "<name>" is registered from an untrusted source` | [Plugin 錯誤](#marketplace-is-registered-from-an-untrusted-source) |220| `Marketplace "<name>" is registered from an untrusted source` | [Plugin 錯誤](#marketplace-is-registered-from-an-untrusted-source) |

216| `Marketplace "<name>" is already added from a different source` | [Plugin 錯誤](#marketplace-is-already-added-from-a-different-source) |221| `Marketplace "<name>" is already added from a different source` | [Plugin 錯誤](#marketplace-is-already-added-from-a-different-source) |

222| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [Plugin 錯誤](#marketplace-name-is-another-spelling-of-a-reserved-name) |

217| `references ${user_config.*} in a shell-form command` | [Plugin 錯誤](#plugin-command-references-user-config) |223| `references ${user_config.*} in a shell-form command` | [Plugin 錯誤](#plugin-command-references-user-config) |

218| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [Plugin 錯誤](#plugin-command-references-user-config) |224| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [Plugin 錯誤](#plugin-command-references-user-config) |

219| `headersHelper for MCP server '<name>' references ${user_config.*}` | [Plugin 錯誤](#plugin-command-references-user-config) |225| `headersHelper for MCP server '<name>' references ${user_config.*}` | [Plugin 錯誤](#plugin-command-references-user-config) |

566* 在互動式工作階段中，在出現的提示中批准或拒絕該動作572* 在互動式工作階段中，在出現的提示中批准或拒絕該動作

567* 在互動式工作階段中，執行 `/compact` 以減少對話大小，以便後續動作再次適應分類器視窗573* 在互動式工作階段中，執行 `/compact` 以減少對話大小，以便後續動作再次適應分類器視窗

568 574

575<h3 id="the-server-returned-no-safety-verdict">

576 The server returned no safety verdict

577</h3>

578

579在[伺服器端分類器審查](/docs/zh-TW/permission-modes#server-side-classifier-review)下，當伺服器沒有給出判決時，auto mode 會拒絕一個動作。拒絕會在 Claude Code 可以判斷一個類別時在括號中名稱該類別，例如 `(timed out)`：

580

581```text theme={null}

582The server-side auto mode classifier gave no verdict (timed out), so auto mode cannot determine the safety of <tool>.

583```

584

585訊息的其餘部分告訴 Claude 一次重試是否可以幫助。在某些這些拒絕之前，Claude Code 會等待，以便 Claude 的下一次嘗試不會立即跟隨。在互動式工作階段中等待期間，微調器顯示 `Auto mode check unavailable` 並帶有倒計時，按 `Esc` 會中斷該輪次。

586

587在連續十個回應都沒有判決後，auto mode 會停止該輪次：

588

589```text theme={null}

590Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.

591```

592

593停止訊息在每種工作階段中出現在不同的位置：

594

595* 在互動式工作階段中，訊息作為警告出現在記錄中，輪次結束

596* 在[非互動式](/docs/zh-TW/headless) `-p` 執行中，執行結束並報告執行錯誤。使用預設文字輸出，訊息在 stderr 上列印

597* 當[子代理](/docs/zh-TW/sub-agents)達到限制時，子代理在完成之前停止，Claude 會收到它產生的任何內容，並附帶 auto mode 停止它的說明

598

599**該怎麼做：**

600

601* 傳送另一條訊息以讓 Claude 再試一次。回應計數重新開始。

602* 如果停止重複且您的請求通過[LLM 閘道或代理](/docs/zh-TW/llm-gateway)，檢查它是否縮短串流回應或重寫它們。[伺服器端分類器審查](/docs/zh-TW/permission-modes#server-side-classifier-review)說明哪個閘道行為會導致拒絕，[閘道相容性指南](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)列出要保持不變的內容。

603* 在啟動 Claude Code 之前設定 `CLAUDE_CODE_AUTO_MODE_SERVER=0` 以改用其自己的分類器請求。在 v2.1.281 之前，Claude Code 在直接連線到 Anthropic API 時不讀取該變數。

604* 要自己批准動作，請改為[切換出 auto mode](/docs/zh-TW/permission-modes#switch-permission-modes)

605

606在 v2.1.280 之前，Claude Code 立即拒絕來自沒有判決的回應的每個動作，從不停止該輪次。

607

569<h3 id="agent-terminated-early-due-to-an-api-error">608<h3 id="agent-terminated-early-due-to-an-api-error">

570 Agent terminated early due to an API error609 Agent terminated early due to an API error

571</h3>610</h3>

2391* 當您看到佔位符行時，無需執行任何操作。工作階段在沒有移除內容的情況下繼續。2430* 當您看到佔位符行時，無需執行任何操作。工作階段在沒有移除內容的情況下繼續。

2392* 如果已恢復工作階段的每輪都失敗，出現 400 錯誤，請執行 `claude update` 並再次恢復工作階段。v2.1.246 之前的版本不會移除內容。2431* 如果已恢復工作階段的每輪都失敗，出現 400 錯誤，請執行 `claude update` 並再次恢復工作階段。v2.1.246 之前的版本不會移除內容。

2393 2432

2433<h3 id="role-system-must-precede-an-assistant-message">

2434 role 'system' 必須在 'assistant' 訊息之前

2435</h3>

2436

2437API 因為系統訊息位於它不接受的對話位置而拒絕了請求，出現 400：

2438

2439```text theme={null}

2440API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...

2441```

2442

2443Claude Code 將其某些提醒和附加文字作為系統訊息發送到對話中。當 API 拒絕其位置時，Claude Code 會重試請求一次，將該文字作為普通使用者訊息發送。API 的同級位置措辭，例如 `use the top-level 'system' parameter for the initial system prompt`，會得到相同的恢復。

2444

2445當錯誤確實出現時，被拒絕的系統訊息不是 Claude Code 可以移除的。這通常意味著 Claude Code 和 API 之間的代理或 [LLM gateway](/docs/zh-TW/llm-gateway) 添加了自己的系統訊息或重新排序了對話。

2446

2447**該怎麼辦：**

2448

2449* 執行 `/clear` 以開始新的對話。如果錯誤也在那裡返回，原因在於請求路徑上，而不是在已保存的對話中。

2450* 如果錯誤在通過 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 配置的代理或閘道後面重複出現，請連接而不使用代理以確認來源，並向操作它的人報告錯誤

2451

2452在 v2.1.280 之前，Claude Code 沒有識別此措辭，因此當被拒絕的系統訊息是 Claude Code 本身發送的時，錯誤也會出現，對話的每個後續輪次都失敗了相同的方式。

2453

2454<h3 id="invalid-encrypted-content-in-search-result-block">

2455 搜尋結果區塊中的無效 encrypted\_content

2456</h3>

2457

2458API 因為對話歷史記錄包含它無法解密的託管網路搜尋內容而拒絕了請求，出現 400。措辭命名它無法讀取的欄位：

2459

2460```text theme={null}

2461API Error: 400 messages.21.content.0: Invalid `encrypted_content` in `search_result` block

2462API Error: 400 messages.21.content.3.citations.0: Invalid `encrypted_index` in `text` block

2463API Error: 400 Failed to decrypt web search result content

2464```

2465

2466來自 API 託管 [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) 的結果包含只有 API 可以讀取的加密欄位。API 拒絕重播它無法解密的內容的請求，例如為不同組織產生的內容。

2467

2468Claude Code 自己的 [WebSearch tool](/docs/zh-TW/tools-reference#websearch-tool-behavior) 將搜尋結果記錄為純文字，因此這些區塊通常通過代理或 [LLM gateway](/docs/zh-TW/llm-gateway) 到達對話，該代理或閘道本身執行了託管網路搜尋。

2469

2470被拒絕的區塊保留在對話歷史記錄中，因此每個後續輪次和 `/compact` 都失敗了相同的方式。

2471

2472**該怎麼辦：**

2473

2474* 執行 `/clear` 或開始新的工作階段；新對話不包含被拒絕的區塊

2475* 如果您在代理或閘道後面執行 Claude Code，請向操作它的人報告錯誤

2476

2394<h3 id="usage-policy-refusal">2477<h3 id="usage-policy-refusal">

2395 使用政策拒絕2478 使用政策拒絕

2396</h3>2479</h3>

2627* 如果目錄在相同路徑重新建立，您的 shell 仍然保有已刪除的目錄。執行 `cd "$PWD"` 或離開並重新進入目錄，然後執行 `claude`2710* 如果目錄在相同路徑重新建立，您的 shell 仍然保有已刪除的目錄。執行 `cd "$PWD"` 或離開並重新進入目錄，然後執行 `claude`

2628* 對於 macOS 上的 `EPERM`，使用 Cmd+Q 結束您的終端應用程式，重新開啟它，返回該資料夾，然後執行 `claude`。如果該資料夾中的 `ls` 仍然失敗，開啟**系統設定 > 隱私與安全 > 檔案和資料夾**，為您的終端應用程式開啟該資料夾，然後重新開啟終端2711* 對於 macOS 上的 `EPERM`，使用 Cmd+Q 結束您的終端應用程式，重新開啟它，返回該資料夾，然後執行 `claude`。如果該資料夾中的 `ls` 仍然失敗，開啟**系統設定 > 隱私與安全 > 檔案和資料夾**，為您的終端應用程式開啟該資料夾，然後重新開啟終端

2629 2712

2713<h3 id="temp-directory-refused-or-cannot-be-created">

2714 暫時目錄被拒絕或無法建立

2715</h3>

2716

2717在 macOS 和 Linux 上，Claude Code 在啟動時建立一個私有暫時目錄 `claude-<uid>`，位於系統暫時目錄或 [`CLAUDE_CODE_TMPDIR`](/docs/zh-TW/env-vars) 覆蓋下。當目錄無法建立，或該路徑的現有項目未通過安全檢查時，Claude Code 將失敗列印到 stderr 並以代碼 1 結束，而不是啟動工作階段：

2718

2719```text wrap theme={null}

2720ENOSPC: no space left on device, mkdir '/tmp/claude-501'

2721

2722Temp directory /tmp/claude-501 is not a directory (may be an attacker-planted symlink). Refusing to use it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

2723

2724Temp directory /tmp/claude-501 is owned by uid 502, expected 501. Refusing to use it — another user may have pre-created it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

2725

2726Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

2727```

2728

2729**該怎麼做：**

2730

2731* 對於 `ENOSPC`，釋放保有暫時目錄的磁碟區上的磁碟空間

2732* 對於 `Refusing to use it` 形式，移除命名的項目本身，而不是連結指向的內容，然後再次啟動 Claude Code；對於 `owned by uid` 形式，只有管理員或該使用者可以移除它

2733* 對於 `is not readable`，在命名的目錄上執行 `chmod 0700`，或移除它並重新啟動

2734* 在任何這些情況下，將 [`CLAUDE_CODE_TMPDIR`](/docs/zh-TW/env-vars) 設定為您控制的目錄並啟動 Claude Code，讓被拒絕的路徑保持不變

2735

2630<h3 id="directory-couldnt-be-resolved-to-a-real-location">2736<h3 id="directory-couldnt-be-resolved-to-a-real-location">

2631 目錄無法解析為真實位置2737 目錄無法解析為真實位置

2632</h3>2738</h3>

3282 Plugin 錯誤3388 Plugin 錯誤

3283</h2>3389</h2>

3284 3390

3285這些錯誤來自 [plugin](/docs/zh-TW/plugins) 和 [marketplace](/docs/zh-TW/plugin-marketplaces) 設定。對於不會產生此頁面上其中一則訊息的 plugin 問題，例如無法載入的 marketplace URL 或已安裝但未出現的 plugin，請參閱 [Plugin 疑難排解](/docs/zh-TW/discover-plugins#troubleshooting)。3391這些錯誤來自 [plugin](/docs/zh-TW/plugins/overview) 和 [marketplace](/docs/zh-TW/plugins/overview) 設定。對於不會產生此頁面上其中一則訊息的 plugin 問題，例如無法載入的 marketplace URL 或已安裝但未出現的 plugin，請參閱 [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting)。

3286 3392

3287<h3 id="plugin-eval-is-currently-in-early-access">3393<h3 id="plugin-eval-is-currently-in-early-access">

3288 plugin eval 目前處於早期存取階段3394 plugin eval 目前處於早期存取階段

3309 Marketplace 是從不受信任的來源註冊的3415 Marketplace 是從不受信任的來源註冊的

3310</h3>3416</h3>

3311 3417

3312Marketplace 是以 [為官方 Anthropic marketplace 保留的名稱](/docs/zh-TW/plugin-marketplaces#marketplace-schema) 註冊的，但其註冊的來源不是 `anthropics` GitHub 儲存庫。Claude Code 每次載入或重新整理 marketplace 時都會重新檢查保留的名稱，因此 marketplace 及從中安裝的 plugin 會停止載入。在 v2.1.205 之前，名稱只在新增 marketplace 時檢查，因此在其名稱變成保留名稱之前註冊的項目會繼續載入。3418Marketplace 是以 [為官方 Anthropic marketplace 保留的名稱](/docs/zh-TW/plugins/marketplace-reference#marketplace-file) 註冊的，但其註冊的來源不是 `anthropics` GitHub 儲存庫。Claude Code 每次載入或重新整理 marketplace 時都會重新檢查保留的名稱，因此 marketplace 及從中安裝的 plugin 會停止載入。在 v2.1.205 之前，名稱只在新增 marketplace 時檢查，因此在其名稱變成保留名稱之前註冊的項目會繼續載入。

3313 3419

3314```text theme={null}3420```text theme={null}

3315Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.3421Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

3321 3427

3322* 如果 marketplace 已經註冊，執行 `claude plugin marketplace remove <name>`，然後從官方 `github.com/anthropics` 儲存庫重新新增它3428* 如果 marketplace 已經註冊，執行 `claude plugin marketplace remove <name>`，然後從官方 `github.com/anthropics` 儲存庫重新新增它

3323* 如果您發佈了在其名稱變成保留名稱之前使用該名稱的第三方 marketplace，請重新命名它並要求使用者從您的來源重新新增它3429* 如果您發佈了在其名稱變成保留名稱之前使用該名稱的第三方 marketplace，請重新命名它並要求使用者從您的來源重新新增它

3324* 請參閱 [Marketplace schema](/docs/zh-TW/plugin-marketplaces#marketplace-schema) 下的保留名稱清單3430* 請參閱 [Marketplace schema](/docs/zh-TW/plugins/marketplace-reference#marketplace-file) 下的保留名稱清單

3431

3432<h3 id="marketplace-name-is-another-spelling-of-a-reserved-name">

3433 Marketplace 名稱是保留名稱的另一種拼寫

3434</h3>

3435

3436Marketplace 的名稱本身不是保留名稱，但 Claude Code 將其視為另一種拼寫。[保留的 marketplace 名稱](/docs/zh-TW/plugins/marketplace-reference#reserved-name-spellings) 列出哪些拼寫算作保留名稱。Claude Code 在您新增 marketplace 時拒絕這樣的名稱：

3437

3438```text theme={null}

3439Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.

3440```

3441

3442當 marketplace 已經以這樣的名稱註冊時，其項目停止載入，而 `/plugin`、`claude plugin install` 和 `claude plugin update` 警告：

3443

3444```text wrap theme={null}

3445known_marketplaces.json has an entry named "claude.code.plugins", another spelling of the reserved marketplace name "claude-code-plugins", so it is ignored. Remove it with: claude plugin marketplace remove claude.code.plugins

3446```

3447

3448當名稱需要 shell 引用時，新增時的拒絕讀作 `This marketplace's name is another spelling of "<reserved>", a reserved marketplace name. It is not exactly the reserved name it appears to be.`

3449

3450**該怎麼做：**

3451

3452* 將 marketplace 重新命名為不拼寫保留名稱的名稱，然後重新新增它

3453* 對於忽略的項目警告，執行它給出的 `claude plugin marketplace remove` 命令，或從 `~/.claude/plugins/known_marketplaces.json` 移除項目

3325 3454

3326<h3 id="marketplace-is-already-added-from-a-different-source">3455<h3 id="marketplace-is-already-added-from-a-different-source">

3327 Marketplace 已從不同的來源新增3456 Marketplace 已從不同的來源新增

3328</h3>3457</h3>

3329 3458

3330您透過 [`/plugin install <plugin> --marketplace <source>`](/docs/zh-TW/discover-plugins#add-a-marketplace-and-install-in-one-command) 確認新增 marketplace，而 Claude Code 從該來源擷取的目錄將自己命名為與您已從不同來源新增的 marketplace 相同的名稱。Claude Code 保留現有的 marketplace 而不是替換它，plugin 不會被安裝。3459您透過 [`/plugin install <plugin> --marketplace <source>`](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command) 確認新增 marketplace，而 Claude Code 從該來源擷取的目錄將自己命名為與您已從不同來源新增的 marketplace 相同的名稱。Claude Code 保留現有的 marketplace 而不是替換它，plugin 不會被安裝。

3331 3460

3332```text theme={null}3461```text theme={null}

3333Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.3462Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

3342 Plugin 命令在 shell 命令中參考 user\_config3471 Plugin 命令在 shell 命令中參考 user\_config

3343</h3>3472</h3>

3344 3473

3345Plugin hook、[monitor](/docs/zh-TW/plugins-reference#monitors) 或 MCP [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) 命令參考 `${user_config.KEY}` [plugin 選項](/docs/zh-TW/plugins-reference#user-configuration)，而替換後的字串會被傳遞到 shell。設定的值包含 `$(...)` 、反引號或 `;` 會在該處作為程式碼執行，因此 Claude Code 拒絕啟動該元件而不是替換該值。檢查在命令範本上執行，因此即使尚未設定任何值，錯誤也會出現。在 v2.1.207 之前，該值被替換到 shell 命令中。3474Plugin hook、[monitor](/docs/zh-TW/plugins/components#monitors) 或 MCP [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) 命令參考 `${user_config.KEY}` [plugin 選項](/docs/zh-TW/plugins/manifest-reference#user-configuration)，而替換後的字串會被傳遞到 shell。設定的值包含 `$(...)` 、反引號或 `;` 會在該處作為程式碼執行，因此 Claude Code 拒絕啟動該元件而不是替換該值。檢查在命令範本上執行，因此即使尚未設定任何值，錯誤也會出現。在 v2.1.207 之前，該值被替換到 shell 命令中。

3346 3475

3347措辭取決於哪個介面參考了該選項。Shell 形式的 hook 報告：3476措辭取決於哪個介面參考了該選項。Shell 形式的 hook 報告：

3348 3477

3372 Plugin 封存完整性檢查失敗3501 Plugin 封存完整性檢查失敗

3373</h3>3502</h3>

3374 3503

3375Plugin 的 marketplace 項目使用具有 `sha256` 釘選的 [`archive` 來源](/docs/zh-TW/plugin-marketplaces#zip-archives)，而下載檔案的摘要與釘選不符。Claude Code 拒絕安裝，因此 plugin 快取中沒有任何變更。不符有三個可能的原因：3504Plugin 的 marketplace 項目使用具有 `sha256` 釘選的 [`archive` 來源](/docs/zh-TW/plugins/marketplace-reference#archive-plugin-source)，而下載檔案的摘要與釘選不符。Claude Code 拒絕安裝，因此 plugin 快取中沒有任何變更。不符有三個可能的原因：

3376 3505

3377* 作者計算釘選後，URL 上的檔案已變更3506* 作者計算釘選後，URL 上的檔案已變更

3378* 作者在 marketplace 項目中輸入了錯誤的摘要3507* 作者在 marketplace 項目中輸入了錯誤的摘要

3392 路徑逃逸 plugin 目錄3521 路徑逃逸 plugin 目錄

3393</h3>3522</h3>

3394 3523

3395Plugin 元件路徑（在 plugin 的 `plugin.json` 或其 [marketplace 項目](/docs/zh-TW/plugin-marketplaces#plugin-entries) 中宣告）解析到 plugin 自己的目錄之外。Claude Code 捨棄該路徑並載入 plugin 的其餘部分。訊息中的元件名稱（例如 `commands` 或 `hooks`）命名了宣告路徑的欄位。3524Plugin 元件路徑（在 plugin 的 `plugin.json` 或其 [marketplace 項目](/docs/zh-TW/plugins/marketplace-reference#plugin-entries) 中宣告）解析到 plugin 自己的目錄之外。Claude Code 捨棄該路徑並載入 plugin 的其餘部分。訊息中的元件名稱（例如 `commands` 或 `hooks`）命名了宣告路徑的欄位。

3396 3525

3397```text theme={null}3526```text theme={null}

3398commands path escapes plugin directory: ./../shared.md3527commands path escapes plugin directory: ./../shared.md

3400 3529

3401在 `claude plugin` 命令輸出中，相同的錯誤讀作 `Path escapes plugin directory: ./../shared.md (commands)`。3530在 `claude plugin` 命令輸出中，相同的錯誤讀作 `Path escapes plugin directory: ./../shared.md (commands)`。

3402 3531

3403Claude Code 拒絕指向 plugin 外部的路徑（如 `../shared-utils`）和導致 plugin 外部的符號連結，以及 [marketplace 符號連結規則](/docs/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks) 不允許的符號連結。對於符號連結，訊息也會說明路徑解析的位置：3532Claude Code 拒絕指向 plugin 外部的路徑（如 `../shared-utils`）和導致 plugin 外部的符號連結，以及 [marketplace 符號連結規則](/docs/zh-TW/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks) 不允許的符號連結。對於符號連結，訊息也會說明路徑解析的位置：

3404 3533

3405```text theme={null}3534```text theme={null}

3406commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory3535commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory

3421* 將參考的檔案移到 plugin 目錄內，並使用 `./` 相對路徑指向它3550* 將參考的檔案移到 plugin 目錄內，並使用 `./` 相對路徑指向它

3422* 如果路徑是指向 plugin 外部檔案的符號連結，請用檔案副本替換符號連結3551* 如果路徑是指向 plugin 外部檔案的符號連結，請用檔案副本替換符號連結

3423* 如果訊息說路徑包含反斜線，請使用正斜線寫入路徑，例如 `./commands/deploy.md`3552* 如果訊息說路徑包含反斜線，請使用正斜線寫入路徑，例如 `./commands/deploy.md`

3424* 若要與同一 marketplace 中的其他 plugin 共享檔案，請使用 plugin 目錄內的符號連結連結它們，遵循 [符號連結規則](/docs/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks)3553* 若要與同一 marketplace 中的其他 plugin 共享檔案，請使用 plugin 目錄內的符號連結連結它們，遵循 [符號連結規則](/docs/zh-TW/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)

3425 3554

3426<h3 id="path-could-not-be-checked">3555<h3 id="path-could-not-be-checked">

3427 無法檢查路徑3556 無法檢查路徑

3429 3558

3430Claude Code 詢問作業系統 plugin 路徑是否存在，並收到除「找不到」以外的錯誤，因此它不會載入路徑命名的內容。plugin 的多少部分載入取決於哪個路徑失敗：3559Claude Code 詢問作業系統 plugin 路徑是否存在，並收到除「找不到」以外的錯誤，因此它不會載入路徑命名的內容。plugin 的多少部分載入取決於哪個路徑失敗：

3431 3560

3432* Plugin 的其中一個 [預設元件位置](/docs/zh-TW/plugins-reference#file-locations-reference)（例如 `skills/` 資料夾、`monitors/monitors.json` 檔案或 plugin 根目錄的 [`SKILL.md`](/docs/zh-TW/plugins-reference#skills)）：plugin 的其他元件仍會載入3561* Plugin 的其中一個 [預設元件位置](/docs/zh-TW/plugins/manifest-reference#standard-layout)（例如 `skills/` 資料夾、`monitors/monitors.json` 檔案或 plugin 根目錄的 [`SKILL.md`](/docs/zh-TW/plugins/components#skills)）：plugin 的其他元件仍會載入

3433* Plugin 自己的目錄：該 plugin 中沒有任何內容載入3562* Plugin 自己的目錄：該 plugin 中沒有任何內容載入

3434 3563

3435對於根本不存在的路徑，您看不到此錯誤。在 `/plugin` 中，錯誤出現在 plugin 下方，並命名路徑和作業系統傳回的程式碼：3564對於根本不存在的路徑，您看不到此錯誤。在 `/plugin` 中，錯誤出現在 plugin 下方，並命名路徑和作業系統傳回的程式碼：

3459 Marketplace 項目路徑不保持在 marketplace 目錄內3588 Marketplace 項目路徑不保持在 marketplace 目錄內

3460</h3>3589</h3>

3461 3590

3462Plugin 的 [marketplace 項目](/docs/zh-TW/plugin-marketplaces#plugin-entries) 宣告了一個來源路徑，Claude Code 無法將其解析到 marketplace 自己的目錄內的位置，因此 plugin 不會安裝或載入。拒絕涵蓋：3591Plugin 的 [marketplace 項目](/docs/zh-TW/plugins/marketplace-reference#plugin-entries) 宣告了一個來源路徑，Claude Code 無法將其解析到 marketplace 自己的目錄內的位置，因此 plugin 不會安裝或載入。拒絕涵蓋：

3463 3592

3464* 絕對的項目路徑、使用 `..` 爬出 marketplace 或拼寫成網路路徑的項目路徑3593* 絕對的項目路徑、使用 `..` 爬出 marketplace 或拼寫成網路路徑的項目路徑

3465* 在 macOS 和 Linux 上，項目路徑在前導 `./` 之後的任何地方包含反斜線3594* 在 macOS 和 Linux 上，項目路徑在前導 `./` 之後的任何地方包含反斜線

3466* 從遠端來源（例如 git 或 URL）擷取的 marketplace 中的項目，通過解析到 marketplace 目錄外的符號連結到達其目標3595* 從遠端來源（例如 git 或 URL）擷取的 marketplace 中的項目，通過解析到 marketplace 目錄外的符號連結到達其目標

3467* 相對項目在從直接 URL 新增到其 `marketplace.json` 的 marketplace 中：Claude Code 只下載該檔案，因此路徑命名的本機 plugin 檔案不存在。請參閱 [相對路徑的 Plugin 在基於 URL 的 marketplace 中失敗](/docs/zh-TW/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)3596* 相對項目在從直接 URL 新增到其 `marketplace.json` 的 marketplace 中：Claude Code 只下載該檔案，因此路徑命名的本機 plugin 檔案不存在。請參閱 [相對路徑的 Plugin 在基於 URL 的 marketplace 中失敗](/docs/zh-TW/plugins/troubleshooting#plugins-with-relative-paths-fail-in-url-based-marketplaces)

3468 3597

3469`claude plugin install` 報告拒絕如下：3598`claude plugin install` 報告拒絕如下：

3470 3599

3481**該怎麼做：**3610**該怎麼做：**

3482 3611

3483* 如果您維護 marketplace，將項目的 `source` 寫成純相對路徑（例如 `./plugins/my-plugin`），並保持它跨越的任何符號連結指向 marketplace 目錄內3612* 如果您維護 marketplace，將項目的 `source` 寫成純相對路徑（例如 `./plugins/my-plugin`），並保持它跨越的任何符號連結指向 marketplace 目錄內

3484* 如果您從直接 URL 新增了 marketplace，相對項目無法解析。要求 marketplace 作者使用 [另一個 plugin 來源](/docs/zh-TW/plugin-marketplaces#plugin-sources)，或改為從其 git 儲存庫新增 marketplace3613* 如果您從直接 URL 新增了 marketplace，相對項目無法解析。要求 marketplace 作者使用 [另一個 plugin 來源](/docs/zh-TW/plugins/marketplace-reference#plugin-sources)，或改為從其 git 儲存庫新增 marketplace

3485 3614

3486<h3 id="failed-to-load-marketplace-configuration">3615<h3 id="failed-to-load-marketplace-configuration">

3487 無法載入 marketplace 設定3616 無法載入 marketplace 設定

3492* `Failed to load marketplace configuration`：檔案不是有效的 JSON，或無法讀取。空檔案也會以這種方式失敗。3621* `Failed to load marketplace configuration`：檔案不是有效的 JSON，或無法讀取。空檔案也會以這種方式失敗。

3493* `Marketplace configuration file is corrupted`：檔案是有效的 JSON，但其內容與登錄架構不符。3622* `Marketplace configuration file is corrupted`：檔案是有效的 JSON，但其內容與登錄架構不符。

3494 3623

3495遺失的檔案不是失敗：Claude Code 將其視為沒有 marketplace 的登錄。3624遺失的檔案不是失敗：Claude Code 將其視為沒有marketplace 的登錄。

3496 3625

3497使用空檔案時，`claude plugin install` 報告：3626使用空檔案時，`claude plugin install` 報告：

3498 3627

3511 Plugin 是您的組織所需的3640 Plugin 是您的組織所需的

3512</h3>3641</h3>

3513 3642

3514您執行了 `claude plugin disable`，或使用 `/plugin` **已安裝** 標籤，以關閉您的組織標記為必需的 [從 claude.ai 同步的 plugin](/docs/zh-TW/plugins-reference#synced-plugins)：3643您執行了 `claude plugin disable`，或使用 `/plugin` **已安裝** 標籤，以關閉您的組織標記為必需的 [從 claude.ai 同步的 plugin](/docs/zh-TW/plugins/loading#synced-plugins)：

3515 3644

3516```text theme={null}3645```text theme={null}

3517Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.3646Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.

feature-availability.md +1 −1

Details

32* [CLI](/docs/zh-TW/quickstart) 和 [Agent SDK](/docs/zh-TW/agent-sdk/overview)32* [CLI](/docs/zh-TW/quickstart) 和 [Agent SDK](/docs/zh-TW/agent-sdk/overview)

33* [VS Code](/docs/zh-TW/vs-code) 和 [JetBrains](/docs/zh-TW/jetbrains) 擴充功能33* [VS Code](/docs/zh-TW/vs-code) 和 [JetBrains](/docs/zh-TW/jetbrains) 擴充功能

34* [Subagents](/docs/zh-TW/sub-agents)、[hooks](/docs/zh-TW/hooks-guide)、[commands](/docs/zh-TW/commands) 和 [skills](/docs/zh-TW/skills)34* [Subagents](/docs/zh-TW/sub-agents)、[hooks](/docs/zh-TW/hooks-guide)、[commands](/docs/zh-TW/commands) 和 [skills](/docs/zh-TW/skills)

~~35* [CLAUDE.md 記憶](/docs/zh-TW/memory)、[plugins](/docs/zh-TW/plugins) 和 [MCP servers](/docs/zh-TW/mcp)~~35* [CLAUDE.md 記憶](/docs/zh-TW/memory)、[plugins](/docs/zh-TW/plugins/overview) 和 [MCP servers](/docs/zh-TW/mcp)

36* [Checkpoints](/docs/zh-TW/checkpointing)、[sandboxing](/docs/zh-TW/sandboxing) 和 [Workflows](/docs/zh-TW/workflows)36* [Checkpoints](/docs/zh-TW/checkpointing)、[sandboxing](/docs/zh-TW/sandboxing) 和 [Workflows](/docs/zh-TW/workflows)

37* [OpenTelemetry 指標](/docs/zh-TW/monitoring-usage)和[受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)37* [OpenTelemetry 指標](/docs/zh-TW/monitoring-usage)和[受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)

38 38

features-overview.md +9 −9

Details

29* **[Dynamic workflows](/docs/zh-TW/workflows)** 從 Claude 編寫的指令碼運行許多 subagents，返回一個結果29* **[Dynamic workflows](/docs/zh-TW/workflows)** 從 Claude 編寫的指令碼運行許多 subagents，返回一個結果

30* **[Cross-session messaging](/docs/zh-TW/cross-session-messaging)** 讓 Claude 將訊息從您的一個會話傳遞到另一個會話30* **[Cross-session messaging](/docs/zh-TW/cross-session-messaging)** 讓 Claude 將訊息從您的一個會話傳遞到另一個會話

31* **[Hooks](/docs/zh-TW/hooks-guide)** 在 Claude Code 達到生命週期事件時運行您的指令碼、HTTP 請求、MCP 工具呼叫、提示或 subagent31* **[Hooks](/docs/zh-TW/hooks-guide)** 在 Claude Code 達到生命週期事件時運行您的指令碼、HTTP 請求、MCP 工具呼叫、提示或 subagent

~~32* **[Plugins](/docs/zh-TW/plugins)** 和 **[marketplaces](/docs/zh-TW/plugin-marketplaces)** 打包和分發這些功能~~32* **[Plugins](/docs/zh-TW/plugins/overview)** 和 **[marketplaces](/docs/zh-TW/plugins/overview)** 打包和分發這些功能

33 33

34[Skills](/docs/zh-TW/skills) 是最靈活的擴展。Skill 是一個包含知識、工作流程或指令的 markdown 檔案。您可以使用像 `/deploy` 這樣的命令調用 skills，或者 Claude 可以在相關時自動載入它們。Skills 可以在您目前的對話中運行，或通過 subagents 在隔離的上下文中運行。34[Skills](/docs/zh-TW/skills) 是最靈活的擴展。Skill 是一個包含知識、工作流程或指令的 markdown 檔案。您可以使用像 `/deploy` 這樣的命令調用 skills，或者 Claude 可以在相關時自動載入它們。Skills 可以在您目前的對話中運行，或通過 subagents 在隔離的上下文中運行。

35 35

54 54

55**[Plugins](/docs/zh-TW/plugins)** 是打包層。Plugin 將 skills、hooks、subagents 和 MCP servers 捆綁到單個可安裝單元中。Plugin skills 是命名空間的（如 `/my-plugin:review`），因此多個 plugins 可以共存。當您想在多個儲存庫中重複使用相同的設置或通過 **[marketplace](/docs/zh-TW/plugin-marketplaces)** 分發給他人時，使用 plugins。55**[Plugins](/docs/zh-TW/plugins/overview)** 是打包層。Plugin 將 skills、hooks、subagents 和 MCP servers 捆綁到單個可安裝單元中。Plugin skills 是命名空間的（如 `/my-plugin:review`），因此多個 plugins 可以共存。當您想在多個儲存庫中重複使用相同的設置或通過 **[marketplace](/docs/zh-TW/plugins/overview)** 分發給他人時，使用 plugins。

56 56

57<h3 id="build-your-setup-over-time">57<h3 id="build-your-setup-over-time">

58 隨著時間推移構建您的設置58 隨著時間推移構建您的設置

61您不需要預先配置所有內容。每個功能都有一個可識別的觸發器，大多數團隊大致按以下順序添加它們：61您不需要預先配置所有內容。每個功能都有一個可識別的觸發器，大多數團隊大致按以下順序添加它們：

62 62

63| 觸發器 | 添加 |63| 觸發器 | 添加 |

~~64| :----------------------------- | :---------------------------------------------------------------------------- |~~64| :----------------------------- | :------------------------------------------------------------------- |

65| Claude 兩次出錯的約定或命令 | 將其添加到 [CLAUDE.md](/docs/zh-TW/memory) |65| Claude 兩次出錯的約定或命令 | 將其添加到 [CLAUDE.md](/docs/zh-TW/memory) |

66| 您一直在要求 Claude 更簡潔、解釋更多或以相同格式回答 | 設定 [輸出風格](/docs/zh-TW/output-styles) |66| 您一直在要求 Claude 更簡潔、解釋更多或以相同格式回答 | 設定 [輸出風格](/docs/zh-TW/output-styles) |

67| 您一直在輸入相同的提示來啟動任務 | 將其保存為使用者可調用的 [skill](/docs/zh-TW/skills) |67| 您一直在輸入相同的提示來啟動任務 | 將其保存為使用者可調用的 [skill](/docs/zh-TW/skills) |

68| 您第三次將相同的劇本或多步驟程序粘貼到聊天中 | 將其捕獲為 [skill](/docs/zh-TW/skills) |68| 您第三次將相同的劇本或多步驟程序粘貼到聊天中 | 將其捕獲為 [skill](/docs/zh-TW/skills) |

69| 您一直在從 Claude 無法看到的瀏覽器選項卡複製資料 | 將該系統連接為 [MCP server](/docs/zh-TW/mcp) |69| 您一直在從 Claude 無法看到的瀏覽器選項卡複製資料 | 將該系統連接為 [MCP server](/docs/zh-TW/mcp) |

~~70| Claude 讀取許多檔案以找到符號的定義或使用位置 | 為您的語言安裝 [code intelligence plugin](/docs/zh-TW/discover-plugins#code-intelligence) |~~70| Claude 讀取許多檔案以找到符號的定義或使用位置 | 為您的語言安裝 [code intelligence plugin](/docs/zh-TW/plugins/code-intelligence) |

71| 一個附帶任務用您不會再次參考的輸出淹沒您的對話 | 通過 [subagent](/docs/zh-TW/sub-agents) 路由它 |71| 一個附帶任務用您不會再次參考的輸出淹沒您的對話 | 通過 [subagent](/docs/zh-TW/sub-agents) 路由它 |

72| 您希望每次都發生某事而無需詢問 | 編寫 [hook](/docs/zh-TW/hooks-guide) |72| 您希望每次都發生某事而無需詢問 | 編寫 [hook](/docs/zh-TW/hooks-guide) |

~~73| 第二個儲存庫需要相同的設置 | 將其打包為 [plugin](/docs/zh-TW/plugins) |~~73| 第二個儲存庫需要相同的設置 | 將其打包為 [plugin](/docs/zh-TW/plugins/overview) |

74 74

75相同的觸發器告訴您何時更新您已經擁有的內容。重複的錯誤或反覆出現的審查評論是 CLAUDE.md 編輯，而不是聊天中的一次性更正。您一直手動調整的工作流程是需要另一次修訂的 skill。75相同的觸發器告訴您何時更新您已經擁有的內容。重複的錯誤或反覆出現的審查評論是 CLAUDE.md 編輯，而不是聊天中的一次性更正。您一直手動調整的工作流程是需要另一次修訂的 skill。

76 76

207功能可以在多個級別定義：使用者範圍、每個專案、通過 plugins，或通過受管理的策略。您也可以在子目錄中嵌套 CLAUDE.md 檔案，或在 monorepo 的特定套件中放置 skills。當相同的功能存在於多個級別時，以下是它們的分層方式：207功能可以在多個級別定義：使用者範圍、每個專案、通過 plugins，或通過受管理的策略。您也可以在子目錄中嵌套 CLAUDE.md 檔案，或在 monorepo 的特定套件中放置 skills。當相同的功能存在於多個級別時，以下是它們的分層方式：

208 208

209* **CLAUDE.md 檔案** 是累加的：所有級別同時對 Claude 的上下文貢獻內容。來自您的工作目錄及以上的檔案在啟動時載入；子目錄在您在其中工作時載入。當指令衝突時，Claude 使用判斷來協調它們。請參閱 [CLAUDE.md 檔案如何載入](/docs/zh-TW/memory#how-claude-md-files-load)。209* **CLAUDE.md 檔案** 是累加的：所有級別同時對 Claude 的上下文貢獻內容。來自您的工作目錄及以上的檔案在啟動時載入；子目錄在您在其中工作時載入。當指令衝突時，Claude 使用判斷來協調它們。請參閱 [CLAUDE.md 檔案如何載入](/docs/zh-TW/memory#how-claude-md-files-load)。

210* **Skills 和 subagents** 按名稱覆蓋：當相同名稱存在於多個級別時，一個定義根據優先級獲勝（skills 為受管理 > 使用者 > 專案；subagents 為受管理 > CLI 標誌 > 專案 > 使用者 > plugin）。Plugin skills 是[命名空間](/docs/zh-TW/plugins#add-skills-to-your-plugin)的，以避免衝突。請參閱 [skill 發現](/docs/zh-TW/skills#resolve-skills-that-share-a-name) 和 [subagent 範圍](/docs/zh-TW/sub-agents#choose-the-subagent-scope)。210* **Skills 和 subagents** 按名稱覆蓋：當相同名稱存在於多個級別時，一個定義根據優先級獲勝（skills 為受管理 > 使用者 > 專案；subagents 為受管理 > CLI 標誌 > 專案 > 使用者 > plugin）。Plugin skills 是[命名空間](/docs/zh-TW/plugins/components#skills)的，以避免衝突。請參閱 [skill 發現](/docs/zh-TW/skills#resolve-skills-that-share-a-name) 和 [subagent 範圍](/docs/zh-TW/sub-agents#choose-the-subagent-scope)。

211* **MCP 伺服器** 按名稱覆蓋：本地 > 專案 > 使用者。請參閱 [MCP 範圍](/docs/zh-TW/mcp#scope-hierarchy-and-precedence)。211* **MCP 伺服器** 按名稱覆蓋：本地 > 專案 > 使用者。請參閱 [MCP 範圍](/docs/zh-TW/mcp#scope-hierarchy-and-precedence)。

212* **Hooks** 合併：所有註冊的 hooks 為其匹配事件觸發，無論來源如何。請參閱 [hooks](/docs/zh-TW/hooks)。212* **Hooks** 合併：所有註冊的 hooks 為其匹配事件觸發，無論來源如何。請參閱 [hooks](/docs/zh-TW/hooks)。

213 213

304 304

305 **上下文成本：** 低。符號查詢通常會取代廣泛的檔案讀取，因此淨上下文使用可能會下降。305 **上下文成本：** 低。符號查詢通常會取代廣泛的檔案讀取，因此淨上下文使用可能會下降。

306 306

307 <Tip>LSP 工具在您為您的語言安裝[程式碼智能 plugin](/docs/zh-TW/discover-plugins#code-intelligence)之前處於非活動狀態。</Tip>307 <Tip>LSP 工具在您為您的語言安裝[程式碼智能 plugin](/docs/zh-TW/plugins/code-intelligence)之前處於非活動狀態。</Tip>

308 </Tab>308 </Tab>

309 309

310 <Tab title="Subagents">310 <Tab title="Subagents">

370 使用 hooks 自動化動作370 使用 hooks 自動化動作

371 </Card>371 </Card>

372 372

373 <Card title="Plugins" icon="puzzle-piece" href="/docs/zh-TW/plugins">373 <Card title="Plugins" icon="puzzle-piece" href="/docs/zh-TW/plugins/overview">

374 捆綁和共享功能集374 捆綁和共享功能集

375 </Card>375 </Card>

376 376

377 <Card title="Marketplaces" icon="store" href="/docs/zh-TW/plugin-marketplaces">377 <Card title="Marketplaces" icon="store" href="/docs/zh-TW/plugins/create-marketplace">

378 託管和分發 plugin 集合378 託管和分發 plugin 集合

379 </Card>379 </Card>

380</CardGroup>380</CardGroup>

fullscreen.md +3 −2

Details

100 100

101* **在提示輸入欄中點擊**，以在您輸入的文字中的任何位置放置游標。101* **在提示輸入欄中點擊**，以在您輸入的文字中的任何位置放置游標。

102* **點擊 `/` 命令或 `@` 檔案清單中的建議**，以接受它。懸停會突顯游標下的列。102* **點擊 `/` 命令或 `@` 檔案清單中的建議**，以接受它。懸停會突顯游標下的列。

103* **點擊選擇功能表中的選項**，以選擇它。這涵蓋權限提示、`/model`、`/config` 和其他顯示選項清單的對話框。懸停會在游標下的列上顯示指標。需要 Claude Code v2.1.187 或更新版本。103* **點擊選擇功能表中的選項**，以選擇它。這涵蓋權限提示、`/model`、`/config` 和其他顯示選項清單的對話框。懸停會在游標下的列上顯示指標。

104* **點擊多選功能表中的選項**，以切換它，然後點擊提交按鈕以確認您的選擇。點擊自由文字列（例如多選題中的 `Other` 列）會聚焦其輸入欄位，以便您可以輸入答案。需要 Claude Code v2.1.208 或更新版本。104* **點擊多選功能表中的選項**，以切換它，然後點擊提交按鈕以確認您的選擇。點擊自由文字列（例如多選題中的 `Other` 列）會聚焦其輸入欄位，以便您可以輸入答案。需要 Claude Code v2.1.208 或更新版本。

105* **點擊設定面板中的設定值**，以變更它，並使用滑鼠滾輪捲動設定清單。需要 Claude Code v2.1.271 或更新版本。105* **點擊 `/config` 面板中的設定值**，以變更它，並使用滑鼠滾輪捲動設定清單。需要 Claude Code v2.1.271 或更新版本。

106* **使用滑鼠滾輪捲動選擇或多選功能表**，當它有超過一次顯示的選項時，例如短終端機視窗中的 `/model` 清單。當指標在其選項上方時，滾輪會捲動清單。需要 Claude Code v2.1.280 或更新版本。

106* **點擊已摺疊的工具結果**，以展開它並查看完整輸出。再次點擊以摺疊。工具呼叫及其結果會一起展開。只有有更多內容要顯示的訊息才可點擊。107* **點擊已摺疊的工具結果**，以展開它並查看完整輸出。再次點擊以摺疊。工具呼叫及其結果會一起展開。只有有更多內容要顯示的訊息才可點擊。

107 * 點擊也會展開 `!` shell 命令的輸出，無論是較舊的截斷結果或命令執行時的即時進度列。需要 Claude Code v2.1.257 或更新版本。108 * 點擊也會展開 `!` shell 命令的輸出，無論是較舊的截斷結果或命令執行時的即時進度列。需要 Claude Code v2.1.257 或更新版本。

108* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然後點擊 URL 或檔案路徑**，以開啟它。純 `http://` 和 `https://` URL 會在您的瀏覽器中開啟，而工具輸出中的檔案路徑（例如在 Edit 或 Write 後列印的路徑）會在您的預設應用程式中開啟。不使用修飾鍵的純點擊不會開啟連結，符合原生終端機行為。109* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然後點擊 URL 或檔案路徑**，以開啟它。純 `http://` 和 `https://` URL 會在您的瀏覽器中開啟，而工具輸出中的檔案路徑（例如在 Edit 或 Write 後列印的路徑）會在您的預設應用程式中開啟。不使用修飾鍵的純點擊不會開啟連結，符合原生終端機行為。

github-actions.md +2 −2

Details

50* 再次執行 `/install-github-app`。當儲存庫已經有 `claude.yml` 時，選擇**使用最新版本更新工作流程檔案**。Claude Code 將新的工作流程檔案副本推送到新分支並開啟 pull request，與首次安裝相同。50* 再次執行 `/install-github-app`。當儲存庫已經有 `claude.yml` 時，選擇**使用最新版本更新工作流程檔案**。Claude Code 將新的工作流程檔案副本推送到新分支並開啟 pull request，與首次安裝相同。

51* 自己將 `--comment` 引數和 [審查工作流程範例](#run-a-skill)中的 `claude_args` 行新增到簽入的檔案，這會保留您對其所做的任何其他編輯。51* 自己將 `--comment` 引數和 [審查工作流程範例](#run-a-skill)中的 `claude_args` 行新增到簽入的檔案，這會保留您對其所做的任何其他編輯。

52 52

53安裝 GitHub App 後，Claude Code 會詢問是否繼續進行 GitHub Actions 設定。選擇**暫時跳過**以僅安裝 GitHub App。稍後再次執行 `/install-github-app` 以完成工作流程和密鑰步驟。在 v2.1.187 之前，Claude Code 直接進行工作流程選擇。53安裝 GitHub App 後，Claude Code 會詢問是否繼續進行 GitHub Actions 設定。選擇**暫時跳過**以僅安裝 GitHub App。稍後再次執行 `/install-github-app` 以完成工作流程和密鑰步驟。

54 54

55<Note>55<Note>

56 * 安裝 GitHub App 時，您授予它多個權限。有關完整集合，請參閱 [GitHub App 權限](#github-app-permissions)56 * 安裝 GitHub App 時，您授予它多個權限。有關完整集合，請參閱 [GitHub App 權限](#github-app-permissions)

237`prompt` 輸入接受[技能](/docs/zh-TW/skills)調用以及純文字：237`prompt` 輸入接受[技能](/docs/zh-TW/skills)調用以及純文字：

238 238

239* 對於儲存庫的 `.claude/skills/` 目錄中的技能，在 `anthropics/claude-code-action` 步驟之前執行 `actions/checkout`，以便技能檔案在執行器上可用，然後將 `/skill-name` 作為 `prompt` 傳遞。239* 對於儲存庫的 `.claude/skills/` 目錄中的技能，在 `anthropics/claude-code-action` 步驟之前執行 `actions/checkout`，以便技能檔案在執行器上可用，然後將 `/skill-name` 作為 `prompt` 傳遞。

240* 對於打包在[外掛程式](/docs/zh-TW/plugins)中的技能，使用 `plugin_marketplaces` 和 `plugins` 輸入安裝外掛程式，然後將命名空間 `/plugin-name:skill-name` 作為 `prompt` 傳遞。`plugins` 輸入採用 `plugin-name@marketplace-name`，其中市場名稱來自市場自己的清單，而不是其儲存庫 URL。240* 對於打包在[外掛程式](/docs/zh-TW/plugins/overview)中的技能，使用 `plugin_marketplaces` 和 `plugins` 輸入安裝外掛程式，然後將命名空間 `/plugin-name:skill-name` 作為 `prompt` 傳遞。`plugins` 輸入採用 `plugin-name@marketplace-name`，其中市場名稱來自市場自己的清單，而不是其儲存庫 URL。

241 241

242以下工作流程安裝 `code-review` 外掛程式，並在 pull request 開啟、更新、重新開啟或標記為準備審查時執行其技能。它執行與快速設定中的審查工作流程相同的外掛程式。當您想控制提示、模型和觸發器本身時，使用這樣的工作流程。如需自動審查而無需維護工作流程檔案，請參閱 [Code Review](/docs/zh-TW/code-review)。在公開儲存庫上，GitHub 從 fork pull request 觸發的執行中扣留密鑰，因此審查僅在來自同一儲存庫中分支的 pull request 上執行。242以下工作流程安裝 `code-review` 外掛程式，並在 pull request 開啟、更新、重新開啟或標記為準備審查時執行其技能。它執行與快速設定中的審查工作流程相同的外掛程式。當您想控制提示、模型和觸發器本身時，使用這樣的工作流程。如需自動審查而無需維護工作流程檔案，請參閱 [Code Review](/docs/zh-TW/code-review)。在公開儲存庫上，GitHub 從 fork pull request 觸發的執行中扣留密鑰，因此審查僅在來自同一儲存庫中分支的 pull request 上執行。

243 243

github-enterprise-server.md +4 −4

Details

68資訊清單使用下列權限和 webhook 事件設定 GitHub App，這些權限和事件共同涵蓋網頁工作階段、程式碼審查、Claude Security、外掛程式市集和貢獻指標：68資訊清單使用下列權限和 webhook 事件設定 GitHub App，這些權限和事件共同涵蓋網頁工作階段、程式碼審查、Claude Security、外掛程式市集和貢獻指標：

69 69

70| 權限 | 存取 | 用途 |70| 權限 | 存取 | 用途 |

~~71| :------------------- | :---- | :------------------------------------------------------------------------------------------------ |~~71| :------------------- | :---- | :------------------------------------------------------------------------------------------------------------------------- |

76| Actions | 讀取 | 讀取自動修復的 CI 狀態 |76| Actions | 讀取 | 讀取自動修復的 CI 狀態 |

77| Commit statuses | 讀取 | 從報告提交狀態而非檢查執行的提供者讀取 CI 狀態 |77| Commit statuses | 讀取 | 從報告提交狀態而非檢查執行的提供者讀取 CI 狀態 |

79| Metadata | 讀取 | GitHub 要求所有應用程式必須具備 |79| Metadata | 讀取 | GitHub 要求所有應用程式必須具備 |

80| Organization members | 讀取 | 符合 github.com 上的 Claude GitHub App，用於在連結安裝時檢查連接使用者的組織角色 |80| Organization members | 讀取 | 符合 github.com 上的 Claude GitHub App，用於在連結安裝時檢查連接使用者的組織角色 |

81 81

160 160

161Claude Code 以非互動方式執行 git，並拒絕連接到不在機器 `known_hosts` 檔案中的主機的 SSH 連接。帶有 git 認證幫助程式的 HTTPS URL 可以避免 `known_hosts` 要求。161Claude Code 以非互動方式執行 git，並拒絕連接到不在機器 `known_hosts` 檔案中的主機的 SSH 連接。帶有 git 認證幫助程式的 HTTPS URL 可以避免 `known_hosts` 要求。

162 162

163有關構建市場的完整指南，請參閱 [Create and distribute a plugin marketplace](/docs/zh-TW/plugin-marketplaces)。163有關構建市場的完整指南，請參閱 [建立和分發插件市場](/docs/zh-TW/plugins/create-marketplace)。

164 164

165<h3 id="pre-register-ghes-marketplaces-with-managed-settings">165<h3 id="pre-register-ghes-marketplaces-with-managed-settings">

166 使用託管設定預先註冊 GHES 市場166 使用託管設定預先註冊 GHES 市場

262 262

263* [在雲端使用 Claude Code](/docs/zh-TW/claude-code-on-the-web)：在雲基礎設施上運行 Claude Code 會話263* [在雲端使用 Claude Code](/docs/zh-TW/claude-code-on-the-web)：在雲基礎設施上運行 Claude Code 會話

264* [Code Review](/docs/zh-TW/code-review)：自動化 PR 審查264* [Code Review](/docs/zh-TW/code-review)：自動化 PR 審查

265* [Plugin marketplaces](/docs/zh-TW/plugin-marketplaces)：構建和分發插件目錄265* [Plugin marketplaces](/docs/zh-TW/plugins/host-marketplace)：構建和分發插件目錄

266* [Analytics](/docs/zh-TW/analytics)：跟踪使用情況和貢獻指標266* [Analytics](/docs/zh-TW/analytics)：跟踪使用情況和貢獻指標

267* [Managed settings](/docs/zh-TW/settings)：組織範圍的策略配置267* [Managed settings](/docs/zh-TW/settings)：組織範圍的策略配置

268* [Network configuration](/docs/zh-TW/network-config)：防火牆和 IP 白名單要求268* [Network configuration](/docs/zh-TW/network-config)：防火牆和 IP 白名單要求

glossary.md +3 −3

Details

84 Bare mode84 Bare mode

85</h3>85</h3>

86 86

87使用 `--bare`，Claude Code 啟動時不會載入 hooks、skills、自訂命令、subagents、plugins、MCP servers、auto memory 或 CLAUDE.md，除了您使用 `--add-dir` 傳遞的目錄中的 skills。建議用於 CI 和指令碼呼叫，其中您需要在每台機器上獲得相同的結果。87使用 `--bare`，Claude Code 啟動時不會載入 hooks、skills、自訂命令、subagents、installed plugins、MCP servers、auto memory 或 CLAUDE.md，除了您使用 `--add-dir` 傳遞的目錄中的 skills。建議用於 CI 和指令碼呼叫，其中您需要在每台機器上獲得相同的結果。

88 88

89了解更多：[使用 bare mode 更快啟動](/docs/zh-TW/headless#start-faster-with-bare-mode)89了解更多：[使用 bare mode 更快啟動](/docs/zh-TW/headless#start-faster-with-bare-mode)

90 90

332 Plugin332 Plugin

333</h3>333</h3>

334 334

335一個 skills、hooks、subagents 和 MCP servers 的捆綁包，打包為單個可安裝單元。Plugin skills 命名為 `plugin-name:skill-name`，以便多個 plugins 共存。通過 [marketplace](/docs/zh-TW/plugin-marketplaces) 在團隊間分發 plugins。335一個 skills、hooks、subagents 和 MCP servers 的捆綁包，打包為單個可安裝單元。Plugin skills 命名為 `plugin-name:skill-name`，以便多個 plugins 共存。通過 [marketplace](/docs/zh-TW/plugins/overview) 在團隊間分發 plugins。

336 336

337了解更多：[Plugins](/docs/zh-TW/plugins)337了解更多：[Plugins](/docs/zh-TW/plugins/overview)

338 338

339<h3 id="project-trust">339<h3 id="project-trust">

340 Project trust340 Project trust

headless.md +1 −1

Details

38 使用裸機模式加快速度38 使用裸機模式加快速度

39</h3>39</h3>

40 40

41新增 `--bare` 以跳過 hooks、skills、自訂命令、[subagents](/docs/zh-TW/sub-agents)、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索來減少啟動時間。沒有它，`claude -p` 會載入互動式工作階段會載入的相同 [上下文](/docs/zh-TW/how-claude-code-works#the-context-window)，包括在工作目錄或 `~/.claude` 中設定的任何內容。41新增 `--bare` 以跳過 hooks、skills、自訂命令、[subagents](/docs/zh-TW/sub-agents)、installed plugins、MCP 伺服器、auto memory 和 CLAUDE.md 的自動探索來減少啟動時間。沒有它，`claude -p` 會載入互動式工作階段會載入的相同 [context](/docs/zh-TW/how-claude-code-works#the-context-window)，包括在工作目錄或 `~/.claude` 中設定的任何內容。

42 42

43裸機模式對於 CI 和指令碼很有用，您需要在每台機器上獲得相同的結果。隊友 `~/.claude` 中的 hook 或專案的 `.mcp.json` 中的 MCP 伺服器不會執行，因為裸機模式永遠不會讀取它們。您使用 `--add-dir` 命名的目錄是部分例外：裸機模式會從其 `.claude/skills/` 資料夾載入 skills，但仍會跳過其 `.claude/commands/` 和 `.claude/agents/` 資料夾。[來自其他目錄的 Skills](/docs/zh-TW/skills#skills-from-additional-directories) 涵蓋載入和不載入的內容。43裸機模式對於 CI 和指令碼很有用，您需要在每台機器上獲得相同的結果。隊友 `~/.claude` 中的 hook 或專案的 `.mcp.json` 中的 MCP 伺服器不會執行，因為裸機模式永遠不會讀取它們。您使用 `--add-dir` 命名的目錄是部分例外：裸機模式會從其 `.claude/skills/` 資料夾載入 skills，但仍會跳過其 `.claude/commands/` 和 `.claude/agents/` 資料夾。[來自其他目錄的 Skills](/docs/zh-TW/skills#skills-from-additional-directories) 涵蓋載入和不載入的內容。

44 44

hooks.md +11 −13

Details

259您定義 hook 的位置決定了其範圍：259您定義 hook 的位置決定了其範圍：

260 260

261| 位置 | 範圍 | 可共享 |261| 位置 | 範圍 | 可共享 |

262| :------------------------------------------ | :------------------------------------------------------------------------ | :------------------------------------ |262| :--------------------------------------------------- | :------------------------------------------------------------------------ | :------------------------------------ |

270 270

271[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 上的雲端工作階段不會讀取您的本機 `~/.claude/settings.json`；那裡的 hooks 來自儲存庫的 `.claude/settings.json`（在具有一個儲存庫的工作階段中）、從您的 claude.ai 帳戶 [同步的外掛程式](/docs/zh-TW/plugins-reference#synced-plugins)，以及您組織的伺服器管理設定。在 [自託管環境](/docs/zh-TW/self-hosted-environments-configuration#permissions-and-tool-approval) 中，Claude Code 也執行操作員從執行器主機的 `~/.claude/` 中植入的 hooks，並在該檔案位於 [Claude Code 應用的受管理來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources) 中時執行執行器映像的受管理設定檔中的 hooks，預設情況下僅當伺服器管理設定或 MDM 傳遞的 Claude Code 原則都不提供受管理層級時。請參閱 [您的設定中哪些內容會轉移到雲端工作階段](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 以了解哪些檔案到達雲端工作階段。271[雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 不會讀取您的本機 `~/.claude/settings.json`。在 [自託管環境](/docs/zh-TW/self-hosted-environments-configuration#permissions-and-tool-approval) 中，Claude Code 也執行操作員從執行器主機的 `~/.claude/` 中植入的 hooks，並在該檔案位於 [Claude Code 應用的受管理來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources) 中時執行執行器映像的受管理設定檔中的 hooks，預設情況下僅當伺服器管理設定或 MDM 傳遞的 Claude Code 原則都不提供受管理層級時。請參閱 [您的設定中哪些內容會轉移到雲端工作階段](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 以了解哪些設定檔和外掛程式，以及因此哪些 hooks，到達雲端工作階段。

272 272

273有關設定檔解析的詳細資訊，請參閱 [settings](/docs/zh-TW/settings)。273有關設定檔解析的詳細資訊，請參閱 [settings](/docs/zh-TW/settings)。

274 274

278 278

279* 您的使用者、專案、本機和外掛程式 hooks 被阻止。在受管理設定 `enabledPlugins` 中強制啟用的外掛程式的 Hooks 是例外279* 您的使用者、專案、本機和外掛程式 hooks 被阻止。在受管理設定 `enabledPlugins` 中強制啟用的外掛程式的 Hooks 是例外

280* Claude Code 也將您的 [`statusLine`](/docs/zh-TW/statusline)、[`fileSuggestion`](/docs/zh-TW/settings-reference#filesuggestion) 和 [`subagentStatusLine`](/docs/zh-TW/statusline#subagent-status-lines) 設定縮小到受管理設定280* Claude Code 也將您的 [`statusLine`](/docs/zh-TW/statusline)、[`fileSuggestion`](/docs/zh-TW/settings-reference#filesuggestion) 和 [`subagentStatusLine`](/docs/zh-TW/statusline#subagent-status-lines) 設定縮小到受管理設定

281* Claude Code 也停用具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources) 的外掛程式，包括在受管理設定 `enabledPlugins` 中強制啟用的外掛程式，除非 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) 明確設定為 `false`。`command` 來源需要 Claude Code v2.1.229 或更新版本281* Claude Code 也停用具有 [`command` 來源](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source) 的外掛程式，包括在受管理設定 `enabledPlugins` 中強制啟用的外掛程式，除非 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) 明確設定為 `false`。`command` 來源需要 Claude Code v2.1.229 或更新版本

282* Claude Code 也阻止市場 [`headersHelper` 命令](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) 明確設定為 `false`，除了受管理設定本身宣告的市場282* Claude Code 也阻止市場 [`headersHelper` 命令](/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) 明確設定為 `false`，除了受管理設定本身宣告的市場

283 283

284請參閱 [在 `allowManagedHooksOnly` 下執行的內容](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)。284請參閱 [在 `allowManagedHooksOnly` 下執行的內容](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)。

285 285

304 304

305在正規表達式路徑上的匹配器使用 JavaScript 的 `RegExp.prototype.test` 進行測試，該測試在值中任何位置的匹配時成功。`Edit.*` 匹配 `Edit` 和 `NotebookEdit`；當您需要整個字串匹配時，用 `^` 和 `$` 包裝模式，如 `^Edit$`。305在正規表達式路徑上的匹配器使用 JavaScript 的 `RegExp.prototype.test` 進行測試，該測試在值中任何位置的匹配時成功。`Edit.*` 匹配 `Edit` 和 `NotebookEdit`；當您需要整個字串匹配時，用 `^` 和 `$` 包裝模式，如 `^Edit$`。

306 306

307逗號分隔符和周圍空格容差需要 Claude Code v2.1.191 或更新版本。

~~308~~

309精確匹配集中的連字號需要 Claude Code v2.1.195 或更新版本。在較早的版本上，像 `code-reviewer` 這樣的連字號名稱被評估為未錨定的正規表達式，因此它也會針對 `senior-code-reviewer` 觸發；在這些版本上將其錨定為 `^code-reviewer$` 以僅匹配該名稱。307精確匹配集中的連字號需要 Claude Code v2.1.195 或更新版本。在較早的版本上，像 `code-reviewer` 這樣的連字號名稱被評估為未錨定的正規表達式，因此它也會針對 `senior-code-reviewer` 觸發；在這些版本上將其錨定為 `^code-reviewer$` 以僅匹配該名稱。

310 308

516 514

517兩種形式都支援相同的 [路徑佔位符](#reference-scripts-by-path)，並且都將它們作為環境變數 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA` 匯出到生成的程序，因此指令碼可以讀取 `process.env.CLAUDE_PLUGIN_ROOT`，無論它是如何啟動的。515兩種形式都支援相同的 [路徑佔位符](#reference-scripts-by-path)，並且都將它們作為環境變數 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA` 匯出到生成的程序，因此指令碼可以讀取 `process.env.CLAUDE_PLUGIN_ROOT`，無論它是如何啟動的。

518 516

519外掛程式 hooks 另外替換 [`${user_config.*}`](/docs/zh-TW/plugins-reference#user-configuration) 值，僅在 exec 形式中：該值被替換為 `command` 和每個 `args` 元素中的純字串，因此沒有 shell 重新解析它。517外掛程式 hooks 另外替換 [`${user_config.*}`](/docs/zh-TW/plugins/manifest-reference#user-configuration) 值，僅在 exec 形式中：該值被替換為 `command` 和每個 `args` 元素中的純字串，因此沒有 shell 重新解析它。

520 518

521shell 形式的外掛程式 hook，其 `command` 參考 `${user_config.*}` 會失敗並出現 [錯誤](/docs/zh-TW/errors#plugin-command-references-user-config)，而不是執行。要在 shell 形式的 hook 中使用選項值，請讀取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數，例如 `webhook_url` 選項的 `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL`，或設定 `args` 以將 hook 切換到 exec 形式。在 v2.1.207 之前，shell 形式的外掛程式 hook 命令也替換了 `${user_config.*}`。519shell 形式的外掛程式 hook，其 `command` 參考 `${user_config.*}` 會失敗並出現 [錯誤](/docs/zh-TW/errors#plugin-command-references-user-config)，而不是執行。要在 shell 形式的 hook 中使用選項值，請讀取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數，例如 `webhook_url` 選項的 `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL`，或設定 `args` 以將 hook 切換到 exec 形式。在 v2.1.207 之前，shell 形式的外掛程式 hook 命令也替換了 `${user_config.*}`。

522 520

647使用這些佔位符按相對於專案或外掛程式根目錄的路徑參考 hook 指令碼，無論 hook 執行時的工作目錄如何：645使用這些佔位符按相對於專案或外掛程式根目錄的路徑參考 hook 指令碼，無論 hook 執行時的工作目錄如何：

648 646

649* `${CLAUDE_PROJECT_DIR}`：工作階段開始的專案根目錄。Claude Code 也在 [stdio MCP 伺服器](/docs/zh-TW/mcp#option-3-add-a-local-stdio-server) 和外掛程式 LSP 伺服器的環境中設定此變數。647* `${CLAUDE_PROJECT_DIR}`：工作階段開始的專案根目錄。Claude Code 也在 [stdio MCP 伺服器](/docs/zh-TW/mcp#option-3-add-a-local-stdio-server) 和外掛程式 LSP 伺服器的環境中設定此變數。

650* `${CLAUDE_PLUGIN_ROOT}`：外掛程式的安裝目錄，用於與 [plugin](/docs/zh-TW/plugins) 一起打包的指令碼。請參閱 [外掛程式環境變數](/docs/zh-TW/plugins-reference#environment-variables) 以了解路徑在更新中的行為。648* `${CLAUDE_PLUGIN_ROOT}`：外掛程式的安裝目錄，用於與 [plugin](/docs/zh-TW/plugins/overview) 一起打包的指令碼。請參閱 [外掛程式環境變數](/docs/zh-TW/plugins/manifest-reference#environment-variables) 以了解路徑在更新中的行為。

651* `${CLAUDE_PLUGIN_DATA}`：外掛程式的 [持久資料目錄](/docs/zh-TW/plugins-reference#persistent-data-directory)，用於應該在外掛程式更新後保留的依賴項和狀態。649* `${CLAUDE_PLUGIN_DATA}`：外掛程式的 [持久資料目錄](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)，用於應該在外掛程式更新後保留的依賴項和狀態。

652 650

653<Note>651<Note>

654 **Worktrees 不同。** 如果 Claude 在工作階段期間進入 [worktree](/docs/zh-TW/worktrees)，Claude Code 將 `${CLAUDE_PROJECT_DIR}` 保留在原位，並以不同的方式將 worktree 路徑傳遞給您的 hooks：652 **Worktrees 不同。** 如果 Claude 在工作階段期間進入 [worktree](/docs/zh-TW/worktrees)，Claude Code 將 `${CLAUDE_PROJECT_DIR}` 保留在原位，並以不同的方式將 worktree 路徑傳遞給您的 hooks：

709 }707 }

710 ```708 ```

711 709

712 有關建立外掛程式 hooks 的詳細資訊，請參閱 [外掛程式元件參考](/docs/zh-TW/plugins-reference#hooks)。710 有關建立外掛程式 hooks 的詳細資訊，請參閱 [外掛程式元件參考](/docs/zh-TW/plugins/components#hooks)。

713 </Tab>711 </Tab>

714</Tabs>712</Tabs>

715 713

1351 1349

1352成功時，`--init-only` 不會列印任何內容到終端。若要確認 hooks 已執行，請使用 `claude --debug-file <path> --init-only` 啟動，將 `<path>` 替換為日誌檔案位置，並檢查日誌中的 Setup 和 SessionStart hook 項目。1350成功時，`--init-only` 不會列印任何內容到終端。若要確認 hooks 已執行，請使用 `claude --debug-file <path> --init-only` 啟動，將 `<path>` 替換為日誌檔案位置，並檢查日誌中的 Setup 和 SessionStart hook 項目。

1353 1351

1354由於 Setup 不會在每次啟動時觸發，需要安裝相依性的外掛無法僅依賴 Setup。實用的模式是在首次使用時檢查相依性，如果缺少則安裝，例如測試 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在則執行 `npm install`。請參閱 [持久資料目錄](/docs/zh-TW/plugins-reference#persistent-data-directory)，了解在何處儲存已安裝的相依性。如果您透過市場發佈外掛，您可能不需要此模式：Claude Code [在快取外掛時自動安裝符合條件的 Node.js 套件相依性](/docs/zh-TW/plugins-reference#node-js-package-dependencies)。1352由於 Setup 不會在每次啟動時觸發，需要安裝相依性的外掛無法僅依賴 Setup。實用的模式是在首次使用時檢查相依性，如果缺少則安裝，例如測試 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在則執行 `npm install`。請參閱 [持久資料目錄](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)，了解在何處儲存已安裝的相依性。如果您透過市場發佈外掛，您可能不需要此模式：Claude Code [在快取外掛時自動安裝符合條件的 Node.js 套件相依性](/docs/zh-TW/plugins/loading#node-js-package-dependencies)。

1355 1353

1356<h4 id="setup-input">1354<h4 id="setup-input">

1357 Setup 輸入1355 Setup 輸入

2530 2528

2531在 Claude 使用 Agent 工具生成子代理時執行，當 Claude [恢復子代理](/docs/zh-TW/sub-agents#resume-subagents) 時，以及每次進程內 [agent team](/docs/zh-TW/agent-teams) 隊友處理新訊息時執行。支援匹配器以按代理類型名稱篩選。對於內建代理，這是代理名稱，例如 `general-purpose`、`Explore` 或 `Plan`。對於 [自訂子代理](/docs/zh-TW/sub-agents)，這是代理 frontmatter 中的 `name` 欄位，而不是檔案名稱。2529在 Claude 使用 Agent 工具生成子代理時執行，當 Claude [恢復子代理](/docs/zh-TW/sub-agents#resume-subagents) 時，以及每次進程內 [agent team](/docs/zh-TW/agent-teams) 隊友處理新訊息時執行。支援匹配器以按代理類型名稱篩選。對於內建代理，這是代理名稱，例如 `general-purpose`、`Explore` 或 `Plan`。對於 [自訂子代理](/docs/zh-TW/sub-agents)，這是代理 frontmatter 中的 `name` 欄位，而不是檔案名稱。

2532 2530

2533對於由 [外掛](/docs/zh-TW/plugins) 提供的子代理，代理類型是外掛範圍的識別碼，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名稱。冒號將外掛範圍的名稱放在正規表達式路徑上，因此使用 `^` 和 `$` 錨定匹配器以進行精確匹配：`^my-plugin:reviewer$`。2531對於由 [外掛](/docs/zh-TW/plugins/overview) 提供的子代理，代理類型是外掛範圍的識別碼，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名稱。冒號將外掛範圍的名稱放在正規表達式路徑上，因此使用 `^` 和 `$` 錨定匹配器以進行精確匹配：`^my-plugin:reviewer$`。

2534 2532

2535<h4 id="subagentstart-input">2533<h4 id="subagentstart-input">

2536 SubagentStart 輸入2534 SubagentStart 輸入

hooks-guide.md +4 −4

Details

10 10

11對於需要判斷而不是確定性規則的決策，您也可以使用[基於提示的 hooks](#prompt-based-hooks) 或[基於代理的 hooks](#agent-based-hooks)，它們使用 Claude 模型來評估條件。11對於需要判斷而不是確定性規則的決策，您也可以使用[基於提示的 hooks](#prompt-based-hooks) 或[基於代理的 hooks](#agent-based-hooks)，它們使用 Claude 模型來評估條件。

12 12

13有關擴展 Claude Code 的其他方式，請參閱[skills](/docs/zh-TW/skills)以提供 Claude 額外的指令和可執行命令、[subagents](/docs/zh-TW/sub-agents)以在隔離的上下文中執行任務，以及[plugins](/docs/zh-TW/plugins)以打包要在專案間共享的擴展。13有關擴展 Claude Code 的其他方式，請參閱[skills](/docs/zh-TW/skills)以提供 Claude 額外的指令和可執行命令、[subagents](/docs/zh-TW/sub-agents)以在隔離的上下文中執行任務，以及[plugins](/docs/zh-TW/plugins/overview)以打包要在專案間共享的擴展。

14 14

15<Tip>15<Tip>

16 本指南涵蓋常見用例和入門方式。有關完整的事件架構、JSON 輸入/輸出格式和非同步 hooks 和 MCP 工具 hooks 等進階功能，請參閱 [Hooks 參考](/docs/zh-TW/hooks)。16 本指南涵蓋常見用例和入門方式。有關完整的事件架構、JSON 輸入/輸出格式和非同步 hooks 和 MCP 工具 hooks 等進階功能，請參閱 [Hooks 參考](/docs/zh-TW/hooks)。

710}710}

711```711```

712 712

713`"Edit|Write"` 匹配器只在 Claude 使用 `Edit` 或 `Write` 工具時觸發，而不是在它使用 `Bash`、`Read` 或任何其他工具時。在 Claude Code v2.1.191 或更新版本上，逗號以相同方式分隔替代項，因此 `"Edit, Write"` 是等效的。請參閱 [Matcher patterns](/docs/zh-TW/hooks#matcher-patterns) 以了解純名稱和正規表達式如何被評估。713`"Edit|Write"` 匹配器只在 Claude 使用 `Edit` 或 `Write` 工具時觸發，而不是在它使用 `Bash`、`Read` 或任何其他工具時。逗號以相同方式分隔替代項，因此 `"Edit, Write"` 是等效的。請參閱 [Matcher patterns](/docs/zh-TW/hooks#matcher-patterns) 以了解純名稱和正規表達式如何被評估。

714 714

715<Note>715<Note>

716 Claude 也可以透過執行 shell 命令來建立或修改檔案。如果您的 hook 必須看到每個檔案變更（例如用於合規掃描或稽核日誌），請新增一個 [`Stop`](/docs/zh-TW/hooks#stop) hook，它每輪掃描一次工作樹。為了獲得每次呼叫的覆蓋範圍，也請匹配 `Bash|PowerShell` 並讓您的指令使用 `git status --porcelain` 列出修改和未追蹤的檔案。[PowerShell hook input section](/docs/zh-TW/hooks#powershell) 解釋了為什麼單獨匹配 `Bash` 是不夠的。若要在特定檔案在磁碟上變更時執行 hook（無論是什麼寫入它），請使用 [FileChanged](/docs/zh-TW/hooks#filechanged) hook。716 Claude 也可以透過執行 shell 命令來建立或修改檔案。如果您的 hook 必須看到每個檔案變更（例如用於合規掃描或稽核日誌），請新增一個 [`Stop`](/docs/zh-TW/hooks#stop) hook，它每輪掃描一次工作樹。為了獲得每次呼叫的覆蓋範圍，也請匹配 `Bash|PowerShell` 並讓您的指令使用 `git status --porcelain` 列出修改和未追蹤的檔案。[PowerShell hook input section](/docs/zh-TW/hooks#powershell) 解釋了為什麼單獨匹配 `Bash` 是不夠的。若要在特定檔案在磁碟上變更時執行 hook（無論是什麼寫入它），請使用 [FileChanged](/docs/zh-TW/hooks#filechanged) hook。

861您新增 hook 的位置決定了其範圍：861您新增 hook 的位置決定了其範圍：

862 862

863| 位置 | 範圍 | 可共享 |863| 位置 | 範圍 | 可共享 |

864| :------------------------------------------ | :----------------------------------------------------------------------------------------------- | :------------------------------ |864| :--------------------------------------------------- | :----------------------------------------------------------------------------------------------- | :------------------------------ |

872 872

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

Details

45內建工具通常分為五個類別，每個類別代表不同類型的代理能力。45內建工具通常分為五個類別，每個類別代表不同類型的代理能力。

46 46

47| 類別 | Claude 可以做什麼 |47| 類別 | Claude 可以做什麼 |

~~48| --------- | --------------------------------------------------------------------------------- |~~48| --------- | ------------------------------------------------------------------------ |

49| **檔案操作** | 讀取檔案、編輯程式碼、建立新檔案、重新命名和重新組織 |49| **檔案操作** | 讀取檔案、編輯程式碼、建立新檔案、重新命名和重新組織 |

50| **搜尋** | 按模式查找檔案、使用正規表達式搜尋內容、探索程式碼庫 |50| **搜尋** | 按模式查找檔案、使用正規表達式搜尋內容、探索程式碼庫 |

51| **執行** | 執行 shell 命令、啟動伺服器、執行測試、使用 git |51| **執行** | 執行 shell 命令、啟動伺服器、執行測試、使用 git |

52| **網路** | 搜尋網路、擷取文件、查詢錯誤訊息 |52| **網路** | 搜尋網路、擷取文件、查詢錯誤訊息 |

~~53| **程式碼智能** | 編輯後查看類型錯誤和警告、跳轉到定義、查找參考（需要[程式碼智能外掛程式](/docs/zh-TW/discover-plugins#code-intelligence)） |~~53| **程式碼智能** | 編輯後查看類型錯誤和警告、跳轉到定義、查找參考（需要[程式碼智能外掛程式](/docs/zh-TW/plugins/code-intelligence)） |

54 54

55這些是主要功能。Claude 還具有用於生成 subagents、詢問您問題和其他編排任務的工具。請參閱[Claude 可用的工具](/docs/zh-TW/tools-reference)以取得完整清單。55這些是主要功能。Claude 還具有用於生成 subagents、詢問您問題和其他編排任務的工具。請參閱[Claude 可用的工具](/docs/zh-TW/tools-reference)以取得完整清單。

56 56

interactive-mode.md +11 −6

Details

21</h3>21</h3>

22 22

23| 快捷鍵 | 說明 | 內容 |23| 快捷鍵 | 說明 | 內容 |

24| :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |24| :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

26| `Ctrl+X Ctrl+K` | 停止此工作階段中所有執行中的[背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)，並關閉[成品自動回覆](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)以供其餘工作階段使用。在 3 秒內按兩次以確認 | 子代理控制 |26| `Ctrl+X Ctrl+K` | 停止此工作階段中所有執行中的[背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)，並關閉[成品自動回覆](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)以供其餘工作階段使用。在 3 秒內按兩次以確認 | 子代理控制 |

38| `Tab` | 接受自動完成建議，或在權限答案中新增註解 | 當自動完成建議在提示輸入中顯示時，接受選定的建議。在大多數權限提示上，當**是**或**否**獲得焦點時，會在該選項上開啟註解欄位，再次按下會關閉欄位。請參閱[在您回答權限提示時新增註解](/docs/zh-TW/permissions#add-a-comment-when-you-answer-a-permission-prompt) |38| `Tab` | 接受自動完成建議，或在權限答案中新增註解 | 當自動完成建議在提示輸入中顯示時，接受選定的建議。在大多數權限提示上，當**是**或**否**獲得焦點時，會在該選項上開啟註解欄位，再次按下會關閉欄位。請參閱[在您回答權限提示時新增註解](/docs/zh-TW/permissions#add-a-comment-when-you-answer-a-permission-prompt) |

39| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移動游標或導覽命令歷史記錄 | 當輸入跨越多個視覺行時（無論是換行還是多行），首先在提示內移動游標。一旦游標在第一行或最後一行視覺行上，再次按下會導覽命令歷史記錄。當您有訊息排隊時，從第一行按 `Up` 會改為[取回您排隊的內容](#take-back-what-you-queued) |39| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移動游標或導覽命令歷史記錄 | 當輸入跨越多個視覺行時（無論是換行還是多行），首先在提示內移動游標。一旦游標在第一行或最後一行視覺行上，再次按下會導覽命令歷史記錄。當您有訊息排隊時，從第一行按 `Up` 會改為[取回您排隊的內容](#take-back-what-you-queued) |

40| `Esc` | 中斷 Claude 或關閉對話框 | 停止目前的回應或工具呼叫中途，以便您可以重新導向。Claude 會保留迄今為止完成的工作。如果您有[訊息排隊](#queue-messages-while-claude-works)，Claude Code 會在下一步傳送它們。當對話框開啟時，`Esc` 會關閉對話框。在權限提示上，`Esc` 會拒絕該操作，與[**否**（不含註解）](/docs/zh-TW/permissions#add-a-comment-when-you-answer-a-permission-prompt)相同 |40| `Esc` | 中斷 Claude 或關閉對話框 | 停止目前的回應或工具呼叫中途，以便您可以重新導向。Claude 會保留迄今為止完成的工作。如果您有[訊息排隊](#queue-messages-while-claude-works)，Claude Code 會在下一步傳送它們。當對話框開啟時，`Esc` 會關閉對話框。在權限提示上，`Esc` 會拒絕該操作，與[**否**（不含註解）](/docs/zh-TW/permissions#add-a-comment-when-you-answer-a-permission-prompt)相同 |

42| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即傳送排隊的訊息 | 中斷目前的回合，以便您的[排隊訊息](#queue-messages-while-claude-works)和您的草稿與它們一起立即發出，而不是在回合結束時。在[shell 模式](#shell-mode-with-prefix)中，該鍵會將您的命令排隊而不中斷。在不報告延伸鍵的終端中，`Ctrl+Enter` 會以純 `Enter` 的形式到達；`Ctrl+X Ctrl+S` 在任何終端中都有效。需要 Claude Code v2.1.275 或更新版本 |42| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即傳送排隊的訊息 | 傳送您的[排隊訊息](#queue-messages-while-claude-works)和您的草稿與它們一起立即發出。[Claude Code 何時傳送您排隊的內容](#when-claude-code-sends-what-you-queued)涵蓋了 Claude 正在處理的回合會發生什麼。在[shell 模式](#shell-mode-with-prefix)中，該鍵只會將您的命令排隊。在不報告延伸鍵的終端中，`Ctrl+Enter` 會以純 `Enter` 的形式到達；`Ctrl+X Ctrl+S` 在任何終端中都有效。需要 Claude Code v2.1.275 或更新版本 |

43| `Shift+Tab` 或 `Alt+M`（當 Node 或 Bun 執行時間未啟用 VT 輸入模式時在 Windows 上） | 循環權限模式 | 循環通過 `default`（在模式指示器中標記為 Manual）、`acceptEdits`、`plan` 和（如果可用）`bypassPermissions`，然後是 `auto`。從 `auto`，第一次按下會切換到 `default`。請參閱[權限模式](/docs/zh-TW/permission-modes)。在檔案權限提示上，相同的鍵會關閉開啟的[註解欄位](/docs/zh-TW/permissions#add-a-comment-when-you-answer-a-permission-prompt)。沒有開啟欄位時，它會選擇允許該操作以供工作階段其餘部分的選項（當提示提供該選項時） |43| `Shift+Tab` 或 `Alt+M`（當 Node 或 Bun 執行時間未啟用 VT 輸入模式時在 Windows 上） | 循環權限模式 | 循環通過 `default`（在模式指示器中標記為 Manual）、`acceptEdits`、`plan` 和（如果可用）`bypassPermissions`，然後是 `auto`。從 `auto`，第一次按下會切換到 `default`。請參閱[權限模式](/docs/zh-TW/permission-modes)。在檔案權限提示上，相同的鍵會關閉開啟的[註解欄位](/docs/zh-TW/permissions#add-a-comment-when-you-answer-a-permission-prompt)。沒有開啟欄位時，它會選擇允許該操作以供工作階段其餘部分的選項（當提示提供該選項時） |

136 指令136 指令

137</h2>137</h2>

138 138

139在 Claude Code 中輸入 `/` 以查看可用的指令，或輸入 `/` 後跟任何字母來篩選。`/` 選單列出內建指令、捆綁和使用者撰寫的 [skills](/docs/zh-TW/skills)，以及由 [plugins](/docs/zh-TW/plugins) 和 [MCP servers](/docs/zh-TW/mcp#use-mcp-prompts-as-commands) 貢獻的指令。並非所有內建指令對每個使用者都可見，因為某些指令取決於您的平台或方案，而且 [某些可用指令在設計上隱藏在選單之外](/docs/zh-TW/commands#how-the-command-menu-matches-what-you-type)，當您輸入其完整名稱時會執行。139在 Claude Code 中輸入 `/` 以查看可用的指令，或輸入 `/` 後跟任何字母來篩選。`/` 選單列出內建指令、捆綁和使用者撰寫的 [skills](/docs/zh-TW/skills)，以及由 [plugins](/docs/zh-TW/plugins/overview) 和 [MCP servers](/docs/zh-TW/mcp#use-mcp-prompts-as-commands) 貢獻的指令。並非所有內建指令對每個使用者都可見，因為某些指令取決於您的平台或方案，而且 [某些可用指令在設計上隱藏在選單之外](/docs/zh-TW/commands#how-the-command-menu-matches-what-you-type)，當您輸入其完整名稱時會執行。

140 140

141在 [全螢幕呈現](/docs/zh-TW/fullscreen#use-the-mouse) 中，`/` 指令和 `@` 檔案建議清單也會回應滑鼠：懸停會反白一列，點擊會接受它。141在 [全螢幕呈現](/docs/zh-TW/fullscreen#use-the-mouse) 中，`/` 指令和 `@` 檔案建議清單也會回應滑鼠：懸停會反白一列，點擊會接受它。

142 142

408* 訊息：如果您在 Claude 執行工具呼叫時排隊訊息，Claude Code 會在這些工具呼叫完成後立即將其傳遞給 Claude，在同一輪次內。當輪次結束時仍有訊息排隊，它們會在沒有另一次按鍵的情況下按照您輸入的順序傳出408* 訊息：如果您在 Claude 執行工具呼叫時排隊訊息，Claude Code 會在這些工具呼叫完成後立即將其傳遞給 Claude，在同一輪次內。當輪次結束時仍有訊息排隊，它們會在沒有另一次按鍵的情況下按照您輸入的順序傳出

409* 命令和 shell 命令：Claude Code 會保留它們直到輪次結束，然後逐個執行，保持您排隊的順序409* 命令和 shell 命令：Claude Code 會保留它們直到輪次結束，然後逐個執行，保持您排隊的順序

410 410

411若要在輪次完成前傳送您排隊的內容，請按 `Ctrl+Enter`。Claude Code 會中斷該輪次，您排隊的訊息會立即傳出，如果您已輸入草稿，您的草稿會排隊在後面。在 [shell 模式](#shell-mode-with-prefix)中，該快捷鍵會排隊您的命令而不中斷輪次。需要 Claude Code v2.1.275 或更新版本。411若要在不等待的情況下傳送您排隊的內容，請按 `Ctrl+Enter`。您排隊的訊息會立即傳出，如果您已輸入草稿，您的草稿會排隊在後面。需要 Claude Code v2.1.275 或更新版本。

412 412

413在不報告擴展鍵的終端中，`Ctrl+Enter` 會以純 `Enter` 的形式到達並排隊草稿；`Ctrl+X Ctrl+S` 在任何終端中都有效。兩個快捷鍵都是 [`chat:sendNow` 動作](/docs/zh-TW/keybindings#chat-actions)的繫結。413如果您在訊息前面排隊了 `!` shell 命令，該快捷鍵會中斷輪次。否則，輪次發生的情況取決於您按下快捷鍵時 Claude 正在執行的操作：

414

415* 執行 shell 命令、子代理或其他可以移至 [背景](#background-bash-commands)的工作：該工作會移至背景並繼續執行，Claude 會在同一輪次中讀取您的訊息

416* 僅寫入回應，或執行無法移至背景的操作：Claude Code 會中斷輪次並在下一步傳送您的訊息。在 v2.1.281 之前，該快捷鍵在兩種情況下都會中斷輪次

417

418在 [shell 模式](#shell-mode-with-prefix)中，該快捷鍵只會排隊您的命令。在不報告擴展鍵的終端中，`Ctrl+Enter` 會以純 `Enter` 的形式到達並排隊草稿；`Ctrl+X Ctrl+S` 在任何終端中都有效。兩個快捷鍵都是 [`chat:sendNow` 動作](/docs/zh-TW/keybindings#chat-actions)的繫結。

414 419

415按 `Esc` 以中斷輪次而不提交您的草稿。Claude Code 會保留您排隊的內容並立即傳送。420按 `Esc` 以中斷輪次而不提交您的草稿。Claude Code 會保留您排隊的內容並立即傳送。

416 421

keybindings.md +132 −116

Details

74在 v2.1.205 之前，`/doctor` 診斷螢幕存在 `Doctor` 上下文和 `doctor:fix` 動作。74在 v2.1.205 之前，`/doctor` 診斷螢幕存在 `Doctor` 上下文和 `doctor:fix` 動作。

75 75

76<h2 id="available-actions">76<h2 id="available-actions">

~~77 可用動作~~77 可用的動作

78</h2>78</h2>

79 79

80動作遵循 `namespace:action` 格式，例如 `chat:submit` 用於傳送訊息，或 `app:toggleTodos` 用於顯示工作清單。每個上下文都有特定的可用動作。80動作遵循 `namespace:action` 格式，例如 `chat:submit` 用於傳送訊息，或 `app:toggleTodos` 用於顯示工作清單。每個上下文都有特定的可用動作。

81 81

82<h3 id="app-actions">82<h3 id="app-actions">

~~83 應用程式動作~~83 App 動作

84</h3>84</h3>

85 85

86在 `Global` 上下文中可用的動作：86在 `Global` 上下文中可用的動作：

87 87

88| 動作 | 預設 | 說明 |88| 動作 | 預設 | 說明 |

~~89| :--------------------- | :----- | :-------------------------------------------------------- |~~89| :--------------------- | :----- | :---------------------------------------------------------- |

~~92| `app:redraw` | (未繫結) | 強制終端機重新繪製 |~~92| `app:redraw` | (未綁定) | 強制終端機重繪 |

95 95

96<h3 id="history-actions">96<h3 id="history-actions">

~~97 歷史記錄動作~~97 History 動作

98</h3>98</h3>

99 99

100用於導覽命令歷史記錄的動作：100用於導覽命令歷史記錄的動作：

107 107

108<h3 id="chat-actions">108<h3 id="chat-actions">

109 聊天動作109 Chat 動作

110</h3>110</h3>

111 111

112在 `Chat` 上下文中可用的動作：112在 `Chat` 上下文中可用的動作：

113 113

114| 動作 | 預設 | 說明 |114| 動作 | 預設 | 說明 |

115| :-------------------- | :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |115| :-------------------- | :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

119| `chat:killAgents` | Ctrl+X Ctrl+K | 停止此工作階段中所有執行中的[背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)，並關閉此工作階段其餘部分的[成品自動回覆](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own) |119| `chat:killAgents` | Ctrl+X Ctrl+K | 停止此工作階段中所有執行中的 [背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)，並關閉此工作階段其餘部分的 [成品自動回覆](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own) |

125| `chat:queueSubmit` | Ctrl+X Enter | 提交訊息，標記為等待其輪次：當 Claude 正在工作時，Claude Code [將其排隊](/docs/zh-TW/interactive-mode#queue-messages-while-claude-works)，永遠不會中斷輪次。與 `chat:submit` 不同，即使自動完成建議被醒目提示，它也會提交草稿。需要 v2.1.247 或更新版本 |125| `chat:queueSubmit` | Ctrl+X Enter | 提交訊息，標記為等待輪次：當 Claude 正在工作時，Claude Code [將其排隊](/docs/zh-TW/interactive-mode#queue-messages-while-claude-works)，永遠不會中斷輪次。與 `chat:submit` 不同，即使自動完成建議被突出顯示，它也會提交草稿。需要 v2.1.247 或更新版本 |

126| `chat:sendNow` | Ctrl+Enter, Ctrl+X Ctrl+S | 中斷執行中的輪次，使您的[排隊訊息](/docs/zh-TW/interactive-mode#queue-messages-while-claude-works)和您的草稿與它們一起立即發出。當沒有任何東西執行時，它會提交草稿，在[殼層模式](/docs/zh-TW/interactive-mode#shell-mode-with-prefix)中它會排隊命令而不中斷。不報告延伸按鍵的終端機會將 `Ctrl+Enter` 傳遞為純 `Enter`，因此 `Ctrl+X Ctrl+S` 是在任何終端機中都有效的繫結。需要 v2.1.275 或更新版本 |126| `chat:sendNow` | Ctrl+Enter, Ctrl+X Ctrl+S | 立即傳送您的 [排隊訊息](/docs/zh-TW/interactive-mode#queue-messages-while-claude-works) 和您的草稿。[Claude Code 傳送您排隊的內容時](/docs/zh-TW/interactive-mode#when-claude-code-sends-what-you-queued) 涵蓋了 Claude 正在處理的輪次會發生什麼。當沒有任何操作執行時，該鍵會提交草稿，在 [shell 模式](/docs/zh-TW/interactive-mode#shell-mode-with-prefix) 中它只會排隊命令。不報告延伸鍵的終端機會將 `Ctrl+Enter` 傳遞為純 `Enter`，因此 `Ctrl+X Ctrl+S` 是在任何終端機中都能運作的綁定。需要 v2.1.275 或更新版本 |

132 132

133\*在沒有 VT 模式的 Windows 上（Node \<24.2.0/\<22.17.0、Bun \<1.2.23），預設為 Meta+M。133\*在沒有 VT 模式的 Windows 上 (Node \<24.2.0/\<22.17.0, Bun \<1.2.23)，預設為 Meta+M。

134 134

135<h3 id="autocomplete-actions">135<h3 id="autocomplete-actions">

136 自動完成動作136 Autocomplete 動作

137</h3>137</h3>

138 138

139在 `Autocomplete` 上下文中可用的動作：139在 `Autocomplete` 上下文中可用的動作：

147 147

148<h3 id="confirmation-actions">148<h3 id="confirmation-actions">

149 確認動作149 Confirmation 動作

150</h3>150</h3>

151 151

152在 `Confirmation` 上下文中可用的動作：152在 `Confirmation` 上下文中可用的動作：

153 153

154| 動作 | 預設 | 說明 |154| 動作 | 預設 | 說明 |

155| :---------------------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------- |155| :---------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------- |

158| `confirm:previous` | Up | 上一個選項 |158| `confirm:previous` | Up | 上一個選項 |

160| `confirm:nextField` | Tab | 下一個欄位 |160| `confirm:nextField` | Tab | 下一個欄位 |

161| `confirm:previousField` | (未繫結) | 上一個欄位 |161| `confirm:previousField` | (未綁定) | 上一個欄位 |

163| `confirm:cycleMode` | Shift+Tab\* | 循環權限模式。在檔案權限提示上，關閉開啟的[評論欄位](/docs/zh-TW/permissions#add-a-comment-when-you-answer-a-permission-prompt)；沒有開啟的欄位時，選擇允許此工作階段其餘部分動作的選項（當提示提供該選項時） |163| `confirm:cycleMode` | Shift+Tab\* | 循環權限模式。在檔案權限提示上，關閉開啟的 [評論欄位](/docs/zh-TW/permissions#add-a-comment-when-you-answer-a-permission-prompt)；沒有開啟的欄位時，選擇允許此工作階段其餘部分的動作的選項，當提示提供該選項時 |

164 164

165\*在沒有 VT 模式的 Windows 上（Node \<24.2.0/\<22.17.0、Bun \<1.2.23），預設為 Meta+M。165\*在沒有 VT 模式的 Windows 上 (Node \<24.2.0/\<22.17.0, Bun \<1.2.23)，預設為 Meta+M。

166 166

167在 v2.1.257 之前，`confirm:toggleExplanation` 動作（預設繫結到 `Ctrl+E`）在 Bash 和 PowerShell 權限提示上顯示模型產生的命令說明。167在 v2.1.257 之前，`confirm:toggleExplanation` 動作綁定到 `Ctrl+E`，預設情況下在 Bash 和 PowerShell 權限提示上顯示模型生成的命令說明。

168 168

169對話框使用 `confirm:yes` 和 `confirm:no` 來接受和取消，即使它們不提出是或否的問題。如果您在此上下文中繫結裸字母（例如 `y` 或 `n`），該字母也會作用於從不將其顯示為按鍵的對話框。顯示 `y` 和 `n` 作為其按鍵的對話框會自行讀取這些字母，不需要繫結。169對話框使用 `confirm:yes` 和 `confirm:no` 來接受和取消，即使它們不提出是或否的問題。如果您在此上下文中綁定裸字母（例如 `y` 或 `n`），該字母也會作用於從不將其顯示為鍵的對話框。顯示 `y` 和 `n` 作為其鍵的對話框會自行讀取這些字母，不需要綁定。

170 170

171此範例將 `y` 繫結到 `confirm:yes`，將 `n` 繫結到 `confirm:no`：171此範例將 `y` 綁定到 `confirm:yes`，將 `n` 綁定到 `confirm:no`：

172 172

173```json theme={null}173```json theme={null}

174{174{

184}184}

185```185```

186 186

187在 v2.1.280 之前，`y` 也預設繫結到 `confirm:yes`，`n` 繫結到 `confirm:no`。如果您在 v2.1.280 之前使用 `/keybindings` 建立了 `keybindings.json`，該檔案會列出兩個繫結，它們會保持有效，直到您刪除這兩行。187使用這些綁定，當 [文字欄位](#text-fields) 有焦點時，`y` 和 `n` 仍然會輸入為字母。

188

189在 v2.1.280 之前，`y` 也預設綁定到 `confirm:yes`，`n` 綁定到 `confirm:no`。如果您在 v2.1.280 之前使用 `/keybindings` 建立了 `keybindings.json`，該檔案會列出兩個綁定，它們會保持有效，直到您刪除這兩行。

188 190

189<h3 id="permission-actions">191<h3 id="permission-actions">

190 權限動作192 Permission 動作

191</h3>193</h3>

192 194

193在 `Confirmation` 上下文中可用於權限對話框的動作：195在 `Confirmation` 上下文中可用於權限對話框的動作：

194 196

195| 動作 | 預設 | 說明 |197| 動作 | 預設 | 說明 |

196| :----------------------- | :---- | :------------------------------------------------------ |198| :----------------------- | :---- | :------------------------------------------------------ |

197| `permission:toggleDebug` | (未繫結) | 切換權限偵錯資訊。v2.1.146 中移除了先前的 Ctrl+D 預設值，因為它與 `app:exit` 衝突 |199| `permission:toggleDebug` | (未綁定) | 切換權限偵錯資訊。Ctrl+D 的先前預設值在 v2.1.146 中被移除，因為它遮蔽了 `app:exit` |

198 200

199<h3 id="transcript-actions">201<h3 id="transcript-actions">

200 文字記錄動作202 Transcript 動作

201</h3>203</h3>

202 204

203在 `Transcript` 上下文中可用的動作：205在 `Transcript` 上下文中可用的動作：

209 211

210`transcript:toggleShowAll` 僅適用於經典渲染器；在[全螢幕渲染](/docs/zh-TW/fullscreen)中，文字記錄檢視器不提供顯示全部切換。212`transcript:toggleShowAll` 僅適用於經典轉譯器；在 [全螢幕轉譯](/docs/zh-TW/fullscreen) 中，文字記錄檢視器不提供顯示全部切換。

211 213

212<h3 id="history-search-actions">214<h3 id="history-search-actions">

213 歷史記錄搜尋動作215 History search 動作

214</h3>216</h3>

215 217

216在 `HistorySearch` 上下文中可用的動作：218在 `HistorySearch` 上下文中可用的動作：

217 219

218| 動作 | 預設 | 說明 |220| 動作 | 預設 | 說明 |

219| :------------------------- | :---------- | :---------------- |221| :------------------------- | :---------- | :---------------- |

225 227

226`historySearch:next`、`historySearch:accept`、`historySearch:cancel` 和 `historySearch:execute` 預設值適用於經典渲染器中的內嵌歷史記錄搜尋，它始終搜尋來自所有專案的提示。`historySearch:cycleScope` 僅在[全螢幕渲染](/docs/zh-TW/fullscreen)中生效，其中 `Ctrl+R` 開啟搜尋對話框，`Ctrl+S` 循環其範圍。對話框的其他按鍵是固定的，無法重新繫結：`Enter` 或 `Tab` 將醒目提示的符合項目放在提示輸入中，`Esc` 取消。228`historySearch:next`、`historySearch:accept`、`historySearch:cancel` 和 `historySearch:execute` 預設值適用於經典轉譯器中的內嵌歷史記錄搜尋，它始終搜尋來自所有專案的提示。`historySearch:cycleScope` 僅在 [全螢幕轉譯](/docs/zh-TW/fullscreen) 中生效，其中 `Ctrl+R` 開啟搜尋對話框，`Ctrl+S` 循環其範圍。對話框的其他鍵是固定的，無法重新綁定：`Enter` 或 `Tab` 將突出顯示的符合項放在提示輸入中，`Esc` 取消。

227 229

228<h3 id="task-actions">230<h3 id="task-actions">

229 工作動作231 Task 動作

230</h3>232</h3>

231 233

232在 `Task` 上下文中可用的動作：234在 `Task` 上下文中可用的動作：

233 235

234| 動作 | 預設 | 說明 |236| 動作 | 預設 | 說明 |

235| :---------------- | :-------------------- | :------------------------------------- |237| :---------------- | :-------------------- | :------------------------------------- |

237 239

238<h3 id="theme-actions">240<h3 id="theme-actions">

239 主題動作241 Theme 動作

240</h3>242</h3>

241 243

242在 `ThemePicker` 上下文中可用的動作：244在 `ThemePicker` 上下文中可用的動作：

247 249

248<h3 id="help-actions">250<h3 id="help-actions">

249 說明動作251 Help 動作

250</h3>252</h3>

251 253

252在 `Help` 上下文中可用的動作：254在 `Help` 上下文中可用的動作：

268 270

269<h3 id="attachments-actions">271<h3 id="attachments-actions">

270 附件動作272 Attachments 動作

271</h3>273</h3>

272 274

273在 `Attachments` 上下文中可用的動作：275在 `Attachments` 上下文中可用的動作：

281 283

282<h3 id="footer-actions">284<h3 id="footer-actions">

283 頁尾動作285 Footer 動作

284</h3>286</h3>

285 287

286在 `Footer` 上下文中可用的動作：288在 `Footer` 上下文中可用的動作：

287 289

288| 動作 | 預設 | 說明 |290| 動作 | 預設 | 說明 |

289| :---------------------- | :---------------- | :----------------------------------------------------------------------------- |291| :---------------------- | :---------------- | :------------------------------------------------------------------------------- |

292| `footer:up` | Up | 在頁尾中向上導覽（在頂部取消選擇） |294| `footer:up` | Up | 在頁尾中向上導覽（在頂部取消選擇） |

297 299

298當頁尾項目被選擇時（例如提示下方代理面板中的一列），`Enter` 會開啟它，即使您在 `Chat` 上下文中將 `Enter` 重新繫結到 `chat:queueSubmit` 或 `chat:newline`。300當選定頁尾項目時（例如提示下方代理面板中的列），即使您在 `Chat` 上下文中將 `Enter` 重新綁定到 `chat:queueSubmit` 或 `chat:newline`，`Enter` 也會開啟它。

299 301

300`Chat` 繫結在 `Footer` 上下文未繫結的按鍵上（例如 `chat:cycleMode` 的 `Shift+Tab`）在選擇項目時繼續有效。302`Chat` 在 `Footer` 上下文未綁定的鍵上的綁定（例如 `Shift+Tab` 用於 `chat:cycleMode`）在選定項目時保持有效。

301 303

302<h3 id="message-selector-actions">304<h3 id="message-selector-actions">

303 訊息選擇器動作305 Message selector 動作

304</h3>306</h3>

305 307

306在 `MessageSelector` 上下文中可用的動作：308在 `MessageSelector` 上下文中可用的動作：

309| :----------------------- | :---------------------------------------- | :------- |311| :----------------------- | :---------------------------------------- | :------- |

315 317

316<h3 id="diff-actions">318<h3 id="diff-actions">

321 323

322| 動作 | 預設 | 說明 |324| 動作 | 預設 | 說明 |

323| :-------------------- | :------ | :------------------------------------------------------------------------- |325| :-------------------- | :------ | :------------------------------------------------------------------------- |

327| `diff:previousFile` | Up, K | 檔案清單中的上一個檔案；在詳細資訊檢視中向上滾動一行 |329| `diff:previousFile` | Up, K | 檔案清單中的上一個檔案；在詳細檢視中向上捲動一行 |

330| `diff:back` | (未繫結) | 在差異檢視器中返回。Escape 透過 `diff:dismiss` 執行返回動作。v2.1.203 中移除了詳細資訊檢視中先前的 Left 預設值 |332| `diff:back` | (未綁定) | 在差異檢視器中返回。Escape 透過 `diff:dismiss` 執行返回動作。詳細檢視中 Left 的先前預設值在 v2.1.203 中被移除 |

331 333

332差異詳細資訊檢視也會將分頁器風格的按鍵繫結到標準[滾動動作](#scroll-actions)。這些繫結是 `DiffDialog` 上下文的一部分，僅適用於詳細資訊檢視；[滾動動作](#scroll-actions)下列出的 `Scroll` 上下文預設值保持不變。334差異詳細檢視也將尋呼機樣式鍵綁定到標準 [捲動動作](#scroll-actions)。這些綁定是 `DiffDialog` 上下文的一部分，僅適用於詳細檢視；[捲動動作](#scroll-actions) 下列出的 `Scroll` 上下文預設值保持不變。

333 335

334| 動作 | 預設 | 說明 |336| 動作 | 預設 | 說明 |

335| :-------------------- | :------------- | :---------- |337| :-------------------- | :------------- | :-------- |

342 344

343<h3 id="diff-panel-actions">345<h3 id="diff-panel-actions">

344 Diff 面板動作346 Diff panel 動作

345</h3>347</h3>

346 348

347用於 `/diff` 在全螢幕渲染中開啟的 [diff 面板](/docs/zh-TW/interactive-mode#diff-panel) 的動作。`app:cycleDiffBase` 在 `DiffPanel` 上下文中，在面板開啟時有效；其他的在 `Global` 中。面板需要 Claude Code v2.1.260 或更新版本。349用於 [差異面板](/docs/zh-TW/interactive-mode#diff-panel) 的動作，`/diff` 在全螢幕轉譯中開啟。`app:cycleDiffBase` 在 `DiffPanel` 上下文中，在面板開啟時有效；其他的在 `Global` 中。該面板需要 Claude Code v2.1.260 或更新版本。

348 350

349| 動作 | 預設 | 說明 |351| 動作 | 預設 | 說明 |

350| :-------------------------- | :------------------- | :--------------------------- |352| :-------------------------- | :------------------- | :----------------------- |

351| `app:toggleReplTab` | (未繫結) | 開啟或關閉 diff 面板，與執行 `/diff` 相同 |353| `app:toggleReplTab` | (未綁定) | 開啟或關閉差異面板，與執行 `/diff` 相同 |

355| `app:toggleDiffNoiseFilter` | (未繫結) | 在面板中顯示或隱藏測試和產生的檔案 |357| `app:toggleDiffNoiseFilter` | (未綁定) | 在面板中顯示或隱藏測試和生成的檔案 |

356| `app:toggleDiffPreSession` | (未繫結) | 展開或摺疊此工作階段之前的變更 |358| `app:toggleDiffPreSession` | (未綁定) | 展開或摺疊此工作階段之前的變更 |

357 359

358<h3 id="model-picker-actions">360<h3 id="model-picker-actions">

359 模型選擇器動作361 Model picker 動作

360</h3>362</h3>

361 363

362在 `ModelPicker` 上下文中可用的動作：364在 `ModelPicker` 上下文中可用的動作：

363 365

364| 動作 | 預設 | 說明 |366| 動作 | 預設 | 說明 |

365| :---------------------------- | :---- | :--------------- |367| :---------------------------- | :---- | :--------------- |

368| `modelPicker:thisSessionOnly` | s | 將醒目提示的模型套用至此工作階段 |370| `modelPicker:thisSessionOnly` | s | 將突出顯示的模型套用到此工作階段 |

369 371

370<h3 id="effort-slider-actions">372<h3 id="effort-slider-actions">

371 努力滑桿動作373 Effort slider 動作

372</h3>374</h3>

373 375

374在 `EffortSlider` 上下文中可用的動作，當您執行不帶引數的 `/effort` 時開啟的滑桿。滑桿的 Left、Right、Enter 和 Escape 按鍵無法重新繫結。376在 `EffortSlider` 上下文中可用的動作，當您執行不帶引數的 `/effort` 時開啟的滑塊。滑塊的 Left、Right、Enter 和 Escape 鍵無法重新綁定。

375 377

376| 動作 | 預設 | 說明 |378| 動作 | 預設 | 說明 |

377| :----------------------------- | :- | :--------------------------------------------------------------------------- |379| :----------------------------- | :- | :----------------------------------------------------------------------------- |

378| `effortSlider:thisSessionOnly` | s | 將焦點[努力程度](/docs/zh-TW/model-config#adjust-effort-level)套用至此工作階段。需要 v2.1.257 或更新版本 |380| `effortSlider:thisSessionOnly` | s | 將焦點 [努力等級](/docs/zh-TW/model-config#adjust-effort-level) 套用到此工作階段。需要 v2.1.257 或更新版本 |

379 381

380<h3 id="select-actions">382<h3 id="select-actions">

381 選擇動作383 Select 動作

382</h3>384</h3>

383 385

384在 `Select` 上下文中可用的動作：386在 `Select` 上下文中可用的動作：

396 398

397Claude Code 在 `/skills` 選單中套用您的 `select:pageUp`、`select:pageDown`、`select:first` 和 `select:last` 繫結。在大多數其他清單中，例如 `/model` 選擇器，您的 `select:first` 和 `select:last` 繫結會套用。PageUp 和 PageDown 會在這些清單中進行分頁，無論您的繫結如何。399Claude Code 在 `/skills` 選單中套用您的 `select:pageUp`、`select:pageDown`、`select:first` 和 `select:last` 綁定。在大多數其他清單中，例如 `/model` 選擇器，您的 `select:first` 和 `select:last` 綁定適用。PageUp 和 PageDown 在這些清單中分頁選項，無論您的綁定如何。

398 400

399在 v2.1.280 之前，這些其他清單忽略 Home、End 和您的 `select:first` 和 `select:last` 繫結。401在 v2.1.280 之前，這些其他清單忽略了 Home、End 和您的 `select:first` 和 `select:last` 綁定。

400 402

401<h3 id="plugin-actions">403<h3 id="plugin-actions">

402 Plugin 動作404 Plugin 動作

405在 `Plugin` 上下文中可用的動作：407在 `Plugin` 上下文中可用的動作：

406 408

407| 動作 | 預設 | 說明 |409| 動作 | 預設 | 說明 |

408| :---------------- | :---- | :--------------------------------- |410| :---------------- | :---- | :-------------------------- |

410| `plugin:install` | I | 安裝選定的 plugins |412| `plugin:install` | I | 安裝選定的外掛程式 |

411| `plugin:favorite` | F | 將選定的 plugin 標記為最愛，使其在「已安裝」標籤頂部附近排序 |413| `plugin:favorite` | F | 將選定的外掛程式設為最愛，使其在已安裝標籤頂部附近排序 |

412 414

413<h3 id="settings-actions">415<h3 id="settings-actions">

414 設定動作416 Settings 動作

415</h3>417</h3>

416 418

417在 `Settings` 上下文中可用的動作。`select:accept` 和 `confirm:no` 動作會從[選擇](#select-actions)和[確認](#confirmation-actions)上下文中重複使用，具有設定特定的行為：變更會在您變更時立即套用到每個設定，因此 Escape 會關閉面板並儲存您的變更，而不是拒絕。419在 `Settings` 上下文中可用的動作。`select:accept` 和 `confirm:no` 動作從 [Select](#select-actions) 和 [Confirmation](#confirmation-actions) 上下文重複使用，具有特定於設定的行為：變更會在您變更時立即套用到每個設定，因此 Escape 會關閉面板並保存您的變更，而不是拒絕。

418 420

419| 動作 | 預設 | 說明 |421| 動作 | 預設 | 說明 |

420| :---------------- | :----------- | :--------------- |422| :---------------- | :----------- | :------------- |

421| `settings:search` | / | 進入搜尋模式 |423| `settings:search` | / | 進入搜尋模式 |

422| `settings:retry` | R | 重試載入使用量資料（發生錯誤時） |424| `settings:retry` | R | 在錯誤時重試載入使用量資料 |

425 427

426<h3 id="agents-actions">428<h3 id="agents-actions">

427 代理動作429 Agents 動作

428</h3>430</h3>

429 431

430在 `Agents` 上下文中可用的動作，適用於[代理檢視](/docs/zh-TW/agent-view)，使用 `claude agents` 開啟。需要 v2.1.257 或更新版本。432在 `Agents` 上下文中可用的動作，適用於 [代理檢視](/docs/zh-TW/agent-view)，使用 `claude agents` 開啟。需要 v2.1.257 或更新版本。

431 433

432| 動作 | 預設 | 說明 |434| 動作 | 預設 | 說明 |

433| :------------------ | :----- | :------------------------------------------------------ |435| :------------------ | :----- | :------------------------------------------------------- |

436 438

437當代理檢視開啟時，Claude Code 對 `Agents` 上下文繫結的任何按鍵使用 `Agents` 繫結，並忽略同一按鍵上的 `Chat` 或 `Global` 繫結。例如，在代理檢視中按 Ctrl+S 會切換工作階段分組，而不是觸發預設的 `chat:stash`。439當代理檢視開啟時，Claude Code 對 `Agents` 上下文綁定的任何鍵使用 `Agents` 綁定，並忽略同一鍵上的 `Chat` 或 `Global` 綁定。例如，在代理檢視中按 Ctrl+S 會切換工作階段分組，而不是觸發預設的 `chat:stash`。

438 440

439分派輸入的外部編輯器快捷鍵不是 `Agents` 動作。代理檢視遵循 `Chat` 上下文的 `chat:externalEditor` 繫結，預設為 Ctrl+G。441分派輸入的外部編輯器快捷鍵不是 `Agents` 動作。代理檢視遵循 `Chat` 上下文的 `chat:externalEditor` 綁定，預設為 Ctrl+G。

440 442

441繫結在代理檢視中的單鍵擊上觸發，因此繫結到 `chat:externalEditor` 的 Ctrl+X Ctrl+E 快捷鍵不會在那裡開啟編輯器。443在代理檢視中，綁定在單個按鍵上觸發，因此綁定到 `chat:externalEditor` 的 Ctrl+X Ctrl+E 和弦不會在那裡開啟編輯器。

442 444

443<h3 id="voice-actions">445<h3 id="voice-actions">

444 語音動作446 Voice 動作

445</h3>447</h3>

446 448

447在啟用[語音聽寫](/docs/zh-TW/voice-dictation)時，在 `Chat` 上下文中可用的動作：449當 [語音聽寫](/docs/zh-TW/voice-dictation) 啟用時，在 `Chat` 上下文中可用的動作：

448 450

449| 動作 | 預設 | 說明 |451| 動作 | 預設 | 說明 |

450| :----------------- | :---- | :----------------------- |452| :----------------- | :---- | :----------------------- |

452 454

453<h3 id="scroll-actions">455<h3 id="scroll-actions">

454 滾動動作456 Scroll 動作

455</h3>457</h3>

456 458

457在啟用[全螢幕渲染](/docs/zh-TW/fullscreen)時，在 `Scroll` 上下文中可用的動作：459當 [全螢幕轉譯](/docs/zh-TW/fullscreen) 啟用時，在 `Scroll` 上下文中可用的動作：

458 460

459| 動作 | 預設 | 說明 |461| 動作 | 預設 | 說明 |

460| :-------------------------- | :------------------- | :--------------------------------------------------- |462| :-------------------------- | :------------------- | :--------------------------------------------------- |

467| `scroll:halfPageUp` | (未繫結) | 向上滾動視窗高度的一半。與 `scroll:pageUp` 相同的行為，為 vi 風格的重新繫結提供 |469| `scroll:halfPageUp` | (未綁定) | 向上捲動檢視區高度的一半。與 `scroll:pageUp` 相同的行為，為 vi 樣式重新綁定提供 |

468| `scroll:halfPageDown` | (未繫結) | 向下滾動視窗高度的一半。與 `scroll:pageDown` 相同的行為，為 vi 風格的重新繫結提供 |470| `scroll:halfPageDown` | (未綁定) | 向下捲動檢視區高度的一半。與 `scroll:pageDown` 相同的行為，為 vi 樣式重新綁定提供 |

469| `scroll:fullPageUp` | (未繫結) | 向上滾動完整視窗高度 |471| `scroll:fullPageUp` | (未綁定) | 向上捲動整個檢視區高度 |

470| `scroll:fullPageDown` | (未繫結) | 向下滾動完整視窗高度 |472| `scroll:fullPageDown` | (未綁定) | 向下捲動整個檢視區高度 |

472| `selection:clear` | (未繫結) | 清除有效的文字選擇。需要 v2.1.234 或更新版本 |474| `selection:clear` | (未綁定) | 清除有效的文字選擇。需要 v2.1.234 或更新版本 |

479 481

634| Ctrl+A | GNU screen 前綴 |636| Ctrl+A | GNU screen 前綴 |

635| Ctrl+Z | Unix 程序暫停 (SIGTSTP) |637| Ctrl+Z | Unix 程序暫停 (SIGTSTP) |

636 638

639<h2 id="text-fields">

640 文字欄位

641</h2>

642

643如果你綁定一個裸露的字母、數字或空格鍵，你仍然可以在對話框或面板內的文字欄位中輸入該字元。其中一個欄位是 Claude 提出問題時的 `Other` 答案。當欄位獲得焦點時，你按下的可列印鍵（不含 Ctrl、Alt 或 Cmd）會進入該欄位，Claude Code 不會根據你的綁定來匹配它。

644

645這些鍵在欄位獲得焦點時仍會執行其綁定：

646

647* 不輸入字元的鍵，例如 Enter、Escape、Tab 和方向鍵

648* 任何使用 Ctrl、Alt 或 Cmd 按下的鍵

649* 已在進行中的[和弦](#chords)的第二個按鍵

650

651在主提示符處，Claude Code 根據作用中的內容（例如 `Chat`）來匹配每個鍵，只有在沒有綁定取用該鍵時才會輸入該鍵。

652

637<h2 id="vim-mode-interaction">653<h2 id="vim-mode-interaction">

638 Vim 模式互動654 Vim 模式互動

639</h2>655</h2>

large-codebases.md +35 −35

Details

202 使用程式碼智能減少檔案讀取202 使用程式碼智能減少檔案讀取

203</h3>203</h3>

204 204

205在大型程式碼庫中，尋找符號的定義或使用位置可能會花費許多檔案讀取和 grep 呼叫。[程式碼智能外掛](/docs/zh-TW/discover-plugins#code-intelligence)將 Claude 連接到語言伺服器，以便它可以跳轉到定義、尋找參考和直接顯示類型錯誤，而不是掃描樹。205在大型程式碼庫中，尋找符號的定義或使用位置可能會花費許多檔案讀取和 grep 呼叫。[程式碼智能外掛](/docs/zh-TW/plugins/code-intelligence)將 Claude 連接到語言伺服器，以便它可以跳轉到定義、尋找參考和直接顯示類型錯誤，而不是掃描樹。

206 206

207官方市場有 TypeScript、Python、Go、Rust 和其他常見語言的外掛。在 Claude Code 工作階段內執行下方命令以安裝 TypeScript 外掛：207官方市場有 TypeScript、Python、Go、Rust 和其他常見語言的外掛。在 Claude Code 工作階段內執行下方命令以安裝 TypeScript 外掛：

208 208

213如果安裝失敗，請符合 Claude Code 報告的訊息：213如果安裝失敗，請符合 Claude Code 報告的訊息：

214 214

215* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市場，然後重試安裝。215* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市場，然後重試安裝。

216* 外掛[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛名稱。216* 外掛[在市場中找不到](/docs/zh-TW/plugins/install#install-a-plugin)：檢查外掛名稱。

217 217

218若要為儲存庫中的每個人啟用外掛而不是自己安裝，請將其添加到 [`enabledPlugins` 專案設定](/docs/zh-TW/settings-reference#plugin-settings)。218若要為儲存庫中的每個人啟用外掛而不是自己安裝，請將其添加到 [`enabledPlugins` 專案設定](/docs/zh-TW/settings-reference#plugin-settings)。

219 219

220程式碼智能外掛需要每個開發人員機器上的語言的語言伺服器二進位檔案。請參閱[每種語言需要哪個二進位檔案](/docs/zh-TW/discover-plugins#code-intelligence)。從官方市場安裝需要網路存取 GitHub，市場在那裡託管。在受限網路上，[改為從內部 Git 主機或本地路徑添加市場](/docs/zh-TW/discover-plugins#add-from-other-git-hosts)。220程式碼智能外掛需要每個開發人員機器上的語言的語言伺服器二進位檔案。請參閱[每種語言需要哪個二進位檔案](/docs/zh-TW/plugins/code-intelligence)。從官方市場安裝需要網路存取 GitHub，市場在那裡託管。在受限網路上，[改為從內部 Git 主機或本地路徑添加市場](/docs/zh-TW/plugins/install#add-a-marketplace)。

221 221

222這與上面的 `claudeMdExcludes` 和 `Read` 拒絕規則配對良好。這些將無關的內容保持在上下文之外，程式碼智能防止 Claude 通過讀取剩餘內容來定位定義。222這與上面的 `claudeMdExcludes` 和 `Read` 拒絕規則配對良好。這些將無關的內容保持在上下文之外，程式碼智能防止 Claude 通過讀取剩餘內容來定位定義。

223 223

331對於此區域中的每個人都需要的同級目錄，請將 `additionalDirectories` 提交到 `.claude/settings.json`。對於個人選擇或一次性存取，請使用 `.claude/settings.local.json` 或在啟動時傳遞 `--add-dir`。331對於此區域中的每個人都需要的同級目錄，請將 `additionalDirectories` 提交到 `.claude/settings.json`。對於個人選擇或一次性存取，請使用 `.claude/settings.local.json` 或在啟動時傳遞 `--add-dir`。

332 332

333<h2 id="add-per-directory-skills">333<h2 id="add-per-directory-skills">

334 添加按目錄技能334 新增各目錄範圍的 skills

335</h2>335</h2>

336 336

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

338 338

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

340 340

341在子目錄內建立技能目錄：341在子目錄內建立 skill 目錄：

342 342

343```bash theme={null}343```bash theme={null}

344mkdir -p packages/api/.claude/skills/api-testing344mkdir -p packages/api/.claude/skills/api-testing

349```markdown packages/api/.claude/skills/api-testing/SKILL.md theme={null}349```markdown packages/api/.claude/skills/api-testing/SKILL.md theme={null}

350---350---

351name: api-testing351name: api-testing

352description: API 套件的測試模式。在 packages/api/ 中編寫或修改測試時使用。352description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.

353---353---

354 354

355## 測試結構355## Test structure

356 356

357測試在 `src/__tests__/` 中，鏡像 `src/` 目錄結構。357Tests are in `src/__tests__/` mirroring the `src/` directory structure.

358每個路由檔案都有對應的 `.test.ts` 檔案。358Each route file has a corresponding `.test.ts` file.

359 359

360## 執行測試360## Running tests

361 361

362- 所有測試：`npm test`362- All tests: `npm test`

363- 單個檔案：`npm test -- src/__tests__/routes/users.test.ts`363- Single file: `npm test -- src/__tests__/routes/users.test.ts`

364- 監視模式：`npm test -- --watch`364- Watch mode: `npm test -- --watch`

365 365

366## 測試實用程式366## Test utilities

367 367

368- `src/__tests__/helpers/db.ts`：提供 `setupTestDb()` 和 `teardownTestDb()` 用於資料庫測試368- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()` for database tests

369- `src/__tests__/helpers/auth.ts`：提供 `createTestUser()` 和 `getAuthToken()` 用於已驗證的端點369- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()` for authenticated endpoints

370 370

371## 模式371## Patterns

372 372

373- 使用 `supertest` 進行 HTTP 斷言，而不是原始 fetch373- Use `supertest` for HTTP assertions, not raw fetch

374- 始終將資料庫測試包裝在回滾的交易中374- Always wrap database tests in a transaction that rolls back

375- 在 `src/__tests__/mocks/` 中模擬外部服務375- Mock external services in `src/__tests__/mocks/`

376```376```

377 377

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

379 379

380您也可以按檔案模式而不是按位置範圍技能。[`paths` frontmatter 欄位](/docs/zh-TW/skills#frontmatter-reference)採用 glob 模式，Claude 僅在使用匹配檔案時自動載入技能。將此用於位於儲存庫根目錄的 `.claude/skills/` 中但僅適用於某些檔案（無論它們出現在何處）的技能，例如範圍限於 `**/migrations/**` 的資料庫遷移技能。380您也可以按檔案模式而不是按位置來限定 skill 的範圍。[`paths` frontmatter 欄位](/docs/zh-TW/skills#frontmatter-reference)採用 glob 模式，當 Claude 使用符合的檔案時，它會自動載入 skill。使用此方法可以讓 skill 位於儲存庫根目錄的 `.claude/skills/` 中，但僅適用於特定檔案（無論它們出現在何處），例如限定於 `**/migrations/**` 的資料庫遷移 skill。

381 381

382有關建立和組織技能的更多資訊，請參閱[技能](/docs/zh-TW/skills)。382如需更多關於建立和組織 skills 的資訊，請參閱 [Skills](/docs/zh-TW/skills)。

383 383

384<h3 id="keep-skills-discoverable">384<h3 id="keep-skills-discoverable">

385 保持技能可發現385 保持 skills 可發現

386</h3>386</h3>

387 387

388隨著技能分散在許多目錄中，Claude 選擇的清單可能會增長很大。Claude 通過讀取每個發現的技能的名稱和描述來選擇技能，只有選定技能的完整內容載入上下文。本部分涵蓋如何保持該清單較小。388隨著 skills 分散在許多目錄中，Claude 可選擇的清單可能會變得很大。Claude 透過讀取每個已發現 skill 的名稱和描述來選擇 skill，只有選定 skill 的完整內容才會載入上下文。本節涵蓋如何保持該清單較小。

389 389

390哪些技能在範圍內取決於您從何處啟動 Claude：390哪些 skills 在範圍內取決於您從何處啟動 Claude：

391 391

392* **從子目錄（如 `packages/api/`）**：來自該目錄、每個父目錄直到儲存庫根目錄以及使用者和企業級別的技能392* **從子目錄（例如 `packages/api/`）**：該目錄的 skills、每個父目錄直到儲存庫根目錄，以及使用者和企業級別的 skills

393* **從儲存庫根目錄**：根目錄技能，加上來自 Claude 在工作階段期間接觸的每個子目錄的技能，可能累積到數百個393* **從儲存庫根目錄**：根目錄 skills，加上 Claude 在工作階段期間接觸的每個子目錄的 skills，這可能會累積成數百個

394* **在使用 [`--add-dir`](#grant-access-across-packages-or-repositories) 添加同級後**：該同級的技能也會載入。`additionalDirectories` 設定僅授予檔案存取權限，不載入技能394* **在使用 [`--add-dir`](#grant-access-across-packages-or-repositories) 新增同層目錄後**：該同層目錄的 skills 也會載入。`additionalDirectories` 設定僅授予檔案存取權限，不會載入 skills

395 395

396名稱始終載入，但[當有許多時，某些技能會完全失去其描述](/docs/zh-TW/skills#skill-descriptions-are-cut-short)，這可能會剝離 Claude 用來決定技能是否適用的關鍵字。保持描述簡短並以請求會包含的詞語開頭，例如「在 `packages/api/` 中編寫或修改測試」。396名稱總是會載入，但[當有許多時，某些 skills 會完全失去其描述](/docs/zh-TW/skills#skill-descriptions-are-cut-short)，這可能會移除 Claude 用來決定 skill 是否適用的關鍵字。保持描述簡短，並以請求會包含的詞語開頭，例如「在 `packages/api/` 中寫入或修改測試」。

397 397

398對於許多目錄共享的技能，例如 PR 約定或部署檢查清單，請將它們放在儲存庫根目錄的 `.claude/skills/` 中，以便從任何啟動目錄載入。當共享技能需要自己的版本歷史或必須跨儲存庫工作時，請改為將它們打包為[外掛](/docs/zh-TW/plugins)。外掛技能使用 `plugin-name:skill-name` 命名空間，因此它們永遠不會與按目錄的技能衝突。平台團隊可以在一個地方對其進行版本化和更新。398對於許多目錄共享的 skills，例如 PR 慣例或部署檢查清單，將它們放在儲存庫根目錄的 `.claude/skills/` 中，以便從任何啟動目錄載入。當共享 skills 需要自己的版本歷史或必須跨儲存庫工作時，改為將它們打包為[plugin](/docs/zh-TW/plugins/overview)。Plugin skills 使用 `plugin-name:skill-name` 命名空間，因此它們永遠不會與各目錄 skills 衝突。平台團隊可以在一個地方進行版本控制和更新。

399 399

400若要找到哪些技能未被使用，請啟用 OpenTelemetry [日誌匯出器](/docs/zh-TW/monitoring-usage)並設定 `OTEL_LOG_TOOL_DETAILS=1`，以便技能名稱逐字記錄而不是編輯。[`skill_activated` 事件](/docs/zh-TW/monitoring-usage#skill-activated-event)在其 `skill.name` 屬性中記錄每次呼叫，`invocation_trigger` 記錄命令、Claude 或巢狀技能是否呼叫它，這告訴您要整合或停用什麼。400若要找出哪些 skills 未被使用，請啟用 OpenTelemetry [logs exporter](/docs/zh-TW/monitoring-usage)，並設定 `OTEL_LOG_TOOL_DETAILS=1`，以便 skill 名稱按字面記錄而不是被編輯。[`skill_activated` 事件](/docs/zh-TW/monitoring-usage#skill-activated-event)在其 `skill.name` 屬性中記錄每次調用，`invocation_trigger` 記錄命令、Claude 或巢狀 skill 是否調用了它，這告訴您要整合或淘汰什麼。

401 401

402<h2 id="centralize-conventions-when-layering-stops-scaling">402<h2 id="centralize-conventions-when-layering-stops-scaling">

403 當分層停止擴展時集中約定403 當分層停止擴展時集中約定

408將約定和參考內容從始終載入的 CLAUDE.md 移出到按需載入的機制中：408將約定和參考內容從始終載入的 CLAUDE.md 移出到按需載入的機制中：

409 409

410* [技能](/docs/zh-TW/skills)：Claude 僅在與任務相關時載入的參考資料410* [技能](/docs/zh-TW/skills)：Claude 僅在與任務相關時載入的參考資料

411* [外掛](/docs/zh-TW/plugins)：平台團隊集中擁有的技能、hooks 和命令的版本化捆綁411* [外掛](/docs/zh-TW/plugins/overview)：平台團隊集中擁有的技能、hooks 和命令的版本化捆綁

412* [MCP 伺服器](/docs/zh-TW/mcp)：如果您的組織已經在儲存庫上執行程式碼搜尋或 RAG 索引，請將其公開為 MCP 工具，以便 Claude 查詢它而不是直接讀取檔案412* [MCP 伺服器](/docs/zh-TW/mcp)：如果您的組織已經在儲存庫上執行程式碼搜尋或 RAG 索引，請將其公開為 MCP 工具，以便 Claude 查詢它而不是直接讀取檔案

413 413

414有關平台團隊如何集中強制執行這些的資訊，請參閱[伺服器管理或端點管理設定](/docs/zh-TW/server-managed-settings#choose-between-server-managed-and-endpoint-managed-settings)。414有關平台團隊如何集中強制執行這些的資訊，請參閱[伺服器管理或端點管理設定](/docs/zh-TW/server-managed-settings#choose-between-server-managed-and-endpoint-managed-settings)。

managed-mcp.md +1 −1

Details

41| **無限制** | 使用者新增任何伺服器 | 不部署任何受管 MCP 設定 |41| **無限制** | 使用者新增任何伺服器 | 不部署任何受管 MCP 設定 |

42 42

43<Note>43<Note>

44 Claude Code 沒有內建的 MCP 伺服器登錄，使用者可以從中瀏覽和安裝。對於已核准的目錄模式，請在使用者會找到的地方（例如內部 wiki）分享已核准的清單及其 `claude mcp add` 命令，或透過 [受管外掛程式市集](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) 將伺服器分發為外掛程式，以便使用者可以從 `/plugin` 瀏覽和安裝它們。44 Claude Code 沒有內建的 MCP 伺服器登錄，使用者可以從中瀏覽和安裝。對於已核准的目錄模式，請在使用者會找到的地方（例如內部 wiki）分享已核准的清單及其 `claude mcp add` 命令，或透過 [受管外掛程式市集](/docs/zh-TW/plugins/org#restrict-what-users-can-install) 將伺服器分發為外掛程式，以便使用者可以從 `/plugin` 瀏覽和安裝它們。

45</Note>45</Note>

46 46

47<h2 id="exclusive-control-with-managed-mcp-json">47<h2 id="exclusive-control-with-managed-mcp-json">

managed-settings.md +9 −7

Details

95 * **在完整 VM 沙箱中**：當您的 Claude Desktop 受管設定將 [`requireCoworkFullVmSandbox`](https://claude.com/docs/third-party/claude-desktop/configuration#requirecoworkfullvmsandbox) 設定時，Claude Code 在虛擬機器內執行，其中裝置的 MDM 原則和受管設定檔案不存在。95 * **在完整 VM 沙箱中**：當您的 Claude Desktop 受管設定將 [`requireCoworkFullVmSandbox`](https://claude.com/docs/third-party/claude-desktop/configuration#requirecoworkfullvmsandbox) 設定時，Claude Code 在虛擬機器內執行，其中裝置的 MDM 原則和受管設定檔案不存在。

96 * **遠端共同工作工作階段**：這些在 Anthropic 受管 VM 上執行，其中 Claude Code 沒有裝置原則可讀取。96 * **遠端共同工作工作階段**：這些在 Anthropic 受管 VM 上執行，其中 Claude Code 沒有裝置原則可讀取。

97 97

98 無論工作階段在何處執行，claude.ai 在任何人從 claude.ai 上的 git 儲存庫或從 Cowork 標籤中的**自訂**新增市集時，會自行應用管理主控台的 [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) 和 [`blockedMarketplaces`](/docs/zh-TW/settings-reference#blockedmarketplaces) 列表。[限制如何運作](/docs/zh-TW/plugin-marketplaces#how-restrictions-work)描述該檢查。[表面涵蓋](/docs/zh-TW/model-config#surface-coverage)表比較共同工作與其他表面。98 無論工作階段在何處執行，claude.ai 在任何人從 claude.ai 上的 git 儲存庫或從 Cowork 標籤中的**自訂**新增市集時，會自行應用管理主控台的 [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) 和 [`blockedMarketplaces`](/docs/zh-TW/settings-reference#blockedmarketplaces) 列表。[限制如何運作](/docs/zh-TW/plugins/org#restrict-what-users-can-install)描述該檢查。[表面涵蓋](/docs/zh-TW/model-config#surface-coverage)表比較共同工作與其他表面。

99* **執行中的工作階段**：大多數變更在[傳遞機制表](#choose-a-delivery-mechanism)中的排程上到達執行中的工作階段，無需重新啟動。99* **執行中的工作階段**：大多數變更在[傳遞機制表](#choose-a-delivery-mechanism)中的排程上到達執行中的工作階段，無需重新啟動。

100 * 對 [`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh)、[`requiredMinimumVersion`](/docs/zh-TW/settings-reference#requiredminimumversion) 和[某些使用者可編輯的金鑰](/docs/zh-TW/settings#when-edits-take-effect)的變更在下一個工作階段啟動時生效。100 * 對 [`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh)、[`requiredMinimumVersion`](/docs/zh-TW/settings-reference#requiredminimumversion) 和[某些使用者可編輯的金鑰](/docs/zh-TW/settings#when-edits-take-effect)的變更在下一個工作階段啟動時生效。

101 * 新的或變更的 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 項目在下一次啟動時生效。如果伺服器受管設定在該啟動時遮蔽協助程式，協助程式會在擷取報告這些設定已移除時立即執行。101 * 新的或變更的 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 項目在下一次啟動時生效。如果伺服器受管設定在該啟動時遮蔽協助程式，協助程式會在擷取報告這些設定已移除時立即執行。

256 256

257 在 Claude Code v2.1.273 或更新版本上，當 `allowManagedMcpServersOnly` 開啟時，來自設定一個的最高排名管理員來源的 `allowedMcpServers` 列表適用並阻止父的值，作為 [跨來源金鑰](#keys-read-from-every-admin-source)。父的列表僅在沒有管理員來源設定一個時適用。[`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 項目說明在 `"merge"` 下哪個來源提供每個金鑰。在 v2.1.223 之前，任何管理員來源中的值都會阻止父的值257 在 Claude Code v2.1.273 或更新版本上，當 `allowManagedMcpServersOnly` 開啟時，來自設定一個的最高排名管理員來源的 `allowedMcpServers` 列表適用並阻止父的值，作為 [跨來源金鑰](#keys-read-from-every-admin-source)。父的列表僅在沒有管理員來源設定一個時適用。[`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 項目說明在 `"merge"` 下哪個來源提供每個金鑰。在 v2.1.223 之前，任何管理員來源中的值都會阻止父的值

258* 對於 `availableModels`，Claude Code 強制執行它應用的受管設定中的值並阻止父提供的列表258* 對於 `availableModels`，Claude Code 強制執行它應用的受管設定中的值並阻止父提供的列表

259* 對於 `strictKnownMarketplaces`，Claude Code 同樣強制執行它應用的受管設定中的列表並阻止父提供的列表。父的列表僅在沒有應用的受管來源設定一個時適用。需要 Claude Code v2.1.282 或更新版本

260* 父提供的 `blockedMarketplaces` 除了受管來源設定的任何封鎖清單外還會適用。需要 Claude Code v2.1.282 或更新版本

259 261

260<h4 id="keep-cowork-folder-access-when-only-managed-rules-apply">262<h4 id="keep-cowork-folder-access-when-only-managed-rules-apply">

261 當僅應用受管規則時保持 Cowork 資料夾存取263 當僅應用受管規則時保持 Cowork 資料夾存取

366| `allowedHttpHookUrls` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#allowedhttphookurls)，直到您修復該值，因此 HTTP hook 只有在另一個設定檔案列出其 URL 時才會執行。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |368| `allowedHttpHookUrls` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#allowedhttphookurls)，直到您修復該值，因此 HTTP hook 只有在另一個設定檔案列出其 URL 時才會執行。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |

367| `httpHookAllowedEnvVars` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#httphookallowedenvvars)，直到您修復該值，因此標頭變數只有在另一個設定檔案命名它時才會被插值。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |369| `httpHookAllowedEnvVars` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#httphookallowedenvvars)，直到您修復該值，因此標頭變數只有在另一個設定檔案命名它時才會被插值。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |

369| `strictKnownMarketplaces` | 強制執行為空的允許清單，直到修復該值，因此沒有[市場來源](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)被允許。無效或無法強制執行的個別項目（例如無法編譯的 `hostPattern` 正規表達式）被剝離，有效子集被強制執行。 |371| `strictKnownMarketplaces` | 強制執行為空的允許清單，直到修復該值，因此沒有[市場來源](/docs/zh-TW/plugins/org#restrict-what-users-can-install)被允許。無效或無法強制執行的個別項目（例如無法編譯的 `hostPattern` 正規表達式）被剝離，有效子集被強制執行。 |

370| `allowManagedHooksOnly` | 視為 `true` 直到修復：[hook 限制](/docs/zh-TW/settings-reference#allowmanagedhooksonly)適用，除非 `disableCommandPluginSources` 明確為 `false`，否則命令來源的外掛被禁用。 |372| `allowManagedHooksOnly` | 視為 `true` 直到修復：[hook 限制](/docs/zh-TW/settings-reference#allowmanagedhooksonly)適用，除非 `disableCommandPluginSources` 明確為 `false`，否則命令來源的外掛被禁用。 |

378| `gatewayInternalNetworks` | 當無效值來自機器上最高的受管理來源時，`/login` 拒絕該機器上的每個新[雲端閘道](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)登入，直到修復該值。 |380| `gatewayInternalNetworks` | 當無效值來自機器上最高的受管理來源時，`/login` 拒絕該機器上的每個新[雲端閘道](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)登入，直到修復該值。 |

379| `crossSessionInbound` | 視為 `refuse`（最限制性的值），因此入站[跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)被拒絕，直到修復該值。開發人員看到[警告](/docs/zh-TW/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse)。 |381| `crossSessionInbound` | 視為 `refuse`（最限制性的值），因此入站[跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)被拒絕，直到修復該值。開發人員看到[警告](/docs/zh-TW/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse)。 |

381| `blockedMarketplaces` | 個別無效項目被剝離，有效子集被強制執行。解析但永遠無法匹配的項目（例如無法編譯的 `hostPattern` 正規表達式）被保留並發出警告。它在修復前不會阻止任何內容，但[市場限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)保持活躍。完全無效的值被丟棄並發出警告，因為阻止每個市場會阻止政策從未命名的來源。 |383| `blockedMarketplaces` | 個別無效項目被剝離，有效子集被強制執行。解析但永遠無法匹配的項目（例如無法編譯的 `hostPattern` 正規表達式）被保留並發出警告。它在修復前不會阻止任何內容，但[市場限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install)保持活躍。完全無效的值被丟棄並發出警告，因為阻止每個市場會阻止政策從未命名的來源。 |

382| `sandbox.credentials` | 可恢復的無效項目被降級為 `mode: "deny"` 並發出警告；無法恢復的項目被剝離；有效項目保持強制執行。請參閱[受管理設定中的無效認證項目](/docs/zh-TW/settings-reference#invalid-credential-entries-in-managed-settings) |384| `sandbox.credentials` | 可恢復的無效項目被降級為 `mode: "deny"` 並發出警告；無法恢復的項目被剝離；有效項目保持強制執行。請參閱[受管理設定中的無效認證項目](/docs/zh-TW/settings-reference#invalid-credential-entries-in-managed-settings) |

383 385

384`allowedHttpHookUrls` 和 `httpHookAllowedEnvVars` 跨設定檔案合併，因此您的使用者、專案或本機設定中的項目在受管理清單為空時仍然適用。386`allowedHttpHookUrls` 和 `httpHookAllowedEnvVars` 跨設定檔案合併，因此您的使用者、專案或本機設定中的項目在受管理清單為空時仍然適用。

402該表涵蓋權限、外掛程式和傳遞控制。對於此處未列出的任何金鑰，[設定參考](/docs/zh-TW/settings-reference#all-settings)索引的「範圍」欄會說明它是否為僅受管理；其中剩餘的僅受管理金鑰包括閘道登入 URL、版本、瀏覽器、行動模擬器、SSH 主機、Desktop 本機工作階段、沙箱二進位路徑、模型定價和 CLAUDE.md 控制。404該表涵蓋權限、外掛程式和傳遞控制。對於此處未列出的任何金鑰，[設定參考](/docs/zh-TW/settings-reference#all-settings)索引的「範圍」欄會說明它是否為僅受管理；其中剩餘的僅受管理金鑰包括閘道登入 URL、版本、瀏覽器、行動模擬器、SSH 主機、Desktop 本機工作階段、沙箱二進位路徑、模型定價和 CLAUDE.md 控制。

403 405

404| 設定 | 說明 |406| 設定 | 說明 |

405| :----------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |407| :----------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

406| [`allowAllClaudeAiMcps`](/docs/zh-TW/settings-reference#allowallclaudeaimcps) | 載入 Claude Code 自行擷取的 claude.ai 連接器，與已部署的 `managed-mcp.json` 一起，而不是抑制它們 |408| [`allowAllClaudeAiMcps`](/docs/zh-TW/settings-reference#allowallclaudeaimcps) | 載入 Claude Code 自行擷取的 claude.ai 連接器，與已部署的 `managed-mcp.json` 一起，而不是抑制它們 |

407| [`allowedChannelPlugins`](/docs/zh-TW/settings-reference#allowedchannelplugins) | 可能推送訊息的頻道外掛程式的允許清單。設定時會取代預設的 Anthropic 允許清單。需要 `channelsEnabled: true`。請參閱[限制哪些頻道外掛程式可以執行](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run) |409| [`allowedChannelPlugins`](/docs/zh-TW/settings-reference#allowedchannelplugins) | 可能推送訊息的頻道外掛程式的允許清單。設定時會取代預設的 Anthropic 允許清單。需要 `channelsEnabled: true`。請參閱[限制哪些頻道外掛程式可以執行](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run) |

408| [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) | 當為 `true` 時，限制哪些 hooks 執行；請參閱[在 `allowManagedHooksOnly` 下執行的內容](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)以取得完整效果清單 |410| [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) | 當為 `true` 時，限制哪些 hooks 執行；請參閱[在 `allowManagedHooksOnly` 下執行的內容](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)以取得完整效果清單 |

409| [`allowManagedMcpServersOnly`](/docs/zh-TW/settings-reference#allowmanagedmcpserversonly) | 當為 `true` 時，只有來自受管理設定的 `allowedMcpServers` 會被遵守。`deniedMcpServers` 仍會從所有來源合併。請參閱[從每個管理員來源讀取的金鑰](#keys-read-from-every-admin-source)以了解哪些受管理來源可以設定它，以及[受管理 MCP 配置](/docs/zh-TW/managed-mcp) |411| [`allowManagedMcpServersOnly`](/docs/zh-TW/settings-reference#allowmanagedmcpserversonly) | 當為 `true` 時，只有來自受管理設定的 `allowedMcpServers` 會被遵守。`deniedMcpServers` 仍會從所有來源合併。請參閱[從每個管理員來源讀取的金鑰](#keys-read-from-every-admin-source)以了解哪些受管理來源可以設定它，以及[受管理 MCP 配置](/docs/zh-TW/managed-mcp) |

410| [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly) | 使受管理設定成為權限規則的唯一設定來源。該項目列出它忽略的每個來源 |412| [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly) | 使受管理設定成為權限規則的唯一設定來源。該項目列出它忽略的每個來源 |

411| [`blockedMarketplaces`](/docs/zh-TW/settings-reference#blockedmarketplaces) | 市集來源的封鎖清單。在下載前檢查被封鎖的來源，因此它們永遠不會接觸檔案系統。請參閱[受管理市集限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) |413| [`blockedMarketplaces`](/docs/zh-TW/settings-reference#blockedmarketplaces) | 市集來源的封鎖清單。在下載前檢查被封鎖的來源，因此它們永遠不會接觸檔案系統。請參閱[受管理市集限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install) |

412| [`channelsEnabled`](/docs/zh-TW/settings-reference#channelsenabled) | 允許組織使用[頻道](/docs/zh-TW/channels)。請參閱[企業控制](/docs/zh-TW/channels#enterprise-controls)以了解每個方案的預設值 |414| [`channelsEnabled`](/docs/zh-TW/settings-reference#channelsenabled) | 允許組織使用[頻道](/docs/zh-TW/channels)。請參閱[企業控制](/docs/zh-TW/channels#enterprise-controls)以了解每個方案的預設值 |

413| [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) | 當為 `true` 時，完全封鎖[`command` 外掛程式來源](/docs/zh-TW/plugin-marketplaces#command-sources)，因此市集宣告的命令永遠不會執行。也會封鎖市集[`headersHelper` 命令](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)，除了受管理設定本身宣告的市集。未設定時，遵循 `allowManagedHooksOnly`。需要 Claude Code v2.1.229 或更新版本，而 `headersHelper` 封鎖需要 v2.1.238 或更新版本 |415| [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) | 當為 `true` 時，完全封鎖[`command` 外掛程式來源](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)，因此市集宣告的命令永遠不會執行。也會封鎖市集[`headersHelper` 命令](/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，除了受管理設定本身宣告的市集。未設定時，遵循 `allowManagedHooksOnly`。需要 Claude Code v2.1.229 或更新版本，而 `headersHelper` 封鎖需要 v2.1.238 或更新版本 |

414| [`disableSideloadFlags`](/docs/zh-TW/settings-reference#disablesideloadflags) | 在啟動時拒絕 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` 旗標。在雲端工作階段中，Claude Code 會捨棄伺服器透過 `--mcp-config` 傳遞的 MCP 伺服器，除了同處理序 `type: "sdk"` 項目，並啟動工作階段。需要 Claude Code v2.1.193 或更新版本 |416| [`disableSideloadFlags`](/docs/zh-TW/settings-reference#disablesideloadflags) | 在啟動時拒絕 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` 旗標。在雲端工作階段中，Claude Code 會捨棄伺服器透過 `--mcp-config` 傳遞的 MCP 伺服器，除了同處理序 `type: "sdk"` 項目，並啟動工作階段。需要 Claude Code v2.1.193 或更新版本 |

415| [`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh) | 當為 `true` 時，會封鎖 CLI 啟動，直到遠端受管理設定被新鮮擷取，如果擷取失敗則退出。請參閱[失敗關閉強制執行](/docs/zh-TW/server-managed-settings#enforce-fail-closed-startup) |417| [`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh) | 當為 `true` 時，會封鎖 CLI 啟動，直到遠端受管理設定被新鮮擷取，如果擷取失敗則退出。請參閱[失敗關閉強制執行](/docs/zh-TW/server-managed-settings#enforce-fail-closed-startup) |

416| [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) | 提供給每個使用者的遠端 MCP 伺服器，與他們自己的伺服器一起。它提供伺服器而不是鎖定任何東西。請參閱[透過受管理設定提供伺服器](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)。需要 Claude Code v2.1.259 或更新版本 |418| [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) | 提供給每個使用者的遠端 MCP 伺服器，與他們自己的伺服器一起。它提供伺服器而不是鎖定任何東西。請參閱[透過受管理設定提供伺服器](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)。需要 Claude Code v2.1.259 或更新版本 |

421| [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) | 在啟動時計算受管理設定的可執行檔；請參閱[使用原則協助程式計算受管理設定](/docs/zh-TW/settings-reference#policyhelper) |423| [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) | 在啟動時計算受管理設定的可執行檔；請參閱[使用原則協助程式計算受管理設定](/docs/zh-TW/settings-reference#policyhelper) |

422| [`sandbox.filesystem.allowManagedReadPathsOnly`](/docs/zh-TW/settings-reference#sandbox-filesystem-allowmanagedreadpathsonly) | 當為 `true` 時，只有來自受管理設定的 `filesystem.allowRead` 路徑會被遵守。`denyRead` 仍會從所有來源合併 |424| [`sandbox.filesystem.allowManagedReadPathsOnly`](/docs/zh-TW/settings-reference#sandbox-filesystem-allowmanagedreadpathsonly) | 當為 `true` 時，只有來自受管理設定的 `filesystem.allowRead` 路徑會被遵守。`denyRead` 仍會從所有來源合併 |

423| [`sandbox.network.allowManagedDomainsOnly`](/docs/zh-TW/settings-reference#sandbox-network-allowmanageddomainsonly) | 只遵守受管理的 `allowedDomains` 和 `WebFetch(domain:...)` 允許規則；封鎖其他網域而不提示 |425| [`sandbox.network.allowManagedDomainsOnly`](/docs/zh-TW/settings-reference#sandbox-network-allowmanageddomainsonly) | 只遵守受管理的 `allowedDomains` 和 `WebFetch(domain:...)` 允許規則；封鎖其他網域而不提示 |

424| [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) | 控制使用者可以新增和安裝外掛程式的外掛程式市集來源。請參閱[受管理市集限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) |426| [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) | 控制使用者可以新增和安裝外掛程式的外掛程式市集來源。請參閱[受管理市集限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install) |

425| [`strictPluginOnlyCustomization`](/docs/zh-TW/settings-reference#strictpluginonlycustomization) | 從使用者和專案來源封鎖技能、代理程式、hooks 和 MCP 伺服器；`true` 鎖定全部四個，陣列命名哪個 |427| [`strictPluginOnlyCustomization`](/docs/zh-TW/settings-reference#strictpluginonlycustomization) | 從使用者和專案來源封鎖技能、代理程式、hooks 和 MCP 伺服器；`true` 鎖定全部四個，陣列命名哪個 |

426| [`wslInheritsWindowsSettings`](/docs/zh-TW/settings-reference#wslinheritswindowssettings) | 當在 HKLM 登錄或 `C:\Program Files\ClaudeCode` 下的檔案中設定時，讓 WSL 讀取 Windows 原則鏈，並且只在該目錄下沒有受管理設定檔或放置項目傳遞[原則金鑰](#how-claude-code-combines-managed-sources)時才讀取 `/etc/claude-code`；該項目給出順序 |428| [`wslInheritsWindowsSettings`](/docs/zh-TW/settings-reference#wslinheritswindowssettings) | 當在 HKLM 登錄或 `C:\Program Files\ClaudeCode` 下的檔案中設定時，讓 WSL 讀取 Windows 原則鏈，並且只在該目錄下沒有受管理設定檔或放置項目傳遞[原則金鑰](#how-claude-code-combines-managed-sources)時才讀取 `/etc/claude-code`；該項目給出順序 |

427 429

monitoring-usage.md +9 −7

Details

64}64}

65```65```

66 66

67Claude Code 會忽略儲存庫的 `.claude/settings.json` 和 `.claude/settings.local.json` 中的 [OpenTelemetry 匯出器變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)，因此儲存庫無法使用它們來開啟遙測、選擇其去向或擷取內容。請在受管設定中設定它們，或讓每個開發人員在其 shell 或 `~/.claude/settings.json` 中設定它們。儲存庫仍然可以透過將其匯出器選擇器（例如 `OTEL_LOGS_EXPORTER`）設定為 `none` 來關閉信號，除非受管設定、`--settings` 檔案或您啟動 Claude Code 的環境設定了該變數。

67Claude Code 不會將 `OTEL_*` 環境變數傳遞給它產生的子程序，包括 Bash 工具、hooks、MCP 伺服器和語言伺服器。透過 Bash 工具執行的 OpenTelemetry 檢測應用程式不會繼承 Claude Code 的匯出器端點或標頭，因此如果該應用程式需要匯出自己的遙測，請直接在命令中設定這些變數。69Claude Code 不會將 `OTEL_*` 環境變數傳遞給它產生的子程序，包括 Bash 工具、hooks、MCP 伺服器和語言伺服器。透過 Bash 工具執行的 OpenTelemetry 檢測應用程式不會繼承 Claude Code 的匯出器端點或標頭，因此如果該應用程式需要匯出自己的遙測，請直接在命令中設定這些變數。

68 70

69<h3 id="how-managed-settings-lock-the-otlp-destination">71<h3 id="how-managed-settings-lock-the-otlp-destination">

651* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一653* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

652* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在654* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在

653* `effort`：套用到請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。655* `effort`：套用到請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。

654* `agent.name`：發出請求的子代理程式類型。內建代理程式名稱和來自官方市場的外掛程式的代理程式逐字出現。其他使用者定義的代理程式名稱會被替換為 `"custom"`。當請求不是由具名子代理程式類型發出時不存在。656* `agent.name`：發出請求的子代理程式類型。內建代理程式名稱和來自官方市場的外掛程式的代理程式逐字出現。其他使用者定義的代理程式名稱會被替換為 `"custom"`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`。當請求不是由具名子代理程式類型發出時不存在。

655* `skill.name`：對請求有效的技能，由技能工具、`/` 命令設定或由產生的子代理程式繼承。內建、捆綁、使用者定義和官方市場外掛程式技能名稱逐字出現。第三方外掛程式技能名稱會被替換為 `"third-party"`。當沒有技能有效時不存在。657* `skill.name`：對請求有效的技能，由技能工具、`/` 命令設定或由產生的子代理程式繼承。內建、捆綁、使用者定義和官方市場外掛程式技能名稱逐字出現。第三方外掛程式技能名稱會被替換為 `"third-party"`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`。當沒有技能有效時不存在。

656* `plugin.name`：當有效技能或子代理程式由外掛程式提供時的擁有外掛程式。官方市場外掛程式名稱逐字出現。第三方外掛程式名稱會被替換為 `"third-party"`。當技能和子代理程式都沒有擁有外掛程式時不存在。658* `plugin.name`：當有效技能或子代理程式由外掛程式提供時的擁有外掛程式。官方市場外掛程式名稱逐字出現。第三方外掛程式名稱會被替換為 `"third-party"`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`。當技能和子代理程式都沒有擁有外掛程式時不存在。

657* `marketplace.name`：擁有外掛程式的安裝來源市場。僅針對官方市場外掛程式發出。否則不存在。659* `marketplace.name`：擁有外掛程式的安裝來源市場。僅針對官方市場外掛程式發出。否則不存在。

658* `mcp_server.name`：此請求消耗其工具結果的 MCP 伺服器。內建、claude.ai 代理和官方登錄伺服器名稱逐字出現。使用者設定的伺服器名稱會被替換為 `"custom"`。當請求未消耗任何 MCP 工具結果時不存在。在 v2.1.222 之前，Claude Code 在每個 MCP 工具呼叫後的每個請求上設定此屬性，而不僅是在消耗工具結果的請求上，因此聚合它的儀表板在升級後會顯示下降。660* `mcp_server.name`：此請求消耗其工具結果的 MCP 伺服器。內建、claude.ai 代理和官方登錄伺服器名稱逐字出現。使用者設定的伺服器名稱會被替換為 `"custom"`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`。當請求未消耗任何 MCP 工具結果時不存在。在 v2.1.222 之前，Claude Code 在每個 MCP 工具呼叫後的每個請求上設定此屬性，而不僅是在消耗工具結果的請求上，因此聚合它的儀表板在升級後會顯示下降。

659* `mcp_tool.name`：此請求消耗其結果的 MCP 工具，具有與 `mcp_server.name` 相同的編輯和版本行為。當請求未消耗任何 MCP 工具結果時不存在。661* `mcp_tool.name`：此請求消耗其結果的 MCP 工具，具有與 `mcp_server.name` 相同的編輯和版本行為。當請求未消耗任何 MCP 工具結果時不存在。

660 662

661<h4 id="token-counter">663<h4 id="token-counter">

1086* `marketplace.name`：外掛程式的安裝來源市場（已知時）。在與 `plugin.name` 相同的條件下編輯為 `"third-party"`1088* `marketplace.name`：外掛程式的安裝來源市場（已知時）。在與 `plugin.name` 相同的條件下編輯為 `"third-party"`

1087* `plugin.version`：來自外掛程式資訊清單的版本。僅當名稱未編輯且資訊清單宣告版本時才包含1089* `plugin.version`：來自外掛程式資訊清單的版本。僅當名稱未編輯且資訊清單宣告版本時才包含

1088* `plugin.scope`：外掛程式的來源類別：`"official"`、`"community"`、`"org"`、`"user-local"` 或 `"default-bundle"`1090* `plugin.scope`：外掛程式的來源類別：`"official"`、`"community"`、`"org"`、`"user-local"` 或 `"default-bundle"`

1089* `enabled_via`：外掛程式啟用的方式：`"default-enable"`、`"org-policy"`、`"admin-install"`、`"seed-mount"` 或 `"user-install"`。`"admin-install"` 值表示外掛程式在[**組織設定 > 外掛程式**](https://claude.ai/admin-settings/plugins)中設定為您的組織所需或自動安裝。在 v2.1.246 之前，Claude Code 將這些外掛程式報告為 `"user-install"` 或 `"seed-mount"`1091* `enabled_via`：外掛程式啟用的方式：`"default-enable"`、`"org-policy"`、`"admin-install"`、`"seed-mount"` 或 `"user-install"`。`"admin-install"` 值表示外掛程式在[**組織設定 > 外掛程式與技能**](https://claude.ai/admin-settings/skills?tab=inventory)中設定為您的組織所需或自動安裝。在 v2.1.246 之前，Claude Code 將這些外掛程式報告為 `"user-install"` 或 `"seed-mount"`

1090* `plugin_id_hash`：外掛程式名稱和市場的確定性雜湊，僅傳送到您設定的匯出器。可讓您計算整個車隊中載入的不同第三方外掛程式，而無需記錄其名稱。對於[從 claude.ai 同步的外掛程式](/docs/zh-TW/plugins-reference#synced-plugins)，Claude Code 使用 claude.ai 為外掛程式報告的市場名稱或 `synced` 雜湊外掛程式名稱。在 v2.1.246 之前，Claude Code 在雜湊中未使用 claude.ai 報告的市場名稱1092* `plugin_id_hash`：外掛程式名稱和市場的確定性雜湊，僅傳送到您設定的匯出器。可讓您計算整個車隊中載入的不同第三方外掛程式，而無需記錄其名稱。對於[從 claude.ai 同步的外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)，Claude Code 使用 claude.ai 為外掛程式報告的市場名稱或 `synced` 雜湊外掛程式名稱。在 v2.1.246 之前，Claude Code 在雜湊中未使用 claude.ai 報告的市場名稱

1091* `has_hooks`：外掛程式是否貢獻鉤子1093* `has_hooks`：外掛程式是否貢獻鉤子

1092* `has_mcp`：外掛程式是否貢獻 MCP 伺服器1094* `has_mcp`：外掛程式是否貢獻 MCP 伺服器

1093* `host_owned_mcp`：當 SDK 主機管理此外掛程式的 MCP 連線且 Claude Code 跳過讀取外掛程式的 MCP 伺服器設定時為 `true`，否則為 `false`。需要 Claude Code v2.1.172 或更新版本1095* `host_owned_mcp`：當 SDK 主機管理此外掛程式的 MCP 連線且 Claude Code 跳過讀取外掛程式的 MCP 伺服器設定時為 `true`，否則為 `false`。需要 Claude Code v2.1.172 或更新版本

1363* 在受管設定、使用者設定或 `--settings` 的 `env` 區塊中設定它，或在您啟動 Claude Code 的環境中設定。專案或本機設定中的值不會啟用它，因為複製的儲存庫可以寫入它們。1365* 在受管設定、使用者設定或 `--settings` 的 `env` 區塊中設定它，或在您啟動 Claude Code 的環境中設定。專案或本機設定中的值不會啟用它，因為複製的儲存庫可以寫入它們。

1364* 伺服器受管設定可以在不顯示[安全核准對話](/docs/zh-TW/server-managed-settings#security-approval-dialogs)的情況下設定它，因為變數只會將您組織自己的編輯原則新增到您的組織已接收的事件。1366* 伺服器受管設定可以在不顯示[安全核准對話](/docs/zh-TW/server-managed-settings#security-approval-dialogs)的情況下設定它，因為變數只會將您組織自己的編輯原則新增到您的組織已接收的事件。

1365 1367

1366在您尚未[信任](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)的資料夾中的互動工作階段中，Claude Code 不會匯出拒絕事件，因為專案和本機設定可能會在信任前將匯出指向不同的收集器。1368在您尚未[信任](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)的資料夾中的互動工作階段中，Claude Code 不會匯出拒絕事件。

1367 1369

1368**事件名稱**：`claude_code.managed_settings_resolved`1370**事件名稱**：`claude_code.managed_settings_resolved`

1369 1371

network-config.md +1 −1

Details

245| `registry.npmjs.org` | 外掛程式安裝（擷取 npm 來源外掛程式套件和安裝外掛程式的 Node.js 套件相依性）、`npx` 啟動的 MCP 伺服器，以及 npm 和 bun 安裝 Claude Code 本身的套件登錄 |245| `registry.npmjs.org` | 外掛程式安裝（擷取 npm 來源外掛程式套件和安裝外掛程式的 Node.js 套件相依性）、`npx` 啟動的 MCP 伺服器，以及 npm 和 bun 安裝 Claude Code 本身的套件登錄 |

247| `*.frame.claudeusercontent.com` | [Artifact](/docs/zh-TW/artifacts) 內容讀取。當 Claude 開啟 Artifact 時，CLI 會從此主機擷取 Artifact 的檔案，且僅當 Artifact 工具[可用](/docs/zh-TW/artifacts#availability)於您的帳戶時。若要關閉工具並移除此需求，請設定 [`"enableArtifact": false`](/docs/zh-TW/settings-reference#enableartifact) 或 [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/zh-TW/env-vars)；Claude Code 也會遵守已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 設定。請參閱[停用 Artifact](/docs/zh-TW/artifacts#disable-artifacts) 以了解這些設定如何互動 |247| `*.frame.claudeusercontent.com` | [Artifact](/docs/zh-TW/artifacts) 內容讀取。當 Claude 開啟 Artifact 時，CLI 會從此主機擷取 Artifact 的檔案，且僅當 Artifact 工具[可用](/docs/zh-TW/artifacts#availability)於您的帳戶時。若要關閉工具並移除此需求，請設定 [`"enableArtifact": false`](/docs/zh-TW/settings-reference#enableartifact) 或 [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/zh-TW/env-vars)；Claude Code 也會遵守已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 設定。請參閱[停用 Artifact](/docs/zh-TW/artifacts#disable-artifacts) 以了解這些設定如何互動 |

248| `github.com` | 複製 GitHub 託管的[外掛程式市集](/docs/zh-TW/plugin-marketplaces)和外掛程式，包括官方 Anthropic 市集，透過 HTTPS 或 SSH。若要僅透過 HTTPS 複製 GitHub `owner/repo` 來源，請設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars) |248| `github.com` | 複製 GitHub 託管的[外掛程式市集](/docs/zh-TW/plugins/overview)和外掛程式，包括官方 Anthropic 市集，透過 HTTPS 或 SSH。若要僅透過 HTTPS 複製 GitHub `owner/repo` 來源，請設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars) |

249| `raw.githubusercontent.com` | [`/release-notes`](/docs/zh-TW/commands) 的變更日誌摘要。在互動式工作階段中，Claude Code 也會在啟動時在背景擷取它，當其快取的變更日誌尚未涵蓋執行中的版本時，例如更新後的首次啟動；非互動式和雲端工作階段永遠不會擷取它 |249| `raw.githubusercontent.com` | [`/release-notes`](/docs/zh-TW/commands) 的變更日誌摘要。在互動式工作階段中，Claude Code 也會在啟動時在背景擷取它，當其快取的變更日誌尚未涵蓋執行中的版本時，例如更新後的首次啟動；非互動式和雲端工作階段永遠不會擷取它 |

250| `*-review.googlesource.com` | 在 `googlesource.com` 簽出上進行 Gerrit 變更查詢。當 Claude Desktop Code 索引標籤工作階段在[受信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)的簽出上啟動或繼續時，其 `origin` 是 `googlesource.com` 主機，Claude Code 會匿名詢問該主機的 `-review` 伺服器，以取得與 HEAD 的 `Change-Id` 相符的開啟變更，每次啟動或繼續一次。其他工作階段類型會略過查詢，且不會連線到其他 Gerrit 主機。選用：使用 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 停用 |250| `*-review.googlesource.com` | 在 `googlesource.com` 簽出上進行 Gerrit 變更查詢。當 Claude Desktop Code 索引標籤工作階段在[受信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)的簽出上啟動或繼續時，其 `origin` 是 `googlesource.com` 主機，Claude Code 會匿名詢問該主機的 `-review` 伺服器，以取得與 HEAD 的 `Change-Id` 相符的開啟變更，每次啟動或繼續一次。其他工作階段類型會略過查詢，且不會連線到其他 Gerrit 主機。選用：使用 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 停用 |

251| `http-intake.logs.us5.datadoghq.com` | 操作遙測事件，僅在 CLI 直接使用 Anthropic API 時傳送，絕不會用於 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。選用：使用 [`DISABLE_TELEMETRY`](/docs/zh-TW/data-usage#telemetry-services) 或 `DO_NOT_TRACK` 停用 |251| `http-intake.logs.us5.datadoghq.com` | 操作遙測事件，僅在 CLI 直接使用 Anthropic API 時傳送，絕不會用於 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。選用：使用 [`DISABLE_TELEMETRY`](/docs/zh-TW/data-usage#telemetry-services) 或 `DO_NOT_TRACK` 停用 |

output-styles.md +2 −2

Details

171 </Step>171 </Step>

172</Steps>172</Steps>

173 173

174[Plugins](/docs/zh-TW/plugins-reference) 也可以在 `output-styles/` 目錄中提供輸出樣式。174[Plugins](/docs/zh-TW/plugins/manifest-reference) 也可以在 `output-styles/` 目錄中提供輸出樣式。

175 175

176<h3 id="frontmatter">176<h3 id="frontmatter">

177 Frontmatter 參考177 Frontmatter 參考

228 228

229* [Settings](/docs/zh-TW/settings)：`outputStyle` 欄位所在位置以及設定優先順序的工作原理229* [Settings](/docs/zh-TW/settings)：`outputStyle` 欄位所在位置以及設定優先順序的工作原理

230* [Permission modes](/docs/zh-TW/permission-modes)：Proactive 樣式與自動模式的比較方式230* [Permission modes](/docs/zh-TW/permission-modes)：Proactive 樣式與自動模式的比較方式

231* [Plugins](/docs/zh-TW/plugins)：與 skills、hooks 和 agents 一起打包和分發輸出樣式231* [Plugins](/docs/zh-TW/plugins/overview)：與 skills、hooks 和 agents 一起打包和分發輸出樣式

232* [Debug your configuration](/docs/zh-TW/debug-your-config)：診斷為什麼輸出樣式沒有生效232* [Debug your configuration](/docs/zh-TW/debug-your-config)：診斷為什麼輸出樣式沒有生效

permission-modes.md +13 −2

Details

332 伺服器端分類器審查332 伺服器端分類器審查

333</h3>333</h3>

334 334

335在 Enterprise 計畫和使用 Claude API 的帳戶上，在 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，以及每當您將 `ANTHROPIC_BASE_URL` 指向[LLM 閘道或代理](/docs/zh-TW/llm-gateway)時，自動模式中的 Claude Code 要求伺服器審查[進入分類器的操作](#how-the-classifier-evaluates-actions)作為會話模型請求的一部分。伺服器審查它們的地方，其判決決定了這些操作。它不審查的地方，最常見的原因是 LLM 閘道或代理干擾了流量，或因為平台、區域或認證還沒有伺服器端檢查，Claude Code 會回退到自己的分類器請求，一旦該回退在會話的其餘部分保持，它會在那些請求被計費的帳戶上顯示[關於分類器請求費用的通知](/docs/zh-TW/auto-mode-classifier-billing)。要跳過詢問伺服器並始終使用 Claude Code 自己的分類器請求，請設定 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/zh-TW/env-vars)。該變數在直接連接到 Anthropic API 時不被讀取。如果您設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 並保持 `CLAUDE_CODE_AUTO_MODE_SERVER` 未設定，Claude Code 也會停止詢問伺服器。335在自動模式中，Claude Code 可以要求伺服器檢查[決策順序](#how-the-classifier-evaluates-actions)發送進行審查的操作，作為會話模型請求的一部分，而不是發送自己的分類器請求。這些會話詢問：

336 336

337預設詢問伺服器需要 Claude Code v2.1.278 或更新版本。337* **直接連接到 Anthropic API**：在互動式終端會話中，在每個 claude.ai 計畫和使用 Claude API 的帳戶上，隨著 Anthropic 推出。在 Pro、Max 和 Team 計畫上需要 Claude Code v2.1.271 或更新版本，在 Enterprise 計畫和 Claude API 帳戶上需要 v2.1.278 或更新版本。從 v2.1.282 開始，[不提取功能標誌](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的會話，例如因為您關閉了遙測，預設在任何類型的會話中詢問伺服器。

338* **雲端提供者、LLM 閘道或代理**：在 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，以及每當您將 `ANTHROPIC_BASE_URL` 指向[LLM 閘道或代理](/docs/zh-TW/llm-gateway)時，無論您的計畫如何。預設詢問伺服器需要 Claude Code v2.1.278 或更新版本。

339* **已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)會話**：需要 Claude Code v2.1.280 或更新版本

340

341伺服器審查操作的地方，其判決決定了它們。另外兩個結果是可能的：

342

343* **伺服器不審查會話**：回應完成時沒有審查結果，或伺服器回答它不審查此會話。最常見的原因是 LLM 閘道或代理丟棄了審查請求或結果，以及平台、區域或認證還沒有伺服器端檢查。Claude Code 回退到自己的分類器請求。一旦該回退在會話的其餘部分保持，它會在那些請求被計費的帳戶上顯示[關於分類器請求費用的通知](/docs/zh-TW/auto-mode-classifier-billing)。

344* **伺服器對操作沒有給出判決**：Claude Code 拒絕該操作而不是執行它未審查。在任何連接上，當回應在審查結果到達之前結束或結果以 Claude Code 無法讀取的形式到達時，會發生這種情況。LLM 閘道或代理可能會導致任一情況。在直接連接到 Anthropic API 時，當伺服器對操作的檢查失敗時，例如超時，也會發生這種情況。[伺服器沒有返回安全判決](/docs/zh-TW/errors#the-server-returned-no-safety-verdict)涵蓋拒絕訊息、拒絕重複時會發生什麼以及應對方法。

345

346要跳過詢問伺服器並始終使用 Claude Code 自己的分類器請求，請設定 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/zh-TW/env-vars)。在直接連接到 Anthropic API 時，該變數需要 Claude Code v2.1.281 或更新版本。將其設定為 `1` 會在沒有伺服器審查的會話中打開伺服器審查，例如 `-p` 或 Agent SDK 會話，除非您也設定了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。如果您設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 並保持 `CLAUDE_CODE_AUTO_MODE_SERVER` 未設定，Claude Code 也會停止詢問伺服器。

338 347

339<h3 id="what-the-classifier-blocks-by-default">348<h3 id="what-the-classifier-blocks-by-default">

340 分類器預設阻止的內容349 分類器預設阻止的內容

476* **被阻止的操作**：Claude Code 顯示通知並在 `/permissions` 下的 **Recently denied** 標籤中列出操作，您可以按 `r` 使用手動批准重試它。當分類器對操作[沒有產生判決](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)時，因為自動模式以外的安全檢查拒絕了分類器自己的請求或其回應沒有解析，Claude Code 拒絕該操作而沒有通知或 **Recently denied** 條目。485* **被阻止的操作**：Claude Code 顯示通知並在 `/permissions` 下的 **Recently denied** 標籤中列出操作，您可以按 `r` 使用手動批准重試它。當分類器對操作[沒有產生判決](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)時，因為自動模式以外的安全檢查拒絕了分類器自己的請求或其回應沒有解析，Claude Code 拒絕該操作而沒有通知或 **Recently denied** 條目。

477* **重複塊**：如果分類器連續 3 次或總共 20 次阻止操作，自動模式暫停，Claude Code 恢復提示。批准提示的操作會恢復自動模式。這些閾值不可配置。任何允許的操作重置連續計數器，而總計數器在會話期間持續，僅在其自己的限制觸發回退時重置。當[自動模式以外的安全檢查拒絕分類器的請求](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)時，Claude Code 不會計算拒絕以達到任一閾值；連結的條目涵蓋 Claude Code 如何處理這些拒絕。486* **重複塊**：如果分類器連續 3 次或總共 20 次阻止操作，自動模式暫停，Claude Code 恢復提示。批准提示的操作會恢復自動模式。這些閾值不可配置。任何允許的操作重置連續計數器，而總計數器在會話期間持續，僅在其自己的限制觸發回退時重置。當[自動模式以外的安全檢查拒絕分類器的請求](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)時，Claude Code 不會計算拒絕以達到任一閾值；連結的條目涵蓋 Claude Code 如何處理這些拒絕。

478* **無法提示的會話**：沒有 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 的[非互動式](/docs/zh-TW/headless) `-p` 執行沒有回退提示。當重複塊達到閾值時，操作不執行，Claude 繼續工作。當[自動模式以外的安全檢查拒絕分類器的請求](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)時也適用相同情況。Claude Code 在任一情況下都不會停止執行。487* **無法提示的會話**：沒有 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 的[非互動式](/docs/zh-TW/headless) `-p` 執行沒有回退提示。當重複塊達到閾值時，操作不執行，Claude 繼續工作。當[自動模式以外的安全檢查拒絕分類器的請求](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)時也適用相同情況。Claude Code 在任一情況下都不會停止執行。

488* **伺服器沒有返回安全判決**：在[伺服器端分類器審查](#server-side-classifier-review)下，Claude Code 拒絕伺服器沒有給出判決的操作，並在一行中十個回應沒有判決後停止轉向。請參閱[伺服器沒有返回安全判決](/docs/zh-TW/errors#the-server-returned-no-safety-verdict)。

479* **檢查期間的模式切換**：如果您在分類器檢查待處理時切換權限模式，Claude Code 會丟棄新模式不會請求的判決，而不是應用它：您會被提示進行批准，或在 [`dontAsk` 模式](#allow-only-pre-approved-tools-with-dontask-mode)中自動拒絕操作。489* **檢查期間的模式切換**：如果您在分類器檢查待處理時切換權限模式，Claude Code 會丟棄新模式不會請求的判決，而不是應用它：您會被提示進行批准，或在 [`dontAsk` 模式](#allow-only-pre-approved-tools-with-dontask-mode)中自動拒絕操作。

480 490

481重複塊通常意味著分類器缺少關於您的基礎設施的上下文。使用 `/feedback` 報告誤報，或讓管理員[配置受信任的基礎設施](/docs/zh-TW/auto-mode-config)。491重複塊通常意味著分類器缺少關於您的基礎設施的上下文。使用 `/feedback` 報告誤報，或讓管理員[配置受信任的基礎設施](/docs/zh-TW/auto-mode-config)。

492 * 攜帶[按命令允許的域](/docs/zh-TW/sandboxing#per-command-allowed-domains-in-auto-mode)的 shell 命令也會路由到分類器，即使允許規則相符，因為規則批准命令，而不是其主機502 * 攜帶[按命令允許的域](/docs/zh-TW/sandboxing#per-command-allowed-domains-in-auto-mode)的 shell 命令也會路由到分類器，即使允許規則相符，因為規則批准命令，而不是其主機

493 * 在命令內容上相符的詢問規則，例如 `Bash(git push *)`，回退到權限提示503 * 在命令內容上相符的詢問規則，例如 `Bash(git push *)`，回退到權限提示

494 2. 唯讀操作和您工作目錄中的檔案編輯會自動批准，除了寫入[受保護路徑](#protected-paths)和[工作目錄外的第一次讀取](#first-read-outside-the-working-directories)，這會提示您504 2. 唯讀操作和您工作目錄中的檔案編輯會自動批准，除了寫入[受保護路徑](#protected-paths)和[工作目錄外的第一次讀取](#first-read-outside-the-working-directories)，這會提示您

505 * 在具有[伺服器端分類器審查](#server-side-classifier-review)的會話中，唯讀和[沙箱](/docs/zh-TW/sandboxing#sandbox-modes) shell 命令等待該審查，如果它標記它們則被阻止

495 3. 其他所有內容都進入分類器。在步驟 1 中直接提示您的連接器工具和 `requiresUserInteraction` MCP 工具永遠不會到達分類器，因此既不是組織要求的批准也不是同意步驟會自動批准506 3. 其他所有內容都進入分類器。在步驟 1 中直接提示您的連接器工具和 `requiresUserInteraction` MCP 工具永遠不會到達分類器，因此既不是組織要求的批准也不是同意步驟會自動批准

496 4. 如果分類器阻止，Claude 收到原因並嘗試替代方案。在大多數會話中，原因命名分類器相符的規則，例如 `[Data Exfiltration]`，而不是給出書面解釋；請參閱[審查拒絕](/docs/zh-TW/auto-mode-config#review-denials)507 4. 如果分類器阻止，Claude 收到原因並嘗試替代方案。在大多數會話中，原因命名分類器相符的規則，例如 `[Data Exfiltration]`，而不是給出書面解釋；請參閱[審查拒絕](/docs/zh-TW/auto-mode-config#review-denials)

497 508

permissions.md +5 −5

Details

278 唯讀命令278 唯讀命令

279</h4>279</h4>

280 280

281Claude Code 將一組內建的 Bash 命令識別為唯讀，並在每種模式中無需權限提示即可執行它們，除了 [`permissions.blockReadsOutsideWorkingDirectories`](/docs/zh-TW/settings-reference#permissions-blockreadsoutsideworkingdirectories) 限制的路徑。該集合包括 `ls`、`cat`、`echo`、`pwd`、`head`、`tail`、`grep`、`find`、`wc`、`which`、`diff`、`stat`、`du`、`cd` 和 `git` 的唯讀形式。該集合不可設定；若要要求其中一個命令的提示，請為其新增 `ask` 或 `deny` 規則。281Claude Code 將一組內建的 Bash 命令識別為唯讀，並在每種模式中無需權限提示即可執行它們，除了 [`permissions.blockReadsOutsideWorkingDirectories`](/docs/zh-TW/settings-reference#permissions-blockreadsoutsideworkingdirectories) 限制的路徑。該集合包括 `ls`、`cat`、`echo`、`pwd`、`head`、`tail`、`grep`、`find`、`wc`、`which`、`diff`、`stat`、`du`、`cd` 和 `git` 的唯讀形式。該集合不可設定；若要要求其中一個命令的提示，請為其新增 `ask` 或 `deny` 規則。在自動模式中，這些命令也可以等待分類器的檢查；請參閱[分類器如何評估動作](/docs/zh-TW/permission-modes#how-the-classifier-evaluates-actions)。

282 282

283像 `ls > out.txt` 這樣的重新導向會在目標上新增檢查。請參閱[重新導向](#redirections)。283像 `ls > out.txt` 這樣的重新導向會在目標上新增檢查。請參閱[重新導向](#redirections)。

284 284

605 605

606* 其專案設定，包括其權限規則和 [hooks](/docs/zh-TW/hooks)606* 其專案設定，包括其權限規則和 [hooks](/docs/zh-TW/hooks)

607* 其 [`.mcp.json` 伺服器](/docs/zh-TW/mcp#project-scope)，受限於與啟動時相同的[伺服器核准](/docs/zh-TW/mcp#project-server-approvals-and-workspace-trust)，以及您在其中註冊的[本機範圍](/docs/zh-TW/mcp#local-scope) MCP 伺服器607* 其 [`.mcp.json` 伺服器](/docs/zh-TW/mcp#project-scope)，受限於與啟動時相同的[伺服器核准](/docs/zh-TW/mcp#project-server-approvals-and-workspace-trust)，以及您在其中註冊的[本機範圍](/docs/zh-TW/mcp#local-scope) MCP 伺服器

608* 其設定啟用的 [plugins](/docs/zh-TW/plugins)、其 [skills](/docs/zh-TW/skills#discovery-from-parent-and-nested-directories) 和其 [subagents](/docs/zh-TW/sub-agents)608* 其設定啟用的 [plugins](/docs/zh-TW/plugins/overview)、其 [skills](/docs/zh-TW/skills#discovery-from-parent-and-nested-directories) 和其 [subagents](/docs/zh-TW/sub-agents)

609* 其 [`env`](/docs/zh-TW/settings-reference#env) 值，套用在前一個目錄設定的環境變數之上，這些變數保持有效609* 其 [`env`](/docs/zh-TW/settings-reference#env) 值，套用在前一個目錄設定的環境變數之上，這些變數保持有效

610 610

611Claude Code 也會斷開前一個目錄的專案和[本機範圍](/docs/zh-TW/mcp#local-scope) MCP 伺服器，以及移動後不再啟用的 [plugins](/docs/zh-TW/mcp#plugin-provided-mcp-servers) 的伺服器。它從新目錄的設定而不是前一個目錄的設定中取得[其他目錄](#working-directories)，並保留您使用 `--add-dir` 或 `/add-dir` 新增的目錄。移動啟用的 Hooks 仍會收到 [`${CLAUDE_PROJECT_DIR}`](/docs/zh-TW/hooks#reference-scripts-by-path) 設定為工作階段啟動的專案根目錄。611Claude Code 也會斷開前一個目錄的專案和[本機範圍](/docs/zh-TW/mcp#local-scope) MCP 伺服器，以及移動後不再啟用的 [plugins](/docs/zh-TW/mcp#plugin-provided-mcp-servers) 的伺服器。它從新目錄的設定而不是前一個目錄的設定中取得[其他目錄](#working-directories)，並保留您使用 `--add-dir` 或 `/add-dir` 新增的目錄。移動啟用的 Hooks 仍會收到 [`${CLAUDE_PROJECT_DIR}`](/docs/zh-TW/hooks#reference-scripts-by-path) 設定為工作階段啟動的專案根目錄。

641若要在專案間共享該設定，請使用以下方法之一：641若要在專案間共享該設定，請使用以下方法之一：

642 642

643* **使用者級別設定**：將檔案放在 `~/.claude/agents/`、`~/.claude/output-styles/` 或 `~/.claude/settings.json` 中，使其在每個專案中可用643* **使用者級別設定**：將檔案放在 `~/.claude/agents/`、`~/.claude/output-styles/` 或 `~/.claude/settings.json` 中，使其在每個專案中可用

644* **Plugins**：將設定打包並分發為 [plugin](/docs/zh-TW/plugins)，供團隊安裝644* **Plugins**：將設定打包並分發為 [plugin](/docs/zh-TW/plugins/overview)，供團隊安裝

645* **從設定目錄啟動**：從包含您想要的 `.claude/` 設定的目錄執行 Claude Code645* **從設定目錄啟動**：從包含您想要的 `.claude/` 設定的目錄執行 Claude Code

646 646

647<h2 id="how-permissions-interact-with-sandboxing">647<h2 id="how-permissions-interact-with-sandboxing">

729每一列是儲存庫可以提供的一種內容。列是您尚未信任資料夾本身的兩種情況：您只信任了父資料夾，或您在那裡執行了 `claude -p` 或 SDK，這永遠不會顯示信任對話框。父資料夾列不適用於[巢狀儲存庫](#project-allow-rules-and-workspace-trust)內：在互動工作階段中 Claude Code 會為其顯示信任對話框，`claude -p` 或 SDK 執行會遵循 `claude -p` 列。729每一列是儲存庫可以提供的一種內容。列是您尚未信任資料夾本身的兩種情況：您只信任了父資料夾，或您在那裡執行了 `claude -p` 或 SDK，這永遠不會顯示信任對話框。父資料夾列不適用於[巢狀儲存庫](#project-allow-rules-and-workspace-trust)內：在互動工作階段中 Claude Code 會為其顯示信任對話框，`claude -p` 或 SDK 執行會遵循 `claude -p` 列。

730 730

732| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------- |732| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------- |

733| 設定檔案中的 [Hooks](/docs/zh-TW/hooks)、[`env`](/docs/zh-TW/settings-reference#env) 區塊和輔助命令（例如 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper)），以及專案技能的 [hooks](/docs/zh-TW/hooks#hooks-in-skills-and-agents) 和 [`allowed-tools`](/docs/zh-TW/skills#pre-approve-tools-for-a-skill) | 已使用 | 已使用。工作區信任在任何工作階段中都不會限制技能的 `allowed-tools` |733| 設定檔案中的 [Hooks](/docs/zh-TW/hooks)、[`env`](/docs/zh-TW/settings-reference#env) 區塊和輔助命令（例如 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper)），以及專案技能的 [hooks](/docs/zh-TW/hooks#hooks-in-skills-and-agents) 和 [`allowed-tools`](/docs/zh-TW/skills#pre-approve-tools-for-a-skill) | 已使用 | 已使用。工作區信任在任何工作階段中都不會限制技能的 `allowed-tools` |

734| `.claude/settings.json` 中的 `permissions.allow` 規則和 `additionalDirectories` | 在您接受信任對話框之前不使用，對話框會再次出現列出它們 | 不使用。Claude Code 會列印 [`this workspace has not been trusted`](/docs/zh-TW/errors#workspace-has-not-been-trusted) 警告到 stderr |734| `.claude/settings.json` 中的 `permissions.allow` 規則和 `additionalDirectories` | 在您接受信任對話框之前不使用，對話框會再次出現列出它們 | 不使用。Claude Code 會列印 [`this workspace has not been trusted`](/docs/zh-TW/errors#workspace-has-not-been-trusted) 警告到 stderr |

735| 專案 [subagent](/docs/zh-TW/sub-agents#hooks-in-subagent-frontmatter) 中的 frontmatter hooks、專案 [`@skills-dir` 外掛程式](/docs/zh-TW/plugins-reference#skills-directory-plugins)，以及來自儲存庫或 `--add-dir` 目錄的 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目 | 不使用，不提供對話框 | 不使用 |735| 專案 [subagent](/docs/zh-TW/sub-agents#hooks-in-subagent-frontmatter) 中的 frontmatter hooks、專案 [`@skills-dir` 外掛程式](/docs/zh-TW/plugins/loading#plugins-shared-through-a-repository)，以及來自儲存庫或 `--add-dir` 目錄的 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目 | 不使用，不提供對話框 | 不使用 |

736| 來自儲存庫或 `--add-dir` 目錄的 subagent 的 frontmatter 中的內聯 [`mcpServers`](/docs/zh-TW/sub-agents#scope-mcp-servers-to-a-subagent)。在 v2.1.238 之前，Claude Code 在兩種情況下都載入這些伺服器 | 不使用，不提供對話框 | 不使用 |736| 來自儲存庫或 `--add-dir` 目錄的 subagent 的 frontmatter 中的內聯 [`mcpServers`](/docs/zh-TW/sub-agents#scope-mcp-servers-to-a-subagent)。在 v2.1.238 之前，Claude Code 在兩種情況下都載入這些伺服器 | 不使用，不提供對話框 | 不使用 |

737| `.mcp.json` 中的伺服器，包括儲存庫[在其自己的設定中批准的伺服器](/docs/zh-TW/mcp#project-server-approvals-and-workspace-trust) | Claude Code 在連接它們之前會詢問您。儲存庫自己的批准不計算 | 連接而不詢問，無論是否批准。SDK 只在 `settingSources` 包含專案設定時才載入它們。同一資料夾中的 `claude mcp list` 仍然將此類伺服器報告為待處理 |737| `.mcp.json` 中的伺服器，包括儲存庫[在其自己的設定中批准的伺服器](/docs/zh-TW/mcp#project-server-approvals-and-workspace-trust) | Claude Code 在連接它們之前會詢問您。儲存庫自己的批准不計算 | 連接而不詢問，無論是否批准。SDK 只在 `settingSources` 包含專案設定時才載入它們。同一資料夾中的 `claude mcp list` 仍然將此類伺服器報告為待處理 |

738| `.mcp.json` 中伺服器上的 [`headersHelper`](/docs/zh-TW/mcp#trust-a-folder-before-its-headershelper-runs)。在 v2.1.238 之前，Claude Code 在兩種情況下都執行輔助程式 | 在您接受信任對話框之前不執行，對話框會再次出現命名輔助程式的聲明位置。Claude Code 在此之前僅使用其靜態 `headers` 連接伺服器 | 不執行。Claude Code 使用其靜態 `headers` 連接伺服器，並為每個伺服器列印 [`headersHelper not run`](/docs/zh-TW/errors#headershelper-not-run) 行到 stderr |738| `.mcp.json` 中伺服器上的 [`headersHelper`](/docs/zh-TW/mcp#trust-a-folder-before-its-headershelper-runs)。在 v2.1.238 之前，Claude Code 在兩種情況下都執行輔助程式 | 在您接受信任對話框之前不執行，對話框會再次出現命名輔助程式的聲明位置。Claude Code 在此之前僅使用其靜態 `headers` 連接伺服器 | 不執行。Claude Code 使用其靜態 `headers` 連接伺服器，並為每個伺服器列印 [`headersHelper not run`](/docs/zh-TW/errors#headershelper-not-run) 行到 stderr |

platforms.md +3 −3

Details

34整合讓 Claude 與程式碼庫外的服務協作。34整合讓 Claude 與程式碼庫外的服務協作。

35 35

36| 整合 | 它的作用 | 用途 |36| 整合 | 它的作用 | 用途 |

~~37| :-------------------------------------- | :--------------------------------- | :--------------------------------------------- |~~37| :----------------------------------------------- | :--------------------------------- | :--------------------------------------------- |

44 44

45對於此處未列出的整合，[MCP servers](/docs/zh-TW/mcp) 和[連接器](/docs/zh-TW/desktop#connect-external-tools)讓您連接幾乎任何東西：Linear、Notion、Google Drive 或您自己的內部 API。45對於此處未列出的整合，[MCP servers](/docs/zh-TW/mcp) 和[連接器](/docs/zh-TW/desktop#connect-external-tools)讓您連接幾乎任何東西：Linear、Notion、Google Drive 或您自己的內部 API。

46 46

87* [GitLab CI/CD](/docs/zh-TW/gitlab-ci-cd)：GitLab 的相同功能87* [GitLab CI/CD](/docs/zh-TW/gitlab-ci-cd)：GitLab 的相同功能

88* [Code Review](/docs/zh-TW/code-review)：每個拉取請求上的自動審查88* [Code Review](/docs/zh-TW/code-review)：每個拉取請求上的自動審查

89* [Slack](/docs/zh-TW/slack)：從團隊聊天發送任務，取回 PR89* [Slack](/docs/zh-TW/slack)：從團隊聊天發送任務，取回 PR

~~90* [Claude Tag](/docs/zh-TW/claude-tag)：在 Team 和 Enterprise 方案上執行 `@Claude` 作為您組織的共享身分~~90* [Claude Tag](https://claude.com/docs/claude-tag)：在 Team 和 Enterprise 方案上執行 `@Claude` 作為您組織的共享身分

91 91

92<h3 id="remote-access">92<h3 id="remote-access">

93 遠端存取93 遠端存取

plugin-dependencies.md +0 −267 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# 限制 plugin 依賴版本~~

~~7> 在 plugin 依賴上聲明版本約束，並將精選 plugin 集合捆綁在一個安裝後面。~~

9一個 plugin 可以通過在 `plugin.json` 或其 marketplace 條目中列出其他 plugin 來依賴它們。預設情況下，依賴會追蹤最新可用版本，因此上游版本發佈可能會在沒有警告的情況下更改您 plugin 的依賴。版本約束讓您可以將依賴保持在經過測試的版本範圍內，直到您選擇升級。

11當您安裝聲明依賴的 plugin 時，Claude Code 會自動解析並安裝它們，除了依賴的 marketplace 條目具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#how-users-accept-the-command) 或 [`headersHelper`](/docs/zh-TW/plugin-marketplaces#how-users-accept-a-headershelper-command) 的依賴，您需要先自行安裝。稍後，`/reload-plugins`、依賴 plugin 的 marketplace 自動更新、重新執行依賴 plugin 上的 `claude plugin install`，以及 `claude plugin marketplace add` 都會在相同規則下安裝任何未安裝的已聲明依賴；如果有一個保持未解決，請參閱[解決依賴錯誤](#resolve-dependency-errors)。

13本指南適用於在 `plugin.json` 中聲明依賴的 plugin 作者，以及標記版本發佈的 marketplace 維護者。此處的依賴是其他 plugin；對於 plugin 本身使用的 npm 和 Bun 套件，請參閱 [Node.js 套件依賴](/docs/zh-TW/plugins-reference#node-js-package-dependencies)。若要安裝具有依賴的 plugin，請參閱[發現並安裝 plugin](/docs/zh-TW/discover-plugins)。如需完整的 manifest 架構，請參閱 [Plugins 參考](/docs/zh-TW/plugins-reference)。

~~15<h2 id="why-constrain-dependency-versions">~~

~~16 為什麼要限制依賴版本~~

~~17</h2>~~

19考慮一個內部 marketplace，其中兩個團隊發佈 plugin。平台團隊維護 `secrets-vault`，這是一個包裝 secrets 後端的 MCP 伺服器。部署團隊維護 `deploy-kit`，它在部署期間調用 `secrets-vault` 來獲取認證。

21`deploy-kit` 已針對 `secrets-vault` v2.1.0 進行測試。沒有版本約束的情況下，下次平台團隊標記重新命名 MCP 工具的版本發佈時，自動更新會將每個工程師的 `secrets-vault` 移至新版本，`deploy-kit` 就會損壞。

23使用版本約束，`deploy-kit` 聲明它需要 `~2.1.0` 範圍內的 `secrets-vault`。安裝了 `deploy-kit` 的工程師會保持在最高匹配的 `2.1.x` 修補程式版本。部署團隊通過發佈具有更寬鬆約束的新 `deploy-kit` 版本，按照自己的時間表進行升級。

~~25<h2 id="declare-a-dependency-with-a-version-constraint">~~

~~26 聲明具有版本約束的依賴~~

~~27</h2>~~

~~29在 plugin 的 `.claude-plugin/plugin.json` 的 `dependencies` 陣列中列出依賴。~~

~~31以下 manifest 聲明了一個未版本化的依賴和一個受約束的依賴：~~

~~33```json .claude-plugin/plugin.json theme={null}~~

~~34{~~

~~35 "name": "deploy-kit",~~

~~36 "version": "3.1.0",~~

~~37 "dependencies": [~~

~~38 "audit-logger",~~

~~39 { "name": "secrets-vault", "version": "~2.1.0" }~~

~~40 ]~~

~~41}~~

~~42```~~

44一個條目可以是只包含 plugin 名稱的純字符串，如 `"audit-logger"` 在 `deploy-kit` manifest 中，它依賴於該 plugin 的 marketplace 提供的任何版本。為了獲得更多控制，請使用具有以下欄位的物件：

46| 欄位 | 類型 | 描述 |

47| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

48| `name` | string | Plugin 名稱。在與聲明 plugin 相同的 marketplace 內解析。必需。 |

49| `version` | string | 一個 [semver 範圍](https://github.com/npm/node-semver#ranges)，例如 `~2.1.0`、`^2.0`、`>=1.4` 或 `=2.1.0`。依賴會在滿足此範圍的最高標記版本處獲取。 |

50| `marketplace` | string | 一個不同的 marketplace 來在其中解析 `name`。跨 marketplace 依賴被阻止，除非目標 marketplace 在根 marketplace 的 `marketplace.json` 中的 [`allowCrossMarketplaceDependenciesOn`](#depend-on-a-plugin-from-another-marketplace) 中列出。 |

~~52預發佈版本（如 `2.0.0-beta.1`）被排除，除非您的範圍使用預發佈後綴（如 `^2.0.0-0`）選擇加入。~~

~~54<h2 id="bundle-plugins-for-a-team">~~

~~55 為團隊組合外掛程式~~

~~56</h2>~~

58除了必需的 `name` 之外，外掛程式資訊清單可以只包含一個 `dependencies` 陣列。安裝它會拉入每個依賴項，這使其成為在一個安裝後面打包精選外掛程式集的方式。

~~60例如，平台團隊可以在內部市場中發佈角色特定的組合，以便工程師執行一個 `claude plugin install` 而不是分別安裝每個工具：~~

~~62```json .claude-plugin/plugin.json theme={null}~~

~~63{~~

~~64 "name": "backend-standard",~~

~~65 "version": "1.0.0",~~

~~66 "description": "Standard plugin set for backend engineers",~~

~~67 "dependencies": [~~

~~68 "secrets-vault",~~

~~69 "deploy-kit",~~

~~70 { "name": "db-migrate", "version": "^3.0" },~~

~~71 "oncall-runbook"~~

~~72 ]~~

~~73}~~

~~74```~~

~~76安裝 `backend-standard` 會解析並安裝所有四個依賴項。~~

78若要稍後將工具新增至標準集，請發佈新的 `backend-standard` 版本並包含額外的依賴項。除非市場[自動更新](/docs/zh-TW/discover-plugins#configure-auto-updates)，工程師可以透過以下兩種方式之一取得新版本：

~~80* 在 `/plugin` 中為市場啟用自動更新。下一次自動更新會將組合移至新版本並安裝它新增的任何依賴項。~~

~~81* 執行 `claude plugin update backend-standard`，然後執行 `/reload-plugins` 以安裝新增的依賴項。~~

~~83若要在整個組織中推出組合，請將組合外掛程式新增至[受管設定](/docs/zh-TW/settings-reference#enabledplugins)中的 `enabledPlugins`。~~

~~85<h2 id="depend-on-a-plugin-from-another-marketplace">~~

~~86 依賴來自另一個 marketplace 的 plugin~~

~~87</h2>~~

~~89預設情況下，Claude Code 拒絕自動安裝位於與聲明它的 plugin 不同的 marketplace 中的依賴。這可防止一個 marketplace 無聲地從您未審查的來源拉入 plugin。~~

91若要允許此操作，根 marketplace 的維護者將目標 marketplace 名稱添加到 `marketplace.json` 中的 `allowCrossMarketplaceDependenciesOn`。根 marketplace 是託管用戶正在安裝的 plugin 的 marketplace；只有其允許清單被查詢，因此信任不會通過中間 marketplace 鏈接。

~~93以下 `marketplace.json` 允許 `deploy-kit` 依賴來自 `acme-shared` 的 plugin：~~

~~95```json .claude-plugin/marketplace.json theme={null}~~

~~96{~~

~~97 "name": "acme-tools",~~

~~98 "owner": { "name": "Acme" },~~

~~99 "allowCrossMarketplaceDependenciesOn": ["acme-shared"],~~

100 "plugins": [

101 {

102 "name": "deploy-kit",

103 "source": "./deploy-kit",

104 "dependencies": [

105 { "name": "audit-logger", "marketplace": "acme-shared" }

106 ]

107 }

108 ]

109}

110```

~~111~~

112如果欄位缺失或不包含目標 marketplace，安裝將失敗，並出現 `cross-marketplace` 錯誤，命名要設置的欄位。用戶仍然可以先手動安裝依賴，這會滿足約束而無需更改允許清單。

~~113~~

114<h2 id="test-a-plugin-and-its-dependency-locally">

115 在本機測試外掛程式及其依賴項

116</h2>

~~117~~

118如果您同時開發一個外掛程式及其所依賴的外掛程式，請使用 `--plugin-dir` 載入兩者：

~~119~~

120```bash theme={null}

121claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

122```

~~123~~

124依賴項的本機副本滿足您外掛程式的依賴項條目，即使該條目命名了市集，您也不需要從其市集安裝依賴項。Claude Code 不會針對本機副本檢查[版本限制](#declare-a-dependency-with-a-version-constraint)，因此本機 `plugin.json` 不需要 `version`。在 v2.1.242 之前，命名市集的依賴項條目永遠不會與本機副本相符，Claude Code 會在載入時停用您的外掛程式。

~~125~~

126當兩個外掛程式位於同一個父資料夾時，您可以將該資料夾傳遞給 `--plugin-dir` 一次。如果該資料夾本身不是外掛程式，Claude Code 會載入每個具有 `.claude-plugin/plugin.json` 的子資料夾。需要 Claude Code v2.1.265 或更新版本。

~~127~~

128如果您尚未從其市集安裝依賴項，當本機副本消失時，您的外掛程式會停止載入：

~~129~~

130* **您停用了本機副本**：Claude Code 會在下一次外掛程式載入時停用您的外掛程式。對於命名市集的依賴項條目，Claude Code 會報告 `Dependency "<name>@inline" is disabled — enable it or remove the dependency`；對於裸名稱條目，它會按其裸名稱報告依賴項。`<name>@inline` 是 Claude Code 識別每個 `--plugin-dir` 和 `--plugin-url` 外掛程式的方式。

131* **您啟動了一個沒有依賴項 `--plugin-dir` 旗標的工作階段**：Claude Code 會報告依賴項未安裝。再次傳遞該旗標，或從其市集安裝依賴項。

~~132~~

133<h2 id="tag-plugin-releases-for-version-resolution">

134 版本解析的標籤外掛程式發佈

135</h2>

~~136~~

137Claude Code 針對託管依賴項的儲存庫上的 git 標籤解析版本約束：`github`、`url` 和 `git-subdir` [外掛程式來源](/docs/zh-TW/plugin-marketplaces#plugin-sources)的外掛程式自身儲存庫，或市集儲存庫中市集透過相對路徑參考的外掛程式。為了讓 Claude Code 找到依賴項的可用版本，上游外掛程式的發佈必須使用特定的命名慣例進行標籤標記。

~~138~~

139將每個發佈標記為 `{plugin-name}--v{version}`，其中 `{version}` 與該提交的 `plugin.json` 中的 `version` 欄位相符。從外掛程式目錄執行：

~~140~~

141```bash theme={null}

142claude plugin tag --push

143```

~~144~~

145`claude plugin tag` 命令從外掛程式的資訊清單和封閉的市集項目衍生標籤名稱。在建立標籤之前，它會驗證外掛程式內容，檢查 `plugin.json` 和市集項目是否在版本上一致，要求外掛程式目錄下的工作樹乾淨，如果標籤已存在則拒絕。

~~146~~

147* `--push` 將標籤推送到 `origin` 遠端，因此儲存庫需要配置的 `origin` 遠端。傳遞 `--remote` 以推送到不同的遠端。

148* 如果推送失敗，標籤仍會在本機建立，命令會以錯誤狀態結束。

149* 使用 `--push` 時，成功執行會以 `Created tag secrets-vault--v2.1.0` 和 `Pushed to origin` 結束，其中最後一行命名推送到的遠端。不使用 `--push` 時，命令會改為列印要執行的 `git push` 命令。

150* `--dry-run` 列印將被標記的內容而不建立它。

~~151~~

152直接執行 `git tag secrets-vault--v2.1.0` 是等效的，如果您自己保持 `plugin.json` 和市集項目同步。

~~153~~

154外掛程式名稱前綴讓一個市集儲存庫可以託管多個具有獨立版本線的外掛程式。`--v` 分隔符被解析為完整外掛程式名稱上的前綴匹配，因此包含連字號的外掛程式名稱會被正確處理。

~~155~~

156當您安裝宣告 `{ "name": "secrets-vault", "version": "~2.1.0" }` 的外掛程式時，Claude Code 會列出託管 `secrets-vault` 的儲存庫上的標籤，篩選以 `secrets-vault--v` 開頭的標籤，並擷取滿足 `~2.1.0` 的最高版本。如果外掛程式自身儲存庫上沒有標籤滿足該範圍，安裝會失敗，並顯示 `Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0`，其中命名依賴項及其市集。對於沒有匹配標籤的相對路徑外掛程式，Claude Code 會改為安裝市集的目前副本，並在外掛程式載入時檢查約束。

~~157~~

158對於市集透過相對路徑參考的外掛程式，作為本機資料夾路徑新增的市集在資料夾是 git 儲存庫時以相同方式解析標籤。這需要 Claude Code v2.1.196 或更新版本。在兩種情況下，Claude Code 會改為從資料夾的目前內容安裝依賴項：

~~159~~

160* 較早版本不會從本機資料夾市集讀取標籤，因此受約束的依賴項只有在該副本滿足範圍時才會載入。

161* 不是 git 儲存庫的本機資料夾沒有標籤，無論版本如何。

~~162~~

163已解析標籤的 semver 與 `plugin.json` 的 `version` 分開記錄，因此約束檢查使用實際擷取的標籤，即使該提交的 `plugin.json` 有過時的值。標籤解析安裝的快取目錄名稱包含 12 字元的提交 SHA 後綴，因此如果維護者強制將標籤移動到不同的提交，下次安裝會取得新的快取目錄，而不是重複使用過時的內容。

~~164~~

165<Note>

166 對於具有 `npm`、`archive` 或 `command` [外掛程式來源](/docs/zh-TW/plugin-marketplaces#plugin-sources)的依賴項，約束不控制擷取的版本，因為標籤型解析僅適用於 git 支援的來源。約束仍會在載入時檢查，如果安裝的版本不滿足約束，依賴外掛程式會被停用，狀態為 `dependency-version-unsatisfied`。對於 `command` 來源，Claude Code 會檢查依賴項的 `plugin.json` 中的版本，並忽略內容雜湊後綴；其 `plugin.json` 未設定版本的依賴項不滿足任何約束，因此在約束它之前請設定一個版本。

~~167~~

168 Claude Code 永遠不會自行安裝具有 `command` 來源的依賴項，因此使用者[首先安裝它](/docs/zh-TW/plugin-marketplaces#how-users-accept-the-command)。Claude Code 也永遠不會在依賴項的市集項目上執行 `headersHelper`，因此使用者[首先安裝該外掛程式](/docs/zh-TW/plugin-marketplaces#how-users-accept-a-headershelper-command)。

169</Note>

~~170~~

171<h2 id="how-constraints-interact">

172 約束如何相互作用

173</h2>

~~174~~

175當多個已安裝的 plugins 限制同一依賴時，Claude Code 會交集它們的範圍，並將依賴解析為滿足所有範圍的最高版本。下表顯示常見組合如何解析。

~~176~~

177| Plugin A 要求 | Plugin B 要求 | 結果 |

178| :---------- | :---------- | :------------------------------------------------------- |

179| `^2.0` | `>=2.1` | 在最高 `2.x` 標籤處進行一次安裝，該標籤位於 `2.1.0` 或更高版本。兩個 plugins 都會載入。 |

180| `~2.1` | `~3.0` | Plugin B 的安裝失敗，出現 `range-conflict` 錯誤。Plugin A 和依賴保持原樣。 |

181| `=2.1.0` | 無 | 依賴保持在 `2.1.0`。在安裝了 Plugin A 時，自動更新會跳過較新版本。 |

~~182~~

183自動更新會在滿足每個已安裝 plugin 範圍的最高 git 標籤處取得受約束的依賴，而不是在 marketplace 的最新版本處，因此依賴會在其允許的範圍內繼續接收更新。如果沒有標籤滿足所有範圍，自動更新會跳過該依賴，並在 `/plugin` 錯誤標籤中列出跳過，並命名限制 plugin。

~~184~~

185當您卸載最後一個限制依賴的 plugin 時，依賴不再被保持，並在下次更新時恢復追蹤其 marketplace 條目。

~~186~~

187<h2 id="enable-or-disable-a-plugin-with-dependencies">

188 啟用或禁用具有依賴的 plugin

189</h2>

~~190~~

191本節涵蓋從 marketplace 安裝的 plugins。對於您使用 `--plugin-dir` 載入的副本，請參閱[在本地測試 plugin 及其依賴](#test-a-plugin-and-its-dependency-locally)。

~~192~~

193啟用 plugin 也會啟用它所依賴的 plugins，禁用 plugin 如果另一個已啟用的 plugin 仍然需要它則會被阻止。

~~194~~

195當您啟用 plugin 時，Claude Code 也會在相同的範圍內啟用其依賴。如果依賴有其自己的依賴，Claude Code 也會啟用那些。成功訊息會列出隨著您命名的 plugin 一起啟用的其他內容。如果依賴無法啟用，命令會拒絕並告訴您什麼在阻止以及如何修復：

~~196~~

197| 條件 | 結果 |

198| :-------------------------- | :------------------------------------------ |

199| 依賴未安裝 | 啟用失敗並為每個遺失的依賴列印 `claude plugin install` 命令。 |

200| 依賴被您組織的 plugin 政策阻止 | 啟用失敗並命名被阻止的依賴。 |

201| 依賴在優先級高於目標範圍的範圍內設置為 `false` | 啟用失敗。在該範圍內啟用依賴，或傳遞 `--scope` 以在那裡寫入。 |

202| 所有依賴都已安裝且被允許 | 啟用成功並為 plugin 和每個在目標範圍內尚未啟用的依賴寫入 `true`。 |

~~203~~

204這甚至在依賴在其 manifest 中設置 [`defaultEnabled: false`](/docs/zh-TW/plugins-reference#default-enablement) 時也成立，因為 Claude Code 為其寫入明確的 `true`。同樣的情況也適用於安裝：為滿足活躍 plugin 而引入的依賴會安裝 `true`，無論其自己的預設值如何。

~~205~~

206當您禁用 plugin 時，Claude Code 拒絕如果另一個已啟用的 plugin 仍然依賴它。錯誤命名依賴它的 plugins 並給您一個鏈接命令，以正確的順序禁用它們，以您要求的那個結尾。

~~207~~

208例如，如果 `deploy-kit` 依賴 `secrets-vault`，單獨禁用 `secrets-vault` 失敗，輸出類似於以下內容：

~~209~~

210```text theme={null}

211secrets-vault is still required by deploy-kit. Disable that plugin first, or

212disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

213```

~~214~~

215從錯誤複製鏈接命令以在一個步驟中禁用完整集合。

~~216~~

217<h2 id="remove-orphaned-auto-installed-dependencies">

218 移除孤立的自動安裝依賴

219</h2>

~~220~~

221自動安裝的依賴在安裝它們的 plugins 被卸載後仍會保留在磁碟上，以防您重新安裝依賴 plugin 或想要直接繼續使用依賴。若要清理它們，請執行 `claude plugin prune` 以列出不再有任何已安裝 plugin 需要的自動安裝依賴，並在確認提示後移除它們。

~~222~~

223```bash theme={null}

224claude plugin prune

225```

~~226~~

227如果沒有任何項目符合移除條件，該命令會列印 `Nothing to prune` 並顯示原因後退出。這是全新安裝時的預期輸出，不是錯誤。

~~228~~

229預設情況下，prune 在使用者範圍內運作，並在移除任何內容前要求確認：

~~230~~

231* `--scope project` 或 `--scope local` 針對不同的範圍。

232* `--dry-run` 列出將被移除的內容而不更改任何內容。

233* `-y` 跳過確認提示。當 stdin 或 stdout 不是終端時，prune 會列出孤立項並退出，除非您傳遞 `-y`。

~~234~~

235若要在卸載時進行 prune，請將 `--prune` 傳遞給 `claude plugin uninstall`。移除命名的 plugin 後，Claude Code 會掃描並移除現在孤立的任何自動安裝依賴。您自己安裝的 plugins 永遠不會被 prune，只有通過另一個 plugin 的 `dependencies` 陣列自動安裝的 plugins 才會被 prune。

~~236~~

237相同的確認行為適用。當 stdin 或 stdout 不是終端時，卸載仍會完成，但 prune 步驟會列出孤立項並且不移除任何內容，除非您傳遞 `-y`。

~~238~~

239例如，若要卸載 `deploy-kit` 並清理它留下的依賴：

~~240~~

241```bash theme={null}

242claude plugin uninstall deploy-kit --prune

243```

~~244~~

245<h2 id="resolve-dependency-errors">

246 解析依賴錯誤

247</h2>

~~248~~

249依賴問題會在 `claude plugin list` 和 `/plugin` 介面中出現，以描述性錯誤訊息的形式呈現，而不是此表中的字面代碼。Claude Code 會禁用受影響的 plugin，直到您解析錯誤。下表列出最常見的錯誤及其解決方法。

~~250~~

251| 錯誤 | 含義 | 如何解析 |

252| :------------------------------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |

253| `dependency-unsatisfied` | 聲明的依賴未安裝，或已安裝但被禁用。 | 執行錯誤訊息中顯示的 `claude plugin install` 命令。如果依賴的 marketplace 尚未配置，請使用 `claude plugin marketplace add` 添加它，Claude Code 將自動解析依賴。如果依賴被禁用，請啟用它。 |

255| `dependency-version-unsatisfied` | 已安裝的依賴版本在此 plugin 的聲明範圍之外。 | 執行 `claude plugin install <dependency>@<marketplace>` 以根據所有當前約束重新解析依賴。 |

256| `no-matching-tag` | 依賴的儲存庫沒有滿足範圍的 `{name}--v*` 標籤。 | 檢查上游是否使用上述約定標記了版本發佈，或放寬您的範圍。 |

~~257~~

258若要以程式設計方式檢查這些錯誤，請執行 `claude plugin list --json`。有問題的 plugin 包含列出這些錯誤的 `errors` 欄位。乾淨載入的 plugin 會省略此欄位。

~~259~~

260<h2 id="see-also">

261 另請參閱

262</h2>

~~263~~

264* [建立 plugins](/docs/zh-TW/plugins)：使用 skills、agents 和 hooks 建立 plugins

265* [建立並分發 plugin marketplace](/docs/zh-TW/plugin-marketplaces)：為您的團隊託管 plugins

266* [Plugins 參考](/docs/zh-TW/plugins-reference#plugin-manifest-schema)：完整的 `plugin.json` 架構

267* [版本管理](/docs/zh-TW/plugins-reference#version-management)：plugin 版本如何被解析並用作快取金鑰

plugin-evals.md +70 −35

Details

6 6

7> 為您的 Claude Code plugin 編寫 eval 案例，使用 claude plugin eval 執行它們，評分結果，與無 plugin 基準線進行比較，並在 CI 中根據分數進行把關。7> 為您的 Claude Code plugin 編寫 eval 案例，使用 claude plugin eval 執行它們，評分結果，與無 plugin 基準線進行比較，並在 CI 中根據分數進行把關。

8 8

9`claude plugin eval` 針對一套測試案例執行您的 [plugin](/docs/zh-TW/plugins)，並對結果進行評分。每個案例都是一個真實的提示加上一個或多個評分器。評分器是對 Claude 產生的內容進行的通過/失敗檢查，例如對回覆的正規表達式、是否呼叫了特定工具，或由第二個模型判斷回覆的評分標準。9`claude plugin eval` 針對一套測試案例執行您的 [plugin](/docs/zh-TW/plugins/overview)，並對結果進行評分。每個案例都是一個真實的提示加上一個或多個評分器。評分器是對 Claude 產生的內容進行的通過/失敗檢查，例如對回覆的正規表達式、是否呼叫了特定工具，或由第二個模型判斷回覆的評分標準。

10 10

11您不必手動編寫測試套件；`claude plugin eval init` 會詢問您有關 plugin 的問題，提議案例和評分器，嘗試它們，並編寫檔案。您也可以要求 Claude 從已開啟的工作階段中執行相同操作。11您不必手動編寫測試套件；`claude plugin eval init` 會詢問您有關 plugin 的問題，提議案例和評分器，嘗試它們，並編寫檔案。您也可以要求 Claude 從已開啟的工作階段中執行相同操作。

12 12

13使用 evals 來測量您的 plugin 可靠地引導 Claude 達到正確結果的程度，在您變更 plugin 或新模型發佈時捕捉迴歸，以及查看與沒有 plugin 相比 plugin 的貢獻。13使用 evals 來：

14 14

15本頁面適用於擁有可運作 plugin 並想測試其行為的 plugin 和 skill 作者，以及在 CI 中把關 plugin 變更的團隊。其案例格式與 [skill-creator plugin](/docs/zh-TW/skills#run-evals-with-skill-creator) 使用的 `evals/evals.json` 檔案分開。若要建立 plugin，請參閱 [Create plugins](/docs/zh-TW/plugins)；若要檢查 plugin 的檔案是否存在語法和架構錯誤而不是其行為，請使用 [`claude plugin validate`](/docs/zh-TW/plugins-reference#plugin-validate)。15* 測量您的 plugin 可靠地引導 Claude 達到正確結果的程度

16* 在您變更 plugin 或新模型發佈時捕捉迴歸

17* 查看與沒有 plugin 相比 plugin 的貢獻

19本頁面適用於擁有可運作 plugin 並想測試其行為的 plugin 和 skill 作者，以及在 CI 中把關 plugin 變更的團隊。其案例格式與 [skill-creator plugin](/docs/zh-TW/skills#run-evals-with-skill-creator) 使用的 `evals/evals.json` 檔案分開。若要建立 plugin，請參閱 [建立 plugin](/docs/zh-TW/plugins/create)；若要檢查 plugin 的檔案是否存在語法和架構錯誤而不是其行為，請使用 [`claude plugin validate`](/docs/zh-TW/plugins/cli-reference#plugin-validate)。

16 20

17<Note>21<Note>

18 每次 eval 執行和每個評判評分器都是您帳戶上的真實模型呼叫，計入您的方案使用量或 API 帳單，因此請先檢查 [requirements](#requirements)。然後 [create your first eval suite](#create-your-first-eval-suite)，或如果您已經有一個，請前往 [Run evals in CI](#run-evals-in-ci)。22 每次 eval 執行和每個評判評分器都是您帳戶上的真實模型呼叫，計入您的方案使用量或 API 帳單，因此請先檢查 [requirements](#requirements)。然後 [create your first eval suite](#create-your-first-eval-suite)，或如果您已經有一個，請前往 [Run evals in CI](#run-evals-in-ci)。

25若要執行 plugin evals，您需要：29若要執行 plugin evals，您需要：

26 30

27* Claude Code v2.1.269 或更新版本。執行 `claude --version` 檢查，執行 `claude update` 升級。31* Claude Code v2.1.269 或更新版本。執行 `claude --version` 檢查，執行 `claude update` 升級。

~~28* 具有 `plugin.json` 或 `.claude-plugin/plugin.json` 資訊清單的 plugin 目錄，或 [skills-directory plugin](/docs/zh-TW/plugins-reference#skills-directory-plugins)。~~32* 具有 `plugin.json` 或 `.claude-plugin/plugin.json` 資訊清單的 plugin 目錄，或 [skills-directory plugin](/docs/zh-TW/plugins/loading#plugins-shared-through-a-repository)。

29* 與您的正常 Claude Code 工作階段相同的驗證和模型提供者。Eval 執行、評判評分器和 `claude plugin eval init` 使用您的認證呼叫模型，因此它們計入您的方案使用量限制或 API 帳單。當命令報告成本時，該數字是這些呼叫的 [list-price estimate](/docs/zh-TW/costs)。33* 與您的正常 Claude Code 工作階段相同的驗證和模型提供者。Eval 執行、評判評分器和 `claude plugin eval init` 使用您的認證呼叫模型，因此它們計入您的方案使用量限制或 API 帳單。當命令報告成本時，該數字是這些呼叫的 [list-price estimate](/docs/zh-TW/costs)。

30 34

31<h2 id="how-an-eval-run-works">35<h2 id="how-an-eval-run-works">

32 Eval 執行的運作方式36 Eval 執行的運作方式

33</h2>37</h2>

34 38

35Eval 套件位於 plugin 內名為 `evals/` 的目錄中，其佈局如 [Write and refine cases](#write-and-refine-cases) 所示。每個案例都是其自己的子目錄，包含 [prompt](#set-run-limits-and-tools-in-prompt-md) 和一個或多個 [graders](#grade-the-result)。提示是使用您的 plugin 的人可能輸入的內容，例如其中一個 skills 應該處理的請求。39Eval 套件位於 plugin 內名為 `evals/` 的目錄中，其佈局如 [撰寫和精化案例](#write-and-refine-cases) 所示。每個案例都是其自己的子目錄，包含 [prompt](#set-run-limits-and-tools-in-prompt-md) 和一個或多個 [graders](#grade-the-result)。提示是使用您的 plugin 的人可能輸入的內容，例如其中一個 skills 應該處理的請求。

36 40

37<h3 id="what-happens-in-a-run">41<h3 id="what-happens-in-a-run">

38 執行中發生的情況42 執行中發生的情況

39</h3>43</h3>

40 44

41對於案例的每次執行，Claude Code 啟動一個新的、[isolated](#how-runs-are-isolated) [non-interactive session](/docs/zh-TW/headless)，僅載入您的 plugin，發送提示，並讓 Claude 工作直到完成或達到案例的轉數或時間限制。然後每個評分器檢查最終回覆、完整文字記錄或 Claude 建立的檔案，並通過或失敗。45對於案例的每次執行，Claude Code 啟動一個新的、[隔離](#how-runs-are-isolated) [非互動式工作階段](/docs/zh-TW/headless)，僅載入您的 plugin，發送提示，並讓 Claude 工作直到完成或達到案例的轉數或時間限制。然後每個評分器檢查最終回覆、完整文字記錄或 Claude 建立的檔案，並通過或失敗。

42 46

43<h3 id="how-a-case-is-scored">47<h3 id="how-a-case-is-scored">

44 案例如何評分48 案例如何評分

50 No-plugin 基準線54 No-plugin 基準線

51</h3>55</h3>

52 56

53高分本身並不能告訴您 plugin 是否有幫助，因為 Claude 可能在沒有它的情況下做得同樣好。為了區分兩者，預設情況下每個案例的執行會在沒有載入 plugin 的情況下重複，您會獲得兩個分數：`WITH` 和 `W/OUT`。它們的差異 `Δ` 是 plugin 的貢獻。如果案例在有 plugin 和沒有 plugin 的情況下都得分 1.0，則不是 plugin 使其通過。這兩組執行稱為 with-arm 和 without-arm；[Compare against a no-plugin baseline](#compare-against-a-no-plugin-baseline) 涵蓋評分器如何在它們之間評分以及如何關閉基準線。57高分本身並不能告訴您 plugin 是否有幫助，因為 Claude 可能在沒有它的情況下做得同樣好。為了區分兩者，預設情況下每個案例的執行會在沒有載入 plugin 的情況下重複，您會獲得兩個分數：`WITH` 和 `W/OUT`。它們的差異 `Δ` 是 plugin 的貢獻。如果案例在有 plugin 和沒有 plugin 的情況下都得分 1.0，則不是 plugin 使其通過。

59這兩組執行稱為 with-arm 和 without-arm；[與 no-plugin 基準線比較](#compare-against-a-no-plugin-baseline) 涵蓋評分器如何在它們之間評分以及如何關閉基準線。

54 60

55<h2 id="create-your-first-eval-suite">61<h2 id="create-your-first-eval-suite">

56 建立您的第一個 eval suite62 建立您的第一個 eval suite

184FAIL if <what a wrong or missing response looks like>.190FAIL if <what a wrong or missing response looks like>.

185```191```

186 192

187然後新增第二個 grader，檢查您的技能是否是產生答案的原因。建立 `evals/first-case/graders/skill-fired.md`，將 `your-skill-name` 替換為您技能的 `SKILL.md` 中的 `name`：193然後新增第二個 grader，檢查您的技能是否是產生答案的原因。建立 `evals/first-case/graders/skill-fired.md`，將 `your-skill-name` 替換為 `skills/` 下您技能的目錄名稱，這是 Claude 呼叫它的名稱：

188 194

189```markdown theme={null}195```markdown theme={null}

190---196---

234在雙 arm 執行中，某些 graders 會以 `scored: false` 報告。像「技能已呼叫」這樣的檢查在沒有外掛程式的情況下永遠無法通過，所以計算它會將 without-arm 推向零並誇大 `Δ`。為了保持兩個 arm 可比較，Claude Code 在兩個 arm 中排除此類 graders 的分數，並在 with-arm 中將其報告為僅通過/失敗指標。這包括：240在雙 arm 執行中，某些 graders 會以 `scored: false` 報告。像「技能已呼叫」這樣的檢查在沒有外掛程式的情況下永遠無法通過，所以計算它會將 without-arm 推向零並誇大 `Δ`。為了保持兩個 arm 可比較，Claude Code 在兩個 arm 中排除此類 graders 的分數，並在 with-arm 中將其報告為僅通過/失敗指標。這包括：

235 241

236* 每個 `tool` 為 `Skill` 的 `tool_used` grader242* 每個 `tool` 為 `Skill` 的 `tool_used` grader

243* 每個 `regex` grader 具有 `target: mock_calls` 和每個 `llm` grader 具有 `focus: mock_calls`，當案例中的每個[模擬伺服器](#mock-mcp-servers)都是您的外掛程式宣告的

237* 任何您標記為 `arm: with-only` 的 grader244* 任何您標記為 `arm: with-only` 的 grader

238 245

239如果案例中的每個 grader 都是其中之一，它們會改為正常評分，因為沒有其他內容可評分。在 grader 上設定 `arm: both` 以無論如何在兩個 arm 中評分，這是您想要的「不得呼叫技能」檢查，具有 `min: 0` 和 `max: 0`。在 `--ablation none` 下，沒有任何內容被排除，所以相同的套件在兩種模式中可能產生不同的絕對分數。246三個設定會改變該排除：

247

248* **每個 grader 都被排除**：如果案例中的每個 grader 都在排除集合中，它們會改為正常評分，因為沒有其他內容可評分。

249* **`arm: both`**：在 grader 上設定 `arm: both` 以無論如何在兩個 arm 中評分，這是您想要的「不得呼叫技能」檢查，具有 `min: 0` 和 `max: 0`。

250* **`--ablation none`**：在 `--ablation none` 下，沒有任何內容被排除，所以相同的套件在兩種模式中可能產生不同的絕對分數。

240 251

241<h3 id="use-a-different-eval-directory">252<h3 id="use-a-different-eval-directory">

242 使用不同的 eval 目錄253 使用不同的 eval 目錄

259 Seed the workspace or conversation270 Seed the workspace or conversation

260</h3>271</h3>

261 272

262每次執行都在空工作區中開始。當案例需要的不僅僅是提示時，在 `prompt.md` 旁邊新增 `case.yaml`，其中包含 `context` 區塊。273每次執行都在空工作區中開始。當案例需要的不僅僅是提示時，在 `prompt.md` 旁邊新增 `case.yaml`，其中包含 `context` 區塊：

263 274

264若要首先建立 fixture 檔案或 git 儲存庫，請在案例目錄中編寫 Bash 指令碼並在 `context.scaffold_script` 中命名它。指令碼以您的身份在代理沙箱外執行，僅當您傳遞 `--scaffold` 時，因此僅對您或您的組織編寫的套件傳遞該標誌。若要繼續早期對話，請將文字記錄保存為 `.jsonl` 檔案並在 `context.history_file` 中命名它，案例的提示變成下一個使用者轉數。若要讓 Claude 在執行期間讀取案例中的 fixture 目錄，請在 `context.add_dirs` 中列出它們。275* **Fixture 檔案或 git 儲存庫**：在案例目錄中編寫 Bash 指令碼並在 `context.scaffold_script` 中命名它。指令碼以您的身份在代理沙箱外執行，僅當您傳遞 `--scaffold` 時，因此僅對您或您的組織編寫的套件傳遞該標誌。

276* **要繼續的早期對話**：將文字記錄保存為 `.jsonl` 檔案並在 `context.history_file` 中命名它，案例的提示變成下一個使用者轉數。

277* **Claude 在執行期間可以讀取的 Fixture 目錄**：在 `context.add_dirs` 中列出它們。

265 278

266`case.yaml` 也需要 `schema_version: "1.1"` 和 `name`；[case.yaml fields](#case-yaml-fields) 參考有完整列表。279`case.yaml` 也需要 `schema_version: "1.1"` 和 `name`；[case.yaml fields](#case-yaml-fields) 參考有完整列表。

267 280

280 Mock MCP servers293 Mock MCP servers

281</h3>294</h3>

282 295

283您可以評估 plugin，其 skills 呼叫 MCP 工具，而無需它們後面的真實服務。在 `evals/mocks/<server>/<tool>.md` 下為整個套件放置一個 Markdown 檔案，或在案例自己的 `mocks/` 目錄下為一個案例，其中 `<server>` 是您的 plugin 的 [MCP configuration](/docs/zh-TW/plugins-reference#mcp-servers) 中伺服器的名稱。296您可以評估 plugin，其 skills 呼叫 MCP 工具，而無需它們後面的真實服務。在 `evals/mocks/<server>/<tool>.md` 下為整個套件放置一個 Markdown 檔案，或在案例自己的 `mocks/` 目錄下為一個案例，其中 `<server>` 是您的 plugin 的 [MCP configuration](/docs/zh-TW/plugins/components#mcp-servers) 中伺服器的名稱。

284 297

285執行永遠不會啟動您的 plugin 的真實 MCP 伺服器，除非您要求。Claude Code 在每個伺服器自己的名稱下註冊替代品。具有 mock 檔案的工具從它回答，並且無需 `--allow-tools` 授予即可允許，具有無 mock 檔案的工具對 Claude 不可用。完全沒有 mocks 的伺服器在案例的 `mocked:` 進度行中顯示為 `plugin_<plugin>_<server>[not started: no mock]`。298執行永遠不會啟動您的 plugin 的真實 MCP 伺服器，除非您要求。Claude Code 在每個伺服器自己的名稱下註冊替代伺服器。具有 mock 檔案的工具從它回答，並且無需 `--allow-tools` 授予即可允許，具有無 mock 檔案的工具對 Claude 不可用。完全沒有 mocks 的伺服器在案例的 `mocked:` 進度行中顯示為 `plugin_<plugin>_<server>[not started: no mock]`。

286 299

287檔案的主體是工具返回給 Claude 的內容。此 mock 代替名為 `tracker` 的伺服器上的 `create_issue` 工具，檢查 Claude 發送的輸入，並回顯標題。將其保存為 `evals/mocks/tracker/create_issue.md`：300檔案的主體是工具返回給 Claude 的內容。此 mock 代替名為 `tracker` 的伺服器上的 `create_issue` 工具，檢查 Claude 發送的輸入，並回顯標題。將其保存為 `evals/mocks/tracker/create_issue.md`：

288 301

296Created issue #4821: {{input.title}}309Created issue #4821: {{input.title}}

297```310```

298 311

299使用 `{{input.<field>}}` 從呼叫的輸入插入欄位，使用 `{{file:fixtures/{input.<field>}.json}}` 插入 mock 旁邊的 fixture 檔案的內容。`expect:` 區塊保護輸入。如果呼叫違反它，執行會中止，分數為 0，並記錄原因，因此案例可以斷言您的 plugin 要求伺服器執行的操作。設定 `error: true` 以改為將主體作為工具錯誤返回，或 `type: agent` 讓小型模型從主體中的指令作為伺服器回答。[mock file reference](#mock-files) 列出每個鍵和 `_server.md` 和 `_tools.json` 檔案。312Mock 檔案的主體和 frontmatter 接受這些選項：

313

314* **替換**：使用 `{{input.<field>}}` 從呼叫的輸入插入欄位，使用 `{{file:fixtures/{input.<field>}.json}}` 插入 mock 旁邊的 fixture 檔案的內容。

315* **`expect:`**：`expect:` 區塊保護輸入。如果呼叫違反它，執行會中止，分數為 0，並記錄原因，因此案例可以斷言您的 plugin 要求伺服器執行的操作。

316* **`error: true`**：設定 `error: true` 以改為將主體作為工具錯誤返回。

317* **`type: agent`**：設定 `type: agent` 讓小型模型從主體中的指令作為伺服器回答。

318

319[mock file reference](#mock-files) 列出每個鍵和 `_server.md` 和 `_tools.json` 檔案。

300 320

301若要評分呼叫本身，請將評分器指向 `target: mock_calls`。321若要評分呼叫本身，請將評分器指向 `target: mock_calls`。

302 322

332| An installed plugin by name, `name` or `name@marketplace` | The cases in the installed copy's eval directory, with the installed copy loaded. Results are written under `./evals/results/` in your current directory, or `./<dir>/results/` with `--eval-dir` |352| An installed plugin by name, `name` or `name@marketplace` | The cases in the installed copy's eval directory, with the installed copy loaded. Results are written under `./evals/results/` in your current directory, or `./<dir>/results/` with `--eval-dir` |

333| `name@skills-dir` | The same, for a [skills-directory plugin](/docs/zh-TW/plugins-reference#skills-directory-plugins) |353| `name@skills-dir` | The same, for a [skills-directory plugin](/docs/zh-TW/plugins/loading#plugins-shared-through-a-repository) |

334| Omitted | The current directory as a path |354| Omitted | The current directory as a path |

335 355

336新增 `--case <glob>` 按案例名稱篩選，`--tag <tag>` 保留具有任何給定標籤的案例。將目標放在 `--tag`、`--allow-tools` 和 `--json` 之前。前兩個採用列表，`--json` 採用可選路徑，因此它們中的每一個都讀取跟隨它的目標作為其自己的值。356新增 `--case <glob>` 按案例名稱篩選，`--tag <tag>` 保留具有任何給定標籤的案例。將目標放在 `--tag`、`--allow-tools` 和 `--json` 之前。前兩個採用列表，`--json` 採用可選路徑，因此它們中的每一個都讀取跟隨它的目標作為其自己的值。

341 361

342執行永遠不會停止要求許可。需要您未授予的授予的內建工具，例如 `Bash`、`Write`、`Edit`、`WebFetch` 和 `WebSearch`，會從工作階段中移除，因此 Claude 根本無法呼叫它們。362執行永遠不會停止要求許可。需要您未授予的授予的內建工具，例如 `Bash`、`Write`、`Edit`、`WebFetch` 和 `WebSearch`，會從工作階段中移除，因此 Claude 根本無法呼叫它們。

343 363

344允許清單是案例在 `allowed_tools` 中列出的唯讀工具，來自 `Read`、`Glob`、`Grep`、`NotebookRead`、`Skill`、`Agent`、`TodoWrite` 和任務工具 `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate` 和 `TaskStop`，加上您使用 `--allow-tools` 授予的任何內容。該授予適用於執行中的每個案例。若要讓案例使用 `Bash`、`Write`、`Edit`、`WebFetch` 或 `WebSearch`，請自己授予它們：364執行只允許案例在 `allowed_tools` 中列出的唯讀工具，來自 `Read`、`Glob`、`Grep`、`NotebookRead`、`Skill`、`AskUserQuestion`、`Agent`、`TodoWrite` 和任務工具 `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate` 和 `TaskStop`，加上您使用 `--allow-tools` 授予的任何內容。該授予適用於執行中的每個案例。若要讓案例使用 `Bash`、`Write`、`Edit`、`WebFetch` 或 `WebSearch`，請自己授予它們：

345 365

346```bash theme={null}366```bash theme={null}

347claude plugin eval . --allow-tools Write Edit "Bash(npm test *)"367claude plugin eval . --allow-tools Write Edit "Bash(npm test *)"

348```368```

349 369

350當案例要求您未授予的工具時，執行在 stderr 上將其列為 `not granted`。[mocked](#mock-mcp-servers) MCP 伺服器上的工具不需要授予。真實 plugin MCP 伺服器上的工具需要伺服器啟動（使用 `--allow-real-servers` 或 `--mocks off`）和按名稱授予，例如 `--allow-tools "mcp__plugin_my-plugin_github__*"`；plugin 的 MCP 工具命名為 `mcp__plugin_<plugin>_<server>__<tool>`。370當案例要求您未授予的工具時，進度輸出將其列為 `not granted`。[mocked](#mock-mcp-servers) MCP 伺服器上的工具不需要授予。真實 plugin MCP 伺服器上的工具需要伺服器啟動（使用 `--allow-real-servers` 或 `--mocks off`）和按名稱授予，例如 `--allow-tools "mcp__plugin_my-plugin_github__*"`；plugin 的 MCP 工具命名為 `mcp__plugin_<plugin>_<server>__<tool>`。

351 371

352當您以任何形式授予 `Bash` 時，每個命令都在 Claude Code 的 [OS-level sandbox](/docs/zh-TW/sandboxing) 下執行。寫入限制在執行的工作區、您的主目錄和 Claude Code 設定無法讀取，網路存取限制在您使用 `--allow-tools "WebFetch(domain:example.com)"` 授予的網域。如果您在沒有沙箱後端的機器上授予 Bash 或 PowerShell，Claude Code 拒絕每次執行而不是無限制執行它，案例顯示執行錯誤，通常分數為 0。原生 Windows 沒有後端，因此在 WSL2 下執行 shell 授予套件；在 Linux 上，首先安裝 `bubblewrap` 和 `socat`。請參閱 [sandboxing prerequisites](/docs/zh-TW/sandboxing)。372當您以任何形式授予 `Bash` 時，每個命令都在 Claude Code 的 [OS-level sandbox](/docs/zh-TW/sandboxing) 下執行。寫入限制在執行的工作區，您的主目錄和 Claude Code 設定無法讀取，網路存取限制在您使用 `--allow-tools "WebFetch(domain:example.com)"` 授予的網域。如果您在沒有沙箱後端的機器上授予 Bash 或 PowerShell，Claude Code 拒絕每次執行而不是無限制執行它，案例顯示執行錯誤，通常分數為 0。原生 Windows 沒有後端，因此在 WSL2 下執行 shell 授予套件；在 Linux 上，首先安裝 `bubblewrap` 和 `socat`。請參閱 [sandboxing prerequisites](/docs/zh-TW/sandboxing)。

353 373

354<h3 id="command-options">374<h3 id="command-options">

355 命令選項375 命令選項

358此表涵蓋執行計數、模型、評分、成本、工具授予、mocks 和輸出的選項。執行 `claude plugin eval --help` 以獲得完整列表，其中還包括 `--case`、`--tag`、`--eval-dir`、`--no-scaffold`、`--report` 和 `--verbose`。378此表涵蓋執行計數、模型、評分、成本、工具授予、mocks 和輸出的選項。執行 `claude plugin eval --help` 以獲得完整列表，其中還包括 `--case`、`--tag`、`--eval-dir`、`--no-scaffold`、`--report` 和 `--verbose`。

359 379

361| :------------------------- | :----------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |381| :------------------------- | :----------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

363| `-j`, `--concurrency <n>` | `1` | Run up to this many agent runs at once, from 1 to 8. They share your account's rate limit, so this shortens wall-clock time rather than raising throughput past that limit. Results keep case order |383| `-j`, `--concurrency <n>` | `1` | Run up to this many agent runs at once, from 1 to 8. They share your account's rate limit, so this shortens wall-clock time rather than raising throughput past that limit. Results keep case order |

364| `--model <model>` | Each case's `model`, else `ANTHROPIC_MODEL` if set, else Claude Code's default | Model for the agent under test. Pin it in CI so a model rollout isn't mistaken for a plugin regression |384| `--model <model>` | Each case's `model`, else `ANTHROPIC_MODEL` if set, else Claude Code's default | Model for the agent under test. Pin it in CI so a model rollout isn't mistaken for a plugin regression |

366| `--ablation <mode>` | `with-without` when a plugin resolves, else `none` | Whether to also run each case without the plugin to measure what it adds. `none` runs one arm; `with-without` adds the no-plugin baseline |386| `--ablation <mode>` | `with-without` when a plugin resolves, else `none` | Whether to also run each case without the plugin to measure what it adds. `none` runs one arm; `with-without` adds the no-plugin baseline |

367| `--threshold <0..1>` | `1.0` | A case passes when its with-arm score is at least this. Any case below it makes the command exit 1 |387| `--threshold <0..1>` | `1.0` | A case passes when its with-arm score is at least this. Any case below it makes the command exit 1 |

368| `--max-cost-usd <usd>` | No ceiling | A ceiling on the run's list-price cost estimate, not on plan usage. Checked before each run starts. Once spent, nothing further starts; runs already in flight finish, so spend can pass the ceiling by those runs. If any run is left unstarted, the command exits 2 with partial results |388| `--max-cost-usd <usd>` | No ceiling | A ceiling on the run's list-price cost estimate, not on plan usage. Checked before each run starts. Once spent, nothing further starts; runs that already started finish, so spend can pass the ceiling by those runs. If any run is left unstarted, the command exits 2 with partial results |

370| `--scaffold` | Off | Run each case's [`scaffold_script`](#add-setup-or-history-with-case-yaml) |390| `--scaffold` | Off | Run each case's [`scaffold_script`](#add-setup-or-history-with-case-yaml) |

371| `--trust-plugin` | Off | Skip the first-run trust prompt for a plugin whose code and suite you'd run yourself. Pass it in CI so the job is never refused by or left waiting at the prompt. See [What a run can access](#security) |391| `--trust-plugin` | Off | Skip the first-run trust prompt for a plugin whose code and suite you'd run yourself. Pass it in CI so the job is never refused by or left waiting at the prompt. See [What a run can access](#security) |

406 426

407寫入或發佈 HTML 報告的問題永遠不會改變退出代碼。若要查看案例評分低的原因，請在本地執行它而不使用 `--json`，以便列印每次執行的進度和評分器行。427寫入或發佈 HTML 報告的問題永遠不會改變退出代碼。若要查看案例評分低的原因，請在本地執行它而不使用 `--json`，以便列印每次執行的進度和評分器行。

408 428

409CI 執行器需要 Claude Code 安裝和 [credentials in the environment](/docs/zh-TW/authentication)，例如 `ANTHROPIC_API_KEY`。沒有 `--trust-plugin`，其簽出目錄 Claude Code 還不信任的工作在沒有終端時被拒絕，退出代碼 1，或在執行器分配一個時在提示處等待。`claude plugin eval init` 需要終端來詢問您的問題；在 CI 中，執行 `claude plugin eval init --bare <name>` 以獲得空白範本。429CI 執行器也需要這些就位：

430

431* **安裝和認證**：CI 執行器需要 Claude Code 安裝和 [credentials in the environment](/docs/zh-TW/authentication)，例如 `ANTHROPIC_API_KEY`。

432* **信任**：沒有 `--trust-plugin`，其簽出目錄 Claude Code 還不信任的工作需要 [first-run trust prompt](#security)，而無法詢問的執行會被拒絕，退出代碼 1。

433* **在 CI 中 `init`**：`claude plugin eval init` 需要終端來詢問您的問題；在 CI 中，執行 `claude plugin eval init --bare <name>` 以獲得空白範本。

410 434

411若要保持成本可預測，請為快速每次變更套件提供僅不呼叫評判的評分器，在您不需要 `Δ` 的地方使用 `--ablation none`，並將 `partial: true` 文件和具有 `skippedPaidGraders` 的執行排除在您繪製的任何趨勢之外。435若要保持成本可預測，請為快速每次變更套件提供僅不呼叫評判的評分器，在您不需要 `Δ` 的地方使用 `--ablation none`，並將 `partial: true` 文件和具有 `skippedPaidGraders` 的執行排除在您繪製的任何趨勢之外。

412 436

458| `costUsd`, `durationSeconds`, `claudeVersion` | Estimated cost at list price including judge calls, wall-clock seconds, and the Claude Code version that ran the suite |482| `costUsd`, `durationSeconds`, `claudeVersion` | Estimated cost at list price including judge calls, wall-clock seconds, and the Claude Code version that ran the suite |

459 483

460<h2 id="security">484<h2 id="security">

461 What a run can access485 執行可以存取的內容

462</h2>486</h2>

463 487

464`claude plugin eval` 載入目標 plugin 的 skills、hooks 和 agents，並在您的機器上以您的身份執行其 eval 套件。將其指向 plugin 與 `claude --plugin-dir` 相同的信任決定，因此僅評估您信任的 plugins。本節中描述的隔離限制了被測試代理可以到達的內容；它不是針對 plugin 自己程式碼的邊界，通過套件的套件對 plugin 是否安全沒有說明。488`claude plugin eval` 載入目標 plugin 的 skills、hooks 和 agents，並在您的機器上以您的身份執行其 eval 套件。將其指向 plugin 與 `claude --plugin-dir` 相同的信任決定，因此僅評估您信任的 plugins。本節中描述的隔離限制了被測試代理可以到達的內容；它不是針對 plugin 自己程式碼的邊界，通過套件的套件對 plugin 是否安全沒有說明。

465 489

466<h3 id="trust-the-plugin-directory">490<h3 id="trust-the-plugin-directory">

467 Trust the plugin directory491 信任 plugin 目錄

468</h3>492</h3>

469 493

470第一次針對目錄執行 `claude plugin eval` 時，Claude Code 會詢問 `Trust this plugin directory?`，除非您已在互動式 `claude` 工作階段中在那裡接受信任提示。在 git 儲存庫內，回答是信任整個儲存庫，對於互動式工作階段也是如此。當 stdin 或 stdout 不是終端時，或在 `--json` 下，執行無法詢問並被拒絕，退出代碼 1；傳遞 `--trust-plugin` 以自己斷言信任，僅對您會在自己的機器上執行的 plugin。您命名而不是作為路徑給出的目標（意味著已安裝的 plugin 或 skills-directory plugin）跳過提示。494第一次針對目錄執行 `claude plugin eval` 時，Claude Code 會詢問 `Trust this plugin directory?`，除非您已在互動式 `claude` 工作階段中在那裡接受信任提示。在 git 儲存庫內，回答是信任整個儲存庫，對於互動式工作階段也是如此。當 stdin 或 stdout 不是終端時，在 `--json` 下，或當 `CI` 環境變數設定為真值（例如 `true`）時，執行無法詢問並被拒絕，退出代碼 1；傳遞 `--trust-plugin` 以自己斷言信任，僅對您會在自己的機器上執行的 plugin。您命名而不是作為路徑給出的目標（意味著已安裝的 plugin 或 skills-directory plugin）跳過提示。

495

496plugin 和套件的某些部分僅在您為該執行傳遞其標誌時執行：

497

498* 案例的 [`scaffold_script`](#add-setup-or-history-with-case-yaml) 使用 `--scaffold`

499* [讀取專用集合之外的工具](#grant-tools) 使用 `--allow-tools`

500* plugin 的 [真實 MCP 伺服器](#mock-mcp-servers) 使用 `--allow-real-servers` 或 `--mocks off`

501

502案例的 `allowed_tools` 和 skill 自己的 `allowed-tools` frontmatter 無法擴展它們中的任何一個。

471 503

472plugin 和套件的某些部分僅在您為該執行傳遞其標誌時執行：案例的 [`scaffold_script`](#add-setup-or-history-with-case-yaml) 使用 `--scaffold`、[tools beyond the read-only set](#grant-tools) 使用 `--allow-tools`，以及 plugin 的 [real MCP servers](#mock-mcp-servers) 使用 `--allow-real-servers` 或 `--mocks off`。案例的 `allowed_tools` 和 skill 自己的 `allowed-tools` frontmatter 無法擴展它們中的任何一個。當 plugin 發佈您未編寫的 hooks，或您啟動其真實 MCP 伺服器時，除非您在隔離環境（例如容器或 CI 執行器）中執行它，否則將其分數視為建議，因為 hooks 和伺服器在代理沙箱外執行，可能會觸及評分器讀取的檔案。504當 plugin 發佈您未編寫的 hooks，或您啟動其真實 MCP 伺服器時，除非您在隔離環境（例如容器或 CI 執行器）中執行它，否則將其分數視為建議，因為 hooks 和伺服器在代理沙箱外執行，可能會修改評分器讀取的檔案。

473 505

474<h3 id="how-runs-are-isolated">506<h3 id="how-runs-are-isolated">

475 How runs are isolated507 執行如何被隔離

476</h3>508</h3>

477 509

478每次執行都獲得一次性主目錄、工作目錄和 Claude Code 設定，被測試代理在那裡以 `claude -p` 子程序執行，僅載入您的 plugin。在編寫案例時牢記這些後果：510每次執行都獲得一次性主目錄、工作目錄和 Claude Code 設定，被測試代理在那裡以 `claude -p` 子程序執行，僅載入您的 plugin。在編寫案例時牢記這些後果：

537 case.yaml fields569 case.yaml fields

538</h3>570</h3>

539 571

540`case.yaml` 以 YAML 描述相同案例並新增指向其他檔案的欄位。它需要 `schema_version: "1.1"` 和 `name`。`prompt.md` 欄位 `description`、`tags`、`plugins`、`runs` 和 `expected_outcome` 在頂層；`model`、`max_turns`、`timeout_seconds`、`allowed_tools`、`append_system_prompt` 和 `env` 在 `execution:` 下。當兩個檔案都存在時，`prompt.md` frontmatter 覆蓋匹配的 `case.yaml` 欄位，`prompt.md` 主體是提示，`graders/*.md` 在 `case.yaml` 中列出的任何評分器之後新增。572`case.yaml` 是 `prompt.md` 的替代或伴隨：它以 YAML 描述案例並新增指向其他檔案的欄位。它需要 `schema_version: "1.1"` 和 `name`。`prompt.md` 欄位 `description`、`tags`、`plugins`、`runs` 和 `expected_outcome` 在頂層；`model`、`max_turns`、`timeout_seconds`、`allowed_tools`、`append_system_prompt` 和 `env` 在 `execution:` 下。當兩個檔案都存在時，`prompt.md` frontmatter 覆蓋匹配的 `case.yaml` 欄位，`prompt.md` 主體是提示，`graders/*.md` 在 `case.yaml` 中列出的任何評分器之後新增。

541 573

542這些欄位僅存在於 `case.yaml` 中：574這些欄位僅存在於 `case.yaml` 中：

543 575

556`graders/` 下的每個評分器檔案在 frontmatter 中採用這些鍵，加上其類型的選項。評分器的名稱是沒有 `.md` 的檔案名稱：588`graders/` 下的每個評分器檔案在 frontmatter 中採用這些鍵，加上其類型的選項。評分器的名稱是沒有 `.md` 的檔案名稱：

557 589

558| Key | Default | Purpose |590| Key | Default | Purpose |

559| :------- | :------ | :------------------------------------------------------------------------------------------------------------------------- |591| :------- | :------ | :------------------------------------------------------------------------------------------------------------------------ |

560| `type` | 必需 | [grader types](#grader-types) 之一 |592| `type` | 必需 | [grader types](#grader-types) 之一 |

561| `weight` | `1` | 執行分數中的相對權重。任何正數 |593| `weight` | `1` | 執行分數中的相對權重。任何正數 |

562| `arm` | 未設定 | `with-only` 在 [two-arm run](#compare-against-a-no-plugin-baseline) 中排除評分器的評分；`both` 強制 `tool_used: Skill` 評分器在兩個 arm 中都被評分 |594| `arm` | 未設定 | `with-only` 在 [two-arm run](#compare-against-a-no-plugin-baseline) 中排除評分器的評分；`both` 強制 Claude Code 否則會排除的評分器在兩個 arm 中都被評分 |

563 595

564<h4 id="what-a-grader-can-look-at">596<h4 id="what-a-grader-can-look-at">

565 What a grader can look at597 What a grader can look at

632 "is not a trusted plugin directory, and this run cannot stop to ask you about it"664 "is not a trusted plugin directory, and this run cannot stop to ask you about it"

633</h3>665</h3>

634 666

635這是針對目錄的第一次執行，Claude Code 還不信任，並且因為 stdin 或 stdout 不是終端或您傳遞了 `--json` 而無法詢問。在終端中執行 `claude plugin eval <dir>` 一次並回答提示，或如果您信任 plugin 的程式碼和套件，請傳遞 `--trust-plugin`。請參閱 [What a run can access](#security)。667這是針對目錄的第一次執行，Claude Code 還不信任，並且因為 stdin 或 stdout 不是終端、您傳遞了 `--json`，或 `CI` 環境變數設定為真值（例如 `true`）而無法詢問。在終端中執行 `claude plugin eval <dir>` 一次並回答提示，或如果您信任 plugin 的程式碼和套件，請傳遞 `--trust-plugin`。請參閱 [What a run can access](#security)。

636 668

637<h3 id="no-eval-cases-found">669<h3 id="no-eval-cases-found">

638 "No eval cases found"670 "No eval cases found"

668 A regex over the trace doesn't match text I can see700 A regex over the trace doesn't match text I can see

669</h3>701</h3>

670 702

671預設 `target` 是 `last_message`，不是 trace。當您確實目標 `trace` 時，它是每行 JSON，因此引號顯示為 `\"`。正規表達式使用 JavaScript 語法，因此在 `flags` 中放置 `i` 而不是編寫 `(?i)`。703* **錯誤的目標**：預設 `target` 是 `last_message`，不是 trace。

704* **JSON 逸出**：當您確實目標 `trace` 時，它是每行 JSON，因此引號顯示為 `\"`。

705* **正規表達式語法**：正規表達式使用 JavaScript 語法，因此在 `flags` 中放置 `i` 而不是編寫 `(?i)`。

672 706

673<h3 id="tools-are-denied-mcp-tools-are-missing-or-bash-won’t-run">707<h3 id="tools-are-denied-mcp-tools-are-missing-or-bash-won’t-run">

674 Tools are denied, MCP tools are missing, or Bash won't run708 Tools are denied, MCP tools are missing, or Bash won't run

692 A grader shows passed: false under a run that scored 1.0726 A grader shows passed: false under a run that scored 1.0

693</h3>727</h3>

694 728

695該評分器在兩個 arm 執行中按設計從分數中排除，其 `scored` 欄位為 `false`。請參閱 [Compare against a no-plugin baseline](#compare-against-a-no-plugin-baseline)。729該評分器在兩個 arm 執行中按設計從分數中排除，其 `scored` 欄位為 `false`。請參閱 [Score against the no-plugin baseline](#compare-against-a-no-plugin-baseline)。

696 730

697<h3 id="runs-fail-with-a-usage-limit-or-rate-limit-error-partway-through">731<h3 id="runs-fail-with-a-usage-limit-or-rate-limit-error-partway-through">

698 Runs fail with a usage-limit or rate-limit error partway through732 Runs fail with a usage-limit or rate-limit error partway through

710 See also744 See also

711</h2>745</h2>

712 746

713* [Create plugins](/docs/zh-TW/plugins)：建立您正在測試的 plugin，並在開發期間使用 `--plugin-dir` 載入它747* [建立 plugin](/docs/zh-TW/plugins/create)：建立您正在測試的 plugin，並在開發期間使用 `--plugin-dir` 載入它

714* [Plugins reference](/docs/zh-TW/plugins-reference#plugin-eval)：`plugin eval` 和 `plugin eval init` 命令項目以及資訊清單的 `experimental.evals` 鍵748* [Plugin 命令參考](/docs/zh-TW/plugins/cli-reference#plugin-eval)：`plugin eval` 和 `plugin eval init` 命令項目。資訊清單的 [`experimental.evals`](/docs/zh-TW/plugins/manifest-reference#fields) 鍵位於資訊清單參考中

715* [Skills](/docs/zh-TW/skills)：skill 的描述如何決定 Claude 何時呼叫它，這是檢查 skill 是否觸發的案例測量的內容749* [Skills](/docs/zh-TW/skills)：skill 的描述如何決定 Claude 何時呼叫它，這是檢查 skill 是否觸發的案例測量的內容

716* [Sandboxing](/docs/zh-TW/sandboxing)：當您授予 Bash 執行時適用的 OS 級沙箱750* [Sandboxing](/docs/zh-TW/sandboxing)：當您授予 Bash 執行時適用的 OS 級沙箱

717* [Create and distribute a plugin marketplace](/docs/zh-TW/plugin-marketplaces)：一旦其套件通過，發佈 plugin751* [發佈 plugin](/docs/zh-TW/plugins/publish)：一旦其測試套件通過，發佈 plugin

752* [測量 plugin 成本和使用情況](/docs/zh-TW/plugins/measure)：plugin 新增至每個工作階段內容的內容，以及人們是否仍在使用它

plugin-hints.md +0 −172 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# 從您的 CLI 推薦您的外掛程式~~

~~7> 從您的 CLI 發出單行標記，以便 Claude Code 提示使用者安裝您的官方外掛程式。~~

9如果您維護 CLI 或 SDK，並在官方 Anthropic 市場中有外掛程式，您的工具可以提示 Claude Code 使用者安裝該外掛程式。當您的 CLI 偵測到它在 Claude Code 內執行時，會向 stderr 寫入單行標記。Claude Code 讀取該標記，將其從輸出中移除，並向使用者顯示一次性安裝提示。

~~11該協議不需要額外命令，也不會改變您的 CLI 為 Claude Code 外部使用者列印的內容。~~

~~13本頁面適用於 CLI 和 SDK 維護者。如果您正在尋找安裝外掛程式，請參閱[探索和安裝外掛程式](/docs/zh-TW/discover-plugins)。~~

~~15<h2 id="how-it-works">~~

~~16 運作方式~~

~~17</h2>~~

19Claude Code 為透過 Bash 和 PowerShell 工具執行的每個命令，以及 [hook](/docs/zh-TW/hooks) 命令設定 [`CLAUDECODE`](/docs/zh-TW/env-vars) 環境變數為 `1`。從 v2.1.172 開始，它也會在這些相同的子程序中將 [`CLAUDE_CODE_CHILD_SESSION`](/docs/zh-TW/env-vars) 設定為 `1`。當您的 CLI 看到其中一個變數時，它會向 stderr 寫入自閉合的 `<claude-code-hint />` 標籤。在 hook 命令中，提示標籤會被移除並忽略。只有 Bash 和 PowerShell 工具輸出會觸發安裝提示。

~~21當 Claude Code 接收到命令輸出時，它會：~~

~~231. 掃描提示行並在輸出到達模型之前將其移除~~

~~242. 檢查提示是否指向官方 Anthropic 市場中的外掛程式~~

~~253. 檢查外掛程式是否尚未安裝且之前未提示過~~

~~264. 向使用者顯示安裝提示，其中包含發出提示的命令名稱~~

~~28Claude Code 永遠不會自動安裝外掛程式。使用者始終需要確認。~~

~~30<h2 id="emit-the-hint">~~

~~31 發出提示~~

~~32</h2>~~

34提示提示只會針對列在官方 Anthropic 市場中的外掛程式觸發。在您推出整合之前，請參閱[將您的外掛程式納入官方市場](#get-your-plugin-into-the-official-marketplace)。

~~36在環境變數上設定發出條件，以便標記不太可能在人類直接執行您的 CLI 時出現，然後將標籤寫入 stderr 的單獨一行。選擇要檢查的變數：~~

38* `CLAUDECODE`：在每個 Claude Code 版本上設定，因此可以到達最多的工作階段。它也在 Claude Code 啟動的 tmux 工作階段和 stdio MCP 伺服器子程序中設定，IDE 擴充功能在其整合終端中設定它，人類可能在那裡直接執行您的 CLI。

39* `CLAUDE_CODE_CHILD_SESSION`：僅在 Claude Code 本身產生的子程序中設定，例如工具呼叫、hook 命令和[狀態列](/docs/zh-TW/statusline)命令，因此標籤通常不會到達人類終端。在工作階段內啟動的長期程序（例如 tmux 伺服器）會捕獲該變數，因此稍後從該程序啟動的 shell 仍會顯示原始標籤。

~~41以下範例在 `CLAUDECODE` 上設定條件以達到最大覆蓋範圍，並為官方市場中名為 `example-cli` 的外掛程式發出提示：~~

~~43<CodeGroup>~~

~~44 ```javascript Node.js theme={null}~~

~~45 if (process.env.CLAUDECODE) {~~

~~46 process.stderr.write(~~

~~47 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',~~

~~48 )~~

~~49 }~~

~~50 ```~~

~~52 ```python Python theme={null}~~

~~53 import os, sys~~

~~55 if os.environ.get("CLAUDECODE"):~~

~~56 print(~~

~~57 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',~~

~~58 file=sys.stderr,~~

~~59 )~~

~~60 ```~~

~~62 ```go Go theme={null}~~

~~63 if os.Getenv("CLAUDECODE") != "" {~~

~~64 fmt.Fprintln(os.Stderr,~~

~~65 `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)~~

~~66 }~~

~~67 ```~~

~~69 ```shell Shell theme={null}~~

~~70 if [ -n "$CLAUDECODE" ]; then~~

~~71 printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2~~

~~72 fi~~

~~73 ```~~

~~74</CodeGroup>~~

~~76將 `example-cli` 替換為您在官方市場中的外掛程式名稱。~~

~~78<h2 id="choose-where-to-emit">~~

~~79 選擇發出位置~~

~~80</h2>~~

~~82您可以控制哪些程式碼路徑發出提示。Claude Code 按外掛程式進行重複資料刪除，因此在每次呼叫時發出沒有缺點。運作良好的接觸點包括：~~

~~84| 位置 | 為什麼有效 |~~

~~85| :---------- | :------------------------- |~~

~~86| `--help` 輸出 | Claude 在探索不熟悉的 CLI 時經常執行幫助 |~~

~~87| 未知子命令錯誤 | 到達 Claude 對您的介面感到困惑的時刻 |~~

~~88| 登入或驗證成功 | 使用者已經處於設定心態 |~~

~~89| 首次執行歡迎訊息 | 自然的入門時刻 |~~

~~91<h2 id="what-the-user-sees">~~

~~92 使用者看到的內容~~

~~93</h2>~~

~~95當提示通過所有檢查時，Claude Code 會顯示如下提示：~~

~~97```text theme={null}~~

~~98─────────────────────────────────────────────────────────────~~

~~99 外掛程式推薦~~

~~100~~

101 example-cli 命令建議安裝外掛程式。

~~102~~

103 外掛程式：example-cli

104 市場：claude-plugins-official

105 example-cli 部署的官方整合

~~106~~

107 您想要安裝它嗎？

108 ❯ 1. 是的，安裝 example-cli

109 2. 否

110 3. 否，不再顯示外掛程式安裝提示

~~111~~

112─────────────────────────────────────────────────────────────

113```

~~114~~

115提示會命名產生提示的命令，以便使用者可以發現工具與其推薦的外掛程式之間的不匹配。如果使用者在 30 秒內未回應，Claude Code 會將提示關閉為**否**。

~~116~~

117提示頻率受限，某些工作階段永遠不會提示：

~~118~~

119* **每個外掛程式一次**：顯示提示後，Claude Code 會記錄該外掛程式，無論使用者的答案如何，都不會再次提示。

120* **每個工作階段一次**：在機器上的所有 CLI 中，每個 Claude Code 工作階段最多出現一個提示。

121* **僅限主要互動工作階段**：Claude Code 只會在使用者正在輸入的終端工作階段中顯示提示。Claude Code 永遠不會提示 [subagent](/docs/zh-TW/sub-agents) 執行的命令，也不會在使用者使用 `-p` 旗標以 [non-interactive mode](/docs/zh-TW/headless) 執行 Claude Code 或透過 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 時提示。Claude Code 在所有這些情況下仍會從命令輸出中移除提示行。

122* **遙測選擇退出**：停用分析的工作階段永遠不會顯示提示。這包括設定了 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的工作階段，以及 Amazon Bedrock 或 Google Cloud 的 Agent Platform 等第三方提供者上的工作階段，其中 [automatic telemetry opt-out](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) 適用。

~~123~~

124選擇**是的，安裝 example-cli** 會將外掛程式安裝到使用者範圍。選擇**否，不再顯示外掛程式安裝提示**會為使用者停用所有未來的提示。

~~125~~

126<h2 id="hint-format">

127 提示格式

128</h2>

~~129~~

130提示是具有三個必需屬性的自閉合標籤。

~~131~~

132```text theme={null}

133<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />

134```

~~135~~

136| 屬性 | 必需 | 描述 |

137| :------ | :- | :---------------------------- |

138| `v` | 是 | 協議版本。`1` 是唯一支援的值 |

139| `type` | 是 | 提示類型。`plugin` 是唯一支援的值 |

140| `value` | 是 | `name@marketplace` 形式的外掛程式識別碼 |

~~141~~

142屬性值可以用雙引號引用或不引用。未引用的值不能包含空格。不支援逸出序列。

~~143~~

144<h2 id="requirements">

145 要求

146</h2>

~~147~~

148Claude Code 在對提示進行操作之前強制執行兩個條件。未通過任一檢查的提示會被丟棄：

~~149~~

150* **自己的行**：標籤必須佔據自己的行。嵌入在行中間的標籤，例如在日誌陳述式內，會被忽略。允許行上的前導和尾隨空格。

151* **官方市場**：`value` 必須參考 Anthropic 控制的市場中的外掛程式，例如 `claude-plugins-official`。指向其他市場的提示會被無聲地丟棄。

~~152~~

153提示行始終會在到達模型之前從輸出中移除，即使版本或類型無法識別，因此標記永遠不會計入代幣使用量。

~~154~~

155其餘指導是建議的，但不是強制的。Claude Code 無法觀察您的 CLI 是否遵循它：

~~156~~

157* **寫入 stderr**：stderr 將標籤保留在 shell 管道之外，例如 `example-cli deploy | jq`。Claude Code 掃描兩個流，因此 stdout 也有效。

158* **在環境變數上設定條件**：僅在設定 `CLAUDECODE` 或 `CLAUDE_CODE_CHILD_SESSION` 時發出。請參閱[發出提示](#emit-the-hint)以了解這兩個變數的差異。

~~159~~

160<h2 id="get-your-plugin-into-the-official-marketplace">

161 將您的外掛程式納入官方市場

162</h2>

~~163~~

164提示協議僅對列在官方 Anthropic 市場 `claude-plugins-official` 中的外掛程式生效。Anthropic 自行決定策劃該市場，應用程式內提交表單會將外掛程式新增到[社群市場](/docs/zh-TW/plugins#submit-your-plugin-to-the-community-marketplace)，提示協議不會檢查該市場。如果您正在與 Anthropic 合作夥伴聯絡人合作，請與他們聯繫以協調官方市場列表。

~~165~~

166<h2 id="see-also">

167 另請參閱

168</h2>

~~169~~

170* [建立外掛程式](/docs/zh-TW/plugins)：建立您的 CLI 推薦的外掛程式

171* [建立和發佈外掛程式市場](/docs/zh-TW/plugin-marketplaces)：在官方市場外託管外掛程式

172* [環境變數](/docs/zh-TW/env-vars)：`CLAUDECODE` 和相關變數的完整參考

plugin-marketplaces.md +0 −1688 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# 建立並分發 plugin marketplace~~

~~7> 建立並託管 plugin marketplace，以在團隊和社群中分發 Claude Code 擴充功能。~~

9**plugin marketplace** 是一個目錄，可讓您將 plugin 分發給他人。Marketplace 提供集中式發現、版本追蹤、自動更新，以及對多種來源類型（包括 git 儲存庫和本機路徑）的支援。本指南將向您展示如何建立自己的 marketplace，以與您的團隊或社群分享 plugin。

~~11想要從現有 marketplace 安裝 plugin？請參閱[探索並安裝預先建立的 plugin](/docs/zh-TW/discover-plugins)。~~

~~13<h2 id="overview">~~

~~14 概述~~

~~15</h2>~~

~~17建立並分發 marketplace 涉及：~~

191. **建立 plugin**：使用 skills、agents、hooks、MCP servers 或 LSP servers 建立一個或多個 plugin。本指南假設您已經有要分發的 plugin；有關如何建立 plugin 的詳細資訊，請參閱[建立 plugin](/docs/zh-TW/plugins)。

~~202. **建立 marketplace 檔案**：定義 `marketplace.json`，列出您的 plugin 及其位置。請參閱[建立 marketplace 檔案](#create-the-marketplace-file)。~~

~~213. **託管 marketplace**：推送到 GitHub、GitLab 或其他 git 主機。請參閱[託管並分發 marketplace](#host-and-distribute-marketplaces)。~~

~~224. **與使用者分享**：使用者使用 `/plugin marketplace add` 新增您的 marketplace 並安裝個別 plugin。請參閱[探索並安裝 plugin](/docs/zh-TW/discover-plugins)。~~

~~24一旦您的 marketplace 上線，您可以透過推送變更到您的儲存庫來更新它。使用者使用 `/plugin marketplace update` 重新整理其本機副本。~~

~~26<h2 id="walkthrough-create-a-local-marketplace">~~

~~27 逐步解說：建立本機市集~~

~~28</h2>~~

30此範例建立一個市集，其中包含一個外掛程式：用於程式碼審查的 `quality-review` 技能。您將建立目錄結構、新增技能、建立外掛程式資訊清單和市集目錄，然後安裝並測試它。

~~32<Steps>~~

~~33 <Step title="建立目錄結構">~~

~~34 ```bash theme={null}~~

~~35 mkdir -p my-marketplace/.claude-plugin~~

~~36 mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin~~

~~37 mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review~~

~~38 ```~~

~~39 </Step>~~

~~41 <Step title="建立技能">~~

~~42 建立一個 `SKILL.md` 檔案，定義 `quality-review` 技能的功能。~~

~~44 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}~~

~~45 ---~~

~~46 description: Review code for bugs, security, and performance~~

~~47 ---~~

~~49 Review the code I've selected or the recent changes for:~~

~~50 - Potential bugs or edge cases~~

~~51 - Security concerns~~

~~52 - Performance issues~~

~~53 - Readability improvements~~

~~55 Be concise and actionable.~~

~~56 ```~~

~~57 </Step>~~

~~59 <Step title="建立外掛程式資訊清單">~~

~~60 建立一個 `plugin.json` 檔案，描述該外掛程式。資訊清單位於 `.claude-plugin/` 目錄中。~~

~~62 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}~~

~~63 {~~

~~64 "name": "quality-review-plugin",~~

~~65 "description": "Adds a quality-review skill for quick code reviews",~~

~~66 "version": "1.0.0",~~

~~67 "author": {~~

~~68 "name": "Your Name"~~

~~69 }~~

~~70 }~~

~~71 ```~~

~~73 <Note>~~

74 設定 `version` 表示使用者只有在您變更此欄位時才會收到更新，因此在每次發行時都要提升版本。具有 [`command` 來源](#command-sources) 的外掛程式不會由此欄位固定。從市集新增為本機目錄的市集中 [就地載入](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution) 的外掛程式也不會被固定。如果您省略 `version`，版本會來自 [版本管理](/docs/zh-TW/plugins-reference#version-management) 中的下一個來源。

~~75 </Note>~~

~~76 </Step>~~

~~78 <Step title="建立市集檔案">~~

~~79 建立列出您的外掛程式的市集目錄。~~

~~81 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}~~

~~82 {~~

~~83 "name": "my-plugins",~~

~~84 "owner": {~~

~~85 "name": "Your Name"~~

~~86 },~~

~~87 "plugins": [~~

~~88 {~~

~~89 "name": "quality-review-plugin",~~

~~90 "source": "./plugins/quality-review-plugin",~~

~~91 "description": "Adds a quality-review skill for quick code reviews"~~

~~92 }~~

~~93 ]~~

~~94 }~~

~~95 ```~~

~~96 </Step>~~

~~98 <Step title="新增並安裝">~~

99 從包含 `my-marketplace` 的目錄啟動 Claude Code 並執行下列命令。安裝命令會開啟外掛程式詳細資料檢視，您可在其中選擇安裝範圍以確認安裝。檢查安裝摘要：如果它報告 `Run /reload-plugins to activate.`，請參閱 [不重新啟動即可套用外掛程式變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)。

~~100~~

101 ```shell theme={null}

102 /plugin marketplace add ./my-marketplace

103 /plugin install quality-review-plugin@my-plugins

104 ```

105 </Step>

~~106~~

107 <Step title="試試看">

108 在編輯器中選擇一些程式碼並執行您的新技能。外掛程式技能會以外掛程式名稱作為命名空間。

~~109~~

110 ```shell theme={null}

111 /quality-review-plugin:quality-review

112 ```

113 </Step>

114</Steps>

~~115~~

116若要深入瞭解外掛程式可以執行的操作，包括 hooks、agents、MCP 伺服器和 LSP 伺服器，請參閱 [Plugins](/docs/zh-TW/plugins)。

~~117~~

118<Note>

119 **外掛程式的安裝方式**：當使用者安裝外掛程式時，Claude Code 會將外掛程式目錄複製到快取位置，除非外掛程式就地載入。連結模式中的 [`command` 來源](#copy-mode-and-link-mode) 會就地載入，從本機目錄新增的市集中的 [相對路徑來源](#relative-paths) 也會就地載入。複製的外掛程式無法使用 `../shared-utils` 之類的路徑參考其目錄外的檔案，因為這些檔案不會被複製。

~~120~~

121 如果您需要在外掛程式之間共用檔案，請使用符號連結。如需詳細資訊，請參閱 [外掛程式快取和檔案解析](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。

122</Note>

~~123~~

124<h2 id="create-the-marketplace-file">

125 建立 marketplace 檔案

126</h2>

~~127~~

128在您的儲存庫根目錄中建立 `.claude-plugin/marketplace.json`。此檔案定義您的 marketplace 名稱、擁有者資訊以及包含其來源的 plugin 清單。

~~129~~

130每個 plugin 項目至少需要 `name` 和 `source`（告訴 Claude Code 從何處取得）。有關所有可用欄位，請參閱下面的[完整架構](#marketplace-schema)。

~~131~~

132```json theme={null}

133{

134 "name": "company-tools",

135 "owner": {

136 "name": "DevTools Team",

137 "email": "devtools@example.com"

138 },

139 "plugins": [

140 {

141 "name": "code-formatter",

142 "source": "./plugins/formatter",

143 "description": "在保存時自動格式化程式碼",

144 "version": "2.1.0",

145 "author": {

146 "name": "DevTools Team"

147 }

148 },

149 {

150 "name": "deployment-tools",

151 "source": {

152 "source": "github",

153 "repo": "company/deploy-plugin"

154 },

155 "description": "部署自動化工具"

156 }

157 ]

158}

159```

~~160~~

161<h2 id="marketplace-schema">

162 Marketplace 架構

163</h2>

~~164~~

165<h3 id="required-fields">

166 必需欄位

167</h3>

~~168~~

169| 欄位 | 類型 | 描述 | 範例 |

170| :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------- |

171| `name` | string | Marketplace 識別碼（kebab-case，無空格、控制字元或雙向格式化字元）。這是公開的：使用者在安裝 plugin 時會看到它（例如，`/plugin install my-tool@your-marketplace`）。每個使用者只能為每個名稱註冊一個 marketplace：新增第二個同名 marketplace 會取代第一個。若要在一個 marketplace 名稱下發佈多個 plugin，請在[單一 `marketplace.json`](#create-the-marketplace-file) 中列出它們全部。 | `"acme-tools"` |

~~174~~

175<Note>

176 **保留名稱**：以下 marketplace 名稱保留供 Anthropic 官方使用，第三方 marketplace 無法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`claude-tag-plugins`、`healthcare`。模仿官方 marketplace 的名稱（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留這些名稱可防止第三方 marketplace 將自己冒充為 Anthropic 發佈的來源。

~~177~~

178 Claude Code 每次載入 marketplace 時都會重新檢查保留名稱，而不僅在您新增 marketplace 時檢查。在名稱成為保留名稱之前以其中一個名稱註冊的 marketplace 會停止載入，並報告它是[從不受信任的來源註冊](/docs/zh-TW/errors#marketplace-is-registered-from-an-untrusted-source)。移除該 marketplace，並從官方 Anthropic 來源重新新增它。受新保留名稱影響的第三方 marketplace 在您以不同名稱重新新增它後立即再次載入。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 未被保留，已在保留名稱下註冊的 marketplace 繼續載入。在 v2.1.265 之前，`claude-tag-plugins` 未被保留。

~~179~~

180 您也無法將 marketplace 命名為 `npm`、`pip`、`uv`、`cargo`、`github` 或 `gh`（任何大小寫）。此檢查需要 Claude Code v2.1.275 或更新版本。

181</Note>

~~182~~

183<h3 id="owner-fields">

184 Owner 欄位

185</h3>

~~186~~

187| 欄位 | 類型 | 必需 | 描述 |

188| :------ | :----- | :- | :-------------------- |

191| `url` | string | 否 | 網站、GitHub 個人檔案或組織 URL |

~~192~~

193<h3 id="optional-fields">

194 選用欄位

195</h3>

~~196~~

197| 欄位 | 類型 | 描述 |

198| :------------------------------------ | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

199| `$schema` | string | JSON Schema URL，用於編輯器自動完成和驗證。Claude Code 在載入時會忽略此欄位。 |

200| `description` | string | 簡短的 marketplace 描述 |

201| `version` | string | Marketplace 版本 |

202| `metadata.pluginRoot` | string | Claude Code 解析裸 plugin 來源名稱的目錄。請參閱[相對路徑](#relative-paths)。需要 Claude Code v2.1.239 或更新版本。 |

203| `allowCrossMarketplaceDependenciesOn` | array | 此 marketplace 中的 plugin 可能依賴的其他 marketplace。來自此處未列出的 marketplace 的相依性在安裝時被阻止。請參閱[依賴來自另一個 marketplace 的 plugin](/docs/zh-TW/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)。 |

204| `renames` | object | 從前一個 plugin `name` 對應到其目前名稱，或對應到 `null`（如果 plugin 已移除）的對應。當您重新命名或移除 `plugins` 中的項目時，可讓現有使用者自動遷移。請參閱[重新命名或移除 plugin](#rename-or-remove-a-plugin)。需要 Claude Code v2.1.193 或更新版本。 |

~~205~~

206`description` 和 `version` 也可在 `metadata` 下接受，以保持向後相容性。

~~207~~

208<h2 id="plugin-entries">

209 Plugin 項目

210</h2>

~~211~~

212`plugins` 陣列中的每個 plugin 項目都描述了一個 plugin 及其位置。您可以包含來自 [plugin manifest schema](/docs/zh-TW/plugins-reference#plugin-manifest-schema) 的任何欄位，例如 `description`、`version`、`author`、`commands` 和 `hooks`，加上這些 marketplace 特定欄位：`source`、`category`、`tags`、`strict`、`relevance`、`headers` 和 `headersHelper`。

~~213~~

214<h3 id="required-fields-2">

215 必需欄位

216</h3>

~~217~~

218| 欄位 | 類型 | 說明 |

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

220| `name` | string | Plugin 識別碼，採用 kebab-case 格式，不含空格、控制字元或雙向格式化字元。這是公開的：使用者在安裝時會看到它（例如，`/plugin install my-plugin@marketplace`）。 |

~~222~~

223<h3 id="optional-plugin-fields">

224 選用 plugin 欄位

225</h3>

~~226~~

227**標準中繼資料欄位：**

~~228~~

229| 欄位 | 類型 | 說明 |

230| :--------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

231| `displayName` | string | 在 UI 介面中顯示的人類可讀名稱。當項目和 plugin 的 `plugin.json` 都未設定時，使用者會看到 plugin 的 `name`。可以包含空格和任何大小寫。不用於命名空間或查詢。 |

232| `description` | string | 簡短的 plugin 說明 |

233| `version` | string | Plugin 版本。如果設定（在此處或在 `plugin.json` 中），plugin 會固定到此字串，使用者只有在版本變更時才會收到更新。具有 [`command` source](#command-sources) 的 plugin 不會由任一欄位固定。從 marketplace 新增為本機目錄且 [loaded in place](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution) 的 plugin 也不會。如果在兩個位置都未設定，版本來自 [version management](/docs/zh-TW/plugins-reference#version-management) 中的下一個來源。 |

234| `author` | object | Plugin 作者資訊（`name` 必需；`email` 和 `url` 選用） |

235| `homepage` | string | Plugin 首頁或文件 URL |

236| `repository` | string | 原始碼儲存庫 URL |

237| `license` | string | SPDX 授權識別碼（例如，MIT、Apache-2.0） |

238| `keywords` | array | 用於 plugin 探索和分類的標籤 |

239| `metadata` | object | 自由格式物件，用於您自己的欄位，例如權利或目錄資料。Claude Code 不會讀取它。在 v2.1.222 之前，`claude plugin validate` 會將該鍵報告為無法識別的欄位。 |

240| `category` | string | 用於組織的 plugin 類別 |

241| `tags` | array | 用於搜尋的標籤 |

242| `strict` | boolean | 控制 `plugin.json` 是否為元件定義的權威（預設值：true）。請參閱下方的 [Strict mode](#strict-mode)。 |

243| `relevance` | object | 告訴 Claude Code 何時向使用者建議此 plugin 的訊號。僅對管理員在受管設定中允許列表的 marketplace 生效。請參閱 [Recommend plugins for your org](/docs/zh-TW/plugin-relevance)。 |

244| `defaultEnabled` | boolean | 安裝後 plugin 是否啟用（預設值：true）。設定為 `false` 以安裝已停用的 plugin，直到使用者選擇加入。優先於 plugin 的 `plugin.json` 中的相同欄位。請參閱 [Default enablement](/docs/zh-TW/plugins-reference#default-enablement)。 |

~~245~~

246項目和 plugin 自己的 `plugin.json` 都可以設定顯示欄位 `displayName`、`description`、`author`、`homepage`、`repository`、`license` 和 `keywords`。在 plugin 清單和詳細資訊中，安裝前後：

~~247~~

248* 對於您在項目上設定的欄位，使用者會看到項目的值，即使 `plugin.json` 設定了不同的值。

249* 對於項目未設定的欄位，使用者會看到 `plugin.json` 值。

~~250~~

251安裝前，Claude Code 只能為具有 [relative-path source](#relative-paths) 的項目讀取 `plugin.json`，其 plugin 檔案位於 marketplace 內部。對於具有任何其他來源類型的項目，使用者在安裝 plugin 之前只會看到項目自己的欄位。

~~252~~

253**元件設定欄位：**

~~254~~

255| 欄位 | 類型 | 說明 |

256| :----------- | :------------- | :----------------------------------- |

~~263~~

264**封存驗證欄位：**

~~265~~

266當項目在需要認證的伺服器上具有 [`archive` source](#zip-archives) 時設定這些。

~~267~~

268| 欄位 | 類型 | 說明 |

269| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

270| `headers` | object | Claude Code 在下載此項目的封存時傳送的 HTTP 標頭。覆寫 marketplace 的相同名稱的標頭。需要 Claude Code v2.1.238 或更新版本。 |

271| `headersHelper` | string | 命令，將此項目的封存下載的 HTTP 標頭列印為一個 JSON 物件，用於過期的認證。請參閱 [Authenticate archive downloads](#authenticate-archive-downloads)。項目還必須設定 [`"strict": false`](#strict-mode)。需要 Claude Code v2.1.238 或更新版本。 |

~~272~~

273<h2 id="plugin-sources">

274 Plugin 來源

275</h2>

~~276~~

277Plugin 來源告訴 Claude Code 在您的 marketplace 中列出的每個個別 plugin 從何處取得。這些在 `marketplace.json` 中每個 plugin 項目的 `source` 欄位中設定。

~~278~~

279Claude Code 將每個已安裝的 plugin 複製到本機版本化 plugin 快取中，位於 `~/.claude/plugins/cache`，除非 plugin 就地載入。[連結模式中的 `command` 來源](#copy-mode-and-link-mode)就地載入，[相對路徑來源](#relative-paths)從本機目錄新增的 marketplace 也是如此。Claude Code 也會[將 plugin 的合格 Node.js 套件相依性安裝](/docs/zh-TW/plugins-reference#node-js-package-dependencies)到快取副本中。請參閱[Plugin 快取和檔案解析](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)以了解從本機目錄 marketplace 就地載入的 plugin 如何取得您的編輯。

~~280~~

281| 來源 | 類型 | 欄位 | 備註 |

282| ------------ | ---------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |

~~290~~

291<Note>

292 **Marketplace 來源與 plugin 來源**：這些是控制不同事物的不同概念。

~~293~~

294 * **Marketplace 來源**：從何處取得 `marketplace.json` 目錄本身。在使用者執行 `/plugin marketplace add` 或在 `extraKnownMarketplaces` 設定中設定。基於 Git 的 marketplace 來源支援 `ref`（分支/標籤）但不支援 `sha`。

295 * **Plugin 來源**：從何處取得 marketplace 中列出的個別 plugin。在 `marketplace.json` 內每個 plugin 項目的 `source` 欄位中設定。基於 Git 的 plugin 來源同時支援 `ref`（分支/標籤）和 `sha`（確切提交）。

~~296~~

297 例如，託管在 `acme-corp/plugin-catalog`（marketplace 來源）的 marketplace 可以列出從 `acme-corp/code-formatter`（plugin 來源）取得的 plugin。marketplace 來源和 plugin 來源指向不同的儲存庫，並獨立固定。

298</Note>

~~299~~

300下面的基於 git 的來源類型為 `github`、`url` 和 `git-subdir`。當任何一個上同時設定 `ref` 和 `sha` 時，`sha` 是有效的固定。Claude Code 直接取得並簽出固定的提交。

~~301~~

302在大多數 git 主機上，包括 GitHub、GitLab 和 Bitbucket，這表示即使上游的 `ref` 命名的分支或標籤已被刪除，只要提交仍可從儲存庫到達，安裝就會成功。某些伺服器（例如 AWS CodeCommit）不支援透過 SHA 取得提交。在這些伺服器上，`ref` 仍必須存在，且固定的提交必須可從其到達。

~~303~~

304如果您透過**組織設定 > Plugins** 分發 plugin，只允許某些來源類型。請參閱[透過組織設定分發](#distribute-through-organization-settings)。

~~305~~

306<h3 id="relative-paths">

307 相對路徑

308</h3>

~~309~~

310對於同一儲存庫中的 plugin，使用以 `./` 開頭的路徑：

~~311~~

312```json theme={null}

313{

314 "name": "my-plugin",

315 "source": "./plugins/my-plugin"

316}

317```

~~318~~

319路徑相對於 marketplace 根目錄解析，即包含 `.claude-plugin/` 的目錄。來源 `./plugins/my-plugin` 因此指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位於 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 參考 marketplace 根目錄外的路徑。在 macOS 和 Linux 上，Claude Code 拒絕在前導 `./` 之後任何地方有反斜線的項目路徑，因此在每個平台上將分隔符寫為 `/`。

~~320~~

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

~~322~~

323`metadata.pluginRoot` 本身必須是 marketplace 內的相對路徑。Claude Code 會忽略已以 `./` 開頭的來源。包含 `/` 的來源（例如 `team-a/formatter`）不是裸名稱，即使設定了 `metadata.pluginRoot`，仍需要 `./` 前綴。

~~324~~

325<Note>

326 Claude Code 相對於 marketplace 的本機副本解析相對路徑，因此當使用者從 git 來源或本機目錄新增您的 marketplace 時可以運作。如果使用者透過直接 URL 新增您的 marketplace 到 `marketplace.json` 檔案，相對路徑將無法解析，因為 Claude Code 只會下載該檔案。對於基於 URL 的分發，請改用任何其他 [plugin 來源](#plugin-sources)。請參閱[疑難排解](#plugins-with-relative-paths-fail-in-url-based-marketplaces)以了解詳細資訊。

327</Note>

~~328~~

329<h3 id="github-repositories">

330 GitHub 儲存庫

331</h3>

~~332~~

333```json theme={null}

334{

335 "name": "github-plugin",

336 "source": {

337 "source": "github",

338 "repo": "owner/plugin-repo"

339 }

340}

341```

~~342~~

343您可以固定到特定分支、標籤或提交：

~~344~~

345```json theme={null}

346{

347 "name": "github-plugin",

348 "source": {

349 "source": "github",

350 "repo": "owner/plugin-repo",

351 "ref": "v2.0.0",

352 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

353 }

354}

355```

~~356~~

357| 欄位 | 類型 | 描述 |

358| :----- | :----- | :------------------------------- |

359| `repo` | string | 必需。`owner/repo` 格式的 GitHub 儲存庫 |

360| `ref` | string | 選用。Git 分支或標籤（預設為儲存庫預設分支） |

361| `sha` | string | 選用。完整的 40 字元 git 提交 SHA 以固定到確切版本 |

~~362~~

363<h3 id="git-repositories">

364 Git 儲存庫

365</h3>

~~366~~

367```json theme={null}

368{

369 "name": "git-plugin",

370 "source": {

371 "source": "url",

372 "url": "https://gitlab.com/team/plugin.git"

373 }

374}

375```

~~376~~

377您可以固定到特定分支、標籤或提交：

~~378~~

379```json theme={null}

380{

381 "name": "git-plugin",

382 "source": {

383 "source": "url",

384 "url": "https://gitlab.com/team/plugin.git",

385 "ref": "main",

386 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

387 }

388}

389```

~~390~~

391| 欄位 | 類型 | 描述 |

392| :---- | :----- | :--------------------------------------------------------------------------------------------------- |

393| `url` | string | 必需。完整的 git 儲存庫 URL（`https://` 或 `git@`）。`.git` 後綴是選用的，因此 Azure DevOps 和 AWS CodeCommit URL 不含後綴也可以運作 |

394| `ref` | string | 選用。Git 分支或標籤（預設為儲存庫預設分支） |

395| `sha` | string | 選用。完整的 40 字元 git 提交 SHA 以固定到確切版本 |

~~396~~

397<h3 id="git-subdirectories">

398 Git 子目錄

399</h3>

~~400~~

401使用 `git-subdir` 指向位於 git 儲存庫子目錄內的 plugin。Claude Code 使用稀疏、部分複製來僅取得子目錄，最小化大型 monorepo 的頻寬。

~~402~~

403```json theme={null}

404{

405 "name": "my-plugin",

406 "source": {

407 "source": "git-subdir",

408 "url": "https://github.com/acme-corp/monorepo.git",

409 "path": "tools/claude-plugin"

410 }

411}

412```

~~413~~

414您可以固定到特定分支、標籤或提交：

~~415~~

416```json theme={null}

417{

418 "name": "my-plugin",

419 "source": {

420 "source": "git-subdir",

421 "url": "https://github.com/acme-corp/monorepo.git",

422 "path": "tools/claude-plugin",

423 "ref": "v2.0.0",

424 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

425 }

426}

427```

~~428~~

429`url` 欄位也接受 GitHub 簡寫（`owner/repo`）或 SSH URL（`git@github.com:owner/repo.git`）。

~~430~~

431| 欄位 | 類型 | 描述 |

432| :----- | :----- | :-------------------------------------------------- |

433| `url` | string | 必需。Git 儲存庫 URL、GitHub `owner/repo` 簡寫或 SSH URL |

434| `path` | string | 必需。儲存庫內包含 plugin 的子目錄路徑（例如，`"tools/claude-plugin"`） |

435| `ref` | string | 選用。Git 分支或標籤（預設為儲存庫預設分支） |

436| `sha` | string | 選用。完整的 40 字元 git 提交 SHA 以固定到確切版本 |

~~437~~

438<h3 id="npm-packages">

439 npm 套件

440</h3>

~~441~~

442npm 來源可以命名公開 npm 登錄表或您的團隊託管的私人登錄表上的任何套件。Claude Code 使用您的 npm 用戶端解析套件、下載 tarball 並將其解包到 plugin 快取中。

~~443~~

444套件的安裝指令碼（例如 `preinstall` 或 `postinstall`）永遠不會執行，其相依性在取得期間不會安裝。

~~445~~

446如果套件在其 `package.json` 旁邊提供支援的 lockfile，Claude Code 會在單獨的步驟中安裝那些[Node.js 套件相依性](/docs/zh-TW/plugins-reference#node-js-package-dependencies)，也會停用指令碼。否則，發佈已建置所需一切的 plugin。需要其他套件的 MCP 伺服器可以透過 `npx` 啟動，它在首次執行時安裝它們。

~~447~~

448```json theme={null}

449{

450 "name": "my-npm-plugin",

451 "source": {

452 "source": "npm",

453 "package": "@acme/claude-plugin"

454 }

455}

456```

~~457~~

458若要固定到特定版本，請新增 `version` 欄位：

~~459~~

460```json theme={null}

461{

462 "name": "my-npm-plugin",

463 "source": {

464 "source": "npm",

465 "package": "@acme/claude-plugin",

466 "version": "2.1.0"

467 }

468}

469```

~~470~~

471若要從私人或內部登錄表安裝，請新增 `registry` 欄位：

~~472~~

473```json theme={null}

474{

475 "name": "my-npm-plugin",

476 "source": {

477 "source": "npm",

478 "package": "@acme/claude-plugin",

479 "version": "^2.0.0",

480 "registry": "https://npm.example.com"

481 }

482}

483```

~~484~~

485| 欄位 | 類型 | 描述 |

486| :--------- | :----- | :--------------------------------------------- |

487| `package` | string | 必需。套件名稱或範圍套件（例如，`@org/plugin`） |

488| `version` | string | 選用。版本或版本範圍（例如，`2.1.0`、`^2.0.0`、`~1.5.0`） |

489| `registry` | string | 選用。自訂 npm 登錄表 URL。預設為系統 npm 登錄表（通常為 npmjs.org） |

~~490~~

491<h3 id="zip-archives">

492 Zip 封存

493</h3>

~~494~~

495使用 `archive` 將 plugin 分發為 Claude Code 透過 HTTPS 下載的 zip 檔案，因此安裝在使用者的機器上無需 git 或 npm 即可運作。在任何靜態檔案伺服器或成品儲存庫上託管該檔案，例如 S3 儲存桶、Artifactory 通用儲存庫或 nginx。需要 Claude Code v2.1.224 或更新版本。在 v2.1.120 到 v2.1.223 版本上，安裝 plugin 失敗，並顯示 `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`；在較舊版本上，包含 `archive` 項目的 marketplace 完全無法載入。

~~496~~

497此項目從成品伺服器上的 zip 檔案安裝 plugin：

~~498~~

499```json theme={null}

500{

501 "name": "my-plugin",

502 "source": {

503 "source": "archive",

504 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"

505 }

506}

507```

~~508~~

509當您建立 zip 時，您可以直接壓縮 plugin 的內容或壓縮 plugin 資料夾本身。Claude Code 在封存的頂部查找 `.claude-plugin/`，然後在單一頂層資料夾內查找，因此兩種配置都會安裝：

~~510~~

511```text theme={null}

512my-plugin.zip my-plugin.zip

513├── .claude-plugin/ └── my-plugin/

514│ └── plugin.json ├── .claude-plugin/

515└── commands/ │ └── plugin.json

516 └── commands/

517```

~~518~~

519Claude Code 不會查找超過一個資料夾，因此嵌套更深的 plugin 無法安裝。Claude Code 拒絕大於 256 MiB 的封存。

~~520~~

521若要固定確切檔案，請新增 `sha256` 欄位，其中包含封存的摘要：

~~522~~

523```json theme={null}

524{

525 "name": "my-plugin",

526 "source": {

527 "source": "archive",

528 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",

529 "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"

530 }

531}

532```

~~533~~

534如果下載的檔案與固定不符，Claude Code 拒絕安裝並報告 [`Plugin archive integrity check failed`](/docs/zh-TW/errors#plugin-archive-integrity-check-failed)。

~~535~~

536封存來源接受這些欄位：

~~537~~

538| 欄位 | 類型 | 描述 |

539| :------- | :----- | :---------------------------------------------------------------------------------------------------------- |

540| `url` | string | 必需。zip 封存的 HTTPS URL。Claude Code 拒絕 `http://` URL，以及迴圈、連結本機和雲端中繼資料主機。每個重新導向躍點都必須滿足相同的規則，否則 Claude Code 拒絕下載 |

541| `sha256` | string | 選用。封存的 SHA-256 摘要，為 64 個十六進位字元，大寫或小寫。Claude Code 驗證每次下載並在不符時拒絕安裝 |

~~542~~

543`sha256` 摘要也會在 `plugin.json` 或 marketplace 項目都未宣告版本時作為 plugin 的版本。請參閱[版本管理](/docs/zh-TW/plugins-reference#version-management)。如果您宣告 `version`，該版本字串是更新信號，因此在變更 zip 及其摘要後，也要提升版本，否則使用者會保留快取副本。

~~544~~

545<h4 id="authenticate-archive-downloads">

546 驗證封存下載

547</h4>

~~548~~

549若要驗證封存下載（例如從私人登錄表下載），請設定 Claude Code 隨其發送的 HTTP 標頭。在您註冊 marketplace 的 `url` 來源上設定 `headers`，例如 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目。在 Claude Code v2.1.238 或更新版本上，您可以改為在 plugin 的項目上設定它，在 `source` 旁邊。

~~550~~

551如果您要放在 `headers` 中的值是短期的，例如您的登錄表應要求時鑄造的權杖，請改為在同一位置設定 `headersHelper` 命令。Claude Code 執行命令並將其列印的 JSON 物件作為該位置的標頭發送。需要 Claude Code v2.1.238 或更新版本。

~~552~~

553您選擇的位置決定哪些下載取得標頭以及 Claude Code 何時執行命令：

~~554~~

555| 位置 | 取得標頭的下載 | Claude Code 何時執行在該處設定的 `headersHelper` |

556| :------------------- | :--------------------------------------- | :--------------------------------------------------------------------------------------- |

557| Marketplace `url` 來源 | marketplace URL 來源上的封存下載，意思是相同的配置、主機和連接埠 | 在每次取得 marketplace 的 `marketplace.json` 之前以及在該來源上每次封存下載之前。Claude Code 將一次執行的輸出重複使用最多 60 秒 |

558| Plugin 項目 | 該項目的下載只有 | 只有當使用者自行安裝或更新該一個 plugin 並[接受命令](#how-users-accept-a-headershelper-command)時 |

~~559~~

560當兩個位置都設定相同名稱的標頭時，Claude Code 發送項目的值。在一個位置內，命令列印的標頭會覆蓋相同名稱的列出標頭。

~~561~~

562<h5 id="add-a-headershelper-to-a-plugin-entry">

563 將 headersHelper 新增到 plugin 項目

564</h5>

~~565~~

566此項目在 `source` 旁邊設定 `headersHelper`。它也設定 `"strict": false`，Claude Code 要求設定 `headersHelper` 的 `marketplace.json` 項目。使用 [`"strict": false`](#strict-mode)，marketplace 項目是 plugin 的完整定義，因此使用者可以在接受命令之前檢查 plugin 包含的內容：

~~567~~

568```json theme={null}

569{

570 "name": "my-plugin",

571 "description": "內部服務的格式化命令",

572 "strict": false,

573 "commands": "./commands",

574 "source": {

575 "source": "archive",

576 "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"

577 },

578 "headersHelper": "/opt/bin/mint-registry-token.sh"

579}

580```

~~581~~

582若要檢查項目，請執行 `claude plugin install my-plugin@your-marketplace`。Claude Code 向您顯示命令和封存 URL，並在您接受後下載 zip。

~~583~~

584在 v2.1.238 之前，Claude Code 下載項目的封存時沒有其 `headers` 或 `headersHelper`，因此依賴它們的安裝失敗，並顯示 `HTTP 401 while downloading plugin archive from`，後面跟著 URL，登錄表的狀態碼代替 401。

~~585~~

586<h4 id="write-the-headershelper-command">

587 寫入 headersHelper 命令

588</h4>

~~589~~

590無論您在 marketplace 的 `url` 來源或 plugin 項目上設定 `headersHelper`，請寫入命令以滿足這些要求：

~~591~~

592* **命令文字**：最多 500 個可列印 ASCII 字元，沒有四個或更多空格的執行。

593* **輸出**：在 stdout 上列印一個標頭名稱和字串值的 JSON 物件，然後在 10 秒內以代碼 0 結束。

594* **Shell 和工作目錄**：Claude Code 透過 `sh` 或 Windows 上的 `cmd.exe` 從設定目錄 `~/.claude` 或 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars#variables) 執行命令。給出絕對路徑或 `PATH` 上的命令，因為相對路徑相對於該目錄解析，而不是使用者的專案。

595* **Claude Code 移除的變數**：從 `marketplace.json` 項目或專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中設定的命令環境中，Claude Code 移除每個名稱包含 `TOKEN`、`SECRET`、`KEY` 或 `AUTH` 等字詞的變數，包括 `ANTHROPIC_API_KEY`。Claude Code 不會將此移除應用於在使用者設定、`--settings` 檔案或受管設定中設定的命令。

596* **Claude Code 設定的變數**：`CLAUDE_CODE_MARKETPLACE_URL` 和 `CLAUDE_CODE_MARKETPLACE_NAME` 用於 `url` 來源的命令，以及 `CLAUDE_CODE_PLUGIN_NAME` 和 `CLAUDE_CODE_PLUGIN_ARCHIVE_URL` 用於項目的命令。`CLAUDE_CODE_MARKETPLACE_NAME` 在使用者透過 URL 新增 marketplace 後的第一次取得時未設定，因為該取得是提供名稱的內容。

~~597~~

598鑄造持有人權杖的命令列印如下物件：

~~599~~

600```json theme={null}

601{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

602```

~~603~~

604<h4 id="when-claude-code-skips-a-headershelper-command-or-drops-its-output">

605 Claude Code 何時跳過 headersHelper 命令或捨棄其輸出

606</h4>

~~607~~

608Claude Code 不執行 `headersHelper` 命令，或在這些情況下捨棄來自 `headers` 或命令輸出的標頭：

~~609~~

610* **命令失敗**：如果命令以非零代碼結束、執行超過 10 秒或列印除字串值的 JSON 物件以外的任何內容，Claude Code 不會進行它執行命令的取得或下載。

611* **Marketplace URL 不以 `https://` 開頭**：Claude Code 不執行該 `url` 來源的命令，只發送其 `headers` 欄位中列出的標頭。

612* **重新導向離開來源**：當下載從封存 URL 的來源重新導向時，Claude Code 捨棄 marketplace `url` 來源和 plugin 項目的 `headers` 值和命令輸出。

613* **項目設定路由或身分標頭**：Claude Code 從項目的 `headers` 和命令輸出中捨棄請求路由和用戶端身分名稱（例如 `Host`、`Cookie` 和 `X-Forwarded-*`），並保留驗證名稱（例如 `Authorization`）。Claude Code 以這種方式篩選每個 `marketplace.json` 項目，以及[內嵌設定項目](/docs/zh-TW/settings-reference#extraknownmarketplaces)取決於哪個檔案宣告它。

614* **在 `--add-dir` 目錄的設定中設定的命令**：Claude Code 忽略它，在 `url` 來源和[內嵌 plugin 項目](/docs/zh-TW/settings-reference#extraknownmarketplaces)上都一樣，只發送該檔案的 `headers`。

615* **受管設定阻止命令**：將 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) 設定為 `true` 會阻止 `headersHelper` 命令，[`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) 也會阻止它們，除非 `disableCommandPluginSources` 明確為 `false`。在任一阻止下，Claude Code 仍會為受管設定本身宣告的 marketplace 執行命令。

~~616~~

617<h4 id="how-users-accept-a-headershelper-command">

618 使用者如何接受 headersHelper 命令

619</h4>

~~620~~

621使用者每次從 plugin 的自己的檢視在 `/plugin` 或使用 `claude plugin install` 或 `claude plugin update` 自行安裝或更新該一個 plugin 時接受 plugin 項目的命令。Claude Code 顯示命令和封存 URL，並僅在使用者接受後執行命令。

~~622~~

623在非互動式 shell 中，傳遞 [`--yes`](/docs/zh-TW/plugins-reference#plugin-install) 以接受命令。若要接受只有先前 `--json` 執行顯示的命令，傳遞 [`--accept-command`](/docs/zh-TW/plugins-reference#plugin-install) 與執行報告的 `sha256`。

~~624~~

625Claude Code 只執行它顯示的命令，用於它顯示的封存 URL。如果項目的命令或封存 URL 在中間變更，Claude Code 拒絕安裝或更新。查詢字串中的變更單獨不計算。

~~626~~

627<h5 id="installs-and-updates-that-refuse-the-command-instead-of-asking">

628 拒絕命令而不是詢問的安裝和更新

629</h5>

~~630~~

631在任何其他操作上，而不是單一 plugin 安裝或更新，Claude Code 既不執行項目的命令也不下載其封存，因此 plugin 保持在其已安裝版本或保持未安裝。使用者看到的內容取決於操作：

~~632~~

633* **一次安裝多個 plugin、從 plugin 建議或作為另一個 plugin 的相依性**：Claude Code 拒絕具有命令的 plugin 並將使用者指向該 plugin 在 `/plugin` 中的自己的檢視。批量安裝中的其他 plugin 仍會安裝。依賴被拒絕 plugin 的 plugin 無法安裝，直到使用者自行安裝被拒絕的 plugin。

634* **背景自動更新，或工作階段開始用於其封存從未下載的 plugin**：Claude Code 在 `/plugin` 錯誤標籤中列出 plugin，以便使用者知道手動安裝或更新它。找到項目的自動更新仍會宣傳已安裝版本列出任何內容。

~~635~~

636<h5 id="when-a-marketplace-url-source’s-command-runs">

637 Marketplace `url` 來源的命令何時執行

638</h5>

~~639~~

640Marketplace `url` 來源的 `headersHelper` 在設定檔案中宣告，例如 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目，而不是在 marketplace 發佈的目錄中，因此 Claude Code 不會在每次安裝或更新時詢問使用者接受它。宣告它的設定檔案決定 Claude Code 何時執行它：

~~641~~

642| 設定檔案 | Claude Code 何時執行命令 |

643| :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |

644| 使用者設定、`--settings` 檔案或機器上的受管設定檔案 | 無需詢問，包括在背景 marketplace 重新整理期間 |

645| 專案的 `.claude/settings.json` 或 `.claude/settings.local.json` | 只有在使用者接受該資料夾本身的[工作區信任對話](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)後。`-p` 或 SDK 工作階段不計算為接受它，父資料夾的信任也不計算 |

646| 伺服器受管設定 | 只有在使用者在[安全核准對話](/docs/zh-TW/server-managed-settings#security-approval-dialogs)中核准傳遞的設定後 |

~~647~~

648在 `-p` 或 SDK 工作階段中，Claude Code 無法顯示安全核准對話。它應用其他傳遞的設定，但 marketplace 取得以及任何需要命令的封存下載失敗，直到使用者在互動式工作階段中核准。

~~649~~

650對於這些檔案之一中的[內嵌 plugin 項目](/docs/zh-TW/settings-reference#extraknownmarketplaces)，Claude Code 要求與該檔案中 marketplace 層級命令相同的資料夾信任或設定核准，使用者也在每次安裝或更新時接受項目的命令。

~~651~~

652<h3 id="command-sources">

653 Command 來源

654</h3>

~~655~~

656當本機安裝的工具產生 plugin 目錄時使用 `command`，例如為目前選定的工具鏈呈現其 plugin 的 IDE。Claude Code 在使用者安裝 plugin 時執行命令，並在背景中每個工作階段重新執行一次，因此您的使用者無需重新安裝即可取得工具的變更輸出。需要 Claude Code v2.1.229 或更新版本。在 v2.1.120 到 v2.1.228 上，安裝 plugin 失敗，並顯示 `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`，在較舊版本上整個 marketplace 無法載入。

~~657~~

658此項目從工具列印的任何目錄安裝 plugin：

~~659~~

660```json theme={null}

661{

662 "name": "my-plugin",

663 "source": {

664 "source": "command",

665 "command": "my-tool claude-plugin-path"

666 }

667}

668```

~~669~~

670Claude Code 透過平台 shell（macOS 和 Linux 上的 `sh` 或 Windows 上的 `cmd.exe`）從使用者的主目錄執行命令。命令必須在 stdout 上列印恰好一行並以代碼 0 結束。該行是包含完整 plugin 的目錄的絕對路徑，命令結束時，路徑可能在執行之間變更。

~~671~~

672Claude Code 停止執行時間超過 `timeout` 秒的命令，安裝或更新失敗。Claude Code 也在這些情況下拒絕列印的路徑，安裝或更新以相同方式失敗：

~~673~~

674* 目錄在其頂層沒有 plugin 內容，例如 `.claude-plugin/` 目錄或 `skills/`、`commands/`、`agents/` 或 `hooks/` 目錄

675* 目錄是 Claude Code 啟動的目錄，或其父目錄之一

676* 在 Windows 上，路徑是 UNC 路徑

~~677~~

678Command 來源接受這些欄位：

~~679~~

680| 欄位 | 類型 | 描述 |

681| :-------- | :----- | :----------------------------------------------------------------------------------------------------------- |

682| `command` | string | 必需。Shell 命令，在 stdout 上列印 plugin 目錄的絕對路徑作為單一行並結束 0。必須是可列印 ASCII，最多 500 個字元，沒有四個或更多空格的執行，以便使用者可以檢查他們被要求接受的整個命令 |

683| `timeout` | number | 選用。放棄前等待命令的整數秒數（預設：60，最大：600） |

684| `mode` | string | 選用。`"copy"`（預設）將列印的目錄複製到 plugin 快取中。`"link"` 使用列印的目錄就地。請參閱[複製模式和連結模式](#copy-mode-and-link-mode) |

~~685~~

686<h4 id="copy-mode-and-link-mode">

687 複製模式和連結模式

688</h4>

~~689~~

690使用預設 `"mode": "copy"`，Claude Code 將列印的目錄複製到版本化 plugin 快取中，並從目錄內容的雜湊衍生[plugin 版本](/docs/zh-TW/plugins-reference#version-management)。您的工具可以在命令結束後刪除或重寫目錄，產生相同內容的重新執行計為最新。Claude Code 拒絕安裝大於 256 MiB 或包含超過 20,000 項目的目錄。

~~691~~

692為大型 plugin 目錄設定 `"mode": "link"`，不應複製，例如呈現的 SDK 匯出。Claude Code 使用連結填充 plugin 的快取項目到列印目錄的每個頂層項目，並就地使用檔案，因此不複製任何內容、不雜湊檔案內容，大小限制不適用。如果頂層項目是指向列印目錄外的符號連結，安裝失敗。Claude Code 也跳過連結模式 plugin 的 [Node.js 套件相依性安裝](/docs/zh-TW/plugins-reference#node-js-package-dependencies)，因此列印已包含 plugin 需要的任何 `node_modules` 的目錄。

~~693~~

694保持列印的目錄就地，只要 plugin 保持安裝。Claude Code 在每次啟動時透過這些連結載入 plugin。Claude Code 從列印目錄的真實路徑及其頂層項目衍生[plugin 版本](/docs/zh-TW/plugins-reference#version-management)，而不是檔案內部，因此列印不同的路徑以表示新內容。在列印目錄或其下方啟動的工作階段中，Claude Code 完全不載入 plugin。

~~695~~

696Claude Code 不支援 Windows 上的連結模式，拒絕在那裡安裝連結模式 plugin。改為宣告 `"mode": "copy"`。

~~697~~

698<h4 id="how-users-accept-the-command">

699 使用者如何接受命令

700</h4>

~~701~~

702Claude Code 在使用者的機器上執行您的命令，因此它將每次執行繫結到使用者的明確接受：

~~703~~

704* 當使用者從 `/plugin` 中的其詳細資訊畫面安裝 plugin，或在互動式終端中使用 `claude plugin install` 或 `claude plugin update` 安裝或更新它時，Claude Code 首先向他們顯示確切的命令字串，並記錄該安裝的已接受命令。可以在相同命令的已記錄接受上進行的 `claude plugin update` 不顯示任何內容。

705* 在非互動式 shell 中，例如佈建指令碼，傳遞 `--yes` 到 `claude plugin install` 或 `claude plugin update` 以接受它列印的命令。若要接受只有先前 `--json` 執行顯示的命令，傳遞 [`--accept-command`](/docs/zh-TW/plugins-reference#plugin-install) 與執行報告的 `sha256`。

706* 每條其他路徑只執行使用者已接受的命令。這包括從 `/plugin` 啟動的更新以及[Claude Code 何時重新執行命令](#when-claude-code-re-runs-the-command)中描述的背景執行。當未接受任何內容時，Claude Code 拒絕執行命令並告訴使用者如何檢查它。Claude Code 從不將 command 來源的 plugin 安裝為另一個 plugin 的相依性，因此使用者自行先安裝它。

707* 如果您變更項目的 `command` 或切換其 `mode`，使用者保留他們已有的版本，Claude Code 停止重新執行命令。在互動式工作階段中，`/plugin` 錯誤標籤顯示新命令，直到使用者透過執行 `claude plugin update <plugin>@<marketplace>` 檢查並接受它。

~~708~~

709系統管理員可以使用受管設定 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) 在整個組織中阻止 command 來源。如果組織設定 [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly)，Claude Code 預設會阻止 command 來源。

~~710~~

711<h4 id="when-claude-code-re-runs-the-command">

712 Claude Code 何時重新執行命令

713</h4>

~~714~~

715列印的目錄反映工具在命令執行時的狀態，因此 Claude Code 在這些時間重新執行命令：

~~716~~

717* 每次使用者安裝或更新 plugin

718* 每個工作階段一次用於每個啟用的 command 來源 plugin，在背景中，工作階段啟動後不久。此執行不透過 marketplace 自動更新進行，因此不取決於 marketplace 的[自動更新設定](/docs/zh-TW/discover-plugins#configure-auto-updates)

719* 在啟動或 `/reload-plugins` 上，當啟用的 plugin 的已安裝版本從 plugin 快取中遺失時

~~720~~

721當使用者設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 時，Claude Code 跳過兩個背景執行。明確安裝和更新仍會使用該變數集執行命令。

~~722~~

723當命令的雜湊輸出已變更時，Claude Code 將結果安裝為新版本，並在執行中的互動式工作階段中重新載入它，切換 [`/reload-plugins` 切換的相同元件](/docs/zh-TW/plugins-reference#environment-variables)。使用者看到 plugin 已重新載入的通知。如果就地重新載入會使工作階段的提示快取失效，Claude Code 改為提示使用者執行 `/reload-plugins`，[警告快取成本並在使用 `--force` 重新執行時應用](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)。

~~724~~

725<h3 id="advanced-plugin-entries">

726 進階 plugin 項目

727</h3>

~~728~~

729此範例顯示使用許多選用欄位的 plugin 項目，包括 commands、agents、hooks 和 MCP servers 的自訂路徑：

~~730~~

731```json theme={null}

732{

733 "name": "enterprise-tools",

734 "source": {

735 "source": "github",

736 "repo": "company/enterprise-plugin"

737 },

738 "description": "企業工作流程自動化工具",

739 "version": "2.1.0",

740 "author": {

741 "name": "Enterprise Team",

742 "email": "enterprise@example.com"

743 },

744 "homepage": "https://docs.example.com/plugins/enterprise-tools",

745 "repository": "https://github.com/company/enterprise-plugin",

746 "license": "MIT",

747 "keywords": ["enterprise", "workflow", "automation"],

748 "category": "productivity",

749 "commands": [

750 "./commands/core/",

751 "./commands/enterprise/",

752 "./commands/experimental/preview.md"

753 ],

754 "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],

755 "hooks": {

756 "PostToolUse": [

757 {

758 "matcher": "Write|Edit",

759 "hooks": [

760 {

761 "type": "command",

762 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"

763 }

764 ]

765 }

766 ]

767 },

768 "mcpServers": {

769 "enterprise-db": {

770 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",

771 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]

772 }

773 },

774 "strict": false

775}

776```

~~777~~

778需要注意的關鍵事項：

~~779~~

780* **`commands` 和 `agents`**：您可以指定多個目錄或個別檔案。路徑相對於 plugin 根目錄，必須保持在其內部。

781 * Claude Code 拒絕解析在 plugin 目錄外的路徑，例如 `./../shared.md`，並顯示 [`path escapes plugin directory`](/docs/zh-TW/errors#path-escapes-plugin-directory) 錯誤，仍會載入 plugin 而不包含該元件

782* **`${CLAUDE_PLUGIN_ROOT}`**：在 hook 命令和 MCP 伺服器配置中使用此變數來參考 plugin 安裝目錄內的檔案。

783 * 請參閱[替換表](/docs/zh-TW/plugins-reference#environment-variables)以了解每個伺服器類型的哪些配置欄位會替換它

784 * 對於應在 plugin 更新後保留的相依性或狀態，請改用 [`${CLAUDE_PLUGIN_DATA}`](/docs/zh-TW/plugins-reference#persistent-data-directory)

785* **`strict: false`**：由於此設定為 false，plugin 不需要自己的 `plugin.json`。marketplace 項目定義所有內容。請參閱下面的 [Strict mode](#strict-mode)。

~~786~~

787根據預設，plugin 的 skills 從其 `source` 下的 `skills/` 目錄載入。`skills` 欄位中列出的路徑會新增到該掃描中：

~~788~~

789```json theme={null}

790"skills": ["./skills/", "./extra-skills/"]

791```

~~792~~

793當多個 plugin 項目在 marketplace 根目錄（`source: "./"`) 共享一個 `skills/` 資料夾時，改為列出特定子目錄，以便每個項目只載入自己的 skills：

~~794~~

795```json theme={null}

796"source": "./",

797"skills": ["./skills/code-review", "./skills/docs"]

798```

~~799~~

800使用 marketplace 根目錄 `source` 時，列出的路徑是該項目的完整集合，共享 `skills/` 資料夾中的其他目錄不會載入。列出 `./skills/` 本身或 plugin 根目錄會保持完整掃描。如果列出的路徑都不存在，則改為執行預設掃描。

~~801~~

802<h3 id="strict-mode">

803 Strict mode

804</h3>

~~805~~

806`strict` 欄位控制 `plugin.json` 是否為元件定義（skills、agents、hooks、MCP servers、輸出樣式）的權威。

~~807~~

808| 值 | 行為 |

809| :--------- | :--------------------------------------------------------------------- |

810| `true`（預設） | `plugin.json` 是權威。marketplace 項目可以用額外的元件補充它，兩個來源都會合併。 |

811| `false` | marketplace 項目是完整定義。如果 plugin 也有宣告元件的 `plugin.json`，那就是衝突，plugin 無法載入。 |

~~812~~

813**何時使用每種模式：**

~~814~~

815* **`strict: true`**：plugin 有自己的 `plugin.json` 並管理自己的元件。marketplace 項目可以在頂部新增額外的 skills 或 hooks。這是預設值，適用於大多數 plugin。

816* **`strict: false`**：marketplace 運營商想要完全控制。plugin 儲存庫提供原始檔案，marketplace 項目定義這些檔案中的哪些被公開為 skills、agents、hooks 等。當 marketplace 以不同於 plugin 作者預期的方式重組或策劃 plugin 的元件時很有用。

~~817~~

818<h2 id="host-and-distribute-marketplaces">

819 託管並分發 marketplace

820</h2>

~~821~~

822當使用者新增託管在 git 儲存庫中的 marketplace，或安裝其列出的 git 型 plugin 時，Claude Code 會將該 marketplace 或 plugin 儲存庫複製到他們的機器上。複製永遠不會下載 [Git LFS](https://git-lfs.com) 內容，因此 LFS 追蹤的檔案會以指標檔案的形式到達。將您的 plugin 需要的檔案保留在 LFS 之外。

~~823~~

824<h3 id="host-on-github-recommended">

825 在 GitHub 上託管（推薦）

826</h3>

~~827~~

828GitHub 是託管和分發 marketplace 的推薦方式：

~~829~~

8301. **建立儲存庫**：為您的 marketplace 設定新儲存庫

8312. **新增 marketplace 檔案**：使用您的 plugin 定義建立 `.claude-plugin/marketplace.json`

8323. **與團隊分享**：使用者使用 `/plugin marketplace add owner/repo` 新增您的 marketplace

~~833~~

834**優點**：內建版本控制、問題追蹤和團隊協作功能。

~~835~~

836<h3 id="host-on-other-git-services">

837 在其他 git 服務上託管

838</h3>

~~839~~

840任何 git 託管服務都可以使用，例如 GitLab、Bitbucket 和自託管伺服器。使用者使用完整儲存庫 URL 新增：

~~841~~

842```shell theme={null}

843/plugin marketplace add https://gitlab.com/company/plugins.git

844```

~~845~~

846<h3 id="private-repositories">

847 私人儲存庫

848</h3>

~~849~~

850Claude Code 支援從私人儲存庫安裝 plugin。如果您改為透過[**組織設定 > Plugins**](https://claude.ai/admin-settings/plugins)分發您的 marketplace，您的 git 認證不涉及其中：組織同步透過您組織在 claude.ai 上的 GitHub 或 GitLab 連線讀取 marketplace 儲存庫。請參閱[透過組織設定分發](#distribute-through-organization-settings)以了解哪些 plugin 來源可以是私人的。

~~851~~

852<h4 id="commands-you-run">

853 您執行的命令

854</h4>

~~855~~

856當您執行 `/plugin marketplace add`、`/plugin install`、`/plugin update` 或 `/plugin marketplace update` 時，Claude Code 使用您現有的 git 認證助手，因此 HTTPS 存取透過 `gh auth login`、macOS Keychain 或 `git-credential-store` 的方式與在您的終端中相同。只要主機已在您的 `known_hosts` 檔案中且金鑰已載入 `ssh-agent`，SSH 存取就可以運作，因為 Claude Code 會抑制主機指紋和金鑰密碼的互動式 SSH 提示。GitHub `owner/repo` 簡寫來源預設透過 SSH 複製；設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars#variables) 以改為透過 HTTPS 複製它們。

~~857~~

858<h4 id="background-auto-updates">

859 背景自動更新

860</h4>

~~861~~

862背景重新整理會檢查 marketplace 的遠端以尋找新提交，使用您配置的 git 認證助手，與您執行的命令相同。對於 SSH 遠端，載入在 `ssh-agent` 中的金鑰會驗證檢查。Claude Code 以非互動方式執行檢查：它關閉 git 的終端提示和 askpass 程式，並告訴認證助手不要提示。檢查是否可以透過 HTTPS 驗證私人儲存庫取決於您的助手：

~~863~~

864* 可以在不提示的情況下提供儲存認證的助手會驗證檢查。Git Credential Manager、macOS Keychain 助手和 `git-credential-store` 在持有主機的認證後以這種方式運作。

865* 需要提示您的助手無法在背景中回答。更新會無聲地失敗，現有簽出會保留在原位，因此您的 plugin 會從最後同步的狀態繼續運作。執行 `/plugin marketplace update <name>` 以使用您的認證重新整理 marketplace。

~~866~~

867當檢查發現簽出是最新的時，Claude Code 會保持原樣。當檢查發現新提交，或因為無法到達或驗證遠端而失敗時，Claude Code 會重新複製 marketplace 並交換新複製。如果該複製失敗，現有簽出會保留在原位。重新複製可能會在大型儲存庫上[逾時](#git-operations-time-out)。

~~868~~

869兩個設定使私人 marketplace 的行為可預測：

~~870~~

871* 設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在背景檢查無法到達或驗證遠端時保留現有簽出，而不嘗試重新複製。您的 plugin 會從最後同步的狀態繼續運作，使用 `/plugin marketplace update` 的手動更新仍會使用您的認證進行驗證。

872* 配置 git 認證助手，例如使用 `gh auth setup-git` 針對 GitHub，以便背景檢查和重新複製可以在不提示的情況下進行驗證。

~~873~~

874在您的環境中設定提供者令牌（例如 `GITHUB_TOKEN`）本身不會啟用背景驗證。令牌只有透過已配置的認證助手（例如 `gh` CLI 的助手，它讀取 `GH_TOKEN` 和 `GITHUB_TOKEN`）才會生效。

~~875~~

876<Note>

877 在 CI/CD 環境中，在從私人儲存庫安裝 plugin 之前配置 git 認證助手。在 GitHub Actions 上，匯出具有對 marketplace 儲存庫的讀取存取權的令牌作為 `GH_TOKEN`，然後執行 `gh auth setup-git`。預設工作流程令牌只能存取工作流程自己的儲存庫，因此另一個儲存庫中的私人 marketplace 需要個人存取令牌或應用程式令牌。

878</Note>

~~879~~

880<h3 id="distribute-through-organization-settings">

881 透過組織設定分發

882</h3>

~~883~~

884如果您在 Team 或 Enterprise 方案上透過[**組織設定 > Plugins**](https://claude.ai/admin-settings/plugins)分發 plugin，這些來源規則適用：

~~885~~

886* 在 github.com 和 gitlab.com 上，marketplace 儲存庫必須是私人或內部的。組織同步透過符合其主機的連線讀取儲存庫：

887 * **github.com**：Claude GitHub App

888 * **您的 GitHub Enterprise Server 主機**：您組織的 [GitHub Enterprise App](/docs/zh-TW/github-enterprise-server#admin-setup)

889 * **gitlab.com 或您的自託管 GitLab 執行個體**：您組織的[GitLab 配置](#sync-a-gitlab-hosted-marketplace)中該主機的存取令牌

890* 每個 plugin 來源必須是 `github`、`url` 或 `git-subdir` 類型，或以 `./` 開頭的[相對路徑](#relative-paths)。如果您在 `metadata.pluginRoot` 下按裸名稱列出 plugin，組織同步會拒絕它作為不支援的來源，因此請寫出路徑，例如 `./plugins/deploy-tools`。

891* Plugin 來源可以在三種情況下是私人的：

892 * 共享 marketplace 儲存庫擁有者的 github.com 來源

893 * 您組織的 GitHub Enterprise 主機上已安裝 GHE App 的來源

894 * 與 marketplace 儲存庫位於同一 GitLab 主機上的 `url` 或 `git-subdir` 來源。在 gitlab.com 上，來源也必須位於與 marketplace 儲存庫相同的頂層群組或使用者命名空間下。

895* 任何其他 plugin 來源必須是 github.com、gitlab.com 或 bitbucket.org 上的公開儲存庫，組織同步在沒有認證的情況下取得。組織同步拒絕這些規則不涵蓋的主機上的 plugin 來源。

~~896~~

897請參閱[為您的組織管理 plugin](https://support.claude.com/en/articles/13837433)以了解管理員工作流程。

~~898~~

899若要包含私人 plugin，請將 plugin 資料夾放在 marketplace 儲存庫內，並使用[相對路徑](#relative-paths)參考它們。組織同步在分發期間打包每個 plugin，因此使用者永遠不需要存取單獨的來源儲存庫。

~~900~~

901例如，此 `marketplace.json` plugin 項目參考您在 marketplace 儲存庫中的 `plugins/deploy-tools` 提交的 plugin：

~~902~~

903```json theme={null}

904{

905 "name": "deploy-tools",

906 "source": "./plugins/deploy-tools"

907}

908```

~~909~~

910<h4 id="sync-a-gitlab-hosted-marketplace">

911 同步 GitLab 託管的 marketplace

912</h4>

~~913~~

914若要從 gitlab.com 或自託管 GitLab 執行個體同步 marketplace，[擁有者](/docs/zh-TW/server-managed-settings#access-control)首先在[**組織設定 > Claude Code**](https://claude.ai/admin-settings/claude-code)為該主機新增 GitLab 配置。GitLab 配置處於公開測試版，僅適用於 plugin marketplace 同步。新增一個不會使 GitLab 儲存庫在[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web#limitations) 中可用。請參閱[為您的組織管理 plugin](https://support.claude.com/en/articles/13837433)以了解設定步驟。

~~915~~

916當您新增 marketplace 時，輸入專案的 HTTPS URL，例如 `https://gitlab.example.com/platform/claude-plugins`。嵌套子群組中的專案可以運作。組織同步讀取專案的預設分支。如果您開啟**自動同步**，只有推送到預設分支才會啟動同步。

~~917~~

918<h4 id="keep-executables-out-of-the-top-level-bin-directory">

919 將可執行檔保留在頂層 bin 目錄之外

920</h4>

~~921~~

922不要在您透過組織設定分發的任何 plugin 中包含頂層 `bin/` 目錄。claude.ai 會拒絕具有該目錄的 plugin，無論 plugin 是透過 marketplace 同步還是直接上傳到達：

~~923~~

924* **Marketplace 同步**：組織同步拒絕該 plugin 並同步 marketplace 的其餘部分。錯誤訊息以 `Plugin contains a top-level bin/ directory` 開頭。

925* **直接上傳**：如果您改為在[**組織設定 > Plugins**](https://claude.ai/admin-settings/plugins)中上傳 plugin，claude.ai 會以相同訊息拒絕上傳。

~~926~~

927將可執行檔保留在另一個目錄中，例如 `scripts/`，並從您的[skills、hooks 或 MCP 伺服器配置](/docs/zh-TW/plugins-reference#environment-variables)中將它們參考為 `${CLAUDE_PLUGIN_ROOT}/scripts/<name>`。

~~928~~

929<h3 id="require-marketplaces-for-your-team">

930 為您的團隊要求 marketplace

931</h3>

~~932~~

933您可以配置您的儲存庫，以便當團隊成員[信任專案資料夾](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)時，Claude Code 會為他們新增您的 marketplace，無需單獨提示。將您的 marketplace 新增到 `.claude/settings.json`：

~~934~~

935```json theme={null}

936{

937 "extraKnownMarketplaces": {

938 "company-tools": {

939 "source": {

940 "source": "github",

941 "repo": "your-org/claude-plugins"

942 }

943 }

944 }

945}

946```

~~947~~

948您也可以指定預設應啟用哪些 plugin：

~~949~~

950```json theme={null}

951{

952 "enabledPlugins": {

953 "code-formatter@company-tools": true,

954 "deployment-tools@company-tools": true

955 }

956}

957```

~~958~~

959有關完整的配置選項，請參閱 [Plugin settings](/docs/zh-TW/settings-reference#plugin-settings)。

~~960~~

961<Note>

962 如果您使用具有相對路徑的本機 `directory` 或 `file` 來源，路徑會針對您的儲存庫的主要簽出進行解析。當您從 git worktree 執行 Claude Code 時，路徑仍然指向主要簽出，因此所有 worktrees 共享相同的 marketplace 位置。Marketplace 狀態每個使用者儲存一次在 `~/.claude/plugins/known_marketplaces.json` 中，而不是每個專案。

963</Note>

~~964~~

965<h3 id="pre-populate-plugins-for-containers">

966 為容器預先填充 plugin

967</h3>

~~968~~

969對於容器映像和 CI 環境，您可以在建置時預先填充 plugin 目錄，以便 Claude Code 啟動時已有 marketplace 和 plugin 可用，無需在執行時複製任何內容。設定 `CLAUDE_CODE_PLUGIN_SEED_DIR` 環境變數以指向此目錄。

~~970~~

971若要分層多個種子目錄，請在 Unix 上使用 `:` 或在 Windows 上使用 `;` 分隔路徑。Claude Code 按順序搜尋每個目錄，第一個包含給定 marketplace 或 plugin 快取的種子獲勝。

~~972~~

973種子目錄鏡像 `~/.claude/plugins` 的結構：

~~974~~

975```

976$CLAUDE_CODE_PLUGIN_SEED_DIR/

977 known_marketplaces.json

978 marketplaces/<name>/...

979 cache/<marketplace>/<plugin>/<version>/...

980```

~~981~~

982建立種子目錄的最簡單方法是在映像建置期間執行 Claude Code 一次，安裝您需要的 plugin，然後將產生的 `~/.claude/plugins` 目錄複製到您的映像中，並將 `CLAUDE_CODE_PLUGIN_SEED_DIR` 指向它。

~~983~~

984若要跳過複製步驟，在建置期間將 `CLAUDE_CODE_PLUGIN_CACHE_DIR` 設定為您的目標種子路徑，以便 plugin 直接安裝到那裡：

~~985~~

986```bash theme={null}

987CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins

988CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

989```

~~990~~

991然後在您的容器的執行時環境中設定 `CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed`，以便 Claude Code 在啟動時從種子讀取。

~~992~~

993在啟動時，Claude Code 將種子的 `known_marketplaces.json` 中找到的 marketplace 註冊到主要配置中，並使用在 `cache/` 下找到的 plugin 快取，而無需重新複製。這在互動模式和使用 `-p` 旗標的非互動模式中都有效。

~~994~~

995行為詳細資訊：

~~996~~

997* **唯讀**：Claude Code 永遠不會寫入種子目錄。

998* **自動更新已停用**：種子 marketplace 不會自動更新。

999* **種子項目優先**：種子中宣告的 marketplace 在每次啟動時覆蓋使用者配置中的任何相符項目。若要選擇退出種子 plugin，請使用 `/plugin disable` 而不是移除 marketplace。

1000* **路徑解析**：Claude Code 在執行時透過探測 `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` 來定位 marketplace 內容，而不是信任儲存在種子 JSON 內的路徑。這表示即使在與建置位置不同的路徑上掛載，種子也能正確運作。

1001* **變更被阻止**：針對種子管理的 marketplace 執行 `/plugin marketplace remove` 或 `/plugin marketplace update` 會失敗，並提示您要求管理員更新種子映像。

1002* **與設定組合**：如果 `extraKnownMarketplaces` 或 `enabledPlugins` 宣告已存在於種子中的 marketplace，Claude Code 使用種子副本而不是複製。

~~1003~~

1004<h3 id="managed-marketplace-restrictions">

1005 受管 marketplace 限制

1006</h3>

~~1007~~

1008對於需要對 plugin 來源進行嚴格控制的組織，管理員可以使用受管設定中的 [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) 設定限制使用者允許新增的 plugin marketplace。若要也拒絕為單次執行側載 plugin、agent 和 MCP 伺服器的 CLI 旗標，請將其與 [`disableSideloadFlags`](/docs/zh-TW/settings-reference#disablesideloadflags) 配對。若要允許清單化哪些 marketplace 的 plugin 可以顯示為內容相關安裝建議，請設定 [`pluginSuggestionMarketplaces`](/docs/zh-TW/settings-reference#pluginsuggestionmarketplaces)。

~~1009~~

1010`strictKnownMarketplaces` 符合 plugin 來自的 marketplace，而不是其內的項目，因此使用者仍然可以從允許的 marketplace 安裝具有[`command` 來源](#command-sources)的 plugin。若要也阻止 command 來源，請設定 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources)。

~~1011~~

1012當在受管設定中配置 `strictKnownMarketplaces` 時，限制行為取決於值：

~~1013~~

1014| 值 | 行為 |

1015| -------- | --------------------------------------------------- |

1016| 未定義（預設） | 無限制。使用者可以新增任何 marketplace |

1017| 空陣列 `[]` | 完全鎖定。阻止每個 marketplace 來源，包括官方 Anthropic marketplace |

1018| 來源清單 | 允許清單強制執行。使用者只能新增符合項目的 marketplace |

~~1019~~

1020<h4 id="common-configurations">

1021 常見配置

1022</h4>

~~1023~~

1024停用所有 marketplace 新增，包括官方 Anthropic marketplace：

~~1025~~

1026```json theme={null}

1027{

1028 "strictKnownMarketplaces": []

1029}

1030```

~~1031~~

1032Claude Code 下載[從 claude.ai 同步的](/docs/zh-TW/plugins-reference#synced-plugins) plugin，而不是從 marketplace 下載，因此此鎖定不涵蓋它們。若要也停止這些，請在受管設定中將 [`syncClaudeAiPlugins`](/docs/zh-TW/settings-reference#syncclaudeaiplugins) 設定為 `false`，或在 claude.ai 上為您的組織關閉 Skills。

~~1033~~

1034僅允許官方 Anthropic marketplace。單一儲存庫項目的匹配是精確的，因此此項目不涵蓋同一儲存庫的 `ref` 或 `path` 變體：

~~1035~~

1036```json theme={null}

1037{

1038 "strictKnownMarketplaces": [

1039 {

1040 "source": "github",

1041 "repo": "anthropics/claude-plugins-official"

1042 }

1043 ]

1044}

1045```

~~1046~~

1047使用此項目，Claude Code 保持已註冊的官方 marketplace 可用，並在新機器上，在您第一次以互動方式啟動 Claude Code 時自動註冊 marketplace。

~~1048~~

1049自動註冊不涵蓋每台機器。它最常遺漏：

~~1050~~

1051* 在機器首次互動啟動之前執行的非互動環境。

1052* Claude Code 已在阻止 marketplace 的原則下以互動方式執行的機器，例如空陣列鎖定。Claude Code 記錄被阻止的嘗試，並在原則變更後不重試。

~~1053~~

1054在這些機器上，將 marketplace 新增到同一 `managed-settings.json` 中的 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces)，以便 Claude Code 自動註冊它，或執行 `claude plugin marketplace add anthropics/claude-plugins-official`。

~~1055~~

1056僅允許特定 marketplace：

~~1057~~

1058```json theme={null}

1059{

1060 "strictKnownMarketplaces": [

1061 {

1062 "source": "github",

1063 "repo": "acme-corp/approved-plugins"

1064 },

1065 {

1066 "source": "github",

1067 "repo": "acme-corp/security-tools",

1068 "ref": "v2.0"

1069 },

1070 {

1071 "source": "url",

1072 "url": "https://plugins.example.com/marketplace.json"

1073 }

1074 ]

1075}

1076```

~~1077~~

1078使用[擁有者萬用字元](/docs/zh-TW/settings-reference#owner-wildcards)項目允許 GitHub 組織下的每個 marketplace 儲存庫。擁有者萬用字元需要 Claude Code v2.1.223 或更新版本。

~~1079~~

1080```json theme={null}

1081{

1082 "strictKnownMarketplaces": [

1083 {

1084 "source": "github",

1085 "repo": "acme-corp/*"

1086 }

1087 ]

1088}

1089```

~~1090~~

1091使用主機上的正規表達式模式匹配允許來自內部 git 伺服器的所有 marketplace。這是 [GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server#plugin-marketplaces-on-ghes) 或自託管 GitLab 執行個體的推薦方法：

~~1092~~

1093```json theme={null}

1094{

1095 "strictKnownMarketplaces": [

1096 {

1097 "source": "hostPattern",

1098 "hostPattern": "^github\\.example\\.com$"

1099 }

1100 ]

1101}

1102```

~~1103~~

1104使用路徑上的正規表達式模式匹配允許來自特定目錄的檔案系統型 marketplace：

~~1105~~

1106```json theme={null}

1107{

1108 "strictKnownMarketplaces": [

1109 {

1110 "source": "pathPattern",

1111 "pathPattern": "^/opt/approved/"

1112 }

1113 ]

1114}

1115```

~~1116~~

1117使用 `".*"` 作為 `pathPattern` 以允許任何檔案系統路徑，同時仍使用 `hostPattern` 控制網路來源。

~~1118~~

1119<Note>

1120 `strictKnownMarketplaces` 限制使用者可以新增的內容，但不會自行註冊 marketplace。若要為使用者自動註冊允許的 marketplace，請將其新增到同一 `managed-settings.json` 中的 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces)。

~~1121~~

1122 官方 Anthropic marketplace 是唯一 Claude Code 自行註冊的，且僅當允許清單允許時。自動註冊也遺漏某些機器，例如非互動環境和早期原則阻止它的機器。若要涵蓋這些機器，也將官方 marketplace 新增到 `extraKnownMarketplaces`。有關兩個設定並排，請參閱 [`strictKnownMarketplaces` 參考](/docs/zh-TW/settings-reference#strictknownmarketplaces)。

1123</Note>

~~1124~~

1125<h4 id="how-restrictions-work">

1126 限制如何運作

1127</h4>

~~1128~~

1129限制在任何網路或檔案系統操作之前進行檢查。檢查在 marketplace 新增以及 plugin 安裝、更新、重新整理和自動更新時執行。如果 marketplace 在配置原則之前被新增，且其來源不再符合允許清單，Claude Code 會拒絕從中安裝或更新 plugin。相同的強制執行也適用於 `blockedMarketplaces`。

~~1130~~

1131其中兩個清單被強制執行取決於您在何處設定它們：

~~1132~~

1133* **claude.ai 管理員主控台**：Claude Code 在[讀取伺服器管理設定](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)的工作階段中強制執行兩個清單。claude.ai 也會在您組織中的任何人從 git 儲存庫在 claude.ai 上新增新 marketplace，或從 Claude Desktop 應用程式外其 Code 標籤中的**自訂**新增時檢查它們。這涵蓋成員為自己的帳戶新增的 marketplace 和在[**組織設定 > Plugins**](https://claude.ai/admin-settings/plugins)下為整個組織新增的 marketplace。claude.ai 拒絕允許清單不允許的儲存庫或封鎖清單命名的儲存庫。它不會重新檢查在您設定清單之前在任一位置新增的 marketplace，也不會檢查上傳的 plugin。

1134* **受管設定檔案、OS 層級原則或其他受管來源**：Claude Code 在讀取該來源的地方強制執行兩個清單。claude.ai 不讀取它。

~~1135~~

1136若要阻止 GitHub 擁有者下的每個 marketplace 儲存庫，請在 `blockedMarketplaces` 項目中使用擁有者萬用字元形式：`{ "source": "github", "repo": "untrusted-org/*" }`。需要 Claude Code v2.1.223 或更新版本。有關匹配規則（在封鎖清單和允許清單之間不同），請參閱[擁有者萬用字元](/docs/zh-TW/settings-reference#owner-wildcards)。

~~1137~~

1138當使用者新增 Claude Code [複製而不是取得](/docs/zh-TW/discover-plugins#add-from-other-git-hosts)的 `https://` 儲存庫 URL（例如裸 `github.com` 或 `gitlab.com` 儲存庫 URL）時，Claude Code 也會根據 `blockedMarketplaces` 中的 `url` 項目檢查它。如果項目命名相同的 URL，Claude Code 會阻止新增。在該比較中，Claude Code 忽略 `.git` 後綴和使用者在 `#` 後附加的任何 ref。需要 Claude Code v2.1.232 或更新版本。在 v2.1.232 之前，Claude Code 僅針對它作為託管 `marketplace.json` 檔案取得的 URL 符合 `url` 項目。

~~1139~~

1140允許清單對大多數來源類型使用精確匹配，除了擁有者萬用字元 `github` 項目。若要允許 marketplace，所有指定的欄位必須相符：

~~1141~~

1142* 對於 GitHub 來源：`repo` 是必需的，要麼命名一個儲存庫，要麼使用擁有者萬用字元形式 `owner/*` 涵蓋該擁有者下的每個儲存庫。有關萬用字元項目如何匹配（包括大小寫規則），請參閱[擁有者萬用字元](/docs/zh-TW/settings-reference#owner-wildcards)。對於單一儲存庫項目，`ref` 必須精確相符或在 marketplace 來源和允許清單項目中都不存在，相同的規則適用於 `path`

1143* 對於 URL 來源：完整 URL 必須完全相符

1144* 對於 `hostPattern` 來源：marketplace 主機與正規表達式模式相符

1145* 對於 `pathPattern` 來源：marketplace 的檔案系統路徑與正規表達式模式相符

~~1146~~

1147允許清單的精確匹配將僅因尾部斜線、`.git` 後綴或 `ssh://` 和 `https://` 方案而異的 URL 視為不同的值。如果您的組織 marketplace 可以透過多個 URL 形式複製，請優先使用 `hostPattern` 項目而不是字面 URL，以便 `https://`、`ssh://` 和 `user@host:path` 形式都相符。

~~1148~~

1149[託管在 claude.ai 上的 marketplace](/docs/zh-TW/discover-plugins#add-from-claude-ai) 按主機相符：符合 `claude.ai` 的 `hostPattern` 項目在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中管理它。在允許清單上，此類項目不允許成員的個人 claude.ai 上傳。需要 Claude Code v2.1.273 或更新版本。

~~1150~~

1151因為 `strictKnownMarketplaces` 在[受管設定](/docs/zh-TW/managed-settings)中設定，個別使用者和專案配置無法覆蓋這些限制。

~~1152~~

1153有關完整的配置詳細資訊，包括所有支援的來源類型和與 `extraKnownMarketplaces` 的比較，請參閱 [strictKnownMarketplaces 參考](/docs/zh-TW/settings-reference#strictknownmarketplaces)。

~~1154~~

1155<h3 id="version-resolution-and-release-channels">

1156 版本解析和發行通道

1157</h3>

~~1158~~

1159Plugin 版本決定快取路徑和更新偵測：如果解析的版本與使用者已有的版本相符，`/plugin update` 和自動更新會跳過 plugin。對於 git 型來源，如果您省略 `version`，Claude Code 使用來源的解析提交 SHA，因此使用者在該提交變更時獲得更新；這是內部或積極開發的 plugin 的最簡單設定。請參閱[版本管理](/docs/zh-TW/plugins-reference#version-management)以了解完整的解析順序，包括 `archive` 來源。

~~1160~~

1161<Warning>

1162 設定 `version` 會固定 plugin，除了 [`command`](#command-sources)（其版本始終包含命令產生內容的雜湊）的每個來源類型。[在原位載入的 plugin](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)來自作為本機目錄新增的 marketplace 也不會被固定。如果您在 `plugin.json` 中宣告 `"version": "1.0.0"` 並推送新提交而不更改該字串，這些來源的現有使用者保留快取副本，因為 Claude Code 看到相同的版本。在每次發行時提升該欄位，或省略它以回退到解析的版本。

~~1163~~

1164 避免在 `plugin.json` 和 marketplace 項目中同時設定 `version`。Claude Code 總是無聲地使用 `plugin.json` 值，因此過時的 manifest 版本可能會掩蓋您在 `marketplace.json` 中設定的版本。

1165</Warning>

~~1166~~

1167<h4 id="set-up-release-channels">

1168 設定發行通道

1169</h4>

~~1170~~

1171若要為您的 plugin 支援「穩定」和「最新」發行通道，您可以設定兩個指向同一儲存庫的不同 ref 或 SHA 的 marketplace。然後，您可以透過以下兩種方式之一透過受管設定將每個使用者群組指派給其自己的 marketplace：

~~1172~~

1173* 將單獨的[端點管理設定](/docs/zh-TW/managed-settings#delivery-mechanisms)（例如受管設定檔案或 MDM 設定檔）部署到每個群組的裝置。[Claude Code 如何組合受管來源](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)說明每個群組檔案或設定檔是否適用於也具有組織範圍來源的裝置。

1174* 為每個群組定義一個 [Claude apps gateway 原則](/docs/zh-TW/claude-apps-gateway-config#managed)。gateway 適用第一個符合使用者的原則，因此排序原則以便每個使用者到達其群組的原則。群組原則的 `extraKnownMarketplaces` 替換全面原則的對應，而不是與其合併，因此在群組的原則中列出群組需要的每個 marketplace，而不僅僅是其通道 marketplace。

~~1175~~

1176來自管理員主控台的伺服器管理設定[適用於您組織中的每個使用者](/docs/zh-TW/server-managed-settings#current-limitations)，因此無法進行每個群組的指派。

~~1177~~

1178<Warning>

1179 每個通道必須解析為不同的版本。如果您使用明確版本，`plugin.json` 必須在每個固定的 ref 處宣告不同的 `version`。如果您省略 `version`，不同的提交 SHA 已經區分通道。如果兩個 ref 解析為相同的版本字串，Claude Code 會將它們視為相同並跳過更新。

1180</Warning>

~~1181~~

1182<h5 id="example">

1183 範例

1184</h5>

~~1185~~

1186```json theme={null}

1187{

1188 "name": "stable-tools",

1189 "plugins": [

1190 {

1191 "name": "code-formatter",

1192 "source": {

1193 "source": "github",

1194 "repo": "acme-corp/code-formatter",

1195 "ref": "stable"

1196 }

1197 }

1198 ]

1199}

1200```

~~1201~~

1202```json theme={null}

1203{

1204 "name": "latest-tools",

1205 "plugins": [

1206 {

1207 "name": "code-formatter",

1208 "source": {

1209 "source": "github",

1210 "repo": "acme-corp/code-formatter",

1211 "ref": "latest"

1212 }

1213 }

1214 ]

1215}

1216```

~~1217~~

1218<h5 id="assign-channels-to-user-groups">

1219 將通道指派給使用者群組

1220</h5>

~~1221~~

1222透過上述[設定發行通道](#set-up-release-channels)下描述的每個群組端點管理設定或 gateway 原則將每個 marketplace 指派給其使用者群組。例如，穩定群組接收：

~~1223~~

1224```json theme={null}

1225{

1226 "extraKnownMarketplaces": {

1227 "stable-tools": {

1228 "source": {

1229 "source": "github",

1230 "repo": "acme-corp/stable-tools"

1231 }

1232 }

1233 }

1234}

1235```

~~1236~~

1237早期存取群組改為接收 `latest-tools`：

~~1238~~

1239```json theme={null}

1240{

1241 "extraKnownMarketplaces": {

1242 "latest-tools": {

1243 "source": {

1244 "source": "github",

1245 "repo": "acme-corp/latest-tools"

1246 }

1247 }

1248 }

1249}

1250```

~~1251~~

1252<h4 id="pin-dependency-versions">

1253 固定依賴版本

1254</h4>

~~1255~~

1256Plugin 可以將其依賴限制在 semver 範圍內，以便依賴的更新不會破壞依賴 plugin。請參閱[限制 plugin 依賴版本](/docs/zh-TW/plugin-dependencies)以了解 `{plugin-name}--v{version}` git 標籤慣例、範圍語法，以及如何組合對同一依賴的多個限制。

~~1257~~

1258<h3 id="rename-or-remove-a-plugin">

1259 重新命名或移除 plugin

1260</h3>

~~1261~~

1262Plugin 的 `name` 是其穩定識別碼。使用者在 `enabledPlugins`、`pluginConfigs` 和 `/plugin install` 命令中參考它，因此更改它會破壞每個現有安裝。若要更改 UI 中顯示的標籤而不破壞安裝，請設定 [`displayName`](#optional-plugin-fields) 並保持 `name` 不變。

~~1263~~

1264如果您必須更改 plugin 的 `name`，或您從 `plugins` 陣列中移除 plugin，請新增頂層 `renames` 項目，以便現有使用者遷移而不是看到 `plugin-not-found` 錯誤。自動遷移需要 Claude Code v2.1.193 或更新版本。將每個前名稱對應到其目前名稱，或如果 plugin 不再存在，則對應到 `null`。以下範例將 `formatter` 重新命名為 `code-formatter`，並記錄 `legacy-linter` 已被移除：

~~1265~~

1266```json theme={null}

1267{

1268 "name": "acme-tools",

1269 "owner": { "name": "Acme" },

1270 "plugins": [

1271 { "name": "code-formatter", "source": "./plugins/code-formatter" }

1272 ],

1273 "renames": {

1274 "formatter": "code-formatter",

1275 "legacy-linter": null

1276 }

1277}

1278```

~~1279~~

1280當使用者啟動 Claude Code 時舊名稱仍在其設定中，Claude Code 會遵循 `renames` 對應：

~~1281~~

1282* 如果項目指向新名稱，Claude Code 會在其新名稱下載入 plugin，並顯示一行通知，例如 `已在 "acme-tools" marketplace 中重新命名為 "code-formatter"`。然後它會在使用者、專案和本機設定範圍中重寫舊金鑰為新金鑰，用於 `enabledPlugins` 和 `pluginConfigs`，因此通知只出現一次。

1283* 對於 `null` 項目，Claude Code 會刪除舊金鑰，通知報告 plugin 已從 marketplace 中移除。

1284* 如果重新命名的 plugin 使用遠端來源，例如 `github` 或 `npm`，Claude Code 在重新命名後報告 `plugin-cache-miss`，使用者必須執行 `/plugin install` 一次以在新名稱下取得它。

~~1285~~

1286將 `renames` 視為僅附加歷史記錄：即使在您預期每個使用者都已遷移後，也要保持舊項目就位。Claude Code 遵循鏈，因此如果您稍後將 `code-formatter` 重新命名為 `formatter-pro`，請新增第二項而不是編輯第一項。仍然啟用原始 `formatter` 的使用者然後透過兩項解析到 `formatter-pro`。

~~1287~~

1288在編輯對應後執行 `claude plugin validate .`；它會拒絕任何鏈形成循環或不終止於 `null` 或 `plugins` 中列出的名稱的項目。

~~1289~~

1290<Note>

1291 受管和原則設定對 Claude Code 是唯讀的，因此在那裡啟用的 plugin 無法自動重寫。重新命名的 plugin 仍在每個工作階段載入，但重新命名通知會重複出現，直到管理員更新受管設定檔案中的 `enabledPlugins` 以使用新名稱。相同的情況也適用於透過其他唯讀來源（例如 `--add-dir`）啟用的 plugin。

1292</Note>

~~1293~~

1294Claude Code 的早期版本會忽略 `renames` 欄位，並為舊名稱報告 `plugin-not-found`。

~~1295~~

1296<h2 id="validation-and-testing">

1297 驗證和測試

1298</h2>

~~1299~~

1300在分享前測試您的 marketplace。驗證會檢查檔案結構；若要測試 plugin 是否會改變 Claude 在實際提示上的行為，請在發佈新版本前使用 [`claude plugin eval`](/docs/zh-TW/plugin-evals) 執行其評估套件。

~~1301~~

1302從您的 marketplace 目錄，驗證 JSON 語法：

~~1303~~

1304```bash theme={null}

1305claude plugin validate .

1306```

~~1307~~

1308或從 Claude Code 內：

~~1309~~

1310```shell theme={null}

1311/plugin validate .

1312```

~~1313~~

1314新增 marketplace 進行測試：

~~1315~~

1316```shell theme={null}

1317/plugin marketplace add ./path/to/marketplace

1318```

~~1319~~

1320安裝測試 plugin 以驗證一切正常運作：

~~1321~~

1322```shell theme={null}

1323/plugin install test-plugin@marketplace-name

1324```

~~1325~~

1326有關完整的 plugin 測試工作流程，請參閱[在本機測試您的 plugin](/docs/zh-TW/plugins#test-your-plugins-locally)。有關技術疑難排解，請參閱 [Plugins reference](/docs/zh-TW/plugins-reference)。

~~1327~~

1328<h2 id="manage-marketplaces-from-the-cli">

1329 從 CLI 管理市集

1330</h2>

~~1331~~

1332Claude Code 提供非互動式的 `claude plugin marketplace` 子命令，用於指令碼和自動化。這些命令等同於互動式工作階段中可用的 `/plugin marketplace` 命令。

~~1333~~

1334<h3 id="plugin-marketplace-add">

1335 Plugin marketplace add

1336</h3>

~~1337~~

1338從 GitHub 儲存庫、git URL、遠端 URL 或本機路徑新增市集。

~~1339~~

1340```bash theme={null}

1341claude plugin marketplace add <source> [options]

1342```

~~1343~~

1344**引數：**

~~1345~~

1346* `<source>`：GitHub `owner/repo` 簡寫、git URL、指向 `marketplace.json` 檔案的遠端 URL，或本機目錄路徑。若要釘選到分支或標籤，請在 GitHub 簡寫後附加 `@ref`，或在 git URL 後附加 `#ref`

~~1347~~

1348URL 必須包含其配置。自 Claude Code v2.1.196 起，未輸入配置的主機（例如 `gitlab.example.com/team/plugins`）會被拒絕為無效的 `owner/repo` 簡寫，錯誤訊息會告訴您新增 `https://` 或使用 `./` 作為本機路徑。較早的版本會將其誤讀為 GitHub 儲存庫路徑，並在複製時因 GitHub 找不到錯誤而失敗。

~~1349~~

1350**選項：**

~~1351~~

1352| 選項 | 說明 | 預設值 |

1353| :-------------------- | :----------------------------------------------------------------------------------------------------------- | :----- |

1354| `--scope <scope>` | 宣告市集的位置：`user`、`project` 或 `local`。請參閱 [Plugin 安裝範圍](/docs/zh-TW/plugins-reference#plugin-installation-scopes) | `user` |

1355| `--sparse <paths...>` | 透過 git sparse-checkout 限制簽出到特定目錄。適用於 monorepos | |

1356| `--claudeai` | 將引數讀取為 [claude.ai 上託管的市集](/docs/zh-TW/discover-plugins#add-from-claude-ai)的名稱，而不是來源。需要 Claude Code v2.1.273 或更新版本 | |

~~1357~~

1358使用 `owner/repo` 簡寫從 GitHub 新增市集：

~~1359~~

1360```bash theme={null}

1361claude plugin marketplace add acme-corp/claude-plugins

1362```

~~1363~~

1364使用 `@ref` 釘選到特定分支或標籤：

~~1365~~

1366```bash theme={null}

1367claude plugin marketplace add acme-corp/claude-plugins@v2.0

1368```

~~1369~~

1370從非 GitHub 主機上的 git URL 新增：

~~1371~~

1372```bash theme={null}

1373claude plugin marketplace add https://gitlab.example.com/team/plugins.git

1374```

~~1375~~

1376從直接提供 `marketplace.json` 檔案的遠端 URL 新增：

~~1377~~

1378```bash theme={null}

1379claude plugin marketplace add https://example.com/marketplace.json

1380```

~~1381~~

1382從本機目錄新增以進行測試：

~~1383~~

1384```bash theme={null}

1385claude plugin marketplace add ./my-marketplace

1386```

~~1387~~

1388在專案範圍宣告市集，以便透過 `.claude/settings.json` 與您的團隊共享：

~~1389~~

1390```bash theme={null}

1391claude plugin marketplace add acme-corp/claude-plugins --scope project

1392```

~~1393~~

1394對於 monorepo，限制簽出到包含外掛程式內容的目錄：

~~1395~~

1396```bash theme={null}

1397claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

1398```

~~1399~~

1400從 [claude.ai 上託管的市集](/docs/zh-TW/discover-plugins#add-from-claude-ai)新增，使用 `claude plugin marketplace list` 的 `From claude.ai:` 區段中列印的名稱：

~~1401~~

1402```bash theme={null}

1403claude plugin marketplace add --claudeai claudeai-organization-library

1404```

~~1405~~

1406使用 `--claudeai` 時，命令會拒絕 `--scope` 和 `--sparse`。市集是為您的帳戶託管的，而不是在設定檔中宣告的，因此您無法透過專案的 `.claude/settings.json` 共享它。

~~1407~~

1408<h3 id="plugin-marketplace-list">

1409 Plugin marketplace list

1410</h3>

~~1411~~

1412列出所有已設定的市集。

~~1413~~

1414```bash theme={null}

1415claude plugin marketplace list [options]

1416```

~~1417~~

1418**選項：**

~~1419~~

1420| 選項 | 說明 |

1421| :------- | :------- |

1422| `--json` | 輸出為 JSON |

~~1423~~

1424使用 `--json` 時，每個項目包括 `name`、`source`、一個 `installLocation` 欄位（包含市集儲存所在的本機快取路徑），以及來源特定的欄位：GitHub 來源的 `repo`、git 和 URL 來源的 `url`，以及本機來源的 `path`。當市集新增時使用釘選的分支或標籤時，GitHub 和 git 來源也包括 `ref` 欄位。

~~1425~~

1426已新增的 [claude.ai 市集](/docs/zh-TW/discover-plugins#add-from-claude-ai)沒有本機複製，因此其項目會改為使用其 claude.ai 識別碼 `marketplaceId` 和 `organizationUuid` 來代替 `installLocation`。

~~1427~~

1428在 [外掛程式從您的 claude.ai 帳戶同步](/docs/zh-TW/plugins-reference#synced-plugins)的終端機工作階段中，文字列表的結尾會有一個 `From claude.ai:` 區段，列出 claude.ai 為您的帳戶列出的內容，超出您已新增的市集。若要新增其中一個，請參閱 [從 claude.ai 新增](/docs/zh-TW/discover-plugins#add-from-claude-ai)。`--json` 輸出僅涵蓋已設定的市集，並省略該區段。需要 Claude Code v2.1.273 或更新版本。

~~1429~~

1430<h3 id="plugin-marketplace-remove">

1431 Plugin marketplace remove

1432</h3>

~~1433~~

1434移除已設定的市集。別名 `rm` 也可接受。

~~1435~~

1436```bash theme={null}

1437claude plugin marketplace remove <name> [options]

1438```

~~1439~~

1440**引數：**

~~1441~~

1442* `<name>`：要移除的市集名稱，如 `claude plugin marketplace list` 所示。這是來自 `marketplace.json` 的 `name`，而不是您傳遞給 `add` 的來源

~~1443~~

1444**選項：**

~~1445~~

1446| 選項 | 說明 | 預設值 |

1447| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----- |

1448| `--scope <scope>` | 限制移除到單一設定範圍：`user`、`project` 或 `local`。請參閱 [Plugin 安裝範圍](/docs/zh-TW/plugins-reference#plugin-installation-scopes)。省略時，宣告會從每個可編輯的範圍中移除。指定時，只會移除該範圍的宣告；當市集仍在另一個範圍中宣告時，共享狀態、快取和已安裝的外掛程式資料會保留 | （所有範圍） |

~~1449~~

1450<Warning>

1451 從其最後剩餘的範圍移除市集也會解除安裝您從中安裝的任何外掛程式。若要重新整理市集而不遺失已安裝的外掛程式，請改用 `claude plugin marketplace update`。

1452</Warning>

~~1453~~

1454<h3 id="plugin-marketplace-update">

1455 Plugin marketplace update

1456</h3>

~~1457~~

1458從其來源重新整理市集，以擷取新外掛程式和版本變更。使用分支或標籤 `ref` 新增的市集會更新到該 ref 的最新提交，而不是儲存庫的預設分支。

~~1459~~

1460```bash theme={null}

1461claude plugin marketplace update [name]

1462```

~~1463~~

1464**引數：**

~~1465~~

1466* `[name]`：要更新的市集名稱，如 `claude plugin marketplace list` 所示。省略時會更新所有市集

~~1467~~

1468當針對種子管理的市集執行時，`remove` 和 `update` 都會失敗，該市集是唯讀的。更新所有市集時，種子管理的項目會被跳過，其他市集仍會更新。若要變更種子提供的外掛程式，請要求您的管理員更新種子映像。請參閱 [為容器預先填入外掛程式](#pre-populate-plugins-for-containers)。

~~1469~~

1470<h2 id="troubleshooting">

1471 疑難排解

1472</h2>

~~1473~~

1474<h3 id="marketplace-not-loading">

1475 Marketplace 未載入

1476</h3>

~~1477~~

1478**症狀**：無法新增 marketplace 或看不到其中的 plugin

~~1479~~

1480**解決方案**：

~~1481~~

1482* 驗證 marketplace URL 可存取

1483* 檢查 `.claude-plugin/marketplace.json` 是否存在於指定路徑

1484* 使用 `claude plugin validate .` 或 `/plugin validate .` 確保 JSON 語法有效。若要檢查 skill、agent 和 command frontmatter，請參閱[驗證沒有 manifest 的 plugin 或目錄](#validate-a-plugin-or-a-directory-without-a-manifest)

1485* 對於私人儲存庫，確認您有存取權限

~~1486~~

1487<h3 id="marketplace-validation-errors">

1488 Marketplace 驗證錯誤

1489</h3>

~~1490~~

1491從您的 marketplace 目錄執行 `claude plugin validate .` 或 `/plugin validate .` 以檢查問題。當指向 marketplace 目錄時，驗證器檢查 `marketplace.json` 是否有架構錯誤、重複的 plugin 名稱和來源路徑遍歷。對於每個 `source` 為本機路徑的項目，它也會驗證該 plugin 自己的 `plugin.json`，並在項目的 `version` 與 `plugin.json` 中的版本不符時發出警告。在 plugin 的 `plugin.json` 中發現的問題會以項目索引作為前綴，形式為 `plugins[2] plugin.json →`。

~~1492~~

1493自 Claude Code v2.1.196 起，每個項目的檢查也會：

~~1494~~

1495* 包含 `source` 為 `.` 的 plugin

1496* 在 `marketplace.json` 位於 `.claude-plugin` 目錄外時執行，針對檔案自己的目錄解析來源

1497* 即使檔案的另一部分有架構錯誤，也會報告每個項目的問題

~~1498~~

1499較早的版本會跳過 marketplace 根目錄中的 plugin，並且只從 `.claude-plugin/marketplace.json` 開始下降。

~~1500~~

1501從 marketplace 目錄，Claude Code 不會開啟 plugin 的 skill、agent、command 或 hook 檔案。若要在這些檔案中找到錯誤，請參閱[驗證沒有 manifest 的 plugin 或目錄](#validate-a-plugin-or-a-directory-without-a-manifest)。下表列出從 marketplace 目錄最常見的錯誤，以及每個錯誤的原因和修正方式：

~~1502~~

1503| 錯誤 | 原因 | 解決方案 |

1504| :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |

1505| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | 您命名的目錄沒有 `.claude-plugin/marketplace.json` 或 `plugin.json`，也沒有 skill、agent 或 command 檔案可檢查 | 從 marketplace 根目錄執行，或使用必需欄位建立 `.claude-plugin/marketplace.json` |

1506| `Invalid JSON syntax: Unexpected token...` | JSON 語法錯誤在 marketplace.json 中 | 檢查缺少的逗號、多餘的逗號或未引用的字串 |

1507| `Duplicate plugin name "x" found in marketplace` | 兩個 plugin 共享相同名稱 | 為每個 plugin 指定唯一的 `name` 值 |

1508| `plugins[0].source: Path contains ".."` | 來源路徑包含 `..` | 使用相對於 marketplace 根目錄的路徑，不含 `..`。請參閱[相對路徑](#relative-paths) |

1509| `Marketplace name cannot contain control or bidirectional-formatting characters` | marketplace `name` 包含 Unicode 雙向格式化字元或控制字元，例如逸出或換行符 | 從名稱中移除該字元。在 v2.1.247 之前，這些字元會產生 `Marketplace name impersonates an official Anthropic/Claude marketplace` 錯誤 |

1510| `Plugin name cannot contain control or bidirectional-formatting characters` | plugin `name` 包含 Unicode 雙向格式化字元或控制字元，例如逸出或換行符 | 從名稱中移除該字元。在 v2.1.247 之前，Claude Code 不執行此檢查 |

~~1511~~

1512**警告**（非阻止性）：

~~1513~~

1514* `Marketplace has no plugins defined`：將至少一個 plugin 新增到 `plugins` 陣列

1515* `No marketplace description provided`：新增頂層 `description` 以幫助使用者瞭解您的 marketplace

1516* `Plugin name "x" is not kebab-case`：重新命名為僅包含小寫字母、數字和連字號（例如，`my-plugin`）。Claude Code 接受其他形式，但 claude.ai marketplace 同步會拒絕它們。

1517* `Marketplace name "x" is reserved in Claude Desktop`：marketplace 名稱為 `org`、`org-provisioned` 或 `unknown`（任何大小寫）。Claude Code 接受這些名稱，但 Claude Desktop 的受管 marketplace 同步會拒絕整個 marketplace。重新命名 marketplace。在 v2.1.221 之前，`claude plugin validate` 不執行此檢查。

1518* `Marketplace name "x" is not accepted by Claude Desktop` 或 `Plugin name "x" is not accepted by Claude Desktop`：Claude Desktop 接受最多 128 個字元的名稱，由字母、數字、`.`、`_` 和 `-` 組成，以字母或數字開頭。Claude Code 接受其他形式，但 Claude Desktop 的受管 marketplace 同步會拒絕名稱檢查失敗的 marketplace，並以無聲方式捨棄名稱檢查失敗的 plugin 項目。重新命名 marketplace 或 plugin。在 v2.1.221 之前，`claude plugin validate` 不執行這些檢查。

~~1519~~

1520<h4 id="validate-a-plugin-or-a-directory-without-a-manifest">

1521 驗證沒有 manifest 的 plugin 或目錄

1522</h4>

~~1523~~

1524若要找到 frontmatter 無法解析的 skill、agent 和 command 檔案，請執行 `claude plugin validate` 並命名保存它們的目錄。Claude Code 不會查看您命名的目錄外的檔案。除了一次針對具有 `plugin.json` 的 plugin 執行外，每次執行都需要 Claude Code v2.1.233 或更新版本。

~~1525~~

1526<h5 id="pick-the-directory-to-name">

1527 選擇要命名的目錄

1528</h5>

~~1529~~

1530Claude Code 根據您命名的目錄檢查不同的檔案。在第一欄中找到您想檢查的內容，並執行該列的命令：

~~1531~~

1532| 若要檢查 | 執行 | Claude Code 檢查 |

1533| :------------------------------------------------------ | :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |

1534| 具有 `plugin.json` 的 plugin | `claude plugin validate ./plugins/my-plugin` | `plugin.json`、`hooks/hooks.json` 以及 plugin 根目錄下的 `skills`、`agents` 和 `commands` 目錄 |

1535| 一個 skill、agent 或 command 目錄，例如尚無 `plugin.json` 的 plugin | `claude plugin validate .claude/skills`、`~/.claude/agents` 或 `./my-plugin/agents` | 該目錄中的每個 skill、agent 或 command 檔案 |

1536| 其 skill 為其根 `SKILL.md` 的資料夾 | `claude plugin validate ./skills`，命名保存該資料夾的 `skills` 目錄 | 每個資料夾的根 `SKILL.md`。保存目錄必須命名為 `skills`；位於另一個名稱下的資料夾（例如 `plugins/`）沒有檢查其根 `SKILL.md` 的執行 |

1537| 一個專案的三個目錄一次 | `claude plugin validate .claude`，或沒有 `.claude-plugin/` manifest 的專案根目錄 | `.claude/skills`、`.claude/agents` 和 `.claude/commands` |

1538| 您的使用者層級目錄 | `claude plugin validate ~/.claude` | `~/.claude/skills`、`~/.claude/agents` 和 `~/.claude/commands` |

~~1539~~

1540<h5 id="check-a-plugin-whose-skill-is-its-root-skill-md">

1541 檢查其 skill 為其根 `SKILL.md` 的 plugin

1542</h5>

~~1543~~

1544當您針對 plugin 目錄執行 `claude plugin validate` 時，Claude Code 不檢查 plugin 根目錄下的 `SKILL.md`。當 plugin 位於名為 `skills` 的目錄中時，執行該命令兩次：

~~1545~~

1546* 命名該 `skills` 目錄以檢查 plugin 的根 `SKILL.md`。

1547* 命名 plugin 目錄以檢查其餘部分。

~~1548~~

1549當 plugin 位於另一個名稱下（例如 `plugins/`）時，`skills` 目錄執行不可用，沒有執行檢查其根 `SKILL.md`。

~~1550~~

1551<h5 id="check-files-behind-symlinks">

1552 檢查符號連結後的檔案

1553</h5>

~~1554~~

1555當您執行 `claude plugin validate` 時，Claude Code 不會跟隨您命名的目錄內的符號連結。它的作用取決於連結的位置：

~~1556~~

1557* **plugin 或 `.claude` 根目錄下的連結 `skills`、`agents` 或 `commands` 目錄**：Claude Code 警告其中沒有任何內容被讀取。

1558* **`skills`、`agents` 或 `commands` 目錄內的連結項目**：Claude Code 跳過它並警告，每個目錄，它跳過了多少個項目，工作階段會載入。

1559* **您命名的 `skills`、`agents` 或 `commands` 目錄本身是符號連結，或其父 `.claude` 目錄是**：Claude Code 報告錯誤並檢查其中沒有任何內容。改為命名真實目錄。

~~1560~~

1561在兩個 skill 情況下，執行通過並帶有警告。若要檢查連結的檔案，再次執行並命名直接保存它們的目錄：

~~1562~~

1563* **其 `skills` 目錄[連結到同級 plugin 的 skill](/docs/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks) 的 plugin**：命名同級 plugin 的目錄。

1564* **`~/.claude/skills` 或 `.claude/skills` 中的[符號連結 skill 項目](/docs/zh-TW/skills#where-skills-live)**：Claude Code 在工作階段中跟隨該項目。若要檢查它，命名一個名為 `skills` 的目錄，保存真實資料夾。

~~1565~~

1566<h5 id="read-the-validation-results">

1567 讀取驗證結果

1568</h5>

~~1569~~

1570乾淨的執行以 `Validation passed` 結束。

~~1571~~

1572`No manifest found in directory` 表示 Claude Code 在那裡找不到 `plugin.json` 或 `marketplace.json`，也找不到它在其下探測的目錄中的 skill、agent 或 command 檔案。改為命名保存您的檔案的 `skills`、`agents` 或 `commands` 目錄。

~~1573~~

1574Claude Code 從這些執行報告的兩個錯誤，以及每個的修正方式：

~~1575~~

1576* `YAML frontmatter failed to parse: ...`：修正 skill、agent 或 command 檔案的 frontmatter 區塊中的 YAML。在您執行此操作之前，工作階段從檔案讀取沒有 frontmatter 欄位

1577* `Invalid JSON syntax: ...` 在 `hooks/hooks.json` 上：修正 JSON 語法。在您執行此操作之前，工作階段載入 plugin 而不載入該檔案中的 hook。Claude Code 僅在 plugin 執行中報告此錯誤

~~1578~~

1579在 plugin 執行中，Claude Code 也警告 plugin 根目錄下的 `CLAUDE.md`。對於您透過 `plugin.json` 中的[元件路徑欄位](/docs/zh-TW/plugins-reference#component-path-fields)設定的路徑，Claude Code 檢查每個路徑是否存在，但不讀取那裡的檔案。

~~1580~~

1581<h3 id="plugin-installation-failures">

1582 Plugin 安裝失敗

1583</h3>

~~1584~~

1585**症狀**：Marketplace 出現但 plugin 安裝失敗

~~1586~~

1587**解決方案**：

~~1588~~

1589* 驗證 plugin 來源 URL 可存取

1590* 檢查 plugin 目錄是否包含必需的檔案

1591* 對於 GitHub 來源，確保儲存庫是公開的或您有存取權

1592* 透過手動複製/下載測試 plugin 來源

1593* 如果來源同時固定 `ref` 和 `sha`，已刪除的上游分支或標籤不會阻止在大多數 git 主機（包括 GitHub、GitLab 和 Bitbucket）上的安裝。在不支援按 SHA 擷取提交的伺服器上（例如 AWS CodeCommit），`ref` 仍必須存在，且固定的提交必須可從其到達。如果安裝仍然失敗，請確認固定的提交仍然存在於儲存庫中

~~1594~~

1595<h3 id="private-repository-authentication-fails">

1596 私人儲存庫驗證失敗

1597</h3>

~~1598~~

1599**症狀**：從私人儲存庫安裝 plugin 時出現驗證錯誤

~~1600~~

1601**解決方案**：

~~1602~~

1603對於手動安裝和更新：

~~1604~~

1605* 驗證您已使用您的 git 提供者進行驗證（例如，為 GitHub 執行 `gh auth status`）

1606* 檢查您的認證助手是否正確配置：`git config --global credential.helper`

1607* 執行 `git ls-remote <marketplace-url>` 以測試 git 是否可以自行驗證。如果 git 要求使用者名稱或密碼，請先儲存認證：對於 GitHub over HTTPS，執行 `gh auth setup-git`，對於 SSH 遠端，將您的金鑰載入 `ssh-agent`

~~1608~~

1609對於背景自動更新：

~~1610~~

1611* 背景檢查使用您配置的 git 認證助手，但永遠不會提示，因此您的助手必須能夠使用儲存的認證回答。具有在 `ssh-agent` 中載入的金鑰的 SSH 遠端也會進行驗證

1612* 如果您的助手需要提示您，背景更新會以無聲方式失敗，現有複製保持原位。先登入您的助手，以便它為主機保存認證。對於 GitHub，執行 `gh auth login`，然後執行 `gh auth setup-git`

1613* 當檢查找到新提交，或無法到達或驗證遠端時，Claude Code 使用相同的認證重新複製 marketplace。重新複製可能在大型儲存庫上逾時

1614* 設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在背景檢查無法到達或驗證遠端時保留現有複製而不嘗試重新複製

1615* 如果重新複製在大型儲存庫上逾時，請使用 [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out) 增加限制

1616* 或使用 `/plugin marketplace update <name>` 手動更新私人 marketplace，這會使用您的認證

~~1617~~

1618在 v2.1.280 之前，背景檢查執行時沒有您的認證助手，無法驗證透過 HTTPS 的私人儲存庫。

~~1619~~

1620<h3 id="marketplace-updates-fail-in-offline-environments">

1621 Marketplace 更新在離線環境中失敗

1622</h3>

~~1623~~

1624**症狀**：在離線或隔離環境中，背景 marketplace 重新整理無法到達遠端，Claude Code 重複嘗試無法成功的重新複製。

~~1625~~

1626**原因**：背景重新整理檢查 marketplace 的遠端以尋找新提交，當檢查無法到達遠端時，Claude Code 嘗試再次複製 marketplace。離線時，複製以相同方式失敗，現有複製保持原位。在 v2.1.274 之前，重新整理在現有複製中執行 `git pull`，當拉取失敗時將複製移到一邊以重新複製，並在之後以盡力而為的基礎上還原它。

~~1627~~

1628重新整理在啟動後在背景中執行，因此不會延遲啟動。每個工作階段仍會重複失敗的嘗試，每個 git 操作都可以等待 [120 秒逾時](#git-operations-time-out)。

~~1629~~

1630**解決方案**：設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在檢查無法到達遠端時跳過重新複製嘗試並繼續使用現有複製：

~~1631~~

1632```bash theme={null}

1633export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

1634```

~~1635~~

1636對於儲存庫永遠無法到達的完全離線部署，請改用 [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) 在建置時預先填充 plugin 目錄。

~~1637~~

1638<h3 id="git-operations-time-out">

1639 Git 操作逾時

1640</h3>

~~1641~~

1642**症狀**：Plugin 安裝或 marketplace 更新失敗，出現逾時錯誤，例如 `Git clone timed out after 120s`。

~~1643~~

1644**原因**：Claude Code 對所有 git 操作（包括複製 plugin 儲存庫和重新複製 marketplace 以更新它）使用 120 秒逾時。大型儲存庫或緩慢的網路連線可能超過此限制。

~~1645~~

1646**解決方案**：使用 `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` 環境變數增加逾時。值以毫秒為單位：

~~1647~~

1648```bash theme={null}

1649export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5 分鐘

1650```

~~1651~~

1652<h3 id="plugins-with-relative-paths-fail-in-url-based-marketplaces">

1653 相對路徑 plugin 在基於 URL 的 marketplace 中失敗

1654</h3>

~~1655~~

1656**症狀**：透過 URL（例如 `https://example.com/marketplace.json`）新增 marketplace，但具有相對路徑來源（如 `"./plugins/my-plugin"`）的 plugin 無法安裝，出現 `its marketplace entry path does not stay inside the marketplace directory` 錯誤。已安裝的 plugin 無法載入，出現 `Plugin source path refused` 錯誤。兩個訊息都有[錯誤參考項目](/docs/zh-TW/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory)。

~~1657~~

1658**原因**：新增基於 URL 的 marketplace 僅下載 `marketplace.json` 檔案本身，Claude Code 不會從該伺服器按相對路徑擷取 plugin 檔案。marketplace 項目中的相對路徑參考未下載的遠端伺服器上的檔案。

~~1659~~

1660**解決方案**：

~~1661~~

1662* **使用外部來源**：將 plugin 項目變更為相對路徑以外的任何 [plugin 來源](#plugin-sources)：

1663 ```json theme={null}

1664 { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

1665 ```

1666* **使用基於 Git 的 marketplace**：在 Git 儲存庫中託管您的 marketplace 並使用 git URL 新增它。基於 Git 的 marketplace 複製整個儲存庫，使相對路徑正常運作。

~~1667~~

1668<h3 id="files-not-found-after-installation">

1669 安裝後找不到檔案

1670</h3>

~~1671~~

1672**症狀**：Plugin 安裝但對檔案的參考失敗，特別是 plugin 目錄外的檔案

~~1673~~

1674**原因**：Claude Code 將已安裝的 plugin 複製到快取目錄，除非 plugin 就地載入。[連結模式中的 `command` 來源](#copy-mode-and-link-mode)就地載入，[本機目錄新增的 marketplace 中的相對路徑來源](#relative-paths)也是如此。參考複製 plugin 目錄外檔案的路徑（例如 `../shared-utils`）無法運作，因為這些檔案不會被複製。

~~1675~~

1676**解決方案**：有關解決方案（包括符號連結和目錄重組），請參閱 [Plugin caching and file resolution](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。

~~1677~~

1678有關其他偵錯工具和常見問題，請參閱 [Debugging and development tools](/docs/zh-TW/plugins-reference#debugging-and-development-tools)。

~~1679~~

1680<h2 id="see-also">

1681 另請參閱

1682</h2>

~~1683~~

1684* [探索並安裝預先建立的 plugins](/docs/zh-TW/discover-plugins) - 從現有 marketplace 安裝 plugins

1685* [Plugins](/docs/zh-TW/plugins) - 建立您自己的 plugins

1686* [Plugins reference](/docs/zh-TW/plugins-reference) - 完整的技術規格和架構

1687* [Plugin settings](/docs/zh-TW/settings-reference#plugin-settings) - Plugin 配置選項

1688* [strictKnownMarketplaces reference](/docs/zh-TW/settings-reference#strictknownmarketplaces) - 受管 marketplace 限制

plugin-relevance.md +0 −188 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# 為您的組織推薦外掛程式~~

~~7> 在 marketplace.json 中的外掛程式項目中新增相關性區塊，以便在使用者的工作相符時，Claude Code 會建議這些外掛程式。~~

9如果您為組織運營外掛程式 marketplace，您可以根據使用者正在進行的工作，讓 Claude Code 向使用者建議特定的外掛程式。在 `marketplace.json` 中的外掛程式項目中新增 `relevance` 區塊，然後在受管設定中將 marketplace 加入允許清單。當使用者的工作階段符合其中一個已宣告的信號時，Claude Code 會顯示該外掛程式的安裝建議。

11Marketplace 宣告的建議是透過[受管設定](/docs/zh-TW/managed-settings)按 marketplace 選擇加入的。在管理員將任何 marketplace 新增至允許清單之前，該 marketplace 的 `relevance` 宣告都不會產生建議，包括官方 Anthropic marketplace。Claude Code 還包括一個獨立於此允許清單的內建建議；當 [`spinnerTipsEnabled`](/docs/zh-TW/settings-reference#spinnertipsenabled) 設定為 `false` 時，該提示和所有 marketplace 宣告的提示都會被停用。

~~13此頁面適用於 marketplace 運營商和企業管理員。如果您想要安裝外掛程式，請參閱[探索和安裝外掛程式](/docs/zh-TW/discover-plugins)。~~

~~15<h2 id="how-it-works">~~

~~16 運作方式~~

~~17</h2>~~

19`marketplace.json` 中的每個外掛程式項目都可以包含一個 `relevance` 物件。該物件命名一個主題和一個或多個信號。信號是 Claude Code 針對目前工作階段測試的模式，例如工作目錄或 Claude 已讀取的檔案。

~~21信號比對在使用者的機器上本地進行。比對不會增加任何網路流量，也不會向 Anthropic 或 marketplace 運營商報告哪些信號相符或其值。~~

~~23當信號相符且外掛程式尚未安裝時，Claude Code 會在三個位置顯示該外掛程式：~~

~~25* **Spinner 提示**：當 Claude 正在回應時，spinner 下方會出現「使用 *主題*？安裝 *外掛程式* 外掛程式」訊息，並附帶 `/plugin install` 命令。~~

~~26* **工作階段開始建議**：如果 `cwd` 信號符合工作目錄，在第一個回合之前會出現一行 `plugin suggestion: <name>@<marketplace> · /plugin` 通知。~~

~~27* **`/plugin` Discover 標籤**：外掛程式會被釘選到 Discover 清單的頂部，並附帶註解，例如「建議用於此目錄」或「建議用於 stripe 命令」。~~

29Spinner 提示和工作階段開始通知是 spinner 提示系統的一部分。當 `spinnerTipsEnabled` 在您的設定檔中解析為 `false`，或當 `excludeDefault` 在使用者、`--settings` 和受管設定中的 [`spinnerTipsOverride`](/docs/zh-TW/settings-reference#spinnertipsoverride) 鍵中解析為 `true`，且這些鍵至少配置一個提示或 `tipsFile` 時，Claude Code 會停用兩者。

~~31Discover 標籤釘選獨立於提示設定。~~

~~33Claude Code 永遠不會自動安裝外掛程式。使用者始終需要確認。~~

~~35<h2 id="add-relevance-to-a-plugin-entry">~~

~~36 為外掛程式項目新增相關性~~

~~37</h2>~~

39在您的 `marketplace.json` 中的外掛程式項目中新增 `relevance` 物件。以下範例宣告當 Claude 讀取 `.tf` 檔案或執行 `terraform` 時，`terraform-helpers` 外掛程式是相關的：

~~41```json theme={null}~~

~~42{~~

~~43 "name": "acme-corp-plugins",~~

~~44 "owner": { "name": "Acme Platform Team" },~~

~~45 "plugins": [~~

~~46 {~~

~~47 "name": "terraform-helpers",~~

~~48 "source": "./plugins/terraform-helpers",~~

~~49 "description": "Acme conventions and helpers for Terraform",~~

~~50 "relevance": {~~

~~51 "topic": "Terraform",~~

~~52 "signals": {~~

~~53 "cli": ["terraform"],~~

~~54 "filesRead": ["**/*.tf"]~~

~~55 }~~

~~56 }~~

~~57 }~~

~~58 ]~~

~~59}~~

~~60```~~

62具有 `relevance` 區塊但沒有相符信號的外掛程式的行為與任何其他 marketplace 項目相同。它會在 Discover 清單中以其正常位置出現，永遠不會顯示為 spinner 提示。

~~64<h2 id="field-reference">~~

~~65 欄位參考~~

~~66</h2>~~

~~68<h3 id="relevance">~~

~~69 `relevance`~~

~~70</h3>~~

~~72| 欄位 | 類型 | 說明 |~~

~~73| :-------- | :- | :---------------------------------------------------------------------------------------------------------------------------------- |~~

74| `topic` | 字串 | 選用。填充 spinner 提示中「使用 *主題*？」的片語。通常是產品名稱，例如 `Stripe`。當外掛程式名稱不能自然地作為主題讀取時，使用 `design` 等網域。預設為外掛程式名稱，每個連字號段落大寫。工作階段開始通知不使用此值。最多 64 個字元。 |

75| `signals` | 物件 | 決定外掛程式何時相關的匹配器。至少需要一個信號才能使外掛程式可被建議。請參閱下表。 |

~~77<h3 id="relevance-signals">~~

~~78 `relevance.signals`~~

~~79</h3>~~

81| 欄位 | 類型 | 說明 |

82| :------------- | :--- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

83| `cwd` | 字串陣列 | 與工作階段工作目錄相符的 Glob 模式。作為絕對路徑相符，當在 git 儲存庫內時，作為相對於儲存庫根目錄的路徑相符。正斜線正規化且不區分大小寫。每個模式都符合目錄本身及其下的所有內容，因此 `infra`、`infra/` 和 `infra/**` 的行為相同。這是唯一可以在工作階段開始時（在第一個回合之前）相符的信號。最多 10 個模式，每個 256 個字元。 |

84| `cli` | 字串陣列 | Claude 在此工作階段執行的 shell 命令中的命令名稱，例如 `["stripe"]`。適用於每個平台：在 Windows 上透過 PowerShell 或 Git Bash 執行的命令以相同方式記錄。Claude Code 為每個 shell 工具呼叫記錄一個命令名稱：任何前導環境變數指派和 `sudo` 之後的第一個權杖。複合命令只貢獻其前導命令，因此 `cd infra && terraform plan` 記錄 `cd`，而不是 `terraform`。完全相符。最多 10 個項目，每個 64 個字元。 |

85| `hosts` | 字串陣列 | 此工作階段中 Bash 命令中 `http://` 或 `https://` URL 中看到的主機名稱，例如 `["api.stripe.com"]`。僅限裸露小寫主機名稱：無配置、連接埠或路徑。完全不區分大小寫相符。最多 20 個項目，每個 128 個字元。 |

86| `filesRead` | 字串陣列 | 與 Claude 在此工作階段讀取的檔案路徑相符的 Glob 模式，例如 `["**/*.tf"]`。正斜線正規化且不區分大小寫。最多 10 個模式，每個 256 個字元。 |

87| `manifestDeps` | 物件陣列 | Claude 在此工作階段讀取的套件資訊清單中宣告的相依性。每個項目都是 `{ "file": "...", "pattern": "..." }`，其中 `file` 是與資訊清單檔案路徑相符的正規表達式（如工作階段狀態中所記錄，通常是絕對路徑），`pattern` 是與該檔案內容相符的正規表達式。在 `file` 的末尾錨定，例如 JSON 逸出形式中的 `[/\\\\]package\\.json$`，因為開始錨定的模式永遠不會符合絕對路徑。路徑不會針對此信號進行分隔符號正規化，因此 Windows 路徑使用反斜線。大於 512 KB 的資訊清單檔案會被跳過。兩個值都是最多 256 個字元的 JavaScript `RegExp` 來源字串。`file` 不區分大小寫相符。`pattern` 區分大小寫。最多 10 個項目。 |

~~89`cli`、`hosts`、`filesRead` 和 `manifestDeps` 信號需要工作階段歷史記錄，因此它們只能在 spinner 提示和 Discover 標籤上相符。~~

91`filesRead` 和 `manifestDeps` 信號測試工作階段的記錄檔案狀態，其中也包括 Claude 已寫入或編輯的檔案以及自動載入的 `CLAUDE.md` 記憶體檔案。對於這兩個信號，Claude Code 會跳過其自身[設定目錄](/docs/zh-TW/claude-directory)及其暫存目錄下的路徑。

93以下範例使用 `manifestDeps` 在 Claude 讀取依賴 `stripe` 的 `package.json` 後建議 Stripe 外掛程式。`file` 模式使用 `[/\\\\]` 以便符合正斜線和反斜線路徑分隔符號，以及 `\\.` 以便點是字面意思。在 JSON 中，正規表達式中的每個反斜線都寫兩次。

~~95```json theme={null}~~

~~96{~~

~~97 "name": "stripe-helpers",~~

~~98 "source": "./plugins/stripe-helpers",~~

~~99 "relevance": {~~

100 "topic": "Stripe",

101 "signals": {

102 "manifestDeps": [

103 {

104 "file": "[/\\\\]package\\.json$",

105 "pattern": "\"stripe\"\\s*:"

106 }

107 ]

108 }

109 }

110}

111```

~~112~~

113<Note>

114 Claude Code 在載入時會忽略 `relevance` 和 `relevance.signals` 下的未知欄位，因此較舊的用戶端會繼續載入您的 marketplace。

115</Note>

~~116~~

117<h2 id="enable-suggestions-in-managed-settings">

118 在受管設定中啟用建議

119</h2>

~~120~~

121在 `marketplace.json` 中宣告 `relevance` 本身是不夠的。管理員必須在[受管設定](/docs/zh-TW/managed-settings)中將 marketplace 加入允許清單，才能向使用者顯示其建議。

~~122~~

123將 marketplace 名稱新增至 `pluginSuggestionMarketplaces`。對於官方 Anthropic marketplace 以外的任何 marketplace，也在相同的受管設定中宣告 marketplace 來源，可以是該名稱在 `extraKnownMarketplaces` 中的項目，或在 `strictKnownMarketplaces` 中的項目。如果在機器上註冊的 marketplace 來自不同的來源，允許清單中的名稱會被忽略。這可防止無關的來源以允許清單中的名稱進行註冊，以便在整個組織中建議其外掛程式。

~~124~~

125以下 `managed-settings.json` 從 GitHub 儲存庫註冊組織 marketplace 並啟用其建議：

~~126~~

127```json theme={null}

128{

129 "extraKnownMarketplaces": {

130 "acme-corp-plugins": {

131 "source": {

132 "source": "github",

133 "repo": "acme-corp/claude-plugins"

134 }

135 }

136 },

137 "pluginSuggestionMarketplaces": ["acme-corp-plugins"]

138}

139```

~~140~~

141官方 marketplace 不受來源宣告要求的限制，因為其名稱只能從官方 Anthropic 來源進行註冊。僅允許清單中的名稱就足夠了：

~~142~~

143```json theme={null}

144{

145 "pluginSuggestionMarketplaces": ["claude-plugins-official"]

146}

147```

~~148~~

149<h2 id="what-the-user-sees">

150 使用者看到的內容

151</h2>

~~152~~

153當工作階段期間信號相符時，spinner 提示會讀取：

~~154~~

155```text theme={null}

156Working with Terraform? Install the terraform-helpers plugin:

157/plugin install terraform-helpers@acme-corp-plugins

158```

~~159~~

160在工作階段開始時，相符的 `cwd` 信號會顯示一行通知：

~~161~~

162```text theme={null}

163plugin suggestion: terraform-helpers@acme-corp-plugins · /plugin

164```

~~165~~

166給定外掛程式的建議在 spinner 提示和工作階段開始通知的組合中最多每三個工作階段出現一次，安裝外掛程式後兩者都不會重複。工作階段開始通知在建議顯示兩次後還會停止出現。

~~167~~

168在 `/plugin` Discover 標籤中，外掛程式會被釘選在其他結果上方，並附帶命名相符信號的註解，例如 `suggested for this directory` 或 `suggested for terraform commands`。Discover 標籤釘選給定的外掛程式一次；稍後的訪問會以正常順序列出它。

~~169~~

170<h2 id="validate-your-marketplace">

171 驗證您的 marketplace

172</h2>

~~173~~

174針對您的 marketplace 目錄執行 `claude plugin validate` 以在發佈前檢查 `relevance` 區塊：

~~175~~

176```

177claude plugin validate ./my-marketplace

178```

~~179~~

180驗證器將 `relevance` 和 `relevance.signals` 下的未知鍵報告為警告，標記不是物件的 `relevance` 值，並拒絕包含配置、連接埠或路徑的 `signals.hosts` 項目。

~~181~~

182<h2 id="see-also">

183 另請參閱

184</h2>

~~185~~

186* [建立和發佈外掛程式 marketplace](/docs/zh-TW/plugin-marketplaces)：建立託管您的外掛程式的 marketplace

187* [從您的 CLI 推薦您的外掛程式](/docs/zh-TW/plugin-hints)：從您自己的 CLI 而不是從 Claude Code 的工作階段信號提示使用者

188* [所有設定](/docs/zh-TW/settings-reference#pluginsuggestionmarketplaces)：`pluginSuggestionMarketplaces` 和 `extraKnownMarketplaces`

plugins.md +0 −527 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# 建立 plugins~~

~~7> 建立自訂 plugins 以使用 skills、agents、hooks 和 MCP servers 擴展 Claude Code。~~

~~9Plugins 讓您使用可在專案和團隊中共享的自訂功能來擴展 Claude Code。本指南涵蓋使用 skills、agents、hooks 和 MCP servers 建立您自己的 plugins。~~

~~11想要安裝現有的 plugins？請參閱[探索和安裝 plugins](/docs/zh-TW/discover-plugins)。如需完整的技術規格，請參閱 [Plugins 參考](/docs/zh-TW/plugins-reference)。~~

~~13<h2 id="when-to-use-plugins-vs-standalone-configuration">~~

~~14 何時使用 plugins 與獨立配置~~

~~15</h2>~~

~~17Claude Code 支援兩種方式來新增自訂 skills、agents 和 hooks：~~

~~19| 方法 | Skill 名稱 | 最適合 |~~

~~20| :---------------------------------------------------------------------------- | :------------------- | :------------------------ |~~

~~21| **獨立**（`.claude/` 目錄） | `/hello` | 個人工作流程、專案特定的自訂、快速實驗 |~~

22| **Plugins**（包含 skills、agents、hooks 或 `.claude-plugin/plugin.json` 資訊清單的自包含目錄） | `/plugin-name:hello` | 與隊友共享、分發到社群、版本化發佈、跨專案重複使用 |

~~24<Tip>~~

~~25 在 `.claude/` 中從獨立配置開始進行快速迭代，然後在準備好共享時[轉換為 plugin](#convert-existing-configurations-to-plugins)。~~

~~26</Tip>~~

~~28<h2 id="quickstart">~~

~~29 快速入門~~

~~30</h2>~~

32本快速入門將引導您建立具有自訂 skill 的 plugin。您將建立一個清單（定義您的 plugin 的配置檔案）、新增一個 skill，並使用 `--plugin-dir` 旗標在本地進行測試。

~~34<h3 id="prerequisites">~~

~~35 先決條件~~

~~36</h3>~~

~~38* Claude Code [已安裝並驗證](/docs/zh-TW/quickstart#step-1-install-claude-code)~~

~~40<h3 id="create-your-first-plugin">~~

~~41 建立您的第一個 plugin~~

~~42</h3>~~

~~44<Steps>~~

~~45 <Step title="建立 plugin 目錄">~~

46 每個 plugin 都位於其自己的目錄中，包含您的 skills、agents 或 hooks，可選地與 `.claude-plugin/plugin.json` 清單並存。位置對於本快速入門並不重要，因為您將在測試步驟中使用 `--plugin-dir` 指向 Claude Code 該目錄。在任何方便的地方建立它，例如暫存資料夾或專案目錄：

~~48 ```bash theme={null}~~

~~49 mkdir my-first-plugin~~

~~50 ```~~

~~52 其餘步驟從父目錄執行，並參考相對於它的路徑，例如 `my-first-plugin/...`。~~

~~53 </Step>~~

~~55 <Step title="建立 plugin 清單">~~

~~56 位於 `.claude-plugin/plugin.json` 的清單檔案定義您的 plugin 的身份：其名稱、描述和版本。Claude Code 使用此中繼資料在 plugin 管理器中顯示您的 plugin。~~

~~58 在您的 plugin 資料夾內建立 `.claude-plugin` 目錄：~~

~~60 ```bash theme={null}~~

~~61 mkdir my-first-plugin/.claude-plugin~~

~~62 ```~~

~~64 然後使用此內容建立 `my-first-plugin/.claude-plugin/plugin.json`：~~

~~66 ```json my-first-plugin/.claude-plugin/plugin.json theme={null}~~

~~67 {~~

~~68 "name": "my-first-plugin",~~

~~69 "description": "A greeting plugin to learn the basics",~~

~~70 "version": "1.0.0",~~

~~71 "author": {~~

~~72 "name": "Your Name"~~

~~73 }~~

~~74 }~~

~~75 ```~~

77 | 欄位 | 用途 |

78 | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

79 | `name` | 唯一識別碼和 skill 命名空間。Skills 以此為前綴（例如 `/my-first-plugin:hello`）。 |

80 | `description` | 在瀏覽或安裝 plugins 時在 plugin 管理器中顯示。 |

81 | `version` | 選用。如果設定，使用者只會在您更新此欄位時收到更新，除了 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)或 plugin [就地載入](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)外；請參閱[版本管理](/docs/zh-TW/plugins-reference#version-management)。如果省略，版本來自[版本管理](/docs/zh-TW/plugins-reference#version-management)中的下一個來源。 |

82 | `author` | 選用。有助於歸屬。 |

~~84 如需 `homepage`、`repository` 和 `license` 等其他欄位，請參閱[完整清單架構](/docs/zh-TW/plugins-reference#plugin-manifest-schema)。~~

~~85 </Step>~~

~~87 <Step title="新增 skill">~~

88 Skills 位於 `skills/` 目錄中。每個 skill 是一個包含 `SKILL.md` 檔案的資料夾。資料夾名稱成為 skill 名稱，以 plugin 的命名空間為前綴（在名為 `my-first-plugin` 的 plugin 中的 `hello/` 建立 `/my-first-plugin:hello`）。

~~90 在您的 plugin 資料夾中建立一個 skill 目錄：~~

~~92 ```bash theme={null}~~

~~93 mkdir -p my-first-plugin/skills/hello~~

~~94 ```~~

~~96 然後使用此內容建立 `my-first-plugin/skills/hello/SKILL.md`：~~

~~98 ```markdown my-first-plugin/skills/hello/SKILL.md theme={null}~~

~~99 ---~~

100 description: Greet the user with a friendly message

101 disable-model-invocation: true

102 ---

~~103~~

104 Greet the user warmly and ask how you can help them today.

105 ```

106 </Step>

~~107~~

108 <Step title="測試您的 plugin">

109 使用 `--plugin-dir` 旗標執行 Claude Code 以載入您的 plugin：

~~110~~

111 ```bash theme={null}

112 claude --plugin-dir ./my-first-plugin

113 ```

~~114~~

115 Claude Code 啟動後，嘗試您的新 skill：

~~116~~

117 ```shell theme={null}

118 /my-first-plugin:hello

119 ```

~~120~~

121 您將看到 Claude 以問候語回應。執行 `/help` 並開啟**自訂命令**標籤，以查看您的 skill 列在 plugin 命名空間下。

~~122~~

123 <Note>

124 **為什麼要命名空間？** Plugin skills 始終被命名空間化（例如 `/my-first-plugin:hello`），以防止多個 plugins 具有相同名稱的 skills 時發生衝突。

~~125~~

126 若要變更命名空間前綴，請更新 `plugin.json` 中的 `name` 欄位。

127 </Note>

128 </Step>

~~129~~

130 <Step title="新增 skill 引數">

131 透過接受使用者輸入使您的 skill 動態化。`$ARGUMENTS` 佔位符會擷取使用者在 skill 名稱後提供的任何文字。

~~132~~

133 更新您的 `SKILL.md` 檔案：

~~134~~

135 ```markdown my-first-plugin/skills/hello/SKILL.md theme={null}

136 ---

137 description: Greet the user with a personalized message

138 ---

~~139~~

140 # Hello Skill

~~141~~

142 Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

143 ```

~~144~~

145 執行 `/reload-plugins` 以取得變更。然後嘗試使用您的名稱執行 skill：

~~146~~

147 ```shell theme={null}

148 /my-first-plugin:hello Alex

149 ```

~~150~~

151 Claude 將按名稱向您問候。如需有關將引數傳遞給 skills 的更多資訊，請參閱 [Skills](/docs/zh-TW/skills#pass-arguments-to-skills)。

152 </Step>

153</Steps>

~~154~~

155<Tip>

156 `--plugin-dir` 旗標對於開發和測試很有用。當您準備好與他人共享您的 plugin 時，請參閱[建立和分發 plugin 市場](/docs/zh-TW/plugin-marketplaces)。

157</Tip>

~~158~~

159<h2 id="develop-a-plugin-in-your-skills-directory">

160 在您的 skills 目錄中開發 plugin

161</h2>

~~162~~

163與其在每次啟動時傳遞 `--plugin-dir`，您可以在您的 skills 目錄中保留一個 plugin，並讓 Claude Code 自動載入它。`claude plugin init` 會為您建立一個：

~~164~~

165```bash theme={null}

166claude plugin init my-tool

167```

~~168~~

169這會建立 `~/.claude/skills/my-tool/`，其中包含 `.claude-plugin/plugin.json` 清單和一個入門 `SKILL.md`。在下一個工作階段中，它會以 `my-tool@skills-dir` 的形式載入，無需市場或安裝步驟。

~~170~~

171如需自動載入規則、個人與專案範圍、工作區信任要求，以及如何更新或移除一個，請參閱 [Skills-directory plugins](/docs/zh-TW/plugins-reference#skills-directory-plugins)。

~~172~~

173<h2 id="plugin-structure-overview">

174 Plugin 結構概述

175</h2>

~~176~~

177您已建立了具有 skill 的 plugin，但 plugins 可以包含更多內容：自訂 agents、hooks、MCP servers、LSP servers 和背景監視器。

~~178~~

179<Warning>

180 **常見錯誤**：不要將 `commands/`、`agents/`、`skills/` 或 `hooks/` 放在 `.claude-plugin/` 目錄內。只有 `plugin.json` 應該在 `.claude-plugin/` 內。所有其他目錄必須位於 plugin 根目錄級別。

~~181~~

182 plugin 根目錄是個別 plugin 自己的目錄，例如來自[快速入門](#quickstart)的 `my-first-plugin/`。它永遠不是 `~/.claude/`。例如，Claude Code 不會讀取放在 `~/.claude/.mcp.json` 的 `.mcp.json`。

183</Warning>

~~184~~

185| 目錄 | 位置 | 用途 |

186| :---------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |

187| `.claude-plugin/` | Plugin 根目錄 | 包含 `plugin.json` 清單（如果元件使用預設位置，則為選用） |

188| `skills/` | Plugin 根目錄 | 作為 `<name>/SKILL.md` 目錄的 Skills |

189| `commands/` | Plugin 根目錄 | 作為平面 Markdown 檔案的 Skills。新 plugins 請使用 `skills/` |

190| `agents/` | Plugin 根目錄 | 自訂 agent 定義 |

191| `hooks/` | Plugin 根目錄 | `hooks.json` 中的事件處理程式 |

192| `.mcp.json` | Plugin 根目錄 | MCP server 配置 |

193| `.lsp.json` | Plugin 根目錄 | 用於程式碼智慧的 LSP server 配置 |

194| `monitors/` | Plugin 根目錄 | `monitors.json` 中的背景監視器配置 |

195| `bin/` | Plugin 根目錄 | 在啟用 plugin 時新增到 Bash tool 的 `PATH` 的可執行檔。您無法在[透過 claude.ai 組織設定分發的 plugin](/docs/zh-TW/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory)中包含此目錄 |

196| `settings.json` | Plugin 根目錄 | 啟用 plugin 時應用的預設[設定](/docs/zh-TW/settings) |

~~197~~

198只要 plugin 恰好包含一個 skill，就可以直接在 plugin 根目錄放置 `SKILL.md`，而不需要建立 `skills/` 目錄。Claude Code 會將其載入為單一 skill，並使用 frontmatter 的 `name` 欄位作為叫用名稱。對於可能成長為多個 skill 的 plugins，請使用 `skills/` 配置。

~~199~~

200<h2 id="develop-more-complex-plugins">

201 開發更複雜的外掛程式

202</h2>

~~203~~

204一旦您熟悉了基本外掛程式，您可以建立更複雜的擴充功能。

~~205~~

206<h3 id="add-skills-to-your-plugin">

207 將 Skills 新增至您的外掛程式

208</h3>

~~209~~

210外掛程式可以包含 [Agent Skills](/docs/zh-TW/skills) 來擴展 Claude 的功能。Skills 是由模型呼叫的：Claude 會根據任務背景自動使用它們。

~~211~~

212在您的外掛程式根目錄新增一個 `skills/` 目錄，其中包含包含 `SKILL.md` 檔案的 Skill 資料夾：

~~213~~

214```text theme={null}

215my-plugin/

216├── .claude-plugin/

217│ └── plugin.json

218└── skills/

219 └── code-review/

220 └── SKILL.md

221```

~~222~~

223每個 `SKILL.md` 包含 YAML frontmatter 和說明。包含一個 `description`，以便 Claude 知道何時使用該 skill：

~~224~~

225```yaml theme={null}

226description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.

~~227~~

228When reviewing code, check for:

2291. Code organization and structure

2302. Error handling

2313. Security concerns

2324. Test coverage

233```

~~234~~

235安裝外掛程式後，檢查安裝摘要：如果它報告 `Run /reload-plugins to activate.`，請參閱 [Apply plugin changes without restarting](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 以在您目前的工作階段中載入 Skills。如需完整的 Skill 編寫指南（包括漸進式揭露和工具限制），請參閱 [Agent Skills](/docs/zh-TW/skills)。

~~236~~

237<h3 id="add-lsp-servers-to-your-plugin">

238 將 LSP 伺服器新增至您的外掛程式

239</h3>

~~240~~

241<Tip>

242 對於 TypeScript、Python 和 Rust 等常見語言，請從官方市集安裝預先建立的 LSP 外掛程式。只有在您需要支援尚未涵蓋的語言時，才建立自訂 LSP 外掛程式。

243</Tip>

~~244~~

245LSP（Language Server Protocol）外掛程式為 Claude 提供即時程式碼智慧。如果您需要支援沒有官方 LSP 外掛程式的語言，您可以透過將 `.lsp.json` 檔案新增至您的外掛程式來建立自己的：

~~246~~

247```json .lsp.json theme={null}

248{

249 "go": {

250 "command": "gopls",

251 "args": ["serve"],

252 "extensionToLanguage": {

253 ".go": "go"

254 }

255 }

256}

257```

~~258~~

259安裝您外掛程式的使用者必須在其機器上安裝語言伺服器二進位檔。

~~260~~

261若要確認伺服器啟動，請啟動啟用外掛程式的 Claude Code 並檢查 `/plugin` 錯誤標籤：無法啟動的語言伺服器會出現在那裡，例如當二進位檔未安裝時出現 `Executable not found in $PATH`。具有無效設定的項目會被跳過；執行 `claude --debug` 以查看原因。

~~262~~

263如需完整的 LSP 設定選項，請參閱 [LSP servers](/docs/zh-TW/plugins-reference#lsp-servers)。

~~264~~

265<h3 id="add-background-monitors-to-your-plugin">

266 將背景監視器新增至您的外掛程式

267</h3>

~~268~~

269背景監視器讓您的外掛程式在背景中監視日誌、檔案或外部狀態，並在事件到達時通知 Claude。Claude Code 在外掛程式啟用時自動啟動每個監視器，因此您不需要指示 Claude 啟動監視。

~~270~~

271在外掛程式根目錄新增一個 `monitors/monitors.json` 檔案，其中包含監視器項目的陣列：

~~272~~

273```json monitors/monitors.json theme={null}

274[

275 {

276 "name": "error-log",

277 "command": "tail -F ./logs/error.log",

278 "description": "Application error log"

279 }

280]

281```

~~282~~

283來自 `command` 的每個 stdout 行都會在工作階段期間作為通知傳遞給 Claude。如需完整的結構描述（包括 `when` 觸發器和變數替換），請參閱 [Monitors](/docs/zh-TW/plugins-reference#monitors)。

~~284~~

285<h3 id="ship-default-settings-with-your-plugin">

286 使用您的外掛程式提供預設設定

287</h3>

~~288~~

289外掛程式可以在外掛程式根目錄包含一個 `settings.json` 檔案，以在啟用外掛程式時套用預設設定。目前僅支援 `agent` 和 `subagentStatusLine` 鍵。

~~290~~

291設定 `agent` 會啟用外掛程式的其中一個 [custom agents](/docs/zh-TW/sub-agents) 作為主執行緒，套用其系統提示、工具限制和模型。這讓外掛程式在啟用時預設改變 Claude Code 的行為方式。

~~292~~

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

294{

295 "agent": "security-reviewer"

296}

297```

~~298~~

299此範例啟用在外掛程式的 `agents/` 目錄中定義的 `security-reviewer` 代理。來自 `settings.json` 的設定優先於在 `plugin.json` 中宣告的 `settings`。未知的鍵會被無聲地忽略。

~~300~~

301<h3 id="organize-complex-plugins">

302 組織複雜的外掛程式

303</h3>

~~304~~

305對於具有許多元件的外掛程式，請按功能組織您的目錄結構。如需完整的目錄配置和組織模式，請參閱 [Plugin directory structure](/docs/zh-TW/plugins-reference#plugin-directory-structure)。

~~306~~

307<h3 id="test-your-plugins-locally">

308 在本機測試您的外掛程式

309</h3>

~~310~~

311使用 `--plugin-dir` 旗標在開發期間測試外掛程式。這會直接載入您的外掛程式，無需安裝。

~~312~~

313```bash theme={null}

314claude --plugin-dir ./my-plugin

315```

~~316~~

317該旗標也接受外掛程式目錄的 `.zip` 封存。

~~318~~

319```bash theme={null}

320claude --plugin-dir ./my-plugin.zip

321```

~~322~~

323當 `--plugin-dir` 外掛程式的名稱與已安裝的市集外掛程式相同時，本機副本在該工作階段中優先。這讓您可以測試已安裝的外掛程式的變更，而無需先卸載它。例外是受管設定強制啟用或強制停用的外掛程式：`--plugin-dir` 無法覆蓋這些。

~~324~~

325當您對外掛程式進行變更時，執行 `/reload-plugins` 以在不重新啟動的情況下取得更新。這會重新載入外掛程式、skills、代理、hooks、外掛程式 MCP 伺服器和外掛程式 LSP 伺服器；在沒有互動式終端的工作階段中，外掛程式 MCP 伺服器變更 [等待您的下一個工作階段](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)。測試您的外掛程式元件：

~~326~~

327* 使用 `/plugin-name:skill-name` 嘗試您的 skills

328* 檢查代理是否出現在 `/context` 下的 Custom Agents 中，或透過其範圍名稱 @-提及一個

329* 觸發每個 hook 匹配的事件，例如要求 Claude 編輯檔案以進行 `PostToolUse` hook，並確認其效果。Claude Code 會記錄哪些 hooks 匹配、其結束代碼和其輸出在 [debug log](/docs/zh-TW/hooks#debug-hooks) 中

~~330~~

331<Tip>

332 您可以透過多次指定旗標來一次載入多個外掛程式：

~~333~~

334 ```bash theme={null}

335 claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

336 ```

~~337~~

338 若要測試外掛程式及其依賴的外掛程式，請參閱 [Test a plugin and its dependency locally](/docs/zh-TW/plugin-dependencies#test-a-plugin-and-its-dependency-locally)。

339</Tip>

~~340~~

341若要在無法新增旗標的工作階段中載入外掛程式，請改為在 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-TW/env-vars#variables) 環境變數中列出其絕對路徑。Claude Code 會將每個路徑載入為載入 `--plugin-dir` 路徑的方式。這些外掛程式會在您使用 `--plugin-dir` 傳遞的任何外掛程式之外載入。[專案和本機設定無法設定此變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)。`CLAUDE_CODE_PLUGIN_DIRS` 需要 Claude Code v2.1.280 或更新版本。

~~342~~

343使用 `--plugin-dir` 嘗試外掛程式可以告訴您它是否能夠運作。若要找出 Claude 實際上多常使用它並獲得正確的結果，請使用 [`claude plugin eval`](/docs/zh-TW/plugin-evals) 針對一組測試提示執行它。每個提示會在載入和不載入外掛程式的情況下執行多次，因此您可以看到外掛程式的貢獻，並在您變更它或新模型發佈時捕捉迴歸。

~~344~~

345若要從一個位置載入多個外掛程式，請傳遞包含它們的資料夾，例如 `--plugin-dir ./plugins`。載入外掛程式資料夾需要 Claude Code v2.1.265 或更新版本。Claude Code 讀取資料夾的頂層以決定哪些外掛程式載入，在互動式工作階段中，它也會監視資料夾以進行後續變更：

~~346~~

347* **載入的內容**：如果資料夾的頂層沒有資訊清單或外掛程式元件，Claude Code 會將其視為外掛程式資料夾。每個具有 `.claude-plugin/plugin.json` 資訊清單的直接子資料夾都會作為單獨的外掛程式載入。Claude Code 會跳過資料夾中的所有其他內容，而不報告錯誤，包括沒有資訊清單的外掛程式。

348* **互動式工作階段期間的變更**：您新增的子資料夾在其資訊清單就位後會作為新外掛程式載入，當您移除子資料夾時，其外掛程式會卸載。Claude Code 會為每個變更在工作階段中列印一行。如果在對話中途套用變更會 [使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，Claude Code 會保留它，該行會說執行 `/reload-plugins` 以套用它。

~~349~~

350若要測試已封裝為 `.zip` 封存並託管在 URL 上的外掛程式（例如 CI 建置成品），請改用 `--plugin-url`。Claude Code 在啟動時擷取封存並僅為該工作階段載入它。如果 Claude Code 無法擷取封存或封存無效，它會在沒有外掛程式的情況下啟動，並記錄您可以在 `/plugin` 管理員的 **Errors** 標籤中檢閱的外掛程式載入錯誤。與任何外掛程式來源相同的 [trust considerations](/docs/zh-TW/discover-plugins#security) 適用：只將此旗標指向您控制或信任的封存。

~~351~~

352若要載入多個外掛程式，請為每個 URL 重複該旗標：

~~353~~

354```bash theme={null}

355claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

356```

~~357~~

358或將空格分隔的 URL 作為一個引用的引數傳遞：

~~359~~

360```bash theme={null}

361claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

362```

~~363~~

364<h3 id="debug-plugin-issues">

365 偵錯外掛程式問題

366</h3>

~~367~~

368如果您的外掛程式未如預期運作：

~~369~~

3701. **檢查結構**：確保您的目錄位於外掛程式根目錄，而不是在 `.claude-plugin/` 內

3712. **個別測試元件**：分別檢查每個 skill、代理和 hook

3723. **使用驗證和偵錯工具**：請參閱 [Debugging and development tools](/docs/zh-TW/plugins-reference#debugging-and-development-tools) 以取得 CLI 命令和疑難排解技術

~~373~~

374<h3 id="share-your-plugins">

375 分享您的外掛程式

376</h3>

~~377~~

378當您的外掛程式準備好分享時：

~~379~~

3801. **新增文件**：包含一個 `README.md`，其中包含安裝和使用說明

3812. **選擇版本控制策略**：決定是否設定明確的 `version` 或依賴 [version management](/docs/zh-TW/plugins-reference#version-management) 中描述的後備。

3823. **建立或使用市集**：透過 [plugin marketplaces](/docs/zh-TW/plugin-marketplaces) 進行分發以進行安裝

3834. **與他人測試**：在更廣泛的分發之前，讓團隊成員測試外掛程式

~~384~~

385一旦您的外掛程式在市集中，其他人可以使用 [Discover and install plugins](/docs/zh-TW/discover-plugins) 中的說明安裝它。若要將外掛程式保持在您的團隊內部，請在 [private repository](/docs/zh-TW/plugin-marketplaces#private-repositories) 中託管市集。

~~386~~

387<h3 id="submit-your-plugin-to-the-community-marketplace">

388 將您的外掛程式提交至社群市集

389</h3>

~~390~~

391Anthropic 為 Claude Code 外掛程式維護兩個公開市集：

~~392~~

393* **`claude-plugins-official`**：由 Anthropic 維護的精選外掛程式集。Claude Code 在您第一次以互動方式啟動 Claude Code 時自動註冊它。如果您在該首次互動啟動之前以非互動方式執行 Claude Code，或 [marketplace policy](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) 阻止了較早的嘗試，請使用 `claude plugin marketplace add anthropics/claude-plugins-official` 自行註冊。

394* **`claude-community`**：公開社群市集，第三方提交在審查後會進入該市集。使用者使用 `/plugin marketplace add anthropics/claude-plugins-community` 新增它，並將其安裝為 `@claude-community`。

~~395~~

396若要提交您的外掛程式以進行社群市集審查，請使用其中一個應用程式內表單：

~~397~~

398* **claude.ai**：[claude.ai/admin-settings/directory/submissions/plugins/new](https://claude.ai/admin-settings/directory/submissions/plugins/new)

399* **Console**：[platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)

~~400~~

401claude.ai 表單需要 Team 或 Enterprise 組織和目錄管理存取權；組織擁有者預設具有此存取權。不屬於 Team 或 Enterprise 組織的個別作者可以改用 Console 表單。

~~402~~

403在提交之前，在本機執行 `claude plugin validate ./your-plugin`，將 `./your-plugin` 替換為您的外掛程式目錄的路徑。審查管道對每個提交執行相同的檢查，以及自動安全篩選。驗證通過時，Claude Code 會列印 `✔ Validation passed`，或如果有警告，則列印 `✔ Validation passed with warnings`。警告不會導致驗證失敗；新增 `--strict` 以將它們視為錯誤。

~~404~~

405已核准的外掛程式會固定到 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 目錄中的特定提交 SHA，CI 會在您推送新提交至您的儲存庫時自動提升該固定。公開目錄每晚從審查管道同步，因此核准和您的外掛程式出現在 `marketplace.json` 之間可能會有延遲。若要檢查您的外掛程式是否已可安裝，請在 [community catalog](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) 中搜尋其名稱。

~~406~~

407官方市集 `claude-plugins-official` 是單獨精選的。Anthropic 自行決定要包含哪些外掛程式。沒有申請流程，提交表單不會將外掛程式新增至官方市集。

~~408~~

409如果 Anthropic 在官方市集中列出您的外掛程式，您的 CLI 可以提示 Claude Code 使用者安裝它。請參閱 [Recommend your plugin from your CLI](/docs/zh-TW/plugin-hints)。

~~410~~

411<h2 id="convert-existing-configurations-to-plugins">

412 將現有配置轉換為 plugins

413</h2>

~~414~~

415如果您已經在 `.claude/` 目錄中有 skills 或 hooks，您可以將它們轉換為 plugin，以便更輕鬆地共享和分發。

~~416~~

417<h3 id="migration-steps">

418 遷移步驟

419</h3>

~~420~~

421<Steps>

422 <Step title="建立 plugin 結構">

423 在您的專案根目錄中建立新的 plugin 目錄，與現有的 `.claude/` 資料夾並排放置，以便下一步中的相對 `cp` 路徑能夠解析：

~~424~~

425 ```bash theme={null}

426 mkdir -p my-plugin/.claude-plugin

427 ```

~~428~~

429 在 `my-plugin/.claude-plugin/plugin.json` 建立清單檔案：

~~430~~

431 ```json my-plugin/.claude-plugin/plugin.json theme={null}

432 {

433 "name": "my-plugin",

434 "description": "Migrated from standalone configuration",

435 "version": "1.0.0"

436 }

437 ```

438 </Step>

~~439~~

440 <Step title="複製您現有的檔案">

441 將您現有的每個配置目錄複製到 plugin 根目錄。您可能沒有全部三個：如果目錄不存在，`cp` 會列印 `No such file or directory` 並且不複製任何內容，因此請跳過該命令或忽略錯誤。

~~442~~

443 ```bash theme={null}

444 cp -r .claude/commands my-plugin/

~~445~~

446 cp -r .claude/agents my-plugin/

~~447~~

448 cp -r .claude/skills my-plugin/

449 ```

~~450~~

451 您的 plugin 現在包含您在 `.claude/` 下擁有的目錄副本。執行 `ls my-plugin` 以確認：您應該看到您複製的每個目錄。

452 </Step>

~~453~~

454 <Step title="遷移 hooks">

455 如果您在設定中有 hooks，請建立一個 hooks 目錄：

~~456~~

457 ```bash theme={null}

458 mkdir my-plugin/hooks

459 ```

~~460~~

461 使用您的 hooks 配置建立 `my-plugin/hooks/hooks.json`。從您的 `.claude/settings.json` 或 `settings.local.json` 複製 `hooks` 物件，因為格式相同。命令在 stdin 上接收 hook 輸入作為 JSON，因此使用 `jq` 來提取檔案路徑：

~~462~~

463 ```json my-plugin/hooks/hooks.json theme={null}

464 {

465 "hooks": {

466 "PostToolUse": [

467 {

468 "matcher": "Write|Edit",

469 "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]

470 }

471 ]

472 }

473 }

474 ```

475 </Step>

~~476~~

477 <Step title="測試您遷移的 plugin">

478 載入您的 plugin 以驗證一切正常：

~~479~~

480 ```bash theme={null}

481 claude --plugin-dir ./my-plugin

482 ```

~~483~~

484 測試每個元件：執行您的命令、檢查 agents 是否出現在 `/context` 中，並觸發每個 hook 符合的事件以確認其效果。Claude Code 會在[除錯日誌](/docs/zh-TW/hooks#debug-hooks)中記錄哪些 hooks 符合以及它們如何退出。

485 </Step>

486</Steps>

~~487~~

488<h3 id="what-changes-when-migrating">

489 遷移時的變更

490</h3>

~~491~~

492| 獨立（`.claude/`） | Plugin |

493| :----------------------- | :--------------------------- |

494| 僅在一個專案中可用 | 可以透過市場共享 |

495| `.claude/commands/` 中的檔案 | `plugin-name/commands/` 中的檔案 |

496| `settings.json` 中的 Hooks | `hooks/hooks.json` 中的 Hooks |

497| 必須手動複製以共享 | 使用 `/plugin install` 安裝 |

~~498~~

499<Note>

500 遷移後，從 `.claude/` 中移除原始檔案以避免重複。專案和使用者 `.claude/agents/` 定義會覆蓋同名的 plugin agents，因此 plugin 版本只有在移除原始檔案後才會生效。Plugin skills 會被命名為 `/plugin-name:skill-name`，因此原始的 `/skill-name` 和 plugin 副本都會保持可用，而不是其中一個覆蓋另一個。

501</Note>

~~502~~

503<h2 id="next-steps">

504 後續步驟

505</h2>

~~506~~

507現在您已了解 Claude Code 的 plugin 系統，以下是針對不同目標的建議路徑：

~~508~~

509<h3 id="for-plugin-users">

510 對於 plugin 使用者

511</h3>

~~512~~

513* [探索和安裝 plugins](/docs/zh-TW/discover-plugins)：瀏覽市場並安裝 plugins

514* [配置團隊市場](/docs/zh-TW/discover-plugins#configure-team-marketplaces)：為您的團隊設定儲存庫級別的 plugins

~~515~~

516<h3 id="for-plugin-developers">

517 對於 plugin 開發人員

518</h3>

~~519~~

520* [使用 evals 測試 plugins](/docs/zh-TW/plugin-evals)：測量您的 plugin 所做的變更並在 CI 上進行把關

521* [建立和分發市場](/docs/zh-TW/plugin-marketplaces)：打包和共享您的 plugins

522* [Plugins 參考](/docs/zh-TW/plugins-reference)：完整的技術規格

523* 深入探討特定的 plugin 元件：

524 * [Skills](/docs/zh-TW/skills)：skill 開發詳情

525 * [Subagents](/docs/zh-TW/sub-agents)：agent 配置和功能

526 * [Hooks](/docs/zh-TW/hooks)：事件處理和自動化

527 * [MCP](/docs/zh-TW/mcp)：外部工具整合

plugins-reference.md +0 −1645 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Plugins 參考~~

~~7> Claude Code plugin 系統的完整技術參考，包括 schemas、CLI 命令和元件規格。~~

~~9<Tip>~~

10 想要安裝 plugins？請參閱 [探索和安裝 plugins](/docs/zh-TW/discover-plugins)。如需建立 plugins，請參閱 [Plugins](/docs/zh-TW/plugins)。如需發佈 plugins，請參閱 [Plugin 市場](/docs/zh-TW/plugin-marketplaces)。

~~11</Tip>~~

~~13**plugin** 是一個自包含的目錄，包含擴展 Claude Code 功能的元件。Plugin 元件包括 skills、agents、hooks、MCP servers、LSP servers 和 monitors。~~

~~15<h2 id="plugin-components-reference">~~

~~16 Plugin 元件參考~~

~~17</h2>~~

~~19<h3 id="skills">~~

~~20 Skills~~

~~21</h3>~~

~~23Plugins 會將 skills 新增至 Claude Code，建立 `/name` 快捷方式供您或 Claude 叫用。~~

~~25**位置**：plugin 根目錄中的 `skills/` 或 `commands/` 目錄，或 plugin 根目錄中的單一 `SKILL.md` 檔案~~

~~27**檔案格式**：Skills 是包含 `SKILL.md` 的目錄；commands 是簡單的 markdown 檔案~~

~~29**Skill 結構**：~~

~~31```text theme={null}~~

~~32skills/~~

~~33├── pdf-processor/~~

~~34│ ├── SKILL.md~~

~~35│ ├── reference.md (optional)~~

~~36│ └── scripts/ (optional)~~

~~37└── code-reviewer/~~

~~38 └── SKILL.md~~

~~39```~~

~~41當 plugin 安裝時，Skills 和 commands 會自動被發現。~~

43如果 plugin 沒有 `skills/` 目錄且沒有 `skills` manifest 欄位，plugin 根目錄中的 `SKILL.md` 會被載入為單一 skill。設定 frontmatter `name` 欄位以控制 skill 的叫用名稱。沒有設定的話，Claude Code 會回退到安裝目錄名稱。對於 [複製到快取中](#plugin-caching-and-file-resolution) 的 plugin，該名稱是一個在每次更新時都會改變的版本字串。對於提供多個 skills 的 plugins，請使用上面所示的 `skills/` 目錄配置。

45在 plugin skills 和 commands 中，Boolean frontmatter 欄位（例如 `disable-model-invocation`）接受 `yes`、`no`、`on`、`off`、`1` 和 `0`（任何字母大小寫），以及 `true` 和 `false`。在 v2.1.218 之前，Claude Code 只識別 `true` 和 `false`。

~~47如需完整詳細資訊，請參閱 [Skills](/docs/zh-TW/skills)。~~

~~49<h3 id="agents">~~

~~50 Agents~~

~~51</h3>~~

~~53Plugins 可以提供專門的子代理程式來執行特定任務，Claude 可以在適當時自動叫用。~~

~~55**位置**：plugin 根目錄中的 `agents/` 目錄~~

~~57**檔案格式**：描述代理程式功能的 Markdown 檔案~~

~~59**Agent 結構**：~~

~~61```markdown theme={null}~~

~~62name: agent-name~~

~~63description: What this agent specializes in and when Claude should invoke it~~

~~64model: sonnet~~

~~65effort: medium~~

~~66maxTurns: 20~~

~~67disallowedTools: Write, Edit~~

~~69Detailed system prompt for the agent describing its role, expertise, and behavior.~~

~~70```~~

~~72<h4 id="plugin-agent-frontmatter">~~

~~73 Plugin agent frontmatter~~

~~74</h4>~~

76Plugin agent 檔案使用與 [subagent 檔案相同的 frontmatter 欄位](/docs/zh-TW/sub-agents#supported-frontmatter-fields)，除了當 agent 來自 plugin 時，Claude Code 只支援其中一些：

78* **支援**：`name`、`description`、`model`、`effort`、`maxTurns`、`tools`、`disallowedTools`、`skills`、`memory`、`background`、`omitClaudeMd`、`isolation`、`color` 和 `experimental`。唯一有效的 `isolation` 值是 `"worktree"`。

79* **基於安全考量不支援**：`hooks`、`mcpServers` 和 `permissionMode`。Claude Code 在從 plugin 載入 agent 時會忽略這些。若要使用它們，請將 agent 檔案複製到 `.claude/agents/` 或 `~/.claude/agents/`。

~~80* **不支援**：`initialPrompt`。~~

82您可以將 plugin agent 檔案放在 `agents/` 的子資料夾中。Claude Code [會遞迴載入它們](/docs/zh-TW/sub-agents#choose-the-subagent-scope)，並將 plugin 名稱、每個子資料夾名稱和檔案名稱用冒號連接以形成 agent 的範圍名稱。例如，名為 `my-plugin` 的 plugin 中的 `agents/review/security.md` 會載入為 `my-plugin:review:security`。兩個設定會改變該名稱：

~~84* Frontmatter `name`：它只替換檔案名稱，所以 `agents/review/security.md` 中的 `name: audit` 會載入為 `my-plugin:review:audit`~~

85* Manifest [`agents`](#component-path-fields) 欄位：您在其中列出的檔案會載入而不含子資料夾名稱，所以 `"agents": "./custom/review/security.md"` 會載入為 `my-plugin:security`

~~87Claude Code 會載入 plugin agent，即使其 frontmatter 沒有 `name` 或無法解析：~~

~~89* 沒有 `name`：Claude Code 會根據檔案名稱為 agent 命名，所以名為 `my-plugin` 的 plugin 中的 `agents/reviewer.md` 會載入為 `my-plugin:reviewer`~~

~~90* 無法解析的 Frontmatter：Claude Code 會根據檔案名稱為 agent 命名，使用 `Agent from my-plugin plugin` 作為其描述，並忽略檔案中的每個欄位~~

~~92相比之下，Claude Code 會跳過其 frontmatter 沒有 `name` 或無法解析的專案、使用者或受管理的 agent 檔案。~~

94若要找到 plugin 預設 `agents/` 目錄中 frontmatter 無法解析的檔案，請執行 `claude plugin validate`。您傳遞的路徑取決於 plugin 是否有 manifest，兩個範例都使用 `./my-plugin` 作為 plugin 目錄：

~~96* 具有 manifest 的 plugin：`claude plugin validate ./my-plugin`~~

~~97* 沒有 manifest 的 plugin：`claude plugin validate ./my-plugin/agents`。需要 Claude Code v2.1.233 或更新版本。~~

~~99Agents 會在 [@-mention 類型提前](/docs/zh-TW/sub-agents#invoke-subagents-explicitly) 中以其範圍名稱（例如 `my-plugin:code-reviewer`）出現，一旦 plugin 被啟用。~~

~~100~~

101如需完整詳細資訊，請參閱 [Subagents](/docs/zh-TW/sub-agents)。

~~102~~

103<h3 id="hooks">

104 Hooks

105</h3>

~~106~~

107Plugins 可以提供事件處理程式，自動回應 Claude Code 事件。

~~108~~

109**位置**：plugin 根目錄中的 `hooks/hooks.json`，或 plugin.json 中的內聯

~~110~~

111**格式**：具有事件匹配器和動作的 JSON 設定

~~112~~

113`hooks/hooks.json` 可以攜帶頂層 `$schema` 金鑰，該金鑰命名 JSON Schema URL 以供編輯器自動完成和驗證。Claude Code 在載入時會忽略該金鑰。

~~114~~

115**Hook 設定**：

~~116~~

117```json theme={null}

118{

119 "hooks": {

120 "PostToolUse": [

121 {

122 "matcher": "Write|Edit",

123 "hooks": [

124 {

125 "type": "command",

126 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"

127 }

128 ]

129 }

130 ]

131 }

132}

133```

~~134~~

135Plugin hooks 回應與 [使用者定義的 hooks](/docs/zh-TW/hooks) 相同的生命週期事件：

~~136~~

137| 事件 | 何時觸發 |

138| :-------------------- | :-------------------------------------------------------------------------------------------------------------------- |

139| `SessionStart` | 當工作階段開始或繼續時 |

140| `Setup` | 當您使用 `--init-only` 啟動 Claude Code，或在 `-p` 模式中使用 `--init` 或 `--maintenance` 時。用於 CI 或指令碼中的一次性準備 |

141| `UserPromptSubmit` | 當您提交提示詞時，在 Claude 處理之前 |

142| `UserPromptExpansion` | 當使用者輸入的命令擴展為提示詞時，在到達 Claude 之前。可以阻止擴展 |

143| `PreToolUse` | 在工具呼叫執行之前。可以阻止它 |

144| `PermissionRequest` | 當工具呼叫需要權限決定時 |

145| `PermissionDenied` | 當自動模式拒絕工具呼叫時，包括沒有分類器判決的拒絕。使用 JSON `hookSpecificOutput.retry: true` 告訴模型它可能重試被拒絕的工具呼叫。Claude Code 在分類器未產生判決時忽略 `retry` |

146| `PostToolUse` | 在工具呼叫成功後 |

147| `PostToolUseFailure` | 在工具呼叫失敗後 |

148| `PostToolBatch` | 在完整的平行工具呼叫批次解決後，在下一個模型呼叫之前 |

149| `Notification` | 當 Claude Code 傳送通知時 |

150| `MessageDisplay` | 在助手訊息文字顯示時 |

151| `SubagentStart` | 當子代理被生成時 |

152| `SubagentStop` | 當子代理完成時 |

153| `TaskCreated` | 當透過 `TaskCreate` 建立任務時 |

154| `TaskCompleted` | 當任務被標記為已完成時 |

155| `Stop` | 當 Claude 完成回應時 |

156| `StopFailure` | 當回合因 API 錯誤而結束時 |

157| `TeammateIdle` | 當[代理團隊](/docs/zh-TW/agent-teams)隊友即將閒置時 |

158| `InstructionsLoaded` | 當 CLAUDE.md 或 `.claude/rules/*.md` 檔案被載入到上下文時。在工作階段開始時以及在工作階段期間延遲載入檔案時觸發 |

159| `ConfigChange` | 當設定檔在工作階段期間變更時 |

160| `CwdChanged` | 當工作目錄變更時，例如當 Claude 執行 `cd` 命令時。適用於使用 direnv 等工具進行反應式環境管理 |

161| `DirectoryAdded` | 當工作目錄在工作階段中期透過 `/add-dir` 或 SDK `register_repo_root` 控制請求新增時 |

162| `FileChanged` | 當監視的檔案在磁碟上變更時。`matcher` 欄位指定要監視的檔案名稱 |

163| `WorktreeCreate` | 當透過 `--worktree`、`isolation: "worktree"` 建立 worktree 時，或用於背景工作階段時。取代預設的 git 行為 |

164| `WorktreeRemove` | 當在工作階段結束時、子代理完成時或您刪除背景工作階段時移除 worktree 時 |

165| `PreCompact` | 在上下文壓縮之前 |

166| `PostCompact` | 在上下文壓縮完成後 |

167| `PreModelSwitch` | 在 Claude Code 應用您或用戶端要求的模型切換之前。可以阻止切換 |

168| `PostModelSwitch` | 在工作階段的模型變更後，包括 Claude Code 自行進行的變更，例如當您繼續工作階段時恢復模型 |

169| `Elicitation` | 當 MCP 伺服器在工具呼叫期間要求使用者輸入時 |

170| `ElicitationResult` | 在使用者回應 MCP 引出後，在回應傳送回伺服器之前 |

171| `SessionEnd` | 當工作階段終止時 |

~~172~~

173**Hook 類型**：

~~174~~

175* `command`：執行 shell 命令或指令碼

176* `http`：將事件 JSON 作為 POST 請求傳送到 URL

177* `mcp_tool`：在已設定的 [MCP server](/docs/zh-TW/mcp) 上呼叫工具

178* `prompt`：使用 LLM 評估提示（使用 `$ARGUMENTS` 預留位置作為內容）

179* `agent`：執行具有工具的代理程式驗證器以進行複雜驗證任務

~~180~~

181針對 plugin 自己的 [bundled MCP server](#mcp-servers) 的 Hooks 必須使用其範圍名稱。工具匹配器和 `if` 欄位採用範圍工具名稱 `mcp__plugin_<plugin-name>_<server-name>__<tool>`，而 `mcp_tool` hook 的 `server` 欄位採用 `plugin:<plugin-name>:<server-name>`。針對裸伺服器金鑰編寫的匹配器永遠不會觸發。請參閱 [Match MCP tools](/docs/zh-TW/hooks#match-mcp-tools) 和 [Plugin-provided MCP servers](/docs/zh-TW/mcp#plugin-provided-mcp-servers)。

~~182~~

183<h3 id="mcp-servers">

184 MCP servers

185</h3>

~~186~~

187Plugins 可以捆綁 Model Context Protocol (MCP) 伺服器，以將 Claude Code 與外部工具和服務連接。

~~188~~

189**位置**：plugin 根目錄中的 `.mcp.json`，或 plugin.json 中的內聯

~~190~~

191**格式**：標準 MCP 伺服器設定

~~192~~

193**MCP 伺服器設定**：

~~194~~

195```json theme={null}

196{

197 "mcpServers": {

198 "plugin-database": {

199 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",

200 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],

201 "env": {

202 "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"

203 }

204 },

205 "plugin-api-client": {

206 "command": "npx",

207 "args": ["@company/mcp-server", "--plugin-mode"]

208 }

209 }

210}

211```

~~212~~

213**整合行為**：

~~214~~

215* Plugin MCP 伺服器在 plugin 啟用時自動啟動

216* 伺服器在 Claude 的工具組中顯示為標準 MCP 工具

217* Plugin 伺服器可以獨立於使用者 MCP 伺服器進行設定

218* 如果您在工作階段中執行 [`/reload-plugins`](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)，Claude Code 會保持其設定未變更的伺服器的即時連接

~~219~~

220<h3 id="lsp-servers">

221 LSP servers

222</h3>

~~223~~

224<Tip>

225 尋找使用 LSP plugins？從官方 marketplace 安裝它們：在 `/plugin` Discover 標籤中搜尋「lsp」。本節記錄如何為官方 marketplace 未涵蓋的語言建立 LSP plugins。

226</Tip>

~~227~~

228Plugins 可以提供 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) 伺服器，以在處理您的程式碼庫時為 Claude 提供 [即時程式碼智慧](/docs/zh-TW/discover-plugins#code-intelligence)。

~~229~~

230**位置**：plugin 根目錄中的 `.lsp.json`，或 `plugin.json` 中的內聯

~~231~~

232**格式**：將語言伺服器名稱對應到其設定的 JSON 設定

~~233~~

234**`.lsp.json` 檔案格式**：

~~235~~

236```json theme={null}

237{

238 "go": {

239 "command": "gopls",

240 "args": ["serve"],

241 "extensionToLanguage": {

242 ".go": "go"

243 }

244 }

245}

246```

~~247~~

248**在 `plugin.json` 中內聯**：

~~249~~

250```json theme={null}

251{

252 "name": "my-plugin",

253 "lspServers": {

254 "go": {

255 "command": "gopls",

256 "args": ["serve"],

257 "extensionToLanguage": {

258 ".go": "go"

259 }

260 }

261 }

262}

263```

~~264~~

265**必需欄位：**

~~266~~

267| 欄位 | 描述 |

268| :-------------------- | :------------------------ |

269| `command` | 要執行的 LSP 二進位檔（必須在 PATH 中） |

270| `extensionToLanguage` | 將檔案副檔名對應到語言識別碼 |

~~271~~

272**選用欄位：**

~~273~~

274| 欄位 | 描述 |

275| :---------------------- | :------------------------------------------------------------------------------------------ |

276| `args` | LSP 伺服器的命令列引數 |

277| `transport` | 通訊傳輸：`stdio`（預設）或 `socket`。Claude Code 接受 `socket` 但在 stdio 上執行每個伺服器，因此 stdout 協定規則適用於所有伺服器 |

278| `env` | 啟動伺服器時要設定的環境變數 |

279| `initializationOptions` | 在初始化期間傳遞給伺服器的選項 |

280| `settings` | 透過 `workspace/didChangeConfiguration` 傳遞的設定 |

281| `workspaceFolder` | 伺服器的工作區資料夾路徑 |

282| `startupTimeout` | 等待伺服器啟動的最長時間（毫秒） |

283| `shutdownTimeout` | 等待正常關閉的最長時間（毫秒）。當逾時時間過去時，Claude Code 會終止伺服器程序。未設定時，不適用逾時 |

284| `restartOnCrash` | 伺服器當機後是否重新啟動。預設為 `true`。設定為 `false` 以保持當機的伺服器停止而不是重新啟動 |

285| `maxRestarts` | 放棄前的最大重新啟動嘗試次數 |

286| `diagnostics` | 編輯後是否將診斷推送到 Claude 的內容中（預設 `true`）。設定為 `false` 以保持程式碼導覽但抑制自動診斷注入 |

~~287~~

288`restartOnCrash` 和 `shutdownTimeout` 需要 Claude Code v2.1.205 或更新版本。在 v2.1.205 之前，設定結構描述接受兩個選項，但設定其中任一個會導致 Claude Code 在啟動時完全跳過該 LSP 伺服器，原因只在 `claude --debug` 輸出中可見。

~~289~~

290**同一副檔名的多個伺服器**：當多個已啟用的 LSP 伺服器在 `extensionToLanguage` 中宣告相同的檔案副檔名時，無論伺服器來自一個 plugin 還是來自不同的 plugins，第一個註冊的伺服器會處理具有該副檔名的檔案，其他伺服器永遠不會啟動。`/plugin` 介面會顯示一個警告，命名其伺服器為作用中的 plugin。

~~291~~

292**無法初始化的伺服器**：Claude Code 會跳過其設定無效的伺服器，例如缺少 `command` 或 `extensionToLanguage` 的伺服器，其他已設定的伺服器仍會啟動。執行 `claude --debug` 以查看伺服器被跳過的原因。

~~293~~

294被跳過的伺服器不會宣告其檔案副檔名，因此宣告相同副檔名的另一個有效伺服器（來自相同或不同的 plugin）仍會處理這些檔案。

~~295~~

296**將日誌輸出傳送到 stderr，而不是 stdout**：Claude Code 將伺服器的 stdout 讀取為協定訊息，並接受最多 64 KiB 的訊息標頭和最多 32 MiB 的訊息本文。Claude Code 會斷開超過任一限制或將非協定輸出寫入 stdout 的伺服器，並將斷開連接計為 `restartOnCrash` 和 `maxRestarts` 的當機。當您使用 `--debug` 執行時，Claude Code 會將命名原因的錯誤寫入偵錯日誌。

~~297~~

298<Warning>

299 **您必須單獨安裝語言伺服器二進位檔。** LSP plugins 設定 Claude Code 如何連接到語言伺服器，但它們不包括伺服器本身。如果您在 `/plugin` Errors 標籤中看到 `Executable not found in $PATH`，請為您的語言安裝所需的二進位檔。

300</Warning>

~~301~~

302**可用的 LSP plugins：**

~~303~~

304| Plugin | 語言伺服器 | 安裝命令 |

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

306| `pyright-lsp` | Pyright (Python) | `pip install pyright` 或 `npm install -g pyright` |

307| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |

308| `rust-analyzer-lsp` | rust-analyzer | [請參閱 rust-analyzer 安裝](https://rust-analyzer.github.io/manual.html#installation) |

~~309~~

310先安裝語言伺服器，然後從 marketplace 安裝 plugin。

~~311~~

312<h3 id="monitors">

313 Monitors

314</h3>

~~315~~

316Plugins 可以宣告背景監視器，Claude Code 在 plugin 啟用時自動啟動。每個監視器在工作階段的生命週期內執行 shell 命令，並將每個 stdout 行傳遞給 Claude 作為通知，因此 Claude 可以對日誌項目、狀態變更或輪詢事件做出反應，而無需被要求自己啟動監視。

~~317~~

318Plugin monitors 使用與 [Monitor tool](/docs/zh-TW/tools-reference#monitor-tool) 相同的機制，並共享其可用性限制。它們僅在互動式 CLI 工作階段中執行，以與 [hooks](#hooks) 相同的信任層級在未沙箱化的環境中執行，並在 Monitor tool 不可用的主機上被跳過。

~~319~~

320**位置**：plugin 根目錄中的 `monitors/monitors.json`，或 plugin.json 中的內聯

~~321~~

322**格式**：監視器項目的 JSON 陣列

~~323~~

324以下 `monitors/monitors.json` 監視部署狀態端點和本機錯誤日誌：

~~325~~

326```json theme={null}

327[

328 {

329 "name": "deploy-status",

330 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",

331 "description": "Deployment status changes"

332 },

333 {

334 "name": "error-log",

335 "command": "tail -F ./logs/error.log",

336 "description": "Application error log",

337 "when": "on-skill-invoke:debug"

338 }

339]

340```

~~341~~

342若要內聯宣告監視器，請在 `plugin.json` 中將 `experimental.monitors` 設定為相同的陣列。若要從非預設路徑載入，請將 `experimental.monitors` 設定為相對路徑字串，例如 `"./config/monitors.json"`。Monitors 是 [experimental component](#experimental-components)。

~~343~~

344**必需欄位：**

~~345~~

346| 欄位 | 描述 |

347| :------------ | :------------------------------------------------ |

348| `name` | 在 plugin 中唯一的識別碼。防止 plugin 重新載入或再次叫用 skill 時的重複程序 |

349| `command` | 在工作階段工作目錄中作為持久背景程序執行的 shell 命令 |

350| `description` | 正在監視的內容的簡短摘要。顯示在工作面板和通知摘要中 |

~~351~~

352**選用欄位：**

~~353~~

354| 欄位 | 描述 |

355| :----- | :----------------------------------------------------------------------------------------------------------------- |

356| `when` | 控制監視器何時啟動。`"always"` 在工作階段啟動和 plugin 重新載入時啟動它，是預設值。`"on-skill-invoke:<skill-name>"` 在此 plugin 中的命名 skill 首次被分派時啟動它 |

~~357~~

358`command` 值支援 [路徑替換](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}` 和 `${CLAUDE_PROJECT_DIR}`，加上環境中的任何 `${ENV_VAR}`。如果指令碼需要從 plugin 自己的目錄執行，請在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。

~~359~~

360Monitor `command` 無法參考 [`${user_config.*}`](#user-configuration) 值。命令透過 shell 執行，因此 Claude Code 會以 [error](/docs/zh-TW/errors#plugin-command-references-user-config) 拒絕監視器，而不是替換值。Monitor 程序不會接收 `CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數，因此讓監視器指令碼從它擁有的設定檔讀取值。

~~361~~

362如果您在工作階段中停用 plugin，Claude Code 不會停止已在執行的監視器；它們在工作階段結束時停止。

~~363~~

364<h3 id="themes">

365 Themes

366</h3>

~~367~~

368Plugins 可以提供顏色主題，這些主題在 `/theme` 中與內建預設值和使用者的本機主題一起出現。主題是 `themes/` 中的 JSON 檔案，具有 `base` 預設值和稀疏的 `overrides` 顏色權杖對應。Themes 是 [experimental component](#experimental-components)。

~~369~~

370```json theme={null}

371{

372 "name": "Dracula",

373 "base": "dark",

374 "overrides": {

375 "claude": "#bd93f9",

376 "error": "#ff5555",

377 "success": "#50fa7b"

378 }

379}

380```

~~381~~

382當使用者選擇 plugin 主題時，Claude Code 會在其設定中儲存 `custom:<plugin-name>:<slug>`。Plugin 主題是唯讀的：當使用者在 `/theme` 中按下 `Ctrl+E` 時，Claude Code 會將其複製到 `~/.claude/themes/` 中，以便他們可以編輯副本。

~~383~~

384***

~~385~~

386<h2 id="plugin-installation-scopes">

387 Plugin 安裝範圍

388</h2>

~~389~~

390當您安裝 plugin 時，您可以選擇一個**範圍**，決定 plugin 在何處可用以及誰可以使用它：

~~391~~

392| 範圍 | 設定檔 | 使用案例 |

393| :-------- | :------------------------------------------ | :------------------------------------------------ |

394| `user` | `~/.claude/settings.json` | 個人 plugin，可在所有專案中使用（預設） |

395| `project` | `.claude/settings.json` | 透過版本控制共享的團隊 plugin |

396| `local` | `.claude/settings.local.json` | 專案特定的 plugin，當 Claude Code 將設定儲存到其中時會被 gitignored |

397| `managed` | [Managed settings](/docs/zh-TW/managed-settings) | 受管理的 plugin（唯讀，僅更新） |

~~398~~

399Plugin 使用與其他 Claude Code 設定相同的範圍系統。如需安裝說明和範圍旗標，請參閱 [Install plugins](/docs/zh-TW/discover-plugins#install-plugins)。如需範圍的完整說明，請參閱 [Configuration scopes](/docs/zh-TW/settings#where-settings-live)。

~~400~~

401***

~~402~~

403<h2 id="skills-directory-plugins">

404 Skills-directory plugins

405</h2>

~~406~~

407任何 skills 目錄下的資料夾，如果包含 `.claude-plugin/plugin.json` 清單，就會在下一個工作階段中以 `<name>@skills-dir` 的名稱載入為 plugin，無需市集且無需安裝步驟。使用 [`plugin init`](#plugin-init) 來建立一個。與複製的市集安裝不同，plugin 是在原地被發現而不是被複製到 plugin 快取中。

~~408~~

409skills 目錄樹支援三種不同的東西：

~~410~~

411| 你擁有的 | 它是什麼 |

412| :-------------------------------------------- | :------------------------------------------------------- |

413| `<skills-dir>/foo/SKILL.md` 且沒有清單 | 一個名為 `foo` 的純 [skill](/docs/zh-TW/skills) |

414| `<skills-dir>/foo/.claude-plugin/plugin.json` | 一個 plugin `foo@skills-dir`，可以捆綁自己的 skills、agents、hooks 等 |

415| `<plugin>/skills/bar/SKILL.md` | 一個 skill `bar` 打包在 plugin 內 |

~~416~~

417<h3 id="choose-where-the-plugin-loads-from">

418 選擇 plugin 從何處載入

419</h3>

~~420~~

421| Skills 目錄 | 範圍 | 載入 |

422| :---------------------- | :- | :---------------------------------------------------------------------------------- |

423| `~/.claude/skills/` | 個人 | 在每個專案中，因為該位置只屬於你 |

424| `<cwd>/.claude/skills/` | 專案 | 只有在你接受該資料夾的工作區 [信任對話](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 後才會載入 |

~~425~~

426專案範圍的 plugin 被簽入到儲存庫中，並到達每個複製它的協作者。因為該內容來自儲存庫而不是來自你，它只有在與 `.claude/settings.json` 中的專案允許規則相同的信任閘道後才會載入，所以信任父資料夾或使用 `-p` 執行是不夠的，執行程式碼的元件會受到進一步限制：

~~427~~

428* 它宣告的 MCP 伺服器會經過與專案 `.mcp.json` 相同的 [每個伺服器批准](/docs/zh-TW/mcp)

429* LSP 伺服器只有在你信任工作區後才會啟動

430* [背景監視器](#monitors) 不會載入

~~431~~

432個人範圍的 plugins 沒有這些限制。

~~433~~

434<Warning>

435 專案範圍的 `@skills-dir` plugins 只從工作階段的 [主要工作目錄](/docs/zh-TW/permissions#working-directories) 的 `.claude/skills/` 載入。它們不會像純 skills 和命令那樣 [向上走到儲存庫根目錄](/docs/zh-TW/skills#discovery-from-parent-and-nested-directories)，所以從子目錄啟動會錯過位於儲存庫根目錄的 plugin。從儲存庫根目錄啟動，或在 v2.1.246 或更新版本上 [使用 `/cd` 將工作階段移到那裡](/docs/zh-TW/permissions#move-the-session-to-another-directory)。

436</Warning>

~~437~~

438<h3 id="edit-reload-and-disable-a-skills-directory-plugin">

439 編輯、重新載入和停用 skills-directory plugin

440</h3>

~~441~~

442你對 skill 的 `SKILL.md` 所做的更改會立即在目前工作階段中生效。對 plugin 的其他元件（例如 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/`）的更改則不會。執行 `/reload-plugins` 或重新啟動 Claude Code 來取得這些更改。請參閱 [Live change detection](/docs/zh-TW/skills#live-change-detection)。

~~443~~

444要停止載入 skills-directory plugin，請刪除其資料夾或按名稱停用它。沒有 `uninstall` 步驟，因為沒有從市集安裝任何東西。

~~445~~

446```bash theme={null}

447claude plugin disable my-tool@skills-dir

448```

~~449~~

450***

~~451~~

452<h2 id="synced-plugins">

453 從 claude.ai 同步的外掛程式

454</h2>

~~455~~

456Claude Code 會載入為您的 claude.ai 帳戶啟用的外掛程式，包括您的組織為其成員開啟的外掛程式，以及您從 marketplace 安裝的外掛程式。它會將每個外掛程式下載到 `~/.claude/plugins/synced/` 中，並將其載入為 `<name>@synced`，沒有 marketplace 也沒有安裝記錄。同步的外掛程式執行時具有與您安裝的 marketplace 外掛程式相同的信任等級：其 skills、agents、hooks、MCP 伺服器和 LSP 伺服器都會載入。

~~457~~

458Claude Code 同步這些外掛程式的位置取決於工作階段：

~~459~~

460* 在 [Cowork](https://claude.com/product/cowork) 和[雲端工作階段](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)中，Claude Code 會在工作階段啟動時將它們下載到工作階段自身的環境中。在 v2.1.239 之前，Claude Code 將這些外掛程式載入為 `<name>@inline`，這是 `--plugin-dir` 外掛程式使用的身分。

461* 在您使用 claude.ai 帳戶登入的終端機工作階段中，Claude Code 每次啟動時會檢查您的帳戶一次，然後在背景中下載新的和更新的外掛程式，並移除您或您的組織關閉的外掛程式。終端機工作階段中的同步需要 Claude Code v2.1.273 或更新版本。

~~462~~

463啟動檢查在背景中執行，因此可以在您的工作階段啟動後完成。當它在互動式工作階段中新增、更新或移除同步的外掛程式時，Claude Code 會顯示 `Plugins changed. Run /reload-plugins to activate.` 執行 [`/reload-plugins`](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 以在該工作階段中載入變更，或留待下次啟動 Claude Code 時再進行。如果您在工作階段執行時在 claude.ai 上啟用外掛程式，Claude Code 會在下次啟動時下載它。

~~464~~

465終端機工作階段中的外掛程式同步在與[從 claude.ai 同步的 skills](/docs/zh-TW/skills#where-synced-skills-load)相同的登入條件下執行。它還需要授予 Claude Code 存取您帳戶外掛程式的登入。

~~466~~

467來自較早版本 Claude Code 的登入會在 Claude Code 在背景中更新該登入時（通常在幾小時內）或在您再次執行 `/login` 時立即取得外掛程式存取權限。外掛程式同步會在您之後下次啟動 Claude Code 時開始。

~~468~~

469`claude plugin list` 會在 `Synced from claude.ai` 標題下顯示同步的外掛程式，而 `/plugin` **Installed** 標籤會列出它們，並以 `synced` 作為其來源。使用 `claude plugin list` 列印的 `<name>@synced` ID 來管理同步的外掛程式：

~~470~~

471* **關閉其中一個**：執行 `claude plugin disable <name>@synced`，或從 `/plugin` **Installed** 標籤中停用它。Claude Code 會將選擇儲存為您使用者層級 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 中的 `"<name>@synced": false`。若要重新開啟外掛程式，請執行 `claude plugin enable <name>@synced`。

472* **在任何地方都排除其中一個**：[為您的 claude.ai 帳戶關閉外掛程式](/docs/zh-TW/desktop#extend-claude-code)。若要在每個環境中將其排除在一個專案之外，請在該專案已提交的 `.claude/settings.json` 中的 `enabledPlugins` 下設定 `"<name>@synced": false`。

473* **在 claude.ai 上管理外掛程式本身**：`claude plugin install`、`update` 和 `uninstall` 不適用於同步的外掛程式。Claude Code 會在下次同步時下載外掛程式的更新。若要移除一個，請為您的 claude.ai 帳戶關閉外掛程式，Claude Code 會在下次同步時將其移除。

474* **停止在機器上同步**：在您的使用者設定中將 [`syncClaudeAiPlugins`](/docs/zh-TW/settings-reference#syncclaudeaiplugins) 設定為 `false`。Claude Code 會停止下載，下次啟動時會將已同步的外掛程式移動到 `~/.claude/plugins/.trash/`，並不再載入它們。您的組織可以在[受管設定](/docs/zh-TW/managed-settings)中設定相同的金鑰，或在 claude.ai 上關閉 Skills，這也會停止外掛程式同步。

~~475~~

476您無法關閉您的組織在 claude.ai 上標記為必需的外掛程式。Claude Code 會載入它，即使您之前停用了它，而 `claude plugin disable` 會拒絕並顯示 `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.` 在 `claude plugin list` 中，這些外掛程式會標記為 `required by your org`。

~~477~~

478當來自任何其他來源的已啟用外掛程式與同步外掛程式的名稱相符時，Claude Code 會載入該外掛程式並報告同步副本未被載入。其他來源包括 marketplace 安裝、[skills 目錄外掛程式](#skills-directory-plugins)、`--plugin-dir` 外掛程式和內建於 Claude Code 的外掛程式。若要改用 claude.ai 副本，請停用您自己的副本。在 v2.1.239 之前，Claude Code 會載入同步副本而不是同名的 marketplace 安裝。

~~479~~

480***

~~481~~

482<h2 id="plugin-manifest-schema">

483 Plugin manifest schema

484</h2>

~~485~~

486`.claude-plugin/plugin.json` 檔案定義了你的 plugin 的中繼資料和設定。

~~487~~

488manifest 是選用的。如果省略，Claude Code 會在[預設位置](#file-locations-reference)自動探索元件，並從目錄名稱衍生 plugin 名稱。當你需要提供中繼資料或自訂元件路徑時，請使用 manifest。

~~489~~

490<h3 id="complete-schema">

491 Complete schema

492</h3>

~~493~~

494```json theme={null}

495{

496 "name": "plugin-name",

497 "displayName": "Plugin Name",

498 "version": "1.2.0",

499 "description": "Brief plugin description",

500 "author": {

501 "name": "Author Name",

502 "email": "author@example.com",

503 "url": "https://github.com/author"

504 },

505 "homepage": "https://docs.example.com/plugin",

506 "repository": "https://github.com/author/plugin",

507 "license": "MIT",

508 "keywords": ["keyword1", "keyword2"],

509 "metadata": { "catalogId": "cat-123", "tier": "pro" },

510 "skills": "./custom/skills/",

511 "commands": ["./custom/commands/special.md"],

512 "agents": ["./custom/agents/reviewer.md"],

513 "hooks": "./config/hooks.json",

514 "mcpServers": "./mcp-config.json",

515 "outputStyles": "./styles/",

516 "lspServers": "./.lsp.json",

517 "experimental": {

518 "themes": "./themes/",

519 "monitors": "./monitors.json",

520 "evals": "quality/evals"

521 },

522 "dependencies": [

523 "helper-lib",

524 { "name": "secrets-vault", "version": "~2.1.0" }

525 ]

526}

527```

~~528~~

529<h3 id="required-fields">

530 必需欄位

531</h3>

~~532~~

533如果你包含 manifest，`name` 是唯一必需的欄位。

~~534~~

535| 欄位 | 類型 | 說明 | 範例 |

536| :----- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |

537| `name` | string | 唯一識別碼，採用 kebab-case，不含空格、控制字元或雙向格式化字元。當[marketplace 項目](/docs/zh-TW/plugin-marketplaces#plugin-entries)以不同名稱列出 plugin 時，marketplace 項目名稱是 `enabledPlugins` 鍵和 `/plugin` 使用的名稱 | `"deployment-tools"` |

~~538~~

539此名稱用於命名空間元件。例如，在 UI 中，名稱為 `plugin-dev` 的 plugin 的 agent `agent-creator` 將顯示為 `plugin-dev:agent-creator`。

~~540~~

541<h3 id="unrecognized-fields">

542 無法識別的欄位

543</h3>

~~544~~

545Claude Code 會忽略它無法識別的頂層欄位。你可以在 `plugin.json` 中保留來自另一個生態系統的中繼資料，plugin 仍然會載入。這使得維護一個 manifest 作為 VS Code 或 Cursor extension manifest、npm `package.json` 或 MCPB/DXT bundle manifest 變得實用。

~~546~~

547`claude plugin validate` 將無法識別的欄位報告為警告，而不是錯誤。如果欄位名稱與已識別的欄位相差一或兩個字元，警告會建議可能的預期名稱。只有無法識別欄位警告的 plugin 仍會通過驗證並在執行時載入。

~~548~~

549Claude Code 如何處理已識別欄位但值類型錯誤的情況取決於該欄位：

~~550~~

551* **大多數欄位**：plugin 無法載入。例如，`keywords` 值是字串而不是陣列是載入錯誤，`claude plugin validate` 會將其報告為錯誤。

552* **`experimental` 和 `metadata`**：Claude Code 會忽略非物件值，`claude plugin validate` 會報告警告。

~~553~~

554傳遞 `--strict` 以將警告視為錯誤。在 CI 中使用它來在發佈前捕捉拼寫錯誤的欄位名稱或來自另一個工具 manifest 的遺留欄位，即使 plugin 在執行時會載入。

~~555~~

556```bash theme={null}

557claude plugin validate ./my-plugin --strict

558```

~~559~~

560<h3 id="metadata-fields">

561 中繼資料欄位

562</h3>

~~563~~

564| 欄位 | 類型 | 說明 | 範例 |

565| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |

567| `displayName` | string | 在 `/plugin` 選擇器和其他 UI 表面中顯示的人類可讀名稱。對於 marketplace 安裝的 plugin，[marketplace 項目](/docs/zh-TW/plugin-marketplaces#optional-plugin-fields)上的 `displayName` 優先於此值。當兩個位置都未設定顯示名稱時，使用者會看到 `name`。與 `name` 不同，可以包含空格和任何大小寫。不用於命名空間或查詢。 | `"Deployment Tools"` |

568| `version` | string | 選用。語義版本。設定此項會將 plugin 固定到該版本字串，因此使用者只有在你提升版本時才會收到更新，除了[`command` source](/docs/zh-TW/plugin-marketplaces#command-sources)或[就地載入](#plugin-caching-and-file-resolution)的 plugin；請參閱[版本管理](#version-management)。如果也在 marketplace 項目中設定，`plugin.json` 優先。如果省略，版本來自[版本管理](#version-management)中的下一個來源。 | `"2.1.0"` |

570| `author` | object | 作者資訊 | `{"name": "Dev Team", "email": "dev@company.com"}` |

575| `metadata` | object | 自由格式物件，用於你自己的資料，例如權利或目錄欄位。Claude Code 不會讀取它，因此值永遠不會影響 plugin 行為。Claude Code 會忽略非物件值，`claude plugin validate` 會將其報告為警告。在 v2.1.222 之前，Claude Code 將該鍵視為[無法識別的欄位](#unrecognized-fields)。 | `{"catalogId": "cat-123"}` |

~~577~~

578<h3 id="default-enablement">

579 預設啟用

580</h3>

~~581~~

582在 `plugin.json` 中設定 `defaultEnabled: false` 以發佈已停用安裝的 plugin。使用者使用 `claude plugin enable <plugin>` 或 `/plugin` 介面將其開啟。對於新增成本或使用者應選擇加入的 plugin（例如連接到外部服務的 plugin），請使用此選項。

~~583~~

584`defaultEnabled` 是當沒有其他因素決定 plugin 狀態時的後備。使用者的設定和依賴項要求優先於它：

~~585~~

586* **使用者的設定**：任何設定範圍中 `enabledPlugins` 中的 plugin 項目。一旦寫入，它會在 plugin 更新和重新安裝中持續存在，因此在後續版本中變更 `defaultEnabled` 不會翻轉現有使用者。

587* **依賴項要求**：當 plugin 由另一個活躍的 plugin 要求時，Claude Code 在安裝或啟用時為其寫入 `true`。這給了它一個明確的設定，因此它自己的預設不再適用。請參閱[啟用或停用具有依賴項的 plugin](/docs/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)。

~~588~~

589相同的欄位可以出現在 plugin 的 marketplace 項目中，其優先於 `plugin.json` 中的值。請參閱[選用 plugin 欄位](/docs/zh-TW/plugin-marketplaces#optional-plugin-fields)。

~~590~~

591<h3 id="component-path-fields">

592 元件路徑欄位

593</h3>

~~594~~

595| 欄位 | 類型 | 說明 | 範例 |

596| :---------------------- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

610| `dependencies` | array | 此 plugin 需要的其他 plugin，可選擇使用 semver 版本限制。請參閱[限制 plugin 依賴項版本](/docs/zh-TW/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

~~611~~

612<h3 id="experimental-components">

613 實驗性元件

614</h3>

~~615~~

616`experimental` 鍵下的元件 `themes` 和 `monitors` 具有在版本之間可能變更的 manifest schema，同時它們穩定。你宣告它們的位置是一個單獨的遷移：頂層仍然有效，`claude plugin validate` 發出警告，未來版本將需要 `experimental.*`。

~~617~~

618<h3 id="user-configuration">

619 使用者設定

620</h3>

~~621~~

622`userConfig` 欄位宣告當 plugin 啟用時 Claude Code 提示使用者的值。使用此選項而不是要求使用者手動編輯 `settings.json`。

~~623~~

624```json theme={null}

625{

626 "userConfig": {

627 "api_endpoint": {

628 "type": "string",

629 "title": "API endpoint",

630 "description": "Your team's API endpoint"

631 },

632 "api_token": {

633 "type": "string",

634 "title": "API token",

635 "description": "API authentication token",

636 "sensitive": true

637 }

638 }

639}

640```

~~641~~

642鍵必須是有效的識別碼。每個選項支援這些欄位：

~~643~~

644| 欄位 | 必需 | 說明 |

645| :------------ | :- | :--------------------------------------------------------------------------------------------------------------------------- |

646| `type` | 是 | `string`、`number`、`boolean`、`directory` 或 `file` 之一 |

647| `title` | 是 | 在設定對話方塊中顯示的標籤 |

648| `description` | 是 | 在欄位下方顯示的說明文字 |

649| `sensitive` | 否 | 如果為 `true`，會遮罩輸入並將值儲存在安全儲存中而不是 `settings.json` |

650| `required` | 否 | 如果為 `true`，當欄位為空時驗證失敗 |

651| `default` | 否 | 當使用者未提供任何內容時使用的值 |

652| `options` | 否 | 對於 `string` 類型，欄位接受的值，在 `/config` 中顯示為它們上的選擇器。請參閱[將欄位限制為固定選項](#limit-a-field-to-fixed-options)。需要 Claude Code v2.1.271 或更新版本 |

653| `multiple` | 否 | 對於 `string` 類型，允許字串陣列 |

654| `min` / `max` | 否 | `number` 類型的邊界 |

~~655~~

656除了 `sensitive` 欄位和 `multiple` 列表，每個啟用 plugin 的每個欄位也會在 `/config` 面板中顯示為一列。這些列需要 Claude Code v2.1.269 或更新版本。

~~657~~

658每個值都可用於在 MCP 和 LSP 伺服器設定和 hook 命令中作為 `${user_config.KEY}` 進行替換。非敏感值也可以在 skill 和 agent 內容中替換。所有值都會匯出到 hook 程序作為 `CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數，其中 `<KEY>` 是選項鍵的大寫形式。

~~659~~

660在 shell 中執行的欄位拒絕 `${user_config.*}`：將設定值替換到 shell 命令中會讓 shell 執行該值包含的任何內容，因此元件會失敗並出現[錯誤](/docs/zh-TW/errors#plugin-command-references-user-config)。每個被拒絕的欄位都有一個替代方式來傳遞值：

~~661~~

662| 被拒絕的欄位 | 如何傳遞值 |

663| :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- |

664| Shell 形式 hook 命令 | 使用[執行形式](/docs/zh-TW/hooks#exec-form-and-shell-form)搭配 `args`，或從 hook 的環境讀取 `CLAUDE_PLUGIN_OPTION_<KEY>` |

665| [Monitor](#monitors) 命令 | 從指令碼中的設定檔讀取值 |

666| MCP [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) | 從指令碼中的設定檔讀取值 |

~~667~~

668在 v2.1.207 之前，這些欄位替換了 `${user_config.KEY}` 值；更新依賴此功能的 plugin。

~~669~~

670非敏感值儲存在你的使用者 `settings.json` 中的 [`pluginConfigs`](/docs/zh-TW/settings-reference#pluginconfigs) 鍵下，作為 `pluginConfigs[<plugin-id>].options`。

~~671~~

672在 macOS 上，Claude Code 將敏感值儲存在 macOS Keychain 中，當 Keychain 拒絕寫入時回退到 `~/.claude/.credentials.json`。在沒有支援的 keychain 的平台上，它將它們儲存在 `~/.claude/.credentials.json` 中。Keychain 儲存與 OAuth 令牌共享，總限制約為 2 KB，因此保持敏感值較小。

~~673~~

674Claude Code 只從三個設定來源讀取所有 `pluginConfigs` 值：

~~675~~

676* **使用者設定**：`~/.claude/settings.json`，啟用時提示寫入的檔案

677* **`--settings`**：CLI 旗標或 SDK 內嵌設定

678* **受管設定**：[組織控制的原則](/docs/zh-TW/permissions#managed-settings)

~~679~~

680當多個來源設定相同的鍵時，受管設定優先，然後是 `--settings`，然後是使用者設定。你可以從此列表中移除的唯一來源是使用者設定：傳遞 [`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 而不包含 `user`，Claude Code 會跳過它們。受管設定和 `--settings` 保持你傳遞的任何內容。SDK 的 [`settingSources`](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) 選項設定相同的列表。

~~681~~

682專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目被忽略。兩個檔案都位於工作區中，因此複製的儲存庫可以在那裡提供值，這些值會流入 plugin hook 命令、MCP 伺服器設定、LSP 命令和監視器命令。在 v2.1.207 之前，這些項目被讀取。限制特定於 `pluginConfigs`：[`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 仍然遵守專案和本地設定。

~~683~~

684<h4 id="limit-a-field-to-fixed-options">

685 將欄位限制為固定選項

686</h4>

~~687~~

688在 `userConfig` 欄位上設定 `options` 以讓使用者從固定列表中選擇其值。

~~689~~

690要將 `tone` 欄位限制為三個選項，在 `options` 中列出它們並將 `default` 設定為其中之一：

~~691~~

692```json theme={null}

693{

694 "userConfig": {

695 "tone": {

696 "type": "string",

697 "title": "Tone",

698 "description": "Voice for generated replies",

699 "options": ["neutral", "warm", "formal"],

700 "default": "neutral"

701 }

702 }

703}

704```

~~705~~

706如果你在任何欄位上宣告 `options`，Claude Code v2.1.271 之前版本的使用者無法載入 plugin。

~~707~~

708當你在欄位上設定 `options` 時，遵循這些規則：

~~709~~

710* 將 `type` 設定為 `string`

711* 不要將 `multiple` 或 `sensitive` 設定為 `true`

712* 將 `default` 設定為其中一個選項

713* 如果你不設定 `default`，將 `required` 設定為 `true`

714* 列出至少一個選項，每個 1 到 64 個字元長

715* 不要以空格開始或結束選項

716* 不要在選項中使用控制字元、不可見字元、改變文字方向的字元或除了常規空格以外的空格

717* 不要列出相同的選項兩次，即使是不同的字母大小寫

~~718~~

719如果你違反任何這些規則，plugin 無法載入。執行 `claude plugin validate` 以查看哪個欄位違反了哪個規則。

~~720~~

721<h3 id="channels">

722 頻道

723</h3>

~~724~~

725`channels` 欄位讓 plugin 宣告一個或多個訊息頻道，將內容注入到對話中。每個頻道繫結到 plugin 提供的 MCP 伺服器。

~~726~~

727```json theme={null}

728{

729 "channels": [

730 {

731 "server": "telegram",

732 "userConfig": {

733 "bot_token": {

734 "type": "string",

735 "title": "Bot token",

736 "description": "Telegram bot token",

737 "sensitive": true

738 },

739 "owner_id": {

740 "type": "string",

741 "title": "Owner ID",

742 "description": "Your Telegram user ID"

743 }

744 }

745 }

746 ]

747}

748```

~~749~~

750`server` 欄位是必需的，必須符合 plugin 的 `mcpServers` 中的鍵。選用的每個頻道 `userConfig` 使用與頂層欄位相同的 schema，讓 plugin 在啟用時提示 bot 令牌或擁有者 ID。

~~751~~

752<h3 id="path-behavior-rules">

753 路徑行為規則

754</h3>

~~755~~

756自訂路徑是取代還是擴展 plugin 的預設目錄取決於欄位：

~~757~~

758* **取代預設**：`commands`、`agents`、`workflows`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，當 manifest 指定 `commands` 時，預設 `commands/` 目錄不會被掃描。要保留預設並新增更多，明確列出它：`"commands": ["./commands/", "./extras/"]`

759* **新增到預設**：`skills`。預設 `skills/` 目錄始終被掃描，`skills` 中列出的目錄與它一起載入。例外：對於[其 `source` 解析為 marketplace 根目錄的 marketplace 項目](/docs/zh-TW/plugin-marketplaces#advanced-plugin-entries)，宣告特定子目錄會取代預設 `skills/` 掃描

760* **自己的合併規則**：[hooks](#hooks)、[MCP 伺服器](#mcp-servers) 和 [LSP 伺服器](#lsp-servers)。請參閱每個部分以了解多個來源如何組合

~~761~~

762當 plugin 同時具有預設資料夾和匹配的 manifest 鍵時，Claude Code 會在 `claude plugin list` 和 `/plugin` 詳細檢視中警告被忽略的資料夾。plugin 仍然使用 manifest 路徑載入。當 manifest 鍵指向預設資料夾時，Claude Code 不會發出警告，例如 `"commands": ["./commands/deploy.md"]`，因為該路徑明確命名了資料夾。

~~763~~

764對於所有路徑欄位：

~~765~~

766* 所有路徑必須相對於 plugin 根目錄並以 `./` 開頭，除了 `skills` 欄位也接受 `"."`

767 * `"."` 和 `"./"` 都表示 plugin 根目錄本身

768 * 在 v2.1.221 之前，`"."` 無法通過 manifest 驗證，plugin 無法載入，因此使用 `"./"` 以支援較早版本

769* 來自自訂路徑的元件使用相同的命名和命名空間規則，除了 agent 檔案。請參閱 [Agents](#agents) 以了解 agent 名稱如何運作

770* 多個路徑可以指定為陣列

771* skill 路徑可以指向直接包含 `SKILL.md` 的目錄，例如 `"skills": ["."]` 用於 plugin 根目錄

772 * Claude Code 從 `SKILL.md` 中的 frontmatter `name` 欄位取得 skill 的呼叫名稱，因此無論安裝目錄名稱如何，名稱保持穩定

773 * 如果 frontmatter 中未設定 `name`，Claude Code 會回退到目錄基名

~~774~~

775具有根目錄中的 `SKILL.md`、沒有 `skills/` 子目錄且沒有 `skills` manifest 欄位的 plugin 會自動載入為單一 skill plugin。對於此佈局，你不需要在 `plugin.json` 中設定 `"skills": ["./"]`。

~~776~~

777**路徑範例**：

~~778~~

779```json theme={null}

780{

781 "commands": [

782 "./specialized/deploy.md",

783 "./utilities/batch-process.md"

784 ],

785 "agents": [

786 "./custom-agents/reviewer.md",

787 "./custom-agents/tester.md"

788 ]

789}

790```

~~791~~

792<h3 id="environment-variables">

793 環境變數

794</h3>

~~795~~

796Claude Code 提供三個變數用於參考路徑：

~~797~~

798| 變數 | 解析為 | 用途 |

799| :---------------------- | :--------------------------------------------------------- | :------------------------------------------------ |

800| `${CLAUDE_PLUGIN_ROOT}` | plugin 安裝目錄的絕對路徑 | 與 plugin 捆綁的指令碼、二進位檔案和設定檔 |

801| `${CLAUDE_PLUGIN_DATA}` | [持久目錄](#persistent-data-directory)，在首次參考時建立，在 plugin 更新中存活 | 已安裝的依賴項，例如 `node_modules` 或 Python 虛擬環境、生成的程式碼和快取 |

802| `${CLAUDE_PROJECT_DIR}` | 專案根目錄 | 專案本地指令碼和設定檔 |

~~803~~

804所有三個都匯出為環境變數到 hook 程序和 MCP 及 LSP 伺服器子程序。它們不存在於 Claude 通過 Bash 工具執行的命令環境中，無論是在主工作階段還是在子 agent 中。在 plugin 內容中，寫入佔位符，Claude Code 在載入內容時內嵌替換路徑。哪些欄位內嵌替換它們取決於 plugin 元件：

~~805~~

806| Plugin 元件 | 佔位符解析的欄位 |

807| :------------------------ | :--------------------------------------- |

808| Skill 和 agent 內容 | 佔位符出現的任何地方 |

809| Hook 和監視器命令 | 佔位符出現的任何地方 |

810| MCP `stdio` 伺服器 | `command`、`args`、`env` |

811| MCP `http`、`sse`、`ws` 伺服器 | `url`、`headers`、`headersHelper` |

812| LSP 伺服器 | `command`、`args`、`env`、`workspaceFolder` |

~~813~~

814在 hook 命令中，使用[執行形式](/docs/zh-TW/hooks#exec-form-and-shell-form)搭配 `args`，以便每個路徑作為一個引數傳遞，不需要引號。在 shell 形式 hook 和監視器命令中，用雙引號包裝變數，如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。此 shell 形式 hook 執行與 plugin 捆綁的指令碼：

~~815~~

816```json theme={null}

817{

818 "hooks": {

819 "PostToolUse": [

820 {

821 "hooks": [

822 {

823 "type": "command",

824 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"

825 }

826 ]

827 }

828 ]

829 }

830}

831```

~~832~~

833對於複製的 plugin，`${CLAUDE_PLUGIN_ROOT}` 在 plugin 更新時變更。前一個版本的目錄在更新後的寬限期內保留在磁碟上，但將其視為暫時的，不要在那裡寫入狀態。對於從本地目錄 marketplace 就地載入的 plugin，變數指向穩定的來源目錄。請參閱 [plugin 快取](#plugin-caching-and-file-resolution)以了解哪些 plugin 被複製以及清理語義。

~~834~~

835當複製的 plugin 在工作階段中途更新時，hook 命令、監視器、MCP 伺服器和 LSP 伺服器繼續使用前一個版本的路徑。執行 `/reload-plugins` 以將 hook、MCP 伺服器和 LSP 伺服器切換到新路徑；監視器需要工作階段重新啟動。在沒有互動式終端的工作階段中，重新載入會將 plugin MCP 伺服器保留在舊路徑上，直到下一個工作階段。

~~836~~

837對於具有 `command` source 的 plugin，Claude Code [可以重新載入 plugin 本身](/docs/zh-TW/plugin-marketplaces#when-claude-code-re-runs-the-command)。

~~838~~

839MCP 伺服器也可以呼叫 `roots/list` 請求以在執行時讀取工作階段的工作目錄。請參閱[`roots/list` 返回的內容以及 Claude Code 何時通知伺服器變更](/docs/zh-TW/mcp#option-3-add-a-local-stdio-server)。

~~840~~

841<h4 id="persistent-data-directory">

842 持久資料目錄

843</h4>

~~844~~

845`${CLAUDE_PLUGIN_DATA}` 目錄解析為 `~/.claude/plugins/data/{id}/`，其中 `{id}` 是 plugin 識別碼，其中 `a-z`、`A-Z`、`0-9`、`_` 和 `-` 以外的字元被替換為 `-`。對於安裝為 `formatter@my-marketplace` 的 plugin，目錄是 `~/.claude/plugins/data/formatter-my-marketplace/`。

~~846~~

847常見用途是一次安裝語言依賴項並在工作階段和 plugin 更新中重複使用它們。將其用於 Python 依賴項、使用 Yarn 或 pnpm 鎖定的依賴項以及其生命週期指令碼必須執行的套件。對於 marketplace 安裝的 plugin，你可能根本不需要它：Claude Code 在快取 plugin 時自動安裝符合條件的 [Node.js 套件依賴項](#node-js-package-dependencies)。

~~848~~

849因為資料目錄的壽命超過任何單一 plugin 版本，單獨檢查目錄存在無法偵測當更新變更 plugin 的依賴項 manifest 時。建議的模式是比較捆綁的 manifest 與資料目錄中的副本，並在它們不同時重新安裝。

~~850~~

851此 `SessionStart` hook 在首次執行時安裝 `node_modules`，並在 plugin 更新包含變更的 `package.json` 時再次安裝：

~~852~~

853```json theme={null}

854{

855 "hooks": {

856 "SessionStart": [

857 {

858 "hooks": [

859 {

860 "type": "command",

861 "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""

862 }

863 ]

864 }

865 ]

866 }

867}

868```

~~869~~

870`diff` 在儲存的副本遺失或與捆綁的副本不同時以非零值退出，涵蓋首次執行和依賴項變更更新。如果 `npm install` 失敗，尾部 `rm` 會移除複製的 manifest，以便下一個工作階段重試。

~~871~~

872然後在 `${CLAUDE_PLUGIN_ROOT}` 中捆綁的指令碼可以針對持久的 `node_modules` 執行：

~~873~~

874```json theme={null}

875{

876 "mcpServers": {

877 "routines": {

878 "command": "node",

879 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],

880 "env": {

881 "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"

882 }

883 }

884 }

885}

886```

~~887~~

888當你從最後一個安裝它的範圍卸載 plugin 時，資料目錄會自動刪除。`/plugin` 介面顯示目錄大小並在刪除前提示。CLI 預設刪除；傳遞 [`--keep-data`](#plugin-uninstall) 以保留它。

~~889~~

890***

~~891~~

892<h2 id="plugin-caching-and-file-resolution">

893 Plugin 快取和檔案解析

894</h2>

~~895~~

896Plugin 可以透過以下三種方式指定：

~~897~~

898* 透過 `claude --plugin-dir` 或 `claude --plugin-url`，在工作階段期間使用。

899* 透過市集安裝，供未來的工作階段使用。

900* 透過您的 claude.ai 帳戶，[同步](#synced-plugins)到 `~/.claude/plugins/synced/`。

~~901~~

902基於安全性和驗證目的，Claude Code 會將\_市集\_ plugin 複製到使用者的本機 **plugin 快取**（`~/.claude/plugins/cache`），除非 plugin 就地載入。[連結模式中的 `command` 來源](/docs/zh-TW/plugin-marketplaces#copy-mode-and-link-mode)會透過快取項目中的連結就地載入。[市集中的相對路徑來源](/docs/zh-TW/plugin-marketplaces#relative-paths)從本機目錄新增的市集會就地從市集資料夾載入。

~~903~~

904對於從本機目錄市集就地載入的 plugin，您對來源目錄的編輯會在下一個工作階段開始或 `/reload-plugins` 時生效。您不需要版本更新。Plugin 的 hook 程序和 MCP 和 LSP 伺服器會收到指向來源目錄的 `CLAUDE_PLUGIN_ROOT`。Claude Code 不會將 plugin 的 [Node.js 套件相依性](#node-js-package-dependencies)安裝到來源目錄中。請自行安裝它們，或從 hook 安裝到[持久資料目錄](#persistent-data-directory)。

~~905~~

906對於複製的 plugin，每個已安裝的版本都是快取中的單獨目錄，按市集和 plugin 分組，並以已解析的版本命名，具有自己的 plugin 檔案副本和 [Node.js 套件相依性](#node-js-package-dependencies)。從[發行標籤](/docs/zh-TW/plugin-dependencies#tag-plugin-releases-for-version-resolution)解析的相依性會取得帶有 commit-SHA 後綴的目錄名稱。

~~907~~

908當您更新或解除安裝 plugin 時，Claude Code 會將先前的版本目錄標記為孤立，並在大約 14 天後的背景掃描中將其移除。寬限期讓已載入舊版本的並行 Claude Code 工作階段繼續執行而不會出現錯誤。Claude Code 只在至少安裝了一個 plugin 時執行掃描；在您解除安裝最後一個 plugin 後，孤立目錄會保留在磁碟上，直到您再次安裝 plugin。

~~909~~

910Claude Code 只在 plugin 或市集資料夾不再包含任何目錄或符號連結時，才會將它從快取中移除。如果您將開發簽出符號連結到快取中作為 plugin 的版本項目，Claude Code 永遠不會將連結標記為孤立，也永遠不會移除它或包含它的資料夾。Claude Code 也永遠不會在連結的簽出中寫入其版本追蹤檔案。

~~911~~

912Claude 的 Glob 和 Grep 工具在搜尋期間會跳過孤立的版本目錄，因此檔案結果不包括過時的 plugin 程式碼。

~~913~~

914<h3 id="node-js-package-dependencies">

915 Node.js 套件相依性

916</h3>

~~917~~

918當 Claude Code 將 plugin 複製到快取時，它也會在那裡安裝 plugin 的 Node.js 套件相依性，以便 plugin 的 hooks 和 MCP 伺服器可以載入它們。本節涵蓋 plugin 在其自己的 `package.json` 中宣告的 npm 和 Bun 套件。對於依賴其他 plugin 的 plugin，請參閱 [plugin 相依性版本](/docs/zh-TW/plugin-dependencies)。

~~919~~

920Claude Code 在每次建立複製版本目錄時都會在其中執行安裝：當您安裝 plugin 時、當 Claude Code 將 plugin 更新為新版本時，以及在工作階段開始時（當已啟用的 plugin 尚未快取時），例如在新機器上。只有當 plugin 的根目錄同時包含 `package.json` 和支援的鎖定檔案時，安裝才會執行：

~~921~~

922| 鎖定檔案 | 命令 |

923| :------------------------------------------ | :----------------------------------------------- |

924| `bun.lock` 或 `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |

925| `npm-shrinkwrap.json` 或 `package-lock.json` | `npm ci --ignore-scripts` |

~~926~~

927如果 plugin 包含多個這些鎖定檔案，Claude Code 會使用第一個符合項，按順序檢查：`bun.lock`、`bun.lockb`、`npm-shrinkwrap.json`、`package-lock.json`。

~~928~~

929Claude Code 在兩種情況下會跳過安裝，各有其自己的修正方式：

~~930~~

931* 如果您的 plugin 只附帶 `yarn.lock` 或 `pnpm-lock.yaml`，請將其替換為 npm 鎖定檔案。

932* 如果 `bunfig.toml` 位於 bun 鎖定檔案旁邊，請移除 `bunfig.toml`，或將 bun 鎖定檔案替換為 npm 鎖定檔案。

~~933~~

934提供 npm 鎖定檔案以獲得最廣泛的覆蓋。Claude Code 從使用者的 PATH 執行符合的鎖定檔案的套件管理員，如果遺失，不會回退到其他鎖定檔案。對於透過 npm 來源分發的 plugin，請使用 `npm-shrinkwrap.json`；npm 會從已發佈的套件中排除 `package-lock.json`。

~~935~~

936Claude Code 限制此相依性安裝，使得 plugin 或其套件中的任何程式碼在安裝期間都不會執行，並限制其執行時間：

~~937~~

938* **凍結解析：** Bun 和 npm 安裝鎖定檔案精確指定的內容，當 `package.json` 和鎖定檔案不一致時，會失敗而不是重新解析版本。

939* **無生命週期指令碼：** `--ignore-scripts` 防止 `preinstall`、`install` 和 `postinstall` 指令碼執行，因此在這些指令碼中建置原生模組的相依性會下載但在此安裝期間不會編譯。

940* **60 秒逾時：** Claude Code 會停止執行時間超過此時間的安裝，並將其視為失敗。

~~941~~

942Claude Code 在此相依性安裝之前會提取 npm 來源 plugin，並且套件本身的任何安裝指令碼都不會在提取期間執行。請參閱 [npm 套件](/docs/zh-TW/plugin-marketplaces#npm-packages)。

~~943~~

944失敗或跳過的安裝永遠不會阻止 plugin。當安裝失敗或 Claude Code 跳過 yarn 或 pnpm 鎖定檔案或旁邊有 `bunfig.toml` 的 bun 鎖定檔案時，它會在[偵錯輸出](#debugging-commands)中將原因記錄為警告。具有 `package.json` 且沒有鎖定檔案的 plugin 會被跳過，不會有日誌項目。逾時的安裝可能會在快取副本中留下部分 `node_modules` 樹。

~~945~~

946您無法關閉自動安裝；沒有設定或環境變數可以停用它。在受限網路中，請參閱[網路存取需求](/docs/zh-TW/network-config#network-access-requirements)以了解要允許的主機。

~~947~~

948對於自動安裝無法提供的相依性，例如需要其生命週期指令碼來建置的套件、Python 相依性或使用 Yarn 或 pnpm 鎖定的 plugin，請從 hook 將其安裝到[持久資料目錄](#persistent-data-directory)。

~~949~~

950<h3 id="path-traversal-limitations">

951 路徑遍歷限制

952</h3>

~~953~~

954Claude Code 不允許 plugin 參考其自己目錄外的檔案。它會拒絕解析到 plugin 根目錄外的元件路徑，無論路徑是在 `plugin.json` 中宣告還是在[市集項目](/docs/zh-TW/plugin-marketplaces#plugin-entries)中宣告。這涵蓋指向 plugin 外部的路徑（如寫入的），例如 `../shared-utils`，以及導向 plugin 外部的符號連結，除了[市集內的連結](#share-files-within-a-marketplace-with-symlinks)。

~~955~~

956在 macOS 和 Linux 上，Claude Code 也會拒絕包含反斜線的元件路徑，即使路徑保留在 plugin 內。因此，使用反斜線路徑宣告的元件只在 Windows 上載入。使用正斜線編寫元件路徑，例如 `./commands/deploy.md`。

~~957~~

958當 Claude Code 拒絕路徑時，它會報告 [`path escapes plugin directory`](/docs/zh-TW/errors#path-escapes-plugin-directory) 錯誤，並在沒有該元件的情況下載入 plugin。

~~959~~

960Claude Code 在安裝 plugin 時也不會將 plugin 目錄外的檔案複製到快取中，因此當複製的 plugin 內的指令碼讀取 plugin 根目錄上方的路徑時，它也找不到這些檔案。

~~961~~

962<h3 id="share-files-within-a-marketplace-with-symlinks">

963 使用符號連結在市集內共享檔案

964</h3>

~~965~~

966如果您的 plugin 需要與同一市集的其他部分共享檔案，您可以在 plugin 目錄內建立符號連結。當 plugin 複製到快取時符號連結的處理方式取決於其目標的解析位置：

~~967~~

968* **在 plugin 自己的目錄內：** 符號連結在快取中保留為相對符號連結，因此在執行時它會繼續解析到複製的目標。

969* **在同一市集內的其他位置：** 符號連結被取消參考。目標的內容被複製到快取中以取代它。這讓中繼 plugin 的 `skills/` 目錄可以連結到市集中其他 plugin 定義的技能。

970* **在市集外：** 符號連結因安全性而被跳過。這防止 plugin 將任意主機檔案（例如系統路徑）拉入快取。

~~971~~

972對於使用 `--plugin-dir` 安裝的 plugin、來自本機路徑的 plugin，或來自複製模式中的 [`command` 來源](/docs/zh-TW/plugin-marketplaces#copy-mode-and-link-mode)的 plugin，只有解析到 plugin 自己目錄內的符號連結會被保留。所有其他連結都會被跳過。

~~973~~

974以下命令會建立從市集 plugin 內部到由同級 plugin 定義的共享技能的連結。在 Windows 上，從提升的命令提示字元使用 `mklink /D` 或啟用開發人員模式：

~~975~~

976```bash theme={null}

977ln -s ../../shared-plugin/skills/foo ./skills/foo

978```

~~979~~

980***

~~981~~

982<h2 id="plugin-directory-structure">

983 Plugin 目錄結構

984</h2>

~~985~~

986<h3 id="standard-plugin-layout">

987 標準 plugin 配置

988</h3>

~~989~~

990一個完整的 plugin 遵循此結構：

~~991~~

992```text theme={null}

993enterprise-plugin/

994├── .claude-plugin/ # 中繼資料目錄（選用）

995│ └── plugin.json # plugin 資訊清單

996├── skills/ # Skills

997│ ├── code-reviewer/

998│ │ └── SKILL.md

999│ └── pdf-processor/

1000│ ├── SKILL.md

1001│ └── scripts/

1002├── commands/ # Skills 作為平面 .md 檔案

1003│ ├── status.md

1004│ └── logs.md

1005├── agents/ # Subagent 定義

1006│ ├── security-reviewer.md

1007│ ├── performance-tester.md

1008│ ├── compliance-checker.md

1009│ └── review/ # 此處的 Agents 載入為 enterprise-plugin:review:<name>

1010│ └── accessibility.md

1011├── workflows/ # Workflow 指令碼

1012│ └── release-audit.js

1013├── output-styles/ # 輸出樣式定義

1014│ └── terse.md

1015├── themes/ # 色彩主題定義

1016│ └── dracula.json

1017├── monitors/ # 背景監視器設定

1018│ └── monitors.json

1019├── hooks/ # Hook 設定

1020│ ├── hooks.json # 主要 hook 設定

1021│ └── security-hooks.json # 其他 hooks

1022├── bin/ # Plugin 可執行檔新增至 PATH

1023│ └── my-tool # 在 Bash tool 中可作為裸命令叫用

1024├── settings.json # Plugin 的預設設定

1025├── .mcp.json # MCP 伺服器定義

1026├── .lsp.json # LSP 伺服器設定

1027├── scripts/ # Hook 和公用程式指令碼

1028│ ├── security-scan.sh

1029│ ├── format-code.py

1030│ └── deploy.js

1031├── LICENSE # 授權檔案

1032└── CHANGELOG.md # 版本歷史

1033```

~~1034~~

1035<Warning>

1036 `.claude-plugin/` 目錄包含 `plugin.json` 檔案。所有其他目錄（commands/、agents/、skills/、workflows/、output-styles/、themes/、monitors/、hooks/）必須位於 plugin 根目錄，而不是在 `.claude-plugin/` 內。

1037</Warning>

~~1038~~

1039Plugin 根目錄的 `CLAUDE.md` 檔案不會作為專案內容載入。Plugins 透過 skills、agents 和 hooks 而非 CLAUDE.md 來貢獻內容。若要提供載入至 Claude 內容的指示，請將其放在 [skill](#skills) 中。

~~1040~~

1041<h3 id="file-locations-reference">

1042 檔案位置參考

1043</h3>

~~1044~~

1045| 元件 | 預設位置 | 用途 |

1046| :------------ | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1047| **資訊清單** | `.claude-plugin/plugin.json` | Plugin 中繼資料和設定（選用） |

1048| **Skills** | `skills/` | 具有 `<name>/SKILL.md` 結構的 Skills |

1049| **Commands** | `commands/` | Skills 作為平面 Markdown 檔案。新 plugins 請使用 `skills/` |

1050| **Agents** | `agents/` | Subagent Markdown 檔案。子資料夾是 [agent 名稱](#agents) 的一部分 |

1051| **Workflows** | `workflows/` | [Workflow](/docs/zh-TW/workflows) 指令碼檔案 |

1052| **輸出樣式** | `output-styles/` | 輸出樣式定義 |

1053| **主題** | `themes/` | 色彩主題定義 |

1054| **Hooks** | `hooks/hooks.json` | Hook 設定 |

1055| **MCP 伺服器** | `.mcp.json` | MCP 伺服器定義 |

1056| **LSP 伺服器** | `.lsp.json` | 語言伺服器設定 |

1057| **監視器** | `monitors/monitors.json` | 背景監視器設定 |

1058| **可執行檔** | `bin/` | 新增至 Bash tool 的 `PATH` 的可執行檔，在 plugin 啟用時可作為裸命令叫用。您無法在透過 claude.ai 組織設定 [分發的 plugin 中包含此目錄](/docs/zh-TW/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory) |

1059| **設定** | `settings.json` | Plugin 啟用時套用的預設設定。僅支援 [`agent`](/docs/zh-TW/sub-agents) 和 [`subagentStatusLine`](/docs/zh-TW/statusline#subagent-status-lines) 鍵 |

~~1060~~

1061***

~~1062~~

1063<h2 id="cli-commands-reference">

1064 CLI 命令參考

1065</h2>

~~1066~~

1067Claude Code 提供 CLI 命令用於非互動式外掛程式管理，適用於指令碼和自動化。

~~1068~~

1069<h3 id="plugin-init">

1070 plugin init

1071</h3>

~~1072~~

1073在 `~/.claude/skills/<name>/` 處建立新外掛程式的框架。在下一個 Claude Code 工作階段中，它會自動載入為 `<name>@skills-dir`，並在 `/plugin` 和 `claude plugin list` 中出現，無需安裝步驟。

~~1074~~

1075請參閱[技能目錄外掛程式](#skills-directory-plugins)以了解範圍和信任要求。

~~1076~~

1077```bash theme={null}

1078claude plugin init <name> [options]

1079```

~~1080~~

1081該命令接受這些引數：

~~1082~~

1083* `<name>`：外掛程式名稱。成為技能命名空間和 `~/.claude/skills/` 下的目錄名稱，因此不能包含空格或路徑分隔符。

~~1084~~

1085該命令接受這些選項：

~~1086~~

1087| 選項 | 說明 | 預設值 |

1088| :----------------------- | :------------------------------------------------------------------------------ | :---------------------- |

1089| `--description <text>` | 資訊清單說明 | |

1090| `--author <name>` | 作者名稱 | `git config user.name` |

1091| `--author-email <email>` | 作者電子郵件 | `git config user.email` |

1092| `--with <components...>` | 同時建立元件資料夾的框架。有效值：`skills`、`agents`、`hooks`、`mcp`、`lsp`、`output-style`、`channel` | |

1093| `-f, --force` | 覆寫目標處現有的 `.claude-plugin/` | |

1094| `-h, --help` | 顯示命令說明 | |

~~1095~~

1096`claude plugin new` 是此命令的別名。

~~1097~~

1098每個 `--with` 值都會為該元件新增一個入門檔案，準備好編輯：

~~1099~~

1100| 元件 | 建立的內容 |

1101| :------------- | :------------------------------------------------------------------------------------------ |

1102| `skills` | 一個額外的命名空間 `<name>:example` 技能，與預設技能並列 |

1103| `agents` | 一個 `agents/` 子代理定義 |

1104| `hooks` | 一個 `hooks/hooks.json`，包含範例事件處理程式 |

1105| `mcp` | 一個 `.mcp.json`，包含 HTTP 和 stdio 伺服器範例 |

1106| `lsp` | 一個 `.lsp.json` 語言伺服器範例 |

1107| `output-style` | 一個 `output-styles/<name>.md`，在外掛程式啟用時自動套用 |

1108| `channel` | 一個基於 MCP 的[頻道](/docs/zh-TW/channels)：一個 stdio 伺服器 (`server.ts`)、其 `.mcp.json` 和一個 `package.json` |

~~1109~~

1110建立框架的外掛程式使用 `@skills-dir` 來源，而不是市集。管理員可以使用 `strictKnownMarketplaces` 或在[受管設定](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)中新增 `{"source": "skills-dir"}` 至 `blockedMarketplaces` 來封鎖此來源。當被封鎖時，`plugin init` 會在寫入前失敗。

~~1111~~

1112這些範例顯示常見的叫用方式：

~~1113~~

1114```bash theme={null}

1115# 建立最小外掛程式的框架

1116claude plugin init my-helper

~~1117~~

1118# 使用技能和掛鉤資料夾建立框架

1119claude plugin init my-helper --with skills hooks

~~1120~~

1121# 覆寫現有框架

1122claude plugin init my-helper --force

1123```

~~1124~~

1125<h3 id="plugin-install">

1126 plugin install

1127</h3>

~~1128~~

1129從可用市集安裝外掛程式。

~~1130~~

1131```bash theme={null}

1132claude plugin install <plugin> [options]

1133```

~~1134~~

1135該命令接受這些引數：

~~1136~~

1137* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name` 以指定特定市集

~~1138~~

1139該命令接受這些選項：

~~1140~~

1141| 選項 | 說明 | 預設值 |

1142| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |

1143| `-s, --scope <scope>` | 安裝範圍：`user`、`project` 或 `local` | `user` |

1144| `--config <key=value>` | 設定外掛程式資訊清單中宣告的 [`userConfig`](#user-configuration) 選項。重複此旗標以設定多個選項 | |

1145| `-y, --yes` | 接受外掛程式市集宣告的命令，無需確認提示：產生具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)的外掛程式的命令，或驗證封存下載的 [`headersHelper`](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更新版本。Claude Code 仍會先列印命令。當 stdin 或 stdout 不是 TTY 時為必需，除非您傳遞 `--accept-command`。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令 | |

1146| `--accept-command <sha256>` | 接受市集宣告的命令，其 `sha256` 先前的 [`--json` 執行](#plugin-json-result)在 `shownCommand` 中報告，以取代 `-y`。接受計數適用於完全相同的命令、外掛程式和市集目錄。如果自命令顯示以來任何一個已變更，包括透過執行本身的市集重新整理，Claude Code 不會接受摘要並再次顯示命令。無法與 `-y` 結合。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令。需要 Claude Code v2.1.271 或更新版本 | |

1147| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，供指令碼使用。請參閱 [JSON 結果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更新版本 | |

1148| `-h, --help` | 顯示命令說明 | |

~~1149~~

1150範圍決定已安裝外掛程式新增至哪個設定檔。例如，`--scope project` 會寫入 .claude/settings.json 中的 `enabledPlugins`，使外掛程式可供複製專案存放庫的所有人使用。

~~1151~~

1152<span id="plugin-json-result" />使用 `--json` 時，stdout 的最後一行是一個 JSON 物件。只解析該行，因為 Claude Code 會在其前面列印市集宣告的任何命令。三個欄位始終存在：

~~1153~~

1154* `command`：執行的子命令，例如 `install`

1155* `outcome`：`ok` 或 `failed`

1156* `message`：結果的人類可讀說明

~~1157~~

1158其他欄位，例如 `pluginId`、`scope` 和 `failureCode`，僅在適用時出現。`plugin uninstall`、`plugin update`、`plugin enable` 和 `plugin disable` 上的 `--json` 選項會列印具有該子命令自己欄位的相同物件。使用錯誤（例如無效的 `--scope`）不會列印結果行，並以 stderr 上的原因退出 1。

~~1159~~

1160當執行顯示市集宣告的命令且不執行它時，`failed` 結果也會攜帶一個 `shownCommand` 物件，其欄位包括顯示的命令、它所屬的外掛程式和命令的 `sha256`。若要接受完全相同的命令，請使用該 `sha256` 作為 `--accept-command` 重新執行。需要 Claude Code v2.1.271 或更新版本。

~~1161~~

1162如果 `shownCommand.acceptCommandMatched` 是 `false`，您傳遞的摘要與現在顯示的命令不符。在傳遞其 `sha256` 之前，向某人顯示該命令。

~~1163~~

1164這些範例顯示常見的叫用方式：

~~1165~~

1166```bash theme={null}

1167# 安裝至使用者範圍（預設）

1168claude plugin install formatter@my-marketplace

~~1169~~

1170# 安裝至專案範圍（與團隊共享）

1171claude plugin install formatter@my-marketplace --scope project

~~1172~~

1173# 安裝至本機範圍（不與團隊共享）

1174claude plugin install formatter@my-marketplace --scope local

1175```

~~1176~~

1177<h3 id="plugin-uninstall">

1178 plugin uninstall

1179</h3>

~~1180~~

1181移除已安裝的外掛程式。

~~1182~~

1183```bash theme={null}

1184claude plugin uninstall <plugin> [options]

1185```

~~1186~~

1187該命令接受這些引數：

~~1188~~

1189* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name`

~~1190~~

1191該命令接受這些選項：

~~1192~~

1193| 選項 | 說明 | 預設值 |

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

1195| `-s, --scope <scope>` | 從範圍解除安裝：`user`、`project` 或 `local` | `user` |

1196| `--keep-data` | 保留外掛程式的[持久資料目錄](#persistent-data-directory) | |

1197| `--prune` | 同時移除其他外掛程式不再需要的自動安裝相依性。請參閱 [plugin prune](#plugin-prune) | |

1198| `-y, --yes` | 跳過 `--prune` 確認提示。當 stdin 或 stdout 不是 TTY 時為必需 | |

1199| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。無法與 `--prune` 結合。需要 Claude Code v2.1.268 或更新版本 | |

1200| `-h, --help` | 顯示命令說明 | |

~~1201~~

1202`claude plugin remove` 和 `claude plugin rm` 是此命令的別名。

~~1203~~

1204根據預設，從最後剩餘的範圍解除安裝也會刪除外掛程式的 `${CLAUDE_PLUGIN_DATA}` 目錄。使用 `--keep-data` 保留它，例如在測試新版本後重新安裝時。

~~1205~~

1206<Note>

1207 當來自不同市集的已安裝外掛程式共享名稱時，`plugin-name@marketplace-name` 形式只會解除安裝來自指定市集的外掛程式。在 v2.1.212 之前，合格形式可能會符合並解除安裝來自不同市集的同名外掛程式。

1208</Note>

~~1209~~

1210<h3 id="plugin-prune">

1211 plugin prune

1212</h3>

~~1213~~

1214移除不再由任何已安裝外掛程式需要的自動安裝外掛程式相依性。Claude Code 為滿足另一個外掛程式的 [`dependencies`](/docs/zh-TW/plugin-dependencies) 欄位而拉入的相依性會被移除；您直接安裝的外掛程式永遠不會被觸及。

~~1215~~

1216```bash theme={null}

1217claude plugin prune [options]

1218```

~~1219~~

1220該命令接受這些選項：

~~1221~~

1222| 選項 | 說明 | 預設值 |

1223| :-------------------- | :---------------------------------- | :----- |

1224| `-s, --scope <scope>` | 在範圍進行清理：`user`、`project` 或 `local` | `user` |

1225| `--dry-run` | 列出將被移除的內容，但不實際移除 | |

1226| `-y, --yes` | 跳過確認提示。當 stdin 或 stdout 不是 TTY 時為必需 | |

1227| `-h, --help` | 顯示命令說明 | |

~~1228~~

1229`claude plugin autoremove` 是此命令的別名。

~~1230~~

1231該命令列出孤立的相依性，並在移除前要求確認。若要在一個步驟中移除外掛程式並清理其相依性，請執行 `claude plugin uninstall <plugin> --prune`。

~~1232~~

1233<h3 id="plugin-enable">

1234 plugin enable

1235</h3>

~~1236~~

1237啟用已停用的外掛程式。當目標從市集安裝並宣告[相依性](/docs/zh-TW/plugin-dependencies)時，Claude Code 會在相同範圍內以遞移方式啟用它們。該命令在[啟用或停用具有相依性的外掛程式](/docs/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)列出的條件下失敗。

~~1238~~

1239```bash theme={null}

1240claude plugin enable <plugin> [options]

1241```

~~1242~~

1243該命令接受這些引數：

~~1244~~

1245* `<plugin>`：外掛程式名稱、`plugin-name@marketplace-name` 或 `plugin-name@synced` 用於[從 claude.ai 同步的外掛程式](#synced-plugins)

~~1246~~

1247該命令接受這些選項：

~~1248~~

1249| 選項 | 說明 | 預設值 |

1250| :-------------------- | :---------------------------------------------------------------------------------------------------------------- | :--- |

1251| `-s, --scope <scope>` | 要啟用的範圍：`user`、`project` 或 `local`。省略時，Claude Code 會偵測安裝外掛程式的範圍 | 自動偵測 |

1252| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 | |

1253| `-h, --help` | 顯示命令說明 | |

~~1254~~

1255<h3 id="plugin-disable">

1256 plugin disable

1257</h3>

~~1258~~

1259停用外掛程式而不解除安裝它。

~~1260~~

1261當目標從市集安裝時，如果另一個已啟用的外掛程式[依賴](/docs/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)它，該命令會失敗。錯誤訊息包含一個鏈式命令，可先停用每個依賴它的外掛程式。

~~1262~~

1263對於您的組織需要的[同步外掛程式](#synced-plugins)，該命令會失敗且不會儲存任何內容。

~~1264~~

1265```bash theme={null}

1266claude plugin disable [plugin] [options]

1267```

~~1268~~

1269該命令接受這些引數：

~~1270~~

1271* `[plugin]`：外掛程式名稱、`plugin-name@marketplace-name` 或 `plugin-name@synced` 用於[從 claude.ai 同步的外掛程式](#synced-plugins)。使用 `--all` 時為選用。

~~1272~~

1273該命令接受這些選項：

~~1274~~

1275| 選項 | 說明 | 預設值 |

1276| :-------------------- | :---------------------------------------------------------------------------------------------------------------- | :--- |

1277| `-a, --all` | 停用所有已啟用的外掛程式。無法與 `--scope` 結合 | |

1278| `-s, --scope <scope>` | 要停用的範圍：`user`、`project` 或 `local`。省略時，Claude Code 會偵測安裝外掛程式的範圍 | 自動偵測 |

1279| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 | |

1280| `-h, --help` | 顯示命令說明 | |

~~1281~~

1282<h3 id="plugin-update">

1283 plugin update

1284</h3>

~~1285~~

1286將外掛程式更新至最新版本。

~~1287~~

1288```bash theme={null}

1289claude plugin update <plugin> [options]

1290```

~~1291~~

1292該命令接受這些引數：

~~1293~~

1294* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name`

~~1295~~

1296該命令接受這些選項：

~~1297~~

1298| 選項 | 說明 | 預設值 |

1299| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |

1300| `-s, --scope <scope>` | 要更新的範圍：`user`、`project`、`local` 或 `managed` | `user` |

1301| `-y, --yes` | 接受外掛程式市集宣告的命令，無需確認提示：產生具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)的外掛程式的命令，或驗證封存下載的 [`headersHelper`](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更新版本。Claude Code 仍會先列印命令。當 stdin 或 stdout 不是 TTY 時為必需，除非您傳遞 `--accept-command`。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令 | |

1302| `--accept-command <sha256>` | 接受市集宣告的命令，其 `sha256` 先前的 [`--json` 執行](#plugin-json-result)在 `shownCommand` 中報告，以取代 `-y`。接受計數適用於完全相同的命令、外掛程式和市集目錄。如果自命令顯示以來任何一個已變更，包括透過執行本身的市集重新整理，Claude Code 不會接受摘要並再次顯示命令。無法與 `-y` 結合。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令。需要 Claude Code v2.1.271 或更新版本 | |

1303| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 | |

1304| `-h, --help` | 顯示命令說明 | |

~~1305~~

1306<Note>

1307 Claude Code 根據您已安裝的外掛程式解析裸外掛程式名稱。當來自不同市集的已安裝外掛程式共享名稱時，Claude Code 會拒絕更新並列出要執行的合格 `plugin-name@marketplace-name` 命令。在 v2.1.246 之前，Claude Code 只接受合格形式，並將裸名稱拒絕為未找到。

1308</Note>

~~1309~~

1310***

~~1311~~

1312<h3 id="plugin-list">

1313 plugin list

1314</h3>

~~1315~~

1316列出已安裝的外掛程式及其版本、來源市集和啟用狀態。

~~1317~~

1318```bash theme={null}

1319claude plugin list [options]

1320```

~~1321~~

1322該命令接受這些選項：

~~1323~~

1324| 選項 | 說明 | 預設值 |

1325| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-- |

1326| `--json` | 輸出為 JSON。具有載入問題或編寫警告的外掛程式列會攜帶 `errors` 或 `notes` 字串陣列。在 Claude Code v2.1.268 或更新版本上，平行的 `errorDetails` 和 `noteDetails` 陣列會提供每個項目的診斷 `type` 和它所指的名稱，例如外掛程式、市集、伺服器或檔案 | |

1327| `--available` | 包含市集中的可用外掛程式。需要 `--json` | |

1328| `-h, --help` | 顯示命令說明 | |

~~1329~~

1330在互動式工作階段中，`/plugin list` 會列印類似的列表內容，但它只涵蓋市集安裝的外掛程式：

~~1331~~

1332* 從技能目錄載入的外掛程式會在 `/plugin` 介面和 `claude plugin list` 中出現，但不會在內嵌 `/plugin list` 輸出中出現。

1333* [從 claude.ai 同步的外掛程式](#synced-plugins)會在 Claude Code v2.1.239 或更新版本上的 `claude plugin list` 中出現，並在 `/plugin` 介面中出現，但不會在內嵌 `/plugin list` 輸出中出現。

1334* 使用 `--plugin-dir` 或 `--plugin-url` 為工作階段載入的外掛程式會在 `/plugin` 介面中出現，並且在相同旗標位於子命令前時才會在 `claude plugin list` 中出現，如 `claude --plugin-dir <dir> plugin list`。只有旗標名稱會指出它們的位置，因此裸 `claude plugin list` 無法找到它們，不同於同步外掛程式和技能目錄外掛程式，Claude Code 會掃描其固定目錄。

~~1335~~

1336互動式形式接受 `--enabled` 或 `--disabled` 以僅顯示該狀態中的外掛程式，並接受 `ls` 作為 `list` 的簡寫。

~~1337~~

1338<h3 id="plugin-details">

1339 plugin details

1340</h3>

~~1341~~

1342顯示外掛程式的元件清單和預計權杖成本。輸出列出外掛程式貢獻的所有元件，分組為技能、代理、掛鉤、MCP 伺服器和 LSP 伺服器，以及它為每個工作階段新增多少權杖的估計。技能群組包括 `skills/` 和 `commands/` 項目。

~~1343~~

1344```bash theme={null}

1345claude plugin details <name>

1346```

~~1347~~

1348該命令接受這些引數：

~~1349~~

1350* `<name>`：外掛程式名稱或 `plugin-name@marketplace-name`

~~1351~~

1352該命令接受這些選項：

~~1353~~

1354| 選項 | 說明 | 預設值 |

1355| :----------- | :----- | :-- |

1356| `-h, --help` | 顯示命令說明 | |

~~1357~~

1358輸出為每個元件顯示兩個成本數字：

~~1359~~

1360* **Always-on：** 外掛程式的列表文字（例如技能說明、代理說明和命令名稱）無論任何元件是否觸發，都會新增至每個工作階段的權杖。

1361* **On-invoke：** 元件觸發時的成本。按元件顯示，而不是外掛程式總計，因為典型工作階段只會叫用元件的子集。

~~1362~~

1363此範例顯示具有兩個技能的外掛程式的輸出外觀：

~~1364~~

1365```

1366dependency-guard 1.2.0

1367 Dependency analysis for Claude Code sessions

1368 Source: dependency-guard@example-marketplace

~~1369~~

1370Component inventory

1371 Skills (2) scan-dependencies, review-changes

1372 Agents (0)

1373 Hooks (1) SessionStart (harness-only — no model context cost)

1374 MCP servers (0)

1375 LSP servers (0)

~~1376~~

1377Projected token cost

1378 Always-on: ~180 tok added to every session

~~1379~~

1380Per-component (rounded)

1381 component always-on on-invoke

1382 scan-dependencies ~100 ~2400

1383 review-changes ~80 ~1800

~~1384~~

1385 On-invoke cost is paid each time a skill or agent fires.

1386 Token counts are estimates and may differ from actual usage.

1387```

~~1388~~

1389always-on 總計是透過您的作用中模型的 `count_tokens` API 計算的。按元件的數字按比例從該總計縮放。如果 API 無法到達，該命令會回退至基於字元的估計。

~~1390~~

1391<h3 id="plugin-validate">

1392 plugin validate

1393</h3>

~~1394~~

1395在發佈前檢查外掛程式或市集是否有語法和結構描述錯誤。

~~1396~~

1397當驗證通過時命令退出 0，失敗時退出 1，驗證執行本身失敗時退出 2，例如當您傳遞的路徑無法讀取時。

~~1398~~

1399```bash theme={null}

1400claude plugin validate <path> [options]

1401```

~~1402~~

1403該命令接受這些引數：

~~1404~~

1405* `<path>`：外掛程式目錄或市集目錄的路徑。請參閱[驗證沒有資訊清單的外掛程式或目錄](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)以了解外掛程式執行涵蓋的檔案。

~~1406~~

1407該命令接受這些選項：

~~1408~~

1409| 選項 | 說明 | 預設值 |

1410| :----------- | :---------------------------------------------------------------------- | :-- |

1411| `--strict` | 將警告視為錯誤，並在警告時退出 1。在 CI 中使用以捕捉執行時容許的問題，例如[無法識別的欄位](#unrecognized-fields) | |

1412| `--json` | 將驗證報告輸出為一個 JSON 物件，具有相同的退出代碼。需要 Claude Code v2.1.259 或更新版本 | |

1413| `-h, --help` | 顯示命令說明 | |

~~1414~~

1415使用 `--json` 時，Claude Code 會將報告寫入 stdout 作為一個 JSON 物件，具有這些頂層欄位：

~~1416~~

1417* `success`：退出代碼給出的相同判決

1418* `strict`：執行是否將警告視為錯誤

1419* `target`：Claude Code 驗證的已解析路徑

1420* `manifest`：資訊清單本身的結果，或 `null` 用於[沒有資訊清單的執行](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)

1421* `contents`：按檔案結果，每個命名其 `file` 並攜帶 `errors`、`warnings` 和 `notes` 陣列

~~1422~~

1423退出 2 時，該命令不會向 stdout 寫入任何內容；錯誤訊息會進入 stderr。

~~1424~~

1425在互動式工作階段中，`/plugin validate <path>` 會內嵌執行相同的檢查。

~~1426~~

1427<h3 id="plugin-eval">

1428 plugin eval

1429</h3>

~~1430~~

1431執行外掛程式的[評估案例](/docs/zh-TW/plugin-evals)並報告評分結果。需要 Claude Code v2.1.269 或更新版本。每個案例都是一個提示加評分者；Claude Code 在隔離的工作階段中執行它多次，只載入目標外掛程式，預設情況下也不載入外掛程式，以便報告顯示差異。請參閱[使用評估測試外掛程式](/docs/zh-TW/plugin-evals)以了解案例格式、評分者、結果和 CI 使用。

~~1432~~

1433```bash theme={null}

1434claude plugin eval [target] [options]

1435```

~~1436~~

1437選用的 `target` 是外掛程式目錄、單個 `prompt.md` 或 `case.yaml` 檔案、已安裝的外掛程式作為 `name` 或 `name@marketplace`，或 `name@skills-dir`，預設為目前目錄。將其放在 `--tag`、`--allow-tools` 和 `--json` 之前。

~~1438~~

1439此表列出大多數執行使用的選項。執行 `claude plugin eval --help` 以取得完整集合，包括 `--case`、`--tag`、`--output-dir`、`--report`、`--allow-real-servers`、`--keep-temp` 和 `--verbose`。

~~1440~~

1441| 選項 | 說明 | 預設值 |

1442| :------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |

1443| `--runs <n>` | 每個案例每個臂的執行次數 | 每個案例的 `runs`，否則 3 |

1444| `-j, --concurrency <n>` | 同時執行的代理工作階段，1 到 8。它們共享您的速率限制 | `1` |

1445| `--model <model>` | 受測代理的模型 | 每個案例的 `model`，否則 `ANTHROPIC_MODEL`（如果設定），否則 Claude Code 的預設值 |

1446| `--judge-model <model>` | `llm` 和 `baseline` 評分者的模型 | 一個小型快速模型 |

1447| `--ablation <mode>` | `none` 或 `with-without`。請參閱[與無外掛程式基線比較](/docs/zh-TW/plugin-evals#compare-against-a-no-plugin-baseline) | 當外掛程式解析時為 `with-without`，否則為 `none` |

1448| `--threshold <0..1>` | 如果任何案例評分低於此值，退出 1 | `1.0` |

1449| `--max-cost-usd <usd>` | 一旦支出達到此值，停止下一次執行，退出 2，並報告部分結果 | 無上限 |

1450| `--allow-tools <tools...>` | 授予超過唯讀集合的工具，例如 `Bash`、`Write`、`Edit` 或 `"mcp__plugin_<plugin>_<server>__*"`。請參閱[授予工具](/docs/zh-TW/plugin-evals#grant-tools) | |

1451| `--scaffold` | 執行每個案例的 [`scaffold_script`](/docs/zh-TW/plugin-evals#add-setup-or-history-with-case-yaml) | 關閉 |

1452| `--trust-plugin` | 跳過首次執行信任提示，用於 CI。請參閱[執行可以存取的內容](/docs/zh-TW/plugin-evals#security) | 關閉 |

1453| `--mocks <mode>` | `record` 或 `off`。請參閱[模擬 MCP 伺服器](/docs/zh-TW/plugin-evals#mock-mcp-servers) | `record` |

1454| `--eval-dir <dir>` | 保存案例的外掛程式下方的目錄 | 資訊清單的 `experimental.evals`，否則 `evals` |

1455| `--json [path]` | 將[結果文件](/docs/zh-TW/plugin-evals#json-result)列印至 stdout，或將其寫入 `.json` 路徑 | |

1456| `--no-publish` | 保持 HTML 報告本機 | |

1457| `-h, --help` | 顯示命令說明 | |

~~1458~~

1459當每個案例都符合閾值時，命令退出 0，在失敗案例、載入錯誤或不受信任的外掛程式目錄時退出 1，在部分執行時退出 2，中斷時退出 130，終止時退出 143。請參閱[在 CI 中執行評估](/docs/zh-TW/plugin-evals#run-evals-in-ci)。

~~1460~~

1461<h3 id="plugin-eval-init">

1462 plugin eval init

1463</h3>

~~1464~~

1465為目前目錄中的外掛程式建立評估套件。需要 Claude Code v2.1.269 或更新版本。在終端中，這會啟動一個編寫訪談，讀取外掛程式、提議案例和評分者、試驗它們，並寫入檔案。使用 `--bare` 或沒有終端時，它會改為寫入一個空白的單案例範本。從互動式 Claude Code 工作階段內執行時，它會列印該工作階段要遵循的訪談說明，而不是寫入範本。請參閱[建立您的第一個評估套件](/docs/zh-TW/plugin-evals#create-your-first-eval-suite)。

~~1466~~

1467```bash theme={null}

1468claude plugin eval init [name] [options]

1469```

~~1470~~

1471選用的 `name` 是案例名稱：訪談不需要一個，而 `--bare` 和無終端範本路徑需要一個。它接受這些選項：

~~1472~~

1473| 選項 | 說明 | 預設值 |

1474| :------------------ | :---------------------------------------------------- | :------------------------------------ |

1475| `--bare` | 改為為 `<name>` 寫入空白 `prompt.md` 和 `graders/criteria.md` | |

1476| `-i, --interactive` | 需要訪談。沒有終端時失敗，而不是寫入範本 | |

1477| `--eval-dir <dir>` | 目前目錄下方寫入案例的目錄 | 資訊清單的 `experimental.evals`，否則 `evals` |

1478| `-h, --help` | 顯示命令說明 | |

~~1479~~

1480<h3 id="plugin-tag">

1481 plugin tag

1482</h3>

~~1483~~

1484為外掛程式建立發行 git 標籤。根據預設，該命令會標籤目前目錄中的外掛程式；傳遞路徑以標籤其他位置的外掛程式。請參閱[標籤外掛程式發行](/docs/zh-TW/plugin-dependencies#tag-plugin-releases-for-version-resolution)。

~~1485~~

1486```bash theme={null}

1487claude plugin tag [path] [options]

1488```

~~1489~~

1490該命令接受這些引數：

~~1491~~

1492* `[path]`：外掛程式目錄的路徑。預設為目前目錄。

~~1493~~

1494該命令接受這些選項：

~~1495~~

1496| 選項 | 說明 | 預設值 |

1497| :-------------------- | :----------------------- | :------- |

1498| `--push` | 建立標籤後將其推送至遠端 | |

1499| `--dry-run` | 列印將被標籤的內容，但不建立標籤 | |

1500| `-f, --force` | 即使工作樹髒污或標籤已存在，也建立標籤 | |

1501| `-m, --message <msg>` | 標籤註解訊息。使用 `%s` 作為版本的預留位置 | |

1502| `--remote <name>` | 使用 `--push` 推送至的遠端 | `origin` |

1503| `-h, --help` | 顯示命令說明 | |

~~1504~~

1505***

~~1506~~

1507<h2 id="debugging-and-development-tools">

1508 除錯和開發工具

1509</h2>

~~1510~~

1511<h3 id="debugging-commands">

1512 除錯命令

1513</h3>

~~1514~~

1515使用 `claude --debug` 查看外掛程式載入詳細資訊：

~~1516~~

1517這會顯示：

~~1518~~

1519* 正在載入哪些外掛程式

1520* 外掛程式清單中的任何錯誤

1521* Skill、agent 和 hook 註冊

1522* MCP 伺服器初始化

~~1523~~

1524<h3 id="common-issues">

1525 常見問題

1526</h3>

~~1527~~

1528| 問題 | 原因 | 解決方案 |

1529| :---------------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1530| 外掛程式未載入 | 無效的 `plugin.json` | 執行 `claude plugin validate ./my-plugin` 或 `/plugin validate ./my-plugin`，其中 `./my-plugin` 是您的外掛程式目錄，以檢查 `plugin.json`、`hooks/hooks.json` 以及外掛程式預設目錄中的 skills、agents 和 commands 的前置資訊是否有語法和結構描述錯誤。請參閱[驗證外掛程式或沒有清單的目錄](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)以了解執行涵蓋的內容 |

1531| Skills 未出現 | 目錄結構錯誤 | 確保 `skills/` 或 `commands/` 位於外掛程式根目錄，而不是在 `.claude-plugin/` 內 |

1532| Hooks 未觸發 | 指令碼不可執行 | 執行 `chmod +x script.sh` |

1533| MCP 伺服器失敗 | 缺少 `${CLAUDE_PLUGIN_ROOT}` | 對所有外掛程式路徑使用變數 |

1534| 路徑錯誤 | 使用了絕對路徑 | 使路徑相對，以 `./` 開頭；請參閱[路徑行為規則](#path-behavior-rules)，其中涵蓋了 `skills` 欄位的 `"."` 例外 |

1535| LSP `Executable not found in $PATH` | 語言伺服器未安裝 | 安裝二進位檔案（例如，`npm install -g typescript-language-server typescript`） |

~~1536~~

1537<h3 id="example-error-messages">

1538 範例錯誤訊息

1539</h3>

~~1540~~

1541**清單驗證錯誤**：

~~1542~~

1543* `Invalid JSON syntax: Unexpected token } in JSON at position 142`：檢查是否缺少逗號、多餘逗號或未加引號的字串

1544* `Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined`：缺少必需欄位

1545* `Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`：JSON 語法錯誤。在 v2.1.246 之前，Claude Code 也會針對以位元組順序標記 (BOM) 儲存為 UTF-8 的 `plugin.json` 產生此錯誤，即使 JSON 在其他方面有效。

~~1546~~

1547**外掛程式載入錯誤**：

~~1548~~

1549* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`：命令路徑存在但不包含有效的命令檔案

1550* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`：marketplace.json 中的 `source` 路徑指向不存在的目錄

1551* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`：移除重複的元件定義或移除 marketplace 項目中的 `strict: false`

~~1552~~

1553<h3 id="hook-troubleshooting">

1554 Hook 除錯

1555</h3>

~~1556~~

1557**Hook 指令碼未執行**：

~~1558~~

15591. 檢查指令碼是否可執行：`chmod +x ./scripts/your-script.sh`

15602. 驗證 shebang 行：第一行應為 `#!/bin/bash` 或 `#!/usr/bin/env bash`

15613. 檢查路徑是否使用 `${CLAUDE_PLUGIN_ROOT}`：`"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`

15624. 手動測試指令碼：`./scripts/your-script.sh`

~~1563~~

1564**Hook 未在預期事件上觸發**：

~~1565~~

15661. 驗證事件名稱正確（區分大小寫）：`PostToolUse`，而不是 `postToolUse`

15672. 檢查匹配器模式是否與您的工具相符：`"matcher": "Write|Edit"` 用於檔案操作

15683. 確認 hook 類型有效：`command`、`http`、`mcp_tool`、`prompt` 或 `agent`

~~1569~~

1570<h3 id="mcp-server-troubleshooting">

1571 MCP 伺服器除錯

1572</h3>

~~1573~~

1574**伺服器未啟動**：

~~1575~~

15761. 檢查命令是否存在且可執行

15772. 驗證所有路徑都使用 `${CLAUDE_PLUGIN_ROOT}` 變數

15783. 檢查 MCP 伺服器日誌：`claude --debug` 顯示初始化錯誤

15794. 在 Claude Code 外手動測試伺服器

~~1580~~

1581**伺服器工具未出現**：

~~1582~~

15831. 確保伺服器在 `.mcp.json` 或 `plugin.json` 中正確設定

15842. 驗證伺服器正確實作 MCP 協定

15853. 檢查除錯輸出中的連線逾時

~~1586~~

1587<h3 id="directory-structure-mistakes">

1588 目錄結構錯誤

1589</h3>

~~1590~~

1591**症狀**：外掛程式載入但元件（skills、agents、hooks）遺失。

~~1592~~

1593**正確結構**：元件必須位於外掛程式根目錄，而不是在 `.claude-plugin/` 內。只有 `plugin.json` 屬於 `.claude-plugin/`。

~~1594~~

1595**除錯檢查清單**：

~~1596~~

15971. 執行 `claude --debug` 並查找「loading plugin」訊息

15982. 檢查每個元件目錄是否列在除錯輸出中

15993. 驗證檔案權限允許讀取外掛程式檔案

~~1600~~

1601***

~~1602~~

1603<h2 id="distribution-and-versioning-reference">

1604 發佈和版本管理參考

1605</h2>

~~1606~~

1607<h3 id="version-management">

1608 版本管理

1609</h3>

~~1610~~

1611Claude Code 使用外掛程式的版本作為快取金鑰，以判斷是否有可用的更新。當您執行 `/plugin update` 或自動更新觸發時，Claude Code 會計算目前版本，如果與已安裝的版本相符，則跳過更新。從[本機目錄市集](#plugin-caching-and-file-resolution)載入的外掛程式會在每次工作階段開始時載入其目前的來源檔案，無論其版本字串說什麼。

~~1612~~

1613對於除了 `command` 以外的每種來源類型，Claude Code 會從以下第一個已設定的項目解析版本：

~~1614~~

16151. 外掛程式 `plugin.json` 中的 `version` 欄位

16162. 外掛程式在 `marketplace.json` 中的市集項目中的 `version` 欄位

16173. 外掛程式來源的 git 提交 SHA，適用於 git 託管市集中的 `github`、`url`、`git-subdir` 和相對路徑來源

16184. SHA-256 摘要，適用於 [`archive` 來源](/docs/zh-TW/plugin-marketplaces#zip-archives)：市集項目中的 `sha256` 釘選，或當您未設定釘選時下載檔案的摘要。Claude Code 將其縮短為前 12 個字元

16195. `unknown`，適用於 `npm` 來源或不在 git 儲存庫內的本機目錄。Claude Code 不會從包含安裝路徑的儲存庫（例如 git 管理的 `~/.claude`）中取得版本

~~1620~~

1621對於 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)，Claude Code 始終從命令產生的內容衍生版本：單獨的 12 字元內容雜湊，或在設定了一個時附加到 `plugin.json` 版本作為 `<version>-<hash>`。Claude Code 會忽略命令來源的市集項目 `version` 欄位。因此，命令的雜湊輸出變更會產生新版本，即使編寫的版本字串保持不變。在[連結模式](/docs/zh-TW/plugin-marketplaces#copy-mode-and-link-mode)中，雜湊涵蓋列印目錄的實際路徑及其頂層項目，而不是檔案內容。

~~1622~~

1623對於這些來源類型，這為您提供了三種方式來版本化外掛程式：

~~1624~~

1625| 方法 | 如何操作 | 更新行為 | 最適合 |

1626| :------------ | :-------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :--------------------------- |

~~1630~~

1631如果您使用明確版本，請遵循[語義版本控制](https://semver.org)（`MAJOR.MINOR.PATCH`）：針對重大變更更新 MAJOR，針對新功能更新 MINOR，針對錯誤修正更新 PATCH。在 `CHANGELOG.md` 中記錄變更。

~~1632~~

1633***

~~1634~~

1635<h2 id="see-also">

1636 另請參閱

1637</h2>

~~1638~~

1639* [Plugins](/docs/zh-TW/plugins) - 教學和實際使用

1640* [Plugin marketplaces](/docs/zh-TW/plugin-marketplaces) - 建立和管理 marketplaces

1641* [Skills](/docs/zh-TW/skills) - Skill 開發詳細資訊

1642* [Subagents](/docs/zh-TW/sub-agents) - Agent 設定和功能

1643* [Hooks](/docs/zh-TW/hooks) - 事件處理和自動化

1644* [MCP](/docs/zh-TW/mcp) - 外部工具整合

1645* [Settings](/docs/zh-TW/settings) - Plugins 的設定選項

plugins/anthropic-marketplaces.md +103 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Anthropic 的 marketplace

7> Anthropic 官方、社群和示範 plugin marketplace for Claude Code：它們的名稱、儲存庫、如何新增每個，以及在哪裡瀏覽它們的 plugin。

9Anthropic 為 Claude Code 發佈三個通用 plugin marketplace：[官方](https://github.com/anthropics/claude-plugins-official)、[社群](https://github.com/anthropics/claude-plugins-community)和[示範](https://github.com/anthropics/claude-code)。每個都是其自身 GitHub 儲存庫中的 plugin 目錄。當您在 Claude Code 工作階段中從其中一個安裝 plugin 時，您在 `@` 後輸入 marketplace 的名稱，如 `/plugin install commit-commands@claude-plugins-official`。

11使用此頁面來區分三個 marketplace，並找到檢查官方 marketplace 是否包含給定 plugin 的位置。

13<Note>

14 這些情況在其他頁面上涵蓋：

16 * **如何安裝 plugin**：請參閱[安裝 plugin](/docs/zh-TW/plugins/install)

17 * **安裝失敗**：請參閱[plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting)

18</Note>

20前往您需要的頁面部分：

22* 若要按儲存庫、marketplace 名稱和取得方式區分三個 marketplace，請參閱 [Anthropic 的 marketplace](#anthropic%E2%80%99s-marketplaces)。

23* 若要在官方 marketplace 中尋找 plugin，請參閱[在官方 marketplace 中尋找 plugin](#find-plugins-in-the-official-marketplace)。

25<h2 id="anthropic’s-marketplaces">

26 Anthropic 的 marketplace

27</h2>

29Marketplace 是儲存庫在其 `.claude-plugin/marketplace.json` 檔案中定義的 plugin 目錄。官方、社群和示範 marketplace 各自來自其自身的 GitHub 儲存庫。Anthropic 也發佈主題特定的 marketplace，例如 `anthropics/skills` 和 `anthropics/knowledge-work-plugins`，您可以在 Claude Code 工作階段中使用 `/plugin marketplace add <owner>/<repo>` 新增。

31此表格提供每個 marketplace 的儲存庫和 marketplace 名稱，這是您從該 marketplace 安裝 plugin 時在 `@` 後輸入的內容。社群 marketplace 的名稱是 `claude-community`，而不是其儲存庫名稱。

33| | 官方 | 社群 | 示範 |

34| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- |

35| 儲存庫 | [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official) | [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) | [`anthropics/claude-code`](https://github.com/anthropics/claude-code/tree/main/plugins) |

38| 取得方式 | Claude Code 在您第一次啟動互動式終端工作階段時新增它，除非[受管原則](/docs/zh-TW/plugins/org#allow-the-official-marketplace-and-your-own)或 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 阻止它。如果遺失，請參閱 [Marketplace `claude-plugins-official` 找不到](/docs/zh-TW/plugins/troubleshooting#marketplace-claude-plugins-official-not-found) | 您在 Claude Code 工作階段中使用 `/plugin marketplace add anthropics/claude-plugins-community` 新增它 | 您在 Claude Code 工作階段中使用 `/plugin marketplace add anthropics/claude-code` 新增它 |

40如果您編寫了 plugin 並希望其他人安裝它，請參閱[發佈 plugin](/docs/zh-TW/plugins/publish)，其涵蓋您自己的 marketplace 和提交到社群 marketplace。

42<h3 id="the-demo-marketplace-in-anthropics/claude-code">

43 `anthropics/claude-code` 中的示範 marketplace

44</h3>

46如果教學課程或較舊的指示集告訴您執行 `/plugin marketplace add anthropics/claude-code`，這會新增示範 marketplace，名為 `claude-code-plugins`。這不是官方 marketplace，Claude Code 已經為您新增了。

48示範 marketplace 的大多數 plugin 也在官方 marketplace 中以相同名稱存在。例如，`code-review`、`feature-dev`、`commit-commands` 和 `security-guidance` 在兩者中都有。從 `claude-plugins-official` 安裝這些，以免安裝了兩份副本。

50<h2 id="find-plugins-in-the-official-marketplace">

51 在官方 marketplace 中尋找 plugin

52</h2>

54官方 marketplace `claude-plugins-official` 是 Claude Code 為您新增的。它列出的大部分內容來自合作夥伴和其他作者，而不是來自 Anthropic：工具供應商發佈將 Claude Code 連接到其服務的 plugin，Anthropic 維護一個較小的自有集合，例如 `commit-commands`、`code-review`、`feature-dev` 和[語言伺服器 plugin](/docs/zh-TW/plugins/code-intelligence)。目錄經常變化，所以此頁面不列出它。

56若要查看其中的內容，請在 Claude Code 工作階段中使用 `/plugin` 的 **Discover** 標籤（您可以搜尋），或在網路上瀏覽 [Claude Marketplace](https://claude.com/marketplace/plugins)。

58<h2 id="browse-and-install-from-anthropic’s-marketplaces">

59 從 Anthropic 的 marketplace 瀏覽和安裝

60</h2>

62您可以在 Claude Code、網路或 GitHub 上搜尋 Anthropic 的 marketplace 中的 plugin：

64* **在 Claude Code 中，透過瀏覽**：在互動式工作階段中執行 `/plugin`。其 **Discover** 標籤列出您已新增的 marketplace 中的 plugin。

65* **在 Claude Code 中，按名稱**：在工作階段中執行 `/plugin install <name>`，它會在您已新增的 marketplace 中查詢名稱。如果 plugin 在其中之一，其詳細資訊會在 `/plugin` 面板中開啟，在您選擇[安裝範圍](/docs/zh-TW/plugins/install#install-a-plugin)並確認之前，不會安裝任何內容。如果不在，您會看到 `Plugin "<name>" not found in any marketplace`。

66* **在網路上**：在 [Claude Marketplace](https://claude.com/marketplace/plugins) 上搜尋完整目錄，其顯示安裝計數並標記某些 plugin 為 **Anthropic verified**。

67* **在 GitHub 上**：在 marketplace 的儲存庫中開啟 `.claude-plugin/marketplace.json`，例如 [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official)。該檔案就是目錄本身。

69若要從桌面應用程式或指令碼安裝，或查看雲端工作階段載入的內容，請參閱[安裝 plugin](/docs/zh-TW/plugins/install)。

71<h3 id="add-the-community-or-demo-marketplace">

72 新增社群或示範 marketplace

73</h3>

75社群和示範 marketplace 在您在 Claude Code 工作階段中新增它們之前不會註冊：

77* **社群**：執行 `/plugin marketplace add anthropics/claude-plugins-community`，然後使用 `@claude-community` 尾碼安裝。

78* **示範**：執行 `/plugin marketplace add anthropics/claude-code`，然後使用 `@claude-code-plugins` 尾碼安裝。

80如果 `claude-plugins-official` 不在 `/plugin` 的 **Marketplaces** 標籤上，使用 `/plugin marketplace add anthropics/claude-plugins-official` 以相同方式新增它。

82如需 `not found` 錯誤和無法新增的 marketplace，請參閱[plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#install-a-plugin)。

84<h2 id="third-party-marketplaces">

85 第三方 marketplace

86</h2>

88許多熱門 plugin 不在任何 Anthropic marketplace 中。它們在其作者自己的 marketplace 中，通常是在其根目錄中具有 `.claude-plugin/marketplace.json` 的 GitHub 儲存庫。

90Anthropic 不審查第三方 marketplace，所以在新增一個之前，請閱讀 [Plugin 安全性和信任](/docs/zh-TW/plugins/security)。

92若要使用第三方 marketplace，在 Claude Code 工作階段中使用 `/plugin marketplace add <owner>/<repo>` 新增其儲存庫，然後使用 `/plugin install <plugin>@<marketplace-name>` 安裝。marketplace 名稱是該 `marketplace.json` 的 `name` 欄位，Claude Code 在新增 marketplace 後會列印它。

94如需新增 marketplace 的其他方式，請參閱[新增 marketplace](/docs/zh-TW/plugins/install#add-a-marketplace)。

96<h2 id="next-steps">

97 後續步驟

98</h2>

100* [安裝和管理 plugin](/docs/zh-TW/plugins/install)：從其中一個 marketplace 安裝 plugin 並選擇範圍

101* [Plugin 安全性和信任](/docs/zh-TW/plugins/security)：plugin 可以在您的機器上執行的操作，以及在安裝前如何檢查一個

102* [程式碼智慧 plugin](/docs/zh-TW/plugins/code-intelligence)：安裝官方 marketplace 的語言伺服器 plugin 之一

103* [建立 marketplace](/docs/zh-TW/plugins/create-marketplace)：在 Anthropic 的旁邊執行您自己的 marketplace

plugins/cli-hints.md +136 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 從您的 CLI 推薦您的外掛程式

7> 透過從您的 CLI 或 SDK 發出 claude-code-hint 標籤，提示 Claude Code 使用者安裝您的官方市場外掛程式。

9如果您維護 CLI 或 SDK，您的工具可以提示 Claude Code 使用者安裝您的外掛程式。當您的 CLI 偵測到它在 Claude Code 內執行時，應該將一行 `<claude-code-hint />` 標籤寫入 stderr。Claude Code 會在模型看到輸出之前從 Bash 和 PowerShell 工具輸出中移除該行，然後向使用者顯示一次性安裝提示。

11此頁面僅適用於您的外掛程式列在 `claude-plugins-official` 或其他具有 Anthropic [官方市場名稱](/docs/zh-TW/plugins/security#official-marketplace-names)的市場中的情況。社群市場 `claude-community` 不是其中之一。

13<Note>

14 若要發佈外掛程式，請參閱[發佈和分發外掛程式](/docs/zh-TW/plugins/publish)。

15</Note>

17<h2 id="emit-the-hint">

18 發出提示

19</h2>

21僅在設定 `CLAUDECODE` 或 `CLAUDE_CODE_CHILD_SESSION` 時發出標籤，以便在使用者直接執行您的 CLI 時不會出現。

23Claude Code 在透過 Bash 和 PowerShell 工具執行的命令以及 hook 命令中設定 `CLAUDECODE=1`。在 v2.1.172 及更新版本上，它也在那裡設定 `CLAUDE_CODE_CHILD_SESSION=1`。這些變數在哪些程序中攜帶它們方面有所不同：

25* **`CLAUDECODE`**：由每個 Claude Code 版本設定。IDE 擴充功能也在其整合終端中設定它，因此僅在 `CLAUDECODE` 上的閘道也會在使用者在其中一個終端中直接執行您的 CLI 時發出標籤

26* **`CLAUDE_CODE_CHILD_SESSION`**：僅在 Claude Code 本身啟動的子程序中設定。當您可以要求 v2.1.172 或更新版本時使用它

28[環境變數參考](/docs/zh-TW/env-vars)有詳細資訊。

30以下範例在 `CLAUDECODE` 上設定閘道以獲得最廣泛的覆蓋範圍，並為官方市場中名為 `example-cli` 的外掛程式發出提示：

32<CodeGroup>

33 ```javascript Node.js theme={null}

34 if (process.env.CLAUDECODE) {

35 process.stderr.write(

36 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',

37 )

38 }

39 ```

41 ```python Python theme={null}

42 import os, sys

44 if os.environ.get("CLAUDECODE"):

45 print(

46 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',

47 file=sys.stderr,

48 )

49 ```

51 ```go Go theme={null}

52 if os.Getenv("CLAUDECODE") != "" {

53 fmt.Fprintln(os.Stderr,

54 `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)

55 }

56 ```

58 ```shell Shell theme={null}

59 if [ -n "$CLAUDECODE" ]; then

60 printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2

61 fi

62 ```

63</CodeGroup>

65將 `example-cli` 替換為您的外掛程式在官方市場中的名稱。

67您可以在每次呼叫時發出提示，因為 Claude Code 會為每個外掛程式提示一次。

69若要檢查發出器，請在終端中執行 `CLAUDECODE=1 example-cli` 並確認標籤行出現在 stderr 上，然後執行 `example-cli` 而不使用變數，並確認沒有額外的列印。

71<h2 id="hint-format">

72 提示格式

73</h2>

75標籤必須佔據自己的一行；Claude Code 會忽略嵌入在行中間的標籤。

77標籤採用三個屬性，全部必需：

79| 屬性 | 說明 |

80| :------ | :---------------------------- |

81| `v` | 協議版本。`1` 是唯一支援的值 |

82| `type` | 提示類型。`plugin` 是唯一支援的值 |

83| `value` | `name@marketplace` 形式的外掛程式識別碼 |

85值可以是雙引號或不帶引號；不帶引號的值不能包含空格。

87即使 `v` 或 `type` 無法識別，Claude Code 也會從輸出中移除該行。

89<h2 id="check-when-the-prompt-appears">

90 檢查提示何時出現

91</h2>

93提示僅在互動式終端工作階段中出現。在 `claude -p` 執行、子代理執行和 hook 命令輸出中，標籤會被移除，不會顯示提示。以下所有檢查也必須通過：

95* **官方且可安裝**：`value` 命名一個 Claude Code 在其官方市場本機副本中找到的外掛程式，該外掛程式尚未安裝，且沒有原則阻止

96* **分析開啟**：Claude Code 分析關閉的工作階段永遠不會提示，例如設定了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的工作階段，或在第三方提供者（例如 Amazon Bedrock）上的工作階段，其中[自動遙測選擇退出](/docs/zh-TW/data-usage#default-behaviors-by-api-provider)適用

97* **頻率限制**：每個工作階段一個提示，每個外掛程式一個提示（無論使用者的答案如何），以及在該機器上已提示 100 個外掛程式後沒有提示

98* **未關閉**：使用者未選擇**否，且不再顯示外掛程式安裝提示**

99* **本機、有人值守的工作階段**：工作階段的工作區是本機而不是在雲端或遠端機器上，且工作階段不是無人值守執行。例如，使用 `--cloud` 啟動的工作階段、提供遠端控制的工作階段或代理團隊隊友永遠不會提示

100

101<h2 id="preview-what-the-user-sees">

102 預覽使用者看到的內容

103</h2>

104

105當[檢查提示何時出現](#check-when-the-prompt-appears)中的檢查通過時，Claude Code 會顯示一個**外掛程式推薦**對話框，如下所示：

106

107```text theme={null}

108─────────────────────────────────────────────────────────────

109 外掛程式推薦

110

111 example-cli 命令建議安裝外掛程式。

112

113 外掛程式：example-cli

114 市場：claude-plugins-official

115 說明：example-cli 部署的官方整合

116

117 您想要安裝它嗎？

118 ❯ 1. 是，安裝

119 2. 否

120 3. 否，且不再顯示外掛程式安裝提示

121

122─────────────────────────────────────────────────────────────

123```

124

125對話框命名 Claude 執行的 shell 命令的第一個單詞，以便使用者可以發現不匹配。每個答案都有一個效果：

126

127* **是，安裝**：在[使用者範圍](/docs/zh-TW/plugins/install)安裝外掛程式

128* **否，且不再顯示外掛程式安裝提示**：關閉該使用者的未來提示提示

129* **30 秒內無答案**：計為**否**

130

131<h2 id="next-steps">

132 後續步驟

133</h2>

134

135* [發佈和分發外掛程式](/docs/zh-TW/plugins/publish)：進入每個市場的路由，包括提示所需的官方市場

136* [外掛程式命令參考](/docs/zh-TW/plugins/cli-reference#plugin-install)：在工作階段外安裝相同外掛程式的 shell 命令

plugins/cli-reference.md +841 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Plugin 命令參考

7> claude plugin shell 命令的完整參考，包括在工作階段中的 /plugin 和 /reload-plugins，以及在單一工作階段中載入 plugin 的旗標。

9您可以從 shell 或指令碼執行 plugin 命令，方式為 `claude plugin`，或在 Claude Code 工作階段內執行 `/plugin` 和 `/reload-plugins`。本參考提供每個命令的旗標、預設值、輸出和結束代碼，以及在單一工作階段中載入 plugin 的兩個旗標。

11在您的組建上執行 `claude plugin --help` 以確認您的版本有哪些子命令。

13<Note>

14 這些情況涵蓋在其他頁面上：

16 * **安裝和管理步驟，以及 `/plugin` 執行的位置**：請參閱 [安裝和管理 plugins](/docs/zh-TW/plugins/install)

17 * **命令在磁碟上變更的內容以及哪個範圍優先**：請參閱 [Plugin 載入參考](/docs/zh-TW/plugins/loading)

18 * **錯誤訊息的含義**：請參閱 [Troubleshoot plugins](/docs/zh-TW/plugins/troubleshooting)

19</Note>

21<h2 id="claude-plugin-commands">

22 claude plugin 命令

23</h2>

25從 shell 或指令碼執行 `claude plugin <subcommand>`，在 Claude Code 工作階段外。這些子命令安裝和管理 plugins，而不開啟 [`/plugin`](#plugin-in-a-session) 面板。

27`claude plugins` 是 `claude plugin` 的別名。

29每個子命令共享這些結束代碼、plugin 引數和範圍值：

31* **結束代碼**：成功時為 `0`，失敗時為 `1`。`validate` 為非預期錯誤新增結束 `2`，`eval` 新增 [其部分](#plugin-eval) 中列出的代碼。

32* **Plugin 引數**：`<plugin>` 引數是 plugin `name` 或 `name@marketplace`。當兩個市場提供相同名稱時，使用限定形式。

33* **範圍**：`--scope` 接受 `user`、`project` 或 `local`，並命名命令寫入的設定檔。`update` 也接受 `managed`。

35<h3 id="plugin-init">

36 plugin init

37</h3>

39在 `~/.claude/skills/<name>/` 建立新 plugin 的架構。它在您的下一個工作階段中以 `<name>@skills-dir` 的形式載入，無需安裝步驟。

41`new` 是 `init` 的別名。

43對於以此命令開始的建立、測試和編輯工作流程，請參閱 [建立 plugin](/docs/zh-TW/plugins/create)。

45```bash theme={null}

46claude plugin init <name> [options]

47```

49`<name>` 成為 `~/.claude/skills/` 下的目錄名稱和 plugin 的 manifest 中的 `name`。

51該命令沒有另一個位置的旗標。若要改為在專案內建立架構，請參閱 [建立 plugin](/docs/zh-TW/plugins/create)。

53| 旗標 | 說明 |

54| :----------------------- | :---------------------------------------------------------------------------- |

55| `--description <text>` | Manifest 說明 |

56| `--author <name>` | 作者名稱。預設為 `git config user.name` |

57| `--author-email <email>` | 作者電子郵件。預設為 `git config user.email` |

58| `--with <components...>` | 也為 `skills`、`agents`、`hooks`、`mcp`、`lsp`、`output-style` 或 `channel` 建立起始檔案的架構 |

59| `-f, --force` | 覆寫目標處的現有 `.claude-plugin/` |

61使用起始 skill 和 hook 檔案建立 plugin 的架構：

63```bash theme={null}

64claude plugin init my-helper --with skills hooks

65```

67Claude Code 驗證其寫入的內容，並列印 `Created plugin "my-helper" at ~/.claude/skills/my-helper`，後面跟著它載入的 id 和關閉它的 `claude plugin disable` 命令。

69當 Claude Code 無法安全地建立架構時，它會結束 `1` 而不寫入，訊息會命名原因。這些是常見原因：

71* 未知的 `--with` 值

72* 目標處現有的架構，沒有 `--force`

73* 阻止 skills-directory plugins 的受管設定

75<h3 id="plugin-install">

76 plugin install

77</h3>

79從您已新增的市場安裝 plugin。`i` 是 `install` 的別名。

81```bash theme={null}

82claude plugin install <plugin> [options]

83```

85大多數 plugins 無需提示即可安裝。對於其市場項目 [執行命令以安裝它](/docs/zh-TW/plugins/host-marketplace) 或 [為其下載設定 `headersHelper`](/docs/zh-TW/plugins/host-marketplace#how-users-accept-a-headershelper-command) 的 plugin，Claude Code 首先列印命令並詢問 `Run this command now? [y/N]`。

87| 旗標 | 說明 |

88| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

89| `-s, --scope <scope>` | 安裝範圍：`user`、`project` 或 `local`。預設為 `user` |

90| `--config <key=value>` | 設定 plugin 的 manifest 宣告的 [`userConfig`](/docs/zh-TW/plugins/manifest-reference) 選項。為每個選項重複旗標。需要 Claude Code v2.1.147 或更新版本 |

91| `-y, --yes` | 接受顯示的安裝命令，無需 `Run this command now?` 提示。當命令在 Claude Code 工作階段內執行時（例如從 Bash 工具或 hook）被忽略。需要 Claude Code v2.1.229 或更新版本 |

92| `--accept-command <sha256>` | 接受顯示的安裝命令，其 `sha256` 先前的 [`--json` 執行](#plugin-json-result) 在 `shownCommand` 中報告，代替 `-y`。無法與 `-y` 結合。請參閱 [接受顯示的安裝命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更新版本 |

93| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，而不是人類可讀的訊息，供指令碼使用。請參閱 [JSON 結果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更新版本 |

95從您自己的終端傳遞 `-y` 以接受顯示的命令，無需提示。以下是沒有 TTY 和 Claude 執行命令時發生的情況：

97* **stdin 或 stdout 不是 TTY，且您既不傳遞 `-y` 也不傳遞 `--accept-command`**：安裝被拒絕。輸出說命令只是顯示，結束代碼為 `1`

98* **Claude 透過其 Bash 工具執行命令**：`-y` 被忽略。改為從您自己的終端執行命令

100為複製專案的每個人安裝 plugin：

101

102```bash theme={null}

103claude plugin install formatter@my-marketplace --scope project

104```

105

106Claude Code 列印 `Successfully installed plugin: formatter@my-marketplace (scope: project)`。當沒有新安裝時，輸出說明原因：

107

108* **已在該範圍安裝**：輸出為 `Plugin "formatter@my-marketplace" is already installed (scope: project)`，結束代碼為 `0`

109* **您拒絕命令來源提示**：輸出為 `Aborted.`，結束代碼為 `1`

110* **您拒絕 `headersHelper` 提示，或無法在沒有 TTY 的情況下確認**：輸出為 `Aborted — the command was not run.`，結束代碼為 `1`

111

112<h4 id="plugin-json-result">

113 JSON 結果格式

114</h4>

115

116當您將 `--json` 傳遞給 `plugin install` 時，stdout 的最後一行是一個 JSON 物件。只解析該行，因為 Claude Code 在其前面列印市場宣告的任何命令。

117

118三個欄位始終存在：

119

120* `command`：執行的子命令，例如 `install`

121* `outcome`：`ok` 或 `failed`

122* `message`：結果的人類可讀說明

123

124其他欄位（例如 `pluginId`、`scope` 和 `failureCode`）僅在適用時出現。

125

126使用錯誤（例如無效的 `--scope`）不列印結果行，結束 `1`，stderr 上有原因。

127

128<h4 id="accept-a-displayed-install-command">

129 接受顯示的安裝命令

130</h4>

131

132當 `--json` 執行顯示市場宣告的命令且不執行它時，`failed` 結果也會帶有 `shownCommand` 物件。其欄位包括顯示的命令、它所屬的 plugin 和命令的 `sha256`。

133

134若要接受完全相同的命令，從您自己的終端使用該 `sha256` 作為 `--accept-command` 重新執行，因為旗標在 Claude Code 工作階段內無效。需要 Claude Code v2.1.271 或更新版本。

135

136`sha256` 計為完全相同的命令、plugin 和市場目錄的接受。如果自命令顯示以來其中任何一個已變更，Claude Code 不接受 `sha256` 並再次顯示命令。執行自己的市場重新整理擷取的變更也計為此類變更。

137

138如果 `shownCommand.acceptCommandMatched` 為 `false`，您傳遞的 `sha256` 與現在顯示的命令不符。在使用其 `sha256` 重新執行之前，檢查該命令。

139

140<h3 id="plugin-uninstall">

141 plugin uninstall

142</h3>

143

144從一個範圍移除已安裝的 plugin。`remove` 和 `rm` 是 `uninstall` 的別名。

145

146```bash theme={null}

147claude plugin uninstall <plugin> [options]

148```

149

150| 旗標 | 說明 |

151| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |

152| `-s, --scope <scope>` | 從範圍卸載：`user`、`project` 或 `local`。預設為 `user` |

153| `--keep-data` | 保留 plugin 的持久資料目錄 `~/.claude/plugins/data/<id>/` |

154| `--prune` | 也移除自動安裝的 [dependencies](/docs/zh-TW/plugins/dependencies)，沒有剩餘 plugin 需要 |

155| `-y, --yes` | 跳過 `--prune` 確認提示。當 stdin 或 stdout 不是 TTY 時，需要與 `--prune` 一起使用 |

156| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。無法與 `--prune` 結合。需要 Claude Code v2.1.268 或更新版本 |

157

158從專案範圍卸載 plugin：

159

160```bash theme={null}

161claude plugin uninstall formatter@my-marketplace --scope project

162```

163

164Claude Code 列印 `Successfully uninstalled plugin: formatter (scope: project)`。當 plugin 未在該範圍安裝時，命令列印以 `Failed to uninstall plugin "formatter@my-marketplace":` 開頭的行，並結束 `1`。

165

166<h3 id="plugin-enable">

167 plugin enable

168</h3>

169

170啟用已停用的 plugin。對於 [從 claude.ai 同步的 plugin](/docs/zh-TW/plugins/loading#synced-plugins)，將 `<name>@synced` 作為 plugin 傳遞。

171

172```bash theme={null}

173claude plugin enable <plugin> [options]

174```

175

176| 旗標 | 說明 |

177| :-------------------- | :---------------------------------------------------------------------------------------------------------------- |

178| `-s, --scope <scope>` | 啟用的範圍：`user`、`project` 或 `local`。省略時自動偵測 |

179| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 |

180

181不使用 `--scope`，命令按本地、專案、使用者的順序檢查您的設定檔，並使用第一個提及 plugin 的範圍。

182

183如果您傳遞 plugin 未宣告的 `--scope`，命令要麼寫入覆寫，要麼失敗：

184

185* **[優先於](/docs/zh-TW/plugins/loading) 宣告範圍的範圍**：Claude Code 在您傳遞的範圍寫入覆寫。例如，`claude plugin disable formatter --scope local` 為您單獨關閉專案啟用的 plugin

186* **任何其他範圍**：命令失敗，訊息為 `Plugin "formatter" is installed at project scope, not user. Use --scope project or omit --scope to auto-detect.`

187

188如果 plugin 已在解析的範圍啟用，命令列印 `Plugin "formatter" is already enabled` 並結束 `1`。使用 `--json`，結果有 `"failureCode": "already_in_goal_state"` 和 `"alreadyInGoalState": true`，因此指令碼可以將該情況視為成功。

189

190當 plugin 宣告 [dependencies](/docs/zh-TW/plugins/dependencies) 時，Claude Code 也啟用它們。命令在這些情況下失敗：

191

192* **dependency 未安裝**：啟用失敗並列印每個遺漏 dependency 的 `claude plugin install` 命令

193* **dependency 被您組織的 plugin 原則阻止**：啟用失敗並命名被阻止的 dependency

194* **dependency 在優先於目標範圍的範圍設定為 `false`**：啟用失敗。在該範圍啟用 dependency，或傳遞 `--scope` 以在那裡寫入

195

196在宣告它的任何地方重新啟用 plugin：

197

198```bash theme={null}

199claude plugin enable formatter

200```

201

202Claude Code 列印 `Successfully enabled plugin: formatter (scope: project)`，命名它偵測到的範圍。

203

204<h3 id="plugin-disable">

205 plugin disable

206</h3>

207

208停用 plugin 而不卸載它。對於 [從 claude.ai 同步的 plugin](/docs/zh-TW/plugins/loading#synced-plugins)，將 `<name>@synced` 作為 plugin 傳遞。

209

210```bash theme={null}

211claude plugin disable [plugin] [options]

212```

213

214| 旗標 | 說明 |

215| :-------------------- | :---------------------------------------------------------------------------------------------------------------- |

216| `-a, --all` | 停用每個啟用的 plugin。無法與 plugin 名稱或 `--scope` 結合 |

217| `-s, --scope <scope>` | 停用的範圍：`user`、`project` 或 `local`。省略時自動偵測 |

218| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 |

219

220不使用 `--scope`，範圍以與 [`plugin enable`](#plugin-enable) 相同的本地、專案、使用者順序自動偵測。

221

222如果您既不傳遞 plugin 名稱也不傳遞 `--all`，Claude Code 列印 `Please specify a plugin name or use --all to disable all plugins` 並結束 `1`。停用已停用的 plugin 列印 `Plugin "formatter" is already disabled` 並結束 `1`，如 [`plugin enable`](#plugin-enable) 對已啟用 plugin 所做的那樣。

223

224命令對仍然需要的 plugin 失敗：

225

226* **另一個啟用的 plugin [depends on](/docs/zh-TW/plugins/dependencies) 它**：命令失敗並命名要先停用的相依項

227* **您的組織要求它作為同步 plugin**：命令失敗並保存任何內容

228

229停用一個 plugin：

230

231```bash theme={null}

232claude plugin disable formatter

233```

234

235Claude Code 列印 `Successfully disabled plugin: formatter (scope: project)`。

236

237<h3 id="plugin-update">

238 plugin update

239</h3>

240

241將 plugin 更新到其市場提供的最新版本。新版本在您的下一個工作階段中載入，或在執行中的工作階段中執行 `/reload-plugins` 後載入。

242

243```bash theme={null}

244claude plugin update <plugin> [options]

245```

246

247| 旗標 | 說明 |

248| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |

249| `-s, --scope <scope>` | 更新的範圍：`user`、`project`、`local` 或 `managed`。預設為 plugin 安裝的範圍 |

250| `-y, --yes` | 接受來自 [command-source](/docs/zh-TW/plugins/host-marketplace) plugin 的已變更安裝命令，無需提示。當 stdin 或 stdout 不是 TTY 時需要，除非您傳遞 `--accept-command`。需要 Claude Code v2.1.229 或更新版本 |

251| `--accept-command <sha256>` | 接受市場宣告的命令，其 `sha256` 先前的 [`--json` 執行](#plugin-json-result) 在 `shownCommand` 中報告，代替 `-y`。無法與 `-y` 結合。需要 Claude Code v2.1.271 或更新版本 |

252| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 |

253

254`managed` 是您可以更新但不能安裝的唯一範圍。對於管理員安裝的 plugins，請參閱 [為您的組織管理 plugins](/docs/zh-TW/plugins/org)。

255

256更新 plugin：

257

258```bash theme={null}

259claude plugin update formatter@my-marketplace

260```

261

262Claude Code 列印 `Checking for updates for plugin "formatter@my-marketplace"…`，然後是結果。當沒有更新時，它列印 `formatter is already at the latest version (1.0.0).` 並結束 `0`。

263

264您可以傳遞裸 plugin 名稱，命令會根據您安裝的 plugins 進行比對。當來自不同市場的已安裝 plugins 共享名稱時，命令拒絕更新並列出要執行的限定 `plugin-name@marketplace-name` 命令。按裸名稱更新需要 Claude Code v2.1.246 或更新版本。

265

266<h3 id="plugin-list">

267 plugin list

268</h3>

269

270列出已安裝的 plugins，包括其版本、範圍和狀態。

271

272```bash theme={null}

273claude plugin list [options]

274```

275

276| 旗標 | 說明 |

277| :------------ | :-------------------------------------- |

278| `--json` | 將列表列印為 JSON |

279| `--available` | 也列出您的市場提供但您未安裝的 plugins。沒有 `--json` 時無效 |

280

281Claude Code 按每個 plugin 的載入方式對人類可讀的輸出進行分組：

282

283* **`Installed plugins:`**：您從市場安裝的 plugins

284* **`Session-only plugins (--plugin-dir / --plugin-url):`**：由同一命令中的這些旗標載入的 plugins，如 `claude --plugin-dir ./my-plugin plugin list`

285* **`Skills-directory plugins (.claude/skills/*):`**：Claude Code 在 skills 目錄中找到的 plugins

286* **`Synced from claude.ai`**：[從您的 claude.ai 帳戶同步的 plugins](/docs/zh-TW/plugins/loading#synced-plugins)

287

288當任何群組中都沒有任何內容時，Claude Code 列印 ``No plugins installed. Use `claude plugin install` to install a plugin.``

289

290<h4 id="json-output">

291 JSON 輸出

292</h4>

293

294使用 `--json`，Claude Code 列印一個陣列，每個安裝一個物件。每個物件帶有下面的欄位。`id`、`version`、`scope`、`enabled` 和 `installPath` 始終存在，其他欄位僅在適用時出現。

295

296| 欄位 | 類型 | 說明 |

297| :------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |

298| `id` | string | 安裝為 `name@marketplace`，工作階段專用 plugins 為 `name@inline`，skills-directory plugins 為 `name@skills-dir`，從 claude.ai 同步的 plugins 為 `name@synced` |

299| `version` | string | 對於市場安裝，[Claude Code 在安裝時計算的](/docs/zh-TW/plugins/loading#versions-and-updates) 版本。對於工作階段專用、skills-directory 或同步 plugin，manifest 的 `version`，或未宣告時為 `unknown` |

300| `scope` | string | 安裝為 `user`、`project`、`local` 或 `managed`；skills-directory plugins 為 `user` 或 `project`；工作階段專用 plugins 為 `session`；從 claude.ai 同步的 plugins 為 `synced` |

301| `enabled` | boolean | plugin 在您的合併設定中是否啟用 |

302| `installPath` | string | plugin 載入的目錄 |

303| `installedAt` | string | 安裝的 ISO 時間戳。僅市場安裝 |

304| `lastUpdated` | string | 上次更新的 ISO 時間戳。僅市場安裝 |

305| `projectPath` | string | 安裝所屬的專案。僅 `project` 和 `local` 範圍 |

306| `mcpServers` | object | plugin 的 MCP 伺服器定義，當市場安裝的 plugin 有任何時 |

307| `errors` | array of strings | 載入錯誤，當 plugin 無法載入時 |

308| `notes` | array of strings | plugin 已載入並正常運作的編寫警告 |

309| `errorDetails` | array of objects | 每個 `errors` 項目一個物件，給出其診斷 `type` 和它引用的名稱，例如 plugin、市場、伺服器或檔案。需要 Claude Code v2.1.268 或更新版本 |

310| `noteDetails` | array of objects | 每個 `notes` 項目的相同詳細物件。需要 Claude Code v2.1.268 或更新版本 |

311

312使用 `--json --available`，Claude Code 列印一個物件而不是陣列。其 `installed` 欄位保存已安裝 plugin 物件的陣列，其 `available` 欄位保存每個未安裝市場 plugin 的一個物件，欄位如下。

313

314| 欄位 | 類型 | 說明 |

315| :---------------- | :--------------- | :----------------------------------------------------------------- |

316| `pluginId` | string | `name@marketplace` |

317| `name` | string | plugin 在市場中的名稱 |

318| `marketplaceName` | string | 提供它的市場 |

319| `source` | string or object | 市場項目的 [source](/docs/zh-TW/plugins/marketplace-reference)：相對路徑為字串，否則為物件 |

320| `description` | string | 項目的說明，當它有時 |

321| `version` | string | 項目的版本，當它宣告時 |

322| `installCount` | number | 安裝計數，當 Claude Code 有 plugin 的計數時 |

323

324<h3 id="plugin-details">

325 plugin details

326</h3>

327

328顯示 plugin 的元件清單及其預計的 token 成本。

329

330plugin 必須已載入：已安裝、在 skills 目錄中找到，或在同一命令中使用 `--plugin-dir` 或 `--plugin-url` 傳遞。`<name>` 是 plugin `name` 或 `name@marketplace`。

331

332```bash theme={null}

333claude plugin details <name>

334```

335

336命令除了 `--help` 外不接受任何旗標。

337

338顯示已安裝 plugin 的貢獻：

339

340```bash theme={null}

341claude plugin details formatter

342```

343

344Claude Code 列印 plugin 的名稱、版本、說明和來源，然後是這些部分：

345

346* **`Component inventory`**：plugin 的 skills、agents、hooks、MCP 伺服器和 LSP 伺服器

347* **`Projected token cost`**：plugin 添加到每個工作階段的始終開啟 tokens

348* **`Per-component (rounded)`**：每個 skill、agent 和命令的始終開啟和按調用估計。當 plugin 沒有時省略

349

350對於兩個成本數字的含義，請參閱 [測量 plugin 成本和使用](/docs/zh-TW/plugins/measure)。

351

352對於未載入的 plugin，Claude Code 列印 ``Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.`` 並結束 `1`。

353

354<h3 id="plugin-prune">

355 plugin prune

356</h3>

357

358移除自動安裝的 [dependencies](/docs/zh-TW/plugins/dependencies)，沒有已安裝的 plugin 再需要。命令永遠不會移除您自己安裝的 plugin。`autoremove` 是 `prune` 的別名。

359

360```bash theme={null}

361claude plugin prune [options]

362```

363

364| 旗標 | 說明 |

365| :-------------------- | :------------------------------------------ |

366| `-s, --scope <scope>` | 修剪的範圍：`user`、`project` 或 `local`。預設為 `user` |

367| `--dry-run` | 列出將移除的內容而不移除它 |

368| `-y, --yes` | 跳過確認提示。當 stdin 或 stdout 不是 TTY 時需要 |

369

370預覽修剪將移除的內容：

371

372```bash theme={null}

373claude plugin prune --dry-run

374```

375

376Claude Code 列出孤立的 dependencies 並以 `(dry run — nothing removed)` 結尾。沒有要移除的內容時，它列印以 `Nothing to prune` 開頭的行。

377

378不使用 `--dry-run`，命令僅在您在提示處確認或傳遞 `-y` 後移除孤立的 dependencies。

379

380無論您在提示處的答案如何，結束代碼都是 `0`。

381

382`prune` 的作用取決於是否附加了終端以及您是否傳遞了 `-y`：

383

384| 終端和旗標 | 發生的情況 |

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

386| 互動式終端，無 `-y` | 列出孤立的 dependencies 並詢問 `Remove? [y/N]` |

387| 任何終端，`-y` | 移除它們並列印 `Removed N auto-installed plugins: <names>` |

388| 非 TTY stdin 或 stdout，無 `-y` | 列印列表並 ``Not a TTY — run `claude plugin prune -y` to remove.``，不移除任何內容 |

389

390<h3 id="plugin-eval">

391 plugin eval

392</h3>

393

394執行 plugin 的 [eval cases](/docs/zh-TW/plugin-evals) 並報告評分結果。需要 Claude Code v2.1.269 或更新版本。

395

396每個案例是一個提示加上評分者。Claude Code 在隔離的工作階段中執行它多次，僅載入目標 plugin，預設情況下也不載入 plugin，以便報告顯示差異。

397

398請參閱 [使用 evals 測試 plugins](/docs/zh-TW/plugin-evals) 以了解案例格式、評分者、結果和 CI 使用。

399

400```bash theme={null}

401claude plugin eval [target] [options]

402```

403

404可選的 `target` 預設為目前目錄，並採用以下任何形式：

405

406* plugin 目錄

407* 單個 `prompt.md` 或 `case.yaml` 檔案

408* 已安裝的 plugin，如 `name` 或 `name@marketplace`

409* `name@skills-dir`

410

411將目標放在 `--tag`、`--allow-tools` 和 `--json` 之前。這些選項中的每一個都將其後面的單詞作為其值，因此在其中一個之後寫入的目標被讀作標籤、工具名稱或 JSON 輸出路徑，而不是目標。

412

413此表列出大多數執行使用的選項。執行 `claude plugin eval --help` 以獲得完整集合，包括 `--case`、`--tag`、`--output-dir`、`--report`、`--allow-real-servers`、`--keep-temp` 和 `--verbose`。

414

415| 選項 | 說明 | 預設 |

416| :------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |

417| `--runs <n>` | 每個 [arm](/docs/zh-TW/plugin-evals#compare-against-a-no-plugin-baseline) 中每個案例的執行 | 每個案例的 `runs`，否則 3 |

418| `-j, --concurrency <n>` | 同時執行的代理工作階段，1 到 8。它們共享您的速率限制 | `1` |

419| `--model <model>` | 測試中的代理的模型 | 每個案例的 `model`，否則 `ANTHROPIC_MODEL`（如果設定），否則 Claude Code 的預設值 |

420| `--judge-model <model>` | `llm` 和 `baseline` 評分者的模型 | 一個小的快速模型 |

421| `--ablation <mode>` | `none` 或 `with-without`。請參閱 [與無 plugin 基線比較](/docs/zh-TW/plugin-evals#compare-against-a-no-plugin-baseline) | 當 plugin 解析時為 `with-without`，否則為 `none` |

422| `--threshold <0..1>` | 如果任何案例評分低於此，結束 1 | `1.0` |

423| `--max-cost-usd <usd>` | 一旦支出達到此值，停止下一次執行，結束 2，並報告部分結果 | 無限制 |

424| `--allow-tools <tools...>` | 授予超出唯讀集合的工具，例如 `Bash`、`Write`、`Edit` 或 `"mcp__plugin_<plugin>_<server>__*"`。請參閱 [授予工具](/docs/zh-TW/plugin-evals#grant-tools) | |

425| `--scaffold` | 執行每個案例的 [`scaffold_script`](/docs/zh-TW/plugin-evals#add-setup-or-history-with-case-yaml) | 關閉 |

426| `--trust-plugin` | 跳過首次執行信任提示，用於 CI。請參閱 [執行可以存取的內容](/docs/zh-TW/plugin-evals#security) | 關閉 |

427| `--mocks <mode>` | `record` 或 `off`。請參閱 [模擬 MCP 伺服器](/docs/zh-TW/plugin-evals#mock-mcp-servers) | `record` |

428| `--eval-dir <dir>` | plugin 下方保存案例的目錄 | manifest 的 `experimental.evals`，否則 `evals` |

429| `--json [path]` | 將 [結果文件](/docs/zh-TW/plugin-evals#json-result) 列印到 stdout，或寫入 `.json` 路徑 | |

430| `--no-publish` | 保持 HTML 報告本地 | |

431

432結束代碼報告執行如何結束。若要在管道中對其進行操作，請參閱 [在 CI 中執行 evals](/docs/zh-TW/plugin-evals#run-evals-in-ci)。

433

434| 結束代碼 | 含義 |

435| :---- | :------------------------- |

436| `0` | 每個案例都符合閾值 |

437| `1` | 失敗的案例、載入錯誤或不受信任的 plugin 目錄 |

438| `2` | 部分執行 |

439| `130` | 已中斷 |

440| `143` | 已終止 |

441

442<h3 id="plugin-eval-init">

443 plugin eval init

444</h3>

445

446為目前目錄中的 plugin 建立 eval 套件。需要 Claude Code v2.1.269 或更新版本。請參閱 [建立您的第一個 eval 套件](/docs/zh-TW/plugin-evals#create-your-first-eval-suite)。

447

448```bash theme={null}

449claude plugin eval init [name] [options]

450```

451

452在終端中，命令開啟互動式 Claude Code 工作階段以進行編寫訪談。在訪談中，Claude 執行以下操作：

453

4541. 讀取 plugin

4552. 詢問您它應該做什麼

4563. 提議案例和評分者

4574. 寫入案例檔案

4585. 執行案例並與您檢查評分，以確認評分者按您的方式評分

459

460使用 `--bare` 或沒有終端，命令改為寫入空白單案例範本。當 Claude 從 Claude Code 工作階段內執行命令時，命令列印該工作階段要遵循的訪談說明，而不是寫入範本。

461

462可選的 `name` 是案例名稱。它在 `--bare` 或沒有終端時需要，因為命令為該案例寫入空白範本。訪談不需要。

463

464命令接受這些選項：

465

466| 選項 | 說明 | 預設 |

467| :------------------ | :---------------------------------------------------------- | :----------------------------------------- |

468| `--bare` | 為 `<name>` 寫入空白 `prompt.md` 和 `graders/criteria.md`，而不是執行訪談 | |

469| `-i, --interactive` | 需要訪談。沒有終端時失敗，而不是寫入範本 | |

470| `--eval-dir <dir>` | 目前目錄下方寫入案例的目錄 | manifest 的 `experimental.evals`，否則 `evals` |

471

472<h3 id="plugin-tag">

473 plugin tag

474</h3>

475

476為 plugin 發佈建立名為 `<name>--v<version>` 的帶註解 git 標籤。標籤前，命令檢查 plugin 的 `plugin.json` 和任何列出它的市場項目是否同意版本。

477

478有關何時標籤發佈，請參閱 [發佈 plugin](/docs/zh-TW/plugins/publish)。

479

480```bash theme={null}

481claude plugin tag [path] [options]

482```

483

484`[path]` 是 plugin 目錄，預設為目前目錄。命令透過從該目錄向上走到列出 plugin 的 `.claude-plugin/marketplace.json` 來找到市場項目。

485

486| 旗標 | 說明 |

487| :-------------------- | :-------------------------------------- |

488| `--push` | 建立後將標籤推送到 `--remote` |

489| `--dry-run` | 列印將標籤化的內容而不建立標籤 |

490| `-f, --force` | 跳過髒工作樹和標籤已存在檢查 |

491| `-m, --message <msg>` | 標籤註解訊息。`%s` 代表版本。預設為 `<name> <version>` |

492| `--remote <name>` | 使用 `--push` 推送到的遠端。預設為 `origin` |

493

494預覽市場簽出中 plugin 的標籤：

495

496```bash theme={null}

497claude plugin tag plugins/formatter --dry-run

498```

499

500Claude Code 列印計畫：

501

502* plugin 名稱

503* 版本及其來自的檔案

504* 匹配的市場項目，當有時

505* 標籤名稱

506* 它將執行的 `git tag` 和 `git push` 命令

507

508不使用 `--dry-run`，Claude Code 列印 `Created tag formatter--v1.0.0` 並列印 `Pushed to origin` 或您自己執行的推送命令。如果推送失敗，標籤仍在本地建立，命令以錯誤結束。

509

510當命令無法安全地標籤時，它結束 `1` 並列印原因。常見原因是：

511

512* `plugin.json` 或市場項目中沒有 `version`

513* 標籤已存在

514* 工作樹是髒的

515

516<h3 id="plugin-validate">

517 plugin validate

518</h3>

519

520驗證 plugin manifest、市場 manifest 或目錄中的 skills、agents 和命令，並以 CI 工作可以對其進行操作的代碼結束。對於建立、測試和編輯工作流程，請參閱 [建立 plugin](/docs/zh-TW/plugins/create)。對於驗證器在每個 manifest 中檢查的內容，請參閱 [plugin manifest 參考](/docs/zh-TW/plugins/manifest-reference) 和 [市場參考](/docs/zh-TW/plugins/marketplace-reference)。

521

522```bash theme={null}

523claude plugin validate <path> [options]

524```

525

526| 旗標 | 說明 |

527| :--------- | :------------------------------------------------------------- |

528| `--strict` | 將警告視為錯誤，因此執行時容許的未識別欄位和遺漏中繼資料失敗執行。需要 Claude Code v2.1.145 或更新版本 |

529| `--json` | 將驗證報告輸出為具有相同結束代碼的一個 JSON 物件。需要 Claude Code v2.1.259 或更新版本 |

530

531在提交前驗證 plugin：

532

533```bash theme={null}

534claude plugin validate ./my-plugin --strict

535```

536

537<h4 id="validate-a-directory">

538 驗證目錄

539</h4>

540

541`<path>` 是 manifest 檔案或目錄。給定目錄，Claude Code 透過在其中找到的內容選擇要驗證的內容：

542

543* `.claude-plugin/marketplace.json`，當它存在時

544* 否則 `.claude-plugin/plugin.json`

545* 否則元件檔案，由目錄的名稱選擇。驗證沒有 manifest 的元件檔案需要 Claude Code v2.1.233 或更新版本：

546 * 名為 `skills`、`agents` 或 `commands` 的目錄：其中的檔案

547 * 名為 `.claude` 的目錄：其中的 `skills`、`agents` 和 `commands` 目錄

548 * 任何其他目錄：其 `.claude` 下的這三個目錄

549

550Claude Code 不遵循您命名的目錄內的符號連結。它的作用取決於連結的位置：

551

552* **plugin 或 `.claude` 根下的連結 `skills`、`agents` 或 `commands` 目錄**：Claude Code 警告其中的任何內容都未被讀取。

553* **`skills`、`agents` 或 `commands` 目錄內的連結項目**：Claude Code 跳過它並警告，每個目錄，它跳過了多少項目，工作階段會載入。

554* **您命名的 `skills`、`agents` 或 `commands` 目錄本身是符號連結，或其父 `.claude` 目錄是**：Claude Code 報告錯誤並檢查其中的任何內容。改為命名真實目錄。

555

556驗證執行不讀取幾個檔案：

557

558* **plugin 根處的 `SKILL.md`**：當您針對 plugin 目錄執行 `claude plugin validate` 時，Claude Code 不檢查 plugin 根處的 `SKILL.md`

559* **plugin 根處的 `CLAUDE.md`**：在 plugin 執行中，Claude Code 也警告 plugin 根處的 `CLAUDE.md`

560* **市場執行中的 Plugin 檔案**：從市場目錄，Claude Code 不開啟 plugins 的 skill、agent、command 或 hook 檔案。若要在這些檔案中找到錯誤，驗證每個 plugin 目錄

561

562<h4 id="output-and-exit-codes">

563 輸出和結束代碼

564</h4>

565

566Claude Code 列印它驗證的檔案、任何帶有其路徑的錯誤和警告，以及判決行。結束代碼遵循判決：

567

568| 結束代碼 | 判決行 | 含義 |

569| :--- | :----------------------------------------------------------------------------- | :------------------------------ |

570| `0` | `Validation passed` 或 `Validation passed with warnings` | manifest 載入。使用 `--strict`，也沒有警告 |

571| `1` | `Validation failed` 或 `Validation failed (--strict treats warnings as errors)` | 錯誤，或 `--strict` 下的警告 |

572| `2` | `Unexpected error during validation: <reason>` | 驗證器本身失敗，例如在不可讀的路徑上 |

573

574使用 `--json`，Claude Code 將報告寫入 stdout 作為具有這些頂級欄位的一個 JSON 物件：

575

576* `success`：結束代碼給出的相同判決

577* `strict`：執行是否將警告視為錯誤

578* `target`：Claude Code 驗證的解析路徑

579* `manifest`：manifest 自己的結果，或沒有 manifest 的執行為 `null`

580* `contents`：每個檔案的結果，命名其 `file` 並帶有 `errors`、`warnings` 和 `notes` 陣列

581

582在結束 `2` 時，命令不向 stdout 寫入任何內容。錯誤訊息進入 stderr。

583

584<h2 id="claude-plugin-marketplace-commands">

585 claude plugin marketplace 命令

586</h2>

587

588從 shell 執行 `claude plugin marketplace <subcommand>` 以新增、列出、重新整理和移除您安裝 plugins 的市場。

589

590* **結束代碼**：這些子命令遵循 plugin 命令的 [exit-code convention](#claude-plugin-commands)

591* **範圍**：它們的 `--scope` 旗標沒有 `-s` 短形式

592

593有關市場是什麼以及 Claude Code 如何快取它，請參閱 [Plugin 載入參考](/docs/zh-TW/plugins/loading)。

594

595<h3 id="plugin-marketplace-add">

596 plugin marketplace add

597</h3>

598

599從 GitHub 儲存庫、git URL、託管 `marketplace.json` 或本地路徑新增市場，並在設定檔中宣告它。

600

601新增後，Claude Code 安裝您已安裝 plugins 遺漏的任何 [dependencies](/docs/zh-TW/plugins/dependencies)。

602

603```bash theme={null}

604claude plugin marketplace add <source> [options]

605```

606

607| 旗標 | 說明 |

608| :-------------------- | :---------------------------------------------------------------------------------------------------------- |

609| `--scope <scope>` | 在其中宣告市場的設定檔：`user`、`project` 或 `local`。預設為 `user` |

610| `--sparse <paths...>` | 將 git 簽出限制為這些目錄，用於 monorepos。僅 `github` 和 `git` 來源 |

611| `--claudeai` | 將引數讀作 [claude.ai 上託管的市場](/docs/zh-TW/plugins/install#add-from-claude-ai) 的名稱，而不是來源。需要 Claude Code v2.1.273 或更新版本 |

612

613`<source>` 採用下表中的任何形式，其形式決定來源類型以及 Claude Code 如何擷取市場。對於結果來源物件，請參閱 [市場參考](/docs/zh-TW/plugins/marketplace-reference)。

614

615| 您輸入 | 來源類型 | Claude Code 如何擷取它 |

616| :----------------------------------------------------------------------- | :---------- | :-------------------------------------------------- |

617| `owner/repo`、`owner/repo#ref` 或 `owner/repo@ref` | `github` | 複製 GitHub 儲存庫，給定時固定到 `ref`。所有者和儲存庫必須遵循 GitHub 命名規則 |

618| `user@host:path[.git][#ref]` | `git` | 透過 SSH 複製 |

619| `https://example.com/repo.git[#ref]` 或包含 `/_git/` 的 URL | `git` | 透過 HTTPS 複製，包括 Azure DevOps URL |

620| `https://github.com/owner/repo` 或 `https://gitlab.com/namespace/project` | `git` | 在附加 `.git` 後透過 HTTPS 複製 |

621| 任何其他 `http://` 或 `https://` URL，包括沒有 `.git` 的自託管 git 主機 | `url` | 將 URL 作為 `marketplace.json` 擷取。若要改為複製儲存庫，請附加 `.git` |

622| `./path`、`../path`、`/path` 或 `~/path` 到目錄 | `directory` | 就地讀取目錄。在 Windows 上，`.\`、`..\` 和 `C:\` 形式也有效 |

623| 相同的路徑形式，到 `.json` 檔案 | `file` | 就地讀取檔案 |

624

625對於其複製 URL 不帶 `.git` 尾碼的主機（例如 AWS CodeCommit），改為在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 中將市場新增為 git 項目。Claude Code 複製 git 項目，無論其 URL 是否以 `.git` 結尾。

626

627Claude Code 也複製具有嵌套子群組的 `gitlab.com` URL，例如 `https://gitlab.com/group/subgroup/project`。

628

629新增市場並與專案共享：

630

631```bash theme={null}

632claude plugin marketplace add your-org/your-marketplace --scope project

633```

634

635Claude Code 列印 `Successfully added marketplace: your-marketplace (declared in project settings)`，使用市場自己的 manifest 中的 `name`。重複新增或無效來源列印以下結果之一：

636

637* **市場已在磁碟上**：輸出為 `Marketplace 'your-marketplace' already on disk — declared in project settings`，結束代碼為 `0`

638* **無法識別的來源**：輸出為 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`，結束代碼為 `1`

639* **裸主機，例如 `gitlab.example.com/team/plugins`**：新增失敗，因為無效的 `owner/repo` 速記，訊息告訴您新增 `https://` 或使用本地路徑

640

641按 `claude plugin marketplace list` 的 `From claude.ai:` 部分中列印的名稱新增 [claude.ai 上託管的市場](/docs/zh-TW/plugins/install#add-from-claude-ai)：

642

643```bash theme={null}

644claude plugin marketplace add --claudeai claudeai-organization-library

645```

646

647使用 `--claudeai`，命令拒絕 `--scope` 和 `--sparse`。市場為您的帳戶託管，未在設定檔中宣告，因此您無法透過專案的 `.claude/settings.json` 共享它。

648

649<h3 id="plugin-marketplace-list">

650 plugin marketplace list

651</h3>

652

653列出您新增的每個市場及其來源。

654

655```bash theme={null}

656claude plugin marketplace list [options]

657```

658

659| 旗標 | 說明 |

660| :------- | :---------- |

661| `--json` | 將列表列印為 JSON |

662

663Claude Code 列印 `Configured marketplaces:` 和每個市場一個 `Source:` 行，或 `No marketplaces configured`。

664

665使用 `--json`，Claude Code 列印一個陣列，每個市場一個物件，帶有下面的欄位。每個欄位都是字串。

666

667| 欄位 | 說明 |

668| :---------------- | :--------------------------------------------------- |

669| `name` | 市場的名稱 |

670| `source` | `github`、`git`、`url`、`directory`、`file` 或 `claudeai` |

671| `repo` | `owner/repo`。僅 `github` 來源 |

672| `url` | 複製或擷取 URL。僅 `git` 和 `url` 來源 |

673| `path` | 本地路徑。僅 `directory` 和 `file` 來源 |

674| `ref` | 固定的分支或標籤。`github` 和 `git` 來源，僅當固定時 |

675| `installLocation` | Claude Code 快取市場的位置 |

676

677已新增的 [claude.ai 市場](/docs/zh-TW/plugins/install#add-from-claude-ai) 沒有本地複製，因此其項目帶有其 claude.ai 識別碼 `marketplaceId` 和 `organizationUuid`，代替 `installLocation`。它也帶有 `scope`（當記錄時）和 `status`。

678

679如果您的終端工作階段 [從您的 claude.ai 帳戶同步 plugins](/docs/zh-TW/plugins/loading#synced-plugins)，文字列表以 `From claude.ai:` 部分結尾。該部分命名 claude.ai 為您的帳戶列出的市場，您未新增的市場，包括基於 git 的和託管的。它需要 Claude Code v2.1.273 或更新版本。

680

681若要從該部分新增市場，請參閱 [從 claude.ai 新增市場](/docs/zh-TW/plugins/install#add-from-claude-ai)。

682

683`--json` 輸出僅涵蓋已配置的市場，並將部分留出。

684

685<h3 id="plugin-marketplace-remove">

686 plugin marketplace remove

687</h3>

688

689從您的設定中移除市場的宣告。`rm` 是 `remove` 的別名。

690

691<Warning>

692 當您從最後一個宣告它的範圍移除市場時，Claude Code 也刪除其快取並卸載您從它安裝的每個 plugin。不使用 `--scope`，命令從每個範圍移除宣告。若要重新整理市場而不失去其 plugins，改為執行 `plugin marketplace update`。

693</Warning>

694

695```bash theme={null}

696claude plugin marketplace remove <name> [options]

697```

698

699`<name>` 是 `plugin marketplace list` 顯示的市場名稱，而不是您傳遞給 `add` 的來源。

700

701| 旗標 | 說明 |

702| :---------------- | :---------------------------------------------------------------- |

703| `--scope <scope>` | 從一個設定範圍移除宣告：`user`、`project` 或 `local`。不使用它，Claude Code 從每個範圍移除宣告 |

704

705從每個範圍移除市場：

706

707```bash theme={null}

708claude plugin marketplace remove your-marketplace

709```

710

711Claude Code 列印 `Successfully removed marketplace: your-marketplace`，當您限定範圍時新增 `(from project settings)`。如果您限定範圍到不宣告市場的設定檔，命令失敗，訊息為 `Marketplace 'your-marketplace' is not declared in project settings. Omit --scope to remove it from all scopes.`

712

713<h3 id="plugin-marketplace-update">

714 plugin marketplace update

715</h3>

716

717重新整理一個市場或每個市場，從其來源擷取新 plugins 和版本。使用分支或標籤 `ref` 新增的市場更新到該 ref 的最新提交，而不是儲存庫的預設分支。

718

719```bash theme={null}

720claude plugin marketplace update [name]

721```

722

723命令除了 `--help` 外不接受任何旗標。

724

725重新整理一個市場：

726

727```bash theme={null}

728claude plugin marketplace update your-marketplace

729```

730

731Claude Code 列印 `Successfully updated marketplace: your-marketplace`。當您省略名稱時，它列印計數，例如 `Successfully updated 2 marketplaces`。沒有新增市場時，它列印 `No marketplaces configured` 並結束 `0`。

732

733<h2 id="plugin-in-a-session">

734 /plugin 在工作階段中

735</h2>

736

737在互動式工作階段內，`/plugin` 開啟 plugin 面板。每個子命令在標籤上開啟面板、在那裡執行操作或內聯列印結果。`/plugins` 和 `/marketplace` 是 `/plugin` 的別名。

738

739您只能在互動式終端工作階段中執行這些命令。在非互動式執行（例如 `claude -p`）中，Claude Code 回覆 `/plugin` 在此環境中不可用。

740

741有關哪些表面有 `/plugin`、如何在沒有它的情況下安裝以及每個面板標籤顯示的內容，請參閱 [安裝和管理 plugins](/docs/zh-TW/plugins/install)。

742

743`<plugin>` 是 plugin `name` 或 `name@marketplace`。

744

745下表列出每個工作階段形式。shell 子命令 `init`、`update`、`details`、`prune`、`eval` 和 `eval init` 沒有工作階段形式。

746

747| 命令 | 別名 | 它的作用 |

748| :-------------------------------------------------- | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

749| `/plugin` | | 在 **Discover** 標籤上開啟面板。`/plugin` 後的任何無法識別的第一個單詞執行相同操作 |

750| `/plugin help` | `/plugin --help`、`/plugin -h` | 顯示 `/plugin` 子命令的使用列表 |

752| `/plugin install` | `i` | 開啟 **Discover** 標籤 |

753| `/plugin install <plugin>` | `i` | 在 **Discover** 標籤中開啟 plugin 的詳細資訊。使用 `name@marketplace`，在該市場的列表中開啟它們 |

754| `/plugin install <plugin> --marketplace <source>` | `i` | 當您尚未新增市場時在 `<source>` 新增市場，要求您先確認，然後開啟 plugin 的詳細資訊。請參閱 [在一個命令中新增市場和安裝](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command)。需要 Claude Code v2.1.275 或更新版本 |

755| `/plugin manage` | | 開啟 **Installed** 標籤 |

756| `/plugin stats` | | 在 [`/skill-doctor`](/docs/zh-TW/skills#find-unused-skills) 可用的工作階段中開啟 **Stats** 標籤。在其他任何地方，它在 **Discover** 標籤上開啟面板 |

757| `/plugin enable <plugin>` | | 在 plugin 處開啟 **Installed** 標籤並啟用它 |

758| `/plugin disable <plugin>` | | 在 plugin 處開啟 **Installed** 標籤並停用它 |

759| `/plugin uninstall <plugin>` | | 在 plugin 處開啟 **Installed** 標籤並卸載它 |

760| `/plugin configure <plugin>` | `config` | 開啟 plugin 的 [`userConfig`](/docs/zh-TW/plugins/manifest-reference) 對話框，或報告 plugin 未宣告任何。需要 Claude Code v2.1.147 或更新版本 |

761| `/plugin validate <path>` | | 列印與 `claude plugin validate` 相同的報告，內聯 |

762| `/plugin tag [path] [--push] [--dry-run] [--force]` | | 建立發佈標籤，如 `claude plugin tag` 所做的那樣。接受 `--push`、`--dry-run` 和 `--force` 或 `-f`；使用任何其他旗標或額外引數，Claude Code 改為列印使用 |

763| `/plugin marketplace` | `market` | 不執行任何可見操作。傳遞 `add`、`list`、`update` 或 `remove` |

764| `/plugin marketplace add [source]` | `market add` | 使用來源，新增它並報告結果。沒有來源，開啟 **Add marketplace** 輸入 |

765| `/plugin marketplace list` | `market list` | 內聯列印您的市場名稱 |

766| `/plugin marketplace update [name]` | `market update` | 開啟 **Marketplaces** 標籤。使用名稱，在那裡重新整理該市場 |

767| `/plugin marketplace remove [name]` | `market remove`、`market rm`、`marketplace rm` | 開啟 **Marketplaces** 標籤。使用名稱，在那裡移除該市場 |

768

769如果您在 `/plugin enable`、`disable`、`uninstall` 或 `configure` 中命名目前專案中未安裝的 plugin，Claude Code 列印 `Plugin "<plugin>" is not installed in this project` 而不是執行操作。

770

771<h2 id="reload-plugins">

772 /reload-plugins

773</h2>

774

775在不重新啟動工作階段的情況下，將待處理的外掛程式變更套用到執行中的工作階段。待處理的變更是指自工作階段啟動以來，您在磁碟上安裝、更新、啟用、停用或編輯的外掛程式。

776

777當您關閉 `/plugin` 面板且在其中進行了待處理的變更時，Claude Code 會為您執行 `/reload-plugins`。在外掛程式面板外發生的變更（例如您在另一個終端機中執行的 `claude plugin` 命令）之後，請自行執行此命令。

778

779```text theme={null}

780/reload-plugins [--force]

781```

782

783| 旗標 | 說明 |

784| :-------- | :----------------------------------------- |

785| `--force` | 即使重新載入會使提示快取失效，也要套用重新載入。不加破折號的 `force` 也可以 |

786

787<h3 id="reload-summary">

788 重新載入摘要

789</h3>

790

791Claude Code 重新載入每個作用中的外掛程式，並列印一行摘要 `Reloaded: N plugins · N skills · N agents · N hooks · N plugin MCP servers · N plugin LSP servers`，在沒有互動式終端機的工作階段中省略外掛程式 MCP 伺服器計數。當任何外掛程式失敗時，摘要會新增 `N errors during load. Run /plugin for details.`

792

793技能計數涵蓋外掛程式提供的每項技能，包括其 `commands/` 項目和其 SKILL.md 技能。代理計數是在工作階段中載入的代理數量，包括不來自外掛程式的代理。

794

795當重新載入的外掛程式的[相依性](/docs/zh-TW/plugins/dependencies)遺失時，Claude Code 會安裝它們、重新載入，並在摘要中附加 `(+ N dependencies: <names>) resolved`。

796

797<h3 id="reloads-that-change-mcp-tools">

798 變更 MCP 工具的重新載入

799</h3>

800

801當重新載入會新增或移除外掛程式 MCP 伺服器或 `LSP` 工具，且該變更會使[提示快取](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)失效時，Claude Code 不會套用重新載入。它會列印類似 `This reload changes MCP tools (<server>) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.` 的一行。傳遞 `--force` 以無論如何套用它。

802

803<h3 id="sessions-without-an-interactive-terminal">

804 沒有互動式終端機的工作階段

805</h3>

806

807`/reload-plugins` 也在沒有互動式終端機的工作階段中執行，例如桌面應用程式、Agent SDK 和[非互動模式](/docs/zh-TW/headless)搭配 `-p`。需要 Claude Code v2.1.260 或更新版本。

808

809在這些工作階段中，命令只在您自行將其輸入到工作階段時執行，例如在 `-p` 提示或桌面應用程式的提示方塊中。當它以其他方式到達時，例如透過[遠端控制](/docs/zh-TW/remote-control)或從 Slack 轉送的訊息，命令會回覆 `/reload-plugins isn't available over a remote connection in this session.` 並且不重新載入任何內容。

810

811這些工作階段中的重新載入不會連接或斷開外掛程式 MCP 伺服器。這些變更會在您的下一個工作階段中生效。

812

813<h2 id="flags-that-load-a-plugin-for-one-session">

814 為單一工作階段載入 plugin 的旗標

815</h2>

816

817兩個 `claude` 旗標為單一工作階段載入 plugin，無需安裝它。兩者都可重複。

818

819Plugin 作者使用它們在發佈前測試 plugin。對於載入-編輯-重新載入工作流程，請參閱 [開發而不使用市場](/docs/zh-TW/plugins/create#develop-without-a-marketplace)。

820

821| 旗標 | 說明 | 範例 |

822| :-------------------- | :--------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |

823| `--plugin-dir <path>` | 從目錄或其 `.zip` 存檔載入 plugin。plugins 資料夾載入每個保存 `.claude-plugin/plugin.json` 的子資料夾。每個旗標採用一個路徑 | `claude --plugin-dir ./my-plugin --plugin-dir ./other.zip` |

824| `--plugin-url <url>` | 從 URL 擷取 plugin `.zip` 存檔。重複旗標，或在一個引用值中傳遞多個 URL 空格分隔 | `claude --plugin-url "https://example.com/a.zip https://example.com/b.zip"` |

825

826任一旗標載入的 plugin 是工作階段專用 plugin。`claude plugin list` 將其顯示為 `<name>@inline`，範圍為 `session`，但僅當相同旗標在子命令前時。例如，執行 `claude --plugin-dir ./my-plugin plugin list`。

827

828當工作階段專用 plugin 與已安裝的 plugin 共享名稱時，Claude Code 為該工作階段載入工作階段專用複製並跳過已安裝的複製。如果您使用 `claude plugin disable <name>@inline` 停用工作階段專用複製，或受管設定鎖定該 plugin 名稱，已安裝的複製改為載入。對於優先順序，請參閱 [Plugin 載入參考](/docs/zh-TW/plugins/loading)。

829

830管理員可以拒絕兩個旗標和 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-TW/env-vars#variables) 變數中命名的資料夾，使用受管 [`disableSideloadFlags`](/docs/zh-TW/settings-reference#disablesideloadflags) 設定。Claude Code 然後列印旗標被您組織的受管設定停用，並結束 `1` 而不啟動。

831

832從 Agent SDK，[`plugins`](/docs/zh-TW/agent-sdk/plugins) 選項等同於 `--plugin-dir`。

833

834<h2 id="next-steps">

835 後續步驟

836</h2>

837

838* [安裝和管理 plugins](/docs/zh-TW/plugins/install)：與步驟相同的操作，以及您在每一個看到的內容

839* [Plugin 載入參考](/docs/zh-TW/plugins/loading)：每個命令在磁碟上變更的內容以及哪個範圍生效

840* [Troubleshoot plugins](/docs/zh-TW/plugins/troubleshooting)：安裝、市場、載入和驗證錯誤訊息及其修復

841* [Plugin manifest 參考](/docs/zh-TW/plugins/manifest-reference)：`claude plugin validate` 檢查的欄位

plugins/code-intelligence.md +156 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Code intelligence plugins

7> 安裝語言伺服器外掛程式，讓 Claude 在編輯後看到型別錯誤並按符號導覽程式碼，並回應 LSP 外掛程式建議對話框。

9Code intelligence 外掛程式為 Claude 提供編輯器所具有的即時診斷和前往定義功能，因此 Claude 可以在執行建置之前捕捉其自身編輯引入的型別錯誤和遺漏的匯入，並按符號而非文字搜尋來尋找定義和參考。

11每個外掛程式都透過語言伺服器協定 (LSP) 將 Claude Code 連接到一種語言的語言伺服器。您從 Anthropic 的官方市集安裝外掛程式，並在您的機器上安裝語言伺服器二進位檔。

13<Note>

14 Code intelligence 外掛程式在終端機工作階段中運作。在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，Claude Code 不會啟動外掛程式語言伺服器，因此 Claude 在那裡無法取得診斷或程式碼導覽。若要撰寫您自己的語言伺服器外掛程式，或連接沒有外掛程式的語言伺服器，請參閱[外掛程式元件中的 LSP 伺服器](/docs/zh-TW/plugins/components#lsp-servers)。

15</Note>

17若要開始使用，請在[安裝 code intelligence 外掛程式](#install-a-code-intelligence-plugin)下的表格中找到您的語言。該表格中的外掛程式來自 Anthropic 的[官方外掛程式市集](/docs/zh-TW/plugins/anthropic-marketplaces)。

19如果您已經看到 **LSP 外掛程式建議**對話框，請參閱[接受或關閉建議對話框](#accept-or-dismiss-the-recommendation-dialog)以了解每個選擇的作用。

21<h2 id="install-a-code-intelligence-plugin">

22 安裝 code intelligence 外掛程式

23</h2>

25Code intelligence 外掛程式告訴 Claude Code 哪個命令啟動語言伺服器以及它處理哪些檔案副檔名。它不包含語言伺服器。先安裝語言伺服器二進位檔，然後安裝外掛程式，最後確認伺服器啟動。

27<Steps>

28 <Step title="安裝語言伺服器二進位檔">

29 在下表中找到您的語言，並安裝其列中的二進位檔。如果您的語言未列出，請參閱[新增沒有官方外掛程式的語言](#add-a-language-without-an-official-plugin)。

31 | 語言 | 外掛程式 | 二進位檔 |

32 | :---------------------- | :--------------------------------------------------------------------------------------------------------------- | :--------------------------- |

33 | C/C++ | [`clangd-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/clangd-lsp) | `clangd` |

34 | C# | [`csharp-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/csharp-lsp) | `csharp-ls` |

35 | Go | [`gopls-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/gopls-lsp) | `gopls` |

36 | Java | [`jdtls-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/jdtls-lsp) | `jdtls` |

37 | Kotlin | [`kotlin-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/kotlin-lsp) | `kotlin-lsp` |

38 | Liquid | [`liquid-lsp`](https://github.com/Shopify/liquid-skills/tree/main/plugins/liquid-lsp) | `shopify`，來自 Shopify CLI |

39 | Lua | [`lua-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/lua-lsp) | `lua-language-server` |

40 | PHP | [`php-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/php-lsp) | `intelephense` |

41 | Python | [`pyright-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/pyright-lsp) | `pyright-langserver` |

42 | Ruby | [`ruby-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ruby-lsp) | `ruby-lsp` |

43 | Rust | [`rust-analyzer-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/rust-analyzer-lsp) | `rust-analyzer` |

44 | Swift | [`swift-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/swift-lsp) | `sourcekit-lsp` |

45 | TypeScript 和 JavaScript | [`typescript-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/typescript-lsp) | `typescript-language-server` |

47 Anthropic 維護表格中的每個外掛程式，除了 `liquid-lsp` 外，該外掛程式由 Shopify 維護，官方市集也列出了它。

49 若要找到安裝二進位檔的命令，請按照表格中的外掛程式連結前往其 README。對於 TypeScript，該命令是 `npm install -g typescript-language-server typescript`。

51 安裝二進位檔後，確認它在您啟動 `claude` 的 shell 的 `PATH` 上，例如使用 `which typescript-language-server`，或在 PowerShell 中使用 `Get-Command typescript-language-server`。

52 </Step>

54 <Step title="安裝外掛程式">

55 若要安裝步驟 1 表格中為您的語言列出的外掛程式，請在 Claude Code 工作階段中執行 `/plugin install`，將 `typescript-lsp` 替換為該外掛程式的名稱：

57 ```

58 /plugin install typescript-lsp@claude-plugins-official

59 ```

61 確認訊息會說明外掛程式現在是否處於作用中或需要 `/reload-plugins`。如果安裝失敗並顯示 `Marketplace "claude-plugins-official" not found`，請參閱[該錯誤的疑難排解項目](/docs/zh-TW/plugins/troubleshooting#marketplace-claude-plugins-official-not-found)。若要控制外掛程式的安裝位置，或從 shell 而不是在 Claude Code 內執行安裝，請參閱[安裝外掛程式](/docs/zh-TW/plugins/install)。

62 </Step>

64 <Step title="確認伺服器啟動">

65 語言伺服器在 Claude 首次編輯具有外掛程式副檔名之一的檔案時啟動。若要看到它運作，請要求 Claude 在該語言的檔案中引入型別錯誤，然後修復它。然後檢查對話框中的診斷行：

67 * **出現診斷行**：在引入錯誤的編輯下方出現 `Found N new diagnostic issues in M files (ctrl+o to expand)` 表示伺服器已啟動。

68 * **未出現診斷行**：執行 `/plugin` 並開啟 **Errors** 標籤。讀取 `Executable not found in $PATH: "<binary>"` 的列會命名要安裝的二進位檔。如果標籤中沒有這樣的列，請參閱[疑難排解 code intelligence](#troubleshoot-code-intelligence)。

70 安裝遺漏的二進位檔後，Claude Code 會在 Claude 下次編輯相符檔案時重試。如果您將二進位檔安裝到不在您啟動 `claude` 的 shell 的 `PATH` 上的目錄中，請從它所在的 shell 啟動新工作階段。

71 </Step>

72</Steps>

74<h2 id="see-what-claude-gains">

75 查看 Claude 獲得的內容

76</h2>

78執行語言伺服器後，Claude 獲得診斷和程式碼導覽：

80* **編輯後的診斷**：每次 Claude 編輯或寫入伺服器處理的檔案時，Claude 都會獲得伺服器報告的錯誤和警告。它會看到它引入的型別錯誤、遺漏的匯入或語法錯誤，而無需執行編譯器。

81* **程式碼導覽**：Claude 獲得一個 `LSP` 工具，該工具透過伺服器查詢符號，而不是搜尋文字。該工具是唯讀的。有關 Claude 可以使用該工具查詢的內容以及權限如何應用於它，請參閱 [LSP 工具行為](/docs/zh-TW/tools-reference#lsp-tool-behavior)。

83<h3 id="read-the-diagnostics-yourself">

84 自己閱讀診斷

85</h3>

87Claude 編輯伺服器處理的檔案後，對話框只顯示 `Found N new diagnostic issues` 摘要。若要閱讀問題本身，請按 **Ctrl+O**。

89<h2 id="accept-or-dismiss-the-recommendation-dialog">

90 接受或關閉建議對話框

91</h2>

93如果語言伺服器二進位檔已在您的 `PATH` 上，但使用它的外掛程式未安裝，Claude Code 會在標題為 **LSP 外掛程式建議**的對話框中提供為您安裝外掛程式。

95<h3 id="when-the-recommendation-dialog-appears">

96 建議對話框何時出現

97</h3>

99**LSP 外掛程式建議**對話框可在 Claude 編輯檔案後出現。這些條件決定它是否出現以及它提供哪個外掛程式：

100

101* **外掛程式符合檔案**：您已新增的其中一個市集或 Claude Code 為您註冊的官方市集列出了該檔案副檔名的 code intelligence 外掛程式，且外掛程式的二進位檔已安裝。

102* **官方優先**：當多個市集為副檔名提供外掛程式時，對話框會提供官方市集的外掛程式。

103* **每個工作階段一次**：對話框在一個工作階段中最多出現一次，針對 Claude 編輯的第一個相符檔案。

104* **不適用於雲端工作階段**：當您的終端機連接到雲端工作階段（例如您使用 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-cloud) 啟動的工作階段）時，對話框永遠不會出現。

105

106<h3 id="respond-to-the-recommendation-dialog">

107 回應建議對話框

108</h3>

109

110**LSP 外掛程式建議**對話框會命名外掛程式並提供這些選擇：

111

112* **Yes, install**：Claude Code 為您的使用者帳戶安裝外掛程式並列印 `<plugin> installed · restart to apply`。啟動新工作階段以載入伺服器。

113* **No, not now**：對話框關閉，稍後的工作階段可以再次提供外掛程式。按 **Esc** 也會執行相同操作。

114* **Never for this plugin**：對話框停止為該外掛程式出現，但仍會為其他外掛程式出現。

115* **Disable all LSP recommendations**：對話框停止為每種語言出現。

116

117如果您未選擇選項，Claude Code 會在 30 秒後關閉它，並將其計為已忽略。計數會跨工作階段保留。在忽略五個對話框後，Claude Code 停止推薦外掛程式，與您選擇 **Disable all LSP recommendations** 相同。

118

119<h3 id="turn-recommendations-back-on">

120 重新開啟建議

121</h3>

122

123**LSP 外掛程式建議**對話框在您選擇 **Disable all LSP recommendations** 或忽略它五次後停止出現。

124

125* **已停用或忽略五次**：若要在任一情況下重新開啟它，請從 `~/.claude.json`（Claude Code 自己的設定檔）中移除 `lspRecommendationDisabled` 和 `lspRecommendationIgnoredCount` 鍵。

126* **永不為此外掛程式**：如果您選擇了 **Never for this plugin** 並希望再次提供該外掛程式，請從同一檔案中的 `lspRecommendationNeverPlugins` 列表中移除其 `name@marketplace` ID。

127

128<h2 id="troubleshoot-code-intelligence">

129 疑難排解 code intelligence

130</h2>

131

132外掛程式疑難排解頁面涵蓋 code intelligence 外掛程式特定的症狀，位於[語言伺服器不啟動、使用過多記憶體或報告錯誤診斷](/docs/zh-TW/plugins/troubleshooting#language-server-doesnt-start)下：

133

134* **語言伺服器不啟動**：您在 `/plugin` 的 **Errors** 標籤中看到 `Executable not found in $PATH`，或 Claude 永遠不會報告該語言的診斷。

135* **高記憶體使用量**：當伺服器索引專案時，記憶體使用量會增加。

136* **monorepo 中的誤判診斷**：診斷報告匯入為未解決，但實際上已解決。

137

138<h2 id="add-a-language-without-an-official-plugin">

139 新增沒有官方外掛程式的語言

140</h2>

141

142如果您的語言不在[官方外掛程式表格](#install-a-code-intelligence-plugin)中，您仍然可以連接語言伺服器。

143

1441. 使用 `.lsp.json` 檔案撰寫外掛程式，該檔案命名伺服器命令和它處理的檔案副檔名。

1452. 然後使用 [`--plugin-dir`](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 載入外掛程式或將其發佈到市集。

146

147有關檔案的欄位和實際範例，請參閱[外掛程式元件中的 LSP 伺服器](/docs/zh-TW/plugins/components#lsp-servers)。

148

149<h2 id="next-steps">

150 後續步驟

151</h2>

152

153* [外掛程式元件中的 LSP 伺服器](/docs/zh-TW/plugins/components#lsp-servers)：為沒有官方外掛程式的語言伺服器撰寫 `.lsp.json`

154* [安裝和管理外掛程式](/docs/zh-TW/plugins/install)：範圍、更新和解除安裝

155* [疑難排解外掛程式](/docs/zh-TW/plugins/troubleshooting)：超出本頁語言伺服器的載入錯誤

156* [在官方市集中尋找外掛程式](/docs/zh-TW/plugins/anthropic-marketplaces#find-plugins-in-the-official-marketplace)：瀏覽官方市集其餘部分的位置

plugins/components.md +1130 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 新增元件至外掛程式

7> 新增技能、hooks、MCP 伺服器及其他所有元件類型至 Claude Code 外掛程式，並提供每種元件的驗證範例。

9export const Piece = ({id, children}) => <div className="pe-piece" data-piece={id}>{children}</div>;

11export const PluginExplorer = ({children}) => {

12 const PIECES = [{

13 id: 'manifest',

14 name: 'Manifest',

15 path: '.claude-plugin/plugin.json',

16 required: "Required by Anthropic's directory",

17 lines: [{

18 depth: 0,

19 kind: 'folder',

20 text: '.claude-plugin/'

21 }, {

22 depth: 1,

23 kind: 'file',

24 text: 'plugin.json'

25 }],

26 href: '/en/plugins/manifest-reference#manifest-file',

27 linkText: 'Go to the manifest reference'

28 }, {

29 id: 'skills',

30 name: 'Skills',

31 path: 'skills/review/SKILL.md',

32 lines: [{

33 depth: 0,

34 kind: 'folder',

35 text: 'skills/'

36 }, {

37 depth: 1,

38 kind: 'folder',

39 text: 'review/'

40 }, {

41 depth: 2,

42 kind: 'file',

43 text: 'SKILL.md'

44 }],

45 href: '/en/plugins/components#skills',

46 linkText: 'Go to the Skills section'

47 }, {

48 id: 'commands',

49 name: 'Commands',

50 path: 'commands/about.md',

51 lines: [{

52 depth: 0,

53 kind: 'folder',

54 text: 'commands/'

55 }, {

56 depth: 1,

57 kind: 'file',

58 text: 'about.md'

59 }],

60 href: '/en/plugins/components#commands',

61 linkText: 'Go to the Commands section'

62 }, {

63 id: 'agents',

64 name: 'Agents',

65 path: 'agents/security-reviewer.md',

66 lines: [{

67 depth: 0,

68 kind: 'folder',

69 text: 'agents/'

70 }, {

71 depth: 1,

72 kind: 'file',

73 text: 'security-reviewer.md'

74 }],

75 href: '/en/plugins/components#agents',

76 linkText: 'Go to the Agents section'

77 }, {

78 id: 'hooks',

79 name: 'Hooks',

80 path: 'hooks/hooks.json',

81 lines: [{

82 depth: 0,

83 kind: 'folder',

84 text: 'hooks/'

85 }, {

86 depth: 1,

87 kind: 'file',

88 text: 'hooks.json'

89 }],

90 href: '/en/plugins/components#hooks',

91 linkText: 'Go to the Hooks section'

92 }, {

93 id: 'monitors',

94 name: 'Monitors',

95 path: 'monitors/monitors.json',

96 lines: [{

97 depth: 0,

98 kind: 'folder',

99 text: 'monitors/'

100 }, {

101 depth: 1,

102 kind: 'file',

103 text: 'monitors.json'

104 }],

105 href: '/en/plugins/components#monitors',

106 linkText: 'Go to the Monitors section'

107 }, {

108 id: 'output-styles',

109 name: 'Output styles',

110 path: 'output-styles/terse.md',

111 lines: [{

112 depth: 0,

113 kind: 'folder',

114 text: 'output-styles/'

115 }, {

116 depth: 1,

117 kind: 'file',

118 text: 'terse.md'

119 }],

120 href: '/en/plugins/components#themes-and-output-styles',

121 linkText: 'Go to the Themes and output styles section'

122 }, {

123 id: 'themes',

124 name: 'Themes',

125 path: 'themes/dracula.json',

126 lines: [{

127 depth: 0,

128 kind: 'folder',

129 text: 'themes/'

130 }, {

131 depth: 1,

132 kind: 'file',

133 text: 'dracula.json'

134 }],

135 href: '/en/plugins/components#themes-and-output-styles',

136 linkText: 'Go to the Themes and output styles section'

137 }, {

138 id: 'workflows',

139 name: 'Workflows',

140 path: 'workflows/audit-routes.js',

141 lines: [{

142 depth: 0,

143 kind: 'folder',

144 text: 'workflows/'

145 }, {

146 depth: 1,

147 kind: 'file',

148 text: 'audit-routes.js'

149 }],

150 href: '/en/workflows#distribute-a-workflow-in-a-plugin',

151 linkText: 'Go to Distribute a workflow in a plugin'

152 }, {

153 id: 'bin',

154 name: 'Executables',

155 path: 'bin/hello-plugin',

156 lines: [{

157 depth: 0,

158 kind: 'folder',

159 text: 'bin/'

160 }, {

161 depth: 1,

162 kind: 'file',

163 text: 'hello-plugin'

164 }],

165 href: '/en/plugins/components#executables',

166 linkText: 'Go to the Executables section'

167 }, {

168 id: 'scripts',

169 name: 'Scripts',

170 path: 'scripts/format.sh',

171 lines: [{

172 depth: 0,

173 kind: 'folder',

174 text: 'scripts/'

175 }, {

176 depth: 1,

177 kind: 'file',

178 text: 'format.sh'

179 }],

180 href: '/en/plugins/components#hooks',

181 linkText: 'Go to the Hooks section'

182 }, {

183 id: 'settings',

184 name: 'Default settings',

185 path: 'settings.json',

186 lines: [{

187 depth: 0,

188 kind: 'file',

189 text: 'settings.json'

190 }],

191 href: '/en/plugins/components#default-settings',

192 linkText: 'Go to the Default settings section'

193 }, {

194 id: 'mcp',

195 name: 'MCP servers',

196 path: '.mcp.json',

197 lines: [{

198 depth: 0,

199 kind: 'file',

200 text: '.mcp.json'

201 }],

202 href: '/en/plugins/components#mcp-servers',

203 linkText: 'Go to the MCP servers section'

204 }, {

205 id: 'lsp',

206 name: 'LSP servers',

207 path: '.lsp.json',

208 lines: [{

209 depth: 0,

210 kind: 'file',

211 text: '.lsp.json'

212 }],

213 href: '/en/plugins/components#lsp-servers',

214 linkText: 'Go to the LSP servers section'

215 }];

216 const [selectedId, setSelectedId] = useState('manifest');

217 const [isFullscreen, setIsFullscreen] = useState(false);

218 const rootRef = useRef(null);

219 useEffect(() => {

220 const onFsChange = () => setIsFullscreen(!!document.fullscreenElement);

221 document.addEventListener('fullscreenchange', onFsChange);

222 return () => document.removeEventListener('fullscreenchange', onFsChange);

223 }, []);

224 const toggleFullscreen = () => {

225 if (!rootRef.current) return;

226 if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {});

227 };

228 const selected = PIECES.find(p => p.id === selectedId) || PIECES[0];

229 const onTreeKeyDown = e => {

230 const keys = ['ArrowDown', 'ArrowUp', 'Home', 'End'];

231 if (keys.indexOf(e.key) === -1) return;

232 const i = PIECES.findIndex(p => p.id === selectedId);

233 let next = i;

234 if (e.key === 'ArrowDown') next = Math.min(PIECES.length - 1, i + 1);

235 if (e.key === 'ArrowUp') next = Math.max(0, i - 1);

236 if (e.key === 'Home') next = 0;

237 if (e.key === 'End') next = PIECES.length - 1;

238 e.preventDefault();

239 if (next === i) return;

240 const id = PIECES[next].id;

241 setSelectedId(id);

242 const el = document.getElementById('pe-node-' + id);

243 if (el) el.focus();

244 };

245 const FolderIcon = () => <svg className="pe-icon" width="15" height="15" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" aria-hidden="true">

246 <path d="M1.5 4.5a1 1 0 0 1 1-1h3.2l1.3 1.5h6a1 1 0 0 1 1 1V12a1 1 0 0 1-1 1h-10.5a1 1 0 0 1-1-1z" />

247 </svg>;

248 const FileIcon = () => <svg className="pe-icon" width="15" height="15" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" aria-hidden="true">

249 <path d="M4 1.5h5.5L13 5v9.5H4z" />

250 <path d="M9.5 1.5V5H13" />

251 </svg>;

252 return <div ref={rootRef} className={isFullscreen ? 'pe-root pe-fullscreen not-prose' : 'pe-root not-prose'} data-selected={selected.id}>

253 <style>{`

254 .pe-root {

255 --pe-mono: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);

256 --pe-accent: #D97757;

257 --pe-accent-text: #A8502F;

258 --pe-accent-bg: rgba(217,119,87,0.10);

259 --pe-bg: #FFFFFF;

260 --pe-surface: #FAFAF7;

261 --pe-hover: #F0EEE6;

262 --pe-border: #E8E6DC;

263 --pe-text: #141413;

264 --pe-text-2: #3D3D3A;

265 --pe-text-3: #5E5D59;

266 font-family: inherit;

267 background: var(--pe-bg);

268 color: var(--pe-text);

269 border: 1px solid var(--pe-border);

270 border-radius: 12px;

271 margin: 1.5rem 0;

272 overflow: hidden;

273 box-sizing: border-box;

274 }

275 .dark .pe-root {

276 --pe-accent-text: #EBA98F;

277 --pe-accent-bg: rgba(217,119,87,0.18);

278 --pe-bg: #1A1918;

279 --pe-surface: #232221;

280 --pe-hover: #2E2D2B;

281 --pe-border: #3A3936;

282 --pe-text: #F1EFE9;

283 --pe-text-2: #D6D4CA;

284 --pe-text-3: #B8B5AD;

285 }

286 .pe-root *, .pe-root *::before, .pe-root *::after { box-sizing: border-box; }

287 .pe-head { display: flex; align-items: flex-start; gap: 12px; padding: 18px 24px 16px; border-bottom: 1px solid var(--pe-border); }

288 .pe-head-text { flex: 1; min-width: 0; }

289 .pe-fs-btn { flex-shrink: 0; width: 32px; height: 32px; display: inline-flex; align-items: center; justify-content: center; border: 1px solid var(--pe-border); border-radius: 6px; background: var(--pe-surface); color: var(--pe-text-2); font-size: 15px; line-height: 1; cursor: pointer; }

290 .pe-fs-btn:hover { background: var(--pe-hover); }

291 .pe-fs-btn:focus-visible { outline: 2px solid var(--pe-accent); outline-offset: 2px; }

292 .pe-fullscreen { border-radius: 0; height: 100vh; display: flex; flex-direction: column; overflow: auto; }

293 .pe-fullscreen .pe-body { flex: 1; }

294 .pe-title { font-size: 19px; font-weight: 600; line-height: 1.3; color: var(--pe-text); margin: 0; }

295 .pe-sub { font-size: 15px; line-height: 1.5; color: var(--pe-text-3); margin: 4px 0 0; }

296 .pe-sub code { font-family: var(--pe-mono); font-size: 0.88em; padding: 1px 5px; border-radius: 4px; background: var(--pe-surface); border: 1px solid var(--pe-border); }

297 .pe-body { display: flex; align-items: stretch; }

298 .pe-tree-pane { width: 270px; flex-shrink: 0; background: var(--pe-surface); border-right: 1px solid var(--pe-border); padding: 16px 0 12px; }

299 .pe-panel { flex: 1; min-width: 0; padding: 16px 24px 24px; }

300 .pe-caption { font-size: 13px; font-weight: 600; color: var(--pe-text-3); margin: 0 0 10px; }

301 .pe-tree-pane .pe-caption { padding: 0 16px; }

302 .pe-rootline { display: flex; align-items: center; gap: 7px; padding: 3px 16px; font-family: var(--pe-mono); font-size: 13.5px; color: var(--pe-text-3); }

303 .pe-node {

304 display: block; width: 100%; margin: 0; padding: 3px 16px 3px 30px; text-align: left; cursor: pointer;

305 background: transparent; color: var(--pe-text-2);

306 border: none; border-left: 3px solid transparent;

307 font-family: var(--pe-mono); font-size: 13.5px; line-height: 1.4;

308 }

309 .pe-node:hover { background: var(--pe-hover); }

310 .pe-node:focus-visible { outline: 2px solid var(--pe-accent); outline-offset: -2px; }

311 .pe-node[aria-pressed="true"] { background: var(--pe-accent-bg); border-left-color: var(--pe-accent); color: var(--pe-accent-text); font-weight: 600; }

312 .pe-line { display: flex; align-items: center; gap: 7px; padding: 2px 0; }

313 .pe-line-tree { flex-wrap: wrap; }

314 .pe-line-tree .pe-req { flex-basis: 100%; margin: 2px 0 0 22px; white-space: normal; width: fit-content; max-width: calc(100% - 22px); }

315 .pe-line span { overflow-wrap: anywhere; }

316 .pe-piece { display: none; font-size: 16px; line-height: 1.6; color: var(--pe-text-2); }

317 .pe-root[data-selected="manifest"] .pe-piece[data-piece="manifest"],

318 .pe-root[data-selected="skills"] .pe-piece[data-piece="skills"],

319 .pe-root[data-selected="commands"] .pe-piece[data-piece="commands"],

320 .pe-root[data-selected="agents"] .pe-piece[data-piece="agents"],

321 .pe-root[data-selected="hooks"] .pe-piece[data-piece="hooks"],

322 .pe-root[data-selected="monitors"] .pe-piece[data-piece="monitors"],

323 .pe-root[data-selected="output-styles"] .pe-piece[data-piece="output-styles"],

324 .pe-root[data-selected="themes"] .pe-piece[data-piece="themes"],

325 .pe-root[data-selected="workflows"] .pe-piece[data-piece="workflows"],

326 .pe-root[data-selected="bin"] .pe-piece[data-piece="bin"],

327 .pe-root[data-selected="scripts"] .pe-piece[data-piece="scripts"],

328 .pe-root[data-selected="settings"] .pe-piece[data-piece="settings"],

329 .pe-root[data-selected="mcp"] .pe-piece[data-piece="mcp"],

330 .pe-root[data-selected="lsp"] .pe-piece[data-piece="lsp"] { display: block; }

331 .pe-piece p { margin: 0 0 10px; }

332 .pe-piece p:last-child { margin-bottom: 0; }

333 .pe-piece code { font-family: var(--pe-mono); font-size: 0.88em; padding: 1px 5px; border-radius: 4px; background: var(--pe-surface); border: 1px solid var(--pe-border); }

334 .pe-piece .code-block { margin: 12px 0 0; }

335 .pe-piece pre code { padding: 0; border: none; background: none; }

336 .pe-piece a { color: var(--pe-accent-text); }

337 .pe-line-compact { display: none; }

338 .pe-icon { flex-shrink: 0; }

339 .pe-req { margin-left: 8px; padding: 0 6px; border-radius: 999px; font-size: 11px; line-height: 18px; letter-spacing: .02em; color: var(--pe-accent-text); border: 1px solid var(--pe-border); background: var(--pe-surface); white-space: nowrap; font-weight: 500; vertical-align: middle; }

340 .pe-name { font-size: 22px; font-weight: 600; line-height: 1.25; letter-spacing: -0.2px; color: var(--pe-text); margin: 0; }

341 .pe-path { font-family: var(--pe-mono); font-size: 13.5px; color: var(--pe-accent-text); margin: 4px 0 0; overflow-wrap: anywhere; }

342 .pe-block { margin: 20px 0 0; }

343 .pe-link {

344 display: inline-block; margin: 24px 0 0; padding: 8px 14px; border-radius: 8px;

345 font-size: 14.5px; font-weight: 600; text-decoration: none;

346 color: var(--pe-accent-text); background: var(--pe-accent-bg); border: 1px solid var(--pe-accent);

347 }

348 .pe-link:hover { filter: brightness(0.97); }

349 .pe-link:focus-visible { outline: 2px solid var(--pe-accent); outline-offset: 2px; }

350 @media (max-width: 700px) {

351 .pe-head { padding: 16px 16px 14px; }

352 .pe-body { flex-direction: column; }

353 .pe-tree-pane { width: 100%; border-right: none; border-bottom: 1px solid var(--pe-border); }

354 .pe-line-tree { display: none; }

355 .pe-line-compact { display: flex; }

356 .pe-panel { padding: 16px 16px 20px; }

357 }

358 `}</style>

359

360 <div className="pe-head">

361 <div className="pe-head-text">

362 <div className="pe-title">What goes in a plugin</div>

363 <div className="pe-sub">This example plugin, <code>my-plugin</code>, has one of every kind of component, each in its default location. Select a file or folder to read what it’s for and see what goes in it.</div>

364 </div>

365 <button type="button" className="pe-fs-btn" onClick={toggleFullscreen} aria-label={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}>

366 {isFullscreen ? '⤡' : '⛶'}

367 </button>

368 </div>

369

370 <div className="pe-body">

371 <div className="pe-tree-pane">

372 <div className="pe-caption" id="pe-tree-caption">Plugin directory</div>

373 <div role="group" aria-labelledby="pe-tree-caption" onKeyDown={onTreeKeyDown}>

374 <div className="pe-rootline"><FolderIcon /><span>my-plugin/</span></div>

375 {PIECES.map(p => <button key={p.id} id={'pe-node-' + p.id} type="button" className="pe-node" aria-pressed={p.id === selected.id} aria-label={p.name + ', ' + p.path} onClick={() => setSelectedId(p.id)}>

376 {p.lines.map((line, i) => <span key={i} className="pe-line pe-line-tree" style={{

377 paddingLeft: line.depth * 18 + 'px'

378 }}>

379 {line.kind === 'folder' ? <FolderIcon /> : <FileIcon />}

380 <span>{line.text}</span>

381 {p.required && i === p.lines.length - 1 ? <span className="pe-req">{p.required}</span> : null}

382 </span>)}

383 <span className="pe-line pe-line-compact">

384 <FileIcon />

385 <span>{p.path}</span>

386 {p.required ? <span className="pe-req">{p.required}</span> : null}

387 </span>

388 </button>)}

389 </div>

390 </div>

391

392 <div className="pe-panel" role="region" aria-labelledby="pe-panel-caption" aria-live="polite" aria-atomic="true">

393 <div className="pe-caption" id="pe-panel-caption">Selected piece</div>

394 <div className="pe-name">{selected.name}{selected.required ? <span className="pe-req">{selected.required}</span> : null}</div>

395 <div className="pe-path">{selected.path}</div>

396

397 <div className="pe-block">{children}</div>

398

399 <a className="pe-link" href={selected.href}>{selected.linkText}</a>

400 </div>

401 </div>

402 </div>;

403};

404

405Claude Code 外掛程式由多個元件組成，例如技能、代理、hooks 和 MCP 伺服器。每個元件在外掛程式中都有一個預設資料夾、`.claude-plugin/plugin.json` 中的選用資訊清單鍵（用於取代或新增至該資料夾），以及使用者看到的名稱。如需每個鍵的完整欄位表，請參閱[資訊清單參考](/docs/zh-TW/plugins/manifest-reference#fields)。

406

407使用此頁面將元件新增至已載入的外掛程式。

408

409新增元件後，在執行中的工作階段中執行 `/reload-plugins`，或啟動新的工作階段，以便 Claude Code 載入該元件。若要在載入前檢查元件的檔案，請從外掛程式目錄在您的殼層中執行 [`claude plugin validate .`](/docs/zh-TW/plugins/cli-reference#plugin-validate)。

410

411<Note>

412 這些情況涵蓋在其他頁面上：

413

414 * **建立您的第一個外掛程式**：從[建立外掛程式](/docs/zh-TW/plugins/create)開始

415 * **安裝他人的外掛程式**：請參閱[安裝外掛程式](/docs/zh-TW/plugins/install)

416 * **您的外掛程式使用者在 claude.ai 或 Cowork 上**：那裡會載入不同的元件集合。請參閱[claude.ai 和 Cowork 上的外掛程式](https://claude.com/docs/plugins/overview)

417</Note>

418

419<h2 id="explore-the-plugin-directory">

420 探索外掛程式目錄

421</h2>

422

423探索工具顯示一個範例外掛程式 `my-plugin`，其在預設位置具有每種元件：

424

425* 一個審查 skill 和一個 `about` 命令

426* 一個安全審查子代理

427* 一個在 Claude 編輯檔案後格式化檔案的 hook，以及它呼叫的 `scripts/` 資料夾

428* 一個日誌監視器

429* 一個輸出樣式和一個色彩主題

430* 一個路由審計工作流程

431* 一個 `hello-plugin` 可執行檔

432* 預設設定

433* 一個本機 MCP 伺服器和一個 Go 語言伺服器

434

435每個檔案都是其格式的最小有效範例，目的是展示形狀而不是有用：真實的 skill 或 agent 包含完整的指示，通常還有支援檔案，真實的 hook 或監視器執行真實的工作。探索工具後的章節使用與探索工具相同的檔案作為範例，並連結至更完整的檔案。選擇檔案或資料夾以讀取其用途、查看其內容，並找到涵蓋它的章節。

436

437<PluginExplorer>

438 <Piece id="manifest">

439 [manifest](/docs/zh-TW/plugins/manifest-reference) 是外掛程式 `.claude-plugin/` 目錄中的 `plugin.json` 檔案。它包含外掛程式的中繼資料和 Claude Code 提示使用者的 `userConfig` 值。只有 `name` 是必需的。在這個中，`description` 是使用者在 `/plugin` 中看到的外掛程式文字，`version` 會讓使用者保持在該版本，直到您變更它：

440

441 ```json theme={null}

442 {

443 "name": "my-plugin",

444 "version": "1.0.0",

445 "description": "Review, formatting, and database tools for this team"

446 }

447 ```

448 </Piece>

449

450 <Piece id="skills">

451 [skill](/docs/zh-TW/skills) 是一個 `SKILL.md` 檔案。將每個 skill 儲存在 `skills/` 下的自己的目錄中。Claude 讀取每個 skill 的 `description`，當使用者要求的內容與其相符時（例如要求 Claude 審查此處的提取請求），Claude 會載入 skill 的指示並遵循它們。使用者也可以直接執行它作為 `/my-plugin:review`：

452

453 ```markdown theme={null}

454 ---

455 description: Reviews a pull request for style and test coverage. Use when asked to review code.

456 ---

457

458 Review the changed files. Report style problems first, then missing tests.

459 ```

460 </Piece>

461

462 <Piece id="commands">

463 命令是使用者按名稱執行的單一 Markdown 檔案。命令是較舊的格式：skill 按名稱執行的方式相同，也可以在自己的目錄中攜帶支援檔案，因此將新的寫成 skills，並為您已有的檔案保留 `commands/`。此檔案變成 `/my-plugin:about`，並採用與 skill 相同的 frontmatter：

464

465 ```markdown theme={null}

466 ---

467 description: Summarize the repository

468 ---

469

470 Summarize what this repository does in three sentences.

471 ```

472 </Piece>

473

474 <Piece id="agents">

475 [子代理](/docs/zh-TW/sub-agents) 是一個單獨的助手，具有自己的指示和自己的內容視窗，Claude 可以將任務委派給它並取回結果。`agents/` 下的每個 Markdown 檔案定義一個：frontmatter 命名它並說明何時使用它，正文是其系統提示。這個命名為 `my-plugin:security-reviewer`，使用者可以使用 `@agent-my-plugin:security-reviewer` 叫用它：

476

477 ```markdown theme={null}

478 ---

479 name: security-reviewer

480 description: Reviews code changes for security issues. Use after edits to authentication or input handling.

481 model: sonnet

482 ---

483

484 You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

485 ```

486 </Piece>

487

488 <Piece id="hooks">

489 [hook](/docs/zh-TW/hooks-guide) 在 Claude Code 生命週期中的某個點自動執行某些操作，例如在每次檔案編輯後：shell 命令、HTTP 請求、MCP 工具呼叫、對模型的提示或子代理。將外掛程式的 hooks 儲存在外掛程式根目錄的 `hooks/hooks.json` 中。這個在 Claude 寫入或編輯檔案後執行外掛程式的 `scripts/format.sh`：

490

491 ```json theme={null}

492 {

493 "hooks": {

494 "PostToolUse": [

495 {

496 "matcher": "Write|Edit",

497 "hooks": [

498 {

499 "type": "command",

500 "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""

501 }

502 ]

503 }

504 ]

505 }

506 }

507 ```

508 </Piece>

509

510 <Piece id="monitors">

511 監視器是一個 shell 命令，Claude Code 在工作階段啟動時在背景啟動，並保持執行直到工作階段結束，使用 [Monitor 工具](/docs/zh-TW/tools-reference#monitor-tool)。它列印的內容作為通知到達 Claude。`when` 欄位可以改為在命名 skill 首次執行時啟動它。這個尾部一個錯誤日誌：

512

513 ```json theme={null}

514 [

515 {

516 "name": "error-log",

517 "command": "tail -F ./logs/error.log",

518 "description": "Application error log"

519 }

520 ]

521 ```

522 </Piece>

523

524 <Piece id="output-styles">

525 外掛程式可以包含 [輸出樣式](/docs/zh-TW/output-styles)，這會改變 Claude 格式化和措辭其回覆的方式。將每個輸出樣式儲存為 `output-styles/<name>.md`。這個在 `/output-style` 中顯示為 `my-plugin:terse`：

526

527 ```markdown theme={null}

528 ---

529 name: terse

530 description: Answer in as few words as possible

531 keep-coding-instructions: true

532 ---

533

534 Keep every reply short. Skip preambles and summaries.

535 ```

536 </Piece>

537

538 <Piece id="themes">

539 外掛程式可以包含 [Claude Code 介面的色彩主題](/docs/zh-TW/terminal-config#create-a-custom-theme)。將每個主題儲存為 `themes/<slug>.json`。這個在 `/theme` 中顯示為 `Dracula`，標記為來自 `my-plugin`：

540

541 ```json theme={null}

542 {

543 "name": "Dracula",

544 "base": "dark",

545 "overrides": {

546 "claude": "#bd93f9",

547 "error": "#ff5555"

548 }

549 }

550 ```

551 </Piece>

552

553 <Piece id="workflows">

554 `workflows/` 資料夾包含 [workflow](/docs/zh-TW/workflows) `.js` 檔案：一個 `meta` 區塊，然後是協調多個子代理的指令碼正文。這個執行為 `/my-plugin:audit-routes`：

555

556 ```javascript theme={null}

557 export const meta = {

558 name: 'audit-routes',

559 description: 'Audit every route handler for missing auth checks',

560 }

561

562 const found = await agent('List every .ts file under src/routes/.', {

563 schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },

564 })

565

566 const audits = await pipeline(found.files, file =>

567 agent(`Audit ${file} for missing authentication checks.`, { label: file }),

568 )

569

570 return audits.filter(Boolean)

571 ```

572 </Piece>

573

574 <Piece id="bin">

575 `bin/` 是外掛程式如何提供命令列工具的方式。啟用外掛程式時，Claude Code 將此資料夾放在它執行命令的 shell 的 `PATH` 上，因此 Claude 或 skill 的指示可以按名稱執行工具，而無需使用者安裝任何東西。有了這個 [可執行檔](#executables)，`hello-plugin` 是 Claude 可以執行的命令：

576

577 ```bash theme={null}

578 #!/bin/bash

579 echo "hello from my-plugin"

580 ```

581 </Piece>

582

583 <Piece id="scripts">

584 `hooks/hooks.json` 中的 hook 執行指令碼，此資料夾是範例保留它的位置。名稱 `scripts/` 是一個慣例，不是 Claude Code 尋找的東西：hook 按其路徑指向檔案，`${CLAUDE_PLUGIN_ROOT}/scripts/format.sh`。格式化指令碼可能看起來像這樣：

585

586 ```bash theme={null}

587 #!/bin/bash

588 npx prettier --write .

589 ```

590 </Piece>

591

592 <Piece id="settings">

593 外掛程式根目錄的 `settings.json` 包含在啟用外掛程式時適用的 [設定](/docs/zh-TW/settings-reference)，因此外掛程式可以改變工作階段的行為方式，而不僅僅是新增元件。只有兩個鍵從外掛程式生效，[`agent`](/docs/zh-TW/settings-reference#agent) 和 [`subagentStatusLine`](/docs/zh-TW/settings-reference#subagentstatusline)；所有其他鍵都被丟棄。請參閱 [預設設定](#default-settings)。

594

595 這個設定 `agent`，它執行工作階段的主執行緒作為外掛程式自己的 `security-reviewer` agent，因此該 agent 的系統提示、工具限制和模型適用於整個工作階段：

596

597 ```json theme={null}

598 {

599 "agent": "security-reviewer"

600 }

601 ```

602 </Piece>

603

604 <Piece id="mcp">

605 [MCP 伺服器](/docs/zh-TW/mcp) 從外部系統為 Claude 提供工具。在外掛程式根目錄的 `.mcp.json` 中宣告它。這個啟動外掛程式內指令碼中的本機伺服器，並在 `/mcp` 中顯示為 `plugin:my-plugin:db`：

606

607 ```json theme={null}

608 {

609 "mcpServers": {

610 "db": {

611 "command": "node",

612 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]

613 }

614 }

615 }

616 ```

617 </Piece>

618

619 <Piece id="lsp">

620 LSP 伺服器為 Claude 提供 [診斷和程式碼導航](/docs/zh-TW/plugins/code-intelligence) 用於語言。在外掛程式根目錄的 `.lsp.json` 中宣告伺服器。這個連接 Go 語言伺服器用於 `.go` 檔案：

621

622 ```json theme={null}

623 {

624 "gopls": {

625 "command": "gopls",

626 "args": ["serve"],

627 "extensionToLanguage": {

628 ".go": "go"

629 }

630 }

631 }

632 ```

633 </Piece>

634</PluginExplorer>

635

636<h2 id="add-each-kind-of-component">

637 新增每種元件

638</h2>

639

640下面的每個章節涵蓋一種元件：其檔案在外掛程式中的位置、驗證的範例、外掛程式載入後使用者看到的內容，以及改變預設位置的 manifest 鍵。新增您的外掛程式需要的；沒有任何是必需的。

641

642<h3 id="skills">

643 Skills

644</h3>

645

646[skill](/docs/zh-TW/skills) 是一個 `SKILL.md` 檔案，當其描述與任務相符時 Claude 可以載入。使用者也可以將其作為命令執行。將每個 skill 儲存在 `skills/` 下的自己的目錄中：

647

648```text theme={null}

649my-plugin/

650├── .claude-plugin/

651│ └── plugin.json

652└── skills/

653 └── review/

654 └── SKILL.md

655```

656

657給 `SKILL.md` 一個 `description`，以便 Claude 知道何時使用它：

658

659```markdown skills/review/SKILL.md theme={null}

660---

661description: Reviews a pull request for style and test coverage. Use when asked to review code.

662---

663

664Review the changed files. Report style problems first, then missing tests.

665```

666

667載入外掛程式後，`/my-plugin:review` 執行 skill。命令名稱和誰可以叫用它遵循這些規則：

668

669* **命令名稱**：`/<plugin>:<directory>`，所以 `my-plugin` 中的 `skills/review/SKILL.md` 是 `/my-plugin:review`。如果您在 frontmatter 中設定 `name`，它會取代最後一個區段，外掛程式前綴保持不變。請參閱 [skill 如何獲得其命令名稱](/docs/zh-TW/skills#how-a-skill-gets-its-command-name)

670* **誰叫用它**：Claude、使用者或兩者，由 frontmatter 控制。請參閱 [控制誰叫用 skill](/docs/zh-TW/skills#control-who-invokes-a-skill)

671

672您也可以將 skills 放在預設 `skills/` 目錄之外：

673

674* **其他目錄**：在 `skills` manifest 鍵中列出它們。它們新增至預設 `skills/` 掃描，而不是取代它，不像 `commands` 和 `agents`

675* **外掛程式根目錄的單一 skill**：沒有 `skills/` 目錄且沒有 `skills` manifest 鍵，外掛程式根目錄的 `SKILL.md` 載入為一個 skill。在其 frontmatter 中設定 `name`，因為否則市場安裝會在其 [快取目錄](/docs/zh-TW/plugins/loading#find-plugins-on-disk) 之後命名 skill，而不是您的外掛程式

676

677若要在外掛程式中包含指示，將其寫成 skill。Claude Code 不會載入外掛程式根目錄的 `CLAUDE.md`，`claude plugin validate` 會警告 `CLAUDE.md at the plugin root is not loaded as project context`。

678

679如需 frontmatter 欄位和支援檔案，請參閱 [Skills](/docs/zh-TW/skills)。

680

681<h3 id="commands">

682 命令

683</h3>

684

685命令是使用者按名稱執行的單一 Markdown 檔案，例如 `/my-plugin:about`。

686

687<Note>

688 命令是較舊的格式，[skills](#skills) 對新工作已取代它們。skill 按名稱執行的方式相同，它也可以在其目錄中攜帶支援檔案。為您從 `.claude/commands/` 移動的檔案保留 `commands/`。

689</Note>

690

691將命令儲存在 `commands/<file>.md`，它變成 `/<plugin>:<file>`。子目錄新增一個區段，所以 `commands/db/migrate.md` 是 `/my-plugin:db:migrate`。

692

693命令檔案採用與 skills 相同的 frontmatter。

694

695<h4 id="define-commands-in-the-manifest">

696 在 manifest 中定義命令

697</h4>

698

699只有當您想將命令檔案保留在 `commands/` 以外的地方，或在 `plugin.json` 中定義短命令而不需要單獨的 Markdown 檔案時，您才需要這個。設定 `commands` manifest 鍵，Claude Code 會讀取它而不是掃描 `commands/`。鍵採用路徑、路徑陣列或將每個命令名稱對應到 `source` 檔案或內嵌 `content` 的物件。

700

701此 manifest 內嵌定義 `/my-plugin:about`，沒有 Markdown 檔案：

702

703```json .claude-plugin/plugin.json theme={null}

704{

705 "name": "my-plugin",

706 "commands": {

707 "about": {

708 "content": "Summarize what this repository does in three sentences.",

709 "description": "Summarize the repository"

710 }

711 }

712}

713```

714

715載入外掛程式並在工作階段中執行 `/my-plugin:about` 以確認它已載入。

716

717如需完整的鍵語法，請參閱 [`commands`](/docs/zh-TW/plugins/manifest-reference#commands)。

718

719<h3 id="agents">

720 Agents

721</h3>

722

723[子代理](/docs/zh-TW/sub-agents) 是一個單獨的助手，具有自己的指示和內容視窗，Claude 可以將任務委派給它。`agents/` 下的每個 Markdown 檔案定義一個：

724

725```markdown agents/security-reviewer.md theme={null}

726---

727name: security-reviewer

728description: Reviews code changes for security issues. Use after edits to authentication or input handling.

729model: sonnet

730---

731

732You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

733```

734

735此 agent 命名為 `my-plugin:security-reviewer`，使用者可以使用 `@agent-my-plugin:security-reviewer` [明確叫用它](/docs/zh-TW/sub-agents#invoke-subagents-explicitly)。名稱形式是 `<plugin>:<name>`，其中 `<name>` 來自 frontmatter，或沒有時來自檔案名稱。

736

737`agents` manifest 鍵取代 `agents/` 掃描。

738

739<h4 id="organize-agents-in-subfolders">

740 在子資料夾中組織 agents

741</h4>

742

743您可以將外掛程式 agent 檔案放在 `agents/` 的子資料夾中。Claude Code [遞迴載入它們](/docs/zh-TW/sub-agents#choose-the-subagent-scope)，並使用冒號連接外掛程式名稱、每個子資料夾名稱和檔案名稱以形成 agent 的範圍名稱。例如，`my-plugin` 中的 `agents/review/security.md` 載入為 `my-plugin:review:security`。兩個設定改變該名稱：

744

745* Frontmatter `name`：它只取代檔案名稱，所以 `agents/review/security.md` 中的 `name: audit` 載入為 `my-plugin:review:audit`

746* Manifest [`agents`](/docs/zh-TW/plugins/manifest-reference#fields) 欄位：您在那裡列出的檔案載入時沒有子資料夾名稱，所以 `"agents": "./custom/review/security.md"` 載入為 `my-plugin:security`

747

748<h4 id="frontmatter-fields-in-plugin-agents">

749 外掛程式 agents 中的 Frontmatter 欄位

750</h4>

751

752外掛程式 agent 的 frontmatter 遵循這些規則：

753

754* **支援的欄位**：`name`、`description`、`model`、`effort`、`maxTurns`、`tools`、`disallowedTools`、`skills`、`memory`、`background`、`omitClaudeMd`、`isolation`、`color` 和 `experimental` 的 `cacheTtl` 鍵。唯一有效的 `isolation` 值是 `"worktree"`。請參閱 [支援的 frontmatter 欄位](/docs/zh-TW/sub-agents#supported-frontmatter-fields) 以了解每個欄位的作用

755* **忽略的欄位**：`permissionMode`、`hooks`、`mcpServers` 和 `initialPrompt`。agent 檔案無法自行新增 hooks 或 MCP 伺服器，因此改為將這些新增為外掛程式 [hooks](#hooks) 和 [MCP 伺服器](#mcp-servers)

756* **無法解析的 Frontmatter**：agent 仍然載入，每個欄位都被忽略。它以檔案命名，其描述讀取 `Agent from my-plugin plugin`。在您的 shell 中執行 [`claude plugin validate`](/docs/zh-TW/plugins/cli-reference#plugin-validate) 以找到這些檔案

757

758如需每個欄位的作用和優先順序規則，請參閱 [子代理](/docs/zh-TW/sub-agents#supported-frontmatter-fields)。

759

760<h3 id="hooks">

761 Hooks

762</h3>

763

764[hook](/docs/zh-TW/hooks-guide) 在 Claude Code 生命週期中的某個點自動執行某些操作，例如在每次檔案編輯後：shell 命令、HTTP 請求、MCP 工具呼叫、對模型的提示或子代理。將外掛程式的 hooks 儲存在外掛程式根目錄的 `hooks/hooks.json` 中，在頂層 `"hooks"` 鍵下，形狀與 `settings.json` 中的 `hooks` 物件相同。這讓您可以複製現有的設定 hook 而不變更。

765

766此 hook 在每個 `Write` 或 `Edit` 後執行捆綁的指令碼：

767

768```json hooks/hooks.json theme={null}

769{

770 "hooks": {

771 "PostToolUse": [

772 {

773 "matcher": "Write|Edit",

774 "hooks": [

775 {

776 "type": "command",

777 "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""

778 }

779 ]

780 }

781 ]

782 }

783}

784```

785

786將指令碼儲存在 `scripts/format.sh` 並使其可執行。

787

788載入外掛程式並要求 Claude 編輯檔案。退出 0 的 `PostToolUse` hook 在文字記錄中不顯示任何內容，因此使用 [偵錯日誌](/docs/zh-TW/hooks#debug-hooks) 或指令碼本身所做的更改來確認它執行。

789

790`hooks/hooks.json` 和 `hooks` manifest 鍵中的 Hooks 都會載入。如需每個事件及其承載，請參閱 [Hook 事件](/docs/zh-TW/hooks#hook-events)。

791

792<h4 id="when-plugin-hooks-fire">

793 外掛程式 hooks 何時觸發

794</h4>

795

796外掛程式的 hooks 不會等待使用外掛程式的 skills 或命令之一。Claude Code 在工作階段載入外掛程式時註冊它們，從那時起它們在其事件上觸發。若要限制 hook 執行的時間，縮小其 `matcher`。

797

798如果 hook 從不觸發，請參閱 [不觸發的 hooks](/docs/zh-TW/plugins/troubleshooting#failed-to-load-hooks-from-and-hooks-that-dont-fire)。

799

800<h4 id="environment-quoting-and-matching-mcp-tools">

801 環境、引號和匹配 MCP 工具

802</h4>

803

804hook 的環境、`${CLAUDE_PLUGIN_ROOT}` 的引號和外掛程式自己的 MCP 工具的匹配器工作如下：

805

806* **環境**：每個 hook 程序在其環境中接收 `CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA`，加上每個 [使用者設定](#user-configuration) 值的 `CLAUDE_PLUGIN_OPTION_<KEY>`，因此您的指令碼可以從那裡讀取它們

807* **引號**：當 `command` 沒有 `args` 時，它通過 shell 執行，因此將 `${CLAUDE_PLUGIN_ROOT}` 路徑包裝在雙引號中，如 [Hooks](#hooks) 下的 `hooks/hooks.json` 範例所做，以保持展開的路徑為一個 shell 單詞。當您改為傳遞 `args` 時，每個元素作為一個引數傳遞，沒有 shell，不需要引號。請參閱 [exec 形式和 shell 形式](/docs/zh-TW/hooks#exec-form-and-shell-form)

808* **匹配外掛程式自己的 MCP 工具**：來自此外掛程式宣告的 [MCP 伺服器](#mcp-servers) 的工具命名為 `mcp__plugin_<plugin>_<server>__<tool>`，因此在匹配器中寫入該完整名稱。僅在伺服器名稱上的匹配器從不觸發。請參閱 [匹配 MCP 工具](/docs/zh-TW/hooks#match-mcp-tools)

809

810<h3 id="mcp-servers">

811 MCP 伺服器

812</h3>

813

814MCP 伺服器從外部系統為 Claude 提供工具。在外掛程式根目錄的 `.mcp.json` 中宣告它，形狀與 [專案 `.mcp.json`](/docs/zh-TW/mcp#project-scope) 相同。此 `.mcp.json` 宣告一個命名為 `db` 的伺服器：

815

816```json .mcp.json theme={null}

817{

818 "mcpServers": {

819 "db": {

820 "command": "node",

821 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]

822 }

823 }

824}

825```

826

827您也可以省略 `mcpServers` 包裝器，將 `db` 放在檔案的頂層。

828

829載入外掛程式並執行 `/mcp` 以確認伺服器顯示為 `plugin:my-plugin:db`。

830

831`claude plugin validate` 檢查 `.mcp.json` 並報告 Claude Code 在載入時會丟棄的伺服器項目作為錯誤。需要 Claude Code v2.1.281 或更新版本。

832

833如需壞項目在載入時顯示的位置，請參閱 [不啟動的 MCP 伺服器](/docs/zh-TW/plugins/troubleshooting#invalid-mcp-server-config-for-and-mcp-servers-that-dont-start)。

834

835`mcpServers` manifest 鍵採用內嵌伺服器對應、JSON 檔案的路徑或這些的陣列。當 manifest 伺服器與 `.mcp.json` 中的伺服器同名時，manifest 伺服器取代它。

836

837<h4 id="reach-users-on-claude-ai-and-cowork">

838 到達 claude.ai 和 Cowork 上的使用者

839</h4>

840

841本機 stdio 伺服器（例如 [MCP 伺服器](#mcp-servers) 下的 `db` 伺服器）在 Claude Code 和在 Claude Desktop 應用程式中在您的機器上執行的 Cowork 工作階段中執行，但不在 claude.ai 上。若要到達那裡的使用者，請透過其 `https://` URL 參考遠端伺服器，claude.ai 和 Cowork 將其作為連接器提供給使用者。

842

843<h4 id="server-names-tool-names-and-reloads">

844 伺服器名稱、工具名稱和重新載入

845</h4>

846

847伺服器的名稱、變數替換和重新載入行為遵循這些規則：

848

849* **伺服器名稱**：`plugin:<plugin>:<server>`，所以 `my-plugin` 中的 `db` 伺服器在 `/mcp` 中是 `plugin:my-plugin:db`。使用相同的形式在 [`mcp_tool` hook](/docs/zh-TW/hooks#mcp-tool-hook-fields) 中命名伺服器

850* **工具名稱**：`mcp__plugin_<plugin>_<server>__<tool>`，所以該 `db` 伺服器上的 `query` 工具是 `mcp__plugin_my-plugin_db__query`。這是在 [權限規則](/docs/zh-TW/permissions) 和 [hook 匹配器](#hooks) 中使用的名稱

851* **替換**：`${CLAUDE_PLUGIN_ROOT}` 和其他 [路徑變數](#path-variables-and-persistent-data) 在 `command`、`args` 和 `env` 中被替換。`args` 中不需要引號，因為每個元素作為一個引數傳遞

852* **重新載入**：當使用者執行 `/reload-plugins` 且 [重新載入適用](/docs/zh-TW/plugins/cli-reference#reloads-that-change-mcp-tools) 時，配置未變更的伺服器保持其連接。配置已變更的伺服器重新連接，您移除的伺服器斷開連接

853

854<h4 id="include-a-packaged-mcpb-server">

855 包含打包的 MCPB 伺服器

856</h4>

857

858`mcpServers` 鍵也接受打包的伺服器作為 [MCPB 檔案](https://github.com/modelcontextprotocol/mcpb)，其副檔名為 `.mcpb` 或較舊的 `.dxt`。將鍵指向檔案，作為外掛程式內的路徑或 `https://` URL：

859

860```json .claude-plugin/plugin.json theme={null}

861{

862 "name": "my-plugin",

863 "mcpServers": "./servers/db.mcpb"

864}

865```

866

867伺服器從捆綁的 manifest 中的 `name` 獲取其名稱。

868

869如需傳輸和驗證，請參閱 [MCP](/docs/zh-TW/mcp#plugin-provided-mcp-servers)。

870

871<h3 id="lsp-servers">

872 LSP 伺服器

873</h3>

874

875LSP 伺服器為 Claude 提供語言的診斷和程式碼導航。如果 [官方程式碼智慧外掛程式](/docs/zh-TW/plugins/code-intelligence) 已涵蓋您的語言，請安裝該外掛程式而不是寫一個。否則在外掛程式根目錄的 `.lsp.json` 中宣告伺服器：

876

877```json .lsp.json theme={null}

878{

879 "gopls": {

880 "command": "gopls",

881 "args": ["serve"],

882 "extensionToLanguage": {

883 ".go": "go"

884 }

885 }

886}

887```

888

889檔案直接將每個伺服器名稱對應到其配置，在對應周圍沒有包裝物件。`command` 是二進位檔的名稱，其引數在 `args` 中。`extensionToLanguage` 需要至少一個副檔名，每個以 `.` 開頭。

890

891`claude plugin validate` 不讀取此檔案。當任何項目無效時，整個檔案在載入時被跳過，`Invalid LSP server config for ".lsp.json"` 出現在 `/plugin` **Errors** 標籤中。

892

893您的外掛程式配置連接但不安裝伺服器二進位檔，每個檔案副檔名獲得一個伺服器：

894

895* **缺少二進位檔**：Claude Code 從使用者的 `PATH` 按名稱啟動 `command`。當二進位檔不存在時，伺服器無法啟動，`claude --debug` 記錄 `LSP server <name> failed to start`

896* **副檔名衝突**：當兩個啟用的伺服器聲稱相同的副檔名時，首先註冊的處理這些檔案，另一個不用於它們，無論伺服器來自一個外掛程式還是兩個。`/plugin` **Errors** 標籤顯示警告 `LSP server "<name>" is not used for <ext> files`

897

898`lspServers` manifest 鍵採用相同的對應內嵌、JSON 檔案的路徑或這些的陣列，其伺服器新增至 `.lsp.json` 中的伺服器。當 manifest 伺服器與 `.lsp.json` 中的伺服器同名時，manifest 伺服器取代它。

899

900如需 `transport`、逾時、重新啟動和其他欄位，請參閱 [`lspServers`](/docs/zh-TW/plugins/manifest-reference#lspservers)。

901

902將日誌輸出傳送至 stderr，而不是 stdout。Claude Code 僅將伺服器的 stdout 讀取為協議訊息，並接受最多 64 KiB 的訊息標頭和最多 32 MiB 的訊息正文。

903

904Claude Code 斷開超過任一限制或將非協議輸出寫入 stdout 的伺服器，並將斷開連接計為 `restartOnCrash` 和 `maxRestarts` 的當機。當您使用 `--debug` 執行時，Claude Code 將命名原因的錯誤寫入偵錯日誌。

905

906<h3 id="executables">

907 可執行檔

908</h3>

909

910外掛程式根目錄的 `bin/` 中的檔案在啟用外掛程式時位於 Bash 工具的 shell 的 `PATH` 上，因此 Claude 可以將它們作為裸命令執行。新增可執行指令碼：

911

912```bash bin/hello-plugin theme={null}

913#!/bin/bash

914echo "hello from my-plugin"

915```

916

917使用 `chmod +x bin/hello-plugin` 使其可執行並載入外掛程式。當您要求 Claude 執行 `hello-plugin` 時，Bash 工具結果顯示指令碼的輸出。

918

919外掛程式 `bin/` 目錄位於使用者自己的 `PATH` 項目之後，因此外掛程式無法遮蔽 `git`、`ls` 或其他系統命令。

920

921claude.ai 和 Cowork 不安裝具有頂層 `bin/` 目錄的外掛程式，包括您 [透過 claude.ai 組織設定分發](/docs/zh-TW/plugins/host-marketplace#distribute-through-organization-settings) 的外掛程式。

922

923<h3 id="default-settings">

924 預設設定

925</h3>

926

927若要設定在啟用外掛程式時適用的預設值，在外掛程式根目錄新增 `settings.json`，或將相同的物件內嵌放在 `settings` manifest 鍵中。兩個鍵生效，`agent` 和 `subagentStatusLine`，所有其他鍵都被丟棄。

928

929設定 `agent` 以執行外掛程式自己的一個 agents 作為主執行緒：

930

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

932{

933 "agent": "security-reviewer"

934}

935```

936

937載入外掛程式並啟動工作階段。Claude 然後使用 `security-reviewer` agent 的系統提示和模型在主對話中回答。

938

939如需鍵控制的所有內容，請參閱 [`agent` 設定](/docs/zh-TW/settings-reference#agent)。

940

941當相同的鍵在多個位置設定時，這些規則決定哪個值適用：

942

943* **檔案優於 manifest**：當兩者都存在且 `settings.json` 設定至少一個支援的鍵時，`settings.json` 適用，manifest 的 `settings` 被忽略

944* **使用者設定優於外掛程式預設值**：在設定來源中，外掛程式預設值是最低層，因此使用者自己在 `~/.claude/settings.json` 中的 `agent` 覆蓋您的

945* **兩個外掛程式設定相同的鍵**：來自最後載入的外掛程式的值適用，`claude --debug` 記錄 `overrides setting`

946

947如需 `subagentStatusLine` 形狀，請參閱 [子代理狀態行](/docs/zh-TW/statusline#subagent-status-lines)。

948

949<h3 id="themes-and-output-styles">

950 主題和輸出樣式

951</h3>

952

953外掛程式可以包含色彩主題和輸出樣式。兩者都出現在與使用者自己相同的選擇器中。對於任一個，設定 manifest 鍵取代資料夾掃描。

954

955| 元件 | 儲存為 | 格式 | 出現在 | Manifest 鍵 |

956| :--- | :------------------------ | :--------------------------------------------------------------------------------------------------- | :----------------------------------- | :-------------------- |

959

960外掛程式主題是唯讀的，因此當使用者在 `/theme` 中編輯一個時，編輯會儲存為其自己的主題目錄中的副本。

961

962此主題在深色預設上重新著色提示符號重點和錯誤文字：

963

964```json themes/dracula.json theme={null}

965{

966 "name": "Dracula",

967 "base": "dark",

968 "overrides": {

969 "claude": "#bd93f9",

970 "error": "#ff5555"

971 }

972}

973```

974

975<h3 id="channels">

976 頻道

977</h3>

978

979[頻道](/docs/zh-TW/channels) 讓外部系統（例如聊天應用程式）將訊息傳送到工作階段。在外掛程式中，頻道是 MCP 伺服器之一加上 `channels` 項目，該項目綁定到它並可以提示其自己的配置。此 manifest 將頻道綁定到 `telegram` 伺服器並要求機器人令牌：

980

981```json .claude-plugin/plugin.json theme={null}

982{

983 "name": "my-plugin",

984 "mcpServers": {

985 "telegram": {

986 "command": "node",

987 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],

988 "env": { "BOT_TOKEN": "${user_config.bot_token}" }

989 }

990 },

991 "channels": [

992 {

993 "server": "telegram",

994 "userConfig": {

995 "bot_token": {

996 "type": "string",

997 "title": "Bot token",

998 "description": "Telegram bot token",

999 "sensitive": true

1000 }

1001 }

1002 }

1003 ]

1004}

1005```

1006

1007`server` 必須符合 `mcpServers` 中的鍵。每個頻道的 `userConfig` 採用與 [頂層 `userConfig` 鍵](#user-configuration) 相同的形狀。

1008

1009如需伺服器必須實現的內容以及使用者如何啟用頻道外掛程式，請參閱頻道參考中的 [打包為外掛程式](/docs/zh-TW/channels-reference#package-as-a-plugin)。如需欄位表，請參閱 [`channels`](/docs/zh-TW/plugins/manifest-reference#channels)。

1010

1011<h3 id="monitors">

1012 監視器

1013</h3>

1014

1015監視器是在整個工作階段的背景中執行的 shell 命令。它列印的內容作為通知到達 Claude，因此 Claude 可以對日誌或狀態變更做出反應，而無需被要求監視它。將項目儲存在 `monitors/monitors.json` 中：

1016

1017```json monitors/monitors.json theme={null}

1018[

1019 {

1020 "name": "error-log",

1021 "command": "tail -F ./logs/error.log",

1022 "description": "Application error log"

1023 }

1024]

1025```

1026

1027命令在 shell 中執行，在工作階段啟動的工作目錄中。

1028

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

1030

1031* **僅互動式工作階段**：外掛程式監視器在互動式工作階段中啟動，從不在使用 `-p` 旗標的非互動式模式中。它們也只在 [Monitor 工具](/docs/zh-TW/tools-reference#monitor-tool) 可用的地方啟動

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

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

1034

1035`experimental.monitors` manifest 鍵採用相同的陣列內嵌或 JSON 檔案的路徑，並代替 `monitors/monitors.json` 讀取。

1036

1037如需 `when` 觸發器和其他欄位，請參閱 [`monitors`](/docs/zh-TW/plugins/manifest-reference#monitors)。

1038

1039<h2 id="user-configuration">

1040 要求使用者提供設定值

1041</h2>

1042

1043在 `userConfig` manifest 鍵中宣告您的外掛程式需要的使用者值，以便使用者不會自行編輯 `settings.json`。每個選項在對話方塊中顯示，其 `title` 作為標籤，其 `description` 在下方。

1044

1045為令牌或密碼設定 `"sensitive": true`。對話方塊然後遮蔽輸入，值儲存在安全儲存中，而不是 `settings.json`。

1046

1047此 manifest 要求端點和令牌：

1048

1049```json .claude-plugin/plugin.json theme={null}

1050{

1051 "name": "my-plugin",

1052 "userConfig": {

1053 "api_url": {

1054 "type": "string",

1055 "title": "API URL",

1056 "description": "Base URL of your team's API"

1057 },

1058 "api_token": {

1059 "type": "string",

1060 "title": "API token",

1061 "description": "Token for your team's API",

1062 "sensitive": true

1063 }

1064 }

1065}

1066```

1067

1068<h3 id="when-the-configuration-dialog-appears">

1069 設定對話方塊何時出現

1070</h3>

1071

1072對話方塊僅在互動式 `/plugin` 介面中出現。當使用者執行以下任何操作時，它會為任何尚未設定的選項開啟：

1073

1074* 在 `/plugin` 中安裝外掛程式

1075* 在工作階段內執行 `/plugin install <plugin>@<marketplace>`

1076* 從 `/plugin` 中的 **Installed** 標籤啟用外掛程式

1077

1078若要在任何時間開啟相同的對話方塊，使用者執行 `/plugin configure <plugin>@<marketplace>`。

1079

1080`claude plugin install` shell 命令從不提示 `userConfig` 值。若要從 shell 設定值，將每個值作為 `--config KEY=VALUE` 傳遞。當選項保持未設定時，命令列印 `userConfig options not yet set` 行，命名兩種設定方式。[`userConfig` 對話方塊從不出現](/docs/zh-TW/plugins/troubleshooting#the-userconfig-dialog-never-appears) 引用該行。

1081

1082如需選項欄位、每個值儲存的位置、元件如何參考已儲存的值以及哪些欄位拒絕 `${user_config.*}`，請參閱 [使用者設定](/docs/zh-TW/plugins/manifest-reference#user-configuration)。

1083

1084<h2 id="path-variables-and-persistent-data">

1085 參考外掛程式路徑和儲存資料

1086</h2>

1087

1088您不知道您的外掛程式將安裝在哪裡，因此透過這些變數而不是固定路徑參考其檔案和資料。它們在 skill、命令和 agent 內容、hook 和監視器命令以及 MCP 和 LSP 伺服器配置中被替換。它們也被匯出到 hook、MCP 和 LSP 程序：

1089

1090* **`${CLAUDE_PLUGIN_ROOT}`**：外掛程式的安裝目錄。每個版本都有自己的 [快取目錄](/docs/zh-TW/plugins/loading#find-plugins-on-disk)，因此當外掛程式更新時路徑會變更。不要在那裡寫入狀態

1091* **`${CLAUDE_PLUGIN_DATA}`**：一個在更新中倖存的目錄，用於 `node_modules`、虛擬環境和快取。它解析為 `~/.claude/plugins/data/<id>/`，並在首次參考時建立

1092* **`${CLAUDE_PROJECT_DIR}`**：專案根目錄，hooks 接收的相同值

1093

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

1095

1096在 Windows 上，替換的路徑使用正斜杠，因此 shell 不會將反斜杠讀取為逸出。

1097

1098<h3 id="install-dependencies-into-the-data-directory">

1099 將相依性安裝到資料目錄

1100</h3>

1101

1102對於市場安裝的外掛程式，Claude Code 在快取外掛程式時自動安裝符合條件的 [Node.js 套件相依性](/docs/zh-TW/plugins/loading#node-js-package-dependencies)，因此您可能不需要自行安裝它們。當您執行時，此 `SessionStart` hook 在首次執行時將 `node_modules` 安裝到 `${CLAUDE_PLUGIN_DATA}` 中，並在更新變更 `package.json` 後再次安裝：

1103

1104```json hooks/hooks.json theme={null}

1105{

1106 "hooks": {

1107 "SessionStart": [

1108 {

1109 "hooks": [

1110 {

1111 "type": "command",

1112 "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""

1113 }

1114 ]

1115 }

1116 ]

1117 }

1118}

1119```

1120

1121在第一個工作階段後，`~/.claude/plugins/data/<id>/node_modules` 存在。MCP 伺服器然後可以在其 `env` 中設定 `NODE_PATH` 為 `${CLAUDE_PLUGIN_DATA}/node_modules`。如需哪些欄位替換哪個變數，請參閱 [環境變數](/docs/zh-TW/plugins/manifest-reference#environment-variables)。

1122

1123<h2 id="next-steps">

1124 後續步驟

1125</h2>

1126

1127* [外掛程式 manifest 參考](/docs/zh-TW/plugins/manifest-reference)：`plugin.json` 欄位、路徑規則和標準配置

1128* [使用 evals 測試外掛程式](/docs/zh-TW/plugin-evals)：檢查您新增的元件以您的意圖改變 Claude 的行為

1129* [發佈和分發外掛程式](/docs/zh-TW/plugins/publish)：版本化外掛程式並將其放在市場中

1130* [疑難排解外掛程式](/docs/zh-TW/plugins/troubleshooting)：當元件無法載入或 hook 無法觸發時該怎麼辦

plugins/create.md +424 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 建立 Claude Code 外掛程式

7> 從空目錄建立您的第一個 Claude Code 外掛程式，在沒有市集的情況下測試它，並轉換現有的 .claude/ 設定。

9外掛程式是一個包含技能、代理、hooks 和 MCP 伺服器的目錄，加上一個稱為清單的 `plugin.json` 檔案，用來命名外掛程式。Claude Code 將該目錄作為一個單位載入，因此您可以與隊友分享、在多個專案中安裝，或將其發佈到市集。

11本頁面適用於編寫自己外掛程式的人員。

13<Note>

14 其他頁面涵蓋了這些情況：

16 * **安裝他人的外掛程式**：請參閱[安裝外掛程式](/docs/zh-TW/plugins/install)

17 * **不確定您是否需要外掛程式**：請參閱概述中的[決定是否需要外掛程式](/docs/zh-TW/plugins/overview#decide-whether-you-need-a-plugin)

18 * **您的外掛程式使用者在 claude.ai 或 Cowork 上**：同一個資料夾會以不同的元件子集安裝在那裡。請參閱[claude.ai 和 Cowork 上的外掛程式](https://claude.com/docs/plugins/overview)

19</Note>

21從與您已有的內容相符的部分開始：

23* **還沒有任何東西**：遵循[建立您的第一個外掛程式](#create-your-first-plugin)，然後[在沒有市集的情況下開發](#develop-without-a-marketplace)和[測試和偵錯](#test-and-debug)。

24* **已在 `.claude/` 下有檔案**：執行一次第一個外掛程式的逐步解說以了解佈局，然後遵循[轉換現有的 `.claude/` 設定](#convert-an-existing-claude-setup)。

26<h2 id="decide-when-to-use-a-plugin">

27 決定何時使用外掛程式

28</h2>

30技能、代理、hooks 和 MCP 伺服器都可以在您的專案或主目錄中獨立運作。當它只為一個專案或只為您服務時，保持該獨立設定。當您想與隊友分享設定、在多個專案中安裝，或發佈版本化版本時，請建立外掛程式。

32當您將獨立技能、代理、hooks 和 MCP 設定移到外掛程式中時，它們的位置和名稱會改變：

34* **檔案的位置**：在外掛程式自己的目錄（稱為外掛程式根目錄）下，作為 `skills/`、`agents/`、`hooks/hooks.json` 和 `.mcp.json`。

35* **它們的命名方式**：外掛程式技能和代理會取得外掛程式名稱作為前綴，例如 `/my-plugin:hello`，因此兩個外掛程式可以各自提供一個 `hello` 技能而不會衝突。

37若要將現有設定移到外掛程式中，請參閱[轉換現有的 `.claude/` 設定](#convert-an-existing-claude-setup)。

39<h2 id="create-your-first-plugin">

40 建立您的第一個外掛程式

41</h2>

43在此逐步解說中，您建立一個外掛程式，其唯一元件是一個技能（問候），並使用 `--plugin-dir` 執行它，該選項會為一個工作階段載入外掛程式而不安裝它。外掛程式可以包含任何[元件](/docs/zh-TW/plugins/components)的組合，例如技能、代理、hooks 和 MCP 伺服器，且不需要任何一個；一個技能是展示佈局的最小範例。

45您需要 Claude Code [已安裝並登入](/docs/zh-TW/quickstart#step-1-install-claude-code)。

47在您想保留外掛程式的目錄（例如 `~/projects`）中開啟終端機，並從該目錄執行這些步驟中的命令。您可以將外掛程式保留在任何地方，因為當您啟動工作階段時，您會將其路徑傳遞給 Claude Code。

49<Steps>

50 <Step title="建立外掛程式目錄">

51 建立外掛程式目錄，其中包含一個 `.claude-plugin/` 資料夾來保存清單：

53 ```bash theme={null}

54 mkdir -p my-first-plugin/.claude-plugin

55 ```

56 </Step>

58 <Step title="編寫清單">

59 [清單](/docs/zh-TW/plugins/manifest-reference)是一個名為 `plugin.json` 的 JSON 檔案，它告訴 Claude Code 外掛程式的名稱並描述它。將此檔案儲存為 `my-first-plugin/.claude-plugin/plugin.json`：

61 ```json my-first-plugin/.claude-plugin/plugin.json theme={null}

62 {

63 "name": "my-first-plugin",

64 "description": "A greeting plugin to learn the basics",

65 "version": "1.0.0",

66 "author": {

67 "name": "Your Name"

68 }

69 }

70 ```

72 這四個欄位的作用如下：

74 * **`name`**：必需。它識別外掛程式並成為外掛程式提供的每個技能和代理的前綴。不要在其中放置空格。

75 * **`description`**：使用者在 `/plugin` 中看到的外掛程式文字。

76 * **`version`**：選用。設定它會讓使用者保持在該版本，直到您更改它；[發佈新版本](/docs/zh-TW/plugins/host-marketplace#release-a-new-version)說明何時設定或省略它。

77 * **`author`**：要歸功於誰。其中的 `name` 是必需的；`email` 和 `url` 是選用的。

79 每個其他欄位都在[清單參考](/docs/zh-TW/plugins/manifest-reference#fields)上。

81 只有 `plugin.json` 放在 `.claude-plugin/` 內。您接下來添加的技能直接放在 `my-first-plugin/` 下，在該資料夾旁邊。

82 </Step>

84 <Step title="添加技能">

85 此外掛程式的一個元件是一個技能。每個技能是 `skills/` 下的一個目錄，包含一個 `SKILL.md` 檔案。建立技能的目錄：

87 ```bash theme={null}

88 mkdir -p my-first-plugin/skills/hello

89 ```

91 然後使用此內容建立 `my-first-plugin/skills/hello/SKILL.md`：

93 ```markdown my-first-plugin/skills/hello/SKILL.md theme={null}

94 ---

95 name: hello

96 description: Greet the user with a friendly message

97 disable-model-invocation: true

98 ---

100 Greet the user warmly and ask how you can help them today.

101 ```

102

103 `disable-model-invocation: true` 行表示 Claude 不會自行執行技能，因此只有您觸發它。從您希望 Claude 自行執行的技能中移除該行。技能的命令結合外掛程式名稱和技能的名稱，因此您將此技能執行為 `/my-first-plugin:hello`。對於其他 frontmatter 欄位，請參閱[技能 frontmatter 參考](/docs/zh-TW/skills#frontmatter-reference)。

104 </Step>

105

106 <Step title="驗證外掛程式">

107 在執行任何操作之前檢查清單和技能的 frontmatter：

108

109 ```bash theme={null}

110 claude plugin validate ./my-first-plugin

111 ```

112

113 該命令列印它檢查的清單路徑和 `✔ Validation passed`。如果它改為列印 `✘ Validation failed`，則該結果行上方的每一行都命名要修復的欄位。在[`claude plugin validate` 報告錯誤](/docs/zh-TW/plugins/troubleshooting#claude-plugin-validate-reports-errors)下查找每條訊息。

114 </Step>

115

116 <Step title="使用外掛程式執行 Claude Code">

117 啟動已載入外掛程式的工作階段：

118

119 ```bash theme={null}

120 claude --plugin-dir ./my-first-plugin

121 ```

122

123 Claude Code 啟動後，執行技能：

124

125 ```text theme={null}

126 /my-first-plugin:hello

127 ```

128

129 Claude 會回覆一個問候。

130 </Step>

131</Steps>

132

133外掛程式只在您使用 `--plugin-dir` 啟動的工作階段中載入。若要在沒有該旗標的情況下繼續處理它，或測試 `.zip` 組建，請參閱[在沒有市集的情況下開發](#develop-without-a-marketplace)。

134

135<h3 id="share-the-plugin">

136 分享您的外掛程式

137</h3>

138

139使用[建立您的第一個外掛程式](#create-your-first-plugin)建立的外掛程式只存在於您的機器上。當它準備好供其他人使用時，有三種方式可以將其提供給他們：

140

141* **直接將其發送給少數人**：給他們外掛程式的目錄或其 `.zip`，無需發佈任何內容。請參閱[在沒有市集的情況下分享外掛程式](/docs/zh-TW/plugins/publish#share-a-plugin-without-a-marketplace)。

142* **在您自己的市集中列出它**：隊友添加您的市集一次並按名稱安裝外掛程式，他們會收到您的更新。請參閱[透過您自己的市集發佈](/docs/zh-TW/plugins/publish#publish-through-your-own-marketplace)。

143* **將其提交到 Anthropic 的社群市集**：列出後，任何添加該市集的人都可以安裝它。請參閱[提交到社群市集](/docs/zh-TW/plugins/publish#submit-to-the-community-marketplace)。

144

145<h3 id="plugin-layout">

146 外掛程式佈局

147</h3>

148

149每種[元件](/docs/zh-TW/plugins/components)（例如技能、代理、hooks 和 MCP 伺服器）都放在外掛程式根目錄下的固定目錄中，外掛程式根目錄是您傳遞給 `--plugin-dir` 的目錄。只添加您使用的目錄。若要點擊完整的外掛程式目錄並閱讀每個檔案的作用，請開啟[外掛程式瀏覽器](/docs/zh-TW/plugins/components#explore-the-plugin-directory)。

150

151該表列出了大多數外掛程式開始使用的目錄，[完整佈局](/docs/zh-TW/plugins/manifest-reference#standard-layout)列出了其餘的。

152

153| 位置 | 內容 |

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

155| `.claude-plugin/plugin.json` | 清單。當您使用 `--plugin-dir` 載入外掛程式且它沒有清單時，Claude Code 會以其目錄命名外掛程式 |

156| `skills/` | 每個技能一個 `<name>/SKILL.md` 目錄 |

157| `commands/` | 平面 Markdown 檔案，技能的較舊形式。對於新外掛程式，請使用 `skills/` |

158| `agents/` | 每個子代理一個 Markdown 檔案 |

159| `hooks/hooks.json` | Hook 設定：一個頂級 `"hooks"` 鍵，其值的形狀與設定檔案中的 `hooks` 相同 |

160| `.mcp.json` | MCP 伺服器定義 |

161

162<Warning>

163 只有 `plugin.json` 放在 `.claude-plugin/` 內。保存在那裡的元件不會載入。

164

165 外掛程式根目錄是外掛程式自己的目錄，不是 `~/.claude/` 本身。保存在 `~/.claude/.mcp.json` 的 `.mcp.json` 不會載入。

166</Warning>

167

168<h2 id="develop-without-a-marketplace">

169 在沒有市集的情況下開發

170</h2>

171

172您不需要[市集](/docs/zh-TW/plugins/overview#get-plugins-from-a-marketplace)來執行您正在編寫的外掛程式。改為直接從磁碟或 URL 載入它：

173

174* [`--plugin-dir`](#load-a-directory-or-archive-for-one-session)：為一個工作階段載入目錄或 `.zip` 存檔。

175* [`--plugin-url`](#fetch-an-archive-from-a-url-for-one-session)：為一個工作階段從 URL 擷取 `.zip` 存檔。

176* [`claude plugin init`](#scaffold-a-plugin-that-loads-every-session)：在 `~/.claude/skills/` 下搭建外掛程式，在每個工作階段中載入。

177

178如果以不同方式載入的兩個外掛程式共享一個名稱，請參閱[名稱衝突](/docs/zh-TW/plugins/loading#name-conflicts)以了解 Claude Code 保留哪一個。

179

180<h3 id="load-a-directory-or-archive-for-one-session">

181 為一個工作階段載入外掛程式

182</h3>

183

184您可以通過三種方式為單個工作階段載入外掛程式：使用 `--plugin-dir` 從磁碟上的目錄或 `.zip` 存檔，使用 `--plugin-url` 從 URL，或從環境變數（當您無法添加旗標時）。每個外掛程式只為該工作階段載入，沒有任何內容寫入您的設定。當您在工作階段期間編輯外掛程式的檔案時，執行 `/reload-plugins` 以載入變更。

185

186<h4 id="from-a-directory-or-zip">

187 從目錄或 `.zip`

188</h4>

189

190當您從 shell 啟動 `claude` 時，使用外掛程式的根目錄或其 `.zip` 存檔傳遞 `--plugin-dir`。重複該旗標以載入多個外掛程式：

191

192```bash theme={null}

193claude --plugin-dir ./my-first-plugin --plugin-dir ./other-plugin.zip

194```

195

196<h4 id="load-a-folder-of-plugins">

197 從外掛程式資料夾

198</h4>

199

200若要從一個地方載入多個外掛程式，請傳遞一個保存它們的資料夾，例如 `--plugin-dir ./plugins`。載入外掛程式資料夾需要 Claude Code v2.1.265 或更新版本。

201

202如果資料夾沒有 `.claude-plugin/` 目錄且其頂級沒有外掛程式元件，Claude Code 會將其視為外掛程式資料夾。然後，每個具有 `.claude-plugin/plugin.json` 清單的直接子資料夾都會作為單獨的外掛程式載入。資料夾中的所有其他內容都會被跳過而不出現錯誤，包括沒有清單的子資料夾。如果資料夾中的外掛程式無法載入，請檢查其子資料夾是否具有 `.claude-plugin/plugin.json`。

203

204在互動式工作階段中，您也可以在啟動後在資料夾中添加和移除外掛程式：

205

206* 您添加的子資料夾在其清單存在後會作為新外掛程式載入。

207* 當您移除子資料夾時，其外掛程式會卸載。

208

209對於這些變更中的每一個，工作階段中都會出現一條訊息。如果在對話中途載入或卸載外掛程式會[使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，則該變更會被保留，訊息會告訴您執行 `/reload-plugins` 以應用它。

210

211<h4 id="fetch-an-archive-from-a-url-for-one-session">

212 從 URL

213</h4>

214

215當您從 shell 啟動 `claude` 時，使用 `.zip` 存檔的位址傳遞 `--plugin-url`，例如您的 CI 發佈的組建成品：

216

217```bash theme={null}

218claude --plugin-url https://example.com/my-first-plugin.zip

219```

220

221Claude Code 在啟動時下載存檔。若要載入多個，請重複該旗標或在一個引用的引數中傳遞以空格分隔的 URL。

222

223只在您控制或信任的存檔上指向該旗標。

224

225如果 Claude Code 無法擷取存檔或存檔無效，它會在沒有外掛程式的情況下啟動，並記錄一個外掛程式載入錯誤，您可以在 `/plugin` 管理器的**錯誤**標籤中查看。

226

227<h4 id="from-an-environment-variable">

228 從環境變數

229</h4>

230

231若要在無法添加 `--plugin-dir` 旗標的工作階段中載入外掛程式，請改為在 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-TW/env-vars#variables) 環境變數中列出它們的絕對路徑。Claude Code 會像載入 `--plugin-dir` 路徑一樣載入每個路徑。這些外掛程式會添加到您使用 `--plugin-dir` 傳遞的任何外掛程式中。[專案和本機設定無法設定此變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)。`CLAUDE_CODE_PLUGIN_DIRS` 需要 Claude Code v2.1.280 或更新版本。

232

233受管設定可以關閉 `--plugin-dir` 和 `CLAUDE_CODE_PLUGIN_DIRS`。請參閱[為一個工作階段載入外掛程式的旗標](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session)。若要一起測試外掛程式及其依賴的外掛程式，請參閱[在本機測試外掛程式及其依賴](/docs/zh-TW/plugins/dependencies#test-a-plugin-and-its-dependency-locally)。

234

235<h3 id="scaffold-a-plugin-that-loads-every-session">

236 讓外掛程式在每個工作階段中載入

237</h3>

238

239您的個人技能目錄是 `~/.claude/skills/`。Claude Code 會將那裡包含 `.claude-plugin/plugin.json` 的任何資料夾作為外掛程式在每個工作階段中載入，無需旗標和無需安裝步驟。`claude plugin init` 為您搭建其中一個外掛程式。

240

241<h4 id="scaffold-the-plugin-with-claude-plugin-init">

242 使用 `claude plugin init` 搭建外掛程式

243</h4>

244

245`claude plugin init` 在 `~/.claude/skills/` 下寫入一個啟動外掛程式。需要 Claude Code v2.1.157 或更新版本。從您的 shell 搭建一個：

246

247```bash theme={null}

248claude plugin init my-tool

249```

250

251該命令在 `~/.claude/skills/my-tool/` 下建立一個 `.claude-plugin/plugin.json` 和一個根 `SKILL.md`。它列印 `✔ Created plugin "my-tool" at ~/.claude/skills/my-tool` 後跟 `It will auto-load next session as my-tool@skills-dir. Run /reload-plugins to load it now.`

252

253傳遞 `--with skills` 以讓 `claude plugin init` 為您在 `skills/` 下搭建一個技能。其他 `--with` 值在[外掛程式命令參考](/docs/zh-TW/plugins/cli-reference#plugin-init)上。

254

255<h4 id="skill-names-in-a-scaffolded-plugin">

256 在搭建的外掛程式中命名技能

257</h4>

258

259`~/.claude/skills/my-tool/SKILL.md` 的根技能也是個人技能，因此您將其作為 `/my-tool` 而不是 `/my-tool:my-tool` 呼叫。您在外掛程式內的 `skills/` 下添加的技能會取得外掛程式名稱前綴，例如 `/my-tool:example`。

260

261<h4 id="stop-loading-the-plugin">

262 停止載入外掛程式

263</h4>

264

265若要停止載入搭建的外掛程式，請刪除其目錄，或在 shell 中使用 `claude plugin init` 列印的 `my-tool@skills-dir` 名稱執行 `claude plugin disable my-tool@skills-dir`。在 ID `my-tool@skills-dir` 中，`skills-dir` 代替市集名稱，因為外掛程式從您的技能目錄而不是市集載入。

266

267<h4 id="load-a-plugin-for-everyone-in-one-repository">

268 透過存放庫分享外掛程式

269</h4>

270

271`claude plugin init` 將外掛程式寫入您的個人技能目錄 `~/.claude/skills/`，因此它在每個專案中為您載入。若要讓外掛程式為一個存放庫中的每個人載入，請在 `<project>/.claude/skills/<name>/` 自己建立相同的佈局，包括其 `.claude-plugin/plugin.json`。請參閱[透過存放庫分享的外掛程式](/docs/zh-TW/plugins/loading#plugins-shared-through-a-repository)以了解 Claude Code 在什麼條件下載入它。

272

273<h2 id="test-and-debug">

274 測試和偵錯

275</h2>

276

277當對外掛程式的變更沒有顯示時，按順序執行這些檢查。每一個都告訴您 Claude Code 對外掛程式做了什麼：

278

2791. 在您的 shell 中，執行 `claude plugin validate <path>`。它檢查清單和每個技能、代理和命令檔案的 frontmatter，並在 `Validation passed` 時退出 `0`。添加 `--strict` 以在警告時也失敗。退出代碼和目錄處理在[外掛程式命令參考](/docs/zh-TW/plugins/cli-reference#plugin-validate)上。

2802. 在執行中的工作階段中，執行 `/reload-plugins` 以應用您在磁碟上所做的編輯。它列印一個 `Reloaded:` 行，其中包含計數。然後通過輸入其 `/plugin-name:skill` 命令或在 `/plugin` **已安裝**標籤中找到外掛程式來確認技能已載入。

2813. 在同一工作階段中，執行 `/plugin`。**已安裝**標籤列出您的外掛程式，在外掛程式的詳細資訊中，Claude Code 找到的元件。**錯誤**標籤列出無法載入的內容及其原因，例如清單中不存在的路徑。

2824. 回到您的 shell，執行 `claude plugin list`。它在各自的部分中列印僅工作階段和技能目錄外掛程式，帶有 `Status: ✔ loaded` 或載入錯誤。若要包括您正在開發的外掛程式，請在 `plugin list` 之前使用其路徑傳遞 `--plugin-dir`。

283

284若要檢查 MCP 伺服器，請在工作階段中執行 `/mcp` 以查看伺服器的狀態。當伺服器健康時，`/mcp` 會將其列為已連接。如果不是，請參閱[不啟動的 MCP 伺服器](/docs/zh-TW/plugins/troubleshooting#invalid-mcp-server-config-for-and-mcp-servers-that-dont-start)。

285

286若要檢查 hook，請觸發它匹配的事件。例如，要求 Claude 編輯檔案以觸發 `PostToolUse` hook。然後閱讀[偵錯日誌](/docs/zh-TW/hooks#debug-hooks)，它顯示哪些 hooks 匹配、它們的退出代碼和它們的輸出。

287

288下一部分涵蓋您在開發時最可能遇到的失敗，[疑難排解頁面](/docs/zh-TW/plugins/troubleshooting#build-a-plugin)對每一個都有完整的條目。

289

290<h3 id="a-component-path-isn’t-found">

291 找不到元件路徑

292</h3>

293

294`/plugin` 的**錯誤**標籤顯示 `<component> path not found: <path>`，例如 `commands path not found`。清單中的元件路徑（例如 `commands`、`skills`、`agents` 或 `hooks`）指向不存在的內容。修復路徑或建立目錄，然後在工作階段中執行 `/reload-plugins`。請參閱[`commands path not found`](/docs/zh-TW/plugins/troubleshooting#commands-path-not-found)。

295

296<h3 id="plugin-dir-at-a-marketplace-root-doesn’t-load-the-plugins-under-plugins/">

297 `--plugin-dir` 在市集根目錄不載入 `plugins/` 下的外掛程式

298</h3>

299

300`--plugin-dir` 採用外掛程式的根目錄，即包含 `.claude-plugin/plugin.json` 和元件目錄（例如 `skills/`）的目錄。如果您改為指向市集根目錄，Claude Code 不會讀取 `marketplace.json`，因此 `plugins/` 下的外掛程式不會載入，您看不到錯誤。將旗標指向一個外掛程式的資料夾，或添加市集。請參閱[疑難排解條目](/docs/zh-TW/plugins/troubleshooting#plugin-dir-loads-a-plugin-with-no-components)。

301

302<h3 id="the-plugin-loads-but-its-skills-are-missing">

303 外掛程式載入但其技能遺失

304</h3>

305

306`skills/` 目錄在 `.claude-plugin/` 內，或清單中的 `skills` 條目指向一個檔案。將 `skills/` 移到外掛程式根目錄，將每個 `skills` 條目指向包含 `SKILL.md` 的目錄，並在工作階段中執行 `/reload-plugins`。請參閱[外掛程式載入但其技能遺失](/docs/zh-TW/plugins/troubleshooting#plugin-loads-but-its-skills-are-missing)。

307

308<h3 id="the-userconfig-dialog-never-appears">

309 `userConfig` 對話框從不出現

310</h3>

311

312您外掛程式的 [`userConfig`](/docs/zh-TW/plugins/components#user-configuration) 選項的對話框是在工作階段中透過 `/plugin` 安裝的一部分。使用 `--plugin-dir` 載入不會顯示它，`claude plugin install` 在 shell 中也不會。載入外掛程式後，在工作階段中執行 `/plugin configure <plugin-name>` 以開啟它。請參閱[`userConfig` 對話框從不出現](/docs/zh-TW/plugins/troubleshooting#the-userconfig-dialog-never-appears)。

313

314<h3 id="check-that-the-plugin-changes-claude’s-behavior">

315 檢查外掛程式是否改變 Claude 的行為

316</h3>

317

318無錯誤載入的外掛程式仍然可能無法按您的意圖引導 Claude。`claude plugin eval`（您在 shell 中執行）使用和不使用外掛程式執行您的測試案例並評分差異。請參閱[使用 evals 測試外掛程式](/docs/zh-TW/plugin-evals)，從[建立您的第一個 eval 套件](/docs/zh-TW/plugin-evals#create-your-first-eval-suite)開始。

319

320<h2 id="convert-an-existing-claude-setup">

321 轉換現有的 `.claude/` 設定

322</h2>

323

324如果您已在專案的 `.claude/` 目錄下有技能、代理或 hooks，您可以將它們移到外掛程式中而無需重寫它們。

325

326從專案根目錄（包含 `.claude/` 的目錄）執行這些步驟中的命令，因為 `cp` 路徑相對於它。

327

328<Steps>

329 <Step title="建立外掛程式結構">

330 在 `.claude/` 旁邊建立外掛程式目錄及其 `.claude-plugin/` 資料夾。您之後可以將外掛程式移到任何地方。

331

332 ```bash theme={null}

333 mkdir -p my-plugin/.claude-plugin

334 ```

335

336 建立 `my-plugin/.claude-plugin/plugin.json`：

337

338 ```json my-plugin/.claude-plugin/plugin.json theme={null}

339 {

340 "name": "my-plugin",

341 "description": "Migrated from standalone configuration",

342 "version": "1.0.0"

343 }

344 ```

345 </Step>

346

347 <Step title="複製您現有的檔案">

348 將您擁有的每個設定目錄複製到外掛程式根目錄，並跳過您沒有的任何目錄的命令。

349

350 ```bash theme={null}

351 cp -r .claude/commands my-plugin/

352 ```

353

354 ```bash theme={null}

355 cp -r .claude/agents my-plugin/

356 ```

357

358 ```bash theme={null}

359 cp -r .claude/skills my-plugin/

360 ```

361

362 執行 `ls -a my-plugin` 以確認您複製的每個目錄都出現在 `.claude-plugin` 旁邊。

363 </Step>

364

365 <Step title="移動您的 hooks">

366 如果您在 `.claude/settings.json` 或 `.claude/settings.local.json` 中有 hooks，請建立一個 hooks 目錄：

367

368 ```bash theme={null}

369 mkdir -p my-plugin/hooks

370 ```

371

372 建立 `my-plugin/hooks/hooks.json` 並將 `hooks` 物件從您的設定檔案複製到其中。格式相同。

373

374 此範例顯示帶有一個 hook 的形狀，該 hook 在 Claude 寫入或編輯每個檔案時執行 linter。用您自己的 `hooks` 物件替換範例。

375

376 ```json my-plugin/hooks/hooks.json theme={null}

377 {

378 "hooks": {

379 "PostToolUse": [

380 {

381 "matcher": "Write|Edit",

382 "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]

383 }

384 ]

385 }

386 }

387 ```

388 </Step>

389

390 <Step title="測試遷移的外掛程式">

391 為一個工作階段載入外掛程式：

392

393 ```bash theme={null}

394 claude --plugin-dir ./my-plugin

395 ```

396

397 在其新名稱下檢查每個元件：

398

399 * **技能**：為曾經是 `/deploy` 的技能執行 `/my-plugin:deploy`。

400 * **子代理**：要求 Claude 為曾經是 `reviewer` 的代理使用 `my-plugin:reviewer` 代理。

401 * **Hooks**：觸發每個 hook 匹配的事件。

402

403 如果遺失了什麼，請執行[測試和偵錯](#test-and-debug)。

404 </Step>

405</Steps>

406

407當原始檔案仍在 `.claude/` 下時，它們會與外掛程式的副本一起保持載入：

408

409* **技能和代理**：這兩組不會衝突，因為外掛程式的技能和代理帶有 `my-plugin:` 前綴。`/deploy` 和 `/my-plugin:deploy` 都有效，Claude 將 `reviewer` 和 `my-plugin:reviewer` 視為兩個子代理。

410* **Hooks**：hooks 沒有前綴，因此同時在您的設定檔案和 `hooks/hooks.json` 中的 hook 會在其事件每次觸發時執行兩次。

411

412在您確認外掛程式有效後，從 `.claude/` 刪除原始檔案並從您的設定檔案中移除 `hooks` 物件。

413

414<h2 id="next-steps">

415 後續步驟

416</h2>

417

418* [外掛程式元件](/docs/zh-TW/plugins/components)：將代理、hooks、MCP 伺服器、LSP 伺服器和使用者設定添加到您的外掛程式

419* [使用 evals 測試外掛程式](/docs/zh-TW/plugin-evals)：編寫 eval 案例並使用 `claude plugin eval` 執行它們以檢查外掛程式引導 Claude 行為的可靠性

420* [發佈外掛程式](/docs/zh-TW/plugins/publish)：版本化它、將其放在市集中，並將其提交到社群市集

421* [claude.ai 和 Cowork 上的外掛程式](https://claude.com/docs/plugins/overview)：同一個外掛程式資料夾安裝在 claude.ai 和 Cowork 上。某些元件僅限 Claude Code

422* [外掛程式清單參考](/docs/zh-TW/plugins/manifest-reference)：每個 `plugin.json` 欄位、路徑規則和目錄

423* [技能](/docs/zh-TW/skills)：編寫您的外掛程式提供的技能

424* [Anthropic 在 claude-code 存放庫中的外掛程式](https://github.com/anthropics/claude-code/tree/main/plugins)：本頁面佈局的完整工作範例，例如 `feature-dev` 和 `code-review`

plugins/create-marketplace.md +251 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 建立 marketplace

7> 從 marketplace.json 檔案建立 plugin marketplace，並在託管前在本機測試。

9plugin marketplace 是一個目錄或儲存庫，包含 `.claude-plugin/marketplace.json` 檔案，該檔案列出您的 plugins 以及從何處取得每個 plugin。您將目錄推送到 git 主機，任何有存取權限的人都可以使用一個命令在 Claude Code 中註冊它，並從中安裝您的 plugins。

11當您想要讓您選擇的群組（例如您的團隊或組織）安裝您的 plugins 並持續從您控制的目錄接收更新時，請建立您自己的 marketplace。該儲存庫可以是私有的，可以列出任意數量的 plugins，管理員可以[在每台機器上要求它](/docs/zh-TW/plugins/org)。

13<Note>

14 其他頁面涵蓋了這些情況：

16 * **與少數人分享一個 plugin**：將 plugin 的目錄或其 `.zip` 檔案發送給他們。請參閱[不使用 marketplace 分享 plugin](/docs/zh-TW/plugins/publish#share-a-plugin-without-a-marketplace)。

17 * **向所有人提供 plugin**：將其提交到 Anthropic 的社群 marketplace。請參閱[提交到社群 marketplace](/docs/zh-TW/plugins/publish#submit-to-the-community-marketplace)。

18 * **自己使用 plugin**：使用 `--plugin-dir` 載入它或將其保存在您的 skills 目錄中。請參閱[不使用 marketplace 開發](/docs/zh-TW/plugins/create#develop-without-a-marketplace)。

19</Note>

21從[建立 marketplace](#create-a-marketplace) 開始，在您自己的機器上建立一個並從中安裝 plugin，然後[新增更多 plugin 項目](#add-plugin-entries)。

23<h2 id="create-a-marketplace">

24 建立 marketplace

25</h2>

27以下步驟在您的機器上建立 marketplace，將 plugin 新增到其中，在 Claude Code 中註冊它，並從中安裝 plugin。這是整個流程，也是您的使用者在您將 marketplace 託管在他們可以存取的地方後所經歷的相同流程。從您想要建立 `my-marketplace/` 的目錄在您的 shell 中執行每個命令。

29您需要一個 plugin 來列出。該範例使用來自[建立您的第一個 plugin](/docs/zh-TW/plugins/create#create-your-first-plugin) 的 `my-first-plugin`，這是一個具有一個 skill 的 plugin，您可以將其作為 `/my-first-plugin:hello` 執行；如果您還沒有 plugin，請先建立它。若要改用您自己的 plugin，請在步驟說 `my-first-plugin` 的任何地方替換其目錄和其 `name`。有關 plugin 目錄可以包含的內容，請參閱 [plugin 目錄探索器](/docs/zh-TW/plugins/components#explore-the-plugin-directory)。

31<Steps>

32 <Step title="設定 marketplace 目錄">

33 marketplace 是一個包含 `.claude-plugin/marketplace.json` 檔案的目錄，加上它列出的 plugins。建立 marketplace 目錄及其 `.claude-plugin/` 資料夾，然後將您的 plugin 複製到 `plugins/` 下：

35 ```bash theme={null}

36 mkdir -p my-marketplace/.claude-plugin my-marketplace/plugins

37 cp -r my-first-plugin my-marketplace/plugins/

38 ```

40 檢查 plugin 在其現在所在位置是否有效，以便任何後續錯誤都是關於 marketplace 而不是 plugin：

42 ```bash theme={null}

43 claude plugin validate ./my-marketplace/plugins/my-first-plugin

44 ```

46 輸出的最後一行讀作 `✔ Validation passed`。

47 </Step>

49 <Step title="建立 marketplace 檔案">

50 將 `marketplace.json` 儲存在 `my-marketplace/.claude-plugin/marketplace.json`。該檔案需要 `name`、`owner` 和 `plugins` 陣列。

52 `plugins` 中的每個物件都是一個 plugin 項目，需要 `name` 和 `source`。將項目的 `source` 寫成從 marketplace 根目錄的路徑。根目錄是 `my-marketplace/`，即包含 `.claude-plugin/` 的目錄。

54 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}

55 {

56 "name": "my-marketplace",

57 "description": "Plugins for my team",

58 "owner": {

59 "name": "Your Name"

60 },

61 "plugins": [

62 {

63 "name": "my-first-plugin",

64 "source": "./plugins/my-first-plugin",

65 "description": "A greeting plugin to learn the basics"

66 }

67 ]

68 }

69 ```

70 </Step>

72 <Step title="驗證 marketplace">

73 在 marketplace 目錄上執行 `claude plugin validate` 以檢查 JSON 語法、必需欄位以及其 `.claude-plugin/marketplace.json` 中的每個 plugin 項目。

75 ```bash theme={null}

76 claude plugin validate ./my-marketplace

77 ```

79 對於在步驟 2 中編寫的檔案，輸出的最後一行讀作 `✔ Validation passed`。

80 </Step>

82 <Step title="新增 marketplace 並安裝 plugin">

83 將目錄註冊為 marketplace。

85 ```bash theme={null}

86 claude plugin marketplace add ./my-marketplace

87 ```

89 該命令列印 `✔ Successfully added marketplace: my-marketplace (declared in user settings)`，這意味著 marketplace 已記錄在您的使用者設定檔中。

91 安裝 plugin。安裝 id 是項目的 `name`、`@` 和 marketplace `name`。

93 ```bash theme={null}

94 claude plugin install my-first-plugin@my-marketplace

95 ```

97 該命令列印 `✔ Successfully installed plugin: my-first-plugin@my-marketplace (scope: user)`。

99 在工作階段內，`/plugin marketplace add ./my-marketplace` 以相同方式註冊 marketplace。`/plugin install my-first-plugin@my-marketplace` 在 `/plugin` 面板中開啟 plugin 的詳細資訊，您可以在其中安裝它。有關該流程，請參閱[安裝和管理 plugins](/docs/zh-TW/plugins/install)。

100 </Step>

101

102 <Step title="確認 plugin 已載入">

103 列出已安裝的 plugins。

104

105 ```bash theme={null}

106 claude plugin list

107 ```

108

109 輸出列出 `my-first-plugin@my-marketplace`，其中 `Status: ✔ enabled`。

110

111 若要查看 plugin 載入的內容，請顯示其詳細資訊。

112

113 ```bash theme={null}

114 claude plugin details my-first-plugin

115 ```

116

117 `Component inventory` 部分讀作 `Skills (1) hello`。

118

119 若要執行 skill，請啟動工作階段並輸入 `/my-first-plugin:hello`。Claude 會向您問候。該命令以 plugin 的名稱作為前綴，就像每個 plugin skill 的名稱一樣。

120 </Step>

121</Steps>

122

123<h2 id="add-plugin-entries">

124 新增 plugin 項目

125</h2>

126

127您分發的每個 plugin 都是 `marketplace.json` 的 `plugins` 陣列中的一個物件。若要新增第二個 plugin，請新增第二個物件。這些欄位涵蓋大多數項目：

128

129* `name`：人們在安裝時在 `@` 之前輸入的識別碼。它不能包含空格。

130* `source`：Claude Code 從何處取得 plugin。對於 marketplace 目錄內的 plugin，請寫入相對路徑字串，如[逐步解說](#create-a-marketplace)中所示，或對於目錄外的 plugin，請寫入來源物件。請參閱[選擇 plugin 來源](#choose-a-plugin-source)。

131* `description`：人們在 `/plugin` 中瀏覽您的 marketplace 時在 plugin 旁邊看到的行。

132

133有關完整欄位清單，請參閱 [Plugin 項目](/docs/zh-TW/plugins/marketplace-reference#plugin-entries)。

134

135項目也可以設定任何 [`plugin.json`](/docs/zh-TW/plugins/manifest-reference) 欄位。有關項目的 `plugin.json` 欄位何時適用於具有自己 `plugin.json` 的 plugin，請參閱[項目和 plugin.json](/docs/zh-TW/plugins/marketplace-reference#entry-and-plugin-json)。

136

137<h2 id="rules-for-plugin-entries">

138 Plugin 項目規則

139</h2>

140

141來自新 marketplace 的大多數失敗安裝來自於從錯誤目錄編寫的相對路徑，或來自與 plugin 的 `plugin.json` 中的 `name` 不同的項目名稱。

142

143<h3 id="write-relative-paths-from-the-marketplace-root">

144 從 marketplace 根目錄編寫相對路徑

145</h3>

146

147marketplace 根目錄是包含 `.claude-plugin/` 的目錄。在[逐步解說](#create-a-marketplace)中，那是 `my-marketplace/`，所以項目的 `source` 是 `"./plugins/my-first-plugin"`。該路徑不是從 `.claude-plugin/` 內部開始的，所以不要使用 `..` 來離開它。

148

149包含 `..` 的路徑和指向不存在目錄的路徑在不同命令中失敗：

150

151* **包含 `..` 的路徑**：`claude plugin validate` 將項目報告為無效。該訊息以 `Path contains "..": ./../plugins/my-first-plugin` 開頭。

152* **指向不存在目錄的路徑**：`claude plugin validate` 通過。`claude plugin install` 失敗，並顯示 `Source path does not exist: <path>`，其中 `<path>` 是 Claude Code 檢查的絕對位置。

153

154<h3 id="keep-the-entry-name-and-the-manifest-name-the-same">

155 保持項目名稱和清單名稱相同

156</h3>

157

158marketplace plugin 在 `marketplace.json` 中有一個項目 `name` 和在其自己的 `plugin.json` 中有一個 `name`，稱為清單名稱。每個名稱出現在不同的地方：

159

160* **項目名稱**：安裝 id，`<entry-name>@<marketplace>`。這是人們輸入以安裝的內容，`claude plugin list` 顯示的內容，以及 Claude Code 在其設定檔中的 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 下編寫的鍵。

161* **清單名稱**：plugin skills 上的前綴，以及 `claude plugin details` 接受的名稱。

162

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

164

165<h2 id="choose-a-plugin-source">

166 選擇 plugin 來源

167</h2>

168

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

170

171| 來源 | 何時使用 | 最小 `source` 值 |

172| :----------- | :------------------------------ | :---------------------------------------------------------------------------------------- |

173| 相對路徑 | plugin 的檔案在 marketplace 目錄本身內 | `"./plugins/my-first-plugin"` |

174| `github` | plugin 是其自己的 GitHub 儲存庫 | `{ "source": "github", "repo": "your-org/my-first-plugin" }` |

175| `git-subdir` | plugin 是某個其他儲存庫的子目錄，例如 monorepo | `{ "source": "git-subdir", "url": "your-org/monorepo", "path": "tools/my-first-plugin" }` |

176

177在 `git-subdir` 來源中，`url` 接受 git URL 或 `owner/repo` GitHub 簡寫。

178

179plugin 也可以來自以下來源類型之一：

180

181* `url`：任何主機上的 git 儲存庫（按 URL）

182* `archive`：通過 HTTPS 下載的 zip 檔案

183* `npm`：npm 套件

184* `command`：通過在安裝 plugin 的機器上執行命令產生的目錄

185

186有關每種來源類型的欄位，以及將基於 git 的來源固定到 `ref` 或 `sha`，請參閱 [Plugin 來源](/docs/zh-TW/plugins/marketplace-reference#plugin-sources)。

187

188<h2 id="validate-and-test">

189 驗證和測試

190</h2>

191

192當您新增 plugins 時，在每次編輯後在您的 shell 中執行 `claude plugin validate ./my-marketplace`，並在分享前從您自己機器上的 marketplace 安裝。驗證和安裝會捕捉不同的問題。

193

194<h3 id="problems-that-validation-reports">

195 驗證報告的問題

196</h3>

197

198`claude plugin validate` 只讀取 marketplace 目錄內的檔案。它報告：

199

200* JSON 語法錯誤，如 `json: Invalid JSON syntax: <reason>`

201* 遺漏的必需欄位，例如 `owner: Invalid input`

202* 包含空格、非 ASCII 字元或模仿官方 Anthropic marketplace 形式的 marketplace 名稱，例如 `claude-official`

203* 包含 `..` 的相對 `source`

204* 頂層或 plugin 項目中的未知欄位，作為警告

205* 每個相對路徑 plugin 的 `plugin.json` 中的問題，如 `plugins[N] plugin.json → <field>: <message>`

206

207有關 `validate` 可以列印的每條訊息，請參閱[驗證訊息](/docs/zh-TW/plugins/marketplace-reference#validation-messages)。有關其旗標和結束代碼，請參閱 [`plugin validate`](/docs/zh-TW/plugins/cli-reference#plugin-validate)。

208

209<h3 id="problems-that-surface-when-you-add-or-install">

210 新增或安裝時出現的問題

211</h3>

212

213`claude plugin validate` 不報告的問題在您新增 marketplace 或從中安裝時出現：

214

215* **當您新增 marketplace 時**：確切的[官方 marketplace 名稱](/docs/zh-TW/plugins/marketplace-reference#reserved-names)，例如 `claude-plugins-official`，通過驗證。當您新增具有其中一個名稱的 marketplace 時，Claude Code 拒絕它，並顯示以 `The name '<name>' is reserved for official Anthropic marketplaces` 開頭的訊息。

216* **當您安裝 plugin 時**：

217 * Claude Code 在您安裝 plugin 時首先取得 `github`、`git-subdir` 或其他遠端來源，因此錯誤的 `repo` 或 `path` 會在那時出現。

218 * 相對 `source` 的目錄不存在也會在安裝時失敗，並顯示 `Source path does not exist: <path>`。

219

220<h3 id="test-an-edit-to-a-plugin">

221 測試對 plugin 的編輯

222</h3>

223

224在[逐步解說](#create-a-marketplace)中，您從具有相對路徑 `source` 的本機目錄新增了 `my-marketplace`。使用該設定，Claude Code 直接從 `my-marketplace/plugins/` 讀取 plugin 的檔案。您的編輯在下一個工作階段開始時或當您在工作階段中執行 `/reload-plugins` 時生效，無需更改 plugin 的 `version`。

225

226從您託管的 marketplace 安裝的人會在 plugin 快取中獲得副本。有關他們如何接收新版本，請參閱[保持使用者最新](/docs/zh-TW/plugins/host-marketplace#keep-users-up-to-date)。

227

228<h3 id="remove-the-marketplace-to-start-over">

229 移除 marketplace 以重新開始

230</h3>

231

232若要移除所有內容並重新開始，請在您的 shell 中執行 `claude plugin marketplace remove my-marketplace`。該命令移除 marketplace 並卸載其 plugins。

233

234<h2 id="host-your-marketplace">

235 託管您的 marketplace

236</h2>

237

238一旦您可以從 marketplace 在您自己的機器上安裝 plugin，如[建立 marketplace](#create-a-marketplace) 中所示，請將 marketplace 目錄推送到 git 主機。

239

240您的隊友然後在他們的 shell 中為 GitHub 儲存庫執行 `claude plugin marketplace add <owner>/<repo>`，或使用儲存庫 URL 執行相同命令。然後他們按名稱安裝 plugin，如[逐步解說](#create-a-marketplace)中所示。

241

242有關私有儲存庫存取、更新、版本控制以及重新命名或移除項目，請參閱[託管和維護 marketplace](/docs/zh-TW/plugins/host-marketplace)。

243

244<h2 id="next-steps">

245 後續步驟

246</h2>

247

248* [託管和維護 marketplace](/docs/zh-TW/plugins/host-marketplace)：選擇主機、保持使用者最新，並安全地重新命名或移除 plugins

249* [Marketplace 參考](/docs/zh-TW/plugins/marketplace-reference)：`marketplace.json` 欄位和來源類型

250* [為您的組織管理 plugins](/docs/zh-TW/plugins/org)：在每台機器上要求您的 marketplace 及其 plugins

251* [按相關性建議 plugins](/docs/zh-TW/plugins/relevance)：當工作階段匹配時，讓 Claude Code 建議來自您的 marketplace 的 plugin

plugins/dependencies.md +245 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 外掛程式相依性

7> 宣告您的外掛程式所依賴的外掛程式，使用版本範圍如 ^1.2，並查看 Claude Code 如何安裝、解析和修剪它們。

9外掛程式相依性是您的外掛程式所依賴的另一個外掛程式，例如您呼叫其 MCP 伺服器或技能的外掛程式。每個相依性會追蹤其市集提供的最新版本，除非您宣告版本約束，即您已測試過的語義版本範圍，例如 `^2.0` 或 `~2.1.0`。

11本頁面適用於在 `plugin.json` 中宣告相依性的外掛程式作者，以及標記發行版本的市集維護者。

13<Note>

14 這些情況涵蓋在其他頁面上：

16 * **安裝具有相依性的外掛程式**：請參閱[管理已安裝的外掛程式](/docs/zh-TW/plugins/install#manage-installed-plugins)

17 * **讀取相依性錯誤**：請參閱[相依性錯誤](/docs/zh-TW/plugins/troubleshooting#dependency-errors)

18 * **宣告您的外掛程式自身程式碼所需的 npm 和 Bun 套件**：請參閱 [Node.js 套件相依性](/docs/zh-TW/plugins/loading#node-js-package-dependencies)

19</Note>

21若要新增約束，請從[使用版本約束宣告相依性](#declare-a-dependency-with-a-version-constraint)開始。如果您維護其他人依賴的外掛程式，請[標記您的發行版本](#tag-plugin-releases-for-version-resolution)，以便其約束可以解析。

23<h2 id="declare-dependencies">

24 宣告依賴

25</h2>

27<span id="decide-whether-to-constrain-dependency-versions" />沒有版本約束的情況下，依賴會在使用者下次更新時移至其 marketplace 發佈的每個新發行版本。如果該發行版本重新命名了你的 plugin 呼叫的 MCP 工具，你的 plugin 會對所有更新的人中斷。

29使用約束（例如來自 git 支援來源的依賴上的 `~2.1.0`），已安裝你的 plugin 的使用者會持續接收依賴的 `2.1.x` 修補程式，永遠不會移至 `2.2`。若要按自己的時間表升級，請針對較新的發行版本進行測試，然後發佈你的 plugin 的新版本，其中包含更寬的約束。

31<h3 id="declare-a-dependency-with-a-version-constraint">

32 使用版本約束宣告依賴

33</h3>

35在你的 plugin 的 `.claude-plugin/plugin.json` 的 `dependencies` 陣列中列出依賴。以下資訊清單宣告一個未版本化的依賴和一個受約束的依賴：

37```json .claude-plugin/plugin.json theme={null}

38{

39 "name": "deploy-kit",

40 "version": "3.1.0",

41 "dependencies": [

42 "audit-logger",

43 { "name": "secrets-vault", "version": "~2.1.0" }

44 ]

45}

46```

48一個項目可以是字串：僅 plugin 名稱，例如此資訊清單中的 `"audit-logger"`，或 `"name@marketplace"` 以在另一個 marketplace 中解析它。使用裸字串，你的 plugin 依賴於該 plugin 的 marketplace 提供的任何版本。

50若要設定版本約束，請使用具有這些欄位的物件，每個都是字串：

52| 欄位 | 說明 |

53| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

54| `name` | 依賴的 plugin 名稱，如其 marketplace 項目中所示。Claude Code 在與宣告 plugin 相同的 marketplace 中查詢它，除非你設定 `marketplace`。必需。 |

55| `version` | [語義版本範圍](https://github.com/npm/node-semver#ranges)，例如 `~2.1.0`、`^2.0`、`>=1.4` 或 `=2.1.0`。依賴會安裝在滿足此範圍的最高 git 標籤，因此依賴的維護者必須 [標記發行版本](#tag-plugin-releases-for-version-resolution)。 |

56| `marketplace` | 用於解析 `name` 的不同 marketplace。允許清單控制跨 marketplace 依賴，詳見 [依賴來自另一個 marketplace 的 plugin](#depend-on-a-plugin-from-another-marketplace)。 |

58範圍不符合預發行版本，例如 `2.0.0-beta.1`，除非你使用預發行後綴（例如 `^2.0.0-0`）選擇加入。

60<h3 id="bundle-plugins-for-a-team">

61 為團隊組合 plugin

62</h3>

64若要讓工程師使用一個命令安裝精選的 plugin 集合，請發佈一個資訊清單包含 `name` 和 `dependencies` 陣列的 plugin。Plugin 資訊清單只需要 `name`，所以這是一個有效的 plugin，安裝它會安裝每個依賴。

66例如，平台團隊可以在內部 marketplace 中發佈角色特定的組合，以便工程師執行一個 `claude plugin install` 而不是分別安裝每個 plugin：

68```json .claude-plugin/plugin.json theme={null}

69{

70 "name": "backend-standard",

71 "version": "1.0.0",

72 "description": "Standard plugin set for backend engineers",

73 "dependencies": [

74 "secrets-vault",

75 "deploy-kit",

76 { "name": "db-migrate", "version": "^3.0" },

77 "oncall-runbook"

78 ]

79}

80```

82若要稍後將 plugin 新增至標準集合，請發佈新的 `backend-standard` 版本，其中包含額外的依賴。當 marketplace 不 [預設自動更新](/docs/zh-TW/plugins/loading#which-marketplaces-and-plugins-auto-update) 時，工程師要麼為 marketplace 開啟自動更新，要麼手動更新：

84* **為 marketplace 開啟自動更新**：下一次自動更新會將組合移至新版本並安裝它新增的任何依賴。

85* **手動更新**：在 shell 中執行 `claude plugin update backend-standard`，然後在開啟的工作階段中執行 `/reload-plugins` 以安裝新增的依賴。

87有關工程師端的步驟，請參閱 [保持 plugin 更新](/docs/zh-TW/plugins/install#keep-plugins-updated)。

89若要將組合部署給組織中的每個人，管理員會將其新增至受管設定中的 `enabledPlugins`。請參閱 [預先安裝並要求 plugin](/docs/zh-TW/plugins/org#pre-install-and-require-plugins)。

91<h3 id="depend-on-a-plugin-from-another-marketplace">

92 依賴來自另一個 marketplace 的 plugin

93</h3>

95預設情況下，Claude Code 不會從與宣告 plugin 自身不同的 marketplace 安裝依賴，除非使用者已在相同範圍內安裝並啟用該依賴。此預設值可防止一個 marketplace 從使用者未審查的來源無聲地安裝 plugin。

97若要允許安裝，請將目標 marketplace 的名稱新增至根 marketplace 的 `marketplace.json` 中的 `allowCrossMarketplaceDependenciesOn`。根 marketplace 是託管使用者正在安裝的 plugin 的 marketplace。只有根 marketplace 的允許清單適用。

99以下 `marketplace.json` 允許 `deploy-kit` 依賴來自 `your-shared-marketplace` 的 plugin：

100

101```json .claude-plugin/marketplace.json theme={null}

102{

103 "name": "your-marketplace",

104 "owner": { "name": "Your Org" },

105 "allowCrossMarketplaceDependenciesOn": ["your-shared-marketplace"],

106 "plugins": [

107 {

108 "name": "deploy-kit",

109 "source": "./deploy-kit",

110 "dependencies": [

111 { "name": "audit-logger", "marketplace": "your-shared-marketplace" }

112 ]

113 }

114 ]

115}

116```

117

118如果 `allowCrossMarketplaceDependenciesOn` 遺失或不包含目標 marketplace，Claude Code 不會安裝依賴。當依賴在 marketplace 項目中宣告時，安裝本身會被拒絕，並顯示以 `Dependency "audit-logger@your-shared-marketplace" (required by deploy-kit@your-marketplace) is in marketplace "your-shared-marketplace", which is not in the allowlist` 開頭的訊息，並命名要設定的欄位。當它在 `plugin.json` 中宣告時，安裝完成而不包含依賴，然後你的 plugin 無法載入。

119

120允許清單檢查不適用於已啟用的依賴。如果使用者首先在相同範圍內從 `your-shared-marketplace` 自行安裝 `audit-logger`，`deploy-kit` 隨後會安裝而無需對允許清單進行任何變更。

121

122<h3 id="test-a-plugin-and-its-dependency-locally">

123 在本機測試 plugin 及其依賴

124</h3>

125

126如果你同時開發 plugin 及其依賴的 plugin，請從 shell 啟動 Claude Code 並使用 [`--plugin-dir`](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 載入兩者：

127

128```bash theme={null}

129claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

130```

131

132依賴的本機副本滿足你的 plugin 的依賴項目，因此你不需要從其 marketplace 安裝依賴。

133

134* **不需要 `version`**：本機 `plugin.json` 也不需要 `version`，因為 [版本約束](#declare-a-dependency-with-a-version-constraint) 不會針對本機副本進行檢查。

135* **命名 marketplace 的項目**：命名 marketplace 的項目也符合 Claude Code v2.1.242 或更新版本上的本機副本。

136

137在你從其 marketplace 安裝依賴之前，每當本機副本被停用或不存在時，你的 plugin 都會停止載入：

138

139* **你停用了本機副本**：你的 plugin 在下一次 plugin 載入時被停用，並顯示以 `is disabled — enable it or remove the dependency` 結尾的錯誤。當錯誤將依賴命名為 `<name>@inline` 時，該識別碼指的是 `--plugin-dir` 副本。

140* **你啟動了沒有依賴的 `--plugin-dir` 旗標的工作階段**：錯誤報告依賴未安裝。再次傳遞旗標，或從其 marketplace 安裝依賴。

141

142當兩個 plugin 都在一個父資料夾中時，你可以一次將該資料夾傳遞給 `--plugin-dir`。如果資料夾本身不是 plugin，Claude Code 會載入每個具有 `.claude-plugin/plugin.json` 的子資料夾。需要 Claude Code v2.1.265 或更新版本。

143

144<h2 id="tag-plugin-releases-for-version-resolution">

145 發行其他人依賴的 plugin

146</h2>

147

148如果你維護其他 plugin 使用版本約束依賴的 plugin，請標記其發行版本，以便這些約束可以解析。約束會針對託管 plugin 的儲存庫上的 git 標籤進行解析。標記 plugin 的 [plugin 來源](/docs/zh-TW/plugins/marketplace-reference#plugin-sources) 在 `marketplace.json` 中指向的儲存庫：

149

150* **`github`、`url` 或 `git-subdir` 來源**：plugin 自身的儲存庫，因此 plugin 的作者建立標籤

151* **相對路徑，例如 `./plugins/secrets-vault`**：marketplace 儲存庫，因此 marketplace 維護者建立標籤

152

153<h3 id="create-a-release-tag">

154 建立發行標籤

155</h3>

156

157將每個發行版本標記為 `<plugin-name>--v<version>`，其中 `<version>` 符合該提交的 `plugin.json` 中的 `version` 欄位。plugin-name 前綴讓一個 marketplace 儲存庫可以託管多個具有獨立版本歷史的 plugin。

158

159從 plugin 目錄建立標籤，並配置 `origin` 遠端以接收推送的標籤，使用 [`claude plugin tag`](/docs/zh-TW/plugins/cli-reference#plugin-tag)：

160

161```bash theme={null}

162claude plugin tag --push

163```

164

165該命令從 plugin 的資訊清單建立標籤名稱。在建立標籤之前，它執行這些檢查：

166

167* 驗證 plugin

168* 當 plugin 目錄在 marketplace 簽出內時，檢查 `plugin.json` 和 marketplace 項目是否同意版本

169* 需要 plugin 目錄下的乾淨工作樹

170* 如果標籤已存在，則拒絕

171

172成功執行會列印 `Created tag secrets-vault--v2.1.0`。使用 `--push`，它也會列印 `Pushed to origin`。沒有 `--push`，它會列印你自己執行的 `git push` 命令。

173

174傳遞 `--dry-run` 以查看計畫而不建立任何內容。

175

176[`claude plugin tag` 參考](/docs/zh-TW/plugins/cli-reference#plugin-tag) 列出其餘旗標。

177

178你也可以直接執行 `git tag secrets-vault--v2.1.0`，只要你自己保持 `plugin.json` 中的 `version` 和 marketplace 項目中的版本同步。

179

180<h3 id="constrain-a-dependency-that-has-a-non-git-source">

181 約束具有非 git 來源的依賴

182</h3>

183

184標籤型解析僅適用於 git 支援的來源。對於具有 `npm`、`archive` 或 `command` [plugin 來源](/docs/zh-TW/plugins/marketplace-reference#plugin-sources) 的依賴，約束不控制擷取哪個版本。當 plugin 載入時仍會檢查它，如果已安裝的版本不滿足它，則依賴 plugin 會被停用。

185

186對於 `npm`、`archive` 和 `command` 來源，檢查的版本是依賴的 `plugin.json` 中的 `version`。在約束該依賴之前在那裡設定一個，因為不設定版本的 `plugin.json` 不滿足任何約束。

187

188Claude Code 永遠不會自行安裝具有 `command` 來源的依賴，因此使用者 [首先安裝它](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)。它也永遠不會執行依賴的 [`headersHelper`](/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，因此使用者也在安裝你的 plugin 之前安裝其 marketplace 項目設定的依賴。

189

190除了 `claude plugin install` 之外，這些操作也會安裝任何遺失的宣告依賴，`command` 和 `headersHelper` 限制也適用於它們：

191

192* `/reload-plugins`

193* 依賴 plugin 的 marketplace 自動更新

194* 在依賴 plugin 上重新執行 `claude plugin install`

195* `claude plugin marketplace add`

196

197<h2 id="how-dependencies-behave-for-your-users">

198 依賴如何為你的使用者表現

199</h2>

200

201這些部分說明一旦你的 plugin 與其他 plugin 一起安裝，Claude Code 如何解析、檢查和組合你宣告的約束。

202

203<h3 id="how-a-constraint-resolves-against-tags">

204 約束如何針對標籤進行解析

205</h3>

206

207當使用者安裝宣告 `{ "name": "secrets-vault", "version": "~2.1.0" }` 的 plugin 時，依賴會從滿足 `~2.1.0` 的最高 `secrets-vault--v` 標籤安裝在託管 `secrets-vault` 的儲存庫上。當沒有標籤滿足範圍時，安裝要麼失敗，要麼使用 marketplace 的目前副本：

208

209* **具有自身儲存庫的 plugin**：安裝失敗，訊息包含 `Dependency "secrets-vault@your-marketplace" has no git tag satisfying`。

210* **由相對路徑參考的 plugin**：安裝改為使用 marketplace 的目前副本，並在 plugin 載入時檢查約束。如果該副本超出範圍，依賴 plugin 保持停用，`claude plugin list` 顯示 `Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0`。

211

212對於 marketplace 由相對路徑參考的 plugin，你新增為本機資料夾路徑的 marketplace 也會針對該資料夾的 git 標籤解析約束，當資料夾是 git 儲存庫時。這需要 Claude Code v2.1.196 或更新版本。不是 git 儲存庫的本機資料夾沒有標籤，因此 Claude Code 改為從資料夾的目前內容安裝依賴。

213

214<h3 id="confirm-the-resolved-version">

215 確認解析的版本

216</h3>

217

218若要確認約束解析到哪個版本，請在 shell 中執行 `claude plugin list`。標籤解析的依賴會顯示其版本，帶有 12 字元提交後綴，例如 `2.1.0-8713c5b11005`。

219

220約束檢查使用標籤的版本而不是 `plugin.json` 中的 `version`，即使該提交的 `plugin.json` 落後。

221

222如果你強制移動標籤到不同的提交，下一次安裝會擷取該提交的內容而不是重複使用陳舊的快取副本。請參閱 [版本和更新](/docs/zh-TW/plugins/loading#versions-and-updates) 以了解 plugin 的版本如何成為其快取鍵。

223

224<h3 id="combine-constraints-from-several-plugins">

225 組合來自多個 plugin 的約束

226</h3>

227

228當多個已安裝的 plugin 約束相同的依賴時，依賴會解析到滿足所有其範圍的最高版本。常見的組合解析如下：

229

230| Plugin A 要求 | Plugin B 要求 | 結果 |

231| :---------- | :---------- | :----------------------------------------------------------------------------- |

232| `^2.0` | `>=2.1` | 在最高 `2.x` 標籤處進行一次安裝，位於或高於 `2.1.0`。兩個 plugin 都載入。 |

233| `~2.1` | `~3.0` | 安裝 plugin B 失敗，並顯示 `has conflicting version requirements` 訊息。Plugin A 和依賴保持原樣。 |

234| `=2.1.0` | 無 | 依賴保持在 `2.1.0`。自動更新在安裝 plugin A 時跳過較新的版本。 |

235

236自動更新會在滿足每個已安裝 plugin 範圍的最高 git 標籤處擷取受約束的依賴，而不是在 marketplace 的最新版本處。如果已安裝 plugin 的範圍不重疊，自動更新會將該依賴保留在其目前版本，`/plugin` **Errors** 標籤會顯示命名約束 plugin 的項目。如果它們重疊但沒有標籤落在範圍內，自動更新會擷取 marketplace 的目前副本，並在該副本的 `version` 落在任何已安裝 plugin 的範圍之外時跳過更新。

237

238當使用者卸載最後一個約束依賴的 plugin 時，依賴不再受約束於版本範圍，並在下一次更新時恢復追蹤其 marketplace 項目。

239

240<h2 id="see-also">

241 另請參閱

242</h2>

243

244* [`claude plugin prune`](/docs/zh-TW/plugins/cli-reference#plugin-prune)：移除任何 plugin 不再需要的自動安裝依賴

245* [託管 marketplace](/docs/zh-TW/plugins/host-marketplace)：發行通道和推薦其他 plugin

plugins/host-marketplace.md +458 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 託管和維護市集

7> 發佈一個外掛程式市集，讓使用者可以透過 /plugin marketplace add 新增它、安裝其外掛程式，並在您推送變更後持續接收更新。

9託管市集意味著將您的 `marketplace.json` 目錄放在其他人可以使用 `/plugin marketplace add` 新增它的位置，安裝其外掛程式，並在您推送後持續接收您的變更。

11本頁面適用於操作市集的人員。

13<Note>

14 這些情況涵蓋在其他頁面上：

16 * **您還沒有編寫目錄檔案**：從 [建立市集](/docs/zh-TW/plugins/create-marketplace) 開始

17 * **您是管理員，需要在組織的機器上要求、限制或預先安裝市集**：閱讀 [為您的組織管理外掛程式](/docs/zh-TW/plugins/org)

18</Note>

20從 [託管您的市集](#host-your-marketplace) 開始以選擇主機和您的使用者執行的命令。在您的第一次發佈之前，閱讀 [讓使用者保持最新狀態](#keep-users-up-to-date)。在您變更外掛程式的 `name` 之前，閱讀 [重新命名或移除外掛程式](#rename-or-remove-a-plugin)。

22<h2 id="host-your-marketplace">

23 Host your marketplace

24</h2>

26您可以在 GitHub、另一個 git 主機、託管的 `marketplace.json` URL 或共享檔案系統上的目錄中託管 marketplace。將您主機的新增命令和使用者機器上需要的內容發送給您的使用者：

28| 主機 | 使用者在 Claude Code 工作階段中執行 | 使用者需要什麼 |

29| :---------------------------------------------------- | :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |

30| GitHub | `/plugin marketplace add your-org/your-marketplace` | `git`，以及對於私有儲存庫，[Grant access to a private marketplace](#grant-access-to-a-private-marketplace) 下描述的存取權 |

31| GitLab、Bitbucket、GitHub Enterprise Server 或另一個 git 主機 | `/plugin marketplace add https://gitlab.example.com/team/plugins.git` | `git` 和從其機器存取主機的權限。發送完整 URL，因為 `owner/repo` 簡寫總是指 github.com |

32| 託管的 `marketplace.json` URL | `/plugin marketplace add https://plugins.example.com/marketplace.json` | 對 URL 的 HTTPS 存取。使用者不需要 `git` 來存取目錄本身 |

33| 共享檔案系統上的目錄 | `/plugin marketplace add /Volumes/shared/claude-plugins` | 對路徑的讀取存取 |

35若要固定 GitHub 或 git-URL marketplace 的分支或標籤，告訴使用者附加 `#<ref>`，如 `your-org/your-marketplace#stable`。[plugin commands reference](/docs/zh-TW/plugins/cli-reference#plugin-marketplace-add) 列出命令接受的每種形式。

37成功新增會列印 `Successfully added marketplace: your-marketplace`。Claude Code 從您 `marketplace.json` 中的 `name` 欄位取得該名稱，而不是從儲存庫名稱。

39使用者隨後透過其項目的 `name` 和 marketplace 的 `name` 安裝 plugin，如 `/plugin install code-formatter@your-marketplace`。

41<h3 id="register-the-marketplace-for-everyone-in-a-repository">

42 Register the marketplace for everyone in a repository

43</h3>

45若要與在一個儲存庫中工作的每個人共享 marketplace，請從您的 shell 在那裡執行一次 `claude plugin marketplace add your-org/your-marketplace --scope project`，並提交它寫入的 `.claude/settings.json`。Claude Code 隨後為每個 [trusts the folder](/docs/zh-TW/plugins/org#require-plugins-per-repository) 的隊友註冊 marketplace。

47<h3 id="avoid-relative-path-entries-in-a-url-hosted-marketplace">

48 Avoid relative-path entries in a URL-hosted marketplace

49</h3>

51當使用者將您的 marketplace 新增為裸 `marketplace.json` URL 時，Claude Code 只下載該檔案。您 `plugins` 陣列中其 `source` 是相對路徑（如 `./plugins/formatter`）的項目隨後在安裝時失敗，並顯示 [`its marketplace entry path does not stay inside the marketplace directory`](/docs/zh-TW/plugins/troubleshooting#plugins-with-relative-paths-fail-in-url-based-marketplaces)。為每個項目提供可以自行取得的 source，如 `github` 儲存庫或 `archive` URL，或在 git 儲存庫中託管 marketplace，以便 Claude Code 複製整個樹。

53<h3 id="edit-plugins-in-place-on-a-shared-directory">

54 Edit plugins in place on a shared directory

55</h3>

57當使用者從共享目錄新增您的 marketplace 時，Claude Code 直接從該目錄讀取具有相對路徑 sources 的 plugins，而不是複製它們。使用者在下次啟動工作階段或執行 `/reload-plugins` 時看到您的編輯，無需更新步驟或版本提升。

59<h3 id="keep-plugin-files-out-of-git-lfs">

60 Keep plugin files out of Git LFS

61</h3>

63將您的 plugins 需要的檔案保留在 [Git LFS](https://git-lfs.com) 之外。當使用者從 git 儲存庫中託管的 marketplace 新增 marketplace 或安裝其列出的基於 git 的 plugin 時，Claude Code 將該 marketplace 或 plugin 儲存庫複製到其機器上。複製永遠不會下載 LFS 內容，因此 LFS 追蹤的檔案會作為指標檔案到達。

65<h3 id="share-files-within-a-marketplace-with-symlinks">

66 Share files within a marketplace with symlinks

67</h3>

69若要在您的 plugin 和同一 marketplace 的其他部分之間共享檔案，請在您的 plugin 目錄內建立符號連結。當 Claude Code 將 plugin 複製到其快取時，它透過目標解析的位置處理每個符號連結：

71* **在 plugin 自己的目錄內**：符號連結在快取中保留為相對符號連結，因此它在執行時繼續解析到複製的目標。

72* **在同一 marketplace 內的其他地方**：符號連結被取消引用。目標的內容被複製到快取中以取代它。這讓 meta-plugin 的 `skills/` 目錄可以連結到 marketplace 中其他 plugins 定義的 skills。

73* **在 marketplace 外**：符號連結因安全原因被跳過。

75對於從本地路徑安裝的 plugins，或從 [`command` source](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)（其 `mode` 是預設 `copy`）安裝的 plugins，Claude Code 只保留在 plugin 自己目錄內解析的符號連結，並跳過所有其他。

77以下命令建立從 marketplace plugin 內部到由同級 plugin 定義的共享 skill 的連結。在 Windows 上，從提升的命令提示字元使用 `mklink /D` 或啟用開發人員模式：

79```bash theme={null}

80ln -s ../../shared-plugin/skills/foo ./skills/foo

81```

83<h2 id="distribute-through-organization-settings">

84 Distribute through organization settings

85</h2>

87在 Team 或 Enterprise 方案上，您也可以透過 claude.ai 上的 [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory) 分發 marketplace，而不是在使用者新增它的地方託管它。Organization sync 透過您組織在 claude.ai 上的 GitHub 或 GitLab 連線讀取儲存庫，因此您使用者的 git 認證不涉及。

89Organization sync 對儲存庫的要求比 `/plugin marketplace add` 更嚴格：

91* **Marketplace 儲存庫**：在 github.com 和 gitlab.com 上，它必須是私有或內部的

92* **Plugin sources**：每個 plugin source 必須是 `github`、`url` 或 `git-subdir` 類型，或以 `./` 開頭的 [relative path](/docs/zh-TW/plugins/marketplace-reference#relative-path-plugin-source)

93* **頂級 `bin/` 目錄**：claude.ai 拒絕具有一個的 plugin 並同步 marketplace 的其餘部分。錯誤訊息以 `Plugin contains a top-level bin/ directory` 開頭。將可執行檔保留在另一個目錄中，如 `scripts/`，並從您的 hooks 或 MCP 伺服器設定中將它們參考為 `${CLAUDE_PLUGIN_ROOT}/scripts/<name>`

95有關管理員工作流程，請參閱 [Manage plugins for your organization](https://support.claude.com/en/articles/13837433)。

97<h2 id="grant-access-to-a-private-marketplace">

98 Grant access to a private marketplace

99</h2>

100

101當使用者新增、從或更新您的 marketplace 時，Claude Code 在其機器上執行 `git`，並關閉互動式提示，並依賴該機器已經持有的任何認證。Claude Code 沒有自己的 git token，`marketplace.json` 也沒有欄位用於它。

102

103您透過發送給使用者的新增命令的形式選擇複製是透過 SSH 還是 HTTPS 執行：

104

105* **GitHub `owner/repo`**：Claude Code 探測 `ssh -T git@github.com`，當探測成功時透過 SSH 複製。如果探測失敗，或 SSH 複製本身失敗，它透過 HTTPS 複製。沒有 GitHub SSH 金鑰的機器上的使用者可以設定 `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` 以跳過探測並透過 HTTPS 複製。

106* **`git@host:path.git`**：SSH。

107* **`https://example.com/repo.git`**：HTTPS。

108

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

110

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

112* **HTTPS**：Claude Code 保持使用者的 git 認證助手啟用，但禁止它提示。助手已儲存的認證有效；它必須要求的認證失敗。在 GitHub 上，`gh auth login` 後跟 `gh auth setup-git` 會儲存一個。

113

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

115

116如果您改為透過 claude.ai 上的 **Organization settings > Plugins & skills** 分發，您使用者的 git 認證不涉及。請參閱 [Distribute through organization settings](#distribute-through-organization-settings) 以了解哪些 plugin sources 可以在那裡是私有的。

117

118<h3 id="serve-users-who-have-no-git-host-account">

119 Serve users who have no git-host account

120</h3>

121

122沒有 git-host 帳戶的使用者可以將您提供的 marketplace 新增為 `marketplace.json` URL 或從共享目錄，但他們只能安裝其項目 sources 他們也可以到達的 plugins。指向私有 `github` 儲存庫的項目在安裝時仍然對他們失敗，因為 Claude Code 使用與 git 託管 marketplace 相同的非互動式 `git` 取得它。

123

124這些項目 sources 不需要 git 帳戶：

125

126* **`archive`**：透過 HTTPS 下載的 zip。使用者既不需要 `git` 也不需要帳戶，只需要對 URL 的網路存取。需要 Claude Code v2.1.224 或更新版本。使用 `sha256` 固定每個存檔，以便 Claude Code 拒絕變更的下載。若要使用下載傳送認證，請參閱 [Authenticate archive downloads](#authenticate-archive-downloads)。

127* **公開 git 儲存庫**：當項目提供 `https://` URL 時，Claude Code 透過 HTTPS 複製公開 `url` 或 `git-subdir` source，無需認證。對於 `github` source 或寫成 `owner/repo` 的 `git-subdir` source，沒有 GitHub SSH 金鑰的使用者設定 `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`。

128

129對於一個網路上的團隊，共享檔案系統上的 `directory` marketplace 也可以在沒有 git 帳戶的情況下工作。使用者只需要對路徑的讀取存取。

130

131<h3 id="what-background-auto-update-does-with-credentials">

132 What background auto-update does with credentials

133</h3>

134

135背景自動更新是 Claude Code 在工作階段啟動後對 marketplaces 和已安裝 plugins 的無人值守重新整理。對於您的 marketplace，它預設關閉，直到使用者或管理員開啟它，如 [Keep users up to date](#keep-users-up-to-date) 下所涵蓋。

136

137當它對私有 marketplace 開啟時，新提交的背景檢查使用使用者配置的 git 認證助手，永遠不會提示。每種遠端和助手給出不同的結果：

138

139* **SSH remotes**：載入 `ssh-agent` 中的金鑰驗證檢查。

140* **具有儲存認證的 HTTPS remotes**：可以在沒有提示的情況下提供儲存認證的助手驗證檢查。Git Credential Manager、macOS Keychain 助手和 `git-credential-store` 一旦持有主機的認證就以這種方式工作。

141* **具有需要提示的助手的 HTTPS remotes**：助手無法在背景中回答。更新失敗無聲，現有簽出保留在原位，因此使用者的 plugins 從最後同步狀態繼續工作。

142

143檢查後，Claude Code 執行以下其中一項：

144

145* **簽出是最新的**：Claude Code 按原樣保留它。

146* **檢查找到新提交，或因為無法到達或驗證遠端而失敗**：Claude Code 再次複製 marketplace 並用新複製替換現有簽出。如果該複製失敗，現有簽出保留在原位。重新複製可以 [time out on large repositories](/docs/zh-TW/plugins/troubleshooting#git-clone-timed-out-after-120s)。

147

148若要保持私有 marketplace 最新，使用者可以執行以下任一操作：

149

150* **儲存認證**：首先登入認證助手，以便它持有主機的認證。對於 GitHub，執行 `gh auth login`，然後 `gh auth setup-git`。

151* **在失敗時保持簽出**：如果使用者設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1`，當背景檢查無法到達或驗證遠端時，Claude Code 保持現有簽出而不嘗試重新複製。Plugins 從最後同步狀態繼續工作。

152

153如果使用者在環境中設定 `GITHUB_TOKEN` 或另一個提供者 token，單獨這不會驗證背景檢查。Token 透過認證助手（如 `gh` CLI 的助手，讀取 `GH_TOKEN` 和 `GITHUB_TOKEN`）生效。

154

155<h2 id="roll-out-to-a-whole-company">

156 Roll out to a whole company

157</h2>

158

159將 plugin 推出到整個公司涉及您作為 marketplace 所有者、控制受管設定的管理員以及使用 Claude Code 的每個人。您可以在沒有管理員的情況下執行推出，在這種情況下每個人自己新增 marketplace 並安裝 plugin。

160

161| 誰 | 他們做什麼 | 它在哪裡涵蓋 |

162| :---------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |

163| 您，marketplace 所有者 | 將目錄保留在只有公司可以讀取的儲存庫中，發送您主機的新增命令，並說明每個人在其機器上需要什麼 | [Host your marketplace](#host-your-marketplace) 和 [Grant access to a private marketplace](#grant-access-to-a-private-marketplace) |

164| 管理員 | 使用受管設定中的 `extraKnownMarketplaces` 和 `enabledPlugins` 為每個人註冊 marketplace 並開啟其 plugins，並在那裡設定 `autoUpdate` | [Require a marketplace and its plugins](/docs/zh-TW/plugins/org#require-a-marketplace-and-its-plugins) 和 [Set update policy](/docs/zh-TW/plugins/org#set-update-policy) |

165| 每個人 | 需要對私有 git 儲存庫的讀取存取，其認證已儲存在其機器上。沒有管理員，他們也執行新增和安裝命令 | [Add a private marketplace](/docs/zh-TW/plugins/install#add-a-private-marketplace) |

166

167對於沒有 git-host 帳戶的人，這些部分各涵蓋一種到達他們的方式：

168

169* **不需要 git 帳戶的項目 sources**：[Serve users who have no git-host account](#serve-users-who-have-no-git-host-account)

170* **預先填充的 plugins 目錄**：[Seed containers and CI](/docs/zh-TW/plugins/org#seed-containers-and-ci)，也為沒有 git-host 帳戶的使用者服務

171* **claude.ai organization settings**：[Distribute through organization settings](#distribute-through-organization-settings)，其中您使用者的 git 認證不涉及

172

173<h2 id="keep-users-up-to-date">

174 Keep users up to date

175</h2>

176

177您的變更透過背景自動更新到達使用者，一旦它對您的 marketplace 開啟，或當使用者自己更新 plugin 時。在兩種情況下，使用者只有在其計算版本變更時才獲得 plugin 的新副本，如 [Release a new version](#release-a-new-version) 下所述。

178

179<h3 id="turn-on-auto-update">

180 Turn on auto-update

181</h3>

182

183背景自動更新預設對您的 marketplace 關閉，`marketplace.json` 沒有欄位來開啟它。使用者或管理員開啟它：

184

185* **告訴使用者開啟它**：每個使用者進入 `/plugin` 中的 **Marketplaces**，選擇您的 marketplace，並選擇 **Enable auto-update**。

186* **要求管理員設定它**：如果管理員在受管設定中的您 marketplace 的 `extraKnownMarketplaces` 項目上設定 `"autoUpdate": true`，它對接收這些設定的每個人都開啟。請參閱 [Set update policy](/docs/zh-TW/plugins/org#set-update-policy)。

187

188沒有自動更新，使用者在工作階段中執行 `/plugin marketplace update <name>` 或在 shell 中執行 `claude plugin update <plugin>@<name>` 時接收您的變更。

189

190有關使用者在更新到達時看到的內容，請參閱 [When auto-update runs](/docs/zh-TW/plugins/loading#when-auto-update-runs)。

191

192<h3 id="release-a-new-version">

193 Release a new version

194</h3>

195

196若要向使用者發佈新版本，變更 plugin 的 `version`。使用者只有在 plugin 的計算版本與他們擁有的版本不同時才獲得新副本。該版本首先來自 `plugin.json`，然後來自 marketplace 項目，根據 [Versions and updates](/docs/zh-TW/plugins/loading#versions-and-updates)。

197

198使用者從 marketplace 新增為本地目錄的 [load in place](/docs/zh-TW/plugins/loading#find-plugins-on-disk) 的 plugin 不受 `version` 控制。它在每個工作階段啟動時載入您的目前檔案，無論其版本字串說什麼。

199

200對於除了就地載入或來自 `command` source 的安裝之外的每次安裝，要麼在每次發佈時增加 `version`，要麼省略它：

201

202* **在每次發佈時提升 `version`**：使用者保留在其快取副本上，直到字串變更。如果您設定 `"version": "1.0.0"` 並推送新提交而不變更它，使用者不會接收它們。

203* **省略 `version`**：使用者改為追蹤您的提交。將 `version` 保留在 `plugin.json` 和 marketplace 項目之外。

204

205不要在 `plugin.json` 和 marketplace 項目中都設定 `version`。如果您這樣做，Claude Code 使用 `plugin.json` 值而不警告，`claude plugin validate` 報告不匹配為 `Entry declares version "<a>" but <path>/plugin.json says "<b>"`。

206

207<h3 id="hold-users-on-one-version">

208 Hold users on one version

209</h3>

210

211一個 marketplace 一次為每個 plugin 提供一個版本，因此您透過選擇每個項目指向的內容來保持使用者在一個版本上：

212

213* **plugin 項目上的 `ref` 和 `sha`**：`ref` 命名分支或標籤，`sha` 命名 `github`、`url` 或 `git-subdir` source 的提交。請參閱 [Plugin sources](/docs/zh-TW/plugins/marketplace-reference#plugin-sources)。

214* **新增命令上的 `#<ref>`**：新增 `your-org/your-marketplace#stable` 的使用者獲得該目錄的分支或標籤。對於一次兩個發佈線，請參閱 [Run release channels](#run-release-channels)。

215* **`<plugin>--v<version>` 標籤**：依賴的版本範圍針對這些標籤解析。請參閱 [Release a plugin that others depend on](/docs/zh-TW/plugins/dependencies#tag-plugin-releases-for-version-resolution)。

216

217[Release a new version](#release-a-new-version) 說明變更的項目何時到達使用者。

218

219<h3 id="change-the-command-of-a-command-source">

220 Change the command of a command source

221</h3>

222

223如果您變更 [`command` source](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source) 的 `command`，或切換其 `mode`，每個使用者必須在 Claude Code 執行它之前接受新命令。Claude Code 只執行使用者在安裝或最後更新 plugin 時接受的確切命令。

224

225在使用者的 marketplace 副本取得變更後，該使用者看到以下內容：

226

227* **沒有更多背景執行**：該使用者的命令的 [once-per-session run](/docs/zh-TW/plugins/loading#when-a-command-source-re-runs) 停止，因此工具的新輸出不會到達他們。

228* **`/plugin` Errors 標籤中的項目**：項目顯示新命令和要執行的 `claude plugin update` 命令。

229

230告訴使用者執行該項目顯示的 `claude plugin update` 命令，在終端中。Claude Code 向他們顯示新命令並要求他們接受它。

231

232<h2 id="run-release-channels">

233 Run release channels

234</h2>

235

236若要提供穩定和早期存取軌道，託管兩個 marketplaces，其項目指向同一 plugin 的不同 refs，並讓每個使用者新增他們想要的。Claude Code 沒有發佈頻道概念，一個 marketplace 一次為每個 plugin 提供一個版本。

237

238給兩個 `marketplace.json` 檔案不同的 `name` 值。Claude Code 透過其 `name` 識別 marketplace，因此使用者一次不能有兩個具有相同名稱的 marketplaces 已註冊。

239

240使用這兩個目錄，新增 `stable-tools` 的使用者從 `stable` 分支安裝 `code-formatter`，新增 `latest-tools` 的使用者從 `latest` 安裝它：

241

242```json theme={null}

243{

244 "name": "stable-tools",

245 "owner": { "name": "Your Org" },

246 "plugins": [

247 { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "stable" } }

248 ]

249}

250```

251

252```json theme={null}

253{

254 "name": "latest-tools",

255 "owner": { "name": "Your Org" },

256 "plugins": [

257 { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "latest" } }

258 ]

259}

260```

261

262給兩個 refs 不同的 `plugin.json` 版本，或省略 `version` 以便提交 SHA 區分它們。更新透過比較版本檢測，因此在沒有版本變更的情況下移動的 ref 使使用者保留在快取副本上。

263

264若要將頻道指派給使用者群組而不是讓使用者選擇，管理員給每個群組匹配的 `extraKnownMarketplaces` 項目，如 [Set update policy](/docs/zh-TW/plugins/org#set-update-policy) 下所述。

265

266<h2 id="rename-or-remove-a-plugin">

267 Rename or remove a plugin

268</h2>

269

270Plugin 的 `name` 是其識別碼。使用者在 `enabledPlugins` 和 `pluginConfigs` 設定鍵以及 `/plugin install` 中參考它，因此變更它會破壞每次現有安裝。

271

272若要變更使用者在 `/plugin` 中看到的標籤而不破壞任何東西，在 `plugin.json` 中設定 `displayName` 並保持 `name` 不變。

273

274<h3 id="migrate-users-with-a-renames-map">

275 Migrate users with a renames map

276</h3>

277

278當您必須變更 `name` 時，將頂級 `renames` 對應新增到 `marketplace.json`，以便 Claude Code 遷移現有使用者，而不是報告 [`Plugin "<name>" not found in marketplace`](/docs/zh-TW/plugins/troubleshooting#plugin-not-found-in-marketplace)。當您從 `plugins` 移除項目時也執行相同操作。自動遷移需要 Claude Code v2.1.193 或更新版本。

279

280將每個前名稱對應到其目前名稱，或在 plugin 消失時對應到 `null`。此 marketplace 將 `formatter` 重新命名為 `code-formatter` 並記錄 `legacy-linter` 已移除：

281

282```json theme={null}

283{

284 "name": "your-marketplace",

285 "owner": { "name": "Your Org" },

286 "plugins": [

287 { "name": "code-formatter", "source": "./plugins/code-formatter" }

288 ],

289 "renames": {

290 "formatter": "code-formatter",

291 "legacy-linter": null

292 }

293}

294```

295

296在您推送後，仍然啟用舊名稱的使用者看到以下結果之一：

297

298* **重新命名的項目**：plugin 在其新名稱下載入。`claude plugin list` 和 `/plugin` 下 plugin 的詳細資訊一次顯示 `Renamed to "code-formatter" in the "your-marketplace" marketplace`，Claude Code 在使用者、專案和本地設定範圍中將舊鍵重寫為新鍵在 `enabledPlugins` 和 `pluginConfigs` 中。

299* **`null` 項目**：舊鍵從這些範圍中刪除，使用者看到 `Removed from the "your-marketplace" marketplace`。

300* **在受管設定中啟用**：plugin 仍然在其新名稱下載入，但 Claude Code 無法重寫受管設定，因此通知重複出現，直到管理員在那裡更新 `enabledPlugins`。

301

302對於使用者從 git 儲存庫或 URL 新增的 marketplace，重新命名的 plugin 報告 [`Plugin "<name>" not cached at <path>`](/docs/zh-TW/plugins/troubleshooting#plugin-not-cached-at)，直到使用者在工作階段中執行 `/plugin install code-formatter@your-marketplace` 一次。

303

304將 `renames` 視為僅附加歷史記錄。在每個人遷移後保持舊項目。當您再次重新命名時，添加第二個項目而不是編輯第一個，因為 Claude Code 遵循從最舊名稱的鏈。

305

306在您的 shell 中，編輯對應後執行 `claude plugin validate .`。它拒絕循環或在 `null` 或 `plugins` 中的名稱以外的任何地方結束的鏈，並顯示 `renames.<name>: chain does not resolve`。

307

308<h3 id="uninstall-removed-plugins-from-users’-machines">

309 Uninstall removed plugins from users' machines

310</h3>

311

312若要從使用者的機器卸載已移除的 plugin 而不是留下副本，在 `marketplace.json` 的頂級設定 `"forceRemoveDeletedPlugins": true`。沒有欄位，已移除的 plugin 保留已安裝，並在工作階段載入它時報告 `Plugin "<name>" not found in marketplace`。使用它，Claude Code 在每個工作階段啟動時執行以下操作：

313

3141. 比較使用者從您的 marketplace 安裝的內容與項目和 `renames` 對應，並將既未列出也未重新命名的任何 plugin 視為已移除。

3152. 從使用者、專案和本地範圍卸載每個已移除的 plugin。只有受管設定安裝的 Plugins 保留在原位。

3163. 在 `/plugin` 中的 **Flagged** 標題下列出每個已移除的 plugin，狀態為 `Removed from marketplace`。

317

318<h2 id="authenticate-archive-downloads">

319 Authenticate archive downloads

320</h2>

321

322若要驗證 [`archive`](/docs/zh-TW/plugins/marketplace-reference#archive-plugin-source) 下載（如從私有登錄的下載），設定 Claude Code 使用它發送的 HTTP 標頭。您可以在以下任一位置設定 `headers`：

323

324* **Marketplace 的 `url` source**：您註冊 marketplace 的 `url` source，如 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目。

325* **Plugin 的項目**：在 Claude Code v2.1.238 或更新版本上，您可以改為在 plugin 的 `marketplace.json` 項目上設定它，在 `source` 旁邊。

326

327在任一位置，當值是短期的（如您的登錄按需生成的 token）時，設定 `headersHelper` 命令而不是 `headers`。Claude Code 執行命令並將其列印的 JSON 物件作為該位置的標頭發送。需要 Claude Code v2.1.238 或更新版本。

328

329[marketplace reference](/docs/zh-TW/plugins/marketplace-reference#plugin-entries) 列出 `headers` 和 `headersHelper` 項目欄位。

330

331您選擇的位置決定哪些下載獲得標頭以及 Claude Code 何時執行命令：

332

333| 位置 | 獲得標頭的下載 | Claude Code 何時執行在那裡設定的 `headersHelper` |

334| :----------------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------- |

335| Marketplace `url` source | 在 marketplace URL 的來源上的存檔下載，意味著相同的方案、主機和連接埠 | 在每次 marketplace 的 `marketplace.json` 的取得之前以及在該來源上的每次存檔下載之前。Claude Code 重複使用一次執行的輸出長達 60 秒 |

336| Plugin 項目 | 該項目的下載只 | 只有當使用者自己安裝或更新該一個 plugin 並 [accepts the command](#how-users-accept-a-headershelper-command) 時 |

337

338其中兩個位置都設定相同名稱的標頭，Claude Code 發送項目的值。在一個位置內，命令列印的標頭覆蓋 `headers` 中列出的相同名稱的標頭。

339

340<h3 id="add-a-headershelper-to-a-plugin-entry">

341 Add a headersHelper to a plugin entry

342</h3>

343

344此項目在 `source` 旁邊設定 `headersHelper`。它也設定 [`"strict": false`](/docs/zh-TW/plugins/marketplace-reference#strict-mode)，Claude Code 要求設定 `headersHelper` 的 `marketplace.json` 項目：

345

346```json theme={null}

347{

348 "name": "my-plugin",

349 "description": "Formatting commands for internal services",

350 "strict": false,

351 "source": {

352 "source": "archive",

353 "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"

354 },

355 "headersHelper": "/opt/bin/mint-registry-token.sh"

356}

357```

358

359若要檢查項目，在您的 shell 中執行 `claude plugin install my-plugin@your-marketplace`。Claude Code 向您顯示命令和存檔 URL，並在您接受後下載 zip。

360

361<h3 id="write-the-headershelper-command">

362 Write the headersHelper command

363</h3>

364

365無論您在 marketplace 的 `url` source 還是在 plugin 項目上設定 `headersHelper`，編寫命令以滿足這些要求：

366

367* **命令文字**：最多 500 個可列印 ASCII 字元，沒有四個或更多空格的執行。

368* **輸出**：在 stdout 上列印一個標頭名稱和字串值的 JSON 物件，然後在 10 秒內退出 0。

369* **Shell 和工作目錄**：Claude Code 透過 `sh` 執行命令，或在 Windows 上透過 `cmd.exe`。工作目錄是設定目錄，即 `~/.claude` 或 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars#variables)。給出絕對路徑或 `PATH` 上的命令，因為相對路徑針對該目錄解析，而不是使用者的專案。

370* **Claude Code 移除的變數**：當命令在 `marketplace.json` 項目中設定，或在專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中設定時，Claude Code 從環境中移除每個名稱看起來像認證的變數，透過 [same rule it applies to an MCP `headersHelper`](/docs/zh-TW/mcp#which-variables-a-helper-can-read)。`ANTHROPIC_API_KEY` 和 `MY_REGISTRY_TOKEN` 都被移除，因此讓命令從檔案或認證存儲讀取其認證。此移除不適用於在使用者設定、`--settings` 檔案或受管設定中設定的命令。

371* **Claude Code 設定的變數**：`CLAUDE_CODE_MARKETPLACE_URL` 和 `CLAUDE_CODE_MARKETPLACE_NAME` 用於 `url` source 的命令，以及 `CLAUDE_CODE_PLUGIN_NAME` 和 `CLAUDE_CODE_PLUGIN_ARCHIVE_URL` 用於項目的命令。`CLAUDE_CODE_MARKETPLACE_NAME` 在使用者透過 URL 新增 marketplace 後的第一次取得時未設定，因為該取得是提供名稱的內容。

372

373鑄造持有者 token 的命令列印像這樣的物件：

374

375```json theme={null}

376{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

377```

378

379<h3 id="when-claude-code-skips-a-headershelper-command-or-drops-its-output">

380 When Claude Code skips a headersHelper command or drops its output

381</h3>

382

383`headersHelper` 命令不執行，或來自 `headers` 或命令輸出的標頭被刪除，當以下任一情況適用時：

384

385* **命令失敗**：如果命令退出非零、執行超過 10 秒或列印除了字串值的 JSON 物件以外的任何內容，命令執行的取得或下載不會發生。

386* **Marketplace URL 不以 `https://` 開頭**：該 `url` source 的命令不執行，請求只攜帶其 `headers` 欄位中列出的標頭。

387* **重新導向離開來源**：當下載被重新導向離開存檔 URL 的來源時，重新導向的請求不攜帶來自 marketplace `url` source 或 plugin 項目的 `headers` 值或命令輸出。

388* **項目設定路由或身份標頭**：Claude Code 從項目的 `headers` 和命令輸出中刪除請求路由和用戶端身份名稱（如 `Host`、`Cookie` 和 `X-Forwarded-*`），並保持驗證名稱（如 `Authorization`）。每個 `marketplace.json` 項目都以這種方式過濾。對於設定中的內聯 plugin 項目，請參閱 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces)。

389* **命令在 `--add-dir` 目錄的設定中設定**：命令被忽略，在 `url` source 和 [inline plugin entry](/docs/zh-TW/settings-reference#extraknownmarketplaces) 上，只有該檔案的 `headers` 被發送。

390* **受管設定阻止命令**：將 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) 設定為 `true` 阻止 `headersHelper` 命令，[`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) 也阻止它們，除非 `disableCommandPluginSources` 明確為 `false`。在任一阻止下，Claude Code 仍然為受管設定本身聲明的 marketplace 執行命令。

391

392<h3 id="how-users-accept-a-headershelper-command">

393 How users accept a headersHelper command

394</h3>

395

396使用者在每次自己安裝或更新該一個 plugin 時接受 plugin 項目的命令。他們從 `/plugin` 中的 plugin 自己的檢視執行此操作，或使用 `claude plugin install` 或 `claude plugin update`。Claude Code 顯示命令和存檔 URL，並只在使用者接受後執行命令。

397

398在非互動式 shell 中，傳遞 [`--yes`](/docs/zh-TW/plugins/cli-reference#plugin-install) 以接受命令。若要接受只有先前 `--json` 執行顯示的命令，傳遞 [`--accept-command`](/docs/zh-TW/plugins/cli-reference#plugin-install) 與執行報告的 `sha256`。

399

400Claude Code 只執行它顯示的命令，用於它顯示的存檔 URL。如果項目的命令或存檔 URL 在之間變更，Claude Code 拒絕安裝或更新。查詢字串中的變更單獨不計。

401

402<h3 id="installs-and-updates-that-refuse-the-command-instead-of-asking">

403 Installs and updates that refuse a command instead of asking

404</h3>

405

406在除了單一 plugin 安裝或更新之外的任何操作上，Claude Code 既不執行項目的命令也不下載其存檔。Plugin 保留在其已安裝版本或保留未安裝，使用者看到以下結果之一：

407

408* **一次安裝多個 plugins、來自 plugin 建議或作為另一個 plugin 的依賴**：Claude Code 拒絕具有命令的 plugin 並將使用者導向該 plugin 在 `/plugin` 中的自己檢視。批量安裝中的其他 plugins 仍然安裝。依賴被拒絕 plugin 的 plugin 失敗安裝，直到使用者自己安裝被拒絕 plugin。

409* **背景自動更新，或工作階段啟動用於其存檔從未下載的 plugin**：Claude Code 在 `/plugin` Errors 標籤中列出 plugin，以便使用者知道自己安裝或更新它。

410

411<h3 id="when-a-marketplace-url-sources-command-runs">

412 When a marketplace `url` source's command runs

413</h3>

414

415您在設定檔案中聲明 marketplace `url` source 的 `headersHelper`，如 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目，而不是在 marketplace 發佈的目錄中。Claude Code 因此不要求使用者在每次安裝或更新時接受它。相反，聲明它的設定檔案決定 Claude Code 何時執行它：

416

417| 設定檔案 | Claude Code 何時執行命令 |

418| :---------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |

419| 使用者設定、`--settings` 檔案或機器上的受管設定檔案 | 無需詢問，包括在背景 marketplace 重新整理期間 |

420| 專案的 `.claude/settings.json` 或 `.claude/settings.local.json` | 只有在使用者接受該資料夾本身的 [workspace trust dialog](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 後。`-p` 或 SDK 工作階段不計為接受它，也不計為授予對父資料夾的信任 |

421| 伺服器受管設定 | 在互動式工作階段中，只有在使用者在 [security approval dialog](/docs/zh-TW/server-managed-settings#security-approval-dialogs) 中批准交付的設定後 |

422

423對於這些檔案中的 [inline plugin entry](/docs/zh-TW/settings-reference#extraknownmarketplaces)，Claude Code 要求與該檔案中 marketplace 級別命令相同的資料夾信任或設定批准，使用者也在每次安裝或更新時接受項目的命令。

424

425<h2 id="depend-on-and-recommend-other-plugins">

426 Depend on and recommend other plugins

427</h2>

428

429項目可以聲明對其他 plugins 的依賴。

430

431* **版本範圍**：依賴可以攜帶 semver 範圍。

432* **跨 marketplace 依賴**：來自另一個 marketplace 的依賴只有在您的 marketplace 在 `allowCrossMarketplaceDependenciesOn` 中列出該 marketplace 時才安裝。

433

434對於版本範圍、它們解析的 `<plugin>--v<version>` git-tag 約定以及跨 marketplace 信任，請參閱 [Plugin dependencies](/docs/zh-TW/plugins/dependencies)。

435

436若要在專案匹配它時讓 Claude Code 建議 plugin，將 `relevance` 區塊新增到項目，其中包含識別專案的信號。使用者只有在管理員在 `pluginSuggestionMarketplaces` 中列出您的 marketplace 時才看到來自您 marketplace 的建議。對於信號和啟用步驟，請參閱 [Plugin relevance](/docs/zh-TW/plugins/relevance)。

437

438<h2 id="work-around-what-a-marketplace-can’t-do">

439 解決市集無法做到的事

440</h2>

441

442某些擁有者要求的功能在 `marketplace.json` 中沒有對應的欄位。以下是每項功能最接近的選項：

443

444* **限制使用者安裝其他項目**：市集允許清單是受管理的設定，`strictKnownMarketplaces`。請參閱[限制使用者可以安裝的項目](/docs/zh-TW/plugins/org#restrict-what-users-can-install)。

445* **在使用者未要求的情況下安裝或啟用外掛程式**：沒有入口欄位可以安裝外掛程式。受管理的 `enabledPlugins` 可以為整個機隊執行此操作；請參閱[預先安裝並要求外掛程式](/docs/zh-TW/plugins/org#pre-install-and-require-plugins)。

446* **向不同的使用者顯示不同的項目**：項目沒有對象欄位，每個新增市集的使用者都會看到整個目錄。為不同的對象託管不同的市集。

447* **將外掛程式標記為已棄用**：沒有棄用狀態。選項是移除項目，在 `renames` 中將其名稱對應到 `null`，並選擇性地設定 `forceRemoveDeletedPlugins`。

448* **為使用者開啟自動更新**：每個使用者在 `/plugin` 中的**市集**下開啟它，或管理員在受管理的設定中設定 `autoUpdate`。請參閱[開啟自動更新](#turn-on-auto-update)。

449* **攜帶 git 認證**：沒有市集欄位可以保存 git 權杖。對 git 託管的市集或外掛程式的存取遵循使用者的 git 設定，詳見[授予對私人市集的存取權](#grant-access-to-a-private-marketplace)。對於 `archive` 來源，項目可以改為設定 [`headers` 或 `headersHelper`](#authenticate-archive-downloads)。

450

451<h2 id="next-steps">

452 Next steps

453</h2>

454

455* [Marketplace reference](/docs/zh-TW/plugins/marketplace-reference)：`marketplace.json` 欄位、source 類型和驗證訊息

456* [Manage plugins for your organization](/docs/zh-TW/plugins/org)：在整個組織的機器上要求、限制或播種您的 marketplace

457* [Plugin dependencies](/docs/zh-TW/plugins/dependencies)：標籤發佈，以便依賴您的 plugins 的 plugins 可以解析版本

458* [Troubleshoot plugins](/docs/zh-TW/plugins/troubleshooting)：您的使用者在新增或從您的 marketplace 更新時看到的錯誤

plugins/install.md +418 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 安裝和管理外掛程式

7> 從任何使用介面上的市集安裝 Claude Code 外掛程式，選擇安裝範圍，並在稍後更新或移除它們。

9安裝外掛程式會將其技能、代理、hooks 和 MCP 伺服器新增到您機器上的 Claude Code。

11本頁面適用於在自己的機器或帳戶上使用外掛程式的任何人，無論是在終端機、桌面應用程式、IDE 或雲端工作階段中：它涵蓋安裝、選擇範圍、新增市集和保持外掛程式更新。

13<Note>

14 這些情況在其他頁面上涵蓋：

16 * **您使用 claude.ai 聊天或 Cowork，而不是 Claude Code**：請參閱 [claude.ai 和 Cowork 中的外掛程式](https://claude.com/docs/plugins/overview)

17 * **Claude Code 列印了錯誤**：在 [外掛程式疑難排解](/docs/zh-TW/plugins/troubleshooting) 中找到它

18</Note>

20從 [安裝外掛程式](#install-a-plugin) 開始。如果有人傳送給您的安裝命令其 `@` 名稱不是 `claude-plugins-official`，請先 [新增該市集](#add-a-marketplace)。

22<h2 id="install-a-plugin">

23 安裝外掛程式

24</h2>

26作為範例，本節安裝來自 [Anthropic 官方市集](/docs/zh-TW/plugins/anthropic-marketplaces) 的 [`commit-commands`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/commit-commands)，它新增了用於提交、推送和開啟拉取請求的命令。

28相同的步驟安裝任何其他外掛程式：在 `commit-commands` 和 `claude-plugins-official` 出現的地方替換其名稱和其市集的名稱。如果該外掛程式來自不同的市集，請先 [新增市集](#add-a-marketplace)。

30選擇您執行 Claude Code 的位置的標籤。

32<Tabs>

33 <Tab title="Terminal">

34 在您的專案中使用 `claude` 啟動 Claude Code，然後：

36 <Steps>

37 <Step title="使用安裝命令開啟外掛程式的詳細資訊">

38 使用外掛程式的名稱和市集執行 `/plugin install`。在工作階段中，此命令不會立即安裝：它在該外掛程式的詳細資訊上開啟 `/plugin` 面板，以便您可以檢閱它並先選擇範圍。

40 ```text theme={null}

41 /plugin install commit-commands@claude-plugins-official

42 ```

44 若要瀏覽，請執行不帶外掛程式名稱的 `/plugin`：面板在 **Discover** 標籤上開啟，該標籤列出您新增的每個市集中的外掛程式，您可以輸入以搜尋，然後在外掛程式上按 **Enter** 以開啟其詳細資訊。

45 </Step>

47 <Step title="檢閱外掛程式新增的內容">

48 詳細資訊窗格顯示外掛程式的描述。它也可以顯示：

50 * **Will install**：外掛程式新增的命令、代理、技能、hooks 和 MCP 及 LSP 伺服器。

51 * **Last updated**：針對 Anthropic 官方市集中的外掛程式顯示。

52 * **Context cost**：對於 Anthropic 官方市集中的外掛程式，有兩個令牌估計。**Every turn** 是外掛程式新增到您傳送的每條訊息的內容，**When invoked** 是其技能和代理在 Claude 載入它們後新增的內容。當您透過命名其市集開啟外掛程式時（如步驟 1 命令所做的那樣）或從 **Marketplaces** 標籤時，估計會出現。您從 **Discover** 清單到達的詳細資訊窗格不會顯示它們。

54 來自本機或自訂市集的外掛程式可以改為顯示 `Components will be discovered at installation`。

56 外掛程式可以執行 hooks 和 MCP 伺服器，因此在安裝前請閱讀窗格。請參閱 [外掛程式安全性和信任](/docs/zh-TW/plugins/security)。

57 </Step>

59 <Step title="選擇範圍">

60 選擇三個安裝選項之一：

62 * **Install for you (user scope)**：您在此機器上的每個專案中都獲得外掛程式

63 * **Install for all collaborators on this repository (project scope)**：它對在此儲存庫中工作的每個人都啟用

64 * **Install for you, in this repo only (local scope)**：您只在此儲存庫中獲得它

66 [選擇安裝範圍](#choose-an-install-scope) 說明每個範圍寫入哪個設定檔，以及當相同外掛程式在多個位置設定時哪個適用。

68 選擇範圍後，Claude Code 安裝外掛程式及其宣告的任何依賴項，然後列印安裝摘要。

69 </Step>

71 <Step title="閱讀安裝摘要">

72 摘要的最後一句告訴您外掛程式在此工作階段中是否可用：

74 * **Active now**：`Plugin is now active.` 不需要重新載入。

75 * **Reload needed**：`Run /reload-plugins to activate.` 面板關閉，Claude Code 為您執行該重新載入。如果重新載入會 [使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，它會警告並改為保留外掛程式待處理。執行 `/reload-plugins --force` 以無論如何啟動它，這會花費一個未快取的請求。

76 * **Load failed**：`The plugin couldn't be loaded`。在 `/plugin` 中開啟 **Errors** 標籤以了解原因，然後請參閱 [安裝後：外掛程式無法運作](/docs/zh-TW/plugins/troubleshooting#plugin-installed-but-not-working)。

77 </Step>

79 <Step title="確認外掛程式有效">

80 輸入 `/` 並在其名稱下尋找外掛程式的技能，形式為 `/<plugin>:<skill>`。對於 `commit-commands`，`/commit-commands:commit` 出現。另外兩個地方也列出外掛程式：

82 * 在 `/plugin` 中開啟 **Installed** 標籤，該標籤列出具有其範圍的外掛程式。

83 * 在您的 shell 中，執行 `claude plugin list`，它列印相同的清單，包含 `Version`、`Scope` 和 `Status` 行。

85 如果 `/commit-commands:commit` 沒有出現，請參閱 [安裝後：外掛程式無法運作](/docs/zh-TW/plugins/troubleshooting#plugin-installed-but-not-working)。

86 </Step>

87 </Steps>

89 從任何其他市集安裝需要先執行一個額外步驟：[新增市集](#add-a-marketplace)。Claude Code 在您第一次啟動互動式終端機工作階段時為您新增 Anthropic 的官方市集，這就是為什麼範例跳過該步驟。如果您在 [claude.com/marketplace](https://claude.com/marketplace) 上找到外掛程式，其 **Claude Code** 按鈕會複製其 [shell 形式](#install-from-your-shell) 中的安裝命令，`claude plugin install <name>@claude-plugins-official`。

90 </Tab>

92 <Tab title="Desktop app">

93 在桌面應用程式的 **Code** 標籤中的本機或 SSH 工作階段中：

95 <Steps>

96 <Step title="開啟外掛程式瀏覽器">

97 按一下提示框旁的 **+** 按鈕，選擇 **Plugins**，然後選擇 **Add plugin**。外掛程式瀏覽器開啟，顯示來自您市集的外掛程式。

98 </Step>

100 <Step title="選擇外掛程式">

101 找到 `commit-commands` 並選擇它。

102 </Step>

103

104 <Step title="選擇範圍">

105 選擇 [範圍](#choose-an-install-scope)：您的使用者帳戶、此專案或僅限本機。

106 </Step>

107 </Steps>

108

109 若要稍後啟用、停用或卸載，請使用 **+ > Plugins > Manage plugins**。外掛程式瀏覽器在桌面應用程式的雲端工作階段中不可用。請參閱 [在桌面應用程式中安裝外掛程式](/docs/zh-TW/desktop#install-plugins)。

110 </Tab>

111

112 <Tab title="VS Code">

113 在 VS Code 中的 Claude Code 面板中：

114

115 <Steps>

116 <Step title="開啟 Manage plugins">

117 在提示框中輸入 `/plugins` 以開啟 **Manage plugins**。

118 </Step>

119

120 <Step title="安裝外掛程式">

121 在 **Plugins** 標籤上，搜尋 `commit-commands` 並按一下 **Install**。如果標籤未列出任何外掛程式，請先在 **Marketplaces** 標籤上新增 `anthropics/claude-plugins-official`。

122 </Step>

123

124 <Step title="選擇範圍">

125 選擇 [範圍](#choose-an-install-scope)：**Install for you**、**Install for this project** 或 **Install locally**。

126 </Step>

127 </Steps>

128

129 您的變更會套用到開啟的工作階段，無需重新啟動。請參閱 [在 VS Code 中管理外掛程式](/docs/zh-TW/vs-code#manage-plugins)。

130 </Tab>

131

132 <Tab title="Cloud session">

133 [雲端工作階段](/docs/zh-TW/cloud-environments)（包括 [claude.ai/code 上的瀏覽器](/docs/zh-TW/claude-code-on-the-web)）沒有外掛程式瀏覽器，不會載入您在自己的機器上安裝的外掛程式或您儲存庫的 `.claude/settings.json` 開啟的外掛程式。對於您的組織透過受管設定分發的外掛程式，請參閱 [為您的組織管理外掛程式](/docs/zh-TW/plugins/org)。

134

135 請參閱 [您的設定中哪些部分也可在雲端工作階段中使用](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 以了解您設定的其餘部分。

136 </Tab>

137</Tabs>

138

139<h3 id="choose-an-install-scope">

140 選擇安裝範圍

141</h3>

142

143外掛程式的安裝範圍決定誰獲得外掛程式以及哪個設定檔將其記錄為啟用：

144

145* **User scope**：外掛程式在此機器上的每個專案中為您啟用。該項目進入 `~/.claude/settings.json` 中的 `enabledPlugins`。

146* **Project scope**：外掛程式在此儲存庫中為每個人啟用。該項目進入 `.claude/settings.json`，您提交它。

147* **Local scope**：外掛程式在此儲存庫中僅為您啟用。該項目進入 `.claude/settings.local.json`。

148

149某些外掛程式由其作者設定為預設關閉，透過 [`defaultEnabled`](/docs/zh-TW/plugins/manifest-reference#defaultenabled) 欄位。這樣的外掛程式已安裝但保持關閉，直到您在 shell 中使用 `claude plugin enable <name>` 或從工作階段中 `/plugin` 的 **Installed** 標籤開啟它。

150

151當相同的外掛程式在多個範圍設定時，本機設定覆蓋專案設定，專案設定覆蓋使用者設定。請參閱 [尋找外掛程式啟用的位置](/docs/zh-TW/plugins/loading#find-where-a-plugin-is-enabled) 以了解完整規則。

152

153終端機、桌面應用程式的本機工作階段和一台電腦上的 VS Code 擴充功能讀取相同的設定檔，因此您在其中任何一個以使用者範圍安裝的外掛程式在其他兩個中可用。

154

155<h3 id="other-places-you-run-claude-code">

156 JetBrains、非互動式執行和 Agent SDK

157</h3>

158

159您執行 Claude Code 的某些地方沒有自己的外掛程式瀏覽器：

160

161* **JetBrains IDEs**：JetBrains 外掛程式在 IDE 的終端機中執行 Claude Code，因此在那裡使用 **Terminal** 標籤的步驟。

162* **`claude -p` 和其他非互動式執行**：`/plugin` 不執行，Claude 回覆 `/plugin isn't available in this environment.` 您已安裝的外掛程式確實會載入。使用 [`claude plugin` 命令](#install-from-your-shell) 從 shell 安裝和管理它們。

163* **Agent SDK**：透過 SDK 的外掛程式選項載入外掛程式。請參閱 [在 Agent SDK 中載入外掛程式](/docs/zh-TW/agent-sdk/plugins)。

164

165如果 Claude Code 報告儲存庫的 `.claude/settings.json` 中啟用的外掛程式未安裝，請參閱 [在專案設定中啟用但未安裝](/docs/zh-TW/plugins/loading#enabled-in-project-settings-but-not-installed)。

166

167<Tip>

168 如果您是外掛程式作者測試磁碟上的外掛程式副本，請從 shell 使用 `--plugin-dir` 啟動 Claude Code，以便為一個工作階段載入它，而不是安裝它。請參閱 [為一個工作階段載入外掛程式的旗標](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session)。

169</Tip>

170

171<h3 id="plugins-from-your-claude-ai-account">

172 來自您 claude.ai 帳戶的外掛程式

173</h3>

174

175您的 claude.ai 帳戶是外掛程式的單獨來源，與您安裝的市集並列：

176

177* **What arrives**：您為 claude.ai 帳戶開啟的每個外掛程式，以及您的組織為其成員開啟的每個外掛程式。在終端機工作階段中，每次您在使用該帳戶登入時啟動 Claude Code 時，它們會在背景同步；在 Cowork 工作階段中，它們在工作階段啟動時下載。

178* **Where you see them**：在 `/plugin` 和 `claude plugin list` 中，ID 為 `<name>@synced`。您可以在自己的範圍關閉一個，除非您的組織要求它。

179* **What doesn't go the other way**：您使用 `/plugin` 或 `claude plugin install` 安裝的外掛程式保留在此機器上，不會新增到您的 claude.ai 帳戶。

180

181有關同步時間、登入要求和關閉同步，請參閱 [從 claude.ai 同步的外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)。

182

183<h3 id="install-from-your-shell">

184 從您的 shell 安裝

185</h3>

186

187在 shell 中執行 `claude plugin install` 以安裝外掛程式，而無需啟動 Claude Code 工作階段，例如從設定指令碼。

188

189* **Scope**：預設為使用者範圍。傳遞 `--scope project` 或 `--scope local` 以變更它。

190* **When the plugins load**：它安裝的外掛程式在您下次啟動 Claude Code 時載入，或當您在已開啟的工作階段中執行 `/reload-plugins` 時載入。

191* **The marketplace must be added first**：在沒有人開啟互動式 Claude Code 工作階段的機器上，官方市集未註冊，因此從它安裝的指令碼在安裝前執行 `claude plugin marketplace add anthropics/claude-plugins-official`。

192

193```bash theme={null}

194claude plugin install formatter@your-org --scope project

195```

196

197命令完成時列印 `Successfully installed plugin: formatter@your-org (scope: project)`。

198

199某些外掛程式透過執行其市集命名的命令進行安裝，稱為 [`command` source](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)。Claude Code 向您顯示該命令並要求您在執行前接受它。指令碼沒有人回答該提示，因此在那裡傳遞 `--yes` 以接受它。

200

201對於每個 `claude plugin install` 旗標，請參閱 [plugin install](/docs/zh-TW/plugins/cli-reference#plugin-install)。

202

203<h2 id="add-a-marketplace">

204 新增市集

205</h2>

206

207當您想要的外掛程式不在 Anthropic 的官方市集中時，您只需要本節，例如同事發佈的外掛程式或來自 Anthropic 社群市集的外掛程式。

208

209市集是外掛程式的目錄，Claude Code 必須知道市集才能從中安裝。您新增一次市集。之後，其外掛程式出現在 **Discover** 標籤上，並使用 `/plugin install <plugin>@<marketplace>` 在工作階段中或 `claude plugin install <plugin>@<marketplace>` 在 shell 中安裝，其中 `<marketplace>` 是市集註冊的名稱。若要在一個步驟中同時執行兩者，請參閱 [新增市集並在一個命令中安裝](#add-a-marketplace-and-install-in-one-command)。

210

211在 Claude Code 工作階段中，執行 `/plugin marketplace add` 後跟市集的來源：GitHub 儲存庫、任何主機上的 git 儲存庫、本機目錄或檔案，或託管的 `marketplace.json`。

212

213| Source | What you type | Example |

214| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |

215| GitHub repository | `owner/repo`。新增 `#ref` 以固定分支或標籤。 | `/plugin marketplace add anthropics/claude-code`，或 `/plugin marketplace add your-org/plugins#v1.2.0` 以固定 `v1.2.0` 標籤 |

216| Git repository on any host | 完整的複製 URL。新增 `#ref` 以固定分支或標籤。 | `/plugin marketplace add https://gitlab.example.com/your-group/your-marketplace.git#v1.0.0` |

217| Local directory or file | 保存 `.claude-plugin/marketplace.json` 的目錄的相對或絕對路徑，或 JSON 檔案本身的路徑。以 `./` 或 `../` 開始相對路徑，因為 Claude Code 將裸 `name/name` 讀取為 GitHub 儲存庫。 | `/plugin marketplace add ./my-marketplace` |

218| Hosted `marketplace.json` | 其 `https://` URL | `/plugin marketplace add https://example.com/marketplace.json` |

219

220從 shell，`claude plugin marketplace add` 採用相同的來源。

221

222<Tip>

223 `/plugin market` 也可作為 `/plugin marketplace` 的較短形式。

224</Tip>

225

226在每個 URL 上包含 `https://` 前綴，或對 SSH 使用 `git@host:path` 形式。如果您輸入裸 `gitlab.example.com/your-group/your-marketplace.git`，Claude Code 將其讀取為 GitHub `owner/repo` 速記並拒絕它。

227

228命令成功時，它列印 `Successfully added marketplace: <name>`，市集的外掛程式在您下次開啟 `/plugin` 時出現在 **Discover** 標籤上，無需重新載入。如果失敗，請在 [外掛程式疑難排解](/docs/zh-TW/plugins/troubleshooting#add-a-marketplace) 中匹配錯誤訊息。

229

230<h3 id="add-a-marketplace-and-install-in-one-command">

231 新增市集並在一個命令中安裝

232</h3>

233

234若要從您尚未新增的市集安裝外掛程式，請在 Claude Code 工作階段中執行 `/plugin install` 並使用 `--marketplace` 命名市集來源。需要 Claude Code v2.1.275 或更新版本。

235

236```text theme={null}

237/plugin install deploy-helper --marketplace your-org/plugins

238```

239

240來源採用 [與 `/plugin marketplace add` 相同的形式](#add-a-marketplace)，例如 GitHub `owner/repo`、git URL 或本機路徑，除了它不能包含空格。單獨給出外掛程式名稱，不帶 `@marketplace` 後綴。

241

242如果您尚未新增該市集，Claude Code 會顯示它解析的來源並要求您在新增前確認。市集新增後，外掛程式的詳細資訊開啟，您選擇 [安裝範圍](#install-a-plugin)。如果來源與您已新增的市集相符，Claude Code 會跳過確認並在該市集中開啟外掛程式的詳細資訊。

243

244<h3 id="add-a-private-marketplace">

245 新增私人市集

246</h3>

247

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

249

250* **HTTPS**：您的 git 認證助手適用，因此您使用 `gh auth login`、macOS Keychain 或 `git-credential-store` 設定的存取有效。互動式提示被抑制，因此您從未驗證過的主機會失敗而不是要求密碼。

251* **SSH**：主機必須已在您的 `known_hosts` 檔案中，金鑰必須在沒有密碼提示的情況下工作，因為主機指紋和密碼提示也被抑制。

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

253

254當您執行 `/plugin install`、`/plugin marketplace update` 和 `claude plugin update` 時，相同的認證適用。

255

256在 GitHub Enterprise Server 主機上，請參閱 [GHES 上的外掛程式市集](/docs/zh-TW/github-enterprise-server#plugin-marketplaces-on-ghes) 以了解每個操作需要的認證。

257

258如果您的組織透過受管設定為您註冊市集，您不需要自己新增它。請參閱 [預先安裝和要求外掛程式](/docs/zh-TW/plugins/org#pre-install-and-require-plugins)。

259

260<h3 id="add-from-claude-ai">

261 從 claude.ai 新增市集

262</h3>

263

264在 [從您的 claude.ai 帳戶同步外掛程式](/docs/zh-TW/plugins/loading#synced-plugins) 的終端機工作階段中，claude.ai 也可以為您列出外掛程式市集，例如您的組織的外掛程式庫和您自己的 claude.ai 上傳。您透過其名稱而不是來源新增其中之一。從 claude.ai 新增市集需要 Claude Code v2.1.273 或更新版本。

265

266從 `/plugin` 面板或 shell 新增 claude.ai 市集：

267

268* **Inside a session**：執行 `/plugin` 並前往 **Marketplaces** 標籤，該標籤列出來自 claude.ai 的市集。在那裡選擇一個以新增它。

269* **From your shell**：執行 `claude plugin marketplace list`，它在 `From claude.ai:` 部分列印它們。然後執行 `claude plugin marketplace add` 並使用 `--claudeai` 旗標和清單中顯示的名稱。

270

271例如，此命令新增名為 `claudeai-organization-library` 的市集：

272

273```bash theme={null}

274claude plugin marketplace add --claudeai claudeai-organization-library

275```

276

277Claude Code 在本機名稱下註冊市集，該名稱以 `claudeai-` 開頭，源自 claude.ai 列出的名稱。例如，列為「Organization library」的市集變成 `claudeai-organization-library`。透過該名稱安裝其外掛程式，例如使用 `claude plugin install <plugin>@claudeai-organization-library`。

278

279如果您登出或登入不同的 claude.ai 組織，市集保持配置但不顯示外掛程式，您已從中安裝的外掛程式繼續載入。

280

281`From claude.ai:` 部分也可以列出透過 claude.ai 共享的基於 git 的市集，並為每個市集列印來源。透過該來源新增它們，如 [新增市集](#add-a-marketplace) 中所示，而不是使用 `--claudeai`。

282

283<h2 id="manage-installed-plugins">

284 管理已安裝的外掛程式

285</h2>

286

287`/plugin` 中的 **Installed** 標籤列出您的外掛程式，並提供啟用、停用、更新或卸載每個外掛程式的操作。在 Claude Code 工作階段中，執行 `/plugin` 並按 **Tab** 到達它，或執行 `/plugin enable`、`/plugin disable` 或 `/plugin uninstall` 以開啟面板並在那裡進行該變更。停用的外掛程式在清單底部的摺疊標題下分組。在清單上使用這些鍵：

288

289* 輸入以按名稱或描述篩選。

290* 按 **Space** 啟用或停用選定的外掛程式，按 **f** 將其加入最愛。

291* 按 **Enter** 開啟外掛程式的詳細資訊。那裡的選單提供 **Disable plugin** 或 **Enable plugin**、**Update now** 和 **Uninstall**。採用設定的外掛程式也提供 **Configure options**。

292

293標籤也可以在 **Managed** 範圍顯示外掛程式。您的組織透過 [受管設定](/docs/zh-TW/settings#settings-files) 安裝了這些，您無法在此啟用、停用或卸載它們。

294

295對於您的組織在 claude.ai 上要求的同步外掛程式，請參閱 [管理從 claude.ai 同步的外掛程式](#manage-plugins-synced-from-claude-ai)。

296

297當您關閉 `/plugin` 面板並在其中進行待處理變更時，Claude Code 為您執行 `/reload-plugins` 以套用它們。如果重新載入會 [使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，它會警告並改為保留變更待處理。執行 `/reload-plugins --force` 以無論如何套用它們。

298

299<h3 id="manage-plugins-synced-from-claude-ai">

300 管理從 claude.ai 同步的外掛程式

301</h3>

302

303`/plugin` 中的 **Installed** 標籤也列出 [從您的 claude.ai 帳戶同步的外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)，其來源為 `synced`。同步外掛程式在 Claude Code v2.1.273 或更新版本的終端機工作階段中出現。

304

305* **Enable or disable**：使用 **Installed** 標籤，除非您的組織將外掛程式標記為必需。

306* **Remove**：在 claude.ai 上關閉外掛程式。

307

308當 Claude Code 將新增、更新或移除的外掛程式同步到互動式工作階段時，您會看到 `Plugins changed. Run /reload-plugins to activate.` 執行 `/reload-plugins` 以在該工作階段中載入變更，或將其保留到下次啟動 Claude Code。

309

310<h3 id="uninstall-a-plugin-the-project-enables">

311 卸載專案啟用的外掛程式

312</h3>

313

314當您為此儲存庫的 `.claude/settings.json` 啟用的外掛程式選擇 **Uninstall** 時，無論是從 **Installed** 標籤還是使用 `/plugin uninstall`，Claude Code 會詢問是否為您停用它或為每個人卸載它：

315

316* **Disable for me**：按 **y**。Claude Code 在您的 `.claude/settings.local.json` 中為外掛程式寫入 `false` 並將其保留為專案安裝。

317* **Uninstall for everyone**：按 **u**。Claude Code 從共享 `.claude/settings.json` 移除外掛程式。

318

319<h3 id="see-what-an-installed-plugin-adds-to-your-sessions">

320 查看已安裝的外掛程式新增到您工作階段的內容

321</h3>

322

323在 shell 中，執行 `claude plugin details <name>` 以了解已安裝的外掛程式。`Always-on` 行是外掛程式在啟用它的每個工作階段中新增的令牌數，每個元件行顯示哪個技能或代理貢獻最多。有關完整輸出和每個數字的含義，請參閱 [測量外掛程式的成本](/docs/zh-TW/plugins/measure#measure-what-a-plugin-costs)。

324

325<h3 id="find-plugins-you-no-longer-use">

326 尋找您不再使用的外掛程式

327</h3>

328

329在 `/plugin` 的 **Installed** 標籤上，您自己安裝且最近未使用的外掛程式出現在 **Not used recently** 標題下，每個外掛程式的詳細資訊顯示 **Last used** 行。使用該標題和該行尋找仍新增啟動和內容成本的外掛程式，然後停用或卸載它們。

330

331<h3 id="plugins-with-dependencies">

332 具有依賴項的外掛程式

333</h3>

334

335外掛程式可以宣告它依賴的其他外掛程式。當您從市集安裝、停用或卸載這樣的外掛程式時，Claude Code 也會對這些依賴項進行操作：

336

337* **Install**：Claude Code 也在相同範圍安裝並啟用外掛程式的宣告依賴項。成功訊息列出它們。

338* **Enable**：Claude Code 也啟用已安裝但停用的外掛程式的依賴項。如果宣告的依賴項未安裝，啟用失敗，訊息告訴您先安裝它。

339* **Disable**：當另一個啟用的外掛程式仍需要您命名的外掛程式時，Claude Code 拒絕並列印以正確順序停用兩者的鏈式命令。

340* **Uninstall**：自動安裝的依賴項保留到您在 shell 中執行 `claude plugin prune` 為止；請參閱 [plugin prune](/docs/zh-TW/plugins/cli-reference#plugin-prune)。

341

342如果您改為使用 `--plugin-dir` 載入外掛程式，請參閱 [在本機測試外掛程式及其依賴項](/docs/zh-TW/plugins/dependencies#test-a-plugin-and-its-dependency-locally)。

343

344<h3 id="manage-plugins-from-your-shell">

345 從 shell 管理外掛程式

346</h3>

347

348您也可以在不啟動 Claude Code 工作階段的情況下管理外掛程式。在 shell 中，執行 `claude plugin install`、`enable`、`disable` 或 `uninstall` 作為普通終端機命令；它們變更 `/plugin` 面板所做的相同設定。每個都採用 `--scope` 以針對一個範圍，當您省略它時使用預設範圍：

349

350* `enable` 和 `disable` 作用於其設定已列出外掛程式的最具體範圍。

351* `install` 和 `uninstall` 作用於使用者範圍。

352

353例如，這些命令停用並重新啟用外掛程式，然後在專案範圍卸載它：

354

355```bash theme={null}

356claude plugin disable formatter@your-org

357claude plugin enable formatter@your-org

358claude plugin uninstall formatter@your-org --scope project

359```

360

361<h2 id="keep-plugins-updated">

362 保持外掛程式更新

363</h2>

364

365當外掛程式來自的市集啟用了自動更新時，外掛程式會自動更新。工作階段啟動後，Claude Code 重新整理這些市集並更新您從中安裝的外掛程式的磁碟副本。

366

367執行中的工作階段保持它已載入的版本。更新後，您會看到 `Plugin updated: <name> · Run /reload-plugins to apply`，下一個工作階段會自動載入新版本。

368

369這些是每種市集類型的自動更新預設值：

370

371* **On by default**：`claude-plugins-official` 和其他 [官方市集名稱](/docs/zh-TW/plugins/security#official-marketplace-names)（除了 `knowledge-work-plugins` 和 `first-party-plugins`）以及 [從 claude.ai 新增的市集](#add-from-claude-ai)。

372* **Off by default**：所有其他市集，包括社群市集、第三方市集和本機開發市集。

373

374有關自動更新何時執行、它跳過哪些外掛程式以及關閉它的環境變數，請參閱 [自動更新何時執行](/docs/zh-TW/plugins/loading#when-auto-update-runs)。

375

376<h3 id="turn-auto-update-on-or-off-for-a-marketplace">

377 為市集開啟或關閉自動更新

378</h3>

379

380在 Claude Code 工作階段中，執行 `/plugin` 並前往 **Marketplaces** 標籤。選擇市集，然後選擇 **Enable auto-update** 或 **Disable auto-update**。

381

382<h3 id="update-one-plugin-now">

383 立即更新一個外掛程式

384</h3>

385

386在工作階段中，在 `/plugin` 的 **Installed** 標籤上開啟外掛程式並選擇 **Update now**，或在 shell 中執行 `claude plugin update <plugin>@<marketplace>`。

387

388<h3 id="auto-update-from-a-private-marketplace">

389 從私人市集自動更新

390</h3>

391

392對於私人市集，請參閱 [背景自動更新對認證的處理](/docs/zh-TW/plugins/host-marketplace#what-background-auto-update-does-with-credentials) 以了解背景自動更新如何透過 SSH 和 HTTPS 驗證，以及 [外掛程式疑難排解](/docs/zh-TW/plugins/troubleshooting#add-a-marketplace) 以了解失敗時看到的訊息。

393

394<h2 id="manage-marketplaces">

395 管理市集

396</h2>

397

398`/plugin` 中的 **Marketplaces** 標籤列出您註冊的每個市集及其來源。選擇一個以瀏覽其外掛程式、更新其清單、開啟或關閉自動更新，或移除它。

399

400您也可以使用命令從 shell 或工作階段內列出、更新和移除市集：

401

402| Action | In your shell | Inside a session |

403| :----------------------------- | :---------------------------------------- | :---------------------------------- |

404| List marketplaces | `claude plugin marketplace list` | `/plugin marketplace list` |

405| Update a marketplace's listing | `claude plugin marketplace update <name>` | `/plugin marketplace update <name>` |

406| Remove a marketplace | `claude plugin marketplace remove <name>` | `/plugin marketplace remove <name>` |

407

408當您移除市集時，Claude Code 卸載您從中安裝的每個外掛程式，並從設定檔中移除其 `enabledPlugins` 項目。**Marketplaces** 標籤在要求您確認前命名這些外掛程式。

409

410<h2 id="next-steps">

411 後續步驟

412</h2>

413

414* [Anthropic 的市集](/docs/zh-TW/plugins/anthropic-marketplaces)：官方、社群和示範市集的差異以及在哪裡瀏覽每個市集

415* [外掛程式載入參考](/docs/zh-TW/plugins/loading)：為什麼外掛程式載入、未載入或在更新後未變更

416* [外掛程式安全性和信任](/docs/zh-TW/plugins/security)：在從您不認識的市集安裝外掛程式前要檢閱的內容

417* [外掛程式疑難排解](/docs/zh-TW/plugins/troubleshooting)：安裝和市集錯誤訊息及其修復

418* [建立外掛程式](/docs/zh-TW/plugins/create)：建立您自己的外掛程式

plugins/loading.md +424 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Plugin 載入參考

7> 追蹤 Claude Code 從何處載入每個 plugin，哪個設定檔決定是否載入，以及為什麼更新沒有改變任何內容。

9當 plugin 未載入、載入了與預期不同的副本，或未取得更新，且您想查看哪個來源、設定範圍或磁碟上的檔案決定了這一點時，請使用此頁面。它提供了 Claude Code 在工作階段啟動時和每次執行 `/reload-plugins` 時應用的規則。您也可以要求 Claude 閱讀此頁面並診斷您的設定。

11<Note>

12 這些情況涵蓋在其他頁面上：

14 * **安裝、啟用、停用和更新步驟**：請參閱 [安裝和管理 plugins](/docs/zh-TW/plugins/install)

15 * **您有特定的錯誤訊息**：請參閱 [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting)

16</Note>

18從 [檢查 plugin 達到哪個階段](#check-which-stage-a-plugin-reached) 開始，了解已安裝 plugin 通過的三個階段，或前往與您看到的內容相符的部分：

20* 您關閉的 plugin 仍然載入：[找出 plugin 在何處啟用](#find-where-a-plugin-is-enabled)

21* 更新沒有改變任何內容：[版本和更新](#versions-and-updates)

22* 您正在查看 `~/.claude/plugins/` 下的檔案：[在磁碟上找出 plugins](#find-plugins-on-disk)

23* `--plugin-dir` plugin 未載入，或載入了同名 plugin：[名稱衝突](#name-conflicts)

25<h2 id="check-which-stage-a-plugin-reached">

26 檢查 plugin 達到哪個階段

27</h2>

29`enabledPlugins` 項目通過多個階段成為您可以使用的 plugin：您的設定宣告它、Claude Code 將其提取到磁碟，以及執行中的工作階段載入它。當 plugin 的行為與設定檔建議的不符時，檢查它達到了哪個階段：

31* **已宣告，在設定中**：`enabledPlugins` 說明哪些 plugins 應該開啟，`extraKnownMarketplaces` 說明哪些市場應該存在。當您執行 `claude plugin marketplace add` 時，Claude Code 會將市場寫入您的使用者設定中的 `extraKnownMarketplaces` 以及磁碟

32* **已提取，在 `~/.claude/plugins/` 下的磁碟上**：Claude Code 已提取的記錄和提取的檔案本身：

33 * `known_marketplaces.json` 記錄每個 Claude Code 已提取的市場，包括其 `source`、`installLocation`、`lastUpdated` 和 `autoUpdate`。每個使用者有一個 `known_marketplaces.json`，因此您在一個專案中新增的市場在每個專案中都可用

34 * `installed_plugins.json` 記錄每個安裝及其 `scope`、`installPath` 和 `version`

35 * `cache/` 保存 plugin 檔案

36* **已載入，在執行中的工作階段中**：Claude Code 在啟動時或最後一次 `/reload-plugins` 時載入的 plugin 集合。對設定或磁碟的更改不會到達此層，直到您執行 `/reload-plugins` 或啟動新工作階段。這就是為什麼 `claude plugin update` 以 `Restart to apply changes.` 結尾，背景更新會提示您 `Run /reload-plugins to apply`

38<h3 id="plugins-and-marketplaces-that-aren’t-on-disk-at-session-start">

39 在工作階段啟動時不在磁碟上的 Plugins 和市場

40</h3>

42Plugins 在工作階段啟動時從 `installed_plugins.json` 和快取載入，無需使用網路。工作階段啟動後，Claude Code 在背景檢查宣告的市場：

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

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

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

49<h2 id="find-where-a-plugin-came-from">

50 找出 plugin 來自何處

51</h2>

53每個 plugin 都有形式為 `<name>@<origin>` 的 id，這是您在設定檔和 `claude plugin list --json` 中看到的。`@` 之後的部分告訴您 Claude Code 在何處找到 plugin：

55| ID 結尾 | Plugin 如何到達 | 如何開啟或關閉 |

56| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- |

57| `@<marketplace>` | 您從您新增的市場安裝了它 | 在設定檔中的 `enabledPlugins` 下設定 `"<name>@<marketplace>": true` 或 `false` |

58| `@inline` | 您使用 `--plugin-dir` 或 `--plugin-url` 啟動 Claude Code，設定了 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-TW/env-vars#variables)，或 Agent SDK 應用程式傳遞了 `plugins` 選項。它僅針對該工作階段載入 | 除非清單設定 `defaultEnabled: false` 或設定檔設定 `"<name>@inline": false`，否則工作階段開啟 |

59| `@skills-dir` | 您在 `~/.claude/skills/` 或專案的 `.claude/skills/` 下儲存了具有 `.claude-plugin/plugin.json` 的 plugin 目錄 | 清單的 `defaultEnabled`，除非設定檔將 `"<name>@skills-dir"` 設定為 `true` 或 `false` |

60| `@synced` | 您或您的組織為您的 claude.ai 帳戶開啟了它，Claude Code [下載了它](#synced-plugins) | 除非清單設定 `defaultEnabled: false` 或設定檔設定 `"<name>@synced": false`，否則開啟。您的組織標記為必需的 plugin 無論如何都會載入 |

62對於市場 plugin，`<name>` 是 `marketplace.json` 中的項目名稱；對於 `@inline` 和 `@skills-dir`，它是 plugin 清單中的 `name`。

64此表中的來源名稱是保留的，因此沒有市場可以命名為 `inline`、`skills-dir` 或 `synced`。

66<h3 id="entry-name-and-manifest-name">

67 項目名稱和清單名稱

68</h3>

70市場 plugin 有兩個名稱，它們可能不同：

72* **`marketplace.json` 中的項目名稱**：安裝和啟用金鑰。它是您在 `enabledPlugins` 中寫入的內容、快取目錄的命名依據，以及 `claude plugin list` 顯示的內容

73* **清單中的 `name`**：plugin 的元件命名空間所在的位置，以及 [名稱衝突](#name-conflicts) 比較的內容

75<h3 id="plugins-shared-through-a-repository">

76 透過儲存庫共享的 Plugins

77</h3>

79若要透過儲存庫共享 plugin，請在 `.claude/settings.json` 中的 `enabledPlugins` 下列出它，或將其放在 `.claude/skills/` 下。Claude Code 不掃描專案的 `.claude/plugins/` 目錄。

81雲端工作階段不會新增儲存庫在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 下列出的市場，因為這需要工作區信任對話框，雲端工作階段永遠不會顯示。

83專案範圍的技能目錄 plugin 僅從工作階段 [主要工作目錄](/docs/zh-TW/permissions#working-directories) 的 `.claude/skills/` 載入，且僅在您接受該資料夾的 [工作區信任對話框](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 後。它不會 [搜尋父目錄直到儲存庫根目錄](/docs/zh-TW/skills#discovery-from-parent-and-nested-directories) 的方式，就像純技能和命令一樣。如果您從子目錄啟動，儲存庫根目錄的 plugin 不會載入。改為從儲存庫根目錄啟動，或 [使用 `/cd` 將工作階段移到那裡](/docs/zh-TW/permissions#move-the-session-to-another-directory)（v2.1.246 或更新版本）。

85專案範圍的 plugin 被簽入儲存庫，並到達複製它的每個協作者。因為該內容來自儲存庫而不是來自您，它僅在應用於 `.claude/settings.json` 中專案允許規則的相同信任檢查後載入。信任父資料夾或使用 `-p` 執行是不夠的。執行程式碼的元件受到進一步限制：

87* 它宣告的 MCP 伺服器通過 [相同的每個伺服器核准](/docs/zh-TW/mcp) 作為專案 `.mcp.json`

88* 它宣告為 [MCP 套件](/docs/zh-TW/plugins/manifest-reference#mcpservers) 的 MCP 伺服器、`.mcpb` 或 `.dxt` 檔案，或來自 plugin 目錄外的檔案被跳過。在 plugin 目錄內內聯或在 `.mcp.json` 中宣告它們

89* [背景監視器](/docs/zh-TW/plugins/components#monitors) 不載入

91個人範圍的 plugins 沒有這些限制。

93如需如何編寫 `--plugin-dir` 和技能目錄 plugins，請參閱 [建立 plugins](/docs/zh-TW/plugins/create)。

95<h3 id="synced-plugins">

96 從 claude.ai 同步的 Plugins

97</h3>

99您為 claude.ai 帳戶開啟的 plugin 也會在 Claude Code 中載入，與您從市場安裝的 plugins 並排。這包括您的組織為其成員開啟的 plugins。這些 plugins 中的每一個都以 `<name>@synced` 載入，沒有市場，也沒有 [安裝記錄](#check-which-stage-a-plugin-reached)。

100

101在終端工作階段中，同步 plugin 的技能、代理、hooks、MCP 伺服器和 LSP 伺服器都會載入，具有與您安裝的市場 plugin 相同的信任。

102

103如需 Cowork 載入的元件，請參閱 claude.com 上的 [claude.ai 和 Cowork 中的 Plugins](https://claude.com/docs/plugins/overview)。

104

105同步 plugins 在 Cowork 工作階段和您使用 claude.ai 帳戶登入的終端工作階段中載入：

106

107* **[Cowork](https://claude.com/product/cowork)**：Claude Code 在工作階段啟動時將它們下載到工作階段自己的環境中

108* **終端工作階段**：每次您啟動 Claude Code 時，它在背景同步一次，下載新的和更新的 plugins，並移除您或您的組織關閉的 plugins。終端工作階段中的同步需要 Claude Code v2.1.273 或更新版本

109

110<h4 id="sync-timing-in-terminal-sessions">

111 終端工作階段中的同步時機

112</h4>

113

114因為終端同步在背景執行，它可能在您的工作階段啟動後完成。當它在互動式工作階段中新增、更新或移除同步 plugin 時，您會看到 `Plugins changed. Run /reload-plugins to activate.` 執行 `/reload-plugins` 以在該工作階段中載入變更，或將其留待下次啟動 Claude Code 時。

115

116如果您在工作階段執行時在 claude.ai 上啟用 plugin，該 plugin 會在您下次啟動 Claude Code 時下載。

117

118<h4 id="sign-in-requirements-for-terminal-sync">

119 終端同步的登入要求

120</h4>

121

122在您的終端中，plugins 僅在您使用 claude.ai 帳戶登入的工作階段中同步。

123

124如果您在較早版本的 Claude Code 上登入，該登入不涵蓋 plugins，直到 Claude Code 在背景更新它。若要更快獲得存取權，請再次執行 `/login`。Plugin 同步然後在您下次啟動 Claude Code 時開始。

125

126<h4 id="control-which-synced-plugins-load">

127 控制哪些同步 plugins 載入

128</h4>

129

130您可以一次關閉一個同步 plugin，除了您的組織要求的 plugin，或關閉機器上的每個同步 plugin：

131

132* **一個 plugin**：在您的殼層中執行 `claude plugin disable <name>@synced`，工作階段中的 `/plugin` **Installed** 標籤都在您的使用者級別 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 中儲存 `"<name>@synced": false`。若要在每個環境中將 plugin 保留在專案之外，在專案的已提交 `.claude/settings.json` 中設定相同的金鑰

133* **機器上的每個同步 plugin**：在您的使用者設定中設定 [`syncClaudeAiPlugins`](/docs/zh-TW/settings-reference#syncclaudeaiplugins) 為 `false`，或您的組織在 [受管設定](/docs/zh-TW/managed-settings) 中設定它。Claude Code 停止下載，下次啟動時，它將已同步的 plugins 移到 `~/.claude/plugins/.trash/`，不再載入它們。如果您的組織在 claude.ai 上關閉技能，plugins 也會停止同步

134* **您的組織要求的 plugin**：您的組織在 claude.ai 上標記為必需的 plugin 即使您之前停用它也會載入。`claude plugin disable` 拒絕它，顯示 `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.`，`claude plugin list` 將其標記為 `required by your org`

135

136如需在 claude.ai 上移除 plugin，請參閱 [管理已安裝的 plugins](/docs/zh-TW/plugins/install#manage-installed-plugins)。

137

138<h2 id="find-where-a-plugin-is-enabled">

139 找出 plugin 在何處啟用

140</h2>

141

142您可以在六個來源中的任何一個設定 `enabledPlugins` 項目。該表從最低優先順序到最高列出它們，以及每個適用於誰。如需設定檔本身，請參閱 [設定檔和它們影響的人](/docs/zh-TW/settings#where-settings-live)。

143

144| 來源 | 您在何處設定它 | 到達 |

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

146| `--add-dir` | 您使用 `--add-dir` 傳遞的目錄中的 `.claude/settings.json` 或 `.claude/settings.local.json` | 僅此工作階段。只有 `true` 值有效果，每個其他來源都會覆蓋它 |

147| `user` | `~/.claude/settings.json` | 您，在每個專案中 |

148| `project` | `.claude/settings.json` | 複製儲存庫的每個人 |

149| `local` | `.claude/settings.local.json` | 您，僅在此儲存庫中 |

150| `flag` | 您在啟動時傳遞的 `--settings` 值 | 僅此工作階段 |

151| `managed` | [受管設定](/docs/zh-TW/managed-settings) | 政策涵蓋的每個使用者。`true` 強制啟用，`false` 阻止，沒有其他來源覆蓋它們 |

152

153這些來源逐個金鑰合併。對於每個 plugin id，適用的值是來自提及該 id 的最高優先順序來源的值。不提及該 id 的來源會保留來自較低優先順序來源的值。

154

155<h3 id="disabled-in-user-settings-but-still-loads">

156 在使用者設定中停用但仍然載入

157</h3>

158

159如果您在 `~/.claude/settings.json` 中將 plugin 設定為 `false`，但它仍然載入，較高優先順序來源中的 `true` 會覆蓋它。plugin 在 `claude plugin list` 和 `/plugin` 中的行顯示 `Disabled in ~/.claude/settings.json but still loads — project settings enable it, which overrides your user setting`。該訊息命名覆蓋您的來源：`project`、`project, gitignored`（針對 `.claude/settings.local.json`）、`cli flag` 或 `managed`。

160

161若要選擇退出您機器上的專案啟用 plugin，在 `.claude/settings.local.json` 中將 id 設定為 `false`，其優先順序高於專案檔案。

162

163<h3 id="enabled-in-project-settings-but-not-installed">

164 在專案設定中啟用但未安裝

165</h3>

166

167當 plugin 的唯一 `true` 在專案的 `.claude/settings.json` 中時，Claude Code 不會在未安裝它的機器上提取它，除非其市場項目具有 [相對路徑來源](/docs/zh-TW/plugins/marketplace-reference#plugin-sources) 或 [種子目錄](/docs/zh-TW/plugins/org#seed-containers-and-ci) 已經保存它。相反，`/plugin` **Errors** 標籤顯示 `Plugin "<name>" is enabled in project settings but isn't installed here`。

168

169相對路徑 plugin 不需要安裝記錄，因為它從市場本身載入。

170

171Claude Code 僅當以下來源之一將其設定為 `true` 時才提取具有外部來源的 plugin：

172

173* 您的使用者設定

174* git 不追蹤的 `.claude/settings.local.json`

175* `--settings` 旗標

176* 受管設定

177

178<h2 id="find-plugins-on-disk">

179 在磁碟上找出 plugins

180</h2>

181

182Claude Code 在一個 plugins 根目錄下保存 plugin 檔案和狀態記錄，該目錄是 `~/.claude/plugins`，除非您設定 [`CLAUDE_CODE_PLUGIN_CACHE_DIR`](/docs/zh-TW/env-vars)。表中的每個路徑都相對於該根目錄。

183

184| 路徑 | 它保存什麼 |

185| :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

186| `cache/<marketplace>/<plugin>/<version>/` | 市場 plugin 的每個已安裝版本一個目錄。`<plugin>` 是市場項目名稱，`<version>` 是 [已解決的版本](#versions-and-updates)。`${CLAUDE_PLUGIN_ROOT}` 指向此目錄 |

187| `data/<plugin-id>/` | plugin 的持久目錄，公開為 `${CLAUDE_PLUGIN_DATA}`。如需如何形成 `<plugin-id>`，請參閱 [路徑變數和持久資料](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)。Claude Code 在 plugin 元件首次使用它時建立它，並在更新中保留它。當您從其最後一個範圍卸載 plugin 時，Claude Code 會刪除它，除非您傳遞 `--keep-data` |

188| `marketplaces/<name>/` | 從 GitHub、另一個 Git 主機或 URL 新增的市場的複製或下載。從本地 `file` 或 `directory` 來源新增的市場在此處沒有副本，其 `known_marketplaces.json` 中的 `installLocation` 是您提供的路徑 |

189| `synced/` | Claude Code [從您的 claude.ai 帳戶同步的 plugins](#synced-plugins) |

190| `.trash/` | claude.ai 同步移除的 plugins，例如在您在 claude.ai 上關閉一個或停止同步後 |

191| `installed_plugins.json` 和 `known_marketplaces.json` | Claude Code 已安裝的記錄和已提取的市場，在 [檢查 plugin 達到哪個階段](#check-which-stage-a-plugin-reached) 下描述。[在 claude.ai 上託管的市場](/docs/zh-TW/plugins/install#add-from-claude-ai) 改為記錄在 `known_marketplaces_claudeai.json` 中 |

192| `flagged-plugins.json` | Claude Code 卸載的 plugins，因為其市場將其除名。它們出現在 `/plugin` 的 **Flagged** 部分；請參閱 [託管市場](/docs/zh-TW/plugins/host-marketplace) |

193

194因為 `${CLAUDE_PLUGIN_ROOT}` 指向版本目錄，plugin 的根路徑隨著每個版本而變化。改為在 `${CLAUDE_PLUGIN_DATA}` 中保存 plugin 的持久檔案。

195

196<h3 id="in-place-and-copied-plugins">

197 就地和複製的 plugins

198</h3>

199

200Claude Code 根據 plugins 的來源，從您保存它們的位置就地載入某些 plugins，並將其餘的複製到快取中：

201

202* **`--plugin-dir` 和技能目錄 plugins**：目錄就地載入，永遠不會被複製。`--plugin-url` 存檔或 `--plugin-dir` `.zip` 首先被提取到工作階段臨時目錄中

203* **您從本地目錄新增的市場中的相對路徑 plugins**：plugin 從其在市場資料夾內的路徑就地載入。您對來源目錄的編輯在下次工作階段啟動或 `/reload-plugins` 時生效，您無需增加版本。plugin 的 hook 程序和 MCP 和 LSP 伺服器接收指向來源目錄的 `CLAUDE_PLUGIN_ROOT`。如需其 Node.js 套件依賴項，請參閱 [依賴項安裝何時執行](#when-the-dependency-install-runs)

204* **[連結模式](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source) 中的 `command` 來源 plugins**：命令列印的目錄通過快取項目中的連結就地載入

205* **每個其他市場 plugin**：Claude Code 在安裝時將 plugin 複製到 `cache/<marketplace>/<plugin>/<version>/` 中並從該副本載入。plugin 目錄外的檔案不被複製，因此當 plugin 內的指令碼讀取 plugin 根目錄上方的路徑（例如 `../shared`）時，它找不到它們

206

207<h3 id="paths-that-escape-the-plugin-directory">

208 逃逸 plugin 目錄的路徑

209</h3>

210

211無論 plugin 就地載入還是從快取副本載入，Claude Code 都不允許它宣告其自己目錄外的元件。它拒絕解決為 plugin 根目錄外的元件路徑，無論路徑是在 `plugin.json` 還是市場項目中宣告的：

212

213* **指向 plugin 外部的路徑，如寫入的那樣**，例如 `../shared-utils`

214* **導致 plugin 外部的符號連結**，除了 [一個市場內 plugins 之間的連結](/docs/zh-TW/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)

215* **在 macOS 和 Linux 上，路徑中任何地方包含反斜杠的路徑**，即使路徑保留在 plugin 內。因此使用反斜杠路徑宣告的元件僅在 Windows 上載入，因此使用正斜杠編寫元件路徑，例如 `./commands/deploy.md`

216

217被拒絕的路徑顯示為 [`path escapes plugin directory`](/docs/zh-TW/errors#path-escapes-plugin-directory) 錯誤，plugin 載入時不包含該元件。

218

219<h3 id="cleanup-of-previous-versions">

220 舊版本的清理

221</h3>

222

223當您更新或卸載 plugin 時，Claude Code 將 `.orphaned_at` 標記寫入舊版本目錄。它在 14 天後的背景清理中移除該目錄，因此已載入舊版本的工作階段繼續執行。

224

225掃描僅在 `installed_plugins.json` 記錄至少一個安裝時執行。卸載最後一個 plugin 後，孤立目錄保留，直到您安裝另一個。

226

227<h3 id="node-js-package-dependencies">

228 Node.js 套件依賴項

229</h3>

230

231當 Claude Code 將 plugin 複製到快取時，它也會在那裡安裝 plugin 的 Node.js 套件依賴項，以便 plugin 的 hooks 和 MCP 伺服器可以載入它們。

232

233本部分涵蓋 plugin 在其自己的 `package.json` 中宣告的 npm 和 Bun 套件。對於依賴其他 plugins 的 plugins，請參閱 [plugin 依賴項版本](/docs/zh-TW/plugins/dependencies)。

234

235<h4 id="when-the-dependency-install-runs">

236 依賴項安裝何時執行

237</h4>

238

239Claude Code 在每次建立複製版本目錄時在其中執行安裝：

240

241* 當您安裝 plugin 時

242* 當 Claude Code 將 plugin 更新到新版本時

243* 在工作階段啟動時，當已啟用 plugin 尚未快取時，例如在新機器上

244

245對於從本地目錄市場 [就地載入](#in-place-and-copied-plugins) 的相對路徑 plugin，Claude Code 不會將依賴項安裝到來源目錄中。自己在那裡安裝它們，或從 hook 安裝到 [`${CLAUDE_PLUGIN_DATA}`](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)。

246

247安裝僅在 plugin 的根目錄同時包含 `package.json` 和支援的鎖定檔案時執行。鎖定檔案決定 Claude Code 執行的命令：

248

249| 鎖定檔案 | 命令 |

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

251| `bun.lock` 或 `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |

252| `npm-shrinkwrap.json` 或 `package-lock.json` | `npm ci --ignore-scripts` |

253

254如果 plugin 包含多個這些鎖定檔案中的一個，Claude Code 使用第一個匹配項，按順序檢查：`bun.lock`、`bun.lockb`、`npm-shrinkwrap.json`、`package-lock.json`。

255

256Claude Code 跳過 Yarn 和 pnpm 鎖定檔案以及 Bun 鎖定檔案旁邊的 `bunfig.toml` 的安裝：

257

258* 如果您的 plugin 只有 `yarn.lock` 或 `pnpm-lock.yaml`，請將其替換為 npm 鎖定檔案

259* 如果 `bunfig.toml` 在 Bun 鎖定檔案的同一目錄中，移除 `bunfig.toml`，或將 Bun 鎖定檔案替換為 npm 鎖定檔案

260

261包含 npm 鎖定檔案以到達最多使用者。Claude Code 從使用者的 PATH 執行匹配的鎖定檔案的套件管理器，如果缺少該套件管理器，不會嘗試其他鎖定檔案。

262

263對於透過 npm 來源分發的 plugin，使用 `npm-shrinkwrap.json`，因為 npm 從已發佈的套件中排除 `package-lock.json`。

264

265<h4 id="limits-on-the-dependency-install">

266 依賴項安裝的限制

267</h4>

268

269Claude Code 限制此依賴項安裝，以便 plugin 或其套件中的任何程式碼在安裝期間不執行，並限制其執行時間：

270

271* **凍結解決**：Bun 和 npm 安裝鎖定檔案精確固定的內容，當 `package.json` 和鎖定檔案不同意時失敗而不是重新解決版本

272* **無生命週期指令碼**：`--ignore-scripts` 防止 `preinstall`、`install` 和 `postinstall` 指令碼執行，因此在這些指令碼中建立原生模組的依賴項在此安裝期間下載但不編譯

273* **60 秒超時**：Claude Code 停止執行超過 60 秒的安裝並將其視為失敗

274

275Claude Code 在此依賴項安裝之前提取 npm 來源 plugin，套件自己的安裝指令碼在提取期間不執行。請參閱 [npm plugin 來源](/docs/zh-TW/plugins/marketplace-reference#npm-plugin-source)。

276

277您無法關閉自動安裝。沒有設定或環境變數停用它。

278

279在受限網路中，請參閱 [網路存取要求](/docs/zh-TW/network-config#network-access-requirements) 以允許的主機。

280

281<h4 id="when-the-dependency-install-fails-or-is-skipped">

282 依賴項安裝失敗或被跳過時

283</h4>

284

285失敗或跳過的安裝永遠不會阻止 plugin，每種情況都留下不同的跡象：

286

287* 失敗的安裝或因 Yarn 或 pnpm 鎖定檔案或 `bunfig.toml` 而跳過的安裝在 `claude --debug` 輸出中顯示為警告

288* 具有 `package.json` 和無鎖定檔案的 plugin 被跳過，沒有日誌項目

289* 超時的安裝可以在快取副本中留下部分 `node_modules` 樹

290

291當自動安裝無法提供依賴項時，從 hook 安裝到 [持久資料目錄](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)。這包括需要其生命週期指令碼建立的套件、Python 依賴項和使用 Yarn 或 pnpm 鎖定的 plugins。

292

293<h2 id="versions-and-updates">

294 版本和更新

295</h2>

296

297如果 plugin 的作者推送了新提交，`claude plugin update` 列印 `<name> is already at the latest version (<version>).`，Claude Code 為 plugin 計算的版本未變更，因此磁碟上沒有任何變更。

298

299Claude Code 為它安裝的每個 plugin 計算版本，這就是它如何檢測更新的方式。`claude plugin update` 和背景自動更新再次計算版本，當它與 `installed_plugins.json` 記錄的內容匹配時跳過 plugin。

300

301版本也命名 plugin 的快取目錄。

302

303固定 `"version"` 的清單是計算的版本在提交中保持相同的一種方式。請參閱 [Claude Code 如何計算版本](#how-claude-code-computes-the-version) 以了解解決順序。

304

305從本地目錄市場 [就地載入](#in-place-and-copied-plugins) 的 plugin 在每次工作階段啟動時載入其當前來源檔案，無論其版本字串說什麼。對於從 [在 claude.ai 上託管的市場](/docs/zh-TW/plugins/install#add-from-claude-ai) 的 plugin，claude.ai 為 plugin 記錄的版本是其版本，清單的 `version` 不被讀取。

306

307<h3 id="how-claude-code-computes-the-version">

308 Claude Code 如何計算版本

309</h3>

310

311對於您按來源新增的市場，Claude Code 按 plugin 市場項目的 `source` 類型選擇規則。[市場參考](/docs/zh-TW/plugins/marketplace-reference#plugin-sources) 列出來源類型。對於該列表中除 `command` 外的每個來源類型：

312

3131. plugin 清單中的 `version` 欄位首先出現

3142. 然後 plugin 市場項目中的 `version` 欄位

3153. 當都未設定時，版本來自來源類型：

316

317| 來源類型 | 未設定 `version` 欄位時的版本 |

318| :------------------------------- | :----------------------------------------------------- |

319| `github`、`url` 或 `git-subdir` | 來源的提交 SHA，縮短為 12 個字元。`git-subdir` 版本也帶有子目錄路徑的雜湊 |

320| `archive` | SHA-256 摘要，縮短為 12 個字元：市場項目中的 `sha256` 固定，或沒有固定時下載檔案的摘要 |

321| Git 託管市場內的相對路徑 | 已安裝目錄的提交 SHA |

322| 本地目錄，當 plugin 目錄和其市場都不是 git 儲存庫時 | `unknown` |

323| `npm` | `unknown` |

324

325Claude Code 不從包含安裝路徑的儲存庫（例如 git 管理的 `~/.claude`）取得版本。

326

327對於 `command` 來源，Claude Code 始終從命令產生的內容衍生版本：其自己的 12 字元雜湊，或當清單設定一個時 `<manifest version>-<hash>`。市場項目的 `version` 對於命令來源被忽略。如需雜湊涵蓋的內容，請參閱 [複製模式和連結模式](/docs/zh-TW/plugins/marketplace-reference#copy-mode-and-link-mode)。

328

329因為清單首先出現，固定 `"version": "1.0.0"` 的清單將每個使用者保留在快取副本上，直到其作者更改字串，無論他們推送多少提交。若要讓使用者改為追蹤提交，請從清單和項目中都省略 `version`。[託管市場](/docs/zh-TW/plugins/host-marketplace) 涵蓋哪個選擇適合哪個發佈設定。

330

331<h3 id="when-claude-code-refreshes-a-marketplace-before-an-install">

332 Claude Code 何時在安裝前重新整理市場

333</h3>

334

335當您安裝 plugin 時，Claude Code 在其市場目錄的本地副本中查找它。您可以在工作階段中執行 `/plugin install` 或在殼層中執行 `claude plugin install`，並使用或不使用其市場命名 plugin。該表顯示這些組合中哪些重新整理本地副本。

336

337| Plugin 名稱 | 命令 | Claude Code 重新整理什麼 |

338| :----------------- | :------------------------------------------ | :------------------ |

339| `name@marketplace` | `/plugin install` 或 `claude plugin install` | 查找前的命名市場 |

340| 僅 `name` | `/plugin install` | 僅具有自動更新的市場，且僅在查找失敗後 |

341| 僅 `name` | `claude plugin install` | 無。它讀取快取的目錄而不重新整理 |

342

343`name@marketplace` 安裝前的重新整理不取決於市場的自動更新設定或 `DISABLE_AUTOUPDATER`。

344

345當重新整理失敗時，安裝從快取目錄進行，`claude plugin install` 報告 `marketplace not refreshed`。

346

347Claude Code 在以下情況下跳過 `name@marketplace` 安裝前的重新整理：

348

349* 市場從本地 `file` 或 `directory` 來源新增，或在設定中內聯定義，具有 [`settings` 來源](/docs/zh-TW/settings-reference#extraknownmarketplaces)

350* [種子目錄](/docs/zh-TW/env-vars) 提供市場

351* Claude Code 在過去 30 秒內重新整理了市場

352* 您設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

353* [受管設定](/docs/zh-TW/plugins/org#restrict-what-users-can-install) 阻止市場，在這種情況下 Claude Code 也拒絕安裝

354

355<h3 id="when-auto-update-runs">

356 自動更新何時執行

357</h3>

358

359在互動式工作階段中，在您傳送第一條訊息後，Claude Code 等待最多十分鐘的隨機延遲。然後它重新整理每個啟用自動更新的市場，並更新從它們在磁碟上安裝的 plugins。

360

361執行中的工作階段保留它載入的版本，您會看到 `Plugin updated: <name> · Run /reload-plugins to apply`。無論您是否重新載入，新版本在您下次啟動時載入。

362

363<h4 id="which-marketplaces-and-plugins-auto-update">

364 哪些市場和 plugins 自動更新

365</h4>

366

367市場是否自動更新遵循首先設定的：

368

3691. **其 `extraKnownMarketplaces` 項目中的 `autoUpdate`** 在設定檔中

3702. **其 `known_marketplaces.json` 項目中的 `autoUpdate`**，`/plugin` **Marketplaces** 下的 **Enable auto-update** 切換寫入。當設定檔也在 `extraKnownMarketplaces` 下宣告市場時，切換也將 `autoUpdate` 寫入該設定項目

3713. **預設**：對於 Anthropic 的官方市場（例如 `claude-plugins-official`）開啟，對於 `knowledge-work-plugins` 和 `first-party-plugins` 關閉，對於 [從 claude.ai 新增的市場](/docs/zh-TW/plugins/install#add-from-claude-ai) 開啟，對於每個其他市場關閉

372

373如果您設定 `DISABLE_UPDATES=1`、`DISABLE_AUTOUPDATER=1` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`，整個傳遞關閉，**Enable auto-update** 切換隱藏，除非您也設定 `FORCE_AUTOUPDATE_PLUGINS=1`。[環境變數參考](/docs/zh-TW/env-vars) 涵蓋每個變數的更廣泛效果。

374

375自動更新也跳過其市場項目宣告 `headersHelper` 的 plugin。[拒絕命令而不是詢問的安裝和更新](/docs/zh-TW/plugins/host-marketplace#installs-and-updates-that-refuse-the-command-instead-of-asking) 解釋何時此類 plugin 出現在 `/plugin` **Errors** 標籤中以及如何從那裡更新它。

376

377當複製的 plugin 在工作階段中期更新時，hook 命令、監視器、MCP 伺服器和 LSP 伺服器繼續使用舊版本的路徑。執行 `/reload-plugins` 以將 hooks、MCP 伺服器和 LSP 伺服器切換到新路徑。監視器需要工作階段重新啟動。

378

379<h3 id="when-a-command-source-re-runs">

380 何時命令來源重新執行

381</h3>

382

383具有 `command` 來源的 Plugins 不等待 [自動更新傳遞](#when-auto-update-runs)。列印的目錄反映工具在命令執行時的狀態，因此 Claude Code 在以下時間再次執行 [您接受的命令](/docs/zh-TW/plugins/host-marketplace#change-the-command-of-a-command-source)：

384

385* 每次您安裝或更新 plugin 時

386* 每個已啟用命令來源 plugin 每個工作階段一次，在工作階段啟動後不久在背景中。此執行不取決於市場的自動更新設定或 `DISABLE_AUTOUPDATER`

387* 在啟動或 `/reload-plugins` 時，當已啟用 plugin 的已安裝版本在 plugin 快取中遺失時

388

389當您設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 時，Claude Code 跳過兩個背景執行。明確安裝和更新仍然使用該變數集執行命令。

390

391當命令的雜湊輸出已變更時，Claude Code 將結果安裝為新版本，並在執行中的互動式工作階段中重新載入它，切換 [`/reload-plugins` 切換的相同元件](/docs/zh-TW/plugins/cli-reference#reload-plugins)。您會看到 plugin 已重新載入的通知。

392

393如果就地重新載入會使工作階段的提示快取失效，Claude Code 改為提示您執行 `/reload-plugins`，它 [警告快取成本並在使用 `--force` 重新執行時應用](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)。

394

395<h2 id="name-conflicts">

396 名稱衝突

397</h2>

398

399當來自不同來源的已啟用 plugins 共享清單名稱時，此順序決定哪一個載入，從最高優先順序到最低：

400

4011. 其 id 出現在受管設定 `enabledPlugins` 中的 plugin，如 `true` 或 `false`。其清單名稱與 id 的名稱部分匹配的 `--plugin-dir` 副本不被載入，您會看到 `--plugin-dir copy of "<name>" ignored: plugin is locked by managed settings`

4022. 已啟用的 `--plugin-dir`、`--plugin-url` 或 `CLAUDE_CODE_PLUGIN_DIRS` plugin。它替換同名的已安裝市場 plugin 或技能目錄 plugin：

403 * **已安裝的市場 plugin**：無聲替換。`claude plugin list` 仍然顯示市場行為已啟用，因為該行反映您的設定。只有當您使用 `--debug` 啟動時 Claude Code 在 `~/.claude/debug/` 下寫入的日誌記錄 `Plugin "<name>" from --plugin-dir overrides installed version`

404 * **技能目錄 plugin**：替換為 `/plugin` **Errors** 標籤行，讀取 `Not loaded — the name "<name>" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence`

4053. 已安裝的市場 plugin。同名的技能目錄 plugin 獲得相同的 `Not loaded` 行，命名已安裝的 plugin

4064. 技能目錄 plugin。在這兩者之間，`~/.claude/skills/` 下的副本載入，專案的 `.claude/skills/` 副本被丟棄，帶有一行說明哪個路徑遮蔽了它

4075. 從 claude.ai [同步的 plugin](#synced-plugins)。當來自任何其他來源的已啟用 plugin 與其名稱匹配時，Claude Code 載入該 plugin 並報告同步副本未載入。若要改為使用 claude.ai 副本，停用您自己的副本

408

409因為順序比較清單名稱，名為 `hello-plugin` 的 `--plugin-dir` plugin 在該 plugin 的清單也說 `"name": "hello-plugin"` 時替換 `hello@example-marketplace`。

410

411<h3 id="keep-a-session-only-plugin-from-loading">

412 防止工作階段專用 plugin 載入

413</h3>

414

415若要防止 `--plugin-dir` plugin 遮蔽任何內容，或在父程序為您傳遞旗標時關閉一個，在任何設定檔中將其 id 設定為 `false`。對於清單名稱為 `hello-plugin` 的 plugin，項目是 `"enabledPlugins": {"hello-plugin@inline": false}`。停用的工作階段專用 plugin 不遮蔽，因此市場或技能目錄副本改為載入。

416

417<h2 id="next-steps">

418 後續步驟

419</h2>

420

421* [安裝和管理 plugins](/docs/zh-TW/plugins/install)：安裝、啟用、停用和更新步驟本身

422* [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting)：按產生它們的階段的錯誤訊息

423* [Plugin 命令參考](/docs/zh-TW/plugins/cli-reference)：此頁面上命名的旗標和命令

424* [為您的組織管理 plugins](/docs/zh-TW/plugins/org)：強制啟用或阻止 plugins 的受管設定

plugins/manifest-reference.md +710 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Plugin manifest 參考

7> plugin.json 的完整參考：每個欄位的類型和預設值、接受的路徑形式，以及 userConfig 和環境變數架構。

9Plugin manifest 是位於 plugin 的 `.claude-plugin/` 目錄中的 `plugin.json` 檔案。它包含 plugin 的中繼資料和 Claude Code 提示使用者輸入的 [`userConfig`](#user-configuration) 值。它也宣告任何您內聯定義或保留在其[預設位置](#standard-layout)之外的元件。

11本參考適用於 plugin 建立者，以及將元件欄位放在 marketplace 項目中的 marketplace 擁有者。

13<Note>

14 這些情況涵蓋在其他頁面上：

16 * **學習建立 plugin**：從[建立 plugin](/docs/zh-TW/plugins/create)開始

17 * **每個元件在執行時的作用**：請參閱 [Plugin 元件](/docs/zh-TW/plugins/components)

18</Note>

20從符合您要查詢內容的部分開始：

22* 一個欄位：[欄位表](#fields)提供每個欄位的類型、是否必需、其預設值和接受的內容。[路徑規則](#path-rules)涵蓋 `./` 前綴和每個元件路徑的包含

23* 一個 `userConfig` 選項或一個 `channels` 項目：[使用者設定](#user-configuration)和[頻道](#channels)架構

24* `${CLAUDE_PLUGIN_ROOT}` 或 plugin 可以參考的另一個變數：[環境變數](#environment-variables)

25* 每個元件的檔案位置：[標準配置](#standard-layout)

26* 來自 `claude plugin validate` 的訊息：[疑難排解頁面](/docs/zh-TW/plugins/troubleshooting)列出每條訊息及其修正，並連結到本頁的相關部分

28<h2 id="manifest-file">

29 Manifest 檔案

30</h2>

32manifest 是選用的。沒有它，Claude Code 會載入它在[標準配置](#standard-layout)中找到的元件。然後 plugin 名稱來自 marketplace 項目，或在您使用 `--plugin-dir` 載入 plugin 時來自目錄名稱。

34當您想要中繼資料、預設目錄外的元件、`userConfig` 或內聯元件定義時，請寫入 manifest。

36將 manifest 儲存在 plugin 根目錄下的 `.claude-plugin/plugin.json`。將所有其他 plugin 檔案放在 plugin 根目錄，而不是 `.claude-plugin/` 內。這包括 `skills/`、`commands/` 和 `hooks/`。

38以下範例設定[欄位表](#fields)中的大多數鍵。它在包含每個參考路徑的 plugin 目錄中通過驗證。

40```json theme={null}

41{

42 "name": "deploy-tools",

43 "displayName": "Deploy Tools",

44 "version": "1.2.0",

45 "description": "Deployment commands, a review agent, and a status monitor",

46 "author": {

47 "name": "Example Team",

48 "email": "dev@example.com",

49 "url": "https://example.com"

50 },

51 "homepage": "https://example.com/docs/deploy-tools",

52 "repository": "https://github.com/example/deploy-tools",

53 "license": "MIT",

54 "keywords": ["deployment", "ci"],

55 "defaultEnabled": true,

56 "dependencies": ["secrets-vault"],

57 "metadata": { "catalogId": "cat-123" },

58 "skills": ["./extra-skills/"],

59 "commands": {

60 "status": {

61 "source": "./commands/status.md",

62 "description": "Show the current deployment status"

63 },

64 "about": {

65 "content": "Explain what the deploy-tools plugin provides.",

66 "description": "Describe this plugin"

67 }

68 },

69 "agents": ["./agents/reviewer.md"],

70 "hooks": "./config/extra-hooks.json",

71 "mcpServers": {

72 "deploy-api": {

73 "command": "node",

74 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]

75 }

76 },

77 "lspServers": "./.lsp.json",

78 "outputStyles": "./styles/",

79 "experimental": {

80 "themes": "./themes/",

81 "monitors": "./config/monitors.json"

82 },

83 "userConfig": {

84 "api_token": {

85 "type": "string",

86 "title": "API token",

87 "description": "Token for the deployment API",

88 "sensitive": true

89 }

90 }

91}

92```

94<h3 id="unrecognized-fields">

95 無法識別的欄位

96</h3>

98無法識別的頂層鍵會被移除，而 `userConfig` 選項、`channels` 項目、`lspServers` 設定或 `monitors` 項目內無法識別的鍵會被拒絕：

100* **頂層欄位**：欄位被移除，plugin 載入。`claude plugin validate` 將每個無法識別的頂層欄位報告為警告

101* **嚴格物件**：`userConfig` 選項、`channels` 項目、`lspServers` 設定和 `monitors` 項目是嚴格的。其中的未知鍵是錯誤，plugin 不會載入

102

103<h3 id="validate-the-manifest">

104 驗證 manifest

105</h3>

106

107`claude plugin validate` 是 manifest 的權威檢查。從您的 shell 針對 plugin 目錄執行它：

108

109```bash theme={null}

110claude plugin validate ./my-plugin

111```

112

113該命令報告以下結果之一：

114

115* **`Validation passed`**：manifest 載入

116* **`Validation passed with warnings`**：manifest 載入，但驗證器發現需要修正的內容，例如 Claude Code 移除的未知頂層欄位、不是 kebab-case 的 `name`，或缺少 `version`、`description` 或 `author`。傳遞 `--strict` 以在 CI 中將警告轉換為失敗

117* **`Validation failed`**：manifest 有類型不匹配、缺少或逃逸 plugin 根目錄的路徑，或 `userConfig` 選項、`channels` 項目、`lspServers` 設定或 `monitors` 項目內的未知鍵。Claude Code 在載入 plugin 時報告相同的問題

118

119<h2 id="fields">

120 欄位

121</h2>

122

123表格列出 `plugin.json` 中的頂層鍵。`name` 是唯一必需的鍵。其中欄位名稱是連結的地方，連結的部分有其完整規則。

124

125對於元件鍵（例如 `commands` 和 `hooks`），[元件路徑形式](#component-path-forms)顯示每個接受的形式及範例，每個路徑都遵循 `./` 前綴、副檔名和包含的[路徑規則](#path-rules)。

126

127| 欄位 | 類型 | 說明 |

128| :----------------------------------- | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

129| `$schema` | String | JSON Schema URL 用於編輯器自動完成。Claude Code 在載入時忽略它 |

130| [`name`](#name) | String | Plugin 識別碼，必需。使用 kebab-case。每個元件都在其下命名空間 |

131| [`displayName`](#displayname) | String | 在 UI 中顯示的名稱，代替 `name` |

132| [`version`](#version) | String | 版本字串。設定它會將使用者保留在該版本，直到您變更它 |

133| `description` | String | plugin 提供內容的簡短說明 |

134| `author` | Object | `name`（必需），加上選用的 `email` 和 `url` |

135| `homepage` | String | 文件 URL。必須解析為 URL，否則 plugin 無法載入 |

136| `repository` | String | 來源儲存庫 URL。未驗證 |

137| `license` | String | SPDX 識別碼，例如 `MIT` 或 `Apache-2.0` |

138| `keywords` | Array of strings | 探索標籤 |

139| [`metadata`](#metadata) | Object | 您自己資料的自由形式物件。Claude Code 不讀取它 |

140| [`defaultEnabled`](#defaultenabled) | Boolean | 當使用者未設定時，plugin 是否在啟用時啟動。預設為 `true` |

141| [`dependencies`](#dependencies) | Array of strings or objects | 必須啟用此 plugin 才能運作的 plugin |

142| [`settings`](#settings) | Object | Claude Code 在 plugin 啟用時應用的設定。只有 `agent` 和 `subagentStatusLine` 生效 |

143| [`userConfig`](#user-configuration) | Object | Claude Code 在 plugin 啟用時提示使用者輸入的值 |

144| [`channels`](#channels) | Array of objects | plugin 提供的訊息頻道，每個繫結到其 MCP 伺服器之一 |

145| `skills` | Path, or array of paths | 要掃描的目錄以尋找 skills，每個目錄都是 `<name>/SKILL.md` 資料夾或直接保存 `SKILL.md` 的資料夾。`"."` 命名 plugin 根目錄。新增到預設 `skills/` 掃描 |

146| [`commands`](#commands) | Path, array of paths, or object | 平面 `.md` 命令檔案、它們的目錄，或命令名稱到 `source` 或 `content` 的物件對應。取代預設 `commands/` 掃描 |

147| `agents` | Path, or array of paths | Agent `.md` 檔案。不接受目錄。取代預設 `agents/` 掃描 |

148| [`hooks`](#hooks) | Path, object, or array of either | `.json` hook 檔案或內聯 hook 設定。與 `hooks/hooks.json` 一起載入 |

149| [`mcpServers`](#mcpservers) | Path, object, or array of either | `.json` MCP 設定檔案、`.mcpb` 或 `.dxt` 套件，或按名稱鍵入的內聯伺服器設定。與 `.mcp.json` 一起載入；稍後宣告的伺服器名稱取代較早的名稱 |

150| [`lspServers`](#lspservers) | Path, object, or array of either | `.json` LSP 設定檔案或按名稱鍵入的內聯伺服器設定。與 `.lsp.json` 一起載入 |

151| `outputStyles` | Path, or array of paths | 輸出樣式檔案或目錄。取代預設 `output-styles/` 掃描 |

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

153| `experimental` | Object | `themes`、`monitors` 和 `evals` 的容器，其 manifest 形式可能仍會變更 |

154| `experimental.themes` | Path, or array of paths | 主題檔案或目錄。取代預設 `themes/` 掃描。頂層 `themes` 鍵仍會載入，並帶有 `claude plugin validate` 警告 |

155| [`experimental.monitors`](#monitors) | Path, or inline array | 保存 monitors 陣列的 `.json` 檔案，或陣列本身。預設為 `monitors/monitors.json`。頂層 `monitors` 鍵仍會載入，並帶有 `claude plugin validate` 警告。Monitors 僅在互動式工作階段中執行，不在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上執行 |

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

157

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

159

160<h3 id="name">

161 `name`

162</h3>

163

164Plugin 識別碼。它必須非空，沒有空格、`@`、`:`、路徑分隔符、控制字元或雙向格式化字元；使用 kebab-case。

165

166Claude Code 在其下命名空間每個元件，因此 plugin `deploy-tools` 中的 agent `reviewer` 顯示為 `deploy-tools:reviewer`。

167

168<h3 id="displayname">

169 `displayName`

170</h3>

171

172在 UI 中顯示的名稱，代替 `name`。它可能包含空格和任何大小寫，它不用於命名空間或查詢。

173

174對於 marketplace 安裝的 plugin，[marketplace 項目](/docs/zh-TW/plugins/marketplace-reference#plugin-entries)上的 `displayName` 優先於此值。

175

176<h3 id="version">

177 `version`

178</h3>

179

180版本字串，不根據 semver 檢查。設定它會將 plugin 固定到該版本，直到您變更它；請參閱[版本和更新](/docs/zh-TW/plugins/loading#versions-and-updates)。具有[`command` 來源](/docs/zh-TW/plugins/marketplace-reference)的 plugin、來自[託管在 claude.ai 上的 marketplace](/docs/zh-TW/plugins/install#add-from-claude-ai) 的 plugin，以及[就地載入](/docs/zh-TW/plugins/loading#find-plugins-on-disk)的 plugin（來自作為本機目錄新增的 marketplace）不受此欄位固定。

181

182<h3 id="metadata">

183 `metadata`

184</h3>

185

186您自己資料的自由形式物件，例如目錄或權利欄位。Claude Code 不讀取它。需要 Claude Code v2.1.222 或更新版本。

187

188<h3 id="defaultenabled">

189 `defaultEnabled`

190</h3>

191

192當使用者未在 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 中設定時，plugin 是否在啟用時啟動。預設為 `true`。啟用的 plugin 所依賴的 plugin 無論如何都會啟用。marketplace 項目中的相同欄位覆蓋此欄位。

193

194一旦寫入使用者的 `enabledPlugins` 項目，它會在 plugin 更新中持續存在，因此在稍後版本中變更 `defaultEnabled` 不會變更現有使用者的設定。

195

196<h3 id="dependencies">

197 `dependencies`

198</h3>

199

200必須啟用此 plugin 才能運作的 plugin。每個項目是 `"name"`、`"name@marketplace"` 或 `{ "name": "...", "marketplace": "...", "version": "..." }`。裸名稱針對此 plugin 自己的 marketplace 解析。請參閱[依賴性約束](/docs/zh-TW/plugins/dependencies)。

201

202<h3 id="settings">

203 `settings`

204</h3>

205

206Claude Code 在 plugin 啟用時應用的設定。只有 `agent` 和 `subagentStatusLine` 生效；其他鍵在載入時被丟棄。plugin 根目錄的 `settings.json` 優先於此鍵。請參閱[預設設定](/docs/zh-TW/plugins/components#default-settings)。

207

208<h2 id="component-path-forms">

209 元件路徑形式

210</h2>

211

212每個元件鍵接受相對於 plugin 根目錄的路徑。`hooks`、`mcpServers`、`lspServers` 和 `experimental.monitors` 也接受內聯設定，`commands` 也接受物件對應，`mcpServers` 也接受 MCP 套件路徑和 URL。以下範例各顯示一次每個接受的形式。有關每個元件在執行時的作用，請參閱 [Plugin 元件](/docs/zh-TW/plugins/components)。

213

214<h3 id="path-only-fields">

215 僅路徑欄位

216</h3>

217

218`agents`、`skills`、`outputStyles`、`workflows` 和 `experimental.themes` 採用一個路徑或路徑陣列。`agents` 項目必須是 `.md` 檔案，`skills` 項目必須是目錄。其他三個接受目錄或檔案。

219

220```json theme={null}

221{

222 "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],

223 "skills": ["./extra-skills/", "."],

224 "outputStyles": "./styles/"

225}

226```

227

228<h3 id="commands">

229 `commands`

230</h3>

231

232`commands` 採用路徑、路徑陣列或物件對應。路徑命名平面 `.md` 命令檔案或目錄。在物件對應中，每個鍵在 plugin 前綴後成為命令名稱。例如，plugin `deploy-tools` 中的 `"about"` 執行為 `/deploy-tools:about`。

233

234每個值恰好設定 `source` 或 `content` 之一，設定兩者或都不設定的項目無法驗證。此表中的其他欄位是選用的：

235

236| 欄位 | 類型 | 說明 |

237| :------------- | :--------------- | :------------------------------- |

238| `source` | string | 命令的 Markdown 檔案路徑，相對於 plugin 根目錄 |

239| `content` | string | 命令主體的內聯 Markdown，而不是 `source` |

240| `description` | string | 為命令顯示的說明 |

241| `argumentHint` | string | 命令名稱後顯示的引數提示，例如 `[file]` |

242| `model` | string | 命令的預設模型 |

243| `allowedTools` | array of strings | 命令可以使用而無需提示的工具 |

244

245此對應宣告一個來自檔案的命令和一個來自內聯內容的命令：

246

247```json theme={null}

248{

249 "commands": {

250 "status": { "source": "./commands/status.md", "argumentHint": "[env]" },

251 "about": { "content": "Explain what this plugin provides." }

252 }

253}

254```

255

256<h3 id="hooks">

257 `hooks`

258</h3>

259

260`hooks` 採用 `.json` 檔案路徑、與 [`settings.json` 中的 `hooks`](/docs/zh-TW/hooks#configuration) 相同形式的內聯 hooks 物件，或混合兩者的陣列。有關 hook 事件和處理程式欄位，請參閱 [hooks 參考](/docs/zh-TW/hooks#hook-events)。

261

262Claude Code 在該檔案存在時將您宣告的內容與 `hooks/hooks.json` 合併。

263

264```json theme={null}

265{

266 "hooks": [

267 "./config/extra-hooks.json",

268 {

269 "PostToolUse": [

270 {

271 "matcher": "Write|Edit",

272 "hooks": [

273 { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.sh" }

274 ]

275 }

276 ]

277 }

278 ]

279}

280```

281

282<h3 id="mcpservers">

283 `mcpServers`

284</h3>

285

286`mcpServers` 採用 `.json` 檔案路徑、MCP 套件路徑或 URL、內聯對應，或混合它們的陣列。有關伺服器設定欄位，請參閱 [plugin 提供的 MCP 伺服器](/docs/zh-TW/mcp#plugin-provided-mcp-servers)。

287

288Claude Code 首先載入 plugin 根目錄的 `.mcp.json`，然後按順序載入每個宣告的形式。稍後宣告的伺服器名稱取代較早的名稱。

289

290`mcpServers` 值採用以下形式之一：

291

292| 形式 | 範例值 | Claude Code 的作用 |

293| :----------- | :------------------------------------------------------------------------------------- | :------------------------------------------------------------- |

294| `.json` 檔案路徑 | `"./mcp/servers.json"` | 將檔案讀取為 `mcpServers` 對應 |

295| MCP 套件路徑 | `"./bundle.mcpb"` | 將 `.mcpb` 或 `.dxt` 套件提取到 plugin 根目錄下的 `.mcpb-cache/` 並讀取其伺服器設定 |

296| MCP 套件 URL | `"https://example.com/server.mcpb"` | 將套件下載到 `.mcpb-cache/`，然後讀取它 |

297| 內聯對應 | `{ "deploy-api": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"] } }` | 使用對應作為按名稱鍵入的伺服器設定 |

298

299套件路徑或 URL 必須以 `.mcpb` 或 `.dxt` 結尾。任何其他副檔名無法驗證。

300

301<h3 id="lspservers">

302 `lspServers`

303</h3>

304

305`lspServers` 採用 `.json` 檔案路徑、伺服器名稱到設定的內聯對應，或兩者的陣列。

306

307Claude Code 首先載入 plugin 根目錄的 `.lsp.json`，然後按順序載入每個宣告的設定。稍後宣告的伺服器名稱取代較早的名稱。

308

309每個伺服器設定是具有這些欄位的嚴格物件。未知鍵無法驗證。

310

311| 欄位 | 必需 | 說明 |

312| :---------------------- | :-- | :------------------------------------------------------------------------------------------ |

313| `command` | Yes | Language server 二進位檔。除非值以 `/` 開頭，否則沒有空格；將引數放在 `args` 中 |

314| `extensionToLanguage` | Yes | 檔案副檔名到 LSP 語言 ID 的對應，至少一個項目。鍵以點開頭，例如 `".go"` |

315| `args` | No | 傳遞給伺服器的引數 |

316| `transport` | No | 通訊傳輸：`stdio`（預設）或 `socket`。Claude Code 接受 `socket` 但在 stdio 上執行每個伺服器，因此 stdout 協定規則適用於所有伺服器 |

317| `env` | No | 伺服器程序的環境變數 |

318| `initializationOptions` | No | 在初始化請求中傳送的選項 |

319| `settings` | No | 由 `workspace/didChangeConfiguration` 傳送的設定 |

320| `workspaceFolder` | No | 伺服器的工作區資料夾路徑 |

321| `startupTimeout` | No | 等待啟動的毫秒數，正整數 |

322| `shutdownTimeout` | No | 等待正常關閉的毫秒數，正整數。當逾時經過時，Claude Code 終止伺服器程序。未設定時，不適用逾時 |

323| `restartOnCrash` | No | 伺服器崩潰後是否重新啟動。預設為 `true`。設定為 `false` 以保持崩潰的伺服器停止而不是重新啟動 |

324| `maxRestarts` | No | 放棄前的重新啟動嘗試，零或更多 |

325| `diagnostics` | No | 編輯後是否將診斷推送到上下文。預設為 `true` |

326

327此內聯設定為 `.go` 檔案執行 `gopls`：

328

329```json theme={null}

330{

331 "lspServers": {

332 "go": {

333 "command": "gopls",

334 "args": ["serve"],

335 "extensionToLanguage": { ".go": "go" }

336 }

337 }

338}

339```

340

341有關 Anthropic 發佈為 plugin 的語言伺服器以及伺服器在執行時的行為，請參閱[程式碼智慧](/docs/zh-TW/plugins/code-intelligence)。

342

343<h3 id="monitors">

344 `monitors`

345</h3>

346

347`experimental.monitors` 採用 `.json` 檔案路徑或內聯陣列。當您省略鍵時，Claude Code 會載入 `monitors/monitors.json`（如果存在）。

348

349每個項目是具有這些欄位的嚴格物件。

350

351| 欄位 | 必需 | 說明 |

352| :------------ | :-- | :------------------------------------------------------------------------------------------------- |

353| `name` | Yes | 在 plugin 內唯一的識別碼 |

354| `command` | Yes | Claude Code 在工作階段工作目錄中作為持續背景程序執行的 Shell 命令 |

355| `description` | Yes | 在工作面板和通知摘要中顯示的簡短摘要 |

356| `when` | No | 使用 `"always"`（預設），monitor 在工作階段啟動和 plugin 重新載入時啟動。使用 `"on-skill-invoke:<skill>"`，它在該 skill 首次執行時啟動 |

357

358此內聯陣列宣告一個 monitor，在 `deploy` skill 首次執行時啟動：

359

360```json theme={null}

361{

362 "experimental": {

363 "monitors": [

364 {

365 "name": "deploy-status",

366 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",

367 "description": "Deployment status changes",

368 "when": "on-skill-invoke:deploy"

369 }

370 ]

371 }

372}

373```

374

375Monitor `command` 無法參考 `${user_config.*}`。請參閱[通過 shell 執行的欄位](#fields-that-run-through-a-shell)。

376

377<h2 id="path-rules">

378 路徑規則

379</h2>

380

381manifest 中的每個元件路徑相對於 plugin 根目錄，必須以 `./` 開頭。路徑（例如 `commands/foo.md`）無法驗證。`skills` 和 `mcpServers` 各接受該規則外的一種形式：

382

383* **`skills`**：也接受 `"."`。`"."` 和 `"./"` 都表示 plugin 根目錄。在 v2.1.221 之前，`"."` 無法通過 manifest 驗證，因此當 plugin 必須在較早版本上載入時使用 `"./"`

384* **`mcpServers`**：也接受 `https://` 套件 URL

385

386<h3 id="containment-and-existence">

387 包含和存在

388</h3>

389

390每個元件路徑必須解析到 plugin 根目錄內並且必須存在。`claude plugin validate` 不檢查 `outputStyles`、`lspServers`、`monitors` 或 `themes` 路徑，因此這些欄位中的錯誤路徑僅在 plugin 載入時失敗：

391

392* **包含**：解析到 plugin 根目錄外的路徑不會載入，`/plugin` **Errors** 標籤顯示 `<component> path escapes plugin directory: <path>`。包含 `..` 的路徑是常見情況，`claude plugin validate` 將其報告為 `Path contains ".." which could be a path traversal attempt`

393* **存在**：不存在的路徑不會載入，`/plugin` **Errors** 標籤顯示 `<component> path not found: <path>`。`claude plugin validate` 將其報告為 `Path not found`

394

395<h3 id="how-each-key-combines-with-its-default-location">

396 每個鍵如何與其預設位置結合

397</h3>

398

399每個元件鍵要麼取代其預設位置，要麼新增到它，要麼與它合併：

400

401* **取代預設**：`commands`、`agents`、`outputStyles`、`workflows`、`experimental.themes`、`experimental.monitors`。當您設定 `commands` 時，預設 `commands/` 目錄不會被掃描。要保留預設並新增更多，明確列出它：`"commands": ["./commands/", "./extras/"]`

402* **新增到預設**：`skills`。`skills/` 目錄仍會被掃描，列出的目錄與它一起載入

403* **合併**：`hooks`、`mcpServers`、`lspServers`。預設檔案首先載入，manifest 宣告的內容合併到它中，如[元件路徑形式](#component-path-forms)下所述

404

405如果 plugin 有預設資料夾（例如 `commands/`）並且也設定了取代它的 manifest 鍵，Claude Code 會載入 manifest 路徑而不是資料夾。`claude plugin list` 和 `/plugin` 介面然後顯示警告 `Default <folder>/ folder is ignored because the manifest sets "<key>"`。

406

407要避免警告，將鍵設定為該資料夾內的路徑：`"commands": ["./commands/deploy.md"]` 命名預設資料夾中的檔案，不會產生警告。

408

409<h2 id="user-configuration">

410 使用者設定

411</h2>

412

413`userConfig` 宣告當外掛程式啟用時 Claude Code 提示使用者輸入的值，讓使用者不需要自行編輯 `settings.json`。

414

415鍵是由字母、數字和底線組成的識別碼，且不能以數字開頭。

416

417每個值都是一個嚴格的物件，包含以下欄位。未知的鍵會導致驗證失敗。

418

419| 欄位 | 必需 | 說明 |

420| :------------ | :- | :-------------------------------------------------------------------------------------------------------------------- |

421| `type` | 是 | `string`、`number`、`boolean`、`directory` 或 `file` 之一 |

422| `title` | 是 | 在設定對話框中顯示的標籤 |

423| `description` | 是 | 在欄位下方顯示的說明文字 |

424| `required` | 否 | 如果為 `true`，設定對話框不接受空值 |

425| `default` | 否 | 當使用者未提供任何值時使用的值：字串、數字、布林值或字串陣列 |

426| `options` | 否 | 對於 `string`，欄位接受的值，在 `/config` 中顯示為選擇器。請參閱[將欄位限制為固定選項](#limit-a-field-to-fixed-options)。需要 Claude Code v2.1.271 或更新版本 |

427| `multiple` | 否 | 對於 `string`，允許字串陣列 |

428| `sensitive` | 否 | 如果為 `true`，會遮蔽輸入並將值儲存在安全儲存空間中，而不是 `settings.json` |

429| `min` / `max` | 否 | `number` 的邊界 |

430

431每個已啟用外掛程式的每個選項也會在 `/config` 面板中顯示為一列，除了 `sensitive` 選項和 `multiple` 清單。`/config` 列需要 Claude Code v2.1.269 或更新版本。

432

433此 `userConfig` 宣告一個端點和一個遮蔽的權杖：

434

435```json theme={null}

436{

437 "userConfig": {

438 "api_endpoint": {

439 "type": "string",

440 "title": "API endpoint",

441 "description": "Your team's API endpoint"

442 },

443 "api_token": {

444 "type": "string",

445 "title": "API token",

446 "description": "API authentication token",

447 "sensitive": true

448 }

449 }

450}

451```

452

453<h3 id="limit-a-field-to-fixed-options">

454 將欄位限制為固定選項

455</h3>

456

457在 `userConfig` 欄位上設定 `options`，讓使用者從固定清單中選擇其值。

458

459若要將 `tone` 欄位限制為三個選項，請在 `options` 中列出它們，並將 `default` 設定為其中之一：

460

461```json theme={null}

462{

463 "userConfig": {

464 "tone": {

465 "type": "string",

466 "title": "Tone",

467 "description": "Voice for generated replies",

468 "options": ["neutral", "warm", "formal"],

469 "default": "neutral"

470 }

471 }

472}

473```

474

475如果您在任何欄位上宣告 `options`，使用 Claude Code v2.1.271 之前版本的使用者將無法載入外掛程式。

476

477`options` 適用於不是 `multiple` 或 `sensitive` 的 `string` 欄位。將 `default` 設定為列出的值之一，或設定 `required: true` 讓使用者必須選擇一個。每個選項是 1 到 64 個字元的純標籤，您在殼層中執行的 `claude plugin validate` 會報告它拒絕的任何其他內容。選項違反這些規則的外掛程式將無法載入。

478

479<h3 id="where-values-are-stored">

480 值的儲存位置

481</h3>

482

483非敏感值會儲存在使用者 `settings.json` 中的 [`pluginConfigs`](/docs/zh-TW/settings-reference#pluginconfigs) 下。敏感值則改為儲存在平台的安全認證存放區中。[設定頁面](/docs/zh-TW/settings-reference#pluginconfigs)列出了讀取 `pluginConfigs` 的設定檔。

484

485<h3 id="reference-a-saved-value">

486 參考已儲存的值

487</h3>

488

489在外掛程式需要的地方參考已儲存的值，有以下兩種形式：

490

491* **`${user_config.KEY}`**：在 MCP 伺服器設定、LSP 伺服器設定、[exec 形式](/docs/zh-TW/hooks#exec-form-and-shell-form) hook `args` 和技能與代理程式內容中替換。在技能和代理程式內容中，只有非敏感值會被替換，敏感值會變成預留位置

492* **`CLAUDE_PLUGIN_OPTION_<KEY>`**：匯出到每個選項的 hook 程序，其中 `<KEY>` 為大寫。shell 形式的 hook 會讀取 `$CLAUDE_PLUGIN_OPTION_API_TOKEN` 以取得 `api_token`

493

494<h3 id="fields-that-run-through-a-shell">

495 通過殼層執行的欄位

496</h3>

497

498Shell 形式的 hook 命令、監視命令和 MCP [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) 拒絕 `${user_config.*}`。在這些欄位之一中參考它的元件會因[錯誤](/docs/zh-TW/errors#plugin-command-references-user-config)而失敗，而不是執行，因為欄位的值會傳遞到會重新解析替換值的殼層。

499

500下表顯示該值如何可以到達這些欄位。

501

502| 欄位 | 值如何到達它 |

503| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------- |

504| Shell 形式的 hook 命令 | 使用[exec 形式](/docs/zh-TW/hooks#exec-form-and-shell-form)搭配 `args`，或從 hook 的環境中讀取 `CLAUDE_PLUGIN_OPTION_<KEY>` |

505| 監視命令 | 不通過 Claude Code。監視程序不會接收 `CLAUDE_PLUGIN_OPTION_<KEY>`，所以監視指令碼必須自行取得該值 |

506| MCP `headersHelper` | 不通過 Claude Code。協助程式的環境包含 `CLAUDE_PLUGIN_ROOT`、`CLAUDE_CODE_MCP_SERVER_NAME` 和 `CLAUDE_CODE_MCP_SERVER_URL`，但沒有選項值，所以協助程式指令碼必須自行取得該值 |

507

508<h2 id="channels">

509 頻道

510</h2>

511

512`channels` 宣告 plugin 提供的訊息頻道，例如到聊天應用程式的橋接。當您宣告一個時，Claude Code 可以在 plugin 啟用時提示頻道的設定。有關伺服器如何注入訊息，請參閱[頻道參考](/docs/zh-TW/channels-reference#package-as-a-plugin)。

513

514每個項目是繫結到 plugin 的 MCP 伺服器之一的嚴格物件，具有這些欄位：

515

516| 欄位 | 必需 | 說明 |

517| :------------ | :-- | :---------------------------------------------------------------------------------------------- |

518| `server` | Yes | 此 plugin 的 `mcpServers` 中頻道繫結到的 MCP 伺服器的鍵 |

519| `displayName` | No | 在設定對話方塊標題中顯示的名稱。預設為伺服器名稱 |

520| `userConfig` | No | 要提示的選項，形式與[頂層 `userConfig`](#user-configuration) 相同。儲存的值替換到伺服器 `env` 中的 `${user_config.KEY}` 參考 |

521

522此 manifest 將頻道繫結到 plugin 的 `telegram` MCP 伺服器，並提示替換到伺服器 `env` 中的機器人令牌：

523

524```json theme={null}

525{

526 "mcpServers": {

527 "telegram": {

528 "command": "node",

529 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],

530 "env": { "BOT_TOKEN": "${user_config.bot_token}" }

531 }

532 },

533 "channels": [

534 {

535 "server": "telegram",

536 "displayName": "Telegram",

537 "userConfig": {

538 "bot_token": {

539 "type": "string",

540 "title": "Bot token",

541 "description": "Telegram bot token",

542 "sensitive": true

543 }

544 }

545 }

546 ]

547}

548```

549

550<h2 id="environment-variables">

551 環境變數

552</h2>

553

554Claude Code 為 plugin 元件提供三個路徑變數。在[每個變數解析的位置](#where-each-variable-resolves)下列出的欄位中將它們參考為 `${NAME}`，並在接收它們的程序中將它們讀取為環境變數。

555

556| 變數 | 解析為 | 用途 |

557| :---------------------- | :------------------------------------------------------------------------------------------------------------ | :----------------------------------- |

558| `${CLAUDE_PLUGIN_ROOT}` | plugin 已安裝版本的絕對路徑 | 與 plugin 捆綁的指令碼、二進位檔和設定檔案 |

559| `${CLAUDE_PLUGIN_DATA}` | `~/.claude/plugins/data/<id>/`，在首次參考時建立並在 plugin 更新中保留。`<id>` 是 plugin 識別碼，其中除字母、數字、`_` 或 `-` 外的每個字元都被 `-` 取代 | 已安裝的依賴項（例如 `node_modules`）、產生的程式碼和快取 |

560| `${CLAUDE_PROJECT_DIR}` | 專案根目錄 | 專案本機指令碼和設定檔案 |

561

562`${CLAUDE_PLUGIN_ROOT}` 在 plugin 更新時變更，因此不要在那裡寫入狀態。有關根目錄移動的位置和舊目錄何時被清理，請參閱[載入頁面](/docs/zh-TW/plugins/loading)。

563

564當您從最後安裝 plugin 的地方卸載它時，`${CLAUDE_PLUGIN_DATA}` 目錄會被刪除，除非您傳遞 [`--keep-data`](/docs/zh-TW/plugins/cli-reference)。

565

566<h3 id="where-each-variable-resolves">

567 每個變數解析的位置

568</h3>

569

570在每個 plugin 元件中，`${...}` 參考在特定欄位中內聯解析，某些元件也在其程序環境中接收變數：

571

572| Plugin 元件 | `${...}` 解析的欄位 | 匯出到程序 |

573| :------------------------ | :--------------------------------------- | :-------------------------------------------------------------------------------------------- |

574| Hook 命令 | 在 `command` 和 `args` 中的任何位置 | `CLAUDE_PLUGIN_ROOT`、`CLAUDE_PLUGIN_DATA`、`CLAUDE_PROJECT_DIR` 和 `CLAUDE_PLUGIN_OPTION_<KEY>` |

575| Monitor 命令 | 在 `command` 中的任何位置 | 未匯出 |

576| MCP `stdio` 伺服器 | `command`、`args`、`env` | `CLAUDE_PLUGIN_ROOT`、`CLAUDE_PLUGIN_DATA` |

577| MCP `http`、`sse`、`ws` 伺服器 | `url`、`headers`、`headersHelper` | 不適用 |

578| LSP 伺服器 | `command`、`args`、`env`、`workspaceFolder` | `CLAUDE_PLUGIN_ROOT`、`CLAUDE_PLUGIN_DATA`、`CLAUDE_PROJECT_DIR` |

579| Skill、command 和 agent 內容 | Markdown 主體中的任何位置 | 不適用 |

580

581變數不存在於 Claude 通過 Bash 工具在主工作階段或子代理中執行的命令環境中。在 skill、command 和 agent 內容中，在 Markdown 主體中寫入 `${...}` 參考，Claude Code 在載入內容時內聯替換路徑。

582

583<h3 id="quoting-and-path-separators">

584 引用和路徑分隔符

585</h3>

586

587保持每個替換的路徑為單一引數：

588

589* **Hook 命令**：使用[exec 形式](/docs/zh-TW/hooks#exec-form-and-shell-form)與 `args` 以便每個路徑是一個沒有引用的引數

590* **Shell 形式 hooks 和 monitor 命令**：用雙引號包裝變數，以便帶有空格的路徑保持為一個字

591

592此 shell 形式 hook 執行與 plugin 捆綁的指令碼：

593

594```json theme={null}

595{

596 "hooks": {

597 "PostToolUse": [

598 {

599 "hooks": [

600 {

601 "type": "command",

602 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"

603 }

604 ]

605 }

606 ]

607 }

608}

609```

610

611在 Windows 上，替換的路徑使用正斜杠，因此 shell 不會將反斜杠讀取為逃逸。

612

613<h2 id="standard-layout">

614 標準配置

615</h2>

616

617每個元件類型在 plugin 根目錄下有預設位置，當 manifest 不指向其他位置時使用。

618

619| 元件 | 預設位置 | 內容 |

620| :-------- | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

621| Manifest | `.claude-plugin/plugin.json` | Plugin 中繼資料和設定。選用 |

622| Skills | `skills/` | 每個 skill 一個 `<name>/SKILL.md`。具有其根目錄的 `SKILL.md`、沒有 `skills/` 和沒有 `skills` 鍵的 plugin 作為單一 skill 載入 |

623| Commands | `commands/` | 平面 Markdown 命令檔案。對於新 plugin 偏好 `skills/` |

624| Agents | `agents/` | Agent Markdown 檔案。子資料夾是[代理名稱](/docs/zh-TW/plugins/components#agents)的一部分 |

625| Hooks | `hooks/hooks.json` | Hook 設定 |

626| MCP 伺服器 | `.mcp.json` | MCP 伺服器定義 |

627| LSP 伺服器 | `.lsp.json` | LSP 伺服器設定 |

628| 輸出樣式 | `output-styles/` | 輸出樣式 Markdown 檔案 |

629| Workflows | `workflows/` | Workflow `.js` 檔案 |

630| 主題 | `themes/` | 主題 JSON 檔案 |

631| Monitors | `monitors/monitors.json` | Monitors 陣列 |

632| 可執行檔 | `bin/` | 此處的檔案在 plugin 啟用時位於 Bash 工具的 `PATH` 上，因此 Claude 將它們作為裸命令執行。claude.ai 和 Cowork 不安裝具有此目錄的 plugin，包括您[通過 claude.ai 組織設定分發](/docs/zh-TW/plugins/host-marketplace#distribute-through-organization-settings)的 plugin |

633| 設定 | `settings.json` | 在 plugin 啟用時應用的 `agent` 和 `subagentStatusLine` 預設值 |

634

635使用每個預設位置的 plugin，加上其 hooks 呼叫的 `scripts/` 資料夾，配置如下：

636

637```text theme={null}

638deploy-tools/

639├── .claude-plugin/

640│ └── plugin.json

641├── skills/

642│ └── deploy/

643│ └── SKILL.md

644├── commands/

645│ └── status.md

646├── agents/

647│ └── reviewer.md

648├── hooks/

649│ └── hooks.json

650├── monitors/

651│ └── monitors.json

652├── output-styles/

653│ └── terse.md

654├── themes/

655│ └── dracula.json

656├── workflows/

657│ └── release-audit.js

658├── bin/

659│ └── deploy-tool

660├── scripts/

661│ └── format.sh

662├── settings.json

663├── .mcp.json

664└── .lsp.json

665```

666

667要點擊此配置並讀取每個檔案的作用，請開啟 [plugin 探索器](/docs/zh-TW/plugins/components#explore-the-plugin-directory)。

668

669plugin 根目錄的 `CLAUDE.md` 不作為上下文載入，`claude plugin validate` 在找到一個時發出警告。要包含載入到 Claude 上下文中的指示，請將它們放在 skill 中。

670

671<h2 id="marketplace-entries-and-the-manifest">

672 Marketplace 項目和 manifest

673</h2>

674

675[marketplace 項目](/docs/zh-TW/plugins/marketplace-reference)接受此頁面上的每個欄位以及[其自己的欄位](/docs/zh-TW/plugins/marketplace-reference#plugin-entries)，包括 `strict`。

676

677`strict` 欄位決定項目是否可以將元件新增到具有自己 `plugin.json` 的 plugin。它預設為 `true`。

678

679<h3 id="how-entry-fields-combine-with-plugin-json">

680 項目欄位如何與 `plugin.json` 結合

681</h3>

682

683項目要麼作為 manifest，要麼將元件新增到它，要麼與它衝突：

684

685* **沒有 `plugin.json`**：項目是 manifest，無論 `strict` 如何。項目 `hooks` 僅以內聯物件形式載入。對於檔案路徑或陣列，`/plugin` **Errors** 標籤顯示 `not yet supported in a marketplace entry` 錯誤

686* **`plugin.json` 存在，`strict` 未設定或 `true`**：Claude Code 載入 manifest 並將項目的 `commands`、`agents`、`skills`、`outputStyles` 和 `themes` 附加到它。對於 `hooks`，項目的事件匹配器取代 manifest 對該相同事件的匹配器，只有 manifest 宣告的事件保留其

687* **`plugin.json` 存在，`strict: false`**：宣告 `commands`、`agents`、`skills`、`hooks`、`outputStyles` 或 `themes` 的項目是衝突，plugin 無法載入，出現 `Plugin <name> has conflicting manifests`

688

689當[其 `source` 是 marketplace 根目錄的 marketplace 項目](/docs/zh-TW/plugins/marketplace-reference)列出特定 `skills` 子目錄時，只有這些子目錄載入，plugin 的預設 `skills/` 目錄不會被掃描。manifest 中的 `skills` 鍵改為[新增到預設](#how-each-key-combines-with-its-default-location)。

690

691<h3 id="metadata-precedence">

692 中繼資料優先順序

693</h3>

694

695某些中繼資料欄位有固定的優先順序，無論 `strict` 如何：

696

697* **`defaultEnabled` 和顯示欄位**：項目的 `defaultEnabled` 和其[顯示欄位](/docs/zh-TW/plugins/marketplace-reference#entry-and-plugin-json)（例如 `displayName`）覆蓋 manifest 的

698* **`version`**：manifest 的 `version` 覆蓋項目的

699* **`name`**：當項目在與 manifest 不同的 `name` 下列出 plugin 時，`enabledPlugins` 使用項目名稱，元件在 manifest 名稱下命名空間

700

701有關完整優先順序表，請參閱[嚴格模式](/docs/zh-TW/plugins/marketplace-reference)。

702

703<h2 id="next-steps">

704 後續步驟

705</h2>

706

707* [將元件新增到 plugin](/docs/zh-TW/plugins/components)：每個元件在執行時的作用，以及驗證的範例

708* [Marketplace 參考](/docs/zh-TW/plugins/marketplace-reference)：marketplace 可以為您的 plugin 設定的項目欄位

709* [Plugin 命令參考](/docs/zh-TW/plugins/cli-reference#plugin-validate)：`claude plugin validate` 旗標和輸出

710* [疑難排解 plugin](/docs/zh-TW/plugins/troubleshooting#claude-plugin-validate-reports-errors)：每條驗證訊息及其修正

plugins/measure.md +193 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 測量外掛程式成本和使用情況

7> 測量 Claude Code 外掛程式的權杖成本，了解人們是否仍在使用它，並為組織範圍的外掛程式問題選擇遙測事件。

9啟用外掛程式的每個工作階段都會在 Claude 的上下文中包含其技能、代理和命令的名稱和描述，這些權杖會計入使用者的使用量，無論外掛程式是否被使用。本頁面說明如何查看外掛程式的該數字、如果您維護外掛程式如何減少它，以及使用情況在何處顯示，以便您可以判斷外掛程式是否仍在被使用。

11本頁面適用於外掛程式作者和維護者。如果您為組織管理 Claude Code，[跨機隊測量](#measure-across-a-fleet)涵蓋了每台機器上的相同問題。

13<Note>

14 這些情況在其他頁面上涵蓋：

16 * **測試外掛程式如何可靠地改變 Claude 的行為**：請參閱[使用評估測試外掛程式](/docs/zh-TW/plugin-evals)

17 * **修剪您自己工作階段的上下文**：請參閱[管理已安裝的外掛程式](/docs/zh-TW/plugins/install#manage-installed-plugins)和[上下文視窗](/docs/zh-TW/context-window)頁面

18</Note>

20從[測量外掛程式的成本](#measure-what-a-plugin-costs)開始。

22<h2 id="measure-what-a-plugin-costs">

23 測量外掛程式的成本

24</h2>

26要查看外掛程式對 Claude 上下文的影響，請使用外掛程式的名稱執行 [`claude plugin details`](/docs/zh-TW/plugins/cli-reference#plugin-details)。您在 shell 中執行它，而不是在執行中的 Claude Code 工作階段的提示符處。外掛程式必須被載入：已安裝、在技能目錄中，或在同一命令中使用 `--plugin-dir` 傳遞，如 `claude --plugin-dir ./formatter plugin details formatter`。

28此範例讀取一個名為 `formatter` 的已安裝外掛程式，該外掛程式有兩個技能、一個命令、一個代理、一個 hook 和一個 MCP 伺服器：

30```bash theme={null}

31claude plugin details formatter

32```

34```text theme={null}

35formatter 1.0.0

36 Description: Formats and lints code on save

37 Source: formatter@my-marketplace

39Component inventory

40 Skills (3) format-all, format-code, lint-fix

41 Agents (1) style-reviewer

42 Hooks (1) PostToolUse (harness-only — no model context cost)

43 MCP servers (1) formatter-tools (tool schemas resolved at runtime; not counted)

44 LSP servers (0)

46Projected token cost

47 Always-on: ~146 tok added to every session

49Per-component (rounded)

50 component always-on on-invoke

51 format-code ~40 ~30

52 lint-fix ~50 ~30

53 style-reviewer ~40 ~40

54 format-all < 20 ~30

56 On-invoke cost is paid each time a skill or agent fires.

57 Token counts are estimates and may differ from actual usage.

58```

60輸出的每個部分回答了不同的問題：

62* **Component inventory**：Claude Code 在外掛程式中找到的內容。命令與技能一起計算，因此 `format-all` 出現在 `Skills` 下。Hooks 和 MCP 伺服器沒有成本估計和每個元件行；要查看外掛程式的 MCP 工具添加了什麼，請在啟用外掛程式的工作階段中執行 `/context`，並閱讀 `MCP tools` 類別。

63* **Always-on**：外掛程式的技能、代理和命令的名稱和描述添加到啟用外掛程式的每個工作階段的權杖，無論是否有任何內容執行。這是每個使用者都會承載的數字，也是要減少的數字。

64* **Per-component**：每一行將一個技能、代理或命令分為其 always-on 份額和其 on-invoke 成本，後者是僅在該元件執行時載入的主體。使用 always-on 列來找出哪個元件貢獻最多。

66<h3 id="lower-the-always-on-figure">

67 降低 always-on 數字

68</h3>

70如果您維護外掛程式，這些更改會減少它對每個工作階段的添加。如果您只是使用它，您的選項是禁用或卸載它；請參閱[管理已安裝的外掛程式](/docs/zh-TW/plugins/install#manage-installed-plugins)。

72always-on 數字計算每個元件的名稱加上其 `description` 和 `when_to_use` frontmatter。要降低它：

74* 縮短技能和代理描述。

75* 分割大型外掛程式，以便使用者只安裝他們需要的元件。

77技能的描述也是 Claude 匹配請求的內容，因此較短的描述可以阻止技能觸發。修剪描述後，使用評估套件中的 [`tool_used: Skill` grader](/docs/zh-TW/plugin-evals#create-your-first-eval-suite) 檢查觸發。

79有關每個元件類型的貢獻，請參閱[外掛程式元件](/docs/zh-TW/plugins/components)。

81<h3 id="cost-shown-to-users-before-install">

82 安裝前向使用者顯示的成本

83</h3>

85官方市場中的外掛程式在安裝前向使用者顯示其成本。在 `/plugin` 中，當使用者瀏覽市場的外掛程式列表並選擇外掛程式時，詳細資訊窗格會顯示一個**Context cost**部分，其中包含 `Every turn:` 行和 `When invoked:` 行。當 always-on 數字為 2,000 個權杖或更多時，`Every turn:` 行會顯示突出顯示。

87您自己市場中的外掛程式沒有**Context cost**部分。

89<h2 id="check-whether-a-plugin-is-used">

90 檢查外掛程式是否被使用

91</h2>

93Claude Code 不會向其作者報告外掛程式的使用情況。使用情況記錄在安裝外掛程式的每個人的機器上，因此您可以了解的內容取決於您與這些人的關係：

95* **您為其組織管理 Claude Code**：OpenTelemetry 事件和 Analytics API 計算每台機器上的安裝和技能啟動。請參閱[跨機隊測量](#measure-across-a-fleet)。

96* **他們是您可以詢問的隊友**：每個使用者自己的 Claude Code 在四個地方向他們顯示他們是否仍在使用外掛程式：[`/plugin` 面板](#not-used-recently-in-/plugin)、[`/skill-doctor`](#find-skills-that-never-run)、[`/doctor`](#unused-plugins-in-/doctor) 和 [`/usage`](#usage-share-in-/usage)。所有四個都是使用者在自己機器上的工作階段中在 Claude Code 提示符處執行的命令。

97* **都不是**：您沒有來自 Claude Code 的該外掛程式的使用信號。

99<h3 id="not-used-recently-in-/plugin">

100 `/plugin` 中最近未使用

101</h3>

102

103在 `/plugin` 的**Installed**標籤上，使用者從市場安裝的外掛程式在至少 14 天和 10 個工作階段未使用後，會移到**Not used recently**標題下。外掛程式的詳細資訊也會顯示 `Last used:` 行。有關使用者對該標題和行的操作，請參閱[尋找您不再使用的外掛程式](/docs/zh-TW/plugins/install#find-plugins-you-no-longer-use)。

104

105**Not used recently**標題永遠不會出現在：

106

107* 使用 `--plugin-dir` 或從技能目錄載入的外掛程式

108* 通過受管設定啟用或從[種子目錄](/docs/zh-TW/plugins/org#seed-containers-and-ci)掛載的外掛程式

109* 包含主題、輸出樣式、監視器或工作流的外掛程式，因為這些在沒有追蹤的啟動的情況下使用

110

111外掛程式的[語言伺服器](/docs/zh-TW/plugins/components#lsp-servers)在傳遞診斷或回答代碼導航請求時計為已使用，因此伺服器在您的工作階段中活躍的 LSP 外掛程式不會列為未使用。

112

113當使用者的組織設定 [`strictKnownMarketplaces`](/docs/zh-TW/plugins/org#restrict-what-users-can-install) 時，標題和 `Last used:` 行都不會出現。

114

115<h3 id="find-skills-that-never-run">

116 尋找永遠不執行的技能

117</h3>

118

119執行 `/skill-doctor` 以查看您的每個技能的成本以及它被使用的頻率。它標記在 Claude 的技能列表中但從未被啟動的技能，包括來自外掛程式的技能。

120

121在互動式工作階段中，報告在 `/plugin` 管理器的**Stats**標籤中打開。請參閱[尋找未使用的技能](/docs/zh-TW/skills#find-unused-skills)以了解報告涵蓋的內容以及它在何處可用。

122

123<h3 id="unused-plugins-in-/doctor">

124 `/doctor` 中未使用的外掛程式

125</h3>

126

127`/doctor` 檢查列出每個使用者安裝的技能、MCP 伺服器和外掛程式，並建議禁用未使用的外掛程式。請參閱[命令參考中的 `/doctor`](/docs/zh-TW/commands#all-commands)。

128

129<h3 id="usage-share-in-/usage">

130 `/usage` 中的使用情況份額

131</h3>

132

133在 Pro、Max、Team 或 Enterprise 計劃上，`/usage` 細分將最近的使用情況歸因於技能、子代理、外掛程式和 MCP 伺服器，作為總數的份額。請參閱[使用 `/usage` 命令](/docs/zh-TW/costs#using-the-/usage-command)。

134

135<h2 id="measure-across-a-fleet">

136 跨機隊測量

137</h2>

138

139如果您為組織管理 Claude Code，您可以從以下任一來源跨每台機器測量外掛程式成本和使用情況：

140

141* **OpenTelemetry 事件**：Claude Code 在您[配置匯出器](/docs/zh-TW/monitoring-usage)後將這些匯出到您自己的後端。請參閱[外掛程式安裝和使用的 OpenTelemetry 事件](#pick-the-opentelemetry-event-for-each-question)。

142* **Analytics API**：由 Anthropic 的記錄提供，無需匯出器。請參閱[查詢 Analytics API](#query-the-analytics-api)。

143

144<h3 id="pick-the-opentelemetry-event-for-each-question">

145 外掛程式安裝和使用的 OpenTelemetry 事件

146</h3>

147

148這些 OpenTelemetry 事件和屬性從您的後端回答每個外掛程式問題：

149

150| 問題 | OpenTelemetry 事件或屬性 |

151| :---------------- | :-------------------------------------------------------------------------------------------------------------------------- |

152| 安裝了哪些外掛程式，來自何處 | [`claude_code.plugin_installed`](/docs/zh-TW/monitoring-usage#plugin-installed-event)，每次安裝一個 |

153| 哪些外掛程式在多少個工作階段中活躍 | [`claude_code.plugin_loaded`](/docs/zh-TW/monitoring-usage#plugin-loaded-event)，工作階段開始時每個啟用的外掛程式一個 |

154| 哪些技能啟動，哪個外掛程式擁有它們 | [`claude_code.skill_activated`](/docs/zh-TW/monitoring-usage#skill-activated-event)，帶有外掛程式技能的 `plugin.name` 和 `marketplace.name` |

155| 外掛程式的 hooks 報告什麼 | [`claude_code.hook_plugin_metrics`](/docs/zh-TW/monitoring-usage#hook-plugin-metrics-event)，僅針對官方市場外掛程式中的 hooks 發出 |

156| 外掛程式在 API 支出中的成本 | [成本計數器](/docs/zh-TW/monitoring-usage#cost-counter)上的 `plugin.name` 和 `marketplace.name`，在活躍技能或子代理屬於外掛程式時設定 |

157

158<h3 id="redacted-plugin-names-in-your-backend">

159 後端中的編輯外掛程式名稱

160</h3>

161

162來自官方市場的外掛程式將其外掛程式名稱和市場名稱逐字報告到您的後端。所有其他外掛程式的名稱預設被編輯或省略，包括來自您組織自己市場的外掛程式。外掛程式的[信任層級](/docs/zh-TW/plugins/security#find-plugins-in-telemetry)決定了哪個。

163

164要在某些事件上獲取真實名稱，請在匯出遙測的機器上將 [`OTEL_LOG_TOOL_DETAILS`](/docs/zh-TW/monitoring-usage#common-configuration-variables) 環境變數設定為 `1`，例如在配置匯出器的相同[受管設定](/docs/zh-TW/monitoring-usage#administrator-configuration)的 `env` 塊中：

165

166| 事件 | 預設 | 使用 `OTEL_LOG_TOOL_DETAILS=1` |

167| :----------------------------------- | :---------------------------------------------------------------------------------------- | :---------------------------------------- |

168| `plugin_loaded` | `plugin.name` 和 `marketplace.name` 是字面字符串 `third-party` | 真實名稱 |

169| `plugin_installed`、`skill_activated` | `plugin.name` 和 `marketplace.name` 省略；在 `skill_activated` 上，`skill.name` 是 `custom_skill` | 真實名稱 |

170| 成本計數器 | `plugin.name` 是 `third-party`；`marketplace.name` 不存在 | 真實 `plugin.name`；`marketplace.name` 仍然不存在 |

171

172在 `plugin_loaded` 上，`plugin_id_hash` 仍然預設識別每個外掛程式，因此您可以計算不同的第三方外掛程式。

173

174<h3 id="query-the-analytics-api">

175 查詢 Analytics API

176</h3>

177

178在 Enterprise 計劃上，Analytics API 從 Anthropic 的記錄中回答「我的組織安裝和啟動哪些外掛程式」，無需匯出器。[`GET /v1/organizations/analytics/plugins`](https://platform.claude.com/docs/en/api/admin/analytics/plugins/list) 返回跨 Claude Code 和 Cowork 的每個外掛程式、每天的安裝和啟動計數，您可以按使用者、RBAC 群組或產品進行分組。

179

180到達 Anthropic 而沒有外掛程式名稱的外掛程式活動出現在一個聚合 `third-party` 行中。[在遙測中尋找外掛程式](/docs/zh-TW/plugins/security#find-plugins-in-telemetry)說明 Claude Code 按名稱報告的外掛程式。

181

182使用具有 `read:analytics` 範圍的 API 金鑰驗證請求，主要所有者按[以程式設計方式存取資料](/docs/zh-TW/analytics#access-data-programmatically)下所述建立。

183

184有關參數和回應欄位，請參閱[端點參考](https://platform.claude.com/docs/en/api/admin/analytics/plugins/list)。

185

186<h2 id="next-steps">

187 後續步驟

188</h2>

189

190* [使用評估測試外掛程式](/docs/zh-TW/plugin-evals)：測量外掛程式如何可靠地引導 Claude，而不僅僅是它的成本

191* [降低 always-on 數字](#lower-the-always-on-figure)：在外掛程式中更改什麼以減少其每轉成本

192* [外掛程式安全性和信任](/docs/zh-TW/plugins/security#find-plugins-in-telemetry)：哪些遙測欄位攜帶外掛程式名稱以及何時被編輯

193* [監視使用情況](/docs/zh-TW/monitoring-usage)：完整的 OpenTelemetry 事件參考

plugins/org.md +460 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 為您的組織管理 Claude Code 外掛程式

7> 透過受管設定控制 Claude Code 在組織中每台機器上安裝和允許的外掛程式。

9受管設定讓您決定 Claude Code 在組織中每台機器上安裝和允許的外掛程式。使用者無法覆蓋它們。您可以從 claude.ai 管理員主控台以[伺服器受管設定](/docs/zh-TW/server-managed-settings)的形式提供它們，或透過 MDM 或 `managed-settings.json` 檔案以端點受管設定的形式提供。此頁面上的大多數控制項僅在受管設定中生效。

11此頁面適用於管理員，此處的設定管理 Claude Code。

13<Note>

14 這些情況涵蓋在其他頁面上：

16 * **為自己安裝外掛程式**：從[安裝外掛程式](/docs/zh-TW/plugins/install)開始

17 * **控制成員在 claude.ai 和 Cowork 中可以使用哪些外掛程式**：請參閱說明中心中的[為您的組織管理外掛程式](https://support.claude.com/en/articles/13837433)

18 * **claude.ai 管理設定中的外掛程式頁面**：[**組織設定 > 外掛程式與技能**](https://claude.ai/admin-settings/skills?tab=inventory)為成員的 claude.ai 帳戶開啟外掛程式，這些外掛程式作為[同步外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)到達 Claude Code。它不設定此頁面上的任何金鑰

19</Note>

21這些部分遵循大多數推出所採取的順序：[為所有人或每個儲存庫要求外掛程式](#pre-install-and-require-plugins)、[為容器和 CI 設定種子](#seed-containers-and-ci)、[限制](#restrict-what-users-can-install)使用者可以自行新增的內容、[設定更新政策](#set-update-policy)，然後[稽核](#audit-and-review)已安裝的內容。若要在一個位置檢視每個政策金鑰，請參閱[控制矩陣](#control-matrix)。

23<h2 id="pre-install-and-require-plugins">

24 預先安裝和要求外掛程式

25</h2>

27市場是外掛程式的目錄，Claude Code 從 git 儲存庫、URL 或本機路徑中擷取。在機器上註冊市場後，Claude Code 可以從中安裝外掛程式。

29若要為整個車隊安裝外掛程式，請在[受管設定](/docs/zh-TW/managed-settings)、政策檔案或組織中每台機器讀取的伺服器提供的政策中同時設定兩個金鑰：`extraKnownMarketplaces` 在每台機器上註冊市場，`enabledPlugins` 命名要從中安裝和啟用的外掛程式。[選擇傳遞機制](#choose-a-delivery-mechanism)涵蓋受管設定如何到達每台機器。

31<h3 id="choose-a-delivery-mechanism">

32 選擇傳遞機制

33</h3>

35受管設定透過以下三種傳遞機制之一到達機器：

37* **伺服器受管設定**：在[**組織設定 > Claude Code > 受管設定**](https://claude.ai/admin-settings/claude-code)將外掛程式金鑰設定為 JSON。需要在您的 Claude 組織中具有[擁有者角色](/docs/zh-TW/server-managed-settings#access-control)。雲端工作階段在安裝外掛程式之前會擷取這些設定。

38* **MDM 政策**：在 macOS 上，提供一個 plist，其頂級金鑰是設定金鑰。在 Windows 上，將整個 JSON 文件儲存為登錄值中的字串。plist 網域和登錄金鑰位於[每個機制儲存政策的位置](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy)。

39* **受管設定檔案**：在平台的系統路徑放置 `managed-settings.json`。您也可以將檔案新增到其旁邊的 `managed-settings.d/` 放入目錄。每個平台的檔案路徑位於[每個機制儲存政策的位置](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy)，放入合併規則位於[將基於檔案的政策分割到各個團隊](/docs/zh-TW/managed-settings#split-a-file-based-policy-across-teams)。

41如果您在 claude.ai 上有 Claude for Teams 或 Enterprise 組織，且您的裝置並非全部在 MDM 下，請使用伺服器受管設定。否則使用 MDM 政策或受管設定檔案。如需權衡，請參閱[在伺服器受管和端點受管設定之間選擇](/docs/zh-TW/server-managed-settings#choose-between-server-managed-and-endpoint-managed-settings)。

43<h4 id="which-managed-source-applies-on-a-machine">

44 哪個受管來源在機器上適用

45</h4>

47預設情況下，這三個來源中只有一個在機器上適用。Claude Code 使用第一個提供政策金鑰的來源，首先檢查伺服器受管設定，然後檢查 MDM 政策，然後檢查受管設定檔案。如果伺服器受管設定提供甚至一個不相關的政策金鑰，Claude Code 會忽略該機器上 MDM 政策或受管設定檔案中的外掛程式金鑰，除了[它從每個來源讀取的金鑰](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)。

49若要改為應用每個來源，請將[`managedSourcesBehavior`](/docs/zh-TW/managed-settings#compose-every-managed-source)設定為 `"merge"`。

51[Claude Code 如何組合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)也在兩種模式中列出 Claude Code 從每個來源讀取的金鑰。

53<h3 id="require-a-marketplace-and-its-plugins">

54 要求市場及其外掛程式

55</h3>

57在 `extraKnownMarketplaces` 下新增市場，使用市場自己的 `marketplace.json` 中的 `name` 作為金鑰。然後在 `enabledPlugins` 下將每個外掛程式新增為 `plugin-name@marketplace-name`。每個市場項目都帶有一個 `source` 物件，其中 `source` 欄位命名類型，例如 `github`。此受管設定範例註冊一個組織市場並強制啟用其中的兩個外掛程式：

59```json theme={null}

60{

61 "extraKnownMarketplaces": {

62 "your-marketplace": {

63 "source": { "source": "github", "repo": "your-org/your-marketplace" },

64 "autoUpdate": true

65 }

66 },

67 "enabledPlugins": {

68 "code-formatter@your-marketplace": true,

69 "deploy-helper@your-marketplace": true

70 }

71}

72```

74設定到達機器後，Claude Code 註冊市場並在使用者下一個工作階段開始時安裝兩個外掛程式。使用者在 `/plugin` 中看到它們，在自己的範圍禁用其中一個不會阻止它載入，因為受管設定優先於每個其他範圍。

76若要在每個範圍阻止外掛程式並將其從市場清單中隱藏，請改為在受管 `enabledPlugins` 中將其設定為 `false`。

78調整市場的 `autoUpdate` 和 `source` 欄位：

80* **`autoUpdate`**：`true` 保持市場及其外掛程式在背景中重新整理，`false` 關閉它。請參閱[設定更新政策](#set-update-policy)。

81* **`source`**：`github` 是幾種來源類型之一。`git` 來源採用 GitLab 或內部主機的 `url`，`url` 來源採用託管 `marketplace.json` 的位址。每個來源形狀都在[市場參考](/docs/zh-TW/plugins/marketplace-reference)中。

83如果市場是私人 git 儲存庫，每個使用者都需要對其具有讀取存取權限。git 型市場的複製在使用者的機器上使用 git 執行，使用儲存的認證且無提示。對於沒有 git 主機帳戶的使用者，請改用[種子](#seed-containers-and-ci)。

85受管項目也會覆蓋來自另一個來源的同名市場項目或 `--plugin-dir` 複本：

87* **市場**：受管市場項目替換具有相同名稱的較低優先順序項目，兩個項目的欄位不合併。

88* **`--plugin-dir` 複本**：`--plugin-dir` 為一個工作階段從本機目錄載入外掛程式。如果該複本的名稱與您的受管 `enabledPlugins` 命名的外掛程式相符，請參閱[名稱衝突](/docs/zh-TW/plugins/loading#name-conflicts)。

90Anthropic 的官方市場 `claude-plugins-official` 當 `enabledPlugins` 將其中一個外掛程式設定為 `true` 時不需要 `extraKnownMarketplaces` 項目。該 `name@claude-plugins-official` 項目在這些金鑰適用的任何地方自行聲明市場。如果您未啟用其任何外掛程式但仍想在每台機器上註冊它，請給它一個明確項目，如[允許官方市場和您自己的](#allow-the-official-marketplace-and-your-own)所做的。

92<h3 id="require-plugins-per-repository">

93 按儲存庫要求外掛程式

94</h3>

96若要涵蓋一個儲存庫的貢獻者而不是整個車隊，請在該儲存庫的 `.claude/settings.json` 中設定 `extraKnownMarketplaces` 和 `enabledPlugins`。`extraKnownMarketplaces` 項目僅適用於貢獻者已信任的資料夾，在不受信任的資料夾中 Claude Code 會無訊息地忽略它們：

98* **互動式工作階段**：Claude Code 僅在貢獻者接受該資料夾的[工作區信任對話](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)後才註冊市場。

99* **[非互動式 `-p` 執行](/docs/zh-TW/headless)**：項目僅適用於使用者已互動式接受信任的資料夾，或您在 `~/.claude.json` 中設定 `hasTrustDialogAccepted` 旗標的資料夾。

100

101市場按相對路徑列出的外掛程式在儲存庫的 `extraKnownMarketplaces` 項目適用後從市場複本載入。市場項目指向外部來源（例如外掛程式自己的 GitHub 儲存庫）的外掛程式不會單獨從儲存庫的設定安裝。每個貢獻者看到 `Plugin "<name>" is enabled in project settings but isn't installed`，直到他們執行 `claude plugin install <name>@<marketplace> --scope project`，如[安裝外掛程式](/docs/zh-TW/plugins/install)所述。

102

103如果您使用具有相對路徑的本機 `directory` 或 `file` 來源，路徑會針對您的儲存庫的主要簽出進行解析。當您從 git worktree 執行 Claude Code 時，路徑仍指向主要簽出，因此所有 worktree 共享相同的市場位置。

104

105若要推出具有依賴項的外掛程式組合，請將組合外掛程式放在 `enabledPlugins` 中，如[外掛程式依賴項](/docs/zh-TW/plugins/dependencies)所述。

106

107<h3 id="when-each-surface-applies-the-plugin-keys">

108 每個表面何時應用外掛程式金鑰

109</h3>

110

111該表顯示每種 Claude Code 工作階段何時應用 `extraKnownMarketplaces` 和 `enabledPlugins`，來自受管設定和來自儲存庫的 `.claude/settings.json`。對於 Desktop 應用程式和 IDE 擴充功能，請參閱[安裝外掛程式](/docs/zh-TW/plugins/install#install-a-plugin)。

112

113| 表面 | 受管 `extraKnownMarketplaces` 和 `enabledPlugins` | 儲存庫 `.claude/settings.json` |

114| :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------- |

115| 終端機、互動式 | 在接收設定的每台機器上的工作階段開始時應用 | `extraKnownMarketplaces` 在信任後應用；`enabledPlugins` 在工作階段開始時應用 |

116| `-p` 和 CI | 在工作階段開始時應用，安裝在背景中執行 | 僅在受信任的資料夾中的 `extraKnownMarketplaces`；`enabledPlugins` 已應用 |

117| 雲端工作階段 | 在 Anthropic 託管的環境中，僅伺服器受管設定到達工作階段，它在安裝外掛程式之前等待它們。MDM 政策和受管設定檔案保留在使用者的機器上。對於自託管環境，請參閱[政策適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies) | 請參閱[安裝外掛程式](/docs/zh-TW/plugins/install#install-a-plugin)下的**雲端工作階段**標籤 |

118

119在 `-p` 或 CI 執行中，市場和外掛程式在背景中安裝，因此外掛程式可能在第一個轉向中遺失。設定 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` 使執行在其第一個查詢之前等待安裝。

120

121<h3 id="confirm-the-rollout">

122 確認推出

123</h3>

124

125檢查市場和外掛程式是否到達機器或 CI 執行：

126

127* **在一台機器上**：啟動 Claude Code 並執行 `/plugin`。市場和外掛程式已列出。

128* **在 CI 中**：使用 `--output-format stream-json --verbose` 執行 `claude -p`。`init` 事件在 `plugins` 下列出已載入的外掛程式。

129

130<h2 id="seed-containers-and-ci">

131 為容器和 CI 設定種子

132</h2>

133

134對於無法在執行時複製的容器映像和 CI 執行器，在建置時預先填充外掛程式目錄並將 `CLAUDE_CODE_PLUGIN_SEED_DIR` 指向它。Claude Code 在啟動時註冊種子的市場並從種子就地載入外掛程式快取，無需複製。

135

136種子也為沒有 git 主機帳戶的使用者提供服務。

137

138<Note>

139 在 CI/CD 環境中，在從私人儲存庫安裝外掛程式之前配置 git 認證幫助程式。在 GitHub Actions 上，匯出具有市場儲存庫讀取存取權限的令牌作為 `GH_TOKEN`，然後執行 `gh auth setup-git`。預設工作流程令牌只能存取工作流程自己的儲存庫，因此另一個儲存庫中的私人市場需要個人存取令牌或應用程式令牌。

140</Note>

141

142<Steps>

143 <Step title="在建置時安裝到種子中">

144 將 `CLAUDE_CODE_PLUGIN_CACHE_DIR` 設定為種子路徑，以便市場和外掛程式安裝在那裡而不是 `~/.claude/plugins`：

145

146 ```bash theme={null}

147 CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/your-marketplace

148 CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install code-formatter@your-marketplace

149 ```

150

151 種子的佈局與 `~/.claude/plugins` 相同：`known_marketplaces.json`、`marketplaces/<name>/` 和 `cache/<marketplace>/<plugin>/<version>/`。您可以在與建置位置不同的路徑掛載種子。

152 </Step>

153

154 <Step title="將執行時指向種子">

155 在容器的環境中設定 `CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed`。若要使用多個種子，請在 Unix 上用 `:` 或在 Windows 上用 `;` 分隔它們的路徑。Claude Code 使用包含給定市場或外掛程式快取的第一個種子。

156 </Step>

157

158 <Step title="啟用外掛程式">

159 種子中的外掛程式預設不啟用。在受管設定或儲存庫的 `.claude/settings.json` 中為每個要載入的種子外掛程式設定 `enabledPlugins`。

160 </Step>

161</Steps>

162

163若要驗證種子，請在映像中使用 `--output-format stream-json --verbose` 執行 `claude -p`。在 `init` 事件的 `plugins` 清單中，每個已載入外掛程式的 `path` 位於種子下，例如 `/opt/claude-seed/cache/your-marketplace/code-formatter/1.0.0`。

164

165種子市場遵循這些規則：

166

167* **唯讀**：Claude Code 永遠不會寫入種子，並強制為種子市場關閉 `autoUpdate`。

168* **種子項目優先**：在每次啟動時，種子中聲明的市場會覆蓋使用者的同名項目。使用者使用 `claude plugin disable` 而不是移除市場來選擇退出種子外掛程式。

169* **更新和移除失敗**：`claude plugin marketplace update <name>` 和在種子市場上不帶 `--scope` 的 `remove` 失敗，並顯示命名種子目錄的訊息。

170* **政策仍適用**：[允許清單和封鎖清單](#restrict-what-users-can-install)也檢查種子市場的記錄來源。允許您建置種子的來源。

171

172對於沒有出站 git 存取的車隊，將種子與共享掛載上的 `directory` 或 `file` 市場來源結合。同時設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`，這也會關閉[外掛程式自動更新](/docs/zh-TW/plugins/loading#when-auto-update-runs)。如果有代理可用，請參閱[代理配置](/docs/zh-TW/network-config#proxy-configuration)以了解要設定的變數。

173

174<h2 id="restrict-what-users-can-install">

175 限制使用者可以安裝的內容

176</h2>

177

178受管 `strictKnownMarketplaces` 允許清單和 `blockedMarketplaces` 封鎖清單決定外掛程式可能來自哪些市場來源。市場的來源是 Claude Code 從中擷取的 git 儲存庫、URL 或本機路徑。兩個清單都匹配外掛程式來自的市場的來源，而不是該市場內的外掛程式自己的項目。

179

180如需常見的鎖定，允許官方市場和您自己的，請參閱[允許官方市場和您自己的](#allow-the-official-marketplace-and-your-own)。將其與[`disableSideloadFlags`](#control-matrix)配對，以便使用者無法從本機目錄或 URL 載入外掛程式。

181

182兩個清單在任何東西下載之前和在工作階段開始時應用：

183

184* **下載前**：當使用者新增市場以及在每次安裝、更新、重新整理和自動更新時應用清單。

185* **在工作階段開始時**：清單再次應用於已安裝的外掛程式，因此已安裝的外掛程式其市場來源不再符合不會載入。`/plugin` 使用 `Marketplace "<name>" is not in the allowed marketplace list` 或 `Marketplace "<name>" is blocked by enterprise policy` 列出它。

186

187兩個清單的執行位置取決於您在何處設定它們：

188

189* **claude.ai 管理員主控台**：Claude Code 在[讀取伺服器受管設定](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)的工作階段中執行兩個清單。claude.ai 也在您組織中的任何人從 git 儲存庫在 claude.ai 上新增新市場，或從 Claude Desktop 應用程式外其 Code 標籤中的**自訂**新增時檢查它們。這涵蓋成員為自己的帳戶新增的市場和在[**組織設定 > 外掛程式**](https://claude.ai/admin-settings/plugins)下為整個組織新增的市場。claude.ai 拒絕允許清單不允許或封鎖清單命名的儲存庫。它不重新檢查在您設定清單之前在任一位置新增的市場，也不檢查上傳的外掛程式。

190* **受管設定檔案、OS 級政策或其他受管來源**：Claude Code 在讀取該來源的位置執行兩個清單。claude.ai 不讀取它。

191

192當設定任何允許清單時，或封鎖清單命名除[`skills-dir`](#blocklist-with-blockedmarketplaces)之外的任何來源時，Claude Code 找不到其市場的外掛程式不會載入。`/plugin` 為其顯示政策錯誤而不是找不到錯誤。常見情況是市場沒有人註冊的過時 `enabledPlugins` 項目。

193

194<h3 id="control-matrix">

195 控制矩陣

196</h3>

197

198該表列出每個外掛程式政策金鑰、它執行的內容以及它無法執行的內容。

199

200| 金鑰 | 它執行的內容 | 它無法執行的內容 |

201| :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |

202| `strictKnownMarketplaces` | 市場來源的允許清單。`[]` 阻止每個來源，包括官方市場。別名：`allowedMarketplaces` | 不註冊市場、限制允許市場內的項目或阻止 `--plugin-dir` |

203| `blockedMarketplaces` | 市場來源的封鎖清單，在允許清單之前檢查 | 不阻止已從不符合的來源註冊的市場 |

204| `syncClaudeAiPlugins` | 設定 `false` 以停止 Claude Code 下載和載入為每個使用者帳戶[從 claude.ai 同步](/docs/zh-TW/plugins/loading#synced-plugins)的外掛程式。需要 Claude Code v2.1.273 或更新版本 | 不關閉一個同步外掛程式。為此，在[`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins)中設定 `"<name>@synced": false` |

205| `enabledPlugins` | `true` 強制啟用，`false` 在每個範圍阻止並隱藏外掛程式 | 不安裝其市場未註冊或不允許的外掛程式 |

206| `disableSideloadFlags` | 拒絕 `--plugin-dir`、`--plugin-url`、`--agents`、Agent SDK `plugins` 選項和非 SDK `--mcp-config` 在啟動時，並以相同方式拒絕[`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-TW/env-vars#variables)變數中命名的資料夾 | 不限制 `.mcp.json`、`claude mcp add` 或 SDK 提供的伺服器。將其與[`allowedMcpServers`](/docs/zh-TW/managed-mcp)配對 |

207| `disableCommandPluginSources` | 阻止具有 `command` 來源的外掛程式安裝、更新或載入。`command` 來源是其外掛程式目錄由在機器上執行命令產生的來源。未設定時，它採用 `allowManagedHooksOnly` 的值 | 不影響其他來源類型 |

208| `allowManagedHooksOnly` | 限制哪些 hooks 執行。請參閱[`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) | 不信任使用者自己啟用的外掛程式中的 hooks |

209| `strictPluginOnlyCustomization` | 阻止不來自外掛程式、受管設定或 Claude Code 內建的技能、代理、hooks 和 MCP 伺服器。設定 `true` 以涵蓋所有四種類型，或 `skills`、`agents`、`hooks` 和 `mcp` 值的陣列（例如 `["skills", "hooks"]`）以涵蓋某些 | 不限制使用者安裝的外掛程式。將其與 `strictKnownMarketplaces` 配對 |

210| `pluginSuggestionMarketplaces` | 其外掛程式可能作為安裝建議出現的市場。請參閱[推薦外掛程式](#recommend-plugins) | 不影響內建提示 |

211| `pluginTrustMessage` | 將您的文字附加到 `/plugin` 在外掛程式安裝前顯示的信任警告 | 不改變警告自己的文字 |

212| `allowedChannelPlugins` | 替換允許推送頻道訊息的預設外掛程式清單。需要 `channelsEnabled: true` | 請參閱[限制哪些頻道外掛程式可以執行](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run) |

213| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/zh-TW/env-vars) | 停止互動式終端機工作階段自動註冊官方市場 | 不移除已註冊的市場。允許清單和封鎖清單在沒有它的情況下控制相同的自動註冊。在設定它的情況下啟動一次的機器在您取消設定後不會恢復自動註冊 |

214

215表中的每個金鑰都是受管設定，除了 `enabledPlugins`、`syncClaudeAiPlugins` 和 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`：

216

217* **`enabledPlugins`**：您可以在任何範圍設定它，受管設定會鎖定它。

218* **`syncClaudeAiPlugins`**：每個使用者也可以在自己的使用者或本機設定中設定它。請參閱其[設定參考中的範圍](/docs/zh-TW/settings-reference#syncclaudeaiplugins)。

219* **`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`**：這是一個環境變數，您透過[關閉整個車隊的更新](#turn-updates-off-for-the-whole-fleet)下顯示的受管 `env` 區塊提供。

220

221此處的每個設定金鑰在[設定參考](/docs/zh-TW/settings-reference)中都有一個項目。

222

223<h4 id="aliases-for-the-marketplace-keys">

224 市場金鑰的別名

225</h4>

226

227`strictKnownMarketplaces` 也可以拼寫為 `allowedMarketplaces`，`extraKnownMarketplaces` 也可以拼寫為 `additionalMarketplaces`。

228

229* **版本**：別名需要 Claude Code v2.1.232 或更新版本，較舊的用戶端會忽略它們。在混合車隊讀取的檔案中，保持規範名稱。

230* **兩個拼寫都設定**：當檔案設定兩個拼寫時，規範金鑰的值適用。

231

232<h3 id="allowlist-with-strictknownmarketplaces">

233 使用 `strictKnownMarketplaces` 的允許清單

234</h3>

235

236將允許清單設定為這些來源物件的清單。大多數項目完全匹配，`hostPattern` 和 `pathPattern` 項目作為正規表達式匹配，`github` 擁有者萬用字元按擁有者匹配：

237

238* **`github`**：`{ "source": "github", "repo": "your-org/approved-plugins" }`，帶有可選的 `ref` 和 `path`。

239* **`github` 擁有者萬用字元**：`{ "source": "github", "repo": "your-org/*" }` 匹配該擁有者下的每個儲存庫。`*` 必須代表整個儲存庫名稱。Claude Code 忽略 `*/plugins` 和 `your-org/tools-*` 等項目作為無效，因此它們不匹配任何內容。需要 Claude Code v2.1.223 或更新版本。

240* **`git`**：`{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }`，帶有可選的 `ref` 和 `path`。

241* **`url`**：`{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }`，帶有可選的 `headers`。

242* **`file` 和 `directory`**：`{ "source": "file", "path": "/opt/marketplace/marketplace.json" }` 或 `{ "source": "directory", "path": "/opt/marketplace/plugins" }`，帶有絕對路徑。

243* **`hostPattern`**：`{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }`，針對 `github`、`git` 和 `url` 來源的主機進行匹配。該模式在主機名中的任何地方匹配，因此使用 `^` 和 `$` 進行錨定如所示以匹配整個主機。`github` 來源始終計為 `github.com`。對於開發人員建立自己的市場的 GitHub Enterprise Server 或 GitLab 主機，使用 `hostPattern` 項目。[GHES 頁面](/docs/zh-TW/github-enterprise-server#allowlist-ghes-marketplaces-in-managed-settings)有工作範例。

244* **`pathPattern`**：`{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }`，針對 `file` 和 `directory` 來源的 `path` 進行匹配。該模式在路徑中的任何地方匹配，因此以 `^` 開頭以固定目錄前綴。`".*"` 允許每個本機路徑。

245* **`skills-dir`**：`{ "source": "skills-dir" }` 在設定允許清單時保持[技能目錄外掛程式](#keep-skills-directory-plugins-loading)載入，並不匹配任何市場。

246

247<h4 id="how-entries-match">

248 項目如何匹配

249</h4>

250

251`url` 項目在其 `url` 值上匹配；`headers` 不進行比較。對於 `github` 和 `git` 項目，`repo` 或 `url`、`ref` 和 `path` 必須全部匹配，或在兩側都不存在：

252

253* 沒有 `ref` 的項目不涵蓋具有 `ref: "main"` 的來源。

254* `your-org/your-marketplace` 的項目不涵蓋複製相同儲存庫的 `git` URL。

255* 尾部斜線、`.git` 後綴或 `ssh://` 代替 `https://` 是不同的值。當市場可以由多個 URL 複製時，更喜歡 `hostPattern` 項目。

256

257擁有者萬用字元項目遵循 `ref` 的確切規則，並匹配儲存庫內的任何 `path`，除非項目固定一個。萬用字元匹配在允許清單上區分大小寫。

258

259<h4 id="keep-skills-directory-plugins-loading">

260 保持技能目錄外掛程式載入

261</h4>

262

263技能目錄外掛程式是使用者在 `~/.claude/skills/` 或專案的 `.claude/skills/` 下保持的外掛程式，位於帶有 `.claude-plugin/plugin.json` 的資料夾中。如果您設定任何沒有 `{ "source": "skills-dir" }` 項目的允許清單，它們會停止載入。純[技能](/docs/zh-TW/skills)，意思是沒有該清單的 `SKILL.md`，保持載入。

264

265<h4 id="marketplaces-hosted-on-claude-ai">

266 託管在 claude.ai 上的市場

267</h4>

268

269允許清單和封鎖清單按其主機匹配[託管在 claude.ai 上的市場](/docs/zh-TW/plugins/install#add-from-claude-ai)。若要允許或阻止一個，請新增與 `claude.ai` 匹配的 `hostPattern` 項目到 `strictKnownMarketplaces` 或 `blockedMarketplaces`。在允許清單上，此類項目允許您組織的 claude.ai 市場和 claude.ai 預設市場，但不允許由成員自己的 claude.ai 上傳組成的市場或其範圍 claude.ai 未聲明的市場。需要 Claude Code v2.1.273 或更新版本。

270

271<h4 id="lock-every-source-out">

272 鎖定每個來源

273</h4>

274

275空允許清單 `[]` 鎖定每個市場來源，包括官方市場。

276

277此鎖定不涵蓋[從 claude.ai 同步](/docs/zh-TW/plugins/loading#synced-plugins)的外掛程式，Claude Code 從每個使用者的帳戶而不是市場下載。若要同時停止這些，請在受管設定中將[`syncClaudeAiPlugins`](/docs/zh-TW/settings-reference#syncclaudeaiplugins)設定為 `false`，或在 claude.ai 上為您的組織關閉技能。

278

279<h3 id="blocklist-with-blockedmarketplaces">

280 使用 `blockedMarketplaces` 的封鎖清單

281</h3>

282

283`blockedMarketplaces` 採用與[`strictKnownMarketplaces`](#allowlist-with-strictknownmarketplaces)相同的來源物件，並首先檢查，因此兩個清單上的來源被阻止。封鎖清單匹配比允許清單匹配更寬：

284

285* Git URL 被規範化，因此一個 `github.com` 儲存庫的 `git@` 和 `https://` 形式、`.git` 後綴和尾部斜線都匹配相同的項目。

286* `github` 項目也阻止等效的 `git` URL，反之亦然。

287* 對於 `owner/*` 項目，擁有者比較不區分大小寫。

288* 沒有 `ref` 或 `path` 的項目阻止它匹配的儲存庫的每個 ref 和 path。

289

290此項目阻止一個 GitHub 擁有者下的每個儲存庫：

291

292```json theme={null}

293{

294 "blockedMarketplaces": [

295 { "source": "github", "repo": "untrusted-org/*" }

296 ]

297}

298```

299

300`blockedMarketplaces` 中的 `url` 項目也在使用者新增 Claude Code [複製而不是擷取](/docs/zh-TW/plugins/cli-reference#plugin-marketplace-add)的 `https://` 儲存庫 URL 時應用，例如裸 `github.com` 或 `gitlab.com` 儲存庫 URL。如果項目命名該 URL，使用者無法新增它。匹配忽略 `.git` 後綴和使用者在 `#` 後附加的任何 ref。需要 Claude Code v2.1.232 或更新版本。

301

302此處的 `{ "source": "skills-dir" }` 項目停止[技能目錄外掛程式](#keep-skills-directory-plugins-loading)從 `~/.claude/skills/` 和專案的 `.claude/skills/` 載入。

303

304僅命名該項目的封鎖清單不計為活躍限制，因此它不[停止 Claude Code 找不到其市場的外掛程式](#restrict-what-users-can-install)載入。

305

306<h3 id="allow-the-official-marketplace-and-your-own">

307 允許官方市場和您自己的

308</h3>

309

310大多數組織允許官方市場和他們自己的，並註冊兩者以便每台機器都有它們。此受管設定政策允許兩個市場，註冊兩者，強制啟用兩個外掛程式，並拒絕 `--plugin-dir`：

311

312```json theme={null}

313{

314 "strictKnownMarketplaces": [

315 { "source": "github", "repo": "anthropics/claude-plugins-official" },

316 { "source": "github", "repo": "your-org/*" },

317 { "source": "skills-dir" }

318 ],

319 "extraKnownMarketplaces": {

320 "claude-plugins-official": {

321 "source": { "source": "github", "repo": "anthropics/claude-plugins-official" }

322 },

323 "your-marketplace": {

324 "source": { "source": "github", "repo": "your-org/your-marketplace" }

325 }

326 },

327 "enabledPlugins": {

328 "code-formatter@your-marketplace": true,

329 "deploy-helper@your-marketplace": true

330 },

331 "disableSideloadFlags": true

332}

333```

334

335在具有此政策的機器上，新增清單外的任何來源，例如 `/plugin marketplace add https://example.com/other-marketplace.git`，失敗並顯示包含 `is blocked by enterprise policy` 的訊息，後跟允許的來源。`claude --plugin-dir ./x` 退出並顯示命名 `disableSideloadFlags` 的訊息。

336

337`{ "source": "skills-dir" }` 項目在此允許清單下保持[技能目錄外掛程式](#keep-skills-directory-plugins-loading)載入。移除該項目，它們停止載入。

338

339使用明確的 `extraKnownMarketplaces` 項目註冊兩個市場，如此政策所做的，而不是依賴允許清單或官方市場自行註冊：

340

341* **允許清單不註冊任何內容**：`extraKnownMarketplaces` 項目執行，它本身必須通過允許清單。Claude Code 拒絕註冊受管市場，其來源允許清單不匹配。

342* **官方市場僅在互動式終端機工作階段中自行註冊**：即使在那裡，它也僅在允許清單允許時註冊。`-p` 執行或附加到雲端工作階段的終端機永遠不會註冊它。

343* **被阻止的嘗試被記住**：如果機器曾在阻止官方市場的政策下執行，Claude Code 會記錄被阻止的嘗試，並在政策更改後不重試。`[]` 鎖定是一個此類政策。該機器僅透過此政策中的 `extraKnownMarketplaces` 項目、其中一個外掛程式的 `enabledPlugins` 項目或手動 `/plugin marketplace add` 再次註冊它。

344

345<h2 id="set-update-policy">

346 設定更新政策

347</h2>

348

349您可以按市場、整個車隊或透過發佈頻道按使用者群組設定更新政策。

350

351<h3 id="turn-auto-update-on-or-off-per-marketplace">

352 按市場開啟或關閉自動更新

353</h3>

354

355外掛程式自動更新在啟動後在背景中為開啟它的市場執行。如需預設開啟它的市場，請參閱[自動更新何時執行](/docs/zh-TW/plugins/loading#when-auto-update-runs)。若要為車隊決定，請在受管 `extraKnownMarketplaces` 項目上設定 `"autoUpdate": true` 或 `false`：

356

357* 如果受管項目設定欄位，Claude Code 拒絕使用者的 `/plugin` 切換並顯示以 `Auto-update for '<name>' is set by` 開頭的錯誤。

358* 如果受管項目保留欄位未設定，使用者的切換保持。

359

360<h3 id="turn-updates-off-for-the-whole-fleet">

361 關閉整個車隊的更新

362</h3>

363

364若要為每個市場關閉外掛程式自動更新，請在受管 `env` 區塊中設定 `DISABLE_AUTOUPDATER`，如此範例所做的。相同變數也停止 Claude Code 自己的更新：

365

366```json theme={null}

367{

368 "env": {

369 "DISABLE_AUTOUPDATER": "1"

370 }

371}

372```

373

374若要停止 Claude Code 自己的更新但保持外掛程式自動更新，請將 `"FORCE_AUTOUPDATE_PLUGINS": "1"` 新增到相同區塊。其他[停止外掛程式自動更新的環境變數](/docs/zh-TW/plugins/loading#when-auto-update-runs)以相同方式工作。

375

376`DISABLE_AUTOUPDATER` 不涵蓋具有[`command` 來源](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)的外掛程式。Claude Code 每個工作階段重新執行每個啟用的命令，並在其更改時安裝輸出。如需停止這些執行的內容，請參閱[命令來源何時重新執行](/docs/zh-TW/plugins/loading#when-a-command-source-re-runs)。

377

378<h3 id="assign-release-channels-to-user-groups">

379 將發佈頻道指派給使用者群組

380</h3>

381

382若要執行穩定和早期存取頻道，請託管兩個指向相同外掛程式的不同 ref 的市場。然後透過單獨的端點受管設定或閘道政策為每個使用者群組提供自己的市場。來自管理員主控台的伺服器受管設定[適用於組織中的每個使用者](/docs/zh-TW/server-managed-settings#current-limitations)，因此它們無法為不同的群組指派不同的設定。

383

384* 將單獨的[端點受管設定](/docs/zh-TW/managed-settings#delivery-mechanisms)（例如受管設定檔案或 MDM 設定檔）部署到每個群組的裝置。若要檢查每個群組檔案或設定檔是否適用於也有組織範圍來源的裝置，請參閱[Claude Code 如何組合受管來源](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)。

385* 為每個群組定義一個 [Claude 應用程式閘道政策](/docs/zh-TW/claude-apps-gateway-config#managed)。閘道應用第一個符合使用者的匹配規則的政策，因此排序政策以便每個使用者到達其群組的政策。該政策的 `extraKnownMarketplaces` 對應不與任何其他政策的合併，因此列出群組需要的每個市場，而不僅僅是其頻道市場。

386

387使用任一機制，穩定群組接收此配置：

388

389```json theme={null}

390{

391 "extraKnownMarketplaces": {

392 "stable-tools": {

393 "source": { "source": "github", "repo": "your-org/stable-tools" }

394 }

395 }

396}

397```

398

399早期存取群組改為接收 `latest-tools`。若要設定兩個市場，請參閱[執行發佈頻道](/docs/zh-TW/plugins/host-marketplace#run-release-channels)。

400

401<h2 id="recommend-plugins">

402 推薦外掛程式

403</h2>

404

405市場擁有者可以將 `relevance` 訊號附加到項目，以便 Claude Code 在專案符合時建議外掛程式。

406

407來自市場的建議僅在其在使用者的機器上註冊、您在受管設定中的 `pluginSuggestionMarketplaces` 中列出其名稱，並且您在相同政策中聲明其來源時出現。聲明來源作為市場的 `extraKnownMarketplaces` 項目或允許清單項目。官方市場僅需要名稱。請參閱[在受管設定中啟用建議](/docs/zh-TW/plugins/relevance#enable-suggestions-in-managed-settings)。

408

409<h2 id="audit-and-review">

410 稽核和檢視

411</h2>

412

413OpenTelemetry 事件和 Analytics API 告訴您您的車隊安裝和執行的內容。

414

415如需外掛程式可以在機器上執行的內容以及每個信任層允許的內容，在批准市場之前請閱讀[外掛程式安全性](/docs/zh-TW/plugins/security)。

416

417<h3 id="opentelemetry-events">

418 OpenTelemetry 事件

419</h3>

420

421`claude_code.plugin_installed` 記錄每次安裝，`claude_code.plugin_loaded` 記錄每個啟用的外掛程式在工作階段開始時。除非您設定 `OTEL_LOG_TOOL_DETAILS=1`，否則兩個事件都會編輯或省略第三方外掛程式和市場名稱，如[您後端中的編輯外掛程式名稱](/docs/zh-TW/plugins/measure#redacted-plugin-names-in-your-backend)所示。欄位清單位於[外掛程式已安裝事件](/docs/zh-TW/monitoring-usage#plugin-installed-event)和[外掛程式已載入事件](/docs/zh-TW/monitoring-usage#plugin-loaded-event)。

422

423<h3 id="analytics-api">

424 Analytics API

425</h3>

426

427在 Enterprise 計畫上，`GET /v1/organizations/analytics/plugins` 返回跨 Claude Code 和 Cowork 的每個外掛程式、每天的安裝和調用計數。您可以按使用者或 RBAC 群組對計數進行分組。到達 Anthropic 而沒有外掛程式名稱的外掛程式活動出現在一個聚合 `third-party` 列中。請參閱[端點參考](https://platform.claude.com/docs/en/api/admin/analytics/plugins/list)和[以程式設計方式存取資料](/docs/zh-TW/analytics#access-data-programmatically)以了解它需要的金鑰。

428

429<h2 id="plan-for-what-managed-settings-can’t-enforce">

430 規劃受管設定無法執行的內容

431</h2>

432

433這些來自安全檢視的請求在目前設定架構中沒有專用金鑰。最接近的現有控制項是：

434

435* **按使用者或按群組目標**：每個外掛程式金鑰適用於接收設定的每個使用者。伺服器受管設定為每個組織提供一個配置。對於按群組政策，使用單獨的端點受管設定或閘道政策，如[將發佈頻道指派給使用者群組](#assign-release-channels-to-user-groups)下所述。

436* **限制允許市場內的項目**：允許清單匹配市場來源。若要從允許的市場阻止一個外掛程式，請在受管 `enabledPlugins` 中將其設定為 `false`。

437* **隱藏 `/plugin`**：沒有金鑰禁用命令。最接近的等效項結合僅命名您的市場的允許清單、您提供的外掛程式的受管 `enabledPlugins` 項目和 `disableSideloadFlags`。

438* **透過允許清單控制 `--plugin-dir`**：允許清單不涵蓋 `--plugin-dir`。`disableSideloadFlags` 執行。

439* **透過這些金鑰執行 claude.ai 外掛程式切換**：[**組織設定 > 外掛程式與技能**](https://claude.ai/admin-settings/skills?tab=inventory)不設定此頁面上的金鑰。成員和您的組織在那裡開啟的內容作為[同步外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)到達 CLI，它們有自己的控制項。

440

441<h2 id="troubleshoot-policy">

442 疑難排解政策

443</h2>

444

445如果外掛程式政策在機器上的行為不符合預期，請首先檢查這些症狀：

446

447* **受管檔案未解析**：當 `managed-settings.json` 不是有效 JSON 時，Claude Code 拒絕啟動並列印[命名檔案的錯誤](/docs/zh-TW/errors#managed-settings-document-could-not-be-parsed)。解析但有一個無效項目的檔案保持其政策的其餘部分。請參閱[受管設定中的無效項目](/docs/zh-TW/managed-settings#invalid-entries-in-managed-settings)。

448* **受管來源未載入**：執行 `/status` 並在 `Setting sources` 行中尋找 `Enterprise managed settings`。如果遺失，來源未載入。

449* **使用者報告 `blocked by enterprise policy`**：訊息命名市場或其來源。對於允許清單，它也列出允許的來源。使用者面向的項目位於[疑難排解外掛程式](/docs/zh-TW/plugins/troubleshooting)。

450* **使用者在 `~/.claude/settings.json` 中禁用的外掛程式仍然載入**：另一個設定來源重新啟用它，例如強制啟用它的受管 `enabledPlugins` 項目。`/plugin` 和 `claude plugin list` 顯示 `Disabled in ~/.claude/settings.json but still loads` 與該設定來源。

451

452<h2 id="next-steps">

453 後續步驟

454</h2>

455

456* [市場參考](/docs/zh-TW/plugins/marketplace-reference#marketplace-sources)：`extraKnownMarketplaces`、`strictKnownMarketplaces` 和 `blockedMarketplaces` 接受的 `source` 值

457* [託管和維護市場](/docs/zh-TW/plugins/host-marketplace)：執行您的政策指向的市場

458* [外掛程式安全性和信任](/docs/zh-TW/plugins/security)：外掛程式可以在機器上執行的內容以及在安裝前如何檢視一個

459* [伺服器受管設定](/docs/zh-TW/server-managed-settings)：從 claude.ai 管理員主控台提供這些金鑰

460* [疑難排解外掛程式](/docs/zh-TW/plugins/troubleshooting#blocked-by-your-organization)：政策阻止使用者時看到的訊息

plugins/overview.md +142 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Plugins 概述

7> 了解什麼是 Claude Code plugin，何時需要使用 plugin 而不是獨立的 skill 或 MCP 伺服器，以及應該閱讀哪個頁面來安裝或建立 plugin。

9Claude Code plugin 是一個目錄，包含 skills、agents、hooks、MCP 伺服器或其他元件，Claude Code 會將其作為一個單位進行安裝和載入。大多數 plugins 來自 marketplace，marketplace 是一個目錄，列出 plugins 及其取得位置。您也可以從某人提供給您的資料夾中載入 plugin，或[建立您自己的](/docs/zh-TW/plugins/create)。

11<Note>

12 如果您使用 claude.ai 聊天或 Cowork 而不是 Claude Code，請參閱[claude.ai 和 Cowork 中的 Plugins](https://claude.com/docs/plugins/overview)。

13</Note>

15若要立即試用 plugin，請在 Claude Code 終端機工作階段中執行 `/plugin`，並從 **Discover** 標籤安裝一個，該標籤列出來自 Anthropic 官方 marketplace 和您已新增的任何 marketplace 的 plugins。從那裡：

17* [安裝和管理 plugins](/docs/zh-TW/plugins/install)：完整的安裝步驟、範圍和其他介面

18* [建立 plugin](/docs/zh-TW/plugins/create)：建立您自己的

19* [決定您是否需要 plugin](#decide-whether-you-need-a-plugin)：plugin 是否是您想要的正確工具

21<h2 id="understand-what-a-plugin-is">

22 了解什麼是 plugin

23</h2>

25Plugin 是一個元件目錄，通常帶有 manifest。Manifest 是位於 `.claude-plugin/plugin.json` 的 JSON 檔案，它為 plugin 提供名稱，並可以新增版本、描述和其他[中繼資料](/docs/zh-TW/plugins/manifest-reference)。元件是 plugin 新增到 Claude Code 的內容，例如：

27* [**Skills**](/docs/zh-TW/plugins/components#skills)：`SKILL.md` 指令，Claude 在相關時載入，您也可以作為命令執行

28* [**Agents**](/docs/zh-TW/plugins/components#agents)：Claude 可以委派給的子代理定義

29* [**Hooks**](/docs/zh-TW/plugins/components#hooks)：Claude Code 在其生命週期中的特定點執行的命令，例如每次編輯後

30* [**MCP servers**](/docs/zh-TW/plugins/components#mcp-servers)：工具伺服器，Claude Code 在啟用 plugin 時連接到

32此圖表顯示一個名為 `my-plugin` 的 plugin，其中包含上述每種元件之一，以及 plugin 載入後您從每個檔案獲得的內容。

34<img src="https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugin-directory.svg?fit=max&auto=format&n=2Q_GtOEovg5qaBem&q=85&s=f623b64e82713b830e48174f0a922888" className="dark:hidden" alt="Diagram in two columns joined by five straight arrows. Left, the directory of a plugin named my-plugin, holding a manifest at .claude-plugin/plugin.json, skills/review/SKILL.md, agents/reviewer.md, hooks/hooks.json, .mcp.json, and other components. Right, what each file gives you in your session: the manifest sets the plugin name, my-plugin; the skill runs as /my-plugin:review; the agent file is a subagent Claude can delegate to; the hooks file holds hooks that run on lifecycle events; and .mcp.json adds an MCP server that gives Claude tools." width="760" height="336" data-path="images/plugin-directory.svg" />

36<img src="https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugin-directory-dark.svg?fit=max&auto=format&n=2Q_GtOEovg5qaBem&q=85&s=17ee2bd45b63154fcc148ae1d1f736d8" className="hidden dark:block" alt="Diagram in two columns joined by five straight arrows. Left, the directory of a plugin named my-plugin, holding a manifest at .claude-plugin/plugin.json, skills/review/SKILL.md, agents/reviewer.md, hooks/hooks.json, .mcp.json, and other components. Right, what each file gives you in your session: the manifest sets the plugin name, my-plugin; the skill runs as /my-plugin:review; the agent file is a subagent Claude can delegate to; the hooks file holds hooks that run on lifecycle events; and .mcp.json adds an MCP server that gives Claude tools." width="760" height="336" data-path="images/plugin-directory-dark.svg" />

38如需 plugin 可以包含的每種元件類型及其示例，請參閱 [Plugin 元件](/docs/zh-TW/plugins/components)。若要查看每個部分在 plugin 目錄中的位置，請使用該頁面上的 [plugin 探索工具](/docs/zh-TW/plugins/components#explore-the-plugin-directory)。

40<h3 id="decide-whether-you-need-a-plugin">

41 決定您是否需要 plugin

42</h3>

44Skills、子代理、hooks 和 MCP 伺服器都可以獨立運作，無需 plugin。例如，您在 `~/.claude/skills/` 中保存的 skill 在您機器上的每個專案中都可用。若要單獨設定其中一個，請參閱 [Skills](/docs/zh-TW/skills)、[Subagents](/docs/zh-TW/sub-agents)、[Hooks](/docs/zh-TW/hooks-guide) 或 [MCP](/docs/zh-TW/mcp)。

46當您想要將多個 skills、子代理、hooks 或 MCP 伺服器打包為一個單位時，請使用 plugin。安裝一個以獲得某人建立的設定，只需一個命令並從其 marketplace 獲得更新。建立一個以將您自己的設定提供給隊友，在許多專案中安裝它，或發佈版本化版本。

48<h3 id="what-an-enabled-plugin-adds-to-your-sessions">

49 啟用的 plugin 對您的工作階段的影響

50</h3>

52啟用的 plugin 是每個工作階段的一部分，不僅是您使用它的工作階段。這有幾個後果值得在安裝之前了解：

54* **上下文和使用情況**：對於每個 skill、agent 和 [Claude 可以自行調用](/docs/zh-TW/skills#control-who-invokes-a-skill)的命令，名稱和描述都在 Claude 的每個回合的上下文中，以便 Claude 知道它存在。這些令牌計入您的使用情況，並在[上下文視窗](/docs/zh-TW/context-window)中留下更少的空間，即使在 plugin 中沒有任何內容執行的工作階段中也是如此。skill 或 agent 的完整文本僅在使用時載入。Plugin 的 MCP 伺服器每個回合新增的內容遵循 [MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。

55* **程序**：plugin 定義的 MCP 伺服器在啟用它的每個工作階段旁邊執行，其 hooks 在其事件處觸發。

56* **權限**：plugin 執行的內容以您的身份執行。請參閱 [Plugin 安全性和信任](/docs/zh-TW/plugins/security)，了解首先要檢查的內容。

58您可以在每個階段檢查 plugin 的佔用空間：

60* **安裝前**：從 `/plugin` 中的 **Marketplaces** 標籤開啟 plugin。Anthropic 官方 marketplace 中的 Plugins 在那裡顯示 **Context cost** 估計。

61* **安裝後**：[測量 plugin 的成本](/docs/zh-TW/plugins/measure#measure-what-a-plugin-costs)顯示如何讀取 plugin 的佔用空間，**Installed** 標籤的 **Not used recently** 群組列出您可以關閉的 plugins。

62* **在不卸載的情況下停止它**：使用 `/plugin` 或在您的 shell 中使用 `claude plugin disable` 停用 plugin。請參閱[管理已安裝的 plugins](/docs/zh-TW/plugins/install#manage-installed-plugins)。

64<h2 id="get-plugins-from-a-marketplace">

65 從 marketplace 取得 plugins

66</h2>

68Marketplace 是一個儲存庫或目錄，具有 `.claude-plugin/marketplace.json` 檔案，該檔案列出 plugins 及其取得位置。它是一個目錄，不是託管商店。您新增一次 marketplace，然後按名稱從中安裝 plugins，例如 `commit-commands@claude-plugins-official`。

70<Note>

71 Plugin marketplace 不是 [Claude Marketplace](https://claude.com/marketplace)。Claude Marketplace 是 claude.com/marketplace 上的網站，您可以在其中瀏覽 plugins、連接器、合作夥伴產品和服務合作夥伴。它不是您使用 `/plugin marketplace add` 新增的 marketplace。

72</Note>

74Claude Code 在您第一次啟動互動式終端機工作階段時新增 Anthropic 的官方 marketplace，除非[受管原則](/docs/zh-TW/plugins/org#allow-the-official-marketplace-and-your-own)阻止它。Claude Code 不會自行新增任何其他 marketplace，包括 Anthropic 的社群和演示 marketplaces。若要區分三個 Anthropic marketplaces，請閱讀 [Anthropic 的 marketplaces](/docs/zh-TW/plugins/anthropic-marketplaces)。若要查看官方 marketplace 列出的內容，請在工作階段中開啟 `/plugin` 的 **Discover** 標籤或瀏覽 [Claude Marketplace](https://claude.com/marketplace/plugins)。

76此圖表顯示從 marketplace 到您的工作階段的路徑。Marketplace 列出 plugin，您安裝該 plugin，Claude Code 載入其元件。

78<img src="https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugins-model.svg?fit=max&auto=format&n=2Q_GtOEovg5qaBem&q=85&s=4196344954b7c2e27fc0bd6a9a1113a1" className="dark:hidden" alt="Diagram of the marketplace path in three boxes, left to right. A marketplace, a catalog of plugins, lists a plugin. The plugin is one directory installed as a unit, holding skills, agents, hooks, MCP servers, and other components. You install the plugin into Claude Code, which loads its components." width="760" height="252" data-path="images/plugins-model.svg" />

80<img src="https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugins-model-dark.svg?fit=max&auto=format&n=2Q_GtOEovg5qaBem&q=85&s=f6cdefe1fc05daf3b253d26e9f3f70f6" className="hidden dark:block" alt="Diagram of the marketplace path in three boxes, left to right. A marketplace, a catalog of plugins, lists a plugin. The plugin is one directory installed as a unit, holding skills, agents, hooks, MCP servers, and other components. You install the plugin into Claude Code, which loads its components." width="760" height="252" data-path="images/plugins-model-dark.svg" />

82[安裝和管理 plugins](/docs/zh-TW/plugins/install#install-a-plugin) 有您執行 Claude Code 的每個位置的安裝步驟。在您開發 plugin 時，您不需要 marketplace：使用 `--plugin-dir` 直接從其資料夾載入它，如[在沒有 marketplace 的情況下開發](/docs/zh-TW/plugins/create#develop-without-a-marketplace)所示。

84<h3 id="make-an-installed-plugin-available-in-your-session">

85 在您的工作階段中提供已安裝的 plugin

86</h3>

88在您安裝的 plugin 為您提供可以執行的 skill 之前，它必須存在於以下每個層級：

90* **設定**：您的設定列出您已新增的 marketplaces 和啟用的 plugins。

91* **磁碟**：`~/.claude/plugins/` 保存 Claude Code 已取得和安裝的內容。

92* **工作階段**：plugins 在啟動時載入，或當您[重新載入 plugins](/docs/zh-TW/plugins/loading#check-which-stage-a-plugin-reached)時。

94閱讀 [Plugin 載入參考](/docs/zh-TW/plugins/loading)，了解每個層級的規則，包括哪個設定檔優先以及檔案在磁碟上的位置。

96<h2 id="tell-anthropic’s-marketplaces-from-third-party-ones">

97 區分 Anthropic 的 marketplaces 和第三方 marketplaces

98</h2>

100Marketplace 的名稱將其放在三個層級之一中。Claude Code 僅接受來自 `github.com/anthropics/` 儲存庫的 marketplaces 的官方和社群名稱：

101

102* **官方**：具有 Anthropic [官方 marketplace 名稱](/docs/zh-TW/plugins/security#official-marketplace-names)之一的 marketplaces，包括 `claude-plugins-official` 和演示 marketplace `claude-code-plugins`。

103* **社群**：具有 Anthropic 社群名稱之一的 marketplaces，例如 `claude-community`。[按名稱識別 Anthropic 的 marketplaces](/docs/zh-TW/plugins/security#marketplace-tiers) 列出它們。

104* **第三方**：所有其他 marketplaces。您的同事或您的組織發佈的 marketplace 是第三方。

105

106無論層級如何，您安裝的 plugin 都可以使用您的使用者權限執行程式碼。閱讀 [Plugin 安全性和信任](/docs/zh-TW/plugins/security)，了解如何在安裝 plugin 之前檢查它。

107

108通過[受管設定](/docs/zh-TW/settings#settings-files)，組織可以允許列表或阻止 marketplaces、強制安裝 plugins 並關閉僅工作階段載入。閱讀[為您的組織管理 plugins](/docs/zh-TW/plugins/org)，了解這些控制項。

109

110<h2 id="understand-install-scopes">

111 了解安裝範圍

112</h2>

113

114當您安裝 plugin 時，您選擇一個範圍，範圍決定誰啟用了 plugin：

115

116* **使用者範圍**：在此電腦上的每個專案中為您啟用

117* **專案範圍**：通過已提交的 `.claude/settings.json` 為在此儲存庫中工作的每個人啟用。每個協作者仍然[在自己的機器上安裝它](/docs/zh-TW/plugins/loading#enabled-in-project-settings-but-not-installed)

118* **本機範圍**：僅在此儲存庫中為您啟用

119

120您在終端機、桌面應用程式的本機工作階段或 VS Code 擴充功能中以使用者範圍安裝的 plugin 在該電腦上的其他兩個中可用，因為所有三個都讀取相同的設定檔。請參閱[選擇安裝範圍](/docs/zh-TW/plugins/install#choose-an-install-scope)，了解如何選擇一個。

121

122雲端工作階段（包括瀏覽器中 claude.ai/code 的工作階段）不會載入您本機設定中的 plugins。如需終端機、VS Code 和桌面應用程式中的安裝步驟，以及雲端工作階段載入的內容，請參閱[安裝 plugin](/docs/zh-TW/plugins/install#install-a-plugin)。

123

124<Note>

125 相同的 plugin 格式也安裝在 claude.ai 和 Cowork 上，其中載入了不同的元件集。對於這些介面，請參閱 claude.com 上的 [claude.ai 和 Cowork 中的 Plugins](https://claude.com/docs/plugins/overview)。

126</Note>

127

128<h2 id="next-steps">

129 後續步驟

130</h2>

131

132大多數人首先從 Anthropic 的官方 marketplace 安裝 plugin，Claude Code 在您第一次啟動互動式終端機工作階段時新增該 marketplace。在終端機工作階段中執行 `/plugin` 以瀏覽它，或遵循[安裝和管理 plugins](/docs/zh-TW/plugins/install)，其中也涵蓋桌面應用程式和 VS Code。若要在開啟 Claude Code 之前查看該 marketplace 中的內容，請在網路上瀏覽 [Claude Marketplace](https://claude.com/marketplace/plugins)。

133

134若要建立您自己的，[建立 plugin](/docs/zh-TW/plugins/create) 從空目錄開始，以工作中的 plugin 結束。

135

136安裝或建立 plugin 後，這些頁面涵蓋接下來的內容：

137

138* **分享您建立的內容**：[發佈和分發 plugin](/docs/zh-TW/plugins/publish)

139* **檢查它是否有效且被使用**：[使用 evals 測試 plugins](/docs/zh-TW/plugin-evals) 和[測量 plugin 成本和使用情況](/docs/zh-TW/plugins/measure)

140* **為您的團隊執行 marketplace**：[建立 marketplace](/docs/zh-TW/plugins/create-marketplace)，然後[託管和維護 marketplace](/docs/zh-TW/plugins/host-marketplace)

141* **為組織設定 plugin 原則**：[為您的組織管理 plugins](/docs/zh-TW/plugins/org)

142* **修復問題**：[Plugin 故障排除](/docs/zh-TW/plugins/troubleshooting)

plugins/publish.md +210 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 發佈和分發外掛程式

7> 透過您自己的市集或 Anthropic 的社群市集發佈 Claude Code 外掛程式，包括發行前檢查清單以及使用者如何取得更新。

9發佈 Claude Code 外掛程式意味著在市集中列出它，市集是一個 JSON 目錄，列出外掛程式及其取得位置，以便其他人可以按名稱安裝它並接收您的更新。您可以執行自己的市集或將您的外掛程式提交到 Anthropic 的社群市集。若要在不發佈的情況下共享外掛程式，請將外掛程式的目錄或其 `.zip` 檔案發送給人們以供他們自行載入。

11本頁面適用於已準備好共享工作外掛程式的作者。

13<Note>

14 這些情況涵蓋在其他頁面上：

16 * **您的外掛程式尚未完成**：從 [建立外掛程式](/docs/zh-TW/plugins/create) 開始

17 * **您維護的 CLI 或 SDK 在官方市集中有外掛程式**：請參閱 [從您的 CLI 推薦您的外掛程式](/docs/zh-TW/plugins/cli-hints)

18</Note>

20從 [選擇分發方式](#choose-how-to-distribute) 開始，比較分發選項。如果您已經知道您的路線，請前往 [準備您的外掛程式以供發行](#prepare-your-plugin-for-release)，然後按照您的路線部分，了解要告訴使用者什麼以及他們如何接收您的更新。

22<h2 id="choose-how-to-distribute">

23 選擇分發方式

24</h2>

26根據誰需要安裝外掛程式來選擇分發選項：

28| 路線 | 誰可以安裝 | 您需要什麼 | 使用者是否自動取得您的更新？ |

29| :------------------------------------------------------ | :-------------------------------------------- | :----------------------------------------------------------- | :------------- |

34自動更新是使用者端的每個市集設定，在背景中取得新版本。

36<h2 id="prepare-your-plugin-for-release">

37 準備您的外掛程式以供發行

38</h2>

40名稱、版本、驗證和從市集安裝決定了發行是否對安裝它的人有效。在第一次發行前檢查它們，然後在之後的每次發行前再次檢查。

42<Steps>

43 <Step title="選擇永久名稱">

44 使用者透過 `name@marketplace` 安裝、啟用和設定您的外掛程式，因此重新命名的外掛程式對每個現有安裝都是不同的外掛程式。選擇 kebab-case 名稱，例如 `deploy-helper`，因為 `claude plugin validate` 會對其他形式發出警告，並將其視為永久名稱。在 `plugin.json` 中設定 `displayName` 以取得使用者看到的標籤。

45 </Step>

47 <Step title="決定您將如何版本化">

48 如果您在 `plugin.json` 中設定 `version` 並稍後推送提交而不更改它，`claude plugin update` 會列印 `<name> is already at the latest version (1.0.0).`，使用者會保留舊副本。要麼在每次發行時遞增 `version`，要麼在 git 託管的市集中省略它，以便 Claude Code 改用提交 SHA。請參閱 [版本和更新](/docs/zh-TW/plugins/loading#versions-and-updates)。

49 </Step>

51 <Step title="驗證">

52 在您的 shell 中，執行 `claude plugin validate --strict ./your-plugin`。乾淨的執行會列印 `✔ Validation passed`。

54 * **在 CI 中**：保留 `--strict`，它也會因為警告（例如未知的資訊清單欄位或缺少 `version`）而以結束代碼 1 失敗執行。如果您在上一步中選擇省略 `version`，請刪除 `--strict`。

55 * **路徑**：驗證報告不以 `./` 開頭的元件路徑。在 hook 命令和 MCP 伺服器設定中，將檔案稱為 `${CLAUDE_PLUGIN_ROOT}/...`。請參閱 [路徑規則](/docs/zh-TW/plugins/manifest-reference#path-rules)。

56 </Step>

58 <Step title="從本機市集安裝它">

59 在您的 shell 中，使用 `claude plugin marketplace add ./path-to-marketplace` 新增列出外掛程式的本機市集，從中安裝外掛程式，並啟動工作階段以確認它載入。

61 * 對於最小的有效市集，請參閱 [建立市集](/docs/zh-TW/plugins/create-marketplace)。

62 * 若要了解安裝是載入您的來源目錄還是快取副本，請參閱 [就地和複製的外掛程式](/docs/zh-TW/plugins/loading#in-place-and-copied-plugins)。

63 </Step>

65 <Step title="填入使用者看到的中繼資料">

66 在 `plugin.json` 中設定 `description`、`author`、`homepage` 和 `repository`，並在外掛程式根目錄新增 `README.md`。`homepage` 必須解析為 URL。[資訊清單參考](/docs/zh-TW/plugins/manifest-reference#fields) 列出每個欄位。

67 </Step>

69 <Step title="執行您的評估套件">

70 如果您有評估套件，請在 shell 中執行 `claude plugin eval`。它執行外掛程式的測試案例並評分結果，這在您變更外掛程式時會捕捉迴歸。請參閱 [使用評估測試外掛程式](/docs/zh-TW/plugin-evals)。

71 </Step>

72</Steps>

74<h2 id="share-a-plugin-without-a-marketplace">

75 不使用市集共享外掛程式

76</h2>

78如果外掛程式在 git 存放庫中，人們可以複製它並載入簽出，或從他們的 shell 使用指向您附加到發行的 `.zip` 的 `--plugin-url` 啟動 Claude Code。若要取得您的下一個版本，他們會拉取或再次下載。如果它不在存放庫中，請將目錄或其 `.zip` 發送給他們。他們可以透過以下兩種方式之一載入它：

80* **對於一個工作階段**：他們從他們的 shell 使用 `claude --plugin-dir ./deploy-helper` 啟動 Claude Code，其中路徑是複製、解壓縮的資料夾或 `.zip` 本身。請參閱 [為一個工作階段載入外掛程式的旗標](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session)。

81* **對於每個工作階段**：他們將外掛程式目錄（包含其 `.claude-plugin/plugin.json`）移到 `~/.claude/skills/` 下，以便 Claude Code [在每個工作階段中載入它](/docs/zh-TW/plugins/loading#find-where-a-plugin-came-from)。

83將 `.claude-plugin/marketplace.json` 新增到同一存放庫是讓人們按名稱安裝並使用命令更新的方式；請參閱 [透過您自己的市集發佈](#publish-through-your-own-marketplace)。

85<h3 id="ship-a-plugin-with-your-own-tool">

86 使用您自己的工具發送外掛程式

87</h3>

89如果您維護 CLI 或 SDK，請在市集中發佈外掛程式，並讓您的安裝程式或安裝後訊息執行或列印使用者需要的兩個命令：`claude plugin marketplace add <source>`，然後 `claude plugin install <name>@<marketplace>`。對於當某人使用您的工具時的工作階段內發現，請參閱 [從您的 CLI 推薦您的外掛程式](/docs/zh-TW/plugins/cli-hints)。

91<h2 id="publish-through-your-own-marketplace">

92 透過您自己的市集發佈

93</h2>

95您自己的市集是一個 `.claude-plugin/marketplace.json` 檔案，列出您的外掛程式，新增到 git 存放庫。一旦檔案在存放庫中，外掛程式就會發佈，沒有提交表單。您可以將檔案保留在外掛程式自己的存放庫中或在單獨的存放庫中。

97<h3 id="add-the-marketplace-file-to-your-repository">

98 將市集檔案新增到您的存放庫

99</h3>

100

101若要從外掛程式自己的存放庫發佈，請在 `.claude-plugin/` 中的 `plugin.json` 旁邊儲存市集檔案，其中一個項目的 `source` 是 `"./"`，存放庫根目錄。給予項目與 `plugin.json` 相同的 `name`，根據 [保持項目名稱和資訊清單名稱相同](/docs/zh-TW/plugins/create-marketplace#keep-the-entry-name-and-the-manifest-name-the-same)：

102

103```json .claude-plugin/marketplace.json theme={null}

104{

105 "name": "your-marketplace",

106 "owner": { "name": "Your Name" },

107 "plugins": [

108 { "name": "deploy-helper", "source": "./" }

109 ]

110}

111```

112

113在您的 shell 中，在存放庫中執行 `claude plugin validate .` 以在推送前檢查檔案。

114

115[建立市集](/docs/zh-TW/plugins/create-marketplace) 涵蓋一個存放庫中有多個外掛程式的佈局。

116

117<h3 id="control-who-can-install">

118 控制誰可以安裝

119</h3>

120

121任何可以複製存放庫的人都可以從中安裝，因此如果存放庫是私人的，市集也是私人的。對於 git 存放庫以外的主機，請參閱 [託管市集](/docs/zh-TW/plugins/host-marketplace)。若要到達整個公司的每個人，包括不使用 git 的人，請參閱 [推出到整個公司](/docs/zh-TW/plugins/host-marketplace#roll-out-to-a-whole-company)。

122

123<h3 id="tell-users-how-to-install">

124 告訴使用者如何安裝

125</h3>

126

127告訴您的使用者新增市集，然後從他們的 shell 安裝外掛程式，用您的替換來源和名稱：

128

129* 新增市集一次：`claude plugin marketplace add your-org/your-marketplace`，其中引數是 GitHub `owner/repo` 速記、URL 或路徑

130* 安裝外掛程式：`claude plugin install deploy-helper@your-marketplace`

131* 或從工作階段內執行兩者：`/plugin install deploy-helper --marketplace your-org/your-marketplace`。需要 Claude Code v2.1.275 或更新版本。請參閱 [在一個命令中新增市集和安裝](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command)

132

133<h3 id="ship-updates-to-users">

134 向使用者發送更新

135</h3>

136

137使用者在要求時或為您的市集啟用自動更新時接收發行：

138

139* **應要求**：使用者 shell 中的 `claude plugin update deploy-helper@your-marketplace` 會重新整理市集，並在您的外掛程式版本已變更時安裝新副本

140* **自動更新**：預設為您的市集關閉。請參閱 [啟用自動更新](/docs/zh-TW/plugins/host-marketplace#turn-on-auto-update)。啟用後，它會在工作階段開始後延遲執行與 `claude plugin update` 相同的操作

141

142[安裝外掛程式](/docs/zh-TW/plugins/install) 涵蓋使用者端命令，[自動更新何時執行](/docs/zh-TW/plugins/loading#when-auto-update-runs) 涵蓋時序。

143

144<h2 id="submit-to-the-community-marketplace">

145 提交到社群市集

146</h2>

147

148Anthropic 的社群市集 `claude-community` 是透過外掛程式目錄提交表單列出提交的外掛程式的公開市集。

149

150使用者在 Claude Code 工作階段中使用 `/plugin marketplace add anthropics/claude-plugins-community` 新增社群市集，並將其安裝為 `@claude-community`。

151

152有關社群市集與官方市集的差異，請參閱 [Anthropic 的市集](/docs/zh-TW/plugins/anthropic-marketplaces)。

153

154若要將您的外掛程式提交到社群市集，請使用其中一個應用程式內表單：

155

156* **claude.ai**：[claude.ai/admin-settings/directory/submissions/plugins/new](https://claude.ai/admin-settings/directory/submissions/plugins/new)

157* **Console**：[platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)

158

159claude.ai 表單需要 Team 或 Enterprise 組織以及目錄權限，預設情況下擁有者持有該權限。不是 Team 或 Enterprise 組織一部分的個人作者可以改用 Console 表單。

160

161在您提交前，在 shell 中本機執行 `claude plugin validate ./your-plugin`，用您的外掛程式目錄的路徑替換 `./your-plugin`。驗證通過時，Claude Code 會列印 `✔ Validation passed`，或如果有警告，則列印 `✔ Validation passed with warnings`。警告不會使驗證失敗；新增 `--strict` 以將它們視為錯誤。

162

163列出的外掛程式出現在 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 目錄中，在幾乎每種情況下都固定到特定的提交 SHA。

164

165提交和您的外掛程式出現在 `marketplace.json` 之間可能會有延遲。若要檢查您的外掛程式是否可安裝，請在 [社群目錄](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) 中搜尋其名稱。

166

167官方市集 `claude-plugins-official` 不透過這些表單接受提交。如果您與 Anthropic 合作夥伴聯絡合作，請詢問他們有關官方市集列表。

168

169<h2 id="ship-updates-renames-and-removals">

170 發送更新、重新命名和移除

171</h2>

172

173<h3 id="release-a-new-version">

174 發行新版本

175</h3>

176

177如果您透過您自己的市集發佈，並且您的 `plugin.json` 設定 `version`，請遞增它並推送。執行 `claude plugin update` 或啟用自動更新的使用者會接收新版本，如 [向使用者發送更新](#ship-updates-to-users) 下所述。

178

179<h3 id="tag-a-release">

180 標記發行

181</h3>

182

183當其他外掛程式在您的上宣告版本範圍時，在 git 中標記發行，因為這些範圍針對標籤進行解析。否則您不需要標籤。

184

185若要標記，請從外掛程式目錄在 shell 中執行 `claude plugin tag`。它建立一個 `{name}--v{version}` 標籤。新增 `--push` 以將標籤發送到 `origin`。[`plugin tag` 參考](/docs/zh-TW/plugins/cli-reference#plugin-tag) 列出其旗標。

186

187<h3 id="rename-or-remove-a-plugin">

188 重新命名或移除外掛程式

189</h3>

190

191永遠不要變更已發佈外掛程式的 `name`。重新命名後，已安裝它的使用者會失去外掛程式，因為他們的安裝是在舊名稱下記錄的。您的市集檔案中的 `renames` 項目會改為遷移它們。當您想要不同的標籤時，變更 `displayName`。

192

193如果重新命名是不可避免的，請使用市集檔案的 `renames` 對應，以便現有安裝遷移而不是因 [`Plugin "<name>" not found in marketplace`](/docs/zh-TW/plugins/troubleshooting#plugin-not-found-in-marketplace) 而失敗。若要從市集移除外掛程式，或取得完整的 `renames` 詳細資訊，請參閱託管頁面上的 [重新命名或移除外掛程式](/docs/zh-TW/plugins/host-marketplace#rename-or-remove-a-plugin)。[市集參考](/docs/zh-TW/plugins/marketplace-reference#top-level-fields) 有該欄位。

194

195<h2 id="declare-dependencies">

196 宣告依賴項

197</h2>

198

199如果您的外掛程式需要來自同一市集的另一個外掛程式被啟用，請在 `plugin.json` 的 `dependencies` 陣列中列出它。每個項目是一個裸名稱或具有 semver `version` 範圍的物件。當使用者安裝您的外掛程式時，Claude Code 也會安裝並啟用依賴項。

200

201[外掛程式依賴項](/docs/zh-TW/plugins/dependencies) 涵蓋範圍語法、跨市集依賴項以及使用者如何修剪他們不再需要的依賴項。

202

203<h2 id="next-steps">

204 後續步驟

205</h2>

206

207* [託管和維護市集](/docs/zh-TW/plugins/host-marketplace)：發行新版本並讓使用者保持最新狀態

208* [外掛程式依賴項](/docs/zh-TW/plugins/dependencies)：宣告和版本化您的外掛程式所依賴的外掛程式

209* [從您的 CLI 推薦您的外掛程式](/docs/zh-TW/plugins/cli-hints)：提示您的 CLI 的 Claude Code 使用者安裝外掛程式

210* [測量外掛程式成本和使用情況](/docs/zh-TW/plugins/measure)：查看您的外掛程式在上下文中的成本以及人們是否使用它

plugins/relevance.md +247 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 為您的組織推薦 plugins

7> 在 marketplace plugin 項目中新增相關性區塊，以便當使用者的工作符合時 Claude Code 會建議安裝，並在受管設定中將 marketplace 加入允許清單。

9Claude Code 可以在使用者的工作階段符合您為該 plugin 定義的訊號時，建議從您組織的 marketplace 安裝 plugin。訊號包括工作目錄、Claude 已讀取的檔案，以及 Claude 已執行的命令。您可以透過在 `marketplace.json` 中的 plugin 項目新增 `relevance` 區塊來定義這些訊號。

11marketplace 操作員會撰寫 `relevance` 項目。管理員隨後在受管設定中將 marketplace 加入允許清單。在 marketplace 被加入允許清單之前，使用者看不到來自該 marketplace 的任何建議。

13<Note>

14 這些情況涵蓋在其他頁面上：

16 * **您想要安裝 plugins**：請參閱 [安裝和管理 plugins](/docs/zh-TW/plugins/install)

17 * **您想要關閉建議**：請參閱 [了解 plugin 相關性的運作方式](#understand-how-plugin-relevance-works)

18</Note>

20從適合您角色的部分開始：

22* **Marketplace 操作員**：閱讀 [建議的運作方式](#understand-how-plugin-relevance-works)，然後 [將相關性新增至 plugin 項目](#add-relevance-to-a-plugin-entry) 並 [驗證您的 marketplace](#validate-your-marketplace)

23* **管理員**：[在受管設定中啟用建議](#enable-suggestions-in-managed-settings)

25<h2 id="understand-how-plugin-relevance-works">

26 了解 plugin 相關性的運作方式

27</h2>

29`marketplace.json` 中的每個 plugin 項目都可以包含 `relevance` 物件。該物件命名一個主題和一個或多個訊號。訊號是 Claude Code 針對目前工作階段測試的模式，例如工作目錄或 Claude 已讀取的檔案。

31訊號比對在使用者的機器上本地進行，不會增加任何網路流量。Claude Code 不會向 Anthropic 或 marketplace 操作員報告哪些訊號相符或其值。

33當訊號相符且 plugin 尚未安裝時，Claude Code 會在以下位置建議該 plugin：

35* **Spinner 提示**：當 Claude 正在回應時，包含 `/plugin install` 命令的訊息會出現在 spinner 下方。

36* **工作階段開始通知**：如果 `cwd` 訊號符合工作目錄，在使用者傳送第一則訊息之前會出現一行通知。

37* **`/plugin` Discover 標籤**：plugin 會釘選在 Discover 清單的頂部。

39[預覽使用者看到的內容](#preview-what-the-user-sees) 顯示每個的確切文字以及它們重複的頻率。

41Claude Code 永遠不會自動安裝 plugin。使用者始終確認。

43當使用者或專案將 [`spinnerTipsEnabled`](/docs/zh-TW/settings-reference#spinnertipsenabled) 設定為 `false`，或當 [`spinnerTipsOverride`](/docs/zh-TW/settings-reference#spinnertipsoverride) 搭配 `excludeDefault` 取代內建提示時，spinner 提示和工作階段開始通知都會停止出現。Discover 標籤釘選不受任一設定影響。

45<h2 id="add-relevance-to-a-plugin-entry">

46 將相關性新增至 plugin 項目

47</h2>

49將 `relevance` 物件新增至您 `marketplace.json` 中的 plugin 項目。下列範例宣告當 Claude 讀取 `.tf` 檔案或執行 `terraform` 時，`terraform-helpers` plugin 是相關的：

51```json theme={null}

52{

53 "name": "your-marketplace",

54 "owner": { "name": "Your Org" },

55 "plugins": [

56 {

57 "name": "terraform-helpers",

58 "source": "./plugins/terraform-helpers",

59 "description": "Your organization's Terraform conventions and helpers",

60 "relevance": {

61 "topic": "Terraform",

62 "signals": {

63 "cli": ["terraform"],

64 "filesRead": ["**/*.tf"]

65 }

66 }

67 }

68 ]

69}

70```

72當其訊號都不相符時，plugin 會保持在 Discover 清單中的正常位置，不會顯示為 spinner 提示。

74若要在發佈前檢查該區塊，請 [驗證您的 marketplace](#validate-your-marketplace)。

76<h2 id="field-reference">

77 欄位參考

78</h2>

80`relevance` 物件及其巢狀 `signals` 物件接受下列表格中的欄位。

82較舊的用戶端仍會載入使用它們無法識別的 `relevance` 欄位的 marketplace，因為在載入時會忽略 `relevance` 和 `relevance.signals` 下的未知欄位。已識別的欄位其值超過 [欄位參考](#field-reference) 中的限制會使整個 plugin 項目失效，使用者無法從 marketplace 安裝該 plugin，直到您修復它；`claude plugin validate` 會報告相同的限制。

84<h3 id="relevance">

85 `relevance`

86</h3>

88| 欄位 | 類型 | 說明 |

89| :-------- | :- | :----------------------------------------------------------------------------------------------------- |

90| `topic` | 字串 | 選用。填入 spinner 提示中「使用 *topic*？」的片語。預設為 plugin 名稱，每個連字號區段首字大寫。最多 64 個字元。 |

91| `signals` | 物件 | 決定 plugin 何時相關的比對器。Claude Code 只有在至少設定一個訊號時才會建議該 plugin。請參閱 [`relevance.signals`](#relevance-signals)。 |

93`topic` 通常是產品名稱，例如 `Terraform`。當 plugin 名稱作為主題聽起來不自然時，使用 `design` 之類的領域。

95<h3 id="relevance-signals">

96 `relevance.signals`

97</h3>

99`signals` 物件接受下列欄位。

100

101| 欄位 | 類型 | 說明 | 限制 |

102| :------------- | :--- | :------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------- |

106| `filesRead` | 字串陣列 | 針對 Claude 在此工作階段讀取的檔案路徑比對的 Glob 模式，例如 `["**/*.tf"]`。正斜線正規化且不區分大小寫。 | 10 個模式，每個 256 個字元 |

107| `manifestDeps` | 物件陣列 | Claude 在此工作階段讀取的套件資訊清單中宣告的相依性。每個項目是 `{ "file": "...", "pattern": "..." }`，其中兩個值都是正規表達式。請參閱 [資訊清單相依性比對](#manifest-dependency-matching)。 | 10 個項目，每個值最多 256 個字元。大於 512 KB 的資訊清單檔案會被略過 |

108

109`filesRead` 和 `manifestDeps` 訊號也會比對 Claude 在此工作階段中寫入或編輯的檔案，以及專案的自動載入 `CLAUDE.md` 記憶體檔案。

110

111<h4 id="working-directory-matching">

112 工作目錄比對

113</h4>

114

115`cwd` 是唯一可以在工作階段開始時比對的訊號，在使用者傳送第一則訊息之前。

116

117Claude Code 比對每個 `cwd` 模式如下：

118

119* 模式會針對工作目錄作為絕對路徑進行比對。當工作階段在 git 儲存庫內時，它也會針對相對於儲存庫根目錄的工作目錄路徑進行比對。

120* 比對是正斜線正規化且不區分大小寫的。

121* 每個模式都會比對目錄本身及其下的所有內容，因此 `infra`、`infra/` 和 `infra/**` 的行為相同。

122

123<h4 id="command-name-matching">

124 命令名稱比對

125</h4>

126

127Claude Code 為 Claude 執行的每個 shell 命令記錄一個命令名稱：任何前導環境變數指派和 `sudo` 之後的第一個權杖。複合命令只貢獻其前導命令，因此 `cd infra && terraform plan` 記錄 `cd`，而不是 `terraform`。

128

129<h4 id="manifest-dependency-matching">

130 資訊清單相依性比對

131</h4>

132

133每個 `manifestDeps` 項目配對兩個 JavaScript `RegExp` 來源字串：

134

135* `file`：不區分大小寫地針對資訊清單檔案的路徑進行比對。路徑通常是絕對的，因此請在結尾而不是開頭錨定模式。路徑不會針對此訊號進行分隔符號正規化，因此 Windows 路徑使用反斜線。

136* `pattern`：區分大小寫地針對該檔案的內容進行比對。

137

138下列範例使用 `manifestDeps` 在 Claude 讀取了依賴您 SDK npm 套件（此處名為 `your-sdk`）的 `package.json` 後建議您的 plugin。

139

140```json theme={null}

141{

142 "name": "your-plugin",

143 "source": "./plugins/your-plugin",

144 "relevance": {

145 "signals": {

146 "manifestDeps": [

147 {

148 "file": "[/\\\\]package\\.json$",

149 "pattern": "\"your-sdk\"\\s*:"

150 }

151 ]

152 }

153 }

154}

155```

156

157在此範例中，`file` 模式使用 `[/\\\\]` 以便同時比對正斜線和反斜線路徑分隔符號，以及 `\\.` 使點是字面意思。在 JSON 中，正規表達式中的每個反斜線都寫兩次。

158

159<h2 id="validate-your-marketplace">

160 驗證您的 marketplace

161</h2>

162

163在您的 shell 中，針對您的 marketplace 目錄執行 `claude plugin validate` 以在發佈前檢查 `relevance` 區塊：

164

165```bash theme={null}

166claude plugin validate ./my-marketplace

167```

168

169驗證器會報告 `relevance` 區塊上的錯誤和警告，包括這些：

170

171* 將 `relevance` 和 `relevance.signals` 下的未知鍵報告為警告

172* 標記不是物件的 `relevance` 值

173* 拒絕包含配置、連接埠或路徑的 `signals.hosts` 項目

174

175每個發現都會列印它所涉及的欄位的路徑，輸出以 `Validation passed`、`Validation passed with warnings` 或 `Validation failed` 結尾。

176

177<h2 id="enable-suggestions-in-managed-settings">

178 在受管設定中啟用建議

179</h2>

180

181使用者看不到來自 marketplace 的任何建議，直到管理員在 [受管設定](/docs/zh-TW/plugins/org) 中將其加入允許清單，即使其 `marketplace.json` 宣告了 `relevance`。

182

183若要將 marketplace 加入允許清單，請編輯您的受管設定如下：

184

185* 將 marketplace 名稱新增至 `pluginSuggestionMarketplaces`。

186* 對於官方 Anthropic marketplace 以外的任何 marketplace，也請宣告 marketplace 來源，可以是 [`extraKnownMarketplaces`](/docs/zh-TW/plugins/org#require-a-marketplace-and-its-plugins) 中該名稱的項目，或 [`strictKnownMarketplaces`](/docs/zh-TW/plugins/org#allowlist-with-strictknownmarketplaces) 中的項目。

187

188在未註冊 marketplace 的機器上，或從不同來源以允許清單名稱註冊的機器上，不會出現來自它的任何建議。來源檢查會阻止無關的來源以允許清單名稱註冊以在您的組織中建議其 plugins。

189

190下列 `managed-settings.json` 從 GitHub 儲存庫註冊組織 marketplace 並啟用其建議：

191

192```json theme={null}

193{

194 "extraKnownMarketplaces": {

195 "your-marketplace": {

196 "source": {

197 "source": "github",

198 "repo": "your-org/your-marketplace"

199 }

200 }

201 },

202 "pluginSuggestionMarketplaces": ["your-marketplace"]

203}

204```

205

206官方 marketplace 的名稱只能從官方 Anthropic 來源註冊，因此不需要來源宣告。對於官方 marketplace，僅將名稱加入允許清單：

207

208```json theme={null}

209{

210 "pluginSuggestionMarketplaces": ["claude-plugins-official"]

211}

212```

213

214<h2 id="preview-what-the-user-sees">

215 預覽使用者看到的內容

216</h2>

217

218當 plugin 的 `relevance` 訊號在工作階段期間相符時，spinner 下方的提示讀取：

219

220```text theme={null}

221Working with Terraform? Install the terraform-helpers plugin:

222/plugin install terraform-helpers@your-marketplace

223```

224

225當 `cwd` 訊號在工作階段開始時相符時，一行通知讀取：

226

227```text theme={null}

228plugin suggestion: terraform-helpers@your-marketplace · /plugin

229```

230

231在 `/plugin` Discover 標籤中，plugin 會釘選在其他結果上方，並帶有命名相符訊號的註釋，例如 `suggested for this directory` 或 `suggested for terraform commands`。

232

233Claude Code 限制建議給定 plugin 的頻率：

234

235* 建議在 spinner 提示和工作階段開始通知的組合中最多每三個工作階段出現一次。

236* 一旦 spinner 提示和通知已組合顯示該 plugin 兩次，工作階段開始通知就會停止出現。

237* 一旦安裝了 plugin，spinner 提示和工作階段開始通知都不會重複。

238* Discover 標籤會在使用者在 plugin 訊號相符時首次開啟標籤時釘選該 plugin。Claude Code 會在 `~/.claude.json` 中記錄這一點，因此每次使用者稍後在該機器上開啟 `/plugin` 時，該 plugin 都會以正常順序出現。

239

240<h2 id="see-also">

241 另請參閱

242</h2>

243

244* [託管 marketplace](/docs/zh-TW/plugins/host-marketplace)：執行託管您的 plugins 的 marketplace

245* [Marketplace 參考](/docs/zh-TW/plugins/marketplace-reference#plugin-entries)：plugin 項目接受的每個欄位

246* [從您的 CLI 推薦您的 plugin](/docs/zh-TW/plugins/cli-hints)：從您自己的 CLI 而不是從 Claude Code 的工作階段訊號提示使用者

247* [為您的組織管理 plugins](/docs/zh-TW/plugins/org)：`extraKnownMarketplaces`、`strictKnownMarketplaces` 和其餘 plugin 原則鍵

plugins/security.md +186 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Plugin 安全性和信任

7> 在安裝 plugin 之前決定是否信任它，從 plugin 在您的機器上可以執行的操作，到如何檢查它和移除它。

9您安裝的 Claude Code plugin 可以使用您的使用者權限在您的機器上執行任意程式碼。

11您從一個 marketplace 安裝 plugin，marketplace 是 Claude Code 從中取得它的目錄。某些 marketplace 名稱是[為 Anthropic 自己的 marketplace 保留的](#marketplace-tiers)，其他所有 marketplace 都是第三方的。Marketplace 的名稱告訴您誰發佈了該目錄，而不是其中每個 plugin 的功能，所以無論它來自哪個 marketplace，都要[在安裝前檢查 plugin](#review-a-plugin-before-you-install)。

13如果您正在決定是否安裝 plugin，或者您在您的團隊可以使用工具之前檢查它們，請閱讀此頁面。

15<Note>

16 這些情況在其他頁面上涵蓋：

18 * **Claude Code 自己的安全模型**：請參閱[安全性](/docs/zh-TW/security)

19 * **限制或要求組織的 plugin**：請參閱[為您的組織管理 plugin](/docs/zh-TW/plugins/org)

20 * **`security-guidance` 或 `claude-security` plugin**：此頁面不是關於它們的。請參閱[`security-guidance`](/docs/zh-TW/security-guidance) 和 [`claude-security`](/docs/zh-TW/claude-security)

21</Note>

23從[plugin 可以執行的操作](#understand-what-a-plugin-can-do)和[哪些 marketplace 是 Anthropic 的](#marketplace-tiers)開始，然後[在安裝前檢查 plugin](#review-a-plugin-before-you-install)。

25<h2 id="understand-what-a-plugin-can-do">

26 了解 plugin 可以執行的操作

27</h2>

29Plugin 可以攜帶在您的機器上使用您的使用者權限執行程式碼的內容，以及進入 Claude 上下文作為指令的內容，所以[在安裝前檢查 plugin](#review-a-plugin-before-you-install)。以下是已安裝的 plugin 可以執行的操作：

31* **Hooks**：plugin 的 [hooks](/docs/zh-TW/hooks) 在 Claude Code 生命週期中的特定點（例如工具呼叫之前或之後）作為 shell 命令執行。

32* **MCP 和 LSP 伺服器**：Claude Code 連接到已啟用的 plugin 聲明的 [MCP 伺服器](/docs/zh-TW/mcp)，並為 Claude 提供它們的工具。Stdio MCP 伺服器作為 Claude Code 在您的機器上啟動的程序執行。Claude Code 也啟動 plugin 聲明的語言伺服器。

33* **`bin/` 目錄**：Claude Code 將每個已啟用的 plugin 的 `bin/` 目錄新增到 Bash 工具的 shell 的 `PATH`，所以 Claude 的 Bash 命令可以執行那裡的任何可執行檔。

34* **Skills、commands 和 agents**：這些進入 Claude 的上下文作為指令，所以它們影響 Claude 對它已有的工具執行的操作。

35* **更新**：當您安裝 plugin 的 marketplace 啟用自動更新時，Claude Code 在背景更新該 plugin，所以您檢查的檔案可能會在磁碟上變更。[何時自動更新執行](/docs/zh-TW/plugins/loading#when-auto-update-runs)有時間安排。要按 marketplace 開啟或關閉自動更新，請參閱[保持 plugin 更新](/docs/zh-TW/plugins/install#keep-plugins-updated)。

37Claude Code 的[權限規則](/docs/zh-TW/permissions)和[沙箱](/docs/zh-TW/sandboxing)涵蓋 Claude 進行的工具呼叫，而不是 plugin 自己執行的程式碼：

39* **Hooks 和伺服器程序**：命令 hooks 使用您的完整使用者權限執行 shell 命令。Claude Code 在沙箱外執行 hooks 和 MCP 伺服器。

40* **Claude 的工具呼叫**：對 plugin 的 MCP 工具之一的呼叫，以及執行 plugin 的 `bin/` 中的可執行檔的 Bash 命令，都是工具呼叫，所以您的權限規則適用於它們。

42安裝 plugin 也會啟用它，除非其 manifest 或 marketplace 項目設定了 [`defaultEnabled: false`](/docs/zh-TW/plugins/install#choose-an-install-scope)，且您自己還沒有啟用它。

44要移除您不再信任的 plugin，請參閱[移除您不再信任的 plugin](#remove-a-plugin-you-no-longer-trust)。

46<h2 id="marketplace-tiers">

47 按名稱識別 Anthropic 的 marketplace

48</h2>

50Marketplace 的名稱將其放在三個層級之一中：官方、社群或第三方。Claude Code 僅接受來自 `github.com/anthropics/` 儲存庫的官方和社群名稱用於 marketplace，所以第三方 marketplace 無法將自己呈現為 Anthropic 的。同事或您的組織發佈的 marketplace 是第三方的。

52該表列出了每個層級中的 marketplace 名稱：

54| 層級 | 哪些 marketplace |

55| :-- | :---------------------------------------------------------------------------- |

56| 官方 | [官方 marketplace 名稱](#official-marketplace-names)，例如 `claude-plugins-official` |

57| 社群 | `claude-community`、`claude-plugins-community` 和 `healthcare` |

58| 第三方 | 所有其他 marketplace |

60其中 `claude-community` 目錄將 plugin 固定到提交 SHA，幾乎每個項目都這樣做，Claude Code 拒絕安裝不同的提交。

62<h3 id="official-marketplace-names">

63 官方 marketplace 名稱

64</h3>

66這些 marketplace 名稱組成官方層級：

68* `claude-plugins-official`

69* `claude-code-marketplace`

70* `claude-code-plugins`

71* `anthropic-marketplace`

72* `anthropic-plugins`

73* `agent-skills`

74* `anthropic-agent-skills`

75* `life-sciences`

76* `knowledge-work-plugins`

77* `claude-for-legal`

78* `claude-for-financial-services`

79* `financial-services-plugins`

80* `first-party-plugins`

81* `claude-tag-plugins`

83有關官方、社群和示範 marketplace 的差異以及在哪裡瀏覽每個 marketplace 列出的內容，請參閱 [Anthropic 的 marketplace](/docs/zh-TW/plugins/anthropic-marketplaces)。

85<h2 id="review-a-plugin-before-you-install">

86 在安裝前檢查 plugin

87</h2>

89在安裝 plugin 之前，查看它新增的內容以及它來自何處。

91<Steps>

92 <Step title="檢查 marketplace 的來源">

93 在您的 shell 中，執行 `claude plugin marketplace list` 以列印每個 marketplace 的新增來源，例如 GitHub 儲存庫或目錄。

94 </Step>

96 <Step title="閱讀詳細資訊窗格">

97 在 Claude Code 工作階段中，執行 `/plugin` 並選擇 plugin。詳細資訊窗格顯示一個**將安裝**部分，列出 plugin 的命令、agents、skills、hooks 和 MCP 及 LSP 伺服器。對於 Anthropic 沒有已發佈元件資料的 plugin，該部分顯示 marketplace 項目聲明的內容，或一個注意：`Components will be discovered at installation` 用於儲存在 marketplace 內的 plugin，或 `Component summary not available for remote plugin` 用於從其他地方取得的 plugin。

98 </Step>

100 <Step title="閱讀 plugin 的來源">

101 在詳細資訊窗格中，選擇安裝選項下方的**開啟首頁**或**在 GitHub 上檢視**。如果窗格不提供任何一個，請開啟您在第一步中找到的 marketplace 儲存庫。在那裡找到 plugin 的目錄。**將安裝**部分顯示 hook 存在但不顯示它執行的內容，所以請在 plugin 的目錄中閱讀這些檔案：

102

103 * **`hooks/hooks.json`**：每個 hook 執行的命令

104 * **`.mcp.json`**：每個伺服器的命令或 URL

105 * **`bin/`**：目錄中的每個檔案

106 </Step>

107

108 <Step title="列出 plugin 包含的內容">

109 複製保存 plugin 目錄的儲存庫，然後在您的 shell 中執行 `claude --plugin-dir <plugin directory> plugin details <plugin name>` 以查看 Claude Code 在其中找到的內容。該命令讀取 plugin 的檔案而不啟動工作階段，並列印一個 `Component inventory` 列出 plugin 的 skills 和 commands、agents、hooks（每個 hook 的事件）以及 MCP 和 LSP 伺服器。

110 </Step>

111</Steps>

112

113安裝 plugin 後，在您的 shell 中執行 `claude plugin details <plugin name>` 以為 `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` 下的已安裝副本列印相同的 `Component inventory`。

114

115<h3 id="remove-a-plugin-you-no-longer-trust">

116 移除您不再信任的 plugin

117</h3>

118

119在您的 shell 中，使用您安裝它的 `--scope` 執行 [`claude plugin uninstall <plugin>`](/docs/zh-TW/plugins/cli-reference#plugin-uninstall)。然後檢查卸載移除了什麼以及它留下了什麼：

120

121* **持久資料**：當那是最後一個安裝 plugin 的範圍時，卸載也會刪除 plugin 的持久資料目錄，除非您傳遞 `--keep-data`。

122* **快取檔案**：plugin 的檔案保留在 `~/.claude/plugins/cache/` 下的磁碟上 14 天，然後[背景掃描移除它們](/docs/zh-TW/plugins/loading#cleanup-of-previous-versions)。卸載您的最後一個 plugin 後，孤立目錄保留到您安裝另一個。要立即刪除檔案，請自己移除 `~/.claude/plugins/cache/<marketplace>/<plugin>/` 下的 plugin 目錄。

123* **Marketplace**：如果您也不信任 marketplace 的擁有者，[移除 marketplace](/docs/zh-TW/plugins/install#manage-marketplaces) 也會卸載您從它安裝的每個 plugin。

124

125<h2 id="recognize-when-claude-code-refuses-or-warns">

126 識別 Claude Code 何時拒絕或警告

127</h2>

128

129您從 `/plugin` 中的**探索**或**Marketplace** 標籤開啟的詳細資訊窗格為每個 plugin 顯示相同的信任警告。Claude Code 在[不受信任的 marketplace 來源和失敗的完整性檢查](#untrusted-marketplace-sources-and-failed-integrity-checks)下的情況下拒絕而不是警告。

130

131<h3 id="trust-warning-before-you-install">

132 安裝前的信任警告

133</h3>

134

135警告讀起來相同，無論 plugin 來自哪個 marketplace：

136

137```text theme={null}

138Make sure you trust a plugin before installing, updating, or using it. Anthropic does not control what MCP servers, files, or other software are included in plugins and cannot verify that they will work as intended or that they won't change. See each plugin's homepage for more information.

139```

140

141如果您的組織在[受管設定](/docs/zh-TW/plugins/org)中設定了 `pluginTrustMessage`，Claude Code 會將該文字附加到警告中。

142

143<h3 id="untrusted-marketplace-sources-and-failed-integrity-checks">

144 不受信任的 marketplace 來源和失敗的完整性檢查

145</h3>

146

147Claude Code 在這些情況下拒絕載入 marketplace 或安裝 plugin，每種情況都有自己的錯誤訊息：

148

149* **不受信任的 marketplace 來源**：當 marketplace 使用官方或社群名稱但其來源在 `github.com/anthropics/` 之外時，Claude Code 停止載入 marketplace 和您從它安裝的 plugin。錯誤是[Marketplace is registered from an untrusted source](/docs/zh-TW/errors#marketplace-is-registered-from-an-untrusted-source)。

150* **存檔完整性**：當 marketplace 項目將 [`archive` 來源](/docs/zh-TW/plugins/marketplace-reference#archive-plugin-source)固定到 `sha256` 摘要，且下載的檔案的摘要不符合時，Claude Code 拒絕安裝。錯誤是[Plugin archive integrity check failed](/docs/zh-TW/errors#plugin-archive-integrity-check-failed)。

151

152`sha256` 固定與社群目錄的提交 SHA 固定分開，後者選擇要檢出的 git 提交。

153

154<h2 id="enforce-plugin-controls-for-your-organization">

155 為您的組織強制執行 plugin 控制

156</h2>

157

158使用[受管設定](/docs/zh-TW/plugins/org)，管理員可以強制執行這些 plugin 控制：

159

160* 允許清單或封鎖清單 marketplace 來源

161* 強制啟用 plugin

162* 關閉 `--plugin-dir` 和 `--plugin-url` 旗標以及 `CLAUDE_CODE_PLUGIN_DIRS` 變數

163* 將 hooks 限制為來自受管設定和強制啟用的 plugin 的 hooks

164* 停止成員 claude.ai 帳戶中的 plugin 在 Claude Code 中載入，使用 [`syncClaudeAiPlugins`](/docs/zh-TW/plugins/org#control-matrix)

165

166[控制矩陣](/docs/zh-TW/plugins/org#control-matrix)說明每個金鑰執行和不涵蓋的內容。

167

168<h2 id="find-plugins-in-telemetry">

169 在遙測中尋找 plugin

170</h2>

171

172如果您的組織將 Claude Code 的 [OpenTelemetry 事件](/docs/zh-TW/monitoring-usage)匯出到其自己的後端，[marketplace 層級](#marketplace-tiers)決定哪些 plugin 名稱出現在那裡：

173

174* **[Plugin loaded 事件](/docs/zh-TW/monitoring-usage#plugin-loaded-event)**：事件按原樣報告官方層級的 plugin 和 marketplace 名稱。對於社群和第三方層級，`plugin.name` 和 `marketplace.name` 是字面字串 `third-party`，除非您設定 `OTEL_LOG_TOOL_DETAILS=1`。

175* **Plugin 範圍**：載入事件的 `plugin.scope` 仍然報告 plugin 來自何處，例如 `org` 用於您的受管設定啟用的 plugin 或 `user-local` 用於任何其他第三方 plugin。[Plugin loaded 事件](/docs/zh-TW/monitoring-usage#plugin-loaded-event)列出每個值。

176* **[Plugin installed 事件](/docs/zh-TW/monitoring-usage#plugin-installed-event)**：除非您設定 `OTEL_LOG_TOOL_DETAILS=1`，否則事件會省略非官方 plugin 的名稱欄位，而不是報告 `third-party`。

177* **[Claude Code Analytics API](https://platform.claude.com/docs/en/api/admin/analytics/plugins/list)**：Claude Code 按名稱報告官方和社群層級的 plugin，並將所有其他 plugin 報告為 `third-party`。

178

179<h2 id="next-steps">

180 後續步驟

181</h2>

182

183* [為您的組織管理 plugin](/docs/zh-TW/plugins/org)：限制使用者可以安裝的 marketplace 並要求您信任的 plugin

184* [安裝和管理 plugin](/docs/zh-TW/plugins/install)：在選擇範圍之前檢查 plugin 的詳細資訊窗格

185* [Anthropic 的 marketplace](/docs/zh-TW/plugins/anthropic-marketplaces)：哪些 marketplace 名稱是 Anthropic 的

186* [安全性](/docs/zh-TW/security)：Claude Code 自己的安全模型

plugins/troubleshooting.md +1064 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 排除外掛程式故障

7> 修復 Claude Code 中的外掛程式錯誤。找到您看到的確切訊息，按照 /plugin 執行、安裝和組織政策的階段分組。

9此頁面列出 Claude Code 外掛程式和市集的錯誤訊息和症狀，市集是 Claude Code 安裝外掛程式的目錄。每個項目都提供原因、一個修復方法，以及修復後您會看到的內容。

11如果訊息命名了外掛程式或市集，該項目會顯示一個佔位符，例如 `<name>`。

13無論您是安裝外掛程式、建置外掛程式、託管市集，還是為組織管理外掛程式，都可以使用此頁面。

15<Note>

16 這些情況涵蓋在其他頁面上：

18 * **為什麼範圍、快取和優先順序的行為方式如此**：閱讀 [外掛程式載入參考](/docs/zh-TW/plugins/loading)

19 * **查找旗標、欄位或命令**：使用 [外掛程式命令參考](/docs/zh-TW/plugins/cli-reference)、[清單參考](/docs/zh-TW/plugins/manifest-reference) 或 [市集參考](/docs/zh-TW/plugins/marketplace-reference)

20</Note>

22搜尋您看到的確切訊息。每個訊息都列在產生它的階段下，這不一定是您執行的命令。例如，安裝可能因為市集遺失而失敗，所以該訊息在 [新增市集](#add-a-marketplace) 下。

24<h2 id="find-where-/plugin-runs">

25 找到 `/plugin` 執行的位置

26</h2>

28`/plugin` 是您在執行中的 Claude Code 終端機工作階段內輸入的命令，它會開啟互動式面板。本節中的條目涵蓋您可以輸入它但它無法執行的位置，以及不存在的命令拼寫。

30<h3 id="plugin-isnt-available-in-this-environment">

31 `/plugin isn't available in this environment`

32</h3>

34您在 Claude Code 終端機工作階段以外的地方輸入了 `/plugin`，Claude 回覆了這一行，而不是開啟任何東西。

36您會在沒有終端機來繪製 `/plugin` 面板的工作階段中收到此回覆：[非互動模式](/docs/zh-TW/headless)，使用 `claude -p`、Agent SDK、Claude 桌面應用程式的 Code 標籤、VS Code 擴充功能面板，以及 claude.ai/code 上的瀏覽器。

38在 VS Code 擴充功能面板中，只有 `/plugin` 行後面跟著某些內容（例如 `/plugin install <plugin>@<marketplace>`）會收到此回覆。單獨輸入 `/plugin` 或 `/plugins` 會開啟 **管理外掛程式** 對話框。

40改為從您所在的表面安裝外掛程式：

42* **Claude 桌面應用程式、本機或 SSH 工作階段**：按一下提示旁邊的 **+** 按鈕，然後按 **外掛程式**，然後按 **新增外掛程式** 以開啟 [外掛程式瀏覽器](/docs/zh-TW/desktop#install-plugins)

43* **VS Code 擴充功能**：使用 [安裝外掛程式](/docs/zh-TW/plugins/install#install-a-plugin) 下的 **VS Code** 標籤

44* **網路上的 Claude Code，或桌面雲端工作階段**：雲端工作階段沒有外掛程式瀏覽器。請參閱 [安裝外掛程式](/docs/zh-TW/plugins/install#install-a-plugin) 下的 **雲端工作階段** 標籤，了解雲端工作階段載入的內容

45* **您有權存取的終端機**：執行 `claude` 並在那裡輸入 `/plugin`，或在您的 shell 中執行 `claude plugin install <plugin>@<marketplace>`，而不啟動工作階段

47當終端機安裝成功時，`/plugin` 會列印以 `✓ Installed <plugin>.` 開頭的安裝摘要，而 `claude plugin install` 會列印 `Successfully installed plugin: <plugin>@<marketplace>`。

49<h3 id="zsh-no-such-file-or-directory-plugin">

50 `zsh: no such file or directory: /plugin`

51</h3>

53您在 shell 提示符處輸入了 `/plugin ...`，shell 報告不存在名為 `/plugin` 的檔案。Bash 報告 `bash: /plugin: No such file or directory`。

55`/plugin` 是您在 Claude Code 工作階段內輸入的命令，而不是在 shell 提示符處。啟動工作階段並在那裡輸入相同的命令：

57```shell theme={null}

58claude

59```

61然後，在 Claude Code 提示符處：

63```text theme={null}

64/plugin install <plugin>@<marketplace>

65```

67成功的安裝會列印以 `✓ Installed <plugin>.` 開頭的摘要。如果安裝本身隨後失敗，其訊息在 [新增市集](#add-a-marketplace) 或 [安裝外掛程式](#install-a-plugin) 下。

69若要從 shell 安裝而不啟動工作階段，請改為執行 `claude plugin install <plugin>@<marketplace>`。

71<h3 id="the-term-plugin-is-not-recognized-as-the-name-of-a-cmdlet">

72 `The term '/plugin' is not recognized as the name of a cmdlet`

73</h3>

75您在 PowerShell 提示符處輸入了 `/plugin ...`，而 `/plugin` 是 Claude Code 命令，不是程式。Bash 和 Zsh 報告 [它們自己的這個錯誤形式](#zsh-no-such-file-or-directory-plugin)。

77改為使用以下任一方式：

79* 執行 `claude`，然後在 Claude Code 提示符處輸入 `/plugin`

80* 在 PowerShell 中執行 `claude plugin install <plugin>@<marketplace>`，而不啟動工作階段

82<h3 id="claude-command-not-found-after-claude-plugin">

83 `claude: command not found` after `claude plugin ...`

84</h3>

86您在 shell 中執行了 `claude plugin install ...`，shell 根本找不到 `claude`。在 Windows 上，訊息是 `'claude' is not recognized as the name of a cmdlet` 或 `'claude' is not recognized as an internal or external command`。

88原因不是外掛程式命令。要麼 Claude Code 未安裝，要麼其安裝目錄不在此 shell 中的 `PATH` 上。遵循 [`command not found: claude` after installation](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)，然後重試外掛程式命令。

90<h3 id="unknown-command-and-command-spellings-that-dont-exist">

91 `Unknown command` and command spellings that don't exist

92</h3>

94您輸入了您在某處看到的外掛程式命令，並在工作階段中收到 `Unknown command: /<name>`，或從 shell 中的 `claude` 二進位檔案收到 `error: unknown command '<name>'` 或 `error: unknown option '<flag>'`。

96有幾個命令拼寫在使用中，Claude Code 沒有。下表將每個對應到真實命令。[外掛程式命令參考](/docs/zh-TW/plugins/cli-reference) 列出每個子命令和旗標。

98| 您輸入 | Claude Code 說什麼 | 改為使用 |

99| :----------------------------------------- | :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |

100| `claude plugin add <source>` | `error: unknown command 'add'` | `claude plugin marketplace add <source>` 以新增市集，或 `claude plugin install <plugin>@<marketplace>` 以安裝外掛程式 |

101| `claude plugin install <plugin> --project` | `error: unknown option '--project'` | `claude plugin install <plugin>@<marketplace> --scope project` |

102| `/install <plugin>` | `Unknown command: /install` | `/plugin install <plugin>@<marketplace>` |

103| `/plugin add <source>` | `/plugin` 面板在 **Discover** 標籤上開啟 | `/plugin marketplace add <source>` |

104| `marketplace.anthropic.com` 作為來源 | `Invalid marketplace source format. Try: owner/repo, https://..., or ./path` | `anthropics/claude-plugins-official` 用於官方市集 |

105

106這些拼寫看起來不對但有效：

107

108* `claude plugins` 是 `claude plugin` 的別名

109* `claude plugin remove` 是 `claude plugin uninstall` 的別名

110* `/plugins` 和 `/marketplace` 在工作階段中開啟與 `/plugin` 相同的面板

111

112<h2 id="add-a-marketplace">

113 新增市集

114</h2>

115

116市集是您從 git 儲存庫、URL 或本機路徑新增到 Claude Code 的目錄。這些條目涵蓋當新增失敗或稍後重新整理失敗時您收到的訊息。

117

118<h3 id="marketplace-claude-plugins-official-not-found">

119 `Marketplace "claude-plugins-official" not found`

120</h3>

121

122您在工作階段中執行了 `/plugin install <plugin>@claude-plugins-official`，Claude Code 報告它沒有該名稱的市集。

123

124官方市集尚未在此機器上註冊。Claude Code 通常在您第一次啟動互動式終端機工作階段時自行註冊它。如果您只透過 VS Code 擴充功能使用 Claude Code，它還沒有執行，並且它會跳過或延遲該步驟：

125

126* 當政策阻止來源時

127* 當設定 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 時

128* 在失敗的嘗試之後，等待重試

129

130`claude plugin` shell 命令永遠不會為您註冊它。

131

132新增它，然後重試安裝：

133

134```text theme={null}

135/plugin marketplace add anthropics/claude-plugins-official

136```

137

138Claude Code 列印 `Successfully added marketplace: claude-plugins-official`，而 `/plugin marketplace list` 顯示市集及其來源。

139

140對於此訊息中的任何其他市集名稱，請參閱 [`Marketplace "<name>" not found`](#marketplace-not-found)。

141

142相同的字串也出現在 `/plugin` **Errors** 標籤中，面板的載入失敗清單，當您的設定中列出的外掛程式命名您尚未新增的市集時。

143

144<h3 id="marketplace-not-found">

145 `Marketplace "<name>" not found`

146</h3>

147

148您在工作階段中執行了 `/plugin install <plugin>@<name>`，通常來自某人傳送給您的安裝行，Claude Code 報告它沒有該名稱的市集。

149

150如果名稱以 `claudeai-` 開頭，市集託管在 claude.ai 上，您可以使用 `claude plugin marketplace add --claudeai <name>` 從 shell 按名稱新增它。請參閱 [從 claude.ai 新增市集](/docs/zh-TW/plugins/install#add-from-claude-ai)。

151

152對於任何其他名稱，安裝行命名市集但不說明市集託管在何處，Claude Code 沒有索引來查詢市集名稱。詢問傳送該行的人市集的來源，這是 GitHub `owner/repo`、git URL 或路徑。然後 [新增市集](/docs/zh-TW/plugins/install#add-a-marketplace) 並再次執行安裝行。

153

154某人傳送給您的市集是第三方的，所以 [在安裝前檢查外掛程式](/docs/zh-TW/plugins/security#review-a-plugin-before-you-install)。

155

156如果您已經新增了市集，請根據 `/plugin marketplace list` 檢查拼寫。

157

158<h3 id="invalid-marketplace-source-format">

159 `Invalid marketplace source format`

160</h3>

161

162您執行了 `/plugin marketplace add <source>` 或 `claude plugin marketplace add <source>`，Claude Code 回覆 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`。

163

164Claude Code 接受以下形式之一的來源：

165

166* GitHub `owner/repo` 速記

167* `https://` 或 `http://` URL

168* `user@host:path` SSH URL

169* 以 `./`、`../`、`/` 或 `~` 開頭的本機路徑

170

171裸名稱（例如 `claude-plugins-official`）不符合任何一個。裸主機名稱（例如 `marketplace.anthropic.com`）也不符合。

172

173以接受的形式之一重新輸入來源：

174

175```text theme={null}

176/plugin marketplace add anthropics/claude-plugins-official

177```

178

179當新增成功時，Claude Code 列印 `Successfully added marketplace: <name>`。

180

181<h3 id="is-not-a-valid-github-owner-repo-shorthand">

182 `'<source>' is not a valid GitHub owner/repo shorthand`

183</h3>

184

185您傳遞了一個包含斜線但不是 `owner/repo` 的來源，例如 `github.com/owner/repo` 或 `gitlab.example.com/group/project` 路徑。Claude Code 拒絕了它，並提供了接受的形式清單。

186

187`owner/repo` 速記僅限 GitHub，必須遵循 GitHub 的命名規則，因此主機名稱或額外的路徑段會失敗。以符合市集託管位置的形式傳遞來源：

188

189* **任何主機上的儲存庫**：完整的複製 URL

190* **託管的 `marketplace.json`**：其 `https://` URL

191* **本機簽出**：`./path` 或絕對路徑

192

193例如，若要透過其複製 URL 新增官方市集，請在工作階段中：

194

195```text theme={null}

196/plugin marketplace add https://github.com/anthropics/claude-plugins-official.git

197```

198

199成功的新增會列印 `Successfully added marketplace: <name>`。

200

201<h3 id="path-does-not-exist">

202 `Path does not exist: <path>`

203</h3>

204

205您傳遞了本機路徑給 `marketplace add`，該路徑處沒有任何內容。相對路徑相對於您的目前目錄解析。

206

207檢查訊息中的已解析路徑。然後從相對路徑開始的目錄執行命令，或傳遞市集目錄的絕對路徑。成功的新增會列印 `Successfully added marketplace: <name>`。

208

209Claude Code 接受包含 `.claude-plugin/marketplace.json` 的目錄，或指向 `.json` 檔案的路徑。指向任何其他檔案的路徑會失敗，並顯示 `File path must point to a .json file (marketplace.json)`。

210

211<h3 id="marketplace-file-not-found-at-claude-plugin-marketplace-json">

212 `Marketplace file not found at <path>/.claude-plugin/marketplace.json`

213</h3>

214

215Claude Code 複製或下載了市集，但在其內部的預期路徑中找不到 `marketplace.json`。新增命令將其報告為 `Failed to add marketplace: Marketplace file not found at ...`。

216

217預設位置是儲存庫根目錄中的 `.claude-plugin/marketplace.json`，[市集參考](/docs/zh-TW/plugins/marketplace-reference) 列出接受的位置。

218

219修復因所有者和其他人而異：

220

221* **您擁有市集**：將檔案放在該位置並重新新增市集

222* **其他人託管它**：詢問所有者確切的來源他們發佈

223

224<h3 id="ssh-authentication-failed-or-https-authentication-failed">

225 `SSH authentication failed` or `HTTPS authentication failed`

226</h3>

227

228您從 git 儲存庫新增或更新了市集，複製失敗，並顯示 `Failed to clone marketplace repository:` 後跟以下其中一行。

229

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

231

232如果儲存庫是正確的，原因是認證。Claude Code 執行 git 時禁用互動式提示，因此它無法像您的終端機那樣要求您輸入密碼、金鑰密碼或認證。如果 git 需要提示，您會看到 `fatal: Cannot prompt because user interactivity has been disabled` 或 `terminal prompts disabled` 在原始錯誤中。只有已經非互動式工作的認證才會成功：

233

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

235* **HTTPS**：您的認證助手必須為主機保存令牌。對於 GitHub，執行 `gh auth login` 和 `gh auth setup-git`。對於另一個主機，在您的 git 認證助手中儲存個人存取令牌。使用 `git ls-remote <url>` 測試

236

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

238

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

240

241有關背景自動更新可以和不能對您的認證做什麼，請參閱 [背景自動更新對認證的作用](/docs/zh-TW/plugins/host-marketplace#what-background-auto-update-does-with-credentials)。

242

243<h3 id="ssh-host-key-is-not-in-your-known-hosts-file">

244 `SSH host key is not in your known_hosts file`

245</h3>

246

247您從您從未連接過的主機透過 SSH 新增了市集，複製失敗，並顯示此行和 `ssh -T git@<host>` 提示。對於金鑰已更改的主機，訊息是 `SSH host key has changed`，並改為提供 `ssh-keygen -R <host>` 提示。

248

249Claude Code 使用 `StrictHostKeyChecking=yes` 複製，因此它拒絕您尚未接受其金鑰的主機，而不是自動接受金鑰。從您的終端機連接一次以接受指紋，然後重試：

250

251```shell theme={null}

252ssh -T git@github.com

253```

254

255對於公開儲存庫，改為使用其 `https://` URL 新增市集，以完全避免 SSH。

256

257<h3 id="command-git-not-found-or-is-in-an-unsafe-location">

258 `Command 'git' not found or is in an unsafe location`

259</h3>

260

261在 Windows 上，您新增了市集，Claude Code 報告 `Failed to clone marketplace repository: Command 'git' not found or is in an unsafe location (current directory)`。

262

263Claude Code 在您的 `PATH` 上查找 `git`，並拒絕執行僅在目前目錄中找到的。若要修復它，請安裝 Git 並重試：

264

265<Steps>

266 <Step title="安裝 Git for Windows">

267 安裝 Git for Windows，使 `git` 在您的 `PATH` 上。

268 </Step>

269

270 <Step title="開啟新終端機">

271 開啟新終端機，使更新的 `PATH` 適用。

272 </Step>

273

274 <Step title="確認 git 執行">

275 確認 `git --version` 列印版本。

276 </Step>

277

278 <Step title="重試新增">

279 再次執行 `marketplace add` 命令。

280 </Step>

281</Steps>

282

283<h3 id="git-clone-timed-out-after-120s">

284 `Git clone timed out after 120s`

285</h3>

286

287您新增或更新了市集，它失敗，並顯示 `Git clone timed out after 120s`，後跟設定 `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` 的提示。

288

289複製市集和重新複製一個以更新它，預設情況下獲得 120 秒。對於大型儲存庫或緩慢連接，提高限制。該值以毫秒為單位：

290

291<Tabs>

292 <Tab title="Bash or Zsh">

293 ```bash theme={null}

294 export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000

295 ```

296 </Tab>

297

298 <Tab title="PowerShell">

299 ```powershell theme={null}

300 $env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"

301 ```

302 </Tab>

303</Tabs>

304

305然後在同一 shell 中重試。

306

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

308

309<h3 id="marketplace-updates-keep-failing-offline">

310 Marketplace updates keep failing offline

311</h3>

312

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

314

315每個工作階段，對於 [開啟自動更新](/docs/zh-TW/plugins/loading#which-marketplaces-and-plugins-auto-update) 的市集，Claude Code 在背景中檢查市集的 git 主機是否有新提交。當該檢查無法到達主機時，它會嘗試再次複製市集，離線時該複製也會失敗。

316

317設定此變數以跳過重新複製嘗試，並在檢查無法到達主機時繼續使用現有簽出：

318

319<Tabs>

320 <Tab title="Bash or Zsh">

321 ```bash theme={null}

322 export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

323 ```

324 </Tab>

325

326 <Tab title="PowerShell">

327 ```powershell theme={null}

328 $env:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = "1"

329 ```

330 </Tab>

331</Tabs>

332

333設定變數後，Claude Code 僅對已包含 `.claude-plugin/marketplace.json` 的簽出跳過重新複製。從未複製或其複製中途停止的市集仍會獲得複製嘗試，因此在線上新增一次。

334

335對於完全離線部署，改為在映像建置時使用 `CLAUDE_CODE_PLUGIN_SEED_DIR` 預先填充外掛程式目錄，遵循 [種子容器和 CI](/docs/zh-TW/plugins/org#seed-containers-and-ci)。

336

337<h3 id="marketplace-add-fails-on-a-github-enterprise-server-host">

338 Marketplace add fails on a GitHub Enterprise Server host

339</h3>

340

341您從 GitHub Enterprise Server (GHES) URL 新增了市集，並收到政策錯誤，或您從 claude.ai 新增了它，並收到 GitHub 存取錯誤。

342

343兩種情況都在 GHES 頁面上：

344

345* [政策錯誤](/docs/zh-TW/github-enterprise-server#marketplace-add-fails-with-a-policy-error) 表示您的組織限制了市集來源，管理員需要為主機新增 `hostPattern`

346* [claude.ai 上的 GitHub 存取錯誤](/docs/zh-TW/github-enterprise-server#marketplace-add-on-claude-ai-fails-with-a-github-access-error) 表示您自己的 GitHub Enterprise 帳戶尚未連接

347

348<h2 id="install-a-plugin">

349 安裝外掛程式

350</h2>

351

352您新增了市集並執行了安裝，安裝停止並顯示訊息，而不是安裝任何內容。這些條目涵蓋這些訊息。它們也涵蓋稍後出現在 `/plugin` **Errors** 標籤中的相關訊息，或當外掛程式或其市集無法找到、讀取或信任時的空白 **Discover** 標籤。

353

354<h3 id="plugin-not-found-in-marketplace">

355 `Plugin "<name>" not found in marketplace "<marketplace>"`

356</h3>

357

358您執行了 `/plugin install <name>@<marketplace>` 或 `claude plugin install <name>@<marketplace>`，外掛程式名稱不在您機器上該市集目錄的副本中。

359

360當您根本沒有新增市集時，`claude plugin install` 在您的 shell 中列印相同的訊息。如果 `claude plugin marketplace update <marketplace>` 然後回答 `Marketplace '<marketplace>' not found`，[首先新增市集](#add-a-marketplace)。

361

362<h4 id="the-message-ends-with-a-refresh-hint">

363 `not found in marketplace` with a refresh hint

364</h4>

365

366提示讀取 `Your local copy may be out of date — try claude plugin marketplace update <marketplace>` 或 `The marketplace couldn't be refreshed (...)`。Claude Code 在查詢前沒有重新整理市集，例如當您離線時，所以您的目錄副本可能已過時。使用市集的名稱重新整理，然後再次安裝：

367

368```text theme={null}

369/plugin marketplace update <marketplace>

370```

371

372`claude plugin marketplace update` 列印 `Successfully updated marketplace: <name>`，而 `/plugin marketplace update` 顯示 `✔ Updated 1 marketplace`。如果重試的安裝列印相同的訊息，請按照 [`not found in marketplace` with no hint](#the-message-has-no-hint) 描述檢查名稱。[Claude Code 何時在安裝前重新整理市集](/docs/zh-TW/plugins/loading#when-claude-code-refreshes-a-marketplace-before-an-install) 列出重新整理不執行的其他情況。

373

374<h4 id="the-message-has-no-hint">

375 `not found in marketplace` with no hint

376</h4>

377

378名稱是最可能的問題。開啟 `/plugin`，前往 **Discover**，並從清單中複製名稱。

379

380在 v2.1.232 之前，Claude Code 僅在查詢未命中後重新整理命名的市集，並且僅當為其開啟自動更新時。

381

382<h3 id="plugin-not-found-in-any-marketplace">

383 `Plugin "<name>" not found in any marketplace`

384</h3>

385

386您執行了 `/plugin install <name>`，沒有 `@marketplace`，沒有註冊的市集有該外掛程式。`claude plugin install <name>` 報告 `Plugin "<name>" not found in any configured marketplace`。

387

388沒有市集名稱，`claude plugin install` 搜尋它已有的目錄，不會首先重新整理它們，而 `/plugin install` 僅重新整理開啟自動更新的市集。命名市集，Claude Code 在查詢外掛程式前重新整理它：

389

390```text theme={null}

391/plugin install <name>@<marketplace>

392```

393

394當安裝成功時，您在工作階段中看到 `✓ Installed <plugin>.`，或從 `claude plugin install` 看到 `Successfully installed plugin: <plugin>@<marketplace>`。

395

396如果您不知道哪個市集列出外掛程式，請執行 `/plugin marketplace list` 以取得您擁有的市集，並在 `/plugin` 中瀏覽 **Discover** 以查找外掛程式名稱。

397

398<h3 id="plugin-is-already-installed-globally">

399 `Plugin '<name>@<marketplace>' is already installed globally`

400</h3>

401

402您為已在使用者範圍或由受管設定安裝的外掛程式執行了 `/plugin install`，Claude Code 拒絕了 `Use '/plugin' to manage existing plugins.`。如果您輸入了沒有 `@<marketplace>` 的外掛程式名稱，訊息會省略 `globally`。

403

404外掛程式已在每個專案中可用，因此沒有任何內容要新增。若要變更其 [範圍](/docs/zh-TW/plugins/install)、啟用或停用它，或配置它，請開啟 `/plugin` 並前往 **Installed**。

405

406僅在專案或本機範圍安裝的外掛程式不會觸發此訊息。Claude Code 允許您也在使用者範圍安裝它，因此它在其他專案中可用。

407

408`claude plugin install` 在您的 shell 中列印不同的訊息。對於已在目標範圍安裝的外掛程式，它列印 `Plugin "<name>@<marketplace>" is already installed (scope: user)` 並以退出代碼 0 退出。如果其快取目錄遺失，相同的命令會重新下載它。

409

410<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">

411 `This plugin uses a source type your Claude Code version does not support`

412</h3>

413

414您安裝了一個外掛程式，其市集條目使用此版本 Claude Code 無法擷取的來源類型，Claude Code 停止並顯示此訊息和 `Update Claude Code and try again.`

415

416更新 Claude Code，然後重試安裝。來源類型在 [市集參考](/docs/zh-TW/plugins/marketplace-reference) 上。

417

418<h3 id="plugin-archive-integrity-check-failed">

419 `Plugin archive integrity check failed`

420</h3>

421

422您安裝了一個作為 zip 存檔分發的外掛程式，Claude Code 拒絕了它，並顯示此行和 `The archive was not installed.`。外掛程式的市集條目使用帶有 `sha256` 釘選的 [`archive` 來源](/docs/zh-TW/plugins/marketplace-reference)，下載的檔案的摘要與釘選不符。

423

424完整訊息如下所示：

425

426```text theme={null}

427Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

428```

429

430修復因發佈者和安裝程式而異：

431

432* **您發佈外掛程式**：重新計算 URL 提供的確切檔案的摘要，並更新市集條目中的 `sha256`。使用 `shasum -a 256 my-plugin.zip` 或 PowerShell 中的 `Get-FileHash -Algorithm SHA256 my-plugin.zip`

433* **您安裝外掛程式**：在工作階段中執行 `/plugin marketplace update <name>` 以重新整理目錄，以防條目已更正，然後重試安裝。如果重新整理後摘要仍然不同，請詢問市集所有者在安裝前他們釘選了哪個檔案

434

435<h3 id="marketplace-is-registered-from-an-untrusted-source">

436 `Marketplace "<name>" is registered from an untrusted source`

437</h3>

438

439您之前新增的市集停止載入，其外掛程式也停止載入。此行出現在 `/plugin` **Errors** 標籤或下一次重新整理時。

440

441市集以 [為官方 Anthropic 市集保留](/docs/zh-TW/plugins/marketplace-reference) 的名稱註冊，但其註冊來源不是 `anthropics` GitHub 儲存庫。每次市集載入或重新整理時都會重新檢查保留的名稱，因此市集和從它安裝的外掛程式停止載入。

442

443完整訊息命名保留的名稱和修復：

444

445```text theme={null}

446Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

447```

448

449修復因使用者和發佈者而異：

450

451* **您使用市集**：在您的 shell 中，執行 `claude plugin marketplace remove <name>`，然後從官方 `github.com/anthropics` 儲存庫再次新增市集

452* **您發佈了在其名稱變為保留前使用該名稱的第三方市集**：重新命名它，並要求使用者從您的來源重新新增它

453

454在 v2.1.205 之前，Claude Code 僅在您新增市集時檢查名稱，因此在其名稱變為保留前註冊的條目保持載入。

455

456<h3 id="plugin-has-a-corrupt-manifest-file-or-has-an-invalid-manifest-file">

457 `Plugin <name> has a corrupt manifest file` or `has an invalid manifest file`

458</h3>

459

460Claude Code 擷取了外掛程式，然後無法讀取其 `.claude-plugin/plugin.json`。在 shell 中，此行中的 `<name>` 可以是臨時目錄名稱；`Failed to install plugin "<name>@<marketplace>"` 前綴帶有外掛程式的真實名稱。措辭說明哪個檢查失敗：

461

462* **`corrupt manifest file`，後跟 `JSON parse error:`**：檔案不是有效的 JSON

463* **`invalid manifest file`，後跟 `Validation errors:`**：檔案解析但失敗架構，例如 `name: Invalid input` 用於遺失的必需欄位

464

465`claude plugin install` 報告為 `Failed to install plugin "<name>@<marketplace>":` 並以代碼 1 退出。

466

467外掛程式的作者必須修復檔案，在那之前無法安裝外掛程式：

468

469* **如果那是您**：在您的 shell 中執行 `claude plugin validate <plugin-directory>` 以查看相同的錯誤及其違規路徑，然後修復檔案

470* **如果不是您**：向市集所有者報告訊息

471

472<h3 id="plugin-directory-not-found-at-path">

473 `Plugin directory not found at path: <path>`

474</h3>

475

476`/plugin` 中的 **Errors** 標籤顯示這個用於啟用的外掛程式，其市集按相對路徑列出，例如 `./plugins/my-plugin`，當市集內該路徑處沒有目錄時。如果您維護市集，請更正條目的 `source` 路徑或還原資料夾。否則，向市集所有者報告訊息。

477

478`Marketplace directory not found at path: <path>` 表示市集自己的目錄遺失。對於您從本機路徑新增的市集，該目錄已移動或已刪除。還原它，或移除市集並從其新位置再次新增它。

479

480<h3 id="no-plugins-available-or-no-marketplaces-configured">

481 `No plugins available` or `No marketplaces configured`

482</h3>

483

484您開啟了 `/plugin`，**Discover** 標籤為空，或 `claude plugin marketplace list` 列印 `No marketplaces configured`。

485

486沒有市集註冊，因此沒有目錄可顯示。在工作階段中，新增官方市集 `anthropics/claude-plugins-official`：

487

488```text theme={null}

489/plugin marketplace add anthropics/claude-plugins-official

490```

491

492Claude Code 列印 `Successfully added marketplace: claude-plugins-official`，而 **Discover** 列出其外掛程式。[Anthropic 市集](/docs/zh-TW/plugins/anthropic-marketplaces) 頁面列出您可以新增的其他市集。

493

494<h3 id="marketplace-is-already-added-from-a-different-source">

495 `Marketplace "<name>" is already added from a different source`

496</h3>

497

498您確認透過 [`/plugin install <plugin> --marketplace <source>`](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command) 新增市集，Claude Code 從該來源擷取的目錄與您已從不同來源新增的市集具有相同的名稱。Claude Code 保留現有市集而不是替換它，外掛程式未安裝。

499

500完整訊息如下所示：

501

502```text theme={null}

503Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

504```

505

506選擇您想要的來源：

507

508* **您已新增的市集**：使用 `/plugin install <plugin>@<name>` 按名稱從它安裝

509* **新來源**：執行 `/plugin marketplace remove <name>`，然後重試安裝

510

511<h3 id="cannot-add-marketplace-its-network-source-differs">

512 `Cannot add marketplace "<name>": its network source differs from the one declared for it in settings`

513</h3>

514

515您執行了 `marketplace add`，該來源的目錄與設定檔已在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 下以不同來源宣告的市集具有相同的名稱。Claude Code 拒絕新增並註冊任何內容。

516

517訊息以修復結尾：來源必須符合設定中為此名稱宣告的來源，或您變更宣告。將您傳遞的來源與該名稱的 `extraKnownMarketplaces` 條目進行比較，包括其 `ref`、`path` 和 `headers`，然後執行以下其中一項：

518

519* **使用宣告的來源**：從設定條目命名的來源新增市集

520* **使用新來源**：編輯或移除 `extraKnownMarketplaces` 條目，然後再次新增市集。如果受管設定宣告它，請詢問您的管理員

521

522<h3 id="failed-to-install-from-the-plugin-menu">

523 `Failed to install: <plugin> (<reason>)`

524</h3>

525

526您在 `/plugin` 功能表中選擇了要安裝的外掛程式，沒有任何一個安裝，功能表關閉並顯示失敗的摘要。

527

528某些原因（例如失敗複製後的 git 輸出）僅顯示其第一行。當這樣的原因被縮短時，摘要以 `Installing a plugin from its details (Enter) in /plugin shows its full error.` 結尾

529

530該做什麼取決於摘要是否縮短了原因：

531

532* 修復括號中原因命名的內容

533* 當原因被縮短時，執行 `/plugin`，在 **Discover** 標籤上選擇外掛程式，然後按 **Enter** 從其詳細資訊安裝它。如果安裝在那裡失敗，詳細資訊檢視會顯示整個錯誤

534

535<h3 id="could-not-move-the-new-copy-of-this-plugin-version">

536 `Could not move the new copy of this plugin version into <path>`

537</h3>

538

539當您安裝外掛程式時，Claude Code 下載其檔案的新副本，並將其移動到 [外掛程式快取](/docs/zh-TW/plugins/loading#find-plugins-on-disk) 中該版本的資料夾。此訊息表示移動失敗，通常是因為另一個程式在安裝執行時使用了該資料夾。檔案系統代碼出現在括號中：

540

541```text theme={null}

542Could not move the new copy of this plugin version into /home/user/.claude/plugins/cache/acme-tools/formatter/1.2.0: the new copy or the version folder stayed busy while the install ran (ENOTEMPTY) — usually a scanner still reading the freshly downloaded files, another program using that folder, or another process re-creating it. The previously installed copy was moved back. Run the install again once other Claude Code sessions or programs using that folder have finished.

543```

544

545訊息說明了安裝前的副本發生了什麼，這告訴您外掛程式是否仍然有效：

546

547* `The previously installed copy was moved back`：您擁有的版本仍然安裝

548* `had to be removed first`、`was not moved back` 或 `could not be moved back`：該外掛程式版本在安裝成功前未安裝

549* 沒有這樣的句子：沒有較早的副本，因此版本未安裝

550

551在 Windows 上，當另一個程式持有已安裝的副本本身時，訊息改為說該副本 `could not be replaced`，並且 `It was not replaced and the new copy was discarded`，因此您擁有的版本仍然安裝。

552

553`Left on disk` 清單命名快取內的預留資料夾。稍後安裝該版本或外掛程式快取清理會移除它們，因此您不需要刪除它們。

554

555若要修復安裝：

556

557* 關閉使用外掛程式資料夾（在 `~/.claude/plugins/cache` 下）的其他 Claude Code 工作階段、編輯器和終端機，然後再次執行安裝

558* 當訊息說檢查外掛程式快取資料夾的權限時，還原您對其命名的資料夾的寫入權限並釋放磁碟空間，然後再次執行安裝

559

560<h3 id="dependency-errors">

561 Dependency errors

562</h3>

563

564宣告依賴項的外掛程式在無法滿足依賴項時可能無法安裝或安裝並保持停用。訊息在安裝時或載入時到達您：

565

566* **在安裝期間**：拒絕作為安裝的錯誤訊息返回

567* **當外掛程式載入時**：問題出現在 `claude plugin list` 和 `/plugin` **Errors** 標籤中，Claude Code 保持受影響的外掛程式停用，直到您解決它

568

569下表列出每個訊息及其修復。若要作為作者宣告依賴項，請參閱 [外掛程式依賴項](/docs/zh-TW/plugins/dependencies)。

570

571| 訊息 | 含義 | 如何解決 |

572| :--------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |

573| `Dependency "<dep>" is not installed` | 宣告的依賴項未安裝。 | 使用 `claude plugin install <dep>@<marketplace>` 在您的 shell 中安裝它，或卸載外掛程式。如果依賴項的市集尚未註冊，請新增它並在您的工作階段中執行 `/reload-plugins`，這會安裝它可以解決的遺失依賴項。 |

574| `Dependency "<dep>" is disabled` | 依賴項已安裝但已關閉。 | 啟用依賴項，或卸載需要它的外掛程式。 |

575| `Requires "<dep>" <range>, installed <version>` | 已安裝的依賴項版本超出外掛程式的宣告範圍。 | 將依賴項更新到範圍內的版本，或卸載外掛程式。 |

576| `<Plugin or Dependency> "<name>" has conflicting version requirements` | 沒有版本滿足每個釘選它的範圍。訊息列出範圍。 | 卸載或更新其中一個衝突的外掛程式，或要求上游作者擴大其約束。 |

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

578| `... has no git tag satisfying <range>` | 依賴項的儲存庫在範圍內沒有 `<name>--v*` 標籤。 | 檢查上游是否使用該約定標記版本，或放寬範圍。 |

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

580

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

582

583<h2 id="plugin-installed-but-not-working">

584 外掛程式已安裝但無法運作

585</h2>

586

587安裝成功，但外掛程式的技能、hooks 或伺服器沒有執行任何操作。從 [外掛程式不出現或其技能不顯示](#plugin-doesnt-appear-or-its-skills-dont-show-up) 開始，它告訴您 Claude Code 報告它載入的位置，然後符合訊息。

588

589<h3 id="plugin-doesnt-appear-or-its-skills-dont-show-up">

590 Plugin doesn't appear or its skills don't show up

591</h3>

592

593您安裝了外掛程式並輸入 `/` 期望其技能，或要求 Claude 使用它，但沒有任何反應。

594

595在變更任何內容前檢查外掛程式的狀態：

596

597<Steps>

598 <Step title="確認外掛程式已安裝並啟用">

599 執行 `/plugin` 並開啟 **Installed**。確認外掛程式已列出並啟用。`claude plugin list` 在您的 shell 中列印相同的清單，每個外掛程式的版本、範圍和 `Status: ✔ enabled`。

600 </Step>

601

602 <Step title="讀取 Errors 標籤">

603 在同一面板中開啟 **Errors** 標籤。每個條目將訊息與指導行配對。本節其餘部分的大多數訊息來自該標籤。

604 </Step>

605

606 <Step title="如果您在此工作階段期間安裝，請重新載入">

607 如果外掛程式已安裝且無錯誤，但您在此工作階段期間安裝了它，請執行 `/reload-plugins`。它列印 `Reloaded:` 及外掛程式、技能、代理、hooks 和伺服器的計數。當某些失敗時，它新增 `N errors during load. Run /plugin for details.`

608 </Step>

609</Steps>

610

611如果外掛程式載入無錯誤且其技能仍未出現，下一步因您自己的外掛程式和其他人的而異：

612

613* **您正在建置的外掛程式**：請參閱 [外掛程式載入但其技能遺失](#plugin-loads-but-its-skills-are-missing)

614* **某人發佈的外掛程式**：在 `/plugin` 中開啟 **Installed**，並開啟外掛程式的詳細資訊窗格，其中列出外掛程式包含的內容。在那裡列出無技能的外掛程式在您輸入 `/` 時沒有任何內容可提供

615

616<h3 id="run-reload-plugins-to-activate">

617 `Run /reload-plugins to activate.`

618</h3>

619

620`/plugin` 中的安裝摘要以 `Run /reload-plugins to activate.` 結尾，而不是 `Plugin is now active.`

621

622Claude Code 在安裝期間沒有啟用外掛程式，要麼是因為啟用它會 [使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，要麼是因為啟用嘗試失敗。

623

624您不需要輸入命令。面板關閉，Claude Code 為您執行 `/reload-plugins`，或將其排隊直到正在串流的回應完成。

625

626讀取該重新載入列印的內容：

627

628* **`Reloaded:` 及外掛程式、技能、代理、hooks 和伺服器的計數**：外掛程式現在處於活動狀態。當某些無法載入時，該行新增 `N errors during load. Run /plugin for details.`

629* **`This reload changes MCP tools (...) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.`**：重新載入會新增或移除外掛程式 MCP 伺服器，或 `LSP` 工具，並使您的提示快取失效。對於 LSP 情況，該行以 `This reload adds the LSP tool` 或 `This reload removes the LSP tool` 開頭。執行它時使用 `--force` 以啟用外掛程式，或啟動新工作階段

630

631在 v2.1.268 之前，在安裝期間未啟用的安裝保持待處理，直到您自己執行 `/reload-plugins`。

632

633在 v2.1.246 之前，該摘要中的技能計數僅包括外掛程式的 `commands/` 條目，因此重新載入可以載入外掛程式的 `SKILL.md` 技能，仍然報告 `0 skills`。

634

635<h3 id="plugin-not-cached-at">

636 `Plugin "<name>" not cached at <path>`

637</h3>

638

639**Errors** 標籤顯示此行及指導 `Run /plugin to refresh the plugin cache`。Claude Code 有外掛程式的安裝記錄，但記錄指向的目錄遺失，例如在您清除快取後。

640

641從您的 shell 重新安裝外掛程式。`claude plugin install <name>@<marketplace>` 重新下載外掛程式，其安裝目錄遺失，即使其記錄存在：

642

643```shell theme={null}

644claude plugin install <name>@<marketplace>

645```

646

647然後在您的工作階段中執行 `/reload-plugins`。**Errors** 標籤條目消失，外掛程式回到 **Installed** 下。

648

649<h3 id="a-plugin-you-disabled-still-loads">

650 `Disabled in ~/.claude/settings.json but still loads`

651</h3>

652

653您在 `~/.claude/settings.json` 中將外掛程式設定為 `false`，其在 `claude plugin list` 或 `/plugin` 中的行顯示此訊息，後跟啟用它的來源，例如 `— project settings enable it, which overrides your user setting`。該更高優先順序來源中的 `true` 正在覆蓋您的使用者設定。

654

655若要在您的機器上選擇退出專案啟用的外掛程式，請在 `.claude/settings.local.json` 中將 id 設定為 `false`，其優先順序高於專案檔案。對於訊息可以命名的其他來源，請參閱 [在使用者設定中停用但仍然載入](/docs/zh-TW/plugins/loading#disabled-in-user-settings-but-still-loads)。

656

657如果 `claude plugin list` 改為將外掛程式標記為 `required by your org`，沒有設定檔涉及：您的組織在 claude.ai 上將該同步外掛程式標記為必需，即使您之前停用了它，它也會載入。請參閱 [從 claude.ai 同步的外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)。

658

659<h3 id="plugin-is-enabled-in-project-settings-but-isnt-installed-here">

660 `Plugin "<name>" is enabled in project settings but isn't installed here`

661</h3>

662

663**Errors** 標籤顯示此行用於您的專案的 `.claude/settings.json` 啟用的外掛程式，指導 `Run claude plugin install <name>@<marketplace> --scope project to install it for this project`。

664

665儲存庫的設定可以為打開它的每個人啟用外掛程式，但它們不會安裝它。當外掛程式來自外部來源（例如 GitHub 儲存庫或 npm 套件）時，Claude Code 在您自己安裝它之前不會下載它。從指導行在您的 shell 中執行命令，然後重新載入：

666

667```shell theme={null}

668claude plugin install <name>@<marketplace> --scope project

669```

670

671在您的工作階段中執行 `/reload-plugins` 後，**Errors** 標籤條目消失，外掛程式列在 **Installed** 下。

672

673如果您的組織為您預先安裝外掛程式，它會透過受管設定執行此操作。請參閱 [預先安裝和要求外掛程式](/docs/zh-TW/plugins/org#pre-install-and-require-plugins)。

674

675<h3 id="failed-to-load-hooks-from-and-hooks-that-dont-fire">

676 `Failed to load hooks from <path>` and hooks that don't fire

677</h3>

678

679外掛程式的 hooks 不執行。要麼 **Errors** 標籤顯示它們的載入失敗，hooks 載入且您在文字記錄中看到 `<Event> hook error` 通知，要麼 hook 載入無錯誤且永遠不會觸發。

680

681<h4 id="hooks-fail-to-load">

682 Hooks fail to load

683</h4>

684

685**Errors** 標籤顯示以下其中一個訊息：

686

687* **`Failed to load hooks from <path>: <reason>`**：`hooks/hooks.json` 不是有效的 JSON 或失敗 hooks 架構。原因命名解析或驗證錯誤。修復檔案。若要在發佈外掛程式前在 `hooks/hooks.json` 中捕捉 JSON 語法問題，請在您的 shell 中執行 `claude plugin validate <plugin-directory>`

688* **`hooks path not found: <path>`**：清單的 `hooks` 欄位命名在相對於外掛程式根目錄的該路徑處不存在的檔案。修復路徑或新增檔案

689

690<h4 id="hook-error-notices-in-the-transcript">

691 `hook error` notices in the transcript

692</h4>

693

694形式為 `... hook error: Failed with non-blocking status code: <stderr>` 的通知表示 hook 執行且其命令失敗。例如，`Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found` 表示 Claude Code 產生的 shell 找不到 `node`。安裝它，或確保它在您啟動 `claude` 的終端機的 `PATH` 上。

695

696對於任何其他錯誤，從外掛程式目錄自行執行 hook 的命令以查看完整輸出，或使用 [偵錯記錄](/docs/zh-TW/hooks#debug-hooks) 捕捉完整 stderr。

697

698<h4 id="hook-loads-but-never-fires">

699 Hook loads but never fires

700</h4>

701

702如果 hook 載入無錯誤但永遠不會觸發，請檢查其定義，然後觀看它執行：

703

704<Steps>

705 <Step title="檢查事件名稱">

706 事件名稱區分大小寫，因此確認您的名稱完全符合，例如 `PostToolUse`。

707 </Step>

708

709 <Step title="檢查匹配器">

710 確認 hook 的 `matcher` 符合工具名稱。

711 </Step>

712

713 <Step title="故意觸發事件">

714 對於 `PostToolUse` hook，要求 Claude 編輯檔案。

715 </Step>

716

717 <Step title="讀取偵錯日誌">

718 開啟 [偵錯日誌](/docs/zh-TW/hooks#debug-hooks)，其記錄哪些 hooks 符合。執行的 hook 會出現在那裡及其退出代碼。

719 </Step>

720</Steps>

721

722<h3 id="invalid-mcp-server-config-for-and-mcp-servers-that-dont-start">

723 `Invalid MCP server config for "<server>"` and MCP servers that don't start

724</h3>

725

726外掛程式捆綁了 MCP 伺服器，**Errors** 標籤顯示 `Invalid MCP server config for "<server>": <error>`，或伺服器已列出但 `/mcp` 永遠不會顯示它已連接。

727

728<h4 id="invalid-mcp-server-config-for-server-error">

729 `Invalid MCP server config for "<server>": <error>`

730</h4>

731

732伺服器的配置通過架構檢查，但 Claude Code 無法為此工作階段解決它。冒號後的文字命名原因並決定修復：

733

734* **`Missing environment variables: <names>`**：在啟動 Claude Code 的 shell 中設定這些變數，然後啟動新工作階段

735* **`URL is unset or invalid`**：URL 使用的 `${user_config.*}` 選項未設定。執行 `/plugin configure <plugin>` 以設定它

736* **`has an invalid MCP url`** 或 **`headersHelper for MCP server '<server>' references ${user_config.*}`**：外掛程式自己的配置有問題。修復您外掛程式的 MCP 配置中的 `url` 或 `headersHelper`，或如果外掛程式不是您的，向外掛程式的作者報告。`headersHelper` 情況在 [外掛程式命令參考 user\_config](/docs/zh-TW/errors#plugin-command-references-user-config) 下有自己的條目

737

738<h4 id="server-is-configured-but-never-connects">

739 Server is configured but never connects

740</h4>

741

742執行 `/mcp` 以查看伺服器的狀態。當伺服器健康時，`/mcp` 將其列為已連接。

743

744若要讀取伺服器在啟動時列印的錯誤，請執行 `claude --debug` 並在 `~/.claude/debug/<session-id>.txt` 開啟日誌。`--debug` 旗標不會列印到終端機。

745

746`.mcp.json` 中失敗架構的伺服器條目不會出現在 **Errors** 標籤中。Claude Code 丟棄該伺服器，並僅在該偵錯日誌中記錄 `Invalid MCP server config for <server> in <path>`。若要在不載入外掛程式的情況下找到條目，請在外掛程式目錄上在您的 shell 中執行 `claude plugin validate`，它將其報告為錯誤。

747

748在 v2.1.281 之前，`claude plugin validate` 沒有檢查 `.mcp.json`。

749

750<h4 id="server-works-with-plugin-dir-but-fails-after-install">

751 Server works with `--plugin-dir` but fails after install

752</h4>

753

754您是外掛程式的作者，伺服器在您使用 `--plugin-dir` 從其來源目錄載入外掛程式時啟動，但在安裝後失敗。

755

756Claude Code 將已安裝的外掛程式複製到其快取中，因此僅從來源目錄工作的路徑會中斷。使用 `${CLAUDE_PLUGIN_ROOT}` 在外掛程式內寫入路徑。

757

758對於到達外掛程式目錄外的路徑，請參閱 [外掛程式參考的外掛程式目錄外的檔案未找到](#files-the-plugin-references-outside-its-directory-arent-found)。

759

760<h3 id="language-server-doesnt-start">

761 Language server doesn't start, uses too much memory, or reports wrong diagnostics

762</h3>

763

764您安裝了 [程式碼智慧外掛程式](/docs/zh-TW/plugins/code-intelligence)，Claude 沒有看到診斷，或語言伺服器使用太多記憶體或報告不是真實的錯誤。

765

766<h4 id="language-server-doesn’t-start">

767 Language server doesn't start

768</h4>

769

770外掛程式連接到您單獨安裝的語言伺服器二進位檔案，Claude Code 從您的 `PATH` 按命令名稱產生它。

771

772`/plugin` **Errors** 標籤顯示失敗及其原因，例如 `Executable not found in $PATH: "<binary>"`，而 `claude --debug` 將其記錄為 `LSP server <name> failed to start: <reason>`。

773

774安裝二進位檔案並確認它在您啟動 `claude` 的終端機的 `PATH` 上，例如使用 `which typescript-language-server`。然後啟動新工作階段。

775

776<h4 id="language-server-uses-too-much-memory">

777 Language server uses too much memory

778</h4>

779

780語言伺服器（例如 `rust-analyzer` 和 `pyright`）索引整個專案。使用 `/plugin disable <plugin>` 在工作階段中停用外掛程式，並改為依賴 Claude 的內建搜尋工具。

781

782<h4 id="false-positive-diagnostics-in-a-monorepo">

783 False positive diagnostics in a monorepo

784</h4>

785

786未為工作區配置的語言伺服器可以報告內部套件的未解決匯入。Claude Code 端沒有任何內容要修復，診斷不會阻止 Claude 編輯程式碼。

787

788<h2 id="build-a-plugin">

789 建立外掛程式

790</h2>

791

792您正在開發外掛程式，並使用 `--plugin-dir` 載入它或從本機市集安裝它。這些項目涵蓋您在開發外掛程式時遇到的失敗。若要在每次變更後執行檢查，請參閱[測試和偵錯](/docs/zh-TW/plugins/create#test-and-debug)。

793

794兩個也會影響外掛程式使用者的失敗在[外掛程式已安裝但無法運作](#plugin-installed-but-not-working)下有其項目：

795

796* **未觸發的 hook**：請參閱[未觸發的 hooks](#failed-to-load-hooks-from-and-hooks-that-dont-fire)

797* **未啟動的 MCP 伺服器**：請參閱[未啟動的 MCP 伺服器](#invalid-mcp-server-config-for-and-mcp-servers-that-dont-start)

798

799<h3 id="commands-path-not-found">

800 `commands path not found: <path>`

801</h3>

802

803**Errors** 標籤顯示 `commands path not found: <absolute path>`，並提供指導 `Check that the path in your manifest or marketplace config is correct`。`skills`、`agents` 和 `hooks` 也會出現相同訊息。

804

805Claude Code 從您的 `plugin.json` 或市集項目解析了一個路徑，相對於外掛程式根目錄，但在該處找不到任何內容。訊息中的路徑是它檢查的絕對路徑，因此請將其與磁碟上的內容進行比較。修正路徑或建立目錄，然後執行 `/reload-plugins`。

806

807資訊清單中的路徑相對於外掛程式根目錄，並以 `./` 開頭。解析到外掛程式根目錄外的路徑會改為報告為 `<component> path escapes plugin directory`，並被捨棄。

808

809<h3 id="plugin-dir-loads-a-plugin-with-no-components">

810 `--plugin-dir` 在市集根目錄不會載入 `plugins/` 下的外掛程式

811</h3>

812

813您啟動了 `claude --plugin-dir <path>`，沒有看到錯誤，但外掛程式的 skills、agents 和 hooks 不存在。

814

815`--plugin-dir` 採用外掛程式的根目錄，即包含 `.claude-plugin/plugin.json` 和元件目錄（例如 `skills/`）的目錄。如果您改為指向市集根目錄，Claude Code 不會讀取 `marketplace.json`，因此 `plugins/` 下的外掛程式不會載入，您也看不到錯誤。在 v2.1.281 之前，Claude Code 將市集根目錄載入為一個以該目錄命名的空外掛程式。將旗標指向外掛程式目錄本身：

816

817```shell theme={null}

818claude --plugin-dir ./my-marketplace/plugins/my-plugin

819```

820

821然後在 `/plugin` 中開啟 **Installed**，外掛程式的詳細資訊窗格會列出其元件。

822

823<h3 id="files-the-plugin-references-outside-its-directory-arent-found">

824 外掛程式參考其目錄外的檔案找不到

825</h3>

826

827外掛程式使用 `--plugin-dir` 從其來源目錄運作，但安裝後失敗，出現關於路徑（例如 `../shared-utils`）的錯誤。

828

829Claude Code 將已安裝的外掛程式複製到其快取中，並從該處載入它，因此到達外掛程式自身目錄外的路徑在快取中指向空無。將共用檔案移到外掛程式目錄內，或透過其內的符號連結參考它們。如需快取位置和路徑解析方式，請參閱[在磁碟上尋找外掛程式](/docs/zh-TW/plugins/loading#find-plugins-on-disk)。

830

831<h3 id="claude-plugin-root-shows-forward-slashes-on-windows">

832 `${CLAUDE_PLUGIN_ROOT}` 在 Windows 上顯示正斜線

833</h3>

834

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

836

837Claude Code 在 Windows 上透過 Git Bash 執行 shell 形式的 hooks，並刻意以正斜線 Win32 形式替換外掛程式根目錄。Bash 內建、MSYS 工具和原生 Windows 二進位檔都接受該形式。

838

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

840

841* 執行形式的 hook，它使用 `args` 陣列直接產生程序

842* 具有 `"shell": "powershell"` 的 hook

843

844<h3 id="plugin-loads-but-its-skills-are-missing">

845 外掛程式載入但其 skills 遺失

846</h3>

847

848您的外掛程式列在 **Installed** 下，沒有錯誤，但當您輸入 `/` 時，不會提供其 skills。

849

850Skills 從外掛程式根目錄的 `skills/` 載入，命令從外掛程式根目錄的 `commands/` 載入。只有 `plugin.json` 屬於 `.claude-plugin/` 內，`.claude-plugin/` 內的 `skills/` 目錄不會被掃描。將目錄移到外掛程式根目錄，並執行 `/reload-plugins`。之後，外掛程式的詳細資訊窗格在 `/plugin` 中列出 skills，輸入 `/` 會提供它們。

851

852每個 skill 是包含 `SKILL.md` 的目錄。資訊清單中指向 `SKILL.md` 檔案而不是其目錄的 `skills` 項目會報告為 `path is a file; skills entries must be directories containing SKILL.md`。

853

854<h3 id="skill-loads-but-claude-never-invokes-the-skill">

855 Skill 載入但 Claude 從不叫用該 skill

856</h3>

857

858您外掛程式的 skill 在您輸入其 `/<plugin>:<skill>` 命令時執行，但 Claude 從不在回應純文字請求時叫用它。

859

860按順序檢查這些原因：

861

862* **Skill 設定 `disable-model-invocation: true`**：設定該欄位後，只有您可以叫用該 skill。[建立您的第一個外掛程式](/docs/zh-TW/plugins/create#create-your-first-plugin)中的範本 skill 會設定它。從您想要 Claude 自行叫用的 skill 中移除該行。[控制誰叫用 skill](/docs/zh-TW/skills#control-who-invokes-a-skill) 涵蓋該欄位

863* **描述不符合人們的提問方式**：完成[Skill 未觸發](/docs/zh-TW/skills#skill-not-triggering)中的檢查

864* **描述被截斷**：安裝許多 skills 時，Claude Code 會縮短描述以符合列表的字元預算，這可能會去除 Claude 需要匹配請求的關鍵字。請參閱[Skill 描述被截短](/docs/zh-TW/skills#skill-descriptions-are-cut-short)

865

866若要測量 skill 在現實提示中觸發的頻率，而不是逐一檢查，請使用 [`tool_used: Skill` 評分器](/docs/zh-TW/plugin-evals#create-your-first-eval-suite)撰寫評估案例，並在每次描述變更後使用 `claude plugin eval` 執行它。

867

868<h3 id="is-not-a-plugin-or-skill-folder">

869 `<directory> is not a plugin or skill folder` 來自 `claude plugin eval init`

870</h3>

871

872您從不是外掛程式根目錄的目錄（例如您的主目錄或保留外掛程式在子目錄中的儲存庫根目錄）執行了 `claude plugin eval init`。`init` 在工作目錄下寫入套件，因此它會停止，而不是建立外掛程式永遠看不到的 `evals/` 目錄。

873

874變更到外掛程式的根目錄，即保存 `.claude-plugin/plugin.json` 或 skill 的 `SKILL.md` 的目錄，然後再次執行命令。若要刻意在其他地方搭建套件，請傳遞 `--eval-dir`。請參閱[使用評估測試外掛程式](/docs/zh-TW/plugin-evals)。

875

876<h3 id="the-userconfig-dialog-never-appears">

877 `userConfig` 對話框從不出現

878</h3>

879

880您的外掛程式宣告 `userConfig` 選項，但安裝時不會出現設定對話框。

881

882互動式安裝會顯示對話框，而 shell 命令改為將值作為旗標：

883

884* **在工作階段中的 `/plugin install`，或 `/plugin` 中的 Discover 標籤**：對話框是此互動式安裝的一部分

885* **在您的 shell 中的 `claude plugin install`**：永遠不會提示 `userConfig` 值。它會儲存您傳遞的任何 `--config KEY=VALUE` 值，當選項保持未設定時，它會列印 `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.` 當任何未設定的選項是必需的時，`(M required)` 跟隨 `not yet set`。

886

887如果您從 shell 安裝，請使用 `--config` 傳遞值，每個選項一個旗標：

888

889```shell theme={null}

890claude plugin install my-plugin@my-marketplace --config api_url=https://example.com

891```

892

893當每個選項都設定時，安裝輸出不會包含 `not yet set` 行。若要之後改為開啟對話框，請在工作階段中執行 `/plugin configure my-plugin@my-marketplace`。

894

895如果您傳遞資訊清單未宣告的 `--config` 鍵，外掛程式仍會安裝，命令會列印 `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.` 後面跟著外掛程式確實宣告的鍵。

896

897<h3 id="claude-plugin-validate-reports-errors">

898 `claude plugin validate` 報告錯誤

899</h3>

900

901您執行了 `claude plugin validate <path>`，或在工作階段中執行了 `/plugin validate <path>`，它列印了 `Found N errors` 和 `Validation failed`，然後以代碼 1 結束。

902

903驗證器讀取您提供的路徑處的資訊清單：外掛程式目錄的 `.claude-plugin/plugin.json`，或市集目錄的 `.claude-plugin/marketplace.json`。對於市集，它在項目自身資訊清單中的問題前加上項目索引，如 `plugins[1] plugin.json → json: ...`。

904

905該表涵蓋停止驗證的訊息和兩個警告 `No frontmatter block found` 和 `Unknown field '<key>'`，只有在您傳遞 `--strict` 時才會停止。其他警告，例如遺失描述，未列出。

906

907| 訊息 | 原因 | 修正 |

908| :------------------------------------------------------------------------------------------------------- | :----------------------------------------- | :------------------------------------------------------------- |

909| `File not found: <path>` | 路徑沒有資訊清單，或不存在。 | 針對外掛程式或市集根目錄（包含 `.claude-plugin/` 的目錄）執行命令。 |

910| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | 目錄沒有 `.claude-plugin/` 資訊清單。 | 建立資訊清單，或指向正確的目錄。 |

911| `Invalid JSON syntax: <parse error>` | 資訊清單或 `hooks/hooks.json` 不是有效的 JSON。 | 修正 JSON。在您修正 `hooks/hooks.json` 之前，工作階段會載入外掛程式而不包含該檔案中的 hooks。 |

912| `Path not found: <path>. The runtime loader will report this as a load failure.` | 資訊清單中的元件路徑不存在。 | 修正路徑或建立目錄。 |

913| `Path contains ".." which could be a path traversal attempt: <path>` | 元件路徑逃逸外掛程式目錄。 | 使用外掛程式根目錄內的路徑。 |

914| `Path is a file; skills entries must be directories containing SKILL.md` | `skills` 項目指向 `SKILL.md` 而不是其目錄。 | 指向父目錄，或 `.` 表示根層級 `SKILL.md`。 |

915| `No frontmatter block found` 或 `YAML frontmatter failed to parse: <error>` | Skill、agent 或命令檔案有遺失或無效的 YAML frontmatter。 | 在 `---` 分隔符之間新增或修正 frontmatter。驗證外掛程式目錄時報告。 |

916| `Unknown field '<key>'` | 資訊清單有結構描述未定義的欄位。 | 移除它，或使用訊息建議的名稱。Claude Code 在載入時忽略未知欄位。 |

917

918在每次修正後再次執行命令，直到它不列印任何錯誤。

919

920`plugin.json` 欄位在[資訊清單參考](/docs/zh-TW/plugins/manifest-reference)上，市集層級訊息在[市集驗證錯誤](#marketplace-validation-errors)下。

921

922<h3 id="plugin-has-conflicting-manifests">

923 `Plugin <name> has conflicting manifests`

924</h3>

925

926外掛程式無法載入，出現 `Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components.`

927

928外掛程式有其自身的 `plugin.json`，其市集項目設定 `strict: false` 同時也宣告 `commands`、`agents`、`skills`、`hooks`、`outputStyles` 或 `themes` 中的任何一個。從項目中移除這些欄位，或在項目中設定 `strict: true`，以便 Claude Code 將它們附加到 `plugin.json`。請參閱[嚴格模式](/docs/zh-TW/plugins/marketplace-reference#strict-mode)。

929

930<h3 id="warning-no-commands-found-in-plugin-custom-directory">

931 `Warning: No commands found in plugin <name> custom directory`

932</h3>

933

934當外掛程式載入時，`claude --debug` 日誌在 `~/.claude/debug/<session-id>.txt` 記錄 `Warning: No commands found in plugin <name> custom directory: <path>. Expected .md files or SKILL.md in subdirectories.` 工作階段或 **Errors** 標籤中不會出現任何內容。

935

936資訊清單中的 `commands` 路徑存在，但不包含 `.md` 檔案，也不包含子目錄中的 `SKILL.md`。新增命令檔案，或從資訊清單中移除路徑。

937

938<h2 id="host-a-marketplace">

939 託管市集

940</h2>

941

942您發佈市集，使用者報告錯誤，或您自己的驗證失敗。這些條目適用於市集所有者。

943

944<h3 id="plugins-with-relative-paths-fail-in-url-based-marketplaces">

945 Plugins with relative paths fail in URL-based marketplaces

946</h3>

947

948使用者使用 `https://example.com/marketplace.json` URL 新增了您的市集。其 `source` 是相對路徑（例如 `./plugins/my-plugin`）的外掛程式安裝失敗，並顯示 `its marketplace entry path does not stay inside the marketplace directory`。已安裝的外掛程式無法載入，並顯示 `Plugin source path refused`。兩個訊息都有 [錯誤參考條目](/docs/zh-TW/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory)。

949

950當使用者使用 URL 新增市集時，Claude Code 僅下載 `marketplace.json` 檔案本身。它不會從該伺服器按相對路徑擷取外掛程式檔案，因此相對路徑中的條目指向從未擷取的目錄。為每個條目提供 Claude Code 可以自行擷取的來源，例如 GitHub 儲存庫：

951

952```json theme={null}

953{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

954```

955

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

957

958<h3 id="marketplace-validation-errors">

959 Marketplace validation errors

960</h3>

961

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

963

964`claude plugin validate` 也驗證其 `source` 是本機路徑的每個條目，並在條目的 `version` 與外掛程式自己的清單不同時警告。

965

966下表列出市集級別訊息。條目級別訊息是 [`claude plugin validate` reports errors](#claude-plugin-validate-reports-errors) 下的外掛程式訊息，前綴為 `plugins[N] plugin.json →`。

967

968| 訊息 | 種類 | 修復 |

969| :----------------------------------------------------------------------------------------------------------------------- | :- | :------------------------------------------------------------------------- |

970| `Duplicate plugin name "<name>" found in marketplace` | 錯誤 | 為每個外掛程式提供唯一的 `name`。 |

971| `Path contains "..": <path>` 在 `plugins[N].source` 下 | 錯誤 | 使用相對於市集根目錄的路徑，沒有 `..` 段。 |

972| `Marketplace name cannot contain control or bidirectional-formatting characters` | 錯誤 | 從名稱中移除字元，例如逃逸或換行符。 |

973| `Plugin name cannot contain control or bidirectional-formatting characters` | 錯誤 | 從外掛程式 `name` 中移除字元。 |

974| `Marketplace has no plugins defined` | 警告 | 至少新增一個條目到 `plugins`。 |

975| `No marketplace description provided` | 警告 | 新增頂級 `description`。 |

976| `Plugin name "<name>" is not kebab-case` 在 `plugins[N] plugin.json → name` 下 | 警告 | 重新命名為小寫字母、數字和連字號。Claude Code 接受其他形式，但 claude.ai 市集同步拒絕它們。 |

977| `Entry declares version "<a>" but <path>/plugin.json says "<b>"` | 警告 | 更新條目以符合 `plugin.json`，在安裝時是權威的。 |

978| `Marketplace name "<name>" is reserved in Claude Desktop` | 警告 | 重新命名市集。Claude Desktop 的受管市集同步拒絕任何大小寫的 `org`、`org-provisioned` 和 `unknown`。 |

979| `Marketplace name "<name>" is not accepted by Claude Desktop` 或 `Plugin name "<name>" is not accepted by Claude Desktop` | 警告 | 重新命名為最多 128 個字元的字母、數字、`.`、`_` 和 `-`，以字母或數字開頭。 |

980

981在 v2.1.247 之前，包含控制或雙向格式化字元的市集名稱報告為 `Marketplace name impersonates an official Anthropic/Claude marketplace`。

982

983<h2 id="blocked-by-your-organization">

984 被您的組織阻止

985</h2>

986

987您的組織部署受管設定，限制外掛程式，命令被拒絕，並顯示政策訊息。這些條目命名每個拒絕背後的設定，因此您知道要求管理員什麼。對於管理員端，請參閱 [為您的組織管理外掛程式](/docs/zh-TW/plugins/org)。

988

989<h3 id="marketplace-source-is-blocked-by-enterprise-policy">

990 `Marketplace source '<source>' is blocked by enterprise policy`

991</h3>

992

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

994

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

996

997將訊息的其餘部分與看到的內容相符，以查看什麼類型的政策阻止了來源：

998

999* **`Allowed sources: <list>`**：阻止來自 `strictKnownMarketplaces` 允許清單而不是 `blockedMarketplaces` 阻止清單

1000* **`No external marketplaces are allowed.`**：`strictKnownMarketplaces` 允許清單為空

1001* **提示速記假設 github.com 的 `Tip:`**：允許清單允許 git 主機按主機名稱，您傳遞的 `owner/repo` 速記指向 github.com。如果儲存庫位於您的內部主機上，使用其完整 URL 再次新增它，例如 `git@your-git-host.com:owner/repo.git`

1002

1003您在政策變得更具限制性之前新增的市集停止重新整理，因為政策在每次重新整理時適用。

1004

1005<h3 id="marketplace-is-not-in-the-allowed-marketplace-list">

1006 `Marketplace "<name>" is not in the allowed marketplace list`

1007</h3>

1008

1009**Errors** 標籤顯示此行，或 `Marketplace "<name>" is blocked by enterprise policy`，用於您已註冊的市集。

1010

1011相同的受管設定，阻止 [市集來源](#marketplace-source-is-blocked-by-enterprise-policy)，在載入時適用。`strictKnownMarketplaces` 不包括此市集，或 `blockedMarketplaces` 命名它，因此 Claude Code 停止載入它及其外掛程式。對於允許清單變體，指導行顯示允許的來源，或 `Contact your administrator to configure allowed marketplace sources`。對於阻止清單變體，它讀取 `This marketplace source is explicitly blocked by your administrator`。

1012

1013<h3 id="plugin-is-blocked-by-your-organizations-policy-and-cannot-be-installed">

1014 `Plugin "<name>" is blocked by your organization's policy and cannot be installed`

1015</h3>

1016

1017安裝被拒絕，並顯示此行，啟用時顯示相同的行，以 `cannot be enabled` 結尾，或安裝或更新時顯示命名原因的行：`Plugin "<name>" is from marketplace "<marketplace>", which is blocked by your organization's policy`，或 `Plugin "<name>" depends on "<dep>", which is blocked by your organization's policy`。

1018

1019受管設定阻止此外掛程式、其市集或它需要的依賴項。詢問您的管理員哪個條目適用。被阻止的依賴項表示外掛程式在依賴項的市集被允許前無法安裝。

1020

1021<h3 id="plugin-dir-is-disabled-by-your-organizations-managed-settings-disables">

1022 `--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)`

1023</h3>

1024

1025您使用 `--plugin-dir`、`--plugin-url`、`--agents` 或 `--mcp-config` 啟動了 `claude`。Claude Code 以此訊息退出，並顯示 `Plugins, custom agents, and MCP servers can only be loaded from sources your administrator has approved.`

1026

1027您的管理員在受管設定中設定了 `disableSideloadFlags`，這會關閉從任意路徑載入外掛程式、代理和伺服器的旗標。改為從核准的市集載入外掛程式，或要求您的管理員移除設定。

1028

1029`/plugin` **Errors** 標籤中的相關訊息是 `--plugin-dir copy of "<name>" ignored: plugin is locked by managed settings`。受管設定按名稱啟用或停用該外掛程式，Claude Code 忽略您的 `--plugin-dir` 副本，因此旗標無法覆蓋政策。

1030

1031<h3 id="plugins-from-claude-skills-are-blocked-by-your-organizations-managed-s">

1032 `Plugins from ~/.claude/skills/ are blocked by your organization's managed settings`

1033</h3>

1034

1035您執行了 `claude plugin init` 或 `claude plugin enable`，它停止並顯示此行。訊息命名 `strictKnownMarketplaces or blockedMarketplaces`，並要求您的管理員將 `{"source":"skills-dir"}` 新增到 `strictKnownMarketplaces` 或從 `blockedMarketplaces` 中移除它。

1036

1037`skills-dir` 來源代表 Claude Code 從您的 `~/.claude/skills/` 目錄載入的外掛程式。要求您的管理員進行訊息命名的變更。

1038

1039<h3 id="command-sourced-plugins-are-disabled-by-your-organizations-managed-set">

1040 `Command-sourced plugins are disabled by your organization's managed settings`

1041</h3>

1042

1043您安裝或更新了具有 `command` 來源的外掛程式，它停止並顯示此行和 `The plugin was not installed or updated and its command was not run.`

1044

1045您的管理員設定了 `disableCommandPluginSources`，因此 Claude Code 拒絕執行市集宣告的產生外掛程式的命令。單獨設定 `allowManagedHooksOnly` 在 `disableCommandPluginSources` 未設定時具有相同的效果。詢問您的管理員外掛程式是否可以從政策允許的來源類型發佈。

1046

1047<h3 id="marketplace-is-seed-managed">

1048 `Marketplace '<name>' is seed-managed`

1049</h3>

1050

1051您執行了 `claude plugin marketplace update <name>`，它失敗，並顯示 `Marketplace '<name>' is seed-managed (<dir>)` 和要求您詢問管理員的提示。

1052

1053操作員透過 `CLAUDE_CODE_PLUGIN_SEED_DIR` 預先填充此市集，Claude Code 將種子管理的市集視為唯讀。批量 `marketplace update` 跳過它並更新其他的。

1054

1055若要變更市集的內容，請詢問維護種子映像的人員更新它。有關程序，請參閱 [種子容器和 CI](/docs/zh-TW/plugins/org#seed-containers-and-ci)。

1056

1057<h2 id="next-steps">

1058 後續步驟

1059</h2>

1060

1061* [外掛程式載入參考](/docs/zh-TW/plugins/loading)：為什麼範圍、快取和優先順序的行為方式如此

1062* [外掛程式命令參考](/docs/zh-TW/plugins/cli-reference)：`claude plugin` 命令的旗標、預設值、輸出和退出代碼

1063* [安裝和管理外掛程式](/docs/zh-TW/plugins/install)：從開始的安裝步驟

1064* [為您的組織管理外掛程式](/docs/zh-TW/plugins/org#troubleshoot-policy)：管理員的政策端故障排除

prompt-caching.md +8 −8

Details

135 啟用或停用外掛程式135 啟用或停用外掛程式

136</h3>136</h3>

137 137

138當您啟用或停用[外掛程式](/docs/zh-TW/plugins)時，變更的成本取決於外掛程式提供的元件類型。下面的案例涵蓋每個元件類型、Claude Code 何時套用變更，以及在同一工作階段中再次停用外掛程式時會發生什麼。138當您啟用或停用[外掛程式](/docs/zh-TW/plugins/overview)時，變更的成本取決於外掛程式提供的元件類型。下面的案例涵蓋每個元件類型、Claude Code 何時套用變更，以及在同一工作階段中再次停用外掛程式時會發生什麼。

139 139

140<h4 id="plugin-components-that-keep-the-cache">140<h4 id="plugin-components-that-keep-the-cache">

141 保留快取的外掛程式元件141 保留快取的外掛程式元件

147 提供 MCP 伺服器的外掛程式147 提供 MCP 伺服器的外掛程式

148</h4>148</h4>

149 149

150當您啟用或停用提供 [MCP 伺服器](/docs/zh-TW/plugins-reference#mcp-servers) 的外掛程式時，Claude Code 會遵循與[連接或斷開 MCP 伺服器](#connecting-or-disconnecting-an-mcp-server)相同的規則：150當您啟用或停用提供 [MCP 伺服器](/docs/zh-TW/plugins/components#mcp-servers) 的外掛程式時，Claude Code 會遵循與[連接或斷開 MCP 伺服器](#connecting-or-disconnecting-an-mcp-server)相同的規則：

151 151

152* 如果 Claude Code 延遲伺服器的工具，它會保留快取。152* 如果 Claude Code 延遲伺服器的工具，它會保留快取。

153* 如果 Claude Code 將它們載入到前綴中，下一個請求會重新讀取整個對話。153* 如果 Claude Code 將它們載入到前綴中，下一個請求會重新讀取整個對話。

156 程式碼智慧外掛程式156 程式碼智慧外掛程式

157</h4>157</h4>

158 158

159當您啟用[程式碼智慧外掛程式](/docs/zh-TW/discover-plugins#code-intelligence)時，Claude 會取得 [LSP 工具](/docs/zh-TW/tools-reference#lsp-tool-behavior)。159當您啟用[程式碼智慧外掛程式](/docs/zh-TW/plugins/code-intelligence)時，Claude 會取得 [LSP 工具](/docs/zh-TW/tools-reference#lsp-tool-behavior)。

160 160

161<h4 id="when-plugin-changes-apply">161<h4 id="when-plugin-changes-apply">

162 外掛程式變更何時套用162 外掛程式變更何時套用

163</h4>163</h4>

164 164

165您在 `/plugin` 功能表中所做的變更會通過 [`/reload-plugins`](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 進行，Claude Code 會在您關閉功能表時為您執行。您會支付成本，無論是附加的公告還是完整重新讀取，都是在變更套用後的第一個回合。Claude Code 也可以自行套用變更：165您在 `/plugin` 功能表中所做的變更會通過 [`/reload-plugins`](/docs/zh-TW/plugins/cli-reference#reload-plugins) 進行，Claude Code 會在您關閉功能表時為您執行。您會支付成本，無論是附加的公告還是完整重新讀取，都是在變更套用後的第一個回合。Claude Code 也可以自行套用變更：

166 166

167* 對於具有 `command` 來源的外掛程式，Claude Code [可以自行重新載入外掛程式](/docs/zh-TW/plugin-marketplaces#when-claude-code-re-runs-the-command)。167* 對於具有 `command` 來源的外掛程式，Claude Code [可以自行重新載入外掛程式](/docs/zh-TW/plugins/loading#when-a-command-source-re-runs)。

168* 當您[從 `/plugin` 介面安裝外掛程式](/docs/zh-TW/discover-plugins#install-plugins)時，Claude Code 可以在安裝期間啟動它。安裝摘要會告訴您它是否執行了此操作。168* 當您[從 `/plugin` 介面安裝外掛程式](/docs/zh-TW/plugins/install#install-a-plugin)時，Claude Code 可以在安裝期間啟動它。安裝摘要會告訴您它是否執行了此操作。

169* 當您在 v2.1.246 或更新版本上使用 `/cd` [移動工作階段](/docs/zh-TW/permissions#move-the-session-to-another-directory)時，Claude Code 會在移動過程中套用新目錄的設定啟用的外掛程式，而不會出現保留 `/reload-plugins` 的完整重新讀取警告。169* 當您在 v2.1.246 或更新版本上使用 `/cd` [移動工作階段](/docs/zh-TW/permissions#move-the-session-to-another-directory)時，Claude Code 會在移動過程中套用新目錄的設定啟用的外掛程式，而不會出現保留 `/reload-plugins` 的完整重新讀取警告。

170* 在互動式工作階段中，當您在使用 `--plugin-dir` 傳遞的[外掛程式資料夾](/docs/zh-TW/plugins#test-your-plugins-locally)中新增或移除外掛程式時，變更會立即套用。如果套用它會觸發完整重新讀取，Claude Code 會改為保留變更並顯示通知以執行 `/reload-plugins`。需要 Claude Code v2.1.265 或更新版本。170* 在互動式工作階段中，當您在使用 `--plugin-dir` 傳遞的[外掛程式資料夾](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session)中新增或移除外掛程式時，變更會立即套用。如果套用它會觸發完整重新讀取，Claude Code 會改為保留變更並顯示通知以執行 `/reload-plugins`。需要 Claude Code v2.1.265 或更新版本。

171 171

172當 `/reload-plugins` 執行且重新載入會觸發完整重新讀取時，Claude Code 會顯示警告且不套用重新載入。執行 `/reload-plugins --force` 以無論如何套用它。172當 `/reload-plugins` 執行且重新載入會觸發完整重新讀取時，Claude Code 會顯示警告且不套用重新載入。執行 `/reload-plugins --force` 以無論如何套用它。

173 173

174`/reload-plugins` 也在沒有互動式終端的工作階段中執行，例如桌面應用程式、Agent SDK 和[非互動式模式](/docs/zh-TW/headless)搭配 `-p`，當您直接將其輸入工作階段時。需要 Claude Code v2.1.260 或更新版本。174`/reload-plugins` 也在沒有互動式終端的工作階段中執行，例如桌面應用程式、Agent SDK 和[非互動式模式](/docs/zh-TW/headless)搭配 `-p`，當您直接將其輸入工作階段時。需要 Claude Code v2.1.260 或更新版本。

175 175

176在這些工作階段中，重新載入會套用除了外掛程式 MCP 伺服器變更之外的所有內容，這些變更[在您的下一個工作階段中生效](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)，因此永遠不會在工作階段中途造成完整重新讀取的成本。176在這些工作階段中，重新載入會套用除了外掛程式 MCP 伺服器變更之外的所有內容，這些變更[在您的下一個工作階段中生效](/docs/zh-TW/plugins/cli-reference#reload-plugins)，因此永遠不會在工作階段中途造成完整重新讀取的成本。

177 177

178<h4 id="plugins-you-enable-and-then-disable-in-one-session">178<h4 id="plugins-you-enable-and-then-disable-in-one-session">

179 您在一個工作階段中啟用然後停用的外掛程式179 您在一個工作階段中啟用然後停用的外掛程式

prompt-library.md +4 −3

Details

626 return base + (href.startsWith('/en/') ? '/' + locale + href.slice(3) : href);626 return base + (href.startsWith('/en/') ? '/' + locale + href.slice(3) : href);

627 };627 };

628 }, []);628 }, []);

629 const SAFE_HREF = /^(\/(?![\/\\\s])|#|https?:\/\/)/;

629 const linkify = s => {630 const linkify = s => {

630 const out = [];631 const out = [];

631 let last = 0;632 let last = 0;

632 const re = /\[([^\]]+)\]$([^)]+)$/g;633 const re = /\[([^\]]+)\]$([^)]+)$/g;

633 for (let m; m = re.exec(s); ) {634 for (let m; m = re.exec(s); ) {

634 if (m.index > last) out.push(s.slice(last, m.index));635 if (m.index > last) out.push(s.slice(last, m.index));

635 out.push(<a key={m.index} href={doc(m[2])}>{m[1]}</a>);636 out.push(SAFE_HREF.test(m[2]) ? <a key={m.index} href={doc(m[2])}>{m[1]}</a> : m[1]);

636 last = re.lastIndex;637 last = re.lastIndex;

637 }638 }

638 if (last < s.length) out.push(s.slice(last));639 if (last < s.length) out.push(s.slice(last));

776 </div>777 </div>

777 <div className="pl-label">{L.whyWorks}</div>778 <div className="pl-label">{L.whyWorks}</div>

778 <div className="pl-teaches">{linkify(p.teaches)}</div>779 <div className="pl-teaches">{linkify(p.teaches)}</div>

779 {p.nextHref && p.next && <div className="pl-next">780 {p.nextHref && p.next && SAFE_HREF.test(p.nextHref) && <div className="pl-next">

780 <span className="pl-next-label">{L.makeItStick}</span>781 <span className="pl-next-label">{L.makeItStick}</span>

781 <a href={doc(p.nextHref)}>{codeify(p.next)} →</a>782 <a href={doc(p.nextHref)}>{codeify(p.next)} →</a>

782 </div>}783 </div>}

1202 },1203 },

1203 "migrate-a-pattern-across": {1204 "migrate-a-pattern-across": {

1204 title: "在程式碼庫中遷移模式",1205 title: "在程式碼庫中遷移模式",

1205 teaches: "描述舊模式和新模式。要求 Claude 首先識別每個位置意味著呼叫網站在回應中列出，以便您可以檢查是否未遺漏任何內容。對於跨許多檔案的遷移，執行 [/batch](/docs/zh-TW/commands)。Claude 將工作分成單位供您批准，然後背景子代理進行變更並為每個單位打開一個拉取請求。"1206 teaches: "描述舊模式和新模式。要求 Claude 首先識別每個位置意味著呼叫網站在回應中列出，以便您可以檢查是否未遺漏任何內容。對於跨許多檔案的遷移，執行 [/batch](/docs/zh-TW/commands)。Claude 將工作分成單位供您批准，然後背景子代理進行變更。"

1206 },1207 },

1207 "optimize-against-a-measurable": {1208 "optimize-against-a-measurable": {

1208 title: "針對可測量目標進行最佳化",1209 title: "針對可測量目標進行最佳化",

remote-control.md +6 −6

Details

252<Note>252<Note>

253 受信任的裝置目前處於測試版。功能和功能可能會隨著體驗的改進而演變。253 受信任的裝置目前處於測試版。功能和功能可能會隨著體驗的改進而演變。

254 254

255 受信任的裝置在 Team 和 Enterprise 方案上可用。預設為關閉，直到擁有者啟用它。255 受信任的裝置在 Pro、Max、Team 和 Enterprise 方案上可用，預設為關閉。在 Team 和 Enterprise 方案上，擁有者會為組織啟用它。在 Pro 和 Max 方案上，您可以在設定中的 Cowork 或帳戶頁面上自行啟用**需要受信任的裝置**。

256</Note>256</Note>

257 257

258受信任的裝置是一個組織範圍的設定，要求成員在從 claude.ai、Claude 行動應用程式或 Claude Desktop 檢視或控制 Remote Control 會話之前驗證其裝置。它將 Remote Control 存取與已知裝置和最近的驗證相關聯，而不僅僅是已登入的帳戶。258受信任的裝置要求您的組織的每個成員，或在 Pro 或 Max 方案上只有您，在從 claude.ai、Claude 行動應用程式或 Claude Desktop 檢視或控制 Remote Control 會話之前驗證其裝置。它將 Remote Control 存取與已知裝置和最近的驗證相關聯，而不僅僅是已登入的帳戶。

259 259

260當設定開啟時，與 Remote Control 會話互動需要以下兩項：260當設定開啟時，與 Remote Control 會話互動需要以下兩項：

261 261

267該設定僅適用於 Remote Control。一般 Claude 聊天、終端機中的 Claude Code 和 API 使用不受影響。267該設定僅適用於 Remote Control。一般 Claude 聊天、終端機中的 Claude Code 和 API 使用不受影響。

268 268

269<h3 id="enable-trusted-devices-for-your-organization">269<h3 id="enable-trusted-devices-for-your-organization">

270 為您的組織啟用受信任的裝置270 為 Team 或 Enterprise 組織啟用受信任的裝置

271</h3>271</h3>

272 272

273擁有者從 Claude Code 管理員主控台啟用該設定。273擁有者從 claude.ai 組織設定啟用該設定。

274 274

275<Steps>275<Steps>

276 <Step title="開啟 Claude Code 管理員設定">276 <Step title="前往 Capabilities 頁面">

277 前往 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)。**需要受信任的裝置**切換會出現在 Remote Control 設定下方。277 前往 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities)。**需要受信任的裝置**切換會出現在該部分中。

278 </Step>278 </Step>

279 279

280 <Step title="開啟需要受信任的裝置">280 <Step title="開啟需要受信任的裝置">

sandboxing.md +2 −2

Details

147* 裸 `Bash` 詢問規則或等效的 `Bash(*)` 形式會被跳過以執行 sandboxed 的命令；它仍然適用於回退到一般權限流程的命令。在[計畫模式](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)中，規則不會被跳過：它會提示 sandboxed 命令，包括唯讀命令。在 v2.1.212 之前，跳過也適用於計畫模式147* 裸 `Bash` 詢問規則或等效的 `Bash(*)` 形式會被跳過以執行 sandboxed 的命令；它仍然適用於回退到一般權限流程的命令。在[計畫模式](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)中，規則不會被跳過：它會提示 sandboxed 命令，包括唯讀命令。在 v2.1.212 之前，跳過也適用於計畫模式

148 148

149<Info>149<Info>

150 自動允許模式獨立於您的權限模式設定運作，除了[計畫模式](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)和自動模式中的命令帶有[每個命令允許的網域](#per-command-allowed-domains-in-auto-mode)。即使您不在「接受編輯」模式中，當啟用自動允許時，sandboxed Bash 命令也會自動執行。這表示在 sandbox 邊界內修改檔案的 Bash 命令會執行而不提示，即使在手動模式中，檔案編輯工具也會提示。150 自動允許模式獨立於您的權限模式設定運作，除了[計畫模式](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)、自動模式中帶有[每個命令允許的網域](#per-command-allowed-domains-in-auto-mode)的命令，以及[伺服器端分類器檢閱](/docs/zh-TW/permission-modes#how-the-classifier-evaluates-actions)自動模式中的 sandboxed 命令。即使您不在「接受編輯」模式中，當啟用自動允許時，sandboxed Bash 命令也會自動執行。這表示在 sandbox 邊界內修改檔案的 Bash 命令會執行而不提示，即使在手動模式中，檔案編輯工具也會提示。

151 151

152 在計畫模式中，自動允許不會擴大核准；請參閱[計畫模式](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)，了解 Claude Code 如何在您計畫時限制命令。在 v2.1.212 之前，自動允許在計畫模式中也執行 sandboxed 命令而不提示。152 在計畫模式中，自動允許不會擴大核准；請參閱[計畫模式](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)，了解 Claude Code 如何在您計畫時限制命令。在 v2.1.212 之前，自動允許在計畫模式中也執行 sandboxed 命令而不提示。

153</Info>153</Info>

318 保護認證318 保護認證

319</h3>319</h3>

320 320

321`sandbox.credentials` 設定宣告要保護、不讓沙箱化命令存取的認證檔案和環境變數。每個項目命名一個檔案路徑或環境變數和一個 `mode`。專用的 `credentials` 區塊將認證規則分組在一起，並與一般檔案系統規則分開。需要 Claude Code v2.1.187 或更新版本。321`sandbox.credentials` 設定宣告要保護、不讓沙箱化命令存取的認證檔案和環境變數。每個項目命名一個檔案路徑或環境變數和一個 `mode`。專用的 `credentials` 區塊將認證規則分組在一起，並與一般檔案系統規則分開。

322 322

323對於 `"mode": "deny"` 的項目，檔案路徑在沙箱內被拒絕讀取，與 `filesystem.denyRead` 應用的限制相同，環境變數在每個沙箱化命令執行前被取消設定。檔案保護是檔案系統層的一部分，因此如果您[停用檔案系統隔離](#disable-filesystem-isolation)，它不適用；環境變數保護仍然適用。323對於 `"mode": "deny"` 的項目，檔案路徑在沙箱內被拒絕讀取，與 `filesystem.denyRead` 應用的限制相同，環境變數在每個沙箱化命令執行前被取消設定。檔案保護是檔案系統層的一部分，因此如果您[停用檔案系統隔離](#disable-filesystem-isolation)，它不適用；環境變數保護仍然適用。

324 324

security-guidance.md +5 −5

Details

25 安裝外掛程式25 安裝外掛程式

26</h2>26</h2>

27 27

~~28在終端機 Claude Code 工作階段中，從 [官方 Anthropic 市場](/docs/zh-TW/discover-plugins#official-anthropic-marketplace) 安裝：~~28在終端機 Claude Code 工作階段中，從 [官方 Anthropic 市場](/docs/zh-TW/plugins/anthropic-marketplaces) 安裝：

29 29

30```text theme={null}30```text theme={null}

31/plugin install security-guidance@claude-plugins-official31/plugin install security-guidance@claude-plugins-official

35 35

36* **Claude 桌面應用程式、本地或 SSH 工作階段**：點擊提示旁的 **+** 按鈕開啟 [外掛程式瀏覽器](/docs/zh-TW/desktop#install-plugins)，然後點擊 **Plugins**，再點擊 **Add plugin**36* **Claude 桌面應用程式、本地或 SSH 工作階段**：點擊提示旁的 **+** 按鈕開啟 [外掛程式瀏覽器](/docs/zh-TW/desktop#install-plugins)，然後點擊 **Plugins**，再點擊 **Add plugin**

37* **VS Code 擴充功能**：從 [**Manage plugins** 對話框](/docs/zh-TW/vs-code#manage-plugins) 安裝37* **VS Code 擴充功能**：從 [**Manage plugins** 對話框](/docs/zh-TW/vs-code#manage-plugins) 安裝

38* **雲端工作階段**：為您的 claude.ai 帳戶啟用外掛程式，以便 Claude Code 將其載入為 [同步外掛程式](/docs/zh-TW/plugins-reference#synced-plugins)。雲端工作階段不會從您的使用者設定或儲存庫的 `.claude/settings.json` 載入外掛程式，如 [您的設定中有哪些內容會保留](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 所說明38* **雲端工作階段**：雲端工作階段不會從您的使用者設定或儲存庫的 `.claude/settings.json` 載入外掛程式，如 [您的設定中有哪些內容會保留](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 所說明。如需您的組織透過受管設定發佈的外掛程式，請參閱 [為您的組織管理外掛程式](/docs/zh-TW/plugins/org)

39 39

40終端機安裝會提示輸入範圍。選擇使用者範圍以將外掛程式寫入您的使用者設定，這樣它會在您在此機器上啟動的每個新本地工作階段中載入。40終端機安裝會提示輸入範圍。選擇使用者範圍以將外掛程式寫入您的使用者設定，這樣它會在您在此機器上啟動的每個新本地工作階段中載入。

41 41

42如果安裝失敗，請比對 Claude Code 報告的訊息：42如果安裝失敗，請比對 Claude Code 報告的訊息：

43 43

44* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。44* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。

~~45* [外掛程式在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。~~45* 外掛程式 [在市場中找不到](/docs/zh-TW/plugins/install#install-a-plugin)：檢查外掛程式名稱。

46 46

47檢查安裝摘要。如果它報告 `Run /reload-plugins to activate.`，請參閱 [在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 以在您目前的工作階段中啟用外掛程式。47檢查安裝摘要。如果它報告 `Run /reload-plugins to activate.`，請參閱 [在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/plugins/cli-reference#reload-plugins) 以在您目前的工作階段中啟用外掛程式。

48 48

49<h3 id="enable-for-your-team-in-local-sessions">49<h3 id="enable-for-your-team-in-local-sessions">

50 在本地工作階段中為您的團隊啟用50 在本地工作階段中為您的團隊啟用

279 279

280* [Code Review](/docs/zh-TW/code-review)：設定 PR 時間多代理審查280* [Code Review](/docs/zh-TW/code-review)：設定 PR 時間多代理審查

281* [使用 hooks 自動化工作流](/docs/zh-TW/hooks-guide)：在相同的生命週期點構建您自己的檢查281* [使用 hooks 自動化工作流](/docs/zh-TW/hooks-guide)：在相同的生命週期點構建您自己的檢查

282* [發現和安裝外掛程式](/docs/zh-TW/discover-plugins#official-anthropic-marketplace)：瀏覽其他官方外掛程式282* [在官方 marketplace 中尋找 plugins](/docs/zh-TW/plugins/anthropic-marketplaces#find-plugins-in-the-official-marketplace)：瀏覽其他官方 plugins 的位置

server-managed-settings.md +2 −2

Details

247}247}

248```248```

249 249

250您也可以在[端點管理的](/docs/zh-TW/managed-settings#delivery-mechanisms) MDM 設定檔或系統 `managed-settings.json` 檔案中設定此金鑰，以在首次啟動時強制執行失敗關閉行為，在任何伺服器承載被傳遞之前。在 Claude Code v2.1.191 或更新版本中，此旗標是上述[優先順序規則](#settings-precedence)的例外：當任何管理員控制的受管來源設定它時，Claude Code 會遵守它，即使快取的伺服器管理承載也存在，因此當伺服器管理的設定存在時，MDM 傳遞的值不會被忽略。250您也可以在[端點管理的](/docs/zh-TW/managed-settings#delivery-mechanisms) MDM 設定檔或系統 `managed-settings.json` 檔案中設定此金鑰，以在首次啟動時強制執行失敗關閉行為，在任何伺服器承載被傳遞之前。此旗標是上述[優先順序規則](#settings-precedence)的例外：當任何管理員控制的受管來源設定它時，Claude Code 會遵守它，即使快取的伺服器管理承載也存在，因此當伺服器管理的設定存在時，MDM 傳遞的值不會被忽略。

251 251

252當 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 提供受管設定時，其輸出會取代 Claude Code 在啟動後讀取的金鑰的所有其他受管來源。對於 Claude Code 讀取此金鑰的來源，請參閱[其設定項目](/docs/zh-TW/settings-reference#forceremotesettingsrefresh)。`policyHelper` 項目說明 Claude Code 讀取協助程式的來源以及它何時執行。252當 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 提供受管設定時，其輸出會取代 Claude Code 在啟動後讀取的金鑰的所有其他受管來源。對於 Claude Code 讀取此金鑰的來源，請參閱[其設定項目](/docs/zh-TW/settings-reference#forceremotesettingsrefresh)。`policyHelper` 項目說明 Claude Code 讀取協助程式的來源以及它何時執行。

253 253

336 336

337由 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 指令碼傳回的金鑰和[工作負載身分識別聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)認證都不會觸發設定擷取。337由 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 指令碼傳回的金鑰和[工作負載身分識別聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)認證都不會觸發設定擷取。

338 338

339在 Claude Desktop 應用程式中的 [Cowork](https://claude.com/docs/cowork/overview) 工作階段中，Claude Code 不會從 claude.ai 管理員主控台擷取伺服器管理的設定，即使使用者使用 Team 或 Enterprise 帳戶登入也是如此。[原則適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)涵蓋了哪些原則會到達使用者機器上的 Cowork 工作階段和遠端 Cowork 工作階段。claude.ai 在 Cowork 使用者從 git 儲存庫或從 Cowork 標籤中的**自訂**新增市集時，仍會套用您的 [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) 和 [`blockedMarketplaces`](/docs/zh-TW/settings-reference#blockedmarketplaces) 清單。[限制如何運作](/docs/zh-TW/plugin-marketplaces#how-restrictions-work)說明了該檢查。339在 Claude Desktop 應用程式中的 [Cowork](https://claude.com/docs/cowork/overview) 工作階段中，Claude Code 不會從 claude.ai 管理員主控台擷取伺服器管理的設定，即使使用者使用 Team 或 Enterprise 帳戶登入也是如此。[原則適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)涵蓋了哪些原則會到達使用者機器上的 Cowork 工作階段和遠端 Cowork 工作階段。claude.ai 在 Cowork 使用者從 git 儲存庫或從 Cowork 標籤中的**自訂**新增市集時，仍會套用您的 [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) 和 [`blockedMarketplaces`](/docs/zh-TW/settings-reference#blockedmarketplaces) 清單。[限制如何運作](/docs/zh-TW/plugins/org#restrict-what-users-can-install)說明了該檢查。

340 340

341如果您在殼層中匯出 `CLAUDE_CODE_USE_*` 提供者變數或非預設的 `ANTHROPIC_BASE_URL`，Claude Code 會略過您工作階段的設定擷取。[`claude doctor` 和 `/status` 報告略過的擷取及其原因](#verify-settings-delivery)。341如果您在殼層中匯出 `CLAUDE_CODE_USE_*` 提供者變數或非預設的 `ANTHROPIC_BASE_URL`，Claude Code 會略過您工作階段的設定擷取。[`claude doctor` 和 `/status` 報告略過的擷取及其原因](#verify-settings-delivery)。

342 342

sessions.md +1 −1

Details

37 37

38恢復的 session 會復原對話以及儲存在其中的狀態：38恢復的 session 會復原對話以及儲存在其中的狀態：

39 39

40* 對話歷史記錄：完整歷史記錄，包括工具呼叫和結果。當前一個程序結束時仍在執行的工具（例如在當機中），在您恢復時不會完成或再次執行；Claude 會在沒有其輸出的情況下繼續。40* 對話歷史記錄：完整歷史記錄，包括工具呼叫和結果。當前一個程序結束時仍在執行的工具（例如在當機中），在您恢復時不會完成或再次執行；Claude 會看到呼叫標記為在其結果被記錄之前被切斷，並被告知在再次執行之前檢查它是否生效，除非設定了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-TW/env-vars#variables)。在 v2.1.281 之前，Claude Code 會從對話中刪除被切斷的呼叫，或將其顯示為您中斷的呼叫。

41* 模型：session 會在其使用的模型上繼續。當模型已被淘汰或不被 `availableModels` 允許時，模型不會被復原；當 `--model` 旗標或 `ANTHROPIC_MODEL` 系列環境變數在啟動時選擇一個時；或在使用提供者特定部署 ID 的提供者上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/third-party-integrations)；請參閱[模型設定](/docs/zh-TW/model-config#setting-your-model)以了解解析順序。41* 模型：session 會在其使用的模型上繼續。當模型已被淘汰或不被 `availableModels` 允許時，模型不會被復原；當 `--model` 旗標或 `ANTHROPIC_MODEL` 系列環境變數在啟動時選擇一個時；或在使用提供者特定部署 ID 的提供者上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/third-party-integrations)；請參閱[模型設定](/docs/zh-TW/model-config#setting-your-model)以了解解析順序。

42* Agent：使用 [`--agent`](/docs/zh-TW/sub-agents#invoke-subagents-explicitly) 或 `agent` 設定啟動的 session 會繼續作為該 agent，保持其工具限制和模型。在恢復時傳遞 `--agent` 以選擇不同的；對於任一情況下的系統提示，請參閱[恢復對話中的系統提示旗標](/docs/zh-TW/cli-reference#system-prompt-flags-in-resumed-conversations)。Claude Code 在兩個地方查找 agent：session 的原始目錄（前提是您已[信任該工作區](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)），然後是您恢復的目錄，因此專案範圍的 agent 在您從另一個目錄恢復時仍會載入。如果 Claude Code 在任一地方都找不到 agent，session 會以預設工具恢復，並顯示[警告，命名該 agent](/docs/zh-TW/errors#session-agent-no-longer-available)。42* Agent：使用 [`--agent`](/docs/zh-TW/sub-agents#invoke-subagents-explicitly) 或 `agent` 設定啟動的 session 會繼續作為該 agent，保持其工具限制和模型。在恢復時傳遞 `--agent` 以選擇不同的；對於任一情況下的系統提示，請參閱[恢復對話中的系統提示旗標](/docs/zh-TW/cli-reference#system-prompt-flags-in-resumed-conversations)。Claude Code 在兩個地方查找 agent：session 的原始目錄（前提是您已[信任該工作區](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)），然後是您恢復的目錄，因此專案範圍的 agent 在您從另一個目錄恢復時仍會載入。如果 Claude Code 在任一地方都找不到 agent，session 會以預設工具恢復，並顯示[警告，命名該 agent](/docs/zh-TW/errors#session-agent-no-longer-available)。

43* 權限模式：如果您從終端機使用 `claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合一個 session 時）恢復，不帶 `-p`，Claude Code 會復原 session 所在的權限模式，除了[恢復時的權限模式](#permission-mode-on-resume)中的情況，其中也涵蓋 session 選擇器、`/resume` 和使用 `claude -p` 恢復。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆蓋復原的模式。43* 權限模式：如果您從終端機使用 `claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合一個 session 時）恢復，不帶 `-p`，Claude Code 會復原 session 所在的權限模式，除了[恢復時的權限模式](#permission-mode-on-resume)中的情況，其中也涵蓋 session 選擇器、`/resume` 和使用 `claude -p` 恢復。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆蓋復原的模式。

settings.md +55 −51

Details

452 與您的團隊共享設定452 與您的團隊共享設定

453</h3>453</h3>

454 454

455提交 `.claude/settings.json` 以便複製儲存庫的每個人都取得相同的權限、hooks、遙測和 plugins。每個隊友仍然可以在自己的 `.claude/settings.local.json` 中為自己覆寫它，因此個人例外不需要提交。如需完整的團隊檔案，請參閱[團隊的共享設定](/docs/zh-TW/settings-example#a-teams-shared-settings)。455提交 `.claude/settings.json` 以便複製儲存庫的每個人都取得相同的權限、hooks 和 plugins。每個隊友仍然可以在自己的 `.claude/settings.local.json` 中為自己覆寫它，因此個人例外不需要提交。如需完整的團隊檔案，請參閱[團隊的共享設定](/docs/zh-TW/settings-example#a-teams-shared-settings)。

456 456

457您提交的某些內容會等到每個隊友[信任資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)，而少數金鑰永遠不會從儲存庫檔案生效；[對不適用的設定進行疑難排解](#common-cases)涵蓋兩者。457您提交的某些內容會等到每個隊友[信任資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)，而少數金鑰永遠不會從儲存庫檔案生效；[對不適用的設定進行疑難排解](#common-cases)涵蓋兩者。

458 458

653 設定優先順序653 設定優先順序

654</h2>654</h2>

655 655

656當相同金鑰出現在多個位置時，Claude Code 使用設定它的最高層級的值。下面的堆疊顯示層級，最高在頂部；較高層級的金鑰覆蓋它在下面任何地方的相同金鑰。656當相同的鍵出現在多個位置時，Claude Code 會使用最高層級設定的值。下面的堆疊顯示各個層級，最高的在頂部；較高層級的鍵會覆蓋下面任何地方的相同鍵。

657 657

658<SettingsPrecedence />658<SettingsPrecedence />

659 659

660按順序，最高優先順序優先：660按順序，優先順序最高的優先：

661 661

6621. **受管設定**：您的組織部署的設定，通過 `managed-settings.json` 檔案、MDM 政策或來自 claude.ai 主控台的[伺服器管理設定](/docs/zh-TW/server-managed-settings)。沒有什麼您設定會覆蓋它們：您用 `--settings` 傳遞的金鑰不覆蓋相同的受管金鑰，而 `--model` 之類的旗標只從您的組織允許的模型中選擇。受管 `model` 設定每個工作階段啟動時的模型，您仍然可以用 `/model` 切換；鎖定是 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels)，它限制 `/model`、`--model` 和您自己檔案中的 `model` 金鑰。當您的組織傳遞多個受管來源時，[受管層級內的優先順序](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)的規則說明 Claude Code 從每個讀取什麼。6621. **受管設定**：您的組織部署的設定，透過 `managed-settings.json` 檔案、MDM 原則或來自 claude.ai 主控台的[伺服器管理設定](/docs/zh-TW/server-managed-settings)。您設定的任何內容都不會覆蓋它們：您使用 `--settings` 傳遞的鍵不會覆蓋相同的受管鍵，而 `--model` 之類的旗標只會從您的組織允許的模型中選擇。受管 `model` 設定每個工作階段開始時的模型，您仍然可以使用 `/model` 切換；鎖定是 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels)，它限制 `/model`、`--model` 和您自己檔案中的 `model` 鍵。當您的組織提供多個受管來源時，[受管層級內的優先順序](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)規則說明 Claude Code 從每個來源讀取的內容。

6632. **命令列引數**：您在終端機啟動 `claude` 時傳遞的旗標，用於一個工作階段；請參閱[為一個工作階段變更設定](#change-a-setting-for-one-session)。Claude Code 使用與其他層級相同的規則合併您用 `--settings <file-or-json>` 傳遞的 JSON：它在此處設定的金鑰優先於本機、專案或使用者設定中的相同金鑰，並為您省略的金鑰保留較低層級的值。6632. **命令列引數**：您從終端機啟動 `claude` 時傳遞的旗標，適用於一個工作階段；請參閱[變更一個工作階段的設定](#change-a-setting-for-one-session)。Claude Code 使用 `--settings <file-or-json>` 傳遞的 JSON 與您的設定檔案合併，遵循與其他層級相同的規則：它採用您在此設定的鍵而不是本機、專案或使用者設定中的相同鍵，並為您省略的鍵保留較低層級的值。

6643. **專案本機設定**（`.claude/settings.local.json`）：此專案的您的個人設定。6643. **專案本機設定** (`.claude/settings.local.json`)：您對此專案的個人設定。

6654. **共享專案設定**（`.claude/settings.json`）：您的團隊簽入原始碼控制的設定。6654. **共用專案設定** (`.claude/settings.json`)：您的團隊簽入原始碼控制的設定。

6665. **使用者設定**（`~/.claude/settings.json`）：每個專案的您的個人設定。6665. **使用者設定** (`~/.claude/settings.json`)：您對每個專案的個人設定。

667 667

668環境變數不是此堆疊中的層級。當行為同時具有 shell 變數和設定金鑰時，哪一個適用是按對決定的，而不是按層級：在您的 shell 中匯出的 `ANTHROPIC_MODEL` 適用於任何檔案中的 `model` 金鑰，而 `ANTHROPIC_DEFAULT_MODEL` 僅在沒有檔案設定 `model` 時適用。[環境變數參考](/docs/zh-TW/env-vars#precedence)說明哪些金鑰有對以及 Claude Code 首先讀取哪一個。設定檔案內的 `env` 區塊是普通金鑰並遵循上面的層級。668環境變數不是此堆疊中的層級。當行為同時具有 shell 變數和設定鍵時，哪一個適用是按對決定的，而不是按層級：在您的 shell 中匯出的 `ANTHROPIC_MODEL` 適用於任何檔案中的 `model` 鍵，而 `ANTHROPIC_DEFAULT_MODEL` 僅在沒有檔案設定 `model` 時適用。[環境變數參考](/docs/zh-TW/env-vars#precedence)說明哪些鍵有對應以及 Claude Code 首先讀取哪一個。設定檔案內的 `env` 區塊是普通鍵，遵循上述層級。

669 669

670對於少數安全敏感金鑰，Claude Code 尊重來自較低層級的更嚴格值優先於受管值；[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)列出它們。670對於少數安全敏感的鍵，Claude Code 會尊重來自較低層級的更嚴格值而不是受管值；[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)列出了它們。

671 671

672<h3 id="lists-merge-instead-of-overriding">672<h3 id="lists-merge-instead-of-overriding">

673 列表改為合併而不是覆蓋673 列表合併而不是覆蓋

674</h3>674</h3>

675 675

676當您在多個檔案中設定相同的列表金鑰（例如 `permissions.allow`）時，Claude Code 合併列表而不是選擇一個，因此每個檔案可以新增項目而不移除另一個檔案的。四個保存模型列表或每個模型項目的金鑰遵循自己的規則：676當您在多個檔案中設定相同的列表鍵（例如 `permissions.allow`）時，Claude Code 會合併列表而不是選擇一個，因此每個檔案都可以新增項目而不移除另一個檔案的項目。四個保存模型列表或每個模型項目的鍵遵循自己的規則：

677 677

678* [`fallbackModel`](/docs/zh-TW/settings-reference#fallbackmodel) 是一個有序鏈，其中位置具有意義，因此 Claude Code 從定義它的最高優先順序檔案取整個值。678* [`fallbackModel`](/docs/zh-TW/settings-reference#fallbackmodel) 是一個有序鏈，其中位置具有意義，因此 Claude Code 採用定義它的最高優先順序檔案的整個值。

679* [`modelPicker`](/docs/zh-TW/settings-reference#modelpicker) 保存一個有序行列表加上替換旗標，因此 Claude Code 永遠不會合併來自兩個來源的行。它從定義它的受管設定、`--settings` 和使用者設定的最高取整個值，並忽略專案和本機設定中的金鑰。需要 Claude Code v2.1.242 或更新版本。679* [`modelPicker`](/docs/zh-TW/settings-reference#modelpicker) 保存一個有序列表行加上一個替換旗標，因此 Claude Code 永遠不會合併來自兩個來源的行。它採用定義它的受管設定、`--settings` 和使用者設定中最高的整個值，並忽略專案和本機設定中的鍵。需要 Claude Code v2.1.242 或更新版本。

680* [`availableModels`](/docs/zh-TW/settings-reference#availablemodels)：當 Claude Code 應用的受管設定定義它時，Claude Code 按原樣應用該列表並忽略您在使用者、專案或本機設定中新增的項目，除非嵌入 Claude Code 的應用程式提供自己的模型列表；請參閱[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)。跨受管來源列表也永遠不會合併；[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明哪個來源的列表適用。跨非受管範圍 Claude Code 照常合併陣列。680* [`availableModels`](/docs/zh-TW/settings-reference#availablemodels)：當 Claude Code 應用的受管設定定義它時，Claude Code 按原樣應用該列表，並忽略您在使用者、專案或本機設定中新增的項目，除非嵌入 Claude Code 的應用程式提供自己的模型列表；請參閱[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)。在受管來源之間，列表也永遠不會合併；[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明哪個來源的列表適用。在非受管範圍內，Claude Code 照常合併陣列。

681* [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings)：Claude Code 一次解析它一個模型，連同 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel)。`modelSettings` 項目說明哪個檔案的值適用於模型。681* [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings)：Claude Code 一次解析一個模型，連同 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel)。`modelSettings` 項目說明哪個檔案的值適用於模型。

682 682

683<span id="examples" />683<span id="examples" />

684 684

686 優先順序範例686 優先順序範例

687</h3>687</h3>

688 688

689當 Claude 工作時，Claude Code 在微調器下顯示單行提示，例如「使用 /config 變更您的預設權限模式（包括 Plan Mode）」。假設您想要這些提示關閉，因此您在 `~/.claude/settings.json` 中將 [`spinnerTipsEnabled`](/docs/zh-TW/settings-reference#spinnertipsenabled) 設定為 `false`。下面的每個情景都是可以將它們打開的東西，以及您可以做什麼。689當 Claude 工作時，Claude Code 在微調器下方顯示一行提示，例如「使用 /config 變更您的預設權限模式（包括 Plan Mode）」。假設您想關閉這些提示，因此您在 `~/.claude/settings.json` 中將 [`spinnerTipsEnabled`](/docs/zh-TW/settings-reference#spinnertipsenabled) 設定為 `false`。下面的每個情景都是可能將它們重新開啟的事情，以及您可以做什麼。

690 690

691<h4 id="team-settings-override-personal-settings">691<h4 id="team-settings-override-personal-settings">

692 團隊設定覆蓋個人設定692 團隊設定覆蓋個人設定

693</h4>693</h4>

694 694

695您的團隊的 `.claude/settings.json` 將其設定為 `true`。Claude Code 使用專案值，因為共享專案位於使用者上方，因此您在該專案中看到提示，而在其他地方看不到。695您的團隊的 `.claude/settings.json` 將其設定為 `true`。Claude Code 使用專案值，因為共用專案位於使用者之上，因此您在該專案中看到提示，在其他地方看不到。

696 696

697您可以取回您的值：在該專案中將 `"spinnerTipsEnabled": false` 新增到 `.claude/settings.local.json`。專案本機位於共享專案上方，因此您的工作階段停止顯示提示，您隊友的工作階段不變。697您可以取回您的值：在該專案的 `.claude/settings.local.json` 中新增 `"spinnerTipsEnabled": false`。專案本機位於共用專案之上，因此您在那裡的工作階段停止顯示提示，您的隊友的工作階段不會改變。

698 698

699<h4 id="organization-settings-override-everything">699<h4 id="organization-settings-override-everything">

700 組織設定覆蓋一切700 組織設定覆蓋一切

701</h4>701</h4>

702 702

703您的組織的受管設定將其設定為 `true`。您在使用者、專案或本機設定中放入的任何內容都不會關閉提示，`--settings` 也不會。受管是最高層級。703您的組織的受管設定將其設定為 `true`。您在使用者、專案或本機設定中放置的任何內容都不會關閉提示，`--settings` 也不會。受管是最高層級。

704 704

705您無法取回您的值。執行 `/status` 以查看哪個受管來源適用，並詢問您的管理員政策是否應該變更。705您無法取回您的值。執行 `/status` 以查看哪個受管來源適用，並詢問您的管理員是否應該變更原則。

706 706

707<h4 id="the-command-line-overrides-your-files-for-one-session">707<h4 id="the-command-line-overrides-your-files-for-one-session">

708 命令列覆蓋您的檔案用於一個工作階段708 命令列覆蓋您的檔案一個工作階段

709</h4>709</h4>

710 710

711您使用 `claude --settings '{"spinnerTipsEnabled": true}'` 啟動了工作階段。命令列位於除受管外的每個檔案上方，因此該工作階段顯示提示，即使您的檔案說 `false`。711您使用 `claude --settings '{"spinnerTipsEnabled": true}'` 啟動了工作階段。命令列位於除受管外的每個檔案之上，因此該工作階段顯示提示，即使您的檔案說 `false`。

712 712

713您在下一個工作階段上取回您的值；`--settings` 持續一個工作階段並不寫入任何檔案。713您在下一個工作階段取回您的值；`--settings` 持續一個工作階段，不會寫入任何檔案。

714 714

715<h4 id="a-flag-or-environment-variable-sets-the-same-thing">715<h4 id="a-flag-or-environment-variable-sets-the-same-thing">

716 旗標或環境變數設定相同的東西716 旗標或環境變數設定相同的內容

717</h4>717</h4>

718 718

719某些金鑰有命令列旗標或環境變數，無論哪個檔案設定它，都覆蓋設定值：`ANTHROPIC_MODEL` 覆蓋 [`model`](/docs/zh-TW/settings-reference#model) 設定，而 `--model` 為工作階段覆蓋兩者。719某些鍵具有命令列旗標或環境變數，無論哪個檔案設定它，都會覆蓋設定值：`ANTHROPIC_MODEL` 覆蓋 [`model`](/docs/zh-TW/settings-reference#model) 設定，`--model` 在一個工作階段內覆蓋兩者。

720 720

721您是否可以取回您的值取決於金鑰：取消設定變數或刪除旗標，並檢查[設定參考](/docs/zh-TW/settings-reference)上的金鑰項目和[環境變數參考](/docs/zh-TW/env-vars)上的變數行，以了解 Claude Code 使用哪一個。721您是否可以取回您的值取決於鍵：取消設定變數或刪除旗標，並檢查[設定參考](/docs/zh-TW/settings-reference)上的鍵項目和[環境變數參考](/docs/zh-TW/env-vars)上的變數列，以了解 Claude Code 使用哪一個。

722 722

723<span id="keys-ignored-in-a-repository-file" />723<span id="keys-ignored-in-a-repository-file" />

724 724

732 疑難排解不適用的設定732 疑難排解不適用的設定

733</h3>733</h3>

734 734

735當您設定金鑰而 Claude Code 不表現得好像您有時，請從 `/status` 開始以查看它載入了哪些檔案，然後在下面找到您的症狀。[除錯您的設定](/docs/zh-TW/debug-your-config)涵蓋更廣泛的檢查，包括乾淨設定測試。735當您設定鍵而 Claude Code 沒有表現得像您一樣時，從 `/status` 開始查看它載入了哪些檔案，然後在下面找到您的症狀。[偵錯您的設定](/docs/zh-TW/debug-your-config)涵蓋更廣泛的檢查，包括乾淨設定測試。

736 736

737<h4 id="a-value-you-set-is-ignored">737<h4 id="a-value-you-set-is-ignored">

738 您設定的值被忽略738 您設定的值被忽略

739</h4>739</h4>

740 740

741其他東西設定相同金鑰、檔案無法設定該值，或檔案未載入：741其他東西設定了相同的鍵，檔案無法設定該值，或檔案未載入：

742 742

743* **較高層級設定它。** 另一個設定檔案、`--settings` 旗標或受管來源在您的上方設定金鑰；[堆疊](#settings-precedence)說明哪一個。旗標或環境變數也可以按自己的方式覆蓋金鑰，按金鑰決定；[設定參考](/docs/zh-TW/settings-reference)上的金鑰項目說明 Claude Code 使用哪一個，而 [`env` 項目](/docs/zh-TW/settings-reference#env)涵蓋受管 `env` 值與 shell 匯出。743* **較高層級設定它。** 另一個設定檔案、`--settings` 旗標或受管來源在您的上方設定鍵；[堆疊](#settings-precedence)說明哪一個。旗標或環境變數也可以自行覆蓋鍵，按鍵決定；[設定參考](/docs/zh-TW/settings-reference)上的鍵項目說明 Claude Code 使用哪一個，[`env` 項目](/docs/zh-TW/settings-reference#env)涵蓋受管 `env` 值與 shell 匯出。

744* **安全金鑰保持其嚴格值。** 對於少數金鑰，Claude Code 尊重來自任何檔案的限制值，因此專案 `true` 用於 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) 保持開啟；請參閱[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)。744* **安全鍵保持其嚴格值。** 對於少數鍵，Claude Code 尊重來自任何檔案的限制值，因此專案 `true` 的 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) 保持開啟；請參閱[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)。

745* **檔案無法設定該值。** [`permissions.defaultMode`](/docs/zh-TW/settings-reference#permissions-defaultmode) 值 `auto` 和 `bypassPermissions` 不從專案或本機設定生效；改為在使用者或受管設定中設定它們，或為一個工作階段傳遞 `--permission-mode`。在 v2.1.257 之前，`bypassPermissions` 從任何檔案生效。745* **檔案無法設定該值。** [`permissions.defaultMode`](/docs/zh-TW/settings-reference#permissions-defaultmode) 值 `auto` 和 `bypassPermissions` 不會從專案或本機設定生效；改為在使用者或受管設定中設定它們，或為一個工作階段傳遞 `--permission-mode`。在 v2.1.257 之前，`bypassPermissions` 從任何檔案生效。

746* **檔案損壞。** 無效的 JSON 或拒絕的值使 Claude Code 跳過檔案或項目；請參閱[修復損壞的設定檔案](#fix-a-broken-settings-file)。746

747 [`env`](/docs/zh-TW/settings-reference#env) 區塊中的遙測匯出變數也不會從專案或本機設定生效，除了少數關閉值。[Claude Code 在 `env` 中忽略的變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)列出變數和這些值。

748* **檔案已損壞。** 無效的 JSON 或被拒絕的值會導致 Claude Code 跳過檔案或項目；請參閱[修復損壞的設定檔案](#fix-a-broken-settings-file)。

747 749

748<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">750<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">

749 您在 Claude Code 中所做的變更在新工作階段中丟失751 您在 Claude Code 中所做的變更在新工作階段中丟失

750</h4>752</h4>

751 753

752當您從 Claude Code 內儲存新工作階段的選擇時，例如使用 `/model` 的預設模型，Claude Code 將其寫入您的使用者設定檔案 `~/.claude/settings.json`。如果您無法寫入該檔案，例如因為另一個工具產生它或將其連結到唯讀副本，變更適用於目前工作階段並在下一個工作階段中消失。在產生檔案的工具中設定金鑰，或用您可以寫入的檔案替換檔案。754當您從 Claude Code 內部為新工作階段儲存選擇時，例如使用 `/model` 的預設模型，Claude Code 會將其寫入您的使用者設定檔案 `~/.claude/settings.json`。如果您無法寫入該檔案，例如因為另一個工具生成它或將其連結到唯讀副本，變更適用於目前工作階段，在下一個工作階段中消失。在生成檔案的工具中設定鍵，或將檔案替換為您可以寫入的檔案。

753 755

754如果您可以寫入檔案而變更仍然不持續，請檢查變更是否[僅用於一個工作階段](#change-a-setting-for-one-session)或[較高層級設定相同金鑰](#a-value-you-set-is-ignored)。對於 `model` 金鑰，[新工作階段在不同的模型上啟動而不是您選擇的](/docs/zh-TW/model-config#a-new-session-starts-on-a-different-model-than-you-picked)列出更多原因。756如果您可以寫入檔案，變更仍然不持續，請檢查變更是否[僅適用於一個工作階段](#change-a-setting-for-one-session)或[較高層級設定相同的鍵](#a-value-you-set-is-ignored)。對於 `model` 鍵，[新工作階段以不同的模型開始，而不是您選擇的](/docs/zh-TW/model-config#a-new-session-starts-on-a-different-model-than-you-picked)列出更多原因。

755 757

756<h4 id="a-managed-change-hasn’t-reached-you">758<h4 id="a-managed-change-hasn’t-reached-you">

757 受管變更還沒有到達您759 受管變更尚未到達您

758</h4>760</h4>

759 761

760受管來源按[傳遞表](/docs/zh-TW/managed-settings#choose-a-delivery-mechanism)中的排程到達執行中的工作階段，因此首先重新啟動工作階段。如果 `/status` 然後命名不同的來源而不是您的管理員變更的，較高優先順序的來源適用；[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)給出順序。762受管來源根據[傳遞表](/docs/zh-TW/managed-settings#choose-a-delivery-mechanism)中的排程到達執行中的工作階段，因此請先重新啟動工作階段。如果 `/status` 隨後命名與您的管理員變更的來源不同的來源，則較高優先順序的來源適用；[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)給出順序。

761 763

762<h4 id="a-committed-key-doesn’t-reach-teammates">764<h4 id="a-committed-key-doesn’t-reach-teammates">

763 提交的金鑰不到達隊友765 已提交的鍵無法到達隊友

764</h4>766</h4>

765 767

766兩件事使 `.claude/settings.json` 中的金鑰無法為複製它的每個人應用：768兩件事使 `.claude/settings.json` 中的鍵無法為克隆它的每個人應用：

769

770* **Claude Code 忽略儲存庫檔案中的鍵。** 在[設定索引](/docs/zh-TW/settings-reference#settings-index)的「範圍」欄中查找 `User, local, or managed`、`User or managed`、`Managed` 或 `Global config`。這些鍵永遠不會從共用檔案應用，除了少數儲存庫檔案仍然可以關閉的鍵。每個這些項目在其「範圍」行上都說明了這一點。`Global config` 鍵僅從 `~/.claude.json` 應用。

767 771

768* **Claude Code 忽略儲存庫檔案中的金鑰。** 在[設定索引](/docs/zh-TW/settings-reference#settings-index)的「範圍」欄中查找 `User, local, or managed`、`User or managed`、`Managed` 或 `Global config`。這些金鑰永遠不會從共享檔案應用，除了少數可以儲存庫檔案仍然關閉的金鑰。每個這些項目在其「範圍」行上說明。`Global config` 金鑰僅從 `~/.claude.json` 應用。772 在 `env` 鍵內，遙測匯出變數也永遠不會從共用檔案應用，除了少數關閉值；請參閱[Claude Code 在 `env` 中忽略的變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)。

769* **金鑰等待信任。** `permissions.allow` 規則、`permissions.additionalDirectories`、`extraKnownMarketplaces` 和大多數 [`env`](/docs/zh-TW/settings-reference#env) 值僅在每個隊友[信任資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)後應用。在那之前，他們仍然看到提示並不從檔案宣告的 marketplace 獲得 plugins。`deny` 和 `ask` 規則立即應用。773* **鍵等待信任。** `permissions.allow` 規則、`permissions.additionalDirectories`、`extraKnownMarketplaces` 和大多數 [`env`](/docs/zh-TW/settings-reference#env) 值僅在每個隊友[信任資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)後應用。在那之前，他們仍然看到提示，不會從檔案宣告的市場獲得外掛程式。`deny` 和 `ask` 規則立即應用。

770 774

771<h4 id="permission-rules-combine-differently-than-you-expected">775<h4 id="permission-rules-combine-differently-than-you-expected">

772 權限規則組合方式與您預期不同776 權限規則的合併方式與您預期的不同

773</h4>777</h4>

774 778

775* **您在權限提示上選擇「是，不要再問」但仍然為相同工具獲得提示。** 該選擇將 `allow` 規則儲存到您的本機檔案，本機的 `allow` 規則不優先於專案或受管檔案的 `ask` 規則；[權限規則如何組合](/docs/zh-TW/permissions#settings-precedence)解釋順序。在 VS Code 擴充功能中，批准卡讓您選擇目標檔案，包括專案的共享檔案，這為每個人變更規則；在 CLI 中，Claude Code 僅寫入您的本機檔案。779* **您在權限提示上選擇了「是，不要再問」，但仍然收到相同工具的提示。** 該選擇將 `allow` 規則儲存到您的本機檔案，本機檔案中的 `allow` 規則不會超越專案或受管檔案中的 `ask` 規則；[權限規則如何合併](/docs/zh-TW/permissions#settings-precedence)解釋了順序。在 VS Code 擴充功能中，核准卡讓您選擇目標檔案，包括專案的共用檔案，這會為每個人變更規則；在 CLI 中，Claude Code 僅寫入您的本機檔案。

776* **您的組織的 allow 規則仍然與您的一起應用。** 這是預期的：Claude Code 跨範圍合併 [`permissions.allow`](/docs/zh-TW/settings-reference#permissions-allow)，除非您的組織設定 [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly)。780* **您的組織的允許規則仍然與您的規則一起應用。** 這是預期的：Claude Code 在範圍內合併 [`permissions.allow`](/docs/zh-TW/settings-reference#permissions-allow)，除非您的組織設定 [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly)。

777 781

778<span id="security-keys-where-the-stricter-value-applies" />782<span id="security-keys-where-the-stricter-value-applies" />

779 783

781 受管設定優先順序的例外785 受管設定優先順序的例外

782</h3>786</h3>

783 787

784對於少數值限制工作階段的金鑰，Claude Code 尊重來自否則無法覆蓋受管設定的範圍的限制值。在此表中找到金鑰以查看它尊重哪個值以及從哪裡。788對於少數值限制工作階段的鍵，Claude Code 尊重來自範圍的限制值，該範圍在其他情況下無法覆蓋受管設定。在此表中找到鍵以查看它尊重哪個值以及來自何處。

785 789

786| 金鑰 | Claude Code 尊重的值 | 注意 |790| 鍵 | Claude Code 尊重的值 | 備註 |

787| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |791| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |

789| [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) | 來自任何範圍的 `false`，以及來自任何範圍的 `disableArtifact: true` | 即使受管來源設定 `true` 也被尊重；沒有什麼將 [Artifact 工具](/docs/zh-TW/artifacts#disable-artifacts)打開。需要 Claude Code v2.1.242 或更新版本 |793| [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) | 來自任何範圍的 `false`，以及來自任何範圍的 `disableArtifact: true` | 即使受管來源設定 `true` 也被尊重；沒有任何東西會打開[成品工具](/docs/zh-TW/artifacts#disable-artifacts)。需要 Claude Code v2.1.242 或更新版本 |

791| [`remoteControlAtStartup`](/docs/zh-TW/settings-reference#remotecontrolatstartup) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使受管來源設定 `true` 也被尊重；專案或本機 `true` 被忽略 |795| [`remoteControlAtStartup`](/docs/zh-TW/settings-reference#remotecontrolatstartup) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使受管來源設定 `true` 也被尊重；專案或本機 `true` 被忽略 |

792| [`crossSessionInbound`](/docs/zh-TW/settings-reference#crosssessioninbound) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的更嚴格值，在 `accept` \< `hold` \< `refuse` 梯形上 | 在受管、`--settings` 和使用者值上被尊重；不是更嚴格的專案或本機值被忽略 |796| [`crossSessionInbound`](/docs/zh-TW/settings-reference#crosssessioninbound) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的更嚴格值，在 `accept` \< `hold` \< `refuse` 梯級上 | 在受管、`--settings` 和使用者值上被尊重；不是更嚴格的專案或本機值被忽略 |

793| [`useAutoModeDuringPlan`](/docs/zh-TW/settings-reference#useautomodeduringplan) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |797| [`useAutoModeDuringPlan`](/docs/zh-TW/settings-reference#useautomodeduringplan) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |

794| [`syncClaudeAiSkills`](/docs/zh-TW/settings-reference#syncclaudeaiskills) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |798| [`syncClaudeAiSkills`](/docs/zh-TW/settings-reference#syncclaudeaiskills) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |

795| [`syncClaudeAiPlugins`](/docs/zh-TW/settings-reference#syncclaudeaiplugins) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |799| [`syncClaudeAiPlugins`](/docs/zh-TW/settings-reference#syncclaudeaiplugins) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |

796| [`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) | 來自任何範圍的較低上限，包括 `--settings` | 即使 Claude Code 應用的受管設定設定較高上限也被尊重；最低上限適用。需要 Claude Code v2.1.267 或更新版本 |800| [`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) | 來自任何範圍（包括 `--settings`）的較低上限 | 即使 Claude Code 應用的受管設定設定較高的上限也被尊重；最低上限適用。需要 Claude Code v2.1.267 或更新版本 |

797 801

798在自己內部執行 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的應用程式也是例外。Claude Code 將該應用程式的模型設定優先於來自每個受管來源的 `model`、`fallbackModel`、`modelPicker` 和 `modelOverrides` 金鑰，以及受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列。Claude Code 保持受管 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單生效，除非應用程式提供自己的。802執行 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的應用程式也是例外。Claude Code 採用該應用程式的模型設定而不是來自每個受管來源的 `model`、`fallbackModel`、`modelPicker` 和 `modelOverrides` 鍵，以及受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列。Claude Code 保持受管 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單有效，除非應用程式提供自己的。

799 803

800<h2 id="settings-in-cloud-sessions">804<h2 id="settings-in-cloud-sessions">

801 雲端工作階段中的設定805 雲端工作階段中的設定

settings-example.md +2 −14

Details

98 團隊的共享設定98 團隊的共享設定

99</h2>99</h2>

100 100

101一個團隊的共享設定，提交到版本庫，以便每個複製它的人都獲得相同的權限、hooks、遙測和外掛程式市集。在版本庫的頂部將這樣的檔案儲存在 `.claude/settings.json`。提交之前需要了解的事項：101一個團隊的共享設定，提交到版本庫，以便每個複製它的人都獲得相同的權限、hooks 和外掛程式市集。在版本庫的頂部將這樣的檔案儲存在 `.claude/settings.json`。提交之前需要了解的事項：

102 102

103* **雲端工作階段也會讀取它。** 一個 [雲端工作階段](/docs/zh-TW/settings#settings-in-cloud-sessions) 從版本庫的複製開始，因此提交的檔案也適用於此。103* **雲端工作階段也會讀取它。** 一個 [雲端工作階段](/docs/zh-TW/settings#settings-in-cloud-sessions) 從版本庫的複製開始，因此提交的檔案也適用於此。

104* **遙測進入受管理或個人設定。** Claude Code 會忽略版本庫設定檔案中的 [OpenTelemetry 匯出器變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)，除了一些關閉遙測的值。在 [受管理設定](/docs/zh-TW/monitoring-usage#administrator-configuration) 中為您的組織設定它們，或在每個人的 `~/.claude/settings.json` 中設定。

104* **允許規則等待信任。** 允許規則和 `extraKnownMarketplaces` 項目在每個人 [信任此資料夾本身](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust) 後生效，不僅是父資料夾；拒絕和詢問規則在每個工作階段中適用，無論是否信任。105* **允許規則等待信任。** 允許規則和 `extraKnownMarketplaces` 項目在每個人 [信任此資料夾本身](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust) 後生效，不僅是父資料夾；拒絕和詢問規則在每個工作階段中適用，無論是否信任。

105* **hook 是版本庫中的指令碼。** 此檔案的 hook 執行 `.claude/hooks/block-rm.sh`；[hook 如何解析](/docs/zh-TW/hooks#how-a-hook-resolves) 說明如何編寫它。106* **hook 是版本庫中的指令碼。** 此檔案的 hook 執行 `.claude/hooks/block-rm.sh`；[hook 如何解析](/docs/zh-TW/hooks#how-a-hook-resolves) 說明如何編寫它。

106* **規則匹配所寫的命令和路徑。** `Bash(git push *)` 不匹配 [`git -C . push`](/docs/zh-TW/permissions#bash-rule-limits)。`Read(./.env)` 本身會停止檔案工具和命名檔案的命令，例如 `cat .env`，但不會停止 [`grep -r` 在目錄上執行](/docs/zh-TW/permissions#read-and-edit)；此檔案中的 `sandbox` 區塊關閉了該間隙，因為沙箱 [新增您的 `Read` 拒絕路徑](/docs/zh-TW/settings-reference#sandbox-filesystem-denyread) 到每個沙箱化命令無法讀取的內容。107* **規則匹配所寫的命令和路徑。** `Bash(git push *)` 不匹配 [`git -C . push`](/docs/zh-TW/permissions#bash-rule-limits)。`Read(./.env)` 本身會停止檔案工具和命名檔案的命令，例如 `cat .env`，但不會停止 [`grep -r` 在目錄上執行](/docs/zh-TW/permissions#read-and-edit)；此檔案中的 `sandbox` 區塊關閉了該間隙，因為沙箱 [新增您的 `Read` 拒絕路徑](/docs/zh-TW/settings-reference#sandbox-filesystem-denyread) 到每個沙箱化命令無法讀取的內容。

124 "Read(./secrets/**)"125 "Read(./secrets/**)"

125 ]126 ]

126 },127 },

127 "env": {

128 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

129 "OTEL_METRICS_EXPORTER": "otlp",

130 "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",

131 "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317"

132 },

133 "hooks": {128 "hooks": {

134 "PreToolUse": [129 "PreToolUse": [

135 {130 {

194 "Read(./secrets/**)"189 "Read(./secrets/**)"

195 ]190 ]

196 },191 },

197 // 透過 gRPC 將 OpenTelemetry 指標傳送到團隊的收集器；將端點替換為您的收集器 URL

198 "env": {

199 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

200 "OTEL_METRICS_EXPORTER": "otlp",

201 "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",

202 "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317"

203 },

204 // 在每個 Bash 命令前，執行版本庫中可以阻止它的指令碼192 // 在每個 Bash 命令前，執行版本庫中可以阻止它的指令碼

205 "hooks": {193 "hooks": {

206 "PreToolUse": [194 "PreToolUse": [

settings-reference.md +334 −309

Details

713| [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) | 防止任何人進入 [bypassPermissions 模式](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) | 權限設定 | Any file |713| [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) | 防止任何人進入 [bypassPermissions 模式](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) | 權限設定 | Any file |

789| [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | 從使用者和專案來源封鎖[技能](/docs/zh-TW/skills)、[代理](/docs/zh-TW/sub-agents)、[hooks](/docs/zh-TW/hooks) 和 [MCP 伺服器](/docs/zh-TW/mcp) | 外掛程式和技能 | Managed |789| [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | 從使用者和專案來源封鎖[技能](/docs/zh-TW/skills)、[代理](/docs/zh-TW/sub-agents)、[hooks](/docs/zh-TW/hooks) 和 [MCP 伺服器](/docs/zh-TW/mcp) | 外掛程式和技能 | Managed |

833 `advisorModel`833 `advisorModel`

834</h3>834</h3>

835 835

836選擇當 Claude 呼叫伺服器端[顧問工具](/docs/zh-TW/advisor)時回答的模型。取消設定以關閉顧問。顧問的能力必須至少與您的主要模型相同。請參閱[選擇顧問模型](/docs/zh-TW/advisor#choose-an-advisor-model)以了解接受的配對及選擇未接受的配對時會發生什麼。836選擇當 Claude 呼叫伺服器端[顧問工具](/docs/zh-TW/advisor)時回答的模型。取消設定以關閉顧問。顧問的能力必須至少與您的主要模型相當。請參閱[選擇顧問模型](/docs/zh-TW/advisor#choose-an-advisor-model)以了解接受的配對及選擇未被接受的配對時會發生什麼。

837 837

838您通常不會手動編輯此金鑰。執行 `/advisor` 以開啟選擇器，顯示目前選擇、可以提供建議的模型和**無顧問**。Claude Code 會將您的選擇儲存到 `~/.claude/settings.json` 中的此金鑰。如果您從[遠端控制](/docs/zh-TW/remote-control)用戶端或附加到遠端工作者的工作階段中選擇，該選擇僅適用於該工作階段，不會變更此金鑰。838您通常不會手動編輯此金鑰。執行 `/advisor` 以開啟選擇器，顯示目前的選擇、可以提供建議的模型和**無顧問**。Claude Code 會將您的選擇儲存到 `~/.claude/settings.json` 中的此金鑰。如果您從[遠端控制](/docs/zh-TW/remote-control)用戶端或附加到遠端工作者的工作階段中選擇，該選擇僅適用於該工作階段，不會變更此金鑰。

839 839

840如果您的帳戶需要[使用額度同意](/docs/zh-TW/advisor#fable-advisor-and-usage-credits)，請先執行 `/model fable` 以接受。在您這樣做之前，在 `/advisor` 中選擇 Fable 不會儲存任何內容，Claude Code 會告訴您先執行 `/model fable`。840如果您的帳戶需要[使用額度同意](/docs/zh-TW/advisor#fable-advisor-and-usage-credits)，請先執行 `/model fable` 以接受。在您這樣做之前，在 `/advisor` 中選擇 Fable 不會儲存任何內容，Claude Code 會告訴您先執行 `/model fable`。

841 841

842* **範圍**: [`任何檔案`](#scopes)842* **範圍**: [`任何檔案`](#scopes)

843* **類型**: 字串，為別名 `"fable"`、`"opus"` 或 `"sonnet"` 之一，這些別名會解析為 Claude Code 該模型系列的目前預設版本，或完整模型 ID，例如 `"claude-opus-5"`843* **類型**: 字串，別名之一 `"fable"`、`"opus"` 或 `"sonnet"`，解析為 Claude Code 該模型系列的目前預設版本，或完整模型 ID，例如 `"claude-opus-5-5"`

844* **預設**: 未設定，因此顧問已關閉844* **預設**: 未設定，因此顧問已關閉

845* **每個工作階段覆蓋**: `--advisor` 優先於此金鑰一個工作階段。[`CLAUDE_CODE_DISABLE_ADVISOR_TOOL`](/docs/zh-TW/env-vars)關閉顧問，此金鑰無法將其重新開啟845* **每個工作階段的覆蓋**: `--advisor` 優先於此金鑰一個工作階段。[`CLAUDE_CODE_DISABLE_ADVISOR_TOOL`](/docs/zh-TW/env-vars)關閉顧問，此金鑰無法將其重新開啟

846 846

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

848{848{

858 858

859透過將此設定為 `false` 來為每個工作階段關閉[延伸思考](/docs/zh-TW/model-config#extended-thinking)。思考預設為開啟，因此 `true` 不會改變任何內容。大多數人透過 `/config` 而不是編輯檔案來設定此項。859透過將此設定為 `false` 來為每個工作階段關閉[延伸思考](/docs/zh-TW/model-config#extended-thinking)。思考預設為開啟，因此 `true` 不會改變任何內容。大多數人透過 `/config` 而不是編輯檔案來設定此項。

860 860

861在始終思考的模型上，例如 Fable 模型，`false` 無效。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，Claude Code 會省略 `thinking` 參數而不是關閉思考，因此自適應推理模型可能仍會思考。在 Anthropic API 上關閉思考時，Claude Code 會傳送努力 `high` 而不是更高級別給它知道[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型，例如 Opus 5。861在始終思考的模型上，例如 Opus 5.5 和 Fable 模型，`false` 無效。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，Claude Code 省略 `thinking` 參數而不是關閉思考，因此自適應推理模型可能仍會思考。在 Anthropic API 上關閉思考時，Claude Code 會傳送努力 `high` 而不是更高級別給它知道[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型，例如 Opus 5。

862 862

863* **範圍**: [`任何檔案`](#scopes)863* **範圍**: [`任何檔案`](#scopes)

864* **類型**: 布林值864* **類型**: 布林值

865 * `true`: 無效；思考已經開啟865 * `true`: 無效；思考已經開啟

866 * `false`: Claude Code 為每個工作階段關閉延伸思考866 * `false`: Claude Code 為每個工作階段關閉延伸思考

867* **預設**: 未設定，因此思考對支援它的模型開啟867* **預設**: 未設定，因此思考對支援它的模型開啟

868* **每個工作階段覆蓋**: [`MAX_THINKING_TOKENS`](/docs/zh-TW/env-vars)優先於此金鑰一個工作階段：`0` 關閉思考，受相同模型和提供者限制如 `false`，正值開啟思考，即使此金鑰為 `false`。在自適應推理模型上，數字本身被忽略868* **每個工作階段的覆蓋**: [`MAX_THINKING_TOKENS`](/docs/zh-TW/env-vars)優先於此金鑰一個工作階段：`0` 關閉思考，受相同的模型和提供者限制如 `false`，正值開啟思考，即使此金鑰為 `false`。在自適應推理模型上，數字本身被忽略

869 869

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

871{871{

877 `availableModels`877 `availableModels`

878</h3>878</h3>

879 879

880限制人員可以為主要工作階段、[子代理](/docs/zh-TW/sub-agents)、[技能](/docs/zh-TW/skills)和[顧問](/docs/zh-TW/advisor)選擇的模型。受管清單限制 `/model`、`--model` 和開發人員自己檔案中的 `model` 金鑰；清單外的模型無法選擇。單獨來說，這不會觸及預設選項；將其與 [`enforceAvailableModels`](#enforceavailablemodels) 配對以實現該目的。880限制人們可以為主要工作階段、[子代理](/docs/zh-TW/sub-agents)、[技能](/docs/zh-TW/skills)和[顧問](/docs/zh-TW/advisor)選擇的模型。受管清單限制 `/model`、`--model` 和開發人員自己檔案中的 `model` 金鑰；清單外的模型無法選擇。單獨來說，這不會觸及預設選項；將其與 [`enforceAvailableModels`](#enforceavailablemodels) 配對以實現該目的。

881 881

882* **範圍**: [`任何檔案`](#scopes)。在受管設定中部署以對組織強制執行。882* **範圍**: [`任何檔案`](#scopes)。在受管設定中部署以為組織強制執行。

883* **類型**: 模型別名或 ID 的陣列883* **類型**: 模型別名或 ID 的陣列

884* **預設**: 未設定，因此每個模型都可用884* **預設**: 未設定，因此每個模型都可用

885 885

886此範例僅允許人員選擇 Sonnet 和 Haiku 模型：886此範例僅允許人們選擇 Sonnet 和 Haiku 模型：

887 887

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

889{889{

897 `effortLevel`897 `effortLevel`

898</h3>898</h3>

899 899

900為您尚未儲存級別的模型設定預設[努力級別](/docs/zh-TW/model-config#adjust-effort-level)。較低級別在直接任務上更快且更便宜，較高級別在複雜問題上推理更深入。900為您尚未儲存級別的模型設定預設[努力級別](/docs/zh-TW/model-config#adjust-effort-level)。較低的級別在直接任務上更快且更便宜，較高的級別在複雜問題上推理更深入。

901 901

902當您在機器上的互動工作階段中執行 `/effort low`、`medium`、`high` 或 `xhigh` 時，Claude Code 會將級別儲存在 [`modelSettings`](#modelsettings) 下的活動模型下，而不是寫入此金鑰。在 v2.1.251 之前，`/effort` 寫入此金鑰。902當您在機器上的互動工作階段中執行 `/effort low`、`medium`、`high` 或 `xhigh` 時，Claude Code 會在 [`modelSettings`](#modelsettings) 下為活動模型儲存級別，而不是寫入此金鑰。在 v2.1.251 之前，`/effort` 寫入此金鑰。

903 903

904在同一設定檔中，Claude Code 使用模型的儲存級別而不是此金鑰。[`modelSettings`](#modelsettings)說明跨檔案優先順序。904在同一設定檔中，Claude Code 使用模型的儲存級別而不是此金鑰。[`modelSettings`](#modelsettings)說明跨檔案優先順序。

905 905

906在附加到遠端工作者的工作階段中，`/effort` 僅適用於該工作階段。在 `-p` 執行或 Agent SDK 中，它也僅適用於該工作階段，[除非模型預設努力有保留](/docs/zh-TW/model-config#non-interactive-effort)。[調整努力級別](/docs/zh-TW/model-config#adjust-effort-level)列出也僅適用於該工作階段的互動選擇。`/effort` 列印的訊息說明發生了什麼。906在附加到遠端工作者的工作階段中、在 `-p` 執行中以及在 Agent SDK 中，`/effort` 僅適用於該工作階段。[調整努力級別](/docs/zh-TW/model-config#adjust-effort-level)列出也僅適用於該工作階段的互動選擇。`/effort` 列印的訊息說明發生了什麼。

907 907

908* **範圍**: [`任何檔案`](#scopes)908* **範圍**: [`任何檔案`](#scopes)

909* **類型**: 字串，為以下之一：909* **類型**: 字串，其中之一：

910 * `"low"`: 最少推理，用於短期、範圍內、延遲敏感且不是智慧敏感的任務910 * `"low"`: 最少推理，用於短期、範圍內、延遲敏感且不是智慧敏感的任務

911 * `"medium"`: 減少成本敏感工作的令牌使用，可以權衡一些智慧911 * `"medium"`: 減少成本敏感工作的令牌使用，可以權衡一些智慧

912 * `"high"`: 平衡令牌使用和智慧912 * `"high"`: 平衡令牌使用和智慧

913 * `"xhigh"`: 更深入的推理，令牌支出更高913 * `"xhigh"`: 更深入的推理，令牌支出更高

914* **預設**: 未設定914* **預設**: 未設定

915* **每個工作階段覆蓋**: `--effort` 優先於此金鑰一個工作階段，[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-TW/env-vars)優先於兩者915* **每個工作階段的覆蓋**: `--effort` 優先於此金鑰一個工作階段，[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-TW/env-vars)優先於兩者

916 916

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

918{918{

920}920}

921```921```

922 922

923在 Opus 4.7、Opus 4.8 和 Fable 5 上，Claude Code 保留該模型的預設努力，組織設定或內建；[調整努力級別](/docs/zh-TW/model-config#adjust-effort-level)說明哪些設定級別的方式結束保留，哪些保留。保留結束後，Claude Code 按 [`modelSettings`](#modelsettings) 中說明的優先順序解析努力。923在您的使用者設定檔 `~/.claude/settings.json` 中，此金鑰是 `/effort` 在按模型儲存級別之前寫入的較舊形式，它繼續適用於之前適用的地方，在 Opus 5、Fable 5.1 和較早的模型上。Opus 5.5 和之後發佈的模型忽略它，並從它們自己的預設開始，直到您為它們儲存級別，`/effort` 在 [`modelSettings`](#modelsettings) 下寫入。在專案、本地和受管設定中，以及使用 `--settings` 時，此金鑰適用於每個模型。

924 924

925<h3 id="enforceavailablemodels">925<h3 id="enforceavailablemodels">

926 `enforceAvailableModels`926 `enforceAvailableModels`

932 932

933* **範圍**: [`任何檔案`](#scopes)933* **範圍**: [`任何檔案`](#scopes)

934* **類型**: 布林值934* **類型**: 布林值

935 * `true`: 當**預設**會解析為 `availableModels` 外的模型時，Claude Code 將其解析為清單中第一個可用模型935 * `true`: 當**預設**會解析為 `availableModels` 外的模型時，Claude Code 將其解析為清單中第一個可用的模型

936 * `false`: **預設**照常解析，即使解析為 `availableModels` 外的模型936 * `false`: **預設**照常解析，即使解析為 `availableModels` 外的模型

937* **預設**: `false`937* **預設**: `false`

938 938

945}945}

946```946```

947 947

948當 `availableModels` 未設定或為空時，此金鑰無效。請參閱[對預設模型強制執行允許清單](/docs/zh-TW/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更新版本。948當 `availableModels` 未設定或為空時，此金鑰無效。請參閱[為預設模型強制執行允許清單](/docs/zh-TW/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更新版本。

949 949

950<h3 id="fallbackmodel">950<h3 id="fallbackmodel">

951 `fallbackModel`951 `fallbackModel`

952</h3>952</h3>

953 953

954命名備份模型供 Claude Code 在您的主要模型過載或不可用時依序嘗試。Claude Code 會為該輪的其餘部分切換到鏈中下一個可用模型，並顯示通知。沒有鏈的情況下，Claude Code 會重試相同模型，然後顯示伺服器的錯誤，您重試或自己切換模型。954命名備份模型供 Claude Code 在您的主要模型過載或不可用時依序嘗試。Claude Code 為該輪的其餘部分切換到備用模型鏈中下一個可用的模型，並顯示通知。沒有鏈的情況下，Claude Code 重試相同的模型，然後顯示伺服器的錯誤，您重試或自己切換模型。

955 955

956切換意味著在備用模型上進行一輪冷[提示快取](/docs/zh-TW/prompt-caching#switching-models)；您的下一條訊息首先再次嘗試主要模型。956切換意味著在備用模型上進行一輪冷[提示快取](/docs/zh-TW/prompt-caching#switching-models)；您的下一條訊息首先再次嘗試主要模型。

957 957

958* **範圍**: [`任何檔案`](#scopes)958* **範圍**: [`任何檔案`](#scopes)

959* **類型**: 模型別名或 ID 的陣列；`"default"` 擴展為預設模型959* **類型**: 模型別名或 ID 的陣列；`"default"` 擴展為預設模型

960* **預設**: 未設定，因此失敗的請求不會在另一個模型上重試960* **預設**: 未設定，因此失敗的請求不會在另一個模型上重試

961* **每個工作階段覆蓋**: `--fallback-model` 優先於此金鑰一個工作階段961* **每個工作階段的覆蓋**: `--fallback-model` 優先於此金鑰一個工作階段

962 962

963此範例在您的主要模型失敗時首先嘗試 Sonnet 5，然後嘗試 Haiku 4.5：963此範例在您的主要模型失敗時首先嘗試 Sonnet 5，然後嘗試 Haiku 4.5：

964 964

968}968}

969```969```

970 970

971與大多數陣列設定不同，此金鑰不會跨設定檔合併：最高優先順序的定義它的檔案提供整個鏈。如果您的專案檔案設定 `["claude-sonnet-5"]`，您的使用者檔案設定 `["claude-haiku-4-5"]`，鏈為 `["claude-sonnet-5"]` 只。Claude Code 從清單中最多保留三個不同的允許模型，忽略其餘的。請參閱[備用模型鏈](/docs/zh-TW/model-config#fallback-model-chains)。971與大多數陣列設定不同，此金鑰不會跨設定檔合併：最高優先順序的定義它的檔案提供整個鏈。如果您的專案檔案設定 `["claude-sonnet-5"]` 而您的使用者檔案設定 `["claude-haiku-4-5"]`，鏈是 `["claude-sonnet-5"]` 只。Claude Code 從清單中保留最多三個不同的允許模型，並忽略其餘的。請參閱[備用模型鏈](/docs/zh-TW/model-config#fallback-model-chains)。

972 972

973<h3 id="fastmode">973<h3 id="fastmode">

974 `fastMode`974 `fastMode`

975</h3>975</h3>

976 976

977為可用的工作階段開啟[快速模式](/docs/zh-TW/fast-mode)，用於互動工作，例如快速迭代或即時除錯，您想要速度而不是更高的每令牌成本。您通常不會手動編輯此金鑰：執行 `/fast` 會將 `fastMode: true` 寫入 `~/.claude/settings.json`，再次執行以關閉快速模式會移除金鑰。快速模式僅在 Opus 5 和 Opus 4.8 上執行：從另一個模型開啟會將您切換到 Opus，切換到不支援的模型會關閉它。請參閱[在快速模式開啟時切換模型](/docs/zh-TW/fast-mode#switch-models-while-fast-mode-is-on)。977為可用的工作階段開啟[快速模式](/docs/zh-TW/fast-mode)，用於互動工作，例如快速迭代或實時除錯，您想要以更高的每令牌成本換取速度。您通常不會手動編輯此金鑰：執行 `/fast` 將 `fastMode: true` 寫入 `~/.claude/settings.json`，再次執行以關閉快速模式會移除金鑰。快速模式僅在 Opus 5.5、Opus 5 和 Opus 4.8 上執行：從另一個模型開啟它會將您切換到 Opus，切換到不支援的模型會關閉它。請參閱[在快速模式開啟時切換模型](/docs/zh-TW/fast-mode#switch-models-while-fast-mode-is-on)。

978 978

979* **範圍**: [`任何檔案`](#scopes)979* **範圍**: [`任何檔案`](#scopes)

980* **類型**: 布林值980* **類型**: 布林值

981 * `true`: Claude Code 為可用的工作階段開啟快速模式981 * `true`: Claude Code 為可用的工作階段開啟快速模式

982 * `false`: 快速模式保持關閉982 * `false`: 快速模式保持關閉

983* **預設**: 未設定，因此快速模式關閉983* **預設**: 未設定，因此快速模式已關閉

984* **每個工作階段覆蓋**: [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/zh-TW/env-vars)為一個工作階段關閉快速模式，此金鑰無法將其重新開啟984* **每個工作階段的覆蓋**: [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/zh-TW/env-vars)為一個工作階段關閉快速模式，此金鑰無法將其重新開啟

985 985

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

987{987{

993 `fastModePerSessionOptIn`993 `fastModePerSessionOptIn`

994</h3>994</h3>

995 995

996通常，執行 `/fast` 會將 [`fastMode`](#fastmode) 儲存到人員的使用者設定，因此快速模式在之後每個工作階段的開始時開啟。將此金鑰設定為 `true` 以停止：儲存的 `fastMode: true` 不再在工作階段開始時開啟快速模式，每個人必須在他們想要的每個工作階段中執行 `/fast`。Claude Code 在其檔案中保留 `fastMode` 金鑰，因此關閉此金鑰會恢復舊行為。Team 或 Enterprise 計畫上的擁有者可以透過[伺服器受管設定](/docs/zh-TW/server-managed-settings)在組織範圍內部署它。當受管設定設定此金鑰時，`/fast on` 在互動終端工作階段外被拒絕，並報告您的組織已禁用快速模式。這涵蓋[非互動模式](/docs/zh-TW/headless)、[VS Code 擴充功能](/docs/zh-TW/vs-code)和[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)。996通常，執行 `/fast` 會將 [`fastMode`](#fastmode)儲存到人員的使用者設定，因此快速模式在之後每個工作階段的開始時開啟。將此金鑰設定為 `true` 以停止：儲存的 `fastMode: true` 不再在工作階段開始時開啟快速模式，每個人必須在他們想要的每個工作階段中執行 `/fast`。Claude Code 在其檔案中保留 `fastMode` 金鑰，因此關閉此金鑰會恢復舊行為。

997

998Team 或 Enterprise 計畫的擁有者可以透過[伺服器受管設定](/docs/zh-TW/server-managed-settings)在組織範圍內部署它。當受管設定設定金鑰時，`/fast on` 在互動終端工作階段外被拒絕，並報告您的組織已停用快速模式。這涵蓋[非互動模式](/docs/zh-TW/headless)、[VS Code 擴充功能](/docs/zh-TW/vs-code)和[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)。

997 999

998* **範圍**: [`任何檔案`](#scopes)1000* **範圍**: [`任何檔案`](#scopes)

999* **類型**: 布林值1001* **類型**: 布林值

1007}1009}

1008```1010```

1009 1011

1010請參閱[需要每個工作階段選擇加入](/docs/zh-TW/fast-mode#require-per-session-opt-in)。1012請參閱[要求每個工作階段的選擇加入](/docs/zh-TW/fast-mode#require-per-session-opt-in)。

1011 1013

1012<h3 id="language">1014<h3 id="language">

1013 `language`1015 `language`

1014</h3>1016</h3>

1015 1017

1016預設情況下讓 Claude 以英文以外的語言回應。回應沒有固定清單：Claude Code 將值逐字新增到系統提示中，作為始終以該語言回應的指令，因此任何 Claude 可以讀取的語言名稱都有效。Claude Code 不檢查值，因此拼寫錯誤的名稱會按原樣傳遞給 Claude，而不是產生錯誤。相同的值設定[語音聽寫](/docs/zh-TW/voice-dictation#change-the-dictation-language)的語言，它有固定的[支援聽寫語言](/docs/zh-TW/voice-dictation#change-the-dictation-language)清單，以及自動生成的工作階段標題。1018預設讓 Claude 以英文以外的語言回應。回應沒有固定清單：Claude Code 將值逐字傳遞給 Claude 作為始終以該語言回應的指令，因此任何 Claude 可以讀取的語言名稱都有效。Claude Code 不檢查值，因此拼寫錯誤的名稱會按原樣到達 Claude，而不是產生錯誤。相同的值設定[語音聽寫](/docs/zh-TW/voice-dictation#change-the-dictation-language)的語言，它確實有[支援的聽寫語言](/docs/zh-TW/voice-dictation#change-the-dictation-language)的固定清單，以及自動生成的工作階段標題。

1017 1019

1018* **範圍**: [`任何檔案`](#scopes)1020* **範圍**: [`任何檔案`](#scopes)

1019* **類型**: 字串，任何語言名稱，例如 `"japanese"`、`"spanish"` 或 `"french"`；Claude Code 不驗證它1021* **類型**: 字串，任何語言名稱，例如 `"japanese"`、`"spanish"` 或 `"french"`；Claude Code 不驗證它

1029 `maxEffortLevel`1031 `maxEffortLevel`

1030</h3>1032</h3>

1031 1033

1032限制工作階段可以使用的[努力級別](/docs/zh-TW/model-config#adjust-effort-level)，保留較低級別可用。任何更高級別都改為在限制處執行，包括來自 `/effort`、`/model` 選擇器、`--effort`、[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-TW/env-vars)、技能或子代理的 `effort` frontmatter 或模型自己的預設。Claude Code 在每個請求前自己應用限制，因此它在每個提供者上保留，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry。需要 Claude Code v2.1.267 或更新版本。1034限制工作階段可以使用的[努力級別](/docs/zh-TW/model-config#adjust-effort-level)，保留較低的級別可用。任何更高的級別改為在上限執行，包括來自 `/effort`、`/model` 選擇器、`--effort`、[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-TW/env-vars)、技能或子代理的 `effort` frontmatter 或模型自己的預設。Claude Code 在每個請求之前自己應用上限，因此它在每個提供者上保持，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry。需要 Claude Code v2.1.267 或更新版本。

1033 1035

1034* **範圍**: [`任何檔案`](#scopes)。在受管設定中部署以對組織強制執行。當多個範圍設定限制時，最低的適用，因此在一個範圍中設定的限制無法從另一個範圍提高1036* **範圍**: [`任何檔案`](#scopes)。在受管設定中部署以為組織強制執行。當多個範圍設定上限時，最低的適用，因此在一個範圍中設定的上限無法從另一個範圍提高

1035* **類型**: 字串，為 `"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"` 之一。`"max"` 值不設定限制1037* **類型**: 字串，其中之一 `"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。`"max"` 值設定無上限

1036* **預設**: 未設定，因此無限制適用1038* **預設**: 未設定，因此無上限適用

1037* **對 ultracode 的影響**: 低於 `xhigh` 的限制使[ultracode](#ultracode)在限制適用的模型上不可用1039* **對 ultracode 的影響**: 低於 `xhigh` 的上限使[ultracode](#ultracode)在上限適用的模型上不可用

1038* **每個模型限制**: 將 `maxEffortLevel` 新增到模型的 [`modelSettings`](#modelsettings) 項目。該項目僅在設定來源（例如您的使用者設定或一個[受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)）中設定兩者時替換此金鑰。在那裡設定 `"max"` 以豁免模型不受該來源的限制；Claude Code 仍然應用來自其他來源的限制1040* **每個模型的上限**: 將 `maxEffortLevel` 新增到模型的 [`modelSettings`](#modelsettings) 項目。該項目在設定來源（例如您的使用者設定或一個[受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)）中設定兩者的範圍內僅替換該模型的此金鑰。在那裡設定 `"max"` 以豁免該模型免受該來源的上限；Claude Code 仍然應用來自其他來源的上限

1039 1041

1040此範例將每個模型限制在 `medium`，豁免 Sonnet 4.6：1042此範例將每個模型限制在 `medium`，並豁免 Sonnet 4.6：

1041 1043

1042```json settings.json theme={null}1044```json settings.json theme={null}

1043{1045{

1050}1052}

1051```1053```

1052 1054

1053當您的組織也為模型設定[努力限制](/docs/zh-TW/model-config#organization-effort-limits)時，兩個限制中較低的適用。1055當您的組織也為模型設定[努力限制](/docs/zh-TW/model-config#organization-effort-limits)時，兩個上限中較低的適用。

1054 1056

1055<h3 id="model">1057<h3 id="model">

1056 `model`1058 `model`

1057</h3>1059</h3>

1058 1060

1059設定每個新工作階段使用的模型，因此您不必每次都使用 `/model` 選擇一個。在此設定它不會阻止您在工作階段中期切換。如果您的管理員設定[組織預設模型](/docs/zh-TW/model-config#organization-default-model)以覆蓋使用者選擇，即使您在使用者、專案或本機設定中設定此金鑰，您也會獲得該模型。1061設定每個新工作階段使用的模型，因此您不必每次都使用 `/model` 選擇一個。在此設定它不會阻止您在工作階段中期切換。如果您的管理員設定[組織預設模型](/docs/zh-TW/model-config#organization-default-model)以覆蓋使用者選擇，即使您在使用者、專案或本地設定中設定此金鑰，您也會獲得該模型。

1060 1062

1061* **範圍**: [`任何檔案`](#scopes)1063* **範圍**: [`任何檔案`](#scopes)

1062* **類型**: 字串，模型別名或完整模型 ID1064* **類型**: 字串，模型別名或完整模型 ID

1063* **預設**: 未設定，因此 Claude Code 使用您帳戶的預設模型1065* **預設**: 未設定，因此 Claude Code 使用您帳戶的預設模型

1064* **每個工作階段覆蓋**: `--model` 優先於 [`ANTHROPIC_MODEL`](/docs/zh-TW/env-vars)，兩者優先於此金鑰一個工作階段，包括優先於受管 `model`；[`availableModels`](#availablemodels) 清單仍然適用於選擇1066* **每個工作階段的覆蓋**: `--model` 優先於 [`ANTHROPIC_MODEL`](/docs/zh-TW/env-vars)，兩者優先於此金鑰一個工作階段，包括優先於受管 `model`；[`availableModels`](#availablemodels) 清單仍然適用於選擇

1065 1067

1066```json settings.json theme={null}1068```json settings.json theme={null}

1067{1069{

1075 `modelOverrides`1077 `modelOverrides`

1076</h3>1078</h3>

1077 1079

1078將 Anthropic 模型 ID 對應到提供者特定的模型 ID，例如 Amazon Bedrock 推論設定檔 ARN。每個模型選擇器項目然後在呼叫提供者 API 時使用其對應的值。管理員在[Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/model-config#override-model-ids-per-version)上使用此項以將每個模型版本路由到特定推論設定檔、版本名稱或部署，以進行治理、成本分配或區域路由。1080將 Anthropic 模型 ID 對應到提供者特定的模型 ID，例如 Amazon Bedrock 推論設定檔 ARN。每個模型選擇器項目然後在呼叫提供者 API 時使用其對應的值。管理員在[Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/model-config#override-model-ids-per-version)上使用此項以將每個模型版本路由到特定的推論設定檔、版本名稱或部署，以進行治理、成本分配或區域路由。

1079 1081

1080* **範圍**: [`任何檔案`](#scopes)1082* **範圍**: [`任何檔案`](#scopes)

1081* **類型**: 將模型 ID 對應到提供者模型 ID 的物件1083* **類型**: 將模型 ID 對應到提供者模型 ID 的物件

1097 `modelPicker`1099 `modelPicker`

1098</h3>1100</h3>

1099 1101

1100列出 `/model` 選擇器提供的模型，按您寫入的順序和您選擇的標籤下，因此選擇器列出您的組織執行的模型，在內建陣容之後或代替它。每行的 `model` 逐字取用，因此它接受 `--model` 接受的任何內容：別名，例如 `opus`、Anthropic 模型 ID 或 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 閘道的提供者格式 ID。需要 Claude Code v2.1.242 或更新版本。1102列出 `/model` 選擇器提供的模型，按您寫入的順序和您選擇的標籤下，因此選擇器列出您的組織執行的模型，在內建陣容之後或代替它。每行的 `model` 逐字取用，因此它接受 `--model` 接受的任何內容：別名（例如 `opus`）、Anthropic 模型 ID 或 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 閘道的提供者格式 ID。需要 Claude Code v2.1.242 或更新版本。

1101 1103

1102* **範圍**: [`使用者或受管`](#scopes)。Claude Code 從受管設定、`--settings` 和使用者設定讀取金鑰，忽略專案和本機設定中的金鑰，因此您複製的儲存庫無法重新標籤選擇器。這三個中最高的設定金鑰的提供整個陣容，Claude Code 永遠不會合併來自兩個來源的陣容。1104* **範圍**: [`使用者或受管`](#scopes)。Claude Code 從受管設定、`--settings` 和使用者設定讀取金鑰，並在專案和本地設定中忽略它，因此您複製的儲存庫無法重新標籤選擇器。這三個中最高的設定金鑰提供整個陣容，Claude Code 永遠不會合併來自兩個來源的陣容。

1103* **類型**: 具有 `options` 陣列和可選 `replaceBuiltInOptions` 布林值的物件1105* **類型**: 具有 `options` 陣列的物件和可選的 `replaceBuiltInOptions` 布林值

1104* **預設**: 未設定，因此選擇器顯示內建陣容1106* **預設**: 未設定，因此選擇器顯示內建陣容

1105 1107

1106此範例在內建陣容之後新增兩個 Bedrock 部署，在您的團隊識別的名稱下：1108此範例在內建陣容之後新增兩個 Bedrock 部署，在您的團隊識別的名稱下：

1135| `options` | 行的陣列，每行具有必需的 `model` 和可選的 `label` 和 `description` | 選擇器顯示的行，按此順序，除了灰顯的行移到底部。沒有 `label` 時，Claude Code 用它知道的模型的內建名稱標題行，或模型 ID 否則，沒有 `description` 時它寫通用第二行 |1137| `options` | 行的陣列，每行具有必需的 `model` 和可選的 `label` 和 `description` | 選擇器顯示的行，按此順序，除了灰顯的行移到底部。沒有 `label` 時，Claude Code 用它知道的模型的內建名稱標題行，或模型 ID 否則，沒有 `description` 時它寫通用第二行 |

1137 1139

1138開啟 `replaceBuiltInOptions` 時，Claude Code 隱藏每個其他行：內建陣容、它為 [`availableModels`](#availablemodels) 項目新增的行、[閘道發現](/docs/zh-TW/llm-gateway-protocol#model-discovery)找到的模型和 [`ANTHROPIC_CUSTOM_MODEL_OPTION`](/docs/zh-TW/model-config#add-a-custom-model-option)。關閉時，Claude Code 跳過內建陣容已涵蓋的列出模型。標籤改變選擇器顯示的內容，不是 Claude Code 執行的模型。1140開啟 `replaceBuiltInOptions` 時，Claude Code 隱藏每個其他行：內建陣容、它為 [`availableModels`](#availablemodels) 項目新增的行、[閘道發現](/docs/zh-TW/llm-gateway-protocol#model-discovery)找到的模型和 [`ANTHROPIC_CUSTOM_MODEL_OPTION`](/docs/zh-TW/model-config#add-a-custom-model-option)。關閉時，Claude Code 跳過內建陣容已涵蓋的列出模型。標籤改變選擇器顯示的內容，而不是 Claude Code 執行的模型。

1139 1141

1140[`availableModels`](#availablemodels) 允許清單仍然適用於這些行。在將列出的模型新增到允許清單之前，請閱讀[合併行為](/docs/zh-TW/model-config#merge-behavior)：特定模型 ID 縮小其系列的萬用字元項目。Claude Code 也在顯示選擇器前檢查每行與工作階段：1142[`availableModels`](#availablemodels) 允許清單仍然適用於這些行。在將列出的模型新增到允許清單之前，請閱讀[合併行為](/docs/zh-TW/model-config#merge-behavior)：特定模型 ID 縮小其系列的萬用字元項目。Claude Code 也在顯示選擇器之前根據工作階段檢查每行：

1141 1143

1142* **已刪除**: Claude Code 無法提供的行，例如已停用的模型或您的組織無法存取的模型1144* **已刪除**: Claude Code 無法提供的行，例如已停用的模型或您的組織無法存取的模型

1143* **灰顯**: 您還無法選擇的行，顯示原因1145* **灰顯**: 您還無法選擇的行，顯示原因

1144* **沒有行倖存**: Claude Code 保留內建陣容，按允許清單過濾如常1146* **沒有行倖存**: Claude Code 保留內建陣容，由允許清單篩選如常

1145 1147

1146Claude Code 刪除它無法解析的行，保留其餘的。請參閱[修復損壞的設定檔](/docs/zh-TW/settings#fix-a-broken-settings-file)。1148Claude Code 刪除它無法解析的行，並保留其餘的。請參閱[修復損壞的設定檔](/docs/zh-TW/settings#fix-a-broken-settings-file)。

1147 1149

1148<h3 id="modelpricing">1150<h3 id="modelpricing">

1149 `modelPricing`1151 `modelPricing`

1150</h3>1152</h3>

1151 1153

1152按您的組織支付的費率而不是清單價格報告支出。當您的組織有合約費率時設定，因此開發人員看到的美元數字符合您的帳單。Claude Code 在 `/usage`、[狀態行](/docs/zh-TW/statusline)、Agent SDK 的 `total_cost_usd`、[`--max-budget-usd`](/docs/zh-TW/cli-reference) 限制和 [OpenTelemetry](/docs/zh-TW/monitoring-usage) 成本指標和事件中應用費率。您提供費率：Claude Code 不從您的合約或 Claude 主控台讀取它們。需要 Claude Code v2.1.242 或更新版本。1154以您的組織支付的費率而不是列表價格報告支出。當您的組織有合約費率時設定它，因此開發人員看到的美元數字符合您的帳單。Claude Code 在 `/usage`、[狀態行](/docs/zh-TW/statusline)、Agent SDK 的 `total_cost_usd`、[`--max-budget-usd`](/docs/zh-TW/cli-reference) 限制和 [OpenTelemetry](/docs/zh-TW/monitoring-usage) 成本指標和事件中應用費率。您提供費率：Claude Code 不從您的合約或 Claude 主控台讀取它們。需要 Claude Code v2.1.242 或更新版本。

1153 1155

1154* **範圍**: [`受管`](#scopes)。透過伺服器受管設定、MDM 原則、`managed-settings.json` 檔案或[原則協助程式](/docs/zh-TW/managed-settings#compute-the-policy-with-a-helper-program)部署金鑰。Claude Code 忽略它在使用者、專案和本機設定中、在 `--settings` 中，以及在 Windows 中的使用者可寫[HKCU 登錄](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy)中。使用伺服器受管設定，每個工作階段按清單價格報告成本，直到該工作階段的[設定擷取](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)已確認設定。嵌入 Claude Code 的主機應用程式，設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars)，可以透過 SDK [`managedSettings`](/docs/zh-TW/agent-sdk/typescript#options) 選項提供自己的表格，Claude Code 僅在沒有受管來源設定金鑰時使用，且僅在 Claude Code v2.1.246 或更新版本中。1156* **範圍**: [`受管`](#scopes)。透過伺服器受管設定、MDM 原則、`managed-settings.json` 檔案或[原則協助程式](/docs/zh-TW/managed-settings#compute-the-policy-with-a-helper-program)部署金鑰。Claude Code 在使用者、專案和本地設定中、在 `--settings` 中以及在 Windows 中的使用者可寫[HKCU 登錄](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy)中忽略它。使用伺服器受管設定時，每個工作階段以列表價格報告成本，直到該工作階段的[設定擷取](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)已確認設定。嵌入 Claude Code 的主機應用程式，設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars)，可以透過 SDK [`managedSettings`](/docs/zh-TW/agent-sdk/typescript#options) 選項提供自己的表格，Claude Code 僅在沒有受管來源設定金鑰時以及僅在 Claude Code v2.1.246 或更新版本中使用。

1155* **類型**: 具有可選 `multiplier` 和可選 `overrides` 對應的物件1157* **類型**: 具有可選 `multiplier` 和可選 `overrides` 對應的物件

1156* **預設**: 未設定，因此 Claude Code 報告清單價格，除非主機應用程式提供表格1158* **預設**: 未設定，因此 Claude Code 報告列表價格，除非主機應用程式提供表格

1159

1160單獨設定 `multiplier` 以獲得統一折扣或加價，單獨設定 `overrides` 以獲得每個模型費率，或兩者。

1157 1161

1158為 Sonnet 4.6 設定合約費率，然後將每個數字（包括 Sonnet 行）減少 15%。單獨設定 `multiplier` 以獲得統一折扣，單獨設定 `overrides` 以獲得每個模型費率，或兩者：1162此範例為 Sonnet 4.6 設定合約費率，然後將每個數字（包括 Sonnet 行）減少 15%：

1159 1163

1160```json managed-settings.json theme={null}1164```json managed-settings.json theme={null}

1161{1165{

1173}1177}

1174```1178```

1175 1179

1176將 `multiplier` 設定為 1 以上，最多 10，以標記每個數字。標記需要 Claude Code v2.1.271 或更新版本。較早版本會忽略 `multiplier` 超過 1 並顯示警告，保留設定的其餘部分。1180將 `multiplier` 設定為 1 以上，最多 10，以標記每個數字。加價需要 Claude Code v2.1.271 或更新版本。較早的版本忽略 `multiplier` 超過 1 並帶有警告，並保留設定的其餘部分。

1177 1181

1178如需步驟，包括如何確認費率有效，請參閱[按合約費率報告支出](/docs/zh-TW/costs#report-spend-at-your-contracted-rates)。1182如需步驟，包括如何確認費率有效，請參閱[以您的合約費率報告支出](/docs/zh-TW/costs#report-spend-at-your-contracted-rates)。

1179 1183

1180<span id="modelpricing-multiplier" />1184<span id="modelpricing-multiplier" />

1181 1185

1186</h4>1190</h4>

1187 1191

1188| 欄位 | 類型 | 它的作用 |1192| 欄位 | 類型 | 它的作用 |

1189| :----------- | :----------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |1193| :----------- | :---------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

1191| `overrides` | 將模型 ID 對應到具有 `input`、`output`、`cacheRead` 和 `cacheWrite` 的費率物件的對應，每個 0 到 10000 | 該模型的美元每百萬令牌費率，全部四個必需。`cacheWrite` 涵蓋五分鐘和一小時快取寫入。請參閱[`modelPricing` 行適用於哪些模型](#which-models-a-modelpricing-row-applies-to) |1195| `overrides` | 模型 ID 對應到具有 `input`、`output`、`cacheRead` 和 `cacheWrite` 的費率物件的對應，每個 0 到 10000 | 該模型的美元每百萬令牌費率，全部四個必需。`cacheWrite` 涵蓋五分鐘和一小時快取寫入。請參閱[`modelPricing` 行適用於哪些模型](#which-models-a-modelpricing-row-applies-to) |

1192 1196

1193Claude Code 完全按您寫入的方式使用行的費率，不新增快速模式附加費或[僅限美國推論費率](https://platform.claude.com/docs/en/about-claude/pricing)。如果您也設定 `multiplier`，Claude Code 在行的費率之上應用它。Claude Code 刪除具有無法解析的費率或無法解析的 `multiplier` 的行，保留其餘的；請參閱[修復損壞的設定檔](/docs/zh-TW/settings#fix-a-broken-settings-file)。1197Claude Code 完全按照您寫入的方式使用行的費率，不新增快速模式加價或[僅限美國推論費率](https://platform.claude.com/docs/en/about-claude/pricing)。如果您也設定 `multiplier`，Claude Code 在行的費率之上應用它。Claude Code 刪除具有它無法解析的費率或 `multiplier` 的行，並保留其餘的；請參閱[修復損壞的設定檔](/docs/zh-TW/settings#fix-a-broken-settings-file)。

1194 1198

1195<h4 id="which-models-a-modelpricing-row-applies-to">1199<h4 id="which-models-a-modelpricing-row-applies-to">

1196 `modelPricing` 行適用於哪些模型1200 `modelPricing` 行適用於哪些模型

1198 1202

1199Claude Code 從行的金鑰決定行適用於哪些模型：1203Claude Code 從行的金鑰決定行適用於哪些模型：

1200 1204

1201* **內建模型的 ID**: Claude Code 本身為內建模型使用的金鑰，無論該金鑰是模型自己的 ID，例如 `claude-sonnet-4-6`，或其 Bedrock、Agent Platform 或 Foundry ID。Claude Code 將行應用於該模型的每個日期快照 ID 和提供者特定 ID。1205* **內建模型的 ID**: Claude Code 本身為內建模型使用的金鑰，無論該金鑰是模型自己的 ID（例如 `claude-sonnet-4-6`）還是其 Bedrock、Agent Platform 或 Foundry ID。Claude Code 將行應用於該模型的每個日期快照 ID 和提供者特定 ID。

1202* **任何其他金鑰**: 不是內建模型 ID 的金鑰，例如閘道模型別名。Claude Code 將行應用於該一個 ID 只。當模型 ID 完全符合您的一個金鑰，也落在由內建模型 ID 鍵入的行下時，Claude Code 使用完全符合。1206* **任何其他金鑰**: 不是內建模型 ID 的金鑰，例如閘道模型別名。Claude Code 僅將行應用於該一個 ID。當模型 ID 完全符合您的一個金鑰，也落在由內建模型 ID 鍵入的行下時，Claude Code 使用完全符合。

1203* **Bedrock 應用程式推論設定檔**: Claude Code 透過您的 [`modelOverrides`](#modeloverrides) 對應或 [`bedrock:GetInferenceProfile` 查詢](/docs/zh-TW/amazon-bedrock#iam-configuration)將設定檔解析為它路由到的模型後，Claude Code 將該模型的行應用於設定檔。1207* **Bedrock 應用程式推論設定檔**: 一旦 Claude Code 透過您的 [`modelOverrides`](#modeloverrides) 對應或 [`bedrock:GetInferenceProfile` 查詢](/docs/zh-TW/amazon-bedrock#iam-configuration)將設定檔解析為它路由到的模型，Claude Code 將該模型的行應用於設定檔。

1204 1208

1205<h3 id="modelsettings">1209<h3 id="modelsettings">

1206 `modelSettings`1210 `modelSettings`

1207</h3>1211</h3>

1208 1212

1209為您使用的每個模型儲存[努力級別](/docs/zh-TW/model-config#adjust-effort-level)。在機器上的互動工作階段中，當您使用 `/effort` 或 [VS Code 擴充功能的模型選擇器](/docs/zh-TW/vs-code#use-the-prompt-box)的努力滑塊將 `low`、`medium`、`high` 或 `xhigh` 儲存為預設時，Claude Code 在您使用的模型下將該級別寫入此處，因此您很少手動編輯此金鑰。[`effortLevel`](#effortlevel) 項目列出 `/effort` 僅適用於該工作階段的工作階段。需要 Claude Code v2.1.251 或更新版本。1213為您使用的每個模型儲存[努力級別](/docs/zh-TW/model-config#adjust-effort-level)。需要 Claude Code v2.1.251 或更新版本。

1214

1215在機器上的互動工作階段中，當您使用 `/effort` 或 `/model` 選擇器的努力滑塊將 `low`、`medium`、`high` 或 `xhigh` 儲存為預設時，Claude Code 在您使用的模型下在此處寫入該級別，因此您很少自己編輯此金鑰。當您在 [VS Code 擴充功能的模型選擇器](/docs/zh-TW/vs-code#use-the-prompt-box)中選擇其中一個級別時，Claude Code 以相同方式在此處儲存它。[`effortLevel`](#effortlevel) 項目列出 `/effort` 僅適用於該工作階段的工作階段。

1210 1216

1211手動編輯金鑰以變更或移除您儲存的級別。1217手動編輯金鑰以變更或移除您儲存的級別。

1212 1218

1213此處模型的 `effortLevel` 優先於同一設定檔中的頂級 [`effortLevel`](#effortlevel)。跨檔案，Claude Code 分別解析每個模型：最高優先順序[設定檔](/docs/zh-TW/settings#settings-precedence)設定該模型的 `effortLevel` 或頂級 `effortLevel` 決定，因此受管設定中的 `effortLevel` 優先於您在使用者設定中儲存的級別。[調整努力級別](/docs/zh-TW/model-config#adjust-effort-level)列出還可以覆蓋儲存級別的內容，例如啟動時的 `--effort`。1219此處模型的 `effortLevel` 優先於同一設定檔中的頂級 [`effortLevel`](#effortlevel)。跨檔案，Claude Code 分別解析每個模型：最高優先順序[設定檔](/docs/zh-TW/settings#settings-precedence)設定該模型的 `effortLevel` 或[適用於該模型](#effortlevel)的頂級 `effortLevel` 決定，因此受管設定中的 `effortLevel` 優先於您在使用者設定中儲存的級別。[調整努力級別](/docs/zh-TW/model-config#adjust-effort-level)列出還可以覆蓋儲存級別的內容，例如啟動時的 `--effort`。

1214 1220

1215要限制一個模型的努力而不是設定其級別，將 [`maxEffortLevel`](#maxeffortlevel) 欄位新增到該模型的項目。欄位需要 Claude Code v2.1.267 或更新版本。1221要限制一個模型的努力而不是設定其級別，將 [`maxEffortLevel`](#maxeffortlevel) 欄位新增到該模型的項目。該欄位需要 Claude Code v2.1.267 或更新版本。

1216 1222

1217* **範圍**: [`任何檔案`](#scopes)1223* **範圍**: [`任何檔案`](#scopes)

1218* **類型**: 將模型名稱對應到具有 `effortLevel` 欄位（`"low"`、`"medium"`、`"high"` 或 `"xhigh"` 之一）、[`maxEffortLevel`](#maxeffortlevel) 欄位或兩者的物件的物件1224* **類型**: 將模型名稱對應到具有 `effortLevel` 欄位（其中之一 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`）、[`maxEffortLevel`](#maxeffortlevel) 欄位或兩者的物件的物件

1219* **預設**: 未設定1225* **預設**: 未設定

1220 1226

1221Claude Code 在模型的規範名稱下寫入每個項目，例如 `claude-opus-5`，並將該模型的別名、日期後綴、`[1m]` 和識別的提供者特定 ID 符合到相同項目。1227Claude Code 在模型的規範名稱下寫入每個項目，例如 `claude-opus-5-5`，並將該模型的別名、日期後綴、`[1m]` 和識別的提供者特定 ID 符合到同一項目。

1222 1228

1223此範例將 Opus 5 保留在 `medium`，而其他模型使用其自己的儲存或預設級別：1229此範例將 Opus 5.5 保持在 `high`，而其他模型使用它們自己的儲存或預設級別：

1224 1230

1225```json settings.json theme={null}1231```json settings.json theme={null}

1226{1232{

1227 "modelSettings": {1233 "modelSettings": {

1228 "claude-opus-5": {1234 "claude-opus-5-5": {

1229 "effortLevel": "medium"1235 "effortLevel": "high"

1230 }1236 }

1231 }1237 }

1232}1238}

1238 `outputStyle`1244 `outputStyle`

1239</h3>1245</h3>

1240 1246

1241按名稱選擇[輸出樣式](/docs/zh-TW/output-styles)。輸出樣式是改變 Claude 角色、語調和輸出格式的儲存指令集，例如內建的 Explanatory 和 Learning 樣式或您自己寫的。1247按名稱選擇[輸出樣式](/docs/zh-TW/output-styles)。輸出樣式是一組儲存的指令，改變 Claude 的角色、語調和輸出格式，例如內建的解釋性和學習樣式或您自己寫的。

1242 1248

1243如果您在工作階段期間變更此金鑰，Claude 從您的下一條訊息開始使用新樣式。如需該訊息在提示快取中的成本，請參閱[變更輸出樣式](/docs/zh-TW/prompt-caching#changing-output-style)。在 v2.1.251 之前，編輯僅在您執行 `/clear` 或開始新工作階段後適用。1249如果您在工作階段期間變更此金鑰，Claude 從您的下一條訊息開始使用新樣式。如需該訊息在提示快取中的成本，請參閱[變更輸出樣式](/docs/zh-TW/prompt-caching#changing-output-style)。在 v2.1.251 之前，編輯僅在您執行 `/clear` 或開始新工作階段後適用。

1244 1250

1246* **類型**: 字串，[內建](/docs/zh-TW/output-styles#built-in-output-styles)或[自訂](/docs/zh-TW/output-styles#create-a-custom-output-style)輸出樣式的名稱1252* **類型**: 字串，[內建](/docs/zh-TW/output-styles#built-in-output-styles)或[自訂](/docs/zh-TW/output-styles#create-a-custom-output-style)輸出樣式的名稱

1247* **預設**: 未設定，因此 Claude Code 使用預設樣式1253* **預設**: 未設定，因此 Claude Code 使用預設樣式

1248 1254

1249此範例選擇內建的 Explanatory 樣式，在任務之間新增教育見解：1255此範例選擇內建的解釋性樣式，在任務之間新增教育見解：

1250 1256

1251```json settings.json theme={null}1257```json settings.json theme={null}

1252{1258{

1258 `promptCacheTtl`1264 `promptCacheTtl`

1259</h3>1265</h3>

1260 1266

1261選擇[提示快取](/docs/zh-TW/prompt-caching)保留主要對話的時間長度。此金鑰適用於您的互動、`-p` 和 Agent SDK 輪，以及 Claude Code 與它們內聯執行的協助程式。一小時的生命週期在較長的中斷中保持快取溫暖，API [在五分鐘生命週期時以更高費率計費每個快取寫入](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。需要 Claude Code v2.1.242 或更新版本。1267選擇[提示快取](/docs/zh-TW/prompt-caching)保持主要對話多長時間。此金鑰適用於您的互動、`-p` 和 Agent SDK 輪，以及 Claude Code 與它們內聯執行的協助程式。一小時的生命週期在較長的中斷中保持快取溫暖，API [以比五分鐘生命週期更高的費率計費每個快取寫入](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。需要 Claude Code v2.1.242 或更新版本。

1262 1268

1263* **範圍**: [`任何檔案`](#scopes)1269* **範圍**: [`任何檔案`](#scopes)

1264* **類型**: 字串，為以下之一：1270* **類型**: 字串，其中之一：

1265 * `"5m"`: 快取保留五分鐘1271 * `"5m"`: 快取保持五分鐘

1266 * `"1h"`: 快取保留一小時1272 * `"1h"`: 快取保持一小時

1267* **預設**: 未設定，因此每個主要對話請求獲得[其預設生命週期](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets)1273* **預設**: 未設定，因此每個主要對話請求獲得[其預設生命週期](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets)

1268* **每個工作階段覆蓋**: [`FORCE_PROMPT_CACHING_5M`](/docs/zh-TW/env-vars)優先於所有其他，然後 [`CLAUDE_CODE_PROMPT_CACHE_TTL`](/docs/zh-TW/env-vars)，然後此金鑰，最後 [`ENABLE_PROMPT_CACHING_1H`](/docs/zh-TW/env-vars)1274* **每個工作階段的覆蓋**: [`FORCE_PROMPT_CACHING_5M`](/docs/zh-TW/env-vars)優先於所有其他，然後 [`CLAUDE_CODE_PROMPT_CACHE_TTL`](/docs/zh-TW/env-vars)，然後此金鑰，最後 [`ENABLE_PROMPT_CACHING_1H`](/docs/zh-TW/env-vars)

1269 1275

1270此範例將主要對話保留在一小時生命週期，子代理保留在五分鐘：1276此範例將主要對話保持在一小時生命週期，並將子代理保持在五分鐘：

1271 1277

1272```json settings.json theme={null}1278```json settings.json theme={null}

1273{1279{

1296}1302}

1297```1303```

1298 1304

1299編輯僅改變您看到的內容，不改變模型生成的內容。要減少思考支出，[降低預算或禁用思考](/docs/zh-TW/model-config#extended-thinking)。1305編輯僅改變您看到的內容，而不是模型生成的內容。要減少思考支出，[降低預算或停用思考](/docs/zh-TW/model-config#extended-thinking)。

1300 1306

1301<h3 id="subagentpromptcachettl">1307<h3 id="subagentpromptcachettl">

1302 `subagentPromptCacheTtl`1308 `subagentPromptCacheTtl`

1303</h3>1309</h3>

1304 1310

1305選擇[提示快取](/docs/zh-TW/prompt-caching)保留 Claude Code 在主要對話外進行的請求的時間長度。此金鑰適用於[子代理](/docs/zh-TW/sub-agents)、[工作流程](/docs/zh-TW/workflows)和 Claude Code 自己的背景和協助程式請求，例如壓縮和工作階段標題。一小時的生命週期在較長的中斷中保持快取溫暖，API [在五分鐘生命週期時以更高費率計費每個快取寫入](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。需要 Claude Code v2.1.242 或更新版本。1311選擇[提示快取](/docs/zh-TW/prompt-caching)保持 Claude Code 在主要對話外進行的請求多長時間。此金鑰適用於[子代理](/docs/zh-TW/sub-agents)、[工作流程](/docs/zh-TW/workflows)和 Claude Code 自己的背景和協助程式請求，例如壓縮和工作階段標題。一小時的生命週期在較長的中斷中保持快取溫暖，API [以比五分鐘生命週期更高的費率計費每個快取寫入](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。需要 Claude Code v2.1.242 或更新版本。

1306 1312

1307* **範圍**: [`任何檔案`](#scopes)1313* **範圍**: [`任何檔案`](#scopes)

1308* **類型**: 字串，為以下之一：1314* **類型**: 字串，其中之一：

1309 * `"5m"`: 快取保留五分鐘1315 * `"5m"`: 快取保持五分鐘

1310 * `"1h"`: 快取保留一小時1316 * `"1h"`: 快取保持一小時

1311* **預設**: 未設定，因此這些請求中的每一個獲得[其預設生命週期](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets)1317* **預設**: 未設定，因此這些請求中的每一個獲得[其預設生命週期](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets)

1312* **每個工作階段覆蓋**: [`FORCE_PROMPT_CACHING_5M`](/docs/zh-TW/env-vars)優先於所有其他，然後 [`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`](/docs/zh-TW/env-vars)，然後此金鑰，然後 [`ENABLE_PROMPT_CACHING_1H`](/docs/zh-TW/env-vars)，要求每個請求的一小時生命週期。如需子代理自己的 frontmatter 值排名的位置，請參閱[自己選擇 TTL](/docs/zh-TW/prompt-caching#choose-the-ttl-yourself)1318* **每個工作階段的覆蓋**: [`FORCE_PROMPT_CACHING_5M`](/docs/zh-TW/env-vars)優先於所有其他，然後 [`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`](/docs/zh-TW/env-vars)，然後此金鑰，然後 [`ENABLE_PROMPT_CACHING_1H`](/docs/zh-TW/env-vars)，要求每個請求的一小時生命週期。如需子代理自己的 frontmatter 值排名的位置，請參閱[自己選擇 TTL](/docs/zh-TW/prompt-caching#choose-the-ttl-yourself)

1313 1319

1314此範例為子代理和主要對話外的其他請求提供一小時生命週期：1320此範例為子代理和主要對話外的其他請求提供一小時生命週期：

1315 1321

1330* **範圍**: [`任何檔案`](#scopes)。在 `/config` 中顯示為**訊息被標記時切換模型**。1336* **範圍**: [`任何檔案`](#scopes)。在 `/config` 中顯示為**訊息被標記時切換模型**。

1331* **類型**: 布林值1337* **類型**: 布林值

1332 * `true`: Claude Code 切換到備用模型並繼續1338 * `true`: Claude Code 切換到備用模型並繼續

1333 * `false`: 在互動工作階段中，Claude Code 暫停以便您可以在切換和編輯提示之間選擇；在無法顯示對話的地方，例如 `-p` 執行，標記的請求以錯誤結束1339 * `false`: 在互動工作階段中，Claude Code 暫停以便您可以在切換和編輯提示之間選擇；在無法顯示對話框的地方，例如 `-p` 執行，標記的請求以錯誤結束

1334* **預設**: `true`，自動切換1340* **預設**: `true`，自動切換

1335 1341

1336```json settings.json theme={null}1342```json settings.json theme={null}

1345 `ultracode`1351 `ultracode`

1346</h3>1352</h3>

1347 1353

1348為[ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)可用的工作階段開始。開啟時，Claude 為每個實質任務規劃工作流程，而不是等待您要求。Claude 僅在[動態工作流程](/docs/zh-TW/workflows)為您啟用、您的模型支援 `xhigh` 努力且無[努力限制](/docs/zh-TW/model-config#organization-effort-limits)低於 `xhigh` 適用時規劃工作流程。無論如何，`ultracode: true` 在 `xhigh` 努力或當努力限制更低時在限制處執行工作階段。Claude Code 讀取此金鑰但永遠不寫入它：`/effort ultracode` 僅為目前工作階段開啟 ultracode。1354使用[ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)啟動工作階段。開啟時，Claude 為每個實質性任務規劃工作流程，而不是等待您要求。Claude 僅在為您啟用[動態工作流程](/docs/zh-TW/workflows)、您的模型支援 `xhigh` 努力且沒有[努力上限](/docs/zh-TW/model-config#organization-effort-limits)低於 `xhigh` 時規劃工作流程。無論如何，`ultracode: true` 在 `xhigh` 努力或當努力上限更低時在上限執行工作階段。Claude Code 讀取此金鑰但永遠不寫入它：`/effort ultracode` 僅為目前工作階段開啟 ultracode。

1349 1355

1350* **範圍**: [`任何檔案`](#scopes)1356* **範圍**: [`任何檔案`](#scopes)

1351* **類型**: 布林值1357* **類型**: 布林值

1352 * `true`: 工作階段在 `xhigh` 努力開始，當動態工作流程為您啟用、您的模型支援 `xhigh` 且無努力限制低於 `xhigh` 時，ultracode 開啟1358 * `true`: 工作階段以 `xhigh` 努力開始，當為您啟用動態工作流程、您的模型支援 `xhigh` 且沒有努力上限低於 `xhigh` 時，ultracode 開啟

1353 * `false`: 工作階段開始時 ultracode 關閉1359 * `false`: 工作階段以 ultracode 關閉開始

1354* **預設**: 未設定，因此 ultracode 關閉1360* **預設**: 未設定，因此 ultracode 已關閉

1355* **每個工作階段覆蓋**: `/effort ultracode` 為一個工作階段開啟 ultracode，不需此金鑰。`--effort ultracode` 也是，需要 Claude Code v2.1.203 或更新版本1361* **每個工作階段的覆蓋**: `/effort ultracode` 在沒有此金鑰的情況下為一個工作階段開啟 ultracode。`--effort ultracode` 標誌也為一個工作階段開啟它，需要 Claude Code v2.1.203 或更新版本

1356 1362

1357```json settings.json theme={null}1363```json settings.json theme={null}

1358{1364{

1360}1366}

1361```1367```

1362 1368

1363Ultracode 在 `xhigh` 努力執行工作階段，優先於 `effortLevel` 和 [`modelSettings`](#modelsettings) 項目。如果[努力限制](/docs/zh-TW/model-config#organization-effort-limits)低於 `xhigh` 適用於模型，例如 [`maxEffortLevel`](#maxeffortlevel) 設定，工作階段改為在限制處執行，ultracode 保持關閉。Claude 然後不自己規劃工作流程，`/effort` 不提供 `ultracode`。Agent SDK `apply_flag_settings` 控制請求也接受金鑰。1369Ultracode 在 `xhigh` 努力執行工作階段，優先於 `effortLevel` 和 [`modelSettings`](#modelsettings) 項目。如果[努力上限](/docs/zh-TW/model-config#organization-effort-limits)低於 `xhigh` 適用於模型，例如 [`maxEffortLevel`](#maxeffortlevel) 設定，工作階段改為在上限執行，ultracode 保持關閉。Claude 然後不自己規劃工作流程，`/effort` 不提供 `ultracode`。Agent SDK `apply_flag_settings` 控制請求也接受金鑰。

1364 1370

1365<h2 id="permission-settings">1371<h2 id="permission-settings">

1366 權限設定1372 權限設定

1915}1921}

1916```1922```

1917 1923

1918Claude Code 在 OS 沙箱邊界強制執行這些清單，所以它們適用於沙箱化命令啟動的每個子程序，例如 `kubectl`、`terraform` 或 `npm`，不僅適用於 Claude 的檔案工具。Claude Code 將您的 [permission rules](/docs/zh-TW/sandboxing#permission-rules) 新增到相同的清單：`Edit` 允許和拒絕規則到 `allowWrite` 和 `denyWrite`、`Read` 拒絕規則到 `denyRead`，以及 `WebFetch(domain:...)` 允許和拒絕規則到 [`network`](#sandbox-network) 網域清單。1924Claude Code 在 OS 沙箱邊界強制執行這些清單，所以它們適用於沙箱化命令啟動的每個子程序，例如 `kubectl`、`terraform` 或 `npm`。Claude Code 將您的 [permission rules](/docs/zh-TW/sandboxing#permission-rules) 新增到相同的清單：`Edit` 允許和拒絕規則到 `allowWrite` 和 `denyWrite`、`Read` 拒絕規則到 `denyRead`，以及 `WebFetch(domain:...)` 允許和拒絕規則到 [`network`](#sandbox-network) 網域清單。

1919 1925

1920除非設定了僅受管的鎖定，Claude Code 合併工作階段載入的設定檔案中的每個清單。[`allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly) 將 `allowRead` 限制為受管設定中的項目，[`allowManagedDomainsOnly`](#sandbox-network-allowmanageddomainsonly) 對允許的網域執行相同操作。1926除非設定了僅受管的鎖定，Claude Code 合併工作階段載入的設定檔案中的每個清單。[`allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly) 將 `allowRead` 限制為受管設定中的項目，[`allowManagedDomainsOnly`](#sandbox-network-allowmanageddomainsonly) 對允許的網域執行相同操作。

1921 1927

2250 `sandbox.credentials`2256 `sandbox.credentials`

2251</h3>2257</h3>

2252 2258

2253宣告認證檔案和環境變數以 [protect from sandboxed commands](/docs/zh-TW/sandboxing#protect-credentials)。每個項目命名檔案 `path` 或變數 `name` 和 `mode`：`deny` 在沙箱內隱藏認證，`mask` 向沙箱化命令顯示佔位符，同時 [sandbox proxy](/docs/zh-TW/sandboxing#mask-credentials) 在出站請求上替換真實值。Claude Code 僅保護您列出的項目；沒有內建認證拒絕清單。需要 Claude Code v2.1.187 或更新版本。2259宣告認證檔案和環境變數以 [protect from sandboxed commands](/docs/zh-TW/sandboxing#protect-credentials)。每個項目命名檔案 `path` 或變數 `name` 和 `mode`：`deny` 在沙箱內隱藏認證，`mask` 向沙箱化命令顯示佔位符，同時 [sandbox proxy](/docs/zh-TW/sandboxing#mask-credentials) 在出站請求上替換真實值。Claude Code 僅保護您列出的項目；沒有內建認證拒絕清單。

2254 2260

2255* **Scope**: [`Any file`](#scopes)。Claude Code 僅從使用者設定、受管設定和 `--settings` 旗標接受 `mask` 項目、`allowPlaintextInject`、`awsPairs` 和 `sigv4`。2261* **Scope**: [`Any file`](#scopes)。Claude Code 僅從使用者設定、受管設定和 `--settings` 旗標接受 `mask` 項目、`allowPlaintextInject`、`awsPairs` 和 `sigv4`。

2256* **Type**: 物件，包含 `files`、`envVars`、`allowPlaintextInject`、`awsPairs` 和 `sigv4`2262* **Type**: 物件，包含 `files`、`envVars`、`allowPlaintextInject`、`awsPairs` 和 `sigv4`

2269}2275}

2270```2276```

2271 2277

2272`deny` 檔案保護是檔案系統層的一部分，所以當您 [disable filesystem isolation](/docs/zh-TW/sandboxing#disable-filesystem-isolation) 時不適用；環境變數保護仍然適用。需要 Claude Code v2.1.187 或更新版本。2278`deny` 檔案保護是檔案系統層的一部分，所以當您 [disable filesystem isolation](/docs/zh-TW/sandboxing#disable-filesystem-isolation) 時不適用；環境變數保護仍然適用。

2273 2279

2274<h4 id="invalid-credential-entries-in-managed-settings">2280<h4 id="invalid-credential-entries-in-managed-settings">

2275 受管設定中的無效認證項目2281 受管設定中的無效認證項目

2287 `sandbox.credentials.files`2293 `sandbox.credentials.files`

2288</h3>2294</h3>

2289 2295

2290保護認證檔案或目錄免受沙箱化命令。使用 `"mode": "deny"`，Claude Code 在沙箱內阻止路徑的讀取，與 [`sandbox.filesystem.denyRead`](#sandbox-filesystem-denyread) 相同的讀取塊。使用 `"mode": "mask"`，Linux 和 WSL2 上的沙箱化命令讀取檔案的哨兵副本，沙箱代理在該項目的 `injectHosts` 的出站請求上替換真實值；在 macOS 上，檔案在沙箱內不可讀。需要 Claude Code v2.1.187 或更新版本，`"mode": "mask"` 需要 v2.1.221 或更新版本。2296保護認證檔案或目錄免受沙箱化命令。使用 `"mode": "deny"`，Claude Code 在沙箱內阻止路徑的讀取，與 [`sandbox.filesystem.denyRead`](#sandbox-filesystem-denyread) 相同的讀取塊。使用 `"mode": "mask"`，Linux 和 WSL2 上的沙箱化命令讀取檔案的哨兵副本，沙箱代理在該項目的 `injectHosts` 的出站請求上替換真實值；在 macOS 上，檔案在沙箱內不可讀。`"mode": "mask"` 需要 Claude Code v2.1.221 或更新版本。

2291 2297

2292* **Scope**: [`Any file`](#scopes)。Claude Code 從專案 `.claude/settings.json` 和本機 `.claude/settings.local.json` 丟棄 `mask` 項目。2298* **Scope**: [`Any file`](#scopes)。Claude Code 從專案 `.claude/settings.json` 和本機 `.claude/settings.local.json` 丟棄 `mask` 項目。

2293* **Type**: 物件陣列，每個包含 `path` 和 `"deny"` 或 `"mask"` 的 `mode`，加上可選的 [mask fields for files](#mask-fields-for-files)2299* **Type**: 物件陣列，每個包含 `path` 和 `"deny"` 或 `"mask"` 的 `mode`，加上可選的 [mask fields for files](#mask-fields-for-files)

2308}2314}

2309```2315```

2310 2316

2311路徑使用與 `sandbox.filesystem.*` 設定相同的 [prefixes](#sandbox-path-prefixes)，Claude Code 合併工作階段載入的每個設定範圍中的陣列。[Protect credentials](/docs/zh-TW/sandboxing#protect-credentials) 涵蓋您使用 `--setting-sources` 排除的來源仍然適用的內容。需要 Claude Code v2.1.187 或更新版本；`mask` 項目需要 v2.1.221 或更新版本。2317路徑使用與 `sandbox.filesystem.*` 設定相同的 [prefixes](#sandbox-path-prefixes)，Claude Code 合併工作階段載入的每個設定範圍中的陣列。[Protect credentials](/docs/zh-TW/sandboxing#protect-credentials) 涵蓋您使用 `--setting-sources` 排除的來源仍然適用的內容。`mask` 項目需要 Claude Code v2.1.221 或更新版本。

2312 2318

2313`mask` 替換僅透過沙箱代理執行，所以設定 [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 或 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) 用於純 HTTP 測試網路。`mask` 適用於單個檔案，所以單獨列出每個認證檔案。Claude Code 接受但忽略 `deny` 項目上的 `mask` 欄位。[Mask credential files](/docs/zh-TW/sandboxing#mask-credential-files) 涵蓋接受哪些設定來源以及項目何時回退到 `deny`。2319`mask` 替換僅透過沙箱代理執行，所以設定 [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 或 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) 用於純 HTTP 測試網路。`mask` 適用於單個檔案，所以單獨列出每個認證檔案。Claude Code 接受但忽略 `deny` 項目上的 `mask` 欄位。[Mask credential files](/docs/zh-TW/sandboxing#mask-credential-files) 涵蓋接受哪些設定來源以及項目何時回退到 `deny`。

2314 2320

2364 `sandbox.credentials.envVars`2370 `sandbox.credentials.envVars`

2365</h3>2371</h3>

2366 2372

2367保護環境變數免受沙箱化命令。使用 `"mode": "deny"`，Claude Code 從沙箱化命令的環境中移除變數。使用 `"mode": "mask"`，沙箱化命令看到每個工作階段的哨兵值，沙箱代理在該項目的 `injectHosts` 的出站請求上替換真實值，所以 `gh` 和 `npm` 等工具保持驗證而不會持有真實認證。需要 Claude Code v2.1.187 或更新版本，`"mode": "mask"` 需要 v2.1.199 或更新版本。2373保護環境變數免受沙箱化命令。使用 `"mode": "deny"`，Claude Code 從沙箱化命令的環境中移除變數。使用 `"mode": "mask"`，沙箱化命令看到每個工作階段的哨兵值，沙箱代理在該項目的 `injectHosts` 的出站請求上替換真實值，所以 `gh` 和 `npm` 等工具保持驗證而不會持有真實認證。`"mode": "mask"` 需要 Claude Code v2.1.199 或更新版本。

2368 2374

2369* **Scope**: [`Any file`](#scopes)。Claude Code 從專案 `.claude/settings.json` 和本機 `.claude/settings.local.json` 丟棄 `mask` 項目。2375* **Scope**: [`Any file`](#scopes)。Claude Code 從專案 `.claude/settings.json` 和本機 `.claude/settings.local.json` 丟棄 `mask` 項目。

2370* **Type**: 物件陣列，每個包含 `name` 和 `"deny"` 或 `"mask"` 的 `mode`，加上可選的 [mask fields for environment variables](#mask-fields-for-environment-variables)2376* **Type**: 物件陣列，每個包含 `name` 和 `"deny"` 或 `"mask"` 的 `mode`，加上可選的 [mask fields for environment variables](#mask-fields-for-environment-variables)

2385}2391}

2386```2392```

2387 2393

2388`name` 必須以字母或底線開頭，並僅包含字母、數字和底線。Claude Code 合併工作階段載入的每個設定範圍中的陣列，當相同變數同時出現兩種模式時應用 `deny`。[Protect credentials](/docs/zh-TW/sandboxing#protect-credentials) 涵蓋您使用 `--setting-sources` 排除的來源仍然適用的內容。需要 Claude Code v2.1.187 或更新版本；`mask` 項目需要 v2.1.199 或更新版本。2394`name` 必須以字母或底線開頭，並僅包含字母、數字和底線。Claude Code 合併工作階段載入的每個設定範圍中的陣列，當相同變數同時出現兩種模式時應用 `deny`。[Protect credentials](/docs/zh-TW/sandboxing#protect-credentials) 涵蓋您使用 `--setting-sources` 排除的來源仍然適用的內容。`mask` 項目需要 Claude Code v2.1.199 或更新版本。

2389 2395

2390`mask` 替換僅透過沙箱代理執行，所以設定 [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 或 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) 用於純 HTTP 測試網路；請參閱 [Mask environment variables](/docs/zh-TW/sandboxing#mask-environment-variables)。Claude Code 接受但忽略 `deny` 項目上的 `mask` 欄位。2396`mask` 替換僅透過沙箱代理執行，所以設定 [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 或 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) 用於純 HTTP 測試網路；請參閱 [Mask environment variables](/docs/zh-TW/sandboxing#mask-environment-variables)。Claude Code 接受但忽略 `deny` 項目上的 `mask` 欄位。

2391 2397

2948 `env`2954 `env`

2949</h3>2955</h3>

2950 2956

2951為每個工作階段和 Claude Code 從中啟動的子程序設定環境變數。[環境變數參考](/docs/zh-TW/env-vars)中的任何變數都可以放在這裡，這是如何將其應用於每個工作階段或將其推出到您的團隊的方式。2957為每個工作階段和 Claude Code 從中啟動的子程序設定環境變數。[環境變數參考](/docs/zh-TW/env-vars)中的大多數變數都可以放在這裡，這是如何將其應用於每個工作階段或將其推出到您的團隊的方式。專案和本機設定無法設定[其中一些](#variables-claude-code-ignores-in-env)。

2952 2958

2953* **範圍**：[`任何檔案`](#scopes)2959* **範圍**：[`任何檔案`](#scopes)

2954* **類型**：將變數名稱對應到字串值的物件2960* **類型**：將變數名稱對應到字串值的物件

2969 `env` 值如何與您的 shell 相互作用2975 `env` 值如何與您的 shell 相互作用

2970</h4>2976</h4>

2971 2977

2972* 此處的值會覆蓋在您的 shell 中匯出的相同變數，當多個設定檔設定一個變數時，[最高優先級](/docs/zh-TW/settings#settings-precedence)的值適用。2978* 此處的值會覆蓋在您的 shell 中匯出的相同變數，當多個設定檔設定一個變數時，[最高優先級](/docs/zh-TW/settings#settings-precedence)的值適用。[Claude Code 在 `env` 中忽略的變數](#variables-claude-code-ignores-in-env)列出專案和本機設定的例外。

2973* 要取消 shell 匯出，請將變數設定為 `""`。Claude Code 將空值視為未設定以進行提供者選擇，子程序繼承空值。2979* 要取消 shell 匯出，請將變數設定為 `""`。Claude Code 將空值視為未設定以進行提供者選擇，子程序繼承空值。

2974* `NO_COLOR` 和 `FORCE_COLOR` 在此設定只到達子程序。要更改 Claude Code 自己的介面顏色，請在啟動 `claude` 之前在您的 shell 中設定它們。2980* `NO_COLOR` 和 `FORCE_COLOR` 在此設定只到達子程序。要更改 Claude Code 自己的介面顏色，請在啟動 `claude` 之前在您的 shell 中設定它們。

2975* 此處的值是設定檔中的純文字，到達 Claude Code 啟動的每個子程序。對於輪換的 OTLP 持有人令牌，使用 [`otelHeadersHelper`](#otelheadershelper)；對於 API 認證，使用 [`apiKeyHelper`](#apikeyhelper)。2981* 此處的值是設定檔中的純文字，到達 Claude Code 啟動的每個子程序。對於輪換的 OTLP 持有人令牌，使用 [`otelHeadersHelper`](#otelheadershelper)；對於 API 認證，使用 [`apiKeyHelper`](#apikeyhelper)。

2980 2986

2981* 從使用者設定、`--settings` 和受管設定：在啟動時，以及在執行中的工作階段中當保存的變更改變合併的 `env` 時。2987* 從使用者設定、`--settings` 和受管設定：在啟動時，以及在執行中的工作階段中當保存的變更改變合併的 `env` 時。

2982* 從專案和本機設定：在您信任工作區後，或在 `-p` 模式下啟動時（不顯示信任對話），以及當保存的變更改變合併的 `env` 時。2988* 從專案和本機設定：在您信任工作區後，或在 `-p` 模式下啟動時（不顯示信任對話），以及當保存的變更改變合併的 `env` 時。

2983* Claude Code 分類為安全的變數，例如模型選擇、逾時和限制、功能切換和遙測設定：在啟動時從每個設定檔，除了[專案和本機設定無法設定的變數](#variables-claude-code-ignores-in-env)。2989* Claude Code 分類為安全的變數，例如模型選擇、逾時和限制、功能切換：在啟動時從每個設定檔，除了[專案和本機設定無法設定的變數](#variables-claude-code-ignores-in-env)。

2984* 在您在 v2.1.246 或更高版本上使用 `/cd` [移動工作階段](/docs/zh-TW/permissions#move-the-session-to-another-directory)後：新目錄的專案和本機 `env` 值，加上前一個目錄的。2990* 在您在 v2.1.246 或更高版本上使用 `/cd` [移動工作階段](/docs/zh-TW/permissions#move-the-session-to-another-directory)後：新目錄的專案和本機 `env` 值，加上前一個目錄的。

2985 2991

2986<h4 id="variables-claude-code-ignores-in-env">2992<h4 id="variables-claude-code-ignores-in-env">

2987 Claude Code 在 `env` 中忽略的變數2993 Claude Code 在 `env` 中忽略的變數

2988</h4>2994</h4>

2989 2995

2990* 專案和本機設定無法設定已簽出的儲存庫不應控制的變數；改為在您的 shell、使用者設定或受管設定中設定這些變數。Claude Code 刪除每個變數並記錄您可以使用 `claude --debug` 看到的警告。它們包括：2996* 專案和本機設定無法設定已簽出的儲存庫不應控制的變數；改為在您的 shell、使用者設定或受管設定中設定這些變數。Claude Code 刪除每個變數，除了幾個關閉遙測的值，並記錄您可以使用 `claude --debug` 看到的警告。它們包括：

2991 2997

2992 * 選擇 Claude Code 儲存或寫入其自己檔案的位置的變數：`CLAUDE_CONFIG_DIR`、`CLAUDE_CODE_TMPDIR` 和作業系統目錄變數，例如 `HOME`、`TMPDIR`、`TMP`、`TEMP` 和 `XDG_*` 系列。2998 * 選擇 Claude Code 儲存或寫入其自己檔案的位置的變數：`CLAUDE_CONFIG_DIR`、`CLAUDE_CODE_TMPDIR` 和作業系統目錄變數，例如 `HOME`、`TMPDIR`、`TMP`、`TEMP` 和 `XDG_*` 系列。

2993 * 匯出工作階段內容的變數：[`OTEL_LOG_RAW_API_BODIES`](/docs/zh-TW/env-vars#variables) 和詳細的測試版追蹤對 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT`。2999 * 匯出工作階段內容的變數：[`OTEL_LOG_RAW_API_BODIES`](/docs/zh-TW/env-vars#variables) 和詳細的測試版追蹤對 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT`。

3000 * [OpenTelemetry 匯出器](/docs/zh-TW/monitoring-usage)變數，開啟遙測、選擇它的去向或選擇它捕獲的內容：

3001

3002 * `CLAUDE_CODE_ENABLE_TELEMETRY`，加上增強遙測測試版對 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` 和 `ENABLE_ENHANCED_TELEMETRY_BETA`

3003 * 匯出器選擇器 `OTEL_LOGS_EXPORTER`、`OTEL_METRICS_EXPORTER` 和 `OTEL_TRACES_EXPORTER`

3004 * 內容變數 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_ASSISTANT_RESPONSES`、`OTEL_LOG_TOOL_CONTENT` 和 `OTEL_LOG_TOOL_DETAILS`

3005 * `OTEL_EXPORTER_OTLP_*` 變數，其名稱以 `_ENDPOINT`、`_HEADERS`、`_PROTOCOL`、`_CERTIFICATE`、`_CLIENT_KEY` 或 `_INSECURE` 結尾，以通用和每個信號形式，例如 `OTEL_EXPORTER_OTLP_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_METRICS_HEADERS`

3006 * `OTEL_EXPORTER_PROMETHEUS_HOST` 和 `OTEL_EXPORTER_PROMETHEUS_PORT`

3007

3008 只有這些值仍然適用於專案和本機設定，因為它們關閉某些內容：三個匯出器選擇器的 `none`，以及 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_TOOL_CONTENT` 和 `OTEL_LOG_TOOL_DETAILS` 的關閉值，例如 `0`。這樣的值會覆蓋您的使用者設定中的相同變數，但不會覆蓋您啟動 Claude Code 的環境、`--settings` 檔案或受管設定設定的變數。

3009

3010 當專案或本機設定檔設定此群組中的變數時，本機互動式工作階段在啟動時顯示通知。執行 `/status` 或 `claude doctor` 以查看 Claude Code 忽略了哪些以及哪些關閉了遙測；兩者都列出名稱，從不列出值。非互動式執行（使用 `-p`）或 Agent SDK 工作階段不顯示通知，因此在升級後檢查您的收集器是否仍然接收資料。如果沒有，請在您的使用者設定、受管設定、工作的環境或您使用 `--settings` 傳遞的檔案中設定變數。

3011

3012 在專案和本機設定中忽略此群組需要 Claude Code v2.1.282 或更高版本。

2994 * 改變 Claude Code 如何啟動或同步的變數，例如 `CLAUDE_CODE_PROCESS_WRAPPER`、`CLAUDE_CODE_SYNC_SKILLS`、`CLAUDE_CODE_SYNC_PLUGINS`、`CLAUDE_CODE_PLUGIN_CACHE_DIR` 和 `CLAUDE_CODE_PLUGIN_SEED_DIR`。3013 * 改變 Claude Code 如何啟動或同步的變數，例如 `CLAUDE_CODE_PROCESS_WRAPPER`、`CLAUDE_CODE_SYNC_SKILLS`、`CLAUDE_CODE_SYNC_PLUGINS`、`CLAUDE_CODE_PLUGIN_CACHE_DIR` 和 `CLAUDE_CODE_PLUGIN_SEED_DIR`。

2995 3014

2996 在 v2.1.251 之前，專案和本機設定可以設定此清單命名的每個變數，除了 `HOME`、`XDG_CONFIG_HOME` 和改變 Claude Code 如何啟動或同步的變數。3015 在 v2.1.251 之前，專案和本機設定也可以設定此清單中選擇 Claude Code 寫入其檔案位置或匯出工作階段內容的變數，除了 `HOME` 和 `XDG_CONFIG_HOME`。

2997* Claude Code 的託管環境擁有的身份變數，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，從每個檔案中被忽略。3016* Claude Code 的託管環境擁有的身份變數，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，從每個檔案中被忽略。

2998* [`CLAUDE_CODE_MESSAGING_SOCKET` 和 `CLAUDE_CODE_MESSAGING_TOKEN`](/docs/zh-TW/env-vars#variables)，Claude Code 自己匯出的，從每個檔案中被忽略。忽略 socket 變數需要 Claude Code v2.1.224 或更高版本，忽略令牌需要 v2.1.228 或更高版本。3017* [`CLAUDE_CODE_MESSAGING_SOCKET` 和 `CLAUDE_CODE_MESSAGING_TOKEN`](/docs/zh-TW/env-vars#variables)，Claude Code 自己匯出的，從每個檔案中被忽略。忽略 socket 變數需要 Claude Code v2.1.224 或更高版本，忽略令牌需要 v2.1.228 或更高版本。

2999* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/zh-TW/sessions#name-the-project-directory-yourself)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略；需要 v2.1.234 或更高版本。3018* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/zh-TW/sessions#name-the-project-directory-yourself)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略；需要 v2.1.234 或更高版本。

3458 `respondToBashCommands`3477 `respondToBashCommands`

3459</h3>3478</h3>

3460 3479

3461選擇在您在輸入框中使用 [`!` 前綴](/docs/zh-TW/interactive-mode#shell-mode-with-prefix)執行 shell 命令後 Claude 是否回應。預設情況下，Claude Code 將命令的輸出新增到對話中，Claude 會回覆。將此金鑰設定為 `false` 以將輸出新增到上下文而不回覆，以便您可以執行多個命令並一起詢問它們。需要 Claude Code v2.1.186 或更新版本。3480選擇在您在輸入框中使用 [`!` 前綴](/docs/zh-TW/interactive-mode#shell-mode-with-prefix)執行 shell 命令後 Claude 是否回應。預設情況下，Claude Code 將命令的輸出新增到對話中，Claude 會回覆。將此金鑰設定為 `false` 以將輸出新增到上下文而不回覆，以便您可以執行多個命令並一起詢問它們。

3462 3481

3463* **範圍**：[`任何檔案`](#scopes)3482* **範圍**：[`任何檔案`](#scopes)

3464* **類型**：布林值3483* **類型**：布林值

3472}3491}

3473```3492```

3474 3493

3475請參閱[使用 `!` 前綴的 Shell 模式](/docs/zh-TW/interactive-mode#shell-mode-with-prefix)。需要 Claude Code v2.1.186 或更新版本。3494請參閱[使用 `!` 前綴的 Shell 模式](/docs/zh-TW/interactive-mode#shell-mode-with-prefix)。

3476 3495

3477<h3 id="showclearcontextonplanaccept">3496<h3 id="showclearcontextonplanaccept">

3478 `showClearContextOnPlanAccept`3497 `showClearContextOnPlanAccept`

3979自訂 Claude Code 新增至 git 提交和拉取請求的歸屬。提交預設會取得 [git trailer](https://git-scm.com/docs/git-interpret-trailers)，例如 `Co-Authored-By`；拉取請求描述會取得純文字。使用下方的子鍵分別設定每個部分。3998自訂 Claude Code 新增至 git 提交和拉取請求的歸屬。提交預設會取得 [git trailer](https://git-scm.com/docs/git-interpret-trailers)，例如 `Co-Authored-By`；拉取請求描述會取得純文字。使用下方的子鍵分別設定每個部分。

3980 3999

3981* **Scope**: [`Any file`](#scopes)4000* **Scope**: [`Any file`](#scopes)

3982* **Type**: 包含 `commit` 和 `pr` 字串以及 `sessionUrl` 布林值的物件4001* **Type**: 包含 `commit` 和 `pr` 字串以及 `sessionUrl` 布林值的物件，或 `false` 以隱藏所有歸屬。`false` 值需要 Claude Code v2.1.281 或更新版本；較早版本會拒絕它，並[略過整個使用者、專案或本機設定檔](/docs/zh-TW/settings#fix-a-broken-settings-file)

3983* **Default**: 未設定，因此 Claude Code 使用每個子鍵下方顯示的標準歸屬4002* **Default**: 未設定，因此 Claude Code 使用每個子鍵下方顯示的標準歸屬

3984 4003

4004若要隱藏所有歸屬，請將 `attribution` 設定為 `false`。在較早版本也會讀取的設定檔中，改為將 [`commit`](#attribution-commit) 和 [`pr`](#attribution-pr) 設定為空字串，並將 [`sessionUrl`](#attribution-sessionurl) 設定為 `false`。

4005

3985此範例會取代提交歸屬、移除拉取請求歸屬，並捨棄工作階段連結：4006此範例會取代提交歸屬、移除拉取請求歸屬，並捨棄工作階段連結：

3986 4007

3987```json settings.json theme={null}4008```json settings.json theme={null}

3994}4015}

3995```4016```

3996 4017

3997若要隱藏所有歸屬，請將 [`commit`](#attribution-commit) 和 [`pr`](#attribution-pr) 設定為空字串，並將 [`sessionUrl`](#attribution-sessionurl) 設定為 `false`。一旦您設定 `commit` 或 `pr`，Claude Code 就會忽略已棄用的 `includeCoAuthoredBy` 設定，並對您未設定的兩者使用其預設文字。4018一旦您設定 `commit` 或 `pr`，Claude Code 就會忽略已棄用的 `includeCoAuthoredBy` 設定，並對您未設定的兩者使用其預設文字。

3998 4019

3999Claude Code 告訴 Claude，您自己關於歸屬的指示（例如 CLAUDE.md 或[記憶](/docs/zh-TW/memory)規則）優先於這些提交和 PR 行，除非該行在[受管設定](/docs/zh-TW/managed-settings)中設定。4020Claude Code 告訴 Claude，您自己關於歸屬的指示（例如 CLAUDE.md 或[記憶](/docs/zh-TW/memory)規則）優先於這些提交和 PR 行，除非該行在[受管設定](/docs/zh-TW/managed-settings)中設定。

4000 4021

4020}4041}

4021```4042```

4022 4043

4023若要立即隱藏所有歸屬，請將 [`attribution.commit`](#attribution-commit) 和 [`attribution.pr`](#attribution-pr) 設定為空字串，並將 [`attribution.sessionUrl`](#attribution-sessionurl) 設定為 `false`。4044若要隱藏所有歸屬，請參閱 [`attribution`](#attribution)。

4024 4045

4025<h3 id="includegitinstructions">4046<h3 id="includegitinstructions">

4026 `includeGitInstructions`4047 `includeGitInstructions`

4178* **受管和 SDK hooks 執行**：來自受管設定的 hooks 和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 在程序中註冊的 hooks4199* **受管和 SDK hooks 執行**：來自受管設定的 hooks 和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 在程序中註冊的 hooks

4179* **強制啟用的外掛程式 hooks 執行**：來自您的受管設定透過 [`enabledPlugins`](#enabledplugins) 強制啟用的外掛程式的 hooks。Claude Code 在完整的 `plugin@marketplace` ID 上比對，因此來自不同市場的同名外掛程式保持被阻止。這讓您可以透過組織市場分發經過驗證的 hooks，同時阻止其他所有內容4200* **強制啟用的外掛程式 hooks 執行**：來自您的受管設定透過 [`enabledPlugins`](#enabledplugins) 強制啟用的外掛程式的 hooks。Claude Code 在完整的 `plugin@marketplace` ID 上比對，因此來自不同市場的同名外掛程式保持被阻止。這讓您可以透過組織市場分發經過驗證的 hooks，同時阻止其他所有內容

4180* **其他所有內容被阻止**：使用者、專案和本機 hooks、來自其他外掛程式的 hooks，以及在代理程式 frontmatter 中宣告的 hooks4201* **其他所有內容被阻止**：使用者、專案和本機 hooks、來自其他外掛程式的 hooks，以及在代理程式 frontmatter 中宣告的 hooks

4181* **命令來源的外掛程式被停用**：Claude Code 也停用具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources) 的外掛程式，包括在受管 `enabledPlugins` 中強制啟用的外掛程式，除非您明確將 [`disableCommandPluginSources`](#disablecommandpluginsources) 設定為 `false`4202* **命令來源的外掛程式被停用**：Claude Code 也停用具有 [`command` 來源](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source) 的外掛程式，包括在受管 `enabledPlugins` 中強制啟用的外掛程式，除非您明確將 [`disableCommandPluginSources`](#disablecommandpluginsources) 設定為 `false`

4182* **市場 `headersHelper` 命令被阻止**：Claude Code 也阻止市場 [`headersHelper` 命令](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](#disablecommandpluginsources) 明確設定為 `false`，受管設定本身宣告的市場除外。需要 Claude Code v2.1.238 或更新版本4203* **市場 `headersHelper` 命令被阻止**：Claude Code 也阻止市場 [`headersHelper` 命令](/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](#disablecommandpluginsources) 明確設定為 `false`，受管設定本身宣告的市場除外。需要 Claude Code v2.1.238 或更新版本

4183* **狀態行和檔案建議縮小到受管設定**：Claude Code 只從受管設定讀取 [`statusLine`](/docs/zh-TW/statusline)、[`fileSuggestion`](#filesuggestion) 和 [`subagentStatusLine`](/docs/zh-TW/statusline#subagent-status-lines)，遵循 [狀態行和檔案建議閘道](#status-line-and-file-suggestion-gates)4204* **狀態行和檔案建議縮小到受管設定**：Claude Code 只從受管設定讀取 [`statusLine`](/docs/zh-TW/statusline)、[`fileSuggestion`](#filesuggestion) 和 [`subagentStatusLine`](/docs/zh-TW/statusline#subagent-status-lines)，遵循 [狀態行和檔案建議閘道](#status-line-and-file-suggestion-gates)

4184 4205

4185當此金鑰設定時，[`/goal`](/docs/zh-TW/goal) 命令無法執行，因為它依賴於 hooks。4206當此金鑰設定時，[`/goal`](/docs/zh-TW/goal) 命令無法執行，因為它依賴於 hooks。

4360<span id="plugin-settings" />4381<span id="plugin-settings" />

4361 4382

4362<h2 id="plugins-and-skills">4383<h2 id="plugins-and-skills">

4363 外掛程式和技能4384 Plugins 和 skills

4364</h2>4385</h2>

4365 4386

4366啟用外掛程式、註冊市集、限制組織允許的外掛程式來源，以及控制哪些技能載入。如需安裝和建置外掛程式，請參閱 [外掛程式](/docs/zh-TW/plugins)。4387啟用 plugins，註冊 marketplaces，限制組織允許的 plugin 來源，以及控制哪些 skills 載入。如需安裝和建置 plugins，請參閱 [Plugins](/docs/zh-TW/plugins/overview)。

4367 4388

4368<h3 id="disablebundledskills">4389<h3 id="disablebundledskills">

4369 `disableBundledSkills`4390 `disableBundledSkills`

4370</h3>4391</h3>

4371 4392

4372關閉 Claude Code 隨附的 [技能](/docs/zh-TW/skills) 和工作流程。Claude Code 會完全移除隨附的技能和工作流程，而內建命令（例如 `/init`）仍可輸入但會隱藏在模型中。4393關閉 Claude Code 隨附的 [skills](/docs/zh-TW/skills) 和工作流程。Claude Code 會完全移除捆綁的 skills 和工作流程，而內建命令（例如 `/init`）仍可輸入但會對模型隱藏。

4373 4394

4374* **範圍**：[`任何檔案`](#scopes)4395* **Scope**: [`Any file`](#scopes)

4375* **類型**：布林值4396* **Type**: Boolean

4376 * `true`：Claude Code 移除隨附的技能和工作流程，並隱藏模型中的內建命令（例如 `/init`）4397 * `true`: Claude Code 移除捆綁的 skills 和工作流程，並對模型隱藏內建命令（例如 `/init`）

4377 * `false`：隨附的技能載入4398 * `false`: 捆綁的 skills 載入

4378* **預設**：未設定，因此隨附的技能會載入4399* **Default**: 未設定，因此捆綁的 skills 載入

4379* **每個工作階段覆寫**：[`CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`](/docs/zh-TW/env-vars) 設定為 `1` 會在一個工作階段中關閉隨附的技能；無論哪一個關閉它們，另一個都無法將其重新開啟4400* **Per-session overrides**: [`CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`](/docs/zh-TW/env-vars) 設定為 `1` 會在一個工作階段中關閉捆綁的 skills；無論哪一個關閉它們，另一個都無法將其重新開啟

4380 4401

4381```json settings.json theme={null}4402```json settings.json theme={null}

4382{4403{

4384}4405}

4385```4406```

4386 4407

4387來自外掛程式、`.claude/skills/` 和 `.claude/commands/` 的技能不受影響。`/doctor` 與內建命令一樣仍可輸入；若要隱藏它，請改為設定 [`DISABLE_DOCTOR_COMMAND`](/docs/zh-TW/env-vars)。4408來自 plugins、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影響。`/doctor` 仍可輸入，就像內建命令一樣；若要隱藏它，請改為設定 [`DISABLE_DOCTOR_COMMAND`](/docs/zh-TW/env-vars)。

4388 4409

4389<h3 id="disableskillshellexecution">4410<h3 id="disableskillshellexecution">

4390 `disableSkillShellExecution`4411 `disableSkillShellExecution`

4391</h3>4412</h3>

4392 4413

4393關閉 [技能](/docs/zh-TW/skills) 和來自使用者、專案、外掛程式或其他目錄來源的自訂命令中 `` !`...` `` 和 ` ```! ` 區塊的內嵌 shell 執行。Claude Code 會用 `[shell command execution disabled by policy]` 取代每個命令，而不是執行它。4414關閉 [skills](/docs/zh-TW/skills) 和來自使用者、專案、plugin 或其他目錄來源的自訂命令中 `` !`...` `` 和 ` ```! ` 區塊的內嵌 shell 執行。Claude Code 會用 `[shell command execution disabled by policy]` 取代每個命令，而不是執行它。

4394 4415

4395* **範圍**：[`任何檔案`](#scopes)。受管設定中的 `true` 無法被其他地方的 `false` 覆寫。4416* **Scope**: [`Any file`](#scopes)。受管設定中的 `true` 無法被其他地方的 `false` 覆寫。

4396* **類型**：布林值4417* **Type**: Boolean

4397 * `true`：Claude Code 用 `[shell command execution disabled by policy]` 取代每個內嵌 shell 命令，而不是執行它4418 * `true`: Claude Code 用 `[shell command execution disabled by policy]` 取代每個內嵌 shell 命令，而不是執行它

4398 * `false`：內嵌 shell 執行4419 * `false`: 內嵌 shell 執行

4399* **預設**：未設定，因此內嵌 shell 執行4420* **Default**: 未設定，因此內嵌 shell 執行

4400 4421

4401```json settings.json theme={null}4422```json settings.json theme={null}

4402{4423{

4404}4425}

4405```4426```

4406 4427

4407隨附的技能和透過受管設定部署的技能不受影響。4428捆綁的 skills 和透過受管設定部署的 skills 不受影響。

4408 4429

4409<h3 id="skilloverrides">4430<h3 id="skilloverrides">

4410 `skillOverrides`4431 `skillOverrides`

4411</h3>4432</h3>

4412 4433

4413隱藏或摺疊 [技能](/docs/zh-TW/skills#override-skill-visibility-from-settings)，而不編輯其 `SKILL.md`。Claude Code 會將每個技能名稱下的值套用到 Claude 看到的技能清單和您的 `/` 自動完成。4434隱藏或摺疊 [skill](/docs/zh-TW/skills#override-skill-visibility-from-settings)，無需編輯其 `SKILL.md`。Claude Code 會將每個 skill 名稱下的值套用到 Claude 看到的 skill 清單和您的 `/` 自動完成。

4414 4435

4415* **範圍**：[`任何檔案`](#scopes)。`/skills` 功能表寫入 `.claude/settings.local.json`。4436* **Scope**: [`Any file`](#scopes)。`/skills` 功能表寫入 `.claude/settings.local.json`。

4416* **類型**：將技能名稱對應到以下其中之一的物件：4437* **Type**: 將 skill 名稱對應到以下其中之一的物件：

4417 * `"on"`：Claude 看到該技能，您可以輸入 `/name`4438 * `"on"`: Claude 看到該 skill，您可以輸入 `/name`

4418 * `"name-only"`：Claude 按名稱看到該技能，但不看到其描述4439 * `"name-only"`: Claude 按名稱看到該 skill，但不看到其描述

4419 * `"user-invocable-only"`：Claude 看不到該技能，但您仍可輸入 `/name`4440 * `"user-invocable-only"`: Claude 看不到該 skill，但您仍可輸入 `/name`

4420 * `"off"`：Claude 看不到該技能，`/name` 在自動完成中隱藏4441 * `"off"`: Claude 看不到該 skill，且 `/name` 在自動完成中隱藏

4421* **預設**：未設定，因此每個技能都是 `"on"`4442* **Default**: 未設定，因此每個 skill 都是 `"on"`

4422 4443

4423此範例將 `legacy-context` 僅按名稱列出給 Claude，並隱藏 Claude 和 `/` 自動完成中的 `deploy`：4444此範例將 `legacy-context` 按名稱列出給 Claude，並從 Claude 和 `/` 自動完成中隱藏 `deploy`：

4424 4445

4425```json settings.json theme={null}4446```json settings.json theme={null}

4426{4447{

4431}4452}

4432```4453```

4433 4454

4434覆寫不適用於外掛程式技能，您可以透過 `/plugin` 管理這些技能。4455覆寫不適用於 plugin skills，您可以透過 `/plugin` 管理這些。

4435 4456

4436在受管設定和使用 `--settings` 傳遞的檔案中，隨附技能別名上的金鑰（例如 `/doctor` 的 `checkup`）也適用於該技能；請參閱 [別名金鑰如何與技能自身名稱上的金鑰結合](/docs/zh-TW/skills#override-skill-visibility-from-settings)。4457在受管設定和使用 `--settings` 傳遞的檔案中，捆綁 skill 的別名上的鍵（例如 `/doctor` 的 `checkup`）也適用於該 skill；請參閱[別名鍵如何與 skill 自身名稱上的鍵結合](/docs/zh-TW/skills#override-skill-visibility-from-settings)。

4437 4458

4438<h3 id="syncclaudeaiskills">4459<h3 id="syncclaudeaiskills">

4439 `syncClaudeAiSkills`4460 `syncClaudeAiSkills`

4440</h3>4461</h3>

4441 4462

4442關閉 [您在 claude.ai 上啟用的技能](/docs/zh-TW/skills#how-synced-skills-behave) 的下載。Claude Code 會將它們下載到 `~/.claude/skills/synced/`，在 [您使用 claude.ai 帳戶登入的終端工作階段](/docs/zh-TW/skills#where-synced-skills-load)（互動或非互動）以及在 Cowork 和雲端工作階段中。設定為 `false` 以停止該下載並停止載入已同步的技能。Claude Code 僅接受 `false`：`true` 與未設定相同，不會開啟同步。4463關閉 [為您的 claude.ai 帳戶啟用的 skills](/docs/zh-TW/skills#how-synced-skills-behave) 的下載。Claude Code 會在[您使用 claude.ai 帳戶登入的終端機工作階段](/docs/zh-TW/skills#where-synced-skills-load)（互動式或非互動式）以及 Cowork 和雲端工作階段中，將它們下載到 `~/.claude/skills/synced/`。設定 `false` 以停止該下載並停止載入已同步的 skills。Claude Code 僅接受 `false`：`true` 與未設定相同，不會在其他情況下關閉的地方開啟同步。

4443 4464

4444* **範圍**：[`使用者、本機或受管`](#scopes)，以及使用 `--settings` 傳遞的檔案。儲存庫無法為您關閉它。4465* **Scope**: [`User, local, or managed`](#scopes)，以及使用 `--settings` 傳遞的檔案。儲存庫無法為您關閉它。

4445* **類型**：布林值4466* **Type**: Boolean

4446 * `false`：Claude Code 停止下載同步的技能，並停止載入 `~/.claude/skills/synced/` 中已有的技能。在使用者或受管設定中，它也會將它們移至 `~/.claude/skills/.trash/`4467 * `false`: Claude Code 停止下載同步的 skills，並停止載入 `~/.claude/skills/synced/` 中已有的 skills。在使用者或受管設定中，它也會將它們移至 `~/.claude/skills/.trash/`

4447 * `true`：與未設定相同4468 * `true`: 與未設定相同

4448* **預設**：未設定，因此使用 claude.ai 帳戶登入的工作階段會同步您的技能4469* **Default**: 未設定，因此使用 claude.ai 帳戶登入的工作階段會同步您的 skills

4449 4470

4450此範例防止機器在任何工作階段中下載帳戶的技能：4471此範例防止機器在任何工作階段中下載帳戶的 skills：

4451 4472

4452```json settings.json theme={null}4473```json settings.json theme={null}

4453{4474{

4459 `syncClaudeAiPlugins`4480 `syncClaudeAiPlugins`

4460</h3>4481</h3>

4461 4482

4462關閉 [您在 claude.ai 帳戶上啟用的外掛程式](/docs/zh-TW/plugins-reference#synced-plugins) 的下載。Claude Code 會將它們下載到 `~/.claude/plugins/synced/`，在您使用 claude.ai 帳戶登入的終端工作階段開始時，以及在 Cowork 和雲端工作階段中，並將每個載入為 `<name>@synced`。設定為 `false` 以停止該下載並停止載入已同步的外掛程式。Claude Code 僅接受 `false`：`true` 與未設定相同，不會開啟同步。需要 Claude Code v2.1.273 或更新版本。4483關閉 [為您的 claude.ai 帳戶啟用的 plugins](/docs/zh-TW/plugins/loading#synced-plugins) 的下載。Claude Code 會在您使用 claude.ai 帳戶登入的終端機工作階段開始時和 Cowork 工作階段中，將它們下載到 `~/.claude/plugins/synced/`，並將每個載入為 `<name>@synced`。設定 `false` 以停止該下載並停止載入已同步的 plugins。Claude Code 僅接受 `false`：`true` 與未設定相同，不會在其他情況下關閉的地方開啟同步。需要 Claude Code v2.1.273 或更新版本。

4463 4484

4464* **範圍**：[`使用者、本機或受管`](#scopes)，以及使用 `--settings` 傳遞的檔案。儲存庫無法為您關閉它。4485* **Scope**: [`User, local, or managed`](#scopes)，以及使用 `--settings` 傳遞的檔案。儲存庫無法為您關閉它。

4465* **類型**：布林值4486* **Type**: Boolean

4466 * `false`：Claude Code 停止下載同步的外掛程式，並停止載入 `~/.claude/plugins/synced/` 中已有的外掛程式。在使用者或受管設定中，它也會將它們移至 `~/.claude/plugins/.trash/`4487 * `false`: Claude Code 停止下載同步的 plugins，並停止載入 `~/.claude/plugins/synced/` 中已有的 plugins。在使用者或受管設定中，它也會將它們移至 `~/.claude/plugins/.trash/`

4467 * `true`：與未設定相同4488 * `true`: 與未設定相同

4468* **預設**：未設定，因此使用 claude.ai 帳戶登入的工作階段會同步您的外掛程式4489* **Default**: 未設定，因此使用 claude.ai 帳戶登入的工作階段會同步您的 plugins

4469 4490

4470若要關閉一個同步的外掛程式而不是全部，請在 [`enabledPlugins`](#enabledplugins) 中設定 `"<name>@synced": false`。4491若要關閉一個同步的 plugin 而不是全部，請在 [`enabledPlugins`](#enabledplugins) 中設定 `"<name>@synced": false`。

4471 4492

4472此範例防止機器在任何工作階段中下載帳戶的外掛程式：4493此範例防止機器在任何工作階段中下載帳戶的 plugins：

4473 4494

4474```json settings.json theme={null}4495```json settings.json theme={null}

4475{4496{

4481 `allowedChannelPlugins`4502 `allowedChannelPlugins`

4482</h3>4503</h3>

4483 4504

4484選擇哪些 [頻道](/docs/zh-TW/channels) 外掛程式可以將訊息推送到組織中的工作階段。設定後，Claude Code 會使用您的清單取代預設的 Anthropic 允許清單；每個項目命名一個外掛程式及其來自的市集。4505選擇哪些 [channel](/docs/zh-TW/channels) plugins 可以將訊息推送到您組織中的工作階段。當您設定它時，Claude Code 會使用您的清單取代預設的 Anthropic 允許清單；每個項目命名一個 plugin 和它來自的 marketplace。

4485 4506

4486* **範圍**：[`受管`](#scopes)4507* **Scope**: [`Managed`](#scopes)

4487* **類型**：物件陣列，每個物件都有 `marketplace` 和 `plugin` 字串。項目可以改為 `"plugin@marketplace"` 字串，例如 `"telegram@claude-plugins-official"`，Claude Code 將其視為等效物件。字串形式需要 Claude Code v2.1.267 或更新版本；較早版本在 `allowedChannelPlugins` 包含一個時會拒絕整個值4508* **Type**: 物件陣列，每個物件都有 `marketplace` 和 `plugin` 字串。項目可以改為 `"plugin@marketplace"` 字串，例如 `"telegram@claude-plugins-official"`，Claude Code 會將其視為等效物件。字串形式需要 Claude Code v2.1.267 或更新版本；較早版本在 `allowedChannelPlugins` 包含一個時會拒絕整個值

4488* **預設**：未設定，因此 Claude Code 使用預設的 Anthropic 允許清單4509* **Default**: 未設定，因此 Claude Code 使用預設的 Anthropic 允許清單

4489 4510

4490此範例開啟頻道，並僅允許來自官方 Anthropic 市集的 Telegram 外掛程式：4511此範例開啟 channels 並僅允許來自官方 Anthropic marketplace 的 Telegram plugin：

4491 4512

4492```json managed-settings.json theme={null}4513```json managed-settings.json theme={null}

4493{4514{

4498}4519}

4499```4520```

4500 4521

4501空陣列會阻止每個頻道外掛程式。4522空陣列會阻止每個 channel plugin。

4502 4523

4503此金鑰在頻道通過帳戶的 [`channelsEnabled`](#channelsenabled) 閘道後生效：在 Team 和 Enterprise 方案上，以及在具有受管設定的 Console 帳戶上，這表示 `channelsEnabled: true`。請參閱 [限制哪些頻道外掛程式可以執行](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run)。4524此鍵在 channels 通過帳戶的 [`channelsEnabled`](#channelsenabled) 閘道後生效：在 Team 和 Enterprise 方案上，以及在具有受管設定的 Console 帳戶上，這表示 `channelsEnabled: true`。請參閱[限制哪些 channel plugins 可以執行](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run)。

4504 4525

4505<h3 id="blockedmarketplaces">4526<h3 id="blockedmarketplaces">

4506 `blockedMarketplaces`4527 `blockedMarketplaces`

4507</h3>4528</h3>

4508 4529

4509為您的組織阻止外掛程式市集來源。Claude Code 在市集新增和外掛程式安裝、更新、重新整理和自動更新時檢查封鎖清單，因此在您設定原則之前某人新增的市集無法用於擷取外掛程式。在下載前檢查被阻止的來源，因此它們永遠不會接觸檔案系統。4530為您的組織阻止 plugin marketplace 來源。Claude Code 在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時檢查封鎖清單，因此有人在您設定原則之前新增的 marketplace 也無法用於擷取 plugins。在下載前檢查被阻止的來源，因此它們永遠不會接觸檔案系統。

4510 4531

4511* **範圍**：[`受管`](#scopes)4532如果您在 [claude.ai 管理員主控台](/docs/zh-TW/server-managed-settings) 中設定此鍵，claude.ai 也會在您組織中的任何人從 claude.ai 上的 git 儲存庫新增 marketplace 時套用它，如[限制如何運作](/docs/zh-TW/plugins/org#restrict-what-users-can-install)所述。

4512* **類型**：市集來源物件的陣列，形式與 [`strictKnownMarketplaces`](#allowed-source-types) 相同4533

4513* **預設**：未設定，因此沒有市集被阻止4534* **Scope**: [`Managed`](#scopes)

4535* **Type**: marketplace 來源物件的陣列，形式與 [`strictKnownMarketplaces`](#allowed-source-types) 相同

4536* **Default**: 未設定，因此沒有 marketplace 被阻止

4514 4537

4515此範例阻止一個 GitHub 儲存庫作為市集來源：4538此範例阻止一個 GitHub 儲存庫作為 marketplace 來源：

4516 4539

4517```json managed-settings.json theme={null}4540```json managed-settings.json theme={null}

4518{4541{

4522}4545}

4523```4546```

4524 4547

4525`github` 項目可能使用 [所有者萬用字元形式](#owner-wildcards) `"owner/*"` 來阻止該 GitHub 所有者下的每個儲存庫，這需要 Claude Code v2.1.223 或更新版本。新增 `{ "source": "skills-dir" }` 以停止 Claude Code 從 `~/.claude/skills/` 載入 [`@skills-dir` 外掛程式](/docs/zh-TW/plugins-reference#skills-directory-plugins)，而不限制任何市集。請參閱 [受管市集限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)。4548`github` 項目可能使用[所有者萬用字元形式](#owner-wildcards) `"owner/*"` 來阻止該 GitHub 所有者下的每個儲存庫，這需要 Claude Code v2.1.223 或更新版本。新增 `{ "source": "skills-dir" }` 以停止 Claude Code 從 `~/.claude/skills/` 載入 [`@skills-dir` plugins](/docs/zh-TW/plugins/loading#plugins-shared-through-a-repository)，而不限制任何 marketplace。請參閱[受管 marketplace 限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install)。

4526 4549

4527<h3 id="channelsenabled">4550<h3 id="channelsenabled">

4528 `channelsEnabled`4551 `channelsEnabled`

4529</h3>4552</h3>

4530 4553

4531為您的組織允許 [頻道](/docs/zh-TW/channels)。在 claude.ai Team 和 Enterprise 方案上，Claude Code 會阻止頻道，直到您將其設定為 `true`。對於使用 API 金鑰進行驗證的 [Anthropic Console](/docs/zh-TW/authentication#claude-console-authentication) 帳戶，預設允許頻道。如果您的組織部署受管設定，Claude Code 也會在這些帳戶上阻止頻道，直到您將此金鑰設定為 `true`。4554為您的組織允許 [channels](/docs/zh-TW/channels)。在 claude.ai Team 和 Enterprise 方案上，Claude Code 會阻止 channels，直到您將其設定為 `true`。對於使用 API 金鑰進行驗證的 [Anthropic Console](/docs/zh-TW/authentication#claude-console-authentication) 帳戶，預設允許 channels。如果您的組織部署受管設定，Claude Code 也會在這些帳戶上阻止 channels，直到您將此鍵設定為 `true`。

4532 4555

4533* **範圍**：[`受管`](#scopes)4556* **Scope**: [`Managed`](#scopes)

4534* **類型**：布林值4557* **Type**: Boolean

4535 * `true`：Claude Code 為您的組織允許頻道4558 * `true`: Claude Code 為您的組織允許 channels

4536 * `false`：與未設定相同；頻道是否被阻止取決於您的方案，如預設所述4559 * `false`: 與未設定相同；channels 是否被阻止取決於您的方案，如「Default」所述

4537* **預設**：未設定；在 Team 和 Enterprise 方案以及具有受管設定的 Console 帳戶上阻止頻道，在 Pro 和 Max 方案以及沒有受管設定的 Console 帳戶上允許4560* **Default**: 未設定；channels 在 Team 和 Enterprise 方案上以及在具有受管設定的 Console 帳戶上被阻止，在 Pro 和 Max 方案上以及在沒有受管設定的 Console 帳戶上被允許

4538 4561

4539```json managed-settings.json theme={null}4562```json managed-settings.json theme={null}

4540{4563{

4542}4565}

4543```4566```

4544 4567

4545若要限制啟用後哪些外掛程式可以註冊為頻道，請設定 [`allowedChannelPlugins`](#allowedchannelplugins)。請參閱 [企業控制](/docs/zh-TW/channels#enterprise-controls)。4568若要限制哪些 plugins 可以在啟用後註冊為 channels，請設定 [`allowedChannelPlugins`](#allowedchannelplugins)。請參閱[企業控制](/docs/zh-TW/channels#enterprise-controls)。

4546 4569

4547<h3 id="disablecommandpluginsources">4570<h3 id="disablecommandpluginsources">

4548 `disableCommandPluginSources`4571 `disableCommandPluginSources`

4549</h3>4572</h3>

4550 4573

4551阻止 [`command` 外掛程式來源](/docs/zh-TW/plugin-marketplaces#command-sources)，它透過在使用者機器上執行市集宣告的命令來安裝外掛程式。當您將其設定為 `true` 時，Claude Code 永遠不會執行該命令，不會安裝或更新命令來源的外掛程式，並停止載入已安裝的外掛程式。設定為 `false` 以明確允許它們。無論何時阻止命令來源，無論您將其設定為 `true` 還是在 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 下保持未設定，它也會阻止市集 [`headersHelper` 命令](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)，除了受管設定本身宣告的市集。需要 Claude Code v2.1.229 或更新版本，`headersHelper` 阻止需要 v2.1.238 或更新版本。4574阻止 [`command` plugin 來源](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)，它透過在使用者的機器上執行 marketplace 宣告的命令來安裝 plugin。當您將其設定為 `true` 時，Claude Code 永遠不會執行該命令，不會安裝或更新命令來源的 plugins，並停止載入已安裝的 plugins。設定為 `false` 以明確允許它們。每當它阻止命令來源時，無論您將其設定為 `true` 還是在 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 下保持未設定，它也會阻止 marketplace [`headersHelper` 命令](/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，除了受管設定本身宣告的 marketplace。需要 Claude Code v2.1.229 或更新版本，`headersHelper` 阻止需要 v2.1.238 或更新版本。

4552 4575

4553* **範圍**：[`受管`](#scopes)4576* **Scope**: [`Managed`](#scopes)

4554* **類型**：布林值4577* **Type**: Boolean

4555 * `true`：Claude Code 永遠不會執行市集宣告的命令，不會安裝或更新命令來源的外掛程式，並停止載入已安裝的外掛程式4578 * `true`: Claude Code 永遠不會執行 marketplace 宣告的命令，不會安裝或更新命令來源的 plugins，並停止載入已安裝的 plugins

4556 * `false`：Claude Code 明確允許命令來源的外掛程式4579 * `false`: Claude Code 明確允許命令來源的 plugins

4557* **預設**：未設定，因此 Claude Code 遵循 [`allowManagedHooksOnly`](#allowmanagedhooksonly)：限制 hook 執行到受管設定的組織也會停用命令來源4580* **Default**: 未設定，因此 Claude Code 遵循 [`allowManagedHooksOnly`](#allowmanagedhooksonly)：限制 hook 執行到受管設定的組織也會禁用命令來源

4558 4581

4559```json managed-settings.json theme={null}4582```json managed-settings.json theme={null}

4560{4583{

4568 `pluginSuggestionMarketplaces`4591 `pluginSuggestionMarketplaces`

4569</h3>4592</h3>

4570 4593

4571命名其外掛程式可以作為內容相關安裝建議出現的市集，在微調提示和釘選在 `/plugin` **Discover** 標籤頂部。內建的第一方前端設計提示不受影響。建議來自每個外掛程式在其市集項目中的 `relevance` 宣告。4594命名其 plugins 可以作為內容相關安裝建議出現的 marketplaces，在微調提示和釘選在 `/plugin` **Discover** 標籤頂部。內建的第一方前端設計提示不受影響。建議來自每個 plugin 在其 marketplace 項目中的 `relevance` 宣告。

4572 4595

4573* **範圍**：[`受管`](#scopes)4596* **Scope**: [`Managed`](#scopes)

4574* **類型**：市集名稱的陣列4597* **Type**: marketplace 名稱的陣列

4575* **預設**：未設定，因此沒有市集宣告的建議出現4598* **Default**: 未設定，因此沒有 marketplace 宣告的建議出現

4576 4599

4577```json managed-settings.json theme={null}4600```json managed-settings.json theme={null}

4578{4601{

4580}4603}

4581```4604```

4582 4605

4583名稱僅在市集在機器上註冊且其註冊來源也在相同受管設定中宣告時生效，作為該名稱的 [`extraKnownMarketplaces`](#extraknownmarketplaces) 項目或作為 [`strictKnownMarketplaces`](#strictknownmarketplaces) 的項目。Claude Code 忽略從不同來源在允許清單名稱下註冊的市集。官方市集豁免於來源要求：僅允許清單其名稱就足夠了，因為該名稱只能從官方 Anthropic 來源註冊。請參閱 [按內容建議外掛程式](/docs/zh-TW/plugin-relevance)。4606名稱僅在 marketplace 在機器上註冊且其註冊來源也在相同受管設定中宣告時生效，作為該名稱的 [`extraKnownMarketplaces`](#extraknownmarketplaces) 項目或作為 [`strictKnownMarketplaces`](#strictknownmarketplaces) 的項目。Claude Code 忽略從不同來源在允許清單名稱下註冊的 marketplace。官方 marketplace 豁免於來源要求：僅允許清單其名稱就足夠了，因為該名稱只能從官方 Anthropic 來源註冊。請參閱[按內容建議 plugins](/docs/zh-TW/plugins/relevance)。

4584 4607

4585<h3 id="plugintrustmessage">4608<h3 id="plugintrustmessage">

4586 `pluginTrustMessage`4609 `pluginTrustMessage`

4587</h3>4610</h3>

4588 4611

4589將您組織自己的文字新增到 Claude Code 在安裝前顯示的外掛程式信任警告中，例如確認來自您內部市集的外掛程式已經過審查。4612將您組織自己的文字新增到 Claude Code 在安裝前顯示的 plugin 信任警告中，例如確認來自您內部 marketplace 的 plugins 已經過審查。

4590 4613

4591* **範圍**：[`受管`](#scopes)4614* **Scope**: [`Managed`](#scopes)

4592* **類型**：字串4615* **Type**: 字串

4593* **預設**：未設定，因此 Claude Code 僅顯示標準警告4616* **Default**: 未設定，因此 Claude Code 僅顯示標準警告

4594 4617

4595```json managed-settings.json theme={null}4618```json managed-settings.json theme={null}

4596{4619{

4602 `strictKnownMarketplaces`4625 `strictKnownMarketplaces`

4603</h3>4626</h3>

4604 4627

4605限制組織中的人員可以新增和安裝外掛程式的外掛程式市集來源。Claude Code 在市集新增和外掛程式安裝、更新、重新整理和自動更新時強制執行允許清單，在任何網路或檔案系統操作之前，因此在您設定原則之前某人新增的市集一旦其來源不再符合就無法用於擷取外掛程式。被阻止的使用者會看到命名受管原則的錯誤。4628限制您組織中的人員可以新增和安裝 plugins 的 plugin marketplace 來源。Claude Code 在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行允許清單，在任何網路或檔案系統操作之前，因此有人在您設定原則之前新增的 marketplace 一旦其來源不再符合就無法用於擷取 plugins。被阻止的使用者會看到命名受管原則的錯誤。

4606 4629

4607* **範圍**：[`受管`](#scopes)4630如果您在 [claude.ai 管理員主控台](/docs/zh-TW/server-managed-settings) 中設定此鍵，claude.ai 也會在您組織中的任何人從 claude.ai 上的 git 儲存庫新增 marketplace 時套用它，如[限制如何運作](/docs/zh-TW/plugins/org#restrict-what-users-can-install)所述。

4608* **類型**：市集來源物件的陣列；請參閱 [允許的來源類型](#allowed-source-types)4631

4609* **預設**：未設定，因此使用者可以新增任何市集。空陣列是完全鎖定，阻止每個市集來源，包括官方 Anthropic 市集4632* **Scope**: [`Managed`](#scopes)

4633* **Type**: marketplace 來源物件的陣列；請參閱[允許的來源類型](#allowed-source-types)

4634* **Default**: 未設定，因此使用者可以新增任何 marketplace。空陣列是完全鎖定，會阻止每個 marketplace 來源，包括官方 Anthropic marketplace

4610 4635

4611此範例允許兩個 GitHub 儲存庫，一個釘選到 `v2.0` ref，一個託管 `marketplace.json` URL：4636此範例允許兩個 GitHub 儲存庫，一個釘選到 `v2.0` ref，一個託管 `marketplace.json` URL：

4612 4637

4620}4645}

4621```4646```

4622 4647

4623您也可以將此金鑰寫為 `allowedMarketplaces`；[市集金鑰別名](#marketplace-key-aliases) 描述 Claude Code 如何處理別名以及哪個版本接受它。此金鑰是原則閘道：它控制使用者可能新增的內容，但不註冊任何內容。若要在一個檔案中限制和預先註冊，請參閱 [與 `extraKnownMarketplaces` 結合](#combine-with-extraknownmarketplaces)。如需使用者面向的檢視，請參閱 [受管市集限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)。4648您也可以將此鍵寫為 `allowedMarketplaces`；[Marketplace 鍵別名](#marketplace-key-aliases)描述 Claude Code 如何處理別名以及哪個版本接受它。此鍵是原則閘道：它控制使用者可能新增的內容，但不註冊任何內容。若要在一個檔案中限制和預先註冊，請參閱[與 `extraKnownMarketplaces` 結合](#combine-with-extraknownmarketplaces)。如需使用者面向的檢視，請參閱[受管 marketplace 限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install)。

4624 4649

4625<h4 id="allowed-source-types">4650<h4 id="allowed-source-types">

4626 允許的來源類型4651 允許的來源類型

4627</h4>4652</h4>

4628 4653

4629下面每個項目顯示每個來源類型的一個允許清單項目及其接受的欄位。大多數類型完全符合；`hostPattern` 和 `pathPattern` 按正規表達式符合，`github` 項目可以使用 [所有者萬用字元](#owner-wildcards)。4654下面每個項目顯示每個來源類型的一個允許清單項目及其接受的欄位。大多數類型完全符合；`hostPattern` 和 `pathPattern` 按 regex 符合，`github` 項目可以使用[所有者萬用字元](#owner-wildcards)。

4630 4655

4631| 來源 | 範例項目 | 欄位 |4656| Source | Example entry | Fields |

4632| :------------ | :------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------- |4657| :------------ | :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------ |

4633| `github` | `{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }` | `repo` 必需；`ref` 是分支或標籤；`path` 是子目錄 |4658| `github` | `{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }` | `repo` 必需；`ref` 是分支或標籤；`path` 是子目錄 |

4634| `git` | `{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git", "ref": "production" }` | `url` 必需；`ref` 和 `path` 如 `github` |4659| `git` | `{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git", "ref": "production" }` | `url` 必需；`ref` 和 `path` 如 `github` |

4635| `url` | `{ "source": "url", "url": "https://plugins.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }` | `url` 必需；`headers` 為已驗證存取新增 HTTP 標頭 |4660| `url` | `{ "source": "url", "url": "https://plugins.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }` | `url` 必需；`headers` 為已驗證存取新增 HTTP 標頭 |

4636| `npm` | `{ "source": "npm", "package": "@acme-corp/claude-plugins" }` | `package` 必需，包含 `marketplace.json` 的 npm 套件 |

4637| `file` | `{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }` | `path` 必需，`marketplace.json` 檔案的絕對路徑 |4661| `file` | `{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }` | `path` 必需，`marketplace.json` 檔案的絕對路徑 |

4638| `directory` | `{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }` | `path` 必需，包含 `.claude-plugin/marketplace.json` 的目錄的絕對路徑 |4662| `directory` | `{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }` | `path` 必需，包含 `.claude-plugin/marketplace.json` 的目錄的絕對路徑 |

4639| `hostPattern` | `{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }` | `hostPattern` 必需，針對市集主機符合的正規表達式 |4663| `hostPattern` | `{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }` | `hostPattern` 必需，在 marketplace 主機中任何地方符合的 regex；用 `^` 和 `$` 錨定以符合整個主機 |

4640| `pathPattern` | `{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }` | `pathPattern` 必需，針對 `file` 和 `directory` 來源的 `path` 符合的正規表達式 |4664| `pathPattern` | `{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }` | `pathPattern` 必需，在 `file` 和 `directory` 來源的 `path` 中任何地方符合的 regex；以 `^` 開始以釘選前綴 |

4641| `skills-dir` | `{ "source": "skills-dir" }` | 無欄位。選擇 `~/.claude/skills/` 外掛程式掃描回入 |4665| `skills-dir` | `{ "source": "skills-dir" }` | 無欄位。選擇 `~/.claude/skills/` plugin 掃描回入 |

4642 4666

4643三個來源類型帶有超出表格的規則：4667三個來源類型帶有超出表格的規則：

4644 4668

4645* **`url`**：URL 市集僅下載 `marketplace.json` 檔案，Claude Code 不會從該伺服器按相對路徑擷取外掛程式檔案，因此其外掛程式必須使用 [外掛程式來源](/docs/zh-TW/plugin-marketplaces#plugin-sources)，而不是相對路徑，例如存檔 URL，可以在同一主機上。對於具有相對路徑的外掛程式，請改用基於 Git 的市集。請參閱 [URL 型市集中的相對路徑外掛程式失敗](/docs/zh-TW/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)。4669* **`url`**: URL marketplace 僅下載 `marketplace.json` 檔案，Claude Code 不會從該伺服器按相對路徑擷取 plugin 檔案，因此其 plugins 必須使用 [plugin 來源](/docs/zh-TW/plugins/marketplace-reference#plugin-sources)，而不是相對路徑，例如存檔 URL，可以在同一主機上。對於具有相對路徑的 plugins，請改用基於 Git 的 marketplace。請參閱[URL 型 marketplaces 中的相對路徑 plugins 失敗](/docs/zh-TW/plugins/troubleshooting#plugins-with-relative-paths-fail-in-url-based-marketplaces)。

4646* **`hostPattern`**：使用它允許內部 GitHub Enterprise 或 GitLab 伺服器上的每個市集，而不列出每個儲存庫。Claude Code 針對 `github.com` 符合 `github` 來源，從 `url` 來源取得主機名稱，並根據 [git URL](https://git-scm.com/docs/git-clone#_git_urls) 的形式從 `git` 來源取得：4670* **`hostPattern`**: 使用它允許內部 GitHub Enterprise 或 GitLab 伺服器上的每個 marketplace，而無需列出每個儲存庫。Claude Code 針對 `github.com` 符合 `github` 來源，從 `url` 來源取得主機名稱，並根據 [git URL](https://git-scm.com/docs/git-clone#_git_urls) 的形式從 `git` 來源取得它：

4647 4671

4648 * 具有配置的 URL，例如 `https://` 或 `ssh://`：URL 中的主機名稱。4672 * 具有方案的 URL，例如 `https://` 或 `ssh://`：URL 中的主機名稱。

4649 * 沒有配置的 SSH 位址，採用 git 的 `user@host:path` 形式，例如 `git@git.example.com:tools/plugins.git`：`@` 和 `:` 之間的主機，這是 git 連接到的主機。4673 * 沒有方案的 SSH 位址，採用 git 的 `user@host:path` 形式，例如 `git@git.example.com:tools/plugins.git`：`@` 和 `:` 之間的主機，這是 git 連接到的主機。

4650 * 任何其他沒有配置的形式：沒有主機，因此沒有 `strictKnownMarketplaces` `hostPattern` 項目符合它。對於 `blockedMarketplaces` `hostPattern`，Claude Code 從更廣泛的形式集合中取得主機，因此封鎖清單項目仍可符合此類形式。在 v2.1.234 之前，`strictKnownMarketplaces` `hostPattern` 也符合 git 不視為 SSH 位址的某些形式。4674 * 任何其他沒有方案的形式：沒有主機，因此沒有 `strictKnownMarketplaces` `hostPattern` 項目符合它。對於 `blockedMarketplaces` `hostPattern`，Claude Code 從更廣泛的形式集合中取得主機，因此封鎖清單項目仍可符合此類形式。在 v2.1.234 之前，`strictKnownMarketplaces` `hostPattern` 也符合 git 不視為 SSH 位址的某些形式。

4651 4675

4652 `file` 和 `directory` 來源沒有主機，永遠不符合 `hostPattern` 項目。4676 `file` 和 `directory` 來源沒有主機，永遠不符合 `hostPattern` 項目。

4653* **`pathPattern`**：使用它允許檔案系統市集與網路來源的 `hostPattern` 項目一起。`".*"` 允許每個本機路徑；較窄的模式（例如 `"^/opt/approved/"`）限制到目錄。4677* **`pathPattern`**: 使用它允許檔案系統 marketplaces 與網路來源的 `hostPattern` 項目一起。`".*"` 允許每個本機路徑；較窄的模式（例如 `"^/opt/approved/"`）限制到目錄。

4654 4678

4655任何允許清單，即使是空的，也會停止 Claude Code 從 `~/.claude/skills/` 載入 [`@skills-dir` 外掛程式](/docs/zh-TW/plugins-reference#skills-directory-plugins)。新增 `{ "source": "skills-dir" }` 項目以繼續載入它們；該項目在此金鑰和 `blockedMarketplaces` 之外沒有意義。4679任何允許清單，即使是空的，也會停止 Claude Code 從 `~/.claude/skills/` 載入 [`@skills-dir` plugins](/docs/zh-TW/plugins/loading#plugins-shared-through-a-repository)。新增 `{ "source": "skills-dir" }` 項目以繼續載入它們；該項目在此鍵和 `blockedMarketplaces` 之外沒有意義。

4656 4680

4657<h4 id="owner-wildcards">4681<h4 id="owner-wildcards">

4658 所有者萬用字元4682 所有者萬用字元

4659</h4>4683</h4>

4660 4684

4661`repo` 值為 `"<owner>/*"` 的 `github` 項目符合該 GitHub 所有者下的每個儲存庫。所有者萬用字元需要 Claude Code v2.1.223 或更新版本，僅在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中有效。在 `github` 來源出現的其他地方，例如 `extraKnownMarketplaces` 或 `/plugin marketplace add`，`repo` 值必須命名單個儲存庫。在 v2.1.223 之前，Claude Code 按字面比較項目，因此允許清單項目不符合任何儲存庫，封鎖清單項目不阻止任何內容；單儲存庫項目在每個版本上強制執行。4685`github` 項目，其 `repo` 值為 `"<owner>/*"`，符合該 GitHub 所有者下的每個儲存庫。所有者萬用字元需要 Claude Code v2.1.223 或更新版本，僅在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中運作。在 `github` 來源出現的其他地方，例如 `extraKnownMarketplaces` 或 `/plugin marketplace add`，`repo` 值必須命名單個儲存庫。在 v2.1.223 之前，Claude Code 按字面比較項目，因此允許清單項目不符合任何儲存庫，封鎖清單項目不阻止任何內容；單儲存庫項目在每個版本上強制執行。

4662 4686

4663此項目允許 `acme-corp` 組織中的任何市集儲存庫：4687此項目允許 `acme-corp` 組織中的任何 marketplace 儲存庫：

4664 4688

4665```json managed-settings.json theme={null}4689```json managed-settings.json theme={null}

4666{4690{

4670}4694}

4671```4695```

4672 4696

4673只有整個儲存庫名稱位置可以是萬用字元。Claude Code 按字面比較項目，例如 `*`、`*/plugins` 或 `acme-corp/tools-*`，因此它們不符合任何儲存庫。4697只有整個儲存庫名稱位置可以是萬用字元。Claude Code 忽略項目（例如 `*`、`*/plugins` 或 `acme-corp/tools-*`）作為無效，因此它們不符合任何儲存庫。

4674 4698

4675兩個設定之間的符合規則不同：4699兩個設定之間的符合規則不同：

4676 4700

4678| ------ | ----------------------------------------------------------- | ------------------------------------ |4702| ------ | ----------------------------------------------------------- | ------------------------------------ |

4681| `ref` | 遵循精確項目規則：具有 `ref` 的項目僅符合具有該精確 ref 的來源，沒有項目的項目僅符合不指定 ref 的來源 | 沒有 `ref` 的項目阻止它符合的儲存庫的所有 ref |4705| `ref` | 遵循精確項目規則：具有 `ref` 的項目僅符合具有該精確 ref 的來源，沒有項目的項目僅符合不指定 ref 的來源 | 沒有 `ref` 的項目阻止它符合的儲存庫的所有 refs |

4683 4707

4684<h4 id="exact-matching">4708<h4 id="exact-matching">

4685 精確符合4709 精確符合

4686</h4>4710</h4>

4687 4711

4688對於除所有者萬用字元 `github` 項目和正規表達式符合的 `hostPattern` 和 `pathPattern` 項目之外的每個來源類型，Claude Code 僅在市集來源與項目完全符合時允許使用者的新增。對於基於 git 的來源 `github` 和 `git`，精確符合包括可選欄位：4712對於除所有者萬用字元 `github` 項目和 regex 符合的 `hostPattern` 和 `pathPattern` 項目之外的每個來源類型，Claude Code 僅在 marketplace 來源完全符合項目時允許使用者的新增。對於基於 git 的來源 `github` 和 `git`，精確符合包括可選欄位：

4689 4713

4690* `repo` 或 `url` 必須完全符合4714* `repo` 或 `url` 必須完全符合

4691* `ref` 欄位必須完全符合，或兩者都未定義4715* `ref` 欄位必須完全符合，或兩者都未定義

4697* `{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }` 和 `{ "source": "github", "repo": "acme-corp/plugins" }`4721* `{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }` 和 `{ "source": "github", "repo": "acme-corp/plugins" }`

4698 4722

4699<h4 id="allow-only-the-official-marketplace">4723<h4 id="allow-only-the-official-marketplace">

4700 僅允許官方市集4724 僅允許官方 marketplace

4701</h4>4725</h4>

4702 4726

4703若要僅允許官方 Anthropic 市集，列出其儲存庫：4727若要僅允許官方 Anthropic marketplace，列出其儲存庫：

4704 4728

4705```json managed-settings.json theme={null}4729```json managed-settings.json theme={null}

4706{4730{

4710}4734}

4711```4735```

4712 4736

4713使用此項目，Claude Code 保持已註冊的官方市集可用，並在新機器上，在您首次以互動方式啟動 Claude Code 時自動註冊市集。自動註冊最常遺漏：4737使用此項目，Claude Code 保持已註冊的官方 marketplace 可用，並在新機器上，在您第一次啟動互動式終端機工作階段時自動註冊 marketplace。自動註冊最常遺漏：

4714 4738

4715* 在機器首次互動啟動之前執行的非互動環境。4739* 在機器的第一個互動式終端機工作階段之前執行的非互動式環境。

4716* Claude Code 已在阻止市集的原則下以互動方式執行的機器，例如空陣列鎖定。Claude Code 記錄被阻止的嘗試，不會在原則變更後重試。4740* Claude Code 僅透過 VS Code 擴充功能執行的機器。

4741* Claude Code 已在阻止 marketplace 的原則下執行互動式終端機工作階段的機器，例如空陣列鎖定。Claude Code 記錄被阻止的嘗試，不會在原則變更後重試。

4717 4742

4718在這些機器上，將市集新增到相同 `managed-settings.json` 中的 [`extraKnownMarketplaces`](#extraknownmarketplaces)，以便 Claude Code 自動註冊它，或執行 `claude plugin marketplace add anthropics/claude-plugins-official`。4743在這些機器上，將 marketplace 新增到相同 `managed-settings.json` 中的 [`extraKnownMarketplaces`](#extraknownmarketplaces)，以便 Claude Code 自動註冊它，或執行 `claude plugin marketplace add anthropics/claude-plugins-official`。

4719 4744

4720<h4 id="combine-with-extraknownmarketplaces">4745<h4 id="combine-with-extraknownmarketplaces">

4721 與 `extraKnownMarketplaces` 結合4746 與 `extraKnownMarketplaces` 結合

4722</h4>4747</h4>

4723 4748

4724兩個金鑰執行不同的工作。此表比較它們：4749兩個鍵執行不同的工作。此表比較它們：

4725 4750

4727| ------ | ------------------------- | ----------------------------- |4752| ------ | ------------------------- | ------------------------------- |

4728| 目的 | 組織原則強制執行 | 團隊便利 |4753| 目的 | 組織原則強制執行 | 團隊便利 |

4729| 設定檔 | 僅受管設定 | 任何設定檔 |4754| 設定檔 | 僅受管設定 | 任何設定檔 |

4730| 行為 | 阻止非允許清單新增 | 註冊遺漏的市集 |4755| 行為 | 阻止非允許清單新增 | 註冊遺漏的 marketplaces |

4734 4759

4735若要為所有使用者限制和預先註冊市集，請在 `managed-settings.json` 中設定兩者：4760若要同時限制和預先為所有使用者註冊 marketplace，請在 `managed-settings.json` 中設定兩者：

4736 4761

4737```json managed-settings.json theme={null}4762```json managed-settings.json theme={null}

4738{4763{

4747}4772}

4748```4773```

4749 4774

4750僅設定 `strictKnownMarketplaces` 時，使用者仍可使用 `/plugin marketplace add` 自行新增允許的市集。官方 Anthropic 市集是 Claude Code 自動註冊的唯一市集，僅當允許清單允許時。[僅允許官方市集](#allow-only-the-official-marketplace) 列出它遺漏的機器。4775僅設定 `strictKnownMarketplaces` 時，使用者仍可使用 `/plugin marketplace add` 自行新增允許的 marketplace。官方 Anthropic marketplace 是 Claude Code 自動註冊的唯一 marketplace，僅當允許清單允許時。[僅允許官方 marketplace](#allow-only-the-official-marketplace) 列出它遺漏的機器。

4751 4776

4752<h3 id="strictpluginonlycustomization">4777<h3 id="strictpluginonlycustomization">

4753 `strictPluginOnlyCustomization`4778 `strictPluginOnlyCustomization`

4754</h3>4779</h3>

4755 4780

4756阻止技能、代理、hooks 和 MCP 伺服器來自使用者和專案來源，因此它們只能來自外掛程式或受管設定。將其與 [`strictKnownMarketplaces`](#strictknownmarketplaces) 結合以控制完整的自訂供應鏈：市集允許清單控制使用者可以安裝哪些外掛程式。4781阻止 skills、agents、hooks 和 MCP 伺服器來自使用者和專案來源，因此它們只能來自 plugins 或受管設定。將其與 [`strictKnownMarketplaces`](#strictknownmarketplaces) 結合以控制完整的自訂供應鏈：marketplace 允許清單控制使用者可以安裝哪些 plugins。

4757 4782

4758* **範圍**：[`受管`](#scopes)4783* **Scope**: [`Managed`](#scopes)

4759* **類型**：`true` 以鎖定所有四種自訂，或命名要鎖定的種類的陣列，來自 `"skills"`、`"agents"`、`"hooks"` 和 `"mcp"`4784* **Type**: `true` 以鎖定所有四種自訂，或命名要鎖定的種類的陣列，來自 `"skills"`、`"agents"`、`"hooks"` 和 `"mcp"`

4760* **預設**：未設定，因此沒有任何內容被鎖定4785* **Default**: 未設定，因此沒有任何內容被鎖定

4761 4786

4762此範例鎖定技能和 hooks，並保持代理和 MCP 伺服器解鎖：4787此範例鎖定 skills 和 hooks，並保持 agents 和 MCP 伺服器解鎖：

4763 4788

4764```json managed-settings.json theme={null}4789```json managed-settings.json theme={null}

4765{4790{

4767}4792}

4768```4793```

4769 4794

4770下面的四個子金鑰項目列出每個表面阻止的內容以及仍然載入的內容。Claude Code 忽略它不識別的表面名稱，而不是使設定檔失敗，因此您可以在每個用戶端更新之前新增新的表面名稱。4795下面的四個子鍵項目列出每個表面阻止的內容以及仍然載入的內容。Claude Code 忽略它不識別的表面名稱，而不是使設定檔失敗，因此您可以在每個用戶端更新之前新增新的表面名稱。

4771 4796

4772<h3 id="strictpluginonlycustomization-skills">4797<h3 id="strictpluginonlycustomization-skills">

4773 `strictPluginOnlyCustomization.skills`4798 `strictPluginOnlyCustomization.skills`

4774</h3>4799</h3>

4775 4800

4776鎖定 `skills` 表面。Claude Code 停止從 `~/.claude/skills/` 和 `.claude/skills/`、`~/.claude/commands/` 和 `.claude/commands/` 的自訂命令、`--add-dir` 目錄下的技能以及從您的 claude.ai 帳戶同步的技能載入技能，並繼續載入外掛程式技能、隨附技能和受管原則目錄中的技能。4801鎖定 `skills` 表面。Claude Code 停止從 `~/.claude/skills/` 和 `.claude/skills/`、`~/.claude/commands/` 和 `.claude/commands/` 的自訂命令、`--add-dir` 目錄下的 skills 以及從您的 claude.ai 帳戶同步的 skills 載入 skills，並繼續載入 plugin skills、捆綁的 skills 和受管原則目錄中的 skills。

4777 4802

4778* **範圍**：[`受管`](#scopes)4803* **Scope**: [`Managed`](#scopes)

4779* **類型**：[`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 陣列中的字串 `"skills"`4804* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 陣列中的字串 `"skills"`

4780* **預設**：未鎖定4805* **Default**: 未鎖定

4781 4806

4782```json managed-settings.json theme={null}4807```json managed-settings.json theme={null}

4783{4808{

4789 `strictPluginOnlyCustomization.agents`4814 `strictPluginOnlyCustomization.agents`

4790</h3>4815</h3>

4791 4816

4792鎖定 `agents` 表面。Claude Code 停止從 `~/.claude/agents/` 和 `.claude/agents/` 載入代理，並繼續載入外掛程式代理、內建代理和受管原則目錄中的代理。4817鎖定 `agents` 表面。Claude Code 停止從 `~/.claude/agents/` 和 `.claude/agents/` 載入 agents，並繼續載入 plugin agents、內建 agents 和受管原則目錄中的 agents。

4793 4818

4794* **範圍**：[`受管`](#scopes)4819* **Scope**: [`Managed`](#scopes)

4795* **類型**：[`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 陣列中的字串 `"agents"`4820* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 陣列中的字串 `"agents"`

4796* **預設**：未鎖定4821* **Default**: 未鎖定

4797 4822

4798```json managed-settings.json theme={null}4823```json managed-settings.json theme={null}

4799{4824{

4805 `strictPluginOnlyCustomization.hooks`4830 `strictPluginOnlyCustomization.hooks`

4806</h3>4831</h3>

4807 4832

4808鎖定 `hooks` 表面。Claude Code 停止執行來自使用者、專案和本機 `settings.json` 的 hooks，並繼續執行外掛程式 hooks 和受管設定中的 hooks。4833鎖定 `hooks` 表面。Claude Code 停止執行來自使用者、專案和本機 `settings.json` 的 hooks，並繼續執行 plugin hooks 和受管設定中的 hooks。

4809 4834

4810* **範圍**：[`受管`](#scopes)4835* **Scope**: [`Managed`](#scopes)

4811* **類型**：[`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 陣列中的字串 `"hooks"`4836* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 陣列中的字串 `"hooks"`

4812* **預設**：未鎖定4837* **Default**: 未鎖定

4813 4838

4814```json managed-settings.json theme={null}4839```json managed-settings.json theme={null}

4815{4840{

4821 `strictPluginOnlyCustomization.mcp`4846 `strictPluginOnlyCustomization.mcp`

4822</h3>4847</h3>

4823 4848

4824鎖定 `mcp` 表面。Claude Code 停止從 `~/.claude.json` 和 `.mcp.json` 載入 MCP 伺服器，並繼續載入外掛程式 MCP 伺服器、[`managed-mcp.json`](/docs/zh-TW/managed-mcp) 伺服器和來自 [`managedMcpServers`](#managedmcpservers) 的伺服器。4849鎖定 `mcp` 表面。Claude Code 停止從 `~/.claude.json` 和 `.mcp.json` 載入 MCP 伺服器，並繼續載入 plugin MCP 伺服器、[`managed-mcp.json`](/docs/zh-TW/managed-mcp) 伺服器和來自 [`managedMcpServers`](#managedmcpservers) 的伺服器。

4825 4850

4826* **範圍**：[`受管`](#scopes)4851* **Scope**: [`Managed`](#scopes)

4827* **類型**：[`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 陣列中的字串 `"mcp"`4852* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 陣列中的字串 `"mcp"`

4828* **預設**：未鎖定4853* **Default**: 未鎖定

4829 4854

4830```json managed-settings.json theme={null}4855```json managed-settings.json theme={null}

4831{4856{

4837 `enabledPlugins`4862 `enabledPlugins`

4838</h3>4863</h3>

4839 4864

4840開啟或關閉個別 [外掛程式](/docs/zh-TW/plugins)，由 `plugin-name@marketplace-name` 鍵入。在任何範圍都沒有項目的外掛程式會回退到其 [`defaultEnabled`](/docs/zh-TW/plugins-reference#default-enablement) 值。當您使用 `/plugin` 或 `claude plugin enable` 啟用或停用外掛程式時，Claude Code 會為您寫入此金鑰。4865按 `plugin-name@marketplace-name` 開啟或關閉個別 [plugins](/docs/zh-TW/plugins/overview)。沒有任何範圍項目的 plugin 會回退到其 [`defaultEnabled`](/docs/zh-TW/plugins/manifest-reference#fields) 值。當您使用 `/plugin` 或 `claude plugin enable` 啟用或禁用 plugin 時，Claude Code 會為您寫入此鍵。

4841 4866

4842* **範圍**：[`任何檔案`](#scopes)4867* **Scope**: [`Any file`](#scopes)

4843* **類型**：將 `plugin-name@marketplace-name` 對應到布林值的物件4868* **Type**: 將 `plugin-name@marketplace-name` 對應到 Boolean 的物件

4844* **預設**：未設定，因此每個外掛程式遵循其 `defaultEnabled` 值4869* **Default**: 未設定，因此每個 plugin 遵循其 `defaultEnabled` 值

4845 4870

4846此範例啟用來自 `team-tools` 市集的兩個外掛程式，並停用來自 `personal` 的一個：4871此範例啟用來自 `team-tools` marketplace 的兩個 plugins，並禁用來自 `personal` 的一個：

4847 4872

4848```json settings.json theme={null}4873```json settings.json theme={null}

4849{4874{

4855}4880}

4856```4881```

4857 4882

4858每個範圍服務於不同的目的：4883每個範圍服務不同的目的：

4859 4884

4860* **使用者設定**：您的個人外掛程式偏好設定4885* **使用者設定**: 您的個人 plugin 偏好設定

4861* **專案設定**：與儲存庫中的每個人共享的外掛程式4886* **專案設定**: 與儲存庫中的每個人共享的 plugins

4862* **本機設定**：每台機器的覆寫，當 Claude Code 在那裡儲存設定時被 gitignored4887* **本機設定**: 每台機器的覆寫，當 Claude Code 在那裡儲存設定時被 gitignored

4863* **受管設定**：組織範圍的原則。設定為 `false` 的外掛程式在每個範圍都被阻止安裝，並從市集隱藏4888* **受管設定**: 組織範圍的原則。設定為 `false` 的 plugin 在每個範圍都被阻止安裝，並從 marketplace 隱藏

4864 4889

4865專案設定優先於使用者設定，因此在 `~/.claude/settings.json` 中將外掛程式設定為 `false` 不會停用專案的 `.claude/settings.json` 啟用的外掛程式。若要在您的機器上選擇退出專案啟用的外掛程式，請改為在 `.claude/settings.local.json` 中將其設定為 `false`。由受管設定強制啟用的外掛程式無法以這種方式停用，因為受管設定覆寫本機設定。4890專案設定優先於使用者設定，因此在 `~/.claude/settings.json` 中將 plugin 設定為 `false` 不會禁用專案的 `.claude/settings.json` 啟用的 plugin。若要在您的機器上選擇退出專案啟用的 plugin，請改為在 `.claude/settings.local.json` 中將其設定為 `false`。由受管設定強制啟用的 Plugins 無法以此方式禁用，因為受管設定覆寫本機設定。

4866 4891

4867在專案的 `.claude/settings.json` 中啟用來自外部來源（例如 GitHub 儲存庫或 npm 套件）的外掛程式不會為其他人安裝它。在載入外掛程式的每個路徑上，Claude Code 報告外掛程式未安裝，直到每個使用者 [自行安裝它](/docs/zh-TW/discover-plugins#configure-team-marketplaces)。4892在專案的 `.claude/settings.json` 中啟用來自外部來源（例如 GitHub 儲存庫或 npm 套件）的 plugin 不會為其他人安裝它。在載入 plugins 的每個路徑上，Claude Code 報告 plugin 未安裝，直到每個使用者[自行安裝它](/docs/zh-TW/plugins/org#require-plugins-per-repository)。

4868 4893

4869<h3 id="extraknownmarketplaces">4894<h3 id="extraknownmarketplaces">

4870 `extraKnownMarketplaces`4895 `extraKnownMarketplaces`

4871</h3>4896</h3>

4872 4897

4873按名稱註冊其他外掛程式市集，以便開啟儲存庫的人或受管設定到達的每個人都能獲得市集，而無需自行新增。Claude Code 註冊它尚不知道的每個市集。[`enabledPlugins`](#enabledplugins) 從它命名的外掛程式是否安裝取決於外掛程式的來源以及哪個檔案啟用它；該項目有規則。4898按名稱註冊其他 plugin marketplaces，以便開啟儲存庫的人或受管設定到達的每個人都能獲得 marketplace，而無需自行新增。Claude Code 註冊它尚不知道的每個 marketplace。[`enabledPlugins`](#enabledplugins) 從它命名的 plugin 是否安裝取決於 plugin 的來源和哪個檔案啟用它；該項目有規則。

4874 4899

4875* **範圍**：[`任何檔案`](#scopes)。Claude Code 僅在您接受該資料夾的工作區信任對話框後才接受儲存庫的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目；在您未信任的資料夾中，包括 `-p` 執行，它會在沒有訊息的情況下忽略它們。4900* **Scope**: [`Any file`](#scopes)。Claude Code 僅在您接受該資料夾的工作區信任對話框後，才接受儲存庫的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目；在您未信任的資料夾中，包括 `-p` 執行，它會忽略它們而不顯示訊息。

4876* **類型**：將市集名稱對應到具有 `source` 物件和可選 `autoUpdate` 布林值的物件的物件4901* **Type**: 將 marketplace 名稱對應到具有 `source` 物件和可選 `autoUpdate` Boolean 的物件的物件

4877* **預設**：未設定4902* **Default**: 未設定

4878 4903

4879此範例註冊 GitHub 市集和來自自託管 git URL 的市集：4904此範例註冊 GitHub marketplace 和來自自託管 git URL 的 marketplace：

4880 4905

4881```json settings.json theme={null}4906```json settings.json theme={null}

4882{4907{

4897}4922}

4898```4923```

4899 4924

4900[在您信任資料夾之前執行的內容](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 將信任閘道與儲存庫可以提供的其他內容進行比較。您也可以將此金鑰寫為 `additionalMarketplaces`；請參閱 [市集金鑰別名](#marketplace-key-aliases)。4925[在您信任資料夾之前執行的內容](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)將信任閘道與儲存庫可以提供的其他內容進行比較。您也可以將此鍵寫為 `additionalMarketplaces`；請參閱 [Marketplace 鍵別名](#marketplace-key-aliases)。

4901 4926

4902設定 `"autoUpdate": true` 與 `source` 一起，使 Claude Code 在啟動後在背景重新整理該市集並更新其已安裝的外掛程式。省略時，`claude-plugins-official` 和大多數其他官方 Anthropic 市集預設為 `true`，第三方市集預設為 `false`。請參閱 [配置自動更新](/docs/zh-TW/discover-plugins#configure-auto-updates)。4927在 `source` 旁邊設定 `"autoUpdate": true` 以使 Claude Code 在啟動後在背景中重新整理該 marketplace 並更新其已安裝的 plugins。省略時，`claude-plugins-official` 和大多數其他官方 Anthropic marketplaces 預設為 `true`，第三方 marketplaces 預設為 `false`。請參閱[配置自動更新](/docs/zh-TW/plugins/install#keep-plugins-updated)。

4903 4928

4904當多個設定檔在相同名稱下定義市集項目時，Claude Code 使用來自 [最高優先順序檔案](/docs/zh-TW/settings#settings-precedence) 的項目。該項目取代較低優先順序的項目，不繼承其任何欄位，因此重新定義無法將一個檔案的 `source.headers` 認證與另一個檔案控制的 URL 結合。在 v2.1.228 之前，Claude Code 按欄位合併相同名稱的項目，因此較高優先順序檔案中的項目可能繼承它未設定的欄位，包括另一個檔案的 `headers`。4929當多個設定檔在相同名稱下定義 marketplace 項目時，Claude Code 使用來自[最高優先順序檔案](/docs/zh-TW/settings#settings-precedence)的項目。該項目取代較低優先順序的項目，不繼承其任何欄位，因此重新定義無法將一個檔案的 `source.headers` 認證與另一個檔案控制的 URL 結合。在 v2.1.228 之前，Claude Code 逐欄位合併相同名稱的項目，因此較高優先順序檔案中的項目可能繼承它未設定的欄位，包括另一個檔案的 `headers`。

4905 4930

4906<h4 id="marketplace-source-types">4931<h4 id="marketplace-source-types">

4907 市集來源類型4932 Marketplace 來源類型

4908</h4>4933</h4>

4909 4934

4910`source` 物件採用以下其中一種形式：4935`source` 物件採用以下形式之一：

4911 4936

4912* **`github`**：GitHub 儲存庫，具有 `repo`4937* **`github`**: GitHub 儲存庫，具有 `repo`

4913* **`git`**：任何 git URL，具有 `url`4938* **`git`**: 任何 git URL，具有 `url`

4914* **`url`**：直接 URL 到 `marketplace.json` 檔案，具有 `url` 和可選 `headers` 和 `headersHelper` 用於已驗證存取。`headersHelper` 命名列印標頭的命令，其值太短暫而無法在 `headers` 中列出，並需要 Claude Code v2.1.238 或更新版本4939* **`url`**: 直接 URL 到 `marketplace.json` 檔案，具有 `url` 和可選 `headers` 和 `headersHelper` 用於已驗證存取。`headersHelper` 命名列印標頭的命令，其值太短暫而無法在 `headers` 中列出，並需要 Claude Code v2.1.238 或更新版本

4915* **`file`**：`marketplace.json` 檔案的本機路徑，具有 `path`4940* **`file`**: 到 `marketplace.json` 檔案的本機路徑，具有 `path`

4916* **`directory`**：本機檔案系統路徑，具有 `path`，僅用於開發4941* **`directory`**: 本機檔案系統路徑，具有 `path`，僅用於開發

4917* **`settings`**：直接在設定檔中宣告的內嵌市集，無需託管儲存庫，具有 `name` 和 `plugins`4942* **`settings`**: 直接在設定檔中宣告的內嵌 marketplace，無需託管儲存庫，具有 `name` 和 `plugins`

4918 4943

4919`git` 來源類型適用於任何 git 託管服務，包括自託管 GitLab 和 Bitbucket。Claude Code 使用 `git clone` 在該機器上使用的相同驗證複製儲存庫：已配置的認證助手或 SSH 金鑰。提供者令牌（例如 `GITHUB_TOKEN`）僅透過讀取它的認證助手生效。請參閱 [私人儲存庫](/docs/zh-TW/plugin-marketplaces#private-repositories) 以取得設定詳細資訊。4944`git` 來源類型適用於任何 git 託管服務，包括自託管 GitLab 和 Bitbucket。Claude Code 使用 `git clone` 在該機器上使用的相同驗證複製儲存庫：已配置的認證助手或 SSH 金鑰。提供者令牌（例如 `GITHUB_TOKEN`）透過讀取它的認證助手生效。請參閱[私人儲存庫](/docs/zh-TW/plugins/host-marketplace#grant-access-to-a-private-marketplace)以取得設定詳細資訊。

4920 4945

4921對於 `github` 和 `git` 來源，Claude Code 在複製市集儲存庫以新增或更新時永遠不會下載 [Git LFS](https://git-lfs.com) 內容。LFS 追蹤的檔案會簽出為指標檔案，新增或更新輸出會報告有多少個。4946對於 `github` 和 `git` 來源，Claude Code 在複製 marketplace 儲存庫以新增或更新它時永遠不會下載 [Git LFS](https://git-lfs.com) 內容。LFS 追蹤的檔案簽出為指標檔案，新增或更新輸出報告有多少。

4922 4947

4923`skipLfs` 欄位在 `source` 物件內被接受且沒有效果。在 v2.1.274 之前，Claude Code 下載 LFS 內容，除非您設定 `"skipLfs": true`。4948`source` 物件內的 `skipLfs` 欄位被接受且沒有效果。在 v2.1.274 之前，Claude Code 下載 LFS 內容，除非您設定 `"skipLfs": true`。

4924 4949

4925對於 `url` 來源，當 `headers` 中的認證過期且命令必須產生新認證時，在 `source` 物件內設定 `headersHelper`。需要 Claude Code v2.1.238 或更新版本。如需命令必須列印的內容以及 Claude Code 執行它的位置，請參閱 [編寫 headersHelper 命令](/docs/zh-TW/plugin-marketplaces#write-the-headershelper-command)，以及 Claude Code 不執行它的情況，請參閱 [何時 Claude Code 跳過 headersHelper 命令](/docs/zh-TW/plugin-marketplaces#when-claude-code-skips-a-headershelper-command-or-drops-its-output)。在 `https://` 市集 URL 上設定 `headersHelper` 後，Claude Code 在兩個點執行命令，重複使用一次執行的輸出長達 60 秒：4950對於 `url` 來源，當 `headers` 中的認證過期且命令必須產生新的認證時，在 `source` 物件內設定 `headersHelper`。需要 Claude Code v2.1.238 或更新版本。如需命令必須列印的內容以及 Claude Code 執行它的位置，請參閱[編寫 headersHelper 命令](/docs/zh-TW/plugins/host-marketplace#write-the-headershelper-command)，以及 Claude Code 不執行它的情況，請參閱[何時 Claude Code 跳過 headersHelper 命令或丟棄其輸出](/docs/zh-TW/plugins/host-marketplace#when-claude-code-skips-a-headershelper-command-or-drops-its-output)。一旦您在 `https://` marketplace URL 上設定 `headersHelper`，Claude Code 在兩個點執行命令，重複使用一次執行的輸出長達 60 秒：

4926 4951

4927* 在該市集 `marketplace.json` 的每次擷取之前，包括稍後的重新整理。Claude Code 使用該擷取傳送列印的標頭。4952* 在該 marketplace 的 `marketplace.json` 的每次擷取之前，包括稍後的重新整理。Claude Code 使用該擷取傳送列印的標頭。

4928* 在市集 URL 來源上的每個外掛程式存檔下載之前，意思是相同的配置、主機和連接埠。Claude Code 使用該下載傳送輸出，沒有其他下載獲得標頭。4953* 在 marketplace URL 來源上的每個 plugin 存檔下載之前，意味著相同的方案、主機和連接埠。Claude Code 使用該下載傳送輸出，沒有其他下載獲得標頭。

4929 4954

4930Claude Code 忽略在您使用 [`--add-dir`](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 新增的目錄的 `.claude/settings.json` 或 `.claude/settings.local.json` 中設定的任何 `headersHelper`，在 `url` 來源和內嵌外掛程式項目上，並僅傳送在該檔案中設定的固定 `headers`。[使用者如何接受 headersHelper 命令](/docs/zh-TW/plugin-marketplaces#how-users-accept-a-headershelper-command) 涵蓋其他設定檔。4955Claude Code 忽略在您使用 [`--add-dir`](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 新增的目錄的 `.claude/settings.json` 或 `.claude/settings.local.json` 中設定的任何 `headersHelper`，在 `url` 來源和內嵌 plugin 項目上，並僅傳送在該檔案中設定的固定 `headers`。[使用者如何接受 headersHelper 命令](/docs/zh-TW/plugins/host-marketplace#how-users-accept-a-headershelper-command)涵蓋其他設定檔。

4931 4956

4932在 `settings` 來源中列出的外掛程式必須參考外部來源（例如 GitHub 或 npm），`name` 必須符合市集金鑰。您仍需在 `enabledPlugins` 中分別啟用每個外掛程式。此範例宣告一個內嵌外掛程式：4957`settings` 來源中列出的 Plugins 必須參考外部來源（例如 GitHub 或 npm），`name` 必須符合 marketplace 鍵。您仍然在 `enabledPlugins` 中分別啟用每個 plugin。此範例內嵌宣告一個 plugin：

4933 4958

4934```json settings.json theme={null}4959```json settings.json theme={null}

4935{4960{

4953}4978}

4954```4979```

4955 4980

4956在 `source: 'settings'` 下的外掛程式項目，其自身 `source` 是 [`archive`](/docs/zh-TW/plugin-marketplaces#zip-archives)，可以為存檔下載設定 `headers`。如果您要放在 `headers` 中的值是短暫的，例如您的登錄機構應要求時鑄造的令牌，請改為設定 `headersHelper` 命令。項目可能同時設定兩者。兩個欄位都需要 Claude Code v2.1.238 或更新版本。4981`source: 'settings'` 下其自身 `source` 是 [`archive`](/docs/zh-TW/plugins/marketplace-reference#archive-plugin-source) 的 plugin 項目可以為存檔下載設定 `headers`。如果您要放在 `headers` 中的值是短暫的，例如您的登錄機構應要求時鑄造的令牌，請改為設定 `headersHelper` 命令。項目可能同時設定兩者。兩個欄位都需要 Claude Code v2.1.238 或更新版本。

4957 4982

4958Claude Code 傳送項目的 `headers` 和命令列印的任何內容，與該外掛程式的存檔下載以及沒有其他下載。Claude Code 僅在使用者 [自行安裝或更新該一個外掛程式](/docs/zh-TW/plugin-marketplaces#how-users-accept-a-headershelper-command) 時執行命令。三個進一步的規則取決於哪個檔案保持項目：4983Claude Code 傳送項目的 `headers` 和命令列印的任何內容，與該 plugin 的存檔下載以及沒有其他下載。Claude Code 僅在使用者[自行安裝或更新該一個 plugin](/docs/zh-TW/plugins/host-marketplace#how-users-accept-a-headershelper-command) 時執行命令。三個進一步的規則取決於哪個檔案持有項目：

4959 4984

4960* **`strict`**：與市集 `marketplace.json` 中的項目不同，設定檔中的項目不需要 `"strict": false`，因為設定檔不帶有要內嵌的清單欄位。請參閱 [嚴格模式](/docs/zh-TW/plugin-marketplaces#strict-mode)。4985* **`strict`**: 與 marketplace 的 `marketplace.json` 中的項目不同，設定檔中的項目不需要 `"strict": false`，因為設定檔不帶有要內嵌的清單欄位。請參閱[嚴格模式](/docs/zh-TW/plugins/marketplace-reference#strict-mode)。

4961* **資料夾信任**：對於專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目，Claude Code 僅在使用者也 [信任該資料夾](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 後執行命令。4986* **資料夾信任**: 對於專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目，Claude Code 僅在使用者也[信任該資料夾](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)後執行命令。

4962* **標頭篩選**：Claude Code 從專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目中刪除 [要求路由和用戶端身分標頭名稱](/docs/zh-TW/plugin-marketplaces#when-claude-code-skips-a-headershelper-command-or-drops-its-output)，因為儲存庫可以提供這些檔案。Claude Code 將相同的篩選套用到目錄項目和 `--add-dir` 目錄設定中的項目，不篩選您的使用者設定、`--settings` 檔案或受管設定中的項目。4987* **標頭篩選**: Claude Code 從專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目丟棄[請求路由和用戶端身份標頭名稱](/docs/zh-TW/plugins/host-marketplace#when-claude-code-skips-a-headershelper-command-or-drops-its-output)，因為儲存庫可以提供這些檔案。Claude Code 將相同的篩選套用到目錄項目和 `--add-dir` 目錄的設定中的項目，並且不篩選您的使用者設定、`--settings` 檔案或受管設定中的項目。

4963 4988

4964<h4 id="marketplace-key-aliases">4989<h4 id="marketplace-key-aliases">

4965 市集金鑰別名4990 Marketplace 鍵別名

4966</h4>4991</h4>

4967 4992

4968在 Claude Code v2.1.232 或更新版本上，您可以將 `extraKnownMarketplaces` 寫為 `additionalMarketplaces`，將 `strictKnownMarketplaces` 寫為 `allowedMarketplaces`。Claude Code 按如下方式處理每個別名：4993在 Claude Code v2.1.232 或更新版本上，您可以將 `extraKnownMarketplaces` 寫為 `additionalMarketplaces`，將 `strictKnownMarketplaces` 寫為 `allowedMarketplaces`。Claude Code 按如下方式處理每個別名：

4969 4994

4970* 較早版本忽略別名，因此在較舊版本也讀取的檔案中保持規範拼寫，例如具有混合 Claude Code 版本的機隊的受管設定檔案。4995* 較早版本忽略別名，因此在較舊版本也讀取的檔案中保持規範拼寫，例如具有混合 Claude Code 版本的機隊的受管設定檔案。

4971* 在接受規範金鑰的任何設定檔中，Claude Code 完全按照讀取規範金鑰的方式讀取別名。4996* 在接受規範鍵的任何設定檔中，Claude Code 完全按照讀取規範鍵的方式讀取別名。

4972* Claude Code 在更新檔案時可能將 `additionalMarketplaces` 重寫為 `extraKnownMarketplaces`。4997* Claude Code 在更新檔案時可能將 `additionalMarketplaces` 重寫為 `extraKnownMarketplaces`。

4973* 如果您在一個檔案中設定兩個拼寫，Claude Code 使用規範值並忽略別名。4998* 如果您在一個檔案中設定兩個拼寫，Claude Code 使用規範值並忽略別名。

4974 4999

4976 `pluginConfigs`5001 `pluginConfigs`

4977</h3>5002</h3>

4978 5003

4979儲存您提供給外掛程式 [`userConfig`](/docs/zh-TW/plugins-reference#user-configuration) 配置對話框的非敏感答案，由外掛程式 ID 鍵入。當您填寫對話框時，Claude Code 將此金鑰寫入您的使用者設定，因此您無需手動編輯它。Claude Code 將敏感選項儲存在 macOS Keychain 中，當 Keychain 拒絕寫入時回退到 `~/.claude/.credentials.json`；在沒有支援的 keychain 的平台上，它將它們儲存在 `~/.claude/.credentials.json`。5004儲存您為 plugin 的 [`userConfig`](/docs/zh-TW/plugins/manifest-reference#user-configuration) 配置對話框提供的非敏感答案，按 plugin ID 鍵入。當您填寫對話框時，Claude Code 將此鍵寫入您的使用者設定，因此您無需手動編輯它。Claude Code 將敏感選項儲存在 macOS Keychain 中，當 Keychain 拒絕寫入時回退到 `~/.claude/.credentials.json`；在沒有支援的 keychain 的平台上，它將它們儲存在 `~/.claude/.credentials.json` 中。

4980 5005

4981* **範圍**：[`使用者或受管`](#scopes)5006* **Scope**: [`User or managed`](#scopes)

4982* **類型**：將外掛程式 ID 對應到具有 `options` 欄位的物件，將每個選項名稱對應到字串、數字、布林值或字串陣列，以及保持每個伺服器使用者配置值的可選 `mcpServers` 欄位，形式相同5007* **Type**: 將 plugin ID 對應到具有 `options` 欄位的物件的物件，將每個選項名稱對應到字串、數字、Boolean 或字串陣列，以及可選的 `mcpServers` 欄位，以相同形狀持有每伺服器使用者配置值

4983* **預設**：未設定5008* **Default**: 未設定

4984 5009

4985此範例儲存來自 `acme-tools` 的 `deployer` 外掛程式的 `api_endpoint` 選項：5010此範例儲存來自 `acme-tools` 的 `deployer` plugin 的 `api_endpoint` 選項：

4986 5011

4987```json settings.json theme={null}5012```json settings.json theme={null}

4988{5013{

4996}5021}

4997```5022```

4998 5023

4999內建外掛程式使用相同的金鑰與 `@builtin` 後綴儲存其選項。例如，[**專案指示**](/docs/zh-TW/memory#choose-which-instruction-files-load) 設定（控制 Claude Code 是否讀取 `AGENTS.md` 檔案）是 `pluginConfigs["agents-md@builtin"].options.instructionFiles`。5024內建 plugins 在相同鍵下儲存其選項，帶有 `@builtin` 後綴。例如，控制 Claude Code 是否讀取 `AGENTS.md` 檔案的[**專案指示**](/docs/zh-TW/memory#choose-which-instruction-files-load)設定是 `pluginConfigs["agents-md@builtin"].options.instructionFiles`。

5000 5025

5001Claude Code 忽略專案和本機項目，因為它將這些值替換到外掛程式 hook、MCP 和 LSP 配置中，而複製的儲存庫不得能夠提供它們。在 v2.1.207 之前，也讀取了專案和本機設定。5026Claude Code 忽略專案和本機項目，因為它將這些值替換到 plugin hook、MCP 和 LSP 配置中，複製的儲存庫不得能夠提供它們。在 v2.1.207 之前，專案和本機設定也被讀取。

5002 5027

5003<h2 id="mcp">5028<h2 id="mcp">

5004 MCP5029 MCP

5224}5249}

5225```5250```

5226 5251

5227外掛程式自己的 `settings.json` 也可以提供此金鑰；請參閱 [Ship default settings with your plugin](/docs/zh-TW/plugins#ship-default-settings-with-your-plugin)。5252外掛程式自己的 `settings.json` 也可以提供此金鑰；請參閱 [Ship default settings with your plugin](/docs/zh-TW/plugins/components#default-settings)。

5228 5253

5229<h3 id="crosssessioninbound">5254<h3 id="crosssessioninbound">

5230 `crossSessionInbound`5255 `crossSessionInbound`

5320 * `"in-process"`: 隊友在您的主終端窗格內執行5345 * `"in-process"`: 隊友在您的主終端窗格內執行

5321 * `"auto"`: 當您在 tmux 內執行時分割窗格，或在 iTerm2 內執行且 `it2` 在您的 `PATH` 上或安裝了 tmux；否則為 in-process5346 * `"auto"`: 當您在 tmux 內執行時分割窗格，或在 iTerm2 內執行且 `it2` 在您的 `PATH` 上或安裝了 tmux；否則為 in-process

5322 * `"tmux"`: 使用 tmux 或 iTerm2 分割窗格，從您的終端偵測5347 * `"tmux"`: 使用 tmux 或 iTerm2 分割窗格，從您的終端偵測

5323 * `"iterm2"`: iTerm2 原生分割窗格透過 `it2` CLI，在 Claude Code v2.1.186 或更新版本中5348 * `"iterm2"`: iTerm2 原生分割窗格透過 `it2` CLI

5324* **Default**: `"in-process"`5349* **Default**: `"in-process"`

5325* **Per-session overrides**: `--teammate-mode` 對一個工作階段優先於此金鑰5350* **Per-session overrides**: `--teammate-mode` 對一個工作階段優先於此金鑰

5326 5351

5330}5355}

5331```5356```

5332 5357

5333`iterm2` 值需要 Claude Code v2.1.186 或更新版本。

~~5334~~

5335<span id="worktree-settings" />5358<span id="worktree-settings" />

5336 5359

5337<h3 id="worktree">5360<h3 id="worktree">

6191 6214

6192Claude Code 仍然接受其伺服器全部為同處理序 `type: "sdk"` 項目的 `--mcp-config`，因此 Agent SDK 和 VS Code 擴充功能保持運作。使用者仍然可以使用 `claude mcp add` 或 `.mcp.json` 檔案新增伺服器；如需個別伺服器控制，也請設定 [`allowedMcpServers`](/docs/zh-TW/managed-mcp)。需要 Claude Code v2.1.193 或更新版本。6215Claude Code 仍然接受其伺服器全部為同處理序 `type: "sdk"` 項目的 `--mcp-config`，因此 Agent SDK 和 VS Code 擴充功能保持運作。使用者仍然可以使用 `claude mcp add` 或 `.mcp.json` 檔案新增伺服器；如需個別伺服器控制，也請設定 [`allowedMcpServers`](/docs/zh-TW/managed-mcp)。需要 Claude Code v2.1.193 或更新版本。

6193 6216

6217相同的檢查涵蓋在 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-TW/env-vars#variables) 環境變數中命名的外掛程式資料夾，這需要 Claude Code v2.1.280 或更新版本。當變數命名資料夾時，Claude Code 會以相同的錯誤結束，錯誤會說要取消設定變數。

6218

6194在雲端工作階段中，Claude Code 也會忽略伺服器傳遞的中途工作階段 MCP 更新，這是雲端工作階段設定和 SDK `setMcpServers()` 呼叫背後的路徑，這些呼叫到達這些工作階段。同處理序 `type: "sdk"` 項目在那裡也保持豁免。在 v2.1.239 之前，伺服器傳遞的 `--mcp-config` 會阻止雲端工作階段啟動。6219在雲端工作階段中，Claude Code 也會忽略伺服器傳遞的中途工作階段 MCP 更新，這是雲端工作階段設定和 SDK `setMcpServers()` 呼叫背後的路徑，這些呼叫到達這些工作階段。同處理序 `type: "sdk"` 項目在那裡也保持豁免。在 v2.1.239 之前，伺服器傳遞的 `--mcp-config` 會阻止雲端工作階段啟動。

6195 6220

6196<h3 id="forceremotesettingsrefresh">6221<h3 id="forceremotesettingsrefresh">

skills.md +15 −15

Details

129| 專案 | `.claude/skills/<skill-name>/SKILL.md` | 此版本庫中的工作階段。提交它，您的團隊也會獲得它 |129| 專案 | `.claude/skills/<skill-name>/SKILL.md` | 此版本庫中的工作階段。提交它，您的團隊也會獲得它 |

130| 巢狀 | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | 在 `<subdir>` 中或其下方啟動的工作階段。在其上方啟動的工作階段在 Claude 處理該處的檔案時會載入該技能。請參閱[單一版本庫和子目錄](#discovery-from-parent-and-nested-directories) |130| 巢狀 | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | 在 `<subdir>` 中或其下方啟動的工作階段。在其上方啟動的工作階段在 Claude 處理該處的檔案時會載入該技能。請參閱[單一版本庫和子目錄](#discovery-from-parent-and-nested-directories) |

134 134

135技能資料夾也遵循以下規則：135技能資料夾也遵循以下規則：

136 136

137* **符號連結資料夾**：企業、個人或專案位置中的 `<skill-name>` 項目可以是磁碟上其他位置目錄的符號連結。Claude Code 從目標讀取 `SKILL.md` 並載入技能一次，即使多個位置指向同一目標。外掛程式技能[以不同方式處理符號連結](/docs/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks)。137* **符號連結資料夾**：企業、個人或專案位置中的 `<skill-name>` 項目可以是磁碟上其他位置目錄的符號連結。Claude Code 從目標讀取 `SKILL.md` 並載入技能一次，即使多個位置指向同一目標。外掛程式技能[以不同方式處理符號連結](/docs/zh-TW/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)。

138* **保留名稱**：不要將技能資料夾命名為 `synced`，無論大小寫如何。Claude Code 使用 `~/.claude/skills/synced/` 來[儲存從 claude.ai 下載的技能](#where-synced-skills-load)，並跳過您在企業、個人和專案位置中以該名稱編寫的技能。138* **保留名稱**：不要將技能資料夾命名為 `synced`，無論大小寫如何。Claude Code 使用 `~/.claude/skills/synced/` 來[儲存從 claude.ai 下載的技能](#where-synced-skills-load)，並跳過您在企業、個人和專案位置中以該名稱編寫的技能。

139* **命令檔案**：`.claude/commands/` 中的 Markdown 檔案是較舊的格式，仍然有效。它支援相同的[前置資料](#frontmatter-reference)，除了 `name` 和 `paths`。若要找到您輸入以叫用它的名稱，請參閱[技能如何獲得其命令名稱](#how-a-skill-gets-its-command-name)。對於新工作，建議使用技能，因為技能也支援[支援檔案](#add-supporting-files)。139* **命令檔案**：`.claude/commands/` 中的 Markdown 檔案是較舊的格式，仍然有效。它支援相同的[前置資料](#frontmatter-reference)，除了 `name` 和 `paths`。若要找到您輸入以叫用它的名稱，請參閱[技能如何獲得其命令名稱](#how-a-skill-gets-its-command-name)。對於新工作，建議使用技能，因為技能也支援[支援檔案](#add-supporting-files)。

140* **技能資料夾作為外掛程式**：將 `.claude-plugin/plugin.json` 新增到技能資料夾，它會載入為[外掛程式](/docs/zh-TW/plugins-reference#skills-directory-plugins)，名稱為 `<name>@skills-dir`，因此可以捆綁代理、hooks 和 MCP 伺服器。在專案的 `.claude/skills/` 中，這需要先接受工作區信任對話。140* **技能資料夾作為外掛程式**：將 `.claude-plugin/plugin.json` 新增到技能資料夾，它會載入為[外掛程式](/docs/zh-TW/plugins/loading#plugins-shared-through-a-repository)，名稱為 `<name>@skills-dir`，因此可以捆綁代理、hooks 和 MCP 伺服器。在專案的 `.claude/skills/` 中，這需要先接受工作區信任對話。

141 141

142<h3 id="discovery-from-parent-and-nested-directories">142<h3 id="discovery-from-parent-and-nested-directories">

143 在單一版本庫和子目錄中載入技能143 在單一版本庫和子目錄中載入技能

275 275

276Claude Code 監視技能目錄的檔案變更，除了在[裸機模式](/docs/zh-TW/headless#start-faster-with-bare-mode)中。當您在 `~/.claude/skills/`、專案 `.claude/skills/` 或 `--add-dir` 目錄內的 `.claude/skills/` 中新增、編輯或移除技能時，Claude Code 在目前工作階段內拾取變更，無需重新啟動。如果您建立在工作階段啟動時不存在的頂層技能目錄，請重新啟動 Claude Code，以便它可以監視新目錄。276Claude Code 監視技能目錄的檔案變更，除了在[裸機模式](/docs/zh-TW/headless#start-faster-with-bare-mode)中。當您在 `~/.claude/skills/`、專案 `.claude/skills/` 或 `--add-dir` 目錄內的 `.claude/skills/` 中新增、編輯或移除技能時，Claude Code 在目前工作階段內拾取變更，無需重新啟動。如果您建立在工作階段啟動時不存在的頂層技能目錄，請重新啟動 Claude Code，以便它可以監視新目錄。

277 277

278即時變更偵測僅涵蓋 `SKILL.md` 文字。對於也是[外掛程式](/docs/zh-TW/plugins-reference#skills-directory-plugins)的技能資料夾，`hooks/`、`.mcp.json`、`agents/` 和 `output-styles/` 的變更需要 `/reload-plugins` 才能生效。278即時變更偵測僅涵蓋 `SKILL.md` 文字。對於也是[外掛程式](/docs/zh-TW/plugins/loading#plugins-shared-through-a-repository)的技能資料夾，`hooks/`、`.mcp.json`、`agents/` 和 `output-styles/` 的變更需要 `/reload-plugins` 才能生效。

279 279

280<h3 id="remove-a-skill">280<h3 id="remove-a-skill">

281 移除技能281 移除技能

285 285

286* **個人或專案技能**：刪除技能的目錄，`~/.claude/skills/<skill-name>/` 或 `.claude/skills/<skill-name>/`。Claude Code [在目前工作階段中將其從 `/skills` 中移除](#live-change-detection)；Claude Code 已從其載入的內容遵循[技能內容生命週期](#skill-content-lifecycle)。286* **個人或專案技能**：刪除技能的目錄，`~/.claude/skills/<skill-name>/` 或 `.claude/skills/<skill-name>/`。Claude Code [在目前工作階段中將其從 `/skills` 中移除](#live-change-detection)；Claude Code 已從其載入的內容遵循[技能內容生命週期](#skill-content-lifecycle)。

287* **企業技能**：管理員從[受管設定目錄](/docs/zh-TW/managed-settings#delivery-mechanisms)內的 `.claude/skills/` 中刪除技能的目錄，例如 Linux 上的 `/etc/claude-code/.claude/skills/<skill-name>/`。287* **企業技能**：管理員從[受管設定目錄](/docs/zh-TW/managed-settings#delivery-mechanisms)內的 `.claude/skills/` 中刪除技能的目錄，例如 Linux 上的 `/etc/claude-code/.claude/skills/<skill-name>/`。

288* **外掛程式技能**：從 `/plugin` 功能表停用或解除安裝提供它的外掛程式，或使用 `/plugin uninstall <plugin-name>@<marketplace-name>`。當[變更適用](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)或您重新啟動時，Claude Code 卸載外掛程式的技能。288* **外掛程式技能**：從 `/plugin` 功能表停用或解除安裝提供它的外掛程式，或使用 `/plugin uninstall <plugin-name>@<marketplace-name>`。當[變更適用](/docs/zh-TW/plugins/cli-reference#reload-plugins)或您重新啟動時，Claude Code 卸載外掛程式的技能。

289* **從 claude.ai 同步的技能**：在您[啟用它](#skills-in-cowork-and-cloud-sessions)的相同位置為您的 claude.ai 帳戶關閉該技能。Claude Code 在下一次[同步您的技能](#where-synced-skills-load)時將其從 `~/.claude/skills/synced/` 中移除。如果您改為手動刪除目錄，下一次同步會在技能在 claude.ai 上保持啟用時再次下載它。289* **從 claude.ai 同步的技能**：在您[啟用它](#skills-in-cowork-and-cloud-sessions)的相同位置為您的 claude.ai 帳戶關閉該技能。Claude Code 在下一次[同步您的技能](#where-synced-skills-load)時將其從 `~/.claude/skills/synced/` 中移除。如果您改為手動刪除目錄，下一次同步會在技能在 claude.ai 上保持啟用時再次下載它。

290* **捆綁技能**：將 [`disableBundledSkills`](#bundled-skills) 設定為 `true` 以關閉捆綁技能，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將一個技能設定為 `"off"` 以隱藏它。290* **捆綁技能**：將 [`disableBundledSkills`](#bundled-skills) 設定為 `true` 以關閉捆綁技能，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將一個技能設定為 `"off"` 以隱藏它。

291 291

389 389

390| 分發路徑 | 您可以使用的 Frontmatter 欄位 |390| 分發路徑 | 您可以使用的 Frontmatter 欄位 |

391| :--------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |391| :--------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |

392| Claude Code skills 在[任何級別](#where-skills-live)，包括[插件](/docs/zh-TW/plugins) skills | 上表中的每個欄位 |392| Claude Code skills 在[任何級別](#where-skills-live)，包括[插件](/docs/zh-TW/plugins/overview) skills | 上表中的每個欄位 |

393| claude.ai skill 上傳、Skills API 和使用 [anthropics/skills](https://github.com/anthropics/skills) 中的 `package_skill.py` 進行打包 | `name`、`description`、`license`、`compatibility`、`metadata`、`allowed-tools` |393| claude.ai skill 上傳、Skills API 和使用 [anthropics/skills](https://github.com/anthropics/skills) 中的 `package_skill.py` 進行打包 | `name`、`description`、`license`、`compatibility`、`metadata`、`allowed-tools` |

394 394

395當您為 claude.ai 帳戶啟用個人 skill 時（例如在 [Cowork 和雲端工作階段](#skills-in-cowork-and-cloud-sessions)和例行程序中使用它），您將其上傳到 claude.ai，因此適用相同的規則。395當您為 claude.ai 帳戶啟用個人 skill 時（例如在 [Cowork 和雲端工作階段](#skills-in-cowork-and-cloud-sessions)和例行程序中使用它），您將其上傳到 claude.ai，因此適用相同的規則。

411下表顯示了每個佈局的命令名稱來自何處：411下表顯示了每個佈局的命令名稱來自何處：

412 412

413| Skill 位置 | 命令名稱來源 | 範例 |413| Skill 位置 | 命令名稱來源 | 範例 |

414| :-------------------------------------------------------------- | :--------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |414| :-------------------------------------------------------------- | :--------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |

420| 插件根 `SKILL.md` | Frontmatter `name`，以插件目錄名稱作為後備 | `my-plugin/SKILL.md` 帶有 `name: review` → `/my-plugin:review`。請參閱[路徑行為規則](/docs/zh-TW/plugins-reference#path-behavior-rules) |420| 插件根 `SKILL.md` | Frontmatter `name`，以插件目錄名稱作為後備 | `my-plugin/SKILL.md` 帶有 `name: review` → `/my-plugin:review`。請參閱[單一 skill 在插件根](/docs/zh-TW/plugins/components#skills) |

421| Skill [從 claude.ai 同步](#how-synced-skills-behave) | 您 claude.ai 帳戶上 skill 的名稱，前綴為 `anthropic-skills:` | 帳戶 skill `deploy` → `/anthropic-skills:deploy`，或在沒有其他命令使用該名稱時為 `/deploy` |421| Skill [從 claude.ai 同步](#how-synced-skills-behave) | 您 claude.ai 帳戶上 skill 的名稱，前綴為 `anthropic-skills:` | 帳戶 skill `deploy` → `/anthropic-skills:deploy`，或在沒有其他命令使用該名稱時為 `/deploy` |

422 422

423在插件 skill 中，frontmatter `name` 替換命令最後一段中的目錄名稱，因此 `my-plugin/skills/review/SKILL.md` 帶有 `name: fancy` 變成 `/my-plugin:fancy`。裸 `/fancy` 也調用 skill，除非另一個命令已使用該名稱。如果您寫的 `name` 已經以插件自己的前綴開頭，Claude Code 在 v2.1.246 或更新版本上不會再次添加前綴。例如，`name: my-plugin:fancy` 仍然變成 `/my-plugin:fancy`。從 v2.1.216 到 v2.1.245，當 `name` 已經帶有它時，Claude Code 會加倍前綴。423在插件 skill 中，frontmatter `name` 替換命令最後一段中的目錄名稱，因此 `my-plugin/skills/review/SKILL.md` 帶有 `name: fancy` 變成 `/my-plugin:fancy`。裸 `/fancy` 也調用 skill，除非另一個命令已使用該名稱。如果您寫的 `name` 已經以插件自己的前綴開頭，Claude Code 在 v2.1.246 或更新版本上不會再次添加前綴。例如，`name: my-plugin:fancy` 仍然變成 `/my-plugin:fancy`。從 v2.1.216 到 v2.1.245，當 `name` 已經帶有它時，Claude Code 會加倍前綴。

442| `${CLAUDE_EFFORT}` | 目前努力級別：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一個不同的級別，報告為 `xhigh`。使用此來根據活動努力設定調整 skill 指示。 |442| `${CLAUDE_EFFORT}` | 目前努力級別：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一個不同的級別，報告為 `xhigh`。使用此來根據活動努力設定調整 skill 指示。 |

443| `${CLAUDE_SKILL_DIR}` | 包含 skill 的 `SKILL.md` 檔案的目錄。對於插件 skills，這是插件內 skill 的子目錄，而不是插件根。在 bash 注入命令中使用此來參考與 skill 捆綁的指令碼或檔案，無論目前工作目錄如何。 |443| `${CLAUDE_SKILL_DIR}` | 包含 skill 的 `SKILL.md` 檔案的目錄。對於插件 skills，這是插件內 skill 的子目錄，而不是插件根。在 bash 注入命令中使用此來參考與 skill 捆綁的指令碼或檔案，無論目前工作目錄如何。 |

444| `${CLAUDE_PROJECT_DIR}` | 專案根目錄。這是 [hooks](/docs/zh-TW/hooks#reference-scripts-by-path) 和 MCP 伺服器作為 `CLAUDE_PROJECT_DIR` 接收的相同路徑。使用此來參考專案本地指令碼或檔案，例如 `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`，獨立於 skill 的安裝位置。 |444| `${CLAUDE_PROJECT_DIR}` | 專案根目錄。這是 [hooks](/docs/zh-TW/hooks#reference-scripts-by-path) 和 MCP 伺服器作為 `CLAUDE_PROJECT_DIR` 接收的相同路徑。使用此來參考專案本地指令碼或檔案，例如 `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`，獨立於 skill 的安裝位置。 |

445| `${CLAUDE_PLUGIN_ROOT}` | 插件的安裝目錄。僅在插件 skills 中替換。使用此來參考插件中任何位置的指令碼或檔案，包括在插件的 skills 之間共享的資源。請參閱[插件環境變數](/docs/zh-TW/plugins-reference#environment-variables)。 |445| `${CLAUDE_PLUGIN_ROOT}` | 插件的安裝目錄。僅在插件 skills 中替換。使用此來參考插件中任何位置的指令碼或檔案，包括在插件的 skills 之間共享的資源。請參閱[插件環境變數](/docs/zh-TW/plugins/manifest-reference#environment-variables)。 |

446| `${CLAUDE_PLUGIN_DATA}` | 插件的[持久資料目錄](/docs/zh-TW/plugins-reference#persistent-data-directory)，在插件更新後倖存。僅在插件 skills 中替換。使用此來參考已安裝的依賴項、生成的檔案或必須超越更新的快取。 |446| `${CLAUDE_PLUGIN_DATA}` | 插件的[持久資料目錄](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)，在插件更新後倖存。僅在插件 skills 中替換。使用此來參考已安裝的依賴項、生成的檔案或必須超越更新的快取。 |

447 447

448Claude Code 在兩個地方替換 `${CLAUDE_SKILL_DIR}` 和 `${CLAUDE_PROJECT_DIR}`：skill 的 markdown 內容和 [`allowed-tools`](#frontmatter-reference) frontmatter 中的 Bash 規則。在插件 skill 中，Claude Code 在相同的兩個地方替換 `${CLAUDE_PLUGIN_ROOT}` 和 `${CLAUDE_PLUGIN_DATA}`。在兩個地方使用相同的變數讓 skill 運行捆綁的指令碼而無需許可提示。以下 skill 顯示了該模式：448Claude Code 在兩個地方替換 `${CLAUDE_SKILL_DIR}` 和 `${CLAUDE_PROJECT_DIR}`：skill 的 markdown 內容和 [`allowed-tools`](#frontmatter-reference) frontmatter 中的 Bash 規則。在插件 skill 中，Claude Code 在相同的兩個地方替換 `${CLAUDE_PLUGIN_ROOT}` 和 `${CLAUDE_PLUGIN_DATA}`。在兩個地方使用相同的變數讓 skill 運行捆綁的指令碼而無需許可提示。以下 skill 顯示了該模式：

449 449

892 892

893兩者的檢查都是基線比較。收集幾個真實的提示，在有技能可用的新會話中運行每一個，然後在[禁用](#override-skill-visibility-from-settings)它的情況下再運行一次，並比較結果。新會話很重要，因為編寫技能時留下的上下文會掩蓋書面指示中的漏洞。893兩者的檢查都是基線比較。收集幾個真實的提示，在有技能可用的新會話中運行每一個，然後在[禁用](#override-skill-visibility-from-settings)它的情況下再運行一次，並比較結果。新會話很重要，因為編寫技能時留下的上下文會掩蓋書面指示中的漏洞。

894 894

895兩個工具可以自動化該比較。對於在[外掛](/docs/zh-TW/plugins)中發布的技能，[`claude plugin eval`](/docs/zh-TW/plugin-evals)在隔離的會話中運行每個提示，有和沒有外掛，使用你定義的或它為你編寫的評分器進行評分，並在低於閾值時以非零值退出，以便你可以在 CI 上進行控制。對於在 Claude Code 對話中迭代單個技能，下面的 skill-creator 外掛運行類似的迴圈，使用其自己的 `evals/evals.json` 格式。這兩種格式不可互換。895兩個工具可以自動化該比較。對於在[外掛](/docs/zh-TW/plugins/overview)中發布的技能，[`claude plugin eval`](/docs/zh-TW/plugin-evals)在隔離的會話中運行每個提示，有和沒有外掛，使用你定義的或它為你編寫的評分器進行評分，並在低於閾值時以非零值退出，以便你可以在 CI 上進行控制。對於在 Claude Code 對話中迭代單個技能，下面的 skill-creator 外掛運行類似的迴圈，使用其自己的 `evals/evals.json` 格式。這兩種格式不可互換。

896 896

897<h3 id="run-evals-with-skill-creator">897<h3 id="run-evals-with-skill-creator">

898 使用 skill-creator 運行評估898 使用 skill-creator 運行評估

907如果安裝失敗，請匹配 Claude Code 報告的訊息：907如果安裝失敗，請匹配 Claude Code 報告的訊息：

908 908

909* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。909* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。

910* 外掛[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛名稱。910* 外掛[在市場中找不到](/docs/zh-TW/plugins/install#install-a-plugin)：檢查外掛名稱。

911 911

912如果安裝摘要報告 `Run /reload-plugins to activate.`，Claude Code 會為你運行該重新載入。如果重新載入警告你的下一則訊息會重新讀取對話，請運行 `/reload-plugins --force` 以在目前會話中啟用外掛的技能。然後要求 Claude 評估現有技能，例如 `evaluate my summarize-changes skill with skill-creator`。外掛會引導你完成編寫測試案例並運行迴圈：912如果安裝摘要報告 `Run /reload-plugins to activate.`，Claude Code 會為你運行該重新載入。如果重新載入警告你的下一則訊息會重新讀取對話，請運行 `/reload-plugins --force` 以在目前會話中啟用外掛的技能。然後要求 Claude 評估現有技能，例如 `evaluate my summarize-changes skill with skill-creator`。外掛會引導你完成編寫測試案例並運行迴圈：

913 913

928技能可以根據您的受眾在不同的範圍內分發：928技能可以根據您的受眾在不同的範圍內分發：

929 929

930* **專案技能**：將 `.claude/skills/` 提交到版本控制930* **專案技能**：將 `.claude/skills/` 提交到版本控制

931* **外掛程式**：在您的[外掛程式](/docs/zh-TW/plugins)中建立 `skills/` 目錄931* **外掛程式**：在您的[外掛程式](/docs/zh-TW/plugins/overview)中建立 `skills/` 目錄

932* **受管理**：透過[受管理設定](/docs/zh-TW/managed-settings)在整個組織範圍內部署932* **受管理**：透過[受管理設定](/docs/zh-TW/managed-settings)在整個組織範圍內部署

933 933

934<h3 id="generate-visual-output">934<h3 id="generate-visual-output">

1143 1143

1144如果 skill 隨附在 plugin 中，您可以測量它在實際提示中觸發的頻率，而不是逐一檢查：使用 [`tool_used: Skill` grader](/docs/zh-TW/plugin-evals#create-your-first-eval-suite) 撰寫評估案例，並在每次描述變更後使用 `claude plugin eval` 執行它。1144如果 skill 隨附在 plugin 中，您可以測量它在實際提示中觸發的頻率，而不是逐一檢查：使用 [`tool_used: Skill` grader](/docs/zh-TW/plugin-evals#create-your-first-eval-suite) 撰寫評估案例，並在每次描述變更後使用 `claude plugin eval` 執行它。

1145 1145

1146若要找到 frontmatter 無法解析的 `SKILL.md` 檔案，請在 skills 目錄上執行 [`claude plugin validate`](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)，例如針對專案 skills 執行 `claude plugin validate .claude/skills`，或針對個人 skills 執行 `claude plugin validate ~/.claude/skills`。需要 Claude Code v2.1.233 或更新版本。1146若要找到 frontmatter 無法解析的 `SKILL.md` 檔案，請在 skills 目錄上執行 [`claude plugin validate`](/docs/zh-TW/plugins/cli-reference#validate-a-directory)，例如針對專案 skills 執行 `claude plugin validate .claude/skills`，或針對個人 skills 執行 `claude plugin validate ~/.claude/skills`。需要 Claude Code v2.1.233 或更新版本。

1147 1147

1148<h3 id="skill-triggers-too-often">1148<h3 id="skill-triggers-too-often">

1149 Skill 觸發過於頻繁1149 Skill 觸發過於頻繁

1184* **[評估 skill 輸出品質](https://agentskills.io/skill-creation/evaluating-skills)**：agentskills.io 上的 eval 檔案格式和反覆運算工作流程1184* **[評估 skill 輸出品質](https://agentskills.io/skill-creation/evaluating-skills)**：agentskills.io 上的 eval 檔案格式和反覆運算工作流程

1185* **[Skill 編寫最佳實踐](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)**：適用於 Claude 產品的編寫指導1185* **[Skill 編寫最佳實踐](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)**：適用於 Claude 產品的編寫指導

1186* **[Subagents](/docs/zh-TW/sub-agents)**：委派任務給專門的代理1186* **[Subagents](/docs/zh-TW/sub-agents)**：委派任務給專門的代理

1187* **[Plugins](/docs/zh-TW/plugins)**：使用其他擴展功能打包和分發 skills1187* **[Plugins](/docs/zh-TW/plugins/overview)**：使用其他擴展功能打包和分發 skills

1188* **[Hooks](/docs/zh-TW/hooks)**：自動化工具事件周圍的工作流程1188* **[Hooks](/docs/zh-TW/hooks)**：自動化工具事件周圍的工作流程

1189* **[Memory](/docs/zh-TW/memory)**：管理 CLAUDE.md 檔案以取得持久上下文1189* **[Memory](/docs/zh-TW/memory)**：管理 CLAUDE.md 檔案以取得持久上下文

1190* **[Commands](/docs/zh-TW/commands)**：內建命令和捆綁 skills 的參考1190* **[Commands](/docs/zh-TW/commands)**：內建命令和捆綁 skills 的參考

statusline.md +1 −1

Details

1142 1142

1143將一個 JSON 行寫入 stdout，每行您想要覆蓋，形式為 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字串按原樣呈現，包括 ANSI 顏色和 OSC 8 超連結。省略任務的 `id` 以保持該行的預設呈現；發出空 `content` 字串以隱藏它。1143將一個 JSON 行寫入 stdout，每行您想要覆蓋，形式為 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字串按原樣呈現，包括 ANSI 顏色和 OSC 8 超連結。省略任務的 `id` 以保持該行的預設呈現；發出空 `content` 字串以隱藏它。

1144 1144

1145適用於 `statusLine` 的相同信任、`disableAllHooks` 和 [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) 閘門也適用於此。外掛程式可以在其 [`settings.json`](/docs/zh-TW/plugins-reference#standard-plugin-layout) 中提供預設 `subagentStatusLine`，但與 hooks 不同，即使外掛程式在受管設定 `enabledPlugins` 中被強制啟用，外掛程式值也不會在 `allowManagedHooksOnly` 下執行。1145適用於 `statusLine` 的相同信任、`disableAllHooks` 和 [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) 閘門也適用於此。外掛程式可以在其 [`settings.json`](/docs/zh-TW/plugins/manifest-reference#standard-layout) 中提供預設 `subagentStatusLine`，但與 hooks 不同，即使外掛程式在受管設定 `enabledPlugins` 中被強制啟用，外掛程式值也不會在 `allowManagedHooksOnly` 下執行。

1146 1146

1147<h2 id="tips">1147<h2 id="tips">

1148 提示1148 提示

sub-agents.md +16 −14

Details

178 178

179**專案 subagents**（`.claude/agents/`）非常適合特定於程式碼庫的 subagents。將它們簽入版本控制，以便您的團隊可以協作使用和改進它們。179**專案 subagents**（`.claude/agents/`）非常適合特定於程式碼庫的 subagents。將它們簽入版本控制，以便您的團隊可以協作使用和改進它們。

180 180

181專案 subagents 是透過從目前工作目錄向上走來發現的，因此會掃描那裡和儲存庫根目錄之間的每個 `.claude/agents/`。自 v2.1.178 起，當這些巢狀目錄中的多個定義相同的 `name` 時，Claude Code 使用最接近工作目錄的定義。181專案 subagents 是透過從目前工作目錄向上走來發現的，因此會掃描那裡和儲存庫根目錄之間的每個 `.claude/agents/`。當這些巢狀目錄中的多個定義相同的 `name` 時，Claude Code 使用最接近工作目錄的定義。

182 182

183使用 `--add-dir` 或 `/add-dir` 新增的目錄時，Claude Code 也會載入其 `.claude/agents/` 資料夾，與您的專案 subagents 一起。請參閱 [Additional directories](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) 以了解哪些其他配置類型從 `--add-dir` 載入。若要跨專案共享 subagents 而不使用 `--add-dir`，請使用 `~/.claude/agents/` 或 [plugin](/docs/zh-TW/plugins)。183使用 `--add-dir` 或 `/add-dir` 新增的目錄時，Claude Code 也會載入其 `.claude/agents/` 資料夾，與您的專案 subagents 一起。請參閱 [Additional directories](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) 以了解哪些其他配置類型從 `--add-dir` 載入。若要跨專案共享 subagents 而不使用 `--add-dir`，請使用 `~/.claude/agents/` 或 [plugin](/docs/zh-TW/plugins/overview)。

184 184

185**使用者 subagents**（`~/.claude/agents/`）是在所有專案中可用的個人 subagents。185**使用者 subagents**（`~/.claude/agents/`）是在所有專案中可用的個人 subagents。

186 186

238 238

239**受管 subagents** 由組織管理員部署。將 markdown 檔案放在 [managed settings directory](/docs/zh-TW/managed-settings#delivery-mechanisms) 內的 `.claude/agents/` 中，使用與專案和使用者 subagents 相同的 frontmatter 格式。受管定義優先於具有相同名稱的專案和使用者 subagents。239**受管 subagents** 由組織管理員部署。將 markdown 檔案放在 [managed settings directory](/docs/zh-TW/managed-settings#delivery-mechanisms) 內的 `.claude/agents/` 中，使用與專案和使用者 subagents 相同的 frontmatter 格式。受管定義優先於具有相同名稱的專案和使用者 subagents。

240 240

241**外掛程式 subagents** 來自您已安裝的 [plugins](/docs/zh-TW/plugins)。它們與您的自訂 subagents 一起自動載入，並在 @-mention 類型提前中以其範圍名稱出現。請參閱 [plugin components reference](/docs/zh-TW/plugins-reference#agents) 以了解建立外掛程式 subagents 的詳細資訊。241**外掛程式 subagents** 來自您已安裝的 [plugins](/docs/zh-TW/plugins/overview)。它們與您的自訂 subagents 一起自動載入，並在 @-mention 類型提前中以其範圍名稱出現。請參閱 [plugin components reference](/docs/zh-TW/plugins/components#agents) 以了解建立外掛程式 subagents 的詳細資訊。

242 242

243<Note>243<Note>

244 基於安全考慮，外掛程式 subagents 不支援 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 欄位。從外掛程式載入代理時，這些欄位會被忽略。如果您需要它們，請將代理檔案複製到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中的 [`permissions.allow`](/docs/zh-TW/settings-reference#permissions-allow) 新增規則，但這些規則適用於整個工作階段，而不僅僅是外掛程式 subagent。244 基於安全考慮，外掛程式 subagents 不支援 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 欄位。從外掛程式載入代理時，這些欄位會被忽略。如果您需要它們，請將代理檔案複製到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中的 [`permissions.allow`](/docs/zh-TW/settings-reference#permissions-allow) 新增規則，但這些規則適用於整個工作階段，而不僅僅是外掛程式 subagent。

305 305

306| Field | 必需 | Description |306| Field | 必需 | Description |

307| :---------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |307| :---------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

308| `name` | 是 | 唯一識別碼，例如 `code-reviewer` 或 `reviewer-v2`。[Hooks](/docs/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必相符。名稱不能包含 `:`，這是為 [plugin-scoped identifiers](/docs/zh-TW/plugins) 保留的，例如 `my-plugin:reviewer`。Claude Code 不會載入名稱包含一個的檔案，並將錯誤記錄到除錯日誌。在 v2.1.218 之前，此類名稱被接受 |308| `name` | 是 | 唯一識別碼，例如 `code-reviewer` 或 `reviewer-v2`。[Hooks](/docs/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必相符。名稱不能包含 `:`，這是為 [plugin-scoped identifiers](/docs/zh-TW/plugins/overview) 保留的，例如 `my-plugin:reviewer`。Claude Code 不會載入名稱包含一個的檔案，並將錯誤記錄到除錯日誌。在 v2.1.218 之前，此類名稱被接受 |

309| `description` | 是 | Claude 何時應委派給此 subagent |309| `description` | 是 | Claude 何時應委派給此 subagent |

310| `tools` | 否 | [Tools](#available-tools) subagent 可以使用，作為逗號分隔的字串（例如 `Read, Grep, Bash`）或 YAML 清單。如果省略，繼承 subagents 可用的每個工具。如果清單中沒有條目解析為工具，subagent 通常 [fails to launch](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools) 並出現命名條目的錯誤。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |310| `tools` | 否 | [Tools](#available-tools) subagent 可以使用，作為逗號分隔的字串（例如 `Read, Grep, Bash`）或 YAML 清單。如果省略，繼承 subagents 可用的每個工具。如果清單中沒有條目解析為工具，subagent 通常 [fails to launch](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools) 並出現命名條目的錯誤。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |

311| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的清單中移除。格式與 `tools` 相同。具有指定符的條目（例如 `Bash(git push *)`）仍然 [removes the whole tool](#available-tools) |311| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的清單中移除。格式與 `tools` 相同。具有指定符的條目（例如 `Bash(git push *)`）仍然 [removes the whole tool](#available-tools) |

349 349

350若要查看除錯日誌，請使用 `--debug` 執行 Claude Code。350若要查看除錯日誌，請使用 `--debug` 執行 Claude Code。

351 351

352一個 [plugin subagent](/docs/zh-TW/plugins-reference#agents)，其 frontmatter 沒有 `name` 或不解析，仍然在其檔案名稱下載入。352一個 [plugin subagent](/docs/zh-TW/plugins/components#agents)，其 frontmatter 沒有 `name` 或不解析，仍然在其檔案名稱下載入。

353 353

354<h5 id="check-an-agents-directory-before-a-session">354<h5 id="check-an-agents-directory-before-a-session">

355 在工作階段前檢查 `agents` 目錄355 在工作階段前檢查 `agents` 目錄

356</h5>356</h5>

357 357

358若要找到 `agents` 目錄中 frontmatter 不解析的檔案，請針對目錄執行 `claude plugin validate`，例如 `.claude/agents` 或 `~/.claude/agents`。Claude Code 僅檢查 [您命名的目錄](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)，並且不會標記 frontmatter 解析但沒有 `name` 的檔案。需要 Claude Code v2.1.233 或更高版本。358若要找到 `agents` 目錄中 frontmatter 不解析的檔案，請針對目錄執行 `claude plugin validate`，例如 `.claude/agents` 或 `~/.claude/agents`。Claude Code 僅檢查 [您命名的目錄](/docs/zh-TW/plugins/cli-reference#validate-a-directory)，並且不會標記 frontmatter 解析但沒有 `name` 的檔案。需要 Claude Code v2.1.233 或更高版本。

359 359

360<h3 id="choose-a-model">360<h3 id="choose-a-model">

361 選擇模型361 選擇模型

573* 參考您已配置的伺服器的名稱573* 參考您已配置的伺服器的名稱

574* 來自 `~/.claude/agents/` 中代理檔案的內聯伺服器，在您使用 `--agents` 或 SDK `agents` 選項傳遞的伺服器中，或受管設定提供的伺服器中574* 來自 `~/.claude/agents/` 中代理檔案的內聯伺服器，在您使用 `--agents` 或 SDK `agents` 選項傳遞的伺服器中，或受管設定提供的伺服器中

575 575

576自 v2.1.153 起，適用於主工作階段的 MCP 限制也涵蓋在 subagent frontmatter 中宣告的伺服器：576適用於主工作階段的 MCP 限制也涵蓋在 subagent frontmatter 中宣告的伺服器：

577 577

578* [`--strict-mcp-config`](/docs/zh-TW/cli-reference) 和 [`--bare`](/docs/zh-TW/cli-reference)578* [`--strict-mcp-config`](/docs/zh-TW/cli-reference) 和 [`--bare`](/docs/zh-TW/cli-reference)

579* [Enterprise managed MCP configuration](/docs/zh-TW/managed-mcp)579* [Enterprise managed MCP configuration](/docs/zh-TW/managed-mcp)

822 822

823兩個事件都支援匹配器以按名稱針對特定代理類型。匹配器值是專案層級和使用者層級 subagents 的代理 frontmatter `name`，或 [plugin subagents](/docs/zh-TW/plugins) 的外掛程式範圍識別碼，例如 `my-plugin:db-agent`。範圍名稱包含冒號，因此它被評估為 [unanchored regular expression](/docs/zh-TW/hooks#matcher-patterns)；使用 `^` 和 `$` 錨定它，如 `^my-plugin:db-agent$`，以僅匹配該代理。823兩個事件都支援匹配器以按名稱針對特定代理類型。匹配器值是專案層級和使用者層級 subagents 的代理 frontmatter `name`，或 [plugin subagents](/docs/zh-TW/plugins/components#agents) 的外掛程式範圍識別碼，例如 `my-plugin:db-agent`。範圍名稱包含冒號，因此它被評估為 [unanchored regular expression](/docs/zh-TW/hooks#matcher-patterns)；使用 `^` 和 `$` 錨定它，如 `^my-plugin:db-agent$`，以僅匹配該代理。

824 824

825此範例僅在 `db-agent` subagent 啟動時執行設定指令碼，並在任何 subagent 停止時執行清理指令碼：825此範例僅在 `db-agent` subagent 啟動時執行設定指令碼，並在任何 subagent 停止時執行清理指令碼：

826 826

862 862

863保持描述簡潔：當您的 subagents 的合併描述超過 [15,000 個 token 限制](/docs/zh-TW/errors#agent-descriptions-are-over-the-15000-token-limit) 時，Claude Code 會顯示啟動警告，但仍會載入每個 subagent。863保持描述簡潔：當您的 subagents 的合併描述超過 [15,000 個 token 限制](/docs/zh-TW/errors#agent-descriptions-are-over-the-15000-token-limit) 時，Claude Code 會顯示啟動警告，但仍會載入每個 subagent。

864 864

865如果 subagent 隨附於 [plugin](/docs/zh-TW/plugins/overview)，您可以測量 Claude 在現實提示中委派給它的可靠性，而不是一次檢查一個：[`claude plugin eval`](/docs/zh-TW/plugin-evals) 會在有和沒有 plugin 的情況下執行每個提示，並對結果進行評分。

866

865<h3 id="invoke-subagents-explicitly">867<h3 id="invoke-subagents-explicitly">

866 明確呼叫 subagents868 明確呼叫 subagents

867</h3>869</h3>

887 889

888您的完整訊息仍然會傳送給 Claude，它根據您要求的內容為 subagent 編寫任務提示。@-mention 控制 Claude 呼叫哪個 subagent，而不是它接收什麼提示。890您的完整訊息仍然會傳送給 Claude，它根據您要求的內容為 subagent 編寫任務提示。@-mention 控制 Claude 呼叫哪個 subagent，而不是它接收什麼提示。

889 891

890由啟用的 [plugin](/docs/zh-TW/plugins) 提供的 Subagents 在預輸入中顯示為其限定名稱，例如 `my-plugin:code-reviewer` 或 `my-plugin:review:security`（當 plugin [將 agents 組織到子資料夾](#choose-the-subagent-scope) 時）。名為背景 subagents 目前在工作階段中執行也出現在預輸入中，在名稱旁邊顯示其狀態。892由啟用的 [plugin](/docs/zh-TW/plugins/overview) 提供的 Subagents 在預輸入中顯示為其限定名稱，例如 `my-plugin:code-reviewer` 或 `my-plugin:review:security`（當 plugin [將 agents 組織到子資料夾](#choose-the-subagent-scope) 時）。名為背景 subagents 目前在工作階段中執行也出現在預輸入中，在名稱旁邊顯示其狀態。

891 893

892您也可以手動輸入提及而不使用選擇器：`@agent-<name>` 用於本地 subagents，或 `@agent-` 後跟外掛程式 subagents 的限定名稱，例如 `@agent-my-plugin:code-reviewer`。當您輸入此形式時，預輸入會顯示檔案符合而不是代理。代理提及在您提交時仍會解析。894您也可以手動輸入提及而不使用選擇器：`@agent-<name>` 用於本地 subagents，或 `@agent-` 後跟外掛程式 subagents 的限定名稱，例如 `@agent-my-plugin:code-reviewer`。當您輸入此形式時，預輸入會顯示檔案符合而不是代理。代理提及在您提交時仍會解析。

893 895

934Subagents 可以在前景或背景中執行：936Subagents 可以在前景或背景中執行：

935 937

936* **前景 subagents** 阻止主要對話直到完成。權限提示會在出現時傳遞給您。938* **前景 subagents** 阻止主要對話直到完成。權限提示會在出現時傳遞給您。

937* **背景 subagents** 在您繼續工作時並行執行。當背景 subagent 到達需要權限的工具呼叫時，Claude Code 會在您的主要工作階段中出現提示，並命名要求的 subagent。批准以讓 subagent 繼續，或按 Esc 拒絕該單一工具呼叫而不停止 subagent。在 v2.1.186 之前，背景 subagents 自動拒絕任何會提示的工具呼叫。939* **背景 subagents** 在您繼續工作時並行執行。當背景 subagent 到達需要權限的工具呼叫時，Claude Code 會在您的主要工作階段中出現提示，並命名要求的 subagent。批准以讓 subagent 繼續，或按 Esc 拒絕該單一工具呼叫而不停止 subagent。

938 940

939對於 Claude 使用 Agent 工具產生的每個 subagent，Claude Code 會從適用的第一個情況中選擇前景或背景：941對於 Claude 使用 Agent 工具產生的每個 subagent，Claude Code 會從適用的第一個情況中選擇前景或背景：

940 942

941* 如果進行中的 [agent team](/docs/zh-TW/agent-teams#limitations) 隊友產生了 subagent，Claude Code 會在前景中執行它。當隊友設定 [`background: true`](#supported-frontmatter-fields) 時，Claude Code 會拒絕並出現錯誤以產生隊友的 subagent。當 [fork 模式](#turn-fork-mode-on-or-off) 關閉且您未 [關閉背景任務](/docs/zh-TW/env-vars) 時，Claude Code 也會在隊友設定 `run_in_background: true` 時拒絕並出現錯誤。943* 如果進行中的 [agent team](/docs/zh-TW/agent-teams#limitations) 隊友產生了 subagent，Claude Code 會在前景中執行它。Claude Code 會拒絕並出現錯誤以產生隊友的 subagent，當隊友的定義設定 [`background: true`](#supported-frontmatter-fields) 時。當 [fork 模式](#turn-fork-mode-on-or-off) 關閉且您未 [關閉背景任務](/docs/zh-TW/env-vars) 時，Claude Code 也會在隊友設定 `run_in_background: true` 時拒絕並出現錯誤。

942* 如果您將 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/zh-TW/env-vars) 設定為 `1`，Claude Code 會在前景中執行 subagent，在每種工作階段中以及無論 fork 模式是否開啟。944* 如果您將 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/zh-TW/env-vars) 設定為 `1`，Claude Code 會在前景中執行 subagent，在每種工作階段中以及無論 fork 模式是否開啟。

943* 當 [fork 模式](#turn-fork-mode-on-or-off) 開啟時（在互動式工作階段中預設開啟），Claude Code 會在背景中執行 subagent，fork 和非 fork subagents 都是如此，Claude 無法要求前景。945* 當 [fork 模式](#turn-fork-mode-on-or-off) 開啟時（在互動式工作階段中預設開啟），Claude Code 會在背景中執行 subagent，fork 和非 fork subagents 都是如此，Claude 無法要求前景。

944* 當 fork 模式關閉時，Claude 預設在背景中執行 subagent，在需要結果才能繼續時在前景中執行。Fork 模式在 [非互動模式](/docs/zh-TW/headless) 中使用 `-p` 和在 Agent SDK 中關閉，除非您開啟它。若要在 Claude 需要結果時將特定 subagent 保持在背景中，請將其 frontmatter [`background`](#supported-frontmatter-fields) 欄位設定為 `true`。946* 當 fork 模式關閉時，Claude 預設在背景中執行 subagent，在需要結果才能繼續時在前景中執行。Fork 模式在 [非互動模式](/docs/zh-TW/headless) 中使用 `-p` 和在 Agent SDK 中關閉，除非您開啟它。若要在 Claude 需要結果時將特定 subagent 保持在背景中，請將其 frontmatter [`background`](#supported-frontmatter-fields) 欄位設定為 `true`。

1177 1179

1178您自己停止的 subagent，使用 `/tasks` 中的 `x` 或 SDK `stop_task` 請求，不會自動恢復。如果 Claude 向它發送訊息，訊息會被拒絕，Claude 會被告知代理已被取消。1180您自己停止的 subagent，使用 `/tasks` 中的 `x` 或 SDK `stop_task` 請求，不會自動恢復。如果 Claude 向它發送訊息，訊息會被拒絕，Claude 會被告知代理已被取消。

1179 1181

1180當 [該 subagent 的列仍在 subagent 面板中](#run-subagents-in-foreground-or-background) 時，輸入到其文字中以自己恢復它。之後，來自 Claude 的訊息可以再次自動恢復它。需要 Claude Code v2.1.191 或更新版本。1182當 [該 subagent 的列仍在 subagent 面板中](#run-subagents-in-foreground-or-background) 時，輸入到其文字中以自己恢復它。之後，來自 Claude 的訊息可以再次自動恢復它。

1181 1183

1182恢復在相同 ID 下啟動代理的新執行，所以已經失敗或完成的 subagent 在任務列表和 Agent SDK 的任務事件中再次顯示為執行中。在 v2.1.205 之前，它在恢復的執行工作時保持顯示其較早的失敗或完成狀態。1184恢復在相同 ID 下啟動代理的新執行，所以已經失敗或完成的 subagent 在任務列表和 Agent SDK 的任務事件中再次顯示為執行中。在 v2.1.205 之前，它在恢復的執行工作時保持顯示其較早的失敗或完成狀態。

1183 1185

1495 1497

1496現在您理解了 subagents，請探索這些相關功能：1498現在您理解了 subagents，請探索這些相關功能：

1497 1499

1498* [使用外掛程式分發 subagents](/docs/zh-TW/plugins) 以跨團隊或專案共享 subagents1500* [使用外掛程式分發 subagents](/docs/zh-TW/plugins/components#agents) 以跨團隊或專案共享 subagents

1499* [以程式方式執行 Claude Code](/docs/zh-TW/headless) 使用 Agent SDK 進行 CI/CD 和自動化1501* [以程式方式執行 Claude Code](/docs/zh-TW/headless) 使用 Agent SDK 進行 CI/CD 和自動化

1500* [使用 MCP 伺服器](/docs/zh-TW/mcp) 為 subagents 提供對外部工具和資料的存取1502* [使用 MCP 伺服器](/docs/zh-TW/mcp) 為 subagents 提供對外部工具和資料的存取

terminal-config.md +1 −1

Details

156 建立自訂主題156 建立自訂主題

157</h3>157</h3>

158 158

159除了內建預設值外，`/theme` 會列出您已定義的任何自訂主題，以及由已安裝的[外掛程式](/docs/zh-TW/plugins-reference#themes)貢獻的任何主題。選擇清單末尾的\*\*新增自訂主題…\*\*以互動方式建立一個：您命名主題，然後選擇要覆寫的個別色彩權杖。當自訂主題被反白顯示時，按 `Ctrl+E` 以編輯它。159除了內建預設值外，`/theme` 會列出您已定義的任何自訂主題，以及由已安裝的[外掛程式](/docs/zh-TW/plugins/components#themes-and-output-styles)貢獻的任何主題。選擇清單末尾的\*\*新增自訂主題…\*\*以互動方式建立一個：您命名主題，然後選擇要覆寫的個別色彩權杖。當自訂主題被反白顯示時，按 `Ctrl+E` 以編輯它。

160 160

161每個自訂主題都是 `~/.claude/themes/` 中的 JSON 檔案。不含 `.json` 副檔名的檔案名稱是主題的 slug，選擇主題會將 `custom:<slug>` 儲存為您的主題偏好設定。該檔案有三個選用欄位：161每個自訂主題都是 `~/.claude/themes/` 中的 JSON 檔案。不含 `.json` 副檔名的檔案名稱是主題的 slug，選擇主題會將 `custom:<slug>` 儲存為您的主題偏好設定。該檔案有三個選用欄位：

162 162

tools-reference.md +5 −5

Details

179Claude Code 在命令執行時將命令的輸出串流到工作檔案；輸出超過 5 GB 的命令會被終止。命令完成後，Claude Code 從該檔案讀回輸出，最多到下面描述的讀回視窗。輸出有多少到達 Claude 內聯取決於 Claude Code 是否將結果視為失敗：179Claude Code 在命令執行時將命令的輸出串流到工作檔案；輸出超過 5 GB 的命令會被終止。命令完成後，Claude Code 從該檔案讀回輸出，最多到下面描述的讀回視窗。輸出有多少到達 Claude 內聯取決於 Claude Code 是否將結果視為失敗：

180 180

181| 結果 | Claude 獲得的內容 |181| 結果 | Claude 獲得的內容 |

182| :- | :-------------------------------------------------------------------------------------- |182| :- | :--------------------------------------------------------------------------------------------------------- |

183| 有效 | 內聯最多約 30,000 個字元（預設）；超過該值，會儲存到工作階段目錄的檔案路徑並在 64 MiB 後截斷，加上開頭的簡短預覽，Claude 在需要其餘部分時讀取或搜尋檔案 |183| 有效 | 內聯最多約 30,000 個字元（預設）；超過該值，為儲存到工作階段目錄的檔案的路徑（檔案超過 64 MiB 的部分會被截斷），加上最多前 2,000 個字元的預覽，Claude 在需要其餘部分時讀取或搜尋該檔案 |

184| 失敗 | 內聯最多約 10,000 個字元；超過該值，從讀回視窗中切割的該大小的頭尾摘錄，沒有檔案路徑 |184| 失敗 | 內聯最多約 10,000 個字元；超過該值，從讀回視窗中切割的該大小的頭尾摘錄，沒有檔案路徑 |

185 185

186命令退出代碼為 1 只有在 Claude Code 將退出代碼 1 識別為該命令的良性結果時，才算作 Bash 工具的有效結果：`grep`、`rg`、`egrep`、`fgrep`、`find`、`diff`、`test` 和 `[`，加上 `git diff` 和 `git grep`。每個其他退出代碼為 1 的命令都算作失敗，即使退出代碼 1 是良性的資訊結果：`pgrep` 和 `jq -e` 沒有符合項，`cmp` 的檔案不同。186命令退出代碼為 1 只有在 Claude Code 將退出代碼 1 識別為該命令的良性結果時，才算作 Bash 工具的有效結果：`grep`、`rg`、`egrep`、`fgrep`、`find`、`diff`、`test` 和 `[`，加上 `git diff` 和 `git grep`。每個其他退出代碼為 1 的命令都算作失敗，即使退出代碼 1 是良性的資訊結果：`pgrep` 和 `jq -e` 沒有符合項，`cmp` 的檔案不同。

221* `mcp`: 本機 [MCP 伺服器](/docs/zh-TW/mcp)221* `mcp`: 本機 [MCP 伺服器](/docs/zh-TW/mcp)

222* `lsp`: [語言伺服器](#lsp-tool-behavior)222* `lsp`: [語言伺服器](#lsp-tool-behavior)

223* `hooks`: [hook](/docs/zh-TW/hooks) 命令223* `hooks`: [hook](/docs/zh-TW/hooks) 命令

224* `plugin`: [外掛程式](/docs/zh-TW/plugins)執行的命令224* `plugin`: [外掛程式](/docs/zh-TW/plugins/overview)執行的命令

225* `helper`: Claude Code 自己的協助程式命令，例如 `git`225* `helper`: Claude Code 自己的協助程式命令，例如 `git`

226* `agent`: 子 Claude Code 程序，例如[代理隊友](/docs/zh-TW/agent-teams)226* `agent`: 子 Claude Code 程序，例如[代理隊友](/docs/zh-TW/agent-teams)

227 227

344* 尋找介面的實作344* 尋找介面的實作

345* 追蹤呼叫階層345* 追蹤呼叫階層

346 346

347Claude Code 會保持 tool 為非作用中狀態，直到您為您的語言安裝[程式碼智慧 plugin](/docs/zh-TW/discover-plugins#code-intelligence)。在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，Claude Code 不會啟動 plugin 語言伺服器，所以 LSP tool 在那裡保持非作用中。Claude Code 從 plugin 取得語言伺服器的設定，您需要自行安裝伺服器二進位檔。347Claude Code 會保持 tool 為非作用中狀態，直到您為您的語言安裝[程式碼智慧 plugin](/docs/zh-TW/plugins/code-intelligence)。在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，Claude Code 不會啟動 plugin 語言伺服器，所以 LSP tool 在那裡保持非作用中。Claude Code 從 plugin 取得語言伺服器的設定，您需要自行安裝伺服器二進位檔。

348 348

349Claude Code 會針對無法啟動其語言伺服器的檔案上的每個 LSP 呼叫傳回錯誤結果。349Claude Code 會針對無法啟動其語言伺服器的檔案上的每個 LSP 呼叫傳回錯誤結果。

350 350

376 376

377該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。當設定 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，它也不可用。377該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。當設定 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，它也不可用。

378 378

379外掛程式可以宣告在外掛程式處於活動狀態時自動啟動的監視，而不是要求 Claude 啟動它們。請參閱 [外掛程式監視](/docs/zh-TW/plugins-reference#monitors)。379外掛程式可以宣告在外掛程式處於活動狀態時自動啟動的監視，而不是要求 Claude 啟動它們。請參閱 [外掛程式監視](/docs/zh-TW/plugins/components#monitors)。

380 380

381<h3 id="websocket-source">381<h3 id="websocket-source">

382 WebSocket 來源382 WebSocket 來源

vs-code.md +2 −2

Details

331 管理 plugins331 管理 plugins

332</h2>332</h2>

333 333

334VS Code 擴充功能包含一個圖形介面，用於安裝和管理 [plugins](/docs/zh-TW/plugins)。在提示框中輸入 `/plugins` 以開啟**管理 plugins** 介面。334VS Code 擴充功能包含一個圖形介面，用於安裝和管理 [plugins](/docs/zh-TW/plugins/overview)。在提示框中輸入 `/plugins` 以開啟**管理 plugins** 介面。

335 335

336<h3 id="install-plugins">336<h3 id="install-plugins">

337 安裝 plugins337 安裝 plugins

394 VS Code 中的 plugin 管理在幕後使用相同的 CLI 命令。您在擴充功能中設定的 plugins 和 marketplaces 也可在 CLI 中使用，反之亦然。394 VS Code 中的 plugin 管理在幕後使用相同的 CLI 命令。您在擴充功能中設定的 plugins 和 marketplaces 也可在 CLI 中使用，反之亦然。

395</Note>395</Note>

396 396

397如需深入瞭解 plugin 系統，請參閱 [Plugins](/docs/zh-TW/plugins) 和 [Plugin marketplaces](/docs/zh-TW/plugin-marketplaces)。397如需深入瞭解 plugin 系統，請參閱 [Plugins](/docs/zh-TW/plugins/overview) 和 [Plugin marketplaces](/docs/zh-TW/plugins/overview)。

398 398

399<h2 id="automate-browser-tasks-with-chrome">399<h2 id="automate-browser-tasks-with-chrome">

400 使用 Chrome 自動化瀏覽器任務400 使用 Chrome 自動化瀏覽器任務

whats-new/2026-w14.md +1 −1

Details

116 └── my-tool116 └── my-tool

117 ```117 ```

118 118

119 <a className="digest-feature-link" href="/docs/zh-TW/plugins-reference#file-locations-reference">外掛程式參考</a>119 <a className="digest-feature-link" href="/docs/zh-TW/plugins/manifest-reference#standard-layout">外掛程式參考</a>

120</div>120</div>

121 121

122<div className="digest-wins">122<div className="digest-wins">

whats-new/2026-w17.md +1 −1

Details

104 <div>原生 macOS 和 Linux 構建用嵌入式 <code>bfs</code> 和 <code>ugrep</code>（可透過 Bash 使用）取代 <code>Glob</code> 和 <code>Grep</code> 工具，以加快搜尋速度，無需單獨的工具往返</div>104 <div>原生 macOS 和 Linux 構建用嵌入式 <code>bfs</code> 和 <code>ugrep</code>（可透過 Bash 使用）取代 <code>Glob</code> 和 <code>Grep</code> 工具，以加快搜尋速度，無需單獨的工具往返</div>

105 <div><code>--from-pr</code> 現在除了接受 github.com 外，還接受 GitLab 合併請求、Bitbucket 拉取請求和 GitHub Enterprise PR URL</div>105 <div><code>--from-pr</code> 現在除了接受 github.com 外，還接受 GitLab 合併請求、Bitbucket 拉取請求和 GitHub Enterprise PR URL</div>

106 <div>自動模式：在 <a href="/docs/zh-TW/auto-mode-config"><code>autoMode.allow</code>、<code>soft\_deny</code> 或 <code>environment</code></a> 中包含 <code>"\$defaults"</code>，以在內建清單旁邊新增自訂規則，而不是取代它</div>106 <div>自動模式：在 <a href="/docs/zh-TW/auto-mode-config"><code>autoMode.allow</code>、<code>soft\_deny</code> 或 <code>environment</code></a> 中包含 <code>"\$defaults"</code>，以在內建清單旁邊新增自訂規則，而不是取代它</div>

107 <div>新的 <a href="/docs/zh-TW/plugin-dependencies#tag-plugin-releases-for-version-resolution"><code>claude plugin tag</code></a> 命令為插件建立版本驗證的發佈 git 標籤</div>107 <div>新的 <a href="/docs/zh-TW/plugins/dependencies#tag-plugin-releases-for-version-resolution"><code>claude plugin tag</code></a> 命令為插件建立版本驗證的發佈 git 標籤</div>

108 <div>Opus 4.7 會話現在針對模型的原生 1M 內容視窗進行計算，修復了膨脹的 <code>/context</code> 百分比和過早的自動壓縮</div>108 <div>Opus 4.7 會話現在針對模型的原生 1M 內容視窗進行計算，修復了膨脹的 <code>/context</code> 百分比和過早的自動壓縮</div>

109 <div><code>/resume</code> 在大型會話上的速度提高了 67%，現在在重新讀取之前提供摘要陳舊的大型會話的選項</div>109 <div><code>/resume</code> 在大型會話上的速度提高了 67%，現在在重新讀取之前提供摘要陳舊的大型會話的選項</div>

110 </div>110 </div>

whats-new/2026-w19.md +1 −1

Details

24 claude --plugin-url https://example.com/my-plugin.zip24 claude --plugin-url https://example.com/my-plugin.zip

25 ```25 ```

26 26

~~27 <a className="digest-feature-link" href="/docs/zh-TW/plugins">Plugins 指南</a>~~27 <a className="digest-feature-link" href="/docs/zh-TW/plugins/overview">Plugins 指南</a>

28</div>28</div>

29 29

30<div className="digest-feature">30<div className="digest-feature">

whats-new/2026-w23.md +1 −1

Details

59 > /plugin list --enabled59 > /plugin list --enabled

60 ```60 ```

61 61

~~62 <a className="digest-feature-link" href="/docs/zh-TW/plugins-reference#plugin-list">外掛程式命令</a>~~62 <a className="digest-feature-link" href="/docs/zh-TW/plugins/cli-reference#plugin-list">外掛程式命令</a>

63</div>63</div>

64 64

65<div className="digest-feature">65<div className="digest-feature">

whats-new/2026-w32.md +2 −2

Details

86 <div className="digest-wins-grid">86 <div className="digest-wins-grid">

87 <div>VS Code 擴充功能獲得 <a href="/docs/zh-TW/vs-code#extension-settings">焦點檢視</a>，它在每個回合後面隱藏工具活動；從命令選單或使用 <code>Ctrl+Alt+F</code>（Mac 上為 <code>Ctrl+Option+F</code>）切換它</div>87 <div>VS Code 擴充功能獲得 <a href="/docs/zh-TW/vs-code#extension-settings">焦點檢視</a>，它在每個回合後面隱藏工具活動；從命令選單或使用 <code>Ctrl+Alt+F</code>（Mac 上為 <code>Ctrl+Option+F</code>）切換它</div>

88 <div>沙箱認證檔案在 Linux 和 WSL2 上接受 <a href="/docs/zh-TW/sandboxing#mask-credential-files"><code>mode: "mask"</code></a>，因此沙箱化命令讀取哨兵副本，而沙箱代理在出口時替換實際值；認證遮罩也獲得 <code>extract</code>、JWT 感知 <code>decode</code> 和 AWS SigV4 重新簽署選項</div>88 <div>沙箱認證檔案在 Linux 和 WSL2 上接受 <a href="/docs/zh-TW/sandboxing#mask-credential-files"><code>mode: "mask"</code></a>，因此沙箱化命令讀取哨兵副本，而沙箱代理在出口時替換實際值；認證遮罩也獲得 <code>extract</code>、JWT 感知 <code>decode</code> 和 AWS SigV4 重新簽署選項</div>

89 <div>市場可以使用新的 <a href="/docs/zh-TW/plugin-marketplaces#zip-archives"><code>archive</code> 來源</a>將外掛程式分發為 zip 封存，透過 HTTPS 下載並具有可選的 SHA-256 釘選，因此安裝無需 git 或 npm</div>89 <div>市場可以使用新的 <a href="/docs/zh-TW/plugins/marketplace-reference#archive-plugin-source"><code>archive</code> 來源</a>將外掛程式分發為 zip 封存，透過 HTTPS 下載並具有可選的 SHA-256 釘選，因此安裝無需 git 或 npm</div>

90 <div><code>/review</code> 現在是 <a href="/docs/zh-TW/code-review#review-a-diff-locally"><code>/code-review</code></a> 的別名，<code>/code-review</code> 沒有努力等級時會重複使用您上次輸入的等級</div>90 <div><code>/review</code> 現在是 <a href="/docs/zh-TW/code-review#review-a-diff-locally"><code>/code-review</code></a> 的別名，<code>/code-review</code> 沒有努力等級時會重複使用您上次輸入的等級</div>

91 <div>您使用 <a href="/docs/zh-TW/agent-view#copy-the-session-with-%2Ffork"><code>/fork</code></a> 複製的工作階段現在在其自己的 worktree 中進行程式碼變更，而不是原始工作階段的簽出</div>91 <div>您使用 <a href="/docs/zh-TW/agent-view#copy-the-session-with-%2Ffork"><code>/fork</code></a> 複製的工作階段現在在其自己的 worktree 中進行程式碼變更，而不是原始工作階段的簽出</div>

92 <div>您從 <a href="/docs/zh-TW/discover-plugins#install-plugins"><code>/plugin</code></a> 安裝的外掛程式在當前工作階段中啟動（如果安全的話）；安裝摘要報告 <code>Plugin is now active.</code> 或告訴您執行 <code>/reload-plugins</code></div>92 <div>您從 <a href="/docs/zh-TW/plugins/install#install-a-plugin"><code>/plugin</code></a> 安裝的外掛程式在當前工作階段中啟動（如果安全的話）；安裝摘要報告 <code>Plugin is now active.</code> 或告訴您執行 <code>/reload-plugins</code></div>

93 <div><a href="/docs/zh-TW/agent-view#how-file-edits-are-isolated">背景工作階段</a>在 worktree 中變更程式碼現在在完成前提交並推送，僅在任務要求時開啟草稿拉取請求，並遵循您 <code>CLAUDE.md</code> 中的 git 指示</div>93 <div><a href="/docs/zh-TW/agent-view#how-file-edits-are-isolated">背景工作階段</a>在 worktree 中變更程式碼現在在完成前提交並推送，僅在任務要求時開啟草稿拉取請求，並遵循您 <code>CLAUDE.md</code> 中的 git 指示</div>

94 <div>每個工作階段 200 個子代理的上限已移除，因此長時間執行的工作階段不再拒絕新的子代理；<a href="/docs/zh-TW/sub-agents#concurrent-subagent-limit">並行</a>和深度限制仍然適用</div>94 <div>每個工作階段 200 個子代理的上限已移除，因此長時間執行的工作階段不再拒絕新的子代理；<a href="/docs/zh-TW/sub-agents#concurrent-subagent-limit">並行</a>和深度限制仍然適用</div>

95 <div>存放庫的簽入設定不再能開啟 <a href="/docs/zh-TW/remote-control#enable-remote-control-for-all-sessions">遠端控制自動連線</a>；改為在您的使用者或受管設定中設定 <code>remoteControlAtStartup</code>，而專案和本機設定只能將其關閉</div>95 <div>存放庫的簽入設定不再能開啟 <a href="/docs/zh-TW/remote-control#enable-remote-control-for-all-sessions">遠端控制自動連線</a>；改為在您的使用者或受管設定中設定 <code>remoteControlAtStartup</code>，而專案和本機設定只能將其關閉</div>

whats-new/2026-w33.md +2 −2

Details

72 <div className="digest-wins-grid">72 <div className="digest-wins-grid">

73 <div>在提示中輸入 <code>@</code> 以<a href="/docs/zh-TW/cross-session-messaging#message-another-session">提及另一個 Claude 工作階段</a>的名稱，Claude 會使用 <code>SendMessage</code> 直接向其傳送訊息；完全符合一個即時工作階段的裸名稱現在無需確認步驟即可傳遞</div>73 <div>在提示中輸入 <code>@</code> 以<a href="/docs/zh-TW/cross-session-messaging#message-another-session">提及另一個 Claude 工作階段</a>的名稱，Claude 會使用 <code>SendMessage</code> 直接向其傳送訊息；完全符合一個即時工作階段的裸名稱現在無需確認步驟即可傳遞</div>

74 <div>一台機器上的互動式工作階段保持<a href="/docs/zh-TW/cross-session-messaging#see-which-sessions-claude-can-reach">唯一名稱</a>：如果您使用另一個即時工作階段已使用的名稱啟動或重新命名工作階段，Claude Code 會為您的工作階段提供 <code>name-word-word</code> 變體並告知您</div>74 <div>一台機器上的互動式工作階段保持<a href="/docs/zh-TW/cross-session-messaging#see-which-sessions-claude-can-reach">唯一名稱</a>：如果您使用另一個即時工作階段已使用的名稱啟動或重新命名工作階段，Claude Code 會為您的工作階段提供 <code>name-word-word</code> 變體並告知您</div>

75 <div>外掛程式市集接受 <a href="/docs/zh-TW/plugin-marketplaces#command-sources"><code>command</code> 來源</a>：本機命令會列印外掛程式目錄，Claude Code 會在每個工作階段中重新解析並應用，無需重新啟動</div>75 <div>外掛程式市集接受 <a href="/docs/zh-TW/plugins/marketplace-reference#command-plugin-source"><code>command</code> 來源</a>：本機命令會列印外掛程式目錄，Claude Code 會在每個工作階段中重新解析並應用，無需重新啟動</div>

76 <div>在 Linux 和 WSL 上，將 <a href="/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl"><code>CLAUDE\_CODE\_TOOL\_MEMORY\_LIMIT</code></a> 設定為 <code>4G</code> 之類的大小，以限制 Bash 和 PowerShell 工具命令可以使用的記憶體</div>76 <div>在 Linux 和 WSL 上，將 <a href="/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl"><code>CLAUDE\_CODE\_TOOL\_MEMORY\_LIMIT</code></a> 設定為 <code>4G</code> 之類的大小，以限制 Bash 和 PowerShell 工具命令可以使用的記憶體</div>

77 <div>任務追蹤工具（例如 <code>TaskCreate</code>、<code>TaskUpdate</code> 和 <code>TodoWrite</code>）<a href="/docs/zh-TW/tools-reference#task-tool-availability">在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及更新版本的這些系列上不再可用</a>；設定 <code>CLAUDE\_CODE\_ENABLE\_TODO\_TOOLS=1</code> 以重新啟用它們</div>77 <div>任務追蹤工具（例如 <code>TaskCreate</code>、<code>TaskUpdate</code> 和 <code>TodoWrite</code>）<a href="/docs/zh-TW/tools-reference#task-tool-availability">在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及更新版本的這些系列上不再可用</a>；設定 <code>CLAUDE\_CODE\_ENABLE\_TODO\_TOOLS=1</code> 以重新啟用它們</div>

78 <div><a href="/docs/zh-TW/code-review#review-a-diff-locally"><code>/code-review</code></a> 在高、超高和最大努力級別現在像其他級別一樣在背景代理中執行</div>78 <div><a href="/docs/zh-TW/code-review#review-a-diff-locally"><code>/code-review</code></a> 在高、超高和最大努力級別現在像其他級別一樣在背景代理中執行</div>

79 <div><a href="/docs/zh-TW/discover-plugins#install-plugins"><code>/plugin install plugin\@marketplace</code></a> 首先重新整理市集，因此新發佈的外掛程式無需手動市集更新即可安裝</div>79 <div><a href="/docs/zh-TW/plugins/install#install-a-plugin"><code>/plugin install plugin\@marketplace</code></a> 首先重新整理市集，因此新發佈的外掛程式無需手動市集更新即可安裝</div>

80 <div>設定接受 <a href="/docs/zh-TW/settings-reference#marketplace-key-aliases"><code>additionalMarketplaces</code> 和 <code>allowedMarketplaces</code></a> 作為 <code>extraKnownMarketplaces</code> 和 <code>strictKnownMarketplaces</code> 的別名</div>80 <div>設定接受 <a href="/docs/zh-TW/settings-reference#marketplace-key-aliases"><code>additionalMarketplaces</code> 和 <code>allowedMarketplaces</code></a> 作為 <code>extraKnownMarketplaces</code> 和 <code>strictKnownMarketplaces</code> 的別名</div>

81 <div>在較新的模型上，Claude 可以<a href="/docs/zh-TW/tools-reference#write-tool-behavior">使用 Write 工具覆寫現有檔案</a>，無需在此工作階段中先讀取它，符合 Edit 工具的規則；較舊的模型需要讀取</div>81 <div>在較新的模型上，Claude 可以<a href="/docs/zh-TW/tools-reference#write-tool-behavior">使用 Write 工具覆寫現有檔案</a>，無需在此工作階段中先讀取它，符合 Edit 工具的規則；較舊的模型需要讀取</div>

82 <div>VS Code 擴充功能可以<a href="/docs/zh-TW/vs-code#organize-sessions-into-groups">將工作階段清單組織成群組</a>：按右鍵以建立、重新命名或刪除群組，並使用 Cmd/Ctrl- 或 Shift-點擊以一次移動多個工作階段</div>82 <div>VS Code 擴充功能可以<a href="/docs/zh-TW/vs-code#organize-sessions-into-groups">將工作階段清單組織成群組</a>：按右鍵以建立、重新命名或刪除群組，並使用 Cmd/Ctrl- 或 Shift-點擊以一次移動多個工作階段</div>

whats-new/2026-w37.md +2 −2

Details

54 54

55 <div className="digest-wins-grid">55 <div className="digest-wins-grid">

56 <div>在頂層或 <code>modelSettings</code> 下按模型設定 <a href="/docs/zh-TW/settings-reference#maxeffortlevel"><code>maxEffortLevel</code></a>，以限制每個提供者（包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）上的努力等級；任何更高的等級都會以上限執行</div>56 <div>在頂層或 <code>modelSettings</code> 下按模型設定 <a href="/docs/zh-TW/settings-reference#maxeffortlevel"><code>maxEffortLevel</code></a>，以限制每個提供者（包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）上的努力等級；任何更高的等級都會以上限執行</div>

~~57 <div>將 `--plugin-dir` 指向一個外掛程式資料夾，以 <a href="/docs/zh-TW/plugins#test-your-plugins-locally">載入每個具有資訊清單的直接子資料夾</a></div>~~57 <div>將 `--plugin-dir` 指向一個外掛程式資料夾，以 <a href="/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session">載入每個具有資訊清單的直接子資料夾</a></div>

58 <div>如果 WebFetch 在五分鐘內未完成下載頁面，<a href="/docs/zh-TW/tools-reference#webfetch-tool-behavior">擷取會因截止期限錯誤而失敗</a>，而不是掛起；設定 <code>CLAUDE\_CODE\_WEBFETCH\_DEADLINE\_MS</code> 以變更截止期限，或設定為 <code>0</code> 以移除限制</div>58 <div>如果 WebFetch 在五分鐘內未完成下載頁面，<a href="/docs/zh-TW/tools-reference#webfetch-tool-behavior">擷取會因截止期限錯誤而失敗</a>，而不是掛起；設定 <code>CLAUDE\_CODE\_WEBFETCH\_DEADLINE\_MS</code> 以變更截止期限，或設定為 <code>0</code> 以移除限制</div>

59 <div>將 `--json` 傳遞給 <code>claude plugin install</code>、<code>uninstall</code>、<code>update</code>、<code>enable</code> 或 <code>disable</code>，以將結果列印為 <a href="/docs/zh-TW/plugins-reference#plugin-json-result">stdout 最後一行上的一個 JSON 物件</a></div>59 <div>將 `--json` 傳遞給 <code>claude plugin install</code>、<code>uninstall</code>、<code>update</code>、<code>enable</code> 或 <code>disable</code>，以將結果列印為 <a href="/docs/zh-TW/plugins/cli-reference#plugin-json-result">stdout 最後一行上的一個 JSON 物件</a></div>

60 <div>當自動模式分類器阻止某個動作時，Claude 收到的原因 <a href="/docs/zh-TW/auto-mode-config#fix-a-denial-with-an-allow-rule-an-environment-entry-or-a-retry">通常會命名相符的規則</a>，例如 <code>\[Data Exfiltration]</code></div>60 <div>當自動模式分類器阻止某個動作時，Claude 收到的原因 <a href="/docs/zh-TW/auto-mode-config#fix-a-denial-with-an-allow-rule-an-environment-entry-or-a-retry">通常會命名相符的規則</a>，例如 <code>\[Data Exfiltration]</code></div>

61 <div>當您在提示中途輸入 <code>/</code> 時，您現在可以從 <a href="/docs/zh-TW/interactive-mode#complete-a-command-mid-prompt">相符命令的清單</a>中選擇，而不是單一建議。該清單在全螢幕呈現時隨著您的輸入而開啟。外掛程式技能也會在其名稱上相符，不需要外掛程式前綴</div>61 <div>當您在提示中途輸入 <code>/</code> 時，您現在可以從 <a href="/docs/zh-TW/interactive-mode#complete-a-command-mid-prompt">相符命令的清單</a>中選擇，而不是單一建議。該清單在全螢幕呈現時隨著您的輸入而開啟。外掛程式技能也會在其名稱上相符，不需要外掛程式前綴</div>

62 <div>在 VS Code 擴充功能中，按一下提示框底部的代理計數以開啟 <a href="/docs/zh-TW/vs-code#use-the-prompt-box">代理地圖</a>，您可以在其中開啟子代理的唯讀文字記錄或停止它</div>62 <div>在 VS Code 擴充功能中，按一下提示框底部的代理計數以開啟 <a href="/docs/zh-TW/vs-code#use-the-prompt-box">代理地圖</a>，您可以在其中開啟子代理的唯讀文字記錄或停止它</div>

workflows.md +57 −57

Details

112按 `Enter` 展開詳細資訊。提示和結果隨後會完整顯示，每個列出的呼叫會顯示其輸入和其結果的開始。112按 `Enter` 展開詳細資訊。提示和結果隨後會完整顯示，每個列出的呼叫會顯示其輸入和其結果的開始。

113 113

114<h2 id="have-claude-write-a-workflow">114<h2 id="have-claude-write-a-workflow">

115 讓 Claude 編寫工作流程115 讓 Claude 撰寫工作流程

116</h2>116</h2>

117 117

118您可以通過兩種方式讓 Claude 為您的任務編寫工作流程：118您可以透過兩種方式讓 Claude 為您的任務撰寫工作流程：

119 119

120* [在您的提示中要求工作流程](#ask-for-a-workflow-in-your-prompt)，使用關鍵字 `ultracode`，Claude 為任務編寫一個。120* [在提示中要求工作流程](#ask-for-a-workflow-in-your-prompt)，用您自己的話語或包含關鍵字 `ultracode`，Claude 會為該任務撰寫一個工作流程。

121* [讓 Claude 使用 ultracode 決定](#let-claude-decide-with-ultracode)：設定 `/effort ultracode`，Claude 為工作階段中的每項實質性任務規劃工作流程。121* [讓 Claude 使用 ultracode 決定](#let-claude-decide-with-ultracode)：設定 `/effort ultracode`，Claude 會為工作階段中的每個實質性任務規劃一個工作流程。

122 122

123您也可以執行已存在的工作流程命令：[捆綁的工作流程](#bundled-workflows)如 `/deep-research`，或您[儲存的](#save-the-workflow-for-reuse)工作流程。123您也可以執行已存在的工作流程命令：像 `/deep-research` 這樣的[捆綁工作流程](#bundled-workflows)，或您[保存](#save-the-workflow-for-reuse)的工作流程。

124 124

125<h3 id="ask-for-a-workflow-in-your-prompt">125<h3 id="ask-for-a-workflow-in-your-prompt">

126 在您的提示中要求工作流程126 在提示中要求工作流程

127</h3>127</h3>

128 128

129要在不改變工作階段努力級別的情況下將單個任務作為工作流程執行，請在提示中包含關鍵字 `ultracode`。用您自己的話提問，例如「使用工作流程」或「執行工作流程」，也可以：Claude 將直接請求視為相同的選擇加入。129若要在不變更工作階段努力程度的情況下將單一任務作為工作流程執行，請在提示中包含關鍵字 `ultracode`。用您自己的話語提問，例如「使用工作流程」或「執行工作流程」，也同樣有效：Claude 將直接要求視為相同的選擇加入。

130 130

131```text wrap theme={null}131```text wrap theme={null}

132ultracode: audit every API endpoint under src/routes/ for missing auth checks132ultracode: audit every API endpoint under src/routes/ for missing auth checks

133```133```

134 134

135Claude Code 在您的輸入中突出顯示該關鍵字，Claude 為任務編寫工作流程指令碼，而不是逐輪完成它。該關鍵字只選擇 Claude 如何組織工作：代理的工具呼叫接收與工作階段中任何其他工具呼叫相同的權限檢查和[沙箱隔離](/docs/zh-TW/sandboxing)。135Claude Code 會在您的輸入中突顯該關鍵字，Claude 會為該任務撰寫工作流程指令碼，而不是逐步進行。該關鍵字只會選擇 Claude 如何組織工作：代理程式的工具呼叫會收到與工作階段中任何其他工具呼叫相同的權限檢查和[沙箱隔離](/docs/zh-TW/sandboxing)。

136 136

137如果執行執行您想要的操作，您可以之後[將其儲存為命令](#save-the-workflow-for-reuse)。如果您已經以另一種方式建立了協調器，例如子代理提示的資料夾或一個分散工作的技能，您可以指向 Claude 並要求工作流程執行相同的操作。137如果執行結果符合您的需求，您可以之後[將其保存為命令](#save-the-workflow-for-reuse)。如果您已經用另一種方式建立了協調器，例如子代理程式提示的資料夾或分散工作的技能，您可以指向它並要求 Claude 撰寫執行相同操作的工作流程。

138 138

139<h4 id="dismiss-or-turn-off-the-keyword">139<h4 id="dismiss-or-turn-off-the-keyword">

140 忽略或關閉關鍵字140 關閉或停用關鍵字

141</h4>141</h4>

142 142

143如果您沒有打算啟動工作流程，請在 macOS 上按 `Option+W` 或在 Windows 和 Linux 上按 `Alt+W` 以忽略此提示的突出顯示，或在游標位於突出顯示關鍵字的正後方時按退格鍵。要停止該關鍵字完全觸發，請在 `/config` 中關閉 Ultracode keyword trigger。143如果您不打算啟動工作流程，請在 macOS 上按 `Option+W` 或在 Windows 和 Linux 上按 `Alt+W` 以關閉此提示的突顯，或在游標位於突顯關鍵字之後時按退格鍵。若要完全停止關鍵字觸發，請在 `/config` 中關閉 Ultracode 關鍵字觸發。

144 144

145<h4 id="where-the-keyword-works">145<h4 id="where-the-keyword-works">

146 關鍵字在何處有效146 關鍵字的適用位置

147</h4>147</h4>

148 148

149該關鍵字是一個選擇加入，僅在您自己輸入的提示中有效：在互動式提示、IDE 擴充面板、[Remote Control](/docs/zh-TW/remote-control) 用戶端，或在 Agent SDK 應用程式中，該應用程式將您的鍵盤輸入的 [`origin`](/docs/zh-TW/agent-sdk/typescript#sdkmessageorigin) 標記為 `{ kind: "human" }`。當提示以另一種方式進入工作階段時，它不會啟動工作流程：149該關鍵字是僅在您自己輸入的提示中選擇加入：在互動式提示、IDE 擴充面板、[遠端控制](/docs/zh-TW/remote-control)用戶端或在代理程式 SDK 應用程式中，該應用程式將您的鍵盤輸入的 [`origin`](/docs/zh-TW/agent-sdk/typescript#sdkmessageorigin) 標記為 `{ kind: "human" }`。當它以其他方式進入工作階段時，不會啟動工作流程：

150 150

151* 使用 `-p` 傳遞的提示151* 使用 `-p` 傳遞的提示

152* Agent SDK 應用程式發送的提示，未將其標記為人類輸入152* 代理程式 SDK 應用程式發送但未標記為人類輸入的提示

153* 排程任務提示153* 排程任務提示

154* 轉發到對話中的 webhook 負載或拉取請求評論154* 轉發到對話中的 webhook 承載或拉取要求評論

155 155

156<Note>156<Note>

157 在 v2.1.210 之前，該關鍵字也從這些路由中的任何一個啟動工作流程，包括轉發到對話中的 webhook 負載或拉取請求評論。157 在 v2.1.210 之前，該關鍵字也會從這些路由中的任何一個啟動工作流程，包括轉發到對話中的 webhook 承載或拉取要求評論。

158</Note>158</Note>

159 159

160<h3 id="let-claude-decide-with-ultracode">160<h3 id="let-claude-decide-with-ultracode">

161 讓 Claude 使用 ultracode 決定161 讓 Claude 使用 ultracode 決定

162</h3>162</h3>

163 163

164Ultracode 是一個 Claude Code 設定，結合 `xhigh` [推理努力](/docs/zh-TW/model-config#adjust-effort-level)與自動工作流程協調。啟用它後，Claude 為每項實質性任務規劃工作流程，而不是等待您要求。164Ultracode 是一個 Claude Code 設定，它結合了 `xhigh` [推理努力](/docs/zh-TW/model-config#adjust-effort-level)與自動工作流程協調。啟用它後，Claude 會為每個實質性任務規劃一個工作流程，而不是等待您提出要求。

165 165

166```text wrap theme={null}166```text wrap theme={null}

167/effort ultracode167/effort ultracode

168```168```

169 169

170要啟動已啟用 ultracode 的工作階段，請使用 `claude --effort ultracode` 啟動。需要 Claude Code v2.1.203 或更新版本。170若要在已啟用 ultracode 的情況下啟動工作階段，請使用 `claude --effort ultracode` 啟動。需要 Claude Code v2.1.203 或更新版本。

171 171

172要在您選擇模型時啟用它，使用箭頭鍵將 `/model` 選擇器的努力滑塊移動到 `ultracode`。[調整努力級別](/docs/zh-TW/model-config#adjust-effort-level)列出啟用 ultracode 的路由。172若要在選擇模型時啟用它，請使用箭頭鍵將 `/model` 選擇器的努力滑塊移至 `ultracode`。[調整努力程度](/docs/zh-TW/model-config#adjust-effort-level)列出了啟用 ultracode 的路由。

173 173

174啟用 ultracode 後，Claude 決定任務何時值得工作流程。單個請求可以變成一系列工作流程：一個用於理解程式碼，一個用於進行更改，一個用於驗證它。這適用於工作階段中的每項任務，因此每個請求使用更多令牌並花費比較低努力級別更長的時間。174啟用 ultracode 後，Claude 會決定任務何時需要工作流程。單一要求可以轉變為連續的多個工作流程：一個用於理解程式碼，一個用於進行變更，一個用於驗證。這適用於工作階段中的每個任務，因此每個要求使用更多令牌並花費比較低努力程度更長的時間。

175 175

176`/effort ultracode` 持續當前工作階段；要讓每個工作階段都以它開始，設定 [`ultracode`](/docs/zh-TW/settings-reference#ultracode) 設定。當您返回日常工作時，使用 `/effort high` 下降。它在支援 `xhigh` [努力](/docs/zh-TW/model-config#adjust-effort-level)的模型上可用；在其他模型上，`/effort` 功能表不提供它。176`/effort ultracode` 持續整個目前工作階段；若要讓每個工作階段都以它開始，請設定 [`ultracode`](/docs/zh-TW/settings-reference#ultracode) 設定。當您返回例行工作時，使用 `/effort high` 降級。`/effort` 功能表僅在 [ultracode 可用時](/docs/zh-TW/model-config#when-ultracode-is-available)提供它。

177 177

178<h3 id="approve-the-plan-before-it-runs">178<h3 id="approve-the-plan-before-it-runs">

179 在執行前批准計畫179 在執行前批准計畫

180</h3>180</h3>

181 181

182在 CLI 中，每次執行提示顯示計畫的階段和這些選項：182在 CLI 中，每次執行提示會顯示計畫的階段和這些選項：

183 183

184* **是，執行它**：啟動執行184* **Yes, run it**：啟動執行

185* **是，不再詢問 `<name>` 在 `<path>` 中**：啟動，並從現在開始跳過此專案中此工作流程的此提示。Claude Code 在您按名稱執行捆綁、儲存或外掛工作流程時提供此選項，而不是針對 Claude 為當前任務編寫的指令碼。185* **Yes, and don't ask again for `<name>` in `<path>`**：啟動，並從現在開始在此專案中跳過此工作流程的此提示。當您按名稱執行捆綁、保存或外掛工作流程時，Claude Code 會提供此選項，而不是針對 Claude 為目前任務撰寫的指令碼。

186* **檢視原始指令碼**：在決定前讀取指令碼186* **View raw script**：在決定前讀取指令碼

187* **否**：取消187* **No**：取消

188 188

189`Ctrl+G` 在您的編輯器中開啟指令碼。`Tab` 讓您在執行啟動前調整提示。189`Ctrl+G` 在您的編輯器中開啟指令碼。`Tab` 讓您在執行開始前調整提示。

190 190

191您是否看到此提示取決於您的[權限模式](/docs/zh-TW/permission-modes)：191您是否看到此提示取決於您的[權限模式](/docs/zh-TW/permission-modes)：

192 192

193| 權限模式 | 何時提示您 |193| 權限模式 | 何時提示您 |

194| :-------------------- | :--------------------------------------------------------- |194| :--------------------- | :------------------------------------------------------------ |

195| 自動 | 首次啟動。任何**是**在您的使用者設定中記錄同意，稍後啟動無需提示即可啟動。當 ultracode 啟用時完全跳過 |195| Auto | 僅首次啟動。任何 **Yes** 會在您的使用者設定中記錄同意，之後啟動時不會提示。當 ultracode 啟用時完全跳過 |

196| 手動、接受編輯 | 每次執行，除非您已為此專案中的該工作流程選擇**是，不再詢問** |196| Manual, accept edits | 每次執行，除非您已為此專案中的該工作流程選擇 **Yes, and don't ask again** |

197| 繞過權限 | Claude Code 不提示您。執行立即啟動 |197| Bypass permissions | Claude Code 不會提示您。執行立即啟動 |

199 199

200在 `claude -p` 和 Agent SDK 中，Claude Code 永遠不會顯示此提示。它通過與工作階段其餘部分相同的[權限評估](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)執行 Workflow 工具呼叫，因此拒絕規則、詢問規則和 `dontAsk` 模式適用於啟動，就像它們適用於每個工具呼叫一樣。要讓工作流程在這些執行中啟動，請使用以下其中之一：200在 `claude -p` 和 Agent SDK 中，Claude Code 永遠不會顯示此提示。它透過與工作階段其餘部分相同的[權限評估](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)執行 Workflow 工具呼叫，因此拒絕規則、詢問規則和 `dontAsk` 模式適用於啟動，就像它們適用於每個工具呼叫一樣。若要讓工作流程在這些執行中啟動，請使用以下其中一個：

201 201

202* **權限規則**：您允許規則中的 `Workflow` 批准每個工作流程，`Workflow(<name>)` 按名稱批准一個儲存的工作流程。202* **Permission rule**：您允許規則中的 `Workflow` 批准每個工作流程，`Workflow(<name>)` 按名稱批准一個保存的工作流程。

203* **自動權限模式**：[分類器](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)審查呼叫並可以批准它。203* **Auto permission mode**：[分類器](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)檢查呼叫並可以批准它。

204* **繞過權限模式**：Claude Code 批准呼叫。204* **Bypass permissions mode**：Claude Code 批准呼叫。

205* **`PreToolUse` 鉤子**：為呼叫返回 `allow` 的[鉤子](/docs/zh-TW/hooks#pretooluse)批准它。205* **A `PreToolUse` hook**：返回呼叫 `allow` 的[鉤子](/docs/zh-TW/hooks#pretooluse)批准它。

206* **您的主機**：[`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags)批准它，或使用 Agent SDK，[`canUseTool`](/docs/zh-TW/agent-sdk/permissions)回呼或[`PermissionRequest` 鉤子](/docs/zh-TW/hooks#permissionrequest)批准它。206* **Your host**：[`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 批准它，或使用 Agent SDK，[`canUseTool`](/docs/zh-TW/agent-sdk/permissions) 回呼或 [`PermissionRequest` 鉤子](/docs/zh-TW/hooks#permissionrequest)批准它。

207 207

208在桌面應用程式中，批准卡顯示工作流程名稱、階段列表和令牌使用警告，具有**一次**、**始終**和**拒絕**動作。進度檢視出現在背景任務側窗格中。208在桌面應用程式中，批准卡會顯示工作流程名稱、階段清單和令牌使用警告，具有 **Once**、**Always** 和 **Deny** 動作。進度檢視會出現在「背景任務」側窗格中。

209 209

210工作流程生成的子代理使用您的[權限規則](/docs/zh-TW/settings-reference#permission-settings)，Claude Code 根據[子代理執行的權限模式](/docs/zh-TW/sub-agents#permission-modes)下的規則選擇其權限模式。要在長時間執行時避免提示，請在啟動前將代理需要的工具新增到您的允許規則。210工作流程產生的子代理程式使用您的[權限規則](/docs/zh-TW/settings-reference#permission-settings)，Claude Code 根據[子代理程式執行的權限模式](/docs/zh-TW/sub-agents#permission-modes)下的規則選擇其權限模式。若要避免在長時間執行時出現提示，請在啟動前將代理程式需要的工具新增到您的允許規則。

211 211

212<h3 id="save-the-workflow-for-reuse">212<h3 id="save-the-workflow-for-reuse">

213 儲存工作流程以供重複使用213 保存工作流程以供重複使用

214</h3>214</h3>

215 215

216當 Claude 為您將重複的任務編寫工作流程時，您可以將該執行的指令碼儲存為命令。一個您在每個分支上執行的審查流程然後每次執行相同的協調。216當 Claude 為您將重複的任務撰寫工作流程時，您可以將該執行的指令碼保存為命令。像在每個分支上執行的檢查這樣的程序然後每次執行相同的協調。

217 217

218執行 `/workflows`，選擇您想保留的執行，然後按 `s`。在儲存對話中，Tab 在兩個儲存位置之間切換：218執行 `/workflows`，選擇您想保留的執行，然後按 `s`。在保存對話中，Tab 在兩個保存位置之間切換：

219 219

220* `.claude/workflows/` 在您的專案中：與克隆儲存庫的每個人共享220* 您專案中的 `.claude/workflows/`：與克隆儲存庫的每個人共享

221* `~/.claude/workflows/` 在您的主目錄中：在每個專案中可用，僅對您可見。如果您設定了 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars)，此位置是該路徑下的 `workflows/` 目錄。221* 您主目錄中的 `~/.claude/workflows/`：在每個專案中可用，僅對您可見。如果您設定了 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars)，此位置是該路徑下的 `workflows/` 目錄。

222 222

223儲存對話顯示個人位置的已解析路徑。223保存對話會顯示個人位置的已解析路徑。

224 224

225按 Enter 儲存。工作流程在未來工作階段中從任一位置作為 `/<name>` 執行。225按 Enter 保存。工作流程在未來工作階段中從任一位置作為 `/<name>` 執行。

226 226

227Claude Code 在寫入前檢查儲存位置是否有符號連結，並顯示錯誤而不是通過一個寫入。它檢查的內容取決於您儲存的位置：227Claude Code 在寫入前檢查保存位置是否有符號連結，並顯示錯誤而不是透過符號連結寫入。它檢查的內容取決於您保存的位置：

228 228

229* 專案位置：如果 `.claude`、`.claude/workflows` 或目標檔案是符號連結，Claude Code 拒絕。229* 專案位置：如果 `.claude`、`.claude/workflows` 或目標檔案是符號連結，Claude Code 會拒絕。

230* 個人位置：Claude Code 只有在目標檔案本身是符號連結時才拒絕，因此由 dotfiles 工具管理的 `~/.claude` 目錄仍然有效。230* 個人位置：Claude Code 僅在目標檔案本身是符號連結時拒絕，因此由 dotfiles 工具管理的 `~/.claude` 目錄仍然有效。

231 231

232在 v2.1.216 之前，Claude Code 跟隨連結，這可能會將檔案放在您選擇的位置之外。232在 v2.1.216 之前，Claude Code 跟隨連結，這可能會將檔案放在您選擇的位置之外。

233 233

234在具有多個 `.claude/` 目錄的 monorepo 中，您可以將工作流程保留在它們適用的套件旁邊。儲存到專案位置會寫入您的工作目錄和儲存庫根目錄之間已存在的最接近的 `.claude/workflows/` 目錄，或如果尚不存在則寫入儲存庫根目錄。專案工作流程也從該路徑沿著的每個 `.claude/workflows/` 載入，當多個定義相同名稱時 Claude Code 執行最接近工作目錄的那個。234在具有多個 `.claude/` 目錄的 monorepo 中，您可以將工作流程保留在它們適用的套件旁邊。保存到專案位置會寫入您的工作目錄和儲存庫根目錄之間已存在的最接近的 `.claude/workflows/` 目錄，或如果尚不存在，則寫入儲存庫根目錄。專案工作流程也會從該路徑沿著的每個 `.claude/workflows/` 載入，當多個定義相同名稱時，Claude Code 執行最接近工作目錄的那個。

235 235

236如果專案工作流程和個人工作流程共享名稱，則執行專案工作流程。236如果專案工作流程和個人工作流程共享名稱，則執行專案工作流程。

237 237

239 在外掛中分發工作流程239 在外掛中分發工作流程

240</h3>240</h3>

241 241

242要在團隊或儲存庫之間共享工作流程，請將其包含在[外掛](/docs/zh-TW/plugins)中。將指令碼放在外掛根目錄的 `workflows/` 目錄中，或使用 [`workflows` 清單欄位](/docs/zh-TW/plugins-reference#component-path-fields)指向不同的位置。242若要在團隊或儲存庫之間共享工作流程，請將其包含在[外掛](/docs/zh-TW/plugins/overview)中。將指令碼放在外掛根目錄的 `workflows/` 目錄中，或使用 [`workflows` 資訊清單欄位](/docs/zh-TW/plugins/manifest-reference#fields)指向不同位置。

243 243

244外掛工作流程由外掛名稱命名空間。一個名為 `acme-tools` 的外掛，其中包含 `meta.name` 為 `release-audit` 的指令碼，執行為 `/acme-tools:release-audit`。244外掛工作流程由外掛名稱命名空間。名為 `acme-tools` 的外掛，其 `meta.name` 為 `release-audit` 的指令碼作為 `/acme-tools:release-audit` 執行。

245 245

246<h3 id="pass-input-to-a-saved-workflow">246<h3 id="pass-input-to-a-saved-workflow">

247 將輸入傳遞給已儲存的工作流程247 將輸入傳遞到保存的工作流程

248</h3>248</h3>

249 249

250已儲存的工作流程可以通過 `args` 參數接受輸入。指令碼將其讀取為名為 `args` 的全域變數。使用此功能在調用時提供研究問題、目標路徑清單或配置物件，而不是為每次執行編輯指令碼。250保存的工作流程可以透過 `args` 參數接受輸入。指令碼將其讀取為名為 `args` 的全域變數。使用此方法在呼叫時提供研究問題、目標路徑清單或設定物件，而不是為每次執行編輯指令碼。

251 251

252以下提示使用問題編號清單執行已儲存的工作流程：252以下提示使用問題編號清單執行保存的工作流程：

253 253

254```text wrap theme={null}254```text wrap theme={null}

255Run /triage-issues on issues 1024, 1025, and 1030255Run /triage-issues on issues 1024, 1025, and 1030

256```256```

257 257

258Claude 將清單作為結構化資料傳遞，因此指令碼可以直接在 `args` 上呼叫陣列和物件方法，無需先解析它。如果省略 `args`，全域變數在指令碼內為 `undefined`。258Claude 將清單作為結構化資料傳遞，因此指令碼可以直接在 `args` 上呼叫陣列和物件方法，而無需先解析它。如果省略 `args`，全域變數在指令碼內為 `undefined`。

259 259

260<h2 id="example-workflow-prompts">260<h2 id="example-workflow-prompts">

261 工作流程提示範例261 工作流程提示範例

worktrees.md +3 −1

Details

256Worktree 獲得自己的檔案和分支，但它與主要檢出共享以下內容：256Worktree 獲得自己的檔案和分支，但它與主要檢出共享以下內容：

257 257

258* **儲存庫的 `.git` 目錄**：worktree 中的 git 命令寫入主儲存庫的共享 `.git` 目錄，[沙箱化](/docs/zh-TW/sandboxing#filesystem-isolation)允許這些寫入，因此 `git commit` 等命令可以從啟用沙箱的 worktree 內部工作。258* **儲存庫的 `.git` 目錄**：worktree 中的 git 命令寫入主儲存庫的共享 `.git` 目錄，[沙箱化](/docs/zh-TW/sandboxing#filesystem-isolation)允許這些寫入，因此 `git commit` 等命令可以從啟用沙箱的 worktree 內部工作。

259* **外掛程式**：從主要檢出在[專案範圍](/docs/zh-TW/plugins-reference#plugin-installation-scopes)安裝的外掛程式也會在同一儲存庫的 worktrees 中載入，因此您不需要為每個 worktree 重新安裝它們。需要 Claude Code v2.1.200 或更新版本。259* **外掛程式**：從主要檢出在[專案範圍](/docs/zh-TW/plugins/loading#find-where-a-plugin-is-enabled)安裝的外掛程式也會在同一儲存庫的 worktrees 中載入，因此您不需要為每個 worktree 重新安裝它們。需要 Claude Code v2.1.200 或更新版本。

260* **權限批准**：在 worktree 會話中為 Bash 命令選擇「是，不再詢問」會將規則儲存到主要檢出的 `.claude/settings.local.json`，因此它適用於主要檢出和儲存庫的每個其他 worktree，並在 worktree 移除後存活。在 Windows 和 Claude Code [不使用儲存庫根目錄](/docs/zh-TW/settings#where-claude-code-looks-for-each-file)的其他情況下，規則會保留在該 worktree 中。在 v2.1.211 之前，在 worktree 中授予的批准被儲存在該 worktree 內，不適用於其他地方，並在 worktree 移除時丟失。請參閱[批准的儲存位置](/docs/zh-TW/permissions#permission-system)。260* **權限批准**：在 worktree 會話中為 Bash 命令選擇「是，不再詢問」會將規則儲存到主要檢出的 `.claude/settings.local.json`，因此它適用於主要檢出和儲存庫的每個其他 worktree，並在 worktree 移除後存活。在 Windows 和 Claude Code [不使用儲存庫根目錄](/docs/zh-TW/settings#where-claude-code-looks-for-each-file)的其他情況下，規則會保留在該 worktree 中。在 v2.1.211 之前，在 worktree 中授予的批准被儲存在該 worktree 內，不適用於其他地方，並在 worktree 移除時丟失。請參閱[批准的儲存位置](/docs/zh-TW/permissions#permission-system)。

261* **未追蹤的技能、代理程式和命令**：當 worktree 檢出在其根目錄沒有 `.claude/skills` 目錄時（例如因為您的 `.claude/skills` 被 gitignored），Claude Code 會在 worktree 會話中載入主要檢出的[專案技能](/docs/zh-TW/skills#where-skills-live)。在具有自己的 `.claude/skills` 目錄的 worktree 中，只會載入該副本。261* **未追蹤的技能、代理程式和命令**：當 worktree 檢出在其根目錄沒有 `.claude/skills` 目錄時（例如因為您的 `.claude/skills` 被 gitignored），Claude Code 會在 worktree 會話中載入主要檢出的[專案技能](/docs/zh-TW/skills#where-skills-live)。在具有自己的 `.claude/skills` 目錄的 worktree 中，只會載入該副本。

262 262

330 330

331將其與 `WorktreeRemove` hook 配對以在會話結束時進行清理。有關輸入架構和移除範例，請參閱 [hooks 參考](/docs/zh-TW/hooks#worktreecreate)。331將其與 `WorktreeRemove` hook 配對以在會話結束時進行清理。有關輸入架構和移除範例，請參閱 [hooks 參考](/docs/zh-TW/hooks#worktreecreate)。

332 332

333`WorktreeCreate` hook 也可讓您在 git 儲存庫外執行 [`/batch`](/docs/zh-TW/commands#all-commands)。每個 `/batch` 子代理程式隨後會使用您專案的版本控制命令發佈其變更，當無法開啟提取請求時，會改為報告其發佈的內容。在 git 儲存庫外執行 `/batch` 需要 Claude Code v2.1.281 或更新版本。

334

333<h2 id="troubleshooting">335<h2 id="troubleshooting">

334 疑難排解336 疑難排解

335</h2>337</h2>

zero-data-retention.md +1 −1

Details

66| 功能 | 原因 |66| 功能 | 原因 |

67| -------------------------------------------------------------------------------------------------------- | ------------------------------------ |67| -------------------------------------------------------------------------------------------------------- | ------------------------------------ |

68| [Cloud sessions](/docs/zh-TW/claude-code-on-the-web)，包括從 [Desktop app](/docs/zh-TW/desktop#cloud-sessions) 啟動的工作階段 | 需要伺服器端儲存工作階段資料，包括包含提示和完成內容的對話歷史記錄。 |68| [Cloud sessions](/docs/zh-TW/claude-code-on-the-web)，包括從 [Desktop app](/docs/zh-TW/desktop#cloud-sessions) 啟動的工作階段 | 需要伺服器端儲存工作階段資料，包括包含提示和完成內容的對話歷史記錄。 |

~~69| [Claude Tag](/docs/zh-TW/claude-tag) | 保留頻道記憶和工作階段文字記錄。 |~~69| [Claude Tag](https://claude.com/docs/claude-tag) | 保留頻道記憶和工作階段文字記錄。 |

70| [Artifacts](/docs/zh-TW/artifacts) | 需要在 Anthropic 營運的基礎設施上儲存已發佈的頁面內容。 |70| [Artifacts](/docs/zh-TW/artifacts) | 需要在 Anthropic 營運的基礎設施上儲存已發佈的頁面內容。 |

72| [Remote Control](/docs/zh-TW/remote-control) | 在 Anthropic 伺服器上儲存工作階段文字記錄，以跨裝置同步對話。 |72| [Remote Control](/docs/zh-TW/remote-control) | 在 Anthropic 伺服器上儲存工作階段文字記錄，以跨裝置同步對話。 |

Documentation 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC