最近后台被问到最多的一个词就是 Codex。从“怎么装”“登录不上”到“能不能接 DeepSeek”再到“为什么总是 reconnecting”问题高度集中。我把自己从下载、登录、配模型到日常使用的完整路径整理了一遍顺手把网上出现频率最高的几个报错也做了根因排查。这篇文章不打算讲太多概念而是按“装好—登录—配置—跑通—排错”的顺序把整个链路走通适合刚接触 Codex、又被各种细节卡住的人直接照着操作。1. Codex 不是又一个“代码补全器”——它到底解决了什么问题1.1 一句话定位终端里的 AI 编程代理Codex 是 OpenAI 推出的 AI 编程代理工具官方把它定位在命令行和编辑器里帮你“干活”的 agent。它和你之前用过的自动补全工具有本质区别补全工具是“你写一句它接一句”Codex 是“你给一个目标它自己读项目、改文件、跑命令、看报错再继续往下做”。我第一次用的时候其实挺不适应的因为它的工作方式不是“建议”而是“执行”。你要让它修一个 bug它会先自己打开相关文件定位问题改完代码后尝试运行测试如果测试没过它会再回头改直到测试通过或者它判断需要你介入。这个过程类似一个初级程序员坐在你旁边唯一区别是他不会主动问你除非你在配置里设置了每一步都请求确认。所以如果你只是想找一个“打字的时候能少敲几个字母”的工具Codex 大概率不适合你。它更适合的场景是项目里有一堆重复的机械改动、跨文件的批量修改、把一段伪代码变成真实实现、根据报错日志反推问题位置这类“小事不值得自己动手但做起来又很费时间”的活。1.2 和 Copilot、Curson 这类工具的核心差异很多人拿 Codex 和 GitHub Copilot、Cursor 对比我自己的感受是它们不在同一个维度上竞争。Copilot 的看家本领是行级补全和对话聊天它给你的是“建议”最终敲不敲回车还是你决定。Cursor 走的是“改代码”路线它可以在多个文件里做修改但主流用法还是你盯着每一步确认。Codex 默认工作模式更激进。在命令行里跑起来之后它会自动执行命令、修改文件、安装依赖甚至调用外部工具。这意味着它会直接动你的项目而不仅仅是给你一段代码让你自己粘。用官方自己的话说它是“agentic”的——有自主性的代理。这种设计带来两个直接结果。第一它能承担更复杂的多步骤任务比如“帮我把这个目录下所有 Python 文件的 print 改成 logging并且把日志格式统一成同一个模板”这类任务在传统交互式工具里很难一次完成因为涉及几十个文件、格式规则、异常处理。第二它的安全模型必须更严谨你不能让它在项目里乱跑所以 Codex 提供了沙箱、审批策略、网络权限控制这些机制。我建议第一次上手的人先把审批策略设成“每次操作都问我”跑顺了再考虑放开。1.3 三种运行形态CLI、桌面版、IDE 扩展Codex 不是一个只有单一形态的工具实际体验中有三种常见入口CLI 命令行工具核心形态所有高级配置和控制能力都体现在这里官方频道发布最频繁。Windows 桌面版适合不想碰终端的人微软商店和官网都有安装包界面是图形化的内置聊天窗口和代码查看器。IDE 扩展VS Code 和 JetBrains 系插件都已在路上VS Code 的支持相对成熟PyCharm 用户可以装插件但稳定性不如 CLI。我的建议是如果你有一点点命令行基础直接上 CLI因为桌面版和 IDE 扩展本质上也是调 CLI 的能力只是外面包了一层界面。CLI 能让你更清楚地看到 Codex 每一步在想什么、做了什么排查问题也方便很多。后面所有章节的操作我也都默认基于 CLI 版本。2. 从安装到登录Windows/Mac/Linux 三端的实战路径2.1 安装前的准备Node版本与npm源Codex CLI 的官方分发渠道主要是 npm 包和 GitHub Release。用 npm 安装最方便命令是npm install -g openai/codex安装前建议先确认 Node 版本够新。我遇到过不少人在这一步卡住报各种奇怪的权限错误和模块解析错误最后发现是 Node 版本太老。官方要求 Node 18 以上但我实测 Node 20 以下的版本在解析某些依赖时会有问题建议直接用 Node 20 或 22 LTS 版本。如果你在国内npm 官方源有时候比较慢安装中途容易超时。可以临时切换到国内镜像源npm config set registry https://registry.npmmirror.com npm install -g openai/codex装完之后跑一下codex --version能输出版本号就说明安装成功。如果提示codex 不是内部或外部命令通常是 npm 全局 bin 目录没在 PATH 里Windows 用户可以在系统环境变量里检查 npm 全局安装路径macOS/Linux 用户检查/usr/local/bin或~/.npm-global/bin是否在 PATH。2.2 三种形态的安装建议为了照顾不同使用习惯我把我在三种形态里的安装结论整理一下形态安装方式适用人群注意事项CLInpm install -g openai/codex想最快跑通全部功能的人需要 Node 18推荐 20/22 LTSWindows 桌面版微软商店或官网安装包不想碰终端的 Windows 用户安装后首次启动要登录注意网络连通性IDE 扩展VS Code 插件市场搜 Codex习惯在编辑器里工作的人配置和 CLI 共用一套登录态桌面版我强调一点安装包一定去官网或微软商店下不要从第三方论坛下载什么“破解版”“汉化版”那些大概率是最新版的安装包改了个图标里面塞了什么不好说。我在排查用户问题时见过两台机器因为装了来路不明的“Codex 加速版”整个系统网络配置都被改了。CLI 在 Windows 上还有个小坑原生命令行的兼容性不如 macO和 Linux。如果你在 Windows 上跑 CLI 经常遇到奇怪的中断、乱码、命令执行失败先别怀疑 Codex试试在 Windows Terminal Git Bash 环境里运行或者干脆用 WSL。这不是 Codex 的问题是很多原生命令行工具在 Windows 下的通病。2.3 登录方式与手机号验证安装完成后的第一步是登录。CLI 里输入codex login它会自动打开浏览器让你选择用 ChatGPT 账号登录还是用 API Key 登录。两种方式的区别很大ChatGPT 账号登录走的是订阅权益Plus/Pro/Team/Enterprise 用户可以在 Codex 里直接使用不需要单独申请 API Key。对大多数人来说这是最省事的方式。API Key 登录适合你对接第三方模型供应商或者不想用自己的 ChatGPT 账号。登录时会让你粘一个 API KeyCodex 会把这个 Key 作为后续请求的凭证。很多人在登录时卡在手机号验证。我的经验是先检查国家/地区代码是不是选对了国内号码就是 86有些用户选了默认的 1自然收不到短信。其次短信有时候确实会有延迟等两分钟再点重新发送。如果多次都收不到建议换回 API Key 方式登录可以绕开手机验证这一步。还有一点容易被忽略登录成功后终端提示Login successful但重启终端又要求重新登录。这种情况多半是认证文件没写进用户目录检查~/.codex/auth.json是否存在不存在就手动执行一次codex login确保浏览器里弹出的授权页面完整走完。2.4 为什么一直提示“无法加载组织设置”搜这个问题的人特别多我在不同机器上也复现过。这个提示一般出现在登录之后、进入会话之前Codex 想从服务端拉取你的组织/团队配置但网络请求失败了。排查顺序我建议这样来先确认网络能正常访问 OpenAI 的服务接口如果当前网络环境本身就不稳定那这个提示完全是网络抖动导致的重试几次就好其次检查账号状态私有组织的用户需要管理员在后台给你开通 Codex 权限没开通就会提示加载失败最后清除本地认证缓存重新登录rm ~/.codex/auth.json codex login如果你有多个账号来回切换auth.json里可能缓存了上一个账号的 token这时候也会报同样的错误。清掉重登基本能解决。请记住一个不算冷的知识Codex CLI 是开源、免费的工具安装本身不依赖任何账号所以“国内能不能用”的第一个答案是——能装。真正涉及限制的是登录环节ChatGPT 账号的地区支持列表是账号侧的事情如果你的账号不支持就改用 API Key 方式登录用第三方兼容模型请求走的是对应服务商的接口跟 ChatGPT 账号无关。3. 核心工作流会话、恢复、exec 与常用命令的取舍3.1 交互模式跑代码和审代码的日常登录完成后在项目目录里输入codex就进入交互模式。这是我最常用的方式因为你可以像和一个同事聊天一样描述任务“帮我看看这个order.py里为什么偶尔会报空指针异常”。Codex 会先读取项目结构、打开相关文件、输出它的分析思路然后动手改。交互模式有几个值得记住的行为CtrlC中断当前任务让 Codex 停下当前动作但不退出会话。CtrlD退出会话。CtrlR重试上一条指令如果 Codex 上一次理解偏了可以改一下措辞再按这个重试。会话里输入exit也能正常退出但CtrlD更快。交互模式的核心价值是“看得到过程”。Codex 每一步做了什么都会实时打出来你可以随时纠偏。比如它准备删某个文件但你不想删直接打断它说明原因它会调整方案。这种控制感是 exec 模式给不了的。3.2 exec 模式一条命令完成自动化任务如果任务是明确、一次性、不需要你盯着看的可以用codex execcodex exec 把 src/utils 下所有 .js 文件里的 console.log 全部替换成 logger.info并保证请求参数格式不变exec 模式不会进入交互界面它直接开始干活干完就退出。这个模式非常适合做批量重构、生成脚手架、运行项目初始化这类事情。我经常用它来做“把某个 markdown 文档转换成网页模板”这类小任务丢给终端之后我该干嘛干嘛回头来看结果。注意 exec 模式同样受审批策略控制。如果你在配置里设了每次修改都要确认那 exec 模式执行中遇到需要修改文件的地方也会停下来等你确认实时输出在终端里。所以自动化任务和审批策略要一起考虑追求“一次跑完”的体验可以把本次会话的审批策略临时调低。早期版本里这个功能叫codex run现在统一改成了codex exec如果你看到旧教程里写codex run 任务直接换成codex exec就行。3.3 斜杠命令与常用会话操作交互模式下有一组斜杠命令我列一下最常用的几个命令作用使用频率/model查看或切换当前模型高频/compact压缩当前会话的上下文防止上下文过长导致遗忘高频/status查看当前会话状态、模型、上下文用量中频/cost查看本次会话的费用估算低频/undo回滚最近一次 Codex 对文件的操作高频救过我好几次/redo撤销 undo低频/exit退出会话中频/compact是特别需要养成习惯的操作。Codex 的上下文窗口虽然不小但在处理大型项目时会话历史很容易占满。一旦你发现它的回复开始“答非所问”、忘记前面说过的规则、重复做同样的事情先执行一次/compact让模型把对话历史压缩成摘要再继续。这个操作比重新开一个会话好用因为任务目标和已经完成的部分会被保留下来不用从头解释。/undo则是我的安全网。Codex 批量改文件的能力很强但有时候批量改完你发现它把不该改的也改了。这时候不要慌/undo会撤销它上一次的文件操作集合甚至可以连续撤销多步。我建议在任何“高危操作”前先记一下会用到的/undo命令因为它在关键时刻比 git checkout 更精准——它只倒回 Codex 自己动过的那部分。3.4 resume 会话中断之后接着干Codex 支持会话持久化。你退出终端、换一台机器、甚至关掉电脑之前的会话记录都存在本地和云端可以通过codex resume直接接上继续聊。codex resume # 恢复最近一次会话 codex resume session-id # 恢复指定会话codex sessions --json可以按时间列出历史会话找到 session id 之后指定恢复。这个功能对长时间任务尤其有用。比如一个跨日的重构任务做到一半发现有个依赖库装不上你可以退出会话去查问题查完回来codex resume上下文还在不用重新给一遍背景。有一点要提醒resume 恢复的是会话文本和文件状态记录不是代码本身。如果你在中断期间手动了项目文件恢复会话后 Codex 会重新读取磁盘上的最新文件内容所以你不用担心它拿着旧版本的记忆去改新代码。这种设计很合理相当于每次 resume 都重新对齐了一次真实项目状态。4. 配置文件与模型接入DeepSeek、中文界面和 AGENTS.md 的实战细节4.1 config.toml 里值得改的几个字段Codex 的配置文件在~/.codex/config.toml首次登录后会自动生成。这个文件是整个工具的灵魂很多“为什么我的 Codex 不听话”的问题根源都在这里。一份最简配置长这样model gpt-5-codex model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com env_key OPENAI_API_KEY第一次上手建议改的字段有两个approval_policy和sandbox_mode。approval_policy on-request sandbox_mode workspace-writeapproval_policy决定 Codex 执行“有副作用操作”时的确认策略on-request表示每次执行命令前都问你是否允许适合新手和在不熟悉的项目里跑任务。workspace-write表示允许它在当前工作目录内写文件但项目外部的系统级改动比如装全局包、改系统文件会被拦截。如果你实在不想每次都被问可以改成approval_policy never。但我的实际体验是在项目环境不熟悉的时候宁愿被多问几次也不要让它自己乱跑。Codex 判断“安全操作”的标准和你的标准未必一致比如它可能认为运行npm install是安全的但这个命令可能瞬间改掉你依赖锁文件的版本树。4.2 接入 DeepSeek 等第三方模型的配置思路“Codex 接入 DeepSeek”是过去几个月搜得最多的需求之一原因是很多人确实需要在国内网络环境下用 AI 编程工具而第三方模型 API 的请求可以直接到达服务商、不受账号地区限制。这个需求本身合理我也实测过几条路径。Codex 要驱动第三方模型前提不是“模型名字叫什么都行”而是模型必须支持工具调用function calling。Codex 的 agent 循环本质上就是“思考—调用工具—看结果—再思考”的循环如果模型不支持工具调用它只能聊天不能改文件、不能跑命令那就没有意义了。DeepSeek 的 API 兼容 OpenAI 的 chat completions 协议也支持 function calling所以可以接。配置思路是这样的在config.toml里新增一个 provider把 base_url 指向 DeepSeek 的接口地址再用DEEPSEEK_API_KEY环境变量存 Key[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat然后启动时指定 provider 和模型codex --provider deepseek --model deepseek-chat这条路径可行但要有心理预期DeepSeek 的模型在简单任务上表现不错涉及复杂多步推理、高频文件修改、长时间自主工作时和官方模型的差距还是会体现出来。我建议如果只是日常做点代码补全、修小 bugDeepSeek 足够如果要做跨模块的大型重构还是优先用原生支持的模型。一个小技巧官方维护了一个模型目录网站 models.dev很多模型的接入参数都能在里面查到。Codex 也支持根据这个目录自动生成 provider 配置可以先去上面搜你要用的模型再手动填到 config 里。4.3 AGENTS.md 和 SKILLS让 Codex 更懂你的项目如果你发现 Codex 在项目中经常“不了解”项目结构或者总是忽视你的代码风格那最有效的解法不是反复在对话里强调而是在项目根目录创建一个AGENTS.md文件。AGENTS.md是 Codex 读取的项目说明书。它和 Claude Code 的CLAUDE.md类似但 Codex 官方主推的是AGENTS.md。我建议项目里两个文件分开维护不要混用因为两套 agent 的上下文交流模式不完全一样混在一起容易让各自产生误读。一个典型的AGENTS.md内容# 项目说明 这个项目是一个电商后端服务技术栈是 Python FastAPI PostgreSQL。 代码在 src/ 目录下测试在 tests/ 目录下。 ## 代码规范 - 所有新代码必须通过 pytest tests/ 才能提交。 - 日志统一使用 logger.info() 格式不要直接 print。 - 数据库表结构变更必须写在 migrations/ 目录里。 ## 常用命令 - 本地启动: uvicorn app.main:app --reload - 跑全部测试: pytest tests/有了这个文件Codex 每次在这个项目里启动会话时都会自动读取它并在任务执行前把里面的约束带到上下文里。你可以直接在文件里写“请始终使用中文回复”这比每次对话都说一遍有效得多也是解决“Codex 说英文”最干净的办法。Codex 还支持 SKILLS 机制就是往项目里放一个skills/目录每个子目录放一个SKILL.md文件描述一种技能的使用方式。比如你经常做“解析日志并生成报告”的事情可以把流程写成一个 SKILLCodex 看到相关任务时自动按流程走。这个东西有一定学习成本建议先把AGENTS.md玩熟再上 SKILLS。4.4 中文显示和界面语言的坑“Codex 怎么设置成中文”这个搜索词出现频率很高但很多用户其实把两件事混在了一起界面语言和回复语言。桌面版的界面语言在设置里可以改改完需要完全退出重开才会生效。CLI 的界面本身是英文的没有中文语言包这一点不用浪费时间折腾。真正重要是回复语言——Codex 用中文还是英文回复你的问题取决于模型收到的指令和界面语言无关。最可靠的方式就是在AGENTS.md里加一行“请始终使用中文回复”。如果你不想建项目级文件也可以在 Codex 的全局配置里加入口。还有人说“我设置了中文但 Codex 有时候还是说英文”这个现象在模型上是正常的尤其涉及技术术语时模型会不自觉切回英文。不要追求百分之百中文反而是在代码注释、报错信息的输出上用英文更不会出问题代码中的注释又不是写给你读者看的是写给编译器看的。5. 高频报错排查reconnecting、local proxy failed、模型不支持的根因5.1 “正在重新连接”为什么反复出现“Codex 正在重新连接”“一直在 reconnecting”这两组搜索词背后其实描述了同一个症状客户端和服务端的连接断开了Codex 在自动重连但一直连不回去。在我的使用经验里这个问题的诱因集中在三类第一类是网络切换比如从公司 WiFi 切到手机热点或者 WiFi 信号不稳定导致长连接被中断客户端重连后一直拉不起新的会话第二类是休眠唤醒笔记本合盖睡眠、电脑休眠唤醒后网络栈还没完全恢复Codex 的 websocket 连接已经断了重连又超时第三类是多个设备同时登录同一个账号Codex 会踢掉旧的连接表现为另一端一直在“重新连接”。排查和解决路径先确认网络连通性随便打开一个网页能打开说明网络没问题。让 Codex 完全退出重新启动一次比在界面里反复点重连有效。如果用了网络转发工具检查它有没有拦截 Codex 相关的域名把它加到直连或白名单里。多个设备不要同时用同一个账号登录尤其桌面版和 CLI 同时开着很容易互相挤下线。日志是最好的排查帮手Codex 会把运行日志写到~/.codex/log/目录下出现 reconnecting 时去里面搜disconnect、error、timeout这几个关键词通常能直接看到断连原因。5.2 cc switch local proxy failed 的排查链路这个报错我在搜索数据里看到时愣了一下因为它同时带出了另一个工具链CC Switch 之类的本地配置管理工具。这类工具的核心作用是帮你管理多个 API provider 的配置切换常见做法是启动一个本地服务监听 127.0.0.1 的某个端口把 Codex 的请求转发到真正的模型服务商。local proxy failed报错通俗讲就是Codex 把请求发给了本地端口但本地端口的转发服务没有正常响应。别急着怪 Codex问题大概率出在本地服务这一层。我的排查顺序是固定的确认本地服务进程还活着。这类工具通常会在系统托盘里运行点开看它是否处于“已启动”状态很多情况下是工具本身崩溃了。看端口是否被占用。netstat -ano | findstr 端口号Windows或lsof -i :端口号macOS/Linux如果端口被其他进程占了本地服务根本起不来。检查配置里的 API Key 是否过期。本地转发服务会拿着你的 Key 去请求上游Key 失效时它会返回 401Codex 可能会包装成local proxy failed。确认 Codex 配置里的 base_url 指向的就是这个工具监听的地址比如http://127.0.0.1:xxxx端口不一致也会报错。这类工具在切换 provider 时容易产生配置文件残留比如切到一个 provider 后发现旧 provider 的端口配置还在Codex 拿着旧配置去连已经停掉的服务报错也就顺理成章了。把 provider 列表完整检查一遍清掉不用的配置再重启工具问题基本能解决。5.3 “模型不支持”提示的含义搜索词里有一句很典型的报错the gpt-5.6-sol model is not supported when using codex with a...。出现这种报错的场景通常是你通过某个网关、聚合服务或者第三方 provider 使用 Codex然后把模型名指定成了一个对方不支持的模型。“不支持”有几种可能模型名称写错了服务商根本没有这个名字的模型模型虽然存在但不支持 Codex 所需的工具调用协议所以报“not supported”或者网关把请求路由到了 OpenAI 官方接口而 OpenAI 侧根本不认识你配置的自定义模型名。排查步骤先确认模型名是不是官方文档里的准确名称很多自定义模型名长得像版本号实际上是某个社区的玩笑命名。检查 provider 的wire_api配置是否和模型匹配。“responses”协议和“chat”协议是两套不同的请求格式接第三方模型时经常要用wire_api chat。用/model命令切回默认模型看问题是否消失。如果切回默认模型也不报错了说明就是刚配置的模型有问题。我遇到过一次很迷惑的情况用户配置的模型名在服务商官网能查到但 Codex 就是报不支持。最后发现是服务商的 API 在工具调用协议上没有完整实现只做了基础文本生成Codex 的 agent 循环根本跑不起来。所以模型名正确只是前提协议兼容才是关键。5.4 日志、缓存和最小化复现排错三板斧所有 Codex 相关的疑难问题我的最终结论都是回到三个动作看日志、清缓存、最小化复现。看日志不用多解释了~/.codex/log/是宝库报错信息里让你“see logs”的时候就老老实实去看。清缓存这个操作我会在确认配置没问题但工具行为很怪的时候做一次删除~/.codex/sessions下的旧会话记录和~/.codex/auth.json重新登录相当于给 Codex 一个干净的状态。注意 sessions 里可能有你没做完的任务删之前先codex resume确认不要了再删。最小化复现的思路是把问题缩小到最简场景然后逐步排除变量。比如“Codex 在项目 A 里正常、在项目 B 里乱来”先把AGENTS.md移走看问题是否消失如果消失就是项目说明书写得太模糊再比如“中文回复不生效”先在一个空目录里建一个只有“请用中文回复”的AGENTS.md测试如果有效就说明是原项目里其他规则干扰了。这样一层层排查比把整个配置删了重来高效得多也更容易定位真正的根因。Codex 这类 agent 工具最大的特点是“可复现性比传统工具弱”——同样的提示词不同上下文、不同模型版本、不同配置环境下结果可能完全不同。所以排错时一定要控制变量一次只改一个因素然后记录结果。我见过很多人遇到问题就全套配置重装结果问题依旧就是因为没有做变量控制技术上问题早就不在配置里了。我个人现在的习惯是新项目一律先用默认配置跑通一次再逐步加AGENTS.md和 provider 配置遇到奇怪报错先 open 日志而不是打开搜索引擎每次会话任务时间超过一小时中途主动/compact一次防止上下文膨胀。Codex 的文档更新很快远端接口行为也可能随时调整但它作为一个“终端里能替你干活”的工具基本使用思路在可预见的范围内不会大变把基础链路走通后面的高级玩法都会顺很多。