OpenAI Codex 安装部署指南：从零到跑通，2026最新版

⏱️ 阅读时间：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 系统要求

⚠️ 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-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-sudoapt-getinstall-ynodejs# Windows 用户：安装 WSL2 后在 Linux 环境操作wsl--install

二、安装步骤

2.1 安装 Codex CLI

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

# 方式一：npm 安装（推荐）npminstall-g@openai/codex# 方式二：Homebrew 安装（仅 macOS/Linux）brewinstall--caskcodex

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

npminstall-g@openai/codex--registry=https://registry.npmmirror.com

2.2 验证安装

# 检查版本codex--version# 输出示例：codex 0.130.0 ✓

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

2.3 登录 ChatGPT 账号

# 启动 Codexcodex

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

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 推荐国内中转平台

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 示例exportDEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"# 阿里百炼示例exportBAILIAN_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"

生效配置：

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

四、实战演示

4.1 基础使用

进入项目目录，启动 Codex：

cdyour-project codex

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

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

Codex 会自动：

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

4.2 非交互式执行

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

# 单条命令执行codexexec"修复 src/auth.py 中的登录验证漏洞"# 指定模型执行codexexec--modelgpt-5.3-codex"优化这段代码的性能"

4.3 SDK 集成（Node.js）

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

npminstall@openai/codex-sdk

基础示例：

import{Codex}from"@openai/codex-sdk";constcodex=newCodex();constthread=codex.startThread();// 让 Codex 诊断测试失败并提出修复方案constturn=awaitthread.run("Diagnose the test failure and propose a fix");console.log(turn.finalResponse);console.log(turn.items);// 继续对话constnextTurn=awaitthread.run("Implement the fix");

带结构的输出示例：

constschema={type:"object",properties:{summary:{type:"string"},status:{type:"string",enum:["ok","action_required"]},},required:["summary","status"],additionalProperties:false,};constturn=awaitthread.run("Summarize repository status",{outputSchema:schema,});

五、踩坑指南

坑1：codex 命令找不到

问题表现：

codex: command not found

解决方案：

# 重新安装npminstall-g@openai/codex# 检查 npm 全局路径npmconfig 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` - 类型检查

配置原则

七、总结

本文带你完成了以下内容：

Codex CLI 最新数据（截至 2026-05）：

• 📦 最新版本：v0.130.0
• ⭐ GitHub Stars：83,200+
• 🛠️ 支持平台：macOS / Linux / Windows(WSL2)
• 💡 主要特性：Responses API、Computer Use、90+ 插件

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

相关阅读：

• 《OpenClaw零失败安装指南：前置检查+安装验证+国内镜像，全流程教学》
• 《OpenAI_Codex免费移动端双线出击_20260516》