🟢 Codex CLI 安装与使用完整指南

Codex CLI 是 OpenAI 在 2025 年推出的命令行 AI 编码工具，对标 Anthropic 的 Claude Code。它深度集成 GPT-5 / GPT-5-Codex / o4-mini 等模型，支持 ChatGPT Plus/Pro 订阅登录（不限量使用）和 OpenAI API Key（按量计费）双模式。Codex 的独特之处在于TUI 交互体验——全键盘操作的终端界面，对 vim 用户极其友好。

零、桌面版：ChatGPT Desktop App

OpenAI 在 2024 年底推出 ChatGPT 桌面应用（macOS 首发，2025 年 Windows），2026 版整合了 Codex 桌面能力——既是聊天工具，也是带 GUI 的 Codex 客户端。CLI 适合自动化，桌面版适合多模态交互 + 团队协作 + 可视化。

0.1 下载与安装

# macOS Homebrew
brew install --cask chatgpt

# Windows
winget install OpenAI.ChatGPTDesktop
# 或官网下载 MSI

# Linux：暂未官方支持，用 web 版 + Web App Manifest 安装到 Chrome

0.2 桌面版核心能力（vs CLI）

0.3 桌面版 Codex IDE（杀手锏）

2026 Q2，ChatGPT Desktop 内置了 Codex IDE 面板——左侧聊天，右侧代码编辑器，按 ⌘+K 直接让 AI 改代码。对标 Cursor / Windsurf，但完全免费（Plus 订阅内）。

0.4 适用场景建议

• 用 CLI：服务器、CI/CD、批处理、自动化
• 用 Desktop：多模态（图片/语音/屏幕）、团队协作、视觉化编程
• 学生/非开发者：只装 Desktop 就够，CLI 没必要

0.5 Plus / Pro / Team / Enterprise 价格

💡 Plus 是性价比之王：$20/月含 Codex CLI 不限量 + DALL·E 3 + Advanced Voice + Browse。比 Anthropic Pro 的 $20 更划算（因为有图像和语音）。

一、安装：三平台完整步骤

1.1 macOS — Homebrew 最快

brew install --cask codex
# 验证
codex --version
# → codex-cli 0.4x.x

# 或用 npm
npm install -g @openai/codex

1.2 Linux — npm 通用方案

# 需要 Node.js 18+
npm install -g @openai/codex

# 验证
codex --version

# Debian/Ubuntu 也可装官方 deb 包
curl -fsSL https://openai.com/codex/install-deb.sh | sudo bash

1.3 Windows — 必须 WSL2

# 1. 装 WSL2（参考 Hermes Windows 指南）
wsl --install -d Ubuntu-22.04

# 2. 在 WSL2 内
wsl
sudo apt update && sudo apt install -y nodejs npm
npm install -g @openai/codex

# 注意：Windows 原生 PowerShell 不支持，强制 WSL2

💡 为什么 Windows 必须 WSL2？Codex CLI 依赖 macOS Seatbelt 和 Linux Landlock 沙箱机制，Windows 原生无法实现等价的安全隔离。

1.4 必装的 2 个前置依赖

二、登录认证：ChatGPT 订阅 vs API Key

2.1 用 ChatGPT Plus/Pro 订阅登录（推荐）

codex
# 首次启动会自动跳转浏览器 → 登录 ChatGPT 账号
# Plus 订阅：每月 $20，含 Codex CLI 无限量
# Pro 订阅：每月 $200，含 GPT-5/Pro 模型优先访问
# 成功后 ~/.codex/auth.json 存有 token

2.2 用 OpenAI API Key

export OPENAI_API_KEY=*** 写入 ~/.zshrc
codex --api-key $OPENAI_API_KEY
# 或用环境变量自动识别
echo 'export OPENAI_API_KEY=*** 写入 ~/.codex/.env

2.3 企业 SSO（Azure OpenAI）

export CODEX_API_BASE=https://your-company.openai.azure.com
export CODEX_API_KEY=***
export CODEX_DEPLOYMENT=gpt-5
codex --provider azure

三、核心用法：TUI 交互模式

3.1 启动 TUI

cd ~/projects/my-app
codex

# 全屏 TUI 启动，顶部状态栏显示当前 model
# 底部输入框，按 Enter 提交

# 切模型（! 触发命令面板）
!model gpt-5
!model o4-mini          # 推理任务用
!model codex-mini       # 速度优先

# 常用快捷键
Ctrl+C        # 中断当前请求
Ctrl+D        # 退出 TUI
Ctrl+L        # 清屏
Esc           # 取消当前编辑
↑/↓           # 历史命令

3.2 Slash 命令（/ 触发）

/help        # 所有命令
/clear       # 清空上下文
/compact     # 压缩历史
/agents      # 加载 AGENTS.md
/review      # 开启 PR review 模式
/diff        # 显示当前所有改动
/undo        # 撤销上一次文件修改
/save        # 保存当前 session
/load        # 加载历史 session
/model       # 切换模型
/exit        # 退出

3.3 Headless 模式（非交互）

# 单次任务
codex exec "解释这个文件做什么" < main.py

# JSON 输出
codex exec "总结 README" --output-format json > summary.json

# 完整 diff 模式
codex exec "修复这个 bug" --output-format stream-json

# 沙箱关闭（不推荐生产用）
codex exec "删除 node_modules" --sandbox danger-full-access

四、沙箱机制：Codex 的安全设计

Codex CLI 相比 Claude Code 的核心差异是原生沙箱——所有命令执行前都过一层 OS 级隔离。

4.1 macOS Seatbelt 沙箱

# 自动启动，默认只允许读当前目录 + 写当前目录
# 外部命令会要求确认
codex
> npm install          # 默认允许
> rm -rf /            # 沙箱拦截，要求确认
> curl evil.com       # 网络访问默认拒绝

4.2 Linux Landlock 沙箱

# Linux 内核 5.13+ 自带的强制访问控制
codex
# 网络/文件系统操作都受 Landlock 限制
# 需要高权限时用 --sandbox 调整

4.3 沙箱模式速查

五、AGENTS.md：团队规范

AGENTS.md 是 OpenAI 推动的项目级 AI 规范文件，相当于「给 AI Agent 的 README」。Claude Code 用 CLAUDE.md，Codex 用 AGENTS.md。

# AGENTS.md（项目根目录）

## 技术栈
- Next.js 15 + TypeScript strict
- PostgreSQL 16 + Prisma ORM
- pnpm 包管理

## 命名约定
- 组件用 PascalCase
- Hooks 用 camelCase 且以 use 开头
- 数据库表名 snake_case 复数

## 常用命令
- pnpm dev       # 启动开发
- pnpm test      # 跑测试
- pnpm db:migrate  # 迁移数据库

## 禁止事项
- 不要直接 commit 到 main
- 不要修改 prisma/schema.prisma 除非明确授权
- 不要安装新依赖前先问

Codex 启动时会自动读取 AGENTS.md 作为系统级指令。

六、MCP 集成

# 添加 MCP 服务器
codex mcp add github -- npx -y @modelcontextprotocol/server-github
# 配置
codex mcp env github GITHUB_TOKEN=***
# 列出
codex mcp list

# 在 TUI 中使用
> 用 github MCP 给我这个 repo 列所有 open issue

七、装完必做的 4 件事

八、Codex vs Claude Code 选型

💡 选型建议：日常开发用 Codex + ChatGPT 订阅（成本最低），复杂架构用 Claude Code + API（推理深度更好）。也可以装两个互补。

九、常见问题 FAQ

本文由 AI Know 基于 OpenAI 官方文档 + 实测经验整理，覆盖 Codex CLI 0.4x 版本。后续版本命令如有变动，请以 官方文档 为准。

← 返回专题列表