使用沙箱

sandbox 命令组用于创建和管理 AgentKit 沙箱工具，并在沙箱会话中执行命令、调用智能体、传输文件、打开 Web 预览或注入本地模型订阅凭据。sandbox create 与 sandbox config 对外支持的工具类型包括 All-in-one、Skill、CodeEnv、DevEnv、ArkClawEnv、HermesEnv 和 Private。

多数沙箱命令从 .agentkit/sandbox.yaml 或 AGENTKIT_SANDBOX_REGION 读取 AgentKit 控制面区域；sandbox dashboard 还支持用 --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`	删除沙箱工具或指定会话。
`dashboard` (`ui`)	启动本地沙箱 Web 控制台。
`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 模板。命令会按模板对应的工具类型解析当前内置基础镜像，并把实际镜像地址写入生成的 Dockerfile。

解析内置基础镜像需要可用的 AgentKit 控制面凭据和区域配置。离线环境或无权限环境无法生成带实际基础镜像的模板。

标志/参数	说明	默认值
`-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 会输出当前配置文件内容，并自动隐藏模型 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=deepseek-v4-flash-ga-260731

agentkit sandbox config --list

首次写入 .agentkit/sandbox.yaml 时，CLI 只保存网络、工具类型、CPU、快照和会话 TTL 等基础默认值；模型提供方、模型名称和模型 Base URL 会在读取有效配置时按云环境补齐，只有用户通过 sandbox config --set model-* 或命令行标志显式设置后才会持久化。支持的配置键如下。

配置键	类型	默认值	说明
`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`	`All-in-one` \| `Skill` \| `CodeEnv` \| `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>`	工具类型：`All-in-one`、`Skill`、`CodeEnv`、`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。	配置值或 —
`--llm-shield-app-id <app-id>`	为 `Skill` 沙箱工具启用 LLM Shield，并注入指定应用 ID。	—
`--envs <KEY=VALUE>`	注入沙箱工具的环境变量；可重复传入。与内置变量同名时，本标志传入的值覆盖内置值。	—
`--json`	输出 JSON。	`false`

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

agentkit sandbox create \
  --tool-type CodeEnv \
  --tool-name dev-code \
  --envs NODE_ENV=development \
  --envs FEATURE_FLAG=enabled

为 Skill 工具启用 LLM Shield 时，必须显式传入应用 ID。该参数只支持 Skill 工具类型。

agentkit sandbox create \
  --tool-type Skill \
  --tool-name guarded-skill \
  --llm-shield-app-id <app-id>

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

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

sandbox dashboard

启动本地 Web 控制台，用于查看和操作沙箱工具与会话。该命令会在本机监听一个端口，默认在交互终端中打开浏览器；在 CI 或传入 --no-open 时只输出访问地址。

通过安装脚本或 agentkit upgrade 安装的独立二进制已包含控制台终端界面所需资源，无需额外安装 Node.js 依赖。若手动解压独立发行包，请保留 vendor/ 目录与 ak 在同一安装目录，否则控制台页面可能无法加载终端组件。

标志/参数	说明	默认值
`--host <host>`	本地监听地址。	`127.0.0.1`
`-p, --port <port>`	本地监听端口；`0` 表示自动选择空闲端口。	`0`
`-r, --region <region>`	AgentKit 区域。	当前云环境区域
`--no-open`	只输出控制台 URL，不打开浏览器。	`false`
`--json`	以 JSON 输出启动信息。	`false`

agentkit sandbox dashboard --port 0

agentkit sandbox ui --no-open --json

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

连接沙箱终端并执行命令。--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。默认打开浏览器时，CLI 会同时请求远端沙箱浏览器打开 /home/gem/，便于直接查看会话文件；传入 --no-open 时只返回 Web URL。

标志/参数	说明	默认值
`-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 dashboard

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 dashboard

​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 dashboard

sandbox delete

sandbox list

sandbox mount

sandbox exec

sandbox invoke

sandbox run

sandbox shell

sandbox web

sandbox codex-login

sandbox model-login

sandbox scp