一、这篇写给「按文档做了但就是起不来」的人
Hermes Agent（社区亦常被搜成 Hermas）走自托管路线时，坑主要集中在：环境变量、模型接口兼容、工具权限、Docker 网络、以及「看起来启动成功但第一条工具调用就失败」。本文按真实排障顺序记录，方便对照。
二、环境与依赖类
现象：安装成功，启动即报模块缺失 / Python 版本不符。
处理：锁死官方建议的 Python 小版本；用 venv/poetry；生产镜像钉死依赖 hash，不要在服务器 pip install 最新版碰运气。
现象：Windows 与 Linux 路径、换行不一致导致脚本失败。
处理：部署目标统一 Linux 容器；本地开发可用 WSL2。
三、模型 API 类
现象：401 / invalid api key。
处理：确认 Key 来自正确控制台；容器内环境变量是否真的注入（printenv）；勿把 Key 写进被挂载覆盖的旧 .env。
现象：连本地 Ollama 失败。
处理：容器内不要写 localhost 指宿主机；用 host.docker.internal 或组成同一 Compose 网络，Base URL 形如 http://ollama:11434/v1。
现象：模型名不匹配。
处理：先 ollama list / 上游 models 接口确认真实 model id，再写进 Agent 配置。
四、工具调用类
现象：模型只聊天不调工具。
处理：检查工具是否注册成功、描述是否清晰；温度是否过高；系统提示是否禁止了函数调用；换支持 tool/function calling 的模型。
现象：一调终端工具就乱删文件。
处理：默认只读工作目录；命令白名单；生产禁用裸 shell，改为受控 API 工具。
五、Docker / 网络类
现象：Web/API 端口映射了但外网访问不了。
处理：查安全组与本机防火墙；确认监听 0.0.0.0 而非仅 127.0.0.1。
现象：重启后配置丢失。
处理：持久化 volume 是否挂对；不要把配置只写在容器可写层。
六、稳定运行类
现象：长任务跑到一半卡住。
处理：为模型与工具分别设超时；限制最大步数；对 429 做退避；日志打印每一步 tool 输入输出摘要（注意脱敏）。
现象：内存持续上涨。
处理：限制并发会话；定期回收历史；大文件工具改为流式/摘要，不把整文件塞进上下文。
七、排障最小闭环
- 能否完成一次无工具对话？
- 能否完成一次「安全」工具调用（如获取当前时间）？
- 能否在重启后仍读取同一套配置与记忆？
三步都过，再接业务工具。Hermes 的价值在自托管落地，先稳后强比堆插件更重要。
八、小结
大多数「Hermes 不好用」其实是：Key/网络/模型名/工具权限四类问题。把部署当成工程发布：钉版本、可回滚、有日志、有超时，踩坑会少一半。