最近一个月我把 Codex CLI 翻来覆去折腾了好几遍从最初在终端里敲两行命令就报错到后来能把官方模型、DeepSeek API 和本地 Ollama 模型全部接到同一个配置文件里切换着用整个过程踩了不少坑。这篇东西就是一份实战记录照着走一遍你也能在本地把 Codex 跑起来并且让它按你的需要去对接不同的模型服务。会涉及环境配置、CLI 安装、认证、本地模型接入、API 集成还有常见报错排查基本把本地部署这条路走通。先说清楚一件事Codex 本身不是一个“大模型”它是一个跑在终端里的 AI 编码代理工具。它负责理解你的指令、读取项目文件、调用模型来完成代码修改和命令执行。所以“本地部署 Codex”不是让你本地训一个模型而是让 Codex 这个壳子在本地跑起来然后再把模型接进去。模型可以继续用官方远程的也可以接本地跑的 Ollama、LM Studio还能接像 DeepSeek 这类第三方 OpenAI 兼容接口。1. 部署前必懂Codex CLI 的组成与本地化思路1.1 Codex CLI 是什么和网页版有什么不同老读者应该知道OpenAI 的 ChatGPT 网页里内置了一个 Codex 功能能直接操作沙箱里的代码。但网页版的问题是它只能在你给它的那个隔离环境里干活碰不到你真实的项目文件。Codex CLI 解决了这个痛点它是一个开源的命令行工具你在项目目录里运行它它就能直接读取、修改本地代码执行 git 命令、跑测试、做代码审查最后把改动直接落到磁盘上。说得直白一点网页版 Codex 像一个“远程外包”你描述需求它给你一个结果但中间过程你控制不了本地部署的 Codex CLI 就像一个“坐在你工位旁边的协作者”它能看到你完整的上下午文改完代码你立刻能跑测试验证。对于经常需要处理多个项目、希望保持代码私密性的开发者来说本地 CLI 的价值非常大。代码层面Codex CLI 是 Node.js 写的所以它和 Node 生态的关系很紧密。你安装它、运行它本质上是启动一个 Node 进程这个进程负责和模型 API 通信、维护对话历史、执行命令。理解这一点很重要后面很多环境配置、报错排查都得回到这个根上。1.2 本地部署的三种典型组合本地部署 Codex 时模型怎么接大概有三种主流组合我也建议你在动手前先想清楚自己属于哪一种。第一种最省事Codex CLI 接官方远程模型。这种组合只要装好 CLI、登录账号什么都不用操心模型能力最强代码理解能力最好但要求你的网络环境能稳定访问 OpenAI 的服务。第二种隐私优先Codex CLI 接本地的 Ollama 或 LM Studio。模型权重完全在本地代码不会出本机适合写敏感项目、客户代码或者内网开发环境。缺点是对硬件有要求模型能力也比云端旗舰模型弱一些。第三种性价比路线Codex CLI 接第三方 OpenAI 兼容 API比如 DeepSeek。这种方式不需要本地显卡又能绕开官方服务的访问限制中文理解好价格也便宜国内开发者用得非常多。我自己的主力配置就是这一种。这三种组合并不冲突它们可以同时写在配置文件里随时切换。后面我会详细演示怎么配置这是整个实战里最核心的部分。1.3 配置文件与数据流向Codex CLI 的全局配置放在你的用户目录下的.codex文件夹里核心文件是config.toml。这个文件决定了三件事默认用哪个模型、模型服务商怎么连接、工具的权限边界。还有一个sessions目录存放历史会话记录方便你之后翻看之前跑过哪些任务。整个数据流向也不复杂你在终端输入指令Codex CLI 先读取项目上下文再按照config.toml里指定的base_url和model把请求发出去等服务端返回结果后CLI 解析响应、决定下一步动作改文件、跑命令、还是继续追问。所以你会看到不管接什么模型只要对方提供了 OpenAI 兼容的接口Codex 就能工作——这个“兼容性”是整个接入方案能够成立的核心前提。我见过不少人在部署时卡住其实就是因为没有搞清楚这条链路。模型接不上、响应解析失败、端点 404问题往往出在base_url或者接口类型配置错了。2. 环境配置先把 Node.js 和终端环境收拾利索2.1 检查环境Node.js 版本与 npm 源Codex CLI 是 npm 包所以 Node.js 是硬性依赖。官方要求 Node.js 18 或更高版本我个人的建议是直接上 20 以上的 LTS 版本实测更稳定不会碰到一些老的兼容性报错。打开终端先检查本机环境node -v npm -v如果提示命令不存在说明还没装 Node.js。Windows 用户我建议直接去 Node.js 官网下载 LTS 安装包一路下一步就行安装过程会自动把 npm 一起装好还会把环境变量写进系统里。macOS 用户如果装了 Homebrew一条brew install node就能搞定Linux 用户建议用 nvm 装避免系统自带的版本太旧。装好之后再确认一下 npm 源。国内网络环境下npm 官方源偶尔会抽风下载大包时容易卡住或超时。部署 Codex 之前我建议把源切到国内镜像这样安装速度会快很多npm config get registry npm config set registry https://registry.npmmirror.com2.2 Windows 和 macOS/Linux 的安装差异Windows 上部署 Codex 有一个很容易忽略的点终端的权限问题。你如果用 PowerShell建议在管理员模式下运行安装命令避免 npm 全局安装时因为权限不足写入失败。另外 Windows 自带的命令提示符对终端交互的支持比较弱我实测下来用 Windows Terminal 搭配 PowerShell 7 体验最好字体渲染、快捷键、以及 Codex 的交互式界面都正常。macOS 和 Linux 这边相对简单但有一个点要特别注意如果你习惯用系统自带的旧版 Node.js比如某些 Linux 发行版自带的 16 以下版本必须升级。因为 Codex CLI 用到了很多新语法和 API老版本 Node 会直接跑不起来报错信息还特别隐晦容易让人误以为是软件本身的问题。另外无论哪个平台装完 Node.js 后建议都重启一下终端。这不是玄学而是新安装的 Node 可能还没有刷新到当前终端会话的 PATH 环境变量里不重启的话node -v还是旧版本甚至提示找不到。2.3 一个小技巧给 npm 换个可靠的全局目录Linux 和 macOS 上如果遇到 npm 全局安装权限问题很多人会直接加sudo但这样做容易把全局目录的属主搞乱以后升级包会很麻烦。更干净的做法是把 npm 的全局目录改到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后在~/.bashrc或~/.zshrc里加一行export PATH~/.npm-global/bin:$PATH配好之后source一下再执行npm install -g就不需要 sudo 了干净又安全。这一步虽然不是必须的但能省掉后面很多权限相关的坑。3. Codex CLI 安装与认证两条路径把命令行跑起来3.1 npm 全局安装 Codex环境没问题之后安装 Codex CLI 本身非常简单就是一条 npm 命令npm install -g openai/codex装完之后验证一下版本codex --version正常情况下会输出一个版本号。如果提示codex 不是内部或外部命令大概率是 npm 全局安装目录没在 PATH 里。Windows 用户去检查%APPDATA%\npm有没有加到系统环境变量macOS/Linux 用户检查上一步配的~/.npm-global/bin。安装过程还有一个不那么起眼但很关键的细节npm 包名是openai/codex中间有斜杠属于 scoped package。有些老教程让你装codex那可能是别的项目别搞混了。装完之后运行codex第一次启动会进入交互式界面如果没有登录它会提示先认证。3.2 登录 OpenAI 账号的方式Codex CLI 提供两种认证方式一种是codex login会打开浏览器让你登录 OpenAI 账号授权另一种是直接配置 API Key。前者适合有 OpenAI 账号、用官方模型的用户后者适合走第三方 API 的用户。codex login的原理是本地启动一个回调服务浏览器授权之后把令牌写回本地的配置里。实际操作时要注意如果到时候终端提示“登录超时”或者“授权回调失败”可以先检查本机默认浏览器是否正常、防火墙有没有拦截本地端口。有些环境下终端会自动打开浏览器如果没弹出来也可能会出现一个链接手动复制到浏览器里打开一样能完成授权。登录成功之后你可以运行codex进交互界面试试输入一句简单的指令比如“写一个快速排序函数”观察它能不能正常响应。这一步通过说明 CLI 和官方服务的链路是通的。3.3 使用 API Key 认证但如果你和我一样要用 DeepSeek 或者其他兼容服务直接配置 API Key 更干脆。Codex CLI 支持从环境变量里读取 API Keyexport DEEPSEEK_API_KEYsk-xxx这里环境变量的名字不是随便取的它要和配置文件里 provider 定义的env_key对应。后面讲 config.toml 时我会详细说现在你只需要记住env_key告诉 Codex“去读哪个环境变量拿 Key”。设置环境变量的方式按平台来。Windows PowerShell 用$env:DEEPSEEK_API_KEYsk-xxxmacOS/Linux 用export。不过终端里export只对当前会话有效为了持久化建议写到 shell 配置文件里。API Key 属于敏感信息代码仓库里千万别提交配置文件里也不要硬编码。3.4 验证安装跑一个最小任务认证配置好之后建议用一个最小任务验证整条链路。比如在任意空目录下运行codex exec 使用 Python 创建一个 hello.py内容为打印 Hello Codexexec参数是 Codex CLI 的非交互模式直接执行单条指令并退出非常适合做自动化验证。如果能看到它创建了文件并且文件内容正确说明安装、认证、模型调用全部正常。如果这一步就报错先别急着往下配别的大概率是认证信息没生效或者网络链路有问题。可以运行codex login status看看当前认证状态再检查环境变量里 Key 是否真的存在、有没有拼写错误。4. 本地模型接入Ollama 与 LM Studio 的完整配置4.1 为什么要把 Codex 接到本地模型把 Codex 接到本地模型最直接的理由是隐私和成本。某些项目代码涉及客户敏感信息不能发到云端这时候本地模型几乎是唯一选择。另外本地模型不按 token 计费你反复让 Codex 改代码、跑测试、生成日志都不会产生费用可以放开手脚折腾。代价也很明显本地模型的能力上限和云端旗舰模型有差距尤其是复杂架构设计、跨文件大规模重构这些任务本地小参数模型会显得“智商不够”。所以我的建议是本地模型适合做日常的代码补全、格式化、单元测试、简单脚本生成复杂任务还是切回云端模型。本地模型服务的原理其实很简单就是在本机起一个 OpenAI 兼容的 HTTP 服务Codex 把请求发给localhost的某个端口本地服务加载模型处理之后返回结果。所以对你来说只要把本地推理框架装好、模型拉好、服务跑起来Codex 这边的配置和接第三方 API 几乎一样。4.2 Ollama 安装与模型拉取Ollama 是目前最流行的本地模型运行工具它对硬件要求相对友好安装也简单。Windows 和 macOS 用户直接去官网下载安装包Linux 用户运行安装脚本curl -fsSL https://ollama.com/install.sh | sh装好之后确认服务状态ollama serve这个命令会启动 Ollama 的后台服务默认监听11434端口。然后拉取模型比如拉一个代码能力比较均衡的模型ollama pull qwen2.5-coder:7b拉取完成后就可以测试了。如果你需要本地部署 DeepSeekOllama 里也有相关模型可选ollama pull deepseek-r1:7b拉取deepseek-r1:7b或者deepseek-coder系列都行具体看你的显存。实测下来16GB 内存的 Mac 跑 7B 模型没问题14B 会比较吃力32GB 内存可以尝试更高参数量的版本。4.3 在 Codex 中配置 Ollama 提供商回到 Codex 这边要把 Ollama 配置成一个模型提供商。编辑~/.codex/config.toml添加如下内容model qwen2.5-coder:7b model_provider ollama [model_providers.ollama] name Ollama base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api chat这里最关键的字段是wire_api chat。Codex CLI 默认会尝试调用 OpenAI 的/responses接口但 Ollama 并没有实现这个接口它兼容的是/v1/chat/completions。设置为chat之后Codex 会改用 Chat Completions 协议去请求这样才能通。env_key这里填OLLAMA_API_KEY但 Ollama 本身不需要 Key所以这个环境变量不设置也没关系。只要base_url指向的地址是对的Ollama 就能接收到请求并返回结果。配置好之后在项目目录里运行codex exec 解释一下当前目录下的代码结构如果正常返回说明本地链路已经通了。一个小细节第一次请求会有点慢因为模型要加载进内存之后会快不少。4.4 LM Studio 的接入方式LM Studio 是另一个常用的本地模型运行工具它的优势是带图形界面模型下载、管理、参数调整都可视化适合不太习惯纯命令行操作的开发者。LM Studio 默认在1234端口提供 OpenAI 兼容服务接入 Codex 也很简单model qwen2.5-coder-7b-instruct model_provider lmstudio [model_providers.lmstudio] name LM Studio base_url http://localhost:1234/v1 env_key LMSTUDIO_API_KEY wire_api chat使用 LM Studio 时记得在它的开发者界面上点一下“Start Server”把本地服务真正跑起来否则 Codex 会连接不上。另外LM Studio 里同一个模型可能有不同的量化版本比如 GGUF 的 Q4_K_M、Q5_K_M模型名要去它的模型库页面确认准确无误填错了 Codex 会报模型不存在。4.5 本地模型怎么选本地模型的选择直接决定 Codex 的实际体验。跑过一圈之后我大概整理了一个参考表格目标场景推荐模型参数量硬件建议纯代码补全/生成qwen2.5-coder7B16GB 内存/8GB 显存通用对话代码混合llama3.18B16GB 内存复杂推理/数学deepseek-r17B/14B32GB 内存/12GB 显存轻量快速响应qwen2.5-coder3B8GB 内存给新手的建议是别贪大。7B 模型在大多数消费级硬件上都能流畅运行响应速度也跟得上你要是硬上 70B等待时间会严重拉低效率反而不如用云端 API。5. API 集成实战用 config.toml 对接 OpenAI 兼容服务5.1 config.toml 的完整拆解很多人的本地部署卡在配置上不是配不进去而是不知道每个字段是什么意思。我把 config.toml 里常见的关键字段完整拆开讲一遍。model设置默认使用的模型 ID它会作用于所有没单独指定模型的 provider。model_provider告诉 Codex 当前默认走哪个 provider这个值必须和下方[model_providers.xxx]的小节名对应。接着是model_reasoning_effort控制推理强度有 minimal、low、medium、high 几个档位日常用 medium 就够高难任务临时切 high。approval_policy控制命令审批策略。默认是通知你审批但如果你在无人工干预的 CI 环境里跑可以设置为on-failure甚至never让 Codex 全自动执行命令。注意安全生产环境慎用无审批模式。最后是[model_providers.xxx]小节每个 provider 要配置name、base_url、env_key和wire_api。base_url是模型服务的地址env_key是 API Key 对应的环境变量名wire_api有两种取值responses和chat前者是 OpenAI 新协议后者是更通用的 Chat Completions 协议第三方服务基本都用chat。5.2 接入 DeepSeek API 的完整例子我自己的主力配置就是 Codex 接 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_KEYsk-你的keyDeepSeek 有两种模型deepseek-chat对应通用对话模型deepseek-reasoner对应推理增强模型。日常编码用前者响应更快复杂架构推导可以临时切到后者。想切换模型时在交互界面里输入/model或者对应的模型选择命令就能换。这里要注意几个坑。第一DeepSeek 的base_url结尾要带/v1不带的话有些 SDK 会拼出错误的路径。第二DeepSeek 官方文档里的接口示例可能用的是它自己的 SDK但 Codex 走的是 OpenAI 兼容协议所以只认base_url、model和env_key这三个关键信息其他别多配。第三如果请求时返回认证错误先确认环境变量名和env_key是不是一致再确认 Key 有没有复制完整。5.3 接入团队内部统一推理服务还有一种场景是团队内部已经有统一的大模型推理网关比如基于 vLLM 或 One API 搭的内部服务所有人都通过同一个地址拿模型能力。这种服务通常也提供 OpenAI 兼容接口配置方式和上面完全一样只是要把base_url换成内网地址[model_providers.internal] name Internal LLM Gateway base_url http://192.168.1.100:8000/v1 env_key INTERNAL_API_KEY wire_api chat接入内部服务时务必先确认客户端网络能访问到那个内网地址和端口。用 curl 测一下就知道了curl http://192.168.1.100:8000/v1/models -H Authorization: Bearer $INTERNAL_API_KEY如果返回了一堆模型列表说明服务可达、协议正常。这一步能帮你把“Codex 配置问题”和“网络问题”快速区分开。5.4 多 Provider 切换与效率提升在我的 config.toml 里同时保留了官方、DeepSeek、Ollama 三个 provider。日常写代码用 DeepSeek写敏感脚本切到本地 Ollama需要顶级代码理解能力时切到官方模型。交互式使用中Codex 提供了模型切换的入口输入/model就能看到当前可用的模型列表上下键选择即可。这个效率非常高不用每次改配置文件再重启。还有一个提升效率的小技巧就是给不同项目准备不同的配置文件。cd到项目目录后可以把 config.toml 放到项目根目录的.codex文件夹里这样 Codex 会优先读取项目级配置。内网项目就强制走内部服务开源项目就走第三方 API互不干扰。6. 高频报错排查我踩过的坑和最终解法6.1 安装阶段npm 卡住、Windows 安装未完成npm install -g openai/codex卡住是很多人的第一个坎。最典型的两种原因网络问题导致下载慢以及 npm 缓存损坏。先解决网络问题把 npm 源切到镜像npm config set registry https://registry.npmmirror.com如果已经卡住了先 CtrlC 中断然后清理 npm 缓存再重试npm cache clean --forceWindows 上还有一种情况安装过程提示“未完成”或者报权限错误。这多半是因为当前 PowerShell 没有以管理员身份运行导致 npm 不能往系统目录写入文件。解决方法是关闭终端右键“以管理员身份运行”再执行安装命令。装完之后退出管理员模式用普通终端使用即可。另外提醒一句Windows 上安装完 Codex 之后codex命令可能要新开一个终端窗口才能识别因为 PATH 环境变量的刷新需要新进程。如果新终端里还是找不到命令检查一下%APPDATA%\npm是否在系统 PATH 里。6.2 启动阶段codex 打不开、一直转圈codex命令执行后没有反应或者界面一直卡在加载状态大概率是认证或网络问题。先看认证状态codex login status如果是未认证重新执行codex login。已经认证但还是转圈那就要检查网络链路是否能正常访问模型服务的base_url。一个通用的检测方法是curl -I https://api.deepseek.com如果这个请求不通说明本机到服务端的网络有问题先解决网络如果通了再看配置文件里的base_url是不是写错了比如多了空格、少写了/v1。还有一种情况是“codex 正在重新连接”这通常出现在交互会话中网络闪断或者本地推理服务重启之后。处理办法比较简单在交互界面里输入/quit退出重新运行codex一般就能恢复。如果频繁出现这个问题检查本地服务的稳定性以及是否是长时间空闲导致连接被服务端断开。6.3 本地端点和响应异常切换 provider 后请求失败这是我遇到过最隐蔽的一类问题。表现是配置好本地模型后启动 Codex 请求本地服务时报错核心信息类似“cc switch local proxy failed while handling codex endpoint /responses”翻译过来就是在切换到本地 provider 后Codex 请求/responses这个端点时失败。这个报错的根因90% 是wire_api没有设置成chat。前面说过Codex 默认用 OpenAI 新的 Responses 协议而 Ollama、LM Studio 这些本地服务只实现了旧的 Chat Completions 协议。你请求一个不存在的端点服务端自然返回失败。解决方式很简单在 provider 配置里显式加上wire_api chat另外 10% 的情况是本地推理服务没启动或者端口不对。Ollama 默认是11434LM Studio 是1234如果改了默认端口base_url要同步改。排查时先确认服务正常curl http://localhost:11434/v1/models能返回模型列表再回过来检查 Codex 配置。6.4 模型不支持与响应异常还有一类报错是模型相关的比如提示“model is not supported”字面意思就是模型不被支持。出现这个报错说明 Codex 把请求发出去了但是服务端不认你传的模型 ID。常见原因有三种模型 ID 拼写错误使用了当前 provider 没有部署的模型模型 ID 对 Codex 协议的支持不完整。撕开来看比如你在 config.toml 里把 model 写成了一个不存在的 ID或者从别处复制了一个已经下线的模型名服务端就会拒绝。解决方法是去服务提供方的模型列表页面确认准确的模型 ID再核对 config.toml 里的model字段。如果模型 ID 没问题但响应内容异常比如返回的全是空内容、乱码、或者报了超时这时候优先怀疑模型本身的参数量太大、推理速度太慢。调小模型参数量或者把model_reasoning_effort调低一档很多响应异常其实是因为单次推理耗时太长触发了上层超时。6.5 高频问题排查速查表问题现象可能原因解决方法npm 安装卡住网络慢/缓存损坏切换 npm 镜像源清缓存重试codex 命令找不到PATH 未配置/未刷新检查全局安装路径重启终端Windows 安装未完成权限不足用管理员 PowerShell 安装一直转圈/正在重新连接认证失效/网络不通检查 login statuscurl 测试 base_url本地端点请求失败wire_api 未设置/服务未启动加wire_api chat检查服务状态model not supported模型 ID 错误/协议不支持核对模型 ID调整 provider响应超时/空内容模型过大/推理强度过高换小模型调低 reasoning effort这些坑我全部踩过一遍现在回看80% 的报错都能在配置文件和网络链路上找到答案。最后再分享一点个人体会本地部署 Codex 这件事真正难的并不是安装那一步而是搞清楚“CLI、配置文件、模型服务”这三者之间的关系。一旦你理解了 Codex 只是个壳子真正干活的是背后的模型服务绝大多数配置问题都能迎刃而解。我建议你部署完成之后先把配置文件里的 provider 逐个手动切换一遍每个都跑一个最小任务彻底摸清它们的区别。之后再遇到报错你就能像剥洋葱一样先看网络、再看配置、最后看模型几分钟内定位问题。