OpenAI Codex CLI 上手

这篇适合谁

这篇适合想在终端里使用 Codex，既能手动操作、也能放进脚本运行的读者。读完你能装好 Codex CLI、完成登录、用 codex exec 跑一次性任务，并知道沙箱和审批该怎么选。最后一节讲我们在 TellWorld 里怎么用它。

Codex CLI 是什么

Codex CLI 是 OpenAI 的 Codex 命令行客户端。在项目目录里运行 codex 进入交互式会话；运行 codex exec 则把一个任务交给它，不打开交互界面，适合放进脚本或 CI 任务。^[2]^[5]

准备工作

安装方式有几种。README 给出的 macOS 和 Linux 命令是 curl -fsSL https://chatgpt.com/codex/install.sh | sh，Windows 命令是 powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"。也可以用 npm install -g @openai/codex 或 brew install --cask codex 安装。^[2]

登录方式决定你怎么付费。Codex 支持两种登录方式：用 ChatGPT 登录，按订阅获得访问权限；用 API key 登录，按用量计费。^[4] README 建议 Plus、Pro、Business、Edu 或 Enterprise 套餐用户使用 ChatGPT 账号。^[2] ChatGPT 桌面应用、CLI 和 IDE 扩展都支持两种方式用于本地工作，但 Codex 云端只能用 ChatGPT 登录。^[4]

安装和登录

按上面的命令安装后，运行 codex，选择 Sign in with ChatGPT，这是 README 给出的路径。^[2] 在命令行里也可以直接用浏览器流程登录：^[4]

codex login

要改用 API key 登录，文档的做法是通过标准输入传入：^[4]

printenv OPENAI_API_KEY | codex login --with-api-key

以后升级时，CLI 文档给出的命令是 Homebrew 用 brew upgrade --cask codex，npm 用 npm install -g @openai/codex。^[3]

交互使用和单次任务

在项目目录里运行 codex 就进入交互式会话。会话里用 /permissions 可以切换当前的权限配置。^[9]

单次任务用 codex exec，把提示词作为参数传入。非交互页面的示例是：^[5]

codex exec "summarize the repository structure and list the top 5 risky areas"

codex exec 运行时，进度输出到 stderr，只有最终的回复输出到 stdout，所以结果可以直接重定向或管道传递。^[5] 如果只需要把最终消息写进文件，用 -o <path> 或 --output-last-message <path>，它仍会打印到 stdout。^[5] 脚本需要解析输出时，用 --json，stdout 会变成 JSON Lines 流，事件类型包括 thread.started、turn.started、turn.completed、turn.failed、item.* 和 error。^[5]

两个参数可以让运行不留痕迹。--ephemeral 不把会话记录写到磁盘；--ignore-user-config 则跳过 $CODEX_HOME/config.toml。^[5] 命令行参考说明，codex exec 可以缩写为 codex e，而传入图片、--output-schema、--output-last-message 或 --ephemeral 时必须同时给出提示词。^[6]

沙箱和审批

codex exec 默认在只读沙箱里运行。^[5] 沙箱页面列出三种常用模式：read-only、workspace-write 和 danger-full-access，最后一种不受沙箱限制。^[7] 审批文档说明，非交互运行应使用 codex exec --sandbox workspace-write。^[8] 同一页面还说明 --full-auto 已不再支持。^[5]

审批策略决定 Codex 何时停下来询问。沙箱页面列出的是 on-request 和 never，并说明 Codex 不再支持把 untrusted 作为可选的审批策略。^[7] 想安全地只读浏览，审批页面给出的是 --sandbox read-only --ask-for-approval on-request；只读的非交互 CI 则用 --sandbox read-only --ask-for-approval never，后者可以缩写为 -a never。^[8]

绕过开关要特别小心。--dangerously-bypass-approvals-and-sandbox（别名 --yolo）意味着既没有沙箱，也没有审批。^[8]

Git 仓库是另一道护栏。Codex 要求命令在 Git 仓库内运行，以防止破坏性修改。要跳过这项检查，可以用 codex exec --skip-git-repo-check。^[5]

配置

用户级配置在 ~/.codex/config.toml。项目级覆盖写在 .codex/config.toml 里，只有你信任该项目时，Codex 才会加载它。^[11] 配置值的优先级从高到低依次是：命令行参数和 --config 覆盖、项目的 .codex/config.toml、--profile 指定的配置文件、~/.codex/config.toml、云端托管的默认值、Unix 上的 /etc/codex/config.toml，最后是内置默认值。^[11] 基础配置页用 approval_policy = "on-request" 和 sandbox_mode = "workspace-write" 作为示例。^[11]

requirements.toml 是管理员强制执行的文件，用来约束安全相关的设置，用户无法覆盖。在 sandbox_mode = "workspace-write" 下，sandbox_workspace_write.writable_roots 可以列出额外的可写目录。^[12]

Codex 在开始工作前也会读取 AGENTS.md。它从全局 Codex 主目录开始，主目录默认是 ~/.codex，除非设置了 CODEX_HOME；该层如果存在 AGENTS.override.md 就读它，否则读 AGENTS.md。在项目层级，它从项目根目录一路走到当前工作目录。合并后的指令总大小达到 project_doc_max_bytes 时停止增加，默认是 32 KiB。^[10]

规则（rules）是较新的功能，文档说明它可能变化。规则文件以 .rules 结尾，放在某个生效配置层旁边的 rules/ 文件夹里，比如 ~/.codex/rules/default.rules。prefix_rule() 的 decision 可以是 allow、prompt 或 forbidden，codex execpolicy check 用来测试规则对某条命令的作用。^[13]

图片

Codex 可以接收图片作为输入，用 -i 或 --image 附加一张或多张。例如：^[15]

codex -i screenshot.png "Explain this error and suggest the smallest fix"

一次传入多张也可以，比如 codex --image before.png,after.png "Compare these states and list the regressions"。^[15] PNG、JPEG 等常见格式都支持。^[15]

Codex 还能生成图片。内置的图片生成使用 gpt-image-2，计入 Codex 的常规用量限额。如果要批量生成，可以设置 OPENAI_API_KEY 改走 API，此时按 API 计价。^[14] Free 套餐不提供图片生成。^[16]

我们在 TellWorld 里怎么用

我们在 Claude Code 里以非交互方式调用 Codex 生成封面图，每次调用的形式是：^[1]

codex exec -C <dir> --skip-git-repo-check --sandbox workspace-write "<task>"

每次调用都在一个空的临时目录里运行。任务要求 Codex 使用它的图片生成工具，生成一张 16:9 的横版图，保存为 cover.png，然后什么都不做。^[1] 需要同时生成多张时，我们为每张图在后台各启动一个 codex exec 进程，然后等待全部完成。2026 年 11 月 13 日，我们就是这样一次做出三张封面的。^[1]

这些选择是我们自己的场景做法，不是通用的推荐。空的临时目录让每次运行碰不到项目文件。临时目录不是 Git 仓库，所以需要 --skip-git-repo-check。--sandbox workspace-write 让 Codex 能写入那张图片，同时把其他系统位置挡在外面。^[1]^[5]^[7]