跳到正文

Codex CLI：在终端里完成一整个开发循环

Codex CLI 的四种安装方式、第一次运行与登录、值得先学会的几个命令（resume、--image、--search、cloud、mcp、/permissions），以及什么时候该用 CLI 而不是别的界面。

当前有效最后核验

适用平台

  • macOS
  • Linux
  • Windows

官方文档怎么说

  • Codex CLI 的定位是在终端里检查代码、做修改、运行命令并自动化可重复的工作。

    Codex CLI

  • macOS/Linux 的独立安装脚本为：curl -fsSL https://chatgpt.com/codex/install.sh | sh；更新使用同一条命令。

    Codex CLI

  • Windows 的独立安装命令为：powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"；更新使用同一条命令。

    Codex CLI

  • 也可以用 npm install -g @openai/codex 或 brew install --cask codex 安装。

    Codex CLI

  • 打开一个项目目录并运行 codex；第一次运行时选择 Sign in with ChatGPT 或其他可用的登录方式。

    Codex CLI

  • 官方建议在任务前后创建 Git 检查点，以便回退改动。

    Codex CLI

  • codex resume 用于重新打开当前仓库中最近的对话，或在需要回到更早的工作时跨本地对话搜索。

    Codex CLI

  • codex --image 可以在第一条提示中传入错误截图、架构图或设计参考，也可以把图片粘贴进交互式 composer。

    Codex CLI

  • codex --search 可以把一次运行切换到实时网页搜索，搜索活动会保留在对话记录中可见。

    Codex CLI

  • codex cloud 可以浏览活跃与已完成的对话、把工作提交到已配置的环境，并从终端把结果应用到本地仓库。

    Codex CLI

  • codex mcp 用于添加本地或远程 MCP servers、在需要时认证，并在 Codex 使用之前检查当前会话可用的工具。

    Codex CLI

  • /permissions 用于选择 Codex 何时可以在不询问的情况下编辑文件或运行命令，并在继续之前检查活动的沙箱和可写根目录。

    Codex CLI

  • codex 的本地代码评审会针对未提交的改动、某个提交或基线分支运行，报告按优先级排序的发现且不修改你的工作区。

    Codex CLI

  • OpenAI 开发者文档索引把 Codex developer tools 列为独立文档集，覆盖 Codex CLI、IDE、cloud、config.toml、认证、定制、自动化和安全。

    OpenAI developer documentation index (llms.txt)

它是什么

官方对 Codex CLI 的一句话定位是：在不离开终端的前提下，检查代码、做修改、运行命令，并自动化可重复的工作。

给出的三条理由也很直接：

  • 对着你的本地仓库工作 —— 让 Codex 检查文件、做编辑，并使用你机器上已经装好的工具。
  • 保持控制 —— 选择适合这个任务的模型、推理强度、权限和命令。
  • 可以和脚本与 CI 组合 —— 交互式使用，或者在可重复的工作流和流水线里调用 codex exec。

第三条是 CLI 相对其他界面的核心优势：它能被脚本调用。

安装：四条路

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

npm install -g @openai/codex

Homebrew

brew install --cask codex

Homebrew 的更新是 brew upgrade --cask codex。

第一次运行

打开一个项目目录并运行 codex。第一次运行时，选择 Sign in with ChatGPT 或其他可用的登录方式。

然后描述你要做的事。官方给的第一句示例故意很轻：

Tell me about this project

这其实是个不错的习惯——进入陌生仓库时先让它解释一遍，比直接布置修改任务更容易发现你对这个代码库的理解偏差。

还有一条官方在快速开始里就给出的建议，值得从第一天养成：在任务前后创建 Git 检查点，以便回退改动。

值得先学会的几个能力

CLI 的命令面不小，但下面几个是构建工作流时最常用的：

codex resume —— 回到之前的对话。 重新打开当前仓库中最近的对话，或者在你需要回到更早的工作时跨本地对话搜索。

codex --image —— 把视觉上下文带进提示。 在第一条提示中传入错误截图、架构图或设计参考，也可以直接把图片粘贴进交互式 composer。

codex --search —— 需要当前信息时用。 把一次运行切换到实时网页搜索，用于任务依赖新版本、文档或外部行为的情况。搜索活动会保留在对话记录中可见——这一点很重要，你能看到它到底查了什么。

codex cloud —— 把工作挪到云端。 浏览活跃与已完成的对话、把工作提交到已配置的环境，并从终端把结果应用到本地仓库。

codex mcp —— 接外部工具。 添加本地或远程 MCP servers、在需要时认证，并在 Codex 使用之前检查当前会话可用的工具。最后这半句是好习惯：先看清有什么工具，再让它动手。

/permissions —— 设定这一轮的边界。 选择 Codex 何时可以在不询问的情况下编辑文件或运行命令，并在继续之前检查活动的沙箱和可写根目录。

subagents —— 拆分较大的调查。 让 Codex 把聚焦的工作委派给专门的 agent，再把它们的发现带回主终端会话。

codex completion —— 让 CLI 贴合你的终端。 为你的 shell 生成补全、选择语法主题，并在 VISUAL 或 EDITOR 配置的编辑器里打开较长的提示词。

三种典型的终端工作流

官方把 CLI 的用法归纳成三类，值得对照自己的习惯看：

把编码循环留在终端里。 在一个仓库里启动 Codex，探索陌生代码、规划一次改动、编辑文件、运行本地开发工具。可以在当前这一轮里引导它，随着命令和 diff 出现随时检查，并把后续工作留在同一个会话里。

使用技能和插件。 把可重复的指令打包成技能，再用插件把 Codex 连到团队的工具和数据上——都不用离开 CLI。

在改动上线前评审。 针对未提交的改动、某个提交或基线分支运行一次专门的评审。Codex 会报告按优先级排序的发现，且不修改你的工作区，让你在提交或开 PR 之前先处理风险。

最后这一条的"不修改工作区"值得强调：评审是只读的，你不会因为跑了一次评审而莫名其妙多出一堆改动。

什么时候该用 CLI

官方给的四个判断场景：

  • 你在终端里工作 —— 在一个专注的循环里探索、编辑和运行一个仓库。
  • 你需要脚本或 CI —— 在可重复的工作流里跑一条非交互命令（codex exec）。
  • 你想要一次本地代码评审 —— 在提交或开 PR 之前检查改动。
  • 你想把工作交给云端 —— 启动一个云端对话，之后再回到终端。

反过来，如果你需要内置浏览器、注释、文件预览这类可视化能力，那些在桌面应用里，CLI 没有。

实际操作

  1. 选一种安装方式：macOS/Linux 独立脚本、Windows 独立脚本、npm 或 Homebrew。
  2. 打开一个项目目录并运行 codex。
  3. 第一次运行时选择 Sign in with ChatGPT 或其他可用的登录方式。
  4. 用一句话描述你要做什么，比如让它解释这个项目、做一处聚焦的修改，或帮忙排查一个问题。
  5. 在任务前后创建 Git 检查点，以便随时回退。
  6. 用 /permissions 确认这一轮 Codex 的边界，检查活动的沙箱和可写根目录。

Windows 步骤

  1. Windows 独立安装：powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
  2. 更新使用同一条命令。
  3. 也可以用 npm install -g @openai/codex 安装。
  4. 若你同时使用 Windows 版 ChatGPT 桌面应用，注意两者的 Codex home 目录与配置共享问题，见《在 Windows 上使用 ChatGPT 桌面应用与 Codex》。

手机步骤

不适用Codex CLI 是终端工具，官方 CLI 页面不涉及手机端。想从手机指挥一台电脑上的 Codex 工作，那是 Remote 的范畴，见《Codex Remote》。

使用案例

  • 进入一个陌生的仓库，先让 Codex 解释这个项目。
  • 在提交或开 PR 之前，针对未提交的改动跑一次本地评审。
  • 在脚本或 CI 里用非交互模式跑一个可重复的流程。
  • 把一段较大的工作交给云端，稍后回到终端取结果。

常见错误

  • 不建 Git 检查点就让 Codex 动手。官方在快速开始里就把"任务前后创建 Git 检查点"列为建议。
  • 没确认权限边界就开始一个会改文件的任务。/permissions 可以在继续之前检查活动的沙箱和可写根目录。
  • 需要当前信息（新版本、外部行为）时不开 --search，然后得到过时的答案。
  • 在 CLI 里找插件的图形界面。CLI 有插件浏览器，输入 /plugins 即可，但那是 TUI 不是图形界面。

常见问题

有哪几种安装方式？
官方列了四种。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：npm install -g @openai/codex。Homebrew：brew install --cask codex（更新用 brew upgrade --cask codex）。前三种的更新命令与安装命令相同。
怎么回到之前的对话？
用 codex resume。官方说明它可以重新打开当前仓库中最近的对话，或者在你需要回到更早的工作时跨本地对话搜索。
能给它看截图吗？
可以。codex --image 允许你在第一条提示中传入错误截图、架构图或设计参考，你也可以直接把图片粘贴进交互式 composer。
什么时候该用 Codex CLI？
官方给了四个场景：你在终端里工作，想在一个专注的循环里探索、编辑和运行仓库；你需要脚本或 CI，要在可重复的工作流里跑一条非交互命令；你想要一次本地代码评审，在提交或开 PR 之前检查改动；你想把工作交给云端，之后再回到终端。
本地代码评审会改我的代码吗？
不会。官方明确说明，它针对未提交的改动、某个提交或基线分支运行，报告按优先级排序的发现，**且不修改你的工作区**，让你在提交或开 PR 之前先处理风险。

官方来源

这些是本教程对照核验的官方页面。需要厂商的原始措辞时请直接查阅。

来源状态