OpenAI 出品的终端 AI 编程智能体，让 AI 助手在你的电脑本地运行
前言
Codex 是 OpenAI 推出的开源 AI 编程智能体，用 Rust 编写，速度快、效率高，能够读取并修改代码文件、执行终端命令，并在终端中完成多步骤的自主开发任务。官方 GitHub 仓库已获得超过 83,200 星标，与 Claude Code 并列为当前最热门的终端 AI 编程工具。
本文将手把手带你完成 Codex 的本地安装与配置，涵盖 Windows（含 WSL2）、macOS、Linux 三大平台，并深入讲解核心功能、安全配置和高效使用技巧。全文配以 Mermaid 流程图 和架构图，让复杂概念一目了然。
一、Codex 是什么？核心架构一图看懂
下图展示了 Codex CLI 的核心架构与工作流程，后续内容将围绕这个框架展开：
核心要点：
- 本地运行：Codex CLI 完全运行在你的电脑上，不需要将代码上传到云端。
- 多后端支持：可以通过 openai_base_url 配置指向任意兼容 OpenAI 协议的 API 端点，包括第三方网关或本地部署的 LLM。
- 安全沙盒：默认启用的沙盒机制严格控制文件写入范围、命令执行权限和网络访问。
二、安装前的环境准备
2.1 系统要求
| 操作系统 | 支持情况 | 推荐方式 |
|---|---|---|
| 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 端点替代，详见下文“国内配置”部分。
2.2 安装 Node.js（Windows）
方式一：官网下载（推荐）
方式二：使用包管理器
|
1 2 3 4 |
# 使用 Chocolatey choco install nodejs # 或使用 Scoop scoop install nodejs |
验证安装
打开 PowerShell 或 CMD，输入：
|
1 2 |
node --version # 应显示 v22.x.x 或更高 npm --version |
如果显示版本号，说明安装成功。
三、安装 Codex CLI
3.1 Windows 平台安装
Windows 上有两种安装方式，推荐使用 WSL2 获得最佳体验。
方式一：WSL2（强烈推荐）
Codex 官方明确表示 Windows 支持仍为实验性，WSL2 是目前最稳定、兼容性最好的方案。
第一步：安装 WSL2
以管理员身份打开 PowerShell，执行：
|
1 |
wsl --install |
安装完成后重启电脑，系统会自动进入 Ubuntu 初始化，设置用户名和密码即可。
第二步：在 WSL2 中安装 Node.js
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# 安装 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
|
1 2 |
npm install -g @openai/codex codex --version # 验证安装 |
重要：项目目录放置位置
项目文件必须放在 Linux 文件系统中，不要放在 /mnt/c/ 路径下。跨文件系统访问会严重影响性能，Git、测试等操作都会变慢：
|
1 2 3 4 5 6 |
# ? 正确：放在 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 终端中直接运行：
|
1 2 |
cd ~/code/my-project code . # 自动以 WSL 模式打开 VS Code |
这样 VS Code 的内置终端也是 WSL 环境，Codex 可以直接使用。
方式二：原生 Windows（PowerShell）
如果不想使用 WSL，也可以在 PowerShell 中直接安装：
|
1 2 |
npm install -g @openai/codex codex --version |
原生 Windows 版本使用实验性的 Windows 沙盒机制（通过 Restricted Token + 文件系统 ACL 限制写入范围），实际使用中偶尔会出现权限问题，Win10 比 Win11 更容易出问题。
3.2 macOS 平台安装
|
1 2 3 4 5 6 7 8 |
# 方式一：npm（通用） npm install -g @openai/codex
# 方式二：Homebrew（推荐） brew install --cask codex
# 验证安装 codex --version |
3.3 Linux 平台安装
|
1 2 3 4 5 6 7 8 9 |
# 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，兼容性最佳。
3.4 安装流程图
四、配置与认证
4.1 账号认证（官方 API 方式）
如果你有 ChatGPT Plus/Pro 订阅，可以使用官方 API：
|
1 |
codex login |
运行后会打开浏览器窗口完成授权。注意：授权过程中不要开启代理或海外环境。
4.2 国内配置（使用第三方兼容端点）
对于国内用户，直接访问 OpenAI API 存在网络限制。解决方案是将 openai_base_url 指向国内兼容端点，Codex 的其他功能完全不变。
第一步：创建配置目录和文件
|
1 |
mkdir -p ~/.codex |
第二步：创建/编辑 ~/.codex/config.toml
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
#: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 环境变量
|
1 2 3 4 5 6 7 8 9 10 |
# 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 提供了配置验证命令：
|
1 |
codex doctor |
该命令会检查配置文件中各项参数是否正确，并给出具体建议。
4.3 配置架构图
五、基础操作：从第一条指令开始
5.1 启动 Codex
进入你的项目目录，直接运行：
|
1 2 |
cd your-project-folder codex |
这将启动交互式对话环境，你可以直接输入自然语言指令让 Codex 执行任务。
5.2 第一个任务：生成代码
在 Codex 交互环境中输入：
|
1 |
用 Python 写一个快速的冒泡排序算法 |
你会看到 Codex 生成完整代码并附带解释。
5.3 常用命令速查
| 命令 | 说明 |
|---|---|
| codex | 启动交互式对话 |
| codex tui | 启动终端 UI 界面 |
| codex exec --file tasks.toml | 批量执行任务 |
| codex login | 登录认证 |
| codex doctor | 检查配置是否正确 |
| codex --version | 查看版本 |
| codex update | 更新到最新版本 |
| /help | 查看所有可用命令 |
| /model <模型名> | 切换模型 |
| /clear | 清空当前对话上下文 |
| /exit | 退出 |
5.4 斜杠命令速查
| 命令 | 功能 |
|---|---|
| /file read <path> | 读取文件内容 |
| /file write <path> <content> | 写入文件 |
| /run <command> | 执行终端命令 |
| /analyze | 分析当前项目结构 |
| /sandbox <mode> | 切换沙盒模式 |
| /save <name> | 保存当前会话 |
| /load <name> | 加载历史会话 |
5.5 Codex 基础操作流程图
六、核心模式：按场景切换，效率拉满
6.1 交互式 TUI 模式（推荐日常使用）
启动带有 UI 界面的交互模式：
|
1 |
codex tui |
在此模式下，你可以进行多轮对话，Codex 会记住上下文。例如：
|
1 2 3 4 5 6 |
> 生成一个 Python 快速排序实现 [生成代码] > 优化为递归版本并添加类型注解 [优化代码] > 生成对应的单元测试用例 [生成测试代码] |
6.2 非交互式批量执行模式
适合批量处理固定任务。创建 tasks.toml 文件：
|
1 2 3 4 5 6 7 8 9 |
[[tasks]] name = "生成用户模型" prompt = "使用 TypeScript 编写一个包含 CRUD 方法的 User 模型" output = "models/user.ts"
[[tasks]] name = "优化 SQL 查询" prompt = "优化以下慢查询：SELECT * FROM orders WHERE status='pending'" output = "queries/optimized.sql" |
然后执行：
|
1 |
codex exec --file tasks.toml --output results/ |
6.3 项目分析模式
在项目根目录运行：
|
1 |
codex /analyze |
Codex 会扫描整个代码库并建立索引，之后你可以提问：“这个项目中哪些函数缺少错误处理？”
6.4 三种核心模式对比
| 模式 | 适用场景 | 启动命令 |
|---|---|---|
| 交互式 TUI | 日常编码、探索性任务 | codex tui |
| 批量执行 | 自动化处理重复性任务 | codex exec --file tasks.toml |
| 项目分析 | 理解大型遗留系统 | codex /analyze |
七、安全沙盒：让 Codex 更“可控”
7.1 沙盒模式详解
Codex 内置了安全沙盒机制，严格限制 Codex 对系统的访问权限：
| 模式 | 文件写入 | 网络访问 | 命令执行 | 适用场景 |
|---|---|---|---|---|
| read-only | ? 只读 | ? 禁止 | ? 禁止 | 仅代码分析和解释 |
| workspace-write | ? 仅工作区 | ? 允许 | ?? 需审批 | 日常开发（推荐） |
| danger-full-access | ? 全盘 | ? 允许 | ? 直接执行 | 自动化脚本（谨慎使用） |
配置方式（在 ~/.codex/config.toml 中）：
|
1 |
sandbox_mode = "workspace-write" |
7.2 审批策略
控制哪些操作需要用户手动确认：
| 策略 | 说明 |
|---|---|
| always | 所有操作都需要确认（最安全） |
| on-request | 非破坏性操作自动执行，不确定时暂停确认（推荐） |
| never | 所有操作自动执行（效率最高，风险最大） |
|
1 |
approval_policy = "on-request" |
7.3 沙盒决策流程图
八、AGENTS.md：让 Codex 记住你的项目
8.1 什么是 AGENTS.md？
Codex 在项目根目录中使用 AGENTS.md 作为项目级记忆文件，类似 Claude Code 的 CLAUDE.md。Codex 会在每次会话开始时自动读取该文件，从而获得项目特定的指令和约定。
8.2 文件示例
在项目根目录创建 AGENTS.md：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
# 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` 中的文件 |
8.3 多级配置优先级
Codex 会按以下顺序合并配置（后者覆盖前者）：
- ~/.codex/AGENTS.md（全局）
- <项目根目录>/AGENTS.md（项目级，最优先）
九、MCP 扩展：无限可能
Codex 支持 MCP（Model Context Protocol） 协议，可以集成第三方工具扩展功能，例如：
- Context7：获取最新技术文档上下文
- Fetch：从网页抓取内容
- Sequential Thinking：复杂任务的分步推理
配置示例（在 config.toml 中添加）：
|
1 2 3 |
[mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp", "--api-key", "你的_API_Key"] |
配置后，Codex 可以主动查询最新文档，回答基于实时文档的问题。
十、资源监控与预算控制
10.1 查看使用情况
|
1 2 3 |
codex usage # 显示总用量 codex usage --today # 今日用量 codex usage --session # 当前会话用量 |
10.2 设置预算限制
在 ~/.codex/config.toml 中添加：
|
1 2 |
budget_limit = 10.0 budget_alert_threshold = 0.8 |
当费用超过 8 美元时给出警告，超过 10 美元则自动拒绝新请求。
十一、常见问题与避坑指南
11.1 平台相关问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 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 方案 |
11.2 配置与认证问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 运行 codex 提示 command not found | npm 全局安装路径未加入 PATH | 重启终端，或手动添加 %APPDATA%\npm 到系统 PATH |
| 国内无法连接 OpenAI API | 网络限制 | 配置第三方兼容端点，参考 4.2 节 |
| 授权后提示 No Active Subscription | 账户无有效订阅 | 确保使用 Plus/Pro 账户；或改用第三方 API |
| 配置不生效 | config.toml 格式错误 | 运行 codex doctor 检查 |
11.3 使用与安全问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| Codex 误删重要文件 | 权限过于宽松 | 使用 workspace-write + on-request 模式 |
| Codex 连接第三方 API 失败 | 网络代理设置问题 | 检查防火墙和代理规则，确保可访问配置的 base_url |
| 沙盒模式限制过严无法写入 | 模式设置不当 | 将 sandbox_mode 设为 workspace-write |
十二、进阶技巧
12.1 Codex vs Claude Code 对比
| 特性 | Codex CLI | Claude Code |
|---|---|---|
| 开发商 | OpenAI | Anthropic |
| 语言实现 | Rust | TypeScript |
| 配置格式 | TOML | JSON / Markdown |
| 项目记忆文件 | AGENTS.md | CLAUDE.md |
| 沙盒机制 | ? 内置，完善 | ? 有限支持 |
| Windows 支持 | 实验性，推荐 WSL2 | 实验性 |
| 开源许可 | Apache-2.0 | 闭源 |
| GitHub Stars | 83k+ | 124k+ |
12.2 集成到 CI/CD
在 GitHub Actions 中使用 Codex：
|
1 2 3 4 |
- name: Run Codex quality check run: | npm install -g @openai/codex codex exec --file ci-tasks.toml |
12.3 提升 Codex “听话”程度的提示工程
- 明确约束：“只给出代码，不要解释” / “给出三种方案并排序”
- 提供示例：在 AGENTS.md 中放入期望的输入/输出对
- 分步要求：“先分析问题，再给出解决方案，最后写代码”
- 要求验证：“完成后运行测试验证正确性”
总结
本文从零开始，带你完成了 Codex 在多平台（Windows/WSL2、macOS、Linux）的安装与配置，详细讲解了核心功能、安全沙盒、AGENTS.md 项目记忆、三种工作模式以及常见问题的避坑指南。
快速上手指南：
- 安装 Node.js ≥ 22
- Windows 用户优先安装 WSL2
- npm install -g @openai/codex
- 配置 ~/.codex/config.toml（国内用户需要指向兼容端点）
- cd your-project && codex
- 输入第一条指令，开始使用
