从零部署 Hermes 以来遇到的问题与解决指南

一、总览：真正难的不是安装

环境限制

SCNet/HPC 登录节点风格环境，老 Linux、非 root、无图形界面、无 D-Bus user session。常见桌面 Linux 或云主机方案不能直接照搬。

网络限制

出网依赖 Clash Meta / CrashCore，本机代理端口是 127.0.0.1:7893。Telegram、OpenAI/Codex、Cloudflare API 都要确认实际进程走代理。

运维限制

不能依赖 systemctl --user，cron/nohup/daemon 启动会丢环境变量。网关稳定性最终取决于单实例、显式环境和可检查的日志。

最重要经验：“配置文件写了”不等于“gateway 进程读到了”。必须检查正在运行的进程是否继承了代理变量、Telegram allowlist 和 Hermes auth 配置。

二、实际环境画像

主机类型

国家超算互联网 / HPC 登录节点风格环境

系统约束

Linux 3.10 内核、CentOS 7 系列特征、无头、非 root、无 D-Bus user session

用户目录

/public/home/freemax

Hermes 主目录

/public/home/freemax/.hermes

代理出口

Clash Meta / CrashCore，HTTP(S) 代理 127.0.0.1:7893

Bot @scnet_hermess_bbot，polling mode，经代理访问 Telegram API

允许入口

用户私聊 594665457 与当前群聊 -1003777010501

静态站点

Cloudflare Pages 项目 hermes-view，自定义域 view.dce.pub

三、问题清单：现象、根因、解决方案

1. Telegram 私聊突然不回复

现象：用户在 Telegram 私聊发送消息后，Hermes 没有回复；日志出现 Unauthorized user: 594665457。

根因：只改 config.yaml 不够，实际 gateway 授权还依赖进程环境变量。cron/nohup 启动的 gateway 没有继承交互 shell 里的授权变量。

TELEGRAM_ALLOWED_USERS=594665457
TELEGRAM_GROUP_ALLOWED_CHATS=-1003777010501
TELEGRAM_ALLOW_ALL_USERS=false

解决：把 allowlist 写入 ~/.hermes/.env，并让 ~/.hermes/scripts/start_gateway_daemon.py 显式加载；重启后检查日志不再出现 unauthorized。

2. Telegram 群聊不响应

现象：私聊可用，但群聊里发消息没反应。

根因：BotFather Privacy Mode 开启时，普通群消息不会投递给 bot；消息没有 @scnet_hermess_bbot；或者群 ID / 发言人 ID 未在 allowlist。

群里用 @scnet_hermess_bbot 你的问题。
也可以回复 bot 的历史消息，或使用 slash command。
保持 Privacy Mode 开启，避免 bot 读取群里每句话造成 token 浪费。

3. Gateway 掉线后没有及时恢复

现象：Telegram 网关断线后，用户感觉长时间不回复。

根因：当前环境不能用 systemctl --user；旧 watchdog 使用 crontab 每分钟检查，helper 脚本曾放在 /tmp，存在被清理风险；旧检查只看进程，不看 Telegram 实际健康。

~/.hermes/scripts/start_gateway_daemon.py
~/.hermes/scripts/start_clash_daemon.py
~/.hermes/scripts/gateway-watchdog.sh

后续优化：watchdog 不应只 pgrep，还应检查日志心跳、Telegram API 连通性，并用 PID 文件或锁文件保证单实例。

4. 多个 gateway 进程互相冲突

现象：群聊/私聊时好时坏，日志可能出现 polling 冲突或重复启动。

根因：crontab watchdog 每分钟误判 gateway 不存在并 spawn 新进程，多个实例争抢同一个 Telegram bot token 的 polling。

解决：清理 crontab 中旧 watchdog，强杀所有旧 gateway，只启动一个干净实例。之后把“单实例”作为启动脚本硬约束。

5. OpenAI Codex OAuth 设备码请求 403 / 卡住

现象：hermes auth add openai-codex 或设备码流程无输出、403、无法拿到 user code。

根因：请求没有走代理，或 OpenAI 授权端点在中国直连受阻。

解决：先用代理验证 OpenAI device auth 端点可达，再确保 Hermes 进程环境包含 HTTP_PROXY / HTTPS_PROXY。必要时用 Python/httpx 显式 proxy 完成设备码轮询。

export HTTP_PROXY=http://127.0.0.1:7893
export HTTPS_PROXY=http://127.0.0.1:7893
export ALL_PROXY=socks5://127.0.0.1:7893

6. Secret redaction 影响 token/secret 写入

现象：工具调用中看起来写入了 token，但实际被替换成 ***。

根因：Hermes 的 secret redaction 会拦截工具输入/输出中的敏感形态字符串。

解决：不要在对话或命令行中直接传 token。让用户直接写入 ~/.hermes/.env 或 ~/.hermes/secrets/*，脚本运行时从文件读取。

7. Feishu/Lark SDK 导入极慢，接入已暂停

现象：安装 lark-oapi 后，导入 SDK 可能超过 120 秒。

根因：该 SDK eager import 大量 API 模块；在 NFS/HPC 文件系统上导入成本被放大。

已做：曾对 lark_oapi/__init__.py 与 lark_oapi/api/__init__.py 做 lazy import 风格补丁，并保留 *.hermes-bak 备份。

状态：用户已要求暂停飞书/lark 接入，后续除非明确重启，不主动推进。

8. 静态页面部署到 Cloudflare Pages

目标：把博客首页部署到 view.dce.pub，把本指南放到 /post/build.html，并复制到 /post/build/index.html 支持 /post/build。

部署路径：/public/home/freemax/public-pages/view-dce-pub/

部署脚本：/public/home/freemax/.hermes/scripts/deploy_cloudflare_pages.py，从 ~/.hermes/secrets/ 读取 Cloudflare 凭据，不在对话中暴露。

四、Telegram Gateway Runbook

当 Telegram 不回复时

先区分私聊还是群聊。私聊看 user allowlist；群聊看 chat allowlist 与 Privacy Mode。
群聊先用 @scnet_hermess_bbot 测试，不要只发普通消息。
检查 gateway 日志最近是否有 inbound、unauthorized、send error。
确认只存在一个 hermes gateway run 进程。
确认运行中进程环境里有代理变量和 Telegram allowlist 变量。

授权变量建议：私聊只允许 594665457，群聊只允许 -1003777010501，不要为了调试长期打开 TELEGRAM_ALLOW_ALL_USERS=true。

五、代理、OAuth 与外网请求

代理端口

127.0.0.1:7893 是关键出口。不要只验证浏览器或交互 shell，要验证实际服务进程。

OAuth

OpenAI Codex 设备码流程需要访问授权端点。直连 403 或超时，优先怀疑代理没有继承。

Cloudflare

Pages 部署脚本读取 secret 文件，并通过 Cloudflare API 发布，不应在日志或聊天中暴露 token。

curl -x http://127.0.0.1:7893 https://api.telegram.org/
curl -x http://127.0.0.1:7893 https://auth.openai.com/
curl -x http://127.0.0.1:7893 https://api.cloudflare.com/client/v4/

六、多 Agent 工作站现状

Hermes Agent OpenAI Codex Qwen Code OpenClaw Claude Code（已安装但需凭据）

Hermes：主对话、Telegram 接入、记忆、工具调度、长期运维。
Codex：代码任务、repo 内自动修改、带 web_search 的研究。
Qwen/OpenClaw：备用代码代理或并行审查。
Claude Code：已安装，但需要 API key 或 OAuth 登录后才能稳定使用。

多 Agent 的重点不是“装得多”，而是给每个工具明确边界：谁负责入口、谁负责代码修改、谁负责部署、谁负责审查，避免多个 agent 同时改同一处文件。

七、日常运维 Runbook

Gateway 重启前

确认 Clash/CrashCore 正在监听 127.0.0.1:7893。
确认 ~/.hermes/.env 包含 Telegram allowlist 与代理变量。
确认没有旧 hermes gateway run 残留。
用 daemon 脚本启动，不要手工随意 nohup 多份。

OAuth / 外网请求失败时

直接用代理请求目标域名，先排除网络问题。
检查 Hermes/gateway 进程是否继承代理变量。
涉及 token 的操作走 secret 文件，不在命令行或聊天中传递。

八、下次重装/迁移检查清单

代理：Clash/CrashCore 启动，127.0.0.1:7893 可用。
Hermes：确认 ~/.hermes/config.yaml、~/.hermes/.env、~/.hermes/auth.json。
Telegram：确认 bot token、私聊 ID、群聊 ID、allowlist 环境变量。
Gateway：只启动一个实例；不要让 cron/watchdog 重复拉起。
Secrets：token 写入 secret 文件，避免被 redaction 或日志泄露。
Codex：OAuth 设备码流程必须确认走代理。
Cloudflare Pages：使用部署脚本读取 ~/.hermes/secrets/cloudflare_*。
Feishu/Lark：当前为暂停事项，不纳入默认迁移目标。