在现代软件开发中，代码规模越来越大、技术栈越来越复杂，开发者花在“理解代码、改动代码、反复验证”的时间，往往远多于真正写新功能的时间。为了解决这一问题，Codex 应运而生。
Codex（Codex CLI） 是一个运行在终端中的 AI 编程助手。与普通聊天式 AI 不同，它可以直接读取你的项目代码、理解文件结构，在你的确认下修改源码、执行命令，并一步步完成真实的开发任务。你可以把它理解为一个“懂代码、会动手、但始终受你控制的编程搭档”。
在本文中，你将从零开始学习 Codex 的安装、配置与实际使用方法，包括如何接入第三方 API、如何在终端和 VS Code 中高效使用，以及遇到常见问题时如何快速排查。即使你从未使用过类似工具，也可以按照本文一步步完成配置，并真正把 Codex 用到你的日常开发中。
一、安装前准备（所有系统通用）
开始安装 Codex CLI 之前，需要准备以下环境：
- Node.js 22+
- npm 10+
- 稳定网络连接
Windows 额外注意
OpenAI 官方也提到 Windows 支持偏“实验性”，更稳的方式是使用 WSL 环境。
二、安装 Codex CLI
Windows
1. 安装 Git Bash
安装 Git Bash，按照安装向导一直下一步即可。
2. 安装 Node.js
安装 Node.js，建议安装最新 LTS 版本。
3. 安装 Codex CLI
在 CMD 或 PowerShell 中执行：
npm install -g @openai/codex
4. 验证安装
执行：
codex --version
如果能够正常返回版本号，说明 Codex CLI 已经安装成功。
macOS
直接执行：
npm install -g @openai/codex
然后验证：
codex --version
必要时可以加 sudo。
OpenAI 官方也提供了 Homebrew 安装方式，可选执行：
brew install codex
Linux
首先安装 Node.js / npm，具体安装命令根据不同 Linux 发行版有所区别。
安装完成后执行：
sudo npm install -g @openai/codex
然后验证：
codex --version
三、配置神马中转 API 作为第三方 API
Codex CLI 会读取自己的配置文件，一般位于：
~/.codex/
Windows 同样位于用户目录下的 .codex 文件夹。
通常需要创建两个配置文件：
- auth.json：用于存放 API Key
- config.toml：用于设置模型与 API 网关配置
四、Windows 配置路径与文件
1. 找到 .codex 文件夹
进入用户目录下的 .codex 文件夹。
例如：
C:\Users\testuser\.codex
如果看不到 .codex，需要先在 Windows 资源管理器中开启“显示隐藏项目”。
2. 创建配置文件
如果没有 .codex 文件夹，可以手动创建。
然后在其中创建：
auth.jsonconfig.toml
3. 配置 auth.json
打开 auth.json，将下面的 sk-xxx 替换成你自己的神马中转 API Key：
{"OPENAI_API_KEY": "sk-xxx"}
4. 配置 config.toml
打开 config.toml，填写模型和 API 网关配置：
model_provider = "whatai"model = "gpt-5-codex"model_reasoning_effort = "high"disable_response_storage = truepreferred_auth_method = "apikey"[model_providers.whatai]name = "whatai"base_url = "https://api.whatai.cc/v1"wire_api = "responses"
其中：
model_provider用于指定当前使用的模型提供商。model用于指定使用的模型。model_reasoning_effort = "high"用于设置较高的推理强度。disable_response_storage = true用于关闭响应存储。preferred_auth_method = "apikey"表示使用 API Key 认证。base_url用于指定神马中转 API 的接口地址。wire_api = "responses"用于指定 API 通信方式。
五、macOS / Linux 配置命令
macOS 和 Linux 可以直接通过终端创建 .codex 目录以及配置文件。
创建目录：
mkdir -p ~/.codex
创建 auth.json：
touch ~/.codex/auth.json
创建 config.toml：
touch ~/.codex/config.toml
之后编辑 auth.json 与 config.toml，配置内容与前面的 Windows 配置方式相同。
这里有一个非常重要的注意事项：
model_provider = "xxx" 必须与：
[model_providers.xxx]
中的段名保持一致。
例如：
model_provider = "whatai"[model_providers.whatai]
这里两个 whatai 必须完全一致。
配置完成后一定要重启终端
修改配置文件之后，不要直接继续使用原来的终端环境。
关闭当前终端，然后重新打开终端，再启动：
codex
这样可以确保新的配置正常生效。
六、启动与基本使用
首先进入你的项目目录：
cd your-project-folder
然后运行：
codex
也可以直接在命令后面跟一个初始任务。
例如，让 Codex 先解释当前代码仓库：
codex "Explain this codebase to me"
这样 Codex 就会直接针对当前项目进行分析。
七、推荐的 Codex 使用习惯
1. 先让它“读项目、给计划”
不要一开始就让 Codex 大范围修改项目。
可以先告诉它：
先扫描项目结构，列出你会修改哪些文件，再开始动手。
这样可以先了解 Codex 对项目的理解和准备修改的内容。
2. 小步提交
建议每次只让 Codex 完成一件事情，例如：
- 修一个 Bug
- 增加一个功能点
- 修改一个页面
- 优化一段代码
不要一次让它进行大量无关修改。
3. 使用 Git 做检查点
由于 Codex 可以直接修改项目文件，因此建议在执行任务前后使用 Git checkpoint。
这样即使 Codex 的修改结果不符合预期，也可以快速回滚。
八、交互技巧：Slash 命令与快捷操作
在 Codex 交互界面中输入 /，可以打开 slash 命令菜单，用于切换模型、调整权限、总结对话等。
一些常见命令包括：
/status
查看当前会话配置和状态。
/new
开启一个新的会话并清空当前上下文。
/model
切换模型。
/init
初始化一些模板或设置，具体功能可能会根据 Codex 版本有所不同。
此外，很多版本还支持使用 ! 直接执行终端命令。
例如：
!git status
或者：
!ls
这种方式可以减少“让模型代跑命令”的额外交互成本。
九、VS Code 插件 Codex
完成前面的 .codex 配置之后，还可以在 VS Code 中使用 Codex。
基本流程是：
- 打开 VS Code。
- 进入扩展商店。
- 搜索
codex。 - 安装 Codex 扩展。
- 安装完成后，Codex 会出现在 VS Code 侧边栏。
OpenAI 官方 quickstart 也提到，安装完成后 Codex 面板会出现在侧边栏，有时可能位于折叠区域。
这样就可以将 Codex 与日常的 VS Code 开发工作流结合起来。
十、常见问题（FAQ）与排查清单
Q1：codex: command not found / 找不到命令
这种情况通常有两个原因：
- npm 全局安装路径没有加入 PATH。
- Codex 没有安装成功。
首先运行：
codex --version
确认是否安装成功。
如果仍然无法使用，可以重新安装：
npm install -g @openai/codex
安装完成之后再次运行：
codex --version
Q2：Linux/macOS 安装时报权限错误（EACCES）
如果安装过程中出现权限错误，可以使用：
sudo npm install -g @openai/codex
Linux 中可以使用上述方式解决。
更长期的解决方案是将 npm 全局目录修改到用户目录，不过这属于通用的 Node.js / npm 运维问题，并不是 Codex 专属配置。
Q3：Windows 找不到 .codex 文件夹
如果 Windows 中找不到 .codex 文件夹，需要在资源管理器中开启：
显示隐藏的项目
因为 .codex 属于隐藏目录风格。
如果仍然没有找到，可以手动创建：
.codex
然后在其中创建：
auth.jsonconfig.toml
Q4：配置了 Key 但仍然提示未认证 / 401
首先检查 auth.json。
内容必须类似：
{"OPENAI_API_KEY": "sk-xxx"}
然后确认：
- API Key 是否正确。
auth.json文件位置是否正确。- 修改配置后是否重新启动终端。
完成修改之后重新打开终端，再运行：
codex
Q5：一直连不上 / 超时 / 网络错误
遇到连接失败、超时或者网络错误时，首先检查：
base_url
是否完全一致。
同时还需要考虑网络环境。
例如公司网络、校园网络等环境可能需要配置代理，或者放行相关域名。
如果属于网络限制问题，那么问题并不一定来自 Codex 本身。
Q6：模型不可用 / 报 model not found
出现：
model not found
通常意味着配置的模型名称与当前 API 实际提供的模型名称不匹配。
可以先尝试使用提供的模型名称：
gpt-5.2-codex
如果你在神马中转 API的模型列表中看到的名称不同，则应该以实际可用的模型名称为准。
模型名称不匹配会直接导致调用失败。
需要特别注意，配置示例中的模型名称可能会随着 API 服务和 Codex 版本变化，因此实际使用时应该以当前可用模型列表为准。
Q7：config.toml 写了但好像没有生效
最常见的原因是：
model_provider = "X"
和：
[model_providers.X]
中的名称不一致。
例如错误配置：
model_provider = "whatai"[model_providers.api111]
这里前面的 whatai 和后面的 api111 不一致，就可能导致配置无法正常工作。
正确情况下应该保持一致：
model_provider = "whatai"[model_providers.whatai]
此外，还需要检查是否忘记重启终端。
修改 config.toml 后，建议关闭当前终端并重新打开，然后再次运行 Codex。
Q8：怎么升级 / 更新 Codex CLI？
OpenAI 官方给出的升级方式是：
npm i -g @openai/codex@latest
执行完成后，可以通过：
codex --version
查看当前安装的版本。
Q9：有哪些命令行参数 / 高级配置可以查？
Codex 官方提供了 command line options 参考。
CLI 默认会从：
~/.codex/config.toml
读取配置。
同时也支持使用：
-c key=value
临时覆盖配置。
如果需要进一步调整 Codex 的高级参数，可以参考官方提供的 command line options 和 config reference。
总结
通过以上步骤，可以从零完成 OpenAI Codex CLI 的安装，并通过 auth.json 和 config.toml 将 Codex 接入神马中转 API。
完整流程可以概括为：
安装 Node.js / npm → 安装 Codex CLI → 创建 .codex 配置目录 → 配置 auth.json → 配置 config.toml → 重启终端 → 运行 Codex → 在终端或 VS Code 中使用。
如果遇到问题，优先检查 API Key、base_url、模型名称、model_provider 配置、文件路径以及终端是否重启。这几个部分基本覆盖了 Codex 第一次安装和配置时最常见的问题。
文章评论