OpenRouter on KnightLi的博客

讓 Codex 使用 DeepSeek 模型的兩種方法：本機閘道和 OpenRouter BYOK

Sun, 24 May 2026 09:52:55 +0800

想讓 Codex 使用 DeepSeek，第一反應通常是改 ~/.codex/config.toml：

1
2

model = "deepseek-chat"
base_url = "https://api.deepseek.com"

這個思路在一些舊版本或普通 OpenAI SDK 場景裡確實成立，但放到目前的 Codex CLI 上，很容易撞到一個底層問題：Codex 的自訂模型供應商走的是 OpenAI Responses 協議，而 DeepSeek 官方介面主要提供 OpenAI 相容的 Chat Completions 呼叫方式。

我本機目前是 codex-cli 0.111.0。codex --help 裡可以看到它支援 --config、--model、--profile 這些設定入口；OpenAI 官方 Codex 設定參考也寫得很明確：model_providers.<id>.wire_api 目前只支援 responses，省略時也預設是 responses。

DeepSeek 官方文件則給出的呼叫路徑是 https://api.deepseek.com/chat/completions，範例也是 client.chat.completions.create(...)。所以問題不在於 DeepSeek 不能被 OpenAI SDK 呼叫，而在於 Codex 發出的請求語義，和 DeepSeek 原生介面能理解的語義不完全是同一套東西。

這就是為什麼直接把 base_url 改成 https://api.deepseek.com 後，可能出現下面這些現象：

請求路徑不匹配，直接 404 或回傳格式不對。
多輪對話、工具呼叫、補丁產生時解析失敗。
tool_calls 順序、訊息結構、串流事件格式對不上。
看起來模型能回一句話，但一到 Codex 真正幹活就開始報錯。

更穩的辦法，是在 Codex 和 DeepSeek 之間放一個「翻譯層」。常見有兩種路線。

方法一：用本機閘道橋接 DeepSeek

本機閘道的作用不是簡單轉發，而是把 Codex 側的 Responses 風格請求，轉換成 DeepSeek 能處理的 Chat Completions 風格請求，再把 DeepSeek 的結果轉換回 Codex 能吃的格式。

如果你用的是 ccx 這類本機閘道，設定思路大致是這樣：

[profiles.deepseek-ccx]
model = "deepseek-v4-flash"
model_provider = "ccx-bridge"

[model_providers.ccx-bridge]
name = "Local CCX Gateway"
base_url = "http://localhost:3000/v1"
env_key = "DEEPSEEK_API_KEY"

然後在終端機裡設定 DeepSeek Key，再用這個 profile 啟動：

1
2

export DEEPSEEK_API_KEY="your-deepseek-key"
codex --profile deepseek-ccx

PowerShell 裡是：

1
2

$env:DEEPSEEK_API_KEY="your-deepseek-key"
codex --profile deepseek-ccx

這裡有兩個細節要注意。

第一，base_url 要指向閘道暴露給 Codex 的位址，不是 DeepSeek 官方位址。閘道背後再去呼叫 DeepSeek。

第二，env_key 寫什麼取決於閘道怎麼鑑權。有的閘道直接讀取 DeepSeek 官方 Key，有的閘道會要求你給它一個本機代理 Key，再由閘道自己的後台保存 DeepSeek Key。遇到這種情況，env_key 就應該改成閘道要求的環境變數名。

這條路的優點是本機可控，延遲和成本也更容易算清楚。缺點是你必須確認閘道真的支援 Codex 目前使用的 Responses 語義，而不是只做了普通 Chat Completions 代理。

方法二：用 OpenRouter BYOK 做線上橋接

如果不想在本機部署閘道，可以考慮 OpenRouter 的 BYOK。BYOK 的意思是把你自己的上游供應商 Key 綁定到 OpenRouter，由 OpenRouter 負責路由和轉發。

這裡最容易寫錯的是環境變數。Codex 存取的是 OpenRouter，所以 env_key 通常應該是 OPENROUTER_API_KEY，不是 DEEPSEEK_API_KEY。DeepSeek Key 要在 OpenRouter 的 BYOK 或 provider key 設定裡新增。

設定範例：

[profiles.deepseek-openrouter]
model = "deepseek/deepseek-chat"
model_provider = "openrouter"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"

啟動方式：

1
2

export OPENROUTER_API_KEY="your-openrouter-key"
codex --profile deepseek-openrouter

PowerShell：

1
2

$env:OPENROUTER_API_KEY="your-openrouter-key"
codex --profile deepseek-openrouter

然後在 OpenRouter 後台把 DeepSeek 的 provider key 加進去。OpenRouter 的 BYOK 文件說明，綁定的 provider key 會被加密保存，並用於路由到對應供應商。

這條路的優點是省掉本機閘道維護成本，設定起來更像普通第三方 API 代理。缺點是中間多了一層線上服務，排障時要同時看 Codex、OpenRouter、DeepSeek 三邊的錯誤訊息。

要不要繼續用 deepseek-chat 這個模型名？

DeepSeek 官方文件在 2026 年 5 月的說明裡，推薦模型名已經出現 deepseek-v4-flash 和 deepseek-v4-pro，並提示 deepseek-chat、deepseek-reasoner 相容別名會在 2026-07-24 之後廢棄。

所以新設定裡更建議優先測試：

`1`	`model = "deepseek-v4-flash"`

如果走 OpenRouter，則要按 OpenRouter 的模型命名來寫，例如：

`1`	`model = "deepseek/deepseek-chat"`

實際可用名稱以你所用閘道或 OpenRouter 模型頁為準。模型名不對時，錯誤通常會表現為 model not found、404，或者 provider 找不到對應 endpoint。

直接改 DeepSeek 官方 base_url 為什麼不推薦

你當然可以試著寫：

[profiles.deepseek-direct]
model = "deepseek-v4-flash"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

但這更像排錯實驗，不適合作為穩定方案。因為 Codex 會按 Responses 協議去和自訂 provider 說話，而 DeepSeek 官方範例走的是 /chat/completions。如果 DeepSeek 或 Codex 未來補齊了相容層，這種直連才可能變得簡單；在此之前，橋接層更可靠。

改完設定後還是走 OpenAI 怎麼辦

先確認設定檔位置。全域設定應該在：

`1`	`~/.codex/config.toml`

專案裡的 .codex/config.toml 不適合放 model_provider、model_providers 這類機器級 provider 設定。OpenAI 官方文件也提醒，專案級設定不會覆蓋這些本機 provider 和認證相關欄位。

如果 Codex 仍然要求網頁登入，或者看起來還在走預設 OpenAI 模型，可以先退出目前登入狀態：

`1`	`codex logout`

有些舊教學會寫成交互介面裡的 /logout。在目前 CLI 裡，更穩的是直接在終端機執行 codex logout。

還可以用臨時參數做一次快速驗證：

`1`	`codex --profile deepseek-ccx`

或者：

`1`	`codex -c model_provider=ccx-bridge -c model=deepseek-v4-flash`

如果這樣能生效，說明設定本身可讀；如果不生效，優先檢查 profile 名稱、TOML 語法、環境變數是否只在目前 shell 裡有效。

排障清單

401：Key 不對，或者 env_key 指向了錯誤的環境變數。
404：base_url 或模型名不對，也可能是把 Responses 請求打到了只支援 Chat Completions 的位址。
tool_calls、patch、串流解析報錯：大機率是協議橋接不完整。
仍然提示登入 OpenAI：執行 codex logout，再確認是否用了正確 profile。
PowerShell 設定環境變數後新開視窗失效：$env:... 只對目前會話生效，需要長期保存就改使用者環境變數。
OpenRouter BYOK 沒走自己的 DeepSeek Key：檢查 OpenRouter 後台 provider key 是否綁定、是否允許目前 OpenRouter API Key 使用，以及是否開啟了 fallback。

結論

讓 Codex 使用 DeepSeek，不是不能改 config.toml，而是不能只改 base_url 就指望一切自動相容。

目前更穩的兩條路是：

用本機閘道做協議橋接，Codex 連本機閘道，閘道再連 DeepSeek。
用 OpenRouter BYOK 做線上轉發，Codex 連 OpenRouter，DeepSeek Key 綁定在 OpenRouter 後台。

如果只是想快速試用，OpenRouter 路線更省事；如果你希望 Key、成本、日誌都盡量掌握在自己手裡，本機閘道更適合長期折騰。

參考資料：

free-claude-code：用代理把 Claude Code 接到 OpenRouter、DeepSeek 和本地模型

Fri, 01 May 2026 03:41:49 +0800

free-claude-code 是一個給 Claude Code 使用的 Anthropic-compatible proxy。

它的思路不是破解 Claude Code，也不是提供官方免費的 Claude 服務，而是在本地啟動一個相容 Anthropic API 形狀的代理服務，把 Claude Code 發出的請求轉發到其他模型後端。README 中提到的後端包括 NVIDIA NIM、OpenRouter、DeepSeek、LM Studio、llama.cpp 和 Ollama。

簡單說，它想解決的是：你喜歡 Claude Code 的終端體驗，但希望把模型請求接到別的 provider 或本地模型上。

它解決什麼問題

Claude Code 的互動體驗很適合開發任務。

它可以在終端裡閱讀程式碼、修改檔案、執行命令、根據專案上下文推進任務。問題是，很多使用者並不一定想始終使用同一個模型後端：

想試試 OpenRouter 上的不同模型
想用 DeepSeek 這類模型降低成本
想把請求接到本地 Ollama
想用 LM Studio 或 llama.cpp 跑本地模型
想在開發環境裡統一走一個代理入口
想比較不同模型在 Claude Code 工作流裡的表現

free-claude-code 的定位，就是在 Claude Code 和這些模型服務之間加一層相容代理。

這樣 Claude Code 仍然按 Anthropic 風格發請求，代理負責把請求適配到不同後端。

工作方式

可以把它理解成三層：

前端是 Claude Code
中間是 free-claude-code 代理
後端是 OpenRouter、DeepSeek、本地模型或其他模型服務

Claude Code 以為自己在存取一個 Anthropic-compatible API。

代理收到請求後，根據配置選擇目標 provider，轉換必要欄位，再把回應返回給 Claude Code。

這類結構的好處是，你不用改 Claude Code 本身，也不用讓每個模型服務都原生支援 Claude Code。只要代理能把介面對齊，就能把更多模型接進同一個工作流。

支援哪些後端

README 中列出的方向包括：

NVIDIA NIM
OpenRouter
DeepSeek
LM Studio
llama.cpp
Ollama

這些後端代表了幾類不同使用方式。

OpenRouter 更像模型聚合入口，可以測試不同商業和開源模型。

DeepSeek 適合關注中文能力、程式碼能力和成本的人。

LM Studio、llama.cpp、Ollama 則偏本地模型路線。它們適合在自己的機器或內網環境裡執行模型，減少外部 API 依賴，也方便做離線實驗。

NVIDIA NIM 則更偏企業和 GPU 推理部署場景。

為什麼是 Anthropic-compatible proxy

Claude Code 本來圍繞 Anthropic 的介面和模型習慣設計。

如果你想讓它接入其他模型，最直接的問題就是介面不一致：

請求欄位不同
模型名稱不同
streaming 格式不同
tool use 表達不同
錯誤返回格式不同
token 和上下文限制不同

代理層的價值就在這裡。

它把 Claude Code 這邊看到的介面維持在接近 Anthropic 的形狀，再在後端做適配。對使用者來說，配置一次代理後，就可以在相同 Claude Code 工作流裡測試不同模型。

適合什麼場景

free-claude-code 適合這些場景：

想用 Claude Code 的終端工作流
想測試非 Anthropic 模型在 Claude Code 裡的表現
想降低模型呼叫成本
想把 Claude Code 接到 OpenRouter
想接入 DeepSeek 等相容模型服務
想用 Ollama、LM Studio、llama.cpp 跑本地模型
想為團隊統一配置一個模型代理入口

如果你只是正常使用官方 Claude Code，並且對模型提供方、成本和本地部署沒有特殊需求，那不一定需要這類代理。

但如果你經常比較模型，或者希望讓 Claude Code 接入本地和第三方模型，這類工具會很有用。

和直接用 OpenRouter 或 Ollama 有什麼區別

直接用 OpenRouter、Ollama 或 LM Studio，通常只是和模型聊天，或者透過 API 呼叫模型。

free-claude-code 的重點不是替代這些服務，而是把它們接到 Claude Code 這個開發工作流裡。

區別在於：

你仍然使用 Claude Code 的終端體驗
AI 可以圍繞程式碼倉庫執行任務
模型後端可以換成其他 provider
本地模型也有機會進入 Claude Code 工作流
配置集中在代理層，而不是每個工具單獨改

所以它更像橋接器，而不是新的聊天客戶端。

本地模型要注意什麼

把 Claude Code 接到本地模型很有吸引力，但也要注意現實限制。

第一，模型能力差距。

Claude Code 的任務通常不只是聊天，還包括理解程式碼、規劃修改、編輯檔案、處理命令輸出。本地小模型不一定能穩定完成這些任務。

第二，上下文視窗。

程式碼任務很吃上下文。模型上下文太小，會導致它讀不全檔案、漏掉約束，或者在多輪任務裡丟失背景。

第三，tool use 相容性。

Claude Code 工作流依賴工具呼叫和結構化行為。後端模型即使能聊天，也未必擅長遵循工具呼叫協議。

第四，速度和硬體。

本地模型的速度取決於機器配置、量化方式和模型大小。程式碼任務如果回應太慢，體驗會明顯下降。

所以，本地模型更適合實驗、低風險任務和特定場景。真正複雜的程式碼任務，仍然要根據模型能力謹慎選擇。

使用邊界

這類專案很容易被標題誤解，所以邊界要說清楚。

第一，它不是官方 Claude Code 免費額度。

它只是把 Claude Code 的請求轉發到其他模型後端。你使用 OpenRouter、DeepSeek、NVIDIA NIM 或其他 API 時，仍然需要遵守對應服務的價格、額度和使用條款。

第二，它不是繞過授權的工具。

使用任何代理工具時，都應該遵守 Claude Code、模型服務商和專案本身的授權協議。不要把它理解成規避官方限制的方式。

第三，代理會處理你的請求內容。

程式碼、命令輸出、專案上下文可能會經過代理和後端服務。部署時要考慮日誌、金鑰、網路和隱私邊界。涉及公司程式碼或敏感專案時，最好使用受控環境。

第四，不同模型表現差異會很大。

同樣的 Claude Code 操作，換一個模型後可能出現完全不同的行為。不要預設所有模型都能替代 Claude。

和 LiteLLM 這類代理有什麼關係

從思路上看，free-claude-code 屬於「相容介面代理」這一類工具。

這類工具的共同目標是減少上層應用和底層模型服務之間的耦合。上層應用只需要面對一個相對統一的介面，底層 provider 可以按配置切換。

不同專案的側重點不同。有的更偏通用模型閘道，有的更偏 OpenAI-compatible API，有的專門為 Claude Code 這類工具做適配。

free-claude-code 值得關注的地方，是它把目標場景直接放在 Claude Code 上，而不是做一個泛泛的聊天代理。

適合怎樣的使用者

它更適合有一定折騰能力的使用者：

熟悉 Claude Code
知道 API key 和模型 provider 怎麼配置
能理解代理服務的啟動和環境變數
能排查網路、連接埠、模型名稱和 streaming 問題
願意比較不同模型在程式碼任務裡的表現

如果你只想開箱即用，官方配置通常更省心。

如果你願意搭代理、換模型、調參數，並且想讓 Claude Code 進入更多模型環境，這個專案就值得研究。

參考

Alishahryar1/free-claude-code

最後一句

free-claude-code 的價值，不在於「免費」這個詞，而在於它把 Claude Code 和更多模型後端之間接了一座橋。

當你想保留 Claude Code 的開發體驗，同時測試 OpenRouter、DeepSeek、本地模型或企業推理服務時，這類 Anthropic-compatible proxy 就有了用武之地。