使用 Codex 沙箱开发应用

AgentKit 沙箱提供云端开发环境，可在其中使用 Codex 等编码智能体开发应用。工具定义计算规格与网络等环境属性；会话保存一次开发过程的文件和运行状态。完整参数见使用沙箱。

开始前请配置 AK/SK，或通过 agentkit login 获取有效的短期 STS 凭证。若要把本地 Codex 订阅凭据注入沙箱，还需先在本机完成 codex login。

创建沙箱工具会分配云端计算资源，可能产生费用。沙箱中的命令可以访问该会话可见的文件、网络和凭据；只处理可信代码，并按最小权限配置。删除会话或工具不可恢复，清理前先下载需要保留的文件。

端到端流程

创建开发工具

创建一个 CodeEnv 工具。CLI 会等待工具就绪，并把工具 ID 与名称写入当前项目的 .agentkit/sandbox.yaml。

agentkit sandbox create --tool-type CodeEnv --tool-name dev-sandbox

若项目已有可用工具，可以跳过此步骤，并在后续命令中用 --tool-id 或 --tool-name 选择它。

注入 Codex 登录凭据

将本地 Codex 订阅凭据注入专用会话。--session-id 用于在后续命令中复用同一会话。

sandbox codex-login 会把本地订阅凭据复制到远端会话。不要共享该会话；使用完成后删除会话或工具。可先加 --dry-run 查看脱敏后的注入操作。

agentkit sandbox codex-login \
  --tool-name dev-sandbox \
  --session-id dev \
  --provider codex

需要使用其他凭据文件时，传入 --auth-file 或 --codex-home。将 provider 改为 claude，可注入本地 Claude 订阅凭据。使用 --provider codex 时，CLI 会在沙箱会话内写入 Codex OAuth 配置；后续在同一会话中执行 codex 会使用该登录配置与默认模型。

上传项目并进入终端

sandbox exec 提供交互终端。--copy 在连接前上传项目，--mode tmux 创建或接入与会话 ID 同名的持久终端。

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

按 Ctrl-] 脱离终端；再次运行 agentkit sandbox exec --tool-name dev-sandbox --session-id dev --mode tmux 可返回该会话，避免重复上传覆盖远端文件。若已在 .agentkit/sandbox.yaml 中保存工具名称，后续可省略 --tool-name。

传输文件

会话建立后，用 sandbox scp 在本地和沙箱之间复制文件或目录。远端路径以 sandbox: 开头。

# 上传
agentkit sandbox scp ./local.txt sandbox:/home/gem/my-app/local.txt --session-id dev

# 下载
agentkit sandbox scp sandbox:/home/gem/my-app/result.json ./result.json --session-id dev

打开 Web 预览

在持久终端中启动 Web 服务，例如监听沙箱内的 127.0.0.1:3000。以下命令打开沙箱浏览器界面，初始页面是会话文件目录：

agentkit sandbox web --tool-name dev-sandbox --session-id dev

打开后，在沙箱浏览器中访问服务地址 http://127.0.0.1:3000。此地址属于远程沙箱，不能直接在本机浏览器中访问；sandbox web 返回的是沙箱浏览器界面地址，不会自动把应用端口发布为公网 URL在不希望自动打开浏览器的环境中加 --no-open，命令只返回界面 URL

清理资源

先确认所需文件已下载。只删除开发会话时同时指定工具与会话；不再使用工具时省略会话 ID，删除整个工具。

# 删除会话
agentkit sandbox delete --tool-name dev-sandbox --session-id dev --force

# 删除工具及其资源
agentkit sandbox delete --tool-name dev-sandbox --force

脚本化执行

sandbox shell 在会话中执行单条非交互命令并输出 JSON，适合脚本调用：

agentkit sandbox shell \
  --tool-name dev-sandbox \
  --session-id dev \
  --command "cd /home/gem/my-app && npm test"

需要编排多条 sandbox exec 任务时，将条目写入 agentkit-sandbox-run.yaml，再运行 agentkit sandbox run --config agentkit-sandbox-run.yaml。配置格式见沙箱命令参考。

实践建议

以固定的 --session-id 复用开发环境；使用 agentkit sandbox list 查看本地缓存的会话。
项目中存在多个工具时，显式传入 --tool-id 或 --tool-name，避免连接到错误环境。
长时间运行的交互任务使用 sandbox exec --mode tmux，并定期把重要结果下载到本地或持久存储。
不再使用会话或工具时及时删除，避免继续占用云端资源。

开始使用

AI-Friendly

命令参考

端到端流程

脚本化执行

实践建议

​端到端流程

​脚本化执行

​实践建议

端到端流程

脚本化执行

实践建议