Penyedia model

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

Aturan ringkas

Mengonfigurasi penyedia di UI Kontrol

Buka Settings → Model Providers di UI Kontrol untuk menambahkan, mengganti, atau menghapus kunci API penyedia yang disimpan di models.providers.<id>.apiKey. Halaman tersebut menunjukkan apakah setiap kunci API berasal dari konfigurasi OpenClaw atau variabel lingkungan tanpa menampilkan kredensialnya. Kunci yang disediakan lingkungan tetap dikelola oleh lingkungan proses Gateway.

Gunakan Test connection untuk menjalankan probe penyedia langsung dan melihat latensi atau kesalahan autentikasi, batas laju, penagihan, batas waktu, atau respons yang telah dikategorikan. Probe membuat permintaan nyata kepada penyedia dan dapat menggunakan sejumlah kecil token. Profil OAuth dan token juga dapat dikeluarkan melalui kartu penyedia.

Kartu Default models mengelola model utama, fallback berurutan, dan model utilitas dari katalog model yang dikonfigurasi. Pilih model, lalu simpan semuanya bersama-sama ke pengaturan agents.defaults.model dan agents.defaults.utilityModel yang sudah ada. Untuk model utilitas, Automatic membiarkan pengaturan tidak ditetapkan dan Disabled menyimpan string kosong untuk menonaktifkan perutean utilitas.

Perilaku penyedia milik Plugin

Sebagian besar logika khusus penyedia berada di Plugin penyedia (registerProvider(...)), sementara OpenClaw mempertahankan loop inferensi generik. Plugin menangani orientasi awal, katalog model, pemetaan variabel lingkungan autentikasi, normalisasi transportasi/konfigurasi, pembersihan skema alat, klasifikasi failover, penyegaran OAuth, pelaporan penggunaan, profil pemikiran/penalaran, dan lainnya.

Daftar lengkap hook SDK penyedia dan contoh Plugin bawaan tersedia di Plugin penyedia. Penyedia yang memerlukan eksekutor permintaan yang sepenuhnya khusus merupakan permukaan ekstensi terpisah yang lebih mendalam.

Rotasi kunci API

Plugin penyedia resmi

Plugin penyedia resmi menerbitkan baris katalog modelnya sendiri. Penyedia ini tidak memerlukan entri model models.providers; aktifkan Plugin penyedia, tetapkan autentikasi, dan pilih model. Gunakan models.providers hanya untuk penyedia khusus eksplisit atau pengaturan permintaan terbatas seperti batas waktu.

OpenAI

• Penyedia: openai
• Autentikasi: OPENAI_API_KEY
• Rotasi opsional: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, ditambah OPENCLAW_LIVE_OPENAI_KEY (satu penggantian)
• Default penyiapan baru: openai/gpt-5.6; pada API langsung, ID tanpa tambahan ditetapkan ke Sol.
• Contoh model: openai/gpt-5.6, openai/gpt-5.6-terra, openai/gpt-5.6-luna, openai/gpt-5.5
• 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
• Transportasi default adalah auto; OpenClaw meneruskan pilihan transportasi ke runtime model bersama.
• Ganti 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 saat Anda menginginkan tingkat eksplisit alih-alih pengalih bersama /fast
• Header atribusi OpenClaw tersembunyi (originator, version, User-Agent) hanya berlaku pada lalu lintas asli OpenAI ke api.openai.com, bukan proksi generik yang kompatibel dengan OpenAI
• Rute asli OpenAI juga mempertahankan store Responses, petunjuk cache prompt, dan pembentukan payload kompatibilitas penalaran OpenAI; rute proksi tidak
• openai/gpt-5.3-codex-spark hanya tersedia melalui OAuth ChatGPT/Codex; rute kunci API OpenAI langsung dan kunci API Azure menolaknya

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

Jika organisasi API tidak menyediakan GPT-5.6, tetapkan openai/gpt-5.5 secara eksplisit. Orientasi awal dan autentikasi ulang normal mempertahankan model utama eksplisit yang sudah ada; models auth login --set-default dan models set adalah jalur penggantian yang disengaja.

Anthropic

• Penyedia: anthropic
• Autentikasi: ANTHROPIC_API_KEY
• Rotasi opsional: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, ditambah OPENCLAW_LIVE_ANTHROPIC_KEY (satu penggantian)
• Contoh model: anthropic/claude-opus-4-6
• CLI: openclaw onboard --auth-choice apiKey
• Permintaan publik langsung Anthropic mendukung pengalih bersama /fast dan params.fastMode, termasuk lalu lintas yang diautentikasi dengan kunci API dan OAuth yang dikirim ke api.anthropic.com; OpenClaw memetakannya ke service_tier Anthropic (auto dibandingkan dengan standard_only)
• Konfigurasi Claude CLI yang diutamakan menjaga referensi model tetap kanonis dan memilih backend CLI secara terpisah: anthropic/claude-opus-4-8 dengan agentRuntime.id: "claude-cli" bercakupan model. Referensi claude-cli/claude-opus-4-7 lama masih berfungsi untuk kompatibilitas.

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

OAuth OpenAI ChatGPT/Codex

• Penyedia: openai
• Autentikasi: OAuth (ChatGPT)
• Referensi harness app-server Codex native baru: openai/gpt-5.6-sol
• Dokumentasi harness app-server Codex native: Harness Codex
• Referensi model lama: codex/gpt-*, openai-codex/gpt-*
• Batas Plugin: openai/* memuat Plugin OpenAI; kebijakan runtime eksplisit atau rute efektif milik penyedia menentukan apakah Plugin app-server Codex native dipilih.
• CLI: openclaw onboard --auth-choice openai atau openclaw models auth login --provider openai
• Transport ChatGPT Responses tertanam OpenClaw secara default menggunakan auto (WebSocket terlebih dahulu, SSE sebagai fallback).
• agents.defaults.models["openai/<model>"].params.transport, params.serviceTier, dan params.fastMode adalah pengaturan permintaan tertanam yang ditentukan. Pengaturan tersebut mempertahankan pemilihan runtime implisit pada OpenClaw; Codex native memiliki transport app-server dan tingkat layanannya sendiri.
• Header atribusi OpenClaw tersembunyi (originator, version, User-Agent) hanya disertakan pada lalu lintas Codex native ke chatgpt.com/backend-api, bukan pada proksi generik yang kompatibel dengan OpenAI
• Toggle /fast bersama tetap tersedia sebagai kontrol runtime; toggle ini berbeda dari parameter model yang ditentukan.
• Katalog Codex native dapat menampilkan referensi persis openai/gpt-5.6-sol, openai/gpt-5.6-terra, dan openai/gpt-5.6-luna sesuai dengan akses akun. Katalog tersebut tidak menerapkan alias polos gpt-5.6 milik API langsung pada sisi klien.
• openai/gpt-5.5 menggunakan contextWindow = 400000 native dari katalog Codex dan runtime default contextTokens = 272000; ganti batas runtime dengan models.providers.openai.models[].contextTokens
• Masuk dengan autentikasi openai dan gunakan openai/gpt-5.6-sol untuk penyiapan baru yang didukung langganan. Pilih openai/gpt-5.5 secara eksplisit jika ruang kerja Codex tersebut tidak menyediakan GPT-5.6.
• Gunakan penyedia/model agentRuntime.id: "openclaw" untuk mempertahankan rute yang sebenarnya memenuhi syarat pada runtime bawaan. Jika runtime tidak ditetapkan atau menggunakan auto, hanya rute HTTPS Responses/ChatGPT resmi yang persis dan tanpa penggantian permintaan yang ditentukan yang dapat memilih Codex secara implisit.
• Referensi GPT Codex lama adalah status lama, bukan rute penyedia aktif. Gunakan referensi kanonis openai/* untuk konfigurasi agen baru, dan jalankan openclaw doctor --fix untuk memigrasikan referensi codex/* dan openai-codex/* sekaligus mempertahankan semantik Codex native-nya dengan agentRuntime.id: "codex" yang tercakup pada model. Pilihan kanonis eksplisit openai/gpt-5.5 yang sudah ada tidak ditingkatkan.

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

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

Opsi terhost lain bergaya langganan

OpenCode

• Autentikasi: 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 (penggantian tunggal)
• Contoh model: google/gemini-3.1-pro-preview, google/gemini-3.5-flash
• 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 API Gemini aktif milik Google, google/gemini-3.1-pro-preview
• CLI: openclaw onboard --auth-choice gemini-api-key
• Pemikiran: /think adaptive menggunakan pemikiran dinamis Google. Gemini 3/3.1 tidak menyertakan thinkingLevel tetap; Gemini 2.5 mengirim thinkingBudget: -1.
• Proses Gemini langsung juga menerima agents.defaults.models["google/<model>"].params.cachedContent (atau cached_content lama) untuk meneruskan handle cachedContents/... native penyedia; cache hit Gemini ditampilkan 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 disertakan sebagai bagian dari Plugin google yang dibundel.

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 menormalisasi stats.cached menjadi cacheRead; penggantian --output-format json lama 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
  • Referensi model menggunakan ID penyedia kanonis zai/*.
  • zai-api-key mendeteksi otomatis titik akhir Z.AI yang sesuai; zai-coding-global, zai-coding-cn, zai-global, dan zai-cn memaksakan 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 lain yang dibundel

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 bawaan di bawah ini sudah menerbitkan katalog default. Gunakan entri models.providers.<id> eksplisit hanya jika Anda ingin mengganti URL dasar, header, atau daftar model default.

Pemeriksaan kemampuan 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 yang berasal dari WebChat dan node meneruskan gambar sebagai input model native, bukan sebagai referensi media khusus teks.

agents.defaults.models["provider/model"] mengontrol alias dan metadata per model untuk agen. Ini tidak membatasi penggantian maupun mendaftarkan model runtime baru dengan sendirinya. Untuk model penyedia kustom, tambahkan juga models.providers.<provider>.models[] dengan setidaknya id yang cocok; gunakan agents.defaults.modelPolicy.allow secara terpisah jika Anda ingin membatasi penggantian.

Moonshot AI (Kimi)

Instal @openclaw/moonshot-provider sebelum orientasi. Tambahkan entri models.providers.moonshot eksplisit hanya jika Anda perlu mengganti URL dasar atau metadata model:

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

ID model Kimi:

• moonshot/kimi-k2.6
• moonshot/kimi-k3
• moonshot/kimi-k2.7-code
• moonshot/kimi-k2.7-code-highspeed
• moonshot/kimi-k2.5

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

Lihat Moonshot AI (Kimi + Kimi Coding) untuk panduan penyiapan lengkap.

Kimi Coding

Kimi Coding menggunakan endpoint kompatibel Anthropic milik Moonshot AI:

• Penyedia: kimi
• Autentikasi: KIMI_API_KEY
• Kimi K3: kimi/k3 (256K) atau kimi/k3[1m] (paket 1M)
• Kimi Code: kimi/kimi-for-coding
• Kimi Code HighSpeed: kimi/kimi-for-coding-highspeed

{  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 lainnya di Tiongkok.

• Penyedia: volcengine (pemrograman: 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" } },  },}

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

Dalam pemilih model orientasi/konfigurasi, pilihan autentikasi Volcengine mengutamakan baris volcengine/* dan volcengine-plan/*. Jika model tersebut belum dimuat, OpenClaw beralih ke katalog tanpa filter sebagai fallback alih-alih menampilkan pemilih dengan cakupan penyedia yang kosong.

BytePlus (Internasional)

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

• Penyedia: byteplus (pemrograman: 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.

Dalam 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 dengan cakupan penyedia yang kosong.

Synthetic

Synthetic menyediakan model yang kompatibel dengan Anthropic melalui penyedia synthetic:

• Penyedia: synthetic
• Autentikasi: SYNTHETIC_API_KEY
• Contoh model: synthetic/hf:MiniMaxAI/MiniMax-M3
• CLI: openclaw onboard --auth-choice synthetic-api-key

{  agents: {    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M3" } },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [{ id: "hf:MiniMaxAI/MiniMax-M3", name: "MiniMax M3" }],      },    },  },}

MiniMax

MiniMax dikonfigurasi melalui models.providers karena menggunakan endpoint khusus:

• OAuth MiniMax (Global): --auth-choice minimax-global-oauth
• OAuth MiniMax (Tiongkok): --auth-choice minimax-cn-oauth
• Kunci API MiniMax (Global): --auth-choice minimax-global-api
• Kunci API MiniMax (Tiongkok): --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 kemampuan milik Plugin:

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

LM Studio

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

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

Kemudian 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 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, tetapkan models.providers.lmstudio.params.preload: false. Lihat /providers/lmstudio untuk penyiapan dan pemecahan masalah.

Ollama

Ollama disertakan 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

# Instal Ollama, lalu tarik sebuah 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 serta pemilih model. Lihat /providers/ollama untuk onboarding, mode cloud/lokal, dan konfigurasi khusus.

vLLM

vLLM disertakan sebagai Plugin penyedia bawaan untuk server lokal/dihosting 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 dapat digunakan jika server Anda tidak mewajibkan autentikasi):

export VLLM_API_KEY="vllm-local"

Kemudian 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 disertakan sebagai Plugin penyedia bawaan untuk server cepat yang dihosting sendiri 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 dapat digunakan jika server Anda tidak mewajibkan autentikasi):

export SGLANG_API_KEY="sglang-local"

Kemudian 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 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 dan alias model
• Penyedia - panduan penyiapan per penyedia