OpenCode + Ollama:编程智能体,就在您的 terminal

OpenCode和Ollama并不是竞争对手:OpenCode是在终端中运行的编程智能体,Ollama则是在本地提供模型服务的引擎。要连接两者,请安装OpenCode,在opencode.json中配置一个指向http://localhost:11434/v1的模型提供商,或运行ollama launch opencode。请将上下文长度设置为至少64,000个token,这是Ollama文档的要求。
本指南介绍如何在 macOS、Linux 或 Windows 上安装 OpenCode,通过官方方法和手动方法将其连接到 Ollama,选择实际机器能运行的代码模型,并说明上下文设置(头号陷阱)和权限设置——许多人以为权限限制比实际更严格。本指南还会对比 OpenCode、Cline 和 Aider。
#OpenCode 配合 Ollama:各自负责什么
OpenCode 是一个在终端中运行的开源编程智能体:它会读取您的项目、修改文件并执行命令。它本身不提供模型。Ollama 则在您的机器上下载并运行模型,并提供本地 API。两者相辅相成:OpenCode 将请求发送给 Ollama,后者使用本地模型作答。因此,无需在“OpenCode 还是 Ollama”之间做选择,两者应配合使用。
本地运行的价值并非出于意识形态。代码智能体能够看到一切:目录树、配置文件和业务逻辑。使用本地模型时,这些上下文保留在机器上,无需按 token 计费,也不依赖网络。代价在于模型能力:一个拥有数百亿参数的本地模型无法匹敌规模最大的托管模型,而且耗时较长的任务执行起来也更慢。
#前置要求:机器、终端和 Ollama
借助我们的经验和引导式路径,打造你的本地副驾驶,上手你的代码助手。
- 在线空间,终身可用
- PDF + 文件
- 30 天内退款
- 作为服务运行的 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(软件包配方),因为后者更新频率较低。
#快速方法:ollama launch opencode
Ollama 可以使用选定的模型启动 OpenCode。命令 ollama launch opencode 会通过内联传入的配置启动 OpenCode,不会覆盖您的 ~/.config/opencode/opencode.json 文件;您现有的 OpenCode 设置仍会生效。使用 --config 选项时,Ollama 会配置 OpenCode,但不会打开交互式会话。仅在 opencode.json 中定义的模型不会出现在 ollama launch 的模型选择器中。
#手动方法:将 Ollama 配置为模型提供方
如果您希望保留手动控制,可以在全局配置文件(~/.config/opencode/opencode.json)或项目根目录下的 opencode.json 中添加一个提供商。Ollama 的 OpenAI 兼容端点是 http://localhost:11434/v1。models 下的每个键都必须与 ollama list 显示的模型名称完全一致。
重启 OpenCode:模型选择器会列出在 Ollama 提供方下声明的模型。
#首要陷阱:上下文长度
许多初次尝试失败,是因为上下文太短:智能体丢失任务开头的信息,重复读取文件,或作出不一致的修改。Ollama 并未设定统一的上下文长度:文档指出,显存低于 24 GB 时为 4k token,24 至 48 GB 之间为 32k token,48 GB 及以上为 256k token。文档还说明,对于需要大上下文的任务,例如智能体和编程工具,应将上下文长度设置为至少 64,000 token。
| 可用显存 | 默认上下文 | 用于 OpenCode |
|---|---|---|
| 少于 24 GB | 4 000 tokens | 调整至至少 64 000 |
| 24 到 48 GB | 32 000 个 token | 调整至至少 64 000 |
| 48 GB 或以上 | 256 000 tokens | 足够;注意内存 |
更改这个值有两种方式。在 Ollama 应用中,可通过设置里的滑块调整上下文长度。在命令行中,OLLAMA_CONTEXT_LENGTH 变量会在服务器启动时生效。更长的上下文会消耗更多内存:请使用 ollama ps 检查模型是否完全加载到 GPU 上,因为一旦模型有部分转由 CPU 处理,速度就会变得非常慢。
#编程智能体应选用哪个本地模型
智能体必须能够可靠地调用工具:读取、写入、执行。请选择在 Ollama 模型库中标有 tools 能力的模型。以下候选模型的标签和大小均从 ollama.com 查得。
| 模型 | Tag | 下载大小 | 备注 |
|---|---|---|---|
| Qwen3-Coder 30B | qwen3-coder:30b | 19 GB | 宣称原生上下文长度为 256K;具备工具调用能力 |
| Devstral Small 2 | devstral-small-2:24b | 15 GB | 宣称的上下文长度为 384K;支持工具与图像 |
| Qwen3.5 | qwen3.5:9b、27b、35b | 根据大小 | 工具调用、视觉和思考能力因模型规模而异 |
| gpt-oss | gpt-oss:20b、120b | 根据大小 | 工具与推理 |
这些是文件的大小;还需计入上下文缓存,它会随着所需的64,000个token上下文而增大。15 GB的模型(Devstral Small 2)在24 GB的机器上最容易运行;19 GB的模型(Qwen3-Coder 30B)则需要预留更多空间。在配置较低的机器上,较小的模型可以执行简单且有针对性的任务,但在涉及多个文件的重构中会更快力不从心。
#一个真实工作流:添加路由及其测试
具体案例:为一个小型 Express API 添加 GET /health 路由,并用一个测试覆盖它。OpenCode 文档建议先运行 /init,它会分析项目并在根目录创建 AGENTS.md 文件;应将该文件提交到 git,以帮助智能体理解项目结构。
- 01打开项目进入仓库根目录,启动 opencode,首次运行时执行 /init。检查底部,确认所选模型确实是 Ollama 模型。
- 02切换到 Plan 模式按 Tab 键可在 Plan 和 Build 模式之间切换。Plan 模式会禁用修改:智能体只会提出它打算如何操作。在进行任何更改之前,请先让它制定计划。
- 03描述任务像向初级开发人员交代任务一样提供背景信息:“在src/server.js中添加一个GET /health路由,返回status ok,然后在test/health.test.js中添加一个测试。”@符号可用于在项目中查找文件。
- 04切换至 Build 模式当您对计划满意时,再次按 Tab 键,并要求应用修改。
- 05执行并迭代智能体可以运行 npm test,读取输出并进行修正。这种执行、观察、修正的循环是智能体技术的核心。
- 06检查并提交提交 commit 前请重新查看 git diff。如果会话偏离了预期,git restore 会将文件恢复到之前的状态。
使用本地模型时,每个步骤都比使用托管模型更慢,含义不明确的指令有时还需要改写。优势在于掌控力:代码和上下文保留在你的设备上,你可以根据硬件选择模型、量化方式和上下文长度。
#权限:智能体可以无需询问您就执行哪些操作
一种常见的看法是,未经您的同意,智能体不会修改任何内容。但这并不是默认行为。OpenCode 文档指出,在未进行配置时,大多数权限的值为 allow,也就是说,相应操作无需询问即可执行;只有少数权限,如 external_directory 和 doom_loop,值为 ask。默认禁止读取 .env 文件,但 .env.example 除外。
对于使用可靠性较低的本地模型的智能体,采用更严格的设置更为稳妥。opencode.json 文件支持 permission 配置节,其中每项操作都可设为 allow、ask 或 deny,也可以将全局规则 * 设为 ask。
#OpenCode、Cline 还是 Aider:该选哪个
| 工具 | 形式 | 亮点 | 适合选择的情况 |
|---|---|---|---|
| OpenCode | 终端界面,也可作为应用和 IDE 扩展使用 | 与厂商无关,支持多供应商,提供 Plan 和 Build 模式 | 您主要在终端中工作,或在远程服务器上工作 |
| Cline | VS Code 扩展 | 编辑器中显示的差异 | 你的工作流围绕 VS Code 展开 |
| Aider | 命令行 | 与 git 深度集成,自动提交 | 你希望精细控制添加到上下文中的文件 |
这三者都使用Ollama的API;花一小时试用最符合您使用习惯的两个,比看一篇对比评测更有价值。如果您需要的是行内自动补全而不是AI智能体,可以看看Tabby。
#故障排除
- 模型未显示
- opencode.json 中的名称与 ollama list 不匹配。请复制确切名称,包括标签。使用 ollama launch 时,仅在 opencode.json 中定义的模型不会出现在其选择器中。
- 智能体忘记了刚刚读过的内容
- 上下文太短:请将其调整为 64 000 tokens(OLLAMA_CONTEXT_LENGTH),并使用 ollama ps 进行检查。
- 连接被拒绝
- Ollama 服务器未运行,或未监听默认端口 11434。请测试 ollama list,然后测试 baseURL。
- 工具调用失败
- 该模型对工具的支持不佳。请在 Ollama 模型库中选用标有 tools 的模型。
- 响应非常缓慢
- 模型及其上下文超出了显存容量,部分计算会在处理器上执行。请缩短上下文、减小模型规模或降低量化精度。
如何将 OpenCode 与 Ollama 配合使用?+
OpenCode 和 Ollama 有什么区别?+
OpenCode 能在 Windows 上配合 Ollama 运行吗?+
使用 OpenCode 时,应在 Ollama 中将上下文长度设为多少?+
OpenCode 会不先询问我就修改我的文件吗?+
选择哪个本地模型用于 OpenCode?+
#深入了解
有反馈、发现了错误,或想补充说明?请告诉我们,让这份指南对每个人都更有帮助。