Codex CLI教程（一） | 安装指南
Codex CLI教程（二） | 配置指南
Codex CLI教程（三） | 命令指南

一、开篇必懂：2种运行模式 大白话+可视化讲透

1.1 一句话核心定义（零技术门槛）

模式名称	大白话解释	操作环境	核心规则
非交互模式	你电脑自带的「黑窗口」（CMD/PowerShell/终端），直接用codex开头的命令一次性干完活，执行完仍停留在原窗口	系统原生终端，没进入Codex内部	所有命令必须加codex前缀
交互模式	从系统黑窗口执行codex命令，「钻进Codex专属对话环境」，可和AI持续多轮对话、改代码，退出才回到原系统窗口	Codex专属会话环境，已经进入Codex内部	直接输需求，或/开头的斜杠命令，绝对不能加codex前缀

1.2 全流程可视化终端模拟（Windows CMD版，国内用户最常用）

用线条1:1还原真实操作界面，从打开终端到进入/退出交互模式，一步看懂模式切换的边界、提示符变化和命令规则。

步骤1：打开终端，默认进入【非交互模式】

┌─────────────────────────────────────────────────────────────────────────────────┐
│ Windows CMD                                                              │
├─────────────────────────────────────────────────────────────────────────────────┤
│ # 刚打开CMD，默认就是【非交互模式】，提示符是 PS C:\Users\你的用户名>   │
│ PS C:\Users\张三>                                                               │
│                                                                                 │
│ ✅ 【当前模式】非交互模式（系统原生终端）                                      │
│ ✅ 【正确操作】这里只能输 codex 开头的命令                                    │
│ ❌ 【错误操作】直接输需求/斜杠命令，会提示「不是内部或外部命令」              │
└─────────────────────────────────────────────────────────────────────────────────┘

步骤2：非交互模式下，执行基础命令（正确示范）

┌─────────────────────────────────────────────────────────────────────────────────┐
│ Windows CMD                                                              │
├─────────────────────────────────────────────────────────────────────────────────┤
│ PS C:\Users\张三> codex --version                                               │
│ 0.91.0                                                                          │
│                                                                                 │
│ PS C:\Users\张三> codex auth check                                              │
│ ✅ 认证状态正常，接口连通性良好                                                │
│                                                                                 │
│ ✅ 【模式不变】执行完命令，仍停留在非交互模式，提示符还是PS开头                │
└─────────────────────────────────────────────────────────────────────────────────┘

步骤3：从非交互模式，进入【交互模式】

┌─────────────────────────────────────────────────────────────────────────────────┐
│ Windows CMD                                                              │
├─────────────────────────────────────────────────────────────────────────────────┤
│ # 在非交互模式下，执行 codex 命令，即可进入交互模式                            │
│ PS C:\Users\张三> codex                                                         │
│ 🚀 Welcome to Codex CLI | 当前模型：gpt-4o                                     │
│ 📖 输入 /help 查看所有命令，输入 /exit 退出会话                                │
│ >                                                                               │
│                                                                                 │
│ ✅ 【模式切换成功】提示符从 PS C:\> 变成了 >，已经进入Codex交互模式            │
│ ✅ 【正确操作】这里直接输需求，或 / 开头的斜杠命令                            │
│ ❌ 【错误操作】再输 codex 开头的命令，会直接报错                              │
└─────────────────────────────────────────────────────────────────────────────────┘

步骤4：交互模式下，执行操作（正确示范）

┌─────────────────────────────────────────────────────────────────────────────────┐
│ Windows CMD                                                              │
├─────────────────────────────────────────────────────────────────────────────────┤
│ > 用Python写一个带注释的冒泡排序算法                                           │
│ < 这里是AI返回的代码内容...                                                     │
│                                                                                 │
│ > /help                                                                         │
│ < 这里是所有斜杠命令的帮助说明...                                               │
│                                                                                 │
│ ✅ 【模式不变】全程停留在交互模式，提示符始终是 >                              │
└─────────────────────────────────────────────────────────────────────────────────┘

步骤5：从交互模式，退出回到非交互模式

┌─────────────────────────────────────────────────────────────────────────────────┐
│ Windows CMD                                                              │
├─────────────────────────────────────────────────────────────────────────────────┤
│ > /exit                                                                         │
│ 👋 已退出Codex CLI会话                                                         │
│ PS C:\Users\张三>                                                               │
│                                                                                 │
│ ✅ 【退出成功】提示符从 > 变回了 PS C:\>，回到了非交互模式                    │
└─────────────────────────────────────────────────────────────────────────────────┘

1.3 macOS/Linux终端版 可视化简化版

┌─────────────────────────────────────────────────────────────────────────────────┐
│ zsh @ MacBook-Pro ~ %                                                           │
├─────────────────────────────────────────────────────────────────────────────────┤
│ # 非交互模式：提示符是 用户名@设备名 ~ %，命令必须加codex前缀                  │
│ zhangsan@MacBook-Pro ~ % codex --version                                       │
│ 0.91.0                                                                          │
│                                                                                 │
│ # 执行codex进入交互模式，提示符变成 >                                           │
│ zhangsan@MacBook-Pro ~ % codex                                                 │
│ 🚀 Welcome to Codex CLI                                                         │
│ >                                                                               │
│                                                                                 │
│ # 执行/exit退出，回到非交互模式                                                │
│ > /exit                                                                         │
│ zhangsan@MacBook-Pro ~ %                                                        │
└─────────────────────────────────────────────────────────────────────────────────┘

---

二、第一部分：非交互模式命令详解（系统终端执行，必学）

所有命令必须在非交互模式（系统原生终端）执行，以codex开头，按功能分为4大类，全场景兼容。

2.1 信息查看类命令（高频必用）

用于确认软件状态、配置信息、认证状态，是日常排查问题的核心入口。

完整命令	核心作用	适用场景
codex --version	查看当前安装的Codex CLI版本号	安装后验证、版本兼容问题排查
codex --help	查看全量命令列表、参数说明与功能介绍	忘记命令用法时快速查阅，新手必用
codex auth check	检查当前认证状态、API Key有效性、接口连通性	配置后验证、401报错排查、网络问题确认
codex auth list	列出当前已配置的所有认证凭证	多服务商/多账号配置管理
codex config show	查看当前终端会话生效的完整配置（含全局+项目级覆盖项）	配置不生效排查、优先级确认
codex config profile list	查看所有已创建的配置档案（Profile）	多环境切换管理

2.2 配置管理类命令

用于快速修改、重载、切换配置，无需手动编辑配置文件。

完整命令	核心作用
codex config reload	重载当前全局+项目级配置文件，修改配置后无需重启终端
codex config set <配置项> <值>	临时修改指定配置项，优先级高于配置文件，示例：codex config set model gpt-4o
codex config profile use <档案名>	切换到指定名称的配置档案，示例：codex config profile use work
codex config profile create <档案名>	创建新的配置档案，示例：codex config profile create personal

2.3 一次性任务执行命令（核心高频）

无需进入交互模式，执行完直接返回结果，适合简单单轮任务，支持丰富的参数扩展。

基础用法

# 核心格式：codex [可选参数] "你的需求"
# 示例1：直接生成代码，输出到终端
codex "用Java写一个带注释的手机号正则校验工具类"

# 示例2：生成内容并写入文件
codex "给当前Spring Boot项目生成标准README.md文档" > README.md

# 示例3：指定项目目录执行，自动加载项目级配置
codex --cd /path/to/your/project "分析当前项目的src目录结构，生成架构说明"

高频可选参数

参数	完整示例	核心作用
--cd <路径>	codex --cd /Users/xxx/project "分析项目代码"	指定工作目录，自动加载该项目的配置文件
--model <模型名>	codex --model deepseek-coder-v2 "写一个Go语言的HTTP接口"	临时指定本次任务使用的模型
--image <图片路径>	codex --image error-screenshot.png "分析这个报错截图，给出修复方案"	附加图片，让AI分析错误截图、原型图等
--full-auto	codex --full-auto "初始化一个Vue3+TS项目"	全自动模式，自动批准所有文件修改/命令执行，仅信任项目使用
--read-only	codex --read-only "分析当前项目的依赖安全漏洞"	只读模式，禁止AI修改任何本地文件，仅做分析

2.4 认证管理类命令

完整命令	核心作用	兼容性
codex login	启动OpenAI官方OAuth账号登录流程	仅OpenAI官方服务可用
codex logout	退出当前登录账号，清除本地认证凭证	全场景通用

---

三、第二部分：交互模式专属操作（进入Codex环境执行，日常开发核心）

在非交互模式执行codex命令，即可进入交互模式，终端提示符变为>，所有操作无需加codex前缀，核心分为斜杠命令、快捷键、基础对话三大块，全场景兼容。

3.1 基础对话用法

进入交互模式后，直接输入你的需求，按回车发送，AI会实时返回结果，支持多轮对话，自动记忆上下文内容，示例：

> 帮我分析一下当前项目的user.controller.js文件，看看有没有安全问题
< AI返回分析结果与修改建议
> 按照你说的方案，直接修改这个文件
< AI申请文件修改权限，你批准后自动执行

3.2 核心斜杠命令（按功能分类，标⭐为高频必用）

所有命令以/开头，仅在交互模式内有效。

⭐ 会话管理类（高频必用）

命令	完整用法	核心作用
/clear	/clear	清空当前会话的所有历史对话，重置AI上下文，避免旧内容干扰新任务
/context	/context	查看当前会话已加载的上下文、文件列表、token占用情况
/fork	/fork	分叉当前会话，保留之前的对话历史，创建新的独立会话，适合多方案并行测试
/save <会话名>	/save 20240520-用户模块开发	保存当前会话历史，后续可重新加载，适合长周期任务中断恢复
/load <会话名>	/load 20240520-用户模块开发	加载之前保存的会话历史，恢复上下文
/help	/help	查看交互模式支持的所有斜杠命令与详细用法，新手必用
/exit	/exit	退出交互模式，回到系统终端的非交互模式

⭐ 模型与配置类

命令	完整用法	核心作用
/model <模型名>	/model gpt-5.3-codex	实时切换当前会话使用的模型，无需重启会话
/model list	/model list	查看当前配置的服务商支持的所有可用模型
/config	/config	查看当前会话生效的所有配置项
/config set <配置项> <值>	/config set sandbox_mode read-only	临时修改当前会话的配置项，仅本次会话生效
/provider <服务商名>	/provider openai	实时切换当前会话使用的模型服务商

⭐ 开发效率工具类

命令	完整用法	核心作用
/review <文件路径>	/review src/user.controller.js	审查指定文件的代码，指出潜在BUG、性能问题、规范问题并给出修改建议
/explain <文件路径>	/explain src/utils/request.js	逐行解释指定文件的代码逻辑、依赖关系、执行流程
/test <文件路径>	/test src/api/user.js	为指定的代码文件生成对应的单元测试用例
/docs <目录/文件路径>	/docs src/	为指定目录/文件生成接口文档、注释说明
/diff	/diff	查看当前会话中AI对代码文件做出的所有修改对比
/revert <文件路径>	/revert src/user.controller.js	撤销AI对指定文件做出的修改，恢复到原始状态

审批安全类

命令	完整用法	核心作用
/approve	/approve	批准AI申请执行的命令、文件修改操作（审批模式下）
/deny	/deny	拒绝AI申请执行的操作
/logout	/logout	退出当前登录的账号，清除本地认证凭证

3.3 高频快捷键（全系统适配）

所有快捷键仅在交互模式内生效，熟练使用可大幅提升操作效率。

快捷键	核心作用	适用场景
Ctrl+C	中断当前正在执行的AI请求，停止生成内容	AI生成内容不符合预期、请求卡死时快速终止
Ctrl+L	清空当前终端屏幕，保留会话上下文	屏幕内容过多，需要清爽的操作界面
Shift+Enter	换行输入多行内容，不发送请求	输入多行代码、长提示词时，避免误发送（Windows用户若无效，可使用Alt+Enter）
Tab	自动补全当前输入的命令、文件路径	快速输入斜杠命令、文件路径，避免手动输入错误
↑/↓	切换历史输入的指令/提示词	重复使用之前的提示词，无需重复输入
Ctrl+R	搜索历史输入的内容	快速查找之前用过的长提示词、命令

---

四、实战场景落地（明确推荐模式，可直接复制）

以下为日常开发最高频场景，明确标注推荐使用模式，所有示例可直接复制替换对应内容使用。

场景1：快速生成代码片段/简单需求

推荐模式：非交互模式，一次性执行，无需进入会话

# 示例：生成MySQL用户表创建语句
codex "写一个MySQL的用户表创建语句，包含用户ID、手机号、邮箱、创建时间等常用字段，加索引和注释"

场景2：错误截图/日志排查BUG

推荐模式：非交互模式，直接附加图片/日志，快速获取修复方案

# 示例1：分析错误截图
codex --image ./error-screenshot.png "分析这个Spring Boot报错截图，告诉我错误原因、触发条件和完整修复步骤"

# 示例2：分析报错日志
codex "下面是我的Node.js服务报错日志，帮我定位BUG并给出修复方案：[粘贴你的日志内容]"

场景3：项目全流程分析/复杂代码重构

推荐模式：交互模式，多轮对话，持续上下文记忆

# 系统终端（非交互模式）执行，进入项目目录的交互模式
codex --cd /path/to/your/project

# 进入交互模式后，分步输入需求
> 分析当前项目的目录结构、技术栈和核心模块，生成架构说明
< AI返回分析结果
> 重点看user模块的代码，重构里面的接口，优化性能，统一异常处理
< AI返回重构方案，申请修改文件权限
> /approve
< AI执行修改
> 给重构后的接口生成单元测试用例
< AI生成测试用例

场景4：代码审查/合规校验

推荐模式：非交互+交互模式结合

# 1. 非交互模式快速生成单文件审查报告
codex --cd /path/to/project "审查src/utils/auth.js文件，指出安全漏洞、性能问题，生成审查报告" > code-review.md

# 2. 交互模式逐行优化
codex --cd /path/to/project
> 按照审查报告，逐行优化auth.js文件，保留原有功能不变
< AI执行优化

场景5：项目初始化/脚手架搭建

推荐模式：非交互模式（全自动）

# 全自动初始化项目，仅在信任的空目录使用
codex --full-auto --cd /path/to/new-project "初始化一个React+TypeScript+Vite项目，配置ESLint、Prettier、React Router、Zustand，生成基础目录结构和首页示例"

---

五、进阶效率命令

5.1 MCP服务管理命令（非交互模式执行，全场景兼容）

MCP（Model Context Protocol）是Codex CLI的核心扩展能力，可连接文件系统、数据库、GitHub等外部工具，扩展AI能力边界。

# 查看当前已配置的所有MCP服务
codex mcp list

# 启动指定的MCP服务
codex mcp start 服务名称

# 停止指定的MCP服务
codex mcp stop 服务名称

# 查看MCP服务的运行状态与日志
codex mcp logs 服务名称

5.2 自定义指令加载（非交互模式执行，全场景兼容）

# 加载自定义指令文件启动，全局约束AI的行为规范
codex --instructions ./custom-instructions.md "按照我指定的代码规范，重构当前项目的所有组件"

# 加载项目级AGENTS.md文件，适配项目专属规范
codex --cd /path/to/project "按照项目根目录的AGENTS.md规范，开发商品管理相关接口"

---

六、新手避坑红线+高频问题速解

6.1 新手绝对不能碰的5条红线

1. ❌ 交互模式里输codex xxx命令，必报错，正确做法是直接输需求或/开头的命令；
2. ❌ 非交互模式里直接输/help、需求文本，必报错，正确做法是所有命令加codex前缀；
3. ❌ 不信任的项目里用--full-auto/--yolo全自动模式，可能导致文件被误改/删除；
4. ❌ 把auth.json提交到Git仓库，必导致API Key泄露，必须配置.gitignore；
5. ❌ 用0.92版本，存在粘贴内容丢失的核心bug，必须用0.91或0.93+版本。

6.2 高频报错速解

非交互模式常见报错

报错现象	核心原因	解决方案
codex: command not found	npm全局安装路径未加入系统环境变量	参考第一篇安装篇的解决方案，配置环境变量
401 Unauthorized 未授权	API Key错误/过期、配置文件路径错误	执行codex auth check检查认证状态，重新核对API Key与配置文件路径
配置不生效，始终用全局配置	未在项目根目录执行命令，或项目级配置文件格式错误	确认当前终端路径是项目根目录，执行codex config show确认生效路径，校验TOML/JSON格式合法性

交互模式常见报错

报错现象	核心原因	解决方案
unknown command: codex	进入交互模式后，仍加了codex前缀	直接输入需求，或/开头的斜杠命令，无需加codex
AI生成内容卡死、无响应	网络波动、上下文过长、模型服务超时	按Ctrl+C中断请求，执行/clear清空上下文，切换到更稳定的模型重试
提示「沙箱模式限制，无法修改文件」	当前配置为只读模式，无文件写入权限	执行/config set sandbox_mode workspace-write，开启工作目录写入权限
图片分析无结果/报错	模型不支持多模态、图片路径错误、格式不支持	确认使用的模型支持多模态能力，使用绝对路径，图片格式为PNG/JPG，大小不超过20MB

6.3 通用排错检查清单

1. 执行codex --version确认软件安装正常；
2. 执行codex auth check确认认证与网络连通正常；
3. 执行codex config show确认配置文件生效路径正确；
4. 校验配置文件的JSON/TOML格式无语法错误；
5. 确认使用的模型支持对应功能，无服务商能力限制。

---

七、Codex 权限等级 完整命令清单（从高到低）

权限等级	完整命令	快捷别名	核心规则（一眼看懂）	风险等级
🚨 最高（裸奔无限制）	codex --dangerously-bypass-approvals-and-sandbox	codex --yolo	❌ 无沙盒 + ❌ 无审批 可访问整个系统、任意文件、执行任意命令	极高
🔥 次高（推荐全自动）	codex --full-auto	无	✅ 沙盒锁定当前文件夹 + ❌ 无审批 只能操作当前项目，不能改系统	低
⚖️ 中等（严格沙盒写入）	codex --sandbox=write	无	✅ 强沙盒 + ❌ 无审批 仅能修改当前目录文件，禁止执行系统命令/联网	极低
🔍 较低（只读查看）	codex --sandbox=read-only	无	✅ 强沙盒 + ❌ 无审批 只能看代码，不能修改任何文件	无
🛡️ 最低（手动确认）	codex --interactive	无	✅ 沙盒 + ✅ 每步手动审批 执行任何操作都需要你点确认	无

---

✅ 默认模式（直接输 codex 就是这个）
默认命令：直接输入
codex 等价于：codex --interactive（最低权限、手动审批模式）

---