OpenAI 终端编码代理 Codex CLI 的全面速查手册，涵盖安装、配置、快捷键、沙盒安全机制及日常使用技巧。
什么是 Codex CLI？
Codex CLI（简称 cx）是 OpenAI 推出的终端编码代理工具，与 Anthropic 的 Claude Code（cc）定位相似，但设计思路有不少差异：cx 拥有内置沙盒、使用 TOML 格式配置、项目全局提示词文件叫
AGENTS.md 。安装与登录
前提条件：Node.js >= 22 是硬性要求，版本低了装不上。账号方面需要 ChatGPT Plus/Pro/Team/Business/Edu 订阅，免费账号用不了。
macOS / Linux
Windows
Windows 目前有两种方式，各有利弊：
方式一：WSL2（推荐）
cx 在 Windows 上仍是实验性支持，WSL2 是目前最稳的方案。
重要提示：项目要放在 Linux 文件系统里（如
~/code/），不要放在 /mnt/c/ 下，跨文件系统 IO 会非常慢。VS Code 配合 WSL 使用
装个 VS Code 的 WSL 扩展，然后在 WSL 终端里：
这样 VS Code 的终端也是 WSL 环境，cx 跑起来没问题。
方式二：原生 Windows（PowerShell）
先确保 Node >= 22 装好了（可以去 nodejs.org 下安装包，或者用
winget install OpenJS.NodeJS）。原生 Windows 下 cx 用的是实验性的 Windows 沙盒：
- 通过 Restricted Token + 文件系统 ACL 限制写入范围
- 创建专用的 Windows Sandbox User 执行命令
- 用 Windows 防火墙规则限制网络访问
偶尔会有权限问题，Win10 上比 Win11 更容易出问题。
Windows 踩坑汇总
问题 | 解决办法 |
WSL 里 codex 登录弹不出浏览器 | 复制终端里显示的 URL，手动在 Windows 浏览器里打开 |
/mnt/c/ 下项目跑得慢 | 把项目移到 ~/code/ 下 |
原生 Windows 沙盒报权限错 | 试试用管理员权限跑 PowerShell，或者切 WSL |
Node 版本不对 | node -v 检查，低于 22 就用 nvm 重装 |
npm 全局安装报 EACCES | WSL 里用 nvm 装的 Node 一般没这问题；原生 Windows 试试管理员 PowerShell |
认证登录
命令 | 说明 | codex | 首次启动自动弹浏览器登录 |
codex login | 手动触发浏览器 OAuth | codex login --device-code | 设备码登录，适合 SSH 远程机器 |
printenv OPENAI_API_KEY | codex login --with-api-key | API Key 登录 |
登录后 token 保存在
~/.codex/token。WSL 环境下就是 Linux 的 home 目录，原生 Windows 下是 %USERPROFILE%\.codex\token。快捷键
cx 的快捷键比 cc 少一些，而且目前不支持自定义。
基础操作
按键 | 作用 | Enter | 发送消息 |
Esc | 取消当前请求 | Esc Esc | 编辑上一条消息 |
Ctrl+C | 中断当前操作 | Ctrl+C Ctrl+C | 强制退出 |
Ctrl+D | 退出 Codex | Ctrl+K | 清屏 |
Ctrl+O | 选择 Codex Cloud 环境 |
编辑与导航
按键 | 作用 | Up / Down | 翻输入历史 |
Tab | 自动补全 | @ | 引用文件（模糊搜索） |
!command | 内联跑 Shell 命令，如 !ls、!git status |
斜杠命令
会话控制
命令 | 说明 | /compact | 压缩上下文，token 爆了就靠这个续命 |
/diff | 查看当前 Git 差异 | /review | 让另一个代理审查代码 |
/resume | 恢复之前的对话 | /fork | 克隆对话到新线程，试不同方案时很好用 |
/plan | 进入计划模式——只规划不执行 | /quit / /exit | 退出 |
配置与模型
命令 | 说明 | /model | 切换模型或调推理级别 |
/personality | 切性格： friendly（话多热情）、pragmatic（干练务实）、none（纯工具人） | /permissions | 调权限 |
/status | 查看工作目录、模型、token 用量 | /init | 在项目里创建 AGENTS.md |
/mcp | 列出已连接的 MCP 工具 | /agent | 管理代理 |
/experimental | 开实验性功能（如 Multi-agents），改完要重启 |
开发与工具
命令 | 说明 |
/init | 在项目里创建 AGENTS.md，新项目第一件事建议就做这个 |
/skills | 浏览和插入技能 |
/mcp | 列出已连接的 MCP 工具 |
/theme | 换主题配色 |
/statusline | 自定义底部状态栏显示内容 |
/debug-config | 查看配置加载顺序，排查配置问题时很有用 |
会话持久化
命令 | 说明 | ||
/export session.json | 导出当前会话 | ||
/load session.json | 加载之前的会话继续干（适合跨天的大重构） |
启动参数
基础启动
模型与行为
参数 | 说明 |
--model <model> | 指定模型，如 gpt-5-codex、gpt-5.3-codex |
--full-auto | 全自动模式，等于 -a on-request -s workspace-write |
-a never | 从不暂停请求人工审批 |
-a on-request | 需要时才问你（交互式推荐） |
--path <dir> | 指定工作目录 |
--add-dir <path> | 添加额外的可写目录，可重复用 |
--search | 开启实时网页搜索（默认是缓存模式） |
-c key=value | 临时覆盖配置值，优先级最高 |
沙盒模式
cx 与 cc 最大的区别之一——内置沙盒，默认限制文件读写和网络访问。
模式 | 读文件 | 写文件 | 联网 | 适用场景 | read-only | ✅ | ❌ | ❌ | 纯看代码，完全安全 |
workspace-write | ✅ | 项目目录 + 临时目录 | 默认禁 | 日常开发首选 | danger-full-access | ✅ | 随便写 | ✅ | 系统级操作，慎用 |
全自动模式对比
方式 | 自动化 | 安全性 | 适用场景 |
默认 TUI | 低 | 高 | 不熟悉时先用 |
--full-auto | 高 | 中 | 日常开发推荐 |
-a never -s workspace-write | 高 | 中 | 精细控制 |
-s danger-full-access | 高 | 低 | 需要系统级操作 |
--yolo | 完全自动 | 极低 | 仅限容器/VM |
建议：日常用
--full-auto 就够了，它在自动执行的同时还有沙盒兜底。--yolo 只在 Docker 容器或虚拟机里才考虑用。所有子命令一览
子命令 | 别名 | 说明 | |||||
codex | — | 开 TUI | |||||
codex exec | codex e | 非交互执行，CI 用 | |||||
codex resume | — | 恢复会话 | |||||
codex fork | — | 分叉会话 | |||||
codex apply | codex a | 把 Cloud 任务的 diff 拉到本地 | |||||
codex cloud-tasks | — | 查看 Cloud 任务列表 | |||||
codex login | — | 登录 | |||||
codex completion | — | 生成 Shell 补全脚本 | |||||
codex app | — | 开 macOS 桌面应用 | |||||
codex mcp-server | — | 当 MCP 服务器用 | |||||
codex features | — | 管理功能标志 | |||||
codex execpolicy check | — | 检查执行策略（预览功能） |
AGENTS.md 项目指令文件
cx 版的
CLAUDE.md。在里面写项目约定、架构说明、编码风格，cx 每次启动都会先读这个文件。新项目第一件事：启动 cx 后输入
/init 生成 AGENTS.md 框架。查找优先级（从全局到局部）
~/.codex/AGENTS.md（全局）
~/.codex/AGENTS.override.md（全局覆盖）
项目根目录/AGENTS.md
项目根目录/AGENTS.override.md
- 各级子目录中的
AGENTS.md（逐层叠加）
合并规则：每个目录最多取一个文件，从根往下拼接，总大小上限 32 KiB（可配置）。
小技巧
如果团队里不想用 AGENTS.md 这个名字，可以在 config.toml 里配回退文件名：
cx 会按
AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md 的顺序查找。配置（TOML 格式）
配置文件位于
~/.codex/config.toml，优先级从高到低：- CLI 参数（
-c key=value）
- Profile 值
- 项目配置（
.codex/config.toml）
- 用户配置（
~/.codex/config.toml）
- 内置默认值
常用配置项
配置项 | 说明 | model | 使用的模型，如 gpt-5-codex |
sandbox_mode | 沙盒策略 | web_search | 网页搜索模式： cached（默认）/ live（实时） |
review_model | /review 用的模型（可单独指定便宜的） | instructions | 直接写指令替代 AGENTS.md |
安全相关配置
配置项 | 说明 | ㅤ | ㅤ |
sandbox_writeable_roots | workspace-write 下额外可写的路径 | ㅤ | ㅤ |
sandbox_net_allow_workspace_write | 允许沙盒内访问网络 | ㅤ | ㅤ |
project_trust | 标记项目是否受信（不受信的会跳过 .codex/ 目录的配置） | ㅤ | ㅤ |
接入第三方模型
然后配置
model_provider = "my_provider" 即可。功能标志
Shell 补全（建议装上）
装了之后 Tab 补全命令和参数，效率提升明显。
目录文件结构
全局（~/.codex/）
文件 | 用途 |
config.toml | 全局配置 |
token | 登录凭证 |
AGENTS.md | 全局项目指令 |
AGENTS.override.md | 全局指令覆盖 |
项目级（.codex/）
文件 | 用途 |
config.toml | 项目配置（仅受信项目） |
AGENTS.md | 项目指令 |
AGENTS.override.md | 项目指令覆盖 |
沙盒与权限详解
这部分是 cx 的一大亮点——自带沙盒安全机制，cc 目前还没有。
两层安全
- 沙盒（Sandbox）：物理层面限制能干什么——能不能写文件、能不能联网
- 审批策略（Approval）：流程上限制——什么时候需要你点确认
macOS 用 Seatbelt 实现沙盒，Linux 用 Landlock（也可以选 Bubblewrap）。限制是操作系统层面的，cx 自己想绕也绕不过去。
审批策略
策略 | 什么时候问你 |
on-request | 需要越权的时候问（推荐） |
never | 从不问，CI/脚本用 |
实战技巧
新项目起手式
计划先行
建议先
/plan 让 cx 出方案，觉得靠谱了再 /permissions 切到可写模式执行。不然上来就让它改文件，万一改歪了还得回退。省钱秘诀
- 多用
/compact— 每次任务完成后压缩上下文
- 用
@引用文件 — 比手动复制粘贴省 token
- 先只读探路 — 满意了再切可写模式
/model调推理级别 — 简单问题没必要用最高级别
CI 中使用
调试小技巧
- 报错直接整段粘进去，cx 解析堆栈跟踪很强
- 支持贴截图（多模态）
cat error.log | codex exec "explain"管道传日志分析
/diff随时查看改动
cx vs cc 对比
对比项 | Codex CLI (cx) | Claude Code (cc) | 开发商 | OpenAI | Anthropic |
默认模型 | gpt-5.3-codex | Claude Sonnet/Opus | 项目指令文件 | AGENTS.md | CLAUDE.md |
配置格式 | TOML | JSON | 内置沙盒 | ✅ 有（Seatbelt/Landlock） | ❌ 没有 |
全自动 | --full-auto / --yolo | --dangerously-skip-permissions | 恢复对话 | codex resume --last | claude -c |
MCP 支持 | ✅ | ✅ | 开源语言 | Rust | TypeScript |
总结：cc 上手更快、功能更丰富；cx 的沙盒机制更安全，适合对安全性要求高的场景。两者搭配使用——cc 写代码 + cx 改 bug，是不错的工作流。
懒人速查
每天都用
干啥 | 命令 |
开始干活 | cd project && codex |
继续昨天的 | codex resume --last |
快速问个事 | codex exec "how do I..." |
审查代码 | /review |
看改了啥 | /diff |
看 token 用量 | /status |
说错了想改 | Esc Esc |
跑路 | Ctrl+C Ctrl+C 或 /quit |
进阶玩法
功能 | 怎么搞 |
分叉对话试方案 | codex fork --last |
接第三方模型 | config.toml 配 model_provider |
MCP 工具 | config.toml 配 MCP 服务器 |
多代理协作 | /experimental 开 Multi-agents |
VS Code 联动 | 装 Codex Companion 插件 |
导出对话 | /export session.json |
换性格 | /personality friendly |