如果你最近刷开发者社区大概率会看到opencode这个词。我先说结论它是一套完全开源的 AI 编程助手主要跑在终端里也能通过插件嵌进 VSCode 和 JetBrains 系列 IDE核心作用就是让你用自然语言指挥它读代码、改代码、跑测试甚至在浏览器里复现前端 bug。和不少朋友一样我也好奇过它和 Claude Code、Codex CLI 有什么区别实际用了一个多月之后我把它当成了日常开发管线里的主力工具之一。这篇东西就是我基于自己踩坑经验整理的一份 opencode 上手参考没有厂商通稿纯粹是答应给团队同事写的一份内部手册顺手发出来给同样在折腾 opencode 的人。1. 先搞清楚 opencode 到底是个什么东西1.1 项目定位与来源opencode 是一个从命令行里运行的 AI 编码代理AI coding agent。它的核心玩法非常直接你在终端里执行opencode它会启动一个交互式会话你可以让它“解释这段代码”“帮我重构这个函数”“在这个接口里加鉴权”它会基于当前项目的文件内容和对话历史给出可执行的建议甚至直接帮你改完文件。和传统的 AI 补全插件相比它更像一个能真正“上手干活”的同事而不是只会在编辑器右下角提示下个单词的助手。它来自一个做开源 Serverless 工具出身的团队项目挂在 GitHub 的sst/opencode下。所以如果你问“opencode 是哪家公司的”准确答案不是“某某大厂”而是“SST 团队维护的开源社区项目”。这个定位意味着两件事一是它没有厂商绑定模型可以自由切换二是它的迭代颗粒度非常细几天不看命令行参数可能就换了写法。我见过不少刚上手的人卡在这一步把 alpha 版本的命令套到新版本上然后到处报错。1.2 和 Claude Code、Codex CLI 的差别聊 opencode 避不开它和 Claude Code、Codex CLI 的对比。很多人最早接触终端 AI 代理就是从这两个工具开始的甚至有一段时间网上全是“AI 编程 agent 哪个好用”的讨论。我的看法是三者底层思路都是“给模型一个可以读项目、改文件的沙箱”但 opencode 有几个明显不同的性格模型中立。Claude Code 和 Anthropic 模型绑定很深Codex CLI 又和 OpenAI 走得太近。opencode 从设计上就允许你对接 OpenAI、Anthropic、Google也可以接各种兼容 OpenAI 协议的网关或本地模型。这意味着你可以用一个工具干所有模型的活。配置更透明。它的配置文件、Skills 目录、项目级说明都以普通文件形式摆在那里你可以直接打开看也方便纳入 Git 管理。环境要求更轻。因为是用 Go 写的单文件二进制分发跑起来比某些 Node 包更轻至少我的旧笔记本上没有明显卡顿。当然这不代表 opencode 比 Claude Code 更强。Claude Code 的长处在 Anthropic 模型加持下复杂多步任务的理解能力非常突出Codex CLI 在 OpenAI 生态里也足够顺手。opencode 的优势是“自由”模型自由、配置自由、甚至技能自由。如果你习惯在不同模型之间横跳或者需要在同一套工作流里接入多种模型opencode 会更舒服。1.3 适合谁、不适合谁适合使用 opencode 的是已经在用 Git、能看懂命令行报错并且愿意把“AI 代理”当作开发辅助工具而不是万能神的开发者。前端、后端、全栈都可以它不太挑语言。因为它能读项目结构和代码定义所以对一些遗留项目的接手场景也特别有用。不适合的也很明确如果你完全没写过代码指望打一句“帮我做个 APP”就能交付产品那 opencode 和市面上其他 AI 编程工具一样满足不了。它不是无代码平台而是一个需要你有基本工程判断力的辅助工具。你在项目里注入越多的结构性信息比如 README、AGENTS.md、测试用例它回馈的效果越好。2. 安装、接入模型与初始化配置2.1 在 Windows、macOS、Linux 上安装 opencodeopencode 的安装方式不算复杂但不同系统踩的坑不一样。我分别说下我实测过的路线。npm 全局安装兼容性最好也最不容易出幺蛾子npm install -g opencode-ai装完在终端执行opencode --version能看到版本号就说明安装成功。如果你的系统里有 Go 环境也可以直接用 Go 安装go install github.com/sst/opencodelatest这种方式的好处是会和 Go 的工具链保持较近的关系缺点是如果你的 Go 版本太老可能遇到编译错误。macOS 用户还可以用 Homebrewbrew install sst/tap/opencodeWindows 用户如果不想用 npm也可以去 GitHub Releases 页面下载对应的 Windows 压缩包解压后把可执行文件所在目录加到PATH里。这里要特别提醒一句很多 Windows 下的“opencode 无法识别”问题都是因为 PATH 没配好或者终端没有重启而不是软件装坏了。安装完成后我建议先执行opencode试试能不能正常启动界面。第一次启动的时候它会引导你选择模型和填写 API Key。如果你只是想快速看一看长什么样也可以先用一个已经配置好的“模型提供方”直接进入。后面讲到配置文件时你会明白这一层其实是在帮你生成一个初始的配置文件。2.2 模型接入你能用哪些模型opencode 的模型接入层是我见过最不折腾的。它默认支持主流厂商的模型也会读取环境变量。比如你想用 Anthropic 的 Claudeexport ANTHROPIC_API_KEY你的Key opencode --model anthropic/claude-sonnet-4如果你想用 OpenAI 的模型export OPENAI_API_KEY你的Key opencode --model openai/gpt-4o命令里的provider/model这种写法是 opencode 的通用模型寻址规则。你也可以在交互界面里通过/models命令随时切换模型不用退出会话重开。关于“opencode go”这个词我在热搜里看到很多人在问。其实要把这个词拆成两层看一层是“用 Go 语言安装 opencode”另一层是指部分第三方模型服务商会把订阅套餐命名为“OpenCode Go”之类的花名。前者就是go install后者只是一个商业套餐名称。实际配置的时候你只需要关心这个套餐提供的 API 地址、模型名和 Key在配置文件里填进去就行。不用被名称带着走。如果你接入的是兼容 OpenAI 协议的服务可以在配置里指定一个自定义 provider把baseURL指向服务商提供的地址模型名写服务商给你的名字即可。不要一上来就找“必用模型攻略”先把自己手头已有的 Key 填进去能跑通一次再考虑优化模型选择。2.3 配置文件把常用设置固定下来opencode 的配置文件一般放在项目根目录的opencode.json或者用户目录下的~/.config/opencode/opencode.json。我建议团队项目把opencode.json提交到 Git 里但把 Key 用环境变量引用这样新成员拉下代码就能直接跑也不会泄露密钥。一个基础配置大概长这样{ $schema: https://opencode.ai/config.json, provider: { default: anthropic, anthropic: { apiKey: {env:ANTHROPIC_API_KEY}, model: claude-sonnet-4-20250514 } }, instruction: 请先阅读项目 README回答问题时尽量给代码示例。 }这里有两个容易误会的点。其一{env:ANTHROPIC_API_KEY}这种写法是让 opencode 去环境变量里取 Key而不是真的把字符串“{env:...}”当成 Key。很多人第一次不会配置就是死在这一句上。其二instruction字段可以写一些全局性的指令它相当于一个常驻的系统提示词。你想让 AI 更严谨、更简洁、更偏向中文回答都可以写在这里。如果你的模型需要自定义 baseURL可以追加mygateway: { apiKey: {env:MYGATEWAY_API_KEY}, baseURL: https://your-gateway.example.com/v1, model: your-model-name }再次强调baseURL 填的是你实际使用的服务商 API 地址。opencode 对 OpenAI 兼容协议的适配非常宽容很多模型服务商都能用这种方式接进来。配好之后用/provider命令查看当前 provider 列表确认能列出你配置的 provider 就算成功。2.4 把 opencode 装进 VSCode 和 IDEAopencode 在终端里的体验已经足够好但如果你还是习惯在编辑器里看代码官方也有对应的插件生态。VSCode 用户直接在扩展市场搜“opencode”安装由 opencode 官方发布的扩展即可。装完之后你可以通过侧边栏面板打开 AI 聊天窗口。插件会自动识别当前打开的文件和项目也会复用你在命令行里配置好的模型和全局设置。有一点要注意VSCode 插件第一次启动时如果提示“找不到 opencode”大多是因为插件在 PATH 里找不到可执行文件。Mac 上如果遇到这个问题通常需要确认 npm 全局 bin 目录是否在 PATH 里Windows 上则需要重启 VSCode或者手动在设置里指定 opencode 可执行文件的完整路径。JetBrains 系IDEA、PyCharm、WebStorm 等也有类似插件在插件市场安装后可以从 Tool Window 里找到 opencode 面板。IDEA 里配置自定义模型时界面字段少容易让人摸不着头脑。我的经验是直接在命令面板里运行opencode把配置交给命令行去处理IDEA 插件主要负责展示和交互底层命令还是共享同一套配置。这样可以避开 IDE 插件自定义 UI 的局限。3. 从跑通到进阶核心功能实操3.1 日常对话与项目任务在项目根目录执行opencode就会进入交互式终端。除了普通对话它支持一些斜杠命令我用得最多的是/init和/agents。/init会扫描当前项目结构生成一个AGENTS.md文件里面写了项目概括、代码风格约定和常用命令。这相当于给 opencode 一份“项目入职手册”。接手陌生项目时先跑一次/init再开始改代码效果比直接问“这项目是干嘛的”好得多。/agents可以进入多代理模式。你可以创建“测试工程师”“代码审查员”“文档助手”等不同角色的代理让它们分工处理同一个项目。比如我接手一个老前端项目时会让“重构代理”分析组件结构同时让“测试代理”找出缺失的测试用例两个会话并行最后在聊天里汇总。这种工作流非常适合 legacy code。实际操作里有个小技巧每次对话不要太贪心。一次只给一个明确目标“修复 login 页面的按钮样式”远比“把这个项目优化一下”有效。opencode 在处理模糊指令时容易陷入自我感动式修改最后改出一堆你没要求的代码。明确目标、限定范围才能让它成为靠谱的帮手。3.2 Skills把自己的工作流教给它Skills 是 opencode 里非常实用但容易被忽略的功能。你可以把它理解为一组可复用的“技能说明书”里面写清楚某个任务怎么做、参考什么规范、输出什么格式。在项目里创建一个.opencode/skills目录里面每个技能单独放一个子目录并包含一个SKILL.md文件。例如.opencode/skills/add-unit-test/SKILL.mdSKILL.md的内容没有强制模板但我习惯用下面的结构--- name: add-unit-test description: 为指定函数或模块增加单元测试优先使用项目已有的测试框架。 --- ## 执行步骤 1. 先查看项目测试配置文件确认框架和运行命令。 2. 为目标模块创建 .test.js 文件。 3. 用例覆盖正常输入、边界输入、异常输入。 4. 运行测试命令输出结果并修正失败用例。写好之后你在 opencode 对话里提到“给这个模块补测试”模型就会自动读取相关技能并按照里面的步骤执行。你还可以把团队编码规范、Git 提交规范、接口设计约定都写进 Skills。这样即使团队换人AI 代理也依然能保持一致的输出习惯。网上经常看到有人问“opencode superpowers”这其实是某个热门的技能集项目相当于把 Claude Code 里的 superpowers 技能库搬到 opencode 里用。类似的技能包很多安装方式基本都是把技能目录克隆到.opencode/skills下面再检查一遍里面的命令和路径是否适配自己的项目。我不建议无脑装一大堆技能太多模型反而不知道该选哪个。保留 3 到 5 个高频技能比囤一百个更好用。3.3 Memory善用项目级记忆opencode 的“记忆”不完全等同于聊天记录它更多是指项目上下文。这个项目上下文可以来自几个地方AGENTS.md、opencode.json里的instruction、以及.opencode/目录下的说明文件。我制作一个很简单的记忆机制在项目根目录放一个AGENTS.md里面记录项目常用的命令、模块结构、代码风格规范并且每次和 opencode 开新会话时第一句先问“先读 AGENTS.md”。一旦它读过后续对话的提醒效果就会好很多。如果你发现每次都要让模型重新理解项目背景可以专门再写一个.opencode/project-context.md把那些“说过一次就不该重复说”的内容放进去比如“这个服务依赖 Redis本地测试需要先启动 docker-compose 里的 redis 容器”“生产环境使用 Vite 构建不要直接改 dist 目录”。这些信息对 AI 代理来说就是项目记忆。长期维护下来一个项目积累的说明文件越多opencode 的表现就越像一个熟悉项目的资深同事而不是一个每次都要重新介绍自己的实习生。有人专门去折腾opencode memory这类第三方扩展我建议先把项目级说明文件跑通。如果说明文件组织得足够好90% 的需求都能覆盖而且它是最稳定、不依赖任何额外服务的方式。3.4 用 LSP 增强代码理解opencode 支持通过 LSPLanguage Server Protocol来获取代码的精确语义信息。LSP 是编辑器里常见的“智能提示协议”它让工具知道某个符号在哪里定义、被谁引用、类型是什么。opencode 接入 LSP 之后就不只是拿正则搜代码而是真正理解代码结构。我的实际经验是在 TypeScript 项目里接入 LSP 后AI 回答跨文件问题时准确率高了不少。比如问“这个 service 在哪些地方被引用”没有 LSP 时它可能只靠关键词搜索结果不全有 LSP 后它能基于符号索引给出完整引用列表。配置方式在官方文档里有说明。大致是在opencode.json的lsp字段里指定要启用的语言服务器例如 TypeScript 项目可以启用typescript-language-server。第一次配置时建议打开日志观察是否能正常连接。LSP 服务如果启动失败opencode 通常会降级成普通文本搜索不会崩但效果会差一截。如果你不太想在配置文件上花时间也可以直接靠项目里的tsconfig.json或pyproject.toml等文件帮助模型理解效果略弱但胜在简单。3.5 用 Playwright 复现和修复前端 bug“opencode 加 Playwright 测前端 bug”是最近讨论很多的一个场景。Playwright 是浏览器自动化测试框架可以打开真实浏览器执行点击、输入、断言等操作。把 Playwright 和 opencode 结合起来就能让 AI 代理不只看代码还能“看见”页面实际渲染的样子。最常见的做法是你先在项目里写一个最小复现脚本用 Playwright 打开目标页面把页面截图或控制台错误输出保存下来然后让 opencode 根据这些信息定位问题。举例来说我遇到过某个菜单在特定分辨率下遮挡内容的问题直接看代码很难发现。我让 Playwright 在 1366x768 下打开页面并点击菜单拿到截图和控制台报错再交给 opencode。它把样式代码和相关组件的布局逻辑分析一遍很快指出是某个绝对定位的元素没做响应式处理。如果你希望 opencode 自动跑 Playwright 测试可以让它读取项目的 Playwright 配置和现有用例然后让它生成新的测试脚本并执行。但有一点必须提醒不要让它在未知环境里随意执行命令。至少提前在AGENTS.md里写明“测试环境启动命令”“测试账号密码存放位置”这类信息避免它跑错环境。前端自动化测试本质也是在操作真实系统尽量在本地或临时测试环境里跑不要让它直接动生产环境。3.6 接手陌生项目先让它当“实习生”再让它干活很多人拿到一个陌生项目期望 opencode 直接给出重构方案这其实有点难为它。更稳的路径是先让它阅读代码库总结项目结构、技术栈、启动方式和核心流程再问“如果要改某个功能涉及哪些文件”。等它回答得八九不离十再让它动手改。你可以这样下达第一波指令请先不要修改任何代码。只要做三件事 1. 阅读 README 和项目配置文件告诉我技术栈和启动方式。 2. 梳理 src 目录或后端代码目录的核心模块。 3. 列出你认为最重要的 5 个文件并说明理由。这一步看着保守其实非常有效。它让模型先建立项目地图再去具体位置干活防呆效果好很多。如果直接让它改一个你还没理解的功能它很可能在错误的位置打补丁改完你还要花时间回滚。4. 常见问题与排查技巧实录4.1 Windows无法将“opencode”项识别为 cmdlet这个报错是 Windows 用户最常遇到的我在多个群里看到过。完整报错是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。原因很简单系统找不到 opencode 的可执行文件。常见解决办法按顺序排查确认安装成功npm ls -g opencode-ai如果有输出说明包已安装。找到 npm 全局目录npm prefix -g这个目录下的内容通常就是可执行文件所在位置。把该目录加到系统PATH在 Windows 设置搜索“环境变量”在Path中加入对应路径。重启终端再执行opencode --version。如果你用的是免安装的压缩包最好把解压后的目录固定在一个稳定位置再添加 PATH不要随手解压到下载文件夹又清空。另外VSCode 里如果终端刚启动仍然找不到命令重启一下 VSCode 而不是只开新终端通常能解决。4.2 模型层报错this model is not available in your country这个报错信息很长但核心是模型服务方根据你的账号、IP 或套餐限制不允许当前地区使用某个模型。很多人第一反应是找“变通”方案我建议先冷静处理。正确的处理流程是先在配置里换成另一个可用模型比如从 p 家模型换成 n 家模型或者从大模型换成服务商明确标注支持当前区域的模型。检查模型名是否拼写正确。有些模型名带了日期后缀少写一个版本号就会报这种错。检查套餐详情。部分商业套餐只包含特定模型接入权即使你在配置里写了未购买的模型也会报 unavailable。联系服务商确认你的账户到底能用哪些模型。这是最稳妥的方式。我理解大家想用好模型的心情但我不会在任何文章里教人用灰色手段绕过地区限制。AI 工具链越来越正规老老实实用正规渠道获取的模型反而最省心。opencode 的价值在于把模型选择权交给你而不是让你去钻空子。4.3 unexpected server error. check server logs这是后端类错误常见于配置了自定义网关或第三方 API 的情况。报错本身只告诉你“服务器返回了意外错误”真正原因要看服务端日志。本地能做的排查包括可能原因排查方法API Key 错误检查环境变量是否被正确读取可以先在终端echo $KEY确认模型名错误确认模型名和 provider 支持的名称完全一致账户余额或配额不足登录服务商控制台查看配额baseURL 指向错误确认路径以/v1结尾没有重复拼接路径网络不通或公司内网限制确认能正常访问 API 域名必要时换网络试试如果你用的是本地模型服务还有一个常见坑本地模型服务没有启动或者监听的端口和配置里不一致。先把本地服务用 curl 手动调一下如果能正常返回再让 opencode 去对接。4.4 插件和编辑器集成不生效VSCode 插件运行正常但对话时一直不响应多半是插件没有找到 opencode 命令行工具。可以在插件设置里手动指定 opencode 路径。Mac 用户如果用了 Homebrew可执行文件通常在/opt/homebrew/bin/opencode或/usr/local/bin/opencodeWindows 用户则要看 npm prefix 对应的目录。IDEA 插件不显示面板先确认安装的是官方支持当前 IDE 版本的插件而不是搜到了同名第三方插件。装完重启 IDE再打开 Tool Window 列表找 opencode。如果还是看不到可以用 IDEA 的“清除缓存并重启”功能这一步解决了不少玄学问题。4.5 其他注意事项不要在opencode.json里写明文 Key除非你确认这个项目不会上传到远端。大项目首次扫描会比较慢耐心等它构建索引不要反复 CtrlC。模型输出的改动先 diff 再接受我从来没有全盘接受过 AI 的批量重构。它能在 80% 的场景给出正确方案但剩下 20% 仍然需要人判断。5. 一点个人体会我折腾 opencode 的时间不算长但它已经改变了我接手项目和写测试代码的方式。几个模型换着用哪个更顺手就切到哪个配置文件一次配好后面基本不需要再动。最大的体会是工具本身只是起点决定它表现上限的是你愿不愿意为它维护项目说明、技能库和清晰的指令。这就像带一个能力很强但不了解公司的新人你给它的上下文越充分它就越能发挥出真实水平。如果你准备尝试先从一个小项目开始跑通一次“读代码、改代码、跑测试”的闭环再逐步把它引入到核心仓库。opencode 的未来还会迭代很快社区插件也会越来越多但核心的使用逻辑短期内不会变把项目说清楚把模型选对把任务拆小。能做到这三点它会成为你开发流程里最值得留着的搭档之一。