在 Codex 中搭建多智能体团队：用混合模型策略兼顾质量与成本

适用场景与完成后的结果

当一个 Codex 项目从简单问答发展到资料研究、代码实现和持续迭代时，只靠一个主任务很容易上下文混乱，也难以控制成本。这篇教程适合想让多个 AI Agent 分工协作的个人开发者和小团队。

读完后，你会搭出一个 3–4 角色的最小团队，知道怎样划分职责、选择模型和安排协作顺序，并完成一次实际运行。文章最后还提供了一段可直接交给 Codex 的搭建提示词。

不需要一开始就配置庞大的 Agent 组织。先用最小团队跑通一个真实任务，观察质量、速度和成本，再决定是否增加角色。

先定边界：模型分工是可检验假设，不是岗位定律

先从四个职责清楚的角色开始。账户可用模型、默认模型和路由会受套餐、客户端版本与管理员策略影响；请先查看自己 Codex 中实际可选的模型，再替换示例 ID。OpenAI 关于多智能体的能力—速度—成本取舍见 Codex 多智能体文档。

这不是“强模型做战略、低价模型做执行”的普适真理。复杂开发、深度教程、安全审计或高风险回归都可能需要升级模型；应以任务歧义、风险、失败成本、返工率与实际费用决定。独立审核的硬门槛是：独立上下文、独立证据、禁止自审、审核者自行阅读任务与 diff 并重跑验证。不同模型只是在可用时增加视角多样性；同一模型也可在全新上下文中完成独立审核。

版本与成本提醒：本文资料核验日期为 2026-08-03。模型 ID、套餐、价格、协议与 UI 都会变化；外部 Provider 调用通常消耗对应 API 余额或套餐额度，未必包含在 ChatGPT 订阅中。即使是连通性测试也可能产生小额费用，开始前先在控制台确认。

配置分层：谁管理什么

主任务（目标、当前轮上下文、分派）
  └─ 项目 .codex/agents/*.toml（角色、模型、权限约束）
       └─ 用户 ~/.codex/config.toml（Provider 名称、Base URL、wire_api、环境变量名）
            └─ 操作系统/组织认可的秘密管理（只在启动时映射为环境变量）
                 └─ 外部模型服务

AGENTS.md 与项目 Skills = 治理与工作流层；不是密钥存储层。

项目级 TOML 不应包含 Key。AGENTS.md 与 Skill 负责说明谁能做什么；用户级 config.toml 只引用环境变量名；实际秘密由操作系统或组织认可的秘密管理方式保存。

配置外部 Provider：先确认 Responses，再谈兼容

Codex 自定义 Provider 使用 Responses 协议。根据 Codex 配置参考，model_providers.<id>.wire_api 当前支持的值是 responses，省略时也默认使用它；为了让意图可审计，示例显式写出该字段。

DeepSeek：官方协议与读者实测要分开

DeepSeek 官方资料说明其地址提供 OpenAI Chat Completions 兼容能力，并提供工具调用资料（见 快速开始与定价 与 工具调用指南）。这不能自动推出对 Codex Responses 的永久兼容。

因此下面只给出需要由读者自行验证的配置形态，不把任何作者项目的内部连通记录当成公共兼容性证据。只有你在自己的账户中真实 spawn 成功，才能把该路由标为可用。

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

Volcengine：从自己的控制台取得 Responses 地址

火山引擎的产品与套餐入口见官方页面。不同 Ark 产品、套餐和版本的 Base URL 可能不同，不能把教程中的某个地址当成通用端点；请从自己的购买页或控制台复制当前确认支持 OpenAI/Responses 的地址，并用只读子 Agent 做真实验证。

[model_providers.volcengine_plan]
name = "Volcengine Coding Plan"
base_url = "<YOUR_VOLCENGINE_RESPONSES_BASE_URL>"
env_key = "VOLCENGINE_API_KEY"
wire_api = "responses"

“OpenAI 格式兼容”并不等于“Responses 兼容”。若端点只声明 Chat Completions，不能仅通过删除 model_reasoning_effort 来修复；应先确认端点的 Responses 支持，或停止并改用已确认的路由。

安全地配置密钥

在密码管理器或操作系统的安全界面中保存密钥时，DeepSeek 使用 <YOUR_DEEPSEEK_API_KEY>，Volcengine 使用 <YOUR_VOLCENGINE_API_KEY> 作为教程中的唯一占位符。不要把真实值写进仓库、.env、截图、聊天、日志或提示词。

Windows PowerShell 可使用隐藏输入：以下脚本不会在命令历史中包含密钥文本，并在写入用户环境变量后释放临时 BSTR。更稳妥的选择是使用操作系统图形界面或组织认可的秘密管理工具。

function Set-UserApiKeyFromHiddenInput {
  param([ValidateSet("DEEPSEEK_API_KEY", "VOLCENGINE_API_KEY")][string]$Name)
  $secureKey = Read-Host "Enter $Name" -AsSecureString
  $bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureKey)
  try {
    $plainKey = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr)
    [Environment]::SetEnvironmentVariable($Name, $plainKey, "User")
    "$Name saved to the user environment: True"
  }
  finally {
    if ($bstr -ne [IntPtr]::Zero) { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr) }
    Remove-Variable plainKey -ErrorAction SilentlyContinue
  }
}

Set-UserApiKeyFromHiddenInput -Name "DEEPSEEK_API_KEY"
Set-UserApiKeyFromHiddenInput -Name "VOLCENGINE_API_KEY"

重启 Codex 后，再做只显示布尔状态的 401 排查；不要输出环境变量值：

$isConfigured = -not [string]::IsNullOrWhiteSpace(
  [Environment]::GetEnvironmentVariable("DEEPSEEK_API_KEY", "User")
)
"DEEPSEEK_API_KEY configured: $isConfigured"

在 macOS/Linux 中，从终端用隐藏输入把密钥注入当前 shell，再从同一个 shell 启动 Codex；完成后清除临时 shell 变量。不要把明文写入 .zshrc、.bashrc、仓库或 .env。如需持久化，请使用操作系统钥匙串、组织认可的秘密管理服务，并仅在启动时映射为环境变量。

read -rs -p "Enter DEEPSEEK_API_KEY: " SECRET; echo
export DEEPSEEK_API_KEY="$SECRET"; unset SECRET
# 从这个 shell 启动 Codex，然后仅运行只读连通性测试。
# Codex 完全退出后，在同一 shell 中执行：unset DEEPSEEK_API_KEY
# Volcengine 变量按相同原则处理；也可以直接关闭这个专用 shell。

用户环境变量可避免密钥进入仓库，但不是保险库：同一用户权限下的本地进程仍可能读取它。禁止让 Agent 读取、打印、截图、写入文件或回显 Key。

创建最小项目 Agent

从 3–4 个角色开始，而不是复制整套团队。项目级自定义 Agent 放在 .codex/agents/*.toml，一个角色一个文件最容易审计。Codex 以 TOML 内的 name 作为身份事实源；文件名与 name 一致是推荐约定，但不是身份判断依据。

模型可用性是条件项。先创建一个只读的内置模型审核者；下面的模型 ID 只是占位示例，必须替换成你账户中实际可用的模型：

.codex/agents/independent-reviewer.toml

name = "independent-reviewer"
description = "在独立上下文中审核任务范围、变更和验证证据。"
model = "<AVAILABLE_REVIEW_MODEL>"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
你在独立上下文中审核，不得审核自己的实现。
先读取原任务、项目规则和真实 diff；自行重跑适用的只读验证。
默认只报告 P0/P1/P2，不修改、提交、推送、部署或发布。
"""

再创建一个绑定外部 Provider 的执行者。这里的 model_provider 必须与用户级 [model_providers.volcengine_plan] 的 id 完全一致：

.codex/agents/implementation-worker.toml

name = "implementation-worker"
description = "只执行边界清晰、可验证且已批准的实现任务。"
model = "glm-5.2"
model_provider = "volcengine_plan"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
只在当前任务明确的文件范围内工作，并先读取项目 AGENTS.md 与适用 Skill。
不得修改密钥、治理文件、生产数据或扩大任务范围。
完成后提交 diff、测试证据和待独立审查事项，不得批准自己的实现。
"""

如果执行 Agent 使用 DeepSeek，对应文件同样需要 model_provider = "deepseek"。内置 OpenAI 路由可省略 model_provider；外部 Provider 不应依赖隐式继承。

可选的并发上限属于项目级 .codex/config.toml，不要混入某个角色文件：

[agents]
max_concurrent_threads_per_session = 3

developer_instructions 是行为约束；sandbox_mode = "read-only" 才是更强的工具/文件权限边界。执行者即使是 workspace-write，也不因此获得 commit、部署、生产数据或账户授权。

主任务分派时应写清当前轮目标、范围、输入文件、验证标准和禁止项。子 Agent 不应把未重新提供或未从仓库读取的跨轮聊天内容当成事实。禁止递归委派：子 Agent 只完成被分配的有界任务，不再生成子 Agent；并发与角色扩张由主任务统一控制。

验证真实连通性，而非只验证 TOML 能解析

每个角色都应被主任务逐个真实 spawn，任务须只读、低成本、边界明确。协调者测试必须明确 spawn orchestrator，不能用主任务直接回答来代替。随后在 Codex 任务详情中核对 Agent 名称、可见时的模型/Provider、开始与完成状态、任务结果；只解析 TOML 或仅看到主任务回复都不算通过。

不要复制别人的“passed”结果。请为自己的项目创建一张空白验证表，并且只在真实完成 spawn 后填写：

公共教程不应把另一个项目的内部角色、模型映射或运行日志当作你的配置依据。保存自己不含秘密的最小验证证据即可。

建议在你自己的验证表中补充 spawned_at，但不要记录密钥、请求头或完整敏感日志。一次验证失败应先检查：模型 ID 是否可用、Provider 是否明确为 Responses、Base URL 是否来自当前官方文档/控制台、环境变量是否只以布尔状态确认，再决定是否调整配置。

运行锁：报告并等待，不要自行清理

若运行时提示锁冲突，优先使用项目提供的受控 status/unlock 机制读取锁的 绝对路径、owner/run id 与活跃状态。报告这三项后停止并等待用户明确批准；“看起来是旧锁”不是删除依据。只有用户批准且项目没有受控维护命令时，才由获授权的操作者按项目安全规则处理精确单文件。本文不提供删除命令、递归操作、通配符或跨 shell 清理方法。

常见故障的安全排查顺序

1. 401 Unauthorized：仅用布尔状态确认对应用户环境变量是否存在；不要打印值。确认后重启 Codex，再用一个只读 spawn 重试。
2. 模型不存在或路由错误：在自己的 Codex 界面、Provider 官方文档或控制台确认当前模型 ID；不要把任何教程中的示例 ID 当作账户保证。
3. 400/422 协议不兼容：先确认该端点明确兼容 Responses。仅支持 Chat Completions 的地址不能靠删掉推理强度字段变成 Responses 端点。
4. 调用卡住或超时：将任务缩为只读、低成本的最小验证，记录时间和错误类别；先检查服务商状态、网络与账户额度，再决定重试或回退到已验证路由。
5. 重启后配置未生效：确认修改的是用户级配置与正确的环境变量作用域，完全退出并重新启动 Codex；然后重新 spawn 指定自定义 Agent，不以主任务默认回复代替验证。

两周观察：把路线当成实验

记录每个角色的失败率、返工率、延迟、审查发现率和外部费用。两周后再决定哪些角色应升级、降级、合并或改回人工审批。不要因为一个角色“便宜”就扩大权限，也不要因为模型“更强”就跳过独立审核。

下一步：完成你的第一个只读 Agent 连通性测试，再按真实结果扩展团队。

一段可直接复制给 Codex 的搭建提示词

请在当前仓库为我设计最小可用的 Codex 多智能体方案，但先不要修改任何文件。

硬性安全门：
1. 先读取项目规则、AGENTS.md、适用 Skills 和现有 .codex/agents；查重后给出 3–4 个最小角色、职责、输入输出、风险与验证计划。
2. 在我明确确认角色方案前，不得修改项目治理文件；用户级 config.toml、系统环境变量、账号授权和长期规则仍需单独明确批准。
3. 只检查 Key 是否已配置，禁止读取、打印、截图、写文件、回显或推断任何 Key 值。
4. 每个外部 Provider 必须声明并验证 Responses 协议；Base URL 与模型 ID 以官方文档或我自己的控制台为准，不能把 Chat Completions 兼容当作 Responses 兼容。
5. 确认后先创建 3–4 个最小角色，并由主任务逐个真实 spawn 只读、低成本任务；记录 role、预期模型/Provider、时间、结果和 pass，不得仅凭 TOML 解析成功宣布连通。
6. 每个子 Agent 使用有界的当前轮任务上下文；不得递归委派、不得自行扩大权限或修改范围。
7. 审核必须使用独立上下文、独立证据，禁止自审；审核者自行读取原任务与 diff 并重跑适用验证。不同模型仅在可用时作为额外多样性。
8. 遇到锁或任何文件清理，先报告绝对路径、owner/run id 和活跃状态，停止并等待我的明确批准；不得自动删除。
9. 不得自动 commit、push、发布、部署、修改生产数据或发起新的付费 API 调用；连通性测试前先说明潜在外部成本并等待确认。

请先输出方案、最小 TOML 草案、验证表模板和需要我确认的项目级/用户级变更清单。

参考与核验日期

• OpenAI Codex 配置参考，访问与核验：2026-08-03。
• OpenAI Codex 多智能体文档，访问与核验：2026-08-03。
• DeepSeek 快速开始与定价、DeepSeek 工具调用，访问与核验：2026-08-03。
• 火山引擎 Coding Plan 产品入口，访问与核验：2026-08-03。
• AIVI 仅可作为第三方工作流灵感，不用于证明 Provider 协议、模型可用性、价格或兼容性等关键事实。

本文未在写作时读取密钥文件、环境变量、账户控制台或生产运行状态；请在自己的授权环境中完成实际验证。