Codex 国内用法:把内核换成 DeepSeek 等国产模型

Codex 是 OpenAI 开源的本地编码 Agent,装在电脑上就能读写你的仓库、跑命令、改代码。它有一个很多人没注意到的能力:客户端和模型是分开的。只要把配置里的模型供应商换成一个 OpenAI 兼容的接口,它就能接 DeepSeek、Kimi、智谱 GLM 这些国内能直连的模型,甚至接你本地跑的 Ollama。这篇讲的就是国内环境下的安装 + 换内核全流程。

本文信息核对时间:2026 年 11 月 17 日。Codex 版本迭代快(当前 npm 包最新 0.169.0),配置字段以官方 Advanced Configuration 文档为准。

核心要点

  • 能换的部分:Codex CLI 的对话模型由 model + model_provider 决定,可指向任意 OpenAI 兼容端点;不能换的是 ChatGPT 云端那套服务(Codex Web、账号托管任务)。
  • 换的位置:写在用户级配置 ~/.codex/config.toml。项目里的 .codex/config.toml 出于安全会忽略 provider 相关键,写了也不生效。
  • 关键字段:base_url(接口地址)、env_key(从哪个环境变量读 API Key)、wire_api(接口协议,国内服务一般用 Chat Completions)。
  • 已在官方文档核对:自定义 provider 的结构、保留 ID(openai、ollama、lmstudio 不能被自定义占用)、改内置 OpenAI 地址应使用 openai_base_url。
  • DeepSeek 端点:OpenAI 兼容地址为 https://api.deepseek.com,模型名 deepseek-flash、deepseek-v4-pro(来源:DeepSeek 官方 API 文档)。

一、先分清:Codex 有四个形态,只有一部分能换内核

  • Codex CLI:开源在 github.com/openai/codex,终端里运行,是本文的主角。它的模型供应商完全可配置。
  • IDE 扩展(VS Code / Cursor / Windsurf):和 CLI 共用同一套配置文件,改了 config.toml 扩展里也生效。
  • 桌面 App:图形界面,功能依赖 OpenAI 账号体系,可配置项比 CLI 少。
  • Codex Web:跑在 OpenAI 云端,代码在云上执行,只能用官方模型,换不了内核。国内想「自己的模型自己跑」,看 CLI。

一句话判断:你要的是「本地终端里的编码 Agent + 自己选的模型」,那就是 CLI;你要的是「OpenAI 云端帮我在沙箱里跑任务」,那是 Web,换不了。

二、安装:国内能走通的三种方式

方式 1:npm 安装(最省事,可走国内镜像)

Codex CLI 在 npm 上有官方包,且已提供 Windows / macOS / Linux 的预编译版本,不需要本地编译。

npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex
codex --version

包地址在 registry.npmmirror.com 对应的 @openai/codex 页面可查,装完用 codex --version 确认版本号输出正常。

方式 2:官方安装脚本(需要能访问 chatgpt.com)

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

官方说明里有个细节值得知道:脚本默认从 releases.openai.com 下载二进制,取不到时才回退 GitHub Releases。想强制走 GitHub Releases,装的时候带上环境变量 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false。

方式 3:直接下二进制

从 GitHub Releases 按平台取压缩包,解压后把 codex 放进 PATH 里任意目录。这一步不依赖 OpenAI 域名,只依赖 GitHub。

三、换内核:把 config.toml 改成你的模型

配置文件位置:macOS / Linux 在 ~/.codex/config.toml,Windows 在 C:\Users\你的用户名\.codex\config.toml。没有就新建。

官方给的 provider 结构长这样(来自 Codex 官方 Advanced Configuration 文档):

提示:官方配置文档放在 OpenAI 开发者站,国内部分网络需代理才能打开;GitHub 仓库里的 docs/config.md 指向的正是同一批页面,可作为入口核对。

model = "模型名"
model_provider = "供应商ID"

[model_providers.供应商ID]
name = "显示名称"
base_url = "接口地址"
env_key = "读哪个环境变量里的Key"
wire_api = "chat"     # 或 responses

三个容易踩的点先说清楚:

  • openai、ollama、lmstudio 是内置保留 ID,不能拿来命名自定义 provider。想改内置 OpenAI 的地址,用顶层的 openai_base_url,不要新建 [model_providers.openai]。
  • Key 不要直接写进配置文件。用 env_key 指向环境变量,Key 本身放在系统环境变量里。
  • wire_api 声明接口协议。国内厂商基本都是 Chat Completions 兼容,写 chat;如果你的网关同时支持 Responses API,可以写 responses。

模板 A:接 DeepSeek(端点与模型名来自 DeepSeek 官方文档)

model = "deepseek-v4-pro"        # 也可用 deepseek-flash
model_provider = "deepseek"

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

然后在系统里设置 Key(Windows 用 PowerShell,设完要重开终端):

# Windows
setx DEEPSEEK_API_KEY "sk-你的key"

# macOS / Linux
export DEEPSEEK_API_KEY="sk-你的key"   # 想长期生效写进 ~/.zshrc 或 ~/.bashrc

模板 B:接 Kimi(Moonshot)(base_url 取自官方「从 OpenAI 迁移到 Kimi」文档)

model = "你的Kimi模型ID"          # 以平台控制台显示的模型名为准
model_provider = "kimi"

[model_providers.kimi]
name = "Kimi"
base_url = "https://api.moonshot.cn/v1"
env_key = "MOONSHOT_API_KEY"
wire_api = "chat"

模板 C:接智谱 GLM(base_url 取自智谱官方 OpenAI 兼容接入文档)

model = "你的GLM模型ID"           # 以 open.bigmodel.cn 控制台的模型名为准
model_provider = "zhipu"

[model_providers.zhipu]
name = "智谱GLM"
base_url = "https://open.bigmodel.cn/api/paas/v4"
env_key = "ZHIPU_API_KEY"
wire_api = "chat"

模板 D:接本地 Ollama(完全不联网也能用)

model = "qwen3-coder:30b"
model_provider = "ollama"

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

注意 ollama 是保留 ID,这里等于直接复用内置 provider 的地址写法;也可以不写这段,启动时加 --oss 参数,Codex 会按 oss_provider = "ollama" 走本地模型。

四、验证与常见报错

  • 怎么确认换成功了:在仓库目录运行 codex,启动信息里会显示当前模型与 provider;问一句「你现在用的是什么模型」,回答能对上就通了。
  • 401 / Unauthorized:环境变量没生效。Windows 上 setx 之后必须重开终端;macOS 上确认写进了当前 shell 的启动文件。
  • 404 / model not found:model 写的模型名和平台不一致。DeepSeek 是 deepseek-flash / deepseek-v4-pro;Kimi、智谱请照控制台里的模型 ID 抄。
  • wire_api 相关报错:该服务只支持 Chat Completions,把 wire_api 改成 chat;反之若网关只支持 Responses,改成 responses。
  • 长上下文截断:不同模型上下文长度不一样,可用 model_context_window = 128000 这类键显式告诉 Codex 窗口大小。
  • 配置没生效:检查是不是写到了项目里的 .codex/config.toml。官方明确说明,项目级配置会忽略 model_provider、model_providers、openai_base_url 这些键,并打印启动警告。

五、用得更顺手的几个开关

  • 多套配置来回切:0.134.0 之后用 profile 文件。把 DeepSeek 那套单独存成 ~/.codex/deepseek.config.toml,启动时 codex --profile deepseek 即可;注意新版本不再从 config.toml 的 [profiles.x] 里读。
  • 单次临时改:codex --model deepseek-flash,或用 -c 覆盖任意键,例如 codex -c model='"deepseek-flash"'。
  • 审批与沙箱:默认它会先问你才执行命令。approval_policy = "on-request"、sandbox_mode = "workspace-write" 是比较稳的组合;danger-full-access 不要随手开。
  • 推理强度:model_reasoning_effort(如 high)、model_verbosity = "low" 可调回答长度,后者只对 Responses 协议生效,Chat Completions 的 provider 会忽略。

六、边界与注意事项

  • 换的是模型,不是服务。Codex Web、账号托管的云端任务、部分依赖 OpenAI 侧的能力不会跟着换;登录态相关功能仍需官方账号。
  • 代码会发给你选的厂商。换成第三方 API 后,仓库内容会作为上下文发到对方服务器,公司项目请先确认合规与数据出境要求;敏感仓库优先用本地 Ollama。
  • 能力有差异。Codex 的提示词与工具调用是按自家模型调的,换成别的模型后,多步改代码的成功率会有波动,建议先在个人项目上试,别直接在生产仓库放开写入权限。
  • Key 管理。只放环境变量,别提交进 git;怀疑泄露立刻在平台控制台吊销重建。
  • 版本与文档。配置字段更新较快,遇到对不上的字段,以官方 Advanced Configuration / Configuration Reference 页面当前版本为准。

总结

国内用 Codex,卡点从来不是「装不上」,而是「装上了但模型连不出去」。把视角从「用 OpenAI 的服务」换成「用一个能换模型的本地编码 Agent」,路径就清晰了:npm 装 CLI → 在 ~/.codex/config.toml 里加一段 model_providers → Key 放环境变量 → 跑起来验证。DeepSeek 是最省事的起点(端点简单、模型名明确),要数据不出内网就接 Ollama。装的时候参考站内 Codex 下载安装教程:手机与电脑端全流程,那篇讲的是四端安装与账号登录,这篇补的是换内核。

信息来源

发表评论

您的邮箱地址不会被公开。必填项已用 * 标注

© 2026 AI泡泡堂 · 银川鲸鱼智家网络科技有限公司 · 宁ICP备2026003950号
回到顶部
公安联网备案:宁公网安备64010002000275号