Codex 用法：OpenAI 的本地编码代理

上一课我们把 Claude Code 用到了「顺手」；这一课 12 分钟，把 OpenAI 阵营的对位工具 Codex 也装到顺手：安装、ChatGPT 账号登录、派第一件活、看住它的权限、切模型、检查改动收尾。本篇 Codex 教程聚焦 CLI 这个主形态——官方定位「在你电脑本地运行的编码代理」；IDE 扩展、桌面 App、网页版三种形态共用同一个账号，最后统一带你看。（事实核对时间 2026-11-05；命令与功能会随版本更新，以官方文档为准。）

学完你能做什么

• 在 macOS、Linux 或 Windows 上装好 Codex CLI，用 ChatGPT 账号完成登录
• 在项目目录里派活：让它解释项目、做小改动、修 bug——它自己读文件、在沙箱里跑命令
• 用 /permissions 看住它的手：知道沙箱三档和审批策略，越界先问你
• 用 /model 切换模型（如 gpt-6.1-sol）、/status 查会话状态和用量
• 用 /diff、/review 检查改动，/compact 压缩长对话，codex resume 续上旧会话

你现在的困境

• 网页版 ChatGPT 聊代码，每个文件都要复制进去、改完再粘回来，来回搬运到手酸
• 装了 Codex 却卡在登录：ChatGPT 账号和 API key 两条路，不知道选哪个、订阅里到底含不含 Codex
• 它动不动停下来问「要不要批准这条命令」，问烦了；全放开又怕它把项目改坏

什么时候用这一招

当你需要：

• 让 OpenAI 的模型直接在你电脑上读项目、改文件、跑命令——改动留在本地，随时可查可回退
• 用现成的 ChatGPT 订阅（Plus / Pro / Business / Edu / Enterprise）驱动编码代理，不单独买 API
• 边界清楚：沙箱圈住它能碰的文件和网络，越界先审批

而且不想：

• 在网页聊天框里来回复制粘贴代码和报错
• 给 AI 你电脑的完全控制权
• 换个工具就重学一套概念——上一课「像派活一样说清一件事」的心法在这里原样适用

🎒 开始前的准备

• 看过 日常使用导读，知道本页讲的是四款工具里的 Codex（OpenAI 阵营）
• 一个 ChatGPT 账号：官方推荐用 Plus / Pro / Business / Edu / Enterprise 订阅登录；各档价格与包含范围见 价格对比（免费档能力以官方页面为准）
• 一个练手项目目录，最好是 git 仓库——官方建议任务前后打 Git 检查点（checkpoint），方便整体回退
• 12 分钟不被打扰的时间

💡 上一课不是前置条件

本课只要求你看过 日常使用导读。Claude Code 用法与本课互相独立，但「派活」心法通用，对照着看更有感觉。

核心思路

Codex CLI 的官方定位一句话讲清：OpenAI 出的、在你电脑本地运行的编码代理（a coding agent from OpenAI that runs locally on your computer）。它对着你的本地仓库干活：检查文件、做修改、跑你机器上已装好的工具——不是「你贴代码它给答案」的聊天框，而是「你派活、它干完」的代理。

和网页版 ChatGPT 的根本区别：

	网页版 ChatGPT	Codex CLI
代码进上下文	你手动复制粘贴	它自己读本地仓库
改代码	给你片段，自己粘回去	直接编辑文件，/diff 可查
验证	你自己跑命令	它在沙箱里跑测试、看报错、自己修
计费	聊天额度	ChatGPT 订阅里的 Codex 用量，或 API key 按量

四种形态，一个账号。 CLI 是本课主线；其他三种形态用同一个 ChatGPT 账号（云端任务必须用 ChatGPT 账号登录；CLI 和 IDE 扩展还共享同一份本地登录凭证）：

形态	一句话定位
CLI 终端（本课主线）	项目目录里跑 codex：读代码、改文件、跑命令，不离开终端
IDE 扩展	VS Code、Cursor、Windsurf 侧边栏（扩展 openai.chatgpt；Xcode、JetBrains 另有集成）
桌面 App	codex app 从终端拉起 ChatGPT 桌面端（macOS/Windows），App 里选 Codex 开聊
Codex Web	浏览器开 chatgpt.com/codex：云端代理，任务在云上跑，你电脑睡着也能继续

安全模型就一句话：沙箱圈地 + 审批把关。沙箱决定它能碰哪些文件和网络；审批策略决定越界前要不要停下来问你。日常从 Ask for approval 起步，官方给的低摩擦组合是 --sandbox workspace-write --ask-for-approval on-request——工作区内自由干活，出圈先报告。

和上一课的 Claude Code 怎么选、怎么搭？ 两款都是「本地代理」的同一个思路，差异主要在背后的模型与订阅：Claude Code 走 Claude 模型 + Anthropic 订阅，Codex 走 GPT 模型 + ChatGPT 订阅。搭着用完全可行——两边都有项目说明书机制（详见 AGENTS.md 与 CLAUDE.md），Codex 的 /import 还能把 Claude Code 的配置和聊天记录直接迁过来。费用全表见 价格对比。

跟我做

第 1 步：安装 Codex CLI

为什么：Codex CLI 是独立安装的命令行工具，先装上才有后面的一切。官方安装脚本一条命令搞定。

方式 A：官方安装脚本（推荐）

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"

方式 B：包管理器

npm install -g @openai/codex

brew install --cask codex

装完验证：

codex --version

你应该看到：终端打出版本号。

以后更新：重跑一遍方式 A 的安装命令即可；brew 用户用 brew upgrade --cask codex；CLI 也自带 codex update 自检更新。

• 小检查：codex --version 能打出版本号

第 2 步：用 ChatGPT 账号登录 Codex

为什么：官方推荐用 ChatGPT 账号登录——直接用 Plus / Pro / Business / Edu / Enterprise 订阅里的 Codex 用量，不用单独买 API key。

cd /path/to/your/project
codex

第一次运行会让你选登录方式，选 Sign in with ChatGPT：浏览器弹出 OpenAI 登录页，登录后凭证自动回到终端。

登录完检查状态：

codex login status

你应该看到：当前登录的账号信息。这条命令在凭证存在时退出码为 0，写脚本判断登录状态也好用。

💡 另一条路：API key 按量计费

没有订阅也有办法：用 OpenAI API key 登录，按标准 API 价目计费（官方 README 提示这条路需要额外设置）：

printenv OPENAI_API_KEY | codex login --with-api-key

两点心里有数：API key 方式没有云端功能（GitHub 自动代码审查、Slack 集成等），模型可用性跟随你的 key；订阅用户日常还是推荐 ChatGPT 登录。

• 小检查：codex login status 显示已登录

第 3 步：Codex 教程核心：怎么派活？像安排同事一样说清一件事

为什么：和上一课 Claude Code 一样，代理的产出质量取决于你说没说清。官方给的第一件活选得合适——先让它给你讲讲这个项目，既练了手，也能借它的回答看看它对项目的理解程度。

Tell me about this project

日常几类活的说法：

任务	你说
读懂项目	Tell me about this project（官方示例）
做小改动	说清改哪个文件、改成什么样、怎么算改好
修 bug	报错原样贴给它，说清怎么触发的
解释某段代码	@ 引用文件路径，让它围绕这个文件讲

你应该看到：Codex 自己去读文件，列出项目结构或动手编辑；需要验证时它在沙箱里跑命令，把输出看进眼里再继续。

官方建议：任务前后各打一个 Git 检查点（checkpoint），改坏了能整体回退。

• 小检查：我派了一件具体的活，看到 Codex 自己读文件、改文件或跑命令

第 4 步：看住它的手——用 /permissions 配权限和沙箱

为什么：代理在你电脑上跑命令，边界必须清楚。Codex 用两道闸：沙箱决定它能碰哪些文件和网络，审批决定越界前要不要先问你。

会话里输入：

/permissions

你应该看到：权限选择器弹出，可以切换审批预设——比如 Auto 放手跑，Read Only 只读严管。

沙箱三档（配置文件 ~/.codex/config.toml 里的 sandbox_mode 字段）：

沙箱模式	含义
read-only	只能看：改文件、跑命令都要审批
workspace-write	工作区内自由读写、跑常规命令（官方推荐的低摩擦默认）
danger-full-access	无沙箱限制，只在明确要全放开时用

审批策略两档：on-request（默认，越界才问）、never（从不问）。

平台差异提前知道：

• macOS：开箱即用（系统自带 Seatbelt 框架）

• Windows：PowerShell 里用原生 Windows 沙箱；WSL2 里走 Linux 沙箱

• Linux：先装 bubblewrap——sudo apt install bubblewrap（Ubuntu/Debian）或 sudo dnf install bubblewrap（Fedora）

• 小检查：/permissions 能打开选择器，我知道当前是哪档沙箱

第 5 步：切模型、查状态——/model 与 /status

为什么：不同任务用不同火力：疑难 bug 用强模型多想想，批量小活用快模型省额度。注意别写旧模型名——GPT-5.5 已于 2026-10-14 从「ChatGPT 登录的 Codex」退役。

会话里切模型：

/model

你应该看到：弹出你账号可用的模型列表（如 gpt-6-luna、gpt-6.1-sol），选中后对话里确认切换。

启动时直接指定也行：

codex --model gpt-6.1-sol

查会话状态：

/status

你应该看到：当前模型、审批策略、可写目录和 token 用量。官方文档说：活跃 CLI 会话里查剩余额度，就用它。

💡 盯用量

会话里 /usage 看账号 token 活跃度（每日 / 每周 / 累计）；网页端用量面板在 chatgpt.com/codex/settings/usage，官方建议每一两周看一次，心里有数自己的节奏。

• 小检查：/status 里能看到当前模型和审批策略

第 6 步：检查改动、收尾会话——/diff 与 codex resume

为什么：AI 改的代码要过目再入库；会话管理决定「第二天还愿不愿意打开它」。

场景	操作	效果
看它改了什么	/diff	Git diff，连 Git 还没跟踪的新文件也列出来
让它自审一遍	/review	汇总工作区问题（行为变化、缺测试），不改你的文件
对话太长变慢	/compact	把历史压缩成摘要，释放上下文
直接跑 shell	! git status	输出进对话，它自动回应
引用文件	@src/...	文件路径进提示词
明天接着干	退出后 codex resume	重开当前仓库最近的会话，也能搜更早的

你应该看到：/diff 列出改动文件与增删内容；codex resume 带着上次的对话上下文回来。

• 小检查：我用 /diff 过目了改动，并用 codex resume 续上过一个会话

检查点 ✅

• codex --version 打出版本号，codex login status 显示已登录
• 我在项目目录启动了 codex，派了第一件活，看到它自己读文件、在沙箱里跑命令
• 我会用 /permissions 切审批预设，知道官方推荐组合是 workspace-write + on-request
• 我会用 /model 切模型（如 gpt-6.1-sol）、/status 查状态；知道 gpt-5.5 已退役
• 改动我用 /diff 过目；长对话 /compact；会话用 codex resume 续

踩坑提醒

❌ 模型名还写着 gpt-5.5——它已经退役了

GPT-5.5 于 2026-10-14 从「ChatGPT 登录的 Codex」退役（API key 会话不受影响）。替换方案：Plus / Pro / Business / Enterprise / Edu 档用 gpt-6.1-sol；Free / Go 档在桌面 App 里用 gpt-6-luna。工作区默认值、保存的模型设置、自定义 agent、定时任务、脚本里的旧模型名要一并更新。

❌ Linux 上启动就弹沙箱警告

原因：Linux 沙箱依赖 bubblewrap（bwrap），没装、或它无法创建用户命名空间时，Codex 启动就会警告。正确做法：sudo apt install bubblewrap（Ubuntu/Debian）或 sudo dnf install bubblewrap（Fedora）；Ubuntu 24.04 装完仍警告的话，按官方文档把 bwrap-userns-restrict AppArmor 配置文件装进 /etc/apparmor.d/ 再加载。

❌ 图省事直接开 danger-full-access

官方安全提示写得很直白：--dangerously-bypass-approvals-and-sandbox 只该在专用沙箱 VM 这类受控环境里用。日常留在 workspace-write；要让它写工作区之外的目录，加 --add-dir 指定，而不是整个放开。另外记住：把审批交给自动审查（Approve for me）不会扩大沙箱——它只是替你审越界请求，边界还是那道边界。

❌ 把登录凭证当普通文件

Codex 把登录凭证缓存在 ~/.codex/auth.json（或系统凭证库），官方明说「像密码一样对待」：不提交进仓库、不贴工单、不发群聊。API key 登录用官方给的管道方式 printenv OPENAI_API_KEY | codex login --with-api-key，别把 key 明文敲在命令行里。

进阶技巧（可选）

给项目留一份「说明书」。 会话里运行 /init，Codex 在当前目录生成 AGENTS.md 脚手架——写上验证命令、约定和坑，每次会话它都会先读。写法详解见 AGENTS.md 与 CLAUDE.md：给 AI 留一份项目说明书。

把 Codex 当 Unix 工具用。 脚本和 CI 里用非交互模式 codex exec，跑完自动退出，输出能直接管道给别的工具：

codex exec "generate release notes for the last 10 commits" | tee release-notes.md

codex exec 默认只读沙箱；要让它改文件，加 --sandbox workspace-write。

从 Claude Code 迁移配置。 会话里运行 /import，选 Claude Code（或 Cursor），把配置、项目文件和最近的聊天记录导进来——官方说明最多找最近 30 天内的 50 个聊天。

电脑关机也想让它干活。 打开 chatgpt.com/codex 把任务交给云端：每个任务有独立工作区，你电脑睡着它也能继续跑；回头在网页、手机或桌面 App 里审查改动、提交 PR。终端里 codex cloud 可以浏览和提交云端任务。

IDE 里接着用。 VS Code、Cursor、Windsurf 装 openai.chatgpt 扩展，编辑器里打开的文件、选中的代码直接进提示词；桌面端一条 codex app 拉起。

本课小结

✅ Codex 教程的日常主线 = 装好 CLI → ChatGPT 账号登录 → 进目录派活 → /permissions 看住边界 → /model 调火力 → /diff 检查、codex resume 续命。 六步转起来，它就是你终端里随叫随到的 OpenAI 编程代理。

✅ 它是代理不是聊天框：自己读本地仓库、改文件、在沙箱里跑命令——你负责说清「做什么、做成什么样」。

✅ 四种形态一个账号：CLI（本课）、IDE 扩展、桌面 App（codex app）、Codex Web（chatgpt.com/codex 云端任务）。

✅ 安全两道闸：沙箱（read-only / workspace-write / danger-full-access）+ 审批（on-request / never）；日常组合 workspace-write + on-request。

✅ 模型别写旧名：gpt-5.5 已于 2026-10-14 退役，换 gpt-6.1-sol 或 gpt-6-luna。

关键操作回顾：

操作	怎么做	说明
安装	curl -fsSL https://chatgpt.com/codex/install.sh | sh（macOS/Linux）；PowerShell 安装命令（Windows）	备用：npm、brew；更新重跑安装命令
登录	codex 后选 Sign in with ChatGPT	codex login status 查状态
派活	直接打字描述任务	官方第一件活：Tell me about this project
配权限	/permissions	沙箱三档 + 审批两档
切模型	/model 或 codex --model gpt-6.1-sol	gpt-5.5 已退役
查状态	/status	模型、审批策略、可写目录、token 用量
看改动	/diff、/review	含 Git 未跟踪的新文件
续会话	codex resume	重开当前仓库最近的聊天

下一课预告

Codex 用顺了，下一课看开源阵营的 OpenCode：OpenCode 用法：开源代理，国产模型随便接。

你会学到：

• OpenCode 是什么：开源 AI 编码代理，模型不绑定任何一家
• 怎么接入国产模型：DeepSeek、Kimi、智谱等都在官方模型目录里
• OpenCode 和 Codex、Claude Code 怎么选、怎么搭着用
• 四款工具费用全表见 价格对比