🚑 疑難排解
依症狀分類的問題排除，對應上游 GitHub issues
Seeing an HTTP 429 error? That's your provider slowing you down — Hermes isn't broken
A 429 means the company that gives you the AI model thinks you're sending requests too fast, so it's blocking you for a moment. This is not a Hermes bug. Hermes retries on its own and switches to a backup automatically, but if the provider keeps blocking you, you need a different move: put in several keys and rotate them, upgrade your plan, or switch providers. Includes real Gemini and z.ai examples.
Seeing "API key not set" or being told your key is invalid? Let's fix it step by step
The most common cause isn't a typo in your key — it's that the key is paired with the wrong provider. Walk through three calm steps, including the easy-to-miss conflicting settings in ~/.hermes/.env.
Typed hermes and got "command not found"? Don't panic—30-second fix
Installed Hermes, typed hermes, and got "command not found"? Nine times out of ten it isn't broken—your window just hasn't re-read its settings yet. Follow along; it takes about 30 seconds.
What to do when you see context length exceeded
Your chat suddenly froze with a context length exceeded message? Rescue the current conversation with one command, then fix your config file so it stops happening. People running local models hit this a lot, and the reason isn't what you'd guess.
Something broke? Check things in this order and you won't waste time
The biggest time-waster is copying an error message into Google and blindly trying random fixes. This teaches you one fixed order: first check the program is even there, then the settings, then whether the model connects, and only last the features. One layer at a time, with a single command to confirm each layer.
What to do when you see "Hermes requires Python 3.11 or newer"
This error usually means you didn't use the official installer. Here are three fixes, plus why some people never hit it.
Two Common Snags When Connecting Telegram to Hermes Agent
A few features go missing from your command menu, and the gateway (the layer that lets your bot send and receive messages) drops offline on its own. Neither is your fault, and both have a fix.