半个月前我把主力编码 Agent 从 Claude Code 换成了 opencode。起因是手头一个接手过来的 Go 项目里遗留代码没有文档、依赖关系一团乱麻Claude Code 处理起来总要反复切换上下文。后来试用了一圈开源终端 Agent最终留下了 opencode——它最吸引我的一点是不绑定单一模型Claude、GPT、本地 Ollama 全都接而且配置逻辑相当透明。如果你是第一次听到 opencode我可以直接告诉你它是什么一个开源的、跑在终端里的 AI 编程助手支持交互式对话、自主 Agent 模式、Skills 技能包、LSP 语言服务还能驱动浏览器做前端测试。这篇东西不是官方文档的复读。我打算从实际操作出发把安装踩坑、模型选择、Skills 用法、LSP 配置、Playwright 测前端、VSCode/IDEA 插件、常见报错排查全部过一遍最后再聊聊它跟 Codex、Claude Code、Pi 这些同类 Agent 到底该怎么选。1. 先搞清楚 opencode 到底是什么以及它解决了什么问题1.1 核心定位终端里的开源编码 Agentopencode 不是一个插件也不依赖某个特定编辑器的生态。它就是一个独立的命令行工具你可以在终端里直接敲opencode进入全屏交互界面也可以用它提供的 CLI 参数一次性执行任务。和 Claude Code 有点类似的是它把“和 AI 对话 修改代码 执行命令”整合在同一个 TUI 里不同的是opencode 把模型层完全抽象出来了你可以在配置文件里自由切换任何兼容 OpenAI 或 Anthropic 接口的模型服务。我当初换掉 Claude Code 的第二个理由是 opencode 对“模型不可用”“服务报错”这类问题的反馈更透明。Claude Code 这类官方工具出问题你往往只能看到一句笼统的报错opencode 会把错误直接抛到终端里日志里能看到请求走了哪个 base URL、命中了哪个模型、返回了什么状态码。对习惯排查问题的开发者来说这种感觉踏实很多。1.2 适用人群和使用场景如果你属于下面这几类人opencode 值得你花一个下午折腾受够了“一个 Agent 绑定一个模型”的人。你想用 Claude 写复杂逻辑又想用 GPT 做结构化重构还偶尔用本地模型跑点不敏感的小任务opencode 可以在一个工具里全搞定。需要接管遗留项目的人。手头有别人写的代码依赖混乱、注释缺失你需要一个能快速扫描目录结构、按模块理解代码、还能执行测试命令的 Agent。想自动化前端 Bug 复现的人。opencode 内置了浏览器自动化能力可以让 Agent 打开本地页面、点击按钮、截图、看控制台日志把“用户反馈的 bug”变成“可复现的测试步骤”。做技术选型对比的人。你正在纠结 Codex、Claude Code、Pi 哪个好用直接用 opencode 作为统一入口分别接入这些模型横向对比输出质量比在多个工具之间来回切换省事得多。2. 安装与初始化从下载到跑通第一个对话2.1 各平台安装方式opencode 的安装方式非常多我按照“省心程度”排个序# macOS / Linux 用户Homebrew 最省心 brew install opencode-ai # 或者用官方脚本适合 Linux 服务器和 CI 环境 curl -fsSL https://opencode.ai/install | bash # Go 用户也可以直接编译安装 go install github.com/sst/opencodelatestWindows 用户我试过两种路径。一种是直接用官方提供的二进制文件从 GitHub Releases 页面下载 Windows 版本解压后把可执行文件所在目录加到 PATH另一种是用 Scoopscoop bucket add sst https://github.com/sst/scoop.git scoop install opencode装完之后在终端输入opencode --version能输出版本号就说明安装成功。第一反应报错“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”的同学大概率是 PATH 没配好或者装完之后没有重新打开终端这个我后面会专门讲。2.2 初始化配置与第一个对话装好后的第一步是初始化配置目录。opencode 的全局配置放在~/.config/opencode/下我建议先看一眼默认生成的配置文件长什么样再动手改。# 首次直接启动会让你选择需要配置的服务商 opencode启动之后你会看到一个全屏 TUI 界面底部是输入框中间是对话历史。第一次用的话直接检查一下模型有没有连通——在输入框里敲一句“你好介绍一下你现在可用的模型”回车看回复。如果回复正常恭喜你核心链路已经通了如果报错十有八九是环境变量没配全或者模型名填错了。opencode 读取模型配置的优先级是这样的命令行参数 项目目录下的配置文件 全局配置文件 默认配置。理解这个顺序很重要因为你在 A 项目里改的配置可能会被 B 项目的本地配置覆盖排查问题的时候特别容易踩这个坑。2.3 非交互模式一条命令跑完一个任务除了 TUI 交互模式opencode 还支持非交互式的run命令这个我在 CI 和批量任务里用得非常多# 让 Agent 阅读代码并重构某个文件 opencode run 重构 src/util.go 中的错误处理逻辑保持对外接口不变 # 让 Agent 运行测试并修复失败用例 opencode run --agent 执行 go test ./...根据失败信息修复测试 # 指定模型执行一次性任务 opencode run --model claude-sonnet-4 为 API 层补充接口文档后面我会详细说这些模式怎么配合实际项目用。先记住一点opencode 的核心是“模型无关”你随时可以用--model参数覆盖全局默认模型这在切换模型对比效果时非常方便。3. 模型配置与订阅方案选择这是 opencode 最大的自由也是最大的坑3.1 先理解 provider 和 model 的关系opencode 的配置逻辑里有两个关键概念provider模型服务商和 model具体模型。provider 定义了请求发往哪个 API 地址、用什么鉴权方式model 是具体使用的模型名。两者分开配置的好处是你可以在一个 provider 下挂多个 model也可以在多个 provider 下挂同一个 model。以我自己的配置文件为例{ $schema: https://opencode.ai/config.json, provider: { anthropic: { options: { api_key: ${env:ANTHROPIC_API_KEY} }, models: { claude-sonnet-4: { name: claude-sonnet-4 } } }, openai: { options: { api_key: ${env:OPENAI_API_KEY} }, models: { gpt-5: { name: gpt-5 } } }, ollama: { options: { baseURL: http://localhost:11434/v1 }, models: { qwen3:32b: { name: qwen3:32b } } } }, model: claude-sonnet-4, agent: true }这个文件干了几件事声明了一个 Anthropic 的 provider使用环境变量里的 API Key声明了 OpenAI 的 provider声明了一个本地 Ollama 的 provider最后把默认模型设成了 Claude Sonnet。这样我在 TUI 里输入/models就能随时切换不需要每次改配置文件。3.2 模型订阅方案怎么选go 订阅与 ccswitch 配合搜索热词里频繁出现“go 套餐”“go 订阅模型选择”“ccswitch 配置 opencode”这几件事其实都围绕同一个需求很多人用的是第三方模型服务订阅而不是直接在官方控制台充值。这些订阅服务通常会提供一个兼容 OpenAI 或 Anthropic 格式的 API 地址和 Key然后你按量或按周期付费。我的建议是无论你用哪家订阅都按下面这个套路来配置在服务商后台拿到 API Base URL 和 Key。在 opencode 的配置文件里把这些信息填到对应的 provider 里不要直接用api_key硬编码而是用环境变量引用。如果你需要在多个订阅服务商之间切换就把 ccswitch 这类工具配好让 opencode 能动态获取当前激活的供应商信息。举一个具体配置 ccswitch 的场景你平时主力用 A 服务商的 Claude 模型偶尔需要用 B 服务商的 GPT 模型。ccswitch 这种工具做的事情就是帮你集中管理多个供应商的 Key 和 Base URL并且能切换当前激活项。配置好之后opencode 读取到的是“当前激活服务商”的配置你不需要一个服务商改一遍 opencode 配置。不过这里我要提醒一句别在同一个配置里塞太多 provider。我一开始把六七个订阅服务商全部塞进去结果 opencode 启动时挨个探活慢得要命还有几个不稳定的服务商拖慢了整体响应。后面我精简到两三个正式用的加上一个本地 Ollama清爽多了。3.3 免费模型与本地模型的接入热词里还有“opencode 免费模型”和“hy3-free 下线了吗”这个我多说一句。所谓免费模型通常分两类第一类是服务商提供的限时免费或低配免费模型比如某些平台上的轻量级模型速度快、额度有限适合做简单任务。这类模型的问题在于不太稳定会突然下线。热词里提到的“hy3-free 下线”就是典型的服务商把免费模型下线了。遇到这种情况第一反应不是纠结为什么下线而是去 opencode 配置里把该 provider 下的模型列表更新掉换到备选模型上。第二类是本地模型比如通过 Ollama 跑的 Qwen、Llama 等开源权重模型。这类模型完全免费、数据不出机器但是代码生成质量跟顶级商用模型差距明显。我的用法是写单元测试、格式化代码、做简单代码解释这类“低风险”任务用本地模型复杂重构、架构设计、跨文件逻辑修改用商用模型。如果你也想在 opencode 里接入 Ollama配置比想象中简单# 先确保 Ollama 已启动 ollama serve # 拉取一个编码能力还可以的模型 ollama pull qwen3:32b然后按前面说的在 provider 里加一个ollama条目baseURL填http://localhost:11434/v1即可。注意 Ollama 自动兼容 OpenAI 格式所以 opencode 直接就能识别不需要额外插件。3.4 配置不当导致的两个经典报错关于模型配置有两个搜索热词里的报错我必须专门拿出来讲因为太典型了。第一个是this model is not available in your country。这个错误字面意思是“当前模型在你的国家/地区不可用”。出现这个报错的原因通常是你使用的模型服务商对请求来源地区有严格限制你当前所在区域的请求被服务商拒绝了跟 opencode 本身没有关系。处理思路是检查你用的服务商支持哪些区域换成支持你所在区域的模型或服务商。注意这不是 opencode 的 bug也不是配置文件格式问题别再翻来覆去检查配置了。第二个是unexpected server error. check server logs。这属于 opencode 把底层错误抛给了用户信息量不够。我遇到这个报错时排查顺序是固定的先看本机能不能直接访问到 API 地址再确认 Key 有没有过期最后用 curl 手动请求一次该模型的 API看返回什么。多数情况是某个中间服务超时或者你填的模型名在服务商那边根本不存在返回了一个误导性的服务端错误。4. 日常实操Skills、LSP、Playwright 这些高阶能力怎么用4.1 Skills把常用工作流封装成技能包Skills 是 opencode 里我个人最喜欢的功能也是热词中出现频率很高的“opencode skills”。简单理解Skills 让 opencode 在处理任务时能调用你预定义好的“技能”每个技能是一个带有说明文档的目录目录里可以放脚本、模板、提示词。我把每个技能理解成“给 Agent 的一份岗位说明书”。Agent 遇到相关任务时会根据技能描述决定要不要调用它。一个完整技能长这样~/.config/opencode/skills/ ├── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── review.py ├── git-commit/ │ ├── SKILL.md │ └── templates/ │ └── commit-template.txt └── frontend-debug/ ├── SKILL.md └── scripts/ └── debug-browser.js每个SKILL.md用 YAML frontmatter 写元信息正文写详细指令。我举一个 code-review 技能的例子--- name: code-review description: 对指定文件或整个项目进行代码审查输出问题列表和修改建议。适用于 PR 评审、代码检查。 --- 按照以下步骤执行代码审查 1. 先读取目标文件理解整体结构。 2. 检查错误处理是否完整特别是外部输入和 IO 操作。 3. 检查并发安全指出数据竞争风险。 4. 遵循项目现有的代码风格不要建议大规模重写。 5. 输出格式为 Markdown 列表问题严重程度用 [高]/[中]/[低] 标注。 调用 scripts/review.py 辅助统计文件和函数复杂度。配置好 Skills 之后你在对话里直接说“对 src 目录做一次 code review”opencode 就会自动匹配到 code-review 技能按里面定义的步骤执行。这相当于把你的团队规范、个人偏好直接固化成了 Agent 的执行标准避免每次都要在提示词里重复一遍。我常用的几个技能包括代码 review、语义化 Git 提交、接手新项目时的模块梳理、前端 Bug 复现。特别是“接手新项目”这个技能我会在 SKILL.md 里写好步骤——先看 README、再看依赖清单、找入口文件、梳理路由表——这样每次拿到新项目都能有稳定的启动路径不容易漏步骤。4.2 LSP让 Agent 真正“理解”代码LSPLanguage Server Protocol原本是编辑器用来提供补全、跳转、诊断的协议opencode 的思路是把它引入 Agent 场景让 Agent 在读写代码时能像 IDE 一样获取类型信息、编译诊断、符号定义。热词里有人问“opencode 如何使用 lsp”这里我把配置过程完整写一遍。配置在 opencode 的lsp字段里比如{ lsp: { typescript: { server: typescript-language-server, args: [--stdio] }, golang: { server: gopls, args: [serve] }, rust: { server: rust-analyzer } } }配置好之后Agent 在分析代码时就能拿到类型和语法级别的反馈。举一个实际场景你让 Agent 修改一个 TypeScript 接口但它不知道该接口在其他文件里怎么被使用如果没有 LSP它只能靠文本搜索来猜测有 LSP 后它能直接拿到符号引用列表改起来精准很多。不过我要提醒LSP 不是越高配越好。每个语言服务器都要吃内存和 CPU如果你同时开五六个语言服务器opencode 的启动速度和响应速度都会明显变慢。我的建议是只配置项目实际用到的语言最多再加一个你最常写的脚本语言。4.3 Playwright让 Agent 自己复现前端 Bug热词里“opencode playwright 怎么测试前端 bug”提到了一个很有意思的能力。opencode 集成了浏览器自动化可以让 Agent 启动一个真实浏览器、打开页面、执行点击输入操作、读取控制台日志和网络请求、截图保存。这对于复现那些“用户说页面白屏但我本地就是复现不出来”的 bug 非常有用。我实际用下来一个典型的前端 bug 排查流程是这样的在对话里告诉 Agent 用户反馈的现象比如“用户说点击登录按钮后页面一直空白”。Agent 会用 Playwright 启动浏览器打开本地开发服务器地址。Agent 执行点击、输入等操作尝试复现问题。如果复现了白屏Agent 会去查看浏览器控制台、Network 面板定位阻塞脚本或接口错误。整个过程会截图Agent 会在对话里贴出截图和对应的日志片段。这里有个前提你得让 Agent 知道启动命令和页面地址。我通常在项目根目录的配置文件里加一行说明或者直接在对话里告诉 Agent“跑npm run dev然后访问http://localhost:5173”。也建议给 Agent 足够的操作许可否则它连启动服务的权限都没有。4.4 Agent 模式与 TUI 使用的几个小技巧opencode 的agent: true配置会让它进入自主 Agent 模式。在这个模式下模型不只是跟你对话它还能自主决定执行哪些命令、读取哪些文件、修改哪些代码。这个模式非常强但也需要一些约束。我的经验是复杂的、跨文件的重构任务才用 Agent 模式简单的问答和代码解释用普通对话模式。不然 Agent 很容易高估自己的能力对着一个简单问题反复改文件最后给你留一堆没必要的改动。另外TUI 界面里有几个快捷键值得记一下/models快速切换当前模型。/tabs管理多组对话。/cost查看当前会话的 token 消耗和费用估算。/session查看会话相关信息。我比较常用的是/cost因为接第三方订阅时有些服务商的计费方式比较混乱有了 token 消耗统计我至少能心里有数避免月底收到惊吓。5. 编辑器生态VSCode 和 JetBrains 插件怎么配置5.1 VSCode 插件从编辑器里直接启动 Agentopencode 的 VSCode 插件让很多人误以为它是“另一个 Copilot”其实它更像是把终端里的 opencode 会话桥接到了编辑器里。装上扩展后你可以从命令面板启动 opencode选中的代码会直接作为上下文传入对话Agent 的修改结果也能以 diff 的形式展示。安装方式很简单VSCode 扩展市场搜OpenCode AI安装即可。要注意的是插件本身不带模型配置它读取的还是你全局那个opencode.json。所以如果你在终端里能正常用插件一般也能正常用如果插件里报模型不可用先回终端里排查再回来。实际用下来我最常用的场景是在编辑器中选中一段要重构的函数右键选择“发给 opencode”然后又切到终端看 Agent 的完整分析和执行过程。这样既保持了编辑器的阅读体验又能用终端 Agent 的完整能力。5.2 JetBrains IDEA 插件更“IDE”的体验JetBrains 系的插件在 IDEA 的插件市场搜opencode也能找到。安装后你可以从 IDE 的侧边栏打开一个 chat 面板和 VSCode 插件的核心逻辑一样本质是终端 Agent 的前端壳。JetBrains 插件有两点体验区别值得提一是对项目内符号的感知更好因为 IDE 本身索引了整个工程发送给 Agent 的上下文更精准二是它的 diff 展示在 IDE 的原生 diff 视图里合并不想接受的改动比在终端里容易很多。不过如果你是重度 Go 或前端开发者我个人反而更习惯 VSCode 插件的轻量感。JetBrains 全家桶本来就吃内存再叠加一个 Agent 进程有时候会让 IDEA 变卡。低配机器建议只用终端版或者用插件但不开自动补全。5.3 编辑器插件排查思路如果你在编辑器插件里遇到“连接不上 opencode 后端”之类的报错先别急着升级插件。多数情况是 opencode 的serve服务没有启动或者端口被占用。VSCode 插件本质上是连接到你本机运行的 opencode server 上所以终端里至少要保证opencode能正常启动。另一种常见情况是代理工具拦截了 localhost 请求导致插件连不上本地服务。这时候需要把 localhost、127.0.0.1 加入不走代理的名单很多本地开发工具连不上本地服务都是这个原因。6. opencode、Codex、Claude Code、Pi到底该选哪个 Agent6.1 四款工具的核心差异热词里“opencode codex claude code”和“opencode codex pi 哪个 agent 好用”这类问题很多。我先说说这四个工具在我眼里的定位差异。Claude Code是 Anthropic 官方推出的终端 Agent体验最成熟和 Claude 模型配合最好但它绑定 Anthropic 的模型生态你想接别的模型得靠环境变量这些变通手段不优雅。Codex CLI是 OpenAI 推出的同类产品主推 GPT 系列模型写代码能力很强尤其是当你习惯用 OpenAI 生态时它的工程化程度也很高但同样是闭源、绑定模型。Pi是一个相对轻量的 Agent 工具我理解它的定位是“快速任务执行器”不太强调多模型和复杂工作流适合简单问题快速处理。opencode是一个开源实现模型无关把“协议”和“模型”解耦这让我能以一个工具统管所有模型还能通过配置文件调整每一个细节。如果非要用一句话总结我的选型逻辑追求开箱即用且品牌模型效果好选 Claude Code 或 Codex追求自由定制、多模型切换、想深度参与工具演进选 opencode。Pi 适合做辅助性工具但我不会把它作为主力。6.2 什么时候我会推荐 opencode开箱即用的工具确实省心Claude Code 我第一次用大概十分钟就跑通了这种体验上的顺畅是真的。opencode 则需要理解 provider、model、配置文件这些概念初始门槛更高一点。但如果你属于以下情况我依然推荐 opencode你手里同时有多个不同家模型的 API Key或者在使用第三方订阅服务希望一个工具统管。你希望把团队的代码规范、约定封装成 Skills让 Agent 严格按团队节奏干活。你经常需要在服务器、CI 环境里跑非交互式的编码任务。你本身喜欢研究工具实现希望 Agent 的行为是可控、可改、可调试的。6.3 多 Agent 并存的实践最后说一下我的真实使用习惯其实我并没有完全抛弃其他 Agent。日常主力是 opencode用于重活、长任务和多模型切换短平快的小问题、简单问答我可能还是会用 Claude Code 跑一下因为它在纯 Claude 模型下的对话体验确实顺滑。两个窗口并存并不冲突反而能在对比中帮你更清楚认识到不同工具的长处和短板。7. 常见问题排查对照表这些坑我基本都踩过把搜索热词里出现频率很高的几个报错和问题整理成一张表方便你直接对号入座。报错 / 问题可能原因排查和解决办法无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名字安装后 PATH 未配置或未刷新重新打开终端检查opencode可执行文件所在目录是否在 PATH 里Windows 用where opencode验证The term opencode is not recognized...同上Linux/macOS 也可能是执行权限不足macOS/Linux 检查~/.local/bin或~/.opencode/bin是否在 PATH必要时chmod xthis model is not available in your country模型服务商对请求来源地区有限制检查服务商支持范围换用支持你所在区域的模型或服务商跟 opencode 配置无关unexpected server error. check server logsAPI 服务不可达 / Key 失效 / 模型名错误先用 curl 直接请求一次接口确认能否连通检查 Key 是否过期确认模型名和服务商列表一致Server error/502 / 503模型服务商侧拥堵或过载等一段时间重试换一个 provider 或模型临时过渡减少并发请求免费模型突然不可用 / 下线服务商下线了免费模型更新配置切换到备选模型考虑本地 Ollama 接开源模型opencode 启动很慢配置了太多 provider 且逐个探活精简 provider只保留真正使用的服务商LSP 开启后内存占用过高同时启动了太多语言服务器只配置项目实际用到的语言必要时减少 LSP 数量编辑器插件连不上 opencode本地 server 未启动 / 端口被占用 / 代理拦截 localhost先确保终端能正常启动 opencode把 localhost 加入不走代理的名单重启插件ccswitch配置后没生效opencode 没有正确读取当前激活供应商的环境变量检查 ccswitch 写入的环境变量名是否与 opencode 配置中的${env:...}一致重启 opencode 进程这个表看着简单每一条背后都是我翻过日志、试过错之后才写下来的。特别是 PATH 那个问题看起来像新手才会踩但只要换一台新机器、换一个操作系统总有人会在同一个地方卡住所以我还是把它放在了最显眼的位置。8. 最后分享一点我的实操心得如果你问我 opencode 最值得投入时间研究的功能是什么我的答案不是模型配置也不是 TUI 操作而是Skills。模型能力本身在快速迭代今天最强的模型三个月后可能就被超越但你把团队规范、个人偏好固化成的技能包是长期稳定的资产。换一个更强的模型后这些技能依然有效甚至因为模型更强而发挥出更大的作用。我现在的做法是每在一个项目里折腾出一种稳定的工作流就把它沉淀成一个 Skill 文件。比如“怎么识别这个老项目里的核心模块”“怎么写这个团队的提交信息”“前端 Bug 要怎么复现”全部用 SKILL.md 描述清楚。新项目来了直接让 opencode 调用对应的技能省去大量重复沟通成本。另一点心得是关于“模型切换的纪律”。opencode 支持多模型是好事但也容易让人陷入“这个模型不行就换一个”的循环反而浪费大量时间在切换和重复执行上。我现在给自己定了个规矩简单任务固定用一个性价比高的模型复杂任务才动用顶级模型并且在一个任务执行过程中不轻易换模型除非它确实在同一个问题上连续失败两次以上。最后再分享一个小技巧如果你喜欢在 CI 里挂一个定时的代码 review 任务可以用opencode run --agent配合 Skills让 Agent 每天自动扫描一次指定目录把发现的问题写进一个 Markdown 文件。这个用法在团队内推广后大家每天上班第一件事就是看自动生成的 review 报告效率比人工催 review 高了不少。opencode 能玩的方向还有很多希望这篇实操笔记能帮你少踩点坑把工具真正用起来。