Orca 오케스트레이션 | AI 여러 에이전트를 조율하는 개념과 핵심

바이브 코딩처럼 AI 코딩 에이전트를 여러 대 동시에 돌리면, 문제는 '시키는 것'보다 '추적'에서 커진다. 어느 창이 끝났는지, 누가 막혔는지, 재시도가 이전 시도와 섞이지 않는지를 눈으로만 따라가기 어렵다. Orca(onorca.dev)의 오케스트레이션은 이 추적을 위해 Message·Task·Dispatch·Decision Gate로 짜인 조율 계층이다.

이 글은 '위키를 여러 편 쓰는 방법'이 아니다. Orca에서 오케스트레이션이 무엇을 뜻하는지, 언제 쓰고 언제 가볍게 넘길지, 데스크톱에서 어떻게 켜고 배정하는지를 정리한다. 2026년 7월 기준 공식 문서와 GitHub(stablyai/orca)를 교차 확인했다. 오케스트레이션 명령은 Settings → Experimental에서 켜는 실험 기능이며, CLI가 실행 중인 Orca 런타임과 통신하므로 orca status --json이 먼저 성공해야 한다.

핵심 포인트: 오케스트레이션은 소유자·완료·의존성을 추적할 때만 가치가 있다. 1회성 지시는 orca terminal send로 충분하고, 추적·재시도 구분이 필요하면 Task 생성 후 dispatch --inject를 쓴다.

1. Orca가 정확히 무엇인가

Orca는 자체 LLM이 아니다. Claude Code·Codex·Cursor CLI·Gemini CLI 등 터미널에서 도는 에이전트와 Git worktree·터미널·파일 편집·diff·브라우저·원격 SSH를 한 데스크톱 ADE(Agent Development Environment) 로 묶는 도구다. 공식 설명도 '여러 AI 코딩 에이전트를 나란히 실행하는 데스크톱 IDE'에 가깝다.

1.1. Orca가 아닌 것

1. 자체 모델·완전 자율 조직이 아니다.
2. Git을 대체하지 않는다.
3. 관리형 SaaS 서버가 아니다.
4. 특정 CMS·위키 전용 자동화 제품이 아니다.

쉽게 말하면, 여러 에이전트에게 일을 시키고 각 창·파일·브랜치·상태·결과를 한곳에서 관리하는 작업 환경이다.

• 공식 문서: https://www.onorca.dev/docs
• GitHub: https://github.com/stablyai/orca

2. 오케스트레이션이 가리키는 것

단순 '창 여러 개 열기'와 별개로, Orca에는 구조화된 오케스트레이션 계층이 있다. 공식 문서는 가벼운 프롬프트는 orca terminal send, 소유권·완료를 Task ID로 추적할 때는 orca orchestration을 쓰라고 구분한다.

2.1. Coordinator와 Worker

그림 2. Coordinator는 조율·배정·수집, Worker는 실행·완료 보고

1. Coordinator — 큰 일을 나누고 담당을 고르며, 완료·실패·질문을 모아 다음 행동을 정한다. 사람이 맡아도 되고 orca orchestration run으로 런타임에 맡겨도 된다.
2. Worker — 배정받은 Task를 수행하고, 완료·실패 시 worker_done을 정확히 한 번 보낸다. 장시간 작업은 heartbeat, 판단이 필요한 질문은 orca orchestration ask로 Coordinator에게 넘긴다.
3. 그룹 주소 — @all·@idle·@codex·@cursor 등으로 일괄 메시지를 보낼 수 있다. PowerShell에서는 --to '@all'처럼 따옴표로 감싼다.

dispatch 시 --inject를 붙이면 Worker 계약(완료 보고 규칙)이 preamble로 들어간다.

2.2. Message · Task · Dispatch · Decision gate

1. Message — 터미널 간 영속 메모. 유형은 status·dispatch·workerdone·escalation·decisiongate·heartbeat.
2. Task — 명세·의존성·상태를 가진 작업 레코드. 상태는 pending·ready·dispatched·completed·failed·blocked.
3. Dispatch — Task를 특정 터미널에 넘긴 실행 기록. 재시도는 새 dispatch로 갈라, 오래된 시도가 현재 배정을 완료 처리하지 못하게 한다.
4. Decision gate — Coordinator 소유 질문. 결정이 기록될 때까지 후속 Task를 세워 둔다.

완료 권한은 활성 dispatch 컨텍스트에서 나온다. 완료·하트비트에는 taskId와 dispatchId가 함께 있어야 한다. 터미널에 찍힌 task_... ID는 클릭하면 현재 dispatch·담당 창으로 이동한다.

예시로 Task를 나누면 이런 식이다. Worker 1은 로그인 버그 수정, Worker 2는 API 테스트 추가, Worker 3은 배포 스크립트 정리 — 서로 다른 일을 카드 단위로 추적한다.

3. 단순 병렬과 구조화 오케스트레이션

그림 1. 단순 병렬 vs 구조화 오케스트레이션 — 추적·의존성이 있을 때만 Task·Dispatch

읽는 기준은 하나다. 한 번 시키고 바로 보면 왼쪽, 여러 일을 오래 돌리며 누가 끝났는지 남겨야 하면 오른쪽이다.

핵심 포인트: 가벼운 프롬프트는 orca terminal send, 추적·완료 보고는 dispatch --inject, 분해·배정 자체를 맡길 때만 orchestration run.

4. CLI 활성화와 Skill 설치

1. Settings → Experimental → CLI를 켠다.
2. orca status --json이 성공하는지 확인한다. 실패하면 오케스트레이션 명령도 통신하지 못한다.
3. Coordinator가 명령을 이해하게 하려면 Skill을 설치한다.

• `npx skills add https://github.com/stablyai/orca --skill orchestration`
• 필요 시 `npx skills add https://github.com/stablyai/orca --skill orca-cli`
• 확인: orca skills list · orca skills get orchestration --full

Skill 문서: https://www.onorca.dev/docs/cli/skills CLI 개요: https://www.onorca.dev/docs/cli/overview

에이전트 권한은 Settings → Agents → Agent Permissions를 Manual로 두는 편이 안전하다.

5. 실제 배정 순서 (수동 dispatch)

대기 중 CLI는 약 15초마다 heartbeat를 stderr로 흘리고, 최종 결과는 stdout이다. 타임아웃은 즉시 실패가 아니라 체크포인트로 보고, task-list·orca terminal read로 살아 있는지 확인한 뒤 기다림을 이어가면 된다.

5.1. Task 명세에 넣을 것

1. --task-title — 목록용 짧은 작업명
2. --display-name — Worker 행에 보일 라벨
3. --spec — 목표, 출력 경로, 범위, 제외 범위, 완료 조건

5.2. Worker 완료 보고

질문은 orca orchestration ask로 넘긴다. 규모가 커서 분해 자체를 맡길 때만 orca orchestration run --spec ... --max-concurrent N --worktree active를 쓰고, 중단은 orca orchestration run-stop이다. 주제·담당이 이미 정해진 작업에서는 자동 루프가 일을 불필요하게 재분해할 수 있어, 수동 Task·Dispatch가 더 예측 가능하다.

5.3. 상태를 되돌리는 명령

1. orca orchestration dispatch-show --task <id>
2. orca orchestration task-update --id <id> --status blocked
3. orca orchestration reset --tasks|--messages|--all — 전역 초기화. 다른 Coordinator가 돌 때는 함부로 쓰지 않는다.

6. Worktree가 필요할 때

Orca는 worktree 중심이다. 각 worktree는 브랜치·디스크 작업 디렉터리·전용 에이전트 터미널을 갖고, Create → Work → Review → Ship → Archive/Delete 순으로 흐른다. 실제 git worktree이므로 일반 Git 명령도 그대로 쓴다.

1. 코드·원고를 Git으로 관리하면 작업별 worktree가 실수 수정·diff 검토·실패 폐기에 유리하다.
2. 한 디렉터리에서만 돌리는 조사·초안이면 worktree 이득은 줄고, 대신 권한·토큰 분리가 더 중요해진다.

공식 worktree 모델: https://www.onorca.dev/docs/model/worktrees

7. 권한과 보안

그림 5. 권한·보안 핵심 — 파일 격리와 비밀 격리는 다르다

핵심 포인트: worktree는 파일·브랜치 격리일 뿐 OS 계정·네트워크·환경 변수·토큰 샌드박스가 아니다.

1. Agent Permissions는 Manual.
2. 배포·게시 토큰은 조율·발행 담당만 쥔다. Worker 프롬프트에 비밀값을 넣지 않는다.
3. --dangerously-skip-permissions·--yolo 류 플래그는 위험 범위를 넓힌다. 필요할 때만, 격리된 환경에서.
4. 로그인된 브라우저 세션 공유를 최소화한다.

8. 상황별 선택

Orca ADE 설치·에이전트 전반은 Orca ADE 전체 정리에서, 원격·폰 연결은 테일스케일·Orca 원격에서 다룬다.

• 오케스트레이션 명령: https://www.onorca.dev/docs/cli/orchestration
• 지원 에이전트: https://www.onorca.dev/docs/agents/supported

9. 마무리

앞에서 다룬 Orca 오케스트레이션의 핵심만 짧게 정리한다.

• Orca는 자체 모델이 아니라 여러 CLI 에이전트를 한곳에서 돌리는 ADE이고, 오케스트레이션은 Task·Dispatch로 소유권과 완료를 추적하는 계층이다
• 1회성 지시는 terminal send, 추적·완료 보고는 dispatch --inject, 자동 분해는 orchestration run으로 구분해 쓴다
• Experimental CLI를 켠 뒤 orca status --json과 orchestration Skill 설치가 선행 조건이다
• 수동 배정은 status → worktree → terminal list → task-create → dispatch --inject → check → task-list 순이 기본이다
• worktree는 파일 격리일 뿐 토큰·OS 격리가 아니므로 Manual 권한과 비밀값 분리를 지킨다
• 메뉴·플래그 이름은 Experimental이므로 공식 문서를 기준으로 주기적으로 다시 확인한다

「창을 많이 여는 것이 오케스트레이션이 아니다. 누가 무엇을 끝냈는지 남기는 것이 오케스트레이션이다」 — 추적 필요가 생길 때만 Task·Dispatch를 올리고, 그 전에는 가벼운 지시로 충분하다.

자주 묻는 질문

• Orca 오케스트레이션이 뭔가요?

  여러 AI 에이전트 창에 맡긴 일을 Task·Dispatch로 기록하고, 완료·실패·질문을 한곳에서 모으는 조율 기능입니다. 창을 여러 개 여는 것만으로는 오케스트레이션이 아닙니다. 소유자와 완료 여부를 추적할 때 가치가 있습니다.

• 그냥 창마다 프롬프트를 넣으면 안 되나요?

  한 번만 시키고 바로 확인할 일이면 orca terminal send로 충분합니다. 여러 일을 동시에 오래 돌리거나 재시도를 구분해야 하면 Task를 만들고 dispatch --inject로 넘긴 뒤 check로 기다리는 편이 안전합니다.

• 오케스트레이션을 쓰려면 무엇을 먼저 켜야 하나요?

  Settings → Experimental에서 CLI를 켠 뒤 orca status --json이 성공해야 합니다. Coordinator가 명령을 이해하려면 npx skills add로 orchestration Skill을 설치하고 orca skills list로 확인합니다. Experimental이라 옵션 이름은 공식 문서를 기준으로 다시 봅니다.

• Task와 Dispatch 차이는 뭔가요?

  Task는 해야 할 일의 명세와 상태 레코드이고, Dispatch는 그 Task를 특정 에이전트 창에 넘긴 실행 기록입니다. 재시도는 새 Dispatch로 갈라서, 오래된 시도가 현재 작업을 완료 처리하지 못하게 막습니다.

• orchestration run을 항상 쓰면 좋나요?

  아닙니다. 분해·배정까지 자동으로 맡길 때만 검토합니다. 주제와 담당이 이미 정해져 있으면 자동 루프가 일을 조사·초안·검증처럼 다시 쪼갤 수 있어, 수동 task-create와 dispatch가 더 예측 가능합니다.

• worktree는 꼭 만들어야 하나요?

  Git으로 코드·원고를 관리하면 작업별 worktree가 실수 수정과 diff 검토에 유리합니다. 한 폴더에서만 돌리는 짧은 조사면 필수는 아닙니다. 다만 worktree는 파일 격리일 뿐 토큰·OS 격리는 아니므로 권한 분리는 따로 해야 합니다.

• Worker가 완료 보고를 여러 번 보내면요?

  계약상 worker_done은 성공·실패 모두 한 번입니다. taskId와 dispatchId를 함께 넣어야 활성 배정에만 완료가 찍힙니다. --inject를 쓰면 이 규칙이 Worker 쪽에 자동으로 주입됩니다.

• 기존 Orca ADE 위키와 무엇이 다른가요?

  Orca ADE 전체 정리(/wiki/orca-ade-parallel-agents)는 설치·에이전트·worktree 전반을 다루고, 이 글은 오케스트레이션 계층의 뜻·핵심 모델·CLI 배정 순서·권한에 초점을 둡니다. 원격 연결은 테일스케일·Orca 보안 위키를 보면 됩니다.