Auth credential semantics

This document defines the canonical credential eligibility and resolution semantics used across:

• text

  Copy

  resolveAuthProfileOrder
• text

  Copy

  resolveApiKeyForProfile
• text

  Copy

  models status --probe
• text

  Copy

  doctor-auth

The goal is to keep selection-time and runtime behavior aligned.

Stable probe reason codes

• text

  Copy

  ok
• text

  Copy

  excluded_by_auth_order
• text

  Copy

  missing_credential
• text

  Copy

  invalid_expires
• text

  Copy

  expired
• text

  Copy

  unresolved_ref
• text

  Copy

  no_model

Token credentials

Token credentials (

) support inline and/or .

Eligibility rules

1. A token profile is ineligible when both
   text

   Copy

   token
   and
   text

   Copy

   tokenRef
   are absent.
2. text

   Copy

   expires
   is optional.
3. If
   text

   Copy

   expires
   is present, it must be a finite number greater than
   text

   Copy

   0
   .
4. If
   text

   Copy

   expires
   is invalid (
   text

   Copy

   NaN
   ,
   text

   Copy

   0
   , negative, non-finite, or wrong type), the profile is ineligible with
   text

   Copy

   invalid_expires
   .
5. If
   text

   Copy

   expires
   is in the past, the profile is ineligible with
   text

   Copy

   expired
   .
6. text

   Copy

   tokenRef
   does not bypass
   text

   Copy

   expires
   validation.

Resolution rules

1. Resolver semantics match eligibility semantics for
   text

   Copy

   expires
   .
2. For eligible profiles, token material may be resolved from inline value or
   text

   Copy

   tokenRef
   .
3. Unresolvable refs produce
   text

   Copy

   unresolved_ref
   in
   text

   Copy

   models status --probe
   output.

Agent copy portability

Agent auth inheritance is read-through. When an agent has no local profile, it can resolve profiles from the default/main agent store at runtime without copying secret material into its own

.

Explicit copy flows, such as

, use this portability policy:

• text

  Copy

  api_key
  profiles are portable unless
  text

  Copy

  copyToAgents: false
  .
• text

  Copy

  token
  profiles are portable unless
  text

  Copy

  copyToAgents: false
  .
• text

  Copy

  oauth
  profiles are not portable by default because refresh tokens can be single-use or rotation-sensitive.
• Provider-owned OAuth flows may opt in with
  text

  Copy

  copyToAgents: true
  only when copying refresh material across agents is known safe.

Non-portable profiles remain available through read-through inheritance unless the target agent signs in separately and creates its own local profile.

Explicit auth order filtering

• When
  text

  Copy

  auth.order.<provider>
  or the auth-store order override is set for a provider,
  text

  Copy

  models status --probe
  only probes profile ids that remain in the resolved auth order for that provider.
• A stored profile for that provider that is omitted from the explicit order is not silently tried later. Probe output reports it with
  text

  Copy

  reasonCode: excluded_by_auth_order
  and the detail
  text

  Copy

  Excluded by auth.order for this provider.

Probe target resolution

• Probe targets can come from auth profiles, environment credentials, or
  text

  Copy

  models.json
  .
• If a provider has credentials but OpenClaw cannot resolve a probeable model candidate for it,
  text

  Copy

  models status --probe
  reports
  text

  Copy

  status: no_model
  with
  text

  Copy

  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.
• Auth-store callers should choose an explicit external-CLI discovery mode:
  text

  Copy

  none
  for persisted/plugin auth only,
  text

  Copy

  existing
  for refreshing already stored external CLI profiles, or
  text

  Copy

  scoped
  for a concrete provider/profile set.
• Read-only/status paths pass
  text

  Copy

  allowKeychainPrompt: false
  ; they use file-backed external CLI credentials only and do not read or reuse macOS Keychain results.

OAuth SecretRef Policy Guard

• SecretRef input is for static credentials only.
• If a profile credential is
  text

  Copy

  type: "oauth"
  , SecretRef objects are not supported for that profile credential material.
• If
  text

  Copy

  auth.profiles.<id>.mode
  is
  text

  Copy

  "oauth"
  , SecretRef-backed
  text

  Copy

  keyRef
  /
  text

  Copy

  tokenRef
  input for that profile is rejected.
• Violations are hard failures in startup/reload auth resolution paths.

Legacy-Compatible Messaging

For script compatibility, probe errors keep this first line unchanged:

Human-friendly detail and stable reason codes may be added on subsequent lines.

Related

• Secrets management
• Auth storage