Hermes Agent常用指令速查表与高频问题排查指南
刚接触Hermes Agent，发现命令记不全、参数总输错、报错信息看不懂？问题多半不在配置，而是缺一份基于真实场景的指令速查和故障排查手册。下面这份指南，专为帮你快速上手而设计。
启动与基础会话
先讲最常用的操作。直接输入 【hermes】，这是启动交互式终端的标准方法，也是最稳妥的入口。它会自动加载当前配置、恢复上下文，并进入一个带历史回溯功能的 TUI 界面，日常使用基本靠它。
如果只想快速问一个问题然后结束，可以用 【hermes chat -q "你的问题"】。比如查询天气：hermes chat -q "今天北京天气怎么样"。这种模式特别适合写到脚本里，或者通过定时任务触发，无需一直保持对话。
会话意外中断了怎么办？运行 【hermes --continue】 或简写为 hermes -c。它会自动定位到你最近一次未完成的 session，不是靠时间戳去猜，而是直接读取 ~/.hermes/state/last_session_id 这个文件，精准又可靠。
有一个细节值得留意：clear 是终端自身的清屏命令，不是 Hermes 的子命令。在交互界面里敲 clear，只会清空屏幕显示，不会重置会话。要想清空上下文，需要输入斜杠指令 /clear。
模型切换与配置管理
临时换模型？方法一：用 hermes chat -q "hello" --model anthropic/claude-3.5-sonnet。这种方式只对本次对话生效，不改任何配置文件，适合快速对比不同模型的输出风格。
方法二：永久设为默认模型。执行 hermes config set model.default deepseek/deepseek-v3，这条命令会写入 ~/.hermes/config.yaml，下次启动即生效。需要特别注意的是，如果填错了模型 ID，后续所有 hermes 命令都会卡住，一直等到超时。这时候只能手动编辑 config.yaml，删除出错的配置行，或者改回一个可用的值。
方法三：直接打开配置文件手动修改。输入 hermes config edit，它会调用系统默认编辑器（通常是 nano）。修改保存后，无需重启 Hermes，新配置会在下一次请求时自动生效。
高频报错一键修复
① 【hermes: command not found】
这通常不是没装上，而是 shell 没刷新 PATH。Mac/Linux 用户执行 source ~/.zshrc（zsh）或 source ~/.bashrc（bash）；Windows PowerShell 用户先运行 $PROFILE 确认路径，再执行 . $PROFILE 即可。
② 【AuthenticationError: Invalid API key】
先确认 key 是否复制完整——比如 Kimi 的 key 以 sk- 开头，共 48 位字符。再检查是否写到了正确的字段：hermes config set KIMI_CN_API_KEY your_key_here。注意，漏掉 _CN_ 或误写成 KIMI_API_KEY，都会导致验证失败。
③ 【RateLimitError: Too many requests】
立刻停手，等 60 秒。不要连续用 hermes chat -q 测试，Hermes 默认启用了请求节流保护，连续触发会锁死当前 session 长达 3 分钟。如果只是为了调试，可以改用 hermes --yolo chat -q 来绕过节流，但注意，这只适用于开发测试，绝不能用于生产环境。
④ 【Cannot connect to Docker daemon】
这表示你启用了 Docker 后端，但 Docker Desktop 没有运行，或者在 Linux 上当前用户没有被加入 docker 组。执行 sudo usermod -aG docker $USER，然后完全退出终端重新登录——只执行 source 是没用的。
诊断与状态检查
第一步，确认版本和环境是否就绪：hermes --version && hermes doctor。前者验证 CLI 可正常调用，后者则检查 Python 版本、依赖完整性、API key 可读性以及网络连通性，一共四项硬指标。
第二步，排查配置有没有被意外覆盖：hermes config show | grep -E "(model|provider|key)"。重点关注 model.default、model.provider 以及对应 key 字段是否为空，或者拼写是否有误。空值会导致所有请求 fallback 到无效的默认值，这种情况很容易被忽略。
第三步，抓取一段便于分享的诊断快照：hermes dump --show-keys=false。它会生成一份不含敏感信息的 JSON 摘要，内容涵盖操作系统、Python 版本、Hermes 版本、已启用的插件以及网关状态等。如果遇到问题需要向社区求助，这份摘要会非常实用。