OpenAI Codex CLI

轻量级终端编码代理

npm install -g @openai/codex

1. 实验性技术免责声明

Codex CLI 是一个处于积极开发中的实验性项目，尚不稳定，可能包含 Bug 或不完整的功能，也可能存在破坏性变更。我们欢迎在社区环境中开放协作，通过提交 Issues、功能请求或 Pull Request 等方式帮助我们改进。

2. 快速开始

  1. 全局安装：

    npm install -g @openai/codex

  2. 设置 API 密钥（仅本会话生效）：

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

    若要长期生效，请将上述行添加到你的 Shell 配置文件（如 ~/.zshrc），或在项目根目录创建 .env 文件：

    OPENAI_API_KEY=your-api-key-here

  3. 交互式运行：

    codex

  4. 带提示运行：

    codex "explain this codebase to me"

  5. 全自动模式示例：

    codex --approval-mode full-auto "create the fanciest todo-list app"

Codex 会在沙箱环境中生成文件、安装依赖并运行，等待你的审批后再将改动提交到工作目录。

3. 为什么选择 Codex?

  • 零配置：仅需提供 API 密钥，即可启动。
  • 安全可靠：全自动模式下禁用网络，运行在独立沙箱。
  • 多模态支持：可传入截图或示意图，直接在终端完成开发任务。
  • 完全开源：随时查看源码并贡献力量。

4. 安全模型与权限

使用 --approval-mode 或交互式提示，控制代理权限：

模式 允许操作 需审批操作
Suggest 读取仓库文件 文件写入、任意 Shell 命令
Auto Edit 读取并写入文件 任意 Shell 命令
Full Auto 读写文件、执行 Shell 命令（网络禁用） 无

4.1. 平台沙箱细节

  • macOS 12+：使用 Apple Seatbelt (sandbox-exec)，将除 $PWD、$TMPDIR、~/.codex 等少数目录外设为只读，同时阻断所有网络请求。
  • Linux：推荐通过 Docker 启动，挂载当前仓库路径，并使用 iptables/ipset 脚本禁止出站流量，仅允许 OpenAI API。详见脚本：codex-cli/scripts/run_in_container.sh。

5. 系统要求

要求 说明
操作系统 macOS 12+、Ubuntu 20.04+/Debian 10+、WSL2
Node.js 22 或更高（LTS 推荐）
Git 2.23+（推荐，用于 PR 辅助）
内存 ≥4 GB（推荐 8 GB）

注意：避免使用 sudo npm install -g，推荐修复 npm 权限问题。

6. CLI 参考

命令 描述 示例
codex 交互式 REPL codex
codex "…" 带初始提示启动 REPL codex "fix lint errors"
codex -q "…" 静默模式，无交互 codex -q --json "explain utils.ts"
`codex completion <bash zsh fish>`

常用标志：--model/-m、--approval-mode/-a、--quiet/-q、--notify

7. 记忆与项目文档

Codex 按以下顺序加载 Markdown 指令：

  1. ~/.codex/instructions.md
  2. 项目根目录的 codex.md
  3. 当前目录的 codex.md

可通过 --no-project-doc 或设置 CODEX_DISABLE_PROJECT_DOC=1 禁用。

注：本文翻译自早期版本 README。后续版本的 Codex CLI 已将 codex.md 更名为 AGENTS.md，配置文件也从 config.yaml 迁移至 config.toml，请以所用版本的官方文档为准。

8. 无交互 / CI 模式

示例 GitHub Actions：

- name: 使用 Codex 更新 CHANGELOG
  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 可关闭交互式输出。

9. 示例用法

示例 输入命令 效果
1 codex "Refactor the Dashboard component to React Hooks" 将类组件改为 Hooks 并运行测试。
2 codex "Generate SQL migrations for adding a users table" 自动生成迁移并在沙箱 DB 中运行。
3 codex "Write unit tests for utils/date.ts" 生成测试脚本，迭代至通过。
4 codex "Bulk-rename *.jpeg → *.jpg with git mv" 安全重命名并更新引用。
5 codex "Carefully review this repo, and propose 3 high impact well-scoped PRs" 提出 3 个高影响力 PR 建议。
6 codex "Look for vulnerabilities and create a security review report" 生成安全审查报告。

10. 安装

从 npm（推荐） 
npm install -g @openai/codex
从源码构建 
git clone https://github.com/openai/codex.git
cd codex/codex-cli
npm install
npm run build
node ./dist/cli.js
# 或
npm link

11. 配置

在 ~/.codex/config.yaml 中添加：

model: o4-mini
fullAutoErrorMode: ask-user
notify: true

自定义指令示例（~/.codex/instructions.md）：

- 始终使用表情符号回复
- 仅在明确提及时执行 git 命令

12. 常见问题解答

2021 年发布的 Codex 模型与本 CLI 有何关系？

2021 年的 Codex 模型已于 2023 年 3 月弃用，与 CLI 工具无关。

支持哪些模型？

支持所有通过 Responses API 提供的模型，默认 o4-mini，可通过 --model gpt-4.1 或配置文件切换。

为何无法使用 `o3` 或 `o4-mini`？

可能需完成 API 账户验证，才能启用流式响应和链式思考摘要。

如何阻止 Codex 修改我的文件？

在沙箱中执行命令前，输入 n 即可拒绝任何文件写入或命令执行。

Windows 系统支持情况？

仅通过 WSL2 使用，官方测试环境为 macOS 和 Linux（Node ≥ 22）。

13. 资金支持机会

我们推出了 100 万美元 开源资助计划，每份资助额度 25,000 美元，滚动评审。

申请地址：OpenAI Codex 开源资助计划

14. 贡献指南

14.1. 开发流程

  1. 从 main 分支创建主题分支。
  2. 保持更改聚焦，每次 PR 只解决一个问题。
  3. 使用 npm run test:watch 快速反馈。
  4. 确保测试、类型检查和 lint 全部通过。

14.2. 编写高影响力代码变更

  1. 先开 Issue，征求社区意见。
  2. 添加/更新测试，确保覆盖。
  3. 完善文档，更新 README 或示例。
  4. 保持提交原子化，单一功能或修复。

14.3. 提交 Pull Request

  1. 填写 PR 模板或简要说明 What/Why/How。
  2. 本地运行 npm test && npm run lint && npm run typecheck。
  3. 保持与 main 分支同步并解决冲突。

14.4. 评审流程

  1. 指定主要评审者。
  2. 根据反馈进行修改。
  3. 达成共识后由维护者合并（squash-and-merge）。

14.5. 社区价值观

  • 友善包容：遵循 贡献者公约。
  • 假设善意：多包容文字沟通中的歧义。
  • 教与学：发现改进请提交 Issue 或 PR。

14.6. 获取帮助

如有疑问，请打开 Discussion 或 Issue 与我们交流。

14.7. 贡献者许可协议 (CLA)

所有贡献者需签署 CLA，在 PR 评论中添加：

I have read the CLA Document and I hereby sign the CLA

14.8. 快速修复

场景 命令
修改最后一次提交 git commit --amend -s --no-edit && git push -f
GitHub UI 操作 编辑 PR 提交信息并添加 Signed-off-by: Your Name <[email protected]>

14.9. 发布 Codex

  1. 切换到发布分支：

    git checkout -b bump-version

  2. 更新版本号：

    npm run release:version

  3. 提交更新并签名：

    git add codex-cli/src/utils/session.ts package.json
git commit -s -m "chore(release): codex-cli v$(node -p "require('./codex-cli/package.json').version")"

  4. 构建并发布：

    npm run release

  5. 推送分支：

    git push origin HEAD

15. 安全与负责任的 AI

若发现安全漏洞或对模型输出有疑虑，请发送邮件至：[email protected]

16. 许可证

本项目采用 Apache-2.0 许可证。