Codex CLI 使用指南：安装、ChatGPT 账号登录、审批模式与 AGENTS.md

Codex 是 OpenAI 的编程代理。Codex CLI 让它直接在你的终端里工作：阅读代码库、执行命令、修改文件、运行测试。本文从安装讲到日常工作流。

准备

• ChatGPT Plus / Pro / Business 等付费账号（包含 Codex 额度），或 OpenAI API Key；
• 终端能访问 OpenAI：开启 TUN 或设置 HTTPS_PROXY，见 Codex 网络环境配置；
• 建议在 Git 仓库中使用。

安装

使用 npm（需要 Node.js）：

npm i -g @openai/codex

macOS 也可以使用 Homebrew：

brew install --cask codex

安装后运行 codex --version 确认。升级时重新执行安装命令即可。

登录

codex

首次运行会提示登录方式：

• 使用 ChatGPT 登录：打开浏览器授权，使用订阅中包含的额度；
• 使用 API Key：设置 OPENAI_API_KEY 环境变量，按量计费。

授权完成后浏览器会回调本机端口。如果终端一直等待，检查 NO_PROXY 是否包含 localhost,127.0.0.1。

基本使用

在项目目录中启动：

cd your-project
codex

然后用自然语言描述任务，例如“为 utils 目录下的函数补充单元测试并运行”。Codex 会给出计划、执行命令、修改文件，并在需要时请求你的确认。

也可以直接带上任务启动：

codex "解释这个项目的目录结构"

非交互模式

在脚本或 CI 中使用：

codex exec "运行测试并修复失败的用例"

审批与沙箱

Codex 在执行命令和修改文件时有不同的权限级别，可以在会话中通过 /approvals 等命令调整：

模式	行为	适合
只读	只能读取与回答，不修改	了解陌生代码库
自动（默认）	工作区内读写与执行，超出范围时请求审批	日常开发
完全访问	不再请求审批，可联网	受信任的隔离环境

选项名称可能随版本调整，以 /help 和官方文档为准。

配置文件

Codex 的配置位于 ~/.codex/config.toml，常见设置包括默认模型、审批策略、沙箱模式等。例如：

# ~/.codex/config.toml（示例，键名以官方文档为准）
model = "你常用的模型名称"
approval_policy = "on-request"

AGENTS.md：给 Codex 的项目说明

在项目根目录创建 AGENTS.md，Codex 会自动读取。建议写入：

# 项目说明
- 技术栈：TypeScript + Node 20
- 安装依赖：pnpm install
- 运行测试：pnpm test
- 代码风格：提交前运行 pnpm lint
- 不要修改 /generated 目录

这和 Claude Code 的 CLAUDE.md 作用相似。两者的详细对比见 Codex 与 Claude Code 对比。

IDE 扩展与云端任务

除了 CLI，Codex 还提供 VS Code 等编辑器扩展，以及在 ChatGPT 中运行的云端任务（把任务交给云端环境执行，完成后审阅改动）。三者共享同一个账号额度。

网络问题速查

现象	处理
npm 安装卡住	为 npm 配置代理或使用镜像源
登录后报地区错误	换 OpenAI 支持地区节点
stream disconnected	固定节点、换更稳定线路
浏览器授权后终端无反应	设置 NO_PROXY 包含 localhost

详细说明见 Codex 网络环境配置。