OpenClaw 인증 자격 증명 해결 및 검증 가이드

API 인증 설정을 하다가 왜 안 되는지 몰라 답답했던 적 있으시죠? 특히 토큰이 만료되었는지, 설정이 잘못되었는지 명확하지 않으면 디버깅이 정말 힘들어집니다.

이 문서는 인증 자격 증명이 어떻게 결정되고 해결되는지 그 규칙을 정리하고 있어요. resolveAuthProfileOrder나 doctor-auth 같은 도구들이 모두 이 규칙을 따르기 때문에, 설정 시 발생할 수 있는 혼란을 줄여줄 거예요.

인증 자격 증명 의미론 (Auth Credential Semantics)

이 문서는 다음 항목들에서 공통으로 사용하는 표준 자격 증명 적격성 및 해결 의미론을 정의합니다.

• resolveAuthProfileOrder
• resolveApiKeyForProfile
• models status --probe
• doctor-auth

이 규칙의 목표는 선택 시점(selection-time)과 실행 시점(runtime)의 동작을 일관되게 유지하는 것입니다.

안정적인 상태 코드

• ok
• missing_credential
• invalid_expires
• expired
• unresolved_ref

토큰 자격 증명

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

적격성 규칙

1. token과 tokenRef가 모두 없으면 해당 토큰 프로필은 부적격으로 간주합니다.
2. expires는 선택 사항입니다.
3. expires가 있는 경우, 반드시 0보다 큰 유한한 숫자여야 합니다.
4. expires가 유효하지 않은 경우(NaN, 0, 음수, 무한대 또는 잘못된 타입), 해당 프로필은 invalid_expires와 함께 부적격 처리됩니다.
5. expires가 과거 시점이면 해당 프로필은 expired와 함께 부적격 처리됩니다.
6. tokenRef를 사용하더라도 expires 검증을 건너뛰지 않습니다.

해결 규칙

1. 해결(Resolver) 의미론은 expires에 대한 적격성 의미론과 일치합니다.
2. 적격한 프로필의 경우, 토큰 값은 인라인 값이나 tokenRef에서 가져올 수 있습니다.
3. 해결할 수 없는 참조(ref)는 models status --probe 출력 시 unresolved_ref를 생성합니다.

OAuth SecretRef 정책 가드

• SecretRef 입력은 정적(static) 자격 증명에만 사용할 수 있습니다.
• 프로필 자격 증명이 type: "oauth"인 경우, 해당 프로필의 자격 증명 재료로 SecretRef 객체를 지원하지 않습니다.
• auth.profiles.<id>.mode가 "oauth"라면, 해당 프로필에 대한 SecretRef 기반의 keyRef/tokenRef 입력은 거부됩니다.
• 이를 위반하면 인증 해결 경로의 시작 또는 재로드 시점에 하드 페일(hard failure)이 발생합니다.

레거시 호환 메시징

스크립트 호환성을 위해, 프로브(probe) 에러의 첫 번째 줄은 다음과 같이 변경되지 않고 유지됩니다.

Auth profile credentials are missing or expired.

사람이 읽기 좋은 상세 내용과 안정적인 상태 코드는 그다음 줄에 추가될 수 있습니다.

AI Setup Assistant

다음 단계

• doctor-auth를 사용하여 인증 상태 확인하기
• models status --probe 명령어로 상세 디버깅하기