Auth credential semantics#

OpenClaw selects credentials for model providers using named auth profiles. The system applies fixed eligibility and resolution rules so that profile order, expiration, and storage location produce consistent behavior across CLI probes, agent runs, and config reloads.

Token credentials#

Token credentials use type: "token" and support either an inline token value or a tokenRef.

Eligibility rules#

A token profile is ineligible when:

Both token and tokenRef are absent.
expires is present but invalid (NaN, 0, negative, non-finite, or wrong type) — reported as invalid_expires.
expires is in the past — reported as expired.

tokenRef does not bypass expires validation.

Resolution rules#

For eligible profiles, the runtime resolves the token from the inline value or the referenced secret. An unresolvable tokenRef produces the unresolved_ref reason code.

Agent copy portability#

Agent auth profiles inherit from the main store at runtime without copying secret material. Explicit copy flows (for example when adding agents) follow these rules:

api_key and token profiles are portable unless copyToAgents: false.
oauth profiles are not portable by default (refresh tokens may be single-use or rotation-sensitive). Provider-owned OAuth flows can opt in with copyToAgents: true only when copying is known to be safe.

Non-portable profiles remain available through read-through inheritance.

Config-only auth routes#

auth.profiles entries with mode: "aws-sdk" are routing metadata only. They are valid when the target provider uses models.providers.<id>.auth: "aws-sdk" (or a plugin-owned Amazon Bedrock setup). Do not store type: "aws-sdk" entries in credential files; openclaw doctor --fix moves legacy markers to auth.profiles and removes them from the credential store.

Explicit auth order filtering#

When auth.order.<provider> (or the auth-store order override) is set, openclaw models status --probe only probes the profile IDs that remain in the resolved order for that provider. A stored profile omitted from the order is not tried later and is reported with:

reasonCode: excluded_by_auth_order
Excluded by auth.order for this provider.

Probe target resolution#

Probe targets can come from:

Stored auth profiles
Environment credentials
models.json

If a provider has credentials but no resolvable model candidate, the probe reports status: no_model with reasonCode: no_model.

External CLI credential discovery#

Runtime-only credentials owned by external CLIs are discovered only when the provider, runtime, or auth profile is in scope for the current operation, or when a stored local profile for that external source already exists. Read-only and status paths use allowKeychainPrompt: false and therefore read only file-backed external CLI credentials.

OAuth SecretRef policy guard#

SecretRef objects are supported only for static credentials. If a profile has type: "oauth" (or auth.profiles.<id>.mode is "oauth"), SecretRef-backed keyRef or tokenRef input is rejected at validation time.

Legacy-compatible messaging#

For script compatibility, probe error messages begin with the unchanged first line:

Auth profile credentials are missing or expired.

Subsequent lines contain the stable reason code and human-friendly detail.