Hermes Agent 安装后提示 command not found 怎么解决？

安装完成后 PATH 未重新加载。执行 source ~/.zshrc（zsh）或 source ~/.bashrc（bash）重载环境变量即可。

Hermes Agent 提示 all models failed 怎么办？

API Key 无效或余额不足。执行 hermes config get providers 检查配置，或重新运行 hermes setup 配置向导。

Hermes Agent Windows 如何安装？

Hermes Agent 暂不支持原生 Windows，需先安装 WSL2：以管理员运行 PowerShell，执行 wsl --install，重启后在 Ubuntu 终端中运行安装脚本即可。

Hermes Agent Azure AI Foundry 返回 HTTP 422 错误如何解决？

Azure AI Foundry 端点不支持 stream_options.include_usage 参数。在 config.yaml 中对 Azure 提供商设置 stream_options.include_usage: false，或升级到 v0.9.0 已修复版本。

Hermes Agent 报错大全 · 安装失败/command not found/API错误解决方案

⚙️ 安装报错

错误 hermes: command not found ▼

zsh: command not found: hermes

原因：安装完成后 PATH 环境变量未重新加载，Shell 找不到 hermes 可执行文件。

✅ 解决方案

1重载当前 Shell 的环境变量：

source ~/.zshrc   # zsh 用户
source ~/.bashrc  # bash 用户

2若仍报错，手动检查安装路径是否在 PATH 中：echo $PATH | tr ':' '\n' | grep -i hermes

3找到 hermes 实际位置后手动加入 PATH：export PATH="$HOME/.local/bin:$PATH"

错误安装脚本执行失败 / 无详细日志 ▼

curl: (22) The requested URL returned error: 404
# 或安装中途无提示退出

原因：网络问题、GitHub Raw 访问受限，或安装脚本版本不匹配。

✅ 解决方案

1开启详细日志重新安装：curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --verbose

2若访问 GitHub 受限，可使用代理或镜像后重试。

3或通过 pip 安装：pip install hermes-agent

4如果你是 Windows 用户，先按 WSL2 图文教程完成环境准备：查看详细步骤 →

警告 Permission denied 安装写入失败 ▼

install: cannot create /usr/local/bin/hermes: Permission denied

原因：默认安装目录需要 root 权限，普通用户无法写入。

✅ 解决方案

1指定安装到用户目录（推荐）：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | INSTALL_DIR="$HOME/.local/bin" bash

2或使用 sudo 安装到系统目录：curl -fsSL ... | sudo bash

🔑 API / 模型配置报错

错误 all models failed 所有模型请求失败 ▼

Error: all models failed after 3 attempts
  model: claude-3-5-sonnet → 401 Unauthorized
  model: gpt-4o            → 429 Rate limit exceeded

原因：API Key 无效、余额不足，或触发速率限制。

✅ 解决方案

1检查 API Key 是否正确配置：hermes config get providers

2重新运行配置向导：hermes setup

3429 速率限制时，添加备用提供商实现自动轮换，或等待限制解除。

错误 Azure AI Foundry 自定义端点 HTTP 422 错误（Issue #9705） ▼

HTTP 422 Unprocessable Entity
  stream_options.include_usage: field not supported

原因：Azure AI Foundry MaaS/Serverless 端点不支持 stream_options.include_usage 参数，但 Hermes 默认发送该字段。

✅ 解决方案

1在 config.yaml 中对 Azure 提供商禁用该选项：

providers:
  azure_foundry:
    stream_options:
      include_usage: false

2或升级到已修复此问题的最新版本。

错误自定义提供商无法设置 HTTP Headers，Cloudflare 返回 403（Issue #9721） ▼

HTTP 403 Forbidden (Cloudflare)
  custom provider: headers field ignored

原因：自定义提供商配置中的 headers 字段未被正确传递，导致 Cloudflare 安全验证失败。

✅ 解决方案

1确认 config.yaml 中 headers 写法正确：

custom_providers:
  my_provider:
    base_url: "https://your-endpoint.com"
    headers:
      CF-Access-Client-Id: "your-id"
      CF-Access-Client-Secret: "your-secret"

2该 Bug 已在 v0.9.0 中修复，升级即可解决。

警告 /model 命令提示 model not allowed ▼

Error: model "gpt-4o" not allowed
  agents.defaults.models is set to whitelist mode

原因：配置文件中 agents.defaults.models 启用了白名单，当前模型不在列表内。

✅ 解决方案

1查看当前白名单：hermes config get agents.defaults.models

2清除白名单限制：hermes config set agents.defaults.models []

警告 hermes doctor 未能检测到 KIMI API Key（Issue #9716） ▼

doctor: KIMI_CN_API_KEY — not detected (probe failed)
# 但实际已配置

原因：hermes doctor 的探针未包含 KIMI_CN_API_KEY 的识别逻辑，误报为未配置。

✅ 解决方案

1忽略该 doctor 警告，直接验证 Kimi 模型是否可用：hermes chat --model kimi "你好"

2此问题是误报，已提交修复，等待下一版本更新。

💬 消息平台接入报错

错误钉钉 Adapter 启动异常 / 无响应（Issue #9714） ▼

DingTalk adapter: async process startup failed
  dingtalk-stream >= 0.20 incompatible

原因：dingtalk-stream 库 0.20 及以上版本存在异步进程启动兼容性问题。

✅ 解决方案

1降级 dingtalk-stream 到兼容版本：pip install "dingtalk-stream<0.20"

2或等待官方修复，关注 Issue #9714 进展。

错误 Telegram 网络闪断后无法重连 ▼

Telegram: connection lost
  retrying... failed to re-establish long polling

原因：Telegram adapter 在瞬时网络故障后未能自动恢复 long polling 连接。

✅ 解决方案

1切换为 Webhook 模式（更稳定）：

hermes config set telegram.mode webhook
hermes config set telegram.webhook_url "https://your-domain.com/webhook"

2或手动重启 Hermes 服务恢复连接：hermes restart

警告飞书 / 微信会话缺少 source_tag 字段（Issue #9718） ▼

KeyError: 'source_tag'
  session state database missing field

原因：从旧版本升级后，状态数据库中的会话记录缺少新增的 source_tag 字段。

✅ 解决方案

1清空旧会话状态，重新初始化：hermes sessions clear

2若不想丢失历史记录，可手动迁移数据库，具体参考 GitHub Issue #9718。

🏃 运行时报错

错误网关报告未运行，但进程实际存在（Issue #9720） ▼

gateway: not running
# 但 ps aux | grep hermes 显示进程存在

原因：Docker 环境中 ps eww -ax 命令执行失败，导致 gateway 状态检测误报为未运行。

✅ 解决方案

1使用 --deep 参数做更精确的状态检测：hermes status --deep

2直接探测 gateway 健康接口确认实际状态：hermes gateway probe

错误 Cron 任务无法使用外部记忆提供商（Issue #9710） ▼

cron job: memory provider ignored
  skip_memory=True hardcoded in cron executor

原因：Cron 任务执行器中 skip_memory=True 被硬编码，导致 mem0 等外部记忆提供商完全失效。

✅ 解决方案

1此为已知 Bug（#9710），当前无配置层面绕过方案。

2临时方案：将需要记忆的任务改为手动触发而非 Cron，等待官方修复。

警告 config.yaml 根级参数被忽略（Issue #9635 / #9636） ▼

# config.yaml 中的根级配置不生效：
prefill_messages_file: ./prompts.txt
personality: assistant

原因：CLI 的 _ensure_runtime_credentials() 会覆盖部分根级参数，且自定义 personality 在根级定义时被运行时忽略。

✅ 解决方案

1将参数移入对应 agent 的配置块下：

agents:
  default:
    prefill_messages_file: ./prompts.txt
    personality: assistant

警告 Dashboard Config 页面 fallback_providers 显示为 [object Object]（Issue #9726） ▼

Dashboard → Config → fallback_providers: [object Object]

原因：Dashboard 前端对 fallback_providers 对象类型的渲染存在 Bug，显示异常但不影响实际功能。

✅ 解决方案

1此为纯显示问题，功能不受影响，可忽略。

2通过 CLI 查看实际配置：hermes config get fallback_providers

🐳 Docker 部署报错

错误 Docker Sandbox 容器崩溃 / --init 不支持（Issue #9730） ▼

docker: Error response from daemon:
  unknown flag: --init
sandbox container crashed on startup

原因：宿主机的 Docker 版本过旧，不支持 --init 标志；或宿主机内核限制了该能力。

✅ 解决方案

1升级 Docker 到最新稳定版本（≥ 20.10）：docker --version # 检查当前版本

2或在 Hermes 配置中禁用 sandbox init 进程：hermes config set sandbox.use_init false

警告 Docker 容器内 HEALTHCHECK 始终报 unhealthy ▼

hermes-gateway  | health check failing: mode not detected
STATUS: unhealthy

原因：Docker HEALTHCHECK 未区分 gateway 和 dashboard 运行模式，导致单模式部署时探针误判。

✅ 解决方案

1手动探测确认服务实际状态：docker exec hermes-gateway hermes gateway probe

2在 docker-compose.yml 中临时禁用 HEALTHCHECK：

healthcheck:
  disable: true

🩺 快速诊断命令

🔍 遇到问题时，按顺序运行以下命令收集信息

hermes status查看各组件运行状态

hermes status --all查看所有服务详情

hermes doctor自动检测配置和环境问题

hermes gateway probe探测 Gateway 连通性

hermes logs --follow实时查看运行日志

hermes config get查看当前全量配置

hermes status --deep深度状态检测（Gateway 可达时）

🔧 Hermes Agent 常见报错

🔍 遇到问题时，按顺序运行以下命令收集信息