常见错误

在使用 Hermes Agent 的过程中，你可能会遇到一些常见错误。本页整理了最常见的错误及其解决方案，帮助你快速定位和修复问题。

command not found: hermes

症状： 在终端输入 hermes 命令后提示命令未找到。

原因： 安装完成后 Shell 环境变量未刷新，或 PATH 配置有误。

解决方案：

# 方法 1：重新加载 Shell 配置
source ~/.bashrc      # Bash 用户
source ~/.zshrc       # Zsh 用户

# 方法 2：如果方法 1 无效，重新打开终端窗口

# 方法 3：检查 hermes 是否在 PATH 中
which hermes
# 如果找不到，手动添加：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

提示

如果你使用的是 pip 安装方式，hermes 可能在 ~/.local/bin/ 目录下。确保该路径已添加到 PATH 中。

API key 未设置或无效

症状： 运行 hermes chat 后提示 LLM 连接失败，或报 401 Unauthorized 错误。

原因： API Key 未配置、已过期或输入有误。

解决方案：

# 方法 1：使用交互式配置向导
hermes model

# 方法 2：手动编辑配置文件
# 打开 ~/.hermes/config.yaml，确认以下字段正确：

llm:
  provider: openrouter
  model: anthropic/claude-sonnet-4-20250514
  api_key: sk-or-v1-xxxxx    # 确认 Key 正确且有效

# 方法 3：使用环境变量（适合 Docker 部署）
export LLM_API_KEY=sk-or-v1-xxxxx

警告

不要将 API Key 硬编码在公开的配置文件中。推荐使用环境变量或 ~/.hermes/.env 文件。

配置文件丢失或损坏

症状： 启动时报配置文件读取错误，或行为异常。

原因： ~/.hermes/config.yaml 文件被误删、格式错误或编码损坏。

解决方案：

# 方法 1：重置配置为默认值（保留记忆和技能）
hermes config reset

# 方法 2：手动重建最小配置
mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml << 'EOF'
llm:
  provider: openrouter
  model: anthropic/claude-sonnet-4-20250514
  api_key: ${LLM_API_KEY}
EOF

# 方法 3：使用 doctor 诊断
hermes doctor

端口冲突

症状： 启动网关服务时提示端口已被占用。

原因： 另一个 Hermes Agent 实例或其他服务占用了同一端口。

解决方案：

# 查找占用端口的进程
lsof -i :8080          # macOS / Linux
netstat -ano | grep 8080   # Windows

# 终止占用进程
kill -9 <PID>          # macOS / Linux

# 或者修改 Hermes 使用的端口
# 在 ~/.hermes/config.yaml 中修改：

gateway:
  port: 8081    # 换一个未被占用的端口

注意

如果你同时运行了 WebUI 和消息网关，它们默认使用不同的端口。确保两者没有冲突。

ModuleNotFoundError

症状： 启动时提示找不到某个 Python 模块。

原因： Python 依赖包缺失或虚拟环境损坏。

解决方案：

# 方法 1：重新安装 Hermes Agent
pip install --force-reinstall hermes-agent

# 方法 2：如果是源码安装，重新安装依赖
cd ~/.hermes-agent
pip install -r requirements.txt

# 方法 3：确保使用正确的虚拟环境
source ~/.hermes-agent/.venv/bin/activate

Permission denied

症状： 读写 ~/.hermes/ 目录时提示权限不足。

原因： 目录所有者不正确，可能之前用 sudo 运行过 Hermes。

解决方案：

# 修复目录所有权
sudo chown -R $(whoami):$(whoami) ~/.hermes

# 验证权限
ls -la ~/.hermes/

警告

永远不要用 sudo 运行 Hermes Agent。这会导致配置文件和目录的所有权变为 root，后续正常用户无法读写。

Agent 无响应或挂起

症状： 发送消息后 Agent 长时间没有回复。

原因： 网络连接问题、LLM API 超时、代理配置不正确。

解决方案：

# 1. 检查网络连通性
curl -I https://openrouter.ai/api/v1/models

# 2. 如果使用代理，确保配置正确
export HTTPS_PROXY=http://127.0.0.1:7890

# 3. 尝试切换到其他 LLM 提供商
hermes model    # 选择一个国内可达的提供商，如 DeepSeek 或 Kimi

# 4. 按 Ctrl+C 中断当前请求，重新发送

Rate limit exceeded

症状： 频繁收到 429 速率限制错误。

原因： API 请求频率超过了提供商的限制。

解决方案：

# 1. 等待 60 秒后重试

# 2. 在配置中设置自动重试

~/.hermes/config.yaml

llm:
  provider: openrouter
  model: anthropic/claude-sonnet-4-20250514
  retry:
    max_retries: 3
    retry_delay: 5

# 3. 升级 API 套餐或切换到更高限额的提供商
# 4. 使用 OpenRouter 作为中间层，自动路由和重试

中文输出乱码

症状： 终端显示中文内容时出现乱码。

原因： 终端编码设置不正确。

解决方案：

# 设置终端编码为 UTF-8
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# Windows 用户：在 PowerShell 中
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

提示

推荐使用 Windows Terminal、iTerm2 或其他现代终端模拟器，它们原生支持 UTF-8 编码。

记忆不持久

症状： 重启后 Agent 忘记之前的对话内容和偏好。

原因： 多个实例同时写入 ~/.hermes/ 目录，或数据目录未正确挂载（Docker 场景）。

解决方案：

# 1. 确保只有一个 Hermes Agent 实例在使用 ~/.hermes/
hermes session list
hermes session kill --all    # 清理残留会话

# 2. Docker 用户：确认数据卷挂载正确
docker run -v /path/to/hermes-data:/root/.hermes ...

# 3. 检查记忆文件是否存在
ls ~/.hermes/memory/

通用排查流程

遇到问题时，按以下顺序尝试：

1. 运行 hermes doctor — 自动诊断常见问题
2. 运行 hermes config reset — 重置配置（保留记忆和技能）
3. 运行 hermes cache clear — 清除临时缓存
4. 检查 安装问题 和 模型问题
5. 如需完全重置：

cp -r ~/.hermes ~/.hermes.backup    # 先备份
rm -rf ~/.hermes                      # 清除所有数据
hermes model                          # 重新配置

相关页面

• 安装问题 — 安装过程中的常见问题
• 模型问题 — LLM 提供商相关故障
• 网关问题 — 消息平台连接问题
• hermes doctor 诊断 — 自动诊断工具