多智能体编排 · 详细指南 · 验证于 2026-08-27

ruflo：详细版

Agent meta-harness：为 Claude Code/Codex 加编排、记忆与 swarm

← 快速上手（简单版） 所属问题域：多智能体编排

相关组合包：Agent 开发环境一键初始化 ｜ 多 Agent 工作流编排

相关问题：`ruflo plugins install` 命令不存在（正确技能入口是 npx skills add） ｜ ruflo 安装被未发布依赖 pin 卡住（@claude-flow/mcp alpha 未发布） ｜ Windows 上 `hive-mind spawn --claude` 检测不到 claude CLI（PATH 检测失败） ｜ 首次 npx ruflo init 很慢、npx 缓存约 2GB（磁盘敏感环境）

ruflo 详细指南

版本 3.38.20~3.38.20 ｜ 分类 session ｜ 安全（已审查） ｜ 素材：项目官方文档（英文 README + USERGUIDE）+ 本市场实测（2026-08-27）
配套：站内文档（manifest + guide + 证据）｜ 快速版：站内文档

1. 场景：什么时候会用它

Ruflo（前身 Claude Flow，ruvnet 出品，MIT，约 7 万星）是 Claude Code / Codex 的 meta-harness：模型负责写，harness 负责给工具、记忆、循环、沙箱和控制。它的卖点是"给 Claude Code 装一套神经系统"——100+ 特化 agent、swarm 编排、自学习记忆、跨机器联邦通信、企业安全护栏。

一句话：装完 init，日常还是用 Claude Code 干活，ruflo 在后台做路由、协调、记忆。

这个工具解决什么问题：给 Claude Code / Codex 加编排、记忆与 swarm（集群）能力。Ruflo 是 Agent 元编排层：init 全量安装写工作区骨架（.claude-flow/ .agents/ .swarm/ 等），start 启动编排系统，doctor 体检，daemon 常驻。

什么时候用：

  • 你要多 Agent 编排 + 记忆 + swarm（start/agent/swarm/memory 命令面）；
  • 你要工作区级流水线骨架（init 生成）；
  • 你要团队协作式 Agent 工作流。

什么时候别用：轻量单会话——它是重档条目（首次安装约 5 分钟 + 1.6GB npx 缓存，init 写多处文件，doctor 拉后台 daemon）。

和相邻工具的边界：CLI 层与 omc/agt/deepcode 实测可共存（实测记录（本地留存））；与 claude-code-router 判定 possible-compatible（2026-08-30 部分实测：本机工作区 settings.json env 仅 CLAUDE_FLOW_*，无 ANTHROPIC_*；ccr 注入 HOME settings.json env ANTHROPIC_* 需 provider 配置后触发；ccr 网关启停与本工具 doctor 并存正常；注入链未全验证，不转 verified）。

2. 能力清单
能力作用
swarm多 agent 协同（ruflo swarm）
memory跨会话记忆（ruflo memory，SQLite 持久化）
hooks自学习钩子（自动路由/学习）
autopilot持久 swarm 直到任务完成
daemon后台常驻 worker
100+ 特化 agent见 Agent 执行版 guide
自学习记忆见 Agent 执行版 guide
MCP 服务器见 Agent 执行版 guide

3. 快速安装
note: CLI 全量路径（本环境实测）；国内推荐 npmmirror；首次运行约 5 分钟属正常
# 来源: Trove 详细指南 · 验证于 2026-08-27
npm_config_registry=https://registry.npmmirror.com npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

预期输出: ruflo v3.38.20

第 1 步：确认版本与骨架目录

讲解：ruflo --version 输出 v3.38.20、工作区出现 .claude-flow/ 等骨架目录，说明 init 全量安装完成。

# 来源: Trove 详细指南 · 验证于 2026-08-27
npx -y ruflo --version
ls -d .claude-flow 2>/dev/null && echo "skeleton: OK" || echo "skeleton: MISSING"

预期输出: ruflo v3.38.20；skeleton: OK

卡住怎么办：

  • 版本对不上 → 重跑 init（带 --no-signup --no-skills-sh --no-codex-detect）；
  • 骨架缺失 → 确认在目标项目目录内执行 init。

第 2 步：doctor 体检

讲解：doctor 把版本/Node/npm/Git/配置/Memory DB/MCP 全查一遍，无 FAIL 即环境就绪；⚠ 项是警告不阻塞。

# 来源: Trove 详细指南 · 验证于 2026-08-27
npx -y ruflo doctor

预期输出: RuFlo Doctor 检查项（版本/Node/npm/Git/配置/Memory DB/MCP）；⚠ 项为警告不阻塞

卡住怎么办：

  • 有 FAIL 项 → 按提示修（Node 版本/配置）；
  • daemon 起了想停 → npx -y ruflo daemon stop。

安装变体
路径命令实测
主路径（实测）npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect && npx -y ruflo -…✅ 本市场实测
镜像/代理见快速版与 semi_auto_note；国内安装按 ruflo 指引实测
半自动说明：实测命令 = npx ruflo init（npmmirror，2026-08-27 本环境验证，v3.38.20；首次含原生 prebuild 下载约 5 分钟、缓存 1.6GB）；国内可加环境变量 npm_config_registry=https://registry.npmmirror.com；--no-signup/--no-skills-sh/--no-codex-detect 消除交互与外网注册；重档条目：init 写工作区 .claude/.claude-flow/.agents/.swarm/.mcp.json/CLAUDE.md + HOME ~/.claude/CLAUDE.md 指针块，doctor 会拉起后台 daemon（ruflo daemon stop 停止）；完整编排需 LLM provider
  • 网络：海外/可直连网络用 npm 官方分支（实测 1.2s）；国内必须 npmmirror 前缀。
  • Node 版本：要求 >= 20；首次安装原生依赖下载约 5 分钟 + 1.6GB npx 缓存（重档，属正常）。
  • 后台进程：doctor/start 会自动拉起 daemon，不用时 ruflo daemon stop。
  • 写面大：工作区 .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db + HOME ~/.claude/CLAUDE.md 指针块——不想要全量形态可卸载后走插件 lite（方式 B）。
  • 与其它工具共装：CLI 层与 omc/agt/deepcode 实测共存；与 omc 插件形态判定 possible-conflict（共享 .claude/ 写面未实测）；与 claude-code-router 判定 possible-compatible（2026-08-30 部分实测：env 字段/层级不重叠，见「和相邻工具的边界」）。

4. 为什么会这样（机制与共享面）

它怎么工作：官方推荐 CLI 全量路径 = npx ruflo init（本环境实测通过）：首次 npx 自动下载原生 prebuild 依赖（约 5 分钟，缓存 1.6GB）；init 写入工作区 .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db 与 HOME ~/.claude/CLAUDE.md 指针块。命令面 30+：init/start/agent/swarm/memory/mcp/hooks/daemon。lite 形态 = Claude Code 插件（方式 B，未实测）。

关键概念：

  • init：全量安装（官方生产推荐，写工作区 + HOME）；
  • doctor：健康诊断（⚠ 为警告不阻塞；会拉起 daemon）；
  • daemon：后台进程（doctor/start 自动拉起，daemon stop 停止）。

装完它动哪里（写面大）：工作区 .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db + HOME ~/.claude/CLAUDE.md 指针块。

  • 工作区：.claude/（agents/commands/helpers/skills）、.claude-flow/（配置 + 学习/日志/会话/工作流）、.agents/、.swarm/（SQLite 记忆库）、.mcp.json（MCP 注册）、CLAUDE.md、ruvector.db
  • HOME：~/.claude/CLAUDE.md（集成指针）、~/.claude-flow/
  • 后台：daemon 进程（doctor/start 自动拉起）

5. 常用操作

第 1 步：init 全量安装（为什么带三个 --no：消除交互与外网注册）

讲解：npx -y ruflo init 首次运行会自动下载原生 prebuild 依赖（约 5 分钟，缓存 1.6GB）——不是卡死，耐心等。--no-signup --no-skills-sh --no-codex-detect 消除交互与外网注册，适合自动化/无账号环境。init 会写工作区多处文件（见方案总览）。

# 来源: Trove 详细指南 · 验证于 2026-08-27
npm_config_registry=https://registry.npmmirror.com npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

预期输出: ruflo v3.38.20

海外/可直连网络分支（去掉 npmmirror 前缀，npm 官方 1.2s 可用）：

# 来源: Trove 详细指南 · 验证于 2026-08-27
npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

预期输出: ruflo v3.38.20

装好确认：

  • npx -y ruflo --version 输出 v3.38.20；
  • 工作区出现 .claude-flow/ 等骨架目录。

卡住怎么办：

  • npx 下载很慢 → 首次原生依赖下载约 5 分钟属正常；确认 Node >= 20；国内用 npmmirror 分支；
  • 工作区多了文件吓人 → 这是全量形态设计（官方生产推荐）；不想要全量可卸载后走方式 B 插件 lite。

第 2 步：doctor 体检（会拉起 daemon）

讲解：doctor 检查版本/Node/npm/Git/配置/Memory DB/MCP；⚠ 项为警告不阻塞。注意 doctor/start 会拉起后台 daemon，用完 ruflo daemon stop。

# 来源: Trove 详细指南 · 验证于 2026-08-27
npx -y ruflo doctor

预期输出: RuFlo Doctor 检查项（版本/Node/npm/Git/配置/Memory DB/MCP）；⚠ 项为警告不阻塞；用完后 ruflo daemon stop

装好确认：

  • 检查项输出完整，无 FAIL（⚠ 可接受）。

卡住怎么办：

  • daemon 起了想停 → npx -y ruflo daemon stop。

第 3 步：编排最小场景（本地 ollama provider 实测；零 key）

讲解：不用外部 API key 也能验证编排面——ruflo 内置 Ollama provider，指向本机 ollama（默认 11434）即可。2026-08-30 隔离环境实测：configure → test（本地端点连通 PASS）→ swarm init → swarm start → swarm status 全过。

# 来源: Trove 详细指南 · 验证于 2026-08-27
npx -y ruflo providers configure -p ollama -e http://127.0.0.1:11434 -m qwen2.5-0.5b
npx -y ruflo providers test -p ollama
npx -y ruflo swarm init
npx -y ruflo swarm start -o "最小目标"
npx -y ruflo swarm status

预期输出: Configured: ollama（endpoint 保存）→ Provider Connectivity Test：Ollama Connected at 11434 PASS → Swarm initialized（Swarm ID + hierarchical/15 agents）→ Agent Deployment Plan（coordinator/architect/coder×3/tester×2/reviewer）+ Swarm initialized with 8 agent slots → 状态表（Elapsed 0s）

装好确认：

  • 编排层（init/start/status）命令面 + 本地连通全绿（2026-08-30 隔离实测，实测复现日志（2026-08-30））。

卡住怎么办：

  • providers test 报 FAIL: ollama: Not configured (no API key found) → 这是云端 ollama 形态需要 key；同输出里本地端点的 PASS: Ollama: Connected at http://127.0.0.1:11434 才是判定项。
  • swarm stop 报 Swarm ID is required → 用 swarm stop <Swarm ID>（swarm status <id> 可查 ID）。
  • 要 agent 真跑任务 → 编排层就绪后，执行通道是 Claude Code Agent 工具 / claude -p / hive-mind spawn --claude——本环境未验证该通道（无 Claude Code 执行会话），如实标注。

启动与入口

  • 编排：npx -y ruflo start；
  • 后台：daemon（doctor/start 自动拉起，daemon stop 停止）；
  • 命令面：npx -y ruflo --help（30+ 命令）。

常用操作

操作一：查看命令清单

# 来源: Trove 详细指南 · 验证于 2026-08-27
npx -y ruflo --help

预期输出: 以 Ruflo v3.38.20 开头，含 init/start/agent/swarm/memory/mcp/hooks/daemon 等 30+ 命令

操作二：健康诊断（本环境实测；注意会拉起后台 daemon）

# 来源: Trove 详细指南 · 验证于 2026-08-27
npx -y ruflo doctor

预期输出: RuFlo Doctor 检查项（版本/Node/npm/Git/配置/Memory DB/MCP）；⚠ 项为警告不阻塞；用完后 ruflo daemon stop

操作三：停止后台 daemon（doctor/start 会拉起）

# 来源: Trove 详细指南 · 验证于 2026-08-27
npx -y ruflo daemon stop

预期输出: Worker daemon stopped

操作四：编排最小场景（需先配 provider；命令来自 --help，本环境未实测——无 API key）

# 来源: Trove 详细指南 · 验证于 2026-08-27
npx -y ruflo start

预期输出: 编排系统启动状态（swarm/agents/memory 就绪）

数据与目录

  • 工作区：.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db；
  • HOME：~/.claude/CLAUDE.md（Ruflo 指针块）、~/.claude-flow/。

6. 冲突逐条（摘要）

与工具页矩阵同源，共 19 对（0 实测兼容 / 13 推断可能兼容 / 6 推断可能冲突）；完整对子、状态与证据见 冲突对子（共装矩阵）。

7. 排障速查
  • 暂无独立排障手册；安装/卸载问题先看 Agent 执行版 guide 注意事项

8. 卸载与残留检查

 
# 来源: Trove 详细指南 · 验证于 2026-08-27
npm rm -g ruflo || true; rm -rf -- .claude-flow .swarm ruvector.db 2>/dev/null || true
note: npm 包卸载自动执行（幂等）；工作区专属文件（.claude-flow/ .swarm/ ruvector.db）从 ruflo 初始化目录运行本卸载会一并删除；通用名文件按下方清单手动确认
# 来源: Trove 详细指南 · 验证于 2026-08-27
npm rm -g ruflo || true
rm -rf -- .claude-flow .swarm ruvector.db 2>/dev/null || true
command -v ruflo >/dev/null 2>&1 && echo "ruflo 仍存在" || echo "ruflo removed: OK"

预期输出: ruflo removed: OK

手动确认清单（通用名文件，可能含用户其他配置，不自动删）：

  • 工作区：.claude/（ruflo 生成 agents/commands/helpers/settings.json/skills 子项）、.agents/、.mcp.json（删除 claude-flow 注册段）、CLAUDE.md（删除 Ruflo 指针）
  • HOME：~/.claude/CLAUDE.md（删除 Ruflo Integration 指针块）、~/.claude-flow/

9. FAQ
  • 运行环境预检（需 Node >= 20；输出包含 v 开头版本号即通过）
  • 官方推荐 CLI 全量路径 = npx ruflo init（本环境实测通过）；Path A = Claude Code 插件（lite，依赖登录环境未实测，命令来自官方 README）
  • 首次运行 npx 自动下载（原生 prebuild 依赖，约 5 分钟，缓存 1.6GB）；--no-signup/--no-skills-sh/--no-codex-detect 消除交互与外网注册；init 写入工作区 .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db 与 HOME ~/.claude/CLAUDE.md 指针块
  • 每条操作 = 一个命令块 + 预期输出；编排类命令需要 LLM provider（方式 A 安装后配 provider）
  • 重档条目：1.6GB 缓存 + 原生依赖 + daemon 常驻 + MCP 333 tools（61K schema tokens）——磁盘/内存/资源占用明显，轻量场景慎用
  • 问：npx 下载很慢/装不上？答：确认 Node >= 20；国内用安装段方式 A 的 npmmirror 分支；首次原生依赖下载约 5 分钟属正常。
  • 问：安装后工作区多了好多文件？答：init 是 CLI 全量安装（官方生产推荐），写入 .claude/.claude-flow/.agents/.swarm/.mcp.json/CLAUDE.md；不想要全量可用方式 B 插件 lite 形态。
  • 问：后台有个进程是什么？答：ruflo daemon（doctor/start 自动拉起），ruflo daemon stop 停止。
  • 问：跑任务报没有模型？答：需要 LLM provider（deepcode provider/ruflo providers 配置 API key）。
  • 问：和其他插件能一起装吗？答：CLI 层实测可共存（omc/agt/deepcode 互不干扰，见 实测记录（本地留存））；与 omc 的 Claude 插件形态共享 .claude/ 与 ~/.claude/CLAUDE.md 未实测（本机未登录），判定 possible-conflict。
  • 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口（usage-report 模板）；项目自身问题请向作者仓库反馈。
  • 版本：[3.38.20, 3.38.20] 锁定（收录实测版本）。
  • 环境：Node >= 20；首次安装原生依赖下载约 5 分钟 + 1.6GB npx 缓存（重档）。
  • 网络：npm 官方 1.2s 可用（海外）；国内用 npmmirror 分支。
  • 写面（大）：工作区 .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db + HOME ~/.claude/CLAUDE.md 指针块。
  • 后台进程：daemon（doctor/start 自动拉起，daemon stop 停止）。
  • 共装：CLI 层与 omc/agt/deepcode 实测共存（实测记录（本地留存））；与 omc 插件形态共享 .claude/ 与 ~/.claude/CLAUDE.md 未实测 → possible-conflict；与 claude-code-router → possible-compatible（2026-08-30 部分实测：工作区 env CLAUDE_FLOW_* vs HOME env ANTHROPIC_*，字段/层级不重叠；注入链未全验证）。

10. 出处
  • 条目签名：ruvnet/ruflo（MIT，原样收录 v3.38.20）
  • 实测：实测记录（本地留存）（2026-08-27，npx init + version/help/doctor 冒烟）；实测记录（本地留存）（与 omc/agt/deepcode 共存，CLI 层）；实测复现日志（2026-08-30）（本地 ollama provider：configure/test 连通 PASS + swarm init/start/status 编排层全过，隔离环境零 key）。
  • 未实测：swarm 执行层（agent 实际跑任务，需 Claude Code / claude -p 执行通道）；方式 B Claude Code 插件（未登录）。

外部教学（来源未实测）

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

  • 官方 README（npm registry readme 字段，v3.38.20）：Ruflo 完整用法 [官方文档 · Ruflo 官方 · 2026-08-31（包 3.38.20）]
    官方用法全解——init 初始化/start 启动编排/status/agent 管理/swarm 协同/memory 记忆/task 任务/session 会话/mcp 管理/hooks 自学习钩子；进阶：neural 模式训练/security 安全扫描与 CVE 检测/policy 策略引擎（ADR-324 决策账本）/performance 性能画像/embeddings 向量检索

收录来源（已合并）

本页内容由多篇来源文章按哈希去重、实测验证、AI 重写后合并而来——来源不散落，全部挂在这一个页面上。

暂无已合并来源：本页为本地实测与多来源重写的沉淀；来源与验证细节见站内对应方案页。

← 返回 ruflo 方案页 ｜ 多智能体编排 问题域