모델 CLI

모델 참조는 제공자와 모델을 선택합니다. 일반적으로 저수준 에이전트 런타임은 선택하지 않습니다. 예를 들어 openai/gpt-5.5는 agents.defaults.agentRuntime.id에 따라 일반 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가 있으면 이를 사용하고, 없으면 명시적인 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(허용 목록 + 별칭 + 제공자 매개변수)
• 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>에 표시되는 정확한 제공자/모델입니다. 허용 목록이 활성화되어 있을 때는 단순 로컬 파일 이름이나 표시 이름만으로는 충분하지 않습니다.

허용 목록 구성 예시:

{
  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.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

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

# models list

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

--allboolean

전체 카탈로그입니다. 인증이 구성되기 전에 번들된 provider 소유의 정적 카탈로그 행을 포함하므로, 탐색 전용 보기에서 일치하는 provider 자격 증명을 추가하기 전까지 사용할 수 없는 모델도 표시할 수 있습니다.

--localboolean

로컬 provider만 표시합니다.

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

--plainboolean

한 줄에 모델 하나씩 출력합니다.

--jsonboolean

기계가 읽을 수 있는 출력입니다.

# models status

확정된 기본 모델, 폴백, 이미지 모델, 구성된 provider의 인증 개요를 표시합니다. 또한 auth store에서 찾은 프로필의 OAuth 만료 상태도 표시합니다(기본적으로 24시간 이내이면 경고). --plain은 확정된 기본 모델만 출력합니다.

예시(Claude CLI):

claude auth login
openclaw models status

# 스캔(OpenRouter 무료 모델)

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

--no-probeboolean

실시간 프로브를 건너뜁니다(메타데이터만).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

agents.defaults.model.primary를 첫 번째 선택 항목으로 설정합니다.

--set-imageboolean

agents.defaults.imageModel.primary를 첫 번째 이미지 선택 항목으로 설정합니다.

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

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

입력:

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

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

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

models.providers의 사용자 지정 provider는 에이전트 디렉터리 아래의 models.json에 기록됩니다(기본값 ~/.openclaw/agents/<agentId>/agent/models.json). 이 파일은 models.mode가 replace로 설정되지 않는 한 기본적으로 병합됩니다.

# 관련 항목

• 에이전트 런타임 — PI, Codex 및 기타 에이전트 루프 런타임
• 구성 참조 — 모델 config 키
• 이미지 생성 — 이미지 모델 구성
• 모델 장애 조치 — 폴백 체인
• 모델 provider — provider 라우팅 및 인증
• 음악 생성 — 음악 모델 구성
• 비디오 생성 — 비디오 모델 구성