Hermes Agent对外接口完整配置指南：Gateway/Webhook/MCP/REST API实战（2026最新）

04510

维护咨询 大模型部署 问题解决 技能定制 大模型训练

站长交流微信: aixbwz

为什么需要对外接口？

Hermes Agent 不只是一个对话助手——它本质上是一个可以 24 小时运行的智能体服务。把它暴露给外部系统，才能真正发挥价值：Telegram 机器人接收用户消息、微信公众平台回调、飞书机器人推送通知、第三方网站调用你的 AI 能力……

本文详细介绍 Hermes Agent 对外暴露接口的几种方式：Gateway 平台接入、Webhook 回调、MCP 服务器暴露、REST API 暴露。

一、Gateway 平台接入（最常用）

Gateway 是 Hermes Agent 连接外部消息平台的核心模块。通过 hermes gateway 命令把 Hermes 接入各个平台，实现「消息进来、AI 处理、回复出去」的全链路。

接入 Telegram

# 第一步：在 BotFather 创建机器人，获取 Token
# 打开 Telegram 搜索 @BotFather
# 发送 /newbot，按提示创建

# 第二步：配置 Token
export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

# 第三步：启动 Gateway
hermes gateway --platform telegram --token $TELEGRAM_BOT_TOKEN

# 或者写入 config.yaml
nano ~/.hermes/config.yaml
# config.yaml 配置示例
platforms:
  telegram:
    bot_token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    allowed_users:
      - 你的Telegram用户ID
    polling_timeout: 30
    max_retries: 3
# 启动服务
hermes gateway --platform telegram

接入 Discord

# 第一步：创建 Discord Application
# https://discord.com/developers/applications

# 第二步：在 Application 下创建 Bot
# 复制 Bot Token

# 第三步：添加 Bot 到服务器
# OAuth2 → URL Generator
# Scopes: bot
# Bot Permissions: 管理员或所需权限

# 第四步：配置
export DISCORD_BOT_TOKEN="MzgxXXXXXXX.XXXXXX.XXXXXXXXXXXXXXXXXXXXXXXX"

hermes gateway --platform discord --token $DISCORD_BOT_TOKEN
# config.yaml
platforms:
  discord:
    bot_token: "MzgxXXXXXXX.XXXXXX.XXXXXXXXXXXXXXXXXXXXXXXX"
    allowed_guilds:
      - 你的服务器ID
    allowed_channels:
      - 频道ID

接入 Slack

# 第一步：创建 Slack App
# https://api.slack.com/apps

# 第二步：启用 Bot 功能
# Features → Bot

# 第三步：设置权限
# OAuth & Permissions → Scopes
# 添加 bot, chat:write, channels:history 等权限

# 第四步：安装到工作区
# Install App → Install to Workspace

# 第五步：配置
export SLACK_BOT_TOKEN="xoxb-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXXXXXXXXXXXX"
export SLACK_SIGNING_SECRET="xxxxxxxxxxxxxxxxxxxx"

hermes gateway --platform slack --token $SLACK_BOT_TOKEN

接入企业微信 / 钉钉 / 飞书

# 企业微信
export WECOM_CORP_ID="wwxxxxxxxxxxxxxx"
export WECOM_AGENT_ID="1000001"
export WECOM_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

hermes gateway --platform wecom --config ~/.hermes/wecom.yaml
# 钉钉
export DINGTALK_APP_KEY="dingxxxxxxxxxxxx"
export DINGTALK_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxx"

hermes gateway --platform dingtalk
# 飞书
export FEISHU_APP_ID="cli_xxxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxx"

hermes gateway --platform feishu

二、Webhook 回调接口

Webhook 允许 Hermes Agent 接收来自第三方系统的 HTTP POST 请求，实现事件驱动的自动化。

配置 Webhook 接收

# config.yaml 中启用 Webhook
gateway:
  webhook:
    enabled: true
    port: 18789
    path: /webhook
    secret: "your-webhook-secret"  # 签名验证密钥

# 可用端点
# POST /webhook           - 通用事件接收
# POST /webhook/telegram  - Telegram 专用
# POST /webhook/discord   - Discord 专用
# GET  /webhook/health    - 健康检查
# 启动带 Webhook 的 Gateway
hermes gateway --webhook --port 18789

Webhook 签名验证

为了安全，所有 Webhook 请求都包含签名头，接收端必须验证：

# 签名头格式
X-Hermes-Signature: sha256=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Python 验证示例
import hmac, hashlib

def verify_signature(payload_body, secret, signature_header):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# Flask 示例
from flask import Flask, request
app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    sig = request.headers.get('X-Hermes-Signature', '')
    if not verify_signature(request.data, 'your-webhook-secret', sig):
        return 'Invalid signature', 401
    # 处理事件
    return 'OK', 200

发送 Webhook 到第三方

# 让 Hermes 主动推送 Webhook 到你的服务器
gateway:
  webhook:
    outbound:
      enabled: true
      url: "https://your-server.com/hermes-webhook"
      events:
        - message.received
        - task.completed
        - agent.error
      secret: "outbound-secret"

三、MCP 服务器暴露

MCP（Model Context Protocol）让 Hermes Agent 作为一个 MCP 服务器运行，供其他 MCP 客户端（如 Claude Desktop、Cursor、Cline）调用。

启动 MCP 服务器

# 方式一：stdio 模式（供本地 MCP 客户端调用）
hermes mcp

# 方式二：HTTP 模式（暴露给网络上的客户端）
hermes mcp --transport http --port 18790

# 查看可用工具
hermes mcp tools
# HTTP MCP 服务器端点
# GET  /tools    - 列出所有可用工具
# POST /execute  - 执行工具调用
# GET  /health  - 健康检查

# MCP 客户端配置示例（Claude Desktop）
{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp"],
      "env": {
        "HERMES_API_KEY": "your-api-key"
      }
    }
  }
}
# Cursor 中的 MCP 配置
# Settings → MCP Servers → Add New Server
{
  "hermes": {
    "url": "http://localhost:18790"
  }
}

MCP 工具列表

Hermes MCP 服务器暴露以下工具（按功能分组）：

  • memory：读取 / 写入持久化记忆
  • todolist：创建 / 更新 / 查询任务列表
  • file：读取 / 写入 / 搜索文件系统
  • terminal：执行 shell 命令
  • web：网页搜索和内容提取
  • delegate：派生子任务给 AI 处理
  • skill：加载和管理 Skills
  • session：搜索历史会话

MCP 安全配置

# config.yaml - MCP 安全配置
mcp:
  enabled: true
  port: 18790
  auth:
    type: api_key        # 或 "oauth2"
    api_keys:
      - key1
      - key2
    allowed_origins:
      - "https://your-app.com"
    rate_limit:
      requests_per_minute: 60

四、REST API 暴露

通过 HTTP REST 接口把 Hermes Agent 的能力直接暴露给第三方应用。

启用 REST API

# config.yaml
api:
  enabled: true
  port: 18791
  base_path: /api/v1
  auth:
    type: bearer_token
    token: "your-secure-api-token"

# 启动
hermes api --port 18791

核心 API 端点

# 对话接口（核心）
POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer your-secure-api-token

{
  "model": "openrouter/anthropic/claude-sonnet-4",
  "message": "你好，帮我查一下今天的天气",
  "session_id": "optional-session-id"
}
# 流式响应
POST /api/v1/chat
Accept: text/event-stream

{
  "model": "openrouter/anthropic/claude-sonnet-4",
  "message": "写一篇关于AI的文章",
  "stream": true
}
# 任务执行
POST /api/v1/execute
{
  "task": "帮我分析这份CSV数据",
  "attachments": ["https://example.com/data.csv"],
  "tools": ["terminal", "file"]
}
# 记忆读写
GET  /api/v1/memory?key=user_preferences
POST /api/v1/memory
{
  "key": "user_preferences",
  "value": {"theme": "dark", "language": "zh"}
}

# 会话历史
GET  /api/v1/sessions
GET  /api/v1/sessions/{session_id}/messages

# 系统状态
GET  /api/v1/status
GET  /api/v1/models

Python 调用示例

import requests

API_URL = "http://localhost:18791/api/v1/chat"
HEADERS = {"Authorization": "Bearer your-secure-api-token"}

# 同步对话
response = requests.post(
    API_URL,
    json={
        "model": "openrouter/anthropic/claude-sonnet-4",
        "message": "你好"
    },
    headers=HEADERS
)
print(response.json()["response"])

# 流式对话
with requests.post(
    API_URL,
    json={"model": "openrouter/anthropic/claude-sonnet-4", "message": "写一个hello world", "stream": True},
    headers=HEADERS,
    stream=True
) as r:
    for line in r.iter_lines():
        if line:
            print(line.decode())

五、Nginx 反向代理配置

生产环境推荐用 Nginx 做反向代理，统一处理 SSL 和负载均衡：

# /etc/nginx/sites-available/hermes
server {
    listen 443 ssl;
    server_name hermes-api.your-domain.com;

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.pem;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:18791;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";

        # WebSocket 支持（Gateway 长连接）
        proxy_read_timeout 86400;
    }

    location /webhook {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
# 启用配置
sudo ln -s /etc/nginx/sites-available/hermes /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

六、安全最佳实践

  • API Key 保护：所有 Token 不要写进代码，用环境变量或 .env 文件管理。
  • Telegram 限制白名单：设置 allowed_users，只允许特定用户调用。
  • Webhook 签名验证：生产环境务必启用签名验证，防止伪造请求。
  • MCP API Key 认证：网络暴露的 MCP 服务器必须开启 API Key 认证。
  • REST API 限流：配置 rate_limit 防止接口被滥用。
  • 定期轮换密钥：Telegram Token、MCP API Key 等定期更换。
  • 最小权限原则：每个平台接入只用必需的权限，不给多余权限。

七、常见问题

Q1：Telegram Bot 没有响应

# 检查 Bot Token 是否正确
echo $TELEGRAM_BOT_TOKEN

# 测试 Bot API
curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe"

# 查看日志
hermes gateway --platform telegram --log-level DEBUG

Q2：Webhook 收不到请求

# 确认端口已开放
sudo ufw allow 18789

# 测试本地接收
curl -X POST http://localhost:18789/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# 如果用了 Cloudflare 等代理，确认 webhook 地址在代理后台已白名单

Q3：MCP 客户端连接被拒绝

# 确认 MCP 服务器正在运行
curl http://localhost:18790/health

# 检查防火墙
sudo ufw allow 18790

# 如果开了认证，确认客户端配置了正确的 key
curl -H "x-api-key: your-key" http://localhost:18790/tools

Q4：REST API 返回 401

# 确认 Bearer Token 配置正确
# Header 格式：Authorization: Bearer your-secure-api-token
# 不要加额外的引号

# 检查 config.yaml 中的 token
cat ~/.hermes/config.yaml | grep -A2 "api:"

Q5：对外暴露接口有哪些安全风险？

主要风险包括：未授权访问（没有做认证）、Webhook 伪造（没验签名）、CORS 跨域问题、接口滥用（没限流）、数据泄露（Token 明文传输）。本文提供的配置均包含认证和加密措施，生产环境务必启用。

总结

Hermes Agent 的对外接口能力非常完整：Gateway 平台接入适合聊天平台、Webhook 适合事件驱动、MCP 服务器让 AI 能力被其他工具调用、REST API 则适合任意第三方应用集成。生产环境务必通过 Nginx 反向代理启用 HTTPS，并做好认证和限流配置。

相关推荐

© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
Hermes
# Hermes Agent# AI工具# AI使用技巧
喜欢就支持一下吧
点赞10 分享
猜你喜欢
评论 抢沙发

请登录后发表评论

    暂无评论内容

七天热门
Hermes Agent 安装教程：60秒快速上手（2026最新）-China AI Hub
1687人已阅读
Hermes Agent 安装教程：60秒快速上手（2026最新）
TOP1
Hermes Agent 常见问题FAQ：安装配置使用全覆盖（2026最新）-China AI Hub
Hermes Agent 常见问题FAQ：安装配置使用全覆盖（2026最新）
5天前680人已阅读
TOP2
Hermes Agent 安装教程：Windows/Linux/macOS 详细图解-China AI Hub
Hermes Agent 安装教程：Windows/Linux/macOS 详细图解
前天580人已阅读
TOP3
Hermes Agent 完整配置教程：从零配置到可用详细步骤-China AI Hub
Hermes Agent 完整配置教程：从零配置到可用详细步骤
前天347人已阅读
TOP4
Hermes Agent 安装教程：60秒快速上手（2026最新）-China AI Hub
Hermes Agent 安装教程：60秒快速上手（2026最新）
5天前243人已阅读
TOP5
Hermes Agent 47个内置工具详解：文件、代码、网页、Git全覆盖（2026最新）-China AI Hub
Hermes Agent 47个内置工具详解：文件、代码、网页、Git全覆盖（2026最新）
5天前171人已阅读
TOP6