codex-desktop-orchestrator：用聊天软件远程调度 Codex

本地桥接服务，把 Codex Desktop 变成可以用 QQ、微信远程指挥的开发助手，支持线程管理、项目别名、长任务和媒体回传。

项目地址：https://github.com/xxloocee/codex-desktop-orchestrator ｜ MIT 开源协议

这是什么

codex-desktop-orchestrator 是一个跑在本机的桥接服务，把 Codex Desktop 变成一个可以被聊天软件远程调度的开发助手。

QQ / 微信消息
  → 本地 bridge daemon
  → 调度 Codex Desktop 线程和任务
  → 指挥 Codex 执行开发工作
  → 把结果、进度和媒体回传到聊天窗口

它不是普通聊天机器人。你在 QQ 里发一句"审查当前未提交的改动"，bridge 会把任务路由到本机 Codex 线程，等 Codex 跑完再把结果发回来——人不在电脑前也能用。

Codex 侧默认走 Codex app-server 链路，不要求 Codex Desktop 通过 9229 CDP 端口启动。

主要功能

在聊天窗口里直接派活

直接让 Codex 审查项目、分析代码、跑检查、总结文档或处理文件。每个聊天会话绑定一个 Codex 线程，避免上下文互相污染。

线程管理

用途	命令	简写
查看最近线程	`/threads`	`/t`
查看当前线程	`/thread current`	`/tc`
切换线程	`/thread use <序号>`	`/tu <序号>`
新建线程	`/thread new <标题>`	`/tn <标题>`
fork 线程	`/thread fork <标题>`	`/tf <标题>`

项目别名

把聊天命令路由到指定本地目录：

/aliases                                  # 查看所有别名
/new my-project 使用 Code Review skill 审查当前未提交更改

长任务管理

用途	命令
查看当前任务	`/task current`
查看最近任务	`/tasks`
取消任务	`/cancel [taskId]`
重试失败或超时任务	`/retry <taskId>`
查看投递记录	`/deliveries`

Codex 状态与权限

用途	命令	简写
查看当前模型	`/model`	`/m`
切换模型	`/model use <名称>`	`/mu <名称>`
查看额度	`/quota`	`/q`
查看运行状态	`/status`	`/st`
查看权限模式	`/permission`	`/pm`
切换权限模式	`/permission <模式>`	—

三种权限模式：

full：完全访问，不等桌面人工审批（默认，适合无人值守远程控制）
reviewed：限制在工作区内，越权操作交给 Codex 自动审核
workspace：限制在工作区内，网络和外写操作直接失败

切换权限需要私聊用户在 QQ_CODEX_PERMISSION_ADMIN_SENDERS 中显式配置，群聊只能查询当前模式。

媒体、语音与文件

图片、语音、视频、文件下载后注入给 Codex
支持 QQ 内置 ASR、OpenAI 兼容 STT、火山引擎 STT、本地 whisper.cpp
Codex 回复里的本地图片和文件引用会回传到聊天窗口

平台支持

平台	状态	说明
QQ	已支持	官方 Bot WebSocket，支持私聊、群聊、媒体、语音转写
微信	文本通道	内置 long-poll 文本网关
飞书	规划中	企业协作入口
Telegram	规划中	跨设备轻量远程指挥

使用方式

1. 安装依赖

git clone https://github.com/xxloocee/codex-desktop-orchestrator
cd codex-desktop-orchestrator
pnpm install

2. 生成配置

pnpm run build
pnpm start -- init

3. 填写 QQ Bot 凭据

QQ Bot 在 QQ 开放平台创建，拿到 AppID 和 ClientSecret 后编辑 .env：

QQBOT_APP_ID=你的AppID
QQBOT_CLIENT_SECRET=你的ClientSecret
QQ_CODEX_ALLOWED_C2C_SENDERS=你的QQ用户OpenID
QQ_CODEX_PERMISSION_ADMIN_SENDERS=你的QQ用户OpenID

[!IMPORTANT] 访问控制默认是 deny-by-default。不配置 allowlist 时服务能启动，但不会接受任何聊天侧任务。只有显式设置 QQ_CODEX_ACCESS_CONTROL=allow-all 才会放开全部来源，doctor 会对此给出安全警告。

4. 构建并启动

pnpm run build
pnpm start

常用运行时命令：

pnpm start -- status       # 查看状态
pnpm start -- doctor       # 健康检查
pnpm start -- logs 200     # 查看最近 200 行日志
pnpm start -- tasks 20     # 查看最近 20 个任务
pnpm start -- stop         # 停止服务
pnpm start -- restart      # 重启服务

默认单轮硬超时 30 分钟，工具连续 5 分钟无事件会被中断，可用 QQ_CODEX_TURN_TIMEOUT_MS 和 CODEX_TOOL_SILENCE_TIMEOUT_MS 调整。

常用配置

项目别名

QQ_CODEX_PROJECT_ALIASES_JSON={"my-project":{"cwd":"D:/Project/my-project","label":"My Project"}}

访问控制

QQ_CODEX_ALLOWED_C2C_SENDERS=OPENID1,OPENID2
QQ_CODEX_ALLOWED_GROUPS=GROUP_OPENID1
QQ_CODEX_GROUP_REQUIRE_MENTION=true

微信文本网关

WEIXIN_ENABLED=true
WEIXIN_EGRESS_BASE_URL=http://127.0.0.1:3200
WEIXIN_EGRESS_TOKEN=your-token

首次扫码登录后启动网关：

pnpm weixin:login
pnpm start:weixin-gateway

适用场景

手机远程控制本地 Codex：离开电脑时用手机下发代码审查、测试或文档任务
异步长任务：发完命令继续做别的事，Codex 跑完自动回传结果
多项目切换：用别名在多个本地仓库之间快速切上下文
语音下发任务：语音消息自动转写后交给 Codex 执行

注意事项

.env 包含 QQ Bot、微信、STT 等敏感凭据，不要提交到仓库
本项目会处理聊天消息、附件、语音和本地文件路径，联调时注意隐私边界
重试会创建新 turn，不会恢复旧 Codex turn 的进程状态
daemon 重启后未完成任务会被收口为 timed-out 或 orphaned，不会自动续跑
工具进度只做事件记录和节流心跳，不会把完整工具日志刷到聊天窗口