OpenClaw 401 is usually one of three different failures: invalid bearer token, missing authentication header, or a single agent with no credentials. Match the exact message before you rotate any key, token, or header setting.
The safest first move is to repair the failing branch on the same agent, verify that exact path, and only then decide whether the host should keep the same authentication method. If the same branch still fails after that first repair, treat it as a header-routing or version-sensitive problem instead of retrying random credentials. On an always-on gateway host, the long-term default should usually be the most predictable auth route, not the most convenient one.
30-Second Route Board
Route the error before you change anything:
| If the log says... | Likely failing part | Safest first move | Verify on the same path | Escalate when |
|---|---|---|---|---|
invalid bearer token | A token-backed auth route that is stale, revoked, overridden, or fragile on the current build | Re-authenticate that exact route first | Re-run the same agent after re-auth or after switching to a known-good API key path | The same branch still fails after a clean re-auth |
missing authentication header | Request routing, provider config, or a build-specific regression | Check which layer is building the outgoing request before you rotate credentials | Confirm whether the retried request now carries usable auth | A known-good credential still produces the same missing-header branch |
| One agent works but another reports 401 or "no credentials" | The failing agent itself | Add or refresh credentials on the failing agent | Re-test that agent, not the one that already worked | The agent still resolves to an empty or unusable profile |
This split is not a theory exercise. Current OpenClaw docs still document multiple Anthropic auth routes, including API key, Claude CLI reuse, and setup-token reuse. They also say auth state is agent-specific. Public runtime evidence shows the 401 family splits too: issue #23538 documents invalid bearer token on OpenClaw 2026.2.21-2, while issue #34830 records a separate 401 missing authentication header regression on OpenClaw 2026.3.2.
So the first question is not "which credential should I change?" It is "which exact branch am I in?" If you skip that step, it is easy to destroy a working setup while trying to fix a different failure.
If the Error Says Invalid Bearer Token
An invalid bearer token branch usually means the request did send a credential, but the upstream service could not use it. On current OpenClaw builds, that most often matters when the host is using Claude-login reuse, Claude CLI reuse, or setup-token reuse instead of a direct Anthropic API key.
The safest first move is re-authentication, not configuration surgery. The current OpenClaw Anthropic provider docs still treat 401 errors / token suddenly invalid as a live troubleshooting branch. Claude Help adds an important detail: ANTHROPIC_API_KEY overrides subscription-style auth in Claude Code. That means a machine can look logged in while requests are still leaving through a different auth path than the one you think is active.
A stored token is not final proof that runtime auth is healthy. In issue #23538, setup-token auth was accepted and stored, but Anthropic requests still failed at runtime with HTTP 401 authentication_error: Invalid bearer token on OpenClaw 2026.2.21-2. That does not make setup-token universally broken. It does mean "the onboarding flow succeeded" is not enough evidence to keep using that route unchanged on a long-lived host.
Use this recovery order:
- Re-run the exact token or setup-token flow you expect the host to use.
- Remove stale Claude or Claude Code sessions if they may still be taking precedence. Claude's session management docs explain where those tokens can be revoked.
- Check whether
ANTHROPIC_API_KEYis overriding the subscription-style path you thought was active. - Re-test the same agent and the same host path after re-authentication, not a different machine that happens to work.
If the same branch keeps failing after a clean re-auth, treat that as a host choice problem, not only a token problem. On an always-on gateway host, the current OpenClaw authentication guide points toward the most predictable method. In practice that usually means moving away from fragile token reuse and toward a direct API key. If your failure is clearly Anthropic-token specific and you need deeper follow-up, the dedicated guide to OpenClaw Anthropic API key errors goes deeper into that route.
If the Error Says Missing Authentication Header
A missing-header branch is easy to misread because it still looks like a 401. But it usually means the request never carried usable auth at all. That is a different repair path from invalid bearer token, where a credential was sent and rejected.
Public issue #34830 matters here because it shows 401 missing authentication header on a later OpenClaw build even when the reporter believed the key itself was correct. If your error says the header is missing, start by checking which layer owns the outgoing request and whether that layer ever had credentials to send. Do not revoke a working token first and hope the environment rebuilds itself into the right route.
The minimum safe sequence is short:
- Confirm which provider path or agent produced the failing request.
- Inspect the active config or environment that should be injecting auth for that path.
- Retry with a known-good credential and see whether the request now carries auth at all.
If the request still drops the header with a known-good key, stop treating it as ordinary credential drift. At that point you are in config, request-routing, or version-sensitive territory, and the wrong fix is to keep rotating secrets.
If One Agent Works and Another Has No Credentials
This branch is different again. Current OpenClaw docs and CLI reference put auth profiles under agent-specific paths such as ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. In plain language, each agent needs its own credentials. A healthy main agent does not prove a new or different agent inherited anything useful.
That is why this branch should be repaired at the failing agent, not at the host that already works. Compare the failing agent's auth state with the healthy one, add or refresh credentials on the failing agent, and then re-test that same agent. When people skip that step and re-run a full onboarding flow against the whole host, they often end up changing the one thing that was not broken.
This is also the point where complexity starts working against you. A host that mixes local sign-in reuse, per-agent profiles, and environment overrides can be made to work, but it is much harder to debug when only one branch breaks. If the gateway is supposed to stay online and predictable, simpler routing usually wins over clever routing.
Which Auth Method Should Stay on This Host
Once service is back, the real question is not "which method worked once?" It is "which method is least likely to fail again on this host?"
Current OpenClaw guidance is unusually clear on this split. The gateway authentication docs say API keys are usually the most predictable option for always-on gateway hosts. The Anthropic provider docs still support Claude CLI reuse and setup-token reuse, but the OpenClaw FAQ is stricter about the environment contract: local Claude-login reuse is supported, but it is not recommended for production. The FAQ also records an Anthropic notice dated April 4, 2026 that the OpenClaw Claude-login path requires Extra Usage billed separately from the subscription.
That leads to a practical rule:
| Environment | Better default to keep | Why |
|---|---|---|
| Always-on server or shared gateway host | Direct API key | Fewer moving parts, less dependence on user-session state, and easier long-term debugging |
| Personal machine you control directly | Claude CLI or subscription-linked auth can be reasonable | Convenience may outweigh the coupling when the machine and user session are both local |
| Setup-token reuse on any host | Supported, but version-sensitive | Current docs still support it, but public issue evidence means it should not be treated as the safest universal default |
The goal is not to defend one authentication method forever. The goal is to match the method to the host you actually run. If the gateway is supposed to stay up, survive reboots, or serve more than one user path, predictability matters more than convenience. If the machine is local and disposable, a local sign-in route may still be fine.
Verify the Fix Before You Move On
Once the immediate outage is fixed, a short verification routine prevents most repeat failures:
- Re-test the same agent that failed. Do not declare success just because another profile works.
- Confirm the active auth route you expect is actually the one in use.
- Remove or revoke stale token methods that should no longer take precedence.
- If you changed auth methods, document the new default for that host so the old route does not silently return later.
This is also where cooldown and unusable-profile states matter. The current Anthropic provider docs say No available auth profile (all in cooldown/unavailable) should be checked with openclaw models status --json. That is not the same branch as invalid bearer token, and it is not the same branch as missing authentication header. If you collapse those states into one generic auth story, you will keep fixing the wrong layer.
The escalation rule is simple:
- If re-authentication fixes
invalid bearer token, decide whether the same host should keep that auth route at all. - If
missing authentication headerpersists with a known-good key, stay focused on routing or version-sensitive behavior rather than token rotation. - If one agent still works while another fails, repair the failing agent first.
- If the problem expands beyond the 401 family, jump to the broader OpenClaw error troubleshooting guide or the installation and deployment guide.
FAQ
Does every OpenClaw 401 mean my API key is wrong?
No. Current public evidence shows at least three different 401 classes worth separating: invalid bearer token, missing authentication header, and one-agent credential gaps.
Is setup-token still supported?
Yes. Current OpenClaw docs still document setup-token as a supported Anthropic auth path. But as of April 7, 2026, public issue #23538 also shows a version-specific runtime invalid bearer token regression on OpenClaw 2026.2.21-2, so setup-token should be treated as supported but version-sensitive.
Why does one agent work while another fails?
Because current OpenClaw docs make auth storage agent-specific. A healthy main agent does not prove a new or different agent inherited the same credentials.
What is the safest long-term authentication method for a server?
For an always-on gateway host, current OpenClaw guidance points to the most predictable route. In practice that usually means preferring a direct API key over session- or token-reuse paths.
The Working Rule
An OpenClaw 401 gets easier to fix when you stop asking "which credential should I change?" and start asking "which exact branch failed?" Match the message, apply the smallest fix to that branch, verify it on the same path, and only then decide which authentication method the host should keep. That keeps a narrow 401 outage from turning into a bigger self-inflicted auth mess.