OpenClaw 멀티 에이전트(Multi‑Agent Routing) 개념 가이드 (다중 자아)

OpenClaw 멀티 에이전트(Multi‑Agent Routing) 개념 가이드 (한글 번역/정리)

원문: https://docs.openclaw.ai/concepts/multi-agent

이 문서는 OpenClaw 공식 문서의 Multi‑Agent Routing 페이지 내용을 기반으로, 핵심 개념을 한국어로 번역/정리한 것입니다.

1) 멀티 에이전트 라우팅이란?

목표(Goal): 하나의 Gateway 프로세스에서

• 여러 개의 “서로 격리된 에이전트”(각각 별도 workspace + agentDir + sessions)와

• 여러 개의 채널 계정(예: WhatsApp 계정 2개, Telegram 봇 2개)을 함께 운영하면서,

들어오는 메시지를 bindings(바인딩 규칙)으로 특정 에이전트에게 라우팅하는 기능입니다.

2) “에이전트 1개(one agent)”는 무엇인가?

문서에서 말하는 에이전트는 “완전히 스코프가 분리된 하나의 두뇌(brain)”입니다. 에이전트마다 독립적으로 다음을 가집니다.

• Workspace

파일, AGENTS.md / SOUL.md / USER.md 같은 에이전트 규칙 파일, 로컬 노트, 페르소나 규칙 등.

• State directory (`agentDir`)

인증 프로필(auth profiles), 모델 레지스트리, 에이전트별 설정이 들어갑니다.

• Session store

채팅 히스토리 + 라우팅 상태가 저장됩니다. 기본적으로 ~/.openclaw/agents/<agentId>/sessions 아래.

인증(Auth) 프로필은 에이전트별로 분리

• 각 에이전트는 자기 agentDir의 auth-profiles.json을 읽습니다.

• 메인 에이전트의 인증정보는 자동으로 공유되지 않습니다.

• 문서에서 강조: `agentDir`를 여러 에이전트가 재사용하면(auth/session 충돌) 절대 안 됨.

공유가 꼭 필요하면 “재사용”이 아니라 파일을 복사(copy) 하는 방식으로만 권장합니다.

Workspace는 “기본 cwd”이지 하드 샌드박스가 아님

• 상대경로는 workspace 내부로 해석되지만,

• 절대경로는 호스트의 다른 경로로도 접근 가능할 수 있음(샌드박싱 설정이 꺼져있다면).

3) 경로(Paths) 빠른 맵

문서에 정리된 기본 경로 요약:

• Config: ~/.openclaw/openclaw.json (또는 OPENCLAW_CONFIG_PATH)

• State dir: ~/.openclaw (또는 OPENCLAW_STATE_DIR)

• Workspace: ~/.openclaw/workspace (또는 ~/.openclaw/workspace-<agentId>)

• Agent dir: ~/.openclaw/agents/<agentId>/agent (또는 agents.list[].agentDir)

• Sessions: ~/.openclaw/agents/<agentId>/sessions

4) 싱글 에이전트 모드(기본)

아무 설정도 하지 않으면 OpenClaw는 기본적으로 단일 에이전트로 동작합니다.

• agentId 기본값: main

• 세션 키: agent:main:<mainKey>

• workspace 기본값: ~/.openclaw/workspace

• state 기본값: ~/.openclaw/agents/main/agent

5) 에이전트 추가(Agent helper / wizard)

문서에서는 에이전트 위저드를 통해 새 에이전트를 추가하라고 안내합니다.

openclaw agents add work
openclaw agents list --bindings

6) 멀티 에이전트의 효과: 여러 사람/여러 페르소나를 한 서버에서

멀티 에이전트를 쓰면, 각 agentId는 완전히 분리된 페르소나가 됩니다.

• 에이전트마다 다른 채널 계정/전화번호(채널의 accountId)를 쓸 수 있음

• 에이전트마다 다른 성격/규칙(workspace의 AGENTS.md, SOUL.md 등)을 가질 수 있음

• 인증/세션이 분리되어 기본적으로 서로 섞이지 않음

즉, 하나의 Gateway 서버를 여러 사람이 공유해도 “AI 두뇌/데이터”를 분리 운영할 수 있게 해줍니다.

7) 라우팅 규칙: 메시지가 어떤 에이전트로 가는가?

바인딩(bindings)은 결정적(deterministic)이며 “가장 구체적인 매칭이 우선”입니다.

우선순위(문서 요약):

1. peer 매칭 (정확한 DM/그룹/채널 id)

2. parentPeer 매칭 (스레드 상속)

3. guildId + roles (Discord 역할 라우팅)

4. guildId (Discord)

5. teamId (Slack)

6. accountId (채널 계정 인스턴스)

7. 채널 레벨 매칭 (accountId: "*")

8. 기본 에이전트 fallback

(agents.list[].default가 있으면 그 에이전트, 아니면 첫 항목, 기본은 main)

추가 규칙:

• 같은 티어에서 여러 바인딩이 매칭되면 설정 파일에서 먼저 나온 binding이 승리

• 한 binding에 match 조건이 여러 개면 모두 만족해야 함(AND)

8) 멀티 계정/전화번호(accountId) 개념

여러 계정을 지원하는 채널(예: WhatsApp)은 accountId로 로그인 인스턴스를 구분합니다. 각 accountId를 서로 다른 에이전트에 매핑할 수 있어, 한 서버에서 여러 번호/계정을 운영해도 세션이 섞이지 않게 만들 수 있습니다.

9) 핵심 용어 정리

• agentId: 하나의 “두뇌”(workspace + 에이전트별 인증 + 에이전트별 세션 저장소)

• accountId: 채널 계정 인스턴스(예: Telegram 봇 A/B, WhatsApp personal/biz)

• binding: (channel, accountId, peer, guild/team 등) 조건으로 들어오는 메시지를 특정 agentId로 라우팅하는 규칙

10) 플랫폼 예시: Telegram 봇을 에이전트별로 분리(봇 토큰 여러 개)

문서의 “Telegram bots per agent” 예시는 다음 구조입니다.

• 에이전트 2개 (main, alerts)

• Telegram 채널 계정 2개 (default, alerts) → 각자 봇 토큰 보유

• 바인딩에서 accountId로 라우팅

{
  "agents": {
    "list": [
      { "id": "main", "workspace": "~/.openclaw/workspace-main" },
      { "id": "alerts", "workspace": "~/.openclaw/workspace-alerts" }
    ]
  },
  "bindings": [
    { "agentId": "main", "match": { "channel": "telegram", "accountId": "default" } },
    { "agentId": "alerts", "match": { "channel": "telegram", "accountId": "alerts" } }
  ],
  "channels": {
    "telegram": {
      "accounts": {
        "default": {
          "botToken": "123456:ABC...",
          "dmPolicy": "pairing"
        },
        "alerts": {
          "botToken": "987654:XYZ...",
          "dmPolicy": "allowlist",
          "allowFrom": ["tg:123456789"]
        }
      }
    }
  }
}

중요 포인트

• channels 아래 키는 telegram-dev처럼 임의로 늘리는 방식이 아니라,

• 같은 telegram 채널 안에 accounts로 여러 봇을 두고,

• bindings에서 accountId로 에이전트에 연결하는 방식이 문서의 정식 패턴입니다.

11) 운영 팁(문서에서 강조하는 실수 방지)

• agentDir는 에이전트 간 공유 금지(인증/세션 충돌)

• workspace는 기본 cwd일 뿐, 보안 격리가 필요하면 샌드박싱 설정을 검토

• 멀티 계정 채널은 accountId 설계를 먼저 하고 bindings를 얹는 편이 안정적