Hermes 自托管实战：工具栈 + 部署流程

一台 8G Ubuntu 家庭服务器，从 0 跑起 Hermes Agent + 4 个自托管后端 + 2 个消息平台。所有配置给绝对路径，可直接对照操作。

1. 架构总览

┌─────────────────────────────────────────────────────────┐
│  消息入口                                              │
│  ┌──────────┐  ┌──────────┐                             │
│  │ QQ Bot   │  │ Telegram │  ← 双通道互备                │
│  └─────┬────┘  └────┬─────┘                             │
│        │            │                                  │
│        ▼            ▼                                  │
│  ┌──────────────────────────────────────┐              │
│  │  hermes-gateway  (WebSocket / 轮询)  │  9119        │
│  └────────────────┬─────────────────────┘              │
│                   │                                    │
│                   ▼                                    │
│  ┌──────────────────────────────────────┐              │
│  │  Hermes Agent 本体  (CLI / 内存)     │  +dashboard  │
│  │  • SOUL / AGENTS / TOOLS / MEMORY    │   :9119      │
│  │  • honcho_* 5 工具                   │              │
│  │  • mcp__<server>__<tool> 双下划线     │              │
│  └────┬─────────┬─────────┬────────┬───┘              │
│       │         │         │        │                   │
│       ▼         ▼         ▼        ▼                   │
│  ┌────────┐ ┌──────┐ ┌──────┐ ┌─────────┐             │
│  │Firecrawl│ │Camofox│ │Honcho│ │ 其他服务│            │
│  │  :3002  │ │ :9377 │ │ :8000│ │  按需   │            │
│  │ web 抓取│ │浏览器 │ │记忆层│ │         │            │
│  └────┬───┘ └──┬───┘ └──┬───┘ └────┬────┘             │
│       │        │        │          │                   │
│       └────────┴────────┴──────────┘                   │
│                       │                                │
│                       ▼                                │
│              ┌──────────────────┐                      │
│              │  宿主机出公网     │                      │
│              │  (宿主机已配代理) │                      │
│              └──────────────────┘                      │
└─────────────────────────────────────────────────────────┘

2. 工具栈速查

组件	端口	用途	部署方式	关键配置
Hermes Agent	—	核心 CLI	`pip install hermes-agent`	`~/.hermes/config.yaml` + `~/.hermes/.env`
hermes-dashboard	9119	Web UI	systemd user service	`~/.config/systemd/user/hermes-dashboard.service`
hermes-gateway	9118	消息平台入口	systemd user service	`~/.config/systemd/user/hermes-gateway.service`
Firecrawl	3002	web_extract / web_search	docker	`web.backend: firecrawl`
Camofox	9377	反检测浏览器	docker	`CAMOFOX_URL=http://localhost:9377`
Honcho	8000	记忆层	docker-compose (api+deriver+pg+redis)	`~/.hermes/honcho.json` baseUrl
Clash Verge (rev)	10000	出公网代理	宿主机 GUI	必须 redir-host 模式
---

3. 部署流程（按顺序执行）

3.1 基础环境

# 假定用户是 youruser，home 在 /home/youruser
sudo apt update && sudo apt install -y python3-pip docker.io docker-compose-plugin
pip install --user hermes-agent
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 当前用户加入 docker 组（免 sudo）
sudo usermod -aG docker $USER
newgrp docker

# user service 持久化（SSH 退出后不挂）
sudo loginctl enable-linger $USER

3.2 Hermes 基础配置

文件：~/.hermes/config.yaml

# 关闭审批（带引号，否则变 bool false）
approvals:
  mode: "off"

# 开启 checkpoint（救命功能，先开再往下走）
checkpoints:
  enabled: true

# 路由：web 抓取走 Firecrawl
web:
  backend: firecrawl

# 路由：浏览器走 Camofox（通过 env 触发，yaml 写不写都行）
browser:
  cloud_provider: firecrawl  # Camofox 模式下这行被忽略，但留着方便理解

文件：~/.hermes/.env

# Camofox（设了就接管所有 browser_* 工具）
CAMOFOX_URL=http://localhost:9377

# Firecrawl API key（如果你的部署启用了）
FIRECRAWL_API_KEY=fc-xxx

# Honcho 自托管
HONCHO_BASE_URL=http://localhost:8000

# QQ Bot
QQ_APP_ID=xxx
QQ_CLIENT_SECRET=xxx

# Telegram
TELEGRAM_BOT_TOKEN=xxx

文件：~/.hermes/memories/ 下三个文件按需定制：
- SOUL.md — Agent 性格（语言、语气、行为准则）
- AGENTS.md — 做事流程（修配置先 diff、Docker 用 background+wait、自托管失败先排查不绕道）
- TOOLS.md — 工具用法 + 失败排查套路

机制说明：以上三个文件每次新会话以冻结快照注入。当前会话改完不会生效，需 /new 才生效。

3.3 Firecrawl

docker run -d --name firecrawl-api \
  --restart unless-stopped \
  -p 3002:3002 \
  -e USE_DB_AUTHENTICATION=false \
  firecrawl/firecrawl:latest

# 验证
curl -sS http://localhost:3002/health

3.4 Camofox

docker run -d --name camofox \
  --restart unless-stopped \
  -p 9377:9377 \
  -v camofox-data:/data \
  ghcr.io/nicholasgasior/camofox:latest

curl -sS http://localhost:9377/  # 返 200 即活

3.5 Honcho（自托管三件套）

文件：~/honcho/docker-compose.yml

version: "3.8"
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: postgres
    volumes:
      - honcho-pg:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s

  api:
    image: ghcr.io/plastic-labs/honcho-api:latest
    depends_on:
      postgres: { condition: service_healthy }
      redis:    { condition: service_healthy }
    environment:
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres
      REDIS_URL: redis://redis:6379
      DERIVER_URL: http://deriver:8000
    ports:
      - "8000:8000"

  deriver:
    image: ghcr.io/plastic-labs/honcho-deriver:latest
    depends_on:
      - postgres
      - redis
    environment:
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres
      REDIS_URL: redis://redis:6379

volumes:
  honcho-pg:

cd ~/honcho && docker compose up -d
docker compose ps  # api + deriver 都 healthy 即可

文件：~/.hermes/honcho.json

{ "baseUrl": "http://localhost:8000" }

自托管模式不要写 apiKey 字段——它会绕过 baseUrl 去打 honcho.ai 云端。

3.6 消息平台

QQ Bot（不走官方 20+ 平台清单，源码在 gateway/platforms/qqbot/）：

export QQ_APP_ID=xxx
export QQ_CLIENT_SECRET=xxx
hermes gateway --qqbot  # 按提示扫码

Telegram（标准 BotFather token）：

export TELEGRAM_BOT_TOKEN=xxx
hermes gateway --telegram

3.7 开机自启（systemd user service）

文件：~/.config/systemd/user/hermes-dashboard.service

[Unit]
Description=Hermes Agent Dashboard
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/hermes dashboard --no-open
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

文件：~/.config/systemd/user/hermes-gateway.service

[Unit]
Description=Hermes Gateway (Messaging Platforms)
After=network.target docker.service

[Service]
Type=simple
EnvironmentFile=%h/.hermes/.env
ExecStart=%h/.local/bin/hermes gateway
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now hermes-dashboard hermes-gateway
systemctl --user status hermes-dashboard  # 看到 active (running) 即成

4. 关键流程

4.1 加新自托管服务（5 步 probe 协议）

装任何 MCP / 第三方 bridge 之前先跑：

步	操作	目的
1	扫服务的 `/openapi.json` 找 `/mcp` 端点	确认是否原生支持 MCP
2	读 `components.securitySchemes`	搞清 key 走 header / query / Bearer
3	用真 MCP 调用验 key 错对	access_token ≠ apikey ≠ 密码
4	拉 tool list 看数量	1-3 个是 PoC，10+ 个是真集成
5	评估 key 爆炸半径	决定直接用还是建子账号

原则：服务有原生 MCP 就用原生（Sonarr / Radarr / Jellyfin / Home Assistant / GitHub / Notion 几乎都自带）。第三方 bridge 是退路不是首选。

4.2 自托管服务失败排查顺序

工具失败时不要立刻 fallback 到 curl+Python 解析。按下面顺序：

服务在跑吗？docker ps | grep <name> / systemctl --user status <unit>
端口在听吗？ss -ltnp | grep <port>
容器健康？docker inspect --format='{{.State.Health.Status}}' <name>
| 4 | 容器日志最近 20 行？docker logs --tail 20 <name> |
| 5 | DNS 返真 IP 吗？getent hosts example.com |

4.3 修改配置的标准动作

# 1. 改前先看当前值
hermes config get <key>

# 2. 改（敏感文件直接 patch 不用 config set）
patch ~/.hermes/config.yaml <<'EOF'
--- a/config.yaml
+++ b/config.yaml
@@ -X,Y +X,Y @@
-old: value
+new: value
EOF

# 3. 验证
hermes config get <key>

# 4. 必要时新开会话加载（frozen-snapshot 机制）
/new

5. 踩坑速查表

症状	根因	修法
`hermes config set approvals.mode off` 写进去是 `false`	`config set` 把字符串当 bool 解析	改完用 `patch` 加引号 `"off"`
SOUL.md 改了当前会话没生效	frozen-snapshot 注入机制	`/new` 开新会话
`CAMOFOX_URL` 设了浏览器还走云端	`browser.cloud_provider` 覆盖	yaml 改不改都行，真正生效的是 env
`browser.cloud_provider: firecrawl` 和 Camofox 不能同时开	代码层 camofox 短路在 nav 入口最前	二选一；要切换改 env 不改 yaml
`mcp__<server>__<tool>` 报 tool not found	工具命名是双下划线不是单下划线	写 `mcp__<server>__<tool>`，两个下划线
`honcho_reasoning` 返空	deriver 异步跑 dialectic，peer card 还在 warming up	等 5-10 分钟再查，非错误
Hermes honcho 调云端而不是本地	配了 `apiKey` 字段	删 `apiKey`，只保留 `baseUrl`
systemd user service SSH 退出后挂	缺 linger	`sudo loginctl enable-linger $USER`
`docker compose restart` 不真重启	compose 复用旧 container	改用 `docker compose up -d --force-recreate`
`frpc 0.69+` dashboard 脚本全炸	API 路径从 `/api/v1` 改成 `/api`	升级时同步改监控脚本
checkpoint 满了磁盘	默认 500MB 上限	改 `checkpoints.max_total_size_mb` 或删 `~/.hermes/checkpoints/`

6. 升级 / 维护清单

频率	任务	命令
每周	`hermes` 升级	`pip install -U hermes-agent`
每周	后端镜像拉新	`docker compose pull && docker compose up -d`（honcho / firecrawl / camofox）
每周	checkpoint 清理	看 `~/.hermes/checkpoints/` 体积，超过 500MB 手动清
每月	Honcho peer card 复查	`hermes honcho status` + 抽查 `honcho_profile`
每月	`.env` / `config.yaml` diff 一次	防止某次手抖改动被遗忘
每季	SOUL / AGENTS / TOOLS 复盘	用着不顺就改，改完 `/new` 验证
每季	backup：`~/.hermes/` 整目录 + 各 `~/honcho/` `docker-compose.yml`	`tar -czf backup-$(date +%F).tar.gz ~/.hermes ~/honcho`

7. 入口速记

# 起停
hermes                                              # 启 CLI
hermes dashboard --no-open                          # 启 Web UI
hermes gateway                                      # 启消息平台网关
systemctl --user {start,stop,status} hermes-dashboard hermes-gateway

# 配置
hermes config get <key>                             # 读
hermes config set <key> <value>                     # 写（注意 bool 坑）
hermes config path                                  # 配文件位置

# 记忆 / 工具
hermes memory status                                # 记忆层状态
hermes honcho status                                # Honcho 状态
hermes tools list | grep mcp                        # 看 MCP 工具

# 调试
journalctl --user -u hermes-dashboard -f            # 实时日志
docker logs -f firecrawl-api                        # Firecrawl 日志
curl localhost:3002/health                          # Firecrawl 健康
curl localhost:9377/                                # Camofox 健康
curl localhost:8000/health                          # Honcho 健康

菜单

分享

Hermes 自托管实战：工具栈 + 部署流程

Hermes 自托管实战：工具栈 + 部署流程

1. 架构总览

2. 工具栈速查

3. 部署流程（按顺序执行）

3.1 基础环境

3.2 Hermes 基础配置

3.3 Firecrawl

3.4 Camofox

3.5 Honcho（自托管三件套）

3.6 消息平台

3.7 开机自启（systemd user service）

4. 关键流程

4.1 加新自托管服务（5 步 probe 协议）

4.2 自托管服务失败排查顺序

4.3 修改配置的标准动作

5. 踩坑速查表

6. 升级 / 维护清单

7. 入口速记

评论

Hermes 自托管实战：工具栈 + 部署流程