本地大模型 API 給 Codex 使用教程：Ollama、LM Studio 和 vLLM

想讓 Codex 使用本地大模型，先不要把任何 OpenAI 兼容地址直接塞進項目配置。當前 Codex 有一條更穩妥的本地模型路徑：OSS 模式。它原生支持選擇 Ollama 或 LM Studio 作爲本地提供方。

最短命令是：

1

codex --oss --local-provider ollama

或者：

1

codex --oss --local-provider lmstudio

如果你自己部署的是 vLLM、LiteLLM 或其他 OpenAI 兼容網關，則可以研究 openai_base_url 的高級配置。但這條路徑要求服務真正兼容 Codex 所需的 API 行爲，排障成本也更高，不應和內置 OSS 模式混爲一談。

先選對路線

你的本地服務	推薦接法	適合誰
Ollama	`codex --oss --local-provider ollama`	想最快跑通本地模型
LM Studio	`codex --oss --local-provider lmstudio`	已在 LM Studio 下載和管理模型
vLLM / 自建 OpenAI 兼容服務	用戶級 `openai_base_url`	已瞭解 API 兼容性、鑑權與模型路由的高級用戶

普通個人用戶建議先跑通 Ollama 或 LM Studio。Codex 的 --oss 會使用指定的本地 OSS 提供方；如果沒有傳 --local-provider，也沒有設置默認值，交互式 CLI 會提示你選擇，但 codex exec 會直接報錯。

方案一：用 Ollama 接入 Codex

1. 確認 Ollama 和模型可用

先檢查 Ollama 是否可用：

1
2


ollama -v
ollama ls

沒有模型時，先下載一個適合本機顯存的代碼或通用模型，例如：

1

ollama pull qwen3:8b

再單獨測試：

1

ollama run qwen3:8b

模型在 Ollama 裏都跑不通時，先解決顯存、驅動、模型下載或 Ollama 服務問題；不要直接轉到 Codex 排查。

2. 單次使用本地模型

在項目目錄執行：

1

codex --oss --local-provider ollama

隨後像平時一樣輸入任務，例如：

1

阅读这个仓库的 README，列出本地启动步骤，不要修改文件。

這隻影響當前會話。想臨時切回常規 Codex，不帶 --oss 啓動即可。

3. 把 Ollama 設爲默認本地提供方

如果經常使用本地模型，把下面內容放到用戶級 Codex 配置文件：

1

oss_provider = "ollama"

之後可直接運行：

1

codex --oss

Codex 的用戶級配置通常位於 CODEX_HOME 下，默認是 ~/.codex/config.toml；Windows 常見路徑是：

1

C:\Users\你的用户名\.codex\config.toml

修改後重開 Codex。若已有複雜配置，先備份 config.toml，只添加這一行，不要覆蓋原有 sandbox、MCP、技能等設置。

方案二：用 LM Studio 接入 Codex

LM Studio 適合已經下載了 GGUF 模型、希望用圖形界面調上下文和 GPU 卸載的人。

1. 在 LM Studio 啓動本地服務並加載模型

進入 LM Studio 的 Developer 頁面，啓動 server，並確認一個 chat/instruct 模型已經加載。LM Studio 的本地 API 默認監聽在：

1

http://localhost:1234

可以先驗證模型服務：

1

curl http://localhost:1234/v1/models

這裏返回的是 LM Studio 側模型狀態；它有助於確認服務和模型都已就緒。

2. 用 Codex OSS 模式啓動

1

codex --oss --local-provider lmstudio

長期默認配置：

1

oss_provider = "lmstudio"

然後使用：

1

codex --oss

LM Studio 的模型上下文長度、GPU offload 和推理參數仍由 LM Studio 管理。若 Codex 反應慢，優先檢查模型大小是否超過顯存、上下文是否設得過長，以及是否同時有其他本地推理服務佔用 GPU。

方案三：vLLM 等 OpenAI 兼容 API 的高級接法

vLLM、LiteLLM、企業網關和一些代理會提供 OpenAI 兼容的 /v1 接口。Codex 的官方配置參考提供了 openai_base_url，用於覆蓋內置 openai 提供方的基礎地址。

示意配置：

1

openai_base_url = "http://127.0.0.1:8000/v1"

如果服務在局域網主機：

1

openai_base_url = "http://192.168.1.20:8000/v1"

這條路要注意四個邊界：

只寫在用戶級 ~/.codex/config.toml。 Codex 會忽略項目 .codex/config.toml 裏的 openai_base_url、model_provider 和 model_providers，以避免倉庫偷偷改變機器的模型提供方。
服務不只是“有 /v1/chat/completions”就一定夠用。Codex 的具體工作流可能需要模型、流式響應、工具調用或其他兼容行爲。
鑑權由你的網關決定。若網關要求 Bearer token，應按網關和 Codex 當前認證配置正確設置；不要把 token 寫進倉庫文件。
這不是 Codex 官方列出的 OSS 本地提供方。遇到異常時，先用 Ollama 或 LM Studio 驗證 Codex OSS 模式，再排查網關兼容性。

vLLM 服務可先單獨驗證：

1

curl http://127.0.0.1:8000/v1/models

只有該命令穩定返回模型列表後，才繼續檢查 Codex 的用戶級 openai_base_url。

怎麼選模型

本地模型能否“用”與能否“像 Codex 官方模型一樣可靠”是兩件事。代碼 Agent 通常需要長上下文、穩定工具調用、較強的代碼理解和足夠快的生成速度。

選型時至少看：

顯存能否容納模型權重和常用上下文；
模型是否是 instruct/chat 或專門的代碼模型；
是否能穩定遵循文件修改、測試和命令執行要求；
是否支持你需要的工具調用或 JSON 輸出；
長任務下是否容易跑偏、忘記約束或產生不完整修改。

本地 7B/8B 模型適合倉庫瀏覽、簡單腳本、文檔整理和局部修改。多文件重構、複雜測試修復和長時間 Agent 任務，對模型和硬件要求更高；不要因爲本地 API 能連通，就默認它適合承擔高風險自動改動。

一套安全的起步方式

第一次用本地模型驅動 Codex，建議先限制權限：

1

codex --oss --local-provider ollama --sandbox read-only

先讓模型完成只讀任務：

1

分析当前仓库的目录结构，指出启动命令和测试命令。不要修改文件。

確認模型理解倉庫、輸出穩定後，再逐步允許 workspace 寫入和測試執行。不要爲了省確認步驟直接啓用無沙箱或跳過審批的模式。

常見問題

1. `codex exec --oss` 直接報錯

通常是沒有指定本地提供方。使用：

1

codex exec --oss --local-provider ollama "只分析当前仓库，不修改文件"

或在用戶級配置中設置 oss_provider。

2. Codex 連不上 Ollama 或 LM Studio

先分別驗證服務：

1
2


ollama ls
curl http://localhost:1234/v1/models

再檢查服務是否啓動、模型是否加載、本機端口是否被防火牆或其他進程影響。

3. 本地模型總是改壞代碼

先縮小任務：讓它只讀分析、只改一個文件、先給方案再執行。並使用 Git 分支或提交點保存可回退狀態。模型能力不足時，提升提示詞複雜度通常解決不了根本問題。

4. 配置寫了卻沒有生效

檢查是否誤寫進項目 .codex/config.toml。提供方相關鍵需要寫在用戶級 ~/.codex/config.toml；修改後重新啓動 Codex。

總結

讓本地大模型給 Codex 使用，優先順序應是：

1
2
3
4
5


Ollama / LM Studio 跑通模型
-> codex --oss --local-provider ollama|lmstudio
-> 只读任务验证
-> 设置 oss_provider 作为默认
-> 再考虑 vLLM 等 OpenAI 兼容网关

對絕大多數用戶，--oss 是最短、最可控的入口。openai_base_url 適合已有兼容網關和運維需求的高級場景，但應放在用戶級配置並先做接口兼容性驗證。

參考：