Model lokal

Model lokal dapat digunakan. Model lokal juga menaikkan tuntutan pada perangkat keras, ukuran konteks, dan pertahanan prompt-injection — kartu kecil atau yang dikuantisasi secara agresif memangkas konteks dan membocorkan keamanan. Halaman ini adalah panduan beropini untuk stack lokal kelas atas dan server lokal kustom yang kompatibel dengan OpenAI. Untuk onboarding dengan hambatan paling rendah, mulai dengan LM Studio atau Ollama dan openclaw onboard.

Untuk server lokal yang hanya boleh dimulai saat model terpilih membutuhkannya, lihat Layanan model lokal.

Batas minimum perangkat keras

Targetkan tinggi: ≥2 Mac Studio spek maksimal atau rig GPU setara (~$30k+) untuk loop agen yang nyaman. Satu GPU 24 GB hanya cocok untuk prompt yang lebih ringan dengan latensi lebih tinggi. Selalu jalankan varian terbesar / ukuran penuh yang dapat Anda host; checkpoint kecil atau yang dikuantisasi berat meningkatkan risiko prompt-injection (lihat Keamanan).

Pilih backend

Gunakan Responses API (api: "openai-responses") saat backend mendukungnya (LM Studio mendukungnya). Jika tidak, tetap gunakan Chat Completions (api: "openai-completions").

Direkomendasikan: LM Studio + model lokal besar (Responses API)

Stack lokal terbaik saat ini. Muat model besar di LM Studio (misalnya build Qwen, DeepSeek, atau Llama ukuran penuh), aktifkan server lokal (default http://127.0.0.1:1234), dan gunakan Responses API untuk menjaga penalaran tetap terpisah dari teks final.

{  agents: {    defaults: {      model: { primary: "lmstudio/my-local-model" },      models: {        "anthropic/claude-opus-4-6": { alias: "Opus" },        "lmstudio/my-local-model": { alias: "Local" },      },    },  },  models: {    mode: "merge",    providers: {      lmstudio: {        baseUrl: "http://127.0.0.1:1234/v1",        apiKey: "lmstudio",        api: "openai-responses",        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,          },        ],      },    },  },}

Checklist penyiapan

• Instal LM Studio: https://lmstudio.ai
• Di LM Studio, unduh build model terbesar yang tersedia (hindari varian "small"/yang dikuantisasi berat), mulai server, pastikan http://127.0.0.1:1234/v1/models mencantumkannya.
• Ganti my-local-model dengan ID model aktual yang ditampilkan di LM Studio.
• Biarkan model tetap dimuat; cold-load menambah latensi startup.
• Sesuaikan contextWindow/maxTokens jika build LM Studio Anda berbeda.
• Untuk WhatsApp, tetap gunakan Responses API agar hanya teks final yang dikirim.

Biarkan model hosted tetap dikonfigurasi meskipun menjalankan lokal; gunakan models.mode: "merge" agar fallback tetap tersedia.

Konfigurasi hibrida: primary hosted, fallback lokal

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "lmstudio/my-local-model": { alias: "Local" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },  models: {    mode: "merge",    providers: {      lmstudio: {        baseUrl: "http://127.0.0.1:1234/v1",        apiKey: "lmstudio",        api: "openai-responses",        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,          },        ],      },    },  },}

Local-first dengan jaring pengaman hosted

Tukar urutan primary dan fallback; pertahankan blok providers yang sama dan models.mode: "merge" agar Anda dapat fallback ke Sonnet atau Opus saat mesin lokal tidak aktif.

Hosting regional / routing data

• Varian hosted MiniMax/Kimi/GLM juga tersedia di OpenRouter dengan endpoint yang dipatok ke region (misalnya, di-host di AS). Pilih varian regional di sana untuk menjaga trafik tetap dalam yurisdiksi pilihan Anda sambil tetap menggunakan models.mode: "merge" untuk fallback Anthropic/OpenAI.
• Lokal saja tetap menjadi jalur privasi terkuat; routing regional hosted adalah jalan tengah saat Anda membutuhkan fitur provider tetapi ingin mengontrol aliran data.

Proxy lokal lain yang kompatibel dengan OpenAI

MLX (mlx_lm.server), vLLM, SGLang, LiteLLM, OAI-proxy, atau gateway kustom berfungsi jika mengekspos endpoint bergaya OpenAI /v1/chat/completions. Gunakan adapter Chat Completions kecuali backend secara eksplisit mendokumentasikan dukungan /v1/responses. Ganti blok provider di atas dengan endpoint dan ID model Anda:

{  agents: {    defaults: {      model: { primary: "local/my-local-model" },    },  },  models: {    mode: "merge",    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "sk-local",        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: 120000,            maxTokens: 8192,          },        ],      },    },  },}

Jika api dihilangkan pada provider kustom dengan baseUrl, OpenClaw default ke openai-completions. Entri provider kustom/lokal memercayai origin baseUrl tepat yang dikonfigurasi untuk permintaan model yang dijaga, termasuk loopback, LAN, tailnet, dan host DNS privat. Permintaan ke origin privat lain tetap memerlukan request.allowPrivateNetwork: true; origin metadata/link-local tetap diblokir tanpa opt-in eksplisit. Atur ke false untuk opt out dari kepercayaan exact-origin.

Nilai models.providers.<id>.models[].id bersifat lokal untuk provider. Jangan sertakan prefiks provider di sana. Misalnya, server MLX yang dimulai dengan mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit harus menggunakan ID katalog dan ref model ini:

• models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
• agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

Atur input: ["text", "image"] pada model visi lokal atau yang diproxy agar lampiran gambar disisipkan ke turn agen. Onboarding provider kustom interaktif menyimpulkan ID model visi umum dan hanya bertanya untuk nama yang tidak dikenal. Onboarding non-interaktif menggunakan inferensi yang sama; gunakan --custom-image-input untuk ID visi yang tidak dikenal atau --custom-text-input saat model yang tampak dikenal sebenarnya text-only di balik endpoint Anda.

Pertahankan models.mode: "merge" agar model hosted tetap tersedia sebagai fallback. Gunakan models.providers.<id>.timeoutSeconds untuk server model lokal atau remote yang lambat sebelum menaikkan agents.defaults.timeoutSeconds. Timeout provider hanya berlaku untuk permintaan HTTP model, termasuk connect, headers, streaming body, dan total abort guarded-fetch. Jika timeout agen atau run lebih rendah, naikkan batas itu juga karena timeout provider tidak dapat memperpanjang keseluruhan run agen.

Catatan perilaku untuk backend /v1 lokal/yang diproxy:

• OpenClaw memperlakukan ini sebagai route kompatibel OpenAI bergaya proxy, bukan endpoint OpenAI native
• shaping permintaan khusus OpenAI native tidak berlaku di sini: tidak ada service_tier, tidak ada Responses store, tidak ada shaping payload kompatibilitas penalaran OpenAI, dan tidak ada hint prompt-cache
• header atribusi OpenClaw tersembunyi (originator, version, User-Agent) tidak disisipkan pada URL proxy kustom ini

Catatan kompatibilitas untuk backend kompatibel OpenAI yang lebih ketat:

• Sebagian server hanya menerima messages[].content string pada Chat Completions, bukan array content-part terstruktur. Atur models.providers.<provider>.models[].compat.requiresStringContent: true untuk endpoint tersebut.

• Sebagian model lokal mengeluarkan permintaan tool berkurung yang berdiri sendiri sebagai teks, seperti [tool_name] diikuti JSON dan [END_TOOL_REQUEST]. OpenClaw mempromosikan itu menjadi pemanggilan tool nyata hanya saat namanya persis cocok dengan tool terdaftar untuk turn tersebut; jika tidak, blok diperlakukan sebagai teks yang tidak didukung dan disembunyikan dari balasan yang terlihat oleh pengguna.

• Jika model mengeluarkan teks JSON, XML, atau bergaya ReAct yang tampak seperti pemanggilan tool tetapi provider tidak mengeluarkan invokasi terstruktur, OpenClaw membiarkannya sebagai teks dan mencatat warning dengan run id, provider/model, pola yang terdeteksi, dan nama tool saat tersedia. Perlakukan itu sebagai inkompatibilitas tool-call provider/model, bukan run tool yang selesai.

• Jika tool muncul sebagai teks assistant alih-alih berjalan, misalnya JSON mentah, XML, sintaks ReAct, atau array tool_calls kosong dalam respons provider, pertama pastikan server menggunakan template/parser chat yang mendukung tool-call. Untuk backend Chat Completions kompatibel OpenAI yang parser-nya hanya berfungsi saat penggunaan tool dipaksa, atur override permintaan per model alih-alih mengandalkan parsing teks:

  {  agents: {    defaults: {      models: {        "local/my-local-model": {          params: {            extra_body: {              tool_choice: "required",            },          },        },      },    },  },}

  Gunakan ini hanya untuk model/sesi tempat setiap turn normal harus memanggil tool. Ini menggantikan nilai proxy default OpenClaw yaitu tool_choice: "auto". Ganti local/my-local-model dengan ref provider/model persis yang ditampilkan oleh openclaw models list.

  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge

• Jika model kustom kompatibel OpenAI menerima upaya penalaran OpenAI di luar profil bawaan, deklarasikan pada blok kompatibilitas model. Menambahkan "xhigh" di sini membuat /think xhigh, picker sesi, validasi Gateway, dan validasi llm-task mengekspos level tersebut untuk ref provider/model yang dikonfigurasi itu:

  {  models: {    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "sk-local",        api: "openai-responses",        models: [          {            id: "gpt-5.4",            name: "GPT 5.4 via local proxy",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,            compat: {              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],              reasoningEffortMap: { xhigh: "xhigh" },            },          },        ],      },    },  },}

Backend yang lebih kecil atau lebih ketat

Jika model dimuat dengan bersih tetapi giliran agen penuh bermasalah, kerjakan dari atas ke bawah — konfirmasi transport terlebih dahulu, lalu persempit permukaannya.

1. Konfirmasi model lokal itu sendiri merespons. Tanpa alat, tanpa konteks agen:

   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json

2. Konfirmasi perutean Gateway. Hanya mengirim prompt yang diberikan — melewati transkrip, bootstrap AGENTS, perakitan mesin konteks, alat, dan server MCP bawaan, tetapi tetap menguji perutean Gateway, autentikasi, dan pemilihan penyedia:

   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json

3. Coba mode ramping. Jika kedua probe lolos tetapi giliran agen nyata gagal dengan panggilan alat yang salah format atau prompt yang terlalu besar, aktifkan agents.defaults.experimental.localModelLean: true. Ini menghapus tiga alat default terberat (browser, cron, message) dan menempatkan katalog alat yang lebih besar di balik kontrol Tool Search terstruktur secara default, kecuali untuk proses yang harus mempertahankan semantik pengiriman message langsung. Lihat Fitur Eksperimental → Mode ramping model lokal untuk penjelasan lengkap, kapan menggunakannya, dan cara mengonfirmasi bahwa mode tersebut aktif.

4. Nonaktifkan alat sepenuhnya sebagai upaya terakhir. Jika mode ramping belum cukup, atur models.providers.<provider>.models[].compat.supportsTools: false untuk entri model tersebut. Agen kemudian akan beroperasi tanpa panggilan alat pada model tersebut.

5. Setelah itu, hambatannya ada di upstream. Jika backend masih gagal hanya pada proses OpenClaw yang lebih besar setelah mode ramping dan supportsTools: false, masalah yang tersisa biasanya adalah kapasitas model atau server upstream — jendela konteks, memori GPU, pengusiran kv-cache, atau bug backend. Pada titik itu, masalahnya bukan lapisan transport OpenClaw.

Pemecahan masalah

• Gateway dapat menjangkau proxy? curl http://127.0.0.1:1234/v1/models.
• Model LM Studio tidak dimuat? Muat ulang; cold start adalah penyebab umum "menggantung".
• Server lokal mengatakan terminated, ECONNRESET, atau menutup stream di tengah giliran? OpenClaw mencatat model.call.error.failureKind berkardinalitas rendah beserta snapshot RSS/heap proses OpenClaw dalam diagnostik. Untuk tekanan memori LM Studio/Ollama, cocokkan timestamp tersebut dengan log server atau log crash / jetsam macOS untuk mengonfirmasi apakah server model dihentikan.
• OpenClaw menurunkan ambang preflight jendela konteks dari jendela model yang terdeteksi, atau dari jendela model tanpa batas ketika agents.defaults.contextTokens menurunkan jendela efektif. Ini memperingatkan di bawah 20% dengan batas bawah 8k. Blok keras menggunakan ambang 10% dengan batas bawah 4k, dibatasi ke jendela konteks efektif sehingga metadata model yang terlalu besar tidak dapat menolak batas pengguna yang sebenarnya valid. Jika Anda terkena preflight tersebut, naikkan batas konteks server/model atau pilih model yang lebih besar.
• Kesalahan konteks? Turunkan contextWindow atau naikkan batas server Anda.
• Server yang kompatibel dengan OpenAI mengembalikan messages[].content ... expected a string? Tambahkan compat.requiresStringContent: true pada entri model tersebut.
• Server yang kompatibel dengan OpenAI mengembalikan validation.keys atau mengatakan entri pesan hanya mengizinkan role dan content? Tambahkan compat.strictMessageKeys: true pada entri model tersebut.
• Panggilan kecil langsung /v1/chat/completions berfungsi, tetapi openclaw infer model run --local gagal pada Gemma atau model lokal lain? Periksa URL penyedia, referensi model, penanda autentikasi, dan log server terlebih dahulu; model run lokal tidak menyertakan alat agen. Jika model run lokal berhasil tetapi giliran agen yang lebih besar gagal, kurangi permukaan alat agen dengan localModelLean atau compat.supportsTools: false.
• Panggilan alat muncul sebagai teks JSON/XML/ReAct mentah, atau penyedia mengembalikan array tool_calls kosong? Jangan tambahkan proxy yang secara membabi buta mengonversi teks asisten menjadi eksekusi alat. Perbaiki template/parser chat server terlebih dahulu. Jika model hanya berfungsi ketika penggunaan alat dipaksa, tambahkan override per model params.extra_body.tool_choice: "required" di atas dan gunakan entri model tersebut hanya untuk sesi ketika panggilan alat diharapkan pada setiap giliran.
• Keamanan: model lokal melewati filter sisi penyedia; jaga agen tetap sempit dan Compaction aktif untuk membatasi radius dampak injeksi prompt.

Terkait

• Referensi konfigurasi
• Failover model