元宝

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

:::info 元宝是一个企业消息平台，主要在腾讯内部和企业环境中使用。它使用 WebSocket 进行实时通信，基于 HMAC 的认证，并支持包括图片、文件和语音消息在内的富媒体。 :::

前提条件

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

安装所需的依赖：

pip install websockets httpx aiofiles

设置

1. 在元宝中创建机器人

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

2. 运行设置向导

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

hermes gateway setup

按提示选择 元宝。向导将：

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

:::tip 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 通知"
 
# 可选：限制访问（旧版，有关细粒度策略请参见下面的访问控制）
YUANBAO_ALLOWED_USERS=user_account_1,user_account_2

4. 启动网关

hermes gateway

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

功能

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

配置选项

聊天 ID 格式

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

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

媒体上传

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

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

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

家聊

在任何元宝聊天（私聊或群聊）中使用 /sethome 命令将其指定为家聊。定时任务（cron jobs）将其结果投递到此频道。

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

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

YUANBAO_HOME_CHANNEL=direct:user_account_id
# 或对于群：
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="我的机器人更新"

示例：设置家聊

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

示例：定时任务投递

创建定时任务：

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

计划输出将于每天上午 9 点投递到您的元宝家聊。

使用技巧

开始对话

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

hello

机器人在同一对话线程中响应。

可用命令

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

命令	描述
/new	开始新对话
/model [provider:model]	显示或更改模型
/sethome	将此聊天设置为家聊
/status	显示会话信息
/help	显示可用命令

发送文件

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

您也可以附带消息：

请分析此文档

接收文件

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

故障排查

机器人在线但不响应消息

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

解决方法：

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

”连接被拒绝”错误

原因：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	最大重连尝试次数
重连退避	1秒 → 60秒（指数）	重连尝试之间的等待时间
回复心跳间隔	2 秒	RUNNING 状态发送频率
发送超时	30 秒	出站 WS 消息的超时时间

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

详细日志

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

HERMES_LOG_LEVEL=debug hermes gateway

与其他功能的集成

定时任务

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

/cron "0 */4 * * *" 报告系统健康状态

结果投递到您的家聊。

后台任务

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

/background 分析归档中的所有文件

跨平台消息

从 CLI 向元宝发送消息：

hermes chat -q "向 yuanbao:group:group_code 发送 '来自 CLI 的问候'"

相关文档

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