메인 콘텐츠로 건너뛰기
모델 및 인증 프로필 Q&A입니다. 설정, 세션, gateway, 채널 및 문제 해결은 기본 FAQ를 참고하세요.

​
모델: 기본값, 선택, 별칭, 전환

OpenClaw의 기본 모델은 다음으로 설정한 값입니다.
agents.defaults.model.primary
모델은 provider/model 형식으로 참조됩니다(예: openai/gpt-5.5 또는 anthropic/claude-sonnet-4-6). 공급자를 생략하면 OpenClaw는 먼저 별칭을 시도하고, 그다음 정확히 같은 모델 ID에 대해 구성된 공급자가 하나뿐인지 확인하며, 마지막으로 더 이상 권장되지 않는 호환 경로로 구성된 기본 공급자로 폴백합니다. 해당 공급자가 더 이상 구성된 기본 모델을 노출하지 않으면, OpenClaw는 오래되어 제거된 공급자의 기본값을 표시하는 대신 구성된 첫 번째 공급자/모델로 폴백합니다. 그래도 provider/model을 명시적으로 설정해야 합니다.
권장 기본값: 공급자 스택에서 사용할 수 있는 가장 강력한 최신 세대 모델을 사용하세요. 도구를 사용할 수 있거나 신뢰할 수 없는 입력을 받는 에이전트: 비용보다 모델 성능을 우선하세요. 일상적이거나 위험도가 낮은 채팅: 더 저렴한 폴백 모델을 사용하고 에이전트 역할별로 라우팅하세요.MiniMax에는 자체 문서가 있습니다: MiniMax 및 로컬 모델.경험칙: 위험도가 높은 작업에는 감당할 수 있는 최고의 모델을 사용하고, 일상적인 채팅이나 요약에는 더 저렴한 모델을 사용하세요. 에이전트별로 모델을 라우팅하고 하위 에이전트를 사용해 긴 작업을 병렬화할 수 있습니다(각 하위 에이전트는 토큰을 소비합니다). 모델 및 하위 에이전트를 참고하세요.강한 경고: 더 약하거나 과도하게 양자화된 모델은 프롬프트 인젝션과 안전하지 않은 동작에 더 취약합니다. 보안을 참고하세요.더 자세한 배경: 모델.
모델 명령을 사용하거나 model 필드만 편집하세요. 전체 구성 교체는 피하세요.안전한 옵션:
  • 채팅에서 /model 사용(빠른 세션별 변경)
  • openclaw models set ...(모델 구성만 업데이트)
  • openclaw configure --section model(대화형)
  • ~/.openclaw/openclaw.json의 agents.defaults.model 편집
전체 구성을 교체하려는 의도가 아니라면 부분 객체로 config.apply를 사용하지 마세요. RPC 편집의 경우 먼저 config.schema.lookup으로 검사하고 config.patch를 선호하세요. lookup 페이로드는 정규화된 경로, 얕은 스키마 문서/제약 조건, 즉시 하위 항목 요약을 제공합니다. 부분 업데이트용입니다. 구성을 덮어썼다면 백업에서 복원하거나 openclaw doctor를 다시 실행해 복구하세요.문서: 모델, 구성, Config, Doctor.
예. 로컬 모델에는 Ollama가 가장 쉬운 경로입니다.가장 빠른 설정:
  1. https://ollama.com/download에서 Ollama를 설치합니다.
  2. ollama pull gemma4 같은 로컬 모델을 가져옵니다.
  3. 클라우드 모델도 원하면 ollama signin을 실행합니다.
  4. openclaw onboard를 실행하고 Ollama를 선택합니다.
  5. Local 또는 Cloud + Local을 선택합니다.
참고:
  • Cloud + Local은 클라우드 모델과 로컬 Ollama 모델을 함께 제공합니다.
  • kimi-k2.5:cloud 같은 클라우드 모델은 로컬 pull이 필요 없습니다.
  • 수동 전환에는 openclaw models list와 openclaw models set ollama/<model>을 사용하세요.
보안 참고: 더 작거나 많이 양자화된 모델은 프롬프트 인젝션에 더 취약합니다. 도구를 사용할 수 있는 모든 봇에는 큰 모델을 강력히 권장합니다. 그래도 작은 모델을 사용하려면 샌드박싱과 엄격한 도구 허용 목록을 활성화하세요.문서: Ollama, 로컬 모델, 모델 공급자, 보안, 샌드박싱.
  • 이러한 배포는 서로 다를 수 있고 시간이 지나며 변경될 수 있습니다. 고정된 공급자 추천은 없습니다.
  • 각 gateway에서 openclaw models status로 현재 런타임 설정을 확인하세요.
  • 보안에 민감하거나 도구를 사용하는 에이전트에는 사용할 수 있는 가장 강력한 최신 세대 모델을 사용하세요.
/model 명령을 단독 메시지로 사용하세요.
/model sonnet
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash
/model gemini-flash-lite
이는 내장 별칭입니다. 사용자 지정 별칭은 agents.defaults.models를 통해 추가할 수 있습니다.사용 가능한 모델은 /model, /model list, 또는 /model status로 나열할 수 있습니다./model(및 /model list)은 간결한 번호 선택기를 표시합니다. 번호로 선택하세요.
/model 3
공급자에 대해 특정 인증 프로필을 강제로 사용할 수도 있습니다(세션별).
/model opus@anthropic:default
/model opus@anthropic:work
팁: /model status는 활성 에이전트, 사용 중인 auth-profiles.json 파일, 다음에 시도할 인증 프로필을 보여줍니다. 사용 가능한 경우 구성된 공급자 엔드포인트(baseUrl)와 API 모드(api)도 표시합니다.@profile로 설정한 프로필 고정을 해제하려면 어떻게 하나요?@profile 접미사 없이 /model을 다시 실행하세요.
/model anthropic/claude-opus-4-6
기본값으로 돌아가려면 /model에서 선택하세요(또는 /model <default provider/model>을 보내세요). 어떤 인증 프로필이 활성 상태인지 확인하려면 /model status를 사용하세요.
/model provider/model은 세션에 대해 해당 공급자 경로를 정확히 선택합니다.예를 들어 qianfan/deepseek-v4-flash와 deepseek/deepseek-v4-flash는 둘 다 deepseek-v4-flash를 포함하지만 서로 다른 모델 참조입니다. OpenClaw는 단순 모델 ID가 일치한다는 이유만으로 한 공급자에서 다른 공급자로 조용히 전환해서는 안 됩니다.사용자가 선택한 /model 참조는 폴백 정책에서도 엄격합니다. 선택한 공급자/모델을 사용할 수 없으면 agents.defaults.model.fallbacks에서 응답하는 대신 답변이 명확히 실패합니다. 구성된 폴백 체인은 여전히 구성된 기본값, Cron 작업 기본 모델, 자동 선택된 폴백 상태에 적용됩니다.세션이 아닌 오버라이드에서 시작된 실행이 폴백 사용을 허용하는 경우, OpenClaw는 요청된 공급자/모델을 먼저 시도하고, 그다음 구성된 폴백을 시도하며, 마지막으로 구성된 primary를 시도합니다. 이렇게 하면 중복된 단순 모델 ID가 기본 공급자로 바로 되돌아가는 것을 방지합니다.모델 및 모델 장애 조치를 참고하세요.
예. 모델 선택과 런타임 선택을 별도로 다루세요.
  • 네이티브 Codex 코딩 에이전트: agents.defaults.model.primary를 openai/gpt-5.5로 설정하세요. ChatGPT/Codex 구독 인증을 사용하려면 openclaw models auth login --provider openai로 로그인하세요.
  • 에이전트 루프 밖의 직접 OpenAI API 작업: 이미지, 임베딩, 음성, 실시간 및 기타 비에이전트 OpenAI API 표면에는 OPENAI_API_KEY를 구성하세요.
  • OpenAI 에이전트 API 키 인증: 정렬된 openai API 키 프로필과 함께 /model openai/gpt-5.5를 사용하세요.
  • 하위 에이전트: 코딩 작업을 자체 openai/gpt-5.5 모델이 있는 Codex 중심 에이전트로 라우팅하세요.
모델 및 슬래시 명령을 참고하세요.
세션 토글 또는 구성 기본값을 사용하세요.
  • 세션별: 세션이 openai/gpt-5.5를 사용하는 동안 /fast on을 보내세요.
  • 모델별 기본값: agents.defaults.models["openai/gpt-5.5"].params.fastMode를 true로 설정하세요.
  • 자동 컷오프: 새 모델 호출을 자동 컷오프 전까지 빠르게 시작하고, 이후 재시도, 폴백, 도구 결과 또는 계속 호출은 빠른 모드 없이 시작하려면 /fast auto 또는 params.fastMode: "auto"를 사용하세요. 컷오프 기본값은 60초입니다. 변경하려면 활성 모델에 params.fastAutoOnSeconds를 설정하세요.
예:
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            fastMode: "auto",
            fastAutoOnSeconds: 30,
          },
        },
      },
    },
  },
}
OpenAI의 경우 빠른 모드는 지원되는 네이티브 Responses 요청에서 service_tier = "priority"로 매핑됩니다. 세션 /fast 오버라이드는 구성 기본값보다 우선합니다. Codex 앱 서버 턴은 턴 시작 시에만 tier를 받을 수 있으므로, auto는 이미 실행 중인 앱 서버 턴 내부가 아니라 다음 OpenClaw 시작 모델 턴에 적용됩니다.추론 및 빠른 모드와 OpenAI 빠른 모드를 참고하세요.
agents.defaults.models가 설정되어 있으면 /model 및 모든 세션 오버라이드의 허용 목록이 됩니다. 해당 목록에 없는 모델을 선택하면 다음이 반환됩니다.
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
이 오류는 일반 응답 대신 반환됩니다. 해결 방법: 정확한 모델을 agents.defaults.models에 추가하거나, 동적 공급자 카탈로그용 "provider/*": {} 같은 공급자 와일드카드를 추가하거나, 허용 목록을 제거하거나, /model list에서 모델을 선택하세요. 명령에 --runtime codex도 포함되어 있었다면 먼저 허용 목록을 업데이트한 뒤 동일한 /model provider/model --runtime codex 명령을 다시 시도하세요.
이는 공급자가 구성되지 않았음을 의미합니다(MiniMax 공급자 구성 또는 인증 프로필을 찾지 못함). 따라서 모델을 해석할 수 없습니다.해결 체크리스트:
  1. 현재 OpenClaw 릴리스로 업그레이드하거나 소스 main에서 실행한 뒤 gateway를 재시작합니다.
  2. MiniMax가 구성되어 있는지(마법사 또는 JSON), 또는 일치하는 공급자를 주입할 수 있도록 MiniMax 인증이 env/인증 프로필에 존재하는지 확인합니다 (minimax에는 MINIMAX_API_KEY, minimax-portal에는 MINIMAX_OAUTH_TOKEN 또는 저장된 MiniMax OAuth).
  3. 인증 경로에 맞는 정확한 모델 ID(대소문자 구분)를 사용합니다. API 키 설정에는 minimax/MiniMax-M3, minimax/MiniMax-M2.7, 또는 minimax/MiniMax-M2.7-highspeed를 사용하고, OAuth 설정에는 minimax-portal/MiniMax-M3, minimax-portal/MiniMax-M2.7, 또는 minimax-portal/MiniMax-M2.7-highspeed를 사용합니다.
  4. 다음을 실행합니다. 
    openclaw models list
    그리고 목록에서 선택하세요(또는 채팅에서 /model list 사용).
MiniMax 및 모델을 참고하세요.
예. MiniMax를 기본값으로 사용하고 필요할 때 세션별로 모델을 전환하세요. 폴백은 “어려운 작업”이 아니라 오류를 위한 것이므로 /model이나 별도 에이전트를 사용하세요.옵션 A: 세션별 전환
{
  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M3" },
      models: {
        "minimax/MiniMax-M3": { alias: "minimax" },
        "openai/gpt-5.5": { alias: "gpt" },
      },
    },
  },
}
그런 다음:
/model gpt
옵션 B: 별도 에이전트
  • 에이전트 A 기본값: MiniMax
  • 에이전트 B 기본값: OpenAI
  • 에이전트별로 라우팅하거나 /agent를 사용해 전환
문서: 모델, 다중 에이전트 라우팅, MiniMax, OpenAI.
예. OpenClaw에는 몇 가지 기본 축약어가 포함되어 있습니다(agents.defaults.models에 모델이 있을 때만 적용됨).
  • opus → anthropic/claude-opus-4-8
  • sonnet → anthropic/claude-sonnet-4-6
  • gpt → openai/gpt-5.4
  • gpt-mini → openai/gpt-5.4-mini
  • gpt-nano → openai/gpt-5.4-nano
  • gemini → google/gemini-3.1-pro-preview
  • gemini-flash → google/gemini-3-flash-preview
  • gemini-flash-lite → google/gemini-3.1-flash-lite
같은 이름으로 자체 별칭을 설정하면, 사용자의 값이 우선합니다.
별칭은 agents.defaults.models.<modelId>.alias에서 가져옵니다. 예:
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
      },
    },
  },
}
그러면 /model sonnet(또는 지원되는 경우 /<alias>)이 해당 모델 ID로 해석됩니다.
OpenRouter(토큰별 과금, 다양한 모델):
{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
    },
  },
  env: { OPENROUTER_API_KEY: "sk-or-..." },
}
Z.AI(GLM 모델):
{
  agents: {
    defaults: {
      model: { primary: "zai/glm-5" },
      models: { "zai/glm-5": {} },
    },
  },
  env: { ZAI_API_KEY: "..." },
}
제공자/모델을 참조했지만 필요한 제공자 키가 없으면 런타임 인증 오류가 발생합니다(예: No API key found for provider "zai").새 에이전트를 추가한 뒤 제공자의 API 키를 찾을 수 없음이는 보통 새 에이전트의 인증 저장소가 비어 있다는 뜻입니다. 인증은 에이전트별로 관리되며 다음 위치에 저장됩니다.
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
해결 옵션:
  • openclaw agents add <id>를 실행하고 마법사에서 인증을 구성합니다.
  • 또는 기본 에이전트의 인증 저장소에서 이식 가능한 정적 api_key / token 프로필만 새 에이전트의 인증 저장소로 복사합니다.
  • OAuth 프로필의 경우, 자체 계정이 필요한 새 에이전트에서 로그인하세요. 그렇지 않으면 OpenClaw가 새로 고침 토큰을 복제하지 않고도 기본/메인 에이전트를 통해 읽을 수 있습니다.
에이전트 간에 agentDir을 재사용하지 마세요. 인증/세션 충돌이 발생합니다.

​
모델 장애 조치 및 “모든 모델 실패”

장애 조치는 두 단계로 발생합니다.
  1. 같은 제공자 내 인증 프로필 순환.
  2. agents.defaults.model.fallbacks의 다음 모델로 모델 폴백.
실패한 프로필에는 쿨다운(지수 백오프)이 적용되므로, 제공자가 속도 제한에 걸리거나 일시적으로 실패하더라도 OpenClaw가 계속 응답할 수 있습니다.속도 제한 버킷에는 단순한 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. 같은 일반 내부 폴백 텍스트는 보수적으로 유지되며, 그 자체만으로는 모델 폴백을 트리거하지 않습니다.
시스템이 인증 프로필 ID 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를 사용하세요.
“No credentials found for profile anthropic” 해결 체크리스트이는 실행이 Anthropic 인증 프로필에 고정되어 있지만 Gateway가 인증 저장소에서 이를 찾을 수 없다는 뜻입니다.
  • Claude CLI 사용
    • Gateway 호스트에서 openclaw models auth login --provider anthropic --method cli --set-default를 실행합니다.
  • 대신 API 키를 사용하려는 경우
    • Gateway 호스트의 ~/.openclaw/.env에 ANTHROPIC_API_KEY를 넣습니다.
    • 누락된 프로필을 강제로 사용하는 고정 순서를 지웁니다. 
      openclaw models auth order clear --provider anthropic
  • Gateway 호스트에서 명령을 실행 중인지 확인
    • 원격 모드에서는 인증 프로필이 사용자의 노트북이 아니라 Gateway 머신에 있습니다.
모델 구성에 Google Gemini가 폴백으로 포함되어 있거나 Gemini 축약어로 전환한 경우, OpenClaw는 모델 폴백 중에 이를 시도합니다. Google 자격 증명을 구성하지 않았다면 No API key found for provider "google"이 표시됩니다.해결: Google 인증을 제공하거나, 폴백이 그쪽으로 라우팅되지 않도록 agents.defaults.model.fallbacks / 별칭에서 Google 모델을 제거하거나 피하세요.LLM 요청 거부됨: thinking 서명 필요(Google Antigravity)원인: 세션 기록에 서명이 없는 thinking 블록이 포함되어 있습니다(종종 중단되었거나 일부만 수신된 스트림에서 발생). Google Antigravity는 thinking 블록에 서명을 요구합니다.해결: 이제 OpenClaw는 Google Antigravity Claude에 대해 서명되지 않은 thinking 블록을 제거합니다. 그래도 나타나면 새 세션을 시작하거나 해당 에이전트에 /thinking off를 설정하세요.

​
인증 프로필: 정의와 관리 방법

관련: /concepts/oauth(OAuth 흐름, 토큰 저장소, 다중 계정 패턴)
인증 프로필은 제공자에 연결된 이름 있는 자격 증명 레코드(OAuth 또는 API 키)입니다. 프로필은 다음 위치에 있습니다.
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
비밀을 출력하지 않고 저장된 프로필을 검사하려면 openclaw models auth list를 실행하세요(선택적으로 --provider <id> 또는 --json). 자세한 내용은 모델 CLI를 참고하세요.
OpenClaw는 다음과 같은 제공자 접두사가 붙은 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에 저장됨)도 설정할 수 있습니다.
# Defaults to the configured default agent (omit --agent)
openclaw models auth order get --provider anthropic

# Lock rotation to a single profile (only try this one)
openclaw models auth order set --provider anthropic anthropic:default

# Or set an explicit order (fallback within provider)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Clear override (fall back to config auth.order / round-robin)
openclaw models auth order clear --provider anthropic
특정 에이전트를 대상으로 하려면:
openclaw models auth order set --provider anthropic --agent main anthropic:default
실제로 무엇이 시도될지 확인하려면 다음을 사용하세요.
openclaw models status --probe
저장된 프로필이 명시적 순서에서 생략되면, probe는 해당 프로필을 조용히 시도하는 대신 excluded_by_auth_order를 보고합니다.
OpenClaw는 둘 다 지원합니다.
  • OAuth / CLI 로그인은 제공자가 지원하는 경우 구독 액세스를 활용하는 경우가 많습니다. Anthropic의 경우 OpenClaw의 Claude CLI 백엔드는 Claude Code claude -p를 사용합니다. Anthropic은 현재 이를 Agent SDK/프로그래밍 방식 사용으로 취급합니다. Anthropic은 2026년 6월 15일의 별도 Agent SDK 크레딧 변경을 일시 중지했으므로, 현재로서는 여전히 구독 사용량 한도에서 차감됩니다. 현재 일시 중지 공지는 Anthropic의 Agent SDK 플랜 문서를 참고하세요.
  • API 키는 토큰별 과금을 사용합니다.
마법사는 Anthropic Claude CLI, OpenAI Codex OAuth, API 키를 명시적으로 지원합니다.

​
관련