概述

codex 是预构建的 AI Agents 运行环境，已内置 OpenAI Codex CLI，可在隔离的沙箱环境中以无头方式自动生成、修改和执行代码，具备完整的文件系统、终端和 git 访问能力。

模板预装 Node.js、git、ripgrep、vim、GitHub CLI 等常用工具，以及 pnpm/tsx/vite 前端脚手架。镜像内不内置任何 API key，认证信息通过沙箱创建时的 envs 注入或通过密钥注入规则下发。

模板内容

创建沙箱

通过 envs 传入 OPENAI_API_KEY：

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('codex', {
  envs: { OPENAI_API_KEY: process.env.OPENAI_API_KEY },
})

常用 CLI flag

无头执行

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('codex', {
  envs: { OPENAI_API_KEY: process.env.OPENAI_API_KEY },
})

const result = await sandbox.commands.run(
  `codex exec --full-auto --skip-git-repo-check "Create a hello world HTTP server in Go"`,
)

console.log(result.stdout)
await sandbox.kill()

Git 仓库集成

await sandbox.git.clone('https://github.com/your-org/your-repo.git', {
  path: '/home/user/repo',
  username: 'x-access-token',
  password: process.env.GITHUB_TOKEN,
  depth: 1,
})

const result = await sandbox.commands.run(
  `codex exec --full-auto --skip-git-repo-check -C /home/user/repo "Add error handling to all API endpoints"`,
)

const diff = await sandbox.commands.run('cd /home/user/repo && git diff')
console.log(diff.stdout)

流式事件

--json 会按行输出结构化事件，便于程序消费：

const result = await sandbox.commands.run(
  `codex exec --full-auto --skip-git-repo-check --json -C /home/user/repo "Refactor the utils package"`,
  {
    onStdout: (data) => {
      for (const line of data.split('\n').filter(Boolean)) {
        const event = JSON.parse(line)
        console.log(`[${event.type}]`, event)
      }
    },
  },
)

Schema 约束输出

将期望输出结构写成 JSON Schema 文件，再通过 --output-schema 传给 CLI，可获得稳定的结构化结果：

await sandbox.files.write(
  '/home/user/schema.json',
  JSON.stringify({
    type: 'object',
    properties: {
      issues: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            file: { type: 'string' },
            severity: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
          },
          required: ['file', 'severity'],
        },
      },
    },
    required: ['issues'],
  }),
)

const result = await sandbox.commands.run(
  `codex exec --full-auto --skip-git-repo-check --output-schema /home/user/schema.json -C /home/user/repo "List all security issues"`,
)

图像输入

将 mockup 上传到沙箱，通过 --image 让 Codex 把视觉稿落地为代码：

import fs from 'node:fs'

await sandbox.files.write('/home/user/mockup.png', fs.readFileSync('./mockup.png'))

const result = await sandbox.commands.run(
  `codex exec --full-auto --skip-git-repo-check --image /home/user/mockup.png -C /home/user/repo "Implement this UI design as React"`,
)

配合密钥注入使用

如需让真实 OPENAI_API_KEY 留在平台侧，可创建类型为 openai 的注入规则（参见密钥注入），沙箱内仅传入占位符：

const sandbox = await Sandbox.create('codex', {
  envs: { OPENAI_API_KEY: 'placeholder' },
  injections: [{ id: '<rule-id>' }],
})

如需指向 OpenAI 兼容的第三方网关，请在注入规则中显式设置 base_url。

参考

• Codex CLI 项目主页：https://github.com/openai/codex