> ## Documentation Index > Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt > Use this file to discover all available pages before exploring further. # 使用沙箱 `sandbox` 命令组用于创建和管理 AgentKit 沙箱工具，并在沙箱会话中执行命令、调用智能体、传输文件、打开 Web 预览或注入本地模型订阅凭据。它也可以初始化 Claude 自托管沙箱项目，并把 Tool 信息交给 [`env`](/productions/agentkit-cli/preview/zh/commands/env) 创建对应 Runtime。`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 , --sid ` 指定用户会话 ID；`--tool-id ` 指定沙箱工具 ID；`--tool-name ` 按工具名称查找；`--tool-type ` 指定工具类型。若本地配置中已经保存 `tool-id`、`tool-name`、`tool-type` 或 `session-id`，相关命令会按各自参数表在未显式传参时读取配置默认值。 工具选择通常按显式 CLI 参数、`.agentkit/sandbox.yaml`、`AGENTKIT_SANDBOX_TOOL_ID`、本地缓存或远端 `Ready` 工具的顺序解析；具体命令是否允许自动创建或提示选择，以对应命令说明为准。 先配置所选平台的控制面凭据，并确认区域支持目标工具类型。使用 BytePlus 时，在命令前加 `agentkit --provider byteplus` 并配置对应区域；不同平台和区域的工具不能互用 工具是云端计算资源，会话是其中一次独立的文件与进程环境。本地会话缓存只用于定位，并不证明远端仍在运行；使用 `sandbox list --sessions --remote --tool-id ` 确认远端状态。会话有存活时间，断开终端不会保证文件永久保留 ## 命令总览 | 子命令 | 说明 | | - | - | | `build` | 在云端 Code Pipeline 中构建自定义沙箱镜像，并写入 `Private` 工具配置和构建状态。 | | `init` | 生成沙箱 Dockerfile 模板，或初始化 Claude 自托管沙箱项目文件。 | | `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` | 在本地与已有沙箱会话之间传输文件或目录。 | | `snapshot` | 创建、查询、恢复和删除会话快照 | ## sandbox build 在云端 Code Pipeline 中构建自定义沙箱镜像。构建完成后，CLI 会把 `tool-type` 设置为 `Private`，把生成的镜像地址与构建状态写入 `.agentkit/sandbox.yaml`，便于后续 `sandbox create` 使用。若 `.agentkit/sandbox.yaml` 包含 `build` 配置，`sandbox build` 会从中读取构建上下文、Dockerfile、镜像名称、命名空间和标签；命令行标志优先于配置文件。 `sandbox build` 会使用 TOS、Container Registry 和 Code Pipeline 等云资源，可能产生费用。执行前确认账号权限、项目目录和镜像命名。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `--dockerfile ` | 相对项目目录的 Dockerfile 路径。 | `Dockerfile` | | `--image-name ` | Container Registry 镜像名称，映射为 CR 仓库名。 | `agentkit-custom-sandbox-image` | | `--repo ` | Container Registry 仓库名；与 `--image-name` 等价。 | `agentkit-custom-sandbox-image` | | `--tag ` | 镜像标签；可包含 `{{timestamp}}` 占位符。 | `{{timestamp}}` | | `--namespace ` | Container Registry 命名空间。 | `agentkit` | | `--project-dir ` | 打包为 Docker 构建上下文的项目目录。 | 当前目录 | ```bash lines theme={null} agentkit sandbox build --project-dir . --dockerfile Dockerfile --image-name custom-sandbox ``` 构建期间显示当前状态和已用时间，构建失败时保留日志与错误原因，便于定位云端构建问题 ## sandbox init 生成沙箱 Dockerfile 模板。未指定模板时，默认生成 `skill` 模板。普通模板会按模板对应的工具类型解析当前内置基础镜像，并把实际镜像地址写入生成的 Dockerfile。`self-host` 模板会初始化 Claude 自托管沙箱项目，写入 `Dockerfile`、`.gitignore`、`.dockerignore`、`README.md` 和 `.agentkit/sandbox.yaml`。 除 `self-host` 外，解析内置基础镜像需要可用的 AgentKit 控制面凭据和区域配置。离线环境或无权限环境无法生成带实际基础镜像的普通模板。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `-t, --template ` | Dockerfile 模板名称：`skill`、`skills`、`aio`、`code`、`code-install-package`、`code-install-skills`、`code-web-server`、`self-host`。 | `skill` | | `-o, --output ` | 输出 Dockerfile 路径；`self-host` 模板固定写入项目约定文件，不使用该参数。 | 模板默认路径 | | `-f, --force` | 覆盖已经存在的输出文件；`self-host` 模板中还会覆盖 `.agentkit/sandbox.yaml`。 | `false` | ```bash lines theme={null} agentkit sandbox init --template code-web-server --output Dockerfile.sandbox agentkit sandbox init -t self-host ``` `self-host` 模板生成的 `.agentkit/sandbox.yaml` 包含 `project_type: self-host`、构建配置、`Private` Tool 默认规格和 `self_host` 配置块。运行 `agentkit env create` 前，先把 `self_host.environment.environment_base_url`、`self_host.environment.environment_id` 与 `self_host.environment.environment_key` 替换为实际 Anthropic 环境参数；保留生成占位符会导致创建失败。 ## sandbox config 配置沙箱命令的本地默认值。配置文件位于当前项目的 `.agentkit/sandbox.yaml`，`--list` 会输出当前配置文件内容，并自动隐藏模型 API Key、WebSearch API Key 和 Claude 自托管环境密钥。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `--set ` | 写入配置值，可重复。 | — | | `--unset ` | 删除配置值，可重复。 | — | | `--list` | 输出当前配置文件内容。 | `false` | ```bash lines theme={null} 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 身份来源。 | | `self-host-project-name` | string | `default` | Claude 自托管沙箱创建 Tool 与 Runtime 时使用的 AgentKit 项目名称。 | | `self-host-poll-interval-seconds` | integer | `5` | 等待 Tool 或 Runtime 状态变化时的轮询间隔，单位为秒。 | | `self-host-environment-base-url` | string | — | Anthropic 环境网关 Base URL；`env create` 必填，生成占位符必须替换。 | | `self-host-environment-id` | string | — | Anthropic 环境 ID；`env create` 必填，生成占位符必须替换。 | | `self-host-environment-key` | string | — | Anthropic 环境密钥；`env create` 必填，生成占位符必须替换。 | | `self-host-sandbox-id` | string | — | Claude 自托管沙箱 Tool ID；`sandbox create` 在自托管项目中会自动写入。 | | `self-host-sandbox-name` | string | — | Claude 自托管沙箱 Tool 名称；`sandbox create` 在自托管项目中会自动写入。 | | `self-host-runtime-image-url` | string | `enterprise-public-cn-beijing.cr.volces.com/vefaas-public/agentkit-selfhostsandbox:runtime-0.0.1` | `env create` 创建 Runtime 时使用的镜像地址。 | | `self-host-runtime-name` | string | `agentkit-selfhost-runtime` | Runtime 名称前缀。 | | `self-host-runtime-role-name` | string | `AgentKit_Runtime_Default_ServiceRole` | Runtime 使用的 IAM 角色名称。 | | `self-host-runtime-cpu-milli` | integer | `2000` | Runtime CPU，单位为 milli-core。 | | `self-host-runtime-memory-mb` | integer | `4096` | Runtime 内存，单位为 MB。 | | `self-host-runtime-min-instance` | integer | `1` | Runtime 最小实例数，可为 `0`。 | | `self-host-runtime-max-instance` | integer | `1` | Runtime 最大实例数，必须大于 `0` 且不小于最小实例数。 | | `self-host-runtime-max-concurrency` | integer | `10` | Runtime 单实例最大并发数。 | | `self-host-runtime-timeout-seconds` | integer | `1200` | 等待 Runtime 就绪的最长时间，单位为秒。 | | `self-host-runtime-api-key-name` | string | `Authorization` | Runtime 网关 API Key 的请求头名称。 | ### 工具鉴权与技能配置 | 配置键 | 说明 | | - | - | | `skill-space-id` | 工具的技能空间 ID；创建时用 --skill-space-id 显式启用 | | `auth-type` | 工具鉴权方式，apikey 或 jwt | | `jwt-discovery-url` | JWT 的 OIDC 发现地址 | | `allowed-clients` | 允许的 JWT 客户端 ID 列表 | ## 模型环境变量 `sandbox create` 和 `sandbox exec` 的模型参数会转换为多组环境变量，供 Codex、OpenCode 和读取 `MODEL_AGENT_*` 的运行时或工具共用。 | 输入 | 注入的环境变量 | | - | - | | `--model-provider ` 或 `model-provider` | `AGENTKIT_SANDBOX_MODEL_PROVIDER` | | `--model-name ` 或 `model-name` | `CODEX_MODEL`、`OPENCODE_MODEL`、`MODEL_AGENT_NAME` | | `--model-api-key ` 或 `model-api-key` | `CODEX_API_KEY`、`OPENCODE_API_KEY`、`MODEL_AGENT_API_KEY` | | `--model-base-url ` 或 `model-base-url` | `CODEX_BASE_URL`、`OPENCODE_BASE_URL`、`MODEL_BASE_URL`、`MODEL_AGENT_BASE_URL` | 若 `--model-base-url` 指向非内置模型端点，需要同时传入 `--model-provider`。对于已有的 `CodeEnv` 会话，`sandbox exec` 中显式传入的模型名称、API Key 或 Base URL 会同步更新会话内的 `/home/gem/.env`、Codex 配置和 OpenCode 配置，后续终端可以复用同一组设置。 生成的 Codex 配置会写入沙箱会话内的 `/home/gem/.codex/config.toml`。通用模型参数不会自动生成 `ANTHROPIC_*` 变量，也不再通过 `CODEX_CONFIG_TOML` 或 `CODEX_MODEL_CATALOG_JSON` 环境变量传递生成配置；如需自定义 Codex 配置，请在会话内编辑该配置文件，或使用 `sandbox codex-login` 重新写入订阅登录配置。 ## sandbox create 创建沙箱工具。创建完成后，CLI 会等待工具进入 `Ready` 状态，并把工具 ID 与名称写入本地沙箱配置。对于 `project_type: self-host` 的项目，创建结果会写入 `self_host.sandbox.id` 和 `self_host.sandbox.name`，供 [`env create`](/productions/agentkit-cli/preview/zh/commands/env#env-create) 创建 Runtime。 `sandbox create` 会在云端创建计算资源，资源存续期间可能产生费用。创建前确认工具类型、规格、网络、镜像和 TOS 挂载配置；不再使用时，通过 `sandbox delete --tool-id --force` 删除工具。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `--tool-type ` | 工具类型：`All-in-one`、`Skill`、`CodeEnv`、`DevEnv`、`ArkClawEnv`、`HermesEnv` 或 `Private`。 | 配置值或 `CodeEnv` | | `--tool-name ` | 工具名称；未设置时自动生成。 | 自动生成 | | `--tos-bucket ` | 要挂载的 TOS bucket。 | 配置值或 — | | `--tos-mount ` | TOS 在沙箱中的挂载路径。 | 配置值或 `/home/gem/workspace` | | `--cpu ` | vCPU 数：`2`、`4`、`8`、`16`。 | 配置值或 `4` | | `--model-name ` | 注入沙箱的模型名称。 | 配置值或模型提供方默认值 | | `--model-api-key ` | 注入沙箱的模型 API Key。 | 配置值或 — | | `--model-provider ` | 模型提供方。 | 配置值或云环境默认值 | | `--model-base-url ` | 模型 API Base URL。 | 配置值或模型提供方默认值 | | `--skill-role-name [roleName]` | 沙箱角色选项，与 `--role-name` 二选一；不带值时交互选择 | — | | `--websearch-apikey ` | WebSearch API Key；不能与 `--skill-role-name` 同时使用。 | 配置值或 — | | `--image-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 ` | 私有网络使用的 VPC ID。 | 配置值或 — | | `--network-subnet-ids ` | 逗号分隔的子网 ID。 | 配置值或 — | | `--llm-shield-app-id ` | 为 `Skill` 沙箱工具启用 LLM Shield，并注入指定应用 ID。 | — | | `--envs ` | 注入沙箱工具的环境变量；可重复传入。与内置变量同名时，本标志传入的值覆盖内置值。 | — | | `--json` | 输出 JSON。 | `false` | | `--role-name [roleName]` | 沙箱 IAM 角色；不带值时交互选择；与 `--skill-role-name` 二选一 | Skill 工具必须显式提供角色选项 | | `--skill-space-id [id]` | 注入 `SKILL_SPACE_ID`；不带值时确认配置值或交互选择空间 | 不注入 | | `--auth-type ` | 工具鉴权方式：`apikey` 或 `jwt` | `apikey` | | `--jwt-discovery-url ` | JWT 的 OIDC 发现地址，JWT 鉴权必填 | — | | `--allowed-clients ` | JWT 允许的客户端 ID，逗号分隔，JWT 鉴权必填 | — | ```bash lines theme={null} 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 ``` 启用 `--network-private` 时，如果命令行或 `.agentkit/sandbox.yaml` 已提供完整的 `network-vpc-id` 与 `network-subnet-ids`，CLI 会直接复用该配置。若配置不完整，CLI 会查询当前区域下的 VPC 与可用子网，交互式选择后写回 `.agentkit/sandbox.yaml`，再继续创建工具。 ```bash lines theme={null} agentkit sandbox create --tool-type CodeEnv --network-private ``` 为 `Skill` 工具启用 LLM Shield 时，必须显式传入应用 ID。该参数只支持 `Skill` 工具类型。 ```bash lines theme={null} agentkit sandbox create \ --tool-type Skill \ --tool-name guarded-skill \ --role-name my-sandbox-role \ --llm-shield-app-id ``` 创建自定义 `Private` 工具时需要先准备镜像地址： ```bash lines theme={null} agentkit sandbox create \ --tool-type Private \ --tool-name private-dev \ --image-url cr.example.com/agentkit/custom-sandbox:latest ``` Claude 自托管沙箱通常使用 `sandbox init -t self-host` 生成配置，再按生成的 `build` 配置构建镜像并创建 `Private` Tool： ```bash lines theme={null} agentkit sandbox init -t self-host # 编辑 .agentkit/sandbox.yaml 中的 self_host.environment.* agentkit sandbox build agentkit sandbox create ``` ## sandbox dashboard 启动本地 Web 控制台，用于查看和操作沙箱工具与会话。该命令会在本机监听一个端口，默认在交互终端中打开浏览器；在 CI 或传入 `--no-open` 时只输出访问地址。 通过安装脚本或 `agentkit upgrade` 安装的独立二进制已包含控制台终端界面所需资源，无需额外安装 Node.js 依赖。若手动解压独立发行包，请保留 `vendor/` 目录与 `ak` 在同一安装目录，否则控制台页面可能无法加载终端组件。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `--host ` | 本地监听地址。 | `127.0.0.1` | | `-p, --port ` | 本地监听端口；`0` 表示自动选择空闲端口。 | `0` | | `-r, --region ` | AgentKit 区域。 | 当前云环境区域 | | `--no-open` | 只输出控制台 URL，不打开浏览器。 | `false` | | `--json` | 以 JSON 输出启动信息。 | `false` | ```bash lines theme={null} agentkit sandbox dashboard --port 0 agentkit sandbox ui --no-open --json ``` ## sandbox delete 删除沙箱工具或工具下的指定会话。传入会话 ID 时删除会话；不传会话 ID 时删除工具本身。删除工具时必须且只能用 `--tool-id` 或 `--tool-name` 指定一个目标。 删除沙箱工具或会话不可恢复，未另行保存的文件、运行状态和会话缓存可能丢失。执行前确认目标 ID 或名称，并先下载需要保留的文件。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `-s, --session-id , --sid ` | 要删除的用户会话 ID；省略时删除工具。 | — | | `--tool-id ` | 沙箱工具 ID。 | — | | `--tool-name ` | 沙箱工具名称。 | — | | `--force` | 跳过确认提示。 | `false` | ```bash lines theme={null} agentkit sandbox delete --tool-id tool-123 --session-id dev --force agentkit sandbox delete --tool-name private-dev --force ``` ## sandbox list 列出沙箱会话或工具，并始终输出 JSON。未传 `--tools` 或 `--sessions` 时默认按 `--sessions --local` 工作，读取本地会话缓存；传入 `--tools` 时默认读取本地工具缓存。需要查询远端数据时显式传入 `--remote`。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `-s, --session-id , --sid ` | 要查找的用户会话 ID。 | — | | `--tool-id ` | 按沙箱工具 ID 过滤会话；与 `--tools` 一起使用时按工具 ID 过滤工具。远端会话查询必填。 | — | | `--sessions` | 列出沙箱会话。 | `true`（未传 `--tools` 时） | | `--tools` | 列出沙箱工具，而不是会话。 | `false` | | `--tool-name ` | 按工具名称过滤工具，仅可与 `--tools` 搭配使用。 | — | | `--tool-type ` | 按工具类型过滤工具，仅可与 `--tools` 搭配使用。 | — | | `--status ` | 按工具状态过滤工具，仅可与 `--tools` 搭配使用。 | — | | `--local` | 仅读取本地缓存。 | `true`（未传 `--remote` 时） | | `--remote` | 查询远端数据；查询远端会话时必须同时传入 `--tool-id`。 | `false` | `sandbox list` 是查看类命令，不会按常用会话命令的工具解析链自动创建或选择沙箱工具。`--tools` 与 `--sessions` 互斥，`--local` 与 `--remote` 互斥；`--tool-name`、`--tool-type` 和 `--status` 只适用于工具模式。 ```bash lines theme={null} agentkit sandbox list agentkit sandbox list --tool-id tool-123 --session-id dev agentkit sandbox list --tools --tool-type CodeEnv --status Ready agentkit sandbox list --tools --remote --tool-name dev-code agentkit sandbox list --sessions --remote --tool-id tool-123 ``` ## sandbox mount 使用 TosBrowser 打开已挂载 TOS 的沙箱会话目录。该命令需要目标工具已配置 TOS 挂载，并且本地已通过 `agentkit login` 保存可用于挂载授权的登录 profile。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `-s, --session-id , --sid ` | 要挂载的用户会话 ID。 | 配置值或 — | | `--oauth-url ` | 选择指定 OAuth profile URL 对应的登录 profile。 | 当前活跃 profile | | `--tool-id ` | 沙箱工具 ID。 | 配置值或 — | | `--tool-name ` | 沙箱工具名称。 | 配置值或 — | | `--tool-type ` | 沙箱工具类型。 | 配置值或 `CodeEnv` | ```bash lines theme={null} agentkit sandbox mount --tool-id tool-123 --session-id dev ``` ## sandbox exec 连接沙箱终端并执行命令。`--command` 可用于指定进入终端后执行的初始命令；未设置时打开终端连接。`--mode tmux` 会附加或创建与会话 ID 同名的 tmux 会话。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `-s, --session-id , --sid ` | 用户会话 ID。 | 配置值或随机生成 | | `--tool-id ` | 沙箱工具 ID。 | 配置值或 — | | `--tool-name ` | 沙箱工具名称。 | 配置值或 — | | `--tool-type ` | 沙箱工具类型。 | `CodeEnv` | | `--command ` | 连接后执行的命令。 | — | | `--mode ` | 执行模式；当前支持 `tmux`。 | — | | `--shell-id ` | 要重连的远端终端 shell ID。 | — | | `--copy ` | 执行前上传本地 SOURCE 到沙箱 DESTINATION，可重复成对传入。 | — | | `--git-config ` | Git 身份来源：`local` 或 INI/TOML/JSON 文件。 | 配置值或 — | | `--model-name ` | 注入会话的模型名称。 | 配置值或 — | | `--model-api-key ` | 注入会话的模型 API Key。 | 配置值或 — | | `--model-provider ` | 注入会话的模型提供方。 | 配置值或 — | | `--model-base-url ` | 注入会话的模型 API Base URL。 | 配置值或 — | | `--disable-websearch-apikey` | 本次会话不注入 WebSearch API Key。 | `false` | ```bash lines theme={null} 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 , --sid ` | 用户会话 ID。 | 配置值或随机生成 | | `--prompt ` | 发送给沙箱 A2A 智能体的提示词；未传 `--task-id` 时必填。 | — | | `--tool-id ` | 沙箱工具 ID。 | 配置值、`AGENTKIT_SANDBOX_TOOL_ID` 或 — | | `--tool-name ` | 沙箱工具名称。 | 配置值或 — | | `--tool-type ` | 沙箱工具类型；未传时优先读取配置值，否则使用 `SkillEnv`。 | 配置值或 `SkillEnv` | | `--async` | 创建任务后立即返回。 | `false` | | `--task-id ` | 轮询已有 A2A 任务 ID。 | — | | `--ttl ` | 沙箱会话 TTL。 | 配置值或 `28800` | | `--model-name ` | 注入为 `MODEL_AGENT_NAME` 的模型名称。 | 配置值或 — | | `--model-provider ` | 注入为 `MODEL_AGENT_PROVIDER` 的模型提供方。 | 配置值或 — | | `--model-base-url ` | 注入为 `MODEL_AGENT_API_BASE` 的模型 API Base URL。 | 配置值或 — | | `--model-api-key ` | 注入为 `MODEL_AGENT_API_KEY` 的模型 API Key。 | 配置值或 — | | `--timeout ` | 等待任务完成的最长秒数。 | `1200` | | `--interval ` | 轮询间隔秒数。 | `2` | | `--history-length ` | 请求的 A2A 任务历史长度。 | `20` | | `--a2a-path ` | 沙箱端点上的 A2A JSON-RPC 路径。 | `/a2a` | ```bash lines theme={null} 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 ` | 包含 exec 条目的 YAML 文件。 | `agentkit-sandbox-run.yaml` | | `--terminal ` | 要打开或执行的 exec 条目数量。 | `1` | | `--dry-run` | 只打印将要执行的 `sandbox exec` 命令。 | `false` | ```yaml title="agentkit-sandbox-run.yaml" lines theme={null} exec: - session_id: dev cwd: . copy: - ["./app", "sandbox:/home/gem/app"] command: "cd /home/gem/app && npm test" ``` ```bash lines theme={null} 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 , --sid ` | 用户会话 ID。 | 配置值或随机生成 | | `--tool-id ` | 沙箱工具 ID。 | 配置值或 — | | `--tool-name ` | 沙箱工具名称。 | 配置值或 — | | `--tool-type ` | 沙箱工具类型。 | 配置值或 `CodeEnv` | | `--command ` | 要在沙箱中执行的命令。 | 必填 | | `--exec-dir ` | 命令执行目录。 | — | | `--copy ` | 执行前上传本地 SOURCE 到沙箱 DESTINATION。 | — | | `--git-config ` | Git 身份来源：`local` 或 INI/TOML/JSON 文件。 | 配置值或 — | ```bash lines theme={null} 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 , --sid ` | 用户会话 ID。 | 配置值或随机生成 | | `--tool-id ` | 沙箱工具 ID。 | 配置值或 — | | `--tool-name ` | 沙箱工具名称。 | 配置值或 — | | `--tool-type ` | 沙箱工具类型。 | `CodeEnv` | | `--no-open` | 只返回 Web URL，不打开浏览器。 | `false` | ```bash lines theme={null} agentkit sandbox web --session-id dev --no-open ``` 打开沙箱主页前会等待浏览器就绪。该 URL 是远程浏览器界面，不会自动发布应用的监听端口；访问会话内的 Web 服务时，在远程浏览器中打开其地址 ## sandbox codex-login 将本地 Codex 或 Claude 订阅凭据注入沙箱会话。`model-login` 与此命令等价。 `sandbox codex-login` 和 `sandbox model-login` 会把本地订阅凭据复制到远端沙箱会话。仅在受信任的沙箱和专用会话中使用，避免共享该会话；使用完成后删除会话或沙箱工具。 使用 `--provider codex` 时，CLI 会在沙箱会话内写入 `/home/gem/.codex/config.toml`，配置 OAuth 登录使用的 `codex_login` 模型提供方，并把默认模型 `gpt-5.5` 同步到 `CODEX_MODEL`、`OPENCODE_MODEL` 与 `MODEL_AGENT_NAME`。本地 API Key 不会随订阅凭据注入。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `-s, --session-id , --sid ` | 要注入的用户会话 ID。 | 配置值或随机生成 | | `-p, --provider ` | 要注入的订阅类型：`codex` 或 `claude`。 | `codex` | | `--auth-file ` | 指定本地凭据文件。 | — | | `--codex-home ` | 本地 Codex home。 | `$CODEX_HOME` 或 `~/.codex` | | `--login` | 本地 Codex 凭据缺失时运行 `codex login`。 | `true` | | `--no-login` | 本地 Codex 凭据缺失时不运行 `codex login`。 | — | | `--tool-id ` | 沙箱工具 ID。 | 配置值或 — | | `--tool-name ` | 沙箱工具名称。 | 配置值或 — | | `--tool-type ` | 沙箱工具类型。 | `CodeEnv` | | `--dry-run` | 打印脱敏后的注入命令，不创建会话。 | `false` | ```bash lines theme={null} agentkit sandbox codex-login --session-id dev --provider codex agentkit sandbox model-login --session-id dev --provider claude --dry-run ``` ## sandbox model-login `model-login` 与 `codex-login` 等价，用于将本地 Codex 或 Claude 订阅凭据注入沙箱会话。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `-s, --session-id , --sid ` | 要注入的用户会话 ID。 | 配置值或随机生成 | | `-p, --provider ` | 要注入的订阅类型：`codex` 或 `claude`。 | `codex` | | `--auth-file ` | 指定本地凭据文件。 | — | | `--codex-home ` | 本地 Codex home。 | `$CODEX_HOME` 或 `~/.codex` | | `--login` | 本地 Codex 凭据缺失时运行 `codex login`。 | `true` | | `--no-login` | 本地 Codex 凭据缺失时不运行 `codex login`。 | — | | `--tool-id ` | 沙箱工具 ID。 | 配置值或 — | | `--tool-name ` | 沙箱工具名称。 | 配置值或 — | | `--tool-type ` | 沙箱工具类型。 | `CodeEnv` | | `--dry-run` | 打印脱敏后的注入命令，不创建会话。 | `false` | ```bash lines theme={null} agentkit sandbox model-login --session-id dev --provider codex ``` ## sandbox scp 在本地与已有沙箱会话之间传输文件或目录。远端路径必须以 `sandbox:` 开头；相对远端路径会解析到 `/home/gem` 下。该命令使用本地会话缓存，因此目标会话需要先通过 `sandbox exec`、`sandbox shell`、`sandbox web`、`sandbox invoke` 或登录命令创建。 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `` | 源路径；本地路径或 `sandbox:`。 | 必填 | | `` | 目标路径；本地路径或 `sandbox:`。 | 必填 | | `-s, --session-id , --sid ` | 用于传输的用户会话 ID。 | 配置值或 — | | `--tool-id ` | 用于区分本地会话缓存的沙箱工具 ID。 | — | ```bash lines theme={null} 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 ``` ## 技能空间、角色与 JWT 创建 `Skill` 工具时，必须传入 `--role-name` 或 `--skill-role-name`，两者不能同时使用或重复传入。交互选择会列出角色并标明缺少的策略，不满足要求的角色不可选；可在提示中确认创建默认角色。非交互环境需传入明确的角色名称 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `Skill` + `apikey` | 技能与 TOS 挂载权限 | `AgentKitDefaultSkillsSandboxAccess` + `AgentKitTOSMountAccess` | | `Skill` + `jwt` | 技能、用户授权与 TOS 挂载权限 | 上述两项 + `AgentKitOauthDefaultSandboxAccess` | | 非 Skill + `apikey` | 通用沙箱权限 | `AgentKitDefaultSandboxAccess` | | 非 Skill + `jwt` | 用户授权沙箱权限 | `AgentKitOauthDefaultSandboxAccess` | 非 Skill 工具挂载 TOS 时还需 `AgentKitTOSMountAccess`。角色选项不能与 `--websearch-apikey` 同时使用；缺少权限时 CLI 不会直接给已有角色追加策略 创建工具可能产生云资源费用。显式指定的角色名称不存在时，CLI 会自动创建 IAM 角色并绑定所需策略；交互选择也可在确认后创建默认角色。创建角色需要相应的 IAM 权限。JWT 只允许配置的客户端访问，请核对发现地址和客户端 ID ```bash lines theme={null} agentkit sandbox create --tool-type Skill --role-name my-sandbox-role --skill-space-id ss-example --auth-type jwt --jwt-discovery-url "https://identity.example.com/.well-known/openid-configuration" --allowed-clients client-example ``` `--skill-space-id ss-example` 直接选择空间；单独传 `--skill-space-id` 会在交互终端确认 `.agentkit/sandbox.yaml` 中的值或从 `default` 项目的空间中选择。成功创建后保存 `skill-space-id`；未传此选项时不会自动注入空间 ID。`--json` 与 CI 不支持交互选择 `apikey` 不接受 JWT 专用参数。可通过 `sandbox config --set auth-type=jwt`、`jwt-discovery-url`、`allowed-clients` 和 `skill-space-id` 保存对应配置，创建时显式参数优先 ## 会话快照 工具需支持快照，可在创建工具时传入 `--enable-snapshot`。创建后通过 `get` 确认状态，再执行恢复；快照可用性取决于工具类型和区域能力。所有快照子命令均要求显式 `--tool-id`，不会从普通会话命令推断该必填值 ## sandbox snapshot create 为指定会话创建快照，结果包含快照 ID 与状态 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `--tool-id ` | 沙箱工具 ID，必填 | 必填 | | `--instance-id ` | 沙箱实例的 SessionId；create 时优先于用户会话 ID | — | | `--json` | 输出 JSON；快照子命令始终返回 JSON | `false` | | `-s, --session-id , --sid ` | 用户会话 ID；create 时定位源会话，resume 时指定目标会话 | — | | `--session ` | --session-id 的别名 | — | | `-h, --help` | 显示帮助 | — | 先将工具创建结果中的 `tool_id` 赋给变量；以下示例要求该工具内已有 `report-session` 会话 ```bash lines theme={null} export TOOL_ID="" ``` ```bash lines theme={null} agentkit sandbox snapshot create --tool-id "$TOOL_ID" --session-id report-session ``` `--session-id` 在工具内定位用户会话；匹配多个实例时改用 `--instance-id`，该参数直接指定实例 ID 并优先使用。结果中的 `session_id` 是用户会话，`instance_id` 是实例 ID，两者不可混淆 将创建结果返回的快照 ID 保存为变量，再检查快照是否可用 ```bash lines theme={null} export SNAPSHOT_ID="" ``` ## sandbox snapshot get 查看快照的状态、所属工具和会话 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `--tool-id ` | 沙箱工具 ID，必填 | 必填 | | `--snapshot-id ` | 快照 ID，必填 | 必填 | | `--json` | 输出 JSON；快照子命令始终返回 JSON | `false` | | `-h, --help` | 显示帮助 | — | ```bash lines theme={null} agentkit sandbox snapshot get --tool-id "$TOOL_ID" --snapshot-id "$SNAPSHOT_ID" ``` ## sandbox snapshot list 按会话、实例、创建时间和分页条件查询快照 | 标志/参数 | 说明 | 默认值 | | - | - | - | | `--tool-id ` | 沙箱工具 ID，必填 | 必填 | | `--instance-id ` | 沙箱实例的 SessionId；create 时优先于用户会话 ID | — | | `--create-time-after