Auth credential semantics

Auth credential semantics 문서는 OpenClaw 공식 문서(auth-credential-semantics)를 한국어로 정리한 가이드입니다. Canonical credential eligibility and resolution semantics for auth profiles 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Canonical credential eligibility and resolution semantics for auth profiles

한국어 가이드 범위: auth-credential-semantics 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Stable probe reason codes
Token credentials
Eligibility rules
Resolution rules
Agent copy portability
Config-only auth routes
Explicit auth order filtering
Probe target resolution
External CLI credential discovery
OAuth SecretRef Policy Guard
Legacy-Compatible Messaging
관련 문서

상세 내용

본문

These semantics keep selection-time and runtime auth behavior aligned. They are shared by:

주요 항목:

resolveAuthProfileOrder (profile ordering)
resolveApiKeyForProfile (runtime credential resolution)
openclaw models status --probe
openclaw doctor auth checks (doctor-auth)

Stable probe reason codes

Probe results carry a status bucket (ok, auth, rate_limit, billing, timeout, format, unknown, no_model) plus a stable reasonCode when the probe never reached a model call:

`reasonCode`	Meaning
`excluded_by_auth_order`	Profile omitted from the explicit auth order for its provider.
`missing_credential`	No inline credential or SecretRef is configured.
`expired`	Token `expires` is in the past.
`invalid_expires`	`expires` is not a valid positive Unix ms timestamp.
`unresolved_ref`	Configured SecretRef could not be resolved.
`ineligible_profile`	Profile is incompatible with provider config (includes malformed key input).
`no_model`	Credentials exist but no probeable model candidate resolved.

Token credentials

Token credentials (type: "token") support inline token and/or tokenRef.

Eligibility rules

A token profile is ineligible when both token and tokenRef are absent (missing_credential). 2. expires is optional. When present it must be a finite number of Unix epoch milliseconds greater than 0 and no larger than the maximum JavaScript Date timestamp (8640000000000000). 3. If expires is invalid (wrong type, NaN, 0, negative, non-finite, or beyond that maximum), the profile is ineligible with invalid_expires. 4. If expires is in the past, the profile is ineligible with expired. 5. tokenRef does not bypass expires validation.

Resolution rules

Resolver semantics match eligibility semantics for expires. 2. For eligible profiles, token material may be resolved from the inline value or tokenRef. 3. Unresolvable refs produce unresolved_ref in models status --probe output.

Agent copy portability

Agent auth inheritance is read-through. When an agent has no local profile, it resolves profiles from the default/main agent store at runtime without copying secret material into its own credential store (agents//agent/openclaw-agent.sqlite).

주요 항목:

api_key and token profiles are portable unless copyToAgents: false.
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 copyToAgents: true only when copying refresh material across agents is known safe; the opt-in only applies when the profile carries inline access/refresh material.

Config-only auth routes

auth.profiles entries with mode: "aws-sdk" are routing metadata, not stored credentials. They are valid when the target provider uses models.providers..auth: "aws-sdk", the route the plugin-owned Amazon Bedrock setup writes. These profile ids may appear in auth.order and session overrides even when no matching entry exists in the credential store.

Explicit auth order filtering

주요 항목:

When auth.order.<provider> or the auth-store order override is set for a provider, models status --probe only probes profile ids that remain in the resolved auth order for that provider. The stored override wins over auth.order config.
A stored profile for that provider that is omitted from the explicit order is not silently tried later. Probe output reports it with reasonCode: excluded_by_auth_order and the detail Excluded by auth.order for this provider.

Probe target resolution

주요 항목:

Probe targets can come from auth profiles, environment credentials, or models.json (result source: profile, env, models.json).
If a provider has credentials but OpenClaw cannot resolve a probeable model candidate for it, models status --probe reports status: no_model with reasonCode: no_model.

External CLI credential discovery

주요 항목:

Runtime-only credentials owned by external CLIs (Claude CLI for claude-cli, Codex CLI for openai, MiniMax CLI for minimax-portal) 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 choose an explicit external-CLI discovery mode: none for persisted/plugin auth only, existing for refreshing already stored external CLI profiles, or scoped for a concrete provider/profile set.
Read-only/status paths pass 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. OAuth credentials are runtime-mutable (refresh flows persist rotated tokens), so SecretRef-backed OAuth material would split mutable state across stores.

주요 항목:

If a profile credential is type: "oauth", SecretRef objects are rejected for any credential material field on that profile.
If auth.profiles.<id>.mode is "oauth", SecretRef-backed keyRef/tokenRef input for that profile is rejected.
Violations are hard failures (thrown errors) in startup/reload secret preparation and profile resolution paths.

Legacy-Compatible Messaging

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/auth-credential-semantics
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Auth credential semantics

핵심 요약

Canonical credential eligibility and resolution semantics for auth profiles

한국어 가이드 범위: auth-credential-semantics 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Stable probe reason codes
Token credentials
Eligibility rules
Resolution rules
Agent copy portability
Config-only auth routes
Explicit auth order filtering
Probe target resolution
External CLI credential discovery
OAuth SecretRef Policy Guard
Legacy-Compatible Messaging
관련 문서

상세 내용

본문

These semantics keep selection-time and runtime auth behavior aligned. They are shared by:

주요 항목:

resolveAuthProfileOrder (profile ordering)
resolveApiKeyForProfile (runtime credential resolution)
openclaw models status --probe
openclaw doctor auth checks (doctor-auth)

Stable probe reason codes

Probe results carry a status bucket (ok, auth, rate_limit, billing, timeout, format, unknown, no_model) plus a stable reasonCode when the probe never reached a model call:

`reasonCode`	Meaning
`excluded_by_auth_order`	Profile omitted from the explicit auth order for its provider.
`missing_credential`	No inline credential or SecretRef is configured.
`expired`	Token `expires` is in the past.
`invalid_expires`	`expires` is not a valid positive Unix ms timestamp.
`unresolved_ref`	Configured SecretRef could not be resolved.
`ineligible_profile`	Profile is incompatible with provider config (includes malformed key input).
`no_model`	Credentials exist but no probeable model candidate resolved.

Token credentials

Token credentials (type: "token") support inline token and/or tokenRef.

Eligibility rules

A token profile is ineligible when both token and tokenRef are absent (missing_credential). 2. expires is optional. When present it must be a finite number of Unix epoch milliseconds greater than 0 and no larger than the maximum JavaScript Date timestamp (8640000000000000). 3. If expires is invalid (wrong type, NaN, 0, negative, non-finite, or beyond that maximum), the profile is ineligible with invalid_expires. 4. If expires is in the past, the profile is ineligible with expired. 5. tokenRef does not bypass expires validation.

Resolution rules

Resolver semantics match eligibility semantics for expires. 2. For eligible profiles, token material may be resolved from the inline value or tokenRef. 3. Unresolvable refs produce unresolved_ref in models status --probe output.

Agent copy portability

주요 항목:

api_key and token profiles are portable unless copyToAgents: false.
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 copyToAgents: true only when copying refresh material across agents is known safe; the opt-in only applies when the profile carries inline access/refresh material.

Config-only auth routes

Explicit auth order filtering

주요 항목:

When auth.order.<provider> or the auth-store order override is set for a provider, models status --probe only probes profile ids that remain in the resolved auth order for that provider. The stored override wins over auth.order config.
A stored profile for that provider that is omitted from the explicit order is not silently tried later. Probe output reports it with reasonCode: excluded_by_auth_order and the detail Excluded by auth.order for this provider.

Probe target resolution

주요 항목:

Probe targets can come from auth profiles, environment credentials, or models.json (result source: profile, env, models.json).
If a provider has credentials but OpenClaw cannot resolve a probeable model candidate for it, models status --probe reports status: no_model with reasonCode: no_model.

External CLI credential discovery

주요 항목:

Runtime-only credentials owned by external CLIs (Claude CLI for claude-cli, Codex CLI for openai, MiniMax CLI for minimax-portal) 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 choose an explicit external-CLI discovery mode: none for persisted/plugin auth only, existing for refreshing already stored external CLI profiles, or scoped for a concrete provider/profile set.
Read-only/status paths pass allowKeychainPrompt: false; they use file-backed external CLI credentials only and do not read or reuse macOS Keychain results.

OAuth SecretRef Policy Guard

주요 항목:

If a profile credential is type: "oauth", SecretRef objects are rejected for any credential material field on that profile.
If auth.profiles.<id>.mode is "oauth", SecretRef-backed keyRef/tokenRef input for that profile is rejected.
Violations are hard failures (thrown errors) in startup/reload secret preparation and profile resolution paths.

Legacy-Compatible Messaging

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/auth-credential-semantics
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Auth credential semantics

핵심 요약

문서 구성

상세 내용

본문

Stable probe reason codes

Token credentials

Eligibility rules

Resolution rules

Agent copy portability

Config-only auth routes

Explicit auth order filtering

Probe target resolution

External CLI credential discovery

OAuth SecretRef Policy Guard

Legacy-Compatible Messaging

관련 문서

실습 체크리스트

관련 링크

관련 가이드

Auth credential semantics

핵심 요약

문서 구성

상세 내용

본문

Stable probe reason codes

Token credentials

Eligibility rules

Resolution rules

Agent copy portability

Config-only auth routes

Explicit auth order filtering

Probe target resolution

External CLI credential discovery

OAuth SecretRef Policy Guard

Legacy-Compatible Messaging

관련 문서

실습 체크리스트

관련 링크

관련 가이드