★ FEATURED ARTICLE 前阵子有个群友在聊天里甩了我一张截图Codex 终端里红字报错下面跟着一串“local proxy failed”“model is not supported”。他说自己按教程装完结果登录这一关就卡了一下午。我看完第一反应是熟悉——我第一次装 Codex 时也干过类似的事装错了入口又在登录方式上反复横跳最后把 config.toml 改得一团乱连官方模型都被我切没了。这篇文章就把 Codex 安装和登录这两件事彻底捋一遍。重点解决三个问题四条安装入口到底怎么选登录方式怎么匹配才不会报错装完之后用哪些命令确认环境是健康的。不管你之前是卡在 npm、卡在 VS Code 扩展、卡在桌面版还是卡在接 DeepSeek 的配置上按下面的思路走基本都能救回来。1. 四条安装入口别急着抄答案Codex 的“安装”和传统软件不太一样它不是一个安装包吃遍所有场景。目前常见的主流入口有四条npm 命令行、VS Code 扩展、官方桌面版、远程容器环境。很多人一上来就在搜索引擎里找“Codex 安装包”下载完发现打不开或者装完界面和自己预期完全不一样大概率是入口选错了。1.1 入口一npm 命令行绝大多数情况的优先选择Codex CLI 是官方主推的使用方式通过 npm 全局安装一条命令就能完成。我实际体验下来CLI 版本功能最完整模型切换、非交互执行、沙盒模式、配置文件读取这些能力都是最先更新的适合重度使用和需要自动化的人。前置条件就两个Node.js 18 及以上建议直接用 20 LTS以及一个能正常访问外网的终端环境。装的时候没有任何图形界面装完也没有桌面图标很多人装完到处找“Codex 在哪打开”其实打开方式就是在终端里敲codex。这个入口最大的优势是“可控”。你想看它到底加载了什么配置、请求发到了哪个地址、日志输出是什么全都在终端里出现任何问题都能顺着日志追。新手不要怕命令行Codex 的 CLI 设计得很克制常用命令就那几个后面我会完整演示一遍。1.2 入口二VS Code 扩展编辑器里直接干活如果你主力开发环境是 VS Code那扩展入口是体验最好的。在扩展商店搜 “OpenAI Codex”安装官方扩展装完之后左侧边栏会出现 Codex 图标点击就能打开对话面板。它的优势是能自动读取当前打开的代码文件作为上下文不需要你手动把代码粘进去。比如你在app.py里选中一个函数直接在面板里说“给这个函数补上异常处理”Codex 会结合你选中的代码给出修改建议确认后可以直接应用到文件里。但要注意扩展依赖的底层核心还是 CLI。也就是说VS Code 扩展装之前最好先把命令行版也装上否则扩展可能找不到可用的命令行后端。这个关联关系经常被忽略很多人以为扩展是独立应用装完发现不能登录其实就是后端没装。1.3 入口三官方桌面版Windows 用户的最省心方案桌面版适合两类人不想碰命令行的业务同学以及在 Windows 上折腾命令行环境反复碰壁的开发者。桌面版是全图形界面安装完后双击打开登录、对话、查看任务都在窗口里完成不需要你手动配置环境变量。我见过很多次有人在 Windows 上装 npm 包失败报权限错误或者网络错误然后就开始怀疑自己电脑有问题。其实 Windows 用户完全可以绕过命令行直接用桌面版。桌面版的界面逻辑更接近 ChatGPT 的网页对话对刚接触 Codex 的人来说接受成本低很多。它的缺点是版本更新比 CLI 慢一点一些新模型或新参数可能要等一段时间才会同步进桌面版。如果不是追求最新功能这个滞后完全可以接受。1.4 入口四远程容器环境多人协作和隔离沙盒的首选第四种入口是远程开发环境常见形态是 Docker 容器或者云开发机。我个人建议把 Codex 装到容器里有一个额外的好处沙盒隔离更干净Codex 执行命令时的文件系统操作不会污染宿主机。具体做法是在 Dockerfile 里基于 Node 镜像安装 Codex CLI然后通过 SSH 或者网页终端进容器使用。如果你在团队里维护统一的开发环境把 Codex 直接镜像进基础镜像所有人拉下来就自带可用环境省去每个人本地折腾的时间。还有一个很常见的场景是本地 Windows 上跑 Codex 的沙盒功能偶尔会出权限问题后面我会专门讲那个non-elevated terminal报错而放进 Linux 容器里几乎没有这个困扰。所以如果你被本地沙盒问题折磨过不妨试试远程容器方案。四条入口里选哪个关键看你的使用场景而不是哪个“看起来高级”。日常个人开发、想要最新特性选 npm CLI主要在 VS Code 写代码选扩展 CLI 组合刚接触、想省心选桌面版团队协作、追求环境一致性选远程容器。2. 登录方式的选择这一步决定你会不会踩坑如果说安装是开胃菜那登录才是真正的分水岭。Codex 的登录方式不是只有一种选错了轻则登录不上重则出现各种让人摸不着头脑的模型错误。根据我自己的踩坑经历登录方式先分清以下几种再动手。2.1 两种官方登录方式ChatGPT 账号与 API Key官方登录方式有两种ChatGPT 账号登录和 API Key 登录。ChatGPT 账号登录走的是 OAuth 流程你在终端里执行codex login它会拉起浏览器登录 ChatGPT 后在浏览器里确认授权终端这边就自动拿到了登录凭证。这个方式适合有 ChatGPT Plus 或 Pro 订阅的人费用打包在订阅里不需要单独按量计费。API Key 登录则是把 OpenAI API 的密钥配置到环境变量里。适合按量付费、想精细控制成本的开发者。配置方式是在终端里设置export OPENAI_API_KEYsk-你的密钥两种方式的适用场景差异很大。如果你只是日常对话和代码辅助ChatGPT 账号登录体验最好不用关心 token 消耗如果你在跑自动化脚本、批量任务API Key 方式更合适因为可以清楚看到每次调用的费用也能在后台设置月度限额。2.2 接 DeepSeek 等第三方模型时的配置要点很多社区玩家会尝试把 Codex 接到 DeepSeek 这类第三方模型上主要是为了降低调用成本或者利用某些开源模型的能力。这个方向完全可行而且在官方开源版 CLI 里预留了自定义模型提供方的配置入口。配置的核心在config.toml文件里路径一般是~/.codex/config.tomlWindows 上在用户主目录下的.codex文件夹里。添加一个自定义 provider 的写法大概是这样model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 api_key_env_var DEEPSEEK_API_KEY配置完重启 Codex再设置好DEEPSEEK_API_KEY环境变量就能把请求发到 DeepSeek 的服务上。这里有三个容易踩的坑。第一base_url一定要写对不同的模型服务商接受的路径格式不一样有的要带/v1有的不需要。第二Codex 内部调用的是 Responses API 风格的接口路径/responses老旧的第三方网关如果只实现了 chat/completions 接口就会报类似local proxy failed while handling codex endpoint /responses的错误这个我后面会展开讲。第三模型名称必须和你的供应商实际提供的模型名完全一致比如 DeepSeek 官方模型名是deepseek-chat写成DeepSeek-Chat这种大小写不正确的形式请求发出去了也会被服务端拒绝。2.3 登录方式选错时的典型报错对照我后台收到最多的求助帖里有两条报错几乎每天都能看到根源都是登录方式和模型配置不匹配。第一条是the gpt-5.6-sol model is not supported when using codex with a chatgpt account这条的意思是你用 ChatGPT 账号登录但配置文件里指定的模型却不是 ChatGPT 账号可用的官方模型。这种情况多半是因为你之前为了接第三方模型改过config.toml改完忘了改回来或者从网上复制了一份别人的配置直接覆盖了自己原本的配置。第二条是the gpt-6-astra model is not supported when using codex with a chatgpt account性质一样只是换了模型名。这两条报错的核心逻辑是一样的账号类型决定可用模型范围配置里的模型名必须落在账号允许的范围内。反过来也成立。如果你用 API Key 方式登录然后配置了 ChatGPT 订阅专属的模型也会遇到类似的不匹配问题。排查思路其实很朴素先确认自己当前用的登录方式是什么再打开~/.codex/config.toml看model这一项填的是什么理清“账号能用的模型”和“配置里写的模型”是否一致即可。3. 安装与登录的完整实操记录理论说完了下面是我在实际环境中完整跑过一遍的安装、配置、登录流程按这个顺序操作每一步都有明确的验证方法。这里以 npm CLI 为演示对象因为它覆盖的坑最多其他入口的逻辑大同小异。3.1 npm 安装 Codex CLI 及验证先确认 Node.js 版本版本太低会导致安装时报引擎不兼容node -v输出如果是 v18.x 以下建议先升级 Node.js 再继续。然后执行全局安装npm install -g openai/codex安装过程如果长时间停在某个进度不动大概率是网络问题。可以临时切换 npm 源重试但注意装完后记得切回官方源否则后续更新容易出问题npm config set registry https://registry.npmjs.org/ npm install -g openai/codex安装完成后立刻验证两个信息。第一个是版本号codex --version能输出类似0.x.x的版本号说明核心程序装好了。第二个是帮助信息codex --help这里能看到当前 CLI 支持的所有子命令包括login、exec、logout等。如果codex命令提示 not found检查 npm 全局安装路径有没有加入系统 PATH。3.2 全局配置文件 config.toml 的正确写法Codex 的行为由config.toml控制。我第一次用的时候完全不理解这个文件存在的意义后来才发现它决定了你跑的是哪个模型、连的是哪个服务商。文件位置在~/.codex/config.toml找不到就手动创建这个目录和文件。官方登录方式下最简配置只需要指定模型和 providermodel gpt-5.6-sol model_provider openai如果你已经配置了多个第三方 provider建议给每次会话固定一个默认模型避免每次打开终端都要手动选择。比如同时接了 OpenAI 和 DeepSeek可以这样写model deepseek-chat model_provider deepseek注意一个很常见的坑Codex 对配置项名称非常敏感大小写、拼写出错都会触发警告提示内容类似codex is ignoring 1 unrecognized configuration setting. check for typos or details in the documentation比如把model_provider写成model-provider或者把base_url写成baseurl都会导致该配置项被无视。这种报错不会直接中断运行但它会让你花费大量时间排查“明明配置了为什么没生效”。3.3 登录、验证权限、发第一条消息配置完成后开始登录。ChatGPT 账号登录执行codex login终端会显示一个本地回环地址然后自动拉起默认浏览器。浏览器里完成账号登录和授权确认后回到终端会看到登录成功的提示。如果你跑的服务器没有图形界面可以把终端里出现的那个 URL 复制到任意一台有浏览器的设备上打开照样能完成授权Codex 支持这种远程授权方式。登录状态可以用下面命令确认codex status状态输出里能看到你的登录账号、当前配置的 provider 和模型。如果这里显示的模型和你预期不一致回到config.toml修改。最后发一条真实消息测试连通性。交互式对话直接运行codex然后在提示符里输入“用一句话介绍你自己”能正常回复说明全链路已经打通。非交互式场景用codex exec 用 Python 写一个斐波那契数列函数它能直接输出代码并自动执行。这一步验证的是不只是登录还包括沙盒环境下命令执行是否正常。4. 装完怎么确认环境自检清单很多人在“装完怎么确认”这件事上很马虎只看图标能点开或者命令能敲出来就觉得完事了。Codex 这类工具最怕“假成功”界面能打开但登录态是旧的、网络是断的、模型是错的光看表面完全看不出来。我总结了一份自检清单装完按这个顺序过一遍能排掉 90% 的隐性故障。版本确认、帮助信息确认这两步前面已经讲过。接下来要确认登录态是否有效。执行codex status重点关注三行信息是否已登录、当前账号、当前模型。如果已登录但账号不是预期账号执行codex logout清掉旧凭证重新codex login。再看配置文件有没有被正确加载。最直接的验证方式是故意在config.toml里写一个错误的模型名然后执行codex status如果报错说明配置读取正常。但这只是排查手法平时不建议这么玩。正常确认方法是看 Codex 启动时有没有输出“loaded configuration”日志或者直接看命令行启动后提示的模型名。最后做一次实弹测试让 Codex 写一个带文件读写的小脚本并让它真正运行。比如codex exec 创建一个 test.txt写入 Hello Codex再读取内容打印出来如果输出里能看到文件内容说明登录、模型、沙盒、命令执行链路全部正常。这也是我建议的最终确认标准不是看它会不会回答而是看它能不能按你要求完成真实操作。5. 常见问题与排查技巧实录最后这部分把我实际遇到过的、以及读者群里高频出现的问题统一列出来每条都附上排查思路和解决办法。这些问题单拎出来看都不难难的是它们经常同时出现互相干扰。5.1 Windows 上的 daemon 权限错误Windows 上跑 Codex 时出自沙盒功能的报错是最多的典型错误是error: start the windows daemon from a non-elevated terminal意思是请在非管理员权限的终端里启动 Windows 守护进程。Codex 的沙盒机制在 Windows 上需要以普通权限的终端启动一旦你用管理员身份的终端运行反而会触发这个错误。解决方法是关掉所有管理员权限的终端窗口重新打开一个普通终端再启动 Codex。注意这里有个隐藏坑——很多人终端窗口是普通开的但 VS Code 的集成终端继承了编辑器的权限如果编辑器是用管理员权限启动的终端同样是高权限。最彻底的做法是彻底退出 VS Code从开始菜单以普通身份重新启动。5.2 登录时 auth token unavailable 的处理思路错误信息codex auth token is unavailable这个错误第一反应是登录凭证丢了但实际上一共就三个原因环境变量冲突、登录缓存损坏、网络路径异常。排查按顺序来。先检查环境变量里有没有设置OPENAI_API_KEY。如果你既设置了 API Key 环境变量又执行了 ChatGPT 账号登录两个凭证源会打架导致 Codex 拿不到它想要的 token。测试方法很简单临时清掉这个环境变量再登录一次。再检查登录缓存是否完整缓存文件在~/.codex/auth.json。如果文件存在但内容明显残缺退出 Codex 后删掉这个文件重新codex login。注意删除前想清楚删掉后原来的登录会话就作废了需要重新走一遍浏览器授权。最后检查网络。授权流程需要终端本地服务和浏览器页面通信有些网络环境下浏览器能打开页面但终端服务发出去的确认请求被卡住了。这种情况通常过几分钟自动好或者换个网络再试。5.3 转发服务报 local proxy failed 时怎么办错误信息完整版本是cc switch local proxy failed while handling codex endpoint /responses这个场景通常在用第三方配置切换工具的时候出现。工具本身会在本地起一个网关服务Codex 的请求先经过这个网关再被转发到真实模型服务。报错的关键在endpoint /responses——Codex 默认调用的是 Responses API 端点而很多本地网关工具只实现了老的 chat/completions 接口或者对新端点的兼容不完整就会在这里栽跟头。排查第一步先确认你配置的模型服务商官方 API 是否支持 Responses 端点。如果明确不支持那就换一个支持的服务商或者放弃网关方式直接在config.toml里配置官方 base_url。我自己实践下来的建议是能用官方接口直连的不要在中间多加一层多一层就多一个故障点。如果确实需要走本地网关检查网关日志里记录的请求路径是/responses还是/chat/completions。如果是后者说明网关把 Codex 的请求改写成了旧格式但改写不完整才导致失败。优先更新网关工具到最新版本或者换一个对 Responses API 支持完整的工具。5.4 组织设置加载失败与配置项警告提示codex无法加载组织设置这个通常和账号权限有关原因一般有两种当前账号不在配置里指定的组织里或组织标识已经过期。检查config.toml里是否有org org-xxx这类设置。如果是复制别人的配置里面的组织 ID 是别人的你当然加载不了。处理办法是注释掉org那一行重新登录一次让 Codex 自动拉取你账号默认的组织。还有一种情况是和配置警告同时出现codex is ignoring 1 unrecognized configuration settingCodex 对未知配置项的处理方式是静默忽略不会报硬错误。通常原因就是拼写或大小写错误。排查时把报错信息和 config.toml 逐行对照常见的错误包括Base URL写成了base url、model_provider写成了modelProvider。这个坑检查起来很快但网上几乎没人详细讲遇到了容易一头雾水。5.5 安装卡死、打不开、无法发送消息的处理安装卡死的三板斧检查网络、检查 Node 版本、检查安装源。npm 卡住时先按CtrlC打断看报错输出里有没有 EAI_AGAIN、ECONNRESET 这类网络相关关键词。有就换源重试没有就删掉 npm 缓存再装npm cache clean --force npm install -g openai/codex桌面版打不开先看进程有没有残留。Windows 上打开任务管理器找到 Codex 相关进程全部结束再重新启动。很多时候不是程序坏了是之前异常退出后锁文件还在导致新进程起不来。“正在重新连接”或“无法发送消息显示更新 agent 沙盒”这类提示本质都是沙盒启动或会话恢复慢。检查你本机 Docker 环境是否正常因为某些版本里沙盒依赖容器运行时。如果是纯 CLI 模式跑着跑着出现这个优先重启终端和 Codex 进程让沙盒重新初始化。如果频繁出现检查磁盘剩余空间沙盒镜像和临时文件占空间超了预期之后初始化就会卡住。最后Codex 的安装和登录本质上不是技术难度问题而是信息分散造成的认知成本问题。四条入口各有所长没有绝对的优劣关键看你在什么场景下用登录方式则要记住一个核心原则账号类型决定可用的模型范围配置里的模型名必须和账号匹配。安装完别急着写代码先花两分钟过一遍自检清单确认登录态、模型、沙盒都正常后续使用会顺畅很多。我个人实操中还有一个体会把它装好之后一定要把你的config.toml和登录命令记录到自己的备忘里。Codex 更新迭代快很多配置键会在新版本里调整到时候网上找的新教程未必比你自己记录得更贴合当时的环境。我的习惯是每次配置有变动就顺手把旧配置备份一份注释掉留个回滚路径这几年靠这个习惯省了不少事。
阅读完成 · 觉得有帮助？
