/multi-agent-orchestration

模型选择与执行模式矩阵

2026-09-30 当前合同：日常 Claude Code/Codex；CodeBuddy、独立 ZCode CLI/MiniMax Code、Qoder CN、千问办公仅用户指定时使用。QoderWork 已移除。按需启动与权限以 26-optional-cli-backends.md、27-qwenwork-cli-worker.md 为准；本文 QoderWork/旧 ZCode 无 TUI/旧模型等历史条目不作为当前派发配方。 本文档为 SKILL.md 的 Level 2 参考文档，提供模型路由和执行模式选择的完整细节。 读取时机：规划并行任务、为 Agent 分配模型、选择 Subagent / Agent Teams / tmux 时。

1. 模型分级（L0 / L1 / L2）

模型路由只服务 worker，不绑定 PM 所在产品。当前白名单读取 policy 与 ref 26；本文中 OpenCode、Hermes、Kimi、Gemini、Rudder、custom 等段落仅保留历史调研价值，不构成派发授权。判断顺序是：任务复杂度 → 当前可用额度 → 白名单 worker backend → 模型/环境变量。

1.1 能力定义

1.2 任务-模型路由

经验法则：任务描述包含"理解/分析/重构/设计"→ L2；包含"添加/补充/翻译/复制"→ L0；其余默认 L1。

1.3 额度 Profile

旧 QoderWork/custom/其他非白名单 Profile 不可派发。可选 CLI 按 ref 26 单独配置。

默认 Claude Code worker 使用 claude-provider。推荐把多个第三方 provider 合并到一个本地 registry，参考 config/claude-provider-registry.example.json；每个 provider 写自己的 base URL、key 环境变量和模型清单，真实 registry 放 ignored local 文件。旧的每 provider 一个 settings JSON 路径继续兼容，参考 config/claude-provider-settings.example.json。标准命令由 render-runtime-profile.sh 生成，并默认包 scripts/claude-provider-env.sh，排除用户级 ~/.claude/settings.json 的 provider/model 覆写。只有用户明确要走订阅/OAuth 时，才使用 claude-oauth 并清理 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和第三方 ANTHROPIC_BASE_URL。

认证模式以显式配置为准：registry 的 auth_type 是唯一来源；settings 路径可向 renderer/wrapper 传 --auth-type auth_token 或 --auth-type api_key，默认仍为 both。单认证模式分别 unset 相反变量；auth_token_clear_api_key 保留 API_KEY 为空串的旧语义。registry 与 CLI 同时声明时拒绝，不能按 provider 名称、URL 或文件名推断并覆盖认证方式。settings 中仍有相反变量键时，单认证模式拒绝启动，以免 Claude 重读原配置后复活该变量；须先由配置所有者移除相反键。此修复只证明启动环境遵守显式选择，不证明某个 provider 的历史停滞原因或真实请求已恢复。

1.4 各执行模式下指定模型

Claude Code Agent Teams 模式：如果要走第三方 API，先让该 session 通过 registry 或 settings 加载 provider env，并显式指定 --model <provider-model>。registry 模式可用模型别名，但渲染命令时必须解析成 provider 真实模型名。

Claude Code tmux worker（推荐 provider registry）：tmux 启动的是一个后台独立终端 session，可 attach 或 capture。默认启动交互式 Claude Code，由 wrapper 从 registry 解析 provider env。模板见 config/claude-provider-registry.example.json。

eval "$(bash scripts/render-runtime-profile.sh \
  --backend claude-code \
  --provider-registry config/claude-providers.local.json \
  --api-provider glm \
  --model glm52 \
  --provider-slot glm-1)"

tmux new-session -d \
  -s worker-claude-provider \
  -c .claude/worktrees/tmux-feature \
  "$WORKER_COMMAND"

Claude Code tmux worker（兼容 settings）：旧路径仍可直接指定 provider settings。

tmux new-session -d \
  -s worker-claude-provider \
  -c .claude/worktrees/tmux-feature \
  'bash scripts/claude-provider-env.sh --settings /path/to/provider.settings.json --model provider-model -- claude --settings /path/to/provider.settings.json --model provider-model --permission-mode auto'

Claude Code tmux worker（可选订阅/OAuth）：只在用户明确要求使用 Claude 订阅/OAuth 时启用，启动命令里清掉第三方 provider 环境，避免误走 API key 或代理服务。

tmux new-session -d \
  -s worker-claude-oauth \
  -c .claude/worktrees/tmux-feature \
  'env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_BASE_URL claude --permission-mode auto'

Codex tmux worker：用 -m 或 profile 指定模型。

tmux new-session -d \
  -s worker-codex-l1 \
  -c .claude/worktrees/tmux-feature \
  'codex exec -m <codex-model> -a never -s danger-full-access - < /tmp/task.prompt.md'

OpenCode 历史候选（不可由当前 Skill 派发）：以下命令仅供旧实验复盘。

tmux new-session -d \
  -s worker-opencode-l1 \
  -c .claude/worktrees/tmux-feature \
  'opencode run --format json --model <provider/model> "$(cat /tmp/task.prompt.md)"'

OpenCode ACP server：仅在 PM 侧已有 ACP client/adapter 时使用。

tmux new-session -d \
  -s worker-opencode-acp \
  -c .claude/worktrees/tmux-feature \
  'opencode acp'

自定义 CLI 历史候选（不可由当前 Skill 派发）：以下命令不属于当前四后端合同。

tmux new-session -d \
  -s worker-custom \
  -c .claude/worktrees/tmux-feature \
  '<agent-command> < /tmp/task.prompt.md'

Hermes Agent tmux worker：Hermes 原生支持 --worktree，pooled auth 支持多 provider 自动 fallback。

tmux new-session -d \
  -s worker-hermes \
  -c .claude/worktrees/tmux-feature \
  'hermes --yolo -m gpt-4o'

或使用 Hermes 原生 worktree：

tmux new-session -d \
  -s worker-hermes \
  'hermes --worktree tmux-feature --yolo -m gpt-4o'

Kimi CLI tmux worker：原生 stream-json 输出，适合 PM 解析。

tmux new-session -d \
  -s worker-kimi \
  -c .claude/worktrees/tmux-feature \
  'kimi --print --output-format stream-json -y -m kimi-latest -c "$(cat /tmp/task.prompt.md)"'

Gemini CLI tmux worker：--approval-mode 提供 4 级审批控制。

tmux new-session -d \
  -s worker-gemini \
  -c .claude/worktrees/tmux-feature \
  'gemini -y --approval-mode auto_edit -m gemini-2.5-pro'

批处理模式：

tmux new-session -d \
  -s worker-gemini \
  -c .claude/worktrees/tmux-feature \
  "bash -lc 'gemini -p \"\$(cat /tmp/task.prompt.md)\" -m gemini-2.5-pro -y'"

QoderWork CLI tmux worker：消耗 QoderWork 平台额度，可利用元典/企查查 MCP 工具链。必须在干净终端启动（不能从 QoderWork 桌面端内部 session 启动）。

tmux new-session -d \
  -s worker-qoderwork \
  -c .claude/worktrees/tmux-feature \
  'qoderclicn -m qmodel_latest --permission-mode auto'

批处理模式：

tmux new-session -d \
  -s worker-qoderwork \
  -c .claude/worktrees/tmux-feature \
  "bash -lc 'qoderclicn -p \"\$(cat /tmp/task.prompt.md)\" -m qmodel_latest'"

交互式 tmux session：只在需要人工接管时用 /model 或 CLI 内部菜单切换模型。

# 启动 Claude Code 后切换模型
tmux send-keys -t session-name "/model" Enter
sleep 1
# 用 Up/Down 导航到目标模型（次数取决于菜单排序）
for i in 1 2 3; do tmux send-keys -t session-name Down; sleep 0.05; done
tmux send-keys -t session-name Enter

或在 prompt 文件开头声明模型偏好：

[模型建议: 这是 i18n 任务，适合轻量模型。请先 /model 切换。]

1.5 运行时升降级

升级（→ L2）：Agent 反复失败 >2 次、任务复杂度超预期

降级（→ L0）：架构设计完成进入实现、剩余为重复性工作

Agent Teams 模式下模型在创建时指定，升降级需重新创建 Teammate。

tmux 交互模式下：

# 中断 Agent 并切换模型
tmux send-keys -t session-name C-c
sleep 0.5
tmux send-keys -t session-name "/model" Enter
# 导航到目标模型后继续
tmux send-keys -t session-name -l -- "模型已升级，继续刚才的任务。"
tmux send-keys -t session-name Enter

Claude Code -p 批处理模式下，推荐停止旧 worker，保留 worktree，按更高 profile 重启，并在 prompt 中说明“接续当前 worktree 已有改动，不要回退”。

1.6 批量调度模板

# tasks.conf 格式: name  backend  worktree路径  profile  prompt文件
worker-1  claude    .claude/worktrees/i18n-fixes      claude-provider  /tmp/task-i18n.txt
worker-2  codex     .claude/worktrees/file-ops        codex-l1         /tmp/task-fileops.txt
worker-3  opencode  .claude/worktrees/ui-copy         opencode-l0      /tmp/task-copy.txt
worker-4  claude    .claude/worktrees/refactor-core   claude-provider  /tmp/task-refactor.txt
worker-5  hermes    .claude/worktrees/api-integration hermes-l1        /tmp/task-api.txt
worker-6  kimi      .claude/worktrees/translation     kimi-l0          /tmp/task-trans.txt
worker-7  gemini    .claude/worktrees/docs-update     gemini-l1        /tmp/task-docs.txt
worker-8  qoderwork .claude/worktrees/legal-research  qoderwork-l1     /tmp/task-legal.txt
worker-9  custom    .claude/worktrees/custom-agent    custom-cli       /tmp/task-custom.txt

2. 执行模式选择

2.1 三档 Claude Code worker

--max-turns、--worktree、--tmux、--bg 的可用性随 Claude Code 版本变化；使用前以当前 claude --help、claude agents --help 为准。无论使用哪一档，worker 都必须写 .claude/agent-sessions/{session}/STATUS.json、RESULT.md、PATCH_SUMMARY.md。

2.2 执行后端对比：Subagent / Agent Teams / tmux Session / ACP

2.3 路由矩阵

路由决策树：

任务时长 ≤15 分钟？
├─ 是 → Subagent
└─ 否 → 需独立 git 分支？
    ├─ 否 → Subagent
    └─ 是 → 当前 PM 是 Claude Code 且 Agent Teams 已启用？
        ├─ 是 → Agent Teams（split-panes）
        └─ 否 → 需要跨产品或额度路由？
            ├─ 是 → tmux worker（Claude/Codex/OpenCode）
            └─ 否 → tmux worker

2.4 混合模式

PM（Team Lead）
├── Subagent A: review PR #1              ← 分钟级，共享上下文
├── Subagent B: 研究 X 接入方案            ← 分钟级，共享上下文
├── Teammate 1: feat/i18n                 ← 小时级，L0，独立上下文
└── Teammate 2: feat/refactor             ← 小时级，L2，独立上下文

PM 在等待 Teammate 期间用 Subagent 处理短任务，不空闲。

tmux worker 模式下，将 Teammate 替换为独立 CLI session 即可。