Codex 引擎

Codex 引擎调用 OpenAI 的 codex CLI（@openai/codex），使用 OpenAI 模型自主完成任务。

前置条件

• 安装 Codex：npm install -g @openai/codex
• 认证（二选一）：
  • ChatGPT OAuth — codex login（适用于 ChatGPT Plus/Pro/Team/Enterprise 订阅者）
  • API Key — 设置 OPENAI_API_KEY 环境变量

配置

# golem.yaml
name: my-bot
engine: codex
# model: o4-mini   # 可选；使用 ChatGPT OAuth 时请省略

认证

Codex 支持两种认证方式：

ChatGPT OAuth（浏览器登录）

适用于 ChatGPT Plus / Pro / Team / Enterprise 订阅者：

codex login    # 打开浏览器；凭据存储在 ~/.codex/auth.json

GolemBot 会自动使用存储的凭据，无需额外配置。

模型兼容性： codex-mini-latest 仅在 API Key 模式下可用。使用 ChatGPT OAuth 时，请在 golem.yaml 中不设置 model，让 Codex 根据你的订阅方案自动选择合适的模型。

API Key

适用于 CI/CD、脚本或程序化访问：

export CODEX_API_KEY=sk-...          # Codex CLI 官方 CI 文档指定的主要环境变量
# OPENAI_API_KEY 同样被接受，兼容旧版本

# 或预先使用 key 登录（存储在 ~/.codex/auth.json）：
printenv CODEX_API_KEY | codex login --with-api-key

通过 createAssistant() 或 golem.yaml 传入：

const bot = createAssistant({ dir: './my-bot', apiKey: process.env.CODEX_API_KEY })

选择模型

查看可用模型：

codex models

常用模型（API Key 模式）：

模型	说明
5.3-codex	最新全尺寸 Codex 模型（2026 年 2 月起对 API 用户可见）
codex-mini-latest	快速、低成本编程模型（基于 o4-mini）
codex-1	基于 o3 的初始版本模型

运行时覆盖 — 通过 createAssistant() 传入 model：

const bot = createAssistant({ dir: './my-bot', model: 'o4-mini' })

工作原理

CLI 调用

GolemBot 以无头模式调用 Codex CLI：

# 新会话
codex exec --json --full-auto --skip-git-repo-check "<prompt>"

# 恢复会话
codex exec resume --json --full-auto --skip-git-repo-check <thread_id> "<prompt>"

使用的参数：

参数	用途
--json	NDJSON 输出，流式解析所必需
--full-auto	禁用交互式权限提示，无头操作必须使用
--skip-git-repo-check	允许在 Git 仓库外运行（临时目录、CI 工作区）
--model <name>	覆盖模型（仅 API Key 模式）

技能注入

Codex 通过 workspace 根目录的 AGENTS.md 发现技能。GolemBot 会从 skills/ 目录自动生成该文件，无需额外配置。

my-bot/
├── AGENTS.md          # 自动生成，包含所有技能描述
└── skills/
    ├── general/
    └── im-adapter/

输出解析

Codex 以 NDJSON 格式（--json）输出。解析器处理以下事件：

事件	处理方式
thread.started	捕获 thread_id 用于会话恢复（不转发给消费者）
item.completed（agent_message）	触发 text 事件
item.completed（command_execution）	触发 tool_call + tool_result 事件
turn.completed	触发携带 sessionId = thread_id 的 done 事件
turn.failed	触发 error 事件
顶层 error	WebSocket 重连通知被静默过滤；其他错误触发 warning 事件

会话恢复

thread.started 中的 thread_id 将作为 sessionId。下次对话时 GolemBot 调用：

codex exec resume --json --full-auto --skip-git-repo-check <thread_id> "<prompt>"

resume 子命令继承所有参数并恢复既有的会话上下文。

注意事项

• Codex Cloud 任务仅在 ChatGPT OAuth 模式下可用，API Key 模式不支持
• 与其他引擎不同，Codex 的 done 事件不包含费用/Token 统计
• 技能通过 workspace 根目录的 AGENTS.md 发现（与 Claude Code 使用同一文件）