Codex CLI接入国产大模型：国内环境安装配置实战指南

OpenAI 官方的 Codex CLI 最近在开发者圈子里热度很高很多视频演示里它能在终端里根据自然语言描述直接改代码、跑测试、处理多文件任务看起来确实能当半个“结对程序员”用。但大家问得最多的其实是同一件事国内网络环境和账号支付都不方便这东西到底能不能直接用。这篇文章给一条能跑通的路线。先说结论可以。安装 Codex CLI 只需要 Node.js 环境接入模型方面通过修改 Codex 配置文件把默认的 OpenAI 模型切换成 DeepSeek、通义、智谱等国产大模型提供的 OpenAI 兼容接口就能正常对话和干活不需要海外账号也不需要额外安装复杂的依赖。整个过程里最核心的安装加配置步骤通常一两分钟就能完成。本文会按下面几条线展开先检查本机环境再按 npm 方式安装 Codex CLI然后写配置文件接入国产大模型接着在 VS Code 里接入 Codex 插件并解决常见报错最后给出功能测试、批量任务思路和一份排错表。适合想在本机快速体验编码 Agent、又不想被账号和支付流程卡住的开发者阅读。1. Codex 是什么为什么接入国产大模型1.1 Codex 能做什么Codex 是 OpenAI 推出的编码智能体工具核心形态是一个命令行工具codex。它和普通 AI 补全插件不一样不是只在你输入时给几行建议而是可以理解整个项目目录的代码结构读取文件内容然后按你的要求生成新代码、修改既有文件、执行命令、查看运行结果并且在关键操作前请求用户批准。比较典型的使用方式有三种交互模式在终端输入codex进入对话界面像聊天一样提出编码需求。单次执行模式使用codex exec 描述任务直接发起一次任务适合脚本化调用。编辑器插件模式在 VS Code 中安装 Codex 插件在编辑器里选中代码后直接让 Codex 处理插件底层会调用本机的 Codex CLI。1.2 为什么要接入国产大模型Codex 默认调用 OpenAI 的模型服务这对很多国内开发者来说有几个门槛需要能访问对应的账号体系需要可用的海外支付方式以及需要按模型调用量计费。为了“让 Codex 能用”最常见的做法不是去解决这些前置条件而是换掉模型提供商。Codex 的配置文件支持自定义模型提供商也就是可以设置一个base_url指向任意兼容 OpenAI 接口的服务。国内主流大模型平台基本都提供了这种 OpenAI 兼容接口申请一个 API Key 就能调用支付方式也方便通常还有免费额度。社区里最常见的组合就是 Codex CLI 接 DeepSeek也有不少人接通义千问和智谱 GLM。所以整条路的逻辑很简单Codex 负责“理解任务、操作文件、跑命令”国产模型负责“生成代码和回复”两边通过 OpenAI 兼容接口对接。2. 安装前的环境准备在跑安装命令之前先确认本机基础环境。Codex CLI 主要依赖 Node.js 和 Git所以先把这两项检查好避免安装后启动报错。2.1 检查 Node.js 和 npmCodex CLI 通过 npm 分发所以本机需要有 Node.js 运行环境。打开终端执行node -v npm -v正常情况下会输出类似v20.11.0和10.2.4这样的版本号。如果提示node: command not found说明没装 Node.js。建议直接去 Node.js 官网下载 LTS 版本安装安装时把 “Add to PATH” 选项勾上。Coddex CLI 对 Node 版本有要求使用较新的 LTS 版本可以避免不少兼容问题。安装完成后重新打开终端再执行一次node -v验证。确认能输出版本号再继续。2.2 检查 GitCodex 在处理项目任务时会依赖 Git 来读取仓库状态、生成文件改动最好提前装好。终端执行git --version如果没装去 Git 官网下载对应系统的安装包或者在 Windows 上用包管理器安装。装完之后同样要重开终端验证。2.3 准备国产大模型 API Key这一步是接入国产大模型的关键。以 DeepSeek 为例需要到 DeepSeek 开放平台注册账号在控制台创建一个 API Key。创建后把 Key 复制保存。这类 API Key 相当于调用模型服务的凭证通常按 token 量计费申请后别随意泄露给别人。如果选择通义千问、智谱、Moonshot 等平台流程类似都是“注册平台 - 创建 API Key - 查看文档中的接口地址”。不同平台的接口地址和模型名称会不一样后面在配置里都要用上。3. 快速安装 Codex CLI环境准备好之后进入安装环节。Codex 官方提供多种安装方式本文用 npm 全局安装这是当前社区里最通用、最不容易出问题的方式。3.1 使用 npm 全局安装终端执行npm install -g openai/codex如果网络状况一般npm 下载可能会比较慢。可以先把 registry 切换到国内镜像源再安装npm config set registry https://registry.npmmirror.com npm install -g openai/codex镜像源只影响 npm 包下载速度后续 Codex 请求模型服务时走的是模型平台的接口地址和 npm 镜像没有关系。3.2 验证安装结果安装完成后执行codex --version如果能输出版本号说明安装成功。如果提示command not found多半是 npm 全局 bin 目录没加到系统 PATH 里。可以先查 npm 全局目录npm prefix -g然后把输出目录下的 bin 路径加入 PATH。Windows 用户在 Path 环境变量里追加该目录macOS 和 Linux 用户在终端配置文件中写入类似export PATH$(npm prefix -g)/bin:$PATH保存后重新加载终端配置。3.3 安装后第一次启动先不急着配模型直接运行codex可以看到 CLI 的交互界面和模型相关信息。初次使用如果弹出登录提示可以暂时跳过因为我们接下来会把它配置到国产大模型上。4. 配置 Codex 接入国产大模型默认情况下 Codex 使用 OpenAI 的模型服务。要切换成国产大模型只需要在 Codex 的配置文件中添加一个自定义模型提供商再把默认模型改成这个提供商下的模型即可。4.1 创建 Codex 配置目录和文件Codex 的配置文件固定放在用户目录下的~/.codex/config.toml。如果目录不存在先创建mkdir -p ~/.codex然后打开配置文件vim ~/.codex/config.toml不想用 vim 也可以用任意编辑器打开没有配置文件就新建一个。4.2 配置 DeepSeek 提供商在config.toml中加入下面这段参考配置[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat model deepseek-chat model_provider deepseek这段配置的作用是告诉 Codex 有一个名为deepseek的模型提供商接口地址指向 DeepSeek 的 OpenAI 兼容端点API Key 从环境变量DEEPSEEK_API_KEY读取默认模型使用deepseek-chat。不同版本的 Codex 对配置字段名可能有细微差异。如果按上面配置后启动报错优先查看当前版本的codex --help输出或官方示例配置字段名通常会在帮助信息里体现。DeepSeek 的接口地址官方文档写明https://api.deepseek.com和https://api.deepseek.com/v1都兼容 OpenAI 格式都能用。4.3 设置 API Key 环境变量在 shell 中设置环境变量。macOS 和 Linuxexport DEEPSEEK_API_KEY你的 API KeyWindows PowerShell$env:DEEPSEEK_API_KEY你的 API Key注意环境变量只在当前终端会话生效关掉窗口就失效。需要长期生效的可以写进~/.bashrc、~/.zshrc或 Windows 的用户环境变量里。实际使用时不建议直接把 Key 明文写进config.toml用环境变量更安全也方便后面切换不同服务商。4.4 其他国产模型参考配置如果你选择的是其他平台只需替换base_url和模型名。下面是一个速查表具体地址以平台最新文档为准平台OpenAI 兼容接口地址典型模型名示例DeepSeekhttps://api.deepseek.comdeepseek-chat阿里云百炼https://dashscope.aliyuncs.com/compatible-mode/v1qwen-plus智谱https://open.bigmodel.cn/api/paas/v4glm-4-plusMoonshot Kimihttps://api.moonshot.cn/v1moonshot-v1-8k修改配置时把[model_providers.xxx]里的小节名改成自定义名称env_key也相应换一个环境变量名即可。例如接入通义千问[model_providers.dashscope] name DashScope base_url https://dashscope.aliyuncs.com/compatible-mode/v1 env_key DASHSCOPE_API_KEY wire_api chat model qwen-plus model_provider dashscope4.5 验证模型调用配置完成后先跑一个最简单的请求确认连通性codex exec 用一句话介绍你自己如果配置正确Codex 会调用 DeepSeek 并返回一段模型回复。这一步通了后面所有任务都能走通。如果返回的是模型不存在或者鉴权失败优先检查模型名和 API Key。5. VS Code 接入 Codex CLI终端能用之后很多开发者更习惯在 VS Code 里使用 Codex。官方提供了 VS Code 插件插件本质上是把本机的 Codex CLI 搬进编辑器界面。5.1 安装插件在 VS Code 扩展商店搜索Codex找到 OpenAI 官方发布的那一个点击安装。安装后会看到 Codex 侧边栏面板。5.2 启用插件并选择模型在侧边栏面板登录或选择模型配置。由于我们在终端里已经把默认模型配置成了 DeepSeek插件启动时会读取同一个配置文件理论上可以直接使用。先选中一段代码然后输入任务描述让插件执行一次观察是否正常返回。5.3 处理 “unable to locate the codex cli binary” 报错这是 Codex 插件最常遇到的报错。通常发生在插件安装好了但是找不到codex可执行文件的路径。处理方式确认终端里codex --version能正常输出。在 VS Code 设置中搜索codex找到 CLI Path 配置项填入codex可执行文件的绝对路径。配置完重启 VS Code。如果仍然报错检查 PATH 环境变量是否包含 npm 全局 bin 目录并确认 VS Code 是通过同一个 shell 启动的。出现这个报错不一定是 Codex 没装好大概率是插件进程的环境变量和终端不完全一致。6. 功能测试与实际使用验证配置完成后按场景跑几个测试确认 Codex 真的能处理实际开发任务。6.1 单文件代码生成测试在空目录下创建一个测试目录然后让 Codex 生成一个脚本codex exec 在当前目录生成一个 Python 脚本读取 data.csv 并输出每列平均值执行后 Codex 会给出操作计划和代码确认后写入文件。检查生成的文件是否存在内容是否符合预期。6.2 代码修改与多文件任务测试让 Codex 修改已有代码能更明显看出它理解项目的程度。例如准备一个小项目里面有两个函数然后执行codex exec 把 utils.py 中的两个函数加上类型注解并为它们补一个测试文件Codex 通常会先读取相关文件再给出改动方案最后生成或修改文件。这个测试能验证代码上下文理解能力也是 Codex 相比普通补全工具的核心差异点。6.3 批量任务思路Codex CLI 的exec模式适合脚本化调用。比如有一批仓库希望批量跑同一类任务可以写一个 Shell 脚本循环对每个项目目录执行for dir in repo1 repo2 repo3; do cd $dir || continue codex exec 检查当前仓库中的 README补充安装说明 sleep 2 done批量任务要注意两点一是控制请求频率避免触发模型服务的限流二是给每个任务加上日志输出方便失败后定位。更复杂的批量任务应当把codex exec的输入、输出重定向到文件再统一分析。7. 资源占用与性能观察Codex CLI 本地只运行客户端逻辑模型推理发生在服务端所以它不是本地模型不需要 GPU也不吃显存。安装后占用主要是 npm 包本身和少量缓存可以忽略不计。这和本地跑 Lllama、Qwen 等开源模型是完全不同的资源模型。性能观察主要看两块请求响应速度由所选模型平台的接口速度决定。DeepSeek 的deepseek-chat在普通开发任务上响应够快但长上下文任务耗时会增加。任务执行质量Codex 需要多次调用模型来完成任务如果任务复杂消耗的 token 会明显增加。同样的任务简单模型可能生成粗糙代码更强模型可能生成更完整方案。要降低使用成本尽量把任务描述写具体让 Codex 少做无用的文件遍历和多余修改。如果只是做小型函数生成不需要给 Codex 整个仓库的上下文。8. 常见问题与排查方法问题现象可能原因排查方式解决方案终端提示codex command not foundnpm 全局 bin 目录未加入 PATH执行npm prefix -g查看目录将 bin 路径加入 PATH重启终端unable to locate the codex cli binaryVS Code 插件找不到 CLI 可执行文件终端执行codex --version在插件设置里手动填入 CLI 路径模型返回鉴权失败API Key 错误或环境变量未生效检查环境变量是否在当前终端设置重新设置DEEPSEEK_API_KEY并重开终端模型名称不支持使用的模型名在对应平台不存在到平台控制台查看模型列表换成平台实际支持的模型名请求超时网络或平台服务波动换一个简单任务再试重试或检查网络连通性配置了本地代理后调用失败代理环境变量被污染检查HTTP_PROXY、HTTPS_PROXY确认代理服务正常或临时清掉不用的代理变量生成代码质量差模型选择不当或提示词太模糊观察 Codex 执行过程换成更强模型细化任务描述npm 安装失败网络拉取包失败查看 npm 错误日志切换 npm 镜像源后重试批量任务中途卡住频率限制或单任务上下文过长查看日志输出分批执行加上超时和重试逻辑排查问题的通用思路是先看日志再看环境变量最后看配置文件。Codex 本身会在终端输出详细执行过程哪里断了基本能直接看到。9. 最佳实践与合规提醒使用 Codex 接国产大模型整理几条建议API Key 不要写进代码仓库。使用环境变量或本机密管理工具配置了真实 Key 之后检查.gitignore避免提交到公开仓库。控制模型访问权限。如果团队共用账号建议使用独立 API Key并在平台侧设置额度或限流防止异常调用产生高额账单。代码和敏感数据要谨慎发送。调用第三方模型 API 意味着要把相关文件和任务描述发送到模型服务端涉及内部代码、客户数据时先确认平台的数据处理条款必要时只给 Codex 发送抽象后的代码片段。AI 生成的改动必须人工审查。Codex 能改文件、跑测试但最终合入代码前要检查逻辑是否有问题尤其是涉及权限、支付、数据删除等敏感逻辑。批量任务要记录日志。每个任务写入独立的日志文件包含输入、输出、成功失败状态方便中途断掉后重新开始。不同模型分开配置。如果同时有 DeepSeek、通义、智谱的 Key建议每个平台单独配置一个小节切换模型时只改model和model_provider两行。10. 总结与下一步这篇文章的核心路线是装好 Node.js用 npm 安装 Codex CLI然后修改~/.codex/config.toml把模型指向 DeepSeek 等国产大模型的 OpenAI 兼容接口最后在终端和 VS Code 里验证任务执行。最值得先验证的是codex exec能否用国产模型跑通第一个代码生成任务只要这一步通了后面基本顺畅。最容易踩的坑集中在三处npm 全局 bin 目录没进 PATH、API Key 环境变量没有对当前终端生效、以及 VS Code 插件找不到 Codex CLI 路径。对照排错表处理即可。下一步可以尝试的方向接入多个国产模型做效果对比把codex exec封装成批量代码审查脚本或者接入本地部署的 OpenAI 兼容模型做完全本地化配置。Codex 真正有价值的地方不是“能对话”而是能自主地完成任务链路配合合适的模型和任务描述可以节省大量重复编码时间。建议收藏备用安装时按这篇流程走一遍即可。