codex-agent

v1.0.0

Published

5 months ago

> Codex Agent 是对 OpenAI Codex CLI 的“守护与编排层”，补齐持续任务调度、异常自愈与多渠道通知能力，让 `codex exec --json` 可以安全地长时间运行并在断连后自动恢复。

0High
0Medium
0Low

aleonchen

Codex Agent

Codex Agent 是对 OpenAI Codex CLI 的“守护与编排层”，补齐持续任务调度、异常自愈与多渠道通知能力，让 codex exec --json 可以安全地长时间运行并在断连后自动恢复。

Why Codex Agent?

持续运行：封装 codex exec 与 codex exec resume，自动追踪 session ID、cwd 与最近一次事件。
状态感知：解析 JSONL 事件流，将 thread.started、turn.*、item.completed 等事件映射到统一的任务状态机。
自愈能力：捕捉 stream disconnected / Transport error 并基于指数退避策略自动重试。
多渠道通知：桌面通知、Slack Webhook、任意 HTTP Webhook 实时同步任务状态，并可附带“继续 / 重试 / 终止”等操作按钮。
易配置：支持环境变量或 codex-agent.json 配置文件，复用 Codex CLI 的 sandbox 与 approval 机制。

Quick Start

安装依赖（推荐 Node.js ≥ 20）：
```
npm install
```
如果希望直接使用 hi-codex 全局命令，可执行 npm link 或在目标环境 npm install -g。
构建 TypeScript：
```
npm run build
```
启动交互式会话（可选初始任务描述）：
```
npx hi-codex "Implement integration tests for payment flow"
```
未提供初始提示时，程序会立即进入多轮模式，提示你输入第一条消息；使用 /quit 可随时退出。

续跑最近一次 Codex 任务：

npx hi-codex --resume --followup "继续修复剩余失败的测试"

多轮对话指令：

任意输入：作为下一轮提示发送给 Codex。
/status：查看当前 session ID、状态与累计轮数。
/quit：退出会话，保持 miruns/ 中的历史记录以便稍后恢复。
--session <uuid>：显式指定 Codex session UUID，未提供 follow-up 时只回显最后一条 Agent 回复并等待你继续。可与 --resume 组合。

配置 codexHistory codex-agent.json 中新增 codexHistory.events 与 codexHistory.turns：

{
  "codexHistory": {
    "events": 200,
    "turns": 10,
  },
}

events 控制从 Codex 原生 jsonl 导入的最大事件数；
turns 控制构建对话摘要时保留的回合数量；
仍可通过 CODEX_AGENT_HISTORY_EVENTS / CODEX_AGENT_HISTORY_TURNS 环境变量覆盖。

开发模式：npm run hi -- "<goal>" 会以 TS Loader 启动；或使用 npm run dev 直接运行 src/index.ts。

Configuration

Codex Agent 在启动时合并以下来源（后者覆盖前者）：

默认参数（src/config/index.ts）
环境变量
当前工作目录下的配置文件（按顺序尝试）：
- codex-agent.json
- codex-agent.config.json
- config/codex-agent.json

配置示例（`codex-agent.json`）

{
  "codexBin": "codex",
  "silenceTimeoutMs": 90000,
  "retry": {
    "retries": 5,
    "factor": 2,
    "minTimeoutMs": 5000,
    "maxTimeoutMs": 120000,
  },
  "notify": {
    "desktop": true,
    "slackWebhookUrl": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
    "webhookUrl": "https://example.com/codex/events",
  },
  "workspaceRoot": ".",
  "mirunsDir": "./miruns",
}

若希望完全通过环境变量配置，可使用 CODEX_BIN、CODEX_SLACK_WEBHOOK_URL、CODEX_NOTIFY_DESKTOP=false 等变量覆盖默认值。

Task Lifecycle

| 状态 | 触发条件 | 默认动作 | | ------------------- | ------------------------------------------------- | ----------------------------------- | | RUNNING | 收到 thread.started / turn.started 或其他事件 | 重置静默计时器 | | WAITING | 连续 silenceTimeout 内未收到新事件 | 发送“等待输入/批准”通知，可手动继续 | | RETRYABLE_NETWORK | 标准输出/错误匹配到网络异常 | 触发指数退避重试 | | ERROR | turn.failed 或进程非零退出 | 发送错误通知，停止计时器 | | COMPLETE | turn.completed | 发送完成通知并归档任务 |

会话元信息以 JSON 形式持久化在 miruns/ 目录，便于下次恢复或进行外部分析。

Notification Channels

DesktopNotifier：使用 node-notifier 推送原生桌面通知。
SlackNotifier：通过 Block Kit 消息推送状态信息，并为每个动作按钮附加 URL。
WebhookNotifier：向任意 HTTP Endpoint 推送完整的 NotificationPayload JSON。

所有通道通过 CompositeNotifier 聚合，并行发送且互不影响。

Architecture

┌───────────────────────────────┐
│        Slack / Webhook UI      │
│ (消息 + 按钮 → HTTP Action)    │
└──────────────┬────────────────┘
               │
        HTTP Actions / Alerts
┌──────────────▼────────────────┐
│ Codex Agent Supervisor (Node) │
│ - 状态机 / 重试 / 持久化       │
│ - 解析 codex --json 事件流    │
│ - 调用 codex exec / resume    │
└──────────────┬────────────────┘
               │
        CLI Process Control
┌──────────────▼────────────────┐
│       OpenAI Codex CLI         │
│  --json 事件流 + sandbox / MCP │
└───────────────────────────────┘

Project Layout

├── bin/hi-codex.ts        # CLI 入口，解析命令行参数
├── src/index.ts           # 包入口导出
├── src/supervisor.ts      # 核心控制器：状态机 + 重试 + 通知
├── src/config/            # 配置加载与 fallback
├── src/events/            # JSONL 事件解析
├── src/state/             # TaskStateMachine 实现
├── src/runner/            # codex 子进程启动 & 会话存储
├── src/notifier/          # Slack / Webhook / Desktop 通知
├── src/utils/             # 日志工具
└── miruns/                # 历史会话快照

Development Notes

npm run build 生成 dist/，供 bin/hi-codex 与库消费者使用。
npm run dev 直接执行 TypeScript 源码（通过 ts-node loader）。
npm run hi -- --resume 可在开发期模拟断点恢复流。

Roadmap Ideas

集成 Slack 交互式按钮回调 → Supervisor HTTP API。
增加健康检查 / Prometheus 指标导出。
引入可视化控制面板管理 miruns 历史任务。

欢迎 Issue / PR 共建，让 Codex Agent 支持更多自动化场景。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme