모델 제공자

LLM/model providers LLM/model 공급자(WhatsApp/Telegram 같은 채팅 채널이 아님)에 대한 참고 자료입니다. 모델 선택 규칙은 Models를 참조하세요.

# 빠른 규칙

# 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입니다(WebSocket 우선, SSE 폴백).
• 모델별 재정의는 agents.defaults.models["openai/<model>"].params.transport("sse", "websocket", 또는 "auto")를 통해 설정합니다.
• OpenAI Responses WebSocket 워밍업은 기본적으로 params.openaiWsWarmup(true/false)를 통해 활성화됩니다.
• 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 백엔드를 별도로 선택합니다. anthropic/claude-opus-4-7과 agents.defaults.agentRuntime.id: "claude-cli"를 사용하세요. 레거시 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 앱 서버 하네스 참조: agents.defaults.agentRuntime.id: "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 인증으로 로그인하되, agents.defaults.agentRuntime.id: "codex"와 함께 openai/gpt-5.5를 구성하세요.
• PI를 통한 Codex OAuth/구독 경로를 원할 때만 openai-codex/gpt-5.5를 사용하세요. API 키 설정과 로컬 카탈로그가 공개 API 경로를 노출하는 경우 Codex 런타임 재정의 없이 openai/gpt-5.5를 사용하세요.
• 이전 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" },
      agentRuntime: { id: "codex" },
    },
  },
}

{
  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
• Thinking: /think adaptive는 Google 동적 thinking을 사용합니다. 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 뒤의 정확한 업스트림 라우팅은 OpenClaw에 하드코딩되어 있지 않고 Kilo Gateway가 소유합니다.

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

# 기타 번들 제공자 Plugin

# 알아두면 좋은 특이 사항

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

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

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

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

# Moonshot AI(Kimi)

Moonshot은 번들 제공자 Plugin으로 제공됩니다. 기본적으로 내장 제공자를 사용하고, 기본 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 호환 엔드포인트를 사용합니다.

• 제공자: kimi
• 인증: KIMI_API_KEY
• 예제 모델: kimi/kimi-code

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

Legacy kimi/k2p5는 호환성 모델 ID로 계속 허용됩니다.

# Volcano Engine (Doubao)

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

• Provider: volcengine (코딩: volcengine-plan)
• 인증: 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)
• 인증: 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
• 인증: 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
• 인증: 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입니다.
• Web search는 공급자 ID minimax에 유지됩니다.

# LM Studio

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

• Provider: lmstudio
• 인증: 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
• 인증: 필요 없음(로컬 서버)
• 예시 모델: ollama/llama3.3
• 설치: https://ollama.com/download

# Install Ollama, then pull a model:
ollama pull llama3.3

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

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

# vLLM

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

• Provider: vllm
• 인증: 선택 사항(서버에 따라 다름)
• 기본 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
• 인증: 선택 사항(서버에 따라 다름)
• 기본 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-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list

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

# 관련 항목

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