Enderfga/claw-orchestrator

Run Claude Code, Codex, Antigravity, Grok Build and OpenCode behind one runtime, and a run only counts as done when checks it didn't write pass. Cross-engine fan-out, councils, session handoff, spend caps, MCP server, ACP agent.

Claw Orchestrator란 무엇인가요?

Claw Orchestrator는 단일 API 뒤에서 코딩 보조 에이전트(Claude Code, Codex, Antigravity, Grok Build, OpenCode 또는 모든 사용자 지정 CLI)를 실행할 수 있는 Node-JS 런타임입니다. 에이전트를 지속적인 세션으로 처리하고, 작업을 직접 확인하는 검증 계층을 추가합니다. 런타임이 테스트, HTTP 프로브, 파일 차이 등을 실행하고 결과를 디스크에 기록합니다. 런타임 자체의 검사가 통과될 때만 실행이 검증됨으로 표시되므로, 에이전트의 "모든 테스트 통과"라는 주장을 무조건 신뢰할 필요가 없습니다.

핵심 아이디어

아이디어	제공하는 가치
수락 계약	에이전트가 완료된 후 런타임이 실행할 검사(예: `npm test`, HTTP 요청, 스크린샷)를 선언합니다. 실행 결과는 "에이전트가 그렇다고 했으니까"가 아니라 검증됨, 반박됨, 또는 검증되지 않음으로 결정됩니다.
멀티 엔진 런타임	Claude Code, Codex, Antigravity, Grok Build, OpenCode 또는 모든 사용자 지정 도구와 통신할 수 있는 단일 CLI / HTTP API입니다. 단일 프롬프트를 여러 엔진으로 동시에 팬아웃할 수 있습니다.
세션 핸드오프	컨텍스트나 작업 공간 상태를 잃지 않고 라이브 대화를 한 엔진에서 다른 엔진(예: 비용이 많이 드는 Claude 모델에서 더 저렴한 Codex로)으로 이동할 수 있습니다.
내구성 있는 워크플로우 커널	모든 상태 전환이 디스크에 체크포인트됩니다. 프로세스가 충돌해도 작업을 잃지 않고 재개, 재시도, 타임아웃 또는 취소할 수 있습니다.
실행 원장 및 예산 제한	JSONL 원장이 턴당 토큰, 비용, 기간 및 엔진을 기록합니다. `maxBudgetUsd`를 설정하여 런타임이 모든 엔진에 걸쳐 엄격한 지출 제한을 강제하도록 할 수 있습니다.
임베디드 대시보드	웹 UI (`http://127.0.0.1:18796/dash`)에서 라이브 이벤트 스트림, 실행 기록, 세션, 위원회, 자동 루프 등에 대한 제어를 보여줍니다.
OpenAI 호환 프록시	`/v1/chat/completions` 엔드포인트를 노출하여 OpenAI 스타일의 요청을 적절한 지속 세션으로 전달함으로써, 모든 OpenAI 클라이언트가 변경 없이 오케스트레이터와 통신할 수 있게 합니다.

주요 기능 (한눈에 보기)

지속적인 세션 – 여러 메시지에 걸쳐 에이전트의 컨텍스트를 유지합니다.
멀티 엔진 팬아웃 – 동일한 작업을 N개의 모델에서 병렬로 실행하고, 선택적으로 단일 답변으로 합성합니다.
위원회 및 자동 루프 – 3-에이전트 루프(플래너 → 코더 → 리뷰어) 및 합의 투표를 위한 내장 프리미티브.
Ultra-code / ultra-app – Claude가 하위 에이전트를 오케스트레이션하거나 짧은 인터뷰에서 전체 웹 앱을 생성할 수 있게 하는 고수준 구성.
검증 평면 – 계약은 런타임에 의해 실행되며, 증거(로그, 차이, 스크린샷)는 디스크에 저장됩니다.
관측 가능성 – 턴별 원장, 비용 제한 및 실시간 모니터링을 위한 대시보드.
통합 – CLI, MCP 플러그인(Zed, JetBrains, Cursor 등 편집기용), ACP 에이전트(표준 Agent Client Protocol) 및 TypeScript SDK.

빠른 시작 (CLI)

# 전역 설치
npm install -g @enderfga/claw-orchestrator

# 로컬 서버 + 대시보드 시작
clawo serve   # → http://127.0.0.1:18796/dash

# Claude Code를 사용한 간단한 해결 요청
clawo solve "Fix the failing tests" \
  --engine claude \
  --check "npm test" \
  --wait

# 세 개의 엔진에서 동일한 프롬프트를 실행하고 답변 합성
clawo fanout "How would you speed up this test suite?" \
  --engines claude,codex,grok \
  --synthesize \
  --wait

# 최근 실행 목록 보기 (비용, 토큰, 판정 등 표시)
clawo runs --since 1h

서버는 액세스 토큰을 ~/.openclaw/server-token에 기록하며, CLI는 이를 자동으로 읽습니다.

워크플로우 예시 (검증 실행)

계약 선언 – --check "npm test"는 에이전트가 완료된 후 프로젝트의 테스트 스위트를 실행하도록 런타임에 지시합니다.
에이전트 작업 – Claude Code(또는 다른 엔진)가 price.js를 편집하여 테스트를 통과시키려 합니다.
런타임 검증 – 런타임이 직접 npm test를 실행합니다. 테스트가 여전히 실패하면 반박됨, 통과하면 검증됨으로 표시됩니다.
증거 저장 – 모든 명령 출력, 변경된 파일 및 차이 스냅샷이 나중의 감사를 위해 디스크에 저장됩니다.

자신의 코드에 임베드하는 방법 (TypeScript SDK)

import { SessionManager } from '@enderfga/claw-orchestrator';

const manager = new SessionManager();
await manager.startSession({
  name: 'fix-tests',
  engine: 'claude',
  cwd: '/my/project'
});

const result = await manager.sendMessage('fix-tests', 'Fix the failing tests');
console.log(result.verdict); // 'verified' | 'refuted' | 'unverified'

SDK는 로컬 clawo-mcp 서버와 통신하므로 CLI와 동일한 검증 보장을 받습니다.

언제 사용하나요?

AI 생성 코드를 위한 CI 스타일의 안전성 – 모델이 변경 사항을 제안하게 하되, 프로젝트 자체의 테스트 스위트(또는 모든 사용자 지정 계약)가 실제로 통과하는지 런타임이 강제하도록 합니다.
비용 제어된 멀티 모델 실험 – 동일한 작업에서 여러 공급업체를 비교하여 가장 저렴하고 정확한 답변을 제공하는 모델을 확인하고 예산을 강제합니다.
복잡한 자율 워크플로우 – 인간의 개입 없이 해결책에 도달하는 자기 반복 루프(플래너-코더-리뷰어)나 위원회를 구축합니다.
도구가 풍부한 편집기 통합 – 런타임을 Zed, JetBrains, VS Code 등에 플러그인하여 IDE 내에서 동일한 검증 보장을 받습니다.

라이선스 및 기여

라이선스: MIT
기여: CONTRIBUTING.md의 가이드라인을 따르세요. PR을 열기 전에 npm run build && npm run lint && npm run format:check && npm run test를 실행하세요.

결론: Claw Orchestrator는 여러 AI 코딩 에이전트를 실행하기 위한 단일하고 내구성 있는 런타임을 제공하며, 결과를 신뢰할 수 있고 감사 가능하게 만드는 독립적인 검증 단계를 갖추고 있습니다.