Codex on DK Blog

Codex 的 Main Agent 和 Subagent 是怎么通信的

Thu, 25 Jun 2026 19:20:00 +0800

很多人第一次看 Codex 的多 agent 机制时，会下意识把 subagent 理解成 “main agent 调了一个内部函数”。这个理解不对。

在 Codex 里，subagent 更接近于：主线程之外又开了一个独立聊天线程。它有自己的 thread id、上下文、工具调用过程、执行状态和 mailbox。main agent 和 subagent 不共享完整上下文，它们靠 Codex runtime 转发内部消息协作。

这篇文章不讲 Rust 语法，只讲一条闭环：

1
2
3
4
5


main agent 怎么派任务
-> runtime 怎么投递消息
-> subagent 怎么独立执行
-> 结果怎么回到 main agent
-> main agent 怎么继续往下走

先看总览图：

先记住一个模型

可以先把 Codex 的 subagent 理解成下面这个结构：

1
2
3


main agent 所在主聊天线程
 另外开了一个独立聊天线程
 这个独立线程就是 subagent

所以 subagent 不是 main agent 内部的一个函数。它有自己的：

thread id
上下文
工具调用过程
执行状态
mailbox

这件事决定了 main agent 和 subagent 的关系不是同步函数调用，而是多个独立线程之间通过内部信件协作。

先看通信闭环

main agent 能控制 subagent 的方式，不是直接读写它的内存，而是调用一组协作工具：

1
2
3
4
5
6


spawn_agent 创建子 agent，并给第一条任务
send_message 给已有 agent 发消息，但不强制它马上跑
followup_task 给已有 agent 发后续任务，并在空闲时触发它继续跑
wait_agent 等待有 agent 消息或状态变化
interrupt_agent 打断某个 agent 当前执行
list_agents 查看当前有哪些 agent

这些工具本质上都是 function call。模型输出 function call，Codex runtime 收到后执行内部逻辑。

把完整流程压成一条主链路，大致就是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


用户提问
 -> main agent 决定拆任务
 -> main agent 调 spawn_agent
 -> runtime 创建 child thread
 -> 第一条任务进入 child thread
 -> child agent 独立执行
 -> main agent 调 wait_agent
 -> child agent 调 send_message(target=root)
 -> root mailbox 收到结果
 -> wait_agent 被唤醒
 -> main agent 下一轮读到这条消息
 -> main agent 汇总后回答用户

这里最重要的三点是：

subagent 是真的独立 thread，不是内部函数。
send_message 和 followup_task 都是在投递内部消息，只是后者会顺带触发目标 agent 开始下一轮执行。
wait_agent 等的是 mailbox 活动，不是同步拿子函数返回值。

例如 main agent 创建 subagent 时，可能只是发出这样一个调用：

1
2
3
4


spawn_agent({
 task_name: "research",
 message: "你去分析 app-server 里的 subagent 通信逻辑"
})

但 runtime 真正做的是：

1
2
3
4
5


创建 child thread
记录 parent_thread_id
记录 task_name
投递第一条任务
启动 child agent 独立执行

而 subagent 回结果时，走的也不是“返回值”，而是再发一封内部信：

1
2
3
4


send_message({
 target: "root",
 message: "我查完了。结论是：Codex 通过 InterAgentCommunication 和 mailbox 通信。"
})

所以从运行时视角看，Codex 的多 agent 更像：

1
2


多个独立聊天线程
 通过 runtime 维护的内部邮箱互相发消息

wait_agent 为什么经常被误解

wait_agent 最容易被误解成“同步等待 subagent 返回值”，其实它更像：

`1`	`main agent 暂停一下，等 mailbox 有没有新消息`

比如：

1
2
3


wait_agent({
 timeout_ms: 30000
})

它的意思是：

1
2
3


最多等 30 秒
如果收到 agent 消息或相关活动，就返回
如果 30 秒没有，就返回 timed_out

超时返回类似：

1
2
3
4


{
 "message": "Wait timed out.",
 "timed_out": true
}

这里一定要分清：

1
2
3


wait_agent 超时
!=
subagent 被杀掉

子 agent 可能还在继续跑。runtime 不会自动替 main agent 做决策，它不会自动：

kill 子 agent
interrupt 子 agent
判定子 agent 失败
自动重派任务

它只是把 timed_out=true 交还给 main agent。接下来 main agent 自己决定下一步：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


继续等:
 wait_agent({ timeout_ms: 30000 })

打断:
 interrupt_agent({ target: "research" })

催促:
 followup_task({ target: "research", message: "收敛一下，直接给结论" })

先回答用户:
 基于已有信息组织答案

所以 main agent 在这套机制里，本质上更像调度者。

这条闭环在源码里怎么落地

如果只看一张源码总览图，可以先记住这条链：

1
2
3
4
5
6
7


模型看到工具定义
 -> 模型发起 function call
 -> tool handler 接住 function call
 -> AgentControl 负责创建 / 发消息 / 等待 / 中断
 -> session handlers 和 InputQueue 负责 mailbox
 -> turn loop 把 mailbox 消息放进模型上下文
 -> app-server / TUI 把事件展示给客户端

按这个链路往下看，源码可以分成 6 个位置。

第一层：工具暴露给模型

文件：

1
2


codex-rs/core/src/tools/spec_plan.rs
codex-rs/core/src/tools/handlers/multi_agents_spec.rs

这里分别负责两件事：

spec_plan.rs 决定当前 turn 要不要把多 agent 工具暴露给模型
multi_agents_spec.rs 定义这些 function call 的参数 schema

也就是说，main agent 能不能调用 spawn_agent、send_message、wait_agent，第一步先看这里。

第二层：main agent 的控制入口

文件：

1
2
3
4
5
6
7


codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs
codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs
codex-rs/core/src/tools/handlers/multi_agents_v2/wait.rs
codex-rs/core/src/tools/handlers/multi_agents_v2/interrupt_agent.rs
codex-rs/core/src/agent/control.rs
codex-rs/core/src/agent/control/spawn.rs
codex-rs/core/src/agent/registry.rs

这层可以理解成 “main agent 的控制台”：

spawn.rs 负责接住 spawn_agent
message_tool.rs 负责接住 send_message 和 followup_task
wait.rs 负责 wait_agent
interrupt_agent.rs 负责打断入口
AgentControl 是统一控制中心
spawn_agent_internal(...) 真正创建 child thread
AgentRegistry 记住有哪些 agent、各自的 thread id 和 path

所以“main agent 怎么找到 subagent、怎么把任务发过去”，主要都在这层。

第三层：内部消息的数据结构

文件：

`1`	`codex-rs/protocol/src/protocol.rs`

关键结构：

`1`	`InterAgentCommunication`

它可以直接理解成一封内部信，里面最关键的是：

author
recipient
content
trigger_turn

例如：

1
2
3
4


from: root
to: research
content: 继续查一下 thread_history.rs
trigger_turn: true

第四层：消息如何进入 mailbox

文件：

1
2


codex-rs/core/src/session/handlers.rs
codex-rs/core/src/session/input_queue.rs

这里是真正的 mailbox 落点：

handlers.rs 里的 inter_agent_communication(...) 收到 Op::InterAgentCommunication
input_queue.rs 里的 enqueue_mailbox_communication(...) 把消息放进 mailbox
如果 trigger_turn=true，runtime 会尝试启动目标 agent 的新一轮 turn

所以 send_message 和 followup_task 的本质区别，就落在 trigger_turn 上。

第五层：mailbox 怎么进入模型上下文

文件：

1
2


codex-rs/core/src/session/turn.rs
codex-rs/core/src/session/mod.rs

这里负责两件事：

turn.rs 在每轮请求模型前，从 InputQueue 取 pending input
mod.rs 里的 record_inter_agent_communication(...) 把消息写进历史和 rollout

也就是说，agent 间消息不只是内存里短暂经过，它还会：

进入下一轮模型上下文
写入会话历史
被客户端看到

第六层：状态和展示

文件：

1
2
3
4
5


codex-rs/core/src/agent/status.rs
codex-rs/app-server-protocol/src/protocol/thread_history.rs
codex-rs/tui/src/app/loaded_threads.rs
codex-rs/tui/src/app/agent_navigation.rs
codex-rs/tui/src/app/thread_routing.rs

这层负责把运行中的事实变成用户能看到的东西：

status.rs 把事件映射成 Running、Completed、Errored 等状态
thread_history.rs 把协作事件转成客户端能展示的 ThreadItem
TUI 相关文件负责找出主线程下有哪些 subagent，以及怎么在界面里切换和缓存它们

所以你在 app-server 或 TUI 里看到的“创建了哪个 agent”“谁给谁发了消息”“wait 有没有超时”，最终都依赖这层映射和展示。

最短源码定位表

你想看什么	看哪个文件
工具怎么暴露给模型	`codex-rs/core/src/tools/spec_plan.rs`
function call 参数怎么定义	`codex-rs/core/src/tools/handlers/multi_agents_spec.rs`
`spawn_agent` 入口	`codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs`
创建 child thread	`codex-rs/core/src/agent/control/spawn.rs`
main 如何控制 agent	`codex-rs/core/src/agent/control.rs`
agent 列表和 metadata	`codex-rs/core/src/agent/registry.rs`
`send_message` / `followup_task`	`codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs`
内部信件结构	`codex-rs/protocol/src/protocol.rs`
mailbox 队列	`codex-rs/core/src/session/input_queue.rs`
mailbox 进入模型上下文	`codex-rs/core/src/session/turn.rs`
通信记录进历史	`codex-rs/core/src/session/mod.rs`
`wait_agent` 超时逻辑	`codex-rs/core/src/tools/handlers/multi_agents_v2/wait.rs`
agent 状态	`codex-rs/core/src/agent/status.rs`
app-server 展示	`codex-rs/app-server-protocol/src/protocol/thread_history.rs`
TUI subagent 导航	`codex-rs/tui/src/app/agent_navigation.rs`

最后收一句

如果只记一句话，我建议记这句：

`1`	`Codex 的 main agent 和 subagent 不是同步函数调用，而是多个独立 thread 通过 runtime 维护的 mailbox 互相发消息`

从原理上看，这是一个“多线程聊天 + 内部邮箱”的协作模型；从源码上看，这条链路则落在 tool handler、AgentControl、session mailbox、turn loop、app-server 和 TUI 几层里，刚好首尾闭环。

Multica 初体验：把 Codex、Claude Code 这类 coding agent 当成队友来管理

Thu, 28 May 2026 22:16:00 +0800

最近看了一下 Multica，感觉它解决的不是“让 AI 写代码”这个问题，而是另一个更实际的问题：当你同时用 Codex、Claude Code、Copilot CLI、OpenCode 这类 coding agent 时，怎么管理它们干活。

以前我的用法比较粗糙：开几个终端窗口，每个窗口一个 agent，谁在跑什么、结果有没有回来、上下文有没有断，全靠自己记。任务少的时候还行，一旦同时丢两三个问题，比如一个查 bug、一个写测试、一个做文档，很快就乱了。

Multica 的思路是把 agent 放进一个协作空间里。它有 workspace、issue、comment、agent 这些概念。你可以把一个 issue 分配给某个 agent，也可以在评论里 @ 它。这个体验更像是在给同事派活，而不是在终端里继续补 prompt。

我当时顺手记了一个很小的判断：如果一个工具只是在网页里多开几个聊天窗口，那它对 coding agent 的帮助有限；如果它能回答“谁在跑、跑到哪、改了什么、失败后能不能复盘”，它才像是在管理执行单元。Multica 比较接近后者。

我比较在意的点

我比较在意的一点是：Multica 并不是简单把所有东西都丢到云端跑。官方文档里说，真正执行任务的是本地 daemon。Multica server 负责 workspace、issue、成员、任务队列这些数据；daemon 跑在你自己的机器上，去调用本地安装的 Claude Code、Codex、Copilot CLI 等工具。

这个设计对我来说挺关键。coding agent 最敏感的地方不是“问答内容”，而是它会读代码、跑命令、改文件。如果一个平台只是提供任务面板，但实际执行仍然在本地，那接受成本会低很多。

当然这不代表完全没有风险。agent 能做什么、工具权限怎么给、仓库怎么隔离，还是要自己控制。

从 provider matrix 看，Multica 对不同 coding tool 的支持不是完全一样的。Claude Code、Codex、OpenCode 在 MCP 支持、skill 注入路径、session resumption 上都有差异。这个地方我觉得文档写得比较实在，没有假装所有工具都能做到同一个水平。

我会特别看这些差异，而不是只看“支持多少 agent”：

能力	我为什么关心
session resumption	agent 中途断了以后能不能接着跑，不然长任务很容易废掉
MCP support	能不能接公司内部工具，而不是只靠本地 shell
skill injection	能不能把团队约定、代码规范、常用命令放进 agent 上下文
task history	失败任务能不能复盘，而不是只剩一句“没做好”

如果我要试

如果要在项目里试，我大概会先按这个方式用：

1
2
3


multica daemon start

multica setup self-host

然后给不同 agent 分清职责，而不是所有任务都丢给一个“全能助手”：

1
2
3


codex-fixer 小范围代码修复和测试
claude-reviewer review、解释设计风险
opencode-docs 文档草稿和命令整理

我现在对这类工具的看法是：不要指望它让 agent 变聪明。它真正有价值的地方是让 agent 的工作可排队、可观察、可追溯。

终端里跑 agent 最大的问题是过程容易丢。Multica 把一次运行抽象成 task，有 queued、dispatched、running、completed、failed 这类状态，也有重试和历史记录。这样你至少知道它是没开始、跑挂了，还是已经完成只是结果不理想。

我不会一上来就接正式仓库

更合理的方式是先拿一个 side project 或内部工具试：

只给只读或低风险仓库。
agent 默认不要有生产凭证。
每个任务只允许小范围修改。
输出必须经过人工 review。
不要把“能跑起来”误认为“能放心用”。

Multica 这类项目让我感觉到一个趋势：coding agent 正在从“单次对话工具”变成“可管理的执行单元”。以前我们关心的是 prompt 怎么写，现在更关心任务怎么派、权限怎么控、结果怎么验收。

这篇先记到这里。它不是那种看完文档就能断言成熟的工具，但方向我觉得值得关注。尤其是团队里已经有人混用 Codex、Claude Code、Copilot CLI 的时候，与其每个人各玩各的，不如有一个地方把任务和 agent 统一管起来。

我暂时不会把它写成“推荐大家马上上”。更准确的评价是：如果你的团队还没有稳定使用 coding agent，它不是第一优先级；如果已经有人同时开好几个 agent 做修复、review、文档和测试，它解决的就是混乱本身。

参考资料

Codex CLI 交互斜杠命令全集（含作用与使用场景）

Thu, 05 Mar 2026 23:40:00 +0800

来源：OpenAI 官方文档（Codex CLI Slash Commands）
更新时间：2026-03-05
说明：以下是 codex 交互界面（TUI）内输入的 /xxx 命令，不是 PowerShell 系统命令。

最近在高频用 Codex CLI，发现很多同学刚上手时，会把 /xxx 斜杠命令和系统命令混在一起，导致操作路径有点乱。
所以我把官方文档里这部分命令做了一次“能直接抄着用”的整理：每个命令不只写功能，还配了一个真实使用场景，方便你在实战里快速判断“现在该敲哪个”。

使用方式

启动 codex
在输入框输入 / 打开命令列表
选择命令或手动输入完整命令

命令清单（作用 + 场景）

命令	具体作用	典型使用场景
`/permissions`	设置当前会话的审批/权限策略	你要从“手动审批”切到“自动执行优先”时
`/sandbox-add-read-dir`	给沙箱追加可读目录（Windows 原生 CLI）	需要读取工作区外的配置目录或共享代码目录
`/agent`	切换当前活跃 agent 线程	同时跑了多个任务，想切回另一个线程继续
`/apps`	浏览并插入可用 connectors/apps	需要接入外部系统数据（如任务系统、文档系统）
`/clear`	清屏并开启新会话	当前对话太长，想从干净上下文重新提问
`/compact`	压缩并总结长对话，减少上下文占用	会话很长导致响应变慢或上下文接近上限
`/copy`	复制最近一次已完成输出	要把刚生成的命令/代码粘贴到别处使用
`/diff`	查看当前 Git diff（含未跟踪文件）	让模型改完代码后，先人工快速过一遍改动
`/exit`	退出 CLI（等价 `/quit`）	结束当前工作会话
`/experimental`	开关实验功能	想试新能力或排查某实验特性的影响
`/feedback`	提交日志/反馈	发现异常行为，需要把现场信息反馈给官方
`/init`	在当前目录生成 `AGENTS.md` 模板	新仓库首次使用 Codex，先定义协作规则
`/logout`	退出登录并清理本地凭据	切账号、交接机器或做安全清理
`/mcp`	查看已配置 MCP 工具	检查某工具是否已接入、当前可不可用
`/mention`	把文件/目录加入当前对话上下文	只想让模型关注某几个目录而不是全仓库
`/model`	切换模型（可含推理强度）	先用快模型探索，再切强模型做最终修复
`/plan`	切到 Plan 模式并提出规划请求	任务复杂，先要分步骤方案再执行
`/personality`	切换回答风格（friendly/pragmatic/none）	团队希望输出更简洁或更工程化
`/ps`	查看实验性的后台终端及输出	排查后台执行任务卡住或失败原因
`/fork`	从当前会话分叉新线程	保留原思路，同时探索另一种实现路径
`/resume`	恢复历史会话	第二天继续昨天做到一半的任务
`/new`	在同一 CLI 中新开对话	当前问题做完，开始另一个独立任务
`/quit`	退出 CLI	同 `/exit`，用于结束会话
`/review`	让 Codex 审查当前改动	提交 PR 前先自动扫一轮风险点
`/status`	查看会话配置与 token 使用	想确认当前模型、沙箱、审批和消耗情况
`/debug-config`	输出配置层与策略诊断信息	配置不生效时定位是被哪一层覆盖
`/statusline`	配置 TUI 状态栏显示项	想在界面上实时看到模型/审批等状态

兼容与别名

/approvals：仍可用，但通常不在 slash 列表里显示；建议改用 /permissions。
/exit 与 /quit：功能等价，都是退出 CLI。

两个高频命令

/init：初始化仓库级协作规则（生成 AGENTS.md）。
/model：任务中途切模型，平衡速度和质量。

版本差异说明

不同 codex-cli 版本会新增/隐藏命令。以你本机实际可见列表为准：在交互界面输入 / 即可查看当前版本完整命令。

写在最后

如果你是第一次系统使用 Codex CLI，我建议先记住这几个高频命令：/model、/permissions、/diff、/review、/status。
这几个覆盖了日常最常见的流程：选模型 -> 管权限 -> 看改动 -> 做审查 -> 查会话状态。

另外一个实用习惯是：遇到“感觉命令不见了”或者“和别人截图不一致”时，先在当前会话里输入 / 看本机版本实际列表，再决定下一步。
这样能避免把时间花在“文档有，但你当前版本没开”这类问题上。