先跑一遍快速检查
大多数问题先用这 5 个命令分层：版本、模型、Skills、配置、综合诊断。不要先改一堆配置。
hermes --version
hermes model
hermes skills browse
hermes config check
hermes doctor求助前准备这 4 样
✓ 运行环境和 Hermes 版本
✓ 完整报错或最近 80 行日志
✓ 你执行过的命令
✓ 期望输出和实际输出
Error index
按现象定位问题
安装问题
启动时报依赖错误
检查：node -v / python3 --version / git --version / hermes --version
可能原因：Node、Python、Git 版本不一致，或 PATH 指向了错误环境。
修复方式：先清楚当前终端使用的版本，再重新打开终端验证 Hermes。
模型 API
返回 401、invalid key 或 provider not configured
检查：hermes model / hermes config check / printenv
可能原因：API Key 没加载、环境变量写错、Provider 没选中或当前会话没重启。
修复方式：重新配置模型，退出当前会话后再启动 Hermes。
模型限流
返回 429、timeout 或偶发失败
检查：查看模型平台额度、限速、当前工作流触发频率
可能原因：高频任务集中打到同一个模型，或输入太长导致请求变慢。
修复方式：降低触发频率，给高频任务换低成本模型，长输入先摘要再处理。
模型名称
model not found 或上下文长度不够
检查：hermes model / /model / 当前配置里的 model name
可能原因：模型名拼写不匹配，或选择的模型上下文窗口太短。
修复方式：换成已验证模型名；长文档任务优先选择 64K 以上上下文模型。
Memory
新会话记不住项目偏好
检查：查看 MEMORY.md、USER.md 和外部记忆 Provider 配置
可能原因：记忆没有写入、路径不对、字符预算过大，或外部记忆没有启用。
修复方式：只写高价值稳定事实；把临时任务规则放进 Skill，不要塞进 Memory。
Skills
搜索不到、安装后不生效、触发不稳定
检查：hermes skills browse / hermes skills search <keyword> / /skills
可能原因：Skill 名称不对、会话没有重启，或描述太宽导致触发条件模糊。
修复方式：用明确关键词搜索；安装后重开会话；自定义 Skill 里写清 When to Use。
Gateway
任务执行了但消息平台没有回复
检查：hermes gateway start / hermes doctor / Gateway 日志
可能原因：Bot 权限、Chat ID、允许名单、网络出口或平台限流出问题。
修复方式：先用 /status 测试目标聊天窗口，再逐步接入真实工作流。
权限和路径
无法读取文件、写日志或执行命令
检查：pwd / ls -la / whoami / 日志目录权限
可能原因：运行用户没有权限，工作目录不对，或部署环境路径和本地不同。
修复方式：切到项目目录，用低权限但可读写的运行用户，并固定日志目录。
工作流输出
输出格式经常跑偏
检查：输入样本、Prompt、输出字段、失败样本
可能原因：没有固定 schema，输入缺少兜底，或一个 Prompt 同时做太多事。
修复方式：拆分任务，固定输出字段，失败时进入人工确认。
部署运维
VPS 上偶发断线或任务不再运行
检查：进程状态、重启记录、磁盘、内存、日志轮转
可能原因：没有进程守护、日志爆满、服务重启后环境变量未加载。
修复方式：配置守护进程、日志保留、失败重启和启动后健康检查。
我没有 VPS 也能用 Hermes Agent 吗？+
可以。本地 macOS、Linux 或 WSL2 都能跑。VPS 只是为了 7×24 长期运行定时任务，建议先在本地跑通，再考虑上云。
安装前需要准备什么？+
建议准备 Git、Node.js、Python、一个可用的模型 API Key，以及可以长期运行的终端环境。部署到 VPS 时还需要 SSH 权限和基础安全配置。
必须使用 OpenRouter 吗？+
不必须。OpenRouter 的优点是模型选择多、切换方便。你也可以选择 OpenAI 或其他兼容接口，关键是为不同任务设置合适的模型与预算。
使用 Hermes Agent 的模型 API 一个月大概多少钱？+
取决于模型和调用频率。个人跑 3-5 个常规工作流，大致可能在 ¥30-150；团队频繁运行可能更高。本站不销售任何模型 API。
能接 Telegram、Slack、飞书或企业微信吗？+
可以作为工作流目标，但具体可用性取决于你的机器人权限、消息平台 API 和部署网络环境。模板里会给出通用接入清单。
工作流没有按时执行怎么办？+
先检查服务器时间、cron 或任务调度配置，再看环境变量、网络连接和日志输出。如果依赖消息平台，还要确认机器人权限没有过期。
模型返回质量不稳定怎么办？+
先固定输入格式和输出 schema，再缩小任务范围。复杂任务拆成检索、摘要、判断、生成多个步骤，必要时为高价值步骤切换更强模型。