--- title: 自行託管 worker 參考 url: https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-reference description: 自行託管沙箱 worker 的參考資料：ant CLI 旗標、環境變數、主機需求、檔案系統路徑，以及 SDK 輔助工具選項。 featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 本頁說明為 `self_hosted` 環境提供服務的預建 worker。如需以任務為導向的指南，請從[自行託管沙箱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes)和[部署自行託管的 worker](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-workers) 開始。 ## CLI 命令與旗標 | 命令 | 說明 | | ---------------------- | ---------------------------------------------------------------- | | `ant beta:worker poll` | 從環境的佇列中認領工作項目，並在程序內執行每個工作階段。使用 `--on-work` 時，則改為針對每個工作項目呼叫您的指令碼。 | | `ant beta:worker run` | 處理一個已認領的工作階段後結束。請將其用作每個工作階段沙箱的進入點。 | | 旗標 | 說明 | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `--environment-id` | 要輪詢工作的環境。也會從 `ANTHROPIC_ENVIRONMENT_ID` 讀取。 | | `--environment-key` | 向此環境驗證 worker 的身分。也會從 `ANTHROPIC_ENVIRONMENT_KEY` 讀取。 | | `--workdir` | 下載技能以及工具讀寫檔案的目錄。預設為 `.`（目前目錄）。 | | `--on-work` | 針對每個已認領的工作項目呼叫的指令碼，取代在程序內執行工具。它會以環境變數接收工作階段詳細資訊，並從標準輸入以 JSON 接收工作項目。 | | `--max-idle` | 工作階段以 `end_turn` [停止原因](https://platform.claude.com/docs/zh-TW/build-with-claude/handling-stop-reasons)進入閒置後，在關閉前等待的時間。預設為 `60s`。 | | `--log-format` | 日誌輸出格式。使用 `json` 以進行結構化日誌擷取。預設為 `text`。 | ## 環境變數 | 變數 | 說明 | 設定者 | | ------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `ANTHROPIC_ENVIRONMENT_ID` | worker 所服務之佇列所屬的環境。 | 您，在 worker 主機上設定。輪詢器會將其傳遞給 `--on-work` 指令碼。 | | `ANTHROPIC_ENVIRONMENT_KEY` | 向佇列驗證 worker 的身分。 | 您，在 worker 主機上設定。輪詢器會將其傳遞給 `--on-work` 指令碼。 | | `ANTHROPIC_SESSION_ID` | 已認領工作項目所代表的工作階段。 | 輪詢器，供 `--on-work` 指令碼使用。 | | `ANTHROPIC_WORK_ID` | 已認領的工作項目。 | 輪詢器，供 `--on-work` 指令碼使用。 | | `ANTHROPIC_WORK_SECRET` | 工作項目的每工作階段密鑰。 | 您。輪詢器不會設定它。請參閱[轉送工作項目的密鑰](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret)。 | | `ANTHROPIC_BASE_URL` | 覆寫預設的 API 端點。選用。 | 您，在 worker 主機上設定。 | | `ANTHROPIC_WEBHOOK_SIGNING_KEY` | 驗證傳入的 webhook 酬載。 | 您，在 webhook 處理常式主機上設定。 | ## 主機需求 | Worker | 需求 | | --------------- | --------------------------------------------------------------------- | | 所有 worker | 一台 Linux 主機，且 `/bin/bash` 位於該確切路徑。worker 的 bash 工具會直接呼叫它，而不參考 `PATH`。 | | TypeScript SDK | `PATH` 上需有 `unzip` 和 `tar`，以及 Node.js 22 或更新版本。 | | Python 和 Go SDK | 不需要額外的二進位檔。這些 SDK 使用其標準函式庫進行封存檔解壓縮。 | [記憶體儲存區](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory#requirements)有其自身的額外需求。 ## 沙箱檔案系統 | 路徑 | 內容 | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/workspace` | 工具執行和技能下載的系統預設工作目錄。如果您使用不同的工作目錄，請更新代理的系統提示，讓 Claude 能找到技能檔案。 | | `/skills//` | 代理已下載的技能。 | | `/mnt/memory//` | 每個附加的記憶體儲存區各一個目錄，位於該儲存區的 `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`)（例如 `/mnt/memory/user-preferences/`）。worker 會在認領工作階段時建立這些目錄，並在工作階段結束時移除它們。 | 在自行託管環境中，工作階段的系統提示會省略 Anthropic 管理的沙箱所使用的 `/mnt/session/outputs` 指示。最終交付成果會位於代理在您沙箱檔案系統中寫入的任何位置，通常在工作目錄之下。 技能可以包含代理可直接執行的可執行檔。CLI 和 SDK worker 在解壓縮技能套件時，會保留其中記錄的可執行權限。如果您手動實作技能下載，則需自行負責設定可執行權限。 ## SDK 輔助工具 Python、TypeScript 和 Go SDK 提供三種不同控制層級的輔助工具： | 輔助工具 | 功能 | 使用時機 | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------------- | | [`EnvironmentWorker`](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-reference#environment-worker) | 端對端處理輪詢、設定和執行。 | 大多數情況。 | | [`work.poller()` (go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-reference#work-poller) | 輪詢工作佇列，並將每個已認領的工作階段交給您。 | 您要決定每個工作階段的處理方式，例如啟動沙箱而非在程序內執行工具。 | | [`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-reference#session-tool-runner) | 根據工作階段 ID 和工具清單，為單一工作階段執行工具呼叫。 | 您已認領工作，只需要執行層。 | ### EnvironmentWorker | 方法 | 說明 | | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `run()` (go: `Run()`) | 無限期執行，在工作階段到達時接手處理。 | | `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | 處理單一已認領的工作項目後返回。請明確傳入工作、工作階段和環境識別碼以及 `work_secret` (typescript: `workSecret`; go: `WorkSecret`)，或讓它讀取 [`ANTHROPIC_*` 變數](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-reference#environment-variables)。 | | 選項 | 說明 | | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `tools` (go: `ToolsFunc`) | 一個工廠函式，接收工作階段的 `AgentToolContext` 並傳回工具清單。預設為標準代理工具集。 | | `memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) | 工作階段執行期間，附加的記憶體儲存區與伺服器同步的頻率。請參閱[同步間隔](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory#sync-interval)。 | | `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) | 代理在本機刪除的檔案是否也從儲存區中刪除。請參閱[刪除](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory#deletions)。 | `EnvironmentWorker` 會自動管理 `AgentToolContext` 和工具集。傳入 `tools` (go: `ToolsFunc`) 工廠函式即可自訂工具清單： ```python Python EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool]) ``` ```typescript TypeScript new EnvironmentWorker({ client, environmentId, environmentKey, tools: (ctx) => [betaBashTool(ctx), myCustomTool] }); ``` C# SDK 沒有 `EnvironmentWorker`。若要從您自己的程式碼回應自訂工具呼叫，請在工作階段的事件串流上傳送每個結果，如[傳回自訂工具結果](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#return-a-custom-tool-result)所示。 ```go Go worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool { return []anthropic.BetaTool{agenttoolset.BetaBashTool(env), myCustomTool} }, }) ``` Java SDK 沒有 `EnvironmentWorker`。若要從您自己的程式碼回應自訂工具呼叫，請在工作階段的事件串流上傳送每個結果，如[傳回自訂工具結果](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#return-a-custom-tool-result)所示。 PHP SDK 沒有 `EnvironmentWorker`。若要從您自己的程式碼回應自訂工具呼叫，請在工作階段的事件串流上傳送每個結果，如[傳回自訂工具結果](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#return-a-custom-tool-result)所示。 Ruby SDK 沒有 `EnvironmentWorker`。若要從您自己的程式碼回應自訂工具呼叫，請在工作階段的事件串流上傳送每個結果，如[傳回自訂工具結果](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#return-a-custom-tool-result)所示。 ### 工作輪詢器 | 選項 | 說明 | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `drain` (go: `Drain`) | 佇列清空後是否停止輪詢，而非等待新工作。 | | `block_ms` (typescript: `blockMs`; go: `BlockMs`) | 每次輪詢在返回前等待工作到達的時間，以毫秒為單位。必須介於 1 到 999 之間；輔助工具會自動重新輪詢。傳入 `null` (python: `None`; go: `param.Null[int64]()`) 以進行非阻塞檢查。預設為 999 毫秒的長輪詢。 | | `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | 重新認領已被認領但在此毫秒數內從未確認的工作項目。 | | `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | 在您的迴圈主體處理完每個工作項目後，是否為其發送停止訊號。當執行工作項目的程式會自行發送停止訊號時，請將其設為 `false` (python: `False`; go: `param.NewOpt(false)`)。`handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) 會這麼做，由您啟動且負責停止呼叫的沙箱也是如此。 | 如需完整範例，請參閱[從 SDK 輪詢器啟動沙箱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-workers#launch-sandboxes-from-the-sdk-poller)。 ### 工作階段工具執行器 `client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`) 以 `tools` (go: `Tools`) 接收工具清單。若要建立該清單，請自行設定 `AgentToolContext` 並呼叫 `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`)： ```python Python from anthropic.lib.tools.agent_toolset import ( AgentToolContext, beta_agent_toolset_20260401, ) async with AgentToolContext( workdir="/workspace", client=client, session_id=work.data.id ) as env: # skills 已下載至 /workspace/skills// tools = beta_agent_toolset_20260401(env) ``` ```typescript TypeScript import { setupSkills, betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node"; const ctx = { workdir: "/workspace", client, sessionId: work.data.id }; await setupSkills(ctx); const tools = betaAgentToolset20260401(ctx); ``` C# SDK 沒有 `AgentToolContext`。 ```go Go env := &agenttoolset.AgentToolContext{Workdir: "/workspace"} if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil { panic(err) } // skills 已下載至 /workspace/skills// tools := agenttoolset.BetaAgentToolset20260401(env) ``` Java SDK 沒有 `AgentToolContext`。 PHP SDK 沒有 `AgentToolContext`。 Ruby SDK 沒有 `AgentToolContext`。 ### AgentToolContext 與代理工具集 `AgentToolContext` 是工具呼叫的執行上下文。它定義工作目錄和路徑政策，並可下載工作階段的技能。 | 選項 | 說明 | | -------------------------------------------------------------------- | ------------------------------------------------------- | | `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`) | 除工作目錄外，檔案工具（`read`、`write`、`edit`、`glob`、`grep`）可存取的目錄。 | | `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`) | `write` 和 `edit` 會拒絕其下路徑的目錄。 | `EnvironmentWorker` 會自行將工作階段的記憶體儲存區目錄加入 `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`)，並將以 `access: "read_only"` 附加之儲存區的目錄加入 `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`)。 此限制僅是針對檔案工具的防護措施，而非沙箱。它不會限制 `bash`。 `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`) 接收一個 `AgentToolContext`，並傳回標準工具實作（`bash`、`read`、`write`、`edit`、`glob`、`grep`）。