你想让 Codex 走本地 Ollama，省掉 API 开销，结果多半卡在这几步：端点填了却连不上、能连上但请求超时、模型吐不出 Codex 想要的格式、跑一会儿就卡死。这篇不讲协议原理，只给一套能照着做的落地顺序和排查清单，顺带说清什么情况下本地这条路其实不划算。
你想让 Codex 走本地 Ollama，省掉 API 开销，结果多半卡在这几步：端点填了却连不上、能连上但请求超时、模型吐不出 Codex 想要的格式、跑一会儿就卡死。这篇不讲协议原理，只给一套能照着做的落地顺序和排查清单。
先打个预防针：本地这条路不是所有场景都划算。固定小任务、离线环境、数据不能出本机，这些情况下值得折腾；长上下文重构、大批量生成这类活，本地体验往往明显不如云端。怎么判断，下面几节会给标准。命令层面的兼容端点写法站内已有，参考 /guides/ollama-openai-compatible-setup。
开工前先对齐三件事：服务、端点、模型标识
动手前先把三样东西确认清楚，顺序别乱：Ollama 服务是不是真在跑、Codex 请求该发到哪个地址、模型名到底叫什么。这三件里任何一件错了，表现都是「连不上」或「找不到模型」，但成因完全不同，混在一起查会浪费时间。
- 先证明服务活着别直接在 Codex 里试，先用一个最简客户端请求本地端点。这一步成功说明服务和端点没问题，失败就与 Codex 无关，去查服务进程和端口。
- 再对齐端点写法Codex 侧把请求地址指向本机兼容端点，常见错误是端口号或多了一级路径。端点写错的表现通常是连接被拒，而不是返回鉴权错误，看到鉴权错说明你其实打到别的地方去了。
- 最后核对模型标识模型名必须与本地实际拉下来的名字完全一致，大小写、标签后缀都别自作主张。远端平台习惯的写法在这里经常对不上。
超时、并发、上下文这三个参数决定它稳不稳
打通之后别急着上强度，先调这三个参数。本地算力有限，首次加载模型权重会明显更慢，客户端整体超时给得太短，会把「在加载」误判成「接入失败」。建议先放宽超时、稳定运行后再往回收。
- 并发别按云端习惯来：同一张卡上同时跑多个请求，多半互相拖慢甚至排队卡死，从单并发起步逐步往上试
- 上下文窗口按本机显存反推，塞太长会直接失败或极慢，先保守再放宽
- 整体超时先放宽，跑稳之后再收紧，别一开始就按云端的标准卡
- 把每一档参数改动记下来，否则出问题分不清是配置还是机器性能
到底能承受多大并发、多长上下文，别拍脑袋。到 /tools/speed-test 量一遍自己的延迟基线，拿到数字再定参数。不同机器差异很大，别人能跑通的配置在你这里未必成立。
| 参数 | 本地该怎么设 | 设错的典型表现 |
|---|---|---|
| 整体超时 | 先放宽，稳定后收紧 | 首轮就被判失败 |
| 并发数 | 从单并发起步 | 请求排队、整体变慢 |
| 上下文长度 | 按显存反推，先保守 | 直接报错或极慢 |
| 模型标识 | 与本地实际名字一致 | 找不到模型 |
什么时候该降级回云端，怎么切才不打断工作
本地适合固定小任务、离线环境、对数据不出本机有硬要求的场景。长上下文重构、大批量生成这类活，本地体验往往不如云端。判断标准别靠感觉，看两件事：单次请求是否稳定完成、整体等待是否还在你能忍的范围内。
预设一条退路：本地请求失败或超时超过设定次数，就切到可用的远端接口。切换动作尽量放在配置层，而不是每次手动改，否则一忙起来就忘了切回来，白等半天。
不适用的情况也要说清楚：机器本身显存不足，或者没有可用的远端通道时，这套降级逻辑起不了作用，得先解决硬件或通道问题。
跑不通时的排查顺序
按顺序来，别跳步。每一步都只验证一件事，验证通过再走下一步，这样定位到哪一步失败，问题范围就缩小到那一层。
- 证明服务在绕过 Codex，直接用最简客户端请求本地端点。这一步失败，问题在服务本身，与 Codex 无关。
- 证明模型在确认模型名拼写与实际加载的名字一致，别用远端平台的习惯写法。
- 看客户端日志的报错类型连接被拒、超时、返回体格式不符，这三类对应完全不同的处理方式。参考 /guides/relay-connectivity-verification 的验证思路。
- 最后才怀疑参数逐个回退到最保守配置，再往上加。每次报错原文和当时配置贴在一起记录，别只记结论。
留痕与自测：让下次改动有据可依
跑通只是开始，能复盘才算稳定。日志至少记四项：请求时间、用的模型名、耗时、结束状态。这四项足够复盘一次慢或一次失败，别一上来就搞复杂埋点。
准备一组小用例，十几条即可，覆盖你日常最常让 Codex 干的活。每次改参数或换模型都跑一遍，看的是稳定通过率而不是单次表现。把本地模型和远端模型在同一组用例上各跑一次，比的是稳定性、格式正确率、等待时长，而不是笼统的好坏。
结论写进团队文档，注明测试时间和机器配置。隔一段时间机器或模型变了要重跑，旧结论别直接沿用。想横向看看不同方案近期的表现，可到 /rankings 和 /price-watch 核对当时的数字。
下一步先把最短单轮链路打通，再用小用例跑一轮稳定性对比。想省掉自己踩坑的时间，去 /guides 看接入类指南，或用 /tools/speed-test 先量出你机器上的延迟基线再调参数。→常见问题
Ollama 起好了，Codex 里却一直连不上，先查哪个？
先绕过 Codex，用最简客户端直接请求本地兼容端点。这一步通不了，问题在服务或端口，跟 Codex 配置无关；这一步通了再去核对 Codex 里填的地址和模型名是否完全一致，多数连不上都是这两处写法问题。
本地跑起来特别慢，是配置问题还是机器不够？
看两个信号：是首次加载慢还是每次请求都慢，以及并发调低后有没有改善。首次慢属于正常，每次都慢且降并发无改善，基本就是显存和算力不够。先把上下文长度压短试一次，能明显变快就是窗口给大了。
本地模型和云端接口能不能混着用？
可以，而且推荐这么做。把简单的、固定的、涉密的活留给本地，长上下文和大批量生成交给远端，退路做成配置项而不是每次手动切。前提是远端通道本身可用，否则降级就只是从慢变成失败。
