本地大模型 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 或 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"

這條路要注意四個邊界：

1. 只寫在用戶級 ~/.codex/config.toml。 Codex 會忽略項目 .codex/config.toml 裏的 openai_base_url、model_provider 和 model_providers，以避免倉庫偷偷改變機器的模型提供方。
2. 服務不只是“有 /v1/chat/completions”就一定夠用。Codex 的具體工作流可能需要模型、流式響應、工具調用或其他兼容行爲。
3. 鑑權由你的網關決定。若網關要求 Bearer token，應按網關和 Codex 當前認證配置正確設置；不要把 token 寫進倉庫文件。
4. 這不是 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。

LM Studio OpenAI 相容本機 API 詳解

LM Studio 可以把本地加載的模型變成 OpenAI 兼容接口。對現有項目來說，通常不需要重寫調用邏輯：把 OpenAI 客戶端的 base_url 改成 LM Studio 本地地址，再把 model 換成 LM Studio 裏的模型標識即可。

最常用的地址是：

1

http://localhost:1234/v1

它適合接入已有的 Python、JavaScript、C# 或其他 OpenAI 客戶端代碼。下面按“先跑通，再接進項目”的順序說明。

先說結論

要使用 LM Studio 的 OpenAI 兼容接口，只需要完成四步：

1. 在 LM Studio 的 Developer 頁面啓動本地服務器。
2. 加載一個聊天模型。
3. 請求 http://localhost:1234/v1/models，確認模型 ID。
4. 將客戶端 base_url 改爲 http://localhost:1234/v1。

最小 Python 寫法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",
)

response = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[
        {"role": "user", "content": "用一句话解释什么是 KV cache。"}
    ],
)

print(response.choices[0].message.content)

api_key="lm-studio" 在未開啓鑑權時只是給 OpenAI SDK 的佔位值；如果你在 LM Studio 服務設置中啓用了 API token，則應改成真正的 token。

第一步：啓動 LM Studio 本地服務器

打開 LM Studio，進入 Developer 頁面，打開 Start server 開關。默認服務會監聽：

1

http://localhost:1234

也可以使用 LM Studio 的命令行工具啓動：

1

lms server start

如果電腦上還沒有 lms，可以按 LM Studio 官方文檔安裝 CLI：

1

npx lmstudio install-cli

服務啓動只代表 API 端口已監聽，不代表已經有可推理的模型。繼續在 Chat 或 Developer 頁面加載一個模型，或者用 lms load 載入。

第二步：先獲取模型 ID

不要憑文件名猜 model 參數。最穩的辦法是請求模型列表：

1

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

Windows PowerShell 可以用：

1

Invoke-RestMethod http://localhost:1234/v1/models

返回的 data 列表裏會有模型標識。之後在請求中把 model 填爲實際返回的 ID。

這一步能避免兩個常見問題：模型雖然下載了但還沒加載，或者代碼裏寫的名稱與 LM Studio 當前暴露的模型 ID 不一致。

第三步：用 curl 測試 Chat Completions

先用最直觀的 OpenAI 兼容端點測試：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的 LM Studio 模型 ID",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "解释什么是向量数据库。"}
    ],
    "temperature": 0.7
  }'

成功後，回答通常在：

1

choices[0].message.content

Chat Completions 會自動應用聊天模型的 prompt template。只要模型本身是 chat/instruct 類型，通常不需要在客戶端手動拼接特殊控制 token。

Python 項目怎麼替換 OpenAI

如果項目原本就使用 OpenAI Python SDK，重點通常只有兩處：base_url 和 model。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",
)

completion = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[
        {"role": "system", "content": "你是一名 Python 助手。"},
        {"role": "user", "content": "写一个读取 JSON 文件的最小示例。"},
    ],
    temperature=0.2,
    max_tokens=500,
)

print(completion.choices[0].message.content)

這樣做的好處是：應用層仍然使用 OpenAI SDK 的對象和返回格式，後端可在雲端 OpenAI API 與本地 LM Studio 之間切換。

但“兼容”不等於每個雲端模型特性都能原樣複製。工具調用、結構化輸出、視覺輸入、推理內容和 Responses API 是否可用，仍取決於 LM Studio 版本、當前模型能力和對應端點支持情況。

流式輸出

在 Chat Completions 中設置 stream=True：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

stream = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[{"role": "user", "content": "写一首四行小诗。"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

流式輸出適合聊天界面、終端工具和長回答。它改善的是用戶等待體驗，不會讓本地模型本身生成得更快。

Embeddings、Responses 與原生 REST API 怎麼選

LM Studio 的 OpenAI 兼容層包含常用端點：

LM Studio 也有自己的原生接口，當前推薦路徑是 /api/v1/*，例如 /api/v1/chat 和 /api/v1/models。原生 API 更適合需要模型加載/卸載、狀態化聊天、MCP 或 LM Studio 專屬能力的項目。

簡單判斷：已有 OpenAI SDK 項目，優先用 /v1；新項目要深度管理本地模型或使用 LM Studio 專屬能力，再考慮 /api/v1。

結構化輸出和工具調用

LM Studio 的 OpenAI 兼容層支持在相應端點中使用工具調用與結構化輸出，但先確認兩件事：

1. 你加載的模型本身要有較可靠的工具調用或 JSON 輸出能力。
2. LM Studio 和客戶端 SDK 的版本要足夠新。

不要只因爲請求沒有報錯，就假設模型能穩定生成符合 schema 的結果。上線前應使用真實參數、異常分支和多輪請求做測試。

常見報錯排查

1. 連接被拒絕或 Connection refused

先確認 Developer 頁面裏的服務器已啓動，再測試：

1

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

如果這裏都連不上，優先檢查端口、LM Studio 是否仍在運行，或本機安全軟件是否攔截本地端口。

2. 404 Not Found

最常見原因是路徑寫錯。OpenAI 兼容聊天端點是：

1

/v1/chat/completions

不是 /api/v1/chat/completions。後者屬於另一套原生 API 路徑。

3. 模型不存在或返回空列表

先在 LM Studio 中加載模型，再檢查 /v1/models 的返回。代碼裏的 model 必須使用實際返回的標識，不要照抄別人的模型名。

4. 能回答但格式很奇怪

檢查是否加載了 base 模型而不是 instruct/chat 模型；同時檢查聊天模板是否由 LM Studio 自動應用。對於工具調用和 JSON 輸出，還要確認模型是否真正支持該能力。

5. 局域網設備訪問不到

LM Studio 可以在 Developer 頁面配置服務到本地網絡。開啓網絡訪問後，還需要確認防火牆、監聽地址和 API token 設置。不要把無鑑權的本地模型服務直接暴露到公網。

一套最小接入清單

1
2
3
4
5
6
7

1. LM Studio Developer -> Start server
2. 加载一个 instruct/chat 模型
3. curl http://localhost:1234/v1/models
4. 客户端 base_url 改为 http://localhost:1234/v1
5. model 填实际返回的 ID
6. 用 chat/completions 跑通单轮请求
7. 再测试流式、工具调用、Embeddings 或结构化输出

先跑通最小請求，再接 RAG、Agent 或編輯器插件，排障會簡單很多。

總結

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

1
2
3
4
5

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

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

參考：

• Codex OSS mode local providers
• Codex configuration reference
• Codex developer commands
• LM Studio OpenAI 兼容接口教程
• vLLM KV Cache 內存不足排查