Penyedia model

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

Aturan cepat

Perilaku penyedia milik Plugin

Sebagian besar logika spesifik penyedia berada di Plugin penyedia (registerProvider(...)) sementara OpenClaw mempertahankan loop inferensi generik. Plugin memiliki onboarding, katalog model, pemetaan env-var auth, normalisasi transport/config, pembersihan tool-schema, klasifikasi failover, refresh OAuth, pelaporan penggunaan, profil thinking/reasoning, dan lainnya.

Daftar lengkap hook SDK penyedia dan contoh Plugin bawaan tersedia di Plugin penyedia. Penyedia yang membutuhkan eksekutor permintaan yang sepenuhnya kustom adalah permukaan ekstensi terpisah yang lebih dalam.

Rotasi API key

Penyedia bawaan (katalog pi-ai)

OpenClaw dikirimkan dengan katalog pi-ai. Penyedia ini tidak memerlukan config models.providers; cukup setel auth + pilih model.

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 API key tertentu berperilaku berbeda.
• CLI: openclaw onboard --auth-choice openai-api-key
• Transport default adalah auto; OpenClaw meneruskan pilihan transport ke pi-ai.
• 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 langsung openai/* ke service_tier=priority pada api.openai.com
• Gunakan params.serviceTier saat 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 kompatibel OpenAI generik
• Rute OpenAI native juga mempertahankan store Responses, petunjuk prompt-cache, dan pembentukan payload kompatibilitas reasoning OpenAI; rute proxy tidak
• openai/gpt-5.3-codex-spark sengaja disembunyikan di OpenClaw karena permintaan API OpenAI live menolaknya dan katalog Codex saat ini tidak mengeksposnya

{  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 yang diautentikasi dengan API key dan OAuth yang dikirim ke api.anthropic.com; OpenClaw memetakannya ke service_tier Anthropic (auto vs standard_only)
• Config Claude CLI pilihan mempertahankan referensi model tetap kanonis dan memilih backend CLI secara terpisah: anthropic/claude-opus-4-7 dengan agentRuntime.id: "claude-cli" yang diskopkan ke model. Referensi legacy claude-cli/claude-opus-4-7 masih berfungsi untuk kompatibilitas.

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

OAuth OpenAI Codex

• Penyedia: openai-codex
• Auth: OAuth (ChatGPT)
• Referensi model PI legacy: openai-codex/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-codex/* memuat Plugin OpenAI; Plugin app-server Codex native dipilih hanya oleh runtime harness Codex atau referensi legacy codex/*.
• CLI: openclaw onboard --auth-choice openai-codex atau openclaw models auth login --provider openai-codex
• Transport default adalah auto (WebSocket terlebih dahulu, fallback SSE)
• Override per model PI melalui agents.defaults.models["openai-codex/<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 kompatibel OpenAI generik
• Berbagi config toggle /fast dan params.fastMode yang sama seperti openai/* langsung; OpenClaw memetakannya ke service_tier=priority
• openai-codex/gpt-5.5 menggunakan contextWindow = 400000 native katalog Codex dan runtime default contextTokens = 272000; override batas runtime dengan models.providers.openai-codex.models[].contextTokens
• Catatan kebijakan: OAuth OpenAI Codex secara eksplisit didukung untuk alat/workflow eksternal seperti OpenClaw.
• Untuk rute umum langganan plus runtime Codex native, masuk dengan auth openai-codex tetapi konfigurasikan openai/gpt-5.5; giliran agen OpenAI memilih Codex secara default.
• Gunakan penyedia/model agentRuntime.id: "pi" hanya saat Anda menginginkan rute kompatibilitas melalui PI; jika tidak, pertahankan openai/gpt-5.5 pada harness Codex default.
• Referensi openai-codex/gpt-5.1*, openai-codex/gpt-5.2*, dan openai-codex/gpt-5.3* yang lebih lama disembunyikan karena akun OAuth ChatGPT/Codex menolaknya; gunakan openai-codex/gpt-5.5 atau rute runtime Codex native sebagai gantinya.

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

{  models: {    providers: {      "openai-codex": {        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 (API key)

• Penyedia: google
• Autentikasi: GEMINI_API_KEY
• Rotasi opsional: fallback GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, GOOGLE_API_KEY, dan OPENCLAW_LIVE_GEMINI_KEY (penimpaan tunggal)
• Model contoh: google/gemini-3.1-pro-preview, google/gemini-3-flash-preview
• Kompatibilitas: konfigurasi lama OpenClaw yang menggunakan google/gemini-3.1-flash-preview dinormalisasi menjadi google/gemini-3-flash-preview
• Alias: google/gemini-3.1-pro diterima dan dinormalisasi ke id Gemini API live milik Google, google/gemini-3.1-pro-preview
• CLI: openclaw onboard --auth-choice gemini-api-key
• Penalaran: /think adaptive menggunakan penalaran dinamis Google. Gemini 3/3.1 menghilangkan thinkingLevel tetap; Gemini 2.5 mengirim thinkingBudget: -1.
• Eksekusi 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 OpenClaw cacheRead

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

Balasan JSON Gemini CLI diurai dari response; penggunaan fallback ke stats, dengan stats.cached dinormalisasi menjadi OpenClaw cacheRead.

Z.AI (GLM)

• Penyedia: zai
• Autentikasi: ZAI_API_KEY
• Model contoh: zai/glm-5.1
• CLI: openclaw onboard --auth-choice zai-api-key
  • Alias: z.ai/* dan z-ai/* dinormalisasi menjadi zai/*
  • zai-api-key otomatis mendeteksi endpoint Z.AI yang sesuai; 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
• Model contoh: 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

• Penyedia: kilocode
• Autentikasi: KILOCODE_API_KEY
• Model contoh: kilocode/kilo/auto
• CLI: openclaw onboard --auth-choice kilocode-api-key
• URL dasar: https://api.kilo.ai/api/gateway/
• Katalog fallback statis mengirim kilocode/kilo/auto; penemuan live https://api.kilo.ai/api/gateway/models dapat memperluas katalog runtime lebih lanjut.
• Perutean upstream persis di balik kilocode/kilo/auto dimiliki oleh Kilo Gateway, bukan di-hard-code di OpenClaw.

Lihat /providers/kilocode untuk detail penyiapan.

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 proksi yang kompatibel dengan OpenAI/Anthropic.

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

Pemeriksaan kapabilitas model Gateway juga membaca metadata eksplisit models.providers.<id>.models[]. 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 referensi media yang hanya teks.

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)

Moonshot dikirim sebagai plugin penyedia yang dibundel. Gunakan penyedia bawaan secara default, dan tambahkan entri models.providers.moonshot eksplisit hanya saat Anda perlu mengganti 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.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 kompatibel Anthropic milik Moonshot AI:

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

Legacy kimi/kimi-code dan kimi/k2p5 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 tersebut belum dimuat, OpenClaw kembali ke katalog tanpa filter alih-alih menampilkan pemilih kosong yang dibatasi per 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 tersebut belum dimuat, OpenClaw kembali ke katalog tanpa filter alih-alih menampilkan pemilih kosong yang dibatasi per penyedia.

Synthetic

Synthetic menyediakan model kompatibel 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 khusus:

• 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.

Pemisahan kapabilitas milik Plugin:

• Default teks/chat tetap di minimax/MiniMax-M2.7
• 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 pada 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 tetapkan 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 LM Studio untuk penemuan + pemuatan otomatis, dengan /v1/chat/completions untuk inferensi secara default. Jika Anda ingin pemuatan JIT, TTL, dan pengosongan otomatis LM Studio memiliki siklus hidup model, tetapkan 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 ketika 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 khusus.

vLLM

vLLM dikirim sebagai Plugin penyedia bawaan untuk server lokal/self-hosted yang kompatibel OpenAI:

• Penyedia: vllm
• Autentikasi: Opsional (tergantung 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 menerapkan autentikasi):

export VLLM_API_KEY="vllm-local"

Lalu tetapkan 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 self-hosted cepat yang kompatibel OpenAI:

• Penyedia: sglang
• Autentikasi: Opsional (tergantung 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 menerapkan autentikasi):

export SGLANG_API_KEY="sglang-local"

Lalu tetapkan 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 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