> ## 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 预览或注入本地模型订阅凭据。`sandbox create` 与 `sandbox config` 对外支持的工具类型包括 `All-in-one`、`Skill`、`CodeEnv`、`DevEnv`、`ArkClawEnv`、`HermesEnv` 和 `Private`。

<Note>
  多数沙箱命令从 `.agentkit/sandbox.yaml` 或 `AGENTKIT_SANDBOX_REGION` 读取 AgentKit 控制面区域；`sandbox dashboard` 还支持用 `--region` 指定本地控制台会话的区域。TOS 挂载区域可通过 `AGENTKIT_SANDBOX_TOS_REGION` 指定；未设置时，CLI 会根据 TOS bucket 或当前云环境推断。
</Note>

常用会话命令使用同一组工具和会话定位参数：`-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` 使用。

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

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `--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 构建上下文的项目目录。 | 当前目录 |

```bash lines theme={null}
agentkit sandbox build --project-dir . --dockerfile Dockerfile --image-name custom-sandbox
```

## sandbox init

生成沙箱 Dockerfile 模板。未指定模板时，默认生成 `skill` 模板。命令会按模板对应的工具类型解析当前内置基础镜像，并把实际镜像地址写入生成的 Dockerfile。

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

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

```bash lines theme={null}
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` |

```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 身份来源。 |

## sandbox create

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

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

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `--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。 | 配置值或 — |
| `--envs <KEY=VALUE>` | 注入沙箱工具的环境变量；可重复传入。与内置变量同名时，本标志传入的值覆盖内置值。 | — |
| `--json` | 输出 JSON。 | `false` |

```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
```

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

```bash lines theme={null}
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` 时只输出访问地址。

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

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `--host <host>` | 本地监听地址。 | `127.0.0.1` |
| `-p, --port <port>` | 本地监听端口；`0` 表示自动选择空闲端口。 | `0` |
| `-r, --region <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` 指定一个目标。

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

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `-s, --session-id <id>, --sid <id>` | 要删除的用户会话 ID；省略时删除工具。 | — |
| `--tool-id <id>` | 沙箱工具 ID。 | — |
| `--tool-name <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，不会列出云端所有沙箱工具。

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

```bash lines theme={null}
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` |

```bash lines theme={null}
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` |

```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 <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` |

```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 <path>` | 包含 exec 条目的 YAML 文件。 | `agentkit-sandbox-run.yaml` |
| `--terminal <count>` | 要打开或执行的 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 <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 文件。 | 配置值或 — |

```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 <id>, --sid <id>` | 用户会话 ID。 | 配置值或随机生成 |
| `--tool-id <id>` | 沙箱工具 ID。 | 配置值或 — |
| `--tool-name <name>` | 沙箱工具名称。 | 配置值或 — |
| `--tool-type <type>` | 沙箱工具类型。 | `CodeEnv` |
| `--no-open` | 只返回 Web URL，不打开浏览器。 | `false` |

```bash lines theme={null}
agentkit sandbox web --session-id dev --no-open
```

## sandbox codex-login

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

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

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

```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 <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` |

```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` 或登录命令创建。

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `<source>` | 源路径；本地路径或 `sandbox:<path>`。 | 必填 |
| `<destination>` | 目标路径；本地路径或 `sandbox:<path>`。 | 必填 |
| `-s, --session-id <id>, --sid <id>` | 用于传输的用户会话 ID。 | 配置值或 — |
| `--tool-id <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
```