모델 CLI

인증 프로필 순환, 쿨다운, 폴백과의 상호작용은 /concepts/model-failover를 참고하세요. 프로바이더 개요 + 예시: /concepts/model-providers.

모델 선택 방식

OpenClaw는 다음 순서로 모델을 선택합니다:

  1. 기본 모델 (agents.defaults.model.primary 또는 agents.defaults.model).
  2. agents.defaults.model.fallbacks의 폴백 (순서대로).
  3. 프로바이더 인증 장애 조치는 다음 모델로 이동하기 전에 프로바이더 내부에서 발생합니다.

관련:

  • agents.defaults.models는 OpenClaw가 사용할 수 있는 모델의 허용 목록/카탈로그입니다 (별칭 포함).
  • agents.defaults.imageModel은 기본 모델이 이미지를 받을 수 없을 때만 사용됩니다.
  • 에이전트별 기본값은 agents.list[].model과 바인딩으로 agents.defaults.model을 오버라이드할 수 있습니다 (/concepts/multi-agent 참고).

모델 정책 요약

  • 기본 모델은 사용 가능한 가장 강력한 최신 세대 모델로 설정하세요.
  • 비용/지연 시간에 민감한 작업과 중요도가 낮은 채팅에는 폴백을 사용하세요.
  • 도구가 활성화된 에이전트나 신뢰할 수 없는 입력에는 이전/약한 모델 티어를 피하세요.

설정 마법사 (권장)

설정을 직접 편집하고 싶지 않다면 온보딩 마법사를 실행하세요:

openclaw onboard

OpenAI Code (Codex) 구독 (OAuth)과 Anthropic (API 키 또는 claude setup-token)을 포함한 일반 프로바이더의 모델 + 인증을 설정할 수 있습니다.

설정 키 (개요)

  • agents.defaults.model.primary와 agents.defaults.model.fallbacks
  • agents.defaults.imageModel.primary와 agents.defaults.imageModel.fallbacks
  • agents.defaults.models (허용 목록 + 별칭 + 프로바이더 파라미터)
  • models.providers (models.json에 작성되는 커스텀 프로바이더)

모델 참조는 소문자로 정규화됩니다. z.ai/* 같은 프로바이더 별칭은 zai/*로 정규화됩니다.

OpenCode를 포함한 프로바이더 설정 예시는 /gateway/configuration에 있습니다.

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

agents.defaults.models가 설정되면 /model과 세션 오버라이드의 허용 목록이 됩니다. 사용자가 허용 목록에 없는 모델을 선택하면 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-5" },
    models: {
      "anthropic/claude-sonnet-4-5": { 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)은 모델 패밀리 + 사용 가능한 프로바이더의 간결한 번호 선택기입니다.
  • Discord에서 /model과 /models는 프로바이더 및 모델 드롭다운과 Submit 단계가 포함된 대화형 선택기를 엽니다.
  • /model <#>로 해당 선택기에서 선택합니다.
  • /model status는 인증 후보와 설정된 경우 프로바이더 엔드포인트 baseUrl + api 모드를 포함한 상세 보기입니다.
  • 모델 참조는 첫 번째 /를 기준으로 분리됩니다. /model <ref> 입력 시 provider/model을 사용하세요.
  • 모델 ID 자체에 /가 포함된 경우 (OpenRouter 스타일) 프로바이더 접두사를 포함해야 합니다 (예: /model openrouter/moonshotai/kimi-k2).
  • 프로바이더를 생략하면 OpenClaw가 입력을 별칭 또는 기본 프로바이더의 모델로 처리합니다 (모델 ID에 /가 없을 때만 동작).

전체 명령어 동작/설정: 슬래시 명령어.

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 <name>: 프로바이더로 필터
  • --plain: 한 줄에 하나의 모델
  • --json: 기계 판독 가능 출력

models status

확인된 기본 모델, 폴백, 이미지 모델, 설정된 프로바이더의 인증 개요를 표시합니다. 인증 스토어에서 발견된 프로필의 OAuth 만료 상태도 보여줍니다 (기본 24시간 내 경고). --plain은 확인된 기본 모델만 출력합니다. OAuth 상태는 항상 표시됩니다 (--json 출력에도 포함). 설정된 프로바이더에 자격 증명이 없으면 models status가 Missing auth 섹션을 출력합니다. JSON에는 auth.oauth (경고 윈도우 + 프로필)와 auth.providers (프로바이더별 유효 인증)가 포함됩니다. 자동화를 위해 --check를 사용하세요 (누락/만료 시 종료 1, 만료 임박 시 2).

인증 방식은 프로바이더/계정에 따라 다릅니다. 상시 운영 게이트웨이 호스트에서는 API 키가 일반적으로 가장 예측 가능합니다. 구독 토큰 흐름도 지원됩니다.

예시 (Anthropic setup-token):

claude setup-token
openclaw models status

스캔 (OpenRouter 무료 모델)

openclaw models scan은 OpenRouter의 무료 모델 카탈로그를 검사하고, 선택적으로 모델의 도구 및 이미지 지원을 프로빙할 수 있습니다.

주요 플래그:

  • --no-probe: 라이브 프로브 건너뛰기 (메타데이터만)
  • --min-params <b>: 최소 파라미터 크기 (십억)
  • --max-age-days <days>: 오래된 모델 건너뛰기
  • --provider <name>: 프로바이더 접두사 필터
  • --max-candidates <n>: 폴백 목록 크기
  • --set-default: 첫 번째 선택을 agents.defaults.model.primary로 설정
  • --set-image: 첫 번째 이미지 선택을 agents.defaults.imageModel.primary로 설정

프로빙에는 OpenRouter API 키가 필요합니다 (인증 프로필 또는 OPENROUTER_API_KEY에서). 키가 없으면 --no-probe로 후보만 나열하세요.

스캔 결과 순위:

  1. 이미지 지원
  2. 도구 지연 시간
  3. 컨텍스트 크기
  4. 파라미터 수

입력

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

TTY에서 실행하면 폴백을 대화형으로 선택할 수 있습니다. 비대화형 모드에서는 --yes를 전달하여 기본값을 수락하세요.

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

models.providers의 커스텀 프로바이더는 에이전트 디렉터리 (기본값 ~/.openclaw/agents/<agentId>/agent/models.json) 아래의 models.json에 기록됩니다. models.mode가 replace로 설정되지 않는 한 기본적으로 병합됩니다.

매칭되는 프로바이더 ID에 대한 병합 모드 우선순위:

  • 에이전트 models.json에 이미 존재하는 비어있지 않은 baseUrl이 우선.
  • 에이전트 models.json의 비어있지 않은 apiKey는 해당 프로바이더가 현재 설정/인증 프로필 컨텍스트에서 SecretRef 관리되지 않을 때만 우선.
  • SecretRef 관리 프로바이더 apiKey 값은 해결된 비밀이 아닌 소스 마커(ENV_VAR_NAME은 환경 참조, secretref-managed는 파일/실행 참조)에서 새로고침.
  • SecretRef 관리 프로바이더 헤더 값은 소스 마커(secretref-env:ENV_VAR_NAME은 환경 참조, secretref-managed는 파일/실행 참조)에서 새로고침.
  • 에이전트 apiKey/baseUrl이 비어있거나 누락되면 설정 models.providers로 폴백.
  • 다른 프로바이더 필드는 설정과 정규화된 카탈로그 데이터에서 새로고침.

마커 영속은 소스 권위적입니다: OpenClaw는 해결된 런타임 비밀 값이 아닌 활성 소스 설정 스냅샷(해석 전)에서 마커를 기록합니다. 이는 openclaw agent 같은 명령어 기반 경로를 포함하여 OpenClaw가 models.json을 재생성할 때마다 적용됩니다.

arrow_back
이전
Models
다음
Model Providers
arrow_forward