快速开始
需要 OpenClaw 2026.4.10 或以上版本。 运行openclaw --version检查版本。使用openclaw update升级。
交互式设置(可选)
你也可以使用交互式向导:访问控制
私信
配置dmPolicy 以控制谁可以私信机器人:
"pairing"- 未知用户会收到配对码;通过 CLI 审批"allowlist"- 只有allowFrom中列出的用户可以聊天"open"- 允许所有用户(默认)"disabled"- 禁用所有私信
群聊
提及要求(channels.yuanbao.requireMention):
true- 需要 @ 提及(默认)false- 无需 @ 提及即可响应
配置示例
使用开放私信策略的基础设置
将私信限制为特定用户
在群聊中禁用 @ 提及要求
优化出站消息投递
调整 merge-text 策略
常用命令
| 命令 | 描述 |
|---|---|
/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 中重置 App Secret
- 更新配置中的值
- 重启网关:
openclaw gateway restart
高级配置
多账号
defaultAccount 控制当出站 API 未指定 accountId 时使用哪个账号。
消息限制
maxChars- 单条消息最大字符数(默认:3000个字符)mediaMaxMb- 媒体上传/下载限制(默认:20MB)overflowPolicy- 消息超出限制时的行为:"split"(默认)或"stop"
流式输出
Yuanbao 支持块级流式输出。启用后,机器人会在生成文本时按分块发送。disableBlockStreaming: true 设为在一条消息中发送完整回复。
群聊历史上下文
控制群聊中有多少历史消息会被包含在 AI 上下文中:回复引用模式
控制机器人在群聊中回复时如何引用消息:| 值 | 行为 |
|---|---|
"off" | 不引用回复 |
"first" | 每条传入消息仅引用第一次回复(默认) |
"all" | 每次回复都引用 |
Markdown 提示注入
默认情况下,机器人会在系统提示中注入指令,以防止 AI 模型将整个回复包裹在 markdown 代码块中。调试模式
为特定机器人 ID 启用未清洗的日志输出:多智能体路由
使用bindings 将 Yuanbao 私信或群聊路由到不同的智能体。
match.channel:"yuanbao"match.peer.kind:"direct"(私信)或"group"(群聊)match.peer.id: 用户 ID 或群号
配置参考
完整配置:网关配置| Setting | Description | Default |
|---|---|---|
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 | AI 无内容返回时的回退回复 | 暂时无法解答,你可以换个问题问问我哦 |
channels.yuanbao.markdownHintEnabled | 注入 markdown 防包裹指令 | true |
channels.yuanbao.debugBotIds | 调试白名单机器人 ID(未清洗日志) | [] |
支持的消息类型
接收
- ✅ 文本
- ✅ 图片
- ✅ 文件
- ✅ 音频 / 语音
- ✅ 视频
- ✅ 表情包 / 自定义 emoji
- ✅ 自定义元素(链接卡片等)
发送
- ✅ 文本(支持 markdown)
- ✅ 图片
- ✅ 文件
- ✅ 音频
- ✅ 视频
- ✅ 表情包
线程和回复
- ✅ 引用回复(可通过
replyToMode配置) - ❌ 线程回复(平台不支持)
相关内容
- Channels Overview - 所有受支持的渠道
- Pairing - 私信认证和配对流程
- Groups - 群聊行为和提及门控
- Channel Routing - 消息会话路由
- Security - 访问模型和加固