Ollama

OpenClaw berkomunikasi dengan API native Ollama (/api/chat), bukan endpoint yang kompatibel dengan OpenAI /v1. Tiga mode didukung:

Mode	Yang digunakan
Cloud + Lokal	Host Ollama yang dapat dijangkau, menyajikan model lokal dan (jika sudah masuk) model `:cloud`
Hanya cloud	`https://ollama.com` secara langsung, tanpa daemon lokal
Hanya lokal	Host Ollama yang dapat dijangkau, hanya model lokal

Untuk penyiapan khusus cloud dengan id penyedia khusus ollama-cloud, lihat Ollama Cloud. Gunakan referensi ollama-cloud/<model> jika Anda ingin perutean cloud tetap terpisah dari penyedia lokal ollama.

Jangan gunakan URL /v1 yang kompatibel dengan OpenAI (http://host:11434/v1). URL tersebut merusak pemanggilan alat dan model dapat mengeluarkan JSON pemanggilan alat mentah sebagai teks biasa. Gunakan URL native: baseUrl: "http://host:11434" (tanpa /v1).

Kunci konfigurasi kanonis adalah baseUrl. baseURL juga diterima untuk contoh bergaya OpenAI SDK, tetapi konfigurasi baru harus menggunakan baseUrl.

Aturan autentikasi

Host lokal dan LAN

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 dan Ollama Cloud

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.

Id penyedia khusus

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.

Profil autentikasi

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.

Cakupan embedding memori

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.

Memulai

Orientasi (direkomendasikan)
Penyiapan manual

Jalankan orientasi

openclaw onboard

Pilih Ollama, lalu pilih mode: Cloud + Lokal, Hanya cloud, atau Hanya lokal.Pada penyiapan terpandu baru, OpenClaw terlebih dahulu memeriksa host Ollama default atau yang dikonfigurasi. Model yang terinstal hanya ditawarkan secara otomatis ketika /api/show mengonfirmasi dukungan alat dan jendela konteks minimal 16K; metadata konteks yang hilang atau lebih kecil tetap menggunakan jalur penyiapan manual. Tahapan penyiapan CLI/macOS bersama tetap memverifikasi rute yang dipilih dengan completion nyata sebelum menyimpannya. Pemeriksaan otomatis ini tidak pernah menarik model; jika tidak ada model terinstal yang sesuai, orientasi berlanjut ke pemilih Ollama normal.

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 secara otomatis menarik model lokal yang dipilih jika belum tersedia. Tag :latest yang terinstal seperti gemma4:latest ditampilkan sekali alih-alih menduplikasi gemma4. Cloud + Local juga memeriksa apakah host sudah masuk untuk akses cloud.

Verifikasi

openclaw models list --provider ollama

Noninteraktif:

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

--custom-base-url dan --custom-model-id bersifat opsional; jika dihilangkan, host lokal default dan model yang disarankan gemma4 akan digunakan.

Instal dan jalankan Ollama

Dapatkan dari ollama.com/download, lalu tarik model:

ollama pull gemma4

Untuk akses cloud hibrida, jalankan ollama signin pada host yang sama.

Tetapkan kredensial

export OLLAMA_API_KEY="ollama-local"    # host lokal/LAN, nilai apa pun dapat digunakan
export OLLAMA_API_KEY="your-real-key"   # hanya https://ollama.com

Atau dalam konfigurasi: openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY".

Pilih model

openclaw models list
openclaw models set ollama/gemma4

Atau dalam konfigurasi:

{
  agents: {
    defaults: {
      model: { primary: "ollama/gemma4" },
    },
  },
}

Model cloud melalui host lokal

Cloud + Local merutekan model lokal dan :cloud melalui satu host Ollama yang dapat dijangkau — ini adalah alur hibrida Ollama dan mode yang dipilih selama penyiapan jika Anda menginginkan keduanya. OpenClaw meminta URL dasar, menemukan model lokal, dan memeriksa status ollama signin. Setelah masuk, OpenClaw menyarankan default terhosting (kimi-k2.5:cloud, minimax-m2.7:cloud, glm-5.1:cloud, glm-5.2:cloud). Jika belum masuk, penyiapan tetap hanya lokal sampai Anda menjalankan ollama signin. Untuk akses khusus cloud tanpa daemon lokal, gunakan openclaw onboard --auth-choice ollama-cloud dan lihat Ollama Cloud — jalur tersebut tidak memerlukan ollama signin atau server yang sedang berjalan:

openclaw onboard --auth-choice ollama-cloud
openclaw models set ollama-cloud/kimi-k2.5:cloud

Daftar model cloud yang ditampilkan selama openclaw onboard diisi secara langsung dari https://ollama.com/api/tags, dibatasi hingga 500 entri, sehingga pemilih mencerminkan katalog terhosting saat ini. Jika ollama.com tidak dapat dijangkau atau tidak mengembalikan model saat penyiapan, OpenClaw kembali ke daftar saran bawaan agar orientasi tetap selesai.

Penemuan model (penyedia implisit)

Ketika OLLAMA_API_KEY (atau profil autentikasi) ditetapkan dan baik models.providers.ollama maupun penyedia khusus lain dengan api: "ollama" tidak didefinisikan, OpenClaw menemukan model dari http://127.0.0.1:11434:

Perilaku	Detail
Kueri katalog	`/api/tags`
Deteksi kemampuan	`/api/show` upaya terbaik membaca `contextWindow`, parameter Modelfile `num_ctx`, dan kemampuan (visi/alat/penalaran)
Model visi	Kemampuan `vision` dari `/api/show` menandai model sebagai mampu memproses gambar (`input: ["text", "image"]`)
Deteksi penalaran	Menggunakan kemampuan `thinking` dari `/api/show` jika tersedia; kembali ke heuristik nama (`r1`, `reason`, `reasoning`, `think`) ketika Ollama tidak menyertakan kemampuan. `glm-5.2:cloud` dan `deepseek-v4-flash\|pro:cloud` selalu dianggap sebagai model penalaran terlepas dari kemampuan yang dilaporkan.
Batas token	`maxTokens` secara default menggunakan batas maksimum token Ollama milik OpenClaw
Biaya	Semua biaya adalah `0`

ollama list
openclaw models list

Menetapkan models.providers.ollama dengan array models eksplisit, atau penyedia khusus dengan api: "ollama" dan baseUrl non-loopback, menonaktifkan penemuan otomatis; model kemudian harus didefinisikan secara manual (lihat Konfigurasi). Entri models.providers.ollama yang diarahkan ke https://ollama.com terhosting juga melewati penemuan, karena model Ollama Cloud dikelola oleh penyedia. Penyedia khusus loopback seperti http://127.0.0.2:11434 tetap dianggap lokal dan mempertahankan penemuan otomatis. Anda dapat menggunakan referensi lengkap seperti ollama/<pulled-model>:latest tanpa entri models.json yang ditulis manual; OpenClaw menyelesaikannya secara langsung. Untuk host yang sudah masuk, memilih referensi ollama/<model>:cloud yang tidak tercantum akan memvalidasi model tersebut secara persis dengan /api/show dan menambahkannya ke katalog runtime hanya jika Ollama mengonfirmasi metadata — kesalahan ketik tetap gagal sebagai model yang tidak dikenal.

Uji asap

Untuk pemeriksaan teks terbatas yang melewati seluruh permukaan alat agen:

OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/llama3.2:latest \
    --prompt "Balas persis dengan: pong" \
    --json

Tambahkan --file dengan gambar untuk pemeriksaan ringkas model visi (menerima PNG/JPEG/WebP; berkas non-gambar ditolak sebelum Ollama dipanggil — gunakan openclaw infer audio transcribe untuk audio):

OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/qwen2.5vl:7b \
    --prompt "Deskripsikan gambar ini dalam satu kalimat." \
    --file ./photo.jpg \
    --json

Kedua jalur tersebut tidak memuat alat obrolan, memori, atau konteks sesi. Jika jalur tersebut berhasil sementara balasan agen normal gagal, masalahnya kemungkinan terletak pada kapasitas alat/agen model, bukan endpoint. Memilih model dengan /model ollama/<model> merupakan pilihan pengguna yang pasti: jika baseUrl yang dikonfigurasi tidak dapat dijangkau, balasan berikutnya gagal dengan error penyedia alih-alih secara diam-diam beralih ke model lain yang dikonfigurasi. Tugas cron terisolasi menambahkan satu pemeriksaan keamanan lokal sebelum memulai giliran agen: jika model yang dipilih mengarah ke penyedia Ollama lokal/jaringan privat/.local dan /api/tags tidak dapat dijangkau, OpenClaw mencatat eksekusi tersebut sebagai skipped dengan model dalam teks error. Pemeriksaan endpoint ini disimpan dalam cache selama 5 menit per host, sehingga tugas cron berulang terhadap daemon yang berhenti tidak semuanya meluncurkan permintaan yang akan gagal. Verifikasi langsung:

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
  pnpm test:live -- extensions/ollama/ollama.live.test.ts

Untuk Ollama Cloud, arahkan pengujian langsung yang sama ke endpoint yang di-host (secara default melewati embedding; paksa dengan OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1 karena kunci cloud mungkin tidak mengizinkan /api/embed):

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

Untuk menambahkan model, tarik model tersebut dan model akan ditemukan secara otomatis:

ollama pull mistral

Inferensi lokal Node

Agen dapat mendelegasikan tugas singkat ke model Ollama pada desktop atau Node server yang telah dipasangkan. Prompt dan respons melewati koneksi Gateway/Node terautentikasi yang sudah ada; permintaan berjalan pada endpoint Ollama loopback milik Node tersebut (http://127.0.0.1:11434).

Mulai Ollama pada Node

ollama pull qwen3:0.6b
ollama list

Hubungkan host Node

openclaw node run \
  --host <gateway-host> \
  --port 18789 \
  --display-name "Local inference"

Setujui perangkat dan perintah Node-nya pada host Gateway, lalu verifikasi:

openclaw devices list
openclaw devices approve <deviceRequestId>
openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes status --connected

Koneksi pertama, atau peningkatan yang menambahkan perintah Ollama, dapat memicu persetujuan perintah Node. Jika Node terhubung tanpa mengiklankan ollama.models dan ollama.chat, periksa kembali openclaw nodes pending.

Gunakan dari agen

Plugin Ollama bawaan menyediakan alat node_inference. Agen memanggil action: "discover" terlebih dahulu, lalu action: "run" dengan Node dan model dari hasil tersebut (run dapat menghilangkan Node jika hanya ada satu Node berkemampuan yang terhubung). Misalnya: “Temukan model Ollama pada Node saya, lalu gunakan model termuat tercepat untuk merangkum teks ini.”

Penemuan membaca /api/tags, memeriksa kemampuan /api/show, dan menggunakan /api/ps jika tersedia untuk menempatkan model yang sudah termuat di urutan pertama. Penemuan hanya mengembalikan model lokal yang dilaporkan Ollama mendukung percakapan (kemampuan completion) — baris Ollama Cloud dan model khusus embedding dikecualikan. Setiap eksekusi menonaktifkan pemikiran model dan secara default membatasi output hingga 512 token (batas mutlak 8192), kecuali pemanggilan alat meminta maxTokens yang berbeda; beberapa model (misalnya GPT-OSS) tidak mendukung penonaktifan pemikiran dan mungkin tetap menghasilkan token penalaran. Agar Ollama tetap berjalan pada Node tanpa mengeksposnya kepada agen:

openclaw config set plugins.entries.ollama.config.nodeInference.enabled false

Mulai ulang Node (openclaw node restart, atau hentikan/jalankan kembali openclaw node run untuk sesi latar depan). Node berhenti mengiklankan ollama.models dan ollama.chat; Ollama itu sendiri dan penyedia Ollama milik Gateway tidak terpengaruh. Atur kembali nilainya menjadi true dan mulai ulang untuk mengaktifkannya kembali; permukaan perintah yang berubah mungkin memerlukan persetujuan openclaw nodes pending lagi setelah tersambung kembali. Verifikasi perintah Node secara langsung, 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

--invoke-timeout membatasi berapa lama Node dapat menjalankan perintah; --timeout membatasi keseluruhan panggilan Gateway dan harus lebih besar. Inferensi lokal Node selalu menggunakan endpoint loopback milik Node itu sendiri — inferensi ini tidak menggunakan kembali models.providers.ollama.baseUrl jarak jauh/cloud yang dikonfigurasi. Perintah Node tersedia secara default pada host Node macOS, Linux, dan Windows serta tetap tunduk pada kebijakan pemasangan/perintah Node yang normal.

Penglihatan dan deskripsi gambar

Plugin Ollama bawaan mendaftarkan Ollama sebagai penyedia pemahaman media berkemampuan gambar, sehingga OpenClaw dapat merutekan permintaan deskripsi gambar eksplisit dan default model gambar yang dikonfigurasi melalui model penglihatan Ollama lokal atau yang di-host.

ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"
openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --json

--model harus berupa referensi <provider/model> lengkap; ketika ditetapkan, infer image describe mencoba model tersebut terlebih dahulu alih-alih melewati deskripsi untuk model yang sudah mendukung penglihatan native. Jika panggilan gagal, OpenClaw dapat melanjutkan melalui agents.defaults.imageModel.fallbacks; error persiapan file/URL menggagalkan proses sebelum fallback dicoba. Gunakan infer image describe untuk alur pemahaman gambar OpenClaw dan imageModel yang dikonfigurasi; gunakan infer model run --file untuk probe multimodal mentah dengan prompt khusus. Untuk menjadikan Ollama sebagai penyedia pemahaman gambar default bagi media masuk:

{
  agents: {
    defaults: {
      imageModel: {
        primary: "ollama/qwen2.5vl:7b",
      },
    },
  },
}

Utamakan referensi ollama/<model> lengkap. Referensi imageModel tanpa awalan seperti qwen2.5vl:7b dinormalisasi menjadi ollama/qwen2.5vl:7b hanya ketika model persis tersebut tercantum di bawah models.providers.ollama.models dengan input: ["text", "image"] dan tidak ada penyedia gambar lain yang dikonfigurasi yang menyediakan id tanpa awalan yang sama; jika tidak, gunakan prefiks penyedia secara eksplisit. Model penglihatan lokal yang lambat mungkin memerlukan batas waktu pemahaman gambar yang lebih panjang daripada model cloud, dan dapat mengalami crash pada perangkat keras terbatas jika Ollama mencoba mengalokasikan seluruh konteks penglihatan yang diiklankan model. Tetapkan batas waktu kemampuan dan batasi num_ctx:

{
  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 }],
      },
    },
  },
}

Batas waktu ini berlaku untuk pemahaman gambar masuk dan alat image eksplisit. models.providers.ollama.timeoutSeconds tetap mengontrol pengaman permintaan HTTP Ollama yang mendasari panggilan model normal. Verifikasi langsung:

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 penglihatan secara eksplisit:

{
  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 berkemampuan gambar. Dengan penemuan implisit, hal ini berasal dari kemampuan penglihatan /api/show.

Konfigurasi

Dasar (penemuan implisit)
Eksplisit (model manual)
URL dasar khusus

export OLLAMA_API_KEY="ollama-local"

Jika OLLAMA_API_KEY ditetapkan, Anda dapat menghilangkan apiKey dalam entri penyedia; OpenClaw mengisinya untuk pemeriksaan ketersediaan.

Gunakan konfigurasi eksplisit untuk penyiapan cloud yang di-host, host/port non-default, jendela konteks yang dipaksakan, atau daftar model yang sepenuhnya manual:

{
  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"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

Konfigurasi eksplisit menonaktifkan penemuan otomatis, sehingga model harus dicantumkan:

{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434", // Tanpa /v1 - URL API native Ollama
        api: "ollama", // Eksplisit: menjamin perilaku pemanggilan alat native
        timeoutSeconds: 300, // Opsional: anggaran koneksi/streaming yang lebih panjang untuk model lokal yang belum dimuat
        models: [
          {
            id: "qwen3:32b",
            name: "qwen3:32b",
            params: {
              keep_alive: "15m", // Opsional: pertahankan model tetap termuat di antara giliran
            },
          },
        ],
      },
    },
  },
}

Jangan tambahkan /v1. Jalur tersebut memilih mode kompatibel OpenAI, yang tidak menyediakan pemanggilan alat secara andal.

Resep umum

Ganti ID model dengan nama persis dari ollama list atau openclaw models list --provider ollama.

Model lokal dengan penemuan otomatis

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

ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4

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

Host Ollama LAN dengan 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.

Hanya Ollama Cloud

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.

Cloud dan lokal melalui daemon yang telah masuk

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

Beberapa host Ollama

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.

Profil model lokal ringan

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.

Pemilihan model

{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}

ID penyedia khusus bekerja dengan cara yang sama: untuk referensi yang menggunakan prefiks penyedia aktif, seperti ollama-spark/qwen3:32b, OpenClaw menghapus prefiks tersebut sebelum memanggil Ollama dan mengirimkan qwen3:32b. Untuk model lokal yang lambat, utamakan penyetelan dalam lingkup penyedia sebelum menaikkan batas waktu seluruh runtime agen:

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

timeoutSeconds mencakup permintaan HTTP model: penyiapan koneksi, header, streaming isi, dan penghentian guarded-fetch secara keseluruhan. params.keep_alive diteruskan sebagai keep_alive tingkat atas pada permintaan /api/chat native; atur per model jika waktu pemuatan giliran pertama menjadi hambatan utama.

Verifikasi cepat

# Daemon Ollama terlihat oleh mesin ini
curl http://127.0.0.1:11434/api/tags

# Katalog OpenClaw dan model yang dipilih
openclaw models list --provider ollama
openclaw models status

# Uji cepat model secara langsung
openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Balas persis dengan: ok"

Untuk host jarak jauh, ganti 127.0.0.1 dengan host baseUrl. Jika curl berfungsi tetapi OpenClaw tidak, periksa apakah Gateway berjalan pada mesin, kontainer, atau akun layanan yang berbeda.

Pencarian Web Ollama

OpenClaw menyertakan Pencarian Web Ollama sebagai penyedia web_search.

Properti	Detail
Host	`models.providers.ollama.baseUrl` jika ditetapkan, jika tidak `http://127.0.0.1:11434`; `https://ollama.com` menggunakan API yang dihosting secara langsung
Autentikasi	Tanpa kunci untuk host lokal yang telah masuk; `OLLAMA_API_KEY` atau autentikasi penyedia yang dikonfigurasi untuk pencarian `https://ollama.com` langsung atau host yang dilindungi autentikasi
Persyaratan	Host lokal/yang dihosting sendiri harus berjalan dan telah masuk dengan `ollama signin`; pencarian langsung yang dihosting memerlukan `baseUrl: "https://ollama.com"` beserta kunci API asli

Pilih opsi ini selama openclaw onboard atau openclaw configure --section web, atau tetapkan:

{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}

Untuk pencarian langsung yang dihosting 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 host yang dihosting sendiri, OpenClaw terlebih dahulu mencoba proksi /api/experimental/web_search lokal, lalu kembali menggunakan jalur /api/web_search yang dihosting pada host yang sama; daemon lokal yang telah masuk biasanya merespons melalui proksi lokal. Panggilan https://ollama.com langsung selalu menggunakan endpoint /api/web_search yang dihosting.

Untuk penyiapan dan perilaku lengkap, lihat Pencarian Web Ollama.

Konfigurasi lanjutan

Mode kompatibel OpenAI lama

Pemanggilan alat tidak andal dalam mode ini. Gunakan hanya jika proksi memerlukan format OpenAI dan Anda tidak bergantung pada pemanggilan alat native.

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: [...]
      }
    }
  }
}

Jendela konteks

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.

Kontrol pemikiran

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 off
openclaw 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 penalaran

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

ollama pull deepseek-r1:32b

Biaya model

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

Penyematan memori

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.

Properti	Nilai
Model default	`nomic-embed-text`
Penarikan otomatis	Ya, jika belum tersedia secara lokal
Konkurensi inline default	1 (penyedia lain memiliki default lebih tinggi; naikkan dengan `nonBatchConcurrency` jika host mampu menanganinya)

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

Konfigurasi streaming

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".

Untuk menggunakan endpoint yang kompatibel dengan OpenAI, lihat “Mode kompatibel OpenAI lama” di atas — streaming dan pemanggilan alat mungkin tidak berfungsi bersamaan di sana.

Pemecahan masalah

Loop kerusakan WSL2 (boot ulang berulang)

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=5m
ollama serve

Lihat ollama/ollama#11317.

Ollama tidak terdeteksi

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

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

Tidak ada model yang tersedia

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

ollama list  # Lihat apa yang telah terinstal
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Atau model lain

Koneksi ditolak

# Periksa apakah Ollama sedang berjalan
ps aux | grep ollama

# Atau mulai ulang Ollama
ollama serve

Host jarak jauh berfungsi dengan curl tetapi tidak dengan OpenClaw

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 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.

Model menghasilkan JSON alat sebagai teks

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.

Kimi atau GLM menghasilkan simbol yang kacau

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" --json
openclaw models set ollama/gemma4

Model lokal yang dingin mengalami batas waktu

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.

Model dengan konteks besar terlalu lambat atau kehabisan memori

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.

Bantuan selengkapnya: Pemecahan masalah dan Pertanyaan umum.

Terkait

Ollama Cloud

Penyiapan khusus cloud dengan penyedia khusus ollama-cloud.

Penyedia model

Ikhtisar semua penyedia, referensi model, dan perilaku failover.

Pemilihan model

Cara memilih dan mengonfigurasi model.

Pencarian Web Ollama

Detail lengkap penyiapan dan perilaku pencarian web yang didukung Ollama.

Konfigurasi

Referensi konfigurasi lengkap.

Overview

Concepts and configuration

Providers

Aturan autentikasi

Memulai

Model cloud melalui host lokal

Penemuan model (penyedia implisit)

Uji asap

Inferensi lokal Node

Penglihatan dan deskripsi gambar

Konfigurasi

Resep umum

Pemilihan model

Verifikasi cepat

Pencarian Web Ollama

Konfigurasi lanjutan

Pemecahan masalah

Terkait

Ollama Cloud

Penyedia model

Pemilihan model

Pencarian Web Ollama

Konfigurasi

​Aturan autentikasi

​Memulai

​Model cloud melalui host lokal

​Penemuan model (penyedia implisit)

​Uji asap

​Inferensi lokal Node

​Penglihatan dan deskripsi gambar

​Konfigurasi

​Resep umum

​Pemilihan model

​Verifikasi cepat

​Pencarian Web Ollama

​Konfigurasi lanjutan

​Pemecahan masalah

​Terkait

Ollama Cloud

Penyedia model

Pemilihan model

Pencarian Web Ollama

Konfigurasi

Aturan autentikasi

Memulai

Model cloud melalui host lokal

Penemuan model (penyedia implisit)

Uji asap

Inferensi lokal Node

Penglihatan dan deskripsi gambar

Konfigurasi

Resep umum

Pemilihan model

Verifikasi cepat

Pencarian Web Ollama

Konfigurasi lanjutan

Pemecahan masalah

Terkait