OpenClaw Troubleshooting Guides

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

• 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.