最近后台被问到最多的一个词，就是 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 三种形态的安装建议
为了照顾不同使用习惯，我把我在三种形态里的安装结论整理一下：
| 形态 | 安装方式 | 适用人群 | 注意事项 |
|---|---|---|---|
| CLI | npm install -g @openai/codex | 想最快跑通全部功能的人 | 需要 Node 18+，推荐 20/22 LTS |
| Windows 桌面版 | 微软商店或官网安装包 | 不想碰终端的 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 Key，Codex 会把这个 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 会先读取项目结构、打开相关文件、输出它的分析思路，然后动手改。
交互模式有几个值得记住的行为：
Ctrl+C中断当前任务，让 Codex 停下当前动作但不退出会话。Ctrl+D退出会话。Ctrl+R重试上一条指令，如果 Codex 上一次理解偏了，可以改一下措辞再按这个重试。- 会话里输入
exit也能正常退出，但Ctrl+D更快。
交互模式的核心价值是“看得到过程”。Codex 每一步做了什么都会实时打出来，你可以随时纠偏。比如它准备删某个文件，但你不想删，直接打断它说明原因，它会调整方案。这种控制感是 exec 模式给不了的。
3.2 exec 模式：一条命令完成自动化任务
如果任务是明确、一次性、不需要你盯着看的，可以用codex exec：
codex 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-write"approval_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 的模型在简单任务上表现不错，涉及复杂多步推理、高频文件修改、长时间自主工作时，和官方模型的差距还是会体现出来。我建议如果只是日常做点代码补全、修小 bug，DeepSeek 足够；如果要做跨模块的大型重构，还是优先用原生支持的模型。
一个小技巧：官方维护了一个模型目录网站 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文件，描述一种技能的使用方式。比如你经常做“解析日志并生成报告”的事情，可以把流程写成一个 SKILL，Codex 看到相关任务时自动按流程走。这个东西有一定学习成本，建议先把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 失效时它会返回 401，Codex 可能会包装成
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 的文档更新很快，远端接口行为也可能随时调整，但它作为一个“终端里能替你干活”的工具，基本使用思路在可预见的范围内不会大变，把基础链路走通，后面的高级玩法都会顺很多。
