/multi-agent-orchestration

Agent CLI 完整参考手册

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/旧模型等历史条目不作为当前派发配方。 以下保留历史 CLI 研究；非当前 backend 不得据此扩张白名单。

本文档为 SKILL.md 的补充参考文档，汇总本机已安装的所有 Agent CLI 的命令规范。 更新日期：2026-08-12

0. 总览

默认 model 列来源：config/orchestration-personal.json 的 main_force.task_routing 与 backend_model_routing.<backend>.default_models（详见 SKILL.md §9）；缺省回落本表。Codex 默认行为按 codex_policy.policy 决定；个人偏好通常 explicit_only——只在用户明确要求时解封。

未安装 / 不可用：OpenClaw（symlink 已断）、Reasonix、Aider、Devin。

1. Claude Code（claude）

SKILL.md 已有详细覆盖。本节仅做参数速查补充。

1.1 核心参数速查

用法: claude [options] [prompt]

交互模式:     claude
批处理模式:   claude -p "prompt"  或  claude -p < prompt.md
流式输出:     claude -p --output-format stream-json "prompt"

1.2 Worker 启动模式

Provider registry（推荐）：

eval "$(bash scripts/render-runtime-profile.sh \
  --backend claude-code \
  --provider-registry config/claude-providers.local.json \
  --api-provider deepseek \
  --model v4flash \
  --mode batch \
  --prompt-file /tmp/task.prompt.md)"

bash -lc "$WORKER_COMMAND"

registry 里每个 provider 有自己的 base_url、auth_token_env / api_key_env、auth_type 和 models。render-runtime-profile.sh 会把模型别名解析成 provider 真实模型名，再交给 claude --model。

Settings 文件（兼容旧路径）：

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 \
    -p --output-format stream-json \
    --permission-mode acceptEdits \
  < /tmp/task.prompt.md

tmux 交互式（可纠偏/可接管）：

tmux new-session -d -s worker-claude -c /path/to/worktree \
  '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'

第三方 provider 不要裸跑 claude --settings ...。标准路径是先用 render-runtime-profile.sh 生成命令；该命令默认包 scripts/claude-provider-env.sh。wrapper 会清理继承的 ANTHROPIC_* provider 路由变量、从 registry 或 settings 导入 env、补齐 ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY、设置 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=1，并给 claude 注入 --setting-sources project,local。这样用户级 ~/.claude/settings.json 里的 MiniMax/其他 provider 不会覆盖本次 worker。

Claude 官方 worktree + tmux：

claude --worktree feature-x --tmux

1.3 已知坑点

• < redirect 在 tmux 内必须用 bash -lc 包裹
• -p + --output-format stream-json + tmux detached 组合可能导致启动即死
• 大 prompt（> 5KB）+ 大 codebase 会触发 autocompact thrash
• --bare、--safe-mode、CLAUDE_CODE_SIMPLE=1 会跳过或可能跳过 hooks；--setting-sources 排除 local 时项目 PreToolUse settings 也不会加载。需要依赖安装门禁的 worker 不得静默使用，spawn 会要求修正命令或显式接受 prompt_only_no_mechanical_enforcement 降级

2. Codex（codex）

2.1 核心参数速查

用法: codex [OPTIONS] [PROMPT]          # 交互模式
      codex exec [OPTIONS] [PROMPT]     # 批处理模式

2.2 子命令

2.3 Worker 启动模式

批处理：

codex exec -m o4-mini -s danger-full-access - < /tmp/task.prompt.md

tmux 交互式：

tmux new-session -d -s worker-codex -c /path/to/worktree \
  'codex -m o4-mini -s workspace-write'

tmux 批处理：

tmux new-session -d -s worker-codex -c /path/to/worktree \
  "bash -lc 'codex exec -m o4-mini -s danger-full-access - < /tmp/task.prompt.md'"

本地开源模型：

codex exec --oss --local-provider ollama -m qwen2.5-coder -s workspace-write - < /tmp/task.prompt.md

2.4 Profile 路由

Codex 的 profile 机制通过 -p / --profile 加载 $CODEX_HOME/<name>.config.toml：

# 使用自定义 profile
codex exec -p legal-worker -m o4-mini -s danger-full-access - < /tmp/task.prompt.md

# 覆盖配置项
codex exec -c 'model="o3"' -c 'shell_environment_policy.inherit=all' - < /tmp/task.prompt.md

0.147 实测（2026-08-30）：profile 是 $CODEX_HOME/<name>.config.toml 独立文件（顶层键，无 [profiles.X] 包裹）。把 [profiles.X] 内嵌进 config.toml 是 legacy 写法，-p X 会直接报错拒绝加载（cannot be used while config.toml contains legacy [profiles.X]）。本机已装 ~/.codex/spark.config.toml（GPT-5.3-Codex-Spark 档，见 §2.5）。

2.5 与 Skill 集成要点

• Codex 的 exec 是 worker 的标准入口，不支持 < redirect 时同样需要 bash -lc 包裹
• -s danger-full-access 是 worker 自动化的常用选项，但需确保 worktree 隔离
• Codex 没有内建的 --system-prompt 参数，系统提示需在 prompt 文件或 config.toml 中设定
• codex apply 可在 worker 完成后单独应用 diff，作为 PM 收口的替代路径
• 本机 codex 可能是已经固定 --sandbox / --ask-for-approval 的安全 launcher。render-runtime-profile.sh 只有在可读脚本中证明两个值与请求完全一致时才省略重复参数；否则继续显式传参。不要把“参数重复导致 CLI exit 2”误判成 Agent/Orca 启动失败。
• launcher 重复 flag 实测（2026-08-30，spark-lane 首派撞坑）：本机 ~/.local/bin/codex launcher 固定 --sandbox danger-full-access --ask-for-approval never。给 --command 显式带 -a never -s workspace-write 会与 launcher 注入值重复，codex 以 cannot be used multiple times exit 2，终端退化成死 zsh（后续 send 的中文 prompt 会被 zsh 当命令执行）。正确姿势：render-runtime-profile.sh --sandbox danger-full-access --approval never（与 launcher 一致）→ 输出省略 flag 的 codex -p <profile>。经该 launcher 启动的 codex 沙箱实际恒为 danger-full-access，隔离靠 Orca worktree 兜底；profile 文件里的 sandbox_mode 会被 launcher 的 CLI flag 覆盖，不起收紧作用。

2.6 GPT-5.3-Codex-Spark 额度 lane（2026-08-30 实测接入）

3. OpenCode（opencode，历史候选、不可派发）

3.1 核心参数速查

用法: opencode [project]                # 交互 TUI
      opencode run [message..]          # 批处理
      opencode acp                      # ACP 服务器

3.2 子命令

3.3 Worker 启动模式

批处理：

opencode run --model anthropic/claude-sonnet-4-20250514 "$(cat /tmp/task.prompt.md)"

tmux 交互式：

tmux new-session -d -s worker-opencode -c /path/to/worktree \
  'opencode --model anthropic/claude-sonnet-4-20250514'

ACP 服务器：

tmux new-session -d -s worker-opencode-acp -c /path/to/worktree \
  'opencode acp'

Web 界面：

opencode web --port 8080

3.4 Provider 管理

OpenCode 的 provider 通过 opencode providers 管理，支持多 provider 配置：

opencode providers          # 查看已配置 provider
opencode models             # 列出所有可用模型
opencode models anthropic   # 列出 Anthropic provider 下的模型
opencode stats              # 查看 token 用量

模型格式为 provider/model，例如 anthropic/claude-sonnet-4-20250514、openai/gpt-4o、google/gemini-2.5-pro。

3.5 与 Skill 集成要点

• opencode run 支持直接传 message 参数（不需要 stdin redirect），比 Claude Code / Codex 更方便
• opencode acp 可直接作为 ACP 服务器，适合已有 ACP client/adapter 的项目
• opencode pr <number> 可自动拉取 PR 分支并启动，适合 PR review worker
• opencode stats 提供内置成本统计，PM 可直接查询 worker 消耗

4. Hermes Agent（hermes）

4.1 核心参数速查

用法: hermes                    # 交互模式（默认 TUI）
      hermes chat -q "prompt"   # 单次查询
      hermes --cli              # 强制经典 REPL

4.2 关键子命令

4.3 Worker 启动模式

单次查询：

hermes chat -q "$(cat /tmp/task.prompt.md)" -m gpt-4o --yolo

tmux 交互式：

tmux new-session -d -s worker-hermes -c /path/to/worktree \
  'hermes --worktree --yolo -m gpt-4o'

tmux + worktree 隔离（Hermes 原生支持 --worktree）：

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

ACP 服务器：

tmux new-session -d -s worker-hermes-acp -c /path/to/worktree \
  'hermes acp'

4.4 Pooled Auth 机制

Hermes 独特的池化凭证系统，适合多 provider 路由：

hermes auth add <provider>     # 添加凭证到池
hermes auth list               # 列出池内凭证
hermes auth remove <p> <t>     # 移除凭证
hermes auth reset <provider>   # 重置耗尽状态
hermes fallback add            # 添加 fallback provider
hermes fallback list           # 查看 fallback 链

4.5 与 Skill 集成要点

• Hermes 的 --worktree 是内建的，比 Claude Code 的 --worktree 更早支持
• Pooled auth + fallback chain 机制让 Hermes 天然适合多 provider 路由场景
• --pass-session-id 可让 PM 精确追踪 worker session
• --yolo 等同于 Claude Code 的 --dangerously-skip-permissions
• Hermes 有丰富的子命令生态（kanban、cron、gateway），可作为编排层的补充工具
• hermes profile 支持多 profile 隔离，类似 Claude Code 的多 settings 文件

5. Kimi CLI（kimi）

5.1 核心参数速查

用法: kimi                        # 交互模式
      kimi --print -c "prompt"    # 批处理模式
      kimi --acp                  # ACP 服务器

5.2 Worker 启动模式

批处理：

kimi --print -c "$(cat /tmp/task.prompt.md)" -m kimi-latest -y

tmux 交互式：

tmux new-session -d -s worker-kimi -c /path/to/worktree \
  'kimi -y -m kimi-latest'

ACP 服务器：

tmux new-session -d -s worker-kimi-acp -c /path/to/worktree \
  'kimi --acp'

流式输出：

kimi --print --output-format stream-json -c "$(cat /tmp/task.prompt.md)"

5.3 与 Skill 集成要点

• Kimi CLI 的参数风格接近 Claude Code（--print、--mcp-config、--yolo）
• -w / --work-dir 可直接指定工作目录，不需要 cd 再启动
• --agent-file 支持自定义 agent 规范，适合给 worker 注入特定角色行为
• 原生支持 stream-json 输出格式，PM 可直接解析
• kimi 和 kimi-cli 是同一个二进制（两个入口）

5A. CodeBuddy CLI（codebuddy）

2026-06-21 实测：CodeBuddy 桌面端内置 codebuddy CLI。当前应使用正式 codebuddy backend，不再称为 custom CLI；它不同于 Moonshot 官方 kimi CLI。

5A.1 二进制位置与版本

本节只记录已有桌面端的二进制位置，不授权 worker 安装软件、写 shell 配置或创建全局 symlink。缺失时按 SKILL.md Execution Authority 报告 BLOCKED；只有用户明确批准精确命令后才能修改环境。

codebuddy --help 的模型列表可能滞后。2026-06-21 实测中，help 只列出 kimi-k2.5，但 --model kimi-k2.6 能正常调用，交互界面显示 Kimi-K2.6 · internal Usage Billing。

5A.2 核心参数速查

用法: codebuddy [options] [prompt]

交互模式:     codebuddy
批处理模式:   codebuddy --print "prompt"

5A.3 tmux Worker 启动模式

推荐 PM 先用 spawn-worker.sh 创建 worktree，再在该 worktree 内启动交互式 CodeBuddy：

tmux new-session -d \
  -s wr-ch07-codebuddy-kimi-k26-r1 \
  -c /path/to/worktree \
  'bash -lc '\''exec "/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy" \
    --model kimi-k2.6 \
    --permission-mode bypassPermissions \
    --session-id wr-ch07-codebuddy-kimi-k26-r1'\'''

短 smoke test 可用：

"/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy" \
  --print \
  --model kimi-k2.6 \
  --permission-mode default \
  --tools '' \
  --output-format text \
  '只回复 OK，不要做任何文件操作。'

5A.4 实测注意事项

• 每个新 worktree 首次启动会询问信任目录。PM 只选择 Trust folder only，不要信任 worktrees/** 父目录。
• --model kimi-k2.6 虽不一定出现在 help 列表中，但可通过短提示词和交互界面的 Kimi-K2.6 标识确认。
• 书稿评测 r1 已完整跑通：review、正文修订、self-check、result、metadata、commit、sentinel done。
• worker 可能在提交后更新 metadata.json 的 commit_sha / status 字段，导致一个未提交尾巴。PM 收口时要检查 git status --short，若只剩 metadata 完成态字段，可补一个 chore(eval): finalize codebuddy kimi metadata 提交。
• 交互式 r2 bootstrap 曾出现 CodeBuddy 内部 shell/write 工具长时间挂起。若 1-2 分钟没有 STATUS.json，PM 应先 Esc 中断，检查无业务改动后重启 tmux session；必要时由 PM 仅在 Session Context 中写入“重启中”状态，再投递 Full Prompt。业务正文和报告仍应由 worker 完成。
• 对长任务优先交互式 tmux，不建议一发 --print 跑完整书稿 worker；交互式模式便于处理信任目录、权限、工具挂起和 prompt 纠偏。

6. Gemini CLI（gemini）

6.1 核心参数速查

用法: gemini [query..]            # 交互模式
      gemini -p "prompt"          # 非交互（headless）模式

6.2 子命令

6.3 Worker 启动模式

批处理：

gemini -p "$(cat /tmp/task.prompt.md)" -m gemini-2.5-pro -y

tmux 交互式：

tmux new-session -d -s worker-gemini -c /path/to/worktree \
  'gemini -y --approval-mode auto_edit -m gemini-2.5-pro'

审批模式分级：

# plan 模式（只读，不执行）
gemini --approval-mode plan -p "分析这个代码库的架构"

# auto_edit 模式（自动批准编辑，但执行命令仍需确认）
gemini --approval-mode auto_edit -p "修复这个 bug"

# yolo 模式（全自动）
gemini --approval-mode yolo -p "重构这个模块"

6.4 与 Skill 集成要点

• Gemini CLI 的 --approval-mode 提供最细粒度的审批控制（4 级）
• -p 是 headless 模式的标准入口，支持 stdin pipe
• 原生支持 stream-json 输出格式
• --experimental-acp 标记为实验性，ACP 稳定性待验证
• Gemini CLI 的子命令生态（extensions/skills/hooks）与 Claude Code 结构类似
• --sandbox 是布尔开关（不像 Codex 有多级 sandbox mode）

7. QoderWork CLI（qoderclicn / qodercli）

详细研究见 references/07-qoderwork-cli-worker.md。本节为速查补充。

7.1 核心参数速查

用法: qoderclicn [options] [query...]

交互模式:     qoderclicn
批处理模式:   qoderclicn -p "prompt"

7.2 可用模型

复测：2026-08-05 CLI 1.0.45 --list-models。推荐用具体名（-m Qwen3.8-Max），旧 alias 兼容但映射可能过时。

7.3 关键限制

• 不能从 QoderWork 桌面端内部启动（SDK 环境变量干扰），必须在干净终端运行
• 认证和额度与桌面端共用 ~/.qoderworkcn/
• CN 版与国际版是两个 CLI：CN 版为 /Applications/QoderWork CN.app/Contents/Resources/bin/qoderclicn，国际版为 /Applications/QoderWork.app/Contents/Resources/bin/qodercli
• /usr/local/bin/qoder 可能指向旧 Qoder 编辑器 CLI，不是 QoderWork agent CLI
• 有 --worktree 参数，但多 Agent 编排建议仍由 PM 用 spawn-worker.sh 手动创建 worktree / 分支 / Session Context，再用 tmux -c <worktree> 启动 CLI
• 新 worktree 首次启动会询问信任目录，只选择当前 folder
• 书稿评测中 qmodel_latest 已确认显示为 Qwen3.7-Max Model，可跑 writing-reviewer 单章 worker

8. Rudder（rudder）

Rudder 更偏项目管理/编排工具而非纯 coding agent，但其 agent 子命令可作为 worker。

8.1 核心参数速查

用法: rudder [options] [command]

启动:       rudder run            # 引导启动 + 运行
诊断:       rudder doctor         # 健康检查

8.2 与 Skill 集成要点

• Rudder 的 worktree:make / worktree:cleanup 可作为 worktree 生命周期管理的替代工具
• rudder agent 可操作 agent，但具体能力取决于 Rudder 实例配置
• 更适合作为编排层的补充（issue 追踪、worktree 管理），而非纯 coding worker
• 与 SKILL.md 的 spawn-worker.sh 思路类似，但走 Rudder 自己的基础设施

9. 跨 CLI 对比矩阵

9.1 Worker 能力对比

9.2 tmux Worker 启动模板对比

# === Claude Code ===
tmux new-session -d -s W -c WT "$WORKER_COMMAND"  # WORKER_COMMAND from render-runtime-profile.sh

# === Codex ===
tmux new-session -d -s W -c WT 'codex -m o4-mini -s workspace-write'

# === OpenCode ===
tmux new-session -d -s W -c WT 'opencode --model anthropic/claude-sonnet-4-20250514'

# === Hermes ===
tmux new-session -d -s W -c WT 'hermes --yolo -m gpt-4o'

# === Kimi ===
tmux new-session -d -s W -c WT 'kimi -y -m kimi-latest'

# === Gemini ===
tmux new-session -d -s W -c WT 'gemini -y --approval-mode auto_edit -m gemini-2.5-pro'

# === QoderWork ===
tmux new-session -d -s W -c WT 'qoderclicn -m qmodel_latest --permission-mode auto'

# === CodeBuddy ===
tmux new-session -d -s W -c WT 'codebuddy --model kimi-k2.6 --permission-mode bypassPermissions'

# === ZCode（无 TUI，走 skill driver：长驻 app-server + 事件渲染 + stdin→session/send）===
tmux new-session -d -s W -c WT 'python3 <skill>/scripts/zcode-worker-driver.py'

其中 W = session name, WT = worktree path。Claude Code 实际派发时优先用 render-runtime-profile.sh 生成 WORKER_COMMAND，避免漏掉 registry/settings wrapper 参数。

10. 选用建议