1- OpenAI Codex CLI

轻量级终端编码代理

npm install -g @openai/codex

1.1- 目录

1. 实验性技术免责声明
2. 快速开始
3. 为什么选择 Codex?
4. 安全模型与权限
   • 平台沙箱细节
5. 系统要求
6. CLI 参考
7. 记忆与项目文档
8. 无交互 / CI 模式
9. 示例用法
10. 安装
11. 配置
12. 常见问题解答
13. 资金支持机会
14. 贡献指南
    • 开发流程
    • 编写高影响力代码变更
    • 提交 Pull Request
    • 评审流程
    • 社区价值观
    • 获取帮助
    • 贡献者许可协议 (CLA)
      • 快速修复
    • 发布 Codex
15. 安全与负责任的 AI
16. 许可证

1.2- 实验性技术免责声明

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

1.3- 快速开始

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

1.4- 为什么选择 Codex?

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

1.5- 安全模型与权限

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

1.5.1- 平台沙箱细节

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

1.6- 系统要求

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

1.7- CLI 参考

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

1.8- 记忆与项目文档

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

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

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

1.9- 无交互 / 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 可关闭交互式输出。

1.10- 示例用法

1.11- 安装

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

1.12- 配置

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

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

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

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

1.13- 常见问题解答

1.14- 资金支持机会

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

申请地址：https://openai.com/form/codex-open-source-fund/

1.15- 贡献指南

1.15.1- 开发流程

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

1.15.2- 编写高影响力代码变更

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

1.15.3- 提交 Pull Request

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

1.15.4- 评审流程

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

1.15.5- 社区价值观

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

1.15.6- 获取帮助

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

1.15.7- 贡献者许可协议 (CLA)

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

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

1.15.7.1- 快速修复

1.15.8- 发布 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
   

1.16- 安全与负责任的 AI

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

1.17- 许可证

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