Codex 这个工具我盯了挺久最近版本更新频繁网上教程要么过于简略、要么已经过时。我花了一整天时间从零开始装了一遍顺手把踩过的坑全记下来了。这篇教程不整虚的直接覆盖下载、安装、配置、接入第三方模型、常见报错排查全程照着做就行。不管你是专业开发者还是刚接触 AI 编程工具的新手这篇文章都适用。1. Codex 到底是干什么的为什么值得装1.1 一分钟搞懂 Codex 是什么简单说Codex 是 OpenAI 推出的一款命令行 AI 编程助手你在终端里运行它它就能理解你的自然语言指令帮你读代码、改代码、跑测试、提交 Git一路从“写个脚本”干到“重构整个模块”。它和 ChatGPT 网页版最大的区别是Codex 直接跑在你本地环境里能真正访问你的文件系统、执行命令、操作 Git 仓库而不只是“建议一段代码然后你自己粘”。我实测下来的体验是它更像一个坐在你旁边的资深结对编程搭档你说一句“帮我看看这个函数哪里性能有问题”它会自己打开文件、分析、给你改完还会告诉你改了什么、为什么改。1.2 它能解决什么实际问题接手一个陌生项目时让它帮你解释代码结构、梳理模块关系比一行行读源码快得多。写业务代码时告诉它“用 TypeScript 写一个带重试机制的请求封装”它直接生成完整文件。调试报错时把报错信息丢给它结合上下文代码定位根因。做代码重构时它能跨文件追踪依赖关系比全局替换靠谱。配合 Git 操作让它帮你写规范的 commit message整理 diff。说白了它能帮你省掉大量机械性编码和排查时间让你把精力放在设计和技术决策上。1.3 哪些人最适合用最常见的使用群体分三类一是前端/后端工程师日常需要快速写胶水代码、处理配置文件的二是做数据分析和脚本自动化的人经常要写一次性 Python 脚本三是刚入门编程的新手遇到报错不知道怎么办Codex 能在上下文里直接帮你解读运行结果比来回问搜索引擎效率高。不过我提醒一句它本质上还是工具不是“万能程序员”。你至少要能看懂它改了什么、写得对不对才能把它的价值最大化。2. 安装前的准备工作先把环境收拾干净2.1 系统要求与硬件建议Codex 是跨平台工具Windows、macOS、Linux 都能跑。但我强烈建议你在开始前确认三件事操作系统版本不要太老。Windows 10/11、macOS 12、主流 Linux 发行版基本都行。终端环境建议用 Windows TerminalWindows、iTerm2 或系统自带 TerminalmacOS、GNOME Terminal 或 KonsoleLinux。磁盘空间不用操心Codex 本体很小但它们运行时要拉取模型上下文会缓存一些数据留出 2-3GB 空间比较稳妥。内存方面8GB 机器也能用但如果你本机跑了 Docker、虚拟机等重负载程序建议至少 16GB不然并行任务多了会卡。2.2 Node.js 安装与环境变量配置2026 最新推荐Codex 目前最主流的安装方式是通过 npm 全局安装所以 Node.js 是绕不开的前置依赖。2026 年这个时间点Node.js 20 LTS 已经成为绝对主力22 LTS 也已经进入维护期我推荐直接上 20 LTS 或更新的 LTS 版本。Windows 用户最简单的方式是去 Node.js 官网下载 LTS 版本的 MSI 安装包双击安装一路 Next。安装完成后打开新终端验证node -v npm -v如果显示版本号说明 Node.js 已经进了 PATH。如果提示“node 不是内部或外部命令”说明安装时没有勾选“Add to PATH”或者安装后没有重启终端。这时候手动把 Node.js 的安装目录默认是C:\Program Files\nodejs\加到系统环境变量 Path 里就能解决。macOS 用户如果装了 Homebrew一条命令搞定brew install node20装完后记得看输出里的 PATH 提示Homebrew 有时候会把新版本放在/opt/homebrew/opt/node20/bin需要手动 link 或者加到.zshrc里。Linux 用户建议用 NodeSource 仓库装不要用发行版自带的旧版本。以 Ubuntu 为例curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs装完同样用node -v验证。npm 的全局安装目录权限问题我之前也被坑过Linux/macOS 下如果npm install -g报 EACCES 错误不要直接sudo npm install -g因为 sudo 安装的全局包会导致后面 Codex 的缓存目录归属混乱。正确做法是配置 npm 的全局目录到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH 里。Windows 下不会有这个问题用户级全局安装是默认的。2.3 推荐安装 GitCodex 经常要帮你操作 Git 仓库、看 diff、提交代码所以本机必须装 Git。Windows 直接下载 Git for Windows安装时如果不太熟悉选项默认即可唯一建议在“Choosing the default editor”那一步选 Notepad 或 Vim避免后续终端编辑器交互卡住。macOS 自带 Git但版本可能旧用brew install git更新即可。装完验证git --version3. 下载与安装 Codex 的完整流程3.1 首选方案npm 全局安装确认 Node.js 环境没问题后打开终端执行npm install -g codex等待安装完成。全局安装后 Codex 会暴露codex命令到 PATH 中。验证是否装好codex --version如果运气好你会看到类似codex 0.x.x的版本号。如果提示codex: command not found最常见的原因是 npm 全局 bin 目录没有加入 PATH。你可以执行npm config get prefix拿到 npm 全局根目录后Windows 下通常是C:\Users\你的用户名\AppData\Roaming\npmmacOS/Linux 下是/usr/local或你之前设置的~/.npm-global。把这个路径下的bin目录Windows 就是那个路径本身加进系统 PATH重启终端即可。在安装过程中如果遇到 npm 下载慢或者超时可以临时更换 npm 镜像源。这里注意我推荐的是公共镜像源不改全局配置单独为这次安装指定npm install -g codex --registryhttps://registry.npmmirror.com装完后记得把 registry 换回来避免影响其他包的版本验证npm config get registry如果是默认官方源就用回官方源否则执行npm config set registryhttps://registry.npmjs.org/。3.2 备选方案从 GitHub Releases 下载二进制包如果你不想依赖 Node.js或者 npm 反复安装失败Codex 也提供了预编译的二进制包。去 Codex 的 GitHub 仓库 Releases 页面找到对应你系统的版本Windows 选codex-x.x.x.exe或 zip 包。macOS 选codex-x.x.x-macos.zip。Linux 选codex-x.x.x-linux.zip。下载后把可执行文件放到一个你习惯的目录比如 Windows 下的C:\codex\macOS/Linux 下的/usr/local/bin/然后确保这个目录在 PATH 中。Windows 用户如果下载的是 exe 文件双击不会被运行因为它是 CLI 工具必须在终端里调用。建议把它改名成codex.exe放好然后在终端执行codex --version这个方案的好处是不受 npm 环境干扰缺点是后续升级要自己重新下载覆盖不如 npm 全局安装方便。3.3 安装后立刻做三件事第一确认命令可用执行codex --version。第二执行一次codex --help浏览一下内置命令清单。第三创建一个干净的测试目录随便写个示例文件比如mkdir ~/codex-test cd ~/codex-test echo console.log(hello codex); test.js这不是必须的但我个人习惯是拿到新工具先创建一个隔离的沙箱目录跑跑看避免在真实项目里误操作。反正后面登录和配置都成功了先拿它做实验最安全。4. 配置与首次登录别卡在这道坎上4.1 ChatGPT 登录鉴权最稳的起步方式安装完成后直接运行codex login它会输出一个登录链接并在浏览器里打开 OpenAI 的登录页面。你登录自己的账号授权后终端会自动收到确认信息本地会生成~/.codex/auth.json保存登录凭证。整个过程和 npm 登录类似属于 OAuth 设备授权流程。登录成功后你直接跑codex它就会进入交互式对话界面。我在这一步建议你立刻输入一句最简单的指令比如“用 Python 写一个快速排序”看它能不能正常调用模型并且把结果写在当前目录。如果这一步通了说明整个链路没问题。4.2 使用 API Key 模式适合没有 ChatGPT 订阅的用户不是每个人都有 ChatGPT Plus 或 Pro 订阅但很多人有 OpenAI API 平台的账号。这种情况下不需要codex login直接配置 API Key 即可。在 OpenAI API 平台创建 API Key 后把它配置为环境变量# Windows PowerShell $env:OPENAI_API_KEYsk-你的key # macOS / Linux export OPENAI_API_KEYsk-你的key然后使用 API 模式启动codex --profile api注意使用 API Key 模式会在官方 API 计费按 token 用量扣费不是订阅制。如果你平时 API 用量不大、只是偶尔让 Codex 干点小活这种方式更划算。如果你是重度用户订阅制会员往往更省心这取决于你的使用频率。4.3 深入了解配置文件与配置结构所有 Codex 的本地配置都在~/.codex/目录下config.toml是主配置文件。auth.json保存登录凭证或 API Key属于敏感文件。log/目录存放运行日志排查问题全靠它。在项目目录下你还可以放一个.codex/config.toml实现“项目级配置覆盖全局配置”的效果。这个机制我非常喜欢团队协作时可以在仓库里提交一份项目级配置新人克隆后codex直接按团队规范运行。一个典型的~/.codex/config.toml长这样model gpt-5-codex model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY说明一下model指定的是模型名称model_provider指定走哪家提供方base_url是 API 接入地址env_key是读取哪个环境变量的值作为密钥。这套结构意味着你可以把model_provider换成 DeepSeek、Ollama 等兼容 OpenAI API 格式的服务商实现“用更强或更便宜的模型驱动 Codex”。这个功能也是网上传得很火的“Codex 接入 DeepSeek”玩法的原理。4.4 手把手Codex 接入 DeepSeek第三方模型配置实例这部分是很多人问的。我自己测试过用 codex 接 DeepSeek能用关键是配置里要写对base_url和model。DeepSeek 兼容 OpenAI API 协议理论上只要你把它的 base URL 指过去模型名写成 DeepSeek 对应的模型 ID就可以让 Codex 驱动 DeepSeek。一个可用的参考配置写作model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY然后设置环境变量# macOS / Linux export DEEPSEEK_API_KEYsk-你的key # Windows PowerShell $env:DEEPSEEK_API_KEYsk-你的key运行时用codex --profile deepseek或者如果你把默认模型改成 DeepSeek直接codex也会按config.toml走。这里有几个细节值得注意model字段必须和提供的模型名完全一致大小写敏感。接 DeepSeek 时要填deepseek-chat或deepseek-reasoner不能填 OpenAI 的模型名。接入第三方模型后Codex 的某些工具调用能力可能会有差异。以我的实测DeepSeek 对函数调用的支持在基础场景下能用但极端复杂的多步骤任务表现可能不如官方模型。所以如果你的场景对代码正确性要求极高还是优先保留官方模型做主力。如果你的第三方服务需要自定义请求头config.toml里可以用extra_headers字段加但一般 API 服务都用 Authorization 头默认就支持。4.5 关于 “Codex 2026 最新版” 的版本选择我建议始终使用最新稳定版原因很简单AI 编程工具迭代极快新版本通常修复了旧版的 bug、提升了任务执行的稳定性、增加了模型上下文窗口支持。用npm update -g codex或去 GitHub Releases 看新版即可。需要说明的是市面上也有同名或相似拼写的工具比如 “Codex” 这个名字被不少项目使用。安装之前务必认准官方来源。正确做法是npm 包名以官方文档/仓库链接为准GitHub 仓库以官方账号发布为准不要在第三方博客里下来路不明的安装包避免被植入恶意脚本。5. 日常使用与上手实践让它真正给你干活5.1 启动与对话模式终端里直接输入codex进入对话模式。在这个模式下它会在当前工作目录执行任务并且可以读取项目里的文件资源。你可以直接说“读一下src/main.js告诉我这个文件导出的函数有哪些”“帮我写一个单元测试覆盖utils/date.ts里所有函数”“运行一下测试告诉我哪里挂了”它会给出一段回复包括它做了什么、为什么这么做。如果它觉得需要执行命令会先征求你的同意比如“我打算运行npm test可以吗”需要输入批准或者直接选择允许模式。这个设计确保了它不会在你不知情的情况下执行危险命令。你可以在对话里让它“自动批准无害命令”降低交互成本但刚开始我建议一条条批准先熟悉它的判断风格再说。5.2 实际任务实操从“一句话”到“一件事”我拿自己的一次真实体验举例。在一个前端项目里项目里有一个页面加载很慢我直接说“帮我分析一下pages/home.vue的接口请求看看哪些可以合并”。Codex 先是读取了文件列出了所有请求接口然后对比了后端接口定义指出有 3 个接口可以并行降低延迟并直接生成了一个优化后的请求函数。我审查代码后手动合并整个过程的代码质量和思路都让我满意。日常使用中我最喜欢的一个功能是让 Codex 处理错误日志。直接把报错贴给它Error: ENOENT: no such file or directory, open C:\data\config.json它会结合项目代码告诉你这个文件是从哪里读取的为什么找不到建议是创建默认配置还是修改路径。这比去搜索引擎搜索错误名效率高太多了。5.3 和 Git 工作流结合Codex 对 Git 的支持是它的一个关键能力。在仓库目录里运行codex你可以让它“看一下当前分支的 diff帮我写个规范的 commit message”“帮我看看git status里有哪些文件改动了解释一下每处改动”“把这两个 commit 合并了保留第一个的 message”它需要调用 Git 命令来完成这些任务因此要求当前目录必须是一个 Git 仓库。实测下来它对常规 Git 操作的把握相当精准但我不建议让它执行破坏性 Git 操作比如强制 push、reset hard这类操作成功率再高一旦翻车代价太大还是手动执行比较稳妥。5.4 与 Web 端 / 桌面端协同配合Codex CLI 和 ChatGPT 网页端/桌面端是可以配合使用的。网页端的优势在于有更大的上下文窗口和可视化文件预览适合处理需要“回溯大量历史上下文”的任务而 CLI 的优势在于直接操作本地文件与命令适合追求快速执行的场景。我通常的做法是复杂问题先在网页端梳理思路、确认方案然后切到 CLI 里让 Codex 动手改代码。两头结合效率最高。6. 常见问题与排查实录我把坑都替你踩平了6.1 “codex 不是内部或外部命令” / “command not found”这个报错占了所有新手问题里的一大半。原因就两类一是安装失败二是 PATH 没配好。排查步骤npm ls -g codex如果能看到 codex 条目说明装上了纯粹是 PATH 问题。执行npm config get prefix拿到全局目录把 bin 目录加进 PATH。如果npm ls -g codex显示没有那就是安装过程出了问题重新执行安装命令注意看终端输出的错误信息。Windows 下我有一个额外提醒装完 Node.js 或 npm 全局包后如果终端是老早打开的窗口PATH 不会自动刷新。一定要重新开一个终端窗口再试这是一个极容易被忽略的低级坑。6.2 登录失败 / 认证过期codex login时提示未授权或者登录超时常见原因有几个浏览器和终端之间的认证回调没有成功。确认浏览器能正常打开登录页并且登录后页面有“成功”或“关闭此页面”的提示。账号本身没有权限。如果账号是组织内子账号部分组织限制 AI 工具访问找管理员确认。auth.json 文件损坏。删除~/.codex/auth.json后重新codex login。一个迟来的经验不要跨时区、跨设备频繁切换登录状态这容易出现令牌刷新冲突。如果你有两台电脑保持各用各的 auth 文件别手动把一台的 auth.json 拷到另一台。6.3 运行时报网络相关错误含 CC Switch 切换报错很多人在配置过其他 AI 编程工具、用 CC Switch 之类的配置管理工具切换模型供应商后运行 Codex 时遇到cc switch local proxy failed while handling codex endpoint /responses类似报错。简单解释下背景CC Switch 这类小程序本质上是在帮你在多个 AI 工具之间“切换模型服务商和本地代理端口”它本身不替代 Codex。出现这个错误通常意味着CC Switch 里设置的本地代理端口并没有实际运行或者 Codex 的config.toml里base_url指向的地址不是当前可用的服务链路。排查顺序建议打开系统设置或 CC Switch 界面确认本地代理/中转服务有没有启动监听的端口是多少。打开~/.codex/config.toml检查base_url是否与正在运行的服务端口一致。查看 Codex 日志目录~/.codex/log/下的最新日志确认请求实际发送到了哪个地址。修改配置后必须重启 Codex 进程而不是开一个新对话。如果确认是自己手写配置造成的错误最稳妥的恢复办法是把config.toml备份后重置为默认配置再用codex login走一遍官方鉴权。这里要特别说明请务必使用正规渠道获取配置模板不要轻信来路不明的“加速配置”或“一键配置脚本”那些往往包含你无法掌握的数据请求路径存在安全和合规风险。6.4 响应速度慢或卡住不动这个问题主要和网络环境或模型负载有关。如果你使用的是官方模型响应慢大概率是服务端负载高可以稍后再试。如果是第三方模型看它的服务状态页。另外检查本机是否设置了系统级代理如果代理地址不可用Codex 请求会一直卡到超时。解决方法是不要使用无效的代理配置删除或修正系统代理、环境变量HTTP_PROXY/HTTPS_PROXY然后重启终端。我这里也提一个使用习惯问题对话时不要一次性丢给它太多文件路径或太长的问题它需要在有限的上下文窗口里处理信息。如果任务实在太大拆分成多轮对话每轮聚焦一个小目标反而更快更稳。6.5 频繁被拒绝执行命令Codex 出于安全考虑对部分有风险的操作会询问权限这是正常现象。如果你觉得它太啰嗦可以在对话开始前明确告知“对于npm test、git status这类无害命令直接执行不要问我。”它一般会按你的指令调整。但如果是删除文件、强推 Git、修改全局配置这类高风险操作我建议始终保留人工审批别图省事。6.6 常见问题速查表症状最常见原因推荐处理方式codex: command not foundnpm 全局 bin 目录不在 PATH重新打开终端或手动添加 PATH登录后无法使用auth.json 损坏或权限不足删除~/.codex/auth.json后重新codex login请求报错 / 端点错误base_url 指向不可用服务或本地代理端口未启动检查config.toml与本地服务状态修正后重启响应卡住超时系统代理无效或服务端负载高关闭无效代理稍后重试改代码不符合预期上下文信息不足明确给出文件路径、依赖关系和期望行为版本过旧自动更新失败或被跳过执行npm update -g codex手动升级6.7 一个独家的排查技巧如果你遇到“同时装了好几个 AI 编程工具相互之间配置串了”的问题教你一个万能隔离法在测试目录下建一个项目级配置.codex/config.toml单独指定该目录使用的模型和 API 地址。这个配置的优先级高于全局配置其他工具完全不会干扰到它。一旦测试通过再决定是否同步到全局配置。Codex 的日志文件~/.codex/log/也会如实记录每次请求的目标地址、报错状态码和模型名称排查网络类问题时比你在网上搜索报错文本管用得多。养成“先看日志再搜报错”的习惯能省不少时间。最后再说一句实在话工具装好了只是开始真正值钱的是你怎么用好它。我的个人建议是前两周强制自己在把一些简单需求交给 Codex 做哪怕自己写更快也让它跑一遍这样你才能理解它的行为模式、摸清它的能力边界。后面再遇到复杂任务你才知道哪些该交给它哪些必须自己来。这种“人机分工”的默契一旦建立起来日常开发效率的提升是实实在在的。