Ollama

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

Host jarak jauh publik dan https://ollama.com memerlukan kredensial sebenarnya: OLLAMA_API_KEY, profil autentikasi, atau apiKey milik penyedia. Untuk penggunaan terhosting langsung, 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; tempatkan 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 ollama-windows:default yang kanonis dengan cadangan. Nilai baseUrl dalam berkas lama tersebut adalah derau 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. Jaga agar keduanya selaras ketika perangkat keras tidak dapat menjalankan seluruh konteks yang diiklankan model.

Tanpa daemon lokal, langsung menggunakan model yang di-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, alih-alih 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/ biasa) sebelum memanggil Ollama, sehingga ollama-large/qwen3.5:27b mencapai Ollama sebagai qwen3.5:27b.

Beberapa model lokal dapat menangani prompt sederhana, tetapi kesulitan dengan seluruh permukaan 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 jika model atau server terus-menerus gagal pada skema alat — opsi ini mengorbankan kemampuan agen demi stabilitas. localModelLean menghapus alat berat untuk peramban, cron, pesan, pembuatan media, suara, dan PDF dari permukaan agen langsung, kecuali diwajibkan secara eksplisit, serta menempatkan katalog yang lebih besar di balik Pencarian Alat. Opsi 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 tanpa henti atau menghabiskan anggarannya untuk penalaran tersembunyi.

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

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

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

OpenClaw menyisipkan options.num_ctx secara bawaan dalam mode ini agar Ollama tidak 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 /api/show, termasuk nilai PARAMETER num_ctx yang lebih besar dari Modelfile khusus; jika tidak, OpenClaw kembali menggunakan jendela konteks Ollama bawaannya.

contextWindow, contextTokens, dan maxTokens tingkat penyedia menetapkan nilai bawaan 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 bawaan berdasarkan modelnya sendiri, OLLAMA_CONTEXT_LENGTH, atau VRAM; nilai params.num_ctx yang tidak valid, nol, negatif, atau tidak 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 masih menyisipkan options.num_ctx secara bawaan dari params.num_ctx atau contextWindow yang dikonfigurasi; nonaktifkan dengan injectNumCtxForOpenAICompat: false jika upstream menolak options.

Entri model native juga menerima opsi runtime Ollama umum di bawah params, yang diteruskan sebagai /api/chat options native: 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 atas, bukan sebagai 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 atas; 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 akan diprioritaskan jika keduanya ditetapkan.

OpenClaw meneruskan pemikiran sesuai yang diharapkan Ollama: think tingkat atas, bukan options.think. Model yang ditemukan otomatis dan /api/show-nya melaporkan kemampuan thinking menyediakan /think low, /think medium, /think high, dan /think max; model tanpa pemikiran 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 memaksa pemikiran API untuk model tertentu. OpenClaw mempertahankan konfigurasi eksplisit tersebut ketika proses aktif hanya memiliki nilai default implisit off; perintah runtime selain off seperti /think medium tetap menimpanya. Permintaan pemikiran bernilai benar tidak pernah dikirim ke model yang secara eksplisit ditandai reasoning: false; permintaan think: false selalu dikirim tanpa pengecualian.

Model bernama deepseek-r1, reasoning, reason, atau think secara default dianggap mendukung penalaran — tidak memerlukan konfigurasi tambahan:

ollama pull deepseek-r1:32b

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

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

Ketika proxy.enabled=true, permintaan penyematan ke origin loopback lokal-host yang persis, yang diturunkan dari baseUrl terkonfigurasi, menggunakan jalur langsung terlindungi milik OpenClaw, bukan proksi penerusan terkelola. Nama host yang dikonfigurasi itu sendiri harus berupa localhost atau literal IP loopback — nama DNS yang hanya me-resolve ke loopback tetap menggunakan jalur proksi terkelola. Host Ollama di LAN, tailnet, jaringan privat, dan jaringan 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.

Penyematan 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 ada tidak memerlukan migrasi format.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Default untuk Ollama. Naikkan pada host yang lebih besar jika pengindeksan ulang terlalu lambat.          nonBatchConcurrency: 1,        },      },    },  },}

Untuk host penyematan jarak jauh, batasi cakupan autentikasi ke 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 default, yang mendukung streaming dan pemanggilan alat secara bersamaan — tidak memerlukan konfigurasi khusus.

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

Pada WSL2 dengan NVIDIA/CUDA, penginstal resmi Ollama untuk Linux membuat unit systemd ollama.service dengan Restart=always. Jika layanan tersebut dimulai otomatis dan memuat model berbasis GPU saat WSL2 melakukan boot, Ollama dapat menahan 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.

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

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

Mitigasi:

sudo systemctl disable ollama

Di sisi Windows, tambahkan ini 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 berjalan, OLLAMA_API_KEY (atau profil autentikasi) telah ditetapkan, 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  # Lihat apa yang telah terinstalollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Atau model lain

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, tetapkan compat.supportsTools: false pada entri model tersebut dan uji kembali.

Respons Kimi/GLM yang di-host 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 terjadi lagi, catat nama model, file 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 "Balas persis dengan: ok" --jsonopenclaw models set ollama/gemma4

Model lokal besar dapat memerlukan waktu lama untuk pemuatan pertama. Batasi cakupan waktu tunggu ke penyedia Ollama dan, jika diinginkan, pertahankan model tetap termuat 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 waktu tunggu koneksi terlindungi untuk penyedia ini.

Banyak model mengiklankan konteks yang lebih besar daripada yang dapat dijalankan perangkat keras Anda dengan nyaman. Ollama native menggunakan default runtime-nya sendiri kecuali params.num_ctx ditetapkan. Batasi anggaran OpenClaw dan konteks permintaan Ollama untuk mendapatkan latensi token pertama yang 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 tersebut. Turunkan maxTokens jika pembuatan keluaran berlangsung terlalu lama.