awslabs/cli-agent-orchestrator · 上手攻略

  • 仓库：awslabs/cli-agent-orchestrator
  • 链接：https://github.com/awslabs/cli-agent-orchestrator
  • 分类：skill（多 agent 编排 / AI 编码 CLI 调度）
  • 作者：spark
  • 更新：2026-09-01

1. 是什么

CLI Agent Orchestrator（简称 CAO，读作 "kay-oh"）是 AWS Labs 开源的多 agent 编排框架。它在你本机起一个 cao-server（FastAPI），用 tmux 隔离出一组"终端会话"，每个会话里跑一个真实的 AI 编码 CLI 进程（Claude Code / Kiro / Codex / Cursor / Antigravity / Grok Build / Hermes / Kimi / MiniMax Code / GitHub Copilot / OpenCode / OMP 等十余种），然后给 supervisor agent 一套 MCP 工具，让它把任务派发给这些 worker。Worker 之间通过 inbox 互发消息，状态机由服务器统一管理。

核心理念（来自仓库 README）：agents remain full CLI processes with their native authentication and capabilities——CAO 不重写 agent，它只调度 agent。这意味着你已经付费、已经登录好的 Claude / Kiro / Codex 账号直接可用，不会被框架套一层 SDK。

截至 2026-09-01，PyPI 最新版本为 2.5.0（2026-08-28 上传，58.3 MB sdist，SHA256 35bd7ac868700b1e52a6d1709c6b78386fd75602d3538db01ceb269780301100）。仓库 README 主分支会持续更新，建议先用 uv tool install 锁 main 分支或显式 PyPI tag。⚠️ PyPI 与 GitHub README 之间的版本号不同步时（PyPI 2.5.0 vs GitHub README 默认指向 main），以 cao --version 实际输出为准。

2. 解决什么问题

把多个 Claude Code / Kiro 实例手工开 tmux 窗口、自己复制粘贴任务、自己 ctrl-C 切换——这是 2025-2026 年多 agent 协作的典型手工流。痛点：

  1. 状态不同步：5 个窗口里谁 idle、谁在跑、谁报错，靠人眼看。
  2. 通信靠剪贴板：worker 之间要传文件路径 / diff / 报错日志，复制粘贴串味。
  3. 调度无规则：supervisor 想"先并行 3 个 codegen，再串行 1 个 review"，纯靠人手排。
  4. 凭据碎片化：每个 CLI 各自一套登录态，迁到 Docker / 远程就丢。

CAO 用三件套解决：① 服务器集中维护 session 状态（SQLite 持久化）；② inbox 服务做 agent 间消息总线；③ MCP 工具把"创建 worker / 派发任务 / 收结果"暴露给 supervisor agent，于是 supervisor 可以用自然语言+工具调用来编排。

⚠️ 它不是：不是 Claude Agent SDK 的替代、不是 LangGraph 的替代、不是 OpenAI Swarm 的替代。它专门管"已经在跑的 CLI 进程"，不做 LLM 调用抽象。

3. 快速安装

3.1 前置依赖（README 列出的硬约束）

# Python 3.10+，tmux 3.3+，uv（推荐），并至少一个 provider CLI 已登录
python3 --version   # ≥ 3.10
tmux -V             # ≥ 3.3
# uv 见 https://docs.astral.sh/uv/
# provider CLI 至少装一个并完成登录，例：
#   kiro cli / claude code / codex cli / antigravity / hermes / kimi ...
# 详细认证流程见仓库 docs/<provider>-cli.md

⚠️ tmux 版本低于 3.3 在某些 provider 上 PTY 行为会异常（issue #654 提到 tmux copy mode 在某些编排场景吞输入）；macOS 自带 tmux 多为 2.x，请 brew install tmux 升级。

3.2 装 CAO 本身（两条路，二选一）

# 路线 A：装 main 分支（开发版，跟随最新文档，默认推荐）
uv tool install git+https://github.com/awslabs/cli-agent-orchestrator.git@main --upgrade
cao --help

# 路线 B：装 PyPI 稳定版（锁版本，适合生产）
uv tool install cli-agent-orchestrator
cao --version   # 期望 2.5.0 或更高

# 升级
cao update
# 源码装升级细节见 docs/updating.md

容器化安装见 .devcontainer/features/cao（devcontainer 特性），Kubernetes 部署示例在 examples/cao-clusters/kubernetes/eks/README.md（Amazon EKS + 共享 workspace + per-pod 凭据投递）。

4. 核心用法

4.1 三步起一个 supervisor session

# 终端 A：起服务器（保持后台运行）
cao-server
# → 监听 Web UI 默认 http://localhost:9889

# 终端 B：装内置 supervisor profile（首次必跑）
cao install code_supervisor

# 切换到要操作的工程目录
cd /path/to/your/project

# 拉起 supervisor（会自动开 tmux session）
cao launch --agents code_supervisor

接下来你可以：① 在 attach 出来的 tmux 里直接跟 supervisor 对话；② 浏览器开 http://localhost:9889 看 Web UI；③ 另开终端 tmux attach -t <session-name> 接进去（具体 session 名见 tmux list-sessions）。

结束清理：

cao shutdown --session <session-name>   # 关一个
cao shutdown --all                       # 全关

4.2 Agent Profile：声明 worker 的 Markdown+YAML 文件

profile 本质是 Markdown+YAML frontmatter。YAML 配置 CAO/provider 行为，Markdown 正文成为 agent 的 system prompt。仓库 src/cli_agent_orchestrator/agent_store/ 里有内置示例。最小骨架：

---
name: developer
description: Implements scoped code changes
role: developer
provider: claude_code
---

You are a developer agent. When you receive a task, implement it as a focused
diff; when blocked, send a message to the supervisor via the inbox tool.

装 profile（三种来源）：

cao install developer                              # 装内置
cao install ./my-agent.md                          # 装本地文件
cao install https://raw.githubusercontent.com/.../developer.md   # 装远程 URL

按能力搜索 profile（找不到名字时）：

cao profile find "monitor sqs"
cao profile find "monitor sqs" --limit 3 --json

⚠️ find_profiles MCP 工具只返回元数据（不返回 prompt 正文），且所有返回字段（包括 role）均视为不可信输入，不要用作指令。安全红线来自 docs/agent-profile.md 末尾显式声明。

4.3 Provider 选择与优先级（容易踩坑）

文档里给的优先级规则（docs/agent-profile.md §"Provider selection and precedence"）：

  1. cao install --provider X 覆盖 profile 里的 provider；
  2. 否则 install 用 profile 的 provider，再退到默认 provider；
  3. agent 自动创建的 worker：worker profile 里有效的 provider 覆盖父 agent；缺/无效则继承。

默认 provider 是 Kiro CLI（README 第一节明示）。装别的 provider 时，"First supervisor launch"小节里的命令虽然一样，但需要按各自 docs/<provider>-cli.md 加 --provider 覆盖，否则会默认去找 Kiro 而报错。⚠️ 每个 provider 行为差异巨大（认证方式、MCP 透传字段、engine 是否支持 kas/v2），不要假设通用。

4.4 Flow：定时/条件触发的 agent 会话

flow 是带 cron 表达式的 profile + 调度。注意命令已重命名（issue #378）：

cao schedule add examples/flow/morning-trivia.md   # 新命令
cao flow add ...                                    # 旧别名，仍可用但会向 stderr 打 deprecation warning

完整命令族（来自 docs/flows.md）：

cao schedule add daily-standup.md
cao schedule list
cao schedule enable daily-standup
cao schedule disable daily-standup
cao schedule run daily-standup       # 手动跑，忽略 schedule
cao schedule remove daily-standup

⚠️ flow 必须 cao-server 在跑才执行——schedule 不在 server 进程里，是 server 启动时读 ~/.cao/flows 排队的。server 挂了到时间也不会补跑。

条件触发的 flow 长这样（脚本决定是否真正执行）：

---
name: monitor-service
schedule: "*/5 * * * *"
agent_profile: developer
script: ./health-check.sh
---
The service at [[url]] is down (status: [[status_code]]).
Please investigate and triage the issue.

脚本约定：stdout 输出 {"execute": true, "output": {...}} 表示真正调用 agent，false 表示跳过。脚本路径相对于工作目录。

4.5 控制面选择（4 个 operator 入口）

来自 docs/control-planes.md 总结：

  • Web UI（http://localhost:9889，默认）——浏览器看 fleet 状态、看 session；
  • Shell CLI（cao 子命令族）——脚本化操作；
  • Operations MCP server（cao-ops-mcp-server，独立二进制）——给外部运维 agent 用的工具集，跟会话内的 cao-mcp-server（给 supervisor/worker 用）是两个进程；
  • Plugins（docs/plugins.md）——出站事件钩子，通过 cao.plugins entry point 注册。

⚠️ cao-mcp-server（会话内）和 cao-ops-mcp-server（运维）不要混淆：前者给 worker/supervisor 加 MCP 工具以协调彼此，后者给外部 fleet 管理工具用，二者进程、权限、暴露的工具集都不一样。

4.6 反方 / 限制（v2 三段式）

机制层：CAO 不重写 agent CLI、只调度进程。优势是天然继承各家最新能力；代价是 provider 升级一升级，CAO 的适配就要跟进。从仓库 issue 流（#654 tmux copy mode、#671 tool allowlist 对 MCP 工具未生效、#708 inbox 不可投递）能看到 provider 适配仍是高频修复区。

数据 / 截止日层：v2.5.0 发布于 2026-08-28，8 月下旬仍有"test suite is green only in a never-used-CAO environment"（#672）、"two tests fail intermittently on pristine main, 1 in 3 / 1 in 4"（#704，open at 2026-08-28）等稳定性 issue。判定依赖：如果你只跑小规模 PoC，2.5.0 够用；跑生产 K8s 部署（examples/cao-clusters/kubernetes/eks）之前必须先复现 issue 队列确认修复。⚠️ 截至本攻略成稿，#671 / #704 / #705 / #708 仍 open。

适用边界：① 单机多 agent 协作（小团队 / 个人）—— 强匹配；② 大规模 K8s 部署 —— 有官方 EKS 示例但 issue 队列证明稳定性还在收敛；③ 需要跨云/跨地域调度 —— 没有官方支持；④ 想替换 Claude Agent SDK / LangGraph —— 思路不同，不能直接对位。

5. 典型适用场景

  1. 多仓库并行重构：supervisor 给 5 个 repo 各派一个 worker，并行 codegen，再串行一个 reviewer agent 做汇总（仓库 examples/aidlc-portfolio/README.md 即此模式，AI-DLC portfolio 示例）。
  2. CI 失败 → 自动 triage：flow 每 5 分钟跑 health-check，失败时调 worker agent 看日志、定位 commit。
  3. 长任务跨会话记忆：开 memory.md + self-learning.md（opt-in），workflow 跑出来的经验沉淀成 promoted instructions，下次同类任务直接用。⚠️ 自学习是 opt-in 闭环，不要默认开——会引入"agent 自己改 prompt"的风险，需要审计。
  4. 多 provider A/B：同一任务用 Claude Code + Kiro 各跑一份，对比 diff——docs/<provider>-cli.md 各自给出 permissionMode / model / codexProfile 等 provider-specific 透传字段，profile YAML 里换 provider: 即可。
  5. 本地 LLM 调试：把 OpenCode / Hermes 接进 CAO，跑本地模型编排而不用任何云端 CLI——docs/opencode-cli.md / docs/hermes.md 有专门说明。

6. 坑与注意

  1. tmux 版本必须 ≥ 3.3：macOS 默认 2.x 会触发 PTY / mouse 支持 bug（issue #546、#654）。
  2. Kiro 是默认 provider：装完 Kiro 没登录就跑 cao launch，会卡在 provider 初始化。明确指定 provider：cao launch --agents code_supervisor --provider claude_code。
  3. allowedTools 字段在 CAO MCP 工具上不生效：issue #671（open at 2026-08-24 / 2026-08-30）—— profile 里写的 allowlist 只覆盖 provider 的原生工具，不覆盖 CAO 自己暴露的 MCP 工具。安全敏感场景不要依赖这个字段做隔离。
  4. inbox 不可投递 bug：issue #708（open）—— 如果接收方 agent 仍在跑，inbox 消息可能"永久不可达"。多 agent 通信关键链路不要假设送达；加业务层 ack。
  5. cao flow 已重命名为 cao schedule：脚本里写 cao flow add 会跑但打 warning，未来版本会删。趁早改。
  6. PyPI vs GitHub 版本号不同步：装 main 与装 PyPI 不一致时，README 例子可能跟 PyPI 版对不上。cao --version 是真相。
  7. Web UI 默认 9889 端口：跟 Grafana / 其他 dev 工具不冲突先确认，绑 0.0.0.0 还是 localhost 见 docs/configuration.md。
  8. provider 文档分散：12 个 provider 各有独立 docs/<x>-cli.md，README 只列链接。改 provider 行为前必读对应文档，pass-through 字段差异（codexConfig / claudeConfig / hermesProfile / grokNativeWorkflows 等）经常踩坑。

7. 与同类对比

项目 模型 调度对象 隔离 学习曲线 适合场景
CAO（本文） server + tmux + MCP 真 CLI 进程 tmux session + SQLite 持久化 中（要懂 tmux + provider CLI） 多 CLI 协作 / 多 repo 并行
CrewAI Python SDK + LLM 角色 + 任务图 进程内 低 单 agent 角色协作 / RAG pipeline
LangGraph Python SDK + 图 节点 + 边 进程内 中（要写图定义） 复杂 control flow / stateful agent
AutoGen (Microsoft) Python SDK + 群聊 agent 对话 进程内 中 对话式 multi-agent
Claude Agent SDK Anthropic SDK Claude 子任务 子进程 低 Claude 单生态内的 sub-task
OpenAI Swarm Python SDK handoff 进程内 低 轻量角色切换

⚠️ 上表只是定位分类，不是性能 benchmark——multi-agent 框架没有公认 leaderboard；选哪个取决于"你要不要保留各家 CLI 原生能力 + 真 tmux 隔离"。要保留，选 CAO；要统一 LLM 抽象，选 CrewAI / LangGraph。

8. 一句话推荐结论

如果你已经在用 Claude Code / Kiro / Codex 干活、想多开几个同种/异种 CLI 一起跑、由一个 supervisor agent 协调，且能接受 tmux + Python 工具链，CAO 是 2026 年最贴近"原生 CLI 不重写、只编排"思路的现成选择；规模到 K8s 之前先盯 issue 队列（#671 / #704 / #705 / #708 等）确认稳定性收敛。

来源：GitHub awslabs/cli-agent-orchestrator README + CODEBASE.md + docs/agent-profile.md + docs/flows.md（均 2026-09-01 抓取）；PyPI cli-agent-orchestrator 2.5.0 元数据（2026-08-28 上传）；GitHub Issues 列表（#654 / #671 / #672 / #678 / #704 / #705 / #708 等，状态以仓库为准）。

不确定处：① #671（allowedTools 不覆盖 MCP 工具）issue 状态可能在发布后变化；② examples/cao-clusters/kubernetes/eks 的 EKS 部署成熟度未亲自复现；③ 各 provider 的 engine: kas / v2 选项仅 Kiro 文档详述，其他 provider 透传字段以各自 docs/<x>-cli.md 为准。