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

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

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