모델 제공자

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

빠른 규칙

Plugin 소유 제공자 동작

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

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

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.5, openai/gpt-5.4-mini
• 특정 설치 또는 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")를 통해 수행합니다.
• 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 reasoning 호환 페이로드 구성도 유지합니다. 프록시 라우트는 그렇지 않습니다.
• openai/gpt-5.3-codex-spark는 로그인한 계정이 이를 노출할 때 ChatGPT/Codex OAuth 구독 인증을 통해 사용할 수 있습니다. OpenClaw는 이 모델에 대해 직접 OpenAI API 키 및 Azure API 키 라우트를 계속 억제합니다. 해당 전송이 이를 거부하기 때문입니다.

{  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 요청은 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)
• 레거시 OpenAI Codex 모델 참조: openai/gpt-5.5
• 네이티브 Codex 앱 서버 하네스 참조: openai/gpt-5.5
• 네이티브 Codex 앱 서버 하네스 문서: Codex harness
• 레거시 모델 참조: codex/gpt-*
• Plugin 경계: openai/*는 OpenAI Plugin을 로드합니다. 네이티브 Codex 앱 서버 Plugin은 Codex 하네스 런타임이 선택합니다.
• CLI: openclaw onboard --auth-choice openai 또는 openclaw models auth login --provider openai
• 기본 전송은 auto입니다(WebSocket 우선, SSE 폴백).
• OpenAI Codex 모델별 재정의는 agents.defaults.models["openai/<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/gpt-5.5는 Codex 카탈로그 네이티브 contextWindow = 400000과 기본 런타임 contextTokens = 272000을 사용합니다. 런타임 한도는 models.providers.openai.models[].contextTokens로 재정의하세요.
• 정책 참고: OpenAI Codex OAuth는 OpenClaw 같은 외부 도구/워크플로에 대해 명시적으로 지원됩니다.
• 일반적인 구독 및 네이티브 Codex 런타임 라우트의 경우 openai 인증으로 로그인하고 openai/gpt-5.5를 구성하세요. OpenAI 에이전트 턴은 기본적으로 Codex를 선택합니다.
• 내장 OpenClaw 라우트를 원할 때만 제공자/모델 agentRuntime.id: "openclaw"를 사용하세요. 그렇지 않으면 openai/gpt-5.5를 기본 Codex 하네스에 유지하세요.
• 레거시 Codex GPT 참조는 라이브 제공자 라우트가 아니라 레거시 상태입니다. 새 에이전트 구성에는 네이티브 Codex 런타임의 openai/gpt-5.5를 사용하고, 이전 레거시 Codex 모델 참조를 정규 openai/* 참조로 마이그레이션하려면 openclaw doctor --fix를 실행하세요.

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

{  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-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 실행은 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를 통한 제공자(사용자 지정/base URL)

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

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

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

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

Moonshot AI (Kimi)

온보딩하기 전에 @openclaw/moonshot-provider를 설치하세요. 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.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" }],      },    },  },}

Kimi 코딩

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는 비어 있는 provider 범위 선택기를 표시하는 대신 필터링되지 않은 카탈로그로 폴백합니다.

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는 비어 있는 provider 범위 선택기를 표시하는 대신 필터링되지 않은 카탈로그로 폴백합니다.

Synthetic

Synthetic은 synthetic provider 뒤에서 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(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-M3에 유지됩니다.
• 이미지 생성은 minimax/image-01 또는 minimax-portal/image-01입니다.
• 이미지 이해는 두 MiniMax 인증 경로 모두에서 Plugin 소유 MiniMax-VL-01입니다.
• 웹 검색은 provider ID minimax에 유지됩니다.

LM Studio

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

Ollama

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

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

vLLM

vLLM은 로컬/자체 호스팅 OpenAI 호환 서버용 번들 provider 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 호환 서버용 번들 provider 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

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

관련 항목

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