1) 安装与版本校验

安装（任选其一）

A. npm（Windows/macOS/Linux 通用）
npm install -g @openai/codex
codex

B. Homebrew（macOS）
brew install codex
codex

版本校验

• 方式 1： 直接运行 codex，启动欢迎页/日志会显示版本；
• 方式 2： 打开 GitHub Releases 对照最新版本号（截至 2025-09-24 为 0.41.0）

2) 登录与首启向导

首次运行 codex 后，按提示选择 “Sign in with ChatGPT”，使用你的 ChatGPT 订阅（Plus/Pro/Team/Edu/Enterprise）直接授权，无需另外配置 API Key。官方也支持用 API Key，但需要额外步骤与迁移指引。

小贴士：

• IDE 侧（VS Code/Cursor/Windsurf）也有扩展，可与 CLI 同账号共享状态。GitHub
• 近期更新还加强了在 GitHub/IDE/终端/Web 多端协同与 @codex 评审能力（如在 PR 中自动审查/建议修复）

3) 快速上手：3 分钟跑通一个真实仓库

假设你已 cd 到项目根目录（有 Git 管理更佳）。
Step 1：打开 Codex
codex

Step 2：告诉 Codex 你要做什么（自然语言即可）
“实现暗黑模式：识别当前 UI 主题变量，新增 dark tokens，提供切换开关，并覆盖按钮/输入框样式；完善单元测试。”

Step 3：Codex 的标准动作（示意）
读取/理解仓库 → 生成改动计划 → 申请“编辑文件/运行命令/安装依赖”等权限 → 执行并给出结果 → 如需复查再迭代

这些交互在 CLI 的 Sandbox & Approvals 与“命令/编辑请求→用户批准→执行→输出”的闭环中完成。

Step 4：验证与提交
让 Codex 跑测试 / 启动开发服务器并观察日志
让它新建分支与提交，并准备 PR 描述（也可去 IDE/GitHub 用 @codex 做代码审查）

4) 常用工作流范式

范式 A： 从需求到改动

1. 说明目标与约束（语言/框架/目录/规范）。
2. 批准它的编辑/命令执行请求（可逐条或批量）。
3. 审阅差异（Codex 会展示 Patch/变更解释），不满意就“继续修改”。

范式 B：调试与诊断

• “请定位最近 3 次提交之间导致性能退化的改动，并写出复现步骤与修复方案（保留日志）。”
• 让它跑 npm test / pytest / go test，出具失败原因与修补 PR。

范式 C：PR 评审（GitHub）

• 在 PR 里 @codex 要求自动审查与修复建议，或让 Codex CLI/IDE 端发起本地审查

5) MCP 接入与安全批准流（图文重点）

什么是 MCP？
MCP = Model Context Protocol，是一种标准化方式让 AI 客户端（如 Codex）安全、受控地访问本地或外部工具/数据（文件系统、Web 抓取、CI、安服扫描、工单系统等）。

Codex CLI 如何启用 MCP？
Codex 通过 ~/.codex/config.toml 配置 本地 STDIO 类型的 MCP 服务器（常见：filesystem、GitHub、Snyk、Web fetch…）。

示意配置（三件套：文件/GitHub/Snyk）

# 文件系统 MCP
[mcp_servers.filesystem]
type = "stdio"
command = "mcp-filesystem"

# GitHub MCP（需要 OAuth 授权）
[mcp_servers.github]
type = "stdio"
command = "mcp-github"

# Snyk 安全扫描 MCP（需先安装并登录 snyk CLI）
[mcp_servers.snyk]
type = "stdio"
command = "mcp-snyk"

Snyk 给出了面向 Codex 的逐步接入教程；Bright Data 也提供了 Web 抓取 MCP 的 Codex 配置示例（含创建 ~/.codex/config.toml 的步骤）

批准流（ASCII 流程图）
┌──────────────┐    申请(读/写/命令/网络)   ┌─────────────┐
│   Codex CLI  │ ────────────────────────▶ │  批准面板    │
└─────┬────────┘                           └─────┬───────┘
      │ 结果/日志/补丁                          │ 允许/拒绝/仅一次
      ▼                                         ▼
┌──────────────┐                          ┌─────────────┐
│   仓库变更    │◀──────────────────────── │ MCP 服务端  │
└──────────────┘    STDIO 通道（受控）      └─────────────┘

注意：社区反馈 Codex 当前仅支持 STDIO MCP（远端 SSE/HTTP 需通过代理或暂不支持），这点在第三方讨论中多次提到。

6) 进阶能力

非交互/CI 模式
Codex 支持在 CI 环境中以“非交互”方式运行（例如为 PR 自动生成变更说明、补丁、或运行分析）。相关用法见 README 的 Advanced → Non-interactive / CI mode。

Verbose/Tracing 调试
当你需要定位失败原因或上报 Issues，可开启详细日志（Advanced → Tracing / verbose logging）。

Zero Data Retention（ZDR）
企业/合规场景可启用“零数据保留”。参见 Docs & FAQ → Zero data retention (ZDR)

7) Windows 11 专项排错

(1) 登录与回环浏览器问题

• 优先用 “Sign in with ChatGPT”；若公司网络代理/证书拦截，建议临时切换到直连环境或在“无头机”按官方 Login on a "Headless" machine 指南登录。

(2) 配置文件位置与格式

• 标准路径是 C:\Users\<你>\.codex\config.toml。个别版本/环境下有人误以为是 config.json，若你遇到“找不到 toml 被识别”的情况，可参考相应 issue 与 README 的 Configuration 说明核对。

(3) 长路径与文件权限

• Windows 压缩/解压或补丁写入时若碰到长路径失败，可在组策略或注册表启用 Win32 Long Paths；给项目目录足够权限（尤其是 node_modules / 构建产物）。
• 若 Git/SSH 受公司防火墙限制，走 ssh.github.com:443（在 ~/.ssh/config 里指定 Host/Port）通常更稳。

(4) 端口与杀软

• 本地开发端口被占用或被安全软件拦截会导致命令执行失败；建议先 netstat -ano/任务管理器排查并放行开发端口与 codex 可执行。