1. 为什么单会话写代码会卡住多 Agent 协作的真实痛点如果你已经用 Codex 单会话写过代码大概率遇到过这种场景一个会话里既让它写实现又让它自己审自己结果它永远说“已完成”。这不是模型不聪明而是单会话缺少独立视角——写代码的和审代码的是同一个上下文它天然倾向于维护自己刚给出的结论。多 Agent 协作要解决的就是这个问题让实施 Agent 和审核 Agent 跑在两个独立会话里通过会话 ID互相定位、通过跨会话消息传递结构化交接。听起来简单但很多人第一步就踩坑以为把审核 Agent 的会话 ID 复制给实施 Agent两边就会自动协作。事实是会话 ID 只是地址结构化消息才是交接协议。你不发消息对方永远不知道要干什么。这篇面向已经会用 Codex 单会话的读者把“复制会话 ID / 深度链接 / 跨会话发消息”升级成一套可复制的多 Agent 实施手册。核心交付三样东西一份能直接抄的config.toml骨架、TaoToken 统一 Key/API 通道配置、以及多 Agent 会话 ID 传递与协作验证的完整动作。读完这一篇就能开跑不需要翻其它文档。先明确三个概念后面所有模式都建立在这上面概念作用能否自动投递工作内容会话 ID复制 ID唯一定位一个 Codex 任务/Agent否深度链接复制深度链接打开指定任务便于人查看否跨会话消息向指定会话发送后续 prompt是会话 ID 长这样019f843e-c357-7fc1-92c2-d138a760771b。把它当作不透明字符串原样传递不要解析、不要手改格式。深度链接适合放进会议纪要、看板让人点开看实现或审核过程但它不负责消息投递也不该被当成 API 参数拼接。跨会话消息才是真正驱动协作的动作——接收方拿到的是一条新的后续任务指令所以正文必须可执行、可验证、带证据。三条边界先记住A 与 B 是独立会话上下文不自动共享ID 解决“发给谁”消息解决“让对方做什么”“完成后发送”靠角色指令约束不是复制 ID 后的隐式事件订阅。2. TaoToken 前置统一 Key 与 API 通道配置多 Agent 协作最烦的一件事是每个 Agent 都要单独配 Key、单独配 base_url一旦要换通道就得改 N 个地方。我的做法是所有 Agent 共用一套 TaoToken 统一 Key 和 API 通道这样会话 ID 在变、Agent 在变但底层调用入口始终稳定。TaoToken 在这里扮演的是统一 API 通道的角色你申请一个 Key所有 Agent 的模型请求都走同一个入口省去逐个配置的麻烦。官网入口在 taotoken.netAPI 地址是https://taotoken.net/api注意 API 地址不带 UTM 参数直接写进配置即可。配置前先拿到 Key进入 API Keys 管理页 创建一个复制出来。如果你还不确定该用哪个模型跑 Agent可以先去 模型对话 里试一轮确认响应质量再落到配置里。这里有个关键点多 Agent 场景下实施 Agent 和审核 Agent 建议用同一个 Key、同一个通道。原因是审核 Agent 需要独立验证实施 Agent 的产物如果两边走不同通道、不同模型版本验证结论的可比性会下降。统一通道能让“审核通过”这个结论更可信。注意Key 属于敏感信息不要写进交接消息明文也不要提交到仓库。配置里用环境变量引用交接里只写“已配置”即可。3. 可复制的 config.toml 骨架下面这份config.toml骨架可以直接抄改掉路径和 Key 引用就能用。它把模型通道、Agent 角色、会话协作参数都收在一处避免散落在多个文件里。# ~/.codex/config.toml # 多 Agent 协作统一配置骨架 [model_providers.taotoken] name taotoken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY # 从环境变量读取不硬编码 wire_api chat [profiles.implementer] model_provider taotoken model claude-sonnet-4-5 # 实施 Agent可写代码、跑验证、提审 approval_policy on-request [profiles.reviewer] model_provider taotoken model claude-sonnet-4-5 # 审核 Agent默认只读不改仓库 approval_policy never sandbox_mode read-only [profiles.orchestrator] model_provider taotoken model claude-sonnet-4-5 # 主控 Agent管依赖图与归档闸门不写业务代码 approval_policy on-request [collab] # 多 Agent 协作参数 max_rejects_before_human 5 # 熔断阈值 default_mode L # S / L / P / V / X evidence_dir docs/evidence # 证据落盘目录几个参数解释一下。env_key指向环境变量你在 shell 里export TAOTOKEN_API_KEY你的Key即可配置文件本身不含密钥。reviewer的sandbox_mode read-only是硬约束——审核 Agent 只报告、不改仓库避免它“顺便修一下”污染证据。max_rejects_before_human 5是熔断阈值打回满 5 次就停自动循环等人介入防止两个 Agent 无限互踢。如果你要做长期编码或 Agent 编排建议直接上 Coding Plan它更适合这种多会话、长链路的场景配额和通道稳定性都更省心。配置写完后用一条最小请求验证通道是否通export TAOTOKEN_API_KEY你的Key curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复 OK 两个字母}] }返回里能看到choices[0].message.content就说明通道正常。这一步别跳过后面所有 Agent 都依赖它。4. 会话 ID 传递与协作验证动作配置通了接下来是核心怎么把会话 ID 串起来让多个 Agent 真正协作。我按模式从简到繁拆你可以按需选。4.1 Mode S单次交接人盯一次最简单的场景实施 Agent 做完交给审核 Agent 审一次。流程是——人给实施 Agent 写清完成条件和审核 Agent 的会话 ID实施达标后发跨会话消息审核独立验证后回结论。实施 Agent 的指令要写清“仅全部满足后才发送”你的任务是实现 Aurora Notes 同步引擎的 reconnect。 完成条件 1. reconnect、stop-before-connect、资源回收相关测试均通过 2. UI 层不得直连同步引擎内部 socket 3. 生成脱敏 evidence 4. 仅当 1-3 全部满足时向审核 Agent 发送交接否则发 blocked/failed 并说明原因。 审核 Agent threadId019f843e-c357-7fc1-92c2-d138a760771b 交接须包含状态、变更文件、命令与结果、evidence 路径、未覆盖项 不得把外部依赖 not-run 写成 passed。实施达标后它调用跨会话消息发送交接send_message_to_thread({ threadId: 019f843e-c357-7fc1-92c2-d138a760771b, prompt: 请对任务 aurora-sync-reconnect 进行独立审核。 结论ready-for-review 实现 - continuous session reconnect - stop-before-connect cancellation - resource cleanup 验证 - cargo test -p sync-engine reconnect - pnpm test --filter desktop-sync Evidence - /Users/you/aurora-notes/docs/evidence/sync-reconnect/summary.json 已知边界 - 真实云账号联调not-run - 未执行生产租户写入 请按 P1/P2 输出审核结论并只读审查。 })审核 Agent 收到后不要只信交接文字要读规格与实现、重跑无破坏性测试、查证据来源再输出结论。回传格式P1-1同一 topology 变更通知导致 session 反复 teardown。 复审条件 1. 同类通知不重置 session generation 2. 新增反例测试 3. 重跑单元测试与 evidence validator。4.2 Mode L单阶段自动闭环Mode S 需要人盯着Mode L 让实施和审核在同一 taskId 内自动来回实现 → 提审 → 审核 →修复再提审×N直到通过或rejectCount 5熔断等人。启动时向实施和审核各发同一套双向协议关键是三个字段reviewRound、rejectCount、maxRejectsBeforeHuman。首次提审reviewRound1、rejectCount0。审核暂不通过时rejectCount加一实施修复后再提审reviewRound加一、沿用回传的rejectCount。换 taskId新阶段时两者归零。注入包长这样改角色行即可你是本任务的【实施 Agent】或【审核 Agent】见下方角色。 双方遵守同一套双向协议并自动互发。 角色实施 | 审核 仓库/Users/you/aurora-notes taskIdA01 实施 Agent threadIdI_ID 审核 Agent threadIdR_ID maxRejectsBeforeHuman5 实施专规 - 可写代码与跑约定验证达标后向审核 send_message - 暂不通过且 rejectCount 5修复后再提审 - rejectCount 5 或 humanInterventionRequiredtrue停止自动提审。 审核专规 - 只读审完必须向实施 send_message - 不得在 rejectCount 5 后继续驱动自动修复循环。 每条跨会话消息必填taskId、reviewRound、rejectCount、maxRejectsBeforeHuman。这里最容易踩的坑是审核通过后没有停止自动提审。通过后实施应停止发送若有主控则另发阶段收口。熔断后禁止继续“再修再提”互驱humanInterventionRequiredtrue。4.3 Mode P多阶段编排与归档闸门Mode L 不会自动打开下一阶段。审核通过 ≠ 已归档 ≠ 下一阶段已启动。Mode P 引入主控 Agent 管依赖图和归档闸门。推进条件必须全部满足才 kickoff当前阶段phaseStatusreview-passed且无未关闭 P1归档完成且存在archiveProof下一阶段全部前置已 archived下一阶段不在硬闸门列表或人已放行未处于humanInterventionRequired。主控注入包你是【主控 / 编排 Agent】。不代替实施写业务代码不代替审核做验收结论。 仓库/Users/you/aurora-notes decomposition/Users/you/aurora-notes/docs/planning/AURORA_SYNC_TASK_DECOMPOSITION.md programaurora-notes-sync 实施 Agent threadIdI_ID 审核 Agent threadIdR_ID 主控 threadIdO_ID maxRejectsBeforeHuman5 archivePolicyprepare-then-human-confirm 职责 1. 按依赖图选择前置已 archived 的下一阶段为当前 taskId 2. 确保 I/R 使用 Mode L收到【阶段审核收口】且 review-passed 后准备归档 3. 提请人确认后执行/监督 archive写入 archiveProof 4. 推进条件全满足后发【阶段推进】给 I并同步 R 的当前 taskId 5. 硬闸门或 rejectCount5停止自动推进等人。 禁止 - 未过审或未归档就 kickoff - 一条消息要求做完整张拆解 - 无人确认时自动正式 archive / commit / 触达生产。通用硬闸门建议默认自动做到review-passed 归档清单就绪人确认归档及必要授权后主控再 kickoff。正式 archive、git commit、生产写入、付费 API、真实外部设备都必须人精确授权。4.4 Mode V / X调查与并行汇总Mode V 是调查→决策调查 Agent 收集现象、日志、调用链、反例交给决策 Agent 独立裁定根因。调查 Agent 默认只读避免未裁定前大改污染证据。决策 Agent 必须区分“已证明 / 假设 / 待实验”。Mode X 是并行专家→汇总多个只读调查 Agent 分域并行各自交接给决策 Agent决策 Agent 列出冲突表与采纳理由汇总后再交给单一实施 Agent。并行时禁止同写一工作区否则证据对不上版本。5. 本篇常见错排查跑多 Agent 协作时下面这些现象我基本都遇到过对照处理即可。现象可能原因处理复制了 ID 但对方无动静未发跨会话消息 / 未写“必须发送”检查指令与是否调用发送审核通过但下阶段没开始仍在 Mode L无主控或未收口到 O改用 Mode P确认 R→O开始了下阶段但前置不够O 未校验依赖/归档回滚 kickoff补 archiveProof声称已归档但无记录无归档环境却伪称 archive停推进补环境或改归档定义两边改同一文件冲突双写入或并行未隔离停一个写者改 worktree无限打回未熔断未带 rejectCount强制 max5人介入对方读不懂消息无协议头/缺字段用附录模板深度链接打不开协作误当投递通道改用 threadId send_message几个反模式必须禁止只发“做完了”无证据把 blocked/not-run 写成 passed审核 Agent 改业务代码“顺便修”无 rejectCount 的无限互踢过审后跳过归档直接改下一阶段多个写入 Agent 共享 dirty 工作区用深度链接当机器 API无人确认时自动正式归档、自动 commit、或自动触达生产。证据纪律是底线交接不能只有“已完成”必须有命令、结果、路径。审核不能只信文字按风险重跑无破坏性验证。passed 须验收条件与证据同时支撑。mock / 沙箱 / not-run 不得冒充真实环境 passed。密钥、令牌、个人笔记正文、账号标识等敏感内容不得进交接明文。6. 把协作链路真正跑起来到这里配置、模式、排障都齐了。最后给你一条从零开跑的最短路径先确认 Codex 能“复制 ID”且 Agent 能向另一会话发消息若要做 Mode P 且归档依赖 OpenSpec确认 OpenSpec 与 archive skill 可用选模式——一次审用 S自动来回用 L多阶段用 P创建会话粘贴注入包启动实施人只在满 5 次打回、确认归档、生产或真实外部触达时介入。统一 Key 和 API 通道的配置入口再放一次方便你直接落地API Keys 管理页 拿 Key接入文档 看参数细节。如果你要长期跑编码和 Agent 编排Coding Plan 比按次调用更稳。想先验证模型响应质量去 模型对话 试一轮再落配置。最后一句口诀收尾ID 是地址消息是交接协议深度链接是人工审计入口证据才是协作结论的可信基础协议先于工具熔断先于勤奋归档闸门先于下一阶段。
