> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 設定雲端環境 > 為 Claude Code 雲端工作階段設定雲端環境：網路存取層級、環境變數、設定指令碼和環境快取。 雲端環境需要 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)，該功能目前處於研究預覽階段，適用於 Pro、Max 和 Team 使用者，以及具有 [premium seats 或 Chat + Claude Code seats](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan) 的 Enterprise 使用者。 每個 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 都在雲端環境中執行。您可以設定環境以允許或拒絕 [網路存取](#access-levels)、為工作階段設定環境變數，以及在 Claude 開始工作前執行 [設定指令碼](#setup-scripts)。 相同的環境適用於您啟動雲端工作階段的任何地方：[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)、終端機搭配 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web)、[Claude Tag](https://claude.com/docs/claude-tag/overview)、[routines](/docs/zh-TW/routines)、[Claude 行動應用程式](/docs/zh-TW/mobile) 和 [Desktop 應用程式](/docs/zh-TW/desktop)。 [Remote Control](/docs/zh-TW/remote-control) 工作階段將網頁和行動介面連接到您自己機器上的工作階段，該工作階段使用您機器的網路和檔案，而不是雲端環境。Claude Tag 頻道工作階段僅使用 [共用環境](#organization-shared-environments)。

Default 環境

無論您透過[網頁](/docs/en/web-quickstart#connect-github)或 CLI 流程（例如 `/web-setup`）連線，上線設定都會為您設定 **Default**（預設）環境；如果網頁上線設定顯示環境表單而不是建立環境，請保持表單的預設值以取得相同的 **Default** 環境。**Default** 本身不帶有任何設定： * [**Trusted** 網路存取](#access-levels)：工作階段可以到達套件登錄檔和其他[允許清單中的網域](#default-allowed-domains)，但無法透過工作階段的網路到達其他任何內容。 * 無其他設定：**Default** 不定義任何環境變數或設定指令碼，因此工作階段只會以[預先安裝的工具](#installed-tools)開始。 只有 **Default** 可用時，每個工作階段都在其中執行。當您有多個環境時，工作階段會根據介面選擇一個： * 在網頁、桌面應用程式和行動應用程式上，工作階段使用[選擇器](#configure-your-environment)中顯示的環境。當您尚未選擇時，管理員設定的[組織預設](#organization-shared-environments)會填入選擇。 * 從 CLI，工作階段使用您的 [`/remote-env` 選擇](#select-an-environment-from-the-cli)，或回退到您第一個可用的雲端環境。 當預設不夠時，請設定環境：當 Claude 需要到達[預設允許清單](#default-allowed-domains)之外的網域、需要為其工作階段設定環境變數，或需要在開始工作前安裝相依性時。

設定您的環境

從 [claude.ai/code](https://claude.ai/code) 的環境選擇器建立、編輯和封存環境，您可以在 [網頁上線](/docs/zh-TW/web-quickstart) 後到達該選擇器。您建立的環境是您帳戶的個人環境；您的管理員建立的 [共用環境](#organization-shared-environments) 會出現在相同的選擇器中。請參閱 [已安裝的工具](#installed-tools) 以了解在沒有任何設定的情況下可用的內容。 在 [claude.ai/code](https://claude.ai/code) 上，選擇顯示目前環境名稱的雲端圖示，位於訊息框上方的列中。選擇器沒有設定頁面或直接 URL。 環境選擇器在 claude.ai/code 的訊息框上方開啟。顯示環境名稱 Default 的雲端按鈕位於訊息框上方的列中。開啟的選單列出一個 Local 列，其中包含 Download 和 Desktop only 標籤、一個 Cloud 部分，其中 Default 環境被選中並顯示勾號，懸停時顯示設定齒輪圖示、一個 Add cloud environment 選項，以及一個 Remote Control 部分，其中包含設定說明。 選擇 **Add cloud environment**，或懸停在現有環境上並選擇右側出現的設定圖示。對話框包括名稱、網路存取層級、環境變數和設定指令碼。 New cloud environment 對話框。一個 Name 欄位，預留位置為 Default，一個 Network access 選擇器設定為 Trusted，並連結到網路政策和存取層級、一個 Environment variables 框，顯示 .env 格式預留位置文字，並附註值對使用環境的任何人都可見、一個 Setup script 框，描述為在新工作階段啟動時執行的 Bash 指令碼，在 Claude Code 啟動前，以及 Cancel 和 Create environment 按鈕。

設定環境變數

環境變數使用 `.env` 格式，每行一個 `KEY=value` 對。純值不需要引號，如果您用匹配對引用值，引號不會成為值的一部分。引用跨越多行或包含 `#` 的值：在未引用的值中，`#` 開始註解，該行的其餘部分被丟棄。 以下範例定義三個變數。 ```text theme={null} NODE_ENV=development LOG_LEVEL=debug DATABASE_URL=postgres://localhost:5432/myapp ``` 每個工作階段在啟動時將環境的值複製一次到普通環境變數中，Claude 執行的任何命令都可以讀取。因為執行中的工作階段不會重新讀取設定，編輯或新增變數會影響您之後啟動的工作階段；已執行的工作階段保留它們啟動時的值。 任何使用環境的人都可以讀取值，雲端環境沒有專用的機密存放區，因此不要新增 API 金鑰或其他認證。如果工作階段仍然需要認證，請參閱 [您的設定中帶來的內容](#what-carries-over-from-your-setup)。

從 CLI 選擇環境

在您的終端機中執行 `/remote-env` 以選擇您從 CLI 建立的雲端工作階段的預設環境，例如 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web)。該命令開啟您現有環境的選擇器，並將您的選擇儲存到 [使用者設定](/docs/zh-TW/settings#settings-files) 中的 `remote.defaultEnvironmentId` 金鑰，因此它適用於您機器上的每個專案，直到您變更它，除非在更高優先順序的 [設定層](/docs/zh-TW/settings#settings-precedence)（例如儲存庫的專案設定）中設定了相同的金鑰。 `/remote-env` 只設定預設值：它不啟動工作階段，也不能新增或編輯環境。在 [claude.ai/code](https://claude.ai/code) 管理它們。

封存環境

若要封存環境，請開啟它進行編輯並選擇 **Archive**。您無法刪除環境，只能封存它。 封存會影響新工作階段，而不是執行中的工作階段： * 已在環境中執行的工作階段會繼續工作。 * 環境從選擇器和 `/remote-env` 中消失，因此您無法為新工作階段選擇它。 * 沒有新工作階段可以在任何介面上的已封存環境中啟動。如果環境是您儲存的 [CLI 預設值](#select-an-environment-from-the-cli)，CLI 雲端工作階段會回退到您第一個可用的雲端環境。任何明確使用環境設定的內容，例如 [routine](/docs/zh-TW/routines#environments-and-network-access)，無法在其中啟動新工作階段；將其指向另一個環境。

組織共用環境

Team 和 Enterprise 計畫上的擁有者和管理員可以建立與組織的每個成員共用的雲端環境。共用環境會出現在每個成員的環境選擇器中，與他們的個人環境並列，因此團隊可以標準化一個設定，而不是每個成員重新建立它。 從 [admin settings](https://claude.ai/admin-settings) 中的 **Cloud environments** 頁面建立、編輯和封存共用環境。每個共用環境都有一個名稱、一個 [網路存取層級](#access-levels)、`.env` 格式的 [環境變數](#set-environment-variables) 和一個 [設定指令碼](#setup-scripts)。擁有者和管理員在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 分別選擇組織的 [預設環境](#the-default-environment)。 共用環境中的值會到達該環境中每個成員的工作階段。與個人環境一樣，共用環境沒有專用的機密存放區，因此不要包含機密。 在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 頻道中，Claude 作為您組織的共用身分工作，而不是任何成員，因此頻道工作階段僅使用共用環境。您可以透過兩種方式設定頻道使用的環境： * 在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 將共用環境設定為組織的 [預設環境](#the-default-environment)。 * [將一個釘選到頻道](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one) 在 Claude Tag 管理員設定中。 共用環境會新增到成員的選擇器中，而不是取代它們。

網路存取

每個環境都設定一個網路存取層級，控制其工作階段可以進行的出站連線。預設層級 **Trusted** 允許套件登錄和其他[允許清單中的網域](#default-allowed-domains)；**Custom** 採用您自己的網域清單。 若要變更環境的網路存取，[開啟它進行編輯](#configure-your-environment)並在對話框中使用 **Network access** 選擇器。開啟選擇器的雲端圖示出現在[Default 環境](#the-default-environment)下列出的應用程式表面上，以及在[例行編輯器](/docs/zh-TW/routines#environments-and-network-access)中；個人環境在您的 claude.ai 帳戶設定中沒有單獨的頁面。 您在工作階段或例行上啟用的 MCP 連接器無需將其主機新增到 **Allowed domains**，因為連接器流量透過 Anthropic 的伺服器而不是工作階段的網路傳輸。您可以按工作階段或按例行配置連接器；移除任何您不需要的連接器，以限制 Claude 可以到達的工具。這依賴於[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下提到的相同 Anthropic 繫結通道。

存取層級

[環境對話框](#configure-your-environment)中的 **Network access** 欄位採用以下四個層級之一： | 層級 | 出站連線 | | :---------- | :-------------------------------------------------------- | | **None** | 透過工作階段的網路沒有出站網路存取 | | **Trusted** | 僅限[允許清單中的網域](#default-allowed-domains)：套件登錄、GitHub、雲端 SDK | | **Full** | 任何網域 | | **Custom** | 您自己的允許清單，可選擇性地包括預設值 | GitHub 操作使用[單獨的代理](#github-proxy)，獨立於此設定，Claude Code 對 Anthropic API 的連線在 **None** 時仍然有效，如[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下所述。

允許特定網域

若要允許不在 Trusted 清單中的網域，在環境的網路存取設定中選擇 **Custom**，然後在 **Allowed domains** 欄位中每行列出一個網域。此範例允許內部專案可能需要的三個主機。 ```text theme={null} api.example.com *.internal.example.com registry.example.com ``` 此環境中的工作階段現在可以到達 `api.example.com`、`internal.example.com` 的任何子網域和 `registry.example.com`，但透過工作階段的網路無法到達其他網域；[GitHub 流量](#github-proxy)和 [MCP 連接器流量](#network-access)不會通過此允許清單。前導 `*.` 符合每個子網域。若要同時保留[Trusted 網域](#default-allowed-domains)，請勾選 **Also include default list of common package managers**；不勾選則只允許您列出的內容。 每個環境都有自己的允許網域清單；沒有組織層級的允許清單可供管理員推送到每個成員的環境。[伺服器管理的設定](/docs/zh-TW/server-managed-settings)仍適用於雲端工作階段內，但其中沒有任何設定會將網域新增到環境的網路允許清單。

GitHub 代理

所有 GitHub 操作都通過專用代理，將您的真實 GitHub 認證保留在工作階段的 VM 外，獨立於環境的[存取層級](#access-levels)： * **Git 認證**：VM 內的 git 用戶端使用限定範圍的認證，代理驗證並將其交換為您的實際 GitHub 令牌。 * **API 請求**：來自內建 GitHub 工具的請求，以及來自 [`proxy-injected` 預留位置](#work-with-github-issues-and-pull-requests)下的 `gh` 的請求，會以您的真實認證替換後發出。 * **推送保護**：`git push` 僅適用於工作階段的目前工作分支；複製、擷取和 PR 操作正常運作。 * **儲存庫範圍**：GitHub API 和發行資產請求僅到達附加到工作階段的儲存庫，因此從未附加的儲存庫下載發行資產的設定指令碼會收到 403。 來自公開儲存庫的已提交檔案透過 `raw.githubusercontent.com` 到達，改由[安全代理](#security-proxy)處理。該網域在預設[Trusted 清單](#default-allowed-domains)中，因此除非環境的[存取層級](#access-levels)排除它，否則這些檔案保持可到達。

安全代理

雲端工作階段在 HTTP/HTTPS 網路代理後面執行，用於安全和濫用防止目的。所有出站網際網路流量都通過此代理，提供： * 防止惡意請求 * 速率限制和濫用防止 * 內容篩選以增強安全性 * 所請求主機名稱的 DNS 層級稽核軌跡

雲端工作階段中可用的內容

每個工作階段都會取得執行 Ubuntu 24.04 的全新虛擬機器 (VM)，無論您自己的作業系統為何，您的儲存庫已複製，常見的工具鏈已預先安裝。本節涵蓋這些預設值、內建 GitHub 工具、如何 [執行測試和服務](#run-tests-start-services-and-add-packages)，以及每個 VM 取得的 [資源限制](#resource-limits)。

您的設定中帶來的內容

雲端工作階段從您儲存庫的全新複製開始。您提交到儲存庫的任何內容都可用。您只在自己的機器上安裝或設定的任何內容在工作階段中都不可用。您組織的政策透過 [伺服器管理的設定](/docs/zh-TW/server-managed-settings) 分別到達。 | | 在雲端工作階段中可用 | 原因 | | :--------------------------------------------------------------------------------------------------------------------------------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 您的儲存庫的 `CLAUDE.md` | 是 | 複製的一部分 | | 您的儲存庫的 `.claude/settings.json` hooks | 是 | 複製的一部分 | | 您的儲存庫的 `.mcp.json` MCP 伺服器 | 是 | 複製的一部分 | | 您的儲存庫的 `.claude/rules/` | 是 | 複製的一部分 | | 您的儲存庫的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 複製的一部分 | | 在 `.claude/settings.json` 中宣告的 Plugins | 是 | 在工作階段啟動時從您宣告的 [marketplace](/docs/zh-TW/plugin-marketplaces) 安裝。需要網路存取以到達 marketplace 來源 | | 您組織的 [伺服器管理的設定](/docs/zh-TW/server-managed-settings) | 是 | 在工作階段啟動時從 Anthropic 的伺服器擷取。請參閱 [Surface coverage](/docs/zh-TW/model-config#surface-coverage) 以了解 `availableModels` 在雲端工作階段中如何強制執行。透過 MDM 或管理設定檔部署到您的裝置的設定不適用，因為工作階段在 Anthropic 管理的 VM 上執行 | | 您的使用者 `~/.claude/CLAUDE.md` | 否 | 位於您的機器上，不在儲存庫中 | | 您的使用者 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位於您的機器上，不在儲存庫中。改為將它們提交到儲存庫的 `.claude/` 目錄。雲端工作階段會自動載入您在 claude.ai 上啟用的技能 | | 僅在您的使用者設定中啟用的 Plugins | 否 | 使用者範圍的 `enabledPlugins` 位於 `~/.claude/settings.json`。改為在儲存庫的 `.claude/settings.json` 中宣告它們 | | 您使用 `claude mcp add` 在預設本機範圍或使用者範圍新增的 MCP 伺服器 | 否 | 這些寫入您機器上的 `~/.claude.json`，不是儲存庫。使用 `claude mcp add --scope project` 新增伺服器，該伺服器寫入儲存庫的 [`.mcp.json`](/docs/zh-TW/mcp#project-scope)，並提交該檔案 | | 您的儲存庫的 `.claude/settings.json` `env` 區塊中的傳輸變數，例如 `NODE_EXTRA_CA_CERTS` 和 [mTLS 用戶端憑證變數](/docs/zh-TW/network-config#mtls-authentication) | 否 | 託管環境管理工作階段的 API 連接，因此 Claude Code 忽略這些金鑰，並在工作階段的偵錯日誌中記錄每個忽略的金鑰 | | 靜態 API 令牌和認證 | 否 | 尚不存在專用的機密存放區。請參閱下文 | | 互動式驗證，例如 AWS SSO | 否 | 不支援。SSO 需要無法在雲端工作階段中執行的基於瀏覽器的登入 | 若要在雲端工作階段中提供您自己的設定，請將其提交到儲存庫。 尚不提供專用的機密存放區，對話框警告不要新增機密或認證：環境變數和設定指令碼位於環境設定中，使用環境的任何人都可以讀取它們。如果工作階段仍然需要認證，請考慮該可見性新增它。

已安裝的工具

雲端工作階段預先安裝了常見的語言執行時、建置工具和資料庫。下表按類別總結了包含的內容。 | 類別 | 包含 | | :------------ | :------------------------------------------------------------------- | | **Python** | Python 3.x，搭配 pip、poetry、uv、black、mypy、pytest、ruff | | **Node.js** | 20、21 和 22，透過 nvm，搭配 npm、yarn、pnpm、bun¹、eslint、prettier、chromedriver | | **Ruby** | 3.1、3.2、3.3，搭配 gem、bundler、rbenv | | **PHP** | 8.4，搭配 Composer | | **Java** | OpenJDK 21，搭配 Maven 和 Gradle | | **Go** | 最新穩定版，搭配模組支援 | | **Rust** | rustc 和 cargo | | **C/C++** | GCC、Clang、cmake、ninja、conan | | **Docker** | docker、dockerd、docker compose | | **Databases** | PostgreSQL 16、Redis 7.0 | | **Utilities** | git、jq、yq、ripgrep、tmux、vim、nano | ¹ Bun 已安裝，但在套件擷取時有已知的 [代理相容性問題](#install-dependencies-with-a-sessionstart-hook)。 如需確切版本，請要求 Claude 在雲端工作階段中執行 `check-tools`。它是安裝在工作階段 VM 上的 shell 命令，不是 slash command；您要求 Claude 是因為 [Claude 為您執行所有 VM 命令](#run-tests-start-services-and-add-packages)。 此清單之外的工具鏈，例如 .NET SDK，即使其套件登錄在 [預設允許清單](#default-allowed-domains) 上也不會預先安裝。使用 [設定指令碼](#setup-scripts) 安裝它們。

使用 GitHub 問題和提取請求

雲端工作階段包括內建 GitHub 工具，讓 Claude 無需任何設定即可讀取問題、列出提取請求、擷取差異和發佈評論。這些工具透過 [GitHub 代理](#github-proxy) 使用您在 [GitHub 驗證選項](/docs/zh-TW/claude-code-on-the-web#github-authentication-options) 下設定的任何方法進行驗證，因此您的令牌永遠不會進入容器。 您可以在 [環境設定](#set-environment-variables) 中自己設定 `GH_TOKEN` 或 `GITHUB_TOKEN`，或兩者都不設定，讓 [GitHub 代理](#github-proxy) 為您驗證： * 如果您設定令牌，它會原封不動地傳遞到容器，因此您的指令碼和 GitHub 的 [`gh` CLI](https://cli.github.com)（如果您安裝它）直接使用它。 * 如果您都不設定，[GitHub 代理](#github-proxy) 正在為您的工作階段處理驗證，兩個變數在 Claude 執行的命令中讀取為預留位置字串 `proxy-injected`，代理在出站 GitHub 請求上替換您的真實認證。`gh` 無需您自己的令牌即可工作，但直接讀取 `GITHUB_TOKEN` 的指令碼會取得預留位置，而不是可用的令牌。 您設定的令牌是普通環境變數，因此使用環境的任何人都可以讀取它；代理路徑將認證保留在環境設定和工作階段 VM 之外。 若要檢查哪種情況適用於您的工作階段，請要求 Claude 執行 `echo $GH_TOKEN`。 GitHub 的 [`gh` CLI](https://cli.github.com) 未預先安裝。如果您需要內建工具未涵蓋的 `gh` 命令，例如 `gh release` 或 `gh workflow run`，請自己安裝並驗證它： 將 `apt update && apt install -y gh` 新增到您的 [設定指令碼](#setup-scripts)。 如果 `echo $GH_TOKEN` 列印 `proxy-injected`，[GitHub 代理](#github-proxy) 為您驗證 `gh`，此步驟不必要。否則，將 `GH_TOKEN` 環境變數新增到您的 [環境設定](#set-environment-variables)，搭配 GitHub 個人存取令牌；與任何環境變數一樣，使用環境的任何人都可以讀取它，因此請狹隘地限定令牌範圍。`gh` 會自動讀取 `GH_TOKEN`，因此您不需要執行 `gh auth login`。 每個雲端工作階段在 claude.ai 上都有一個文字記錄 URL，工作階段可以從 `CLAUDE_CODE_REMOTE_SESSION_ID` 環境變數讀取自己的 ID。使用此在 PR 主體、提交訊息、Slack 貼文或產生的報告中放置可追蹤的連結，以便檢閱者可以開啟產生它們的執行。 Claude 在雲端工作階段中建立的提交包括 `Claude-Session: ` git 預告片，PR 主體包括工作階段 URL 在其自己的列上。這需要 v2.1.179 或更新版本。若要省略預告片和 PR 主體連結，請將 [`attribution.sessionUrl`](/docs/zh-TW/settings#attribution-settings) 設定為 `false`。此設定需要 v2.1.182 或更新版本。 若要在提交或 PR 以外的內容中包含工作階段連結，例如 Claude 發佈的 Slack 訊息或它寫入的報告檔案，請要求 Claude 執行以下命令並使用其輸出。該命令將環境變數值中的 `cse_` 前綴轉換為文字記錄 URL 預期的 `session_` 前綴： ```bash theme={null} echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}" ```

執行測試、啟動服務和新增套件

您無法進入工作階段 VM 的 shell。Claude 為您執行每個命令，因此請將本節中的工作表述為您提示中的請求。

執行測試

Claude 執行測試作為處理工作的一部分。在您的提示中要求它，例如「修復 `tests/` 中的失敗測試」或「在每次變更後執行 pytest」。隨 [預先安裝的工具鏈](#installed-tools) 提供的測試執行器（例如 pytest 和 cargo test）無需額外設定即可工作。您的專案宣告為相依性的執行器（例如 jest）會隨您的相依性一起安裝。

啟動服務

PostgreSQL 和 Redis 已預先安裝但預設不執行。要求 Claude 啟動您需要的任何一個；它執行的命令是： ```bash theme={null} service postgresql start ``` ```bash theme={null} service redis-server start ``` Docker 可用於執行容器化服務。要求 Claude 執行 `docker compose up` 以啟動您專案的服務。拉取映像的網路存取遵循您環境的 [存取層級](#access-levels)，[Trusted 預設值](#default-allowed-domains) 包括 Docker Hub 和其他常見登錄。 如果您的映像很大或拉取速度很慢，請將 `docker compose pull` 或 `docker compose build` 新增到您的 [設定指令碼](#setup-scripts)。[環境快取](#environment-caching) 保留拉取的映像，因此每個新工作階段都在磁碟上有它們。快取僅儲存檔案，不儲存執行中的程序，因此 Claude 仍然每個工作階段啟動容器。

新增套件

若要新增未預先安裝的套件，請使用 [設定指令碼](#setup-scripts)。[環境快取](#environment-caching) 保留指令碼安裝的內容，因此您在那裡安裝的套件在每個工作階段開始時都可用，無需每次重新安裝。您也可以要求 Claude 在工作階段中期安裝套件，但這些安裝不會帶到其他工作階段。

資源限制

雲端工作階段執行時具有可能隨時間變化的近似資源上限： * 4 vCPU * 16 GB RAM * 30 GB 磁碟 VM 可能會停止需要明顯更多記憶體的工作，例如大型建置工作或記憶體密集型測試。對於超出這些限制的工作負載，請使用 [Remote Control](/docs/zh-TW/remote-control) 在您自己的硬體上執行 Claude Code。

設定指令碼

設定指令碼是一個 Bash 指令碼，在新的雲端工作階段啟動時執行，在 Claude Code 啟動之前執行。使用設定指令碼來安裝相依性、設定工具，或取得工作階段需要但未預先安裝的任何內容。 指令碼以 root 身份在 Ubuntu 24.04 上執行，因此 `apt install` 和大多數語言套件管理員都能運作。 若要新增設定指令碼，請開啟環境設定對話框，並在 **Setup script** 欄位中輸入您的指令碼。 此範例安裝 GitHub 的 [`gh` CLI](https://cli.github.com)，這不是預先安裝的。 ```bash theme={null} #!/bin/bash apt update && apt install -y gh ```

指令碼需求

設定指令碼有三個限制條件需要考慮： * **Exit zero**：如果指令碼以非零狀態結束，工作階段將無法啟動。在非關鍵命令後附加 `|| true`，以便間歇性安裝失敗不會阻止工作階段。 * **在五分鐘內完成**：將指令碼的總執行時間保持在大約五分鐘以內，以便[環境快取](#environment-caching)可以建立。使用 `&` 和 `wait` 並行執行獨立安裝，並將任何無法納入的單一下載移至[SessionStart hook](#setup-scripts-vs-sessionstart-hooks)，在背景中啟動它。 * **安裝的網路存取**：套件安裝需要連接到登錄檔。預設的 **Trusted** 層級涵蓋[常見套件登錄檔](#default-allowed-domains)，包括 npm、PyPI、RubyGems 和 crates.io；使用 **None** 網路存取時，安裝會失敗。

環境快取

設定指令碼在您第一次在環境中啟動工作階段時執行。完成後，Anthropic 會快照檔案系統，並將該快照重複用作後續工作階段的起點。新工作階段會以您的相依性、工具和 Docker 映像已在磁碟上開始，並跳過設定指令碼步驟。即使指令碼安裝大型工具鏈或拉取容器映像，這也能保持啟動速度快。 快取是檔案系統快照，因此它會保留設定指令碼寫入磁碟的內容，並丟失任何僅在執行中的內容。您安裝的套件、您拉取的 Docker 映像和您寫入的檔案都會保留。指令碼啟動的資料庫、`docker compose up` 堆疊或任何其他背景程序不會；透過詢問 Claude 或使用 [SessionStart hook](#setup-scripts-vs-sessionstart-hooks) 在每個工作階段啟動這些。 當您變更環境的設定指令碼或允許的網路主機時，以及當快取在大約七天後達到過期時，設定指令碼會再次執行以重建快取。恢復現有工作階段永遠不會重新執行設定指令碼。 您不需要自己啟用快取或管理快照。

設定指令碼與 SessionStart hooks

使用設定指令碼來佈建 VM 本身：未[預先安裝](#installed-tools)的工具鏈和 CLI 工具。使用 [SessionStart hook](/docs/zh-TW/hooks#sessionstart) 進行應在各處執行的專案設定，雲端和本機，例如 `npm install`。 當雲端工作階段啟動時，設定指令碼和 SessionStart hooks 按固定順序執行： 1. 設定指令碼首先執行，在 Claude Code 啟動之前，且僅當不存在[快取環境](#environment-caching)時。 2. Claude Code 啟動並執行您的 SessionStart hooks，就像在每個工作階段（本機或雲端）開始時一樣。 | | 設定指令碼 | SessionStart hooks | | ------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **您在哪裡設定它們** | [claude.ai/code](https://claude.ai/code) 的環境對話框 | [設定檔](/docs/zh-TW/settings#settings-files)，例如您的儲存庫的 `.claude/settings.json`；請參閱[您的設定中保留的內容](#what-carries-over-from-your-setup)，了解哪些檔案到達雲端工作階段 | | **它們何時執行** | 在 Claude Code 啟動之前，當存在[快取環境](#environment-caching)時跳過 | 在 Claude Code 啟動後，在每個工作階段（包括已恢復的工作階段）上 | | **它們在哪裡執行** | 僅限雲端工作階段 | 本機和雲端工作階段 | 如果您在使用者層級 `~/.claude/settings.json` 中有 SessionStart hooks，不要期望它們在雲端中：使用者層級設定保留在您的機器上。在雲端工作階段中，Claude Code 執行來自儲存庫和您組織的[伺服器管理設定](/docs/zh-TW/server-managed-settings)的 hooks。

使用 SessionStart hook 安裝相依性

若要僅在雲端工作階段中安裝相依性，請將 SessionStart hook 與檢查其執行位置的指令碼配對。 首先，將 SessionStart hook 新增至您的儲存庫的 `.claude/settings.json`。此設定告訴 Claude Code 在工作階段啟動或恢復時執行儲存庫中的 `scripts/install_pkgs.sh`： ```json theme={null} { "hooks": { "SessionStart": [ { "matcher": "startup|resume", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh" } ] } ] } } ``` `matcher` 將 hook 限制為 `startup` 和 `resume` 事件，`$CLAUDE_PROJECT_DIR` 解析為儲存庫根目錄，因此 hook 無論工作階段的工作目錄如何都能找到指令碼。 接下來，在 `scripts/install_pkgs.sh` 建立指令碼。它在雲端外立即結束，然後安裝您的相依性： ```bash theme={null} #!/bin/bash if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then exit 0 fi npm install pip install -r requirements.txt exit 0 ``` `CLAUDE_CODE_REMOTE` 檢查是將安裝限制在雲端工作階段的原因：工作階段 VM 的環境將該變數設為 `true`，本機上永遠不會是 `true`，因此在您的筆記型電腦上，指令碼在安裝任何內容之前結束。 這兩個檔案一起為每個雲端工作階段在啟動時提供新鮮的 `npm install` 和 `pip install`，同時保持本機工作階段不受影響。

雲端工作階段中的限制

SessionStart hooks 在雲端中的行為與本機相同，但有以下注意事項： * **無雲端專用範圍**：hooks 在本機和雲端工作階段中執行。若要跳過本機執行，請檢查 `CLAUDE_CODE_REMOTE` 環境變數，如上所示。 * **需要網路存取**：安裝命令需要連接到套件登錄檔。如果您的環境使用 **None** 網路存取，這些 hooks 會失敗。**Trusted** 下的[預設允許清單](#default-allowed-domains)涵蓋 npm、PyPI、RubyGems 和 crates.io。 * **Proxy 相容性**：所有出站流量都通過[安全 proxy](#security-proxy)。某些套件管理員無法與此 proxy 正確搭配運作。Bun 是一個已知的範例。 * **增加啟動延遲**：hooks 在每次工作階段啟動或恢復時執行，不同於設定指令碼，設定指令碼受益於[環境快取](#environment-caching)。透過在重新安裝之前檢查相依性是否已存在來保持安裝指令碼快速。 若要為後續 Bash 命令保留環境變數，請寫入 `$CLAUDE_ENV_FILE` 的檔案。請參閱 [SessionStart hooks](/docs/zh-TW/hooks#sessionstart) 以取得詳細資訊。 若要自訂基礎映像，請使用設定指令碼在[提供的映像](#installed-tools)上安裝您需要的內容，或使用 `docker compose` 作為 Claude 旁邊的容器執行您自己的映像。目前不支援完全取代基礎映像。

預設允許的網域

使用 **Trusted** 網路存取，工作階段預設可以到達以下網域。標記為 `*` 的網域表示萬用字元子網域符合，因此 `*.gcr.io` 允許 `gcr.io` 的任何子網域。 * api.anthropic.com * statsig.anthropic.com * docs.claude.com * platform.claude.com * code.claude.com * claude.ai * github.com * [www.github.com](http://www.github.com) * api.github.com * npm.pkg.github.com * raw\.githubusercontent.com * pkg-npm.githubusercontent.com * objects.githubusercontent.com * release-assets.githubusercontent.com * codeload.github.com * avatars.githubusercontent.com * camo.githubusercontent.com * gist.github.com * gitlab.com * [www.gitlab.com](http://www.gitlab.com) * registry.gitlab.com * bitbucket.org * [www.bitbucket.org](http://www.bitbucket.org) * api.bitbucket.org * registry-1.docker.io * auth.docker.io * index.docker.io * hub.docker.com * [www.docker.com](http://www.docker.com) * production.cloudflare.docker.com * download.docker.com * gcr.io * \*.gcr.io * ghcr.io * mcr.microsoft.com * \*.data.mcr.microsoft.com * public.ecr.aws * cloud.google.com * accounts.google.com * gcloud.google.com * \*.googleapis.com * storage.googleapis.com * compute.googleapis.com * container.googleapis.com * azure.com * portal.azure.com * microsoft.com * [www.microsoft.com](http://www.microsoft.com) * \*.microsoftonline.com * packages.microsoft.com * dotnet.microsoft.com * dot.net * visualstudio.com * dev.azure.com * \*.amazonaws.com * \*.api.aws * oracle.com * [www.oracle.com](http://www.oracle.com) * java.com * [www.java.com](http://www.java.com) * java.net * [www.java.net](http://www.java.net) * download.oracle.com * yum.oracle.com * registry.npmjs.org * [www.npmjs.com](http://www.npmjs.com) * [www.npmjs.org](http://www.npmjs.org) * npmjs.com * npmjs.org * yarnpkg.com * registry.yarnpkg.com * pypi.org * [www.pypi.org](http://www.pypi.org) * files.pythonhosted.org * pythonhosted.org * test.pypi.org * pypi.python.org * pypa.io * [www.pypa.io](http://www.pypa.io) * rubygems.org * [www.rubygems.org](http://www.rubygems.org) * api.rubygems.org * index.rubygems.org * ruby-lang.org * [www.ruby-lang.org](http://www.ruby-lang.org) * rubyforge.org * [www.rubyforge.org](http://www.rubyforge.org) * rubyonrails.org * [www.rubyonrails.org](http://www.rubyonrails.org) * rvm.io * get.rvm.io * crates.io * [www.crates.io](http://www.crates.io) * index.crates.io * static.crates.io * rustup.rs * static.rust-lang.org * [www.rust-lang.org](http://www.rust-lang.org) * proxy.golang.org * sum.golang.org * index.golang.org * golang.org * [www.golang.org](http://www.golang.org) * goproxy.io * pkg.go.dev * maven.org * repo.maven.org * central.maven.org * repo1.maven.org * repo.maven.apache.org * jcenter.bintray.com * gradle.org * [www.gradle.org](http://www.gradle.org) * services.gradle.org * plugins.gradle.org * kotlinlang.org * [www.kotlinlang.org](http://www.kotlinlang.org) * spring.io * repo.spring.io * packagist.org (PHP Composer) * [www.packagist.org](http://www.packagist.org) * repo.packagist.org * nuget.org (.NET NuGet) * [www.nuget.org](http://www.nuget.org) * api.nuget.org * pub.dev (Dart/Flutter) * api.pub.dev * hex.pm (Elixir/Erlang) * [www.hex.pm](http://www.hex.pm) * cpan.org (Perl CPAN) * [www.cpan.org](http://www.cpan.org) * metacpan.org * [www.metacpan.org](http://www.metacpan.org) * api.metacpan.org * cocoapods.org (iOS/macOS) * [www.cocoapods.org](http://www.cocoapods.org) * cdn.cocoapods.org * haskell.org * [www.haskell.org](http://www.haskell.org) * hackage.haskell.org * swift.org * [www.swift.org](http://www.swift.org) * archive.ubuntu.com * security.ubuntu.com * ubuntu.com * [www.ubuntu.com](http://www.ubuntu.com) * \*.ubuntu.com * ppa.launchpad.net * launchpad.net * [www.launchpad.net](http://www.launchpad.net) * \*.nixos.org * dl.k8s.io (Kubernetes) * pkgs.k8s.io * k8s.io * [www.k8s.io](http://www.k8s.io) * releases.hashicorp.com (HashiCorp) * apt.releases.hashicorp.com * rpm.releases.hashicorp.com * archive.releases.hashicorp.com * hashicorp.com * [www.hashicorp.com](http://www.hashicorp.com) * repo.anaconda.com (Anaconda/Conda) * conda.anaconda.org * anaconda.org * [www.anaconda.com](http://www.anaconda.com) * anaconda.com * continuum.io * apache.org (Apache) * [www.apache.org](http://www.apache.org) * archive.apache.org * downloads.apache.org * eclipse.org (Eclipse) * [www.eclipse.org](http://www.eclipse.org) * download.eclipse.org * nodejs.org (Node.js) * [www.nodejs.org](http://www.nodejs.org) * developer.apple.com * developer.android.com * pkg.stainless.com * binaries.prisma.sh * statsig.com * [www.statsig.com](http://www.statsig.com) * api.statsig.com * sentry.io * \*.sentry.io * downloads.sentry-cdn.com * http-intake.logs.datadoghq.com * browser-intake-us5-datadoghq.com * \*.datadoghq.com * \*.datadoghq.eu * api.honeycomb.io * sourceforge.net * \*.sourceforge.net * packagecloud.io * \*.packagecloud.io * fonts.googleapis.com * fonts.gstatic.com * json-schema.org * [www.json-schema.org](http://www.json-schema.org) * json.schemastore.org * [www.schemastore.org](http://www.schemastore.org) * \*.modelcontextprotocol.io * [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)：啟動、管理和共用雲端工作階段 * [Web quickstart](/docs/zh-TW/web-quickstart)：連接 GitHub 並啟動您的第一個雲端工作階段 * [Claude Tag](https://claude.com/docs/claude-tag/overview)：Claude 從 Slack 啟動的工作階段在相同的環境中執行 * [Routines](/docs/zh-TW/routines)：排程執行使用相同的環境和網路存取層級 * [Remote Control](/docs/zh-TW/remote-control)：改為在您自己的機器的網路和檔案上執行工作階段 * [SessionStart hooks](/docs/zh-TW/hooks#sessionstart)：儲存庫提交的設定，在本機和雲端工作階段中執行 * [Server-managed settings](/docs/zh-TW/server-managed-settings)：到達雲端工作階段的組織政策