自託管環境快速入門
設定您的第一個自託管環境：安裝 Claude Code、建立環境、啟動執行器，並將工作階段路由到該環境。
自託管環境在您的組織運營的基礎設施上執行 Claude Code 雲端工作階段，由您部署的執行器程序執行。本快速入門設定您的第一個環境，這是最小的可行設定：單一主機上的一個執行器，執行一個測試工作階段。有兩個步驟：建立環境、啟動執行器並將工作階段路由到該環境，然後從您的終端傳送後續訊息到執行中的工作階段。您將在兩個介面之間移動：claude.ai 用於建立環境、檢查其狀態和路由工作階段，以及主機上的終端用於執行器執行的所有操作。
完成後，您將在雲端環境管理頁面上擁有一個環境、一個輪詢工作的執行器，以及在您的主機上執行的工作階段。在連接真實存放庫或內部系統之前，請完成部署到生產環境，其中涵蓋安全態勢、出口控制、git 認證和編排。
先決條件
組織和角色
claude.ai 端需要：
- 允許自託管環境由擁有者在雲端環境管理頁面上開啟；在開啟之前，新增按鈕不會出現。如果您不持有該角色，持有該角色的人可以建立環境並將其密鑰交給您；本頁面上的執行器和終端步驟不需要 claude.ai 角色，而在步驟檢查管理 UI 中的狀態時，執行器自己的日誌行會給您相同的信號。
- 您的組織的 GitHub 連接，以便開發人員在啟動工作階段時可以選擇存放庫。
主機和網路
執行器主機需要：
- 具有到
api.anthropic.com的出站 HTTPS、到claude.ai和下面安裝步驟重定向到的下載主機，以及到您的 git 主機以進行複製的 Linux 或 macOS 主機或容器；網路需求表有完整清單。Windows 不支援作為執行器主機；改為在 Linux 容器中執行執行器。開發人員工作站不受影響，因為工作階段從瀏覽器中的 claude.ai 啟動。 - 用於測試工作階段的儲存庫：公開儲存庫，或此主機已能透過其 HTTPS URL 複製且不會被要求提供憑證的儲存庫。
- 與實時同步的時鐘，例如使用 NTP。當時鐘偏差超過五分鐘時，驗證失敗；請參閱疑難排解。
執行器主機上的軟體
在啟動之前在主機上安裝：
- Claude Code v2.1.224 或更新版本，使用任何標準安裝方法。執行器是標準
claude二進位檔的一部分，較早版本無法識別self-hosted-runner子命令。原生安裝程式的預設latest頻道在發佈後立即提供每個版本；stable頻道、Homebrewclaude-codecask 和穩定 apt、dnf 和 apk 存放庫延遲約一週。若要固定您的艦隊執行的確切版本，請參閱安裝特定版本。對於容器映像，請參閱部署到生產環境中的 Dockerfile。 - Git 2.24 或更新版本。部署頁面上的某些 git 選項需要較新的版本；設定 git說明每個下限。
確認主機已準備好：
claude self-hosted-runner --help
準備好的主機會列印執行器的使用文字，列出 --environment-secret-file 等旗標。在 2.1.224 之前的版本上，該命令會改為列印一般 claude --help 輸出；使用 claude update 升級或從 latest 頻道重新安裝。
設定環境和執行器
使用引導式設定或手動步驟。引導式設定是單一命令，會啟動互動式 Claude Code 工作階段，並引導您完成其餘步驟。在無法進行互動式工作階段的主機上，請改用手動步驟。當持有擁有者角色的人員已建立環境並將其密鑰交給您時，也請使用手動步驟，因為引導式設定需要以擁有者身分登入。
執行引導式設定
引導式設定會引導您在管理 UI 中建立環境、使用您保存的密鑰檔案啟動本機執行器、確認執行器註冊，並將速查表寫入 ./runner-setup/CHEAT-SHEET.md。執行之前，請確認您的登入狀態和版本：
- 登入：在您已使用持有擁有者角色的帳戶透過
claude auth login登入的機器上執行它。若僅使用 API 金鑰或第三方模型提供者，工作階段會啟動，但其組織檢查會失敗。 - 版本：確認版本檢查已通過。在 2.1.224 之前的版本上，setup 命令會啟動一個 Claude 工作階段，將這些字詞作為提示詞，而不是引導式設定。
若要啟動引導式設定，請在您的 shell 中執行設定子命令並按照提示進行：
claude self-hosted-runner setup
設定本身不會啟動測試工作階段：它會告訴您在 claude.ai/code 啟動一個。設定的最後一步會停止它所啟動的執行器。如果您在該步驟之前離開設定，執行器會繼續執行。若要在最後一步之後繼續，請在您的 shell 中使用 ./runner-setup/CHEAT-SHEET.md 中的命令再次啟動執行器，然後將工作階段路由到環境。
手動設定
在 claude.ai 上建立環境，從主機上的終端機啟動執行器，然後返回 claude.ai 確認執行器出現，並將工作階段路由到它。如果持有擁有者角色的人員已建立環境並將其密鑰交給您，請從步驟 2 開始。
建立環境
前往管理設定中的雲端環境頁面。在自託管環境下，選擇新增，命名環境，然後選擇建立。在精靈的第二步，選擇複製環境金鑰以複製環境密鑰，管理 UI 將其標記為環境金鑰。claude.ai 只顯示一次密鑰，您之後無法檢索它；它在建立後 365 天過期。環境的 ccpool_... ID 在其詳細對話方塊中保持可見；您需要它用於令牌驗證中的 aud 檢查，以及用於從 CI 分派測試工作階段。
如果您遺失密鑰或需要輪換它，請從環境的設定標籤建立新密鑰，將新密鑰推出到您的執行器，然後撤銷舊密鑰。持有已撤銷密鑰的執行器在下一次驗證輪詢時失敗並退出，記錄 poll auth failed，您的編排器使用新密鑰重新啟動它們。
啟動執行器
建立密鑰目錄。此命令和下一個命令使用 /etc/claude，這需要 root，且它們建立的密鑰檔案只能由執行它們的使用者讀取。如果執行器將以其他使用者身分執行，它會以 error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>') 退出。在這種情況下，請以執行器的使用者身分執行這兩個命令，並使用該使用者可寫入的目錄取代 /etc/claude，然後將相同路徑傳遞給 --environment-secret-file。執行器程序可以讀取的任何路徑都有效。
mkdir -p /etc/claude
將環境密鑰寫入檔案。下面的命令從您的終端讀取，以便密鑰保持在 shell 歷史記錄之外：貼上您複製的值，按 Enter，然後按 Ctrl-D，子 shell 的 umask 使檔案只能由其擁有者讀取。
(umask 077 && cat > /etc/claude/environment-secret)
選擇基本目錄，將下面執行器命令中的 <writable-dir> 替換為執行器可以寫入或建立的絕對路徑。執行器在啟動時建立目錄，然後簽出存放庫並在其下建立每個工作階段的目錄。沒有 --base-dir，它使用 /workspace，這只在該目錄已存在且可寫或您以 root 身份啟動執行器時有效。
如果執行器無法建立或寫入路徑，它在啟動時會以命名目錄的錯誤退出，而不是註冊。請參閱疑難排解。
然後使用 --environment-secret-file 和 --base-dir 啟動執行器：
claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'
執行器向您的環境註冊後會記錄 Registered: runner_id=<runner-id>，然後開始輪詢工作。如果執行器之後退出，請自行重新啟動它。有關何時會發生這種情況，請參閱如果執行器退出。
驗證執行器出現
返回雲端環境頁面。您的環境狀態在執行器啟動後幾秒內從未部署執行器變更為健康；開啟環境並選擇活動以查看執行器本身。如果您無法存取管理頁面，上一步執行器日誌中的 Registered: runner_id=<runner-id> 行可提供相同的訊號。
將工作階段路由到環境
在 claude.ai/code 啟動工作階段，並從環境選擇器中選擇您的環境，其中自託管環境與 Anthropic 託管的環境並排出現。對於儲存庫，請選擇先決條件中的儲存庫：公開儲存庫，或此主機已可以複製的儲存庫。執行器使用主機已有的任何 git 憑證進行複製。
下一個可用的執行器會拾取佇列中的工作階段，並記錄 Picked up session <session-id> 以及其活動計數和容量，因此您可以從執行器自己的輸出確認哪個主機接收了工作階段。在 claude.ai/code 觀看工作階段工作並閱讀 Claude 的回覆。
如果工作階段沒有開始工作，請對照您看到的情況：
如果執行器退出
如果執行器在此快速入門期間退出，請使用相同的命令再次啟動它。執行器可能會自行退出：
- 工作階段已完成：日誌顯示
[runner:exit] account workload drained — exiting。執行器在其活動工作階段完成後按設計退出。請參閱執行器生命週期。 - 失去聯繫：日誌顯示一行
[runner:fatal]，並帶有runner record gone server-side或poll auth failed。如果執行器與 Anthropic 失去聯繫一段時間，例如因為主機進入睡眠狀態，它可能會在下次連線到 Anthropic 時退出。
完成一個回合並不會結束您的測試工作階段。第一個回合之後，工作階段仍處於附加狀態，執行器也仍在執行，因此您可以向工作階段傳送後續訊息，而無需先重新啟動執行器。
對於生產環境，在編排器下部署執行器，該編排器在退出時重新啟動它，並在執行器啟動後立即持續退出時等待更長的時間再重新啟動。請參閱部署到生產環境和當執行器退出時。
傳送後續訊息到執行中的工作階段
一旦工作階段在您的環境上執行，從任何您使用 claude auth login 登入的機器上的 claude CLI 傳送後續訊息；該命令不需要從啟動工作階段的機器執行。該命令發佈一條訊息：
claude -p "your message" --cloud <session-id>
對於 <session-id>，傳遞裸 session_... 或 cse_... ID 或工作階段的 claude.ai/code URL。成功傳送會列印 Sent to cloud session. 以及工作階段 ID 和檢視連結。接受的 ID 形式、JSON 輸出，以及帳戶和原則需求在從 CLI 傳送後續訊息上，因為該命令對 Anthropic 託管的工作階段的工作方式相同。