skip to content

In OpenClaw, how does an API-key auth profile differ from a subscription token saved with `openclaw models auth setup-token`, and when do you choose each?

level: middleimportance: should knowfreq 7%

answer

  1. three credential shapes
  2. who pays, and from which limit
  3. a token nobody refreshes
  4. OAuth, then token, then API key
  5. secrets in the agent's SQLite store

basics

~20 s

Both are OpenClaw auth profiles. An API key bills the provider account per use; a setup token ties requests to a subscription plan's limits and is a static token that OpenClaw never refreshes. API keys suit shared, predictable automation.

solid answer

~50 s

OpenClaw stores provider credentials as **auth profiles** of three types: `api_key`, `oauth` and `token`. `openclaw models auth setup-token --provider <id>` needs an interactive terminal and runs that provider's token method; for Anthropic you create the token with `claude setup-token` and OpenClaw saves it as a `token` profile. A token is static: OpenClaw does **not** refresh it, so you replace it when it expires. An API key (`openclaw models auth paste-api-key --provider <id>`) uses the provider's pay-as-you-go billing, while subscription usage draws on the plan's usage limits, which the provider can change. The docs recommend an API key for shared automation and predictable spend. With no explicit order, OpenClaw tries OAuth, then token, then API-key profiles, so an API key works naturally as the backup. The secrets live in the agent's SQLite auth store; `auth.profiles` and `auth.order` in config hold only routing metadata.

go deeper

for a junior

Recall that both are auth profiles, that an API key bills per use, and that a setup token draws on a subscription plan's limits.

for a middle

Explain the three profile types, that OpenClaw never refreshes a static token, and that default ordering tries OAuth, then token, then API key.

for a senior

Show how a token plus an API-key backup rotates under a usage-window limit, and how auth.order or a stored order changes the preference.

for a principal

Decide per use case: a personal plan's flat cost and limits against metered, account-owned API billing for shared or scheduled automation.

## What an auth profile is An **auth profile** is one stored credential that OpenClaw can use to call a model provider. Every provider credential is a profile, whether it is an API key or an OAuth login. A profile has an id such as `anthropic:default` or `openai:[email protected]`, and one of three types: | Type | What it holds | Refreshed by OpenClaw? | |---|---|---| | `api_key` | A provider API key | Not needed | | `oauth` | Access and refresh tokens from a sign-in flow | Yes | | `token` | A static bearer-style token, optionally expiring | No | The secret material lives in the per-agent auth store, `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`. The config keys `auth.profiles` and `auth.order` in `openclaw.json` are **metadata and routing only** and contain no secrets. ## The two routes compared **API key.** You paste a key you created in the provider's console: - `openclaw models auth paste-api-key --provider openai` prompts for the key; in automation pipe it on stdin rather than passing it as an argument. - Requests bill the provider account per use. OpenClaw's Anthropic page calls API-key auth preferable for **shared automation and predictable production spend**. **Subscription token.** `openclaw models auth setup-token --provider <id>` requires an interactive terminal (TTY) and runs the provider's token-auth method: - For Anthropic you run `claude setup-token` on any machine with Claude Code installed, then paste the printed token; `openclaw models auth login --provider anthropic --method setup-token` is the same path. - OpenClaw stores it as a `token` profile. It is **never refreshed** by OpenClaw: when it expires, you save a new one. - `openclaw models auth paste-token --provider <id>` stores a token you already have, by default as `<provider>:manual`, and `--expires-in 365d` records an expiry so status can warn before it lapses. - Usage draws on the **subscription plan's usage limits**, and the provider can change how such programmatic use is counted without an OpenClaw release. For Anthropic, OpenClaw also prefers reusing an existing Claude Code login on the same host when one is available; that login stays owned and refreshed by Claude Code, not by OpenClaw. ## How the two work together With no explicit order, OpenClaw sorts a provider's profiles by type, **OAuth first, then static token, then API key**, and within a type by least recent use. So a subscription token plus an API key gives you a natural primary and backup: 1. Requests go to the token profile while it is healthy. 2. When the plan's usage window runs out, the provider error lands in OpenClaw's rate-limit bucket, the token profile goes into cooldown and the API-key profile takes over. 3. When the cooldown ends, the token profile becomes eligible again. To force a different order, set `auth.order.<provider>` in config or a per-agent override with `openclaw models auth order set --provider <id> <profileIds...>`; the stored override wins over config. ## Choosing - **Personal, single-operator use** where a flat plan is cheaper and an occasional limit is acceptable: a subscription token, ideally with an API key behind it. - **A small team, shared automation or night jobs** that must not stall when a plan's window runs out: an API key as the primary route, because spend is metered and limits are the account's, not a personal plan's. - **OpenAI** follows the same idea through OAuth rather than a setup token: a ChatGPT or Codex sign-in profile with an `openai:` API-key profile as backup in `auth.order.openai`. ## Replacing and removing credentials - `openclaw models auth paste-api-key --provider <id> --profile-id <id>` adds a named backup key without changing the active provider connection. - `openclaw models auth logout <profileId>` removes one profile from the agent's store and also drops it from `auth.profiles` and every `auth.order` list, so no stale reference is left behind. - Removing a saved credential is different from a token expiring: an expired token simply stops being eligible until a new one is saved. ## Checking it - `openclaw models auth list --provider anthropic` lists profiles, their cooldowns and disable reasons, without printing secrets. - `openclaw models status` shows token expiry and, for providers such as Anthropic and OpenAI, usage windows and quota snapshots.

  • A subscription token's usage window runs out mid-evening. What does OpenClaw do if an API-key profile exists for the same provider?
    Usage-window exhaustion is classified with rate limits, so the token profile goes into a cooldown and OpenClaw rotates to the next eligible profile, here the API key. The model does not change; only the credential does. When the cooldown passes, the token profile is eligible again.
  • Why should a token or key never be passed as a command-line argument to `paste-token` or `paste-api-key`?
    Arguments land in shell history and process lists. Both commands prompt for the value by default, and the docs say to pipe it on stdin in automation, for example with printf piped into `openclaw models auth paste-api-key --provider openai`.

  • OpenClaw refreshes a setup token automatically before it expires
  • Auth profiles keep their secrets in auth.profiles in openclaw.json
  • OpenClaw always tries API keys before subscription tokens
  • A subscription token gives unlimited use for a flat fee
  • The setup-token command runs without an interactive terminal