Documentation — Spybara

claude-apps-gateway-deploy.md +28 −26

Details

6 6

7> 向您的身份提供者註冊閘道、建置容器、在 Kubernetes 或 Cloud Run 上部署，並運營它：健康檢查、祕密輪換、升級和安全性。7> 向您的身份提供者註冊閘道、建置容器、在 Kubernetes 或 Cloud Run 上部署，並運營它：健康檢查、祕密輪換、升級和安全性。

8 8

9本頁涵蓋執行 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway) 的運營方面：在您的身份提供者 (IdP) 中註冊 OAuth 用戶端、將閘道部署為容器，以及日常運營。關於閘道在啟動時讀取的 `gateway.yaml` 檔案中的每個選項，請參閱 [設定參考](/zh-TW/claude-apps-gateway-config)。9本頁涵蓋執行 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) 的運營方面：在您的身份提供者 (IdP) 中註冊 OAuth 用戶端、將閘道部署為容器，以及日常運營。關於閘道在啟動時讀取的 `gateway.yaml` 檔案中的每個選項，請參閱 [設定參考](/docs/zh-TW/claude-apps-gateway-config)。

10 10

11生產部署按順序遵循四個步驟，下面的章節與之相符。前兩個是您做出選擇的地方；後兩個是一旦運行時要查閱的參考資料。11生產部署按順序遵循四個步驟，下面的章節與之相符。前兩個是您做出選擇的地方；後兩個是一旦運行時要查閱的參考資料。

12 12

31 31

32任何 OIDC 相容的 IdP 都可以使用：Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、PingFederate 等。IdP 必須滿足三個要求：32任何 OIDC 相容的 IdP 都可以使用：Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、PingFederate 等。IdP 必須滿足三個要求：

33 33

34* 在生產環境中透過 HTTPS 提供 `/.well-known/openid-configuration`；閘道接受 [`http://` 發行者](/zh-TW/claude-apps-gateway-config#oidc)，環回發行者另外需要 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`34* 在生產環境中透過 HTTPS 提供 `/.well-known/openid-configuration`；閘道接受 [`http://` 發行者](/docs/zh-TW/claude-apps-gateway-config#oidc)，環回發行者另外需要 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`

35* 支援授權碼流程。PKCE（代碼交換的證明金鑰）預設開啟；對於不支援它的 IdP，使用 `oidc.use_pkce: false` 停用它35* 支援授權碼流程。PKCE（代碼交換的證明金鑰）預設開啟；對於不支援它的 IdP，使用 `oidc.use_pkce: false` 停用它

36* 在 id\_token 中傳回 `email` 和可選的 `groups`，或使用 `oidc.userinfo_fallback: true` 從 userinfo 端點提供它們36* 在 id\_token 中傳回 `email` 和可選的 `groups`，或使用 `oidc.userinfo_fallback: true` 從 userinfo 端點提供它們

37 37

41 41

42* **Okta**：位於 `https://example.okta.com` 的組織授權伺服器傳回省略 `email` 和 `groups` 的簡化 id\_token，因此當您將其用作 `issuer` 時設定 `oidc.userinfo_fallback: true`。包含 id\_token 中 `email` 和可選 `groups` 的自訂授權伺服器（例如 `https://example.okta.com/oauth2/default`）直接發出它們，不需要回退。Okta 只在 `oidc.scopes` 中請求 `groups` 範圍且應用程式的群組聲明篩選器允許時才發出 `groups`；`userinfo_fallback` 無法填充 IdP 未被要求的聲明。42* **Okta**：位於 `https://example.okta.com` 的組織授權伺服器傳回省略 `email` 和 `groups` 的簡化 id\_token，因此當您將其用作 `issuer` 時設定 `oidc.userinfo_fallback: true`。包含 id\_token 中 `email` 和可選 `groups` 的自訂授權伺服器（例如 `https://example.okta.com/oauth2/default`）直接發出它們，不需要回退。Okta 只在 `oidc.scopes` 中請求 `groups` 範圍且應用程式的群組聲明篩選器允許時才發出 `groups`；`userinfo_fallback` 無法填充 IdP 未被要求的聲明。

43* **Microsoft Entra ID**：`issuer` = `https://login.microsoftonline.com/<tenant-id>/v2.0`。Entra 發出群組物件 ID 而不是名稱，因此在 `managed.policies.match.groups` 中使用 GUID，或使用應用程式角色以獲得人類可讀的名稱。如果您的租戶在 `roles` 而不是 `groups` 下發出角色，設定 `oidc.groups_claim: roles`。43* **Microsoft Entra ID**：`issuer` = `https://login.microsoftonline.com/<tenant-id>/v2.0`。Entra 發出群組物件 ID 而不是名稱，因此在 `managed.policies.match.groups` 中使用 GUID，或使用應用程式角色以獲得人類可讀的名稱。如果您的租戶在 `roles` 而不是 `groups` 下發出角色，設定 `oidc.groups_claim: roles`。

44* **Google Workspace**：`issuer` = `https://accounts.google.com`。Google 的 id\_token 不包含群組。要將基於群組的 `allowed_groups` 或 `managed.policies` 與 Google 作為 IdP 一起使用，請配置 [`oidc.google_groups`](/zh-TW/claude-apps-gateway-config#oidc)，它使用具有網域範圍委派的服務帳戶透過 Admin SDK Directory API 查詢每個使用者的群組。沒有它，使用 `oidc.allowed_email_domains` 進行成員資格閘道和 `managed.policies.match.email_domain` 進行原則分配。Google 也忽略標準 `offline_access` 範圍。對於重新整理令牌，設定 `oidc.scopes: [openid, profile, email]` 和 `oidc.extra_auth_params: { access_type: offline, prompt: consent }`。44* **Google Workspace**：`issuer` = `https://accounts.google.com`。Google 的 id\_token 不包含群組。要將基於群組的 `allowed_groups` 或 `managed.policies` 與 Google 作為 IdP 一起使用，請配置 [`oidc.google_groups`](/docs/zh-TW/claude-apps-gateway-config#oidc)，它使用具有網域範圍委派的服務帳戶透過 Admin SDK Directory API 查詢每個使用者的群組。沒有它，使用 `oidc.allowed_email_domains` 進行成員資格閘道和 `managed.policies.match.email_domain` 進行原則分配。Google 也忽略標準 `offline_access` 範圍。對於重新整理令牌，設定 `oidc.scopes: [openid, profile, email]` 和 `oidc.extra_auth_params: { access_type: offline, prompt: consent }`。

45 45

46如需有關上述未涵蓋的身份提供者的支援，請參閱[疑難排解](#troubleshooting)。46如需有關上述未涵蓋的身份提供者的支援，請參閱[疑難排解](#troubleshooting)。

47 47

48<Warning>48<Warning>

49 重新整理令牌讓閘道無聲地更新開發人員的會話，無需將開發人員送回瀏覽器。它們也驅動取消配置，因為當 IdP 停用使用者時，下一次重新整理失敗，會話在 `ttl_hours` 內結束。閘道預設請求 `offline_access` 以獲取重新整理令牌。如果您的 IdP 需要明確同意離線存取，請配置 OAuth 用戶端以允許它。49 重新整理令牌讓閘道無聲地更新開發人員的會話，無需將開發人員送回瀏覽器。它們也驅動取消配置，因為當 IdP 停用使用者時，下一次重新整理失敗，會話在 `ttl_hours` 內結束。閘道預設請求 `offline_access` 以獲取重新整理令牌。如果您的 IdP 需要明確同意離線存取，請配置 OAuth 用戶端以允許它。

50 50

51 如果您的 IdP 根本無法發出重新整理令牌，閘道仍然可以工作，但沒有無聲更新，因此開發人員在會話過期時重新執行瀏覽器登入。為了防止每小時發生一次，將 [`session.ttl_hours`](/zh-TW/claude-apps-gateway-config#session) 提高到 `8` 或 `12`。權衡是取消配置延遲，因為沒有重新整理令牌，被停用的使用者在更長的 TTL 經過之前保持存取權限。51 如果您的 IdP 根本無法發出重新整理令牌，閘道仍然可以工作，但沒有無聲更新，因此開發人員在會話過期時重新執行瀏覽器登入。為了防止每小時發生一次，將 [`session.ttl_hours`](/docs/zh-TW/claude-apps-gateway-config#session) 提高到 `8` 或 `12`。權衡是取消配置延遲，因為沒有重新整理令牌，被停用的使用者在更長的 TTL 經過之前保持存取權限。

52</Warning>52</Warning>

53 53

54<h2 id="deployment">54<h2 id="deployment">

62除了它執行的位置之外，還有一些決策塑造部署：62除了它執行的位置之外，還有一些決策塑造部署：

63 63

64* **成本**：閘道沒有單獨的許可證或按座位費用；它是 `claude` 二進位檔案的一部分。您透過現有的雲端或 Anthropic 承諾為推理付費，加上容器的計算和您的遙測收集器。64* **成本**：閘道沒有單獨的許可證或按座位費用；它是 `claude` 二進位檔案的一部分。您透過現有的雲端或 Anthropic 承諾為推理付費，加上容器的計算和您的遙測收集器。

65* **繞過**：閘道不強制執行通往模型的唯一路由必須通過它。具有自己認證的開發人員仍然可以直接呼叫提供者，因此關閉該路徑是網路原則決策，例如阻止到 `api.anthropic.com` 的出口，除了來自閘道。阻止該出口也會破壞 [WebFetch 網域安全檢查](/zh-TW/data-usage#webfetch-domain-safety-check)，它從每個開發人員的機器呼叫 `api.anthropic.com`；在受管原則中設定 `skipWebFetchPreflight: true` 以停用它。65* **繞過**：閘道不強制執行通往模型的唯一路由必須通過它。具有自己認證的開發人員仍然可以直接呼叫提供者，因此關閉該路徑是網路原則決策，例如阻止到 `api.anthropic.com` 的出口，除了來自閘道。阻止該出口也會破壞 [WebFetch 網域安全檢查](/docs/zh-TW/data-usage#webfetch-domain-safety-check)，它從每個開發人員的機器呼叫 `api.anthropic.com`；在受管原則中設定 `skipWebFetchPreflight: true` 以停用它。

66* **多個閘道**：每個閘道是一個單獨的部署，具有自己的配置。CLI 按閘道主機名儲存其信任指紋和認證，因此不同的團隊可以連接到不同的閘道而不會衝突。要提供多個 OIDC 發行者，請執行單獨的實例。66* **多個閘道**：每個閘道是一個單獨的部署，具有自己的配置。CLI 按閘道主機名儲存其信任指紋和認證，因此不同的團隊可以連接到不同的閘道而不會衝突。要提供多個 OIDC 發行者，請執行單獨的實例。

67* **無伺服器**：Cloud Run 可以工作；設定 `min-instances: 1` 以避免冷 OIDC 發現。Lambda 和 Cloud Functions 不行，因為閘道是長時間執行的 HTTP 伺服器。67* **無伺服器**：Cloud Run 可以工作；設定 `min-instances: 1` 以避免冷 OIDC 發現。Lambda 和 Cloud Functions 不行，因為閘道是長時間執行的 HTTP 伺服器。

68 68

69此處的每個生產拓撲都在純 HTTP 副本前面放置 L7 代理，例如 Ingress、Cloud Run 的前端或 ALB。設定 [`listen.trusted_proxies`](/zh-TW/claude-apps-gateway-config#listen) 為代理的來源範圍，以便閘道從 `X-Forwarded-For` 讀取用戶端 IP。閘道只在 TCP 對等體受信任時才遵守標頭；[Google Cloud 實際工作範例](/zh-TW/claude-apps-gateway-on-gcp) 為每個拓撲提供具體值。沒有受信任的代理，每個請求似乎都來自代理的 IP，這會將按 IP 速率限制摺疊為一個共享桶，並在審計事件中記錄代理的 IP。69此處的每個生產拓撲都在純 HTTP 副本前面放置 L7 代理，例如 Ingress、Cloud Run 的前端或 ALB。設定 [`listen.trusted_proxies`](/docs/zh-TW/claude-apps-gateway-config#listen) 為代理的來源範圍，以便閘道從 `X-Forwarded-For` 讀取用戶端 IP。閘道只在 TCP 對等體受信任時才遵守標頭；[Google Cloud 實際工作範例](/docs/zh-TW/claude-apps-gateway-on-gcp) 為每個拓撲提供具體值。沒有受信任的代理，每個請求似乎都來自代理的 IP，這會將按 IP 速率限制摺疊為一個共享桶，並在審計事件中記錄代理的 IP。

70 70

71<h3 id="container-image">71<h3 id="container-image">

72 容器映像72 容器映像

74 74

75圍繞標準 Claude Code 版本中的原生 `claude` 二進位檔案建置您自己的映像：75圍繞標準 Claude Code 版本中的原生 `claude` 二進位檔案建置您自己的映像：

76 76

~~771. 從固定版本下載您的映像架構的 Linux 建置；請參閱 [安裝特定版本](/zh-TW/setup#install-a-specific-version) 以取得下載 URL。~~771. 從固定版本下載您的映像架構的 Linux 建置；請參閱 [安裝特定版本](/docs/zh-TW/setup#install-a-specific-version) 以取得下載 URL。

~~782. 根據 [二進位完整性和代碼簽名](/zh-TW/setup#binary-integrity-and-code-signing) 中所述，根據版本的 GPG 簽名 `manifest.json` 驗證它。~~782. 根據 [二進位完整性和代碼簽名](/docs/zh-TW/setup#binary-integrity-and-code-signing) 中所述，根據版本的 GPG 簽名 `manifest.json` 驗證它。

793. 將其複製到建置上下文中。793. 將其複製到建置上下文中。

80 80

81如果您的建置無法到達版本主機，請將版本鏡像到您的內部登錄中，並固定您的機隊執行的版本。81如果您的建置無法到達版本主機，請將版本鏡像到您的內部登錄中，並固定您的機隊執行的版本。

82 82

83除了二進位檔案，映像還需要：83除了二進位檔案，映像還需要：

84 84

85* **基於 glibc 的映像**：glibc 建置的唯一動態依賴項是 glibc 庫。基於 Musl 的映像需要 `linux-x64-musl` 或 `linux-arm64-musl` 建置加上額外套件；請參閱 [Alpine Linux 設定](/zh-TW/setup#alpine-linux-and-musl-based-distributions)。85* **基於 glibc 的映像**：glibc 建置的唯一動態依賴項是 glibc 庫。基於 Musl 的映像需要 `linux-x64-musl` 或 `linux-arm64-musl` 建置加上額外套件；請參閱 [Alpine Linux 設定](/docs/zh-TW/setup#alpine-linux-and-musl-based-distributions)。

86* **可寫入的狀態目錄**：閘道以任何使用者身份執行，但最小映像沒有可寫入的主目錄。將 `CLAUDE_CONFIG_DIR` 設定為可寫入的路徑，例如 `/tmp/.claude`。86* **可寫入的狀態目錄**：閘道以任何使用者身份執行，但最小映像沒有可寫入的主目錄。將 `CLAUDE_CONFIG_DIR` 設定為可寫入的路徑，例如 `/tmp/.claude`。

87* **容器命令**：`claude gateway --config /etc/claude/gateway.yaml`，配置檔案以唯讀方式掛載，祕密作為環境變數提供；閘道在 `listen.port` 上監聽，預設為 `8080`。87* **容器命令**：`claude gateway --config /etc/claude/gateway.yaml`，配置檔案以唯讀方式掛載，祕密作為環境變數提供；閘道在 `listen.port` 上監聽，預設為 `8080`。

88 88

99<Note>99<Note>

100 **工作負載身份**100 **工作負載身份**

101 101

102 優先選擇平台的工作負載身份而不是靜態金鑰：EKS 上的 IRSA 用於 Bedrock 和 AWS 上的 Claude Platform，GKE 上的工作負載身份用於 Agent Platform，以及 AKS 上的工作負載身份用於 Foundry。在上游區塊中設定 `auth: {}`，或對 Foundry 設定 `use_azure_ad: true`，閘道透過該提供者的預設認證鏈拾取 Pod 的身份。對於跨雲配對，例如 GKE 上的 Bedrock 上游，在上游的 `auth` 區塊中設定明確認證。[`upstreams` 參考](/zh-TW/claude-apps-gateway-config#upstreams) 有各平台設定詳情。102 優先選擇平台的工作負載身份而不是靜態金鑰：EKS 上的 IRSA 用於 Bedrock 和 AWS 上的 Claude Platform，GKE 上的工作負載身份用於 Agent Platform，以及 AKS 上的工作負載身份用於 Foundry。在上游區塊中設定 `auth: {}`，或對 Foundry 設定 `use_azure_ad: true`，閘道透過該提供者的預設認證鏈拾取 Pod 的身份。對於跨雲配對，例如 GKE 上的 Bedrock 上游，在上游的 `auth` 區塊中設定明確認證。[`upstreams` 參考](/docs/zh-TW/claude-apps-gateway-config#upstreams) 有各平台設定詳情。

103</Note>103</Note>

104 104

105<h3 id="cloud-run">105<h3 id="cloud-run">

109按如下方式配置服務：109按如下方式配置服務：

110 110

111* 將 `listen.port` 保留在預設值 `8080`，這與 Cloud Run 的預設 `PORT` 相符，或設定 `port: ${PORT}`111* 將 `listen.port` 保留在預設值 `8080`，這與 Cloud Run 的預設 `PORT` 相符，或設定 `port: ${PORT}`

112* 將 `public_url` 設定為外部可到達的來源。對於生產，這通常是內部負載平衡器的主機名，因為 `/login` [拒絕公開地址](/zh-TW/claude-apps-gateway#prerequisites)，而 `*.run.app` URL 解析為一個，所以單獨的 Cloud Run URL 僅適用於 `curl` 或瀏覽器煙霧測試。例外是一個網路，其中 `*.run.app` 透過 Private Service Connect 和 Cloud DNS 私有區域私下解析；在該拓撲中，Cloud Run URL 是有效的 `public_url`。[Google Cloud 實際工作範例](/zh-TW/claude-apps-gateway-on-gcp#deploy-the-gateway) 涵蓋兩者。112* 將 `public_url` 設定為外部可到達的來源。對於生產，這通常是內部負載平衡器的主機名，因為 `/login` [拒絕公開地址](/docs/zh-TW/claude-apps-gateway#prerequisites)，而 `*.run.app` URL 解析為一個，所以單獨的 Cloud Run URL 僅適用於 `curl` 或瀏覽器煙霧測試。例外是一個網路，其中 `*.run.app` 透過 Private Service Connect 和 Cloud DNS 私有區域私下解析；在該拓撲中，Cloud Run URL 是有效的 `public_url`。[Google Cloud 實際工作範例](/docs/zh-TW/claude-apps-gateway-on-gcp#deploy-the-gateway) 涵蓋兩者。

113* 將配置掛載為祕密卷113* 將配置掛載為祕密卷

114* 設定 `min-instances: 1` 以避免首次請求時的冷 OIDC 發現114* 設定 `min-instances: 1` 以避免首次請求時的冷 OIDC 發現

115 115

116<Note>116<Note>

117 如需 Google Cloud 上的完整實際工作範例，涵蓋 Cloud Run 或 GKE、Cloud SQL 和 Secret Manager，請參閱 [在 Google Cloud 上部署](/zh-TW/claude-apps-gateway-on-gcp)。117 如需 Google Cloud 上的完整實際工作範例，涵蓋 Cloud Run 或 GKE、Cloud SQL 和 Secret Manager，請參閱 [在 Google Cloud 上部署](/docs/zh-TW/claude-apps-gateway-on-gcp)。

118</Note>118</Note>

119 119

120<h3 id="push-the-gateway-url-to-developer-machines">120<h3 id="push-the-gateway-url-to-developer-machines">

121 將閘道 URL 推送到開發人員機器121 將閘道 URL 推送到開發人員機器

122</h3>122</h3>

123 123

124一旦閘道開始提供服務，透過受管設定、MDM 或直接寫入各個 OS `managed-settings.json` 將 `forceLoginMethod` 和 `forceLoginGatewayUrl` 推送到每個開發人員的機器。沒有這個，`/login` 顯示標準帳戶選擇器，沒有閘道選項。請參閱 [用戶端受管設定](/zh-TW/claude-apps-gateway-config#client-side-managed-settings) 以取得檔案路徑。124一旦閘道開始提供服務，透過受管設定、MDM 或直接寫入各個 OS `managed-settings.json` 將 `forceLoginMethod` 和 `forceLoginGatewayUrl` 推送到每個開發人員的機器。沒有這個，`/login` 顯示標準帳戶選擇器，沒有閘道選項。請參閱 [用戶端受管設定](/docs/zh-TW/claude-apps-gateway-config#client-side-managed-settings) 以取得檔案路徑。

125 125

126<h2 id="operations">126<h2 id="operations">

127 運營127 運營

160 160

161* **現有會話**：持有人令牌使用 JWT 祕密在本地驗證，會話重新整理不接觸存儲，閘道程序仍然可以提供推理161* **現有會話**：持有人令牌使用 JWT 祕密在本地驗證，會話重新整理不接觸存儲，閘道程序仍然可以提供推理

162* **新簽入**：失敗直到 Postgres 恢復，因為設備流及其速率限制計數器存在於 Postgres 中162* **新簽入**：失敗直到 Postgres 恢復，因為設備流及其速率限制計數器存在於 Postgres 中

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

164* **就緒**：`/readyz` 在中斷期間報告未就緒，因此在就緒上閘門流量的協調器一次從輪換中移除每個副本。在該拓撲中，所有流量，包括閘道仍然可以提供的推理，在負載平衡器處失敗，直到 Postgres 恢復。`/healthz` 上的活躍探針保持通過，因此副本不會重新啟動。如果您寧願已簽入的開發人員在存儲中斷期間保持工作，請將就緒探針指向 `/healthz`；成本是新簽入失敗對仍然報告就緒的副本。164* **就緒**：`/readyz` 在中斷期間報告未就緒，因此在就緒上閘門流量的協調器一次從輪換中移除每個副本。在該拓撲中，所有流量，包括閘道仍然可以提供的推理，在負載平衡器處失敗，直到 Postgres 恢復。`/healthz` 上的活躍探針保持通過，因此副本不會重新啟動。如果您寧願已簽入的開發人員在存儲中斷期間保持工作，請將就緒探針指向 `/healthz`；成本是新簽入失敗對仍然報告就緒的副本。

165 165

166如果您的 IdP 宕機，現有會話工作直到 `ttl_hours`，新登入和重新整理失敗。如果您的 IdP 有頻繁的維護窗口，設定更長的 `ttl_hours`。166如果您的 IdP 宕機，現有會話工作直到 `ttl_hours`，新登入和重新整理失敗。如果您的 IdP 有頻繁的維護窗口，設定更長的 `ttl_hours`。

193 193

19430 秒迴圈過期 `kv` 行超過其 TTL，每小時掃描在支出表上強制保留窗口，因此沒有任何東西無限增長。沒有 [支出限制](/zh-TW/claude-apps-gateway-spend-limits) 配置，只有 `kv` 被寫入。如果您的安全原則禁止應用程式角色的 DDL，預先建立這些表和 `_migrations`，使用管理員角色，並授予應用程式角色 `SELECT, INSERT, UPDATE, DELETE` 在每個上。19430 秒迴圈過期 `kv` 行超過其 TTL，每小時掃描在支出表上強制保留窗口，因此沒有任何東西無限增長。沒有 [支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits) 配置，只有 `kv` 被寫入。如果您的安全原則禁止應用程式角色的 DDL，預先建立這些表和 `_migrations`，使用管理員角色，並授予應用程式角色 `SELECT, INSERT, UPDATE, DELETE` 在每個上。

195 195

196使用支出限制，丟失的資料庫意味著丟失支出追蹤和上限，不僅僅是開發人員重新登入，因此執行定期備份。要立即清除一個已離職的開發人員，而不是等待保留，直接執行 `DELETE FROM principal_emails WHERE principal = '<sub>'`；這移除唯一持有其電子郵件、名稱和群組的表。`spend` 和 `admin_audit` 行僅參考偽匿名 OIDC `sub`。196使用支出限制，丟失的資料庫意味著丟失支出追蹤和上限，不僅僅是開發人員重新登入，因此執行定期備份。要立即清除一個已離職的開發人員，而不是等待保留，直接執行 `DELETE FROM principal_emails WHERE principal = '<sub>'`；這移除唯一持有其電子郵件、名稱和群組的表。`spend` 和 `admin_audit` 行僅參考偽匿名 OIDC `sub`。

197 197

218| 資料 | 路徑 | 由閘道發送給 Anthropic |218| 資料 | 路徑 | 由閘道發送給 Anthropic |

219| ----------------------------------------------------------------------- | -------------------------------------- | ------------------------- |219| ----------------------------------------------------------------------- | -------------------------------------- | ------------------------- |

221| 遙測（OTLP 指標，加上 [選擇加入日誌和追蹤](/zh-TW/claude-apps-gateway-config#telemetry)） | CLI → 閘道 → 您的收集器 | 從不 |221| 遙測（OTLP 指標，加上 [選擇加入日誌和追蹤](/docs/zh-TW/claude-apps-gateway-config#telemetry)） | CLI → 閘道 → 您的收集器 | 從不 |

222| 身份（電子郵件、群組、sub） | IdP → 閘道 → JWT → CLI；CLI 在 OTLP 匯出上標記它 | 從不 |222| 身份（電子郵件、群組、sub） | IdP → 閘道 → JWT → CLI；CLI 在 OTLP 匯出上標記它 | 從不 |

223| 受管設定 | 您的閘道 YAML → CLI | 從不 |223| 受管設定 | 您的閘道 YAML → CLI | 從不 |

224| 審計日誌 | 閘道 stderr → 您的聚合器 | 從不 |224| 審計日誌 | 閘道 stderr → 您的聚合器 | 從不 |

237 237

238兩個威脅超出範圍，因為它們是您的基礎設施要保護的：238兩個威脅超出範圍，因為它們是您的基礎設施要保護的：

239 239

240* **受損的閘道主機**：主機既持有上游認證，又向每個連接的開發人員分發 [受管設定](/zh-TW/claude-apps-gateway-config#managed)，因此對閘道配置的控制與對您的 MDM 的控制相當。CLI 的一次性批准對話框用於殼層功能設定限制無聲變更，但不替代主機安全。240* **受損的閘道主機**：主機既持有上游認證，又向每個連接的開發人員分發 [受管設定](/docs/zh-TW/claude-apps-gateway-config#managed)，因此對閘道配置的控制與對您的 MDM 的控制相當。CLI 的一次性批准對話框用於殼層功能設定限制無聲變更，但不替代主機安全。

241* **惡意 OIDC 提供者**：提供者簽署閘道信任的 id\_token，因此它可以聲稱任何身份。審查和保護您的 IdP 是您的責任。241* **惡意 OIDC 提供者**：提供者簽署閘道信任的 id\_token，因此它可以聲稱任何身份。審查和保護您的 IdP 是您的責任。

242 242

243<h3 id="user-code-brute-force-resistance">243<h3 id="user-code-brute-force-resistance">

246 246

247開發人員在 `/device` 驗證頁面中輸入的 `user_code` 是從 20 字元字母表中抽取的 8 個字元，產生 20⁸ 或約 2.56×10¹⁰ 個組合，並在 10 分鐘後過期。247開發人員在 `/device` 驗證頁面中輸入的 `user_code` 是從 20 字元字母表中抽取的 8 個字元，產生 20⁸ 或約 2.56×10¹⁰ 個組合，並在 10 分鐘後過期。

248 248

249閘道在設備授予端點上應用按 IP 速率限制，可透過 [`rate_limits`](/zh-TW/claude-apps-gateway-config#http-tuning) 配置。如果許多開發人員從單一共享公司 NAT 地址簽入，請提高限制。限制僅適用於簽入流程，不適用於推理。249閘道在設備授予端點上應用按 IP 速率限制，可透過 [`rate_limits`](/docs/zh-TW/claude-apps-gateway-config#http-tuning) 配置。如果許多開發人員從單一共享公司 NAT 地址簽入，請提高限制。限制僅適用於簽入流程，不適用於推理。

250 250

251<h3 id="compliance-posture">251<h3 id="compliance-posture">

252 合規性態勢252 合規性態勢

255* **資料駐留**：閘道自己的資料平面不向 Anthropic 發送任何東西，除非 Anthropic API 是配置的上游；當它是時，您現有的資料處理協議適用於推理路徑。遙測、審計、身份和設定只流向您配置的目的地。255* **資料駐留**：閘道自己的資料平面不向 Anthropic 發送任何東西，除非 Anthropic API 是配置的上游；當它是時，您現有的資料處理協議適用於推理路徑。遙測、審計、身份和設定只流向您配置的目的地。

256* **主機程序流量**：主機程序是 Claude Code CLI，可以向 Anthropic 發送啟動分析和更新檢查。對於嚴格出口部署，在閘道的容器環境中設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`。256* **主機程序流量**：主機程序是 Claude Code CLI，可以向 Anthropic 發送啟動分析和更新檢查。對於嚴格出口部署，在閘道的容器環境中設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`。

257* **用戶端分析**：CLI 在簽入到閘道時停用自己的使用分析，錯誤報告在第三方 API 表面上預設關閉。257* **用戶端分析**：CLI 在簽入到閘道時停用自己的使用分析，錯誤報告在第三方 API 表面上預設關閉。

258* **用戶端機器**：開發人員的 CLI 仍然向 Anthropic 發送 WebFetch 主機名檢查和版本檢查，除非設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` 和 `skipWebFetchPreflight: true`。請參閱 [資料使用](/zh-TW/data-usage)。258* **用戶端機器**：開發人員的 CLI 仍然向 Anthropic 發送 WebFetch 主機名檢查和版本檢查，除非設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` 和 `skipWebFetchPreflight: true`。請參閱 [資料使用](/docs/zh-TW/data-usage)。

259* **調查評分**：閘道認證停用 Anthropic 綁定評分接收器，因此評分不發送給 Anthropic。259* **調查評分**：閘道認證停用 Anthropic 綁定評分接收器，因此評分不發送給 Anthropic。

260* **記錄單共享**：在調查的記錄單共享提示上選擇「是」會在 `~/.claude/feedback-bundles/` 下寫入本地檔案，而不是上傳到 Anthropic。260* **記錄單共享**：在調查的記錄單共享提示上選擇「是」會在 `~/.claude/feedback-bundles/` 下寫入本地檔案，而不是上傳到 Anthropic。

261* **用戶端更新**：更新檢查與閘道流量分開。透過您自己的分發固定版本，如果筆記型電腦不得提取版本，設定 `DISABLE_UPDATES`。`DISABLE_AUTOUPDATER` 只停止背景更新，而 `claude update` 仍然有效。261* **用戶端更新**：更新檢查與閘道流量分開。透過您自己的分發固定版本，如果筆記型電腦不得提取版本，設定 `DISABLE_UPDATES`。`DISABLE_AUTOUPDATER` 只停止背景更新，而 `claude update` 仍然有效。

262* **TLS**：在生產中透過 HTTPS 提供 `public_url`，要麼從閘道自己的監聽器透過 `listen.tls`，要麼從 TLS 終止 ingress 在純 HTTP 副本前面，設定 `listen.public_url`。閘道不拒絕純 HTTP。IdP 必須在生產中提供 HTTPS，Postgres 支援 `?sslmode=require`。在您的 ingress 設定 `Strict-Transport-Security`。262* **TLS**：在生產中透過 HTTPS 提供 `public_url`，要麼從閘道自己的監聽器透過 `listen.tls`，要麼從 TLS 終止 ingress 在純 HTTP 副本前面，設定 `listen.public_url`。閘道不拒絕純 HTTP。IdP 必須在生產中提供 HTTPS，Postgres 支援 `?sslmode=require`。在您的 ingress 設定 `Strict-Transport-Security`。

263* **漏洞披露**：遵循 [報告安全問題](/zh-TW/security#reporting-security-issues)263* **漏洞披露**：遵循 [報告安全問題](/docs/zh-TW/security#reporting-security-issues)

264 264

265<h2 id="troubleshooting">265<h2 id="troubleshooting">

266 故障排除266 故障排除

272* **登入問題**：開發人員執行 `claude --debug-file ./claude-debug.txt`、重現，並發送該檔案加上相同窗口的閘道審計日誌272* **登入問題**：開發人員執行 `claude --debug-file ./claude-debug.txt`、重現，並發送該檔案加上相同窗口的閘道審計日誌

273* **推理問題**：請求的模型、配置的上游，以及請求的閘道審計日誌，記錄哪個上游提供了它以及回應狀態273* **推理問題**：請求的模型、配置的上游，以及請求的閘道審計日誌，記錄哪個上游提供了它以及回應狀態

274 274

275閘道的 stderr 包含審計事件串流，審計日誌記錄開發人員身分，除錯檔案記錄來自開發人員機器的 hook 和 MCP 伺服器輸出。在發佈到公開議題之前，請檢查並隱蔽這些資訊。

276

275| 症狀 | 原因 | 修復 |277| 症狀 | 原因 | 修復 |

276| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |278| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

277| 開發人員的 `/login` 顯示標準帳戶選擇器而不是 **Cloud 閘道** 螢幕 | `forceLoginMethod` 或 `forceLoginGatewayUrl` 未在該機器上的受管設定中設定 | 將 [受管設定檔案](/zh-TW/claude-apps-gateway#set-the-gateway-url) 部署到設備；`/login` 從那裡讀取閘道 URL |279| 開發人員的 `/login` 顯示標準帳戶選擇器而不是 **Cloud 閘道** 螢幕 | `forceLoginMethod` 或 `forceLoginGatewayUrl` 未在該機器上的受管設定中設定 | 將 [受管設定檔案](/docs/zh-TW/claude-apps-gateway#set-the-gateway-url) 部署到設備；`/login` 從那裡讀取閘道 URL |

278| 啟動顯示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 已安裝的 Claude Code 建置早於閘道支援 | 讓開發人員更新 Claude Code 到包含 Cloud 閘道支援的版本 |280| 啟動顯示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 已安裝的 Claude Code 建置早於閘道支援 | 讓開發人員更新 Claude Code 到包含 Cloud 閘道支援的版本 |

279| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 閘道主機名解析為至少一個公開 IP 地址。Claude Code 檢查每個解析的地址，並要求每個都是私有的。常見原因是雙堆棧名稱，其中一個系列解析為公開地址，包括 AWS 內部雙堆棧負載平衡器，它們傳回公開範圍 AAAA 地址。Anthropic 營運的公開閘道端點豁免於檢查，`/login` 透過 `https://` 接受它們。在 v2.1.206 之前，`/login` 拒絕它們，就像任何其他公開地址一樣 | 讓閘道名稱在開發人員機器上只解析為私有地址。對於雙堆棧名稱，刪除公開範圍記錄或提供單獨的僅內部 DNS 名稱。請參閱 [私有網路先決條件](/zh-TW/claude-apps-gateway#prerequisites)。 |281| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 閘道主機名解析為至少一個公開 IP 地址。Claude Code 檢查每個解析的地址，並要求每個都是私有的。常見原因是雙堆棧名稱，其中一個系列解析為公開地址，包括 AWS 內部雙堆棧負載平衡器，它們傳回公開範圍 AAAA 地址。Anthropic 營運的公開閘道端點豁免於檢查，`/login` 透過 `https://` 接受它們。在 v2.1.206 之前，`/login` 拒絕它們，就像任何其他公開地址一樣 | 讓閘道名稱在開發人員機器上只解析為私有地址。對於雙堆棧名稱，刪除公開範圍記錄或提供單獨的僅內部 DNS 名稱。請參閱 [私有網路先決條件](/docs/zh-TW/claude-apps-gateway#prerequisites)。 |

280| CLI `/login`：`Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於閘道主機，代理的主機名解析為公開地址。代理的主機解析為僅私有地址是允許的，不會觸發此錯誤 | 在開發人員的機器上將閘道主機新增到 `NO_PROXY`，以便連接是直接的，或使用主機名解析為私有地址的代理 |282| CLI `/login`：`Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於閘道主機，代理的主機名解析為公開地址。代理的主機解析為僅私有地址是允許的，不會觸發此錯誤 | 在開發人員的機器上將閘道主機新增到 `NO_PROXY`，以便連接是直接的，或使用主機名解析為私有地址的代理 |

282| 啟動退出，配置驗證錯誤命名 `store.postgres_url` | 未配置 Postgres；閘道需要 Postgres | 設定 `store.postgres_url`。對於本地開發，使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |284| 啟動退出，配置驗證錯誤命名 `store.postgres_url` | 未配置 Postgres；閘道需要 Postgres | 設定 `store.postgres_url`。對於本地開發，使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |

286| `/oauth/callback` 顯示「Sign-in could not be completed」 | 電子郵件網域被拒絕、id\_token 驗證失敗，或 `email_verified` 明確為 `false`，閘道始終拒絕，沒有覆蓋 | 檢查 `allowed_email_domains` 以及 IdP 是否傳回驗證的 `email` 聲明。對於 `email_verified: false`，修復 IdP 端驗證。如果您的 IdP 在不同的聲明名稱下發出電子郵件，設定 `oidc.email_claim`。 |288| `/oauth/callback` 顯示「Sign-in could not be completed」 | 電子郵件網域被拒絕、id\_token 驗證失敗，或 `email_verified` 明確為 `false`，閘道始終拒絕，沒有覆蓋 | 檢查 `allowed_email_domains` 以及 IdP 是否傳回驗證的 `email` 聲明。對於 `email_verified: false`，修復 IdP 端驗證。如果您的 IdP 在不同的聲明名稱下發出電子郵件，設定 `oidc.email_claim`。 |

293| 簽入在 IdP 完成但回調失敗，Chrome 中出現 CSP 錯誤或 Safari 中出現「this sign-in link has expired」 | IdP 透過 `response_mode=form_post` 傳回代碼，它透過 POST 自動提交到 `/oauth/callback`。Chrome 在嚴格 CSP 下阻止它；Safari 允許提交但回調只讀取查詢字串。 | 確保您的 IdP 遵守 `response_mode=query`，閘道明確請求它，以便回調是純重新導向 |295| 簽入在 IdP 完成但回調失敗，Chrome 中出現 CSP 錯誤或 Safari 中出現「this sign-in link has expired」 | IdP 透過 `response_mode=form_post` 傳回代碼，它透過 POST 自動提交到 `/oauth/callback`。Chrome 在嚴格 CSP 下阻止它；Safari 允許提交但回調只讀取查詢字串。 | 確保您的 IdP 遵守 `response_mode=query`，閘道明確請求它，以便回調是純重新導向 |

296| CLI `/login`：「Could not verify the gateway's TLS certificate」或 `SELF_SIGNED_CERT_IN_CHAIN` | 閘道的 TLS 鏈由 CLI 主機的信任存儲中不存在的私有 CA 簽署 | Claude Code 預設在原生二進位檔案上讀取 OS 信任存儲，在 Node 22.15 或更新版本上；[`CLAUDE_CODE_CERT_STORE`](/zh-TW/network-config#ca-certificate-store) 控制此行為。如果 CA 安裝在 OS 信任存儲中，確保開發人員在當前執行時上。否則在啟動前將 `NODE_EXTRA_CA_CERTS` 設定為 CA 憑證 PEM。首次連接指紋提示仍然適用。 |298| CLI `/login`：「Could not verify the gateway's TLS certificate」或 `SELF_SIGNED_CERT_IN_CHAIN` | 閘道的 TLS 鏈由 CLI 主機的信任存儲中不存在的私有 CA 簽署 | Claude Code 預設在原生二進位檔案上讀取 OS 信任存儲，在 Node 22.15 或更新版本上；[`CLAUDE_CODE_CERT_STORE`](/docs/zh-TW/network-config#ca-certificate-store) 控制此行為。如果 CA 安裝在 OS 信任存儲中，確保開發人員在當前執行時上。否則在啟動前將 `NODE_EXTRA_CA_CERTS` 設定為 CA 憑證 PEM。首次連接指紋提示仍然適用。 |

297 299

298<h2 id="related">300<h2 id="related">

299 相關301 相關

300</h2>302</h2>

301 303

302* [Claude 應用程式閘道概述](/zh-TW/claude-apps-gateway)：快速入門和開發人員連接304* [Claude 應用程式閘道概述](/docs/zh-TW/claude-apps-gateway)：快速入門和開發人員連接

303* [設定參考](/zh-TW/claude-apps-gateway-config)：每個 `gateway.yaml` 選項305* [設定參考](/docs/zh-TW/claude-apps-gateway-config)：每個 `gateway.yaml` 選項

commands.md +78 −78

Details

10 10

11輸入 `/` 以查看所有可用命令，或輸入 `/` 後跟字母以篩選。11輸入 `/` 以查看所有可用命令，或輸入 `/` 後跟字母以篩選。

12 12

13命令只有在您的訊息開始時才會被識別。命令名稱後面的文字會作為引數傳遞給它。{/* min-version: 2.1.199 */}自 v2.1.199 起，[skills](/zh-TW/skills#pass-arguments-to-skills) 是例外：skill 調用後跟更多 skills，例如 `/skill-a /skill-b do XYZ`，會載入開始時命名的每個 skill，並將尾部文字作為引數傳遞給每個 skill。最多可以鏈接六個 skills。13命令只有在您的訊息開始時才會被識別。命令名稱後面的文字會作為引數傳遞給它。{/* min-version: 2.1.199 */}自 v2.1.199 起，[skills](/docs/zh-TW/skills#pass-arguments-to-skills) 是例外：skill 調用後跟更多 skills，例如 `/skill-a /skill-b do XYZ`，會載入開始時命名的每個 skill，並將尾部文字作為引數傳遞給每個 skill。最多可以鏈接六個 skills。

14 14

15如果您在 Claude 正在回應時發送命令，它會排隊並在目前回合完成後執行。某些命令，例如 `/status`、`/tasks` 和 `/usage`，會立即執行而不會中斷回應。15如果您在 Claude 正在回應時發送命令，它會排隊並在目前回合完成後執行。某些命令，例如 `/status`、`/tasks` 和 `/usage`，會立即執行而不會中斷回應。

16 16

20 20

21大多數命令在工作階段的特定時刻很有用，從設定專案到推送變更。21大多數命令在工作階段的特定時刻很有用，從設定專案到推送變更。

22 22

23**存放庫中的首次工作階段。** 執行 `/init` 以產生啟動程式 `CLAUDE.md`，然後執行 `/memory` 以精煉它。使用 `/mcp` 以設定專案需要的任何伺服器，要求 Claude 建立您想要的任何 [subagents](/zh-TW/sub-agents)，並執行 `/permissions` 以設定您的批准規則。23**存放庫中的首次工作階段。** 執行 `/init` 以產生啟動程式 `CLAUDE.md`，然後執行 `/memory` 以精煉它。使用 `/mcp` 以設定專案需要的任何伺服器，要求 Claude 建立您想要的任何 [subagents](/docs/zh-TW/sub-agents)，並執行 `/permissions` 以設定您的批准規則。

24 24

25**在工作期間。** `/plan` 在大型變更前切換到 Plan Mode。`/model` 和 `/effort` 調整您使用的模型以及它應用多少推理。當對話變得冗長時，`/context` 顯示視窗中填充的內容，`/compact` 將其總結以釋放空間。使用 `/btw` 進行快速旁註，不應該加入對話歷史記錄。25**在工作期間。** `/plan` 在大型變更前切換到 Plan Mode。`/model` 和 `/effort` 調整您使用的模型以及它應用多少推理。當對話變得冗長時，`/context` 顯示視窗中填充的內容，`/compact` 將其總結以釋放空間。使用 `/btw` 進行快速旁註，不應該加入對話歷史記錄。

26 26

27**並行執行工作。** Claude 委派側邊任務給 [subagents](/zh-TW/sub-agents)，`/tasks` 列出目前工作階段的背景工作，包括已完成的 subagents。`/background` 分離整個工作階段以繼續作為 [background agent](/zh-TW/agent-view) 執行並釋放您的終端機。對於跨越程式碼庫的大型變更，`/batch` 將其分解為獨立單位，並在各自的 [worktree](/zh-TW/worktrees) 中執行每個單位。請參閱 [Run agents in parallel](/zh-TW/agents) 以了解這些方法如何相關。27**並行執行工作。** Claude 委派側邊任務給 [subagents](/docs/zh-TW/sub-agents)，`/tasks` 列出目前工作階段的背景工作，包括已完成的 subagents。`/background` 分離整個工作階段以繼續作為 [background agent](/docs/zh-TW/agent-view) 執行並釋放您的終端機。對於跨越程式碼庫的大型變更，`/batch` 將其分解為獨立單位，並在各自的 [worktree](/docs/zh-TW/worktrees) 中執行每個單位。請參閱 [Run agents in parallel](/docs/zh-TW/agents) 以了解這些方法如何相關。

28 28

29**在您推送前。** `/diff` 顯示變更的內容，`/code-review` 檢查差異以找出正確性錯誤和清理，並可以使用 `--fix` 應用發現的結果，`/review` 在 GitHub pull request 上執行快速單次通過的唯讀審查，`/code-review <level> <pr#>` 執行其中一個的多代理審查，`/security-review` 檢查差異以找出安全性漏洞。`/code-review ultra` 在雲端執行多代理審查。29**在您推送前。** `/diff` 顯示變更的內容，`/code-review` 檢查差異以找出正確性錯誤和清理，並可以使用 `--fix` 應用發現的結果，`/review` 在 GitHub pull request 上執行快速單次通過的唯讀審查，`/code-review <level> <pr#>` 執行其中一個的多代理審查，`/security-review` 檢查差異以找出安全性漏洞。`/code-review ultra` 在雲端執行多代理審查。

30 30

38 38

39下表列出了 Claude Code 中包含的所有命令。大多數是內建命令，其行為被編碼到 CLI 中。有兩種項目被標記：39下表列出了 Claude Code 中包含的所有命令。大多數是內建命令，其行為被編碼到 CLI 中。有兩種項目被標記：

40 40

41* **[Skill](/zh-TW/skills#bundled-skills)**：一個捆綁的 skill。它的工作方式與您自己編寫的 skills 相同：一個提示交給 Claude，Claude 也可以在相關時自動調用。41* **[Skill](/docs/zh-TW/skills#bundled-skills)**：一個捆綁的 skill。它的工作方式與您自己編寫的 skills 相同：一個提示交給 Claude，Claude 也可以在相關時自動調用。

~~42* **[Workflow](/zh-TW/workflows#bundled-workflows)**：一個捆綁的[動態工作流](/zh-TW/workflows)，在許多 subagents 之間展開工作並在背景中運行。~~42* **[Workflow](/docs/zh-TW/workflows#bundled-workflows)**：一個捆綁的[動態工作流](/docs/zh-TW/workflows)，在許多 subagents 之間展開工作並在背景中運行。

43 43

~~44若要添加您自己的命令，請參閱 [skills](/zh-TW/skills)。~~44若要添加您自己的命令，請參閱 [skills](/docs/zh-TW/skills)。

45 45

46在下表中，`<arg>` 表示必需的引數，`[arg]` 表示可選的引數。46在下表中，`<arg>` 表示必需的引數，`[arg]` 表示可選的引數。

47 47

51 51

52| 命令 | 用途 |52| 命令 | 用途 |

53| :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |53| :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

54| `/add-dir <path>` | 為目前工作階段期間的檔案存取添加工作目錄。輸入部分路徑會顯示匹配的目錄建議；按 `Tab` 以接受一個。大多數 `.claude/` 配置[未從添加的目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍後使用 `--continue` 或 `--resume` 從添加的目錄繼續工作階段 |54| `/add-dir <path>` | 為目前工作階段期間的檔案存取添加工作目錄。輸入部分路徑會顯示匹配的目錄建議；按 `Tab` 以接受一個。大多數 `.claude/` 配置[未從添加的目錄發現](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍後使用 `--continue` 或 `--resume` 從添加的目錄繼續工作階段 |

55| `/advisor [model\|off]` | 啟用或停用[顧問工具](/zh-TW/advisor)，它在工作期間的關鍵時刻諮詢第二個模型以獲得指導。接受 `opus`、`sonnet`、`fable`（{/* min-version: 2.1.170 */}v2.1.170+）或完整的模型 ID。不帶引數時，開啟選擇器 |55| `/advisor [model\|off]` | 啟用或停用[顧問工具](/docs/zh-TW/advisor)，它在工作期間的關鍵時刻諮詢第二個模型以獲得指導。接受 `opus`、`sonnet`、`fable`（{/* min-version: 2.1.170 */}v2.1.170+）或完整的模型 ID。不帶引數時，開啟選擇器 |

56| `/agents` | {/* min-version: 2.1.198 */}自 v2.1.198 起，執行 `/agents` 會列印提醒，要求您詢問 Claude 以建立或管理 [subagents](/zh-TW/sub-agents)，或直接編輯 `.claude/agents/` 或 `~/.claude/agents/`。{/* max-version: 2.1.197 */}在 v2.1.197 及更早版本上，開啟互動式介面以建立和管理 subagent 配置 |56| `/agents` | {/* min-version: 2.1.198 */}自 v2.1.198 起，執行 `/agents` 會列印提醒，要求您詢問 Claude 以建立或管理 [subagents](/docs/zh-TW/sub-agents)，或直接編輯 `.claude/agents/` 或 `~/.claude/agents/`。{/* max-version: 2.1.197 */}在 v2.1.197 及更早版本上，開啟互動式介面以建立和管理 subagent 配置 |

57| `/autofix-pr [prompt]` | 生成一個[網頁上的 Claude Code](/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 和訪問[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web) |57| `/autofix-pr [prompt]` | 生成一個[網頁上的 Claude Code](/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 和訪問[網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) |

58| `/background [prompt]` | 分離目前的工作階段以作為[背景 agent](/zh-TW/agent-view) 運行並釋放此終端機。傳遞提示以在分離前發送一個額外的指示。使用 `claude agents` 監視工作階段。別名：`/bg` |58| `/background [prompt]` | 分離目前的工作階段以作為[背景 agent](/docs/zh-TW/agent-view) 運行並釋放此終端機。傳遞提示以在分離前發送一個額外的指示。使用 `claude agents` 監視工作階段。別名：`/bg` |

59| `/batch <instruction>` | **[Skill](/zh-TW/skills#bundled-skills).** 在整個程式碼庫中並行協調大規模變更。研究程式碼庫，將工作分解為 5 到 30 個獨立單位，並呈現計劃。獲得批准後，在隔離的 [git worktree](/zh-TW/worktrees) 中為每個單位生成一個背景 subagent。每個 subagent 實現其單位、運行測試並開啟 pull request。需要 git 存放庫。示例：`/batch migrate src/ from Solid to React` |59| `/batch <instruction>` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 在整個程式碼庫中並行協調大規模變更。研究程式碼庫，將工作分解為 5 到 30 個獨立單位，並呈現計劃。獲得批准後，在隔離的 [git worktree](/docs/zh-TW/worktrees) 中為每個單位生成一個背景 subagent。每個 subagent 實現其單位、運行測試並開啟 pull request。需要 git 存放庫。示例：`/batch migrate src/ from Solid to React` |

60| `/branch [name]` | 在此時刻建立目前對話的分支，以便您可以嘗試不同的方向而不會失去目前的對話。切換到分支並保留原始分支，您可以使用 `/resume` 返回。若要將側邊工作交給背景 subagent 而不是自己切換到副本，請使用 `/fork` |60| `/branch [name]` | 在此時刻建立目前對話的分支，以便您可以嘗試不同的方向而不會失去目前的對話。切換到分支並保留原始分支，您可以使用 `/resume` 返回。若要將側邊工作交給背景 subagent 而不是自己切換到副本，請使用 `/fork` |

62| `/cd <path>` | {/* min-version: 2.1.169 */}將此工作階段移動到新的工作目錄。對話的提示快取被保留：新目錄的 [`CLAUDE.md`](/zh-TW/memory) 被附加為訊息，而不是重建系統提示。工作階段被重新定位到新目錄的專案儲存，因此 `--resume` 和 `--continue` 從那裡找到它。如果您之前未在該目錄中工作過，會提示您信任該目錄。{/* min-version: 2.1.206 */}輸入部分路徑會顯示匹配的目錄建議；按 `Tab` 以接受一個。建議需要 Claude Code v2.1.206 或更新版本。若要授予對額外目錄的存取權而不移動工作階段，請使用 `/add-dir`。使用 [`Cd` 權限規則](/zh-TW/permissions#cd)限制或停用 `/cd` 目標。需要 Claude Code v2.1.169 或更新版本；較早的版本報告 `Unknown command: /cd` |62| `/cd <path>` | {/* min-version: 2.1.169 */}將此工作階段移動到新的工作目錄。對話的提示快取被保留：新目錄的 [`CLAUDE.md`](/docs/zh-TW/memory) 被附加為訊息，而不是重建系統提示。工作階段被重新定位到新目錄的專案儲存，因此 `--resume` 和 `--continue` 從那裡找到它。如果您之前未在該目錄中工作過，會提示您信任該目錄。{/* min-version: 2.1.206 */}輸入部分路徑會顯示匹配的目錄建議；按 `Tab` 以接受一個。建議需要 Claude Code v2.1.206 或更新版本。若要授予對額外目錄的存取權而不移動工作階段，請使用 `/add-dir`。使用 [`Cd` 權限規則](/docs/zh-TW/permissions#cd)限制或停用 `/cd` 目標。需要 Claude Code v2.1.169 或更新版本；較早的版本報告 `Unknown command: /cd` |

64| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/zh-TW/skills#bundled-skills).** 為您的專案語言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 參考加載 Claude API 參考資料。涵蓋工具使用、串流、批次、結構化輸出和常見陷阱。當您的程式碼導入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動激活。執行 `/claude-api migrate` 以將現有 Claude API 程式碼升級到較新的模型：Claude 詢問要掃描哪些檔案以及要針對哪個模型，然後更新在版本之間變更的模型 ID、thinking 配置和其他參數。執行 `/claude-api managed-agents-onboard` 以進行互動式逐步解說，從頭開始建立新的 Managed Agent |64| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 為您的專案語言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 參考加載 Claude API 參考資料。涵蓋工具使用、串流、批次、結構化輸出和常見陷阱。當您的程式碼導入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動激活。執行 `/claude-api migrate` 以將現有 Claude API 程式碼升級到較新的模型：Claude 詢問要掃描哪些檔案以及要針對哪個模型，然後更新在版本之間變更的模型 ID、thinking 配置和其他參數。執行 `/claude-api managed-agents-onboard` 以進行互動式逐步解說，從頭開始建立新的 Managed Agent |

65| `/clear [name]` | 使用空上下文開始新對話。傳遞名稱以在 `/resume` 選擇器中標記上一個對話。若要在繼續同一對話時釋放上下文，請改用 `/compact`。使用 `/resume` 繼續上一個對話，或在同一個 Claude Code 程序中，{/* min-version: 2.1.191 */}從[倒帶選單的上一個工作階段項目](/zh-TW/checkpointing#rewind-past-a-cleared-conversation)恢復它。別名：`/reset`、`/new` |65| `/clear [name]` | 使用空上下文開始新對話。傳遞名稱以在 `/resume` 選擇器中標記上一個對話。若要在繼續同一對話時釋放上下文，請改用 `/compact`。使用 `/resume` 繼續上一個對話，或在同一個 Claude Code 程序中，{/* min-version: 2.1.191 */}從[倒帶選單的上一個工作階段項目](/docs/zh-TW/checkpointing#rewind-past-a-cleared-conversation)恢復它。別名：`/reset`、`/new` |

66| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/zh-TW/skills#bundled-skills).** 審閱目前的差異以查找正確性錯誤並進行重用、簡化和效率清理。傳遞 `--fix` 以將發現應用到您的工作樹，傳遞 `--comment` 以將其作為內聯 GitHub PR 評論發佈，或傳遞 `ultra` 以運行深度[雲端審閱](/zh-TW/ultrareview)。{/* min-version: 2.1.154 */}從 v2.1.154 開始，`/simplify` 運行單獨的僅清理審閱，應用修復而不尋找錯誤。請參閱[本地審閱差異](/zh-TW/code-review#review-a-diff-locally)以了解努力程度和目標設定 |66| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 審閱目前的差異以查找正確性錯誤並進行重用、簡化和效率清理。傳遞 `--fix` 以將發現應用到您的工作樹，傳遞 `--comment` 以將其作為內聯 GitHub PR 評論發佈，或傳遞 `ultra` 以運行深度[雲端審閱](/docs/zh-TW/ultrareview)。{/* min-version: 2.1.154 */}從 v2.1.154 開始，`/simplify` 運行單獨的僅清理審閱，應用修復而不尋找錯誤。請參閱[本地審閱差異](/docs/zh-TW/code-review#review-a-diff-locally)以了解努力程度和目標設定 |

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

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

69| `/config [key=value ...]` | 開啟[設定](/zh-TW/settings)介面以調整主題、模型、[輸出樣式](/zh-TW/output-styles)和其他偏好設定。{/* min-version: 2.1.181 */}從 v2.1.181 開始，傳遞一個或多個 `key=value` 對以直接設定設定，無需開啟介面，例如 `/config thinking=false`。{/* min-version: 2.1.182 */}從 v2.1.182 開始，也接受命名的簡寫鍵，例如 `/config theme=dark` 或 `/config model=sonnet`。`key=value` 形式也適用於非互動模式（`-p`）和[遠端控制](/zh-TW/remote-control)。執行 `/config --help` 以列出每個可設定的鍵及其選項。別名：`/settings` |69| `/config [key=value ...]` | 開啟[設定](/docs/zh-TW/settings)介面以調整主題、模型、[輸出樣式](/docs/zh-TW/output-styles)和其他偏好設定。{/* min-version: 2.1.181 */}從 v2.1.181 開始，傳遞一個或多個 `key=value` 對以直接設定設定，無需開啟介面，例如 `/config thinking=false`。{/* min-version: 2.1.182 */}從 v2.1.182 開始，也接受命名的簡寫鍵，例如 `/config theme=dark` 或 `/config model=sonnet`。`key=value` 形式也適用於非互動模式（`-p`）和[遠端控制](/docs/zh-TW/remote-control)。執行 `/config --help` 以列出每個可設定的鍵及其選項。別名：`/settings` |

70| `/context [all]` | 將目前的上下文使用情況視覺化為彩色網格。顯示上下文繁重工具、記憶體膨脹和容量警告的最佳化建議。在[全螢幕模式](/zh-TW/fullscreen)中，每個項目的分解會折疊以保持網格可見。傳遞 `all` 以展開它 |70| `/context [all]` | 將目前的上下文使用情況視覺化為彩色網格。顯示上下文繁重工具、記憶體膨脹和容量警告的最佳化建議。在[全螢幕模式](/docs/zh-TW/fullscreen)中，每個項目的分解會折疊以保持網格可見。傳遞 `all` 以展開它 |

71| `/copy [N]` | 將最後一個助手回應複製到剪貼簿。傳遞數字 `N` 以複製第 N 個最新回應：`/copy 2` 複製倒數第二個。當存在程式碼區塊時，顯示互動式選擇器以選擇個別區塊或完整回應。在選擇器中按 `w` 以將選擇寫入檔案而不是剪貼簿，這在 SSH 上很有用 |71| `/copy [N]` | 將最後一個助手回應複製到剪貼簿。傳遞數字 `N` 以複製第 N 個最新回應：`/copy 2` 複製倒數第二個。當存在程式碼區塊時，顯示互動式選擇器以選擇個別區塊或完整回應。在選擇器中按 `w` 以將選擇寫入檔案而不是剪貼簿，這在 SSH 上很有用 |

73| `/dataviz [request]` | **[Skill](/zh-TW/skills#bundled-skills).** 圖表、圖形和儀表板的設計指導。Claude 為資料選擇圖表形式，按角色分配顏色，使用捆綁的指令碼驗證調色盤以確保色盲安全和對比度，並應用標記、互動和無障礙規則。使用品牌中立的佔位符調色盤，您可以用自己的調色盤替換。{/* min-version: 2.1.198 */}需要 Claude Code v2.1.198 或更新版本 |73| `/dataviz [request]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 圖表、圖形和儀表板的設計指導。Claude 為資料選擇圖表形式，按角色分配顏色，使用捆綁的指令碼驗證調色盤以確保色盲安全和對比度，並應用標記、互動和無障礙規則。使用品牌中立的佔位符調色盤，您可以用自己的調色盤替換。{/* min-version: 2.1.198 */}需要 Claude Code v2.1.198 或更新版本 |

74| `/debug [description]` | **[Skill](/zh-TW/skills#bundled-skills).** 為目前工作階段啟用偵錯日誌記錄並通過讀取工作階段偵錯日誌來排除故障。除非您使用 `claude --debug` 啟動，否則偵錯日誌記錄預設為關閉，因此在工作階段中期運行 `/debug` 會從該時刻開始捕獲日誌。可選擇性地描述問題以集中分析 |74| `/debug [description]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 為目前工作階段啟用偵錯日誌記錄並通過讀取工作階段偵錯日誌來排除故障。除非您使用 `claude --debug` 啟動，否則偵錯日誌記錄預設為關閉，因此在工作階段中期運行 `/debug` 會從該時刻開始捕獲日誌。可選擇性地描述問題以集中分析 |

77| `/design-sync [hint]` | **[Skill](/zh-TW/skills#bundled-skills).** 轉換您的存放庫的 React 設計系統並將其上傳到 [Claude Design](https://claude.ai/design)，以便它產生的設計使用您的真實元件。可選擇性地命名設計系統，例如 `/design-sync Acme DS`。首次同步會驗證每個元件，在大型存放庫上可能需要幾個小時。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上，基礎工具無法到達 claude.ai，因此命令不可用 |77| `/design-sync [hint]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 轉換您的存放庫的 React 設計系統並將其上傳到 [Claude Design](https://claude.ai/design)，以便它產生的設計使用您的真實元件。可選擇性地命名設計系統，例如 `/design-sync Acme DS`。首次同步會驗證每個元件，在大型存放庫上可能需要幾個小時。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上，基礎工具無法到達 claude.ai，因此命令不可用 |

79| `/diff` | 開啟互動式差異檢視器，顯示未提交的變更和每個回合的差異。使用左/右箭頭在目前的 git 差異和個別 Claude 回合之間切換，使用上/下箭頭瀏覽檔案。按 Enter 以開啟選定檔案的差異，使用上/下或 PageUp/PageDown 捲動它，按 Esc 返回檔案清單。{/* min-version: 2.1.198 */}自 v2.1.198 起，開啟的檢視器也會在存放庫的 git 狀態在工作階段外變更時自動重新整理，例如在另一個終端機中進行分支切換或提交 |79| `/diff` | 開啟互動式差異檢視器，顯示未提交的變更和每個回合的差異。使用左/右箭頭在目前的 git 差異和個別 Claude 回合之間切換，使用上/下箭頭瀏覽檔案。按 Enter 以開啟選定檔案的差異，使用上/下或 PageUp/PageDown 捲動它，按 Esc 返回檔案清單。{/* min-version: 2.1.198 */}自 v2.1.198 起，開啟的檢視器也會在存放庫的 git 狀態在工作階段外變更時自動重新整理，例如在另一個終端機中進行分支切換或提交 |

80| `/doctor` | **[Skill](/zh-TW/skills#bundled-skills).** 執行設定檢查以診斷問題並可以修復它們。檢查安裝健康狀況，包括重複或遺留的安裝、`PATH` 問題和無法解析的設定檔案。查找未使用的 skills、MCP 伺服器和 plugins 與其上下文成本，標記緩慢的 [hooks](/zh-TW/hooks)，並檢查是否有更新版本在您的發行頻道上。對簽入的檔案進行本地 `CLAUDE.md` 檔案的重複資料刪除，通過削減 Claude 可以從程式碼庫衍生的內容來修剪簽入的 [`CLAUDE.md`](/zh-TW/memory) 檔案，並將保留的始終載入的指導遷移到 [skills](/zh-TW/skills) 和按需載入的嵌套 `CLAUDE.md` 檔案。修剪會削減目錄佈局、依賴清單和架構概述等部分，並保留與工具預設值不同的陷阱、基本原理和約定。也提供使 [auto mode](/zh-TW/permissions#permission-modes) 成為您的預設值的選項，以及[預先批准](/zh-TW/permissions)經常被拒絕的唯讀命令。首先報告發現並在變更任何內容之前要求確認。從終端機，`claude doctor` 列印唯讀安裝診斷而不啟動工作階段。別名：`/checkup`。{/* min-version: 2.1.206 */}`CLAUDE.md` 修剪檢查需要 Claude Code v2.1.206 或更新版本。在 v2.1.206 之前，版本檢查將 Homebrew 安裝與 `autoUpdatesChannel` 設定進行比較，而不是[已安裝的 cask 頻道](/zh-TW/setup#configure-release-channel)。{/* min-version: 2.1.205 */}在 v2.1.205 之前，`/doctor` 開啟唯讀診斷螢幕，按 `f` 將報告發送給 Claude |80| `/doctor` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 執行設定檢查以診斷問題並可以修復它們。檢查安裝健康狀況，包括重複或遺留的安裝、`PATH` 問題和無法解析的設定檔案。查找未使用的 skills、MCP 伺服器和 plugins 與其上下文成本，標記緩慢的 [hooks](/docs/zh-TW/hooks)，並檢查是否有更新版本在您的發行頻道上。對簽入的檔案進行本地 `CLAUDE.md` 檔案的重複資料刪除，通過削減 Claude 可以從程式碼庫衍生的內容來修剪簽入的 [`CLAUDE.md`](/docs/zh-TW/memory) 檔案，並將保留的始終載入的指導遷移到 [skills](/docs/zh-TW/skills) 和按需載入的嵌套 `CLAUDE.md` 檔案。修剪會削減目錄佈局、依賴清單和架構概述等部分，並保留與工具預設值不同的陷阱、基本原理和約定。也提供使 [auto mode](/docs/zh-TW/permissions#permission-modes) 成為您的預設值的選項，以及[預先批准](/docs/zh-TW/permissions)經常被拒絕的唯讀命令。首先報告發現並在變更任何內容之前要求確認。從終端機，`claude doctor` 列印唯讀安裝診斷而不啟動工作階段。別名：`/checkup`。{/* min-version: 2.1.206 */}`CLAUDE.md` 修剪檢查需要 Claude Code v2.1.206 或更新版本。在 v2.1.206 之前，版本檢查將 Homebrew 安裝與 `autoUpdatesChannel` 設定進行比較，而不是[已安裝的 cask 頻道](/docs/zh-TW/setup#configure-release-channel)。{/* min-version: 2.1.205 */}在 v2.1.205 之前，`/doctor` 開啟唯讀診斷螢幕，按 `f` 將報告發送給 Claude |

81| `/effort [level\|auto]` | 設定模型[努力程度](/zh-TW/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用的程度取決於模型，`max` 和 `ultracode` 僅限工作階段。`ultracode` 是一個 Claude Code 設定，結合 `xhigh` 推理與自動[工作流](/zh-TW/workflows#let-claude-decide-with-ultracode)協調。`auto` 重設為模型預設值。不帶引數時，開啟互動式滑塊；使用左右箭頭選擇程度，按 `Enter` 應用。立即生效，無需等待目前回應完成。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用程度引數，其中它僅適用於目前工作階段且不會儲存為您的預設值；需要 Claude Code v2.1.205 或更新版本。在 Fable 5、Opus 4.8 和 Opus 4.7 上，非互動 `/effort` 在[模型預設努力程度保持](/zh-TW/model-config#adjust-effort-level)生效時報告 `Not applied`，因此改為在啟動時傳遞 `--effort` |81| `/effort [level\|auto]` | 設定模型[努力程度](/docs/zh-TW/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用的程度取決於模型，`max` 和 `ultracode` 僅限工作階段。`ultracode` 是一個 Claude Code 設定，結合 `xhigh` 推理與自動[工作流](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)協調。`auto` 重設為模型預設值。不帶引數時，開啟互動式滑塊；使用左右箭頭選擇程度，按 `Enter` 應用。立即生效，無需等待目前回應完成。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用程度引數，其中它僅適用於目前工作階段且不會儲存為您的預設值；需要 Claude Code v2.1.205 或更新版本。在 Fable 5、Opus 4.8 和 Opus 4.7 上，非互動 `/effort` 在[模型預設努力程度保持](/docs/zh-TW/model-config#adjust-effort-level)生效時報告 `Not applied`，因此改為在啟動時傳遞 `--effort` |

84| `/fast [on\|off]` | 切換[快速模式](/zh-TW/fast-mode)開啟或關閉。{/* min-version: 2.1.205 */}在非互動模式（`-p`）中，`/fast` 僅在使用快速模式在其 [`--settings`](/zh-TW/cli-reference#cli-flags) 值中啟動的工作階段中工作，例如 `claude -p --settings '{"fastMode": true}'`；切換然後僅適用於目前工作階段且不會儲存為您的預設值，在任何其他非互動工作階段中命令報告快速模式不可用。需要 Claude Code v2.1.205 或更新版本 |84| `/fast [on\|off]` | 切換[快速模式](/docs/zh-TW/fast-mode)開啟或關閉。{/* min-version: 2.1.205 */}在非互動模式（`-p`）中，`/fast` 僅在使用快速模式在其 [`--settings`](/docs/zh-TW/cli-reference#cli-flags) 值中啟動的工作階段中工作，例如 `claude -p --settings '{"fastMode": true}'`；切換然後僅適用於目前工作階段且不會儲存為您的預設值，在任何其他非互動工作階段中命令報告快速模式不可用。需要 Claude Code v2.1.205 或更新版本 |

86| `/fewer-permission-prompts` | **[Skill](/zh-TW/skills#bundled-skills).** 掃描您的記錄以查找常見的唯讀 Bash 和 MCP 工具呼叫，然後將優先允許清單添加到專案 `.claude/settings.json` 以減少權限提示 |86| `/fewer-permission-prompts` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 掃描您的記錄以查找常見的唯讀 Bash 和 MCP 工具呼叫，然後將優先允許清單添加到專案 `.claude/settings.json` 以減少權限提示 |

87| `/focus` | 切換焦點檢視，僅顯示您的最後一個提示、帶有編輯 diffstats 的單行工具呼叫摘要和最終回應。{/* min-version: 2.1.198 */}自 v2.1.198 起，工具呼叫摘要也會計算在回合中啟動的 subagents 數量，並將已完成的背景工作通知折疊為單一計數。選擇在工作階段之間保持；設定設定中的 [`viewMode`](/zh-TW/settings#available-settings) 以覆蓋它。僅在[全螢幕渲染](/zh-TW/fullscreen)中可用 |87| `/focus` | 切換焦點檢視，僅顯示您的最後一個提示、帶有編輯 diffstats 的單行工具呼叫摘要和最終回應。{/* min-version: 2.1.198 */}自 v2.1.198 起，工具呼叫摘要也會計算在回合中啟動的 subagents 數量，並將已完成的背景工作通知折疊為單一計數。選擇在工作階段之間保持；設定設定中的 [`viewMode`](/docs/zh-TW/settings#available-settings) 以覆蓋它。僅在[全螢幕渲染](/docs/zh-TW/fullscreen)中可用 |

88| `/fork <directive>` | {/* min-version: 2.1.161 */}生成一個[分叉的 subagent](/zh-TW/sub-agents#fork-the-current-conversation)：一個背景 subagent，繼承完整的對話並在指令上工作，同時您繼續進行。其結果在完成時返回到您的對話。若要自己切換到對話的副本，請使用 `/branch`。在 v2.1.161 之前，`/fork` 是 `/branch` 的別名 |88| `/fork <directive>` | {/* min-version: 2.1.161 */}生成一個[分叉的 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)：一個背景 subagent，繼承完整的對話並在指令上工作，同時您繼續進行。其結果在完成時返回到您的對話。若要自己切換到對話的副本，請使用 `/branch`。在 v2.1.161 之前，`/fork` 是 `/branch` 的別名 |

90| `/heapdump` | 將 JavaScript 堆快照和記憶體分解寫入 `~/Desktop`，或在沒有 Desktop 資料夾的 Linux 上寫入您的主目錄，以診斷高記憶體使用情況。請參閱[故障排除](/zh-TW/troubleshooting#high-cpu-or-memory-usage) |90| `/heapdump` | 將 JavaScript 堆快照和記憶體分解寫入 `~/Desktop`，或在沒有 Desktop 資料夾的 Linux 上寫入您的主目錄，以診斷高記憶體使用情況。`.heapsnapshot` 檔案包含您的完整對話和認證，所以不要分享它。請參閱[故障排除](/docs/zh-TW/troubleshooting#high-cpu-or-memory-usage) |

93| `/ide` | 管理 IDE 整合並顯示狀態 |93| `/ide` | 管理 IDE 整合並顯示狀態 |

101| `/loop [interval] [prompt]` | **[Skill](/zh-TW/skills#bundled-skills).** 在工作階段保持開啟時重複執行提示。省略間隔，Claude 會在迭代之間自動調整步調。省略提示，[如果可用](/zh-TW/scheduled-tasks#run-the-built-in-maintenance-prompt)Claude 運行自主維護檢查或 `.claude/loop.md` 中的提示。示例：`/loop 5m check if the deploy finished`。請參閱[按計劃運行提示](/zh-TW/scheduled-tasks)。別名：`/proactive` |101| `/loop [interval] [prompt]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 在工作階段保持開啟時重複執行提示。省略間隔，Claude 會在迭代之間自動調整步調。省略提示，[如果可用](/docs/zh-TW/scheduled-tasks#run-the-built-in-maintenance-prompt)Claude 運行自主維護檢查或 `.claude/loop.md` 中的提示。示例：`/loop 5m check if the deploy finished`。請參閱[按計劃運行提示](/docs/zh-TW/scheduled-tasks)。別名：`/proactive` |

102| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | 管理 MCP 伺服器連線和 OAuth 驗證。不帶引數執行以開啟互動式清單，傳遞 `reconnect <server>` 以重新連接一個已斷開連接的伺服器，或傳遞 `enable`/`disable` 與伺服器名稱或 `all` 以在不開啟對話框的情況下變更連接狀態。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用，其中不帶引數執行時列印伺服器狀態的文字摘要而不是開啟清單；需要 Claude Code v2.1.205 或更新版本 |102| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | 管理 MCP 伺服器連線和 OAuth 驗證。不帶引數執行以開啟互動式清單，傳遞 `reconnect <server>` 以重新連接一個已斷開連接的伺服器，或傳遞 `enable`/`disable` 與伺服器名稱或 `all` 以在不開啟對話框的情況下變更連接狀態。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用，其中不帶引數執行時列印伺服器狀態的文字摘要而不是開啟清單；需要 Claude Code v2.1.205 或更新版本 |

105| `/model [model]` | 切換 AI 模型並將其儲存為新工作階段的預設值。對於支援此功能的模型，使用左/右箭頭以[調整努力程度](/zh-TW/model-config#adjust-effort-level)。不帶引數時，開啟選擇器；在列上按 `s` 以僅為目前工作階段切換。當對話有先前輸出時，選擇器會要求確認，因為下一個回應會重新讀取完整歷史記錄而不使用快取上下文。確認後，變更立即應用，無需等待目前回應完成。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用模型引數而不是選擇器，其中它僅適用於目前工作階段且不會儲存為您的預設值；需要 Claude Code v2.1.205 或更新版本 |105| `/model [model]` | 切換 AI 模型並將其儲存為新工作階段的預設值。對於支援此功能的模型，使用左/右箭頭以[調整努力程度](/docs/zh-TW/model-config#adjust-effort-level)。不帶引數時，開啟選擇器；在列上按 `s` 以僅為目前工作階段切換。當對話有先前輸出時，選擇器會要求確認，因為下一個回應會重新讀取完整歷史記錄而不使用快取上下文。確認後，變更立即應用，無需等待目前回應完成。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用模型引數而不是選擇器，其中它僅適用於目前工作階段且不會儲存為您的預設值；需要 Claude Code v2.1.205 或更新版本 |

107| `/permissions` | 管理工具權限的允許、詢問和拒絕規則。開啟互動式對話框，您可以按範圍檢視規則、添加或移除規則、管理工作目錄，以及檢視[最近的自動模式拒絕](/zh-TW/auto-mode-config#review-denials)。別名：`/allowed-tools` |107| `/permissions` | 管理工具權限的允許、詢問和拒絕規則。開啟互動式對話框，您可以按範圍檢視規則、添加或移除規則、管理工作目錄，以及檢視[最近的自動模式拒絕](/docs/zh-TW/auto-mode-config#review-denials)。別名：`/allowed-tools` |

109| `/plugin [subcommand]` | 管理 Claude Code [plugins](/zh-TW/plugins)。不帶引數執行以開啟 plugin 選單，或傳遞子命令如 `list`、`install`、`enable` 或 `disable` 以直接執行 |109| `/plugin [subcommand]` | 管理 Claude Code [plugins](/docs/zh-TW/plugins)。不帶引數執行以開啟 plugin 選單，或傳遞子命令如 `list`、`install`、`enable` 或 `disable` 以直接執行 |

111| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。直接詢問 Claude 以查看 pull request 評論。在較早的版本上，從 GitHub pull request 擷取並顯示評論；自動偵測目前分支的 PR，或傳遞 PR URL 或編號。需要 `gh` CLI |111| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。直接詢問 Claude 以查看 pull request 評論。在較早的版本上，從 GitHub pull request 擷取並顯示評論；自動偵測目前分支的 PR，或傳遞 PR URL 或編號。需要 `gh` CLI |

113| `/radio` | 在您的瀏覽器中開啟 Claude FM lo-fi 廣播。當沒有瀏覽器可用時列印串流 URL。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上不可用 |113| `/radio` | 在您的瀏覽器中開啟 Claude FM lo-fi 廣播。當沒有瀏覽器可用時列印串流 URL。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上不可用 |

115| `/release-notes` | 在互動式版本選擇器中檢視變更日誌。選擇特定版本以查看其發行說明，或選擇顯示所有版本。{/* min-version: 2.1.208 */}說明會在您的記錄中出現，無需進入 Claude 看到的對話。在 v2.1.208 之前，檢視的說明進入對話，包括顯示所有版本時的整個變更日誌 |115| `/release-notes` | 在互動式版本選擇器中檢視變更日誌。選擇特定版本以查看其發行說明，或選擇顯示所有版本。{/* min-version: 2.1.208 */}說明會在您的記錄中出現，無需進入 Claude 看到的對話。在 v2.1.208 之前，檢視的說明進入對話，包括顯示所有版本時的整個變更日誌 |

116| `/reload-plugins [--force]` | 重新載入所有作用中的 [plugins](/zh-TW/plugins) 以套用待處理的變更，無需重新啟動。報告每個已重新載入的元件的計數，並標記任何載入錯誤。當重新載入會變更載入的 MCP 工具並使提示快取失效時，命令會警告並跳過，除非您傳遞 `--force` |116| `/reload-plugins [--force]` | 重新載入所有作用中的 [plugins](/docs/zh-TW/plugins) 以套用待處理的變更，無需重新啟動。報告每個已重新載入的元件的計數，並標記任何載入錯誤。當重新載入會變更載入的 MCP 工具並使提示快取失效時，命令會警告並跳過，除非您傳遞 `--force` |

117| `/reload-skills` | {/* min-version: 2.1.152 */}重新掃描 [skill](/zh-TW/skills) 和命令目錄，以便在工作階段期間添加或更改的 skills 在磁碟上變得可用，無需重新啟動。報告有多少 skills 可用以及添加或移除了多少 |117| `/reload-skills` | {/* min-version: 2.1.152 */}重新掃描 [skill](/docs/zh-TW/skills) 和命令目錄，以便在工作階段期間添加或更改的 skills 在磁碟上變得可用，無需重新啟動。報告有多少 skills 可用以及添加或移除了多少 |

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

120| `/rename [name]` | 重新命名目前的工作階段並在提示列上顯示名稱。不使用名稱時，從對話歷史記錄自動產生名稱。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用；需要 Claude Code v2.1.205 或更新版本 |120| `/rename [name]` | 重新命名目前的工作階段並在提示列上顯示名稱。不使用名稱時，從對話歷史記錄自動產生名稱。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用；需要 Claude Code v2.1.205 或更新版本 |

121| `/resume [session]` | 按 ID 或名稱繼續對話，或開啟工作階段選擇器。自 v2.1.144 起，[背景工作階段](/zh-TW/agent-view)會在選擇器中顯示，標記為 `bg`；仍在運行的工作階段無法在此處繼續，因此從 `claude agents` 附加到它或先在那裡停止它。別名：`/continue` |121| `/resume [session]` | 按 ID 或名稱繼續對話，或開啟工作階段選擇器。自 v2.1.144 起，[背景工作階段](/docs/zh-TW/agent-view)會在選擇器中顯示，標記為 `bg`；仍在運行的工作階段無法在此處繼續，因此從 `claude agents` 附加到它或先在那裡停止它。別名：`/continue` |

122| `/review [PR]` | {/* min-version: 2.1.202 */}按編號執行 GitHub pull request 的快速單次通過、唯讀審閱。不帶引數時，列出開放的 PR 以供選擇；PR 編號後的文字成為額外的審閱指示。從 v2.1.186 到 v2.1.201，`/review` 改為運行與 `/code-review medium` 相同的多 agent 引擎。如需選定努力程度的多 agent 審閱，請使用 [`/code-review <level> <pr#>`](/zh-TW/code-review#review-a-diff-locally)；如需雲端審閱，請參閱 [`/code-review ultra`](/zh-TW/ultrareview) |122| `/review [PR]` | {/* min-version: 2.1.202 */}按編號執行 GitHub pull request 的快速單次通過、唯讀審閱。不帶引數時，列出開放的 PR 以供選擇；PR 編號後的文字成為額外的審閱指示。從 v2.1.186 到 v2.1.201，`/review` 改為運行與 `/code-review medium` 相同的多 agent 引擎。如需選定努力程度的多 agent 審閱，請使用 [`/code-review <level> <pr#>`](/docs/zh-TW/code-review#review-a-diff-locally)；如需雲端審閱，請參閱 [`/code-review ultra`](/docs/zh-TW/ultrareview) |

124| `/run` | **[Skill](/zh-TW/skills#bundled-skills).** 啟動並驅動您的專案應用程式以查看在執行中的應用程式中工作的變更，而不僅僅是在測試中。請參閱[運行並驗證您的應用程式](/zh-TW/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |124| `/run` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 啟動並驅動您的專案應用程式以查看在執行中的應用程式中工作的變更，而不僅僅是在測試中。請參閱[運行並驗證您的應用程式](/docs/zh-TW/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |

125| `/run-skill-generator` | **[Skill](/zh-TW/skills#bundled-skills).** 通過從乾淨環境編寫每個專案的 [skill](/zh-TW/skills#run-and-verify-your-app)，教導 `/run` 和 `/verify` 如何構建、啟動和驅動您的專案應用程式。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |125| `/run-skill-generator` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 通過從乾淨環境編寫每個專案的 [skill](/docs/zh-TW/skills#run-and-verify-your-app)，教導 `/run` 和 `/verify` 如何構建、啟動和驅動您的專案應用程式。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |

127| `/schedule [description]` | 建立、更新、列出或執行[例行工作](/zh-TW/routines)，在 Anthropic 管理的雲端基礎設施上執行。Claude 會以對話方式引導您完成設定。別名：`/routines` |127| `/schedule [description]` | 建立、更新、列出或執行[例行工作](/docs/zh-TW/routines)，在 Anthropic 管理的雲端基礎設施上執行。Claude 會以對話方式引導您完成設定。別名：`/routines` |

128| `/scroll-speed` | 以互動方式調整滑鼠滾輪[捲動速度](/zh-TW/fullscreen#mouse-wheel-scrolling)，使用尺標，您可以在對話框開啟時捲動以預覽變更。僅在[全螢幕渲染](/zh-TW/fullscreen)中可用，在 JetBrains IDE 終端機中不可用 |128| `/scroll-speed` | 以互動方式調整滑鼠滾輪[捲動速度](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)，使用尺標，您可以在對話框開啟時捲動以預覽變更。僅在[全螢幕渲染](/docs/zh-TW/fullscreen)中可用，在 JetBrains IDE 終端機中不可用 |

130| `/setup-bedrock` | 通過互動式精靈配置 [Amazon Bedrock](/zh-TW/amazon-bedrock) 驗證、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_BEDROCK=1` 時可見。首次 Amazon Bedrock 使用者也可以從登入螢幕訪問此精靈 |130| `/setup-bedrock` | 通過互動式精靈配置 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 驗證、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_BEDROCK=1` 時可見。首次 Amazon Bedrock 使用者也可以從登入螢幕訪問此精靈 |

131| `/setup-vertex` | 通過互動式精靈配置 [Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 驗證、專案、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_VERTEX=1` 時可見。首次 Google Cloud 的 Agent Platform 使用者也可以從登入螢幕訪問此精靈 |131| `/setup-vertex` | 通過互動式精靈配置 [Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 驗證、專案、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_VERTEX=1` 時可見。首次 Google Cloud 的 Agent Platform 使用者也可以從登入螢幕訪問此精靈 |

132| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/zh-TW/skills#bundled-skills).** 審閱變更的程式碼以查找清理機會並應用修復。四個審閱 [agents](/zh-TW/sub-agents) 並行運行，涵蓋現有幫助程式的重用、簡化、效率和變更是否位於正確的抽象層級。從 v2.1.154 開始，審閱不尋找正確性錯誤。使用 `/code-review` 查找錯誤。在較早的版本上，`/simplify` 等同於 `/code-review --fix`。傳遞路徑或 PR 參考以審閱特定目標 |132| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/docs/zh-TW/skills#bundled-skills).** 審閱變更的程式碼以查找清理機會並應用修復。四個審閱 [agents](/docs/zh-TW/sub-agents) 並行運行，涵蓋現有幫助程式的重用、簡化、效率和變更是否位於正確的抽象層級。從 v2.1.154 開始，審閱不尋找正確性錯誤。使用 `/code-review` 查找錯誤。在較早的版本上，`/simplify` 等同於 `/code-review --fix`。傳遞路徑或 PR 參考以審閱特定目標 |

133| `/skills` | 列出可用的 [skills](/zh-TW/skills)。{/* min-version: 2.1.121 */}自 v2.1.121 起，輸入以按名稱篩選清單。按 `t` 按 token 計數排序。按 `Space` 以[從 Claude 或 `/` 選單隱藏 skill](/zh-TW/skills#override-skill-visibility-from-settings)，然後按 `Enter` 以儲存 |133| `/skills` | 列出可用的 [skills](/docs/zh-TW/skills)。{/* min-version: 2.1.121 */}自 v2.1.121 起，輸入以按名稱篩選清單。按 `t` 按 token 計數排序。按 `Space` 以[從 Claude 或 `/` 選單隱藏 skill](/docs/zh-TW/skills#override-skill-visibility-from-settings)，然後按 `Enter` 以儲存 |

140| `/team-onboarding` | 從您的 Claude Code 使用歷史記錄產生團隊入職指南。Claude 分析您過去 30 天的工作階段、命令和 MCP 伺服器使用情況，並產生一份 markdown 指南，團隊成員可以貼上作為第一條訊息以快速設定。對於 claude.ai 上 Pro、Max、Team 和 Enterprise 方案的訂閱者，也會返回一個分享連結，團隊成員可以直接在 Claude Code 中開啟 |140| `/team-onboarding` | 從您的 Claude Code 使用歷史記錄產生團隊入職指南。Claude 分析您過去 30 天的工作階段、命令和 MCP 伺服器使用情況，並產生一份 markdown 指南，團隊成員可以貼上作為第一條訊息以快速設定。對於 claude.ai 上 Pro、Max、Team 和 Enterprise 方案的訂閱者，也會返回一個分享連結，團隊成員可以直接在 Claude Code 中開啟 |

141| `/teleport` | 將[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web#from-web-to-terminal) 工作階段拉入此終端機：開啟選擇器，然後擷取分支和對話。也可用作 `/tp`。需要 claude.ai 訂閱 |141| `/teleport` | 將[網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web#from-web-to-terminal) 工作階段拉入此終端機：開啟選擇器，然後擷取分支和對話。也可用作 `/tp`。需要 claude.ai 訂閱 |

143| `/theme` | 變更色彩主題。包括跟隨您終端機深色或淺色背景的 `auto` 選項、淺色和深色變體、色盲無障礙（daltonized）主題、ANSI 主題（使用您終端機的色彩調色盤），以及來自 `~/.claude/themes/` 或 plugins 的任何[自訂主題](/zh-TW/terminal-config#create-a-custom-theme) |143| `/theme` | 變更色彩主題。包括跟隨您終端機深色或淺色背景的 `auto` 選項、淺色和深色變體、色盲無障礙（daltonized）主題、ANSI 主題（使用您終端機的色彩調色盤），以及來自 `~/.claude/themes/` 或 plugins 的任何[自訂主題](/docs/zh-TW/terminal-config#create-a-custom-theme) |

146| `/ultrareview [PR]` | 在雲端沙箱中使用 [ultrareview](/zh-TW/ultrareview) 運行深度、多 agent 程式碼審閱。首選的調用現在是 `/code-review ultra`，`/ultrareview` 保留為別名。Pro 和 Max 上包括 3 次免費執行，然後需要[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |146| `/ultrareview [PR]` | 在雲端沙箱中使用 [ultrareview](/docs/zh-TW/ultrareview) 運行深度、多 agent 程式碼審閱。首選的調用現在是 `/code-review ultra`，`/ultrareview` 保留為別名。Pro 和 Max 上包括 3 次免費執行，然後需要[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

148| `/usage` | 顯示工作階段成本、方案使用限制和活動統計資訊。在 Pro、Max、Team 或 Enterprise 方案上，包括按 skill、subagent、plugin 和 MCP 伺服器的使用情況分解。請參閱[成本追蹤指南](/zh-TW/costs#using-the-%2Fusage-command)以了解詳細資訊。`/cost` 和 `/stats` 是別名 |148| `/usage` | 顯示工作階段成本、方案使用限制和活動統計資訊。在 Pro、Max、Team 或 Enterprise 方案上，包括按 skill、subagent、plugin 和 MCP 伺服器的使用情況分解。請參閱[成本追蹤指南](/docs/zh-TW/costs#using-the-%2Fusage-command)以了解詳細資訊。`/cost` 和 `/stats` 是別名 |

149| `/usage-credits` | 配置使用量額度以在達到限制時繼續工作。在 Pro 和 Max 方案上，開啟[CLI 內對話框](/zh-TW/costs#set-a-spend-limit-on-pro-and-max)以購買使用量額度、設定每月支出限制和配置自動重新載入；在 Claude Code v2.1.207 之前的版本和其他方案上，在您的瀏覽器中開啟使用量額度計費頁面，除了沒有計費存取權的 Team 和 Enterprise 成員改為從 CLI 向其管理員發送使用量額度請求。{/* min-version: 2.1.205 */}當沒有瀏覽器可以開啟計費頁面時，例如透過 SSH，命令改為列印要訪問的 URL；這需要 Claude Code v2.1.205 或更新版本，較早的版本在該情況下顯示任何內容。先前為 `/extra-usage` |149| `/usage-credits` | 配置使用量額度以在達到限制時繼續工作。在 Pro 和 Max 方案上，開啟[CLI 內對話框](/docs/zh-TW/costs#set-a-spend-limit-on-pro-and-max)以購買使用量額度、設定每月支出限制和配置自動重新載入；在 Claude Code v2.1.207 之前的版本和其他方案上，在您的瀏覽器中開啟使用量額度計費頁面，除了沒有計費存取權的 Team 和 Enterprise 成員改為從 CLI 向其管理員發送使用量額度請求。{/* min-version: 2.1.205 */}當沒有瀏覽器可以開啟計費頁面時，例如透過 SSH，命令改為列印要訪問的 URL；這需要 Claude Code v2.1.205 或更新版本，較早的版本在該情況下顯示任何內容。先前為 `/extra-usage` |

150| `/verify` | **[Skill](/zh-TW/skills#bundled-skills).** 通過構建您的專案應用程式、運行它並觀察結果來確認程式碼變更是否執行了應該執行的操作，而不是依賴測試或類型檢查。請參閱[運行並驗證您的應用程式](/zh-TW/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |150| `/verify` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 通過構建您的專案應用程式、運行它並觀察結果來確認程式碼變更是否執行了應該執行的操作，而不是依賴測試或類型檢查。請參閱[運行並驗證您的應用程式](/docs/zh-TW/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |

151| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。若要在 Vim 和一般編輯模式之間切換，請使用 `/config` → Editor mode |151| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。若要在 Vim 和一般編輯模式之間切換，請使用 `/config` → Editor mode |

152| `/voice [hold\|tap\|off]` | 切換[語音聽寫](/zh-TW/voice-dictation)，或在特定模式下啟用它。需要 Claude.ai 帳戶 |152| `/voice [hold\|tap\|off]` | 切換[語音聽寫](/docs/zh-TW/voice-dictation)，或在特定模式下啟用它。需要 Claude.ai 帳戶 |

153| `/web-setup` | 使用您的本地 `gh` CLI 認證將您的 GitHub 帳戶連接到[網頁上的 Claude Code](/zh-TW/web-quickstart#connect-from-your-terminal)。如果 GitHub 未連接，`/schedule` 會自動提示此操作 |153| `/web-setup` | 使用您的本地 `gh` CLI 認證將您的 GitHub 帳戶連接到[網頁上的 Claude Code](/docs/zh-TW/web-quickstart#connect-from-your-terminal)。如果 GitHub 未連接，`/schedule` 會自動提示此操作 |

155 155

156<h2 id="mcp-prompts">156<h2 id="mcp-prompts">

157 MCP prompts157 MCP prompts

158</h2>158</h2>

159 159

160MCP 伺服器可以公開顯示為命令的提示。這些使用 `/mcp__<server>__<prompt>` 格式，並從連接的伺服器動態發現。請參閱 [MCP prompts](/zh-TW/mcp#use-mcp-prompts-as-commands) 以了解詳細資訊。160MCP 伺服器可以公開顯示為命令的提示。這些使用 `/mcp__<server>__<prompt>` 格式，並從連接的伺服器動態發現。請參閱 [MCP prompts](/docs/zh-TW/mcp#use-mcp-prompts-as-commands) 以了解詳細資訊。

161 161

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

163 另請參閱163 另請參閱

164</h2>164</h2>

165 165

166* [Skills](/zh-TW/skills)：建立您自己的命令166* [Skills](/docs/zh-TW/skills)：建立您自己的命令

167* [Interactive mode](/zh-TW/interactive-mode)：鍵盤快捷鍵、Vim 模式和命令歷史記錄167* [Interactive mode](/docs/zh-TW/interactive-mode)：鍵盤快捷鍵、Vim 模式和命令歷史記錄

168* [CLI reference](/zh-TW/cli-reference)：啟動時間旗標168* [CLI reference](/docs/zh-TW/cli-reference)：啟動時間旗標

hooks.md +62 −62

Details

7> Claude Code hook 事件、配置架構、JSON 輸入/輸出格式、退出代碼、非同步 hooks、HTTP hooks、提示 hooks 和 MCP 工具 hooks 的參考。7> Claude Code hook 事件、配置架構、JSON 輸入/輸出格式、退出代碼、非同步 hooks、HTTP hooks、提示 hooks 和 MCP 工具 hooks 的參考。

8 8

9<Tip>9<Tip>

~~10 如需快速入門指南和範例，請參閱 [使用 hooks 自動化工作流程](/zh-TW/hooks-guide)。~~10 如需快速入門指南和範例，請參閱 [使用 hooks 自動化工作流程](/docs/zh-TW/hooks-guide)。

11</Tip>11</Tip>

12 12

13Hooks 是使用者定義的 shell 命令、HTTP 端點或 LLM 提示，在 Claude Code 生命週期的特定時間點自動執行。使用此參考來查詢事件架構、配置選項、JSON 輸入/輸出格式，以及非同步 hooks、HTTP hooks 和 MCP 工具 hooks 等進階功能。如果您是第一次設定 hooks，請改為從 [指南](/zh-TW/hooks-guide) 開始。13Hooks 是使用者定義的 shell 命令、HTTP 端點或 LLM 提示，在 Claude Code 生命週期的特定時間點自動執行。使用此參考來查詢事件架構、配置選項、JSON 輸入/輸出格式，以及非同步 hooks、HTTP hooks 和 MCP 工具 hooks 等進階功能。如果您是第一次設定 hooks，請改為從 [指南](/docs/zh-TW/hooks-guide) 開始。

14 14

15<h2 id="hook-lifecycle">15<h2 id="hook-lifecycle">

16 Hook 生命週期16 Hook 生命週期

52| `TaskCompleted` | When a task is being marked as completed |52| `TaskCompleted` | When a task is being marked as completed |

53| `Stop` | When Claude finishes responding |53| `Stop` | When Claude finishes responding |

54| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |54| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

57| `ConfigChange` | When a configuration file changes during a session |57| `ConfigChange` | When a configuration file changes during a session |

58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

59| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |59| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

~~60| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |~~60| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

62| `PreCompact` | Before context compaction |62| `PreCompact` | Before context compaction |

63| `PostCompact` | After context compaction completes |63| `PostCompact` | After context compaction completes |

64| `Elicitation` | When an MCP server requests user input during a tool call |64| `Elicitation` | When an MCP server requests user input during a tool call |

147 }147 }

148 ```148 ```

149 149

150 如果命令是更安全的 `rm` 變體，如 `rm file.txt`，指令碼會改為執行 `exit 0`。Exit code 0 且沒有輸出表示 hook 沒有決定要報告，因此工具呼叫會繼續通過正常的[權限流程](/zh-TW/permissions)。Hook 可以拒絕呼叫，但保持沉默不會批准它。150 如果命令是更安全的 `rm` 變體，如 `rm file.txt`，指令碼會改為執行 `exit 0`。Exit code 0 且沒有輸出表示 hook 沒有決定要報告，因此工具呼叫會繼續通過正常的[權限流程](/docs/zh-TW/permissions)。Hook 可以拒絕呼叫，但保持沉默不會批准它。

151 </Step>151 </Step>

152 152

153 <Step title="Claude Code 根據結果採取行動">153 <Step title="Claude Code 根據結果採取行動">

190 190

191有關設定檔解析的詳細資訊，請參閱 [settings](/zh-TW/settings)。企業管理員可以使用 `allowManagedHooksOnly` 來阻止使用者、專案和外掛程式 hooks。在受管理的設定 `enabledPlugins` 中強制啟用的外掛程式的 Hooks 是例外，因此管理員可以通過組織市場分發經過驗證的 hooks。請參閱 [Hook 配置](/zh-TW/settings#hook-configuration)。191有關設定檔解析的詳細資訊，請參閱 [settings](/docs/zh-TW/settings)。企業管理員可以使用 `allowManagedHooksOnly` 來阻止使用者、專案和外掛程式 hooks。在受管理的設定 `enabledPlugins` 中強制啟用的外掛程式的 Hooks 是例外，因此管理員可以通過組織市場分發經過驗證的 hooks。請參閱 [Hook 配置](/docs/zh-TW/settings#hook-configuration)。

192 192

193<h3 id="matcher-patterns">193<h3 id="matcher-patterns">

194 匹配器模式194 匹配器模式

258 258

259`UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`MessageDisplay` 和 `CwdChanged` 不支援匹配器，總是在每次出現時觸發。如果您將 `matcher` 欄位新增到這些事件，它會被無聲地忽略。259`UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`MessageDisplay` 和 `CwdChanged` 不支援匹配器，總是在每次出現時觸發。如果您將 `matcher` 欄位新增到這些事件，它會被無聲地忽略。

260 260

261對於工具事件，您可以通過在個別 hook 處理程式上設定 [`if` 欄位](#common-fields) 來更狹隘地篩選。`if` 使用 [權限規則語法](/zh-TW/permissions) 來匹配工具名稱和參數，因此 `"Bash(git *)"` 僅在任何 Bash 輸入的子命令匹配 `git *` 時執行，`"Edit(*.ts)"` 僅針對 TypeScript 檔案執行。261對於工具事件，您可以通過在個別 hook 處理程式上設定 [`if` 欄位](#common-fields) 來更狹隘地篩選。`if` 使用 [權限規則語法](/docs/zh-TW/permissions) 來匹配工具名稱和參數，因此 `"Bash(git *)"` 僅在任何 Bash 輸入的子命令匹配 `git *` 時執行，`"Edit(*.ts)"` 僅針對 TypeScript 檔案執行。

262 262

263<h4 id="match-mcp-tools">263<h4 id="match-mcp-tools">

264 匹配 MCP 工具264 匹配 MCP 工具

265</h4>265</h4>

266 266

267[MCP](/zh-TW/mcp) 伺服器工具在工具事件中顯示為常規工具（`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied`），因此您可以像匹配任何其他工具名稱一樣匹配它們。267[MCP](/docs/zh-TW/mcp) 伺服器工具在工具事件中顯示為常規工具（`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied`），因此您可以像匹配任何其他工具名稱一樣匹配它們。

268 268

269MCP 工具遵循命名模式 `mcp__<server>__<tool>`，例如：269MCP 工具遵循命名模式 `mcp__<server>__<tool>`，例如：

270 270

280 280

281精確匹配集中的連字號需要 Claude Code v2.1.195 或更新版本。在較早的版本上，像 `mcp__brave-search` 這樣的裸連字號前綴被評估為未錨定的正規表達式，並匹配來自該伺服器的每個工具。`mcp__brave-search__.*` 形式在每個版本上都有效。281精確匹配集中的連字號需要 Claude Code v2.1.195 或更新版本。在較早的版本上，像 `mcp__brave-search` 這樣的裸連字號前綴被評估為未錨定的正規表達式，並匹配來自該伺服器的每個工具。`mcp__brave-search__.*` 形式在每個版本上都有效。

282 282

283來自 [plugin-bundled MCP server](/zh-TW/mcp#plugin-provided-mcp-servers) 的工具使用包含外掛程式名稱的範圍伺服器段：`mcp__plugin_<plugin-name>_<server-name>__<tool>`。針對裸伺服器金鑰編寫的匹配器永遠不會針對這些工具觸發。對於名為 `my-plugin` 的外掛程式，在金鑰 `db` 下打包伺服器，`query` 工具顯示為 `mcp__plugin_my-plugin_db__query`，因此來自該伺服器的每個工具的匹配器是 `mcp__plugin_my-plugin_db__.*`。在處理程式的 [`if` 欄位](#common-fields) 中使用相同的範圍工具名稱。請參閱 [Plugin-provided MCP servers](/zh-TW/mcp#plugin-provided-mcp-servers) 以了解如何建立範圍名稱。283來自 [plugin-bundled MCP server](/docs/zh-TW/mcp#plugin-provided-mcp-servers) 的工具使用包含外掛程式名稱的範圍伺服器段：`mcp__plugin_<plugin-name>_<server-name>__<tool>`。針對裸伺服器金鑰編寫的匹配器永遠不會針對這些工具觸發。對於名為 `my-plugin` 的外掛程式，在金鑰 `db` 下打包伺服器，`query` 工具顯示為 `mcp__plugin_my-plugin_db__query`，因此來自該伺服器的每個工具的匹配器是 `mcp__plugin_my-plugin_db__.*`。在處理程式的 [`if` 欄位](#common-fields) 中使用相同的範圍工具名稱。請參閱 [Plugin-provided MCP servers](/docs/zh-TW/mcp#plugin-provided-mcp-servers) 以了解如何建立範圍名稱。

284 284

285此範例記錄所有 memory 伺服器操作並驗證來自任何 MCP 伺服器的寫入操作：285此範例記錄所有 memory 伺服器操作並驗證來自任何 MCP 伺服器的寫入操作：

286 286

319 319

320* **[命令 hooks](#command-hook-fields)**（`type: "command"`）：執行 shell 命令。您的指令碼在 stdin 上接收事件的 [JSON 輸入](#hook-input-and-output)，並通過退出代碼和 stdout 傳回結果。320* **[命令 hooks](#command-hook-fields)**（`type: "command"`）：執行 shell 命令。您的指令碼在 stdin 上接收事件的 [JSON 輸入](#hook-input-and-output)，並通過退出代碼和 stdout 傳回結果。

321* **[HTTP hooks](#http-hook-fields)**（`type: "http"`）：將事件的 JSON 輸入作為 HTTP POST 請求發送到 URL。端點通過使用與命令 hooks 相同的 [JSON 輸出格式](#json-output) 的回應正文傳回結果。321* **[HTTP hooks](#http-hook-fields)**（`type: "http"`）：將事件的 JSON 輸入作為 HTTP POST 請求發送到 URL。端點通過使用與命令 hooks 相同的 [JSON 輸出格式](#json-output) 的回應正文傳回結果。

322* **[MCP 工具 hooks](#mcp-tool-hook-fields)**（`type: "mcp_tool"`）：在已連接的 [MCP 伺服器](/zh-TW/mcp) 上呼叫工具。工具的文字輸出被視為類似命令 hook stdout。322* **[MCP 工具 hooks](#mcp-tool-hook-fields)**（`type: "mcp_tool"`）：在已連接的 [MCP 伺服器](/docs/zh-TW/mcp) 上呼叫工具。工具的文字輸出被視為類似命令 hook stdout。

323* **[提示 hooks](#prompt-and-agent-hook-fields)**（`type: "prompt"`）：將提示發送到 Claude 模型進行單輪評估。模型以 JSON 形式返回是/否決定。請參閱 [基於提示的 hooks](#prompt-based-hooks)。323* **[提示 hooks](#prompt-and-agent-hook-fields)**（`type: "prompt"`）：將提示發送到 Claude 模型進行單輪評估。模型以 JSON 形式返回是/否決定。請參閱 [基於提示的 hooks](#prompt-based-hooks)。

324* **[代理 hooks](#prompt-and-agent-hook-fields)**（`type: "agent"`）：生成一個可以使用 Read、Grep 和 Glob 等工具來驗證條件的 subagent，然後返回決定。代理 hooks 是實驗性的，可能會變更。請參閱 [基於代理的 hooks](#agent-based-hooks)。324* **[代理 hooks](#prompt-and-agent-hook-fields)**（`type: "agent"`）：生成一個可以使用 Read、Grep 和 Glob 等工具來驗證條件的 subagent，然後返回決定。代理 hooks 是實驗性的，可能會變更。請參閱 [基於代理的 hooks](#agent-based-hooks)。

325 325

326所有匹配的 hooks 並行執行，相同的處理程式會自動去重。命令 hooks 按命令字串和 `args` 去重，HTTP hooks 按 URL 去重。326所有匹配的 hooks 並行執行，相同的處理程式會自動去重。命令 hooks 按命令字串和 `args` 去重，HTTP hooks 按 URL 去重。

327 327

328處理程式在目前目錄中執行，使用 Claude Code 的環境。在遠端網路環境中，`$CLAUDE_CODE_REMOTE` 環境變數設定為 `"true"`，在本機 CLI 中未設定。{/* min-version: 2.1.199 */}自 v2.1.199 起，[`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/zh-TW/env-vars) 設定為 [Remote Control](/zh-TW/remote-control) 工作階段 ID，而本機工作階段具有活動的 Remote Control 連接。328處理程式在目前目錄中執行，使用 Claude Code 的環境。在遠端網路環境中，`$CLAUDE_CODE_REMOTE` 環境變數設定為 `"true"`，在本機 CLI 中未設定。{/* min-version: 2.1.199 */}自 v2.1.199 起，[`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/zh-TW/env-vars) 設定為 [Remote Control](/docs/zh-TW/remote-control) 工作階段 ID，而本機工作階段具有活動的 Remote Control 連接。

329 329

330<h4 id="common-fields">330<h4 id="common-fields">

331 通用欄位331 通用欄位

336| 欄位 | 必需 | 描述 |336| 欄位 | 必需 | 描述 |

337| :-------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |337| :-------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

338| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |338| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |

339| `if` | 否 | 權限規則語法以篩選此 hook 何時執行，例如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。Hook 命令僅在工具呼叫匹配模式時執行。請參閱下面的 [Bash 匹配表](#bash-if-matching) 以了解 Bash 模式如何針對子命令、`$()` 和反引號進行評估。僅在工具事件上評估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，設定 `if` 的 hook 永遠不會執行。使用與 [權限規則](/zh-TW/permissions) 相同的語法 |339| `if` | 否 | 權限規則語法以篩選此 hook 何時執行，例如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。Hook 命令僅在工具呼叫匹配模式時執行。請參閱下面的 [Bash 匹配表](#bash-if-matching) 以了解 Bash 模式如何針對子命令、`$()` 和反引號進行評估。僅在工具事件上評估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，設定 `if` 的 hook 永遠不會執行。使用與 [權限規則](/docs/zh-TW/permissions) 相同的語法 |

340| `timeout` | 否 | 取消前的秒數。預設值：`command`、`http` 和 `mcp_tool` 為 600；`prompt` 為 30；`agent` 為 60。[`UserPromptSubmit`](#userpromptsubmit) 將 `command`、`http` 和 `mcp_tool` 的預設值降低到 30，[`MessageDisplay`](#messagedisplay) 將其降低到 10 |340| `timeout` | 否 | 取消前的秒數。預設值：`command`、`http` 和 `mcp_tool` 為 600；`prompt` 為 30；`agent` 為 60。[`UserPromptSubmit`](#userpromptsubmit) 將 `command`、`http` 和 `mcp_tool` 的預設值降低到 30，[`MessageDisplay`](#messagedisplay) 將其降低到 10 |

341| `statusMessage` | 否 | hook 執行時顯示的自訂微調訊息 |341| `statusMessage` | 否 | hook 執行時顯示的自訂微調訊息 |

342| `once` | 否 | 如果為 `true`，每個工作階段只執行一次，然後被移除。僅在 [skill frontmatter](#hooks-in-skills-and-agents) 中受尊重；在設定檔和代理 frontmatter 中被忽略 |342| `once` | 否 | 如果為 `true`，每個工作階段只執行一次，然後被移除。僅在 [skill frontmatter](#hooks-in-skills-and-agents) 中受尊重；在設定檔和代理 frontmatter 中被忽略 |

355 355

356當 Bash 命令無法解析時，篩選器也會失敗開放，無論如何執行您的 hook。因為 `if` 篩選器是盡力而為的，請使用 [權限系統](/zh-TW/permissions) 而不是 hook 來強制執行硬允許或拒絕。356當 Bash 命令無法解析時，篩選器也會失敗開放，無論如何執行您的 hook。因為 `if` 篩選器是盡力而為的，請使用 [權限系統](/docs/zh-TW/permissions) 而不是 hook 來強制執行硬允許或拒絕。

357 357

358<h4 id="command-hook-fields">358<h4 id="command-hook-fields">

359 命令 hook 欄位359 命令 hook 欄位

406 406

407兩種形式都支援相同的 [路徑佔位符](#reference-scripts-by-path)，並且都將它們作為環境變數 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA` 匯出到生成的程序，因此指令碼可以讀取 `process.env.CLAUDE_PLUGIN_ROOT`，無論它是如何啟動的。407兩種形式都支援相同的 [路徑佔位符](#reference-scripts-by-path)，並且都將它們作為環境變數 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA` 匯出到生成的程序，因此指令碼可以讀取 `process.env.CLAUDE_PLUGIN_ROOT`，無論它是如何啟動的。

408 408

409外掛程式 hooks 另外替換 [`${user_config.*}`](/zh-TW/plugins-reference#user-configuration) 值，僅在 exec 形式中：該值被替換為 `command` 和每個 `args` 元素中的純字串，因此沒有 shell 重新解析它。409外掛程式 hooks 另外替換 [`${user_config.*}`](/docs/zh-TW/plugins-reference#user-configuration) 值，僅在 exec 形式中：該值被替換為 `command` 和每個 `args` 元素中的純字串，因此沒有 shell 重新解析它。

410 410

411shell 形式的外掛程式 hook，其 `command` 參考 `${user_config.*}` 會失敗並出現 [錯誤](/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.*}`。411shell 形式的外掛程式 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.*}`。

412 412

413<Note>413<Note>

414 在 exec 形式中，`command` 僅是可執行檔名稱或路徑。如果 `command` 是沒有路徑分隔符的裸名稱，並且與 `args` 一起包含空格，Claude Code 會記錄警告，因為生成將失敗：沒有名為 `node script.js` 的可執行檔。將額外的令牌移到 `args` 中。包含空格的絕對路徑，如 `C:\Program Files\nodejs\node.exe`，是單個有效的可執行檔，不會觸發警告。414 在 exec 形式中，`command` 僅是可執行檔名稱或路徑。如果 `command` 是沒有路徑分隔符的裸名稱，並且與 `args` 一起包含空格，Claude Code 會記錄警告，因為生成將失敗：沒有名為 `node script.js` 的可執行檔。將額外的令牌移到 `args` 中。包含空格的絕對路徑，如 `C:\Program Files\nodejs\node.exe`，是單個有效的可執行檔，不會觸發警告。

463 463

464| 欄位 | 必需 | 描述 |464| 欄位 | 必需 | 描述 |

465| :------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |465| :------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

466| `server` | 是 | 已配置的 MCP 伺服器的名稱。對於 [plugin-bundled server](/zh-TW/mcp#plugin-provided-mcp-servers)，這是範圍名稱 `plugin:<plugin-name>:<server-name>`，例如 `plugin:my-plugin:db`，而不是裸伺服器金鑰。伺服器必須已連接；hook 永遠不會觸發 OAuth 或連接流程 |466| `server` | 是 | 已配置的 MCP 伺服器的名稱。對於 [plugin-bundled server](/docs/zh-TW/mcp#plugin-provided-mcp-servers)，這是範圍名稱 `plugin:<plugin-name>:<server-name>`，例如 `plugin:my-plugin:db`，而不是裸伺服器金鑰。伺服器必須已連接；hook 永遠不會觸發 OAuth 或連接流程 |

467| `tool` | 是 | 該伺服器上要呼叫的工具名稱 |467| `tool` | 是 | 該伺服器上要呼叫的工具名稱 |

468| `input` | 否 | 傳遞給工具的參數。字串值支援來自 hook 的 [JSON 輸入](#hook-input-and-output) 的 `${path}` 替換，例如 `"${tool_input.file_path}"` |468| `input` | 否 | 傳遞給工具的參數。字串值支援來自 hook 的 [JSON 輸入](#hook-input-and-output) 的 `${path}` 替換，例如 `"${tool_input.file_path}"` |

469 469

510 510

511使用這些佔位符按相對於專案或外掛程式根目錄的路徑參考 hook 指令碼，無論 hook 執行時的工作目錄如何：511使用這些佔位符按相對於專案或外掛程式根目錄的路徑參考 hook 指令碼，無論 hook 執行時的工作目錄如何：

512 512

513* `${CLAUDE_PROJECT_DIR}`：專案根目錄。Claude Code 也在 [stdio MCP 伺服器](/zh-TW/mcp#option-3-add-a-local-stdio-server) 和外掛程式 LSP 伺服器的環境中設定此變數。513* `${CLAUDE_PROJECT_DIR}`：專案根目錄。Claude Code 也在 [stdio MCP 伺服器](/docs/zh-TW/mcp#option-3-add-a-local-stdio-server) 和外掛程式 LSP 伺服器的環境中設定此變數。

514* `${CLAUDE_PLUGIN_ROOT}`：外掛程式的安裝目錄，用於與 [plugin](/zh-TW/plugins) 一起打包的指令碼。在每次外掛程式更新時變更。514* `${CLAUDE_PLUGIN_ROOT}`：外掛程式的安裝目錄，用於與 [plugin](/docs/zh-TW/plugins) 一起打包的指令碼。在每次外掛程式更新時變更。

515* `${CLAUDE_PLUGIN_DATA}`：外掛程式的 [持久資料目錄](/zh-TW/plugins-reference#persistent-data-directory)，用於應該在外掛程式更新後保留的依賴項和狀態。515* `${CLAUDE_PLUGIN_DATA}`：外掛程式的 [持久資料目錄](/docs/zh-TW/plugins-reference#persistent-data-directory)，用於應該在外掛程式更新後保留的依賴項和狀態。

516 516

517對於任何參考路徑佔位符的 hook，優先使用 [exec 形式](#exec-form-and-shell-form)。Exec 形式將每個 `args` 元素作為一個參數傳遞，不進行 shell 標記化，因此包含空格或特殊字元的路徑不需要引用。在 shell 形式中，用雙引號括起每個佔位符。517對於任何參考路徑佔位符的 hook，優先使用 [exec 形式](#exec-form-and-shell-form)。Exec 形式將每個 `args` 元素作為一個參數傳遞，不進行 shell 標記化，因此包含空格或特殊字元的路徑不需要引用。在 shell 形式中，用雙引號括起每個佔位符。

518 518

566 }566 }

567 ```567 ```

568 568

569 有關建立外掛程式 hooks 的詳細資訊，請參閱 [外掛程式元件參考](/zh-TW/plugins-reference#hooks)。569 有關建立外掛程式 hooks 的詳細資訊，請參閱 [外掛程式元件參考](/docs/zh-TW/plugins-reference#hooks)。

570 </Tab>570 </Tab>

571</Tabs>571</Tabs>

572 572

574 Skills 和代理中的 Hooks574 Skills 和代理中的 Hooks

575</h3>575</h3>

576 576

577除了設定檔和外掛程式外，hooks 還可以使用 frontmatter 直接在 [skills](/zh-TW/skills) 和 [subagents](/zh-TW/sub-agents) 中定義。這些 hooks 的範圍限於元件的生命週期，只有在該元件處於活動狀態時才執行。577除了設定檔和外掛程式外，hooks 還可以使用 frontmatter 直接在 [skills](/docs/zh-TW/skills) 和 [subagents](/docs/zh-TW/sub-agents) 中定義。這些 hooks 的範圍限於元件的生命週期，只有在該元件處於活動狀態時才執行。

578 578

579支援所有 hook 事件。對於 subagents，`Stop` hooks 會自動轉換為 `SubagentStop`，因為這是 subagent 完成時觸發的事件。579支援所有 hook 事件。對於 subagents，`Stop` hooks 會自動轉換為 `SubagentStop`，因為這是 subagent 完成時觸發的事件。

580 580

643| 欄位 | 描述 |643| 欄位 | 描述 |

644| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |644| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

646| `prompt_id` | UUID 識別目前正在處理的使用者提示。與 [OpenTelemetry 事件上的 `prompt.id` 屬性](/zh-TW/monitoring-usage#event-correlation-attributes) 相符，因此您可以將 hook 輸出與單一提示的遙測相關聯。在第一個使用者輸入之前不存在。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本 |646| `prompt_id` | UUID 識別目前正在處理的使用者提示。與 [OpenTelemetry 事件上的 `prompt.id` 屬性](/docs/zh-TW/monitoring-usage#event-correlation-attributes) 相符，因此您可以將 hook 輸出與單一提示的遙測相關聯。在第一個使用者輸入之前不存在。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本 |

647| `transcript_path` | 對話 JSON 的路徑。成績單檔案以非同步方式寫入，可能滯後於記憶體中的對話，因此當 hook 觸發時，它可能尚未包含目前回合的最新訊息。需要目前回合最後助手文字的 Hooks 應在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是讀取成績單 |647| `transcript_path` | 對話 JSON 的路徑。成績單檔案以非同步方式寫入，可能滯後於記憶體中的對話，因此當 hook 觸發時，它可能尚未包含目前回合的最新訊息。需要目前回合最後助手文字的 Hooks 應在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是讀取成績單 |

648| `cwd` | 叫用 hook 時的目前工作目錄 |648| `cwd` | 叫用 hook 時的目前工作目錄 |

649| `permission_mode` | 目前 [權限模式](/zh-TW/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。標記為**手動**的模式以 `"default"` 到達，永遠不會以 `"manual"` 到達，因此匹配 `"default"` 的指令碼繼續工作。並非所有事件都接收此欄位。檢查每個 [hook 事件](#hook-events) 部分中的 JSON 範例 |649| `permission_mode` | 目前 [權限模式](/docs/zh-TW/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。標記為**手動**的模式以 `"default"` 到達，永遠不會以 `"manual"` 到達，因此匹配 `"default"` 的指令碼繼續工作。並非所有事件都接收此欄位。檢查每個 [hook 事件](#hook-events) 部分中的 JSON 範例 |

650| `effort` | 物件，其 `level` 欄位保存該回合的活躍 [努力等級](/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果請求的模型努力等級超過目前模型支援的等級，這是模型實際使用的降級等級。Ultracode 不是一個不同的等級，報告為 `"xhigh"`。該物件與 [狀態行](/zh-TW/statusline#available-data) `effort` 欄位相符。存在於在工具使用上下文中觸發的事件，例如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`，當目前模型支援努力參數時。該等級也可作為 `$CLAUDE_EFFORT` 環境變數提供給 hook 命令和 Bash 工具。 |650| `effort` | 物件，其 `level` 欄位保存該回合的活躍 [努力等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果請求的模型努力等級超過目前模型支援的等級，這是模型實際使用的降級等級。Ultracode 不是一個不同的等級，報告為 `"xhigh"`。該物件與 [狀態行](/docs/zh-TW/statusline#available-data) `effort` 欄位相符。存在於在工具使用上下文中觸發的事件，例如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`，當目前模型支援努力參數時。該等級也可作為 `$CLAUDE_EFFORT` 環境變數提供給 hook 命令和 Bash 工具。 |

652 652

653使用 `--agent` 執行或在 subagent 內執行時，包括兩個額外欄位：653使用 `--agent` 執行或在 subagent 內執行時，包括兩個額外欄位：

655| 欄位 | 描述 |655| 欄位 | 描述 |

656| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |656| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

658| `agent_type` | 代理名稱（例如 `"Explore"` 或 `"security-reviewer"`）。當工作階段使用 `--agent` 或 hook 在 subagent 內觸發時出現。對於 subagents，subagent 的類型優先於工作階段的 `--agent` 值。對於 [自訂 subagents](/zh-TW/sub-agents)，這是代理 frontmatter 中的 `name` 欄位，而不是檔案名稱。對於由 [plugin](/zh-TW/plugins) 提供的 subagents，這是外掛範圍識別碼，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名稱。請參閱 [SubagentStart](#subagentstart) 以了解如何針對外掛範圍名稱編寫匹配器。 |658| `agent_type` | 代理名稱（例如 `"Explore"` 或 `"security-reviewer"`）。當工作階段使用 `--agent` 或 hook 在 subagent 內觸發時出現。對於 subagents，subagent 的類型優先於工作階段的 `--agent` 值。對於 [自訂 subagents](/docs/zh-TW/sub-agents)，這是代理 frontmatter 中的 `name` 欄位，而不是檔案名稱。對於由 [plugin](/docs/zh-TW/plugins) 提供的 subagents，這是外掛範圍識別碼，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名稱。請參閱 [SubagentStart](#subagentstart) 以了解如何針對外掛範圍名稱編寫匹配器。 |

659 659

660只有 [`SessionStart`](#sessionstart) hooks 可以接收 `model` 欄位，且不保證存在。沒有 `$CLAUDE_MODEL` 環境變數。Hook 程序繼承父環境，因此如果您在 shell 中設定它，它可以讀取 `$ANTHROPIC_MODEL`，但當您在工作階段期間使用 `/model` 切換模型時，該值不會改變。一組變數不被繼承：Claude Code [從它產生的每個子程序中移除 `OTEL_*` 匯出器變數](/zh-TW/monitoring-usage#administrator-configuration)，包括 hooks。660只有 [`SessionStart`](#sessionstart) hooks 可以接收 `model` 欄位，且不保證存在。沒有 `$CLAUDE_MODEL` 環境變數。Hook 程序繼承父環境，因此如果您在 shell 中設定它，它可以讀取 `$ANTHROPIC_MODEL`，但當您在工作階段期間使用 `/model` 切換模型時，該值不會改變。一組變數不被繼承：Claude Code [從它產生的每個子程序中移除 `OTEL_*` 匯出器變數](/docs/zh-TW/monitoring-usage#administrator-configuration)，包括 hooks。

661 661

662例如，Bash 命令的 `PreToolUse` hook 在 stdin 上接收此內容：662例如，Bash 命令的 `PreToolUse` hook 在 stdin 上接收此內容：

663 663

776 您必須為每個 hook 選擇一種方法，而不是兩種：要麼單獨使用退出代碼進行信號傳遞，要麼以 0 退出並列印 JSON 以進行結構化控制。Claude Code 僅在退出 0 時處理 JSON。如果您退出 2，任何 JSON 都會被忽略。776 您必須為每個 hook 選擇一種方法，而不是兩種：要麼單獨使用退出代碼進行信號傳遞，要麼以 0 退出並列印 JSON 以進行結構化控制。Claude Code 僅在退出 0 時處理 JSON。如果您退出 2，任何 JSON 都會被忽略。

777</Note>777</Note>

778 778

779您的 hook 的 stdout 必須僅包含 JSON 物件。如果您的 shell 設定檔在啟動時列印文字，它可能會干擾 JSON 解析。請參閱故障排除指南中的 [JSON 驗證失敗](/zh-TW/hooks-guide#json-validation-failed)。779您的 hook 的 stdout 必須僅包含 JSON 物件。如果您的 shell 設定檔在啟動時列印文字，它可能會干擾 JSON 解析。請參閱故障排除指南中的 [JSON 驗證失敗](/docs/zh-TW/hooks-guide#json-validation-failed)。

780 780

781Hook 輸出字串，包括 `additionalContext`、`systemMessage` 和純 stdout，上限為 10,000 個字元。超過此限制的輸出會儲存到檔案並替換為預覽和檔案路徑，與大型工具結果的處理方式相同。781Hook 輸出字串，包括 `additionalContext`、`systemMessage` 和純 stdout，上限為 10,000 個字元。超過此限制的輸出會儲存到檔案並替換為預覽和檔案路徑，與大型工具結果的處理方式相同。

782 782

868* **條件專案規則**：哪個測試命令適用於剛編輯的檔案，此 worktree 中哪些目錄是唯讀的868* **條件專案規則**：哪個測試命令適用於剛編輯的檔案，此 worktree 中哪些目錄是唯讀的

869* **外部資料**：分配給您的開放問題、最近的 CI 結果、從內部服務擷取的內容869* **外部資料**：分配給您的開放問題、最近的 CI 結果、從內部服務擷取的內容

870 870

871對於永遠不會改變的指示，優先使用 [CLAUDE.md](/zh-TW/memory)。它無需執行指令碼即可載入，是靜態專案約定的標準位置。871對於永遠不會改變的指示，優先使用 [CLAUDE.md](/docs/zh-TW/memory)。它無需執行指令碼即可載入，是靜態專案約定的標準位置。

872 872

873將文字寫成事實陳述，而不是命令式系統指示。「部署目標是生產」或「此儲存庫使用 `bun test`」之類的措辭讀起來像專案資訊。框架為帶外系統命令的文字可能會觸發 Claude 的提示注入防禦，這會導致 Claude 將文字呈現給您，而不是將其視為上下文。873將文字寫成事實陳述，而不是命令式系統指示。「部署目標是生產」或「此儲存庫使用 `bun test`」之類的措辭讀起來像專案資訊。框架為帶外系統命令的文字可能會觸發 Claude 的提示注入防禦，這會導致 Claude 將文字呈現給您，而不是將其視為上下文。

874 874

950 </Tab>950 </Tab>

951</Tabs>951</Tabs>

952 952

953有關擴展範例，包括 Bash 命令驗證、提示篩選和自動批准指令碼，請參閱指南中的 [您可以自動化的內容](/zh-TW/hooks-guide#what-you-can-automate) 和 [Bash 命令驗證器參考實現](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)。953有關擴展範例，包括 Bash 命令驗證、提示篩選和自動批准指令碼，請參閱指南中的 [您可以自動化的內容](/docs/zh-TW/hooks-guide#what-you-can-automate) 和 [Bash 命令驗證器參考實現](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)。

954 954

955<h2 id="hook-events">955<h2 id="hook-events">

956 Hook 事件956 Hook 事件

962 SessionStart962 SessionStart

963</h3>963</h3>

964 964

965在 Claude Code 啟動新工作階段或恢復現有工作階段時執行。適用於載入開發上下文，例如現有問題或程式碼庫的最近變更，或設定環境變數。對於不需要指令碼的靜態上下文，請改用 [CLAUDE.md](/zh-TW/memory)。965在 Claude Code 啟動新工作階段或恢復現有工作階段時執行。適用於載入開發上下文，例如現有問題或程式碼庫的最近變更，或設定環境變數。對於不需要指令碼的靜態上下文，請改用 [CLAUDE.md](/docs/zh-TW/memory)。

966 966

967SessionStart 在每個工作階段執行，因此請保持這些 hooks 快速。僅支援 `type: "command"` 和 `type: "mcp_tool"` hooks。967SessionStart 在每個工作階段執行，因此請保持這些 hooks 快速。僅支援 `type: "command"` 和 `type: "mcp_tool"` hooks。

968 968

1008| 欄位 | 描述 |1008| 欄位 | 描述 |

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

1011| `initialUserMessage` | 用作工作階段第一個使用者訊息的字串。適用於 [非互動模式](/zh-TW/headless)（`-p`），其中即使未提供提示，它也成為第一個轉向。如果提供了提示，它作為下一個轉向跟隨。與 `additionalContext` 不同，後者附加到現有轉向，這會建立轉向 |1011| `initialUserMessage` | 用作工作階段第一個使用者訊息的字串。適用於 [非互動模式](/docs/zh-TW/headless)（`-p`），其中即使未提供提示，它也成為第一個轉向。如果提供了提示，它作為下一個轉向跟隨。與 `additionalContext` 不同，後者附加到現有轉向，這會建立轉向 |

1012| `sessionTitle` | 設定工作階段標題，與 `/rename` 的效果相同。使用此項根據啟動資料夾、git 分支或 worktree 名稱自動命名工作階段。僅在 `source` 為 `"startup"` 或 `"resume"` 時適用；在 `"clear"` 和 `"compact"` 上被忽略 |1012| `sessionTitle` | 設定工作階段標題，與 `/rename` 的效果相同。使用此項根據啟動資料夾、git 分支或 worktree 名稱自動命名工作階段。僅在 `source` 為 `"startup"` 或 `"resume"` 時適用；在 `"clear"` 和 `"compact"` 上被忽略 |

1014| `reloadSkills` | 布林值。當為 `true` 時，Claude Code 在 SessionStart hooks 完成後重新掃描 [skill](/zh-TW/skills) 和命令目錄，因此 hook 安裝的 skills 在同一工作階段中可用，從第一個提示開始 |1014| `reloadSkills` | 布林值。當為 `true` 時，Claude Code 在 SessionStart hooks 完成後重新掃描 [skill](/docs/zh-TW/skills) 和命令目錄，因此 hook 安裝的 skills 在同一工作階段中可用，從第一個提示開始 |

1015 1015

1016```json theme={null}1016```json theme={null}

1017{1017{

1096 1096

1097`--init-only` 執行 Setup hooks 和 SessionStart hooks（帶有 `startup` 匹配器），然後退出而不啟動對話。`--init` 和 `--maintenance` 僅在與 `-p` 結合時觸發 Setup hooks；在互動式工作階段中，這兩個標誌目前不觸發 Setup hooks。1097`--init-only` 執行 Setup hooks 和 SessionStart hooks（帶有 `startup` 匹配器），然後退出而不啟動對話。`--init` 和 `--maintenance` 僅在與 `-p` 結合時觸發 Setup hooks；在互動式工作階段中，這兩個標誌目前不觸發 Setup hooks。

1098 1098

1099因為 Setup 不在每次啟動時觸發，需要安裝依賴項的外掛程式無法僅依賴 Setup。實際的模式是在首次使用時檢查依賴項，如果缺失則安裝，例如測試 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在則執行 `npm install`。請參閱 [持久資料目錄](/zh-TW/plugins-reference#persistent-data-directory) 以了解在何處儲存已安裝的依賴項。1099因為 Setup 不在每次啟動時觸發，需要安裝依賴項的外掛程式無法僅依賴 Setup。實際的模式是在首次使用時檢查依賴項，如果缺失則安裝，例如測試 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在則執行 `npm install`。請參閱 [持久資料目錄](/docs/zh-TW/plugins-reference#persistent-data-directory) 以了解在何處儲存已安裝的依賴項。

1100 1100

1101<h4 id="setup-input">1101<h4 id="setup-input">

1102 Setup 輸入1102 Setup 輸入

1118 Setup 決定控制1118 Setup 決定控制

1119</h4>1119</h4>

1120 1120

1121Setup hooks 無法阻止。任何非零退出代碼（包括 2）都會向使用者顯示 stderr 作為 `<hook name> hook error` 通知，執行繼續。在 [非互動模式](/zh-TW/headless) 中，hook 輸出僅在您使用 `--verbose` 啟動時出現。1121Setup hooks 無法阻止。任何非零退出代碼（包括 2）都會向使用者顯示 stderr 作為 `<hook name> hook error` 通知，執行繼續。在 [非互動模式](/docs/zh-TW/headless) 中，hook 輸出僅在您使用 `--verbose` 啟動時出現。

1122 1122

1123要將資訊傳遞到 Claude 的上下文中，請在 JSON 輸出中返回 `additionalContext`；純 stdout 僅寫入偵錯日誌。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您還可以返回這些事件特定欄位：1123要將資訊傳遞到 Claude 的上下文中，請在 JSON 輸出中返回 `additionalContext`；純 stdout 僅寫入偵錯日誌。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您還可以返回這些事件特定欄位：

1124 1124

1188 1188

1189達到逾時的 `UserPromptSubmit` hook 被取消，其輸出（包括任何 `additionalContext`）被丟棄。提示仍然到達 Claude，但沒有該上下文。從 v2.1.196 開始，成績單顯示一個通知，命名 hook、觸發的逾時以及輸出被丟棄。較早的版本取消 hook 而不顯示通知。1189達到逾時的 `UserPromptSubmit` hook 被取消，其輸出（包括任何 `additionalContext`）被丟棄。提示仍然到達 Claude，但沒有該上下文。從 v2.1.196 開始，成績單顯示一個通知，命名 hook、觸發的逾時以及輸出被丟棄。較早的版本取消 hook 而不顯示通知。

1190 1190

1191[Agent SDK callback hook](/zh-TW/agent-sdk/hooks) 在 `UserPromptSubmit` 上達到逾時會阻止提示，並顯示命名 hook 和逾時的訊息，因為該處的 callback 可能充當必須不失敗開放的原則閘道。工作階段繼續。在 v2.1.208 之前，callback 在該事件上的逾時以執行錯誤結束轉向。1191[Agent SDK callback hook](/docs/zh-TW/agent-sdk/hooks) 在 `UserPromptSubmit` 上達到逾時會阻止提示，並顯示命名 hook 和逾時的訊息，因為該處的 callback 可能充當必須不失敗開放的原則閘道。工作階段繼續。在 v2.1.208 之前，callback 在該事件上的逾時以執行錯誤結束轉向。

1192 1192

1193<h4 id="userpromptsubmit-input">1193<h4 id="userpromptsubmit-input">

1194 UserPromptSubmit 輸入1194 UserPromptSubmit 輸入

1443在 Claude 建立工具參數後和處理工具呼叫之前執行。匹配工具名稱：`Bash`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`WebFetch`、`WebSearch`、`AskUserQuestion`、`ExitPlanMode` 和任何 [MCP 工具名稱](#match-mcp-tools)。1443在 Claude 建立工具參數後和處理工具呼叫之前執行。匹配工具名稱：`Bash`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`WebFetch`、`WebSearch`、`AskUserQuestion`、`ExitPlanMode` 和任何 [MCP 工具名稱](#match-mcp-tools)。

1444 1444

1445<Warning>1445<Warning>

1446 PreToolUse 僅在 Claude 呼叫工具時執行。您 [在提示中使用 `@` 參考的檔案](/zh-TW/common-workflows#reference-files-and-directories) 被新增而不進行任何工具呼叫：Claude Code 在建立提示時插入其內容，因此沒有 PreToolUse hook 針對它們觸發，包括匹配 `Read` 的 hooks。要阻止特定路徑的 `@` 參考，請改用 [`Read` 拒絕規則](/zh-TW/permissions#read-and-edit)。1446 PreToolUse 僅在 Claude 呼叫工具時執行。您 [在提示中使用 `@` 參考的檔案](/docs/zh-TW/common-workflows#reference-files-and-directories) 被新增而不進行任何工具呼叫：Claude Code 在建立提示時插入其內容，因此沒有 PreToolUse hook 針對它們觸發，包括匹配 `Read` 的 hooks。要阻止特定路徑的 `@` 參考，請改用 [`Read` 拒絕規則](/docs/zh-TW/permissions#read-and-edit)。

1447</Warning>1447</Warning>

1448 1448

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

1464| :------------------ | :-- | :----------------- | :----------------------------------------------------------------------------- |1464| :------------------ | :-- | :----------------- | :----------------------------------------------------------------------------- |

1467| `timeout` | 數字 | `120000` | 可選逾時（毫秒）。超過 [最大值](/zh-TW/tools-reference#bash-tool-behavior) 的值會被減少到最大值，而不是被拒絕 |1467| `timeout` | 數字 | `120000` | 可選逾時（毫秒）。超過 [最大值](/docs/zh-TW/tools-reference#bash-tool-behavior) 的值會被減少到最大值，而不是被拒絕 |

1469 1469

1470<h5 id="write">1470<h5 id="write">

1556 Agent1556 Agent

1557</h5>1557</h5>

1558 1558

1559生成一個 [subagent](/zh-TW/sub-agents)。1559生成一個 [subagent](/docs/zh-TW/sub-agents)。

1560 1560

1561| 欄位 | 類型 | 範例 | 描述 |1561| 欄位 | 類型 | 範例 | 描述 |

1562| :-------------- | :- | :------------------------- | :------------ |1562| :-------------- | :- | :------------------------- | :------------ |

1599 ExitPlanMode1599 ExitPlanMode

1600</h5>1600</h5>

1601 1601

1602呈現一個計劃並要求使用者在 Claude 離開 [plan mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在呼叫工具之前將計劃寫入磁碟上的檔案，因此模型的字面 `tool_input` 通常為空。Claude Code 在將輸入傳遞給 hooks 之前注入計劃內容和檔案路徑。1602呈現一個計劃並要求使用者在 Claude 離開 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在呼叫工具之前將計劃寫入磁碟上的檔案，因此模型的字面 `tool_input` 通常為空。Claude Code 在將輸入傳遞給 hooks 之前注入計劃內容和檔案路徑。

1603 1603

1604| 欄位 | 類型 | 範例 | 描述 |1604| 欄位 | 類型 | 範例 | 描述 |

1605| :--------------- | :- | :------------------------------------------ | :-------------------------------------------------------------------------------------------- |1605| :--------------- | :- | :------------------------------------------ | :-------------------------------------------------------------------------------------------- |

1617 1617

1618| 欄位 | 描述 |1618| 欄位 | 描述 |

1619| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1619| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1620| `permissionDecision` | `"allow"` 跳過權限提示，除了 [需要使用者互動的工具](#pretooluse-decision-control) 和連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)。`"deny"` 防止工具呼叫。`"ask"` 提示使用者確認。`"defer"` 優雅地退出，以便稍後可以恢復工具。[拒絕和詢問規則](/zh-TW/permissions#manage-permissions) 仍然適用，無論 hook 返回什麼 |1620| `permissionDecision` | `"allow"` 跳過權限提示，除了 [需要使用者互動的工具](#pretooluse-decision-control) 和連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)。`"deny"` 防止工具呼叫。`"ask"` 提示使用者確認。`"defer"` 優雅地退出，以便稍後可以恢復工具。[拒絕和詢問規則](/docs/zh-TW/permissions#manage-permissions) 仍然適用，無論 hook 返回什麼 |

1622| `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此包括未修改的欄位以及修改後的欄位。與 `"allow"` 結合以自動批准，或與 `"ask"` 結合以向使用者顯示修改後的輸入。對於 `"defer"`，被忽略 |1622| `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此包括未修改的欄位以及修改後的欄位。與 `"allow"` 結合以自動批准，或與 `"ask"` 結合以向使用者顯示修改後的輸入。對於 `"defer"`，被忽略 |

1640}1640}

1641```1641```

1642 1642

1643`AskUserQuestion` 和 `ExitPlanMode` 需要使用者互動，通常在 [非互動模式](/zh-TW/headless) 中使用 `-p` 標誌時阻止。返回 `permissionDecision: "allow"` 以及 `updatedInput` 滿足該要求：hook 從 stdin 讀取工具的輸入，通過您自己的 UI 收集答案，並在 `updatedInput` 中返回它，以便工具執行而不提示。僅返回 `"allow"` 對這些工具不夠。對於 `AskUserQuestion`，回顯原始 `questions` 陣列並新增一個 [`answers`](#askuserquestion) 物件，將每個問題的文字對應到選定的答案。1643`AskUserQuestion` 和 `ExitPlanMode` 需要使用者互動，通常在 [非互動模式](/docs/zh-TW/headless) 中使用 `-p` 標誌時阻止。返回 `permissionDecision: "allow"` 以及 `updatedInput` 滿足該要求：hook 從 stdin 讀取工具的輸入，通過您自己的 UI 收集答案，並在 `updatedInput` 中返回它，以便工具執行而不提示。僅返回 `"allow"` 對這些工具不夠。對於 `AskUserQuestion`，回顯原始 `questions` 陣列並新增一個 [`answers`](#askuserquestion) 物件，將每個問題的文字對應到選定的答案。

1644 1644

1645連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 即使 hook 返回 `"allow"` 也會提示。1645連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 即使 hook 返回 `"allow"` 也會提示。

1646 1646

1647從 v2.1.199 開始，一個 MCP 工具，其伺服器使用 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool) 標記它，更嚴格：hook 無法使用 `"allow"` 跳過其批准提示，無論是否有 `updatedInput`，因為 Claude Code 無法確認 hook 收集了工具需要的互動。1647從 v2.1.199 開始，一個 MCP 工具，其伺服器使用 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 標記它，更嚴格：hook 無法使用 `"allow"` 跳過其批准提示，無論是否有 `updatedInput`，因為 Claude Code 無法確認 hook 收集了工具需要的互動。

1648 1648

1649<Note>1649<Note>

1650 PreToolUse 之前使用頂層 `decision` 和 `reason` 欄位，但這些對此事件已棄用。改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。棄用的值 `"approve"` 和 `"block"` 對應於 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件繼續使用頂層 `decision` 和 `reason` 作為其目前格式。1650 PreToolUse 之前使用頂層 `decision` 和 `reason` 欄位，但這些對此事件已棄用。改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。棄用的值 `"approve"` 和 `"block"` 對應於 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件繼續使用頂層 `decision` 和 `reason` 作為其目前格式。

1654 延遲工具呼叫以供稍後使用1654 延遲工具呼叫以供稍後使用

1655</h4>1655</h4>

1656 1656

1657`"defer"` 用於執行 `claude -p` 作為子程序並讀取其 JSON 輸出的整合，例如 Agent SDK 應用程式或建立在 Claude Code 之上的自訂 UI。它讓該呼叫程序在工具呼叫處暫停 Claude，通過其自己的介面收集輸入，並從中斷處恢復。Claude Code 僅在 [非互動模式](/zh-TW/headless) 中使用 `-p` 標誌時遵守此值。在互動式工作階段中，它記錄警告並忽略 hook 結果。1657`"defer"` 用於執行 `claude -p` 作為子程序並讀取其 JSON 輸出的整合，例如 Agent SDK 應用程式或建立在 Claude Code 之上的自訂 UI。它讓該呼叫程序在工具呼叫處暫停 Claude，通過其自己的介面收集輸入，並從中斷處恢復。Claude Code 僅在 [非互動模式](/docs/zh-TW/headless) 中使用 `-p` 標誌時遵守此值。在互動式工作階段中，它記錄警告並忽略 hook 結果。

1658 1658

1659`AskUserQuestion` 工具是典型情況：Claude 想要詢問使用者某些事情，但沒有終端來回答。往返工作如下：1659`AskUserQuestion` 工具是典型情況：Claude 想要詢問使用者某些事情，但沒有終端來回答。往返工作如下：

1660 1660

1680}1680}

1681```1681```

1682 1682

1683沒有逾時或重試限制。工作階段保留在磁碟上，直到您恢復它，受到 [`cleanupPeriodDays`](/zh-TW/settings#available-settings) 保留掃描的約束，該掃描在預設 30 天後刪除工作階段檔案。如果恢復時答案還沒有準備好，hook 可以再次返回 `"defer"`，程序以相同的方式退出。呼叫程序控制何時通過最終返回 `"allow"` 或 `"deny"` 從 hook 中斷迴圈。1683沒有逾時或重試限制。工作階段保留在磁碟上，直到您恢復它，受到 [`cleanupPeriodDays`](/docs/zh-TW/settings#available-settings) 保留掃描的約束，該掃描在預設 30 天後刪除工作階段檔案。如果恢復時答案還沒有準備好，hook 可以再次返回 `"defer"`，程序以相同的方式退出。呼叫程序控制何時通過最終返回 `"allow"` 或 `"deny"` 從 hook 中斷迴圈。

1684 1684

1685`"defer"` 僅在 Claude 在轉向中進行單一工具呼叫時有效。如果 Claude 一次進行多個工具呼叫，`"defer"` 會被忽略並顯示警告，工具通過正常權限流程進行。該限制存在是因為恢復只能重新執行一個工具：沒有辦法延遲一個呼叫而不留下其他呼叫未解決。1685`"defer"` 僅在 Claude 在轉向中進行單一工具呼叫時有效。如果 Claude 一次進行多個工具呼叫，`"defer"` 會被忽略並顯示警告，工具通過正常權限流程進行。該限制存在是因為恢復只能重新執行一個工具：沒有辦法延遲一個呼叫而不留下其他呼叫未解決。

1686 1686

1735 1735

1736| 欄位 | 描述 |1736| 欄位 | 描述 |

1737| :------------------- | :------------------------------------------------------------------------------------------------------------------ |1737| :------------------- | :------------------------------------------------------------------------------------------------------------------ |

1738| `behavior` | `"allow"` 授予權限，`"deny"` 拒絕它。[拒絕和詢問規則](/zh-TW/permissions#manage-permissions) 仍然適用，所以返回 `"allow"` 的 hook 不會覆蓋匹配的拒絕規則 |1738| `behavior` | `"allow"` 授予權限，`"deny"` 拒絕它。[拒絕和詢問規則](/docs/zh-TW/permissions#manage-permissions) 仍然適用，所以返回 `"allow"` 的 hook 不會覆蓋匹配的拒絕規則 |

1772 1772

1773<Note>1773<Note>

1774 `setMode` 與 `bypassPermissions` 僅在工作階段已經啟用繞過模式時生效：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或 `permissions.defaultMode: "bypassPermissions"` 在設定中，且模式未被 [`permissions.disableBypassPermissionsMode`](/zh-TW/permissions#managed-settings) 停用。否則更新是無操作。`bypassPermissions` 無論 `destination` 如何都永遠不會被持久化為 `defaultMode`。1774 `setMode` 與 `bypassPermissions` 僅在工作階段已經啟用繞過模式時生效：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或 `permissions.defaultMode: "bypassPermissions"` 在設定中，且模式未被 [`permissions.disableBypassPermissionsMode`](/docs/zh-TW/permissions#managed-settings) 停用。否則更新是無操作。`bypassPermissions` 無論 `destination` 如何都永遠不會被持久化為 `defaultMode`。

1775</Note>1775</Note>

1776 1776

1777每個項目上的 `destination` 欄位決定變更是保留在記憶體中還是持久化到設定檔。1777每個項目上的 `destination` 欄位決定變更是保留在記憶體中還是持久化到設定檔。

1990 PermissionDenied1990 PermissionDenied

1991</h3>1991</h3>

1992 1992

1993當 [自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器拒絕工具呼叫時執行。此 hook 僅在自動模式中觸發：當您手動拒絕權限對話框、當 `PreToolUse` hook 阻止呼叫或當 `deny` 規則匹配時，它不執行。使用它來記錄分類器拒絕、調整配置或告訴模型它可能重試工具呼叫。1993當 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器拒絕工具呼叫時執行。此 hook 僅在自動模式中觸發：當您手動拒絕權限對話框、當 `PreToolUse` hook 阻止呼叫或當 `deny` 規則匹配時，它不執行。使用它來記錄分類器拒絕、調整配置或告訴模型它可能重試工具呼叫。

1994 1994

1995匹配工具名稱，與 PreToolUse 相同的值。1995匹配工具名稱，與 PreToolUse 相同的值。

1996 1996

2057 2057

2058`agent_needs_input` 和 `agent_completed` 類型需要 Claude Code v2.1.198 或更高版本。2058`agent_needs_input` 和 `agent_completed` 類型需要 Claude Code v2.1.198 或更高版本。

2059 2059

2110 SubagentStart2110 SubagentStart

2111</h3>2111</h3>

2112 2112

2113當通過 Agent 工具生成 Claude Code subagent 時執行。支援匹配器以按代理類型名稱篩選。對於內建代理，這是代理名稱，如 `general-purpose`、`Explore` 或 `Plan`。對於 [自訂 subagents](/zh-TW/sub-agents)，這是代理 frontmatter 中的 `name` 欄位，而不是檔案名稱。2113當通過 Agent 工具生成 Claude Code subagent 時執行。支援匹配器以按代理類型名稱篩選。對於內建代理，這是代理名稱，如 `general-purpose`、`Explore` 或 `Plan`。對於 [自訂 subagents](/docs/zh-TW/sub-agents)，這是代理 frontmatter 中的 `name` 欄位，而不是檔案名稱。

2114 2114

2115對於由 [plugin](/zh-TW/plugins) 提供的 subagents，代理類型是外掛程式範圍的識別碼，例如 `my-plugin:reviewer`，而不是裸露的 frontmatter 名稱。冒號將外掛程式範圍的名稱放在正規表達式路徑上，因此使用 `^` 和 `$` 錨定匹配器以進行精確匹配：`^my-plugin:reviewer$`。2115對於由 [plugin](/docs/zh-TW/plugins) 提供的 subagents，代理類型是外掛程式範圍的識別碼，例如 `my-plugin:reviewer`，而不是裸露的 frontmatter 名稱。冒號將外掛程式範圍的名稱放在正規表達式路徑上，因此使用 `^` 和 `$` 錨定匹配器以進行精確匹配：`^my-plugin:reviewer$`。

2116 2116

2117<h4 id="subagentstart-input">2117<h4 id="subagentstart-input">

2118 SubagentStart 輸入2118 SubagentStart 輸入

2244 TaskCompleted2244 TaskCompleted

2245</h3>2245</h3>

2246 2246

2247當任務被標記為已完成時執行。這在兩種情況下觸發：當任何代理通過 TaskUpdate 工具明確標記任務為已完成時，或當 [agent team](/zh-TW/agent-teams) 隊友完成其輪次並有進行中的任務時。使用此項來強制執行完成條件，例如通過測試或 lint 檢查，然後任務才能關閉。2247當任務被標記為已完成時執行。這在兩種情況下觸發：當任何代理通過 TaskUpdate 工具明確標記任務為已完成時，或當 [agent team](/docs/zh-TW/agent-teams) 隊友完成其輪次並有進行中的任務時。使用此項來強制執行完成條件，例如通過測試或 lint 檢查，然後任務才能關閉。

2248 2248

2249當 `TaskCompleted` hook 以代碼 2 退出時，任務不被標記為已完成，stderr 訊息被反饋給模型作為反饋。要完全停止隊友而不是重新執行它，請返回 JSON，其中 `{"continue": false, "stopReason": "..."}`。TaskCompleted hooks 不支援匹配器，在每次出現時觸發。2249當 `TaskCompleted` hook 以代碼 2 退出時，任務不被標記為已完成，stderr 訊息被反饋給模型作為反饋。要完全停止隊友而不是重新執行它，請返回 JSON，其中 `{"continue": false, "stopReason": "..."}`。TaskCompleted hooks 不支援匹配器，在每次出現時觸發。

2250 2250

2309當主 Claude Code 代理完成回應時執行。如果停止是由於使用者中斷，則不執行。API 錯誤會觸發 [StopFailure](#stopfailure)。2309當主 Claude Code 代理完成回應時執行。如果停止是由於使用者中斷，則不執行。API 錯誤會觸發 [StopFailure](#stopfailure)。

2310 2310

2311<Tip>2311<Tip>

2312 [`/goal`](/zh-TW/goal) 命令是工作階段範圍提示型 Stop hook 的內建快捷方式。當您想要 Claude 繼續工作直到條件成立而不編寫 hook 配置時，請使用它。2312 [`/goal`](/docs/zh-TW/goal) 命令是工作階段範圍提示型 Stop hook 的內建快捷方式。當您想要 Claude 繼續工作直到條件成立而不編寫 hook 配置時，請使用它。

2313</Tip>2313</Tip>

2314 2314

2315<h4 id="stop-input">2315<h4 id="stop-input">

2442 TeammateIdle2442 TeammateIdle

2443</h3>2443</h3>

2444 2444

2445當 [agent team](/zh-TW/agent-teams) 隊友在完成其輪次後即將閒置時執行。使用此項來在隊友停止工作之前強制執行品質閘道，例如要求通過 lint 檢查或驗證輸出檔案存在。2445當 [agent team](/docs/zh-TW/agent-teams) 隊友在完成其輪次後即將閒置時執行。使用此項來在隊友停止工作之前強制執行品質閘道，例如要求通過 lint 檢查或驗證輸出檔案存在。

2446 2446

2447當 `TeammateIdle` hook 以代碼 2 退出時，隊友會收到 stderr 訊息作為反饋，並繼續工作而不是閒置。要完全停止隊友而不是重新執行它，請返回 JSON，其中 `{"continue": false, "stopReason": "..."}`。TeammateIdle hooks 不支援匹配器，在每次出現時觸發。2447當 `TeammateIdle` hook 以代碼 2 退出時，隊友會收到 stderr 訊息作為反饋，並繼續工作而不是閒置。要完全停止隊友而不是重新執行它，請返回 JSON，其中 `{"continue": false, "stopReason": "..."}`。TeammateIdle hooks 不支援匹配器，在每次出現時觸發。

2448 2448

2656 WorktreeCreate2656 WorktreeCreate

2657</h3>2657</h3>

2658 2658

2659當您執行 `claude --worktree` 或 [subagent 使用 `isolation: "worktree"`](/zh-TW/sub-agents#choose-the-subagent-scope) 時，Claude Code 使用 `git worktree` 建立隔離的工作副本。如果您配置 WorktreeCreate hook，它會替換預設的 git 行為，讓您使用不同的版本控制系統，如 SVN、Perforce 或 Mercurial。2659當您執行 `claude --worktree` 或 [subagent 使用 `isolation: "worktree"`](/docs/zh-TW/sub-agents#choose-the-subagent-scope) 時，Claude Code 使用 `git worktree` 建立隔離的工作副本。如果您配置 WorktreeCreate hook，它會替換預設的 git 行為，讓您使用不同的版本控制系統，如 SVN、Perforce 或 Mercurial。

2660 2660

2661因為 hook 完全替換預設行為，[`.worktreeinclude`](/zh-TW/worktrees#copy-gitignored-files-into-worktrees) 不被處理。如果您需要將本機配置檔案（如 `.env`）複製到新 worktree，請在您的 hook 指令碼內執行。2661因為 hook 完全替換預設行為，[`.worktreeinclude`](/docs/zh-TW/worktrees#copy-gitignored-files-into-worktrees) 不被處理。如果您需要將本機配置檔案（如 `.env`）複製到新 worktree，請在您的 hook 指令碼內執行。

2662 2662

2663Hook 必須返回建立的 worktree 目錄的絕對路徑。Claude Code 使用此路徑作為隔離工作階段的工作目錄。請參閱 [WorktreeCreate 輸出](#worktreecreate-output) 以了解每個 hook 類型如何返回路徑。2663Hook 必須返回建立的 worktree 目錄的絕對路徑。Claude Code 使用此路徑作為隔離工作階段的工作目錄。請參閱 [WorktreeCreate 輸出](#worktreecreate-output) 以了解每個 hook 類型如何返回路徑。

2664 2664

3109 在停止前檢查多個條件3109 在停止前檢查多個條件

3110</h3>3110</h3>

3111 3111

3112此 `Stop` hook 使用詳細提示在允許 Claude 停止之前檢查三個條件。`SubagentStop` hooks 使用相同的格式來評估 [subagent](/zh-TW/sub-agents) 是否應該停止。如果 `"ok"` 為 `false`，Claude 繼續工作，提供的原因作為其下一個指令：3112此 `Stop` hook 使用詳細提示在允許 Claude 停止之前檢查三個條件。`SubagentStop` hooks 使用相同的格式來評估 [subagent](/docs/zh-TW/sub-agents) 是否應該停止。如果 `"ok"` 為 `false`，Claude 繼續工作，提供的原因作為其下一個指令：

3113 3113

3114```json theme={null}3114```json theme={null}

3115{3115{

3382 3382

3383有關更細粒度的 hook 匹配詳細資訊，設定 `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` 以查看額外的日誌行，例如 hook 匹配器計數和查詢匹配。3383有關更細粒度的 hook 匹配詳細資訊，設定 `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` 以查看額外的日誌行，例如 hook 匹配器計數和查詢匹配。

3384 3384

3385有關故障排除常見問題，如 hooks 不觸發、Stop hooks 持續阻擋或配置錯誤，請參閱指南中的 [限制和故障排除](/zh-TW/hooks-guide#limitations-and-troubleshooting)。有關涵蓋 `/context`、`/doctor` 和設定優先順序的更廣泛診斷逐步解說，請參閱 [偵錯您的配置](/zh-TW/debug-your-config)。3385有關故障排除常見問題，如 hooks 不觸發、Stop hooks 持續阻擋或配置錯誤，請參閱指南中的 [限制和故障排除](/docs/zh-TW/hooks-guide#limitations-and-troubleshooting)。有關涵蓋 `/context`、`/doctor` 和設定優先順序的更廣泛診斷逐步解說，請參閱 [偵錯您的配置](/docs/zh-TW/debug-your-config)。

hooks-guide.md +50 −50

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](/zh-TW/skills)以提供 Claude 額外的指令和可執行命令、[subagents](/zh-TW/sub-agents)以在隔離的上下文中執行任務，以及[plugins](/zh-TW/plugins)以打包要在專案間共享的擴展。13有關擴展 Claude Code 的其他方式，請參閱[skills](/docs/zh-TW/skills)以提供 Claude 額外的指令和可執行命令、[subagents](/docs/zh-TW/sub-agents)以在隔離的上下文中執行任務，以及[plugins](/docs/zh-TW/plugins)以打包要在專案間共享的擴展。

14 14

15<Tip>15<Tip>

16 本指南涵蓋常見用例和入門方式。有關完整的事件架構、JSON 輸入/輸出格式和非同步 hooks 和 MCP 工具 hooks 等進階功能，請參閱 [Hooks 參考](/zh-TW/hooks)。16 本指南涵蓋常見用例和入門方式。有關完整的事件架構、JSON 輸入/輸出格式和非同步 hooks 和 MCP 工具 hooks 等進階功能，請參閱 [Hooks 參考](/docs/zh-TW/hooks)。

17</Tip>17</Tip>

18 18

19<h2 id="set-up-your-first-hook">19<h2 id="set-up-your-first-hook">

85 您可以自動化的內容85 您可以自動化的內容

86</h2>86</h2>

87 87

88Hooks 讓您在 Claude Code 生命週期的關鍵點執行程式碼：編輯後格式化檔案、在執行前阻止命令、當 Claude 需要輸入時發送通知、在工作階段開始時注入上下文等。有關 hook 事件的完整列表，請參閱 [Hooks 參考](/zh-TW/hooks#hook-lifecycle)。88Hooks 讓您在 Claude Code 生命週期的關鍵點執行程式碼：編輯後格式化檔案、在執行前阻止命令、當 Claude 需要輸入時發送通知、在工作階段開始時注入上下文等。有關 hook 事件的完整列表，請參閱 [Hooks 參考](/docs/zh-TW/hooks#hook-lifecycle)。

89 89

90每個範例都包含一個現成可用的配置區塊，您可以將其新增到[設定檔](#configure-hook-location)。90每個範例都包含一個現成可用的配置區塊，您可以將其新增到[設定檔](#configure-hook-location)。

91 91

92有關 hooks 執行單獨模型審查並將發現結果反饋到工作階段中的生產範例，請參閱 [`security-guidance` plugin 如何與 Claude Code 整合](/zh-TW/security-guidance#how-the-plugin-integrates-with-claude-code)。92有關 hooks 執行單獨模型審查並將發現結果反饋到工作階段中的生產範例，請參閱 [`security-guidance` plugin 如何與 Claude Code 整合](/docs/zh-TW/security-guidance#how-the-plugin-integrates-with-claude-code)。

93 93

94<h3 id="get-notified-when-claude-needs-input">94<h3 id="get-notified-when-claude-needs-input">

95 當 Claude 需要輸入時收到通知95 當 Claude 需要輸入時收到通知

186 186

187`agent_needs_input` 和 `agent_completed` 匹配器需要 Claude Code v2.1.198 或更新版本。187`agent_needs_input` 和 `agent_completed` 匹配器需要 Claude Code v2.1.198 或更新版本。

188 188

189輸入 `/hooks` 並選擇 `Notification` 以確認 hook 已註冊。有關完整的事件架構，請參閱 [Notification 參考](/zh-TW/hooks#notification)。189輸入 `/hooks` 並選擇 `Notification` 以確認 hook 已註冊。有關完整的事件架構，請參閱 [Notification 參考](/docs/zh-TW/hooks#notification)。

190 190

191<h3 id="auto-format-code-after-edits">191<h3 id="auto-format-code-after-edits">

192 編輯後自動格式化程式碼192 編輯後自動格式化程式碼

309}309}

310```310```

311 311

312您可以將 `echo` 替換為任何產生動態輸出的命令，如 `git log --oneline -5` 以顯示最近的提交。有關在每個工作階段開始時注入上下文，請考慮改用 [CLAUDE.md](/zh-TW/memory)。有關環境變數，請參閱參考中的 [`CLAUDE_ENV_FILE`](/zh-TW/hooks#persist-environment-variables)。312您可以將 `echo` 替換為任何產生動態輸出的命令，如 `git log --oneline -5` 以顯示最近的提交。有關在每個工作階段開始時注入上下文，請考慮改用 [CLAUDE.md](/docs/zh-TW/memory)。有關環境變數，請參閱參考中的 [`CLAUDE_ENV_FILE`](/docs/zh-TW/hooks#persist-environment-variables)。

313 313

314<h3 id="audit-configuration-changes">314<h3 id="audit-configuration-changes">

315 審計配置變更315 審計配置變更

337}337}

338```338```

339 339

340匹配器按配置類型篩選：`user_settings`、`project_settings`、`local_settings`、`policy_settings` 或 `skills`。要阻止變更生效，以代碼 2 退出或傳回 `{"decision": "block"}`。有關完整的輸入架構，請參閱 [ConfigChange 參考](/zh-TW/hooks#configchange)。340匹配器按配置類型篩選：`user_settings`、`project_settings`、`local_settings`、`policy_settings` 或 `skills`。要阻止變更生效，以代碼 2 退出或傳回 `{"decision": "block"}`。有關完整的輸入架構，請參閱 [ConfigChange 參考](/docs/zh-TW/hooks#configchange)。

341 341

342<h3 id="reload-environment-when-directory-or-files-change">342<h3 id="reload-environment-when-directory-or-files-change">

343 當目錄或檔案變更時重新載入環境343 當目錄或檔案變更時重新載入環境

376 376

377在每個具有 `.envrc` 的目錄中執行一次 `direnv allow`，以便允許 direnv 載入它。如果您使用 devbox 或 nix 而不是 direnv，相同的模式適用於 `devbox shellenv` 或 `devbox global shellenv` 代替 `direnv export bash`。377在每個具有 `.envrc` 的目錄中執行一次 `direnv allow`，以便允許 direnv 載入它。如果您使用 devbox 或 nix 而不是 direnv，相同的模式適用於 `devbox shellenv` 或 `devbox global shellenv` 代替 `direnv export bash`。

378 378

379若要對特定檔案而不是每次目錄變更做出反應，請使用 `FileChanged` 搭配 `matcher` 列出要監視的檔案名稱（以 `|` 分隔）。建立監視清單時，Claude Code 會將此值分割為字面檔案名稱，而不是作為正規表達式進行評估。有關輸入架構、`watchPaths` 輸出和 `CLAUDE_ENV_FILE` 詳細資訊，請參閱 [FileChanged](/zh-TW/hooks#filechanged)。此範例監視工作目錄中 `.envrc` 和 `.env` 的變更：379若要對特定檔案而不是每次目錄變更做出反應，請使用 `FileChanged` 搭配 `matcher` 列出要監視的檔案名稱（以 `|` 分隔）。建立監視清單時，Claude Code 會將此值分割為字面檔案名稱，而不是作為正規表達式進行評估。有關輸入架構、`watchPaths` 輸出和 `CLAUDE_ENV_FILE` 詳細資訊，請參閱 [FileChanged](/docs/zh-TW/hooks#filechanged)。此範例監視工作目錄中 `.envrc` 和 `.env` 的變更：

380 380

381```json theme={null}381```json theme={null}

382{382{

396}396}

397```397```

398 398

399有關輸入架構、`watchPaths` 輸出和 `CLAUDE_ENV_FILE` 詳細資訊，請參閱 [CwdChanged](/zh-TW/hooks#cwdchanged) 和 [FileChanged](/zh-TW/hooks#filechanged) 參考項目。399有關輸入架構、`watchPaths` 輸出和 `CLAUDE_ENV_FILE` 詳細資訊，請參閱 [CwdChanged](/docs/zh-TW/hooks#cwdchanged) 和 [FileChanged](/docs/zh-TW/hooks#filechanged) 參考項目。

400 400

401<h3 id="auto-approve-specific-permission-prompts">401<h3 id="auto-approve-specific-permission-prompts">

402 自動批准特定權限提示402 自動批准特定權限提示

431若要改為設定特定的權限模式，您的 hook 的輸出可以包含帶有 `setMode` 項目的 `updatedPermissions` 陣列。`mode` 值是任何權限模式，如 `default`、`acceptEdits` 或 `bypassPermissions`，`destination: "session"` 僅將其應用於當前工作階段。431若要改為設定特定的權限模式，您的 hook 的輸出可以包含帶有 `setMode` 項目的 `updatedPermissions` 陣列。`mode` 值是任何權限模式，如 `default`、`acceptEdits` 或 `bypassPermissions`，`destination: "session"` 僅將其應用於當前工作階段。

432 432

433<Note>433<Note>

434 `bypassPermissions` 只有在工作階段已經啟用了繞過模式時才適用：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或設定中的 `permissions.defaultMode: "bypassPermissions"`，且未被 [`permissions.disableBypassPermissionsMode`](/zh-TW/permissions#managed-settings) 禁用。它永遠不會被持久化為 `defaultMode`。434 `bypassPermissions` 只有在工作階段已經啟用了繞過模式時才適用：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或設定中的 `permissions.defaultMode: "bypassPermissions"`，且未被 [`permissions.disableBypassPermissionsMode`](/docs/zh-TW/permissions#managed-settings) 禁用。它永遠不會被持久化為 `defaultMode`。

435</Note>435</Note>

436 436

437若要將工作階段切換到 `acceptEdits`，您的 hook 會將此 JSON 寫入 stdout：437若要將工作階段切換到 `acceptEdits`，您的 hook 會將此 JSON 寫入 stdout：

450}450}

451```451```

452 452

453保持匹配器盡可能狹窄。在 `.*` 上進行匹配或留空匹配器會自動批准每個權限提示，包括檔案寫入和 shell 命令。有關決策欄位的完整集合，請參閱 [PermissionRequest 參考](/zh-TW/hooks#permissionrequest-decision-control)。453保持匹配器盡可能狹窄。在 `.*` 上進行匹配或留空匹配器會自動批准每個權限提示，包括檔案寫入和 shell 命令。有關決策欄位的完整集合，請參閱 [PermissionRequest 參考](/docs/zh-TW/hooks#permissionrequest-decision-control)。

454 454

455<h2 id="how-hooks-work">455<h2 id="how-hooks-work">

456 Hooks 如何工作456 Hooks 如何工作

482| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |482| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

484| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |484| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

486| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |486| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

494每個 hook 都有一個 `type` 來決定它如何執行。大多數 hooks 使用 `"type": "command"`，它執行 shell 命令。還有四種其他類型可用：494每個 hook 都有一個 `type` 來決定它如何執行。大多數 hooks 使用 `"type": "command"`，它執行 shell 命令。還有四種其他類型可用：

495 495

496* `"type": "http"`：POST 事件資料到 URL。請參閱 [HTTP hooks](#http-hooks)。496* `"type": "http"`：POST 事件資料到 URL。請參閱 [HTTP hooks](#http-hooks)。

497* `"type": "mcp_tool"`：在已連接的 MCP 伺服器上呼叫工具。請參閱 [MCP tool hooks](/zh-TW/hooks#mcp-tool-hook-fields)。497* `"type": "mcp_tool"`：在已連接的 MCP 伺服器上呼叫工具。請參閱 [MCP tool hooks](/docs/zh-TW/hooks#mcp-tool-hook-fields)。

498* `"type": "prompt"`：單輪 LLM 評估。請參閱[基於提示的 hooks](#prompt-based-hooks)。498* `"type": "prompt"`：單輪 LLM 評估。請參閱[基於提示的 hooks](#prompt-based-hooks)。

499* `"type": "agent"`：具有工具存取的多輪驗證。Agent hooks 是實驗性的，可能會改變。請參閱[基於 Agent 的 hooks](#agent-based-hooks)。499* `"type": "agent"`：具有工具存取的多輪驗證。Agent hooks 是實驗性的，可能會改變。請參閱[基於 Agent 的 hooks](#agent-based-hooks)。

500 500

556}556}

557```557```

558 558

559您的指令可以解析該 JSON 並對任何這些欄位採取行動。`UserPromptSubmit` hooks 改為取得 `prompt` 文字，`SessionStart` hooks 取得 `source`（startup、resume、clear、compact），等等。有關共享欄位，請參閱參考中的[常見輸入欄位](/zh-TW/hooks#common-input-fields)，以及每個事件的部分以了解事件特定的架構。559您的指令可以解析該 JSON 並對任何這些欄位採取行動。`UserPromptSubmit` hooks 改為取得 `prompt` 文字，`SessionStart` hooks 取得 `source`（startup、resume、clear、compact），等等。有關共享欄位，請參閱參考中的[常見輸入欄位](/docs/zh-TW/hooks#common-input-fields)，以及每個事件的部分以了解事件特定的架構。

560 560

561<h4 id="hook-output">561<h4 id="hook-output">

562 Hook 輸出562 Hook 輸出

579 579

580退出代碼決定接下來會發生什麼：580退出代碼決定接下來會發生什麼：

581 581

582* **Exit 0**：hook 報告沒有異議，操作正常進行。對於 `PreToolUse` hook，這不會批准工具呼叫：正常的[權限流程](/zh-TW/permissions)仍然適用。對於 `UserPromptSubmit`、`UserPromptExpansion` 和 `SessionStart` hooks，您寫入 stdout 的任何內容都會新增到 Claude 的上下文中。582* **Exit 0**：hook 報告沒有異議，操作正常進行。對於 `PreToolUse` hook，這不會批准工具呼叫：正常的[權限流程](/docs/zh-TW/permissions)仍然適用。對於 `UserPromptSubmit`、`UserPromptExpansion` 和 `SessionStart` hooks，您寫入 stdout 的任何內容都會新增到 Claude 的上下文中。

583* **Exit 2**：操作被阻止。寫入原因到 stderr，Claude 會收到它作為回饋，以便它可以調整。某些事件無法被阻止：對於 `SessionStart`、`Setup`、`Notification` 和其他事件，exit 2 會向使用者顯示 stderr，執行繼續。有關完整清單，請參閱[每個事件的 exit code 2 行為](/zh-TW/hooks#exit-code-2-behavior-per-event)。583* **Exit 2**：操作被阻止。寫入原因到 stderr，Claude 會收到它作為回饋，以便它可以調整。某些事件無法被阻止：對於 `SessionStart`、`Setup`、`Notification` 和其他事件，exit 2 會向使用者顯示 stderr，執行繼續。有關完整清單，請參閱[每個事件的 exit code 2 行為](/docs/zh-TW/hooks#exit-code-2-behavior-per-event)。

584* **任何其他退出代碼**：操作繼續。文字記錄顯示 `<hook name> hook error` 通知，後面跟著 stderr 的第一行；完整的 stderr 進入[除錯日誌](/zh-TW/hooks#debug-hooks)。584* **任何其他退出代碼**：操作繼續。文字記錄顯示 `<hook name> hook error` 通知，後面跟著 stderr 的第一行；完整的 stderr 進入[除錯日誌](/docs/zh-TW/hooks#debug-hooks)。

585 585

586<h4 id="structured-json-output">586<h4 id="structured-json-output">

587 結構化 JSON 輸出587 結構化 JSON 輸出

607 607

608使用 `"deny"`，Claude Code 會取消工具呼叫並將 `permissionDecisionReason` 回饋給 Claude。這些 `permissionDecision` 值特定於 `PreToolUse`：608使用 `"deny"`，Claude Code 會取消工具呼叫並將 `permissionDecisionReason` 回饋給 Claude。這些 `permissionDecision` 值特定於 `PreToolUse`：

609 609

610* `"allow"`：跳過互動式權限提示。拒絕和詢問規則，包括企業受管拒絕清單，仍然適用，以及您的組織設定為 `ask` 的連接器工具提示和標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具610* `"allow"`：跳過互動式權限提示。拒絕和詢問規則，包括企業受管拒絕清單，仍然適用，以及您的組織設定為 `ask` 的連接器工具提示和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具

611* `"deny"`：取消工具呼叫並將原因傳送給 Claude611* `"deny"`：取消工具呼叫並將原因傳送給 Claude

612* `"ask"`：照常向使用者顯示權限提示612* `"ask"`：照常向使用者顯示權限提示

613 613

614第四個值 `"defer"` 在[非互動模式](/zh-TW/headless)中使用 `-p` 旗標時可用。它以保留的工具呼叫退出程序，以便 Agent SDK 包裝器可以收集輸入並繼續。有關詳細資訊，請參閱參考中的[延遲工具呼叫以供稍後使用](/zh-TW/hooks#defer-a-tool-call-for-later)。614第四個值 `"defer"` 在[非互動模式](/docs/zh-TW/headless)中使用 `-p` 旗標時可用。它以保留的工具呼叫退出程序，以便 Agent SDK 包裝器可以收集輸入並繼續。有關詳細資訊，請參閱參考中的[延遲工具呼叫以供稍後使用](/docs/zh-TW/hooks#defer-a-tool-call-for-later)。

615 615

616傳回 `"allow"` 會跳過互動式提示，但不會覆蓋[權限規則](/zh-TW/permissions#manage-permissions)。如果拒絕規則與工具呼叫相符，即使您的 hook 傳回 `"allow"`，呼叫也會被阻止。如果詢問規則相符，使用者仍會被提示，以及您的組織設定為 `ask` 的連接器工具和標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具。這意味著來自任何設定範圍（包括[受管理的設定](/zh-TW/settings#settings-files)）的拒絕規則始終優先於 hook 批准。616傳回 `"allow"` 會跳過互動式提示，但不會覆蓋[權限規則](/docs/zh-TW/permissions#manage-permissions)。如果拒絕規則與工具呼叫相符，即使您的 hook 傳回 `"allow"`，呼叫也會被阻止。如果詢問規則相符，使用者仍會被提示，以及您的組織設定為 `ask` 的連接器工具和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具。這意味著來自任何設定範圍（包括[受管理的設定](/docs/zh-TW/settings#settings-files)）的拒絕規則始終優先於 hook 批准。

617 617

618其他事件使用不同的決策模式。例如，`PostToolUse` 和 `Stop` hooks 使用頂級 `decision: "block"` 欄位，而 `PermissionRequest` 使用 `hookSpecificOutput.decision.behavior`。有關按事件的完整分解，請參閱參考中的[摘要表](/zh-TW/hooks#decision-control)。618其他事件使用不同的決策模式。例如，`PostToolUse` 和 `Stop` hooks 使用頂級 `decision: "block"` 欄位，而 `PermissionRequest` 使用 `hookSpecificOutput.decision.behavior`。有關按事件的完整分解，請參閱參考中的[摘要表](/docs/zh-TW/hooks#decision-control)。

619 619

620對於 `UserPromptSubmit` hooks，改用 `hookSpecificOutput.additionalContext` 將文字注入到 Claude 的上下文中。將 `additionalContext` 嵌套在 `hookSpecificOutput` 內；如果您將其放在 JSON 的頂級，Claude Code 會無聲地忽略它。例如，此輸出將目前分支狀態新增到每個提示：620對於 `UserPromptSubmit` hooks，改用 `hookSpecificOutput.additionalContext` 將文字注入到 Claude 的上下文中。將 `additionalContext` 嵌套在 `hookSpecificOutput` 內；如果您將其放在 JSON 的頂級，Claude Code 會無聲地忽略它。例如，此輸出將目前分支狀態新增到每個提示：

621 621

628}628}

629```629```

630 630

631有關完整的輸出形狀（包括阻止提示和設定工作階段標題），請參閱 [UserPromptSubmit 決策控制](/zh-TW/hooks#userpromptsubmit-decision-control)。631有關完整的輸出形狀（包括阻止提示和設定工作階段標題），請參閱 [UserPromptSubmit 決策控制](/docs/zh-TW/hooks#userpromptsubmit-decision-control)。

632 632

633具有 `type: "prompt"` 的 Hooks 以不同方式處理輸出：請參閱[基於提示的 hooks](#prompt-based-hooks)。633具有 `type: "prompt"` 的 Hooks 以不同方式處理輸出：請參閱[基於提示的 hooks](#prompt-based-hooks)。

634 634

653}653}

654```654```

655 655

656`"Edit|Write"` 匹配器只在 Claude 使用 `Edit` 或 `Write` 工具時觸發，而不是在它使用 `Bash`、`Read` 或任何其他工具時。在 Claude Code v2.1.191 或更新版本上，逗號以相同方式分隔替代項，因此 `"Edit, Write"` 是等效的。請參閱[匹配器模式](/zh-TW/hooks#matcher-patterns)以了解純名稱和正規表達式如何被評估。656`"Edit|Write"` 匹配器只在 Claude 使用 `Edit` 或 `Write` 工具時觸發，而不是在它使用 `Bash`、`Read` 或任何其他工具時。在 Claude Code v2.1.191 或更新版本上，逗號以相同方式分隔替代項，因此 `"Edit, Write"` 是等效的。請參閱[匹配器模式](/docs/zh-TW/hooks#matcher-patterns)以了解純名稱和正規表達式如何被評估。

657 657

658<Note>658<Note>

659 Claude 也可以透過 `Bash` 工具執行 shell 命令來建立或修改檔案。如果您的 hook 必須看到每個檔案變更，例如用於合規掃描或稽核日誌，請新增一個[`Stop`](/zh-TW/hooks#stop) hook，它每輪掃描一次工作樹。為了獲得每次呼叫的覆蓋範圍，也請匹配 `Bash` 並讓您的指令使用 `git status --porcelain` 列出修改和未追蹤的檔案。659 Claude 也可以透過 `Bash` 工具執行 shell 命令來建立或修改檔案。如果您的 hook 必須看到每個檔案變更，例如用於合規掃描或稽核日誌，請新增一個[`Stop`](/docs/zh-TW/hooks#stop) hook，它每輪掃描一次工作樹。為了獲得每次呼叫的覆蓋範圍，也請匹配 `Bash` 並讓您的指令使用 `git status --porcelain` 列出修改和未追蹤的檔案。

660</Note>660</Note>

661 661

662每個事件類型都在特定欄位上進行匹配：662每個事件類型都在特定欄位上進行匹配：

681| `UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`CwdChanged`、`MessageDisplay` | 不支援匹配器 | 始終在每次出現時觸發 |681| `UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`CwdChanged`、`MessageDisplay` | 不支援匹配器 | 始終在每次出現時觸發 |

682 682

706 </Tab>706 </Tab>

707 707

708 <Tab title="匹配 MCP 工具">708 <Tab title="匹配 MCP 工具">

709 MCP 工具使用與內建工具不同的命名慣例：`mcp__<server>__<tool>`，其中 `<server>` 是 MCP 伺服器名稱，`<tool>` 是它提供的工具。例如，`mcp__github__search_repositories` 或 `mcp__filesystem__read_file`。來自[外掛提供的 MCP 伺服器](/zh-TW/mcp#plugin-provided-mcp-servers)的工具使用範圍伺服器段，例如 `mcp__plugin_my-plugin_db__query`。使用正規表達式匹配器來針對來自特定伺服器的所有工具，或使用 `mcp__.*__write.*` 之類的模式跨伺服器進行匹配。有關完整的範例列表，請參閱參考中的[匹配 MCP 工具](/zh-TW/hooks#match-mcp-tools)。709 MCP 工具使用與內建工具不同的命名慣例：`mcp__<server>__<tool>`，其中 `<server>` 是 MCP 伺服器名稱，`<tool>` 是它提供的工具。例如，`mcp__github__search_repositories` 或 `mcp__filesystem__read_file`。來自[外掛提供的 MCP 伺服器](/docs/zh-TW/mcp#plugin-provided-mcp-servers)的工具使用範圍伺服器段，例如 `mcp__plugin_my-plugin_db__query`。使用正規表達式匹配器來針對來自特定伺服器的所有工具，或使用 `mcp__.*__write.*` 之類的模式跨伺服器進行匹配。有關完整的範例列表，請參閱參考中的[匹配 MCP 工具](/docs/zh-TW/hooks#match-mcp-tools)。

710 710

711 下面的命令使用 `jq` 從 hook 的 JSON 輸入中提取工具名稱，並將其寫入 stderr。寫入 stderr 會保持 stdout 乾淨以用於 JSON 輸出，並將訊息發送到[除錯日誌](/zh-TW/hooks#debug-hooks)：711 下面的命令使用 `jq` 從 hook 的 JSON 輸入中提取工具名稱，並將其寫入 stderr。寫入 stderr 會保持 stdout 乾淨以用於 JSON 輸出，並將訊息發送到[除錯日誌](/docs/zh-TW/hooks#debug-hooks)：

712 712

713 ```json theme={null}713 ```json theme={null}

714 {714 {

752 </Tab>752 </Tab>

753</Tabs>753</Tabs>

754 754

755有關完整的匹配器語法，請參閱 [Hooks 參考](/zh-TW/hooks#configuration)。755有關完整的匹配器語法，請參閱 [Hooks 參考](/docs/zh-TW/hooks#configuration)。

756 756

757<h4 id="filter-by-tool-name-and-arguments-with-the-if-field">757<h4 id="filter-by-tool-name-and-arguments-with-the-if-field">

758 使用 `if` 欄位按工具名稱和引數篩選758 使用 `if` 欄位按工具名稱和引數篩選

759</h4>759</h4>

760 760

761`if` 欄位使用[權限規則語法](/zh-TW/permissions)按工具名稱和引數一起篩選 hooks，因此 hook 程序只在工具呼叫相符時生成。這超越了 `matcher`，它只在工具名稱級別篩選。761`if` 欄位使用[權限規則語法](/docs/zh-TW/permissions)按工具名稱和引數一起篩選 hooks，因此 hook 程序只在工具呼叫相符時生成。這超越了 `matcher`，它只在工具名稱級別篩選。

762 762

763例如，這個配置只在 Claude 使用 `git` 命令而不是所有 Bash 命令時執行 hook：763例如，這個配置只在 Claude 使用 `git` 命令而不是所有 Bash 命令時執行 hook：

764 764

793 793

794篩選器也會失敗開放，當 Bash 命令無法解析時執行您的 hook。因為篩選器是盡力而為，請使用[權限系統](/zh-TW/permissions)而不是 hook 來強制執行硬允許或拒絕。794篩選器也會失敗開放，當 Bash 命令無法解析時執行您的 hook。因為篩選器是盡力而為，請使用[權限系統](/docs/zh-TW/permissions)而不是 hook 來強制執行硬允許或拒絕。

795 795

796`if` 欄位接受與權限規則相同的模式：`"Bash(git *)"`、`"Edit(*.ts)"` 等。若要匹配多個工具名稱，請使用每個都有自己的 `if` 值的單獨處理程式，或在 `matcher` 級別進行匹配，其中支援管道交替。796`if` 欄位接受與權限規則相同的模式：`"Bash(git *)"`、`"Edit(*.ts)"` 等。若要匹配多個工具名稱，請使用每個都有自己的 `if` 值的單獨處理程式，或在 `matcher` 級別進行匹配，其中支援管道交替。

797 797

814 814

815在 Claude Code 中執行 [`/hooks`](/zh-TW/hooks#the-%2Fhooks-menu) 以瀏覽按事件分組的所有配置的 hooks。815在 Claude Code 中執行 [`/hooks`](/docs/zh-TW/hooks#the-%2Fhooks-menu) 以瀏覽按事件分組的所有配置的 hooks。

816 816

817若要禁用 hooks，請在設定檔中設定 `"disableAllHooks": true`。受管理的原則設定中配置的 Hooks 仍會執行，除非 `disableAllHooks` 也在那裡設定。817若要禁用 hooks，請在設定檔中設定 `"disableAllHooks": true`。受管理的原則設定中配置的 Hooks 仍會執行，除非 `disableAllHooks` 也在那裡設定。

818 818

851}851}

852```852```

853 853

854有關完整的配置選項，請參閱參考中的[基於提示的 hooks](/zh-TW/hooks#prompt-based-hooks)。854有關完整的配置選項，請參閱參考中的[基於提示的 hooks](/docs/zh-TW/hooks#prompt-based-hooks)。

855 855

856<h2 id="agent-based-hooks">856<h2 id="agent-based-hooks">

857 基於代理的 hooks857 基於代理的 hooks

858</h2>858</h2>

859 859

860<Warning>860<Warning>

861 Agent hooks 是實驗性的。行為和配置可能在未來版本中改變。對於生產工作流程，優先使用[命令 hooks](/zh-TW/hooks#command-hook-fields)。861 Agent hooks 是實驗性的。行為和配置可能在未來版本中改變。對於生產工作流程，優先使用[命令 hooks](/docs/zh-TW/hooks#command-hook-fields)。

862</Warning>862</Warning>

863 863

864當驗證需要檢查檔案或執行命令時，使用 `type: "agent"` hooks。與只進行單個 LLM 呼叫的提示 hooks 不同，代理 hooks 生成一個 subagent，可以讀取檔案、搜尋程式碼和使用其他工具在傳回決策之前驗證條件。864當驗證需要檢查檔案或執行命令時，使用 `type: "agent"` hooks。與只進行單個 LLM 呼叫的提示 hooks 不同，代理 hooks 生成一個 subagent，可以讀取檔案、搜尋程式碼和使用其他工具在傳回決策之前驗證條件。

887 887

888當 hook 輸入資料本身足以做出決策時，使用提示 hooks。當您需要根據程式碼庫的實際狀態驗證某些內容時，使用代理 hooks。888當 hook 輸入資料本身足以做出決策時，使用提示 hooks。當您需要根據程式碼庫的實際狀態驗證某些內容時，使用代理 hooks。

889 889

890有關完整的配置選項，請參閱參考中的[基於代理的 hooks](/zh-TW/hooks#agent-based-hooks)。890有關完整的配置選項，請參閱參考中的[基於代理的 hooks](/docs/zh-TW/hooks#agent-based-hooks)。

891 891

892<h2 id="http-hooks">892<h2 id="http-hooks">

893 HTTP hooks893 HTTP hooks

920}920}

921```921```

922 922

923端點應使用與命令 hooks 相同的[輸出格式](/zh-TW/hooks#json-output)傳回 JSON 回應主體。要阻止工具呼叫，傳回 2xx 回應並包含適當的 `hookSpecificOutput` 欄位。HTTP 狀態代碼本身無法阻止操作。923端點應使用與命令 hooks 相同的[輸出格式](/docs/zh-TW/hooks#json-output)傳回 JSON 回應主體。要阻止工具呼叫，傳回 2xx 回應並包含適當的 `hookSpecificOutput` 欄位。HTTP 狀態代碼本身無法阻止操作。

924 924

925標頭值支援使用 `$VAR_NAME` 或 `${VAR_NAME}` 語法的環境變數插值。只有在 `allowedEnvVars` 陣列中列出的變數才會被解析；所有其他 `$VAR` 參考保持為空。925標頭值支援使用 `$VAR_NAME` 或 `${VAR_NAME}` 語法的環境變數插值。只有在 `allowedEnvVars` 陣列中列出的變數才會被解析；所有其他 `$VAR` 參考保持為空。

926 926

927有關完整的配置選項和回應處理，請參閱參考中的 [HTTP hooks](/zh-TW/hooks#http-hook-fields)。927有關完整的配置選項和回應處理，請參閱參考中的 [HTTP hooks](/docs/zh-TW/hooks#http-hook-fields)。

928 928

929<h2 id="limitations-and-troubleshooting">929<h2 id="limitations-and-troubleshooting">

930 限制和故障排除930 限制和故障排除

942 * `prompt`：30 秒。942 * `prompt`：30 秒。

943 * `agent`：60 秒。943 * `agent`：60 秒。

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

945* `PermissionRequest` hooks 在[非互動模式](/zh-TW/headless)（`-p` 旗標）中不觸發。對於自動化權限決策，使用 `PreToolUse` hooks。945* `PermissionRequest` hooks 在[非互動模式](/docs/zh-TW/headless)（`-p` 旗標）中不觸發。對於自動化權限決策，使用 `PreToolUse` hooks。

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

947* 當多個 `PreToolUse` hooks 傳回 [`updatedInput`](/zh-TW/hooks#pretooluse) 以重寫工具的引數時，最後完成的會獲勝。由於 hooks 並行執行，順序是非確定性的。避免有多個 hook 修改同一工具的輸入。947* 當多個 `PreToolUse` hooks 傳回 [`updatedInput`](/docs/zh-TW/hooks#pretooluse) 以重寫工具的引數時，最後完成的會獲勝。由於 hooks 並行執行，順序是非確定性的。避免有多個 hook 修改同一工具的輸入。

948 948

949<h3 id="hooks-and-permission-modes">949<h3 id="hooks-and-permission-modes">

950 Hooks 和權限模式950 Hooks 和權限模式

952 952

953`PreToolUse` hooks 在任何權限模式檢查之前觸發。傳回 `permissionDecision: "deny"` 的 hook 會阻止工具，即使在 `bypassPermissions` 模式或使用 `--dangerously-skip-permissions`。這讓您強制執行使用者無法透過變更其權限模式來繞過的原則。953`PreToolUse` hooks 在任何權限模式檢查之前觸發。傳回 `permissionDecision: "deny"` 的 hook 會阻止工具，即使在 `bypassPermissions` 模式或使用 `--dangerously-skip-permissions`。這讓您強制執行使用者無法透過變更其權限模式來繞過的原則。

954 954

955反面不成立：傳回 `"allow"` 的 hook 不會繞過來自設定的拒絕規則，它也無法抑制您的組織設定為 `ask` 的連接器工具的提示或標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具。Hooks 可以加強限制，但不能放寬超過權限規則允許的限制。955反面不成立：傳回 `"allow"` 的 hook 不會繞過來自設定的拒絕規則，它也無法抑制您的組織設定為 `ask` 的連接器工具的提示或標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具。Hooks 可以加強限制，但不能放寬超過權限規則允許的限制。

956 956

957<h3 id="hook-not-firing">957<h3 id="hook-not-firing">

958 Hook 未觸發958 Hook 未觸發

976 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh976 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh

977 echo $? # 檢查退出代碼977 echo $? # 檢查退出代碼

978 ```978 ```

979* 如果您看到「command not found」，使用絕對路徑或 `${CLAUDE_PROJECT_DIR}` 來參考指令。為了完全避免 shell 引用，添加 `"args": []` 以切換到 [exec 形式](/zh-TW/hooks#exec-form-and-shell-form)，它直接生成指令而不使用 shell979* 如果您看到「command not found」，使用絕對路徑或 `${CLAUDE_PROJECT_DIR}` 來參考指令。為了完全避免 shell 引用，添加 `"args": []` 以切換到 [exec 形式](/docs/zh-TW/hooks#exec-form-and-shell-form)，它直接生成指令而不使用 shell

980* 如果您看到「jq: command not found」，安裝 `jq` 或使用 Python/Node.js 進行 JSON 解析980* 如果您看到「jq: command not found」，安裝 `jq` 或使用 Python/Node.js 進行 JSON 解析

981* 如果指令根本沒有執行，使其可執行：`chmod +x ./my-hook.sh`981* 如果指令根本沒有執行，使其可執行：`chmod +x ./my-hook.sh`

982 982

1007# ... 您的 hook 邏輯的其餘部分1007# ... 您的 hook 邏輯的其餘部分

1008```1008```

1009 1009

1010如果您的 hook 合理地需要超過八次迭代才能收斂，使用 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/zh-TW/env-vars) 提高上限。1010如果您的 hook 合理地需要超過八次迭代才能收斂，使用 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/zh-TW/env-vars) 提高上限。

1011 1011

1012<h3 id="json-validation-failed">1012<h3 id="json-validation-failed">

1013 JSON 驗證失敗1013 JSON 驗證失敗

1045 深入瞭解1045 深入瞭解

1046</h2>1046</h2>

1047 1047

1048* [Hooks 參考](/zh-TW/hooks)：完整的事件架構、JSON 輸出格式、非同步 hooks 和 MCP 工具 hooks1048* [Hooks 參考](/docs/zh-TW/hooks)：完整的事件架構、JSON 輸出格式、非同步 hooks 和 MCP 工具 hooks

1049* [安全考量](/zh-TW/hooks#security-considerations)：在共享或生產環境中部署 hooks 之前進行檢查1049* [安全考量](/docs/zh-TW/hooks#security-considerations)：在共享或生產環境中部署 hooks 之前進行檢查

1050* [Bash 命令驗證器範例](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)：完整的參考實現1050* [Bash 命令驗證器範例](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)：完整的參考實現

plugins-reference.md +45 −45

Details

7> Claude Code 外掛系統的完整技術參考，包括架構、CLI 命令和元件規格。7> Claude Code 外掛系統的完整技術參考，包括架構、CLI 命令和元件規格。

8 8

9<Tip>9<Tip>

10 想要安裝外掛？請參閱 [探索和安裝外掛](/zh-TW/discover-plugins)。如需建立外掛，請參閱 [Plugins](/zh-TW/plugins)。如需發佈外掛，請參閱 [Plugin marketplaces](/zh-TW/plugin-marketplaces)。10 想要安裝外掛？請參閱 [探索和安裝外掛](/docs/zh-TW/discover-plugins)。如需建立外掛，請參閱 [Plugins](/docs/zh-TW/plugins)。如需發佈外掛，請參閱 [Plugin marketplaces](/docs/zh-TW/plugin-marketplaces)。

11</Tip>11</Tip>

12 12

13本參考提供 Claude Code 外掛系統的完整技術規格，包括元件架構、CLI 命令和開發工具。13本參考提供 Claude Code 外掛系統的完整技術規格，包括元件架構、CLI 命令和開發工具。

48 48

49如果 plugin 沒有 `skills/` 目錄且沒有 `skills` manifest 欄位，plugin 根目錄中的 `SKILL.md` 會被載入為單一 skill。設定 frontmatter `name` 欄位以控制 skill 的叫用名稱。沒有它的話，Claude Code 會回退到安裝目錄名稱，對於 marketplace 安裝的 plugins，這是一個在每次更新時都會變更的版本字串。對於提供多個 skills 的 plugins，請使用上面所示的 `skills/` 目錄配置。49如果 plugin 沒有 `skills/` 目錄且沒有 `skills` manifest 欄位，plugin 根目錄中的 `SKILL.md` 會被載入為單一 skill。設定 frontmatter `name` 欄位以控制 skill 的叫用名稱。沒有它的話，Claude Code 會回退到安裝目錄名稱，對於 marketplace 安裝的 plugins，這是一個在每次更新時都會變更的版本字串。對於提供多個 skills 的 plugins，請使用上面所示的 `skills/` 目錄配置。

50 50

~~51如需完整詳細資訊，請參閱 [Skills](/zh-TW/skills)。~~51如需完整詳細資訊，請參閱 [Skills](/docs/zh-TW/skills)。

52 52

53<h3 id="agents">53<h3 id="agents">

54 Agents54 Agents

79 79

80**整合點**：80**整合點**：

81 81

~~82* Agents 出現在 [@-mention 下拉式選單](/zh-TW/sub-agents#invoke-subagents-explicitly) 中，其範圍名稱為 `my-plugin:code-reviewer`，一旦啟用 plugin~~82* Agents 出現在 [@-mention 下拉式選單](/docs/zh-TW/sub-agents#invoke-subagents-explicitly) 中，其範圍名稱為 `my-plugin:code-reviewer`，一旦啟用 plugin

83* Claude 可以根據任務上下文自動叫用 agents83* Claude 可以根據任務上下文自動叫用 agents

84* Users 可以手動叫用 agents84* Users 可以手動叫用 agents

85* Plugin agents 與內建 Claude agents 一起運作85* Plugin agents 與內建 Claude agents 一起運作

86 86

~~87如需完整詳細資訊，請參閱 [Subagents](/zh-TW/sub-agents)。~~87如需完整詳細資訊，請參閱 [Subagents](/docs/zh-TW/sub-agents)。

88 88

89<h3 id="hooks">89<h3 id="hooks">

90 Hooks90 Hooks

116}116}

117```117```

118 118

119Plugin hooks 回應與 [user-defined hooks](/zh-TW/hooks) 相同的生命週期事件：119Plugin hooks 回應與 [user-defined hooks](/docs/zh-TW/hooks) 相同的生命週期事件：

120 120

121| Event | When it fires |121| Event | When it fires |

122| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |122| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

142| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |142| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

144| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |144| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

146| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |146| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

155 155

156* `command`：執行 shell 命令或指令碼156* `command`：執行 shell 命令或指令碼

157* `http`：將事件 JSON 作為 POST 請求傳送到 URL157* `http`：將事件 JSON 作為 POST 請求傳送到 URL

158* `mcp_tool`：在已設定的 [MCP server](/zh-TW/mcp) 上呼叫工具158* `mcp_tool`：在已設定的 [MCP server](/docs/zh-TW/mcp) 上呼叫工具

159* `prompt`：使用 LLM 評估提示（使用 `$ARGUMENTS` 佔位符表示上下文）159* `prompt`：使用 LLM 評估提示（使用 `$ARGUMENTS` 佔位符表示上下文）

160* `agent`：執行具有工具的 agentic 驗證器以進行複雜驗證任務160* `agent`：執行具有工具的 agentic 驗證器以進行複雜驗證任務

161 161

162針對 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](/zh-TW/hooks#match-mcp-tools) 和 [Plugin-provided MCP servers](/zh-TW/mcp#plugin-provided-mcp-servers)。162針對 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)。

163 163

164<h3 id="mcp-servers">164<h3 id="mcp-servers">

165 MCP servers165 MCP servers

300 300

301Plugins 可以宣告背景 monitors，Claude Code 在 plugin 啟用時自動啟動。每個 monitor 執行一個 shell 命令，持續整個工作階段，並將每個 stdout 行傳遞給 Claude 作為通知，以便 Claude 可以對日誌項目、狀態變更或輪詢事件做出反應，而無需被要求自行啟動監視。301Plugins 可以宣告背景 monitors，Claude Code 在 plugin 啟用時自動啟動。每個 monitor 執行一個 shell 命令，持續整個工作階段，並將每個 stdout 行傳遞給 Claude 作為通知，以便 Claude 可以對日誌項目、狀態變更或輪詢事件做出反應，而無需被要求自行啟動監視。

302 302

303Plugin monitors 使用與 [Monitor tool](/zh-TW/tools-reference#monitor-tool) 相同的機制，並共享其可用性限制。它們僅在互動式 CLI 工作階段中執行，以與 [hooks](#hooks) 相同的信任級別在未沙箱化的環境中執行，並在 Monitor tool 不可用的主機上被跳過。303Plugin monitors 使用與 [Monitor tool](/docs/zh-TW/tools-reference#monitor-tool) 相同的機制，並共享其可用性限制。它們僅在互動式 CLI 工作階段中執行，以與 [hooks](#hooks) 相同的信任級別在未沙箱化的環境中執行，並在 Monitor tool 不可用的主機上被跳過。

304 304

305**位置**：plugin 根目錄中的 `monitors/monitors.json`，或在 `plugin.json` 中內聯305**位置**：plugin 根目錄中的 `monitors/monitors.json`，或在 `plugin.json` 中內聯

306 306

342 342

343`command` 值支援 [path substitutions](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}` 和 `${CLAUDE_PROJECT_DIR}`，加上環境中的任何 `${ENV_VAR}`。如果指令碼需要從 plugin 自己的目錄執行，請在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。343`command` 值支援 [path substitutions](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}` 和 `${CLAUDE_PROJECT_DIR}`，加上環境中的任何 `${ENV_VAR}`。如果指令碼需要從 plugin 自己的目錄執行，請在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。

344 344

345monitor `command` 無法參考 [`${user_config.*}`](#user-configuration) 值。命令透過 shell 執行，所以 Claude Code 會以 [error](/zh-TW/errors#plugin-command-references-user-config) 拒絕 monitor，而不是替換該值。Monitor 程序不會接收 `CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數，所以讓 monitor 指令碼從它擁有的設定檔讀取該值。在 v2.1.207 之前，monitor 命令替換了 `${user_config.*}` 值。345monitor `command` 無法參考 [`${user_config.*}`](#user-configuration) 值。命令透過 shell 執行，所以 Claude Code 會以 [error](/docs/zh-TW/errors#plugin-command-references-user-config) 拒絕 monitor，而不是替換該值。Monitor 程序不會接收 `CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數，所以讓 monitor 指令碼從它擁有的設定檔讀取該值。在 v2.1.207 之前，monitor 命令替換了 `${user_config.*}` 值。

346 346

347在工作階段中途停用 plugin 不會停止已在執行的 monitors。它們在工作階段結束時停止。347在工作階段中途停用 plugin 不會停止已在執行的 monitors。它們在工作階段結束時停止。

348 348

383 383

384Plugins 使用與其他 Claude Code 設定相同的範圍系統。如需安裝說明和範圍旗標，請參閱 [安裝 plugins](/zh-TW/discover-plugins#install-plugins)。如需範圍的完整說明，請參閱 [Configuration scopes](/zh-TW/settings#configuration-scopes)。384Plugins 使用與其他 Claude Code 設定相同的範圍系統。如需安裝說明和範圍旗標，請參閱 [安裝 plugins](/docs/zh-TW/discover-plugins#install-plugins)。如需範圍的完整說明，請參閱 [Configuration scopes](/docs/zh-TW/settings#configuration-scopes)。

385 385

386***386***

387 387

395 395

396| 您擁有的內容 | 它是什麼 |396| 您擁有的內容 | 它是什麼 |

397| :-------------------------------------------- | :------------------------------------------------------- |397| :-------------------------------------------- | :------------------------------------------------------- |

401 401

406| Skills 目錄 | 範圍 | 載入 |406| Skills 目錄 | 範圍 | 載入 |

407| :---------------------- | :------- | :----------------------------------------------- |407| :---------------------- | :------- | :----------------------------------------------- |

410 410

411專案範圍的 plugin 被簽入存放庫，並到達克隆它的每個協作者。因為該內容來自存放庫而不是來自您，它只在與 `.claude/settings.json` 相同的信任閘道後載入，並且執行程式碼的元件受到進一步限制：411專案範圍的 plugin 被簽入存放庫，並到達克隆它的每個協作者。因為該內容來自存放庫而不是來自您，它只在與 `.claude/settings.json` 相同的信任閘道後載入，並且執行程式碼的元件受到進一步限制：

412 412

413* 它宣告的 MCP servers 會經過與專案 `.mcp.json` 相同的 [per-server approval](/zh-TW/mcp)413* 它宣告的 MCP servers 會經過與專案 `.mcp.json` 相同的 [per-server approval](/docs/zh-TW/mcp)

414* LSP servers 只有在您信任工作區後才會啟動414* LSP servers 只有在您信任工作區後才會啟動

415* [Background monitors](#monitors) 不會載入415* [Background monitors](#monitors) 不會載入

416 416

417個人範圍的 plugins 沒有這些限制。417個人範圍的 plugins 沒有這些限制。

418 418

419<Warning>419<Warning>

420 專案範圍的 `@skills-dir` plugins 只從您啟動 Claude Code 的目錄的 `.claude/skills/` 載入。它們不會像純 skills 和 commands 那樣 [walk up to the repository root](/zh-TW/skills#automatic-discovery-from-parent-and-nested-directories)，所以從子目錄啟動會錯過位於存放庫根目錄的 plugin。從存放庫根目錄啟動，或在變更目錄後執行 `/reload-plugins`。420 專案範圍的 `@skills-dir` plugins 只從您啟動 Claude Code 的目錄的 `.claude/skills/` 載入。它們不會像純 skills 和 commands 那樣 [walk up to the repository root](/docs/zh-TW/skills#automatic-discovery-from-parent-and-nested-directories)，所以從子目錄啟動會錯過位於存放庫根目錄的 plugin。從存放庫根目錄啟動，或在變更目錄後執行 `/reload-plugins`。

421</Warning>421</Warning>

422 422

423<h3 id="edit-reload-and-disable-a-skills-directory-plugin">423<h3 id="edit-reload-and-disable-a-skills-directory-plugin">

424 編輯、重新載入和停用 skills 目錄 plugin424 編輯、重新載入和停用 skills 目錄 plugin

425</h3>425</h3>

426 426

427您對 skill 的 `SKILL.md` 所做的變更會立即在目前工作階段中生效。對 plugin 的其他元件（例如 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/`）的變更則不會。執行 `/reload-plugins` 或重新啟動 Claude Code 以取得這些變更。請參閱 [Live change detection](/zh-TW/skills#live-change-detection)。427您對 skill 的 `SKILL.md` 所做的變更會立即在目前工作階段中生效。對 plugin 的其他元件（例如 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/`）的變更則不會。執行 `/reload-plugins` 或重新啟動 Claude Code 以取得這些變更。請參閱 [Live change detection](/docs/zh-TW/skills#live-change-detection)。

428 428

429若要停止載入 skills 目錄 plugin，請刪除其資料夾或按名稱停用它。沒有 `uninstall` 步驟，因為沒有從 marketplace 安裝任何內容。429若要停止載入 skills 目錄 plugin，請刪除其資料夾或按名稱停用它。沒有 `uninstall` 步驟，因為沒有從 marketplace 安裝任何內容。

430 430

487 487

488| 欄位 | 類型 | 描述 | 範例 |488| 欄位 | 類型 | 描述 | 範例 |

489| :----- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |489| :----- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |

491 491

492此名稱用於命名空間元件。例如，在 UI 中，名稱為 `plugin-dev` 的 plugin 的 agent `agent-creator` 將顯示為 `plugin-dev:agent-creator`。492此名稱用於命名空間元件。例如，在 UI 中，名稱為 `plugin-dev` 的 plugin 的 agent `agent-creator` 將顯示為 `plugin-dev:agent-creator`。

493 493

533`defaultEnabled` 是當沒有其他因素決定 plugin 狀態時的後備。有兩件事優先於它：533`defaultEnabled` 是當沒有其他因素決定 plugin 狀態時的後備。有兩件事優先於它：

534 534

535* **使用者的設定**：在任何設定範圍的 `enabledPlugins` 中為 plugin 的項目。一旦寫入，它會在 plugin 更新和重新安裝中保留，因此在後續版本中變更 `defaultEnabled` 不會翻轉現有使用者。535* **使用者的設定**：在任何設定範圍的 `enabledPlugins` 中為 plugin 的項目。一旦寫入，它會在 plugin 更新和重新安裝中保留，因此在後續版本中變更 `defaultEnabled` 不會翻轉現有使用者。

536* **相依性要求**：當 plugin 被另一個啟用的 plugin 所需時，Claude Code 會在安裝或啟用時為其寫入 `true`。這給了它一個明確的設定，所以它自己的預設不再適用。請參閱[啟用或停用具有相依性的 plugin](/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)。536* **相依性要求**：當 plugin 被另一個啟用的 plugin 所需時，Claude Code 會在安裝或啟用時為其寫入 `true`。這給了它一個明確的設定，所以它自己的預設不再適用。請參閱[啟用或停用具有相依性的 plugin](/docs/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)。

537 537

538相同的欄位可以出現在 plugin 的 marketplace 項目中，其優先於 `plugin.json` 中的值。請參閱[選用 plugin 欄位](/zh-TW/plugin-marketplaces#optional-plugin-fields)。538相同的欄位可以出現在 plugin 的 marketplace 項目中，其優先於 `plugin.json` 中的值。請參閱[選用 plugin 欄位](/docs/zh-TW/plugin-marketplaces#optional-plugin-fields)。

539 539

540<h3 id="component-path-fields">540<h3 id="component-path-fields">

541 元件路徑欄位541 元件路徑欄位

557| `dependencies` | array | 此 plugin 需要的其他 plugins，可選擇使用 semver 版本限制。請參閱[限制 plugin 相依性版本](/zh-TW/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |557| `dependencies` | array | 此 plugin 需要的其他 plugins，可選擇使用 semver 版本限制。請參閱[限制 plugin 相依性版本](/docs/zh-TW/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

558 558

559<h3 id="experimental-components">559<h3 id="experimental-components">

560 實驗性元件560 實驗性元件

601 601

602每個值都可用於在 MCP 和 LSP server 設定和 hook 命令中替換為 `${user_config.KEY}`。非敏感值也可以在 skill 和 agent 內容中替換。所有值都會匯出到 hook 程序作為 `CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數，其中 `<KEY>` 是選項金鑰大寫。602每個值都可用於在 MCP 和 LSP server 設定和 hook 命令中替換為 `${user_config.KEY}`。非敏感值也可以在 skill 和 agent 內容中替換。所有值都會匯出到 hook 程序作為 `CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數，其中 `<KEY>` 是選項金鑰大寫。

603 603

604在 shell 中執行的欄位拒絕 `${user_config.*}`：將設定的值替換到 shell 命令中會讓 shell 執行該值包含的任何內容，因此元件會失敗並出現[錯誤](/zh-TW/errors#plugin-command-references-user-config)。每個被拒絕的欄位都有一個替代方式來傳遞值：604在 shell 中執行的欄位拒絕 `${user_config.*}`：將設定的值替換到 shell 命令中會讓 shell 執行該值包含的任何內容，因此元件會失敗並出現[錯誤](/docs/zh-TW/errors#plugin-command-references-user-config)。每個被拒絕的欄位都有一個替代方式來傳遞值：

605 605

606| 被拒絕的欄位 | 如何傳遞值 |606| 被拒絕的欄位 | 如何傳遞值 |

607| :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- |607| :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- |

608| Shell 形式的 hook 命令 | 使用[執行形式](/zh-TW/hooks#exec-form-and-shell-form)搭配 `args`，或從 hook 的環境讀取 `CLAUDE_PLUGIN_OPTION_<KEY>` |608| Shell 形式的 hook 命令 | 使用[執行形式](/docs/zh-TW/hooks#exec-form-and-shell-form)搭配 `args`，或從 hook 的環境讀取 `CLAUDE_PLUGIN_OPTION_<KEY>` |

609| [Monitor](#monitors) 命令 | 從指令碼中的設定檔讀取值 |609| [Monitor](#monitors) 命令 | 從指令碼中的設定檔讀取值 |

611 611

612在 v2.1.207 之前，這些欄位替換 `${user_config.KEY}` 值；更新依賴此功能的 plugins。612在 v2.1.207 之前，這些欄位替換 `${user_config.KEY}` 值；更新依賴此功能的 plugins。

613 613

614非敏感值儲存在 `settings.json` 中的 [`pluginConfigs`](/zh-TW/settings#pluginconfigs) 金鑰下，作為 `pluginConfigs[<plugin-id>].options`。{/* min-version: 2.1.207 */}Claude Code 將金鑰寫入使用者設定並從使用者設定、`--settings` 旗標和受管設定讀取；專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目會被忽略。在 v2.1.207 之前，Claude Code 也讀取專案和本地設定。614非敏感值儲存在 `settings.json` 中的 [`pluginConfigs`](/docs/zh-TW/settings#pluginconfigs) 金鑰下，作為 `pluginConfigs[<plugin-id>].options`。{/* min-version: 2.1.207 */}Claude Code 將金鑰寫入使用者設定並從使用者設定、`--settings` 旗標和受管設定讀取；專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目會被忽略。在 v2.1.207 之前，Claude Code 也讀取專案和本地設定。

615 615

616敏感值進入 macOS Keychain，或在沒有支援的 keychain 可用的平台上進入 `~/.claude/.credentials.json`。Keychain 儲存與 OAuth 令牌共享，總限制約為 2 KB，因此請保持敏感值較小。616敏感值進入 macOS Keychain，或在沒有支援的 keychain 可用的平台上進入 `~/.claude/.credentials.json`。Keychain 儲存與 OAuth 令牌共享，總限制約為 2 KB，因此請保持敏感值較小。

617 617

653自訂路徑是否取代或擴展 plugin 的預設目錄取決於欄位：653自訂路徑是否取代或擴展 plugin 的預設目錄取決於欄位：

654 654

655* **取代預設值**：`commands`、`agents`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，當 manifest 指定 `commands` 時，預設 `commands/` 目錄不會被掃描。若要保留預設值並新增更多，請明確列出：`"commands": ["./commands/", "./extras/"]`655* **取代預設值**：`commands`、`agents`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，當 manifest 指定 `commands` 時，預設 `commands/` 目錄不會被掃描。若要保留預設值並新增更多，請明確列出：`"commands": ["./commands/", "./extras/"]`

656* **新增到預設值**：`skills`。預設 `skills/` 目錄始終被掃描，`skills` 中列出的目錄與其一起載入。例外：對於[其 `source` 解析為 marketplace 根目錄的 marketplace 項目](/zh-TW/plugin-marketplaces#advanced-plugin-entries)，宣告特定子目錄會取代掃描656* **新增到預設值**：`skills`。預設 `skills/` 目錄始終被掃描，`skills` 中列出的目錄與其一起載入。例外：對於[其 `source` 解析為 marketplace 根目錄的 marketplace 項目](/docs/zh-TW/plugin-marketplaces#advanced-plugin-entries)，宣告特定子目錄會取代掃描

657* **自有合併規則**：[hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers)。請參閱每個部分以了解多個來源如何組合657* **自有合併規則**：[hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers)。請參閱每個部分以了解多個來源如何組合

658 658

659當 plugin 同時具有預設資料夾和相符的 manifest 金鑰時，Claude Code v2.1.140 及更新版本會在 `claude plugin list` 和 `/plugin` 詳細檢視中標記被忽略的資料夾。plugin 仍會使用 manifest 路徑載入。當 manifest 金鑰指向預設資料夾時不會顯示警告，例如 `"commands": ["./commands/deploy.md"]`，因為在這種情況下資料夾是明確定址的。659當 plugin 同時具有預設資料夾和相符的 manifest 金鑰時，Claude Code v2.1.140 及更新版本會在 `claude plugin list` 和 `/plugin` 詳細檢視中標記被忽略的資料夾。plugin 仍會使用 manifest 路徑載入。當 manifest 金鑰指向預設資料夾時不會顯示警告，例如 `"commands": ["./commands/deploy.md"]`，因為在這種情況下資料夾是明確定址的。

706 706

707在 hook 命令中，使用[執行形式](/zh-TW/hooks#exec-form-and-shell-form)搭配 `args`，以便每個路徑作為一個引數傳遞，無需引號。在 shell 形式的 hooks 和 monitor 命令中，將變數包裝在雙引號中，如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。此 shell 形式的 hook 執行與 plugin 捆綁的指令碼：707在 hook 命令中，使用[執行形式](/docs/zh-TW/hooks#exec-form-and-shell-form)搭配 `args`，以便每個路徑作為一個引數傳遞，無需引號。在 shell 形式的 hooks 和 monitor 命令中，將變數包裝在雙引號中，如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。此 shell 形式的 hook 執行與 plugin 捆綁的指令碼：

708 708

709```json theme={null}709```json theme={null}

710{710{

727 727

728當 plugin 在工作階段中途更新時，hook 命令、monitors、MCP servers 和 LSP servers 會繼續使用前一個版本的路徑。執行 `/reload-plugins` 以將 hooks、MCP servers 和 LSP servers 切換到新路徑；monitors 需要工作階段重新啟動。728當 plugin 在工作階段中途更新時，hook 命令、monitors、MCP servers 和 LSP servers 會繼續使用前一個版本的路徑。執行 `/reload-plugins` 以將 hooks、MCP servers 和 LSP servers 切換到新路徑；monitors 需要工作階段重新啟動。

729 729

730MCP servers 也可以呼叫 `roots/list` 請求以在執行時讀取工作階段的工作目錄。請參閱[`roots/list` 傳回的內容以及 Claude Code 何時通知伺服器變更](/zh-TW/mcp#option-3-add-a-local-stdio-server)。730MCP servers 也可以呼叫 `roots/list` 請求以在執行時讀取工作階段的工作目錄。請參閱[`roots/list` 傳回的內容以及 Claude Code 何時通知伺服器變更](/docs/zh-TW/mcp#option-3-add-a-local-stdio-server)。

731 731

732<h4 id="persistent-data-directory">732<h4 id="persistent-data-directory">

733 持久資料目錄733 持久資料目錄

895| **Executables** | `bin/` | 新增到 Bash tool 的 `PATH` 的可執行檔。此處的檔案在 plugin 啟用時可在任何 Bash tool 呼叫中作為裸命令叫用 |895| **Executables** | `bin/` | 新增到 Bash tool 的 `PATH` 的可執行檔。此處的檔案在 plugin 啟用時可在任何 Bash tool 呼叫中作為裸命令叫用 |

897 897

898***898***

899 899

942| `mcp` | 一個 `.mcp.json`，包含 HTTP 和 stdio server 範例 |942| `mcp` | 一個 `.mcp.json`，包含 HTTP 和 stdio server 範例 |

943| `lsp` | 一個 `.lsp.json` 語言伺服器範例 |943| `lsp` | 一個 `.lsp.json` 語言伺服器範例 |

946 946

947搭建的 plugin 使用 `@skills-dir` 來源而不是 marketplace。管理員可以使用 `strictKnownMarketplaces` 或透過在 [managed settings](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) 中新增 `{"source": "skills-dir"}` 到 `blockedMarketplaces` 來阻止此來源。當被阻止時，`plugin init` 在寫入前失敗。947搭建的 plugin 使用 `@skills-dir` 來源而不是 marketplace。管理員可以使用 `strictKnownMarketplaces` 或透過在 [managed settings](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) 中新增 `{"source": "skills-dir"}` 到 `blockedMarketplaces` 來阻止此來源。當被阻止時，`plugin init` 在寫入前失敗。

948 948

949**範例：**949**範例：**

950 950

1032 plugin prune1032 plugin prune

1033</h3>1033</h3>

1034 1034

1035移除不再被任何已安裝 plugin 所需的自動安裝 plugin 相依性。Claude Code 為滿足另一個 plugin 的 [`dependencies`](/zh-TW/plugin-dependencies) 欄位而引入的相依性會被移除；您直接安裝的 plugins 永遠不會被觸及。1035移除不再被任何已安裝 plugin 所需的自動安裝 plugin 相依性。Claude Code 為滿足另一個 plugin 的 [`dependencies`](/docs/zh-TW/plugin-dependencies) 欄位而引入的相依性會被移除；您直接安裝的 plugins 永遠不會被觸及。

1036 1036

1037```bash theme={null}1037```bash theme={null}

1038claude plugin prune [options]1038claude plugin prune [options]

1059 plugin enable1059 plugin enable

1060</h3>1060</h3>

1061 1061

1062啟用已停用的 plugin。如果 plugin 宣告 [dependencies](/zh-TW/plugin-dependencies)，Claude Code 會在相同範圍內以傳遞方式啟用它們，當相依性未安裝時命令會失敗。1062啟用已停用的 plugin。如果 plugin 宣告 [dependencies](/docs/zh-TW/plugin-dependencies)，Claude Code 會在相同範圍內以傳遞方式啟用它們，當相依性未安裝時命令會失敗。

1063 1063

1064```bash theme={null}1064```bash theme={null}

1065claude plugin enable <plugin> [options]1065claude plugin enable <plugin> [options]

1080 plugin disable1080 plugin disable

1081</h3>1081</h3>

1082 1082

1083停用 plugin 而不卸載它。當另一個已啟用的 plugin [depends on](/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) 目標時失敗。錯誤訊息包含一個鏈式命令，該命令會先停用每個相依項。1083停用 plugin 而不卸載它。當另一個已啟用的 plugin [depends on](/docs/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) 目標時失敗。錯誤訊息包含一個鏈式命令，該命令會先停用每個相依項。

1084 1084

1085```bash theme={null}1085```bash theme={null}

1086claude plugin disable [plugin] [options]1086claude plugin disable [plugin] [options]

1198 plugin tag1198 plugin tag

1199</h3>1199</h3>

1200 1200

1201為 plugin 建立發行版 git 標籤。預設情況下，命令會標記目前目錄中的 plugin；傳遞路徑即可標記其他位置的 plugin。請參閱 [Tag plugin releases](/zh-TW/plugin-dependencies#tag-plugin-releases-for-version-resolution)。1201為 plugin 建立發行版 git 標籤。預設情況下，命令會標記目前目錄中的 plugin；傳遞路徑即可標記其他位置的 plugin。請參閱 [Tag plugin releases](/docs/zh-TW/plugin-dependencies#tag-plugin-releases-for-version-resolution)。

1202 1202

1203```bash theme={null}1203```bash theme={null}

1204claude plugin tag [path] [options]1204claude plugin tag [path] [options]

1364 另請參閱1364 另請參閱

1365</h2>1365</h2>

1366 1366

1367* [Plugins](/zh-TW/plugins) - 教學和實際使用1367* [Plugins](/docs/zh-TW/plugins) - 教學和實際使用

1368* [Plugin marketplaces](/zh-TW/plugin-marketplaces) - 建立和管理 marketplaces1368* [Plugin marketplaces](/docs/zh-TW/plugin-marketplaces) - 建立和管理 marketplaces

1369* [Skills](/zh-TW/skills) - Skill 開發詳細資訊1369* [Skills](/docs/zh-TW/skills) - Skill 開發詳細資訊

1370* [Subagents](/zh-TW/sub-agents) - Agent 設定和功能1370* [Subagents](/docs/zh-TW/sub-agents) - Agent 設定和功能

1371* [Hooks](/zh-TW/hooks) - 事件處理和自動化1371* [Hooks](/docs/zh-TW/hooks) - 事件處理和自動化

1372* [MCP](/zh-TW/mcp) - 外部工具整合1372* [MCP](/docs/zh-TW/mcp) - 外部工具整合

1373* [Settings](/zh-TW/settings) - Plugins 的設定選項1373* [Settings](/docs/zh-TW/settings) - Plugins 的設定選項

troubleshooting.md +18 −14

Details

10 10

11| 症狀 | 前往 |11| 症狀 | 前往 |

12| :-------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |12| :-------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |

14| 更新或安裝下載失敗，出現 `The connection dropped while downloading the update` 或 `aborted` | [錯誤參考](/zh-TW/errors#the-connection-dropped-while-downloading-the-update) |14| 更新或安裝下載失敗，出現 `The connection dropped while downloading the update` 或 `aborted` | [錯誤參考](/docs/zh-TW/errors#the-connection-dropped-while-downloading-the-update) |

15| 登入迴圈、OAuth 錯誤、`403 Forbidden`、「組織已停用」、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證 | [故障排除安裝和登入](/zh-TW/troubleshoot-install#login-and-authentication) |15| 登入迴圈、OAuth 錯誤、`403 Forbidden`、「組織已停用」、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證 | [故障排除安裝和登入](/docs/zh-TW/troubleshoot-install#login-and-authentication) |

16| 設定未套用、hooks 未觸發、MCP 伺服器未載入 | [偵錯您的設定](/zh-TW/debug-your-config) |16| 設定未套用、hooks 未觸發、MCP 伺服器未載入 | [偵錯您的設定](/docs/zh-TW/debug-your-config) |

19| VS Code 擴充功能未連接或未偵測到 Claude | [VS Code 整合](/zh-TW/vs-code#fix-common-issues) |19| VS Code 擴充功能未連接或未偵測到 Claude | [VS Code 整合](/docs/zh-TW/vs-code#fix-common-issues) |

20| JetBrains 外掛程式或 IDE 未偵測到 | [JetBrains 整合](/zh-TW/jetbrains#troubleshooting) |20| JetBrains 外掛程式或 IDE 未偵測到 | [JetBrains 整合](/docs/zh-TW/jetbrains#troubleshooting) |

21| 高 CPU 或記憶體、回應緩慢、掛起、搜尋找不到檔案 | [效能和穩定性](#performance-and-stability)下方 |21| 高 CPU 或記憶體、回應緩慢、掛起、搜尋找不到檔案 | [效能和穩定性](#performance-and-stability)下方 |

22 22

23如果您不確定哪個適用，請在 Claude Code 內執行 `/doctor` 以自動檢查您的安裝、設定、擴充功能和上下文使用情況；它會提議可以在您確認後套用的修復。如果 `claude` 根本無法啟動，請改為從您的 shell 執行 `claude doctor`。執行 `/mcp` 以檢查 MCP 伺服器狀態。23如果您不確定哪個適用，請在 Claude Code 內執行 `/doctor` 以自動檢查您的安裝、設定、擴充功能和上下文使用情況；它會提議可以在您確認後套用的修復。如果 `claude` 根本無法啟動，請改為從您的 shell 執行 `claude doctor`。執行 `/mcp` 以檢查 MCP 伺服器狀態。

371. 定期使用 `/compact` 減少上下文大小371. 定期使用 `/compact` 減少上下文大小

382. 在主要任務之間關閉並重新啟動 Claude Code382. 在主要任務之間關閉並重新啟動 Claude Code

393. 考慮將大型構建目錄新增到您的 `.gitignore` 檔案393. 考慮將大型構建目錄新增到您的 `.gitignore` 檔案

404. 使用 [`claude --safe-mode`](/zh-TW/cli-reference#cli-flags) 重新啟動以檢查外掛程式、MCP 伺服器或 hook 是否為來源。它會停用該工作階段的所有自訂；如果使用量下降，請參閱[偵錯您的設定](/zh-TW/debug-your-config#test-against-a-clean-configuration)以找出是哪一個404. 使用 [`claude --safe-mode`](/docs/zh-TW/cli-reference#cli-flags) 重新啟動以檢查外掛程式、MCP 伺服器或 hook 是否為來源。它會停用該工作階段的所有自訂；如果使用量下降，請參閱[偵錯您的設定](/docs/zh-TW/debug-your-config#test-against-a-clean-configuration)以找出是哪一個

41 41

42如果在這些步驟後記憶體使用仍然很高，請執行 `/heapdump` 以將 JavaScript 堆快照和記憶體分解寫入 `~/Desktop`。在沒有 Desktop 資料夾的 Linux 上，檔案會寫入您的主目錄。42如果在這些步驟後記憶體使用仍然很高，請執行 `/heapdump` 以將 JavaScript 堆快照和記憶體分解寫入 `~/Desktop`。在沒有 Desktop 資料夾的 Linux 上，檔案會寫入您的主目錄。

43 43

44分解顯示駐留集大小、JS 堆、陣列緩衝區和未計算的原生記憶體，這有助於識別增長是在 JavaScript 物件還是原生程式碼中。若要檢查保留者，請在 Chrome DevTools 中的 Memory → Load 下開啟 `.heapsnapshot` 檔案。在 [GitHub](https://github.com/anthropics/claude-code/issues) 上報告記憶體問題時附加兩個檔案。44分解會顯示常駐集合大小、JS 堆積、陣列緩衝區和未計算的原生記憶體，這有助於識別成長是在 JavaScript 物件還是在原生程式碼中。若要檢查保留者，請在 Chrome DevTools 中的 Memory → Load 下開啟 `.heapsnapshot` 檔案；分解是以 `-diagnostics.json` 結尾的檔案。

46<Warning>

47 `.heapsnapshot` 檔案包含程序中的每個字串。請勿將其附加到公開問題或分享。在 [GitHub](https://github.com/anthropics/claude-code/issues) 上報告記憶體問題時，只附加 `-diagnostics.json` 檔案。該檔案包含記憶體統計資訊，不包含任何對話內容或認證。

48</Warning>

45 49

46<h3 id="large-tables-are-cut-off-in-the-terminal">50<h3 id="large-tables-are-cut-off-in-the-terminal">

47 大型表格在終端中被截斷51 大型表格在終端中被截斷

48</h3>52</h3>

49 53

50超過 200 列的 Markdown 表格會呈現其前 200 列，後面跟著 `… N more rows not shown` 行。只有顯示受到限制：完整表格保留在對話中，[`/copy`](/zh-TW/commands) 會複製每一列。對於在終端中太大而無法閱讀的表格，請要求 Claude 改為將其寫入檔案。在 v2.1.208 之前，Claude Code 呈現每一列，因此繼續包含非常大型表格的工作階段可能會在重新呈現時停滯。54超過 200 列的 Markdown 表格會呈現其前 200 列，後面跟著 `… N more rows not shown` 行。只有顯示受到限制：完整表格保留在對話中，[`/copy`](/docs/zh-TW/commands) 會複製每一列。對於在終端中太大而無法閱讀的表格，請要求 Claude 改為將其寫入檔案。在 v2.1.208 之前，Claude Code 呈現每一列，因此繼續包含非常大型表格的工作階段可能會在重新呈現時停滯。

51 55

52<h3 id="auto-compaction-stops-with-a-thrashing-error">56<h3 id="auto-compaction-stops-with-a-thrashing-error">

53 Auto-compaction 停止並出現 thrashing 錯誤57 Auto-compaction 停止並出現 thrashing 錯誤

59 63

601. 要求 Claude 以較小的塊讀取超大檔案，例如特定行範圍或函式，而不是整個檔案641. 要求 Claude 以較小的塊讀取超大檔案，例如特定行範圍或函式，而不是整個檔案

612. 執行 `/compact` 並關注丟棄大輸出，例如 `/compact keep only the plan and the diff`652. 執行 `/compact` 並關注丟棄大輸出，例如 `/compact keep only the plan and the diff`

~~623. 將大檔案工作移動到 [subagent](/zh-TW/sub-agents)，以便它在單獨的上下文視窗中執行~~663. 將大檔案工作移動到 [subagent](/docs/zh-TW/sub-agents)，以便它在單獨的上下文視窗中執行

634. 如果早期對話不再需要，執行 `/clear`674. 如果早期對話不再需要，執行 `/clear`

64 68

65<h3 id="command-hangs-or-freezes">69<h3 id="command-hangs-or-freezes">

77 編輯器整合終端中的文字亂碼或損毀81 編輯器整合終端中的文字亂碼或損毀

78</h3>82</h3>

79 83

80如果在 VS Code、Cursor 或 Devin Desktop 整合終端中執行 Claude Code 時字元呈現為方塊、塗抹或錯誤的字形，終端的 GPU 渲染器可能是原因。在 Claude Code 中執行 `/terminal-setup` 以將 `terminal.integrated.gpuAcceleration` 設定為 `"off"`，或在您的編輯器設定中手動設定並重新載入視窗。請參閱[終端配置](/zh-TW/terminal-config)以了解 `/terminal-setup` 寫入的其他設定。84如果在 VS Code、Cursor 或 Devin Desktop 整合終端中執行 Claude Code 時字元呈現為方塊、塗抹或錯誤的字形，終端的 GPU 渲染器可能是原因。在 Claude Code 中執行 `/terminal-setup` 以將 `terminal.integrated.gpuAcceleration` 設定為 `"off"`，或在您的編輯器設定中手動設定並重新載入視窗。請參閱[終端配置](/docs/zh-TW/terminal-config)以了解 `/terminal-setup` 寫入的其他設定。

81 85

82<h3 id="search-and-discovery-issues">86<h3 id="search-and-discovery-issues">

83 搜尋和發現問題87 搜尋和發現問題

117 </Tab>121 </Tab>

118</Tabs>122</Tabs>

119 123

120然後在您的[環境](/zh-TW/env-vars)中設定 `USE_BUILTIN_RIPGREP=0`。124然後在您的[環境](/docs/zh-TW/env-vars)中設定 `USE_BUILTIN_RIPGREP=0`。

121 125

122<h3 id="slow-or-incomplete-search-results-on-wsl">126<h3 id="slow-or-incomplete-search-results-on-wsl">

123 WSL 上的搜尋速度緩慢或結果不完整127 WSL 上的搜尋速度緩慢或結果不完整

Documentation 2026-07-20 23:01 UTC to 2026-07-21 23:00 UTC