Langsung ke konten utama
OpenClaw terintegrasi dengan API native Ollama (/api/chat) untuk model cloud yang dihosting dan server Ollama lokal/self-hosted. Anda dapat menggunakan Ollama dalam tiga mode: Cloud + Local melalui host Ollama yang dapat dijangkau, Cloud only terhadap https://ollama.com, atau Local only terhadap host Ollama yang dapat dijangkau. OpenClaw juga mendaftarkan ollama-cloud sebagai id penyedia terhosting kelas utama untuk penggunaan Ollama Cloud langsung. Gunakan ref seperti ollama-cloud/kimi-k2.5:cloud ketika Anda menginginkan perutean khusus cloud tanpa berbagi id penyedia ollama lokal. Untuk halaman penyiapan khusus cloud saja, lihat Ollama Cloud.
Pengguna Ollama jarak jauh: Jangan gunakan URL kompatibel OpenAI /v1 (http://host:11434/v1) dengan OpenClaw. Ini merusak pemanggilan tool dan model dapat mengeluarkan JSON tool mentah sebagai teks biasa. Gunakan URL API native Ollama sebagai gantinya: baseUrl: "http://host:11434" (tanpa /v1).
Konfigurasi penyedia Ollama menggunakan baseUrl sebagai kunci kanonis. OpenClaw juga menerima baseURL untuk kompatibilitas dengan contoh bergaya SDK OpenAI, tetapi konfigurasi baru sebaiknya menggunakan baseUrl.

​
Aturan auth

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.

​
Memulai

Pilih metode dan mode penyiapan yang Anda inginkan.
Terbaik untuk: jalur tercepat ke penyiapan cloud atau lokal Ollama yang berfungsi.
1

Jalankan onboarding

openclaw onboard
Pilih Ollama dari daftar penyedia.
2

Pilih mode Anda

  • Cloud + Lokal — host Ollama lokal plus model cloud yang dirutekan melalui host tersebut
  • Cloud saja — model Ollama terhosting melalui https://ollama.com
  • Lokal saja — hanya model lokal
3

Pilih model

Cloud only meminta OLLAMA_API_KEY dan menyarankan default cloud terhosting. Cloud + Local dan Local only meminta URL dasar Ollama, menemukan model yang tersedia, dan menarik otomatis model lokal yang dipilih jika belum tersedia. Ketika Ollama melaporkan tag :latest yang terpasang seperti gemma4:latest, penyiapan menampilkan model terpasang itu sekali alih-alih menampilkan gemma4 dan gemma4:latest atau menarik alias polos lagi. Cloud + Local juga memeriksa apakah host Ollama tersebut sudah masuk untuk akses cloud.
4

Verifikasi model tersedia

openclaw models list --provider ollama

​
Mode non-interaktif

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk
Secara opsional tentukan URL dasar atau model kustom:
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

​
Model cloud

Cloud + Local menggunakan host Ollama yang dapat dijangkau sebagai titik kontrol untuk model lokal dan cloud. Ini adalah alur hibrida pilihan Ollama.Gunakan Cloud + Lokal selama penyiapan. OpenClaw meminta URL dasar Ollama, menemukan model lokal dari host tersebut, dan memeriksa apakah host sudah masuk untuk akses cloud dengan ollama signin. Ketika host sudah masuk, OpenClaw juga menyarankan default cloud terhosting seperti kimi-k2.5:cloud, minimax-m2.7:cloud, dan glm-5.1:cloud.Jika host belum masuk, OpenClaw mempertahankan penyiapan lokal saja sampai Anda menjalankan ollama signin.

​
Penemuan model (penyedia implisit)

Ketika Anda menetapkan OLLAMA_API_KEY (atau profil auth) dan tidak mendefinisikan models.providers.ollama atau penyedia jarak jauh kustom lain dengan api: "ollama", OpenClaw menemukan model dari instans Ollama lokal di http://127.0.0.1:11434.
PerilakuDetail
Kueri katalogMengueri /api/tags
Deteksi kapabilitasMenggunakan lookup best-effort /api/show untuk membaca contextWindow, parameter Modelfile num_ctx yang diperluas, dan kapabilitas termasuk vision/tools
Model visionModel dengan kapabilitas vision yang dilaporkan oleh /api/show ditandai sebagai mampu gambar (input: ["text", "image"]), sehingga OpenClaw menyuntikkan gambar otomatis ke prompt
Deteksi penalaranMenggunakan kapabilitas /api/show jika tersedia, termasuk thinking; fallback ke heuristik nama model (r1, reasoning, think) ketika Ollama menghilangkan kapabilitas
Batas tokenMenetapkan maxTokens ke batas token maksimum default Ollama yang digunakan oleh OpenClaw
BiayaMenetapkan semua biaya ke 0
Ini menghindari entri model manual sembari menjaga katalog tetap selaras dengan instans Ollama lokal. Anda dapat menggunakan ref lengkap seperti ollama/<pulled-model>:latest di infer model run lokal; OpenClaw menyelesaikan model terpasang itu dari katalog langsung Ollama tanpa memerlukan entri models.json yang ditulis tangan. Untuk host Ollama yang sudah masuk, beberapa model :cloud dapat digunakan melalui /api/chat dan /api/show sebelum muncul di /api/tags. Ketika Anda secara eksplisit memilih ref lengkap ollama/<model>:cloud, OpenClaw memvalidasi model yang hilang persis itu dengan /api/show dan menambahkannya ke katalog runtime hanya jika Ollama mengonfirmasi metadata model. Salah ketik tetap gagal sebagai model tidak dikenal alih-alih dibuat otomatis. 
# See what models are available
ollama list
openclaw models list
Untuk uji smoke pembuatan teks sempit yang menghindari seluruh permukaan tool agen, gunakan infer model run lokal dengan ref model Ollama lengkap: 
OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/llama3.2:latest \
    --prompt "Reply with exactly: pong" \
    --json
Jalur itu tetap menggunakan penyedia, auth, dan transport native Ollama yang dikonfigurasi OpenClaw, tetapi tidak memulai giliran agen chat atau memuat konteks MCP/tool. Jika ini berhasil sementara balasan agen normal gagal, selidiki kapasitas prompt/tool agen model berikutnya. Untuk uji smoke model vision yang sempit pada jalur ramping yang sama, tambahkan satu atau beberapa file gambar ke infer model run. Ini mengirim prompt dan gambar langsung ke model vision Ollama yang dipilih tanpa memuat tool chat, memori, atau konteks sesi sebelumnya: 
OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/qwen2.5vl:7b \
    --prompt "Describe this image in one sentence." \
    --file ./photo.jpg \
    --json
model run --file menerima file yang terdeteksi sebagai image/*, termasuk input PNG, JPEG, dan WebP umum. File non-gambar ditolak sebelum Ollama dipanggil. Untuk pengenalan ucapan, gunakan openclaw infer audio transcribe sebagai gantinya. Saat Anda mengalihkan percakapan dengan /model ollama/<model>, OpenClaw memperlakukannya sebagai pilihan pengguna yang persis. Jika baseUrl Ollama yang dikonfigurasi tidak dapat dijangkau, balasan berikutnya gagal dengan galat penyedia alih-alih diam-diam menjawab dari model fallback lain yang dikonfigurasi. Pekerjaan cron terisolasi menjalankan satu pemeriksaan keamanan lokal tambahan sebelum memulai giliran agen. Jika model yang dipilih terselesaikan ke penyedia Ollama lokal, jaringan privat, atau .local dan /api/tags tidak dapat dijangkau, OpenClaw mencatat run cron tersebut sebagai skipped dengan ollama/<model> yang dipilih dalam teks galat. Preflight endpoint di-cache selama 5 menit, sehingga beberapa pekerjaan cron yang diarahkan ke daemon Ollama yang sama-sama berhenti tidak semuanya meluncurkan permintaan model yang gagal. Verifikasi langsung jalur teks lokal, jalur stream native, dan embeddings terhadap Ollama lokal dengan: 
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
  pnpm test:live -- extensions/ollama/ollama.live.test.ts
Untuk smoke test kunci API Ollama Cloud, arahkan pengujian langsung ke https://ollama.com dan pilih model hosted dari katalog saat ini: 
export OLLAMA_API_KEY='<your-ollama-cloud-api-key>'

OPENCLAW_LIVE_TEST=1 \
OPENCLAW_LIVE_OLLAMA=1 \
OPENCLAW_LIVE_OLLAMA_BASE_URL=https://ollama.com \
OPENCLAW_LIVE_OLLAMA_MODEL=glm-5.1:cloud \
OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=1 \
pnpm test:live -- extensions/ollama/ollama.live.test.ts
Smoke cloud menjalankan teks, stream native, dan pencarian web. Secara default, embeddings dilewati untuk https://ollama.com karena kunci API Ollama Cloud mungkin tidak mengotorisasi /api/embed. Atur OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1 saat Anda secara eksplisit ingin pengujian langsung gagal jika kunci cloud yang dikonfigurasi tidak dapat menggunakan endpoint embed. Untuk menambahkan model baru, cukup pull model tersebut dengan Ollama: 
ollama pull mistral
Model baru akan otomatis ditemukan dan tersedia untuk digunakan.
Jika Anda mengatur models.providers.ollama secara eksplisit, atau mengonfigurasi penyedia jarak jauh khusus seperti models.providers.ollama-cloud dengan api: "ollama", penemuan otomatis dilewati dan Anda harus mendefinisikan model secara manual. Penyedia khusus loopback seperti http://127.0.0.2:11434 tetap diperlakukan sebagai lokal. Lihat bagian konfigurasi eksplisit di bawah.

​
Inferensi lokal Node

Agen dapat mendelegasikan tugas singkat ke model Ollama yang terpasang pada node desktop atau server yang dipasangkan. Prompt dan respons melintasi koneksi Gateway/node terautentikasi yang sudah ada; permintaan model berjalan pada node yang dipilih terhadap endpoint Ollama loopback standarnya (http://127.0.0.1:11434).
1

Start Ollama on the node

Pull setidaknya satu model chat dan biarkan Ollama tetap berjalan:
ollama pull qwen3:0.6b
ollama list
2

Connect the node host

Pada mesin yang sama dengan Ollama, hubungkan host node ke Gateway:
openclaw node run \
  --host <gateway-host> \
  --port 18789 \
  --display-name "Local inference"
Setujui perangkat baru dan perintah node yang dideklarasikannya pada host Gateway, lalu verifikasi node:
openclaw devices list
openclaw devices approve <deviceRequestId>
openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes status --connected
Koneksi pertama dan upgrade yang menambahkan perintah Ollama sama-sama dapat memicu persetujuan perintah node. Jika node terhubung tanpa mengiklankan ollama.models dan ollama.chat, periksa openclaw nodes pending lagi.
3

Ask an agent to use local inference

Plugin Ollama bawaan mengekspos tool node_inference. Agen terlebih dahulu menggunakan action: "discover", lalu action: "run" dengan node dan model yang dikembalikan. Jika tepat satu node yang mampu terhubung, run dapat menghilangkan node.Misalnya: “Temukan model Ollama pada node saya, lalu gunakan model termuat tercepat untuk merangkum teks ini.”
Penemuan membaca /api/tags, memeriksa kapabilitas /api/show, dan menggunakan /api/ps saat tersedia untuk memberi peringkat model yang sudah termuat terlebih dahulu. Ini hanya mengembalikan model lokal yang mampu chat: baris Ollama Cloud dan model khusus embedding dikecualikan. Setiap run meminta Ollama menonaktifkan thinking model dan membatasi output pada 512 token kecuali pemanggilan tool meminta nilai maxTokens yang berbeda. Beberapa model, seperti GPT-OSS, tidak mendukung penonaktifan thinking dan mungkin tetap menggunakan token penalaran. Untuk membiarkan Ollama tetap berjalan pada node tanpa membuatnya tersedia bagi agen, atur hal berikut dalam konfigurasi yang digunakan oleh host node tersebut: 
openclaw config set plugins.entries.ollama.config.nodeInference.enabled false
Jika node menggunakan perintah foreground openclaw node run dari pengaturan di atas, hentikan proses tersebut dan jalankan perintahnya lagi. Jika menggunakan layanan node terpasang, jalankan openclaw node restart. Node berhenti mengiklankan ollama.models dan ollama.chat; Ollama sendiri dan penyedia Ollama milik Gateway tetap tidak berubah. Atur nilainya ke true dan mulai ulang node untuk mengiklankan inferensi lokal lagi. Permukaan perintah yang berubah mungkin memerlukan persetujuan melalui openclaw nodes pending setelah tersambung ulang. Anda dapat memverifikasi perintah node yang sama tanpa giliran agen: 
openclaw nodes invoke \
  --node "Local inference" \
  --command ollama.models \
  --params '{}' \
  --invoke-timeout 90000 \
  --timeout 100000

openclaw nodes invoke \
  --node "Local inference" \
  --command ollama.chat \
  --params '{"model":"qwen3:0.6b","prompt":"Reply with exactly: pong","maxTokens":32,"timeoutMs":120000}' \
  --invoke-timeout 130000 \
  --timeout 140000
Inferensi lokal node sengaja tidak menggunakan kembali models.providers.ollama.baseUrl jarak jauh atau cloud. Jalankan Ollama pada endpoint loopback standar node. Perintah node tersedia secara default pada host node macOS, Linux, dan Windows serta tetap tunduk pada kebijakan pairing node dan perintah normal.

​
Vision dan deskripsi gambar

Plugin Ollama bawaan mendaftarkan Ollama sebagai penyedia pemahaman media yang mampu menangani gambar. Ini memungkinkan OpenClaw merutekan permintaan deskripsi gambar eksplisit dan default model gambar yang dikonfigurasi melalui model vision Ollama lokal atau hosted. Untuk vision lokal, pull model yang mendukung gambar: 
ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"
Lalu verifikasi dengan CLI infer: 
openclaw infer image describe \
  --file ./photo.jpg \
  --model ollama/qwen2.5vl:7b \
  --json
--model harus berupa ref <provider/model> lengkap. Saat diatur, openclaw infer image describe mencoba model tersebut terlebih dahulu alih-alih melewati deskripsi karena model mendukung vision native. Jika pemanggilan model gagal, OpenClaw dapat melanjutkan melalui agents.defaults.imageModel.fallbacks yang dikonfigurasi; galat persiapan file atau URL tetap gagal sebelum percobaan fallback. Gunakan infer image describe saat Anda menginginkan alur penyedia pemahaman gambar OpenClaw, agents.defaults.imageModel yang dikonfigurasi, dan bentuk output deskripsi gambar. Gunakan infer model run --file saat Anda menginginkan probe model multimodal mentah dengan prompt khusus dan satu atau beberapa gambar. Untuk menjadikan Ollama sebagai model pemahaman gambar default untuk media masuk, konfigurasikan agents.defaults.imageModel: 
{
  agents: {
    defaults: {
      imageModel: {
        primary: "ollama/qwen2.5vl:7b",
      },
    },
  },
}
Utamakan ref lengkap ollama/<model>. Jika model yang sama tercantum di bawah models.providers.ollama.models dengan input: ["text", "image"] dan tidak ada penyedia gambar lain yang dikonfigurasi mengekspos ID model bare tersebut, OpenClaw juga menormalkan ref imageModel bare seperti qwen2.5vl:7b menjadi ollama/qwen2.5vl:7b. Jika lebih dari satu penyedia gambar yang dikonfigurasi memiliki ID bare yang sama, gunakan prefiks penyedia secara eksplisit. Model vision lokal yang lambat mungkin memerlukan timeout pemahaman gambar yang lebih panjang daripada model cloud. Model tersebut juga dapat crash atau berhenti saat Ollama mencoba mengalokasikan konteks vision penuh yang diiklankan pada perangkat keras terbatas. Atur timeout kapabilitas, dan batasi num_ctx pada entri model saat Anda hanya memerlukan giliran deskripsi gambar normal: 
{
  models: {
    providers: {
      ollama: {
        models: [
          {
            id: "qwen2.5vl:7b",
            name: "qwen2.5vl:7b",
            input: ["text", "image"],
            params: { num_ctx: 2048, keep_alive: "1m" },
          },
        ],
      },
    },
  },
  tools: {
    media: {
      image: {
        timeoutSeconds: 180,
        models: [{ provider: "ollama", model: "qwen2.5vl:7b", timeoutSeconds: 300 }],
      },
    },
  },
}
Timeout ini berlaku untuk pemahaman gambar masuk dan untuk tool image eksplisit yang dapat dipanggil agen selama giliran. models.providers.ollama.timeoutSeconds tingkat penyedia tetap mengontrol guard permintaan HTTP Ollama yang mendasarinya untuk pemanggilan model normal. Verifikasi langsung tool gambar eksplisit terhadap Ollama lokal dengan: 
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
  pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts
Jika Anda mendefinisikan models.providers.ollama.models secara manual, tandai model vision dengan dukungan input gambar: 
{
  id: "qwen2.5vl:7b",
  name: "qwen2.5vl:7b",
  input: ["text", "image"],
  contextWindow: 128000,
  maxTokens: 8192,
}
OpenClaw menolak permintaan deskripsi gambar untuk model yang tidak ditandai mampu gambar. Dengan penemuan implisit, OpenClaw membaca ini dari Ollama saat /api/show melaporkan kapabilitas vision.

​
Konfigurasi

Jalur pengaktifan paling sederhana untuk lokal saja adalah melalui variabel lingkungan:
export OLLAMA_API_KEY="ollama-local"
Jika OLLAMA_API_KEY diatur, Anda dapat menghilangkan apiKey dalam entri penyedia dan OpenClaw akan mengisinya untuk pemeriksaan ketersediaan.

​
Resep umum

Gunakan ini sebagai titik awal dan ganti ID model dengan nama persis dari ollama list atau openclaw models list --provider ollama.
Gunakan ini ketika Ollama berjalan pada 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 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 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 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.

​
Pemilihan model

Setelah dikonfigurasi, semua model Ollama Anda tersedia: 
{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}
ID provider Ollama khusus juga didukung. Ketika referensi model menggunakan prefiks provider aktif, seperti ollama-spark/qwen3:32b, OpenClaw hanya menghapus prefiks tersebut sebelum memanggil Ollama sehingga server menerima qwen3:32b. Untuk model lokal yang lambat, utamakan penyetelan permintaan dalam cakupan provider sebelum menaikkan batas waktu runtime seluruh agent: 
{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}
timeoutSeconds berlaku untuk permintaan HTTP model, termasuk penyiapan koneksi, header, streaming body, dan total pembatalan guarded-fetch. params.keep_alive diteruskan ke Ollama sebagai keep_alive tingkat atas pada permintaan /api/chat native; tetapkan per model ketika waktu pemuatan giliran pertama menjadi hambatan.

​
Verifikasi cepat

# Ollama daemon visible to this machine
curl http://127.0.0.1:11434/api/tags

# OpenClaw catalog and selected model
openclaw models list --provider ollama
openclaw models status

# Direct model smoke
openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Reply with exactly: ok"
Untuk host jarak jauh, ganti 127.0.0.1 dengan host yang digunakan di baseUrl. Jika curl berfungsi tetapi OpenClaw tidak, periksa apakah Gateway berjalan pada mesin, kontainer, atau akun layanan yang berbeda. OpenClaw mendukung Ollama Web Search sebagai provider web_search bawaan.
PropertiDetail
HostMenggunakan host Ollama yang Anda konfigurasi (models.providers.ollama.baseUrl jika ditetapkan, jika tidak http://127.0.0.1:11434); https://ollama.com menggunakan API terhosting secara langsung
AutentikasiTanpa kunci untuk host Ollama lokal yang sudah masuk; OLLAMA_API_KEY atau autentikasi provider yang dikonfigurasi untuk pencarian langsung https://ollama.com atau host yang dilindungi autentikasi
PersyaratanHost lokal/self-hosted harus berjalan dan masuk dengan ollama signin; pencarian terhosting langsung memerlukan baseUrl: "https://ollama.com" plus kunci API Ollama nyata
Pilih Ollama Web Search selama openclaw onboard atau openclaw configure --section web, atau tetapkan: 
{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}
Untuk pencarian terhosting langsung melalui Ollama Cloud: 
{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [{ id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text"] }],
      },
    },
  },
  tools: {
    web: {
      search: { provider: "ollama" },
    },
  },
}
Untuk daemon lokal yang sudah masuk, OpenClaw menggunakan proxy /api/experimental/web_search milik daemon. Untuk https://ollama.com, OpenClaw memanggil endpoint terhosting /api/web_search secara langsung.
Untuk penyiapan lengkap dan detail perilaku, lihat Ollama Web Search.

​
Konfigurasi lanjutan

Pemanggilan alat tidak andal dalam mode kompatibel OpenAI. Gunakan mode ini hanya jika Anda memerlukan format OpenAI untuk proxy dan tidak bergantung pada perilaku pemanggilan alat native.
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 off
openclaw 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.
PropertiNilai
Model defaultnomic-embed-text
Auto-pullYa — model embedding ditarik secara otomatis jika belum ada secara lokal
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".
Jika Anda perlu menggunakan endpoint kompatibel OpenAI, lihat bagian “Mode kompatibel OpenAI lama” di atas. Streaming dan tool calling mungkin tidak berfungsi secara bersamaan dalam mode tersebut.

​
Pemecahan masalah

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=5m
ollama 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 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 yang menjalankan Gateway:
openclaw gateway status --deep
curl 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" --json
openclaw 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.
Bantuan lebih lanjut: Pemecahan masalah dan FAQ.

​
Terkait

Penyedia model

Ikhtisar semua penyedia, referensi model, dan perilaku failover.

Pemilihan model

Cara memilih dan mengonfigurasi model.

Ollama Web Search

Penyiapan lengkap dan detail perilaku untuk pencarian web yang didukung Ollama.

Konfigurasi

Referensi konfigurasi lengkap.