mirror of https://github.com/openclaw/openclaw.git
193 lines
6.1 KiB
Markdown
193 lines
6.1 KiB
Markdown
---
|
||
summary: "Model authentication: OAuth, API keys, and Claude CLI reuse"
|
||
read_when:
|
||
- Debugging model auth or OAuth expiry
|
||
- Documenting authentication or credential storage
|
||
title: "Authentication"
|
||
---
|
||
|
||
# Authentication (Model Providers)
|
||
|
||
<Note>
|
||
This page covers **model provider** authentication (API keys, OAuth, Claude CLI reuse). For **gateway connection** authentication (token, password, trusted-proxy), see [Configuration](/gateway/configuration) and [Trusted Proxy Auth](/gateway/trusted-proxy-auth).
|
||
</Note>
|
||
|
||
OpenClaw supports OAuth and API keys for model providers. For always-on gateway
|
||
hosts, API keys are usually the most predictable option. Subscription/OAuth
|
||
flows are also supported when they match your provider account model.
|
||
|
||
See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
|
||
layout.
|
||
For SecretRef-based auth (`env`/`file`/`exec` providers), see [Secrets Management](/gateway/secrets).
|
||
For credential eligibility/reason-code rules used by `models status --probe`, see
|
||
[Auth Credential Semantics](/auth-credential-semantics).
|
||
|
||
## Recommended setup (API key, any provider)
|
||
|
||
If you’re running a long-lived gateway, start with an API key for your chosen
|
||
provider.
|
||
For Anthropic specifically, API key auth is the safe path. Claude CLI reuse is
|
||
the other supported subscription-style setup path.
|
||
|
||
1. Create an API key in your provider console.
|
||
2. Put it on the **gateway host** (the machine running `openclaw gateway`).
|
||
|
||
```bash
|
||
export <PROVIDER>_API_KEY="..."
|
||
openclaw models status
|
||
```
|
||
|
||
3. If the Gateway runs under systemd/launchd, prefer putting the key in
|
||
`~/.openclaw/.env` so the daemon can read it:
|
||
|
||
```bash
|
||
cat >> ~/.openclaw/.env <<'EOF'
|
||
<PROVIDER>_API_KEY=...
|
||
EOF
|
||
```
|
||
|
||
Then restart the daemon (or restart your Gateway process) and re-check:
|
||
|
||
```bash
|
||
openclaw models status
|
||
openclaw doctor
|
||
```
|
||
|
||
If you’d rather not manage env vars yourself, onboarding can store
|
||
API keys for daemon use: `openclaw onboard`.
|
||
|
||
See [Help](/help) for details on env inheritance (`env.shellEnv`,
|
||
`~/.openclaw/.env`, systemd/launchd).
|
||
|
||
## Anthropic: legacy token compatibility
|
||
|
||
Existing Anthropic token profiles are still honored at runtime if they are
|
||
already configured, but OpenClaw no longer offers Anthropic setup-token auth
|
||
for new setup via onboarding or `models auth` commands.
|
||
|
||
For new setup, use an Anthropic API key or migrate to Claude CLI on the gateway
|
||
host.
|
||
|
||
Manual token entry (any provider; writes `auth-profiles.json` + updates config):
|
||
|
||
```bash
|
||
openclaw models auth paste-token --provider openrouter
|
||
```
|
||
|
||
Auth profile refs are also supported for static credentials:
|
||
|
||
- `api_key` credentials can use `keyRef: { source, provider, id }`
|
||
- `token` credentials can use `tokenRef: { source, provider, id }`
|
||
- OAuth-mode profiles do not support SecretRef credentials; if `auth.profiles.<id>.mode` is set to `"oauth"`, SecretRef-backed `keyRef`/`tokenRef` input for that profile is rejected.
|
||
|
||
Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
|
||
|
||
```bash
|
||
openclaw models status --check
|
||
```
|
||
|
||
Optional ops scripts (systemd/Termux) are documented here:
|
||
[Auth monitoring scripts](/help/scripts#auth-monitoring-scripts)
|
||
|
||
## Anthropic: Claude CLI migration
|
||
|
||
If Claude CLI is already installed and signed in on the gateway host, you can
|
||
switch an existing Anthropic setup over to the CLI backend. This is a
|
||
supported OpenClaw migration path for reusing a local Claude CLI login on that
|
||
host.
|
||
|
||
Prerequisites:
|
||
|
||
- `claude` installed on the gateway host
|
||
- Claude CLI already signed in there with `claude auth login`
|
||
|
||
```bash
|
||
openclaw models auth login --provider anthropic --method cli --set-default
|
||
```
|
||
|
||
This keeps your existing Anthropic auth profiles for rollback, but changes the
|
||
default model selection to `claude-cli/...` and adds matching Claude CLI
|
||
allowlist entries under `agents.defaults.models`.
|
||
|
||
Verify:
|
||
|
||
```bash
|
||
openclaw models status
|
||
```
|
||
|
||
Onboarding shortcut:
|
||
|
||
```bash
|
||
openclaw onboard --auth-choice anthropic-cli
|
||
```
|
||
|
||
Interactive `openclaw onboard` and `openclaw configure` prefer Claude CLI for
|
||
Anthropic and no longer offer setup-token as a new setup path.
|
||
|
||
## Checking model auth status
|
||
|
||
```bash
|
||
openclaw models status
|
||
openclaw doctor
|
||
```
|
||
|
||
## API key rotation behavior (gateway)
|
||
|
||
Some providers support retrying a request with alternative keys when an API call
|
||
hits a provider rate limit.
|
||
|
||
- Priority order:
|
||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (single override)
|
||
- `<PROVIDER>_API_KEYS`
|
||
- `<PROVIDER>_API_KEY`
|
||
- `<PROVIDER>_API_KEY_*`
|
||
- Google providers also include `GOOGLE_API_KEY` as an additional fallback.
|
||
- The same key list is deduplicated before use.
|
||
- OpenClaw retries with the next key only for rate-limit errors (for example
|
||
`429`, `rate_limit`, `quota`, `resource exhausted`).
|
||
- Non-rate-limit errors are not retried with alternate keys.
|
||
- If all keys fail, the final error from the last attempt is returned.
|
||
|
||
## Controlling which credential is used
|
||
|
||
### Per-session (chat command)
|
||
|
||
Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:default`, `anthropic:work`).
|
||
|
||
Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).
|
||
|
||
### Per-agent (CLI override)
|
||
|
||
Set an explicit auth profile order override for an agent (stored in that agent’s `auth-profiles.json`):
|
||
|
||
```bash
|
||
openclaw models auth order get --provider anthropic
|
||
openclaw models auth order set --provider anthropic anthropic:default
|
||
openclaw models auth order clear --provider anthropic
|
||
```
|
||
|
||
Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.
|
||
|
||
## Troubleshooting
|
||
|
||
### "No credentials found"
|
||
|
||
If the Anthropic profile is missing, migrate that setup to Claude CLI or an API
|
||
key on the **gateway host**, then re-check:
|
||
|
||
```bash
|
||
openclaw models status
|
||
```
|
||
|
||
### Token expiring/expired
|
||
|
||
Run `openclaw models status` to confirm which profile is expiring. If a legacy
|
||
Anthropic token profile is missing or expired, migrate that setup to Claude CLI
|
||
or an API key.
|
||
|
||
## Claude CLI requirements
|
||
|
||
Only needed for the Anthropic Claude CLI reuse path:
|
||
|
||
- Claude Code CLI installed (`claude` command available)
|