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。
功能
- 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，然后汇总结果。运行过程可以在面板里实时查看。
文件
| 路径 | 作用 |
|---|---|
src/main.ts |
HTTP 服务：/mcp、面板、/api、SSE |
src/manager.ts |
用 Pi SDK 管理多个 AgentSession：事件、用量、follow-up、中止、持久化 |
src/mcp.ts |
MCP 工具定义 |
src/panel.html |
面板（原生 JS，无需构建） |
src/faux.ts |
离线假模型（含 SIMULATE_ERROR 出错测试） |
codex-plugin/ |
Codex 插件和本地 marketplace |
scripts/smoke.ts |
MCP 冒烟测试 |
scripts/mock-responses.mjs |
测试用的假 OpenAI Responses 端点，在没有模型凭据时充当 Codex 的父模型 |
已知限制
- 原型阶段：已在 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