SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

如何在 coding agent 使用 Ollama 本機模型

設定 Ollama 的 base URL 與任意 API key,避開 context length 限制,了解本機模型適合的工作,以及 Claude Code、Codex 的版本差異。

連線方式

您可以將 Ollama 與編碼代理程式(coding agent)搭配使用,連線過程比預期更簡單。您只需修改一個 base URL 並選擇一個模型名稱。API key 欄位仍需填入數值,但本機伺服器會忽略該欄位,因此輸入任何字串皆可。

Ollama 監聽 11434 埠,並同時提供三種 API 介面。/api 是 Ollama 的原生 API。/v1 是相容於 OpenAI 的層級,其本身涵蓋多種形式:/v1/chat/completions、/v1/responses、/v1/completions、/v1/models 與 /v1/embeddings。Ollama 的說明文件指出該處的 key 為必填但會被忽略。第三種介面則相容於 Anthropic:用戶端將 http://localhost:11434 作為 base URL 並附加 /v1/messages,這正是 Claude Code 所使用的格式。大多數代理程式使用 /v1/chat/completions,Codex 使用 /v1/responses,而 Claude Code 使用 /v1/messages。您的代理程式已支援其中一種格式,因此無需進行其他變更。

此部分僅需五分鐘即可完成。結果是否堪用,取決於幾乎無人調整的兩項設定:context length 與 keep-alive,以及是否將適合的工作指派給模型。這兩項設定將分別於後續章節說明,真實的限制則列於文末。

哪些程式碼代理接受本機 base URL

測試只有一個問題:工具是否提供 base URL 設定?如果有,就能與你的伺服器通訊。

Ollama 提供 Claude Code、OpenCode、Codex、Cline、Roo Code、Zed、JetBrains IDEs 及 VS Code 的整合頁面。Aider 另有文件說明其 Ollama 支援。這涵蓋了 2026 年 10 月大多數人所稱的程式碼代理。這些工具使用的 API 形式不完全相同,而設定失敗通常就是因為這項差異。

  • 大多數代理需要 OpenAI 相容端點。將 base URL 設為 http://localhost:11434/v1,並提供任何非空白的 API key 字串。
  • Claude Code 完全不接受 OpenAI base URL。它使用 Anthropic Messages API,因此需要將 ANTHROPIC_BASE_URL 設為 http://localhost:11434;Ollama 會在此提供 /v1/messages。
  • Codex 使用 OpenAI Responses API。Ollama 也提供 /v1/responses,此功能自版本 0.13.3 起加入。
  • 沒有 base URL 設定的代理無法重新導向,因為端點已寫入用戶端。如果代理接受自訂 URL,但需要不同的 API 形式,請改在前方加入轉換層,例如 自行託管的 LiteLLM gateway,再以用戶端要求的形式重新公開模型。

Ollama 可以代你寫入這些設定。ollama launch opencode 會以你選擇的模型和內嵌設定啟動 OpenCode,ollama launch claude 對 Claude Code 執行相同操作,而 ollama launch droid --config 只會寫入設定,不會啟動工具。

安裝 Ollama 並下載支援工具呼叫的模型

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

安裝程式會新增並啟動 systemd 單元,因此 systemctl status ollama 應顯示 active (running)。若未顯示,請執行 journalctl -e -u ollama 查看失敗原因。

模型必須支援工具呼叫(tool calling),因為這是代理程式(agent)運作的基礎。代理程式會讀取檔案、撰寫修補程式、執行測試,接著讀取錯誤訊息並重試。若模型無法輸出工具呼叫,它將會以文字描述編輯內容而非實際執行,導致代理程式陷入迴圈或停止。在下載前,請先於 ollama.com 的模型頁面確認是否有 tools 標籤。qwen3-coder:30b 具備此功能,截至 2026 年 10 月,該標籤的下載量為 19 GB,並支援 256K 的上下文視窗。若您的機器僅使用 CPU 或記憶體不足,請參考 VPS 上 Qwen 27B 標籤的記憶體計算方式,以了解在 8 到 64 GB 記憶體下實際可容納的規模,避免浪費下載流量。下載完成後,這些 GB 檔案會存放在伺服器的根磁碟中,這通常是 VPS 上空間最吃緊的部分,因此建議在磁碟塞滿前閱讀 Ollama 模型檔案存放位置及遷移方法。

現在確認伺服器實際提供的模型名稱:

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

回應中的字串必須與代理程式設定檔中的內容完全一致。先行檢查可解決大多數「找不到模型」的錯誤。若尚未安裝 Ollama,請參考 在 VPS 上使用 Ollama 自架 LLM 的詳細指南。

將 OpenCode 指向 Ollama

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

models 下的值是傳送至 Ollama 的模型名稱,因此必須與 ollama ls 完全相同。name 欄位只是在模型選擇器中顯示的標籤。啟動 opencode,切換至 Ollama 提供者,並監看 journalctl -e -u ollama,確認請求確實送達您的伺服器,而不是其他位置。代理程式本身的設定請參閱 在 VPS 上執行 OpenCode。

將 Claude Code 指向 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 會刻意設為空字串。Base URL 會控制請求的目的地;清除金鑰可避免將託管服務的認證帶入這個本機設定。ollama launch claude 會替你完成所有這些設定。

請了解相容性層未涵蓋的功能。它未實作 tool_choice 或 prompt caching,也沒有 token counting endpoint,因此你看到的 token 數量,只是根據模型自身 tokenizer 得出的近似值。Claude Code 也會傳送大型 system prompt,並提供大量工具,因此需要的 context 比聊天用戶端更多。至於哪些功能可以沿用、哪些無法沿用,請參閱是否能自行託管 Claude。

將 Aider 指向 Ollama

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

Aider 的文件建議使用 ollama_chat/ 前綴,而不是 ollama/。預設情況下,Aider 會為每個請求要求足夠的上下文,並另外保留 8k token 的回覆空間。您也可以在 .aider.model.settings.yml 中為每個模型固定上下文視窗大小;當某個模型需要不同於伺服器預設值的視窗大小時,這項功能很實用:

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

為何運作正常的設定仍會產生無意義的內容

這是最關鍵的章節。Ollama 會根據偵測到的 GPU 總 VRAM(顯示記憶體)選擇預設的上下文長度,並為每個偵測到的 GPU 扣除 OLLAMA_GPU_OVERHEAD。其實作採用以下閾值:

圖表Ollama default context length by aggregate VRAM, checked 2026-10-26
此圖表背後的資料
[
  {
    "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"
  }
]

大多數 VPS 方案以及所有僅使用 CPU 的伺服器都會落在第一列:4,096 個 token。多個較小的 GPU 合計可達到 47 GiB 的閾值,從而獲得最後一列的 262,144 個 token。

代理程式在執行任何工作前會先傳遞 4096 個 token。系統提示詞、工具定義、儲存庫列表以及它開啟的第一個檔案,其大小早已超過此數值。接下來發生的問題在於:系統不會報錯。Aider 的文件指出,Ollama 會靜默捨棄超出視窗範圍的上下文。最舊的 token 會被移除,導致模型在無法讀取檔案的情況下仍自信地回答,或是遺忘您兩步之前給出的指令。這就是大多數報告稱本地模型寫程式能力不足的原因。選擇數值本身是一項決策,在決定數值前,建議先閱讀 num_ctx 在不同大小下對 KV cache 記憶體的消耗。

Ollama 的文件建議,代理程式與程式碼工具等任務應至少設定為 64000 個 token。請在伺服器上進行設定:

sudo systemctl edit ollama.service

在覆寫檔案中加入以下行:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

接著重新載入並重啟服務:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

重啟後從您的代理程式發送請求,然後再次執行 ollama ps,以便有已載入的模型可供檢查。ollama ps 是檢查指令。它會列印出 CONTEXT 欄位,該數值即為模型實際接收到的數量。您的 ID 與 SIZE 將會不同:

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

建議在伺服器端而非代理程式端進行設定,原因有二。OpenAI 聊天完成(chat completions)架構中沒有上下文長度的欄位,因此相容 OpenAI 的客戶端無法請求該數值。此外,伺服器預設值適用於所有代理程式,除非模型或請求另有覆寫。輸出端有其上限,且與上下文長度不同,它會透過相容性端點傳輸,因此當回覆在修補程式中途停止時,請參考 num_predict 以及與其對應的 max_tokens 欄位。若特定模型需要不同的視窗大小,請使用 Modelfile 將其寫入副本中:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536
ollama create qwen3-coder-64k -f Modelfile

上下文並非免費。視窗越長,記憶體消耗越高,因此請監控 PROCESSOR 欄位。100% GPU 是您應關注的數值。一旦模型部分溢出至 CPU,token 處理速率會大幅下降,導致代理程式迴圈變得無法使用,而 測量本地 LLM 的每秒 token 數 是找出您機器實際效能上限的方法。在購買機器前,請參考 程式設計代理程式 VPS 所需的 RAM 與 CPU 規格 以進行評估。

在請求之間保持模型載入

Ollama 預設會在模型上次收到請求 5 minutes 後卸載模型。這對聊天方塊來說合理,但不適合代理工作。您暫停查看差異內容時,計時器可能已逾時;下一個請求便會先從磁碟重新載入數十 GB 的權重,然後才顯示第一個 token。這看起來像是服務卡住。

OLLAMA_KEEP_ALIVE 可接受 10m 或 24h 這類持續時間字串、代表秒數的純數字、可讓模型持續載入的 -1,以及立即卸載模型的 0。請將它與 context length 放在一起設定:

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

keep_alive 請求欄位存在於 Ollama 原生的 /api/generate 和 /api/chat 端點,也可作為 Ollama 在 /v1/chat/completions 上的擴充功能使用。能公開其他請求欄位的代理可以在該處傳送這個欄位;否則請使用環境變數。需要釋放記憶體時,ollama stop qwen3-coder:30b 會在不停止伺服器的情況下卸載模型。若要讓設定在重新開機後仍然生效,或需要評估讓權重整天保留在記憶體中與釋放記憶體之間的取捨,讓 Ollama 模型保持載入於記憶體可同時處理這兩種需求。

在獨立伺服器上執行 Ollama

Ollama 會繫結至 localhost。若要從其他電腦連線,請在相同的 systemd override 中設定 OLLAMA_HOST=0.0.0.0:11434,然後重新啟動服務。

只能在私有網路中這樣做。Ollama 的文件指出,本機 API 不需要驗證,因此若將連接埠 11434 開放到網際網路,任何人都能使用你的硬體。有兩種安全做法。保留繫結至 localhost,並從筆記型電腦透過 SSH 轉送連接埠:

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

你的 agent 持續指向 http://localhost:11434/v1,不會察覺其中差異。另一種做法是使用 VPN,讓 Ollama 綁定至 VPN 位址,而不是 0.0.0.0。如果多人或多個 agent 要共用同一台主機,Ollama 支援在記憶體允許時處理平行請求;Ollama 與 vLLM 的比較說明了吞吐量差異從何處開始造成影響。

本機程式碼模型適合哪些工作,以及不適合哪些工作

由你自行託管的模型驅動的 agent,並不能在所有工作上取代 frontier API。它在以下 4 類工作上具有明顯優勢。

  • 大量機械式修改,每次變更都很小且可以驗證。例如在整個 repository 中重新命名、加入 type hints、撰寫 docstrings,以及翻譯註解。模型可以執行數小時,費用不會增加。
  • 不得離開硬體的工作。例如受保密協議約束的客戶端程式碼,或不得傳送給第三方的內部 repository。
  • 離線與 air-gapped 機器。這些環境根本沒有可呼叫的 hosted API。
  • 可預測的成本。伺服器付款完成後,agent 即使在迴圈中持續消耗 tokens,也不會產生額外費用;這與按量計費的 API 正好相反。GPU VPS 與 API tokens 損益兩平的時機 內有計算方式。

它在長時間、多步驟的工作上則處於劣勢。「找出這項測試失敗的原因、修正問題,再更新呼叫端」需要連續執行許多正確的工具呼叫,並讓完整歷史持續保留在上下文中。使用中型伺服器上的 8B 至 14B 模型時,模型可能產生格式錯誤的工具呼叫,或在幾輪對話後忘記計畫。你花在引導模型上的時間,可能比直接完成工作還多。這不是靠撰寫更好的 prompt 就能解決的問題,而是容量限制。

只要錯誤的代價很高,而且你不會逐行閱讀輸出,它也會處於劣勢。讓本機模型執行範圍狹窄、且輸出可驗證的工作;至於你不會逐步檢查的工作,則保留給 hosted model。

故障模式與常見錯誤訊息

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. 伺服器未執行,或代理程式指向了錯誤的主機。請執行 systemctl status ollama,接著執行 journalctl -e -u ollama。

代理程式回報模型不存在。 設定檔中的名稱與伺服器提供的名稱不符。請對照 curl http://localhost:11434/v1/models 並直接複製該處的字串。標籤(tag)是名稱的一部分,若設定檔指定的標籤未曾下載,即使已安裝類似的模型,程式仍會失敗。

代理程式僅以文字回答,未編輯檔案。 原因可能是模型不支援工具,或是請求內容加上工具定義已填滿上下文視窗(context window)。請檢查模型頁面上的 tools 標籤,再檢查 ollama ps 中的 CONTEXT 欄位。

首個 token 輸出前有長時間停頓,隨後速度正常。 這是因為連線逾時(keep-alive)已過期,權重需重新從磁碟讀取。請設定 OLLAMA_KEEP_ALIVE。

模型與剛讀取的檔案內容矛盾。 這是上下文截斷(context truncation)所致。ollama ps 通常會顯示比您預期更小的 CONTEXT 值,這是因為環境變數被傳遞至您的 shell,而非 systemd 單元。

一切運作正常但速度緩慢,且 PROCESSOR 顯示 100% CPU 或 CPU/GPU 分割運算。 通常是因為模型加上上下文內容超過了 VRAM 容量。若 PROCESSOR 在具備 GPU 的機器上顯示 100% CPU,請先排除其他原因:Ollama 可能完全未偵測到 GPU。Ollama 文件指出,在 Linux 上經過暫停/恢復循環後,有時會無法偵測到 NVIDIA GPU 並退回使用 CPU,此時可透過 sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm 重新載入驅動程式來解決。若已偵測到 GPU 但分割運算依然存在,請降低上下文長度,或改用較小的模型或較低位元的量化版本。在重新下載前,q4_K_M、q8_0 與 fp16 各自的記憶體需求,以及品質下降的實際情況 可協助您評估降級後能節省多少空間,以及需犧牲的效能。Unknown 也是可能的 PROCESSOR 值;它不會啟用 CPU 卸載(offloading)。

FAQ

我可以將 Claude Code 指向 Ollama 嗎?

可以,但不能使用與 OpenAI 相容的 URL。Claude Code 使用 Anthropic Messages API,而 Ollama 在相同的 11434 埠上提供該格式的 /v1/messages。請匯出 ANTHROPIC_BASE_URL=http://localhost:11434、ANTHROPIC_AUTH_TOKEN=ollama 以及空的 ANTHROPIC_API_KEY,然後使用 claude --model qwen3-coder:30b 啟動。ollama launch claude 會為您寫入相同的設定。此相容層未實作 tool_choice 或提示詞快取(prompt caching),且沒有 token 計算端點,因此回報的 token 數量僅為近似值。

為什麼我的本地模型會回答它看不到的程式碼?

因為請求已超出上下文視窗(context window),且最舊的部分在沒有錯誤訊息的情況下被捨棄。Ollama 會在扣除每個 GPU 的設定開銷後,根據偵測到的總 VRAM 設定預設上下文:低於 23 GiB 時預設為 4,096 tokens,23 到 47 GiB 以下為 32,768 tokens,47 GiB 或以上則為 262,144 tokens。請在 systemd 單元中設定 OLLAMA_CONTEXT_LENGTH=64000,重新啟動 Ollama,並確認 ollama ps 中的 CONTEXT 欄位顯示新數值。

在 VPS 上執行程式碼代理(coding agent)應該選擇哪個模型?

請選擇帶有 tools 標籤且能在 64k 上下文視窗下放入記憶體的最大模型,並優先選擇針對程式碼調校過的模型。qwen3-coder:30b 是在具備足夠 VRAM 的 GPU 伺服器上的常見選擇。如果該標籤對您的伺服器來說太大,Nemotron 3.5 Lightning 的 RAM 數據與純 CPU 速度 是在下載前很有用的參考。參數低於約 14B 的模型雖然仍能回答程式碼相關問題,但在多步驟編輯時容易失敗,因為代理工作對於工具呼叫中的微小格式錯誤非常敏感。請使用您儲存庫中的一個實際任務進行測試,而非使用範例提示詞。

在自己的模型上執行程式碼代理需要 GPU 嗎?

實際上需要。純 CPU 推論雖然可行,對於單一問題也沒問題,但代理程式在每個任務中會發送大量請求,且每次都會重新讀取長歷史紀錄,因此緩慢的 token 速率會將兩分鐘的任務變成一小時。請檢查 ollama ps 中的 PROCESSOR 欄位:100% CPU 或 CPU/GPU 分割表示正在使用 CPU,這會拖慢推論速度。Unknown 並不會建立 CPU 卸載(offloading)。

這篇文章對您有幫助嗎?