最近几周我一直在折腾一个组合：把 Codex 从网页浏览器里解放出来，放到本地终端和桌面环境里跑，后端模型也从默认的官方接口，换成了能自己控制路由的本地模型网关。整个链路跑通之后，我最大的感受是：Codex 本地部署这件事，动手门槛没有想象中那么高，真正容易卡住的反而是几个概念没理清——比如“本地部署”到底部署的是什么、CLI 和桌面版是什么关系、模型服务怎么才能自由切换。这篇实战记录就是给想折腾又怕踩坑的人写的，把从下载安装到接入 DeepSeek、再到日常使用的完整过程，全部摊开讲一遍。
1. 先想清楚一件事：Codex 的“本地部署”到底在部署什么
1.1 云端 Codex 与本地程序的边界
很多人一听“Codex 本地部署”，第一反应是“我要在自己电脑上训练一个大模型”，这个理解其实偏了。Codex 本身不是一个需要你从零训练的语言模型，它更像一套把大模型能力翻译成编程动作的智能体套件：读代码、改文件、执行命令、看报错、再修复，这一整套循环才是 Codex 的价值所在。
具体到部署形态，要拆成两层看。
第一层是客户端程序，也就是 Codex CLI 或者 Codex 桌面版。这部分是实实在在装在你电脑上的，负责跟你对话、操作文件系统、调用终端命令、管理会话上下文。第二层是模型服务，也就是真正干“思考”活的大语言模型。默认情况下，Codex 会把请求发到 OpenAI 云端接口，但你完全可以改成自己的本地模型服务，或者任何一个兼容的第三方接口。
这两层是解耦的：客户端在自己手里，是“本地”的；模型服务既可以指向云端，也可以指向内网自建的推理服务。用一个不太严谨但好理解的类比：Codex CLI 是一个遥控器，模型服务是遥控器背后的电视信号。遥控器拿在自己手里，信号可以来自广电塔（官方 API），也可以来自你家自己架的机顶盒服务器（本地模型）。所谓的“本地部署 Codex”，最常见的做法就是“遥控器在自己手里 + 信号走自己的机顶盒”，两个条件可以自由组合。
1.2 为什么值得把工作流迁到本地
如果你只是偶尔让 AI 写一段脚本、解释一段报错，那网页版确实够用，没必要折腾。但当你打算把 AI 编程助手当成日常主力工具，网页版的限制就非常明显了。
最核心的痛点是文件访问。Codex CLI 可以直接读取你当前项目的源码结构，能定位某个函数在哪里定义、某段配置为什么报错，能直接在本地文件上做修改。网页版做不到这一点，即使能上传文件，也是几个小文件的临时快照，没法形成“读整个仓库-改多处代码-跑测试验证”的闭环。
第二个痛点是工作流集成。本地跑的 Codex 可以直接复用你机器上的 Git 配置、环境变量、密钥管理工具，还能调用你项目里的构建脚本和测试命令。我实测下来，让 Codex 完成“修复单元测试失败”这件事，它会把测试输出读进去，定位到断言失败的位置，改完代码再重新跑一遍测试，整个过程完全在本地终端里完成，非常顺手。
第三个理由是模型可控性。把模型请求指向自己内网跑的 DeepSeek 或开源模型后，代码和会话数据可以不经过第三方云端，对数据敏感的项目来说，这个价值比功能本身还大。而且模型路由一旦打通，你就可以按任务类型切换模型：日常问答用便宜的，深度重构用更强的，成本控制灵活得多。
1.3 谁适合现在就开始折腾
我建议下面几类人群直接开搞：
- 日常重度依赖 AI 辅助编码的开发者：受够了网页版不能读本地文件、不能执行命令的憋屈。本地 CLI 能把 AI 从“聊天窗口”变成“结对同事”。
- 对数据隐私有要求的团队或个人：接入了内网模型网关之后，源码和上下文不出内网，合规压力小很多。
- 折腾型技术爱好者：本身就是玩 Linux、Docker、GPU 部署的，把这套链路跑通之后，可以自由组合各种模型，可玩性很高。
反过来，如果你只是偶尔用 AI 写点一次性脚本，对终端也陌生，那暂时没必要上这套方案——先把网页版用熟，等需求上来了再迁移也来得及。
2. 部署前的准备：环境、账号与模型网关
2.1 本地运行环境清单
Codex CLI 本质上是 Node.js 写的一个命令行工具，所以第一个硬性依赖就是 Node.js 运行时。我建议装 Node.js 18 以上版本，版本太老会出现各种兼容性报错。Git 也是必需的，因为 Codex 的很多操作要依赖 Git 来跟踪文件变更、生成补丁。操作系统方面，macOS、Linux、Windows 都能跑，Windows 上更推荐用 PowerShell 7 或 Windows Terminal 来跑 CLI，体验比老的 cmd 好很多。
桌面版的情况类似，Windows 有独立的安装包，但它在底层调用的还是同一套 Codex 引擎，所以我个人建议：如果你主要在 Windows 上工作，先装 CLI 再决定要不要装桌面版。CLI 的好处是跟终端工作流无缝衔接，可以出现在任何编辑器内置终端里，而桌面版更像是把同样的能力包了一层图形界面。
硬盘空间这块，工具本身占用不大，装完大概几百 MB 到 1GB 左右。但要注意，如果你打算在本机跑模型服务（比如用 Ollama、LM Studio、vLLM 跑一个 DeepSeek 量化模型），那模型文件会占几十 GB 空间，GPU 显存也要对应跟上。我之前在一张 24GB 显存的卡上跑过 14B 级别的量化模型，勉强能跑，但生成速度只能说够用；要跑更大参数的模型，建议上多卡或者直接用 API 网关中转。
2.2 获取 Codex 授权与 API Key
这一步很多人会卡住，所以单独拿出来说清楚。
使用 Codex 需要两个层面的授权：一个是 Codex 程序本身的访问权限，另一个是后端模型服务的调用凭证。在官方默认链路下，你需要在 OpenAI 账号体系下开通 Codex 功能，然后通过codex login完成 OAuth 登录，登录成功后会生成一个本地凭证，CLI 拿这个凭证去访问云端接口。
如果是走 API Key 的方式，那你要去 API 平台创建一个密钥，然后把密钥设置成环境变量或者直接写进配置。这里有个容易混淆的地方：ChatGPT 会员登录态和 API Key 是两套不同的鉴权系统。我之前就见过有人把 API Key 当成 ChatGPT 密码来登录，结果折腾半天登录不进去。记住一条简单规则：如果你要用官方默认模型，建议走 OAuth 登录；如果你要接第三方模型或本地模型服务，则走 API Key，并且这个 Key 是你所对接服务商提供的，不是 OpenAI 的。
2.3 Model Provider 选型：官方模型还是 DeepSeek 等第三方
Codex 内部有一个 model provider 的概念，通俗讲就是“模型服务商”。每个 provider 定义了一个接口地址、一个密钥环境变量名，以及一份可用模型列表。官方配置里内置了 OpenAI 自己的 provider，但我们可以手动添加新的 provider，把请求转发到兼容的第三方服务上。
我目前实测下来，社区里用得最多的替代模型是 DeepSeek 系列。原因很简单：第一，DeepSeek 的 API 兼容 OpenAI 的接口协议，Codex 不需要任何额外适配；第二，价格比官方模型便宜一个量级，编码任务的生成质量也够用；第三，DeepSeek 有开源权重，你可以自己在内网用 vLLM 或 SGLang 部署，彻底脱离外部 API。
| 模型服务 | 接口协议 | 成本 | 部署方式 | 适合场景 |
|---|---|---|---|---|
| OpenAI 官方模型 | OpenAI 兼容 | 较高 | 云端 SaaS | 追求最强能力，能接受数据出网 |
| DeepSeek API | OpenAI 兼容 | 低 | 云端 SaaS | 高频任务、成本敏感 |
| 本地部署 DeepSeek 量化 | OpenAI 兼容 | 硬件成本 | 自建推理服务 | 数据不出内网，隐私敏感 |
选型上我个人的建议是：第一次跑通链路，用 DeepSeek API 最省事，因为不需要考虑 GPU 资源，接口兼容性也已经有大量验证；等你把整个流程跑顺了，再去折腾本地推理服务也不迟。
3. Codex 下载安装全流程：CLI 与桌面版两条路
3.1 通过 npm 安装 Codex CLI
官方 CL I 的安装方式很简单，一行命令：
npm install -g @openai/codex安装完成后，先验证一下是否成功：
codex --version能看到版本号就说明程序本体装好了。这里有一个很容易踩的坑：npm 全局安装目录如果不在系统 PATH 里，终端会提示找不到codex命令。解决办法是重新设置 PATH，或者查看 npm 全局 bin 目录的真实路径，把它加进 shell 配置里。我见过不少人卡在这一步，其实不是安装失败，就是 PATH 没对上。
装好之后，第一次使用之前要先登录：
codex login这个命令会打开浏览器，让你完成账号授权。授权成功后，本地会生成一个凭证文件，后续使用不需要反复登录。如果你打算用 API Key 模式，可以跳过codex login，直接配置 provider 信息。
3.2 Windows 桌面版安装
桌面版是另一个选择。如果你在 Windows 上，可以去官网下载桌面版安装包，安装流程是标准的下一步式，没什么特殊操作。装完之后打开客户端，登录方式和 CLI 类似，也要走一遍授权。
但我要多提醒一句：不要以为装了桌面版就可以不装 CLI。桌面版在图形界面上确实更友好，但很多自动化操作、脚本调用、编辑器联动，最终还是落到 CLI 上。我的建议是两台腿走路：日常人机交互用桌面版，批量任务和编辑器联动用 CLI，两者共用一套登录凭证和配置目录，切换起来没有负担。
3.3 安装后的初始化与登录验证
装完不验证就等于白装。我每次在新机器上部署完，都会按这个顺序做一遍体检：
- 检查版本号：
codex --version，确认命令可用。 - 检查登录态：
codex login status（不同版本命令可能略有差异，可以在codex --help里确认），或者直接看本地配置文件里的授权信息是否存在。 - 跑一次空转对话：随便问 Codex “请输出 hello world”，确认从客户端到模型服务的整个链路是通的。
这里涉及一个关键路径概念：所有配置和凭证都存放在用户目录下。CLI 的配置文件叫config.toml，登录凭证通常在.codex目录（具体文件名以版本提示为准）。动手改配置之前，先确认这些文件的位置，后面排查问题全靠它们。
3.4 配置 config.toml，把模型指向 DeepSeek
这是整个本地部署过程中最有含金量的一步，也是热词里“codex 接入 deepseek”的答案所在。
Codex 的配置文件config.toml采用 TOML 格式。默认情况下你可能不需要碰它，但一旦要切换模型服务商，就必须在这里手动添加 provider。下面是我实测可用的一份配置：
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 = "responses"几个关键字段逐一说清楚：
model：指定默认使用的模型名称。这里写的是 DeepSeek API 的模型别名，如果你自己部署了开源模型，就填你部署服务暴露的模型名。model_provider：指定走哪个 provider，要和下面[model_providers.deepseek]的键名一致。base_url：模型服务的接口地址。DeepSeek 官方 API 尾部要带/v1，很多兼容服务也是同样套路；本地 vLLM 服务通常直接填http://127.0.0.1:8000/v1这类地址。env_key：告诉 Codex 从哪个环境变量读取密钥。比如DEEPSEEK_API_KEY，那你就需要在 shell 里先export DEEPSEEK_API_KEY=sk-xxxx，或者写在.env文件里 source 一下。wire_api：这个是传输协议类型，当前版本填"responses"是官方推荐方式，兼容性也最好；早期版本有的需要填"chat"，如果你用的是旧版本，报错说 endpoint 不识别，可以检查一下这个字段。
改完配置后，先用codex --help或者直接发起一次简单对话验证。如果 Codex 提示找不到模型，多半是model这个字段的别名没对上；如果提示鉴权失败，就去查环境变量是否真的导入了。
4. 让 Codex 真正跑起来：一次完整的实操会话
4.1 启动会话与工作区选择
配置搞定后，就可以开始实际使用了。先进入一个真实项目目录：
cd /path/to/your/project codex直接运行codex会进入交互式会话。这时候 Codex 默认能感知当前目录的文件结构，但不会自动把所有文件读进上下文，而是按需加载。你在提问时提到某个文件名，或者需要修改某段逻辑，它才会去读对应内容。这种懒加载设计很聪明，既省 token 又避免上下文被无关文件塞满。
Codex 默认会启用安全审批机制，涉及执行命令、修改文件这类操作时，会弹出确认提示。初次使用者可以先保持默认的谨慎模式，跑熟了再根据需求调整。如果你感觉自己对项目完全放心，也可以使用--full-auto这类参数让 Codex 自动执行全部操作，但这个过程我建议只在 Git 工作区里用，万一改错了还能回滚。
4.2 从需求到代码的完整过程
为了让你直观感受这个工具的工作方式，我记录一次我用它修改测试代码的真实过程。
我在一个 Python 项目里运行测试时发现某个接口的返回值格式不符合预期，于是直接在 Codex 会话里发起需求：
这个项目里 tests/test_api.py 有个测试在断言返回的 user 对象字段，但实际接口返回的字段名是 user_name。请找到所有相关断言并修复它们，然后运行测试验证。Codex 首先会读取tests/test_api.py，定位到失败断言的具体行，然后顺藤摸瓜找到接口逻辑里返回字段的定义位置。接下来它会给出一个修改方案：把测试断言中的字段名更新为user_name，或者让接口层做一层映射。我让它选择了前者，因为它直接修改了发起方，不会碰接口兼容性。
然后 Codex 开始改文件，每一步都展示 diff，等确认后写入。接着它在我的终端里自动执行测试命令，把测试输出读回上下文，看到全部通过后给出总结。整个过程大概三分钟，它的表现就像一个熟悉代码库的同事，而不是一个只会聊天的对话机器人。
4.3 会话历史、审批权限与沙箱机制
这里有几个使用体验上的细节，我单独拿出来讲。
第一，会话可以恢复。关掉终端后，用codex resume可以回到上一次的会话，上下文不会丢。这个功能在你做长时间重构任务时特别有用，不用每次重新描述需求。
第二，审批粒度可以调节。Codex 把操作分成读文件和写文件、执行命令、网络请求等不同等级，你可以在配置里调整哪些操作需要确认，哪些放行。我个人的配置是：网络请求一律要确认，文件修改默认确认，测试命令放行。这样既不打断思路，又能守住底线。
第三，理解沙箱机制。Codex 在执行命令时，会默认在一个受限环境里跑操作，防止它误伤系统。你可以把它理解成给它穿了一层“防火围裙”，它可以做饭，但不能烧厨房。如果你的项目需要安装依赖、访问系统服务，遇到沙箱拦截是正常的，按提示选择放行或永久信任即可。
5. 常见问题与排查技巧实录
这个部分是我最想写的，因为整个部署过程中我踩过的坑，几乎全被热搜词里那几条问题精准命中了。
5.1 登录与授权相关：登录不上、无法加载组织设置
“Codex 登录不上”“Codex 无法加载组织设置”是我见到最多的求助帖。按我的排查顺序，先确认是不是网络问题：能不能正常访问目标服务商的官网。排除网络因素后，大概率是本地凭证失效或损坏，此时可以执行codex logout后重新登录，强制刷新凭证。
组织设置加载失败通常出现在账号属于多个组织或工作空间的场景。Codex 登录时默认会选择当前账号的默认组织，如果默认组织设置异常，就会出现“登录成功但组织加载失败”的怪现象。解决办法是在登录后手动切换组织，或者先打开网页端把默认组织改成最常用的那个，CLI 那边一般就会恢复正常。
这类问题还有一个隐蔽来源：凭证文件损坏。如果你之前手动拷过配置目录、做过系统迁移，多检查一下凭证文件的权限和完整性。正常情况下，权限应该是当前用户可读写，如果变成 root 所有或其他用户所有，CLI 会读不到信息，直接表现为登录不上。
5.2 模型不可用：model is not supported 与 unrecognized configuration setting
热词里有一条很经典的报错：the 'gpt-5.6-sol' model is not supported when using codex with a...。这类报错的核心原因只有一个：你用的 Codex 版本不知道这个模型名。
可能的情况有三种。第一种是模型名拼错了，或者那个模型只存在于特定渠道，你的账号没有权限访问。第二种是版本过旧，Codex 客户端不认识新推出的模型，升级版本即可。第三种是你自定义 provider 时填写的模型别名与推理服务实际暴露的名称不一致，本地模型尤其容易发生这种问题。
另一个相关报错是codex is ignoring 1 unrecognized configuration setting. check for typos。这个报错说明你的config.toml里有一个配置项是 Codex 不认识的。最常见的诱因是拼写错误，比如model_provider少写了一个字母，或者base_url写成了baseurl。排查方式很简单：把配置逐行跟官方文档对一遍，或者先把多余的自定义项全部注释掉，再逐个启用定位问题源。
5.3 网络与网关异常：endpoint /responses 访问失败
热搜词里还有一条很长的报错：cc switch local proxy failed while handling codex endpoint /responses...。这类报错一出，很多人以为是 Codex 本体坏了，其实问题基本集中在网络链路和接口地址上，Codex 只是把底层网络错误往上层抛了出来。
排查思路按三个顺序来：第一，检查base_url是否填对。特别是自建模型服务，地址的协议、端口、路径前缀都要确认，常见错误是把http://127.0.0.1:8000/v1写成http://127.0.0.1:8000，少了一个/v1，请求就会打到错误的路径上。第二，确认目标服务真正在监听。在终端里用 curl 直接访问一次接口地址，如果返回正常，说明网络层没问题，问题在 Codex 配置；如果 curl 都连不上，那要回到服务端排查。第三，检查鉴权信息是否随请求正确传递。很多第三方网关会在鉴权失败时返回 401，但 Codex 会把错误包装成“endpoint 异常”的形式，容易产生误导。
这个问题的根治方法，是在配置里保持base_url和你手工测试时的地址严格一致，不要凭印象填写。
5.4 本地模型服务对接时的坑
当你从 DeepSeek API 切换到本地推理服务时，常见的坑有两个。
第一个坑是模型名不一致。本地用 vLLM 起服务时，暴露出来的模型名是启动参数决定的，比如你部署的是 DeepSeek 的量化权重，服务里注册的名字可能是deepseek-ai/DeepSeek-V3，但在 API 请求里你只能用完整的注册名。如果 Codex 配置里model写的是不带命名空间的短名字，服务端会返回 model not found。
第二个坑是上下文长度限制。Codex 的智能体工作流很吃上下文，它会主动塞入多轮对话内容、文件 diff、命令输出。如果你本地模型的最大上下文长度设置太短，会出现“聊着聊着突然断掉”或者“任务做到一半失去上下文”的现象。解决方案是在推理服务端把 max context length 尽量开大，至少要 32K 起步，有条件直接上 128K。上下文不足对 Codex 的影响比其他 AI 对话工具严重得多，因为它是一个有状态的工作代理，丢一段上下文可能就丢了整个任务的连贯性。
| 报错现象 | 大概率原因 | 排查与解决 |
|---|---|---|
| 登录不上 | 凭证损坏或网络受限 | codex logout后重新登录，检查凭证文件权限 |
| 组织设置加载失败 | 默认组织异常 | 网页端切换默认组织，或 CLI 内手动切换组织 |
| model not supported | 模型名错误或版本过旧 | 核对模型名，升级 Codex 版本 |
| unrecognized config | 配置项拼写错误 | 对照文档逐项检查config.toml |
| endpoint /responses 报错 | base_url 不对或服务未启动 | curl 直连接口地址，确认协议、端口、路径前缀 |
| 本地模型会话中断 | 上下文长度不足 | 调大推理服务的 max context length |
6. 把 Codex 用顺手的进阶技巧
6.1 用自定义指令和会话策略优化输出
Codex 支持通过项目内的AGENTS.md文件来定义项目级别的约束和指令。你可以在这个文件里写明代码风格偏好、禁止使用的库、测试要求等等。它相当于一条隐形的项目规范，Codex 每次干活之前都会先读一遍这个文件，再开始修改代码。
我建议每个人都为常用项目写一份AGENTS.md，哪怕只有三五行都行。比如我某个项目里就明确规定：不要修改公共接口签名，新增字段必须写迁移脚本。加了这一行之后，Codex 的输出质量立刻上了一个台阶，因为它不会再“自由发挥”改动不该动的地方了。
6.2 与 Dify、DeerFlow 等本地 AI 工具联动
Codex 不是唯一值得部署的本地 AI 工具。如果你已经在折腾本地大模型部署，大概率也听说过 Dify 和 DeerFlow。Dify 更擅长把大模型能力编排成可视化工作流，DeerFlow 则更聚焦文档解析和知识库处理。
我目前的做法是：Codex 负责代码层面的深度修改，Dify 负责业务流程编排，DeerFlow 负责把本地 PDF、Office 文档解析成结构化数据喂给下游。三者都跑在本地或内网，构成一个小型 AI 工作台，互不干扰却又能通过 API 串联。这种“各司其职”的组合，比把全部任务都压在一个模型上要靠谱得多。
6.3 让 Codex 读本地代码库的姿势
Codex 不是所有文件都会主动读的。大会上传整个仓库的时代还没完全到来，精准引导它读文件是提升效率的关键技巧。
一种有效做法是“指路式提问”：在需求描述里直接指定文件路径，比如“参考src/utils/parser.py里的解析逻辑，在src/services/下新增一个服务”。代码世界里的定位越精确，回复质量越高。另一种做法是用好忽略文件，格式类似.gitignore，让 Codex 自动跳过无关目录，比如构建产物、第三方依赖包，这样它读代码时注意力不会被大量无关文件分散。
最后再分享一个我自己的体会：Codex 本地部署的价值，不在于把这套工具装上，而在于通过配置文件、模型网关和项目约束，把它驯化成真正适配你工作流的东西。装上只是起点，配置才是真正拉开差距的地方。我折腾这几周最深的感受是，接 DeepSeek、调本地模型、写 AGENTS.md，每一步单独看都不复杂，但串起来之后，Codex 就从“一个聪明但偶尔自作主张的实习生”，变成了“熟悉你代码库、遵守你规范、能连续干活几个小时的可靠同事”。如果你正在犹豫要不要入坑，我的建议是：先跑通 CLI 加默认模型的链路，再一步步切换模型、加上自定义指令，这个过程本身就是对自己工作流的一次重新梳理。
