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 就有了用武之地。