hermes教程-Yuanbao

将 Hermes 连接到 Yuanbao，腾讯的企业级消息平台。该适配器使用 WebSocket 网关实现实时消息投递，并支持直聊（C2C）和群聊两种会话模式。

信息

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

前置条件

• 拥有一个具备机器人创建权限的 Yuanbao 账号
• 获取 Yuanbao 的 APP_ID 和 APP_SECRET（向平台管理员申请）
• Python 包：websockets 和 httpx
• 如需支持媒体功能：aiofiles

安装所需依赖：

pip install websockets httpx aiofiles

设置

1. 在 Yuanbao 中创建机器人

1. 从 https://yuanbao.tencent.com/ 下载 Yuanbao 应用
2. 在应用中进入 PAI → 我的机器人，创建一个新机器人
3. 创建完成后，复制 APP_ID 和 APP_SECRET

2. 运行设置向导

配置 Yuanbao 最简单的方式是通过交互式设置：

hermes gateway setup

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

1. 询问你的 APP_ID
2. 询问你的 APP_SECRET
3. 自动保存配置

提示

WebSocket URL 和 API 域名已内置合理的默认值。你只需提供 APP_ID 和 APP_SECRET 即可开始使用。

3. 配置环境变量

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

## 必填
YUANBAO_APP_ID=your-app-id
YUANBAO_APP_SECRET=your-app-secret
YUANBAO_WS_URL=wss://api.yuanbao.example.com/ws
YUANBAO_API_DOMAIN=https://api.yuanbao.example.com
## 可选：机器人账号 ID（通常通过 sign-token 自动获取）
## YUANBAO_BOT_ID=your-bot-id
## 可选：内部路由环境（例如 test/staging/production）
## YUANBAO_ROUTE_ENV=production
## 可选：定时任务/通知的主频道（格式：direct:<account> 或 group:<group_code>）
YUANBAO_HOME_CHANNEL=direct:bot_account_id
YUANBAO_HOME_CHANNEL_NAME="Bot Notifications"
## 可选：限制访问（旧方式，详见下方访问控制以获取更精细的策略）
YUANBAO_ALLOWED_USERS=user_account_1,user_account_2

4. 启动网关

hermes gateway

适配器将连接到 Yuanbao WebSocket 网关，通过 HMAC 签名进行身份验证，并开始处理消息。

功能特性

• WebSocket 网关 — 实时双向通信
• HMAC 认证 — 使用 APP_ID/APP_SECRET 进行安全请求签名
• C2C 消息 — 用户与机器人之间的直接对话
• 群组消息 — 群聊中的对话
• 媒体支持 — 通过 COS（对象存储）支持图片、文件和语音消息
• Markdown 格式化 — 消息自动分块以适应 Yuanbao 的大小限制
• 消息去重 — 防止同一条消息被重复处理
• 心跳/保活 — 维持 WebSocket 连接稳定
• 输入状态指示 — 在智能体处理时显示“正在输入…”状态
• 自动重连 — 处理 WebSocket 断开，采用指数退避策略
• 群组信息查询 — 获取群组详情和成员列表
• 贴纸/表情支持 — 在对话中发送 TIMFaceElem 贴纸和表情
• 自动设置主频道 — 第一个向机器人发送消息的用户自动被设为主频道所有者
• 慢响应通知 — 当智能体处理时间超过预期时，发送等待消息

配置选项

聊天 ID 格式

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

媒体上传

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

• 图片：支持 JPEG、PNG、GIF、WebP
• 文件：支持所有常见文档类型
• 语音：支持 WAV、MP3、OGG

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

主频道

在任何 Yuanbao 聊天（私聊或群聊）中使用 /sethome 命令，将其设为主频道。定时任务（cron 作业）的结果将投递到此频道。

提示 — 自动设置主频道

如果未配置主频道，第一个向机器人发送消息的用户将被自动设为主频道所有者。如果当前主频道是群聊，第一条私聊消息会将其升级为直聊频道。

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

YUANBAO_HOME_CHANNEL=direct:user_account_id
## 或对于群聊：
## YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"

示例：设置主频道

1. 在 Yuanbao 中与机器人开始对话
2. 发送命令：/sethome
3. 机器人回复：“主频道已设置为 [聊天名称]，ID 为 [聊天 ID]。定时任务将投递到此位置。”
4. 未来的定时任务和通知将发送到此频道

示例：定时任务投递

创建一个定时任务：

/cron "0 9 * * *" 检查服务器状态

定时输出将在每天上午 9 点投递到你的 Yuanbao 主频道。

使用技巧

开始对话

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

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

可用命令

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

发送文件

要向机器人发送文件，直接在 Yuanbao 聊天中附加文件即可。机器人会自动下载并处理文件附件。

你也可以在附件中包含一条消息：

接收文件

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

故障排除

机器人在线但不响应消息

原因：WebSocket 握手时认证失败。

解决方法：

1. 确认 APP_ID 和 APP_SECRET 正确
2. 检查 WebSocket URL 是否可访问
3. 确保机器人账号具有适当权限
4. 查看网关日志：tail -f ~/.hermes/logs/gateway.log

“连接被拒绝”错误

原因：WebSocket URL 不可达或错误。

解决方法：

1. 确认 WebSocket URL 格式正确（应以 wss:// 开头）
2. 检查到 Yuanbao API 域名的网络连通性
3. 确认防火墙允许 WebSocket 连接
4. 使用以下命令测试 URL：curl -I https://[YUANBAO_API_DOMAIN]

媒体上传失败

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

解决方法：

1. 确认 API_DOMAIN 正确
2. 检查是否为机器人启用了媒体上传权限
3. 确保媒体文件可访问且未损坏
4. 向平台管理员检查 COS 存储桶配置

消息未投递到主频道

原因：主频道 ID 格式错误或定时任务尚未触发。

解决方法：

1. 确认 YUANBAO_HOME_CHANNEL 格式正确
2. 使用 /sethome 命令自动检测正确格式
3. 使用 /status 检查定时任务计划
4. 确认机器人在目标聊天中具有发送权限

频繁断开连接

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

解决方法：

1. 检查网关日志中的错误模式
2. 增加连接设置中的心跳超时时间
3. 确保到 Yuanbao API 的网络连接稳定
4. 考虑启用详细日志：HERMES_LOG_LEVEL=debug

访问控制

Yuanbao 支持对私聊和群聊进行精细的访问控制：

## 私聊策略：open（默认）| allowlist | disabled
YUANBAO_DM_POLICY=open
## 允许向机器人发送私聊的用户 ID 列表（仅在 DM_POLICY=allowlist 时使用）
YUANBAO_DM_ALLOW_FROM=user_id_1,user_id_2
## 群聊策略：open（默认）| allowlist | disabled
YUANBAO_GROUP_POLICY=open
## 允许的群组代码列表（仅在 GROUP_POLICY=allowlist 时使用）
YUANBAO_GROUP_ALLOW_FROM=group_code_1,group_code_2

这些也可以在 config.yaml 中设置：

platforms:
  yuanbao:
    extra:
      dm_policy: allowlist
      dm_allow_from: "user1,user2"
      group_policy: open
      group_allow_from: ""

高级配置

消息分块

Yuanbao 有最大消息大小限制。Hermes 会自动对大型响应进行分块，并考虑 Markdown 格式（尊重代码块、表格和段落边界）。

连接参数

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

注意

这些值目前无法通过环境变量配置。它们针对典型的 Yuanbao 部署进行了优化。

详细日志

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

HERMES_LOG_LEVEL=debug hermes gateway

与其他功能的集成

定时任务

在 Yuanbao 上安排任务：

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

后台任务

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

跨平台消息

从 CLI 向 Yuanbao 发送消息：

hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"

相关文档

• 消息网关概述
• 斜杠命令参考
• 定时任务
• 后台会话