Home

深色模式

Codex CLI ​

概述 ​

Codex CLI 不是终端里的聊天壳子，而是一个能读仓库、改文件、跑命令的本地 coding agent。

OpenAI 官方文档当前把它定义成一套本地终端工作流：你可以直接进交互式 TUI，也可以一次性跑一个 prompt，还可以把它塞进脚本和 CI。真正高频的用法，通常就落在这三种模式上。

本文基于 2026 年 4 月 2 日查阅的 OpenAI 官方 Codex 文档整理，重点放在本地 CLI 日常用法，不展开 IDE extension 和 Codex cloud 细节。

安装与首次启动 ​

截至 2026 年 4 月 2 日，Codex CLI 官方 CLI 页面当前默认展示的安装命令是：

sh
npm i -g @openai/codex

安装完成后，直接运行：

sh
codex

第一次启动时，Codex 会提示你登录。官方文档当前说明，CLI 支持两种认证方式：

  • 用 ChatGPT 账号登录
  • 用 API key 登录

如果只是个人日常使用，直接走默认浏览器登录最省事。需要脚本化或 CI 场景时，再换 API key 会更自然。

登录方式怎么选 ​

默认浏览器登录 ​

直接执行：

sh
codex login

不带参数时，Codex 会走 ChatGPT OAuth 流程。官方文档当前说明，这也是 CLI 在没有有效会话时的默认认证路径。

如果当前机器不方便拉起浏览器，可以改用设备码方式：

sh
codex login --device-auth

API key 登录 ​

做自动化时，更适合 API key：

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

官方文档当前也明确建议，程序化的 Codex CLI 工作流更适合 API key 认证。

检查当前登录状态 ​

sh
codex login status

这条命令对脚本特别有用，因为官方 reference 说明它在已登录时会返回退出码 0。

三种最常见的工作方式 ​

交互模式：codex ​

这是最像“结对开发”的模式：

sh
codex

官方 feature 文档当前说明，进入 TUI 后你可以：

  • 直接发 prompt、代码片段和截图
  • 看 Codex 先讲计划，再决定是否同意
  • 在会话里切换权限模式
  • 用 /clear、/copy、/exit 之类的快捷入口管理当前会话

如果你今天要连续做一串相关任务，这是最顺手的入口。

直接带一个 prompt 启动 ​

如果只是临时问一句，不一定要先进全屏 TUI。官方 feature 文档当前给出的直接形式是：

sh
codex "Explain this codebase to me"

这个模式更适合：

  • 先拿一个解释
  • 先让它做概览
  • 先试探性问一件小事

脚本模式：codex exec ​

自动化工作流用这个：

sh
codex exec "fix the CI failure"

官方文档当前把 codex exec 定义成 non-interactive 入口，适合脚本或 CI。它会把结果输出到标准输出，不要求你在中途做人机交互。

会话恢复很值得用 ​

Codex CLI 当前会把本地会话记录下来，所以很多时候没必要每次重讲上下文。

恢复交互会话 ​

sh
codex resume
codex resume --last
codex resume <SESSION_ID>

官方 feature 文档当前说明：

  • codex resume 会打开最近会话列表
  • codex resume --last 会直接回到当前目录最近一次会话
  • codex resume <SESSION_ID> 可以精确恢复某个会话

恢复非交互任务 ​

脚本模式也能继续：

sh
codex exec resume --last "Fix the race conditions you found"

这对长链路任务很实用。第一次先让它找问题，第二次接着修，不用重新铺背景。

高频参数先记这几个 ​

切模型 ​

sh
codex --model gpt-5.4

或者：

sh
codex --model gpt-5-codex

官方 reference 当前说明，--model 用来覆盖配置文件里的默认模型。

切 profile ​

sh
codex --profile deep-review

如果你已经在 config.toml 里定义了不同工作模式，这个参数会很顺手。

指定工作目录 ​

sh
codex --cd /path/to/repo

或者在 exec 里：

sh
codex exec --cd /path/to/repo "run the tests and explain failures"

给额外目录写权限 ​

sh
codex --add-dir ../shared-lib

当仓库外还有联动目录时，这比直接把沙箱拉到 danger-full-access 更稳。

控制审批 ​

sh
codex --ask-for-approval on-request

官方 CLI reference 当前给出的常见值是：

  • untrusted
  • on-request
  • never

交互式开发里，on-request 最均衡。CI 或完全自动化场景，才更常见 never。

控制沙箱 ​

sh
codex --sandbox workspace-write

常见值：

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

如果只是阅读和解释代码，read-only 就够了。需要改项目文件时，再切到 workspace-write。

附带图片输入 ​

Codex CLI 当前支持直接带图片：

sh
codex -i screenshot.png "Explain this error"
codex --image img1.png,img2.jpg "Summarize these diagrams"

这个能力在排前端问题、看报错截图或吃设计稿时很有用。

开实时 Web 搜索 ​

sh
codex --search "check the latest API change and update the docs"

官方 reference 当前说明，--search 会把 web_search 切到 live。如果不加这个参数，很多本地场景默认走的是缓存搜索。

终端里的几个高频动作 ​

在交互会话里，比较常用的是：

  • /permissions：切换权限模式
  • /copy：复制最近一次完整输出
  • /clear：清空当前终端显示
  • /exit：退出会话

还有一个很实用的小细节：官方 feature 文档当前说明，输入框里按 Ctrl+G 可以打开外部编辑器，适合写长 prompt。

MCP 和补全也在 CLI 里管 ​

管 MCP ​

sh
codex mcp list
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

官方 MCP 文档当前说明，MCP 配置写入的是 config.toml，CLI 和 IDE 共用。

开 shell completion ​

sh
codex completion zsh

如果你长期在终端里用 Codex，这个设置很值，能少敲不少参数。

该谨慎的几个开关 ​

OpenAI 官方安全文档当前明确写到，本地 Codex 默认网络关闭，而且工作区写权限也默认受限。这个默认值是有意义的，不是保守过头。

特别是下面两个开关，别默认开：

  • --sandbox danger-full-access
  • --dangerously-bypass-approvals-and-sandbox，也就是 --yolo

官方 reference 当前对 --yolo 的说明很直接：不做审批，也不做沙箱，只适合外部已经充分加固的环境。普通本机开发别把它当快捷方式。

一条够用的日常路线 ​

如果是普通个人项目，日常节奏通常可以这样走：

  1. codex 进入交互式 TUI
  2. 用 /permissions 保持在 Auto 或 read-only
  3. 真要自动化时，再改用 codex exec
  4. 任务中断后用 codex resume --last 接着做
  5. 需要文档和第三方工具时，用 codex mcp 管理 MCP

这样用，Codex CLI 才更像一个稳定工具，而不是偶尔拿来试试的新玩具。

参考 ​