type
Post
status
Published
date
Mar 6, 2026
slug
summary
tags
AI
教程
转载
category
记录
icon
password
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 目前有两种方式，各有利弊：
cx 在 Windows 上仍是实验性支持，WSL2 是目前最稳的方案。
💡
重要提示：项目要放在 Linux 文件系统里（如 ~/code/），不要放在 /mnt/c/ 下，跨文件系统 IO 会非常慢。
VS Code 配合 WSL 使用
装个 VS Code 的 WSL 扩展，然后在 WSL 终端里：
这样 VS Code 的终端也是 WSL 环境，cx 跑起来没问题。
先确保 Node >= 22 装好了（可以去 nodejs.org 下安装包，或者用 winget install OpenJS.NodeJS）。
原生 Windows 下 cx 用的是实验性的 Windows 沙盒：
  • 通过 Restricted Token + 文件系统 ACL 限制写入范围
  • 创建专用的 Windows Sandbox User 执行命令
  • 用 Windows 防火墙规则限制网络访问
偶尔会有权限问题，Win10 上比 Win11 更容易出问题。
问题
解决办法
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 框架。

查找优先级（从全局到局部）

  1. ~/.codex/AGENTS.md（全局）
  1. ~/.codex/AGENTS.override.md（全局覆盖）
  1. 项目根目录/AGENTS.md
  1. 项目根目录/AGENTS.override.md
  1. 各级子目录中的 AGENTS.md（逐层叠加）
合并规则：每个目录最多取一个文件，从根往下拼接，总大小上限 32 KiB（可配置）。

小技巧

如果团队里不想用 AGENTS.md 这个名字，可以在 config.toml 里配回退文件名：
cx 会按 AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md 的顺序查找。

配置（TOML 格式）

配置文件位于 ~/.codex/config.toml，优先级从高到低：
  1. CLI 参数（-c key=value）
  1. Profile 值
  1. 项目配置（.codex/config.toml）
  1. 用户配置（~/.codex/config.toml）
  1. 内置默认值

常用配置项

配置项
说明
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 目前还没有。

两层安全

  1. 沙盒（Sandbox）：物理层面限制能干什么——能不能写文件、能不能联网
  1. 审批策略（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
原文来源：linux.do 社区帖 by GailingBoling，2026 版
 
 
Loading...
Announcement
记录一些个人折腾的过程
顺便写一点教程和小tips
文中如有错误也可联系我修改
bmluYTI3QGxpbnV4LmRv