Skip to content

EXTERNAL_HERMES.md

Latest commit

 

History

History
248 lines (179 loc) · 7.94 KB

EXTERNAL_HERMES.md

File metadata and controls

248 lines (179 loc) · 7.94 KB

连接外部 Hermes Agent 配置指南

背景

danghuangshang 自 v3.7.0 起把 Hermes Agent(by Nous Research)作为 OpenClaw 的 平行 runtime:同一套 14 Agent 朝廷设定,你可以二选一跑,也可以两套 并存(各占不同端口)。

维度 OpenClaw 路线 Hermes 路线
语言 Node.js Python
配置文件 ~/.openclaw/openclaw.json ~/.hermes/config.yaml + .env
Token 位置 JSON 内 channels.*.accounts.*.token ~/.hermes/.env 环境变量
默认 GUI 端口 18795 (Hermes 自己用 dashboard 端口,默认 8765)
Gateway 端口 18789 不暴露独立端口,统一进程
多 Bot 多 Agent 原生 agents.list[] × bindings[] 用 personalities/ + profiles/
14 Agent 朝廷 ✅ 直接用 configs/* ✅ 用 configs/hermes/personalities/*
跨进程 sandbox sandbox.mode=non-main terminal.backend=docker/ssh/modal

二者底层都是"messaging gateway + 多 channel 路由 + 工具调用"的同代架构, Hermes 自带 hermes claw migrate 把 openclaw.json 直接转 Hermes config。

快速开始

方式 1: 全新装 Hermes(推荐新用户)

# 1. 装 Hermes(自带 uv / Python 3.11 / Node / ripgrep / ffmpeg)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

# 2. 拷贝 danghuangshang 的 Hermes 模板
mkdir -p ~/.hermes
cp ~/clawd/danghuangshang/hermes.example.yaml ~/.hermes/config.yaml

# 3. 拷贝朝廷角色人设
mkdir -p ~/.hermes/personalities
cp ~/clawd/danghuangshang/configs/hermes/personalities/*.md ~/.hermes/personalities/

# 4. 配 token / API key
cp ~/clawd/danghuangshang/configs/hermes/env.example ~/.hermes/.env
$EDITOR ~/.hermes/.env

# 5. 跑起来
hermes setup           # 交互式补缺失字段
hermes                 # CLI 直接进 REPL
hermes gateway start   # 启动 Discord/Telegram/Feishu/Slack 多通道网关

方式 2: 从已有 OpenClaw 迁移

# 一键把 ~/.openclaw/openclaw.json 转成 Hermes config
hermes claw migrate

# 然后把 danghuangshang 的人设覆盖上去
cp ~/clawd/danghuangshang/configs/hermes/personalities/*.md ~/.hermes/personalities/

方式 3: 两套 runtime 并存

# OpenClaw 跑在 18789(原 gateway)
openclaw gateway start

# 另开终端,Hermes 跑在自己进程
hermes gateway start --port 8765

两者绑定不同 Discord Bot Token / 飞书 App 即可。同一 Bot 不要同时被两边接管。

Token 与凭证(.env)

Hermes 不在 YAML 里写敏感字段,所有 token 走环境变量:

# ===== LLM =====
OPENROUTER_API_KEY=
ANTHROPIC_API_KEY=
# 或自托管 OpenAI 兼容网关
OPENAI_BASE_URL=https://your-llm-provider-api-url
OPENAI_API_KEY=

# ===== Discord =====
DISCORD_BOT_TOKEN=
DISCORD_APPLICATION_ID=
DISCORD_ALLOWED_ROLES=  # 可选,限制只有特定 role 能 @

# ===== Telegram =====
TELEGRAM_BOT_TOKEN=

# ===== 飞书 =====
FEISHU_APP_ID=
FEISHU_APP_SECRET=

# ===== Slack =====
SLACK_APP_TOKEN=
SLACK_BOT_TOKEN=

# ===== WhatsApp =====
# 走 baileys,首次扫码登录

完整变量表见 Hermes .env.example。

朝廷角色 → Hermes Personality 映射

OpenClaw 的 agents.list[] 在 Hermes 里对应 ~/.hermes/personalities/*.md:

OpenClaw agent.id Hermes personality 文件 说明
silijian silijian.md 司礼监(默认人设)
neige neige.md 内阁(prompt 优化 + 计划)
duchayuan duchayuan.md 都察院(代码审查)
bingbu bingbu.md 兵部(开发)
hubu hubu.md 户部(财务/分析)
libu libu.md 礼部(品牌/营销)
gongbu gongbu.md 工部(运维/部署)
libu2 libu2.md 吏部(项目管理)
xingbu xingbu.md 刑部(法务/合规)
hanlin_* hanlin_*.md 翰林院 5 子角色

切换角色:hermes 进入 REPL 后 /personality silijian 即可。 默认走哪个见 ~/.hermes/config.yaml 里 personality: 字段。

Discord 接入对照

OpenClaw 一个 Discord Bot 对应一个 accounts.*.token,需要 applicationId。 Hermes 一个进程默认一个 Bot,跨多个 Bot 要开多个 Hermes profile:

# 默认 profile = ~/.hermes
hermes gateway start

# 第二个 Bot(都察院专用)用独立 profile
HERMES_HOME=~/.hermes-duchayuan hermes gateway start

每个 profile 有自己独立的 .env 和 config.yaml。 14 Agent 朝廷玩到极致就是 14 个 profile。多数人用单 profile + personality 切换就够。

验证连接

1. 健康检查

hermes doctor              # 全栈诊断(模型/工具/平台/skill)
hermes status              # 当前模型 / 网关 / channel 状态
hermes channels list       # 当前启用的消息平台

2. 看 dashboard

hermes dashboard           # 默认 http://localhost:8765

3. 看 Gateway 日志

hermes gateway logs --follow

故障排除

问题 1:hermes 命令找不到

# 安装脚本结束后没刷新 shell
source ~/.bashrc   # 或 ~/.zshrc

# 仍找不到 → 手动加 PATH
export PATH="$HOME/.hermes/bin:$PATH"

问题 2:Discord 网关启动报 applicationId required

# 必填
echo "DISCORD_APPLICATION_ID=YOUR_APP_ID" >> ~/.hermes/.env
hermes gateway restart

OpenClaw v2026.5.x(已测到 v2026.5.20)起、Hermes v0.13.x 起,Discord slash 命令注册都要 applicationId。danghuangshang openclaw.example.json 已对齐补全。

问题 3:模型 401 / 空回复

hermes model           # 列已配置的 provider
hermes model auth      # 看 token 是否有效

问题 4:OpenClaw 已存在,不想动现有进程

直接走"方式 3 并存",两套绑定不同 Bot Token 就好。 hermes claw migrate 只读 OpenClaw 配置生成 Hermes 配置,不会改原文件。

架构对比

                ┌──────── Discord / Telegram / Feishu / Slack ────────┐
                │                                                      │
        ┌───────▼───────┐                                       ┌─────▼──────┐
        │  OpenClaw GW  │                                       │ Hermes GW  │
        │   :18789      │                                       │  内置进程   │
        └───────┬───────┘                                       └─────┬──────┘
                │                                                      │
        ┌───────▼───────┐                                       ┌─────▼──────┐
        │ agents.list[] │                                       │ personality│
        │  × bindings[] │                                       │  × profile │
        └───────┬───────┘                                       └─────┬──────┘
                │                                                      │
                └────────► 同一套 14 Agent 朝廷设定 ◄──────────────────┘

选哪个?

  • 你已经在跑 OpenClaw 多 Bot,且 14 Agent 跑得很满 → 留在 OpenClaw。
  • 你要单进程跨 20 个平台(WhatsApp/Signal/Email/Google Chat …)→ Hermes。
  • 你想 self-host Sandbox + RL 训练数据采集 → Hermes(自带 Atropos)。
  • 你怕折腾,想点一下就跑 → install-lite.sh 选 OpenClaw,默认路线。

两套 runtime 项目都在持续更新,本项目长期同步两边新版本。

相关文档