모델 CLI

모델 참조는 제공자와 모델을 선택합니다. 일반적으로 저수준 에이전트 런타임을 선택하지는 않습니다. OpenAI 에이전트 참조가 주요 예외입니다. openai/gpt-5.5는 공식 OpenAI 제공자에서 기본적으로 Codex 앱 서버 런타임을 통해 실행됩니다. 명시적 런타임 재정의는 전체 에이전트나 세션이 아니라 제공자/모델 정책에 속합니다. Codex 런타임 모드에서 openai/gpt-* 참조는 API 키 과금을 의미하지 않습니다. 인증은 Codex 계정이나 openai-codex 인증 프로필에서 올 수 있습니다. 에이전트 런타임을 참조하세요.

모델 선택 작동 방식

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

선택 소스와 대체 동작

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

• 구성된 기본값(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

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>에 표시되는 정확한 provider/model입니다. 허용 목록이 활성화되어 있을 때는 순수 로컬 파일 이름이나 표시 이름만으로는 충분하지 않습니다.

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

{  agents: {    defaults: {      models: {        "openai-codex/*": {},        "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 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). 이 파일은 models.mode가 replace로 설정되지 않은 한 기본적으로 병합됩니다.

관련 항목

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