메인 콘텐츠로 건너뛰기

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.

모델 및 인증 프로필 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를 선호하세요. 조회 페이로드는 정규화된 경로, 얕은 스키마 문서/제약 조건, 즉시 하위 항목 요약을 제공합니다. 부분 업데이트용입니다. 구성을 덮어썼다면 백업에서 복원하거나 openclaw doctor를 다시 실행해 복구하세요.문서: 모델, 구성, 구성, 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 같은 클라우드 모델은 로컬 가져오기가 필요 없습니다.
  • 수동 전환에는 openclaw models listopenclaw 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-flashdeepseek/deepseek-v4-flash는 둘 다 deepseek-v4-flash를 포함하더라도 서로 다른 모델 참조입니다. OpenClaw는 단순 모델 ID가 일치한다는 이유만으로 한 제공자에서 다른 제공자로 조용히 전환해서는 안 됩니다.사용자가 선택한 /model 참조는 폴백 정책에서도 엄격합니다. 선택한 제공자/모델을 사용할 수 없으면 agents.defaults.model.fallbacks에서 응답하는 대신 답장이 명확히 실패합니다. 구성된 폴백 체인은 구성된 기본값, cron 작업 기본 모델, 자동 선택된 폴백 상태에는 계속 적용됩니다.세션이 아닌 오버라이드에서 시작된 실행이 폴백을 사용할 수 있는 경우, OpenClaw는 요청된 제공자/모델을 먼저 시도한 다음 구성된 폴백을 시도하고, 그 후에야 구성된 기본 모델을 시도합니다. 이렇게 하면 중복된 단순 모델 ID가 기본 제공자로 바로 되돌아가는 일을 방지합니다.모델모델 장애 조치를 참조하세요.
예. 모델 선택과 런타임 선택은 분리해서 다루세요.
  • 네이티브 Codex 코딩 에이전트: agents.defaults.model.primaryopenai/gpt-5.5로 설정하세요. ChatGPT/Codex 구독 인증을 사용하려면 openclaw models auth login --provider openai-codex로 로그인하세요.
  • 에이전트 루프 밖의 직접 OpenAI API 작업: 이미지, 임베딩, 음성, 실시간 및 기타 비에이전트 OpenAI API 표면에는 OPENAI_API_KEY를 구성하세요.
  • OpenAI 에이전트 API 키 인증: 정렬된 openai-codex 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.fastModetrue로 설정하세요.
예:
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}
OpenAI의 경우 빠른 모드는 지원되는 네이티브 Responses 요청에서 service_tier = "priority"에 매핑됩니다. 세션 /fast 오버라이드는 구성 기본값보다 우선합니다.사고 및 빠른 모드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), 또는 일치하는 제공자를 주입할 수 있도록 env/인증 프로필에 MiniMax 인증이 있는지 확인하세요 (minimax에는 MINIMAX_API_KEY, minimax-portal에는 MINIMAX_OAUTH_TOKEN 또는 저장된 MiniMax OAuth).
  3. 인증 경로에 맞는 정확한 모델 ID(대소문자 구분)를 사용하세요. API 키 설정에는 minimax/MiniMax-M2.7 또는 minimax/MiniMax-M2.7-highspeed, OAuth 설정에는 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-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "minimax" },
        "openai/gpt-5.5": { alias: "gpt" },
      },
    },
  },
}
그런 다음:
/model gpt
옵션 B: 별도 에이전트
  • 에이전트 A 기본값: MiniMax
  • 에이전트 B 기본값: OpenAI
  • 에이전트별로 라우팅하거나 /agent를 사용해 전환
문서: 모델, 멀티 에이전트 라우팅, MiniMax, OpenAI.
예. OpenClaw는 몇 가지 기본 단축 표현을 제공합니다(agents.defaults.models에 모델이 있을 때만 적용됨).
  • opusanthropic/claude-opus-4-7
  • sonnetanthropic/claude-sonnet-4-6
  • gptopenai/gpt-5.4
  • gpt-miniopenai/gpt-5.4-mini
  • gpt-nanoopenai/gpt-5.4-nano
  • geminigoogle/gemini-3.1-pro-preview
  • gemini-flashgoogle/gemini-3-flash-preview
  • gemini-flash-litegoogle/gemini-3.1-flash-lite-preview
같은 이름으로 자체 별칭을 설정하면 해당 값이 우선합니다.
별칭은 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" },
        "anthropic/claude-haiku-4-5": { alias: "haiku" },
      },
    },
  },
}
그러면 /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을 재사용하지 마세요. 인증/세션 충돌이 발생합니다.

모델 장애 조치와 “All models failed”

장애 조치는 두 단계로 진행됩니다.
  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/.envANTHROPIC_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 request rejected: thinking signature required (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에 저장됨)도 설정할 수 있습니다.
# 구성된 기본 에이전트가 기본값입니다(--agent 생략)
openclaw models auth order get --provider anthropic

# 순환을 단일 프로필로 고정(이 프로필만 시도)
openclaw models auth order set --provider anthropic anthropic:default

# 또는 명시적 순서 설정(제공자 내 폴백)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# 재정의 지우기(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
저장된 프로필이 명시적 순서에서 생략되면, 프로브는 이를 조용히 시도하는 대신 해당 프로필에 대해 excluded_by_auth_order를 보고합니다.
OpenClaw는 둘 다 지원합니다.
  • OAuth는 종종 구독 액세스를 활용합니다(해당되는 경우).
  • API 키는 토큰당 과금을 사용합니다.
마법사는 Anthropic Claude CLI, OpenAI Codex OAuth, API 키를 명시적으로 지원합니다.

관련 문서