Codex CLI 上手指南：安装、权限模式与项目配置

这是一份面向终端的 Codex CLI 实操指南，从安装、登录、第一个任务，到沙箱与审批模式、AGENTS.md、config.toml、MCP 接入和会话恢复，都给出了具体命令和配置示例。适合想把 Codex 真正用进日常开发流程的人按步骤照做。

安装与登录

• macOS/Linux 用官方脚本安装，Windows 用 PowerShell 脚本，也可用 npm install -g @openai/codex 或 Homebrew 的 brew install --cask codex；升级可重跑脚本、codex update 或包管理器。
• 进入项目目录运行 codex，首次启动选择登录方式：ChatGPT 账号（消耗套餐额度，也是解锁 Codex cloud 的唯一方式）或 API key（按 token 计费，适合 CI）。
• 命令行也能管理登录：codex login 打开浏览器授权，--device-auth 用于无头机器，login status 查看状态，logout 清除凭证，也可用管道传入 API key。
• 会话内用 /status 或 /usage 查看当前用量与额度。

第一个任务与交互技巧

• 从真实的小任务开始，例如让它解释项目里的鉴权逻辑、为密码重置流程补测试并跑测试套件，观察它读文件、说明计划、改代码、执行命令的完整链路。
• 输入 @ 可搜索并附加文件；行首加 ! 直接执行 shell 命令，如 !git status。
• 运行中按 Enter 追加当前轮指令，按 Tab 把后续指令排队；空输入下连按两次 Esc 可回到上一条消息修改后继续。
• /diff 查看改动（含未跟踪文件）；截图或设计稿可用 codex --image 附加或直接粘贴进提示。

沙箱与审批模式

• Codex 由两层控制：沙箱限制命令实际能做什么，审批策略决定何时停下来问你。默认 Auto 模式（workspace-write + on-request）可在项目内读写执行，越出目录或访问网络前会询问。
• Read only 模式只读不改；never 审批适合不应改动任何东西的 CI 检查；danger-full-access 完全无沙箱，只应在可随时丢弃的机器上使用。
• 会话内 /permissions 在 Auto 与 Read Only 间切换；workspace-write 默认关闭网络，需要时在 config.toml 打开。
• 要写项目外的第二个目录，用 --add-dir 而不是切到完全权限；官方明确警告不要在非隔离 VM 上使用 --yolo。
• 沙箱是操作系统级隔离：macOS 用 Seatbelt，Linux 用 bubblewrap 加 seccomp，Windows 有原生沙箱，WSL2 内走 Linux 沙箱。

AGENTS.md 与 config.toml

• AGENTS.md 存放每次都要重复的规则：构建与测试命令、代码风格、禁止改动的目录。会话内运行 /init 可生成初版，内容要短而具体。
• 查找顺序为全局 ~/.codex/AGENTS.md，再从 git 根目录逐层向下，每层最多取一个文件（优先 AGENTS.override.md）；子目录规则后加载、优先级更高，合并总量默认上限 32 KiB。
• 用户配置在 ~/.codex/config.toml，项目配置在 .codex/config.toml 且需先把项目标记为可信。常用项包括 model、model_reasoning_effort、web_search（cached/live/disabled）、sandbox_mode、approval_policy 和 network_access。
• 配置优先级从高到低：命令行参数与 -c key=value、项目配置、--profile 指定的配置、用户配置、系统配置；不确定时用 /debug-config 查看生效层级。

MCP 接入与会话管理

• 用 codex mcp add <name> -- <启动命令> 添加 MCP 服务器，-- 之后是启动命令；环境变量用 --env VAR=value 传入。
• 远程服务器用 codex mcp add <name> --url OAuth 时用 codex mcp login <name>；codex mcp list 查看已配置项。
• 同样的服务器也可手写进 config.toml 的 [mcp_servers.<name>] 段，填写 command 与 args。
• codex resume 可接着之前的会话继续，适合长任务分多次推进。

今天就能做

• 在项目里跑一次 /init 生成 AGENTS.md，补上测试命令和禁止改动的目录。
• 把默认 Auto 模式当作起点，需要写项目外目录时用 --add-dir，不要直接开完全权限。
• 用 codex mcp add 接入一个常用工具（如文档检索），验证 MCP 流程后再扩展。