Jinsi ya kutumia Ollama na coding agent wako

Unachounganisha

Unaweza kutumia Ollama pamoja na wakala wako wa uandishi wa msimbo (coding agent), na muunganisho huo ni rahisi kuliko watu wanavyodhani. Unabadilisha URL moja ya msingi na kuchagua jina moja la model. Sehemu ya API key bado inahitaji thamani, lakini seva ya ndani huipuuza, kwa hivyo kamba yoyote ya herufi inafanya kazi.

Ollama husikiliza kwenye port 11434 na kuhudumia maumbo mawili ya maombi kwa wakati mmoja. /v1/chat/completions ni umbo linalooana na OpenAI, na nyaraka za Ollama zinaelezea kuwa ufunguo hapo unahitajika lakini hupuuzwa. /v1/messages ni umbo linalooana na Anthropic, ambalo ndilo linalotumiwa na Claude Code. Wakala wako tayari anatumia mojawapo ya hayo mawili, kwa hivyo hakuna kingine kinachobadilika.

Sehemu hiyo inachukua dakika tano. Ikiwa matokeo yatatumika inategemea mipangilio miwili ambayo karibu hakuna mtu anayebadilisha, urefu wa muktadha (context length) na keep-alive, na kumpa model aina ya kazi ambayo ni nzuri kwake. Zote mbili zina sehemu yake maalum, na mipaka ya kweli iko mwishoni.

Ni mawakala gani wa uandishi wa msimbo wanaokubali base URL ya ndani

Jaribio ni swali moja: je, zana hiyo inatoa mpangilio wa base URL? Ikiwa inatoa, inaweza kuwasiliana na seva yako.

Ollama huchapisha kurasa za ushirikiano kwa ajili ya Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDEs na VS Code. Aider huandika nyaraka zake za usaidizi wa Ollama kando. Hiyo inashughulikia sehemu kubwa ya kile watu wanachomaanisha kwa wakala wa uandishi wa msimbo mnamo Agosti 2026. Sio wote wanaozungumza lugha moja ya kiufundi, na tofauti hiyo ndipo usanidi unaposhindwa.

• Mawakala wengi wanataka endpoint inayooana na OpenAI. Wape base URL http://localhost:11434/v1 na kamba yoyote ya API key isiyo tupu.
• Claude Code haikubali base URL ya OpenAI hata kidogo. Inatumia Anthropic Messages API, kwa hivyo inahitaji ANTHROPIC_BASE_URL kuwekwa kuwa http://localhost:11434, ambapo Ollama hutoa /v1/messages.
• Codex hutumia OpenAI Responses API. Ollama hutoa /v1/responses pia, iliyoongezwa katika toleo la 0.13.3.
• Wakala asiye na mpangilio wa base URL hawezi kuelekezwa kwingine, kwa sababu endpoint imejengwa ndani ya mteja. Weka safu ya utafsiri mbele yake, kama vile gateway ya LiteLLM inayojiendesha, na uweke upya modeli yako katika umbo lolote ambalo mteja anahitaji.

Ollama inaweza kukuandikia usanidi huu. ollama launch opencode huanzisha OpenCode na usanidi wa ndani kwa ajili ya modeli unayochagua, ollama launch claude hufanya vivyo hivyo kwa Claude Code, na ollama launch droid --config huandika usanidi bila kuzindua zana hiyo.

Sakinisha Ollama na uvute modeli inayoweza kutumia zana

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

Kisakinishi huongeza unit ya systemd na kuianzisha, kwa hivyo systemctl status ollama inapaswa kutoa active (running). Ikiwa haifanyi hivyo, journalctl -e -u ollama itaonyesha sababu.

Modeli lazima iunge mkono utumiaji wa zana (tool calling), kwa sababu utumiaji wa zana ndio njia ambayo wakala (agent) hufanya kazi. Inasoma faili, inaandika patch, inaendesha jaribio, kisha inasoma hitilafu na kujaribu tena. Modeli isiyoweza kutoa wito wa zana itaelezea marekebisho kwa lugha ya kawaida badala ya kuyafanya, na wakala atazunguka bila mwisho au kusimama. Tafuta lebo ya tools kwenye ukurasa wa modeli katika ollama.com kabla ya kuivuta. qwen3-coder:30b inayo, na kufikia Agosti 2026 tag hiyo ni download ya 19 GB yenye dirisha la muktadha (context window) la 256K. Ikiwa seva yako inatumia CPU pekee au ina RAM ndogo, hesabu za kumbukumbu kwa ajili ya tag ya Qwen 27B kwenye VPS zinaonyesha kile kinachotoshea katika 8 hadi 64 GB kabla ya kutumia data kwa download. Mara tu unapovuta modeli hiyo, gigabytes hizo huwekwa kwenye root disk ya seva, ambayo ni sehemu ya VPS yenye nafasi ndogo zaidi, kwa hivyo mahali ambapo Ollama huhifadhi faili zake za modeli na jinsi ya kuzihamishia kwingine inafaa kusomwa kabla diski haijajaa.

Sasa thibitisha ni majina yapi ambayo seva inatoa:

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

Vipande vya maandishi (strings) katika jibu hilo ndivyo ambavyo usanidi wa wakala wako lazima uwe navyo, herufi kwa herufi. Kukagua hili kwanza hutatua hitilafu nyingi za "model not found". Ikiwa Ollama bado haijasakinishwa, mwongozo mrefu zaidi unapatikana katika kujihudumia LLM kwa kutumia Ollama kwenye VPS.

Elekeza OpenCode kwenye Ollama

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

Ufunguo ulio chini ya models ni jina la model linalotumwa kwa Ollama, kwa hivyo lazima lilingane na ollama ls kikamilifu. Sehemu ya name ni lebo tu inayotumika kwenye kiteuzi cha model. Anzisha opencode, badilisha hadi kwa mtoa huduma wa Ollama, na ufuatilie journalctl -e -u ollama ili kuthibitisha kuwa ombi limefika kwenye seva yako badala ya mahali pengine. Usanidi wa agent wenyewe umeelezwa katika kuendesha OpenCode kwenye VPS.

Elekeza Claude Code kwenye 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 imewekwa kuwa kamba tupu kwa makusudi. Ufunguo halisi ukibaki kwenye mazingira (environment) utatuma maombi yako kwenye API inayohudumiwa (hosted API) badala yake, jambo litakalokuletea bili na kukosa inference ya ndani. ollama launch claude hukuwekea haya yote.

Elewa kile ambacho safu ya utangamano (compatibility layer) inakiacha. Haitekelezi tool_choice wala prompt caching, na haina endpoint ya kuhesabu token, kwa hivyo namba za token unazoziona ni makadirio kutoka kwa tokenizer ya modeli yenyewe. Claude Code pia husafirisha system prompt kubwa na seti kubwa ya zana, kwa hivyo inahitaji muktadha (context) zaidi kuliko mteja wa gumzo (chat client). Swali pana zaidi la kile kinachohamishwa na kisichohamishwa limefafanuliwa katika kama unaweza kujiendeshea Claude mwenyewe.

Kuelekeza Aider kwenye Ollama

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

Nyaraka za Aider zinapendekeza prefix ya ollama_chat/ badala ya ollama/. Pia inakuruhusu kuweka kikomo cha context window kwa kila model ndani ya .aider.model.settings.yml, jambo ambalo ni muhimu wakati model moja inahitaji window tofauti na ile ya default ya seva:

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

Kwa nini usanidi unaofanya kazi bado unatoa matokeo yasiyo na maana

Hii ndiyo sehemu muhimu zaidi. Ollama huchagua urefu wa muktadha (context length) kwa msingi wa VRAM (kumbukumbu ya video kwenye GPU) inayoiona, na mipangilio hiyo ya awali imechapishwa hapa:

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

Mipango mingi ya VPS, na kila seva inayotumia CPU pekee, huangukia kwenye safu ya kwanza: 4,096 tokens. GPU kubwa pekee ndiyo hupata 262,144 tokens zilizopo kwenye safu ya mwisho.

Wakala (agent) hupitisha tokens 4096 kabla ya kuanza kazi yoyote. Prompt ya mfumo, ufafanuzi wa zana, orodha ya hazina (repository) na faili ya kwanza inayofunguliwa tayari ni kubwa kuliko hiyo. Kinachotokea baadaye ndilo tatizo zima: hakuna kosa linalotokea. Nyaraka za Aider zinaeleza kuwa Ollama hutupa kimya kimya muktadha unaozidi dirisha hilo. Tokens za zamani zaidi hupotea, kwa hivyo modeli hujibu kwa ujasiri kuhusu faili ambayo haiwezi tena kuiona, au husahau maelekezo uliyotoa hatua mbili zilizopita. Utaratibu huo ndio chanzo cha ripoti nyingi zinazosema modeli ya ndani ni "mjinga" sana kuandika msimbo. Kuchagua namba hiyo yenyewe ni uamuzi wa kipekee, na gharama ya num_ctx katika kumbukumbu ya KV cache kwa kila ukubwa inafaa kusomwa kabla ya kuamua namba moja.

Nyaraka za Ollama zinasema kazi kama mawakala na zana za uandishi wa msimbo zinapaswa kuwekwa angalau tokens 64000. Iweke kwenye seva:

sudo systemctl edit ollama.service

Ongeza mistari hii kwenye faili ya override:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Kisha pakia upya na uanzishe upya:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps ndiyo njia ya kukagua. Inachapisha safu ya CONTEXT, na namba hiyo ndiyo ambayo modeli imepokea kihalisi. ID yako na SIZE yako zitatofautiana:

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

Iweke kwenye seva badala ya kwenye wakala, kwa sababu mbili. Schema ya OpenAI chat completions haina sehemu ya urefu wa muktadha, kwa hivyo mteja anayefuata viwango vya OpenAI hawezi kuomba urefu huo. Na mpangilio huo ni kwa kila seva, kwa hivyo kila wakala unaoelekeza kwenye kisanduku hicho utaurithi. Upande wa matokeo una kikomo chake, na tofauti na urefu wa muktadha, unapitishwa kupitia endpoint ya utangamano, kwa hivyo num_predict na sehemu ya max_tokens inayoiwakilisha ndiyo unayopaswa kuitumia wakati jibu linapokwama katikati ya patch. Ikiwa modeli moja inahitaji dirisha tofauti, iweke kwenye nakala kwa kutumia Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Muktadha hauji bure. Dirisha refu zaidi hugharimu kumbukumbu zaidi, kwa hivyo fuatilia safu ya PROCESSOR. 100% GPU ndicho unachotaka. Mara tu sehemu ya modeli inapohamia kwenye CPU, kasi ya tokens hushuka kiasi kwamba mzunguko wa wakala hauwezi kutumika tena, na kupima tokens kwa sekunde kwenye LLM ya ndani ndiyo njia ya kupata kikomo halisi cha mashine yako. Ukubwa wa mashine kabla ya kuinunua umeelezwa katika kiasi cha RAM na CPU kinachohitajika na VPS ya wakala wa uandishi wa msimbo.

Weka model ikiwa imepakiwa kati ya maombi

Kwa chaguomsingi, Ollama huondoa model kwenye kumbukumbu dakika 5 baada ya ombi lake la mwisho. Hii inafaa kwa kisanduku cha gumzo lakini haifai kwa kazi za wakala (agent work). Unaposimama kusoma diff, kipima muda huisha, na ombi linalofuata hupakia upya makumi ya gigabytes ya weights kutoka kwenye diski kabla ya token ya kwanza kuonekana. Hii huonekana kama mfumo umekwama.

OLLAMA_KEEP_ALIVE huchukua kamba ya muda (duration string) kama vile 10m au 24h, namba ya sekunde, -1 ili kuweka model ikiwa imepakiwa bila kikomo, au 0 ili kuiondoa mara moja. Iweke kando ya urefu wa muktadha (context length):

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

Sehemu ya ombi ya keep_alive ipo kwenye endpoints asilia za Ollama pekee, yaani /api/generate na /api/chat, si kwenye endpoints za utangamano (compatibility endpoints), kwa hivyo wakala hawezi kuiweka kwa kila ombi. Environment variable ndiyo njia pekee uliyo nayo. Unapohitaji kumbukumbu hiyo irudi, ollama stop qwen3-coder:30b huondoa model bila kusimamisha seva. Ikiwa unataka mpangilio huu udumu baada ya reboot, au unataka kupima faida ya kuweka weights kwenye kumbukumbu siku nzima dhidi ya kurudisha kumbukumbu hiyo, kuweka model ya Ollama ikiwa imepakiwa kwenye kumbukumbu hufanya kazi kwa njia zote mbili.

Kukimbiza Ollama kwenye seva tofauti

Ollama hufungika kwenye localhost. Ili kuifikia kutoka mashine nyingine, weka OLLAMA_HOST=0.0.0.0:11434 kwenye override ile ile ya systemd na uanzishe upya huduma hiyo.

Fanya hivyo kwenye mtandao wa ndani pekee. Nyaraka za Ollama zinaeleza kuwa hakuna uthibitishaji unaohitajika kwa API ya ndani, kwa hivyo port 11434 ikiwa wazi kwenye Internet inamaanisha mtu yeyote anaweza kutumia vifaa vyako na kusoma chochote ambacho wakala wako anatuma. Kuna chaguo mbili salama. Acha bind kwenye localhost na upeleke port hiyo kupitia SSH kutoka kwenye laptop yako:

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

Wakala wako ataendelea kuelekeza kwenye http://localhost:11434/v1 na hatatambua tofauti yoyote. Chaguo jingine ni VPN, huku Ollama ikiwa imefungwa kwenye anwani ya VPN badala ya 0.0.0.0. Ikiwa watu kadhaa au mawakala kadhaa watashiriki seva moja, kipanga ratiba (scheduler) cha Ollama hakijajengwa kwa ajili ya mzigo huo, na ulinganisho kati ya Ollama na vLLM unaonyesha mahali ambapo tofauti ya throughput inapoanza kuleta athari.

Wakati modeli ya kodi ya ndani inaposhinda, na wakati haishindi

Wakala anayeendeshwa na modeli unayoiendesha mwenyewe haichukui nafasi ya API ya kiwango cha juu (frontier API) katika kila kazi. Inashinda wazi katika aina nne za kazi.

• Marekebisho ya jumla ya kiufundi, ambapo kila mabadiliko ni madogo na unaweza kuyakagua. Kubadilisha majina katika repository nzima, kuongeza type hints, kuandika docstrings, na kutafsiri maoni. Modeli inaweza kufanya kazi kwa saa nyingi bila gharama kuongezeka.
• Kazi ambazo hazipaswi kutoka kwenye maunzi (hardware) yako. Kodi ya mteja iliyo chini ya mkataba wa usiri, au repository ya ndani ambayo huna ruhusa ya kuituma kwa wahusika wengine.
• Mashine zilizotengwa na mtandao (offline na air-gapped), ambapo hakuna API ya mtandaoni inayoweza kupatikana.
• Gharama inayotabirika. Mara tu seva inapolipwa, wakala anayetumia token nyingi katika mzunguko haongezi gharama yoyote, tofauti na API inayotoza kwa matumizi. Wakati GPU VPS inapofikia uwiano wa gharama dhidi ya token za API ina maelezo ya hesabu hizo.

Inashindwa katika kazi ndefu zenye hatua nyingi. "Tafuta kwa nini jaribio hili linashindwa, rekebisha chanzo, sasisha wanaoliita" inahitaji mfululizo wa wito wa zana (tool calls) sahihi, huku historia nzima ikiwa bado kwenye muktadha. Modeli iliyo katika kiwango cha 8B hadi 14B kwenye seva ya kawaida itatoa wito wa zana usio sahihi, au itapoteza mpango baada ya hatua chache, na utatumia muda mwingi kuiongoza kuliko kazi yenyewe ingechukua. Hilo si tatizo la prompt unaloweza kulitatua kwa kuandika maelekezo zaidi. Ni suala la uwezo wa modeli.

Pia inashindwa wakati wowote ambapo kukosea ni ghali na hutaweza kusoma kila mstari. Ipe modeli ya ndani kazi ndogo ambazo unaweza kuzikagua matokeo yake, na utumie modeli ya mtandaoni kwa kazi ambazo huwezi kuzikagua hatua kwa hatua.

Njia za hitilafu, na ujumbe utakaouona

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Seva haifanyi kazi, au wakala (agent) imeelekezwa kwenye host nyingine. Tekeleza systemctl status ollama, kisha journalctl -e -u ollama.

Wakala anaripoti kuwa model haipo. Jina lililo kwenye config yako halilingani na jina linalotolewa na seva. Lilinganishe na curl http://localhost:11434/v1/models na unakili kamba (string) ya jina kutoka hapo. Tag ni sehemu ya jina, kwa hivyo config inayotaja tag ambayo hujawahi kuipakua itafeli hata kama model inayofanana imewekwa.

Wakala anajibu kwa maelezo marefu na hahariri faili. Aidha model haina uwezo wa kutumia zana (tool support), au ombi pamoja na ufafanuzi wa zana zake tayari vimejaza dirisha la muktadha (context window). Angalia lebo ya tools kwenye ukurasa wa model, kisha angalia safu ya CONTEXT katika ollama ps.

Ukimya mrefu kabla ya token ya kwanza, kisha kasi ya kawaida. Muda wa keep-alive umeisha na uzito (weights) unasomwa kutoka kwenye diski tena. Weka OLLAMA_KEEP_ALIVE.

Model inapingana na faili iliyosoma punde. Ufupishaji wa muktadha (context truncation). ollama ps kwa kawaida huonyesha thamani ya CONTEXT ndogo kuliko unayodhani umeweka, kwa sababu variable ya mazingira (environment variable) ilienda kwenye shell yako badala ya kwenda kwenye unit ya systemd.

Kila kitu kinafanya kazi, lakini kwa polepole, na PROCESSOR si 100% GPU. Model pamoja na muktadha wake haitoshi kwenye VRAM. Punguza urefu wa muktadha, au hamia kwenye model ndogo zaidi au quantisation ndogo zaidi. Kabla ya kupakua tena, gharama ya kumbukumbu ya q4_K_M, q8_0 na fp16, na mahali ambapo ubora hupungua inakuonyesha nafasi unayopata kwa kupunguza hatua moja na kile unachopoteza kwa kufanya hivyo.

FAQ

Je, ninaweza kuelekeza Claude Code kwenye Ollama?

Ndiyo, lakini si kwa kutumia URL inayooana na OpenAI. Claude Code hutumia Anthropic Messages API, na Ollama hutoa umbo hilo kwenye /v1/messages katika port ileile ya 11434. Hamisha ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama na ANTHROPIC_API_KEY tupu, kisha uianzishe kwa claude --model qwen3-coder:30b. ollama launch claude hukuandikia mipangilio hiyo hiyo. Safu ya uoanifu haitekelezi tool_choice au prompt caching, na haina endpoint ya kuhesabu token, kwa hivyo idadi ya token inayoonyeshwa ni makadirio tu.

Kwa nini modeli yangu ya ndani inajibu kuhusu msimbo (code) ambao haiwezi kuona?

Kwa sababu ombi hilo halitoshei tena kwenye context window, na sehemu ya zamani zaidi iliondolewa bila kutoa hitilafu. Ollama huweka context yake ya msingi kulingana na VRAM inayoipata, na chini ya 24 GiB, thamani hiyo ya msingi ni 4,096 token, ambazo system prompt ya wakala na ufafanuzi wa zana (tool definitions) huzidi kiasi hicho zenyewe. Weka OLLAMA_CONTEXT_LENGTH=64000 kwenye systemd unit, anzisha upya Ollama, na uthibitishe kuwa safu ya CONTEXT katika ollama ps inaonyesha thamani mpya.

Ni modeli ipi ninayopaswa kutumia kwa wakala wa uandishi wa msimbo kwenye VPS?

Chagua modeli kubwa zaidi yenye lebo ya tools ambayo bado inatoshea kwenye kumbukumbu (memory) ikiwa na 64k context window, na upendelee ile iliyoboreshwa kwa ajili ya msimbo. qwen3-coder:30b ndiyo jibu la kawaida kwenye seva ya GPU yenye VRAM ya kutosha. Ikiwa tag hiyo ni kubwa mno kwa seva yako, takwimu za RAM na kasi ya CPU pekee kwa ajili ya Nemotron 3.5 Lightning ni kulinganisha muhimu kabla ya kuanza kupakua. Chini ya takriban vigezo 14B (parameters), modeli inaweza kujibu maswali kuhusu msimbo vizuri lakini ikashindwa kufanya marekebisho ya hatua nyingi, kwa sababu kazi ya wakala huadhibu makosa madogo ya umbizo (formatting) katika wito wa zana (tool calls). Jaribu kwa kazi moja halisi kutoka kwenye hazina (repository) yako badala ya kutumia prompt ya mfano.

Je, ninahitaji GPU ili kuendesha wakala wa uandishi wa msimbo kwenye modeli yangu mwenyewe?

Kiutendaji, ndiyo. Inference ya CPU pekee hufanya kazi na inafaa kwa maswali ya mara moja, lakini wakala hutuma maombi mengi kwa kila kazi na kila moja husoma upya historia ndefu, kwa hivyo kasi ndogo ya token hubadilisha kazi ya dakika mbili kuwa ya saa nzima. Angalia safu ya PROCESSOR katika ollama ps: thamani yoyote isiyo 100% GPU inamaanisha kuwa sehemu ya modeli inaendeshwa kwenye CPU, na kasi ya token hushuka kwa kasi.