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：启动终端 TUI。
  • 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 TUI 里常用 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。

适合的使用方式

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

参考