Documentation — Spybara

claude-apps-gateway-deploy.md +108 −37

Details

126 126

127請參閱 [每個機制儲存原則的位置](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy) 以取得檔案路徑，以及 [用戶端受管設定](/docs/zh-TW/claude-apps-gateway-config#client-side-managed-settings) 以取得 Claude Desktop `bootstrapUrl` 等效項。127請參閱 [每個機制儲存原則的位置](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy) 以取得檔案路徑，以及 [用戶端受管設定](/docs/zh-TW/claude-apps-gateway-config#client-side-managed-settings) 以取得 Claude Desktop `bootstrapUrl` 等效項。

128 128

129<h3 id="large-rollouts">

130 大規模推出

131</h3>

132

133登入按用戶端 IP 地址進行速率限制，預設值適合小型團隊。每個地址在每 10 分鐘內獲得 30 次登入開始和 10 次代碼提交。向數千名開發人員的推出可能在第一個早上達到這些限制，原因有兩個：

134

135* **閘道無法看到您的負載平衡器之外。** 沒有 [`listen.trusted_proxies`](/docs/zh-TW/claude-apps-gateway-config#listen)，每個開發人員似乎都來自負載平衡器的地址並共享一個限制。首先設定它。閘道在第一次忽略 `X-Forwarded-For` 標頭時記錄警告。

136* **許多開發人員共享幾個 NAT 或 VPN 出口地址。** 即使 `trusted_proxies` 正確，他們也共享這些地址的限制。提高 [`rate_limits`](/docs/zh-TW/claude-apps-gateway-config#http-tuning) 以適應。

137

138要調整 `max`，將開發人員數除以他們共享的出口地址。估計在一個 `window_seconds` 期間內有多少人登入，預設為 10 分鐘。然後將其加倍以涵蓋重試和登入到 Claude Code 和 Claude Desktop 的開發人員。

139

140例如，10,000 名開發人員在 4 個出口地址後面在一小時內均勻登入。這是每個地址 2,500 名開發人員，每 10 分鐘約 420 名，您將其加倍並四捨五入到 1,000。下面的範例將兩個限制都設定為 1,000：

141

142```yaml theme={null}

143rate_limits:

144 device_authorization: { max: 1000, window_seconds: 600 }

145 device_verify: { max: 1000, window_seconds: 600 }

146```

147

148`device_verify` 是阻止某人猜測另一個開發人員登入代碼的原因，因此只在您的估計需要的範圍內提高它。即使在這些限制下，代碼也是來自 20 字元字母表的 8 個字元，並在 10 分鐘後過期，因此猜測仍然不切實際；請參閱 [使用者代碼暴力破解抵抗](#user-code-brute-force-resistance)。

149

150當您的 IdP 發行重新整理權杖時，Claude Code 會無聲地更新會話，因此您可以在推出後將限制放回。沒有重新整理權杖，開發人員每 [`session.ttl_hours`](/docs/zh-TW/claude-apps-gateway-config#session) 再次登入。同時調整兩個限制的大小以適應該穩定速率，並保持提高。

151

152當達到限制時，Claude Code v2.1.274 或更新版本顯示 `The gateway is limiting sign-in attempts right now`。v2.1.274 或更新版本的閘道在驗證頁面上顯示 `Too many attempts came from your network address`，並提供要檢查的設定。它還寫入 `sign-in refused` 日誌行，命名要變更的設定。

153

129<h2 id="operations">154<h2 id="operations">

130 運營155 操作

131</h2>156</h2>

132 157

133一旦閘道開始提供流量，日常運營就是讀取其日誌、探測其健康狀況，以及按您的時間表輪換其祕密。下面的小節涵蓋每一個，加上 Postgres 持有的內容以及升級和回滾的行為方式。158一旦閘道開始提供流量，日常操作包括讀取其日誌、探測其健康狀態，以及按照您的排程輪換其密鑰。以下小節涵蓋每一項，以及 Postgres 保存的內容，以及升級和回滾的行為方式。

134 159

135<h3 id="logs">160<h3 id="logs">

136 日誌161 日誌

137</h3>162</h3>

138 163

139閘道向 stderr 寫入兩個流，都是 JSON 友好的：164閘道向 stderr 寫入兩個串流，兩者都是 JSON 友善的：

140 165

141* **審計事件**：每個安全相關事件的單行 JSON。將 stderr 管道傳輸到您的日誌聚合器。166* **稽核事件**：每個安全相關事件一行 JSON。將 stderr 導管到您的日誌聚合器。

142 167

143 發出的事件包括 `config.load`、`session.mint`、`session.refresh`、`device.authorize`、`device.verify`、`device.callback`、`auth.denied`、`access.denied`、`access.public_client`、`inference`、`managed.serve`、`desktop_bootstrap.serve`、`desktop_bootstrap.denied`、`spend.blocked`、`admin.denied`、`admin.limit.upsert` 和 `admin.limit.delete`。欄位因事件而異：168 發出的事件包括 `config.load`、`session.mint`、`session.refresh`、`device.authorize`、`device.verify`、`device.callback`、`auth.denied`、`access.denied`、`access.public_client`、`inference`、`managed.serve`、`desktop_bootstrap.serve`、`desktop_bootstrap.denied`、`spend.blocked`、`admin.denied`、`admin.limit.upsert` 和 `admin.limit.delete`。欄位因事件而異：

144 169

145 * 成功的 mint 和 refresh 事件攜帶 `sub`、`email`、`client_ip` 和結果170 * 成功的 mint 和 refresh 事件攜帶 `sub`、`email`、`client_ip` 和結果

146 * `auth.denied` 和 `access.denied` 攜帶原因和用戶端 IP，加上 `auth.denied` 的請求路徑，因為在這些拒絕時不存在使用者身份。兩個 `access.denied` 原因改變事件攜帶的內容：171 * `auth.denied` 和 `access.denied` 攜帶原因和用戶端 IP，加上 `auth.denied` 的請求路徑，因為在這些拒絕時不存在使用者身份。兩個 `access.denied` 原因改變事件攜帶的內容：

147 * `xff_unparseable`：事件也攜帶無法讀取的 `X-Forwarded-For` 項目172 * `xff_unparseable`：事件也攜帶無法讀取的 `X-Forwarded-For` 項目

148 * `client_ip_unknown`：事件不攜帶用戶端 IP，因為連線沒有對等位址，而設定了 `access_control` 清單173 * `client_ip_unknown`：事件不攜帶用戶端 IP，因為連線沒有對等位址，而 `access_control` 清單已設定

149 * `access.public_client` 攜帶在 `access_control.allow_cidrs` 為空時，每個程序從公開位址到達的第一個請求的用戶端 IP。閘道照常提供請求；事件表示閘道可能可從公開網際網路到達。請參閱 [`access_control` 參考](/docs/zh-TW/claude-apps-gateway-config#http-tuning)，了解什麼算作公開以及建議的允許清單。174 * `access.public_client` 攜帶每個程序中第一個從公開位址到達的請求的用戶端 IP，同時 `access_control.allow_cidrs` 為空。閘道照常提供請求；事件表示閘道可能可從公開網際網路到達。請參閱 [`access_control` 參考](/docs/zh-TW/claude-apps-gateway-config#http-tuning)，了解什麼算作公開以及建議的允許清單。

150 * `inference` 記錄哪個上游提供了請求以及回應狀態175 * `inference` 記錄哪個上游提供了請求以及回應狀態

151 * `desktop_bootstrap.denied` 記錄被拒絕的 Claude Desktop bootstrap 擷取，包含原因（`not_configured`、`policy_not_opted_in` 或 `no_policy_matched`）和使用者的身份176 * `desktop_bootstrap.denied` 記錄被拒絕的 Claude Desktop bootstrap 擷取，包含原因（`not_configured`、`policy_not_opted_in` 或 `no_policy_matched`）和使用者的身份

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

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

154 179

155<h3 id="health">180<h3 id="health">

156 健康181 健康狀態

182</h3>

183

184閘道提供 `GET /healthz` 作為活躍性探測，`GET /readyz` 作為就緒性探測；`/readyz` 驗證存放區是否可到達。兩者都豁免於 `access_control.allow_cidrs`，因此探測在鎖定的接聽程式上保持運作。

185

186`/.well-known/oauth-authorization-server` 的 OAuth 探索文件也只在設定載入、OIDC 探索、上游用戶端建構和 Postgres 遷移全部成功後才傳回 `200`，因此它也可作為端對端啟動檢查。

187

188<h3 id="concurrent-upstream-requests">

189 並行上游請求

157</h3>190</h3>

158 191

159閘道提供 `GET /healthz` 作為活躍探針，`GET /readyz` 作為就緒探針；`/readyz` 驗證存儲是否可到達。兩者都豁免於 `access_control.allow_cidrs`，因此探針在鎖定的監聽器上保持工作。192預設情況下，每個閘道複本同時最多向上游傳送 256 個請求。串流回應在串流結束前計入限制。

193

194在複本達到限制時到達的請求在閘道內等待空閒插槽。開發人員看到回應開始緩慢或似乎掛起。在 `provider: anthropic` 上游上，等待時間超過 [`timeouts.upstream_ttfb_ms`](/docs/zh-TW/claude-apps-gateway-config#http-tuning) 的請求放棄該上游，當沒有後續上游提供它時失敗並返回 502。

195

196包含 `upstream requests:` 的啟動日誌行顯示有效的限制。當複本的開啟請求數超過限制時，它也會記錄最多每分鐘一次包含 `client requests are open` 的警告。

160 197

161OAuth 發現文件位於 `/.well-known/oauth-authorization-server` 也只在配置載入、OIDC 發現、上游用戶端構造和 Postgres 遷移全部成功後才傳回 `200`，因此它也充當端到端啟動檢查。198要同時提供更多請求，您有兩個選項：

199

200* 新增複本。

201* 提高每個複本上的限制。在閘道容器上設定 `BUN_CONFIG_MAX_HTTP_REQUESTS` 環境變數為 1 到 65535 之間的整數，然後重新啟動容器。

202

203複本以約限制除以請求保持開啟的平均秒數的請求速率填滿其限制。例如，如果請求平均保持開啟 10 秒，預設限制為 256 的複本以約每秒 26 個請求的速率填滿它。

204

205如果您在 CPU 上自動擴展，達到限制的複本會佇列請求而不觸發橫向擴展，因此將目標設定在複本在記錄 `client requests are open` 警告時顯示的 CPU 級別以下。

206

207<Warning>

208 每個開啟的請求在串流時和等待插槽時在閘道程序中保持記憶體。如果您將限制保持在 256，過載複本上的記憶體仍會增長，因為等待的請求保持其請求本體。根據尖峰時開啟的請求數調整容器的記憶體大小，並在您變更限制時監視記憶體。記憶體不足的複本被殺死並丟棄它保持的每個串流。

209</Warning>

162 210

163<h3 id="outage-behavior">211<h3 id="outage-behavior">

164 中斷行為212 中斷行為

165</h3>213</h3>

166 214

167如果 Postgres 宕機，閘道本身繼續為已簽入的開發人員提供服務，新的簽入失敗。開發人員是否實際保持工作取決於您的協調器如何處理就緒：215如果 Postgres 宕機，閘道本身繼續提供已登入的開發人員，新登入失敗。開發人員是否實際繼續工作取決於您的協調器如何處理就緒性：

168 216

169* **現有會話**：持有人令牌使用 JWT 祕密在本地驗證，會話重新整理不接觸存儲，閘道程序仍然可以提供推理217* **現有工作階段**：持有人令牌使用 JWT 密鑰在本地驗證，工作階段重新整理不接觸存放區，閘道程序仍可提供推論

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

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

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

173 221

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

175 223

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

177 JWT 祕密輪換225 JWT 密鑰輪換

178</h3>226</h3>

179 227

180分三個步驟輪換簽名祕密，以便現有會話保持有效：228分階段輪換簽署密鑰，以便現有工作階段保持有效：

181 229

1821. 生成新祕密。將其前置到 `session.jwt_secret` 陣列。2301. 產生新密鑰。將其前置到 `session.jwt_secret` 陣列。

1832. 滾動部署。新令牌使用新祕密簽名；舊令牌仍然驗證。2312. 推出部署。新令牌使用新密鑰簽署；舊令牌仍驗證。

1843. 在 `ttl_hours` 加上邊距後，移除舊祕密並再次滾動。2323. 在 `ttl_hours` 加上邊際後，移除舊密鑰並再次推出。

185 233

186輪換也是在它們過期之前強制會話退出的唯一方法：持有人令牌根據 JWT 祕密在本地驗證，因此沒有按會話撤銷。直接替換祕密，不在陣列中保留舊祕密，一次使每個未完成的會話無效。對於個別離職，在您的 IdP 中取消配置使用者；他們的會話在 `ttl_hours` 內結束。234輪換也是在過期前強制工作階段退出的唯一方式：持有人令牌針對 JWT 密鑰在本地驗證，因此不存在每個工作階段的撤銷。直接替換密鑰，不在陣列中保持舊密鑰，立即使每個未完成的工作階段失效。對於個別離職，在您的 IdP 中取消配置使用者；其工作階段在 `ttl_hours` 內結束。

187 235

188<h3 id="postgres">236<h3 id="postgres">

189 Postgres237 Postgres

190</h3>238</h3>

191 239

192閘道持有五個資料表加上一個 `_migrations` 表，全部由其啟動時遷移建立：240閘道保持五個資料表加上 `_migrations` 表，全部由其啟動時遷移建立：

193 241

194| 表 | 內容 | 保留 |242| 表 | 內容 | 保留 |

195| ------------------ | ------------------------------------- | --------------------------------------------- |243| ------------------ | ------------------------------------- | -------------------------------------------- |

196| `kv` | 設備授予（10 分鐘 TTL）和速率限制計數器 | 每行 TTL |244| `kv` | 裝置授予（10 分鐘 TTL）和速率限制計數器 | 每行 TTL |

201 249

20230 秒迴圈過期 `kv` 行超過其 TTL，每小時掃描在支出表上強制保留窗口，因此沒有任何東西無限增長。沒有 [支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits) 配置，只有 `kv` 被寫入。閘道在啟動時應用其自己的架構遷移，以及在每次升級時，因此其資料庫角色需要建立和更改表的權限。將其指向專用於閘道的資料庫或架構，以保持該授予狹窄。25030 秒迴圈過期 `kv` 行超過其 TTL，每小時掃描在支出表上強制保留視窗，因此沒有任何東西無限增長。沒有[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)已設定，只有 `kv` 被寫入。閘道在啟動和每次升級時應用其自己的架構遷移，因此其資料庫角色需要建立和更改表的權限。將其指向專用於閘道的資料庫或架構，以保持該授予狹窄。

203 251

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

205 253

206<h3 id="upgrades">254<h3 id="upgrades">

207 升級255 升級

208</h3>256</h3>

209 257

210副本是無狀態的，因此滾動重新啟動在任何時間都是安全的。閘道在啟動時執行架構遷移，這意味著部署新二進位檔案自我遷移資料庫。並行副本在 Postgres 諮詢鎖上序列化，因此只有一個應用每個遷移。258複本是無狀態的，因此滾動重新啟動不會遺失閘道狀態。閘道在啟動時執行架構遷移，這意味著部署新二進位檔案自動遷移資料庫。並行複本在 Postgres 諮詢鎖上序列化，因此只有一個應用每個遷移。

259

260當您的協調器使用 `SIGTERM` 停止複本時，如在滾動重新啟動或縮減中，閘道停止接受新連線並讓已在進行中的請求和串流在退出前完成。它等待最多 25 秒，稱為排放視窗，然後關閉仍然開啟的任何東西。`SIGINT`（例如終端中的 Ctrl+C）啟動相同的排放，排放期間的第二個信號關閉開啟的請求並立即退出。排放需要閘道 v2.1.274 或更新版本。

261

262長代代可以串流數分鐘。在 Kubernetes 和 Amazon ECS 上，將這兩者一起提高以給予這些串流更多時間：

211 263

212遷移是僅附加的，因此回滾到知道較少遷移的先前二進位檔案是安全的；它忽略額外的行。回滾也根據較舊二進位檔案的架構重新驗證 YAML，因此採用較新版本引入的金鑰的配置在較舊版本上啟動失敗。在回滾之前移除新金鑰。264* **排放視窗**：在閘道容器上設定 `CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS` 環境變數為正整數毫秒數，例如 `120000`。閘道忽略任何其他形式的值，例如 `120s`，並保持 25 秒預設

265* **您的協調器的寬限期**：Kubernetes 上的 `terminationGracePeriodSeconds`，或 Amazon ECS 上的 `stopTimeout`

213 266

214因為您在自己的映像中固定閘道的版本，新 Claude Code 版本中的修復，包括安全修復，只有在您更新固定並重新部署時才會到達您的部署。將閘道包含在您用於持有生產認證的其他服務的相同修補週期中。267寬限期在兩個平台上預設為 30 秒。將其保持至少比排放視窗長 5 秒，否則協調器在排放完成前殺死閘道。在 Kubernetes 上，也新增任何 `preStop` 鉤子的持續時間，因為寬限期在鉤子執行前開始計數，而不是當閘道接收 `SIGTERM` 時。

268

269您的平台也可能限制排放可以執行多長時間：

270

271* **Amazon ECS on Fargate**：`stopTimeout` 最多允許 120 秒

272* **Cloud Run**：在 `SIGTERM` 後 10 秒停止實例，因此開啟的串流在那裡最多獲得 10 秒，無論排放視窗是什麼

273

274當排放視窗結束時仍有開啟的請求，閘道記錄包含 `drain window over after` 的警告，計數它切割的請求，並命名兩個要提高的設定。

275

276遷移是僅附加的，因此回滾到知道較少遷移的先前二進位檔案是安全的；它忽略額外的行。回滾也針對較舊二進位檔案的架構重新驗證 YAML，因此採用由較新版本引入的金鑰的設定在較舊版本上啟動失敗。在回滾前移除新金鑰。

277

278因為您在自己的映像中固定閘道的版本，新 Claude Code 版本中的修復（包括安全修復）僅在您更新固定並重新部署時到達您的部署。將閘道包含在您用於保持生產認證的其他服務的相同修補排程中。

215 279

216<h2 id="security">280<h2 id="security">

217 安全281 安全

239 303

240* 開發人員持有短期 JWT 而不是原始上游金鑰。CLI 到閘道的腿使用 RFC 8628 設備授予，閘道與 IdP 的授權碼交換在預設配置中執行 PKCE，因此攔截的 IdP 授權碼是無用的。304* 開發人員持有短期 JWT 而不是原始上游金鑰。CLI 到閘道的腿使用 RFC 8628 設備授予，閘道與 IdP 的授權碼交換在預設配置中執行 PKCE，因此攔截的 IdP 授權碼是無用的。

241* 設備驗證頁面強制執行同源 POST 和根據 RFC 8628 §5.1 的每 IP 速率限制。請參閱 [使用者代碼暴力破解抵抗](#user-code-brute-force-resistance)。305* 設備驗證頁面強制執行同源 POST 和根據 RFC 8628 §5.1 的每 IP 速率限制。請參閱 [使用者代碼暴力破解抵抗](#user-code-brute-force-resistance)。

242* 出站請求通過伺服器端請求偽造 (SSRF) 防護，解析 DNS、阻止連結本地和雲端中繼資料地址加上預設環回，並將連接固定到解析的 IP，因此操作員影響的 URL（例如 IdP 和 OTLP 目的地）無法重新導向到雲端中繼資料端點。RFC 1918 私有範圍被刻意允許，因為 IdP 和 OTLP 收集器通常存在於私有 IP 上。只有當閘道必須到達的東西合法地存在於環回上時，才在閘道的環境中設定 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`，例如本地開發 IdP 或 `localhost` 上的邊車 OTLP 收集器。該變數放寬每個操作員配置的 URL 的環回阻止，也跳過啟動時檢查 pod 是否可以到達雲端中繼資料端點的警告，因此偏好為收集器提供自己的內部地址。306* 閘道對您的 IdP、您的 OTLP 收集器和 `provider: anthropic` 上游的請求通過伺服器端請求偽造 (SSRF) 防護，解析 DNS、阻止連結本地和雲端中繼資料地址加上預設環回，並將連接固定到解析的 IP，因此操作員影響的 URL 無法重新導向到雲端中繼資料端點。RFC 1918 私有範圍被刻意允許，因為 IdP 和 OTLP 收集器通常存在於私有 IP 上。對於其他提供者，閘道在載入配置時拒絕命名這些地址或中繼資料主機名的 `base_url`，提供者的 SDK 隨後連接而不進行 DNS 檢查。

307

308 如果您開啟 [僅代理出口](/docs/zh-TW/claude-apps-gateway-config#proxy-only-egress)，該地址檢查會移至您的轉發代理：閘道交付主機名，代理的允許清單必須拒絕這些目的地。

309

310 只有當閘道必須到達的東西合法地存在於環回上時，才在閘道的環境中設定 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`，例如本地開發 IdP 或 `localhost` 上的邊車 OTLP 收集器。該變數放寬每個操作員配置的 URL 的環回阻止，也跳過啟動時檢查 pod 是否可以到達雲端中繼資料端點的警告，因此偏好為收集器提供自己的內部地址。

243 311

244如果您新增自己的出口控制，閘道必須在使用工作負載身份等實例中繼資料認證時到達中繼資料伺服器。312如果您新增自己的出口控制，閘道必須在使用工作負載身份等實例中繼資料認證時到達中繼資料伺服器。

245 313

254 322

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

256 324

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

258 326

259<h3 id="compliance-posture">327<h3 id="compliance-posture">

260 合規性態勢328 合規性態勢

291| 啟動顯示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 已安裝的 Claude Code 組建早於 gateway 支援 | 讓開發者將 Claude Code 更新到包含 Cloud gateway 支援的版本 |359| 啟動顯示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 已安裝的 Claude Code 組建早於 gateway 支援 | 讓開發者將 Claude Code 更新到包含 Cloud gateway 支援的版本 |

292| 啟動結束，顯示 `Administrator policy requires a Cloud gateway sign-in on this machine` | 開發者的環境設定了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`、其設定配置了 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper)，或來自較早 Claude Console 登入的 API 金鑰仍然被儲存 | 讓開發者清除每個適用的項目：取消設定變數、移除 `apiKeyHelper` 項目，或執行 `claude auth logout` 以移除已儲存的金鑰。然後讓他們啟動 `claude` 並使用 `/login` 登入。另請參閱[系統管理員原則要求 Cloud gateway 登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。 |360| 啟動結束，顯示 `Administrator policy requires a Cloud gateway sign-in on this machine` | 開發者的環境設定了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`、其設定配置了 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper)，或來自較早 Claude Console 登入的 API 金鑰仍然被儲存 | 讓開發者清除每個適用的項目：取消設定變數、移除 `apiKeyHelper` 項目，或執行 `claude auth logout` 以移除已儲存的金鑰。然後讓他們啟動 `claude` 並使用 `/login` 登入。另請參閱[系統管理員原則要求 Cloud gateway 登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。 |

293| 啟動或 `/login` 在受管設定載入時出現 403 後報告 `Claude Code may not be enabled for your organization` | gateway 或其前面的某個東西以 403 回應了 `/managed/settings` 請求。gateway 自己的設定路由永遠不會回應 403。狀態來自 [`access_control`](/docs/zh-TW/claude-apps-gateway-config#http-tuning) IP 檢查或來自 gateway 前面的代理或 WAF。稽核日誌將 IP 檢查拒絕記錄為 `access.denied`，並附上原因。開發者保持登入狀態。 | 檢查稽核日誌中失敗時的 `access.denied`，並修正 `access_control` 清單或前端，然後讓開發者再次啟動 `claude` |361| 啟動或 `/login` 在受管設定載入時出現 403 後報告 `Claude Code may not be enabled for your organization` | gateway 或其前面的某個東西以 403 回應了 `/managed/settings` 請求。gateway 自己的設定路由永遠不會回應 403。狀態來自 [`access_control`](/docs/zh-TW/claude-apps-gateway-config#http-tuning) IP 檢查或來自 gateway 前面的代理或 WAF。稽核日誌將 IP 檢查拒絕記錄為 `access.denied`，並附上原因。開發者保持登入狀態。 | 檢查稽核日誌中失敗時的 `access.denied`，並修正 `access_control` 清單或前端，然後讓開發者再次啟動 `claude` |

362| CLI `/login`：`The gateway is limiting sign-in attempts right now`，或在較舊版本上 `Request failed with status code 429`。`/device` 頁面可能對尚未嘗試過的開發者顯示 `Too many attempts` | 達到了每個 IP 的登入速率限制。要麼 `listen.trusted_proxies` 不涵蓋負載平衡器，所以每個開發者共享其位址，要麼許多開發者共享 NAT 或 VPN 出口位址。具有 `result: rate_limited` 的稽核事件顯示相同的一個或幾個 `client_ip` 值。 | 首先將 `listen.trusted_proxies` 設定為負載平衡器的來源範圍，然後如果開發者仍然共享位址，請提高 `rate_limits`。請參閱[大規模推出](#large-rollouts)。 |

294| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway 主機名稱解析為至少一個公開 IP 位址。Claude Code 檢查每個已解析的位址，並要求每個位址都是私有的。常見原因是雙堆疊名稱，其中一個系列解析為公開位址，包括 AWS 內部雙堆疊負載平衡器，它們傳回公開範圍的 AAAA 位址。 | 讓 gateway 名稱在開發者機器上只解析為私有位址。對於雙堆疊名稱，請刪除公開範圍記錄或提供單獨的僅限內部 DNS 名稱。請參閱[私有網路先決條件](/docs/zh-TW/claude-apps-gateway#prerequisites)。如果位址是您的組織擁有並在內部使用的公開空間，請改為[宣告該區塊](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。 |363| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway 主機名稱解析為至少一個公開 IP 位址。Claude Code 檢查每個已解析的位址，並要求每個位址都是私有的。常見原因是雙堆疊名稱，其中一個系列解析為公開位址，包括 AWS 內部雙堆疊負載平衡器，它們傳回公開範圍的 AAAA 位址。 | 讓 gateway 名稱在開發者機器上只解析為私有位址。對於雙堆疊名稱，請刪除公開範圍記錄或提供單獨的僅限內部 DNS 名稱。請參閱[私有網路先決條件](/docs/zh-TW/claude-apps-gateway#prerequisites)。如果位址是您的組織擁有並在內部使用的公開空間，請改為[宣告該區塊](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。 |

295| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於 gateway 主機，且代理的主機名稱解析為公開位址。主機名稱只解析為私有位址的代理是允許的，不會觸發此錯誤 | 在開發者的機器上將 gateway 主機新增到 `NO_PROXY`，以便連線是直接的，或使用主機名稱解析為私有位址的代理。訊息會命名要新增的確切 `NO_PROXY` 項目 |364| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於 gateway 主機，且代理的主機名稱解析為公開位址。主機名稱只解析為私有位址的代理是允許的，不會觸發此錯誤 | 在開發者的機器上將 gateway 主機新增到 `NO_PROXY`，以便連線是直接的，或使用主機名稱解析為私有位址的代理。訊息會命名要新增的確切 `NO_PROXY` 項目 |

296| CLI `/login`：`Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | gateway 位於 [`gatewayInternalNetworks`](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中宣告的區塊上，開發者的機器從該區塊外的位址到達它：VPN 位址池、容器或 WSL2 NAT 區段，或不是您的網路 | 讓開發者從您網路上的主機 OS 執行 `/login`。如果顯示的位址也是您組織自己的公開空間，請將 gateway 的項目替換為涵蓋兩者的區塊，最多 `/8`；第二個重疊項目會被拒絕 |365| CLI `/login`：`Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | gateway 位於 [`gatewayInternalNetworks`](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中宣告的區塊上，開發者的機器從該區塊外的位址到達它：VPN 位址池、容器或 WSL2 NAT 區段，或不是您的網路 | 讓開發者從您網路上的主機 OS 執行 `/login`。如果顯示的位址也是您組織自己的公開空間，請將 gateway 的項目替換為涵蓋兩者的區塊，最多 `/8`；第二個重疊項目會被拒絕 |

302| 啟動結束，顯示命名 `store.postgres_url` 的設定驗證錯誤 | 未設定 Postgres；gateway 需要 Postgres | 設定 `store.postgres_url`。對於本機開發，請使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |371| 啟動結束，顯示命名 `store.postgres_url` 的設定驗證錯誤 | 未設定 Postgres；gateway 需要 Postgres | 設定 `store.postgres_url`。對於本機開發，請使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |

304| 啟動結束，在 `config.load` 後出現 OIDC 探索錯誤 | `oidc.issuer` 無法到達，或 TLS 鏈不受信任 | 檢查發行者是否可從 pod 到達並提供 `/.well-known/openid-configuration`。為私有 PKI 設定 `ca_cert_pem`。如果 pod 只能通過轉發代理到達 IdP，請設定 [`oidc.use_proxy: true`](/docs/zh-TW/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改為給 pod 一條到 IdP 每個端點的直接路由。 |373| 啟動結束，在 `config.load` 後出現 OIDC 探索錯誤 | `oidc.issuer` 無法到達，或 TLS 鏈不受信任 | 檢查發行者是否可從 pod 到達並提供 `/.well-known/openid-configuration`。為私有 PKI 設定 `ca_cert_pem`。如果 pod 只能通過轉發代理到達 IdP，請設定 [`oidc.use_proxy: true`](/docs/zh-TW/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改為給 pod 一條到 IdP 每個端點的直接路由。如果 pod 也無法解析 IdP 的主機名稱，或代理拒絕 `CONNECT` 到 IP 位址，請參閱[僅代理出口](/docs/zh-TW/claude-apps-gateway-config#proxy-only-egress)，這需要 v2.1.277 或更新版本。 |

375| 日誌：`could not connect to Postgres at boot, attempt 1 of 3` | 當 gateway 啟動時資料庫無法到達，例如在冷執行個體上，其網路仍在啟動中 | 如果 gateway 隨後完成啟動，則無需採取任何行動。當資料庫無法到達時，gateway 在結束前嘗試連線三次，間隔兩秒。如果它結束時顯示 `could not connect to Postgres`，請檢查 `store.postgres_url` 和到資料庫的網路路徑。如果嘗試逾時而不是被拒絕，請提高 [`store.connect_timeout_seconds`](/docs/zh-TW/claude-apps-gateway-config#store) 以給每個嘗試更長的時間。 |

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

307| 日誌：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 預設不在 id\_token 中包含 `email`。此拒絕僅在設定 `allowed_email_domains` 時觸發；沒有它，遺漏的電子郵件會建立沒有電子郵件的工作階段 | 設定 IdP 在 id\_token 中發出 `email`。Okta：將 `email` 新增到自訂授權伺服器的 ID 令牌宣告。Entra：在應用程式註冊上新增 `email` 作為選用宣告。PingFederate：啟用發出 `email` 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 `email` 但不會在 id\_token 中包含它，例如 Okta 組織授權伺服器，請設定 `oidc.userinfo_fallback: true`。 |377| 日誌：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 預設不在 id\_token 中包含 `email`。此拒絕僅在設定 `allowed_email_domains` 時觸發；沒有它，遺漏的電子郵件會建立沒有電子郵件的工作階段 | 設定 IdP 在 id\_token 中發出 `email`。Okta：將 `email` 新增到自訂授權伺服器的 ID 令牌宣告。Entra：在應用程式註冊上新增 `email` 作為選用宣告。PingFederate：啟用發出 `email` 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 `email` 但不會在 id\_token 中包含它，例如 Okta 組織授權伺服器，請設定 `oidc.userinfo_fallback: true`。 |

308| 日誌：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，開發者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了重新整理令牌但沒有隨之傳回 id\_token，所以 gateway 詢問了 IdP 的 userinfo 端點以取得使用者的宣告。IdP 在那裡拒絕了重新整理的存取令牌。gateway 回應 `temporarily_unavailable`，所以 Claude Code 保留重新整理令牌但無法更新工作階段。v2.1.260 之前的 gateway 版本記錄相同的行，但沒有 `(at …)` 詳細資訊。 | 設定 [`oidc.scope_on_refresh: true`](/docs/zh-TW/claude-apps-gateway-config#oidc)（在 gateway v2.1.260 或更新版本中可用），以便重新整理請求再次要求 `openid`。某些 IdP（例如 Okta）僅在被要求時才在重新整理時傳回 id\_token。在 PingFederate 上，改為在 **Applications > OAuth > OpenID Connect Policy Management** 下啟用 **Return ID Token On Refresh Grant**。該金鑰不會改變 PingFederate 的行為。對於仍然省略它的其他 IdP，檢查 userinfo 端點是否接受由重新整理發出的存取令牌。作為臨時解決方案，提高 [`session.ttl_hours`](/docs/zh-TW/claude-apps-gateway-config#session)。請參閱[身分提供者設定](#identity-provider-setup)以了解取消佈建權衡。 |378| 日誌：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，開發者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了重新整理令牌但沒有隨之傳回 id\_token，所以 gateway 詢問了 IdP 的 userinfo 端點以取得使用者的宣告。IdP 在那裡拒絕了重新整理的存取令牌。gateway 回應 `temporarily_unavailable`，所以 Claude Code 保留重新整理令牌但無法更新工作階段。v2.1.260 之前的 gateway 版本記錄相同的行，但沒有 `(at …)` 詳細資訊。 | 設定 [`oidc.scope_on_refresh: true`](/docs/zh-TW/claude-apps-gateway-config#oidc)（在 gateway v2.1.260 或更新版本中可用），以便重新整理請求再次要求 `openid`。某些 IdP（例如 Okta）僅在被要求時才在重新整理時傳回 id\_token。在 PingFederate 上，改為在 **Applications > OAuth > OpenID Connect Policy Management** 下啟用 **Return ID Token On Refresh Grant**。該金鑰不會改變 PingFederate 的行為。對於仍然省略它的其他 IdP，檢查 userinfo 端點是否接受由重新整理發出的存取令牌。作為臨時解決方案，提高 [`session.ttl_hours`](/docs/zh-TW/claude-apps-gateway-config#session)。請參閱[身分提供者設定](#identity-provider-setup)以了解取消佈建權衡。 |

309| 每個 Amazon Bedrock 請求都傳回 502；日誌顯示 `Could not load credentials from any providers` | 在 EC2 上，IMDSv2 的預設躍點限制為 1 會阻止來自容器內的執行個體中繼資料請求。啟動和 `/readyz` 仍然通過，因為 AWS SDK 在第一個請求時解析執行個體認證，而不是在用戶端建構時 | 使用 `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` 提高躍點限制，或在啟動範本中設定它。變更適用於執行個體上的每個容器。在可用的地方優先使用 ECS 工作角色，它們從 ECS 容器認證端點讀取認證並完全避免變更，或在專用 gateway 執行個體上應用變更以限制暴露。 |379| 每個 Amazon Bedrock 請求都傳回 502；日誌顯示 `Could not load credentials from any providers` | 在 EC2 上，IMDSv2 的預設躍點限制為 1 會阻止來自容器內的執行個體中繼資料請求。啟動和 `/readyz` 仍然通過，因為 AWS SDK 在第一個請求時解析執行個體認證，而不是在用戶端建構時 | 使用 `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` 提高躍點限制，或在啟動範本中設定它。變更適用於執行個體上的每個容器。在可用的地方優先使用 ECS 工作角色，它們從 ECS 容器認證端點讀取認證並完全避免變更，或在專用 gateway 執行個體上應用變更以限制暴露。 |

380| 在尖峰負載時，回應開始緩慢或似乎掛起，或在上游健康時失敗，顯示 502 `all upstreams failed` | 副本開啟的請求比它一次傳送到上游的請求多，所以額外的請求在 gateway 內等待。在 `provider: anthropic` 上游上，等待時間超過 `timeouts.upstream_ttfb_ms` 的請求會放棄該上游，當沒有後來的上游提供它時會產生 502。日誌顯示包含 `client requests are open` 的警告。 | 新增副本，或提高每個副本上的限制。請參閱[並行上游請求](#concurrent-upstream-requests)。 |

claude-apps-gateway-on-aws.md +1 −1

Details

503| Bedrock 請求傳回 `403 AccessDeniedException` | 帳戶尚未提交 Anthropic 的一次性使用案例表單，自動 AWS Marketplace 訂閱在帳戶的第一次叫用時啟動尚未完成，或任務角色的原則缺少推論設定檔或基礎模型 ARN | 從 Bedrock 主控台的模型目錄提交使用案例表單；如果剛剛提交或這是帳戶的第一次叫用，請在幾分鐘後重試。在兩個 ARN 系列上授予 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream`。 |503| Bedrock 請求傳回 `403 AccessDeniedException` | 帳戶尚未提交 Anthropic 的一次性使用案例表單，自動 AWS Marketplace 訂閱在帳戶的第一次叫用時啟動尚未完成，或任務角色的原則缺少推論設定檔或基礎模型 ARN | 從 Bedrock 主控台的模型目錄提交使用案例表單；如果剛剛提交或這是帳戶的第一次叫用，請在幾分鐘後重試。在兩個 ARN 系列上授予 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream`。 |

505| ECS 任務在 gateway 記錄任何內容之前停止，出現 `ResourceInitializationError` | 執行角色無法讀取 Secrets Manager 機密，或私有子網沒有到 Secrets Manager 或 ECR 的路徑 | 在三個 `gateway-` 機密的 ARN 上授予 `secretsmanager:GetSecretValue` 給執行角色，並透過 NAT 閘道提供出站，或沒有一個，Secrets Manager、ECR 和 CloudWatch Logs 的介面端點，`awslogs` 驅動程式在同一階段需要，加上 S3 閘道端點 |505| ECS 任務在 gateway 記錄任何內容之前停止，出現 `ResourceInitializationError` | 執行角色無法讀取 Secrets Manager 機密，或私有子網沒有到 Secrets Manager 或 ECR 的路徑 | 在三個 `gateway-` 機密的 ARN 上授予 `secretsmanager:GetSecretValue` 給執行角色，並透過 NAT 閘道提供出站，或沒有一個，Secrets Manager、ECR 和 CloudWatch Logs 的介面端點，`awslogs` 驅動程式在同一階段需要，加上 S3 閘道端點 |

507| Gateway 啟動退出，出現 Postgres TLS 憑證驗證錯誤 | 連接字串設定 `sslmode=verify-full` 但映像不信任 RDS CA 套件：套件未複製到映像中，或 `NODE_EXTRA_CA_CERTS` 不指向它 | 新增建置步驟的兩個 Dockerfile 行，複製套件並設定 `NODE_EXTRA_CA_CERTS`，然後重建、在新標籤下推送並重新部署 |507| Gateway 啟動退出，出現 Postgres TLS 憑證驗證錯誤 | 連接字串設定 `sslmode=verify-full` 但映像不信任 RDS CA 套件：套件未複製到映像中，或 `NODE_EXTRA_CA_CERTS` 不指向它 | 新增建置步驟的兩個 Dockerfile 行，複製套件並設定 `NODE_EXTRA_CA_CERTS`，然後重建、在新標籤下推送並重新部署 |

508| 串流回應在安靜期間中途掉落 | v2.1.229 之前的 gateway 在 Bedrock 或 Claude Platform on AWS 上游上在上游安靜時不發送任何內容，例如沒有串流輸出的擴展思考。ALB 預設在 60 秒後沒有資料的連接關閉，因此它在該間隙處切斷串流。v2.1.229 及更新版本的 gateway 在該逾時下保持安靜串流：在這些上游上，gateway 在大約 15 秒後沒有串流資料時發出 SSE `ping` 事件，在 Anthropic API 上游上它中繼 API 自己的 ping | 將 gateway 更新到 v2.1.229 或更新版本，或透過 `modify-load-balancer-attributes` 或 EKS 上的 `load-balancer-attributes` Ingress 註釋將 `idle_timeout.timeout_seconds` 屬性設定為 `3600` |508| 串流回應在安靜期間中途掉落 | v2.1.229 之前的 gateway 在 Bedrock 或 Claude Platform on AWS 上游上在上游安靜時不發送任何內容，例如沒有串流輸出的擴展思考。ALB 預設在 60 秒後沒有資料的連接關閉，因此它在該間隙處切斷串流。v2.1.229 及更新版本的 gateway 在該逾時下保持安靜串流：在這些上游上，gateway 在大約 15 秒後沒有串流資料時發出 SSE `ping` 事件，在 Anthropic API 上游上它中繼 API 自己的 ping | 將 gateway 更新到 v2.1.229 或更新版本，或透過 `modify-load-balancer-attributes` 或 EKS 上的 `load-balancer-attributes` Ingress 註釋將 `idle_timeout.timeout_seconds` 屬性設定為 `3600` |

509 509

claude-apps-gateway-on-gcp.md +1 −1

Details

319| `--no-invoker-iam-check` 被拒絕，出現 `invoker_iam_disabled is not currently available` | 被 `constraints/run.managed.requireInvokerIam` 阻止 | 使用 `--allow-unauthenticated`。如果透過 `constraints/iam.allowedPolicyMemberDomains` 的網域受限共用也阻止了它，請使用 GKE 路徑，它在網路層公開閘道，無需 `allUsers` 繫結。 |319| `--no-invoker-iam-check` 被拒絕，出現 `invoker_iam_disabled is not currently available` | 被 `constraints/run.managed.requireInvokerIam` 阻止 | 使用 `--allow-unauthenticated`。如果透過 `constraints/iam.allowedPolicyMemberDomains` 的網域受限共用也阻止了它，請使用 GKE 路徑，它在網路層公開閘道，無需 `allUsers` 繫結。 |

321| 閘道啟動在 Cloud Run 上以 Postgres 連線逾時錯誤退出 | 服務未附加到 VPC，或 Cloud SQL 在該 VPC 上沒有私有 IP；儲存在 5 秒後停止等待 | 使用 `--network` 和 `--subnet` 部署以進行直接 VPC 出口，並使用 `--no-assign-ip` 和指向相同 VPC 的 `--network` 建立 Cloud SQL 執行個體 |321| 閘道啟動在 Cloud Run 上以 Postgres 連線逾時錯誤退出 | 服務未附加到 VPC，或 Cloud SQL 在該 VPC 上沒有私有 IP | 使用 `--network` 和 `--subnet` 部署以進行直接 VPC 出口，並使用 `--no-assign-ip` 和指向相同 VPC 的 `--network` 建立 Cloud SQL 執行個體 |

322| Google Cloud 的 Agent Platform 請求返回 `403 PERMISSION_DENIED` | 執行時未使用 `claude-gateway` 服務帳戶，或模型未在 Model Garden 中為專案啟用 | 在 Cloud Run 上設定 `--service-account` 或在 GKE 上繫結 Workload Identity，並在 Model Garden 中為目標區域啟用每個 Claude 模型 |322| Google Cloud 的 Agent Platform 請求返回 `403 PERMISSION_DENIED` | 執行時未使用 `claude-gateway` 服務帳戶，或模型未在 Model Garden 中為專案啟用 | 在 Cloud Run 上設定 `--service-account` 或在 GKE 上繫結 Workload Identity，並在 Model Garden 中為目標區域啟用每個 Claude 模型 |

324 324

cloud-environments.md +11 −4

Details

164 封存環境164 封存環境

165</h3>165</h3>

166 166

167若要封存環境，請開啟它進行編輯並選擇**封存**。您無法刪除環境，只能封存它。167若要封存您自己的環境之一，請開啟它進行編輯並選擇**封存**。擁有者從管理設定中的**雲端環境**頁面封存[共用環境](#organization-shared-environments)。您無法刪除環境，只能封存它。

168 168

169封存會影響新工作階段，而不是執行中的工作階段：169封存會影響新工作階段，而不是執行中的工作階段：

170 170

177 組織共用環境177 組織共用環境

178</h3>178</h3>

179 179

180在 Team 和 Enterprise 方案上，擁有者可以建立與組織的每個成員共用的雲端環境。相同的角色管理**雲端環境**管理頁面上的所有其他內容，包括[自託管環境](/docs/zh-TW/self-hosted-environments)；管理員角色無法開啟該頁面。可以開啟它的完整角色清單是[管理伺服器管理的設定](/docs/zh-TW/server-managed-settings#access-control)的角色清單。共用環境與個人環境一起出現在每個成員的環境選擇器中，因此團隊可以標準化一個設定，而不是每個成員重新建立它。180在 Team 和 Enterprise 方案上，擁有者可以建立與組織的每個成員共用的雲端環境。相同的角色管理**雲端環境**管理頁面上的所有其他內容，包括[自託管環境](/docs/zh-TW/self-hosted-environments)；管理員角色無法開啟該頁面。可以開啟它的完整角色清單是[管理伺服器管理的設定](/docs/zh-TW/server-managed-settings#access-control)的角色清單。

181 181

182從 [admin 設定](https://claude.ai/admin-settings)中的**雲端環境**頁面建立、編輯和封存共用環境。共用環境也可以從 [claude.ai/code](https://claude.ai/code) 的[環境選擇器](#configure-your-environment)開啟：擁有者可以在那裡編輯它。其他成員以唯讀方式看到它。每個共用環境都有一個名稱、一個[網路存取層級](#access-levels)、`.env` 格式的[環境變數](#set-environment-variables)和一個[設定指令碼](#setup-scripts)。擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 分別選擇組織的[預設環境](#the-default-environment)。182共用環境會在每個成員的[環境選擇器](#configure-your-environment)中出現，在**組織**標題下，位於成員自己的環境之後（在**個人**標題下），因此團隊可以標準化一個設定，而不是每個成員重新建立它。選擇共用環境的設定圖示會為每個成員（包括擁有者）開啟其設定的唯讀摘要。

183

184擁有者以兩種方式之一將環境提供給組織：

185

186* **建立共用環境**：使用[管理設定](https://claude.ai/admin-settings)中的**雲端環境**頁面，這也是擁有者編輯和封存共用環境的地方。每個都有一個名稱、一個[網路存取層級](#access-levels)、`.env` 格式的[環境變數](#set-environment-variables)和一個[設定指令碼](#setup-scripts)。

187* **共用個人環境**：在環境選擇器中開啟您自己的環境之一進行編輯，然後從**誰可以使用它**列共用它。環境保留其 ID，因此已使用它的工作階段和例行程序不受影響，每個成員都可以看到它並在其中啟動工作階段。

188

189擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 分別選擇組織的[預設環境](#the-default-environment)。

183 190

184每個成員在共用環境中的工作階段都會讀取其變數，因此不要在其中包含機密。[API 認證](#add-api-credentials)（為工作階段提供它們無法讀取的金鑰）在 Team 或 Enterprise 方案上尚不可用。191每個成員在共用環境中的工作階段都會讀取其變數，因此不要在其中包含機密。[API 認證](#add-api-credentials)（為工作階段提供它們無法讀取的金鑰）在 Team 或 Enterprise 方案上尚不可用。

185 192

198 205

199每個環境都設定一個網路存取層級，控制其工作階段可以進行的出站連線。預設層級 **Trusted** 允許套件登錄和其他[允許清單中的網域](#default-allowed-domains)；**Custom** 採用您自己的網域清單。206每個環境都設定一個網路存取層級，控制其工作階段可以進行的出站連線。預設層級 **Trusted** 允許套件登錄和其他[允許清單中的網域](#default-allowed-domains)；**Custom** 採用您自己的網域清單。

200 207

201若要變更環境的網路存取，[開啟它進行編輯](#configure-your-environment)並在對話框中使用 **Network access** 選擇器。開啟選擇器的雲端圖示出現在[Default 環境](#the-default-environment)下列出的應用程式表面上，以及在[例行編輯器](/docs/zh-TW/routines#environments-and-network-access)中；個人環境在您的 claude.ai 帳戶設定中沒有單獨的頁面。208若要變更環境的網路存取，[開啟它進行編輯](#configure-your-environment)並在對話框中使用 **Network access** 選擇器。[共用環境](#organization-shared-environments)在該處以唯讀方式開啟，因此擁有者改為從[管理設定](https://claude.ai/admin-settings)中的 **Cloud environments** 頁面變更其網路存取。開啟選擇器的雲端圖示出現在[Default 環境](#the-default-environment)下列出的應用程式表面上，以及在[例行編輯器](/docs/zh-TW/routines#environments-and-network-access)中；個人環境在您的 claude.ai 帳戶設定中沒有單獨的頁面。

202 209

203<Note>210<Note>

204 您在工作階段或例行上啟用的 MCP 連接器無需將其主機新增到 **Allowed domains**，因為連接器流量透過 Anthropic 的伺服器而不是工作階段的網路傳輸。這依賴於[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下提到的相同 Anthropic 繫結通道。關閉任何您不需要的連接器，以限制 Claude 可以到達的工具。211 您在工作階段或例行上啟用的 MCP 連接器無需將其主機新增到 **Allowed domains**，因為連接器流量透過 Anthropic 的伺服器而不是工作階段的網路傳輸。這依賴於[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下提到的相同 Anthropic 繫結通道。關閉任何您不需要的連接器，以限制 Claude 可以到達的工具。

env-vars.md +1 −1

Details

223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | 啟用 `CLAUDE_AUTO_BACKGROUND_TASKS` 時，提醒 Claude 檢查仍在執行的 [背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 之間的秒數。僅接受 `1` 到 `86400` 的純整數；任何其他值或拼寫讀作未設定。未設定時，沒有檢查提醒。需要 Claude Code v2.1.248 或更新版本 |223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | 啟用 `CLAUDE_AUTO_BACKGROUND_TASKS` 時，提醒 Claude 檢查仍在執行的 [背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 之間的秒數。僅接受 `1` 到 `86400` 的純整數；任何其他值或拼寫讀作未設定。未設定時，沒有檢查提醒。需要 Claude Code v2.1.248 或更新版本 |

224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)（權杖），從 `100000` 到 `1000000`。僅接受純整數（如 `500000`）：像 `500k` 這樣的值讀作 `500` 並限制在 100K 最小值。有效視窗也上限為模型的上下文視窗。優先於 `/autocompact` 命令、`--autocompact` 旗標和 `autoCompactWindow` 設定。狀態列的 `used_percentage` 始終針對模型的完整上下文視窗進行測量，因此一旦設定此變數，該百分比不再指示何時會執行壓縮 |224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)（權杖），從 `100000` 到 `1000000`。僅接受純整數（如 `500000`）：像 `500k` 這樣的值讀作 `500` 並限制在 100K 最小值。有效視窗也上限為模型的上下文視窗。優先於 `/autocompact` 命令、`--autocompact` 旗標和 `autoCompactWindow` 設定。狀態列的 `used_percentage` 始終針對模型的完整上下文視窗進行測量，因此一旦設定此變數，該百分比不再指示何時會執行壓縮 |

225| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE 連線](/docs/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 隱藏父終端時。優先於 [`autoConnectIde`](/docs/zh-TW/settings-reference#autoconnectide) 全域配置設定 |225| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE 連線](/docs/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 隱藏父終端時。優先於 [`autoConnectIde`](/docs/zh-TW/settings-reference#autoconnectide) 全域配置設定 |

226| `CLAUDE_CODE_AUTO_MODE_SERVER` | 在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，設定為 `1` 以讓平台的伺服器端分類器檢查 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 動作；平台不執行分類器的地方，Claude Code 回退到自己的分類器請求。未設定或 `0` 時，分類器透過 Claude Code 本身傳送的請求執行。對其他提供者（包括 Anthropic API）無效。需要 Claude Code v2.1.271 或更新版本 |226| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否要求伺服器 [檢查自動模式動作](/docs/zh-TW/permission-modes#server-side-classifier-review)。未設定時，Claude Code 在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上要求伺服器，以及當您指向 `ANTHROPIC_BASE_URL` 至 LLM 閘道或代理時。設定為 `0` 以改用 Claude Code 自己的分類器請求。不在直接連線到 Anthropic API 時讀取。需要 Claude Code v2.1.271 或更新版本；預設要求伺服器需要 v2.1.278 或更新版本 |

227| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設認證提供者鏈產生認證的時間（毫秒），然後請求失敗，並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)（預設：`60000`）。當鏈中的步驟合法需要更長時間時提高此值，例如透過 `aws-vault` 等包裝器進行基於瀏覽器的 SSO 登入（帶 MFA）。適用於 Claude Code 使用預設鏈簽署的任何地方：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 和 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更新版本 |227| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設認證提供者鏈產生認證的時間（毫秒），然後請求失敗，並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)（預設：`60000`）。當鏈中的步驟合法需要更長時間時提高此值，例如透過 `aws-vault` 等包裝器進行基於瀏覽器的 SSO 登入（帶 MFA）。適用於 Claude Code 使用預設鏈簽署的任何地方：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 和 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更新版本 |

228| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設定為 `0` 以關閉 [Bash 命令變更的檔案差異](/docs/zh-TW/hooks#bash)，或設定為 `1` 以在每個權限模式中記錄。優先於 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |228| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設定為 `0` 以關閉 [Bash 命令變更的檔案差異](/docs/zh-TW/hooks#bash)，或設定為 `1` 以在每個權限模式中記錄。優先於 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |

229| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設定為 `0` 以使非互動工作階段在每個轉結束時向其主機報告閒置狀態，即使背景工作仍在執行。預設情況下，工作階段在背景工作（例如背景代理或 [工作流程](/docs/zh-TW/workflows) 執行）仍在進行時，保持在轉結束後報告執行狀態。這可防止監視狀態的主機（例如遠端工作階段清單）在工作中途宣佈 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不保持執行狀態。執行狀態預設和 `0` 選擇退出需要 Claude Code v2.1.269 或更新版本；在較早版本上，設定 `1` 以保持執行狀態 |229| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設定為 `0` 以使非互動工作階段在每個轉結束時向其主機報告閒置狀態，即使背景工作仍在執行。預設情況下，工作階段在背景工作（例如背景代理或 [工作流程](/docs/zh-TW/workflows) 執行）仍在進行時，保持在轉結束後報告執行狀態。這可防止監視狀態的主機（例如遠端工作階段清單）在工作中途宣佈 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不保持執行狀態。執行狀態預設和 `0` 選擇退出需要 Claude Code v2.1.269 或更新版本；在較早版本上，設定 `1` 以保持執行狀態 |

errors.md +2 −0

Details

1740 1740

1741**該怎麼做：**1741**該怎麼做：**

1742 1742

1743這些步驟會變更您自己的環境之一。[組織共享環境](/docs/zh-TW/cloud-environments#organization-shared-environments)在選擇器中以唯讀方式開啟，因此請要求擁有者從[管理設定](https://claude.ai/admin-settings)中的**雲端環境**頁面變更其網路存取。

1744

1743* 開啟例行程式進行編輯，或啟動雲端工作階段。選擇顯示您環境名稱的雲端圖示（例如**預設**）以開啟選擇器。將滑鼠懸停在您的環境上，然後按一下設定圖示。1745* 開啟例行程式進行編輯，或啟動雲端工作階段。選擇顯示您環境名稱的雲端圖示（例如**預設**）以開啟選擇器。將滑鼠懸停在您的環境上，然後按一下設定圖示。

1744* 在**更新雲端環境**對話方塊中，將**網路存取**從**信任**變更為**自訂**，然後將被阻止的網域新增到**允許的網域**。每行輸入一個網域。檢查**也包括常見套件管理員的預設清單**以在您的自訂網域旁邊保留[預設允許清單](/docs/zh-TW/cloud-environments#default-allowed-domains)。如果您想要不受限制的存取，請改為選擇**完整**。1746* 在**更新雲端環境**對話方塊中，將**網路存取**從**信任**變更為**自訂**，然後將被阻止的網域新增到**允許的網域**。每行輸入一個網域。檢查**也包括常見套件管理員的預設清單**以在您的自訂網域旁邊保留[預設允許清單](/docs/zh-TW/cloud-environments#default-allowed-domains)。如果您想要不受限制的存取，請改為選擇**完整**。

1745* 按一下**儲存變更**。下一次執行使用更新的允許清單。1747* 按一下**儲存變更**。下一次執行使用更新的允許清單。

permission-modes.md +6 −4

Details

328 328

329在 v2.1.158 到 v2.1.206 中，自動模式在這些提供者上是關閉的，直到您設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，而 Claude Code 在這些提供者上忽略 `defaultMode: "auto"`，除非也設定了該變數。該變數仍被接受以保持相容性，從 v2.1.207 開始沒有效果。329在 v2.1.158 到 v2.1.206 中，自動模式在這些提供者上是關閉的，直到您設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，而 Claude Code 在這些提供者上忽略 `defaultMode: "auto"`，除非也設定了該變數。該變數仍被接受以保持相容性，從 v2.1.207 開始沒有效果。

330 330

331<h4 id="server-side-classifier-review">331<h3 id="server-side-classifier-review">

332 伺服器端分類器審查332 伺服器端分類器審查

333</h4>333</h3>

334

335在 Enterprise 方案和使用 Claude API 的帳戶上，在 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，以及每當您將 `ANTHROPIC_BASE_URL` 指向[LLM 閘道或代理](/docs/zh-TW/llm-gateway)時，自動模式中的 Claude Code 會要求伺服器審查[進入分類器的操作](#how-the-classifier-evaluates-actions)作為會話的模型請求的一部分。在伺服器審查它們的地方，其判決決定這些操作。在它不審查的地方，通常是因為 LLM 閘道或代理干擾了流量，或因為平台、區域或認證還沒有伺服器端檢查，Claude Code 會回退到自己的分類器請求，一旦該回退在會話的其餘部分保持，它會在那些請求被計費的帳戶上顯示[關於分類器請求費用的一次性對話](/docs/zh-TW/auto-mode-classifier-billing)。要跳過詢問伺服器並始終使用 Claude Code 自己的分類器請求，請設定 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/zh-TW/env-vars)。該變數在直接連接到 Anthropic API 時不被讀取。如果您設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 並保持 `CLAUDE_CODE_AUTO_MODE_SERVER` 未設定，Claude Code 也會停止詢問伺服器。

334 336

335在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，Claude Code 預設使用自己的分類器請求審查自動模式操作。要讓平台的伺服器端分類器審查[進入分類器的操作](#how-the-classifier-evaluates-actions)作為會話的模型請求的一部分，請設定 [`CLAUDE_CODE_AUTO_MODE_SERVER=1`](/docs/zh-TW/env-vars)。平台執行分類器的地方，其判決決定這些操作；平台不執行的地方，Claude Code 會回退到自己的分類器請求。在 v2.1.271 和 v2.1.272 中，詢問平台是這些提供者上的預設。337預設詢問伺服器需要 Claude Code v2.1.278 或更新版本。

336 338

337<h3 id="what-the-classifier-blocks-by-default">339<h3 id="what-the-classifier-blocks-by-default">

338 分類器預設阻止的內容340 分類器預設阻止的內容

517 519

518 會話的第一個自動模式請求驗證 Sonnet 5 預設：如果請求成功，Sonnet 5 保持會話的分類器模型，如果它失敗是因為模型不可用，會話改為使用回退。在該驗證解決後，分類器的模型在會話中不會改變。520 會話的第一個自動模式請求驗證 Sonnet 5 預設：如果請求成功，Sonnet 5 保持會話的分類器模型，如果它失敗是因為模型不可用，會話改為使用回退。在該驗證解決後，分類器的模型在會話中不會改變。

519 521

520 在 Enterprise 方案和使用 Claude API、[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 的帳戶上，分類器呼叫計入您的令牌使用。每次檢查發送文字記錄的一部分加上待決操作，在執行前添加往返。工作目錄外的讀取和受保護路徑外的編輯跳過分類器，因此開銷主要來自 shell 命令和網路操作。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，您可以將審查移至會話的模型請求中；請參閱[伺服器端分類器審查](#server-side-classifier-review)。522 在 Enterprise 方案和使用 Claude API、[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 的帳戶上，分類器呼叫計入您的令牌使用。每次檢查發送文字記錄的一部分加上待決操作，在執行前添加往返。工作目錄外的讀取和受保護路徑外的編輯跳過分類器，因此開銷主要來自 shell 命令和網路操作。在伺服器審查操作的地方，作為會話的模型請求的一部分，沒有單獨的分類器呼叫要計數；請參閱[伺服器端分類器審查](#server-side-classifier-review)。

521 523

522 沙箱網路存取不添加每個連接分類器請求。分類器與命令一起判斷[命令命名的主機](/docs/zh-TW/sandboxing#per-command-allowed-domains-in-auto-mode)，Claude Code 根據批准的列表檢查每個連接而不再次呼叫分類器。524 沙箱網路存取不添加每個連接分類器請求。分類器與命令一起判斷[命令命名的主機](/docs/zh-TW/sandboxing#per-command-allowed-domains-in-auto-mode)，Claude Code 根據批准的列表檢查每個連接而不再次呼叫分類器。

523 </Accordion>525 </Accordion>

plugin-marketplaces.md +109 −76

Details

24一旦您的 marketplace 上線，您可以透過推送變更到您的儲存庫來更新它。使用者使用 `/plugin marketplace update` 重新整理其本機副本。24一旦您的 marketplace 上線，您可以透過推送變更到您的儲存庫來更新它。使用者使用 `/plugin marketplace update` 重新整理其本機副本。

25 25

26<h2 id="walkthrough-create-a-local-marketplace">26<h2 id="walkthrough-create-a-local-marketplace">

~~27 逐步解說：建立本機 marketplace~~27 逐步解說：建立本機市集

28</h2>28</h2>

29 29

30此範例建立一個包含一個 plugin 的 marketplace：用於程式碼審查的 `quality-review` skill。您將建立目錄結構、新增 skill、建立 plugin manifest 和 marketplace 目錄，然後安裝並測試它。30此範例建立一個市集，其中包含一個外掛程式：用於程式碼審查的 `quality-review` 技能。您將建立目錄結構、新增技能、建立外掛程式資訊清單和市集目錄，然後安裝並測試它。

31 31

32<Steps>32<Steps>

33 <Step title="建立目錄結構">33 <Step title="建立目錄結構">

38 ```38 ```

39 </Step>39 </Step>

40 40

~~41 <Step title="建立 skill">~~41 <Step title="建立技能">

~~42 建立 `SKILL.md` 檔案，定義 `quality-review` skill 的功能。~~42 建立一個 `SKILL.md` 檔案，定義 `quality-review` 技能的功能。

43 43

44 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}44 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

45 ---45 ---

~~46 description: 檢查程式碼中的錯誤、安全性和效能問題~~46 description: Review code for bugs, security, and performance

47 ---47 ---

48 48

~~49 檢查我選擇的程式碼或最近的變更，查找：~~49 Review the code I've selected or the recent changes for:

~~50 - 潛在的錯誤或邊界情況~~50 - Potential bugs or edge cases

~~51 - 安全性問題~~51 - Security concerns

~~52 - 效能問題~~52 - Performance issues

~~53 - 可讀性改進~~53 - Readability improvements

54 54

~~55 簡潔且可行動。~~55 Be concise and actionable.

56 ```56 ```

57 </Step>57 </Step>

58 58

~~59 <Step title="建立 plugin manifest">~~59 <Step title="建立外掛程式資訊清單">

~~60 建立 `plugin.json` 檔案，描述 plugin。manifest 位於 `.claude-plugin/` 目錄中。~~60 建立一個 `plugin.json` 檔案，描述該外掛程式。資訊清單位於 `.claude-plugin/` 目錄中。

61 61

62 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}62 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

63 {63 {

64 "name": "quality-review-plugin",64 "name": "quality-review-plugin",

~~65 "description": "新增 quality-review skill 以進行快速程式碼審查",~~65 "description": "Adds a quality-review skill for quick code reviews",

66 "version": "1.0.0",66 "version": "1.0.0",

67 "author": {67 "author": {

68 "name": "Your Name"68 "name": "Your Name"

71 ```71 ```

72 72

73 <Note>73 <Note>

74 設定 `version` 表示使用者只會在您變更此欄位時收到更新，因此在每次發行時都要提升版本。具有 `command` 來源的 plugin 不會由此欄位固定。如果您省略 `version`，版本會來自[版本管理](/docs/zh-TW/plugins-reference#version-management)中的下一個來源。74 設定 `version` 表示使用者只有在您變更此欄位時才會收到更新，因此在每次發行時都要提升版本。具有 [`command` 來源](#command-sources) 的外掛程式不會由此欄位固定。從市集新增為本機目錄的市集中 [就地載入](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution) 的外掛程式也不會被固定。如果您省略 `version`，版本會來自 [版本管理](/docs/zh-TW/plugins-reference#version-management) 中的下一個來源。

75 </Note>75 </Note>

76 </Step>76 </Step>

77 77

~~78 <Step title="建立 marketplace 檔案">~~78 <Step title="建立市集檔案">

~~79 建立列出您的 plugin 的 marketplace 目錄。~~79 建立列出您的外掛程式的市集目錄。

80 80

81 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}81 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}

82 {82 {

88 {88 {

89 "name": "quality-review-plugin",89 "name": "quality-review-plugin",

90 "source": "./plugins/quality-review-plugin",90 "source": "./plugins/quality-review-plugin",

~~91 "description": "新增 quality-review skill 以進行快速程式碼審查"~~91 "description": "Adds a quality-review skill for quick code reviews"

92 }92 }

93 ]93 ]

94 }94 }

96 </Step>96 </Step>

97 97

98 <Step title="新增並安裝">98 <Step title="新增並安裝">

99 從包含 `my-marketplace` 的目錄啟動 Claude Code 並執行下列命令。安裝命令會開啟 plugin 詳細資訊檢視，您可以在其中選擇安裝範圍以確認安裝。檢查安裝摘要：如果它報告 `Run /reload-plugins to activate.`，請參閱[不重新啟動即可套用 plugin 變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)。99 從包含 `my-marketplace` 的目錄啟動 Claude Code 並執行下列命令。安裝命令會開啟外掛程式詳細資料檢視，您可在其中選擇安裝範圍以確認安裝。檢查安裝摘要：如果它報告 `Run /reload-plugins to activate.`，請參閱 [不重新啟動即可套用外掛程式變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)。

100 100

101 ```shell theme={null}101 ```shell theme={null}

102 /plugin marketplace add ./my-marketplace102 /plugin marketplace add ./my-marketplace

105 </Step>105 </Step>

106 106

107 <Step title="試試看">107 <Step title="試試看">

108 在編輯器中選擇一些程式碼並執行您的新 skill。Plugin skills 使用 plugin 名稱進行命名空間。108 在編輯器中選擇一些程式碼並執行您的新技能。外掛程式技能會以外掛程式名稱作為命名空間。

109 109

110 ```shell theme={null}110 ```shell theme={null}

111 /quality-review-plugin:quality-review111 /quality-review-plugin:quality-review

113 </Step>113 </Step>

114</Steps>114</Steps>

115 115

116若要深入瞭解 plugin 可以執行的操作，包括 hooks、agents、MCP servers 和 LSP servers，請參閱 [Plugins](/docs/zh-TW/plugins)。116若要深入瞭解外掛程式可以執行的操作，包括 hooks、agents、MCP 伺服器和 LSP 伺服器，請參閱 [Plugins](/docs/zh-TW/plugins)。

117 117

118<Note>118<Note>

119 **plugin 如何安裝**：當使用者安裝 plugin 時，Claude Code 會將 plugin 目錄複製到快取位置，除了[連結模式](#copy-mode-and-link-mode)中的 `command` 來源（會被就地使用）。複製的 plugin 無法使用 `../shared-utils` 之類的路徑參考其目錄外的檔案，因為這些檔案不會被複製。119 **外掛程式的安裝方式**：當使用者安裝外掛程式時，Claude Code 會將外掛程式目錄複製到快取位置，除非外掛程式就地載入。連結模式中的 [`command` 來源](#copy-mode-and-link-mode) 會就地載入，從本機目錄新增的市集中的 [相對路徑來源](#relative-paths) 也會就地載入。複製的外掛程式無法使用 `../shared-utils` 之類的路徑參考其目錄外的檔案，因為這些檔案不會被複製。

120 120

121 如果您需要在 plugin 之間共享檔案，請使用符號連結。有關詳細資訊，請參閱 [Plugin caching and file resolution](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。121 如果您需要在外掛程式之間共用檔案，請使用符號連結。如需詳細資訊，請參閱 [外掛程式快取和檔案解析](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。

122</Note>122</Note>

123 123

124<h2 id="create-the-marketplace-file">124<h2 id="create-the-marketplace-file">

176 **保留名稱**：以下 marketplace 名稱保留供 Anthropic 官方使用，第三方 marketplace 無法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`claude-tag-plugins`、`healthcare`。模仿官方 marketplace 的名稱（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留這些名稱可防止第三方 marketplace 將自己冒充為 Anthropic 發佈的來源。176 **保留名稱**：以下 marketplace 名稱保留供 Anthropic 官方使用，第三方 marketplace 無法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`claude-tag-plugins`、`healthcare`。模仿官方 marketplace 的名稱（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留這些名稱可防止第三方 marketplace 將自己冒充為 Anthropic 發佈的來源。

177 177

178 Claude Code 每次載入 marketplace 時都會重新檢查保留名稱，而不僅在您新增 marketplace 時檢查。在名稱成為保留名稱之前以其中一個名稱註冊的 marketplace 會停止載入，並報告它是[從不受信任的來源註冊](/docs/zh-TW/errors#marketplace-is-registered-from-an-untrusted-source)。移除該 marketplace，並從官方 Anthropic 來源重新新增它。受新保留名稱影響的第三方 marketplace 在您以不同名稱重新新增它後立即再次載入。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 未被保留，已在保留名稱下註冊的 marketplace 繼續載入。在 v2.1.265 之前，`claude-tag-plugins` 未被保留。178 Claude Code 每次載入 marketplace 時都會重新檢查保留名稱，而不僅在您新增 marketplace 時檢查。在名稱成為保留名稱之前以其中一個名稱註冊的 marketplace 會停止載入，並報告它是[從不受信任的來源註冊](/docs/zh-TW/errors#marketplace-is-registered-from-an-untrusted-source)。移除該 marketplace，並從官方 Anthropic 來源重新新增它。受新保留名稱影響的第三方 marketplace 在您以不同名稱重新新增它後立即再次載入。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 未被保留，已在保留名稱下註冊的 marketplace 繼續載入。在 v2.1.265 之前，`claude-tag-plugins` 未被保留。

179

180 您也無法將 marketplace 命名為 `npm`、`pip`、`uv`、`cargo`、`github` 或 `gh`（任何大小寫）。此檢查需要 Claude Code v2.1.275 或更新版本。

179</Note>181</Note>

180 182

181<h3 id="owner-fields">183<h3 id="owner-fields">

182 擁有者欄位184 Owner 欄位

183</h3>185</h3>

184 186

185| 欄位 | 類型 | 必需 | 描述 |187| 欄位 | 類型 | 必需 | 描述 |

207 Plugin 項目209 Plugin 項目

208</h2>210</h2>

209 211

210`plugins` 陣列中的每個 plugin 項目描述一個 plugin 及其位置。您可以包含 [plugin manifest 架構](/docs/zh-TW/plugins-reference#plugin-manifest-schema)中的任何欄位，例如 `description`、`version`、`author`、`commands` 和 `hooks`，加上這些 marketplace 特定欄位：`source`、`category`、`tags`、`strict`、`relevance`、`headers` 和 `headersHelper`。212`plugins` 陣列中的每個 plugin 項目都描述了一個 plugin 及其位置。您可以包含來自 [plugin manifest schema](/docs/zh-TW/plugins-reference#plugin-manifest-schema) 的任何欄位，例如 `description`、`version`、`author`、`commands` 和 `hooks`，加上這些 marketplace 特定欄位：`source`、`category`、`tags`、`strict`、`relevance`、`headers` 和 `headersHelper`。

211 213

212<h3 id="required-fields-2">214<h3 id="required-fields-2">

213 必需欄位215 必需欄位

214</h3>216</h3>

215 217

216| 欄位 | 類型 | 描述 |218| 欄位 | 類型 | 說明 |

217| :------- | :------------- | :----------------------------------------------------------------------------------------------------- |219| :------- | :------------- | :----------------------------------------------------------------------------------------------------------- |

220 222

221<h3 id="optional-plugin-fields">223<h3 id="optional-plugin-fields">

222 選用 plugin 欄位224 選用 plugin 欄位

224 226

225**標準中繼資料欄位：**227**標準中繼資料欄位：**

226 228

227| 欄位 | 類型 | 描述 |229| 欄位 | 類型 | 說明 |

228| :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |230| :--------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

231| `version` | string | Plugin 版本。如果設定（在此處或在 `plugin.json` 中），plugin 會固定到此字串，使用者只有在版本變更時才會收到更新。具有 [`command` 來源](#command-sources)的 plugin 不會由任一欄位固定。如果在兩個地方都未設定，版本來自 [版本管理](/docs/zh-TW/plugins-reference#version-management)中的下一個來源。 |233| `version` | string | Plugin 版本。如果設定（在此處或在 `plugin.json` 中），plugin 會固定到此字串，使用者只有在版本變更時才會收到更新。具有 [`command` source](#command-sources) 的 plugin 不會由任一欄位固定。從 marketplace 新增為本機目錄且 [loaded in place](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution) 的 plugin 也不會。如果在兩個位置都未設定，版本來自 [version management](/docs/zh-TW/plugins-reference#version-management) 中的下一個來源。 |

242| `defaultEnabled` | boolean | 安裝後 plugin 是否啟用（預設值：true）。設定為 `false` 以安裝已停用的 plugin，直到使用者選擇加入。優先於 plugin 的 `plugin.json` 中的相同欄位。請參閱 [預設啟用](/docs/zh-TW/plugins-reference#default-enablement)。 |244| `defaultEnabled` | boolean | 安裝後 plugin 是否啟用（預設值：true）。設定為 `false` 以安裝已停用的 plugin，直到使用者選擇加入。優先於 plugin 的 `plugin.json` 中的相同欄位。請參閱 [Default enablement](/docs/zh-TW/plugins-reference#default-enablement)。 |

243 245

244兩個項目和 plugin 自己的 `plugin.json` 都可以設定顯示欄位 `displayName`、`description`、`author`、`homepage`、`repository`、`license` 和 `keywords`。在 plugin 清單和詳細資訊中，安裝前後：246項目和 plugin 自己的 `plugin.json` 都可以設定顯示欄位 `displayName`、`description`、`author`、`homepage`、`repository`、`license` 和 `keywords`。在 plugin 清單和詳細資訊中，安裝前後：

245 247

246* 對於您在項目上設定的欄位，使用者會看到項目的值，即使 `plugin.json` 設定了不同的值。248* 對於您在項目上設定的欄位，使用者會看到項目的值，即使 `plugin.json` 設定了不同的值。

247* 對於項目未設定的欄位，使用者會看到 `plugin.json` 值。249* 對於項目未設定的欄位，使用者會看到 `plugin.json` 值。

248 250

249安裝前，Claude Code 只能為具有 [相對路徑來源](#relative-paths)的項目讀取 `plugin.json`，其 plugin 檔案位於 marketplace 內部。對於具有任何其他來源類型的項目，使用者在安裝 plugin 之前只會看到項目自己的欄位。251安裝前，Claude Code 只能為具有 [relative-path source](#relative-paths) 的項目讀取 `plugin.json`，其 plugin 檔案位於 marketplace 內部。對於具有任何其他來源類型的項目，使用者在安裝 plugin 之前只會看到項目自己的欄位。

250 252

251**元件配置欄位：**253**元件設定欄位：**

252 254

253| 欄位 | 類型 | 描述 |255| 欄位 | 類型 | 說明 |

254| :----------- | :------------- | :----------------------------------- |256| :----------- | :------------- | :----------------------------------- |

261 263

262**檔案驗證欄位：**264**封存驗證欄位：**

263 265

264當項目在需要認證的伺服器上具有 [`archive` 來源](#zip-archives)時，設定這些欄位。266當項目在需要認證的伺服器上具有 [`archive` source](#zip-archives) 時設定這些。

265 267

266| 欄位 | 類型 | 描述 |268| 欄位 | 類型 | 說明 |

267| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |269| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

269| `headersHelper` | string | 命令，將此項目的檔案下載的 HTTP 標頭列印為一個 JSON 物件，用於過期的認證。請參閱 [驗證檔案下載](#authenticate-archive-downloads)。項目還必須設定 [`"strict": false`](#strict-mode)。需要 Claude Code v2.1.238 或更新版本。 |271| `headersHelper` | string | 命令，將此項目的封存下載的 HTTP 標頭列印為一個 JSON 物件，用於過期的認證。請參閱 [Authenticate archive downloads](#authenticate-archive-downloads)。項目還必須設定 [`"strict": false`](#strict-mode)。需要 Claude Code v2.1.238 或更新版本。 |

270 272

271<h2 id="plugin-sources">273<h2 id="plugin-sources">

272 Plugin 來源274 Plugin 來源

274 276

275Plugin 來源告訴 Claude Code 在您的 marketplace 中列出的每個個別 plugin 從何處取得。這些在 `marketplace.json` 中每個 plugin 項目的 `source` 欄位中設定。277Plugin 來源告訴 Claude Code 在您的 marketplace 中列出的每個個別 plugin 從何處取得。這些在 `marketplace.json` 中每個 plugin 項目的 `source` 欄位中設定。

276 278

277Claude Code 將每個已安裝的 plugin 複製到本機版本化 plugin 快取中，位於 `~/.claude/plugins/cache`，除了[連結模式中的 `command` 來源](#copy-mode-and-link-mode)，Claude Code 會改為使用該來源。Claude Code 也會[將 plugin 的合格 Node.js 套件相依性安裝](/docs/zh-TW/plugins-reference#node-js-package-dependencies)到快取副本中。279Claude Code 將每個已安裝的 plugin 複製到本機版本化 plugin 快取中，位於 `~/.claude/plugins/cache`，除非 plugin 就地載入。[連結模式中的 `command` 來源](#copy-mode-and-link-mode)就地載入，[相對路徑來源](#relative-paths)從本機目錄新增的 marketplace 也是如此。Claude Code 也會[將 plugin 的合格 Node.js 套件相依性安裝](/docs/zh-TW/plugins-reference#node-js-package-dependencies)到快取副本中。請參閱[Plugin 快取和檔案解析](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)以了解從本機目錄 marketplace 就地載入的 plugin 如何取得您的編輯。

278 280

279| 來源 | 類型 | 欄位 | 備註 |281| 來源 | 類型 | 欄位 | 備註 |

280| ------------ | ---------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |282| ------------ | ---------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |

288 290

314}316}

315```317```

316 318

317路徑相對於 marketplace 根目錄解析，即包含 `.claude-plugin/` 的目錄。在上面的範例中，`./plugins/my-plugin` 指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位於 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 參考 marketplace 根目錄外的路徑。在 macOS 和 Linux 上，Claude Code 拒絕在前導 `./` 之後任何地方有反斜線的項目路徑，因此在每個平台上將分隔符寫為 `/`。319路徑相對於 marketplace 根目錄解析，即包含 `.claude-plugin/` 的目錄。來源 `./plugins/my-plugin` 因此指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位於 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 參考 marketplace 根目錄外的路徑。在 macOS 和 Linux 上，Claude Code 拒絕在前導 `./` 之後任何地方有反斜線的項目路徑，因此在每個平台上將分隔符寫為 `/`。

318 320

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

320 322

437 npm 套件439 npm 套件

438</h3>440</h3>

439 441

440作為 npm 套件分發的 plugin 使用 `npm install` 安裝。這適用於公開 npm 登錄表或您的團隊託管的任何私人登錄表上的任何套件。442npm 來源可以命名公開 npm 登錄表或您的團隊託管的私人登錄表上的任何套件。Claude Code 使用您的 npm 用戶端解析套件、下載 tarball 並將其解包到 plugin 快取中。

443

444套件的安裝指令碼（例如 `preinstall` 或 `postinstall`）永遠不會執行，其相依性在取得期間不會安裝。

445

446如果套件在其 `package.json` 旁邊提供支援的 lockfile，Claude Code 會在單獨的步驟中安裝那些[Node.js 套件相依性](/docs/zh-TW/plugins-reference#node-js-package-dependencies)，也會停用指令碼。否則，發佈已建置所需一切的 plugin。需要其他套件的 MCP 伺服器可以透過 `npx` 啟動，它在首次執行時安裝它們。

441 447

442```json theme={null}448```json theme={null}

443{449{

813 託管並分發 marketplace819 託管並分發 marketplace

814</h2>820</h2>

815 821

822當使用者新增託管在 git 儲存庫中的 marketplace，或安裝其列出的 git 型 plugin 時，Claude Code 會將該 marketplace 或 plugin 儲存庫複製到他們的機器上。複製永遠不會下載 [Git LFS](https://git-lfs.com) 內容，因此 LFS 追蹤的檔案會以指標檔案的形式到達。將您的 plugin 需要的檔案保留在 LFS 之外。

823

816<h3 id="host-on-github-recommended">824<h3 id="host-on-github-recommended">

817 在 GitHub 上託管（推薦）825 在 GitHub 上託管（推薦）

818</h3>826</h3>

851 背景自動更新859 背景自動更新

852</h4>860</h4>

853 861

854根據預設，背景重新整理會為其 `git pull` 停用 git 認證助手，因此即使已配置助手，pull 也無法對私人儲存庫進行 HTTPS 驗證。SSH 遠端不受影響：載入在 `ssh-agent` 中的金鑰會以與您執行的命令相同的方式驗證背景 pull。當背景 pull 失敗時，Claude Code 會回退到從頭重新複製 marketplace。重新複製確實會使用您儲存的 git 認證，但它可能會在大型儲存庫上[逾時](#git-operations-time-out)，因此私人 marketplace 自動更新可能會間歇性失敗。862根據預設，背景重新整理會停用 git 認證助手，當它檢查 marketplace 的遠端以尋找新提交時，因此檢查無法對私人儲存庫進行 HTTPS 驗證，即使已配置助手。SSH 遠端不受影響：載入在 `ssh-agent` 中的金鑰會以與您執行的命令相同的方式驗證背景檢查。

863

864當檢查找到新提交，或因為無法到達或驗證遠端而失敗時，Claude Code 會重新複製 marketplace 並交換新複製。如果該複製失敗，現有簽出會保留在原位。重新複製確實會使用您儲存的 git 認證，但它可能會在大型儲存庫上[逾時](#git-operations-time-out)，因此私人 marketplace 自動更新可能會間歇性失敗。

855 865

856兩個設定使私人 marketplace 的行為可預測：866兩個設定使私人 marketplace 的行為可預測：

857 867

858* 設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在背景 pull 失敗時保留現有複製，而不是刪除並重新複製。您的 plugin 會從最後同步的狀態繼續運作，使用 `/plugin marketplace update` 的手動更新仍會使用您的認證進行 pull。868* 設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在背景檢查無法到達或驗證遠端時保留現有簽出，而不嘗試重新複製。您的 plugin 會從最後同步的狀態繼續運作，使用 `/plugin marketplace update` 的手動更新仍會使用您的認證進行驗證。

859* 配置 git 認證助手，例如使用 `gh auth setup-git` 針對 GitHub，以便重新複製回退可以在不提示的情況下進行驗證。869* 配置 git 認證助手，例如使用 `gh auth setup-git` 針對 GitHub，以便重新複製可以在不提示的情況下進行驗證。

860 870

861在您的環境中設定提供者令牌（例如 `GITHUB_TOKEN`）本身不會啟用背景驗證。令牌只有透過已配置的認證助手（例如 `gh` CLI 的助手，它讀取 `GH_TOKEN` 和 `GITHUB_TOKEN`）才會生效。871在您的環境中設定提供者令牌（例如 `GITHUB_TOKEN`）本身不會啟用背景驗證。令牌只有透過已配置的認證助手（例如 `gh` CLI 的助手，它讀取 `GH_TOKEN` 和 `GITHUB_TOKEN`）才會生效。

862 872

863若要使背景 pull 本身透過 HTTPS 進行驗證，請配置全域 git URL 重寫。重寫會在遠端 URL 中嵌入令牌，因此即使背景 pull 停用認證助手，它也會生效，成功的 pull 會跳過重新複製回退。以下範例會重寫 marketplace 儲存庫的 URL 以包含存取令牌：873若要使背景檢查本身透過 HTTPS 進行驗證，請配置全域 git URL 重寫。重寫會在遠端 URL 中嵌入令牌，因此即使背景檢查停用認證助手，它也會生效。當檢查發現簽出是最新的時，Claude Code 會跳過重新複製。以下範例會重寫 marketplace 儲存庫的 URL 以包含存取令牌：

864 874

865```bash theme={null}875```bash theme={null}

866git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"876git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

879重寫會以純文字形式將令牌儲存在您的 gitconfig 中，因此請使用具有對 marketplace 儲存庫的唯讀存取權的令牌。889重寫會以純文字形式將令牌儲存在您的 gitconfig 中，因此請使用具有對 marketplace 儲存庫的唯讀存取權的令牌。

880 890

881<Note>891<Note>

882 在 CI/CD 環境中，在從私人儲存庫安裝 plugin 之前配置 git 認證助手。在 GitHub Actions 上，匯出具有對 marketplace 儲存庫的讀取存取權的令牌作為 `GH_TOKEN`，然後執行 `gh auth setup-git`。預設工作流程令牌只能存取工作流程自己的儲存庫，因此另一個儲存庫中的私人 marketplace 需要個人存取令牌或應用程式令牌。在管道中配置的全域 URL 重寫也會直接驗證背景 pull。892 在 CI/CD 環境中，在從私人儲存庫安裝 plugin 之前配置 git 認證助手。在 GitHub Actions 上，匯出具有對 marketplace 儲存庫的讀取存取權的令牌作為 `GH_TOKEN`，然後執行 `gh auth setup-git`。預設工作流程令牌只能存取工作流程自己的儲存庫，因此另一個儲存庫中的私人 marketplace 需要個人存取令牌或應用程式令牌。

893

894 如果您在管道中配置全域 URL 重寫，重寫也會直接驗證背景檢查。

883</Note>895</Note>

884 896

885<h3 id="distribute-through-organization-settings">897<h3 id="distribute-through-organization-settings">

999 1011

1000行為詳細資訊：1012行為詳細資訊：

1001 1013

1002* **唯讀**：種子目錄永遠不會被寫入。自動更新對種子 marketplace 被停用，因為 git pull 在唯讀檔案系統上會失敗。1014* **唯讀**：Claude Code 永遠不會寫入種子目錄。

1015* **自動更新已停用**：種子 marketplace 不會自動更新。

1003* **種子項目優先**：種子中宣告的 marketplace 在每次啟動時覆蓋使用者配置中的任何相符項目。若要選擇退出種子 plugin，請使用 `/plugin disable` 而不是移除 marketplace。1016* **種子項目優先**：種子中宣告的 marketplace 在每次啟動時覆蓋使用者配置中的任何相符項目。若要選擇退出種子 plugin，請使用 `/plugin disable` 而不是移除 marketplace。

1004* **路徑解析**：Claude Code 在執行時透過探測 `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` 來定位 marketplace 內容，而不是信任儲存在種子 JSON 內的路徑。這表示即使在與建置位置不同的路徑上掛載，種子也能正確運作。1017* **路徑解析**：Claude Code 在執行時透過探測 `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` 來定位 marketplace 內容，而不是信任儲存在種子 JSON 內的路徑。這表示即使在與建置位置不同的路徑上掛載，種子也能正確運作。

1005* **變更被阻止**：針對種子管理的 marketplace 執行 `/plugin marketplace remove` 或 `/plugin marketplace update` 會失敗，並提示您要求管理員更新種子映像。1018* **變更被阻止**：針對種子管理的 marketplace 執行 `/plugin marketplace remove` 或 `/plugin marketplace update` 會失敗，並提示您要求管理員更新種子映像。

1033}1046}

1034```1047```

1035 1048

1049Claude Code 下載[從 claude.ai 同步的](/docs/zh-TW/plugins-reference#synced-plugins) plugin，而不是從 marketplace 下載，因此此鎖定不涵蓋它們。若要也停止這些，請在受管設定中將 [`syncClaudeAiPlugins`](/docs/zh-TW/settings-reference#syncclaudeaiplugins) 設定為 `false`，或在 claude.ai 上為您的組織關閉 Skills。

1050

1036僅允許官方 Anthropic marketplace。單一儲存庫項目的匹配是精確的，因此此項目不涵蓋同一儲存庫的 `ref` 或 `path` 變體：1051僅允許官方 Anthropic marketplace。單一儲存庫項目的匹配是精確的，因此此項目不涵蓋同一儲存庫的 `ref` 或 `path` 變體：

1037 1052

1038```json theme={null}1053```json theme={null}

1143 1158

1144允許清單的精確匹配將僅因尾部斜線、`.git` 後綴或 `ssh://` 和 `https://` 方案而異的 URL 視為不同的值。如果您的組織 marketplace 可以透過多個 URL 形式複製，請優先使用 `hostPattern` 項目而不是字面 URL，以便 `https://`、`ssh://` 和 `user@host:path` 形式都相符。1159允許清單的精確匹配將僅因尾部斜線、`.git` 後綴或 `ssh://` 和 `https://` 方案而異的 URL 視為不同的值。如果您的組織 marketplace 可以透過多個 URL 形式複製，請優先使用 `hostPattern` 項目而不是字面 URL，以便 `https://`、`ssh://` 和 `user@host:path` 形式都相符。

1145 1160

1161[託管在 claude.ai 上的 marketplace](/docs/zh-TW/discover-plugins#add-from-claude-ai) 按主機相符：符合 `claude.ai` 的 `hostPattern` 項目在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中管理它。在允許清單上，此類項目不允許成員的個人 claude.ai 上傳。需要 Claude Code v2.1.273 或更新版本。

1162

1146因為 `strictKnownMarketplaces` 在[受管設定](/docs/zh-TW/managed-settings)中設定，個別使用者和專案配置無法覆蓋這些限制。1163因為 `strictKnownMarketplaces` 在[受管設定](/docs/zh-TW/managed-settings)中設定，個別使用者和專案配置無法覆蓋這些限制。

1147 1164

1148有關完整的配置詳細資訊，包括所有支援的來源類型和與 `extraKnownMarketplaces` 的比較，請參閱 [strictKnownMarketplaces 參考](/docs/zh-TW/settings-reference#strictknownmarketplaces)。1165有關完整的配置詳細資訊，包括所有支援的來源類型和與 `extraKnownMarketplaces` 的比較，請參閱 [strictKnownMarketplaces 參考](/docs/zh-TW/settings-reference#strictknownmarketplaces)。

1154Plugin 版本決定快取路徑和更新偵測：如果解析的版本與使用者已有的版本相符，`/plugin update` 和自動更新會跳過 plugin。對於 git 型來源，如果您省略 `version`，Claude Code 使用來源的解析提交 SHA，因此使用者在該提交變更時獲得更新；這是內部或積極開發的 plugin 的最簡單設定。請參閱[版本管理](/docs/zh-TW/plugins-reference#version-management)以了解完整的解析順序，包括 `archive` 來源。1171Plugin 版本決定快取路徑和更新偵測：如果解析的版本與使用者已有的版本相符，`/plugin update` 和自動更新會跳過 plugin。對於 git 型來源，如果您省略 `version`，Claude Code 使用來源的解析提交 SHA，因此使用者在該提交變更時獲得更新；這是內部或積極開發的 plugin 的最簡單設定。請參閱[版本管理](/docs/zh-TW/plugins-reference#version-management)以了解完整的解析順序，包括 `archive` 來源。

1155 1172

1156<Warning>1173<Warning>

1157 設定 `version` 會固定 plugin，除了 [`command`](#command-sources)（其版本始終包含命令產生內容的雜湊）的每個來源類型。如果您在 `plugin.json` 中宣告 `"version": "1.0.0"` 並推送新提交而不更改該字串，這些來源的現有使用者保留快取副本，因為 Claude Code 看到相同的版本。在每次發行時提升該欄位，或省略它以回退到解析的版本。1174 設定 `version` 會固定 plugin，除了 [`command`](#command-sources)（其版本始終包含命令產生內容的雜湊）的每個來源類型。[在原位載入的 plugin](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)來自作為本機目錄新增的 marketplace 也不會被固定。如果您在 `plugin.json` 中宣告 `"version": "1.0.0"` 並推送新提交而不更改該字串，這些來源的現有使用者保留快取副本，因為 Claude Code 看到相同的版本。在每次發行時提升該欄位，或省略它以回退到解析的版本。

1158 1175

1159 避免在 `plugin.json` 和 marketplace 項目中同時設定 `version`。Claude Code 總是無聲地使用 `plugin.json` 值，因此過時的 manifest 版本可能會掩蓋您在 `marketplace.json` 中設定的版本。1176 避免在 `plugin.json` 和 marketplace 項目中同時設定 `version`。Claude Code 總是無聲地使用 `plugin.json` 值，因此過時的 manifest 版本可能會掩蓋您在 `marketplace.json` 中設定的版本。

1160</Warning>1177</Warning>

1345**選項：**1362**選項：**

1346 1363

1347| 選項 | 說明 | 預設值 |1364| 選項 | 說明 | 預設值 |

1348| :-------------------- | :-------------------------------------------------------------------------------------------------------- | :----- |1365| :-------------------- | :----------------------------------------------------------------------------------------------------------- | :----- |

1368| `--claudeai` | 將引數讀取為 [claude.ai 上託管的市集](/docs/zh-TW/discover-plugins#add-from-claude-ai)的名稱，而不是來源。需要 Claude Code v2.1.273 或更新版本 | |

1351 1369

1352使用 `owner/repo` 簡寫從 GitHub 新增市集：1370使用 `owner/repo` 簡寫從 GitHub 新增市集：

1353 1371

1391claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins1409claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

1392```1410```

1393 1411

1412從 [claude.ai 上託管的市集](/docs/zh-TW/discover-plugins#add-from-claude-ai)新增，使用 `claude plugin marketplace list` 的 `From claude.ai:` 區段中列印的名稱：

1413

1414```bash theme={null}

1415claude plugin marketplace add --claudeai claudeai-organization-library

1416```

1417

1418使用 `--claudeai` 時，命令會拒絕 `--scope` 和 `--sparse`。市集是為您的帳戶託管的，而不是在設定檔中宣告的，因此您無法透過專案的 `.claude/settings.json` 共享它。

1419

1394<h3 id="plugin-marketplace-list">1420<h3 id="plugin-marketplace-list">

1395 Plugin marketplace list1421 Plugin marketplace list

1396</h3>1422</h3>

1409 1435

1410使用 `--json` 時，每個項目包括 `name`、`source`、一個 `installLocation` 欄位（包含市集儲存所在的本機快取路徑），以及來源特定的欄位：GitHub 來源的 `repo`、git 和 URL 來源的 `url`，以及本機來源的 `path`。當市集新增時使用釘選的分支或標籤時，GitHub 和 git 來源也包括 `ref` 欄位。1436使用 `--json` 時，每個項目包括 `name`、`source`、一個 `installLocation` 欄位（包含市集儲存所在的本機快取路徑），以及來源特定的欄位：GitHub 來源的 `repo`、git 和 URL 來源的 `url`，以及本機來源的 `path`。當市集新增時使用釘選的分支或標籤時，GitHub 和 git 來源也包括 `ref` 欄位。

1411 1437

1438已新增的 [claude.ai 市集](/docs/zh-TW/discover-plugins#add-from-claude-ai)沒有本機複製，因此其項目會改為使用其 claude.ai 識別碼 `marketplaceId` 和 `organizationUuid` 來代替 `installLocation`。

1439

1440在 [外掛程式從您的 claude.ai 帳戶同步](/docs/zh-TW/plugins-reference#synced-plugins)的終端機工作階段中，文字列表的結尾會有一個 `From claude.ai:` 區段，列出 claude.ai 為您的帳戶列出的內容，超出您已新增的市集。若要新增其中一個，請參閱 [從 claude.ai 新增](/docs/zh-TW/discover-plugins#add-from-claude-ai)。`--json` 輸出僅涵蓋已設定的市集，並省略該區段。需要 Claude Code v2.1.273 或更新版本。

1441

1412<h3 id="plugin-marketplace-remove">1442<h3 id="plugin-marketplace-remove">

1413 Plugin marketplace remove1443 Plugin marketplace remove

1414</h3>1444</h3>

1590 1620

1591對於背景自動更新：1621對於背景自動更新：

1592 1622

1593* 根據預設，背景重新整理會停用 git 認證助手以進行拉取，因此拉取無法透過 HTTPS 進行驗證。具有在 `ssh-agent` 中載入的金鑰的 SSH 遠端仍會進行驗證。失敗的拉取會觸發從頭開始的重新複製，這會使用您儲存的認證，但在大型儲存庫上可能會逾時1623* 根據預設，背景重新整理會停用 git 認證助手以進行拉取，因此拉取無法透過 HTTPS 進行驗證。具有在 `ssh-agent` 中載入的金鑰的 SSH 遠端仍會進行驗證

1594* 設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在背景拉取失敗時保留現有複製1624* 當拉取無法驗證時，Claude Code 會使用您儲存的認證重新複製 marketplace，但重新複製可能在大型儲存庫上逾時

1595* 配置 git 認證助手（例如 `gh auth setup-git`），以便重新複製後備可以進行驗證1625* 設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在背景拉取無法到達或驗證遠端時保留現有複製而不嘗試重新複製

1626* 配置 git 認證助手（例如 `gh auth setup-git`），以便重新複製可以驗證

1596* 如果重新複製在大型儲存庫上逾時，請使用 [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out) 增加限制1627* 如果重新複製在大型儲存庫上逾時，請使用 [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out) 增加限制

1597* 配置範圍限定於 marketplace 儲存庫的 [git URL 重寫](#private-repositories)，以便背景拉取直接進行驗證1628* 配置範圍限定於 marketplace 儲存庫的 [git URL 重寫](#private-repositories)，以便背景拉取直接驗證

1598* 或使用 `/plugin marketplace update <name>` 手動更新私人 marketplace，這會使用您的認證1629* 或使用 `/plugin marketplace update <name>` 手動更新私人 marketplace，這會使用您的認證

1599 1630

1600<h3 id="marketplace-updates-fail-in-offline-environments">1631<h3 id="marketplace-updates-fail-in-offline-environments">

1601 Marketplace 更新在離線環境中失敗1632 Marketplace 更新在離線環境中失敗

1602</h3>1633</h3>

1603 1634

1604**症狀**：Marketplace `git pull` 在背景中失敗，Claude Code 重複嘗試無法成功的重新複製。1635**症狀**：在離線或隔離環境中，背景 marketplace 重新整理無法到達遠端，Claude Code 重複嘗試無法成功的重新複製。

1636

1637**原因**：背景重新整理檢查 marketplace 的遠端以尋找新提交，當拉取無法到達遠端時，Claude Code 嘗試再次複製 marketplace。離線時，複製以相同方式失敗，現有複製保持原位。在 v2.1.274 之前，重新整理在現有複製中執行 `git pull`，當拉取失敗時將複製移到一邊以重新複製，並在之後以盡力而為的基礎上還原它。

1605 1638

1606**原因**：根據預設，當 `git pull` 失敗時，Claude Code 會嘗試從頭開始重新複製。在離線或隔離環境中，重新複製以相同方式失敗，之後先前快取的還原是盡力而為。重新整理在啟動後在背景中執行，因此不會延遲啟動，但每個工作階段都會重複失敗的嘗試，每個 git 操作都可以等待 [120 秒逾時](#git-operations-time-out)。1639重新整理在啟動後在背景中執行，因此不會延遲啟動。每個工作階段仍會重複失敗的嘗試，每個 git 操作都可以等待 [120 秒逾時](#git-operations-time-out)。

1607 1640

1608**解決方案**：設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在拉取失敗時跳過重新複製嘗試並繼續使用現有快取：1641**解決方案**：設定 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在拉取無法到達遠端時跳過重新複製嘗試並繼續使用現有複製：

1609 1642

1610```bash theme={null}1643```bash theme={null}

1611export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=11644export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

1617 Git 操作逾時1650 Git 操作逾時

1618</h3>1651</h3>

1619 1652

1620**症狀**：Plugin 安裝或 marketplace 更新失敗，出現逾時錯誤，例如「Git clone timed out after 120s」或「Git pull timed out after 120s」。1653**症狀**：Plugin 安裝或 marketplace 更新失敗，出現逾時錯誤，例如 `Git clone timed out after 120s`。

1621 1654

1622**原因**：Claude Code 對所有 git 操作（包括複製 plugin 儲存庫和拉取 marketplace 更新）使用 120 秒逾時。大型儲存庫或緩慢的網路連線可能超過此限制。1655**原因**：Claude Code 對所有 git 操作（包括複製 plugin 儲存庫和重新複製 marketplace 以更新它）使用 120 秒逾時。大型儲存庫或緩慢的網路連線可能超過此限制。

1623 1656

1624**解決方案**：使用 `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` 環境變數增加逾時。值以毫秒為單位：1657**解決方案**：使用 `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` 環境變數增加逾時。值以毫秒為單位：

1625 1658

1649 1682

1650**症狀**：Plugin 安裝但對檔案的參考失敗，特別是 plugin 目錄外的檔案1683**症狀**：Plugin 安裝但對檔案的參考失敗，特別是 plugin 目錄外的檔案

1651 1684

1652**原因**：Plugin 被複製到快取目錄而不是就地使用，除了[連結模式中的 `command` 來源](#copy-mode-and-link-mode)。參考複製 plugin 目錄外檔案的路徑（例如 `../shared-utils`）無法運作，因為這些檔案不會被複製。1685**原因**：Claude Code 將已安裝的 plugin 複製到快取目錄，除非 plugin 就地載入。[連結模式中的 `command` 來源](#copy-mode-and-link-mode)就地載入，[本機目錄新增的 marketplace 中的相對路徑來源](#relative-paths)也是如此。參考複製 plugin 目錄外檔案的路徑（例如 `../shared-utils`）無法運作，因為這些檔案不會被複製。

1653 1686

1654**解決方案**：有關解決方案（包括符號連結和目錄重組），請參閱 [Plugin caching and file resolution](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。1687**解決方案**：有關解決方案（包括符號連結和目錄重組），請參閱 [Plugin caching and file resolution](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。

1655 1688

routines.md +42 −27

Details

48 建立例行工作48 建立例行工作

49</h2>49</h2>

50 50

51在 [claude.ai/code/routines](https://claude.ai/code/routines) 網頁、Desktop 應用程式或 CLI 中建立例行工作。這三個介面都會寫入同一個雲端帳戶，因此您在其中一個介面建立的例行工作會立即出現在其他介面中。在 Desktop 應用程式的 **Code** 標籤中，按一下側邊欄或側邊欄的 **More** 選單中的 **Routines**，然後按 **New routine**，並選擇 **Cloud**；選擇 **Local** 則會建立 [Desktop 排程工作](/docs/zh-TW/desktop-scheduled-tasks)，該工作在您的機器上執行，而不是在雲端執行。51在 [claude.ai/code/routines](https://claude.ai/code/routines) 網頁、桌面應用程式或 CLI 中建立例行工作。這三個介面都會寫入同一個雲端帳戶，因此您在其中一個介面建立的例行工作會立即出現在其他介面中。在桌面應用程式的 **Code** 標籤中，按一下側邊欄或側邊欄的 **More** 選單中的 **Routines**，然後按 **New routine**，並選擇 **Cloud**；選擇 **Local** 則會建立 [Desktop scheduled task](/docs/zh-TW/desktop-scheduled-tasks)，它在您的機器上執行，而不是在雲端執行。

52 52

~~53建立表單會設定例行工作的提示、儲存庫、環境、連接器和觸發器。~~53建立表單會設定例行工作的提示詞、儲存庫、環境、連接器和觸發器。

54 54

55例行工作以完整的 Claude Code 雲端工作階段自主執行：執行期間沒有權限模式選擇器，也沒有核准提示。工作階段可以執行 shell 命令、使用 [skills](/docs/zh-TW/skills) 提交到複製的儲存庫，以及呼叫您包含的任何連接器。例行工作可以存取的內容由您選擇的儲存庫、[環境](/docs/zh-TW/cloud-environments)的網路存取和變數，以及您包含的連接器決定。將這些範圍限制在例行工作實際需要的內容。55例行工作以完整的 Claude Code 雲端工作階段自主執行：沒有權限模式選擇器，工作階段執行 shell 命令、使用 [skills](/docs/zh-TW/skills) 提交到複製的儲存庫，並呼叫您包含的任何連接器，所有這些都無需停止以尋求批准，除了某些 [artifact](/docs/zh-TW/artifacts) 動作。

56 56

57例行工作屬於您的個人 claude.ai 帳戶。它們不會與隊友共享，並且會計入您帳戶的每日執行配額。例行工作透過您連接的 GitHub 身分或連接器執行的任何操作都會顯示為您：提交和拉取請求會帶有您的 GitHub 使用者，Slack 訊息、Linear 票證或其他連接器操作會使用您為這些服務連接的帳戶。57例行工作可以存取的內容由您選擇的儲存庫、[環境](/docs/zh-TW/cloud-environments)的網路存取和變數，以及您包含的連接器決定。將這些範圍限制在例行工作實際需要的內容。

59當例行工作的排程或 **Run now** 啟動執行時，Claude 只有在以下所有條件都成立時，才會重新發佈現有的 artifact 而不詢問：

61* 您可以編輯該 artifact，且它屬於您自己的組織

62* 該 artifact 未公開共享，且未與特定人員或您的組織共享，且未選擇最新版本作為檢視者看到的版本

63* 發佈只包含頁面，沒有支援檔案或任何其他新增內容，且不會強制覆蓋較新的版本

64* 該頁面不包含超出頁面範圍的授權，例如 [connector calls](/docs/zh-TW/artifacts#pull-live-data-with-mcp-connectors)

66在所有其他情況下，包括發佈新的 artifact，Claude 會先詢問。當例行工作的工作是保持頁面最新時，請給它一個您已經發佈的 artifact。

68例行工作屬於您的個人 claude.ai 帳戶。它們不與隊友共享，並且計入您帳戶的每日執行配額。例行工作透過您連接的 GitHub 身分或連接器執行的任何操作都會顯示為您：提交和拉取請求會帶有您的 GitHub 使用者，Slack 訊息、Linear 票證或其他連接器動作會使用您為這些服務連接的帳戶。

58 69

59<h3 id="create-from-the-web">70<h3 id="create-from-the-web">

60 從網頁建立71 從網頁建立

65 造訪 [claude.ai/code/routines](https://claude.ai/code/routines) 並按一下 **New routine**。76 造訪 [claude.ai/code/routines](https://claude.ai/code/routines) 並按一下 **New routine**。

66 </Step>77 </Step>

67 78

~~68 <Step title="命名例行工作並撰寫提示">~~79 <Step title="命名例行工作並撰寫提示詞">

69 為例行工作提供描述性名稱，並撰寫 Claude 每次執行的提示。提示是最重要的部分：例行工作自主執行，因此提示必須是自成一體的，並明確說明要做什麼以及成功的樣子。80 為例行工作提供描述性名稱，並撰寫 Claude 每次執行的提示詞。提示詞是最重要的部分：例行工作自主執行，因此提示詞必須是自包含的，並明確說明要做什麼以及成功的樣子。

70 81

71 當觸發器觸發時，工作階段會收到例行工作的已儲存提示作為其指派的工作，並執行它，而不是將其視為在對話中途到達的不受信任的內容。觸發器只證明提示是由您帳戶上的授權工作階段提前儲存的，因此觸發的提示不是即時使用者輸入，無法作為執行期間操作的核准或同意。工作階段在執行期間擷取的內容保持其正常處理。在 v2.1.213 之前，工作階段收到的提示被框架化為不受信任的背景通知，可能會拒絕對其採取行動。82 當觸發器觸發時，工作階段會收到例行工作的已儲存提示詞作為其指派的任務並執行它，而不是將其視為在對話中途到達的不受信任的內容。觸發器只證明提示詞是由您帳戶上的授權工作階段提前儲存的，因此觸發的提示詞不是即時使用者輸入，無法作為執行期間動作的批准或同意。工作階段在執行期間擷取的內容保持其正常處理。在 v2.1.213 之前，工作階段收到相同的提示詞，框架為不受信任的背景通知，可能拒絕對其採取行動。

72 83

~~73 提示輸入包括模型選擇器。Claude 在每次執行時都會使用選定的模型。~~84 提示詞輸入包括模型選擇器。Claude 在每次執行時使用選定的模型。

74 </Step>85 </Step>

75 86

76 <Step title="選擇儲存庫">87 <Step title="選擇儲存庫">

~~77 為 Claude 新增一個或多個 GitHub 儲存庫以在其中工作。每個儲存庫在執行開始時會從預設分支複製。Claude 為其變更建立 `claude/` 前綴分支。~~88 為 Claude 新增一個或多個 GitHub 儲存庫以在其中工作。每個儲存庫在執行開始時被複製，從預設分支開始。Claude 為其變更建立 `claude/` 前綴的分支。

78 </Step>89 </Step>

79 90

80 <Step title="選擇環境">91 <Step title="選擇環境">

~~81 為例行工作選擇 [雲端環境](/docs/zh-TW/cloud-environments)。環境控制雲端工作階段可以存取的內容：~~92 為例行工作選擇 [cloud environment](/docs/zh-TW/cloud-environments)。環境控制雲端工作階段可以存取的內容：

82 93

~~83 * **網路存取**：設定每次執行期間可用的網際網路存取層級~~94 * **Network access**：設定每次執行期間可用的網際網路存取級別

84 * **環境變數**：提供 Claude 在每次執行期間可以使用的值。它們[對使用環境的任何人都可見](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 方案上，將 Claude 在執行期間呼叫的 API 金鑰儲存為 [API 認證](/docs/zh-TW/cloud-environments#add-api-credentials)。該部分也列出了永遠不會獲得認證的請求95 * **Environment variables**：提供 Claude 在每次執行期間可以使用的值。它們 [對使用該環境的任何人都可見](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 方案上，將 Claude 在執行期間呼叫的 API 的金鑰儲存為 [API credentials](/docs/zh-TW/cloud-environments#add-api-credentials)。該部分也列出了永遠不會獲得認證的請求

85 * **設定指令碼**：安裝例行工作需要的相依性和工具。結果會被[快取](/docs/zh-TW/cloud-environments#environment-caching)，因此指令碼不會在每個工作階段上重新執行96 * **Setup script**：安裝例行工作需要的相依性和工具。結果是 [cached](/docs/zh-TW/cloud-environments#environment-caching)，因此指令碼不會在每個工作階段上重新執行

86 97

87 提供了 **Default** 環境，具有 **Trusted** 網路存取，僅允許[預設允許清單](/docs/zh-TW/cloud-environments#default-allowed-domains)中的套件登錄、雲端提供者 API、容器登錄和常見開發網域透過工作階段的網路。您新增到例行工作的連接器透過 Anthropic 的伺服器存取其服務，因此不需要允許清單變更。如果您的例行工作需要直接存取您自己的服務或該清單外的網域，請在執行前編輯環境的[網路存取](/docs/zh-TW/cloud-environments#network-access)。若要使用單獨的環境，請[先建立一個](/docs/zh-TW/cloud-environments#configure-your-environment)。98 提供了 **Default** 環境，具有 **Trusted** 網路存取，它只允許 [default allowlist](/docs/zh-TW/cloud-environments#default-allowed-domains) 的套件登錄、雲端提供者 API、容器登錄和常見開發網域透過工作階段的網路。您新增到例行工作的連接器透過 Anthropic 的伺服器存取其服務，因此不需要更改允許清單。如果您的例行工作需要直接存取您自己的服務或該清單外的網域，請在執行前編輯環境的 [network access](/docs/zh-TW/cloud-environments#network-access)。若要使用單獨的環境，請先 [create one](/docs/zh-TW/cloud-environments#configure-your-environment)。

88 </Step>99 </Step>

89 100

90 <Step title="選擇觸發器">101 <Step title="選擇觸發器">

92 103

93 <Tabs>104 <Tabs>

94 <Tab title="Schedule">105 <Tab title="Schedule">

95 為重複執行選擇預設頻率，或在特定時間戳記排程單次一次性執行。請參閱[新增排程觸發器](#add-a-schedule-trigger)以了解時區處理、交錯、自訂 cron 間隔和一次性執行。106 為定期執行選擇預設頻率，或在特定時間戳記排程單次一次性執行。請參閱 [Add a schedule trigger](#add-a-schedule-trigger) 以了解時區處理、交錯、自訂 cron 間隔和一次性執行。

96 </Tab>107 </Tab>

97 108

98 <Tab title="GitHub event">109 <Tab title="GitHub event">

~~99 選擇儲存庫、要反應的事件和選擇性篩選器。請參閱[新增 GitHub 觸發器](#add-a-github-trigger)以取得支援事件和篩選欄位的完整清單。~~110 選擇儲存庫、要反應的事件和選擇性篩選器。請參閱 [Add a GitHub trigger](#add-a-github-trigger) 以取得支援事件和篩選欄位的完整清單。

100 </Tab>111 </Tab>

101 112

102 <Tab title="API">113 <Tab title="API">

103 在此選擇 **API**，然後儲存例行工作。URL 和權杖在儲存例行工作後產生，因為它們取決於例行工作 ID。請參閱[新增 API 觸發器](#add-an-api-trigger)以複製 URL 並產生權杖。114 在此選擇 **API**，然後儲存例行工作。URL 和權杖在儲存例行工作後產生，因為它們取決於例行工作 ID。請參閱 [Add an API trigger](#add-an-api-trigger) 以複製 URL 並產生權杖。

104 </Tab>115 </Tab>

105 </Tabs>116 </Tabs>

106 </Step>117 </Step>

107 118

108 <Step title="檢閱連接器">119 <Step title="檢查連接器">

109 在表單底部的 **Connectors** 下，預設包括您所有連接的 [MCP 連接器](/docs/zh-TW/mcp)。移除例行工作不需要的任何連接器：Claude 可以使用包含連接器的每個工具，包括寫入，而無需在執行期間要求權限。120 在表單底部的 **Connectors** 下，預設包括您所有連接的 [MCP connectors](/docs/zh-TW/mcp)。移除例行工作不需要的任何連接器：Claude 可以使用包含連接器的每個工具，包括寫入，而無需在執行期間要求權限。

110 </Step>121 </Step>

111 122

112 <Step title="建立例行工作">123 <Step title="建立例行工作">

113 按一下 **Create**。例行工作出現在清單中，並在下次其觸發器之一符合時執行。若要立即開始執行，請按一下例行工作詳細資料頁面上的 **Run now**。124 按一下 **Create**。例行工作出現在清單中，並在下次其觸發器之一符合時執行。若要立即啟動執行，請按一下例行工作詳細資料頁面上的 **Run now**。

114 125

115 每次執行都會在您的其他工作階段旁邊建立新的工作階段，您可以在其中查看 Claude 執行的操作、檢閱變更並建立拉取請求。126 每次執行都會在您的其他工作階段旁邊建立新的工作階段，您可以在其中查看 Claude 執行的操作、檢查變更並建立拉取請求。

116 </Step>127 </Step>

117</Steps>128</Steps>

118 129

120 從 CLI 建立131 從 CLI 建立

121</h3>132</h3>

122 133

123在任何工作階段中執行 `/schedule` 以對話方式建立排程例行工作。您也可以直接傳遞描述，用於重複例行工作，例如 `/schedule daily PR review at 9am` 或一次性例行工作，例如 `/schedule clean up feature flag in one week`。Claude 會逐步執行網頁表單收集的相同資訊，然後將例行工作儲存到您的帳戶。該命令也可在別名 `/routines` 下使用。134在任何工作階段中執行 `/schedule` 以對話方式建立排程例行工作。您也可以直接傳遞描述，用於定期例行工作，例如 `/schedule daily PR review at 9am` 或一次性例行工作，例如 `/schedule clean up feature flag in one week`。Claude 會逐步執行網頁表單收集的相同資訊，然後將例行工作儲存到您的帳戶。該命令也可在別名 `/routines` 下使用。

124 135

125成功的開始看起來像一次對話：Claude 在儲存前詢問有關排程、儲存庫和提示的後續問題。如果 Claude 改為回覆您需要驗證或無法連接到您的遠端 claude.ai 帳戶，則未建立例行工作；請參閱[疑難排解](#troubleshooting)。136成功的開始看起來像一次對話：Claude 在儲存前詢問有關排程、儲存庫和提示詞的後續問題。如果 Claude 改為回覆您需要驗證或無法連接到您的遠端 claude.ai 帳戶，則未建立例行工作；請參閱 [Troubleshooting](#troubleshooting)。

126 137

127CLI 中的 `/schedule` 建立排程例行工作。若要新增 API 觸發器，請在 [claude.ai/code/routines](https://claude.ai/code/routines) 的網頁上編輯例行工作。您可以從網頁或 CLI 新增 [GitHub 觸發器](#add-a-github-trigger)。CLI 路徑需要 Claude Code v2.1.225 或更新版本。138CLI 中的 `/schedule` 建立排程例行工作。若要新增 API 觸發器，請在 [claude.ai/code/routines](https://claude.ai/code/routines) 網頁上編輯例行工作。您可以從網頁或 CLI 新增 [GitHub trigger](#add-a-github-trigger)。CLI 路徑需要 Claude Code v2.1.225 或更新版本。

128 139

129沒有排程觸發器的例行工作，例如僅由 API 呼叫或 GitHub 事件啟動的例行工作，沒有下次執行時間，Claude 儲存或更新它時 CLI 不會顯示任何時間。在 v2.1.211 之前，CLI 為這些例行工作報告了第 1 年的下次執行時間。140沒有排程觸發器的例行工作，例如僅由 API 呼叫或 GitHub 事件啟動的例行工作，沒有下次執行時間，當 Claude 儲存或更新它時，CLI 不會顯示任何時間。在 v2.1.211 之前，CLI 為這些例行工作報告了第 1 年的下次執行時間。

130 141

131<h2 id="configure-triggers">142<h2 id="configure-triggers">

132 設定觸發條件143 設定觸發條件

349 360

350例行程序需要 GitHub 存取權限來複製存儲庫。當您使用 `/schedule` 從 CLI 建立例行程序時，Claude 檢查您的帳戶是否具有您執行它的存儲庫的 GitHub 存取權限，如果沒有，則新增一個設定注記，說明如何授予它。請參閱 [GitHub authentication options](/docs/zh-TW/claude-code-on-the-web#github-authentication-options) 以了解授予存取權限的兩種方式。361例行程序需要 GitHub 存取權限來複製存儲庫。當您使用 `/schedule` 從 CLI 建立例行程序時，Claude 檢查您的帳戶是否具有您執行它的存儲庫的 GitHub 存取權限，如果沒有，則新增一個設定注記，說明如何授予它。請參閱 [GitHub authentication options](/docs/zh-TW/claude-code-on-the-web#github-authentication-options) 以了解授予存取權限的兩種方式。

351 362

363如果您的 GitHub 連線在運行到期時遺失或過期，例行程序會跳過運行，最多 72 小時。在該時間窗口內重新連接 GitHub，例行程序會自動恢復。72 小時後仍未連接，例行程序會關閉，您在重新連接 GitHub 後將其重新打開。

364

352您新增的每個存儲庫在每次運行時都會被複製。Claude 從存儲庫的預設分支開始，除非您的提示另有指定。365您新增的每個存儲庫在每次運行時都會被複製。Claude 從存儲庫的預設分支開始，除非您的提示另有指定。

353 366

354Claude 將其工作推送到以 `claude/` 為前綴的分支，這些分支始終被接受。當您的提示指示 Claude 推送到另一個分支時，Claude Code 會先檢查推送，如果以下任何情況為真，則拒絕它：367Claude 將其工作推送到以 `claude/` 為前綴的分支，這些分支始終被接受。當您的提示指示 Claude 推送到另一個分支時，Claude Code 會先檢查推送，如果以下任何情況為真，則拒絕它：

377 390

378**Default** 環境使用 **Trusted** 網路存取，它只允許 [預設允許清單](/docs/zh-TW/cloud-environments#default-allowed-domains) 通過會話的網路。對該路徑上允許清單外的主機的請求失敗，返回 `403` 和 `x-deny-reason: host_not_allowed`。MCP connector 流量通過 Anthropic 的伺服器路由，而不是該路徑，因此您新增到例行程序的 connectors 無需將其主機新增到 **Allowed domains** 即可工作。移除您不需要的任何 connectors，詳見 [Connectors](#connectors)。391**Default** 環境使用 **Trusted** 網路存取，它只允許 [預設允許清單](/docs/zh-TW/cloud-environments#default-allowed-domains) 通過會話的網路。對該路徑上允許清單外的主機的請求失敗，返回 `403` 和 `x-deny-reason: host_not_allowed`。MCP connector 流量通過 Anthropic 的伺服器路由，而不是該路徑，因此您新增到例行程序的 connectors 無需將其主機新增到 **Allowed domains** 即可工作。移除您不需要的任何 connectors，詳見 [Connectors](#connectors)。

379 392

380要允許其他網域：393要允許其他網域上的一個您自己的環境，請遵循這些步驟。[organization-shared environment](/docs/zh-TW/cloud-environments#organization-shared-environments) 在此處打開為唯讀，因此所有者從 [admin settings](https://claude.ai/admin-settings) 中的 **Cloud environments** 頁面變更其網路存取。

381 394

382<Steps>395<Steps>

383 <Step title="打開例行程序進行編輯">396 <Step title="打開例行程序進行編輯">

413 426

414一次性運行不計入每日例行程序運行上限。它們像任何其他會話一樣消耗您的常規訂閱使用量。427一次性運行不計入每日例行程序運行上限。它們像任何其他會話一樣消耗您的常規訂閱使用量。

415 428

429當您的訂閱暫停時，您的例行程序會被暫停並且不會運行。一旦您的訂閱再次啟用，請將它們重新開啟。

430

416<h2 id="troubleshooting">431<h2 id="troubleshooting">

417 故障排除432 故障排除

418</h2>433</h2>

427 442

428* 您使用 Console API 金鑰、[Anthropic 設定檔或聯盟認證](/docs/zh-TW/authentication#anthropic-profiles-and-federation-credentials)，或雲端提供商（例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）進行身份驗證。`/schedule` 需要 claude.ai 訂閱登入。使用 Console API 金鑰或設定檔時，且啟用功能旗標擷取，提交 `/schedule` 會改為顯示 `/schedule is available with Claude for Enterprise — ask your admin about migrating from API-key access`。使用雲端提供商登入時，您仍會看到 `Unknown command: /schedule`。如果在您的 shell 中設定了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，或在 `settings.json` 中設定了 `apiKeyHelper`，請先移除它，因為這些設定優先於 claude.ai 登入。設定檔或聯盟認證也會優先，因此請同時關閉該設定443* 您使用 Console API 金鑰、[Anthropic 設定檔或聯盟認證](/docs/zh-TW/authentication#anthropic-profiles-and-federation-credentials)，或雲端提供商（例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）進行身份驗證。`/schedule` 需要 claude.ai 訂閱登入。使用 Console API 金鑰或設定檔時，且啟用功能旗標擷取，提交 `/schedule` 會改為顯示 `/schedule is available with Claude for Enterprise — ask your admin about migrating from API-key access`。使用雲端提供商登入時，您仍會看到 `Unknown command: /schedule`。如果在您的 shell 中設定了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，或在 `settings.json` 中設定了 `apiKeyHelper`，請先移除它，因為這些設定優先於 claude.ai 登入。設定檔或聯盟認證也會優先，因此請同時關閉該設定

429* 您完全登出，沒有 API 金鑰或其他認證。啟用功能旗標擷取時，提交 `/schedule` 會顯示 `/schedule requires a claude.ai subscription. Run /login to sign in with your claude.ai account.` 在 v2.1.268 之前，登出的工作階段會顯示與 Console API 金鑰相同的 Claude for Enterprise 訊息444* 您完全登出，沒有 API 金鑰或其他認證。啟用功能旗標擷取時，提交 `/schedule` 會顯示 `/schedule requires a claude.ai subscription. Run /login to sign in with your claude.ai account.` 在 v2.1.268 之前，登出的工作階段會顯示與 Console API 金鑰相同的 Claude for Enterprise 訊息

430* 您在雲端工作階段中。改為從 [web UI](https://claude.ai/code/routines) 管理例行程序445* 您在雲端工作階段中，提交 `/schedule` 會回答該命令在該環境中不可用。改為從 [web UI](https://claude.ai/code/routines) 管理例行程序

431* 您的組織政策停用了[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，例行程序在其上執行。在此情況下，提交 `/schedule` 會回答 [`Cloud sessions are disabled by your organization's policy`](/docs/zh-TW/errors#cloud-sessions-are-disabled-by-your-organizations-policy)。在 v2.1.268 之前，它返回 `Unknown command: /schedule`446* 您的組織政策停用了[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，例行程序在其上執行。在此情況下，提交 `/schedule` 會回答 [`Cloud sessions are disabled by your organization's policy`](/docs/zh-TW/errors#cloud-sessions-are-disabled-by-your-organizations-policy)。在 v2.1.268 之前，它返回 `Unknown command: /schedule`

432* Owner 為您的 Team 或 Enterprise 組織[關閉了例行程序](#routines-are-disabled-by-your-organizations-policy)。在 v2.1.227 之前，命令在此情況下仍會出現，而 claude.ai 會在 Claude 嘗試建立或執行例行程序時拒絕它447* Owner 為您的 Team 或 Enterprise 組織[關閉了例行程序](#routines-are-disabled-by-your-organizations-policy)。在 v2.1.227 之前，命令在此情況下仍會出現，而 claude.ai 會在 Claude 嘗試建立或執行例行程序時拒絕它

433 448

self-hosted-environments-deploy.md +13 −1

Details

168* 執行器設定 `GCM_INTERACTIVE=never`，因此 Git Credential Manager 不會打開登入對話框。168* 執行器設定 `GCM_INTERACTIVE=never`，因此 Git Credential Manager 不會打開登入對話框。

169* 執行器清除 `core.askPass`，因此如果您使用 askpass 幫助程式，請改為通過 `GIT_ASKPASS` 環境變數設定它。169* 執行器清除 `core.askPass`，因此如果您使用 askpass 幫助程式，請改為通過 `GIT_ASKPASS` 環境變數設定它。

170 170

171如果您的 Git 主機拒絕認證，或您沒有配置認證，執行器會重試幾次，然後失敗儲存庫準備。執行器不會將這些設定傳遞到工作階段的環境中。171如果您的 Git 主機拒絕認證，或您沒有配置認證，執行器會重試幾次，然後失敗儲存庫準備當儲存庫是工作階段推送結果的儲存庫時。對於工作階段僅從中讀取的儲存庫，[Troubleshooting](#troubleshooting) 涵蓋執行器何時改為跳過它。執行器不會將這些設定傳遞到工作階段的環境中。

172 172

173如果簽出目錄由與執行器程序不同的 uid 擁有，Git 拒絕對其進行操作；添加 `safe.directory`：173如果簽出目錄由與執行器程序不同的 uid 擁有，Git 拒絕對其進行操作；添加 `safe.directory`：

174 174

531* **工作階段無法通過身份驗證出站代理到達網路**：當您使用 [`--proxy-authorization-command` 或 `--proxy-authorization-file`](#authenticate-to-an-egress-proxy) 設定的來源失敗、在 30 秒後超時或產生空值時，執行器以 `502 Bad Gateway` 回答該連接並記錄原因。執行器在該日誌中編輯命令的 stderr，永遠不記錄標頭值。使用 `--proxy-authorization-command`，自己在主機上執行命令以確認它在 stdout 上列印整個標頭值。如果執行器改為在啟動時以 `could not start the proxy-authorization listener` 退出，它無法打開其環回偵聽器。531* **工作階段無法通過身份驗證出站代理到達網路**：當您使用 [`--proxy-authorization-command` 或 `--proxy-authorization-file`](#authenticate-to-an-egress-proxy) 設定的來源失敗、在 30 秒後超時或產生空值時，執行器以 `502 Bad Gateway` 回答該連接並記錄原因。執行器在該日誌中編輯命令的 stderr，永遠不記錄標頭值。使用 `--proxy-authorization-command`，自己在主機上執行命令以確認它在 stdout 上列印整個標頭值。如果執行器改為在啟動時以 `could not start the proxy-authorization listener` 退出，它無法打開其環回偵聽器。

532* **執行器記錄 `Poll failed` 行包含 `rejecting the malformed poll response`**：執行器接收到工作輪詢回應，其主體不是隊列的預期 JSON，最常見的原因是執行器和 `api.anthropic.com` 之間的某些內容（例如攔截代理或強制入口網站）以自己的頁面回答。執行器拒絕回應，在 `claude_code_self_hosted_runner_poll_errors_total` [指標](/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics)的 `transport` 種類下計數，並在[工作階段生命週期](/docs/zh-TW/self-hosted-environments#session-lifecycle)中描述的失敗輪詢時間表上重試。執行器保持服務其活躍工作階段。配置代理以從 `api.anthropic.com` 無更改地傳遞回應。在 v2.1.246 之前，執行器將此類回應讀取為空工作隊列，這可能結束其活躍工作階段或使其退出。532* **執行器記錄 `Poll failed` 行包含 `rejecting the malformed poll response`**：執行器接收到工作輪詢回應，其主體不是隊列的預期 JSON，最常見的原因是執行器和 `api.anthropic.com` 之間的某些內容（例如攔截代理或強制入口網站）以自己的頁面回答。執行器拒絕回應，在 `claude_code_self_hosted_runner_poll_errors_total` [指標](/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics)的 `transport` 種類下計數，並在[工作階段生命週期](/docs/zh-TW/self-hosted-environments#session-lifecycle)中描述的失敗輪詢時間表上重試。執行器保持服務其活躍工作階段。配置代理以從 `api.anthropic.com` 無更改地傳遞回應。在 v2.1.246 之前，執行器將此類回應讀取為空工作隊列，這可能結束其活躍工作階段或使其退出。

533* **工作階段的分支不再存在於遠端**：對於工作階段僅從中讀取的 Git 來源，執行器跳過該來源並在其餘來源上繼續。對於工作階段推送結果的來源，已刪除的分支（通常因為它被合併並自動刪除）使工作階段失敗，並出現命名儲存庫和分支的錯誤，要求您恢復分支並重試。當跳過會使其沒有儲存庫時，執行器使用相同的錯誤使工作階段失敗。在 v2.1.228 之前，此類工作階段在空目錄中啟動。533* **工作階段的分支不再存在於遠端**：對於工作階段僅從中讀取的 Git 來源，執行器跳過該來源並在其餘來源上繼續。對於工作階段推送結果的來源，已刪除的分支（通常因為它被合併並自動刪除）使工作階段失敗，並出現命名儲存庫和分支的錯誤，要求您恢復分支並重試。當跳過會使其沒有儲存庫時，執行器使用相同的錯誤使工作階段失敗。在 v2.1.228 之前，此類工作階段在空目錄中啟動。

534* **工作階段啟動時沒有其中一個儲存庫**：在沒有 [`checkout` hook](/docs/zh-TW/self-hosted-environments-configuration#checkout) 的執行器上，Git 主機可以拒絕執行器對工作階段僅從中讀取的儲存庫的存取檢查。執行器隨後跳過該儲存庫，記錄命名拒絕的 `[runner:warn] could not access context source` 行，並在其餘儲存庫上啟動工作階段。

535

536 執行器僅跳過明確的拒絕：主機回答儲存庫未找到，Git 找不到主機的認證，或身份驗證失敗。網路故障、超時或 HTTP `403` 仍然會失敗工作階段啟動，對於工作階段推送結果的儲存庫的拒絕也是如此。執行器仍然會失敗跳過會使其沒有儲存庫的工作階段。使用 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)，執行器僅跳過 Git 代理本身拒絕的儲存庫。

537

538 存取檢查在每次工作階段在執行器上啟動時再次執行，因此一旦執行器的 Git 身份具有讀取存取權限，下一次啟動會複製儲存庫。在 v2.1.274 之前，這些拒絕中的每一個都失敗了工作階段啟動。

534* **工作階段需要幾分鐘才能啟動**：初始複製通常主導。觀看 `claude_code_self_hosted_runner_session_init_duration_seconds` [指標](/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics)以確認，並使用[預熱簽出](#reuse-a-pre-warmed-checkout)或較小的 `CLAUDE_RUNNER_FETCH_DEPTH` 切割複製。539* **工作階段需要幾分鐘才能啟動**：初始複製通常主導。觀看 `claude_code_self_hosted_runner_session_init_duration_seconds` [指標](/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics)以確認，並使用[預熱簽出](#reuse-a-pre-warmed-checkout)或較小的 `CLAUDE_RUNNER_FETCH_DEPTH` 切割複製。

540* **輪次以 401 失敗**：每個工作階段使用執行器從 Anthropic 獲取並通過工作階段的 stdin 輪換的短期 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-TW/self-hosted-environments-configuration#wrapper-scripts) 來驗證模型呼叫。當輪次以來自模型 API 的 401 或 403 結束時，執行器獲取新令牌並將其傳遞給工作階段。失敗的輪次不會重試。

541

542 當獲取失敗時，執行器記錄 `inference_token refresh failed` 行，說明何時會重試，並且只要工作階段運行就會繼續重試。

543

544 如果每個呼叫在工作階段約 30 分鐘後開始失敗，包裝指令碼可能已切斷工作階段的 stdin，因此令牌輪換無法到達它；請參閱[保持 stdin 和檔案描述符 3 附加](/docs/zh-TW/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached)。

545

546 在 v2.1.274 之前，執行器在幾次嘗試後停止重試失敗的獲取，並等待下一個排定的獲取。失敗的輪次沒有觸發獲取，因此每個輪次都以 401 失敗，直到下一個排定的獲取。

535* **Pod 在清空中途被殺死**：將 `terminationGracePeriodSeconds` 提高到至少執行器在啟動時記錄的值。請參閱[關閉時序](#shutdown-timing)。547* **Pod 在清空中途被殺死**：將 `terminationGracePeriodSeconds` 提高到至少執行器在啟動時記錄的值。請參閱[關閉時序](#shutdown-timing)。

536 548

537日誌初始化後，執行器將其生命週期日誌（包括 `[runner:fatal]` 行）寫入 stdout，將調試輸出寫入 stderr，全部作為純文字行而不是 JSON。上面故障排除項中描述的啟動失敗在該點之前列印到 stderr。使用 `--log-file` 捕捉兩個流，這也讓 `self-hosted-runner doctor` 尾隨它們，或使用您的平台的日誌收集。549日誌初始化後，執行器將其生命週期日誌（包括 `[runner:fatal]` 行）寫入 stdout，將調試輸出寫入 stderr，全部作為純文字行而不是 JSON。上面故障排除項中描述的啟動失敗在該點之前列印到 stderr。使用 `--log-file` 捕捉兩個流，這也讓 `self-hosted-runner doctor` 尾隨它們，或使用您的平台的日誌收集。

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

Details

103| `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS` | `30000` | 執行器在背景工作完成後考慮工作階段忙碌的時間，而讀取結果的後續轉向尚未開始。[`--drain-wait-sec` 和 `--release-idle-session-min` 列](#runner-cli-flags)描述排空和閒置釋放時保持適用的位置，[執行器生命週期](/docs/zh-TW/self-hosted-environments#runner-lifecycle)描述它在 `--retire-at` 退休時適用的位置。`0` 或無法使用的值回退到預設值，因此無法關閉保持。需要 Claude Code v2.1.228 或更新版本。 |103| `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS` | `30000` | 執行器在背景工作完成後考慮工作階段忙碌的時間，而讀取結果的後續轉向尚未開始。[`--drain-wait-sec` 和 `--release-idle-session-min` 列](#runner-cli-flags)描述排空和閒置釋放時保持適用的位置，[執行器生命週期](/docs/zh-TW/self-hosted-environments#runner-lifecycle)描述它在 `--retire-at` 退休時適用的位置。`0` 或無法使用的值回退到預設值，因此無法關閉保持。需要 Claude Code v2.1.228 或更新版本。 |

104| `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` | `~/.claude` | 捕獲到執行器啟動快照中並播種到每個工作階段的 `CLAUDE_CONFIG_DIR` 的目錄；磁碟上的變更在執行器重新啟動後適用。設定變數也會移動執行器讀取 `.claude.json` 的位置以進行 [MCP 播種](/docs/zh-TW/self-hosted-environments-configuration#mcp-servers)，因此設定它（包括其自己的預設值）會重新定位該查詢；指向空目錄以完全停用播種。 |104| `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` | `~/.claude` | 捕獲到執行器啟動快照中並播種到每個工作階段的 `CLAUDE_CONFIG_DIR` 的目錄；磁碟上的變更在執行器重新啟動後適用。設定變數也會移動執行器讀取 `.claude.json` 的位置以進行 [MCP 播種](/docs/zh-TW/self-hosted-environments-configuration#mcp-servers)，因此設定它（包括其自己的預設值）會重新定位該查詢；指向空目錄以完全停用播種。 |

105| `SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS` | `900000` | 執行器在工作階段達到其 `--kill-session-after-min` 限制後等待的時間，以便執行中的轉向完成或釋放完成，然後才終止工作階段 |105| `SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS` | `900000` | 執行器在工作階段達到其 `--kill-session-after-min` 限制後等待的時間，以便執行中的轉向完成或釋放完成，然後才終止工作階段 |

106| `SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS` | `7000` | 執行器在轉向完成後計算工作階段忙碌的上限時間，用於 `--drain-wait-sec` 排空，而工作階段的程序向 Anthropic 報告轉向的結束。`0` 或無法使用的值回退到預設值，因此無法關閉保持。需要 Claude Code v2.1.275 或更新版本。 |

106| `SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS` | `30000` | 執行器等待作業系統將 `SIGKILL` 傳遞到卡在不可中斷 I/O 中的子程序的時間，然後自己退出。下限為 `--post-session-hook-timeout-sec` 加 15 秒，以及設定 `--push-outcome-on-release` 時的 30 秒，因此有效最小值在預設值為 75 秒。 |107| `SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS` | `30000` | 執行器等待作業系統將 `SIGKILL` 傳遞到卡在不可中斷 I/O 中的子程序的時間，然後自己退出。下限為 `--post-session-hook-timeout-sec` 加 15 秒，以及設定 `--push-outcome-on-release` 時的 30 秒，因此有效最小值在預設值為 75 秒。 |

107| `CLAUDE_RUNNER_FETCH_DEPTH` | `50` | 新複製的 git 提取深度。設定正整數，或 `full` 或 `0` 以進行完整提取。工作區中已存在的存放庫保持其現有深度。 |108| `CLAUDE_RUNNER_FETCH_DEPTH` | `50` | 新複製的 git 提取深度。設定正整數，或 `full` 或 `0` 以進行完整提取。工作區中已存在的存放庫保持其現有深度。 |

108| `CLAUDE_RUNNER_SKIP_GIT_VERIFY` | 未設定 | 當 `1` 時，在 `checkout` 掛鉤執行後跳過 `.git` 存在檢查。當您的掛鉤具體化非 git 來源時設定此項。 |109| `CLAUDE_RUNNER_SKIP_GIT_VERIFY` | 未設定 | 當 `1` 時，在 `checkout` 掛鉤執行後跳過 `.git` 存在檢查。當您的掛鉤具體化非 git 來源時設定此項。 |

slack.md +3 −1

Details

231 231

232此項目適用於使用 [Claude Tag](https://claude.com/docs/claude-tag/overview) 的工作區，其中 Claude 在頻道中以您組織的共享身分工作，而不是以任何成員的帳戶工作。如果您在 [claude.ai/code](https://claude.ai/code) 建立了頻道的雲端環境，它屬於您的個人帳戶，Claude 無法在個人環境中啟動頻道工作階段。Claude Code 會立即使工作階段失敗，重試也無法幫助。232此項目適用於使用 [Claude Tag](https://claude.com/docs/claude-tag/overview) 的工作區，其中 Claude 在頻道中以您組織的共享身分工作，而不是以任何成員的帳戶工作。如果您在 [claude.ai/code](https://claude.ai/code) 建立了頻道的雲端環境，它屬於您的個人帳戶，Claude 無法在個人環境中啟動頻道工作階段。Claude Code 會立即使工作階段失敗，重試也無法幫助。

233 233

234如果您是擁有者，請從[管理設定](https://claude.ai/admin-settings)中的**雲端環境**頁面將環境重新建立為[組織共享環境](/docs/zh-TW/cloud-environments#organization-shared-environments)。您可以透過兩種方式應用它：234如果您是擁有者且環境是您自己的，請從環境選擇器[與組織共享](/docs/zh-TW/cloud-environments#organization-shared-environments)。否則，擁有者應從[管理設定](https://claude.ai/admin-settings)中的**雲端環境**頁面將其重新建立為組織共享環境。

235

236您可以透過兩種方式應用它：

235 237

236* 在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 將其設定為組織預設值。238* 在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 將其設定為組織預設值。

237* [在 Claude Tag 管理設定中的頻道上設定它](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one)。239* [在 Claude Tag 管理設定中的頻道上設定它](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one)。

web-quickstart.md +4 −2

Details

196<Steps>196<Steps>

197 <Step title="打開差異檢視">197 <Step title="打開差異檢視">

198 差異指示器顯示整個會話中新增和移除的行，例如 `+42 -18`。選擇它以打開差異檢視，左側有文件列表，右側有更改。198 差異指示器顯示整個會話中新增和移除的行，例如 `+42 -18`。選擇它以打開差異檢視，左側有文件列表，右側有更改。

199

200 差異預設會與其基礎分支進行比較。若要與不同的分支進行比較，請選擇**比較對象**並選擇一個。

199 </Step>201 </Step>

200 202

201 <Step title="留下內聯評論">203 <Step title="留下內聯評論">

202 選擇差異中的任何行，輸入您的反饋，然後按 Enter。評論會排隊直到您發送下一條訊息，然後它們會與其捆綁。Claude 看到 "在 `src/auth.ts:47`，不要在這裡捕捉錯誤" 以及您的主要指令，因此您無需描述問題所在。204 選擇差異中的任何行，輸入您的反饋，然後按 Enter。評論會排隊直到您發送下一條訊息，然後它們會與其捆綁。Claude 看到「在 `src/auth.ts:47`，不要在這裡捕捉錯誤」以及您的主要指令，因此您無需描述問題所在。

203 </Step>205 </Step>

204 206

205 <Step title="建立拉取請求">207 <Step title="建立拉取請求">

207 </Step>209 </Step>

208 210

209 <Step title="在 PR 後繼續迭代">211 <Step title="在 PR 後繼續迭代">

210 建立 PR 後會話保持活躍。將 CI 失敗輸出或審查者評論貼上到聊天中，並要求 Claude 解決它們。要讓 Claude 自動監控 PR，請參閱[自動修復拉取請求](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)。212 會話在建立 PR 後保持活躍。將 CI 失敗輸出或審查者評論貼上到聊天中，並要求 Claude 解決它們。若要讓 Claude 自動監控 PR，請參閱[自動修復拉取請求](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)。

211 </Step>213 </Step>

212</Steps>214</Steps>

213 215

Documentation 2026-09-18 23:58 UTC to 2026-09-19 23:57 UTC