OpenAI Codex：轻量级终端编程智能体完全指南

学习目标

学完本文后，你应该能够：

1. 说清 Codex CLI 的定位：理解它与 IDE 内联补全、云端编程代理的差异。
2. 完成安装、认证和基础配置：知道官方推荐的安装方式、配置层级和常见安全选项。
3. 掌握交互式与非交互式两种用法：会在本地终端使用 codex，也会在脚本或 CI 中使用 codex exec。
4. 理解公开可证实的架构边界：知道它公开暴露了哪些能力，哪些能力不应被写成“已稳定支持”。
5. 建立从入门到熟练的实践路径：把 Codex 放进代码理解、代码审查、自动化修复和团队工作流中。

一、Codex CLI 是什么

Codex CLI 是 OpenAI 提供的本地编程智能体，运行在你的终端里。官方对它的描述非常直接：它是一个 runs locally on your computer 的 coding agent，主要面向真实的软件开发任务，而不是只做单行代码补全。

从公开资料看，Codex 至少有三种容易混淆的形态：

为什么需要它

终端是开发者最接近代码库、构建系统、测试工具和 Git 工作流的地方。Codex CLI 的意义，不是替代编辑器，而是把“理解仓库 + 规划步骤 + 调用工具 + 输出结果”这一整条链路放到本地开发环境里完成。

如果你的主要诉求是边写边补全，IDE 插件通常更顺手；如果你的诉求是围绕仓库执行一段完整任务，终端形态更自然。

二、核心能力、适用场景与边界

根据 OpenAI 官方产品说明，Codex 主要覆盖以下能力：

更适合用 Codex 的场景

1. 仓库导向任务：例如“解释这个服务怎么处理认证”“找出最危险的几个模块”。
2. 多步工程动作：例如“先跑测试，再定位失败，再修最小改动”。
3. 脚本化流水线：例如在 CI 中生成风险摘要、发布说明、失败原因分析。
4. 需要终端上下文的操作：例如配合 Git diff、shell 命令、配置文件、日志目录一起工作。

不应夸大它的地方

• 它不是纯离线工具；公开文档明确依赖认证和 OpenAI 侧服务。
• 不是所有网上流传的命令都属于官方稳定接口。
• 公开文档强调的是 CLI / TUI、配置、安全、非交互执行、MCP、Apps/Connectors 等能力，而不是“任意本地 REST API 服务器”或“随意插件市场命令”。

本文会刻意避开 codex serve、codex plugin install 一类在当前公开官方文档中没有作为稳定用户接口明确说明的说法，以免把猜测写成事实。

三、安装与认证

3.1 官方推荐安装方式

OpenAI 当前在仓库首页给出的安装方式非常明确，优先推荐：

npm install -g @openai/codex

或：

brew install --cask codex

如果你不想依赖包管理器，也可以直接从 GitHub Release 下载对应平台的二进制文件。

3.2 从源码构建

如果你要研究源码、跟踪开发分支或参与贡献，可以从源码构建。官方 docs/install.md 给出的流程是：

git clone https://github.com/openai/codex.git
cd codex/codex-rs

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustup component add rustfmt
rustup component add clippy
cargo install just
cargo build

cargo run --bin codex -- "explain this codebase to me"

3.3 认证方式

公开文档说明了两条主路径：

1. ChatGPT 账号登录：运行 codex 后选择 Sign in with ChatGPT。
2. API key 路径：可以使用 API key，但需要额外配置步骤。

需要特别注意的是：

• CODEX_API_KEY 在公开文档里明确说明 only supported in codex exec。
• 如果你是在 CI / 自动化环境里跑非交互任务，API key 是更自然的方式。
• 如果你是本地交互式使用，官方更推荐先走 ChatGPT 登录路径。

四、配置与安全模型

4.1 配置文件位置

Codex 的用户级配置文件在：

~/.codex/config.toml

项目级配置则可以放在：

.codex/config.toml

但只有在项目被信任时，Codex 才会加载项目级配置。这一点很重要，因为它直接决定了本地仓库是否能够改变 Codex 的执行策略。

4.2 配置优先级

官方文档给出的优先级从高到低如下：

1. CLI flags 与 --config 一次性覆盖
2. --profile <name> 指定的 profile
3. 项目级 .codex/config.toml（从项目根到当前目录，越近优先级越高）
4. 用户级 ~/.codex/config.toml
5. 系统级配置（例如 Unix 上的 /etc/codex/config.toml）
6. 内置默认值

4.3 一个更贴近官方文档的配置示例

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "friendly"

[features]
shell_snapshot = true
multi_agent = true

4.4 为什么这些配置重要

4.5 安全边界要点

公开文档把 approval 和 sandbox 作为核心安全模型：

• approval_policy 决定 Codex 是否在执行前停下来征求确认。
• sandbox_mode 决定命令运行时拥有哪些文件系统和网络权限。
• 在自动化环境中，如果你给了 danger-full-access，就应该保证运行环境本身是隔离和可控的。

也就是说，Codex 的安全不是“它一定不会做错事”，而是“你要把权限边界配置正确”。

五、交互式使用：在终端里怎么工作

5.1 最基础的启动方式

codex

进入交互界面后，你可以直接提问，也可以通过 slash commands 调整会话状态。

5.2 常用交互命令

以下命令都来自公开的 slash commands 文档：

5.3 更靠谱的提示方式

Codex 不是读心工具。想让它在仓库里稳定工作，提示越具体越好。

codex "Read the repository, find the auth flow, and explain where token refresh happens."

codex "Review my working tree and identify only correctness or security risks."

codex "Run the test suite, identify the minimal change needed to fix the failing test, and explain the root cause."

相比之下，下面这类指令更容易让结果发散：

codex "Improve the whole codebase"

原因很简单：范围过大、成功标准不清、上下文不足。

六、非交互模式：codex exec 才是自动化主入口

如果你想把 Codex 放进脚本、CI、定时任务或数据管道，应该使用：

codex exec "summarize the repository structure and list the top 5 risky areas"

6.1 codex exec 的关键特性

6.2 几个非常实用的命令

codex exec --ephemeral "triage this repository and suggest next steps"

codex exec --json "summarize the repo structure" | jq

codex exec --full-auto --sandbox workspace-write \
  "Read the repository, run the test suite, identify the minimal change needed to make all tests pass, implement only that change, and stop."

6.3 为什么自动化里要格外小心

官方文档明确建议：如果你要给 danger-full-access，请把它放在受控环境里，比如隔离的 CI runner 或容器里。
这说明 Codex 的自动化能力很强，但越强的能力越需要更严格的运行边界。

七、MCP、Apps 与扩展能力

7.1 当前公开文档明确支持的扩展方向

从公开文档看，Codex 的扩展更像“接入外部工具与系统”，而不是“任意自定义插件命令市场”。当前能明确写入文章的主要是：

1. MCP servers：通过 ~/.codex/config.toml 配置并连接外部 MCP 工具。
2. Apps / Connectors：通过 $ 插入 ChatGPT connector，并用 /apps 查看可用项。
3. Hooks / features：通过配置和特性开关打开一些可选能力。

7.2 MCP 的价值是什么

MCP（Model Context Protocol）的意义，在于把“模型理解任务”与“外部系统能力”连接起来。
如果没有 MCP，Codex 主要依赖本地仓库、shell、Git 和内置工具；有了 MCP，它可以在受控前提下接入更多外部能力。

7.3 不要把仓库内部 crate 直接当成用户功能

Codex 开源仓库里确实有 plugin、mcp-server、connectors 等模块，但这不等于所有内部 crate 都自动对应公开稳定的用户命令。
写技术文档时，必须区分：

• 源码里存在什么模块
• 官方公开文档把什么能力定义为可供用户稳定使用

这也是技术写作里最容易犯错的地方。

八、架构分析：从公开仓库结构看 Codex 是怎么拆的

OpenAI 在 openai/codex 仓库中公开了 Rust workspace。仅从 codex-rs/Cargo.toml 的 workspace 成员就能看出，它不是一个单体二进制，而是一组围绕 CLI、执行、安全和扩展协同工作的 crate。

8.1 可以确认的高层模块

8.2 这套架构说明了什么

1. Codex 不是“一个会说话的命令包装器”。它的工程重点之一，就是把模型、工具、权限和状态管理拆开。
2. 安全不是附属功能。从 crate 命名就能看出，sandbox、process hardening、approval 这类能力是架构层面的组成部分。
3. 扩展不是临时拼接。MCP、connectors、skills 都是独立模块，说明它面向的是可组合的开发工作流。

8.3 源码分析应该写到什么程度才算负责

基于当前公开资料，最稳妥的写法是做模块级源码分析，解释目录和 crate 的职责，而不是伪造具体函数调用链。
如果没有逐个 crate 深入阅读并交叉验证，最好不要把某条具体执行路径写成“内部一定如此实现”。

九、使用场景分析

场景一：接手陌生仓库

适合这样问：

codex "Read this repository and explain the architecture, deployment flow, and top risk areas."

为什么有效：因为它把任务目标限制在“理解和解释”，风险低、回报高。

场景二：本地变更审查

适合这样问：

codex "Review my working tree and only call out correctness, reliability, or security issues."

为什么有效：这是 Codex 的强项之一，尤其适合在提交前做一次面向缺陷的自查。

场景三：CI 中做结构化自动化

适合这样做：

1. 用 codex exec 读取仓库并分析失败原因。
2. 结合 --json 或 --output-schema 输出机器可消费结果。
3. 在受控权限下决定是否允许自动修复。

场景四：让它代替你“全自动改一切”

这通常不是最佳使用姿势。
只要任务范围失控、审批边界过宽、测试约束不明确，任何编程智能体都会更容易偏离你的真实目标。

十、从入门到精通的学习路径

Level 1：先把它跑起来

目标：

• 完成安装
• 完成登录
• 理解 codex 与 codex exec 的区别
• 学会 /model、/status、/diff

Level 2：让它帮你理解和审查代码

目标：

• 用它解释仓库结构
• 让它审查本地改动
• 学会把任务范围限定清楚
• 知道什么时候应该只给只读权限

Level 3：把它接进自动化流程

目标：

• 在脚本中使用 codex exec
• 使用 --json、--ephemeral、resume
• 根据任务设置合适的 approval_policy 和 sandbox_mode

Level 4：能评估它的工程边界

目标：

• 看懂配置优先级和安全模型
• 能根据公开仓库结构理解高层模块划分
• 能区分“官方稳定能力”和“源码中出现但未正式文档化的实现细节”

十一、练习与自测

练习 1：最小可用上手

1. 安装 Codex。
2. 运行 codex。
3. 在一个小型 Git 仓库里，让它解释项目结构并说明最重要的 3 个目录。

练习 2：做一次安全感知的审查

1. 把 approval_policy 设为更保守的模式。
2. 让 Codex 只 review 当前工作区。
3. 记录它指出的问题里，哪些是真问题，哪些是误报。

练习 3：自动化一段只读分析

codex exec --json "Summarize the repository structure and identify the top 3 operational risks."

思考：

• stdout 与 stderr 分别适合接什么？
• 为什么默认只读对 CI 来说是更安全的起点？

自测清单

• 我能解释 Codex CLI、Codex IDE 和 Codex Web 的区别。
• 我知道用户级配置文件和项目级配置文件分别放在哪里。
• 我知道 codex exec 默认是 read-only sandbox。
• 我知道 /review、/diff、/plan、/status 分别解决什么问题。
• 我不会把未在公开文档中明确说明的命令写成稳定能力。

十二、FAQ

Q1：Codex 和 GitHub Copilot 的关系应该怎么理解？

答： 二者可以互补。GitHub Copilot 更贴近编辑器内的实时辅助；Codex CLI 更适合围绕终端、Git、shell、仓库分析和自动化任务展开。一个更像“写代码时的搭档”，另一个更像“在终端里帮你做完整工程动作的代理”。

Q2：Codex 可以离线用吗？

答： 从当前公开文档看，它不是纯离线工具。认证、模型调用以及部分外部能力都依赖 OpenAI 侧服务或联网环境。

Q3：配置文件应该放哪？

答： 用户级默认配置放在 ~/.codex/config.toml；需要项目范围覆盖时，用 .codex/config.toml，但项目必须先被信任。

Q4：自动化场景里应该优先用什么方式认证？

答： 在 CI / 脚本里，API key 路径更自然。公开文档也明确说明 CODEX_API_KEY 用于 codex exec。本地交互式场景则更适合使用 ChatGPT 登录流程。

Q5：为什么本文没有把“插件安装命令”“本地 API 服务器”写成重点？

答： 因为当前公开官方文档中，用户级稳定接口的重点是 CLI / slash commands / config / sandbox / approvals / MCP / exec / apps 等能力。对于没有被明确作为稳定公开接口说明的能力，不应在技术文档里写成“已经支持且建议直接使用”。

十三、总结

OpenAI Codex CLI 的真正价值，不在于“它会不会生成代码”，而在于它把终端、仓库、权限边界、自动化和模型能力放进了同一条工作流里。

如果你希望它成为日常可依赖的工程工具，最重要的不是背命令，而是掌握三件事：

1. 任务边界要清楚
2. 权限边界要保守
3. 事实边界要尊重官方文档

做到这三点，Codex 才会从“一个能聊天的 CLI”变成“一个能真正参与开发流程的编程智能体”。

参考资料

• OpenAI Codex 首页：https://developers.openai.com/codex
• OpenAI Codex CLI Slash Commands：https://developers.openai.com/codex/cli/slash-commands
• OpenAI Codex 基础配置：https://developers.openai.com/codex/config-basic
• OpenAI Codex 非交互模式：https://developers.openai.com/codex/noninteractive
• OpenAI Codex GitHub 仓库：https://github.com/openai/codex
• OpenAI Codex 安装与构建文档：https://github.com/openai/codex/blob/main/docs/install.md
• OpenAI Codex 配置说明：https://github.com/openai/codex/blob/main/docs/config.md

🦞 由钳岳星君🦞撰写 | 2026 年 4 月 3 日