SpyBara
Go Premium

self-hosted-environments.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

This page contains 164 additions and 0 deletions.

2026
Sat 12 03:02 Fri 18 23:58

自託管環境

在您控制的基礎設施上執行 Claude Code 雲端工作階段：設定自託管環境、部署執行器，並將工作階段路由到您自己的運算資源。

自託管環境在您的組織運營的基礎設施上執行 Claude Code 雲端工作階段。雲端工作階段是指在開發者機器以外的任何地方執行的工作階段：開發者可以從 claude.ai、行動和桌面應用程式、終端機（使用 claude --cloud）和排程例行工作啟動這些工作階段，預設情況下它們在 Anthropic 的基礎設施上執行。在自託管環境中，這些相同的工作階段在您的網路內執行，開發者體驗基本相同，除了可用性和限制中的差異以及部署頁面的已知問題。

如果您的團隊不使用雲端工作階段，這裡沒有任何需要設定的內容：終端機或 IDE 中的工作階段始終在開發者自己的機器上執行。如果您想在自己的常駐機器上執行 Claude Code 並從其他裝置驅動它，請使用遠端控制，該功能也可在 Pro 和 Max 方案上使用。當您準備好設定時，請直接前往快速入門；如果您想先檢查安全狀況，請從部署到生產環境開始。本頁的其餘部分說明自託管的工作原理以及何時選擇它。

自託管環境的工作原理

自託管有三個部分：

  • 環境：雲端工作階段可以被發送到的命名目的地。您的組織在 claude.ai 管理設定中建立環境，每個環境都會分組一組執行器。
  • 執行器：在您網路內的主機上執行的程式。執行器執行工作階段；其概念與自託管 CI 執行器相同。
  • 工作階段：開發者啟動的一個 Claude Code 任務。

當開發者啟動雲端工作階段時，工作階段啟動 UI 會顯示一個環境選擇器，列出 Anthropic 託管的環境以及您的組織建立的任何環境。如果他們選擇您的環境，Anthropic 的控制平面會將工作階段放在您環境的佇列上，執行器會認領它、複製開發者選擇的儲存庫，並在您的主機上啟動 Claude Code 程序來執行它。執行器使用您設定的認證向您的 git 主機進行身份驗證；設定 git 涵蓋了各種選項。工作階段從您網路內部到達您的內部服務，當它是內部的時，也以相同方式到達您的 git 主機；到 Anthropic 的流量、佇列輪詢、工作階段的事件流和模型推理是對 api.anthropic.com 的出站 HTTPS，以及工作階段可以到達的進一步主機的簡短清單在網路需求中。Anthropic 永遠不會連接到您的網路。

自託管環境的架構圖：您的網路邊界包含一個執行器、其內部的兩個 Claude Code 工作階段程序和您的 git 主機，外部有 api.anthropic.com 持有佇列、工作階段流和推理。執行器輪詢佇列並到達 git 主機，每個工作階段程序開啟自己的流、推理和 git 連接，每個連接都是從您的網路出站，沒有入站。 
<img src="https://mintcdn.com/claude-code/Y0sJ2uDoOVbOVZrQ/images/self-hosted-network-paths-dark.svg?fit=max&auto=format&n=Y0sJ2uDoOVbOVZrQ&q=85&s=fec6aef3b0740d80eaf6d6a7000a2233" className="hidden dark:block" alt="自託管環境的架構圖：您的網路邊界包含一個執行器、其內部的兩個 Claude Code 工作階段程序和您的 git 主機，外部有 api.anthropic.com 持有佇列、工作階段流和推理。執行器輪詢佇列並到達 git 主機，每個工作階段程序開啟自己的流、推理和 git 連接，每個連接都是從您的網路出站，沒有入站。" width="680" height="320" data-path="images/self-hosted-network-paths-dark.svg" />

圖表中的兩個 Claude Code 方塊是工作階段程序：一個執行器同時執行兩個工作階段，達到其設定的容量。執行器一次為一個擁有者服務，並在認領其第一個工作階段時鎖定到該擁有者，因此簽出的程式碼永遠不會在擁有者之間混合；執行器生命週期涵蓋了該規則。

您可以自己啟動執行器並保持它們執行，或執行自動擴展協調器，這是您託管的第二個程序，它在工作階段佇列時啟動執行器；每個執行器在其工作完成時自行退出。無論哪種方式，您都只需設定一次環境，它就會出現在每個支援的表面上的選擇器中。

可用性和限制

在規劃推出之前，請檢查這些內容：

為什麼要自託管

大多數團隊最好由 Anthropic 託管的環境服務，這些環境不需要基礎設施來執行或維護。自託管適用於網路、工具或合規要求要求在其控制的基礎設施上保持工作階段執行的團隊。如果是這樣，請為其帶來的操作所有權做好計劃：您構建和維護執行器映像、操作艦隊並控制其網路。

作為交換，自託管為您提供網路存取、自訂工具和合規控制：

  • 網路存取：工作階段在您的網路內執行，可以到達內部服務、資料庫和登錄，而無需將它們暴露給公網
  • 自訂工具：在執行器映像中預先安裝編譯器、SDK 和內部 CLI，以便每個工作階段都準備好構建
  • 合規：儲存庫簽出和構建工件保留在您控制的基礎設施上。工作階段內容仍然會發送到 api.anthropic.com 進行模型推理。

環境、執行器和工作階段

環境在 claude.ai 管理設定中的雲端環境頁面上進行管理；執行器是您在自己的基礎設施上啟動和管理的程序。

關鍵概念

這些術語在整個自託管頁面中出現：

術語 它是什麼
環境 您的執行器的命名分組，在 claude.ai 設定中建立。工作階段被路由到環境，而不是單個執行器。
環境祕密 執行器用來向環境進行身份驗證和註冊的單一共享認證。在環境建立時顯示一次，在管理 UI 中標記為環境金鑰。
執行器 您部署的長期程序。執行器向環境註冊、接收執行器令牌並輪詢工作階段。
工作階段 一個 Claude Code 任務，從 claude.ai、行動應用程式或其他 Anthropic 表面（例如排程例行工作或代理）啟動。每個工作階段作為執行器生成的子 Claude Code 程序執行。

在 API 欄位、令牌聲明和度量名稱中，環境顯示為 pool，環境 ID 是 pool_id。參考映射了兩種拼寫，包括已棄用的 pool 標誌名稱。

執行器一次為一個擁有者服務。執行器認領的第一個工作階段將執行器鎖定到該工作階段的擁有者，執行器隨後只為該擁有者執行工作階段，達到設定的容量。擁有者是誰取決於工作階段如何啟動：

  • 使用者啟動的工作階段：擁有者是該使用者的帳戶。
  • Claude Tag 頻道工作階段：Claude 執行它們時沒有附加使用者帳戶，因此擁有者是啟動工作階段的 Claude Tag 代理。該代理啟動的每個頻道工作階段都有相同的擁有者，無論誰發送了 Slack 訊息，因此當您以 --capacity 大於 1 或正 --drain-grace-sec 執行它時，鎖定到它的執行器為不同人員啟動的工作階段服務。鎖定到使用者的執行器永遠不會認領這些，鎖定到 Claude Tag 代理的執行器永遠不會認領使用者的工作階段。

因此，最小艦隊大小是您預期同時活躍的擁有者數量，計算使用者和 Claude Tag 代理。

工作階段生命週期

當開發者啟動工作階段並選擇您的環境時，Anthropic 的控制平面將工作階段放在環境的佇列上。從那裡：

  1. 具有可用容量的執行器認領工作階段並持有其租約。
  2. 執行器將儲存庫複製到其工作目錄並生成子 Claude Code 程序。
  3. 子程序在執行器保持輪詢時透過 HTTPS 流回事件；每次輪詢都會刷新租約並充當心跳。
  4. 如果執行器停止輪詢約 60 秒，伺服器會將工作階段重新佇列到另一個執行器。

執行器為每個輪詢請求提供 10 秒。當請求超時、丟失或執行器無法解析的回應時，執行器會繼續為其活躍工作階段服務，並在一兩秒後重試，而不是等待下一個排程的輪詢。例如，用自己的頁面回答輪詢的攔截代理會產生執行器無法解析的回應。每次另一個請求以其中一種方式失敗時，執行器會將下一次重試前的間隔加倍，最多 20 秒，並在租約即將過期時縮短間隔。

執行器生命週期

執行器認領的第一個工作階段將執行器鎖定到該工作階段的擁有者，執行器為該擁有者執行最多 --capacity 個並行工作階段。當執行器有活躍工作階段且未收到關閉信號或達到其退休時間時，執行器會繼續認領鎖定擁有者的佇列工作。一旦它們完成會發生什麼取決於 --drain-grace-sec：

  • 在預設值 0 時：執行器在其活躍工作階段完成後立即退出，無需輪詢更多工作，因此您部署它的協調器（例如 Kubernetes）可以使用新磁碟重新啟動它，準備為任何擁有者服務。
  • 在正值時：執行器在退出前繼續輪詢鎖定擁有者的佇列那麼多秒。

此生命週期隔離每個擁有者的簽出程式碼，無需執行器在擁有者之間刪除磁碟狀態。

您的基礎設施停止執行器的方式決定您是否需要 --retire-at。傳遞 SIGTERM 的終止不需要標誌：執行器按照關閉時序所述進行排水，或當您設定 --defer-shutdown-max-min 時保持為其已持有的工作階段服務。如果您的基礎設施改為在已知的掛鐘時間銷毀主機而不發送信號，或寬限期太短而無法排水，例如沙箱生命週期上限或現貨實例回收，請傳遞 --retire-at <epoch-seconds> 設定為該時間前幾分鐘。在退休時間：

  1. 執行器停止接受新工作。
  2. 執行器透過 --release-idle-session-min 標誌使用的相同發佈路徑發佈每個活躍工作階段，因此當使用者發送下一條訊息時，工作階段在新執行器上恢復。執行器何時發佈每個工作階段取決於其狀態：
    • 執行器在工作階段進行中時立即發佈該工作階段，一旦該輪次完成。
    • 當輪次完成並留下執行中的背景任務時，執行器最多等待 60 秒，然後發佈工作階段，即使它們仍在執行中。如果任務已完成但讀取其結果的後續輪次尚未執行，執行器會保持工作階段直到該輪次完成，並等待不超過 SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS 以便該輪次開始。
  3. 執行器在所有工作階段都被發佈後以 0 退出。

超過終止的輪次仍然會丟失；關閉時序涵蓋了調整邊距的大小。沒有 --retire-at，無信號主機終止與崩潰無法區分：控制平面記錄丟失的工作者而不是乾淨的發佈，工作階段重新佇列到另一個執行器。

網路路徑

執行器及其工作階段進行多種出站連接，不需要來自 Anthropic 的入站連接：

  • 控制平面：執行器輪詢 api.anthropic.com 以獲取工作並發佈設定進度和失敗事件，全部出站 HTTPS。輪詢充當執行器的心跳。
  • SCM 連接器：可選的協調器 SCM 連接器 隧道是唯一的 WebSocket 連接。
  • Git：執行器透過 HTTPS 或 SSH 從您的 git 主機複製和推送，使用您的部署提供的認證進行身份驗證；設定 git 涵蓋了各種選項，包括每個工作階段鑄造的認證和 Anthropic git 代理，它透過 api.anthropic.com 路由 git。
  • 工作階段子程序：子 Claude Code 程序持有工作階段的事件流到 api.anthropic.com，並為模型推理和工作階段期間執行的 git 命令進行自己的出站呼叫。請參閱網路需求以取得完整的出站清單。上面的圖表顯示了這些路徑，除了可選的 SCM 連接器。

模型推理使用 Anthropic API。控制平面將 API 端點傳遞給每個工作階段，工作階段使用 Anthropic 發行的、工作階段範圍的 OAuth 令牌進行身份驗證，因此推理無法在自託管環境中透過 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 閘道路由。

支援公司出站代理。執行器和可選的自動擴展協調器遵守網路設定中描述的代理和 mTLS 環境變數，例如 HTTPS_PROXY 和 NO_PROXY；在每個程序的環境中設定它們。這些變數涵蓋控制平面呼叫、協調器的 SCM 連接器 WebSocket 和 HTTPS 遠端的內建複製，工作階段從執行器繼承它們。工作階段流使用透過 HTTPS 的伺服器發送事件，因此路徑中的代理不得緩衝回應。

如果您的代理還需要 Proxy-Authorization 標頭，執行器可以將其新增到它開啟到代理的每個連接；請參閱向出站代理進行身份驗證。

保留在您的基礎設施上的內容

儲存庫簽出、構建工件、祕密和工作階段建立或修改的任何檔案都保留在您配置的機器上。對話本身，包括提示、回應和工具結果，會發送到 api.anthropic.com 進行模型推理，Anthropic 儲存工作階段記錄，以便您可以從另一個支援的表面恢復工作階段。

自託管環境將工作階段執行移到您的網路中。控制平面仍然是 Anthropic 託管的：工作階段協調、佇列和 claude.ai 介面繼續在 Anthropic 的基礎設施上執行。

開始使用

自託管環境頁面按您正在做的事情組織：

  • 快速入門：安裝 Claude Code、建立環境、啟動執行器並路由您的第一個工作階段
  • 部署到生產環境：安全強化、網路出站、git 認證、Kubernetes 和 Compose 配方、已知問題和故障排除
  • 自訂工作階段：每個工作階段認證的包裝器指令碼、生命週期掛鉤、按需執行器、MCP 伺服器和權限
  • 端到端測試：CI 煙霧測試，在您推廣執行器映像之前驗證它
  • 參考：每個 CLI 標誌、環境變數、度量和健康端點
  • 驗證工作階段身份：在授予存取權限之前，從您自己的服務驗證工作階段令牌