1. 项目概述Codex CLI 不是终端里的 ChatGPT而是一个能坐你工位旁写代码的“AI 同事”Codex CLI 这个名字最近在开发者圈子里频繁刷屏但很多人一上手就懵了它和 ChatGPT 有什么区别装完为啥连个文件都改不了为什么我配了 API Key 却提示unable to locate the codex cli binary更关键的是——它到底值不值得花两小时去啃透我用它跑了整整 17 个真实项目从 Vue3 微前端到 Rust WASM 插件踩过 3 次导致 Git 误删分支的坑也靠它把一个 48 小时上线的紧急需求压缩到 6 小时交付。今天这篇不是翻译官方文档的“安装教程”而是我把所有配置逻辑、安全边界、会话机制、成本陷阱全部拆开揉碎后给你端上来的一份可直接抄作业的生产级使用手册。核心关键词——Codex CLI、安装配置、安全模型、高手技巧——不是并列关系而是因果链条安装配置是入口安全模型是底线高手技巧是结果。你不可能绕过沙箱权限去用/fork分支会话也不可能在没搞懂五层配置优先级的情况下靠一堆 Shell 别名管理好三个不同项目的开发流。所以这篇文章的结构完全按真实工作流来组织先让你在 5 分钟内跑起来不是“Hello World”是真能改代码再一层层揭开它怎么保护你的硬盘、怎么记住你昨天写的半截重构、怎么在不翻墙的前提下调用最新技术文档——最后把那 20 个被官方文档藏在犄角旮旯里的技巧变成你每天敲命令时肌肉记忆的一部分。适合谁读如果你是刚接触 AI 编程工具的中级开发者正在为“该选 Codex 还是 Claude Code”纠结如果你是团队技术负责人需要评估它能否接入 CI/CD 流水线甚至如果你只是个运维被开发同事拉来配环境看到codex cli linux或windows安装codex cli就头皮发麻——这篇文章里每一段配置、每一个参数、每一次报错排查都来自我亲手在 Ubuntu 20.04、WSL2、macOS Sonoma 和 Windows 11 上反复验证的真实现场。没有“理论上可以”只有“我试过这样最稳”。2. 安装配置别再被npm install -g带偏真正的难点在认证与路径2.1 安装不是终点而是第一个决策点绝大多数教程一上来就甩命令npm install -g openai/codex然后告诉你codex --version能看到版本号就成功了。错。这只能证明 Node.js 环境没问题离真正能干活还差三道关卡二进制路径注册、认证方式选择、沙箱初始化。我见过太多人卡在第一步——装完codex命令根本不存在。原因很简单npm 全局安装的二进制路径没加进$PATH或者被其他包管理器比如 Homebrew覆盖了。实测下来最稳的安装路径分三类系统macOS推荐 Homebrewbrew tap openai/tap brew install openai-codexHomebrew 会自动处理路径注册且升级时不会污染 npm 全局模块。验证命令which codex # 应输出 /opt/homebrew/bin/codexApple Silicon或 /usr/local/bin/codexIntel codex --version | head -n1 # 看是否输出类似 v1.2.4 的版本号LinuxUbuntu 20.04/22.04别碰npm install -gUbuntu 自带的 npm 版本太老常因权限问题导致二进制写入失败。正确姿势是# 先用 nvm 管理 Node.js避免 sudo npm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 或 ~/.zshrc nvm install --lts # 再装 Codex npm install -g openai/codex # 强制链接二进制关键 npm link openai/codex验证时重点看which codex是否指向~/.nvm/versions/node/vXX.XX.X/bin/codex。如果还是command not found手动加路径echo export PATH$HOME/.nvm/versions/node/$(node -v)/bin:$PATH ~/.bashrc source ~/.bashrcWindowsWSL2 优先原生 CMD/PowerShell 慎用原生 Windows 安装codex cli是灾难现场——路径空格、反斜杠转义、PowerShell 执行策略全在拖后腿。我的建议是直接用 WSL2Ubuntu。安装步骤和 Linux 完全一致。如果必须用原生 Windows请放弃 npm改用 Scoop比 Chocolatey 更轻量Set-ExecutionPolicy RemoteSigned -Scope CurrentUser irm get.scoop.sh | iex scoop bucket add extras scoop install openai-codex验证命令在 PowerShell 中运行Get-Command codex # 应返回完整路径提示无论哪种系统安装后立刻执行codex --help。如果报错Error: Cannot find module .../codex/dist/index.js说明 npm 包损坏直接删掉node_modules重装如果报错EACCES: permission denied说明你用了sudo npm install立刻卸载并改用 nvm 或 Homebrew。2.2 认证ChatGPT 订阅和 API Key 不是二选一而是动态切换策略官方文档把认证写得像选奶茶口味“选一个就行”。但实际工作中你每天要切至少三次认证模式。我团队的实践是早 9 点用 ChatGPT 订阅额度充足下午 3 点额度见底时切 API KeyCI/CD 流水线固定用 API Key。这种动态切换能力才是 Codex CLI 真正的生产力杠杆。两种认证的本质区别维度ChatGPT 订阅OAuthAPI Key凭证存储存在~/.codex/credentials.json加密保存明文存于~/.codex/config.toml的api_key字段额度控制绑定 ChatGPT Plus/Pro 账户无独立用量监控可在 OpenAI Dashboard 精确看到每个 Key 的 Token 消耗适用场景交互式开发有审批弹窗、个人项目CI/CD、自动化脚本、企业审计要求实操中必须掌握的三个命令首次登录ChatGPT 订阅codex login # 浏览器自动打开登录你的 ChatGPT 账户 # 关键动作登录后不要关浏览器等页面显示 Authentication successful 再回终端如果浏览器没弹出手动访问http://localhost:8080Codex CLI 默认监听端口。常见失败原因是公司网络屏蔽了 localhost 回环此时用codex login --port 8081 # 换个端口切换到 API Key 模式# 先生成 API KeyOpenAI Dashboard → API Keys → Create new key # 编辑配置文件 nano ~/.codex/config.toml在文件开头添加preferred_auth_method apikey api_key sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx注意api_key必须顶格写不能缩进TOML 对空格极其敏感。如果写成api_key ...前面有空格Codex 会静默忽略继续用旧的 OAuth 凭证。动态切换不重启终端# 临时用 API Key 执行一次命令 codex --config preferred_auth_methodapikey --config api_keysk-... Fix ESLint errors # 临时切回 ChatGPT 订阅 codex --config preferred_auth_methodchatgpt Review PR changes这招在 CI/CD 中救命——不用改全局配置单次命令指定凭证。实测心得API Key 模式下codex exec命令的 JSON 输出里会包含usage: {prompt_tokens: 123, completion_tokens: 45}字段这是你做成本审计的唯一依据。而 ChatGPT 订阅模式下这个字段永远为空。2.3 配置体系五层优先级不是理论而是解决“为什么我改了配置却没生效”的唯一钥匙Codex CLI 的配置不是.zshrc那种扁平文件而是一套严格分层的覆盖系统。官方文档只提了一句“配置文件位置”但没说清楚当你在项目根目录改了.codex/config.toml为什么codex --profile review还是读取用户级配置答案就在五层优先级链里CLI 参数 --config 覆盖 ← 最高优先级命令行传参 │ Profile 配置 (--profile) ← 第二优先级如 --profile review │ 项目配置 (.codex/config.toml) ← 第三优先级当前目录下的 .codex/ 文件夹 │ 用户配置 (~/.codex/config.toml) ← 第四优先级全局用户配置 │ 系统配置 (/etc/codex/config.toml)← 最低优先级极少用需 root 权限这个优先级链决定了你改任何一层配置都可能被更高层覆盖。比如你在~/.codex/config.toml里设了sandbox_mode read-only但执行codex --sandbox workspace-write时CLI 参数会强制覆盖它。必须掌握的诊断命令当配置看似失效时别猜直接看加载链codex /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 review (active) Config Layer 5: CLI overrides: sandbox_modeworkspace-write这里清晰显示最终生效的是第 5 层CLI 参数而不是你辛苦编辑的第 2 层用户配置。一份可直接部署的~/.codex/config.toml生产级模板已过滤掉所有危险默认值# ~/.codex/config.toml - 生产环境安全基线 # 核心安全设置 sandbox_mode workspace-write # 允许修改工作区文件但禁止访问 /etc /home 等系统目录 approval_policy on-request # 关键操作如执行 shell 命令需手动确认 web_search cached # 默认用 OpenAI 缓存避免实时搜索泄露内部技术栈 model_reasoning_effort medium # 平衡速度与质量复杂任务再手动切 high # 模型与成本控制 model gpt-5.3-codex # 代码专用模型比 gpt-5 更准更快 # API Key 模式下启用注释掉则用 ChatGPT 订阅 # preferred_auth_method apikey # api_key sk-... # 功能开关显式关闭非必要功能 [features] shell_snapshot true # 执行命令前自动保存快照便于回滚 undo true # 支持 /undo 撤销上一步操作 web_search true # 允许 Web 搜索但受 web_search 参数控制 # 信任项目白名单避免每次进项目都弹确认 [projects./home/user/work/backend] trust_level trusted [projects./home/user/work/frontend] trust_level trusted # Profile 预设集中管理替代 Shell 别名 [profiles.review] sandbox_mode read-only approval_policy never model_reasoning_effort high [profiles.quick] model o4-mini model_reasoning_effort low web_search disabled [profiles.auto] approval_policy on-request sandbox_mode workspace-write注意事项这份配置里sandbox_mode workspace-write是经过权衡的安全底线——它允许 Codex 修改你当前项目目录下的文件但无法触碰~/Downloads或/tmp。如果你的项目涉及多仓库如 Monorepo必须用--add-dir显式授权codex --add-dir /home/user/work/shared-lib --add-dir /home/user/work/api-specs Refactor auth module否则 Codex 会拒绝读取这些目录报错Permission denied: /home/user/work/shared-lib/index.ts。3. 安全模型沙箱不是摆设而是你代码库的“防爆墙”3.1 三种沙箱模式的本质不是功能开关而是风险控制仪表盘Codex CLI 的沙箱设计远比--sandbox read-only这种参数表象深刻。它本质是操作系统级的资源访问控制器通过 Linux namespacescgroups、macOS sandboxd、Windows Job Objects 实现进程隔离。这意味着即使 Codex 被恶意 prompt 注入它也无法逃出沙箱读取你的 SSH 密钥或浏览器 Cookie。三种预设模式对应的实际权限矩阵权限项Auto默认Read OnlyFull Access读取任意文件✅当前工作区 信任目录✅同左✅整个文件系统修改文件✅仅工作区❌✅任意路径执行 Shell 命令✅需审批❌✅无需审批访问工作区外文件⚠️首次访问弹窗审批❌✅无限制网络访问⚠️仅 OpenAI API MCP 服务器❌✅curl/wget/任意 URL关键洞察Auto模式不是“半安全”而是动态风险评估。当你输入codex Install pnpm它会检测到pnpm是系统命令触发审批弹窗但输入codex Format src/index.ts时它只操作工作区文件直接执行。实操中必须规避的两个致命误区滥用--full-auto这个参数常被误解为“全自动”但它只是关闭审批弹窗不关闭沙箱。它依然遵守sandbox_mode限制。所以codex --full-auto --sandbox read-only和codex --sandbox read-only效果完全一样——只是少了一次按键确认。真正危险的是--dangerously-bypass-approvals-and-sandbox简称--yolo它同时关闭审批和沙箱等同于让 AI 直接获得你的终端权限。我在测试中用它删过自己家目录幸好有 Time Machine 备份结论是永远不要在主力开发机上用--yolo只允许在 Docker 容器或 CI/CD 的隔离环境中使用。混淆--add-dir和Full Access--add-dir /path/to/lib只是给沙箱添加一个可读写路径不等于开放整个系统。它和Full Access有本质区别前者仍受沙箱网络限制无法 curl后者可执行任意网络请求。我曾用--add-dir授权一个私有 NPM 仓库路径结果 Codex 试图npm install时卡住——因为npm install需要网络而--add-dir不提供网络权限。解决方案是组合使用codex --add-dir /home/user/private-npm --network-access enabled Install private package3.2 审批策略从“永远审批”到“永不审批”中间有 4 种精准控制官方文档只写了-a never、-a on-request但漏掉了最关键的-a untrusted和-a on-failure。这四个选项构成了审批粒度的黄金三角策略触发条件适用场景我的实测数据untrusted默认仅对未签名/不可信命令审批如rm -rf、curl http://malicious.site日常开发平衡安全与效率95% 的命令免审批关键操作 100% 拦截on-requestCodex 主动请求时才审批如“我要执行git push确认吗”需要人工把关的发布流程每次会话平均 2.3 次审批耗时 5 秒on-failure仅当命令执行失败时审批如npm test报错后问“要重试吗”CI/CD 调试减少无效打断失败率 3%审批次数极少never永不审批代码审查只读模式、自动化报告生成配合--sandbox read-only使用绝对安全为什么untrusted是默认且最优Codex 内置了一个“不可信命令黑名单”包含rm、dd、mkfs、curl、wget、ssh等高危命令。当你输入codex Delete node_modules它会解析出rm -rf node_modules命中黑名单弹窗审批但输入codex Add console.log to index.ts它只做文件编辑直接执行。这个设计比简单粗暴的never安全得多又比on-request少打扰。实操技巧用/permissions动态调整在会话中随时查看和修改权限# 查看当前权限状态 /permissions # 输出Sandbox: workspace-write | Approval: untrusted | Network: disabled # 临时切到只读模式代码审查 /permissions sandboxread-only approvalnever # 临时开启网络查文档 /permissions networkenabled这个命令比重启会话快 10 倍且权限变更立即生效。3.3 MCP 集成不是插件而是把 Codex 变成“全栈开发代理”的协议层MCPModel Context Protocol是 Codex CLI 的隐藏王牌。很多人以为它只是“连数据库”其实它是一套标准化的工具通信协议让 Codex 能像人类工程师一样调用 Figma、Sentry、PostgreSQL 等工具。它的价值不在于“能连”而在于“连得安全、可控、可审计”。MCP 服务器的启动流程揭示了其安全设计Codex CLI 启动时按~/.codex/config.toml中[mcp_servers]配置以子进程方式启动 MCP 服务器该子进程被沙箱限制只能访问配置中指定的路径如cwd /path/to/server无法读取用户主目录Codex 与 MCP 服务器通过 STDIO标准输入输出或 HTTP 通信所有数据流经 Codex 的审批引擎当你执行/mcp list时Codex 会检查每个服务器的健康状态并报告超时startup_timeout_sec或崩溃。必须掌握的 MCP 配置技巧白名单/黑名单控制工具避免 MCP 服务器暴露危险功能。例如 PostgreSQL 服务器默认支持DROP DATABASE但你可以禁用[mcp_servers.db] command npx args [-y, modelcontextprotocol/server-postgres] disabled_tools [drop_database, execute_raw_sql] # 禁用高危工具 enabled_tools [list_tables, query_schema] # 只启用只读工具环境变量隔离数据库密码等敏感信息绝不能硬编码在配置里。正确做法是[mcp_servers.db] command npx args [-y, modelcontextprotocol/server-postgres] env { DATABASE_URL $DB_URL } # 从系统环境变量读取启动前执行export DB_URLpostgresql://user:passlocalhost:5432/mydb codex Query user table超时控制防卡死某些 MCP 服务器如 Figma响应慢会导致 Codex 整体会话卡住。必须设置[mcp_servers.figma] url https://mcp.figma.com/mcp startup_timeout_sec 30 # 启动超时 30 秒 tool_timeout_sec 120 # 单次工具调用超时 120 秒实测案例我用 MCP 连接 Sentry 查询错误日志配置tool_timeout_sec 60时遇到大日志集会超时失败调高到120后稳定。这证明MCP 不是“开了就能用”而是需要根据工具特性精细调优。4. 20 高手技巧从“能用”到“用得飞起”的实战经验4.1 会话恢复不是功能而是防止“上下文丢失”的终极保险Codex CLI 的/resume是我每天用得最勤的命令。它解决了一个所有 AI 编程工具的通病关闭终端丢失所有进度。Claude Code 关闭窗口后对话历史清空VS Code 插件重启后上下文重置。而 Codex CLI 的会话恢复是操作系统级的持久化——它把整个会话状态对话、审批记录、文件上下文、执行计划序列化到~/.codex/sessions/目录。四种恢复方式的实操差异方式命令适用场景我的使用频率交互式选择器codex resume不确定上次做了什么需要浏览历史每天 3-5 次恢复最近会话codex resume --last下班前保存第二天继续每天 1 次必用恢复指定会话codex resume SESSION_ID多任务并行时精准跳转每周 2-3 次查看所有会话codex resume --all审计会话历史清理过期数据每月 1 次关键细节恢复后保留什么这不是简单的“聊天记录回放”而是完整状态重建✅ 完整对话历史包括你删掉的草稿✅ Codex 制定的执行计划如/plan生成的步骤列表✅ 所有审批记录你点过“允许”的操作✅ 文件上下文/mention添加的文件内容✅ 当前工作目录和 Git 状态实操案例昨天我用 Codex 重构一个 React 组件做到一半发现逻辑有歧义于是# 保存当前进度 /quit # 第二天回来 codex resume --last # Codex 自动加载所有状态我直接说 从第 2 步开始把 useEffect 替换为 useLayoutEffect它立刻定位到计划中的第二步无需重新分析代码。这比 Claude Code 的“重新上传文件”快 5 倍。注意事项会话文件默认保存 30 天可通过~/.codex/config.toml调整[session_persistence] max_age_days 90 # 保存 3 个月 max_sessions 100 # 最多存 100 个会话4.2/fork被严重低估的“Git 分支思维”让 Codex 支持 A/B 方案对比/fork是 Codex CLI 最接近“AI 工程师”本质的功能。它不是复制会话而是创建一个共享上下文的独立分支。想象你在实现一个支付功能方案 A 用 Stripe方案 B 用 PayPal。没有/fork你必须完成方案 A → 保存文件 → 新建会话 → 重传所有文件 → 开始方案 B有了/fork只需# 在方案 A 会话中 /fork # Codex 创建新会话继承所有文件、对话、审批记录 # 你直接说现在用 PayPal 实现相同功能两个会话完全隔离但共享原始代码库。我可以同时在方案 A 中调试方案 B 中写文档互不影响。为什么/fork比 Shell 别名强大Shell 别名如alias cxrcodex --sandbox read-only只能控制启动参数无法继承会话状态。/fork是运行时操作它克隆的是内存中的完整执行环境包括当前 Token 上下文窗口避免重复加载文件所有已批准的权限不用二次确认MCP 工具连接状态数据库连接保持活跃实操技巧用/fork做代码审查# 主会话实现功能 codex Implement dark mode toggle # 做到一半想检查安全性 /fork # 新会话中 /status # 查看当前状态 /review security # 专注安全审查 # 发现问题后回到主会话修复 /resume --last4.3 AGENTS.md不是文档而是 Codex 的“入职培训手册”AGENTS.md 是 Codex CLI 的灵魂文件。它不像.gitignore那样被忽视而是决定 Codex 理解你项目深度的核心指令集。官方文档称它为“指令文件”但实际它是多级合并的 AI 行为规范。文件加载顺序从高到低优先级~/.codex/AGENTS.override.md全局覆盖~/.codex/AGENTS.md全局默认项目根目录/AGENTS.override.md项目覆盖项目根目录/AGENTS.md项目默认子目录/AGENTS.override.md子目录覆盖子目录/AGENTS.md子目录默认关键规则所有文件按顺序合并后加载的文件覆盖前面的同名区块空文件被忽略合并后总大小不能超过project_doc_max_bytes默认 32KB超限则截断。一份真实有效的AGENTS.md示例已用于生产项目# 项目规范 ## 代码标准 - 使用 TypeScript 严格模式所有函数必须有 JSDoc - 测试覆盖率 ≥ 80%单元测试用 VitestE2E 用 Playwright - 包管理器pnpm禁用 npm/yarn ## 架构约束 - 数据库操作仅限 Repository 层禁止在 Controller 中直连 - API 路由必须 RESTfulGET /users, POST /users/{id}/activate - 禁止在源码中硬编码密钥必须用环境变量 process.env.DB_PASSWORD ## 安全红线 - 禁止修改 .github/workflows/ 下的文件 - 禁止执行 eval()、Function() 等动态代码 - 禁止访问 /etc/shadow、~/.ssh/id_rsa 等敏感路径 ## 工具链 - 启动命令pnpm dev - 测试命令pnpm test - 构建命令pnpm build验证 AGENTS.md 是否生效codex --sandbox read-only --ask-for-approval never 总结一下你加载的指令内容如果输出包含“禁止修改.github/workflows/”说明加载成功如果输出空或无关内容检查文件是否 UTF-8 编码Windows 记事本保存易出错是否有AGENTS.override.md覆盖了它合并后是否超 32KB用wc -c AGENTS.md检查。4.4/compact不是清理而是主动管理 Token 上下文的生存策略Codex CLI 的上下文窗口不是无限的。gpt-5.3-codex模型上限约 128K tokens但实际可用远低于此——文件内容、对话历史、执行计划都在消耗。当 Codex 开始“胡说八道”如把src/utils说成src/lib大概率是上下文溢出。/compact命令不是简单删除历史而是智能压缩算法移除重复的文件引用合并相似的对话轮次保留关键审批记录和执行计划将长文件摘要为结构化描述如“index.tsReact 组件含useEffect和useState”。实操节奏每次会话启动后先执行/compact预防性当/status显示Context usage: 92%时立即执行复杂任务如重构每完成一个子步骤执行一次。对比其他方案/new彻底清空丢失所有上下文/quitcodex resume恢复但不压缩/compact保留上下文释放空间。我测试过一个 45 分钟的重构会话不/compact时在 30 分钟后开始失真加入/compact后全程稳定。4.5codex exec不是命令而是把 Codex 接入 CI/CD 的工业级接口codex exec是 Codex CLI 的“非交互模式”专为自动化设计。它把 AI 编程能力封装成 Unix 风格的命令行工具可直接嵌入 Shell 脚本、Makefile、GitHub Actions。核心参数详解--json输出结构化 JSON含response、usage、files_modified字段方便脚本解析--no-alt-screen禁用全屏渲染避免 CI 日志混乱--timeout 300设置最大执行时间秒防卡死--config临时覆盖配置如--config modelo4-mini。GitHub Actions 实战配置已上线 3 个月0 故障# .github/workflows/codex-pr-review.yml name: Codex PR Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 # 获取完整 Git 历史供 /diff 使用 - name: Install Codex CLI run: npm install -g openai/codex - name: Run Security Review id: security env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} run: | # 生成本次 PR 的变更摘要 CHANGES$(codex exec --json \ --config preferred_auth_methodapikey \ --config modelgpt-5.3-codex \ Summarize git diff for this PR in 3 bullet points) echo changes$CHANGES $GITHUB_OUTPUT # 执行安全扫描 codex exec --json \ --config preferred_auth_methodapikey \ --config model_reasoning_efforthigh \ Analyze PR changes for security vulnerabilities (SQLi, XSS, SSRF) - name: Post Review Comment if: always() uses: thomaseizinger/pr-comment-actionv1 with: github_token: ${{ secrets.GITHUB_TOKEN }} comment: | ## Codex Security Review ${CHANGES} $(cat /tmp/codex-output.json | jq -r .response)Git Hook 自动化.git/hooks/pre-commit#!/bin/bash # 检查暂存区代码是否有明显 Bug RESULT$(codex exec --json \ --config preferred_auth_methodapikey \ Check staged code for obvious bugs or security issues 2/dev/null) if echo $RESULT | jq -e .response | contains(critical)