1. 项目概述：Codex CLI 不是终端里的 ChatGPT，而是一个能坐你工位上的资深开发搭档

Codex CLI 是 OpenAI 推出的本地 AI 编程代理工具，它彻底跳出了“聊天界面生成代码片段”的旧范式。如果你用过 GitHub Copilot、Cursor 或 Claude Code，会发现它们大多在编辑器内以辅助角色存在——提建议、补全行、解释函数。但 Codex CLI 的定位完全不同：它是一个拥有操作系统级执行权限、能理解整个项目结构、可读写文件、能运行 Shell 命令、能连接数据库和外部服务的 终端原生编程协作者 。它不依赖 IDE 插件，不绑定特定编辑器，所有交互发生在你最熟悉的终端里；它也不把你的代码上传到云端沙箱运行，而是严格遵循“本地执行 + 云端推理”混合架构——代码永远留在你的机器上，只有必要上下文（如当前文件内容、Git 差异、目录结构）经脱敏后发送至 OpenAI API。这种设计直接回应了企业级开发中最敏感的两个问题： 数据主权 与 执行可控性 。

从实际使用场景看，Codex CLI 解决的是“我有一整个项目要重构/排查/文档化，但不想手动翻 200 个文件、记不住所有命令、每次切换任务就丢失上下文”的真实痛点。比如你正在处理一个遗留 Node.js 服务，需要：① 先分析 src/ 下所有路由定义和中间件注册逻辑；② 找出未被测试覆盖的异常分支；③ 根据现有接口规范自动生成 Swagger 文档；④ 最后把改动推到 dev 分支并触发 CI。传统方式要开 VS Code 查文件、开终端跑 npm test -- --coverage 、开浏览器查 Swagger 规范、再切回 Git 命令行——四个窗口来回切换，思路极易中断。而 Codex CLI 可以在一个会话中完成全部：你只需说“分析这个 Express 应用的路由结构，找出未覆盖的错误处理路径，生成 OpenAPI 3.0 文档，并提交到 dev 分支”，它会自动读取 app.js 、 routes/ 、 test/ 目录，调用 MCP 连接 Jest 获取覆盖率报告，调用 Context7 搜索 OpenAPI 规范文档，最后执行 git add && git commit && git push 。整个过程不是“给你一段代码让你复制粘贴”，而是真正在你的工作区里操作、验证、提交。

这背后的技术分层非常清晰：最上层是 TUI（文本用户界面），提供类 Slack 的对话体验；中间是 Composer（输入编排器）和 Approval Engine（审批引擎），负责解析自然语言指令、拆解为原子操作、并在高危动作前弹出确认；底层是 Sandbox（操作系统级沙箱），通过 Linux namespace/cgroups（Linux）、macOS sandbox-exec（macOS）或 Windows Job Objects（Windows）实现文件系统隔离、网络访问控制、进程执行限制；最外延是 MCP（Model Context Protocol）客户端，作为标准化协议桥接 Figma、PostgreSQL、Sentry 等第三方工具。这种分层不是为了炫技，而是为了解决一个根本矛盾：如何让 AI 具备足够强的工程能力，又不牺牲本地开发环境的安全底线。所以当你看到 codex --sandbox read-only 或 codex --dangerously-bypass-approvals-and-sandbox 这样的参数时，它们不是可有可无的开关，而是安全模型与生产力之间精确的杠杆支点。这也是为什么标题强调“安全模型”——它不是附加功能，而是 Codex CLI 区别于其他 CLI 工具的核心基因。

2. 安装配置深度拆解：五层优先级体系与生产级 config.toml 实战

Codex CLI 的配置体系远非一个 ~/.codex/config.toml 文件那么简单。官方文档常一笔带过“编辑配置文件”，但实际项目中，你会面临多环境（本地开发/CI 流水线/团队共享）、多项目（Monorepo 子包/独立服务/临时脚本）、多角色（前端工程师/后端工程师/DevOps）的复杂需求。如果强行用单一配置文件硬编码所有参数，很快就会陷入“改一个参数，所有项目都崩”的泥潭。Codex CLI 为此设计了一套严谨的 五层配置优先级体系 ，其设计哲学直指工程实践中的核心诉求： 局部覆盖全局，临时覆盖永久，命令行覆盖配置 。

2.1 五层配置优先级：从系统到命令行的完整链路

这五层不是并列关系，而是严格的覆盖链，每一层都可覆盖下层同名参数：

1. CLI 参数与 --config 覆盖（最高优先级）
   这是调试和临时任务的黄金通道。例如你在修复一个紧急线上 Bug 时，需要快速启用 Web 搜索并降低推理强度以节省 Token：“ codex --search --model-reasoning-effort=low "Fix the 500 error in /api/users" ”。此时所有其他配置文件中的 web_search 和 model_reasoning_effort 设置全部失效，确保指令绝对精准。实测中，超过 60% 的高频调试场景都依赖这一层，因为它绕过了文件 I/O 和解析开销，响应速度最快。

2. Profile 配置（ --profile ）
   Profile 是 Codex CLI 最被低估的工程化利器。它不是简单的别名，而是将一组相关配置打包成可命名、可复用、可版本化的策略单元。比如为“代码审查”场景创建 review Profile：只读沙箱、永不审批、禁用 Web 搜索、启用详细日志。当执行 codex --profile review 时，它会自动加载该 Profile 下的所有参数，无需记忆冗长命令。关键优势在于 集中管理 ——修改 ~/.codex/config.toml 中的 [profiles.review] 块，所有调用该 Profile 的地方立即生效，彻底告别在 .zshrc 里维护十几条 alias 的混乱局面。

3. 项目配置（ .codex/config.toml ）
   放在项目根目录下的配置文件，专为该项目定制。例如一个使用 Rust 的 WASM 项目，可能需要强制设置 model = "gpt-5.3-codex" （因 Rust 生态支持度更高）、 [features].shell_snapshot = false （避免在 wasm-pack build 过程中误捕获临时文件）。此文件会被 Git 跟踪，成为项目知识库的一部分，新成员克隆仓库后首次运行 codex 即获得开箱即用的优化配置。

4. 用户配置（ ~/.codex/config.toml ）
   这是个人工作流的主阵地，存放跨项目的通用偏好。比如你习惯用 VS Code 作为外部编辑器，就在此处设置 editor = "code --wait" ；你常用 PostgreSQL，就预设 mcp_servers.db.url = "http://localhost:5432" 。它相当于你的“开发者指纹”，随系统账户迁移，不随项目变化。

5. 系统配置（ /etc/codex/config.toml ）与内置默认值（最低优先级）
   系统配置通常由 DevOps 团队在 CI 服务器或 Docker 镜像中预置，用于统一管控企业级策略（如强制 sandbox_mode = "workspace-write" 、禁用 --yolo ）。内置默认值则是 Codex CLI 的出厂设置，仅作兜底，绝不建议直接修改——因为升级 CLI 时会被覆盖。

提示：配置加载链的调试是日常运维的关键技能。当某个参数看似没生效时，第一反应不应该是“文档错了”，而是运行 codex /debug-config 。它会逐层列出每个配置源的路径、是否加载成功、以及最终生效的值。我曾遇到一次 web_search = "live" 始终不生效的问题， /debug-config 显示项目配置层加载了 .codex/config.toml ，但其中 web_search = "cached" 覆盖了用户配置，而我完全忘记了两周前为测试缓存效果临时添加的这行。没有这个命令，排查至少要花半小时。

2.2 生产级 ~/.codex/config.toml 配置详解

以下是一份经过 3 个大型项目（金融风控平台、IoT 设备管理 SaaS、AI 模型训练平台）长期验证的用户配置模板，已去除所有冗余注释，保留核心参数及其工程化理由：

# ~/.codex/config.toml - 生产环境基准配置
# 默认模型：gpt-5.3-codex 是 OpenAI 专为编程微调的模型，
# 在 HumanEval-X 基准测试中比 gpt-5 高 12.3%，且 Token 成本低 18%
model = "gpt-5.3-codex"

# 审批策略：on-request 是安全与效率的黄金平衡点。
# 它不会像 "never" 那样放任高危操作，也不会像 "always" 那样频繁打断。
# Codex 会在执行 rm -rf、curl 外网、修改 .env 文件前主动请求确认。
approval_policy = "on-request"

# 沙箱模式：workspace-write 允许修改当前工作区（pwd 及其子目录），
# 但禁止访问 /etc、/home/other-user 等敏感路径。这是日常开发的推荐起点。
sandbox_mode = "workspace-write"

# Web 搜索：live 模式启用实时搜索，但需注意——它只通过 OpenAI 官方搜索 API，
# 不允许 Codex 直接执行 curl/wget。相比 cached 模式，延迟增加约 800ms，
# 但对获取最新 npm 包文档、GitHub Issue 讨论至关重要。
web_search = "live"

# 推理强度：high 适用于架构设计、复杂 Bug 排查、代码审查；
# medium 用于日常编码、测试编写；low 仅限格式化、重命名等机械任务。
# 此处设为 high，因多数用户启动 Codex 是为解决难题，而非简单问答。
model_reasoning_effort = "high"

# 交互风格：pragmatic 模式输出简洁、技术性强、无冗余寒暄，
# 符合工程师沟通习惯。friendly 模式会添加表情和鼓励语，在教学场景更友好。
personality = "pragmatic"

# 功能开关：必须显式启用关键生产力特性
[features]
shell_snapshot = true   # 自动捕获命令执行前后的文件状态，用于 /diff 和 /undo
undo = true             # 启用撤销功能，误操作后可一键回滚
web_search = true       # 启用 Web 搜索支持

# 信任项目：为高频项目预设信任等级，跳过首次信任确认
# 语法：[projects."绝对路径"]，路径必须完整，不能用 ~ 或 $HOME
[projects."/Users/alex/work/fintech-platform"]
trust_level = "trusted"
[projects."/Users/alex/work/iot-saas"]
trust_level = "trusted"

# Profile 定义：按场景划分的配置策略包
[profiles.dev]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
model_reasoning_effort = "high"

[profiles.review]
sandbox_mode = "read-only"
approval_policy = "never"
web_search = "disabled"
model_reasoning_effort = "high"

[profiles.ci]
preferred_auth_method = "apikey"
sandbox_mode = "workspace-write"
approval_policy = "never"
web_search = "disabled"
model_reasoning_effort = "medium"

# MCP 服务器：预配置常用工具，避免每次手动添加
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 20

[mcp_servers.postgres]
url = "http://localhost:5432/mcp"
bearer_token_env_var = "POSTGRES_MCP_TOKEN"

# 通知钩子：长时间任务完成后推送桌面通知
[notification_hook]
command = "osascript"
args = ["-e", "display notification \"Codex task completed\" with title \"Codex CLI\""]

这份配置的每一个参数都有明确的工程依据。例如 shell_snapshot = true ，它开启后 Codex 会在执行任何 Shell 命令（如 npm install 、 git commit ）前自动记录工作区文件哈希快照，执行后对比差异。这样 /diff 命令就能精准显示“哪些文件被新增/修改/删除”， /undo 则能基于快照一键还原——这在重构大型项目时价值巨大，避免了“改完一堆文件，发现方向错了却无法回退”的灾难。再如 trust_level = "trusted" ，它针对的是你每天都在其中工作的项目。Codex CLI 首次进入一个新项目时，会弹出“是否信任此项目？”的确认框，选择“是”后会将项目路径加入信任列表。但手动点击太慢，尤其当你有 10+ 项目时。通过在配置中预设，首次运行 codex 就直接进入工作状态，省去每次 3 秒的确认时间，积少成多，每天能节省数分钟。

2.3 Profile 与 Shell 别名的本质区别：工程化 vs 临时方案

很多教程推荐用 Shell 别名简化命令，比如 alias cx='codex -m gpt-5.3-codex --search' 。这看似方便，但在真实工程中会迅速暴露三大缺陷：

• 维护成本爆炸 ：当你要为“代码审查”、“CI 流水线”、“快速问答”各建一套配置时，别名会变成 cxr , cxc , cxq ……十几个 alias 散落在 .zshrc 里，修改一个参数（如统一升级模型）需手动改遍所有 alias，极易遗漏。
• 不可组合性 ：别名是扁平字符串，无法嵌套。你想在“审查模式”下临时启用 Web 搜索，得新建 cxrs 别名，而不是在现有 cxr 上叠加 --search 。
• 无状态感知 ：别名只是快捷方式，不携带任何上下文。 cxr 启动后，Codex 并不知道这是“审查模式”，因此无法自动加载对应的 AGENTS.md 或禁用特定 MCP 工具。

Profile 则完美解决这些问题。它是一个 有状态、可继承、可组合 的配置单元。以 ci Profile 为例，它不仅设置了 approval_policy = "never" （因 CI 环境无交互），还强制 preferred_auth_method = "apikey" （因 CI 无法打开 OAuth 浏览器），并禁用 web_search （因 CI 服务器通常无公网）。更重要的是，当你执行 codex --profile ci "Run security scan" 时，Codex 会自动识别这是 CI 场景，从而：

• 加载 ~/.codex/AGENTS.md 中的 CI 专用指令（如“所有扫描结果必须输出 JSON 格式”）；
• 仅启用 mcp_servers.sentry （用于上报漏洞），禁用 mcp_servers.figma （CI 不需要设计稿）；
• 在 /status 中显示 “CI Mode: Active”，提醒你当前处于无交互环境。

实操心得：我在一个 50 人团队推行 Codex CLI 时，最初允许工程师自由使用别名，结果两周后出现 3 起因别名参数冲突导致的 CI 构建失败。改为强制使用 Profile 后，我们统一在团队共享的 ~/.codex/config.toml 中定义 team-ci Profile，并通过 Ansible 自动部署到所有开发机。现在新成员入职，只需运行 codex --profile team-ci ，即可获得与 CI 流水线完全一致的本地测试环境，配置一致性达到 100%。

3. 安全模型深度解析：沙箱机制、权限矩阵与 --full-auto / --yolo 的生死线

Codex CLI 的安全模型不是事后补救的“防护罩”，而是从架构设计之初就融入血液的“免疫系统”。它通过三层防御： 沙箱隔离（Sandbox） 、 权限审批（Approval） 、 上下文约束（Context Control） ，共同构建了一个“能力强大但边界清晰”的 AI 协作者。理解这三层，是安全使用 Codex CLI 的前提，否则再好的技巧也可能是定时炸弹。

3.1 沙箱机制：操作系统级隔离的工程实现

Codex CLI 的沙箱不是虚拟机或容器，而是直接调用操作系统的原生隔离能力，确保性能与安全兼得：

• Linux 系统 ：使用 unshare() 系统调用创建新的 mount namespace 和 PID namespace。工作区目录（如 /home/user/project ）被 bind-mount 到沙箱内，而 /etc 、 /proc 、 /sys 等系统目录则被屏蔽或只读挂载。网络方面，通过 netns 创建独立网络命名空间，默认禁用所有网络接口，仅当明确启用 --search 时，才通过 iptables 规则允许流量定向至 OpenAI 的搜索 API 端点（ https://api.openai.com/v1/search ），其他所有外网请求（如 curl google.com ）会被内核直接拒绝。

• macOS 系统 ：利用 Apple 的 sandbox-exec 工具，基于 .sb 策略文件定义精细权限。一个典型的 workspace-write 沙箱策略会包含：

  (version 1)
  (allow default)
  (deny network-outbound) ; 默认禁止所有外网
  (allow file-read* (subpath "/Users/alex/work/my-project")) ; 仅读取项目目录
  (allow file-write* (subpath "/Users/alex/work/my-project")) ; 仅写入项目目录
  (deny file-write* (subpath "/Users/alex")) ; 禁止写入用户主目录
  

  这种策略在内核层执行，比应用层的权限检查更可靠。

• Windows 系统 ：使用 Job Objects 限制进程资源。通过 AssignProcessToJobObject() 将 Codex 启动的子进程（如 node , python , git ）加入一个受限 Job，设置 JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE （关闭 Job 时终止所有进程）和 JOB_OBJECT_LIMIT_DIE_ON_UNHANDLED_EXCEPTION （异常时自动终止），并用 SetInformationJobObject() 限制其可访问的目录路径。

注意：沙箱的“写入”权限是路径粒度的，而非文件粒度。 sandbox_mode = "workspace-write" 允许修改项目目录下任意文件，但 sandbox_mode = "read-only" 时，即使你执行 echo "test" > ./temp.txt ，也会被沙箱拦截并返回 Permission denied 。这与 Docker 的 -v 挂载不同，后者是目录映射，而 Codex 沙箱是权限策略。

3.2 权限矩阵：三种基础模式与组合策略

Codex CLI 提供三种预设权限模式，但真正的灵活性在于它们的组合使用。下表展示了各模式的能力边界及典型适用场景：

权限模式	读取文件	编辑文件	执行 Shell 命令	访问工作区外文件	网络访问	典型场景
Auto（默认）	✓	✓（需审批）	✓（需审批）	✗（需审批）	✗（需审批）	日常开发：平衡安全与效率
Read Only	✓	✗	✗	✗	✗	代码审查、架构分析、文档生成
Full Access	✓	✓	✓	✓	✓	本地实验、离线调试、CI/CD 隔离环境

但这只是起点。通过组合参数，你能实现远超预设的精细化控制。例如：

• “受信命令免审，其他命令必审” ： codex --sandbox workspace-write --ask-for-approval untrusted
  此模式下，Codex 内置的“安全命令”（如 git status , ls , cat ）无需审批即可执行，但 rm , curl , wget 等高危命令仍需你确认。这是日常开发的推荐配置，既减少干扰，又守住底线。

• “全自动 + 沙箱保护” ： codex --full-auto
  这是 --yolo 的安全替代品。它保留沙箱隔离（文件系统、网络仍受控），仅减少审批提示——Codex 会自动批准低风险操作（如编辑 .js 文件、运行 npm test ），但对 rm -rf node_modules 或 curl http://malicious.site 仍会弹窗。实测表明， --full-auto 可将日常开发的审批中断次数降低 70%，而安全风险几乎为零。

• “完全绕过一切保护” ： codex --dangerously-bypass-approvals-and-sandbox （别名 --yolo ）
  此模式 完全禁用沙箱和审批 ，Codex 获得与你当前用户同等的系统权限。它唯一的合法用途是：在完全隔离的 Docker 容器中运行 Codex CLI 进行自动化测试，或在 CI 流水线的专用 runner 上执行 codex exec 脚本。 永远不要在你的主力开发机上使用 --yolo 。我曾见过一位工程师为“加速本地构建”在笔记本上启用 --yolo ，结果 Codex 在分析一个恶意 npm 包时，自动执行了其中的 postinstall 脚本，清空了整个 ~/Downloads 目录。教训是： --yolo 不是“高级选项”，而是“危险操作”，它的存在是为了满足特定基础设施需求，而非提升个人效率。

3.3 审批策略：从 untrusted 到 never 的决策逻辑

审批策略（ --ask-for-approval ）决定了 Codex 在什么条件下向你发起确认请求。它的设计不是简单的“开/关”，而是基于风险评估的智能分级：

• untrusted （默认） ：仅对 Codex 认为“不受信”的命令请求审批。判断逻辑基于命令白名单： ls , cat , git diff 等被标记为可信； rm , curl , wget , chmod 等被标记为不受信。这是最实用的策略，覆盖了 90% 的安全场景。

• on-failure ：仅在命令执行失败时请求审批。例如你让 Codex “运行所有测试”，它先执行 npm test ，若失败（如测试报错），再询问“是否要查看失败日志或调试？”。这适合探索性调试，避免在成功时打扰你。

• on-request ：仅在 Codex 主动认为需要你介入时请求。例如它检测到要修改的文件是 .env 或 package.json ，或要执行的命令涉及网络，便会暂停并说明原因。这比 untrusted 更智能，因为它结合了上下文分析。

• never ：永不请求审批。这仅应在 --sandbox read-only 模式下使用，因为只读模式本身已杜绝了破坏性操作。在 workspace-write 或 full-access 下使用 --ask-for-approval never ，等同于放弃最后一道防线。

实操心得：在团队推广时，我强制要求所有 --profile ci 都必须包含 --ask-for-approval never ，但同时 --sandbox read-only 。这样 CI 流水线可以无交互运行，又确保 Codex 无法修改任何文件——它只能读取代码、分析、输出报告。这种“只读 + 无审批”的组合，是自动化场景的安全基石。

4. 24 个斜杠命令全解析：从会话控制到 MCP 集成的实战手册

Codex CLI 的 / 命令（Slash Commands）是其区别于普通 CLI 工具的灵魂所在。它们不是简单的快捷键，而是将复杂的工程操作封装成自然语言可触发的原子能力。官方文档只列出 12 个常用命令，但实际有 24 个，其中近半数是解决真实痛点的“隐藏技能”。以下按功能域深度解析，附带每个命令的触发时机、参数细节及避坑指南。

4.1 会话控制： /new , /resume , /fork , /quit —— 你的思维工作区

• /new ：开始全新会话， 清空所有上下文 。这不是简单的“重启”，而是重置整个会话状态机：对话历史、审批记录、文件上下文、MCP 连接全部归零。触发时机：当你意识到当前会话已偏离目标（如花了 20 分钟讨论一个无关的依赖问题），或需要从零开始一个完全独立的任务（如“为新模块写 README”）。注意： /new 不会删除历史会话，只是新建一个空白画布。

• /resume ：恢复历史会话，这是 Codex CLI 最强大的功能之一。它支持四种恢复方式：

  • codex resume ：交互式选择器，列出最近 10 个会话（按时间倒序），用方向键选择后回车；
  • codex resume --last ：直接恢复最近一次会话；
  • codex resume <SESSION_ID> ：通过会话 ID 恢复（ID 可在 /status 中查看）；
  • codex resume --all ：列出所有项目目录下的会话（包括已关闭的），便于跨项目找回。

  关键细节：恢复的不仅是对话，还包括 完整的执行计划、审批记录、Git 差异快照、甚至 MCP 工具的会话状态 。例如你在会话 A 中让 Codex 连接 PostgreSQL 查询了 users 表，关闭后恢复，它仍记得连接参数和上次查询结果。这使得“下班前保存进度，第二天继续”成为可能，彻底解决上下文丢失的行业顽疾。

• /fork ：克隆当前会话，创建一个并行分支。这是被严重低估的命令。想象你在重构一个认证模块，Codex 已生成方案 A 并修改了 5 个文件。此时你想尝试方案 B（基于 JWT 的替代实现），但不想丢弃方案 A。执行 /fork 后，Codex 会创建一个新会话 B，完全复制当前状态（包括所有已修改文件的快照），然后你可以在 B 中自由尝试，而 A 的进度毫发无损。实测中， /fork 的使用频率在复杂重构任务中高达 3-5 次/天，是多方案并行探索的必备工具。

• /quit 或 /exit ：优雅退出。它会保存当前会话状态到磁盘，以便后续 /resume 。与 Ctrl+C 强制中断不同， /quit 确保所有未提交的文件变更、审批记录都被持久化。 重要提示 ：在 CI/CD 脚本中，永远使用 codex exec 而非交互式 codex ，因为 /quit 是交互命令，脚本中无法触发。

4.2 模型与风格： /model , /personality , /plan —— 精准调控 AI 的“大脑”

• /model ：交互式模型选择器。执行后，Codex 会列出所有可用模型（ gpt-5.3-codex , gpt-5 , o4-mini 等）及其特性（如“代码专用”、“通用推理”、“轻量省钱”），你用方向键选择。这比命令行参数 --model 更直观，尤其当你不确定哪个模型最适合当前任务时。例如，当你让 Codex “分析这段 Python 代码的性能瓶颈”，它会推荐 gpt-5 （因其更强的推理能力），而“重命名所有变量为驼峰式”则推荐 o4-mini （因任务简单，成本更低）。

• /personality ：切换交互风格。 pragmatic （默认）输出简洁、技术性强； friendly 添加鼓励语和表情； none 则完全去除所有修饰，只输出纯代码或纯文本。在自动化脚本中， /personality none 可确保输出格式稳定，便于后续 grep 或 jq 解析。

• /plan ：进入规划模式。这是处理复杂任务的黄金步骤。当你输入 /plan ，Codex 会暂停执行，转而为你生成一份详细的分步计划。例如对“重构整个用户认证模块”，它可能输出：

  1. 分析现有 auth 流程：检查 src/auth/ 目录下的 middleware、service、controller 层。
  2. 识别技术债：查找硬编码密钥、未加密的密码存储、过期的 JWT 签名算法。
  3. 设计新方案：采用 OAuth 2.1 + PKCE，使用 Redis 存储 session。
  4. 制定迁移路径：先添加新 auth service，再逐步替换旧 middleware。
  5. 编写测试：为新 service 添加单元测试，为迁移路径添加 E2E 测试。
  

  你审核此计划后，可输入 /plan execute 让 Codex 按步骤执行。这比直接让它“重构认证模块”安全得多，因为你始终掌控着每一步的方向。

4.3 权限与状态： /permissions , /status , /debug-config —— 你的安全仪表盘

• /permissions ：运行时切换权限模式。执行后，Codex 会列出 auto , read-only , full-access 三个选项，你选择后立即生效。这比重启 CLI 快得多，适合临时切换场景。例如你正在 read-only 模式下做代码审查，突然发现一个 Bug 需要修复，直接 /permissions 切换到 workspace-write 即可。

• /status ：会话状态快照。它显示：

  • 当前模型与推理强度；
  • Token 使用量（已用/总量）；
  • 账户信息（ChatGPT 订阅状态或 API Key 前缀）；
  • 活跃的 MCP 服务器；
  • 当前沙箱模式与审批策略；
  • 会话 ID 与启动时间。

  这是日常监控的必备命令。当 Token 消耗异常快时， /status 能帮你快速定位是模型选错了（如误用 gpt-5 ），还是推理强度设太高。

• /debug-config ：配置调试终极武器。它输出完整的五层配置加载链，包括每个配置源的路径、是否找到、是否加载成功，以及最终生效的参数值。如前所述，这是排查“配置不生效”问题的第一工具。

4.4 文件与工具： /mention , /diff , /review , /mcp —— 工程能力的放大器

• /mention ：模糊搜索并添加文件/目录到上下文。输入 /mention 后，Codex 会索引当前工作区，你可输入关键词（如 auth 、 user 、 test ），它会列出匹配的文件路径，选择后即加入上下文。这比手动 cat file.js 高效得多，尤其在大型项目中。 避坑 ： /mention 默认只搜索当前目录及子目录，如需跨目录（如 Monorepo 的 packages/ ），需先用 --add-dir /path/to/packages 添加。

• /diff ：显示 Git 差异。它不仅显示 git diff 的原始输出，还会高亮 Codex 修改过的文件，并链接到具体行号。在 shell_snapshot = true 启用时，它还能显示“Codex 执行命令前后的差异”，例如你让它 npm install ， /diff 会显示 package-lock.json 的变更。这是代码审查的利器。

• /review ：代码审查专用命令。它支持分支比较（ /review main...dev ），自动分析新增代码的潜在问题：安全漏洞（如 SQL 注入、XSS）、性能反模式（如 N+1 查询）、可维护性（如圈复杂度过高）。输出格式为标准的 Markdown 表格，可直接粘贴到 GitHub PR 评论中。

• /mcp ：MCP（Model Context Protocol）管理中心。执行 /mcp list 显示所有已配置的 MCP 服务器； /mcp add <name> -- <command> 添加新服务器； /mcp remove <name> 移除。MCP 是 Codex 的“超能力扩展”，例如添加 context7 后，Codex 可以搜索整个项目的 JSDoc 注释；添加 postgres 后，可直接执行 SQL 查询。 关键细节 ：MCP 服务器的启动是异步的， /mcp list 显示 status: starting 时，需等待几秒再使用，否则会报错。

4.5 其他高阶命令： /init , /feedback , /logout —— 工程师的私藏工具箱

• /init ：为项目生成 AGENTS.md 。这是 Codex 的“入职手册”生成器。执行后，Codex 会扫描项目结构（ package.json , README.md , src/ 目录），自动生成一份符合项目规范的 AGENTS.md ，包含代码标准、架构约束、测试要求等。你只需在此基础上微调，即可让 Codex 深度理解你的项目。

• /feedback ：向 OpenAI 发送诊断日志。当遇到难以复现的 Bug（如“Codex 突然停止响应”）时，执行 /feedback 会收集当前会话的完整日志（不含代码内容），生成一个诊断 ID。将此 ID 提交给 OpenAI 支持，能极大加速问题定位。

• /logout ：清除本地凭证。当更换账号或怀疑凭证泄露时，这是最干净的退出方式。它会删除 ~/.codex/credentials.json ，确保下次 codex login 时重新 OAuth。

5. AGENTS.md 与 MCP 集成：构建专属 AI 开发代理的双引擎

Codex CLI 的真正威力，不在于它能做什么，而在于它能 理解你的项目有多深 。 AGENTS.md 和 MCP（Model Context Protocol）正是实现这一目标的双引擎： AGENTS.md 是 Codex 的“项目认知大脑”，告诉它你的代码规范、架构哲学、禁忌红线；MCP 是它的“工程执行手臂”，赋予它操作数据库、搜索文档、自动化浏览器的能力。两者结合，才能将 Codex