一、前置准备

1. 获取Bot凭证：在元宝APP内创建自定义机器人，获取以下3个信息：

   • app_id：机器人唯一标识
   • app_secret：机器人密钥
   • 无需配置公网Webhook地址！元宝Bot采用主动WebSocket长连接模式，不需要对外暴露HTTP回调接口

2. 环境要求：

   • 服务器能正常访问外网（能连接腾讯元宝WebSocket服务器 wss://bot-wss.yuanbao.tencent.com）
   • 已经部署好Hermes Agent服务，版本支持yuanbao平台适配器
   • 已启用yuanbao工具集（默认已内置支持）

二、核心配置步骤

步骤1：写入Bot基础配置

执行以下命令写入AppID和AppSecret到Hermes配置：

/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.enabled true
/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.extra.app_id "你的AppID"
/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.extra.app_secret "你的AppSecret"

步骤2：配置消息响应策略

根据使用场景选择群聊策略：

方案A（推荐自用/开放使用）：开放所有群响应

所有拉Bot进去的派（群）都能@Bot响应，不需要额外加白名单：

/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.extra.group_policy open

方案B（推荐商用/多群场景）：白名单模式

只有指定群可以响应Bot，更安全：

/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.extra.group_policy allowlist
/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.extra.group_allow_from '["群code1","群code2"]'

步骤3：配置全局权限放行（必加，否则会被认证层拦截）

在Hermes配置文件/opt/data/config.yaml的顶层或者环境变量中添加以下两个配置：

# 元宝通道放行所有用户消息
YUANBAO_ALLOW_ALL_USERS: true
# 全局网关层兜底放行所有用户请求，避免SSO/登录认证拦截
GATEWAY_ALLOW_ALL_USERS: true

步骤4：（可选）设置默认消息通道

如果需要把定时任务、告警通知默认推送到你的私聊，可以设置Home频道：

/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.home_channel "direct:你的账号ID"

三、启动&验证

1. 重启Hermes网关生效配置

# 杀掉旧网关进程
pkill -f "hermes gateway run"
# 后台启动新网关
nohup /opt/hermes/.venv/bin/hermes gateway run --replace > /opt/data/logs/gateways/default/current 2>&1 &

2. 验证连接状态

等待10秒后执行以下命令，没有报错且显示connected: true即WebSocket连接成功：

/opt/hermes/.venv/bin/hermes status

3. 功能验证

四、常用功能配置

1. 开启/关闭未@消息观察（可选）

如果需要Bot观察群里所有聊天内容（不需要@也会读取上下文），添加配置：

/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.extra.observe_unmentioned_group_messages true

默认关闭，避免被群消息刷屏消耗token。

2. 配置DM权限

如果需要限制私聊用户范围，修改DM策略：

# 仅白名单用户可以私聊
/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.extra.dm_policy allowlist
/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.extra.dm_allow_from '["用户ID1","用户ID2"]'

3. 媒体大小限制

默认支持最大50MB文件发送，可自行调整：

/opt/hermes/.venv/bin/hermes config set platforms.yuanbao.extra.media_max_size_mb 100

五、已支持全部功能清单

✅ 私聊/群聊文本消息收发，自动长消息拆分、Markdown格式支持
✅ 图片、PDF、Word、压缩包等所有格式文件/附件发送
✅ 元宝原生贴纸（TIMFaceElem）发送，不是伪造图片
✅ 群成员查询、精准@群成员功能
✅ 群成员私信发送（支持带附件）
✅ 群信息查询（群名称、群主、成员数）
✅ 定时任务、自动推送、告警通知全场景支持
✅ 回复消息引用、慢响应自动提示等原生体验

六、运维说明

1. 日志路径：/opt/data/logs/gateways/default/current，排查问题直接查看该日志
2. 重启命令：修改配置后执行pkill -f "hermes gateway run"，网关会自动被进程守护拉起
3. WebSocket断线自动重连：内置指数退避重连机制，网络波动恢复后会自动重连，不需要手动干预
4. 消息去重：内置300秒消息去重，网络重连时不会重复处理消息