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