claude setup-token: what it authenticates, and why it fails

claude setup-token mints a one-year OAuth token for Claude Code, prints it to your terminal, and saves it nowhere. You paste it into CLAUDE_CODE_OAUTH_TOKEN — or into an agent host that asks for a Claude Code token — and the agent authenticates to Claude as your Claude Code login. That is the whole mechanism. The two failures that account for most of the trouble afterwards are that another credential in the same environment outranks it, or that the token was issued with a narrower scope than the thing you pointed it at. Neither produces a helpful error, and two further causes below are specific to OpenClaw.

What claude setup-token actually mints

Anthropic's Claude Code authentication documentation describes the command in one paragraph, and the details it chooses to state are the ones people trip over. The command exists “for CI pipelines, scripts, or other environments where interactive browser login isn't available”. It opens the same browser authorization flow as /login. The token prints to the terminal, and — in the documentation's words — “it does not save the token anywhere”.

Two consequences follow immediately. Because the command stores nothing, a token you fail to copy is gone and you mint another. And because it “can only make model requests”, it is a narrower credential than an API key by design — a distinction that becomes the whole story below.

Where the token ranks against your other credentials

This is the single most useful fact about claude setup-token and it is published in Anthropic's documentation rather than in any guide about it. When several credentials are present, Claude Code picks one in a fixed order:

Your setup-token is fifth of seven. Anthropic states the interactive case plainly: “If you have an active Claude subscription but also have ANTHROPIC_API_KEY set in your environment, the API key takes precedence once approved.” On a server, in a Dockerfile, or in a CI job, the same rule applies without anybody being there to notice — a key exported months ago in a shell profile quietly shadows the token you just minted, and the symptom is “my setup-token isn't working” when the real symptom is “my setup-token was never consulted”.

Check this before you debug anything else. On the machine that actually runs the agent, confirm that ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and any apiKeyHelper setting are unset. Unsetting them in your interactive shell proves nothing about the environment a service manager hands to the process.

Why claude setup-token returns 401 or gets ignored

Four causes, in the order worth checking them. Only the first is free to rule out.

1. Another credential outranks it

Covered above. No error, no log line, no 401 — the agent simply bills somewhere you did not intend. This one is silent, which is why it belongs first.

2. The token was issued with Claude Code-only scope

In February 2026 the scope the command requests narrowed. The resulting token can be rejected for anything outside Claude Code itself, with a specific and quotable string:

Error: Your OAuth token is restricted to Claude Code and can't be used for external API calls.

That is claude-code issue #23703 , opened 2026-02-06 against Claude Code 2.1.34 and closed as a duplicate. The reporter names the case exactly: “Claude setup-token is now only requesting user interface scope? this is making it impossible to use it for openclaw” — and confirms it as a regression, “this worked in a previous version”. If you see that string, no amount of re-pasting helps; the credential you hold is not the credential you need.

3. Mode and type disagree in OpenClaw's config

OpenClaw records a credential in two places — the profile's declared mode in the gateway config, and the profile's type in the agent's auth profile store. When those disagree, authentication fails with the generic 401 rather than a configuration error. OpenClaw issue #2697 (2026-01-27, v2026.1.24-3) is the worked example: a successful claude login, a profile written as mode: token against an auth profile of type: oauth, a lastGood pointer aimed at a different profile name, and “401 Invalid bearer token” on every request. The fix was to make the two agree and restart the gateway.

4. One bad credential takes the whole provider down

This is the failure that turns a credential problem into an outage. OpenClaw issue #9095 (2026-02-04, v2026.2.2-3) records HTTP 401 authentication_error: Invalid bearer token followed by No available auth profile for anthropic (all in cooldown or unavailable). Once the provider is in cooldown, every Claude variant disappears at once and the fallback chain has nothing to fall back to. If your agent went from “Claude is misbehaving” to “no models at all”, this is the shape — and the recovery is to fix the credential and restart the gateway, not to wait it out.

A related and much older report is worth knowing about if the token is being ignored entirely rather than rejected: claude-code issue #8938 (opened 2025-10-04, still open, labelled area:auth and has repro) records Claude Code 2.0.5 still prompting for theme and authentication method with CLAUDE_CODE_OAUTH_TOKEN exported and local config removed. On an unattended box that prompt is indistinguishable from a hang.

What a setup-token does not buy you

Four limits, three of them documented by Anthropic and one structural.

• It is not a general Anthropic credential. The documentation states it “can only make model requests, so it can't establish Remote Control sessions or fetch claude.ai connectors”. Locally configured MCP servers still work.
• Bare mode does not read it. If a script passes --bare, Anthropic directs you to ANTHROPIC_API_KEY or an apiKeyHelper instead.
• It does not renew. A token credential is stored as a provider and a token value and nothing else — no access/refresh pair, no expiry timestamp. There is no refresh material for a runtime to use, so automatic token refresh does not apply to it. At twelve months it simply stops working and a human re-mints it.
• It does not reliably move your agent's usage onto your Claude plan. The token authenticates and the agent runs, but Anthropic limits Claude subscription use from third-party and hosted clients, so that traffic can draw additional metered usage instead of being absorbed by Pro or Max. This is the one that costs money rather than uptime, because nothing fails when it happens. If you are working out what changed and what your options are, we wrote that up separately in OpenClaw after the Claude subscription cutoff .

We are not the only ones saying this, and it is worth reading in the runtime's own voice rather than a host's: OpenClaw's OAuth documentation concludes that “for Anthropic in production, API key auth is still the safer recommended path”. If you want a subscription route that behaves the way people expect this one to, it is ChatGPT (Codex) rather than Claude — see connecting OpenAI to OpenClaw.

Using a setup-token on a hosted OpenClaw agent

There is a reason hosted users meet this credential's edges before anybody else does. OpenClaw prefers Claude CLI reuse — picking up an existing interactive claude login on the same machine. A headless always-on agent has no interactive login to reuse. The paste-a-token path exists precisely to cover that case, which means every hosted Claude-subscription user is on the narrower credential by construction.

On Lobsterland this is a first-class auth method rather than a workaround. You pick Claude Code Token as the Anthropic auth method in the instance wizard or on the AI Model screen, paste the value the command printed, and the platform writes the credential into the right shape for the runtime you chose: an OpenClaw auth profile of type token, or, for a Hermes instance, the CLAUDE_CODE_OAUTH_TOKEN environment variable with the provider pinned so the runtime selects it. The token our fleet stores for this method is the sk-ant-oat… value the command prints — if what you pasted does not look like that, you copied the wrong line out of the terminal.

One class of failure above is genuinely off the table here. The mode-versus-type disagreement behind issue #2697 comes from two tools writing the same credential differently; our control plane derives both from one code path that refuses to emit a Claude Code credential in any mode other than token, so the pair cannot drift apart. The other three are upstream and stay upstream.

Stop babysitting your OpenClaw box

Fix it once — or stop fixing it for good.

Apply the checklist above and keep self-hosting, or skip the maintenance entirely: run your OpenClaw on managed hosting from $6.90/mo, starting with a 7-day free trial. We handle the stale locks, gateway restarts, version upgrades, and uptime — and you can import your existing instance in a couple of minutes. Cancel anytime.

Managed hosting — from $6.90/mo Your own hosted OpenClaw instance with automatic restarts and version upgrades. Starts with a 7-day free trial — import your current setup, keep your channels, cancel anytime.

$199 managed setup — optional Prefer we do it for you? One workspace configured end-to-end: first-run config, one 30-minute onboarding/debug session, and a 7-day follow-up. Limited weekly slots.

• Managed hosting handles stale .jsonl.lock files, gateway restarts, and version upgrades for you
• Import your existing OpenClaw setup in minutes — keep your channels and configuration
• The optional $199 setup is scoped: no custom development, enterprise/SRE support, or unsupported self-hosting repair

If you would rather compare options first, review OpenClaw cloud hosting or see the best OpenClaw hosting options before deciding.

Run it on managed hosting — from $6.90/mo Prefer we set it up? $199 managed setup Keep self-hosted: work the four causes above

Frequently asked questions

What does claude setup-token do?

It mints a long-lived OAuth token for Claude Code. Anthropic's authentication documentation states the token is valid for one year, that the command opens the same browser authorization flow as /login, that the token prints to the terminal and "does not save the token anywhere", and that it "authenticates with your Claude subscription and requires a Pro, Max, Team, or Enterprise plan". You copy the printed value and set it as the CLAUDE_CODE_OAUTH_TOKEN environment variable, or paste it into whatever tool is asking for a Claude Code token. It is a credential-minting command, not a configuration command: nothing on your machine changes when you run it.

Why does my Claude setup-token return 401 Invalid bearer token?

There are four common causes and they need different fixes. First, precedence: Anthropic documents CLAUDE_CODE_OAUTH_TOKEN as the fifth credential source, below ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY and apiKeyHelper, so a stale API key in the same environment silently wins and your token is never used. Second, scope: since early 2026 the minted token can come back restricted, with the error "Your OAuth token is restricted to Claude Code and can't be used for external API calls" (claude-code issue #23703, opened 2026-02-06 on version 2.1.34). Third, a mode and type mismatch between OpenClaw's config and its auth profile, which produced exactly this 401 in openclaw issue #2697 (2026-01-27, v2026.1.24-3). Fourth, the token expired: a one-year token has no refresh material, so it fails outright rather than renewing.

Does a Claude setup-token let a hosted agent run on my Claude Pro or Max plan?

Do not plan on it. The token authenticates and the agent runs, but Anthropic limits Claude subscription use from third-party and hosted clients, so that traffic can draw additional metered usage instead of being absorbed by your Claude Pro or Max plan. Nothing fails loudly when this happens, which is why it is usually discovered on a bill rather than in a log. For predictable Anthropic costs, use an Anthropic API key. OpenClaw's own documentation reaches the same conclusion: "for Anthropic in production, API key auth is still the safer recommended path". If you specifically want a subscription that behaves as advertised on an agent, the ChatGPT (Codex) route is the one that currently does.

How long does a Claude setup-token last, and does it refresh itself?

One year, and no. Anthropic documents the command as generating a one-year OAuth token. The distinction that matters for an always-on agent is structural: on Lobsterland a setup-token is stored as a token-type auth profile that carries only the provider and the token value, while a full OAuth profile carries an access token, a refresh token and an expiry. A token profile has no refresh material, so there is nothing for the runtime to renew. When it expires, a human runs claude setup-token again and re-pastes the result. Plan the calendar reminder when you create it, not when the agent goes quiet.

What can a Claude setup-token not be used for?

Anthropic's documentation is explicit that the token "can only make model requests, so it can't establish Remote Control sessions or fetch claude.ai connectors", though locally configured MCP servers still work. It is also not read in Claude Code's bare mode, where an ANTHROPIC_API_KEY or an apiKeyHelper is required instead. And since the 2026 scope narrowing it may be issued restricted to Claude Code itself, in which case external API calls are refused outright. Treat it as a subscription-scoped credential for model calls, not as a general-purpose Anthropic key.