# OpenAI Codex CLI

Canonical: https://cqbase.net/zh/entry/openai-codex
Chinese: https://cqbase.net/zh/entry/openai-codex
English: https://cqbase.net/en/entry/openai-codex

> 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 的[支持国家和地区名单](https://developers.openai.com/api/docs/supported-countries)写明：在未列出的地区访问或提供访问，可能导致账号被封或暂停。该名单有台湾，没有中国大陆、香港和澳门。官方帮助中心也说，未列出即不支持。政策可能调整，以官网为准。本文不讨论如何绕过该限制。

## 怎么装

核验日期为 2026-11-15（Asia/Shanghai），命令来自仓库 README 和 [Codex CLI 文档](https://learn.chatgpt.com/docs/codex/cli)。macOS 或 Linux：

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

Windows PowerShell：

```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，官方做法是把密钥通过标准输入传给登录命令：

```bash
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](https://github.com/openai/codex/issues/39162) 还报告过在 macOS 上打开旧会话后，ChatGPT 登录状态失效。
- 权限和沙箱。先用 `/permissions` 看当前模式，不要默认允许所有命令。[issue #47345](https://github.com/openai/codex/issues/47345) 曾报告 Linux 沙箱在某次更新后失败（已关闭），请以当前文档和报错为准。
- 把 API key 写进仓库或聊天。官方要求通过 `codex login --with-api-key` 或安全的环境变量传入。登录缓存可能写在 `~/.codex/auth.json`，注意文件权限。
- 额度用尽或功能缺失。Free / Go 与付费档、以及订阅登录与 API key 登录，包含的功能和计费不同。Codex Cloud 不在 Free / Go 里。具体次数以 [ChatGPT 定价](https://chatgpt.com/codex/pricing/) 和帮助中心为准，本文不编造数字。

## 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](https://github.com/openai/codex) 使用 Apache-2.0 许可。本文依据 2026-11-15 查阅的 README、[CLI 文档](https://learn.chatgpt.com/docs/codex/cli)、[Authentication](https://learn.chatgpt.com/docs/auth.md)、[帮助中心说明](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan) 和[支持地区名单](https://developers.openai.com/api/docs/supported-countries)，用自己的话写成，供 CQBase 上下文库使用。若安装命令、方案范围或地区政策有变，以官网为准。

## 收录信息

- 作者: openai
- 许可证: Apache-2.0
- 来源: https://github.com/openai/codex
- 收录: 2026-11-15
- GitHub 星标: 135344（采集 2026-11-15）

