모델 CLI

모델 참조는 제공자와 모델을 선택합니다. 일반적으로 저수준 에이전트 런타임을 선택하지는 않습니다. OpenAI 에이전트 참조가 주요 예외입니다. openai/gpt-5.5는 공식 OpenAI 제공자에서 기본적으로 Codex 앱 서버 런타임을 통해 실행됩니다. 구독 Copilot 참조(github-copilot/*)는 추가로 외부 GitHub Copilot 에이전트 런타임 Plugin을 사용하도록 명시적으로 선택할 수 있습니다. 이 경로는 명시적으로 유지됩니다(auto 폴백 없음). 명시적 런타임 재정의는 전체 에이전트나 세션이 아니라 제공자/모델 정책에 속합니다. Codex 런타임 모드에서 openai/gpt-* 참조는 API 키 과금을 의미하지 않습니다. 인증은 Codex 계정 또는 openai OAuth 프로필에서 올 수 있습니다. 에이전트 런타임 및 GitHub Copilot 에이전트 런타임을 참조하세요.

모델 선택 작동 방식

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

선택 소스와 폴백 동작

동일한 provider/model도 어디에서 왔는지에 따라 다른 의미를 가질 수 있습니다.

• 구성된 기본값(agents.defaults.model.primary 및 에이전트별 기본 모델)은 일반적인 시작점이며 agents.defaults.model.fallbacks를 사용합니다.
• 자동 폴백 선택은 임시 복구 상태입니다. modelOverrideSource: "auto"로 저장되므로 이후 턴에서 매번 알려진 불량 기본 모델을 탐색하지 않고 폴백 체인을 계속 사용할 수 있습니다. OpenClaw는 주기적으로 원래 기본 모델을 다시 탐색하고, 복구되면 자동 선택을 지우며, 폴백/복구 전환을 상태 변경당 한 번 알립니다.
• 사용자 세션 선택은 정확합니다. /model, 모델 선택기, session_status(model=...), sessions.patch는 modelOverrideSource: "user"를 저장합니다. 선택한 제공자/모델에 도달할 수 없으면 OpenClaw는 다른 구성된 모델로 넘어가지 않고 눈에 보이게 실패합니다.
• agents.defaults.model.primary를 변경해도 기존 세션 선택은 다시 쓰지 않습니다. 상태에 This session is pinned to X; config primary Y will apply to new/unpinned sessions.라고 표시되면 /model default로 현재 세션 선택을 지워 구성된 기본 모델을 다시 상속하게 하세요.
• Cron --model / 페이로드 model은 작업별 기본 모델입니다. 작업이 명시적 페이로드 fallbacks를 제공하지 않는 한 구성된 폴백을 계속 사용합니다(엄격한 cron 실행에는 fallbacks: [] 사용).
• CLI 기본 모델 및 허용 목록 선택기는 전체 내장 카탈로그를 로드하는 대신 명시적 models.providers.*.models를 나열하여 models.mode: "replace"를 준수합니다.
• Control UI 모델 선택기는 Gateway에 구성된 모델 보기를 요청합니다. 있으면 제공자 전체 provider/* 항목을 포함한 agents.defaults.models, 없으면 명시적 models.providers.*.models와 사용 가능한 인증이 있는 제공자를 사용합니다. 전체 내장 카탈로그는 view: "all"이 있는 models.list 또는 openclaw models list --all 같은 명시적 찾아보기 보기에 예약됩니다.

빠른 모델 정책

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

온보딩(권장)

구성을 직접 편집하고 싶지 않다면 온보딩을 실행하세요.

openclaw onboard

일반적인 제공자의 모델 + 인증을 설정할 수 있으며, 여기에는 OpenAI Code (Codex) 구독(OAuth) 및 Anthropic(API 키 또는 Claude CLI)이 포함됩니다.

구성 키(개요)

• 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에 기록되는 사용자 지정 제공자)

안전한 허용 목록 편집

agents.defaults.models를 직접 업데이트할 때는 추가 쓰기를 사용하세요.

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

"모델이 허용되지 않음"(그리고 응답이 중단되는 이유)

agents.defaults.models가 설정되어 있으면 /model 및 세션 재정의의 허용 목록이 됩니다. 사용자가 해당 허용 목록에 없는 모델을 선택하면 OpenClaw는 다음을 반환합니다.

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

거부된 명령에 /model openai/gpt-5.5 --runtime codex 같은 런타임 재정의가 포함되어 있었다면 먼저 허용 목록을 수정한 다음 동일한 /model ... --runtime ... 명령을 다시 시도하세요. 네이티브 Codex 실행의 경우 선택된 모델은 여전히 openai/gpt-5.5입니다. codex 런타임은 하네스를 선택하고 Codex 인증을 별도로 사용합니다.

로컬/GGUF 모델의 경우 허용 목록에 전체 제공자 접두사 참조를 저장하세요. 예: ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf 또는 openclaw models list --provider <provider>에 표시된 정확한 제공자/모델입니다. 허용 목록이 활성 상태일 때는 로컬 파일 이름이나 표시 이름만으로는 충분하지 않습니다.

모든 모델을 수동으로 나열하지 않고 제공자를 제한하려면 agents.defaults.models에 provider/* 항목을 추가하세요.

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

이 정책을 사용하면 /model, /models 및 모델 선택기는 해당 제공자에 대해서만 발견된 카탈로그를 표시합니다. 선택한 제공자의 새 모델은 허용 목록을 편집하지 않아도 나타날 수 있습니다. 다른 제공자의 특정 모델 하나가 필요할 때는 정확한 provider/model 항목을 provider/* 항목과 혼합할 수 있습니다.

허용 목록 구성 예시:

{  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 default/model status

전체 명령 동작/구성: 슬래시 명령.

CLI 명령

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw models image-fallbacks add <provider/model>openclaw models image-fallbacks remove <provider/model>openclaw models image-fallbacks clear

openclaw models(하위 명령 없음)는 models status의 단축 명령입니다.

models list

기본적으로 구성되었거나 인증상 사용 가능한 모델을 표시합니다. 유용한 플래그:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> 제공자 ID로 필터링합니다. 예: moonshot. 대화형 선택기에 표시되는 레이블은 허용되지 않습니다.

models status

해석된 주 모델, 대체 모델, 이미지 모델, 구성된 제공자의 인증 개요를 표시합니다. 또한 인증 저장소에서 발견된 프로필의 OAuth 만료 상태를 드러냅니다(기본적으로 24시간 이내이면 경고). --plain은 해석된 주 모델만 출력합니다.

예시(Claude CLI):

claude auth loginopenclaw models status

스캔(OpenRouter 무료 모델)

openclaw models scan은 OpenRouter의 무료 모델 카탈로그를 검사하며, 선택적으로 도구 및 이미지 지원 여부를 확인하기 위해 모델을 프로브할 수 있습니다.

스캔 결과의 순위는 다음 기준으로 매겨집니다.

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

입력:

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

실시간 프로브가 TTY에서 실행되면 대체 모델을 대화형으로 선택할 수 있습니다. 비대화형 모드에서는 기본값을 수락하려면 --yes를 전달하세요. 메타데이터 전용 결과는 정보 제공용입니다. --set-default와 --set-image는 OpenClaw가 사용할 수 없는 키 없는 OpenRouter 모델을 구성하지 않도록 실시간 프로브가 필요합니다.

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

models.providers의 사용자 지정 제공자는 에이전트 디렉터리 아래의 models.json에 기록됩니다(기본값 ~/.openclaw/agents/<agentId>/agent/models.json). 제공자 Plugin 카탈로그는 에이전트의 Plugin 상태 아래에 생성된 Plugin 소유 카탈로그 조각으로 저장되며 자동으로 로드됩니다. 이 파일은 models.mode가 replace로 설정되지 않은 한 기본적으로 병합됩니다.

관련 항목

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