Yuanbao

将 Hermes 连接到腾讯企业消息平台元宝（Yuanbao）。该适配器使用 WebSocket gateway 实现实时消息传递，支持单聊（C2C）和群聊两种会话模式。

信息

元宝是一个企业消息平台，主要用于腾讯内部及企业环境。它使用 WebSocket 进行实时通信，采用基于 HMAC 的认证方式，支持图片、文件和语音消息等富媒体内容。

前提条件

拥有机器人创建权限的元宝账号

元宝 APP_ID 和 APP_SECRET（由平台管理员提供）

Python 包：websockets 和 httpx

媒体支持需要：aiofiles

安装所需依赖：

配置

1. 在元宝中创建机器人

从 https://yuanbao.tencent.com/ 下载元宝应用

在应用中进入 PAI → 我的机器人，创建一个新机器人

机器人创建完成后，复制 APP_ID 和 APP_SECRET

2. 运行配置向导

配置元宝最简便的方式是通过交互式向导：

在提示时选择 Yuanbao。向导将：

询问你的 APP_ID

询问你的 APP_SECRET

自动保存配置

提示

WebSocket URL 和 API Domain 均内置了合理的默认值。只需提供 APP_ID 和 APP_SECRET 即可开始使用。

3. 配置环境变量

初始配置完成后，在 ~/.hermes/.env 中验证以下变量：

4. 启动 Gateway

适配器将连接到元宝 WebSocket gateway，使用 HMAC 签名进行认证，并开始处理消息。

功能特性

WebSocket gateway — 实时双向通信

HMAC 认证 — 使用 APP_ID/APP_SECRET 进行安全请求签名

C2C 消息 — 用户与机器人的单聊会话

群聊消息 — 群组聊天中的会话

媒体支持 — 通过 COS（云对象存储）支持图片、文件和语音消息

Markdown 格式化 — 消息自动分块以适应元宝的大小限制

消息去重 — 防止同一消息被重复处理

心跳/保活 — 维持 WebSocket 连接稳定性

输入状态指示 — 在 agent 处理期间显示"正在输入…"状态

自动重连 — 以指数退避方式处理 WebSocket 断线

群组信息查询 — 获取群组详情和成员列表

表情/Emoji 支持 — 在会话中发送 TIMFaceElem 表情和 emoji

自动设置主频道 — 第一个向机器人发消息的用户自动成为主频道所有者

慢响应通知 — 当 agent 处理时间超出预期时发送等待提示

配置选项

聊天 ID 格式

元宝根据会话类型使用带前缀的标识符：

聊天类型	格式	示例
单聊（C2C）	`direct:<account>`	`direct:user123`
群聊	`group:<group_code>`	`group:grp456`

媒体上传

元宝适配器通过 COS（腾讯云对象存储）自动处理媒体上传：

图片：支持 JPEG、PNG、GIF、WebP

文件：支持所有常见文档类型

语音：支持 WAV、MP3、OGG

媒体 URL 在上传前会自动验证并下载，以防止 SSRF 攻击。

主频道

在任意元宝聊天（单聊或群聊）中使用 /sethome 命令，将其指定为主频道。定时任务（cron job）的结果将发送到该频道。

自动设置主频道

如果未配置主频道，第一个向机器人发消息的用户将自动成为主频道所有者。如果当前主频道是群聊，第一条单聊消息将把主频道升级为直接频道。

也可以在 ~/.hermes/.env 中手动设置：

示例：设置主频道

在元宝中与机器人开始对话

发送命令：/sethome

机器人回复："Home channel set to [chat_name] with ID [chat_id]. Cron jobs will deliver to this location."

后续 cron job 和通知将发送到该频道

示例：Cron Job 投递

创建一个 cron job：

定时输出将在每天上午 9 点发送到你的元宝主频道。

使用技巧

开始对话

在元宝中向机器人发送任意消息：

hello

机器人将在同一会话线程中回复。

可用命令

所有标准 Hermes 命令均可在元宝上使用：

命令	描述
`/new`	开始新对话
`/model [provider:model]`	查看或切换模型
`/sethome`	将当前聊天设为主频道
`/status`	显示会话信息
`/help`	显示可用命令

发送文件

在元宝聊天中直接附加文件即可发送给机器人。机器人将自动下载并处理附件。

也可以在附件中附带消息：

Please analyze this document

接收文件

当你要求机器人创建或导出文件时，它会直接将文件发送到你的元宝聊天中。

故障排查

机器人在线但不响应消息

原因：WebSocket 握手期间认证失败。

解决方法：

验证 APP_ID 和 APP_SECRET 是否正确

检查 WebSocket URL 是否可访问

确保机器人账号拥有适当权限

查看 gateway 日志：tail -f ~/.hermes/logs/gateway.log

"Connection refused" 错误

原因：WebSocket URL 不可达或不正确。

解决方法：

验证 WebSocket URL 格式（应以 wss:// 开头）

检查到元宝 API 域名的网络连通性

确认防火墙允许 WebSocket 连接

使用以下命令测试 URL：curl -I https://[YUANBAO_API_DOMAIN]

媒体上传失败

原因：COS 凭证无效或媒体服务器不可达。

解决方法：

验证 API_DOMAIN 是否正确

检查机器人是否已启用媒体上传权限

确保媒体文件可访问且未损坏

联系平台管理员检查 COS bucket 配置

消息未投递到主频道

原因：主频道 ID 格式不正确或 cron job 尚未触发。

解决方法：

验证 YUANBAO_HOME_CHANNEL 格式是否正确

使用 /sethome 命令自动检测正确格式

使用 /status 检查 cron job 计划

验证机器人在目标聊天中是否有发送权限

频繁断线

原因：WebSocket 连接不稳定或网络不可靠。

解决方法：

检查 gateway 日志中的错误模式

在连接设置中增加心跳超时时间

确保到元宝 API 的网络连接稳定

考虑启用详细日志：HERMES_LOG_LEVEL=debug

访问控制

元宝支持对单聊和群聊进行细粒度访问控制：

也可以在 config.yaml 中设置：

高级配置

消息分块

元宝有最大消息大小限制。Hermes 自动对大响应进行分块，采用 Markdown 感知拆分（遵守代码围栏、表格和段落边界）。

连接参数

以下连接参数内置于适配器中，具有合理的默认值：

参数	默认值	描述
WebSocket 连接超时	15 秒	等待 WS 握手的时间
心跳间隔	30 秒	保持连接活跃的 ping 频率
最大重连次数	100	最大重连尝试次数
重连退避	1s → 60s（指数）	重连尝试之间的等待时间
回复心跳间隔	2 秒	RUNNING 状态发送频率
发送超时	30 秒	出站 WS 消息的超时时间

备注

这些值目前无法通过环境变量配置，已针对典型元宝部署场景进行优化。

详细日志

启用 debug 日志以排查连接问题：

与其他功能集成

Cron Job

在元宝上调度定时任务：

/cron "0 */4 * * *" Report system health

结果将投递到你的主频道。

后台任务

在不阻塞会话的情况下运行长时间操作：

/background Analyze all files in the archive

跨平台消息

从 CLI 向元宝发送消息：

"Yuanbao"

Yuanbao

前提条件

配置

1. 在元宝中创建机器人

2. 运行配置向导

3. 配置环境变量

4. 启动 Gateway

功能特性

配置选项

聊天 ID 格式

媒体上传

主频道

示例：设置主频道

示例：Cron Job 投递

使用技巧

开始对话

可用命令

发送文件

接收文件

故障排查

机器人在线但不响应消息

"Connection refused" 错误

媒体上传失败

消息未投递到主频道

频繁断线

访问控制

高级配置

消息分块

连接参数

详细日志

与其他功能集成

Cron Job

后台任务

跨平台消息

相关文档

"Yuanbao"

Yuanbao#

前提条件#

配置#

1. 在元宝中创建机器人#

2. 运行配置向导#

3. 配置环境变量#

4. 启动 Gateway#

功能特性#

配置选项#

聊天 ID 格式#

媒体上传#

主频道#

示例：设置主频道#

示例：Cron Job 投递#

使用技巧#

开始对话#

可用命令#

发送文件#

接收文件#

故障排查#

机器人在线但不响应消息#

"Connection refused" 错误#

媒体上传失败#

消息未投递到主频道#

频繁断线#

访问控制#

高级配置#

消息分块#

连接参数#

详细日志#

与其他功能集成#

Cron Job#

后台任务#

跨平台消息#

相关文档#

Yuanbao

前提条件

配置

1. 在元宝中创建机器人

2. 运行配置向导

3. 配置环境变量

4. 启动 Gateway

功能特性

配置选项

聊天 ID 格式

媒体上传

主频道

示例：设置主频道

示例：Cron Job 投递

使用技巧

开始对话

可用命令

发送文件

接收文件

故障排查

机器人在线但不响应消息

"Connection refused" 错误

媒体上传失败

消息未投递到主频道

频繁断线

访问控制

高级配置

消息分块

连接参数

详细日志

与其他功能集成

Cron Job

后台任务

跨平台消息

相关文档