OpenAI Codex CLI 完整使用指南

作者：Ranger Ramblings
发布时间：2026年3月31日 09:05
原始链接：https://mp.weixin.qq.com/s/oc97KPo0zErvYGpr7sUgVg

本文档基于 Codex CLI 截至 2026 年 3 月的最新文档整理，适用于 macOS / Linux（Windows 为实验性支持）。鉴于 ClaudeCode 大面积封号导致我吸不到纯正的 Opus 4.6，不得不使用代餐，尽管 GPT 5.4 也很强大，但就是没 Opus 那味儿，可能我还是爱 Opus 更多一点。

1. 简介

Codex CLI 是 OpenAI 推出的本地终端编程 Agent，使用 Rust 编写，具备高性能与低资源占用的特点。它可以：

• 读取并修改当前目录的代码库
• 执行 Shell 命令（在沙箱策略控制下）
• 与外部工具通过 MCP 协议通信
• 以非交互方式集成进 CI/CD 流水线

适用平台：macOS、Linux（Windows 为实验性支持，推荐使用 WSL）

订阅要求：需要 ChatGPT Plus、Pro、Business、Edu 或 Enterprise 计划，或直接使用 OpenAI API Key。

2. 环境配置

2.1 安装

推荐使用 npm 全局安装：

npm install -g @openai/codex

或使用 Homebrew（macOS）：

brew install --cask codex

也可以从 GitHub Releases[1] 下载预编译二进制文件，解压后重命名为 codex 并添加到 PATH。

2.2 升级

npm update -g @openai/codex

2.3 首次认证

安装后运行 codex，首次启动会提示登录：

codex

支持两种认证方式：

• ChatGPT 账号 OAuth（推荐）：浏览器跳转授权
• API Key：手动输入 sk-... 格式的密钥

也可以提前完成认证：

codex auth

退出登录：

codex auth logout

2.4 Shell 自动补全

安装补全脚本以获得命令行 Tab 补全：

codex completion bash   # Bash
codex completion zsh    # Zsh
codex completion fish   # Fish

将输出追加到对应 Shell 的配置文件中（如 ~/.zshrc）。

2.5 配置目录

Codex 的全局配置存放在：

~/.codex/
├── config.toml        # 主配置文件
├── sessions/          # 历史会话记录
└── log/               # 日志文件（如 codex-tui.log）

项目级配置存放在仓库根目录下：

<project>/
├── .codex/
│   └── config.toml    # 项目级配置（仅受信任项目生效）
└── AGENTS.md          # Agent 行为指令文件

3. 常见环境变量

使用示例：

# 使用 API Key 启动
OPENAI_API_KEY=sk-xxx codex

# 使用项目隔离配置
CODEX_HOME=$(pwd)/.codex codex exec "列出当前指令源"

# 指向自定义 API 端点（如内部代理）
OPENAI_BASE_URL=https://proxy.example.com codex

安全提示：不要将 API Key 硬编码在脚本中，优先使用环境变量管理器（如 direnv、1Password CLI）注入密钥。

4. 命令参考

4.1 主命令（交互式 TUI）

codex [OPTIONS] [PROMPT]

常用选项：

示例：

# 直接启动 TUI
codex

# 带初始 Prompt 启动
codex "解释一下这个项目的目录结构"

# 指定模型和工作目录启动
codex -m gpt-5.4-mini --path ~/projects/myapp "帮我写单元测试"

# 附带截图启动
codex --image screenshot.png "根据截图修复这个 UI 问题"

4.2 exec — 非交互式执行

codex exec [OPTIONS] "<prompt>"
# 简写：
codex e "<prompt>"

常用选项：

示例：

# 简单一次性任务
codex exec "给所有 Python 文件加上类型注解"

# CI 环境中使用（JSON 输出 + 无沙箱）
codex exec --json --yolo "运行测试并输出失败原因"

# 指定目录 + 保存结果
codex exec --cd ~/project --output-last-message result.txt "生成 README"

# 使用管道传入 Prompt
echo "分析这个日志文件" | codex exec -

4.3 resume — 恢复会话

# 交互式选择历史会话
codex resume

# 恢复最近一次会话（当前目录）
codex resume --last

# 恢复任意目录的最近会话
codex resume --last --all

# 恢复指定 ID 的会话
codex resume <session-id>

# 恢复并附加新 Prompt（非交互）
codex exec resume --last "继续实现上次的计划"

4.4 fork — 分支会话

# 打开会话选择器后创建分支
codex fork

# 从最近的会话创建分支
codex fork --last

分支会话保留原始对话的完整记录，在新线程中独立推进，适合探索不同实现方向。

4.5 mcp — 管理 MCP 服务器

# 查看所有 MCP 命令
codex mcp --help

# 添加 MCP 服务器（stdio 类型）
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 添加带环境变量的 MCP 服务器
codex mcp add myserver --env TOKEN=xxx -- npx -y my-mcp-package

# 列出已配置的 MCP 服务器
codex mcp list

# 删除 MCP 服务器
codex mcp remove context7

# 对 MCP 服务器进行 OAuth 认证
codex mcp auth <server-name>

4.6 features — 功能开关

# 查看所有功能标志及其状态
codex features list

# 开启功能（持久化写入 config.toml）
codex features enable unified_exec

# 关闭功能
codex features disable shell_snapshot

4.7 其他子命令

# 认证管理
codex auth              # 登录
codex auth logout       # 退出登录

# 将 Codex 作为 MCP Server 运行（供其他 Agent 调用）
codex mcp-server

# 在 Codex 沙箱中运行任意命令（调试用）
codex sandbox -- <command>

# 检查执行策略规则
codex execpolicy check -- <command>

# 打开桌面 App（macOS）
codex app [<workspace-path>]

# 应用 Codex Cloud 任务生成的 diff 到本地
codex apply  # 简写：codex a

5. 会话内命令（Slash Commands）

在 TUI 的输入框中输入 / 可调出命令列表，继续输入字母过滤。

5.1 会话管理

5.2 配置与状态

5.3 代码与内容

5.4 多 Agent

5.5 自定义 Slash Commands

在 ~/.codex/ 或项目 .codex/ 目录下创建文件即可定义自定义命令：

# 自定义命令文件路径示例
~/.codex/slash-commands/pr-review.md

文件内容为提示词模板，在 TUI 中输入 /pr-review 即可调用。

6. 会话内快捷键与交互技巧

7. 常用工作流程

7.1 日常功能开发

# 1. 进入项目目录
cd ~/projects/myapp

# 2. 启动 Codex（带初始 Prompt）
codex "在 src/auth 模块下实现 JWT 刷新 Token 逻辑，参考 @src/auth/login.ts 的写法"

# 3. TUI 内查看计划，确认后审批执行
# 4. 查看 diff，如有问题注入修正指令
# 5. 完成后提交

7.2 代码评审（提交前）

codex
# TUI 内输入：
/review
# 选择"Review uncommitted changes"
# Codex 会报告安全、逻辑、测试等方面的风险

7.3 CI/CD 自动化

# .github/workflows/codex.yml 示例
- name: Run Codex
  run: |
    codex exec --yolo --json \
      "运行测试套件，修复所有失败用例，不要修改测试文件本身"

7.4 大任务并行（Subagents）

codex "将以下三个任务并行处理：
1. 重构 src/utils 下的所有文件，统一错误处理方式
2. 为 src/api 下所有路由补充 OpenAPI 注释
3. 更新 README 中的安装步骤"
# Codex 会自动 spawn 子 Agent 并行执行

7.5 恢复中断任务

# 恢复最近会话并补充新指令
codex exec resume --last "继续昨天的重构任务，重点完成 payment 模块"

7.6 使用管道与脚本集成

# 将错误日志传入 Codex 分析
cat error.log | codex exec - --output-last-message analysis.txt

# 批量处理（JSON 输出）
codex exec --json "生成迁移脚本" | jq '.content'

8. 常用功能详解

8.1 图片输入

Codex 支持将截图、设计稿等图片作为输入：

# 命令行附带图片
codex --image mockup.png "根据这个设计稿实现登录页面"

# 多张图片（逗号分隔）
codex --image before.png,after.png "对比这两张截图，找出差异"

TUI 中也可以直接粘贴图片（部分终端支持）。

8.2 网页搜索

# 启用实时网页搜索
codex --search "查找 React 19 的 breaking changes 并更新依赖"

# 通过配置永久设置
# 在 config.toml 中：
# web_search = "live"

8.3 代码评审

TUI 内使用 /review，支持四种模式：

• Review uncommitted changes：所有未提交更改（包括未暂存）
• Review against a base branch：与上游分支的 diff
• Review a commit：选择指定 commit SHA
• Custom review instructions：自定义评审重点（如"专注无障碍回归"）

8.4 会话恢复与分支

# 查看会话 ID（在 /status 或 ~/.codex/sessions/ 中）
ls ~/.codex/sessions/

# 恢复特定会话
codex resume <session-id>

# 分支探索不同方案
codex fork --last

8.5 Subagents（并行子 Agent）

在 Prompt 中明确要求并行时，Codex 会 spawn 多个子 Agent：

"请并行完成以下任务：[任务1]、[任务2]、[任务3]"

注意：每个子 Agent 独立消耗 Token 配额。

8.6 OSS/本地模型（Ollama）

# 启动 Ollama 后
codex --oss "用 qwen2.5-coder 分析这个函数"

# 在 config.toml 中配置
# model_provider = "oss"

9. 配置文件详解

配置文件路径：~/.codex/config.toml（全局）或 <project>/.codex/config.toml（项目级）。

配置优先级（从高到低）：命令行 -c 选项 → 项目配置（当前目录到项目根） → 用户配置 → 系统配置 → 内置默认值。

9.1 核心配置示例

# ============================================================
# 核心模型配置
# ============================================================
model = "gpt-5.4"
# model = "gpt-5.4-mini"      # 更快、更经济的选项

# ============================================================
# 审批与沙箱策略
# ============================================================
approval_policy = "on-request"
# "untrusted"      - 所有操作都需要审批（最安全）
# "on-request"     - 只在需要时审批（推荐交互使用）
# "never"          - 全自动（推荐 CI 使用）

sandbox_mode = "workspace-write"
# "read-only"          - 只读，不执行写操作
# "workspace-write"    - 可写当前工作区（推荐）
# "danger-full-access" - 完全访问（谨慎使用）

# ============================================================
# 网页搜索
# ============================================================
web_search = "cached"
# "cached"   - 使用 OpenAI 缓存索引（默认，更安全）
# "live"     - 实时联网搜索
# "disabled" - 关闭搜索

# ============================================================
# 推理配置
# ============================================================
model_reasoning_effort = "high"
# "minimal" | "low" | "medium" | "high"

# ============================================================
# TUI 配置
# ============================================================
[tui]
# alternate_screen = true      # 全屏模式（默认开启）
# status_line = ["model", "context_stats", "git_branch"]

# ============================================================
# Shell 环境策略
# ============================================================
[shell_environment_policy]
inherit = "core"              # "none" | "core" | "all"
exclude = ["AWS_*", "AZURE_*"]  # 不传递给子进程的变量
# include_only = ["PATH", "HOME", "MY_VAR"]

# ============================================================
# 模型 Provider（自定义/代理）
# ============================================================
# model_provider = "proxy"
# [model_providers.proxy]
# name = "Internal LLM Proxy"
# base_url = "http://proxy.example.com"
# env_key = "OPENAI_API_KEY"

# Azure 示例
# [model_providers.azure]
# name = "Azure OpenAI"
# base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
# env_key = "AZURE_OPENAI_API_KEY"
# query_params = { api-version = "2025-04-01-preview" }
# wire_api = "responses"

# Ollama 本地模型示例
# [model_providers.ollama]
# name = "Ollama"
# base_url = "http://localhost:11434/v1"
# env_key = ""
# wire_api = "chat"

9.2 Profile（配置剖面）

Profile 允许在不同场景间快速切换配置：

# 在 config.toml 中定义
[profiles.ci]
approval_policy = "never"
sandbox_mode = "danger-full-access"
model = "gpt-5.4-mini"

[profiles.safe]
approval_policy = "untrusted"
sandbox_mode = "read-only"

使用方式：

codex --profile ci "运行所有测试"
codex exec --profile safe "分析代码结构"

9.3 通知钩子

# Agent 完成一个回合时触发外部程序
[notify]
command = ["notify-send", "Codex", "任务完成"]

10. AGENTS.md 使用规范

AGENTS.md 是 Codex 的"项目行为说明书"，在每次会话启动时自动载入。

10.1 文件层级

~/.codex/AGENTS.md          # 全局个人默认配置
<repo>/AGENTS.md            # 仓库级共享规范
<repo>/src/AGENTS.md        # 子目录级规则（优先级更高）
<repo>/AGENTS.override.md   # 最高优先级，用于临时覆盖

10.2 生成初始文件

# 在项目根目录运行
/init   # TUI 内斜杠命令

10.3 内容建议

# AGENTS.md 示例

## 项目概述
这是一个 Next.js 14 全栈应用，使用 TypeScript 和 Prisma ORM。

## 技术栈
- 框架：Next.js 14 (App Router)
- 数据库：PostgreSQL + Prisma
- 测试：Vitest + Testing Library
- 样式：Tailwind CSS

## 代码规范
- 所有新文件必须使用 TypeScript，禁止 `any` 类型
- 组件使用函数式写法，不使用 class 组件
- 每个新功能必须配套单元测试

## 测试规范
- 修改业务逻辑后必须运行 `pnpm test`
- 不要修改 `__tests__` 目录下已有的测试用例

## 禁止操作
- 不要直接修改 `prisma/migrations/` 目录
- 不要删除 `.env.example` 中的任何字段
- 不要在没有测试覆盖的情况下修改 `src/lib/auth.ts`

## 提交规范
使用 Conventional Commits 格式：feat、fix、docs、refactor、test

10.4 自定义文件名

# config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536  # 最大加载字节数

11. MCP（Model Context Protocol）集成

11.1 快速添加

# 添加 Context7（开发文档 MCP）
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 添加带认证的服务
codex mcp add myservice --env API_TOKEN=xxx -- npx -y my-mcp-server

11.2 配置文件方式

# config.toml

# stdio 类型 MCP 服务器
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

# HTTP 类型 MCP 服务器
[mcp_servers.remote-api]
url = "https://mcp.example.com/sse"
bearer_token_env_var = "REMOTE_API_TOKEN"
startup_timeout_sec = 15
tool_timeout_sec = 60
# enabled = false  # 临时禁用

11.3 将 Codex 作为 MCP Server

# 以 MCP Server 方式运行 Codex（供其他 Agent 调用）
codex mcp-server

12. 沙箱与审批策略

12.1 沙箱模式对比

12.2 审批策略对比

12.3 快速低摩擦模式

# --auto 等同于 workspace-write + on-request
codex --auto "重构 utils 模块"

12.4 受保护路径

即使在 workspace-write 模式下，.git/ 和 .codex/ 目录默认保持只读。如需 Codex 执行 git commit 等操作，需在审批后确认。

13. 非交互式模式（CI/脚本）

13.1 基础用法

codex exec "执行任务描述"
# 简写
codex e "执行任务描述"

13.2 JSON 输出模式

codex exec --json "分析项目结构" | jq '.type == "text"'

输出为换行符分隔的 JSON 事件，每行一个状态变化事件。

13.3 GitHub Actions 集成

- name: Codex 代码检查
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  run: |
    codex exec \
      --yolo \
      --cd ${{ github.workspace }} \
      "检查代码中是否有安全漏洞，输出详细报告"

13.4 结构化输出

# 使用 JSON Schema 验证输出
codex exec \
  --response-schema schema.json \
  "分析依赖并返回结构化数据"

14. 使用技巧与最佳实践

14.1 Prompt 构建四要素

一个高质量的 Codex Prompt 包含以下四个要素：

1. 1. 上下文（Context）：指定相关文件、错误信息、背景
2. 2. 任务（Task）：明确要做什么
3. 3. 格式（Format）：期望的输出形式（代码、文档、测试等）
4. 4. 验证标准（Done criteria）：如何判断任务完成

"在 @src/api/users.ts 中实现用户分页查询接口，
参考 @src/api/products.ts 的写法，
添加对应的 Zod 校验 schema，
完成后运行

14.2 @ 文件引用

在 TUI 输入框中输入 @ 触发工作区文件模糊搜索：

"参考 @src/utils/logger.ts，为所有 API 路由添加统一日志"

14.3 使用外部编辑器写长 Prompt

按 Ctrl+G 打开 $VISUAL/$EDITOR 编辑器，写完保存后自动发送：

# 配置 VS Code 为编辑器
export VISUAL="code --wait"

14.4 善用 Git 检查点

在重大任务前后创建 Git commit，方便回滚：

git add -A && git commit -m "checkpoint: before Codex refactor"
codex "重构整个 auth 模块"
# 如果不满意：git reset --hard HEAD~1

14.5 上下文压缩

长对话中使用 /compact 命令压缩上下文，释放 Token 空间，避免超出上下文窗口：

/compact

Codex 也会在必要时自动压缩。

14.6 利用 AGENTS.md 积累团队知识

每次发现 Codex 反复犯同类错误（如忘记某个约定），将规则写入 AGENTS.md，形成团队共享的"AI 使用手册"。

14.7 模型按需切换

# TUI 内切换
/model

# 启动时指定
codex -m gpt-5.4-mini "快速修复这个 typo"

14.8 多配置 Profile 管理

为不同场景（开发、CI、安全分析）定义不同 Profile：

codex --profile dev "正常开发任务"
codex --profile ci  exec "自动化任务"
codex --profile safe "审查陌生代码"

14.9 使用 ! 前缀运行 Shell 命令

在 TUI 输入框中直接运行 Shell 命令，输出作为 Codex 的上下文：

!git status
!pnpm test 2>&1 | tail -20

14.10 自定义 Slash Commands

将常用的 Prompt 模板封装为 Slash Command，供团队复用：

# 文件：~/.codex/slash-commands/security-audit.md
# 内容：
对当前工作区进行安全审计，重点检查：
1. SQL 注入风险
2. XSS 漏洞
3. 不安全的依赖版本
4. 硬编码的 secrets
输出格式：按严重程度分级，每项给出具体文件和修复建议

15. 注意事项与常见问题

15.1 安全注意事项

• 永远不要在生产环境直接使用 --yolo / danger-full-access，除非运行在完全隔离的容器中
• 网页搜索结果存在提示注入（Prompt Injection）风险，建议保持默认的缓存模式（cached）
• API Key 不要写入代码或 AGENTS.md，使用环境变量管理
• 项目级 .codex/config.toml 仅在"受信任项目"中生效，不要将敏感配置提交到公开仓库
• shell_environment_policy 中使用 exclude = ["AWS_*", "*SECRET*", "*TOKEN*"] 防止密钥泄露到子进程

15.2 性能与成本

• Subagents 并行执行会倍增 Token 消耗，仅在确实需要并行时使用
• 长会话中定期使用 /compact 压缩上下文
• 轻量任务（文件浏览、简单问答）优先使用 gpt-5.4-mini 以节省配额

15.3 Windows 用户

• Windows 原生支持为实验性，推荐在 WSL（Windows Subsystem for Linux）环境中使用
• Windows 原生使用时需在 config.toml 中设置：

[windows]
sandbox = "elevated"

15.4 Git 仓库要求

• Codex 默认要求在 Git 仓库中运行
• 非 Git 目录使用时添加 --allow-no-git 选项
• 自定义项目根标记：

project_root_markers = [".git", ".hg", "pyproject.toml"]

15.5 常见报错处理

16. 模型选择参考

推荐默认：gpt-5.4（如未在 config.toml 中指定，Codex 会自动选择推荐模型）

附录：快速参考卡

# 安装
npm install -g @openai/codex

# 启动
codex                        # 交互式 TUI
codex "做某件事"              # 带初始 Prompt

# 非交互
codex exec "任务"            # 执行并退出
codex e "任务" --json        # JSON 输出流

# 会话管理
codex resume --last          # 恢复最近会话
codex fork --last            # 分支最近会话

# MCP 管理
codex mcp add name -- cmd    # 添加 MCP 服务器
codex mcp list               # 列出服务器

# 功能管理
codex features list          # 查看功能标志
codex features enable <flag> # 开启功能

# TUI 内常用斜杠命令
/model    /review    /clear
/compact  /fork      /status
/copy     /init      /exit

文档整理自 OpenAI Codex 官方文档[2] · 最后更新：2026 年 3 月

引用链接

[1] GitHub Releases: https://github.com/openai/codex/releases
[2] OpenAI Codex 官方文档: https://developers.openai.com/codex