作者： Ollama 如何搭配 coding agent 使用？
設定 Ollama 給 coding agent 使用：掌握 base URL、可任填的 API key、會造成問題的 context length，以及本機 model 適合的工作。
連線方式
您可以將 Ollama 與 coding agent 搭配使用，連線設定比一般預期更簡單。只要變更一個 base URL，再選擇一個 model name 即可。API key 欄位仍要求填入值，但本機伺服器會忽略該值，因此輸入任何字串都可以。
Ollama 監聽 11434 埠，並同時提供兩種請求格式。/v1/chat/completions 是 OpenAI 相容格式，Ollama 文件將其中的 key 說明為必填，但會忽略其內容。/v1/messages 是 Anthropic 相容格式，也是 Claude Code 使用的格式。您的 agent 已經支援其中一種格式，因此其他設定不需變更。
這部分只需 5 分鐘。實際結果是否可用，取決於兩項幾乎沒有人會調整的設定：context length 和 keep-alive；同時也取決於是否讓 model 執行適合它的工作。這兩項設定各有專節說明，最後再說明實際限制。
哪些 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，此功能自 version 0.13.3 起加入。 - 如果 agent 沒有 base URL 設定，就無法重新導向，因為 endpoint 已內建於 client。請改在前方加入轉譯層，例如 自架的 LiteLLM gateway，再依 client 要求的格式重新公開你的 model。
Ollama 可以替你寫入這些設定。ollama launch opencode 會使用你選擇的 model，以 inline config 啟動 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 unit 並啟動服務，因此 systemctl status ollama 應輸出 active (running)。如果沒有，journalctl -e -u ollama 會顯示原因。
模型必須支援工具呼叫，因為 agent 依靠工具呼叫運作。它會讀取檔案、寫入 patch、執行測試，接著讀取失敗結果並再次嘗試。無法輸出工具呼叫的模型，只會以文字說明要如何修改，而不會實際執行修改，導致 agent 重複循環或停止。拉取模型前，請先在 ollama.com 的模型頁面確認 tools 標籤。qwen3-coder:30b 具備此標籤；截至 August 2026，該標籤需要下載 19 GB，並提供 256K context window。如果主機只有 CPU 或 RAM 不足，請參閱 VPS 上 Qwen 27B 標籤的記憶體計算方式，在開始下載前確認 8 到 64 GB 實際能容納的模型。
現在確認伺服器實際提供哪些名稱：
curl http://localhost:11434/v1/models回應中的字串就是 agent 設定必須逐字包含的內容。先檢查這些名稱，可以排除大多數 model-not-found 錯誤。如果尚未安裝 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 provider，並監控 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 或 prompt caching，也沒有 token 計數端點，因此您看到的 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:30bAider 的文件建議使用 ollama_chat/ 前綴，而不是 ollama/。您也可以在 .aider.model.settings.yml 中為每個模型固定 context window；當某個模型需要的視窗大小不同於伺服器預設值時，這項功能很實用：
- 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 listing，以及它開啟的第一個檔案，早已超過這個大小。接下來發生的事情正是問題所在：系統不會回報錯誤。Aider 文件指出，Ollama 會靜默捨棄超出 context window 的內容。最舊的 tokens 會被移除，因此模型可能在已看不到檔案的情況下，仍然自信地回答相關問題；也可能忘記你兩個步驟前提供的指示。多數「本機模型太笨，無法寫程式碼」的回報，都源自這個機制。
Ollama 文件指出，agent 和 coding tool 等工作至少應設定為 64000 個 tokens。請在伺服器上設定：
sudo systemctl edit ollama.service在 override file 中加入以下幾行：
[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 的 client 無法要求特定值。此外，這項設定以伺服器為單位，因此你指向該伺服器的所有 agent 都會繼承這項設定。如果某個模型需要不同的 window，可以使用 Modelfile 將設定寫入副本：
FROM qwen3-coder:30b
PARAMETER num_ctx 65536ollama create qwen3-coder-64k -f ModelfileContext 並非免費。較長的 window 會耗用更多記憶體，因此請監看 PROCESSOR 欄位。100% GPU 才是你需要的數值。模型有一部分溢出至 CPU 後，token rate 會下降到足以讓 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 會繫結至 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 的比較說明了吞吐量差異開始造成影響的情況。
本機 coding model 何時具優勢，以及何時不具優勢
由你自行託管的 model 驅動的 agent，並不能在所有工作上取代 frontier API。它在以下 4 類工作中具有明顯優勢。
- 大量機械式修改，而且每次變更都很小且可驗證。例如在整個 repository 中重新命名、加入 type hints、撰寫 docstrings，以及翻譯註解。model 可以執行數小時，費用也不會增加。
- 不得離開你硬體的工作。例如受保密協議約束的 client code，或禁止傳送給第三方的內部 repository。
- 離線和 air-gapped 電腦。這類環境根本沒有可呼叫的 hosted API。
- 可預測的成本。伺服器付費後，agent 即使在迴圈中持續消耗 tokens，也不會產生額外費用；這與按用量計費的 API 正好相反。GPU VPS 與 API tokens 的損益平衡點 說明了相關計算方式。
它在長時間的多步驟工作上則不具優勢。「找出這項測試失敗的原因、修正原因，再更新呼叫端」需要連續完成許多正確的工具呼叫，而且完整歷程仍須保留在 context 中。在一般伺服器上執行 8B 到 14B 範圍的 model 時，model 可能產生格式錯誤的工具呼叫，或在幾個回合後遺失原本的計畫。你花在引導它的時間，可能比直接完成工作還多。這不是靠撰寫更好的 prompt 就能解決的問題，而是容量限制。
只要錯誤的代價很高，而且你不會逐行檢查內容，它同樣不具優勢。將本機 model 用於輸出可驗證的狹窄工作，至於你不會逐步檢查的工作，則保留給 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 比對，並從該處複製字串。tag 是名稱的一部分，因此即使已安裝相似模型，若設定指定了從未拉取的 tag，仍會失敗。
agent 以文字回答，且完全不會編輯檔案。 模型可能不支援工具，或請求加上工具定義後已占滿 context window。查看模型頁面的 tools 標籤，再檢查 ollama ps 中的 CONTEXT 欄位。
第一個 token 出現前長時間沒有回應，之後速度正常。 keep-alive 已逾時，系統正在重新從磁碟讀取權重。設定 OLLAMA_KEEP_ALIVE。
模型與剛讀取的檔案內容互相矛盾。 這是 context truncation。ollama ps 通常會顯示比您設定值更小的 CONTEXT 值，因為環境變數只套用到您的 shell，未套用到 systemd unit。
所有功能都正常，但速度很慢，而且 PROCESSOR 不是 100% GPU。 模型及其 context 無法容納在 VRAM 中。降低 context length，或改用較小的模型或較小的 quantisation。
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。模型參數量低於約 14B 時，仍可能適合回答程式碼問題，但在多步驟編輯上失敗，因為 agent 工作無法容忍工具呼叫中的細微格式錯誤。請使用自己 repository 中的一項真實工作進行測試，不要只使用範例提示。
我需要 GPU 才能在自己的模型上執行 coding agent 嗎？
實務上需要。CPU-only inference 可以運作，也適合單次提問；但 agent 每項工作會送出許多請求，而且每次都要重新讀取長篇歷史，因此較慢的 token 速率會讓原本 2 分鐘的工作變成 1 小時。檢查 ollama ps 中的 PROCESSOR 欄位：任何不是 100% GPU 的值，都表示部分模型在 CPU 上執行，token 速率會大幅下降。