最近两周我一直在终端里用 opencode 干活从读一个陌生的老项目、定位前端样式 bug到顺手改后端接口再跑通测试整个过程基本没怎么切出终端。如果你一直在关注 Claude Code、Codex 这类命令行 AI 编程代理那 opencode 这个名字你应该不陌生——它是目前社区热度很高的开源 agent 工具由 SST 团队开发底层用 Go 编写定位就是“终端里的开源 AI 编程助手”。这篇文章我不打算念文档而是从我实际安装、配置、用到踩坑的完整过程出发把 opencode 的安装方式、配置文件、Skills 机制、LSP 接入、Playwright 调试前端以及一堆报错的处理方法一次讲清楚。不管你是第一次听说 opencode还是已经装上了但不知道怎么配出顺手的工作流这篇文章都适合你。我会尽量把“为什么这么做”也讲明白而不是只丢给你一段配置让你复制。1. opencode 到底是什么为什么值得从 Claude Code / Codex 转过来1.1 从定位看 opencode终端里的开源 agent先花一分钟搞清楚 opencode 是什么。简单说它是一个跑在终端里的 AI 编码代理你给它一句话比如“帮我看看这个接口为啥超时”它会自己读代码、定位文件、给出修改方案甚至可以执行命令、跑测试、提交代码。这个使用体验和 Claude Code 很像但 opencode 是开源的而且它对模型提供商的态度非常开放——Anthropic、OpenAI、Google Gemini、DeepSeek、Ollama 本地模型甚至任何兼容 OpenAI 协议的自建服务都可以接进来。这里有一个容易混淆的点很多人会把它和另一个叫 Codex 的工具搞混。Codex 是 OpenAI 官方的 agent 工具闭源但功能很强Claude Code 是 Anthropic 官方的 agent闭源而 opencode 属于开源阵营里的后起之秀。如果你在意数据隐私、想用本地模型或者不想被绑定在某一家云厂商的生态里opencode 这种“自带模型路由”的开源方案就有天然优势。从项目托管和社区活跃度来看SST 团队本身就是做开发工具的他们对开发者体验的把控很到位。1.2 核心特性不完全清单我整理了一张表把 opencode 比较核心的特性列出来方便你对照自己的需求。特性说明我的实际感受TUI 交互界面终端里直接展示对话流、文件改动 diff、命令执行结果比纯文本交互直观很多改代码时能清楚看到每一处变化多模型接入支持多家云厂商模型、OpenAI 兼容服务、本地 Ollama我同时配了 Claude 和本地 Qwen按任务切换Skills给 agent 注入特定领域的指令比如“代码审查”“提交信息规范”相当于自定义技能包项目规范可以沉淀下来反复用LSP 集成通过语言服务器协议获得跳转、诊断、补全能力大幅减少了“agent 找不到符号定义”的情况MCP 支持通过 Model Context Protocol 外接工具比如 Playwright前端 bug 可以让 agent 自己开浏览器复现IDE 插件VS Code、JetBrains 系列都有官方插件终端里的修改会同步到 IDE 编辑器两边不打架高度可配置opencode.json 统一管理 provider、模型、skill、hook配一次之后基本不用再动换模型只是改一行这里面的 Skills 和 LSP 是让我觉得它不是一个“玩具”的关键。后面我会单独拿两节来讲怎么配、怎么用因为这俩功能在真实项目里价值最大。2. 安装这关怎么过从零到命令行能跑起来2.1 安装前的环境检查opencode 是 Go 写的编译产物是单个可执行文件所以安装本身不复杂但有几个前置条件容易忽略。首先你的系统需要有 curl 或者 wgetWindows 上建议直接使用 PowerShell 和 Git Bash 二选一其次如果你打算用 Go 命令安装那就需要提前装好 Go 环境推荐 1.22 以上版本。最后终端代理配置要确认好因为首次启动要从远端拉取模型配置公司网络如果有防火墙后面会报各种奇怪的网络错误这一点我后面会详细展开。在安装之前我建议先确认两件事一是你的终端是不是新的有时候装完 opencode 后命令找不到就是因为终端没有重新加载 PATH二是确认一下你本机有没有 Node.js 环境虽然不是必须但后面用 Playwright 做前端调试、启用部分 MCP 服务时Node 是少不了的。与其到时候再来补环境不如一次性装好。2.2 curl 安装和 Go 安装两种姿势选哪个opencode 官方推荐的方式是使用安装脚本。在 Linux 和 macOS 上直接执行下面这段命令curl -fsSL https://opencode.ai/install | bash这个脚本会检测系统架构和平台然后把可执行文件安装到用户目录下的.opencode/bin目录并把路径写进你的 shell 配置文件里比如.bashrc或.zshrc。安装完成后记得执行source ~/.zshrc或者重开终端然后运行opencode --version验证是否成功。如果你和我一样习惯用 Go 生态的命令行工具也可以直接go install github.com/sst/opencodelatest这样会安装到$GOPATH/bin或$HOME/go/bin下面。两种方式没有本质区别都是同一份源码编译出来的单文件。但有一点要注意用go install时你的$GOPATH/bin必须在 PATH 里否则命令照样找不到。我自己的习惯是优先用官方脚本因为它会自动帮你配 PATH省得手动改配置。2.3 Windows 和 PowerShell 下的典型报错热词里有一句很经典“opencode : 无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名。”这句话是 Windows 用户最容易撞见的。出现这个报错90% 的原因是安装程序把可执行文件放到了某个目录但该目录不在 PowerShell 的 PATH 环境变量里。排查路径很固定。先在 PowerShell 里执行where.exe opencode看能不能找到位置。如果找不到就去默认安装目录确认文件是否存在Get-ChildItem $HOME\.opencode\bin\opencode.exe文件存在但命令不生效那就手动把目录加进当前用户的 PATH[Environment]::SetEnvironmentVariable(Path, $env:Path ;$HOME\.opencode\bin, User)然后重开 PowerShell再执行opencode --version。这是我在多台 Windows 机器上实测有效的方案。如果你是走go install路线把路径换成$HOME\go\bin就行。3. 配置文件讲透模型、Provider、Skills 一次配明白3.1 opencode.json 是核心先搞懂几个关键字段opencode 的配置采用一个 JSON 文件管理默认路径在项目根目录的opencode.json如果要在所有项目里全局生效可以放在~/.config/opencode/opencode.json。这个想法和.editorconfig、settings.json类似——每个项目可以有自己的覆盖配置用户级配置作为兜底。我一般把通用的模型凭证和 Skills 放全局把项目专属的指令放项目里。一份最基础的配置长这样{ $schema: https://opencode.ai/config.json, provider: { anthropic: { options: { apiKey: {env:ANTHROPIC_API_KEY} }, models: { claude-sonnet-4: { name: Claude Sonnet 4 } } }, openai: { options: { apiKey: {env:OPENAI_API_KEY} } }, ollama: { models: { qwen2.5-coder:14b: { name: Qwen Coder 14B } } } }, model: anthropic/claude-sonnet-4 }注意{env:ANTHROPIC_API_KEY}这种写法它的意思是运行时从环境变量里读取密钥而不是把密钥明文写在配置文件里。这个习惯非常好能避免配置文件不小心被提交到 Git 仓库导致密钥泄露。provider 下面的 models 字段可以单独重命名或指定模型上下文长度、价格参数不过绝大多数情况下默认值就够了。还有一个非常实用的字段是指令instructions。你可以把团队的编码规范、提交信息的格式要求、代码风格的偏好写进去opencode 在生成代码时会把这些内容当作系统提示词的一部分。比如我就在全局配置里写了“默认使用中文回答注释用中文变量命名遵循项目风格”。3.2 模型选择与“免费模型”的正确姿势很多刚接触 opencode 的人会问能不能白嫖模型答案是能但你要分清楚哪类“免费”才靠谱。一种靠谱的免费方案是本地模型也就是通过 Ollama 跑 qwen2.5-coder、deepseek-coder-v2 之类的小模型。好处是隐私好、完全免费、离线可用缺点是模型能力有限复杂代码生成和上下文理解会明显弱于一线闭源模型。如果你只是拿它做代码解释、生成单元测试、修复简单 lint 错误本地 14B 左右的小模型完全够用。另一种是云厂商的免费额度比如部分厂商会提供限时免费或低价的模型体验OpenRouter 这类聚合平台偶尔也有免费的模型端点。这种方案的优势是模型能力强能跑大型任务但你要做好心理准备免费端点通常不稳定限流、掉线时有发生。我见过很多人配置了某个免费模型地址第二天就不能用了然后跑过来说“opencode 坏了”。这不是 opencode 的问题是免费模型自身的可用性问题。我的建议是正式项目用稳定的付费模型本地做实验才用免费或本地模型。还有一点要提醒如果遇到 This model is not available in your country. 这样的报错意思是你选的模型服务不支持你当前所在的区域。这个错误来自上游模型服务商而不是 opencode 本身。合规的做法是先确认你所在区域是否在服务商的支持列表里如果确实不支持就换一个当前区域可用的模型或者选择官方支持该区域的接入渠道。3.3 Skills 机制让 agent 按你的规范干活Skills 是 opencode 里一个很容易被忽略但价值极高的功能。通俗理解它就是一组“技能包”每个技能包包含一段专业指令和可选的参考文件当你的任务匹配到某个技能时agent 会先加载技能再处理你的请求。举例来说你可以给项目定义一个“代码审查”技能。在.opencode/skills/review/SKILL.md里写出具体规范--- name: code-review description: 当用户要求代码审查或 review 时使用本技能。 --- 你是一名资深代码审查者。请按照以下顺序审查改动 1. 先读取 git diff理解本次改动的意图。 2. 检查命名、代码结构、异常处理和潜在的性能问题。 3. 针对每个问题给出严重级别标记critical / major / minor。 4. 最终汇总输出审查报告。然后在配置里注册这个技能{ skills: { review: { name: code-review, description: 执行代码审查, path: .opencode/skills/review } } }这样当你输入“帮我 review 一下最近的改动”opencode 会自动匹配到 code-review 技能然后按你定义的流程执行。这比你在提示词里反复粘贴一大段规范要优雅得多而且同一套技能可以在不同项目里复用。社区里也有人把 oh-my-claudecode 那套配置管理的思路迁移到 opencode 上用它来统一管理 Skills、自定义指令和快捷键。这个方向是可行的因为 opencode 的核心配置就是 JSON完全可以用脚本批量生成和同步。3.4 用 hook 和 MCP 扩展能力边界除了 Skillsopencode 还支持 hook 和 MCP。hook 可以在特定事件时触发外部命令比如在 agent 执行命令前提示你确认或者在每次会话结束后把对话摘要写入 Logseq。MCP 则是连接外部工具的标准协议后面会讲到的 Playwright 就是通过 MCP 接进来的。如果你熟悉 Claude Code 的生态会发现这套扩展模型和它非常接近但 opencode 的配置更集中基本都在一个 JSON 文件里解决。4. 日常开发实战接手项目、LSP 定位、Playwright 修前端 Bug4.1 用 opencode 快速接手一个陌生项目“opencode 接手开发项目”是热搜词里我最有共鸣的一个场景。新入职一家公司或者接手老项目时代码量大、文档缺失、业务逻辑复杂过去靠人肉读代码往往要花两三天。用 opencode 可以把这个过程压缩到一两个小时。我的做法是三步走。第一步在项目根目录启动 opencode先让它对整个仓库做一次结构扫描生成项目地图opencode然后在对话里输入“请先扫描项目根目录总结项目的技术栈、目录结构、入口文件和关键模块输出一份 README 风格的项目概览。”这不是让 agent 猜它是真的会去读文件所以输出质量取决于项目里代码的可读性但大体上能给你一个可信的骨架。第二步是局部深入。让 agent 针对某个模块生成调用关系图比如“追踪用户登录接口从路由到数据库的完整调用路径列出涉及的文件和函数”。这个过程里它会把相关文件打开、跳转、阅读甚至主动去检查配置。如果你配合了 LSP它还能准确识别函数定义、引用位置检索体验比单纯靠 grep 好太多。第三步是动手改造。我的建议是每次改动前先问 agent 要一个计划确认影响范围再让它动手。opencode 在生成改动时会给出类似 Git diff 的展示你可以一个一个文件确认后再采纳。这种半自动的节奏既保留了 AI 的效率又不至于让代码库失控。4.2 LSP 接入让 agent 看懂代码跳转LSP 全称 Language Server Protocol是编辑器与语言服务器之间的通信协议。VS Code 里的跳转定义、智能提示、诊断信息背后都是 LSP 在起作用。opencode 接入 LSP 之后agent 就不再靠正则匹配或者硬搜来找代码了它可以直接问语言服务器“这个符号的定义在哪”“这个文件有什么语法错误”。配置方式是在 opencode.json 里加 lsp 字段{ lsp: { typescript: { command: typescript-language-server, args: [--stdio] }, golang: { command: gopls }, python: { command: pyright-langserver, args: [--stdio] } } }装好对应语言服务器之后重启 opencode然后输入“找出这个仓库里所有类型定义在 X 处的引用”。你会发现 agent 给出的答案准确率明显上升不再是“我猜可能是这个文件”。尤其是 TypeScript、Go 这种对类型敏感的语言LSP 简直是刚需。我用下来最大的体会是opencode 读取大项目时更“稳”了不会因为符号名太多而找错文件上下文质量提升明显。4.3 用 Playwright 替你做前端 Bug 复现“opencode playwright 怎么测试前端 bug”这条热搜说到了前端开发者的痛处。以前 agent 只能帮你读代码找 bug 原因但前端问题往往和浏览器环境强相关你不实际打开页面很难确认。opencode 通过 MCP 接入 Playwright 之后agent 可以自己启动浏览器、访问页面、点击按钮、读取控制台日志、截图然后根据实际表现来推断问题。配置非常简单主要是在 opencode.json 里添加一个 MCP 服务{ mcp: { playwright: { type: local, command: [npx, playwright/mcplatest] } } }使用场景举个例子。你对 agent 说“打开本地开发服务器访问登录页输入错误的账号密码点击登录然后告诉我控制台报了什么错。”agent 会逐步执行这些操作再把看到的现象反馈给你。它还能主动定位按钮元素、等待网络请求完成、截取关键页面相当于一个能替你操作浏览器的测试工程师。我第一次用这个功能时也有点怀疑担心 agent 在浏览器里“乱点”。实际测试下来只要你的指令描述得清楚它的操作路径通常很克制。我一般会让它“打开页面 - 读取 console 日志 - 截图”这个最小流程就足以复现绝大多数前端运行时错误。如果真的需要更复杂的用户路径比如登录后跳转再操作也建议拆成几步来指挥这样每一步出现偏差时更容易定位。4.4 与 VS Code / JetBrains 插件联动很多朋友反馈说纯终端的 TUI 虽然高效但看 diff 和编辑代码还是不如 IDE 顺手。opencode 也意识到了这一点提供了 VS Code 扩展和 JetBrains 系插件。装上之后opencode 在终端里的文件修改会以外部文件变更的形式同步到打开的项目里你可以在 IDE 里直接查看 diff、手动调整然后保存回去。这里有两个细节需要提醒。第一是版本要配套插件市场里搜 opencode 时注意看它要求的 opencode CLI 最低版本如果 CLI 太旧插件连接会失败。第二是快捷键和命令面板VS Code 里可以用命令面板直接启动一个会话JetBrains 插件也支持类似的入口不用切到终端就能对话。插件本质上是 CLI 的另一个前端所以核心配置还是以 opencode.json 为主插件本身不需要额外设置。4.5 和其他编程 agent 怎么选codex、claude code、opencode、pi热词里有一句“opencode codex claude code, opencode codex pi 哪个 agent 好用”我干脆把这几个主流选择放在一起聊聊。我的结论是没有绝对最好的 agent只有最匹配你工作流的工具。Agent开源模型绑定界面适合人群Claude Code否主要是 Anthropic 模型终端交互重度 Claude 用户追求开箱即用Codex否OpenAI 系模型终端 IDE 集成深度使用 OpenAI 生态的团队opencode是几乎任意模型支持本地模型TUI IDE 插件在意灵活性和自主可控的开发者pi专业版 agent 工具不完全各家配置较复杂终端交互愿意花时间调参的极客我个人已经把日常开发主力切换到了 opencode原因有三一是它在模型上不锁死我可以根据不同任务切换最强模型或低成本模型二是开源社区更新快新功能迭代频繁三是配置透明出了问题我能看日志、改配置而不是关在一个黑盒里。当然如果你已经深度依赖 Claude Code 的生态也不是非要迁移。工具只是手段能解决问题就是好工具。5. 高频报错与解决实录5.1 unexpected server error. check server logs 怎么查这是 opencode 用户最常碰到的报错之一热词里也原样出现了。报错信息只会说“发生了服务器错误请检查服务器日志”真正原因多种多样。第一次遇到时我一度以为是 opencode 本身的 bug后来发现 80% 的情况是模型 API 那边出了问题。排查顺序我建议按下面来。第一步确认网络链路是否通比如能否直接请求到 API 的域名公司内网可能有额外的防火墙。第二步确认模型 ID 是否写对有些自定义模型的 ID 和展示名不一致填错了就会报这个错。第三步打开 opencode 的调试日志在启动命令后加--log-level debug或者直接查看日志目录下的文件。Linux/macOS 一般在~/.local/share/opencode/logWindows 在用户目录下的.local/share/opencode/log。日志里会有更具体的 HTTP 状态码和错误内容拿到 401、403、404、429 这样的状态码后问题定位就快了。如果日志显示是 429说明你请求太频繁或者额度超了换个时间再试或者检查模型的 rate limit。如果是 401说明 API key 无效或者环境变量没传进去。5.2 This model is not available in your country. 处理思路这个报错本质上是上游模型服务按区域做的限制。opencode 本身只是调 API它不会判断你在哪个国家也不应该用非正规手段去规避这个限制。我的建议是稳一点操作。第一步把报错原样贴给 agent让它确认当前配置的模型是不是限制区域模型。第二步如果是去模型服务商的官网查你这个区域是否在支持列表里如果确实不支持就更换成支持区域的模型或者选择其他支持你区域的本地模型。很多情况下同一家厂商也有多个模型可选换一个不受区域限制的型号就能解决。第三点如果你是通过模型网关或代理服务访问请先确认这类使用方式是否符合服务商的条款尽量选择官方认可的接入方式。我一直觉得工具的稳定性和合规性应该排在第一位支付一点模型费用远比折腾半天最后被限流、封 key 要划算。5.3 日志、调试模式和异常退出opencode 用了 Go 语言编写稳定性和并发处理能力都不错但偶尔也会遇到异常退出或者命令卡住的情况。我第一次遇到好像“死循环”的任务时第一反应是 CtrlC 强杀后来才知道有更好的方式。如果你要调试某个指令为什么没按预期执行可以用详细模式启动opencode --log-level debug这样它会把每一步的思考过程、调用了哪些工具、读了多少个文件、请求了哪个模型全部打印在日志里。平时正常使用不需要开这个级别日志文件量会很大。如果遇到 agent 卡在一个工具调用上不返回排查它调用的那个命令或服务是不是挂了比如 Playwright 的浏览器进程没有正确退出也可能导致下一次任务启动变慢。5.4 我整理的一些小建议最后把这段时间使用 opencode 攒下的一些小经验放这里不算成体系但都是实际有用的。第一密钥管理一定要用环境变量。我用export ANTHROPIC_API_KEYxxx写在本地 shell 配置里opencode 通过{env:ANTHROPIC_API_KEY}读取。这样即使配置文件被误提交到 Git密钥也不会跟着泄露。第二改动之前先让 agent 出方案。一句“先别改告诉我你打算怎么改”能帮你规避大部分无效生成尤其是在接手老项目时这个习惯非常值钱。第三善用.gitignore。opencode 的会话记录、缓存、日志文件目录不要混进版本控制我见过有人把整个.opencode目录提交到仓库里面可能包含敏感信息或大体积日志很没必要。第四如果你同时使用 ccswitch 之类的模型网关或密钥管理工具注意它们和 opencode 的关系opencode 通过环境变量或配置指向对应服务的地址网关负责把请求分发到不同模型。这类工具适合搞多模型统一管理的人但配置时务必确认使用方式符合服务条款避免因为接入方式问题影响稳定性。6. 结尾一点个人体会如果你问我 opencode 到底值不值得花时间迁移到日常开发流程里我的答案是值得。它不完美有些地方还需要打磨比如大型项目下上下文管理还有优化空间部分 IDE 插件的联动偶尔要重启 CLI 才生效但这不妨碍它成为我目前最顺手的终端 agent。我特别喜欢它的配置透明性——出问题能查日志能力不够能加 Skills模型不合适能随时切换这种“工具由我掌控”的感觉是闭源 agent 始终给不了的。最后再分享一个小技巧不要一上来就追求复杂的配置。我建议你第一次使用时只配一个你手上已有的模型随便找个项目跑通“读代码-改代码-跑测试”的最小闭环再逐渐加 LSP、Skills、Playwright 这些进阶功能。循序渐进地调你会发现 opencode 的体验是越用越顺的。看完这篇文章如果你能顺利把它跑起来并且在这个基础上配出一套自己舒服的工作流那我觉得这篇长文就没白写。