OpenClaw API Key Errors: Fix Missing Keys, 401, 429, and Gateway Auth

Start with the first error, the process that reported it, and the model or endpoint it was trying to reach. If OpenClaw reports No API key found for provider, restore a usable credential for that provider on the actual Gateway host and agent. If the client reports AUTH_TOKEN_MISMATCH, repair its Gateway authentication. If a model provider returns 429, honor its wait instruction and inspect quota or cooldown before sending more work.

Those fixes are not interchangeable. A Gateway token lets a client connect to OpenClaw; a provider API key or supported login authenticates model access; a channel credential connects a messaging integration. OpenClaw's authentication documentation separates these connections.

This guide follows the current documentation checked on October 7, 2026. The recovery commands below are documented procedures. The Python example is a tested, offline scheduling example using fictional responses; no live credential, provider request, or production incident was tested for this update.

Find your error and take the first useful action

Pause repeated submissions while you identify the rejected request. Keep the error message, time, agent, provider/model, runtime, and attempted endpoint together. When several attempts failed, retain their order: a final “all in cooldown” message can conceal an earlier authentication error and a later failure on a backup model.

The distinctions above follow the models CLI, Gateway connect troubleshooting, and OpenResponses HTTP reference. Use the detailed sections below to turn the matching symptom into a repair and a success check.

Inspect the agent and session that actually failed

Run diagnostics on the Gateway machine with the appropriate service identity and state directory. A login on your laptop, or a working default agent, does not establish that a remote service or another agent can use the same authentication.

For example, if the failing agent is named research, these commands inspect the Gateway and that agent's configured model authentication:

openclaw gateway status
openclaw models status --agent research

Use openclaw logs --follow to locate the first relevant error and the subsequent attempts. Record the OpenClaw version alongside it. Keep private prompts and credential values out of any excerpt you share.

Replace research with the real agent ID. In the affected chat, inspect the session separately:

/model status
/status

The CLI reports configured defaults and fallbacks; it does not resolve a chat's model override. /model status shows the chat selection, while /status can distinguish the selected model from an active fallback. ACP and other runtime-owned connections may have their own model and authentication state. Models CLI documentation explains these scopes.

Read the status findings as separate questions:

• auth.providers: where is authentication expected to come from?
• auth.oauth: what is the stored profile's health or expiry, including API-key profiles?
• auth.modelRouteIssues: is the configured model connection missing, incompatible, or indeterminate?
• auth.runtimeAuthRoutes: can the runtime that owns authentication actually run?

A stored key with an unavailable native runtime is a runtime problem. A referenced file that is found but cannot be resolved is an indeterminate credential source. Neither finding alone proves that the provider rejected a key.

What does a successful status check prove?

openclaw models status --check --agent research uses documented exit codes: 0 means no recognized route, runtime, or expiry issue; 1 includes missing, expired, incompatible, unavailable, or indeterminate conditions; 2 means expiring authentication without a condition that warrants 1. Read the returned object as well as the exit code, because a failed command can return an error object. Missing usage-window data is unknown, not a zero balance. The CLI reference documents the check behavior.

Without --probe, status is not an inference test. It can still resolve targeted secrets or inspect provider-owned state, so it should not be described as completely offline. A model catalog, a healthy /healthz, and a successful Gateway handshake also do not prove that the chosen provider accepts a model request.

“No API key found”: repair the selected credential source

A missing-key message means the selected connection did not obtain usable authentication. First determine whether the credential is genuinely absent, excluded by profile order, shadowed by an agent-local profile, or supplied by a failed SecretRef.

Current OpenClaw stores shared authentication in ~/.openclaw/state/openclaw.sqlite, with agent-local state in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. An agent without a local override can read shared credentials without copying them. A local profile with the same ID or an auth-order override can change the selection. Use the supported auth helpers rather than copying keys into every agent or editing SQLite. Authentication storage describes the current arrangement.

For a genuinely missing Anthropic API key on the research agent, the current interactive helper is:

openclaw models auth paste-api-key --provider anthropic --agent research

The helper prompts for the key; it should not appear in command-line arguments or support logs. It updates the configured/active profile or creates a manual profile. If you need a separate named backup, use the documented --profile-id behavior deliberately, rather than accidentally changing the active connection. openclaw models auth add provides the interactive provider helper. These procedures are documented in models authentication helpers.

For OpenAI, the canonical provider is openai for both API-key and ChatGPT/Codex authentication. The login helper defaults to ChatGPT/Codex authentication; an API-key method must be selected explicitly when that is the intended connection. paste-token accepts token material and is not a substitute for paste-api-key. Legacy openai-codex profile names are migration inputs, not a reason to create an unrelated provider namespace. See Gateway authentication for the supported methods.

If the selected connection uses an explicit SecretRef, restore its authorized source instead of deleting the reference and hoping an environment key takes over. An active reference takes precedence on supported paths, while a stored auth profile may shadow a config reference. A configured-unavailable provider cannot bypass the explicit reference failure by silently using another source. Read-only diagnostics can show a prepared snapshot even while sending remains unavailable. Secret operations explains this distinction.

After the repair, follow the helper's application guidance, inspect the same agent again, and verify a short request in the affected session. Seeing the profile listed is an intermediate result; receiving a complete model reply through the intended connection is the useful success signal.

Old auth JSON files and native CLI login are different cases

Older auth-profiles.json, auth-state.json, and auth.json files are migration material in the current documentation, not the current credential store. Verified Doctor imports preserve timestamped archives and do not overwrite usable SQLite authentication with stale JSON. Preserve the originals and follow the specific migration finding before using repair mode. Deleting history or installing an arbitrary older release is not a missing-key fix. Storage and migration guidance describes the supported paths.

For native Claude CLI authentication, repair the login under the host/user that owns it and select the native CLI backend separately. The executable, PATH, and CLAUDE_CONFIG_DIR must match the runtime. OpenClaw does not read, store, refresh, or forward Claude's native login tokens. A managed setup-token is another supported method, with an interactive TTY requirement; it is not an extracted native token. The authentication guide describes compatibility, but a model label alone cannot establish subscription billing or account entitlement.

Provider 401: fix rejection or missing outgoing authentication

If the response came from the model provider, inspect the issuer and body before replacing anything. invalid bearer token points toward the credential used for that request. missing authentication header points toward authentication not being attached or an incompatible endpoint/adapter. A billing or account restriction can also appear with 401 or 403; the status alone is not a diagnosis. Model failover documentation explains classification using the provider's error details.

Check these connections in order:

1. Provider and endpoint: confirm baseUrl, API adapter, model ID, and any required headers for the actual request. These settings belong under models.providers.<id> in model configuration, not inside credential rows.
2. Authentication method: distinguish an API key, supported managed login, setup-token, and native runtime authentication. A familiar sk- prefix does not prove that a value is valid for this provider.
3. Selected source: inspect the profile, agent-local override, explicit reference, or service environment used by the failed attempt.
4. Provider restriction: if credentials resolve, use the provider's account information to check model access, expiration/revocation, or billing restrictions named in the response.

Repair the condition you found: supply a missing source, renew an expired supported login, replace a credential the provider rejected, or correct the endpoint/header configuration. Do not rotate all profiles to fix one request. Removing a stored key does not revoke it at the provider; removing provider authentication through a running Gateway's control plane can abort matching active runs. Authentication guidance describes these different effects.

For a detailed provider-side procedure, use OpenClaw 401: invalid bearer token and missing authentication headers. If the key is accepted but the model is unavailable or lacks required tool support, continue with connecting models and verifying tool use. “Model not available” by itself does not prove that the model was retired.

Gateway token mismatch, pairing, and channel access

When the Control UI or another client cannot connect, read the Gateway's detailed connect error. WebSocket 1008 is a policy rejection code; it does not uniquely identify an invalid provider key.

These distinctions come from Gateway connection troubleshooting. A shared secret does not replace Control UI device identity. For a token-authenticated client, the host's interactive gateway auth-token --show facility can reveal the current credential to its authorized operator; keep that value local, out of URLs, logs, screenshots, and public messages.

For a channel that reports a permission or delivery problem, inspect that channel's bot identity and access policy separately. If the Gateway accepts the client and a model reply completes but delivery fails, provider-key changes will not repair the messaging integration. An ignored message can also reflect a no-reply policy, rather than a failed inference. Agent and Control UI troubleshooting provides the relevant diagnostic branches.

Calling the Gateway HTTP API is not calling the provider directly

OpenClaw's OpenResponses HTTP endpoint is disabled by default. In shared-token/password mode it expects Authorization: Bearer with the Gateway credential, not an Anthropic or OpenAI key. Trusted-proxy and other identity-bearing modes use their own rules. Shared-secret HTTP access has full operator semantics; it should not be treated as a narrow read-only key. OpenResponses HTTP documentation describes the modes and scope.

A disabled endpoint can return 404. Its incoming authentication-attempt limiter can return 429 with Retry-After. Neither tells you whether the upstream model key works. Fix the authorized client's authentication and wait; do not change IP, Origin, or provider profiles to evade the limiter.

openclaw gateway status normally tests service state and a WebSocket authentication handshake. --require-rpc additionally checks read scope; --no-probe checks service state only. An explicit --url requires explicit credentials and does not fall back to configured/environment authentication. A local --port target uses the invoking CLI's authentication/TLS context, which can differ from service configuration. Gateway query documentation explains the checks. Success must match the connection and permissions your client actually needs.

Provider 429 and “all in cooldown”: wait for the right reason

For a provider rejection, read both the error body and its retry guidance. A temporary pacing limit, an exhausted usage window, a billing restriction, and a permanent authentication failure call for different recovery. A final cooldown message does not preserve those distinctions by itself.

The current built-in model retry policy allows up to 10 total attempts for model 429 errors. Other transient errors have a separate limit of eight retries and a 90-second consecutive-outage window. A complete model response clears that outage window; partial output or tool activity does not. Provider wait guidance can exceed the usual backoff cap, and deadline/cancellation can end recovery earlier. Do not wrap a whole-turn retry loop around this existing policy. retry.provider.maxRetries is an embedded-session setting, not a generic openclaw.json property. Retry documentation gives the current scope.

The provider's Retry-After is a minimum wait, not always a quota-reset timestamp. HTTP permits an integer number of seconds or an HTTP date; OpenClaw also documents millisecond hints. If that minimum exceeds your job deadline, defer the job or use an eligible approved fallback rather than sending early. HTTP Retry-After semantics and OpenClaw failover explain these cases.

Cooldown is persisted state. The regular internal sequence of 30 seconds, one minute, and five minutes is not a promise about an upstream reset. A model-scoped cooldown may leave a sibling model usable; billing disablement can block a whole profile. The initial ten-minute billing/permanent-auth disablement does not automatically clear just because you restarted, recharged, or upgraded. Inspect the recorded cause before assuming the wait alone will solve it. Model failover describes the state and recovery.

Reduce avoidable submissions and concurrency when the provider's response identifies pacing. When it identifies an exhausted account window, resolve that account's permitted capacity or wait for its stated reset. Multiple keys do not multiply a shared account quota. For the full recovery procedure, use OpenClaw 429, cooldown, and fallback troubleshooting.

When is a fallback allowed?

Configured default, cron, and automatic selections can use their approved chains. An explicitly chosen session model is strict, as is an agent primary without fallbacks. A successful fallback applies to that turn; the next turn starts with the selected model again. A temporarily eligible same-provider profile does not permanently change a user's auth pin. Current selection and failover rules explain the limits.

Before using a backup, confirm that it supports the task, tools, context, data handling, and billing conditions. A timeout means the earlier outcome may be unknown. Check completed tools and external actions before advancing to another model or account. A repeated prompt or job ID is not proof of provider idempotency; HTTP semantics does not make POST automatically safe to replay.

Request 400 and context errors need a different repair

Read the rejected body to distinguish an unsupported field, feature flag, or API adapter from context_length_exceeded. Correct the field only for the connection that rejected it; switching between direct APIs and compatible endpoints can change which features are accepted.

For context overflow, preserve completed changes, tool results, and pending work first. Then use supported compaction when history is the problem, or continue from a short saved task record in a fresh session when compaction cannot fit. If a fresh session fails too, inspect fixed instructions, tool schemas, workspace input, and the real loaded model limit. Do not delete stored history or simply increase model metadata. The OpenClaw context recovery guide explains the runtime-specific steps.

A rate limit on the primary and a context failure on a smaller fallback are two failed attempts, not one generic “API key error.” Check which model rejected which request before changing its configuration. The failover documentation describes per-attempt error handling.

Docker, TLS, config, and tools: fix the process that is failing

Docker works differently from your interactive shell

Check the actual container/service user, state volume, mounted configuration, and required variable's presence and source without printing secret values. The normal environment-loading rule preserves existing process values, but the sources are not interchangeable: workspace .env files ignore provider credentials and protected controls, while the trusted global state-directory .env can supply provider keys. Config environment fills missing values; supported managed systemd services have their own refresh rules. Do not assume that every environment value overrides every configuration field. Environment rules define the precedence.

If the deployment definition has the intended value but the running container still uses the old one, apply the change through the current Docker deployment procedure. Compose environment changes require recreating the Gateway with up -d; a restart alone does not apply new environment values. Preserve mounted state and plan for interrupted work before recreating anything. The current official setup uses /home/node; an old /root/.openclaw or two-image recipe is not evidence for your deployment. Docker environment documentation provides the supported setup.

For “port already running,” first identify whether the CLI/client targets an existing Gateway and whether it is the intended instance. Compare service user, configuration, state directory, and target port. Killing an unknown process or forcing a second installation can worsen a configuration mismatch.

TLS and 502 do not establish that a key is invalid

A TLS failure calls for inspecting the certificate chain, expiry, hostname, proxy, and the trust configuration of the process making the connection. Keep certificate validation enabled. If an authorized private CA is required, Node's NODE_EXTRA_CA_CERTS can extend trusted roots from a PEM file at process startup; changing process.env later does not reload it. Explicit client ca settings can bypass the default and extra roots. Node's CLI documentation gives the exact behavior.

A 502 can reflect upstream failure, but OpenClaw's HTTP API can also produce a local contract error when required structured client-tool output is not returned. An SSE connection may open and later report response.failed. Check the final body/event and the emitting process rather than treating every established connection or 200 as a completed inference. OpenResponses HTTP documentation describes these cases.

Validate the active config before repairing it

When the problem began after an edit, locate and validate the actual configuration:

openclaw config file
openclaw config validate

Inspect only the necessary, nonsecret keys against the installed schema. Standard JSON syntax validation alone does not validate OpenClaw's JSON5 configuration or installed field support. The validator checks structural and SecretRef compatibility, including nonexecuting exec-path trust checks; it cannot prove provider-specific parameter behavior, secret backend output, or credential acceptance. An issue on an inactive provider may be reported without blocking the active Gateway. Config CLI documentation describes the limits.

Back up the affected configuration before an authorized structural repair. Patch operations merge objects but replace arrays/scalars, and null deletes values. Use Doctor repair or migration for a finding that actually requires it; Doctor cannot manufacture a key or lift quota.

If the model can reply but a skill/tool fails, read that tool's parser, dependency, plugin, approval, or storage error. A read-only database and a missing executable are different problems from provider rejection. Repair the named runtime condition instead of rotating credentials or adding unsupported skill fields. Agent troubleshooting supplies the next diagnostic branch.

Production recovery: schedule the next action without replaying work

A useful recovery controller needs more than a list of retryable HTTP codes. Record the failed connection, parsed provider error, wait instruction, attempt count, remaining deadline, and whether the operation can safely be replayed. Keep completed actions separate from pending work. Stop on invalid authentication, exhausted billing/access, incompatible requests, cancellation, and unknown outcomes unless a specific recovery path makes continuation safe.

The following complete offline example demonstrates that decision. It makes no network requests, sleeps, secret reads, or OpenClaw calls. Save it as recovery_demo.py and run it with Python 3.10 or newer. Its three-attempt/20-second budget is an example application policy, not OpenClaw's built-in retry configuration. An integration would supply the parsed observations from its actual adapter and execute the returned action through its existing job scheduler; do not add this loop around OpenClaw's own whole-turn recovery.

from dataclasses import dataclass, field
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
import math


@dataclass(frozen=True)
class Observation:
    issuer: str                 # "provider" or "gateway"
    status: int | None
    kind: str                   # Parsed body/event meaning, not status alone
    headers: dict[str, str] = field(default_factory=dict)
    replay_safe: bool = False   # Must be established by the caller


@dataclass(frozen=True)
class Backup:
    approved: bool = False
    compatible: bool = False
    permitted_by_selection: bool = False


@dataclass(frozen=True)
class Decision:
    action: str
    wait_seconds: float
    reason: str


def wait_floor(headers: dict[str, str], now: datetime) -> float | None:
    h = {key.lower(): value.strip() for key, value in headers.items()}
    values = []
    for key, divisor in (("retry-after", 1), ("retry-after-ms", 1000)):
        raw = h.get(key)
        if raw is None:
            continue
        if key == "retry-after" and raw.isascii() and raw.isdigit():
            values.append(int(raw))
        elif key == "retry-after-ms":
            try:
                value = float(raw) / divisor
            except ValueError:
                return None
            if not math.isfinite(value) or value < 0:
                return None
            values.append(value)
        else:
            try:
                date = parsedate_to_datetime(raw)
                if date.tzinfo is None:
                    return None
                values.append(max(0.0, (date - now).total_seconds()))
            except (TypeError, ValueError, OverflowError):
                return None
    return max(values, default=0.0)


def decide(event: Observation, *, now: datetime, attempt: int,
           remaining: float, backup: Backup = Backup(),
           max_attempts: int = 3, next_call_budget: float = 2.0) -> Decision:
    def result(action, reason, wait=0.0):
        return Decision(action, wait, reason)

    if event.kind == "completed" and event.status is not None \
            and 200 <= event.status < 300:
        return result("complete", "Terminal success was recorded")
    if event.issuer != "provider":
        return result("stop", "Repair the incoming Gateway connection")
    if event.kind in {"auth", "billing", "context", "request", "refusal",
                      "cancelled", "local_contract"}:
        return result("stop", "Use the specific repair path: " + event.kind)
    if event.kind not in {"rate_limit", "server_error"}:
        return result("stop", "Unknown or ambiguous outcome; inspect work")
    if not event.replay_safe:
        return result("stop", "Replay safety has not been established")
    if attempt >= max_attempts:
        return result("stop", "Attempt budget exhausted")
    if remaining < next_call_budget:
        return result("defer", "Too little time for another attempt")
    minimum = wait_floor(event.headers, now)
    if minimum is None:
        return result("stop", "Unusable wait header; inspect the response")
    backoff = min(2 ** (attempt - 1), 8)
    wait = max(minimum, backoff)
    if wait + next_call_budget <= remaining:
        return result("retry", "Retry the pending operation only", wait)
    if (backup.approved and backup.compatible
            and backup.permitted_by_selection):
        return result("fallback", "Approved backup fits this selection")
    return result("defer", "Provider minimum exceeds this deadline", wait)


if __name__ == "__main__":
    clock = datetime(2026, 10, 7, 12, 0, tzinfo=timezone.utc)
    observations = [
        Observation("provider", 429, "rate_limit",
                    {"Retry-After": "4"}, replay_safe=True),
        Observation("provider", 200, "completed"),
    ]
    elapsed = 0.0
    for attempt, event in enumerate(observations, start=1):
        current = datetime.fromtimestamp(clock.timestamp() + elapsed,
                                         tz=timezone.utc)
        decision = decide(event, now=current, attempt=attempt,
                          remaining=20.0 - elapsed)
        print(attempt, decision)
        if decision.action != "retry":
            break
        elapsed += decision.wait_seconds  # Virtual time; no sleep or call

The demonstration prints a four-second retry decision followed by completion from a fictional terminal success. It does not demonstrate a provider accepting a key. It stops for Gateway 429, unknown timeout outcomes, an authentication/billing body even when the status looks transient, and exhausted attempts. It also recognizes Retry-After dates; the code never caps a provider's minimum and then retries early.

The kind field is the adapter's interpretation of the body or final stream event. For example, 200 plus local_contract must not become completed, and 503 plus a documented billing error must not become server_error. The replay_safe flag is a caller responsibility: neither the code nor a prompt can prove that an earlier write, message, or charge did not happen. The backup gate describes a preapproved choice, not automatic permission to switch accounts. These limits reflect OpenClaw failover and HTTP replay semantics.

Verify the repair through the same connection

After a local repair, repeat the diagnostic that exposed the problem, then test the intended path. Keep the host, agent, session, selected model, profile/runtime, and endpoint consistent. A provider-console check or a catalog request on another endpoint is useful context but does not validate the request that failed.

For a client-authentication repair, confirm that the client connects with the intended identity and required scope. For a model-authentication repair, use a short, read-only request in the affected chat and confirm a complete reply from the intended model/runtime. If delivery or tool access was the original problem, verify that component separately with an appropriately harmless action.

An optional models status --probe makes actual requests and can consume tokens or trigger limits. The current CLI requires exclusive ownership of the canonical state directory: arrange a maintenance window, stop the running Gateway appropriately, let accepted work and cleanup settle even after a timeout/interruption, scope the probe, then restore service. Its timeout/concurrency/token settings are not a guarantee of total spend. Probe guidance describes the procedure. A probe is not needed merely to check whether a field has valid syntax.

If the same error remains, stop changing unrelated settings. Collect a small support record: version, host/service identity, agent and runtime, selected versus active model, attempted endpoint, credential source type, error body/code, timing, retry hints, and what work completed. Redact credentials, private prompts, and unrelated host/account details. That record should make the remaining failure specific enough to investigate without replaying the entire task.

Frequently asked questions

Why does OpenClaw say unauthorized when my API key works elsewhere?

The failed connection may use a different endpoint, agent profile, service environment, runtime login, or Gateway credential. Identify the issuer and inspect the affected session. A working key on another request does not establish that this request used it. Authentication documentation separates client and provider authentication.

Where should I put a new OpenClaw API key?

Use the current interactive provider auth helper on the Gateway host, explicitly targeting the affected agent for a multiagent change. paste-api-key is for API keys; managed tokens and native CLI logins have separate methods. Do not manually edit SQLite or treat legacy auth JSON as the current store. Models auth helpers and storage documentation describe the supported path.

Does a successful models status or model list mean my key works?

No. Status can report stored authentication and configured compatibility; a catalog may be cached or visible without authentication. Only a completed request through the intended model connection demonstrates acceptance for that request. A --check exit of 0 is not an inference result. Models CLI documentation explains the difference.

Should I restart OpenClaw to clear cooldown?

First resolve the recorded cause. Cooldown and billing/auth disablement can persist in SQLite, and restarting does not replenish upstream quota. For Docker environment changes, recreation is a separate deployment action; a restart alone does not apply new values. Model failover and Docker environment rules cover the two cases.

What if Codex reports account/read failed during TUI bootstrap?

Treat a native Codex bootstrap message such as account/read failed or workspace routing discovery unauthorized (401) as a failure to inspect in that runtime's account/workspace connection. It does not identify an OpenClaw Gateway token or prove that an OpenAI API key was rejected. First establish which executable, host/user, account, and runtime-owned connection emitted it; OpenClaw's models status documentation distinguishes runtime authentication from stored provider profiles. The error text alone does not establish a specific account repair. For the Codex CLI message itself, what each tail after the second account/read failed: means and which repair it points to, see Codex account/read failed during TUI bootstrap: Fix by the Tail.

Can I keep retrying after a timeout if there was no reply?

Only after establishing that continuation will not repeat accepted work. A missing reply is an unknown outcome, and a POST is not automatically idempotent. Inspect completed tools and external actions, preserve the pending step, and use a bounded retry or eligible approved fallback. HTTP idempotence rules explain why silence is not proof that nothing happened.