元寶

Tencent Yuanbao 是騰訊的 AI 助理平台。OpenClaw channel plugin 透過 WebSocket 將 Yuanbao 機器人連接到 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",
    },
  },
}

# 調整合併文字策略

{
  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

# 機器人傳送空白或後備回覆

1. 檢查 AI 模型是否回傳有效內容
2. 預設後備回覆是："暂时无法解答，你可以换个问题问问我哦"
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 設定）
• ❌ 執行緒回覆（平台不支援）

# 相關

• Channels Overview - 所有支援的 channel
• Pairing - DM 驗證與配對流程
• Groups - 群組聊天行為與提及控管
• Channel Routing - 訊息的工作階段路由
• Security - 存取模型與強化措施