Skip to main content

Documentation Index

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

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

腾讯元宝

腾讯元宝是腾讯的 AI 助手平台。OpenClaw 渠道插件通过 WebSocket 将腾讯元宝机器人连接到 OpenClaw,使其能够通过私信和群聊与用户互动。 Status: 已可用于生产环境,支持机器人私信 + 群聊。WebSocket 是唯一受支持的连接模式。

快速开始

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

使用你的凭证添加腾讯元宝渠道

openclaw channels add --channel yuanbao --token "appKey:appSecret"
--token 的值使用以冒号分隔的 appKey:appSecret 格式。你可以在腾讯元宝应用中通过在应用设置里创建机器人来获取这些值。
2

设置完成后,重启 Gateway 网关以应用更改

openclaw gateway restart

交互式设置(可选方式)

你也可以使用交互式向导:
openclaw channels login --channel yuanbao
按照提示输入你的 App ID 和 App Secret。

访问控制

私信

配置 dmPolicy 来控制谁可以给机器人发送私信:
  • "pairing" — 未知用户会收到配对码;通过 CLI 批准
  • "allowlist" — 只有列在 allowFrom 中的用户可以聊天
  • "open" — 允许所有用户(默认)
  • "disabled" — 禁用所有私信
批准配对请求:
openclaw pairing list yuanbao
openclaw pairing approve yuanbao <CODE>

群聊

提及要求channels.yuanbao.requireMention):
  • true — 必须 @提及(默认)
  • false — 无需 @提及也会回复
在群聊中回复机器人的消息会被视为隐式提及。

配置示例

使用开放私信策略的基础设置

{
  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: "immediate",
    },
  },
}

调整 merge-text 策略

{
  channels: {
    yuanbao: {
      outboundQueueStrategy: "merge-text",
      minChars: 2800, // 缓冲直到达到这么多字符
      maxChars: 3000, // 超过此限制时强制拆分
      idleMs: 5000, // 空闲超时后自动刷新(毫秒)
    },
  },
}

常用命令

命令说明
/help显示可用命令
/status显示机器人状态
/new开始一个新会话
/stop停止当前运行
/restart重启 OpenClaw
/compact压缩会话上下文
腾讯元宝支持原生斜杠命令菜单。Gateway 网关启动时会自动将命令同步到平台。

故障排除

机器人在群聊中没有响应

  1. 确保机器人已被添加到群组
  2. 确保你 @提及了机器人(默认必需)
  3. 检查日志:openclaw logs --follow

机器人没有收到消息

  1. 确保机器人已在腾讯元宝应用中创建并通过审核
  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: "主机器人",
        },
        backup: {
          appKey: "key_yyy",
          appSecret: "secret_yyy",
          name: "备用机器人",
          enabled: false,
        },
      },
    },
  },
}
defaultAccount 用于控制当出站 API 未指定 accountId 时使用哪个账号。

消息限制

  • maxChars — 单条消息最大字符数(默认:3000 个字符)
  • mediaMaxMb — 媒体上传/下载限制(默认:20 MB)
  • overflowPolicy — 消息超过限制时的行为:"split"(默认)或 "stop"

流式传输

腾讯元宝支持块级分块流式传输出。启用后,机器人会在生成文本时分块发送。
{
  channels: {
    yuanbao: {
      disableBlockStreaming: false, // 启用分块流式传输(默认)
    },
  },
}
设置 disableBlockStreaming: true 可将完整回复作为一条消息发送。

群聊历史上下文

控制在群聊中有多少条历史消息会包含在 AI 上下文中:
{
  channels: {
    yuanbao: {
      historyLimit: 100, // 默认:100,设置为 0 可禁用
    },
  },
}

Reply-to 模式

控制机器人在群聊中回复时如何引用消息:
{
  channels: {
    yuanbao: {
      replyToMode: "first", // "off" | "first" | "all"(默认:"first")
    },
  },
}
行为
"off"不使用引用回复
"first"每条入站消息仅第一条回复使用引用(默认)
"all"每条回复都使用引用

Markdown 提示注入

默认情况下,机器人会在系统提示词中注入说明,以防止 AI 模型将整个回复包裹在 markdown 代码块中。
{
  channels: {
    yuanbao: {
      markdownHintEnabled: true, // 默认:true
    },
  },
}

调试模式

为特定机器人 ID 启用未经脱敏的日志输出:
{
  channels: {
    yuanbao: {
      debugBotIds: ["bot_user_id_1", "bot_user_id_2"],
    },
  },
}

多智能体路由

使用 bindings 将腾讯元宝私信或群组路由到不同智能体。
{
  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"(私信)或 "group"(群聊)
  • match.peer.id:用户 ID 或群组代码

配置参考

完整配置:Gateway 网关配置
设置说明默认值
channels.yuanbao.enabled启用/禁用该渠道true
channels.yuanbao.defaultAccount出站路由使用的默认账号default
channels.yuanbao.accounts.<id>.appKeyApp Key(用于签名和票据生成)
channels.yuanbao.accounts.<id>.appSecretApp 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长消息处理方式(splitstopsplit
channels.yuanbao.replyToMode群组 reply-to 策略(offfirstallfirst
channels.yuanbao.outboundQueueStrategy出站策略(merge-textimmediatemerge-text
channels.yuanbao.minCharsmerge-text:触发发送的最小字符数2800
channels.yuanbao.maxCharsmerge-text:每条消息的最大字符数3000
channels.yuanbao.idleMsmerge-text:自动刷新前的空闲超时(毫秒)5000
channels.yuanbao.mediaMaxMb媒体大小限制(MB)20
channels.yuanbao.historyLimit群聊历史上下文条目数100
channels.yuanbao.disableBlockStreaming禁用块级分块流式传输出false
channels.yuanbao.fallbackReply当 AI 未返回内容时的回退回复暂时无法解答,你可以换个问题问问我哦
channels.yuanbao.markdownHintEnabled注入防止 markdown 包裹的提示说明true
channels.yuanbao.debugBotIds调试白名单机器人 ID(未经脱敏的日志)[]

支持的消息类型

接收

  • ✅ 文本
  • ✅ 图片
  • ✅ 文件
  • ✅ 音频 / 语音
  • ✅ 视频
  • ✅ 贴纸 / 自定义表情
  • ✅ 自定义元素(链接卡片等)

发送

  • ✅ 文本(支持 markdown)
  • ✅ 图片
  • ✅ 文件
  • ✅ 音频
  • ✅ 视频
  • ✅ 贴纸

线程和回复

  • ✅ 引用回复(可通过 replyToMode 配置)
  • ❌ 线程回复(平台不支持)

相关内容