Yuanbao

Tencent Yuanbao 是腾讯的 AI 助手平台。社区维护的 openclaw-plugin-yuanbao 插件通过 WebSocket 将 Yuanbao 机器人连接到 OpenClaw，用于直接消息和群聊。

状态： 已可用于生产环境的机器人直接消息和群聊。WebSocket 是唯一支持的连接模式。此插件由 Tencent Yuanbao 团队作为外部目录条目维护，而非由 OpenClaw 核心维护；以下配置/行为细节（安装和通用 CLI 界面之外）来自插件自身文档，未针对 OpenClaw 核心源码进行验证。

快速开始¶

需要 OpenClaw 2026.4.10 或更高版本。使用 openclaw --version 检查；使用 openclaw update 升级。

1. 使用你的凭据添加 Yuanbao 通道

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

--token 使用冒号分隔的 appKey:appSecret。在 Yuanbao 应用中，通过应用设置创建机器人来获取这些值。

2. 验证通道

配置更改遵循热重载。检查通道是否就绪：

openclaw channels status --probe

如果 Gateway 离线，请启动 Gateway。

交互式设置（替代方案）¶

openclaw channels login --channel yuanbao

按照提示输入你的 App Key（appKey）和 App Secret（appSecret）。

访问控制¶

直接消息¶

channels.yuanbao.dm.policy：

值	行为
`open`（默认）	允许所有用户
`pairing`	未知用户会获得配对码；通过 CLI 批准
`allowlist`	仅 `allowFrom` 中的用户可以聊天
`disabled`	禁用所有直接消息

批准配对请求：

openclaw pairing list yuanbao
openclaw pairing approve yuanbao <CODE>

群聊¶

channels.yuanbao.requireMention（默认 true）：要求机器人在群聊中响应前必须被 @提及。回复机器人自己的消息被视为隐式提及。

配置示例¶

基本设置，开放直接消息策略：

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

将直接消息限制为特定用户：

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

在群聊中禁用 @提及要求：

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

出站投递调优：

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

设置 outboundQueueStrategy: "immediate" 以无缓冲方式发送每个数据块。

常用命令¶

命令	描述
`/help`	显示可用命令
`/status`	显示机器人状态
`/new`	开始新会话
`/stop`	停止当前运行
`/restart`	重启 OpenClaw
`/compact`	压缩会话上下文

Yuanbao 支持原生斜杠命令菜单；网关启动时命令会自动同步到平台。

故障排查¶

机器人在群聊中不响应：

确认机器人已添加到群聊
确认你 @提及了机器人（默认要求）
检查日志：openclaw logs --follow

机器人未收到消息：

确认机器人已在 Yuanbao 应用中创建并获批
确认 appKey 和 appSecret 已正确配置
确认网关正在运行：openclaw gateway status
检查日志：openclaw logs --follow

机器人发送空回复或回退回复：

检查 AI 模型是否返回有效内容
默认回退回复："暂时无法解答，你可以换个问题问问我哦"
使用 channels.yuanbao.fallbackReply 自定义

App Secret 泄露：

在 Yuanbao 应用中重置 App Secret
更新配置中的值
使用 openclaw channels status --probe 验证热重载是否已应用新凭据。

高级配置¶

多个账户¶

{
  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 以在一条消息中发送完整回复。

群聊历史上下文¶

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

控制群聊中 AI 上下文包含多少条历史消息。

回复模式¶

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

值	行为
`off`	不引用回复
`first`	仅引用每条入站消息中的第一条回复（默认）
`all`	引用所有回复

Markdown 提示注入¶

默认情况下，机器人会注入一条系统提示指令，以防止模型将整个回复包裹在 Markdown 代码块中。

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

调试模式¶

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

为列出的机器人 ID 启用未脱敏的日志输出。

多智能体路由¶

使用 bindings 将 Yuanbao 私聊或群聊路由到不同的智能体：

{
  agents: {
    entries: {
      main: { default: true },
      "agent-a": { workspace: "/home/user/agent-a" },
      "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"（私聊）或 "group"（群聊）
match.peer.id：用户 ID 或群组代码

配置参考¶

完整配置：网关配置

设置	描述	默认值
`channels.yuanbao.enabled`	启用/禁用该通道	`true`
`channels.yuanbao.defaultAccount`	出站路由的默认账号	`default`
`channels.yuanbao.accounts.<id>.appKey`	App Key（签名 + 票据生成）	-
`channels.yuanbao.accounts.<id>.appSecret`	App Secret（签名）	-
`channels.yuanbao.accounts.<id>.token`	预签名 token（跳过自动票据签名）	-
`channels.yuanbao.accounts.<id>.name`	账号显示名称	-
`channels.yuanbao.accounts.<id>.enabled`	启用/禁用特定账号	`true`
`channels.yuanbao.dm.policy`	私聊策略	`open`
`channels.yuanbao.dm.allowFrom`	私聊白名单（用户 ID 列表）	-
`channels.yuanbao.requireMention`	在群聊中要求 @提及	`true`
`channels.yuanbao.overflowPolicy`	长消息处理方式（`split` 或 `stop`）	`split`
`channels.yuanbao.replyToMode`	群聊回复策略（`off`、`first`、`all`）	`first`
`channels.yuanbao.outboundQueueStrategy`	出站策略（`merge-text` 或 `immediate`）	`merge-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.fallbackReply`	当模型未返回内容时的兜底回复	`暂时无法解答，你可以换个问题问问我哦`
`channels.yuanbao.markdownHintEnabled`	注入 Markdown 防包裹指令	`true`
`channels.yuanbao.debugBotIds`	调试白名单机器人 ID（未脱敏日志）	`[]`

支持的消息类型¶

接收： 文本、图片、文件、音频/语音、视频、贴纸/自定义表情、自定义元素（链接卡片）。

发送： 文本（Markdown）、图片、文件、音频、视频、贴纸。

线程与回复： 支持引用回复（可通过 replyToMode 配置）；平台不支持线程回复。

通道总览 - 所有受支持的通道
配对 - 私聊认证与配对流程
群聊 - 群聊行为与 @提及控制
通道路由 - 消息的会话路由
安全 - 访问模型与安全加固

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw