最近很多读者在后台问我Codex 到底怎么安装网上那些“GPT-5.6 配置教程”能不能信为什么我照着配置完直接报model is not supported还有用 CC Switch 切模型时报local proxy failed while handling codex endpoint /responses这又是什么情况这篇文章我不绕弯子直接从 Codex 是什么讲起接着把环境准备、安装步骤、登录鉴权、模型配置、第三方模型接入、完整实战、常见报错排查全部过一遍。文章会尽量保持“照着做就能跑”的风格同时对网上那些夸张说法做一个安全、合规的解释。1. Codex 是什么从终端里长出来的 AI 编程助手1.1 Codex 要解决什么问题Codex 是 OpenAI 推出的 AI 编程智能体产品它不是一个普通的“补全代码”工具而是可以直接在终端里帮你完成“理解需求 → 查代码 → 改代码 → 跑命令 → 看结果 → 继续调整”这一整条开发闭环的助手。你可以把它理解成把 ChatGPT 的对话能力直接搬到了项目目录里。它会读取当前仓库的文件根据你的指令修改代码执行测试命令然后根据输出继续修正。它甚至可以在你允许的情况下操作 git、安装依赖、运行脚本。这个定位和传统 AI 编程工具有明显区别传统补全工具你在编辑器里写代码它预测你接下来要写什么Codex你在终端里给它一个任务它自己去翻代码、改文件、跑命令然后把结果告诉你。所以更准确地说Codex 是一个“终端里的 AI 开发同事”而不是“编辑器的自动补全插件”。1.2 Codex CLI 与网页版、API 的区别Codex 目前常见的使用形式有三种形态说明适合场景网页版打开对话界面上传代码或让 AI 处理仓库轻量使用、不想碰命令行Codex CLI终端命令工具直接在你的项目目录里执行任务本地开发、需要实际操作文件与命令API 模式通过编程接口调用底层模型能力二次开发、自动化流程、内部工具本文重点讲 Codex CLI。因为只有 CLI 才能在本地直接读写项目文件也是目前开发者用得最多、问题也最多的一种形态。1.3 关于“GPT-5.6”这个模型名先泼一盆冷水网上很多标题写着“Codex 接入 GPT-5.6”但这里我必须强调一个关键点模型名不能随便写。Codex 底层使用什么模型取决于你的账号权限、服务商支持情况以及当前官方模型列表。有些第三方文章为了流量会编造“GPT-5.6 配置教程”但实际你把gpt-5.6-sol之类的名字填进配置大概率会得到下面这种报错the gpt-5.6-sol model is not supported when using codex with a provider...这不是 Codex 坏了也不一定是你操作错误而是你配置的模型名在当前服务商和鉴权方式下根本不存在或者模型名拼写已经过时。正确做法是先查看当前账号可用的模型列表再决定配置里写什么。2. 安装前的环境准备2.1 系统要求与前置工具Codex CLI 本质上是一个 Node.js 命令行工具所以安装前最重要的前置条件就是 Node.js 环境。除此之外如果你希望在本地项目里让 Codex 自动操作 git 命令那还需要安装 Git。我整理了一份最小环境清单软件版本要求用途Node.js建议 18 及以上运行 Codex CLInpm随 Node.js 自带安装 Codex 包Git2.x 及以上代码仓库操作终端bash / zsh / PowerShell运行命令如果你的系统中已经安装过 Node.js可以跳过安装步骤但建议确认一下版本node -v npm -v git --version如果这三个命令都能输出版本号说明环境基本没问题。2.2 安装 Node.js 和 npm不同操作系统的安装方式不一样这里我推荐用 nvm 管理 Node.js 版本尤其是 Windows 和 Linux 上都适用后续切换版本非常方便。macOS / Linux 安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新打开终端然后安装 Node.jsnvm install 20 nvm use 20Windows 用户可以直接到 Node.js 官网下载 LTS 版本安装包安装完成后在 cmd 或 PowerShell 里验证node -v npm -v需要注意的是不同 Codex 版本对 Node.js 的最低版本要求可能不同。如果你安装 Codex 时出现引擎版本报错优先升级 Node.js而不是去降低 Codex 版本。2.3 安装 Git可选但推荐Codex 在操作项目时会读取 git 信息比如判断当前在哪个仓库、检测文件变更。如果你希望 Codex 自动帮你提交代码、创建分支Git 就是刚需。macOS 自带 Git但版本可能较旧可以用 Homebrew 更新brew install gitLinux 使用系统包管理器sudo apt update sudo apt install git -yWindows 建议安装 Git for Windows安装时保持默认选项即可。安装完成后全局配置一下身份信息git config --global user.name your name git config --global user.email youremail.comCodex 在生成 git 提交时如果检测不到 user.name 和 user.email会直接报错。3. 安装 Codex CLI3.1 使用 npm 全局安装环境准备好之后安装 Codex CLI 其实就一条命令npm install -g openai/codex安装过程中npm 会把 Codex 的可执行文件放到全局 bin 目录下。安装完成后验证是否成功codex --version能输出版本号说明安装成功。如果你所在网络环境访问 npm 官方源比较慢可以临时切换为国内镜像源但不建议全局永久切换因为不同镜像源的同步速度不一样反而可能装到旧版本npm install -g openai/codex --registryhttps://registry.npmmirror.com安装完成后再切回官方源即可。3.2 查看 Codex 帮助信息Codex 命令行工具自带详细的帮助文档刚接触时不要急着执行任务先看一遍命令列表codex --help输出一般会包含以下几个常用命令Usage: codex [options] [command] Commands: login Log in with your ChatGPT account logout Log out exec Execute a task in non-interactive mode models List available models install Install shell integration ...不同版本的命令会有些差异所以遇到不认识的命令最保险的方式就是查看 help 输出。3.3 如何升级和卸载Codex 更新比较频繁建议定期升级npm update -g openai/codex如果想彻底卸载npm uninstall -g openai/codex卸载后可以再检查一下用户目录下的.codex配置文件夹避免历史配置影响下一次安装。4. Codex 登录与鉴权方式Codex 使用前必须解决鉴权问题。目前主流有两种方式ChatGPT 账号登录和 API Key。4.1 使用 ChatGPT 账号登录如果你有 ChatGPT 账号最简单的方式是直接在终端登录codex login执行后终端会输出一个登录链接浏览器打开链接完成授权然后把回调信息粘贴回终端Codex 就会把令牌保存到本地。这种方式的优点是免去管理 API Key 的麻烦适合个人开发者日常使用。需要提醒的是ChatGPT 账号登录方式下Codex 能使用的模型范围取决于你的订阅类型。免费账号、Plus 账号、Pro 账号可用模型和用量限制都不一样。4.2 使用 API Key如果你是自己调用 API或者准备接入第三方模型服务商那更适合使用 API Key。在终端中设置环境变量export OPENAI_API_KEYsk-你的密钥如果希望长期生效可以把这行写入 shell 配置文件echo export OPENAI_API_KEYsk-你的密钥 ~/.bashrc source ~/.bashrcmacOS 用户如果使用 zsh则写入~/.zshrc。注意API Key 等同于你的账户凭证千万不要提交到 git 仓库也不要随意截图发到论坛。如果 Key 泄露要在官方后台立刻吊销并重新生成。4.3 如何选择鉴权方式场景推荐方式个人日常开发有 ChatGPT 账号ChatGPT 登录团队项目需要统一计费和管理API Key接入第三方模型服务商API Key 自定义 providerCI/CD 自动任务API Key 环境变量注入两种方式可以并存。Codex 会优先读取 API Key再用登录令牌作为兜底。5. 配置核心模型与第三方模型5.1 配置文件在哪里Codex 的配置文件默认在用户目录下~/.codex/config.toml如果文件不存在可以手动创建mkdir -p ~/.codex touch ~/.codex/config.toml这个文件采用 TOML 格式Codex 启动时会读取它来决定默认模型、服务商、网络超时等行为。5.2 配置默认模型打开~/.codex/config.toml最常见的配置是这样的model gpt-5-codex model_provider openai这里的两个核心字段model默认使用的模型名model_provider模型服务商标识默认是openai。强烈建议不要直接照抄网上的模型名。正确姿势是先运行codex models查看当前账号或 API Key 实际可用的模型清单然后把其中一个名字填到配置里。如果你填入的模型名不存在Codex 在执行任务时就会报错。这也是网上那些“GPT-5.6 教程”最容易翻车的地方。5.3 配置第三方模型服务商Codex 支持通过自定义 model provider 接入 OpenAI 兼容的第三方 API。以接入 DeepSeek 为例配置如下model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat requires_openai_auth false这里逐项解释一下配置项作用base_url第三方 API 地址必须和服务商文档一致env_key指定从哪个环境变量读取 API Keywire_apiAPI 协议格式OpenAI 官方用responses兼容服务商一般用chatrequires_openai_auth是否要求 OpenAI 官方鉴权第三方服务商通常设为false配置完成后设置对应的环境变量export DEEPSEEK_API_KEY你的DeepSeek密钥再运行codex就会使用 DeepSeek 的模型来执行任务。需要特别说明的是具体的base_url、模型名和协议类型要以你接入的服务商当前文档为准。不同服务商的兼容程度不一样有的支持responses协议有的只支持chat completions这也是很多接入教程写了一半就跑不通的原因。5.4 完整配置示例下面给一个相对完整的config.toml示例方便你理解整体结构model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat requires_openai_auth false [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses这样配置的好处是你可以在多个 provider 之间自由切换不需要反复修改 base_url只需要切换model和model_provider两行即可。6. 完整实战用 Codex 完成一个 Python 小项目6.1 创建项目结构我先创建一个简单的 Python 项目用来演示 Codex 的完整工作流程mkdir codex-demo cd codex-demo git init然后创建一个说明文件echo # Codex Demo README.md这个项目本身是空的Codex 需要从零开始帮我们生成代码。6.2 启动 Codex 交互模式在项目目录下直接运行codex首次启动时Codex 可能会提示你确认是否信任当前目录。考虑到这只是一个演示项目选择信任即可。进入交互界面后你可以像跟 ChatGPT 对话一样用自然语言描述需求。交互模式下Codex 会实时展示它准备执行的操作并请求你的确认。6.3 执行第一个任务我在交互界面中输入在这个目录下创建一个 Python 脚本实现以下功能 1. 读取当前目录下的 data.txt 文件 2. 统计文本中每一行出现的次数 3. 把统计结果按次数降序输出到 result.txt。Codex 会自己创建脚本、生成测试数据、运行并验证。整个过程不需要我手动写一行代码。6.4 使用 exec 模式与 git 结合在自动化脚本或 CI 场景下交互模式并不方便。这时可以使用 exec 模式codex exec --dangerously-bypass-approvals-and-sandbox 写一个 Python 脚本输出当前时间这个参数会跳过所有确认步骤因此只建议在可信的、隔离的环境中使用。日常开发中我还是建议保留审批机制让 Codex 在运行每个高风险命令前都征求你的同意。Codex 也支持一步完成 git 提交。比如完成任务后直接让它提交代码codex exec git add . git commit -m feat: add word count script需要注意的是Codex 执行的命令会真实作用于当前仓库所以项目一定要做好版本管理避免不可逆操作。6.5 运行结果说明执行完成后项目目录里会出现 Codex 生成的脚本、测试数据和结果文件。这时候我们应该自己检查一遍代码确认逻辑符合预期而不是盲信 AI 的输出。以下是一个典型的结果文件内容3 lines: hello codex 2 lines: hello world 1 line: test lineCodex 的价值在于把“编码 → 运行 → 看报错 → 修改”的循环压缩到了很短的时间内。它仍然需要你来把关最终质量。7. 常见报错与排查思路7.1 codex: command not found现象安装完成后终端输入codex提示找不到命令。可能原因npm 全局 bin 目录没有加入系统 PATH安装过程没有成功使用了非标准 Node.js 安装方式。排查步骤npm root -g先查看 npm 全局安装目录然后把这个目录下的bin路径加入系统的 PATH 环境变量。Windows 用户可以在“系统环境变量”中检查 npm 的全局路径是否在 PATH 里。7.2 cc switch local proxy failed while handling codex endpoint /responses现象使用 CC Switch 之类的配置管理工具切换模型后Codex 执行任务时报错cc switch local proxy failed while handling codex endpoint /responses. provi...可能原因CC Switch 配置了一个本地代理服务但该服务没有正常启动代理服务只支持chat协议不支持 Codex 默认使用的/responses端点配置文件里的模型名或 provider 信息不匹配。排查步骤先确认代理服务是否存活例如访问它对应的本地端口确认代理服务是否支持 OpenAI Responses API如果只支持 Chat Completions可以在 Codex 配置中改用支持chat协议的 provider检查 CC Switch 当前激活的 provider 配置确认base_url指向正确服务暂时绕过代理直接用官方 OpenAI 配置测试判断是 Codex 本身问题还是代理问题。这类问题本质上都是“模型名 服务地址 协议类型”三者不匹配导致的。排查时先把这三项逐一对齐。7.3 the gpt-5.6-sol model is not supported现象把某个网上流传的模型名填进配置后报错提示该模型不被支持。可能原因模型名是杜撰的或者已经下线当前账号或 API Key 没有该模型权限服务商还没适配该模型。排查步骤codex models先确认实际可用的模型列表然后从列表中选择一个名称填入配置。重点提醒对于“GPT-5.6”这类说法不要盲从。AI 工具教程里最容易误导人的就是“新模型名字”。你只需要记住一条原则官方可用模型以codex models输出为准。7.4 WSL 下 localhost 代理配置不生效现象Windows 上使用 WSL 运行 Codex提示wsl: 检测到 localhost 代理配置, 但未镜像到 wsl。nat 模式下的 wsl 不支持 localhost 代理。可能原因WSL 默认使用 NAT 网络模式无法直接访问 Windows 上的 localhost 代理服务Windows 代理环境变量没有传递到 WSL 内部。解决方案在 Windows 用户目录下新建或编辑.wslconfig文件[wsl2] networkingModemirrored然后在 PowerShell 中重启 WSLwsl --shutdown重新进入 WSL 后代理配置会被镜像到 WSL 内部。如果不想改网络模式也可以在 WSL 内手动设置代理环境变量指向 Windows 主机的局域网 IP。7.5 其他高频问题汇总问题现象常见原因解决思路登录后提示认证失败令牌过期 / 浏览器环境异常执行codex logout后重新登录执行命令被拒绝Codex 沙箱权限限制检查目录信任状态按需调整审批策略中文输出乱码终端字符编码问题切换终端编码为 UTF-8Node.js 版本过低Codex 依赖新版运行时安装 Node.js 18 以上版本网络请求超时服务商 API 地址不可达检查 base_url 和网络连通性8. 最佳实践与工程建议8.1 使用额度要合规不要滥用“新用户福利”有些渠道会把 Codex 的推广包装成“白嫖 100 美刀”“免费额度教程”。这类说法中有一部分是官方真实的用户福利但通常会附带使用期限、用途限制和账号限制。我的建议是优先使用官方正规渠道获取额度和授权不要为了套取福利注册大量账号不要把账号借给第三方使用团队场景下使用 API Key 统一计费方便追踪成本。与其研究怎么“薅”不如把精力放在如何让 Codex 真正帮你提高开发效率。8.2 最小权限与安全边界Codex 是一个可以真实执行命令的工具所以安全边界非常重要。在实际项目中应该让 Codex 遵循最小权限原则不要让 Codex 使用 root 或管理员身份运行不要直接把生产环境的数据库连接信息暴露给 Codex执行删除、批量修改、发布等危险操作前先审视它的行动计划使用独立分支或测试仓库进行实验。Codex 生成的代码也可能存在安全漏洞。它可能在你的服务器上执行不可信命令所以最终审查必不可少。8.3 配置文件与密钥管理config.toml里不要写明文密钥。推荐做法是使用env_key指定环境变量密钥统一放到.env文件并确保该文件被.gitignore忽略在 CI/CD 平台中使用密钥管理功能注入环境变量。此外如果团队多人使用 Codex建议使用统一的配置文件模板但密钥各自通过环境变量注入避免密钥在团队内扩散。8.4 日志与可观测性Codex 在执行任务时会产生大量操作记录。在自动化场景下建议使用非交互模式并输出 JSON 日志方便后续分析codex exec --json 运行项目测试 codex-log.json这样即使任务失败也能从日志中定位是哪一步出了问题。8.5 关于第三方模型接入的建议如果要接入 DeepSeek 等第三方模型建议先在官方文档中确认服务商是否兼容 OpenAI APIbase_url是否需要携带/v1后缀支持的模型名是否完整是否支持 Codex 依赖的responses或chat协议。另外不要把“DeepSeek harness”这类社区评估工具和 Codex 配置混为一谈。它们属于不同的项目安装目标和使用方式都不同。8.6 生成代码的审查习惯Codex 可以快速生成大量代码但它并不理解你的业务上下文和隐性约束。每次任务完成之后至少要做三件事1. 阅读 diff确认改动符合预期 2. 运行测试验证功能正确性 3. 检查敏感信息防止密钥或内网地址被提交。只有形成这个习惯才能把 Codex 当成可靠的生产力工具而不是事故制造机。9. 总结与后续学习建议Codex 安装配置本身并不复杂核心就三步安装 Node.js、安装 Codex CLI、配置模型和服务商。但真正让 Codex 好用的是理解它的鉴权方式、模型配置逻辑以及排查报错的方法。这篇文章里我们重点梳理了Codex 的概念和三种使用形态Node.js、npm、Git 环境的准备通过 npm 安装 Codex CLIChatGPT 账号登录和 API Key 两种鉴权方式config.toml 中模型和第三方 provider 的配置方法一个完整的 Python 项目实战高频报错的排查思路包括 CC Switch、模型不支持和 WSL 代理问题。下一步你可以继续探索这些方向在真实项目中尝试让 Codex 处理 Bug 修复或单元测试编写学习自定义 approval 策略让 Codex 在可控范围内自动执行尝试接入不同的模型服务商对比代码质量和成本关注 Codex 官方文档中关于沙箱和安全限制的更新。如果你在安装或配置过程中遇到新的报错欢迎在评论区贴出错误信息我会根据自己的实际经验帮你一起排查。也建议把这篇文章收藏下来下次配置新环境时可以直接对照操作。