codex-pi-subagents

让 Codex 把子任务交给 Pi 执行：每个子 agent 可以用 Pi 支持的任意模型（DeepSeek、Anthropic、Gemini、OpenRouter、本地模型……），并提供一个实时 Web 面板，可在普通浏览器或 ChatGPT 桌面 app 的内置浏览器中打开。

Codex ──MCP (streamable HTTP)──▶ codex-pi-subagents 常驻服务 ──Pi SDK──▶ AgentSession × N（各自的模型）
                                        │
                                        └── http://127.0.0.1:7788  Web 面板（SSE 实时）

为什么

Codex 原生子 agent 只能沿用父会话的 model provider（自定义 agent 文件里的 model_provider 不生效）。本项目把子 agent 交给 Pi，因此每个子任务都能单独选模型、选 provider。

Related MCP server: LightWorker

功能

• MCP 工具：pi_list_models、pi_spawn_agent、pi_wait、pi_get_agent、pi_send_followup、pi_abort、pi_list_agents

• 多个 Pi 会话在同一进程并发运行，每个会话可指定模型、thinking 等级、工作目录，工具可选 coding 或 read-only 两种预设

• 会话以 JSONL 持久化；服务重启后面板日志从 JSONL 恢复，follow-up 可以接着原来的上下文继续

• Web 面板：agent 列表、状态、token 和费用、实时输出、工具调用，可发送 follow-up 或中止

• Codex 插件：打包 MCP 配置和一个 skill，skill 告诉 Codex 何时以及如何委派给 Pi

• --faux 离线假模型：不需要任何 API key 就能跑通整条链路

安装

需要 Node ≥ 22.19（Pi 1.4.0 的要求）。

git clone https://github.com/Caho1/codex-pi-subagents
cd codex-pi-subagents
npm install
npm start                 # 使用 Pi 已配置的模型（环境变量或 ~/.pi/agent）
npm start -- --faux       # 离线假模型，用于试跑
npm run check             # 类型检查
npm run smoke -- /path/to/project   # 通过 MCP 做冒烟测试（需要服务已启动）

参数：--port 7788、--host 127.0.0.1、--data ~/.codex-pi-subagents（agent 索引和会话 JSONL 的存放目录）、--stdio（同时在 stdio 上提供 MCP）。也可用环境变量 PI_SUBAGENTS_PORT、PI_SUBAGENTS_DATA 设置。

面板地址是 http://127.0.0.1:7788 ，每个工具结果里都带 panel 链接。

模型：DeepSeek

Pi 内置 deepseek provider（OpenAI 兼容，https://api.deepseek.com），只读环境变量 DEEPSEEK_API_KEY，不需要 models.json：

export DEEPSEEK_API_KEY=...    # 不要写进任何文件
npm start

pi_list_models 会返回 deepseek/deepseek-flash 和 deepseek/deepseek-v4-pro（以 DeepSeek /models 接口实际返回为准）。其他 provider 见 Pi 文档 providers.md 和 models-configuration.md。

接入 Codex

先启动本服务，然后任选下面一种方式。

方式 A：插件（推荐）

插件会带上 MCP 连接和 pi-subagents skill。

codex plugin marketplace add ./codex-plugin
codex plugin add pi-subagents@pi-subagents-local

插件自带的 MCP 工具默认需要审批，在 ~/.codex/config.toml 里放行：

[plugins."pi-subagents@pi-subagents-local".mcp_servers.pi-subagents]
default_tools_approval_mode = "approve"

方式 B：手动配置 mcp_servers

[mcp_servers.pi-subagents]
url = "http://127.0.0.1:7788/mcp"
tool_timeout_sec = 300             # pi_wait 最多阻塞 240 秒
default_tools_approval_mode = "approve"

这种方式没有 skill。需要在提示词或 AGENTS.md 里说明"用 pi_spawn_agent 委派子任务"。

可选：只用 Pi，关掉原生子 agent

[agents]
enabled = false

不关的话两套工具并存。实测装了插件以后，即使原生子 agent 开着，Codex 收到"用子 agent 做 X"这类请求也会按 skill 选择 Pi。

可选：Codex 父模型也用 DeepSeek

DeepSeek 支持 OpenAI Responses API，满足 Codex 唯一支持的 wire_api = "responses"：

model = "deepseek-flash"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

用法示例

在 Codex 里：

Review src/ for real bugs. Use two subagents in parallel — one on deepseek-v4-pro, one on deepseek-flash — both read-only. Wait for both and merge the findings.

Codex 会依次调用 pi_list_models、pi_spawn_agent ×2、pi_wait，然后汇总结果。运行过程可以在面板里实时查看。

文件

已知限制

• 原型阶段：已在 Codex CLI 0.164.0 + Pi 1.4.0 + DeepSeek 上实测，未在 ChatGPT 桌面 app 的内置浏览器中验证。

• Codex 通过阻塞的 pi_wait 等待结果，还没有在完成时主动唤醒 Codex（计划通过 App Server 的 turn/start 实现）。

• 子 agent 不受 Codex 沙箱约束，权限由 Pi 的工具决定。用于探索或评审时请用 tools: "read-only"；多个子 agent 同时写文件没有隔离（尚无 worktree 支持）。

• 子 agent 看不到 Codex 的对话，任务描述必须写完整。

• 面板和 MCP 没有鉴权，只监听 127.0.0.1，不要绑定到公网地址。

• MCP 工具无法主动打开浏览器标签页，面板需要用户点链接打开，或在桌面 app 里用 @Browser 打开。

• Codex 对非 OpenAI 模型会提示 "Model metadata not found"，改用默认元数据。

License

MIT