企业官网建设流程全解析

最近 Codex 的讨论热度很高，很多开发者想尝尝鲜，却发现要么卡在 Node.js 环境准备，要么卡在 npm 安装超时，要么卡在登录那一步。还有朋友在 VSCode 插件或 ChatGPT 桌面端里点击 Codex 功能时，直接看到 unable to locate the codex cli binary 的报错，折腾半天不知道问题出在哪里。

这篇教程就围绕国内环境下的 Codex 安装、配置、接入国产大模型这条完整链路展开，目标是让一个没怎么碰过命令行的新同学，也能照着一步步跑通。整个过程其实非常快，Codex CLI 本身的安装命令只有一条，熟练的话 1 分钟内就能完成，后面接入国产大模型也只是编辑一个配置文件的问题。

文章会覆盖四块内容：

• Codex 是什么，为什么要通过配置国产模型的方式来使用。
• Node.js 环境准备与 npm 镜像源配置。
• 使用 npm 安装 Codex CLI，并解决 codex 命令找不到的问题。
• 编辑 config.toml，把 Codex 接入 DeepSeek、通义千问等国产大模型。

最后还会整理一批高频报错的排查思路，包括 unable to locate the codex cli binary、local proxy failed、model not supported 等，方便你直接对照处理。

1. Codex 是什么，为什么国内用户需要折腾接入

1.1 Codex 与 Codex CLI

Codex 是 OpenAI 推出的 AI 编程智能体，它不是一个简单的代码补全插件，而是在终端或编辑器里运行的一个“可以干活”的助手。你可以用自然语言描述需求，比如“帮我把这个接口的入参校验补上”，Codex 会读取项目代码，给出修改方案，甚至直接执行命令、运行测试。

Codex CLI 是 Codex 的命令行版本。安装之后，你在项目目录里输入 codex，就能进入一个交互式界面。它会扫描项目文件，结合模型能力理解代码结构，然后输出一系列操作计划。你可以审阅计划，选择允许或拒绝执行，也可以让它继续调整。

这种工作流和传统的 AI 编程工具有明显区别，它更接近“让 AI 直接参与开发流程”，而不是只给一段代码让你自己粘贴。因此在 2025 年之后，Codex 相关的话题讨论度迅速上升，很多人都在尝试用它做一个日常开发的辅助智能体。

1.2 为什么要接入国产大模型

Codex 官方默认使用 OpenAI 自己的模型服务，这意味着你需要注册 OpenAI 账号，可能还要处理付费订阅、API 额度绑定等问题。对这些流程不太熟悉的朋友，很容易在第一步就被劝退。

另一个更实际的问题是，日常开发中我们经常需要把代码片段发送给模型分析，如果你所在的企业对数据合规有要求，官方服务的模型不一定是最合适的选择。接入国产大模型之后，数据请求发送到国内服务商，链路更短，配置也更直接，很多团队会优先选择这种方式。

国产大模型目前在代码理解、代码生成、中文指令理解等场景表现已经相当不错。DeepSeek、通义千问、智谱、Kimi 等平台都提供了兼容 OpenAI 接口风格的 API 地址，这就给 Codex CLI 留下了接入空间。你只需要在配置文件中把模型服务地址换成国产模型的 API 地址，再配上对应的 API Key，Codex 就能在本地跑起来。

1.3 本文适合哪些读者

这篇文章适合以下几类读者：

• 想体验 Codex 但还没有 OpenAI 账号的国内开发者。
• 已经安装了 Codex 但遇到命令行工具识别不了、请求发不出去等问题的同学。
• 希望在公司内网环境或合规要求较高的项目中使用 AI 编程助手的技术人员。
• 对 DeepSeek、通义千问等国产模型感兴趣，想找一个趁手终端工具的开发者。

无论你是前端、后端还是测试、运维，只要能打开终端，愿意跟着输入几条命令，都能完成整个配置流程。

2. 环境准备：先把 Node.js 备好

2.1 检查 Node.js 与 npm

Codex CLI 官方推荐的安装方式是通过 npm 全局安装，所以第一步是确认电脑上已经有 Node.js 和 npm。Node.js 是一个 JavaScript 运行时，npm 是它自带的包管理工具，Codex CLI 就是通过 npm 分发和安装的。

打开终端（Windows 上可以打开 PowerShell 或 CMD，macOS 上打开“终端”应用），输入下面两条命令：

node -v npm -v

正常情况会输出类似下面的版本号：

v22.14.0 10.9.2

如果提示 node: command not found，或者 npm: command not found，说明 Node.js 还没有安装或没有正确加入系统 PATH，需要先安装 Node.js。

这里要提醒一下，Node.js 版本过低可能会导致 npm 安装某些包时出现兼容性问题，建议安装最新的 LTS（长期支持）版本。LTS 版本稳定性更好，适合日常开发环境。

2.2 没有 Node.js 怎么装

如果你还没有安装 Node.js，安装方式很简单：

• Windows：打开 Node.js 官网，下载 Windows 安装包，双击安装，一路 Next 即可。安装时默认会勾选“Add to PATH”，不要取消。
• macOS：如果安装了 Homebrew，可以执行 brew install node；也可以直接去官网下载 macOS 安装包。
• Linux：比较推荐使用 nvm 管理 Node.js 版本，或者用系统包管理器安装。

安装完成后，重新打开一个终端窗口，再次执行 node -v 和 npm -v 验证。这一步不能省，因为很多同学安装完 Node.js 之后没有重启终端，导致命令找不到。

2.3 配置 npm 镜像源（可选）

国内开发者使用 npm 安装依赖时，经常会遇到下载速度慢、超时、甚至直接失败的情况。这是因为 npm 默认源在国外。解决办法是把 npm 源切换到国内镜像。

这里用的是国内常用的 npmmirror 镜像，命令如下：

npm config set registry https://registry.npmmirror.com

设置完成后，可以用下面的命令确认是否生效：

npm config get registry

如果输出的是 https://registry.npmmirror.com，说明镜像源已经配置成功。配置镜像源只是让 npm 下载更快，不影响 Codex 本身的运行逻辑。如果你原本就有其他 npm 私有源，可以根据实际情况决定是否修改。

3. 安装 Codex CLI：一条命令搞定

3.1 使用 npm 全局安装

环境准备好后，安装 Codex CLI 只需要一条 npm 命令：

npm install -g @openai/codex

这里解释一下命令参数：

• -g 表示全局安装，这样安装完成后可以在任意目录下使用 codex 命令。
• @openai/codex 是 Codex CLI 在 npm 上的包名。

执行之后，npm 会下载并安装这个包。安装成功时，终端会输出类似 added xxx packages 的提示。整个过程通常在 1 分钟左右完成，取决于网络状况和机器性能。

如果你之前安装过旧版本，也可以直接用 npm update 更新：

npm update -g @openai/codex

更新时建议顺手执行 npm config get registry 确认镜像源，因为不同源的同步可能有一定延迟，偶尔会遇到版本不是最新的情况。

3.2 验证安装是否成功

安装完成后，输入下面的命令验证：

codex --version

如果输出一个版本号，比如 codex 0.xx.x，说明 Codex CLI 已经安装成功。这时候你可以在任意项目目录下输入 codex 启动交互界面。

如果你在执行 codex --version 时得到 command not found，说明 npm 的全局 bin 目录没有加入系统 PATH，需要按下一节的方式处理。

3.3 解决 codex 命令找不到的问题

这种情况在 Windows 上比较常见。解决办法是先查看 npm 的全局目录：

npm config get prefix

然后根据输出结果，把对应的 bin 目录加入 PATH。

以 Windows 为例，如果 npm config get prefix 输出的是 C:\Users\你的用户名\AppData\Roaming\npm，那么在 PowerShell 中执行：

setx PATH "$env:PATH;C:\Users\你的用户名\AppData\Roaming\npm"

这里把路径替换成你实际输出的目录。执行完成后，重新打开一个终端窗口，让 PATH 生效。注意 setx 只对新打开的终端窗口生效，当前窗口内不会立即生效。

macOS 或 Linux 下，如果 codex 命令找不到，通常是 npm 全局目录不在 PATH 中，可以临时执行：

export PATH="$(npm config get prefix)/bin:$PATH"

确认 command 可用后，再把这行写入 ~/.bashrc 或 ~/.zshrc，让它永久生效。

这一步排查思路同样适用于 VSCode 插件或 ChatGPT 桌面端报错 unable to locate the codex cli binary。插件本质上是在系统 PATH 中寻找 codex 可执行文件，如果命令行工具本身能用，插件仍然找不到，通常是因为图形界面应用启动时没有读取到你终端里的 PATH 配置，重启系统或重启应用往往就能解决。

4. 登录 Codex：官方账号与国产模型两种路线

4.1 使用官方 OpenAI 账号登录

如果你已经有 OpenAI 账号，并且希望直接使用官方模型，那么安装完成后执行：

codex login

命令会尝试打开浏览器，跳转到 OpenAI 的授权页面。你在浏览器中完成登录和授权后，终端里会提示登录成功。

不过，官方登录方式对国内用户存在一定门槛，比如账号注册、付费套餐、网络链路等。如果你只想快速体验，更推荐走国产模型路线，这样整个流程会简单很多。

4.2 准备国产模型 API Key

以 DeepSeek 为例，接入前需要先到 DeepSeek 开放平台注册账号，然后创建一个 API Key。平台通常要求绑定手机号，部分服务需要小额充值才能调用模型接口，具体规则以平台当前页面为准。

DeepSeek 当前有两个常用模型：

• deepseek-chat：通用对话模型，适合日常代码生成、解释、重构。
• deepseek-reasoner：推理模型，适合复杂问题分析，但响应速度相对慢一些。

创建好 API Key 后，把 Key 保存下来，后面配置环境变量时使用。

如果你使用的是通义千问，则需要在阿里云百炼平台开通 DashScope 服务，获取 API Key。模型名如 qwen-plus、qwen-max 等，具体以控制台展示为准。不同平台的申请流程和计费方式不同，建议先阅读官方文档。

4.3 跳过官方登录，直接走自定义模型提供商

很多人以为 Codex 必须要登录 OpenAI 才能使用，其实不一定。Codex CLI 提供了模型提供商（model_providers）配置能力，你可以在配置文件中定义一个自定义提供商，指向任何兼容 OpenAI API 风格的地址，并设置 requires_openai_auth = false，这样就能跳过官方登录。

这种配置方式的本质是：Codex 只负责命令行交互和代码上下文收集，真正理解代码并生成补丁的是你配置的模型服务。因此，只要模型服务能力过关，开发体验并不会打折扣。

5. 接入国产大模型：编辑 config.toml

5.1 配置文件在哪里

Codex CLI 的配置文件路径如下：

• Windows：C:\Users\你的用户名.codex\config.toml
• macOS / Linux：~/.codex/config.toml

如果 ~/.codex 目录不存在，或者里面没有 config.toml，可以手动创建。创建目录和文件的命令：

mkdir -p ~/.codex touch ~/.codex/config.toml

Windows 下可以先创建 .codex 文件夹，再在里面新建 config.toml 文件。

下面给出两份可复制的配置示例。注意，Codex CLI 不同版本对配置字段的支持可能有差异，如果某个字段在你的版本中不生效，请以 codex --help 或官方文档输出为准。

5.2 DeepSeek 接入示例

在 config.toml 中写入如下配置：

# 文件路径：~/.codex/config.toml # 默认使用的模型，格式为：提供商名称/模型名称 model = "deepseek/deepseek-chat" # 默认使用的模型提供商，必须与下方 model_providers 中的 key 对应 model_provider = "deepseek" # 定义自定义模型提供商 deepseek [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat" requires_openai_auth = false

下面逐行解释关键字段：

• model：这是 Codex 启动后默认加载的模型。deepseek/deepseek-chat 表示使用 deepseek 这个提供商下的 deepseek-chat 模型。
• model_provider：指定默认提供商，和下面的 [model_providers.deepseek] 对应。
• base_url：模型服务地址。DeepSeek 提供兼容 OpenAI 格式的接口，所以这里填它的 v1 端点。
• env_key：Codex 会从环境变量中读取这个字段对应的值作为 API Key。
• wire_api：通信协议。chat 表示走 OpenAI Chat Completions 接口格式，DeepSeek 等国产模型普遍支持这种格式。如果服务商支持 OpenAI 新版 Responses 协议，也可以改成 responses。
• requires_openai_auth：设为 false 后，Codex 不会强制要求 OpenAI 账号登录。

配置保存后，需要设置环境变量。macOS / Linux 下执行：

export DEEPSEEK_API_KEY="sk-你的key"

Windows PowerShell 下执行：

$env:DEEPSEEK_API_KEY="sk-你的key"

注意，这样设置的环境变量只在当前终端窗口生效。如果你希望永久生效，可以写入 shell 配置文件（如 ~/.bashrc、~/.zshrc）或 Windows 系统环境变量。

5.3 通义千问接入示例

如果你想使用阿里云通义千问，可以在同一个 config.toml 中追加千问的提供商配置。

# 文件路径：~/.codex/config.toml # 切换默认模型为千问 model = "qwen/qwen-plus" model_provider = "qwen" [model_providers.qwen] name = "Qwen" base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1" env_key = "QWEN_API_KEY" wire_api = "chat" requires_openai_auth = false

同样，设置环境变量：

export QWEN_API_KEY="sk-你的key"

如果你想同时保留 DeepSeek 和通义千问的配置，可以把两个 provider 都写在同一个文件里。示例如下：

model = "deepseek/deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat" requires_openai_auth = false [model_providers.qwen] name = "Qwen" base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1" env_key = "QWEN_API_KEY" wire_api = "chat" requires_openai_auth = false

这样做了之后，你可以随时通过修改 model 和 model_provider 两个字段来切换模型，而不需要改环境变量。

5.4 使用 Codex 验证配置

配置完成后，在任意项目目录下执行：

codex

如果一切正常，Codex 会启动交互式界面。你可以输入一句简单的指令测试，比如：

查看当前目录下有哪些文件，并简单解释这个项目的结构。

Codex 会读取目录内容，调用你配置的模型，然后返回一段分析结果。

部分版本还提供非交互模式，可以直接把任务作为参数传入。例如：

codex exec "写一个 Python 函数，判断一个字符串是否是回文"

如果你使用的版本不支持 exec 子命令，可以运行 codex --help 查看当前版本支持的参数和子命令。

6. 常见问题与排查思路

接入过程中最容易出问题的几个点，基本集中在命令找不到、网络请求失败、模型不兼容这三类。下面整理成对照表，同时详细说明排查步骤。

6.1 unable to locate the codex cli binary

这个报错经常出现在 VSCode 的 Codex 插件或 ChatGPT 桌面端中。完整报错类似：

Unable to locate the codex cli binary. Set codex_cli_path or ensure the executable is in your PATH.

虽然报错文字很长，但核心含义是：图形界面应用在系统环境变量中找不到 codex 可执行文件。

排查顺序如下：

1. 打开终端，执行 codex --version，如果终端能正常输出版本号，说明 CLI 本身已经安装成功。
2. 如果终端提示 command not found，先按前面 3.3 节的方式修复 PATH。
3. 如果终端能用，插件仍报错，需要找到 codex 的完整路径。Windows 执行 where codex，macOS / Linux 执行 which codex。
4. 把路径复制出来，在插件设置或桌面端设置里找到 codex_cli_path 配置项，填入完整路径。
5. 重启插件或应用。

需要注意的是，不要直接把路径写在系统 PATH 里就以为万事大吉。有些桌面应用启动时不会重新加载 PATH，或者启动时的 PATH 并不包含用户级配置，所以手动指定 codex_cli_path 往往是最直接的办法。

6.2 local proxy failed while handling codex endpoint

这类问题属于网络请求链路异常，现象是 Codex 调用模型接口时报类似：

cc switch local proxy failed while handling codex endpoint /responses.

这个报错的常见原因是：当前终端或系统设置了 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 等环境变量，Codex 发起的请求走了这个代理，但代理服务不可用、返回异常或不允许转发。

排查步骤：

1. 执行下面的命令查看代理环境变量是否被设置：

echo $HTTP_PROXY $HTTPS_PROXY $ALL_PROXY

Windows PowerShell 下执行：

echo $env:HTTP_PROXY $env:HTTPS_PROXY $env:ALL_PROXY

2. 如果输出了代理地址，先临时清除：

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

Windows PowerShell 下执行：

Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY

3. 重新运行 codex，再次发起请求，看问题是否消失。
4. 如果确实需要一个代理环境，请确保代理服务地址有效、进程正在运行，并且支持转发 HTTPS 请求。

这里要强调，在日常开发环境中，除非确实需要，否则不建议在终端里长期设置全局代理，因为很多命令行工具并不会自动处理代理异常，反而会导致各种莫名的网络错误。

6.3 model not supported 或模型不存在

如果你在配置中用了模型服务商不支持的模型名，或者 base_url、wire_api 与服务商实际提供的协议不匹配，Codex 会返回模型不支持的相关提示。

解决办法分三步：

1. 到模型服务商官网或控制台确认准确的模型 ID。比如 DeepSeek 当前常用的是 deepseek-chat 和 deepseek-reasoner，不要直接填 deepseek-v3 这类猜测的名字。
2. 检查 config.toml 里的 model 字段，确认格式是 提供商名称/模型名称，并且提供商名称和下面的 [model_providers.xxx] 完全一致。
3. 如果服务商接口兼容的不是 OpenAI Chat Completions 格式，而是其他协议，需要查一下当前 Codex 版本支持哪些 wire_api 值，再做调整。

6.4 其他问题汇总

还有一些问题虽然不是必现，但遇到的人也不少：

• npm 安装超时：切换 npmmirror 源后重试，如果仍失败，可以尝试清空 npm 缓存再安装。
• codex login 打不开浏览器：终端会显示一个登录链接，手动复制链接到浏览器打开即可。
• Windows 下配置了环境变量但 codex 仍提示没有权限：检查 API Key 是否有余额、是否被平台限流，以及系统时间是否准确。部分地区服务商会校验时间戳，系统时间偏差过大可能导致签名验证失败。

7. 最佳实践与工程建议

7.1 API Key 安全管理

这是最重要的一点，不管你使用哪个模型服务商，API Key 都是可以调用付费接口的凭证。不要把 API Key 直接写死在 config.toml 中，而是通过环境变量引用。前文配置示例中使用 env_key 这种写法，就是为了避免 Key 泄露。

同时，不要把你的 config.toml 提交到 Git 仓库，尤其是公司项目或开源项目。建议在 .gitignore 中添加：

.codex/

如果使用 Windows，也要注意不要把 Key 写到系统临时文件或截图公开分享。

7.2 命令执行的权限与审查

Codex 在交互模式下会给出执行计划，并且会请求你的确认。实际使用中，不要盲目同意所有命令，尤其是涉及删除文件、覆盖配置、git push、数据库操作等高风险动作。建议遵循最小权限原则：只允许 Codex 在当前项目目录内执行任务，不要给它全局范围内的操作权限。

如果你在 CI/CD 流水线中使用 Codex 类工具，更要严格限制模型生成的命令，最好先人工评审。

7.3 成本与模型选择

不同国产模型的计费方式差异很大，同一个任务在不同模型上的消耗也可能不同。建议在正式使用前，先看平台给出的价格说明，估算一下每天的调用量。

日常简单任务选择 deepseek-chat 这类通用模型就够用，复杂逻辑推理可以切换到 deepseek-reasoner 或千问系列的大杯模型。你的 config.toml 中可以通过多个 provider 实现切换，方便日常对比效果和成本。

7.4 保持版本更新

Codex CLI 更新频率较高，新版本会修复 bug、增加模型提供商协议支持。建议每隔一段时间执行：

npm update -g @openai/codex

更新后重新运行 codex --version 确认版本变化。如果更新后之前的配置失效，先不要急着降级，排查一下新版本是否调整了配置字段名称。

7.5 数据合规与服务商选择

企业项目中使用 AI 编程助手时，要充分考虑代码数据的去向。把公司内部代码发送给第三方大模型，必须确认公司允许这样做，并且服务商的数据处理条款符合合规要求。如果你的项目对保密性要求很高，可以考虑私有化部署模型服务，然后在 config.toml 中填写内网地址。

8. 总结与学习路线

这篇教程从零开始，完成了以下几步：

• 了解 Codex 是什么，以及为什么可以通过配置国产大模型来使用。
• 准备好 Node.js 与 npm 环境，并配置了国内镜像源。
• 使用 npm 安装 Codex CLI，解决了 codex 命令找不到的问题。
• 编辑 config.toml，把 Codex 接入 DeepSeek、通义千问，并完成命令行验证。
• 整理了安装和接入过程中的高频报错，包括 unable to locate the codex cli binary、local proxy failed、model not supported 等。

接下来如果你想继续深入学习，可以从这几个方向入手：

• 研究 Codex 在 VSCode 插件、ChatGPT 桌面端中的配置方式，打通编辑器内使用链路。
• 练习在真实项目中用 Codex 完成接口开发、重构、单元测试生成等任务。
• 了解不同国产模型的代码能力差异，找到最适合自己团队的组合。
• 如果团队有私有化需求，可以尝试部署本地模型并配置自定义提供商。

Codex 这类 AI 编程智能体的核心价值，是帮开发者在项目上下文里直接完成任务，而不只是回答孤立的问题。安装和配置只是第一步，真正有价值的是日常开发中反复使用、持续调优。

如果你安装过程中卡在某个报错上，可以对照第六节的排查表逐项检查。如果还是解决不了，建议把报错原文和 config.toml 中非敏感部分一起搜索，通常能找到对应版本的解决方案。