·ClawNode멀티에이전트AI에이전트OpenClaw

AI 에이전트를 한 명 잘 운영하는 것과, 여러 명을 팀으로 운영하는 것은 완전히 다른 문제입니다.

R2D2, HK47, BB8, K2SO. 스타워즈 캐릭터 이름을 딴 4개의 에이전트를 디스코드에 배포한 사용자가 있었습니다. 각각 다른 성격, 다른 역할로 설계했습니다.

첫 번째 메시지를 보냈습니다. "Hi R2D2."

네 에이전트가 동시에 응답했습니다. 셋은 "저는 R2D2가 아닙니다"라고 하고, 하나만 "삐뚜루두뚜"를 시도했습니다.

원인은 bindings 설정 미스. 채널별 에이전트 라우팅을 설정하지 않아서 모든 에이전트가 모든 메시지에 반응했습니다.

서브에이전트 vs 독립에이전트

가장 먼저 결정해야 할 것은 이 구분입니다.

서브에이전트 = 파견 직원

  • 용건이 끝나면 소멸합니다
  • 별도 워크스페이스가 없습니다
  • 동시 최대 2개 (4개면 API 429 한도에 걸립니다)
  • 실패해도 주 에이전트가 부분 결과를 반환합니다

독립에이전트 = 분점

  • 별도 워크스페이스, 별도 봇, 별도 SOUL.md를 가집니다
  • 영구적으로 존재합니다
  • 초기 설정과 지속적인 관리가 필요합니다

대부분의 경우 파견 직원으로 충분합니다. "이 일에 전담하는 누군가가 필요하다"는 판단이 설 때만 분점을 씁니다.

워크스페이스 공유가 폭발하는 방식

두 에이전트가 같은 워크스페이스를 공유하면 세 가지 문제가 동시에 생깁니다.

  1. 파일 락 경쟁 — 한 에이전트가 파일을 쓰는 동안 다른 에이전트가 같은 파일에 접근하면 응답이 실패합니다.
  2. 벡터 DB 동시 쓰기 — 인덱스가 손상됩니다. 메모리 검색이 엉뚱한 결과를 반환합니다.
  3. 세션 메타데이터 오염 — Claude가 GPT의 대화 히스토리를 읽고 혼란스러워합니다.

두 사람이 같은 일기장을 동시에 쓰면, 한 사람이 다른 사람의 페이지를 덮어쓰게 됩니다.

해결법: 별도 워크스페이스를 쓰되, 공유해야 할 파일은 symlink로 연결합니다.

서브에이전트 모델 설정이 안 먹히는 이유

멀티에이전트를 쓰는 사람들이 가장 많이 묻는 질문 중 하나입니다.

{
  "agents": {
    "list": [{
      "id": "forge",
      "model": { "primary": "openai/gpt-5.3-codex" }
    }]
  }
}

이렇게 설정해도 실제 spawn 시 메인 에이전트의 기본 모델이 사용됩니다. 아직 agentId → model 자동 매핑이 없습니다.

해결법: spawn할 때 수동으로 모델을 명시해야 합니다.

sessions_spawn({ agentId: "forge", model: "openai-codex/gpt-5.3-codex" })

두 번째로 흔한 실수는 provider prefix입니다. claude/...는 유효하지 않습니다. anthropic/...이 맞습니다.

6개 에이전트의 SOUL.md를 동기화하는 방법

1+5개 에이전트를 운영하면서 중앙 Git 레포로 SOUL.md, TOOLS.md 등 템플릿을 관리하는 사례가 있습니다.

문제는 Git push 후 각 에이전트 워크스페이스에 수동 복사가 필요하다는 점입니다. 6개 에이전트의 SOUL.md를 하나 바꿀 때마다 6번 복사합니다.

해결법: hooks enable boot-md로 게이트웨이 시작 시 자동 배포합니다. 프랜차이즈 본사에서 매뉴얼을 업데이트하면 모든 지점에 자동 배포되는 구조입니다. 에이전트가 2개를 넘어가면 이런 DevOps 패턴이 사실상 필수입니다.

SOUL.md를 잘 설계하는 방법은 이 글에서 따로 다뤘습니다.

에이전트가 자기 자신을 죽인 이슈

GitHub Issue #44000. 가장 극적인 멀티에이전트 사건입니다.

"에이전트가 설정 변경 후 게이트웨이를 재시작하려고 pkill -f openclaw-gateway를 실행했습니다. 에이전트 자신이 그 프로세스 안에서 돌고 있었기 때문에, 같이 죽었습니다. 이후 재시작 명령은 영원히 실행되지 않았습니다."

비행기 조종사가 비행 중에 엔진을 교체하려는 상황입니다.

안전한 재시작 메커니즘(SIGUSR1)이 있지만, 에이전트는 쉘 명령어를 선호합니다. AGENTS.md에 "이 명령은 쓰지 마라"고 명시하거나, 인프라 작업용 도구를 따로 제한해야 합니다.

보고자가 제안한 임시 해결법입니다.

# nohup/setsid로 부모 프로세스에서 분리
nohup sh -c 'pkill -f openclaw-gateway; sleep 2; openclaw gateway' &

에이전트가 도구를 잃어버리는 현상

GitHub Issue #34810.

4시쯤 에이전트가 갑자기 파일 시스템 도구(exec/read/write)를 잃어버렸습니다.
파일 만들어달라고 하면 "터미널에서 직접 실행하세요"라고 합니다.

가능한 원인은 세 가지입니다.

  1. 게이트웨이 재시작 시 도구 바인딩 해제
  2. 세션 리셋 후 도구 권한 미복구
  3. 모델이 "도구가 없다"고 잘못 판단 (환각)

세 번째가 가장 당혹스럽습니다. 도구를 호출할 수 있는데 없다고 믿는 경우입니다. 이때는 세션을 새로 시작하면 해결됩니다.

AI가 "했다고 말했는데 실제로는 안 한" 상황

멀티에이전트 환경에서 이 문제가 더 자주 생깁니다.

에이전트가 없는 파일이 있다고 하고,
읽고 썼다고 하는데 실제로는 아무것도 없었습니다.

원인은 세 가지입니다.

  • 원격 게이트웨이라 다른 서버에 작업했음
  • 샌드박스 디렉토리에 썼는데 임시라 사라짐
  • 모델이 도구 호출 자체를 환각 (진짜 안 한 걸 했다고 믿음)

단일 에이전트보다 멀티에이전트 환경에서 이 상황이 더 복잡합니다. 어느 에이전트가 어떤 작업을 실제로 수행했는지 추적하기 어렵기 때문입니다.

openclaw logs --follow로 도구 호출이 실제 발생했는지 확인하는 습관이 필요합니다. 에이전트 한계와 검증 방법을 참고하세요.

멀티에이전트 운영은 단일 에이전트보다 설계가 훨씬 중요합니다. OpenClaw로 무엇을 자동화할 수 있는지 먼저 파악하려면 AI 업무 자동화 가이드를 보세요. 본격적인 운영 설계가 필요하다면 제품 페이지에서 팀 기능을 확인해보세요.

← 블로그 목록으로