개요
Ruflo는 Claude Code를 위해 설계된 오픈 소스 멀티 에이전트 오케스트레이션 플랫폼입니다. 지능형 Agent 스웜 배포, 자율 워크플로우 조정, 대화형 AI 시스템 구축을 지원합니다. 엔터프라이즈급 아키텍처, 자기 학습 스웜 인텔리전스, RAG 통합 및 네이티브 Claude Code 통합을 갖추고 있습니다.
README 미리보기
\n\n[](https://flo.ruv.io/)\n\n[](https://flo.ruv.io/)\n[](https://goal.ruv.io/)\n[](https://goal.ruv.io/agents)\n\n[](https://github.com/ruvnet/claude-flow)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/ruvnet/claude-flow)\n[](https://www.npmjs.com/package/@claude-flow/codex)\n[](https://github.com/ruvnet/ruvector)\n\n# Ruflo\n\n**Multi-agent AI orchestration for Claude Code**\n\n\n\nOrchestrate 100+ specialized AI agents across machines, teams, and trust boundaries. Ruflo adds coordinated swarms, self-learning memory, federated comms, and enterprise security to Claude Code — so agents don't just run, they collaborate.\n\n### Why Ruflo?\n\n> Claude Flow is now Ruflo — named by [`rUv`](https://ruv.io), who loves Rust, flow states, and building things that feel inevitable. The "Ru" is the rUv. The "flo" is working until 3am. Underneath, powered by [`Cognitum.One`](https://cognitum.one/?RuFlo) agentic architecture, running a supercharged Rust based AI engine, embeddings, memory, and plugin system.\n\n\n### What Ruflo Does\n\nOne `npx ruvflo init` gives Claude Code a nervous system: agents self-organize into swarms, learn from every task, remember across sessions, and — with federation — securely talk to agents on other machines without leaking data. You keep writing code. Ruflo handles the coordination.\n\n```\nSelf-Learning / Self-Optimizing Agent Architecture\n\nUser --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Providers\n ^ |\n +---- Learning Loop **New to Ruflo?** You don't need to learn 314 MCP tools or 26 CLI commands. After `init`, just use Claude Code normally -- the hooks system automatically routes tasks, learns from successful patterns, and coordinates agents in the background.\n\n---\n\n\n\n## Quick Start\n\nThere are **two different install paths** with very different surface areas. Pick based on what you need (#1744):\n\n| | **Claude C
FAQ (5)
문제 해결ruflo 또는 Claude Flow CLI --version이 첫 실행 시 60초 이상 멈췄다가 코드 143으로 종료되는 문제를 해결하는 방법은?
ONNX 임베딩 모델을 로드하기 전에 --version/-V가 종료되는 v3.10.33 이상으로 업그레이드하세요:
npx -y ruflo@3.10.33 --version
npx -y @claude-flow/cli@3.10.33 --version콜드 캐시 상태에서 멈춤 현상이 발생한 이유는 CLI 초기화 과정이 버전을 출력하기 전에 HuggingFace에서 23 MB all-MiniLM-L6-v2 ONNX 모델을 다운로드했기 때문입니다. v3.10.33에서는 ruflo와 @claude-flow/cli 모두 package.json에서 버전을 읽고 즉시 종료하므로, 시작 시간이 60초 이상에서 약 33 ms로 단축됩니다.
이전 릴리스를 사용해야 하는 경우 더 긴 타임아웃으로 모델 캐시를 한 번 예열하세요:
timeout 180 npx -y ruflo@alpha --version다운로드가 완료되면 이후 호출부터는 디스크 캐시를 사용하여 빠르게 시작됩니다. 더 광범위한 lazy-loading/cli-core 분리 작업은 ADR-100/#1760에서 계속 추적되고 있습니다.
문제 해결verify.mjs가 "Cannot find module '@noble/ed25519'" 오류로 실패하고 witness 검증을 건너뛰는 문제를 어떻게 해결하나요?
검증을 실행하기 전에 선언된 npm 의존성을 설치하세요. 저장소 루트에서 다음을 실행하세요:
npm ci && npm run build그런 다음 검증기를 다시 호출하세요. 예를 들어:
node plugins/ruflo-core/scripts/witness/verify.mjs --manifest verification/linux/manifest.md.json클린 상태가 아닌 로컬 체크아웃의 경우에도 저장소 루트에서 npm install을 실행하면 누락된 @noble/ed25519 의존성을 설치할 수 있습니다. 소스 전용 검증 러너의 pre-flight 단계에 npm ci && npm run build를 추가하세요. 출력에 Ed25519 검사가 건너뛰어졌다고 나와 있는 경우 exit code 0을 성공으로 간주하지 마세요. 성공적인 검증은 반드시 서명 유효성 검증 결과와 pass/drift/regressed/missing 카운트를 출력해야 합니다.
문제 해결memory_search_unified가 기본 네임스페이스 6개만 검색하고 메모리 항목이 누락되는 문제를 어떻게 해결하나요?
ruflo **3.10.33 이상**으로 업그레이드하세요 (npm install -g ruflo@3.10.33). ruflo 3.10.13 / @claude-flow/cli 3.10.22와 같은 영향받는 버전에서는 네임스페이스 필터 없이 memory_search_unified를 사용할 경우 하드코딩된 6개 네임스페이스 목록이 사용되었기 때문에, knowledge-graph, causal-edges, brain-system 또는 사용자 정의 네임스페이스에 있는 항목이 아무런 알림 없이 누락되었습니다. 이 수정 사항은 기본적으로 동적 네임스페이스 열거를 사용하며, namespaces: string[], CSV 환경 변수 CLAUDE_FLOW_MEMORY_SEARCH_NAMESPACES, 그리고 응답 내 namespaceSource를 추가합니다. 해결 우선순위는 다음과 같습니다: 명시적 namespace → 명시적 namespaces → 환경 변수 재정의 → 동적 열거 → 레거시 폴백. 이전 버전에서는 대상 네임스페이스를 명시적으로 전달하세요. 예를 들어 memory_search_unified({ query: "needle", namespace: "brain-system" })와 같이 사용하거나 업그레이드하세요. dist/ 아래의 수정 사항에 의존하지 마세요. npm 업그레이드 시 덮어쓰기됩니다.
문제 해결Codex에서 Ruflo MCP 서버가 non-JSON stdout 로그 또는 initialize timeout으로 인해 로드되지 않는 문제를 해결하려면 어떻게 해야 하나요?
Ruflo를 **v3.10.33 이상**으로 업그레이드하세요. 이 버전은 서드파티 임베딩/모델 로딩 진행 로그를 stdout에서 stderr로 리다이렉트하여 stdout을 MCP JSON-RPC 프레임 전용으로 유지합니다.
수정된 버전으로 고정되도록 Codex MCP 구성을 업데이트하세요:
[mcp_servers.ruflo]
command = "npx"
args = ["-y", "ruflo@3.10.33", "mcp", "start"]
enabled = true그런 다음 Codex 또는 MCP 서버를 재시작하세요. v3.10.30에서 문제가 되던 로그는 다음과 같습니다:
Disk cache hit: all-MiniLM-L6-v2
🚀 Initializing 19 worker threads...
Loading model: all-MiniLM-L6-v2 (23MB)
Downloading: ...이러한 로그 때문에 Codex와 같은 엄격한 MCP 클라이언트가 initialize 응답을 파싱하는 데 실패하여 mcp__ruflo... 도구가 나타나지 않았습니다. stdout 스트림이 이미 JSON이 아닌 텍스트로 오염되어 있기 때문에 시작 타임아웃만 늘려서는 이전 버전의 문제가 해결되지 않습니다. 업그레이드 후에는 첫 번째 모델 다운로드/초기화 실행이 여전히 느린 경우에만 클라이언트 타임아웃을 늘리세요.
문제 해결왜 ruflo-console은 성공적인 보안 위협 탐지를 실패로 보고하고, 실제 오류 대신 '[WARN] Skipped helper auto-refresh'를 표시하나요?
ruflo-console을 **0.40.5 이상**으로 업그레이드하세요. 수정 사항은 PR #3934(머지 767f7a689)에 포함되어 있습니다. 버전 0.40.3은 0이 아닌 모든 CLI 종료 코드를 실패로 잘못 처리했습니다. verdict 명령은 탐지 결과를 나타내기 위해 0이 아닌 종료 코드를 사용합니다. 예를 들어 security defend/security scan은 위협 발견 시 종료 코드 1을 반환하고, channel-scan/scan-plan은 게이트가 작동할 때 종료 코드 2를 반환하며, metaharness 알림 스크립트는 알림에는 종료 코드 1을, 실제 실패에는 종료 코드 2를 반환합니다. 수정된 러너는 전체 JSON 응답을 파싱하여, JSON이 탐지 결과를 확인하고 별도의 실패가 보고되지 않으면 선언된 0이 아닌 종료 코드를 유효한 verdict로 허용합니다. 또한 첫 번째 stderr 줄([WARN] 알림일 수 있음) 대신 실제 [ERROR] 줄을 선택하는 공유 failureReason 헬퍼를 사용합니다. 업그레이드 후 콘솔/MCP 서비스를 재시작하세요. 업그레이드가 지연되는 경우 콘솔의 ok:false 상태나 첫 번째 stderr 줄에 의존하지 말고, 명령의 stdout JSON을 직접 검사 및 파싱하고 stderr에서 [ERROR]를 검색하세요.