cqbase.net · 中英双语

CQBase 上下文库

Context & Query Base

工作流

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 | sh

Windows 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。本次没有在本机实跑,因此不编造项目摘要或它改过的文件。

  1. 在你自己的仓库目录运行 codex,并完成 ChatGPT 或 API key 登录。
  2. 发送:Tell me about this project。按官方说明,它应查看本地仓库并介绍项目;你不必事先把目录树贴进对话。
  3. 若只想做一个小改动,用你自己的、范围很窄的任务描述即可。官方建议在任务前后做 Git 检查点,以便回退。
  4. 用 /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 上下文库使用。若安装命令、方案范围或地区政策有变,以官网为准。

订阅 CQBase 周刊

每周一封,介绍本周新收录的公开 AI 技能、提示词、MCP 和用法。可随时退订。我们不会把邮箱交给第三方作其营销之用。