Cara Menghubungkan Ollama ke Agen Pemrograman
Pelajari cara menyambungkan agen pemrograman ke Ollama menggunakan base URL lokal. Kami membahas konfigurasi API key, pengaturan context length, dan optimasi performa model.
Yang Anda hubungkan
Anda dapat menggunakan Ollama dengan coding agent. Konfigurasinya lebih sederhana daripada yang diperkirakan banyak orang. Anda hanya perlu mengubah satu base URL dan memilih satu nama model. Kolom API key tetap memerlukan nilai, tetapi server lokal mengabaikannya, sehingga string apa pun dapat digunakan.
Ollama mendengarkan pada port 11434 dan menyediakan tiga permukaan API sekaligus. /api adalah API native Ollama. /v1 adalah lapisan yang kompatibel dengan OpenAI, yang mencakup beberapa bentuk: /v1/chat/completions, /v1/responses, /v1/completions, /v1/models, dan /v1/embeddings. Dokumentasi Ollama menjelaskan bahwa key di sana wajib diisi, tetapi diabaikan. Permukaan ketiga kompatibel dengan Anthropic: client menggunakan http://localhost:11434 sebagai base URL dan menambahkan /v1/messages, yaitu format yang digunakan Claude Code. Sebagian besar agent menggunakan /v1/chat/completions, Codex menggunakan /v1/responses, dan Claude Code menggunakan /v1/messages. Agent Anda sudah mendukung salah satu format ini, sehingga tidak ada hal lain yang perlu diubah.
Bagian ini dapat diselesaikan dalam lima menit. Apakah hasilnya dapat digunakan bergantung pada dua pengaturan yang hampir tidak pernah diubah orang, yaitu panjang konteks dan keep-alive, serta pada pemberian jenis pekerjaan yang sesuai dengan kemampuan model. Masing-masing dibahas dalam bagian tersendiri, sedangkan batasan yang sebenarnya dijelaskan di bagian akhir.
Agen coding mana yang menerima base URL lokal
Pengujiannya hanya satu: apakah tool tersebut menyediakan pengaturan base URL? Jika ya, tool tersebut dapat berkomunikasi dengan server Anda.
Ollama menyediakan halaman integrasi untuk Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDEs, dan VS Code. Aider mendokumentasikan dukungannya sendiri untuk Ollama secara terpisah. Cakupan ini meliputi sebagian besar tool yang dimaksud orang sebagai agen coding pada October 2026. Tool-tool tersebut tidak semuanya menggunakan format API yang sama. Perbedaan inilah yang sering menyebabkan konfigurasi gagal.
- Sebagian besar agen memerlukan endpoint yang kompatibel dengan OpenAI. Berikan base URL
http://localhost:11434/v1dan string API key apa pun yang tidak kosong. - Claude Code sama sekali tidak menerima base URL OpenAI. Tool ini menggunakan Anthropic Messages API, sehingga
ANTHROPIC_BASE_URLharus diatur kehttp://localhost:11434, tempat Ollama menyediakan/v1/messages. - Codex menggunakan OpenAI Responses API. Ollama juga menyediakan
/v1/responses, yang ditambahkan pada version 0.13.3. - Agen yang tidak menyediakan pengaturan base URL tidak dapat dialihkan, karena endpoint ditetapkan di dalam client. Jika agen menerima URL kustom tetapi memerlukan format API yang berbeda, gunakan translation layer di depannya, seperti gateway LiteLLM yang di-host sendiri, lalu expose ulang model Anda dalam format yang diminta client.
Ollama dapat menulis konfigurasi ini untuk Anda. ollama launch opencode menjalankan OpenCode dengan konfigurasi inline untuk model yang Anda pilih, ollama launch claude melakukan hal yang sama untuk Claude Code, dan ollama launch droid --config menulis konfigurasi tanpa menjalankan tool tersebut.
Instal Ollama dan pull model yang dapat memanggil tool
curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama lsInstaller menambahkan unit systemd dan menjalankannya, sehingga systemctl status ollama seharusnya menampilkan active (running). Jika tidak, journalctl -e -u ollama akan menampilkan penyebabnya.
Model harus mendukung pemanggilan tool karena pemanggilan tool merupakan cara kerja agent. Agent membaca file, menulis patch, menjalankan pengujian, lalu membaca kegagalan dan mencoba lagi. Model yang tidak dapat mengeluarkan pemanggilan tool hanya akan menjelaskan perubahan dalam bentuk teks, bukan menerapkannya. Akibatnya, agent akan mengulang atau berhenti. Cari label tools pada halaman model di ollama.com sebelum melakukan pull. qwen3-coder:30b memiliki label tersebut, dan per Oktober 2026, tag itu memerlukan unduhan sebesar 19 GB dengan context window 256K. Jika server Anda hanya menggunakan CPU atau memiliki RAM terbatas, perhitungan kebutuhan memori untuk tag Qwen 27B pada VPS menunjukkan kapasitas yang benar-benar dapat digunakan pada 8 hingga 64 GB sebelum Anda mengunduhnya. Setelah model di-pull, gigabyte tersebut akan tersimpan pada root disk server. Bagian VPS ini biasanya memiliki ruang kosong paling terbatas. Karena itu, lokasi penyimpanan file model Ollama dan cara memindahkannya ke tempat lain sebaiknya dibaca sebelum disk penuh.
Sekarang, pastikan nama yang benar-benar disediakan oleh server:
curl http://localhost:11434/v1/modelsString dalam respons tersebut harus tercantum dalam konfigurasi agent secara persis, karakter demi karakter. Memeriksanya terlebih dahulu biasanya menyelesaikan sebagian besar error model-not-found. Jika Ollama belum terinstal, panduan yang lebih panjang tersedia di cara melakukan self-hosting LLM dengan Ollama pada VPS.
Mengarahkan OpenCode ke Ollama
Edit ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"qwen3-coder:30b": {
"name": "qwen3-coder 30b"
}
}
}
}
}Key di bawah models adalah nama model yang dikirim ke Ollama, jadi harus sama persis dengan ollama ls. Field name hanyalah label di pemilih model. Jalankan opencode, beralihlah ke penyedia Ollama, dan pantau journalctl -e -u ollama untuk memastikan permintaan telah sampai di server Anda dan bukan ke tempat lain. Pengaturan agen itu sendiri dibahas di menjalankan OpenCode di VPS.
Arahkan Claude Code ke Ollama
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30bANTHROPIC_API_KEY sengaja diatur ke string kosong. URL dasar menentukan tujuan pengiriman permintaan; mengosongkan kunci tersebut mencegah kredensial layanan ter-host digunakan dalam penyiapan lokal ini. ollama launch claude mengatur semua hal tersebut untuk Anda.
Pahami keterbatasan yang ditinggalkan oleh lapisan kompatibilitas. Lapisan ini tidak mengimplementasikan tool_choice atau caching prompt, dan tidak memiliki endpoint penghitungan token. Karena itu, jumlah token yang Anda lihat merupakan perkiraan berdasarkan tokenizer milik model itu sendiri. Claude Code juga mengirim system prompt yang besar dan menyediakan banyak tool, sehingga memerlukan konteks yang lebih besar daripada client chat. Pembahasan yang lebih luas tentang hal-hal yang dapat digunakan kembali dan yang tidak tercakup dalam apakah Claude dapat Anda host sendiri.
Arahkan Aider ke Ollama
export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30bDokumentasi Aider merekomendasikan awalan ollama_chat/ daripada ollama/. Secara default, Aider meminta konteks yang memadai untuk setiap permintaan, ditambah 8k token untuk balasan. Aider juga memungkinkan Anda menetapkan jendela konteks untuk setiap model dalam .aider.model.settings.yml. Fitur ini berguna jika suatu model memerlukan jendela yang berbeda dari default server:
- name: ollama_chat/qwen3-coder:30b
extra_params:
num_ctx: 65536Mengapa konfigurasi yang berfungsi tetap menghasilkan keluaran yang tidak masuk akal
Ini bagian yang paling penting. Ollama memilih panjang konteks default dari total VRAM (memori video pada GPU) yang dapat dideteksinya, lalu mengurangkan OLLAMA_GPU_OVERHEAD untuk setiap GPU yang terdeteksi. Implementasinya menggunakan ambang berikut:
Data di balik grafik ini
[
{
"label": "Under 23 GiB aggregate VRAM",
"default_context_tokens": "4,096"
},
{
"label": "23 to under 47 GiB aggregate VRAM",
"default_context_tokens": "32,768"
},
{
"label": "47 GiB aggregate VRAM or more",
"default_context_tokens": "262,144"
}
]Sebagian besar paket VPS dan semua server yang hanya menggunakan CPU berada pada baris pertama: 4,096 token. Beberapa GPU berkapasitas lebih kecil dapat mencapai ambang 47 GiB secara gabungan, sehingga memenuhi 262,144 token pada baris terakhir.
Sebuah agent mengirimkan 4096 token sebelum melakukan pekerjaan apa pun. System prompt, definisi tool, daftar repository, dan file pertama yang dibukanya sudah lebih besar daripada itu. Berikutnya muncul masalah utamanya: tidak ada error. Dokumentasi Aider menyatakan bahwa Ollama membuang konteks yang melebihi window secara diam-diam. Token paling lama akan dikeluarkan, sehingga model menjawab dengan yakin tentang file yang sudah tidak dapat dilihatnya atau melupakan instruksi yang Anda berikan dua langkah sebelumnya. Mekanisme ini menjadi penyebab sebagian besar laporan bahwa model lokal terlalu tidak cerdas untuk menulis kode. Memilih nilainya sendiri merupakan keputusan tersendiri, dan biaya num_ctx dalam memori cache KV pada setiap ukuran layak dibaca sebelum Anda menetapkan nilainya.
Dokumentasi Ollama menyatakan bahwa tugas seperti agent dan tool coding harus diatur minimal ke 64000 token. Atur pada server:
sudo systemctl edit ollama.serviceTambahkan baris berikut ke file override:
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"Kemudian muat ulang dan mulai ulang:
sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama psKirim permintaan dari agent setelah mulai ulang, lalu jalankan ollama ps lagi agar ada model yang dimuat untuk diperiksa. ollama ps adalah pemeriksaannya. Perintah ini menampilkan kolom CONTEXT, dan angka tersebut adalah jumlah yang benar-benar diterima model. Nilai ID dan SIZE Anda akan berbeda:
NAME ID SIZE PROCESSOR CONTEXT RUNNER UNTIL
qwen3-coder:30b a1b2c3d4e5f6 24 GB 100% GPU 64000 ggml 4 minutes from nowAtur pada server, bukan pada agent, karena dua alasan. Skema OpenAI chat completions tidak memiliki field untuk panjang konteks, sehingga klien yang kompatibel dengan OpenAI tidak dapat memintanya. Selain itu, default server berlaku untuk setiap agent, kecuali model atau request menimpanya. Sisi output memiliki batasnya sendiri. Berbeda dengan panjang konteks, nilai ini dikirim melalui endpoint kompatibilitas. Karena itu, num_predict dan field max_tokens yang dipetakan ke dalamnya adalah pengaturan yang digunakan ketika balasan berhenti di tengah patch. Jika satu model memerlukan window yang berbeda, masukkan pengaturannya ke dalam salinan model menggunakan Modelfile:
FROM qwen3-coder:30b
PARAMETER num_ctx 65536ollama create qwen3-coder-64k -f ModelfileKonteks tidak gratis. Window yang lebih panjang membutuhkan lebih banyak memori, jadi pantau kolom PROCESSOR. 100% GPU adalah kondisi yang Anda inginkan. Setelah sebagian model dialihkan ke CPU, laju token turun cukup jauh sehingga loop agent tidak dapat digunakan. Mengukur token per detik pada LLM lokal membantu Anda menemukan batas nyata untuk mesin Anda. Penentuan ukuran mesin sebelum membelinya dibahas dalam berapa banyak RAM dan CPU yang dibutuhkan VPS untuk agent coding.
Pertahankan model tetap dimuat di antara permintaan
Secara default, Ollama membongkar model 5 menit setelah permintaan terakhir. Perilaku ini sesuai untuk kotak obrolan, tetapi tidak sesuai untuk pekerjaan agen. Anda berhenti sejenak untuk membaca diff, penghitung waktu habis, lalu permintaan berikutnya memuat ulang puluhan gigabita bobot dari disk sebelum token pertama muncul. Kondisi ini terlihat seperti hang.
OLLAMA_KEEP_ALIVE menerima string durasi seperti 10m atau 24h, angka biasa dalam detik, -1 untuk mempertahankan model tetap dimuat tanpa batas waktu, atau 0 untuk segera membongkarnya. Atur parameter ini bersama panjang konteks:
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"Kolom permintaan keep_alive tersedia pada endpoint native Ollama /api/generate dan /api/chat, serta sebagai ekstensi Ollama pada /v1/chat/completions. Agen yang menyediakan kolom permintaan tambahan dapat mengirimkannya melalui endpoint tersebut. Jika tidak, gunakan variabel lingkungan. Saat memerlukan kembali memori, ollama stop qwen3-coder:30b membongkar model tanpa menghentikan server. Jika ingin pengaturan ini tetap berlaku setelah reboot, atau ingin membandingkan manfaat mempertahankan bobot di memori sepanjang hari dengan mendapatkan kembali memori tersebut, mempertahankan model Ollama tetap dimuat di memori dapat dilakukan melalui kedua cara tersebut.
Menjalankan Ollama pada server terpisah
Ollama terikat pada localhost. Agar dapat diakses dari mesin lain, tetapkan OLLAMA_HOST=0.0.0.0:11434 pada systemd override yang sama, lalu restart service.
Lakukan ini hanya pada jaringan privat. Dokumentasi Ollama menyatakan bahwa API lokal tidak memerlukan autentikasi. Jika port 11434 dibuka ke Internet, siapa pun dapat menggunakan hardware Anda. Ada 2 opsi yang aman. Biarkan binding tetap pada localhost, lalu teruskan port melalui SSH dari laptop Anda:
ssh -N -L 11434:localhost:11434 you@your-vpsAgent Anda tetap mengarah ke http://localhost:11434/v1 dan tidak mengetahui perbedaannya. Opsi lainnya adalah VPN, dengan Ollama terikat pada alamat VPN, bukan 0.0.0.0. Jika beberapa orang atau beberapa agent akan berbagi satu server, Ollama mendukung permintaan paralel selama memori mencukupi. perbandingan antara Ollama dan vLLM menunjukkan kapan perbedaan throughput mulai menimbulkan dampak.
Kapan model koding lokal unggul, dan kapan tidak
Agen yang digerakkan oleh model yang Anda host sendiri tidak menggantikan API frontier untuk setiap tugas. Model ini jelas unggul dalam empat jenis pekerjaan.
- Pengeditan mekanis massal, di mana setiap perubahan kecil dan Anda dapat memeriksanya. Mengganti nama di seluruh repositori, menambahkan petunjuk tipe (type hints), menulis docstring, menerjemahkan komentar. Model berjalan selama berjam-jam dan tagihan Anda tidak bertambah.
- Pekerjaan yang tidak boleh keluar dari perangkat keras Anda. Kode klien di bawah perjanjian kerahasiaan, atau repositori internal yang tidak diizinkan untuk dikirim ke pihak ketiga.
- Mesin offline dan air-gapped, di mana tidak ada API yang di-host untuk dipanggil sama sekali.
- Biaya yang dapat diprediksi. Setelah server dibayar, agen yang menghabiskan token dalam sebuah loop tidak memerlukan biaya tambahan, yang merupakan kebalikan dari API berbasis meteran. Di mana GPU VPS mencapai titik impas dibandingkan token API memiliki perhitungannya.
Model ini kalah pada tugas multi-langkah yang panjang. "Cari tahu mengapa tes ini gagal, perbaiki penyebabnya, perbarui pemanggilnya" memerlukan banyak panggilan alat (tool calls) yang benar secara berurutan, dengan seluruh riwayat tetap dalam konteks. Model dalam rentang 8B hingga 14B pada server sederhana akan menghasilkan panggilan alat yang salah format, atau kehilangan rencana setelah beberapa putaran, dan Anda menghabiskan lebih banyak waktu untuk mengarahkannya daripada waktu yang dibutuhkan untuk menyelesaikan tugas tersebut. Itu bukan masalah prompt yang bisa Anda selesaikan dengan menulis ulang. Itu adalah masalah kapasitas.
Model ini juga kalah kapan pun kesalahan berakibat mahal dan Anda tidak akan membaca setiap barisnya. Berikan pekerjaan yang sempit kepada model lokal yang outputnya Anda verifikasi, dan gunakan model yang di-host untuk pekerjaan yang tidak akan Anda periksa langkah demi langkah.
Mode kegagalan dan string yang akan Anda lihat
curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Server tidak berjalan, atau agent diarahkan ke host yang berbeda. Jalankan systemctl status ollama, lalu journalctl -e -u ollama.
Agent melaporkan bahwa model tidak ada. Nama dalam konfigurasi Anda tidak cocok dengan nama yang disediakan server. Bandingkan nama tersebut dengan curl http://localhost:11434/v1/models, lalu salin string dari sana. Tag merupakan bagian dari nama. Jadi, konfigurasi yang mencantumkan tag yang belum pernah Anda pull akan gagal meskipun model serupa sudah terpasang.
Agent memberikan jawaban berupa prosa dan tidak pernah mengedit file. Model mungkin tidak mendukung tool, atau request beserta definisi tool-nya sudah memenuhi context window. Periksa label tools pada halaman model, lalu periksa kolom CONTEXT dalam ollama ps.
Hening cukup lama sebelum token pertama, lalu kecepatannya normal. Keep-alive telah kedaluwarsa dan weights sedang dibaca ulang dari disk. Atur OLLAMA_KEEP_ALIVE.
Model menyangkal isi file yang baru saja dibacanya. Ini adalah truncation context. ollama ps biasanya menampilkan nilai CONTEXT yang lebih kecil daripada yang Anda tetapkan, karena environment variable diterapkan ke shell, bukan ke unit systemd.
Semuanya berfungsi, tetapi lambat, dan PROCESSOR menampilkan 100% CPU atau pembagian CPU/GPU. Biasanya model beserta context-nya tidak muat di VRAM. Jika PROCESSOR membaca 100% CPU pada mesin yang memiliki GPU, singkirkan penyebab lain terlebih dahulu: Ollama mungkin sama sekali tidak menemukan GPU. Dokumentasi Ollama mencatat bahwa di Linux, setelah siklus suspend/resume, Ollama terkadang gagal menemukan GPU NVIDIA dan beralih ke CPU. Memuat ulang driver dengan sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm dapat mengatasi masalah tersebut. Jika GPU ditemukan tetapi pembagian tetap ada, kurangi panjang context, atau gunakan model yang lebih kecil atau quantisation yang lebih kecil. Sebelum melakukan pull ulang, penjelasan tentang biaya memori q4_K_M, q8_0, dan fp16, serta titik penurunan kualitasnya menjelaskan kapasitas yang diperoleh dengan menurunkan satu tingkat dan konsekuensinya. Unknown juga merupakan nilai PROCESSOR yang mungkin. Nilai tersebut tidak membuktikan bahwa CPU offloading sedang digunakan.
FAQ
Dapatkah saya mengarahkan Claude Code ke Ollama?
Ya, tetapi bukan dengan URL yang kompatibel dengan OpenAI. Claude Code menggunakan Anthropic Messages API, sedangkan Ollama menyediakan format tersebut pada /v1/messages di port 11434 yang sama. Ekspor ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama, dan ANTHROPIC_API_KEY yang kosong, lalu jalankan dengan claude --model qwen3-coder:30b. ollama launch claude menulis pengaturan yang sama untuk Anda. Lapisan kompatibilitas ini tidak mengimplementasikan tool_choice atau caching prompt, dan tidak memiliki endpoint penghitungan token. Karena itu, jumlah token yang dilaporkan hanya perkiraan.
Mengapa model lokal saya menjawab tentang kode yang tidak dapat dilihatnya?
Karena permintaan tersebut tidak lagi muat dalam context window, dan bagian paling awal dibuang tanpa error. Ollama menetapkan context default berdasarkan total VRAM yang terdeteksi setelah mengurangi overhead yang dikonfigurasi untuk setiap GPU: di bawah 23 GiB, default-nya adalah 4,096 token; dari 23 hingga kurang dari 47 GiB, nilainya adalah 32,768 token; dan pada 47 GiB atau lebih, nilainya adalah 262,144 token. Tetapkan OLLAMA_CONTEXT_LENGTH=64000 di unit systemd, restart Ollama, lalu pastikan kolom CONTEXT di ollama ps menampilkan nilai baru.
Model mana yang sebaiknya saya jalankan sebagai coding agent pada VPS?
Pilih model terbesar dengan label tools yang masih muat di memori dengan context window 64k, dan utamakan model yang dioptimalkan untuk kode. qwen3-coder:30b adalah pilihan umum pada server GPU dengan VRAM yang memadai. Jika tag tersebut terlalu besar untuk server Anda, angka RAM dan kecepatan CPU-only untuk Nemotron 3.5 Lightning dapat menjadi perbandingan yang berguna sebelum Anda mengunduhnya. Di bawah sekitar 14B parameter, model masih dapat menjawab pertanyaan tentang kode dengan baik, tetapi dapat gagal saat melakukan perubahan multi-langkah karena pekerjaan agent sangat terpengaruh oleh kesalahan format kecil dalam tool call. Uji model dengan satu tugas nyata dari repository Anda sendiri, bukan dengan prompt contoh.
Apakah saya memerlukan GPU untuk menjalankan coding agent pada model saya sendiri?
Dalam praktiknya, ya. Inferensi CPU-only dapat berjalan dan cukup untuk pertanyaan tunggal, tetapi agent mengirim banyak permintaan untuk setiap tugas dan membaca ulang riwayat yang panjang pada setiap permintaan. Akibatnya, laju token yang lambat dapat mengubah tugas berdurasi dua menit menjadi satu jam. Periksa kolom PROCESSOR di ollama ps: 100% CPU atau pembagian CPU/GPU menunjukkan penggunaan CPU, yang memperlambat inferensi. Unknown tidak membuktikan adanya offloading ke CPU.