跳转至

Yuanbao

Tencent Yuanbao 是 Tencent 的 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 离线,请启动它。

交互式设置(替代方式)

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 支持原生斜杠命令菜单;Gateway 启动时,命令会自动同步到平台。

故障排查

机器人在群聊中不响应:

  1. 确认机器人已添加到群聊
  2. 确认你 @提及了机器人(默认要求)
  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 Secret
  2. 更新配置中的值
  3. 使用 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 提示注入

默认情况下,机器人会注入一条 system-prompt 指令,防止模型将整个回复包裹在 Markdown 代码块中。

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

调试模式

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

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

多智能体路由

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

{
  agents: {
    ownership: "explicit",
    defaults: {
      heartbeat: { agentId: "main" },
      systemAgent: { agentId: "main" },
    },
    entries: {
      main: { workspace: "~/.openclaw/workspace" },
      "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" },
      },
    },
    { agentId: "main", match: { channel: "yuanbao", accountId: "*" } },
  ],
  talk: { agentId: "main" },
}
  • 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 merge-text:触发发送的最小字符数 2800
channels.yuanbao.maxChars merge-text:每条消息最大字符数 3000
channels.yuanbao.idleMs merge-text:自动刷新前的空闲超时(毫秒) 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