OpenClaw 인증 프로필 설정 및 관리 가이드

여러 AI 모델을 사용하다 보면 API 키 관리나 계정 전환이 정말 번거로울 때가 많죠. 특히 프로젝트마다 다른 계정을 써야 하거나, 갑작스러운 rate limit 때문에 작업이 끊기면 개발 흐름이 완전히 깨지기 마련이에요.

이런 문제를 깔끔하게 해결해 주는 기능이 바로 Auth profile입니다. 인증 프로필과 자격 증명을 어떻게 효율적으로 관리할 수 있는지 함께 알아볼게요.

Auth Profiles

인증 프로필(Auth profile)과 자격 증명 관리에 대해 이해해 봅시다.

---

Auth profile이란 무엇인가요?

Auth profile은 특정 provider에 연결된 이름이 지정된 자격 증명 레코드(OAuth 또는 API key)예요. 프로필은 다음 경로에 저장됩니다.

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

---

일반적인 profile ID는 어떤 형태인가요?

OpenClaw는 다음과 같이 provider 이름이 접두사로 붙은 ID를 사용해요.

• anthropic:default (이메일 식별자가 없을 때 주로 사용)
• anthropic:<email> (OAuth 식별자용)
• 직접 선택한 커스텀 ID (예: anthropic:work)

---

어떤 auth profile을 먼저 사용할지 제어할 수 있나요?

네, 가능해요. Config에서 프로필에 대한 선택적 metadata와 provider별 우선순위(auth.order.<provider>) 설정을 지원하거든요.

OpenClaw는 프로필이 일시적인 cooldown(rate limits, 타임아웃, 인증 실패 등) 상태이거나, 장기적인 disabled(결제 문제, 크레딧 부족 등) 상태인 경우 해당 프로필을 잠시 건너뛸 수 있어요.

이 상태를 확인하려면 openclaw models status --json 명령어를 실행하고 auth.unusableProfiles 항목을 체크해 보세요.

에이전트별 순서 설정하기:

# Lock rotation to a single profile
openclaw models auth order set --provider anthropic anthropic:default

# Set an explicit order (fallback within provider)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Clear override
openclaw models auth order clear --provider anthropic

---

OAuth와 API key의 차이점은 무엇인가요?

OpenClaw는 두 방식 모두 지원해요.

• OAuth는 주로 구독 기반 액세스를 활용할 때 사용해요 (해당하는 경우).
• API keys는 토큰당 과금(pay-per-token) 방식을 사용하고요.

설정 위저드(wizard)는 Anthropic setup-token과 OpenAI Codex OAuth를 명시적으로 지원하며, API key도 안전하게 저장해 줍니다.

궁금한 점이 더 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

• 에이전트 설정 가이드
• Provider 연결 방법