1. 从一次工具迁移说起opencode 到底是做什么的最近小半个月我把日常的编码主力从一个很火的商业 Agent 慢慢换到了 opencode 上。起因很简单我想在同一个终端工具里自由切换不同厂商的模型又不想把所有代码会话都绑在一家生态里于是试了一圈开源的终端 AI 编码助手最后留下的是它。这个 opencode 是什么说得直接一点它是一个用 Go 写的开源 TUI 编程助手放在命令行里运行给它一个任务它会自己翻你项目里的代码、调用工具、改文件、跑测试然后把改动结果拿给你审。很多人在搜索记录里看到“opencode go”这个词其实就是指它是 Go 语言实现这件事不是某个独立命令。因为核心是用 Go 写的所以启动速度快、单文件分发、跨平台安装也简单这是它和一大批 Node 系 AI 命令行工具最直观的区别。如果你也正在纠结 opencode 是不是又一个换壳玩具或者刚下载完就在 Windows 上碰到“无法将 opencode 项识别为 cmdlet”的报错又或者听别人说它能接免费模型但不知道具体怎么配这篇文章基本就是为你准备的。我会从它是什么、到底解决了什么问题开始一路讲到安装、配置、MCP、skills、日常接老项目、用 Playwright 测前端 bug 的实战最后再给一个高频报错速查表。全程不堆官方文档的复制粘贴尽量把“我实际跑通过”的细节写清楚。1.1 和 codex、claude code、pi 这类 Agent 怎么选现在终端 AI 编码助手已经不是新鲜概念了Claude Code、Codex CLI、OpenCode还有更新一点的 pi 之类的项目都在抢占同一个场景让模型直接在终端里操作代码。很多人会直接问“哪个 agent 好用”但我的体会是它们定位差得挺远先想明白自己要什么再选工具。Claude Code 最突出的地方是“开箱即用”的成熟度它对 Claude 模型的指令遵循、工具调用做得很顺项目里写一个 CLAUDE.md 就能长期保持上下文但同时它天然偏向 Anthropic 生态想接别的模型要绕不少路。Codex CLI 是 OpenAI 阵营的开源终端 Agent如果你主要用 OpenAI 的模型体验很顺但它和其他模型提供方的适配程度同样有限。opencode 和它们的核心差异是两个一是完全开源代码随便翻出问题可以自己改二是模型中立Anthropic、OpenAI、Gemini、本地 Ollama、第三方 OpenAI 兼容接口都能接同一个任务可以在不同模型之间横跳对比。至于 pi 这种新秀思路更极客适合喜欢整天换工具、追新版本的人但生态成熟度还在早期。如果你问我现在团队导入用哪个我一般这么建议追求稳定省心、团队全是 Claude 用户用 Claude Code重度 OpenAI 生态、想要官方支持用 Codex CLI想多模型切换、想把 AI 编码能力沉淀成团队自己的 skills、或者需要对接国内模型网关的优先看 opencode。1.2 “opencode 是哪家公司的”可能是最容易误会的问题我在好几个技术群里都看到有人问“opencode 是哪家公司的”这里统一说清楚它不是一个商业公司的闭源产品核心是个人和开源社区驱动的项目由做 Serverless 开发框架的 SST 团队核心成员发起代码完整放在 GitHub 上协议也是常见的开源许可证。所以它没有“官方客服”没有“套餐价格表”遇到问题主要靠 GitHub Issues、Discord 社区和文档。这一点既是优点也是坑。优点是迭代真的快社区提的 feature 可能几周就上线缺点是你别指望它有商业产品那种保姆级支持有些边角功能坏了要等下一个版本修复遇到问题得学会自己看日志。我在实际使用中的策略是生产环境尽量用稳定发布版新功能先在测试项目里试每周固定时间升一次版而不是天天追最新。后面第 7 节我会专门讲怎么看日志排查问题。2. 安装与首次启动三分钟跑起来含 Windows 报错解法2.1 三种安装方式按你的环境挑一个安装 opencode 其实就几条路挑一个适合你环境的就行。macOS 用户如果装了 Homebrew最简单的方式是brew install sst/tap/opencodeLinux 和大部分 Unix 环境可以用官方安装脚本curl -fsSL https://opencode.ai/install | bashWindows 用户我个人最推荐用 npm 全局安装因为最不容易踩权限坑npm i -g opencode-ai装完先验证一下版本能正常输出就说明命令已经进入 PATHopencode --version另外还有一个保底方案是去 GitHub 的 Release 页面直接下载对应平台的可执行文件Windows 就是下载 exe解压之后放进一个目录手动把这个目录加到 PATH 里。这个方法特别适合那些公司网络对 GitHub 访问不稳定、又不想折腾镜像源的场景。2.2 Windows 专属报错无法将“opencode”项识别为 cmdlet这个报错的热度在中文搜索里非常高我几乎可以确定你装完 opencode 在 PowerShell 里敲opencode时弹出来的就是这句opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名先说结论99% 的情况不是 opencode 坏了而是你刚装的命令没有被当前的 PowerShell 找到。原因通常是两类。一类是安装完成后没有重启终端PowerShell 里的 PATH 环境变量还是旧的这种情况关掉终端重新打开一个就行。另一类是 npm 的全局安装目录根本不在系统 PATH 里命令装到了某个文件夹但系统不知道去哪儿找它。第二种的解决办法是打开 PowerShell先执行npm config get prefix这会输出 npm 全局安装根目录在 Windows 上通常是C:\Users\你的用户名\AppData\Roaming\npm。确认这个路径后去系统环境变量设置里把%APPDATA%\npm加进 Path保存后重开终端。如果不想动环境变量还有一个懒人办法直接用绝对路径跑例如C:\Users\xxx\AppData\Roaming\npm\opencode.exe能跑通再去改环境变量。2.3 首次启动认证、模型选择、跑通第一个任务安装完成后直接在终端里输入opencode就会进入它的 TUI 界面。第一次进入会让你选择模型提供方并且要通过登录或者填 API Key 的方式完成认证。如果你更习惯命令行操作也可以先用这条命令opencode auth login登录完成后一行式任务可以用opencode run跑。比如我想让它解释当前目录的项目结构opencode run 简要分析一下这个项目的目录结构和主要模块如果当前目录没有项目它会提示你如果有它会开始读文件、分析代码然后在终端里输出结论。第一次跑的时候你会发现它像真人一样先看 package.json、README、入口文件之类再给结论这种感觉和单纯的“聊天框问答”完全不一样。提示首次使用建议先跑一个简单任务确认模型连通、文件读取正常再开始接真实项目。不要在没验证过环境的情况下直接让它改代码。3. 配置是灵魂模型、MCP、skills、memory 一次讲透3.1 两个核心配置opencode.json 和 auth.jsonopencode 的配置机制不复杂记住两个关键位置就好一个是全局目录下的配置文件Linux/macOS 在~/.config/opencode/Windows 在%USERPROFILE%\.config\opencode\另一个是项目根目录下的opencode.json。其中auth.json保存的是各模型提供方的密钥这个文件默认不会提交到 Git千万别手动把它放到仓库里。opencode.json是主配置可以配置默认模型、MCP 服务、启动参数等。项目根目录下的配置会覆盖全局配置所以同一个团队可以约定把 opencode.json 提交进仓库让所有人统一 MCP 和模型策略。一个最小化的项目配置大概是这样的{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, autoupdate: true }注意model的格式是“提供方/模型名”这是 opencode 里识别模型的基本写法。如果你不用这个字段TUI 启动时会用上次选择的模型或者要求你手动选择。3.2 免费模型怎么接说说几条靠谱路径“opencode 免费模型”是搜索热词我得先泼点冷水完全免费且稳定的大模型 API 在 2025 年的现实世界里基本不存在所谓的免费模型通常有额度限制、速度限制、或者只适合低强度试用。实际工作中我见过的靠谱路径是三条。第一条是用本地模型例如 Ollama。跑一个 7B 左右的中小模型在本地做日常重构、代码解释完全够用隐私也好适合不愿意把代码发给外部 API 的场景。opencode 对 OpenAI 兼容接口的支持很成熟把 Ollama 的本地接口配进来就行比如ollama pull qwen2.5-coder:7b ollama serve然后在 opencode 配置里加一个指向http://localhost:11434/v1的 provider模型名填你拉取的模型名。好处是不花钱、不出网坏处是模型能力上限就摆在那复杂架构设计和长链路排错还是会吃力。第二条是用模型聚合平台或者云厂商提供的体验额度。很多云平台和聚合服务商会提供 OpenAI 兼容的 API 地址、有限度的免费调用次数把这类接口作为一个 provider 配到 opencode 里就能当“免费模型”用。配置方式和本地模型一样只是 baseURL 换成服务商给的地址。这类服务五花八门我不在这里具体点名但有三个判断标准是否支持 OpenAI 兼容协议、是否把密钥明文暴露、文档里有没有明确写清免费额度和续费规则。三条都满足再往生产环境接。第三条是参与开源社区贡献换取额度。opencode 和部分模型服务商有合作对开源项目的有效贡献者会提供免费的使用额度这是合规又稳的一条路但门槛显然比前两条高。如果只是自己玩一玩本地 Ollama 是最快能跑通的方式。提示尽量别把来源不明的“免费 API Key”用在公司项目里轻则数据外泄重则合规风险。个人学习随便试但要时刻记住代码是资产。3.3 MCP 配置让 agent 真正“动手”MCPModel Context Protocol是一个把外部工具接入 AI 模型的标准协议。opencode 对 MCP 支持得相当好配置文件里加一个 mcp 字段就能让它在会话里调用外部服务。很多人在搜“opencode mvn 配置”我怀疑是“opencode MCP 配置”的口误因为两者发音有点像而 MCP 恰恰是配置里最值得花时间的部分。一个典型的项目配置长这样{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest], enabled: true } } }这个配置的作用是让 opencode 能调用 Playwright打开真实浏览器去测试前端页面。配置完成后重启 opencode 会话对话里就能直接说“用 Playwright 打开当前页面看一眼控制台有没有报错”它会自己启动浏览器做操作、截屏、抓日志。这类 MCP 工具还有文件系统、数据库、浏览器调试、Git 操作等方向团队可以根据开发场景按需接入。我的建议是不要一上来接一堆先接一个真正解决痛点的跑顺了再扩展。3.4 skills 和 memory把团队经验沉淀下来opencode 的 skills 机制是我最看重的功能之一。简单说它允许你把一段经常要做的操作写成一个带结构化描述的 Markdown 指令之后在对话里通过名字唤起agent 就按照你预定义的流程执行。社区里很火的 superpowers、oh-my-claudecode 这类项目本质上就是把大量技巧预置成 skillsopencode 的机制也能吸收这种玩法。一个最简单的技能示例保存为.opencode/skills/code-review.md--- name: code-review description: 对当前分支做一次代码评审输出问题和改进建议 --- 请对当前 Git 分支相对 main 的改动做代码评审 1. 先运行 git diff main...HEAD --stat 了解改动范围。 2. 按文件逐个阅读 diff重点关注逻辑错误、边界条件、安全隐患。 3. 输出格式问题列表严重程度 文件位置 原因 修改建议。 4. 最后总结改动里做得好的地方。写好后在对话里说“做个 code review”它就会执行这套流程。memory 则对应项目里的长上下文最实用的做法是在项目根目录维护一个 AGENTS.md把目录结构、启动命令、测试命令、代码约定都写进去opencode 会在会话开始时自动读取这份文件。配合 skills相当于把一个团队的开发规范直接注入到模型的工作记忆里这才是它比纯聊天式工具更有长期价值的地方。4. 日常开发实战怎么把 opencode 变成团队搭档4.1 我日常最顺手的 TUI 操作路径TUI 界面刚上手的人容易懵因为满屏幕都是信息但其实高频操作就那么几个。进入会话后直接在输入框写任务想切换模型输入/model会弹出选择器平时我至少会保留一个强模型和一个便宜模型简单任务用便宜的复杂架构讨论切强模型想查看当前会话可用的工具输入/mcp能看到 MCP 服务状态需要放弃当前改动对话里说“把所有改动撤销”它会根据 Git 状态判断并执行。我最常用的一个习惯是“先看后改”。拿到一个任务我不会让它直接改而是先下指令先不要改代码。请阅读相关文件告诉我你的修改方案包括影响范围、要动哪些文件、怎么测试确认后再动手。这能极大避免模型乱改一团。另一个习惯是给任务加边界比如“只改 xxx 目录下的文件其他文件不要动”“不要改 package-lock.json”“不要执行 git push”。模型在开放式任务里容易自作主张把边界写在指令里比事后回滚省事得多。4.2 接手老项目从一脸懵到顺利改动“opencode 接手开发项目”这个搜索词我觉得背后是很多人的真实痛点新项目还好老项目代码乱、文档缺、历史包袱重人和 AI 都容易栽跟头。我接手老项目的标准流程是这样的。第一步先让 opencode 跑一次全项目梳理。给它的指令是先阅读这个项目的 README、package.json、构建配置和入口文件帮我弄清楚三件事 1. 项目怎么启动、怎么跑测试 2. 目录结构和核心模块职责 3. 有没有明显的遗留技术债 结果写到 AGENTS.md之后我们所有会话都要参考这个文件。这个操作我会显式要求它写进 AGENTS.md因为之后每一次新会话它都会重新读这份文件相当于给项目建立了一份“活的交接文档”。第二步我会根据 AGENTS.md 里的启动命令让 opencode 先把项目跑起来。很多 AI 工具改代码时根本不跑项目导致改完才发现编译都过不了所以在老项目里“能跑起来”是第一原则。第三步才让它开始改需求。但改之前我会明确任务的最小范围比如“在订单列表页增加一个导出按钮只改前端页面和对应接口调用不动后端”并强调改完以后跑一次相关的测试命令。这套流程下来即使一个我从没接触过的老仓库通常也可以在一小时内进入可维护状态。4.3 我最推荐的团队工作流把 opencode 引入团队时我见过两种极端一种是不让任何人用怕乱改代码另一种是塞给新员工当“万能工具”出问题甩锅给 AI。这两种都不对。比较合理的落法是把它当成一个“严格的结对实习生”可以做任务但每一步都要人来审。我所在团队现在的基本规范是三条。第一opencode 的改动必须在独立 git 分支上不允许直接在主分支或者自己正在开发的分支上让它乱动。第二任务指令必须包含可验证的完成标准比如“跑通某条测试”“页面能正常打开”不允许只写“优化一下”。第三涉及删除、回滚、推送远程仓库这类高风险操作由人手动执行不让 agent 代劳。另外每周我们会有一次“技能共建”时间把上一周遇到的高频操作写成 skills 放进仓库。一开始很慢但积累到二十来个 skills 之后团队做需求的速度明显提升因为很多重复工作都被标准化了。opencode 在这里的价值不只是“帮你写代码”而是帮你把隐性经验显性化变成团队资产。5. 从终端走向界面桌面版、VSCode 和 IDEA 插件5.1 桌面版适合谁虽然 opencode 本质是终端工具但现在也有桌面版的形式本质上是把 TUI 界面包装在一个独立图形窗口里。对一部分开发者来说这比塞在终端里更好用尤其是需要长时间盯着会话输出、或者同时开多个会话对比不同模型结果的时候。用桌面版最大的好处是窗口管理更自由左边是聊天和任务列表右边可以看 diff 和文件变更不需要在终端和编辑器之间来回切。不过它的底层还是同一个 opencode 核心配置文件和命令行版本完全通用不存在“桌面版功能比 CLI 少”的问题。我的建议是终端用户没必要专门换但如果你习惯 GUI、或者给非技术同事演示桌面版确实更友好。5.2 VSCode 插件编辑和对话无缝衔接VSCode 插件让 opencode 的使用场景从“终端里发指令”变成了“编辑器里发指令”。搜索安装 opencode 插件后左侧边栏会出现一个对话面板。你可以选中一段代码直接右键发送给 opencode让它解释、重构、写测试也可以在对话里引用当前打开的文件让它基于文件内容回答问题。我把这个场景用得最多的是“圈定范围”。在终端里让它改文件它可能会自己猜要改哪里但插件模式下我选中需要改的函数或文件指令就会变得精确很多。还有一个很实用的小技巧在 VSCode 里让 opencode 读终端的报错日志然后直接把修复方案贴回来省掉了一大段人工复制描述的过程。插件本质上还是调用同一个模型和配置所以不用担心两边的模型不一致。5.3 IDEA 插件Java 系开发者怎么跟 opencode 配合JetBrains 系IDEA、GoLand、PyCharm现在也有 opencode 插件了。Java/Go 项目往往是多模块工程结构比前端项目复杂插件的作用主要体现在两点一是可以直接让插件读取当前模块的上下文不用在终端里手动解释模块结构二是可以把 AI 会话和 IDE 的错误提示联动起来比如把一个编译错误的 stack trace 发给 opencode让它直接定位到相关类。IDEA 插件装完后有个常见问题如果插件找不到 opencode 命令通常是因为 IDEA 的启动环境没有继承终端里的 PATH。解决办法是在插件设置里手动填 opencode 可执行文件的绝对路径。Windows 上尤其容易遇到这种情况路径一般就是 npm 全局目录下的 opencode.exe前面第 2 节已经讲过怎么查npm全局目录这里填进去就行。6. 真实场景复现用 opencode Playwright 定位前端 Bug6.1 场景描述为什么前端 Bug 那么难用 AI 排查日常开发里有一类问题特别折腾页面渲染出来的表现和预期不一致但没有明显报错打开控制台也只有一堆噪音。这类“前端交互 Bug”以前很难用 AI 排查因为模型看不到页面只能靠人描述而人的描述往往不准确。opencode 接入 Playwright MCP 之后这个场景基本被解决了。Playwright 可以控制真实浏览器opencode 通过 MCP 调用它就能打开页面、点击、输入、截图、抓 console 日志整个流程是模型自己操作的。这相当于给了 agent 一双眼睛让它自己去看页面到底发生了什么。6.2 一次完整的前端 Bug 排查过程我先在项目根目录的 opencode.json 里接好 Playwright MCP然后重启 opencode 会话。假设现在的问题是移动端登录页在点击登录按钮后没有任何反应也没有报错。我会这样下指令先启动项目的 dev server然后用 Playwright 打开移动端登录页。 帮我复现这个操作输入一个测试账号和密码点击登录按钮然后把控制台日志、网络请求和页面截图都给我看一下。 最后分析为什么点击登录没有反应。opencode 会先找到 dev server 启动命令跑起来再调 Playwright 打开对应端口页面模拟点击。如果它足够顺利会在几轮交互后告诉你控制台没报错但点击按钮时有一个 JavaScript 异常被 catch 掉了或者请求发送失败但页面没有错误提示或者按钮被某个元素遮挡所以点击事件根本没触发。找到原因后我会继续让它给出修复方案再让它直接改代码并重新跑一次页面验证。这里有一个重要的操作原则让它修复后必须自己复测不要改完就说“好了”。模型写代码和验证代码是两种能力显式要求“改完以后用 Playwright 重新跑一遍同样的流程”能避免大量“看起来修了、实际没修好”的假完成。6.3 这个玩法的常见坑第一Playwright 会打开真实的浏览器窗口在无图形界面的服务器上需要额外配置 headless 模式默认打开真实窗口会把服务器卡死。第二测试环境如果有验证码、短信登录这类环节必须提前处理要么 mock 掉要么准备测试账号否则每次复测都会卡在验证环节。第三不要让 opencode 用生产环境账号去跑 Playwright风险很大有一次它差点在测试环境发了一笔真实的支付请求从那以后我配置里就强制绑定了测试环境域名。第四Playwright 启动浏览器会比较耗资源尤其是同时开多个会话的时候尽量一次只跑一个浏览器任务。7. 高频问题与报错速查7.1 一张表解决大部分上手问题问题最常见原因处理办法Windows 报“无法将 opencode 项识别为 cmdlet”npm 全局目录不在 PATH或终端没重启重启终端检查%APPDATA%\npm是否在 PATH或用 npm config get prefix 查目录运行 opencode 报 unexpected server error网络异常、服务端临时故障、API 额度超限先看~/.config/opencode/下的日志检查 API Key 是否有效试一次低额度模型确认网络连通模型 API 报 401密钥错误或没有认证重新执行opencode auth login在 auth.json 里确认 key 是否正确切换模型后行为差异很大不同模型能力差异本来就大这不是 bug建议按任务难度分配模型复杂任务用强模型简单任务用便宜模型MCP 工具不生效配置格式错误或依赖没装检查 opencode.json 里 command 路径是否存在本地依赖建议用 npx -y 执行指令要求很明确但模型还是改超范围缺少边界约束在指令里显式声明“只允许改动 xxx 目录”“禁止执行 git push”等硬性边界免费额度模型突然连不上服务商额度或服务下线换备用 gateway或者暂时切本地 Ollama 模型日志是我排查问题的第一入口尤其是unexpected server error这类笼统报错。opencode 会在配置目录下保留日志文件Windows 上一般在%USERPROFILE%\.config\opencode\logLinux/macOS 在~/.config/opencode/log。看到报错不要急着重新安装先把最后几十行日志打开看看多半能直接找到是网络问题、API Key 问题还是模型服务商的问题。7.2 最后分享一个我的使用习惯工具选型这件事没有绝对的最好只有合不合适。opencode 目前是我用的最多的终端 Agent并不是因为它每个方面都比 Claude Code 强而是它把“模型自由”和“可配置性”放在第一位这让它成了一个能跟着团队需求长期演进的底座。用了这段时间我最大的体会是不要把 agent 当成自动写代码的机器要把 agent 当成一个需要你写清楚需求、给足上下文、事后认真 review 的协作对象。你越是把团队的知识、规范、踩坑记录沉淀成 AGENTS.md 和 skills它给你的回报就越明显。希望你也能在项目里把它用起来少踩几个我踩过的坑。
1. 从一次工具迁移说起opencode 到底是做什么的最近小半个月我把日常的编码主力从一个很火的商业 Agent 慢慢换到了 opencode 上。起因很简单我想在同一个终端工具里自由切换不同厂商的模型又不想把所有代码会话都绑在一家生态里于是试了一圈开源的终端 AI 编码助手最后留下的是它。这个 opencode 是什么说得直接一点它是一个用 Go 写的开源 TUI 编程助手放在命令行里运行给它一个任务它会自己翻你项目里的代码、调用工具、改文件、跑测试然后把改动结果拿给你审。很多人在搜索记录里看到“opencode go”这个词其实就是指它是 Go 语言实现这件事不是某个独立命令。因为核心是用 Go 写的所以启动速度快、单文件分发、跨平台安装也简单这是它和一大批 Node 系 AI 命令行工具最直观的区别。如果你也正在纠结 opencode 是不是又一个换壳玩具或者刚下载完就在 Windows 上碰到“无法将 opencode 项识别为 cmdlet”的报错又或者听别人说它能接免费模型但不知道具体怎么配这篇文章基本就是为你准备的。我会从它是什么、到底解决了什么问题开始一路讲到安装、配置、MCP、skills、日常接老项目、用 Playwright 测前端 bug 的实战最后再给一个高频报错速查表。全程不堆官方文档的复制粘贴尽量把“我实际跑通过”的细节写清楚。1.1 和 codex、claude code、pi 这类 Agent 怎么选现在终端 AI 编码助手已经不是新鲜概念了Claude Code、Codex CLI、OpenCode还有更新一点的 pi 之类的项目都在抢占同一个场景让模型直接在终端里操作代码。很多人会直接问“哪个 agent 好用”但我的体会是它们定位差得挺远先想明白自己要什么再选工具。Claude Code 最突出的地方是“开箱即用”的成熟度它对 Claude 模型的指令遵循、工具调用做得很顺项目里写一个 CLAUDE.md 就能长期保持上下文但同时它天然偏向 Anthropic 生态想接别的模型要绕不少路。Codex CLI 是 OpenAI 阵营的开源终端 Agent如果你主要用 OpenAI 的模型体验很顺但它和其他模型提供方的适配程度同样有限。opencode 和它们的核心差异是两个一是完全开源代码随便翻出问题可以自己改二是模型中立Anthropic、OpenAI、Gemini、本地 Ollama、第三方 OpenAI 兼容接口都能接同一个任务可以在不同模型之间横跳对比。至于 pi 这种新秀思路更极客适合喜欢整天换工具、追新版本的人但生态成熟度还在早期。如果你问我现在团队导入用哪个我一般这么建议追求稳定省心、团队全是 Claude 用户用 Claude Code重度 OpenAI 生态、想要官方支持用 Codex CLI想多模型切换、想把 AI 编码能力沉淀成团队自己的 skills、或者需要对接国内模型网关的优先看 opencode。1.2 “opencode 是哪家公司的”可能是最容易误会的问题我在好几个技术群里都看到有人问“opencode 是哪家公司的”这里统一说清楚它不是一个商业公司的闭源产品核心是个人和开源社区驱动的项目由做 Serverless 开发框架的 SST 团队核心成员发起代码完整放在 GitHub 上协议也是常见的开源许可证。所以它没有“官方客服”没有“套餐价格表”遇到问题主要靠 GitHub Issues、Discord 社区和文档。这一点既是优点也是坑。优点是迭代真的快社区提的 feature 可能几周就上线缺点是你别指望它有商业产品那种保姆级支持有些边角功能坏了要等下一个版本修复遇到问题得学会自己看日志。我在实际使用中的策略是生产环境尽量用稳定发布版新功能先在测试项目里试每周固定时间升一次版而不是天天追最新。后面第 7 节我会专门讲怎么看日志排查问题。2. 安装与首次启动三分钟跑起来含 Windows 报错解法2.1 三种安装方式按你的环境挑一个安装 opencode 其实就几条路挑一个适合你环境的就行。macOS 用户如果装了 Homebrew最简单的方式是brew install sst/tap/opencodeLinux 和大部分 Unix 环境可以用官方安装脚本curl -fsSL https://opencode.ai/install | bashWindows 用户我个人最推荐用 npm 全局安装因为最不容易踩权限坑npm i -g opencode-ai装完先验证一下版本能正常输出就说明命令已经进入 PATHopencode --version另外还有一个保底方案是去 GitHub 的 Release 页面直接下载对应平台的可执行文件Windows 就是下载 exe解压之后放进一个目录手动把这个目录加到 PATH 里。这个方法特别适合那些公司网络对 GitHub 访问不稳定、又不想折腾镜像源的场景。2.2 Windows 专属报错无法将“opencode”项识别为 cmdlet这个报错的热度在中文搜索里非常高我几乎可以确定你装完 opencode 在 PowerShell 里敲opencode时弹出来的就是这句opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名先说结论99% 的情况不是 opencode 坏了而是你刚装的命令没有被当前的 PowerShell 找到。原因通常是两类。一类是安装完成后没有重启终端PowerShell 里的 PATH 环境变量还是旧的这种情况关掉终端重新打开一个就行。另一类是 npm 的全局安装目录根本不在系统 PATH 里命令装到了某个文件夹但系统不知道去哪儿找它。第二种的解决办法是打开 PowerShell先执行npm config get prefix这会输出 npm 全局安装根目录在 Windows 上通常是C:\Users\你的用户名\AppData\Roaming\npm。确认这个路径后去系统环境变量设置里把%APPDATA%\npm加进 Path保存后重开终端。如果不想动环境变量还有一个懒人办法直接用绝对路径跑例如C:\Users\xxx\AppData\Roaming\npm\opencode.exe能跑通再去改环境变量。2.3 首次启动认证、模型选择、跑通第一个任务安装完成后直接在终端里输入opencode就会进入它的 TUI 界面。第一次进入会让你选择模型提供方并且要通过登录或者填 API Key 的方式完成认证。如果你更习惯命令行操作也可以先用这条命令opencode auth login登录完成后一行式任务可以用opencode run跑。比如我想让它解释当前目录的项目结构opencode run 简要分析一下这个项目的目录结构和主要模块如果当前目录没有项目它会提示你如果有它会开始读文件、分析代码然后在终端里输出结论。第一次跑的时候你会发现它像真人一样先看 package.json、README、入口文件之类再给结论这种感觉和单纯的“聊天框问答”完全不一样。提示首次使用建议先跑一个简单任务确认模型连通、文件读取正常再开始接真实项目。不要在没验证过环境的情况下直接让它改代码。3. 配置是灵魂模型、MCP、skills、memory 一次讲透3.1 两个核心配置opencode.json 和 auth.jsonopencode 的配置机制不复杂记住两个关键位置就好一个是全局目录下的配置文件Linux/macOS 在~/.config/opencode/Windows 在%USERPROFILE%\.config\opencode\另一个是项目根目录下的opencode.json。其中auth.json保存的是各模型提供方的密钥这个文件默认不会提交到 Git千万别手动把它放到仓库里。opencode.json是主配置可以配置默认模型、MCP 服务、启动参数等。项目根目录下的配置会覆盖全局配置所以同一个团队可以约定把 opencode.json 提交进仓库让所有人统一 MCP 和模型策略。一个最小化的项目配置大概是这样的{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, autoupdate: true }注意model的格式是“提供方/模型名”这是 opencode 里识别模型的基本写法。如果你不用这个字段TUI 启动时会用上次选择的模型或者要求你手动选择。3.2 免费模型怎么接说说几条靠谱路径“opencode 免费模型”是搜索热词我得先泼点冷水完全免费且稳定的大模型 API 在 2025 年的现实世界里基本不存在所谓的免费模型通常有额度限制、速度限制、或者只适合低强度试用。实际工作中我见过的靠谱路径是三条。第一条是用本地模型例如 Ollama。跑一个 7B 左右的中小模型在本地做日常重构、代码解释完全够用隐私也好适合不愿意把代码发给外部 API 的场景。opencode 对 OpenAI 兼容接口的支持很成熟把 Ollama 的本地接口配进来就行比如ollama pull qwen2.5-coder:7b ollama serve然后在 opencode 配置里加一个指向http://localhost:11434/v1的 provider模型名填你拉取的模型名。好处是不花钱、不出网坏处是模型能力上限就摆在那复杂架构设计和长链路排错还是会吃力。第二条是用模型聚合平台或者云厂商提供的体验额度。很多云平台和聚合服务商会提供 OpenAI 兼容的 API 地址、有限度的免费调用次数把这类接口作为一个 provider 配到 opencode 里就能当“免费模型”用。配置方式和本地模型一样只是 baseURL 换成服务商给的地址。这类服务五花八门我不在这里具体点名但有三个判断标准是否支持 OpenAI 兼容协议、是否把密钥明文暴露、文档里有没有明确写清免费额度和续费规则。三条都满足再往生产环境接。第三条是参与开源社区贡献换取额度。opencode 和部分模型服务商有合作对开源项目的有效贡献者会提供免费的使用额度这是合规又稳的一条路但门槛显然比前两条高。如果只是自己玩一玩本地 Ollama 是最快能跑通的方式。提示尽量别把来源不明的“免费 API Key”用在公司项目里轻则数据外泄重则合规风险。个人学习随便试但要时刻记住代码是资产。3.3 MCP 配置让 agent 真正“动手”MCPModel Context Protocol是一个把外部工具接入 AI 模型的标准协议。opencode 对 MCP 支持得相当好配置文件里加一个 mcp 字段就能让它在会话里调用外部服务。很多人在搜“opencode mvn 配置”我怀疑是“opencode MCP 配置”的口误因为两者发音有点像而 MCP 恰恰是配置里最值得花时间的部分。一个典型的项目配置长这样{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest], enabled: true } } }这个配置的作用是让 opencode 能调用 Playwright打开真实浏览器去测试前端页面。配置完成后重启 opencode 会话对话里就能直接说“用 Playwright 打开当前页面看一眼控制台有没有报错”它会自己启动浏览器做操作、截屏、抓日志。这类 MCP 工具还有文件系统、数据库、浏览器调试、Git 操作等方向团队可以根据开发场景按需接入。我的建议是不要一上来接一堆先接一个真正解决痛点的跑顺了再扩展。3.4 skills 和 memory把团队经验沉淀下来opencode 的 skills 机制是我最看重的功能之一。简单说它允许你把一段经常要做的操作写成一个带结构化描述的 Markdown 指令之后在对话里通过名字唤起agent 就按照你预定义的流程执行。社区里很火的 superpowers、oh-my-claudecode 这类项目本质上就是把大量技巧预置成 skillsopencode 的机制也能吸收这种玩法。一个最简单的技能示例保存为.opencode/skills/code-review.md--- name: code-review description: 对当前分支做一次代码评审输出问题和改进建议 --- 请对当前 Git 分支相对 main 的改动做代码评审 1. 先运行 git diff main...HEAD --stat 了解改动范围。 2. 按文件逐个阅读 diff重点关注逻辑错误、边界条件、安全隐患。 3. 输出格式问题列表严重程度 文件位置 原因 修改建议。 4. 最后总结改动里做得好的地方。写好后在对话里说“做个 code review”它就会执行这套流程。memory 则对应项目里的长上下文最实用的做法是在项目根目录维护一个 AGENTS.md把目录结构、启动命令、测试命令、代码约定都写进去opencode 会在会话开始时自动读取这份文件。配合 skills相当于把一个团队的开发规范直接注入到模型的工作记忆里这才是它比纯聊天式工具更有长期价值的地方。4. 日常开发实战怎么把 opencode 变成团队搭档4.1 我日常最顺手的 TUI 操作路径TUI 界面刚上手的人容易懵因为满屏幕都是信息但其实高频操作就那么几个。进入会话后直接在输入框写任务想切换模型输入/model会弹出选择器平时我至少会保留一个强模型和一个便宜模型简单任务用便宜的复杂架构讨论切强模型想查看当前会话可用的工具输入/mcp能看到 MCP 服务状态需要放弃当前改动对话里说“把所有改动撤销”它会根据 Git 状态判断并执行。我最常用的一个习惯是“先看后改”。拿到一个任务我不会让它直接改而是先下指令先不要改代码。请阅读相关文件告诉我你的修改方案包括影响范围、要动哪些文件、怎么测试确认后再动手。这能极大避免模型乱改一团。另一个习惯是给任务加边界比如“只改 xxx 目录下的文件其他文件不要动”“不要改 package-lock.json”“不要执行 git push”。模型在开放式任务里容易自作主张把边界写在指令里比事后回滚省事得多。4.2 接手老项目从一脸懵到顺利改动“opencode 接手开发项目”这个搜索词我觉得背后是很多人的真实痛点新项目还好老项目代码乱、文档缺、历史包袱重人和 AI 都容易栽跟头。我接手老项目的标准流程是这样的。第一步先让 opencode 跑一次全项目梳理。给它的指令是先阅读这个项目的 README、package.json、构建配置和入口文件帮我弄清楚三件事 1. 项目怎么启动、怎么跑测试 2. 目录结构和核心模块职责 3. 有没有明显的遗留技术债 结果写到 AGENTS.md之后我们所有会话都要参考这个文件。这个操作我会显式要求它写进 AGENTS.md因为之后每一次新会话它都会重新读这份文件相当于给项目建立了一份“活的交接文档”。第二步我会根据 AGENTS.md 里的启动命令让 opencode 先把项目跑起来。很多 AI 工具改代码时根本不跑项目导致改完才发现编译都过不了所以在老项目里“能跑起来”是第一原则。第三步才让它开始改需求。但改之前我会明确任务的最小范围比如“在订单列表页增加一个导出按钮只改前端页面和对应接口调用不动后端”并强调改完以后跑一次相关的测试命令。这套流程下来即使一个我从没接触过的老仓库通常也可以在一小时内进入可维护状态。4.3 我最推荐的团队工作流把 opencode 引入团队时我见过两种极端一种是不让任何人用怕乱改代码另一种是塞给新员工当“万能工具”出问题甩锅给 AI。这两种都不对。比较合理的落法是把它当成一个“严格的结对实习生”可以做任务但每一步都要人来审。我所在团队现在的基本规范是三条。第一opencode 的改动必须在独立 git 分支上不允许直接在主分支或者自己正在开发的分支上让它乱动。第二任务指令必须包含可验证的完成标准比如“跑通某条测试”“页面能正常打开”不允许只写“优化一下”。第三涉及删除、回滚、推送远程仓库这类高风险操作由人手动执行不让 agent 代劳。另外每周我们会有一次“技能共建”时间把上一周遇到的高频操作写成 skills 放进仓库。一开始很慢但积累到二十来个 skills 之后团队做需求的速度明显提升因为很多重复工作都被标准化了。opencode 在这里的价值不只是“帮你写代码”而是帮你把隐性经验显性化变成团队资产。5. 从终端走向界面桌面版、VSCode 和 IDEA 插件5.1 桌面版适合谁虽然 opencode 本质是终端工具但现在也有桌面版的形式本质上是把 TUI 界面包装在一个独立图形窗口里。对一部分开发者来说这比塞在终端里更好用尤其是需要长时间盯着会话输出、或者同时开多个会话对比不同模型结果的时候。用桌面版最大的好处是窗口管理更自由左边是聊天和任务列表右边可以看 diff 和文件变更不需要在终端和编辑器之间来回切。不过它的底层还是同一个 opencode 核心配置文件和命令行版本完全通用不存在“桌面版功能比 CLI 少”的问题。我的建议是终端用户没必要专门换但如果你习惯 GUI、或者给非技术同事演示桌面版确实更友好。5.2 VSCode 插件编辑和对话无缝衔接VSCode 插件让 opencode 的使用场景从“终端里发指令”变成了“编辑器里发指令”。搜索安装 opencode 插件后左侧边栏会出现一个对话面板。你可以选中一段代码直接右键发送给 opencode让它解释、重构、写测试也可以在对话里引用当前打开的文件让它基于文件内容回答问题。我把这个场景用得最多的是“圈定范围”。在终端里让它改文件它可能会自己猜要改哪里但插件模式下我选中需要改的函数或文件指令就会变得精确很多。还有一个很实用的小技巧在 VSCode 里让 opencode 读终端的报错日志然后直接把修复方案贴回来省掉了一大段人工复制描述的过程。插件本质上还是调用同一个模型和配置所以不用担心两边的模型不一致。5.3 IDEA 插件Java 系开发者怎么跟 opencode 配合JetBrains 系IDEA、GoLand、PyCharm现在也有 opencode 插件了。Java/Go 项目往往是多模块工程结构比前端项目复杂插件的作用主要体现在两点一是可以直接让插件读取当前模块的上下文不用在终端里手动解释模块结构二是可以把 AI 会话和 IDE 的错误提示联动起来比如把一个编译错误的 stack trace 发给 opencode让它直接定位到相关类。IDEA 插件装完后有个常见问题如果插件找不到 opencode 命令通常是因为 IDEA 的启动环境没有继承终端里的 PATH。解决办法是在插件设置里手动填 opencode 可执行文件的绝对路径。Windows 上尤其容易遇到这种情况路径一般就是 npm 全局目录下的 opencode.exe前面第 2 节已经讲过怎么查npm全局目录这里填进去就行。6. 真实场景复现用 opencode Playwright 定位前端 Bug6.1 场景描述为什么前端 Bug 那么难用 AI 排查日常开发里有一类问题特别折腾页面渲染出来的表现和预期不一致但没有明显报错打开控制台也只有一堆噪音。这类“前端交互 Bug”以前很难用 AI 排查因为模型看不到页面只能靠人描述而人的描述往往不准确。opencode 接入 Playwright MCP 之后这个场景基本被解决了。Playwright 可以控制真实浏览器opencode 通过 MCP 调用它就能打开页面、点击、输入、截图、抓 console 日志整个流程是模型自己操作的。这相当于给了 agent 一双眼睛让它自己去看页面到底发生了什么。6.2 一次完整的前端 Bug 排查过程我先在项目根目录的 opencode.json 里接好 Playwright MCP然后重启 opencode 会话。假设现在的问题是移动端登录页在点击登录按钮后没有任何反应也没有报错。我会这样下指令先启动项目的 dev server然后用 Playwright 打开移动端登录页。 帮我复现这个操作输入一个测试账号和密码点击登录按钮然后把控制台日志、网络请求和页面截图都给我看一下。 最后分析为什么点击登录没有反应。opencode 会先找到 dev server 启动命令跑起来再调 Playwright 打开对应端口页面模拟点击。如果它足够顺利会在几轮交互后告诉你控制台没报错但点击按钮时有一个 JavaScript 异常被 catch 掉了或者请求发送失败但页面没有错误提示或者按钮被某个元素遮挡所以点击事件根本没触发。找到原因后我会继续让它给出修复方案再让它直接改代码并重新跑一次页面验证。这里有一个重要的操作原则让它修复后必须自己复测不要改完就说“好了”。模型写代码和验证代码是两种能力显式要求“改完以后用 Playwright 重新跑一遍同样的流程”能避免大量“看起来修了、实际没修好”的假完成。6.3 这个玩法的常见坑第一Playwright 会打开真实的浏览器窗口在无图形界面的服务器上需要额外配置 headless 模式默认打开真实窗口会把服务器卡死。第二测试环境如果有验证码、短信登录这类环节必须提前处理要么 mock 掉要么准备测试账号否则每次复测都会卡在验证环节。第三不要让 opencode 用生产环境账号去跑 Playwright风险很大有一次它差点在测试环境发了一笔真实的支付请求从那以后我配置里就强制绑定了测试环境域名。第四Playwright 启动浏览器会比较耗资源尤其是同时开多个会话的时候尽量一次只跑一个浏览器任务。7. 高频问题与报错速查7.1 一张表解决大部分上手问题问题最常见原因处理办法Windows 报“无法将 opencode 项识别为 cmdlet”npm 全局目录不在 PATH或终端没重启重启终端检查%APPDATA%\npm是否在 PATH或用 npm config get prefix 查目录运行 opencode 报 unexpected server error网络异常、服务端临时故障、API 额度超限先看~/.config/opencode/下的日志检查 API Key 是否有效试一次低额度模型确认网络连通模型 API 报 401密钥错误或没有认证重新执行opencode auth login在 auth.json 里确认 key 是否正确切换模型后行为差异很大不同模型能力差异本来就大这不是 bug建议按任务难度分配模型复杂任务用强模型简单任务用便宜模型MCP 工具不生效配置格式错误或依赖没装检查 opencode.json 里 command 路径是否存在本地依赖建议用 npx -y 执行指令要求很明确但模型还是改超范围缺少边界约束在指令里显式声明“只允许改动 xxx 目录”“禁止执行 git push”等硬性边界免费额度模型突然连不上服务商额度或服务下线换备用 gateway或者暂时切本地 Ollama 模型日志是我排查问题的第一入口尤其是unexpected server error这类笼统报错。opencode 会在配置目录下保留日志文件Windows 上一般在%USERPROFILE%\.config\opencode\logLinux/macOS 在~/.config/opencode/log。看到报错不要急着重新安装先把最后几十行日志打开看看多半能直接找到是网络问题、API Key 问题还是模型服务商的问题。7.2 最后分享一个我的使用习惯工具选型这件事没有绝对的最好只有合不合适。opencode 目前是我用的最多的终端 Agent并不是因为它每个方面都比 Claude Code 强而是它把“模型自由”和“可配置性”放在第一位这让它成了一个能跟着团队需求长期演进的底座。用了这段时间我最大的体会是不要把 agent 当成自动写代码的机器要把 agent 当成一个需要你写清楚需求、给足上下文、事后认真 review 的协作对象。你越是把团队的知识、规范、踩坑记录沉淀成 AGENTS.md 和 skills它给你的回报就越明显。希望你也能在项目里把它用起来少踩几个我踩过的坑。
