모델 CLI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

모델 선택 작동 방식

​

선택 소스와 대체 동작

• 구성된 기본값(agents.defaults.model.primary 및 에이전트별 기본 모델)은 일반적인 시작점이며 agents.defaults.model.fallbacks를 사용합니다.
• 자동 대체 선택은 임시 복구 상태입니다. 이후 턴에서 알려진 문제가 있는 기본 모델을 먼저 탐색하지 않고 대체 체인을 계속 사용할 수 있도록 modelOverrideSource: "auto"와 함께 저장됩니다.
• 사용자 세션 선택은 정확합니다. /model, 모델 선택기, session_status(model=...), sessions.patch는 modelOverrideSource: "user"를 저장합니다. 해당 선택된 제공자/모델에 연결할 수 없으면 OpenClaw는 다른 구성된 모델로 넘어가지 않고 명확히 실패합니다.
• Cron --model / 페이로드 model은 작업별 기본 모델입니다. 작업이 명시적 페이로드 fallbacks를 제공하지 않는 한 구성된 대체 모델을 계속 사용합니다(엄격한 Cron 실행에는 fallbacks: [] 사용).
• CLI 기본 모델 및 허용 목록 선택기는 전체 내장 카탈로그를 로드하는 대신 명시적 models.providers.*.models를 나열하여 models.mode: "replace"를 따릅니다.
• Control UI 모델 선택기는 Gateway에 구성된 모델 뷰를 요청합니다. agents.defaults.models가 있으면 제공자 전체 provider/* 항목을 포함해 사용하고, 없으면 명시적 models.providers.*.models와 사용 가능한 인증이 있는 제공자를 사용합니다. 전체 내장 카탈로그는 view: "all"이 있는 models.list 또는 openclaw models list --all 같은 명시적 탐색 뷰에만 사용됩니다.

​

빠른 모델 정책

• 사용할 수 있는 가장 강력한 최신 세대 모델을 기본 모델로 설정하세요.
• 비용/지연 시간에 민감한 작업과 중요도가 낮은 채팅에는 대체 모델을 사용하세요.
• 도구가 활성화된 에이전트나 신뢰할 수 없는 입력에는 오래되었거나 약한 모델 계층을 피하세요.

​

온보딩(권장)

openclaw onboard

​

구성 키(개요)

• agents.defaults.model.primary 및 agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary 및 agents.defaults.imageModel.fallbacks
• agents.defaults.pdfModel.primary 및 agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary 및 agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary 및 agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models(허용 목록 + 별칭 + 제공자 매개변수 + provider/* 동적 제공자 항목)
• models.providers(models.json에 기록되는 사용자 지정 제공자)

​

안전한 허용 목록 편집

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

​

”모델이 허용되지 않음”(및 응답이 중단되는 이유)

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

{
  agents: {
    defaults: {
      models: {
        "openai-codex/*": {},
        "vllm/*": {},
      },
    },
  },
}

{
  agents: {
    defaults: {
      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.4
/model status

​

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

​

models list

​

models status

claude auth login
openclaw models status

​

스캔(OpenRouter 무료 모델)

1. 이미지 지원
2. 도구 지연 시간
3. 컨텍스트 크기
4. 매개변수 수

• OpenRouter /models 목록(필터 :free)
• 실시간 프로브에는 인증 프로필 또는 OPENROUTER_API_KEY의 OpenRouter API 키가 필요합니다(환경 변수 참조).
• 선택적 필터: --max-age-days, --min-params, --provider, --max-candidates
• 요청/프로브 제어: --timeout, --concurrency

​

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

​

관련 항목

• 에이전트 런타임 — PI, Codex 및 기타 에이전트 루프 런타임
• 구성 참조 — 모델 구성 키
• 이미지 생성 — 이미지 모델 구성
• 모델 장애 조치 — 폴백 체인
• 모델 제공자 — 제공자 라우팅 및 인증
• 음악 생성 — 음악 모델 구성
• 동영상 생성 — 동영상 모델 구성