Cara Sambungkan Ollama Dengan Ejen Pengekodan

Perkara yang anda sambungkan

Anda boleh menggunakan Ollama dengan ejen pengekodan anda, dan sambungannya lebih ringkas daripada jangkaan ramai. Anda hanya perlu menukar satu base URL dan memilih satu nama model. Medan API key masih memerlukan nilai, namun pelayan tempatan akan mengabaikannya, jadi sebarang rentetan aksara boleh digunakan.

Ollama mendengar pada port 11434 dan menyediakan dua bentuk permintaan pada masa yang sama. /v1/chat/completions ialah bentuk yang serasi dengan OpenAI, dan dokumentasi Ollama menyatakan bahawa kunci di situ diperlukan tetapi diabaikan. /v1/messages ialah bentuk yang serasi dengan Anthropic, iaitu bahasa yang digunakan oleh Claude Code. Ejen anda sudah pun menyokong salah satu daripada kedua-dua bentuk ini, jadi tiada perkara lain yang perlu diubah.

Bahagian itu mengambil masa lima minit. Sama ada hasilnya boleh digunakan atau tidak bergantung kepada dua tetapan yang jarang diubah oleh sesiapa, iaitu context length dan keep-alive, serta memberikan model jenis tugasan yang sesuai dengan keupayaannya. Kedua-duanya mempunyai bahagian tersendiri, dan had sebenar dinyatakan di penghujung.

Ejen pengekodan yang manakah menerima base URL tempatan

Ujiannya hanya satu soalan: adakah alat tersebut mendedahkan tetapan base URL? Jika ya, ia boleh berhubung dengan pelayan anda.

Ollama menerbitkan halaman integrasi untuk Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, IDE JetBrains dan VS Code. Aider mendokumentasikan sokongan Ollama miliknya secara berasingan. Ini merangkumi kebanyakan perkara yang dimaksudkan oleh orang ramai sebagai ejen pengekodan pada Ogos 2026. Tidak semua ejen menggunakan format yang sama, dan perbezaan itulah yang menyebabkan kegagalan persediaan.

• Kebanyakan ejen mahukan endpoint yang serasi dengan OpenAI. Berikan mereka base URL http://localhost:11434/v1 dan sebarang rentetan API key yang tidak kosong.
• Claude Code tidak menerima base URL OpenAI sama sekali. Ia menggunakan Anthropic Messages API, jadi ia memerlukan ANTHROPIC_BASE_URL ditetapkan kepada http://localhost:11434, di mana Ollama menyediakan /v1/messages.
• Codex menggunakan OpenAI Responses API. Ollama juga menyediakan /v1/responses, yang ditambah dalam versi 0.13.3.
• Ejen tanpa tetapan base URL tidak boleh diubah hala, kerana endpoint tersebut dibina ke dalam klien. Letakkan lapisan terjemahan di hadapan sebagai ganti, seperti gateway LiteLLM yang dihoskan sendiri, dan dedahkan semula model anda dalam bentuk yang diminta oleh klien.

Ollama boleh menulis konfigurasi ini untuk anda. ollama launch opencode memulakan OpenCode dengan konfigurasi sebaris untuk model yang anda pilih, ollama launch claude melakukan perkara yang sama untuk Claude Code, dan ollama launch droid --config menulis konfigurasi tersebut tanpa melancarkan alat berkenaan.

Memasang Ollama dan memuat turun model yang menyokong panggilan alatan

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

Pemasang akan menambah unit systemd dan memulakannya, jadi systemctl status ollama sepatutnya memaparkan active (running). Jika tidak, journalctl -e -u ollama akan memaparkan puncanya.

Model tersebut mestilah menyokong panggilan alatan, kerana panggilan alatan ialah cara ejen berfungsi. Ia membaca fail, menulis patch, menjalankan ujian, kemudian membaca kegagalan dan mencuba semula. Model yang tidak boleh mengeluarkan panggilan alatan akan menerangkan suntingan dalam bentuk prosa dan bukannya melaksanakannya, lalu menyebabkan ejen bergelung atau terhenti. Cari label tools pada halaman model di ollama.com sebelum anda memuat turun. qwen3-coder:30b menyokongnya, dan setakat Ogos 2026, tag tersebut merupakan muat turun bersaiz 19 GB dengan tetingkap konteks 256K. Jika pelayan anda hanya menggunakan CPU atau kekurangan RAM, pengiraan memori untuk tag Qwen 27B pada VPS menunjukkan apa yang sebenarnya muat dalam 8 hingga 64 GB sebelum anda memulakan muat turun.

Sekarang, sahkan nama model yang sebenarnya disediakan oleh pelayan:

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

Rentetan dalam respons tersebut ialah perkara yang mesti terkandung dalam konfigurasi ejen anda, aksara demi aksara. Menyemaknya terlebih dahulu dapat menyelesaikan kebanyakan ralat model-tidak-ditemui. Jika Ollama belum dipasang, panduan yang lebih panjang terdapat dalam pengehosan kendiri LLM dengan Ollama pada VPS.

Menghalakan OpenCode ke Ollama

Sunting ~/.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"
        }
      }
    }
  }
}

Kunci di bawah models ialah nama model yang dihantar ke Ollama, jadi ia mestilah sepadan dengan ollama ls dengan tepat. Medan name hanyalah label dalam pemilih model. Mulakan opencode, tukar kepada penyedia Ollama, dan pantau journalctl -e -u ollama untuk mengesahkan permintaan tersebut sampai ke pelayan anda dan bukannya ke tempat lain. Penyediaan ejen itu sendiri diliputi dalam menjalankan OpenCode pada VPS.

Halakan 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 dibiarkan sebagai rentetan kosong. Kunci sebenar yang dibiarkan dalam persekitaran akan menghantar permintaan anda ke API yang dihoskan, yang menyebabkan anda dikenakan bayaran dan tiada inferens tempatan dilakukan. ollama launch claude menetapkan semua ini untuk anda.

Fahami perkara yang tidak disertakan oleh lapisan keserasian. Ia tidak melaksanakan tool_choice atau caching prompt, dan ia tidak mempunyai endpoint pengiraan token, jadi nombor token yang anda lihat adalah anggaran daripada tokenizer model itu sendiri. Claude Code juga menghantar prompt sistem yang besar dan set alat yang besar, jadi ia memerlukan lebih banyak konteks berbanding klien sembang. Soalan yang lebih luas tentang perkara yang dibawa bersama dan perkara yang tidak disertakan diliputi dalam sama ada anda boleh mengehos sendiri Claude.

Menghalakan Aider ke Ollama

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

Dokumentasi Aider mengesyorkan awalan ollama_chat/ berbanding ollama/. Ia juga membolehkan anda menetapkan tetingkap konteks bagi setiap model dalam .aider.model.settings.yml, yang berguna apabila sesuatu model memerlukan tetingkap yang berbeza daripada lalai pelayan:

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

Mengapa persediaan yang berfungsi masih menghasilkan maklumat tidak masuk akal

Ini adalah bahagian yang penting. Ollama memilih panjang konteks lalai daripada VRAM (memori video pada GPU) yang dapat dikesan, dan nilai lalai tersebut telah diterbitkan:

[
  {
    "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"
  }
]

Kebanyakan pelan VPS, dan setiap pelayan yang hanya menggunakan CPU, berada dalam baris pertama: 4,096 token. Hanya GPU yang besar mendapat 262,144 token dalam baris terakhir.

Sesuatu ejen akan menggunakan 4096 token sebelum ia melakukan sebarang kerja. Prompt sistem, definisi alat, senarai repositori, dan fail pertama yang dibuka sudah pun melebihi saiz tersebut. Masalah sebenar berlaku selepas itu: tiada ralat yang dipaparkan. Dokumentasi Aider menyatakan bahawa Ollama membuang konteks yang melebihi tetingkap secara senyap. Token yang paling lama akan dibuang, jadi model tersebut menjawab dengan yakin tentang fail yang tidak lagi dapat dilihatnya, atau melupakan arahan yang anda berikan dua langkah sebelumnya. Mekanisme itulah punca kebanyakan laporan yang mengatakan model tempatan terlalu lemah untuk menulis kod.

Dokumentasi Ollama menyatakan bahawa tugasan seperti ejen dan alat pengekodan harus ditetapkan kepada sekurang-kurangnya 64000 token. Tetapkan nilai ini pada pelayan:

sudo systemctl edit ollama.service

Tambahkan baris ini dalam fail override:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Kemudian muat semula dan mulakan semula:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps ialah semakan. Ia mencetak lajur CONTEXT, dan nombor tersebut adalah apa yang sebenarnya diterima oleh model. ID dan SIZE anda akan berbeza:

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

Tetapkan nilai ini pada pelayan dan bukannya dalam ejen, atas dua sebab. Skema OpenAI chat completions tidak mempunyai medan untuk panjang konteks, jadi klien yang serasi dengan OpenAI tidak boleh memintanya. Selain itu, tetapan ini adalah untuk setiap pelayan, jadi setiap ejen yang anda halakan ke kotak tersebut akan mewarisinya. Jika satu model memerlukan tetingkap yang berbeza, masukkan tetapan tersebut ke dalam salinan dengan Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Konteks tidak percuma. Tetingkap yang lebih panjang memerlukan lebih banyak memori, jadi perhatikan lajur PROCESSOR. 100% GPU adalah apa yang anda mahukan. Apabila sebahagian daripada model melimpah ke CPU, kadar token akan jatuh sehingga gelung ejen menjadi tidak boleh digunakan, dan mengukur token sesaat pada LLM tempatan adalah cara anda mencari had sebenar untuk kotak anda. Penentuan saiz mesin sebelum anda membelinya dibincangkan dalam berapa banyak RAM dan CPU yang diperlukan oleh VPS ejen pengekodan.

Pastikan model kekal dimuatkan antara permintaan

Secara lalai, Ollama akan memunggah model 5 minit selepas permintaan terakhir. Tetapan ini sesuai untuk kotak sembang tetapi tidak sesuai untuk kerja ejen. Anda berhenti seketika untuk membaca diff, pemasa tamat, dan permintaan seterusnya akan memuatkan semula berpuluh-puluh gigabait pemberat (weights) daripada cakera sebelum token pertama muncul. Keadaan ini kelihatan seperti sistem tergantung.

OLLAMA_KEEP_ALIVE menerima rentetan tempoh seperti 10m atau 24h, angka saat yang biasa, -1 untuk memastikan model kekal dimuatkan selama-lamanya, atau 0 untuk memunggah serta-merta. Tetapkan nilai ini bersebelahan dengan panjang konteks:

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

Medan permintaan keep_alive hanya wujud pada endpoint /api/generate dan /api/chat asli Ollama, bukan pada endpoint keserasian, jadi ejen tidak boleh menetapkannya bagi setiap permintaan. Pemboleh ubah persekitaran (environment variable) ialah satu-satunya kawalan yang anda miliki. Apabila anda memerlukan memori tersebut kembali, ollama stop qwen3-coder:30b akan memunggah model tanpa menghentikan pelayan.

Menjalankan Ollama pada pelayan berasingan

Ollama terikat pada localhost. Untuk mencapainya dari mesin lain, tetapkan OLLAMA_HOST=0.0.0.0:11434 dalam override systemd yang sama dan mulakan semula servis tersebut.

Lakukan perkara ini hanya pada rangkaian peribadi. Dokumentasi Ollama menyatakan bahawa tiada pengesahan diperlukan untuk API tempatan, jadi port 11434 yang terbuka kepada internet bermakna sesiapa sahaja boleh menggunakan perkakasan anda dan membaca apa sahaja yang dihantar oleh ejen anda. Terdapat dua pilihan yang selamat. Kekalkan ikatan pada localhost dan majukan port tersebut melalui SSH dari komputer riba anda:

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

Ejen anda terus menghala ke http://localhost:11434/v1 dan tidak mengetahui sebarang perbezaan. Pilihan lain ialah VPN, dengan Ollama terikat pada alamat VPN dan bukannya 0.0.0.0. Jika beberapa orang atau beberapa ejen berkongsi satu mesin, penjadual Ollama tidak dibina untuk beban tersebut, dan perbandingan antara Ollama dan vLLM menunjukkan di mana perbezaan throughput mula menjejaskan prestasi.

Di mana model pengekodan tempatan lebih baik, dan di mana ia tidak

Ejen yang dipacu oleh model yang anda hoskan sendiri tidak menggantikan API frontier bagi setiap tugasan. Ia jelas lebih baik dalam empat jenis kerja.

• Suntingan mekanikal pukal, di mana setiap perubahan adalah kecil dan anda boleh menyemaknya. Menamakan semula merentasi repositori, menambah type hints, menulis docstring, menterjemah komen. Model berjalan selama berjam-jam dan bil tidak meningkat.
• Kerja yang tidak boleh keluar dari perkakasan anda. Kod pelanggan di bawah perjanjian kerahsiaan, atau repositori dalaman yang anda tidak dibenarkan untuk hantar kepada pihak ketiga.
• Mesin luar talian dan air-gapped, di mana tiada API dihoskan untuk dipanggil sama sekali.
• Kos yang boleh diramal. Sebaik sahaja pelayan dibayar, ejen yang menggunakan token secara berulang tidak menelan kos tambahan, yang bertentangan dengan API bermeter. Di mana GPU VPS mencapai titik pulang modal berbanding token API mempunyai pengiraan tersebut.

Ia kalah dalam tugasan berbilang langkah yang panjang. "Cari punca ujian ini gagal, baiki puncanya, kemas kini pemanggil" memerlukan banyak panggilan alat yang betul secara berturut-turut, dengan keseluruhan sejarah masih dalam konteks. Model dalam julat 8B hingga 14B pada pelayan yang sederhana akan menghasilkan panggilan alat yang cacat, atau hilang arah selepas beberapa pusingan, dan anda menghabiskan lebih banyak masa mengawalnya berbanding masa yang diambil untuk menyiapkan tugasan tersebut. Itu bukan masalah prompt yang boleh diselesaikan dengan penulisan. Ia adalah masalah kapasiti.

Ia juga kalah apabila kesilapan membawa kos yang tinggi dan anda tidak akan membaca setiap baris. Berikan model tempatan tugasan yang khusus yang outputnya anda boleh sahkan, dan kekalkan model dihoskan untuk kerja yang anda tidak akan semak langkah demi langkah.

Mod kegagalan dan rentetan yang akan anda lihat

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Pelayan tidak berjalan, atau ejen dihalakan ke hos yang berbeza. Jalankan systemctl status ollama, kemudian journalctl -e -u ollama.

Ejen melaporkan bahawa model tidak wujud. Nama dalam konfigurasi anda tidak sepadan dengan nama yang disediakan oleh pelayan. Bandingkan dengan curl http://localhost:11434/v1/models dan salin rentetan daripada situ. Tag adalah sebahagian daripada nama, jadi konfigurasi yang menamakan tag yang tidak pernah anda tarik akan gagal walaupun model yang serupa telah dipasang.

Ejen menjawab dalam bentuk prosa dan tidak pernah menyunting fail. Sama ada model tidak mempunyai sokongan alat, atau permintaan berserta definisi alatnya telah memenuhi tetingkap konteks. Semak label tools pada halaman model, kemudian semak lajur CONTEXT dalam ollama ps.

Keheningan yang lama sebelum token pertama, kemudian kelajuan kembali normal. Tempoh keep-alive telah tamat dan pemberat sedang dibaca semula daripada cakera. Tetapkan OLLAMA_KEEP_ALIVE.

Model bercanggah dengan fail yang baru dibacanya. Pemotongan konteks (context truncation). ollama ps biasanya menunjukkan nilai CONTEXT yang lebih kecil daripada yang anda sangka telah ditetapkan, kerana pemboleh ubah persekitaran (environment variable) telah pergi ke shell anda dan bukannya ke unit systemd.

Semuanya berfungsi, tetapi perlahan, dan PROCESSOR bukan 100% GPU. Model berserta konteksnya tidak muat dalam VRAM. Kurangkan panjang konteks, atau beralih kepada model yang lebih kecil atau kuantisasi yang lebih rendah.

FAQ

Bolehkah saya menghalakan Claude Code ke Ollama?

Boleh, tetapi bukan dengan URL yang serasi dengan OpenAI. Claude Code menggunakan Anthropic Messages API, dan Ollama menyediakan bentuk tersebut pada /v1/messages pada port 11434 yang sama. Eksport ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama dan ANTHROPIC_API_KEY yang kosong, kemudian mulakannya dengan claude --model qwen3-coder:30b. ollama launch claude akan menulis tetapan yang sama untuk anda. Lapisan keserasian ini tidak melaksanakan tool_choice atau caching prompt, dan ia tidak mempunyai endpoint pengiraan token, jadi jumlah token yang dilaporkan hanyalah anggaran.

Mengapakah model tempatan saya menjawab tentang kod yang tidak dapat dilihatnya?

Ini kerana permintaan tersebut tidak lagi muat dalam tetingkap konteks, dan bahagian paling lama telah digugurkan tanpa ralat. Ollama menetapkan konteks lalainya berdasarkan VRAM yang dikesan, dan di bawah 24 GiB, nilai lalai tersebut ialah 4,096 token, yang mana prompt sistem dan definisi alat ejen sendiri sudah melebihi jumlah tersebut. Tetapkan OLLAMA_CONTEXT_LENGTH=64000 dalam unit systemd, mulakan semula Ollama, dan sahkan bahawa lajur CONTEXT dalam ollama ps menunjukkan nilai baharu tersebut.

Model manakah yang patut saya jalankan untuk ejen pengekodan pada VPS?

Pilih model terbesar yang membawa label tools yang masih muat dalam memori dengan tetingkap konteks 64k, dan utamakan model yang ditala untuk kod. qwen3-coder:30b ialah jawapan biasa pada pelayan GPU yang mempunyai VRAM mencukupi. Di bawah kira-kira 14B parameter, sesebuah model mungkin masih boleh menjawab soalan tentang kod dengan baik tetapi gagal melakukan suntingan berbilang langkah, kerana kerja ejen akan menghukum kesilapan pemformatan kecil dalam panggilan alat. Uji dengan satu tugasan sebenar daripada repositori anda sendiri dan bukannya menggunakan prompt contoh.

Adakah saya memerlukan GPU untuk menjalankan ejen pengekodan pada model saya sendiri?

Secara praktikalnya, ya. Inferens menggunakan CPU sahaja boleh berfungsi dan memadai untuk soalan tunggal, tetapi ejen menghantar banyak permintaan bagi setiap tugasan dan setiap permintaan membaca semula sejarah yang panjang, jadi kadar token yang perlahan akan menjadikan tugasan dua minit mengambil masa selama sejam. Semak lajur PROCESSOR dalam ollama ps: sebarang nilai selain daripada 100% GPU bermakna sebahagian daripada model sedang berjalan pada CPU, dan kadar token akan jatuh dengan mendadak.