메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.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 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를 사용하세요.
예. 모델 선택과 런타임 선택을 별도로 다루세요.
  • 네이티브 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-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.fastMode를 true로 설정하세요.
예:
{
  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), 또는 일치하는 제공자가 주입될 수 있도록 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에 모델이 있을 때만 적용됨).
  • opus → anthropic/claude-opus-4-6
  • sonnet → anthropic/claude-sonnet-4-6
  • gpt → openai/gpt-5.5
  • 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-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를 재사용하지 마세요. 인증/세션 충돌이 발생합니다.

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

장애 조치는 두 단계로 진행됩니다.
  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/재시도 경로에 남습니다.일반 서버 오류 텍스트는 의도적으로 “알 수 없음/오류가 들어간 모든 것”보다 좁게 처리됩니다. OpenClaw는 공급자 컨텍스트가 일치할 때 Anthropic의 단독 An unknown error occurred, OpenRouter의 단독 Provider returned error, Unhandled stop reason: error 같은 중지 사유 오류, 일시적 서버 텍스트 (internal server error, unknown error, 520, upstream error, backend error)가 포함된 JSON api_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 모델을 제거하거나 피해서 fallback이 그쪽으로 라우팅되지 않도록 하세요.LLM 요청 거부됨: thinking 서명 필요(Google Antigravity)원인: 세션 기록에 서명 없는 thinking 블록이 포함되어 있습니다(중단되었거나 부분적인 스트림에서 자주 발생). Google Antigravity는 thinking 블록에 서명을 요구합니다.수정: 이제 OpenClaw는 Google Antigravity Claude에 대해 서명 없는 thinking 블록을 제거합니다. 그래도 계속 나타나면 새 세션을 시작하거나 해당 에이전트에 /thinking off를 설정하세요.

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

관련: /concepts/oauth (OAuth 흐름, 토큰 저장소, 다중 계정 패턴)
인증 프로필은 provider에 연결된 이름 있는 자격 증명 레코드(OAuth 또는 API 키)입니다. 프로필은 다음 위치에 있습니다.
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
비밀 정보를 덤프하지 않고 저장된 프로필을 검사하려면 openclaw models auth list를 실행하세요(선택적으로 --provider <id> 또는 --json). 자세한 내용은 모델 CLI를 참고하세요.
OpenClaw는 다음과 같은 provider 접두사가 붙은 ID를 사용합니다.
  • anthropic:default(이메일 ID가 없을 때 일반적)
  • OAuth ID에는 anthropic:<email>
  • 사용자가 선택한 사용자 지정 ID(예: anthropic:work)
예. 구성은 프로필의 선택적 메타데이터와 provider별 순서(auth.order.<provider>)를 지원합니다. 이는 비밀 정보를 저장하지 않으며, ID를 provider/모드에 매핑하고 순환 순서를 설정합니다.OpenClaw는 프로필이 짧은 cooldown(속도 제한/시간 초과/인증 실패) 상태이거나 더 긴 disabled 상태(결제/크레딧 부족)에 있으면 일시적으로 건너뛸 수 있습니다. 이를 검사하려면 openclaw models status --json을 실행하고 auth.unusableProfiles를 확인하세요. 조정: auth.cooldowns.billingBackoffHours*.속도 제한 cooldown은 모델 범위일 수 있습니다. 한 모델에 대해 cooling down 중인 프로필도 동일한 provider의 형제 모델에서는 여전히 사용할 수 있지만, 결제/비활성화 기간은 여전히 전체 프로필을 차단합니다.CLI를 통해 에이전트별 순서 재정의(해당 에이전트의 auth-state.json에 저장됨)도 설정할 수 있습니다.
# 구성된 기본 에이전트가 기본값입니다(--agent 생략)
openclaw models auth order get --provider anthropic

# 순환을 단일 프로필로 잠급니다(이것만 시도)
openclaw models auth order set --provider anthropic anthropic:default

# 또는 명시적 순서를 설정합니다(provider 내 fallback)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# 재정의를 지웁니다(config auth.order / round-robin으로 fallback)
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는 적용 가능한 경우 구독 액세스를 활용하는 경우가 많습니다.
  • API 키는 토큰당 지불 결제를 사용합니다.
마법사는 Anthropic Claude CLI, OpenAI Codex OAuth, API 키를 명시적으로 지원합니다.

​
관련 항목