企业官网建设流程全解析

Codex 出来之后，身边不少同事都在折腾这个终端编程代理。简单说，它就是 OpenAI 开源的一个 coding agent，你可以在命令行里用自然语言交代任务——"把这个模块的测试补一下""帮我查一下这个报错为什么出现，顺手修掉"——它会自己读代码、改代码、跑命令、出 diff，比 IDE 里那种只会补全的 AI 要主动得多。但国内开发者很快就撞上一个现实问题：Codex 默认对接的是 OpenAI 官方接口，账号和支付方式对很多人来说都是门槛。于是大家普遍的做法，是把它指向国内那些提供 OpenAI 兼容接口的 API 服务商，比如 DeepSeek、智谱这类，既能直连访问，又可以用国内常见的支付方式开通。这篇文章就是我在 Windows 上从零到一配通这件事的完整记录，包括环境准备、Codex 安装、config.toml 编写、跑通第一个任务，以及我踩过的各种报错和排查方法。适合所有想在 Windows 上用 Codex 干活的开发者，不管你是第一次装还是已经配到一半卡住，都能在里面找到对应思路。

1. 先别急着装，三分钟理清 Codex 到底在配什么

1.1 市面上其实有三个"Codex"

很多人一搜就懵，因为"Codex"这个名字同时指了好几样东西。第一是 ChatGPT 桌面版和网页版里的 Codex，那是 OpenAI 官方托管的云端编程 agent，你登录账号就能用，但它不开放任何自定义 API 配置，你也改不了它背后用的模型。第二是我们这篇文章的主角 Codex CLI，这是一个开源本地工具，通过 npm 安装后跑在终端里，它的特点就是可以自定义模型后端，只要对方提供 OpenAI 兼容接口，就能把请求转过去。第三是 OpenAI 模型接口层面上的 Codex API 命名，一般开发者日常接触不到。

所以，当你搜到"codex 接入 deepseek""codex 使用教程""codex 官网下载"这些关键词的时候，要找的基本都是 Codex CLI。后面我所有的配置、报错，也都是围绕 Codex CLI 讲的。

1.2 所谓"接入国内 API"，本质是给 Codex 换后端

Codex 不是一个和 OpenAI 绑死的客户端。它的底层逻辑非常简单：启动时读一个配置文件，拿到服务商地址、模型名、API Key，然后按照 OpenAI 兼容协议发请求。你只要找到一个实现了/chat/completions接口的国内服务商，把它的地址填进去，Codex 就"以为"自己在和 OpenAI 说话，实际流量全进了国内服务商。

这里有个很重要的概念：接口协议。OpenAI 自己的官方接口现在更推荐responses协议，而国内绝大多数服务商实现的是更传统、也更通用的chat/completions协议。Codex 通过配置里的wire_api字段来决定用哪套协议说话。这个理解到位了，后面很多报错你一眼就能看出来是怎么回事。

1.3 整条配置链长什么样

Codex CLI（Windows 终端）→C:\Users\<用户名>\.codex\config.toml（告诉它连谁、用什么模型、Key 从哪个环境变量读）→ 国内服务商 API（DeepSeek / 智谱 / 其他兼容服务商）。

这三个环节缺一不可：环境变量里要有 Key，config.toml 格式要对，模型名要和服务商文档一致。后面你遇到的所有报错，几乎都逃不出这三点。

2. 环境准备：先把 Git 和 Node.js 装明白

2.1 Git：Codex 干活的基本盘

Codex 在工作区里干活时，会大量依赖 Git 来做文件变更追踪，比如生成 diff、应用 patch、克隆仓库、甚至帮你产生 commit message。你可以不理解为啥一个 AI 工具要装 Git，但你只要知道没有 Git，Codex 很容易在半路报一些奇奇怪怪的错误。

安装很简单，去 git-scm.com 下载 Windows 版，一路默认安装就行。需要注意两点：一是安装时尽量保持英文路径，别往中文目录里塞；二是 Git for Windows 默认会带上 Git Credential Manager，这个组件一定别去掉，后面访问私有仓库能不能免密登录就靠它。

装完验证一下：

git --version

能输出版本号就说明没问题。如果提示找不到命令，大概率是安装时 PATH 没加进去，重开一个终端再试，还不行就重新安装，在安装向导里把"把 Git 加入 PATH"的选项勾上。

2.2 Node.js：装 LTS 就好，别追最新版

Codex CLI 是通过 npm 分发的，所以本机必须有 Node.js。官方要求 Node.js 版本在 20.5 以上，我的建议是直接装 22 LTS，稳一点。下载地址是 nodejs.org，选 LTS 版本，Windows 安装包双击装完会自动配好 PATH。

国内 npm 下载经常慢，装完 Node 顺手把 npm 镜像源换成国内源，后面装 Codex 会快很多：

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

验证一下：

node -v npm -v

两个都能输出版本号就成。这里有个容易踩的坑：如果电脑上装了多个 Node 版本，或者用过 nvm-windows，PATH 里可能同时存在多个 node 路径，导致版本混乱。建议只保留一个版本，尤其是别在一个终端里来回切换，Codex 依赖的 npm 全局包很容易因此找不到。

2.3 装完先验证，别着急跳过

很多人的 Codex 装到一半出问题，根子都在环境没验证好。我建议在装 Codex 之前，先执行这两个命令：

where git where node

Terminal 会返回这两个命令的实际路径。如果输出的路径不对，或者不在你预期的安装目录，先解决 PATH 问题再进行下一步，否则后面排错会非常痛苦。

另外提醒一句：装完 Node 或 Git 后，之前已经打开的终端窗口是不会自动刷新 PATH 的，必须新开一个窗口再验证。这一点 Windows 用户最容易忽略。

3. 安装 Codex CLI：一行命令的事，但坑也不少

3.1 用 npm 全局安装，最通用

环境准备就绪后，安装 Codex 其实就一条命令：

npm install -g @openai/codex

装完验证：

codex --version

能输出版本号就说明装好了。如果你之前搜到过"codex 官网下载"或者"codex windows 桌面版"，那是官方提供的安装器，也可以装，但我个人更推荐 npm 方式，因为后面升级只需要一条npm update -g @openai/codex，比重新下载安装包省事。

3.2 安装卡住、下载慢、报错怎么办

如果你在安装的时候卡住半天不动，或者报各种网络错误，十有八九是 npm 默认源的问题。前面我们已经把 registry 换成了 npmmirror，如果还是慢，可以再检查一下是不是当时换源没生效：

npm config get registry

输出了https://registry.npmmirror.com就没问题。另外，Windows Defender 或者其他杀毒软件有时会把新装的命令行工具误报，导致安装"看起来完成了但实际文件被删了"。如果你遇到"codex windows 安装未完成"这类情况，先把安装目录加入杀毒白名单，再重新安装一次。还有一种情况是之前安装中断留下了残留，此时先执行：

npm uninstall -g @openai/codex

清理干净后再重装。

3.3 安装成功却提示"codex 不是内部或外部命令"

这是 PATH 的问题。npm 全局安装的目录没有加入系统 PATH，导致终端找不到 codex。可以先看看全局目录在哪：

npm prefix -g

比如输出是C:\Users\你的用户名\AppData\Roaming\npm，那就把这个目录加到系统 PATH 里，然后新开终端再试。顺便说一句，升级 Codex 很简单：

npm update -g @openai/codex

Codex 更新频率挺高的，功能和行为都会变，建议隔一段时间升一次级，升级后重新跑个简单任务验证配置仍然有效。

4. 核心环节：写 config.toml，把 Codex 指向国内 API

4.1 配置文件到底放在哪

Codex 的配置文件位置是C:\Users\<你的用户名>\.codex\config.toml。注意是点开头的一个.codex文件夹，不是别的名字。第一次运行 codex 时一般会自动创建这个目录，如果没创建，手动建一个同名目录和一个空的 config.toml 文件也行。

在 PowerShell 里可以用这个命令确认路径存在：

Test-Path ~\.codex\config.toml

返回 True 就是配置文件已经在，返回 False 就自己新建。

4.2 Codex 接入 DeepSeek：一个直接抄的模板

下面这段是把 Codex 指向 DeepSeek 的完整配置，新建或覆盖写入 config.toml 即可：

model = "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"

我逐个字段解释一下，因为后面所有服务商都是同一个套路：

• model：顶层要用的模型名，必须和服务商平台上的名字一致。DeepSeek 目前代表性的模型名是deepseek-chat，推理模型是deepseek-reasoner，具体以 platform.deepseek.com 控制台看到的为准。
• model_provider：指定下面配的哪个服务商块生效。
• [model_providers.deepseek]：定义一个名为 deepseek 的服务商块，方括号里这个名字你可以随便起，只要和顶层匹配即可。
• name：展示名，没有实际功能。
• base_url：服务商的 OpenAI 兼容接口根地址。注意，这里只写到 API 根路径，比如https://api.deepseek.com/v1，不要再往上拼/chat/completions，否则 Codex 会拼出双份路径导致 404。
• env_key：告诉 Codex 去哪个环境变量里读 API Key，这里是DEEPSEEK_API_KEY。
• wire_api：接口协议类型，填chat表示走/chat/completions。这是接入国内服务商最关键的一个字段，漏掉它 Codex 可能默认走 OpenAI 的responses协议，而国内服务商大多不支持，直接报错。

4.3 多服务商并存：智谱 GLM 和硅基流动的写法

DeepSeek 之外，智谱GLM 和硅基流动也是国内开发者常用的选择。它们可以一起写在同一个 config.toml 里，通过改顶层的model和model_provider来切换。

智谱的配置：

model = "glm-4.6" model_provider = "zhipu" [model_providers.zhipu] name = "Zhipu GLM" base_url = "https://open.bigmodel.cn/api/paas/v4" env_key = "ZHIPU_API_KEY" wire_api = "chat"

智谱的国内站是 open.bigmodel.cn，模型名以控制台展示为准，不同时期的版本号会变，比如 glm-4.5、glm-4.6 这种，配置前先去官网核对一次。

硅基流动的配置：

model = "deepseek-ai/DeepSeek-V3" model_provider = "siliconflow" [model_providers.siliconflow] name = "SiliconFlow" base_url = "https://api.siliconflow.cn/v1" env_key = "SILICONFLOW_API_KEY" wire_api = "chat"

硅基流动是个聚合平台，上面托管了很多开源模型，好处是一个平台能试多种模型。但要注意，Codex 调用服务商会用到工具调用（function calling），如果选的模型不支持这个能力，Codex 会表现得"听不太懂话"，所以优先选官方标注支持工具调用的模型。

4.4 API Key 的正确保存方式：环境变量，别写进配置文件

每个服务商都需要注册账号、创建 API Key。以 DeepSeek 为例，去 platform.deepseek.com 注册后，在控制台创建一个 API Key，复制出来。其他服务商流程类似。

拿到 Key 之后，不要直接写进 config.toml。正确做法是存成环境变量。在 Windows 上，用setx命令设置用户级环境变量：

setx DEEPSEEK_API_KEY "sk-你的key"

注意，setx只对之后新开的终端窗口生效。如果当前终端想立即生效，就先临时设置：

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

更稳妥的图形化方式是：Windows 设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 用户变量 → 新建，变量名填DEEPSEEK_API_KEY，变量值填 Key。

为什么不建议把 Key 写进 config.toml？因为配置文件很容易被同步到网盘、打进 dotfiles 仓库，稍不注意就把 Key 泄露了。环境变量的好处是 Key 独立于配置，换 Key 时也不用改文件。

4.5 配置完怎么验证：先测 API，再测 Codex

配置是否生效，先别急着开 Codex，先用 PowerShell 直接调一次服务商接口，这样可以快速隔离问题。

$env:DEEPSEEK_API_KEY = "sk-你的key" $headers = @{ Authorization = "Bearer $env:DEEPSEEK_API_KEY" } $body = @{ model = "deepseek-chat" messages = @(@{ role = "user"; content = "说你好" }) } | ConvertTo-Json -Depth 5 $resp = Invoke-RestMethod -Uri "https://api.deepseek.com/v1/chat/completions" -Method Post -Headers $headers -ContentType "application/json; charset=utf-8" -Body ([System.Text.Encoding]::UTF8.GetBytes($body)) $resp.choices[0].message.content

如果这段命令能返回一段文字，说明网络、Key、模型名都没问题，剩下的问题只可能出在 Codex 配置层。如果这步就报错，那就先根据报错解决服务商侧的问题，比如 Key 无效、模型名写错、余额不足等。

API 测试通过后，在任意目录执行：

codex "用一句话解释什么是递归"

能正常回复，说明整个链路已经通了。

5. 跑通第一个任务：交互模式、exec 模式和权限策略

5.1 交互模式：codex 直接开聊

进入一个测试项目目录，直接运行：

codex

会进入交互式对话界面。你可以像跟人聊天一样提任务，比如"请给这个项目写一个 README"，Codex 会先读取目录结构，再给出计划，然后动手改文件。每一步改动它会征求你的确认，即使是删一个多余文件也会先问。退出交互模式输入/exit或者按 Ctrl+C。

第一次进入时，如果它弹出登录界面、要求你登录 ChatGPT 账号，先别急。用自定义服务商时其实不需要登录 OpenAI，出现登录提示多半是环境变量没读到，或者 config.toml 没生效。检查一下 4.5 的验证步骤，把配置理通再跑。

5.2 一次性任务与全自动模式：codex exec

不想进交互界面，可以直接用一次性执行：

codex exec "用 Python 写一个脚本，统计当前目录下所有 .py 文件的行数，并运行它看看结果"

这是相对新版本的用法，如果你用的版本不支持codex exec，就先用codex --help看看命令说明。还有全自动模式，可以让 Codex 不经过确认直接执行命令、修改文件：

codex exec --full-auto "把当前目录下所有 TODO 注释整理到 TODO.md"

全自动模式风险较高，我建议第一次体验时在一个临时副本目录里跑，别一上来就在正式仓库里开全自动。不同版本参数可能略有差异，执行前先跑codex exec --help确认。

5.3 approval_policy 和 sandbox_mode：Windows 上要留个心眼

Codex 的行为可以在 config.toml 里通过两个顶层字段控制：

approval_policy = "suggest" sandbox_mode = "workspace-write"

approval_policy控制审批策略：on-request是每次操作都询问，suggest是给建议但仍会等待你确认，full-auto是自动批准。我日常用suggest，既不会太啰嗦，又留了确认的机会。sandbox_mode控制沙箱：workspace-write允许修改当前工作区文件，read-only只读，danger-full-access是彻底放开限制。

这里有个 Windows 用户要特别注意的现实：Codex 的沙箱在 Windows 上的隔离能力是不完整的，官方文档也明确说过这一点。所以别以为开了沙箱就万事大吉，重要项目操作前最好先备份，或者在一个单独的目录里让 Codex 干活。我自己是把 Codex 的默认工作区放在一个专用的临时目录，验证完再手动迁移代码。

6. 常见报错与排查：我踩过的坑都在这里

6.1 400 模型名错误：API 其实已经把答案告诉你了

遇到下面这类报错，不要慌，报错本身就是在帮你：

API error: 400 the supported api model names are ...

意思是：你填的模型名不在这个服务商的白名单里。注意看报错后面列出的模型名列表，照着填就行。有些聚合平台会把模型名改得和官方不一致，比如把 DeepSeek 的模型写成deepseek-flash、deepseek-v4这种风格，和官方文档对不上，遇到时以服务商 API 返回的supported api model names为准，不用怀疑自己。顺便说一句，DeepSeek 官方平台的常用模型名是deepseek-chat和deepseek-reasoner，模型名是区分大小写的，别写错。

6.2 401/403 认证失败：八成是环境变量没生效

这类报错典型表现是：

Authentication failed

首先确认环境变量有没有真的设置成功：

echo $env:DEEPSEEK_API_KEY

如果输出为空，说明环境变量没设置，或者是在setx之前打开的终端里运行的。setx只对之后新开的终端生效，所以我每次配置完都会强制自己新开一个终端再测。还有一种情况是复制 Key 时多复制了看不见的空格，粘贴时注意别带多余字符。如果是多服务商并存，还要检查 config.toml 里的env_key是不是对上了你设置环境变量时用的名字，比如智谱写了ZHIPU_API_KEY，环境变量却设成了ZHIPU_KEY，那肯定 401。

6.3 "codex endpoint /responses" 相关报错：接口协议和网络层一起查

如果你看到类似这样的报错片段：

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

这个报错有两个常见来源。第一个是wire_api没配或者配错，导致 Codex 用 OpenAI 专属的responses协议去请求国内服务商，而服务商只提供/chat/completions。排查方法很简单，确认 config.toml 每个服务商块里都有wire_api = "chat"。

第二个来源就麻烦一点。如果你的 Windows 上开着系统级流量转发或加速类的软件，它可能会把 Codex 发往国内 API 的 HTTPS 请求也拦截或改写一遍，导致 Codex 在处理 endpoint 时出现cc switch ... failed这类报错。遇到这种情况，先把这类软件退出，恢复系统默认网络设置再试。配置国内可直连的服务商，本来就是希望请求走直连，不需要任何多余的网络中转层。如果一定要保留这类软件，那就把服务商 API 域名加入它的直连规则。

6.4 上下文超长报错：省着点喂给模型

还有一种常见报错：

This model's maximum context length is 1048576 tokens. However, you requested ...

意思是输入的内容超过了模型上下文上限。Codex 作为 agent，会把项目里的相关文件内容作为上下文发给模型。如果你的目录里有超大日志文件、构建产物、node_modules 这类东西，很容易一下子把上下文撑爆。解决办法是给 Codex 一个干净的工作区，配合.gitignore把大文件排除掉；另外对话太长时，直接新开一个会话，不要在一个上下文里无限追加任务。上下文超长不只是报错问题，还直接关系到费用消耗，因为发给模型的内容是按 token 计费的。

6.5 Git 认证和 GitLab 相关报错：这锅不是 Codex 的

有人遇到：

login failed. check api token or gitlab version. log in via git if the versi...

这类报错大多发生在 Codex 执行 git 操作时，比如克隆私有仓库、拉取代码。它的本质是本机 Git 的凭据没配好，Codex 只是代替你执行了 git 命令，认证失败自然就抛出来了。解决办法是先把 Git 凭据问题解决：确保 Git for Windows 安装了 Git Credential Manager，然后自己先在终端里手动 clone 一次仓库，让它记住凭据。对于 GitLab，也可以在 GitLab 后台生成 Personal Access Token，把它配置到 Git 凭据里。Git 层面能正常拉取推送了，Codex 层的报错自然消失。

6.6 Windows 特有坑：中文路径、执行策略、编码

Windows 上还有几个很琐碎但很烦人的坑。第一是中文用户名或中文路径，某些工具链在处理非 ASCII 路径时会异常，建议项目目录用纯英文路径。第二是 PowerShell 执行策略，运行某些安装脚本时会提示"在此系统上禁止运行脚本"，可以执行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

然后选 Y。第三是输出乱码，Codex 输出的中文在旧版终端里可能显示成乱码，切一下 UTF-8 编码：

chcp 65001

另外，如果你之前遇到过 "codex windows 安装未完成"，记得把杀毒软件加白名单，这属于 Defender 误删文件导致的半成品安装，重新装之前先彻底卸载。

6.7 Docker API 报错：跟服务商无关

还有一种报错和 API 服务商一点关系都没有：

failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen...

如果你在 Codex 里配置了 Docker 相关的 MCP 工具，启动时它会尝试连接 Docker Desktop 的 Windows 管道，连不上就是这个报错。解决办法是先启动 Docker Desktop，等它右下角状态变绿，再跑 Codex。如果你不做容器相关开发，暂时不需要这项能力，直接把这个 MCP 配置注释掉就行，不影响正常使用。

6.8 排错顺序速查表

出了报错别乱试，按这个顺序排查效率最高：

7. 完整配置模板与我的几个实际教训

7.1 一个三服务商并存、可直接抄的模板

最后把我目前在用的完整配置贴出来，你可以直接覆盖到 config.toml，按需调整模型和 Key：

model = "deepseek-chat" model_provider = "deepseek" approval_policy = "suggest" sandbox_mode = "workspace-write" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat" [model_providers.zhipu] name = "Zhipu GLM" base_url = "https://open.bigmodel.cn/api/paas/v4" env_key = "ZHIPU_API_KEY" wire_api = "chat" [model_providers.siliconflow] name = "SiliconFlow" base_url = "https://api.siliconflow.cn/v1" env_key = "SILICONFLOW_API_KEY" wire_api = "chat"

想切换服务商，只需要改顶层的model和model_provider，比如切到智谱就把顶层改成model = "glm-4.6"、model_provider = "zhipu"，改完保存后新开终端生效。

7.2 长期使用要留意的几件事

费用是第一个要留意的，Codex 作为 agent 消耗 token 的速度比普通对话快得多，它每读一个文件、每运行一次命令都要消耗额度。我建议在服务商后台开启余额提醒，或者定期看一眼消费记录，别让它不知不觉烧掉太多。第二个是数据隐私，所有发出去的问题和代码都会经过服务商，敏感项目不要直接丢给 Codex，或者提前做脱敏处理。第三个是版本更新，Codex 的更新非常频繁，每次升级后行为可能变化，建议升级后先跑一个简单任务验证一下原配置还正常。

7.3 我的两个真实翻车记录

第一个翻车是 base_url 写错。我一开始想当然，把 base_url 写成了https://api.deepseek.com/v1/chat/completions，结果 Codex 拼接请求时变成了双份路径，直接 400。折腾了好一会儿才意识到 base_url 只要写到 API 根路径，剩下的路径 Codex 会自己拼。

第二个翻车更蠢，用setx设置好环境变量后，没开新终端就急着跑 codex，连续报 401。我一度以为是 Key 出了问题，反复重新创建了好几次 Key，最后才发现是终端里根本读不到刚设的环境变量。后来我学乖了，每次用setx之后强制新开一个终端，或者干脆先用$env:DEEPSEEK_API_KEY = "sk-xxx"在当前终端里临时设一遍，先跑通再说。

最后分享一个小技巧：给 Codex 安排一个专门的临时工作目录，所有冒险操作都让它在那个目录里进行。这个做法帮我避免了很多"一觉醒来仓库被改得乱七八糟"的惨剧。Codex 是个很好用的工具，但再好的工具也得用对方式，熟悉了这套配置流程之后，你在 Windows 上应该能比较顺手地把它用起来了。