Gateway

인증 자격 증명 의미론

이 문서는 다음 전반에서 사용되는 표준 자격 증명 적격성 및 확인 의미 체계를 정의합니다.

resolveAuthProfileOrder
resolveApiKeyForProfile
models status --probe
doctor-auth

목표는 선택 시점과 런타임 동작을 일치시키는 것입니다.

안정적인 프로브 사유 코드

ok
excluded_by_auth_order
missing_credential
invalid_expires
expired
unresolved_ref
no_model

토큰 자격 증명

토큰 자격 증명(type: "token")은 인라인 token 및/또는 tokenRef를 지원합니다.

적격성 규칙

token과 tokenRef가 모두 없으면 토큰 프로필은 부적격입니다.
expires는 선택 사항입니다.
expires가 있으면 0보다 큰 유한한 숫자여야 합니다.
expires가 유효하지 않으면(NaN, 0, 음수, 무한, 또는 잘못된 타입) 프로필은 invalid_expires로 부적격입니다.
expires가 과거이면 프로필은 expired로 부적격입니다.
tokenRef는 expires 검증을 우회하지 않습니다.

확인 규칙

확인자의 의미 체계는 expires에 대한 적격성 의미 체계와 일치합니다.
적격 프로필의 경우 토큰 자료는 인라인 값 또는 tokenRef에서 확인될 수 있습니다.
확인할 수 없는 참조는 models status --probe 출력에 unresolved_ref를 생성합니다.

에이전트 복사 이식성

에이전트 인증 상속은 읽기 통과 방식입니다. 에이전트에 로컬 프로필이 없으면 자체 auth-profiles.json에 비밀 자료를 복사하지 않고도 런타임에 기본/메인 에이전트 저장소에서 프로필을 확인할 수 있습니다.

openclaw agents add와 같은 명시적 복사 흐름은 다음 이식성 정책을 사용합니다.

api_key 프로필은 copyToAgents: false가 아닌 한 이식 가능합니다.
token 프로필은 copyToAgents: false가 아닌 한 이식 가능합니다.
oauth 프로필은 갱신 토큰이 단일 사용이거나 순환에 민감할 수 있으므로 기본적으로 이식할 수 없습니다.
공급자 소유 OAuth 흐름은 에이전트 간 갱신 자료 복사가 안전하다고 알려진 경우에만 copyToAgents: true로 옵트인할 수 있습니다.

이식 불가능한 프로필은 대상 에이전트가 별도로 로그인하여 자체 로컬 프로필을 만들지 않는 한 읽기 통과 상속을 통해 계속 사용할 수 있습니다.

구성 전용 인증 경로

mode: "aws-sdk"가 있는 auth.profiles 항목은 저장된 자격 증명이 아니라 라우팅 메타데이터입니다. 대상 공급자가 models.providers.<id>.auth: "aws-sdk" 또는 Plugin 소유 Amazon Bedrock 설정 AWS SDK 경로를 사용할 때 유효합니다. 이러한 프로필 ID는 auth-profiles.json에 일치하는 항목이 없어도 auth.order와 세션 재정의에 나타날 수 있습니다.

auth-profiles.json에 type: "aws-sdk"를 쓰지 마세요. 레거시 설치에 이러한 마커가 있으면 openclaw doctor --fix가 이를 auth.profiles로 이동하고 자격 증명 저장소에서 마커를 제거합니다.

명시적 인증 순서 필터링

auth.order.<provider> 또는 인증 저장소 순서 재정의가 공급자에 설정된 경우, models status --probe는 해당 공급자에 대해 확인된 인증 순서에 남아 있는 프로필 ID만 프로브합니다.
해당 공급자의 저장된 프로필이 명시적 순서에서 누락되면 나중에 조용히 시도되지 않습니다. 프로브 출력은 이를 reasonCode: excluded_by_auth_order와 세부 정보 Excluded by auth.order for this provider.로 보고합니다.

프로브 대상 확인

프로브 대상은 인증 프로필, 환경 자격 증명 또는 models.json에서 올 수 있습니다.
공급자에 자격 증명이 있지만 OpenClaw가 해당 공급자에 대해 프로브 가능한 모델 후보를 확인할 수 없으면 models status --probe는 reasonCode: no_model과 함께 status: no_model을 보고합니다.

외부 CLI 자격 증명 검색

외부 CLI가 소유한 런타임 전용 자격 증명은 공급자, 런타임 또는 인증 프로필이 현재 작업의 범위에 있거나, 해당 외부 소스에 대한 저장된 로컬 프로필이 이미 존재하는 경우에만 검색됩니다.
인증 저장소 호출자는 명시적인 외부 CLI 검색 모드를 선택해야 합니다. 지속된/Plugin 인증만 위한 none, 이미 저장된 외부 CLI 프로필 새로 고침을 위한 existing, 또는 구체적인 공급자/프로필 집합을 위한 scoped입니다.
읽기 전용/상태 경로는 allowKeychainPrompt: false를 전달합니다. 이 경로는 파일 기반 외부 CLI 자격 증명만 사용하며 macOS Keychain 결과를 읽거나 재사용하지 않습니다.

OAuth SecretRef 정책 가드

SecretRef 입력은 정적 자격 증명 전용입니다.
프로필 자격 증명이 type: "oauth"이면 해당 프로필 자격 증명 자료에 SecretRef 객체가 지원되지 않습니다.
auth.profiles.<id>.mode가 "oauth"이면 해당 프로필에 대한 SecretRef 기반 keyRef/tokenRef 입력은 거부됩니다.
위반은 시작/다시 로드 인증 확인 경로에서 하드 실패입니다.

레거시 호환 메시징

스크립트 호환성을 위해 프로브 오류는 이 첫 줄을 변경하지 않고 유지합니다.

Auth profile credentials are missing or expired.

사람이 읽기 쉬운 세부 정보와 안정적인 사유 코드는 이후 줄에 추가될 수 있습니다.