OpenCode + Ollama：编程智能体，就在您的 terminal

#OpenCode 配合 Ollama：各自负责什么

OpenCode 是一个在终端中运行的开源编程智能体：它会读取您的项目、修改文件并执行命令。它本身不提供模型。Ollama 则在您的机器上下载并运行模型，并提供本地 API。两者相辅相成：OpenCode 将请求发送给 Ollama，后者使用本地模型作答。因此，无需在“OpenCode 还是 Ollama”之间做选择，两者应配合使用。

本地运行的价值并非出于意识形态。代码智能体能够看到一切：目录树、配置文件和业务逻辑。使用本地模型时，这些上下文保留在机器上，无需按 token 计费，也不依赖网络。代价在于模型能力：一个拥有数百亿参数的本地模型无法匹敌规模最大的托管模型，而且耗时较长的任务执行起来也更慢。

#前提：主机、终端和Ollama

Ollama 正在运行

在进行任何配置之前，请先确认模型能够响应：运行 ollama list，然后用 ollama run 运行一个代码模型。如果成功，接下来只需配置 OpenCode。

一个现代化的终端

OpenCode的文档中提到了WezTerm、Alacritty、Ghostty和Kitty。在Windows系统上，文档建议使用WSL以获得更好的性能和完整的兼容性。

用于上下文的内存

智能体会读取文件并不断积累历史记录。Ollama 表示，OpenCode 要求上下文长度至少为 64,000 个 token，因此，除了存放模型权重所需的内存，还需要额外的内存。

一个Git仓库

并非必需，但建议使用：通过 git diff 或 git restore，可以妥善撤销一次失败会话造成的改动。

#安装OpenCode并连接至Ollama

OpenCode 可通过脚本或包管理器安装。文档列出了官方脚本、npm、bun、pnpm、yarn、Homebrew、Arch、Chocolatey、Scoop、Mise 和 Docker 的安装方式。对于在 macOS 和 Linux 上使用 Homebrew 的用户，文档建议使用官方 tap，而不是默认仓库中的 formula（软件包配方），因为后者更新频率较低。

curl -fsSL https://opencode.ai/install | bash

npm install -g opencode-ai

brew install anomalyco/tap/opencode

choco install opencode
scoop install opencode

#快速方法：ollama launch opencode

Ollama 可以使用选定的模型启动 OpenCode。命令 ollama launch opencode 会通过内联传入的配置启动 OpenCode，不会覆盖您的 ~/.config/opencode/opencode.json 文件；您现有的 OpenCode 设置仍会生效。使用 --config 选项时，Ollama 会配置 OpenCode，但不会打开交互式会话。仅在 opencode.json 中定义的模型不会出现在 ollama launch 的模型选择器中。

ollama launch opencode

#手动方法：将 Ollama 配置为模型提供方

如果您希望保留手动控制，可以在全局配置文件（~/.config/opencode/opencode.json）或项目根目录下的 opencode.json 中添加一个提供商。Ollama 的 OpenAI 兼容端点是 http://localhost:11434/v1。models 下的每个键都必须与 ollama list 显示的模型名称完全一致。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "qwen3-coder:30b": { "name": "Qwen3-Coder 30B" },
        "devstral-small-2:24b": { "name": "Devstral Small 2" }
      }
    }
  }
}

重启 OpenCode：模型选择器会列出在 Ollama 提供方下声明的模型。

#首要陷阱：上下文长度

许多初次尝试失败，是因为上下文太短：智能体丢失任务开头的信息，重复读取文件，或作出不一致的修改。Ollama 并未设定统一的上下文长度：文档指出，显存低于 24 GB 时为 4k token，24 至 48 GB 之间为 32k token，48 GB 及以上为 256k token。文档还说明，对于需要大上下文的任务，例如智能体和编程工具，应将上下文长度设置为至少 64,000 token。

更改这个值有两种方式。在 Ollama 应用中，可通过设置里的滑块调整上下文长度。在命令行中，OLLAMA_CONTEXT_LENGTH 变量会在服务器启动时生效。更长的上下文会消耗更多内存：请使用 ollama ps 检查模型是否完全加载到 GPU 上，因为一旦模型有部分转由 CPU 处理，速度就会变得非常慢。

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

#编程智能体应选用哪个本地模型

智能体必须能够可靠地调用工具：读取、写入、执行。请选择在 Ollama 模型库中标有 tools 能力的模型。以下候选模型的标签和大小均从 ollama.com 查得。

这些是文件的大小；还需计入上下文缓存，它会随着所需的64,000个token上下文而增大。15 GB的模型（Devstral Small 2）在24 GB的机器上最容易运行；19 GB的模型（Qwen3-Coder 30B）则需要预留更多空间。在配置较低的机器上，较小的模型可以执行简单且有针对性的任务，但在涉及多个文件的重构中会更快力不从心。

#一个真实的流程：添加一条路由及其测试

具体案例：为一个小型 Express API 添加 GET /health 路由，并用一个测试覆盖它。OpenCode 文档建议先运行 /init，它会分析项目并在根目录创建 AGENTS.md 文件；应将该文件提交到 git，以帮助智能体理解项目结构。

1. 01
   打开项目

   请进入仓库根目录，运行 opencode，然后首次执行 /init。在底部确认所选模型确实为 Ollama 模型。
2. 02
   切换到 Plan 模式

   按 Tab 键可在 Plan 和 Build 模式之间切换。Plan 模式会禁用修改：智能体只会提出它打算如何操作。在进行任何更改之前，请先让它制定计划。
3. 03
   描述任务内容

   像向初级开发人员交代任务一样提供背景信息：“在src/server.js中添加一个GET /health路由，返回status ok，然后在test/health.test.js中添加一个测试。”@符号可用于在项目中查找文件。
4. 04
   切换至 Build 模式

   当您对计划满意时，再次按 Tab 键，并要求应用修改。
5. 05
   执行与迭代

   智能体可以运行 npm test，读取输出并进行修正。这种执行、观察、修正的循环是智能体技术的核心。
6. 06
   验证并提交

   提交前请重新检查 git diff。如果会话出现偏差，可使用 git restore 将文件恢复至之前状态。

使用本地模型时，每一步操作都比使用托管模型更慢，且模糊指令有时需要重新表述。其优势在于掌控权：代码和上下文始终保留在您的设备上，您可以根据自身硬件选择模型、量化方式和上下文长度。

#权限：智能体可以无需询问您就执行哪些操作

一种常见的看法是，未经您的同意，智能体不会修改任何内容。但这并不是默认行为。OpenCode 文档指出，在未进行配置时，大多数权限的值为 allow，也就是说，相应操作无需询问即可执行；只有少数权限，如 external_directory 和 doom_loop，值为 ask。默认禁止读取 .env 文件，但 .env.example 除外。

对于使用可靠性较低的本地模型的智能体，采用更严格的设置更为稳妥。opencode.json 文件支持 permission 配置节，其中每项操作都可设为 allow、ask 或 deny，也可以将全局规则 * 设为 ask。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": { "*": "ask" }
}

#OpenCode、Cline 或 Aider：如何选择

这三者都使用Ollama的API；花一小时试用最符合您使用习惯的两个，比看一篇对比评测更有价值。如果您需要的是行内自动补全而不是AI智能体，可以看看Tabby。

#故障排除

模型未显示

opencode.json 文件中的名称与 ollama list 不匹配。请复制完全正确的名称，包括标签。使用 ollama launch 命令时，仅在 opencode.json 中定义的模型不会出现在选择器中。

智能体忘记了刚刚读过的内容

上下文长度太短：请设置为 64,000 个 token（OLLAMA_CONTEXT_LENGTH），并使用 ollama ps 检查状态。

连接被拒绝

Ollama 服务未运行或未在默认端口 11434 上监听。请先运行 ollama list，再检查 baseURL 的 URL。

工具调用失败

该模型对工具的支持不佳。请在 Ollama 模型库中选用标有 tools 的模型。

响应非常缓慢

模型及其上下文超出显存容量，部分计算将在处理器上执行。请减少上下文长度、模型大小或量化级别。

#深入了解

• Cline + Ollama 在 VS Code 中运行
• 在终端中使用 Aider + Ollama
• Tabby：本地代码自动补全
• 选择量化方案
• 理解上下文窗口
• 5 分钟安装 Ollama

• 来源：Ollama 的 OpenCode 集成文档
• 来源：Ollama，上下文长度
• 来源：OpenCode 文档
• 来源：OpenCode 权限