元宝接入 AI 智能体指南

为什么适合托管实例

元宝走的是 WebSocket 长连接：由机器人主动连到元宝服务器，而不是等对方来访问您。 所以不需要公网 IP、不需要备案域名、也不用做端口映射，托管实例可以直接连上，这一点 比需要回调地址的平台省心不少。

准备工作

• 一个可以创建机器人的元宝开放平台账号。
• 一个已经部署好的 Hermes 实例。
• 机器人的 AppID 和 AppSecret（创建完成后在后台获取）。

第一步：创建机器人

在元宝开放平台创建一个机器人，填好名称、头像和简介。创建完成后记下 AppID 和 AppSecret，其中 AppSecret 通常只完整显示一次，请当场保存。

同时确认一下机器人的可用范围，先只放开自己测试，跑通之后再逐步扩大，避免一上来用量 超出预期。

第二步：配置 Hermes

最省事的方式是直接在机器人自己的控制台里操作：打开 Channels（通道）页面，找到 Yuanbao，点 Configure 填入凭据，打开开关，再点 Test 验证，全程不用改文件。

也可以在实例的网页终端里运行引导式配置：

hermes gateway setup

或者直接写环境变量：

YUANBAO_APP_ID=你的-app-id
YUANBAO_APP_SECRET=你的-app-secret
YUANBAO_WS_URL=wss://元宝提供的长连接地址

WebSocket 地址以元宝开放平台文档给出的为准，不同环境可能不一样，填错的话表现就是 一直连不上。配置完成后重启网关让设置生效。

第三步：测试

在元宝里找到这个机器人发一条消息，正常情况下几秒内会收到回复。如果没有反应，先确认 自己在不在可用范围内，再检查 AppSecret 有没有填错或被重新生成过——这两个是最常见的 原因。

常见问题

• 一直连不上：多半是 WebSocket 地址不对，或者 AppID / AppSecret 有空格、换行混进去了。
• 之前能用突然不回了：AppSecret 被重置过，旧的就失效了，需要把新的重新填进去。
• 只有自己能用，同事不能用：可用范围没有包含对方。
• 回复很慢：和模型选择有关，可以在控制台里换一个更快的模型试试。

需要我们代为配置吗

可以在 控制台 联系客服，我们帮您在实例上配置好。 请不要把 AppSecret 直接发在聊天里，我们会告诉您填在哪里。