모델 제공자

LLM/모델 제공자(WhatsApp/Telegram 같은 채팅 채널 아님)에 대한 참조입니다. 모델 선택 규칙은 모델을 참조하세요.

빠른 규칙

Plugin 소유 제공자 동작

대부분의 제공자별 로직은 제공자 Plugin(registerProvider(...))에 있으며, OpenClaw는 일반 추론 루프를 유지합니다. Plugin은 온보딩, 모델 카탈로그, 인증 환경 변수 매핑, 전송/구성 정규화, 도구 스키마 정리, 장애 조치 분류, OAuth 새로 고침, 사용량 보고, 사고/추론 프로필 등을 소유합니다.

제공자 SDK 훅과 번들 Plugin 예제의 전체 목록은 제공자 Plugin에 있습니다. 완전히 사용자 지정 요청 실행기가 필요한 제공자는 별도의 더 깊은 확장 표면입니다.

API 키 순환

기본 제공자(pi-ai 카탈로그)

OpenClaw는 pi-ai 카탈로그와 함께 제공됩니다. 이러한 제공자는 models.providers 구성이 필요 없습니다. 인증을 설정하고 모델을 선택하기만 하면 됩니다.

OpenAI

• 제공자: openai
• 인증: OPENAI_API_KEY
• 선택적 순환: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, 그리고 OPENCLAW_LIVE_OPENAI_KEY(단일 재정의)
• 예시 모델: openai/gpt-5.5, openai/gpt-5.4-mini
• 특정 설치 또는 API 키가 다르게 동작하면 openclaw models list --provider openai로 계정/모델 사용 가능 여부를 확인하세요.
• CLI: openclaw onboard --auth-choice openai-api-key
• 기본 전송은 auto입니다. OpenClaw는 전송 선택을 pi-ai에 전달합니다.
• 모델별 재정의는 agents.defaults.models["openai/<model>"].params.transport("sse", "websocket", 또는 "auto")를 통해 수행합니다.
• OpenAI 우선순위 처리는 agents.defaults.models["openai/<model>"].params.serviceTier를 통해 활성화할 수 있습니다.
• /fast 및 params.fastMode는 직접 openai/* Responses 요청을 api.openai.com의 service_tier=priority에 매핑합니다.
• 공유 /fast 토글 대신 명시적 티어를 원할 때는 params.serviceTier를 사용하세요.
• 숨겨진 OpenClaw 기여도 헤더(originator, version, User-Agent)는 api.openai.com으로 가는 네이티브 OpenAI 트래픽에만 적용되며, 일반 OpenAI 호환 프록시에는 적용되지 않습니다.
• 네이티브 OpenAI 경로는 Responses store, 프롬프트 캐시 힌트, OpenAI 추론 호환 페이로드 형성도 유지합니다. 프록시 경로는 그렇지 않습니다.
• openai/gpt-5.3-codex-spark는 라이브 OpenAI API 요청이 이를 거부하고 현재 Codex 카탈로그가 이를 노출하지 않기 때문에 OpenClaw에서 의도적으로 숨겨져 있습니다.

{  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

Anthropic

• 제공자: anthropic
• 인증: ANTHROPIC_API_KEY
• 선택적 순환: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, 그리고 OPENCLAW_LIVE_ANTHROPIC_KEY(단일 재정의)
• 예시 모델: anthropic/claude-opus-4-6
• CLI: openclaw onboard --auth-choice apiKey
• 직접 공개 Anthropic 요청은 공유 /fast 토글과 params.fastMode를 지원하며, 여기에는 api.anthropic.com으로 전송되는 API 키 및 OAuth 인증 트래픽이 포함됩니다. OpenClaw는 이를 Anthropic service_tier(auto 대 standard_only)에 매핑합니다.
• 선호 Claude CLI 구성은 모델 참조를 표준으로 유지하고 CLI 백엔드를 별도로 선택합니다. 모델 범위 agentRuntime.id: "claude-cli"와 함께 anthropic/claude-opus-4-7을 사용하세요. 레거시 claude-cli/claude-opus-4-7 참조도 호환성을 위해 계속 작동합니다.

{  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },}

OpenAI Codex OAuth

• 제공자: openai-codex
• 인증: OAuth(ChatGPT)
• 레거시 PI 모델 참조: openai-codex/gpt-5.5
• 네이티브 Codex 앱 서버 하네스 참조: openai/gpt-5.5
• 네이티브 Codex 앱 서버 하네스 문서: Codex 하네스
• 레거시 모델 참조: codex/gpt-*
• Plugin 경계: openai-codex/*는 OpenAI Plugin을 로드합니다. 네이티브 Codex 앱 서버 Plugin은 Codex 하네스 런타임 또는 레거시 codex/* 참조로만 선택됩니다.
• CLI: openclaw onboard --auth-choice openai-codex 또는 openclaw models auth login --provider openai-codex
• 기본 전송은 auto입니다(WebSocket 우선, SSE 폴백).
• PI 모델별 재정의는 agents.defaults.models["openai-codex/<model>"].params.transport("sse", "websocket", 또는 "auto")를 통해 수행합니다.
• params.serviceTier는 네이티브 Codex Responses 요청(chatgpt.com/backend-api)에도 전달됩니다.
• 숨겨진 OpenClaw 기여도 헤더(originator, version, User-Agent)는 chatgpt.com/backend-api로 가는 네이티브 Codex 트래픽에만 첨부되며, 일반 OpenAI 호환 프록시에는 첨부되지 않습니다.
• 직접 openai/*와 같은 /fast 토글 및 params.fastMode 구성을 공유합니다. OpenClaw는 이를 service_tier=priority에 매핑합니다.
• openai-codex/gpt-5.5는 Codex 카탈로그 네이티브 contextWindow = 400000과 기본 런타임 contextTokens = 272000을 사용합니다. 런타임 한도는 models.providers.openai-codex.models[].contextTokens로 재정의하세요.
• 정책 참고: OpenAI Codex OAuth는 OpenClaw 같은 외부 도구/워크플로에 명시적으로 지원됩니다.
• 일반적인 구독과 네이티브 Codex 런타임 경로의 경우 openai-codex 인증으로 로그인하되 openai/gpt-5.5를 구성하세요. OpenAI 에이전트 턴은 기본적으로 Codex를 선택합니다.
• PI를 통한 호환성 경로를 원할 때만 제공자/모델 agentRuntime.id: "pi"를 사용하세요. 그렇지 않으면 openai/gpt-5.5를 기본 Codex 하네스에 유지하세요.
• 이전 openai-codex/gpt-5.1*, openai-codex/gpt-5.2*, openai-codex/gpt-5.3* 참조는 ChatGPT/Codex OAuth 계정이 이를 거부하기 때문에 숨겨져 있습니다. 대신 openai-codex/gpt-5.5 또는 네이티브 Codex 런타임 경로를 사용하세요.

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },}

{  models: {    providers: {      "openai-codex": {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

기타 구독형 호스팅 옵션

OpenCode

• 인증: OPENCODE_API_KEY(또는 OPENCODE_ZEN_API_KEY)
• Zen 런타임 제공자: opencode
• Go 런타임 제공자: opencode-go
• 예시 모델: opencode/claude-opus-4-6, opencode-go/kimi-k2.6
• CLI: openclaw onboard --auth-choice opencode-zen 또는 openclaw onboard --auth-choice opencode-go

{  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },}

Google Gemini(API 키)

• 제공자: google
• 인증: GEMINI_API_KEY
• 선택적 순환: GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, GOOGLE_API_KEY 대체, 및 OPENCLAW_LIVE_GEMINI_KEY(단일 재정의)
• 예시 모델: google/gemini-3.1-pro-preview, google/gemini-3-flash-preview
• 호환성: google/gemini-3.1-flash-preview를 사용하는 기존 OpenClaw 구성은 google/gemini-3-flash-preview로 정규화됩니다.
• 별칭: google/gemini-3.1-pro는 허용되며 Google의 라이브 Gemini API ID인 google/gemini-3.1-pro-preview로 정규화됩니다.
• CLI: openclaw onboard --auth-choice gemini-api-key
• 사고: /think adaptive는 Google 동적 사고를 사용합니다. Gemini 3/3.1은 고정 thinkingLevel을 생략합니다. Gemini 2.5는 thinkingBudget: -1을 전송합니다.
• 직접 Gemini 실행은 제공자 네이티브 cachedContents/... 핸들을 전달하기 위해 agents.defaults.models["google/<model>"].params.cachedContent(또는 기존 cached_content)도 허용합니다. Gemini 캐시 적중은 OpenClaw cacheRead로 표시됩니다.

Google Vertex 및 Gemini CLI

• 제공자: google-vertex, google-gemini-cli
• 인증: Vertex는 gcloud ADC를 사용합니다. Gemini CLI는 자체 OAuth 흐름을 사용합니다.

Gemini CLI OAuth는 번들 google Plugin의 일부로 제공됩니다.

brew install gemini-cli

npm install -g @google/gemini-cli

openclaw plugins enable google

openclaw models auth login --provider google-gemini-cli --set-default

Gemini CLI JSON 응답은 response에서 파싱됩니다. 사용량은 stats로 대체되며, stats.cached는 OpenClaw cacheRead로 정규화됩니다.

Z.AI (GLM)

• 제공자: zai
• 인증: ZAI_API_KEY
• 예시 모델: zai/glm-5.1
• CLI: openclaw onboard --auth-choice zai-api-key
  • 별칭: z.ai/* 및 z-ai/*는 zai/*로 정규화됩니다.
  • zai-api-key는 일치하는 Z.AI 엔드포인트를 자동 감지합니다. zai-coding-global, zai-coding-cn, zai-global, 및 zai-cn은 특정 표면을 강제합니다.

Vercel AI Gateway

• 제공자: vercel-ai-gateway
• 인증: AI_GATEWAY_API_KEY
• 예시 모델: vercel-ai-gateway/anthropic/claude-opus-4.6, vercel-ai-gateway/moonshotai/kimi-k2.6
• CLI: openclaw onboard --auth-choice ai-gateway-api-key

Kilo Gateway

• 제공자: kilocode
• 인증: KILOCODE_API_KEY
• 예시 모델: kilocode/kilo/auto
• CLI: openclaw onboard --auth-choice kilocode-api-key
• 기본 URL: https://api.kilo.ai/api/gateway/
• 정적 대체 카탈로그는 kilocode/kilo/auto를 제공합니다. 라이브 https://api.kilo.ai/api/gateway/models 검색은 런타임 카탈로그를 더 확장할 수 있습니다.
• kilocode/kilo/auto 뒤의 정확한 업스트림 라우팅은 Kilo Gateway가 소유하며, OpenClaw에 하드코딩되어 있지 않습니다.

설정 세부 정보는 /providers/kilocode를 참조하세요.

기타 번들 제공자 Plugin

알아두면 좋은 특이 사항

models.providers를 통한 제공자(사용자 지정/base URL)

models.providers(또는 models.json)를 사용하여 사용자 지정 제공자나 OpenAI/Anthropic 호환 프록시를 추가하세요.

아래의 많은 번들 제공자 Plugin은 이미 기본 카탈로그를 게시합니다. 기본 base URL, 헤더 또는 모델 목록을 재정의하려는 경우에만 명시적인 models.providers.<id> 항목을 사용하세요.

Gateway 모델 기능 검사도 명시적인 models.providers.<id>.models[] 메타데이터를 읽습니다. 사용자 지정 또는 프록시 모델이 이미지를 허용하는 경우, WebChat 및 노드 출처 첨부 경로가 이미지를 텍스트 전용 미디어 참조 대신 네이티브 모델 입력으로 전달하도록 해당 모델에 input: ["text", "image"]를 설정하세요.

agents.defaults.models["provider/model"]은 에이전트의 모델 가시성, 별칭, 모델별 메타데이터만 제어합니다. 그 자체로 새 런타임 모델을 등록하지는 않습니다. 사용자 지정 제공자 모델의 경우, 최소한 일치하는 id가 포함된 models.providers.<provider>.models[]도 추가하세요.

Moonshot AI (Kimi)

Moonshot은 번들 제공자 Plugin으로 제공됩니다. 기본적으로 기본 제공 제공자를 사용하고, base URL이나 모델 메타데이터를 재정의해야 할 때만 명시적인 models.providers.moonshot 항목을 추가하세요.

• 제공자: moonshot
• 인증: MOONSHOT_API_KEY
• 예시 모델: moonshot/kimi-k2.6
• CLI: openclaw onboard --auth-choice moonshot-api-key 또는 openclaw onboard --auth-choice moonshot-api-key-cn

Kimi K2 모델 ID:

• moonshot/kimi-k2.6
• moonshot/kimi-k2.5
• moonshot/kimi-k2-thinking
• moonshot/kimi-k2-thinking-turbo
• moonshot/kimi-k2-turbo

{  agents: {    defaults: { model: { primary: "moonshot/kimi-k2.6" } },  },  models: {    mode: "merge",    providers: {      moonshot: {        baseUrl: "https://api.moonshot.ai/v1",        apiKey: "${MOONSHOT_API_KEY}",        api: "openai-completions",        models: [{ id: "kimi-k2.6", name: "Kimi K2.6" }],      },    },  },}

Kimi 코딩

Kimi Coding은 Moonshot AI의 Anthropic 호환 엔드포인트를 사용합니다:

• Provider: kimi
• Auth: KIMI_API_KEY
• 예시 모델: kimi/kimi-for-coding

{  env: { KIMI_API_KEY: "sk-..." },  agents: {    defaults: { model: { primary: "kimi/kimi-for-coding" } },  },}

레거시 kimi/kimi-code 및 kimi/k2p5는 호환성 모델 ID로 계속 허용되며 Kimi의 안정적인 API 모델 ID로 정규화됩니다.

Volcano Engine (Doubao)

Volcano Engine (火山引擎)은 중국에서 Doubao 및 기타 모델에 대한 액세스를 제공합니다.

• Provider: volcengine (코딩: volcengine-plan)
• Auth: VOLCANO_ENGINE_API_KEY
• 예시 모델: volcengine-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice volcengine-api-key

{  agents: {    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },  },}

온보딩은 기본적으로 코딩 표면을 사용하지만, 일반 volcengine/* 카탈로그도 동시에 등록됩니다.

온보딩/구성 모델 선택기에서 Volcengine 인증 선택지는 volcengine/* 및 volcengine-plan/* 행을 모두 선호합니다. 해당 모델이 아직 로드되지 않은 경우 OpenClaw는 빈 공급자 범위 선택기를 표시하는 대신 필터링되지 않은 카탈로그로 폴백합니다.

BytePlus(국제)

BytePlus ARK는 국제 사용자를 위해 Volcano Engine과 동일한 모델에 대한 액세스를 제공합니다.

• Provider: byteplus (코딩: byteplus-plan)
• Auth: BYTEPLUS_API_KEY
• 예시 모델: byteplus-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice byteplus-api-key

{  agents: {    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },  },}

온보딩은 기본적으로 코딩 표면을 사용하지만, 일반 byteplus/* 카탈로그도 동시에 등록됩니다.

온보딩/구성 모델 선택기에서 BytePlus 인증 선택지는 byteplus/* 및 byteplus-plan/* 행을 모두 선호합니다. 해당 모델이 아직 로드되지 않은 경우 OpenClaw는 빈 공급자 범위 선택기를 표시하는 대신 필터링되지 않은 카탈로그로 폴백합니다.

Synthetic

Synthetic은 synthetic 공급자 뒤에서 Anthropic 호환 모델을 제공합니다:

• Provider: synthetic
• Auth: SYNTHETIC_API_KEY
• 예시 모델: synthetic/hf:MiniMaxAI/MiniMax-M2.5
• CLI: openclaw onboard --auth-choice synthetic-api-key

{  agents: {    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" } },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.5", name: "MiniMax M2.5" }],      },    },  },}

MiniMax

MiniMax는 사용자 지정 엔드포인트를 사용하므로 models.providers를 통해 구성됩니다:

• MiniMax OAuth(글로벌): --auth-choice minimax-global-oauth
• MiniMax OAuth(CN): --auth-choice minimax-cn-oauth
• MiniMax API 키(글로벌): --auth-choice minimax-global-api
• MiniMax API 키(CN): --auth-choice minimax-cn-api
• Auth: minimax에는 MINIMAX_API_KEY; minimax-portal에는 MINIMAX_OAUTH_TOKEN 또는 MINIMAX_API_KEY

설정 세부 정보, 모델 옵션, 구성 스니펫은 /providers/minimax를 참조하세요.

Plugin 소유 기능 분리:

• 텍스트/채팅 기본값은 minimax/MiniMax-M2.7에 유지됩니다
• 이미지 생성은 minimax/image-01 또는 minimax-portal/image-01입니다
• 이미지 이해는 두 MiniMax 인증 경로 모두에서 Plugin 소유 MiniMax-VL-01입니다
• 웹 검색은 공급자 ID minimax에 유지됩니다

LM Studio

LM Studio는 네이티브 API를 사용하는 번들 공급자 Plugin으로 제공됩니다:

• Provider: lmstudio
• Auth: LM_API_TOKEN
• 기본 추론 기본 URL: http://localhost:1234/v1

그런 다음 모델을 설정합니다(http://localhost:1234/api/v1/models에서 반환된 ID 중 하나로 교체):

{  agents: {    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },  },}

OpenClaw는 기본적으로 검색 및 자동 로드에는 LM Studio의 네이티브 /api/v1/models 및 /api/v1/models/load를 사용하고, 추론에는 /v1/chat/completions를 사용합니다. LM Studio JIT 로딩, TTL, 자동 축출이 모델 수명 주기를 소유하도록 하려면 models.providers.lmstudio.params.preload: false를 설정하세요. 설정 및 문제 해결은 /providers/lmstudio를 참조하세요.

Ollama

Ollama는 번들 공급자 Plugin으로 제공되며 Ollama의 네이티브 API를 사용합니다:

• Provider: ollama
• Auth: 필요 없음(로컬 서버)
• 예시 모델: ollama/llama3.3
• 설치: https://ollama.com/download

# Ollama를 설치한 다음 모델을 가져옵니다:ollama pull llama3.3

{  agents: {    defaults: { model: { primary: "ollama/llama3.3" } },  },}

Ollama는 OLLAMA_API_KEY로 옵트인하면 http://127.0.0.1:11434에서 로컬로 감지되며, 번들 공급자 Plugin은 Ollama를 openclaw onboard와 모델 선택기에 직접 추가합니다. 온보딩, 클라우드/로컬 모드, 사용자 지정 구성은 /providers/ollama를 참조하세요.

vLLM

vLLM은 로컬/자체 호스팅 OpenAI 호환 서버를 위한 번들 공급자 Plugin으로 제공됩니다:

• Provider: vllm
• Auth: 선택 사항(서버에 따라 다름)
• 기본 기본 URL: http://127.0.0.1:8000/v1

로컬에서 자동 검색에 옵트인하려면(서버가 인증을 강제하지 않는 경우 어떤 값이든 작동):

export VLLM_API_KEY="vllm-local"

그런 다음 모델을 설정합니다(/v1/models에서 반환된 ID 중 하나로 교체):

{  agents: {    defaults: { model: { primary: "vllm/your-model-id" } },  },}

자세한 내용은 /providers/vllm을 참조하세요.

SGLang

SGLang은 빠른 자체 호스팅 OpenAI 호환 서버를 위한 번들 공급자 Plugin으로 제공됩니다:

• Provider: sglang
• Auth: 선택 사항(서버에 따라 다름)
• 기본 기본 URL: http://127.0.0.1:30000/v1

로컬에서 자동 검색에 옵트인하려면(서버가 인증을 강제하지 않는 경우 어떤 값이든 작동):

export SGLANG_API_KEY="sglang-local"

그런 다음 모델을 설정합니다(/v1/models에서 반환된 ID 중 하나로 교체):

{  agents: {    defaults: { model: { primary: "sglang/your-model-id" } },  },}

자세한 내용은 /providers/sglang을 참조하세요.

로컬 프록시(LM Studio, vLLM, LiteLLM 등)

예시(OpenAI 호환):

{  agents: {    defaults: {      model: { primary: "lmstudio/my-local-model" },      models: { "lmstudio/my-local-model": { alias: "Local" } },    },  },  models: {    providers: {      lmstudio: {        baseUrl: "http://localhost:1234/v1",        apiKey: "${LM_API_TOKEN}",        api: "openai-completions",        timeoutSeconds: 300,        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 200000,            maxTokens: 8192,          },        ],      },    },  },}

CLI 예시

openclaw onboard --auth-choice opencode-zenopenclaw models set opencode/claude-opus-4-6openclaw models list

전체 구성 예시는 구성도 참조하세요.

관련 항목

• 구성 참조 - 모델 구성 키
• 모델 장애 조치 - 폴백 체인 및 재시도 동작
• 모델 - 모델 구성 및 별칭
• 공급자 - 공급자별 설정 가이드