跳到主要内容

元宝（Yuanbao）

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

信息

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

前置条件​

  • 具有机器人创建权限的元宝账号
  • 元宝 APP_ID 和 APP_SECRET（由平台管理员提供）
  • Python 包：websockets 和 httpx
  • 媒体支持：aiofiles

安装所需依赖：

pip install websockets httpx aiofiles

配置​

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

  1. 从 https://yuanbao.tencent.com/ 下载元宝 App
  2. 在 App 中，进入 PAI → 我的机器人，创建新机器人
  3. 机器人创建后，复制 APP_ID 和 APP_SECRET

2. 运行配置向导​

配置元宝最简便的方式是使用交互式配置：

hermes gateway setup

出现提示时选择元宝。向导将：

  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

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

功能特性​

  • WebSocket 网关 —— 实时双向通信
  • HMAC 认证 —— 使用 APP_ID/APP_SECRET 进行安全请求签名
  • C2C 消息 —— 用户与机器人的私聊
  • 群聊消息 —— 群组中的对话
  • 媒体支持 —— 通过 COS（云对象存储）支持图片、文件和语音消息
  • Markdown 格式化 —— 消息根据元宝的大小限制自动分块
  • 消息去重 —— 防止重复处理同一消息
  • 心跳/保活 —— 维持 WebSocket 连接稳定
  • 输入状态指示 —— Agent 处理时显示"正在输入..."状态
  • 自动重连 —— 以指数退避方式处理 WebSocket 断连
  • 群组信息查询 —— 获取群组详情和成员列表
  • 贴纸/表情支持 —— 在对话中发送 TIMFaceElem 贴纸和表情
  • 自动设置主频道 —— 第一个向机器人发消息的用户自动设为主频道归属者
  • 慢响应通知 —— Agent 处理时间较长时发送等待提示消息

配置选项​

聊天 ID 格式​

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

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

媒体上传​

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

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

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

主频道​

在任意元宝聊天（私聊或群聊）中使用 /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. 在元宝中与机器人开始对话
  2. 发送命令：/sethome
  3. 机器人回复："Home channel set to [chat_name] with ID [chat_id]. Cron jobs will deliver to this location."
  4. 之后的定时任务和通知将发送到此频道

示例：定时任务投递​

创建定时任务：

/cron "0 9 * * *" Check server status

定时输出将每天上午 9 点投递到您的元宝主频道。

使用提示​

开始对话​

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

hello

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

可用命令​

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

命令说明
/new开始新对话
/model [provider:model]显示或切换模型
/sethome将此聊天设为主频道
/status显示会话信息
/help显示可用命令

发送文件​

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

也可以同时附上消息：

Please analyze this document

接收文件​

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

故障排查​

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

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

解决方案：

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

"Connection refused" 错误​

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

解决方案：

  1. 验证 WebSocket URL 格式（应以 wss:// 开头）
  2. 检查到元宝 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. 确保到元宝 API 的网络连接稳定
  4. 考虑启用详细日志：HERMES_LOG_LEVEL=debug

访问控制​

元宝支持对私聊和群聊的细粒度访问控制：

# 私聊策略：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: ""

高级配置​

消息分块​

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

连接参数​

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

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

这些值目前不可通过环境变量配置。它们针对典型的元宝部署场景进行了优化。

详细日志​

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

HERMES_LOG_LEVEL=debug hermes gateway

与其他功能集成​

定时任务​

安排在元宝上运行的任务：

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

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

后台任务​

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

/background Analyze all files in the archive

跨平台消息​

从 CLI 向元宝发送消息：

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

相关文档​