Master OpenClaw Auth: Resolve Credential Semantics

You know that feeling when your auth works in one command but fails in another for no clear reason? It usually happens because different parts of a system interpret your credentials differently. To fix this, we use a unified set of rules for how credentials are picked and resolved across all our tools.

This guide breaks down the logic used by resolveAuthProfileOrder, resolveApiKeyForProfile, models status --probe, and doctor-auth. The goal is to make sure your runtime behavior matches what you see during setup.

Stable Reason Codes

When things go wrong, you need clear feedback. These are the standard codes you will see:

• ok
• missing_credential
• invalid_expires
• expired
• unresolved_ref

Token Credentials

If you are using type: "token", you can provide a token directly or use a tokenRef.

Eligibility rules

Here is how the system decides if a token profile can be used:

1. A token profile is ineligible when both token and tokenRef are absent.
2. expires is optional.
3. If expires is present, it must be a finite number greater than 0.
4. If expires is invalid (NaN, 0, negative, non-finite, or wrong type), the profile is ineligible with invalid_expires.
5. If expires is in the past, the profile is ineligible with expired.
6. tokenRef does not bypass expires validation.

Resolution rules

Once a profile is deemed eligible, these rules apply:

1. Resolver semantics match eligibility semantics for expires, and token material is resolved from the inline value or tokenRef.
2. Unresolvable refs produce unresolved_ref in models status --probe output.

OAuth SecretRef Policy Guard

We have a strict policy for OAuth to keep things predictable.

• 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/tokenRef input for that profile is rejected.
• Violations are hard failures in startup/reload auth resolution paths.

Legacy-Compatible Messaging

If you have scripts that parse our output, don’t worry. We kept the first line of probe errors the same for compatibility:

Auth profile credentials are missing or expired.

You might see more details or specific reason codes on the lines below it, but that first line stays exactly as it is.

Need help getting your auth configured? Check out the AI Setup Assistant.

Next Steps

• Auth Profile Configuration
• Troubleshooting Auth