Codex CLI 安装与首次使用指南
先确认哪个 ChatGPT 套餐能用 Codex CLI，再完成 macOS、Linux、Windows 安装与登录，设置沙箱和审批权限；附 AGENTS.md 配置与常见问题，均链接官方文档。
核验日期：2026-10-20。本文依据 OpenAI 官方 Codex 文档整理，本站尚未在新版 Codex 上完成安装实测。Codex 更新很快，命令和套餐以文中链接的官方页面为准。
第一次用 Codex CLI，最容易卡住的不是安装命令，而是两件事：你的 ChatGPT 套餐能不能用 CLI，以及第一次运行时 Codex 被允许做什么。本文按这个顺序讲，最后附 Windows 说明和常见问题。
如果你还在比较工具，先看 Codex CLI 的功能、适用场景与源码审查结果，或 Claude Code 与 Codex 怎么选。
先确认：你的套餐能用哪个 Codex
| 登录方式 | 能用的 Codex 入口 | 费用来源 |
|---|---|---|
| ChatGPT Free / Go | 桌面应用中的 Codex（官方注明“逐步开放”） | 套餐内额度 |
| ChatGPT Plus / Pro / Business / Enterprise / Edu | CLI、IDE 扩展、网页版、云端任务 | 套餐内额度，可用 ChatGPT credits 扩展 |
| OpenAI API key | CLI、IDE 扩展、桌面应用（云端功能不可用） | 按 API 标准价格单独计费，不占套餐额度 |
依据：官方价格与功能对照、登录方式说明。所以“Codex 免费吗”的准确回答是：Free 套餐目前只在桌面应用里提供 Codex；想在终端里用 CLI，需要 Plus 及以上套餐，或者用 API key 按量付费。套餐价格与额度会调整，以官方页面为准。
第一步：安装 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 或 Homebrew：
npm install -g @openai/codex
brew install --cask codex
装好后运行 codex --version 确认版本。以上命令来自 官方 CLI 页面。npm 包名是 @openai/codex，不要装名字相近的第三方包。
第二步：登录
在项目目录里运行 codex，第一次会提示登录；也可以直接运行：
codex login
默认走浏览器授权，选择 Sign in with ChatGPT。用 API key 时，官方推荐从标准输入传入，避免 key 留在命令历史里：
printenv OPENAI_API_KEY | codex login --with-api-key
在没有浏览器的远程服务器上，用设备码登录（Beta，需要先在 ChatGPT 安全设置里开启设备码登录）：
codex login --device-auth
登录后用 codex login status 确认当前用的是哪种方式。登录信息缓存在 ~/.codex/auth.json（明文）或系统凭据存储里，不要把这个文件提交到仓库。见 官方登录文档。
如果 --with-api-key 报“未知参数”，多半是 Codex 版本过旧：本站在旧版 0.33.0 上看到的参数还是 --api-key。先按第一步更新，再登录。
第三步：第一个任务与权限
进入一个用 Git 管理的项目目录，运行 codex，先问一个不改文件的问题：
Tell me about this project
官方建议在任务前后各做一次 Git 提交，方便回滚。
Codex 的权限由两部分决定：沙箱（能读写哪里、能不能联网）和审批（什么时候先问你）。官方默认值如下：
- Git 管理的目录：
Auto预设，即--sandbox workspace-write --ask-for-approval on-request。可以在工作目录内读文件、改文件、运行命令；要改目录外的文件或需要联网时，会先征求同意。 - 非 Git 目录：
read-only。 workspace-write默认不给命令联网；.git、.codex、.agents等目录即使在可写范围内也是只读的。
只想聊天或做规划时，在会话里用 /permissions 切到只读，或者这样启动：
codex --sandbox read-only --ask-for-approval on-request
--sandbox danger-full-access 会去掉沙箱，官方要求谨慎使用，不建议在第一次上手时使用。见 官方审批与安全说明。
第四步：用 AGENTS.md 和 config.toml 固定你的习惯
- AGENTS.md：Codex 开始工作前会先读它。全局规则放在
~/.codex/AGENTS.md，项目规则放在仓库里，越靠近当前目录的文件优先级越高；合并后默认上限 32 KiB。适合写“改完 JS 先跑npm test”“加生产依赖前先问我”这类约定。见 官方 AGENTS.md 说明。 - config.toml：个人默认配置在
~/.codex/config.toml，项目级覆盖放在仓库的.codex/config.toml，用来固定默认模型、审批和沙箱级别。见 官方配置入门。 - 查看用量：会话中运行
/status查看剩余额度，或打开 用量面板。
Windows 用户注意
Codex 可以在 Windows 原生 PowerShell 中运行，使用 Windows 自带的沙箱，不强制要求 WSL。项目放在 WSL2 里时，Codex 会改用 Linux 沙箱；VS Code 扩展可以设置 "chatgpt.runCodexInWindowsSubsystemForLinux": true，让 Agent 一直在 WSL2 里运行。见 官方 Windows 沙箱说明 与 审批与安全中的系统沙箱部分。
安装脚本需要在新开的 PowerShell 窗口里运行，装好后重新打开终端，再检查 codex --version。
常见问题
Codex 免费吗？ ChatGPT Free 套餐目前只在桌面应用中提供 Codex，并且是逐步开放；CLI 和 IDE 扩展需要 Plus 及以上套餐，或者用 API key 按 API 价格付费。见 官方价格页。
用 API key 和用 ChatGPT 账号登录有什么区别？ API key 走 OpenAI Platform 的标准计费，不使用套餐内额度；依赖 ChatGPT 工作区或云端服务的功能（例如 Codex cloud）在 API key 下不可用或受限。官方建议 CI/CD 等脚本场景用 API key。
在中国大陆能用吗？ OpenAI 官方的 支持国家和地区列表 里没有中国大陆和中国香港。官方说明，在列表以外的地区访问或提供访问，可能导致账号被封禁或暂停。
Codex CLI 是开源的吗？ 是。源码在 openai/codex，采用 Apache-2.0 许可证。云端的 Codex Web 是另一项托管服务。
和 Claude Code 怎么选？ 主要看你已有的套餐和想用的模型。两者的账号、开源情况和模型接入对比见 Claude Code vs Codex。