AI工具

Codex 本地大模型接入 Ollama 常见报错：排查顺序、原因和修复方法

整理 Codex 本地大模型接入 Ollama 时的常见报错和排查方法，覆盖 --oss、--local-provider ollama、Ollama 服务、模型名称、localhost、WSL、Windows、配置文件和性能问题。

Codex 本地大模型接入 Ollama 时，最常见的问题不是模型真的不能用，而是入口、服务、模型名和运行环境没有对齐。比如 Ollama 没启动，模型没有 pull，Codex 没有走本地 provider，或者在 WSL、Docker、远程终端里把 localhost 理解错了。

这篇按报错排查型来整理。你可以先确认最小链路，再根据具体错误往下查。建议先用命令行跑通，再写进长期配置。这样出错时更容易判断是 Codex 配置问题、Ollama 服务问题，还是本地模型本身能力或性能问题。

先确认正确接入方式

Codex CLI 当前有本地开源模型入口。临时使用 Ollama 时，可以从这个命令开始：

1

codex --oss --local-provider ollama -m qwen2.5-coder:7b

这里的含义是：

  • --oss：使用本地开源模型 provider。
  • --local-provider ollama：明确选择 Ollama。
  • -m qwen2.5-coder:7b：指定 Ollama 里已经存在的模型名。

如果你还没有下载模型，先执行：

1

ollama pull qwen2.5-coder:7b

再确认 Ollama 能正常响应：

1

ollama run qwen2.5-coder:7b "用一句话介绍你自己"

只有这一步能跑通，才继续排查 Codex。不要一开始就改 config.toml，否则会把服务问题、模型问题和配置问题混在一起。

最小排查顺序

遇到 Codex 接入 Ollama 报错，建议按这个顺序查：

  1. ollama 命令是否能在当前终端找到。
  2. Ollama 服务是否正在运行。
  3. 模型是否已经 ollama pull。
  4. Codex 命令是否真的使用了 --oss --local-provider ollama。
  5. -m 后面的模型名是否和 ollama list 完全一致。
  6. 当前环境里的 localhost:11434 是否指向 Ollama 所在机器。
  7. Codex 版本是否支持本地 provider 相关参数。
  8. 本地模型是否足够执行代码任务。

前五步解决的是“能不能连上”，后面才是“好不好用”。

报错：找不到 ollama 命令

典型表现：

1
2

ollama: command not found
The term 'ollama' is not recognized

先确认 Ollama 是否安装，以及当前 shell 能不能找到它。

macOS 或 Linux：

1
2

which ollama
ollama --version

Windows PowerShell：

1
2

Get-Command ollama
ollama --version

如果系统里能打开 Ollama 应用，但终端里找不到 ollama，通常是 PATH 没配置好。重启终端、重启 Codex 所在的桌面应用，或者把 Ollama 命令所在目录加入 PATH。

Windows 下还要注意：你在 PowerShell 能找到 ollama，不代表 WSL 里也能找到。Codex 如果运行在 WSL 环境，就要在 WSL 里单独确认命令和服务访问方式。

报错：Ollama 服务没启动

典型表现：

1
2
3

connection refused
failed to connect to Ollama
Could not connect to 127.0.0.1:11434

Ollama 的默认服务端口通常是 11434。先确认服务是否可访问：

1

curl http://127.0.0.1:11434/api/tags

如果失败，先启动 Ollama：

1

ollama serve

有些系统上 Ollama 桌面应用会自动启动服务，有些环境需要手动启动。排查时不要只看应用图标，要直接请求 /api/tags，因为 Codex 需要的是本地 API 服务可用。

如果你看到端口被占用，说明可能已经有一个 Ollama 服务在跑。此时不要反复开多个实例，先确认当前服务是否能列出模型。

报错：model not found

典型表现：

1
2

model not found
pull model first

这通常是模型名不一致。先看本机实际有哪些模型：

1

ollama list

然后把 Codex 的 -m 参数改成列表里完全一致的名称：

1

codex --oss --local-provider ollama -m qwen2.5-coder:7b

常见错误包括：

  • 写成 qwen2.5-coder，但本地实际是 qwen2.5-coder:7b。
  • 复制了别人的模型名，但本机没有 pull。
  • 模型下载到另一台机器，当前机器的 Ollama 里没有。
  • 在 WSL 里访问的是 WSL 内部的 Ollama，而模型在 Windows 宿主机的 Ollama 里。

模型名不要靠记忆写，直接从 ollama list 复制。

报错：Codex 没有走 Ollama

有时你以为 Codex 已经接入 Ollama，但实际仍在使用默认模型或默认 provider。典型表现是本地 Ollama 没有请求日志，或者报错和 Ollama 无关。

先用临时命令强制指定：

1

codex --oss --local-provider ollama -m qwen2.5-coder:7b

如果这条能跑，再考虑写入配置文件。不要同时设置太多项。一个可读的配置可以类似这样：

1
2
3

model_provider = "oss"
oss_provider = "ollama"
model = "qwen2.5-coder:7b"

如果你打开了严格配置检查，旧字段、拼错字段或当前版本不支持的字段可能会导致启动失败。此时先去掉自定义配置，只用命令行参数验证最小链路。

报错：unknown option 或参数不支持

典型表现：

1
2
3

unknown option '--oss'
unknown option '--local-provider'
unexpected argument

这通常说明 Codex CLI 版本较旧，或者你运行的不是预期中的 Codex 命令。

先确认版本和帮助信息：

1
2

codex --version
codex --help

在帮助里搜索 --oss 和 --local-provider。如果没有，先更新 Codex。更新后重新打开终端，再运行：

1

codex --oss --local-provider ollama -m qwen2.5-coder:7b

Windows 下还要确认 codex 命令来自同一个安装位置。有时系统里存在多个 Node/npm 全局路径，终端调用到旧版本，桌面端或 IDE 扩展用的是另一个版本。

报错：localhost 指错地方

localhost 是本地模型排查里最容易误判的点。它永远指“当前进程所在环境的本机”，不一定是你以为的那台机器。

常见场景：

  • Codex 在 Windows 里跑，Ollama 也在 Windows 里跑：127.0.0.1:11434 通常没问题。
  • Codex 在 WSL 里跑，Ollama 在 Windows 宿主机跑：WSL 的 127.0.0.1 不一定能直接访问 Windows 服务。
  • Codex 在 Docker 容器里跑，Ollama 在宿主机跑：容器里的 localhost 指容器自己。
  • Codex 连接远程环境，Ollama 在你的本地电脑：远程环境的 localhost 指远程机器。

排查方法是在 Codex 实际运行的环境里执行：

1

curl http://127.0.0.1:11434/api/tags

如果访问不到，就不要继续改模型名。先把网络地址修好。Docker 场景可以考虑宿主机地址或容器网络服务名；远程场景则要让 Ollama 跑在远程机器上，或者做安全的内网转发。

报错：401、API key 或认证相关错误

Ollama 本地默认调用通常不需要 OpenAI API key。如果接入 Ollama 时出现 OpenAI API key、401、unauthorized 之类错误，说明 Codex 可能没有走本地 provider，或者你的配置仍指向 OpenAI / 代理服务。

先临时清空复杂配置，只保留命令行：

1

codex --oss --local-provider ollama -m qwen2.5-coder:7b

再检查配置文件里是否存在类似自定义 provider：

1

model_provider = "proxy"

或者仍然指定了 OpenAI 相关的 base URL、API key、代理服务。不要把 Ollama 接入写成普通 OpenAI API 代理，除非你明确知道当前 Codex 版本、provider 配置和 Ollama API 兼容层之间的关系。

报错：请求卡住或一直没有响应

典型表现：

1
2
3

waiting for model
request timed out
no response

本地模型慢不等于配置错。先看 Ollama 是否正在加载模型。第一次运行大模型时，加载时间可能比较长，低内存机器还会非常慢。

排查方向：

  • 换小一点的模型测试，例如 7B 级别。
  • 先用 ollama run 单独问一个短问题。
  • 观察 CPU、内存、显存是否打满。
  • 避免一开始就让 Codex 做大型重构。
  • 关闭其他占用显存或内存的程序。

如果 ollama run 本身就很慢，Codex 只会更慢。因为 Codex 任务通常包含更多上下文、更多工具调用和更长输出。

报错：context length exceeded

典型表现：

1
2
3

context length exceeded
prompt too long
input is too large

Codex 做代码任务时，会把项目上下文、指令、文件片段和工具结果放进模型上下文。本地模型的上下文窗口往往比云端强模型更紧张。

处理方法：

  • 缩小任务范围，不要一次让它读整个仓库。
  • 明确指定文件路径。
  • 先让 Codex 做分析，不要立即要求大规模修改。
  • 避免把长日志、长构建输出整段塞给模型。
  • 换上下文更大的本地模型。

本地模型适合小步任务。越是复杂的跨文件改动，越需要拆成多轮。

报错：工具调用不稳定

有些本地模型能聊天，但不擅长稳定执行 Agent 工作流。表现包括：

  • 不按要求调用工具。
  • JSON 或结构化输出格式不稳定。
  • 反复解释，不实际改文件。
  • 忽略系统约束。
  • 对长上下文里的文件关系判断差。

这不是 Ollama 连接错误，而是模型能力问题。可以尝试：

  • 换更偏代码的模型。
  • 降低任务复杂度。
  • 用更明确的指令和文件路径。
  • 一次只做一个小改动。
  • 对关键修改保留人工 review。

本地模型可以降低成本、保护隐私、离线运行，但不一定等价于 Codex 默认推荐模型。尤其是大型仓库理解、复杂调试、多工具协作，本地小模型容易露出短板。

Windows 常见坑

Windows 下排查时，重点看这几件事：

  • PowerShell、CMD、Git Bash、WSL 里的 PATH 可能不同。
  • 桌面应用启动时继承的环境变量不一定和终端一致。
  • Ollama 在 Windows 宿主机，Codex 在 WSL 时，网络地址要单独验证。
  • 防火墙可能拦截 11434 端口。
  • 终端显示中文乱码，不一定代表文件或配置真的乱码。

建议先在 Codex 实际运行的同一个终端里跑：

1
2
3
4

Get-Command ollama
ollama list
curl.exe http://127.0.0.1:11434/api/tags
codex --oss --local-provider ollama -m qwen2.5-coder:7b

四步里哪一步失败，就先修哪一步。

推荐的稳定配置流程

第一次配置时，不要直接追求“永久默认”。按下面顺序来：

  1. 安装 Ollama。
  2. ollama pull 一个中小型代码模型。
  3. 用 ollama run 验证模型能回答。
  4. 用 curl /api/tags 验证服务可访问。
  5. 用 codex --oss --local-provider ollama -m 模型名 临时启动。
  6. 做一个小任务，比如解释单个文件。
  7. 再写入 config.toml。
  8. 最后再尝试更复杂的修改任务。

这样每一步都能回退，不会一边改模型、一边改配置、一边改网络地址。

排查模板

如果你要把问题发给同事或 AI 帮忙排查，建议提供这些信息：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

操作系统：
Codex 版本：
Ollama 版本：
Codex 运行位置：Windows / WSL / macOS / Linux / Docker / 远程机器
Ollama 运行位置：
使用的命令：
模型名：
ollama list 是否能看到模型：
curl http://127.0.0.1:11434/api/tags 是否成功：
完整报错：
最近改过的配置：

有了这些信息，基本可以判断问题在命令、模型、服务、网络还是 Codex 配置。

FAQ

Codex 接入 Ollama 后就完全离线了吗？

如果 Codex 只使用本地 Ollama provider，模型推理可以在本地完成。但是否完全离线，还要看你有没有启用 web search、MCP、插件、远程任务、云端同步或其他外部工具。不要只凭“模型在本地”就认为整个工作流没有网络访问。

可以把 Ollama 当成 OpenAI API base_url 配给 Codex 吗？

不建议作为第一选择。Codex 已经有本地开源模型 provider 入口时，优先用 --oss --local-provider ollama。只有在你明确需要自定义代理、并确认当前版本支持对应 wire API 时，再考虑自定义 provider。

本地模型适合做所有 Codex 任务吗？

不适合。它更适合解释文件、小范围修改、生成脚本、整理文档、简单排错。大型重构、跨仓库理解、复杂测试修复和需要稳定工具调用的任务，对模型能力要求更高。

为什么同一个模型在 Ollama 里能回答，在 Codex 里表现差？

普通聊天只需要回答一段文本。Codex 任务还需要理解仓库、遵守开发约束、选择工具、读取文件、生成补丁、解释测试结果。本地模型能聊天，不代表能稳定完成 Agent 工作。

是否需要给 Codex 配 OpenAI API key？

使用本地 Ollama provider 本身不需要 OpenAI API key。但如果你同时使用 OpenAI 云端模型、云任务、某些插件或外部服务，可能仍然需要相应账号和权限。排查 Ollama 时先把链路简化，避免认证问题混进来。

换模型后需要重启 Codex 吗？

如果只是命令行用 -m 临时指定，通常重新启动这次 Codex 会话即可。如果改了长期配置文件，建议退出当前 Codex 会话后重新进入，避免旧会话继续使用旧配置。

小结

Codex 本地大模型接入 Ollama 的排查重点是分层：先确认 ollama 命令可用，再确认 Ollama 服务可访问，再确认模型已经下载，最后确认 Codex 通过 --oss --local-provider ollama 走到了正确 provider。不要把连接错误、模型名错误、localhost 错误和模型能力问题混在一起。

跑通最小链路后，再考虑长期配置和复杂任务。对本地模型要有合理预期：它能让 Codex 在低成本、低外部依赖的场景里工作，但越复杂的代码任务，越需要更强模型、更小步骤和更严格的人工 review。

© 2022 - 2026 KnightLi的博客
记录并分享
使用 Hugo 构建
主题 Stack 由 Jimmy 设计