作者： 如何在 coding agent 使用 Ollama 本機模型
設定 Ollama 的 base URL 與任意 API key，避開 context length 限制，了解本機模型適合的工作，以及 Claude Code、Codex 的版本差異。
連線方式
您可以在程式碼代理程式中使用 Ollama，而連線設定比多數人預期的更簡單。只需變更一個 base URL，並選擇一個模型名稱。API key 欄位仍要求填入值，但本機伺服器會忽略該值，因此填入任何字串都可以。
Ollama 會在埠 11434 監聽，並同時提供兩種請求格式。/v1/chat/completions 是 OpenAI 相容格式，Ollama 文件說明其中的 key 為必要欄位，但會被忽略。/v1/messages 是 Anthropic 相容格式，也是 Claude Code 使用的格式。您的代理程式本來就支援其中一種格式，因此其他設定不必變更。
這部分只需五分鐘。實際結果是否可用，取決於幾乎沒有人會調整的兩項設定：context length 與 keep-alive；同時也取決於是否讓模型處理適合它的工作。這兩項設定各有專屬章節，文末則會說明實際限制。
哪些 coding agent 接受本機 base URL
測試只有一個問題：工具是否提供 base URL 設定？如果有，就能連線到你的伺服器。
Ollama 提供 Claude Code、OpenCode、Codex、Cline、Roo Code、Zed、JetBrains IDEs 和 VS Code 的整合頁面。Aider 則另外說明自己的 Ollama 支援。這涵蓋了截至 August 2026 多數人所稱的 coding agent。這些工具使用的格式不完全相同，設定失敗通常就是因為這項差異。
- 多數 agent 需要 OpenAI-compatible endpoint。將 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提供該 API，這項功能自 version 0.13.3 起加入。 - 沒有 base URL 設定的 agent 無法重新導向，因為 endpoint 已內建於 client。請改在前方加入 translation layer，例如 自行託管的 LiteLLM gateway，再依 client 要求的格式重新提供你的 model。
Ollama 可以替你寫入這些設定。ollama launch opencode 會以 inline config 啟動 OpenCode，使用你選擇的 model；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 會顯示原因。
模型必須支援工具呼叫，因為代理程式就是透過工具呼叫運作。它會讀取檔案、寫入修補程式、執行測試，接著讀取失敗訊息並再次嘗試。無法發出工具呼叫的模型只會以文字描述修改內容，而不會實際執行修改，導致代理程式陷入迴圈或停止。下載前，請先在 ollama.com 的模型頁面尋找 tools 標籤。qwen3-coder:30b 具備此標籤；截至 August 2026，該標籤需要下載 19 GB，並提供 256K context window。如果你的主機只有 CPU 或 RAM 不足，請先閱讀 VPS 上 Qwen 27B 標籤的記憶體估算，確認 8 到 64 GB 的容量實際能容納哪些內容，再開始下載。下載完成後，這些 GB 會存放在伺服器的 root 磁碟上。VPS 的 root 磁碟通常最缺乏可用空間，因此在磁碟用盡前，值得先閱讀 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:30bANTHROPIC_API_KEY 會刻意設為空字串。若環境中留有真正的金鑰，請求會改送至代管 API，這會產生費用，且不會使用本機推論。ollama launch claude 會自動為你完成這些設定。
請了解相容性層未涵蓋的功能。它未實作 tool_choice 或提示快取，也沒有 token 計數端點，因此你看到的 token 數量，只是根據模型自身 tokenizer 估算的結果。Claude Code 也會隨附大型系統提示與大量工具，因此需要比聊天用戶端更多的上下文。哪些功能可以沿用、哪些無法沿用的完整說明，請參閱是否能自行代管 Claude。
將 Aider 指向 Ollama
export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30bAider 的文件建議使用 ollama_chat/ 前綴，而不是 ollama/。您也可以在 .aider.model.settings.yml 中為每個模型固定上下文視窗大小。當某個模型需要的視窗大小不同於伺服器預設值時，這項設定很實用：
- name: ollama_chat/qwen3-coder:30b
extra_params:
num_ctx: 65536為什麼設定正常，結果仍然不合理
這是關鍵所在。Ollama 會依據它能偵測到的 VRAM（GPU 上的視訊記憶體）選擇預設 context length，而這些預設值已公開：
The data behind this chart
[
{
"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"
}
]大多數 VPS 方案，以及所有僅使用 CPU 的伺服器，都會落在第一列：4,096 tokens。只有大型 GPU 才會取得最後一列的 262,144 tokens。
Agent 在開始執行任何工作前，就會傳入 4096 tokens。System prompt、工具定義、repository 清單與它開啟的第一個檔案，合計早已超過這個數值。接下來發生的事情就是問題所在：系統不會顯示錯誤。Aider 的文件指出，超過視窗大小的 context 會被 Ollama 靜默捨棄。最早的 tokens 會被移出，因此模型可能仍有信心地回答一個它已經看不到的檔案，或忘記你兩個步驟前下達的指示。這種機制是多數「本機模型太笨，無法寫程式」回報的原因。選擇這個數值本身也需要考量，在決定前，值得閱讀 各種大小的 num_ctx 對 KV cache 記憶體的成本。
Ollama 的文件表示，agent 與 coding tool 等工作應設定至少 64000 tokens。在伺服器上設定：
sudo systemctl edit ollama.service在 override 檔案中加入以下內容：
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"接著重新載入並重新啟動：
sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama psollama ps 是檢查指令。它會輸出 CONTEXT 欄位，而該數值就是模型實際收到的值。你的 ID 與 SIZE 會不同：
NAME ID SIZE PROCESSOR CONTEXT UNTIL
qwen3-coder:30b a1b2c3d4e5f6 24 GB 100% GPU 64000 4 minutes from now請在伺服器上設定，而不是在 agent 中設定，原因有二。OpenAI chat completions schema 沒有 context length 欄位，因此相容 OpenAI 的用戶端無法要求特定值。其次，這項設定以伺服器為單位，因此所有指向該伺服器的 agent 都會繼承它。輸出端有自己的上限；與 context length 不同，該設定會經由 compatibility endpoint 傳遞。因此，當回覆在 patch 中途停止時，應使用 num_predict 以及對應的 max_tokens 欄位。如果某個模型需要不同的視窗，可以使用 Modelfile 將設定寫入副本：
FROM qwen3-coder:30b
PARAMETER num_ctx 65536ollama create qwen3-coder-64k -f ModelfileContext 並非免費。較長的視窗會消耗更多記憶體，因此請監看 PROCESSOR 欄位。你需要的是 100% GPU。模型的一部分一旦溢出到 CPU，token 速率就會大幅下降，導致 agent loop 無法使用；測量本機 LLM 的每秒 tokens 數可以協助你找出伺服器的實際上限。在購買前評估機器規格，請參閱coding agent VPS 需要多少 RAM 與 CPU。
在請求之間保留模型載入狀態
Ollama 預設會在模型上次處理請求 5 分鐘後卸載模型。這對聊天框很合適，但不適合代理工作。您暫停閱讀差異內容時，計時器可能已經結束，下一個請求就必須從磁碟重新載入數十 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 endpoint，不適用於相容性 endpoint，因此代理無法逐一為請求設定這個欄位。環境變數是唯一可用的控制方式。需要釋放記憶體時，ollama stop qwen3-coder:30b 會卸載模型，但不會停止伺服器。若要讓設定在重新開機後仍然生效，或需要評估整天將權重保留在記憶體中與釋放記憶體之間的取捨，讓 Ollama 模型持續載入記憶體可以同時處理這兩種需求。
在獨立伺服器上執行 Ollama
Ollama 會繫結至 localhost。若要從其他機器連線，請在相同的 systemd override 中設定 OLLAMA_HOST=0.0.0.0:11434，然後重新啟動服務。
僅限在私有網路上這樣做。Ollama 的文件指出，本機 API 不需要驗證，因此將連接埠 11434 開放至網際網路，代表任何人都能使用你的硬體，並讀取 agent 傳送的所有內容。有兩種安全作法。保留繫結至 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。 伺服器未執行，或 agent 指向其他主機。執行 systemctl status ollama，接著執行 journalctl -e -u ollama。
agent 回報模型不存在。 設定中的名稱與伺服器提供的名稱不一致。將其與 curl http://localhost:11434/v1/models 比對，並從中複製字串。標籤也是名稱的一部分，因此即使已安裝相似模型，若設定指定了從未下載的標籤，仍會失敗。
agent 以文字回答，完全不編輯檔案。 模型可能不支援工具，或要求加上工具定義後已填滿 context window。查看模型頁面的 tools 標籤，再檢查 ollama ps 中的 CONTEXT 欄位。
第一個 token 出現前長時間沒有回應，之後速度正常。 keep-alive 已過期，系統再次從磁碟讀取權重。設定 OLLAMA_KEEP_ALIVE。
模型與剛讀取的檔案內容矛盾。 這是 context 截斷所致。ollama ps 通常會顯示小於你設定值的 CONTEXT，因為環境變數只套用到你的 shell，未套用到 systemd unit。
所有功能都能運作，但速度很慢，而且 PROCESSOR 不是 100% GPU。 模型及其 context 無法放入 VRAM。降低 context length，或改用較小的模型或較小的 quantisation。在重新 pull 之前，q4_K_M、q8_0 與 fp16 各自占用多少記憶體，以及實際會在哪裡降低品質會說明降低一級能釋放多少空間，以及需要放棄哪些內容。
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 或提示快取，也沒有 token 計數端點，因此回報的 token 數量只是近似值。
為什麼我的本機模型會回答它看不到的程式碼？
因為請求已超出 context window，最早的部分會在沒有錯誤訊息的情況下被捨棄。Ollama 會依偵測到的 VRAM 設定預設 context；當 VRAM 少於 24 GiB 時，預設值為 4,096 tokens，單是 agent 的 system prompt 與工具定義就會超過這個容量。在 systemd unit 中設定 OLLAMA_CONTEXT_LENGTH=64000，重新啟動 Ollama，並確認 ollama ps 的 CONTEXT 欄位顯示新值。
在 VPS 上執行 coding agent，應該選哪個模型？
選擇帶有 tools 標籤、在 64k context window 下仍能裝入記憶體的最大模型，並優先選擇針對程式碼調校的模型。若 GPU server 具備足夠 VRAM，qwen3-coder:30b 是常見選擇。如果該標籤的模型對你的 server 太大，下載前可以參考Nemotron 3.5 Lightning 的 RAM 數據與僅使用 CPU 時的速度。低於約 14B parameters 的模型，仍可能擅長回答程式碼問題，卻無法可靠完成多步驟編輯，因為 agent 工作很容易受到工具呼叫中的細微格式錯誤影響。請使用自己 repository 中的一項實際任務進行測試，不要只使用範例 prompt。
我需要 GPU 才能在自己的模型上執行 coding agent 嗎？
實際上需要。僅使用 CPU 的 inference 可以運作，也適合單一問題；但 agent 每項任務會傳送許多請求，而且每次都會重新讀取很長的歷史內容，因此較慢的 token rate 會讓原本 2 分鐘的任務變成 1 小時。查看 ollama ps 中的 PROCESSOR 欄位：任何不是 100% GPU 的值，都表示部分模型正在 CPU 上執行，而 token rate 會大幅下降。