一、Codex CLI 是什么？

Codex CLI 是 OpenAI 推出的一个命令行开发助手工具，主要面向开发者，具备以下特点：

• 终端交互式开发助手：可在终端中直接与 AI 对话，分析、修改、生成、运行代码。

• 类 ChatGPT 能力 + 本地代码执行能力：不仅能理解自然语言描述，还能真正操作你的项目文件、运行代码、给出建议并生成补丁。

• 支持多种模式：包括建议（suggest）、自动修改（auto-edit）、全自动（full-auto）。

• 支持多模型和多平台接入：OpenAI、Azure OpenAI、OpenRouter、Gemini、xAI、Groq 等。

• 支持多种配置与历史记录管理。

二、适用场景举例

命令	作用
codex "fix build errors"	自动修复构建错误并展示修改建议
codex "Write unit tests for utils/date.ts"	自动编写单元测试并运行验证
codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$"	解释正则表达式的含义
codex --approval-mode full-auto "Generate SQL migrations"	自动生成迁移脚本并运行

三、安装方式

推荐：通过 npm 安装

npm install -g @openai/codex
# 或者使用 yarn / bun / pnpm

可选：源码安装

git clone https://github.com/openai/codex.git
cd codex/codex-cli
corepack enable
pnpm install
pnpm build
node ./dist/cli.js

四、使用前准备

1. 设置 API Key（环境变量）

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

也可设置多个服务商的密钥（OpenAI、Azure、OpenRouter、Gemini 等）

2. 启动 Codex

codex            # 启动交互式 REPL
codex -m gpt-4   # 指定模型
codex -q "..."   # 静默模式运行

五、安全模型与权限说明

模式	权限说明	是否需要审批
suggest（默认）	只读代码，提供建议	所有写操作需确认
auto-edit	自动打补丁修改代码	shell 命令仍需确认
full-auto	自动读写文件+运行代码	不需要审批（但禁用网络，有限目录）

安全提示：full-auto 模式下也会提示你是否在受 Git 管理的目录外执行。

六、配置文件说明

配置文件存放在 ~/.codex/config.yaml 或 ~/.codex/config.json 中，可设置：

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

完整配置（多服务商示例）：

{
  "model": "o4-mini",
  "provider": "openai",
  "providers": {
    "openai": {
      "name": "OpenAI",
      "baseURL": "https://api.openai.com/v1",
      "envKey": "OPENAI_API_KEY"
    },
    "azure": {
      "name": "AzureOpenAI",
      "baseURL": "https://YOUR_PROJECT_NAME.openai.azure.com/openai",
      "envKey": "AZURE_OPENAI_API_KEY"
    },
    "openrouter": { "...": "..." },
    "gemini": { "...": "..." },
    "xai": { "...": "..." }
  },
  "history": {
    "maxSize": 1000,
    "saveHistory": true,
    "sensitivePatterns": []
  }
}

七、沙箱机制（平台隔离）

• macOS 使用 Apple Seatbelt 机制执行命令。

• Linux 建议使用 Docker 配合 run_in_container.sh 实现沙箱隔离。

八、自定义说明与行为

• 可在 ~/.codex/AGENTS.md 编写行为指导，如：

- Always respond with emojis
- Only use git commands when explicitly requested

九、其他实用参数

参数	用途
--model/-m	指定模型（如 gpt-4、o4-mini）
--approval-mode/-a	权限模式：suggest / auto-edit / full-auto
--quiet/-q	静默模式，不显示 UI
--notify	是否桌面通知
DEBUG=true	显示 API 请求详情（调试用）

十、推荐用法总结

codex "Refactor the Dashboard component to React Hooks"
codex --approval-mode full-auto "Generate unit tests for ./utils"  
codex -q "Look for vulnerabilities and create a report"

---

如需集成到 CI/CD（如 GitHub Actions），也可执行：

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

---

如需进一步说明如何落地到你的 Java/Vue/3D 项目中，我可提供更具体的应用案例。

是否需要我再整理一份实际项目的使用范例？