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 spesifik penyedia berada di Plugin penyedia (registerProvider(...)) sementara OpenClaw mempertahankan loop inferensi generik. Plugin memiliki onboarding, katalog model, pemetaan env-var autentikasi, normalisasi transport/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 membutuhkan eksekutor permintaan yang sepenuhnya kustom adalah permukaan ekstensi yang terpisah dan lebih dalam.

# Rotasi kunci API

# Penyedia bawaan (katalog pi-ai)

OpenClaw disertakan dengan katalog pi-ai. Penyedia ini tidak memerlukan konfigurasi models.providers; cukup atur autentikasi + pilih model.

# 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 (penggantian 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 (WebSocket lebih dulu, fallback SSE)
• Timpa per model melalui agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket", atau "auto")
• Pemanasan WebSocket OpenAI Responses secara default diaktifkan melalui params.openaiWsWarmup (true/false)
• 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, bukan toggle /fast bersama
• Header atribusi OpenClaw tersembunyi (originator, version, User-Agent) hanya berlaku pada lalu lintas 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 sengaja ditekan di OpenClaw karena permintaan API OpenAI langsung menolaknya dan katalog Codex saat ini tidak mengeksposnya

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

# 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 (penggantian 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 lalu lintas yang diautentikasi dengan kunci API dan OAuth yang dikirim ke api.anthropic.com; OpenClaw memetakannya ke service_tier Anthropic (auto vs standard_only)
• Konfigurasi Claude CLI yang disarankan mempertahankan ref model kanonis dan memilih backend CLI secara terpisah: anthropic/claude-opus-4-7 dengan agents.defaults.agentRuntime.id: "claude-cli". Ref lama claude-cli/claude-opus-4-7 tetap berfungsi untuk kompatibilitas.

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

# OpenAI Codex OAuth

• Penyedia: openai-codex
• Autentikasi: OAuth (ChatGPT)
• Ref model PI: openai-codex/gpt-5.5
• Ref harness server aplikasi Codex native: openai/gpt-5.5 dengan agents.defaults.agentRuntime.id: "codex"
• Dokumentasi harness server aplikasi Codex native: Harness Codex
• Ref model lama: codex/gpt-*
• Batas Plugin: openai-codex/* memuat Plugin OpenAI; Plugin server aplikasi Codex native hanya dipilih oleh runtime harness Codex atau ref lama codex/*.
• CLI: openclaw onboard --auth-choice openai-codex atau openclaw models auth login --provider openai-codex
• Transport default adalah auto (WebSocket lebih dulu, fallback SSE)
• Timpa per model PI melalui agents.defaults.models["openai-codex/<model>"].params.transport ("sse", "websocket", atau "auto")
• params.serviceTier juga diteruskan pada permintaan Codex Responses native (chatgpt.com/backend-api)
• Header atribusi OpenClaw tersembunyi (originator, version, User-Agent) hanya dilampirkan pada lalu lintas Codex native ke chatgpt.com/backend-api, bukan proxy generik yang kompatibel dengan OpenAI
• Berbagi toggle /fast dan konfigurasi params.fastMode yang sama dengan openai/* langsung; OpenClaw memetakannya ke service_tier=priority
• openai-codex/gpt-5.5 menggunakan contextWindow = 400000 native dari katalog Codex dan runtime default contextTokens = 272000; timpa batas runtime dengan models.providers.openai-codex.models[].contextTokens
• Catatan kebijakan: OpenAI Codex OAuth didukung secara eksplisit untuk alat/alur kerja eksternal seperti OpenClaw.
• Untuk rute langganan umum plus runtime Codex native, masuk dengan autentikasi openai-codex tetapi konfigurasikan openai/gpt-5.5 ditambah agents.defaults.agentRuntime.id: "codex".
• Gunakan openai-codex/gpt-5.5 hanya saat Anda menginginkan rute Codex OAuth/langganan melalui PI; gunakan openai/gpt-5.5 tanpa penggantian runtime Codex saat penyiapan kunci API dan katalog lokal Anda mengekspos rute API publik.
• Ref lama openai-codex/gpt-5.1*, openai-codex/gpt-5.2*, dan openai-codex/gpt-5.3* ditekan karena akun ChatGPT/Codex OAuth 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" },
      agentRuntime: { id: "codex" },
    },
  },
}

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

# Opsi hosted gaya langganan lainnya

# 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: fallback GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, GOOGLE_API_KEY, dan OPENCLAW_LIVE_GEMINI_KEY (override tunggal)
• Model contoh: 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 Google, google/gemini-3.1-pro-preview
• CLI: openclaw onboard --auth-choice gemini-api-key
• Berpikir: /think adaptive menggunakan dynamic thinking 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 cachedContents/... native penyedia; 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 diuraikan 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 mendeteksi otomatis endpoint Z.AI yang cocok; zai-coding-global, zai-coding-cn, zai-global, dan zai-cn memaksa surface 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 mengirimkan kilocode/kilo/auto; discovery live https://api.kilo.ai/api/gateway/models dapat memperluas katalog runtime lebih lanjut.
• Routing 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 khusus/dasar)

Gunakan models.providers (atau models.json) untuk menambahkan penyedia khusus 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 ketika Anda ingin menimpa URL dasar default, header, atau daftar model.

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

# Moonshot AI (Kimi)

Moonshot dikirim sebagai Plugin penyedia yang dibundel. Gunakan penyedia bawaan secara default, dan tambahkan entri models.providers.moonshot eksplisit hanya ketika 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.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 coding

Kimi Coding menggunakan endpoint Moonshot AI yang kompatibel dengan Anthropic:

• Penyedia: kimi
• Autentikasi: KIMI_API_KEY
• Contoh model: kimi/kimi-code

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

kimi/k2p5 lama tetap diterima sebagai id model kompatibilitas.

# Volcano Engine (Doubao)

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

• Penyedia: volcengine (coding: 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 coding, 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 penyedia.

# BytePlus (Internasional)

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

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

Pemisahan kapabilitas milik Plugin:

• Default teks/chat tetap pada 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 auto-evict LM Studio mengelola 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 terdeteksi 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 kustom.

# vLLM

vLLM dikirim sebagai Plugin penyedia bawaan untuk server lokal/self-hosted 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 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 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 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-zen
openclaw models set opencode/claude-opus-4-6
openclaw 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