Prime Agent Ollama 2026：连不上排查

症状：模型不显示、连接失败、编码任务卡住。
最快解法：不要先重装，按 Ollama 服务、访问地址、models.json、API 兼容参数、模型能力五层隔离。

这篇内容适合三类人：已经配置过 Prime Agent、但看不到 Ollama 模型的个人开发者；能连接本地模型、却遇到请求报错、无工具行为或输出中断的 AI 工程师；准备让 Prime Agent 在远程或持续运行环境中执行长任务的平台团队。

⚠️ 本文最后更新于 2026 年 8 月 11 日，配置字段与兼容行为核实自 Prime Agent 当前模型配置文档、Providers 文档，以及 Ollama 官方 API、FAQ 和 Troubleshooting 文档。相关字段可能随版本变化，升级后应重新验证。

Prime Agent Ollama 2026：先把故障拆成五层

典型误区是：模型列表为空就重装 Prime Agent，连接报错就重新安装 Ollama，编码任务失败就认定本地模型“不兼容”。这三种处理都可能绕开真正原因。

你可以先用下面的判断工具确定排查方向：

官方文档目前将本地兼容服务配置归入 OpenAI 兼容接口，并支持在自定义模型配置中指定服务地址、API 类型、模型 ID 与兼容选项。你应把“服务能否响应”和“Agent 能否完成任务”当成两个不同验收目标。可先查看 Prime Agent 自定义模型配置文档 与 Providers 配置说明。

第一步：确认 Ollama 本身真的可用

模型列表为空时，应该先查 Prime Agent 还是 Ollama？

先不要打开 Prime Agent，直接在 Ollama 所在主机执行：

ollama list
curl http://127.0.0.1:11434/api/tags
curl http://127.0.0.1:11434/v1/models

预期结果是：ollama list 能列出目标模型，/api/tags 返回本地模型清单，/v1/models 返回 OpenAI 兼容格式的模型数据。如果第一条命令没有目标模型，问题是模型尚未安装或名称记错；如果 CLI 有模型但 HTTP 请求失败，问题在服务进程、监听地址或端口；只有三项都正常，才进入 Prime Agent 配置层。

Ollama 官方 OpenAI 兼容接口使用 /v1/chat/completions，本地示例地址通常是 http://localhost:11434/v1/。接口需要一个 API key 字段时，可使用占位值；Ollama 本地服务不会按普通云 API 的方式校验该值。具体请求格式以 Ollama OpenAI 兼容接口文档 为准。

模型名称必须完全一致，包括标签。例如配置写的是 qwen2.5-coder:7b，而本机实际只有 qwen2.5-coder:latest，Prime Agent 可能显示配置项，却在真正请求时返回模型不存在。不要凭显示名称猜测 ID，直接复制 ollama list 或 /v1/models 返回的实际值。

第二步：核对主机、容器与远程地址

Prime Agent 连接 Ollama 时 baseUrl 应该怎么填？

如果 Prime Agent 和 Ollama 在同一台主机、同一网络命名空间中，通常使用：

{
  "baseUrl": "http://127.0.0.1:11434/v1",
  "api": "openai-completions",
  "apiKey": "ollama"
}

这里的关键不是把地址写成什么，而是确认 localhost 指向谁：

• Prime Agent 与 Ollama 都在宿主机：127.0.0.1 通常有效。
• Prime Agent 在容器、Ollama 在宿主机：容器内的 127.0.0.1 指向容器本身，不是宿主机。
• 两者在不同机器：必须使用 Ollama 所在机器的可达内网地址或受控代理地址。
• Ollama 只监听回环地址：远程机器即使端口开放，也无法访问服务。

从 Prime Agent 实际运行的位置执行：

curl -i http://<ollama-host>:11434/v1/models
curl -i http://<ollama-host>:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"<model-id>","messages":[{"role":"user","content":"只回复 OK"}],"stream":false}'

200 只能证明基础路由可达，404 多半是路径或版本不匹配，connection refused 说明监听进程或地址不对，超时则优先检查网络策略、防火墙和模型首次加载时间。不要只在 Ollama 所在机器上测试，因为那无法证明 Prime Agent 所在环境能访问它。

远程访问还要考虑安全边界。不要把未经认证的 Ollama API 直接暴露到公网；更稳妥的做法是使用私有网络、SSH 隧道或带访问控制的内部代理，并把网络配置与 Ollama 官方 Troubleshooting 文档 对照检查。

第三步：检查 models.json 是否被正确读取

Prime Agent 当前文档指定的自定义模型配置路径是：

~/.prime/agent/models.json

先检查文件是否存在、JSON 是否有效：

ls -l ~/.prime/agent/models.json
python -m json.tool ~/.prime/agent/models.json >/dev/null

如果第二条命令报错，先修逗号、引号和括号，不要同时改 provider、模型 ID 和兼容字段。配置结构可按当前文档整理为类似形式：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://127.0.0.1:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {
          "id": "<model-id>",
          "reasoning": false
        }
      ]
    }
  }
}

你需要分别排除三种现象：

1. 模型未安装：ollama list 找不到对应 ID。
2. 配置未加载：文件正确，但 Prime Agent 的模型列表没有变化。
3. 名称不一致：模型出现在列表中，但发送请求时返回不存在。

部分版本会在打开模型选择器或执行模型列表命令时重新读取配置，因此修改后重新打开模型选择器，再检查是否出现目标 ID。若仍未出现，记录实际启动用户、当前工作目录和 HOME 环境变量；通过 SSH、服务管理器或容器启动时，读取到的用户目录可能与你在交互式终端中检查的目录不同。

第四步：把接口兼容问题拆开验证

模型已经出现，但请求阶段报参数错误，应该从哪里下手？

模型显示只证明配置被解析，不代表后端接受 Prime Agent 发出的全部字段。常见冲突包括：

• 后端不接受 developer role；
• 后端不接受 reasoning_effort；
• 流式请求不接受 stream_options.include_usage；
• 模型支持普通文本，却不支持工具调用或结构化输出。

Ollama 当前文档列出了 Chat Completions 的流式、工具、推理控制等支持范围，但“接口支持”不等于每个模型都能稳定完成 Agent 工作流。工具调用还取决于模型训练能力与实际响应格式。

兼容设置要分清层级：provider 级 compat 影响该服务下的全部模型，model 级配置只覆盖单个模型。若报错明确指向 role 或推理字段，可先尝试：

{
  "compat": {
    "supportsDeveloperRole": false,
    "supportsReasoningEffort": false
  }
}

每次只修改一个字段，然后重复最小请求。不要一次关闭所有能力，否则你无法知道真正起作用的是哪项改动，也可能把本来支持的功能一并禁掉。

第五步：从普通对话递进到编码任务

基础对话已经正常，但文件修改和测试流程仍然失败时怎么办？

按下面的里程碑测试，不要直接提交一个大型重构任务：

里程碑 1：读取。 让 Agent 读取一个已知的小文件，并复述其中一处内容。失败时检查工作目录和文件权限。

里程碑 2：修改。 要求只修改一个小文件中的一行，然后用 git diff 检查结果。模型只输出修改建议、没有真正写文件，可能是工具调用没有返回，或模型没有稳定遵循工具协议。

里程碑 3：执行。 让 Agent 运行一个无破坏性的测试命令，并返回退出状态。若命令没有执行，先查工具权限和 Agent 运行模式。

里程碑 4：恢复。 故意让测试失败，再要求 Agent 读取错误、修复并重新执行。这个阶段能区分“会生成代码”和“能闭环处理反馈”。

里程碑 5：长流程。 最后才测试多文件修改、长上下文和连续命令。

能回答“如何修改代码”，不等于能稳定完成 Prime Agent 的程序化任务。若同一个失败在最小项目中稳定复现，而基础 Chat Completions 请求正常，应优先更换更适合编码与工具调用的模型，或缩小任务边界；不要把模型能力不足写成 Prime Agent 或 Ollama 的确定性 Bug。

第六步：用时间线定位卡顿、断流与资源耗尽

长任务停顿时，同时记录三条时间线：

• Prime Agent：最后一次工具调用、重试、错误和会话状态；
• Ollama：模型加载、请求开始、请求结束、异常退出；
• 主机：内存压力、交换空间、CPU/GPU 使用率和进程状态。

如果首次请求长时间无输出，可能是模型加载；如果输出前段正常、上下文变长后变慢，重点检查上下文增长；如果多个子任务同时启动后断流，检查并发和内存压力。Ollama FAQ 说明默认上下文窗口和保持模型加载的行为可以通过配置或 API 参数调整，但实际可用范围仍取决于模型、主机资源与任务内容。可参考 Ollama FAQ 中的上下文与日志说明。

远程环境还要单独测试终端断开后的行为：

ssh <user>@<host>
tmux new -s prime-agent
# 在 tmux 中启动 Ollama 与 Prime Agent

随后断开 SSH，再重新连接并检查进程、会话和日志。若终端一断，Agent 会话或模型进程就结束，问题不是 API 参数，而是运行方式不具备持续性。此时应改用服务管理器、容器编排或稳定的远程工作环境，并明确日志保存位置。

修复后的最小验收清单

完成调整后，按这个顺序验收：

• ✅ /v1/models 能返回目标模型 ID；
• ✅ Prime Agent 模型列表能显示同一个 ID；
• ✅ 最小文本请求返回正常内容；
• ✅ 读取小文件成功；
• ✅ 修改小文件后能检查差异；
• ✅ 测试命令能执行并返回结果；
• ✅ 失败任务能够继续或安全停止；
• ✅ 记录 Prime Agent 版本、Ollama 版本、模型 ID、配置摘要和日志路径。

每次记录一条“失败边界”，例如“文本请求正常，但关闭 supportsDeveloperRole 前无法进入工具调用”。这比只写“已修复”更有价值，也方便版本升级后快速回归。

如果你当前是在本机临时验证，可先参考 Kvmkit 帮助中心 整理远程环境与服务持续运行问题。若准备把 Prime Agent 放到持续运行的 Mac 环境，还应把网络、会话保持和算力稳定性一并纳入验收，而不是只看模型是否能回复一句话。

当问题来自本机内存波动、终端断开或远程环境无法长期保持时，继续反复修改 models.json 通常不会带来改善。Windows 或 Linux 主机上的本地 Ollama 适合短时验证，但在长任务中可能遇到资源争用、后台进程退出和网络路径复杂等缺点；如果你的任务需要稳定运行、持续会话和可控交付，租用一台独立 Mac 往往比在配置层反复试错更省时间。你可以先查看 Mac mini 租用方案，再根据是否需要美国东部节点比较 远程 Mac 环境。对于临时算力、测试环境或远程验收，这种方案比立即购买硬件更容易控制周期；但如果你需要长期满负载运行或必须接入本地物理设备，自购 Mac 仍可能更合适。