Some content in this article was created with AI assistance. Please verify as needed.

Codex CLI 是 OpenAI 官方的本地终端 coding agent。它可以在选定目录中读代码、改文件、跑命令。Codex app、IDE extension、CLI、Web/Cloud 是不同入口，这篇只记我主要用的 CLI。

安装和启动

官方推荐的 standalone 安装方式是：

1
curl -fsSL https://chatgpt.com/codex/install.sh | sh

启动：

1
codex

第一次运行会提示登录，可以用 ChatGPT 账号，也可以用 API key。不同 ChatGPT 计划里的 Codex 权益以官方 pricing 页面为准。

Windows 可以直接在 PowerShell 里跑；需要 Linux 原生环境时再用 WSL2。

常用命令

1
2
3
4
5
6
codex
codex --version
codex login
codex exec "summarize this repository"
codex exec --cd . "run the relevant tests"
codex completion powershell

我常用或需要知道的子命令：

  • codex：启动终端 CLI。
  • codex app：启动 Codex 桌面 app。
  • codex exec / codex e：非交互执行任务，适合脚本或 CI 风格任务。
  • codex apply：应用 Codex Cloud task 生成的 diff。
  • codex login：登录或切换认证方式。
  • codex debug models：查看 Codex 看到的模型目录。
  • codex completion：生成 shell completion。

codex exec 可以用 --cd 指定工作目录，也可以用 -c key=value 做一次性配置覆盖。--dangerously-bypass-approvals-and-sandbox / --yolo 会绕过审批和沙箱，除非是在隔离 runner 里，否则不建议碰。

config.toml

Codex 用户级配置：

1
~/.codex/config.toml

项目或子目录级配置：

1
.codex/config.toml

Codex 只会在信任项目后加载项目内 .codex/ 配置。优先级从高到低：

  1. CLI flags 和 --config 覆盖。
  2. 项目 .codex/config.toml，从项目根到当前目录，越近优先级越高。
  3. --profile 选择的 profile 文件，例如 ~/.codex/profile-name.config.toml。
  4. 用户配置 ~/.codex/config.toml。
  5. 系统配置，例如 Unix 上的 /etc/codex/config.toml。
  6. 内置默认值。

常见配置：

1
2
3
4
5
model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

model 和 model_reasoning_effort 控制默认模型和推理强度。approval_policy 控制 Codex 什么时候暂停询问。sandbox_mode 控制本地命令的文件系统和网络访问范围。

权限、审批和沙箱

本地命令执行最好按最小权限配置。常见沙箱模式：

  • read-only：只读，适合浏览代码和问答。
  • workspace-write：允许写当前 workspace，适合常规开发任务。
  • danger-full-access：去掉本地沙箱限制，只应在明确需要且风险可控时使用。

官方也在推进 permission profiles，可以用 default_permissions 和 [permissions.<name>] 定义文件系统和网络策略。内置 profile 包括：

  • :read-only
  • :workspace
  • :danger-full-access

我的基本做法：

  • 日常默认 workspace-write + on-request。
  • 不给默认网络访问，除非任务确实需要下载依赖或查远端资源。
  • 对 .env、secrets、凭据目录保持 deny。
  • 不在普通开发目录使用 danger-full-access 或 --yolo。

AGENTS.md

Codex 使用 AGENTS.md 作为项目说明文件。项目事实、构建命令、测试命令、目录约定和安全边界都适合放这里。

常见结构：

1
2
3
4
repo/
  AGENTS.md
  src/
    AGENTS.md

通用写法放在 AGENTS.md 那篇。这里记一点就够：希望 Codex 稳定遵守的长期规则，应该写进 AGENTS.md，不要每次对话重复粘贴。

CLI slash commands

Codex CLI 里常用 slash commands：

  • /model：选择当前模型和可用 reasoning effort。
  • /plan：进入 plan mode，让 Codex 先给执行计划。
  • /status：查看当前模型、approval policy、writable roots、context 等状态。
  • /permissions：调整当前会话权限。
  • /debug-config：检查配置层和策略要求。
  • /fast：在模型目录支持时切换 Fast tier。
  • /personality：切换沟通风格。
  • /goal：设置或查看当前 task goal。
  • /quit / /exit：退出 CLI。

codex cli 有一个 /ide 命令，在 vscode 中的终端可以用，但是要求 vscode 安装 codex 对应插件以配合使用。

适合的使用方式

  • 复杂改动先用 /plan，确认方向后再让 Codex 实施。
  • 频繁任务用 codex exec 脚本化，但不要默认绕过沙箱。
  • 项目规则写进 AGENTS.md，个人默认行为写进 ~/.codex/config.toml。
  • 需要临时覆盖模型、沙箱、profile 时优先用 CLI flag 或 -c key=value。
  • 运行前用 /status 确认模型、权限和工作目录，尤其是在多个仓库之间切换时。

非交互式运行

下面详细整理一下 codex exec 的基本用法。codex exec 用于在非交互模式下运行 Codex，也可以简写为 codex e。

最基本的用法是直接加上一段提示词，例如：

1
codex exec "summarize this repository"

在默认格式化输出下，运行过程中的进度信息会输出到 stderr，最终的 agent message 会输出到 stdout。因此在非交互模式下，通常可以通过重定向或管道把最终输出接入到后续步骤。

例如，可以直接重定向到文件中：

1
codex exec "summarize this repository" > summary.md

如果希望显式地把最后一个 agent message 写入文件，可以使用 -o / --output-last-message 选项：

1
codex exec "summarize this repository" -o summary.md

需要注意的是，-o 的作用是把最终消息写入指定文件；最终消息通常仍然会打印到 stdout。

输出相关还有一个容易产生歧义的选项 --json。这个选项并不是要求最终回答是一个结构化 JSON，而是让 stdout 输出详细的 JSON lines 事件流，即每一行都是一个 JSON 对象。它更适合调试、CI 日志分析，或者需要追踪 agent 执行过程的场景。

如果要求结构化输出，也就是希望最终回答必须是一个满足指定约束的 JSON 字符串，那么应该使用 --output-schema 来约束最终回答。例如：

1
2
3
codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o metadata.json

这里 --output-schema 负责约束最终输出的 JSON 结构，-o 则只是把最终结果保存到文件中，方便后续脚本读取。

关于输入，也有一些需要注意的用法。

首先，可以直接使用 stdin 作为完整 prompt：

1
cat prompt.txt | codex exec -

也可以同时使用任务指令和 stdin：

1
npm test 2>&1 | codex exec "summarize this test output"

此时命令行中的字符串是任务指令，stdin 则作为附加上下文传给 Codex。这种用法很适合总结测试输出、编译错误、lint 结果等。

如果不想先切换目录，也可以用 -C / --cd 指定工作目录：

1
codex exec -C /path/to/repo "summarize this repository"

codex exec 也可以 resume 之前的 session，例如：

1
codex exec resume --last "fix this code"

为了安全考虑，codex exec 默认通常只具有只读权限。如果需要它修改工作区文件，需要显式提高 sandbox 权限，例如：

1
codex exec --sandbox workspace-write "fix this code"

如果在隔离的 runner、容器或虚拟机中运行，也可以使用更高权限：

1
codex exec --sandbox danger-full-access "fix this code"

但 danger-full-access 应该谨慎使用，因为它会放宽沙箱限制。

此外，codex exec 默认要求在 git 仓库中运行。如果需要在非 git 仓库中运行，可以加上 --skip-git-repo-check：

1
codex exec --skip-git-repo-check "summarize this folder"

还有几个常用但不必展开太多的选项：

可以用 -m / --model 指定本次运行使用的模型：

1
codex exec -m gpt-5.5 "review this diff"

可以用 -p / --profile 使用配置文件中的某个 profile：

1
codex exec -p my-profile "run the usual repo checks"

如果只是一次性的自动化任务，不希望持久化本次 session，可以使用 --ephemeral：

1
codex exec --ephemeral "triage this repository"

如果任务需要参考图片，也可以用 -i / --image 附加图片输入：

1
codex exec -i screenshot.png "explain this error"

在 CI 或自动化环境中，codex exec 通常会复用已有的 CLI 登录状态；如果需要临时提供 API key，可以只在单次命令中设置环境变量：

1
CODEX_API_KEY=... codex exec --json "triage open bug reports"

不过在 CI 中不建议把 API key 设置成整个 job 的全局环境变量，因为后续由仓库脚本控制的步骤也可能访问到它。更安全的做法是只在调用 codex exec 的那一步提供凭据。

参考