安装与首次运行：5 分钟从零到第一次对话

系列定位： 本文是 Codex 深度系列的第二篇。上一篇建立了产品全景认知，本篇目标是 5 分钟内完成安装并发出第一条指令——覆盖 CLI、App、IDE Extension 三种界面的跨平台 Quickstart。

官方参考： Quickstart · CLI Overview · App Overview · IDE Extension · Windows Setup · GitHub: openai/codex

前置条件速查

在开始安装之前，确认你的环境满足以下条件：

条件要求备注
操作系统macOS 12+ / Linux（glibc 2.31+）/ Windows（通过 WSL 2）Windows 原生支持为 Experimental，推荐 WSL
Node.js≥ 22（仅 npm 安装方式需要）Homebrew / 二进制方式无需 Node.js
ChatGPT 账号Plus / Pro / Business / Edu / Enterprise 任一Free/Go 用户可限时免费试用
可选：API Keyplatform.openai.com 生成仅在需要 API 按量计费时使用

一、Codex CLI 安装

CLI 是 Codex 的核心界面，也是 App 和 IDE Extension 的底层引擎。安装 CLI 即拥有完整的终端智能体能力。

方式 1：npm（推荐，跨平台）

Bash
# 全局安装
npm install -g @openai/codex
​
# 验证
codex --version
​
# 启动
codex
国内用户加速

如果 npm 下载缓慢，可使用镜像：npm install -g @openai/codex --registry=https://registry.npmmirror.com

方式 2：Homebrew（macOS / Linux）

Bash
# 安装（Cask 方式，无需 Node.js）
brew install --cask codex
​
# 验证
codex --version
追踪最新版本

社区建议使用 brew install --head codex 获取 HEAD 版本（最新 commit），适合想要第一时间体验新功能的用户。稳定版用 --cask 即可。

方式 3：二进制下载（无需包管理器）

从 GitHub Releases 下载预编译二进制：

平台文件名
macOS Apple Siliconcodex-aarch64-apple-darwin.tar.gz
macOS Intelcodex-x86_64-apple-darwin.tar.gz
Linux x86_64codex-x86_64-unknown-linux-musl.tar.gz
Bash
# 下载并解压（以 macOS ARM 为例）
tar -xzf codex-aarch64-apple-darwin.tar.gz
​
# 移入 PATH
sudo mv codex /usr/local/bin/
​
# 验证
codex --version

升级与卸载

Bash
# npm 升级
npm install -g @openai/codex@latest
​
# 内置升级命令
codex --upgrade
​
# npm 卸载
npm uninstall -g @openai/codex
​
# Homebrew 卸载
brew uninstall --cask codex

三种安装方式对比

方式需要 Node.js自动升级适用平台推荐场景
npm✅ ≥ 22npm update -gmacOS / Linux / WSL已有 Node.js 环境的开发者
Homebrew❌brew upgrademacOS / Linux不想安装 Node.js 的用户
二进制❌手动下载所有平台离线环境 / 定制化部署

二、Codex App 安装

Codex App 是桌面端的多智能体指挥中心，内置 Git Worktree 隔离、Skills、Automations 等高级功能。

macOS 安装

  1. 访问 chatgpt.com/codex 或 openai.com/codex 下载 DMG
  2. 打开 Codex.dmg，将应用拖入 Applications 文件夹
  3. 启动 Codex，使用 ChatGPT 账号登录
快捷方式

如果已安装 CLI，直接在终端运行 codex app 也能启动桌面应用。

Windows 安装

Codex App 已登陆 Microsoft Store，支持原生 Windows 沙箱和 PowerShell：

  1. 在 Microsoft Store 搜索 Codex 并安装
  2. 启动后使用 ChatGPT 账号登录
  3. 选择项目文件夹，发送第一条消息
Windows 注意

Codex App for Windows 可以选择原生 PowerShell 或 WSL 模式。如果你的项目在 WSL 文件系统中，建议在 App 设置中切换到 WSL 模式以获得最佳兼容性。

Linux

Linux 版 Codex App 尚未发布，可在 openai.com/form/codex-app 注册通知。Linux 用户当前推荐使用 CLI 或 IDE Extension。

三、IDE Extension 安装

Codex IDE Extension 让你在编辑器内直接与 Codex 协作，无需切换窗口。

支持的编辑器

编辑器安装方式备注
VS CodeMarketplace 搜索 "OpenAI Codex" 或扩展 ID openai.chatgpt安装后重启编辑器，侧边栏出现 Codex 图标
CursorExtensions 面板搜索安装Cursor 活动栏默认水平显示，建议固定 Codex 图标
WindsurfExtensions 面板搜索安装同 VS Code 操作方式
VS Code Insiders同 VS Code可同时安装 Stable 和 Insiders 版
JetBrains IDEsMarketplace 下载IntelliJ IDEA / PyCharm / WebStorm 等

安装步骤（以 VS Code 为例）

Text
1. 打开 VS Code → 侧边栏 Extensions（⇧⌘X）
2. 搜索 "OpenAI Codex" → 点击 Install
3. 重启 VS Code
4. 侧边栏出现 Codex 图标 → 点击 Sign In
5. 选择 "Sign in with ChatGPT" 完成认证

三种交互模式

模式能力适用场景
Agent读写运行代码，工作区内自动执行，工作区外请求审批日常编码、重构、调试
Chat仅对话，不修改文件规划讨论、代码解释、方案探索
Agent (Full Access)完全自动，包括网络访问和工作区外操作⚠️ 谨慎使用，适合受信任环境
平台限制

IDE Extension 在 macOS 和 Linux 上完全支持。Windows 为实验性支持，建议在 WSL 工作区中使用以获得最佳体验。启用方式：VS Code 设置中打开 chatgpt.runCodexInWindowsSubsystemForLinux。

四、认证方式

Codex 支持两种认证方式，覆盖不同使用场景：

方式 1：ChatGPT 账号登录（推荐）

Bash
# 启动 CLI，选择 "Sign in with ChatGPT"
codex
# → 浏览器自动打开 → 使用 ChatGPT 账号授权 → 完成

优势： 使用你的 ChatGPT 订阅额度（Plus/Pro/Business/Enterprise），无需管理 API Key，无需按 token 计费。

方式 2：API Key

Bash
# 方法 A：环境变量
export OPENAI_API_KEY="sk-..."
codex
​
# 方法 B：.env 文件（项目级）
echo 'OPENAI_API_KEY=sk-...' > .env
codex
​
# 方法 C：auth.json 配置
# ~/.codex/auth.json
# {"OPENAI_API_KEY": "sk-......"}

优势： 按 token 计费，适合 CI/CD 自动化、高频使用超出订阅额度的场景。

两种方式对比

维度ChatGPT 登录API Key
计费订阅包含（Plus $20/月起）按 token 计费（gpt-5.4: 2.50/2.50/15.00 per 1M）
设置难度浏览器一键登录需生成、存储和管理密钥
CLI 交互模式✅ 支持✅ 支持
codex exec（非交互）✅ 支持（需先登录一次）✅ 支持（CI/CD 首选）
App / IDE Extension✅ 原生支持✅ 支持（需配置）
安全建议Token 自动管理⚠️ 永远不要硬编码在代码中，使用 .env • .gitignore
安全警告

无论使用哪种方式，都不要将凭证提交到 Git 仓库。API Key 用户务必将 .env 加入 .gitignore。

五、第一次交互式会话（TUI）

安装并认证完成后，让我们正式开始第一次对话。

启动 TUI

Bash
# 进入你的项目目录
cd ~/projects/my-app
​
# 启动 Codex（交互模式）
codex

Codex 会启动一个全屏终端界面（TUI），自动检测当前目录结构。

发送第一条指令

Text
> Explain this codebase to me

Codex 会扫描项目文件，给出结构概览、技术栈分析和入口点说明。

更多入门指令

指令效果
codex "Explain this codebase to me"项目结构分析（直接传入 prompt 跳过空白 TUI）
codex "Find and fix bugs with minimal changes"自动扫描并修复 Bug
codex "Write tests for the auth module"为指定模块生成测试
codex "Build a classic Snake game in this repo"从零生成一个完整小项目

TUI 内操作

  • 审批控制： 默认 suggest 模式——Codex 提出修改建议，你逐条审批。按 y 接受、n 拒绝
  • 模型切换： 在 TUI 内可随时切换 gpt-5.4 / gpt-5.4-mini 等模型
  • 退出： 按 Ctrl+C 或 Esc 退出会话
  • 恢复会话： codex resume 继续上一次对话
审批模式速查
  • suggest — 所有操作需审批（默认，最安全）
  • auto-edit — 文件编辑自动执行，命令执行需审批
  • full-auto — 全自动，适合信任度高的场景

切换方式：codex --approval-mode auto-edit 或在 config.toml 中设置。

六、第一次非交互式执行（codex exec）

codex exec 是 CLI 的非交互模式，适合脚本化、CI/CD 集成和管道操作。

基本用法

Bash
# 生成代码解释，输出到 stdout
codex exec "Summarize the changes in the last 5 commits"
​
# 将输出管道到文件
codex exec "Generate release notes for v2.0" > RELEASE_NOTES.md
​
# 指定审批模式（全自动）
codex exec --approval-mode full-auto "Run all tests and fix failures"

CI/CD 中使用

Bash
# GitHub Actions 示例
- name: Codex Code Review
  env:
    OPENAI_API_KEY: $ secrets.OPENAI_API_KEY 
  run: |
    npx @openai/codex exec "Review the diff in this PR and suggest improvements"

exec 与交互模式的区别

维度交互模式（codex）非交互模式（codex exec）
界面全屏 TUI无 UI，stdout/stderr 输出
适用场景日常编码、迭代开发CI/CD、脚本管道、批量任务
审批实时交互审批预设审批模式（suggest / auto-edit / full-auto）
输出格式TUI 渲染纯文本 / JSON（--format json）
认证ChatGPT 登录或 API Key通常使用 API Key（CI 环境）
JSON 输出

在自动化场景中使用 --format json 获取结构化输出，便于下游工具解析。

七、Windows 用户的 WSL 设置指南

Codex CLI 和 IDE Extension 在 Windows 上的原生支持为 Experimental。官方推荐通过 WSL 2（Windows Subsystem for Linux）获得最佳体验。

1
步骤 1：安装 WSL 2
Powershell
# 以管理员身份打开 PowerShell
wsl --install
​
# 默认安装 Ubuntu，也可指定发行版
wsl --install -d Ubuntu

安装完成后重启电脑，首次启动 WSL 时设置用户名和密码。

2
步骤 2：在 WSL 中安装 Node.js
Bash
# 进入 WSL
wsl
​
# 通过 nvm 安装 Node.js（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
​
# 重新打开终端或执行 source
source ~/.bashrc
​
# 安装 Node.js 22
nvm install 22
​
# 验证
node -v
npm -v
3
步骤 3：安装并运行 Codex
Bash
# 在 WSL 内安装
npm install -g @openai/codex
​
# 启动
codex
4
步骤 4：VS Code + WSL 集成
Text
1. 在 VS Code 中安装 "WSL" 扩展（ms-vscode-remote.remote-wsl）
2. 打开 WSL 工作区：Ctrl+Shift+P → "WSL: Connect to WSL"
3. 安装 Codex IDE Extension（在 WSL 端自动安装）
4. 在 VS Code 设置中启用：chatgpt.runCodexInWindowsSubsystemForLinux = true
性能提示

将项目文件放在 WSL 文件系统中（/home/user/projects/），而不是 Windows 挂载路径（/mnt/c/）。跨文件系统操作会显著降低 I/O 性能。

WSL 工作流总览

Mermaid
正在渲染 Mermaid 图表…

八、Shell 补全配置

配置 Shell 补全后，输入 codex 按 Tab 即可自动补全子命令和参数，提升操作效率。

Bash

Bash
# 生成补全脚本并加载
codex completion bash > ~/.codex-completion.bash
echo 'source ~/.codex-completion.bash' >> ~/.bashrc
source ~/.bashrc

Zsh

Bash
# 确保补全目录存在
mkdir -p ~/.zsh/completions
​
# 生成补全脚本
codex completion zsh > ~/.zsh/completions/_codex
​
# 添加到 fpath（如果尚未添加）
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

Fish

Bash
# 生成补全脚本
codex completion fish > ~/.config/fish/completions/codex.fish
​
# 立即生效（无需重启）
source ~/.config/fish/completions/codex.fish

PowerShell

Powershell
# 生成补全脚本
codex completion power-shell > $HOME\.codex-completion.ps1
​
# 添加到 Profile
Add-Content $PROFILE 'Import-Module $HOME\.codex-completion.ps1'
Shell补全脚本位置激活方式
Bash~/.codex-completion.bashsource ~/.bashrc
Zsh~/.zsh/completions/_codexsource ~/.zshrc
Fish~/.config/fish/completions/codex.fish自动加载
PowerShell$HOME\.codex-completion.ps1重启 PowerShell

安装验证清单

完成安装后，运行以下命令确认一切就绪：

  • codex --version → 输出版本号（如 0.114.0）
  • codex → TUI 正常启动，输入 "Hello" 得到响应
  • codex exec "echo hello" → 非交互模式正常输出
  • codex completion bash → 输出补全脚本（无报错）
  • IDE Extension 侧边栏显示 Codex 图标，登录状态正常

常见问题

本文小结

步骤要点
CLI 安装npm i -g @openai/codex 或 brew install --cask codex 或二进制下载
App 安装macOS 下载 DMG / Windows 通过 Microsoft Store / Linux 暂未发布
IDE ExtensionVS Code / Cursor / Windsurf Marketplace 搜索 "OpenAI Codex"
认证ChatGPT 登录（推荐，订阅包含）或 API Key（按量计费，CI/CD 首选）
首次交互codex 启动 TUI → 输入指令 → 审批执行
非交互执行codex exec "prompt" → stdout 输出，适合脚本和 CI/CD
WindowsWSL 2 + nvm + Node.js 22 → 最佳兼容性
Shell 补全codex completion bash/zsh/fish/power-shell → 生成脚本并加载
下一篇 →