Codex CLI 实战手册：常用指令、案例与个人开发者最佳实践

01、Codex CLI 是什么

Codex CLI 是 OpenAI 官方推出的命令行编码 Agent。它在终端中运行，直接操作你的本地代码仓库：读文件、执行 shell 命令、写出 diff——你可以把它理解为一个能在你眼皮底下帮你写代码、改 bug、做评审的 AI 搭档。

Codex 当前有多个产品形态，CLI 定位明确：终端优先、本地仓库深度集成。

示意图

02、安装与登录

安装（本机实测 codex-cli 0.128.0，npm 最新 0.146.0）：

# npm 全局安装（全平台，包括 Windows）
npm install -g @openai/codex

# macOS 也可以用 Homebrew
brew install codex

登录有三种方式：

# 方式 1：浏览器 OAuth（默认，最常用）
codex login

# 方式 2：无头环境用 API Key
echo $OPENAI_API_KEY | codex login --with-api-key

# 方式 3：远程 / SSH 无浏览器环境
codex login --device-auth

# 查看登录状态
codex login status

# 登出
codex logout

# 升级到最新版
codex update

03、交互式 TUI 模式

直接运行 codex "帮我加一个登录接口" 就进入全屏 TUI（Terminal UI）。Agent 会读取当前目录的代码，跟你边聊边改。

常用全局选项（交互和非交互均可用）：

TUI 内斜杠命令（按 / 弹出，从本机 codex.exe 二进制字符串取证）：

常用：/model /approvals /init /compact /diff /review /status /new /quit /resume /fork
管理：/mcp /skills /permissions /features /experimental
反馈：/feedback /plan /ps /rollout /rename /agent /logout

特别说明：/init 会扫描当前仓库并生成 AGENTS.md——这就是 Codex 的「项目说明书」，Agent 会在每次对话中自动加载它来理解你的项目约定。

04、命令全景速查

05、非交互模式 codex exec

codex exec 是自动化与 CI 的核心。它不在 TUI 中交互，而是执行完就退出。

# 基本用法
codex exec "在 src/utils.ts 中加一个 UUID 生成函数"

# 从 stdin 读指令（文件内容自动追加为 <stdin> 块）
git diff HEAD~3 | codex exec - "把这三个 commit 的改动总结成中文 changelog"

# 输出 JSON 事件（方便程序消费）
codex exec --json "列出 src/ 下所有未使用的导入" | jq -r ".final_message"

# 结构化输出：指定 JSON Schema，结果写入文件
codex exec --output-schema response_schema.json -o result.json \
  "分析代码库中所有 SQL 注入风险点"

# 一次性任务，不保留会话文件
codex exec --ephemeral "快速检查 .env.example 与 .env 的一致性"

# 在 CI 中运行，不在 git 仓库内也可以
codex exec --skip-git-repo-check --json \
  "审查下面这段配置的安全性" < k8s_deployment.yaml

CI 集成示例（GitHub Actions 风格）：

- name: AI Code Review
  run: |
    codex review --base origin/main \
      --json > review_result.json
    python scripts/post_review_comment.py review_result.json

06、代码评审 codex review

codex review 专门用于只评审不修改的场景，支持多种 diff 来源：

# 评审当前分支相对于 main 的改动
codex review --base main

# 评审未提交的改动（已暂存 + 未暂存 + 未跟踪）
codex review --uncommitted

# 评审单个 commit
codex review --commit HEAD~1 --title "重构用户模块"

# 自定义评审重点
codex review --base main "重点审查事务边界和异常处理"

# 从管道传入额外上下文
git log --oneline HEAD~5..HEAD | codex review --uncommitted -

Pre-push hook 示例（.git/hooks/pre-push）：

#!/bin/sh
echo "Codex 正在审查未提交改动..."
codex review --uncommitted --json > /tmp/codex_review.json
# 有严重问题时阻止推送
if grep -q '"severity":"critical"' /tmp/codex_review.json; then
  echo "发现严重问题，推送已阻止"
  exit 1
fi

07、会话管理 resume / fork

Codex 的每次交互（包括 exec 的非交互任务）都会保存为会话。你可以随时接续或分支：

# 继续最近的会话（最常用）
codex resume --last

# 启动会话选择器（默认按当前目录过滤）
codex resume

# 查看所有目录的会话
codex resume --all

# 继续上次的非交互会话
codex resume --last --include-non-interactive

# 继续特定会话
codex resume 019fb8a3-4874-7510-9392-f01dbc2cc32c "从刚才断掉的地方继续"

# 从历史会话分支新对话（保留上下文但不影响原会话）
codex fork --last "换一种方案试试"

在 exec 模式中也可以续接：

codex exec resume --last "继续完成刚才的测试补充工作"

08、MCP：连接外部工具

MCP（Model Context Protocol）让 Codex 能访问外部数据源和工具。本机当前挂载了两个 MCP server：

codex mcp list
# 输出：playwright (stdio, enabled)、notion (http, enabled)

添加 MCP server 的两种方式：

# stdio 方式：启动本地进程通信
# 例：Playwright 浏览器自动化
codex mcp add playwright -- npx @playwright/mcp@latest

# HTTP 方式：连接远程服务
# 例：Notion 工作空间
codex mcp add notion --url https://mcp.notion.com/mcp

# HTTP + Bearer Token 鉴权
codex mcp add internal-api \
  --url https://internal.example.com/mcp \
  --bearer-token-env-var INTERNAL_MCP_TOKEN

# stdio + 环境变量
codex mcp add db-tools --env DB_HOST=localhost -- npx my-db-mcp

管理命令：

codex mcp list          # 列出所有 server
codex mcp get notion    # 查看 notion server 详细配置
codex mcp remove notion # 移除
codex mcp login notion  # 鉴权
codex mcp logout notion # 取消鉴权

把 Codex 自己作为 MCP server 暴露给其他应用：

codex mcp-server  # 通过 stdio 提供 coding agent 能力

09、云端任务与本地 apply

codex cloud 是实验性功能，用于把任务提交到云端离线执行，稍后再拉取结果：

codex cloud list                        # 列出云端任务
codex cloud exec "重构 UserService"      # 提交新任务（不启动 TUI）
codex cloud status <TASK_ID>             # 查看任务状态
codex cloud diff <TASK_ID>               # 查看 diff
codex cloud apply <TASK_ID>              # 将 diff 应用到本地工作树

本地 apply（对接已完成的云端任务 ID）：

codex apply <TASK_ID>    # 等价于 codex cloud apply

10、沙箱与审批：安全模型

Codex 在运行模型生成的 shell 命令时，使用两层保护：沙箱策略 + 审批策略。

沙箱模式（-s）：

审批策略（-a）：

平台原生沙箱后端：

codex sandbox macos   -- ls -la       # macOS: Seatbelt
codex sandbox linux   -- ls -la       # Linux: bubblewrap
codex sandbox windows -- ls -la       # Windows: Restricted Token

严重警告： --dangerously-bypass-approvals-and-sandbox 会跳过所有确认和沙箱限制。仅用于外部沙箱环境（如 Docker 容器）中运行，绝不要在本机使用。

11、config.toml：持久化配置

Codex 的默认配置在 ~/.codex/config.toml。本机真实配置结构（脱敏后）：

model_provider = "custom"
model = "kimi-k3"

[model_providers.custom]
name = "OpenAI"
base_url = "http://127.0.0.1:15721/v1"
wire_api = "responses"
requires_openai_auth = true

[mcp_servers.playwright]
type = "stdio"
command = "npx"
args = ["@playwright/mcp@latest"]

[mcp_servers.playwright.tools.browser_navigate]
approval_mode = "approve"

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

用 profile 管理多套配置：

同一个 config.toml 可以定义多个 profile，通过 -p 切换：

# 用工作配置
codex -p work

# 用个人项目配置
codex -p personal "给这个想法写个 POC"

临时覆盖配置（-c）：

codex -c model="kimi-k3" -c 'sandbox_permissions=["workspace-write"]' \
  "修一下 src/auth.ts 的类型错误"

特性开关：

codex features list            # 查看所有特性开关
codex features enable search   # 开启某个特性
codex features disable search  # 关闭

12、辅助命令

Shell 补全：

codex completion powershell >> $PROFILE    # PowerShell
codex completion zsh >> ~/.zshrc            # Zsh
codex completion bash >> ~/.bashrc          # Bash
codex completion fish > ~/.config/fish/completions/codex.fish

调试工具：

codex debug models         # 输出完整模型目录 JSON
codex debug prompt-input   # 预览模型实际收到的 prompt 内容

启动桌面 App：

codex app  # 打开 Codex 桌面 App（未安装则引导下载）

13、个人开发者最佳实践

规则 1 · 每个仓库写 AGENTS.md

在仓库根目录放 AGENTS.md（或用 /init 自动生成），写清楚项目约定、技术栈、测试习惯。Codex 每次对话都会自动加载，准确率提升显著。

# AGENTS.md 示例要点

- 语言：TypeScript + React，Node.js 后端
- 测试：Jest + Playwright，要求每个 API 至少一个集成测试
- 风格：ESLint + Prettier，缩进 2 空格
- 约定：禁止 any 类型，API 一律 POST

规则 2 · 安全默认：workspace-write + on-request

日常开发用 -s workspace-write -a on-request。模型不会动工作区以外的文件，执行前会征得你的同意。这对绝大多数场景足够了。

规则 3 · --dangerously-bypass-approvals-and-sandbox 绝不在本机用

这个标志只应在 Docker 容器等外部隔离环境中使用。在本机使用时，一次误执行的 rm -rf 就能让你后悔。

规则 4 · exec 一次性任务加 --ephemeral

不加 --ephemeral 的话，每次 codex exec 都会在磁盘上保留会话文件。一次性任务（比如检查、汇总、生成）加 --ephemeral 保持清洁。

规则 5 · CI 用 --json + --output-schema 让输出可被程序消费

不要用 grep 解析 Codex 的输出。用 --json 得到结构化的 JSONL 事件流，或用 --output-schema 约束最终输出的 JSON 格式。这是自动化管线的基础。

规则 6 · review 放进 pre-push / CI

把 codex review --uncommitted 或 codex review --base main 放进 pre-push hook 或 CI 流水线。AI 评审的成本几乎为零，而且模型不会犯「看得太累就放过了」的人类常见错误。

规则 7 · 长任务勤用 resume / fork

Codex 的会话是持久化的。一个跨多天的重构可以拆成几个阶段，每次 codex resume --last 继续。如果要探索备选方案，codex fork --last 分支出来，原会话保持不变。

规则 8 · 截图传 -i，模型看得见

遇到 UI bug，截图后用 -i 传给 Codex。模型能「看」到你的截图，定位问题效率远高于纯文本描述。

codex -i error-dialog.png "这个弹窗应该在点击取消后消失，但它卡住了"

规则 9 · 用 --search 让 Agent 查最新资料

模型的知识有截止日期。遇到需要查阅最新 API 文档、库版本、CVE 的场景，加 --search，Codex 会调用 web_search 工具自动查询。

规则 10 · 保持更新，装好补全

codex update 定期跑。codex completion 装好 tab 补全——这些小细节积累起来，日常使用体验差很多。

14、场景速查表

参考来源说明

本文基于以下一手资料整理，所有命令参数均来自实际 CLI 输出，不存在凭记忆猜测：

codex --help 及各子命令 --help 输出（本机安装 codex-cli 0.128.0）
npm view @openai/codex 验证最新发布版本（0.146.0，2026-07-31）
codex.exe 二进制字符串提取验证 TUI 斜杠命令清单
codex debug models 确认模型目录结构
codex mcp list 确认 MCP server 挂载实况
~/.codex/config.toml 确认配置结构（已脱敏）