Fix OpenClaw 401 Unauthorized: Invalid API

Getting 401 Unauthorized or incorrect api key provided when connecting to your OpenClaw gateway? This is almost always a token mismatch between your client and the gateway.

Understanding OpenClaw Authentication

OpenClaw uses a gateway token to authenticate API requests. Every request to the gateway must include this token in the x-api-key header or as a Bearer token.

# Check your gateway token
openclaw config get gateway.token

# Or find it in the config file
cat ~/.openclaw/openclaw.json | grep token

Common Causes and Fixes

1. Token Changed After Restart

If you regenerated the token or reinstalled OpenClaw:

# View the current token
openclaw config get gateway.token

# Use this token in your client configuration

2. Environment Variable Override

An environment variable might override the config file:

# Check if OPENCLAW_GATEWAY_TOKEN is set
env | grep OPENCLAW_GATEWAY_TOKEN

# Unset if it has a stale value
unset OPENCLAW_GATEWAY_TOKEN

3. Docker Token Mismatch

In Docker, the token is stored in the volume. If you recreated the volume:

# Check the token inside the container
docker compose exec openclaw cat /home/node/.openclaw/openclaw.json | grep token

# Or set it explicitly via environment
docker compose down
# Add to docker-compose.yml:
# environment:
#   - OPENCLAW_GATEWAY_TOKEN=your-known-token
docker compose up -d

4. Multiple Instances

If you run multiple OpenClaw instances, each has its own token:

# Check which instance you are connecting to
curl -I http://YOUR_IP:18789
# Verify the port matches the instance with your token

5. Incorrect Header Format

The API key must be sent correctly:

# Correct
curl -H "x-api-key: YOUR_TOKEN" http://localhost:18789/v1/models

# Also correct (Bearer format)
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:18789/v1/models

# Wrong (missing header)
curl http://localhost:18789/v1/models

Testing Authentication

# Quick test — should return 200 with model list
TOKEN=$(openclaw config get gateway.token)
curl -s -o /dev/null -w "%{http_code}" \
  -H "x-api-key: $TOKEN" \
  http://localhost:18789/v1/models

Expected: 200

If you get 401, the token does not match. If you get connection refused, the gateway is not running.

Resetting the Token

If you cannot find the correct token:

# Generate a new token
openclaw config set gateway.token "$(openssl rand -hex 32)"
openclaw gateway restart

# Note the new token
openclaw config get gateway.token

Control UI Authentication

The Control UI uses the same gateway token. If the UI shows 401:

Open the Control UI in your browser
It should prompt for the token
Enter the token from openclaw config get gateway.token
If it does not prompt, clear browser cache and cookies for the gateway URL

allowInsecureAuth Setting

For development only, you can disable authentication:

# WARNING: Disables API key requirement — never use in production
openclaw config set gateway.controlui.allowInsecureAuth true
openclaw gateway restart

Frequently Asked Questions

Why do I get 401 Unauthorized in OpenClaw?

A 401 Unauthorized or "incorrect api key provided" error is almost always a gateway token mismatch — the token your client sends does not match the token the gateway expects.

Where do I find my OpenClaw gateway token?

Run openclaw config get gateway.token, or read it from the config file at ~/.openclaw/openclaw.json. Use that exact value in your client.

Why did my token stop working after a restart or reinstall?

Regenerating the token or reinstalling OpenClaw issues a new gateway token. Copy the current token with openclaw config get gateway.token and update every client that connects to the gateway.

Which header does OpenClaw use for the token?

Every request to the gateway must include the token in the x-api-key header (or as a Bearer token). A missing or stale header is a common cause of 401 errors.