edit | blame | history | raw

Codex 常驻会话桥接说明

创建人员：Codex
文件职责：说明如何把管理系统消息发送到常驻 Codex 会话。
管理规范/模板：../../全局规范.md；../ai-workplace/AI工作空间创建指南.md。
引用文件：agents.example.json；send-codex-message.ps1。
记录方式：工具说明文档；桥接协议或使用方式变化时追加更新。

1. 目标

本目录用于验证和沉淀一种桥接方式：

管理系统 / 脚本
-> Codex app-server WebSocket / JSON-RPC
-> 指定 thread
-> 常驻 Codex TUI 或后台会话

目标不是每次调用 codex exec 新起一个会话，而是向已经登记的 thread_id 发消息。

2. 当前前置条件

必须先有一个可连接的 Codex app-server：

codex.cmd app-server --listen ws://127.0.0.1:4567

并且目标观察员窗口应连接到同一个 app-server，或至少目标 thread_id 已经在该 app-server 可恢复。

如果 app-server 没有监听，send-codex-message.ps1 会 fail-fast，不会假装发送成功。

3. Agent 注册表

参考 agents.example.json 创建项目自己的注册表，建议放在：

D:/manage_system/data/codex-bridge/agents.json

关键字段：

字段 说明
server_url Codex app-server WebSocket 地址
thread_id 目标 Codex thread id；为空时脚本可创建新 thread
cwd 该 agent 默认工作目录
model 可选；发 turn 时覆盖模型
approval_policy 可选；默认建议 never
sandbox 可选；默认按 thread 原设置

4. 发送消息

.\send-codex-message.ps1 `
  -Agent observer `
  -Message "你按 ag 检查最近实验，有问题全部报给我"

指定注册表：

.\send-codex-message.ps1 `
  -RegistryPath D:/manage_system/data/codex-bridge/agents.json `
  -Agent observer `
  -Message "桥接测试：回复 OK"

如果没有 thread_id，允许创建新 thread：

.\send-codex-message.ps1 -Agent observer -Message "初始化观察员" -CreateThreadIfMissing

5. 已知限制

  1. 本工具依赖 Codex app-server 的实验协议，协议可能随 Codex CLI 版本变化。
  2. 当前脚本只实现 WebSocket JSON-RPC 路径，不使用键盘模拟。
  3. codex.cmd app-server --listen ws://... 在部分环境下可能进程存在但端口未监听，遇到这种情况应先解决 app-server 启动问题。
  4. 不建议把消息发到没有队列锁的同一个 thread；同一时间同一 thread 最好只跑一个 turn。