当 OpenCode 搭配 Ollama 出现故障时，先检查服务器端点和精确的模型 ID，再考虑更换模型。如果两项检查都通过，就用一个小型文件编辑来区分是工具调用问题还是连接问题。模型能回复聊天请求，只说明它通过了编码智能体工作流的第一步。

本指南假设 Ollama 和 OpenCode 已经安装。安装和提供商配置请参阅 Ollama 与 OpenCode 配置指南。本文的排查流程旨在定位故障，同时避免反复修改你现有的配置。

确定哪个请求失败了

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

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

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

opencode --version
ollama --version

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

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

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

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 已停止，启动应用程序或在终端中运行其服务：

ollama serve

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

Ollama 的 OpenCode 集成文档使用以 /v1 结尾的 OpenAI 兼容基础 URL，请在 OpenCode 的提供商配置中保留该后缀。原生诊断路由（如 /api/version）不在该路径之下。

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

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

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

{
  "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 组合而成：

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

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

配置也可能来自多个位置。OpenCode 的配置文档描述了设置的合并规则。当某个值似乎被忽略时，在本地检查已解析的配置：

opencode debug config

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

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

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

创建一个新目录并进入：

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

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

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 支持 JSON 输出：

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 的上下文文档建议编码工具和智能体至少使用 64,000 个 token，并说明更大的分配会消耗更多内存。手动启动的服务器可以设置显式分配：

OLLAMA_CONTEXT_LENGTH=65536 ollama serve

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

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

ollama ps

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

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

保留有用的故障报告

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

OpenCode 故障排查指南说明了如何定位日志。在测试版本上，此命令可识别配置的数据和日志路径：

opencode debug paths

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

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

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

常见问题

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

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

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

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

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

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