550 - 《调研 OpenAI Codex CLI》

看到 OpenAI 新出了 Codex CLI，正好在做的事也是类似的，于是做下调研。包含介绍、实现和想法。

1、OpenAI CodeX CLI 介绍。

OpenAI CodeX CLI 是一个轻量级的交互式 Code Agent 工具，让开发者可以基于自然语言做代码修改和命令运行，并通过沙箱环境确保安全性。

快速上手（注：1）环境变量里要有 OPENAI_API_KEY 的配置，2）不要安装到 codex 这个包了，我被坑了一会，安装后发现怎么就不对呢。。）。

npm install -g @openai/codex
codex "explain this codebase to me"

特点。

• 安全性。1）通过 --approval-mode 指定命令审批模式，提供 Suggest、Auto Edit 和 Full Auto 三种模式，控制 AI 的自主程度，确保用户对敏感操作有控制权，2）所有命令默认在沙盒环境中运行，限制网络访问和文件系统权限，macOS 下用 Apple Seatbelt（sandbox-exec），将命令限制在只读监狱中，仅允许特定目录（如 $PWD）可写；Linux 下用 Docker 容器，通过自定义防火墙脚本限制网络访问，仅允许与 OpenAI API 通信。
• 其他特点都不太重要，比如 Zero Config、多模态、支持非交互模式、codex.md 提供上下文、支持 json 输出等，这些在其他的类似产品里面都比较常见。

其配置文件在 ~/.codex 下，有 config.json 和 instructions.md 。顾名思义，应该比较好理解他们两个是分别在做什么的。

命令行参数。

• --quiet 或 -q，安静模式，或者叫非交互模式，减少终端输出，仅返回核心结果，适合 CI/CD 或脚本化使用。
• --model 或 -m，指定 AI 模型，默认模型为 o4-mini
• --approval-mode 或 -a，设置 Agent 的自主程度和审批策略。1）默认 suggest：仅读取文件，任何写入或命令执行需用户批准，2）auto-edit：自动应用文件写入和补丁，但命令执行仍需批准，3）full-auto：完全自动，读写文件和执行命令均无需批准（在沙盒环境中运行）
• --json，以 JSON 格式输出结果，适用于程序化处理或与其他工具集成。
• --no-project-doc，禁用项目文档加载，阻止 Codex 读取 ~/.codex/instructions.md 或项目根目录下的 codex.md 文件，适合用户希望避免预设指令影响当前任务的情况，也可通过环境变量 CODEX_DISABLE_PROJECT_DOC=1 全局禁用。
• --help，略。

环境变量。

• OPENAI_API_KEY：设置 OpenAI API 密钥，必需参数，用于认证 API 调用。
• CODEX_QUIET_MODE=1：等同于 --quiet，启用安静模式。
• CODEX_DISABLE_PROJECT_DOC=1：等同于 --no-project-doc，禁用项目文档加载。

一些场景。

• 自动化 CI/CD 任务：codex -a auto-edit --quiet "update CHANGELOG for next release"，在 GitHub Actions 中自动更新日志，减少人工干预。
• 交互式代码重构：codex --model gpt-4o "Refactor the Dashboard component to React Hooks"，使用更强模型进行复杂重构任务，并通过交互模式确认结果。
• 非交互式代码解释：codex -q --json "explain this regex: ^(?=.*[A-Z]).{8,}$"，以 JSON 格式输出正则表达式解释，适合集成到其他工具。

2、代码实现。

基础介绍。

• 需要 Node 22 + 。
• 工程化方案。1）TypeScript + Vitest + npm + Prettier + ESLint，2）Build 基于 codex-cli/build.mjs 自定义的构建脚本。
• 命令行交互和 Claude Code 的实现一样，基于 Ink，感觉这是复杂交互的必选项。
• Function Call 里只有一个 Tool 如下，然后在 handleFunctionCall 处理 Tool 调用，并且通过提示词额外定义了 apply_patch 的虚拟命令。

{
  type: "function",
  name: "shell",
  description: "Runs a shell command, and returns its output.",
  strict: false,
  parameters: {
    type: "object",
    properties: {
      command: { type: "array", items: { type: "string" } },
      workdir: {
        type: "string",
        description: "The working directory for the command.",
      },
      timeout: {
        type: "number",
        description:
          "The maximum time to wait for the command to complete in milliseconds.",
      },
    },
    required: ["command"],
    additionalProperties: false,
  },

核心提示词。

You are operating as and within the Codex CLI, a terminal-based agentic coding assistant built by OpenAI. It wraps OpenAI models to enable natural language interaction with a local codebase. You are expected to be precise, safe, and helpful.

You can:
- Receive user prompts, project context, and files.
- Stream responses and emit function calls (e.g., shell commands, code edits).
- Apply patches, run commands, and manage user approvals based on policy.
- Work inside a sandboxed, git-backed workspace with rollback support.
- Log telemetry so sessions can be replayed or inspected later.
- More details on your functionality are available at `codex --help`

The Codex CLI is open-sourced. Don't confuse yourself with the old Codex language model built by OpenAI many moons ago (this is understandably top of mind for you!). Within this context, Codex refers to the open-source agentic coding