12 KiB
| read_when | summary | title | x-i18n | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
`openclaw models`에 대한 CLI 참조(status/list/set/scan, 별칭, 폴백, 인증) | 모델 |
|
openclaw models
모델 검색, 스캔, 구성(기본 모델, 대체 모델, 인증 프로필).
관련 항목:
일반 명령
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
Codex, 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/PI_CODING_AGENT_DIR을 사용하고, 그렇지 않으면
구성된 기본 에이전트를 사용합니다.
프로브 행은 인증 프로필, env 자격 증명 또는 models.json에서 가져올 수 있습니다.
Codex OAuth 문제 해결에는 openclaw models status,
openclaw models auth list --provider openai-codex, 그리고
openclaw config get agents.defaults.model --json이 에이전트가 네이티브 Codex 런타임을 통해
openai/*에 사용할 수 있는 openai-codex 인증 프로필을 가지고 있는지
확인하는 가장 빠른 방법입니다. OpenAI 제공자 설정을 참조하세요.
참고:
models set <model-or-alias>는provider/model또는 별칭을 허용합니다.models list는 읽기 전용입니다. config, 인증 프로필, 기존 카탈로그 상태, 제공자 소유 카탈로그 행을 읽지만models.json을 다시 쓰지는 않습니다.Auth열은 제공자 수준이며 읽기 전용입니다. 로컬 인증 프로필 메타데이터, env 마커, 구성된 제공자 키, 로컬 제공자 마커, AWS Bedrock env/프로필 마커, Plugin 합성 인증 메타데이터에서 계산됩니다. 제공자 런타임을 로드하거나, 키체인 secrets를 읽거나, 제공자 APIs를 호출하거나, 모델별 실행 준비 상태를 정확히 증명하지는 않습니다.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-codex같은 제공자 id로 필터링합니다.Moonshot AI같은 대화형 제공자 선택기의 표시 레이블은 허용하지 않습니다.- 모델 참조는 첫 번째
/를 기준으로 분할해 파싱됩니다. 모델 ID에/가 포함된 경우(OpenRouter 스타일), 제공자 접두사를 포함하세요(예:openrouter/moonshotai/kimi-k2). - 제공자를 생략하면 OpenClaw는 먼저 입력을 별칭으로 확인한 다음 해당 정확한 모델 id에 대한 고유한 구성된 제공자 일치로 확인하고, 그 다음에야 deprecation 경고와 함께 구성된 기본 제공자로 대체합니다. 해당 제공자가 더 이상 구성된 기본 모델을 노출하지 않으면 OpenClaw는 오래된 제거된 제공자 기본값을 표시하는 대신 첫 번째 구성된 제공자/모델로 대체합니다.
models status는 인증 출력에서 비밀이 아닌 자리표시자(예:OPENAI_API_KEY,secretref-managed,minimax-oauth,oauth:chutes,ollama-local)를 secrets로 마스킹하는 대신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>(카탈로그 요청 및 프로브별 제한 시간)--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>(반복 또는 쉼표로 구분된 프로필 ids)--probe-timeout <ms>--probe-concurrency <n>--probe-max-tokens <n>--agent <id>(구성된 에이전트 id;OPENCLAW_AGENT_DIR/PI_CODING_AGENT_DIR재정의)
--json은 stdout을 JSON 페이로드 전용으로 유지합니다. 인증 프로필, 제공자,
시작 진단은 stderr로 라우팅되므로 스크립트가 stdout을 jq 같은 도구로
직접 파이프할 수 있습니다.
프로브 상태 버킷:
okauthrate_limitbillingtimeoutformatunknownno_model
예상되는 프로브 세부 정보/이유 코드 사례:
excluded_by_auth_order: 저장된 프로필이 있지만 명시적auth.order.<provider>가 이를 생략했으므로, 프로브는 시도하는 대신 제외를 보고합니다.missing_credential,invalid_expires,expired,unresolved_ref: 프로필이 있지만 적격하지 않거나 확인할 수 없습니다.no_model: 제공자 인증은 있지만 OpenClaw가 해당 제공자에 대해 프로브 가능한 모델 후보를 확인할 수 없습니다.
별칭 + 대체 모델
openclaw models aliases list
openclaw models fallbacks list
인증 프로필
openclaw models auth add
openclaw models auth list [--provider <id>] [--json]
openclaw models auth login --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
models auth add는 대화형 인증 헬퍼입니다. 선택한
제공자에 따라 제공자 인증 흐름(OAuth/API 키)을 시작하거나 수동 토큰 붙여넣기로 안내할 수 있습니다.
models auth list는 토큰, API 키 또는 OAuth secret 자료를 출력하지 않고
선택한 에이전트의 저장된 인증 프로필을 나열합니다. 하나의 제공자(예: openai-codex)로
필터링하려면 --provider <id>를 사용하고, 스크립팅에는 --json을 사용하세요.
models auth login은 제공자 Plugin의 인증 흐름(OAuth/API 키)을 실행합니다. 설치된 제공자를 보려면
openclaw plugins list를 사용하세요.
인증 결과를 특정 구성된 에이전트 저장소에 쓰려면
openclaw models auth --agent <id> <subcommand>를 사용하세요. 상위 --agent 플래그는
add, list, login, setup-token, paste-token, 그리고
login-github-copilot에서 적용됩니다.
예:
openclaw models auth login --provider openai-codex --set-default
openclaw models auth list --provider openai-codex
참고:
setup-token과paste-token은 토큰 인증 메서드를 노출하는 제공자를 위한 범용 토큰 명령으로 유지됩니다.setup-token은 대화형 TTY가 필요하며 제공자의 토큰 인증 메서드(해당 제공자가 노출하는 경우 기본값은 해당 제공자의setup-token메서드)를 실행합니다.paste-token은 다른 곳에서 생성했거나 자동화에서 생성한 토큰 문자열을 허용합니다.paste-token은--provider가 필요하고, 토큰 값을 입력하라는 프롬프트를 표시하며,--profile-id를 전달하지 않으면 기본 프로필 id<provider>:manual에 씁니다.paste-token --expires-in <duration>은365d또는12h같은 상대 기간에서 절대 토큰 만료 시각을 저장합니다.- Anthropic 참고: Anthropic 직원은 OpenClaw 스타일 Claude CLI 사용이 다시 허용된다고 알려왔으므로, Anthropic이 새 정책을 게시하지 않는 한 OpenClaw는 이 통합에서 Claude CLI 재사용과
claude -p사용을 승인된 것으로 취급합니다. - Anthropic
setup-token/paste-token은 지원되는 OpenClaw 토큰 경로로 계속 사용할 수 있지만, 이제 OpenClaw는 사용할 수 있는 경우 Claude CLI 재사용과claude -p를 선호합니다.