Ollama

Host Ollama lokal dan LAN tidak memerlukan token bearer nyata. OpenClaw menggunakan penanda lokal ollama-local hanya untuk URL dasar Ollama loopback, jaringan privat, .local, dan bare-hostname.

Host publik jarak jauh dan Ollama Cloud (https://ollama.com) memerlukan kredensial nyata melalui OLLAMA_API_KEY, profil autentikasi, atau apiKey milik penyedia.

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 tersebut 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>. Berkas profil autentikasi 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 berkas itu adalah derau kompatibilitas dan sebaiknya dipindahkan ke konfigurasi penyedia.

Saat Ollama digunakan untuk embedding memori, autentikasi bearer dibatasi pada 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 di-host sendiri secara default.

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

ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw 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 sisi OpenClaw. params.num_ctx dikirim ke Ollama untuk permintaan. Jaga keduanya tetap selaras saat perangkat keras Anda tidak dapat menjalankan konteks penuh yang diiklankan oleh model.

Gunakan ini saat Anda tidak menjalankan daemon lokal dan ingin model Ollama ter-host 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 saat daemon Ollama lokal atau LAN sudah masuk dengan ollama signin dan harus melayani model lokal serta model :cloud.

ollama signin
ollama 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 penyedia khusus saat Anda memiliki lebih dari satu server Ollama. Setiap penyedia mendapatkan host, model, auth, timeout, dan ref 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"],
      },
    },
  },
}

Saat OpenClaw mengirim permintaan, prefiks penyedia aktif dihapus sehingga ollama-large/qwen3.5:27b mencapai Ollama sebagai qwen3.5:27b.

Beberapa model lokal dapat menjawab prompt sederhana tetapi kesulitan dengan seluruh permukaan tool agen. Mulailah dengan membatasi tool dan konteks sebelum mengubah pengaturan runtime global.

{
  agents: {
    defaults: {
      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 kapabilitas agen dengan stabilitas. localModelLean menghapus alat peramban, cron, dan pesan dari permukaan agen, 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 untuk penalaran tersembunyi.

Jika Anda perlu menggunakan endpoint kompatibel OpenAI sebagai gantinya (misalnya, di balik proxy yang hanya mendukung format OpenAI), atur 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 kolom 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 kustom. Jika tidak, OpenClaw kembali ke jendela konteks default Ollama yang digunakan oleh OpenClaw.

Anda dapat mengatur 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 native Ollama membiarkan options.num_ctx tidak diatur kecuali Anda secara eksplisit mengonfigurasi params.num_ctx, sehingga Ollama dapat menerapkan default berdasarkan modelnya sendiri, OLLAMA_CONTEXT_LENGTH, atau VRAM. Untuk membatasi atau memaksa konteks runtime per permintaan Ollama tanpa membangun ulang Modelfile, atur params.num_ctx; nilai tidak valid, nol, negatif, dan non-finite diabaikan. 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 native Ollama juga menerima opsi runtime umum Ollama 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 bocor ke Ollama. Gunakan params.think atau params.thinking untuk mengirim think Ollama tingkat atas; false menonaktifkan berpikir 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. Jika keduanya dikonfigurasi, entri model penyedia eksplisit menang atas default agen.

Untuk model native Ollama, OpenClaw meneruskan kontrol berpikir sesuai yang 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-berpikir hanya mengekspos /think off.

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

Anda juga dapat mengatur default model:

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

params.think atau params.thinking per model dapat menonaktifkan atau memaksa berpikir API Ollama untuk model tertentu yang dikonfigurasi. OpenClaw mempertahankan parameter model eksplisit tersebut ketika proses aktif hanya memiliki default implisit off; perintah runtime non-off seperti /think medium tetap menimpa proses aktif.

OpenClaw memperlakukan model dengan nama seperti deepseek-r1, reasoning, atau think sebagai berkemampuan penalaran 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 diatur ke $0. Ini berlaku untuk model yang ditemukan otomatis maupun yang didefinisikan manual.

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

Embedding waktu 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 dalam cakupan 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 pemanggilan alat secara bersamaan. Tidak diperlukan konfigurasi khusus.

Untuk permintaan /api/chat native, OpenClaw juga meneruskan kontrol penalaran 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 upaya think tingkat atas yang sesuai. /think max dipetakan ke upaya 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 dimulai otomatis dan memuat model berbasis GPU saat boot WSL2, Ollama dapat menahan memori host saat model dimuat. Reklaim memori Hyper-V tidak selalu dapat mereklamasi 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 WSL2 dimulai
• SIGTERM dari systemd, bukan peristiwa OOM-killer Linux

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

Mitigasi:

sudo systemctl disable ollama

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

[experimental]
autoMemoryReclaim=disabled

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

export OLLAMA_KEEP_ALIVE=5m
ollama serve

Lihat ollama/ollama#11317.

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

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 installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model

Periksa bahwa Ollama berjalan pada port yang benar:

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve

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

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

Penyebab umum:

• baseUrl mengarah 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 tersedia di daemon laptop Anda tetapi tidak di daemon jarak jauh.

Ini biasanya berarti provider menggunakan mode kompatibel OpenAI atau model tidak dapat menangani skema alat.

Utamakan mode Ollama native:

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

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

Respons Kimi/GLM yang di-hosting yang panjang dan berupa rangkaian simbol nonlinguistik diperlakukan sebagai output provider yang gagal, bukan sebagai jawaban asisten yang berhasil. Ini memungkinkan retry, fallback, atau penanganan kesalahan normal mengambil alih tanpa menyimpan teks rusak tersebut ke dalam sesi.

Jika ini terjadi berulang kali, ambil nama model mentah, 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 "Reply with exactly: ok" --json
openclaw models set ollama/gemma4

Model lokal besar dapat memerlukan pemuatan pertama yang lama sebelum streaming dimulai. Batasi timeout hanya pada provider Ollama, dan secara opsional minta Ollama menjaga model tetap dimuat antar 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 timeout koneksi Undici yang dijaga untuk provider 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 menetapkan 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 terlalu banyak prompt. Turunkan params.num_ctx jika Ollama memuat konteks runtime yang terlalu besar untuk mesin. Turunkan maxTokens jika generasi berjalan terlalu lama.