Skip to main content
하나의 Gateway 프로세스에서 여러 격리된 에이전트를 실행합니다. 각 에이전트는 자체 워크스페이스, 상태 디렉터리(agentDir), SQLite 기반 세션 기록을 가지며, 여러 채널 계정(예: 두 개의 WhatsApp 번호)도 사용할 수 있습니다. 수신 메시지는 바인딩을 통해 올바른 에이전트로 라우팅됩니다. 에이전트는 워크스페이스 파일, 인증 프로필, 모델 레지스트리, 세션 저장소를 포함하는 페르소나별 전체 범위입니다. 바인딩은 채널 계정(Slack 워크스페이스, WhatsApp 번호 등)을 이러한 에이전트 중 하나에 매핑합니다.

에이전트란 무엇인가

각 에이전트에는 다음 항목이 개별적으로 제공됩니다.
  • 워크스페이스: 파일, AGENTS.md/SOUL.md/USER.md, 로컬 메모, 페르소나 규칙.
  • 상태 디렉터리(agentDir): 인증 프로필, 모델 레지스트리, 에이전트별 구성.
  • 세션 저장소: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite에 저장되는 채팅 기록 및 라우팅 상태.
인증 프로필은 에이전트별로 관리되며 다음 위치에서 읽습니다.
sessions_history는 더 안전한 세션 간 회상 경로입니다. 원시 대화 기록 덤프가 아니라 범위가 제한되고 민감 정보가 제거된 보기를 반환합니다. 사고 블록 서명, 도구 결과 페이로드 세부 정보, <relevant-memories> 스캐폴딩, 도구 호출 XML 태그(<tool_call>, <function_call> 및 각각의 복수형/하위 호환 형식), MiniMax 도구 호출 XML을 제거한 다음, 출력을 자르고 바이트 크기로 제한합니다.
여러 에이전트에서 agentDir을 절대 재사용하지 마십시오. 인증/세션 상태 충돌이 발생합니다. 보조 에이전트의 로컬 OAuth 자격 증명이 만료되거나 갱신에 실패하면 OpenClaw는 동일한 프로필 ID에 해당하는 기본/main 에이전트의 자격 증명까지 읽어 가장 최신 토큰을 채택하며, 갱신 토큰은 보조 에이전트의 저장소에 복사하지 않습니다. 완전히 독립적인 OAuth 계정을 사용하려면 해당 에이전트에서 로그인하십시오. 자격 증명을 수동으로 복사하는 경우 이식 가능한 정적 api_key 또는 token 프로필만 복사하십시오. OAuth 갱신 자료는 기본적으로 이식할 수 없습니다(copyToAgents를 사용하면 프로필을 명시적으로 포함할 수 있습니다).
Skills는 각 에이전트 워크스페이스와 ~/.openclaw/skills 같은 공유 루트에서 로드된 다음, 적용되는 에이전트 Skills 허용 목록에 따라 필터링됩니다. 공유 기준에는 agents.defaults.skills를 사용하고, 에이전트별 대체 항목에는 agents.list[].skills를 사용하십시오(명시적 항목은 기본값을 대체하며 병합되지 않습니다). Skills: 에이전트별 및 공유Skills: 에이전트 허용 목록을 참조하십시오. Plugin 소유 저장소는 해당 Plugin의 구성을 따릅니다. 두 번째 에이전트를 추가해도 모든 전역 Plugin 저장소가 자동으로 분리되지는 않습니다. 예를 들어 페르소나 간에 컴파일된 위키 지식을 공유하지 않아야 하는 경우 에이전트별 Memory Wiki 볼트를 구성하십시오.
워크스페이스 참고: 각 에이전트의 워크스페이스는 기본 cwd이며 강제 샌드박스가 아닙니다. 상대 경로는 워크스페이스 내부에서 해석되지만, 샌드박싱을 활성화하지 않으면 절대 경로를 통해 호스트의 다른 위치에 접근할 수 있습니다. 샌드박싱을 참조하십시오.

경로

단일 에이전트 모드(기본값)

아무것도 구성하지 않으면 OpenClaw는 하나의 에이전트를 실행합니다.
  • agentId의 기본값은 main입니다.
  • 세션 키는 agent:main:<mainKey> 형식입니다(기본 mainKeymain).
  • 워크스페이스의 기본값은 ~/.openclaw/workspace입니다(OPENCLAW_PROFILEdefault 이외의 값으로 설정된 경우 workspace-<profile>).
  • 상태의 기본값은 ~/.openclaw/agents/main/agent입니다.

에이전트 도우미

격리된 새 에이전트를 추가합니다.
플래그: --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]>(반복 가능), --non-interactive(--workspace 필요). 수신 메시지를 라우팅하도록 bindings를 추가한 다음(마법사가 이 작업을 제안합니다) 확인합니다.

빠른 시작

1

각 에이전트 워크스페이스 생성

각 에이전트에는 SOUL.md, AGENTS.md, 선택적 USER.md가 포함된 자체 워크스페이스와 전용 agentDir, 그리고 ~/.openclaw/agents/<agentId> 아래의 세션 저장소가 제공됩니다.
2

채널 계정 생성

선호하는 채널에서 에이전트마다 계정을 하나씩 생성하십시오.
  • Discord: 에이전트마다 봇 하나를 사용하고, Message Content Intent를 활성화한 다음 각 토큰을 복사합니다.
  • Telegram: BotFather를 통해 에이전트마다 봇 하나를 만들고 각 토큰을 복사합니다.
  • WhatsApp: 계정마다 각 전화번호를 연결합니다.
채널 가이드를 참조하십시오: Discord, Telegram, WhatsApp.
3

에이전트, 계정 및 바인딩 추가

agents.list 아래에 에이전트를, channels.<channel>.accounts 아래에 채널 계정을 추가하고, bindings로 연결합니다(아래 예시 참조).
4

재시작 및 확인

여러 에이전트, 여러 페르소나

구성된 각 agentId는 핵심 에이전트 상태에 대해 서로 구분되는 페르소나 경계입니다.
  • 채널별로 서로 다른 계정(accountId별).
  • 서로 다른 성격(에이전트별 AGENTS.md/SOUL.md).
  • 별도의 인증 및 세션. 에이전트 간 접근은 명시적 기능이나 Plugin 구성을 통해서만 활성화됩니다.
이를 통해 여러 사람이 하나의 Gateway를 공유하면서 핵심 에이전트 상태를 서로 분리할 수 있습니다.

에이전트별 Memory Wiki 볼트

Memory Wiki는 기본적으로 하나의 전역 볼트를 사용합니다. 지원 에이전트가 컴파일한 지식을 마케팅 에이전트의 지식과 분리하려면 plugins.entries.memory-wiki.config.vault.scopeagent로 설정합니다.
구성된 경로는 상위 디렉터리입니다. OpenClaw는 정규화된 에이전트 ID를 추가하여 ~/.openclaw/wiki/support~/.openclaw/wiki/marketing과 같은 경로를 생성합니다. 여러 에이전트가 구성된 경우 에이전트 범위 CLI 및 Gateway 작업에는 에이전트를 명시적으로 지정해야 합니다. 브리지 필터링, 마이그레이션 및 신뢰 경계에 관한 자세한 내용은 Memory Wiki 에이전트별 볼트를 참조하십시오.

에이전트 간 QMD 메모리 검색

한 에이전트가 다른 에이전트의 QMD 세션 트랜스크립트를 검색할 수 있도록 하려면 agents.list[].memorySearch.qmd.extraCollections 아래에 추가 컬렉션을 추가합니다. 모든 에이전트가 동일한 컬렉션을 공유해야 하는 경우 agents.defaults.memorySearch.qmd.extraCollections를 사용합니다.
추가 컬렉션 경로는 에이전트 간에 공유할 수 있지만, 경로가 에이전트 워크스페이스 외부에 있으면 name을 명시적으로 유지해야 합니다. 워크스페이스 내부의 경로는 에이전트 범위로 유지되므로 각 에이전트가 자체 트랜스크립트 검색 세트를 보유합니다.

하나의 WhatsApp 번호, 여러 사용자(DM 분리)

하나의 WhatsApp 계정에서 발신자의 E.164(+15551234567)를 peer.kind: "direct"와 일치시켜 서로 다른 WhatsApp DM을 서로 다른 에이전트로 라우팅합니다. 응답은 여전히 동일한 WhatsApp 번호에서 전송되며, 에이전트별 발신자 ID는 없습니다.
직접 채팅은 기본적으로 에이전트의 기본 세션 키로 통합되므로, 완전한 격리를 위해서는 사용자마다 에이전트 하나가 필요합니다.
DM 접근 제어(페어링/허용 목록)는 에이전트별이 아니라 WhatsApp 계정별로 전역 적용됩니다. 공유 그룹의 경우 그룹을 하나의 에이전트에 바인딩하거나 브로드캐스트 그룹을 사용합니다.

라우팅 규칙

바인딩은 결정론적이며 가장 구체적인 항목이 우선합니다. 전체 계층 순서(정확한 피어, 상위 피어, 피어 와일드카드, 길드+역할, 길드, 팀, 계정, 채널, 기본 에이전트)는 채널 라우팅을 참조하십시오. 여기서 강조할 만한 몇 가지 규칙은 다음과 같습니다.
  • 동일한 계층에서 여러 바인딩이 일치하면 구성 순서상 첫 번째 바인딩이 우선합니다.
  • 바인딩에 여러 일치 필드(예: peer + guildId)가 설정되어 있으면 지정된 모든 필드가 일치해야 합니다(AND 의미 체계).
  • accountId가 생략된 바인딩은 모든 계정이 아니라 기본 계정에만 일치합니다. 채널 전체 대체 경로에는 accountId: "*"를, 하나의 계정에는 accountId: "<name>"을 사용합니다. 동일한 바인딩을 명시적 계정 ID와 함께 다시 추가하면 기존 채널 전용 바인딩을 중복 생성하지 않고 업그레이드합니다.

여러 계정/전화번호

여러 계정을 지원하는 채널(예: WhatsApp)은 accountId를 사용하여 각 로그인을 식별합니다. 각 accountId는 자체 에이전트로 라우팅되므로 하나의 서버에서 세션을 혼합하지 않고 여러 전화번호를 호스팅할 수 있습니다. accountId가 생략될 때 사용할 계정을 선택하려면 channels.<channel>.defaultAccount를 설정합니다. 설정하지 않으면 OpenClaw는 default가 있는 경우 이를 사용하고, 그렇지 않으면 구성된 첫 번째 계정 ID(정렬 기준)를 사용합니다. 여러 계정을 지원하는 채널: discord, feishu, googlechat, imessage, irc, line, mattermost, matrix, nextcloud-talk, nostr, signal, slack, telegram, whatsapp, zalo, zalouser.

개념

  • agentId: 하나의 “두뇌”(워크스페이스, 에이전트별 인증, 에이전트별 세션 저장소).
  • accountId: 하나의 채널 계정 인스턴스(예: WhatsApp 계정 personalbiz).
  • binding: (channel, accountId, peer) 및 선택적으로 길드/팀 ID를 기준으로 수신 메시지를 agentId에 라우팅합니다.
  • 직접 채팅은 agent:<agentId>:<mainKey>로 통합됩니다(에이전트별 “메인”, session.mainKey 참조).

플랫폼 예시

각 Discord 봇 계정은 고유한 accountId에 매핑됩니다. 각 계정을 에이전트에 바인딩하고 봇별 허용 목록을 유지하십시오.
  • 각 봇을 길드에 초대하고 Message Content Intent를 활성화하십시오.
  • 토큰은 channels.discord.accounts.<id>.token에 저장됩니다(기본 계정은 DISCORD_BOT_TOKEN을 사용할 수 있습니다).
  • BotFather에서 에이전트마다 봇을 하나씩 만들고 각 토큰을 복사하십시오.
  • 토큰은 channels.telegram.accounts.<id>.botToken에 저장됩니다(기본 계정은 TELEGRAM_BOT_TOKEN을 사용할 수 있습니다).
  • 동일한 Telegram 그룹에서 여러 봇을 사용하는 경우 각 봇을 초대한 뒤 응답해야 하는 봇을 멘션하십시오.
  • 각 그룹 봇의 BotFather Privacy Mode를 비활성화하고(/setprivacy -> Disable), Telegram에서 설정을 적용할 수 있도록 봇을 제거한 후 다시 추가하십시오.
  • channels.telegram.groups로 그룹을 허용하거나, 신뢰할 수 있는 그룹 배포에만 groupPolicy: "open"을 사용하십시오.
  • 발신자 사용자 ID는 groupAllowFrom에 넣으십시오. 그룹 및 슈퍼그룹 ID는 groupAllowFrom이 아니라 channels.telegram.groups에 속합니다.
  • 각 봇이 자체 에이전트로 라우팅되도록 accountId를 기준으로 바인딩하십시오.
Gateway를 시작하기 전에 각 계정을 연결하십시오.
~/.openclaw/openclaw.json(JSON5):

일반적인 패턴

채널별로 분리합니다. WhatsApp은 빠른 일상용 에이전트로, Telegram은 Opus 에이전트로 라우팅합니다.
이 예시에서는 accountId: "*"을 사용하므로 나중에 계정을 추가해도 바인딩이 계속 작동합니다. 나머지는 채팅 에이전트에 유지하면서 단일 DM/그룹을 Opus로 라우팅하려면 해당 피어에 대한 match.peer 바인딩을 추가하십시오. 피어 일치는 항상 채널 전체 규칙보다 우선합니다.

에이전트별 샌드박스 및 도구 구성

각 에이전트는 자체 샌드박스 및 도구 제한을 가질 수 있습니다.
setupCommandsandbox.docker 아래에 있으며 컨테이너 생성 시 한 번 실행됩니다. 확인된 범위가 "shared"이면 에이전트별 sandbox.docker.* 재정의는 무시됩니다.
이 구성은 다음과 같은 이점을 제공합니다.
  • 보안 격리: 신뢰할 수 없는 에이전트의 도구를 제한합니다.
  • 리소스 제어: 일부 에이전트는 샌드박스에서 실행하면서 나머지는 호스트에서 유지합니다.
  • 유연한 정책: 에이전트마다 서로 다른 권한을 적용합니다.
tools.elevated에는 전역 게이트(tools.elevated.enabled/allowFrom)와 에이전트별 게이트(agents.list[].tools.elevated.enabled/allowFrom)가 모두 있습니다. 에이전트별 게이트는 전역 게이트보다 더 제한할 수만 있습니다. 상승된 권한 명령을 실행하려면 두 게이트 모두 발신자를 허용해야 합니다. 그룹을 대상으로 지정하려면 agents.list[].groupChat.mentionPatterns를 사용하여 @멘션이 의도한 에이전트에 명확하게 매핑되도록 하십시오.
자세한 예시는 다중 에이전트 샌드박스 및 도구를 참조하십시오.

관련 항목