企业官网建设流程全解析

我第一次装 Codex 的时候，最迷茫的不是代码怎么写，而是这个工具到底怎么装、怎么登录。Codex 不是那种去官网点一下就能下到安装包的软件，它是一套以命令行为主的 AI 编程助手，安装入口五花八门，登录又分 ChatGPT 账号和 API Key 两条路，装完之后怎么确认自己是“真装好了”而不是“命令能敲了但是没用”，也有一堆细节。这篇文章我把四条安装入口的选择逻辑、登录流程、装完之后的确认步骤，以及接入 DeepSeek 这类第三方模型服务的配置都串一遍，适合刚接触 Codex 的开发者，也适合装到一半卡住、准备搜解决办法的人。

1. 动工之前先认清楚：Codex 到底是个什么形态的工具

1.1 它是终端里的编程助手，不是又一个聊天网页

很多人第一次搜 Codex，脑子里默认它是类似 ChatGPT 网页版的东西，进去聊两句就能生成代码。实际上 Codex 的主流形态是命令行工具，你装完之后在终端里敲一条codex命令，它会进入一个交互式会话窗口。你可以在里面描述任务，比如“帮我看看当前目录下哪个函数最慢”，它会读取项目文件、分析逻辑、给出修改方案，然后等你确认后直接改代码。

这个“命令行优先”的设计一开始不太习惯，但用多了会觉得它比网页聊天更适合干活，因为它天然能接触到本地文件系统，也方便接进 Git 工作流。你给它一个任务，它会自己列计划、逐文件修改、产出 diff，最后让你 review。这个过程里它始终待在你的项目目录里，而不是飘在一个聊天网页中。

1.2 安装之前需要准备的两个前置条件

装 Codex 本身不算复杂，但有两样东西你得先有，不然装到一半会卡住。

第一是运行环境。目前最主流的安装方式走 npm，所以机器上要有一个能用的 Node.js 环境，建议 Node.js 20 以上、npm 9 以上。如果你之前装过 Node.js，直接在终端里执行node -v和npm -v就能看到版本；如果系统提示找不到命令，先去 Node.js 官网下载 LTS 版本装好再说。macOS 用户如果习惯用 Homebrew，也可以用brew install node补齐。

第二是账号或密钥。Codex 的登录方式分两种：一种是 ChatGPT 账号授权，需要账号处于付费订阅状态，免费账号登录之后会被告知没有访问权限；另一种是 OpenAI API Key，按实际使用量计费。这两者在后面第三章会详细展开。绝大多数安装失败或者装完不能用的案例，问题都出在账号这一环，而不是命令没装对。

1.3 四条入口的本质区别：包管理器、桌面壳子、源码构建

所谓的“四条入口”，说白了就是四种拿到可执行文件的方式：用 npm 全局安装、用 Homebrew 安装、装官方桌面版、或者从源码构建。它们跑的核心引擎是同一个，区别在于安装路径、升级方式、以及不同操作系统的适配程度。

这就好比你买同一台相机，可以从官网下单，可以找电商渠道，也可以去线下店自提，拿到手的机器一样，但售后、物流、到手时间都不同。Codex 的四条入口也是如此，选哪条主要看你的使用习惯和系统环境。下面我把每一条的实际操作和适用场景都过一遍。

2. 四条安装入口的选择逻辑与实操对比

2.1 入口一：npm 全局安装，最通用的一条路

npm 方式适合绝大多数开发者，尤其是已经装了 Node.js、平时就靠命令行吃饭的人。安装命令就一行：

npm install -g @openai/codex

执行完之后，npm 会把codex可执行文件放进全局 bin 目录。这时候先敲一下版本号，确认命令真的被识别了：

codex --version

如果系统提示command not found，大概率是 npm 的全局 bin 目录没有加进 PATH。Windows 上常见于 nvm-windows 安装的 Node.js，macOS 上常见于通过 nvm 管理的 Node.js。解决方式是把对应目录加到 PATH，或者重装 Node.js 让安装器帮你配置环境变量。

npm 方式的优势是升级方便，一条命令就能完成：

npm update -g @openai/codex

卸载也很干净：

npm uninstall -g @openai/codex

对于想要长期使用、又不想在电脑上留一堆残留文件的开发者，npm 是最合适的选择。

2.2 入口二：Homebrew 安装，macOS 用户的最优解

macOS 用户如果已经离不开 Homebrew，那用 brew 装 Codex 会省心很多，所有依赖和可执行文件都由 brew 统一管理，升级时也不会像 npm 全局包那样偶尔和系统其他模块产生奇怪的关联。

安装命令如下：

brew tap openai/codex brew install codex

第一条命令是把 OpenAI 的 Homebrew 仓库加进本地源，第二条命令是真正安装。装完同样是先验证版本：

codex --version

顺带说一句，如果你的 brew 版本比较老，或者仓库同步有问题，安装过程中提示找不到 formula，先执行brew update更新 brew 自身，再重试。Homebrew 装的 Codex，卸载走brew uninstall codex，升级走brew upgrade codex，整体风格和 macOS 的包管理习惯完全一致。

2.3 入口三：桌面版安装，适合不想碰命令行的人

如果说前面两种入口都是“给终端用户的”，那桌面版就是“给小白用户”的。Codex 官方提供了桌面应用，安装之后是一个带图形界面的窗口，左侧是会话列表，中间是对话区域，右下角能实时看到 Codex 正在读写哪些文件。这个形态更像一个编辑器插件，或者一个独立的 AI 编程客户端。

桌面版的安装方式和普通软件没有区别，去官方渠道下载对应平台的安装包，macOS 就是.dmg，Windows 就是.exe，双击安装即可。装完之后打开应用，它会引导你完成登录，之后你就可以在图形界面里描述任务，它照样能读取你指定的目录、修改代码。

桌面版的好处是门槛低，不需要理解 PATH、npm、配置文件这些概念。坏处是它不解决“终端里想用 codex 命令”这件事，如果你习惯在各种终端工具里并行工作，最终还是得装 CLI。而且桌面版和 CLI 的配置体系是各自独立的，有时候你在桌面版里选了一个模型，在终端里敲codex使用的还是另一套配置，别把它们混为一谈。

2.4 入口四：源码构建或 Release 安装包，进阶和离线场景

第四条路适合两类人：一类是想深入改 Codex 源码或者抢先用最新提交的开发者，另一类是电脑环境比较特殊，npm 和 brew 都跑不起来的用户。

源码方式先克隆仓库：

git clone https://github.com/openai/codex.git cd codex npm install npm run build

构建完成后，可执行文件会出现在构建目录里。这种方式能让你随时git pull拉最新代码重新构建，但代价是每条更新都得手工完成，不适合普通用户日常使用。

如果只是想要一个现成的二进制文件，而不想通过包管理器装，可以直接去 GitHub Releases 页面下载对应平台压缩包，解压后把可执行文件放进一个已经在 PATH 里的目录，比如/usr/local/bin或者 Windows 下的某个自定义目录。这种方式在离线内网环境、或者 Node.js 环境本身出了问题的机器上很实用。

2.5 四条入口怎么选：一张表说清楚

我的建议是：如果你是个正常的开发者，默认走 npm，macOS 用户且不想记忆 npm 命令的走 brew；如果你只想要一个图形界面，桌面版完全够用；源码构建留在你有明确需求时再碰。四条入口并不冲突，可以同时存在，但注意敲codex命令时到底调用的是哪一个，用which codex（macOS/Linux）或where codex（Windows）就能查出来。

3. 登录：ChatGPT 账号与 API Key 两条路

3.1 方式一：codex login 走 ChatGPT 账号授权

安装完成之后，第一步是登录。在终端里直接敲：

codex login

这时终端会显示一个授权链接和一个一次性代码，同时尝试打开浏览器。你在浏览器里登录 ChatGPT 账号，输入终端给出的代码，进入授权页面，点击确认。成功之后终端会打印登录成功的信息，表示授权流程结束。

需要特别提醒的是，ChatGPT 账号登录这条路要求账号是付费订阅状态。免费账号走到最后一步时，Codex 会提示当前账号没有访问权限。所以如果你只有一个免费 ChatGPT 账号，别在登录上反复折腾，要么升级账号，要么直接走 API Key。

登录成功之后，授权信息会保存在用户目录下的~/.codex/auth.json文件里。这个文件就是你的登录凭证，里面包含 token 和账号相关的元信息。不要把它提交到 Git 仓库，也不要随便发给别人，丢了或者泄露了都得重新处理。

3.2 方式二：OPENAI_API_KEY 跳过交互登录

第二种方式不依赖浏览器授权，而是直接给 Codex 一个 API Key。先在 OpenAI 平台创建一个 API Key，然后在终端里设置环境变量：

export OPENAI_API_KEY="sk-..."

如果你希望每次打开终端都自动生效，就把这行加到 shell 的配置文件里，macOS/Linux 是~/.zshrc或~/.bashrc，Windows 是 PowerShell 的$PROFILE。设置完环境变量之后，再用codex login就不再需要走浏览器流程了，Codex 会直接拿环境变量里的 Key 当作凭证。

这里有个非常重要容易踩的坑：环境变量的优先级高于auth.json。也就是说，如果你之前已经用 ChatGPT 账号登录成功了，但后来又设置了OPENAI_API_KEY，那么 Codex 实际用的是 API Key，而不是你的 ChatGPT 订阅。这种情况下的计费方式、可用模型都会不一样。排查“我明明登录了为什么没有权限”这类问题的时候，先检查环境变量。

3.3 怎么判断登录真的成功了

登录这件事，终端提示“Login successful”只是第一步，真正的成功是以“能否完成一次真实的模型请求”来判断。我一般分三层看：

第一层，看凭证文件是否生成。文件~/.codex/auth.json存在，且不是空文件，说明至少走完了授权流程。

第二层，看 Codex 是否知道你是谁。在终端里进入 Codex 会话，发一句最简单的请求，比如“你好，请回复收到”，如果它能正常回复，说明账号、网络、模型路由都是通的。

第三层，看请求是否真的消耗了对应的额度。ChatGPT 登录方式去 ChatGPT 的用量页面看消耗，API Key 方式去 API 控制台的用量记录里看消耗。这一步很多人忽略，但它是判断“你到底在用哪个账号、哪个计费通道”的最可靠依据。

3.4 登录失败：token exchange failed 这类报错的完整排查链路

热搜词里反复出现一个报错：login server error: token exchange failed: token endpoint returned。这个报错我见过很多次，它出现在登录流程的最后一步。前面的浏览器授权都成功了，但在拿临时授权码去换正式访问令牌的环节失败了。

按照我的排查经验，按下面顺序一步步来：

第一步，检查系统时间。这个最容易被忽略，如果电脑时间和真实时间相差超过几分钟，令牌签名校验就会失败，报错现象和 token exchange failed 完全一致。把系统时间同步到自动，然后重新登录一次。

第二步，清理登录状态。有时候是本地残留的旧凭证和新授权流程冲突。把~/.codex/auth.json备份后删掉，同时删除~/.codex/sessions或者旧会话目录里的缓存文件，再用codex login重新走流程。

第三步，换一个干净的浏览器环境。授权过程中，如果你在浏览器里同时登录了多个 OpenAI 账号，或者浏览器插件拦截了跳转，都可能导致授权码传递不完整。用无痕窗口重新打开授权链接，只保留一个账号登录状态。

第四步，检查账号状态。确认账号是付费订阅，并且没有欠费、没有触发风控。

以上几步走完，这个报错基本能解决。如果还是不行，那就去查看 Codex 自己记录的日志，日志文件通常在~/.codex/log/目录下，按日期命名，里面的错误信息比终端显示的要详细得多。

4. 装完怎么确认：从“能打开”到“确实能用”

4.1 第一层确认：版本、路径和运行环境

很多人装完 Codex，第一步是敲codex --version，看到输出了一个版本号就以为万事大吉。这个判断方向没错，但还不够。版本命令只能证明“系统找到了一个叫 codex 的命令”，不能证明它是你想要的版本、不能证明它来自你希望的安装方式。

我建议同时敲三个命令：

codex --version which codex

macOS/Linux 输出/usr/local/bin/codex或者~/.nvm/versions/node/v20.x.x/bin/codex，Windows 用where codex输出完整路径。看到路径之后，你能立刻判断这个 codex 是 npm 装的、brew 装的、还是桌面版附带的命令行包装器。这一步能避免后面“两个版本打架”的混乱。

4.2 第二层确认：配置目录和登录态

确认版本没问题之后，看一下用户目录下的 Codex 配置目录：

ls -la ~/.codex

正常情况下会出现config.toml、auth.json、sessions、log等文件或目录。config.toml是核心配置文件，auth.json是登录凭证。如果这两个文件都正常存在，说明安装和登录至少走通了。

注意一点：如果config.toml不存在，Codex 也能运行，它会用内置默认配置；但如果auth.json不存在，且环境变量里也没有OPENAI_API_KEY，那 Codex 一定无法发起任何真实请求。所以第二层确认的核心是：要么看到auth.json，要么看到环境变量。

4.3 第三层确认：发一个最小请求跑通全链路

命令能敲、配置文件存在，都还只是纸面确认，最终确认方法是发一个真实请求。在任意一个空目录里，执行：

codex

第一次运行 Codex 通常会询问你是否信任当前目录，选择信任之后进入交互界面。输入一句最简单的指令，比如：

请用一句话回答：你现在使用的是哪个模型？

如果它能直接回答出来，说明安装、登录、网络、模型路由、当前配置全部连通了。如果它卡在加载模型列表，或者一直转圈没有输出，再回到上一章排查登录问题。

这一步建议在空目录里做，不要一上来就在真实项目里测试，避免它未经你确认就改动文件。Codex 本身会等你在终端的确认，但新手阶段还是尽量把风险控制在最小范围内。

4.4 第四层确认：在一个真实仓库里做一次小改动

最后一层确认是我个人强烈建议的，因为它模拟了真正的使用场景。找一个你不太在意的测试目录，执行：

git init echo "hello codex" > README.md codex

然后在会话里向 Codex 发一个具体任务，比如“请在 README.md 末尾加一行说明，内容是 This is a test。”它会先描述计划，再修改文件，最后展示 diff。你确认之后，文件就真的变了。

跑完这一轮，可以接着试它读取多个文件、执行终端命令的能力。这才是 Codex 真正区别于聊天工具的价值所在。如果到这里都通了，说明你的安装和登录已经完全没有问题了。

5. 接入 DeepSeek 等第三方模型服务的配置方法

5.1 为什么有人要把 Codex 接到 DeepSeek

Codex 默认只对接 OpenAI 自家的模型，但它的界面和本地工作流——读取项目、生成计划、自动改文件、产出 diff——其实是可以复用的。这正是很多开发者把 Codex 配置到 DeepSeek 等第三方模型服务上的原因：用 Codex 的终端工作流，配上更符合自己成本预算或者访问条件的模型端点。

这里需要明确一点：这种配置不改动 Codex 本身的代码，只是告诉它“我的模型服务地址变了、密钥变了、走 chat 还是 responses 协议变了”。Codex 的配置体系天生支持自定义模型服务商，所以这种方式是官方允许的用法，只是默认配置不会替你写这些内容。

5.2 修改 ~/.codex/config.toml 的完整示例

以接入 DeepSeek 为例。先确保你有一个 DeepSeek 平台的 API Key，然后在~/.codex/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，具体名字以你申请到的模型为准。
• model_provider必须和下面[model_providers.deepseek]里的名字对应，Codex 根据这个名字找到自定义配置。
• base_url是模型服务的 API 接口地址。DeepSeek 提供了兼容 OpenAI 接口的地址，末尾带/v1是为了拼接出完整的请求路径。
• env_key告诉 Codex 从哪个环境变量读取密钥。设置方式为：

export DEEPSEEK_API_KEY="你的 key"

同样记得写进 shell 配置文件长期生效。

• wire_api指定协议格式。Codex 原生使用responses协议，但很多第三方服务兼容的是chat协议，所以这里填chat。如果你的服务商明确支持responses协议，再改回responses。

配置完成后，重新打开codex会话，发一句话测试。如果返回 401，多半是DEEPSEEK_API_KEY没设置对；如果返回 404，多半是base_url拼错了，比如少了/v1。用第三方服务时，Codex 的“计划、改文件、执行命令”能力不受影响，模型换了个供应商，但工具本身没有变。

5.3 用 cc switch 管理多套配置，以及本地转发失败怎么排查

很多开发者不止接一个模型服务，今天用 ChatGPT 登录，明天切成 DeepSeek，后天又切到别的兼容端点。手动改config.toml来回切换很麻烦，社区里因此出现了 cc switch 这类配置切换工具。它的原理不算神秘：在你和模型服务之间加一层本地转发服务，当你在工具里选定某个配置时，它改写 Codex 实际请求的地址，把请求指向你选中的端点。

这类工具的好处是切换方便，坏处是引入了额外一层，一旦本地转发服务没起来，Codex 就会报错。热搜词里那个经典问题“cc switch 本地转发失败，Codex 请求 /responses 时报错”，就是这个场景。排查思路我按顺序排一下：

第一步，确认 cc switch 的后台服务是否真的在运行。这类工具通常有系统托盘图标或者命令行状态命令，先看状态是不是 running。服务没起，请求自然到不了目标端点。

第二步，检查 Codex 当前请求的地址。打开~/.codex/config.toml，看model_provider和base_url是否被改成了指向 cc switch 的本地地址。如果是，但你并不想经过这层转发，直接改回真实服务商的地址，问题瞬间消失。

第三步，检查端口。cc switch 的本地服务默认监听某个端口，如果端口被其他程序占用，或者防火墙拦截了本地回环请求，也会表现成 Codex 请求失败。

第四步，绕过链路验证。别急着排查 cc switch 的细节，直接把config.toml改成直连 DeepSeek 或 OpenAI 的原始地址，看 Codex 是否恢复正常。这一步能快速区分问题出在 cc switch 上，还是出在模型服务本身。

说白了，cc switch 只是帮你管理配置的工具，不是 Codex 必需的组件。遇到转发失败，优先考虑先去配置层面绕开它，验证核心链路是通的，再回来处理工具自身的问题，这样不会在错误的层面上浪费太多时间。

6. 我用下来的一些实际心得和踩坑记录

6.1 先在临时目录里跑通最小闭环

我见过太多人装完 Codex 直接进公司项目，让它“重构一下登录模块”，然后被它的一堆建议和 diff 弄得手足无措。个人建议是，前半个小时就在一个空目录里玩，让它创建文件、改文件、删除文件，确认它的操作模式你能接受，再放进真实项目。这不是不信任它，而是人要先熟悉一个工具的脾气，再让它碰重要东西。

6.2 环境变量和登录态别混用

前面反复提到过，OPENAI_API_KEY和auth.json同时存在时，环境变量优先。我实际遇到过一个情况：同事说他明明用了 ChatGPT 订阅，为什么终端里提示没有权限。我一看，他 shell 配置文件里躺着一个过期的OPENAI_API_KEY，Codex 优先用这个 Key 去请求，Key 失效了自然报错。他自己完全忘了什么时候设置过这个变量。遇到这类问题，先执行env | grep OPENAI（Windows 用Get-ChildItem Env:OPENAI*）看看环境变量里到底有什么。

6.3 多个安装入口同时存在时，先查 which codex

npm 装一个、brew 装一个、桌面版又自带一个，这在同一台机器上完全可能出现。你敲codex --version看到的可能不是你以为的那个版本。我在 mac 上吃过一次亏：npm 装的 Codex 升级了，但系统 PATH 里排在更前面的却是 brew 目录下的老版本，导致我改了config.toml里的新字段，老版本却不认识。统一到一个安装入口，能少踩很多坑。

6.4 版本更新频繁，升级后要复查配置

Codex 的版本迭代很快，config.toml的字段偶尔会变。升级到新版本之后，如果发现配置不生效，先备份旧的config.toml，再让 Codex 重新生成默认配置，对比一下字段差异。新版工具对旧字段通常会给出警告，别无视那些警告，直接跑生产项目。

6.5 给新手的最终建议清单

• 安装默认走 npm，装完先敲codex --version和which codex。
• 登录优先尝试 ChatGPT 账号授权，确认账号是付费订阅。
• 不想开浏览器的，用OPENAI_API_KEY，确认环境变量长期生效。
• 登录报错先查系统时间和本地缓存，再折腾网络。
• 第一次使用全程在临时目录里进行，跑通“读文件、改文件、执行命令”全流程。
• 需要接 DeepSeek 等第三方模型时，改好config.toml后用一个简单请求验证。
• 用了 cc switch 这类切换工具，出问题先绕过它直连排除核心链路，再回头修转发层。

最后再分享一个小习惯：我每次在新电脑上装完 Codex，都会先跑一遍“版本确认、登录态确认、最小请求、临时仓库小改动”这四步，整个过程五分钟不到，但能确保后面所有项目都跑在一个非常扎实的基础上。Codex 这个工具本身不复杂，复杂的是安装形式多、登录方式多、配置选项多，把这些前置问题一次理清，后面就顺畅了。