모델 제공업체

LLM/모델 제공자에 대한 참조 문서입니다(WhatsApp/Telegram과 같은 채팅 채널이 아님). 모델 선택 규칙은 모델을 참조하십시오.

빠른 규칙

Plugin 소유의 제공자 동작

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

제공자 SDK 후크와 번들 Plugin 예제의 전체 목록은 제공자 Plugin에 있습니다. 완전히 사용자 지정된 요청 실행기가 필요한 제공자는 별도의 더 심층적인 확장 표면입니다.

API 키 순환

공식 제공자 Plugin

공식 제공자 Plugin은 자체 모델 카탈로그 행을 게시합니다. 이러한 제공자는 models.providers 모델 항목이 필요하지 않습니다. 제공자 Plugin을 활성화하고 인증을 설정한 다음 모델을 선택하십시오. 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.6; 직접 API에서는 장식 없는 ID가 Sol로 해석됩니다.
• 모델 예시: openai/gpt-5.6, openai/gpt-5.6-terra, openai/gpt-5.6-luna, openai/gpt-5.5
• 특정 설치 또는 API 키가 다르게 작동하는 경우 openclaw models list --provider openai로 계정/모델 가용성을 확인하십시오.
• CLI: openclaw onboard --auth-choice openai-api-key
• 기본 전송 방식은 auto입니다. OpenClaw는 전송 방식 선택을 공유 모델 런타임에 전달합니다.
• 모델별 재정의는 agents.defaults.models["openai/<model>"].params.transport를 통해 설정합니다("sse", "websocket" 또는 "auto").
• agents.defaults.models["openai/<model>"].params.serviceTier를 통해 OpenAI 우선 처리 기능을 활성화할 수 있습니다.
• /fast와 params.fastMode는 api.openai.com에 대한 직접 openai/* Responses 요청을 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는 ChatGPT/Codex OAuth를 통해서만 사용할 수 있으며, 직접 OpenAI API 키 및 Azure API 키 경로에서는 거부됩니다.

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

API 조직에서 GPT-5.6을 제공하지 않으면 openai/gpt-5.5를 명시적으로 설정하십시오. 일반 온보딩과 재인증은 기존의 명시적 기본 모델을 유지하며, models auth login --set-default와 models set은 의도적인 교체 경로입니다.

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 요청은 api.anthropic.com으로 전송되는 API 키 및 OAuth 인증 트래픽을 포함하여 공유 /fast 토글과 params.fastMode를 지원합니다. OpenClaw는 이를 Anthropic service_tier(auto와 standard_only)에 매핑합니다.
• 권장 Claude CLI 구성은 모델 참조를 정식 형식으로 유지하고 CLI 백엔드를 별도로 선택합니다. 즉, anthropic/claude-opus-4-8과 모델 범위의 agentRuntime.id: "claude-cli"를 사용합니다. 레거시 claude-cli/claude-opus-4-7 참조도 호환성을 위해 계속 작동합니다.

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

OpenAI ChatGPT/Codex OAuth

• 제공자: openai
• 인증: OAuth(ChatGPT)
• 새로운 네이티브 Codex 앱 서버 하네스 참조: openai/gpt-5.6-sol
• 네이티브 Codex 앱 서버 하네스 문서: Codex 하네스
• 레거시 모델 참조: codex/gpt-*
• Plugin 경계: openai/*는 OpenAI Plugin을 로드하며, 명시적 런타임 정책 또는 제공자가 소유한 유효 경로가 네이티브 Codex 앱 서버 Plugin의 선택 여부를 결정합니다.
• CLI: openclaw onboard --auth-choice openai 또는 openclaw models auth login --provider openai
• OpenClaw에 내장된 ChatGPT Responses 전송 방식의 기본값은 auto입니다(WebSocket 우선, SSE 폴백).
• agents.defaults.models["openai/<model>"].params.transport, params.serviceTier, params.fastMode는 작성된 내장 요청 설정입니다. 이 설정은 암시적 런타임 선택을 OpenClaw에 유지하며, 네이티브 Codex는 자체 앱 서버 전송 방식과 서비스 티어를 소유합니다.
• 숨겨진 OpenClaw 귀속 헤더(originator, version, User-Agent)는 chatgpt.com/backend-api로 향하는 네이티브 Codex 트래픽에만 첨부되며, 일반 OpenAI 호환 프록시에는 첨부되지 않습니다.
• 공유 /fast 토글은 런타임 제어로 계속 사용할 수 있으며, 작성된 모델 매개변수와는 별개입니다.
• 네이티브 Codex 카탈로그는 계정 액세스 권한에 따라 정확한 openai/gpt-5.6-sol, openai/gpt-5.6-terra, openai/gpt-5.6-luna 참조를 제공할 수 있습니다. 직접 API의 장식 없는 gpt-5.6 별칭은 클라이언트 측에서 적용하지 않습니다.
• openai/gpt-5.5는 Codex 카탈로그의 네이티브 contextWindow = 400000과 기본 런타임 contextTokens = 272000을 사용합니다. 런타임 상한을 재정의하려면 models.providers.openai.models[].contextTokens를 사용하십시오.
• 새로운 구독 기반 설정에서는 openai 인증으로 로그인하고 openai/gpt-5.6-sol을 사용하십시오. 해당 Codex 작업 공간에서 GPT-5.6을 제공하지 않으면 openai/gpt-5.5를 명시적으로 선택하십시오.
• 그 외에는 적합한 경로를 내장 런타임에 유지하려면 제공자/모델의 agentRuntime.id: "openclaw"를 사용하십시오. 런타임이 설정되지 않았거나 auto이면 작성된 요청 재정의가 없는 정확한 공식 HTTPS Responses/ChatGPT 호환 경로만 Codex를 암시적으로 선택할 수 있습니다.
• 레거시 Codex GPT 참조는 라이브 제공자 경로가 아니라 레거시 상태입니다. 새 에이전트 구성에는 정식 openai/* 참조를 사용하고, 기존의 명시적 openai/gpt-5.5 선택을 업그레이드하지 않으면서 오래된 레거시 Codex 모델 참조를 마이그레이션하려면 openclaw doctor --fix를 실행하십시오.

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

{  models: {    providers: {      openai: {        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.5-flash
• 호환성: 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 실행에서는 agents.defaults.models["google/<model>"].params.cachedContent(또는 기존 cached_content)도 허용하여 제공자 네이티브 cachedContents/... 핸들을 전달합니다. 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는 기본적으로 stream-json을 사용합니다. OpenClaw는 어시스턴트 스트림 메시지를 읽고 stats.cached를 cacheRead로 정규화합니다. 기존 --output-format json 재정의에서도 response의 응답 텍스트를 계속 읽습니다.

Z.AI (GLM)

• 제공자: zai
• 인증: ZAI_API_KEY
• 모델 예시: zai/glm-5.2
• CLI: openclaw onboard --auth-choice zai-api-key
  • 모델 참조는 표준 zai/* 제공자 ID를 사용합니다.
  • 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

기타 번들 제공자 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에서 시작된 첨부 파일 경로가 이미지를 텍스트 전용 미디어 참조 대신 네이티브 모델 입력으로 전달하도록 하십시오.

agents.defaults.models["provider/model"]은 에이전트의 모델 표시 여부, 별칭 및 모델별 메타데이터만 제어합니다. 이것만으로는 새 런타임 모델을 등록하지 않습니다. 사용자 지정 제공자 모델의 경우 일치하는 id 이상을 포함하여 models.providers.<provider>.models[]도 추가하십시오.

Moonshot AI(Kimi)

온보딩 전에 @openclaw/moonshot-provider를 설치하십시오. 기본 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.7-code
• 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" }],      },    },  },}

전체 설정 가이드는 Moonshot AI(Kimi + Kimi Coding)을 참조하십시오.

Kimi Coding

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

• 제공자: kimi
• 인증: 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 및 기타 모델에 대한 액세스를 제공합니다.

• 제공자: 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과 동일한 모델에 대한 액세스를 제공합니다.

• 제공자: 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 호환 모델을 제공합니다.

• 제공자: 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(중국): --auth-choice minimax-cn-oauth
• MiniMax API 키(글로벌): --auth-choice minimax-global-api
• MiniMax API 키(중국): --auth-choice minimax-cn-api
• 인증: minimax에는 MINIMAX_API_KEY, minimax-portal에는 MINIMAX_OAUTH_TOKEN 또는 MINIMAX_API_KEY

설정 세부 정보, 모델 옵션 및 구성 스니펫은 /providers/minimax을 참조하십시오.

Plugin 소유 기능 분리:

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

LM Studio

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

• 제공자: 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를 사용합니다.

• 제공자: 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에서 감지되며, 번들 제공자 Plugin은 Ollama를 openclaw onboard와 모델 선택기에 직접 추가합니다. 온보딩, 클라우드/로컬 모드 및 사용자 지정 구성은 /providers/ollama를 참조하십시오.

vLLM

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

• 제공자: 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으로 제공됩니다.

• 제공자: 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-zenopenclaw models set opencode/claude-opus-4-6openclaw models list

전체 구성 예시는 구성도 참조하십시오.

관련 항목

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