Cara Menghubungkan Ollama ke Agen Pemrograman

Apa yang Anda hubungkan

Anda dapat menggunakan Ollama dengan agen pemrograman Anda, dan koneksinya lebih sederhana dari yang diperkirakan. Anda hanya perlu mengubah satu base URL dan memilih satu nama model. Kolom API key tetap memerlukan nilai, namun server lokal akan mengabaikannya, sehingga string apa pun dapat digunakan.

Ollama mendengarkan pada port 11434 dan melayani dua bentuk permintaan secara bersamaan. /v1/chat/completions adalah bentuk yang kompatibel dengan OpenAI, dan dokumentasi Ollama menjelaskan bahwa kunci di sana diperlukan tetapi diabaikan. /v1/messages adalah bentuk yang kompatibel dengan Anthropic, yang digunakan oleh Claude Code. Agen Anda sudah mendukung salah satu dari keduanya, jadi tidak ada hal lain yang perlu diubah.

Bagian tersebut hanya memakan waktu lima menit. Apakah hasilnya dapat digunakan bergantung pada dua pengaturan yang jarang diubah oleh orang lain, yaitu context length dan keep-alive, serta memberikan jenis pekerjaan yang sesuai dengan kemampuan model tersebut. Keduanya akan dibahas di bagian masing-masing, dan batasan yang sebenarnya ada di bagian akhir.

Agen pengodean mana yang menerima base URL lokal

Tesnya hanya satu pertanyaan: apakah alat tersebut menyediakan pengaturan base URL? Jika ya, alat tersebut dapat berkomunikasi dengan server Anda.

Ollama menerbitkan halaman integrasi untuk Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, IDE JetBrains, dan VS Code. Aider mendokumentasikan dukungan Ollama-nya sendiri secara terpisah. Hal tersebut mencakup sebagian besar dari apa yang dimaksud orang sebagai agen pengodean pada Agustus 2026. Tidak semuanya menggunakan format yang sama, dan perbedaan itulah yang menyebabkan kegagalan konfigurasi.

• Sebagian besar agen menginginkan endpoint yang kompatibel dengan OpenAI. Berikan base URL http://localhost:11434/v1 dan string API key apa pun yang tidak kosong.
• Claude Code sama sekali tidak menerima base URL OpenAI. Agen ini menggunakan Anthropic Messages API, sehingga memerlukan ANTHROPIC_BASE_URL yang diatur ke http://localhost:11434, di mana Ollama melayani /v1/messages.
• Codex menggunakan OpenAI Responses API. Ollama juga melayani /v1/responses, yang ditambahkan pada versi 0.13.3.
• Agen tanpa pengaturan base URL tidak dapat dialihkan, karena endpoint sudah tertanam di dalam klien. Sebagai gantinya, tempatkan lapisan translasi di depannya, seperti gateway LiteLLM yang di-host sendiri, dan ekspos kembali model Anda dalam format apa pun yang diminta oleh klien.

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

Menginstal Ollama dan menarik model yang mendukung pemanggilan tool

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

Installer akan menambahkan unit systemd dan menjalankannya, sehingga systemctl status ollama seharusnya menampilkan active (running). Jika tidak, journalctl -e -u ollama akan menampilkan alasannya.

Model harus mendukung pemanggilan tool (tool calling), karena pemanggilan tool adalah cara kerja agen. Agen membaca file, menulis patch, menjalankan tes, lalu membaca kegagalan dan mencoba lagi. Model yang tidak dapat mengeluarkan pemanggilan tool akan mendeskripsikan pengeditan dalam bentuk prosa alih-alih melakukannya, sehingga agen akan mengalami loop atau berhenti. Cari label tools pada halaman model di ollama.com sebelum Anda melakukan pull. qwen3-coder:30b memiliki label tersebut, dan per Agustus 2026 tag ini berukuran 19 GB dengan jendela konteks 256K. Jika server Anda hanya menggunakan CPU atau memiliki RAM terbatas, perhitungan memori untuk tag Qwen 27B pada VPS menunjukkan apa yang sebenarnya muat dalam kapasitas 8 hingga 64 GB sebelum Anda mengunduhnya. Setelah Anda menariknya, gigabyte tersebut akan tersimpan pada disk root server, yang merupakan bagian dari VPS dengan ruang paling terbatas, sehingga di mana Ollama menyimpan file modelnya dan cara memindahkannya ke lokasi lain layak dibaca sebelum disk penuh.

Sekarang konfirmasikan nama model apa saja yang sebenarnya dilayani oleh server:

curl http://localhost:11434/v1/models

String dalam respons tersebut adalah apa yang harus dimuat oleh konfigurasi agen Anda, karakter demi karakter. Memeriksanya terlebih dahulu akan menyelesaikan sebagian besar error model-not-found. Jika Ollama belum terinstal, panduan yang lebih lengkap tersedia di 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.

Mengarahkan Claude Code ke Ollama

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

ANTHROPIC_API_KEY sengaja dikosongkan. Kunci asli yang tertinggal di environment akan mengirimkan permintaan Anda ke API yang di-host, sehingga Anda akan dikenakan biaya dan tidak mendapatkan inferensi lokal. ollama launch claude mengatur semua ini untuk Anda.

Pahami apa yang tidak didukung oleh lapisan kompatibilitas ini. Lapisan ini tidak mengimplementasikan tool_choice atau prompt caching, dan tidak memiliki endpoint penghitungan token, sehingga angka token yang Anda lihat hanyalah perkiraan dari tokenizer model itu sendiri. Claude Code juga menyertakan system prompt yang besar dan set alat yang luas, sehingga membutuhkan konteks yang lebih besar daripada klien chat biasa. Pertanyaan lebih luas mengenai apa yang dapat digunakan dan apa yang tidak, dibahas dalam apakah Anda dapat melakukan self-host Claude.

Mengarahkan Aider ke Ollama

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

Dokumentasi Aider menyarankan penggunaan prefiks ollama_chat/ dibandingkan ollama/. Aider juga memungkinkan Anda untuk menyematkan (pin) jendela konteks per model di .aider.model.settings.yml, yang berguna ketika satu model memerlukan jendela yang berbeda dari setelan bawaan server:

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

Mengapa konfigurasi yang berjalan tetap menghasilkan output yang tidak masuk akal

Ini adalah bagian yang penting. Ollama memilih panjang konteks default berdasarkan VRAM (memori video pada GPU) yang terdeteksi, dan nilai default tersebut telah dipublikasikan:

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB VRAM or more",
    "default_context_tokens": "262,144"
  }
]

Sebagian besar paket VPS, dan setiap server yang hanya menggunakan CPU, masuk ke baris pertama: 4,096 token. Hanya GPU besar yang mendapatkan 262,144 token di baris terakhir.

Sebuah agen menghabiskan 4096 token sebelum melakukan pekerjaan apa pun. System prompt, definisi tool, daftar repositori, dan file pertama yang dibuka sudah lebih besar dari itu. Masalah utamanya adalah: tidak ada error yang muncul. Dokumentasi Aider menyatakan bahwa Ollama secara diam-diam membuang konteks yang melebihi jendela tersebut. Token terlama akan terhapus, sehingga model menjawab dengan percaya diri mengenai file yang tidak lagi dapat dilihatnya, atau melupakan instruksi yang Anda berikan dua langkah sebelumnya. Mekanisme inilah yang menjadi penyebab sebagian besar laporan bahwa model lokal terlalu bodoh untuk menulis kode. Memilih angka tersebut adalah keputusan tersendiri, dan apa biaya num_ctx dalam memori KV cache pada setiap ukuran layak dibaca sebelum Anda menetapkan nilainya.

Dokumentasi Ollama menyatakan bahwa tugas seperti agen dan alat pengodean harus diatur setidaknya ke 64000 token. Atur pada server:

sudo systemctl edit ollama.service

Tambahkan baris berikut ke dalam file override:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Kemudian muat ulang dan mulai ulang:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps adalah cara pengecekannya. Perintah ini mencetak kolom CONTEXT, dan angka tersebut adalah jumlah yang sebenarnya diterima oleh model. ID dan SIZE Anda akan berbeda:

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

Atur pada server alih-alih di dalam agen, karena dua alasan. Skema chat completions OpenAI tidak memiliki field untuk panjang konteks, sehingga klien yang kompatibel dengan OpenAI tidak dapat memintanya. Selain itu, pengaturan ini bersifat per server, sehingga setiap agen yang Anda arahkan ke server tersebut akan mewarisinya. Sisi output memiliki batasnya sendiri, dan tidak seperti panjang konteks, pengaturan ini dikirim melalui endpoint kompatibilitas, jadi num_predict dan field max_tokens yang memetakannya adalah hal yang perlu Anda atur ketika balasan terhenti di tengah-tengah patch. Jika satu model memerlukan jendela yang berbeda, buatlah salinannya dengan Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Konteks tidak gratis. Jendela yang lebih panjang memakan lebih banyak memori, jadi perhatikan kolom PROCESSOR. 100% GPU adalah target yang Anda inginkan. Begitu sebagian model tumpah ke CPU, kecepatan token akan turun drastis hingga loop agen menjadi tidak dapat digunakan, dan mengukur token per detik pada LLM lokal adalah cara untuk menemukan batas kemampuan server Anda yang sebenarnya. Menentukan ukuran mesin sebelum membelinya dibahas dalam berapa banyak RAM dan CPU yang dibutuhkan VPS agen pengodean.

Menjaga model tetap dimuat di antara permintaan

Secara default, Ollama akan membongkar (unload) model 5 menit setelah permintaan terakhir. Pengaturan ini tepat untuk kotak obrolan, namun tidak untuk pekerjaan agen. Anda mungkin berhenti sejenak untuk membaca diff, pengatur waktu habis, dan permintaan berikutnya akan memuat ulang puluhan gigabyte bobot dari disk sebelum token pertama muncul. Hal ini terlihat seperti sistem yang macet.

OLLAMA_KEEP_ALIVE menerima string durasi seperti 10m atau 24h, angka detik biasa, -1 untuk menjaga model tetap dimuat tanpa batas waktu, atau 0 untuk segera membongkar model. Atur parameter ini di samping panjang konteks:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

Bidang permintaan keep_alive hanya tersedia pada endpoint asli /api/generate dan /api/chat di Ollama, bukan pada endpoint kompatibilitas, sehingga agen tidak dapat mengaturnya per permintaan. Variabel lingkungan adalah satu-satunya kendali yang Anda miliki. Saat Anda membutuhkan kembali memori tersebut, ollama stop qwen3-coder:30b akan membongkar model tanpa menghentikan server. Jika Anda ingin pengaturan ini tetap ada setelah reboot, atau ingin mempertimbangkan antara menjaga bobot tetap di memori sepanjang hari dengan mendapatkan kembali memori tersebut, menjaga model Ollama tetap dimuat di memori mencakup kedua skenario tersebut.

Menjalankan Ollama pada server terpisah

Ollama melakukan binding ke localhost. Untuk mengaksesnya dari mesin lain, atur OLLAMA_HOST=0.0.0.0:11434 di dalam override systemd yang sama lalu restart service tersebut.

Lakukan hal ini hanya pada jaringan privat. Dokumentasi Ollama menyatakan bahwa tidak diperlukan autentikasi untuk API lokal, sehingga port 11434 yang terbuka ke internet berarti siapa pun dapat menggunakan perangkat keras Anda dan membaca apa pun yang dikirim oleh agen Anda. Terdapat dua opsi yang aman. Tetap gunakan binding pada localhost dan teruskan (forward) port tersebut melalui SSH dari laptop Anda:

ssh -N -L 11434:localhost:11434 you@your-vps

Agen Anda tetap mengarah ke http://localhost:11434/v1 dan tidak akan mendeteksi perbedaan apa pun. Opsi lainnya adalah menggunakan VPN, dengan Ollama di-bind ke alamat VPN alih-alih 0.0.0.0. Jika beberapa orang atau beberapa agen akan berbagi satu server, scheduler Ollama tidak dirancang untuk beban tersebut, dan perbandingan antara Ollama dan vLLM menunjukkan di mana perbedaan throughput mulai menjadi kendala.

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 temui

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Server tidak berjalan, atau agen diarahkan ke host yang berbeda. Jalankan systemctl status ollama, lalu journalctl -e -u ollama.

Agen melaporkan bahwa model tidak ada. Nama dalam konfigurasi Anda tidak cocok dengan nama yang disediakan oleh server. Bandingkan dengan curl http://localhost:11434/v1/models dan salin string dari sana. Tag adalah bagian dari nama, sehingga konfigurasi yang menyebutkan tag yang belum pernah Anda tarik akan gagal meskipun model serupa sudah terinstal.

Agen menjawab dalam bentuk prosa dan tidak pernah mengedit file. Model tidak memiliki dukungan alat, atau permintaan beserta definisi alatnya telah memenuhi jendela konteks. Periksa label tools pada halaman model, lalu periksa kolom CONTEXT di ollama ps.

Keheningan panjang sebelum token pertama, lalu kecepatan normal. Keep-alive telah kedaluwarsa dan bobot sedang dibaca ulang dari disk. Atur OLLAMA_KEEP_ALIVE.

Model bertentangan dengan file yang baru saja dibacanya. Pemotongan konteks (context truncation). ollama ps biasanya menunjukkan nilai CONTEXT yang lebih kecil dari yang Anda kira, karena variabel lingkungan masuk ke shell Anda, bukan ke unit systemd.

Semuanya berfungsi, namun lambat, dan PROCESSOR bukan 100% GPU. Model beserta konteksnya tidak muat di VRAM. Kurangi panjang konteks, atau beralihlah ke model yang lebih kecil atau kuantisasi yang lebih kecil. Sebelum Anda menarik ulang, berapa biaya memori untuk q4_K_M, q8_0, dan fp16, serta di mana kualitas sebenarnya menurun memberi tahu Anda berapa banyak ruang yang didapat dengan satu langkah penurunan dan apa yang Anda korbankan untuk itu.

FAQ

Bisakah saya mengarahkan Claude Code ke Ollama?

Bisa, tetapi tidak dengan URL yang kompatibel dengan OpenAI. Claude Code menggunakan Anthropic Messages API, dan Ollama menyediakan format tersebut di /v1/messages pada port 11434 yang sama. Ekspor ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama, dan ANTHROPIC_API_KEY kosong, lalu jalankan dengan claude --model qwen3-coder:30b. ollama launch claude akan menuliskan pengaturan yang sama untuk Anda. Lapisan kompatibilitas ini tidak mengimplementasikan tool_choice atau prompt caching, dan tidak memiliki endpoint penghitungan token, sehingga jumlah token yang dilaporkan hanyalah perkiraan.

Mengapa model lokal saya menjawab tentang kode yang tidak bisa ia lihat?

Karena permintaan tersebut tidak lagi muat dalam context window, dan bagian terlama dari permintaan tersebut dibuang tanpa pesan error. Ollama menetapkan konteks default berdasarkan VRAM yang terdeteksi, dan di bawah 24 GiB, nilai defaultnya adalah 4,096 token, yang mana sudah terlampaui hanya oleh system prompt dan definisi tool milik agen. Tetapkan OLLAMA_CONTEXT_LENGTH=64000 di unit systemd, restart Ollama, dan pastikan kolom CONTEXT di ollama ps menunjukkan nilai yang baru.

Model mana yang harus saya jalankan untuk agen pengodean di 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 jawaban umum untuk server GPU dengan VRAM yang mencukupi. Jika ukuran tersebut terlalu besar untuk server Anda, angka RAM dan kecepatan CPU-only untuk Nemotron 3.5 Lightning adalah perbandingan yang berguna sebelum Anda melakukan pengunduhan. Di bawah sekitar 14B parameter, model mungkin masih bisa menjawab pertanyaan tentang kode dengan baik namun gagal dalam pengeditan multi-langkah, karena pekerjaan agen sangat sensitif terhadap kesalahan format kecil dalam pemanggilan tool. Lakukan pengujian dengan satu tugas nyata dari repositori Anda sendiri, bukan dengan prompt contoh.

Apakah saya memerlukan GPU untuk menjalankan agen pengodean pada model saya sendiri?

Secara praktis, ya. Inferensi CPU-only memang berfungsi dan cukup untuk pertanyaan tunggal, tetapi agen mengirimkan banyak permintaan per tugas dan setiap permintaan membaca ulang riwayat yang panjang, sehingga kecepatan token yang lambat akan mengubah tugas dua menit menjadi satu jam. Periksa kolom PROCESSOR di ollama ps: nilai apa pun selain 100% GPU berarti sebagian model berjalan di CPU, dan kecepatan token akan turun drastis.