OpenAI Codex 安装部署指南：从零到跑通，2026最新版

⏱️ 阅读时间8分钟 | 难度入门级 | 适用系统macOS / Linux / Windows(WSL2)前言距离上次写 Codex 测评已经有一段时间了这期间 Codex 又经历了好几轮大更新Computer Use 能力、内置浏览器、持久记忆、90 插件生态…更重要的是Codex CLI 最新版本已经到 v0.130.02026-05-08GitHub Star 数突破 83,200。今天带来一篇纯实操教程手把手教你从零安装部署 Codex包含国内用户最关心的网络问题解决方案。一、环境准备1.1 系统要求要求项最低版本推荐版本操作系统macOS 12 / Ubuntu 20.04 / Windows 11 (WSL2)macOS 14 / Ubuntu 22.04Node.js18.022.0npm10.0最新版Git2.232.40内存4GB8GB⚠️ Windows 用户注意Codex CLI 暂时不支持原生 Windows需要通过 WSL2 或使用 Codex App。1.2 环境检查在终端执行以下命令检查当前环境# 检查 Node.js 版本node--version# 输出示例v22.12.0 ✓# 检查 npm 版本npm--version# 输出示例10.9.0 ✓# 检查 Git 版本git--version# 输出示例git version 2.43.0 ✓如果版本不满足要求# Node.js 安装macOS/Linuxcurl-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-sudoapt-getinstall-ynodejs# Windows 用户安装 WSL2 后在 Linux 环境操作wsl--install二、安装步骤2.1 安装 Codex CLICodex CLI 有两种安装方式推荐方式一# 方式一npm 安装推荐npminstall-gopenai/codex# 方式二Homebrew 安装仅 macOS/Linuxbrewinstall--caskcodex 国内用户如果 npm 安装慢可以使用淘宝镜像npminstall-gopenai/codex--registryhttps://registry.npmmirror.com2.2 验证安装# 检查版本codex--version# 输出示例codex 0.130.0 ✓看到版本号就说明安装成功了。2.3 登录 ChatGPT 账号# 启动 Codexcodex终端会提示选择登录方式1. Sign in with ChatGPT (推荐) 2. Use API Key方式一推荐输入 1通过浏览器授权登录你的 ChatGPT 账号。Plus/Pro 用户可享受更高的使用额度。方式二输入你的 OpenAI API Key。 如果你有 ChatGPT Plus/Pro 订阅推荐使用方式一登录可以享受更好的使用体验。三、国内用户配置核心3.1 为什么需要配置Codex CLI 默认调用api.openai.com中国大陆无法直连。需要将 API 端点替换为兼容 OpenAI 协议的国内服务。3.2 配置文件位置Codex 的配置文件位于~/.codex/config.toml3.3 推荐国内中转平台服务商Base URL支持模型特点七牛云 AIhttps://api.qnaigc.com/v1DeepSeek V4、Claude、Kimi、GLM多模型统一 Key硅基流动https://api.siliconflow.cn/v1多家开源模型按量付费有免费额度DeepSeek 官方https://api.deepseek.com/v1DeepSeek 系列官方源稳定性高阿里百炼https://dashscope.aliyuncs.com/compatible-mode/v1Qwen3 系列中文能力强3.4 配置示例编辑~/.codex/config.toml# 国内配置示例使用七牛云 AI openai_base_url https://api.qnaigc.com/v1 # 选择使用的模型 model deepseek-chat # 模型提供商配置 [model_providers.deepseek] name deepseek env_key DEEPSEEK_API_KEY⚠️关键提醒Codex 新版本使用 Responses API很多中转平台只支持 Chat Completions 协议。如果能连上但跑不起来很可能是 API 协议不兼容建议多试几家平台。3.5 环境变量配置在~/.bashrc或~/.zshrc中添加# DeepSeek 示例exportDEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxxxxxx# 阿里百炼示例exportBAILIAN_API_KEYsk-xxxxxxxxxxxxxxxxxxxx生效配置source~/.bashrc# 或 source ~/.zshrc四、实战演示4.1 基础使用进入项目目录启动 Codexcdyour-project codex进入交互式 TUI 界面后可以直接用自然语言描述需求 帮我创建一个用户登录系统包含注册和登录功能Codex 会自动分析项目结构生成代码文件写入磁盘运行测试验证4.2 非交互式执行适合 CI/CD 集成或快速任务# 单条命令执行codexexec修复 src/auth.py 中的登录验证漏洞# 指定模型执行codexexec--modelgpt-5.3-codex优化这段代码的性能4.3 SDK 集成Node.js如果你想在项目中使用 Codex SDKnpminstallopenai/codex-sdk基础示例import{Codex}fromopenai/codex-sdk;constcodexnewCodex();constthreadcodex.startThread();// 让 Codex 诊断测试失败并提出修复方案constturnawaitthread.run(Diagnose the test failure and propose a fix);console.log(turn.finalResponse);console.log(turn.items);// 继续对话constnextTurnawaitthread.run(Implement the fix);带结构的输出示例constschema{type:object,properties:{summary:{type:string},status:{type:string,enum:[ok,action_required]},},required:[summary,status],additionalProperties:false,};constturnawaitthread.run(Summarize repository status,{outputSchema:schema,});五、踩坑指南坑1codex 命令找不到问题表现codex: command not found解决方案# 重新安装npminstall-gopenai/codex# 检查 npm 全局路径npmconfig get prefix# 确保路径在 PATH 中echo$PATHWindows 用户建议直接使用 Codex App避免 CLI 环境配置问题。坑2登录授权后仍然失败问题表现浏览器授权成功但终端提示失败。解决方案检查网络连接清除浏览器缓存后重试换用 API Key 方式登录执行codex logout后重新登录坑3国内模型配置后提示找不到问题表现配置了环境变量但 Codex 仍然提示找不到 API Key。解决方案Windows 用户配置完环境变量后必须完全退出 Codex 并重启不是刷新是完全退出再打开如果还不行试试重启电脑检查config.toml中的env_key名称是否与环境变量名匹配⚠️ Codex 新版本使用 Responses API很多平台还没适配。能跑就用跑不起来就换平台。坑4长会话性能下降问题表现对话时间长了Codex 开始变笨。解决方案分段任务复杂任务拆分成多个小任务每个任务开启新会话使用 AGENTS.md将关键上下文写入项目根目录的AGENTS.md文件会话刷新策略会话 1理解代码库结构 → 写入 AGENTS.md会话 2基于 AGENTS.md 实现功能会话 3独立验证坑5Computer Use 功能不可用问题表现想用 Codex 操作电脑但提示 Computer Use 不可用。解决方案Computer Use 目前只支持 macOS 15。如果你的系统版本低于 macOS 15这个功能将无法使用。六、进阶配置AGENTS.mdCodex 支持通过AGENTS.md文件配置项目级别的行为规范。这是一个非常强大的功能。基本结构# 项目名 ## 工作流 - 每次代码变更后运行 npm test - 使用 Conventional Commits (feat:, fix:, refactor:) - 完成后通过 gh pr create 创建 PR ## 技术栈 - Node.js 18, Express 4.x, PostgreSQL 16 - 测试: Jest React Testing Library ## 代码规范 - 组件文件不超过 300 行超过则拆分 - 禁止使用 any 类型 - 所有公开 API 必须有 JSDoc 注释 ## 必须运行的检查 修改完成后按顺序运行 1. npm run lint - Linter 修复 2. npm test - 运行相关测试 3. npm run typecheck - 类型检查配置原则原则说明保持简短控制在 100 行以内硬上限 300 行精准只写 Codex 可能忽略的信息拆分规则太多时拆分到子目录的 AGENTS.md七、总结本文带你完成了以下内容步骤内容✅ 环境准备Node.js、npm、Git 安装与版本检查✅ 安装 Codex CLInpm/Homebrew 两种方式✅ 国内用户配置七牛云/硅基流动/DeepSeek/阿里百炼✅ 实战演示交互式/非交互式/SDK 三种使用方式✅ 踩坑指南5 个常见问题及解决方案✅ 进阶配置AGENTS.md 项目规范配置Codex CLI 最新数据截至 2026-05 最新版本v0.130.0⭐ GitHub Stars83,200️ 支持平台macOS / Linux / Windows(WSL2) 主要特性Responses API、Computer Use、90 插件如果你在安装过程中遇到任何问题欢迎在评论区留言觉得有用的话点个赞、收个藏你的支持是我持续输出的动力 相关阅读《OpenClaw零失败安装指南前置检查安装验证国内镜像全流程教学》《OpenAI_Codex免费移动端双线出击_20260516》