⏱️ 阅读时间：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 推荐国内中转平台

服务商 Base URL 支持模型 特点
七牛云 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 会自动：

  1. 分析项目结构
  2. 生成代码文件
  3. 写入磁盘
  4. 运行测试验证

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：登录授权后仍然失败

问题表现：浏览器授权成功，但终端提示失败。

解决方案：

  1. 检查网络连接
  2. 清除浏览器缓存后重试
  3. 换用 API Key 方式登录
  4. 执行 codex logout 后重新登录

坑3：国内模型配置后提示找不到

问题表现：配置了环境变量，但 Codex 仍然提示找不到 API Key。

解决方案：

  1. Windows 用户：配置完环境变量后，必须完全退出 Codex 并重启（不是刷新，是完全退出再打开）
  2. 如果还不行，试试重启电脑
  3. 检查 config.toml 中的 env_key 名称是否与环境变量名匹配

⚠️ Codex 新版本使用 Responses API，很多平台还没适配。能跑就用，跑不起来就换平台。

坑4：长会话性能下降

问题表现：对话时间长了，Codex 开始"变笨"。

解决方案：

  1. 分段任务：复杂任务拆分成多个小任务，每个任务开启新会话
  2. 使用 AGENTS.md：将关键上下文写入项目根目录的 AGENTS.md 文件
  3. 会话刷新策略：
    • 会话 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+ 插件

如果你在安装过程中遇到任何问题，欢迎在评论区留言！觉得有用的话，点个赞、收个藏，你的支持是我持续输出的动力 🙏

相关阅读：

# node.js
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

AI 时代前端生存与破局：从焦虑到核心竞争力构建

avatar AtomGit开源社区
cover

IDEA 不只接 Claude 和 Codex：本地模型和第三方 API 也能直接用

avatar AtomGit开源社区
cover

Java并发编程:ConcurrentLinkedQueue设计与实现

avatar AtomGit开源社区