Codex 安装与使用（2026最新版）

一、环境准备​

1.1 系统要求​

​

​

​

⚠️ Windows 用户注意：Codex CLI 暂时不支持原生 Windows，需要通过 WSL2 或使用 Codex App。​

​

1.2 环境检查​

二、安装步骤​

2.1 安装 Codex CLI​

​

​

Codex CLI 有两种安装方式，推荐方式一：​

​

代码块​

Plain Text

方式一：npm 安装（推荐）​

npm install -g @openai/codex​

​

方式二：Homebrew 安装（仅 macOS/Linux）​

brew install --cask codex​

​

​

​

​

💡 国内用户如果 npm 安装慢，可以使用淘宝镜像：​

​

代码块​

Plain Text

npm install -g @openai/codex --registry=https://registry.npmmirror.com​

​

​

2.2 验证安装​

​

代码块​

Plain Text

检查版本​

codex --version​

输出示例：codex 0.130.0 ✓​

​

看到版本号就说明安装成功了。​

2.3 登录 ChatGPT 账号​

​

代码块​

Plain Text

启动 Codex​

codex​

​

终端会提示选择登录方式：​

​

Sign in with ChatGPT (推荐)​

Use API Key​

一键获取完整项目代码​

1​

2​

方式一（推荐）：输入 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"​

一键获取完整项目代码​

toml​

​

1​

2​

3​

4​

5​

6​

7​

8​

9​

10​

⚠️ 关键提醒：Codex 新版本使用 Responses API，很多中转平台只支持 Chat Completions 协议。如果能连上但跑不起来，很可能是 API 协议不兼容，建议多试几家平台。​

​

3.5 环境变量配置​

在 ~/.bashrc 或 ~/.zshrc 中添加：​

​

DeepSeek 示例​

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"​

​

阿里百炼示例​

export BAILIAN_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"​

一键获取完整项目代码​

bash​

1​

2​

3​

4​

5​

生效配置：​

​

source ~/.bashrc # 或 source ~/.zshrc​

一键获取完整项目代码​

bash​

1​

四、实战演示​

4.1 基础使用​

进入项目目录，启动 Codex：​

​

cd your-project​

codex​

一键获取完整项目代码​

bash​

1​

2​

进入交互式 TUI 界面后，可以直接用自然语言描述需求：​

​

​

帮我创建一个用户登录系统，包含注册和登录功能​

一键获取完整项目代码​

1​

Codex 会自动：​

​

​

分析项目结构​

生成代码文件​

写入磁盘​

运行测试验证​

4.2 非交互式执行​

适合 CI/CD 集成或快速任务：​

​

单条命令执行​

codex exec "修复 src/auth.py 中的登录验证漏洞"​

​

指定模型执行​

codex exec --model gpt-5.3-codex "优化这段代码的性能"​

一键获取完整项目代码​

bash​

1​

2​

3​

4​

5​

4.3 SDK 集成（Node.js）​

如果你想在项目中使用 Codex SDK：​

​

npm install @openai/codex-sdk​

一键获取完整项目代码​

bash​

1​

基础示例：​

​

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");​

一键获取完整项目代码​

javascript​

​

1​

2​

3​

4​

5​

6​

7​

8​

9​

10​

11​

12​

13​

带结构的输出示例：​

​

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,​

});​

一键获取完整项目代码​

javascript​

​

1​

2​

3​

4​

5​

6​

7​

8​

9​

10​

11​

12​

13​

五、踩坑指南​

坑1：codex 命令找不到​

问题表现：​

​

codex: command not found​

一键获取完整项目代码​

1​

解决方案：​

​

重新安装​

npm install -g @openai/codex​

​

检查 npm 全局路径​

npm config get prefix​

​

确保路径在 PATH 中​

echo $PATH​

一键获取完整项目代码​

bash​

1​

2​

3​

4​

5​

6​

7​

8​

Windows 用户建议直接使用 Codex App，避免 CLI 环境配置问题。​

​

坑2：登录授权后仍然失败​

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

​

解决方案：​

​

检查网络连接​

清除浏览器缓存后重试​

换用 API Key 方式登录​

执行 codex logout 后重新登录​

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

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

​

解决方案：​

​

Windows 用户：配置完环境变量后，必须完全退出 Codex 并重启（不是刷新，是完全退出再打开）​

如果还不行，试试重启电脑​

检查 config.toml 中的 env_key 名称是否与环境变量名匹配​

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

​

坑4：长会话性能下降​

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

​

解决方案：​

​

分段任务：复杂任务拆分成多个小任务，每个任务开启新会话​

使用 AGENTS.md：将关键上下文写入项目根目录的 AGENTS.md 文件​

会话刷新策略：​

会话 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 注释​

​

必须运行的检查​

修改完成后，按顺序运行：​

npm run lint - Linter 修复​

npm test - 运行相关测试​

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+ 插件​

​