本文内容截至 2026 年 5 月，基于 @openai/codex 最新稳定版。命令与模式名称如有变化，以官方仓库 README 为准。
启动与登录
在项目目录里直接运行 codex，就会打开一个交互式终端会话。首次运行时，Codex 会提示你选择登录方式：
# 进入项目目录后启动
$ cd ~/my-project
$ codex
# 也可以直接登录，再单独启动会话
$ codex login # 浏览器 OAuth，使用 ChatGPT 账号
$ codex login --with-api-key # 手动输入 OpenAI API Key
$ codex logout # 退出登录方式一：ChatGPT 账号（浏览器 OAuth）
运行 codex login 后会自动打开浏览器，用你的 ChatGPT 账号完成授权。登录成功后额度复用你的 Plus / Pro 订阅，不额外按 token 计费。适合已有 ChatGPT 订阅的用户。
方式二：API Key
运行 codex login --with-api-key，在终端里粘贴你从 platform.openai.com 生成的密钥。此方式按 token 量计费，适合没有订阅但有 API 访问权限、或希望精确控制成本的场景。
不要同时存在 ChatGPT OAuth 登录和 OPENAI_API_KEY 环境变量——两套认证并存容易导致连接不稳定。如果出现 Reconnecting 问题，先运行 codex logout 再 unset OPENAI_API_KEY，选一种方式重新登录。
写好第一条指令
登录后，Codex 打开一个交互式会话。你用自然语言描述任务，Codex 会读取、修改并运行当前目录下的代码。
# Codex 启动后，在输入框里直接描述任务
› 给 src/api/login.ts 里的 loginUser 函数补充单元测试
# Codex 可以读文件、修改代码、执行命令
› 找出项目里所有 TODO 注释并整理成列表
› 帮我在提交前做一次本地 code review几条使用建议：
- 说清楚范围：指定文件路径或函数名，避免 Codex 猜测。
- 一次一件事：任务拆细后，每步都能审查，出错也更容易回滚。
- 善用截图：可以把截图/图片直接附加到输入框，让 Codex 参考界面修复 Bug。
审批与沙箱模式
Codex 安全机制分两层：沙箱模式控制它技术上能做什么，审批策略决定什么时候必须先问你。
沙箱模式（截至 2026）
| 模式 | 能做什么 | 典型场景 |
|---|---|---|
read-only |
只读文件，不修改、不执行命令 | 只想让 Codex 分析代码、回答问题 |
workspace-write |
读文件、在工作目录内编辑文件、执行常规本地命令（默认） | 日常开发：写代码、跑测试、整理文件 |
danger-full-access |
无沙箱限制，可执行任意命令 | 确实需要越过工作目录操作时才启用 |
审批策略（Auto 预设）
默认的 Auto 预设下，Codex 在工作目录内自动读、编辑、运行命令，不会逐步请示。如果你只是想聊天看效果、不希望它真的改文件，用 /permissions（或 /approvals）斜杠命令把沙箱切换到 read-only：
› /permissions
# 弹出权限面板，选择 read-only 即可切换为只读模式对陌生代码库第一次探索时，建议先用 read-only 模式让 Codex 帮你梳理结构，确认理解正确后再切回 workspace-write 让它动手修改。
用 AGENTS.md 给项目立规矩
AGENTS.md 是 Codex 的项目说明文件，相当于给 AI 写的「团队 Wiki 摘要」——在任何任务开始前加载，让 Codex 了解项目约定、禁区和偏好，不用每次提示里重复说明。
文件位置与加载顺序
Codex 启动时会从主目录（~/）向下到当前工作目录逐级查找 AGENTS.md，找到的全部加载，越靠近工作目录优先级越高：
~/.codex/AGENTS.md——全局规则（个人习惯、通用偏好）~/my-project/AGENTS.md——项目根目录规则~/my-project/src/AGENTS.md——子目录规则（如果存在）
用 /init 快速生成
在 Codex 会话里运行 /init，它会扫描项目目录并自动生成一份 AGENTS.md 草稿：
› /init
# Codex 扫描项目后生成 AGENTS.md，检查内容后手动编辑补充细节AGENTS.md 写什么
生成后建议按实际项目约定修改，典型内容包括：
# 项目概述
这是一个 Next.js 14 + TypeScript 项目，使用 pnpm 管理依赖。
# 编码约定
- 所有新文件使用 TypeScript，不写纯 JS
- 组件文件名用 PascalCase，工具函数用 camelCase
- 提交前必须通过 pnpm lint 和 pnpm test
# 禁止操作
- 不要修改 .env.local 文件
- 不要删除 migrations/ 目录下的文件
# 常用命令
- 启动开发服务器：pnpm dev
- 运行测试：pnpm test
- 构建：pnpm build常用斜杠命令
在 Codex 会话的输入框里输入 / 可以看到所有可用命令。以下是最常用的几个：
| 命令 | 作用 |
|---|---|
/model |
切换模型（如 gpt-5.4、gpt-5.3-codex 等，截至 2026） |
/approvals / /permissions |
调整审批策略和沙箱模式 |
/init |
为当前项目生成 AGENTS.md |
/status |
查看当前连接状态、模型与配置摘要 |
/feedback |
提交反馈，附带请求 ID 和错误日志，方便问题定位 |
/fast |
切换到速度优先模式 |
/personality |
调整 Codex 的回复风格 |
/agent |
管理子智能体（用于并行化任务） |
/raw |
查看原始请求/响应，便于调试 |
在会话输入框里直接输入 / 会弹出自动补全列表，所有可用命令一目了然，不需要背。
非交互模式：codex exec
除了交互式会话，Codex 还支持 codex exec 命令——直接传入任务描述，非交互地执行并退出，适合接入 CI/CD 流水线或脚本自动化：
# 非交互执行：让 Codex 运行测试并输出摘要
$ codex exec "运行所有单元测试并输出失败用例摘要"
# 适合放入 Makefile 或 CI 脚本
$ codex exec "检查 src/ 下所有 TypeScript 类型错误"codex exec 在非交互模式下执行，建议在 CI 环境中配合明确的沙箱策略使用，避免意外修改文件。确保 OPENAI_API_KEY 或登录凭证已在环境中配置好。
常见问题
用 ChatGPT 登录还是 API Key，哪个更划算？
已有 ChatGPT Plus/Pro 订阅的话，用 codex login（OAuth）更划算——额度已经包含在订阅里，不会再按 token 另外计费。如果没有订阅，就用 codex login --with-api-key，按实际用量付费，偶发使用成本更低。
Codex 会不会乱改我的代码、破坏项目？
默认的 workspace-write 沙箱只在当前工作目录内操作，不会越界访问其他目录。如果对某次操作不放心，可以先用 /permissions 切到 read-only 只让它分析，确认方案后再切回来执行。建议在 Git 工作区操作，这样即使有不符合预期的修改也能立刻 git diff 检查并回滚。
AGENTS.md 必须放在项目根目录吗？
不是必须的。Codex 会从主目录（~/）到当前工作目录依次加载所有 AGENTS.md。可以在 ~/.codex/AGENTS.md 写全局偏好，在项目根目录写项目特有规则，在子目录写更细粒度的约定，互不冲突，靠近工作目录的规则优先级更高。
Codex 连不上 / 一直 Reconnecting 怎么办？
大概率是网络问题。在启动 codex 的同一终端设置 HTTPS_PROXY 环境变量，指向本地 http 代理（不支持 socks5）。详细的逐步排查清单见 一直 Reconnecting 怎么解决。