openclaw models: 모델 관리 및 인증 설정 가이드

여러 AI 모델을 번갈아 가며 사용하다 보면 인증 설정이 꼬이거나 모델 이름이 기억나지 않아 답답할 때가 많아요. API 키가 유효한지, 기본 모델이 제대로 설정되었는지 일일이 확인하는 작업은 개발 흐름을 끊기 마련이죠.

복잡한 설정 파일 대신 CLI 명령어로 모델 상태를 한눈에 파악하고 관리하고 싶은 분들을 위해 openclaw models 사용법을 정리했어요.

필요한 것

• OpenClaw CLI
• 설치된 Provider Plugin (openclaw plugins list로 확인 가능)

빠른 시작

5분 만에 모델 설정을 마치는 4단계 프로세스예요.

1. 모델 스캔: openclaw models scan 명령어로 사용 가능한 모델을 찾아요.
2. 목록 확인: openclaw models list를 입력해 전체 모델 리스트를 확인해요.
3. 기본 모델 설정: openclaw models set <model-or-alias>로 자주 쓸 모델을 지정해요.
4. 상태 점검: openclaw models status로 설정이 올바른지 최종 확인해요.

openclaw models scan
openclaw models list
openclaw models set openai/gpt-4o
openclaw models status

주요 기능 활용하기

모델 상태 및 인증 확인

openclaw models status는 현재 설정된 기본 모델, Fallback 모델, 그리고 인증 상태를 요약해서 보여줘요.

• --probe: 각 Provider에 실제 요청을 보내 인증이 유효한지 실시간으로 테스트해요. (토큰이 소모될 수 있어요.)
• --agent <id>: 특정 Agent의 모델 및 인증 상태를 검사할 때 사용해요.
• --check: 인증이 만료되었거나 누락된 경우 종료 코드를 반환해서 스크립트에서 활용하기 좋아요.

모델 지정 규칙

models set 명령어를 사용할 때 모델 ID에 /가 포함되어 있다면 주의가 필요해요.

• OpenRouter처럼 모델 ID 자체에 /가 들어가는 경우, openrouter/moonshotai/kimi-k2와 같이 Provider 프리픽스를 반드시 포함해야 해요. OpenClaw는 첫 번째 /를 기준으로 Provider와 모델을 구분하기 때문이에요.
• Provider를 생략하면 기본 Provider의 모델이나 Alias로 인식해요.

인증 프로필 관리

Provider의 인증 흐름을 실행하려면 다음 명령어를 사용하세요.

openclaw models auth login --provider <id>

다른 기기에서 생성한 토큰이 있다면 setup-token이나 paste-token 명령어로 간편하게 인증을 마칠 수 있어요.

참고: Anthropic의 경우 정책에 따라 Claude Code 외부에서의 구독 사용이 제한될 수 있으니, 사용 전 현재 약관을 꼭 확인해 보세요.

문제 해결

• 인증 만료가 의심될 때: openclaw models status --check를 실행하세요. 만료된 경우 종료 코드 1, 만료 예정인 경우 2를 반환해요.
• 모델을 찾을 수 없을 때: 모델 ID에 /가 포함된 경우 Provider 이름을 앞에 붙였는지 확인하세요. (예: provider/model/id)

AI Setup Assistant

다음 단계

• Models
• Getting started