从零到高效开发详解Codex本地安装与使用的完全指南

目录

• 前言
• 一、Codex 是什么？核心架构一图看懂
• 二、安装前的环境准备
• 2.1 系统要求
• 2.2 安装 Node.js（Windows）
• 三、安装 Codex CLI
• 3.1 Windows 平台安装
• 3.2 macOS 平台安装
• 3.3 Linux 平台安装
• 3.4 安装流程图
• 四、配置与认证
• 4.1 账号认证（官方 API 方式）
• 4.2 国内配置（使用第三方兼容端点）
• 4.3 配置架构图
• 五、基础操作：从第一条指令开始
• 5.1 启动 Codex
• 5.2 第一个任务：生成代码
• 5.3 常用命令速查
• 5.4 斜杠命令速查
• 5.5 Codex 基础操作流程图
• 六、核心模式：按场景切换，效率拉满
• 6.1 交互式 TUI 模式（推荐日常使用）
• 6.2 非交互式批量执行模式
• 6.3 项目分析模式
• 6.4 三种核心模式对比
• 七、安全沙盒：让 Codex 更“可控”
• 7.1 沙盒模式详解
• 7.2 审批策略
• 7.3 沙盒决策流程图
• 八、AGENTS.md：让 Codex 记住你的项目
• 8.1 什么是 AGENTS.md？
• 8.2 文件示例
• 8.3 多级配置优先级
• 九、MCP 扩展：无限可能
• 十、资源监控与预算控制
• 10.1 查看使用情况
• 10.2 设置预算限制
• 十一、常见问题与避坑指南
• 11.1 平台相关问题
• 11.2 配置与认证问题
• 11.3 使用与安全问题
• 十二、进阶技巧
• 12.1 Codex vs Claude Code 对比
• 12.2 集成到 CI/CD
• 12.3 提升 Codex “听话”程度的提示工程
• 总结

OpenAI 出品的终端 AI 编程智能体，让 AI 助手在你的电脑本地运行

Codex 是 OpenAI 推出的开源 AI 编程智能体，用 Rust 编写，速度快、效率高，能够读取并修改代码文件、执行终端命令，并在终端中完成多步骤的自主开发任务。官方 GitHub 仓库已获得超过 83,200 星标，与 Claude Code 并列为当前最热门的终端 AI 编程工具。

本文将手把手带你完成 Codex 的本地安装与配置，涵盖 Windows（含 WSL2）、macOS、Linux 三大平台，并深入讲解核心功能、安全配置和高效使用技巧。全文配以 Mermaid 流程图 和架构图，让复杂概念一目了然。

下图展示了 Codex CLI 的核心架构与工作流程，后续内容将围绕这个框架展开：

核心要点：

• 本地运行：Codex CLI 完全运行在你的电脑上，不需要将代码上传到云端。
• 多后端支持：可以通过 openai_base_url 配置指向任意兼容 OpenAI 协议的 API 端点，包括第三方网关或本地部署的 LLM。
• 安全沙盒：默认启用的沙盒机制严格控制文件写入范围、命令执行权限和网络访问。

操作系统	支持情况	推荐方式
Windows 10/11	✅ 支持（实验性）	WSL2（最稳定）或 PowerShell
macOS	✅ 完整支持	npm 或 Homebrew
Linux	✅ 完整支持	npm 或 二进制包
硬件	建议 4核8G内存以上	复杂项目需要更多资源
Node.js	≥ 22（硬性要求）	低于 22 版本无法安装

重要：Node.js 版本要求 22 或更高，这是官方明确的最低版本要求。

账号要求：需要 ChatGPT Plus/Pro/Team/Business/Edu 订阅，免费账号无法直接使用官方 API。若没有订阅，可使用第三方兼容 API 端点替代，详见下文“国内配置”部分。

方式一：官网下载（推荐）

1. 打开浏览器访问 https://nodejs.org/
2. 点击“LTS”版本下载（版本号大于 22，推荐长期支持版本）
3. 双击 .msi 文件按向导完成安装

方式二：使用包管理器

# 使用 Chocolatey
choco install nodejs
# 或使用 Scoop
scoop install nodejs

验证安装

打开 PowerShell 或 CMD，输入：

node --version   # 应显示 v22.x.x 或更高
npm --version

如果显示版本号，说明安装成功。

Windows 上有两种安装方式，推荐使用 WSL2 获得最佳体验。

方式一：WSL2（强烈推荐）

Codex 官方明确表示 Windows 支持仍为实验性，WSL2 是目前最稳定、兼容性最好的方案。

第一步：安装 WSL2

以管理员身份打开 PowerShell，执行：

wsl --install

安装完成后重启电脑，系统会自动进入 Ubuntu 初始化，设置用户名和密码即可。

第二步：在 WSL2 中安装 Node.js

# 安装 nvm（Node 版本管理工具）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载配置
source ~/.bashrc

# 安装 Node.js 22
nvm install 22

# 验证安装
node -v   # 应显示 v22.x.x
npm -v

为什么不用 apt install nodejs？Ubuntu 自带仓库的 Node.js 版本通常较旧，低于官方要求的 22，使用 nvm 可以精确安装所需版本。

第三步：安装 Codex CLI

npm install -g @openai/codex
codex --version   # 验证安装

重要：项目目录放置位置

项目文件必须放在 Linux 文件系统中，不要放在 /mnt/c/ 路径下。跨文件系统访问会严重影响性能，Git、测试等操作都会变慢：

# ✅ 正确：放在 Linux home 目录下
mkdir -p ~/code && cd ~/code
git clone your-repo

# ❌ 错误：放在 Windows 盘符中
cd /mnt/c/Users/xxx/project   # 性能极差！

VS Code + WSL 扩展配置：

安装 VS Code 的 WSL 扩展，然后在 WSL 终端中直接运行：

cd ~/code/my-project
code .   # 自动以 WSL 模式打开 VS Code

这样 VS Code 的内置终端也是 WSL 环境，Codex 可以直接使用。

方式二：原生 Windows（PowerShell）

如果不想使用 WSL，也可以在 PowerShell 中直接安装：

npm install -g @openai/codex
codex --version

原生 Windows 版本使用实验性的 Windows 沙盒机制（通过 Restricted Token + 文件系统 ACL 限制写入范围），实际使用中偶尔会出现权限问题，Win10 比 Win11 更容易出问题。

# 方式一：npm（通用）
npm install -g @openai/codex

# 方式二：Homebrew（推荐）
brew install --cask codex

# 验证安装
codex --version

# npm 安装
npm install -g @openai/codex

# 或直接从 GitHub 下载二进制包（网络受限时推荐）
curl -L https://github.com/openai/codex/releases/download/rust-v0.131.0/codex-x86_64-unknown-linux-musl.tar.gz | tar -xz
sudo mv codex /usr/local/bin/

# 验证安装
codex --version

推荐使用 musl 静态链接版本，不依赖系统 glibc，兼容性最佳。

如果你有 ChatGPT Plus/Pro 订阅，可以使用官方 API：

codex login

运行后会打开浏览器窗口完成授权。注意：授权过程中不要开启代理或海外环境。

对于国内用户，直接访问 OpenAI API 存在网络限制。解决方案是将 openai_base_url 指向国内兼容端点，Codex 的其他功能完全不变。

第一步：创建配置目录和文件

mkdir -p ~/.codex

第二步：创建/编辑 ~/.codex/config.toml

#:schema https://developers.openai.com/codex/config-schema.json

# 指向国内兼容端点（这里以七牛云为例）
openai_base_url = "https://api.qnaigc.com/v1"

# 选择的模型（以服务商实际名称为准）
model = "deepseek-v4-pro"

# 沙盒模式：允许修改当前项目目录的文件
sandbox_mode = "workspace-write"

# 关闭联网搜索（国内连接 Bing Search API 不稳定）
web_search = "disabled"

# 审批策略：非破坏性命令自动执行，不确定时暂停确认
approval_policy = "on-request"

国内兼容端点可通过七牛云、88code 等 AI 网关服务申请，新用户通常有免费额度。

第三步：设置 API Key 环境变量

# PowerShell（Windows）
[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY','你的API_KEY','User')

# WSL / Linux / macOS（zsh 用户）
echo 'export OPENAI_API_KEY="你的API_KEY"' >> ~/.zshrc
source ~/.zshrc

# bash 用户
echo 'export OPENAI_API_KEY="你的API_KEY"' >> ~/.bashrc
source ~/.bashrc

第四步：验证配置

从 v0.131.0 版本开始，Codex 提供了配置验证命令：

codex doctor

该命令会检查配置文件中各项参数是否正确，并给出具体建议。

进入你的项目目录，直接运行：

cd your-project-folder
codex

这将启动交互式对话环境，你可以直接输入自然语言指令让 Codex 执行任务。

在 Codex 交互环境中输入：

用 Python 写一个快速的冒泡排序算法

你会看到 Codex 生成完整代码并附带解释。

命令	说明
codex	启动交互式对话
codex tui	启动终端 UI 界面
codex exec --file tasks.toml	批量执行任务
codex login	登录认证
codex doctor	检查配置是否正确
codex --version	查看版本
codex update	更新到最新版本
/help	查看所有可用命令
/model <模型名>	切换模型
/clear	清空当前对话上下文
/exit	退出

命令	功能
/file read <path>	读取文件内容
/file write <path> <content>	写入文件
/run <command>	执行终端命令
/analyze	分析当前项目结构
/sandbox <mode>	切换沙盒模式
/save <name>	保存当前会话
/load <name>	加载历史会话

启动带有 UI 界面的交互模式：

codex tui

在此模式下，你可以进行多轮对话，Codex 会记住上下文。例如：

> 生成一个 Python 快速排序实现
[生成代码]
> 优化为递归版本并添加类型注解
[优化代码]
> 生成对应的单元测试用例
[生成测试代码]

适合批量处理固定任务。创建 tasks.toml 文件：

[[tasks]]
name = "生成用户模型"
prompt = "使用 TypeScript 编写一个包含 CRUD 方法的 User 模型"
output = "models/user.ts"

[[tasks]]
name = "优化 SQL 查询"
prompt = "优化以下慢查询：SELECT * FROM orders WHERE status='pending'"
output = "queries/optimized.sql"

然后执行：

codex exec --file tasks.toml --output results/

在项目根目录运行：

codex /analyze

Codex 会扫描整个代码库并建立索引，之后你可以提问：“这个项目中哪些函数缺少错误处理？”

模式	适用场景	启动命令
交互式 TUI	日常编码、探索性任务	codex tui
批量执行	自动化处理重复性任务	codex exec --file tasks.toml
项目分析	理解大型遗留系统	codex /analyze

Codex 内置了安全沙盒机制，严格限制 Codex 对系统的访问权限：

模式	文件写入	网络访问	命令执行	适用场景
read-only	❌ 只读	❌ 禁止	❌ 禁止	仅代码分析和解释
workspace-write	✅ 仅工作区	✅ 允许	⚠️ 需审批	日常开发（推荐）
danger-full-access	✅ 全盘	✅ 允许	✅ 直接执行	自动化脚本（谨慎使用）

配置方式（在 ~/.codex/config.toml 中）：

sandbox_mode = "workspace-write"

控制哪些操作需要用户手动确认：

策略	说明
always	所有操作都需要确认（最安全）
on-request	非破坏性操作自动执行，不确定时暂停确认（推荐）
never	所有操作自动执行（效率最高，风险最大）

approval_policy = "on-request"

Codex 在项目根目录中使用 AGENTS.md 作为项目级记忆文件，类似 Claude Code 的 CLAUDE.md。Codex 会在每次会话开始时自动读取该文件，从而获得项目特定的指令和约定。

在项目根目录创建 AGENTS.md：

# AGENTS.md - 项目全局指令
## 项目概述
- 项目名称：MyWebApp
- 技术栈：TypeScript + React + Node.js
- 代码风格：ESLint + Prettier，2 空格缩进
## 常用命令
- 启动开发服务器：`npm run dev`
- 运行测试：`npm test`
- 类型检查：`npm run type-check`
## Codex 行为约定
- 所有组件文件必须包含 PropTypes 或 TypeScript 类型定义
- API 调用必须包含错误处理
- CSS 使用 Tailwind，不要写内联样式
## 禁止事项
- 不要在代码中使用 `any` 类型
- 不要直接修改 `node_modules` 中的文件

Codex 会按以下顺序合并配置（后者覆盖前者）：

1. ~/.codex/AGENTS.md（全局）
2. <项目根目录>/AGENTS.md（项目级，最优先）

Codex 支持 MCP（Model Context Protocol） 协议，可以集成第三方工具扩展功能，例如：

• Context7：获取最新技术文档上下文
• Fetch：从网页抓取内容
• Sequential Thinking：复杂任务的分步推理

配置示例（在 config.toml 中添加）：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp", "--api-key", "你的_API_Key"]

配置后，Codex 可以主动查询最新文档，回答基于实时文档的问题。

codex usage                 # 显示总用量
codex usage --today         # 今日用量
codex usage --session       # 当前会话用量

在 ~/.codex/config.toml 中添加：

budget_limit = 10.0
budget_alert_threshold = 0.8

当费用超过 8 美元时给出警告，超过 10 美元则自动拒绝新请求。

问题	原因	解决方案
WSL2 中 codex login 弹不出浏览器	WSL2 默认无图形界面	复制终端显示的 URL，手动在 Windows 浏览器中打开
Node.js 版本过低	低于 22 不被支持	使用 nvm 更新：nvm install 22 && nvm use 22
WSL2 访问 /mnt/c/ 项目极慢	跨文件系统 IO 性能差	将项目放在 ~/code/ 等 Linux 目录下
原生 Windows 出现权限问题	Windows 沙盒机制尚不稳定	切换到 WSL2 方案

问题	原因	解决方案
运行 codex 提示 command not found	npm 全局安装路径未加入 PATH	重启终端，或手动添加 %APPDATA%npm 到系统 PATH
国内无法连接 OpenAI API	网络限制	配置第三方兼容端点，参考 4.2 节
授权后提示 No Active Subscription	账户无有效订阅	确保使用 Plus/Pro 账户；或改用第三方 API
配置不生效	config.toml 格式错误	运行 codex doctor 检查

问题	原因	解决方案
Codex 误删重要文件	权限过于宽松	使用 workspace-write + on-request 模式
Codex 连接第三方 API 失败	网络代理设置问题	检查防火墙和代理规则，确保可访问配置的 base_url
沙盒模式限制过严无法写入	模式设置不当	将 sandbox_mode 设为 workspace-write

特性	Codex CLI	Claude Code
开发商	OpenAI	Anthropic
语言实现	Rust	TypeScript
配置格式	TOML	JSON / Markdown
项目记忆文件	AGENTS.md	CLAUDE.md
沙盒机制	✅ 内置，完善	✅ 有限支持
Windows 支持	实验性，推荐 WSL2	实验性
开源许可	Apache-2.0	闭源
GitHub Stars	83k+	124k+

在 GitHub Actions 中使用 Codex：

- name: Run Codex quality check
  run: |
    npm install -g @openai/codex
    codex exec --file ci-tasks.toml

• 明确约束：“只给出代码，不要解释” / “给出三种方案并排序”
• 提供示例：在 AGENTS.md 中放入期望的输入/输出对
• 分步要求：“先分析问题，再给出解决方案，最后写代码”
• 要求验证：“完成后运行测试验证正确性”

本文从零开始，带你完成了 Codex 在多平台（Windows/WSL2、macOS、Linux）的安装与配置，详细讲解了核心功能、安全沙盒、AGENTS.md 项目记忆、三种工作模式以及常见问题的避坑指南。

快速上手指南：

1. 安装 Node.js ≥ 22
2. Windows 用户优先安装 WSL2
3. npm install -g @openai/codex
4. 配置 ~/.codex/config.toml（国内用户需要指向兼容端点）
5. cd your-project && codex
6. 输入第一条指令，开始使用

以上就是从零到高效开发详解Codex本地安装与使用的完全指南的详细内容，更多关于Codex安装与使用教学的资料请关注风君子博客其它相关文章！