企业官网建设流程全解析

Codex 是 OpenAI 推出的 AI 编程代理，它的核心能力不是补全一行代码，而是像一名初级工程师那样，在真实的终端环境里理解任务、修改文件、执行命令、观察结果，然后继续调整。2026 年你再看 Codex 相关资料，看到的已经不只是npm install命令，还有桌面应用、IDE 扩展、自定义模型接入，以及一堆环境报错。这篇教程按一条从零到进阶的路线展开：先讲清楚 Codex 到底是什么，再把安装、登录、第一个任务、模型接入、高频报错和落地技巧逐个走完。适合两类读者：一类是从没用过 AI 编程助手的入门者，另一类是已经装了 Codex 但总在报错、想把它真正用到项目里的开发者。文中的命令以当前常见版本为例，落地前先确认自己环境里的实际版本。

1. 先理解 Codex 是什么：CLI、桌面应用和 IDE 扩展的关系

1.1 一个会执行命令的编程代理，不是普通的代码补全插件

很多初学者会把 Codex 和代码补全工具混为一谈。代码补全工具的核心是“你写一半，它猜后半句”；Codex 的核心是“你给它一个目标，它在项目里自己想办法完成”。

Codex 的工作循环大致是这样的：

1. 读取当前目录下的项目结构、文件内容和说明文档，建立对代码库的理解。
2. 根据你的任务拆解步骤，制定一个执行计划。
3. 直接创建或修改文件，而不是只给出建议代码。
4. 执行终端命令，比如安装依赖、运行测试、检查编译结果。
5. 读取命令输出，判断是否成功，失败就继续修复，直到目标完成。

这里最关键的是第 4 步。Codex 并不是一个“给你建议然后你自己动手”的工具，而是一个“自己动手然后向你汇报”的代理。它会调用终端、读取报错、改代码、再跑一次测试。只有理解这一点，你后面才会明白为什么沙箱权限、审批机制和AGENTS.md这些概念如此重要。

1.2 三种使用形态：codex CLI、桌面应用、IDE 扩展

Codex 最常见的三种使用方式分别是命令行、桌面应用和编辑器的 IDE 扩展。它们的底层引擎是同一个，但入口和依赖关系不同。

为什么要理解这三种形态的关系？因为很多报错并不是 Codex 本身坏了，而是入口工具没找到后端引擎。比如“unable to locate the codex cli binary”这类错误，本质就是桌面应用或 IDE 扩展在启动时找不到命令行工具，而不是模型出错了。后面第 5 章会专门讲这条排查链。

注意：学习阶段建议先只装 CLI，不要同时装桌面应用和 IDE 扩展。入口越少，报错越容易定位。

2. 环境准备：装好 Node 环境，用 npm 安装 Codex CLI

2.1 前置环境清单

Codex CLI 是通过 npm 发布的，所以安装前提是 Node.js 环境。常见版本要求是 Node.js 18 及以上，生产环境建议使用长期支持版本。

安装前先确认已有环境的版本：

node -v npm -v git --version

如果node命令不存在，先去 Node.js 官网安装 LTS 版本。Windows 也可以使用官方安装包或winget install OpenJS.NodeJS.LTS。macOS 和 Linux 上，如果同时维护多个 Node 版本，推荐用 nvm 管理，避免全局目录权限问题。

2.2 安装 Codex CLI 并验证

安装命令只有一条：

npm install -g @openai/codex

安装完成后执行：

codex --version

如果能看到版本号，说明安装成功并且命令已经被系统找到。如果提示codex: command not found，不要急着重装，先执行下面三条命令确认 npm 的全局目录是否在 PATH 中：

which codex npm prefix -g echo $PATH

这一步非常关键。npm 的全局可执行文件目录通常不是系统默认 PATH 的一部分，尤其是用 nvm 安装 Node 时。解决方式是把npm prefix -g输出的目录加进PATH。比如 macOs/Linux 的 nvm 场景通常是：

export PATH="$(npm prefix -g)/bin:$PATH"

Windows 上 npm 全局包装脚本是codex.cmd，一些桌面应用和 IDE 扩展只认无扩展名的可执行文件，这时候需要显式设置CODEX_CLI_PATH指向完整的codex.cmd路径。这类“装完了但找不到命令”的问题，是 Codex 新手最容易踩的第一个坑。

2.3 登录认证：两种方式选一种

Codex 必须认证后才能调用模型。目前常见的有两种方式。

第一种是账号登录：

codex login

命令会打开浏览器，让你授权 OpenAI 账号。登录成功后，凭证会保存在本地，后续命令不需要重复登录。

第二种是 API Key 环境变量：

export OPENAI_API_KEY="你的密钥"

两种方式使用场景不同：

验证认证是否成功，可以跑一个最简单的任务：

codex exec "用一句话解释 HTTP 状态码 404 的含义"

如果返回一段自然语言回答，说明安装、PATH、认证全部正常。如果这里就报错，先回到第 2.2 节检查环境，再检查密钥是否有效。

3. 跑通第一个真实任务：从交互模式到自动改代码

3.1 先使用交互模式理解 Codex 的做事方式

交互模式适合探索和调试。进入一个空目录，执行codex，然后输入任务：

mkdir -p ~/codex-demo && cd ~/codex-demo codex

在交互界面里输入：

在当前目录创建一个 Python 命令行待办应用，支持 add、list、done 三个子命令，数据保存到本地 JSON 文件。

Codex 会先读取目录内容，然后给出执行计划：创建哪些文件、实现哪些函数、如何运行验证。接下来它会修改文件，并在需要执行命令时征求你的批准。

这里要理解 Codex 的“审批机制”。它不会在没有任何限制的情况下随便执行危险命令。常见的安全级别如下：

交互模式下，Codex 会在执行命令前弹出批准请求，你需要确认命令内容后再放行。

注意：第一次使用建议把安全级别控制在 workspace-write 以内，不要一上来就允许完整访问权限。等看清楚 Codex 会执行哪些命令之后，再决定是否扩大权限。

3.2 用 codex exec 做一次性执行，适合脚本和 CI

交互模式适合边聊边改，但如果你只需要让 Codex 完成一个明确任务，可以用codex exec：

codex exec "为当前项目补充一个 README.md，说明安装和运行方式"

这个命令会以非交互方式执行，结束后直接退出。它很适合同一个任务批量执行，或者接进 CI 流程。

常用参数说明如下：

不同版本参数名可能略有差异，使用前先执行codex exec --help确认当前版本的准确写法。

3.3 用项目说明文件约束 Codex 的行为

Codex 在真实项目里经常会出现“代码写得通顺但不符合项目规范”的问题，比如把测试放在错误目录、用了项目里不存在的依赖管理工具、改了不该改的文件。解决这个问题的方式是在项目根目录放一个说明文件。

Codex 会读取项目根目录下的AGENTS.md（部分版本也识别codex.md），把它作为每次任务的上下文。这个文件相当于团队新人入职时拿到的“项目规矩”。

示例：

# 项目约定 - 语言：Python 3.12 - 依赖管理：使用 uv，不要直接使用 pip install - 测试：pytest，测试文件放在 tests/ 目录 - 提交规范：不要修改 uv.lock，除非明确要求 - 异常处理：业务异常统一抛出 BizException

有了这个文件，Codex 就会在修改代码前先读取这些约束，很多“改得太随意”的问题可以在源头上避免。这里有一个明显的坑：AGENTS.md本身会随着项目演进过时，过时规则比没有规则更危险，因为 Codex 会严格遵守它。项目结构变化时，记得同步更新说明文件。

4. 进阶配置：把 Codex 接入 DeepSeek 等 OpenAI 兼容服务

4.1 为什么要换模型服务商

Codex 默认使用 OpenAI 的模型，但在真实工程里，你可能会遇到以下几种需求：

• 团队使用企业内部的 API 网关，希望 Codex 的请求统一走网关，方便密钥管理和审计。
• 希望接入其他提供 OpenAI 兼容接口的模型服务商，比如 DeepSeek，以控制成本或满足具体场景。
• 某些模型服务商只支持/chat/completions接口，而不支持较新的/responses接口，需要适配。

这些场景本质上都是在做一件事：让 Codex 的请求从一个自定义的base_url发出。Codex 的配置机制支持这种扩展，这也是“codex 接入 deepseek”这类操作能够实现的原因。

需要提醒的是，不同服务商的接口兼容程度不同。接入后，部分 OpenAI 专属能力可能不可用，需要先在小任务上验证，再逐步扩大使用范围。

4.2 修改~/.codex/config.toml

Codex 的全局配置文件位于~/.codex/config.toml（Windows 下是%USERPROFILE%\.codex\config.toml）。接入一个 OpenAI 兼容服务，只需要在这个文件里增加一个模型提供商配置。

下面是接入 DeepSeek 的示例：

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

配置项的说明如下：

设置密钥：

export DEEPSEEK_API_KEY="你的密钥"

然后指定模型运行任务：

codex exec --model ds/deepseek-chat "写一个统计日志文件行数的 Python 脚本"

如果配置正确，Codex 会通过https://api.deepseek.com/v1发送请求，并带上DEEPSEEK_API_KEY环境变量读取到的密钥。

4.3 用切换工具管理多个服务商：cc-switch 这类场景

实际项目里，开发者经常需要在多个模型服务商之间切换。社区里出现了一类工具，通过维护多份配置或启动一个本地代理服务来帮助完成切换，常见的场景包括切换 Codex 使用的 OpenAI 和 Claude 配置，或者切换不同模型服务商。

这类工具的大致原理是：工具把多个服务商的地址和密钥管理起来，当你要切换时，它会改写 Codex 的config.toml，或者启动一个本地代理，让 Codex 把请求先发到本地地址，再由代理转发给真正的服务商。

这种“本地代理”是正常开发工具，属于 API 网关的一部分。它带来便利的同时也引入了一个问题：如果本地代理没有启动，或者代理端口被占用，Codex 的请求就会失败。

如果你确实需要用这类工具，要注意：

• 确认代理进程确实在运行，而不是只改了配置。
• 确认 Codex 配置里的base_url指向代理地址，而不是旧地址。
• 密钥优先存放在环境变量或工具自己的密钥管理中，不要写进会被同步到仓库的配置文件。

注意：不要把 API 密钥直接写进config.toml，尤其是团队共享仓库时。密钥泄漏的修复成本远高于配置一个环境变量。

5. 高频报错排查：CLI 找不到、本地代理失败、模型不支持

5.1 unable to locate the codex cli binary

这是桌面应用和 IDE 扩展用户最常见的报错。完整错误一般是“unable to locate the codex cli binary. set codex cli path or ensure the electron app can find it in PATH”这类表述。

现象是：你明明安装了 Codex，命令行里也能用，但桌面应用或 IDE 扩展启动时仍然报错。

原因在于：桌面应用是前端壳，真正干活的是 codex CLI。前端应用启动时会去 PATH 里找codex可执行文件。如果 npm 全局目录不在 PATH 中，或者应用使用无扩展名解析但 Windows 下只有codex.cmd，就会找不到。

排查顺序：

codex --version which codex npm prefix -g echo $PATH

如果codex --version能正常输出，但which codex找不到路径，问题就在 PATH。解决方案有两种：

• 把npm prefix -g对应的bin目录加入 PATH。
• 显式设置环境变量：

export CODEX_CLI_PATH="/path/to/codex"

Windows 下通常设置为：

$env:CODEX_CLI_PATH="C:\path\to\codex.cmd"

设置后再重启桌面应用或 IDE。这个问题的预防措施很简单：安装完 CLI 后先执行codex --version确认命令行可用，再安装图形化入口。

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

这个报错出现在使用配置切换工具、并且工具开了本地代理的场景。报错里提到的/responses是 OpenAI Responses API 的路径。

原因是本地代理进程没有正确启动，或者 Codex 的配置仍然指向代理地址，但代理已经退出或端口被占用。另一种可能是代理只实现了较旧的/chat/completions接口，却收到了/responses请求。

排查步骤：

1. 检查本地代理进程是否存活，比如ps aux | grep switch。
2. 检查 Codex 配置中base_url指向的地址和端口，是否和代理实际监听的端口一致。
3. 用 curl 直接探测代理地址，确认它是否能响应请求。
4. 确认 Codex 请求的是/responses还是/chat/completions。如果代理不支持前者，可以把配置中的wire_api调整为chat。

如果只需要切换模型服务商，建议优先使用“改写配置文件”模式的工具，而不是“本地代理”模式。这样少了一个中间进程，排查链路更短。如果必须使用本地代理，就把它当成一个独立服务来运维：检查进程、端口、日志，而不要只看 Codex 本身。

5.3 the 'model-name' model is not supported when using codex with a custom provider

这类报错里会包含一个具体模型名，比如the 'gpt-5.6-sol' model is not supported when using codex with a custom provider。这里的模型名通常是一个占位示例，实际报错时里面写着你自己配置的模型标识。

原因是：使用自定义模型提供商时，Codex 会校验模型名是否符合约定。常见触发场景包括：

• --model参数里写的模型名拼写错误，比如把deepseek-chat写成deepseek-chat-v2。
• 服务商实际不提供该模型，或模型名已变更。
• model配置里只写了模型名，没有带提供商前缀，导致 Codex 用默认提供商去解析。
• wire_api配置和服务商支持的接口不一致。

排查方式：

# 先用简单命令确认模型名能被命令参数解析 codex exec --model ds/deepseek-chat "回复 OK"

如果确认模型名没问题，再去服务商文档查看准确的模型标识。有些服务商提供模型列表接口，可以用 curl 验证：

curl https://api.deepseek.com/v1/models \ -H "Authorization: Bearer $DEEPSEEK_API_KEY"

修复方式：

• 修改--model参数为提供商前缀/准确模型名。
• 在config.toml中把model字段写全，不要漏掉前缀。
• 更新 Codex 版本，某些版本对自定义提供商的支持更完整。
• 确认wire_api与服务商接口能力一致，必要时改成chat。

5.4 高频报错速查表

排查顺序通常是：先确认 CLI 版本，再确认 PATH，然后确认环境变量，接着检查配置文件，最后验证网络连通性。图形界面报错时，优先从命令行复现一遍同样任务，十次里有八次能立刻把问题定位到环境配置上。

6. 把 Codex 用到极致的落地技巧

6.1 提示词写成“可验收的任务”，而不是模糊愿望

Codex 对模糊需求的处理能力已经不错，但它仍然需要足够明确的验收标准。一条糟糕的提示词可能是：“帮我把这个项目改一下。”一条好的提示词应该是：

在 auth 模块中增加 access token 过期检测： 1. token 过期时返回 HTTP 401 和错误码 TOKEN_EXPIRED。 2. 在 AuthService 中新增 checkTokenExpired 方法。 3. 补充单元测试，覆盖过期和未过期两个分支。 4. 不要修改其他模块的代码。

好的提示词包含四类信息：目标、约束、验收标准、禁止事项。尤其是“不要改动什么”，往往是 Codex 最容易越界的地方。如果你的项目已经写了AGENTS.md，提示词里就可以少重复约束，直接给任务目标。

6.2 沙箱和审批级别要按项目风险选择

执行完任务后，一定要检查git diff。Codex 写代码很快，但它也会引入不合理的依赖、删除看似没用实际关键的配置、把测试改得“看起来通过但什么都没验证”。这不是工具问题，而是任何自动生成代码都需要人工审查。

6.3 生产环境使用清单

如果你的团队准备把 Codex 引入日常工作，建议先在一个小模块试用两周，记录它最容易出错的地方，再决定哪些任务可以完全交给它、哪些必须人工把关。

最后给一个实用的练习建议：把权限控制当成学习 Codex 的第一优先级。先学会在 read-only 模式下让它解释项目、生成方案，再逐步放开到改代码。等到你能熟练通过git diff审查它产生的每一次改动时，Codex 才算真正变成了可靠的生产力工具，而不是一个偶尔能跑通、偶尔把项目改乱的“黑盒”。