AI Insights 网站头像
AI Insights

追踪 AI 趋势，分享 AI 工具

Agent

Hermes Agent 实战: Telegram/飞书/企业微信全平台 AI 助手搭建

Hermes Agent 实战教程，通过一个进程同时接入 Telegram、飞书和企业微信三大平台，掌握全平台 AI 助手搭建核心配置。

2026/04/01 8 分钟阅读
toolAI助手HermesTelegram飞书企业微信

难度：中等 · 时长：约 20 分钟 · 收获：掌握 Hermes 全平台接入核心配置

你有没有想过——同一个 AI 助手，同时跑在 Telegram、飞书和企业微信里，而且只部署一次？Hermes Agent 就能做到。

它是 Nous Research 开源的自学进化型 AI Agent，最大的亮点之一就是内置了一个全平台消息网关。你只需要在服务器上启动一个进程，就能同时接入 Telegram、Discord、Slack、飞书、企业微信、Signal、WhatsApp 等 10+ 消息平台。消息自动路由，记忆跨平台共享，配置一次，永久生效。

今天这篇文章，我们一起来把三个最常用的平台——Telegram、飞书（ Lark）、企业微信——全部接起来。

目标读者

本文适合以下开发者：

  • 有一定 Linux / 命令行基础，想在服务器上自托管 AI Agent
  • 对多平台消息接入有需求的独立开发者或小型团队
  • 正在评估 Hermes Agent 作为 OpenClaw 替代方案的团队

[!TIP] 如果你还没有 LLM API Key，推荐从 Defapi 获取。Defapi 上的 Claude Opus 4.6 输入 $2.5 / 输出 $12.5 每百万 Token，只有官方价格的一半，性价比极高。具体支持的接口协议见 Defapi Claude 文档。

核心依赖与环境

依赖说明
Python3.11+安装脚本自动处理
操作系统Linux (Ubuntu 22.04+)、macOS 或 WSL2
消息平台账号Telegram Bot Token / 飞书企业自建应用 / 企业微信
LLM API Key推荐 Defapi（Claude Opus 4.6 半价）
Docker可选，v0.6.0 已官方支持容器部署

[!WARNING] Windows 原生不支持，请安装 WSL2 后在 WSL2 终端内操作。

完整项目结构

hermes-agent/
├── scripts/
│   └── install.sh    # 一键安装脚本
└── ~/.hermes/        # 主配置目录（安装后自动生成）
    ├── config.yaml   # 核心配置（模型、工具集）
    ├── .env          # API Keys（不提交到 Git！）
    ├── skills/       # 技能目录
    ├── memory/       # 持久化记忆
    ├── sessions/     # 会话历史（FTS5 全文检索）
    └── gateway/      # 网关配置（各平台独立 YAML）
        ├── telegram.yaml
        ├── feishu.yaml
        └── wecom.yaml

手把手步骤

步骤 1：一键安装 Hermes Agent

Linux / macOS / WSL2 下，执行官方安装脚本：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装脚本会自动处理 Python、Node.js 和所有依赖项，全程无需手动干预。安装完成后重载 shell：

source ~/.bashrc  # bash 用户
source ~/.zshrc   # zsh 用户

验证安装成功：

hermes doctor

步骤 2：配置 LLM Provider——对接 Defapi

接下来要告诉 Hermes 去哪里找大模型。我们在 .env 文件里写入 API Key：

hermes config set ANTHROPIC_API_KEY <your-defapi-key>

Defapi 兼容 Anthropic 的 v1/messages 接口协议，Hermes 可以直接对接。你也可以通过 hermes model 命令交互式选择模型和 Provider：

hermes model
# 交互选择：
# 1. Nous Portal
# 2. OpenRouter (200+ 模型)
# 3. OpenAI
# 4. Defapi / 自定义端点
# 5. 其他...

如果用 Defapi，在交互菜单里选自定义端点（Custom），填入：

API Endpoint: https://api.defapi.org
Model: anthropic/claude-opus-4.6

步骤 3：接入第一个平台——Telegram Bot

这是最容易验证的一个平台，因为 Telegram 的 Bot API 是公开的，无需企业认证。

3.1 创建 Bot

在 Telegram 里找 @BotFather，发送 /newbot，按提示命名 Bot 并获取 BOT_TOKEN，格式类似 123456789:ABCdefGHIjklMNOpqrsTUVwxyz。

3.2 配置 Hermes 网关

hermes gateway setup
# 选择 telegram，进入交互配置

或者手动创建 ~/.hermes/gateway/telegram.yaml：

platform: telegram
enabled: true
bot_token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

# 访问控制：只允许特定用户
allowed_users:
  - your_telegram_username

# 安全设置
require_approval_for_dangerous_tools: true

3.3 验证

启动网关后，给 Bot 发一条消息：

hermes gateway start
# 或者后台运行：
hermes gateway start --daemon

在 Telegram 里给 Bot 发 /new，Bot 应该回复欢迎消息。发一条中文消息试试，比如”你好”，看看 AI 是否有响应。

[!TIP] 如果 Bot 没有响应，检查：hermes gateway status 查看运行状态，hermes logs 查看最新日志。常见原因是 Bot Token 填错或者端口被占用。

步骤 4：接入飞书（Lark）企业应用

飞书接入稍微复杂一点，需要在飞书开放平台创建一个企业自建应用。

4.1 在飞书开放平台创建应用

  • 打开 飞书开放平台，创建一个企业自建应用
  • 在「凭证与基础信息」里获取 App ID 和 App Secret
  • 开启「机器人」能力

4.2 配置事件订阅

在应用的「事件订阅」中：

  • 请求地址 URL 填：https://你的域名/gateway/feishu/webhook
  • 事件选择：im.message.receive_v1（接收消息）

[!WARNING] 飞书要求回调 URL 必须是公网可访问的 HTTPS 地址。如果你的服务器没有公网域名，可以用 ngrok 做临时内网穿透：ngrok http 8080，将生成的 HTTPS 地址填入飞书。

4.3 安装应用到企业

在「版本管理与发布」中创建版本并发布，否则 Bot 无法接收消息。

4.4 配置 Hermes 网关

hermes gateway setup
# 选择 feishu，交互填入 App ID 和 App Secret

手动编辑 ~/.hermes/gateway/feishu.yaml：

platform: feishu
enabled: true
app_id: "cli_xxxxxxxxxxxxxx"
app_secret: "xxxxxxxxxxxxxxxxxxxx"
verification_token: "your_verification_token"

# 消息加密（可选但推荐）
encrypt_key: "your_encrypt_key"

# 允许的群组和用户
allowed_chats: []
require_mention: false

4.5 验证

在飞书里给 Bot 发消息 /new，看是否有响应。飞书的消息格式和 Telegram 不同，Bot 支持富文本消息卡片，Hermes 会自动适配。

步骤 5：接入企业微信（WeCom）

企业微信的接入方式和飞书类似，也是走回调 Webhook 模式。

5.1 在企业微信管理后台创建应用

  • 登录 企业微信管理后台
  • 进入「应用管理」→「创建应用」→ 选择「企业自建」
  • 获取 AgentId、Secret、和企业 CorpId
  • 设置「企业可信IP」为你的服务器 IP

5.2 配置接收消息

在应用设置中开启「接收消息」模式：

  • 填写 URL：https://你的域名/gateway/wecom/webhook
  • 选择「兼容模式」或「事件模式」

5.3 配置 Hermes 网关

# ~/.hermes/gateway/wecom.yaml
platform: wecom
enabled: true
corp_id: "wwxxxxxxxxxxxxxx"
agent_id: "1000001"
corp_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
encrypt_mode: "safe"  # 安全模式需要配置 encoding_aes_key
encoding_aes_key: "your_32_char_aes_key"

5.4 验证

企业微信里找到你的应用，发一条消息测试。

[!TIP] 企业微信对 IP 白名单要求严格。如果部署在云服务器上（如 DigitalOcean、Hetzner），务必在管理后台将服务器公网 IP 加入可信 IP 列表，否则消息会被企业微信直接拒绝。

步骤 6：启动网关，一次跑三个平台

所有平台配置完成后，用一条命令启动网关：

hermes gateway start

Hermes 会自动加载 ~/.hermes/gateway/ 下所有已启用平台的配置，并发启动所有适配器。如果某个平台启动失败（比如 Token 错误），不会影响其他平台的正常运行。

用 hermes gateway status 查看各平台运行状态：

Platform  Status    Users  Messages
telegram  ● online  3      142
feishu    ● online  7      89
wecom     ● online  2      15

用 Ctrl+C 停止网关，或者 --daemon 后台运行：

hermes gateway start --daemon

步骤 7：多平台消息验证

现在你可以在三个平台上分别发消息给 Bot 测试：

# Telegram
/new
你好，介绍一下你自己

# 飞书
/new
你是谁？

# 企业微信
/new
有什么我能帮你的？

三端响应完全一致，记忆共享——你在 Telegram 里说过的事情，飞书和企业微信都知道。这才是 Hermes 最核心的价值：一次配置，全平台统一体验。

[!TIP] 如果你想让每个平台跑不同的 Agent 实例（不同的模型、不同的技能集），可以使用 Hermes v0.6.0 新增的 Profiles 功能：hermes -p telegram profile create，然后在不同 profile 下配置不同的模型和平台。Profile 之间完全隔离，互不影响。

常见问题排查

1. Telegram Bot 收不到消息

症状：Bot 完全不响应，查看日志也没有任何记录。

排查步骤：

# 1. 确认 Token 正确
hermes config get telegram.bot_token

# 2. 确认端口没有被占用
ss -tlnp | grep 8080

# 3. 如果用了 webhook 模式，检查 Telegram Bot API 配置
# Webhook URL 必须在公网可访问，本地开发用 ngrok 穿透
ngrok http 8080

# 4. 重置 webhook（有时候 Bot 卡在旧的 webhook 上）
curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook"

2. 飞书回调验证失败

症状：飞书开放平台显示「回调 URL 校验失败」。

排查步骤：

# 1. 确认公网 URL 可访问
curl -X GET "https://your-domain.com/gateway/feishu/webhook"

# 2. 检查飞书签名验证
# 飞书使用 AES 加密消息，encrypt_key 必须和后台配置一致
# 查看 Hermes 日志：
hermes logs --platform feishu

[!WARNING] 飞书的加密模式（encrypt_mode）必须和后台设置匹配。如果你在后台选了「安全模式」，Hermes 配置里也必须填 encrypt_mode: safe 和对应的 encoding_aes_key。

3. 企业微信消息无响应

症状：消息发出去没有任何回复，日志里也没有记录。

排查步骤：

# 1. 确认 CorpId / AgentId / Secret 填写正确

# 2. 最重要的：检查 IP 白名单
# 企业微信要求调用 API 的服务器 IP 在可信 IP 列表内

# 3. 获取 AccessToken 测试
curl "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=wwxxx&corpsecret=secret"

# 如果返回 "errmsg": "ip not in whitelist"，说明 IP 没有加白

4. 模型不响应

症状：消息被 Bot 收到了，但 AI 不回复，一直显示 thinking。

排查步骤：

# 1. 测试 API Key 是否有效
curl -X POST "https://api.defapi.org/api/v1/messages" \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-opus-4.6","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

# 2. 检查模型配置
hermes config get model

# 3. 检查 fallback_providers（推荐配置）
# 在 ~/.hermes/config.yaml 里添加备用 Provider：
fallback_providers:
  - provider: openrouter
    api_key: "${OPENROUTER_API_KEY}"

[!TIP] 推荐在 Defapi 之外至少配置一个备用 Provider。Hermes v0.6.0 支持 fallback_providers 链式调用——当主 Provider 超时或返回错误时，自动切换到备用 Provider，保证 Agent 不掉线。

5. 工具执行报错

症状：Bot 回复说无法执行某个操作。

排查步骤：

# 1. 查看当前启用的工具集
hermes tools

# 2. 启用需要的工具集
hermes tools enable web_search
hermes tools enable terminal

# 3. 危险命令需要人工确认
hermes config get approval_required
# 设置为 true 会让所有危险命令需要你手动审批

6. 多平台并发冲突

症状：某个平台收到消息后其他平台也没响应了。

# 确认只有一个 Hermes 网关实例在运行
ps aux | grep hermes
pkill -f hermes-agent

# 然后重新启动
hermes gateway start

[!TIP] 用 Profiles 功能可以让每个平台跑完全独立的 Hermes 实例：每个 profile 有自己的配置目录、记忆和会话，不同 profile 之间完全隔离，适合团队里不同成员各自使用自己的 Bot。

扩展阅读 / 进阶方向

从 OpenClaw 迁移

如果你已经在用 OpenClaw，Hermes 提供了官方迁移工具，能自动导入 SOUL.md、MEMORY.md、Skills、API Keys 和消息平台配置：

hermes claw migrate        # 交互式完整迁移
hermes claw migrate --dry-run  # 先预览
hermes claw migrate --preset user-data  # 不迁移敏感信息

MCP Server 模式

Hermes v0.6.0 新增了 MCP Server 能力，可以用一条命令让 Hermes 对外暴露工具：

hermes mcp serve
# 支持 stdio 和 Streamable HTTP 两种传输协议

连接后，Cursor、VS Code、Zed 等 IDE 就能通过 MCP 协议调用 Hermes 的所有工具和对话能力。

自定义技能系统

Hermes 的 Skills 系统支持从自然语言描述自动创建技能。也可以手动写：

# 查看已有技能
hermes skills

# 浏览 Skills Hub（社区技能市场）
/skills

# 从 agentskills.io 安装社区技能

Cron 定时任务

用自然语言设置定时任务，Hermes 自动执行并推送结果到任意平台：

# 每天早上 8 点推送天气报告到 Telegram
/cron "Every day at 8am, summarize today's weather and send to me" --platform telegram

结语

Hermes Agent 的全平台网关设计得非常优雅——你只需要维护一份配置，就能让同一个 Agent 实例跑在任意多个消息平台上。记忆跨平台共享，配置一次搞定，资源占用也比跑多个独立 Bot 低得多。

如果你还在用 OpenClaw，或者正在找一款真正能打的开源 AI Agent，Hermes 值得你花 20 分钟试试。配合 Defapi 的半价 Claude Opus 4.6，每月成本可以压缩到原来的 50%，体验却一点不打折。