English | 中文

Codex Auto Runner

当 Codex 的 5h 限额恢复时，自动开启正在进行中的目标任务；在不浪费任何一个恢复窗口的前提下，持续推进，直至任务完成、需要人工介入，或周额度被充分消耗。

Codex Auto Runner 是一个运行在本地的 Codex 目标任务恢复器。它为一个非常具体、也非常真实的痛点而生：长任务跑到一半，5h 额度耗尽；上下文还在，目标还在，任务还没结束，但下一次额度恢复时，人不一定守在电脑前。

它要解决的不是“如何绕过限制”，而是“如何不浪费已经恢复的额度”。

你只需要在 Codex 里设定好目标。Codex Auto Runner 会识别当前会话、检测目标模式、记录任务状态、等待额度恢复、二次确认额度确实可用，然后恢复同一个 Codex 线程，重新激活正在进行的目标，让 Codex 继续沿着原上下文往前推进。

换句话说，它把 Codex 的 5h 恢复窗口变成了一次次自动接力：额度恢复，任务继续；再次耗尽，再次等待；直到周额度被用到极致，或者目标真正抵达终点。

这是一个非官方的本地工具，不属于 OpenAI 官方产品，也不会突破、规避或修改任何额度规则。它只是让你已经拥有的额度更有秩序、更少空转、更接近连续生产力。

立即判断是否适合你

适合：

• 你经常让 Codex 做跨小时的迁移、修复、审查或生成任务。
• 你已经会使用 Codex 目标模式，并希望恢复窗口到来时自动续跑同一个线程。
• 你接受工具只在本机运行，并且遇到登录、额度未知、审批或验证失败时停止。

不适合：

• 你想绕过、扩容或修改 Codex 额度规则。
• 你希望工具自动接受高风险权限、自动 push 或自动部署。
• 你不使用 Windows Codex Desktop。

如果这个项目正好解决你的长任务续跑痛点，欢迎给仓库点 star，让其他 Codex 重度用户更容易发现它。

核心愿景

Codex 的强大之处在于上下文、目标和持续推理。真正昂贵的不是等待本身，而是等待之后没人接住任务。

Codex Auto Runner 让长任务拥有“跨额度窗口继续推进”的能力：

1. Codex 正在执行一个目标任务。
2. 5h 额度耗尽，任务进入等待。
3. 本地守护进程记录当前线程、目标和任务状态。
4. 到达恢复时间后，系统重新读取真实额度，而不是盲目启动。
5. 额度确认可用后，恢复原 Codex 线程。
6. 如果目标因为额度限制暂停，自动恢复为 active。
7. 向 Codex 发送最小必要继续指令：

继续，并开启当前正在进行的目标任务

8. Codex 读取原上下文继续推进。
9. 循环往复，直到周额度耗尽、任务完成，或遇到需要用户判断的情况。

这就是它的中心承诺：不新开空会话，不丢失上下文，不让恢复后的 5h 窗口沉默过去。

适合什么场景

• 大型代码迁移、跨模块重构、复杂 Bug 排查。
• 需要 Codex 连续多轮推进的产品功能实现。
• 晚上、工作间隙、离开电脑后仍希望任务在额度恢复时自动继续。
• 目标模式已经设置清楚，希望 Codex 按原目标持续执行。
• 希望把 5h 窗口和周额度当成可调度资源，而不是手动盯守的倒计时。

主要能力

• 5h 限额恢复监测：读取 Codex 真实额度桶，按真实 reset 时间安排唤醒。
• 周额度持续推进：支持“直到周额度耗尽”模式，让任务跨多个 5h 窗口继续运行。
• 目标模式识别：自动发现 Codex 会话，识别哪些会话已开启目标模式；未设置目标的会话无法创建自动任务。
• 自动恢复 active 目标：目标因暂停、受限或额度耗尽停住时，可在恢复运行前重新设为 active。
• 原线程续跑：恢复同一个 Codex thread，让模型读取原上下文继续，而不是新开一个空会话。
• 充值/重置额度续跑：用户开启后，可在周额度耗尽且有可用重置次数时继续任务。
• 自动版 + 专业版：自动版面向一键接管目标会话；专业版保留优先级、沙箱、审批、验证命令等高级配置。
• 额度概览：展示 5h 与 1 周窗口、剩余额度、刷新时间、任务状态。
• 本地 Web UI：Vite + React 前端，提供中英文切换与接近 Codex 风格的界面。
• 本地守护进程：调度器、HTTP API、SQLite 状态、任务队列都运行在本机。

运行闭环

flowchart LR
  A[Codex 目标会话] --> B[5h 额度耗尽]
  B --> C[任务进入 WAITING_QUOTA]
  C --> D[等待真实恢复时间]
  D --> E[二次确认额度可用]
  E --> F[恢复同一 Codex 线程]
  F --> G[必要时恢复目标为 active]
  G --> H[继续当前目标任务]
  H --> I{完成 / 需要人工 / 周额度耗尽?}
  I -- 继续推进 --> B
  I -- 停止 --> J[完成或等待用户处理]

Loading

调度器不会只因为时间到了就贸然执行。它会在恢复点重新读取额度，并经过抖动后的二次验证，确认额度确实从 exhausted 变为 available 或 near_limit 后才启动任务。

项目结构

codex-auto-runner/
  apps/
    daemon/               本地守护进程、额度监测、调度器、HTTP API
    web/                  Vite + React 前端
    cli/                  car 命令行工具
  packages/
    app-server-client/    Codex app-server JSON-RPC 客户端
    codex-resolver/       自动探测并暂存 Codex 可执行文件
    quota-engine/         额度桶解析、阻塞判定、恢复时间计算
    persistence/          SQLite 任务、事件、锁与状态机
    task-engine/          thread resume/start、目标激活、turn 生命周期
    validator/            验证命令执行器
    git-guard/            任务运行前的仓库安全检查
    logger/               结构化日志与敏感字段脱敏
    shared-types/         共享配置与领域类型
  schemas/
    generated/            Codex app-server 协议 schema
  tools/
    protocol-probe/       账号与额度协议探针
    thread-turn-probe/    线程与回合协议探针

环境要求

• Windows + Codex Desktop。
• Node.js 20 或更高版本。
• pnpm 9 或更高版本。
• 可用的 Codex 账号额度。

当前实现优先面向 Windows Codex Desktop 环境。其他平台后续可以扩展，但不是当前主要验证目标。

快速开始

pnpm install
pnpm doctor
pnpm --filter @car/daemon start
pnpm web

打开本地前端：

http://127.0.0.1:5173/

pnpm doctor 会在当前机器上自动查找 Codex，并确认可执行文件可以运行。它不会把真实本机路径写入仓库，也不会读取或上传用户的账号凭据。

Codex 自动发现顺序

下载者不需要改代码绑定自己的 Codex 路径。运行时会按以下顺序解析 Codex：

1. CAR_CODEX_EXEC：用户显式指定的 codex 可执行文件。
2. %LOCALAPPDATA%\CodexAutoRunner\codex-portable\codex.exe：本机已经暂存过的副本。
3. PATH 中的 codex。
4. Windows Codex Desktop：通过 Get-AppxPackage -Name OpenAI.Codex 免提权发现 MSIX 安装位置，并把运行所需文件复制到用户本机的 %LOCALAPPDATA%\CodexAutoRunner\codex-portable\。

因此，GitHub 仓库里不会保存某一台电脑的 %USERPROFILE% 真实路径，也不会绑定作者机器上的 Codex 安装目录。每个用户首次运行时都会在自己的机器上重新解析。

常用命令

pnpm car status
pnpm car quota
pnpm car task list
pnpm car task run-now <task-id>
pnpm car task pause <task-id>
pnpm car task resume <task-id>
pnpm schema:gen
pnpm probe
pnpm probe:turn
pnpm doctor
pnpm privacy:check
pnpm typecheck
pnpm test

安全边界

• daemon 只监听 127.0.0.1。
• 本地 HTTP API 使用随机 token 鉴权。
• .env、日志、数据库、构建产物、探针转储、本机运行数据不会进入 Git。
• api.json、car-api.token、runner.db、status.json、events.jsonl 等运行文件只在用户本机生成，并已被 .gitignore 排除。
• Codex 可执行路径只在运行时解析；日志和诊断输出会把 %LOCALAPPDATA%、%USERPROFILE% 等本机路径脱敏。
• 日志会脱敏 token、authorization、secret、account_id 等字段。
• 不自动 push、不自动部署、不替用户接受高风险审批。
• Codex 网络访问需要显式开启，默认关闭。
• 当额度未知、需要登录、项目被锁定、验证失败或任务需要人工判断时，调度器会停止自动推进。

发布前可以运行：

pnpm privacy:check

该命令会扫描仓库文件，发现真实用户路径、Codex 私有会话路径、常见 API Key、GitHub token、Bearer token 或本地运行文件名时直接失败，避免把个人信息误提交到公开仓库。

开发检查

pnpm --filter @car/web build
pnpm --filter @car/daemon typecheck
pnpm test

参与贡献

适合贡献的方向：

• 新平台的 Codex 发现逻辑。
• 更稳健的额度桶解析和恢复时间判断。
• 更清楚的安全边界、日志脱敏和隐私检查。
• UI 可用性、可访问性和中英文文案。
• 可复现的 bug 报告和真实长任务使用反馈。

提交前请运行：

pnpm privacy:check
pnpm typecheck
pnpm test

更多说明见 CONTRIBUTING.md。

当前状态

项目已经具备核心闭环：

• Codex app-server 连接与额度读取。
• 5h 与 1 周额度桶解析。
• 额度恢复点调度与二次验证。
• Codex 会话发现与目标模式检测。
• 原线程续跑与目标 active 恢复。
• 自动版任务创建与专业版任务配置。
• 本地额度仪表盘与中英文界面。
• 周额度耗尽后的重置次数续跑选项。

Codex Auto Runner 的目标很明确：当 Codex 可以继续时，任务不应该还在等待人回来按下按钮。