跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Tencent Yuanbao 是騰訊的 AI 助理平台。OpenClaw channel plugin 透過 WebSocket 將 Yuanbao 機器人連接到 OpenClaw,讓它們可以透過 直接訊息與群組聊天與使用者互動。 狀態: 可用於生產環境的機器人 DM + 群組聊天。WebSocket 是唯一支援的連線模式。

快速開始

需要 OpenClaw 2026.4.10 或以上版本。 執行 openclaw --version 檢查版本。使用 openclaw update 升級。
1

使用你的憑證新增 Yuanbao channel

openclaw channels add --channel yuanbao --token "appKey:appSecret"
--token 值使用以冒號分隔的 appKey:appSecret 格式。你可以在 Yuanbao 應用程式中,透過在應用程式設定建立機器人來取得這些值。
2

設定完成後,重新啟動 gateway 以套用變更

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)
    },
  },
}

常用指令

指令說明
/help顯示可用指令
/status顯示機器人狀態
/new啟動新工作階段
/stop停止目前執行
/restart重新啟動 OpenClaw
/compact壓縮工作階段上下文
Yuanbao 支援原生斜線指令選單。指令會在 gateway 啟動時自動同步到平台。

疑難排解

機器人在群組聊天中沒有回應

  1. 確認機器人已加入群組
  2. 確認你已 @mention 機器人(預設為必要)
  3. 檢查記錄:openclaw logs --follow

機器人未收到訊息

  1. 確認機器人已在 Yuanbao 應用程式中建立並核准
  2. 確認 appKeyappSecret 已正確設定
  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")
    },
  },
}
行為
"off"不引用回覆
"first"每則傳入訊息只引用第一則回覆(預設)
"all"引用每一則回覆

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 設定
設定說明預設
channels.yuanbao.enabled啟用/停用 channeltrue
channels.yuanbao.defaultAccount傳出路由的預設帳號default
channels.yuanbao.accounts.<id>.appKeyApp Key(用於簽署和票證產生)-
channels.yuanbao.accounts.<id>.appSecretApp Secret(用於簽署)-
channels.yuanbao.accounts.<id>.token預先簽署的權杖(略過自動票證簽署)-
channels.yuanbao.accounts.<id>.name帳號顯示名稱-
channels.yuanbao.accounts.<id>.enabled啟用/停用特定帳號true
channels.yuanbao.dm.policyDM 政策open
channels.yuanbao.dm.allowFromDM 允許清單(使用者 ID 清單)-
channels.yuanbao.requireMention群組中需要 @mentiontrue
channels.yuanbao.overflowPolicy長訊息處理(splitstopsplit
channels.yuanbao.replyToMode群組 reply-to 策略(offfirstallfirst
channels.yuanbao.outboundQueueStrategy傳出策略(merge-textimmediatemerge-text
channels.yuanbao.minChars合併文字:觸發傳送的最小字元數2800
channels.yuanbao.maxChars合併文字:每則訊息的最大字元數3000
channels.yuanbao.idleMs合併文字:自動清空前的閒置逾時(毫秒)5000
channels.yuanbao.mediaMaxMb媒體大小限制(MB)20
channels.yuanbao.historyLimit群組聊天歷史上下文項目100
channels.yuanbao.disableBlockStreaming停用區塊層級串流輸出false
channels.yuanbao.fallbackReplyAI 未回傳內容時的後備回覆暂时无法解答,你可以换个问题问问我哦
channels.yuanbao.markdownHintEnabled注入 markdown 防包裹指示true
channels.yuanbao.debugBotIds偵錯允許清單機器人 ID(未清理記錄)[]

支援的訊息類型

接收

  • ✅ 文字
  • ✅ 圖片
  • ✅ 檔案
  • ✅ 音訊 / 語音
  • ✅ 影片
  • ✅ 貼圖 / 自訂表情符號
  • ✅ 自訂元素(連結卡片等)

傳送

  • ✅ 文字(支援 markdown)
  • ✅ 圖片
  • ✅ 檔案
  • ✅ 音訊
  • ✅ 影片
  • ✅ 貼圖

執行緒與回覆

  • ✅ 引用回覆(可透過 replyToMode 設定)
  • ❌ 執行緒回覆(平台不支援)

相關