Yuanbao

Tencent Yuanbao는 Tencent의 AI 어시스턴트 플랫폼입니다. OpenClaw 채널 Plugin은 Yuanbao 봇을 WebSocket을 통해 OpenClaw에 연결하여 직접 메시지와 그룹 채팅으로 사용자와 상호작용할 수 있게 합니다.

상태: 봇 DM + 그룹 채팅에 프로덕션 사용 가능. WebSocket이 유일하게 지원되는 연결 모드입니다.

# 빠른 시작

OpenClaw 2026.4.10 이상이 필요합니다. openclaw --version을 실행해 확인하세요. openclaw update로 업그레이드하세요.

openclaw channels add --channel yuanbao --token "appKey:appSecret"

openclaw gateway restart

# 대화형 설정(대안)

대화형 마법사도 사용할 수 있습니다.

openclaw channels login --channel yuanbao

프롬프트에 따라 App ID와 App Secret을 입력하세요.

# 접근 제어

# 직접 메시지

dmPolicy를 구성하여 봇에게 DM을 보낼 수 있는 사용자를 제어하세요.

• "pairing" - 알 수 없는 사용자는 페어링 코드를 받으며, CLI로 승인합니다.
• "allowlist" - allowFrom에 나열된 사용자만 채팅할 수 있습니다.
• "open" - 모든 사용자를 허용합니다(기본값).
• "disabled" - 모든 DM을 비활성화합니다.

페어링 요청 승인:

openclaw pairing list yuanbao
openclaw pairing approve yuanbao <CODE>

# 그룹 채팅

멘션 요구 사항(channels.yuanbao.requireMention):

• true - @mention 필요(기본값)
• false - @mention 없이 응답

그룹 채팅에서 봇의 메시지에 답장하는 것은 암시적 멘션으로 처리됩니다.

# 구성 예시

# 열린 DM 정책을 사용하는 기본 설정

{
  channels: {
    yuanbao: {
      appKey: "your_app_key",
      appSecret: "your_app_secret",
      dm: {
        policy: "open",
      },
    },
  },
}

# 특정 사용자로 DM 제한

{
  channels: {
    yuanbao: {
      appKey: "your_app_key",
      appSecret: "your_app_secret",
      dm: {
        policy: "allowlist",
        allowFrom: ["user_id_1", "user_id_2"],
      },
    },
  },
}

# 그룹에서 @mention 요구 사항 비활성화

{
  channels: {
    yuanbao: {
      requireMention: false,
    },
  },
}

# 발신 메시지 전달 최적화

{
  channels: {
    yuanbao: {
      // Send each chunk immediately without buffering
      outboundQueueStrategy: "immediate",
    },
  },
}

# merge-text 전략 조정

{
  channels: {
    yuanbao: {
      outboundQueueStrategy: "merge-text",
      minChars: 2800, // buffer until this many chars
      maxChars: 3000, // force split above this limit
      idleMs: 5000, // auto-flush after idle timeout (ms)
    },
  },
}

# 일반 명령

Yuanbao는 네이티브 슬래시 명령 메뉴를 지원합니다. Gateway가 시작될 때 명령이 플랫폼에 자동으로 동기화됩니다.

# 문제 해결

# 봇이 그룹 채팅에서 응답하지 않음

1. 봇이 그룹에 추가되었는지 확인하세요.
2. 봇을 @mention했는지 확인하세요(기본적으로 필요).
3. 로그를 확인하세요: openclaw logs --follow

# 봇이 메시지를 받지 못함

1. Yuanbao 앱에서 봇이 생성되고 승인되었는지 확인하세요.
2. appKey와 appSecret이 올바르게 구성되었는지 확인하세요.
3. Gateway가 실행 중인지 확인하세요: openclaw gateway status
4. 로그를 확인하세요: openclaw logs --follow

# 봇이 빈 응답이나 fallback 응답을 보냄

1. AI 모델이 유효한 콘텐츠를 반환하는지 확인하세요.
2. 기본 fallback 응답은 다음과 같습니다. "暂时无法解答，你可以换个问题问问我哦"
3. channels.yuanbao.fallbackReply로 사용자 지정하세요.

# App Secret 유출

1. YuanBao APP에서 App Secret을 재설정하세요.
2. 구성의 값을 업데이트하세요.
3. Gateway를 재시작하세요: openclaw gateway restart

# 고급 구성

# 여러 계정

{
  channels: {
    yuanbao: {
      defaultAccount: "main",
      accounts: {
        main: {
          appKey: "key_xxx",
          appSecret: "secret_xxx",
          name: "Primary bot",
        },
        backup: {
          appKey: "key_yyy",
          appSecret: "secret_yyy",
          name: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

defaultAccount는 발신 API가 accountId를 지정하지 않을 때 사용할 계정을 제어합니다.

# 메시지 제한

• maxChars - 단일 메시지 최대 문자 수(기본값: 3000자)
• mediaMaxMb - 미디어 업로드/다운로드 제한(기본값: 20 MB)
• overflowPolicy - 메시지가 제한을 초과할 때의 동작: "split"(기본값) 또는 "stop"

# 스트리밍

Yuanbao는 블록 수준 스트리밍 출력을 지원합니다. 활성화하면 봇은 텍스트를 생성하는 동안 청크 단위로 전송합니다.

{
  channels: {
    yuanbao: {
      disableBlockStreaming: false, // block streaming enabled (default)
    },
  },
}

완성된 답변을 하나의 메시지로 보내려면 disableBlockStreaming: true를 설정하세요.

# 그룹 채팅 기록 컨텍스트

그룹 채팅의 AI 컨텍스트에 포함할 이전 메시지 수를 제어합니다.

{
  channels: {
    yuanbao: {
      historyLimit: 100, // default: 100, set 0 to disable
    },
  },
}

# 답장 대상 모드

그룹 채팅에서 답장할 때 봇이 메시지를 인용하는 방식을 제어합니다.

{
  channels: {
    yuanbao: {
      replyToMode: "first", // "off" | "first" | "all" (default: "first")
    },
  },
}

# Markdown 힌트 주입

기본적으로 봇은 AI 모델이 전체 답변을 markdown 코드 블록으로 감싸지 않도록 시스템 프롬프트에 지침을 주입합니다.

{
  channels: {
    yuanbao: {
      markdownHintEnabled: true, // default: true
    },
  },
}

# 디버그 모드

특정 봇 ID에 대해 정제되지 않은 로그 출력을 활성화합니다.

{
  channels: {
    yuanbao: {
      debugBotIds: ["bot_user_id_1", "bot_user_id_2"],
    },
  },
}

# 멀티 에이전트 라우팅

bindings를 사용하여 Yuanbao DM 또는 그룹을 다른 에이전트로 라우팅합니다.

{
  agents: {
    list: [
      { id: "main" },
      { id: "agent-a", workspace: "/home/user/agent-a" },
      { id: "agent-b", workspace: "/home/user/agent-b" },
    ],
  },
  bindings: [
    {
      agentId: "agent-a",
      match: {
        channel: "yuanbao",
        peer: { kind: "direct", id: "user_xxx" },
      },
    },
    {
      agentId: "agent-b",
      match: {
        channel: "yuanbao",
        peer: { kind: "group", id: "group_zzz" },
      },
    },
  ],
}

라우팅 필드:

• match.channel: "yuanbao"
• match.peer.kind: "direct"(DM) 또는 "group"(그룹 채팅)
• match.peer.id: 사용자 ID 또는 그룹 코드

# 구성 참조

전체 구성: Gateway 구성

# 지원되는 메시지 유형

# 수신

• ✅ 텍스트
• ✅ 이미지
• ✅ 파일
• ✅ 오디오 / 음성
• ✅ 비디오
• ✅ 스티커 / 사용자 지정 이모지
• ✅ 사용자 지정 요소(링크 카드 등)

# 발신

• ✅ 텍스트(markdown 지원 포함)
• ✅ 이미지
• ✅ 파일
• ✅ 오디오
• ✅ 비디오
• ✅ 스티커

# 스레드와 답장

• ✅ 인용 답장(replyToMode로 구성 가능)
• ❌ 스레드 답장(플랫폼에서 지원하지 않음)

# 관련 항목

• 채널 개요 - 지원되는 모든 채널
• 페어링 - DM 인증 및 페어링 흐름
• 그룹 - 그룹 채팅 동작 및 멘션 게이팅
• 채널 라우팅 - 메시지의 세션 라우팅
• 보안 - 접근 모델 및 강화