⏱️ 阅读时间：8分钟 | 📌 难度：入门级 | 🔧 适用系统：macOS / Linux / Windows(WSL2)
前言
距离上次写 Codex 测评已经有一段时间了，这期间 Codex 又经历了好几轮大更新：Computer Use 能力、内置浏览器、持久记忆、90+ 插件生态…
更重要的是，Codex CLI 最新版本已经到 v0.130.0（2026-05-08），GitHub Star 数突破 83,200+。
今天带来一篇纯实操教程，手把手教你从零安装部署 Codex，包含国内用户最关心的网络问题解决方案。
一、环境准备
1.1 系统要求
| 操作系统 | macOS 12+ / Ubuntu 20.04+ / Windows 11 (WSL2) | macOS 14+ / Ubuntu 22.04+ |
| Node.js | 18.0+ | 22.0+ |
| npm | 10.0+ | 最新版 |
| Git | 2.23+ | 2.40+ |
| 内存 | 4GB | 8GB+ |
⚠️ Windows 用户注意：Codex CLI 暂时不支持原生 Windows，需要通过 WSL2 或使用 Codex App。
1.2 环境检查
在终端执行以下命令检查当前环境：
# 检查 Node.js 版本
node –version
# 输出示例：v22.12.0 ✓
# 检查 npm 版本
npm –version
# 输出示例：10.9.0 ✓
# 检查 Git 版本
git –version
# 输出示例：git version 2.43.0 ✓
如果版本不满足要求：
# Node.js 安装（macOS/Linux）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –
sudo apt-get install -y nodejs
# Windows 用户：安装 WSL2 后在 Linux 环境操作
wsl –install
二、安装步骤
2.1 安装 Codex CLI
Codex CLI 有两种安装方式，推荐方式一：
# 方式一：npm 安装（推荐）
npm install -g @openai/codex
# 方式二：Homebrew 安装（仅 macOS/Linux）
brew install –cask codex
💡 国内用户如果 npm 安装慢，可以使用淘宝镜像：
npm install -g @openai/codex –registry=https://registry.npmmirror.com
2.2 验证安装
# 检查版本
codex –version
# 输出示例：codex 0.130.0 ✓
看到版本号就说明安装成功了。
2.3 登录 ChatGPT 账号
# 启动 Codex
codex
终端会提示选择登录方式：
1. Sign in with ChatGPT (推荐)
2. Use API Key
- 方式一（推荐）：输入 1，通过浏览器授权登录你的 ChatGPT 账号。Plus/Pro 用户可享受更高的使用额度。
- 方式二：输入你的 OpenAI API Key。
💡 如果你有 ChatGPT Plus/Pro 订阅，推荐使用方式一登录，可以享受更好的使用体验。
三、国内用户配置（核心）
3.1 为什么需要配置？
Codex CLI 默认调用 api.openai.com，中国大陆无法直连。需要将 API 端点替换为兼容 OpenAI 协议的国内服务。
3.2 配置文件位置
Codex 的配置文件位于：~/.codex/config.toml
3.3 推荐国内中转平台
| 七牛云 AI | https://api.qnaigc.com/v1 | DeepSeek V4、Claude、Kimi、GLM | 多模型统一 Key |
| 硅基流动 | https://api.siliconflow.cn/v1 | 多家开源模型 | 按量付费，有免费额度 |
| DeepSeek 官方 | https://api.deepseek.com/v1 | DeepSeek 系列 | 官方源，稳定性高 |
| 阿里百炼 | https://dashscope.aliyuncs.com/compatible-mode/v1 | Qwen3 系列 | 中文能力强 |
3.4 配置示例
编辑 ~/.codex/config.toml：
# 国内配置示例：使用七牛云 AI
openai_base_url = "https://api.qnaigc.com/v1"
# 选择使用的模型
model = "deepseek-chat"
# 模型提供商配置
[model_providers.deepseek]
name = "deepseek"
env_key = "DEEPSEEK_API_KEY"
⚠️ 关键提醒：Codex 新版本使用 Responses API，很多中转平台只支持 Chat Completions 协议。如果能连上但跑不起来，很可能是 API 协议不兼容，建议多试几家平台。
3.5 环境变量配置
在 ~/.bashrc 或 ~/.zshrc 中添加：
# DeepSeek 示例
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"
# 阿里百炼示例
export BAILIAN_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"
生效配置：
source ~/.bashrc # 或 source ~/.zshrc
四、实战演示
4.1 基础使用
进入项目目录，启动 Codex：
cd your-project
codex
进入交互式 TUI 界面后，可以直接用自然语言描述需求：
> 帮我创建一个用户登录系统，包含注册和登录功能
Codex 会自动：
4.2 非交互式执行
适合 CI/CD 集成或快速任务：
# 单条命令执行
codex exec "修复 src/auth.py 中的登录验证漏洞"
# 指定模型执行
codex exec –model gpt-5.3-codex "优化这段代码的性能"
4.3 SDK 集成（Node.js）
如果你想在项目中使用 Codex SDK：
npm install @openai/codex-sdk
基础示例：
import { Codex } from "@openai/codex-sdk";
const codex = new Codex();
const thread = codex.startThread();
// 让 Codex 诊断测试失败并提出修复方案
const turn = await thread.run("Diagnose the test failure and propose a fix");
console.log(turn.finalResponse);
console.log(turn.items);
// 继续对话
const nextTurn = await thread.run("Implement the fix");
带结构的输出示例：
const schema = {
type: "object",
properties: {
summary: { type: "string" },
status: { type: "string", enum: ["ok", "action_required"] },
},
required: ["summary", "status"],
additionalProperties: false,
};
const turn = await thread.run("Summarize repository status", {
outputSchema: schema,
});
五、踩坑指南
坑1：codex 命令找不到
问题表现：
codex: command not found
解决方案：
# 重新安装
npm install -g @openai/codex
# 检查 npm 全局路径
npm config get prefix
# 确保路径在 PATH 中
echo $PATH
Windows 用户建议直接使用 Codex App，避免 CLI 环境配置问题。
坑2：登录授权后仍然失败
问题表现：浏览器授权成功，但终端提示失败。
解决方案：
坑3：国内模型配置后提示找不到
问题表现：配置了环境变量，但 Codex 仍然提示找不到 API Key。
解决方案：
⚠️ Codex 新版本使用 Responses API，很多平台还没适配。能跑就用，跑不起来就换平台。
坑4：长会话性能下降
问题表现：对话时间长了，Codex 开始"变笨"。
解决方案：
- 会话 1：理解代码库结构 → 写入 AGENTS.md
- 会话 2：基于 AGENTS.md 实现功能
- 会话 3：独立验证
坑5：Computer Use 功能不可用
问题表现：想用 Codex 操作电脑，但提示 Computer Use 不可用。
解决方案：Computer Use 目前只支持 macOS 15+。如果你的系统版本低于 macOS 15，这个功能将无法使用。
六、进阶配置：AGENTS.md
Codex 支持通过 AGENTS.md 文件配置项目级别的行为规范。这是一个非常强大的功能。
基本结构
# 项目名
## 工作流
– 每次代码变更后运行 `npm test`
– 使用 Conventional Commits (feat:, fix:, refactor:)
– 完成后通过 `gh pr create` 创建 PR
## 技术栈
– Node.js 18+, Express 4.x, PostgreSQL 16
– 测试: Jest + React Testing Library
## 代码规范
– 组件文件不超过 300 行，超过则拆分
– 禁止使用 `any` 类型
– 所有公开 API 必须有 JSDoc 注释
## 必须运行的检查
修改完成后，按顺序运行：
1. `npm run lint` – Linter 修复
2. `npm test` – 运行相关测试
3. `npm run typecheck` – 类型检查
配置原则
| 保持简短 | 控制在 100 行以内，硬上限 300 行 |
| 精准 | 只写 Codex 可能忽略的信息 |
| 拆分 | 规则太多时，拆分到子目录的 AGENTS.md |
七、总结
本文带你完成了以下内容：
| ✅ 环境准备 | Node.js、npm、Git 安装与版本检查 |
| ✅ 安装 Codex CLI | npm/Homebrew 两种方式 |
| ✅ 国内用户配置 | 七牛云/硅基流动/DeepSeek/阿里百炼 |
| ✅ 实战演示 | 交互式/非交互式/SDK 三种使用方式 |
| ✅ 踩坑指南 | 5 个常见问题及解决方案 |
| ✅ 进阶配置 | AGENTS.md 项目规范配置 |
Codex CLI 最新数据（截至 2026-05）：
- 📦 最新版本：v0.130.0
- ⭐ GitHub Stars：83,200+
- 🛠️ 支持平台：macOS / Linux / Windows(WSL2)
- 💡 主要特性：Responses API、Computer Use、90+ 插件
如果你在安装过程中遇到任何问题，欢迎在评论区留言！觉得有用的话，点个赞、收个藏，你的支持是我持续输出的动力 🙏
相关阅读：
- 《OpenClaw零失败安装指南：前置检查+安装验证+国内镜像，全流程教学》
- 《OpenAI_Codex免费移动端双线出击_20260516》
