Hermes Agent 中文站 Logo

Hermes Agent 中文站

导航

issues

遇到问题LCP

如果 Hermes 没有按预期运行，先从这里按症状分流。这个模块覆盖安装更新、模型 Provider、自定义 endpoint、CLI/TUI、Gateway 推送、Tools/Skills/MCP、Profiles、Docker、Nix、SSH 与远程后端问题。

最后更新：2026-04-28查看 GitHub 原文

01-总览｜卡住了？先定位问题，不要急着重装

一句话结论：这一页不是替你现场修问题，而是先帮你把问题分到正确类别，再跳到对应 FAQ 页；先定位，再排障。

如果你现在已经很焦虑，只先记住一句：

先确认你卡的是安装、模型、CLI / 会话、Gateway、Tools / Skills、配置隔离，还是远程 backend；不要一上来就把所有变量一起改。

🩺 先做一个最小判断

如果 hermes 命令已经能执行，先跑：

hermes doctor

这一步的目的不是立刻修好，而是先回答：

  • Hermes 现在是不是已经至少能启动
  • 当前是不是明显卡在 provider / model / config 这一层
  • 你是在“完全没跑起来”，还是“能跑但某一层异常”

如果你连 hermes 都执行不了，就不要先查模型、Gateway 或 MCP，先从安装 / 环境问题开始。

⚡ 快速定位：先看你的问题

如果你不想从头往下读，先按你眼前最像的现象直接跳：

🚫 命令起不来 / 更新后命令异常

🔐 Key / 模型 / endpoint 不对

⌨️ CLI / TUI / 会话不对劲

📩 平台接好了但消息不通

🧰 工具 / Skills / MCP 不工作

⚙️ 配置改了但环境像没变

🐳 Docker / SSH / 远程环境边界混乱

🔄 从 OpenClaw 过来后卡住

🚦 如果你现在只想快速选一条排障路

直接按当前状态走：

建议排障顺序

  • 先查：🚫 命令起不来 / 更新后命令异常
  • 再查：🔐 Key / 模型 / endpoint 不对
  • 然后查：⌨️ CLI / TUI / 会话不对劲
  • 再查：📩 Gateway / Messaging
  • 最后再进入：🧰 Tools / Skills / MCP、⚙️ 配置隔离、🐳 远程 backend

🔢 更稳的排障顺序

不要同时改 5 件事。更稳的顺序通常是：

  1. 先确认 hermes 命令能不能正常运行
  2. 再确认 provider / model / endpoint 是否可用
  3. 再确认 CLI / TUI / session 是否正常
  4. 再确认 Gateway / Messaging 是否可用
  5. 最后再查 tools / skills / MCP / 远程后端

这样排的原因很简单：

  • 如果基础 chat 都没跑通，后面的异常大多是连带问题
  • 如果模型层没通，工具层和入口层的报错通常没有参考价值
  • 如果你还没分清是配置问题还是能力问题，越改越乱的概率很高

🚫 先不要做的 4 件事

在官方文档和官方 Issues 没证明之前，先不要：

  • 一上来就删目录重装
  • 把第三方博客里的野路子命令直接贴进去跑
  • 把 API Key、token、完整 .env 贴到公开 issue
  • 把“国内环境补充问题”误当成 Hermes 官方 bug 结论

尤其是这两类情况，不要误判：

  1. 中国环境里的网络 / 中转 API / 回调问题
  2. OpenAI-compatible 接口“能聊天但不完整支持 tools / system role / function calling”

它们都很常见，但不一定是 Hermes 核心逻辑出了问题。

🏷️ 如果你怀疑这是官方已知问题

可以先按官方 GitHub labels 去搜，而不是直接提新 issue。

优先关注这些分类：

  • area/config
  • area/docker
  • area/nix
  • backend/docker
  • backend/ssh
  • backend/local
  • comp/cli
  • comp/tui
  • comp/gateway
  • comp/tools
  • comp/agent
  • needs-repro
  • needs-triage
  • P0 / P1 / P2 / P3

如果你要搜问题，优先用这种组合方式：

comp/cli hermes --continue
comp/gateway telegram status
area/config profile session
backend/docker terminal.backend docker

官方入口：

🇨🇳 中国环境补充说明

下面这些问题在中文环境里特别常见，但它们属于“补充排查”，不是自动等同于官方结论：

  • 安装脚本下载失败，先查网络和代理
  • 自定义 endpoint 的 /v1 缺失或重复
  • OpenAI-compatible 接口能聊天但 tools 不稳定
  • Windows 用户把 WSL2、PowerShell、原生路径混在一起
  • 阿里云 / 腾讯云安全组、端口或反向代理没放通
  • 飞书 / 企业微信 / 钉钉的 token、callback、权限没配齐

如果你是在国内环境里落地，不要把这些混成 Hermes 本身的单一 bug，先回 03-国内落地 / 01-总览 把部署、模型、入口三层重新拆开。

✅ 看完这页你应该能立刻判断什么

看完这一页，你应该能直接回答这 4 个问题：

  1. 我的问题是在“命令都跑不起来”，还是“能跑但某一层异常”？
  2. 我现在更像卡在安装、模型、CLI / TUI、Gateway，还是 Tools / Skills / 配置 / 远程 backend？
  3. 我应该先回哪条已落地页面，而不是盲目继续折腾？
  4. 我现在该先看官方文档，还是先去官方 Issues 搜 label？

如果这 4 个判断还是不清楚，先不要自己扩散排查范围，再跑一次 hermes doctor，然后回到上面的快速定位重新判断。

➡️ 下一步

完成后进入：

如果你想先回到上一阶段入口重新确认位置：

🔗 相关排查入口

如果当前页没有命中症状，先回到遇到问题总入口重新按问题类型分流。

上一篇

从 OpenClaw 过来

帮助 OpenClaw 用户判断继续用、共存还是迁移到 Hermes。

下一篇

安装 / 更新 / 环境问题

一句话结论：这一页只处理“命令起不来、装不上、更新后变怪、环境边界混乱”这类问题。只要你还没确认 hermes 命令本身是否正常，就先不要跳去查模型、Gateway、Tools。