工作流
OpenAI Codex CLI
OpenAI 的轻量终端编码代理,Apache-2.0。
openai/codex 是 OpenAI 的终端编码代理,Apache-2.0,仓库描述是一个跑在终端里的轻量编码代理。它和 Claude Code、Gemini CLI 属于同一类工具:你在仓库目录里下指令,它改代码。
先读仓库里的权限和沙箱说明,再在一个小改动上试用。不同产品的“自动批准命令”不是一回事,不要把在另一个工具里养成的习惯直接搬过来。
本页是导读,不是原文。
解决什么问题
Codex CLI 是 OpenAI 的终端编码代理,在本机项目目录里读文件、改代码并运行命令。它和 Claude Code、Gemini CLI 是同一类工具,但登录和额度走的是 ChatGPT 或 OpenAI API。同一套产品还有 IDE 扩展、桌面应用,以及网页上的 Codex Web;本文只写入门用的 CLI。
仓库使用 Apache-2.0 许可。官方也提供 codex exec 做非交互脚本,以及 /permissions、/init(生成 AGENTS.md)、技能和插件、MCP(codex mcp)。本文不堆功能清单。
适合谁
适合已经能在终端打开仓库、希望代理在本地干活的人。官方帮助中心写明,Codex 包含在 ChatGPT 的 Free、Go、Plus、Pro、Business、Enterprise 等方案中,用量因方案而异;Codex Cloud 面向符合条件的 Plus、Pro 以及 Business、Enterprise、Healthcare、Education 账号,不含在 Free 或 Go 里。仓库 README 则建议用 Plus、Pro、Business、Edu 或 Enterprise 登录。两者都以官网为准,本文不编造各档具体次数。也可用 API key,按 OpenAI API 标准价格计费,部分依赖 ChatGPT 工作区的功能会受限。
OpenAI 的支持国家和地区名单写明:在未列出的地区访问或提供访问,可能导致账号被封或暂停。该名单有台湾,没有中国大陆、香港和澳门。官方帮助中心也说,未列出即不支持。政策可能调整,以官网为准。本文不讨论如何绕过该限制。
怎么装
核验日期为 2026-11-15(Asia/Shanghai),命令来自仓库 README 和 Codex CLI 文档。macOS 或 Linux:
curl -fsSL https://chatgpt.com/codex/install.sh | shWindows PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"也可以用 npm install -g @openai/codex 或 brew install --cask codex。装完后进入项目目录,运行 codex。第一次请选择 Sign in with ChatGPT,并在浏览器里完成登录。也可以运行 codex login。若要用 API key,官方做法是把密钥通过标准输入传给登录命令:
printenv OPENAI_API_KEY | codex login --with-api-key不要把密钥贴进对话。可用 codex login status 查看当前方式,用 codex logout 退出。无界面环境可尝试官方的设备码登录:codex login --device-auth。
会话里可用 /permissions 查看沙箱和授权范围,用 /init 生成 AGENTS.md,用来写下项目约定。改动前先看官方权限说明,不要把在别的工具里养成的「自动批准」习惯直接搬过来。
一个实际例子
官方入门提示词是:Tell me about this project。本次没有在本机实跑,因此不编造项目摘要或它改过的文件。
- 在你自己的仓库目录运行
codex,并完成 ChatGPT 或 API key 登录。 - 发送:
Tell me about this project。按官方说明,它应查看本地仓库并介绍项目;你不必事先把目录树贴进对话。 - 若只想做一个小改动,用你自己的、范围很窄的任务描述即可。官方建议在任务前后做 Git 检查点,以便回退。
- 用
/permissions确认它能改哪些文件、能跑哪些命令。重要改动请自己看 diff,再用你平时的测试和 Git 流程处理。
常见坑
- 登录失败或不在支持地区。请先对照 OpenAI 的支持地区名单和帮助中心的「unsupported country」说明。无界面环境用设备码,而不是等浏览器自己弹出来。issue #39162 还报告过在 macOS 上打开旧会话后,ChatGPT 登录状态失效。
- 权限和沙箱。先用
/permissions看当前模式,不要默认允许所有命令。issue #47345 曾报告 Linux 沙箱在某次更新后失败(已关闭),请以当前文档和报错为准。 - 把 API key 写进仓库或聊天。官方要求通过
codex login --with-api-key或安全的环境变量传入。登录缓存可能写在~/.codex/auth.json,注意文件权限。 - 额度用尽或功能缺失。Free / Go 与付费档、以及订阅登录与 API key 登录,包含的功能和计费不同。Codex Cloud 不在 Free / Go 里。具体次数以 ChatGPT 定价 和帮助中心为准,本文不编造数字。
FAQ
免费的 ChatGPT 能用 Codex CLI 吗?
官方帮助中心写明,Codex 包含在 Free 和 Go 等方案中,但用量有限。仓库 README 更推荐用 Plus 或更高档登录。Codex Cloud 不包含在 Free 或 Go 里。以官网当前说明为准。
一定要用 API key 吗?
不必。推荐方式是用 ChatGPT 账号在浏览器里登录。API key 适合脚本或 CI,并按 API 价格计费。
AGENTS.md 是什么?
官方 CLI 可用 /init 生成 AGENTS.md,用来写下给 Codex 的项目说明,作用接近其他代理里的约定文件。请先看它生成的内容,再按需修改。
在中国大陆能用吗?
OpenAI 官方支持名单未列出中国大陆、香港和澳门,并警告在未列出地区访问可能导致账号被封或暂停。是否可用以官网当前名单为准。本文不提供绕过方法。
它和 Codex Web 是一回事吗?
不是。CLI 在本机仓库里运行;Codex Web 是云端代理,入口在 chatgpt.com/codex。还可以安装 IDE 扩展或运行 codex app。本文只覆盖 CLI 入门。
来源与许可
仓库 openai/codex 使用 Apache-2.0 许可。本文依据 2026-11-15 查阅的 README、CLI 文档、Authentication、帮助中心说明 和支持地区名单,用自己的话写成,供 CQBase 上下文库使用。若安装命令、方案范围或地区政策有变,以官网为准。