最近好几个群都在聊 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 的核心差异列出来方便你判断自己该用哪个。维度opencodeClaude CodeCodex CLI开源情况完全开源MIT未开源开源底层语言GoTypeScript/闭源TypeScript模型锁定不锁定多 provider 自由切换主要是 Claude 系主要是 OpenAI 系本地模型支持 Ollama 等需中转或特殊配置支持部分兼容层插件/Skills成熟的插件市场与 Skills 机制插件生态丰富相对有限IDE 配套VSCode / JetBrains 插件 桌面版无官方 IDE 插件已有 VSCode 扩展安装体积单二进制轻量Node 包较大Node 包中等从表里能看出来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直接用 Homebrewbrew install sst/tap/opencode不想加 tap 的话也可以用官方安装脚本curl -fsSL https://opencode.ai/install | bashWindows 用户我实测最省心的是 scoopscoop install opencode习惯 Node 生态的npm 全局安装也可以npm install -g opencode-ai因为 opencode 是 Go 写的所以如果你本机有 Go 环境还能直接源码安装顺便能拿到最新开发版go install github.com/sst/opencodelatest提示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\npmopencode 的执行文件应该就在这个目录下。如果是 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 doctordoctor会检查你的配置、环境变量、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.jsonWindows 是%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 真的“看懂”代码LSPLanguage 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 配 MavenAI 在项目里执行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 其他高频问题速查表我把这段时间累计遇到的典型问题整理成一张速查表方便你直接对照处理。现象常见原因解决办法opencode 命令找不到PATH 未配置或未刷新确认安装目录刷新 PATH重启终端/IDE启动后无法连接本地服务端口被占用或服务未启动杀掉残留 opencode 进程后重试模型请求一直转圈API Key 没配或额度超了检查环境变量跑 doctor 验证技能安装失败插件市场源不可达检查网络或手动下载技能包放到项目.opencode/目录Playwright 无法启动浏览器浏览器内核未安装执行npx playwright install chromium配置不生效修改了项目配置但没重开会话重启 opencode 或开新会话再试7. 我坚持用下来的几条实在建议关于 opencode最后分享几点我自己沉淀下来的使用心得算不上教程但确实帮我少走了很多弯路。模型别贪贵分场景用。我见过很多人一上来就上最强模型结果改个变量名也在烧钱。日常机械操作交给便宜模型或本地模型核心设计决策再调强模型成本能省一大截。AGENTS.md 值得认真写。每换一个项目或成员花十几分钟把项目怎么跑、怎么测、有什么约定写清楚后续所有 AI 会话的体验都会上一个台阶。这是投入产出比最高的一步。善用 Plan 模式。AI 直接改代码看着很爽但遇到重构类任务先让它出方案再动手能避免很多“改到一半发现方向错了”的尴尬。遇到报错先跑opencode doctor再看日志别急着重装。九成问题都是配置层面的日志里写得明明白白。这也是我琢磨了很久才养成的习惯——以前一报错就卸载重装纯粹是在浪费时间。
