Ollama

URL Ollama local loopback, jaringan privat, .local, dan nama host polos tidak memerlukan token bearer yang sebenarnya. OpenClaw menggunakan penanda ollama-local untuk URL tersebut.

Host publik jarak jauh dan https://ollama.com memerlukan kredensial yang sebenarnya: OLLAMA_API_KEY, profil autentikasi, atau apiKey penyedia. Untuk penggunaan langsung yang dihosting, utamakan penyedia ollama-cloud.

Penyedia khusus dengan api: "ollama" mengikuti aturan yang sama. Misalnya, penyedia ollama-remote yang diarahkan ke host LAN privat dapat menggunakan apiKey: "ollama-local"; subagen menyelesaikan penanda tersebut melalui hook penyedia Ollama alih-alih menganggapnya sebagai kredensial yang hilang. agents.defaults.memorySearch.provider juga dapat diarahkan ke id penyedia khusus agar embedding menggunakan endpoint Ollama tersebut.

auth-profiles.json menyimpan kredensial untuk suatu id penyedia; letakkan pengaturan endpoint (baseUrl, api, model, header, batas waktu) di models.providers.<id>. Berkas datar lama seperti { "ollama-windows": { "apiKey": "ollama-local" } } bukan format runtime; openclaw doctor --fix menulis ulang berkas tersebut menjadi profil kunci API kanonis ollama-windows:default beserta cadangannya. Nilai baseUrl dalam berkas lama tersebut tidak relevan dan harus dipindahkan ke konfigurasi penyedia.

Autentikasi bearer untuk embedding memori Ollama dibatasi pada host tempat autentikasi tersebut dideklarasikan:

• Kunci tingkat penyedia hanya dikirim ke host penyedia tersebut.
• agents.*.memorySearch.remote.apiKey hanya dikirim ke host embedding jarak jauhnya.
• Nilai env OLLAMA_API_KEY murni dianggap sebagai konvensi Ollama Cloud dan secara default tidak dikirim ke host lokal/yang dihosting sendiri.

Ollama pada mesin yang sama dengan Gateway, ditemukan secara otomatis:

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

Jangan tambahkan blok models.providers.ollama kecuali Anda memerlukan model manual.

{  models: {    providers: {      ollama: {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 300,        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            reasoning: true,            input: ["text"],            params: {              num_ctx: 32768,              thinking: false,              keep_alive: "15m",            },          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/qwen3.5:9b" },    },  },}

contextWindow adalah anggaran konteks OpenClaw; params.num_ctx dikirim ke Ollama. Selaraskan keduanya ketika perangkat keras tidak dapat menjalankan seluruh konteks yang diiklankan model.

Tanpa daemon lokal, langsung menggunakan model ter-host:

export OLLAMA_API_KEY="your-ollama-api-key"

{  models: {    providers: {      ollama: {        baseUrl: "https://ollama.com",        apiKey: "OLLAMA_API_KEY",        api: "ollama",        models: [          {            id: "kimi-k2.5:cloud",            name: "kimi-k2.5:cloud",            reasoning: false,            input: ["text", "image"],            contextWindow: 128000,            maxTokens: 8192,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/kimi-k2.5:cloud" },    },  },}

Untuk id penyedia khusus ollama-cloud sebagai pengganti bentuk ini, lihat Ollama Cloud.

Gunakan ID penyedia khusus saat menjalankan lebih dari satu server Ollama; masing-masing memiliki host, model, autentikasi, dan batas waktunya sendiri.

{  models: {    providers: {      "ollama-fast": {        baseUrl: "http://mini.local:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],      },      "ollama-large": {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 420,        contextWindow: 131072,        maxTokens: 16384,        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],      },    },  },  agents: {    defaults: {      model: {        primary: "ollama-fast/gemma4",        fallbacks: ["ollama-large/qwen3.5:27b"],      },    },  },}

OpenClaw menghapus prefiks penyedia aktif (dengan kembali menggunakan prefiks ollama/ saja sebagai cadangan) sebelum memanggil Ollama, sehingga ollama-large/qwen3.5:27b diterima Ollama sebagai qwen3.5:27b.

Beberapa model lokal dapat menangani prompt sederhana, tetapi kesulitan dengan seluruh cakupan alat agen. Batasi alat dan konteks sebelum mengubah pengaturan runtime global:

{  agents: {    list: [      {        id: "local",        experimental: {          localModelLean: true,        },        model: { primary: "ollama/gemma4" },      },    ],  },  models: {    providers: {      ollama: {        baseUrl: "http://127.0.0.1:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [          {            id: "gemma4",            name: "gemma4",            input: ["text"],            params: { num_ctx: 32768 },            compat: { supportsTools: false },          },        ],      },    },  },}

Gunakan compat.supportsTools: false hanya ketika model atau server selalu gagal memproses skema alat — pengaturan ini mengorbankan kemampuan agen demi stabilitas. localModelLean menghapus alat berat untuk peramban, cron, pesan, pembuatan media, suara, dan PDF dari cakupan langsung agen kecuali diwajibkan secara eksplisit, serta menempatkan katalog yang lebih besar di balik Pencarian Alat. Pengaturan ini tidak mengubah konteks runtime atau mode berpikir Ollama. Padukan dengan params.num_ctx dan params.thinking: false untuk model berpikir kecil bergaya Qwen yang berulang atau menghabiskan anggarannya untuk penalaran tersembunyi.

Tetapkan api: "openai-completions" secara eksplisit untuk proksi di belakang /v1/chat/completions:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // default: true        apiKey: "ollama-local",        models: [...]      }    }  }}

Mode ini mungkin tidak mendukung pengaliran dan pemanggilan alat secara bersamaan; Anda mungkin perlu menetapkan params: { streaming: false } pada model.

OpenClaw menyisipkan options.num_ctx secara default dalam mode ini agar Ollama tidak secara diam-diam kembali menggunakan konteks 4096 token. Jika proksi Anda menolak bidang options yang tidak dikenal, nonaktifkan:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: false,        apiKey: "ollama-local",        models: [...]      }    }  }}

Untuk model yang ditemukan secara otomatis, OpenClaw menggunakan jendela konteks yang dilaporkan oleh /api/show, termasuk nilai PARAMETER num_ctx yang lebih besar dari Modelfile khusus; jika tidak, OpenClaw kembali menggunakan jendela konteks Ollama default miliknya.

contextWindow, contextTokens, dan maxTokens tingkat penyedia menetapkan nilai default untuk setiap model di bawah penyedia tersebut dan dapat ditimpa per model. contextWindow adalah anggaran prompt/Compaction milik OpenClaw. Permintaan /api/chat native membiarkan options.num_ctx tidak ditetapkan kecuali Anda menetapkan params.num_ctx secara eksplisit, sehingga Ollama menerapkan nilai default modelnya sendiri, OLLAMA_CONTEXT_LENGTH, atau nilai berbasis VRAM; nilai params.num_ctx yang tidak valid, nol, negatif, atau bukan bilangan terbatas akan diabaikan. Jika konfigurasi lama hanya menggunakan contextWindow/maxTokens untuk memaksakan konteks permintaan native, jalankan openclaw doctor --fix untuk menyalinnya ke params.num_ctx. Adaptor yang kompatibel dengan OpenAI tetap menyisipkan options.num_ctx secara default dari params.num_ctx atau contextWindow yang dikonfigurasi; nonaktifkan dengan injectNumCtxForOpenAICompat: false jika layanan hulu menolak options.

Entri model native juga menerima opsi runtime Ollama umum di bawah params, yang diteruskan sebagai options native /api/chat: num_keep, seed, num_predict, top_k, top_p, min_p, typical_p, repeat_last_n, temperature, repeat_penalty, presence_penalty, frequency_penalty, stop, num_batch, num_gpu, main_gpu, use_mmap, dan num_thread. Beberapa kunci (format, keep_alive, truncate, shift) diteruskan sebagai bidang permintaan tingkat teratas, bukan options bertingkat. OpenClaw hanya meneruskan kunci permintaan Ollama ini, sehingga parameter khusus runtime seperti streaming tidak pernah dikirim ke Ollama. Gunakan params.think (atau params.thinking) untuk menetapkan think tingkat teratas; false menonaktifkan pemikiran tingkat API untuk model berpikir bergaya Qwen.

{  models: {    providers: {      ollama: {        contextWindow: 32768,        models: [          {            id: "llama3.3",            contextWindow: 131072,            maxTokens: 65536,            params: {              num_ctx: 32768,              temperature: 0.7,              top_p: 0.9,              thinking: false,            },          }        ]      }    }  }}

agents.defaults.models["ollama/<model>"].params.num_ctx per model juga berfungsi; entri model penyedia eksplisit diutamakan jika keduanya ditetapkan.

OpenClaw meneruskan pemikiran sesuai yang diharapkan Ollama: think tingkat teratas, bukan options.think. Model yang ditemukan secara otomatis dan kemampuan thinking-nya dilaporkan oleh /api/show menyediakan /think low, /think medium, /think high, dan /think max; model tanpa kemampuan berpikir hanya menyediakan /think off.

openclaw agent --model ollama/gemma4 --thinking offopenclaw agent --model ollama/gemma4 --thinking low

Atau tetapkan nilai default model:

{  agents: {    defaults: {      models: {        "ollama/gemma4": {          thinking: "low",        },      },    },  },}

params.think/params.thinking per model dapat menonaktifkan atau memaksakan proses berpikir API untuk model tertentu. OpenClaw mempertahankan konfigurasi eksplisit tersebut ketika proses aktif hanya memiliki nilai bawaan implisit off; perintah runtime selain off seperti /think medium tetap menggantikannya. Permintaan proses berpikir yang bernilai benar tidak pernah dikirim ke model yang secara eksplisit ditandai reasoning: false; permintaan think: false selalu dikirim dalam kondisi apa pun.

Model bernama deepseek-r1, reasoning, reason, atau think secara bawaan dianggap mampu melakukan penalaran — tidak memerlukan konfigurasi tambahan:

ollama pull deepseek-r1:32b

Ollama berjalan secara lokal dan gratis, sehingga semua biaya model adalah 0, baik untuk model yang ditemukan secara otomatis maupun yang ditentukan secara manual.

Plugin Ollama bawaan mendaftarkan penyedia embedding memori untuk pencarian memori. Penyedia ini menggunakan URL dasar Ollama dan kunci API yang dikonfigurasi, memanggil /api/embed, serta mengelompokkan beberapa potongan memori ke dalam satu permintaan input jika memungkinkan.

Saat proxy.enabled=true, permintaan embedding ke origin local loopback host yang sama persis dan diturunkan dari baseUrl yang dikonfigurasi menggunakan jalur langsung terlindungi milik OpenClaw, bukan proksi penerusan terkelola. Nama host yang dikonfigurasi harus berupa localhost atau literal IP loopback — nama DNS yang sekadar di-resolve ke loopback tetap menggunakan jalur proksi terkelola. Host Ollama di LAN, tailnet, jaringan privat, dan publik selalu tetap menggunakan jalur proksi terkelola, dan pengalihan ke host/port lain tidak mewarisi kepercayaan. proxy.loopbackMode: "proxy" tetap merutekan lalu lintas loopback melalui proksi; proxy.loopbackMode: "block" menolaknya sebelum tersambung — lihat Proksi terkelola.

Embedding saat kueri menggunakan prefiks pengambilan untuk model yang mewajibkan atau merekomendasikannya: nomic-embed-text, qwen3-embedding, dan mxbai-embed-large. Batch dokumen tetap mentah, sehingga indeks yang sudah ada tidak memerlukan migrasi format.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Default for Ollama. Raise on larger hosts if reindexing is too slow.          nonBatchConcurrency: 1,        },      },    },  },}

Untuk host embedding jarak jauh, batasi cakupan autentikasi hanya pada host tersebut:

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        model: "nomic-embed-text",        remote: {          baseUrl: "http://gpu-box.local:11434",          apiKey: "ollama-local",          nonBatchConcurrency: 2,        },      },    },  },}

Ollama menggunakan API native (/api/chat) secara bawaan, yang mendukung streaming dan pemanggilan alat secara bersamaan — tidak memerlukan konfigurasi khusus.

Untuk permintaan native, kontrol proses berpikir diteruskan secara langsung: /think off dan openclaw agent --thinking off mengirim think: false pada tingkat teratas, kecuali params.think/params.thinking eksplisit telah dikonfigurasi; /think low|medium|high mengirim string tingkat upaya yang sesuai; /think max dipetakan ke tingkat upaya tertinggi Ollama, yaitu think: "high".

Pada WSL2 dengan NVIDIA/CUDA, penginstal Linux resmi Ollama membuat unit systemd ollama.service dengan Restart=always. Jika layanan tersebut dimulai otomatis dan memuat model berbasis GPU selama proses boot WSL2, Ollama dapat mengunci memori host selama pemuatan; pengambilan kembali memori Hyper-V tidak selalu dapat mengambil kembali halaman-halaman tersebut, sehingga Windows dapat menghentikan VM WSL2, systemd memulai ulang Ollama, dan siklus tersebut berulang.

Indikasi: boot ulang/penghentian WSL2 berulang, penggunaan CPU tinggi di app.slice atau ollama.service tepat setelah WSL2 dimulai, serta SIGTERM dari systemd, bukan dari penghenti OOM Linux.

OpenClaw mencatat peringatan saat mulai ketika mendeteksi WSL2, ollama.service diaktifkan dengan Restart=always, dan penanda CUDA terlihat.

Mitigasi:

sudo systemctl disable ollama

Di sisi Windows, tambahkan konfigurasi berikut ke %USERPROFILE%\.wslconfig, lalu jalankan wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

Atau persingkat keep-alive / mulai Ollama secara manual hanya saat diperlukan:

export OLLAMA_KEEP_ALIVE=5mollama serve

Lihat ollama/ollama#11317.

Pastikan Ollama sedang berjalan, OLLAMA_API_KEY (atau profil autentikasi) telah diatur, dan models.providers.ollama tidak ditentukan secara eksplisit:

ollama servecurl http://localhost:11434/api/tags

Tarik model secara lokal atau tentukan secara eksplisit di models.providers.ollama:

ollama list  # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

Verifikasi dari mesin dan runtime yang sama dengan yang menjalankan Gateway:

openclaw gateway status --deepcurl http://ollama-host:11434/api/tags

Penyebab umum:

• baseUrl mengarah ke localhost, tetapi Gateway berjalan di Docker atau host lain.
• URL menggunakan /v1, sehingga memilih perilaku kompatibel OpenAI, bukan Ollama native.
• Host jarak jauh memerlukan perubahan firewall atau pengikatan LAN.
• Model berada di daemon laptop Anda, tetapi tidak di daemon jarak jauh.

Biasanya penyedia berada dalam mode kompatibel OpenAI, atau model tidak dapat menangani skema alat. Utamakan mode native:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434",        api: "ollama",      },    },  },}

Jika model lokal kecil masih gagal menangani skema alat, atur compat.supportsTools: false pada entri model tersebut dan uji kembali.

Respons Kimi/GLM yang dihosting dan berupa rangkaian simbol panjang nonlinguistik diperlakukan sebagai panggilan penyedia yang gagal, bukan balasan yang berhasil, sehingga penanganan percobaan ulang/fallback/kesalahan normal mengambil alih, alih-alih menyimpan teks rusak ke dalam sesi.

Jika masalah terulang, catat nama model, berkas sesi saat ini, dan apakah proses menggunakan Cloud + Local atau Cloud only, lalu coba sesi baru dan model fallback:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --jsonopenclaw models set ollama/gemma4

Model lokal berukuran besar dapat memerlukan waktu lama untuk pemuatan pertama. Batasi cakupan batas waktu ke penyedia Ollama dan, secara opsional, pertahankan model tetap dimuat di antara giliran:

{  models: {    providers: {      ollama: {        timeoutSeconds: 300,        models: [          {            id: "gemma4:26b",            name: "gemma4:26b",            params: { keep_alive: "15m" },          },        ],      },    },  },}

Jika host itu sendiri lambat menerima koneksi, timeoutSeconds juga memperpanjang batas waktu koneksi terlindungi untuk penyedia ini.

Banyak model menawarkan konteks yang lebih besar daripada yang dapat dijalankan perangkat keras Anda dengan nyaman. Ollama native menggunakan nilai bawaan runtime-nya sendiri, kecuali params.num_ctx diatur. Batasi anggaran OpenClaw dan konteks permintaan Ollama agar latensi token pertama dapat diprediksi:

{  models: {    providers: {      ollama: {        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            params: { num_ctx: 32768, thinking: false },          },        ],      },    },  },}

Turunkan contextWindow jika OpenClaw mengirim terlalu banyak prompt. Turunkan params.num_ctx jika konteks runtime Ollama terlalu besar untuk mesin. Turunkan maxTokens jika pembuatan keluaran berlangsung terlalu lama.