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 下载安装教程:手机与电脑端全流程,那篇讲的是四端安装与账号登录,这篇补的是换内核。
信息来源
- openai/codex 官方仓库与 README(安装命令、发行版下载说明)
- Codex Advanced Configuration(model_providers、保留 ID、profile、openai_base_url;英文站,国内部分网络需代理)
- Codex Config basics(配置优先级、approval_policy、sandbox_mode)
- DeepSeek 官方 API 文档(base_url 与模型名)
- Moonshot 官方文档:从 OpenAI 迁移到 Kimi(base_url)
- 智谱官方文档:OpenAI 兼容接入(base_url)
- npmmirror 镜像站(@openai/codex 安装包)