简介：这套代码资源围绕OpenAI Codex编程智能体的本地部署展开，适合希望在本地环境体验或搭建AI编程助手的开发者和技术学习者。资源包包含完整的配置思路与对照参考，覆盖免费GLM4.6模型配置与正版Codex拼车方案两种路径，同时整理了快捷命令、MCP Server配置和开发思路说明，可帮助读者快速上手并对比Codex与Claude Code的实际表现。压缩包共3个文件，以inscode配置入口、html说明页和gitignore过滤规则为主，整体仅5KB，轻量而聚焦。目前已有2549人学习，内容来自作者真实体验，在Bug处理能力和用户体验方面给出了明确对比结论，并附带求职背景下的AI学习与职业发展参考，适合中高级开发者作为本地部署与选型判断的实用资料。资源虽小，但将部署路径与对比经验浓缩在一个可直接运行的入口中，便于快速验证。 我第一次在终端里敲下 codex 这个命令时，心里其实挺没底的。过去两年，我几乎所有代码工作都交给了在线 AI 工具，但一碰到代码涉密、网络环境特殊、或者想换模型跑一遍需求，在线方案就变得很被动。后来我把目光放到了 Codex CLI 上——OpenAI 开源的终端 AI 编程代理，可以跑在本地，也能通过配置接入 Ollama、DeepSeek 这类本地或第三方模型。这篇文章就是一份完整的 Codex 本地部署指南：从环境准备、安装、模型接入，到高频报错的排查链路，最后再说说 Skill 怎么把 Codex 调教成符合自己习惯的编程搭子。适合正在折腾本地大模型、想把 AI 编程代理彻底握在自己手里的朋友。

1. 先把概念捋清楚：Codex、Codex CLI 和本地部署

1.1 三个容易混淆的名字

Codex 这个词在不同时期指代过完全不同的东西。最早它是 OpenAI 的代码模型名，后来官方把终端里的 AI 编程代理也命名为 Codex，并且衍生出了 Codex CLI、云端 Codex、IDE 插件等一堆形态。搜索"Codex 本地部署"时能看到各种不同结果，有人装的是模型，有人装的是插件，有人只是在看别人跑代码，所以第一步必须确认：我们说的是 Codex CLI，一个跑在你自己终端里的 AI 编程代理。

它做的事情非常简单：你告诉它"把登录接口加上限流"，它会在本地读你的代码、改文件、执行测试，甚至帮你跑 git 命令。这种形态和 Claude Code 的思路非常接近，但 Codex CLI 的优势在于配置自由度更高，可以接入任意 OpenAI 兼容的后端，这就为"本地部署"留下了很大的想象空间。

1.2 本地部署到底图什么

我自己的理由有三条。第一条是代码隐私，公司内部项目或者还没申请专利的代码，不适合整段丢到别人的网页对话框里；本地部署后，代码只在本机处理。第二条是模型可替换，今天想用 DeepSeek，明天想换 Qwen，改一行配置就行，不被单一平台绑死。第三条是降低对固定服务的依赖，模型跑在自己机器或者自家服务上，内网开发、出差断网的时候基础能力仍然可用。

需要说明的是，本地部署不一定等于"在本地跑几十 G 权重的模型"。它包含三种典型形态：第一种是纯本地推理，用 Ollama 或 vLLM 在自有 GPU 上跑开源模型，完全离线；第二种是模型在云端但通过 API 方式接入，比如 Codex CLI 接 DeepSeek，控制权和成本在自己手里，但模型服务不需要自己维护；第三种是中间加一个网关或编排层，比如 Dify 这类平台做模型路由和知识库，AI 编程代理只是其中一个环节。这篇指南主要覆盖前两种，最后会简单提一下怎么接进更大的平台生态。

2. 安装 Codex CLI：环境、版本和初始化

2.1 先把 Node.js 环境理顺

Codex CLI 是 Node.js 写的命令行程序，安装前第一件事是检查 Node 版本。官方要求不算苛刻，但建议直接上 Node.js 20 LTS 或以上。太老的版本容易出现依赖装不上去、启动直接报错这类问题；版本太低时有些新特性用不了，排查起来还容易误以为是代码问题。检查命令很简单：

node -v
npm -v

如果版本偏低，不要急着用系统包管理器升级，我建议用 nvm（Linux/macOS）或 nvm-windows 来管理 Node 版本。这样有两个好处：一是全局安装的 npm 包会装到当前用户目录下，不会出现 macOS/Linux 常见的 EACCES 权限错误；二是以后在多个 Node 版本间切换非常方便。Codex 更新很频繁，备一个干净可控的运行时环境，能少踩很多坑。

2.2 安装和验证安装

Node 就绪之后，安装 Codex CLI 其实就是一条命令：

npm install -g @openai/codex

装完后别急着用，先验证一下：

codex --version

这里有个细节：Codex CLI 的迭代速度非常快，官方经常加新功能、改配置字段。如果你之前装过旧版本，建议重新执行一次安装命令更新到最新版。我踩过一次很典型的坑：旧版本完全不认识 model_providers 配置段，导致我辛辛苦苦写好的本地模型配置怎么都不生效，后来检查才发现是版本太旧。所以遇到配置不生效、命令报未知参数时，先更新版本再排查，能省掉大量时间。

2.3 初始化：接本地模型不需要 OpenAI 账号

很多人第一次跑 codex 命令会被引导去登录 OpenAI 账号，以为必须登录才能用。实际上，如果你的目标是本地部署、接自己的模型，可以跳过登录。首次运行如果弹出登录提示，直接 Ctrl+C 终止，然后去改配置文件就行。

如果你还是要用 OpenAI 官方的模型，那就执行 codex login ，或者把 API Key 放到环境变量里。我更推荐用环境变量 OPENAI_API_KEY ，不要写死在配置里，免得哪天把配置文件分享出去时顺带把密钥也泄露了。密钥和配置分离，是本地部署这类场景最基础的安全习惯。

3. 让 Codex 用上本地模型：配置文件才是重头戏

3.1 先用 Ollama 把一个模型跑起来

要用本地模型，最简单的方式是 Ollama。它把模型下载、量化、推理封装得非常友好，消费级显卡也能跑得动编码类小模型。安装好 Ollama 之后，拉一个模型：

ollama pull qwen3:8b
ollama serve

ollama serve 默认监听 11434 端口，并且提供一个 OpenAI 兼容的接口。验证一下是否正常：

curl http://localhost:11434/v1/models

能返回模型列表，就说明本地推理服务已经起来了。模型选择方面，编码场景 7B/8B 级别的模型就能应付常见任务，比如 Qwen3 系列；显存足够的话再上更大的模型，效果会有提升，但延迟也会肉眼可见地增加。建议先把小模型跑通链路，再根据实际硬件逐步升级。

3.2 写一份能跑的 config.toml

Codex CLI 的配置文件在 ~/.codex/config.toml ，不存在就手动创建。要让 Codex 用上 Ollama，配置长这样：

model = "qwen3:8b"
model_provider = "ollama"

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

这里有两个关键点。第一， base_url 必须写到 /v1 这个路径。Ollama 的 OpenAI 兼容接口挂在 /v1 下面，只写 http://localhost:11434 会直接 404。第二， wire_api 填 chat ，意思是让 Codex 用 Chat Completions 协议和后端通信，Ollama 的兼容层目前对这套协议支持最稳。改完配置后重新打开 codex ，先随便问一句"帮我写一个计算斐波那契数列的 Python 函数"，能正常返回说明链路已经通了。

3.3 顺便把 DeepSeek 这类第三方 API 接上

本地模型跑通之后，接 DeepSeek 就很容易了，思路完全一样，只是把 base_url 换成对方提供的地址，再加上 API Key。下面是接 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"

然后设置环境变量：

export DEEPSEEK_API_KEY="你的密钥"

Windows 上则用：

setx DEEPSEEK_API_KEY "你的密钥"

注意 env_key 字段只写变量名，不要写 $ 符号也不要写实际值。这样配置和环境分离，换机器部署时只需要重新导出环境变量，不用改动任何代码。

3.4 为什么 wire_api 选错会直接翻车

这是本地部署最容易忽略的协议层问题。Codex 原生使用 OpenAI 最新的 Responses API，但绝大多数第三方模型服务和本地推理工具只实现了更早的 Chat Completions API。如果你的配置里写了 wire_api = "responses" 而后端不支持，请求会直接失败；反过来，如果后端真的是 Responses 风格，你却用 chat 包一层，也可能丢失某些工具调用能力。

所以每次接入新 provider，第一件事是查它的 API 文档，确认支持哪种协议，再决定 wire_api 填什么。我的经验是：能先用 chat 跑通流程，就先用它起步；后续需要研究高级能力时，再切换到 responses 做对照测试。别一上来就追求最新协议，稳定优先。

4. 高频报错排查：从"找不到二进制"到"模型不支持"

4.1 ChatGPT 桌面端报 unable to locate the codex cli binary

这个报错出现频率非常高，场景是你已经在 ChatGPT 桌面应用里打开了 Codex 功能，结果弹窗提示 unable to locate the codex cli binary. set codex_cli_path or ensure the electron... 。根因其实很简单：桌面应用在系统 PATH 里找不到 codex 这个可执行文件，或者它启动时没有继承你 shell 里的 PATH。macOS 上使用 nvm 的场合尤其常见，因为 nvm 的路径只写进了 shell 配置文件，桌面应用拿到的是最基础的 PATH。

排查链路按这个顺序走：

1. 确认 CLI 真的装了： codex --version 。
2. 找到二进制路径： which codex ，记下输出。
3. 设置环境变量 CODEX_CLI_PATH 指向那个完整路径。
4. 重启桌面应用再试。

macOS/Linux 在 shell 里执行：

export CODEX_CLI_PATH=/path/to/codex

Windows 在系统环境变量里新增 CODEX_CLI_PATH 指向 codex.exe 的完整路径。做完这一步，绝大多数情况都能解决。

4.2 model is not supported：模型名必须和 provider 对得上

另一种高频报错长这样： the 'gpt-5.6-sol' model is not supported when using codex with a... ，后面通常还会跟一串 provider 名。这类问题几乎都是配置里的 model 字段填了一个后端根本不认识的模型名。Codex 会把你写的 model 原样透传给 provider，后端不认识就直接拒绝。

比如你配置里写了 model = "gpt-5.6-sol" ，但实际用的是 DeepSeek 的 key，DeepSeek 后端只认 deepseek-chat 这类模型名，自然直接拒绝。排查思路很简单：打开 ~/.codex/config.toml ，确认 model 和 model_provider 一一对应，然后去对应 provider 的文档里查它支持的模型名，用 curl 手动调一次接口验证。比如接 DeepSeek，就发一个 chat 请求看返回是正常还是报模型不存在。这样能把问题范围精确锁定在"配置名写错"还是"协议不匹配"。

4.3 端点连不上：base_url、端口和监听状态

如果请求时报类似 failed while handling codex endpoint /responses 的信息，而且错误信息里带有连接失败、超时这类字眼，问题大概率出在 base_url 配置上，而不是 Codex 本身。以下几种情况我都实际遇到过：Ollama 服务没启动；端口写错，比如 11434 写成 11443 ； base_url 少了 /v1 路径；或者中间接了个自建网关，网关本身挂了。

排查链路我每次都是这样走：

1. 先确认后端服务活着： curl http://localhost:11434/v1/models 。
2. 确认配置文件里的 base_url 和 curl 里用的一致，包含路径和端口。
3. 确认 wire_api 与路径匹配： chat 对应 /chat/completions ， responses 对应 /responses ，填错会返回 404。
4. 如果中间有网关或编排层（比如基于 Dify 做了模型路由），先用 curl 打网关自带的 API，确认网关可用再让 Codex 去连。

这一步需要耐心，绝大多数"本地部署失败"其实是服务没起来或者地址写错，靠 curl 一步步验证就能定位。

5. Skill：把 Codex 从"会用"变成"好用"

5.1 Skill 到底是什么

配置好模型只是第一步，想让 Codex 干活更贴合自己的习惯，还要靠 Skill。简单类比：Skill 就像给 AI 编程代理发一本工作手册，里面写清楚你的代码规范、目录约定、常用工作流。Codex 在处理任务时按需读取这本手册，按你的规矩来，而不是每次都在对话里重复强调。

Skill 本质上是一个 Markdown 文件，放在 ~/.codex/skills/<skill-name>/SKILL.md 下。它在对话里按需加载，不会像系统提示词那样一直占着上下文窗口。和 Claude 的 Skills 机制类似，Codex 也支持这种模式，不同版本的字段和触发方式略有差异，以官方最新文档为准。

5.2 手写一个最小可用的 Skill

我以"规范 git commit message"为例，手把手写一个。先创建目录：

mkdir -p ~/.codex/skills/commit-style

然后创建 SKILL.md ：

---
name: commit-style
description: 生成 git commit message 时强制遵循团队提交规范
---

# Commit Message 规范

- 使用 Conventional Commits 格式
- type 限定为 feat/fix/docs/refactor/test/chore
- 正文解释"为什么"，不要复述代码
- 提交信息用中文，标题不超过 50 字

用的时候，在 Codex 对话里输入"@commit-style 帮我生成刚才改动的 commit message"，它就会按这个规范生成。如果当前的版本不支持 @ 触发，直接用自然语言说"按 commit-style 规范生成提交信息"也一样能匹配到。

5.3 沉淀一套自己的 Skill 库

我的经验是一个 Skill 只解决一件事，别写太长，否则模型反而容易抓不住重点。适合沉淀成 Skill 的内容包括：团队编码规范、目录结构约定、测试命令、部署前检查清单、项目的特殊配置说明。把这些固定套路放进 Skill，每次开新会话都不用重新解释。

我个人的一个小习惯是，把"启动项目并跑一遍测试"这类高频操作写成 Skill，里面把启动命令、依赖环境、常见启动失败原因都写清楚，之后让 Codex 一键完成，省掉大量来回试探的时间。跑顺之后，还可以把 ~/.codex 目录纳入 git 管理，config.toml、Skill 都跟着走，换新电脑一条命令拉下来就能恢复完整环境。如果你想进一步把 Codex 接进 Dify 这类平台做更深的编排，思路和前面接本地模型一样：本质上都是让平台通过 OpenAI 兼容 API 转发请求，先保证端点可用，再谈复杂的知识库和工具链集成。

Codex 本地部署跑通之后，我最大的感觉不是"写代码变快了"，而是"用 AI 写代码"这件事终于踏实了。代码不出本地、模型随手能换、报错能一条条查到自己头上，整个链路都在控制范围内。刚入坑的朋友，我的建议是先别急着上复杂配置，用 Ollama 加一个小尺寸模型把流程跑通，再慢慢换大模型、加 Skill。这一套我跑了几个月，踩过的坑基本都写在上面了，剩下那些更好玩的用法，等你探索出来再回来分享吧。

本文还有配套的精品资源，点击获取