Model lokal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Batas minimum perangkat keras

​

Pilih backend

​

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

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

• Instal LM Studio: https://lmstudio.ai
• Di LM Studio, unduh build model terbesar yang tersedia (hindari varian “small”/sangat terkuantisasi), mulai server, pastikan http://127.0.0.1:1234/v1/models mencantumkannya.
• Ganti my-local-model dengan ID model sebenarnya 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.

​

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

​

Hosting regional / routing data

• Varian MiniMax/Kimi/GLM hosted juga tersedia di OpenRouter dengan endpoint yang dipatok ke wilayah (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.
• Local-only tetap menjadi jalur privasi terkuat; routing regional hosted adalah jalan tengah saat Anda membutuhkan fitur provider tetapi ingin mengendalikan aliran data.

​

Proxy lokal kompatibel OpenAI lainnya

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

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

• OpenClaw memperlakukan ini sebagai route kompatibel OpenAI bergaya proxy, 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 proxy kustom ini

• Beberapa server hanya menerima messages[].content string pada Chat Completions, bukan array content-part terstruktur. Tetapkan models.providers.<provider>.models[].compat.requiresStringContent: true untuk endpoint tersebut.
• Beberapa model lokal mengeluarkan permintaan tool mandiri dalam tanda kurung sebagai teks, seperti [tool_name] diikuti JSON dan [END_TOOL_REQUEST]. OpenClaw mempromosikannya menjadi panggilan tool nyata hanya saat namanya persis cocok dengan tool terdaftar untuk giliran tersebut; jika tidak, blok diperlakukan sebagai teks yang tidak didukung dan disembunyikan dari balasan yang terlihat pengguna.
• Jika model mengeluarkan JSON, XML, atau teks bergaya ReAct yang terlihat seperti panggilan tool tetapi provider tidak mengeluarkan invocation terstruktur, OpenClaw membiarkannya sebagai teks dan mencatat peringatan dengan run id, provider/model, pola yang terdeteksi, dan nama tool saat tersedia. Perlakukan itu sebagai inkompatibilitas 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 mendukung tool-call. Untuk backend Chat Completions kompatibel OpenAI yang parser-nya hanya bekerja saat penggunaan tool dipaksa, tetapkan 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 giliran normal harus memanggil tool. Ini meng-override nilai proxy default OpenClaw untuk 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 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:
  {
    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

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 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
   
3. Coba mode ramping. Jika kedua pemeriksaan lolos tetapi giliran agen nyata gagal dengan pemanggilan alat yang tidak valid 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 mengonfirmasi bahwa mode ini aktif.
4. Nonaktifkan alat sepenuhnya sebagai pilihan terakhir. Jika mode ramping tidak cukup, tetapkan models.providers.<provider>.models[].compat.supportsTools: false untuk entri model tersebut. Agen kemudian akan beroperasi tanpa pemanggilan 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, penggusuran kv-cache, atau bug backend. Pada titik itu, ini 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 plus 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 telah 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. Pemblokiran 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 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.
• Pemanggilan kecil langsung ke /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.
• Pemanggilan alat muncul sebagai teks JSON/XML/ReAct mentah, atau penyedia mengembalikan array tool_calls kosong? Jangan tambahkan proxy yang secara 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 yang mengharapkan pemanggilan alat 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