Gateway

Model lokal

Model lokal dapat digunakan. Model lokal juga menaikkan standar untuk perangkat keras, ukuran konteks, dan pertahanan prompt-injection — kartu kecil atau yang dikuantisasi secara agresif memotong konteks dan membocorkan keamanan. Halaman ini adalah panduan berpendirian 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.

Batas minimum perangkat keras

Targetkan tinggi: ≥2 Mac Studio spesifikasi maksimum atau rig GPU yang setara (~$30k+) untuk local loop agent 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 sangat terkuantisasi meningkatkan risiko prompt-injection (lihat Keamanan).

Pilih backend

Backend	Gunakan saat
LM Studio	Penyiapan lokal pertama kali, pemuat GUI, Responses API native
Ollama	Alur kerja CLI, pustaka model, layanan systemd tanpa banyak intervensi
MLX / vLLM / SGLang	Penyajian self-hosted throughput tinggi dengan endpoint HTTP yang kompatibel dengan OpenAI
LiteLLM / OAI-proxy / proksi kustom yang kompatibel dengan OpenAI	Anda meneruskan API model lain dan perlu membuat OpenClaw memperlakukannya sebagai OpenAI

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 reasoning tetap terpisah dari teks akhir.

{
  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 sangat terkuantisasi), 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 akhir yang dikirim.

Tetap konfigurasikan model hosted 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,
          },
        ],
      },
    },
  },
}

Utamakan lokal 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 / perutean data

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

Proksi 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. Endpoint loopback seperti 127.0.0.1 dipercaya secara otomatis; endpoint LAN, tailnet, dan DNS privat tetap membutuhkan request.allowPrivateNetwork: true.

Nilai models.providers.<id>.models[].id bersifat lokal untuk provider. Jangan sertakan prefix 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 vision lokal atau yang diproksi agar lampiran gambar disisipkan ke dalam giliran agent. Onboarding provider kustom interaktif menyimpulkan ID model vision umum dan hanya menanyakan nama yang tidak dikenal. Onboarding non-interaktif menggunakan inferensi yang sama; gunakan --custom-image-input untuk ID vision yang tidak dikenal atau --custom-text-input saat model yang tampak dikenal ternyata hanya teks 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, body streaming, dan total abort guarded-fetch.

Catatan perilaku untuk backend /v1 lokal/diproksi:

OpenClaw memperlakukan ini sebagai rute proxy-style yang kompatibel dengan OpenAI, bukan endpoint OpenAI native
pembentukan permintaan khusus OpenAI native tidak berlaku di sini: tidak ada service_tier, tidak ada Responses store, tidak ada pembentukan payload reasoning-compat OpenAI, dan tidak ada hint prompt-cache
header atribusi OpenClaw tersembunyi (originator, version, User-Agent) tidak disisipkan pada URL proksi kustom ini

Catatan kompatibilitas untuk backend yang kompatibel dengan OpenAI yang lebih ketat:

Beberapa 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.
Beberapa model lokal memancarkan permintaan tool bertanda kurung yang berdiri sendiri sebagai teks, seperti [tool_name] diikuti JSON dan [END_TOOL_REQUEST]. OpenClaw mempromosikannya menjadi pemanggilan tool nyata hanya saat namanya sama persis dengan tool terdaftar untuk giliran tersebut; jika tidak, blok diperlakukan sebagai teks yang tidak didukung dan disembunyikan dari balasan yang terlihat pengguna.
Jika model memancarkan JSON, XML, atau teks bergaya ReAct yang tampak seperti pemanggilan tool tetapi provider tidak memancarkan invocation terstruktur, OpenClaw membiarkannya sebagai teks dan mencatat peringatan dengan run id, provider/model, pola yang terdeteksi, dan nama tool bila tersedia. Perlakukan itu sebagai ketidakcocokan tool-call provider/model, bukan tool run 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 chat template/parser yang mampu tool-call. Untuk backend Chat Completions yang kompatibel dengan 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 ketika setiap giliran normal harus memanggil tool. Ini menimpa 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 yang kompatibel dengan OpenAI menerima upaya reasoning OpenAI di luar profil bawaan, deklarasikan pada blok compat model. Menambahkan "xhigh" di sini membuat /think xhigh, pemilih 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 agent penuh berperilaku salah, kerjakan dari atas ke bawah — pastikan transport terlebih dahulu, lalu persempit surface.

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

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

Pastikan perutean Gateway. Hanya mengirim prompt yang diberikan — melewati transkrip, bootstrap AGENTS, perakitan context-engine, 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
```
Coba mode ramping. Jika kedua probe lolos tetapi giliran agen nyata gagal dengan pemanggilan alat yang salah format atau prompt yang terlalu besar, aktifkan agents.defaults.experimental.localModelLean: true. Ini menghapus tiga alat default terberat (browser, cron, message) sehingga bentuk prompt lebih kecil dan tidak terlalu rapuh. Lihat Fitur Eksperimental → Mode ramping model lokal untuk penjelasan lengkap, kapan menggunakannya, dan cara memastikan mode ini aktif.
Nonaktifkan alat sepenuhnya sebagai upaya terakhir. Jika mode ramping tidak cukup, atur models.providers.<provider>.models[].compat.supportsTools: false untuk entri model tersebut. Agen kemudian akan beroperasi tanpa pemanggilan alat pada model itu.
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, pengeluaran 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 belum dimuat? Muat ulang; start dingin adalah penyebab umum "menggantung".
Server lokal mengatakan terminated, ECONNRESET, atau menutup stream di tengah giliran? OpenClaw mencatat model.call.error.failureKind berkardinalitas rendah serta 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 memastikan apakah server model dimatikan.
OpenClaw menurunkan ambang preflight jendela konteks dari jendela model yang terdeteksi, atau dari jendela model tanpa batas saat 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 itu, naikkan batas konteks server/model atau pilih model yang lebih besar.
Kesalahan konteks? Turunkan contextWindow atau naikkan batas server Anda.
Server kompatibel OpenAI mengembalikan messages[].content ... expected a string? Tambahkan compat.requiresStringContent: true pada entri model tersebut.
Panggilan kecil langsung ke /v1/chat/completions berhasil, 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.
Pemanggilan alat muncul sebagai teks JSON/XML/ReAct mentah, atau penyedia mengembalikan array tool_calls kosong? Jangan tambahkan proxy yang secara membabi buta mengubah teks asisten menjadi eksekusi alat. Perbaiki template/parser chat server terlebih dahulu. Jika model hanya berfungsi saat penggunaan alat dipaksa, tambahkan override per model params.extra_body.tool_choice: "required" di atas dan gunakan entri model itu hanya untuk sesi ketika pemanggilan 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.

Model lokal

Batas minimum perangkat keras

Pilih backend

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

Konfigurasi hibrida: primary hosted, fallback lokal

Utamakan lokal dengan jaring pengaman hosted

Hosting regional / perutean data

Proksi lokal lain yang kompatibel dengan OpenAI

Backend yang lebih kecil atau lebih ketat

Pemecahan Masalah

Terkait

Ask OpenClaw

# Batas minimum perangkat keras

# Pilih backend

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

# Konfigurasi hibrida: primary hosted, fallback lokal

# Utamakan lokal dengan jaring pengaman hosted

# Hosting regional / perutean data

# Proksi lokal lain yang kompatibel dengan OpenAI

# Backend yang lebih kecil atau lebih ketat

# Pemecahan Masalah

# Terkait

Batas minimum perangkat keras

Pilih backend

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

Konfigurasi hibrida: primary hosted, fallback lokal

Utamakan lokal dengan jaring pengaman hosted

Hosting regional / perutean data

Proksi lokal lain yang kompatibel dengan OpenAI

Backend yang lebih kecil atau lebih ketat

Pemecahan Masalah

Terkait