--- title: 雲端環境設定 url: https://platform.claude.com/docs/zh-TW/managed-agents/environments description: 為您的工作階段自訂雲端沙箱。 featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 環境（environment）定義了您的代理程式執行所在的沙箱（sandbox）設定。您只需建立一次環境，之後每次啟動工作階段（session）時參照其 ID 即可。多個工作階段可以共用同一個環境，但每個工作階段都會取得各自獨立的沙箱（一個全新的 Linux 容器）。 本頁介紹 `type: cloud` 環境。若要在您自己的基礎架構上執行沙箱，請參閱[自行託管的沙箱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes)。若要在兩者之間做選擇，請參閱[選擇代理環境](https://platform.claude.com/docs/zh-TW/managed-agents/choosing-an-environment)。 ## 建立環境 ```bash cURL curl -fsS https://api.anthropic.com/v1/environments \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ --data '{ "name": "python-dev", "config": { "type": "cloud", "networking": {"type": "limited", "allow_package_managers": true} } }' ``` ```bash CLI ant apply environment.yaml ``` ```yaml # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json name: python-dev config: type: cloud networking: type: limited allow_package_managers: true ``` [`ant apply`](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/apply) 會從 `environment.yaml` 建立環境、印出其 ID，並將其記錄在 `claude-lock.json` 中。請提交 `claude-lock.json`，這樣下一次執行 `ant apply` 時就會更新此環境，而不是嘗試再次建立它。 ```python Python environment = client.beta.environments.create( name="python-dev", config={ "type": "cloud", "networking": {"type": "limited", "allow_package_managers": True}, }, ) print(f"Environment ID: {environment.id}") ``` ```typescript TypeScript const environment = await client.beta.environments.create({ name: "python-dev", config: { type: "cloud", networking: { type: "limited", allow_package_managers: true } } }); console.log(`Environment ID: ${environment.id}`); ``` ```csharp C# var environment = await client.Beta.Environments.Create(new() { Name = "python-dev", Config = new BetaCloudConfigParams { Networking = new BetaLimitedNetworkParams { AllowPackageManagers = true, }, }, }); Console.WriteLine($"Environment ID: {environment.ID}"); ``` ```go Go environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{ Name: "python-dev", Config: anthropic.BetaEnvironmentNewParamsConfigUnion{ OfCloud: &anthropic.BetaCloudConfigParams{ Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{ OfLimited: &anthropic.BetaLimitedNetworkParams{ AllowPackageManagers: anthropic.Bool(true), }, }, }, }, }) if err != nil { panic(err) } fmt.Printf("Environment ID: %s\n", environment.ID) ``` ```java Java var environment = client.beta().environments().create(EnvironmentCreateParams.builder() .name("python-dev") .config(BetaCloudConfigParams.builder() .networking(BetaLimitedNetworkParams.builder() .allowPackageManagers(true) .build()) .build()) .build()); IO.println("Environment ID: " + environment.id()); ``` ```php PHP $environment = $client->beta->environments->create( name: 'python-dev', config: [ 'type' => 'cloud', 'networking' => ['type' => 'limited', 'allow_package_managers' => true], ], ); echo "Environment ID: {$environment->id}\n"; ``` ```ruby Ruby environment = client.beta.environments.create( name: "python-dev", config: { type: "cloud", networking: {type: "limited", allow_package_managers: true} } ) puts "Environment ID: #{environment.id}" ``` 請使用唯一且具描述性的 `name` (csharp, go: `Name`)，以便區分各個環境。此範例使用允許套件管理器的 `limited` [網路](https://platform.claude.com/docs/zh-TW/managed-agents/environments#networking)設定，因此沙箱可以連線到套件登錄庫和程式碼託管服務。若要讓它連線到其他主機，請將這些主機加入 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)。 ## 在工作階段中使用環境 在[建立工作階段](https://platform.claude.com/docs/zh-TW/managed-agents/sessions)時，以字串形式傳入環境 ID。 ```bash cURL curl -fsS https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ --data '{ "agent": "'"$AGENT_ID"'", "environment_id": "'"$ENVIRONMENT_ID"'" }' ``` ```bash CLI ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENVIRONMENT_ID" ``` ```python Python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: agent.id, environment_id: environment.id }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = agent.ID, EnvironmentID = environment.ID, }); ``` ```go Go session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{ OfString: anthropic.String(agent.ID), }, EnvironmentID: environment.ID, }) if err != nil { panic(err) } ``` ```java Java var session = client.beta().sessions().create(SessionCreateParams.builder() .agent(agent.id()) .environmentId(environment.id()) .build()); ``` ```php PHP $session = $client->beta->sessions->create( agent: $agent->id, environmentID: $environment->id, ); ``` ```ruby Ruby session = client.beta.sessions.create( agent: agent.id, environment_id: environment.id ) ``` ## 設定選項 ### 套件 `packages` (csharp, go: `Packages`) 欄位會在代理程式啟動前將套件預先安裝到沙箱中。套件由各自的套件管理器安裝，並在共用同一環境的工作階段之間快取。當指定多個套件管理器時，它們會依字母順序執行（apt、cargo、gem、go、npm、pip）。您可以選擇性地固定特定版本。未固定版本的套件會安裝最新版本。如果環境使用 `limited` [網路](https://platform.claude.com/docs/zh-TW/managed-agents/environments#networking)設定，也請將 `networking` (csharp, go: `Networking`) 中的 `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) 設為 `true`；否則請求會以 400 錯誤遭到拒絕。 ```bash cURL curl -fsS https://api.anthropic.com/v1/environments \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ --data '{ "name": "data-analysis", "config": { "type": "cloud", "packages": { "pip": ["pandas", "numpy", "scikit-learn"], "npm": ["express"] }, "networking": {"type": "limited", "allow_package_managers": true} } }' ``` ```bash CLI ant apply environment.yaml ``` ```yaml # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json name: data-analysis config: type: cloud packages: pip: - pandas - numpy - scikit-learn npm: - express networking: type: limited allow_package_managers: true ``` ```python Python environment = client.beta.environments.create( name="data-analysis", config={ "type": "cloud", "packages": { "pip": ["pandas", "numpy", "scikit-learn"], "npm": ["express"], }, "networking": {"type": "limited", "allow_package_managers": True}, }, ) ``` ```typescript TypeScript const environment = await client.beta.environments.create({ name: "data-analysis", config: { type: "cloud", packages: { pip: ["pandas", "numpy", "scikit-learn"], npm: ["express"] }, networking: { type: "limited", allow_package_managers: true } } }); ``` ```csharp C# using Anthropic.Models.Beta.Environments; var environment = await client.Beta.Environments.Create(new() { Name = "data-analysis", Config = new BetaCloudConfigParams { Packages = new() { Pip = ["pandas", "numpy", "scikit-learn"], Npm = ["express"], }, Networking = new BetaLimitedNetworkParams { AllowPackageManagers = true, }, }, }); ``` ```go Go environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{ Name: "data-analysis", Config: anthropic.BetaEnvironmentNewParamsConfigUnion{ OfCloud: &anthropic.BetaCloudConfigParams{ Packages: anthropic.BetaPackagesParams{ Pip: []string{"pandas", "numpy", "scikit-learn"}, Npm: []string{"express"}, }, Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{ OfLimited: &anthropic.BetaLimitedNetworkParams{ AllowPackageManagers: anthropic.Bool(true), }, }, }, }, }) if err != nil { panic(err) } _ = environment ``` ```java Java import com.anthropic.models.beta.environments.*; import java.util.List; var environment = client.beta().environments().create(EnvironmentCreateParams.builder() .name("data-analysis") .config(BetaCloudConfigParams.builder() .packages(BetaPackagesParams.builder() .pip(List.of("pandas", "numpy", "scikit-learn")) .npm(List.of("express")) .build()) .networking(BetaLimitedNetworkParams.builder() .allowPackageManagers(true) .build()) .build()) .build()); ``` ```php PHP $environment = $client->beta->environments->create( name: 'data-analysis', config: [ 'type' => 'cloud', 'packages' => [ 'pip' => ['pandas', 'numpy', 'scikit-learn'], 'npm' => ['express'], ], 'networking' => ['type' => 'limited', 'allow_package_managers' => true], ], ); ``` ```ruby Ruby environment = client.beta.environments.create( name: "data-analysis", config: { type: "cloud", packages: { pip: %w[pandas numpy scikit-learn], npm: %w[express] }, networking: {type: "limited", allow_package_managers: true} } ) ``` 支援的套件管理工具： | 欄位 | 套件管理工具 | 範例 | | ------- | ------------- | ------------------------------------------- | | `apt` | 系統套件（apt-get） | `"graphviz"` | | `cargo` | Rust（cargo） | `"hyperfine@1.18.0"` | | `gem` | Ruby（gem） | `"rails:7.1.0"` | | `go` | Go 模組 | `"golang.org/x/tools/cmd/goimports@latest"` | | `npm` | Node.js（npm） | `"express@4.18.0"` | | `pip` | Python（pip） | `"sqlalchemy==2.0.30"` | ### 網路 `networking` (csharp, go: `Networking`) 欄位控制沙箱的對外網路存取。 使用 `limited` 網路設定時，`allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 也適用於在 Anthropic 伺服器上執行的 `web_search` 和 `web_fetch` 工具。對 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 不相符之主機上的 URL 發出的 `web_fetch` 呼叫，會向代理程式傳回錯誤結果。`web_search` 會省略來自 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 不相符之主機的結果。`allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) 和 `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) 不會為這些工具新增任何主機。當 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 未列出任何主機時，任何 `web_fetch` 或 `web_search` 呼叫都不會傳回網頁或搜尋結果。您為這些工具加入 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 的主機，也會對沙箱開放。`unrestricted` 網路設定和自行託管的環境不會限制這些工具。若要進一步限制它們，請在代理程式工具集中該工具的項目上設定 `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) 或 `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`)。請參閱[限制網頁搜尋與網頁擷取的網域](https://platform.claude.com/docs/zh-TW/managed-agents/tools-web-restrictions)。 | 模式 | 說明 | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `limited` | 將沙箱的網路存取限制在 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 中的主機。將 `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) 和 `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) 設為 `true` 以允許額外的存取。除非代理程式必須連線到您無法事先列出的網站，否則請使用此模式。 | | `unrestricted` | 完整的對外網路存取，但一般安全封鎖清單中的主機除外。使用前，請閱讀[不受限網路的風險](https://platform.claude.com/docs/zh-TW/managed-agents/environments#risks-of-unrestricted-networking)。 | 請在 API 請求中明確設定 `networking` (csharp, go: `Networking`)；省略此欄位的建立請求會取得 `unrestricted`。Claude Console 中用於建立環境的表單預設選取 **Limited**，且不允許其他任何存取。 以下範例建立一個使用 `limited` 網路的環境： ```bash cURL curl -fsS https://api.anthropic.com/v1/environments \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "name": "api-access", "config": { "type": "cloud", "networking": { "type": "limited", "allowed_hosts": ["api.example.com"], "allow_mcp_servers": true, "allow_package_managers": true } } }' ``` ```bash CLI ant apply environment.yaml ``` ```yaml # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json name: api-access config: type: cloud networking: type: limited allowed_hosts: - api.example.com allow_mcp_servers: true allow_package_managers: true ``` ```python Python environment = client.beta.environments.create( name="api-access", config={ "type": "cloud", "networking": { "type": "limited", "allowed_hosts": ["api.example.com"], "allow_mcp_servers": True, "allow_package_managers": True, }, }, ) ``` ```typescript TypeScript const environment = await client.beta.environments.create({ name: "api-access", config: { type: "cloud", networking: { type: "limited", allowed_hosts: ["api.example.com"], allow_mcp_servers: true, allow_package_managers: true } } }); ``` ```csharp C# using Anthropic.Models.Beta.Environments; var environment = await client.Beta.Environments.Create(new() { Name = "api-access", Config = new BetaCloudConfigParams { Networking = new BetaLimitedNetworkParams { AllowedHosts = ["api.example.com"], AllowMcpServers = true, AllowPackageManagers = true, }, }, }); ``` ```go Go environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{ Name: "api-access", Config: anthropic.BetaEnvironmentNewParamsConfigUnion{ OfCloud: &anthropic.BetaCloudConfigParams{ Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{ OfLimited: &anthropic.BetaLimitedNetworkParams{ AllowedHosts: []string{"api.example.com"}, AllowMCPServers: anthropic.Bool(true), AllowPackageManagers: anthropic.Bool(true), }, }, }, }, }) if err != nil { panic(err) } _ = environment ``` ```java Java import com.anthropic.models.beta.environments.*; import java.util.List; var environment = client.beta().environments().create(EnvironmentCreateParams.builder() .name("api-access") .config(BetaCloudConfigParams.builder() .networking(BetaLimitedNetworkParams.builder() .allowedHosts(List.of("api.example.com")) .allowMcpServers(true) .allowPackageManagers(true) .build()) .build()) .build()); ``` ```php PHP $environment = $client->beta->environments->create( name: 'api-access', config: [ 'type' => 'cloud', 'networking' => [ 'type' => 'limited', 'allowed_hosts' => ['api.example.com'], 'allow_mcp_servers' => true, 'allow_package_managers' => true, ], ], ); ``` ```ruby Ruby environment = client.beta.environments.create( name: "api-access", config: { type: "cloud", networking: { type: "limited", allowed_hosts: %w[api.example.com], allow_mcp_servers: true, allow_package_managers: true } } ) ``` 請搭配明確的 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 清單使用 `limited` 網路設定。遵循「principle of least privilege」（最小權限原則），只授予代理程式所需的最低網路存取權限，並定期稽核您允許的網域。 使用 `limited` 網路且未設定其他欄位時，不允許任何主機。您附加到工作階段的檔案、記憶體儲存區和 GitHub 儲存庫仍可使用。當沙箱在連接埠 80 或 443 上發出的請求因其主機不被允許而遭拒時，回應會是一個指出被封鎖主機的 403。 使用 `limited` 網路時： * `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 指定沙箱可以連線的網域。請指定純主機名稱或萬用字元模式（例如 `*.example.com`）。請勿包含 URL 協定、連接埠或路徑。純主機名稱只會比對完全相同的主機：`example.com` 不會比對 `www.example.com`。`*.example.com` 會比對 `example.com` 的所有子網域，但不包括 `example.com` 本身。 * `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) 允許對代理程式上所設定之 MCP 伺服器端點的對外存取，範圍超出 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 陣列中列出的主機。預設為 `false`。當其為 `false` 時，如果代理程式宣告了主機不在 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 中的 MCP 伺服器，工作階段建立會以 400 錯誤失敗。這同樣適用於[它可以委派的代理程式](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration)。若要修正，請將該主機加入 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)，或將 `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) 設為 `true`。 * `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) 允許對一組公開套件登錄庫和程式碼託管服務的對外存取，範圍超出 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 陣列中列出的主機。清單請參閱[套件管理器主機](https://platform.claude.com/docs/zh-TW/managed-agents/environments#package-manager-hosts)。預設為 `false`。只要環境指定了 `packages` (csharp, go: `Packages`)，就請將其設為 `true`；否則即使登錄庫主機已列在 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 中，請求仍會以 400 錯誤遭到拒絕。 #### 套件管理器主機 當 `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) 為 `true` 時，除了 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 中的主機外，沙箱還可以連線到以下主機。此清單由 Anthropic 維護，並可能變更。 | 生態系 | 主機 | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 程式碼託管 | `github.com`、`api.github.com`、`codeload.github.com`、`raw.githubusercontent.com`、`objects.githubusercontent.com`、`release-assets.githubusercontent.com`、`gitlab.com`、`bitbucket.org` | | Node.js | `registry.npmjs.org`、`registry.yarnpkg.com`、`nodejs.org` | | Python | `pypi.org`、`files.pythonhosted.org` | | Rust | `crates.io`、`index.crates.io`、`static.crates.io`、`static.rust-lang.org` | | Go | `proxy.golang.org`、`sum.golang.org` | | Java | `repo1.maven.org`、`repo.maven.apache.org`、`services.gradle.org`、`plugins.gradle.org`、`plugins-artifacts.gradle.org` | | Ruby | `rubygems.org`、`index.rubygems.org` | | PHP | `packagist.org`、`repo.packagist.org` | | Ubuntu（apt） | `archive.ubuntu.com`、`security.ubuntu.com`、`ppa.launchpad.net` | | 容器 | `registry-1.docker.io`、`auth.docker.io`、`production.cloudflare.docker.com`、`download.docker.com`、`ghcr.io` | 網路存取是以主機為單位授予，而非以操作為單位。沙箱可以使用命令所提供的任何憑證，向允許的主機發送任何請求，包括 `git push` 和套件發布等上傳操作。如果代理程式處理不受信任的輸入（儲存庫檔案、擷取的網頁內容或第三方工具輸出），成功的「prompt injection」（提示注入）可能會利用允許的主機將檔案複製到沙箱外。為降低此風險，請將 `bash` 工具的[權限政策](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies)設為 `always_ask` 或 `auto`。如果環境未指定 `packages` (csharp, go: `Packages`)，您也可以改為將 `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) 保持為 `false`，並在 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 中只列出代理程式所需的主機。 #### 不受限網路的風險 使用 `unrestricted` 網路時，沙箱中的程式碼可以向網際網路上的任何主機傳送請求，但一般安全封鎖清單中的主機除外。在選擇此模式之前，請考慮代理程式可以利用這種存取權做些什麼： * **代理程式可以變更外部網站上的內容，而不只是讀取：** `bash` 工具可以傳送任何請求。代理程式可以張貼資料、提交表單、呼叫 API，以及執行會變更外部網站資料的指令碼。即使只是擷取 URL 的請求，在某些網站上也可能變更資料。 * **預設情況下，沒有任何機制會暫停這些請求：** 代理程式工具集的預設[權限政策](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies)是 `always_allow`，因此 `bash` 命令會在未經核准的情況下執行。 * **沙箱中的任何內容都可能離開沙箱：** 這包括檔案、工具輸出，以及您放入沙箱的任何憑證或機密。 * **擷取的內容可能操控代理程式：** 代理程式讀取的網頁、API 回應和其他內容可能包含指示（提示注入），從而改變它接下來的行為。 * **代理程式代表您行事：** 它的行為可能違反網站的服務條款，或在網站上建立帳戶和記錄。 * **模型行為並非安全控制措施：** 代理程式可能以您未要求的方式在外部網站上採取行動，包括在網站封鎖請求後以不同方式重試。請使用網路設定和權限政策來限制它能做的事。 * **安全封鎖清單並非允許清單：** 它不會限制代理程式可以連線到哪些其他網站，也不會限制代理程式在這些網站上做什麼。 為降低這些風險，請搭配明確的主機清單使用 `limited` 網路。以下 `networking` 值允許 `api.example.com`，並為會安裝套件的代理程式加上[套件管理器主機](https://platform.claude.com/docs/zh-TW/managed-agents/environments#package-manager-hosts)： ```json { "type": "limited", "allowed_hosts": ["api.example.com"], "allow_package_managers": true } ``` 如果您能列出代理程式所需的網站，那麼只使用 `web_search` 和 `web_fetch` 工具的代理程式就不需要 `unrestricted` 網路設定。使用 `limited` 網路設定時，`allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 也適用於這些工具（請參閱[網路](https://platform.claude.com/docs/zh-TW/managed-agents/environments#networking)），因此請在 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 中列出這些網站。同時將它們列在 `web_search` 的 `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) 中，可讓它搜尋這些網站。您加入 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 的主機也會對沙箱開放。若要進一步限制這些工具，請參閱[限制網頁搜尋與網頁擷取的網域](https://platform.claude.com/docs/zh-TW/managed-agents/tools-web-restrictions)。 只有在代理程式必須連線到您無法事先列出的網站時，才使用 `unrestricted`。在這種情況下，請勿將機密和敏感檔案放入沙箱，並只給予代理程式該任務所需的憑證。請考慮將 `bash` 工具的權限政策設為 `always_ask` 或 `auto`，並[監看工作階段的事件](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming)。 ## 環境生命週期 * 環境會持續存在，直到被明確封存或刪除為止。 * 每個工作階段都會取得各自的沙箱實例，即使多個工作階段參照同一個環境亦然。工作階段之間不共用檔案系統狀態。 * 環境沒有版本控管。如果您經常更新環境，請自行記錄變更，以便辨別每個工作階段使用的是哪一個設定。 ## 管理環境 ```bash cURL # 列出環境 curl -fsS https://api.anthropic.com/v1/environments \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" # 擷取特定環境 curl -fsS "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" # 封存環境（唯讀，現有工作階段繼續運作） curl -fsS -X POST "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" # 刪除環境（僅限沒有工作階段參照時） curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" ``` ```bash CLI # 列出 environments ant beta:environments list # 擷取特定 environment ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID" # 封存 environment（唯讀，既有 session 會繼續執行） ant beta:environments archive --environment-id "$ENVIRONMENT_ID" # 刪除 environment（僅限沒有 session 參照它時） ant beta:environments delete --environment-id "$ENVIRONMENT_ID" ``` ```python Python # 列出環境 environments = client.beta.environments.list() # 擷取特定環境 env = client.beta.environments.retrieve(environment.id) # 封存環境（唯讀，現有工作階段繼續運作） client.beta.environments.archive(environment.id) # 刪除環境（僅當沒有工作階段參照它時） client.beta.environments.delete(environment.id) ``` ```typescript TypeScript // 列出環境 const environments = await client.beta.environments.list(); // 擷取特定環境 const env = await client.beta.environments.retrieve(environment.id); // 封存環境（唯讀，現有工作階段繼續運作） await client.beta.environments.archive(environment.id); // 刪除環境（僅當沒有工作階段參照它時） await client.beta.environments.delete(environment.id); ``` ```csharp C# // 列出環境 var environments = await client.Beta.Environments.List(); // 擷取特定環境 var env = await client.Beta.Environments.Retrieve(environment.ID); // 封存環境（唯讀，現有工作階段繼續運作） await client.Beta.Environments.Archive(environment.ID); // 刪除環境（僅當沒有工作階段參照它時） await client.Beta.Environments.Delete(environment.ID); ``` ```go Go // 列出環境 environments, err := client.Beta.Environments.List(ctx, anthropic.BetaEnvironmentListParams{}) // ... // 擷取特定環境 env, err := client.Beta.Environments.Get(ctx, environment.ID, anthropic.BetaEnvironmentGetParams{}) // ... // 封存環境（唯讀，現有工作階段繼續運作） _, err = client.Beta.Environments.Archive(ctx, environment.ID, anthropic.BetaEnvironmentArchiveParams{}) // ... // 刪除環境（僅當沒有工作階段參照它時） _, err = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{}) ``` ```java Java // 列出環境 var environments = client.beta().environments().list(); // 擷取特定環境 var env = client.beta().environments().retrieve(environment.id()); // 封存環境（唯讀，現有 session 繼續運作） client.beta().environments().archive(environment.id()); // 刪除環境（僅當沒有 session 參照它時） client.beta().environments().delete(environment.id()); ``` ```php PHP // 列出環境 $environments = $client->beta->environments->list(); // 擷取特定環境 $env = $client->beta->environments->retrieve($environment->id); // 封存環境（唯讀，現有工作階段繼續運作） $client->beta->environments->archive($environment->id); // 刪除環境（僅當沒有工作階段參照它時） $client->beta->environments->delete($environment->id); ``` ```ruby Ruby # 列出環境 environments = client.beta.environments.list # 擷取特定環境 env = client.beta.environments.retrieve(environment.id) # 封存環境（唯讀，現有工作階段繼續運作） client.beta.environments.archive(environment.id) # 刪除環境（僅當沒有工作階段參照它時） client.beta.environments.delete(environment.id) ``` ## 預先安裝的執行環境 雲端沙箱內建常見的程式語言執行環境、資料庫與命令列工具。完整清單請參閱[雲端沙箱參考](https://platform.claude.com/docs/zh-TW/managed-agents/cloud-sandboxes-reference)。 ## 後續步驟 雲端沙箱中可用的預先安裝套件、資料庫與公用程式。 建立工作階段以執行您的代理程式並開始執行任務。