OpenClaw Troubleshooting Guides

Fixes for the most common OpenClaw errors and issues, from install failures to control-panel problems.

• OpenClaw 2026.8.1 to 2026.9.2 Upgrade Crash Loop: The Fix OrderTwelve upgrade reports were filed against OpenClaw 2026.8.1 and against the 2026.9.1 to 2026.9.2 path between August 31 and September 7, 2026. This page groups them by symptom, quotes the command each reporter used, and gives the order that avoids discovering the blockers one restart at a time.
• Hermes Install Fails on Ubuntu 24.04: The Fix OrderThree open Ubuntu reports (issues 88529, 89343, 87460) describe silent install.sh failures. The fixes: install the official prerequisites plus libatomic1 before the script, give the Chrome for Testing download real time, then hermes doctor.
• Hermes Agent Memory Not Working: What Breaks ItFour documented reasons Hermes Agent memory looks broken: the frozen snapshot loaded at session start, the 2,200 and 1,375 character limits, issue 85622 where an external provider suppresses the built-in files, and two agents sharing one home directory.
• Hermes Agent Not Responding on Telegram: 4 FixesFour documented reasons a Hermes Agent goes silent on Telegram: a stopped gateway, an authorization gap, a model under the 64K context floor (issue 24140), and a model retired by the provider, plus the stuck typing indicator that only looks like a hang (issue 28004).
• Hermes Gateway Keeps Restarting: 3 Measured CausesThree documented reasons a Hermes Agent gateway restarts, with the commands that confirm each: gateway memory growth (issue 58817), dashboard OOM on 1 GB servers (issue 14898), and disk growth from updates (issue 58172).
• How to Fix "Hermes backend exited before it became ready"The number in the brackets decides everything. Zero means a healthy backend shut itself down, usually a Windows watchdog misfire, and any other number means it genuinely failed, usually an update applied while Hermes was still running.
• How to Fix "Timed out connecting to Hermes backend after 15000ms"The 15000ms timeout is a single slow answer from a healthy local backend, not a broken agent or a bad API key. Running the terminal version once warms the cache and clears it in most cases, and the underlying stall was repaired upstream in release v2026.7.1.
• How to Fix "Could not connect to Hermes gateway"Two separate parts of Hermes are both called the gateway, which is why the obvious command does not help. The desktop needs the backend server on port 9119, and the fastest test is to start it by hand and let the app attach to it.
• OpenClaw Gateway Token Missing or Unauthorized? Read the Detail Code FirstOpenClaw returns one of five auth detail codes when a gateway connection is refused, and each one needs a different fix. This guide maps AUTH_TOKEN_MISSING, AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH, AUTH_SCOPE_MISMATCH and PAIRING_REQUIRED to the exact commands that clear them.
• OpenClaw stops responding when the Mac mini goes to sleepA Mac mini running an always-on agent has two separate problems, and fixing only the obvious one leaves you with an agent that still goes quiet. Sleep is the first. The second is that a LaunchAgent needs a logged-in user.
• OpenClaw stuck on starting, or the gateway will not come upA gateway that hangs on starting is nearly always failing for a reason it already wrote to the logs. Read the logs first, because the five causes below have five different fixes and guessing between them wastes the most time.
• OpenClaw error: openclaw: command not foundIn almost every case the install worked and the binary exists. Your shell simply does not have the global npm bin directory on its PATH, which is a two-line fix once you know which shell file to edit.
• OpenClaw error: RangeError, maximum call stack size exceededUnlike most errors, this one is usually not your configuration. It has been reported and fixed three separate times in OpenClaw for three different reasons, so the first thing to establish is which version you are running.
• OpenClaw and Ollama: error, unknown command "launch" for "ollama"This error is not a bug and not a version problem. The command does not exist, because the relationship runs the other way around: OpenClaw calls Ollama as a model provider, Ollama never launches OpenClaw.
• OpenClaw error: API rate limit reached, please try again laterThe single most useful thing to know about this error is that OpenClaw did not produce it. It is relaying a 429 from whichever model provider it was calling, so the fix is on the provider side or in how hard OpenClaw is hitting it.
• Where is the OpenClaw config file, and how do you change its location?The short answer is ~/.openclaw/openclaw.json, written in JSON5. The longer answer matters when your edits appear to be ignored, which is almost always a second config file or an environment variable winning over the one you edited.
• OpenClaw error: gateway connect failed, pairing requiredThis error means the gateway is running and reachable, but it does not trust the client that just connected. Nothing is broken. The device simply has no approved identity yet, and there are four different reasons that can happen.