모델 프로바이더

이 페이지는 LLM/모델 프로바이더를 다룹니다 (WhatsApp/Telegram 같은 채팅 채널이 아닙니다). 모델 선택 규칙은 /concepts/models를 참고하세요.

핵심 규칙

• 모델 참조는 provider/model 형식 (예: opencode/claude-opus-4-6).
• agents.defaults.models를 설정하면 허용 목록이 됩니다.
• CLI 도우미: openclaw onboard, openclaw models list, openclaw models set <provider/model>.

API 키 순환

• 일부 프로바이더에서 범용 프로바이더 순환을 지원합니다.
• 여러 키를 다음과 같이 설정:
  • OPENCLAW_LIVE_<PROVIDER>_KEY (단일 라이브 오버라이드, 최우선)
  • <PROVIDER>_API_KEYS (쉼표 또는 세미콜론 목록)
  • <PROVIDER>_API_KEY (기본 키)
  • <PROVIDER>_API_KEY_* (번호 목록, 예: <PROVIDER>_API_KEY_1)
• Google 프로바이더의 경우 GOOGLE_API_KEY도 폴백으로 포함됩니다.
• 키 선택 순서는 우선순위를 유지하고 중복 값을 제거합니다.
• 요청은 속도 제한 응답(예: 429, rate_limit, quota, resource exhausted)에서만 다음 키로 재시도됩니다.
• 속도 제한이 아닌 실패는 즉시 실패합니다. 키 순환이 시도되지 않습니다.
• 모든 후보 키가 실패하면 마지막 시도의 최종 오류가 반환됩니다.

내장 프로바이더 (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.4, openai/gpt-5.4-pro
• 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로 활성화 가능
• OpenAI 패스트 모드: agents.defaults.models["<provider>/<model>"].params.fastMode로 모델별 활성화 가능
• openai/gpt-5.3-codex-spark는 라이브 OpenAI API에서 거부하므로 OpenClaw에서 의도적으로 억제됨. Spark는 Codex 전용으로 처리

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

Anthropic

• 프로바이더: anthropic
• 인증: ANTHROPIC_API_KEY 또는 claude setup-token
• 선택적 순환: 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 token (setup-token 붙여넣기) 또는 openclaw models auth paste-token --provider anthropic
• 직접 API 키 모델은 공유 /fast 토글과 params.fastMode를 지원합니다. OpenClaw는 이를 Anthropic service_tier (auto vs standard_only)로 매핑
• 정책 참고: setup-token 지원은 기술적 호환성입니다. Anthropic은 과거에 Claude Code 외부에서의 일부 구독 사용을 차단한 적이 있습니다. 현재 Anthropic 약관을 확인하고 위험 감수 수준에 따라 결정하세요.
• 권장: 구독 setup-token 인증보다 Anthropic API 키 인증이 더 안전한 권장 경로입니다.

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

OpenAI Code (Codex)

• 프로바이더: openai-codex
• 인증: OAuth (ChatGPT)
• 예시 모델: openai-codex/gpt-5.4
• CLI: openclaw onboard --auth-choice openai-codex 또는 openclaw models auth login --provider openai-codex
• 기본 전송은 auto (WebSocket 우선, SSE 폴백)
• 모델별 오버라이드: agents.defaults.models["openai-codex/<model>"].params.transport ("sse", "websocket", 또는 "auto")
• 직접 openai/*와 동일한 /fast 토글 및 params.fastMode 설정 공유
• openai-codex/gpt-5.3-codex-spark는 Codex OAuth 카탈로그가 노출할 때 사용 가능. 자격에 따라 달라짐
• 정책 참고: OpenAI Codex OAuth는 OpenClaw 같은 외부 도구/워크플로에 대해 명시적으로 지원됩니다.

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

OpenCode

• 인증: OPENCODE_API_KEY (또는 OPENCODE_ZEN_API_KEY)
• Zen 런타임 프로바이더: opencode
• Go 런타임 프로바이더: opencode-go
• 예시 모델: opencode/claude-opus-4-6, opencode-go/kimi-k2.5
• 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로 정규화됨
• CLI: openclaw onboard --auth-choice gemini-api-key

Google Vertex, Antigravity, Gemini CLI

• 프로바이더: google-vertex, google-antigravity, google-gemini-cli
• 인증: Vertex는 gcloud ADC 사용, Antigravity/Gemini CLI는 각각의 인증 흐름 사용
• 주의: OpenClaw에서의 Antigravity 및 Gemini CLI OAuth는 비공식 통합입니다. 일부 사용자가 타사 클라이언트 사용 후 Google 계정 제한을 보고한 바 있습니다. Google 약관을 검토하고 진행하려면 중요하지 않은 계정을 사용하세요.
• Antigravity OAuth는 번들 플러그인(google-antigravity-auth, 기본 비활성)으로 제공됩니다.
  • 활성화: openclaw plugins enable google-antigravity-auth
  • 로그인: openclaw models auth login --provider google-antigravity --set-default
• Gemini CLI OAuth는 번들 플러그인(google-gemini-cli-auth, 기본 비활성)으로 제공됩니다.
  • 활성화: openclaw plugins enable google-gemini-cli-auth
  • 로그인: openclaw models auth login --provider google-gemini-cli --set-default
  • 참고: client id나 secret를 openclaw.json에 붙여넣을 필요가 없습니다. CLI 로그인 흐름이 게이트웨이 호스트의 인증 프로필에 토큰을 저장합니다.

Z.AI (GLM)

• 프로바이더: zai
• 인증: ZAI_API_KEY
• 예시 모델: zai/glm-5
• CLI: openclaw onboard --auth-choice zai-api-key
  • 별칭: z.ai/* 및 z-ai/*는 zai/*로 정규화

Vercel AI Gateway

• 프로바이더: vercel-ai-gateway
• 인증: AI_GATEWAY_API_KEY
• 예시 모델: vercel-ai-gateway/anthropic/claude-opus-4.6
• CLI: openclaw onboard --auth-choice ai-gateway-api-key

Kilo Gateway

• 프로바이더: kilocode
• 인증: KILOCODE_API_KEY
• 예시 모델: kilocode/anthropic/claude-opus-4.6
• CLI: openclaw onboard --kilocode-api-key <key>
• 기본 URL: https://api.kilo.ai/api/gateway/
• 확장된 내장 카탈로그에 GLM-5 Free, MiniMax M2.5 Free, GPT-5.2, Gemini 3 Pro Preview, Gemini 3 Flash Preview, Grok Code Fast 1, Kimi K2.5 포함.

설정 세부사항은 /providers/kilocode를 참고하세요.

기타 내장 프로바이더

• OpenRouter: openrouter (OPENROUTER_API_KEY)
• 예시 모델: openrouter/anthropic/claude-sonnet-4-5
• Kilo Gateway: kilocode (KILOCODE_API_KEY)
• 예시 모델: kilocode/anthropic/claude-opus-4.6
• xAI: xai (XAI_API_KEY)
• Mistral: mistral (MISTRAL_API_KEY)
• 예시 모델: mistral/mistral-large-latest
• CLI: openclaw onboard --auth-choice mistral-api-key
• Groq: groq (GROQ_API_KEY)
• Cerebras: cerebras (CEREBRAS_API_KEY)
  • Cerebras의 GLM 모델은 zai-glm-4.7 및 zai-glm-4.6 ID를 사용.
  • OpenAI 호환 기본 URL: https://api.cerebras.ai/v1.
• GitHub Copilot: github-copilot (COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN)
• Hugging Face Inference: huggingface (HUGGINGFACE_HUB_TOKEN 또는 HF_TOKEN) — OpenAI 호환 라우터. 예시 모델: huggingface/deepseek-ai/DeepSeek-R1. CLI: openclaw onboard --auth-choice huggingface-api-key. Hugging Face (Inference) 참고.

models.providers를 통한 프로바이더 (커스텀/기본 URL)

models.providers (또는 models.json)로 커스텀 프로바이더나 OpenAI/Anthropic 호환 프록시를 추가합니다.

Moonshot AI (Kimi)

Moonshot은 OpenAI 호환 엔드포인트를 사용하므로 커스텀 프로바이더로 설정합니다:

• 프로바이더: moonshot
• 인증: MOONSHOT_API_KEY
• 예시 모델: moonshot/kimi-k2.5

Kimi K2 모델 ID:

{/_ moonshot-kimi-k2-model-refs:start _/ && null}

• moonshot/kimi-k2.5
• moonshot/kimi-k2-0905-preview
• moonshot/kimi-k2-turbo-preview
• moonshot/kimi-k2-thinking
• moonshot/kimi-k2-thinking-turbo {/_ moonshot-kimi-k2-model-refs:end _/ && null}

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

Kimi Coding

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

• 프로바이더: kimi-coding
• 인증: KIMI_API_KEY
• 예시 모델: kimi-coding/k2p5

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

Qwen OAuth (무료 티어)

Qwen은 디바이스 코드 흐름을 통해 Qwen Coder + Vision에 대한 OAuth 접근을 제공합니다. 번들 플러그인을 활성화한 후 로그인하세요:

openclaw plugins enable qwen-portal-auth
openclaw models auth login --provider qwen-portal --set-default

모델 참조:

• qwen-portal/coder-model
• qwen-portal/vision-model

설정 세부사항과 참고사항은 /providers/qwen을 참고하세요.

Volcano Engine (Doubao)

Volcano Engine(火山引擎)은 중국에서 Doubao 및 기타 모델에 대한 접근을 제공합니다.

• 프로바이더: volcengine (코딩: volcengine-plan)
• 인증: VOLCANO_ENGINE_API_KEY
• 예시 모델: volcengine/doubao-seed-1-8-251228
• CLI: openclaw onboard --auth-choice volcengine-api-key

{
  agents: {
    defaults: { model: { primary: "volcengine/doubao-seed-1-8-251228" } },
  },
}

사용 가능한 모델:

• volcengine/doubao-seed-1-8-251228 (Doubao Seed 1.8)
• volcengine/doubao-seed-code-preview-251028
• volcengine/kimi-k2-5-260127 (Kimi K2.5)
• volcengine/glm-4-7-251222 (GLM 4.7)
• volcengine/deepseek-v3-2-251201 (DeepSeek V3.2 128K)

코딩 모델 (volcengine-plan):

• volcengine-plan/ark-code-latest
• volcengine-plan/doubao-seed-code
• volcengine-plan/kimi-k2.5
• volcengine-plan/kimi-k2-thinking
• volcengine-plan/glm-4.7

BytePlus (국제)

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

• 프로바이더: byteplus (코딩: byteplus-plan)
• 인증: BYTEPLUS_API_KEY
• 예시 모델: byteplus/seed-1-8-251228
• CLI: openclaw onboard --auth-choice byteplus-api-key

{
  agents: {
    defaults: { model: { primary: "byteplus/seed-1-8-251228" } },
  },
}

사용 가능한 모델:

• byteplus/seed-1-8-251228 (Seed 1.8)
• byteplus/kimi-k2-5-260127 (Kimi K2.5)
• byteplus/glm-4-7-251222 (GLM 4.7)

코딩 모델 (byteplus-plan):

• byteplus-plan/ark-code-latest
• byteplus-plan/doubao-seed-code
• byteplus-plan/kimi-k2.5
• byteplus-plan/kimi-k2-thinking
• byteplus-plan/glm-4.7

Synthetic

Synthetic는 synthetic 프로바이더 뒤에서 Anthropic 호환 모델을 제공합니다:

• 프로바이더: 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 (Anthropic 호환): --auth-choice minimax-api
• 인증: MINIMAX_API_KEY

설정 세부사항, 모델 옵션, 설정 스니펫은 /providers/minimax를 참고하세요.

Ollama

Ollama는 번들 프로바이더 플러그인으로 제공되며 Ollama의 네이티브 API를 사용합니다:

• 프로바이더: ollama
• 인증: 불필요 (로컬 서버)
• 예시 모델: ollama/llama3.3
• 설치: https://ollama.com/download

# Ollama 설치 후 모델 풀:
ollama pull llama3.3

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

OLLAMA_API_KEY로 선택하면 Ollama가 http://127.0.0.1:11434에서 로컬로 감지되며, 번들 프로바이더 플러그인이 openclaw onboard와 모델 선택기에 Ollama를 직접 추가합니다. 온보딩, 클라우드/로컬 모드, 커스텀 설정은 /providers/ollama를 참고하세요.

vLLM

vLLM은 로컬/자체 호스팅 OpenAI 호환 서버를 위한 번들 프로바이더 플러그인으로 제공됩니다:

• 프로바이더: 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 호환 서버를 위한 번들 프로바이더 플러그인으로 제공됩니다:

• 프로바이더: 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/minimax-m2.5-gs32" },
      models: { "lmstudio/minimax-m2.5-gs32": { alias: "Minimax" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "LMSTUDIO_KEY",
        api: "openai-completions",
        models: [
          {
            id: "minimax-m2.5-gs32",
            name: "MiniMax M2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

참고:

• 커스텀 프로바이더의 경우 reasoning, input, cost, contextWindow, maxTokens는 선택 사항입니다. 생략 시 OpenClaw 기본값:
  • reasoning: false
  • input: ["text"]
  • cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
  • contextWindow: 200000
  • maxTokens: 8192
• 권장: 프록시/모델 한계에 맞는 명시적 값을 설정하세요.
• 비네이티브 엔드포인트(호스트가 api.openai.com이 아닌 비어있지 않은 baseUrl)에서 api: "openai-completions"의 경우, OpenClaw는 지원되지 않는 developer 역할에 대한 프로바이더 400 오류를 방지하기 위해 compat.supportsDeveloperRole: false를 강제합니다.
• baseUrl이 비어있거나 생략되면 OpenClaw는 기본 OpenAI 동작을 유지합니다 (api.openai.com으로 해석).
• 안전을 위해 비네이티브 openai-completions 엔드포인트에서는 명시적 compat.supportsDeveloperRole: true도 오버라이드됩니다.

CLI 예시

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

전체 설정 예시는 /gateway/configuration을 참고하세요.