OpenAI DigitalOcean 沙箱

完整实现见Cookbook的应用管理与Webhook管理示例。

工作方式

DigitalOcean Managed Agents Runtime Services（M.A.R.S.）使用 codex-agentapi 镜像启动Firecracker微型虚拟机。镜像包含Codex，并启动向Agents API建立出站连接的执行器。

选择 Webhook管理，由OpenAI事件启动或恢复沙箱；或选 应用管理，由应用直接控制。交互式入门可用下文 DigitalOcean CLI。连接与恢复行为见沙箱生命周期。

DigitalOcean Managed Agents目前为公开预览，访问与配置见提供商文档。

开始之前

需要启用沙箱且可用 codex-agentapi 的DigitalOcean账户，以及有Agents API权限的OpenAI项目。

应用或CLI使用 OPENAI_API_KEY；OPENAI_EXECUTOR_API_KEY 使用环境密钥，只把后者作为 CODEX_API_KEY 传入沙箱。

Webhook控制器或Python应用需设置 DIGITALOCEAN_TOKEN，安装支持异步的 PyDo SDK 0.41.0或以上版本（pydo[aio]）。Agents API请求用 OpenAI SDK。只有CLI路径需要安装CLI。

Webhook 管理

保存智能体，保存 OPENAI_AGENT_ID。在DigitalOcean App Platform部署HTTPS控制器，配置该ID、读取会话用的 OPENAI_API_KEY、DIGITALOCEAN_TOKEN 和 OPENAI_EXECUTOR_API_KEY。
在OpenAI项目注册 /webhook 端点，启用 agent.session.action_required 与 agent.session.failed，保存签名秘密为 OPENAI_WEBHOOK_SECRET 并重新部署。
用同一 OPENAI_AGENT_ID 和工作目录 /workspace 按会话步骤打开流、发送输入。environment_connection 请求到达时，控制器验证签名、读取当前会话，检查智能体ID和所需动作，再查询DigitalOcean中的 mars-{session_id}，恢复暂停沙箱，或在没有活动沙箱时创建。
收到 agent.session.failed 后再次读取会话，仅在当前仍为 failed 时删除沙箱。

镜像连接执行器，应用负责Agents API输入与结果流，控制器负责资源创建及重连。每个会话的资源操作要串行化，处理重复和并发投递。控制器要求见Webhook管理生命周期。

用 DigitalOcean CLI 试用

CLI同时创建两类资源，允许终端交互，直接创建沙箱，不使用webhook控制器。

安装含 harness-runtime 的 doctl 1.170.0或以上版本，并认证：

来源示例 1（bash）：

## [中文] 示例 1：用 DigitalOcean CLI 试用。
## [中文] 通过 doctl 的交互认证保存 DigitalOcean 访问配置；这是提供商认证，不是创建 OpenAI 会话。
doctl auth init

将以下清单保存为 environment.yaml：

来源示例 2（yaml）：

## [中文] 示例 2：用 DigitalOcean CLI 试用。
## [中文] 这是提供商环境清单；变量由部署工具展开，展开后的凭证不应写入日志或版本控制。
name: openai-codex-session
agent: codex-agentapi
config:
  agent:
    model: gpt-6.1-sol
    instructions: Work from the files in /workspace.
  environment:
    type: self_hosted
    workspace_directory: /workspace
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

config 是OpenAI创建会话请求。CLI用 OPENAI_API_KEY 认证，将响应值填入 ${ENV_ID}，只把环境密钥传入沙箱。不要把变量展开后的清单写入日志或版本控制。工具需要的目标地址加入 egress。

创建会话和沙箱：

来源示例 3（bash）：

## [中文] 示例 3：用 DigitalOcean CLI 试用。
## [中文] 根据 environment.yaml 清单创建会话与沙箱，记录两类 ID；CLI 默认最多等300秒就绪。
doctl harness-runtime create --spec environment.yaml

默认最多等待300秒就绪。从详情保存OpenAI会话ID和DigitalOcean会话ID，再附加：

来源示例 4（bash）：

## [中文] 示例 4：用 DigitalOcean CLI 试用。
## [中文] 附加到已命名的 DigitalOcean 运行会话进行终端交互；Ctrl+D 断开不会删除资源。
doctl harness-runtime launch openai-codex-session

让智能体向 /workspace/hello.txt 写入 hello 并读回。按 Ctrl+D 断开终端但不删除会话，用相同 launch 命令重新附加。结束按清理操作。

应用管理

应用负责创建两类资源时，先创建OpenAI会话：

来源示例 5（javascript）：

程序文字说明6：你是乐于助人的编码助手，编写清晰代码并验证其可用性。

程序文字说明7：这段拼接字符串构成编码助手指令：编写清晰代码并验证其可用性。

// [中文] 示例 5：应用管理。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "You are a helpful coding assistant. Write clean code and verify that it works.",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

console.log(session);

来源示例 6（python）：

沿用程序文字说明6。

沿用程序文字说明7。

## [中文] 示例 6：应用管理。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "You are a helpful coding assistant. Write clean code and verify that it works.",
    },
    environment={"type": "self_hosted", "workspace_directory": "/workspace"},
)
print(session.to_json())

来源示例 7（go）：

沿用程序文字说明6。

沿用程序文字说明7。

// [中文] 示例 7：应用管理。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
    openai.BetaAgentSessionNewParams{
        Agent: openai.BetaAgentSessionNewParamsAgent{
            Model:        openai.String("gpt-6-astra"),
            Instructions: openai.String("You are a helpful coding assistant. Write clean code and verify that it works."),
        },
        Environment: openai.EnvironmentParamUnion{
            OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace"},
        },
    })
if err != nil {
    panic(err)
}
fmt.Println(result)

来源示例 8（java）：

沿用程序文字说明7。

// [中文] 示例 8：应用管理。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "You are a helpful coding assistant. Write clean code and verify"
                                + " that it works.")
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .build())
                .build());
System.out.println(result);

来源示例 9（ruby）：

沿用程序文字说明6。

沿用程序文字说明7。

## [中文] 示例 9：应用管理。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "You are a helpful coding assistant. Write clean code and verify that it works."
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace"
  }
)
puts result

按连接指南保存 session.id 和环境ID。智能体配置已经发给OpenAI，以下仅含沙箱配置，保存为 sandbox.yaml：

来源示例 10（yaml）：

## [中文] 示例 10：应用管理。
## [中文] 这是提供商环境清单；变量由部署工具展开，展开后的凭证不应写入日志或版本控制。
agent: codex-agentapi
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

用 DIGITALOCEAN_TOKEN 创建 pydo.aio.Client，调用 client.agents.create_session。params.openai_session_id 使用OpenAI会话ID，body.manifest 为清单内容，body.variables 提供 ENV_ID 与 OPENAI_EXECUTOR_API_KEY，保存返回的DigitalOcean session_id。
打开事件流并提交输入，要求写入并读取 /workspace/hello.txt。输入等待执行器连接。确认连接事件与轮次完成，并检查输出有无工具失败。
使用相对路径 hello.txt 调用 workspace_download 下载。可保留两类资源供后续轮次使用，也可清理。

初始化与执行使用有限超时，应用处理连接失败。应用或CLI直接管理的会话，不再配置另一个资源创建webhook处理器。

清理

先保存文件，再删除OpenAI会话和销毁DigitalOcean沙箱。删除会话不发webhook，必须执行两项清理，并报告失败。

PyDo使用DigitalOcean会话ID调用 client.agents.destroy_session；CLI可提供该ID或沙箱名称：

来源示例 11（bash）：

## [中文] 示例 11：清理。
## [中文] 移除指定 DigitalOcean 沙箱；OpenAI 会话须另行删除，操作前先取回文件。
doctl harness-runtime remove openai-codex-session

删除webhook控制器前，先移除OpenAI侧注册。

OpenAI DigitalOcean 沙箱

工作方式

开始之前

Webhook 管理

用 DigitalOcean CLI 试用

应用管理

清理

参考