适用版本

本方案已实机验证:

Hermes Agent v0.21.2 (2026.9.11)
upstream: 205645ee
Install method: git
Install directory: /usr/local/lib/hermes-agent
Python: 3.11.16

仅明确适用于上述 Hermes v0.21.2 / upstream 205645ee。

后续升级 Hermes 后,应先检查相关代码是否已经由官方修复,不应直接照搬本补丁。


一、问题现象

服务器同时运行:

hermes gateway
hermes dashboard

Gateway 为 root 用户的 systemd user service:

/root/.config/systemd/user/hermes-gateway.service

Dashboard 为 system service:

/etc/systemd/system/hermes-dashboard.service

虽然服务类型不同,但两者最终都以:

USER=root
HOME=/root
HERMES_HOME=/root/.hermes

或等效环境运行,因此都会读取同一套:

/root/.hermes/config.yaml

Hermes v0.21.2 中,Gateway 和 Dashboard 是两个独立 Python 进程,各自执行 MCP discovery,因此会分别启动一整套 stdio MCP。

实际表现:

Gateway
├─ BrightData
├─ Playwright
├─ Tuniu MCP ×8
└─ mcp_death_supervisor

Dashboard
├─ BrightData
├─ Playwright
├─ Tuniu MCP ×8
└─ mcp_death_supervisor

因此形成两套重复 MCP。

这不是:

权限问题
root/user 权限问题
system service / user service 冲突

而是 Hermes 当前 MCP 生命周期按进程管理造成的。


二、实际内存影响

修改前:

Gateway cgroup    ≈ 1.1 GB
Dashboard cgroup  ≈ 1.2 GB

整机 RAM:
used       ≈ 2.7–2.8 GB
available  ≈ 1.1 GB

Dashboard 自身启动第二套 MCP 后,占用超过 1GB。

修改后:

Dashboard MemoryCurrent ≈ 163 MB

整机:

RAM total      3.8 GB
used           1.8 GB
free           1.4 GB
available      2.1 GB

实际释放约:

≈ 1 GB RAM

因此 4GB VM 的内存压力明显下降。


三、v0.21.2 为什么可以安全改为 Lazy MCP

v0.21.2 中 Dashboard 启动时存在 eager MCP discovery:

/usr/local/lib/hermes-agent/hermes_cli/main.py

对应逻辑:

if not mcp_discovery_after_bind:
    from hermes_cli.mcp_startup import start_background_mcp_discovery
    start_background_mcp_discovery(
        logger=logger,
        thread_name="dashboard-mcp-discovery",
    )

这会导致:

Dashboard 服务刚启动
        ↓
立即启动整套 MCP

但 v0.21.2 的 WebSocket / Agent session 路径已经具备按需 MCP 初始化。

文件:

/usr/local/lib/hermes-agent/tui_gateway/server.py

Agent session 构建时存在:

from tui_gateway.entry import ensure_mcp_discovery_started
ensure_mcp_discovery_started()

随后 _make_agent() 中还会:

wait_for_mcp_discovery()

并且存在:

_schedule_mcp_late_refresh()

用于 MCP 较慢时完成后续工具刷新。

因此 v0.21.2 已具备完整链路:

Dashboard 普通启动
        ↓
无需 MCP

真正创建 Chat / Agent session
        ↓
ensure_mcp_discovery_started()
        ↓
后台启动 MCP
        ↓
wait_for_mcp_discovery()
        ↓
必要时 late refresh

所以可以取消 Dashboard 启动阶段的 eager MCP,而保留真正需要 Agent 时的 lazy MCP。


四、实施方案

目标:

Gateway
└─ 长期持有唯一一套 MCP

Dashboard
└─ 普通启动时不加载 MCP

但 Dashboard Chat 真正创建 Agent session 时,仍允许按需加载 MCP。


1. 备份 main.py

cp -a \
/usr/local/lib/hermes-agent/hermes_cli/main.py \
/usr/local/lib/hermes-agent/hermes_cli/main.py.bak-20260913-mcp

2. 给 Dashboard eager MCP 增加环境变量开关

执行:

python3 - <<'PY'
from pathlib import Path

p = Path("/usr/local/lib/hermes-agent/hermes_cli/main.py")
s = p.read_text()

old = '''    if not mcp_discovery_after_bind:
        try:
            from hermes_cli.mcp_startup import start_background_mcp_discovery
'''

new = '''    if (
        os.environ.get("HERMES_DASHBOARD_EAGER_MCP", "1") != "0"
        and not mcp_discovery_after_bind
    ):
        try:
            from hermes_cli.mcp_startup import start_background_mcp_discovery
'''

if s.count(old) != 1:
    raise SystemExit(f"ABORT: target count={s.count(old)}")

p.write_text(s.replace(old, new, 1))
print("OK")
PY

这样默认行为仍然兼容 Hermes 原逻辑:

HERMES_DASHBOARD_EAGER_MCP 未设置
        ↓
默认值 1
        ↓
仍然 eager MCP

只有明确设置:

HERMES_DASHBOARD_EAGER_MCP=0

才关闭 Dashboard 启动阶段 MCP。


3. 检查 Python 语法

/usr/local/lib/hermes-agent/venv/bin/python -m py_compile \
/usr/local/lib/hermes-agent/hermes_cli/main.py

无输出即正常。


4. 给 Dashboard 设置 Lazy MCP

创建 systemd drop-in:

mkdir -p /etc/systemd/system/hermes-dashboard.service.d

cat >/etc/systemd/system/hermes-dashboard.service.d/mcp-lazy.conf <<'EOF'
[Service]
Environment="HERMES_DASHBOARD_EAGER_MCP=0"
EOF

5. 重载 systemd

systemctl daemon-reload

6. 只重启 Dashboard

systemctl restart hermes-dashboard

注意:

不要重启 Gateway

Gateway MCP 保持原状。


五、验证

执行:

echo '=== dashboard memory ==='
systemctl show hermes-dashboard -p MemoryCurrent

echo
echo '=== memory ==='
free -h

echo
echo '=== MCP processes ==='
ps -eo pid,ppid,rss,comm,args --forest | \
grep -E 'hermes|mcp-remote|playwright|brightdata|mcp_death_supervisor' | \
grep -v grep

正常结果应该是:

Gateway
├─ BrightData
├─ Playwright
├─ mcp-remote
├─ ...
└─ mcp_death_supervisor

Dashboard
└─ hermes dashboard

Dashboard 下不再出现:

mcp-remote
playwright-mcp
brightdata/mcp/server.js
mcp_death_supervisor

实测:

Dashboard MemoryCurrent ≈ 163 MB

证明第二套常驻 MCP 已成功消除。


六、最终运行结构

修改前:

/root/.hermes/config.yaml
        │
        ├───────────────┐
        ↓               ↓
Gateway             Dashboard
   ↓                   ↓
MCP ×1套            MCP ×1套

总计:MCP ×2

修改后:

Gateway
├─ 微信 / 企业微信
├─ Agent
└─ MCP ×1套
        ↑
     常驻

Dashboard
└─ WebUI
   配置
   状态
   Sessions
   日志
   MCP管理页面

普通 Dashboard 管理操作:

不会启动第二套 MCP

七、Dashboard Chat 的注意事项

当前方案解决的是:

Dashboard 24小时常驻第二套 MCP

并没有实现:

Gateway 与 Dashboard 跨进程共享同一套 MCP

v0.21.2 中,当 Dashboard 真正创建 Chat / Agent session 时:

ensure_mcp_discovery_started()

仍可能按需启动 Dashboard 自己的一套 MCP。

所以:

平时:

Gateway     MCP ×1
Dashboard   MCP ×0

使用 Dashboard Chat 后可能变成:

Gateway     MCP ×1
Dashboard   MCP ×1(lazy)

这是 Hermes 当前跨进程 MCP 生命周期设计造成的,并非本补丁异常。

如果主要通过:

企业微信
个人微信
Gateway Agent

使用 Hermes,而 Dashboard 主要用于管理,则本方案非常适合。


八、Swap 说明

优化后可能仍看到:

Swap used 较高

例如:

Swap: 6GB
used: 2.4GB

但只要:

available RAM 充足
vmstat 中 si/so 基本为 0

就不代表系统正在持续内存交换。

检查:

vmstat 1 10

正常应基本为:

si   so
0    0
0    0
0    0

不建议为了数字好看执行:

swapoff -a

九、回滚

如果 Dashboard 出现异常:

rm -f /etc/systemd/system/hermes-dashboard.service.d/mcp-lazy.conf

cp -a \
/usr/local/lib/hermes-agent/hermes_cli/main.py.bak-20260913-mcp \
/usr/local/lib/hermes-agent/hermes_cli/main.py

systemctl daemon-reload
systemctl restart hermes-dashboard

Gateway 不需要重启。


十、Hermes 升级注意事项

当前安装方式:

Install method: git

因此:

hermes update

可能:

  1. 覆盖 main.py 本地补丁;
  2. 因本地修改导致 git dirty tree;
  3. upstream 已经正式修复重复 MCP,此时补丁不再需要;
  4. upstream 修改代码结构,旧补丁不再适配。

每次升级后先检查:

hermes --version

grep -Rni \
"start_background_mcp_discovery" \
/usr/local/lib/hermes-agent/hermes_cli \
/usr/local/lib/hermes-agent/tui_gateway \
2>/dev/null

并检查:

tui_gateway/server.py

是否仍有:

ensure_mcp_discovery_started()

只有确认新版本逻辑后,再决定是否继续使用本补丁。


当前已验证结论

适配并验证:

Hermes Agent v0.21.2
发布日期:2026-09-11
upstream commit:205645ee

实测结果:

Dashboard:
约 1.2GB → 163MB

整机 RAM used:
约 2.8GB → 1.8GB

available:
约 1.1GB → 2.1GB

核心原则:

Gateway = 常驻 MCP Owner
Dashboard = 默认不启动 MCP
Dashboard Agent/Chat = 必要时 Lazy MCP

​