codex使用教程

指 2025 年后发布的 Codex CLI（终端 Agent），非已退役的旧 Codex 模型。

安装

任选一种：

# 官方脚本（macOS / Linux，推荐）
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex

Windows 用 PowerShell 跑官方脚本，或装 WSL2 后在 WSL 内用上述方式。

登录

cd /你的项目
codex

首次启动选 Sign in with ChatGPT，浏览器完成 OAuth 即可。也可用 API Key 登录。

基本用法

进入 TUI 后直接用自然语言下任务：

> 解释一下这个项目的结构
> 修复 src/utils.ts 里的空指针问题，做最小改动
> 给 parseConfig 函数补单元测试

关键习惯：执行前先 git commit 或建 checkpoint，改完看 diff，不满意可回退。

常用 TUI 命令：

命令	作用
/init	生成 AGENTS.md 项目指令文件
/status	查看当前模型与权限
/permissions	调整审批/沙箱策略
/model	切换模型与推理强度
/review	审查未提交的改动

项目指令：AGENTS.md

在项目根目录放 AGENTS.md，Codex 启动时自动加载，相当于给 Agent 的“项目说明书”：

# 项目说明
Next.js 14 + TypeScript。

# 命令
- 启动：pnpm dev
- 测试：pnpm test（改完必须跑）
- Lint：pnpm lint --fix

# 约束
- 不要改 node_modules
- API 路由放 src/app/api/

也可直接运行 /init 让 Codex 自动生成。

非交互模式（脚本/CI）

# 一次性执行
codex exec "修复所有 lint 错误"

# 管道输入
cat error.log | codex exec "诊断这个报错"

# JSON 输出
codex exec --json "审查安全漏洞"

适合集成到 CI 或自动化脚本中。

权限控制（重要）

默认 Codex 不会随意改文件或联网。常用策略：

参数	效果
-s read-only	只能读，不能写
-s workspace-write	可写当前工作区
-a on-request	越界操作需你批准
--full-auto	工作区可写 + 自动审批常规操作

新手建议：先用默认或 -a on-request，看清楚它要做什么再放行，不要一上来就 --yolo。

注意事项

• 包名是 @openai/codex，npm 上无作用域的 codex 是无关旧包，装错会出怪问题。
• Codex 会实际修改你的文件，任务前后用 Git 打 checkpoint 是最稳的习惯。
• 复杂任务可先让它“只给方案、不改代码”，确认思路后再执行。