Orchestrator

Orchestrator MCP

一个 Agent。一份第二意见。同一个终端。

让 Claude Code 询问 Codex。让 Codex 询问 Claude Code。
使用已在电脑上登录的订阅。
无需配置服务提供商 API 密钥。

查看演示 · 对比 · 安装 · 功能介绍 · 审查 · 工作流 · 安全性 · 控制面板

Orchestrator MCP 是一个本地 Model Context Protocol 服务，让一个编码 Agent 能够咨询另一个 Agent。它会启动你已在机器上安装并完成身份验证的 Codex、Claude Code、OpenCode、GitHub Copilot，或实验性的 Antigravity CLI，转发请求并返回结构化答案。

它不会要求提供服务提供商密钥、代理服务提供商的流量，也不会悄悄切换模型。身份验证仍由各供应商的 CLI 负责。

快速开始：在 Codex 已登录的情况下，从 Claude Code 开始（其他宿主：安装）：

uv tool install orchestrator-mcp-server              # or pipx, pip, or brew
orchestrator-mcp-server init --host claude           # writes ~/.orchestrator-mcp/config.yaml
claude mcp add orchestrator \
  --env ORCHESTRATOR_CONFIG=$HOME/.orchestrator-mcp/config.yaml \
  --env ORCHESTRATOR_HOST_RUNTIME=claude -- orchestrator-mcp-server

然后让 Claude Code 向 Codex 征求第二意见。

使用前 / 使用后

订阅不变，上下文切换更少。

 Claude Code host  ──►  Orchestrator MCP  ──►  Codex CLI
 Codex host        ──►  Orchestrator MCP  ──►  Claude Code CLI
 Any host          ──►  Orchestrator MCP  ──►  OpenCode CLI (DeepSeek, Qwen, Kimi…)
 Any host          ──►  Orchestrator MCP  ──►  GitHub Copilot CLI
 Any host          ──►  Orchestrator MCP  ──►  Antigravity CLI (experimental)

                         local routing
                    no provider API keys
                no same-execution-identity loops

普通的 orchestrator_consult 调用会排除宿主的整个运行时：Claude Code 不能使用该工具咨询 Claude Code，Codex 也不能使用它咨询 Codex。 审查和工作流使用更精确的 (runtime, model) 执行身份；当 consult.host.model 明确指定宿主时，它们可以路由到同一运行时上可证明不同且经过版本标识的模型。宿主绝不会将任务路由回自身的执行身份。

对比情况

如果你只需要让 Claude Code 向 Codex 提问，OpenAI 的 codex-plugin-cc 就能做到，还支持后台 任务。PAL MCP 可通过服务提供商的 API 密钥连接多个模型。Orchestrator 则适用于其他情况：

调用会阻塞发起调用的轮次，通常持续数分钟。要在此期间继续使用 Claude Code 工作，请让后台子 Agent 发起调用。

Google 的 Gemini CLI 已于 2026 年 6 月 18 日停止为免费账户和 Google AI Pro/Ultra 账户提供服务；这里通过其后继产品 Antigravity CLI 访问 Google 模型。

安装

Claude Code：作为插件安装。 需要在 PATH 中安装 uv，并至少安装且登录 Codex、Antigravity、OpenCode 或 GitHub Copilot 之一（见下文步骤 1）。你向它们咨询的内容——提示词、差异、文件内容——会通过你自己的登录信息发送给相应服务提供商；相关用量会计入你在这些服务中的账户。请参阅隐私政策和安全模型。在 Claude Code 中：

/plugin marketplace add crAK1644/orchestrator-mcp
/plugin install orchestrator-mcp@orchestrator-mcp
/orchestrator-mcp:setup

/orchestrator-mcp:setup 会根据检测到的 Agent 命令行工具生成 ~/.orchestrator-mcp/config.yaml，然后对其运行 doctor。它会检测 Codex、Antigravity 和 GitHub Copilot；OpenCode 则需根据 config.example.yaml 中的 Agent 手动添加到配置中。随后，在 /mcp 中重新连接 plugin:orchestrator-mcp:orchestrator，或重启 Claude Code：/reload-plugins 会保留使用无配置文件启动的服务。

如果之前已通过 claude mcp add orchestrator 添加服务器，请移除该条目（运行 claude mcp remove orchestrator -s <scope>，其中作用域可通过 claude mcp get orchestrator 查看），否则服务器会重复运行。

其他所有宿主以及未安装插件的 Claude Code，都需要自行安装服务器：

Homebrew：

brew tap crAK1644/tap
brew install orchestrator-mcp-server

Apple Silicon 使用预构建软件包。Intel macOS 和 Linux 会从源代码构建依赖项；如果想更快地临时安装，请使用 uvx 选项。

uv、pipx 或 pip： 将 orchestrator-mcp-server 安装到虚拟环境中，可使用 uv tool install orchestrator-mcp-server、pipx install orchestrator-mcp-server 或 pip install orchestrator-mcp-server。需要 Python 3.11 或更高版本。

1. 登录 Agent 命令行工具

登录你希望 Orchestrator 使用的每个 Agent：

codex login
claude auth login

这是 Codex 和 Claude Code 的常规登录流程。Orchestrator 会检查是否已准备就绪，但绝不会读取或存储它们的凭据。

对于 OpenCode，使用 opencode auth login 登录一次，选择你打算咨询的提供商。仅支持托管提供商——此服务不会在你的计算机上运行模型。请参阅下文的 OpenCode 运行时部分。

对于 GitHub Copilot，请登录 Orchestrator 运行它时所用的状态副本，而不是你自己的副本：COPILOT_HOME=$HOME/.orchestrator-mcp/copilot/home copilot login。init 写入 Copilot Agent 时会打印该命令；如果咨询时发现 Copilot 已退出登录，则会在 required_action 中返回该命令。它需要 Copilot 订阅计划；请参阅下文的 GitHub Copilot 运行时部分。

2. 编写入门配置

orchestrator-mcp-server init --host claude   # or codex: the client you run it under

init 会查找此处已安装的 Codex、Claude Code、GitHub Copilot 和 Antigravity 命令行工具，写入 ~/.orchestrator-mcp/config.yaml（权限模式为 0600，绝不会覆盖现有文件；使用 --path 可指定其他路径），并打印第 3 步所需的准确配置行。它会选择不是宿主的最佳审查者。 Copilot 的评分低于其他工具，因此只有当它是宿主之外唯一的命令行工具时，才会将它选为审查者；在 deep_reviewers 中则会将它排在最后。它的 Agent 会写为 model: auto，这是每种计划都支持的唯一模型， 因此名称不会过时；init 还会打印第 1 步中的登录命令。它不会写入 workflow: 块， 因为只有你能选择工作流可操作的目录；也不会写入 OpenCode Agent，因为它的模型名称变动过于频繁，不适合用作模板。你可以从 config.example.yaml 手动添加。

consult:
  database_path: ~/.orchestrator-mcp/consultations.sqlite3
  timeout_s: 180

  agents:
    codex:
      runtime: codex
      command: codex
      model: gpt-5.6-sol
      priority: 10
      web_search: true
      scores: { coding: 95, research: 90, reasoning: 95, review: 90 }

    claude:
      runtime: claude
      command: claude
      model: claude-opus-5-5
      priority: 10
      web_search: true
      scores: { coding: 90, research: 95, writing: 95, review: 95 }

3. 将服务添加到 MCP 客户端

init 已打印出填入你路径的配置。

claude mcp add orchestrator \
  --env ORCHESTRATOR_CONFIG=$HOME/.orchestrator-mcp/config.yaml \
  --env ORCHESTRATOR_HOST_RUNTIME=claude \
  -- orchestrator-mcp-server

[mcp_servers.orchestrator]
command = "orchestrator-mcp-server"
env = { ORCHESTRATOR_CONFIG = "~/.orchestrator-mcp/config.yaml", ORCHESTRATOR_HOST_RUNTIME = "codex" }

{
  "mcpServers": {
    "orchestrator": {
      "command": "/opt/homebrew/bin/orchestrator-mcp-server",
      "env": {
        "ORCHESTRATOR_CONFIG": "~/.orchestrator-mcp/config.yaml",
        "ORCHESTRATOR_HOST_RUNTIME": "claude"
      }
    }
  }
}

{
  "servers": {
    "orchestrator": {
      "type": "stdio",
      "command": "orchestrator-mcp-server",
      "env": {
        "ORCHESTRATOR_CONFIG": "~/.orchestrator-mcp/config.yaml",
        "ORCHESTRATOR_HOST_RUNTIME": "claude"
      }
    }
  }
}

{
  "mcp": {
    "orchestrator": {
      "type": "local",
      "command": ["orchestrator-mcp-server"],
      "environment": {
        "ORCHESTRATOR_CONFIG": "~/.orchestrator-mcp/config.yaml",
        "ORCHESTRATOR_HOST_RUNTIME": "opencode"
      }
    }
  }
}

更改配置后，重启 MCP 客户端。

提示

为 ORCHESTRATOR_CONFIG 指定绝对路径或 ~ 下的路径。通过图形界面启动的客户端通常会从不同的工作目录启动，并且继承的 PATH 比终端中的更短。

4. 检查

ORCHESTRATOR_CONFIG=~/.orchestrator-mcp/config.yaml ORCHESTRATOR_HOST_RUNTIME=claude \
  orchestrator-mcp-server doctor

每项检查输出一行 ok 或 FAIL：配置已加载、数据库已打开，以及每个 Agent 的 CLI 已安装并登录。只要有任何一项失败，命令就会以状态码 1 退出。它只会运行各 CLI 自带的登录检查，因此不会有任何项目材料离开本机。

客户端会启动服务并通过 stdin 与其通信，因此 orchestrator-mcp-server 不是需要你手动启动的命令。（仪表板 是此分发的另一部分，需要手动启动。）除了上面的 init 和 doctor，还有两个标志可用于在客户端之外查询信息：

orchestrator-mcp-server --version   # which build the client will spawn
orchestrator-mcp-server --help      # what the environment variables have to say

这两个标志都会在不读取配置的情况下返回结果并退出。命令行上的任何其他内容（下文的终端报告除外）都会被拒绝，而不是忽略。要让服务读取配置，请在不带参数的情况下运行它：若文件无法接受，程序会输出一条指出问题键名的消息——大多数错误只占一行，架构验证失败则会输出多行，但绝不会显示回溯信息。

终端报告

六个只读命令会打印数据库中已有的内容。它们会代替服务运行，读取同一份配置中的 database_path，并以只读方式打开文件：绝不会迁移数据库，因此，如果数据库来自较早版本，程序会提示你启动一次服务。

orchestrator-mcp-server usage [--days 30] [--json]      # turns, tokens and cost per agent and model
orchestrator-mcp-server history [--limit 20] [--kind review] [--json]   # recent records, with their ids
orchestrator-mcp-server scorecard [--days 30] [--json]  # how each reviewer answered, and what became of its findings
orchestrator-mcp-server strengths [--days 30] [--json]  # how each agent answered each kind of question, how fast, at what cost
orchestrator-mcp-server search WORD... [--days N] [--limit 10] [--json]   # stored prompts and answers that hold every word
orchestrator-mcp-server export ID                       # one record and everything it owns, as JSON

只有当组内每一轮都报告了价格时，才会显示价格；否则价格会显示为 unknown，并附上已报告价格的总和，不会显示为零。评分卡会将主机标记为 fixed 或 accepted_risk 的发现计为已保留，将标记为 rejected 的发现计为已拒绝；这些处置状态由主机在最终确定审查时报告，本服务不会检查，而之后的重新检查也不会更新这些状态。当某位审查者的发现有十条得到裁定后，才会显示其命中率。重新检查的审查不纳入统计，以免同一条发现被重复计数；没有合成记录的审查（尚未最终确定，或 store_full_content: false，此时无法最终确定）会计为已请求但未评判。

sole serious 统计至少有两位审查者作答的审查中，只有该审查者提出、且主机未拒绝的严重和重要发现。尚未处理的发现也会计入，因为记录修复轮次不会改变处置状态。它表示第二位审查者可能会漏掉什么。如果某位审查者从未与其他审查者一同作答，则会显示 -。

strengths 回答的是“谁擅长什么？”。对于每种问题类型（coding、research、review 等），它会按 Agent 和模型统计请求、已回答和失败的轮次数，计算回答平均耗时和费用。每次咨询都会计入，包括审查者和工作流步骤；从未开始的轮次，或被支出上限阻止的轮次则不会计入。请求达到五次后会显示失败率；review 行还会附带评分卡的命中率。表格下方的提示会指出值得关注的事项，但不会修改任何内容：某种问题类型的五次或更多请求中，失败率至少为 30% 的 Agent 及其最常见错误（connection_required 之类的设置错误会归类为设置问题，并提示使用 doctor）；以及配置当前将某种问题类型路由给的 Agent，如果其每次回答耗时至少是另一个已配置 Agent 的两倍，而失败次数不比对方多（两者都需至少回答五次，且使用当前配置的模型），则会提示该问题类型。配置中已不存在的 Agent 或模型绝不会被推荐。路由方式按服务的实际逻辑计算；如果 ORCHESTRATOR_HOST_RUNTIME 指定了主机自身的运行时，则会将其排除在外。这些信息都不能说明谁的回答更好：只有 review 行会提供这方面的信号，而且各 Agent 收到的问题并不相同。 search 会回答“哪个 Agent 告诉我的？”。如果存储的提示词或回答包含查询中的所有单词，就会匹配，并优先显示最佳匹配；单词的其他词尾形式也会匹配（search 可以找到 searched）。每条命中都会显示一段包含匹配词（以「»」标记）的简短摘录、Agent 和模型、日期，以及用于 export 的 ID。审核者的命中会注明其审核。单词只是单词：AND、NEAR、*、: 和引号都没有特殊含义，查询最多为 200 个字符。--limit 最大为 25，--days 默认为全部时间。 每次调用都会根据文本实际打印时的内容在内存中建立索引，因此旧记录中的凭据既无法读取，也无法搜索到，数据库中也不会添加任何内容。每兆字节存储文本约需 0.2 秒。若 store_full_content 为 false（即不保留任何文本），则不会找到任何内容，并会说明原因。同一搜索功能也可通过只读工具 orchestrator_search_consultations 使用。

export 接受完整 ID，或 history 中至少 8 个字符的唯一前缀。它会按存储内容打印记录，并像其他所有内容一样应用相同的屏蔽处理；不包含会话 ID 或确认令牌哈希。审核或工作流会通过 ID 标明其拥有的咨询；使用 export 导出这些咨询即可阅读。它打印的是你的提示词和回答，因此请像对待数据库一样谨慎处理。以只读方式打开 WAL 数据库时，旁边可能会创建 -wal 和 -shm 文件；数据库文件本身绝不会被写入。

改用 uvx 运行

claude mcp add orchestrator \
  --env ORCHESTRATOR_CONFIG=$HOME/.orchestrator-mcp/config.yaml \
  --env ORCHESTRATOR_HOST_RUNTIME=claude \
  -- uvx orchestrator-mcp-server

[mcp_servers.orchestrator]
command = "uvx"
args = ["orchestrator-mcp-server"]
env = { ORCHESTRATOR_CONFIG = "~/.orchestrator-mcp/config.yaml", ORCHESTRATOR_HOST_RUNTIME = "codex" }

你将获得什么

咨询工具

这些删除工具只会移除本地 SQLite 记录。它们无法清除已咨询运行时自身的 CLI 或提供方历史记录。

三种独立的启用选项：咨询工具始终会公布；评审工具仅在存在 consult.review 配置块时公布；工作流工具仅在存在 consult.workflow 配置块时公布。评审者不是工作流，工作流也不是评审者。

斜杠命令

服务器也会提供 MCP 提示词；支持 prompts/list 的客户端会将其呈现为斜杠命令。在 Claude Code 中，它们显示为 /mcp__<server-name>__<command>，其中服务器名称取决于你在 MCP 客户端配置中为其指定的名称——对于上方展示的 orchestrator 条目，命令为 /mcp__orchestrator__review。如果将服务器作为插件安装，服务器名称为 plugin_orchestrator-mcp_orchestrator，因此同一命令为 /mcp__plugin_orchestrator-mcp_orchestrator__review。

所有参数均为可选；不带参数的命令会展开为一条指令，要求向你询问缺少的信息。支持 completion/complete 的客户端会为 agent 提供已配置的 Agent，为 workflow_id 提供最近的 ID。只有在相应工具也已公布时才会公布 review 和 workflow；两者的判断依据相同——否则，命令只能回答“未配置评审者”，既多耗一次往返，也像是个错误。

有两点需要说清楚。**这里不会安装任何内容。**这些提示词通过与工具相同的 stdio 连接传送：没有命令目录，没有生成的 Markdown，也不会向你的机器写入任何内容；不支持 prompts/list 的客户端也不会受到影响。**提示词是文本，不是操作。**展开提示词不会咨询任何人、不会发送任何内容，也不会启动工作流——它会像你手动输入的一样进入宿主的对话，然后宿主再调用工具，并保留所有检查点。之所以提供这些提示词，是因为这里值得使用的流程都需要握手确认；仅凭工具描述来驱动流程的宿主往往会跳过检查点，而检查点正是这些流程有价值的关键。

资源

每条记录也都是资源模板，供使用资源而非调用工具的客户端使用：orchestrator://consultation/{consultation_id}、orchestrator://review/{review_id} 和 orchestrator://workflow/{workflow_id} 会读取与之对应的 get 工具返回的 JSON，ID 会从最近的历史记录中补全。模板不会列出实例；要查找 ID，请使用列表工具。每个模板都与其对应的工具一样，采用相同的选择加入方式发布。

审查和工作流视图

在支持渲染 MCP Apps 的宿主中，例如 Claude Desktop，orchestrator_get_review、orchestrator_finalize_review 和 orchestrator_workflow_status 会以表格形式展示结果：按严重程度、审查者和位置列出发现，或列出工作流步骤及接下来可运行的内容。该页面随软件包一同提供，路径为 ui://orchestrator/view.html，不会从网络加载任何内容，并且会将审查者文本作为文本而非标记放在页面上。其他宿主仍会获得与之前相同的文本结果。

咨询工作原理

orchestrator_consult 会选择能力评分最高的合格 Agent。评分相同时，priority 较低者优先；最后以 Agent ID 决定胜者。设置 consult.score_margin，即可让优先级在与最高分相差不超过该分值的 Agent 之间决定胜负：为低价或免费 Agent 设置较低的优先级和 5 分的余量，那么它的 92 分就会胜过付费 Agent 的 95 分。默认值 0 保持纯粹按评分排序。缺少所需能力或评分为 0 的 Agent 不符合条件。

选定的 CLI 会在其现有登录会话下运行，并返回一个响应信封：

如果选定的 Agent 失败，Orchestrator 会返回该失败，不会悄悄改用其他模型。

选择证据来源

consult:
  context_roots: [~/src]   # empty: the argument is not in the tool schema at all

consult:
  personas:
    skeptic: Doubt the premise before answering. Say what evidence would change your mind.
    migrations: Check every schema change for a lock and a way back.

带检查点的审查

咨询会询问一个 Agent。审查会向一个或多个已配置的审查者提出相同问题，并提供相同材料。

 plan review          approve + run          synthesize
 sends nothing   ──►  reviewers answer  ──►  host records conclusion
      │                    in parallel                │
      └─ scope              one-time token            └─ every Critical and Important kept
         reviewers
         secret hits
         request count

在 config.yaml 中启用审查：

consult:
  review:
    reviewers: [codex]          # standard: exactly one
    deep_reviewers: [codex, claude]  # deep: one to five
    roots: [~/src]              # context_paths and diff_ref are restricted to these trees
    checklist:                  # optional: added to every reviewer's instructions
      - a fix that patches the reported line but not the same mistake beside it
    escalate:                   # optional: paths that deserve a deep review
      - src/auth/*

checklist 用于记录审查中反复发现的问题。每一项都会发送给所有审查者，并显示在“特别检查以下内容：”之后；省略此项则指示保持不变。 escalate 指定标准审查不够充分时涉及的路径。当标准审查的 diff_ref 涉及其中某个路径时，计划会带上 escalate: {paths, suggestion: "mode=deep"}。这只是建议：审查人员仍按计划安排，是否重新规划为深度模式由宿主决定。glob 是针对相对于仓库的路径应用的 fnmatch 模式，因此 * 也会跨越 /。 如果路径名在 diff 中被 git 加上引号（名称中含有制表符、双引号或非 ASCII 字符，且启用了 core.quotePath），则永远不会匹配。

对于分支审查，跳过文件：diff_ref 允许 Orchestrator 自行运行 diff。

orchestrator_review(goal="...", diff_ref="main...HEAD", diff_repo="~/src/myproject")

A..B 对比两个提交，A...B 从它们的合并基点开始对比（即拉取请求中显示的内容），单个提交 X 则表示 X^..X（如果是合并提交，则使用其第一个父提交）。如果 roots 恰好指定一个目录，可以省略 diff_repo。diff_ref 不能与 context 或 context_paths 同时使用。

• 运行 diff 前，两端都会解析为提交 SHA，计划清单会显示这些 SHA。在计划生成和运行之间移动分支会改变审批哈希，因此令牌将不再匹配。
• 仅包含已提交的更改。不读取工作树和索引；请先提交，或通过 context 传入 diff。
• 仓库及其所在仓库的顶层目录都必须位于 roots 之下。如果 diff_repo 指向位于这些目录之外的仓库子目录，将被拒绝。git 数据存放在其他位置的检出也会被拒绝：位于 roots 之外的仓库的关联工作树、指向外部位置的 .git 文件，或 objects/info/alternates（git clone --shared）指定了外部目录。
• 运行 git 时会禁用外部 diff 程序、textconv 过滤器、替换引用和延迟获取，因此仓库配置中指定的程序无法在此次运行中执行。在部分克隆中，如果 diff 需要缺失的 blob，将会失败而不会获取它们。二进制文件会显示为“不同”，而不是显示字节内容。
• 作为 material 传入的清单会保留，并列在固定端点之后，且 material_verified 会保持为 false。
• 有一个限制：检查后，git 会按名称打开目录，因此，如果有人已经能在某个根目录内写入，并恰好在那一刻将仓库替换为符号链接，就能将其重定向。要彻底防止这种情况，需要在 git 外层使用操作系统沙箱。
• 审查人员会收到 diff，其标头包含相对于仓库的文件路径，不会包含仓库自身的位置。

context_paths 是一种便捷方式，可用于传入过大而无法粘贴到工具参数中的材料。Orchestrator 会读取这些根目录下指定的每个文件，并将其内容发送给审查人员。调用方提供的路径字符串也会作为文件标题和清单标签包含在内，因此绝对路径可能会泄露用户名或目录结构。如果这属于敏感信息，请改用 context 传入字节内容，并使用中性标签。

每个根目录都必须是指向现有目录的绝对路径。服务会在启动时检查，并在无法找到某个目录时拒绝启动，同时指出该目录，而不是启动后等到首次调用 context_paths 时才失败——那时轮到审查人员处理了。

工作流有意拆分如下：

1. orchestrator_review 会创建计划，不会发送任何内容。计划会显示审查者、材料大小、网页访问权限、请求数，以及疑似凭据文本的位置。suspect_hits 会额外标出包含长串随机样式令牌的行，而这些令牌不符合任何已知模式（例如，由 32 个字母和数字组成的字符串）。这只是猜测：十六进制字符串、UUID、完整性哈希、snake_case 或 kebab-case 名称，以及末尾带数字的纯字母名称（LoaderV2）都不会被标出；已经位于 secret_hits 中的行也不会被标出。它不会阻止操作，也不会存储结果。纯字母密钥或十六进制密钥可以绕过检查，因此请自行阅读材料。计划若在一天内无人执行，则会在下次制定审查计划时被丢弃。
2. 向用户展示该计划。orchestrator_review_run 会使用一次性令牌，并行请求审查者进行审查。
3. 阅读每项结果，并调用 orchestrator_finalize_review。仅有审查者回复时，审查仍处于 awaiting_synthesis 状态。

检查点会绑定范围并确保令牌只能使用一次，但它只是建议性的： MCP 不会为服务提供单独的人类沟通渠道，因此无法证明谁看到了计划。 人工审批取决于调用客户端的工具确认体验或外部审核关卡。

最终定稿必须保留所有机器可读的 Critical 和 Important 发现，即使其他审查者对此持不同意见。深度模式还要求宿主 Agent 在看到审查者的答案之前记录自己的发现。

重要

发送给审查者的材料可能会保留在相应供应商 CLI 自己的历史记录中。Orchestrator 无法删除 Codex、Claude Code、OpenCode、GitHub Copilot 或 Antigravity 的会话日志。

三阶段工作流

一次咨询只涉及一个问题。一次审阅只涉及一份材料。工作流则是一个完整的连贯任务：研究与规划、实施与测试、审阅与修复，并通过有次数上限的修复循环，让失败的测试和未解决的严重发现继续推进。它产生的每次咨询和审阅都会关联到一个 workflow_id。

 research? → plan → author_execution_prompt → implement
                                               └→ [apply_patch if delegated] → test

 test
 ├─ failed by default → fix → [apply_patch if delegated] → test
 └─ passed / advance_on_failed_test → review → synthesize

 synthesize
 ├─ clean → completed
 └─ open serious findings → fix

 `?` means research may be skipped. Fixing is capped at `max_fix_rounds`.

在 config.yaml 中启用它。如果没有 workflow: 块，就不会公布工作流工具；审阅工具也遵循同样的规则：

consult:
  host:
    runtime: claude              # asserted against ORCHESTRATOR_HOST_RUNTIME
    model: claude-opus-5         # optional; see "Host identity" below
  workflow:
    max_fix_rounds: 5
    roots: [~/src]
    advance_on_failed_test: false
    review_policy:
      different_from_implementer: true
      different_from_planner: false
    bindings:
      research:  {agent: codex-sol}
      plan:      {agent: codex-sol}
      author_execution_prompt: {executor: host}
      implement: {agent: nemotron-ultra, execution: patch}
      apply_patch: {executor: host}
      test:      {executor: host}
      review:    {agents: [codex-sol, claude-opus]}
      synthesize: {executor: host}
      fix:       {agent: codex-sol, execution: patch}

workflow: 要求设置 store_full_content: true，否则会在启动时拒绝运行。工作流就是其存储的计划、简报、补丁和报告；审阅步骤也无法在没有这些内容的情况下完成，因此应在启动时而非经过数个付费步骤后才报错。

roots: 遵循与 review.roots: 相同的规则——经过 ~/$VAR 展开后必须是绝对路径，且必须是启动时已存在的目录。相对路径会被拒绝，而不会根据客户端启动服务的位置进行解析；否则允许列表就会与文件中的定义不符。

模型不受阶段限制

绑定有以下三种形式，混用会导致启动错误：

省略 agent: 表示 auto：根据步骤的能力评分进行路由；评分相同时，按 priority 排序，然后按 Agent ID 排序，与 orchestrator_consult 使用的规则相同。GPT、Claude、DeepSeek、Gemini、Qwen——任何可通过受支持的运行时访问的模型，都可以执行其能力评分符合要求且允许使用相应模式的步骤。未绑定的步骤由主机执行，这是保守的默认设置，但有一个例外：review 不能由主机执行。因为它的产物是只能由审查服务写入的审查记录，而由主机记录结果会将综合结论直接写入步骤。由于未绑定的步骤默认由主机执行，如果配置中完全没有提及 review，系统会在 workflow_start 时拒绝启动，此时还没有产生任何开销；而不会等到研究、规划和实现都完成并付出开销后，才在审查步骤拒绝。

步骤根据为此新增的四项能力进行路由：planning、prompt_authoring、testing 和 synthesis，以及 coding、research 和 review。

绑定会在工作流创建时解析并生成快照，工作流所遵循的策略也会如此——轮次上限、advance_on_failed_test 和审查策略。编辑 config.yaml 不会改变运行中工作流的路由，也不会调整其上限；要进行这些更改，需使用 orchestrator_workflow_plan_replan 并单独审批。重新规划会重新决策你指定的步骤，其他步骤则继续使用工作流已有的路由。

预设

预设是为步骤命名的一组绑定，可用于避免每次启动时都逐一填写这些绑定。workflow_start(preset="cheap") 会按从低到高的顺序叠加各层配置：主机默认设置、bindings:、预设，然后是此次调用的 bindings 参数。预设只指定它要更改的步骤。

    presets:
      cheap:
        research: {agent: flash}
        plan:     {agent: flash}

预设会在加载配置时进行检查，检查方式与 bindings: 完全相同：如果 Agent 不存在、步骤不支持指定模式，或混用了不同形式，系统会拒绝启动，并指出 workflow.presets.<name>.<step>。名称必须为小写，并符合 [a-z][a-z0-9_-]{0,31}。启动时如果指定了未知预设，系统会拒绝启动并列出已配置的预设名称。预设名称不会被保存：工作流实际使用的是解析后的快照，因此之后编辑预设不会改变运行中的工作流。

执行模式及其可访问范围

Agent 上的 execution_modes 表示操作者的信任设置，而非能力。实际执行方式取决于该列表与运行时可实现功能的交集；若请求被拒绝，系统会说明是哪一方拒绝。

根目录允许列表和提示词指令都不构成隔离。如果运行时无法隔离，Agent 声明使用 isolated_write 时会在启动时被拒绝，而不是在路由时被拒绝。

没有委派的 Agent 会写入你的工作树。 在 patch 模式下，Agent 看不到你的检出内容——只能看到主机发送给它的上下文，就像审阅者一样——差异会返回给主机应用。在 isolated_write 模式下，它看到的是副本：位于 ~/.orchestrator-mcp/worktrees/<workflow_id>/<step_id>/ 下的工作树，检出的是最新已应用的结果（在主机应用任何内容前，这是工作流的基线）。通常在捕获差异并写入私有恢复副本后，该工作树会被删除。如果捕获失败，或恢复副本无法安全保留补丁，则会保留工作树，因为它可能包含唯一可用的副本。无论哪种情况，成功的步骤都会以 awaiting_host_apply 状态结束，分支由主机负责。ConsultAdapter 对此毫无变化：它仍只有三个动词，无法请求任何智能体操作，而写入能力则位于独立协议下的独立软件包中。

使用隔离运行前，有四件事值得了解：

• 差异是记录，而不是回复。 Orchestrator 会在工作树中运行 git add -A，并获取相对于基线的暂存差异，因此也会捕获 Agent 创建的文件——普通的 git diff <baseline>.. 会漏掉这些文件。模型的摘要会与补丁一同保存，作为对其工作的描述，而不会被当作工作记录。其命令列表也以相同方式保存，并且明确知道它并不完整：codex 会完全省略被沙盒拒绝的命令，不将它们纳入事件流。
• Agent 无法提交。 工作树的 git 目录位于沙盒之外，因此在沙盒内运行 git add、commit、stash 和 checkout 都会失败。Agent 会将工作留在树中，由此服务记录。该步骤的超时时间为 consult.workflow.execution_timeout_s（默认 900s），而不是为提问设置的 consult.timeout_s。
• 差异无法包含的两类内容，而且两者都不会悄无声息地通过。 在工作树内部创建的仓库——例如脚手架生成的子项目、引入的测试夹具，或任何 git init——都会导致 git add -A 拒绝整个树。该步骤会失败，并且工作树会被保留，错误中会包含其路径，因为此时其中存有工作的唯一副本。根据设计，git add -A 会跳过已忽略的文件，因此它们永远不会出现在补丁中；它们会列在步骤的 ignored 字段中，而不会随着工作树消失。
• 被读取以进行仓库捕获的仓库，是 Agent 启动前固定的那个。 工作树的 .git 是一个单行文件，指明其 git 目录所在位置；该文件位于 Agent 整个步骤都在其中写入的目录内。创建工作树时会读取该 gitdir，并在后续每次 git 调用时显式传入，因此捕获操作比较的对象不会由步骤可能改写的文件决定。

主机身份

(runtime, model) 是执行身份，而不是 Agent ID，并且只来自可信的启动配置——绝不来自工具参数。runtime 仍来自 ORCHESTRATOR_HOST_RUNTIME，它仍是权威来源；在 host: 下命名它是一种声明，若不匹配则会拒绝启动。

model 是环境无法提供的部分。有了它，主机自身运行时上的另一个模型便可被路由。没有它，该运行时上的所有 Agent 都会被排除——这就是当前的 consult 行为。请写入带版本的名称：身份必须能够证明不同，因此 opus 和 claude-opus 会被视为 claude-opus-5 并遭拒绝；完全没有版本的名称也会因无法证明其不同而遭拒绝，不会被假定为不同。

review_policy 也会根据此解析后的身份进行检查，因此指向同一模型的两个 Agent ID，无论拼写如何，都只算一名审阅者。

每个步骤两次调用

plan_step                    run_step | record_host_step
returns a preview       ──►  spends that step's token
and a one-time token         and runs or records it

不存在单次调用形式，也没有工作流级令牌。一项批准若同时涵盖研究、实现、每一轮修复和每次审阅，就等于没有明确批准任何事项。令牌所能证明的是快照完整性——正在运行的步骤就是预览过的步骤，且 Agent、模式和输入都相同。它无法证明有人看到了任何内容，因为 MCP 没有提供让此服务联系到人的渠道；这取决于客户端的工具确认体验或外部关卡。

工作目录必须解析到已配置的根目录之下。永远不接受 /，也不会从当前工作目录推断任何内容。未设置 allow_dirty 时，会拒绝脏工作树。

委派步骤只能看到宿主交给它的内容

这里没有任何内容会代替 Agent 读取你的代码仓库，因此委派步骤开始时，面前没有任何代码。orchestrator_workflow_plan_step(workflow_id, step, context) 会接收这些材料——通常是正在修改的文件的源代码——而宿主决定其中包含什么。没有这些材料，实现步骤就只有计划和简述，没有可供修改的内容；诚实的模型会如实说明这一点，而不是凭空编造一个从未见过的文件。

这些材料会在存储和发送之前，使用与其他内容相同的清理器进行脱敏；它们也包含在步骤的提示词哈希中，因此预览中描述的文本就是实际发送的文本。审查步骤会收到与编码步骤相同的材料。

测试结果是观测到的，而非声称的

编码 Agent 声称自己运行了测试，这一信息会作为报告内容保留，但绝不会被当作测试结果。TestReport 包含准确的命令、工作目录、退出代码、有长度限制的输出、耗时和受测提交，以及 reported_by；该字段由服务根据写入该行的是哪个工具来赋值，绝不会从调用方的负载中读取。由宿主编写的报告经过宿主认证，其来源信息也会如实标明。

reported_by: orchestrator 只有一个来源：绑定到 isolated_write 的 test 步骤。在这种情况下，退出代码来自 CLI 自身的事件流，而不是模型写入的任何内容。请仔细了解这能说明什么、不能说明什么。它意味着运行中报告的每条命令都返回了零；codex 会从该事件流中省略被沙盒拒绝的命令，因此这并不表示项目的测试套件确实运行了。若一个受隔离的测试步骤在测试期间编辑了文件，报告会在 changed_files 中列出这些文件；无论如何，工作树都会被删除，因此其中的任何内容都无法应用，但“测试通过”和“代码被修改到测试通过”不再看起来毫无区别。

测试失败时，流程会返回 fixing，而不是继续推进，除非设置了 advance_on_failed_test。

有两个字段会交叉校验，而不会并列存储。报告不能在退出代码非零或完全没有退出代码的情况下标记为 passed——从未读取退出代码的命令属于 skipped，这正是命令被拒绝或进程被终止时的情况；退出代码为零时，也不能标记为 failed。提交由服务根据工作流当前持有的提交来盖章，而不是从负载中读取：loop_done 会对两者进行比较，因此较早一轮的通过结果不能带到后续轮次。

apply_patch 是唯一一个全部工作内容都是对你的代码树产生副作用的步骤，而它成功执行的唯一证据，就是一个此前不存在的提交。若没有记录提交，或记录的是它开始时已有的提交，该步骤就会被拒绝并标记为 failed，而不是继续推进——因为未完成工作的步骤就是失败步骤，因此没有 applied: false 可写入。应用并提交补丁后，再次规划该步骤。

循环的终止条件

审核步骤会经过审核服务——它不会直接将综合结果写入工作流存储，从而绕过确保每项重要发现都得以保留的保障。发现项新增了 disposition（open、fixed、rejected、accepted_risk）字段，因为此前无法表示“尚未解决的发现项”；如果没有理由，系统会拒绝驳回或接受严重或重要发现项所带来的风险。

loop_done 在此处计算，绝不会交由审核者判定。只有在当前提交的权威测试通过、每位审核者的发现项均已解析并保留、没有仍处于 open 状态的严重或重要发现项、missing_serious 通过，且工作流不处于任何异常状态时，它才为真。如果达到 max_fix_rounds 时仍有严重发现项处于待处理状态，工作流会以 needs_attention 结束，而不是 completed。

审核后的修复轮次会携带仍处于待处理状态的发现项，这些发现项从审核记录中读取，而不是从工作流存储中读取，因此该轮次是对审核的回应，而不是再次尝试实现目标。若测试失败触发修复，则会改为携带失败的 TestReport。重新审核是对上一轮审核（parent_review_id）的复查：服务端会附加该审核中仍处于待处理状态的发现项，并要求审核者逐项确认或删除，同时仅在更改内容中查找新问题。将修复的差异作为此步骤的 context 发送，不要再次发送整个代码树。

执行约定：诚实界定范围

编码提示词由此处的代码组装：先放入我们的 EXECUTION_CONTRACT，然后将范围、已接受的计划、编写的简报和先前的发现项作为 JSON 负载。编写的简报是该负载中的数据，没有任何字段会将其转变为约定文本。

这体现的是代码所有权，而不是传输层面的强制边界。Claude Code 有真正的系统提示词通道；Codex、OpenCode、GitHub Copilot 和 Antigravity 接收到的是一段编译后的文本，因此在这些工具中，内容顺序只是一种提示词约定，意志坚定的模型可能会违背它。坦诚说明这一点，比夸大其作用更有意义。

安全模型

警告

脱敏会覆盖所有保留的数据库副本，但传输了什么取决于流程。 普通咨询会发送原始材料，同时存储经过清理的副本。审查通常会发送脱敏副本；secrets="send_as_is" 是明确发送原始内容的途径。工作流步骤材料在存储和传输前都会进行脱敏。检测依赖尽力而为的模式匹配，并非能完美检出的扫描器，因此无法识别特征的秘密仍可能漏过。请确保数据库不对外开放，或者在所选功能允许的情况下设置 store_full_content: false。

供应商的历史记录不在上述处理范围内。 发送给审查者的材料也会进入该审查者自己的 CLI 历史记录——Codex 写入 ~/.codex/sessions/，其他工具也会保留各自的日志。Orchestrator 无法脱敏或删除这些文件。不过，它会在 3 个地方读取这些文件中的 2 个字段：Codex 适配器会打开刚刚运行过的会话对应的 rollout 文件，以获取 CLI 不会通过其他方式报告的模型身份；还会打开最新的 rollout，以读取最新的 Codex CLI 速率限制数值。OpenCode 适配器会对刚刚运行过的会话执行 opencode export，原因相同——该运行时的事件流中没有模型身份信息。不会从这些文件中获取其他任何内容。GitHub Copilot 的情况则不同：其状态保存在 Orchestrator 自己的 ~/.orchestrator-mcp/copilot/home 下，每次咨询对应一个会话目录。恢复会话前，Orchestrator 会查找该目录；通过删除工具或 retention_days 删除咨询时，也会连同目录及其锁一起删除。Orchestrator 不会删除该目录中的其他内容，因此 CLI 自己的存储 session-store.db 会保留每个提示词和回答的副本，直到你删除该主目录。它还会在该主目录中读取 mcp-config.json，以获取要关闭的 MCP 服务名称，并向 settings.json 写入一项设置：disableAllHooks。

还有两项限制值得注意：

• CLI 错误文本会缩短，常见的秘密格式也会进行脱敏，但不常见的格式仍可能出现在返回的错误中。请勿将原始错误信封转发到不可信的位置。
• 调用方提供的 JSON Schema 被视为可信输入。其中异常的正则表达式可能会消耗大量 CPU。

Orchestrator 会检查结构、路由、权限，以及可观测到的模型身份。但它无法证明模型的事实性陈述属实。

    nemotron-ultra:
      runtime: opencode
      command: opencode
      model: opencode/nemotron-3-ultra-free
      scores: { coding: 60, reasoning: 60 }

每次咨询都在 Orchestrator 写入的配置下运行，你自己的配置不会有任何内容传入：权限一律拒绝，不启用 MCP 服务、插件、指令、项目 Agent 或提供方，并关闭共享和自动更新。OPENCODE_CONFIG 是合并而非替换配置，因此 XDG_CONFIG_HOME 也会指向一个空目录——你的全局配置无法访问，而不只是优先级较低。

工作目录为 ~/.orchestrator-mcp/opencode/<agent>，权限模式为 0700，配置文件权限模式为 0600，其中不存放其他内容。每个 Agent 使用独立目录，而非共用一个目录：目前所有 Agent 的文件都相同，但只要有一个版本让某个 Agent 需要写入专属内容，就可能导致咨询启动与读取配置之间发生竞争。特意将目录放在 $HOME 下而不是 /tmp：如果 Orchestrator 发现该目录的上级目录中存在 opencode.json 或 opencode.jsonc，就会拒绝运行——父级目录的权限高于自身；而这项检查只能在 OpenCode 读取配置链之前执行，因此每个祖先目录都必须是其他人无法写入的目录。目录之后不会被删除，也不能删除：OpenCode 会记录会话目录，并在恢复会话时重新解析它，因此每次运行都使用临时目录会破坏所有后续轮次。

启用前，有两项限制值得了解：

• 此运行时不支持网络搜索。 无论 web_search 设置为何，都会拒绝 source_mode: web，而不会在 Web 模式的约定下返回模型模式的回答。
• **即使失败，opencode run 也会以退出码 0 结束，**因此要根据事件流判断是否成功。未生成回答的运行会报告为失败，而不是空回答。

此运行时没有类似 Codex、Claude Code 和 Antigravity 的架构标志，因此响应格式会在提示词中说明。如果模型返回的 JSON 格式错误，系统会在同一会话中再次询问；第二次仍然失败，则咨询结束。

    copilot:
      runtime: copilot
      command: copilot
      model: auto
      scores: { coding: 60, reasoning: 60 }

**它的状态与你的状态分开。**Copilot 运行时，COPILOT_HOME 指向 ~/.orchestrator-mcp/copilot/home（模式为 0700），因此它的配置和会话与你自己的 ~/.copilot 分开保存，Orchestrator 既不会读取，也不会写入。尚未检查 CLI 在被告知使用其他主目录时是否仍会查找 ~/.copilot：在不同的 HOME 下，CLI 处于未登录状态，因此无法运行测试。请使用 COPILOT_HOME=$HOME/.orchestrator-mcp/copilot/home copilot login，在该主目录下登录一次。在 macOS 上，登录信息保存在系统钥匙串中，因此你已有的登录信息也会沿用。没有钥匙串时，GitHub 的文档说明令牌会保存在该主目录下的一个文件中，这也是命令中指定该路径的原因；这里尚未实际测试该路径。与其他所有凭据一样，令牌变量 COPILOT_GITHUB_TOKEN、GH_TOKEN 和 GITHUB_TOKEN 都不会传递给子进程；子进程只会获得固定的环境变量允许列表。

**仅作答，层层设限。**CLI 没有只读模式。每次咨询都会关闭所有内置工具，禁用 shell、write 和 url 类型，不提供自定义指令，禁用内置 MCP 服务且不启用远程会话，并且绝不会传递 --allow-all-tools。工作目录是一个全新空目录，之后会被删除；其中或其旁边即使放置了 .mcp.json 或 .github/mcp.json，也不会被列出或启动。关闭工具依赖于一个列出不存在工具的允许列表，CLI 接受这种做法，但 GitHub 文档没有对此作出说明，因此还会检查输出流：任何 tool.* 事件，或任何要求调用工具的消息，都会使该轮对话以 protocol_validation_failed 失败，而不是作为答案返回。该检查只识别 CLI 1.0.89 在工具调用时发出的事件，不涉及其他情况。要求它创建文件的提示词没有创建任何文件。

**这些限制未涵盖的情况。**允许列表关闭的是 MCP 服务的工具，而不是 MCP 服务本身。使用 copilot mcp add 添加到该主目录的 MCP 服务仍会在每次运行时启动并连接，其工具会被列为已禁用，因此模型无法调用它。因此，Orchestrator 也会对该主目录的 mcp-config.json 中列出的每个服务传递 --disable-mcp-server，就绪检查时也一样。该标志接受一个名称，不支持模式匹配，因此不会停止此文件中未列出的服务。该主目录中的钩子会在相同标志下于咨询期间运行，无论钩子位于 settings.json 还是 config.json 中（CLI 会自行将这些设置移入 settings.json），且没有任何标志可以阻止钩子运行。设置项 disableAllHooks 可以做到这一点，因此 Orchestrator 会在每次运行和就绪检查前将其写入该主目录的 settings.json，同时保留文件中的其他内容；之后，两个文件中的钩子都不会运行。移入 settings.json 时会覆盖其中已有的设置，因此，如果 config.json 中的 disableAllHooks 不为 true，两个钩子就会重新启用；此时会指出该 config.json，并拒绝运行。如果 settings.json 无法作为 JSON 对象读取（包括包含注释的情况），则会指出该文件并保持原样；运行会被拒绝，而不是在钩子处于启用状态时继续。未检查插件，也未检查该设置是否涵盖插件带来的内容。请将该主目录仅用于登录和会话，不要在其中放入其他内容。 会话。 提示词通过标准输入传入。consultation_id 会延续同一个 Copilot 会话：Orchestrator 为每个会话生成一个 UUID，并在确认该会话仍位于对应目录中后，按名称恢复会话。没有这项检查时，Copilot 会启动一个空会话，并像从未发生过这段对话一样作答，因此，从目录中移除的会话会返回 session_not_found。会话状态每次咨询都会新增一个目录，其中未掩码地保存每条提示词和回答。删除咨询时，会移除其目录及旁边的锁文件；删除拥有该咨询的审核或工作流时也会如此，retention_days 清理任务同样如此。无法删除的目录会保留，但删除操作仍会成功。对于 CLI 拒绝处理的首轮请求（例如使用了你的计划不提供的模型），会留下一个空目录，处理方式也相同。目录中的其他内容不会被移除。CLI 自己的存储 session-store.db 还会保存每条提示词和回答的第二份副本（已在 CLI 1.0.89 上检查）；如果某个会话对应的咨询已不在数据库中（例如来自此版本发布前的会话），该会话也会保留。删除 ~/.orchestrator-mcp/copilot/home 会清除其中所有内容，之后也无法继续使用曾经用过该目录的咨询。

费用。 Copilot 会报告高级请求数，但不报告价格，因此每轮的费用显示为未知，而不会是 $0.00，美元上限也无法将其计入。设置每轮上限（费用上限）。Token 计数仅针对当前轮，而不是整个会话的累计值；如果某轮的流中显示调用了多个模型，则会在 counts_incomplete 中说明。

启用前需要了解的限制：

• 此运行时不支持网页搜索。 无论 web_search 如何设置，都会拒绝 source_mode: web，而不会在网页模式的约定下提供模型模式的回答。
• 仅用于咨询。 会拒绝 isolated_write；patch 会返回差异供宿主应用。
• 没有 schema 标志，因此响应格式会在提示词中说明；如果回复格式错误，会在同一会话中再询问一次，和 OpenCode 一样。
• 它依赖 GitHub 未公开说明的行为：退出代码、事件流，以及就绪检查读取的消息，均已在 CLI 1.0.89 上检查。如果流中没有结束的 result 事件、该事件指向其他会话或包含非零退出代码、以事件形式开头的行不是 JSON，或者没有回答，则该轮会失败。遇到不认识的事件类型时会跳过而不作判断，因此流中的新内容可能在未被察觉的情况下通过。
• 你发送的内容会由 GitHub 和 Copilot 选择的模型背后的模型提供方处理；此外，CLI 还会向 GitHub 发送自己的遥测数据，Orchestrator 不会关闭此功能。请参阅隐私政策。

可选仪表板会显示 Agent、路由决策、提示词、回答、用量、延迟、错误、评审、记录的修复轮次和工作流。默认关闭，因为它可能会显示咨询数据库中存储的所有内容。

consult:
  dashboard:
    enabled: true
    editable: false
    host: 127.0.0.1   # loopback only; `localhost` also works
    port: 8765        # 1-65535

加载配置时，如果 host 不是回环地址，系统会拒绝启动，因为这些页面会显示所有存储的提示词和回答。

单独启动：

ORCHESTRATOR_CONFIG=/absolute/path/to/config.yaml orchestrator-mcp-dashboard

打开 http://127.0.0.1:8765，或访问 host 和 port 指向的地址。导航栏包含 Monitor、Workflows、Reviews 和 Scorecard，这些页面均为只读；只有设置 editable: true 时，才会显示 Agents 和 Reviewers。

/workflows 会列出所有工作流；工作流页面会显示其状态、相对于上限的修复轮次、启动时冻结的绑定关系，以及按实际发生顺序排列的步骤时间线。每个步骤都会链接到其咨询和评审。这些咨询无法通过其他途径访问。工作流页面为只读：删除操作仍需通过 MCP 工具进行，确认令牌也在那里。

/scorecard 会汇总每位评审者的回答，以及其发现的后续处理结果，数据与 orchestrator-mcp-server scorecard 显示的相同（?days=90 可将时间范围从 30 天延长）。该页面仅执行读取操作，因此不受 editable 限制。

设置 editable: true，即可在浏览器中管理咨询 Agent 和评审者选择。通过浏览器管理的 Agent 会写入 ~/.orchestrator-mcp/agents.yaml；仪表板绝不会改写 config.yaml、运行登录命令或发起咨询。

MCP 服务和仪表板都会在启动时读取配置。要应用更改，请重启它们。

配置

ORCHESTRATOR_CONFIG 指向 YAML 文件。如果未设置，服务会在其工作目录中查找 config.yaml。

支出上限

consult:
  spend:
    max_cost_usd_per_consultation: 2.0
    max_cost_usd_per_review: 5.0
    max_cost_usd_per_workflow: 25.0
    max_turns_per_consultation: 8
    max_turns_per_review: 12
    max_turns_per_workflow: 40

这六项均为可选项，默认均未设置，也就是没有上限，行为不会改变。每次进行咨询前都会检查该咨询的上限；每轮评审人员开始前都会检查评审的上限；每个工作流步骤开始前都会检查工作流的上限，包括评审人员，因为这些费用由工作流承担。检查会在消耗一次性令牌和启动任何子进程之前进行，因此拒绝不会产生费用，提高上限后，同一令牌仍可使用一次。

这三个作用域彼此嵌套，轮次会在触及最先达到的上限时被拒绝。咨询上限用于限制 orchestrator_consult：该工具接收 consultation_id，并恢复其背后的会话，因此首次调用之后的每次调用都会针对同一个付费 CLI 再消耗一轮。评审人员和工作流步骤也属于咨询，因此现在除了受上层上限限制外，还受各自上限的约束。

这能提供的保障是有限的，而限制本身正是重点：请求无法在发出之前定价，因此保证的是超过上限后的下一个请求会被拒绝，而不是支出绝不会超过上限。按这个意义来说，向五位评审人员分发任务算作一个请求。

不报告价格的 Agent 不会计入总额，因此总额只是一个下限。拒绝信息会指出这些 Agent，而不是把下限说成总和。错误代码为 spend_limit_reached。

如果你的路由中有任何部分采用固定费率方案，也请设置轮次上限。 Codex、GitHub Copilot 和 Antigravity 不会报告每轮价格，因此对它们设置美元上限不会计算任何费用，数值也永远不会离开 $0.00——它看起来像是一个限制，实际上却不是。无论 Agent 收取多少费用，轮次都会计入，因此 max_turns_per_review 和 max_turns_per_workflow 能限制金钱无法衡量的工作量。它们会在相同时间点进行检查，使用相同的错误代码拒绝，并像支出一样计数：根据轮次账本重新计算，因此重试的评审人员会将每次尝试都准确计数一次。

尚未进行任何轮次的咨询永远不会被拒绝。它尚未产生任何支出，因此还没有触及上限——这些上限阻止的是之后的轮次。

计划会附带估算值。 评审计划和工作流步骤预览会显示 estimates（每个 Agent 的令牌数和费用）以及 estimated_cost_usd，这些数据根据该 Agent 在同一模型上最近 50 次成功轮次拟合得出。这只是估算，并非报价：basis_turns 表示估算依据的轮次数；没有历史记录的 Agent 不会有估算值；价格轮次少于 3 次的 Agent，其费用为 null——因此只要有任何 Agent 未定价，总额就为 null，规则与上文相同。如果估算值会达到美元上限，计划会在 ceiling_warning 中说明。这只是建议；拒绝仍会依据实际支出进行判断。

观察一次运行

ORCHESTRATOR_LOG_LEVEL 可开启 stderr 日志记录：路由决策、启动和退出的子进程、获取和丢失的租约、审查者扇出，以及工作流步骤转换。默认值为 WARNING，因此普通服务不会输出日志；想了解运行缓慢的任务正在做什么时，可设为 INFO 或 DEBUG。

ORCHESTRATOR_LOG_LEVEL=INFO

记录仅写入 stderr，绝不会写入 stdout——stdout 是 MCP 传输通道，日志行会导致协议帧损坏。凭据格式的文本会在写入前，在渲染后的日志行中进行遮蔽，采用与数据库副本相同的尽力而为方式。

可能运行数分钟的工具——orchestrator_consult、 orchestrator_consult_many、orchestrator_review_run、orchestrator_retry_review 和 orchestrator_workflow_run_step——还会发送 MCP 进度通知：每 15 秒发送一次心跳，包含相对于配置超时的已用时间；每当 Agent 或审查者作出响应时，也会发送相应的数量。请求进度的客户端会收到这些通知；不请求进度的客户端不受影响。

consult 是唯一的顶层配置节。由于已移除直接 API 路由，0.4 之前版本中的 capabilities、model_list、router_settings 或 limits 配置会在启动时被拒绝。

系统要求

• macOS 或 Linux。目前尚未测试 Windows。
• Python 3.11 或更高版本。CI 目前会使用锁定文件测试 Python 3.11 至 3.14，并使用每个依赖项的最新版本测试 Python 3.14。
• Homebrew 或 uv。
• 使用 stdio 的 MCP 客户端，例如 Claude Code 或 Codex。
• 至少配置一个符合条件的 Agent。普通咨询需要使用另一个运行时；审查和工作流可以在主机的运行时中使用可证明确属不同版本的模型。

测试

离线测试套件使用虚拟 CLI Agent。无需网络，也不会消耗模型容量：

uv sync
uv run pytest -q -n auto

实时冒烟测试会使用配置中的 Agent：

ORCHESTRATOR_HOST_RUNTIME=claude uv run python smoke_consult_live.py
ORCHESTRATOR_HOST_RUNTIME=claude uv run python smoke_review_live.py
ORCHESTRATOR_HOST_RUNTIME=claude uv run python smoke_workflow_live.py

实时测试会发出真实请求，可能会消耗付费容量。除非有意为之，否则不要在 CI 中运行这些测试。

故障排除

明确不包含的内容

• 不直接路由到提供商 API，也不配置提供商 API 密钥。
• 普通咨询的 Agent 不会使用文件编辑、Shell 命令、MCP 工具或子 Agent；显式启用 Web 模式后，仅开放目标运行时的网页搜索功能。
• 不自动修复；由宿主 Agent 负责编辑和测试。工作流会记录并验证各阶段，但不会无人值守地运行任务。
• 不会委派任务写入实际工作树。isolated_write 会在一次性工作树中运行，且仅限运行时能够隔离执行的环境：Codex，以及 Orchestrator 的操作系统级沙箱能够正常工作的 OpenCode。Claude Code、GitHub Copilot 和 Antigravity 不支持此功能。所有补丁均由宿主应用。
• 不支持流式传输；每次咨询都会返回一个完整信封。
• 不支持由仪表盘发起咨询。
• 不会自动重新加载配置。
• 不支持多用户或共享状态。
• 回环仪表盘没有账户系统。

贡献

欢迎提交问题和拉取请求。

1. Fork 此仓库并创建分支。
2. 进行修改，并添加一个没有此修改就会失败的测试。
3. 运行 uv run pytest -q。
4. 提交拉取请求。

请勿将私有配置、登录数据和咨询数据库提交到代码库。报告 Bug 时，请提交问题，并附上已移除路径、凭据和其他私密信息的响应信封。

许可证

MIT · PyPI · GitHub issues · 隐私 · 安全

基于 Pydantic 和 Python MCP SDK 构建。