모델 및 인증 프로필 Q&A입니다. 설정, 세션, Gateway, 채널 및 문제 해결은 기본 FAQ를 참조하세요.Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
모델: 기본값, 선택, 별칭, 전환
“기본 모델”이란 무엇인가요?
“기본 모델”이란 무엇인가요?
provider/model로 참조됩니다(예: openai/gpt-5.5 또는 anthropic/claude-sonnet-4-6). 제공자를 생략하면 OpenClaw는 먼저 별칭을 시도한 다음, 정확히 그 모델 ID와 일치하는 고유하게 구성된 제공자를 찾고, 그 후에야 더 이상 권장되지 않는 호환성 경로로 구성된 기본 제공자에 폴백합니다. 해당 제공자가 구성된 기본 모델을 더 이상 노출하지 않으면 OpenClaw는 오래된 제거된 제공자 기본값을 표시하는 대신, 처음 구성된 제공자/모델로 폴백합니다. 그래도 provider/model을 명시적으로 설정해야 합니다.어떤 모델을 추천하나요?
어떤 모델을 추천하나요?
구성을 초기화하지 않고 모델을 전환하려면 어떻게 하나요?
구성을 초기화하지 않고 모델을 전환하려면 어떻게 하나요?
- 채팅에서
/model(빠른 세션별 전환) openclaw models set ...(모델 구성만 업데이트)openclaw configure --section model(대화형)~/.openclaw/openclaw.json에서agents.defaults.model편집
config.apply를 사용하지 마세요.
RPC 편집의 경우 먼저 config.schema.lookup으로 확인하고 config.patch를 선호하세요. 조회 페이로드는 정규화된 경로, 얕은 스키마 문서/제약 조건, 즉시 하위 항목 요약을 제공합니다.
부분 업데이트용입니다.
구성을 덮어썼다면 백업에서 복원하거나 openclaw doctor를 다시 실행해 복구하세요.문서: 모델, 구성, 구성, Doctor.셀프 호스팅 모델(llama.cpp, vLLM, Ollama)을 사용할 수 있나요?
셀프 호스팅 모델(llama.cpp, vLLM, Ollama)을 사용할 수 있나요?
https://ollama.com/download에서 Ollama를 설치합니다.ollama pull gemma4같은 로컬 모델을 가져옵니다.- 클라우드 모델도 원하면
ollama signin을 실행합니다. openclaw onboard를 실행하고Ollama를 선택합니다.Local또는Cloud + Local을 선택합니다.
Cloud + Local은 클라우드 모델과 로컬 Ollama 모델을 함께 제공합니다.kimi-k2.5:cloud같은 클라우드 모델은 로컬 가져오기가 필요 없습니다.- 수동 전환에는
openclaw models list및openclaw models set ollama/<model>을 사용하세요.
OpenClaw, Flawd, Krill은 어떤 모델을 사용하나요?
OpenClaw, Flawd, Krill은 어떤 모델을 사용하나요?
- 이러한 배포는 서로 다를 수 있고 시간이 지나며 변경될 수 있습니다. 고정된 제공자 추천은 없습니다.
- 각 Gateway에서
openclaw models status로 현재 런타임 설정을 확인하세요. - 보안에 민감하거나 도구가 활성화된 에이전트에는 사용할 수 있는 가장 강력한 최신 세대 모델을 사용하세요.
재시작 없이 즉시 모델을 전환하려면 어떻게 하나요?
재시작 없이 즉시 모델을 전환하려면 어떻게 하나요?
/model 명령을 독립 메시지로 사용하세요.agents.defaults.models를 통해 추가할 수 있습니다./model, /model list 또는 /model status로 사용 가능한 모델을 나열할 수 있습니다./model(및 /model list)은 간결한 번호형 선택기를 표시합니다. 번호로 선택하세요./model status는 어떤 에이전트가 활성 상태인지, 어떤 auth-profiles.json 파일을 사용 중인지, 다음에 어떤 인증 프로필을 시도할지 보여줍니다.
사용할 수 있는 경우 구성된 제공자 엔드포인트(baseUrl)와 API 모드(api)도 보여줍니다.@profile로 설정한 프로필 고정을 해제하려면 어떻게 하나요?@profile 접미사 없이 /model을 다시 실행하세요./model에서 선택하세요(또는 /model <default provider/model>을 보내세요).
어떤 인증 프로필이 활성 상태인지 확인하려면 /model status를 사용하세요.두 제공자가 같은 모델 ID를 노출하면 /model은 어느 쪽을 사용하나요?
두 제공자가 같은 모델 ID를 노출하면 /model은 어느 쪽을 사용하나요?
/model provider/model은 해당 세션에 대해 정확한 제공자 경로를 선택합니다.예를 들어 qianfan/deepseek-v4-flash와 deepseek/deepseek-v4-flash는 둘 다 deepseek-v4-flash를 포함하더라도 서로 다른 모델 참조입니다. OpenClaw는 단순 모델 ID가 일치한다는 이유만으로 한 제공자에서 다른 제공자로 조용히 전환해서는 안 됩니다.사용자가 선택한 /model 참조는 폴백 정책에서도 엄격합니다. 선택한 제공자/모델을 사용할 수 없으면 agents.defaults.model.fallbacks에서 응답하는 대신 답장이 명확히 실패합니다. 구성된 폴백 체인은 구성된 기본값, cron 작업 기본 모델, 자동 선택된 폴백 상태에는 계속 적용됩니다.세션이 아닌 오버라이드에서 시작된 실행이 폴백을 사용할 수 있는 경우, OpenClaw는 요청된 제공자/모델을 먼저 시도한 다음 구성된 폴백을 시도하고, 그 후에야 구성된 기본 모델을 시도합니다. 이렇게 하면 중복된 단순 모델 ID가 기본 제공자로 바로 되돌아가는 일을 방지합니다.모델 및 모델 장애 조치를 참조하세요.일상 작업에는 GPT 5.5를, 코딩에는 Codex 5.5를 사용할 수 있나요?
일상 작업에는 GPT 5.5를, 코딩에는 Codex 5.5를 사용할 수 있나요?
- 네이티브 Codex 코딩 에이전트:
agents.defaults.model.primary를openai/gpt-5.5로 설정하세요. ChatGPT/Codex 구독 인증을 사용하려면openclaw models auth login --provider openai-codex로 로그인하세요. - 에이전트 루프 밖의 직접 OpenAI API 작업: 이미지, 임베딩, 음성, 실시간 및 기타 비에이전트 OpenAI API 표면에는
OPENAI_API_KEY를 구성하세요. - OpenAI 에이전트 API 키 인증: 정렬된
openai-codexAPI 키 프로필과 함께/model openai/gpt-5.5를 사용하세요. - 하위 에이전트: 코딩 작업을 자체
openai/gpt-5.5모델을 가진 Codex 중심 에이전트로 라우팅하세요.
GPT 5.5의 빠른 모드는 어떻게 구성하나요?
GPT 5.5의 빠른 모드는 어떻게 구성하나요?
- 세션별: 세션이
openai/gpt-5.5를 사용하는 동안/fast on을 보내세요. - 모델별 기본값:
agents.defaults.models["openai/gpt-5.5"].params.fastMode를true로 설정하세요.
service_tier = "priority"에 매핑됩니다. 세션 /fast 오버라이드는 구성 기본값보다 우선합니다.사고 및 빠른 모드와 OpenAI 빠른 모드를 참조하세요.왜 "Model ... is not allowed"가 표시된 뒤 답장이 없나요?
왜 "Model ... is not allowed"가 표시된 뒤 답장이 없나요?
agents.defaults.models가 설정되어 있으면 /model 및 모든
세션 오버라이드의 허용 목록이 됩니다. 해당 목록에 없는 모델을 선택하면 다음을 반환합니다.agents.defaults.models에 추가하거나, 동적 제공자 카탈로그용 "provider/*": {} 같은 제공자 와일드카드를 추가하거나, 허용 목록을 제거하거나, /model list에서 모델을 선택하세요.
명령에 --runtime codex도 포함되어 있었다면 먼저 허용 목록을 업데이트한 다음
같은 /model provider/model --runtime codex 명령을 다시 시도하세요.왜 "Unknown model: minimax/MiniMax-M2.7"가 표시되나요?
왜 "Unknown model: minimax/MiniMax-M2.7"가 표시되나요?
-
현재 OpenClaw 릴리스로 업그레이드하거나 소스
main에서 실행한 다음 Gateway를 재시작하세요. -
MiniMax가 구성되어 있는지(마법사 또는 JSON), 또는 일치하는 제공자를 주입할 수 있도록 env/인증 프로필에 MiniMax 인증이
있는지 확인하세요
(
minimax에는MINIMAX_API_KEY,minimax-portal에는MINIMAX_OAUTH_TOKEN또는 저장된 MiniMax OAuth). -
인증 경로에 맞는 정확한 모델 ID(대소문자 구분)를 사용하세요.
API 키
설정에는
minimax/MiniMax-M2.7또는minimax/MiniMax-M2.7-highspeed, OAuth 설정에는minimax-portal/MiniMax-M2.7/minimax-portal/MiniMax-M2.7-highspeed를 사용하세요. -
다음을 실행하세요.
그리고 목록에서 선택하세요(또는 채팅에서
/model list).
MiniMax를 기본값으로 사용하고 복잡한 작업에는 OpenAI를 사용할 수 있나요?
MiniMax를 기본값으로 사용하고 복잡한 작업에는 OpenAI를 사용할 수 있나요?
/model이나 별도 에이전트를 사용하세요.옵션 A: 세션별 전환- 에이전트 A 기본값: MiniMax
- 에이전트 B 기본값: OpenAI
- 에이전트별로 라우팅하거나
/agent를 사용해 전환
opus / sonnet / gpt는 내장 단축어인가요?
opus / sonnet / gpt는 내장 단축어인가요?
agents.defaults.models에 모델이 있을 때만 적용됨).opus→anthropic/claude-opus-4-7sonnet→anthropic/claude-sonnet-4-6gpt→openai/gpt-5.4gpt-mini→openai/gpt-5.4-minigpt-nano→openai/gpt-5.4-nanogemini→google/gemini-3.1-pro-previewgemini-flash→google/gemini-3-flash-previewgemini-flash-lite→google/gemini-3.1-flash-lite-preview
모델 단축어(별칭)를 정의/재정의하려면 어떻게 하나요?
모델 단축어(별칭)를 정의/재정의하려면 어떻게 하나요?
agents.defaults.models.<modelId>.alias에서 가져옵니다. 예:/model sonnet(또는 지원되는 경우 /<alias>)이 해당 모델 ID로 해석됩니다.OpenRouter나 Z.AI 같은 다른 제공자의 모델은 어떻게 추가하나요?
OpenRouter나 Z.AI 같은 다른 제공자의 모델은 어떻게 추가하나요?
No API key found for provider "zai").새 에이전트를 추가한 후 제공자의 API 키를 찾을 수 없음이는 일반적으로 새 에이전트의 인증 저장소가 비어 있다는 뜻입니다. 인증은 에이전트별로 관리되며 다음 위치에 저장됩니다.openclaw agents add <id>를 실행하고 마법사에서 인증을 구성합니다.- 또는 기본 에이전트의 인증 저장소에서 이식 가능한 정적
api_key/token프로필만 새 에이전트의 인증 저장소로 복사합니다. - OAuth 프로필의 경우 자체 계정이 필요한 새 에이전트에서 로그인하세요. 그렇지 않으면 OpenClaw가 갱신 토큰을 복제하지 않고도 기본/메인 에이전트를 통해 읽을 수 있습니다.
agentDir을 재사용하지 마세요. 인증/세션 충돌이 발생합니다.모델 장애 조치와 “All models failed”
장애 조치는 어떻게 동작하나요?
장애 조치는 어떻게 동작하나요?
- 같은 제공자 내 인증 프로필 순환.
agents.defaults.model.fallbacks의 다음 모델로 모델 폴백.
429 응답보다 더 많은 항목이 포함됩니다. OpenClaw는
Too many concurrent requests,
ThrottlingException, concurrency limit reached,
workers_ai ... quota limit exceeded, resource exhausted 같은 메시지와 주기적
사용량 기간 제한(weekly/monthly limit reached)도 장애 조치할 만한
속도 제한으로 처리합니다.일부 결제처럼 보이는 응답은 402가 아니며, 일부 HTTP 402
응답도 이 일시적 버킷에 남습니다. 제공자가 401 또는 403에서
명시적인 결제 문구를 반환하면 OpenClaw는 이를 여전히
결제 경로에 둘 수 있지만, 제공자별 텍스트 매처는 이를 소유한
제공자 범위에만 유지됩니다(예: OpenRouter Key limit exceeded). 402
메시지가 대신 재시도 가능한 사용량 기간 또는
조직/워크스페이스 지출 한도처럼 보이면(daily limit reached, resets tomorrow,
organization spending limit exceeded), OpenClaw는 이를 장기 결제 비활성화가 아니라
rate_limit으로 처리합니다.컨텍스트 초과 오류는 다릅니다. request_too_large,
input exceeds the maximum number of tokens,
input token count exceeds the maximum number of input tokens,
input is too long for the model, 또는 ollama error: context length exceeded 같은 시그니처는 모델
폴백으로 진행하지 않고 Compaction/재시도 경로에 남습니다.일반 서버 오류 텍스트는 의도적으로 “unknown/error가 들어간 모든 것”보다 좁게 처리됩니다.
OpenClaw는 제공자 컨텍스트가
일치할 때 Anthropic의 단순 An unknown error occurred, OpenRouter의 단순
Provider returned error, Unhandled stop reason: error 같은 중지 이유 오류, 일시적 서버 텍스트가 포함된 JSON api_error 페이로드
(internal server error, unknown error, 520, upstream error, backend error), ModelNotReadyException 같은 제공자 사용 중 오류를
장애 조치할 만한 타임아웃/과부하 신호로 처리합니다.
LLM request failed with an unknown error. 같은 일반 내부 폴백 텍스트는 보수적으로 유지되며 그 자체만으로 모델 폴백을 트리거하지 않습니다."No credentials found for profile anthropic:default"는 무슨 뜻인가요?
"No credentials found for profile anthropic:default"는 무슨 뜻인가요?
anthropic:default를 사용하려 했지만 예상 인증 저장소에서 해당 자격 증명을 찾을 수 없었다는 뜻입니다.수정 체크리스트:- 인증 프로필이 어디에 있는지 확인(새 경로와 레거시 경로)
- 현재:
~/.openclaw/agents/<agentId>/agent/auth-profiles.json - 레거시:
~/.openclaw/agent/*(openclaw doctor로 마이그레이션됨)
- 현재:
- 환경 변수가 Gateway에 로드되는지 확인
- 셸에서
ANTHROPIC_API_KEY를 설정했지만 systemd/launchd를 통해 Gateway를 실행하면 상속되지 않을 수 있습니다.~/.openclaw/.env에 넣거나env.shellEnv를 활성화하세요.
- 셸에서
- 올바른 에이전트를 편집 중인지 확인
- 다중 에이전트 설정에서는
auth-profiles.json파일이 여러 개 있을 수 있습니다.
- 다중 에이전트 설정에서는
- 모델/인증 상태 점검
- 구성된 모델과 제공자 인증 여부를 보려면
openclaw models status를 사용하세요.
- 구성된 모델과 제공자 인증 여부를 보려면
-
Claude CLI 사용
- Gateway 호스트에서
openclaw models auth login --provider anthropic --method cli --set-default를 실행합니다.
- Gateway 호스트에서
-
대신 API 키를 사용하려는 경우
-
Gateway 호스트의
~/.openclaw/.env에ANTHROPIC_API_KEY를 넣습니다. -
누락된 프로필을 강제로 사용하게 하는 고정 순서를 지웁니다.
-
Gateway 호스트의
-
Gateway 호스트에서 명령을 실행 중인지 확인
- 원격 모드에서는 인증 프로필이 노트북이 아니라 Gateway 머신에 있습니다.
왜 Google Gemini도 시도하고 실패했나요?
왜 Google Gemini도 시도하고 실패했나요?
No API key found for provider "google"가 표시됩니다.수정: Google 인증을 제공하거나, agents.defaults.model.fallbacks / 별칭에서 Google 모델을 제거하거나 피해서 폴백이 해당 모델로 라우팅되지 않게 하세요.LLM request rejected: thinking signature required (Google Antigravity)원인: 세션 기록에 서명이 없는 thinking 블록이 포함되어 있습니다(중단/부분 스트림에서 자주 발생).
Google Antigravity는 thinking 블록에 서명을 요구합니다.수정: 이제 OpenClaw는 Google Antigravity Claude에 대해 서명되지 않은 thinking 블록을 제거합니다. 그래도 계속 나타나면 새 세션을 시작하거나 해당 에이전트에 /thinking off를 설정하세요.인증 프로필: 정의와 관리 방법
관련: /concepts/oauth(OAuth 흐름, 토큰 저장소, 다중 계정 패턴)인증 프로필이란 무엇인가요?
인증 프로필이란 무엇인가요?
openclaw models auth list를 실행하세요(선택적으로 --provider <id> 또는 --json). 자세한 내용은 모델 CLI를 참조하세요.일반적인 프로필 ID는 무엇인가요?
일반적인 프로필 ID는 무엇인가요?
anthropic:default(이메일 ID가 없을 때 일반적)- OAuth ID용
anthropic:<email> - 사용자가 선택한 사용자 지정 ID(예:
anthropic:work)
어떤 인증 프로필을 먼저 시도할지 제어할 수 있나요?
어떤 인증 프로필을 먼저 시도할지 제어할 수 있나요?
auth.order.<provider>)를 지원합니다. 이는 비밀을 저장하지 않습니다. ID를 제공자/모드에 매핑하고 순환 순서를 설정합니다.OpenClaw는 프로필이 짧은 쿨다운 상태(속도 제한/타임아웃/인증 실패) 또는 더 긴 비활성화 상태(결제/크레딧 부족)에 있으면 일시적으로 건너뛸 수 있습니다. 이를 확인하려면 openclaw models status --json을 실행하고 auth.unusableProfiles를 확인하세요. 조정: auth.cooldowns.billingBackoffHours*.속도 제한 쿨다운은 모델 범위일 수 있습니다. 한 모델에 대해 쿨다운 중인 프로필도
같은 제공자의 형제 모델에는 계속 사용할 수 있지만,
결제/비활성화 기간은 여전히 전체 프로필을 차단합니다.CLI를 통해 에이전트별 순서 재정의(해당 에이전트의 auth-state.json에 저장됨)도 설정할 수 있습니다.excluded_by_auth_order를 보고합니다.OAuth와 API 키의 차이는 무엇인가요?
OAuth와 API 키의 차이는 무엇인가요?
- OAuth는 종종 구독 액세스를 활용합니다(해당되는 경우).
- API 키는 토큰당 과금을 사용합니다.
관련 문서
- FAQ — 기본 FAQ
- FAQ — 빠른 시작 및 최초 실행 설정
- 모델 선택
- 모델 장애 조치