Appearance
解决 OpenClaw 连接腾讯元宝机器人时的配置、权限和消息异常问题。适用场景：连接元宝机器人到聊天应用（私聊/群聊），排查机器人无回应、消息为空等故障。关键操作：使用 openclaw channels add --channel yuanbao --token "appKey:appSecret" 添加通道，然后 openclaw gateway restart 生效；通过 dmPolicy 控制私聊权限，requireMention 控制群聊是否需要 @ 提及。限制：仅支持 WebSocket 连接，不支持线程回复，单消息最大 3000 字符。
OpenClaw 元宝通道配置与故障排查
OpenClaw 的元宝（Yuanbao）通道插件通过 WebSocket 将腾讯元宝机器人接入网关，支持私聊和群聊中的文本、图片、文件、语音等消息类型。本文档涵盖从快速接入、权限控制、高级配置到常见故障的完整流程。
状态：生产可用（私聊 + 群聊）。仅支持 WebSocket 连接模式。
快速接入
要求 OpenClaw 2026.4.10 或更高版本。 运行
openclaw --version检查版本。使用openclaw update升级。
使用凭据添加元宝通道
bash
openclaw channels add --channel yuanbao --token "appKey:appSecret"--token 值使用冒号分隔的 appKey:appSecret 格式。你可以在元宝应用的后台创建机器人时获取这些信息。
设置完成后，重启网关以应用配置
bash
openclaw gateway restart交互式配置（备选）
也可使用交互式向导：
bash
openclaw channels login --channel yuanbao按提示输入 App ID 和 App Secret。
访问控制
私聊
通过 dmPolicy 配置控制谁能私聊机器人：
"pairing"— 未知用户会收到配对码；通过 CLI 批准"allowlist"— 仅allowFrom中的用户可以聊天"open"— 允许所有用户（默认）"disabled"— 禁用所有私聊
批准配对请求：
bash
openclaw pairing list yuanbao
openclaw pairing approve yuanbao <CODE>群聊
@ 提及要求（channels.yuanbao.requireMention）：
true— 要求 @ 提及机器人（默认）false— 无需 @ 提及即可回复
在群聊中回复机器人的消息被视为隐式 @ 提及。
配置示例
基础设置：开放私聊
json5
{
channels: {
yuanbao: {
appKey: "your_app_key",
appSecret: "your_app_secret",
dm: {
policy: "open",
},
},
},
}限制私聊到特定用户
json5
{
channels: {
yuanbao: {
appKey: "your_app_key",
appSecret: "your_app_secret",
dm: {
policy: "allowlist",
allowFrom: ["user_id_1", "user_id_2"],
},
},
},
}禁用群聊 @ 提及要求
json5
{
channels: {
yuanbao: {
requireMention: false,
},
},
}优化出站消息投递
json5
{
channels: {
yuanbao: {
// 立即发送每个块，不缓冲
outboundQueueStrategy: "immediate",
},
},
}调整文本合并策略
json5
{
channels: {
yuanbao: {
outboundQueueStrategy: "merge-text",
minChars: 2800, // 缓冲到此字符数才发送
maxChars: 3000, // 超出此限制强制拆分
idleMs: 5000, // 空闲超时后自动刷新（毫秒）
},
},
}常用命令
| 命令 | 描述 |
|---|---|
/help | 显示可用命令 |
/status | 显示机器人状态 |
/new | 开始新会话 |
/stop | 停止当前运行 |
/restart | 重启 OpenClaw |
/compact | 压缩会话上下文 |
元宝支持原生斜杠命令菜单。网关启动时，命令会自动同步到平台。
故障排除
机器人在群聊中不回应
- 确保机器人已添加到群聊
- 确保 @ 提及了机器人（默认要求）
- 检查日志：
openclaw logs --follow
机器人收不到消息
- 确保机器人在元宝应用中已创建并获批
- 确保
appKey和appSecret配置正确 - 确保网关正在运行：
openclaw gateway status - 检查日志：
openclaw logs --follow
机器人发送空回复或回退回复
- 检查 AI 模型是否返回了有效内容
- 默认回退回复为："暂时无法解答，你可以换个问题问问我哦"
- 可通过
channels.yuanbao.fallbackReply自定义
App Secret 泄露
- 在元宝应用中重置 App Secret
- 更新配置文件中的值
- 重启网关：
openclaw gateway restart
高级配置
多账号
json5
{
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— 媒体上传/下载限制（默认：20MB）overflowPolicy— 消息超限时的处理行为："split"（默认）或"stop"
流式输出
元宝支持块级流式输出。启用后，机器人会在生成过程中分块发送文本。
json5
{
channels: {
yuanbao: {
disableBlockStreaming: false, // 块流式输出启用（默认）
},
},
}设置 disableBlockStreaming: true 可将完整回复一次性发送。
群聊历史上下文
控制群聊中包含多少条历史消息到 AI 上下文中：
json5
{
channels: {
yuanbao: {
historyLimit: 100, // 默认：100，设为 0 禁用
},
},
}回复引用模式
控制机器人在群聊中回复时如何引用消息：
json5
{
channels: {
yuanbao: {
replyToMode: "first", // "off" | "first" | "all"（默认："first"）
},
},
}| 值 | 行为 |
|---|---|
"off" | 不引用回复 |
"first" | 只引用每个入站消息的第一条回复（默认） |
"all" | 引用所有回复 |
Markdown 提示注入
默认情况下，机器人会在系统提示中注入指令，防止 AI 模型将整个回复包裹在 markdown 代码块中。
json5
{
channels: {
yuanbao: {
markdownHintEnabled: true, // 默认：true
},
},
}调试模式
为特定的机器人 ID 启用未脱敏的日志输出：
json5
{
channels: {
yuanbao: {
debugBotIds: ["bot_user_id_1", "bot_user_id_2"],
},
},
}多智能体路由
使用 bindings 将元宝的私聊或群聊路由到不同的智能体。
json5
{
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 或群组代码
配置参考
完整配置：网关配置
| 设置 | 描述 | 默认值 |
|---|---|---|
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 | 预签名令牌（跳过自动票据签名） | - |
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 | AI 无返回内容时的回退回复 | 暂时无法解答，你可以换个问题问问我哦 |
channels.yuanbao.markdownHintEnabled | 注入 Markdown 防包裹指令 | true |
channels.yuanbao.debugBotIds | 调试白名单机器人 ID（未脱敏日志） | [] |
支持的消息类型
接收
- ✅ 文本
- ✅ 图片
- ✅ 文件
- ✅ 音频 / 语音
- ✅ 视频
- ✅ 贴纸 / 自定义表情
- ✅ 自定义元素（链接卡片等）
发送
- ✅ 文本（支持 Markdown）
- ✅ 图片
- ✅ 文件
- ✅ 音频
- ✅ 视频
- ✅ 贴纸
线程与回复
- ✅ 引用回复（通过
replyToMode配置） - ❌ 线程回复（平台不支持）
常见问题
怎么获取元宝机器人的 appKey 和 appSecret？
在腾讯元宝开发者后台创建机器人后，在应用设置中可以找到 App ID（即 appKey）和 App Secret（即 appSecret）。将它们以冒号分隔的形式作为 --token 参数值使用。
机器人在群聊里不回复，也没有报错，为什么？
最常见的原因是群聊默认要求 @ 提及机器人。检查 channels.yuanbao.requireMention 是否设为 true（默认值）。如果不需要 @ 提及，可设为 false。同时确认机器人已添加到群聊中。
OpenClaw 元宝通道支持多长的消息？超长了怎么办？
单消息最大字符数默认为 3000（由 maxChars 控制）。当消息超出限制时，默认行为是自动拆分为多条消息发送（overflowPolicy: "split"）。你也可以改为 "stop" 来阻止发送超长消息。媒体文件大小限制为 20MB。