Jinsi ya kutumia Ollama na coding agent

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 linaloendana na OpenAI, na nyaraka za Ollama zinaelezea kuwa ufunguo (key) hapo unahitajika lakini hupuuzwa. /v1/messages ni umbo linaloendana 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, pamoja 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, na tofauti hiyo ndipo usanidi unapofeli.

• 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. Inazungumza Anthropic Messages API, kwa hivyo inahitaji ANTHROPIC_BASE_URL kuwekwa kuwa http://localhost:11434, ambapo Ollama hutumikia /v1/messages.
• Codex hutumia OpenAI Responses API. Ollama hutumikia /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 badala yake, kama vile gateway ya LiteLLM inayojiendesha yenyewe, na uweke upya modeli yako katika umbo lolote ambalo mteja anahitaji.

Ollama inaweza kukuandikia usanidi huu. ollama launch opencode huanzisha OpenCode ikiwa 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 kuonyesha active (running). Ikiwa haionyeshi 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 kikomo au kusimama. Tafuta lebo ya tools kwenye ukurasa wa modeli katika ollama.com kabla ya kuivuta. qwen3-coder:30b inayo lebo hiyo, 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 tag ya Qwen 27B kwenye VPS zinaonyesha kile kinachotoshea katika 8 hadi 64 GB kabla ya kutumia data kwa download.

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 kujihostia LLM na 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 wakala 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 ukiachwa kwenye mazingira (environment) utatuma maombi yako kwenye API inayopangishwa (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) inakosa. Haitekelezi tool_choice au 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 kinachohamishika na kile kisichohamishika limefafanuliwa katika kama unaweza kuji-host Claude.

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 kiambishi awali cha ollama_chat/ badala ya ollama/. Pia inakuruhusu kuweka kikomo cha dirisha la muktadha (context window) kwa kila model katika .aider.model.settings.yml, jambo ambalo ni muhimu wakati model moja inahitaji dirisha tofauti na lile lililowekwa na seva kama chaguo-msingi:

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

Kwa nini usanidi unaofanya kazi bado unatoa majibu yasiyo na maana

Hii ndiyo sehemu muhimu. Ollama huchagua urefu wa context chaguo-msingi kulingana na VRAM (kumbukumbu ya video kwenye GPU) inayoiona, na chaguo hizo zimechapishwa:

[
  {
    "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 tokens 262,144 zilizopo kwenye safu ya mwisho.

Wakala (agent) hupitisha tokens 4096 kabla ya kuanza kazi yoyote. System prompt, ufafanuzi wa zana (tool definitions), orodha ya hazina (repository listing) na faili la kwanza linalofunguliwa tayari ni kubwa kuliko hapo. Kinachotokea baadaye ndilo tatizo zima: hakuna kosa linalotokea. Nyaraka za Aider zinaeleza kuwa Ollama hufuta kimya kimya context inayozidi dirisha hilo. Tokens za zamani zaidi hupotea, hivyo modeli hujibu kwa ujasiri kuhusu faili ambalo haiwezi tena kuliona, au husahau maelekezo uliyotoa hatua mbili zilizopita. Utaratibu huo ndio chanzo cha ripoti nyingi zinazosema kuwa modeli ya ndani ni "mjinga" sana kuandika msimbo (code).

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

sudo systemctl edit ollama.service

Ongeza mistari hii kwenye faili la 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 na SIZE yako vitatofautiana:

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

Iweke kwenye seva badala ya kuweka kwenye wakala, kwa sababu mbili. Schema ya OpenAI chat completions haina sehemu ya urefu wa context, kwa hivyo mteja anayefuata viwango vya OpenAI hawezi kuomba urefu huo. Na mpangilio huo ni kwa kila seva, kwa hivyo kila wakala unaoelekeza kwenye seva hiyo utaurithi. 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

Context si ya bure. Dirisha refu zaidi hutumia kumbukumbu nyingi zaidi, kwa hivyo fuatilia safu ya PROCESSOR. 100% GPU ndicho unachotaka. Mara 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 ukomo halisi wa seva yako. Ukubwa wa mashine kabla ya kuinunua umeelezwa katika kiasi cha RAM na CPU kinachohitajika na VPS ya wakala wa kuandika msimbo.

Kuweka 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 mazungumzo 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"

Uga wa ombi wa keep_alive upo kwenye endpoints asilia za /api/generate na /api/chat za Ollama pekee, si kwenye endpoints za utangamano (compatibility endpoints), kwa hivyo wakala hawezi kuiweka kwa kila ombi. Variable ya mazingira (environment variable) ndiyo njia pekee uliyo nayo. Unapohitaji kumbukumbu hiyo irudi, ollama stop qwen3-coder:30b huondoa model bila kusimamisha seva.

Kukimbiza Ollama kwenye seva tofauti

Ollama hufungwa kwenye localhost. Ili kuifikia kutoka mashine nyingine, weka OLLAMA_HOST=0.0.0.0:11434 kwenye override ileile ya systemd kisha 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 maunzi yako na kusoma chochote ambacho wakala wako anatuma. Kuna chaguo mbili salama. Weka bind kwenye localhost na uelekeze 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 coding ya ndani inaposhinda, na wakati haishindi

Wakala anayeendeshwa na modeli unayoiweka kwenye seva yako haichukui nafasi ya API ya kiwango cha juu katika kila kazi. Inashinda wazi katika aina nne za kazi.

• Marekebisho ya kiufundi ya jumla, ambapo kila mabadiliko ni madogo na unaweza kuyakagua. Kubadilisha majina katika repository nzima, kuongeza type hints, kuandika docstrings, kutafsiri maoni. Modeli inaweza kufanya kazi kwa saa nyingi bila gharama kuongezeka.
• Kazi ambazo hazipaswi kutoka kwenye vifaa vyako. Msimbo wa mteja ulio chini ya mkataba wa usiri, au repository ya ndani ambayo huna ruhusa ya kuituma kwa wahusika wengine.
• Mashine za nje ya mtandao na zisizounganishwa na mtandao (air-gapped), ambapo hakuna API ya mtandaoni ya kuita.
• Gharama inayotabirika. Mara tu seva inapolipwa, wakala anayetumia token nyingi katika mzunguko haongezi gharama yoyote, jambo ambalo ni kinyume na API inayotozwa kulingana na matumizi. Wakati GPU VPS inapoanza kutoa faida ikilinganishwa na token za API ina hesabu zake.

Inashindwa katika kazi ndefu za hatua nyingi. "Tafuta kwa nini jaribio hili linashindwa, rekebisha chanzo, sasisha wanaoliita" inahitaji mfululizo wa miito ya zana (tool calls) sahihi, huku historia nzima ikiwa bado kwenye muktadha. Modeli iliyo katika kiwango cha 8B hadi 14B kwenye seva ya kawaida itatoa mwito 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 matokeo yake unaweza kuyathibitisha, 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 tofauti. 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 kisha nakili kamba (string) kutoka hapo. Tag ni sehemu ya jina, kwa hivyo config inayotaja tag ambayo hujawahi kuipakua itashindwa hata kama model inayofanana imewekwa.

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

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

Model inapingana na faili iliyosoma punde. Context truncation. ollama ps kwa kawaida huonyesha thamani ya CONTEXT ndogo kuliko unavyodhani umeweka, kwa sababu environment variable ilienda kwenye shell yako badala ya kwenda kwenye systemd unit.

Kila kitu kinafanya kazi, kwa polepole, na PROCESSOR sio 100% GPU. Model pamoja na context yake haitoshi kwenye VRAM. Punguza urefu wa context, au hamia kwenye model ndogo zaidi au quantisation ndogo zaidi.

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. Export 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 inayoripotiwa ni makadirio tu.

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

Kwa sababu ombi hilo halitoshei tena kwenye context window, na sehemu ya zamani zaidi iliondolewa bila kutoa error. Ollama huweka context yake ya msingi kulingana na VRAM inayoiona, na chini ya 24 GiB thamani hiyo ya msingi ni 4,096 token, ambayo system prompt ya wakala na ufafanuzi wa zana (tool definitions) huizidi peke yake. 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 kuendesha kwa ajili ya wakala wa msimbo (coding agent) kwenye VPS?

Chagua modeli kubwa zaidi yenye lebo ya tools ambayo bado inatoshea kwenye kumbukumbu (memory) ikiwa na 64k context window, na upendelee ile iliyosanifiwa kwa ajili ya msimbo. qwen3-coder:30b ndilo jibu la kawaida kwenye seva ya GPU yenye VRAM ya kutosha. Chini ya vigezo (parameters) 14B, modeli bado inaweza kujibu maswali kuhusu msimbo vizuri lakini ikafeli kwenye marekebisho ya hatua nyingi, kwa sababu kazi ya wakala huadhibu makosa madogo ya uumbizaji (formatting) katika tool calls. Jaribu kwa kutumia kazi moja halisi kutoka kwenye repository yako badala ya kutumia mfano wa prompt.

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

Kwa vitendo, 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 hugeuza kazi ya dakika mbili kuwa ya saa moja. 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 kiasi kikubwa.