Hermes Agent 新建与启动消息网关全流程指南

By 是琪琪呢 | | 3 minutes
Hermes Agent 网关 教程

Hermes Agent 新建与启动消息网关全流程指南

前言

本指南面向需要在本地或服务器上快速搭建 Hermes Agent 并启动 消息网关 的技术人员。内容包括从创建独立 profile、配置文件、启动网关（前后台两种方式）、验证以及常见故障排查，全部采用 Markdown 格式，符合 Hugo 站点的发布要求。

目录

  1. 创建独立 Profile
  2. 配置 config.yaml
  3. [启动消息网关]
  4. 验证网关是否正常工作
  5. 常见问题与排查技巧
  6. 完整一键脚本示例

创建独立 Profile 

1
2

# 创建目录（假设使用 ID 1）
mkdir -p ~/.hermes/profiles/1

说明：每个 profile 独立管理配置、日志和网关实例，避免相互干扰。

配置 config.yaml

在 ~/.hermes/profiles/1/ 下创建 config.yaml（请自行替换 api_key 为真实值，不要在公开仓库泄露）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

profile_name: mygw
description: Hermes Agent 专用网关 profile
api_server:
  enabled: true
  address: 127.0.0.1
  port: 8642   # 与系统其它服务冲突请自行修改
model:
  provider: openai
  name: openai/gpt-oss-120b
  api_key: "[REDACTED]"
  base_url: "http://127.0.0.1:8317/v1"
logging:
  level: INFO
  file: logs/agent.log
  error_file: logs/error.log

提示：source ~/.bashrc && 必须在每次调用 Hermes 前执行，以确保环境变量（如代理、PATH）生效。

启动消息网关

前台运行（调试） 

1

source ~/.bashrc && hermes --profile 1 gateway run --replace
  • 输出：控制台实时打印日志，方便观察启动过程。
  • 停止：Ctrl+C 即可终止进程。

后台运行（生产） 

1

source ~/.bashrc && hermes --profile 1 gateway run --replace --background --notify_on_complete
  • 返回 session_id（如 proc_568635ce1526）和 PID（如 93560），后续可用 process 工具管理。
  • 推荐使用 --notify_on_complete，系统会在进程结束后主动通知，避免手动轮询。

验证网关是否正常工作

  1. 检查进程
1

process action=list
  1. 查看日志（最近 200 行）
1

process action=log session_id=proc_568635ce1526
  1. 发送测试消息（以 Feishu 为例）
1
2
3
4
5

# 发送一条简单的 test 消息到飞书 Home 频道
source ~/.bashrc && hermes --profile 1 message send \
  --platform feishu \
  --target oc_c12c7daf2c84d0f9349f95216fc4ec6e \
  --content "Hermes Agent 网关已成功启动，PID=$(cat ~/.hermes/profiles/1/gateway.lock | jq .pid)"
  • 若收到消息，即表示网关已成功接入 Feishu。

常见问题与排查技巧

症状 可能原因 排查步骤
错误 99991663 Invalid access token 飞书 tenant_access_token 过期或未正确读取 1. 确认 ~/.hermes/feishu/token.json 中的 tenant_access_token 是否最新。
2. 重新执行 hermes feishu token refresh 获取新 token。
Gateway 启动后立即退出 配置文件语法错误 / 端口被占用 1. 查看 logs/error.log 中的堆栈信息。
2. 使用 lsof -i:8642 检查端口占用情况。
消息发送失败 lark-cli 配置错误或机器人权限不足 1. 在 ~/.config/lark-cli/config.yaml 中确认 bot_token 正确。
2. 使用 lark-cli im messages-send --dry-run 预览请求。
日志文件未生成 logs/ 目录权限不足 mkdir -p ~/.hermes/profiles/1/logs && chmod 755 ~/.hermes/profiles/1/logs

快速排查脚本（可选） 

1
2
3
4
5
6
7
8
9

#!/usr/bin/env bash
source ~/.bashrc
PROFILE_DIR=~/.hermes/profiles/1
# 检查 config.yaml 语法
python3 -c "import yaml, sys; yaml.safe_load(open('$PROFILE_DIR/config.yaml'))" && echo "✅ config.yaml 语法 OK"
# 检查端口占用
if lsof -i:8642 >/dev/null; then echo "⚠️ 端口 8642 已被占用"; else echo "✅ 端口 8642 空闲"; fi
# 查看日志文件权限
ls -l $PROFILE_DIR/logs

完整一键脚本示例

保存为 ~/start_mygw.sh 并添加执行权限 chmod +x ~/start_mygw.sh：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

#!/usr/bin/env bash
set -euo pipefail
source ~/.bashrc
PROFILE=1
BASE=~/.hermes/profiles/$PROFILE

# 1. 创建目录（若不存在）
mkdir -p "$BASE" "$BASE/logs"

# 2. 写入 config.yaml（请自行替换 api_key）
cat > "$BASE/config.yaml" <<'EOF'
profile_name: mygw
description: Hermes Agent 专用网关 profile
api_server:
  enabled: true
  address: 127.0.0.1
  port: 8642
model:
  provider: openai
  name: openai/gpt-oss-120b
  api_key: "[REDACTED]"
  base_url: "http://127.0.0.1:8317/v1"
logging:
  level: INFO
  file: logs/agent.log
  error_file: logs/error.log
EOF

# 3. 启动网关（后台）
hermes --profile "$PROFILE" gateway run --replace --background --notify_on_complete

# 4. 输出提示
echo "✅ Hermes Agent 网关已在后台启动，进程信息已写入 $BASE/gateway.lock"

使用说明：运行 ~/start_mygw.sh 即可完成 profile 创建、配置以及网关启动，适合首次部署或快速恢复。

结束语

按照本指南操作后，你将拥有一个 独立且可管理 的 Hermes Agent 消息网关，能够安全地对接飞书、企业微信、Telegram 等多平台，并通过 hermes CLI 完整地进行监控与维护。后续如需添加其他平台，只需在对应的 Bot/SDK 配置文件中加入凭证并在 config.yaml 的 platforms 列表里声明即可。