Codex CLI 接入 DeepSeek 与 Ollama：从安装配置到排错完整指南

Codex 是 OpenAI 推出的命令行 AI 编程 Agent在终端里启动后它能读取项目结构、自动生成修改方案、执行命令、修改文件甚至完成从需求到提交的完整开发任务。这类工具默认绑定 OpenAI 官方模型对国内开发者来说账号、网络和费用都有一定门槛。好在 Codex CLI 从设计上保留了模型提供方model provider的扩展能力通过修改配置文件就能把底层模型替换为 DeepSeek、本地 Ollama 或者第三方中转模型在普通网络环境下以很低成本获得可用的 Agent 体验。本文会从安装、配置、运行到排错完整走一遍这个过程。1. 先理解 Codex CLI 的模型接入机制为什么能换成 DeepSeek 和 Ollama1.1 Codex CLI 不是只能调用 OpenAImodel provider 的作用Codex CLI 的默认配置指向 OpenAI 官方接口模型也是官方模型。但它的架构不是写死的而是通过配置文件~/.codex/config.toml来声明模型提供方。每个提供方provider包含四个关键信息名称、请求地址、API Key 的环境变量名、请求协议格式。model gpt-5 model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses实际请求时Codex CLI 会把model_providers里配置的base_url作为接口根地址把model作为模型名从env_key指定的环境变量中读取密钥。只要第三方服务提供 OpenAI 兼容接口就能通过这套机制接入。wire_api字段决定 Codex CLI 使用哪种请求格式。responses对应 OpenAI 较新的 Responses APIchat对应更普及的 Chat Completions API。DeepSeek、Ollama、绝大多数中转服务目前都兼容 Chat Completions因此配置时一般写chat。1.2 云端 API、本地模型和中转模型分别适合什么场景三种接入方式各有定位不能简单说谁更好。接入方式典型服务优点缺点适合场景云端官方 APIOpenAI、DeepSeek模型能力强、稳定按量计费、部分服务国内访问有门槛正式开发、需要高质量代码生成时本地模型Ollama Qwen、Llama 等免费、数据不出本机依赖本机算力、大模型推理慢学习体验、离线实验、敏感代码场景中转模型第三方中转服务一次接入多种模型、调用方便服务稳定性依赖第三方、需要自行甄别想用不同模型对比、没有稳定访问国外 API 时1.3 自定义 provider 的字段说明在 config.toml 中新增 provider 时需要正确理解以下字段字段含义示例值容易出错的地方name显示名称仅用于标识DeepSeek名字随意但不能重复base_url接口根地址https://api.deepseek.com/v1漏掉/v1会导致 404env_key保存 API Key 的环境变量名DEEPSEEK_API_KEY只配变量名还不够还要在 shell 中 exportwire_api请求协议chat/responses服务只支持 chat 时写 responses 会报不支持注意配置base_url时到底带不带/v1取决于服务商文档。DeepSeek 官方接口是https://api.deepseek.com它的/v1路径可以兼容Ollama 的 OpenAI 兼容端点则是http://127.0.0.1:11434/v1。2. 安装 Codex CLI 桌面端Node.js、npm 镜像与版本确认2.1 环境准备Codex CLI 是 Node.js 命令行工具先确认本机有 Node.js 和 npm。node --version npm --version建议使用 Node.js 18 或更高版本。版本过老时Codex CLI 安装过程中可能出现语法兼容问题。这里不写死具体版本以 Codex 仓库和 npm 包的实际要求为准。安装前重点确认 npm 源。国内默认从 npm 官方源拉包速度不稳定建议先切换到国内镜像npm config set registry https://registry.npmmirror.com设置完成后可以验证npm config get registry2.2 安装 Codex CLI使用全局安装方式npm install -g openai/codex安装过程中如果长时间卡在下载阶段优先检查 npm 源是否生效而不是反复重试。安装完成后查看命令是否可用codex --version能输出版本号说明安装成功。此时如果直接运行codex它会引导登录 OpenAI 账号。这一步可以暂时跳过因为本文后面的 DeepSeek 和 Ollama 接入方式不依赖 OpenAI 登录。2.3 首次启动时如何处理登录Codex CLI 启动时会判断当前模型提供商。如果使用默认 OpenAI provider则必须先完成 ChatGPT 登录或配置 OpenAI API Key。如果配置文件已经写好了第三方 provider启动时就不用登录Codex 会直接从你指定的环境变量中读取密钥。这是国内开发者能顺利使用 Codex 的关键不登录 OpenAI不访问 OpenAI 控制台只通过配置指定国内可访问的模型服务。3. 接入 DeepSeekOpenAI 兼容 API 的最小配置3.1 准备 DeepSeek API Key在 DeepSeek 开放平台注册账号创建 API Key。创建后页面只会完整显示一次要立即复制保存。DeepSeek API 采用按量计费新用户通常有一定免费额度具体以官网说明为准。API Key 属于敏感凭证不要写进代码仓库也不要直接写进 config.toml。推荐先设置为环境变量export DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxxWindows PowerShell 使用对应语法$env:DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxx3.2 修改 Codex 配置文件编辑~/.codex/config.toml如果目录不存在则先创建。下面是接入 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这里选择deepseek-chat作为默认模型。它对应 DeepSeek-V3 系列适合日常对话和代码生成。如果需要更强的推理能力可以改成deepseek-reasoner但推理模型的响应时间更长费用也可能更高。关键点wire_api chat必须写因为 DeepSeek 的 OpenAI 兼容端点实现的是 Chat Completions 协议。base_url的/v1路径不能随便删Codex 会在后面拼接/chat/completions或/responses。如果希望永久保存 API Key可以把它放在 config.toml 中通过env_key指定也可以在 shell 配置文件中写入 export 命令。3.3 启动 Codex 并验证启动时指定 providercodex --model-provider deepseek进入交互界面后输入一个简单任务验证链路你用 Python 写一个函数读取当前目录下所有 .txt 文件并统计总行数如果配置正确Codex 会进入 Agent 流程先生成实现方案再调用模型生成代码必要时直接修改文件或执行命令。只要模型能返回内容且 Codex 能继续追问就说明 DeepSeek 接入成功。还可以在交互会话中使用/model命令切换同一 provider 下的其他模型比如在deepseek-chat和deepseek-reasoner之间切换。3.4 这一节最常见的坑错误现象常见原因解决方式请求返回 404base_url 缺少/v1改成https://api.deepseek.com/v1提示模型不存在模型名拼写错误使用官方文档中的deepseek-chat或deepseek-reasoner提示缺少 API Key环境变量没有 export确认 shell 中已设置DEEPSEEK_API_KEY并重新打开终端请求报协议不支持wire_api 写成 responses改为wire_api chat4. 接入本地 Ollama不依赖外部服务的 Agent 体验4.1 安装 Ollama 并下载模型Ollama 是本地模型运行工具安装后可以把 Qwen、Llama、DeepSeek 等开源模型跑在本机。Codex CLI 通过 Ollama 提供的 OpenAI 兼容接口访问本地模型整个过程不经过外部 API。Ollama 官方下载速度不稳定时可以尝试从 GitHub Releases 获取安装包或者使用其他国内镜像加速方式。模型拉取变慢也常见通常是因为默认下载源带宽有限。实际工程中建议先确认磁盘空间再选择合适大小的模型。安装完成后启动 Ollama 服务并拉取一个模型ollama pull qwen3:8b拉取结束后查看本机已有模型ollama list输出类似NAME ID SIZE MODIFIED qwen3:8b 8d6d2cbb7a3e 5.5 GB About a minute ago这里输出的模型名就是 Codex 配置中要填写的model值。4.2 验证 Ollama 的 OpenAI 兼容接口Ollama 默认监听127.0.0.1:11434。先用 curl 检查接口是否可用curl http://127.0.0.1:11434/v1/models如果返回包含模型列表的 JSON说明兼容接口正常。如果请求失败排查 Ollama 服务是否启动端口是否被占用。4.3 配置 Ollama provider在~/.codex/config.toml增加以下内容model qwen3:8b model_provider ollama [model_providers.ollama] name Ollama Local base_url http://127.0.0.1:11434/v1 env_key OLLAMA_API_KEY wire_api chat本地模型不需要真实密钥但 Codex 会读取env_key指向的环境变量。如果该变量不存在Codex 可能提示缺少 API Key。解决办法是设置一个非空占位值export OLLAMA_API_KEYollama然后启动codex --model-provider ollama4.4 本地模型在 Codex 里的表现与限制本地模型体验和云端模型有明显区别响应速度取决于 CPU/GPU8B 级别模型在纯 CPU 环境中可能比较慢。代码生成能力弱于 DeepSeek 和 GPT 系列复杂项目理解能力有限。完全离线不会把代码片段发送到外部服务适合敏感环境。不需要网络也不会因为外部接口波动而失败。学习阶段建议从 4B 或 8B 模型开始先把链路跑通再根据本机算力调整模型大小。4.5 本地接入的常见坑问题现象常见原因检查方式处理建议Codex 连接不上 OllamaOllama 服务未启动ollama serve或任务管理器检查进程先启动 Ollama 再启动 Codex返回 404base_url 写错检查端口和路径使用http://127.0.0.1:11434/v1模型名不存在模型没有拉取完成ollama list查看真实名称重新 pull 或用已有模型名推理很慢模型过大或 CPU 推理查看资源占用换更小模型比如qwen3:4b缺少 API Key 报错本地模型没有真实密钥检查环境变量设置OLLAMA_API_KEYollama占位5. 通过中转模型接入更多模型并用 CC Switch 管理切换5.1 中转模型是什么中转模型通常指第三方模型服务商提供的中转接口。这类服务会把多家模型统一成 OpenAI 兼容格式用户只需要一个 API Key 和一个 base_url就能访问多种模型。中转服务的优势是接入简单不用分别注册多个平台劣势是服务稳定性依赖第三方模型版本、价格和接口策略都可能变化。选择中转服务时要自行确认服务方是否合规、稳定避免把重要代码发给不可信的服务。5.2 手动配置中转 provider中转服务的具体 base_url、模型名、API Key 都由服务商提供。配置结构是一样的model gpt-4o-mini model_provider relay [model_providers.relay] name My Relay base_url https://your-relay.example.com/v1 env_key RELAY_API_KEY wire_api chatwire_api要优先看中转服务商文档。大多数中转实现 Chat Completions但也有部分宣称支持 Responses 协议。如果请求失败或返回仅支持chat的报错就改成chat。5.3 CC Switch 的核心作用CC Switch 是社区里的 Codex 配置切换工具。它解决的问题是当你有 DeepSeek、Ollama、多个中转服务时每次改 config.toml 都很麻烦。CC Switch 可以在界面上维护多套 provider 配置一键切换当前生效的模型。这类工具通常会自动写入~/.codex/config.toml并在切换时重启或触发 Codex 重新读取配置。具体界面和命令以项目 README 为准本文不展开操作细节只讲清原理。5.4 切换 provider 时本地转发失败的处理思路使用 CC Switch 类工具时有一个典型报错切换 provider 后Codex 请求失败错误信息提示本地转发服务启动失败同时指出请求到达的是/responses接口并带上 provider 名称。这个场景背后通常有三种原因CC Switch 的本地转发服务没有正常启动Codex 请求访问不到本机监听端口。当前 provider 的模型名不被 Codex 支持Codex 尝试用默认的 responses 协议请求服务端不支持。配置文件被覆盖base_url 或 env_key 指向了不可用的服务。排查顺序如下先看 CC Switch 的本地服务进程是否存在。检查本机端口监听情况确认转发服务端口是否正常。查看 config.toml 当前 provider 的实际内容确认 base_url 和模型名没有被工具改错。不启动 CC Switch直接用命令行指定 provider绕过工具排查codex --model-provider relay如果绕过 CC Switch 后正常问题就在工具本身如果仍然失败问题在 provider 配置。6. 常见错误排查链路从现象定位到根因6.1 网络连接失败或超时现象Codex 启动后卡住随后提示无法连接。检查顺序确认 base_url 是否可达用 curl 直接测试接口。检查系统环境变量中是否有会改变请求路径的配置比如 HTTP 相关环境变量被设置到某个不可达地址。确认代码项目目录是否在网络映射盘或特殊权限目录中Codex 执行命令时可能受目录权限影响。curl -I https://api.deepseek.com/v16.2 模型名不支持the ... model is not supported when using codex现象启动 Codex 时直接报错提到某个模型名不支持。例如the gpt-5.6-sol model is not supported when using codex with a provider...这个错误说明 Codex 对模型名做了校验或者当前 provider 的协议能力与 Codex 期望不匹配。处理方式使用该 provider 官方文档明确支持的模型名不要随意使用奇怪的别名。检查wire_api是否设置正确。中转服务只支持 chat 时Codex 内部如果走了 responses 流程就会因为模型能力不匹配报错。升级 Codex 版本部分模型名校验在旧版本中更严格。6.3 缺少 API Key现象Codex 提示找不到 API Key。排查确认 config.toml 里env_key写的变量名正确。确认环境变量已经 export并且新开了终端让变量生效。本地 Ollama 场景需要设置一个非空占位值不能留空。6.4 Ollama 服务正常但 Codex 请求失败现象curl 接口正常Codex 仍然失败。可能原因Ollama 和 Codex 运行在不同网络命名空间比如 WSL 访问 Windows 本机端口时127.0.0.1指向不同。模型没有完全加载第一次请求需要等待。Ollama 版本过老OpenAI 兼容接口存在兼容性问题。处理方式先升级 Ollama 到最新版本再检查网络地址。WSL 场景需要把 base_url 改成宿主机 IP 或使用host.docker.internal这类特殊地址。6.5 错误排查速查表错误现象根因方向首选检查项404路径不正确base_url 是否缺少/v1401/403密钥无效或未设置env_key 和真实 Key 是否匹配模型名不支持模型不在白名单检查 provider 文档确认模型名连接失败服务不可达或环境变量影响curl 测试接口本地模型无响应资源不足或服务未启动ollama list 和端口监听7. 从学习环境到生产环境配置安全与管理建议7.1 不要把 config.toml 提交到 Git.codex目录下的配置文件可能包含敏感信息。即使没有直接写 API Keyenv_key字段也会暴露你正在使用的服务商。建议把~/.codex/目录加入 Git 忽略规则并在团队项目中统一用环境变量注入密钥。.codex/7.2 用环境变量分层管理密钥不同项目可以使用不同的 API Key实现成本隔离和权限控制。启动 Codex 前先设置当前项目所需变量export DEEPSEEK_API_KEY$(cat ~/.secrets/deepseek.key) codex --model-provider deepseek这样可以把密钥从配置文件中剥离降低泄露风险。7.3 生产环境还要关注日志、权限和成本学习环境只要跑通即可生产环境还需要额外考虑日志Codex 执行命令时会修改项目文件生产场景建议在单独分支或容器中运行避免误改线上代码。权限不要给 Codex 提供过大的文件系统权限限定在项目目录内更安全。成本云端模型按 token 计费长对话或大仓库扫描会快速消耗额度。建议设置模型用量提醒并定期清理历史会话。更新Codex 和 Ollama 迭代较快每次升级后重新验证一次配置防止字段变动导致原配置失效。7.4 可复用的接入检查清单每次新增模型服务商按照下面清单确认可以避免大部分问题服务商的 OpenAI 兼容接口地址是什么是否包含/v1。服务商支持chat还是responses协议。官方推荐的模型名是什么是否带版本后缀。API Key 已经设置为环境变量且终端已刷新。在 config.toml 中新增了独立的 provider 段落。用curl先测通接口再启动 Codex。以codex --model-provider provider启动验证。会话中用/model切换模型确认可用。检查配置文件中没有明文 API Key。升级 Codex 或模型服务版本后重新跑一次最小验证任务。这套流程既适用于 DeepSeek也适用于任何 OpenAI 兼容服务。Codex 的扩展能力决定了接入方式高度统一真正需要花时间理解的是 base_url、wire_api、模型名和密钥管理这四个部分。把这几块搞清楚之后无论是接 DeepSeek、本地 Ollama还是任何中转模型都只是换一套参数的问题。