---
title: "OpenCode 搭配 Ollama：修复连接和工具调用故障"
description: "通过端点检查、精确模型 ID、上下文验证和一个小型编码测试夹具，诊断 OpenCode 与 Ollama 的故障。"
date: "2026-10-28T00:00:00.000Z"
location: "San Francisco, CA - 2026年10月28日"
image: "/images/opencode-ollama-troubleshooting-hero.jpg"
unlisted: true
keywords: "OpenCode Ollama 故障排查, OpenCode Ollama 无法运行, Ollama OpenCode 工具调用, OpenCode 本地模型连接"
tags:
  - "OpenCode"
  - "Ollama"
  - "故障排查"
author:
  name: "Wayne Pan"
  url: "https://www.linkedin.com/in/wapan/"
  title: "CTO"
faq:
  - question: "Ollama 聊天成功是否意味着 OpenCode 工具调用也能正常工作？"
    answer: "不是。聊天响应只证明模型能生成文本。OpenCode 还需要结构化工具调用、执行权限以及足够的上下文来完成任务。请验证实际的文件编辑及其测试结果。"
  - question: "增加 OpenCode 的上下文限制是否会为 Ollama 分配更多内存？"
    answer: "OpenCode 中声明的上下文限制并不能证明 Ollama 已分配了该上下文。请配置 Ollama 服务器并使用 ollama ps 检查正在运行的模型。更大的上下文也会增加内存需求。"
  - question: "当 Ollama 模型从 OpenCode 中消失时，是否应该重新安装所有组件？"
    answer: "先比较 Ollama 返回的模型 ID 与 OpenCode 配置中声明的模型是否一致。在重新安装任何应用之前，先检查端点和所选提供商。"
locale: "zh-cn"
translationKey: "opencode-ollama-troubleshooting"
---
当 **OpenCode 搭配 Ollama 出现故障**时，先检查服务器端点和精确的模型 ID，再考虑更换模型。如果两项检查都通过，就用一个小型文件编辑来区分是工具调用问题还是连接问题。模型能回复聊天请求，只说明它通过了编码智能体工作流的第一步。

本指南假设 Ollama 和 OpenCode 已经安装。安装和提供商配置请参阅 [Ollama 与 OpenCode 配置指南](/zh-cn/blog/opencode连接ollama本地模型/)。本文的排查流程旨在定位故障，同时避免反复修改你现有的配置。

## 确定哪个请求失败了

OpenCode 的故障可能发生在推理之前、生成过程中或工具执行时，需要分阶段排查。连接被拒绝与模型返回一段看似 JSON 的文本，指向的是完全不同的问题。在更改任何设置之前，先记录端点、所选模型和错误信息，这样才能判断更改是否有效。

| 观察现象 | 下一步检查 | 结果说明什么 |
|---|---|---|
| 连接被拒绝 | 向配置的主机和端口请求 `/api/version` | 该 Ollama 端点是否可达 |
| 模型未找到 | 读取 `/v1/models` 并比较精确 ID | 请求的模型是否存在于该服务器上 |
| 聊天正常，文件未更改 | 检查工具调用和权限结果 | OpenCode 是否尝试并完成了操作 |
| 小编辑正常，大任务失败 | 检查已分配的上下文和运行时日志 | 较大任务是否遇到了可量化的限制 |
| 本地正常，云端挂起 | 分别测试两条路径 | 故障是否特定于云端路径 |

在复现故障之前先记录版本号：：

```bash
opencode --version
ollama --version
```

本文的本地检查使用了 OpenCode 1.19.4 和 Ollama 0.32.9，运行在配备 96 GB 统一内存的 Apple M3 Ultra 上。该硬件可以运行我们选择的 31B 模型，但这并不意味着内存较小的笔记本也能胜任。其他硬件上的模型选择请参考 [Ollama 编码模型指南](/zh-cn/blog/适合编程智能体的最佳ollama模型/)。

## 在更换模型之前先检查端点

向 OpenCode 所使用的同一主机和端口发送请求。`127.0.0.1:11434` 上的本地服务器和 `127.0.0.1:11435` 上的服务器是不同的端点。如果请求失败，先修复服务器或地址问题——更换模型无法解决连接被拒绝的问题。

```bash
curl --fail-with-body --max-time 5 \
  http://127.0.0.1:11434/api/version

curl --fail-with-body --max-time 5 \
  http://127.0.0.1:11434/v1/models
```

收到版本响应说明 Ollama 已正常应答。收到模型列表响应则说明该服务器暴露了哪些模型 ID。空列表意味着服务器可达但没有已列出的模型，这与连接错误不同。

如果 Ollama 已停止，启动应用程序或在终端中运行其服务：

```bash
ollama serve
```

如果端口已被占用，先检查哪个服务正在运行，而不是再启动一个副本。远程 Ollama 安装需要使用其远程地址；`127.0.0.1` 始终指运行客户端的本机。

[Ollama 的 OpenCode 集成文档](https://docs.ollama.com/integrations/opencode)使用以 `/v1` 结尾的 OpenAI 兼容基础 URL，请在 OpenCode 的提供商配置中保留该后缀。原生诊断路由（如 `/api/version`）不在该路径之下。

## 将配置的模型与服务器精确 ID 匹配

使用服务器返回的模型 ID，包括其标签。在一个 Ollama 服务器上下载的模型，在另一个没有同名模型的服务器上无法使用。重试请求之前，请一并检查所选提供商、其基础 URL 和模型声明。

以下是我们在 OpenCode 1.19.4 上使用的提供商配置结构：

```json
{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:11434/v1"
      },
      "models": {
        "gemma4:31b": {
          "name": "Gemma 4 31B",
          "limit": {
            "context": 65536,
            "output": 2048
          }
        }
      }
    }
  }
}
```

将 `gemma4:31b` 替换为你的服务器实际列出的 ID。此示例不会下载该模型。OpenCode 的完整选择器由提供商名称和模型 ID 组合而成：

```bash
opencode run -m ollama/gemma4:31b "Reply with one short sentence."
```

我们故意通过 Ollama 的兼容端点请求了一个不存在的模型，收到了带有 `not_found_error` 的 HTTP 404。该结果确认是模型选择错误，而非内存不足或工具解析器异常。

配置也可能来自多个位置。[OpenCode 的配置文档](https://opencode.ai/docs/config/)描述了设置的合并规则。当某个值似乎被忽略时，在本地检查已解析的配置：

```bash
opencode debug config
```

已解析的配置可能包含凭据。分享诊断报告之前，请提取相关的提供商设置，并移除密钥或无关的账户信息。

## 使用一次性编码测试夹具验证操作

自行检查已更改的文件并运行对应测试。给 OpenCode 一个含有已知 bug 的小文件，要求它修复，然后运行独立检查。这样既能测试文件访问、编辑和执行能力，又能将排查范围控制在可检查的大小。

创建一个新目录并进入：

```bash
mkdir opencode-ollama-check
cd opencode-ollama-check

cat > add.mjs <<'JS'
export function add(a, b) {
  return a - b;
}
JS

cat > check.mjs <<'JS'
import { add } from './add.mjs';
if (add(2, 3) !== 5) throw new Error('Expected add(2, 3) to return 5');
console.log('PASS');
JS

node check.mjs
```

第一次检查应该会失败。将你已验证的提供商配置复制到这个一次性目录中，然后运行：

```bash
opencode run -m ollama/gemma4:31b \
  "Read add.mjs. Fix add so it adds its arguments. Run node check.mjs."

node check.mjs
```

自行检查 `add.mjs` 的内容。如果文件仍然执行减法或独立检查失败，那么模型返回的成功信息就不足为凭。保持权限提示可见，以便区分"编辑被拒绝"和"工具调用缺失"两种情况。在我们的检查过程中，macOS 在 `/private/tmp` 下解析了测试夹具，而工具请求的是其 `/tmp` 别名。OpenCode 将别名路径视为外部路径，在非交互式运行中将其拒绝。使用解析后的实际目录和相对文件路径，就能让测试夹具在最小权限下运行。

如需更深入检查，[OpenCode 的 CLI](https://opencode.ai/docs/cli/) 支持 JSON 输出：

```bash
opencode run --format json -m ollama/gemma4:31b \
  "Read add.mjs and explain the implementation."
```

查找已执行的工具及其结果。包含函数名或 JSON 对象的文本本身并不能证明 OpenCode 执行了任何操作。在修正端点和测试夹具权限后，一次修复运行读取了测试夹具，将减法改为加法，并通过了独立的 Node 检查。第二次运行在替换了故意缺失的模型 ID 后同样通过了检查。在我们单独的 API 直接探测中，Gemma 4 31B 在 65,536 上下文下返回了结构化的 `read_file` 调用。该结果仅验证了探测的响应格式，并不代表编码任务中的可靠性。

## 检查 Ollama 实际分配的上下文

OpenCode 声明的模型限制和 Ollama 的运行时分配必须一致。仅在客户端配置中调大数值，并不能证明服务器实际分配了更多上下文。在请求期间检查正在运行的模型，然后将其实际上下文与任务的提示词和工具历史进行对比。

[Ollama 的上下文文档](https://docs.ollama.com/context-length)建议编码工具和智能体至少使用 64,000 个 token，并说明更大的分配会消耗更多内存。手动启动的服务器可以设置显式分配：

```bash
OLLAMA_CONTEXT_LENGTH=65536 ollama serve
```

在运行 Ollama 的进程上设置该变量。仅在运行 OpenCode 的终端中导出它，不会重新配置已在运行的 Ollama 应用。如果由应用程序管理你的服务器，请使用应用程序的上下文设置。

在模型加载期间检查其状态：

```bash
ollama ps
```

检查 `CONTEXT` 和 `PROCESSOR` 列。如果 Ollama 使用自定义主机或端口，CLI 也需要指向该服务器。内存压力、CPU 卸载、截断和工具格式失败需要分别排查，仅凭响应缓慢无法确定具体是哪种情况。

如果你的硬件无法容纳所需的上下文，选择一个支持工具的较小模型并重复相同的测试夹具。不要用不同的任务来对比两个模型，然后把差异归结为模型质量的不同。

## 保留有用的故障报告

有用的报告能让其他开发者复现相同的请求。报告应包括：版本信息、脱敏后的提供商配置、精确的模型标签、已分配的上下文，以及能复现故障的最小测试夹具。记录直接请求是否成功、OpenCode 是否能到达模型服务器。这些细节有助于维护者定位问题。

[OpenCode 故障排查指南](https://opencode.ai/docs/troubleshooting/)说明了如何定位日志。在测试版本上，此命令可识别配置的数据和日志路径：

```bash
opencode debug paths
```

将本地和云端结果分开记录。本地编码测试无法验证 Ollama Cloud 的身份验证或可用性，云端中断也不能证明本地工具调用存在回归。同样，描述相同症状的旧 issue 不能证明其修复方案适用于你当前安装的版本。

如果测试夹具成功但你的仓库任务失败，保留可工作的测试夹具并逐步增加复杂度：加一个文件、加大输入、或加长工具序列。第一个能复现故障的变更，比在没有对比的情况下重新安装两个应用更有价值。

完成本地诊断后如需配置其他提供商，[OpenCode 自定义提供商指南](/zh-cn/blog/opencode自定义提供商配置/)涵盖了 Haimaker 的设置。本地测试数据应保留在本地；切换提供商是可选的下一步，在条件允许时再考虑。

## 常见问题

#### Ollama 聊天成功是否意味着 OpenCode 工具调用也能正常工作？

不是。聊天响应只证明模型能生成文本。OpenCode 还需要结构化工具调用、执行权限以及足够的上下文来完成任务。请验证实际的文件编辑及其测试结果。

#### 增加 OpenCode 的上下文限制是否会为 Ollama 分配更多内存？

OpenCode 中声明的上下文限制并不能证明 Ollama 已分配了该上下文。请配置 Ollama 服务器并使用 ollama ps 检查正在运行的模型。更大的上下文也会增加内存需求。

#### 当 Ollama 模型从 OpenCode 中消失时，是否应该重新安装所有组件？

先比较 Ollama 返回的模型 ID 与 OpenCode 配置中声明的模型是否一致。在重新安装任何应用之前，先检查端点和所选提供商。