Codex ClawMessenger

@quukk/codex-clawmessenger 是一个独立的 ClawMessenger sidecar，通过官方 @openai/codex-sdk 把融云私聊、群聊和 Discussion v2 / Roundtable 任务接入本机 Codex。它不是 Codex 原生插件包，也不会修改 Codex 本体。

安装与启动

要求 Node.js 18 及以上，并且本机 Codex 已完成认证。

npm install -g @quukk/codex-clawmessenger
codex-clawmessenger setup
codex-clawmessenger start --daemon
codex-clawmessenger status

前台调试时使用：

codex-clawmessenger start

所有命令均支持 --config <绝对或相对路径>。默认运行文件位于 ~/.config/codex/：

• clawmessenger.json：节点配置与融云凭据，写入权限为仅当前用户；
• clawmessenger-state.json：会话映射、消息去重和运行状态，不保存完整聊天正文；
• clawmessenger.log：脱敏结构化日志；
• clawmessenger.pid、clawmessenger-status.json、clawmessenger.stop.json：daemon 所有权、心跳和优雅停机控制。

CLI

codex-clawmessenger setup
codex-clawmessenger start [--daemon]
codex-clawmessenger stop
codex-clawmessenger status [--json]
codex-clawmessenger logs [-n N] [-f]

• setup 先检查 Codex backend，再刷新或注册 Codex 节点并原子保存配置；探测或注册失败时不会写入新凭据。
• start --daemon 等待运行时心跳进入 running 或 degraded 后返回。
• stop 只会控制 PID 文件、随机所有权 token 和实际命令行同时匹配的进程；无法验证时拒绝终止。
• status --json 输出融云连接、Codex 健康度、活动任务、排队任务和最后心跳时间。
• logs -f 可用 Ctrl+C 停止跟随。

配置

环境变量优先于配置文件：

| 环境变量 | 含义 | 默认值 | | --- | --- | --- | | CLAW_SERVER_URL | ClawMessenger 服务地址 | https://newsradar.dreamdt.cn/im | | CLAW_TOKEN | 融云 token；通常由 setup 保存 | 无 | | CLAW_ACCOUNT_ID | Codex 节点 ID；通常由 setup 保存 | 无 | | DM_APP_KEY | 融云 AppKey；未设置时从服务端公开配置接口读取 | 无 | | CLAW_CODEX_DIR | Codex 工作目录，必须是已存在的绝对目录 | 当前目录 | | CLAW_CODEX_SANDBOX | read-only、workspace-write 或 danger-full-access | workspace-write | | CLAW_CODEX_NETWORK | 是否允许 Codex 网络访问 | false | | CLAW_CODEX_ADDITIONAL_DIRS | 额外允许目录，使用系统路径分隔符连接 | 无 | | CLAW_CODEX_MODEL | 默认原生 Codex 模型 ID | Codex 默认 | | CLAW_CODEX_MODELS | 可供 Roundtable 显式路由的模型 ID，逗号分隔 | 无 | | CLAW_MAX_CONCURRENT | 不同会话的最大并发 turn 数 | 2 | | CLAW_MAX_QUEUED_PER_CHAT | 每个会话最大排队数 | 20 | | CLAW_LOG_LEVEL | debug、info、warn 或 error | info |

danger-full-access 还必须在配置文件中显式设置 "allowDangerFullAccess": true，仅设置环境变量不会绕过这道确认。远程 IM 不处理 Codex 原生审批，approvalPolicy 固定为 never。

模型目录只公布 CLAW_CODEX_MODELS 白名单中的条目，Roundtable 路由使用 codex/<模型 ID>；未在白名单中的显式模型会失败，不会静默回退或改写全局默认模型。

消息与 Roundtable

普通私聊和群聊支持文本、图片、安全落盘的普通文件路径、停止生成以及本地会话映射命令：

/status
/stop
/new
/sessions
/switch <thread-id>
/delete <thread-id>

同一 conversation key 严格串行，不同会话按全局上限并行；/stop 和 /status 绕过普通队列。消息 ID 使用持久去重，daemon 重启后原先处于 queued 或 running 的任务会标记为 unknown，不会自动重放。

Discussion v2 与 Roundtable 支持：

• host 与 participant 角色；
• 每轮 checkpoint、用户继续/结束、最终 Markdown 纪要；
• 显式 Codex 模型路由；
• 大消息 wire 分片、artifact 分块与 ACK；
• 取消、逻辑幂等和隐私安全生命周期日志。

发给其他节点或格式不合法的 discussion_* 帧会被丢弃，不会降级成普通 Codex prompt。

安全与已知限制

• Codex thread ID 依赖本机 ~/.codex/sessions；复制 JSON 映射到另一台机器不能保证恢复。
• /delete 只删除 bridge 的本地映射，不删除 Codex 的本地 thread 数据。
• runStreamed() 事件在本实现中只映射为粗粒度状态；不把它宣传为逐 token 文本增量。
• AbortSignal 是协作式取消，可能留下半完成 turn；该 turn 的一致性无法保证，但 bridge 不会自动重放。
• 图片通过隔离目录中的绝对本地路径作为 Codex 图片输入。
• 普通文件不是 Codex 原生上传，只是在安全落盘后向 Codex 提供受控路径提示。
• 每个 turn 由 Codex SDK 启动 Codex 子进程，资源模型不同于常驻 App Server。
• 附件只接受 HTTPS、公网解析结果和受支持的安全文件类型；脚本、SVG、路径穿越、私网/回环地址和超限内容会被拒绝。
• token、Authorization、完整 prompt、消息正文和附件内容不会写入结构化日志。

开发验证

npm ci
npm run typecheck
npm test
npm run test:pack

test:pack 会生成 tgz，在受控临时目录中使用 --ignore-scripts 安装，导入发布包，执行安装后的 CLI，并检查依赖树与发布文件边界。

真实 Codex 冒烟默认跳过。仅在本机已经认证且明确允许调用时运行：

CODEX_SMOKE=1 npm run test:codex-smoke

PowerShell：

$env:CODEX_SMOKE='1'
npm run test:codex-smoke
Remove-Item Env:CODEX_SMOKE