Penyedia model

Referensi untuk penyedia LLM/model (bukan kanal chat seperti WhatsApp/Telegram). Untuk aturan pemilihan model, lihat Model.

Aturan cepat

Perilaku penyedia milik Plugin

Sebagian besar logika khusus penyedia berada dalam Plugin penyedia (registerProvider(...)) sementara OpenClaw mempertahankan loop inferensi generik. Plugin memiliki onboarding, katalog model, pemetaan env-var auth, normalisasi transport/konfigurasi, pembersihan skema alat, klasifikasi failover, refresh OAuth, pelaporan penggunaan, profil berpikir/penalaran, dan banyak lagi.

Daftar lengkap hook SDK penyedia dan contoh Plugin yang dibundel ada di Plugin penyedia. Penyedia yang membutuhkan eksekutor permintaan yang benar-benar kustom adalah permukaan ekstensi yang terpisah dan lebih dalam.

Rotasi kunci API

Plugin penyedia resmi

Plugin penyedia resmi menerbitkan baris katalog model mereka sendiri. Penyedia ini tidak memerlukan entri model models.providers; aktifkan Plugin penyedia, atur auth, dan pilih model. Gunakan models.providers hanya untuk penyedia kustom eksplisit atau pengaturan permintaan sempit seperti timeout.

OpenAI

• Penyedia: openai
• Auth: OPENAI_API_KEY
• Rotasi opsional: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, plus OPENCLAW_LIVE_OPENAI_KEY (override tunggal)
• Contoh model: openai/gpt-5.5, openai/gpt-5.4-mini
• Verifikasi ketersediaan akun/model dengan openclaw models list --provider openai jika instalasi atau kunci API tertentu berperilaku berbeda.
• CLI: openclaw onboard --auth-choice openai-api-key
• Transport default adalah auto; OpenClaw meneruskan pilihan transport ke runtime model bersama.
• Override per model melalui agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket", atau "auto")
• Pemrosesan prioritas OpenAI dapat diaktifkan melalui agents.defaults.models["openai/<model>"].params.serviceTier
• /fast dan params.fastMode memetakan permintaan Responses openai/* langsung ke service_tier=priority pada api.openai.com
• Gunakan params.serviceTier ketika Anda menginginkan tingkat eksplisit alih-alih toggle /fast bersama
• Header atribusi OpenClaw tersembunyi (originator, version, User-Agent) hanya berlaku pada traffic OpenAI native ke api.openai.com, bukan proxy generik yang kompatibel dengan OpenAI
• Rute OpenAI native juga mempertahankan store Responses, petunjuk prompt-cache, dan pembentukan payload kompatibilitas penalaran OpenAI; rute proxy tidak
• openai/gpt-5.3-codex-spark tersedia melalui auth langganan OAuth ChatGPT/Codex ketika akun yang Anda gunakan mengeksposnya; OpenClaw masih menekan rute kunci API OpenAI langsung dan kunci API Azure untuk model ini karena transport tersebut menolaknya

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

Anthropic

• Penyedia: anthropic
• Auth: ANTHROPIC_API_KEY
• Rotasi opsional: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, plus OPENCLAW_LIVE_ANTHROPIC_KEY (override tunggal)
• Contoh model: anthropic/claude-opus-4-6
• CLI: openclaw onboard --auth-choice apiKey
• Permintaan Anthropic publik langsung mendukung toggle /fast bersama dan params.fastMode, termasuk traffic kunci API dan yang diautentikasi OAuth yang dikirim ke api.anthropic.com; OpenClaw memetakannya ke service_tier Anthropic (auto vs standard_only)
• Konfigurasi Claude CLI pilihan mempertahankan referensi model kanonis dan memilih backend CLI secara terpisah: anthropic/claude-opus-4-8 dengan agentRuntime.id: "claude-cli" bercakupan model. Referensi legacy claude-cli/claude-opus-4-7 tetap berfungsi untuk kompatibilitas.

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

OAuth OpenAI ChatGPT/Codex

• Penyedia: openai
• Auth: OAuth (ChatGPT)
• Referensi model OpenAI Codex legacy: openai/gpt-5.5
• Referensi harness app-server Codex native: openai/gpt-5.5
• Dokumen harness app-server Codex native: Harness Codex
• Referensi model legacy: codex/gpt-*
• Batas Plugin: openai/* memuat Plugin OpenAI; Plugin app-server Codex native dipilih oleh runtime harness Codex.
• CLI: openclaw onboard --auth-choice openai atau openclaw models auth login --provider openai
• Transport default adalah auto (WebSocket terlebih dahulu, fallback SSE)
• Override per model OpenAI Codex melalui agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket", atau "auto")
• params.serviceTier juga diteruskan pada permintaan Responses Codex native (chatgpt.com/backend-api)
• Header atribusi OpenClaw tersembunyi (originator, version, User-Agent) hanya dilampirkan pada traffic Codex native ke chatgpt.com/backend-api, bukan proxy generik yang kompatibel dengan OpenAI
• Berbagi toggle /fast dan konfigurasi params.fastMode yang sama seperti openai/* langsung; OpenClaw memetakannya ke service_tier=priority
• openai/gpt-5.5 menggunakan contextWindow = 400000 native katalog Codex dan runtime default contextTokens = 272000; override batas runtime dengan models.providers.openai.models[].contextTokens
• Catatan kebijakan: OAuth OpenAI Codex didukung secara eksplisit untuk alat/workflow eksternal seperti OpenClaw.
• Untuk rute umum langganan plus runtime Codex native, masuk dengan auth openai dan konfigurasikan openai/gpt-5.5; giliran agen OpenAI memilih Codex secara default.
• Gunakan provider/model agentRuntime.id: "openclaw" hanya ketika Anda menginginkan rute bawaan OpenClaw; jika tidak, pertahankan openai/gpt-5.5 pada harness Codex default.
• referensi GPT Codex legacy adalah status legacy, bukan rute penyedia live. Gunakan openai/gpt-5.5 pada runtime Codex native untuk konfigurasi agen baru, dan jalankan openclaw doctor --fix untuk memigrasikan referensi model Codex legacy lama ke referensi kanonis openai/*.

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

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

Opsi hosted bergaya langganan lainnya

OpenCode

• Auth: OPENCODE_API_KEY (atau OPENCODE_ZEN_API_KEY)
• Penyedia runtime Zen: opencode
• Penyedia runtime Go: opencode-go
• Contoh model: opencode/claude-opus-4-6, opencode-go/kimi-k2.6
• CLI: openclaw onboard --auth-choice opencode-zen atau openclaw onboard --auth-choice opencode-go

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

Google Gemini (kunci API)

• Penyedia: google
• Autentikasi: GEMINI_API_KEY
• Rotasi opsional: GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, fallback GOOGLE_API_KEY, dan OPENCLAW_LIVE_GEMINI_KEY (override tunggal)
• Contoh model: google/gemini-3.1-pro-preview, google/gemini-3-flash-preview
• Kompatibilitas: konfigurasi OpenClaw lama yang menggunakan google/gemini-3.1-flash-preview dinormalisasi menjadi google/gemini-3-flash-preview
• Alias: google/gemini-3.1-pro diterima dan dinormalisasi menjadi id Gemini API live milik Google, google/gemini-3.1-pro-preview
• CLI: openclaw onboard --auth-choice gemini-api-key
• Thinking: /think adaptive menggunakan dynamic thinking Google. Gemini 3/3.1 menghilangkan thinkingLevel tetap; Gemini 2.5 mengirim thinkingBudget: -1.
• Jalankan Gemini langsung juga menerima agents.defaults.models["google/<model>"].params.cachedContent (atau cached_content lama) untuk meneruskan handle native penyedia cachedContents/...; hit cache Gemini muncul sebagai cacheRead OpenClaw

Google Vertex dan Gemini CLI

• Penyedia: google-vertex, google-gemini-cli
• Autentikasi: Vertex menggunakan gcloud ADC; Gemini CLI menggunakan alur OAuth-nya

OAuth Gemini CLI dikirim sebagai bagian dari Plugin google bawaan.

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 menggunakan stream-json secara default. OpenClaw membaca pesan stream asisten dan menormalkan stats.cached menjadi cacheRead; override lama --output-format json tetap membaca teks balasan dari response.

Z.AI (GLM)

• Penyedia: zai
• Autentikasi: ZAI_API_KEY
• Contoh model: zai/glm-5.2
• CLI: openclaw onboard --auth-choice zai-api-key
  • Ref model menggunakan ID penyedia zai/* kanonis.
  • zai-api-key mendeteksi otomatis endpoint Z.AI yang cocok; zai-coding-global, zai-coding-cn, zai-global, dan zai-cn memaksa permukaan tertentu

Vercel AI Gateway

• Penyedia: vercel-ai-gateway
• Autentikasi: AI_GATEWAY_API_KEY
• Contoh model: 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 penyedia bawaan lainnya

Keunikan yang perlu diketahui

Penyedia melalui models.providers (URL kustom/dasar)

Gunakan models.providers (atau models.json) untuk menambahkan penyedia kustom atau proxy yang kompatibel dengan OpenAI/Anthropic.

Banyak Plugin penyedia bawaan di bawah ini sudah menerbitkan katalog default. Gunakan entri models.providers.<id> eksplisit hanya saat Anda ingin menimpa URL dasar, header, atau daftar model default.

Pemeriksaan kapabilitas model Gateway juga membaca metadata models.providers.<id>.models[] eksplisit. Jika model kustom atau proksi menerima gambar, tetapkan input: ["text", "image"] pada model tersebut agar jalur lampiran WebChat dan asal node meneruskan gambar sebagai input model native, bukan sebagai referensi media teks-saja.

agents.defaults.models["provider/model"] hanya mengontrol visibilitas model, alias, dan metadata per model untuk agen. Itu tidak mendaftarkan model runtime baru dengan sendirinya. Untuk model penyedia kustom, tambahkan juga models.providers.<provider>.models[] dengan setidaknya id yang cocok.

Moonshot AI (Kimi)

Instal @openclaw/moonshot-provider sebelum onboarding. Tambahkan entri models.providers.moonshot eksplisit hanya saat Anda perlu menimpa URL dasar atau metadata model:

• Penyedia: moonshot
• Autentikasi: MOONSHOT_API_KEY
• Contoh model: moonshot/kimi-k2.6
• CLI: openclaw onboard --auth-choice moonshot-api-key atau openclaw onboard --auth-choice moonshot-api-key-cn

ID model Kimi K2:

• 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" }],      },    },  },}

Pengodean Kimi

Kimi Coding menggunakan endpoint Moonshot AI yang kompatibel dengan Anthropic:

• Penyedia: kimi
• Autentikasi: KIMI_API_KEY
• Contoh model: kimi/kimi-for-coding

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

kimi/kimi-code dan kimi/k2p5 lama tetap diterima sebagai ID model kompatibilitas dan dinormalisasi ke ID model API stabil Kimi.

Volcano Engine (Doubao)

Volcano Engine (火山引擎) menyediakan akses ke Doubao dan model lain di Tiongkok.

• Penyedia: volcengine (pengodean: volcengine-plan)
• Autentikasi: VOLCANO_ENGINE_API_KEY
• Contoh model: volcengine-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice volcengine-api-key

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

Onboarding secara default menggunakan permukaan pengodean, tetapi katalog umum volcengine/* didaftarkan pada saat yang sama.

Di pemilih model onboarding/konfigurasi, pilihan autentikasi Volcengine memprioritaskan baris volcengine/* dan volcengine-plan/*. Jika model-model tersebut belum dimuat, OpenClaw beralih ke katalog tanpa filter alih-alih menampilkan pemilih kosong yang dibatasi penyedia.

BytePlus (Internasional)

BytePlus ARK menyediakan akses ke model yang sama seperti Volcano Engine untuk pengguna internasional.

• Penyedia: byteplus (pengodean: byteplus-plan)
• Autentikasi: BYTEPLUS_API_KEY
• Contoh model: byteplus-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice byteplus-api-key

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

Onboarding secara default menggunakan permukaan pengodean, tetapi katalog umum byteplus/* didaftarkan pada saat yang sama.

Di pemilih model onboarding/konfigurasi, pilihan autentikasi BytePlus memprioritaskan baris byteplus/* dan byteplus-plan/*. Jika model-model tersebut belum dimuat, OpenClaw beralih ke katalog tanpa filter alih-alih menampilkan pemilih kosong yang dibatasi penyedia.

Synthetic

Synthetic menyediakan model yang kompatibel dengan Anthropic di balik penyedia synthetic:

• Penyedia: synthetic
• Autentikasi: SYNTHETIC_API_KEY
• Contoh model: 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 dikonfigurasi melalui models.providers karena menggunakan endpoint kustom:

• MiniMax OAuth (Global): --auth-choice minimax-global-oauth
• MiniMax OAuth (CN): --auth-choice minimax-cn-oauth
• Kunci API MiniMax (Global): --auth-choice minimax-global-api
• Kunci API MiniMax (CN): --auth-choice minimax-cn-api
• Autentikasi: MINIMAX_API_KEY untuk minimax; MINIMAX_OAUTH_TOKEN atau MINIMAX_API_KEY untuk minimax-portal

Lihat /providers/minimax untuk detail penyiapan, opsi model, dan cuplikan konfigurasi.

Pembagian kapabilitas milik Plugin:

• Default teks/chat tetap menggunakan minimax/MiniMax-M3
• Pembuatan gambar adalah minimax/image-01 atau minimax-portal/image-01
• Pemahaman gambar adalah MiniMax-VL-01 milik Plugin pada kedua jalur autentikasi MiniMax
• Pencarian web tetap menggunakan id penyedia minimax

LM Studio

LM Studio dikirim sebagai Plugin penyedia bawaan yang menggunakan API native:

• Penyedia: lmstudio
• Autentikasi: LM_API_TOKEN
• URL dasar inferensi default: http://localhost:1234/v1

Lalu atur model (ganti dengan salah satu ID yang dikembalikan oleh http://localhost:1234/api/v1/models):

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

OpenClaw menggunakan /api/v1/models dan /api/v1/models/load native milik LM Studio untuk penemuan + pemuatan otomatis, dengan /v1/chat/completions untuk inferensi secara default. Jika Anda ingin pemuatan JIT, TTL, dan pengeluaran otomatis LM Studio mengelola siklus hidup model, atur models.providers.lmstudio.params.preload: false. Lihat /providers/lmstudio untuk penyiapan dan pemecahan masalah.

Ollama

Ollama dikirim sebagai Plugin penyedia bawaan dan menggunakan API native Ollama:

• Penyedia: ollama
• Autentikasi: Tidak diperlukan (server lokal)
• Contoh model: ollama/llama3.3
• Instalasi: https://ollama.com/download

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

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

Ollama dideteksi secara lokal di http://127.0.0.1:11434 saat Anda ikut serta dengan OLLAMA_API_KEY, dan Plugin penyedia bawaan menambahkan Ollama langsung ke openclaw onboard dan pemilih model. Lihat /providers/ollama untuk onboarding, mode cloud/lokal, dan konfigurasi kustom.

vLLM

vLLM dikirim sebagai Plugin penyedia bawaan untuk server lokal/hosting sendiri yang kompatibel dengan OpenAI:

• Penyedia: vllm
• Autentikasi: Opsional (bergantung pada server Anda)
• URL dasar default: http://127.0.0.1:8000/v1

Untuk ikut serta dalam penemuan otomatis secara lokal (nilai apa pun berfungsi jika server Anda tidak memberlakukan autentikasi):

export VLLM_API_KEY="vllm-local"

Lalu atur model (ganti dengan salah satu ID yang dikembalikan oleh /v1/models):

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

Lihat /providers/vllm untuk detail.

SGLang

SGLang dikirim sebagai Plugin penyedia bawaan untuk server hosting sendiri yang cepat dan kompatibel dengan OpenAI:

• Penyedia: sglang
• Autentikasi: Opsional (bergantung pada server Anda)
• URL dasar default: http://127.0.0.1:30000/v1

Untuk ikut serta dalam penemuan otomatis secara lokal (nilai apa pun berfungsi jika server Anda tidak memberlakukan autentikasi):

export SGLANG_API_KEY="sglang-local"

Lalu atur model (ganti dengan salah satu ID yang dikembalikan oleh /v1/models):

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

Lihat /providers/sglang untuk detail.

Proksi lokal (LM Studio, vLLM, LiteLLM, dll.)

Contoh (kompatibel dengan 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,          },        ],      },    },  },}

Contoh CLI

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

Lihat juga: Konfigurasi untuk contoh konfigurasi lengkap.

Terkait

• Referensi konfigurasi - kunci konfigurasi model
• Failover model - rantai fallback dan perilaku percobaan ulang
• Model - konfigurasi model dan alias
• Penyedia - panduan penyiapan per penyedia