Codex CLI 使用指南：OpenAI 终端编程智能体

本文介绍 OpenAI 推出的终端编程智能体 Codex CLI：它基于 Rust 构建，运行在本地终端中，可直接读取、修改并运行指定目录中的代码。文章系统梳理 macOS、Linux 与 Windows 平台的安装部署方式、ChatGPT 账号与 API Key 两种认证配置、终端命令与交互式斜杠指令速查表、TUI 键盘快捷键（输入编辑、会话控制、Transcript 视图）、审批策略与沙箱级别配置，并结合新项目初始化、交互式开发验证与提交前代码审查三个场景演示其典型工作流，最后补充配置分层、MCP 凭据管理等实践中的易踩坑点。

Codex CLI 简介

OpenAI 推出的 Codex CLI 是一款运行在本地终端中的轻量级编程智能体（Agent）。它基于 Rust 构建，能够直接在用户指定的本地目录中读取、修改并运行代码，支持 macOS（Apple Silicon 与 x86_64）、Linux（x86_64 与 arm64）以及 Windows（原生或 WSL2）。

与 ChatGPT 网页端不同，Codex CLI 直接工作在真实代码仓库中：它可以扫描项目结构、执行构建与测试命令、按 AGENTS.md 中的团队规范行事，并通过沙箱（Sandbox）与审批（Approvals）机制约束文件写入和命令执行的权限边界。

安装与部署

Codex 支持跨平台运行，CLI 可通过独立脚本、npm、Homebrew 或直接下载二进制文件安装。

安装命令

可根据操作系统与偏好选择以下方式之一：

• 独立脚本安装（官方推荐）

  • macOS / Linux：

    bash

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

  • Windows (PowerShell)：

    powershell

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

  curl ... | sh 会直接执行远端脚本。生产环境建议先下载脚本审计内容（或固定校验和）后再执行；脚本默认从 releases.openai.com/codex 下载二进制，失败时回退到 GitHub Releases。 在 Windows 上 Codex CLI 支持本地沙箱；若更习惯 Linux 环境，也可在 WSL2 中运行。

• 包管理器安装

  • npm 方式：

    bash

    npm install -g @openai/codex

  • Homebrew (macOS)：

    bash

    brew install --cask codex

• 桌面客户端（可选）

  如果更倾向于图形界面，可以在 Windows 上通过 winget 部署 Codex 桌面应用：

  powershell

  winget install Codex -s msstore

安装完成后运行 codex --version 确认版本，即可开始使用。

身份认证

首次在终端运行 codex 会触发登录流程。Codex 支持两种主要的授权方式：

1. ChatGPT 账号绑定（推荐）：Codex 包含在 ChatGPT Plus、Pro、Business、Edu 及 Enterprise 订阅中，在终端选择 “Sign in with ChatGPT” 并在浏览器中完成跳转授权即可。

2. OpenAI API Key：如果需要在无浏览器交互的环境（如 CI 或远程服务器）中使用，可设置环境变量：

   bash

   export OPENAI_API_KEY="your-openai-api-key"

配置文件结构

Codex 遵循多级配置覆盖机制：

• 全局默认配置：~/.codex/config.toml，对所有会话生效；
• 项目级配置：<your-project>/.codex/config.toml，用于定制当前项目专属的模型与审批规则。项目目录需要被标记为受信任（Trusted，首次打开时 Codex 会询问是否信任该目录），未信任目录下的项目级配置与项目指令不会被完整加载。

此外，用户级指令文件 ~/.codex/AGENTS.md 会与项目级 AGENTS.md 拼接后共同生效。

常用命令与指令

Codex CLI 具有两种主要的交互模式：非交互模式（单次执行）和交互式终端 UI 模式（TUI）。

终端命令

在终端中直接运行，可以用来启动会话或执行特定运维任务：

交互式会话中的斜杠指令（Slash Commands）

进入 codex 交互界面后，在对话框内输入 / 可以触发一系列控制当前会话行为的快捷指令：

键盘快捷键

TUI 交互中的键盘快捷键按场景分为输入编辑、会话与运行控制、Transcript 视图三类，个别默认键位可能随版本调整，以输入框按 ? 呼出的快捷键帮助面板为准。

输入与编辑

会话与运行控制

Transcript 视图

Ctrl + T 打开 Transcript 视图，可查看模型的推理摘要（Reasoning Summary）与工具调用明细，功能类似 Claude Code 的 Ctrl + O。

计划模式（Plan Mode）

计划模式下 Codex 处于只读状态：仅检索项目、分析依赖、产出分步实施方案，不修改文件、不执行写操作，方案确认后再切回执行模式开始改代码。与 Claude Code 的 Plan Mode 概念一致。

会话中可用 /status 查看当前生效的配置，/permissions 调整 Codex 的文件编辑与命令执行权限。

核心机制配置

为了使 Codex 在复杂工程中发挥更稳定的作用，有几项配置机制建议了解。

全局行为配置：config.toml

若希望每次启动都保持特定行为，可修改全局配置文件 ~/.codex/config.toml（会话启动时读取）：

# 审批策略，合法取值：
#   "untrusted"   仅显式放行的命令免审批，其余一律询问
#   "on-request"  模型自行决定何时请求审批（默认值；旧别名 on-failure）
#   "never"       从不请求审批，命令失败直接返回给模型继续处理
approval_policy = "on-request"

# 沙箱级别，合法取值：
#   "read-only"           只读，不写入任何文件（默认值）
#   "workspace-write"     仅当前工作区可写
#   "danger-full-access"  完全放开，无沙箱隔离
sandbox_mode = "workspace-write"

高风险参数：–yolo

# 等价于 --dangerously-bypass-approvals-and-sandbox
# 官方描述：跳过所有确认提示，命令不经过沙箱直接执行（EXTREMELY DANGEROUS）
# 仅建议在容器、CI 等外层已有隔离措施的环境中使用
codex --yolo

[!WARNING] --yolo 会同时关闭审批与沙箱两道防线，等价于 Claude Code 中的 --dangerously-skip-permissions。切勿在含敏感凭据的宿主机上日常使用；如需免交互自动化，优先采用 sandbox_mode = "workspace-write" 配合 "never" 审批策略的组合，将写入范围限定在工作区内。

编写 AGENTS.md 指南

AGENTS.md 是 Codex 的指令基础，作为一个公开透明的"智能体说明书"存放在项目根目录（或用户目录 ~/.codex/）下，Codex 每次启动都会自动读取其内容。可以使用 /init 生成，并根据团队规范定制如下内容：

• 项目技术栈细节（如 Node.js v18、Postgres）；
• 标准的构建、测试和代码风格检查指令（如 npm run lint、pytest）；
• 代码约束（如"必须编写对应的单元测试"、“严禁修改 config 目录下的生产环境配置”）。

两个实践细节值得注意：

• 若存在 AGENTS.override.md，它会优先于 AGENTS.md 被加载，适合存放不想提交到仓库的个人本地规则；
• 未被信任（Untrusted）的项目目录不会深度加载项目级指令，因此在陌生仓库中首次运行时应留意信任确认提示。

配置 MCP (Model Context Protocol) 扩展

通过在 ~/.codex/config.toml 中定义 mcp_servers，可以让 Codex 获得外部工具的读写权限（例如查询 Linear 上的待办任务、查询本地数据库、检索企业文档等）：

# 示例：在 ~/.codex/config.toml 中注册一个 GitHub MCP 服务器（stdio 传输）
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { "GITHUB_PERSONAL_ACCESS_TOKEN" = "your_token" }

[!WARNING] env 字段中的值会以明文形式写进配置文件。如果 ~/.codex/ 目录会随 dotfiles 仓库同步，应避免将真实 Token 硬编码在 config.toml 中，改为通过 shell 环境变量注入。Codex 的 HTTP 传输型 MCP 服务器还要求通过 bearer_token_env_var 指定环境变量名读取 Bearer Token，不支持在配置中内联 Token 值。

实际使用示例

示例一：新项目初始化

1. 进入代码库，并启动会话：

   bash

   cd ~/my-new-app
   codex

2. 在对话框中生成统一规则文档：

   text

   > /init

3. 打开生成的 AGENTS.md 文件，增加本项目的运行规范：

   markdown

   ## 运行与测试约束
   
   - 本项目使用 ESLint，提交前请务必确认 `npm run lint` 通过。
   - 所有的 API 变动都必须在 `tests/` 目录下更新对应的集成测试。

示例二：交互式开发与测试自动验证

当向 Codex 发送一个比较复杂的业务需求时，它可以一边写代码，一边调用本地测试脚本确认正误：

> 请帮我实现一个邮箱验证的中间件，要求使用 Zod 校验，并在修改后运行 npm test 确认测试通过。

Codex 的执行流程：

1. 扫描现有路由代码和 Zod 配置；
2. 编写验证逻辑，并检测测试文件夹位置；
3. 如果测试报错，根据终端输出的 Trace 自动修正中间件代码，直到本地命令返回 exit 0。

示例三：发布前的代码审查（Code Review）

完成了某一阶段的开发，但还不确定代码是否存在漏洞，可以在提交前使用：

> /review

Codex 将针对本地暂存的修改进行静态评估，指出逻辑死锁、缺乏边界校验或不符合 AGENTS.md 规范的细节，并提供修复建议。

实践建议与踩坑点

结合日常使用，以下几点值得注意：

• 快捷键的双重语义：Ctrl + C 在输入框为空时是退出会话、任务运行中是中断当前轮次，误触退出后可用 codex resume 恢复最近会话；运行中单次 Esc 是中断当前轮次，空输入框下连按两次 Esc 是回退编辑上一条消息，两者时机不同。
• 运行中打字不会丢失：任务执行期间直接输入并按 Enter，消息会进入队列而非打断任务；想立即打断请用 Esc。
• 换行键受终端影响：Shift + Enter 依赖终端的增强键盘协议支持，跨终端演示或脚本化场景优先使用 Alt + Enter 或 Ctrl + J。
• 权限策略按场景收敛：默认使用只读或自动审批模式；将完全访问模式留给受信任的个人项目。在共享机器上以完全访问模式运行前，务必确认 AGENTS.md 中没有授予过于宽泛的命令权限。
• 长会话主动 /compact：上下文接近上限时模型质量会明显下降，与其等待自动截断，不如在阶段性任务完成后手动压缩。
• AGENTS.md 保持精简：指令文件会被完整注入每次会话的上下文，堆砌无关规则会挤占有效上下文并稀释关键约束的权重，建议控制在几十行内。
• CI 中使用 codex exec：非交互模式以进程退出码反映任务成败，配合 --json 输出便于流水线解析；不要在 CI 中交互式调用 TUI。
• 版本更新频繁：Codex CLI 迭代速度快，斜杠指令与配置项在不同版本间可能有增减，遇到行为不符时先用 /status 与 codex --version 确认环境，再对照当前版本文档排查。