企业官网建设流程全解析

1. Codex 到底是什么？先搞清楚它和聊天框的区别

2026 年 9 月，后台私信里问得最多的问题依然是 Codex 安装。其实这工具我已经在项目里用了大半年，最近又帮两个完全没接触过命令行的同事，从零开始把 Codex 装好并跑通了第一个任务。这篇就把完整过程写下来，覆盖环境准备、CLI 和桌面版安装、登录、接入 DeepSeek，以及我实际踩过的几个报错坑，目标是让你照着敲一遍就能上手，而不是看完一堆说明书然后原地发懵。

在写安装命令之前，我想先花两三分钟把 Codex 的定位说清楚。我见过太多人装完以后试了两句话就放下了，原因不是工具不好用，而是理解错了。Codex 不是一个网页版的 AI 写作助手，它是 OpenAI 推出的编码智能体（agent），能直接在你电脑上读取文件、写文件、执行终端命令、运行测试。换句话说，ChatGPT 网页版只负责“讲话”，Codex 还会“动手”。后台那套运行逻辑，大家通常叫它 agent harness：它把一次编程任务拆成很多个小步骤，自己判断下一步该读哪个文件、该跑哪条命令，而不是像普通聊天窗口那样等你把上下文全部粘进去。

1.1 它是怎么帮你干活的

一个非常典型的场景：你打开终端进入一个空目录，输入codex，然后说“帮我用 Python 写一个爬取博客文章列表的小脚本”，它会先给你列一个简短计划，然后开始建目录、安装依赖、创建文件、执行脚本。如果中途报错，它会自己看错误日志，再改代码再跑一遍。这个体验和“复制粘贴到 ChatGPT 里”完全是两回事，因为你不再需要手动把每个文件内容粘进去，Codex 自己掌握文件系统上下文。

具体到能力边界，Codex 大概能做这几类事：

• 读写项目里的文件，新建、修改、删除都能触发；
• 在项目目录里执行终端命令，比如npm test、python manage.py migrate；
• 调用外部工具链，比如 Git、Docker、包管理器；
• 把多次尝试后的最终结果整理成清晰的改动说明。

注意，它不是你电脑上的万能遥控器。默认情况下，Codex 的权限被限制在启动目录或你授权的 workspace 内，不会随便去翻你桌面上的私人文件。这个限制后面会提到，它是安全机制，不是功能缺陷。

1.2 2026 年的 Codex 常见形态

现在 Codex 已经不止一个形态了。我建议你根据自己的操作习惯选一个主用入口，其他的可以后面再补。下面这个表格是我个人理解的使用场景划分：

我给你的建议是：新手从桌面版起步，但不要完全扔掉 CLI，因为网上大部分教程、脚本、配置文件都是围绕 CLI 写的。你只要看得懂命令行，后面排查问题会轻松很多。接下来就从环境准备开始，一步一步走。

2. 开工前的准备：Node.js、Git、VS Code 一次装齐

很多新手装 Codex 失败，不是 Codex 本身的问题，而是电脑里缺了依赖。Codex 安装虽然只有一条命令，但它的运行环境涉及 Node.js 和 Git，少一个都会在某个环节突然报错。所以我先带你把底座打好。

2.1 先装 Node.js：Codex CLI 的运行底座

Codex CLI 一般通过 npm 安装，npm 是 Node.js 自带的包管理器，所以第一步就是装 Node.js。

到 Node.js 官网下载页，选择 LTS 版本即可。LTS 意味着长期维护版本，稳定性有保障，不要贪新去下最新的 Current 版。Windows 用户选.msi安装包，下载后双击一路下一步。安装路径尽量保持默认，千万不要放到带中文或空格的目录里，后面很容易出现路径解析问题。

安装完成后，打开一个新的终端窗口（这一步很关键，旧窗口不会自动刷新环境变量），分别输入：

node -v npm -v

能看到版本号输出，说明 Node.js 装好了。如果提示node 不是内部或外部命令，一般是 PATH 没生效。解决办法是重启终端，或者手动把 Node.js 安装目录加到系统环境变量里。Windows 下默认安装路径通常是C:\Program Files\nodejs\，把这个目录加到 Path 变量后重新打开终端即可。

2.2 再装 Git：很多自动化操作依赖它

Codex 在克隆代码、查看 Git 状态、处理补丁时都会调用 Git。虽然你不一定直接用它，但 Git 是底层依赖，装好能省掉很多麻烦。

Windows 用户去 Git 官网下载 Git for Windows，安装时大部分配置保持默认。唯一要注意的是安装过程中有一个“Adjusting your PATH environment”的选项，一定要选第二项Git from the command line and also from 3rd-party software。如果选了第一项，Codex 在终端里可能找不到 Git 命令。

装完后同样验证一下：

git --version

能输出版本号就说明没问题。macOS 用户如果装了 Xcode Command Line Tools，系统会自带 Git；没装的话执行xcode-select --install即可。Linux 用户用各自发行版的包管理器安装，比如sudo apt install git。

2.3 顺手把 npm 源切成国内镜像

这一步不是必须的，但我建议每个国内用户都做。原因很简单：npm 默认源在海外，下载大一点的包时速度可能很慢，甚至超时。国内有不少正规的 npm 镜像服务，切换之后下载速度能快很多。把 npm 默认源切到国内镜像，命令如下：

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

执行完第二条命令能返回刚才设置的地址，说明切换成功。之后再用 npm 安装任何包都会走这个镜像。如果某一天安装 Codex 突然报 404，很可能是镜像源还没来得及同步最新的 npm 包，这时候切回官方源再装一次就行：

npm config set registry https://registry.npmjs.org

3. 官方支持的安装方式，我推荐你先用这一种

环境准备好之后，真正的主角终于登场了。Codex 官方提供了多种安装方式，我按推荐程度从高到低排列，你选一种适合自己的就行。

3.1 方式一：npm 全局安装 Codex CLI

这是最常用、也最容易自动更新的方式。打开终端，直接执行：

npm install -g @openai/codex

-g表示全局安装，这样你在任何目录下都能直接使用codex命令。安装过程会输出一堆下载信息，看到added字样基本就成功了。装完以后，验证一下：

codex --version

如果你看到版本号，说明安装成功。如果提示codex 无法识别或command not found，大概率是 npm 的全局安装目录不在系统的 PATH 里。Windows 下常见的全局目录是%APPDATA%\npm，macOS/Linux 下可能是/usr/local/bin或~/.npm-global。把这个目录加到 PATH 后重新打开终端即可。

3.2 方式二：Windows 桌面版安装

Windows 用户如果不想碰命令行，可以去 Codex 官网找到 Windows 桌面版下载入口，下载安装包后双击安装。桌面版自带一套完整的运行环境，不需要单独安装 Node.js，对新手非常友好。

安装完成后，桌面上会有 Codex 的快捷方式。第一次打开会让你登录，登录流程和 CLI 类似。这里有个小细节：桌面版和 CLI 可以共存，互不干扰。你完全可以在桌面版里写写简单的需求，在 CLI 里跑自动化脚本，两者共享同一个配置文件~/.codex/config.toml，所以模型设置不会冲突。

3.3 方式三：macOS 使用 Homebrew

macOS 用户除了 npm 方式外，也可以用 Homebrew 安装。如果你已经装了 Homebrew，只需要执行：

brew install codex

或者按官方文档添加适合当前版本的工具源。Homebrew 的好处是它会把相关依赖一起处理好，升级也方便，后续直接brew upgrade codex就能更新。Linux 用户同理，可以去官方仓库查看对应的安装包，但我个人还是建议 Linux 服务器上用 npm 方式，因为更灵活，也更容易配合 CI 流程。

3.4 安装完成后最关键的一步：登录认证

安装只是第一步，真正让 Codex 跑起来的是登录认证。运行：

codex login

终端会显示一个链接和一个授权码。浏览器打开链接，把授权码填进去，选择用 ChatGPT 账号授权即可。授权成功后，回到终端就能看到登录成功的提示。

如果你习惯用 API Key，也可以直接用下面的方式登录：

codex login --api-key

然后粘贴你的 API Key。这里要区分一下两种认证方式的差别：ChatGPT 账号登录走的是订阅套餐额度，API Key 走的是按 token 计费。对于新手，我建议先用 ChatGPT 账号体验，跑通流程后再考虑 API Key。无论用哪种方式，都要记住不要把 API Key 提交到 Git 仓库里，尤其是公开仓库，否则别人拿到你的 Key 就能随意调用接口，产生不必要的费用。

4. 上手实操：跑通一次完整的编码任务

登录成功后，Codex 就算正式能用了。很多新手到这一步就卡住了，因为不知道第一句话该说什么。别急，我带你跑一个最经典的“用 Python 写爬虫”任务，把交互式和非交互式的用法都过一遍。

4.1 交互式命令行：第一次对话

找一个空目录，打开终端进入这个目录，然后输入：

codex

几秒钟后，你会进入一个交互式界面，类似终端里的聊天窗口。输入：

帮我在当前目录下写一个 Python 爬虫，抓取某个公开博客的文章标题和发布时间，保存为 csv 文件

Codex 会先列出一个执行计划，然后开始创建文件、安装必要的依赖库。每一步执行前，它会请求你的确认。这里新手容易紧张，以为是不是出问题了。其实不是，这是 Codex 的安全控制机制：在执行会改变系统的命令前，需要经过你同意。

看到提示后按回车确认，Codex 就会继续干活。整个过程中，你可以随时输入新的要求打断它，比如“改用 requests 而不是 httpx”“结果里再加一个 url 字段”。这种边做边改的体验，比传统的“把需求写完整再让工具执行”舒服很多。

交互模式里还有几个实用快捷键：Ctrl+C可以中断当前任务，Ctrl+D退出 Codex，输入exit也能退出。如果你不确定当前有哪些模型可用，输入/model会列出账号支持的模型列表，这个功能在排查模型报错时特别有用。

4.2 非交互模式：codex exec 批量执行

如果每次都要进入交互模式，那自动化就无从谈起了。Codex 提供了exec子命令，可以在命令行直接指定任务，执行完自动退出：

codex exec "给当前项目补充一个 README.md，包含安装和运行说明"

这个模式下，Codex 会在后台自动执行任务，不会跟你反复确认，适合你已经信任的目录或在 CI 脚本里使用。我平时最常用的几个参数是：

codex exec --sandbox workspace-write "修复 tests 目录下的失败用例" codex exec --skip-git-repo-check "检查当前目录里的 Python 文件风格"

--sandbox用来控制权限范围，workspace-write表示只允许改动当前工作区；--skip-git-repo-check用在非 Git 仓库目录，避免 Codex 反复提醒你初始化版本控制。执行完以后，在命令后面加上-o参数可以把输出保存到文件，方便写定时任务时留日志。

4.3 配置文件 config.toml 的日常调整

Codex 的配置集中在~/.codex/config.toml。拿文本编辑器打开这个文件，你会看到类似下面的内容：

model = "gpt-5.2-codex" model_provider = "openai" sandbox_mode = "workspace-write"

这里的model是主模型，决定 Codex 的推理质量。OpenAI 官方会不定期更新模型名，如果你默认配置里的模型在你账号下不可用，就改成当前可用的模型。sandbox_mode有三个常见值：read-only只允许读取文件，workspace-write允许修改当前工作区，danger-full-access允许任意操作。新手建议保持workspace-write，既够用又不会把系统搞乱。

4.4 VS Code 里用 Codex：边写边改

如果你平时主要写代码，我更推荐安装 VS Code 的 Codex 扩展。安装后在侧边栏会多出一个 Codex 面板，你可以直接在里面输入任务，也可以选中报错代码后右键，选择让 Codex 处理。它能看到当前打开的项目文件，理解上下文能力比纯命令行更好一些。

实际使用中，我习惯把 VS Code 扩展和 CLI 搭配起来：日常小改动用扩展，批量脚本任务用 CLI。两边共用配置后，你会发现同一个项目里两个入口看到的模型、权限完全一致，不会出现“这边能用那边不能”的情况。

5. 国内进阶玩法：把 Codex 接到 DeepSeek

装好、登录好，你已经在用 Codex 了。但对不少国内用户来说，还有一个很现实的问题：ChatGPT 账号的订阅和网络环境未必那么顺手。这时候，有一条国内开发者很喜欢的路——把 Codex 的后台模型替换成 DeepSeek。Codex 本身支持自定义模型提供商，接 DeepSeek 以后，操作界面和流程不变，但底层跑的是 DeepSeek 的模型，成本更低，国内访问也更顺畅。

5.1 为什么要“换模型”

其实很简单：Codex 的核心价值是那套能自己调工具、改代码的 agent 机制，它相当于一个“手脚灵活的躯体”。模型相当于大脑，大脑可以选择不同的供应商。DeepSeek 是国产开源模型里综合能力很强的选手，写代码、做重构、解释报错都不含糊，而且 API 价格对个人开发者非常友好。

所以对于国内个人开发者，尤其是处于学习阶段的新手，把 Codex 接到 DeepSeek 是一个兼顾体验和成本的方案。你不用完全依赖 OpenAI 的订阅，也不用担心海外支付渠道的问题，只要有一个 DeepSeek 的 API Key，就能在同样的 Codex 操作流程里继续干活。

5.2 修改 config.toml 接入 DeepSeek

打开~/.codex/config.toml，在文件里加入一个自定义 provider，然后把默认模型指向它。我实际跑通的配置如下：

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

接着设置环境变量。macOS/Linux 在终端里执行：

export DEEPSEEK_API_KEY="sk-你的密钥"

Windows PowerShell 用户执行：

$env:DEEPSEEK_API_KEY="sk-你的密钥"

设置完以后，重新启动 Codex，再执行codex进入交互模式，它就会用 DeepSeek 模型来响应。你可以随便问一句“用 Python 写一个二分查找”，看看返回质量是否符合预期。

如果你想把 DeepSeek 作为无条件默认模型，就把model_provider = "openai"改为model_provider = "deepseek"。如果只是临时想切换，不用改文件，在执行命令时加参数：

codex exec --model-provider deepseek "解释这段代码"

5.3 接入 DeepSeek 后要注意什么

接入过程虽然简单，但有几个坑我得提前告诉你：

• DeepSeek 的接口地址一定要写对，base_url结尾是/v1，不要漏掉，否则认证会失败。
• 不同模型的工具调用能力有差异。Codex 这类智能体非常依赖模型能不能正确调用工具，如果你的 DeepSeek 模型版本太旧，可能会出现“模型说了要做，但迟迟不动手”的情况。遇到这种问题，先升级到 DeepSeek 最新版模型。
• 成本不要只看单次价格。DeepSeek 便宜，但智能体会反复调用多次，容易比你预期的 token 消耗更多。个人体验下来，日常任务影响不大，但如果让 Codex 全自动跑一个大型重构，还是要留意账户余额变化。

我用 DeepSeek 跑了快两个月的日常开发，最大的体会是“作为默认模型非常够用”。一些小脚本、注释、单元测试，DeepSeek 的处理速度和准确度都不错。遇到特别复杂的架构设计、跨模块重构，我再手动切回 OpenAI 模型，两边互补，既省钱又不损失质量。

6. 新手最容易掉进去的坑：报错定位与处理方法

最后这部分，我把自己和身边同事实际踩过的坑整理成一个排查手册。Codex 本身迭代很快，网上教程的配置可能早就过时了，但排查思路是通用的。遇到问题不要一上来就重装，先按下面的顺序定位。

6.1 遇到 “cc switch local ... codex endpoint /responses” 的处理

这是最近不少人问过的一个报错。现象是执行codex命令时，日志里出现类似cc switch local ... failed while handling codex endpoint /responses的提示，然后任务被迫中断。第一次遇到，我也被绕晕过。

拆开看，前半段是 Codex 在启动时切换本地运行状态失败，后半段是它去调用/responses接口时没有拿到预期响应。换句话说，这不一定是 Codex 安装坏了，而是它向外发请求时没有走通，或者本地运行环境被什么东西干扰了。

我的排查顺序是这样的：

1. 完全退出 Codex 进程，重新启动一次，排除偶发状态残留。
2. 检查系统防火墙或安全软件，看是否拦截了终端程序和 Codex 相关进程。Windows 自带的防火墙偶尔会误拦，Mac 上则要检查是否有权限弹窗没被处理。
3. 查看 hosts 文件有没有被其他工具改成奇怪的条目。如果之前用过什么网络优化工具，它篡改 hosts 后可能会让 Codex 的域名指向错误地址。
4. 换一个网络环境再试。比如从公司网络切到手机热点，或者从 Wi-Fi 切到有线网络。很多内部网络会做访问控制，导致 Codex 的服务端连接异常。
5. 重新执行codex login，刷新登录凭证。

按这个顺序处理，大部分情况都能解决。真正需要重装 Codex 的情况反而很少。

6.2 模型报错：The 'gpt-5.6-sol' model is not supported

这个报错在切换模型后特别常见。官方原话是The 'gpt-5.6-sol' model is not supported when using Codex with a ChatGPT acc，意思是当前 ChatGPT 账号不支持使用gpt-5.6-sol这个模型。它跟安装无关，纯粹是账号权限和模型名不匹配的问题。

解决办法分两种情况。

如果你用的是 ChatGPT 账号登录，就在config.toml里把model改成账号确实支持的模型。不确定的话，直接在交互模式里输入/model，它会列出当前账号可用的模型列表，照着列表选一个填进去就行。

如果你用的是 API Key，优先确认 Key 对应的组织是否有权限访问指定的模型。有些 Key 是从老项目里继承下来的，模型权限可能被限制在很小的范围。这时候去后台生成一个新的 Key，或者改用一个默认支持模型的名字再试。

还有一种情况是官方更新了模型名，旧教程里的名字已经下线。遇到这种问题，直接去 Codex 官方文档或 changelog 里查最新的模型列表，比我这里写的任何具体名字都靠谱。

6.3 桌面版打开就白屏、闪退

桌面版虽然对新手友好，但偶尔也会抽风。我遇到过的原因无非这几类：

• 系统版本太旧。Codex 桌面版对 Windows 和 macOS 的最低版本有要求，太老的操作系统跑不起来。
• 缺少系统运行库。Windows 下常见的是 VC++ 运行库缺失，去微软官网装最新的 Microsoft Visual C++ Redistributable 通常能解决。
• 配置文件损坏。如果你之前用过旧版 Codex，~/.codex目录里可能残留了不兼容的配置。先把config.toml备份一份，然后把整个.codex目录改名成.codex.bak，再重新登录试试。
• 杀毒软件误杀。Windows Defender 或其他安全软件可能会把 Codex 的主程序当成可疑文件隔离，需要到隔离区里恢复并加入信任名单。

桌面版闪退还有一种可能，就是磁盘空间不足。Codex 在运行时会写日志和临时文件，空间满了就会出现各种奇怪行为。清理一下磁盘缓存再启动，往往就好了。

6.4 登录不上、登录后一直没反应

登录流程卡住也是问得比较多的问题。这里有一个通用套路：

如果你点开登录链接以后页面一直转圈，先换一个浏览器试试，或者用无痕模式重新打开链接。浏览器插件（广告拦截、脚本管理）很容易干扰授权页面的跳转，无痕模式能避开大部分插件问题。

如果授权页能打开，但回到终端发现还是没反映，可以检查一下系统时间。别笑，这个问题我真实遇到过。系统时间跟实际时间偏差过大时，HTTPS 握手会失败，登录请求自然无法完成。校准系统时间后重新登录即可。

如果登录后提示OpenAI account is not allowed之类的错误，基本可以确定是账号本身的权限问题，需要检查当前账号是否有 Codex 使用权限。免费账号与付费账号在可用模型和功能上是有差异的，申请一个对应套餐或换成 API Key 登录，问题一般就能解决。

6.5 高频问题速查表

最后再分享一个个人习惯：不管新装哪个版本，我都会先在临时目录里跑一个完整的“从零创建项目”流程。这样既不污染正经代码库，又能快速确认工具链是否真的通畅。“能跑通”和“看起来很能跑”之间，差的往往就是这个最小实验。Codex 版本更新很快，配置写法可能过一两个月就有变化，但只要你掌握了排查思路，以后遇到任何新报错都不会慌。