Common OpenClaw issues, fixed and documented

Symptom

The QR code displays in terminal but scanning it with WhatsApp gives 'Not Valid' or the connection drops immediately.

Cause

Baileys session mismatch — your local auth_info_multi folder is out of sync with WhatsApp's servers.

Fix — step by step

1. 1Stop OpenClaw completely (Ctrl+C or kill the process).
2. 2Delete the auth_info_multi folder in your project root.
3. 3Run openclaw start so a fresh QR can generate.
4. 4Scan within 60 seconds before it expires.
5. 5Avoid switching networks or devices mid-scan.

Symptom

OpenClaw refuses to start with an error like: 'engine node: wanted >=18.0.0, got 16.x.x' or a similar version mismatch.

Cause

OpenClaw requires a newer Node.js runtime than the system package manager installed by default.

Fix — step by step

1. 1Run node --version to confirm your current runtime.
2. 2Install nvm from the official install script.
3. 3Run nvm install 20 && nvm use 20.
4. 4Set your shell profile to use the right version automatically.
5. 5Retry openclaw start after reopening the terminal.

Symptom

Agent starts but all responses fail with '401 Unauthorized' or 'invalid_api_key' errors in the logs.

Cause

The API key is set under the wrong environment variable, contains hidden whitespace, or was revoked by the provider.

Fix — step by step

1. 1Check the .env file for the exact provider variable name.
2. 2Paste the key into a plain text editor to remove hidden whitespace.
3. 3Confirm the key is still active in the provider dashboard.
4. 4Verify the .env file sits in the project root.
5. 5Restart OpenClaw fully because .env changes do not hot-reload.

Symptom

OpenClaw starts, logs 'Loading skills...' and then crashes immediately with a module error or syntax failure.

Cause

A skill dependency is broken, a package was installed under the wrong Node.js version, or the skill code is not compatible with the running runtime.

Fix — step by step

1. 1Set LOG_LEVEL=debug and reproduce the crash.
2. 2Identify the last skill name logged before exit.
3. 3Open that skill folder and reinstall its dependencies.
4. 4Remove and reinstall the skill if the crash persists.
5. 5Run openclaw doctor to catch any other dependency mismatches.

Symptom

After deploying to a VPS, OpenClaw fails with 'EADDRINUSE: address already in use :::3000'.

Cause

A previous OpenClaw process is still running or another service already owns the configured port.

Fix — step by step

1. 1Run lsof -i :3000 to find the process using the port.
2. 2Stop or kill the old process cleanly.
3. 3Change the configured port if another service should keep using 3000.
4. 4Delete stale PM2 processes if you use PM2.
5. 5Restart with the updated port and verify the reverse proxy target.

Symptom

The agent seems to forget everything after a restart and MEMORY.md updates do not stick.

Cause

The memory path resolves to the wrong directory or the process does not have permission to write to the expected file.

Fix — step by step

1. 1Confirm MEMORY_PATH points to the intended absolute location.
2. 2Check the file permissions in the project directory.
3. 3Fix ownership and write permissions if needed.
4. 4Restart the process under the same deploy user.
5. 5Add a fact, restart, and verify that the fact still exists.