Codex CLI本地部署实战：模型接入与配置指南

最近一个月我把 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.com

2.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 Key：

export DEEPSEEK_API_KEY="sk-xxx"

这里环境变量的名字不是随便取的，它要和配置文件里 provider 定义的env_key对应。后面讲 config.toml 时我会详细说，现在你只需要记住：env_key告诉 Codex“去读哪个环境变量拿 Key”。

设置环境变量的方式按平台来。Windows PowerShell 用$env:DEEPSEEK_API_KEY="sk-xxx"；macOS/Linux 用export。不过终端里export只对当前会话有效，为了持久化，建议写到 shell 配置文件里。API Key 属于敏感信息，代码仓库里千万别提交，配置文件里也不要硬编码。

3.4 验证安装：跑一个最小任务

认证配置好之后，建议用一个最小任务验证整条链路。比如在任意空目录下运行：

codex exec "使用 Python 创建一个 hello.py，内容为打印 Hello Codex"

exec参数是 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

拉取完成后就可以测试了。如果你需要本地部署 DeepSeek，Ollama 里也有相关模型可选：

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 的实际体验。跑过一圈之后，我大概整理了一个参考表格：

给新手的建议是别贪大。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_KEY="sk-你的key"

DeepSeek 有两种模型，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

如果已经卡住了，先 Ctrl+C 中断，然后清理 npm 缓存再重试：

npm cache clean --force

Windows 上还有一种情况，安装过程提示“未完成”或者报权限错误。这多半是因为当前 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 默认是11434，LM 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 高频问题排查速查表

这些坑我全部踩过一遍，现在回看，80% 的报错都能在配置文件和网络链路上找到答案。

最后再分享一点个人体会：本地部署 Codex 这件事，真正难的并不是安装那一步，而是搞清楚“CLI、配置文件、模型服务”这三者之间的关系。一旦你理解了 Codex 只是个壳子，真正干活的是背后的模型服务，绝大多数配置问题都能迎刃而解。我建议你部署完成之后，先把配置文件里的 provider 逐个手动切换一遍，每个都跑一个最小任务，彻底摸清它们的区别。之后再遇到报错，你就能像剥洋葱一样，先看网络、再看配置、最后看模型，几分钟内定位问题。