Ollama

Host Ollama lokal dan LAN tidak memerlukan token bearer sungguhan. OpenClaw menggunakan penanda lokal ollama-local hanya untuk loopback, jaringan privat, .local, dan URL dasar Ollama dengan nama host polos.

Host publik jarak jauh dan Ollama Cloud (https://ollama.com) memerlukan kredensial sungguhan melalui OLLAMA_API_KEY, profil auth, atau apiKey milik penyedia. Untuk penggunaan terhosting langsung, utamakan penyedia ollama-cloud.

Id penyedia kustom yang menetapkan api: "ollama" mengikuti aturan yang sama. Misalnya, penyedia ollama-remote yang mengarah ke host Ollama LAN privat dapat menggunakan apiKey: "ollama-local" dan sub-agen akan menyelesaikan penanda itu melalui hook penyedia Ollama alih-alih memperlakukannya sebagai kredensial yang hilang. Pencarian memori juga dapat menetapkan agents.defaults.memorySearch.provider ke id penyedia kustom tersebut agar embedding menggunakan endpoint Ollama yang sesuai.

auth-profiles.json menyimpan kredensial untuk id penyedia. Letakkan pengaturan endpoint (baseUrl, api, id model, header, timeout) di models.providers.<id>. File profil auth datar lama seperti { "ollama-windows": { "apiKey": "ollama-local" } } bukan format runtime; jalankan openclaw doctor --fix untuk menulis ulangnya menjadi profil kunci API kanonis ollama-windows:default dengan cadangan. baseUrl dalam file tersebut adalah gangguan kompatibilitas dan harus dipindahkan ke konfigurasi penyedia.

Ketika Ollama digunakan untuk embedding memori, auth bearer dicakupkan ke host tempat ia dideklarasikan:

• Kunci tingkat penyedia hanya dikirim ke host Ollama milik penyedia tersebut.
• agents.*.memorySearch.remote.apiKey hanya dikirim ke host embedding jarak jauhnya.
• Nilai env OLLAMA_API_KEY murni diperlakukan sebagai konvensi Ollama Cloud, tidak dikirim ke host lokal atau self-hosted secara default.

Gunakan ini ketika Ollama berjalan pada mesin yang sama dengan Gateway dan Anda ingin OpenClaw menemukan model yang terpasang secara otomatis.

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

Jalur ini menjaga konfigurasi tetap minimal. Jangan tambahkan blok models.providers.ollama kecuali Anda ingin mendefinisikan model secara manual.

Gunakan URL Ollama native untuk host LAN. Jangan tambahkan /v1.

{  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 di sisi OpenClaw. params.num_ctx dikirim ke Ollama untuk permintaan. Jaga keduanya tetap selaras ketika perangkat keras Anda tidak dapat menjalankan konteks penuh yang diiklankan model.

Gunakan ini ketika Anda tidak menjalankan daemon lokal dan ingin model Ollama terhosting secara langsung.

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" },    },  },}

Gunakan ini ketika daemon Ollama lokal atau LAN sudah masuk dengan ollama signin dan harus melayani model lokal serta model :cloud.

ollama signinollama pull gemma4

{  models: {    providers: {      ollama: {        baseUrl: "http://127.0.0.1:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 300,        models: [          { id: "gemma4", name: "gemma4", input: ["text"] },          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },        ],      },    },  },  agents: {    defaults: {      model: {        primary: "ollama/gemma4",        fallbacks: ["ollama/kimi-k2.5:cloud"],      },    },  },}

Gunakan ID provider khusus ketika Anda memiliki lebih dari satu server Ollama. Setiap provider mendapatkan host, model, autentikasi, batas waktu, dan referensi modelnya 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"],      },    },  },}

Ketika OpenClaw mengirim permintaan, prefiks provider aktif dihapus sehingga ollama-large/qwen3.5:27b sampai ke Ollama sebagai qwen3.5:27b.

Beberapa model lokal dapat menjawab prompt sederhana tetapi kesulitan dengan seluruh permukaan alat agent. Mulailah dengan membatasi 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 secara andal gagal pada skema alat. Ini menukar kemampuan agent dengan stabilitas. localModelLean menghapus browser, cron, dan alat pesan dari permukaan agent langsung serta secara default menempatkan katalog yang lebih besar di balik kontrol Tool Search terstruktur kecuali ketika sebuah run harus mempertahankan semantik pengiriman pesan langsung, tetapi tidak mengubah konteks runtime atau mode berpikir Ollama. Pasangkan dengan params.num_ctx eksplisit dan params.thinking: false untuk model berpikir kecil bergaya Qwen yang berulang atau menghabiskan anggaran responsnya pada penalaran tersembunyi.

Jika Anda perlu menggunakan endpoint kompatibel OpenAI sebagai gantinya (misalnya, di belakang proxy yang hanya mendukung format OpenAI), tetapkan api: "openai-completions" secara eksplisit:

{  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 streaming dan pemanggilan alat secara bersamaan. Anda mungkin perlu menonaktifkan streaming dengan params: { streaming: false } dalam konfigurasi model.

Ketika api: "openai-completions" digunakan dengan Ollama, OpenClaw menyuntikkan options.num_ctx secara default sehingga Ollama tidak diam-diam kembali ke jendela konteks 4096. Jika proxy/upstream Anda menolak field options yang tidak dikenal, nonaktifkan perilaku ini:

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

Untuk model yang ditemukan otomatis, OpenClaw menggunakan jendela konteks yang dilaporkan oleh Ollama jika tersedia, termasuk nilai PARAMETER num_ctx yang lebih besar dari Modelfile khusus. Jika tidak, OpenClaw kembali ke jendela konteks default Ollama yang digunakan oleh OpenClaw.

Anda dapat menetapkan default contextWindow, contextTokens, dan maxTokens tingkat penyedia untuk setiap model di bawah penyedia Ollama tersebut, lalu menimpanya per model saat diperlukan. contextWindow adalah anggaran prompt dan Compaction OpenClaw. Permintaan Ollama native membiarkan options.num_ctx tidak disetel kecuali Anda secara eksplisit mengonfigurasi params.num_ctx, sehingga Ollama dapat menerapkan default model, OLLAMA_CONTEXT_LENGTH, atau berbasis VRAM miliknya sendiri. Untuk membatasi atau memaksa konteks runtime per permintaan Ollama tanpa membangun ulang Modelfile, setel params.num_ctx; nilai tidak valid, nol, negatif, dan non-finite diabaikan. Jika Anda memutakhirkan konfigurasi lama yang hanya menggunakan contextWindow atau maxTokens untuk memaksa konteks permintaan Ollama native, jalankan openclaw doctor --fix untuk menyalin anggaran penyedia atau model eksplisit tersebut ke params.num_ctx. Adapter Ollama kompatibel OpenAI tetap menyuntikkan options.num_ctx secara default dari params.num_ctx atau contextWindow yang dikonfigurasi; nonaktifkan dengan injectNumCtxForOpenAICompat: false jika upstream Anda menolak options.

Entri model Ollama native juga menerima opsi runtime Ollama umum di bawah params, termasuk temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread, dan use_mmap. OpenClaw hanya meneruskan kunci permintaan Ollama, sehingga parameter runtime OpenClaw seperti streaming tidak dibocorkan ke Ollama. Gunakan params.think atau params.thinking untuk mengirim think Ollama tingkat atas; false menonaktifkan thinking tingkat API untuk model thinking 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. Jika keduanya dikonfigurasi, entri model penyedia eksplisit menang atas default agent.

Untuk model Ollama native, OpenClaw meneruskan kontrol thinking sebagaimana diharapkan Ollama: think tingkat atas, bukan options.think. Model yang ditemukan otomatis dengan respons /api/show yang menyertakan kapabilitas thinking mengekspos /think low, /think medium, /think high, dan /think max; model non-thinking hanya mengekspos /think off.

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

Anda juga dapat menetapkan default model:

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

params.think atau params.thinking per model dapat menonaktifkan atau memaksa thinking API Ollama untuk model terkonfigurasi tertentu. OpenClaw mempertahankan parameter model eksplisit tersebut saat run aktif hanya memiliki default implisit off; perintah runtime selain off seperti /think medium tetap menimpa run aktif.

OpenClaw memperlakukan model dengan nama seperti deepseek-r1, reasoning, atau think sebagai berkapabilitas reasoning secara default.

ollama pull deepseek-r1:32b

Tidak diperlukan konfigurasi tambahan. OpenClaw menandainya secara otomatis.

Ollama gratis dan berjalan secara lokal, sehingga semua biaya model disetel ke $0. Ini berlaku untuk model yang ditemukan otomatis maupun yang didefinisikan secara manual.

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

Saat proxy.enabled=true, permintaan embedding memori Ollama ke origin local loopback host yang tepat yang diturunkan dari baseUrl yang dikonfigurasi menggunakan jalur langsung terlindungi OpenClaw alih-alih proxy terusan terkelola. Nama host yang dikonfigurasi itu sendiri harus berupa localhost atau literal IP loopback; nama DNS yang hanya resolve ke loopback tetap menggunakan jalur proxy terkelola. Host Ollama LAN, tailnet, jaringan privat, dan publik juga tetap berada di jalur proxy terkelola. Redirect ke host atau port lain tidak mewarisi kepercayaan. Operator masih dapat menetapkan pengaturan global proxy.loopbackMode: "proxy" untuk mengirim traffic loopback melalui proxy, atau proxy.loopbackMode: "block" untuk menolak koneksi loopback sebelum membuka koneksi; lihat Proxy terkelola untuk dampak seluruh proses dari pengaturan ini.

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

Untuk memilih Ollama sebagai penyedia embedding pencarian memori:

{  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, pertahankan auth terbatas pada host tersebut:

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

Integrasi Ollama OpenClaw menggunakan API Ollama native (/api/chat) secara default, yang sepenuhnya mendukung streaming dan tool calling secara bersamaan. Tidak diperlukan konfigurasi khusus.

Untuk permintaan /api/chat native, OpenClaw juga meneruskan kontrol thinking langsung ke Ollama: /think off dan openclaw agent --thinking off mengirim think: false tingkat atas kecuali nilai model eksplisit params.think/params.thinking dikonfigurasi, sementara /think low|medium|high mengirim string effort think tingkat atas yang sesuai. /think max dipetakan ke effort native tertinggi Ollama, think: "high".

Pada WSL2 dengan NVIDIA/CUDA, installer Linux resmi Ollama membuat unit systemd ollama.service dengan Restart=always. Jika layanan tersebut autostart dan memuat model berbasis GPU saat boot WSL2, Ollama dapat menahan memori host saat model dimuat. Reklaim memori Hyper-V tidak selalu dapat mereklaim halaman yang tertahan tersebut, sehingga Windows dapat menghentikan VM WSL2, systemd memulai Ollama lagi, dan loop berulang.

Bukti umum:

• reboot atau penghentian WSL2 berulang dari sisi Windows
• CPU tinggi di app.slice atau ollama.service sesaat setelah startup WSL2
• SIGTERM dari systemd, bukan peristiwa OOM-killer Linux

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

Mitigasi:

sudo systemctl disable ollama

Tambahkan ini ke %USERPROFILE%\.wslconfig di sisi Windows, lalu jalankan wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

Setel keep-alive yang lebih pendek di lingkungan layanan Ollama, atau mulai Ollama secara manual hanya saat Anda membutuhkannya:

export OLLAMA_KEEP_ALIVE=5mollama serve

Lihat ollama/ollama#11317.

Pastikan Ollama berjalan dan Anda menyetel OLLAMA_API_KEY (atau profil auth), dan Anda tidak mendefinisikan entri eksplisit models.providers.ollama:

ollama serve

Verifikasi bahwa API dapat diakses:

curl http://localhost:11434/api/tags

Jika model Anda tidak tercantum, tarik model secara lokal atau definisikan secara eksplisit di models.providers.ollama.

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

Periksa bahwa Ollama berjalan pada port yang benar:

# Check if Ollama is runningps aux | grep ollama # Or restart Ollamaollama serve

Verifikasi dari mesin dan runtime yang sama yang menjalankan Gateway:

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

Penyebab umum:

• baseUrl menunjuk ke localhost, tetapi Gateway berjalan di Docker atau pada host lain.
• URL menggunakan /v1, yang memilih perilaku kompatibel OpenAI alih-alih Ollama native.
• Host jarak jauh memerlukan perubahan firewall atau binding LAN di sisi Ollama.
• Model ada di daemon laptop Anda tetapi tidak di daemon jarak jauh.

Ini biasanya berarti penyedia menggunakan mode kompatibel OpenAI atau model tidak dapat menangani skema tool.

Lebih disarankan mode Ollama native:

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

Jika model lokal kecil masih gagal pada skema tool, setel compat.supportsTools: false pada entri model tersebut dan uji ulang.

Respons Kimi/GLM hosted yang panjang dan berupa rangkaian simbol non-linguistik diperlakukan sebagai output penyedia yang gagal, bukan jawaban asisten yang berhasil. Ini memungkinkan retry, fallback, atau penanganan error normal mengambil alih tanpa menyimpan teks rusak ke dalam sesi.

Jika terjadi berulang kali, tangkap nama model mentah, file sesi saat ini, dan apakah run 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 besar dapat membutuhkan pemuatan pertama yang lama sebelum streaming dimulai. Pertahankan timeout terbatas pada penyedia Ollama, dan secara opsional minta Ollama mempertahankan model tetap dimuat antar turn:

{  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 Undici yang dijaga untuk penyedia ini.

Banyak model Ollama mengiklankan konteks yang lebih besar daripada yang dapat dijalankan perangkat keras Anda dengan nyaman. Ollama native menggunakan default konteks runtime Ollama sendiri kecuali Anda mengatur params.num_ctx. Batasi anggaran OpenClaw dan konteks permintaan Ollama ketika Anda menginginkan 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 terlebih dahulu jika OpenClaw mengirim prompt terlalu banyak. Turunkan params.num_ctx jika Ollama memuat konteks runtime yang terlalu besar untuk mesin. Turunkan maxTokens jika pembuatan berjalan terlalu lama.