企业官网建设流程全解析

Codex 是 OpenAI 推出的编程智能体，它的运行方式和使用习惯都和常见的 IDE 插件不同：你可以在终端里直接描述一个任务，由它自己决定先读哪个文件、执行哪条命令、看到报错后再改哪些代码。很多开发者第一次接触时，会在安装阶段就卡住，比如 Node 版本不对、npm 全局命令找不到、登录成功但请求一直失败，或者想切换到 DeepSeek 等兼容服务时不知道改哪里。下面按“安装 -> 认证 -> 接模型 -> 排错”的顺序，记录 Codex CLI 和桌面版的完整上手过程，同时会说明 CC Switch 这类多服务切换工具的使用方法，以及 /responses 报错的排查思路。会用到 npm、Git、Node.js 这些常见工具，也会说明如何把 Codex 接到 DeepSeek 等 OpenAI 兼容服务。文中的命令和配置示例都用于说明常规流程，落地时要以你自己电脑上的 Node 版本、Codex 版本和模型服务商文档为准。

1. 先分清 Codex CLI、桌面版和官网入口，再决定怎么装

1.1 Codex 解决的是什么问题

传统 AI 编程辅助工具一般以插件形式嵌入编辑器，你选中一段代码，它给你补全或解释。Codex 的形态不同，它更像一个能独立工作的命令行助手：你给它一个目标，它会自己去翻代码、改文件、执行命令，然后根据执行结果继续修正。这种工作方式适合自动化重复修改、批量重构、写测试，也适合在 CI 或服务端环境里使用。

“Codex”这个名字在不同场景下指的东西不完全一样。搜索时能看到 codex cli、codex 桌面版、codex 官网登录入口、codex harness 这些关键词，它们属于不同的产品形态或项目。下面先做区分，避免在后面安装时把不同类型的产物混在一起。

1.2 三种形态的对比

注意，产品形态和版本更新比较快，Web 入口和桌面版的界面、功能、名称都可能调整。安装前先确认你当前下载的是官方发布渠道的版本，不要使用来路不明的安装包。

1.3 “免费使用”到底指什么

标题里常见的“免费使用”，需要理性理解。Codex CLI 本身可以通过 npm 安装，但实际调用模型能力通常需要认证信息。免费可能来自几个方向：账号自带的额度、模型服务商给新用户的活动额度、或者自己部署开源模型。这三类方式的配置方法不同，是否免费、免费多少，以你所用账号和模型服务方控制台的当期规则为准。

本文只讲正规的安装、登录和配置流程，不涉及任何绕过付费或访问限制的操作。如果你在配置时需要 API Key，就去对应服务商控制台申请，走正常流程。

2. 环境准备：先把 Node.js、Git 和 PATH 检查一遍

2.1 为什么第一步检查 Node.js

Codex CLI 通过 npm 分发，而 npm 是 Node.js 自带的包管理器，所以安装之前必须先确认 Node.js 可用。如果 Node 版本过旧，npm 安装或 Codex 启动都可能失败，报错信息也很容易让人误以为是 Codex 本身的问题。

在终端里依次执行：

node -v npm -v git --version

正常情况下会看到：

• node：v18 或更高版本。
• npm：一个正常的 npm 版本号。
• git：已安装并返回版本号，比如 2.39.x。

如果命令不存在，先补齐对应工具再继续安装 Codex。Git 不是 Codex CLI 运行的必要条件，但后续很多工作流会用到 Git，建议提前装好。

2.2 不同操作系统下的推荐做法

使用 nvm 或 nvm-windows 管理 Node 版本是个好习惯，因为不同项目可能要求不同 Node 大版本，nvm 可以随时切换，也避免用 sudo 修改系统目录带来的权限问题。

2.3 安装前的环境检查清单

• [ ]node -v能输出版本号，且不低于 18。
• [ ]npm -v能输出版本号。
• [ ]git --version能输出版本号。
• [ ] 如果已经安装过 Codex，codex --version能输出版本号。
• [ ] 如果没有安装，跳过上一条，直接进入安装章节。

环境检查这一步看起来基础，但大多数“装不上”的问题都出在这里。先确认环境正常，再开始安装，能省掉很多无效排查。

3. 安装 Codex CLI 和桌面版：两种方式分开说

3.1 用 npm 全局安装 Codex CLI

打开终端，执行：

npm install -g @openai/codex

-g表示全局安装，也就是把它安装到当前用户或系统的 npm 全局目录，而不是某个项目目录。安装完成后，终端里就可以直接用codex命令。

执行：

codex --version codex --help

codex --version如果输出了版本号，说明命令已经进入 PATH；codex --help会列出常用子命令，比如 login、logout、version 等。

如果提示找不到命令，说明 npm 全局目录没有加入 PATH，处理方法看下一节。

3.2 安装成功但提示 command not found

这是最常见的安装问题。npm install本身可能没有报错，但系统找不到codex可执行文件。原因是 npm 全局 bin 目录不在 PATH 环境变量里。

先查看 npm 全局目录：

npm prefix -g npm config get prefix

在 Windows 上，npm prefix -g通常输出类似C:\Users\你的用户名\AppData\Roaming\npm的路径。把该路径加入系统 PATH，或者在当前 PowerShell 窗口临时执行：

$env:Path += ";$env:APPDATA\npm"

在 macOS 和 Linux 上，把全局 bin 目录加入 shell 配置，例如：

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

建议把这行写入~/.bashrc或~/.zshrc，避免每次开终端都要重新设置。

还有一种情况是 npm 安装时报 EACCES 权限错误。这通常是因为用系统级目录作为 npm 全局目录。推荐用 nvm 管理 Node，或者把 npm 全局目录改到用户目录下，不要用 sudo 强行安装，那样容易留下权限隐患。

3.3 桌面版安装和“打不开”的排查

如果你更习惯图形界面，可以直接从 Codex 官网下载桌面版安装包。Windows 上运行安装程序，macOS 上把应用拖到 Applications 目录。安装完成后启动应用，用同一套账号登录。

桌面版打不开时，按这个顺序排查：

1. 检查安装包是否完整下载，重新下载后再装一次。
2. Windows 上尝试右键以管理员身份运行，看是否有权限提示。
3. 检查系统安全软件是否拦截了程序启动。
4. 尝试从终端直接运行安装目录里的可执行文件，观察终端输出的错误信息。

桌面版和 CLI 共用同一个登录体系，但版本更新节奏可能不同。如果你在命令行里已经能正常使用 Codex，桌面版又打不开，可以优先查看桌面版的日志或错误弹窗，不要盲目重装系统。

4. 登录和 API Key：两种认证方式都要会

4.1 方式一：用 ChatGPT 账号登录

在终端执行：

codex login

命令会生成一个授权链接。正常情况下会自动打开浏览器，如果浏览器没有打开，可以复制链接手动打开，登录后把授权码粘贴回终端。

登录成功后，凭证会写入用户目录下的 Codex 配置目录（常见位置是~/.codex目录，具体文件以版本为准）。之后启动 Codex 时它会自动读取凭证。

4.2 方式二：用 API Key

如果你不使用 ChatGPT 账号登录，而是在模型服务商控制台申请了 API Key，可以通过环境变量注入。在 macOS 和 Linux 终端：

export OPENAI_API_KEY="sk-xxxx"

在 Windows PowerShell：

$env:OPENAI_API_KEY="sk-xxxx"

设置完成后启动 Codex，它读取到密钥就会走 API 认证。注意环境变量只在当前终端会话有效，重新开终端后需要重新设置；想长期生效，要写入 shell 配置或系统环境变量，也可以借助.env加载工具。

4.3 登录后怎么验证认证是否成功

不要只看到“登录成功”就结束，直接启动一个最小会话：

codex

然后输入一句最简单的请求，比如：

列出当前目录下的文件

如果 Codex 正常返回结果，认证链路就通了。如果报 401 或提示认证失败，优先检查：

• API Key 是否填写完整，是否复制到多余空格。
• 账号是否还有有效额度。
• 当前会话的环境变量是否被其他配置覆盖。

5. 接入 DeepSeek 等 OpenAI 兼容服务：理解 base_url、model、env_key

5.1 为什么需要切换模型提供方

Codex 默认调用 OpenAI 官方接口，但不少开发者在学习或测试阶段希望接入其他 OpenAI 兼容服务，例如 DeepSeek。原因可能是成本、额度或者团队内部已经部署了兼容接口。Codex CLI 可以通过配置文件指定“模型提供方”，也就是告诉它：连接哪个接口地址、使用哪个模型 ID、从哪个环境变量读取密钥。

5.2 用 config.toml 配置自定义提供方

Codex CLI 的配置文件通常是用户目录下的~/.codex/config.toml。下面是一个接入 DeepSeek 的示例结构：

# 默认使用哪个模型 model = "deepseek-chat" # 默认使用哪个提供方 model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

逐个解释字段含义：

• model：Codex 默认使用的模型 ID，必须是模型服务商真实支持的模型名。
• model_provider：默认提供方的名称，和下面配置段的名称对应。
• name：提供方的显示名，用于日志和界面展示。
• base_url：模型服务的 API 地址，不同服务商的路径规范可能不同，有的要求带/v1前缀。
• env_key：程序读取哪个环境变量作为密钥。密钥不要直接写在 toml 里，而是先设置环境变量，再由 Codex 去读。
• wire_api：使用chat还是responses协议。如果服务商只实现其中一种，写错会直接导致请求失败。

上面是示例结构，不同版本的字段名和默认值可能有差异，落地前先阅读你所用 Codex 版本的官方仓库说明，以及模型服务商提供的兼容文档。

设置环境变量：

export DEEPSEEK_API_KEY="sk-xxxx"

然后启动codex，用一句简单请求验证是否能正常返回。如果失败，检查配置里的模型 ID 是否存在、base_url 是否完整。

5.3 切换提供方后最常见的报错：model is not supported

接入第三方提供方后，经常会出现类似下面的报错：

the 'xxx' model is not supported when using codex ...

这类问题的原因通常有三个：

1. 配置的model名称不是该服务商支持的模型 ID。
2. wire_api协议写错，服务商只支持 chat 协议，但配置用成了 responses。
3. base_url指向的服务并不提供该模型，或者地址本身指向错误环境。

排查方法：先到服务商控制台或文档里确认模型 ID 的准确写法，再确认 base_url，最后把wire_api改成服务商支持的类型。改完配置后，新开一个 Codex 会话再测试。

注意：配置文件修改后，旧会话不一定立即生效。Codex 通常在启动时读取配置，因此修改完要退出当前会话，重新启动。

6. 用 CC Switch 管理多套服务和 /responses 报错排查

6.1 CC Switch 解决的是配置切换问题

当你有多个模型服务商、多套 API Key 时，手动改config.toml很繁琐，还容易改错。CC Switch 是一个社区常用的桌面工具，用于在多个服务配置之间切换。它把“使用哪个服务、哪个 Key、哪个模型”集中在一个界面里，切换后启动的 Codex 会走新的配置。

需要强调一点：CC Switch 本身不提供模型能力，它只负责把请求导向你配置的目标服务，并在本地启动一个转发服务来配合 Codex 工作。因此排查问题时，目标服务是否可用、转发服务是否启动的检查，两方面都要做。

6.2 基本配置流程

在官方发布渠道下载安装 CC Switch，启动后在界面里添加服务。常见字段如下：

添加完成后，在界面中选择当前生效的服务，然后重启 Codex 或新开会话。建议先用一句最小请求验证切换是否成功，再开始正式任务。

6.3 /responses 请求失败怎么排查

切换服务后，Codex 会话请求可能直接失败，错误日志里会出现类似failed while handling codex endpoint /responses的关键字。出现这个情况，优先按下面的顺序查。

快速定位问题归属的方法：先暂时不启用 CC Switch，直接按第 5 节的方法用环境变量连目标服务。如果直连正常，说明问题出在 CC Switch 这一层；如果直连也失败，则是目标服务的地址、密钥或模型配置有问题。这样能快速把排查范围缩小到一层。

另外，CC Switch 和 Codex 的版本都在更新，接口行为可能变化。遇到无法解释的报错，先升级到较新版本，再查看工具自身的日志目录。

7. 高频问题速查：从安装到运行一条链排到底

7.1 问题速查表

7.2 三个最容易踩的坑

坑一：把 API Key 直接写进 config.toml。配置文件容易被复制、分享或提交到仓库，密钥一旦泄露，可能被他人滥用产生费用。正确做法是使用env_key指向环境变量，真实密钥只出现在本机的环境变量或密钥管理工具里。

坑二：只配了 model_provider，没有改 model。很多人的 config.toml 里添加了[model_providers.deepseek]配置段，但最上层的model还是官方模型的 ID，结果 Codex 仍然去调用旧模型。配置时要检查model和model_provider是否配对。

坑三：修改配置后不重启会话。Codex 读取配置的时机一般是启动时，修改配置后如果继续在旧会话里测试，会看到“改了没生效”的假象。遇到这种问题，先退出会话重新启动，再验证。

7.3 统一排查顺序

遇到任何安装或运行问题，按这个顺序排查，效率最高：

1. 命令是否存在：用codex --version或系统命令查找确认。
2. 版本是否满足：Node.js、npm、Codex 三个版本都要确认。
3. 配置位置是否正确：确认你改的是~/.codex/config.toml，不是别的目录下的同名文件。
4. 密钥是否注入：检查环境变量是否真的存在，用printenv或echo查看，注意不要把完整密钥输出到日志。
5. 地址和协议是否匹配：base_url、model、wire_api 三项要一起核对。
6. 看日志关键字：大多数问题都会在终端或工具日志里留下线索。
7. 最小化复现：关掉多余工具，直接用环境变量方式连目标服务，判断问题在哪一层。

8. 生产使用建议和可复用检查清单

8.1 密钥安全：让配置文件和密钥彻底分离

无论是 Codex 还是 CC Switch，都不要把密钥写进会被分享的文件。建议只通过环境变量注入，并在项目目录的.gitignore中排除.env等文件。CI 环境中使用密钥管理服务注入，而不是写在流水线配置文件里。如果怀疑密钥泄露，及时到服务商控制台撤销并重新生成。

8.2 会话记录、成本和回滚

Codex 的会话记录通常会保存在用户目录下的 Codex 配置目录中，常见位置是~/.codex下，具体文件名以版本为准。重要工作前可以复制备份该目录，出问题时直接回滚。

使用第三方模型服务时，要在服务商控制台关注用量和余额，给测试任务选择成本更低的模型。升级 Codex 前先看发布说明，如果升级后发现行为变化，可以回退到之前的版本。在生产脚本中，建议固定 Codex 版本，而不是每次拉最新版。

8.3 可复用检查清单

环境检查清单：

• [ ] Node.js 版本不低于 18。
• [ ] npm 和 Git 命令可用。
• [ ] npm 全局 bin 目录已加入 PATH。
• [ ]codex --version能正常输出。

接入新服务核对清单：

• [ ] 已拿到服务商提供的 base_url。
• [ ] 已申请有效 API Key。
• [ ] 已确认模型 ID 在服务商文档中存在。
• [ ] 已确认协议类型是 chat 还是 responses。
• [ ] config.toml 中 model 与 model_provider 配对。
• [ ] 环境变量名称与 env_key 一致。
• [ ] 已用一句最小请求验证。

排错优先级清单：

• [ ] 命令是否存在。
• [ ] 版本是否满足。
• [ ] 配置文件位置是否正确。
• [ ] 密钥是否注入。
• [ ] 地址和协议是否匹配。
• [ ] 日志关键字是否出现。
• [ ] 最小化复现是否成功。

Codex 这类命令行编程智能体的价值，不在于把某一条指令写对，而在于它能接管一连串读代码、改代码、跑命令、看报错的循环。要把这套工具稳定用起来，核心不是等一个“最新教程”，而是建立自己的安装、认证、配置、排错链路。文中的示例配置和命令，落地时一定要以本机的 Node 版本、Codex 版本和服务商文档为准。下一步建议先把最小会话跑通，再接入第二个、第三个模型提供方，最后再用 CC Switch 这类工具做集中管理。对新手来说，最有价值的练习是故意把配置写错一次，然后按第 7 节的排查顺序把它找回来。