在 VSCode 里用 Codex 跑任务时,不用一直盯着屏幕。
后台常驻,监控本地 Codex 的运行状态,通过飞书(或本地控制台)把任务完成、额度告警、网络故障推给你。
当前版本仅支持 飞书 与 控制台 两种通道;微信 iLink 暂不兼容。
| 场景 | 级别 | |
|---|---|---|
| ✅ | 任务完成 —— 按项目聚合,带摘要(受 aggregate 节流) |
info |
| 🚨 | 任务被中断 —— 立即推送 | alert |
| 📊 | 额度告警 —— 80%(默认关)/ 95% / 耗尽 100% | warn / critical / alert |
| 🔄 | 额度重置 —— 5 小时 / 7 天窗口 | info |
| 📶 | 网络异常 —— 代理未运行 / 代理节点故障 / 整体断网 | alert |
| ✅ | 网络恢复 —— 连续 2 次探测正常 | info |
- ✅ 可运行:
npm start启动常驻进程(Node ≥ 26) - ✅ 推送通道:飞书企业自建应用、控制台;iLink 暂不实现(
channel: "ilink"会明确报错) - ✅ 单文件打包:
npm run build:exe产出dist-exe/CodexMonitor.exe(Node SEA,约 105 MB) - ✅ 工作时间段:默认工作日 09:00–19:00,范围外全部静默并记录,TUI 按
n查看 ⚠️ 运行时依赖:Ink / React / ascii.rest(TUI 与启动动画);分发以单文件 exe 为准- ✅ 投递可靠:失败自动进入发件箱,指数退避重试并跨重启恢复
⚠️ 不回放历史:从进程启动时刻开始 tail 会话日志,启动前的旧事件不会补推
需要 Node.js ≥ 26(仓库内有 .nvmrc,可 nvm use)。
npm install
cp codexmonitor.config.example.json codexmonitor.config.json
# 编辑 codexmonitor.config.json:先设 "channel": "console" 本地验证
npm start启动后会看到:
[codexmonitor] 已启动(通道:console)
用 Codex 跑任务:中断会立即推送;任务完成按 aggregate 节流聚合(默认最多 2 小时一条)。想先验证链路,中断一个任务最快。
- 在 飞书开放平台 · 开发者后台 创建企业自建应用,并开通「机器人」能力(机器人能力说明)
- 在「凭证与基础信息」页获取
App ID/App Secret - 在「权限管理」中开通发送单聊消息、通过邮箱/手机号查询用户所需的权限,并发布应用版本
- 把
notify.channel改为"feishu",填写feishu.appId、feishu.appSecret - 填写
feishu.email或feishu.mobile(用于解析 open_id,邮箱优先);该用户需在应用可用范围内
{
"notify": { "channel": "feishu" },
"feishu": {
"appId": "cli_xxxxxxxx",
"appSecret": "xxxxxxxx",
"email": "you@corp.com",
"mobile": ""
}
}
codexmonitor.config.json含密钥,已被.gitignore忽略,不要提交。
配置文件为单一 JSON,深合并到默认值;只需写要覆盖的字段。
| 字段 | 默认值 | 说明 |
|---|---|---|
notify.channel |
"ilink" |
feishu / console;默认值 ilink 未实现,必须显式设置 |
codex.sessionsDir |
~/.codex/sessions |
Codex 会话日志根目录 |
codex.maxTrackedFiles |
20 |
同时跟踪的最新会话文件数 |
notify.aggregate.minIntervalMs |
7200000 |
完成通知的最小间隔(2h) |
notify.aggregate.maxItems |
5 |
单条聚合消息最多包含的任务数 |
notify.aggregate.maxPerDay |
4 |
完成通知每日上限 |
notify.thresholds.warnEnabled |
false |
是否推送 80% 预警 |
notify.workHours.enabled |
true |
是否启用工作时间限制 |
notify.workHours.start / end |
"09:00" / "19:00" |
工作时间段;start 含、end 不含 |
notify.workHours.days |
[1,2,3,4,5] |
工作日,0=周日…6=周六;未列出的日期全天静默 |
notify.workHours.timezone |
"" |
空串=系统本地时区;也可填 IANA 时区 |
probe.enabled |
true |
是否启用网络探针 |
probe.intervalMs |
20000 |
正常探测周期 |
probe.retryDelayMs |
5000 |
故障未确认时的快速重试间隔 |
probe.timeoutMs |
6000 |
单层探测超时 |
probe.slowThresholdMs |
2500 |
L2 延迟超过该值判 slow(仍视为链路可用) |
probe.confirmAttempts / recoverAttempts |
3 / 3 |
连续几次故障才报警 / 连续几次正常才恢复 |
probe.targets.l2 |
https://api.openai.com/v1/responses |
经代理探测的 Codex 真实端点 |
probe.proxy.mode |
"auto" |
auto 读环境变量与系统代理;manual 只探测 ports |
state.dir |
~/.codexmonitor |
运行时状态目录 |
Watcher(只读 JSONL) ─┐
├─▶ PolicyEngine(纯函数) ─▶ Notifier ─▶ 飞书 / 控制台
NetProbe(独立定时) ─┘ │
└─▶ 投递日志
| 层 | 职责 |
|---|---|
| Watcher | 增量 tail rollout-*.jsonl,解析完成 / 中断 / 额度事件,按 ts 排序 |
| NetProbe | 代理端口推导 → L1 TCP / L2 经代理访问 Codex 端点 / L3 直连(辅助)→ 滞回状态机 |
| PolicyEngine | 分级、聚合节流、额度状态机、配额守卫。纯函数,无 IO |
| Notifier | 分片投递、发件箱重试、投递留痕。通道可替换 |
探针判定:L2 返回 401/2xx 视为通;403(Cloudflare 拦截)、5xx、超时视为不通。代理模式下 L1 ok + L2 失败 一律判「代理节点故障」——TUN 模式下直连也走隧道,不能据此判断是否整体断网。
默认工作日(周一至周五)09:00–19:00 正常推送;其余时间:
- 所有通知都不推送,包括任务中断、额度耗尽、网络故障告警
- 每条通知写入
~/.codexmonitor/suppressed.jsonl - TUI 头部实时显示工作时间段与「推送中 / 静默中」状态
- TUI 按
n在「最近通知」与「静默通知」之间切换 - 启动时加载最近 50 条静默记录,重启后仍可查看
- 手动测试通知(
t)不受限制 - 工作时间内已接受、失败后跨到时间段外的重试会继续执行
- 仅支持同一天内的
start < end,不支持 22:00–次日 06:00 这类跨午夜区间
| 键 | 作用 |
|---|---|
t |
发送测试通知 |
p |
暂停 / 恢复网络探针 |
r |
重载配置 |
n |
切换最近通知 / 静默通知 |
q |
退出 |
| 路径 | 内容 |
|---|---|
~/.codexmonitor/delivery.jsonl |
每次投递一条:级别、来源、正文、ok、错误码、messageId |
~/.codexmonitor/suppressed.jsonl |
工作时间外被静默的通知:时间、级别、来源、正文、原因 |
~/.codexmonitor/quota.json |
额度状态快照,重启后恢复 |
~/.codexmonitor/pending.json |
投递失败、等待重试的通知 |
npm run typecheck # tsc --noEmit
npm test # vitest run
npm run build # 编译到 dist/
npm start # prestart 自动 build,然后常驻运行
npm run build:exe # Node 26 SEA:dist-exe/CodexMonitor.exe测试覆盖:JSONL 解析、尾部读取、分级、聚合、额度状态机、配额守卫、代理推导(含 SOCKS5 / 认证 / HTTPS)、三层探测、投递分片、投递日志、状态持久化、编排层、端到端文件链路、运行时事件与监控核心、TUI 格式化 / store / 组件、工作时间判断与静默记录。
| 工作流 | 触发 | 内容 |
|---|---|---|
ci.yml |
PR、push main |
windows-latest:npm ci → typecheck → build → test |
build-exe.yml |
手动、push v* 标签 |
手动运行只产出 dev artifact;push 标签才创建 Release。流程:npm test → 校验 tag 与版本 → npm run build:exe → exe 冒烟 → 上传 |
打包需要 Node 26.x(mainFormat: "module" 的 SEA 能力),两个工作流都按 .nvmrc 固定版本。未签名 exe 首次运行会触发 SmartScreen;如需签名,必须在 postject 注入之后进行。
- 平台:目前仅在 Windows 上验证与支持;macOS / Linux 未验证(代理推导依赖 Windows 注册表,其他平台只能走环境变量)
- iLink 通道未实现:本轮不兼容,
channel: "ilink"直接报错 - 冷启动不回放:启动前的历史事件不补推;额度状态依赖
quota.json,首次运行要等 Codex 下一次token_count - Windows 的 SIGTERM:父进程
kill()会直接终止进程,SIGTERM处理器不执行;交互式Ctrl+C正常 quotaWarn尚无冷却:quotaWarnCooldownMs已声明但未生效,开启 80% 预警后可能偏频繁- 工作时间外完全静默:包括告警;只能通过 TUI
n或suppressed.jsonl查看。如果需要告警豁免,应另行配置或修改代码 - 工作时间不支持跨午夜:
start >= end会报配置错误
ISC
