5 分钟装好 Codex CLI，让 AI 在你终端里写代码

本系列文章基于 Codex CLI 源码深度分析，带你从安装到架构，彻底搞懂这个 OpenAI 开源的本地 AI 编程代理。

全网唯一从 Rust 源码层面拆解 Codex CLI 的系列

一、Codex CLI 是什么？

Codex CLI 是 OpenAI 开源的一个本地终端 AI 编程代理。它不是一个简单的"代码补全"工具，而是一个真正能理解你的代码库、执行命令、修改文件、管理 Git 工作流的 AI 助手。

和 GitHub Copilot、Cursor 这类 IDE 插件不同，Codex CLI 运行在终端里，这意味着：

• 你可以把它接入任何工作流（CI/CD、脚本、定时任务）
• 它有完整的沙箱安全机制，AI 执行的命令被隔离
• 它是开源的，你可以读源码、改源码、二次开发
• 它支持非交互模式（codex exec），适合自动化场景

二、安装

macOS / Linux

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

包管理器安装

# npm
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

从 GitHub Release 下载

访问 GitHub Releases，下载对应平台的二进制：

平台	文件名
macOS Apple Silicon	codex-aarch64-apple-darwin.tar.gz
macOS Intel	codex-x86_64-apple-darwin.tar.gz
Linux x86_64	codex-x86_64-unknown-linux-musl.tar.gz
Linux arm64	codex-aarch64-unknown-linux-musl.tar.gz

解压后把二进制文件放到 PATH 中即可。

验证安装

codex --version

三、登录认证

Codex CLI 支持两种认证方式：

方式一：ChatGPT 账号（推荐）

codex login

选择 Sign in with ChatGPT，浏览器会自动打开登录页面。登录后 Codex 会自动保存认证令牌。

优势：使用 ChatGPT Plus/Pro/Team/Enterprise 套餐，无需额外付费。

方式二：API Key

codex login --api-key

输入你的 OpenAI API Key。需要自己在 OpenAI 平台充值。

四、第一个命令

安装完成后，试试最基础的用法：

codex "用 Python 写一个简单的 HTTP 服务器"

你会看到 Codex 的 TUI（终端界面）启动，AI 开始思考、生成代码、解释实现思路。

TUI 界面概览

┌─────────────────────────────────────────────────┐
│  Codex                                    [⚡]  │  ← 顶部状态栏
├─────────────────────────────────────────────────┤
│                                                 │
│  👤 你: 用 Python 写一个简单的 HTTP 服务器       │
│                                                 │
│  🤖 Codex: 我来帮你写一个 Python HTTP 服务器...  │  ← 聊天区域
│                                                 │
│  ```python                                      │
│  from http.server import HTTPServer...          │
│  ```                                        │
│                                                 │
├─────────────────────────────────────────────────┤
│  > _                                    [Send]  │  ← 底部输入栏
└─────────────────────────────────────────────────┘

五、核心命令速览

1. 交互模式（默认）

codex                              # 启动交互式 TUI
codex "解释这个项目的架构"           # 带初始 prompt 启动

2. 非交互模式

codex exec "修复 src/main.rs 中的所有编译错误"
codex exec --json "列出所有 TODO 注释" > todos.json

3. 代码审查

codex review                        # 审查当前改动
codex review --branch main          # 与 main 分支对比

4. 应用 AI 生成的修改

codex apply                         # 应用最近的 diff

5. 会话管理

codex resume                        # 恢复最近的会话
codex resume --last                 # 直接恢复上一个会话
codex fork                          # 分叉一个会话

6. 沙箱执行

codex sandbox -- ls -la             # 在沙箱中执行命令

六、源码结构速览

在深入使用之前，先了解项目的整体结构会很有帮助。Codex CLI 的 Rust 核心位于 codex-rs/ 目录：

codex-rs/
├── cli/                    # 命令行入口（20+ 子命令）
├── core/                   # 核心 Agent 运行时
│   ├── src/
│   │   ├── session/        # Session → Turn → Agent Loop
│   │   ├── config/         # 配置加载
│   │   ├── context/        # 上下文管理
│   │   └── tools/          # 工具系统
├── tui/                    # 终端 UI（ratatui）
├── app-server/             # 应用服务器
├── app-server-protocol/    # JSON-RPC v2 协议
├── sandboxing/             # 安全沙箱（Linux/macOS/Windows）
├── ext/                    # 扩展系统
├── mcp/                    # MCP 协议实现
├── protocol/               # 核心协议定义
└── tools/                  # 工具定义

七、常见问题

Q: 安装后运行 codex 提示 command not found？

确保安装路径在 PATH 中。用 curl 安装的默认路径是 ~/.local/bin/codex。

Q: 登录后提示 “No active subscription”？

ChatGPT 免费账户目前不支持 Codex CLI。需要 Plus/Pro/Team/Enterprise 套餐，或使用 API Key。

Q: Windows 上能用吗？

Windows 需要通过 WSL2 运行。直接安装 Windows 版本可用 codex app 启动桌面应用。

Q: 怎么配置代理？

# 设置 HTTPS 代理
export HTTPS_PROXY=http://127.0.0.1:7890
codex

或在 config.toml 中配置：

[network]
proxy = "http://127.0.0.1:7890"

八、下一步

现在你已经安装好了 Codex CLI，下一篇我们将深入配置系统，从 config.toml 到沙箱策略，全面掌握 Codex CLI 的配置能力。

---

本系列文章：

• A1：5 分钟装好 Codex CLI（本文）
• A2：Codex CLI 配置完全指南
• A3：非交互模式实战
• A4：代码审查实战
• … 更多文章持续更新

讨论：你更倾向于让 AI 直接执行命令，还是每次都要确认？欢迎在评论区分享你的看法。