本指南遵循 Oracle 的测试版 Python 示例，采用 由应用管理资源配置的方式：您的应用负责创建和删除 Agents API 会话及 OCI 沙盒。
请参阅 OpenAI Cookbook 中的由应用管理资源的示例。
有关资源配置模式和连接行为，请参阅沙盒生命周期。
OCI GenAI 沙盒目前处于测试阶段。请联系您的 Oracle 客户经理，为您的账户申请访问权限。
开始之前
创建一个已启用沙盒的 Generative AI 项目。授予您的 OCI 身份管理该项目所在区间内的项目和沙盒的权限。替换以下 IAM 策略中的占位符：
allow group <group-name> to manage generative-ai-sandbox in compartment <compartment-name>
allow group <group-name> to manage generative-ai-project in compartment <compartment-name>使用包含 Node.js 和 npm 的沙盒运行时。Oracle 的示例默认请求 python-3.11；如果该运行时不包含 npm，请选择兼容的自定义运行时。
如果您的项目限制出站流量，请允许通过 HTTPS 访问 registry.npmjs.org 以安装 Codex，允许通过 HTTPS 访问 api.openai.com，并允许与 codex-cloud-environments.chatgpt.com 建立安全 WebSocket 连接。请参阅执行器网络访问。
1. 安装 OCI CLI 和测试版 SDK
创建虚拟环境并安装 OCI CLI：
uv venv --python 3.14
source .venv/bin/activate
uv pip install --upgrade oci-cli然后安装 Oracle 在接入过程中提供的测试版 Python SDK：
uv pip install "/path/to/oci-<beta-version>-py3-none-any.whl"请在安装 CLI 之后 安装测试版 SDK。此后安装或升级 oci-cli 可能会将测试版 SDK 替换为 PyPI 上的 oci 包；如果发生这种情况，请重新安装测试版 wheel 包。测试版 SDK 必须包含 oci.generative_ai_sandbox。
2. 配置 OCI 环境
在您的账户已启用的区域中，对安全令牌配置方案进行身份验证：
oci session authenticate --profile-name Sandbox --region us-chicago-1设置项目 OCID 和 OpenAI 凭据，但不要将其提交到代码仓库：
export OCI_SANDBOX_PROJECT_ID="ocid1.generativeaiproject..."
export OPENAI_API_KEY="..."
export OPENAI_EXECUTOR_API_KEY="..."使用 OPENAI_API_KEY 发起应用程序请求。将 OPENAI_EXECUTOR_API_KEY 设置为环境密钥，并仅将该密钥作为 CODEX_API_KEY 传入沙盒。
Oracle 的示例读取 Sandbox 配置方案，并使用 us-chicago-1。如需覆盖默认设置：
export OCI_SANDBOX_PROFILE="my-profile"
export OCI_SANDBOX_REGION="us-chicago-1"该示例还支持以下可选设置：
| 设置 | 默认值 |
|---|---|
OCI_SANDBOX_ENDPOINT | https://inference.generativeai.<region>.oci.oraclecloud.com |
OCI_SANDBOX_RUNTIME | python-3.11 |
OCI_SANDBOX_SHAPE | SMALL |
OCI_SANDBOX_EXPIRATION | PT30M（30 分钟） |
配置您自己的应用时，请将配置方案中的安全令牌和私钥与 oci.auth.signers.SecurityTokenSigner 配合使用。使用 oci.generative_ai_sandbox 中的 GenerativeAiSandboxClient，按所选区域和端点创建沙盒客户端。
3. 运行由应用管理的会话
有关 Agents API 请求和执行器启动命令，请参阅自托管连接指南。按照与 Oracle 示例相同的流程操作：
- 创建一个自托管的 Agents API 会话，将
/workspace设为其工作目录。保存会话 ID 和环境 ID。 - 创建 OCI GenAI 沙盒，并等待其进入
RUNNING状态。 - 安装 Codex，并将
/workspace/brief.txt写入沙盒。 - 使用会话的环境 ID 和环境密钥启动
codex exec-server。 - 打开会话事件流，然后发送输入，要求智能体将
brief.txt转化为迁移计划。等待任务完成，然后读取生成的/workspace/plan.md。 - 停止并删除 OCI 沙盒，然后删除 Agents API 会话。即使其中一项清理操作失败，也要尝试执行另一项。
保留这两项资源以供后续轮次使用，并在删除沙盒之前取回文件。请使用 Oracle 指定的测试版 SDK 版本；预览版本可能会更改沙盒 API 的名称。