31| 變數 | 說明 |31| 變數 | 說明 |
32| :- | :- |32| :- | :- |
33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 工作階段 JWT，前綴為 `sk-ant-cc-`。其 `act` 聲明識別工作階段建立者，並在建立的使用介面有記錄時包含建立者的電子郵件。該值是生成時的 token；重新整理會透過子程序的 stdin 到達，因此包裝指令碼只會看到初始值。請參閱[驗證工作階段身分](/docs/zh-TW/self-hosted-environments-identity)。 |33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 工作階段 JWT，前綴為 `sk-ant-cc-`。其 `act` 聲明識別工作階段建立者，並在建立的使用介面有記錄時包含建立者的電子郵件。該值是生成時的 token；重新整理會透過子程序的 stdin 到達，因此包裝指令碼只會看到初始值。請參閱[驗證工作階段身分](/docs/zh-TW/self-hosted-environments-identity)。 |
34| `CCR_SESSION_ACCOUNT_EMAIL` | 工作階段建立者的電子郵件，由執行器從 token 的 `act.email` 聲明中預先提取，未經簽章驗證。適合用於標籤，例如提交尾註。當電子郵件限制憑證發行時，請改為驗證 token 並從中讀取聲明；請參閱[佈建限定於工作階段建立者的憑證](#provision-credentials-scoped-to-the-session-creator)。當 token 不包含建立者電子郵件時未設定。請視為個人可識別資訊。 |34| `CCR_SESSION_ACCOUNT_EMAIL` | 工作階段建立者的電子郵件，由執行器從 token 的 `act.email` 聲明中預先提取，未經簽章驗證。適合用於標籤，例如提交尾註。當電子郵件限制憑證發行時，請改為驗證 token 並從中讀取聲明。請參閱[佈建限定於工作階段建立者的憑證](#provision-credentials-scoped-to-the-session-creator)。當 token 不包含建立者電子郵件時未設定，例如由您組織的服務身分建立的工作階段。請視為個人可識別資訊。 |
35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立工作階段的用戶端使用介面，例如 `web_claude_ai`、`desktop_app`、`ios`、`claude_code_cli` 或 `scheduled_trigger`。Anthropic 在工作階段建立時記錄該值一次，因此包裝指令碼和每個生命週期 hook 都會看到相同的值。僅將其用於採用分析和標籤，不要用作授權訊號。當工作階段沒有已記錄或可識別的使用介面時未設定，因此在 `set -u` 下請以 `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` 參照它。需要 Claude Code v2.1.229 或更新版本。 |35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立工作階段的用戶端使用介面，例如 `web_claude_ai`、`desktop_app`、`ios`、`claude_code_cli` 或 `scheduled_trigger`。Anthropic 在工作階段建立時記錄該值一次，因此包裝指令碼和每個生命週期 hook 都會看到相同的值。僅將其用於採用分析和標籤，不要用作授權訊號。當工作階段沒有已記錄或可識別的使用介面時未設定。需要 Claude Code v2.1.229 或更新版本。 |
36| `CLAUDE_RUNNER_CLAUDE_BIN` | 執行器自己的 Claude Code 二進位檔案的絕對路徑。以 `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` 結束您的包裝指令碼，以移交給固定的二進位檔案，而無需硬編碼安裝路徑。 |36| `CLAUDE_RUNNER_CLAUDE_BIN` | 執行器自己的 Claude Code 二進位檔案的絕對路徑。以 `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` 結束您的包裝指令碼，以移交給固定的二進位檔案，而無需硬編碼安裝路徑。 |
37| `CLAUDE_CODE_REMOTE_SESSION_ID` | 標記形式為 `cse_...` 的工作階段 ID。這與[生命週期 hook](#lifecycle-hooks) 以 `CLAUDE_RUNNER_SESSION_ID`（`session_...` 形式）看到的是相同工作階段；UUID 變數在兩者之間相符，將 `cse_` 前綴替換為 `session_` 會產生工作階段 URL 中顯示的 ID。 |37| `CLAUDE_CODE_REMOTE_SESSION_ID` | 標記形式為 `cse_...` 的工作階段 ID。這與[生命週期 hook](#lifecycle-hooks) 以 `CLAUDE_RUNNER_SESSION_ID`（`session_...` 形式）看到的是相同工作階段；UUID 變數在兩者之間相符，將 `cse_` 前綴替換為 `session_` 會產生工作階段 URL 中顯示的 ID。 |
38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | 標準 UUID 形式的相同工作階段 ID，適用於以 UUID 為鍵的系統。 |38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | 標準 UUID 形式的相同工作階段 ID，適用於以 UUID 為鍵的系統。 |
39| `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` | 對於屬於某個 Slack 討論串的 [Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段，為該討論串的連結。其他工作階段不會設定此變數，討論串工作階段也可能未設定。 |
40| `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` | 對於屬於某個 Slack 討論串的 Claude Tag 工作階段，為該討論串的 Slack 時間戳記，例如 `1700000000.000100`。可能未設定，且可能在 `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` 未設定時已設定，因此請分別檢查每個變數。 |
39| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | 保存目前工作階段 JWT 的每個工作階段檔案的絕對路徑，在 token 重新整理時保持最新。Shell 子程序在下載使用者新增到工作階段的附件時從中讀取其 `Authorization` 標頭。`exec` 會自動保留該變數；重建子程序環境的包裝指令碼必須帶上該變數，否則附件下載會無聲地停止運作。 |41| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | 保存目前工作階段 JWT 的每個工作階段檔案的絕對路徑，在 token 重新整理時保持最新。Shell 子程序在下載使用者新增到工作階段的附件時從中讀取其 `Authorization` 標頭。`exec` 會自動保留該變數；重建子程序環境的包裝指令碼必須帶上該變數，否則附件下載會無聲地停止運作。 |
40| `CLAUDE_CONFIG_DIR` | 每個工作階段的 Claude 設定目錄，在工作階段開始時從執行器在啟動時擷取的執行器主機設定快照中寫入；請參閱[權限和工具核准](#permissions-and-tool-approval)。此處的寫入隔離於此工作階段。工作階段結束後，該目錄會保留在 `<base-dir>/_sessions/` 下，除非您使用 [`--remove-session-state`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 啟動執行器；請參閱[重複使用預先準備的簽出](/docs/zh-TW/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout)。 |42| `CLAUDE_CONFIG_DIR` | 每個工作階段的 Claude 設定目錄，在工作階段開始時從執行器在啟動時擷取的執行器主機設定快照中寫入；請參閱[權限和工具核准](#permissions-and-tool-approval)。此處的寫入隔離於此工作階段。工作階段結束後，該目錄會保留在 `<base-dir>/_sessions/` 下，除非您使用 [`--remove-session-state`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 啟動執行器；請參閱[重複使用預先準備的簽出](/docs/zh-TW/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout)。 |
41| `ANTHROPIC_BASE_URL` | 子程序將使用的 API 基礎 URL，由控制平面按工作階段傳遞，通常為 `https://api.anthropic.com`。不要覆寫它：工作階段的推理憑證是 Anthropic 發行的 OAuth token，其他提供者不接受。 |43| `ANTHROPIC_BASE_URL` | 子程序將使用的 API 基礎 URL，由控制平面按工作階段傳遞，通常為 `https://api.anthropic.com`。不要覆寫它：工作階段的推理憑證是 Anthropic 發行的 OAuth token，其他提供者不接受。 |
43 45
44包裝指令碼也會繼承子程序的其餘受管環境，包括任何伺服器提供的環境變數。`exec` 會自動傳播所有內容；如果您的包裝指令碼以另一種方式生成子程序，請轉發完整環境。46包裝指令碼也會繼承子程序的其餘受管環境，包括任何伺服器提供的環境變數。`exec` 會自動傳播所有內容；如果您的包裝指令碼以另一種方式生成子程序，請轉發完整環境。
45 47
48`CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` 和 `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` 會傳到您的包裝指令碼或 [`command` hook](#command)。它們也會傳到工作階段執行的內容，例如 shell 命令、git hook 和 Claude Code hook。`checkout`、`post-session` 和 `spawn-runner` hook 不會收到它們。
49
50<h3 id="give-a-default-to-variables-that-can-be-unset">
51 為可能未設定的變數提供預設值
52</h3>
53
54`CCR_SESSION_ACCOUNT_EMAIL`、`CLAUDE_RUNNER_CLIENT_PLATFORM`、`CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` 和 `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` 都可能未設定。如果您的指令碼使用 `set -u`，Bash 在展開未設定的變數時會以 `unbound variable` 停止，因此請以預設值展開它們，例如 `${CCR_SESSION_ACCOUNT_EMAIL:-}`。
55
56在 shell 展開 Slack 討論串連結的任何地方，請採取以下預防措施：
57
58* **為其加上引號**：連結可能包含 shell 會處理的字元，例如 `?` 和 `&`，因此請為變數加上引號，如 `"${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}"`。
59* **不要將其值放入 `eval` 和 `sh -c` 字串中**：不要將其值代入 `eval` 或 `sh -c` 執行的字串，即使在引號內也不行。請改為讓該字串參照變數。
60
46<h3 id="keep-stdin-and-file-descriptor-3-attached">61<h3 id="keep-stdin-and-file-descriptor-3-attached">
47 保持 stdin 和檔案描述符 3 連接62 保持 stdin 和檔案描述符 3 連接
48</h3>63</h3>
49 64
50子程序的 stdin 是執行器的控制通道。token 輪換和工作階段結束訊號會在其上到達。執行器也會在檔案描述符 3 上開啟一個管道，並從中讀取子程序的活動訊號以驅動閒置和啟動逾時。單純的 `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` 會自動保留兩者。65子程序的 stdin 是執行器的控制通道。token 輪換和工作階段結束訊號會在其上到達。執行器也會在檔案描述符 3 上開啟一個管道，並從中讀取子程序的活動訊號以驅動閒置和啟動逾時。單純的 `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` 會自動保留兩者。
51 66
52如果您的包裝指令碼使用單獨的 `&` 在背景中執行子程序，它會切斷子程序的 stdin：工作階段看起來健康，直到初始 OAuth token 大約 30 分鐘的生命週期過期，然後每個 API 呼叫都會失敗，並出現 `401 authentication_error`。如果您的包裝指令碼必須在背景中執行子程序，例如為了讓拆卸 trap 保持作用，請將 stdin 儲存在檔案描述符 4 或更高的編號上，並明確重新連接它：67如果您的包裝指令碼使用單獨的 `&` 在背景中執行子程序，它會切斷子程序的 stdin。工作階段看起來健康，直到初始 OAuth token 大約 30 分鐘的生命週期過期，然後每個使用該 token 的 API 呼叫都會失敗，並出現 `401 authentication_error`。如果您的包裝指令碼必須在背景中執行子程序，例如為了讓拆卸 trap 保持作用，請將 stdin 儲存在檔案描述符 4 或更高的編號上，並明確重新連接它：
53 68
54```bash theme={null}69```bash theme={null}
55exec 4<&070exec 4<&0
59wait "$CHILD"74wait "$CHILD"
60```75```
61 76
62不要在包裝指令碼中關閉或重複使用檔案描述符 3。重新導向子程序的 stdout 和 stderr 是可以的。77您可以重新導向子程序的 stdout。請保持檔案描述符 3 和 stderr 連接到執行器：
78
79* **檔案描述符 3**：將子程序的活動訊號傳送給執行器。不要在包裝指令碼中關閉或重複使用它。
80* **stderr**：當包裝指令碼或子程序以非零狀態退出時，執行器會將 stderr 的最後幾行張貼到工作階段，並在自己的日誌中印出。工作階段的使用者會看到這些行，因此不要將祕密印到 stderr，並在部署包裝指令碼前移除 `set -x`。如果您重新導向 stderr，工作階段仍會執行，但執行器只會以退出碼回報失敗。
63 81
64<h3 id="pass-the-system-prompt-flags-through">82<h3 id="pass-the-system-prompt-flags-through">
65 傳遞系統提示詞旗標83 傳遞系統提示詞旗標
108 checkout126 checkout
109</h3>127</h3>
110 128
111每個儲存庫執行一次，取代執行器內建的複製與擷取。使用此 hook 從直讀式鏡像複製、從封存檔植入工作樹，或套用每個工作階段的 git 身分驗證。執行器會設定下列變數，也可能設定表格未列出的其他 `CLAUDE_RUNNER_` 變數：129每個儲存庫執行一次，取代執行器內建的複製與擷取。使用此 hook 從您透過 HTTPS 或 SSH 存取的直讀式鏡像複製、從封存檔植入工作樹，或套用每個工作階段的 git 身分驗證。執行器會設定下列變數，也可能設定表格未列出的其他 `CLAUDE_RUNNER_` 變數：
112 130
113| 變數 | 說明 |131| 變數 | 說明 |
114| :- | :- |132| :- | :- |
115| `CLAUDE_RUNNER_REPO_URL` | 要複製的儲存庫 URL，在應用任何 `--git-host-rewrite` 和 `--git-ssh-rewrite` 之後 |133| `CLAUDE_RUNNER_REPO_URL` | 要複製的儲存庫 URL，在應用任何 `--git-host-rewrite` 和 `--git-ssh-rewrite` 之後 |
116| `CLAUDE_RUNNER_REPO_REF` | 要簽出的修訂版本：分支、標籤或提交 SHA，如會話要求的那樣。空表示儲存庫的預設分支。 |134| `CLAUDE_RUNNER_REPO_REF` | 要簽出的修訂版本，依工作階段的要求而定：分支、標籤、提交 SHA，或完整參照名稱，例如 `refs/pull/<number>/head`。空值表示儲存庫的預設分支。 |
117| `CLAUDE_RUNNER_CHECKOUT_PATH` | 工作樹必須留下的絕對路徑 |135| `CLAUDE_RUNNER_CHECKOUT_PATH` | 工作樹必須留下的絕對路徑 |
118| `CLAUDE_RUNNER_SESSION_ID` | 標記形式為 `session_...` 的會話 ID，用於記錄和相關性 |136| `CLAUDE_RUNNER_SESSION_ID` | 標記形式為 `session_...` 的會話 ID，用於記錄和相關性 |
119| `CLAUDE_RUNNER_SESSION_UUID` | 規範 UUID 形式的相同會話 ID |137| `CLAUDE_RUNNER_SESSION_UUID` | 規範 UUID 形式的相同會話 ID |
120| `CLAUDE_RUNNER_API_BASE_URL` | 用於會話範圍呼叫的 Anthropic API 基礎 URL |138| `CLAUDE_RUNNER_API_BASE_URL` | 用於會話範圍呼叫的 Anthropic API 基礎 URL |
121| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立會話的用戶端表面，例如 `web_claude_ai`、`desktop_app` 或 `ios`。當會話沒有記錄或識別的表面時未設定。 |139| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立工作階段的用戶端使用介面，例如 `web_claude_ai`、`desktop_app` 或 `ios`。當工作階段沒有已記錄或可辨識的使用介面時不會設定，因此在 `set -u` 下請以 `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` 參照它。需要 Claude Code v2.1.229 或更新版本。 |
122| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 會話存取權杖，用於會話範圍的 API 呼叫 |140| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 會話存取權杖，用於會話範圍的 API 呼叫 |
123| `GIT_CONFIG_COUNT`、`GIT_CONFIG_KEY_n`、`GIT_CONFIG_VALUE_n` | 執行器為您的 hook 所執行之 git 固定的 Git 設定。[生命週期 hook 內的 Git 設定](#git-configuration-inside-lifecycle-hooks)說明了這些設定。需要 Claude Code v2.1.280 或更新版本。 |141| `GIT_CONFIG_COUNT`、`GIT_CONFIG_KEY_n`、`GIT_CONFIG_VALUE_n` | 執行器為您的 hook 所執行之 git 固定的 Git 設定。[生命週期 hook 內的 Git 設定](#git-configuration-inside-lifecycle-hooks)說明了這些設定。需要 Claude Code v2.1.280 或更新版本。 |
124 142
125指令碼必須在 `CLAUDE_RUNNER_CHECKOUT_PATH` 留下一個工作樹，簽出在要求的修訂版本。分離的 HEAD 是可以的；執行器在頂部建立會話的工作分支。執行器之後驗證路徑包含 `.git`；如果您的掛鉤具體化非 git 來源（例如 Perforce 或解包的 tarball），請在執行器的環境中設定 `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` 以跳過該檢查。基於 Git 的流程（例如工作分支建立和推送結果）需要 git 簽出，因此使用 [`post-session` 掛鉤](#post-session)從非 git 樹匯出結果。143指令碼必須在 `CLAUDE_RUNNER_CHECKOUT_PATH` 留下一個簽出於所要求修訂版本的工作樹。分離的 HEAD 也可以，因為執行器會在其上建立工作階段的工作分支。
126 144
127執行器不會將 git 認證傳遞給掛鉤。相反，從會話的身份鑄造每個會話的複製認證：根據[驗證來自您的服務的權杖](/docs/zh-TW/self-hosted-environments-identity#verify-the-token-from-your-service)中所述，使用標準 JWT 庫針對 `CLAUDE_RUNNER_API_BASE_URL` 下的 JWKS 端點驗證 `CLAUDE_CODE_SESSION_ACCESS_TOKEN`，然後讓您的認證服務為權杖的 `act` 聲明中的身份發行短期複製認證。`CLAUDE_RUNNER_CLAUDE_BIN` 未在簽出掛鉤環境中設定，因此 `decode-token` 子命令在此不可用。回退到主機已有的任何 git 驗證（例如 SSH 代理、認證助手或 `.netrc`）也是一個選項。145在您的 hook 返回後，執行器會驗證 `CLAUDE_RUNNER_CHECKOUT_PATH` 包含 `.git`。如果您的 hook 具體化的是非 git 來源（例如 Perforce 或解開的 tarball），請在執行器的環境中設定 `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` 以略過該檢查。基於 Git 的流程（例如建立工作分支與推送結果）需要 git 簽出，因此請使用 [`post-session` hook](#post-session) 從非 git 樹匯出結果。
128 146
129當掛鉤以非零狀態退出，或以 0 退出而沒有在後面留下可用的簽出時，執行器執行的操作取決於儲存庫：147<h4 id="get-git-credentials-in-the-hook">
148 在 hook 中取得 git 憑證
149</h4>
130 150
131* **會話推送結果的儲存庫**：執行器失敗會話，在非零退出時將指令碼的 stderr 尾部呈現給使用者。151執行器不會將 git 憑證傳遞給 hook。`decode-token` 子命令在此也無法使用，因為 `CLAUDE_RUNNER_CLAUDE_BIN` 未在 checkout hook 環境中設定。請改為從工作階段的身分產生每個工作階段的複製憑證，或退而使用主機本身的 git 身分驗證：
132* **會話只從中讀取的儲存庫**，例如新增到執行中會話的儲存庫：執行器記錄帶有失敗詳細資訊的 `[runner:warn]` 行，向會話發佈 `Skipped` 步驟，移除掛鉤在簽出路徑留下的任何內容，並繼續處理其餘儲存庫。當執行器無法立即移除路徑時，它會在會話結束時重試移除。如果跳過使會話完全沒有儲存庫，執行器仍然會失敗會話。
133 152
134在 v2.1.228 之前，執行器在任何儲存庫的掛鉤失敗時失敗會話，因此掛鉤無法提供的唯讀儲存庫在會話在每個新執行器上恢復時再次失敗會話。153* **每個工作階段的複製憑證**：依照[從您的服務驗證 token](/docs/zh-TW/self-hosted-environments-identity#verify-the-token-from-your-service)所述，使用標準 JWT 函式庫，針對 `CLAUDE_RUNNER_API_BASE_URL` 下的 JWKS 端點驗證 `CLAUDE_CODE_SESSION_ACCESS_TOKEN`。接著讓您的憑證服務為 token 的 `act` 宣告中的身分核發短期複製憑證。請以 `act.sub` 作為該憑證的識別鍵，且不要要求 `act.email`。
154* **主機 git 身分驗證**：使用主機已有的任何 git 身分驗證，例如 SSH agent、憑證輔助程式或 `.netrc`。
135 155
136執行器在會話結束後移除簽出路徑。156<h4 id="when-the-hook-fails">
157 hook 失敗時
158</h4>
159
160當 hook 以非零狀態結束，或以 0 結束卻未留下可用的簽出時，即視為 hook 失敗：
161
162* **會話推送結果的儲存庫**：執行器失敗會話，在非零退出時將指令碼的 stderr 尾部呈現給使用者。
163* **工作階段只會讀取的儲存庫**，例如新增到執行中工作階段的儲存庫：執行器會記錄一行帶有失敗詳細資訊的 `[runner:warn]`，向工作階段發佈 `Skipped` 步驟，移除 hook 在簽出路徑留下的任何內容，並繼續處理其餘儲存庫。如果略過後工作階段完全沒有任何儲存庫，執行器仍會使工作階段失敗。
164
165當 hook 成功時，執行器會在工作階段結束後移除簽出路徑。
137 166
138<h3 id="post-session">167<h3 id="post-session">
139 post-session168 post-session
151| `CLAUDE_RUNNER_WORKSPACE_PATHS` | 會話工作樹的冒號分隔絕對路徑。零儲存庫會話為空。 |180| `CLAUDE_RUNNER_WORKSPACE_PATHS` | 會話工作樹的冒號分隔絕對路徑。零儲存庫會話為空。 |
152| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | 會話的偵錯日誌的路徑，在掛鉤執行時仍在磁碟上 |181| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | 會話的偵錯日誌的路徑，在掛鉤執行時仍在磁碟上 |
153| `CLAUDE_RUNNER_API_BASE_URL` | 用於會話範圍呼叫的 Anthropic API 基礎 URL |182| `CLAUDE_RUNNER_API_BASE_URL` | 用於會話範圍呼叫的 Anthropic API 基礎 URL |
154| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立會話的用戶端表面，例如 `web_claude_ai`、`desktop_app` 或 `ios`。當會話沒有記錄或識別的表面時未設定。需要 Claude Code v2.1.229 或更新版本。 |183| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立工作階段的用戶端使用介面，例如 `web_claude_ai`、`desktop_app` 或 `ios`。當工作階段沒有已記錄或可辨識的使用介面時不會設定，因此在 `set -u` 下請以 `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` 參照它。需要 Claude Code v2.1.229 或更新版本。 |
155| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 會話存取權杖，用於會話範圍的 API 呼叫 |184| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 會話存取權杖，用於會話範圍的 API 呼叫 |
156| `GIT_CONFIG_COUNT`、`GIT_CONFIG_KEY_n`、`GIT_CONFIG_VALUE_n` | 執行器為您的 hook 所執行之 git 固定的 Git 設定。[生命週期 hook 內的 Git 設定](#git-configuration-inside-lifecycle-hooks)說明了這些設定。需要 Claude Code v2.1.280 或更新版本。 |185| `GIT_CONFIG_COUNT`、`GIT_CONFIG_KEY_n`、`GIT_CONFIG_VALUE_n` | 執行器為您的 hook 所執行之 git 固定的 Git 設定。[生命週期 hook 內的 Git 設定](#git-configuration-inside-lifecycle-hooks)說明了這些設定。需要 Claude Code v2.1.280 或更新版本。 |
157 186
158`CLAUDE_RUNNER_EXIT_REASON` 採用四個值之一：187`CLAUDE_RUNNER_EXIT_REASON` 採用四個值之一：
159 188
160* `completed`：會話乾淨地結束。Claude Code 程序正常退出，或會話在仍在執行時被存檔或刪除。189* `completed`：工作階段正常結束。Claude Code 程序正常結束，或在工作階段被封存或刪除後自行結束。
161* `failed`：Claude Code 程序崩潰，或在它啟動後設定失敗。190* `failed`：Claude Code 程序崩潰，或在它啟動後設定失敗。
162* `interrupted`：執行器停止了會話。它釋放會話以釋放插槽、會話在啟動時逾時、伺服器將會話移出此執行器、執行器正在排水，或會話超過其 [`--kill-session-after-min`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 限制。191* `interrupted`：執行器停止了工作階段，屬於下列其中一種情況：
192 * 執行器釋放工作階段以空出插槽。
193 * 工作階段在啟動時逾時。
194 * 伺服器將工作階段移出此執行器。
195 * 執行器的輪詢在程序結束前察覺到封存或刪除。
196 * 執行器正在排空。
197 * 工作階段超過其 [`--kill-session-after-min`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 限制。
163* `abandoned`：保留給另一個執行器聲稱的會話。掛鉤目前在該情況下不觸發。198* `abandoned`：保留給另一個執行器聲稱的會話。掛鉤目前在該情況下不觸發。
164 199
165[會話生命週期計數器](/docs/zh-TW/self-hosted-environments-reference#session-lifecycle-counter-semantics)將釋放、啟動逾時和伺服器移動計為 `completed` 而不是 `interrupted`，因為執行器乾淨地交回了插槽。如果您將掛鉤收據與計數器進行比較，請預期該差異。200如果您將 hook 收到的結果與[工作階段生命週期計數器](/docs/zh-TW/self-hosted-environments-reference#session-lifecycle-counter-semantics)進行比較，請預期部分 `interrupted` 結果在計數器中會被計為 `completed`。計數器會將釋放、啟動逾時、伺服器移動，以及由執行器輪詢先察覺到的封存或刪除計為 `completed`，因為執行器已乾淨地交回插槽。
166 201
167掛鉤的結束狀態永遠不會影響會話結果；失敗被記錄並忽略。執行器在每個會話結束（包括執行器關閉）時等待最多 `--post-session-hook-timeout-sec`（預設 60 秒）。此範例將未提交的工作保存到救援分支：202掛鉤的結束狀態永遠不會影響會話結果；失敗被記錄並忽略。執行器在每個會話結束（包括執行器關閉）時等待最多 `--post-session-hook-timeout-sec`（預設 60 秒）。此範例將未提交的工作保存到救援分支：
168 203
169```bash theme={null}204```bash theme={null}
170#!/usr/bin/env bash205#!/usr/bin/env bash
171set -u206set -u
207export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}
172IFS=':'208IFS=':'
173# -c overrides beat repo-local settings, blocking session-written fsmonitor,209# -c overrides beat repo-local settings, blocking session-written fsmonitor,
174# hook-path, and gpg-program config from executing code with the hook's210# hook-path, and gpg-program config from executing code with the hook's
188done224done
189```225```
190 226
227指令碼中的 `GIT_ALLOW_PROTOCOL` 這一行將 git 限制為 HTTPS、HTTP 與 SSH 遠端。如果執行器的環境已自行設定非空的 `GIT_ALLOW_PROTOCOL` 清單，指令碼會保留該清單。
228
191hook 會使用執行器主機上其自身環境中可用的任何 git 憑證進行推送。在[映像中不含憑證的做法](/docs/zh-TW/self-hosted-environments-deploy#configure-git)下，包括內建複製經由 Anthropic git 代理伺服器進行時，都不會有任何憑證，因此請在推送前於 hook 內產生短期推送憑證：將 hook 在 `CLAUDE_CODE_SESSION_ACCESS_TOKEN` 中收到的工作階段 token 與您自己的 token 服務交換，並依照[驗證工作階段身分](/docs/zh-TW/self-hosted-environments-identity)所述進行驗證。當 hook 持有工作階段所沒有的憑證時，請將 `origin` 替換為由操作人員提供的 URL，並傳遞 `-c credential.helper=` 加上您自己的輔助程式。[生命週期 hook 內的 Git 設定](#git-configuration-inside-lifecycle-hooks)說明了工作階段寫入的設定仍可能影響哪些部分。229hook 會使用執行器主機上其自身環境中可用的任何 git 憑證進行推送。在[映像中不含憑證的做法](/docs/zh-TW/self-hosted-environments-deploy#configure-git)下，包括內建複製經由 Anthropic git 代理伺服器進行時，都不會有任何憑證，因此請在推送前於 hook 內產生短期推送憑證：將 hook 在 `CLAUDE_CODE_SESSION_ACCESS_TOKEN` 中收到的工作階段 token 與您自己的 token 服務交換，並依照[驗證工作階段身分](/docs/zh-TW/self-hosted-environments-identity)所述進行驗證。當 hook 持有工作階段所沒有的憑證時，請將 `origin` 替換為由操作人員提供的 URL，並傳遞 `-c credential.helper=` 加上您自己的輔助程式。[生命週期 hook 內的 Git 設定](#git-configuration-inside-lifecycle-hooks)說明了工作階段寫入的設定仍可能影響哪些部分。
192 230
193<h4 id="hook-timing-when-the-runner-releases-a-session">231<h4 id="hook-timing-when-the-runner-releases-a-session">
264| `CLAUDE_RUNNER_ORDER_ID` | 不透明的冪等性金鑰，每個啟動請求唯一，對 Kubernetes 資源名稱安全。將其用作您的佈建程式的去重金鑰。 |302| `CLAUDE_RUNNER_ORDER_ID` | 不透明的冪等性金鑰，每個啟動請求唯一，對 Kubernetes 資源名稱安全。將其用作您的佈建程式的去重金鑰。 |
265| `CLAUDE_RUNNER_SESSION_ID` | 此請求所針對的工作階段。它在每次重新請求工作階段時重複，因此將其用於記錄和路由，而不是作為去重金鑰。對於預熱請求為空，預熱請求會在設定 [`--min-idle`](/docs/zh-TW/self-hosted-environments-reference#orchestrator-cli-flags) 時在任何特定工作階段之前啟動待命執行器，因此不要假設變數已設定。 |303| `CLAUDE_RUNNER_SESSION_ID` | 此請求所針對的工作階段。它在每次重新請求工作階段時重複，因此將其用於記錄和路由，而不是作為去重金鑰。對於預熱請求為空，預熱請求會在設定 [`--min-idle`](/docs/zh-TW/self-hosted-environments-reference#orchestrator-cli-flags) 時在任何特定工作階段之前啟動待命執行器，因此不要假設變數已設定。 |
266| `CLAUDE_RUNNER_SESSION_UUID` | 相同的工作階段 ID，採用規範 UUID 形式。對於預熱請求為空。 |304| `CLAUDE_RUNNER_SESSION_UUID` | 相同的工作階段 ID，採用規範 UUID 形式。對於預熱請求為空。 |
267| `CLAUDE_RUNNER_ATTEMPT` | 此工作階段已有多少個啟動請求。對於預熱請求為 `0`。 |305| `CLAUDE_RUNNER_ATTEMPT` | 用於記錄的每個工作階段計數器。它不是重試次數，也不是請求次數。對於預熱請求為 `0`，但針對某個工作階段的請求也可能帶有 `0`。 |
268| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | 來自輪詢回應的 HTTP `Date` 標頭的伺服器時間。當 hook 驗證工作單 JWT 的 `exp` 時，請與此值進行比較，而不是本地時鐘，以容許時間偏差。當閘道省略標頭時為空。 |306| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | 來自輪詢回應的 HTTP `Date` 標頭的伺服器時間。當 hook 驗證工作單 JWT 的 `exp` 時，請與此值進行比較，而不是本地時鐘，以容許時間偏差。當閘道省略標頭時為空。 |
269| `CLAUDE_RUNNER_POOL_ID` | 新執行器應加入的環境的 ID，採用 `ccpool_...` 形式 |307| `CLAUDE_RUNNER_POOL_ID` | 新執行器應加入的環境的 ID，採用 `ccpool_...` 形式 |
270| `CLAUDE_RUNNER_ACCOUNT_ID` | 排隊工作階段的帳戶的標記 ID，用於按帳戶路由、配額或退款。不可用時為空，Claude Tag 頻道工作階段始終為空，這些工作階段沒有帳戶排隊。 |308| `CLAUDE_RUNNER_ACCOUNT_ID` | 排隊工作階段的帳戶的標記 ID，用於按帳戶路由、配額或退款。不可用時為空，Claude Tag 頻道工作階段始終為空，這些工作階段沒有帳戶排隊。 |
271| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | 排隊工作階段的帳戶的電子郵件。不可用時為空。將電子郵件視為個人可識別資訊，不要記錄它。 |309| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | 排隊工作階段的帳戶的電子郵件。不可用時為空。將電子郵件視為個人可識別資訊，不要記錄它。 |
272| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | 工作階段的第一個 git 來源的 URL，用於路由到預先準備了該儲存庫的執行器。工作階段沒有 git 來源時為空。 |310| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | 工作階段的第一個 git 來源的 URL，用於路由到預先準備了該儲存庫的執行器。工作階段沒有 git 來源時為空。 |
273| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | 工作階段的第一個 git 來源的修訂版本：分支、SHA 或標籤。未指定時為空。 |311| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | 工作階段的第一個 git 來源的修訂版本：分支、SHA、標籤或完整參照名稱。未指定時為空。 |
274| `CLAUDE_RUNNER_REPO_SOURCES` | 所有工作階段的 git 來源的 `{url, revision}` 的 JSON 陣列，用於在次要儲存庫上路由的 hook。沒有來源時為空。 |312| `CLAUDE_RUNNER_REPO_SOURCES` | 所有工作階段的 git 來源的 `{url, revision}` 的 JSON 陣列，用於在次要儲存庫上路由的 hook。沒有來源時為空。 |
275| `CLAUDE_RUNNER_CORRELATION_ID` | 在工作階段建立時提供的相關 ID，回顯以便 hook 可以將此工作單對應到建立工作階段的請求。工作階段沒有時為空。 |313| `CLAUDE_RUNNER_CORRELATION_ID` | 在工作階段建立時提供的相關 ID，回顯以便 hook 可以將此工作單對應到建立工作階段的請求。工作階段沒有時為空。 |
276| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立工作階段的用戶端表面，例如 `web_claude_ai`、`desktop_app`、`ios` 或 `scheduled_trigger`，用於採用分析。當工作階段沒有記錄或識別的表面時未設定，對於預熱請求也未設定；使用 `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]` 檢查它，在 `set -u` 下保持安全。 |314| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立工作階段的用戶端表面，例如 `web_claude_ai`、`desktop_app`、`ios` 或 `scheduled_trigger`，用於採用分析。當工作階段沒有記錄或識別的表面時未設定，對於預熱請求也未設定；使用 `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]` 檢查它，在 `set -u` 下保持安全。 |
282* **在啟動的執行器上使用 `--capacity 1`**：工作階段綁定的工作單恰好註冊一個綁定到該工作階段的執行器，因此更高的容量會新增永遠不會接收工作的插槽，執行器在啟動時會記錄警告。320* **在啟動的執行器上使用 `--capacity 1`**：工作階段綁定的工作單恰好註冊一個綁定到該工作階段的執行器，因此更高的容量會新增永遠不會接收工作的插槽，執行器在啟動時會記錄警告。
283* **預熱工作單註冊未綁定**：待命執行器未綁定到工作階段，並像固定群組執行器一樣聲稱已排隊的工作。321* **預熱工作單註冊未綁定**：待命執行器未綁定到工作階段，並像固定群組執行器一樣聲稱已排隊的工作。
284 322
285合約有四個佈建程式無關的規則：323無論您的 hook 在哪個平台上佈建，合約都有四條規則：
286 324
2871. **在 `CLAUDE_RUNNER_ORDER_ID` 上保持冪等性。** 重新傳遞相同的請求最多必須啟動一個執行器。從 ID 衍生確定性資源名稱，並讓您的平台拒絕重複項。不要改為在 `CLAUDE_RUNNER_SESSION_ID` 上進行金鑰設定。每次重新請求工作階段都會使用相同的工作階段 ID 和新的訂單 ID，因此按工作階段 ID 命名或去重的工作負載會為該工作階段建立一次，之後永遠不會再建立。3251. **在 `CLAUDE_RUNNER_ORDER_ID` 上保持冪等性。** 重新傳遞相同的請求最多必須啟動一個執行器。從 ID 衍生確定性資源名稱，並讓您的平台拒絕重複項。不要改為在 `CLAUDE_RUNNER_SESSION_ID` 上進行金鑰設定。每次重新請求工作階段都會使用相同的工作階段 ID 和新的訂單 ID，因此按工作階段 ID 命名或去重的工作負載會為該工作階段建立一次，之後永遠不會再建立。
2882. **不要重試工作負載。** 一個訂單 ID 最多意味著建立一個工作負載。如果執行器永遠不註冊，Anthropic 會在 `--expected-spawn-seconds` 後使用新的訂單 ID 重新請求。3262. **不要重試工作負載。** 一個訂單 ID 最多意味著建立一個工作負載。如果執行器永遠不註冊，Anthropic 會在 `--expected-spawn-seconds` 後使用新的訂單 ID 重新請求。
2893. **使用退出代碼合約。** 退出 0 表示已提交。退出 1 表示可重試的失敗；工作階段退避並被重新提供。退出 2 或更高表示不可重試；工作階段被阻止再次啟動，直到 [Owner](/docs/zh-TW/cloud-environments#organization-shared-environments) 在環境的 **Activity** 標籤中選擇 **Retry**。在非零退出時，hook 的 stderr 的尾部會作為失敗原因出現在那裡，因此將可操作的錯誤寫入 stderr，永遠不要寫入祕密。對於預熱請求，沒有工作階段失敗：協調器只在本地記錄非零退出，伺服器在租約後重新請求啟動。3273. **使用退出碼合約。** 以符合結果的狀態退出：
2904. **將 `--expected-spawn-seconds` 設定為至少您的 p99 啟動時間。** 這是伺服器端租約。所有協調器副本必須使用相同的值。328
329 * **退出 0**：已提交。
330 * **退出 1**：可重試的失敗。工作階段會退避並被重新提供。
331 * **退出 2 或更高**：不可重試的失敗。工作階段會被阻止再次啟動，直到使用者向其傳送新訊息，或 [Owner](/docs/zh-TW/cloud-environments#organization-shared-environments) 在環境的 **Activity** 標籤中對其選擇 **Retry**。
332
333 在非零退出時，hook 的 stderr 的尾部會作為失敗原因出現在 **Activity** 標籤中，因此將可操作的錯誤寫入 stderr，且永遠不要將祕密寫入其中。在 shell hook 中，請[保持暫時性失敗可重試](#keep-transient-failures-retryable-in-a-shell-hook)。
334
335 預熱請求沒有可失敗的工作階段：協調器只在本地記錄非零退出，伺服器會在 `--expected-spawn-seconds` 租約到期後重新請求啟動。
3364. **將 `--expected-spawn-seconds` 設定為至少您從啟動請求到執行器註冊的 p99 時間。** 從協調器收到啟動請求時開始計算，並包含在您的平台上等待容量的時間以及啟動時間。此值是伺服器端租約，工作單會隨之過期，因此工作負載耗時更長的執行器將無法註冊。所有協調器副本必須使用相同的值。
291 337
292hook 寫入 stdout 或 stderr 的所有內容都會出現在協調器的日誌中，認證會自動編輯。如果工作階段保持排隊，請檢查協調器的 `/healthz` 主體以取得佇列計數，然後在 [**Cloud environments** 管理頁面](https://claude.ai/admin-settings/cloud-environments) 上開啟您環境的 **Activity** 標籤：在那裡展開失敗的工作階段以查看其啟動錯誤，並選擇 **Retry** 以重新請求它。338hook 寫入 stdout 或 stderr 的所有內容都會出現在協調器的日誌中，認證會自動編輯。如果工作階段保持排隊，請檢查協調器的 `/healthz` 主體以取得佇列計數，然後在 [**Cloud environments** 管理頁面](https://claude.ai/admin-settings/cloud-environments) 上開啟您環境的 **Activity** 標籤：在那裡展開失敗的工作階段以查看其啟動錯誤，並選擇 **Retry** 以重新請求它。
293 339
294保持排隊且在 **Activity** 標籤中沒有啟動錯誤的工作階段可能意味著 hook 是在工作階段 ID 上進行金鑰設定的。若要確認，請檢查您的平台是否有該工作階段的第一個啟動請求的工作負載，以及沒有重新請求的工作負載。如果是這樣，請改為在 `CLAUDE_RUNNER_ORDER_ID` 上進行工作負載金鑰設定。340保持排隊且在 **Activity** 標籤中沒有啟動錯誤的工作階段可能意味著 hook 是在工作階段 ID 上進行金鑰設定的。若要確認，請檢查您的平台是否有該工作階段的第一個啟動請求的工作負載，以及沒有重新請求的工作負載。如果是這樣，請改為在 `CLAUDE_RUNNER_ORDER_ID` 上進行工作負載金鑰設定。
295 341
342<h4 id="keep-transient-failures-retryable-in-a-shell-hook">
343 在 shell hook 中保持暫時性失敗可重試
344</h4>
345
346在使用 `set -e` 的 shell hook 中，原本重試即可排除的失敗可能會阻止工作階段。hook 會在失敗的命令處停止，並以該命令本身的狀態退出，而協調器會對該狀態套用退出碼合約。許多失敗會回傳 2 或更高的狀態，例如命令未安裝時的 `127`，以及 `curl --fail` 遇到 HTTP 錯誤時的 `22`，因此它們會在第一次失敗時就阻止工作階段。
347
348已被 hook 阻止的工作階段會保持阻止狀態，直到使用者向其傳送新訊息，或 [Owner](/docs/zh-TW/cloud-environments#organization-shared-environments) 在環境的 **Activity** 標籤中對其選擇 **Retry**。
349
350若要將此類失敗改為退出 1，請將以下幾行直接放在 hook 的 `#!` 行下方，位於任何可能失敗的內容之前：
351
352```bash theme={null}
353set -e
354PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }
355trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
356```
357
358這幾行會改變 hook 其餘部分的行為，因此加入後，請檢查 hook 中是否有以下每種模式：
359
360* **單獨的 `exit 2` 或更高**：設定 trap 後，它會變成退出 1。對於任何重試都無法修正的錯誤，請改為以原因呼叫 `permanent`，例如 `permanent "namespace claude-runners does not exist"`。請在主 shell 中呼叫它，不要在 `$( )`、`( )` 或管線中呼叫。
361* **`exec`**：不要以 `exec` 開始 hook 的最後一個命令，因為 `exec` 會取代 shell，trap 將不會執行。
362* **第二個 `EXIT` trap**：第二個 `trap ... EXIT` 會取代第一個，因此請將兩者合併為單一 trap。將您的清理命令直接放在 `rc=$?;` 之後，並在每個命令結尾加上 `|| true;`。如此一來，清理在失敗和成功時都會執行，且失敗的清理命令不會設定 hook 的退出狀態。以下合併後的 trap 展示了其形式，其中 `your-cleanup-command` 代表您自己的命令：
363
364 ```bash theme={null}
365 trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
366 ```
367* **允許失敗的命令**：如果 hook 之前未使用 `set -e`，它現在會在第一個回傳非零的命令處停止，例如找不到任何結果的查詢，或被您的平台拒絕的重複提交。如果 hook 會根據結果採取動作，請將該命令作為 `if` 的條件。如果它忽略結果，請在該命令後加上 `|| true`。
368
369若要確認 trap 是否正常運作，請在 `trap` 行正下方新增一行，呼叫一個不存在的命令，例如 `no-such-command`。從您的 shell 執行 hook 檔案，確認 `echo $?` 輸出 `1`，然後移除該行。
370
296<h2 id="send-model-requests-to-bedrock-or-agent-platform">371<h2 id="send-model-requests-to-bedrock-or-agent-platform">
297 將模型請求傳送至 Bedrock 或 Agent Platform372 將模型請求傳送至 Bedrock 或 Agent Platform
298</h2>373</h2>
381將模型請求傳送至 Amazon Bedrock 或 Google Cloud 的 Agent Platform 的工作階段，與 Anthropic API 上的工作階段有以下差異：456將模型請求傳送至 Amazon Bedrock 或 Google Cloud 的 Agent Platform 的工作階段，與 Anthropic API 上的工作階段有以下差異：
382 457
383* **來自 claude.ai 的政策**：[伺服器管理設定](/docs/zh-TW/server-managed-settings)不會傳達至這些工作階段。Owner 在 Claude Code 管理設定中設定的組織政策也不會傳達，因此 Claude Code 不會在工作階段內強制執行這些政策。請將您所依賴的規則放入 runner 映像檔的[受管設定檔案](/docs/zh-TW/managed-settings#delivery-mechanisms)中。458* **來自 claude.ai 的政策**：[伺服器管理設定](/docs/zh-TW/server-managed-settings)不會傳達至這些工作階段。Owner 在 Claude Code 管理設定中設定的組織政策也不會傳達，因此 Claude Code 不會在工作階段內強制執行這些政策。請將您所依賴的規則放入 runner 映像檔的[受管設定檔案](/docs/zh-TW/managed-settings#delivery-mechanisms)中。
459* **帳戶 skill**：這些工作階段不會下載使用者的 claude.ai 帳戶所啟用的 skill。請參閱[每個工作階段的設定如何組成](#how-each-session’s-config-is-assembled)。
384* **檔案**：使用者在 claude.ai 或行動裝置或桌面應用程式中附加至工作階段的檔案不會傳達至工作階段，且 Claude 無法使用 [`SendUserFile` 工具](/docs/zh-TW/tools-reference)回傳檔案。請改將輸入檔案放在儲存庫中或 runner 上。460* **檔案**：使用者在 claude.ai 或行動裝置或桌面應用程式中附加至工作階段的檔案不會傳達至工作階段，且 Claude 無法使用 [`SendUserFile` 工具](/docs/zh-TW/tools-reference)回傳檔案。請改將輸入檔案放在儲存庫中或 runner 上。
385* **模型選擇**：Anthropic 的控制平面會傳送每個工作階段的模型，當工作階段在沒有指定模型的情況下啟動時，Claude Code 會使用該供應商的預設模型。Runner 會從其傳遞給工作階段的環境中移除 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_MODEL`。供應商頁面的範例會設定 `ANTHROPIC_MODEL`，但在 runner 的環境中，這兩個變數都沒有任何作用。[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#4-pin-model-versions) 和 [Agent Platform](/docs/zh-TW/google-vertex-ai#5-pin-model-versions) 的「固定模型版本」中的各模型系列變數確實會傳達至工作階段。這些變數決定的是 `opus` 等別名解析為哪個模型，而非完整模型 ID 解析為哪個模型。461* **模型選擇**：Anthropic 的控制平面會傳送每個工作階段的模型，當工作階段在沒有指定模型的情況下啟動時，Claude Code 會使用該供應商的預設模型。您無法透過 runner 環境中的 `ANTHROPIC_MODEL` 或 `ANTHROPIC_DEFAULT_MODEL` 選擇模型，但可以固定別名所解析的目標：
462 * **`ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_MODEL`**：即使供應商頁面的範例會設定 `ANTHROPIC_MODEL`，runner 仍會從其傳遞給工作階段的環境中移除這兩個變數。
463 * **各模型系列的固定變數**：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#4-pin-model-versions) 和 [Agent Platform](/docs/zh-TW/google-vertex-ai#5-pin-model-versions) 的「固定模型版本」中的變數確實會傳達至工作階段。這些變數決定的是 `opus` 等別名解析為哪個模型，而非完整模型 ID 解析為哪個模型。
386* **您的帳戶未提供的模型**：工作階段可能會在某則訊息上失敗，並出現指出該模型名稱的錯誤。請啟用您的開發人員可以選擇的模型、「固定模型版本」中所述的背景模型，以及[自動模式](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)所使用的分類器模型。在 Amazon Bedrock 上，請在您的政策中允許其中每一個模型。464* **您的帳戶未提供的模型**：工作階段可能會在某則訊息上失敗，並出現指出該模型名稱的錯誤。請啟用您的開發人員可以選擇的模型、「固定模型版本」中所述的背景模型，以及[自動模式](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)所使用的分類器模型。在 Amazon Bedrock 上，請在您的政策中允許其中每一個模型。
387* **網路搜尋和快速模式**：[網路搜尋](/docs/zh-TW/tools-reference#websearch-tool-behavior)在 Amazon Bedrock 上無法使用，而[快速模式](/docs/zh-TW/fast-mode)在兩個供應商上都無法使用。關於其他因供應商而異的功能，請參閱[因供應商而異的 CLI 功能](/docs/zh-TW/feature-availability#cli-capabilities-that-vary-by-provider)。465* **網路搜尋和快速模式**：[網路搜尋](/docs/zh-TW/tools-reference#websearch-tool-behavior)在 Amazon Bedrock 上無法使用，而[快速模式](/docs/zh-TW/fast-mode)在兩個供應商上都無法使用。關於其他因供應商而異的功能，請參閱[因供應商而異的 CLI 功能](/docs/zh-TW/feature-availability#cli-capabilities-that-vary-by-provider)。
388 466
411 489
412工作階段會繼承 runner 的環境，因此請在該處設定 [`ENABLE_TOOL_SEARCH`](/docs/zh-TW/mcp#scale-with-mcp-tool-search)，以控制 runner 產生的每個工作階段的 MCP 工具搜尋；各個值的說明請參閱 MCP 頁面。490工作階段會繼承 runner 的環境，因此請在該處設定 [`ENABLE_TOOL_SEARCH`](/docs/zh-TW/mcp#scale-with-mcp-tool-search)，以控制 runner 產生的每個工作階段的 MCP 工具搜尋；各個值的說明請參閱 MCP 頁面。
413 491
492<a id="connection-timing" />
493
494<h3 id="wait-for-mcp-servers-before-the-first-turn">
495 在第一個回合前等待 MCP 伺服器
496</h3>
497
498自架的工作階段會在兩個不同的時間點，短暫等待仍在連線中的 MCP 伺服器。錯過等待的伺服器，其工具在第一個回合開始時將不可用，之後無需您採取任何動作即會變為可用。這兩次等待如下：
499
500* **工作階段啟動**：在首次取得工具清單之前，工作階段預設最多會等待 5 秒，等待項目中設定了 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的 HTTP 或 SSE 伺服器；若您在 runner 的環境中設定了 [`MCP_CONNECTION_NONBLOCKING=0`](/docs/zh-TW/env-vars)，則會等待所有伺服器。否則，HTTP 和 SSE 伺服器會在背景中連線。工作階段在此等待期間，初始化速度會較慢。[`MCP_CONNECT_TIMEOUT_MS`](/docs/zh-TW/env-vars) 可變更 5 秒的預設值。
501* **第一個回合**：在訊息抵達後，第一個回合最多會等待 2 秒，等待仍在連線中的 stdio 伺服器。工作階段在此等待期間，第一個回覆會較慢。若要變更此等待的時間長度，請在 runner 的環境中設定 [`CLAUDE_CODE_MCP_STARTUP_WAIT_MS`](/docs/zh-TW/env-vars)。它不會變更此等待涵蓋哪些伺服器。需要 Claude Code v2.1.274 或更新版本。
502
503`claude mcp add` 沒有 `alwaysLoad` 旗標。若要設定此鍵，請改用 `claude mcp add-json` 加入伺服器，它會在伺服器的 JSON 中接受此鍵並將其寫入 `.claude.json`。在您的 Dockerfile 中：
504
505```dockerfile theme={null}
506RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user
507```
508
509如果伺服器的工具在之後的回合中也沒有出現，請依照 [MCP 伺服器](#mcp-servers)中的說明，檢查該伺服器是否有傳達到工作階段。
510
414<h3 id="turn-off-built-in-session-tools">511<h3 id="turn-off-built-in-session-tools">
415 關閉內建工作階段工具512 關閉內建工作階段工具
416</h3>513</h3>
571 668
572設定 `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` 以從不同路徑植入，或將其指向空目錄以停用植入。669設定 `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` 以從不同路徑植入，或將其指向空目錄以停用植入。
573 670
574儲存庫提交的 `.claude/settings.json` 會作為專案設定疊加於其上。在包含多個儲存庫的工作階段中，[最多只有一個儲存庫的檔案會生效](#repository-settings-in-sessions-with-several-repositories)。工作階段也會從執行器映像中的標準系統路徑讀取 [`managed-settings.json`](/docs/zh-TW/settings#where-settings-live)。其設定鍵是否與[伺服器受管設定](/docs/zh-TW/server-managed-settings)一併套用，取決於 [Claude Code 如何組合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)：預設情況下，當您的組織傳遞任何伺服器受管設定鍵時，工作階段會忽略執行器映像的檔案，但 [Claude Code 從每個管理來源讀取的設定鍵](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)除外，例如 `env` 區塊、沙箱鎖定、沙箱二進位檔路徑和 `forceRemoteSettingsRefresh`。請參閱[設定優先順序](/docs/zh-TW/settings#settings-precedence)。671工作階段也會讀取以下設定檔：
672
673* **專案設定**：儲存庫提交的 `.claude/settings.json` 會疊加於使用者層級基準之上。在包含多個儲存庫的工作階段中，[最多只有一個儲存庫的檔案會生效](#repository-settings-in-sessions-with-several-repositories)。
674* **受管設定**：工作階段會從執行器映像中的標準系統路徑讀取 [`managed-settings.json`](/docs/zh-TW/settings#where-settings-live)。關於其設定鍵是否與[伺服器受管設定](/docs/zh-TW/server-managed-settings)一併套用，請參閱 [Claude Code 如何組合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)。
675
676關於這些來源的套用順序，請參閱[設定優先順序](/docs/zh-TW/settings#settings-precedence)。
575 677
576當 Anthropic 的控制平面為工作階段提供 [Claude Code hook](/docs/zh-TW/hooks) 時，執行器會將其與您自己的設定並存安裝，而非覆寫您的設定。需要 Claude Code v2.1.229 或更新版本。678當 Anthropic 的控制平面為工作階段提供 [Claude Code hook](/docs/zh-TW/hooks) 時，執行器會將其與您自己的設定並存安裝，而非覆寫您的設定。需要 Claude Code v2.1.229 或更新版本。
577 679
579* **撰寫者**：控制平面以其自身部署中的固定常數填入這些指令碼，絕不來自個別工作階段或第三方輸入。681* **撰寫者**：控制平面以其自身部署中的固定常數填入這些指令碼，絕不來自個別工作階段或第三方輸入。
580* **仍受何者管控**：透過 `--settings` 傳遞的 hook 會進入一般的合併 hook 設定，而非受管層級，因此您的受管設定仍然適用。`disableAllHooks` 會停用它們，且它們不屬於 [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) 保持載入的類別。682* **仍受何者管控**：透過 `--settings` 傳遞的 hook 會進入一般的合併 hook 設定，而非受管層級，因此您的受管設定仍然適用。`disableAllHooks` 會停用它們，且它們不屬於 [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) 保持載入的類別。
581 683
684當使用者啟動自己的工作階段時，Claude Code 也會將[其 claude.ai 帳戶已啟用的 skill](/docs/zh-TW/skills#skills-in-cowork-and-cloud-sessions) 下載至該工作階段的設定目錄。[routine](/docs/zh-TW/routines) 執行不會取得其擁有者的 skill，而[將模型請求傳送至 Bedrock 或 Agent Platform](#send-model-requests-to-bedrock-or-agent-platform) 的工作階段則不會下載任何 skill。若這些工作階段需要某個 skill，請將其提交至儲存庫的 `.claude/skills/`，或將其加入您的執行器映像。
685
582在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段以外，自託管環境中的工作階段預設會關閉[自動記憶](/docs/zh-TW/memory#auto-memory)。若有應跨工作階段延續的指令，請使用執行器映像或儲存庫中的 `CLAUDE.md`。686在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段以外，自託管環境中的工作階段預設會關閉[自動記憶](/docs/zh-TW/memory#auto-memory)。若有應跨工作階段延續的指令，請使用執行器映像或儲存庫中的 `CLAUDE.md`。
583 687
584執行器對主機 `~/.claude/` 的快照不包含 `projects/` 目錄。自動記憶的預設儲存位置就位於該目錄下。如果您將記憶檔案放在那裡，執行器不會將其植入工作階段，這些檔案也不會開啟自動記憶。688執行器對主機 `~/.claude/` 的快照不包含 `projects/` 目錄。自動記憶的預設儲存位置就位於該目錄下。如果您將記憶檔案放在那裡，執行器不會將其植入工作階段，這些檔案也不會開啟自動記憶。
