使用沙箱

sandbox 命令组用于创建和管理 AgentKit 沙箱工具，并在沙箱会话中执行命令、调用智能体、传输文件、打开 Web 预览或注入本地模型订阅凭据。当前沙箱工具类型包括 CodeEnv、SkillEnv 和 Private。

沙箱命令不提供 --region 标志。需要指定 AgentKit 控制面区域时，可通过 agentkit sandbox config --set region=<region> 写入 .agentkit/sandbox.yaml，或设置 AGENTKIT_SANDBOX_REGION。TOS 挂载区域可通过 AGENTKIT_SANDBOX_TOS_REGION 指定；未设置时，CLI 会根据 TOS bucket 或当前云环境推断。

常用会话命令使用同一组工具和会话定位参数：-s, --session-id <id>, --sid <id> 指定用户会话 ID；--tool-id <id> 指定沙箱工具 ID；--tool-name <name> 按工具名称查找；--tool-type <type> 指定工具类型。若本地配置中已经保存 tool-id、tool-name、tool-type 或 session-id，相关命令会按各自参数表在未显式传参时读取配置默认值。

命令总览

子命令	说明
`build`	在云端 Code Pipeline 中构建自定义沙箱镜像，并写入 `Private` 工具配置。
`init`	生成沙箱 Dockerfile 模板。
`config`	读取、写入或删除沙箱命令默认值。
`create`	创建沙箱工具。
`delete`	删除沙箱工具或指定会话。
`list`	列出本地缓存的沙箱会话。
`mount`	使用 TosBrowser 打开已挂载 TOS 的沙箱会话目录。
`exec`	连接沙箱终端并执行命令。
`invoke`	通过 A2A 调用 `SkillEnv` 沙箱中的智能体。
`run`	按 YAML 编排执行一组 `sandbox exec` 任务。
`shell`	在沙箱中执行非交互 shell 命令并输出 JSON 结果。
`web`	打开沙箱 Web 预览。
`codex-login`	将本地 Codex 或 Claude 订阅凭据注入沙箱会话。
`model-login`	`codex-login` 的等价命令。
`scp`	在本地与已有沙箱会话之间传输文件或目录。

sandbox build

在云端 Code Pipeline 中构建自定义沙箱镜像。构建完成后，CLI 会把 tool-type 设置为 Private，并把生成的镜像地址写入 .agentkit/sandbox.yaml，便于后续 sandbox create 使用。

sandbox build 会使用 TOS、Container Registry 和 Code Pipeline 等云资源，可能产生费用。执行前确认账号权限、项目目录和镜像命名；构建失败时，CLI 可能在项目的 .agentkit/sandbox/build/ 目录写入构建日志。

标志/参数	说明	默认值
`--dockerfile <path>`	相对项目目录的 Dockerfile 路径。	`Dockerfile`
`--image-name <name>`	Container Registry 镜像名称，映射为 CR 仓库名。	`agentkit-custom-sandbox-image`
`--repo <name>`	Container Registry 仓库名；与 `--image-name` 等价。	`agentkit-custom-sandbox-image`
`--tag <tag>`	镜像标签；可包含 `{{timestamp}}` 占位符。	`{{timestamp}}`
`--namespace <name>`	Container Registry 命名空间。	`agentkit`
`--project-dir <path>`	打包为 Docker 构建上下文的项目目录。	当前目录

agentkit sandbox build --project-dir . --dockerfile Dockerfile --image-name custom-sandbox

sandbox init

生成沙箱 Dockerfile 模板。未指定模板时，默认生成 skill 模板。

标志/参数	说明	默认值
`-t, --template <name>`	Dockerfile 模板名称：`skill`、`skills`、`aio`、`code`、`code-install-package`、`code-install-skills`、`code-web-server`。	`skill`
`-o, --output <path>`	输出 Dockerfile 路径。	模板默认路径
`-f, --force`	覆盖已经存在的输出文件。	`false`

agentkit sandbox init --template code-web-server --output Dockerfile.sandbox

sandbox config

配置沙箱命令的本地默认值。配置文件位于当前项目的 .agentkit/sandbox.yaml，--list 会输出合并默认值后的 YAML，并自动隐藏模型 API Key 和 WebSearch API Key。

标志/参数	说明	默认值
`--set <KEY=VALUE>`	写入配置值，可重复。	—
`--unset <KEY>`	删除配置值，可重复。	—
`--list`	输出当前有效配置。	`false`

agentkit sandbox config \
  --set tool-type=CodeEnv \
  --set session-id=dev \
  --set model-name=glm-5-2-260617

agentkit sandbox config --list

支持的配置键如下。

配置键	类型	默认值	说明
`model-name`	string	根据云环境选择	注入沙箱的模型名称。
`model-base-url`	string	根据模型提供方选择	模型 API Base URL。
`model-provider`	string	Volcengine 为 `model_square`，BytePlus 为 `byteplus_model_square`	模型提供方。
`model-api-key`	string	—	注入沙箱的模型 API Key。
`network-public`	boolean	`true`	创建工具时启用公网访问。
`network-private`	boolean	`false`	创建工具时启用私有 VPC 访问。
`network-shared-internet`	boolean	`false`	私有网络下启用共享公网出口。
`network-vpc-id`	string	—	私有网络使用的 VPC ID。
`network-subnet-ids`	string list	—	私有网络使用的子网 ID，支持逗号分隔或 JSON 数组。
`tool-type`	`CodeEnv` \| `SkillEnv` \| `DevEnv` \| `ArkClawEnv` \| `HermesEnv` \| `Private`	`CodeEnv`	默认沙箱工具类型。
`tool-id`	string	—	默认沙箱工具 ID。
`tool-name`	string	—	默认沙箱工具名称。
`region`	string	当前云环境区域	AgentKit 控制面区域。
`cpu`	`2` \| `4` \| `8` \| `16`	`4`	创建工具时使用的 vCPU 数。
`tos-bucket`	string	—	创建工具时挂载的 TOS bucket。
`tos-mount`	string	`/home/gem/workspace`	TOS 在沙箱中的挂载路径。
`role-name`	string	—	`--skill-role-name` 未传值时使用的 IAM 角色名。
`enable-snapshot`	boolean	`false`	创建工具时启用会话快照。
`websearch-apikey`	string	—	注入沙箱的 WebSearch API Key。
`image-url`	string	—	`Private` 工具使用的自定义镜像地址。
`tool-image-url`	string	—	`image-url` 的别名。
`session-id`	string	随机生成	默认用户会话 ID。
`ttl`	integer	`28800`	会话 TTL，单位为秒。
`git-config`	`local` 或文件路径	—	注入沙箱会话的 Git 身份来源。

sandbox create

创建沙箱工具。创建完成后，CLI 会等待工具进入 Ready 状态，并把工具 ID 与名称写入本地沙箱配置。

sandbox create 会在云端创建计算资源，资源存续期间可能产生费用。创建前确认工具类型、规格、网络、镜像和 TOS 挂载配置；不再使用时，通过 sandbox delete --tool-id <id> --force 删除工具。

标志/参数	说明	默认值
`--tool-type <type>`	工具类型：`CodeEnv`、`SkillEnv`、`DevEnv`、`ArkClawEnv`、`HermesEnv`、`Private`。	配置值或 `CodeEnv`
`--tool-name <name>`	工具名称；未设置时自动生成。	自动生成
`--tos-bucket <bucket>`	要挂载的 TOS bucket。	配置值或 —
`--tos-mount <path>`	TOS 在沙箱中的挂载路径。	配置值或 `/home/gem/workspace`
`--cpu <count>`	vCPU 数：`2`、`4`、`8`、`16`。	配置值或 `4`
`--model-name <name>`	注入沙箱的模型名称。	配置值或模型提供方默认值
`--model-api-key <key>`	注入沙箱的模型 API Key。	配置值或 —
`--model-provider <provider>`	模型提供方。	配置值或云环境默认值
`--model-base-url <url>`	模型 API Base URL。	配置值或模型提供方默认值
`--skill-role-name [roleName]`	为沙箱技能配置 IAM 角色；省略值时自动生成角色名。	配置的 `role-name` 或 —
`--websearch-apikey <key>`	WebSearch API Key；不能与 `--skill-role-name` 同时使用。	配置值或 —
`--image-url <url>`	自定义镜像地址；`Private` 工具必填。	配置值或 —
`--enable-snapshot`	启用会话快照。	配置值或 `false`
`--network-public`	启用公网访问。	配置值或 `true`
`--no-network-public`	禁用公网访问。	—
`--network-private`	启用私有 VPC 访问。	配置值或 `false`
`--no-network-private`	禁用私有 VPC 访问。	—
`--network-shared-internet`	私有网络下启用共享公网出口。	配置值或 `false`
`--no-network-shared-internet`	禁用共享公网出口。	—
`--network-vpc-id <id>`	私有网络使用的 VPC ID；启用 `--network-private` 时必填。	配置值或 —
`--network-subnet-ids <ids>`	逗号分隔的子网 ID。	配置值或 —
`--json`	输出 JSON。	`false`

agentkit sandbox create --tool-type CodeEnv --tool-name dev-code --cpu 4

创建自定义 Private 工具时需要先准备镜像地址：

agentkit sandbox create \
  --tool-type Private \
  --tool-name private-dev \
  --image-url cr.example.com/agentkit/custom-sandbox:latest

sandbox delete

删除沙箱工具或工具下的指定会话。传入会话 ID 时删除会话；不传会话 ID 时删除工具本身。删除工具时必须且只能用 --tool-id 或 --tool-name 指定一个目标。

删除沙箱工具或会话不可恢复，未另行保存的文件、运行状态和会话缓存可能丢失。执行前确认目标 ID 或名称，并先下载需要保留的文件。

标志/参数	说明	默认值
`-s, --session-id <id>, --sid <id>`	要删除的用户会话 ID；省略时删除工具。	—
`--tool-id <id>`	沙箱工具 ID。	—
`--tool-name <name>`	沙箱工具名称。	—
`--force`	跳过确认提示。	`false`

agentkit sandbox delete --tool-id tool-123 --session-id dev --force

agentkit sandbox delete --tool-name private-dev --force

sandbox list

列出本地缓存的沙箱会话，或查看某个本地缓存会话。该命令读取本地会话缓存并输出 JSON，不会列出云端所有沙箱工具。

标志/参数	说明	默认值
`-s, --session-id <id>, --sid <id>`	要查找的用户会话 ID。	—
`--tool-id <id>`	按沙箱工具 ID 过滤本地缓存。	—

agentkit sandbox list

agentkit sandbox list --tool-id tool-123 --session-id dev

sandbox mount

使用 TosBrowser 打开已挂载 TOS 的沙箱会话目录。该命令需要目标工具已配置 TOS 挂载，并且本地已通过 agentkit login 保存可用于挂载授权的登录 profile。

标志/参数	说明	默认值
`-s, --session-id <id>, --sid <id>`	要挂载的用户会话 ID。	配置值或 —
`--oauth-url <url>`	选择指定 OAuth profile URL 对应的登录 profile。	当前活跃 profile
`--tool-id <id>`	沙箱工具 ID。	配置值或 —
`--tool-name <name>`	沙箱工具名称。	配置值或 —
`--tool-type <type>`	沙箱工具类型。	配置值或 `CodeEnv`

agentkit sandbox mount --tool-id tool-123 --session-id dev

sandbox exec

sandbox attach 是该命令的别名，接受相同标志。连接沙箱终端并执行命令。--command 可用于指定进入终端后执行的初始命令；未设置时打开终端连接。--mode tmux 会附加或创建与会话 ID 同名的 tmux 会话。

标志/参数	说明	默认值
`-s, --session-id <id>, --sid <id>`	用户会话 ID。	配置值或随机生成
`--tool-id <id>`	沙箱工具 ID。	配置值或 —
`--tool-name <name>`	沙箱工具名称。	配置值或 —
`--tool-type <type>`	沙箱工具类型。	`CodeEnv`
`--command <cmd>`	连接后执行的命令。	—
`--mode <mode>`	执行模式；当前支持 `tmux`。	—
`--shell-id <id>`	要重连的远端终端 shell ID。	—
`--copy <sourceAndDestination...>`	执行前上传本地 SOURCE 到沙箱 DESTINATION，可重复成对传入。	—
`--git-config <source>`	Git 身份来源：`local` 或 INI/TOML/JSON 文件。	配置值或 —
`--model-name <name>`	注入会话的模型名称。	配置值或 —
`--model-api-key <key>`	注入会话的模型 API Key。	配置值或 —
`--model-provider <provider>`	注入会话的模型提供方。	配置值或 —
`--model-base-url <url>`	注入会话的模型 API Base URL。	配置值或 —
`--disable-websearch-apikey`	本次会话不注入 WebSearch API Key。	`false`

agentkit sandbox exec --session-id dev --command "npm test"

agentkit sandbox exec \
  --session-id dev \
  --mode tmux \
  --copy ./app sandbox:/home/gem/app \
  --command "cd /home/gem/app && codex"

sandbox invoke

通过 A2A 调用沙箱中的智能体。默认工具类型为 SkillEnv，输出 JSON。传入 --async 时，命令在创建任务后立即返回；传入 --task-id 时，命令轮询已有任务。

标志/参数	说明	默认值
`[asyncMode]`	与 `--async` 搭配使用的可选布尔值：`true` 或 `false`。	—
`-s, --session-id <id>, --sid <id>`	用户会话 ID。	配置值或随机生成
`--prompt <prompt>`	发送给沙箱 A2A 智能体的提示词；未传 `--task-id` 时必填。	—
`--tool-id <id>`	沙箱工具 ID。	配置值、`AGENTKIT_SANDBOX_TOOL_ID` 或 —
`--tool-name <name>`	沙箱工具名称。	配置值或 —
`--tool-type <type>`	沙箱工具类型。	配置值或 `SkillEnv`
`--async`	创建任务后立即返回。	`false`
`--task-id <id>`	轮询已有 A2A 任务 ID。	—
`--ttl <seconds>`	沙箱会话 TTL。	配置值或 `28800`
`--model-name <name>`	注入为 `MODEL_AGENT_NAME` 的模型名称。	配置值或 —
`--model-provider <provider>`	注入为 `MODEL_AGENT_PROVIDER` 的模型提供方。	配置值或 —
`--model-base-url <url>`	注入为 `MODEL_AGENT_API_BASE` 的模型 API Base URL。	配置值或 —
`--model-api-key <key>`	注入为 `MODEL_AGENT_API_KEY` 的模型 API Key。	配置值或 —
`--timeout <seconds>`	等待任务完成的最长秒数。	`1200`
`--interval <seconds>`	轮询间隔秒数。	`2`
`--history-length <count>`	请求的 A2A 任务历史长度。	`20`
`--a2a-path <path>`	沙箱端点上的 A2A JSON-RPC 路径。	`/a2a`

agentkit sandbox invoke --tool-id skill-tool-123 --session-id task-dev --prompt "总结项目结构"

agentkit sandbox invoke --tool-id skill-tool-123 --prompt "执行长任务" --async

sandbox run

读取 YAML 文件并把其中的条目转换为 agentkit sandbox exec 命令。默认文件名为 agentkit-sandbox-run.yaml。配置根节点可以是列表，也可以是包含 exec、execs、tabs 或 commands 的对象。

标志/参数	说明	默认值
`-f, --config <path>`	包含 exec 条目的 YAML 文件。	`agentkit-sandbox-run.yaml`
`--terminal <count>`	要打开或执行的 exec 条目数量。	`1`
`--dry-run`	只打印将要执行的 `sandbox exec` 命令。	`false`

agentkit-sandbox-run.yaml

exec:
  - session_id: dev
    cwd: .
    copy:
      - ["./app", "sandbox:/home/gem/app"]
    command: "cd /home/gem/app && npm test"

agentkit sandbox run --config agentkit-sandbox-run.yaml --dry-run

条目支持的字段包括 session_id、sid、tool_id、tool_type、command、mode、shell_id、git_config、model_name、model_api_key、model_provider、model_base_url、cwd、workdir、copy 和 copies。也可以使用 args 或 argv 直接提供 sandbox exec 的原始参数列表。

sandbox shell

在沙箱中执行非交互 shell 命令并输出 JSON 结果。该命令要求传入 --command，适合自动化脚本；需要交互终端时使用 sandbox exec。

标志/参数	说明	默认值
`-s, --session-id <id>, --sid <id>`	用户会话 ID。	配置值或随机生成
`--tool-id <id>`	沙箱工具 ID。	配置值或 —
`--tool-name <name>`	沙箱工具名称。	配置值或 —
`--tool-type <type>`	沙箱工具类型。	配置值或 `CodeEnv`
`--command <cmd>`	要在沙箱中执行的命令。	必填
`--exec-dir <dir>`	命令执行目录。	—
`--copy <sourceAndDestination...>`	执行前上传本地 SOURCE 到沙箱 DESTINATION。	—
`--git-config <source>`	Git 身份来源：`local` 或 INI/TOML/JSON 文件。	配置值或 —

agentkit sandbox shell --session-id dev --command "python --version"

sandbox web

打开沙箱 Web 预览，并输出包含 URL、工具 ID、会话 ID 与会话是否新建的 JSON。

标志/参数	说明	默认值
`-s, --session-id <id>, --sid <id>`	用户会话 ID。	配置值或随机生成
`--tool-id <id>`	沙箱工具 ID。	配置值或 —
`--tool-name <name>`	沙箱工具名称。	配置值或 —
`--tool-type <type>`	沙箱工具类型。	`CodeEnv`
`--no-open`	只返回 Web URL，不打开浏览器。	`false`

agentkit sandbox web --session-id dev --no-open

将本地 Codex 或 Claude 订阅凭据注入沙箱会话。model-login 与此命令等价。

sandbox codex-login 和 sandbox model-login 会把本地订阅凭据复制到远端沙箱会话。仅在受信任的沙箱和专用会话中使用，避免共享该会话；使用完成后删除会话或沙箱工具。

标志/参数	说明	默认值
`-s, --session-id <id>, --sid <id>`	要注入的用户会话 ID。	配置值或随机生成
`-p, --provider <provider>`	要注入的订阅类型：`codex` 或 `claude`。	`codex`
`--auth-file <path>`	指定本地凭据文件。	—
`--codex-home <path>`	本地 Codex home。	`$CODEX_HOME` 或 `~/.codex`
`--login`	本地 Codex 凭据缺失时运行 `codex login`。	`true`
`--no-login`	本地 Codex 凭据缺失时不运行 `codex login`。	—
`--tool-id <id>`	沙箱工具 ID。	配置值或 —
`--tool-name <name>`	沙箱工具名称。	配置值或 —
`--tool-type <type>`	沙箱工具类型。	`CodeEnv`
`--dry-run`	打印脱敏后的注入命令，不创建会话。	`false`

agentkit sandbox codex-login --session-id dev --provider codex

agentkit sandbox model-login --session-id dev --provider claude --dry-run

model-login 与 codex-login 等价，用于将本地 Codex 或 Claude 订阅凭据注入沙箱会话。

标志/参数	说明	默认值
`-s, --session-id <id>, --sid <id>`	要注入的用户会话 ID。	配置值或随机生成
`-p, --provider <provider>`	要注入的订阅类型：`codex` 或 `claude`。	`codex`
`--auth-file <path>`	指定本地凭据文件。	—
`--codex-home <path>`	本地 Codex home。	`$CODEX_HOME` 或 `~/.codex`
`--login`	本地 Codex 凭据缺失时运行 `codex login`。	`true`
`--no-login`	本地 Codex 凭据缺失时不运行 `codex login`。	—
`--tool-id <id>`	沙箱工具 ID。	配置值或 —
`--tool-name <name>`	沙箱工具名称。	配置值或 —
`--tool-type <type>`	沙箱工具类型。	`CodeEnv`
`--dry-run`	打印脱敏后的注入命令，不创建会话。	`false`

agentkit sandbox model-login --session-id dev --provider codex

sandbox scp

在本地与已有沙箱会话之间传输文件或目录。远端路径必须以 sandbox: 开头；相对远端路径会解析到 /home/gem 下。该命令使用本地会话缓存，因此目标会话需要先通过 sandbox exec、sandbox shell、sandbox web、sandbox invoke 或登录命令创建。

标志/参数	说明	默认值
`<source>`	源路径；本地路径或 `sandbox:<path>`。	必填
`<destination>`	目标路径；本地路径或 `sandbox:<path>`。	必填
`-s, --session-id <id>, --sid <id>`	用于传输的用户会话 ID。	配置值或 —
`--tool-id <id>`	用于区分本地会话缓存的沙箱工具 ID。	—

agentkit sandbox scp ./local.txt sandbox:/home/gem/local.txt --session-id dev

agentkit sandbox scp sandbox:/home/gem/result.json ./result.json --session-id dev

开始使用

AI-Friendly

命令参考

命令总览

sandbox build

sandbox init

sandbox config

sandbox create

sandbox delete

sandbox list

sandbox mount

sandbox exec

sandbox invoke

sandbox run

sandbox shell

sandbox web

sandbox scp

​命令总览

​sandbox build

​sandbox init

​sandbox config

​sandbox create

​sandbox delete

​sandbox list

​sandbox mount

​sandbox exec

​sandbox invoke

​sandbox run

​sandbox shell

​sandbox web

​sandbox codex-login

​sandbox model-login

​sandbox scp

命令总览

sandbox build

sandbox init

sandbox config

sandbox create

sandbox delete

sandbox list

sandbox mount

sandbox exec

sandbox invoke

sandbox run

sandbox shell

sandbox web

sandbox codex-login

sandbox model-login

sandbox scp