集成聊天平台

教程概述

本教程展示如何把 Hermes Agent 集成到主流聊天平台。我们会以 QQ、飞书、钉钉为例，介绍 Webhook 接入、消息适配、权限控制等关键环节，帮助你构建一个团队可用的 AI 助手。

前提条件

开始前请确认满足以下条件

已完成「基础配置」教程
在目标平台拥有管理员权限或开发者账号
了解 Webhook 与 HTTP API 的基本概念
本地或服务器有可被外网访问的地址（如 ngrok）

学习目标

完成本教程后你将能够

理解平台集成的统一架构
完成 QQ 机器人接入
完成飞书 / 钉钉自定义机器人接入
搭建消息中转与权限校验机制

详细步骤

理解集成架构

所有平台集成都遵循同一模式：平台 → Webhook → Hermes Adapter → Agent Core → Adapter → 平台。

text

[Chat Platform]
      │ Webhook
      ▼
[Hermes Adapter] ──> [Agent Core] ──> [LLM]
      ▲                                    │
      └────────────  响应  ─────────────────┘

2
暴露本地服务
开发阶段可使用 ngrok 把本地 3000 端口映射到公网，便于平台回调。
bash
```
npm install -g ngrok
ngrok http 3000
# 复制类似 https://xxxx.ngrok.io 的地址
```
小贴士：生产环境建议直接部署到云服务器，并使用 HTTPS 证书。
3
接入 QQ 机器人
通过 NapCatQQ 或 go-cqhttp 提供 OneBot 协议接口，再在 .env 中配置即可。
bash
```
ADAPTER=onebot
ONEBOT_WS_URL=ws://127.0.0.1:6700
ONEBOT_TOKEN=your-token
```
4
接入飞书自定义机器人
在飞书后台创建机器人应用，获取 App ID 和 Secret，然后填入配置。
bash
```
ADAPTER=feishu
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_VERIFY_TOKEN=xxx
```
注意：请务必校验 verification token，避免接收伪造请求。
5
接入钉钉机器人
钉钉支持 outgoing 机器人模式，配置 Webhook 地址与签名校验密钥即可。
bash
```
ADAPTER=dingtalk
DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=xxx
DINGTALK_SECRET=SEC...
```
6
添加权限与速率控制
在 config/permissions.json 中限制可使用 Agent 的用户、群组与每分钟请求次数。
json
```
{
  "allowedUsers":  ["u_001", "u_002"],
  "allowedGroups": ["g_team_ai"],
  "rateLimitPerMin": 20
}
```

最佳实践

为机器人设置独立账号或租户，避免影响个人/公司主账号
在网关层做速率限制，再到业务层做权限校验，做到双重防护
为高频群聊开启历史消息缓存，让 Agent 拥有更好上下文
记录所有调用日志，方便审计与故障排查

常见问题

Q1.为什么飞书无法收到回复？

请先在事件订阅页面验证回调地址，并确认机器人已加入对应的群聊或会话。

Q2.QQ 机器人频繁被限制？

建议使用官方机器人 API 或者降低消息频率，并避免发送批量重复内容。

Q3.如何同时接入多个平台？

Hermes Agent 支持启动多个 Adapter 实例，使用 ADAPTERS=onebot,feishu 即可。

🎉 教程总结

你已经成功把 Hermes Agent 接入了至少一个聊天平台。接下来可以在「自定义 Skills」教程中，为 Agent 增加查天气、查数据库等能力，让它真正成为团队助手。

教程概述

前提条件

学习目标

详细步骤

理解集成架构

暴露本地服务

接入 QQ 机器人

接入飞书自定义机器人

接入钉钉机器人