OpenClaw 모델 설정 가이드: 우선순위 및 폴백 구성하기

여러 LLM을 사용하다 보면 모델 설정을 바꾸거나 API 키를 관리하는 게 정말 번거로울 때가 많죠? 특히 모델이 갑자기 응답하지 않을 때 자동으로 다른 모델로 넘어가게 설정하는 과정은 꽤나 복잡해요. OpenClaw는 이런 고민을 해결해 주기 위해 아주 유연한 모델 관리 시스템을 제공하고 있어요.

인증 프로필 교체, 재시도 대기 시간(cooldowns), 그리고 이것이 fallback과 어떻게 상호작용하는지에 대해서는 /concepts/model-failover를 참고하세요. 제공자(provider)별 개요와 예시는 /concepts/model-providers에서 확인할 수 있어요.

모델 선택 작동 방식

OpenClaw는 다음 순서에 따라 모델을 선택해요.

Primary 모델 (agents.defaults.model.primary 또는 agents.defaults.model).
agents.defaults.model.fallbacks에 지정된 Fallbacks (순서대로).
다음 모델로 넘어가기 전, 해당 provider 내부에서 Provider auth failover가 먼저 일어납니다.

빠른 모델 정책

primary 모델은 여러분이 사용할 수 있는 가장 강력한 최신 세대 모델로 설정하세요.
비용이나 지연 시간(latency)에 민감한 작업, 또는 중요도가 낮은 채팅에는 fallback을 활용하세요.
도구(tool)를 사용하는 에이전트나 신뢰할 수 없는 입력값의 경우, 오래되거나 성능이 낮은 모델 티어는 피하는 것이 좋아요.

온보딩 (추천 방식)

설정을 직접 수정하고 싶지 않다면 온보딩 명령어를 실행해 보세요.

openclaw onboard

이 명령어를 통해 OpenAI Code (Codex) subscription (OAuth) 및 Anthropic (API key 또는 claude setup-token)을 포함한 주요 provider의 모델과 인증 설정을 마칠 수 있어요.

설정 키 (개요)

agents.defaults.model.primary 및 agents.defaults.model.fallbacks
agents.defaults.imageModel.primary 및 agents.defaults.imageModel.fallbacks
agents.defaults.imageGenerationModel.primary 및 agents.defaults.imageGenerationModel.fallbacks
agents.defaults.models (허용 목록 + 별칭 + provider 파라미터)
models.providers (models.json에 작성된 커스텀 provider)

모델 참조 이름은 소문자로 정규화돼요. z.ai/* 같은 provider 별칭은 zai/*로 정규화됩니다.

OpenCode를 포함한 provider 설정 예시는 /providers/opencode에서 볼 수 있어요.

”Model is not allowed” 오류 (응답이 멈추는 이유)

agents.defaults.models가 설정되어 있다면, 이 목록은 /model 명령어와 세션 오버라이드를 위한 **허용 목록(allowlist)**이 돼요. 사용자가 이 목록에 없는 모델을 선택하면 OpenClaw는 다음 메시지를 반환해요.

Model "provider/model" is not allowed. Use /model to list available models.

이 과정은 일반적인 응답이 생성되기 전에 발생하기 때문에, 마치 메시지에 “응답하지 않는” 것처럼 느껴질 수 있어요. 이 문제를 해결하려면 다음 중 하나를 수행하세요.

해당 모델을 agents.defaults.models에 추가하세요.
허용 목록을 비우세요 (agents.defaults.models 제거).
/model list에서 모델을 선택하세요.

허용 목록 설정 예시:

{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-6" },
    models: {
      "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
      "anthropic/claude-opus-4-6": { alias: "Opus" },
    },
  },
}

채팅 중 모델 전환 (`/model`)

재시작 없이 현재 세션의 모델을 즉시 바꿀 수 있어요.

/model
/model list
/model 3
/model openai/gpt-5.2
/model status

참고 사항:

/model (및 /model list)은 번호가 매겨진 간결한 선택창을 보여줘요 (모델 제품군 + 사용 가능한 provider).
Discord에서는 /model과 /models 명령어가 provider와 모델 드롭다운, 제출 단계가 포함된 대화형 선택창을 엽니다.
/model <번호>를 입력하면 해당 선택창에서 모델을 선택할 수 있어요.
/model은 세션 선택 사항을 즉시 업데이트해요. 에이전트가 대기 중이라면 다음 실행부터 바로 새 모델을 사용합니다. 에이전트가 작업 중이라면 현재 작업이 끝난 뒤 대기 중이거나 미래의 작업에 새 모델이 적용돼요.
/model status는 상세 보기 모드예요 (인증 후보군, 설정된 경우 provider 엔드포인트 baseUrl + api 모드 표시).
모델 참조는 첫 번째 /를 기준으로 파싱돼요. /model <ref>를 입력할 때는 provider/model 형식을 사용하세요.
모델 ID 자체에 /가 포함된 경우(OpenRouter 방식), provider 접두사를 반드시 포함해야 해요 (예: /model openrouter/moonshotai/kimi-k2).
provider를 생략하면 OpenClaw는 입력을 별칭이나 기본 provider의 모델로 취급합니다 (모델 ID에 /가 없을 때만 작동).

전체 명령어 동작 및 설정: Slash commands.

CLI 명령어

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

openclaw models (하위 명령어 없음)는 models status의 단축어예요.

`models list`

기본적으로 설정된 모델들을 보여줍니다. 유용한 플래그:

--all: 전체 카탈로그 표시
--local: 로컬 provider만 표시
--provider <name>: 특정 provider로 필터링
--plain: 한 줄에 모델 하나씩 출력
--json: 기계 읽기 가능한 형식으로 출력

`models status`

확정된 primary 모델, fallback, 이미지 모델, 그리고 설정된 provider의 인증 개요를 보여줍니다. 인증 저장소에 있는 프로필의 OAuth 만료 상태도 확인할 수 있어요 (기본적으로 24시간 이내 만료 시 경고). --plain은 확정된 primary 모델만 출력해요. OAuth 상태는 항상 표시되며 --json 출력에도 포함됩니다. 설정된 provider에 자격 증명이 없다면 models status는 Missing auth 섹션을 출력해요. JSON 출력에는 auth.oauth (경고 창 + 프로필)와 auth.providers (provider별 유효 인증)가 포함됩니다. 자동화를 위해 --check를 사용하세요 (인증 누락/만료 시 종료 코드 1, 만료 임박 시 2 반환).

인증 방식은 provider나 계정에 따라 달라요. 항상 켜져 있는 Gateway 호스트의 경우 API key가 가장 예측 가능하며, 구독 토큰 방식도 지원됩니다.

예시 (Anthropic setup-token):

claude setup-token
openclaw models status

스캐닝 (OpenRouter 무료 모델)

openclaw models scan은 OpenRouter의 무료 모델 카탈로그를 조사하고, 선택적으로 모델의 도구(tool) 및 이미지 지원 여부를 테스트해요.

주요 플래그:

--no-probe: 실제 테스트를 건너뛰고 메타데이터만 확인
--min-params <b>: 최소 파라미터 크기 (10억 단위)
--max-age-days <days>: 오래된 모델 제외
--provider <name>: provider 접두사 필터링
--max-candidates <n>: fallback 목록 크기
--set-default: 첫 번째 선택지를 agents.defaults.model.primary로 설정
--set-image: 첫 번째 이미지 선택지를 agents.defaults.imageModel.primary로 설정

테스트(probing)를 하려면 OpenRouter API key가 필요해요 (인증 프로필 또는 OPENROUTER_API_KEY에서 가져옴). 키가 없다면 --no-probe를 사용하여 후보 목록만 확인하세요.

스캔 결과는 다음 순서로 순위가 매겨집니다.

이미지 지원 여부
도구(tool) 지연 시간
컨텍스트 크기
파라미터 수

입력 데이터:

OpenRouter /models 목록 (:free 필터링)
인증 프로필 또는 OPENROUTER_API_KEY의 OpenRouter API key 필요 (/environment 참고)
선택적 필터: --max-age-days, --min-params, --provider, --max-candidates
테스트 제어: --timeout, --concurrency

TTY 환경에서 실행하면 대화형으로 fallback을 선택할 수 있어요. 비대화형 모드에서는 --yes를 전달하여 기본값을 수락하세요.

모델 레지스트리 (`models.json`)

models.providers에 설정된 커스텀 provider는 에이전트 디렉토리(기본값 ~/.openclaw/agents/<agentId>/agent/models.json)의 models.json에 작성돼요. models.mode가 replace로 설정되지 않는 한, 이 파일은 기본적으로 병합(merge)됩니다.

동일한 provider ID가 있을 때의 병합 우선순위:

에이전트 models.json에 이미 존재하는 비어 있지 않은 baseUrl이 우선합니다.
에이전트 models.json의 비어 있지 않은 apiKey는 해당 provider가 현재 설정/인증 프로필 컨텍스트에서 SecretRef로 관리되지 않을 때만 우선합니다.
SecretRef로 관리되는 provider의 apiKey 값은 확인된 비밀 값을 유지하는 대신 소스 마커(환경 변수 참조의 경우 ENV_VAR_NAME, 파일/실행 참조의 경우 secretref-managed)에서 새로고침됩니다.
SecretRef로 관리되는 provider 헤더 값은 소스 마커(환경 변수 참조의 경우 secretref-env:ENV_VAR_NAME, 파일/실행 참조의 경우 secretref-managed)에서 새로고침됩니다.
에이전트의 apiKey/baseUrl이 비어 있거나 누락된 경우 설정 파일의 models.providers를 사용합니다.
기타 provider 필드는 설정 및 정규화된 카탈로그 데이터에서 새로고침됩니다.

마커 유지는 소스 권한을 따릅니다. OpenClaw는 런타임에 확인된 비밀 값이 아니라, 활성 소스 설정 스냅샷(확인 전 단계)의 마커를 작성해요. 이는 openclaw agent와 같은 명령어를 포함하여 OpenClaw가 models.json을 다시 생성할 때마다 적용됩니다.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.