# Fix OpenClaw 401 Errors: Invalid Bearer Token and Missing Auth Header

> For an OpenClaw 401, first identify who rejected the request. An invalid provider token, a missing outgoing auth header, and a Gateway or device-token mismatch require different fixes. Check the failing agent and session before replacing credentials.

- URL: https://blog.laozhang.ai/en/posts/openclaw-401-authentication-error
- Published: 2026-04-07
- Updated: 2026-10-04
- Author: LaoZhang AI Team (https://blog.laozhang.ai/en/about)
- Category: AI Troubleshooting
- Tags: OpenClaw, 401 Error, Authentication, Anthropic, AI Troubleshooting

---
To fix an OpenClaw 401, first identify **which connection failed**. If a model-provider response says `invalid bearer token`, inspect the credential selected for that model. If it says `missing authentication header`, check whether the outgoing provider route resolved and attached authentication. If the Control UI cannot connect and reports `AUTH_TOKEN_MISMATCH` or a pairing code, repair Gateway/client authentication.

Start on the machine running the Gateway, under the same user account as its service. Check the failing agent with `openclaw models status --agent <agentId>` and, for an existing chat, run `/model status` in that chat. The CLI checks the agent's configured model routes; it does **not** show a chat-session override. A working default agent or a successful login on your laptop does not establish that the failing session has usable authentication. [OpenClaw's models CLI reference](https://docs.openclaw.ai/cli/models) explains this distinction.

This guide follows the documentation checked on October 4, 2026. The commands are documented recovery procedures; we have not reproduced a provider 401 or tested a live model call for this update.

## Match the error to the connection that failed

![OpenClaw error-routing illustration for invalid bearer tokens, missing authentication headers, and missing credentials](https://blog.laozhang.ai/posts/en/openclaw-401-authentication-error/img/triage-map.webp)

Use the exact error and the process that emitted it together. Follow the current commands in the sections below rather than treating every authentication message as a reason to reset the host.

| Symptom | What to inspect first | First recovery action |
|---|---|---|
| `Failed to authenticate. API Error: 401 Invalid bearer token` or a provider `authentication_error` | Selected provider, runtime, account/profile, and token health | Renew the affected managed login or key; for native Claude CLI, repair Claude Code's login |
| `401 Missing Authentication header` or `Error generating, error: Error: Missing Authentication header` | Provider endpoint, auth source, service environment, and agent/session selection | Restore credential resolution or correct the outgoing route; investigate version behavior if usable credentials still produce the error |
| `No API key found for provider "anthropic"` or no usable profile on one agent | Shared credentials, an agent-local override, and profile order | Repair the affected override or configure usable credentials for that route |
| Control UI disconnected with `AUTH_TOKEN_MISSING`, `AUTH_TOKEN_MISMATCH`, or device/pairing details | Failed Gateway `connect` response | Update the client credential or repair device approval as the detail code requires |
| `No available auth profile (all in cooldown)` | First provider failure and `auth.unusableProfiles` | Resolve its recorded cause; an auth failure and a quota cooldown are different branches |

A Gateway shared token connects a client to OpenClaw. A provider API key or provider token authenticates model access. A channel token authenticates a messaging integration. Changing one does not repair rejection of another.

Before making changes, capture the OpenClaw version, failing agent ID, selected model/runtime, exact error, and when it began. Keep secrets out of the record. These checks establish the local starting point:

```bash
openclaw --version
openclaw gateway status
openclaw doctor

# Replace research with the agent that actually failed.
AGENT_ID=research
openclaw models status --agent "$AGENT_ID"
```

Read `doctor` findings before choosing a repair. The command without `--fix` is the diagnostic starting point; the migration and update repairs below change stored state.

## If the error says “Invalid bearer token”

A provider's `invalid bearer token` response points to a credential that it could not accept. The message alone does not tell you whether that credential is expired, revoked, from the wrong account, or selected through a stale override. First establish whether the selected Anthropic route uses the direct API, an OpenClaw-managed token profile, or native Claude CLI.

### Repair native Claude CLI authentication in Claude Code

For a native Claude CLI route, run these commands **as the Gateway user on the Gateway host**:

```bash
claude auth status --text
```

If that login is missing, expired, or cannot refresh, authenticate again and restart the Gateway:

```bash
claude auth login
openclaw gateway restart
```

Claude Code owns the native login and refresh lifecycle. OpenClaw invokes the installed executable; it does not read, store, refresh, or forward its native login tokens. Do not copy a native OAuth token into an OpenClaw credential file. Check that the service can find `claude` on its `PATH`, and check `CLAUDE_CONFIG_DIR` if the service uses a separate Claude login directory. These are the current [Anthropic provider troubleshooting steps](https://docs.openclaw.ai/providers/anthropic#troubleshooting).

A successful interactive login under a different macOS or Linux user will not repair the service user's native login. Likewise, a Claude CLI model choice does not silently fall back to the direct Anthropic API if the executable cannot run.

### Repair the selected API key or managed token profile

For an API route, inspect the credential source shown by `models status` and the saved profile list for the affected agent. Listing profiles does not print API keys or OAuth secrets:

```bash
AGENT_ID=research
openclaw models auth list --provider anthropic --agent "$AGENT_ID"
openclaw models auth order get --provider anthropic --agent "$AGENT_ID"
```

If the selected API key is revoked or belongs to the wrong account, replace that key through the supported interactive helper:

```bash
openclaw models auth paste-api-key --provider anthropic --agent "$AGENT_ID"
```

For a new Anthropic setup, current provider guidance recommends an API key instead of token auth that expires or can be revoked. An existing managed setup-token route remains documented in the broader [authentication guide](https://docs.openclaw.ai/gateway/authentication) and [OAuth guide](https://docs.openclaw.ai/concepts/oauth). If you intentionally retain that route, renew it through its supported interactive flow:

```bash
openclaw models auth login --provider anthropic --method setup-token --agent "$AGENT_ID"
```

This command requires an interactive terminal. It configures an OpenClaw-managed credential; it is separate from logging the native Claude executable into an account.

Follow the command's application/restart guidance, then verify the same session. Avoid adding `--force` to a generic fix: on the shared-main agent it can clear the provider's shared credentials and local overrides. Removing an OpenClaw profile also does not revoke the underlying credential at the provider. [The auth CLI reference](https://docs.openclaw.ai/cli/models) describes the scope of these mutations.

## If the error says “Missing authentication header”

This error says the receiving endpoint did not get the authentication header it requires. It does not prove your key was rejected. A missing credential, wrong provider configuration, an intermediary that strips headers, or version-specific request handling can produce the same symptom.

Check these conditions in order:

1. **Confirm the session's provider and runtime.** Use `/model status` in the failing chat. A successful test against a different provider or profile cannot validate this request path.
2. **Confirm the Gateway can resolve auth.** Inspect `openclaw models status --agent <agentId>` and the provider's profile order. A saved profile omitted by explicit `auth.order` is not the selected credential.
3. **Confirm the service environment.** A key exported in your shell is not necessarily present in a systemd or launchd service. OpenClaw documents `~/.openclaw/.env` as a daemon-readable location, with restart and status checks after a change. Use the intended provider's key variable on the Gateway host; do not substitute `OPENCLAW_GATEWAY_TOKEN`. [Provider authentication setup](https://docs.openclaw.ai/gateway/authentication) gives the current environment guidance.
4. **Confirm the endpoint and protocol.** Provider connection fields such as `baseUrl`, `api`, model IDs, and headers belong in provider configuration, not in credential rows. A custom proxy's authentication requirements must match the endpoint you actually selected.
5. **If resolved credentials still fail, record the version and routing chain.** Inspect the earliest provider error, not just the final failover summary. Stop repeated key rotation and investigate the request path or a release-specific problem.

Historical OpenRouter reports show why that last branch matters. In [issue #51056](https://github.com/openclaw/openclaw/issues/51056), filed March 20, 2026, a Linux reporter running OpenClaw `2026.3.13` described missing-header failures despite a key that worked outside OpenClaw. In [issue #97934](https://github.com/openclaw/openclaw/issues/97934), filed June 29, a macOS reporter described the same symptom on `2026.6.10` and reported success after returning to `2026.6.1`.

Those are version-bound reports, not evidence that today's release has the same bug. They also do not justify installing that old version over current migrated state. For an intentional rollback, use the official compatibility procedure and a matching verified backup.

## If one agent works and another has no credentials

Current OpenClaw credentials use a **shared read-through base with agent-local overrides**. A new agent can use a usable shared profile without receiving a copied API key. A local profile with the same ID takes precedence over the shared profile, so a stale local credential can explain why one agent fails while another works. [Current Anthropic troubleshooting](https://docs.openclaw.ai/providers/anthropic#troubleshooting) documents this behavior.

Under the default state root, the stores are:

| Store | Default location | Role |
|---|---|---|
| Shared credentials | `~/.openclaw/state/openclaw.sqlite` | Shared auth that agents can read at runtime |
| Agent-local credentials and auth state | `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite` | Local credential overrides, profile order, cooldown, and usage state |

`OPENCLAW_STATE_DIR` changes the roots. Personal Gateway accounts use separate identity-scoped records; they are not ordinary shared profiles. Native Claude CLI login is also outside this shared credential mechanism. [OAuth storage documentation](https://docs.openclaw.ai/concepts/oauth#storage-where-tokens-live) explains the distinctions.

Compare the failing agent's `models status`, saved profile IDs, and provider order with those of the working agent. Then check `/model status` in each relevant chat. Look for a local override, a different account selection, a session pin, or an excluded profile before creating another key.

If the wrong profile is explicitly pinned in the chat, select the intended model/account there. `/new` and `/reset` preserve valid explicit user model/profile pins; they are not guaranteed ways to clear a wrong account selection. If a stale local override appeared after an update, use the documented update repair below. If no usable shared or local credential exists, configure auth on the Gateway host or for the affected agent through the supported helper.

Do not copy OAuth secrets between agents or edit the SQLite database by hand. Read-through lets an agent use shared credentials without cloning them, and shared OAuth refresh writes back to the shared owner.

## If the 401 began after an update or storage migration

Inspect the version, `doctor` findings, and service binary before changing provider credentials. Current [update troubleshooting](https://docs.openclaw.ai/gateway/troubleshooting/updates-and-rollbacks#after-an-update) documents `doctor --fix` as a recovery for stale per-agent OAuth shadows that prevent agents from resolving the current shared profile.

For that documented update problem, or a supported legacy-file migration identified by `doctor`, retain a state/config backup and then run:

```bash
openclaw doctor --fix
openclaw gateway restart
```

Supported legacy files such as `auth-profiles.json`, `auth-state.json`, and per-agent `auth.json` are migration inputs. Runtime no longer uses their credentials. Doctor imports verified values into SQLite and archives the originals. An empty store with unmigrated provider metadata can produce `AUTH_PROFILE_MIGRATION_REQUIRED`; repeatedly editing an old JSON file will not complete that migration.

There is a specific exception: the old shared `credentials/oauth.json` importer is retired. Current documentation says that path needs an intermediate upgrade through `2026.9.5` to import it before installing the latest release. Apply this only when that exact legacy path exists and the diagnostic calls for it; it is not a general downgrade step. See [the storage and migration rules](https://docs.openclaw.ai/concepts/oauth#storage-where-tokens-live).

If a service action is blocked because an older binary is reading newer config, correct the executable/service version or restore a compatible backup with its matching release. Do not delete `meta.lastTouchedVersion` to defeat the newer-config guard.

## If the Control UI or client cannot authenticate

Use `error.details.code` from the failed Gateway `connect` response. These codes describe the client-to-Gateway connection, not an upstream model-provider 401. The current [Gateway auth detail map](https://docs.openclaw.ai/gateway/troubleshooting/agent-replies-and-control-ui#auth-detail-codes-quick-map) gives distinct actions:

| Detail code | Correct recovery |
|---|---|
| `AUTH_TOKEN_MISSING` | Retrieve the shared token on the Gateway host and supply it to the intended client |
| `AUTH_TOKEN_MISMATCH` | Resolve shared-token drift; if the response permits a trusted device-token retry, allow that documented retry before further repair |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Rotate or re-approve the affected device token, then reconnect |
| `AUTH_SCOPE_MISMATCH` | Re-pair or approve the requested role/scopes; rotating the shared token does not grant them |
| `PAIRING_REQUIRED` | Review and approve the pending device request or scope/role upgrade |

For a missing shared token, run this **in an interactive terminal on the Gateway host**:

```bash
openclaw gateway auth-token --show
```

Keep its output local and paste it only into the intended client's connection settings. For a pending device request, review the requested access before approving its actual request ID:

```bash
openclaw devices list
openclaw devices approve <requestId>
```

Reconnecting successfully establishes Gateway access. It does not establish that the selected model provider accepts its own credential. Do not disable Gateway authentication to work around a provider 401.

## Verify the same agent, account, model, and session

![Post-fix illustration emphasizing the same agent, active authentication route, and cooldown state](https://blog.laozhang.ai/posts/en/openclaw-401-authentication-error/img/post-fix-checklist.webp)

After the repair, repeat the agent status check and inspect the original chat with `/model status`. Confirm that its selected runtime/account is the one you repaired, then send one short, ordinary message through that same chat. A reply from the intended route without the original authentication error is the useful success signal. This live request can incur provider usage or charges.

Static checks have a narrower meaning. `openclaw models status --agent <agentId> --check` exits `0` when it finds no configured-route auth/runtime issue or expiring selected credential; that does not prove a model request will succeed. Exit `1` covers missing/expired auth, incompatible routes, unavailable runtimes, and indeterminate readiness. Exit `2` means an otherwise eligible selected credential is expiring. [The status reference](https://docs.openclaw.ai/cli/models) defines these results.

If you deliberately choose a CLI probe instead, `models status --probe` makes real model requests and may consume tokens or trigger rate limits. The current CLI requires exclusive state-directory ownership, so stop the running Gateway first. Use `--agent`, `--probe-provider`, and `--probe-profile` to limit the check to the intended agent/provider/profile. Wait for accepted work and cleanup to finish before restarting the Gateway; an interrupted or timed-out probe does not prove that its state lock and temporary resources have been released. A probe validates its tested candidate; it still does not inspect a chat-session override.

If status reports `No available auth profile (all in cooldown)`, inspect JSON `auth.unusableProfiles` and the first provider failure. A `429` or exhausted quota needs the [OpenClaw rate-limit and cooldown troubleshooting path](https://blog.laozhang.ai/en/posts/openclaw-rate-limit-exceeded-429), while a rejected credential still needs auth recovery. Waiting out a cooldown does not renew a revoked token.

For an unresolved incident, record the OpenClaw version, host/service user, affected agent, provider/model/runtime, selected profile ID, first error, and result of the scoped verification. Redact credentials and private message content. That record distinguishes a still-broken auth path from a different error encountered after authentication recovered.

## Which authentication method should you keep?

For an always-on Gateway, the [OpenClaw authentication guide](https://docs.openclaw.ai/gateway/authentication) recommends an API key as the most predictable choice. It gives explicit usage-based billing and avoids depending on an interactive user's native login. For a personal machine already running Claude Code, native Claude CLI can be a suitable choice when the Gateway runs under that same user and can launch the authenticated executable.

Choose the runtime and account deliberately. An `anthropic/*` model identity can run through either runtime, and a Claude CLI route can use an explicitly selected API account. The provider name or CLI label alone is not a subscription-billing guarantee. Current [Anthropic route documentation](https://docs.openclaw.ai/providers/anthropic) explains this distinction.

Keep an existing managed setup-token route only as an intentional supported configuration. Its availability does not prove entitlement, account capacity, or that a stored token remains valid. Whichever route you choose, record the account/runtime used by the Gateway and verify it after credential or service changes.

## FAQ

### Does every OpenClaw 401 mean my API key is wrong?

No. A provider can reject a credential or receive no authentication header, while the Gateway can separately reject a shared token or device connection. Identify the error's source and selected session route before changing a secret.

### Why does one agent work while another says “No API key found”?

Current agents can read shared auth, but a same-ID local profile overrides the shared credential. Agent order and chat-session selections can also differ. Inspect the failing agent and chat instead of assuming every agent needs a separate key. [Current storage rules](https://docs.openclaw.ai/concepts/oauth#storage-where-tokens-live) describe read-through and local ownership.

### Is Anthropic setup-token still supported?

Yes, the [broader authentication guide](https://docs.openclaw.ai/gateway/authentication) still documents it. The current Anthropic provider page recommends API keys for new setups when token auth expires or is revoked, and documents native Claude CLI as a separate route. Support for a route is not a guarantee of subscription billing.

### Should I downgrade if the error says “Missing authentication header”?

Not from the message alone. Check credential resolution, service environment, provider configuration, and session selection first. Historical reports describe particular releases; a current rollback needs compatibility checks and a backup matched to the intended release, especially after credential storage migration.

### Does a successful status check mean the 401 is fixed?

No. Status without `--probe` is not a model-call test, and agent status does not inspect a chat-session override. Verify one short reply on the same agent, selected account, runtime, and session. A live test may consume paid usage.