【Hermes Agent 从入门到精通】第 35 篇：FAQ 与常见问题排查

本系列定位：零基础入门，从安装配置到高级架构全覆盖。无论你是开发者、运维工程师、还是技术爱好者，本系列带你彻底掌握 Hermes Agent。

---

本篇你将学到

• 最常见的问题与解决方案
• hermes doctor 诊断指南
• 按问题类型分类的排查流程

学完本篇，你将能快速解决使用 Hermes 过程中遇到的绝大多数问题。

---

一、安装问题

Q1：hermes: command not found

# 检查 PATH
echo $PATH | grep hermes

# 手动添加
echo 'export PATH="$HOME/.hermes/venv/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Q2：Python 版本太低

python3 --version    # 必须 ≥ 3.10

# 升级 Python
sudo apt install python3.12    # Ubuntu
brew install python@3.12       # macOS

Q3：安装脚本下载失败

# 使用代理
export http_proxy=http://your-proxy:port
export https_proxy=http://your-proxy:port
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

---

下面是安装问题的排查流程图：

二、模型/Provider 问题

Q4：模型不回复 / 报错 401

# 检查 API Key
hermes config env-path     # 查看 .env 路径
cat ~/.hermes/.env | grep API_KEY

# 重新配置
hermes setup

Q5：hermes doctor 显示 Provider 错误

hermes doctor
# 如果显示 API Key 缺失 → 写入 .env
# 如果显示网络错误 → 检查代理/防火墙
# 如果显示 Token 无效 → 重新生成 API Key

Q6：Copilot 403 错误

# gh auth login 的 Token 不能用于 Copilot API
# 必须用 Copilot 专用 OAuth：
hermes model    # 选择 GitHub Copilot → 走 OAuth 设备码流程

Q7：凭证池耗尽

hermes auth list              # 查看状态
hermes auth reset openrouter  # 重置已恢复的 Key

---

三、工具问题

Q8：工具不生效

# 检查工具集状态
hermes tools list

# 启用
hermes tools enable browser

# 重要：工具修改需要新会话才生效
# 在会话中执行：
/reset

Q9：浏览器工具报错

# 检查浏览器后端
hermes config get terminal.backend

# browser 工具需要额外的依赖
# 确保 Chromium 或 Browserbase 已配置

Q10：MCP 工具不显示

# 测试 MCP 连接
hermes mcp test NAME

# 重新加载 MCP
/reload-mcp

# 新会话生效
/reset

---

四、网关问题

Q11：Telegram Bot 不回复

# 检查网关状态
hermes gateway status

# 检查日志
grep "error\|failed" ~/.hermes/logs/gateway.log | tail -10

# 检查 Token
hermes config check

# 重启
hermes gateway restart

Q12：Discord Bot 沉默

检查 Discord Developer Portal：
  Bot → Privileged Gateway Intents → MESSAGE CONTENT INTENT 必须开启！

Q13：Slack Bot 只在 DM 中工作

Slack App → Event Subscriptions → 必须订阅 message.channels 事件

Q14：网关在 SSH 断开后停止

# 启用 linger
sudo loginctl enable-linger $USER

# 验证
loginctl show-user $USER | grep Linger

Q15：WSL2 关闭后网关停止

# 启用 systemd
sudo tee /etc/wsl.conf <<EOF
[boot]
systemd=true
EOF

wsl --shutdown
wsl

Q16：网关崩溃循环

hermes gateway stop
systemctl --user reset-failed hermes-gateway
hermes doctor --fix
hermes gateway start

---

五、技能问题

Q17：技能不显示

# 检查安装
hermes skills list

# 检查平台启用
hermes skills config

# 手动加载
/skill name

# 重新扫描
/reload-skills

Q18：技能加载后不生效

# 技能修改需要新会话
/reset

# 或手动加载
/skill name

---

六、Windows 特殊问题

Q19：Alt+Enter 不能换行

Windows Terminal 拦截了 Alt+Enter（用于全屏切换）
→ 使用 Ctrl+Enter 替代

Q20：config.yaml 编码错误（HTTP 400）

# Windows 记事本保存的文件可能有 BOM
# 用 hermes config edit 编辑（自动无 BOM）
hermes config edit

Q21：execute_code 报 WinError 10106

沙箱子进程缺少 SYSTEMROOT 环境变量
→ 确保 Hermes 版本最新（已修复）
→ 或在 execute_code 中 echo %SYSTEMROOT% 验证

---

七、性能问题

Q22：Hermes 运行变慢

# 检查磁盘占用
du -sh ~/.hermes/*/

# 清理
hermes sessions prune --older-than 30
ls -dt ~/.hermes/state-snapshots/*/ | tail -n +3 | xargs rm -rf

# 检查记忆容量
cat ~/.hermes/memories/MEMORY.md | wc -c
# 如果接近 2200 → 精简记忆

Q23：Token 消耗过高

# 查看用量
hermes insights --days 7

# 优化：
# 1. 日常用便宜模型
hermes config set model.default deepseek/deepseek-chat

# 2. 更积极压缩上下文
hermes config set compression.threshold 0.40

# 3. 禁用不常用的工具
hermes tools disable image_gen

---

八、万能排查流程

遇到任何问题时，按此顺序排查：

---

模块七总结

恭喜完成实战场景与运维模块！

篇	主题	核心收获
31	软件开发实战	全流程编程搭档（编码/调试/审查/Git）
32	DevOps 运维	监控/日志/容器/数据库/CI-CD
33	安全配置	审批模式/密钥脱敏/容器隔离/生产清单
34	性能调优	磁盘清理/Session 维护/Token 优化
35	FAQ 排查	常见问题分类索引/万能排查流程

---

下篇预告

附录 A：CLI 命令完整速查手册

全部 hermes CLI 命令和 Slash 命令的分类速查表。

---

如果本篇内容对你有帮助，欢迎点赞收藏！有任何疑问，欢迎在评论区交流。