19 个
长尾问题入口
覆盖安装、模型、Skills、Gateway、部署和资源领取。
6 类
排查阶段
先定位问题归属，再进入对应教程和最小复现。
3 分钟
缩小范围
每个问题都给出常见现象、第一步检查和下一步动作。
先按搜索词判断入口
不要在一个报错里同时改模型、配置、Gateway 和工作流。先锁定现象，再按对应页面做最小复现。下面这些就是用户最容易直接搜索的词。
hermes command not foundOpenRouter model not foundHermes Agent Gateway 不回复Hermes Agent Memory vs SkillsHermes Agent Windows WSL2 安装Hermes Agent VPS 部署失败
Hermes Agent 安装失败
安装失败、命令找不到或 setup 卡住
先确认终端、PATH、Git、curl、Python、Node 和系统路线，再检查 Provider。
hermes command not found
命令找不到、PATH 没生效
确认安装环境、shell 配置、PATH 和 WSL2 / PowerShell 是否混用。
Hermes Agent Windows WSL2 安装
Windows、Linux、macOS 怎么选安装路线
Windows 新手优先 WSL2，macOS 和 Linux 先确认 shell、Node、Python、Git 和权限。
hermes setup 没有 Provider configured
setup 输出缺 Provider、Memory 或 Skills 信号
跑完 setup 后不要只看是否报错，要逐项确认 Provider、Memory、Skills 和 Gateway。
OpenRouter model not found
OpenRouter 报 model not found
从模型名、Provider、API Key、环境变量和会话重启逐项排查。
OpenRouter 401 / 429
API Key 失效、额度不足或限流
401 先查 Key 和 Provider，429 先查额度、限速和工作流触发频率。
Hermes Agent OpenRouter 配置
Provider 和模型路由怎么配置
先用一个确认可用的模型跑短问答，再处理路由、备用模型和工作流模板。
hermes skills install
Skills 安装命令和使用顺序
先 browse 和 search，再 install；会话内安装用 /skills install，后续用 update。
Skills 装完不生效
Skill 不触发、搜索不到或输出不稳定
检查 Skill 目录、会话重启、When to Use 和低风险测试样例。
Hermes Agent Memory 不生效
Memory 没记住项目规则或偏好
先区分稳定事实、临时上下文和可复用流程，避免把所有信息都塞进 Memory。
Hermes Agent Gateway 不回复
Gateway 不回复或消息平台无响应
先分清消息有没有进入 Hermes，再看模型调用和后台日志。
Gateway Token / Chat ID
Token、允许名单或 Chat ID 配错
Token 有效不代表 Gateway 可用，还要确认回调、群 ID、允许名单和进程配置。
Hermes Agent Telegram 不回复
Telegram 机器人能收到消息但没有回复
先查 Bot Token、Chat ID、允许名单和 Gateway 进程，再回到 CLI 做同输入复现。
Hermes Agent 飞书 企业微信接入
飞书、企业微信接入先做测试群
企业消息入口先做只读提醒和测试群，不要第一天就接生产群和高权限动作。
Memory vs Skills
Memory 和 Skills 到底怎么分工
Memory 记录稳定事实和偏好，Skills 沉淀可复用步骤和工具调用。
Hermes Agent 日报工作流怎么跑
日报、RSS 摘要或 Issue 分类先跑只读模板
第一个工作流建议从只读日报开始，用固定输入、固定输出和日志验证稳定性。
Hermes Agent VPS 部署失败
本地能跑，部署到 VPS 后失败
VPS 问题先查环境变量、Node/Python 版本、后台进程、日志和定时任务。
Hermes Agent 成本日志怎么记录
模型成本、失败次数和人工修改怎么留痕
长期运行前先记录调用次数、模型成本、失败原因和人工修改点。
Hermes Agent 免费资源包
Starter 包怎么领、下载后先看哪里
免费资源包不用填表，夸克和百度网盘都能下载，适合新手先跑第一个低风险模板。
按阶段排查
先判断问题属于哪一层
大部分报错都能归到环境、模型、Skills / Memory、消息入口或部署运行。先选层级，排查会快很多。
安装环境
4 个入口模型接入
3 个入口Skills / Memory
4 个入口消息入口
4 个入口工作流运行
3 个入口资源上手
1 个入口1安装环境
Hermes Agent 安装失败
常见现象
hermes: command not found、setup 不继续、依赖缺失、Windows 路径混乱。
先检查
新开终端后运行 which hermes、git --version、python3 --version、node --version。
进入教程2安装环境
hermes command not found
常见现象
安装后输入 hermes 仍然提示 command not found。
先检查
运行 echo $SHELL、which hermes、printf '%s\n' "$PATH"。
进入教程3安装环境
Hermes Agent Windows WSL2 安装
常见现象
Windows 路径混乱、PowerShell 和 WSL2 混用、macOS 权限或 Linux 依赖缺失。
先检查
先确认当前终端是哪套环境，再运行 node --version、python3 --version、git --version。
进入教程4安装环境
hermes setup 没有 Provider configured
常见现象
setup 能跑完，但没有 Provider configured、Memory enabled 或 Skills directory ready。
先检查
保存完整 setup 输出，再对照 Provider、Memory、Skills directory 和 Messaging gateway 四个信号。
进入教程5模型接入
OpenRouter model not found
常见现象
模型列表里能看到，但运行工作流或 Gateway 时提示 model not found。
先检查
先运行 hermes model、hermes model list、hermes config check、hermes doctor。
进入教程6模型接入
OpenRouter 401 / 429
常见现象
返回 invalid key、unauthorized、rate limit、timeout 或频繁失败。
先检查
运行 hermes model、hermes config check，并用短问答测试 Provider。
进入教程7模型接入
Hermes Agent OpenRouter 配置
常见现象
模型 Key 已经填了，但工作流仍然超时、报错或无法调用目标模型。
先检查
先运行 hermes model、hermes config check，并用同一个模型完成一句短问答。
进入教程8Skills / Memory
hermes skills install
常见现象
不知道该装哪个 Skill，或者装完后不清楚怎么验证。
先检查
先运行 hermes skills browse，再用 hermes skills search 搜具体能力。
进入教程9Skills / Memory
Skills 装完不生效
常见现象
安装后会话里不触发，或者每次都需要额外解释。
先检查
运行 hermes skills browse、hermes skills search <keyword>，再重启会话。
进入教程10Skills / Memory
Hermes Agent Memory 不生效
常见现象
明明告诉过 Agent 项目规则，下次生成内容时仍然忘记或前后不一致。
先检查
先确认这是长期稳定规则，还是只在当前任务里临时有效的上下文。
进入教程11消息入口
Hermes Agent Gateway 不回复
常见现象
Telegram、飞书、企业微信等消息平台能发消息，但 Agent 没有回复。
先检查
先看 Token、允许名单、Chat ID、gateway status 和最近日志。
进入教程12消息入口
Gateway Token / Chat ID
常见现象
机器人在群里，但 /status、短问答或日报任务没有回复。
先检查
检查 Token、Webhook、允许名单、Chat ID、群 ID 和 gateway status。
进入教程13消息入口
Hermes Agent Telegram 不回复
常见现象
Telegram 群里能发命令，但 Agent 没有回应，或只在某个群不回复。
先检查
确认机器人在正确群里、Chat ID 没填错、触发用户在允许名单里。
进入教程14消息入口
Hermes Agent 飞书 企业微信接入
常见现象
机器人加进群后没有回复，或消息推到了错误群、错误频道。
先检查
确认 Webhook、签名密钥、群 ID、应用权限和回调地址是否一致。
进入教程15Skills / Memory
Memory vs Skills
常见现象
不知道该把项目规则写进 Memory，还是把流程做成 Skill。
先检查
问自己：这是稳定事实，还是可重复执行的方法？
进入教程16工作流运行
Hermes Agent 日报工作流怎么跑
常见现象
想做自动日报，但输入源太多、输出格式不稳定，跑一次就不知道怎么验收。
先检查
先只选 1 到 2 个输入源，固定输出字段，不要一开始就接正式推送。
进入教程17工作流运行
Hermes Agent VPS 部署失败
常见现象
本地跑通了，上服务器后找不到命令、Key 没加载、定时任务不执行或日志为空。
先检查
在 VPS 上运行 printenv、node --version、python3 --version、which hermes，并查看最近日志。
进入教程18工作流运行
Hermes Agent 成本日志怎么记录
常见现象
工作流能跑，但不知道一个月花多少钱，也不知道失败主要发生在哪里。
先检查
先记录日期、任务、模型、输入长度、成功状态、错误原因和人工修改。
进入教程19资源上手
Hermes Agent 免费资源包
常见现象
想找中文模板、排错清单和 Starter 包，但不知道下载后从哪一步开始。
先检查
先打开免费资源包页，选择一个网盘下载，再看 Starter 使用说明。
进入教程恢复路线
排查完以后，用 Starter 包跑一次最小闭环
报错修好不等于工作流稳定。建议再用免费 Starter 包里的日报、Issue 分类或内容选题模板跑一次，确认输入、输出和日志都可复现。