OpenClaw Auth Credentials Explained — Tokens, SecretRefs, Expiry, and Probe Codes

OpenClaw auth credentials are easy to misread because there are several layers: stored auth profiles, environment credentials, SecretRefs, provider model candidates, and explicit auth order. The credential semantics doc exists to keep selection-time checks and runtime behavior aligned, especially for models status --probe and auth failure debugging.

Token eligibility

A token credential can store an inline token, a tokenRef, or both. It is ineligible if both are absent. Expiry is optional, but if expires is present it must be a finite number greater than zero. Invalid values such as zero, negative numbers, non-finite values, NaN, or the wrong type make the profile ineligible with invalid_expires. If the expiry is in the past, the profile is ineligible with expired.

The important detail: tokenRef does not bypass expiry validation. OpenClaw validates the profile first, then resolves eligible token material from the inline value or SecretRef. If the reference cannot be resolved, probe output reports unresolved_ref.

Stable reason codes

Probe reason codes are designed to be stable enough for scripts and monitoring. The documented set includes ok, excluded_by_auth_order, missing_credential, invalid_expires, expired, unresolved_ref, and no_model.

openclaw models status --probe

That command can report targets from auth profiles, environment credentials, or models.json. If a provider has credentials but no probeable model candidate can be resolved, the status is no_model. That is different from missing auth; it means the provider side exists but OpenClaw cannot pick something concrete to test.

Auth order filtering

Explicit auth order is strict by design. When auth.order.<provider> or an auth-store override is set, probe only tests profile ids that remain in the resolved order. A stored profile omitted from that order is not silently tried later. Instead, probe reports excluded_by_auth_order with detail saying it was excluded by auth order for the provider.

OAuth and SecretRefs

SecretRef input is for static credentials only. If a profile credential is type: "oauth", SecretRef objects are not supported for that profile credential material. If auth.profiles.<id>.mode is "oauth", SecretRef-backed keyRef or tokenRef input is rejected. The docs describe these as hard failures in startup or reload auth resolution paths.

My practical rule: use SecretRefs for static keys and tokens, not for OAuth-mode profile material. Keep auth order explicit only when you truly want to remove fallback paths. And whenever a model suddenly stops working, read the reason code before changing config.

If you are turning model auth and credential routing into real operations instead of a demo, The OpenClaw Playbook is the shortcut I wish every operator had: identity files, memory rules, safety boundaries, channel discipline, and production habits in one field-tested guide.

Selection order in practice

Auth order is a policy statement. If you list one profile first and omit another, OpenClaw treats that as intentional. That is safer than surprise fallback, but it means a forgotten profile id can create a failure even though valid credentials still exist on disk. Probe output is the quickest way to distinguish “no credential exists” from “this credential was excluded by policy.”

Practical triage path

When auth fails, check three things in order: whether a credential target exists, whether it is eligible, and whether it is selected. Missing token material, invalid expiry, unresolved SecretRef, and auth-order exclusion are different problems. Fixing them with one broad config rewrite usually creates more risk than reading the reason code and changing one layer.

Runbook detail

For OpenClaw Auth Credentials Explained — Tokens, SecretRefs, Expiry, and Probe Codes, the important operator move is to record the exact documented surface you used and the condition that proves it worked. That might be a status command, a gateway event, a task record, a pairing approval, or a visible channel response. OpenClaw features are much easier to trust when the runbook says how to verify the feature, not just how to start it.