OpenAI Codex CLI 编码助手操作指南

OpenAI Codex CLI 是一个可以在终端中运行的轻量级编码助手，让你在开发过程中能利用 ChatGPT 的推理能力，可以直接运行代码、操作文件和迭代，所有的操作都受到版本控制。

快速入门

全局安装 Codex CLI：

npm install -g @openai/codex

设置 OpenAI API 密钥作为环境变量，注意，这个命令只会在当前终端会话中设置密钥，若要永久设置，请将导出行添加到你的 shell 配置文件（例如 ~/.zshrc）中。

你可以交互式地运行 Codex：

codex

或通过提示输入来运行（也可以选择全自动模式）：

codex "explain this codebase to me"
codex --approval-mode full-auto "create the fanciest todo-list app"

最后 Codex 会为你创建一个文件，在沙箱中运行然后安装任何缺失的依赖项，展示实时结果。你可以批准这些更改，它们会被提交到你当前的工作目录。

Codex 功能

Codex CLI 为希望在版本控制下进行聊天驱动开发的开发者设计，不需要额外的设置，只需你的 OpenAI API 密钥就能使用。Codex 支持全自动批准，保证安全性和稳定性，通过在网络禁用和目录沙箱环境中运行来实现。

Codex 支持多模态功能，可以通过传入截图或图表来实现特定功能。

安全模型和权限

Codex 允许你决定代理的自主权和自动批准策略，通过 --approval-mode 标志（或交互式入门提示）来实现：

• 默认模式（建议）：读取仓库中的任何文件，所有文件写入/补丁，所有 shell/Bash 命令，需要批准。

• 自动编辑：读取并应用文件补丁写入，所有 shell/Bash 命令，需要批准。

• 全自动：读写文件，执行 shell 命令。在全自动模式下，每个命令都在网络禁用且限制在当前工作目录（加上临时文件）中运行，用来实现深度防御。如果目录未被 Git 跟踪，Codex 会在启动时显示警告/确认，来确保安全性。

沙箱

Codex 使用的加固机制依赖于你的操作系统。

• macOS 12+：使用 Apple Seatbelt（sandbox-exec）包装命令，除了少数可写根目录（$PWD、$TMPDIR、~/.codex 等）外，所有内容都放在只读沙盒中。默认情况下，完全阻止出站网络，即使子进程尝试 curl 到某个地方也会失败。

• Linux：推荐使用 Docker 进行沙箱化，Codex 在最小容器镜像内启动自身，并以相同路径挂载你的仓库为读/写。自定义 iptables / ipset 防火墙脚本拒绝所有出站流量，除了 OpenAI API。能提供确定性的、可重复的运行，不需要在主机上具有 root 权限。

系统要求

• 操作系统：macOS 12+、Ubuntu 20.04+/Debian 10+ 或 Windows 11 via WSL2。

• Node.js：22 或更高版本（推荐 LTS）。

• Git（可选，推荐）：2.23+ 用于内置 PR 助手。

• RAM：最低 4GB（推荐 8GB）。

不要运行 sudo npm install -g，修复 npm 权限。

CLI 参考

• codex：交互式 REPL。

• codex "..."：交互式 REPL 的初始提示。

• codex -q "..."：非交互式“安静模式”。

• codex -q --json "explain utils.ts"：关键标志：--model/-m、--approval-mode/-a 和 --quiet/-q。

项目文档

Codex 按以下顺序合并 Markdown 指令：

• ~/.codex/instructions.md：个人全局指导。

• 仓库根目录的 codex.md：共享项目笔记。

• 当前工作目录的 codex.md：子包特定信息。

可以通过 --no-project-doc 或 CODEX_DISABLE_PROJECT_DOC=1 来禁用。

非交互式/CI 模式

在管道中无头运行 Codex，例如 GitHub Action 步骤：

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    codex -a auto-edit --quiet "update CHANGELOG for next release"

设置 CODEX_QUIET_MODE=1 来静音交互式 UI 噪音。

示例

以下是示例，将引号中的文本替换为你自己的任务。

1、codex "Refactor the Dashboard component to React Hooks"：Codex 重写类组件，运行 npm test，显示差异。

2、codex "Generate SQL migrations for adding a users table"：推断你的 ORM，创建迁移文件，在沙箱化数据库中运行它们。

3、codex "Write unit tests for utils/date.ts"：生成测试，执行它们，迭代直到它们通过。

4、codex "Bulk-rename *.jpeg → *.jpg with git mv"：安全地重命名文件并更新导入/使用。

5、codex "Explain what this regex does: A-Z]).{8,}$"：输出逐步的人类解释。

6、codex "Carefully review this repo, and propose 3 high impact well-scoped PRs"：在当前代码库中提出有影响力的 PR。

7、codex "Look for vulnerabilities and create a security review report"：查找并解释安全漏洞。

安装

从 npm（推荐）：

npm install -g @openai/codex
# 或者
yarn global add @openai/codex

从源码构建：

# 克隆仓库并导航到 CLI 包
git clone https://github.com/openai/codex.git
cd codex/codex-cli
# 安装依赖并构建
npm install
npm run build
# 运行本地构建的 CLI
node ./dist/cli.js --help
# 或者全局链接命令以方便使用
npm link

配置

Codex 在 ~/.codex/ 中查找配置文件。

# ~/.codex/config.yaml
model: o4-mini # 默认模型
fullAutoErrorMode: ask-user # 或 ignore-and-continue

可以定义自定义指令：

# ~/.codex/instructions.md
- Always respond with emojis
- Only use git commands if I explicitly mention you should