채널과 라우팅

OpenClaw는 메시지가 도착한 채널로 응답을 라우팅합니다. 모델이 채널을 선택하는 것이 아니라, 호스트 설정에 의해 결정적으로 제어됩니다.

핵심 용어

  • Channel: whatsapp, telegram, discord, slack, signal, imessage, webchat.
  • AccountId: 채널별 계정 인스턴스 (지원되는 경우).
  • 선택적 채널 기본 계정: channels.<channel>.defaultAccount는 아웃바운드 경로에서 accountId를 지정하지 않을 때 사용할 계정을 선택합니다.
    • 다중 계정 설정에서는 두 개 이상의 계정이 구성된 경우 명시적 기본값 (defaultAccount 또는 accounts.default)을 설정하세요. 없으면 폴백 라우팅이 첫 번째 정규화된 계정 ID를 선택할 수 있습니다.
  • AgentId: 격리된 워크스페이스 + 세션 저장소 (“두뇌”).
  • SessionKey: 컨텍스트 저장과 동시성 제어에 사용되는 버킷 키.

세션 키 형태 (예시)

다이렉트 메시지는 에이전트의 main 세션으로 통합됩니다:

  • agent:<agentId>:<mainKey> (기본값: agent:main:main)

그룹과 채널은 채널별로 격리됩니다:

  • 그룹: agent:<agentId>:<channel>:group:<id>
  • 채널/룸: agent:<agentId>:<channel>:channel:<id>

스레드:

  • Slack/Discord 스레드는 기본 키에 :thread:<threadId>를 추가합니다.
  • Telegram 포럼 토픽은 그룹 키에 :topic:<topicId>를 포함합니다.

예시:

  • agent:main:telegram:group:-1001234567890:topic:42
  • agent:main:discord:channel:123456:thread:987654

메인 DM 라우트 고정

session.dmScope가 main일 때, 다이렉트 메시지는 하나의 메인 세션을 공유할 수 있습니다. 소유자가 아닌 DM이 세션의 lastRoute를 덮어쓰는 것을 방지하기 위해, 다음 조건이 모두 충족되면 OpenClaw가 allowFrom에서 고정 소유자를 추론합니다:

  • allowFrom에 와일드카드가 아닌 항목이 정확히 하나만 있을 때.
  • 해당 항목이 채널의 구체적인 발신자 ID로 정규화될 수 있을 때.
  • 인바운드 DM 발신자가 해당 고정 소유자와 일치하지 않을 때.

이 불일치 상황에서 OpenClaw는 인바운드 세션 메타데이터를 기록하지만, 메인 세션 lastRoute 업데이트는 건너뜁니다.

라우팅 규칙 (에이전트 선택 방법)

라우팅은 각 인바운드 메시지에 대해 하나의 에이전트를 선택합니다:

  1. 정확한 피어 매칭 (bindings의 peer.kind + peer.id).
  2. 상위 피어 매칭 (스레드 상속).
  3. 길드 + 역할 매칭 (Discord) guildId + roles.
  4. 길드 매칭 (Discord) guildId.
  5. 팀 매칭 (Slack) teamId.
  6. 계정 매칭 (채널의 accountId).
  7. 채널 매칭 (해당 채널의 아무 계정, accountId: "*").
  8. 기본 에이전트 (agents.list[].default, 없으면 첫 번째 목록 항목, 폴백은 main).

바인딩에 여러 매칭 필드가 포함된 경우 (peer, guildId, teamId, roles), 제공된 모든 필드가 일치해야 해당 바인딩이 적용됩니다.

매칭된 에이전트가 사용할 워크스페이스와 세션 저장소를 결정합니다.

브로드캐스트 그룹 (여러 에이전트 실행)

브로드캐스트 그룹을 사용하면 OpenClaw가 정상적으로 응답할 때 동일한 피어에 대해 여러 에이전트를 실행할 수 있습니다 (예: WhatsApp 그룹에서 멘션/활성화 게이팅 후).

설정:

{
  broadcast: {
    strategy: "parallel",
    "[email protected]": ["alfred", "baerbel"],
    "+15555550123": ["support", "logger"],
  },
}

참고: Broadcast Groups.

설정 개요

  • agents.list: 에이전트 정의 (워크스페이스, 모델 등).
  • bindings: 인바운드 채널/계정/피어를 에이전트에 매핑.

예시:

{
  agents: {
    list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
  },
  bindings: [
    { match: { channel: "slack", teamId: "T123" }, agentId: "support" },
    { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
  ],
}

세션 저장소

세션 저장소는 상태 디렉토리 (기본값 ~/.openclaw)에 있습니다:

  • ~/.openclaw/agents/<agentId>/sessions/sessions.json
  • JSONL 트랜스크립트는 저장소와 함께 위치합니다

session.store와 {agentId} 템플릿을 통해 저장소 경로를 재정의할 수 있습니다.

게이트웨이와 ACP 세션 검색은 기본 agents/ 루트와 템플릿된 session.store 루트 아래의 디스크 기반 에이전트 저장소를 스캔합니다. 검색된 저장소는 해결된 에이전트 루트 내에 있어야 하며 일반 sessions.json 파일을 사용해야 합니다. 심볼릭 링크와 루트 외부 경로는 무시됩니다.

WebChat 동작

WebChat은 선택된 에이전트에 연결되며 에이전트의 메인 세션을 기본으로 사용합니다. 이를 통해 해당 에이전트의 크로스 채널 컨텍스트를 한 곳에서 볼 수 있습니다.

응답 컨텍스트

인바운드 응답에는 다음이 포함됩니다:

  • 사용 가능한 경우 ReplyToId, ReplyToBody, ReplyToSender.
  • 인용된 컨텍스트는 Body에 [Replying to ...] 블록으로 추가됩니다.

이는 채널 간에 일관됩니다.

arrow_back
이전
Broadcast Groups
다음
Location
arrow_forward