Codex 本地大模型接入 Ollama 常見報錯：教程、排障和 FAQ

Codex 能接入本地大模型以後，很多人第一反應是：終於可以把一部分程式碼任務放到 Ollama 上跑，省額度，也能處理更私有的本地專案。但真正上手時，常見情況是命令能跑、模型也裝了，Codex 還是連不上，或者連上以後輸出質量很差。

這篇按“教程 + 排障 + FAQ”寫，目標不是證明本地模型能完全替代雲端模型，而是幫你先把 Codex 和 Ollama 跑通，再判斷哪些任務適合交給本地模型。

適合用本地模型做什麼

接入 Ollama 後，本地模型更適合這些任務：

• 閱讀小型程式碼片段。
• 生成指令碼草稿。
• 改寫 README、註釋和配置說明。
• 做簡單程式碼解釋。
• 處理不方便上傳到雲端的私有文字。
• 在額度緊張時承擔低風險輔助任務。

它不太適合直接承擔複雜重構、大型程式碼庫推理、安全敏感修改和長任務自動執行。尤其是 7B、8B、14B 這類消費級模型，能力和穩定性通常不能按 Claude、GPT 或 Gemini 的水平預期。

第一步：確認 Ollama 正常工作

先不要急著改 Codex 配置。先確認 Ollama 自己能跑。

安裝後檢視版本：

1

ollama --version

拉取一個適合程式碼任務的模型：

1

ollama pull qwen2.5-coder:7b

執行一次對話：

1

ollama run qwen2.5-coder:7b

如果這一步都失敗，問題還不在 Codex，而是在 Ollama 安裝、模型下載、視訊記憶體、網路或系統許可權。

第二步：確認 Ollama API 可訪問

Codex 接入本地模型時，通常需要訪問 Ollama 的 HTTP API。預設地址一般是：

1

http://localhost:11434

可以先用 curl 測試：

1

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

能看到模型列表，說明 Ollama 服務在執行。Windows PowerShell 可以用：

1

Invoke-RestMethod http://localhost:11434/api/tags

如果這裡訪問失敗，先處理服務問題，不要繼續調 Codex。

第三步：在 Codex 中配置本地模型

不同 Codex 版本的本地模型配置入口可能不同，但排障思路是一致的：讓 Codex 使用 OpenAI 相容介面或本地模型提供方，並把基礎地址指到 Ollama。

需要確認三件事：

• base_url 或類似欄位指向 http://localhost:11434。
• 模型名和 ollama list 裡顯示的名字完全一致。
• 如果走 OpenAI 相容介面，要確認路徑和協議是否匹配。

很多報錯不是模型能力問題，而是模型名多了一個字尾、地址少了埠、或者 Windows 和 WSL 對 localhost 的理解不同。

推薦的最小測試

配置完成後，先讓 Codex 做一個低風險任務：

1

請解釋當前目錄下 README.md 的主要內容，不要修改檔案。

或者：

1

請檢視這個函式，指出可能的邊界條件，不要直接改程式碼。

不要一上來就讓本地模型執行大規模重構。先測讀取、理解和簡短輸出，再逐步測試小修改。

常見報錯：connection refused

典型表現：

1
2
3

connection refused
failed to connect
ECONNREFUSED 127.0.0.1:11434

常見原因：

• Ollama 沒有啟動。
• 埠不是 11434。
• Codex 在 WSL、容器或遠端環境裡執行，訪問不到 Windows 主機的 localhost。
• 防火牆或代理攔截了本地埠。

排查順序：

1. 在同一個終端裡執行 curl http://localhost:11434/api/tags。
2. 確認 ollama serve 或 Ollama 桌面服務正在執行。
3. 如果 Codex 在 WSL 裡，嘗試用 Windows 主機 IP 替代 localhost。
4. 臨時關閉代理環境變數，再測試一次。

如果 curl 也失敗，先修 Ollama 服務。如果 curl 成功但 Codex 失敗，再看 Codex 的配置地址。

常見報錯：model not found

典型表現：

1
2
3

model not found
unknown model
pull model manifest: file does not exist

先檢視本地模型名：

1

ollama list

注意模型名要完整匹配。例如你本地只有：

1

qwen2.5-coder:7b

配置裡寫成 qwen2.5-coder、qwen-coder 或 qwen2.5-coder:latest，都可能找不到。

解決方法：

1

ollama pull qwen2.5-coder:7b

然後把 Codex 裡的模型名改成完全一致的 qwen2.5-coder:7b。

常見報錯：404 或介面路徑不對

如果 Codex 走的是 OpenAI 相容介面，而你直接把地址指到 Ollama 原生 API，有時會出現 404、路徑不匹配或響應格式不對。

需要區分兩類介面：

1
2
3
4
5

Ollama 原生介面：
http://localhost:11434/api/chat

OpenAI 相容介面：
http://localhost:11434/v1/chat/completions

如果你的 Codex 配置要求 OpenAI 相容介面，通常應該把基礎地址寫成類似：

1

http://localhost:11434/v1

而不是：

1

http://localhost:11434/api

遇到 404 時，優先檢查 base URL 和介面模式是否匹配。

常見報錯：context length exceeded

典型表現：

1
2
3

context length exceeded
prompt is too long
input exceeds context window

本地模型的上下文視窗通常比雲端大模型更緊張。Codex 讀取程式碼庫、歷史對話和工具輸出後，很容易超過限制。

解決方法：

• 縮小任務範圍，只讓 Codex 看相關檔案。
• 先讓它總結目錄，再指定要改的檔案。
• 避免一次塞入完整日誌、完整依賴樹和大段生成檔案。
• 換上下文更大的模型。
• 對長檔案先做人工裁剪或分段處理。

如果任務是大型重構，本地模型不一定合適。可以讓本地模型做輔助分析，把最終修改交給更強模型。

常見問題：輸出質量很差

本地模型接上後能回答，但答得亂、改錯檔案、命令瞎編，通常有幾個原因：

• 模型太小，不適合程式碼任務。
• 沒有使用程式碼專用模型。
• 上下文給得太寬，模型抓不住重點。
• 溫度或取樣引數太激進。
• Codex 的任務描述過於開放。

改進方法：

1

只閱讀 src/api/user.ts，找出可能的空值問題。不要修改檔案，只列出發現。

比下面這種更適合本地模型：

1

幫我最佳化整個專案。

本地模型需要更窄、更明確的任務邊界。你越把問題切小，它越穩定。

常見問題：速度很慢

速度慢一般和三件事有關：

• 模型引數量太大。
• 沒有使用 GPU 或視訊記憶體不足。
• 上下文太長，prefill 時間過久。

可以先試小模型：

1

ollama pull qwen2.5-coder:7b

如果 7B 能接受，再嘗試 14B、32B。不要一開始就拉最大模型。對 Codex 來說，響應穩定和可控比引數量好看更重要。

Windows 和 WSL 的 localhost 問題

這是 Windows 使用者最容易踩的坑。

如果 Ollama 跑在 Windows，Codex 跑在 WSL，WSL 裡的 localhost 指的是 WSL 自己，不一定能訪問 Windows 的 Ollama 服務。

可以在 WSL 中測試：

1

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

如果失敗，再找 Windows 主機 IP：

1

cat /etc/resolv.conf

裡面的 nameserver 地址有時可以作為 Windows 主機地址測試：

1

curl http://<windows-host-ip>:11434/api/tags

如果這樣能通，就把 Codex 配置裡的 localhost 換成這個地址。還要確認 Ollama 允許從非本機地址訪問，否則仍然會被拒絕。

代理環境變數導致的異常

如果你配置了代理，Codex 或終端可能會把本地請求也轉發到代理，導致 localhost:11434 訪問異常。

檢查環境變數：

1
2
3

echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY

Windows PowerShell：

1
2
3

$env:HTTP_PROXY
$env:HTTPS_PROXY
$env:NO_PROXY

建議把本地地址加入 NO_PROXY：

1

localhost,127.0.0.1

如果你在 WSL 或區域網 IP 下訪問 Ollama，也把對應 IP 加進去。

什麼時候不建議用 Ollama 接 Codex

以下情況不建議強行用本地模型：

• 要修改生產關鍵路徑。
• 要跨幾十個檔案做架構調整。
• 需要長時間自主執行。
• 專案測試很少，回滾成本高。
• 本地模型已經多次誤解需求。

更穩妥的做法是：本地模型負責草稿、解釋、區域性檢查，雲端強模型負責複雜推理和最終修改。

推薦任務模板

可以把任務寫得更像工單：

1
2
3
4
5
6

請只檢視 src/auth/session.ts。
目標：找出可能導致登入態丟失的邊界條件。
要求：
1. 不要修改檔案。
2. 只輸出問題列表。
3. 每個問題說明觸發條件和建議驗證方式。

如果需要修改，也先限定範圍：

1
2
3
4
5
6

請只修改 src/utils/format.ts。
目標：補齊空字串和 null 的處理。
要求：
1. 不要改函式簽名。
2. 保持現有匯出不變。
3. 修改後說明應該執行哪個測試。

這類寫法能顯著降低本地模型跑偏的機率。

FAQ

Codex 接 Ollama 後能完全離線嗎？

如果 Codex 本身、模型和專案都在本地，並且不呼叫雲端模型，推理可以在本機完成。但具體是否完全離線，還要看你的 Codex 執行方式、外掛、工具呼叫和配置。建議用網路監控或防火牆規則驗證，而不是隻看模型來源。

用哪個 Ollama 模型比較合適？

程式碼任務可以先試 qwen2.5-coder:7b、qwen2.5-coder:14b 這類程式碼模型。機器效能較弱時先用 7B；視訊記憶體和記憶體足夠，再嘗試更大模型。

為什麼同一個問題雲端模型會，本地模型不會？

本地模型引數量、訓練資料、上下文視窗和工具適配通常都不同。接入方式相同，不代表能力相同。把任務切小、給明確檔案範圍、減少開放式要求，效果會好很多。

可以把整個程式碼庫都交給本地模型嗎？

不建議一開始這麼做。先從單檔案、單函式、單報錯開始。如果要分析整個程式碼庫，先讓 Codex 用搜尋工具縮小範圍，再讓模型處理相關片段。

Ollama 需要一直開著嗎？

需要。Codex 呼叫本地模型時，Ollama 服務必須可訪問。關閉 Ollama 後，通常會出現連線失敗或請求超時。

接入成功後還需要 API Key 嗎？

如果只呼叫本地 Ollama，通常不需要雲端模型 API Key。但如果 Codex 配置裡還有其他模型提供方，或者某些功能仍走雲端，就要按實際配置判斷。

小結

Codex 接入 Ollama 的排障順序很簡單：先確認 Ollama 能跑，再確認 HTTP API 能訪問，接著檢查 Codex 的 base URL、介面模式和模型名。連線問題解決後，再處理上下文、速度和輸出質量。

本地模型最適合從小任務開始：解釋、檢查、草稿和低風險修改。只要任務邊界清楚，它可以成為 Codex 的低成本輔助模型；如果把複雜重構和長任務一口氣交給它，體驗通常會變得不穩定。