---
read_when:
    - 기본 모델을 변경하거나 제공자 인증 상태를 보려는 경우
    - 사용 가능한 모델/프로바이더를 스캔하고 인증 프로필을 디버그하려는 경우
summary: CLI reference for `openclaw models`(status/list/set/scan, 별칭, 폴백, 인증)
title: 모델
x-i18n:
    generated_at: "2026-06-27T17:18:34Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 15d0a01e0f8f971996359413306a1c694e5a787eaef69b13eb8ac63c2a7c8990
    source_path: cli/models.md
    workflow: 16
---

# `openclaw models`

모델 검색, 스캔, 구성(기본 모델, 대체 모델, 인증 프로필).

관련 항목:

- 제공자 + 모델: [모델](/ko/providers/models)
- 모델 선택 개념 + `/models` 슬래시 명령: [모델 개념](/ko/concepts/models)
- 제공자 인증 설정: [시작하기](/ko/start/getting-started)

## 일반 명령

```bash
openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models scan
```

`openclaw models status`는 확인된 기본값/대체 모델과 인증 개요를 표시합니다.
제공자 사용량 스냅샷을 사용할 수 있으면 OAuth/API 키 상태 섹션에
제공자 사용 기간과 할당량 스냅샷이 포함됩니다.
현재 사용 기간 제공자: Anthropic, GitHub Copilot, Gemini CLI, OpenAI,
MiniMax, Xiaomi, z.ai. 사용량 인증은 사용 가능한 경우 제공자별 훅에서
가져오며, 그렇지 않으면 OpenClaw가 인증 프로필, env 또는 config에서
일치하는 OAuth/API 키 자격 증명으로 대체합니다.
`--json` 출력에서 `auth.providers`는 env/config/store를 인식하는 제공자
개요이고, `auth.oauth`는 인증 저장소 프로필 상태만 나타냅니다.
구성된 각 제공자 프로필에 대해 실시간 인증 프로브를 실행하려면 `--probe`를 추가하세요.
프로브는 실제 요청입니다(토큰을 소비하고 rate limit를 트리거할 수 있음).
구성된 에이전트의 모델/인증 상태를 검사하려면 `--agent <id>`를 사용하세요. 생략하면
명령은 설정된 경우 `OPENCLAW_AGENT_DIR`을 사용하고, 그렇지 않으면
구성된 기본 에이전트를 사용합니다.
프로브 행은 인증 프로필, env 자격 증명 또는 `models.json`에서 올 수 있습니다.
OpenAI ChatGPT/Codex OAuth 문제 해결에는 `openclaw models status`,
`openclaw models auth list --provider openai`, 그리고
`openclaw config get agents.defaults.model --json`이 에이전트가
네이티브 Codex 런타임을 통해 `openai/*`에 사용할 수 있는 `openai` OAuth 프로필을
가지고 있는지 확인하는 가장 빠른 방법입니다. [OpenAI 제공자 설정](/ko/providers/openai#check-and-recover-codex-oauth-routing)을 참조하세요.

참고:

- `models set <model-or-alias>`는 `provider/model` 또는 별칭을 허용합니다.
- `models list`는 읽기 전용입니다. config, 인증 프로필, 기존 카탈로그
  상태, 제공자 소유 카탈로그 행을 읽지만
  `models.json`을 다시 쓰지는 않습니다.
- `Auth` 열은 제공자 수준이며 읽기 전용입니다. 로컬 인증 프로필
  메타데이터, env 마커, 구성된 제공자 키, 로컬 제공자
  마커, AWS Bedrock env/profile 마커, Plugin 합성 인증 메타데이터에서
  계산됩니다. 제공자 런타임을 로드하거나, keychain 비밀을 읽거나, 제공자
  API를 호출하거나, 모델별 정확한 실행 준비 상태를 증명하지 않습니다.
- `models list --all --provider <id>`는 아직 해당 제공자로 인증하지 않았더라도
  Plugin 매니페스트 또는 번들 제공자 카탈로그 메타데이터의 제공자 소유 정적 카탈로그
  행을 포함할 수 있습니다. 해당 행은 일치하는 인증이 구성될 때까지
  계속 사용할 수 없음으로 표시됩니다.
- `models list`는 제공자 카탈로그 검색이 느릴 때도 제어 평면의 응답성을 유지합니다.
  기본 보기와 구성된 보기는 짧은 대기 후 구성된 모델 행 또는 합성 모델 행으로
  대체하고, 검색은 백그라운드에서 완료되도록 둡니다.
  정확한 전체 검색 카탈로그가 필요하고 제공자 검색을 기다릴 의향이 있으면
  `--all`을 사용하세요.
- 광범위한 `models list --all`은 제공자 런타임 보조 훅을 로드하지 않고
  매니페스트 카탈로그 행을 레지스트리 행 위에 병합합니다. 제공자 필터링 매니페스트
  빠른 경로는 `static`으로 표시된 제공자만 사용합니다. `refreshable`로 표시된
  제공자는 레지스트리/캐시 기반으로 유지되고 매니페스트 행을 보조 항목으로 추가하며,
  `runtime`으로 표시된 제공자는 레지스트리/런타임 검색에 남습니다.
- `models list`는 네이티브 모델 메타데이터와 런타임 한도를 구분해서 유지합니다. 표
  출력에서 유효 런타임 한도가 네이티브 컨텍스트 윈도와 다르면 `Ctx`는
  `contextTokens/contextWindow`를 표시합니다. JSON 행은 제공자가 해당 한도를 노출할 때
  `contextTokens`를 포함합니다.
- `models list --provider <id>`는 `moonshot` 또는
  `openai` 같은 제공자 id로 필터링합니다. `Moonshot AI` 같은 대화형 제공자
  선택기의 표시 레이블은 허용하지 않습니다.
- 모델 참조는 **첫 번째** `/`를 기준으로 분할해 파싱됩니다. 모델 ID에 `/`가 포함되어 있으면(OpenRouter 스타일) 제공자 접두사를 포함하세요(예: `openrouter/moonshotai/kimi-k2`).
- 제공자를 생략하면 OpenClaw는 입력을 먼저 별칭으로 확인하고, 그다음
  해당 정확한 모델 id에 대한 고유한 구성된 제공자 일치로 확인하며, 그 후에야
  지원 중단 경고와 함께 구성된 기본 제공자로 대체합니다.
  해당 제공자가 구성된 기본 모델을 더 이상 노출하지 않으면 OpenClaw는
  오래된 제거된 제공자 기본값을 표시하는 대신 첫 번째 구성된 제공자/모델로
  대체합니다.
- `models status`는 인증 출력에서 비밀로 마스킹하는 대신 비밀이 아닌 자리표시자(예: `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`)에 대해 `marker(<value>)`를 표시할 수 있습니다.

### 모델 스캔

`models scan`은 OpenRouter의 공개 `:free` 카탈로그를 읽고 대체 모델 사용 후보의
순위를 매깁니다. 카탈로그 자체는 공개되어 있으므로 메타데이터 전용 스캔에는
OpenRouter 키가 필요하지 않습니다.

기본적으로 OpenClaw는 실시간 모델 호출로 도구와 이미지 지원을 프로브하려고 시도합니다.
구성된 OpenRouter 키가 없으면 명령은 메타데이터 전용
출력으로 대체하고, `:free` 모델도 프로브와 추론에는 `OPENROUTER_API_KEY`가
필요하다고 설명합니다.

옵션:

- `--no-probe`(메타데이터 전용, config/secrets 조회 없음)
- `--min-params <b>`
- `--max-age-days <days>`
- `--provider <name>`
- `--max-candidates <n>`
- `--timeout <ms>`(카탈로그 요청 및 프로브별 timeout)
- `--concurrency <n>`
- `--yes`
- `--no-input`
- `--set-default`
- `--set-image`
- `--json`

`--set-default`와 `--set-image`에는 실시간 프로브가 필요합니다. 메타데이터 전용 스캔
결과는 정보 제공용이며 config에 적용되지 않습니다.

### 모델 상태

옵션:

- `--json`
- `--plain`
- `--check`(종료 1=만료/누락, 2=만료 임박)
- `--probe`(구성된 인증 프로필의 실시간 프로브)
- `--probe-provider <name>`(제공자 하나 프로브)
- `--probe-profile <id>`(반복 또는 쉼표로 구분된 프로필 id)
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
- `--agent <id>`(구성된 에이전트 id, `OPENCLAW_AGENT_DIR` 재정의)

`--json`은 stdout을 JSON 페이로드 전용으로 유지합니다. 인증 프로필, 제공자,
시작 진단은 stderr로 라우팅되어 스크립트가 stdout을 `jq` 같은 도구로 직접
파이프할 수 있습니다.

프로브 상태 버킷:

- `ok`
- `auth`
- `rate_limit`
- `billing`
- `timeout`
- `format`
- `unknown`
- `no_model`

예상되는 프로브 세부 정보/이유 코드 사례:

- `excluded_by_auth_order`: 저장된 프로필은 있지만 명시적
  `auth.order.<provider>`가 이를 생략했으므로 프로브는 시도하는 대신
  제외를 보고합니다.
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
  프로필은 있지만 적합하지 않거나 확인할 수 없습니다.
- `no_model`: 제공자 인증은 있지만 OpenClaw가 해당 제공자에 대해 프로브 가능한
  모델 후보를 확인할 수 없습니다.

## 별칭 + 대체 모델

```bash
openclaw models aliases list
openclaw models fallbacks list
```

## 인증 프로필

```bash
openclaw models auth add
openclaw models auth list [--provider <id>] [--json]
openclaw models auth login --provider <id>
openclaw models auth login --provider openai --profile-id openai:work
openclaw models auth paste-api-key --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
```

`models auth add`는 대화형 인증 도우미입니다. 선택한 제공자에 따라 제공자 인증
흐름(OAuth/API 키)을 시작하거나 수동 토큰 붙여넣기로 안내할 수 있습니다.

`models auth list`는 선택한 에이전트에 저장된 인증 프로필을
토큰, API 키 또는 OAuth 비밀 자료를 출력하지 않고 나열합니다. `openai` 같은
제공자 하나로 필터링하려면 `--provider <id>`를 사용하고, 스크립팅에는 `--json`을 사용하세요.

`models auth login`은 제공자 Plugin의 인증 흐름(OAuth/API 키)을 실행합니다. 설치된 제공자를 보려면
`openclaw plugins list`를 사용하세요.
인증 결과를 특정 구성된 에이전트 저장소에 쓰려면
`openclaw models auth --agent <id> <subcommand>`를 사용하세요. 상위 `--agent` 플래그는
`add`, `list`, `login`, `paste-api-key`, `setup-token`, `paste-token`, 그리고
`login-github-copilot`에서 적용됩니다.

OpenAI 모델의 경우 `--provider openai`는 기본적으로 ChatGPT/Codex 계정 로그인으로 설정됩니다.
OpenAI API 키 프로필을 추가하려는 경우에만 `--method api-key`를 사용하세요.
일반적으로 Codex 구독 제한에 대한 백업으로 사용합니다. 이전 레거시 OpenAI Codex 접두사 인증/프로필 상태를 `openai`로 마이그레이션하려면 `openclaw doctor --fix`를 실행하세요.

예시:

```bash
openclaw models auth login --provider openai --set-default
openclaw models auth login --provider openai --method api-key
openclaw models auth paste-api-key --provider openai
openclaw models auth list --provider openai
```

참고:

- `login`은 로그인 중 명명된 프로필을 지원하는 제공자에 대해
  `--profile-id <id>`를 허용합니다. 같은 제공자의 여러 로그인을 분리해서
  유지하려면 이를 사용하세요.
- `paste-api-key`는 다른 곳에서 생성한 API 키를 허용하고, 키
  값을 입력받은 뒤 `--profile-id`를 전달하지 않으면 기본 프로필 id `<provider>:manual`에
  씁니다. 자동화에서는 예를 들어
  `printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai`처럼 stdin으로 키를 파이프하세요.
- `setup-token`과 `paste-token`은 토큰 인증 방법을 노출하는 제공자를 위한
  일반 토큰 명령으로 유지됩니다.
- `setup-token`에는 대화형 TTY가 필요하며 제공자의 토큰 인증
  방법을 실행합니다(제공자가 노출하는 경우 기본값은 해당 제공자의 `setup-token` 방법).
- `paste-token`은 다른 곳이나 자동화에서 생성한 토큰 문자열을 허용합니다.
- `paste-token`에는 `--provider`가 필요하며, 기본적으로 토큰 값을 입력받고
  `--profile-id`를 전달하지 않으면 기본 프로필 id `<provider>:manual`에 씁니다.
- 자동화에서는 제공자 자격 증명이 셸 기록이나 프로세스 목록에 나타나지 않도록
  인수로 전달하는 대신 stdin으로 토큰을 파이프하세요.
- `paste-token --expires-in <duration>`은 `365d` 또는 `12h` 같은
  상대 기간에서 절대 토큰 만료 시각을 저장합니다.
- `openai`의 경우 OpenAI API 키와 ChatGPT/OAuth 토큰 자료는
  서로 다른 인증 형태입니다. `sk-...` OpenAI API 키에는 `paste-api-key`를 사용하고
  토큰 인증 자료에만 `paste-token`을 사용하세요.
- Anthropic 참고: Anthropic 직원이 OpenClaw 스타일 Claude CLI 사용이 다시 허용된다고 알려왔으므로, Anthropic이 새 정책을 게시하지 않는 한 OpenClaw는 이 통합에서 Claude CLI 재사용과 `claude -p` 사용을 승인된 것으로 취급합니다.
- Anthropic `setup-token` / `paste-token`은 지원되는 OpenClaw 토큰 경로로 계속 사용할 수 있지만, 이제 OpenClaw는 사용 가능한 경우 Claude CLI 재사용과 `claude -p`를 선호합니다.

## 관련 항목

- [CLI 참조](/ko/cli)
- [모델 선택](/ko/concepts/model-providers)
- [모델 장애 조치](/ko/concepts/model-failover)