AI工具

Codex 本地大模型接入 Ollama 常见报错：教程、排障和 FAQ

整理 Codex 接入 Ollama 本地大模型的配置步骤、常见报错和 FAQ，覆盖模型未找到、连接失败、上下文不足、输出质量差、Windows/WSL 访问等排障场景。

Codex 能接入本地大模型以后，很多人第一反应是：终于可以把一部分代码任务放到 Ollama 上跑，省额度，也能处理更私有的本地项目。但真正上手时，常见情况是命令能跑、模型也装了，Codex 还是连不上，或者连上以后输出质量很差。

这篇按“教程 + 排障 + FAQ”写，目标不是证明本地模型能完全替代云端模型，而是帮你先把 Codex 和 Ollama 跑通，再判断哪些任务适合交给本地模型。

适合用本地模型做什么

接入 Ollama 后，本地模型更适合这些任务：

  • 阅读小型代码片段。
  • 生成脚本草稿。
  • 改写 README、注释和配置说明。
  • 做简单代码解释。
  • 处理不方便上传到云端的私有文本。
  • 在额度紧张时承担低风险辅助任务。

它不太适合直接承担复杂重构、大型代码库推理、安全敏感修改和长任务自动执行。尤其是 7B、8B、14B 这类消费级模型，能力和稳定性通常不能按 Claude、GPT 或 Gemini 的水平预期。

第一步：确认 Ollama 正常工作

先不要急着改 Codex 配置。先确认 Ollama 自己能跑。

安装后查看版本：

1

ollama --version

拉取一个适合代码任务的模型：

1

ollama pull qwen2.5-coder:7b

运行一次对话：

1

ollama run qwen2.5-coder:7b

如果这一步都失败，问题还不在 Codex，而是在 Ollama 安装、模型下载、显存、网络或系统权限。

第二步：确认 Ollama API 可访问

Codex 接入本地模型时，通常需要访问 Ollama 的 HTTP API。默认地址一般是：

1

http://localhost:11434

可以先用 curl 测试：

1

curl http://localhost:11434/api/tags

能看到模型列表，说明 Ollama 服务在运行。Windows PowerShell 可以用：

1

Invoke-RestMethod http://localhost:11434/api/tags

如果这里访问失败，先处理服务问题，不要继续调 Codex。

第三步：在 Codex 中配置本地模型

不同 Codex 版本的本地模型配置入口可能不同，但排障思路是一致的：让 Codex 使用 OpenAI 兼容接口或本地模型提供方，并把基础地址指到 Ollama。

需要确认三件事：

  • base_url 或类似字段指向 http://localhost:11434。
  • 模型名和 ollama list 里显示的名字完全一致。
  • 如果走 OpenAI 兼容接口，要确认路径和协议是否匹配。

很多报错不是模型能力问题，而是模型名多了一个后缀、地址少了端口、或者 Windows 和 WSL 对 localhost 的理解不同。

推荐的最小测试

配置完成后，先让 Codex 做一个低风险任务：

1

请解释当前目录下 README.md 的主要内容，不要修改文件。

或者：

1

请查看这个函数，指出可能的边界条件，不要直接改代码。

不要一上来就让本地模型执行大规模重构。先测读取、理解和简短输出，再逐步测试小修改。

常见报错：connection refused

典型表现：

1
2
3

connection refused
failed to connect
ECONNREFUSED 127.0.0.1:11434

常见原因：

  • Ollama 没有启动。
  • 端口不是 11434。
  • Codex 在 WSL、容器或远程环境里运行，访问不到 Windows 主机的 localhost。
  • 防火墙或代理拦截了本地端口。

排查顺序：

  1. 在同一个终端里运行 curl http://localhost:11434/api/tags。
  2. 确认 ollama serve 或 Ollama 桌面服务正在运行。
  3. 如果 Codex 在 WSL 里，尝试用 Windows 主机 IP 替代 localhost。
  4. 临时关闭代理环境变量，再测试一次。

如果 curl 也失败，先修 Ollama 服务。如果 curl 成功但 Codex 失败，再看 Codex 的配置地址。

常见报错：model not found

典型表现：

1
2
3

model not found
unknown model
pull model manifest: file does not exist

先查看本地模型名：

1

ollama list

注意模型名要完整匹配。例如你本地只有：

1

qwen2.5-coder:7b

配置里写成 qwen2.5-coder、qwen-coder 或 qwen2.5-coder:latest，都可能找不到。

解决方法：

1

ollama pull qwen2.5-coder:7b

然后把 Codex 里的模型名改成完全一致的 qwen2.5-coder:7b。

常见报错：404 或接口路径不对

如果 Codex 走的是 OpenAI 兼容接口，而你直接把地址指到 Ollama 原生 API，有时会出现 404、路径不匹配或响应格式不对。

需要区分两类接口：

1
2
3
4
5

Ollama 原生接口：
http://localhost:11434/api/chat

OpenAI 兼容接口：
http://localhost:11434/v1/chat/completions

如果你的 Codex 配置要求 OpenAI 兼容接口，通常应该把基础地址写成类似：

1

http://localhost:11434/v1

而不是：

1

http://localhost:11434/api

遇到 404 时，优先检查 base URL 和接口模式是否匹配。

常见报错：context length exceeded

典型表现：

1
2
3

context length exceeded
prompt is too long
input exceeds context window

本地模型的上下文窗口通常比云端大模型更紧张。Codex 读取代码库、历史对话和工具输出后，很容易超过限制。

解决方法：

  • 缩小任务范围，只让 Codex 看相关文件。
  • 先让它总结目录，再指定要改的文件。
  • 避免一次塞入完整日志、完整依赖树和大段生成文件。
  • 换上下文更大的模型。
  • 对长文件先做人工裁剪或分段处理。

如果任务是大型重构，本地模型不一定合适。可以让本地模型做辅助分析，把最终修改交给更强模型。

常见问题：输出质量很差

本地模型接上后能回答，但答得乱、改错文件、命令瞎编，通常有几个原因：

  • 模型太小，不适合代码任务。
  • 没有使用代码专用模型。
  • 上下文给得太宽，模型抓不住重点。
  • 温度或采样参数太激进。
  • Codex 的任务描述过于开放。

改进方法：

1

只阅读 src/api/user.ts，找出可能的空值问题。不要修改文件，只列出发现。

比下面这种更适合本地模型：

1

帮我优化整个项目。

本地模型需要更窄、更明确的任务边界。你越把问题切小，它越稳定。

常见问题：速度很慢

速度慢一般和三件事有关：

  • 模型参数量太大。
  • 没有使用 GPU 或显存不足。
  • 上下文太长，prefill 时间过久。

可以先试小模型：

1

ollama pull qwen2.5-coder:7b

如果 7B 能接受，再尝试 14B、32B。不要一开始就拉最大模型。对 Codex 来说，响应稳定和可控比参数量好看更重要。

Windows 和 WSL 的 localhost 问题

这是 Windows 用户最容易踩的坑。

如果 Ollama 跑在 Windows，Codex 跑在 WSL，WSL 里的 localhost 指的是 WSL 自己，不一定能访问 Windows 的 Ollama 服务。

可以在 WSL 中测试：

1

curl http://localhost:11434/api/tags

如果失败，再找 Windows 主机 IP：

1

cat /etc/resolv.conf

里面的 nameserver 地址有时可以作为 Windows 主机地址测试：

1

curl http://<windows-host-ip>:11434/api/tags

如果这样能通，就把 Codex 配置里的 localhost 换成这个地址。还要确认 Ollama 允许从非本机地址访问，否则仍然会被拒绝。

代理环境变量导致的异常

如果你配置了代理，Codex 或终端可能会把本地请求也转发到代理，导致 localhost:11434 访问异常。

检查环境变量：

1
2
3

echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY

Windows PowerShell：

1
2
3

$env:HTTP_PROXY
$env:HTTPS_PROXY
$env:NO_PROXY

建议把本地地址加入 NO_PROXY：

1

localhost,127.0.0.1

如果你在 WSL 或局域网 IP 下访问 Ollama，也把对应 IP 加进去。

什么时候不建议用 Ollama 接 Codex

以下情况不建议强行用本地模型：

  • 要修改生产关键路径。
  • 要跨几十个文件做架构调整。
  • 需要长时间自主执行。
  • 项目测试很少，回滚成本高。
  • 本地模型已经多次误解需求。

更稳妥的做法是：本地模型负责草稿、解释、局部检查，云端强模型负责复杂推理和最终修改。

推荐任务模板

可以把任务写得更像工单：

1
2
3
4
5
6

请只查看 src/auth/session.ts。
目标：找出可能导致登录态丢失的边界条件。
要求：
1. 不要修改文件。
2. 只输出问题列表。
3. 每个问题说明触发条件和建议验证方式。

如果需要修改，也先限定范围：

1
2
3
4
5
6

请只修改 src/utils/format.ts。
目标：补齐空字符串和 null 的处理。
要求：
1. 不要改函数签名。
2. 保持现有导出不变。
3. 修改后说明应该运行哪个测试。

这类写法能显著降低本地模型跑偏的概率。

FAQ

Codex 接 Ollama 后能完全离线吗？

如果 Codex 本身、模型和项目都在本地，并且不调用云端模型，推理可以在本机完成。但具体是否完全离线，还要看你的 Codex 运行方式、插件、工具调用和配置。建议用网络监控或防火墙规则验证，而不是只看模型来源。

用哪个 Ollama 模型比较合适？

代码任务可以先试 qwen2.5-coder:7b、qwen2.5-coder:14b 这类代码模型。机器性能较弱时先用 7B；显存和内存足够，再尝试更大模型。

为什么同一个问题云端模型会，本地模型不会？

本地模型参数量、训练数据、上下文窗口和工具适配通常都不同。接入方式相同，不代表能力相同。把任务切小、给明确文件范围、减少开放式要求，效果会好很多。

可以把整个代码库都交给本地模型吗？

不建议一开始这么做。先从单文件、单函数、单报错开始。如果要分析整个代码库，先让 Codex 用搜索工具缩小范围，再让模型处理相关片段。

Ollama 需要一直开着吗？

需要。Codex 调用本地模型时，Ollama 服务必须可访问。关闭 Ollama 后，通常会出现连接失败或请求超时。

接入成功后还需要 API Key 吗？

如果只调用本地 Ollama，通常不需要云端模型 API Key。但如果 Codex 配置里还有其他模型提供方，或者某些功能仍走云端，就要按实际配置判断。

报错：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。更新后重新打开终端，再运行：

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

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

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

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

再检查配置文件里是否存在类似自定义 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 任务通常包含更多上下文、更多工具调用和更长输出。

报错：工具调用不稳定

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

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

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

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

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

推荐的稳定配置流程

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

  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 配置。

小结

Codex 接入 Ollama 的排障顺序很简单：先确认 Ollama 能跑，再确认 HTTP API 能访问，接着检查 Codex 的 base URL、接口模式和模型名。连接问题解决后，再处理上下文、速度和输出质量。

本地模型最适合从小任务开始：解释、检查、草稿和低风险修改。只要任务边界清楚，它可以成为 Codex 的低成本辅助模型；如果把复杂重构和长任务一口气交给它，体验通常会变得不稳定。