OpenClaw

OpenClaw: Fixes

This is the sixth of eight OpenClaw pages. It covers the problems people hit most often, from a failed install to a job that will not stop. Each one is written as the symptom, the likely cause, and the fix.

These fixes match OpenClaw's docs as of 14 November 2026, for version 2026.11.3. When you are not sure what is wrong, openclaw doctor is the first command to try, because it checks the setup and reports what it finds.

If you used the longer & "$env:APPDATA\npm\openclaw.cmd" line during install, use it in place of openclaw here too.

Install fails, or `openclaw` is not recognized

Symptom. The install script stops with an error, or openclaw --version says the command is not recognized or not found.

Likely cause. Usually the terminal was opened before the install finished setting things up, so it cannot find the new program yet. The other common causes are a missing or too-old Node.js and, on Windows, PowerShell's script setting. GitHub issues have also reported Windows installs where the program landed in a folder PowerShell was not looking in.

Fix. Close the terminal, open a new one, and run openclaw --version again. If PowerShell says running scripts is disabled, use the openclaw.cmd line from Install and first job instead of changing the setting.

If it still fails, check which Node.js you have.

node -v

OpenClaw needs Node 24.16.0 or newer on the 24 line, or Node 26.1.0 or newer. Its docs recommend 26.12.1 or 24.22.1 or newer for security. Node 22, 23, and 25 do not work. If OpenClaw asks Update NodeJS: Y/N [N]:, typing Y downloads a matching Node.js for OpenClaw alone, without replacing the one on your computer.

To install Node.js yourself on Windows, paste this into PowerShell.

winget install OpenJS.NodeJS.LTS

On a Mac with Homebrew, paste this into Terminal.

brew install node

If the command is still not found after a new terminal, run npm prefix -g, which prints a folder. On Windows, the docs say to add that folder to your PATH under Settings → System → Environment Variables, then open a new terminal.

The chat page will not open

Symptom. openclaw dashboard opens nothing useful, or the page says it cannot connect.

Likely cause. The Gateway is not running, or something else is already using its port, 18789.

Fix. Check the Gateway first:

openclaw gateway status

A healthy Gateway shows Runtime: running. If it is not running, use openclaw gateway start. If it was never installed, use the two lines from step 3 of Install and first job. If the logs mention EADDRINUSE or another Gateway already listening, a second copy is holding the port, so run openclaw gateway restart. To watch what the Gateway is doing, run openclaw logs --follow, and press Ctrl+C to stop watching.

On Windows, if OpenClaw could not set up its startup task, the Gateway starts only after you log in.

The model says your key is wrong or missing

Symptom. Replies fail with a message such as No API key found for provider "google", or with another error about the key or about signing in.

Likely cause. The key was pasted wrongly, was deleted in Google AI Studio, or was never saved where the Gateway can read it.

Fix. Create a new key in Google AI Studio, then run the Google key setup again.

openclaw models auth login --provider google

Running Gemini key setup again switches the main model back to google/gemini-4-argon, which is not free. Afterward, run the two model-switch lines from step 4 of Install and first job. To check which models and keys OpenClaw can use, run openclaw models status.

Replies stop because of a rate limit

Symptom. The agent stalls partway through a job, and the error mentions 429, a rate limit, or exhausted resources.

Likely cause. You have used up the free Gemini allowance for now. Google does not publish how much free use you get.

Fix. Wait and try again later, and break big jobs into smaller ones. OpenClaw puts a rate-limited key into a short cooldown, and openclaw models status --json lists keys it is skipping under auth.unusableProfiles. If you move to a paid key instead, set a spend limit on the provider's website before you paste it.

"Unknown model" or "not allowed"

Symptom. You see Unknown model: …, or a message ending in is not allowed by agents.defaults.modelPolicy.allow, and then no reply.

Likely cause. The model name has a typo, your OpenClaw version does not know that model yet, or a list of allowed models leaves it out. A model your key cannot use, such as the paid default on a free key, also fails. This guide could not confirm the exact error Google returns for it.

Fix. List the models your key can reach, and copy the name exactly.

openclaw models list --provider google

Then run the model-switch lines from Install and first job again with that name. For the "not allowed" message, the docs say to pick a model from /model list in the chat, or add the model to that allowed list.

The agent loops or repeats itself

Symptom. The agent runs the same step again and again without getting anywhere.

Likely cause. The model is stuck. OpenClaw always blocks an action after three identical errors in a row and gives the model one chance to change course. Its wider loop detection is off by default.

Fix. Press Stop, type /new to start a fresh chat, and send a smaller job with one finished file and one place to save it. If loops keep happening, especially with a small or local model, turn on loop detection, which OpenClaw's docs recommend for smaller models. In the chat page, it is under Settings → Agent Defaults → Tools. You can also paste these two lines.

openclaw config set tools.loopDetection.enabled true
openclaw gateway restart

This guide built the first line from the documented config set command and the setting name tools.loopDetection.enabled.

How to stop it right now

Symptom. The agent is doing something you did not ask for, and you want it to stop at once.

Likely cause. It does not matter yet. Stop first and find out why afterward.

Fix. Click Stop in the chat page. You can also type /stop, or just stop, which ends the whole chat's current run and drops the messages queued behind it.

To stop everything, including schedules and chat apps, stop the Gateway in your terminal.

openclaw gateway stop

Nothing runs until you start it again with openclaw gateway start. OpenClaw's docs say a program the agent started in the background keeps running after /stop. This guide could not confirm that stopping the Gateway ends it, so if you asked for one, restart your computer to be sure.

After it does something wrong, follow After it does something wrong once the agent is stopped.

It runs commands without asking, or waits on one

Symptom. Commands run with no approval request. Or a job sits waiting, and the line Approval required. shows up in the logs.

Likely cause. For the first, tools.exec.mode is back on full. This guide could not confirm whether running setup again changes it. For the second, the agent is waiting for your answer to an approval request.

Fix. Check the setting:

openclaw exec-policy show

If it does not say ask, run openclaw config set tools.exec.mode ask and then openclaw gateway restart. For a waiting command, read the request in the chat page and answer it. OpenClaw's troubleshooting page says a waiting command can also be answered with /approve in the chat. Deny anything that mentions delete, move, your user folder, Documents, Desktop, email, or a browser login.

A scheduled job did not run

Symptom. The morning file or price line never appeared.

Likely cause. The computer was asleep or off, or the Gateway was not running. Or the job needed a command and nobody was there to approve it, so OpenClaw refused it.

Fix. Check the scheduler and the job's recent runs.

openclaw automations status
openclaw automations list

A healthy scheduler shows it is enabled, with a next wake time. Then run openclaw automations runs <jobId> --limit 20 with the job's ID to see each run. If the logs say cron: scheduler disabled; jobs will not run automatically, the scheduler has been turned off. Rewrite a job that keeps getting refused so it only writes files in the workspace.

Update it safely

Symptom. You want a newer OpenClaw, and you want your settings, memory, and workspace to stay.

Likely cause. None. This is housekeeping. Do these three steps in order.

Fix.

Copy your .openclaw folder before you update, because it holds the settings, the memory, and the workspace. On Windows the folder is C:\Users\YourName\.openclaw, and on a Mac it is ~/.openclaw inside your home folder. The file openclaw.json holds settings, credentials holds chat-app tokens and provider state, workspace holds memory, and agents holds model keys and chat history. A copy can live in File History or Previous Versions on Windows, or in Time Machine on a Mac. Then run the backup command below, which writes a checked archive of that same folder. Keep the Backups folder private, because the archive can hold your keys.

On Windows, in PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\Backups\openclaw"
openclaw backup create --output "$env:USERPROFILE\Backups\openclaw" --verify

On a Mac:

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify

What you should see the command finishes without an error, and a new archive file appears in that Backups folder.

Read the notes on the OpenClaw releases page before you update. This guide could not confirm that a past update resets a named safety setting, so read any note about settings before you continue. Preview the update first. Run the real update only when the preview names a version you expect. Leave automatic updates off for this step. They are a separate choice, covered under the trade-off below.

openclaw update --dry-run
openclaw update

What you should see the preview names your installed version and the target version, and the real update then finishes.

Check the version, then send one small job in the chat page. If that page is closed, run openclaw dashboard first.

openclaw --version

Send this in the chat:

Write a file named update-check.txt in your workspace with the single word ok. Do not run commands, do not open a website, and do not delete anything.

What you should see the command prints a version number, and update-check.txt in the workspace contains the word ok.

OpenClaw can install updates by itself when the Gateway runs as a background service. The switch is update.auto.enabled, and it stays off unless you turn it on under Settings → Updates. On the stable and beta channels, an update waits for active work first, then restarts the Gateway after a 15-minute limit even if a job is still running. The extended-stable channel never applies an update by itself.

Automatic updates.

You gain: newer stable or beta releases install on their own, so you do not have to run the update command.
You risk: an update can land before you read the release notes or make a backup, and it can interrupt a job after 15 minutes.
Makes sense when: backups already run regularly, you stay on the stable channel, and no job runs unattended for long stretches.

Uninstall or reset it cleanly

Symptom. You want a fresh start, or you want OpenClaw gone.

Likely cause. None. This is housekeeping.

Fix. For a small reset, type /new for a fresh chat, and delete any memory lines you do not want, as on Files, the browser, and memory.

To remove OpenClaw completely, first copy anything you want to keep out of the workspace, because a full uninstall deletes it. Then preview what will go.

openclaw uninstall --dry-run --all

When the list looks right, run openclaw uninstall --all, which removes the Gateway service, its settings and keys, the workspace, and the app. A plain openclaw uninstall asks first and only selects the Gateway service unless you pick more. Then remove the program itself.

npm rm -g openclaw

Open a new terminal to check that it is gone. On Windows, Get-Command openclaw -ErrorAction SilentlyContinue should print nothing, and on a Mac, command -v openclaw should print nothing. If you are finished with your Gemini key, delete it in Google AI Studio too.

If the program is already gone but the Gateway keeps running, remove the service by hand. On Windows:

schtasks /Delete /F /TN "OpenClaw Gateway"
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd" -ErrorAction SilentlyContinue
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.vbs" -ErrorAction SilentlyContinue