Codex 本地大模型接入 Ollama 常見報錯：排查順序、原因和修復方法

Codex 接入 Ollama 本地模型時報錯，表面看像是 Codex 壞了，實際上常見原因通常更小：Ollama 沒啟動、模型名稱不對、Codex 仍在走雲端 provider、localhost 指到了錯的環境，或者本地模型本身處理不了這個任務。

排查時不要一次改很多設定。先確認 Ollama 能正常回答，再確認 Codex 真的走 Ollama，最後再調模型大小、上下文長度和工具調用表現。

先確認正確接入方式

常見本地鏈路分三層：

1. Ollama 負責運行本地模型。
2. Codex 以 local provider 方式連到 Ollama。
3. Codex 把編程任務發給該模型。

可以先測：

1
2
3

ollama serve
ollama pull qwen2.5-coder:7b
ollama run qwen2.5-coder:7b

再根據 Codex 版本使用對應參數：

1

codex --oss --local-provider ollama

如果當前版本不認這些參數，先看本機說明：

1
2

codex --help
codex --version

最小排查順序

建議按這個順序排查：

1
2
3
4
5
6

ollama --version
ollama list
ollama run qwen2.5-coder:7b
curl http://localhost:11434/api/tags
codex --version
codex --help

ollama run 不通，就先修 Ollama；curl 不通，就先修服務和網路；Codex 沒有 local-provider 相關選項，就先升級或改用該版本支援的設定方式。

報錯：找不到 ollama 命令

這通常表示 Ollama 沒安裝，或執行檔不在 PATH。

Windows 下先檢查：

1
2

where.exe ollama
ollama --version

如果安裝後仍找不到，關閉 PowerShell 重新打開，必要時重啟 Windows。

報錯：Ollama 服務沒啟動

Codex 連不到本地模型時，先測 Ollama 服務：

1

curl http://localhost:11434/api/tags

沒有回應就啟動：

1

ollama serve

Windows 上桌面版 Ollama 可能已經幫你管理服務，不要同時啟動多個互相衝突的實例。

報錯：model not found

Ollama 的模型名稱要完全一致。

1
2
3

ollama list
ollama pull qwen2.5-coder:7b
ollama run qwen2.5-coder:7b

不要憑印象猜 tag。qwen2.5-coder 和 qwen2.5-coder:7b 在本機可能不是同一個可用模型。

報錯：Codex 沒有走 Ollama

如果 Codex 仍要求雲端登入或 API key，通常代表它沒有進入本地 provider 模式。

先看：

1

codex --help

確認是否有 local provider、OSS mode 或 Ollama 相關選項。也要檢查全域設定、專案設定和環境變數，避免舊設定把 Codex 指向其他 provider。

報錯：unknown option 或參數不支援

這通常是教程和本機 Codex 版本不一致。

1
2

codex --version
codex --help

以本機 help 為準。需要時升級 Codex，或改用目前版本支援的寫法。

報錯：localhost 指錯地方

WSL、Docker、遠端終端和 Windows 桌面應用混用時最容易遇到這個問題。

一定要在 Codex 實際運行的環境裡測：

1

curl http://localhost:11434/api/tags

如果 Windows PowerShell 通，但 WSL 裡不通，問題是網路指向，不是模型本身。

報錯：401、API key 或認證相關錯誤

本地 Ollama 通常不需要 OpenAI API key。看到這類錯誤時，Codex 可能仍在走雲端 provider 或 OpenAI-compatible endpoint。

檢查：

1
2

$env:OPENAI_API_KEY
$env:OPENAI_BASE_URL

如果要純本地運行，就清理衝突設定，並確認 provider 已切回 Ollama。

報錯：請求卡住或一直沒有回應

本地模型慢不一定是錯。CPU 推理、大模型、上下文過長或 GPU 沒用上，都會讓回應像卡住。

先用小模型和小任務測試。如果 ollama run 裡一句話都很慢，Codex 裡也不會快。

報錯：context length exceeded

Codex 經常會帶入檔案、diff、日誌和指令。本地模型上下文太小時，就容易超限。

處理方法：

• 只讓 Codex 看單一檔案；
• 刪掉大段日誌；
• 拆小任務；
• 換更大上下文的模型；
• 不要把整個倉庫一次塞進去。

報錯：工具調用不穩定

很多本地模型能寫程式，但不一定能穩定做 agentic tool use。常見表現是亂編命令、忽略輸出、JSON 壞掉或循環嘗試。

本地模型更適合簡單修改、解釋、重構和小 bug。跨倉庫重構、安全審查、長鏈路除錯，仍建議使用更強的模型。

Windows 常見坑

先查：

1
2
3

where.exe ollama
where.exe codex
$PSVersionTable.PSVersion

不要直接複製 Bash 寫法：

1

export OLLAMA_HOST=...

PowerShell 要寫：

1

$env:OLLAMA_HOST = 'http://localhost:11434'

路徑有空格或中文時，使用引號；PowerShell cmdlet 操作真實路徑時優先用 -LiteralPath。

推薦的穩定配置流程

1
2
3
4
5

ollama pull qwen2.5-coder:7b
ollama run qwen2.5-coder:7b
curl http://localhost:11434/api/tags
codex --help
codex --oss --local-provider ollama

先用小任務測：

1

Read this single file and suggest one safe refactor. Do not edit yet.

能跑通後，再逐步增加修改、測試和長任務。

排查模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

OS:
PowerShell or shell version:
Codex version:
Ollama version:
Model name:
Command used:
Exact error:
Does ollama run work:
Does curl http://localhost:11434/api/tags work:
Are you using WSL, Docker, or remote SSH:

FAQ

Codex 接入 Ollama 後就完全離線了嗎？

不一定。要看 provider 設定、Codex 模式和是否還啟用了其他服務。

可以把 Ollama 當成 OpenAI API base_url 配給 Codex 嗎？

有些工具支援 OpenAI-compatible endpoint，有些需要專用 Ollama provider。以本機 Codex 版本為準。

本地模型適合做所有 Codex 任務嗎？

不適合。它適合隱私、成本和小任務；複雜工具調用仍需要更強模型。

為什麼同一個模型在 Ollama 裡能回答，在 Codex 裡表現差？

聊天比 agentic coding 容易。Codex 需要規劃、讀檔、改檔、跑命令和理解輸出。

是否需要給 Codex 配 OpenAI API key？

純本地 Ollama 通常不需要；混合 provider 或雲端模式需要。

換模型後需要重啟 Codex 嗎？

建議重啟，避免舊 provider 或模型狀態干擾排查。

小結

Codex 接入 Ollama 的常見錯誤，多半來自服務狀態、模型名稱、provider 選擇、網路指向和本地模型能力。按 Ollama、localhost、Codex provider、模型能力這個順序排查，會比盲目改設定穩得多。