opencode实战指南：从安装配置到多模型接入与高效开发

最近好几个群都在聊 opencode，频率最高的几个问题分别是：这玩意儿跟 Claude Code 比到底强在哪？装完报错“无法将 opencode 项识别为 cmdlet”怎么办？为什么配了好几个模型都不生效？

我是从它还叫 sst/opencode 的早期版本就开始用的，一路跟着迭代到现在，日常看代码、改 bug、写脚本基本都离不开这个终端工具。这篇文章不打算把官方文档翻译一遍，而是把我从零开始安装、配置、接模型、接 VSCode 和 IDEA、再到把它真正用进日常开发流程里的完整过程梳理出来，包括踩过的坑、折腾过的配置，以及高频报错的排查思路。

先说结论：opencode 是一个开源的、跑在终端里的 AI 编程代理（agent），用 Go 编写，由做 serverless-stack 框架的 SST 团队维护。它跟 Claude Code、Codex CLI 属于同一类工具，但最大的区别是开放和自由——你想接哪家模型就接哪家，Anthropic、OpenAI、Google Gemini、本地 Ollama 都行，甚至支持自己写插件扩展技能。下面我会按从安装到实战的顺序，把整个链路拆开讲清楚。

1. opencode 到底是什么，为什么值得上手

1.1 一句话说清楚：终端里的 AI 编程副驾

opencode 本质上是一个交互式终端程序。你在项目目录里敲一下opencode，它就会启动一个类似聊天界面的 TUI（文本用户界面），左边是对话流，底部是输入框，你告诉它需求，它会自己读代码、改文件、执行命令、跑测试，然后把结果反馈给你。

很多用过的朋友会把它当成 Claude Code 的替代品来用，因为它兼容性好、可配置性强，而且完全开源免费。跟直接把代码贴给网页版 AI 不同，opencode 是“住在”你的项目里的。它能直接看到整个仓库的结构，能检索符号定义，能调用编译器和命令行工具，还能打开浏览器做端到端验证。这种工作方式更接近“你雇了一个坐在你旁边、能直接操作电脑的实习生”，而不是“你每次都要把上下文打包发过去的外包顾问”。

1.2 它和 Claude Code、Codex CLI 有什么不一样

我先放一张对比表，把三款主流终端 agent 的核心差异列出来，方便你判断自己该用哪个。

从表里能看出来，opencode 最大的差异化优势是“不捆绑模型”。如果你今天想试试 Gemini 的免费额度，明天想换 Claude 写复杂重构，后天又想在没网的环境下用本地模型，那 opencode 一套就能全部搞定。Claude Code 和 Codex CLI 用起来虽然顺手，但基本被锁定在自家模型体系里，切换成本相对高。

另外提一句，很多人搜“opencode 是哪家公司的”，这里统一回答：opencode 来自 SST 团队，就是做 serverless-stack 和 Ion 的那批人。这个团队在开发者工具圈子里口碑一直不错，项目的活跃度和迭代速度也都能看到，不是那种跑路风险高的个人玩具项目。

1.3 谁适合用 opencode

我体感下来，这几类人最容易从 opencode 里获益：

• 日常要维护多个技术栈项目的人。opencode 的模型无关特性让你可以在不同项目里用不同模型，前端项目用便宜快速的模型，复杂架构调整用更强的模型。
• 有隐私或成本顾虑的人。接上 Ollama 跑本地模型，代码完全不出机器，也没有按 token 计费的压力。
• 受够了各家 CLI agent 功能残缺的人。opencode 的 LSP、Playwright 浏览器自动化、Skills 机制，都是实打实能提升 AI 干活质量的功能。
• VS Code / JetBrains 重度用户。它在 IDE 插件上的完成度已经可以日常使用了，后面我会专门讲。

2. 安装 opencode：从零到跑通

2.1 各平台安装方式一览

opencode 的安装方式很灵活，我最推荐的是官方脚本和 Homebrew，其次是 npm 和 scoop。把你的系统对号入座就行。

macOS 用户（也支持 Linux）直接用 Homebrew：

brew install sst/tap/opencode

不想加 tap 的话，也可以用官方安装脚本：

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

Windows 用户我实测最省心的是 scoop：

scoop install opencode

习惯 Node 生态的，npm 全局安装也可以：

npm install -g opencode-ai

因为 opencode 是 Go 写的，所以如果你本机有 Go 环境，还能直接源码安装，顺便能拿到最新开发版：

go install github.com/sst/opencode@latest

提示：npm 包名是opencode-ai，不是opencode。直接用npm i -g opencode会装到一个完全不相关的包，这个坑我见过不下三次。

2.2 最常见的“无法识别 opencode”错误与解决

Windows 用户装上之后，十有八九会在 PowerShell 里碰到这句经典报错：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果存在路径，请确认路径正确，然后再试一次。

这句话翻译过来就是：系统在 PATH 环境变量里找不到 opencode 这个可执行文件。它不一定代表你没装上，更可能是装好了但没被找到。排查路径按顺序来：

第一步，先确认程序到底装到哪了。如果是 npm 装的：

npm prefix -g

这个命令会输出 npm 全局包的安装目录，比如C:\Users\你的用户名\AppData\Roaming\npm，opencode 的执行文件应该就在这个目录下。如果是 scoop 装的，一般会在C:\Users\你的用户名\scoop\shims里。

第二步，把对应目录加进 PATH。Windows 11 可以直接在“系统属性 → 环境变量”里加，也可以在 PowerShell 里临时刷新当前会话：

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

第三步，重新打开一个终端窗口再试。如果还不行，多数情况下是 npm 的全局 bin 目录本身就没进 PATH，手动补上即可。

注意：如果你是在 IDE 内置终端里运行 opencode，改完 PATH 之后务必重启 IDE，否则内置终端继承的还是旧环境变量，这时候就会误以为“又没装上”。

2.3 验证安装与环境检查

装好之后，建议先跑一个简单命令验证版本：

opencode --version

能看到版本号就说明核心程序没问题。接着建议直接跑一下自检命令：

opencode doctor

doctor会检查你的配置、环境变量、API Key 是否就绪，还会提示缺了什么。这个命令在后续排查问题时会非常有用，遇到诡异问题时先跑一遍它，比瞎猜高效得多。

第一次正式启动，直接在任意项目目录下敲opencode即可。它会先问你要不要初始化项目上下文（生成 AGENTS.md），跟着引导走就行。如果你更想先确认界面，也可以随便在一个空目录里启动，反正随时能退出。

3. 模型接入与配置：自由选择你的“大脑”

3.1 opencode 支持哪些模型来源

opencode 的模型接入是它相比同类工具最大的优势所在。我这段时间试下来，常用的来源大概分四类：

• 商业闭源模型：Anthropic 的 Claude 系列、OpenAI 的 GPT/Codex 系列，填 API Key 即用。
• 免费额度模型：Google 的 Gemini 系列，注册 AI Studio 就能拿到 API Key，免费档位对日常 coding 完全够用。
• 本地模型：通过 Ollama 跑 Qwen、Llama、DeepSeek 等开源模型，完全离线、无隐私问题。
• 企业/中转服务：支持配置自定义 OpenAI 兼容端点，公司内部网关或者第三方服务都能接。

这种多来源设计意味着你完全可以根据项目性质、成本预算和隐私要求去搭配模型。我的习惯是：日常小改动用 Gemini 免费档，大重构切 Claude，断网环境用 Ollama 本地模型。

3.2 配置文件到底怎么写

opencode 的配置入口有两个：全局配置和项目配置。全局配置文件在~/.config/opencode/opencode.json（Windows 是%USERPROFILE%\.config\opencode\opencode.json），项目配置则在项目根目录的opencode.json或.opencode/目录里。

一个最基础的配置长这样：

{ "$schema": "https://opencode.ai/config.json", "model": "google/gemini-2.5-flash", "provider": { "openai": { "api_key": "env:OPENAI_API_KEY" }, "anthropic": { "api_key": "env:ANTHROPIC_API_KEY" } } }

model字段指定默认模型，命名规则是“提供商/模型名”。provider字段用来给各提供商配置参数，API Key 建议用env:变量名的形式引用环境变量，而不是直接把密钥写死在配置文件里，这样安全得多，也方便多台机器同步配置。

如果要用本地 Ollama 模型，配置更简单：

{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "models": { "qwen3:14b": { "name": "Qwen3 14B" } } } } }

配好之后，在 opencode 的 TUI 里输入/model，就能看到所有可用模型列表，随手切换。这个模式非常像 IDE 里切换解释器，体验很自然。

3.3 免费模型与本地模型怎么接

我知道很多朋友搜 opencode 就是想找一个不用花钱、又能把 AI 编程跑起来的路子，这里详细展开讲。

方案一：Google Gemini 免费档

去 Google AI Studio 申请一个 API Key，类型选 Gemini 2.5 Flash（或其他免费档模型），然后设置环境变量：

# Windows PowerShell $env:GEMINI_API_KEY = "你的Key" # macOS / Linux export GEMINI_API_KEY="你的Key"

接着配置文件里指定：

{ "model": "google/gemini-2.5-flash" }

实测下来，Gemini 免费档的请求频率对个人开发足够了，写测试、补注释、解释陌生代码这些场景响应质量都不错。需要注意的是免费档有速率限制，如果并发任务太多会短暂 429，稍微等一下就好。

方案二：Ollama 本地模型

本地模型的好处一是完全免费，二是代码不出本机，适合处理公司敏感代码。先装 Ollama，再拉模型：

ollama pull qwen3:14b

然后按上一节的方式在配置里加上 ollama provider。本地模型的推理速度和模型大小直接相关，我建议笔记本用户从 14B 左右的量化版开始试，再根据自己电脑的显存和内存往上调。

提示：本地模型在复杂代码理解上确实不如顶级闭源模型，但它胜任机械性工作绰绰有余。比如批量格式化、生成单元测试骨架、翻译报错信息，这类任务我基本都是直接丢给本地模型处理。

4. 核心功能实操：把它当生产力工具而不是聊天框

4.1 双模式 Agent：先规划再动手

启动 opencode 之后，底部输入框会标明当前处于哪个 agent 模式。早期版本默认是 Build 模式，后续版本加入了 Plan 模式，机制类似官方版 Claude Code 的思路。

Build 模式：直接执行，AI 会边思考边改代码、跑命令，适合你明确知道要做什么的场景，比如“把登录接口的超时时间从 5 秒改成 10 秒，并更新单元测试”。

Plan 模式：只读分析，AI 会先调研代码、给出方案，但不会动任何文件。这特别适合接手不熟悉的项目——先让它输出一份改造计划，你确认没问题再切到 Build 模式去落地。

我在实际工作中养成的习惯是：改核心模块之前，先花 5 分钟在 Plan 模式里把方案聊清楚。别小看这一步，AI 在“先解释思路”时犯错的概率远低于“直接上手就改”，而且你还能借机检查它的理解是否和你一致。

4.2 Skills 技能机制和社区技能包

Skills 是 opencode 近几个版本重点发力的能力，你可以把它理解成“给 AI 预装的岗位培训手册”。每一个 Skill 本质上是一组 Markdown 指令和示例，告诉 AI 遇到某类任务时该怎么思考、怎么执行、按什么规范和格式输出。

在 opencode 的 TUI 里，输入/skills可以查看当前可用的技能列表。社区里有大量现成技能包可以安装，最有名的就是 obra 搞的 Superpowers 系列——当初很多人搜“opencode 安装 superpowers”，其实就是通过插件市场装这套技能包：

/plugin 搜索 superpowers

装好之后，AI 在应对代码 review、重构、调试、写文档等场景时会自动应用对应的技能模板，输出质量明显比裸用模型高。我用下来最直观的感受是，它减少了大量“AI 回答得很好但根本不项目实际”的情况，因为技能里强加了“先读代码、再给结论、附上证据”的约束。

4.3 LSP 加持：让 AI 真的“看懂”代码

LSP（Language Server Protocol）是很多编辑器智能提示背后的协议，opencode 把它也接入了，这也是当初我选择它的重要原因之一。

简单说，LSP 让 opencode 能向语言服务器查询符号定义、类型信息、引用关系等。以往 AI agent 只能靠“搜索文本”来猜测代码结构，有了 LSP 之后，它能拿到真正经过语法解析的符号级上下文。比如修改一个函数的调用方时，AI 可以精确找到所有引用位置，而不是靠正则去猜。

在项目里启用 LSP 需要在配置文件里声明语言服务器。opencode 会负责下载和管理对应的 server 二进制文件，以 TypeScript 项目为例，比较常见的做法是让 agent 使用项目自带的typescript-language-server。运行过程中如果发现 LSP 相关的二进制下载失败，优先检查网络和版本兼容性，然后跑opencode doctor看诊断信息。

4.4 Playwright 集成：让 AI 自己开浏览器找前端 bug

前端开发最麻烦的一件事就是“这个 bug 我复现不了”。opencode 直接内置了 Playwright 浏览器自动化工具，让 AI 能自己打开浏览器、访问页面、点击操作、读取控制台报错、截图回来给你看。

日常我这么用它：项目启动后，在 opencode 里直接说“打开 http://localhost:5173，走一遍登录流程，我填了错误的验证码，看看页面报什么错，把截图给我”。AI 会自动启动浏览器，一步步操作并返回截图和 console 报错信息。这种“先复现再修”的工作流，比我以前自己反复点页面高效太多了。

需要注意，第一次使用 Playwright 功能时可能要装浏览器内核，命令行跑一下：

npx playwright install chromium

如果 agent 报找不到浏览器的错，多半就是这一步漏了。另外提醒一下，浏览器自动化比较吃资源，如果你同时在跑大型编译任务，建议别让 agent 开着浏览器乱逛太久。

4.5 项目记忆：AGENTS.md 与会话管理

opencode 处理“项目记忆”的方式很直接——项目根目录下的AGENTS.md文件。这个文件相当于“给 AI 的项目说明书”，告诉它项目结构、构建命令、代码规范、常见注意事项。每次启动会话时，opencode 会自动读取这个文件并注入上下文。

你可以用/init让 AI 自动生成一份初始版 AGENTS.md，再手工补充细节。我自己的做法是，在接手一个新项目或新同事加入时，先花十分钟把 AGENTS.md 写清楚。后面所有会话的 AI 表现会稳定很多，不会反复问“这个项目怎么启动”“测试命令是什么”这类基础问题。

另外，opencode 的会话记录是本地存储的，你可以随时用opencode --continue接着上一次的会话继续聊，也可以开多个会话分别推进不同任务。对于那种“做到一半被打断，第二天接着搞”的场景，这个能力真的很救命。

5. 接入开发环境：VSCode、IDEA 与桌面版

5.1 VSCode 插件实践

很多人不习惯纯终端工作，opencode 官方也提供了 VSCode 插件。安装方式很简单，直接在 VSCode 扩展市场搜“opencode”，装官方那个扩展即可。

装好后，侧边栏会出现 opencode 面板，界面类似于常规 AI 编程插件，但底层其实是连接到你本地的 opencode 服务。这意味着你在 IDE 里创建的会话、使用的模型、加载的技能，跟终端里的保持一致，不会出现两套配置割裂的情况。

实际用下来，最适合 IDE 插件的场景是“局部代码解释”和“选中代码改造”。你选中一段代码，右键发给 opencode，让它解释或重构，改动可以直接以 diff 形式展示，比切到终端再描述上下文方便得多。

注意：VSCode 插件依赖本机已经装好 opencode CLI，如果插件反复提示找不到 opencode，先确认 CLI 能正常跑通，再重启 IDE。

5.2 JetBrains IDEA 插件实践

用 IntelliJ IDEA、PyCharm、GoLand 等 JetBrains 系 IDE 的朋友也不用酸，opencode 同样有官方插件，在插件市场搜“opencode”安装即可。

JetBrains 插件的交互逻辑跟 VSCode 版类似，但针对 Java/Kotlin 生态做了不少优化。我身边有人问“opencode mvn 配置”怎么弄，其实不用额外给 opencode 配 Maven，AI 在项目里执行mvn test、mvn compile时会直接用你本机的 Maven 环境，关键是把JAVA_HOME和MAVEN_HOME配好，让 agent 在终端里能正常调用这些命令。

5.3 桌面版和 CLI 怎么选

opencode 也出了桌面版，本质上是一个带图形界面的客户端，连接本地的 opencode 服务。它更适合那些想要聊天界面、又不想被终端吓到的朋友，也方便查看会话历史和截图类结果。

我的建议是：桌面版和 IDE 插件可以作为辅助，但主力还是 CLI TUI。原因在于，CLI 能直接在项目目录上下文里工作，权限控制和命令执行链路最完整，配合终端分屏效率最高。桌面版现在完成度已经不错，但一些高级 agent 操作和复杂的命令行交互，还是 CLI 更顺手。

6. 高频问题排查实录

6.1 模型不可用：this model is not available in your country

这个报错很多朋友遇到过，完整提示是this model is not available in your country。出现这个提示，说明你选定的模型提供方在你当前所在地区不提供服务，这是模型服务商的限制。

碰到这种情况，现实的做法有三个：一是切换到你所在地区能正常使用的其他模型，比如 Gemini 的免费模型；二是更换模型服务商，改用一个在你那边有服务节点的供应商；三是最稳妥的，直接用 Ollama 跑本地模型，彻底绕开地区限制。工具的价值是帮你把代码写好，没必要跟某个网红模型死磕，换一个照样干。

6.2 unexpected server error 与日志排查

另一个高频报错是：

error: unexpected server error. check server logs

这个提示比较模糊，它背后通常是两种情况：一是 API Key 失效或额度用光了，二是某个 provider 的请求参数有问题。排查思路如下：

先跑opencode doctor检查整体配置，如果没发现问题，再看具体日志。opencode 的日志文件在本地数据目录下，macOS/Linux 一般在~/.local/share/opencode/log/，Windows 在%USERPROFILE%\.local\share\opencode\log\，按时间排序列出最近的日志文件，重点看里面有没有 provider 返回的具体状态码和错误信息。

如果日志显示 401，基本就是 API Key 问题；显示 429 是请求太频繁或额度超了；显示 404 则多半是模型 ID 写错了，去 provider 官网核对一下模型名。

6.3 其他高频问题速查表

我把这段时间累计遇到的典型问题整理成一张速查表，方便你直接对照处理。

7. 我坚持用下来的几条实在建议

关于 opencode，最后分享几点我自己沉淀下来的使用心得，算不上教程，但确实帮我少走了很多弯路。

模型别贪贵，分场景用。我见过很多人一上来就上最强模型，结果改个变量名也在烧钱。日常机械操作交给便宜模型或本地模型，核心设计决策再调强模型，成本能省一大截。

AGENTS.md 值得认真写。每换一个项目或成员，花十几分钟把项目怎么跑、怎么测、有什么约定写清楚，后续所有 AI 会话的体验都会上一个台阶。这是投入产出比最高的一步。

善用 Plan 模式。AI 直接改代码看着很爽，但遇到重构类任务，先让它出方案再动手，能避免很多“改到一半发现方向错了”的尴尬。

遇到报错先跑opencode doctor，再看日志，别急着重装。九成问题都是配置层面的，日志里写得明明白白。这也是我琢磨了很久才养成的习惯——以前一报错就卸载重装，纯粹是在浪费时间。