OpenAI Codex Cli

OpenAI Codex Cli

在您的终端中运行的轻量级编码代理

npm i -g @openai/codex

快速入门

全局安装：

 

npm install -g @openai/codex

 

接下来，将您的 OpenAI API 密钥设置为环境变量：

 

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

 

注意：此命令仅针对当前终端会话设置密钥。要使其永久生效，请将此export行添加到 Shell 的配置文件中（例如~/.zshrc）。

交互运行：

 

codex

 

或者，以提示符作为输入运行（也可以在Full Auto模式下运行）：

 

codex "explain this codebase to me"

 

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

 

就是这样——Codex 将搭建一个文件，在沙盒中运行它，安装所有缺失的依赖项，并实时显示结果。批准更改后，它们将提交到您的工作目录。

---

为什么选择 Codex？

Codex CLI 专为那些已经习惯使用终端，并希望拥有 ChatGPT 级别推理能力以及实际运行代码、操作文件和迭代能力的开发者打造——所有这些都在版本控制之下。简而言之，它是一种聊天驱动的开发方式，能够理解并执行您的代码库。

• 零设置- 带上您的 OpenAI API 密钥即可工作！
• 完全自动批准，同时通过运行网络禁用和目录沙盒确保安全+可靠
• 多模式——通过截图或图表来实现功能✨

它是完全开源的，因此您可以看到它的发展并为其做出贡献！

---

融资机会

我们很高兴启动一项100 万美元的计划，支持使用 Codex CLI 和其他 OpenAI 模型的开源项目。

• 赠款以25,000 美元API 信用增量发放。
• 申请将以滚动方式接受审核。

有兴趣吗？ 点击此处申请。

---

安全模型和权限

Codex 允许您通过标志（或交互式入职提示）决定代理获得 多少自主权和自动批准政策：--approval-mode

模式	代理人无需询问即可做什么	仍需批准
建议 （默认）	• 读取 repo 中的任何文件	•所有文件写入/修补 •所有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 权限即可进行确定性、可重复的运行。您可以阅读更多内容run_in_container.sh

这两种方法对于日常使用都是透明的codex——您仍然可以从 repo 根目录运行并像往常一样批准/拒绝步骤。

---

系统要求

要求	细节
操作系统	macOS 12+、Ubuntu 20.04+/Debian 10+ 或通过 WSL2 的Windows 11
Node.js	22 或更新版本（推荐 LTS）
Git（可选，推荐）	2.23+ 内置 PR 助手
内存	最低 4 GB（建议 8 GB）

永远不要运行sudo npm install -g；而是修复 npm 权限。

---

CLI 参考

命令	目的	例子
codex	交互式 REPL	codex
codex "…"	交互式 REPL 的初始提示	codex "fix lint errors"
codex -q "…"	非交互式“安静模式”	codex -q --json "explain utils.ts"
codex completion <bash|zsh|fish>	打印shell完成脚本	codex completion bash

关键标志：--model/-m、、--approval-mode/-a和--quiet/-q。

---

记忆与项目文档

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

1. ~/.codex/instructions.md– 个人全球指导
2. codex.md在 repo 根目录 – 共享项目说明
3. codex.md在 cwd 中 – 子包细节

使用--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
# or
yarn global add @openai/codex

 

从源代码构建

 

---

配置

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

 

# ~/.codex/config.yaml
model: o4-mini # Default model
fullAutoErrorMode: ask-user # or ignore-and-continue

 

您还可以定义自定义指令：

 

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

 

---

常问问题

OpenAI 于 2021 年发布了一个名为 Codex 的模型 - 这相关吗？

 

我如何阻止 Codex 接触我的 repo？

 

它在 Windows 上运行吗？

 

支持哪些型号？

 

---

贡献

该项目正在积极开发中，代码可能会发生较大变化。开发完成后，我们会更新此消息！

我们更广泛地欢迎贡献——无论您是第一次提交拉取请求，还是经验丰富的维护者。同时，我们关注可靠性和长期可维护性，因此代码合并的门槛特意设得很高。以下指南阐明了“高质量”在实践中的含义，并使整个流程透明友好。

开发工作流程

• 从以下位置创建主题分支main– 例如feat/interactive-prompt。

• 保持你的修改专注。多个不相关的修复应该作为单独的 PR 提交。

• 在开发过程中使用npm run test:watch以获得超快速反馈。

• 我们使用Vitest进行单元测试，使用ESLint + Prettier进行样式测试，使用TypeScript进行类型检查。

• 在推送之前，运行完整的测试/类型/lint 套件：

   

  npm test && npm run lint && npm run typecheck

   

• 如果您尚未签署贡献者许可协议 (CLA)，请添加包含确切文本的 PR 评论

   

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

   

  一旦所有作者签名，CLA-Assistant 机器人就会将 PR 状态变为绿色。

 

 

# Watch mode (tests rerun on change)
npm run test:watch

# Type‑check without emitting files
npm run typecheck

# Automatically fix lint + prettier issues
npm run lint:fix
npm run format:fix

 

编写影响重大的代码更改

1. 从一个问题开始。打开一个新问题或在现有讨论中发表评论，以便我们在编写代码之前就解决方案达成一致。
2. 添加或更新测试。每个新功能或错误修复都应包含测试覆盖率，这些测试覆盖率在更改之前失败，而在更改之后通过。无需 100% 的覆盖率，但目标是获得有意义的断言。
3. 文档行为。如果您的更改影响到用户行为，请更新 README、内联帮助 ( codex --help) 或相关的示例项目。
4. 保持提交的原子性。每次提交都应该编译通过，测试也应该通过。这使得审核和潜在的回滚更容易。

打开拉取请求

• 填写 PR 模板（或包含类似信息）——什么？为什么？如何？
• 在本地运行所有检查（npm test && npm run lint && npm run typecheck）。本地可以发现的 CI 故障会减慢进程。
• 确保您的分支是最新的main并且已经解决了合并冲突。
• 仅当您认为 PR 处于可合并状态时才将其标记为“准备审核” 。

审核流程

1. 一名维护者将被指定为主要审阅者。
2. 我们可能会要求修改，但请不要介意。我们重视这项工作，但我们也重视一致性和长期可维护性。
3. 当大家一致认为 PR 符合标准时，维护者将会压缩并合并。

社区价值观

• 友善包容。尊重他人；我们遵守贡献者契约。
• 假设对方的意图是好的。书面沟通很难——宁可表现得慷慨一些。
• 教与学。如果您发现任何令人困惑的地方，请提交问题或 PR 以进行改进。

获取帮助

如果您在设置项目时遇到问题，想就某个想法寻求反馈，或者只是想打个招呼，请打开讨论或直接跳转到相关问题。我们很乐意为您提供帮助。

让我们携手，让 Codex CLI 成为一款不可思议的工具。祝您 hacking 愉快！ 🚀

贡献者许可协议（CLA）

所有贡献者必须接受 CLA。该流程非常简单：

1. 打开你的拉取请求。

2. 粘贴以下评论（recheck如果您之前已签名，请回复）：

    

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

    

3. CLA-Assistant 机器人会在 repo 中记录您的签名并将状态检查标记为已通过。

不需要特殊的 Git 命令、电子邮件附件或提交页脚。

快速修复

设想	命令
修改上次提交	git commit --amend -s --no-edit && git push -f
仅限 GitHub UI	编辑 PR 中的提交消息 → 添加 Signed-off-by: Your Name <email@example.com>

DCO检查阻止合并，直到 PR 中的每个提交都带有页脚（使用 squash 时这只是一个）。

释放codex

要发布 CLI 的新版本，请运行以下定义的发布脚本codex-cli/package.json：

1. 打开codex-cli目录
2. 确保你位于类似这样的分支上git checkout -b bump-version
3. 将版本升级CLI_VERSION到当前日期时间：npm run release:version
4. 提交版本升级（经 DCO 签字同意）： 
    

    

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

    
5. 复制 README、构建并发布到 npm：npm run release
6. 推送到分支：git push origin HEAD