最近技术社区里讨论度最高的 AI 编程工具除了 Claude Code、Codex 那一拨就是 opencode 了。我先说结论如果你想要一个“终端里能跑、编辑器里也能用、模型随便换、还能自己定义技能”的 AI 编程助手opencode 值得花一个下午认真折腾一下。这篇文章我会从安装、配置模型、Skills、Playwright 测试、编辑器插件到常见报错把我这两周实际跑通的经验全部整理出来新手照着做就行老手也可以直接跳到问题排查部分对号入座。1. opencode 到底是什么为什么值得关注1.1 认识 opencode不是又一个聊天机器人opencode 是一个开放源代码的 AI 编程代理AI coding agent它的核心定位和 Claude Code、Codex CLI 类似在终端里启动一个智能体让它读你的项目代码、理解任务、调用工具、修改文件、运行命令最终帮你在真实项目里完成开发任务。但 opencode 有几个明显不一样的地方。第一它不绑定某一家模型厂商Anthropic、OpenAI、Google、本地模型都能接模型对你来说就是一个配置项。第二它把 agent 的能力拆成了可插拔的模块比如 Skills技能包、MCP模型上下文协议、LSP语言服务器协议你可以按需组合。第三它的团队背景很硬由开源社区里做无服务器框架出名的 SST 团队开发后来被 Anthropic 收入麾下所以底层设计和工程质量在同类工具里属于第一梯队。很多人问“opencode 是哪家公司的”这里顺便说清楚项目最初由 SST 团队发起并开源后续 Anthropic 完成了对 opencode 的收购现在它可以算作 Anthropic 生态里的开源成员但项目本身依然保持独立开源不强制你用 Anthropic 的模型。1.2 它能做什么从读懂项目到真正“动手改代码”opencode 在真实开发里的能力边界我用我自己的使用场景来举例。最基础的能力是项目级上下文理解。你启动 opencode 后它会扫描项目结构、读取关键文件、理解技术栈然后你只要描述需求它就能在你现有代码基础上做修改。比如我接过一个老旧的 Java Maven 项目直接让它定位某个接口的调用链路并给出重构方案它能顺着代码把上下游模块都翻出来比我自己翻快得多。再往上是多工具调用。opencode 内置了终端命令执行、文件编辑、代码搜索等工具配合 Playwright 还能做浏览器自动化测试——我经常让它改完前端代码后自己打开页面跑一遍交互流程看有没有把按钮点崩。配合 LSP 的话它还能直接利用 IDE 级别的语义分析能力做跨文件的符号跳转和类型检查而不只是简单的文本匹配。它适合谁我觉得是这几类人主力用终端和 VSCode/JetBrains 的开发者、需要在已有项目里做 AI 辅助开发的团队、喜欢折腾工具链并希望高度自定义 AI 工作流的折腾党。如果你只是想要一个开箱即用、什么都不用配的聊天窗口它可能不是最省事的但如果你愿意花一点时间配置它能给你的开发流带来的提升是全方位的。2. 安装 opencode从零到跑起来2.1 环境准备先确认 Node 版本再动手opencode 的安装方式有几种最常用的是通过 npm 全局安装所以第一步是确认本机有 Node.js。这里我踩过坑opencode 对 Node 版本有要求我一开始用的是 Node 16装完启动直接报错升到 Node 20 之后才正常。建议直接装 Node 20 或更高版本避免不必要的麻烦。node -v npm -v如果两个命令都能正常输出版本号说明 Node 环境没问题。接下来安装 opencode 本体二选一# 方式一npm 全局安装 npm install -g opencode-ai # 方式二curl 脚本安装自动识别系统架构 curl -fsSL https://opencode.ai/install | bash我自己的习惯是 npm 安装因为后续升级方便直接npm update -g opencode-ai就行。安装完成后验证一下opencode --version如果能看到版本号输出恭喜核心程序已经跑起来了。2.2 Windows 下“无法将 opencode 项识别为 cmdlet”的解决思路这个报错是热词里出现频率最高的一个几乎每个 Windows 用户在命令行装完 opencode 后都会遇到opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。先说原因。这个提示表示 PowerShell 在当前环境变量 PATH 里找不到 opencode 这个可执行文件。常见的坑有三个npm 全局安装目录没有被加入 PATH安装过程被权限拦截实际上没有写入成功当前终端是在安装之前打开的没有刷新环境变量。我的处理步骤是先查 npm 全局目录npm prefix -g拿到路径比如C:\Users\你的用户名\AppData\Roaming\npm检查这个目录下有没有opencode.cmd或opencode.ps1文件如果没有说明安装写入失败建议用管理员身份重新运行安装命令打开 Windows 设置 → 系统 → 关于 → 高级系统设置 → 环境变量把上面的 npm 目录追加到 Path 变量里保存后关闭当前终端重新打开一个新的 PowerShell 窗口再执行opencode --version。如果还是不行就检查 npm 是否被系统防护软件拦截了写入。实测下来大多数情况下都是 PATH 没配置好的问题重新打开终端这个动作很容易被忽略但恰恰是最后一步最关键。2.3 首次启动登录模型服务商安装完成后直接输入opencode启动交互界面。首次使用它会引导你配置模型服务商。这里要解释一下 opencode 的模型接入逻辑它本身不提供模型所有推理能力来自你配置的模型提供方。你可以选择 Anthropic、OpenAI、Google Gemini、本地 Ollama或者任何兼容 OpenAI API 格式的服务地址。选择之后会生成一个用于登录的链接浏览器打开后授权即可。如果你暂时没有付费 API key也可以先用本地模型比如通过 Ollama 跑一个量化版本的小模型体验完整流程。不过说实话本地模型的推理能力和顶级商业模型差距还是很大做日常聊天还行做真正的 agent 任务建议用商业模型。我第一次启动时图省事直接选了默认配置结果后面发现默认模型在某些工具调用场景下表现一般。后来我改成了自己的 API key效果立刻不一样。这部分配置不仅可以随时改还可以针对不同项目用不同的模型后面我会专门讲。3. 配置与模型选择把 opencode 调成适合你的样子3.1 理解 opencode.json 配置文件opencode 的所有配置都集中在一个 JSON 文件里项目级配置放在项目根目录的opencode.json全局配置放在用户主目录下的~/.config/opencode/opencode.jsonWindows 路径略有不同。它的作用类似项目的.env加vite.config的合体。一个最基本的配置文件长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-20250514, provider: { anthropic: { api_key: your-api-key, model: claude-sonnet-4-20250514 } } }注意model字段的格式是厂商/模型名比如openai/gpt-4o、google/gemini-2.0-flash、ollama/llama3。这个命名规范贯穿全系统你在命令行、配置文件、Skills 里指定模型时都遵循这个格式。配置字段里我强烈建议保留$schema这一行这样在 VSCode 里编辑 JSON 时能获得自动补全和字段校验省去查文档的功夫。3.2 模型服务商选择免费与付费怎么权衡关于模型选择这是最多人问的问题。搜索热词里也反复出现“opencode 免费模型”和“opencode go 订阅模型选择”。先说免费层面。opencode 官方内置了对 Ollama 的支持你本地装好 Ollama 并拉取模型后在 opencode 配置文件里加一块 provider 就行{ provider: { ollama: { model: ollama/qwen2.5-coder:14b } } }本地模型的好处是免费、数据不出本机、离线可用适合代码片段解释、简单重构这类轻量任务。缺点是推理速度看机器配置14B 参数模型在我这台 M 系列芯片上勉强能用换成 32B 就明显变慢机器差一点的建议从 7B 或 8B 起步。商业模型方面你可以自己申请各家的 API key也可以使用各种商业订阅服务。如果你看到别人讨论“opencode go 套餐”“opencode 订阅模型选择”那通常指的是通过第三方聚合订阅服务来访问多个模型。这部分配置的本质是在 opencode 里设置一个自定义 provider 的 baseURL我见过不少人把这类配置和工具链混在一起用但要注意的是这类第三方服务的稳定性、安全性和合规性参差不齐如果你要用建议选择信誉良好的正规服务并且不要把敏感项目的 API key 随意交给不熟悉的渠道。我的建议是日常主力用一个性能强的商业模型同时保留一个本地模型做快速验证两者通过 opencode 的交互式切换来区分任务场景。另外要留意一点不同模型对工具调用的遵循程度差别巨大如果出现“改了文件但改错了”“命令执行一半就停下来”这类问题先怀疑模型能力再怀疑配置问题别在弱模型上死磕。3.3 Provider 混用与多模型切换opencode 支持一个项目里同时配置多个 provider然后用快捷键或者斜杠命令切换当前模型。这个能力非常实用。我在实际开发里会同时挂三个场景推荐模型优势日常编码、重构、写测试Claude Sonnet 系列或 GPT-4o代码理解强工具调用稳定复杂多文件修改、长链路推理更强的旗舰模型如 Claude Opus上下文窗口大思考链路完整简单问答、解释代码片段本地 Ollama 模型免费、隐私安全、响应快配置多个 provider 之后在 opencode 交互界面里可以直接切换模型像切换输入法一样方便。同一个需求用便宜模型快速过一遍思路再用强模型执行最终修改这是我目前性价比最高的用法。4. 核心玩法拆解Skills、Playwright、LSP 和记忆系统4.1 Skills给 AI 定制“专业动作”Search 热词里“opencode skills”和“opencode oh-my-claudecode”被反复搜索说明这个功能是大家最想搞懂的点。简单说Skills 是 opencode 里的“预设技能包”一个 Skill 就是一段带说明文本的提示词模板告诉 AI“当你遇到这类任务时应该按照什么步骤做、调用什么工具、遵循什么规范”。一个 Skill 通常是一个目录里面有SKILL.md描述文件还可能包含脚本和参考模板。比如我想让 opencode 在写 Rust 代码时自动遵循我团队的 clippy 规范就可以建一个 rust-style 的 Skill~/.config/opencode/skills/rust-style/SKILL.mdSKILL.md的内容大致是--- name: rust-style description: 在生成 Rust 代码时强制执行团队规范 --- 当你需要编写或修改 Rust 代码时必须遵循以下步骤 1. 检查项目根目录是否存在 clippy.toml读取其中的 lint 配置 2. 所有新代码必须通过 cargo clippy 检查且无 warning 3. 错误处理使用 thiserror 或 anyhow禁止 unwrap 直接透出到上层 4. 修改完成后运行 cargo fmt 并给出 diff 摘要。配置好后当你对 opencode 说“给这个模块加一个配置解析函数”它就会自动加载对应 Skill按预设规范执行。你不需要每次在提示词里重复这些要求相当于把团队最佳实践“编译”进了 agent 的潜意识。网上还有人分享了一个叫 “Superpowers” 的技能集合项目它把需求拆解、任务规划、代码评审等环节都做成了一个个标准化的 Skill装进 opencode 之后 agent 的处理流程会更有条理。安装方式也很简单克隆仓库把 skills 目录软链到 opencode 的 skills 目录即可。我实测下来它对“把模糊需求拆成可执行步骤”这个环节提升最明显推荐一试。4.2 用 Playwright 做前端 Bug 验证热词里“opencode playwright 怎么测试前端 bug”是我认为最值得重点讲的场景因为在所有 AI 编程工具里能把“改代码”和“验证页面”闭环的真的不多。opencode 通过 MCP模型上下文协议接入 Playwright让 AI 有能力启动浏览器、打开页面、模拟点击、填写表单、截图、读取控制台日志。这意味着你修完一个前端 bug 后可以直接让 opencode 自己打开页面跑一遍复现步骤确认问题真的被解决了。我的实际操作流程是这样的先让 opencode 修复某个已知 bug比如“表单校验失败后没有错误提示”然后直接输入指令“用 Playwright 打开本地开发服务器访问 /register 页面提交空表单截图并检查是否出现错误提示元素”。opencode 会调用 Playwright 工具依次执行打开浏览器、导航、填写、点击、截图等一系列操作最后把截图和检查结果返回给我。如果校验文案还没出现它会根据当前代码状态再调一轮修改直到通过测试条件。这个循环能力非常强等于把“手动刷新页面→肉眼检查→来回调”变成了自动闭环。配置 MCP 的方式是在opencode.json里注册一个 mcp 服务块。官方文档有 Playwright MCP server 的现成配置照抄即可。第一次用之前记得先npm install -g playwright/mcp并安装浏览器内核否则会报找不到浏览器的错误。4.3 LSP 集成让 AI 具备 IDE 级别的代码理解LSPLanguage Server Protocol集成是 opencode 的另一大杀器。传统上 AI 读代码是靠文本抓取加关键词匹配而 LSP 让 AI 能调用语言服务器获得“符号定义在哪里、这个变量有哪些引用、这个函数的类型签名是什么”这类精确的语义信息。我在一个 TypeScript 项目里实测过以前让 Claude Code 重构一个函数它经常因为改了函数签名但没改调用方而报错但 opencode 接上 TypeScript LSP 后它可以自动定位所有调用点把调用处一起改掉。这相当于 AI 从“拿着地图找路”升级成了“带 GPS 导航”。配置 LSP 不复杂在opencode.json里声明要启用的语言服务器即可。opencode 自带了对部分语言的内置支持比如 TypeScript、Python、Go 等。对于本地装了对应语言工具链的项目通常一键就能启用不需要手动写 LSP server 的启动命令。启用后你可以让 AI “查找这个 symbol 的所有引用并逐个分析”它会给出带文件和行号的精确结果而不是模糊的全文搜索。4.4 Memory 记忆功能让 AI 记住你的偏好热词里出现的“opencode memory”指的是 opencode 的长期记忆能力。它允许把一些跨会话的关键信息和偏好写入一个名为AGENTS.md还有旧版叫memory.md的文件里之后每次会话启动时AI 都会自动加载这个文件作为背景知识。举个例子我在前端项目的AGENTS.md里写了这些内容# 项目规范 - 组件库使用 Ant Design禁止手写样式实现已有组件 - 接口请求统一走 src/api 目录下的封装禁止在业务组件里直接写 fetch - 所有新增功能需要同步补充单元测试测试框架使用 Vitest - 提交信息遵循 conventional commits 规范。写完之后每次启动 opencode 处理这个项目它都会主动遵守这些约定。这个文件既适合个人用也适合团队放进 Git 仓库里统一维护新人和 AI 都能快速了解项目规矩。它的价值在于把“上下文”从一次性的 prompt 升级成了持续生效的项目记忆是提升 agent 产出质量性价比最高的配置之一。5. 编辑器与桌面体验VSCode、IDEA 和桌面版怎么选5.1 VSCode 插件在编辑器里直接召唤 AIopencode 官方提供了 VSCode 插件装好之后你不需要切到终端就能在当前编辑器窗口里和 agent 对话。我每天的实际使用场景是编辑器左侧开着 opencode 面板选中一段代码 ShiftEnter 发给它它返回修改建议后我可以直接点击“应用”改动会以 diff 形式呈现在编辑器里确认没问题再合入。这个“预览确认”的流程比终端里直接改文件安全很多尤其适合对 AI 修改还不完全放心的团队协作场景。插件还有一个很实用的能力上下文自动携带当前打开文件以及鼠标光标所在的行号。你在代码里点一下然后让 opencode “解释这里的逻辑”它知道你说的“这里”是哪里不需要你手动贴代码。安装很简单在 VSCode 扩展市场搜 “opencode” 安装然后打开侧边栏的 opencode 图标选择模型并启动即可。如果你已经有一个正在跑的 opencode 会话插件还能直接接管它复用上下文和对话历史。5.2 JetBrains IDEA 插件Java 和 Kotlin 项目的救星写 Java/Kotlin 的朋友更关心的应该是 IDEA 插件。我身边用 IntelliJ IDEA 的同事对 opencode 评价很高原因就一个它终于让 AI 真正理解了 IDEA 项目的结构而不只是拿 Maven 或者 Gradle 文件当摆设。IDEA 插件支持从 opencode 的配置里读取模型和 provider 设置也就是说你不需要在 IDEA 里再配一遍密钥。用法和 VSCode 插件类似侧边栏直接对话上下文自动跟随当前文件和光标位置。实测下来对一个 Spring Boot 项目做“给 UserController 加一个分页查询接口”这类任务它能正确识别项目里已有的 Service 层、Mapper 层结构生成的代码风格和团队现有代码一致。这里特意说一句如果你用的 IDE 是 IDEA项目中还涉及 Maven 多模块结构使用前先让 opencode 打开项目的根目录不要打开子模块目录。它需要看到整个 Maven 聚合结构才能正确理解模块依赖关系否则会出现 import 路径张冠李戴的问题。5.3 桌面版和 CLI多端覆盖你的工作流opencode 还提供了桌面版应用适合不想开终端、就像用独立聊天软件一样用 AI 的场景。桌面版同样支持多会话管理、模型切换和 Skills 加载数据与 CLI 版本共用同一套配置这边配好那边直接同步。不过我个人的主力还是 CLI 版。原因很简单当你在终端里跑测试、看日志、敲 git 命令时直接在一个界面里让 AI 读取报错并定位问题效率比切窗口再粘贴报错日志高得多。桌面版更适合做非编码类的对话任务比如让 AI 整理需求文档、设计接口方案这类偏“聊天”的活儿。按照我现在的习惯日常编码开 VSCode 插件复杂重构直接切到终端跑 CLI桌面版用来做方案讨论和文档生成。三个入口各司其职但背后是同一个项目配置和记忆体验非常连贯。6. 常见问题与避坑手册6.1 高频报错排查速查表这段时间群里交流最多的问题我把它们整理成了一个速查表按频率从高到低排列报错信息原因解决办法无法将“opencode”项识别为 cmdletPATH 未配置 / 安装未生效重新打开终端手动加入 npm 全局目录管理员身份重装unexpected server error. check server logs模型服务商接口异常 / API key 配额耗尽检查 API 余额和 key 有效性切换其他模型验证查看 ~/.local/share/opencode/log 日志this model is not available in your country模型在账号所在区域不可用检查账号区域设置和订阅套餐权限更换其他可用模型或服务商Error: connection refused本地服务未启动 / 代理冲突确认 Ollama 等服务已启动检查本地端口占用和网络配置module not found: playwright/mcpPlaywright MCP 未安装执行npm install -g playwright/mcp并重试这里面值得展开说一下的是this model is not available这个报错。翻译过来是“当前国家/地区不支持使用该模型”。第一次遇到时我也头大但这里要说清楚这不是 opencode 的问题而是模型服务商对模型可用区域做了限制。正规的处理思路是检查账号主体所在的区域、订阅套餐是否覆盖该模型或者换一个同厂可用模型。我在项目里就会配置一个备选模型主模型不可用时用一条命令切换过去避免工作中断。该报错的本质是权限和区域策略问题不要在工具层面想着“绕过”而是从模型选择和账号配置层面解决。6.2 Linux 下修改 JSON 配置的小技巧热词里有“opencode linux 修改 json”这可能是很多从 Windows 转到 Linux 开发机的人会遇到的小别扭。opencode 的全局配置在 Linux 下位于~/.config/opencode/opencode.json注意不是~/.opencode也不是项目根目录。有些版本的程序对 JSON 解析非常严格如果你手改配置时多了一个逗号或者注释掉了某一项启动时会直接报 parse error。我的习惯是改完立刻用node -e JSON.parse(require(fs).readFileSync(opencode.json))验证一下语法再启动 opencode。另外Linux 服务器上如果 headless 运行没有图形界面安装 Playwright 浏览器内核时要额外加--with-deps参数否则会缺一堆系统动态链接库报错信息往往很隐晦。可以直接跑npx playwright install --with-deps chromium把依赖一次性装齐。6.3 新手最容易忽略的 4 个配置细节最后分享几个反复被人问到的细节都是真实踩坑总结。第一不要在配置里把 API key 硬编码进项目级 opencode.json。项目级配置会跟着仓库走一旦提交到远程就有泄漏风险。正确做法是配置里只写 provider 名称key 通过环境变量注入比如OPencode_ANTHROPIC_API_KEY这类变量名。opencode 会自动读取环境变量不必再写进 JSON 文件。第二模型名一定要写准确。很多人在这一块翻车明明 key 是好的但模型名少写一个后缀就会报模型不存在。最稳妥的办法是在 opencode 交互里输入/models查看可用列表直接复制。第三Skills 目录位置别放错。项目级 Skills 放在项目根的.opencode/skills/全局 Skills 放在~/.config/opencode/skills/放反了不会被加载。第四超大项目的启动速度问题。如果你的项目文件非常多opencode 首次扫描会消耗不少时间。可以在配置文件里加上.gitignore同款规则让 opencode 跳过node_modules、dist、build这类目录减少无效文件对上下文的污染也能明显提升响应速度。配置方式是在opencode.json里设置 ignore 字段我一般会把常见的构建产物目录全部列进去。最后再分享一个我自己的小习惯每次开始新项目前先在项目根目录建好AGENTS.md把技术栈、目录结构、代码规范、测试命令这些基础信息写清楚。这前后花不了十分钟但之后每次让 opencode 干活它给出的方案贴合度都明显更高。工具用得越久越会发现给它喂好“背景知识”比换更强的模型更能带来实际体验的提升。opencode 说到底是一个放大开发者意图的框架你定义得越清楚它执行得就越靠谱。
opencode完全指南：从安装配置到Skills与Playwright实战
最近技术社区里讨论度最高的 AI 编程工具除了 Claude Code、Codex 那一拨就是 opencode 了。我先说结论如果你想要一个“终端里能跑、编辑器里也能用、模型随便换、还能自己定义技能”的 AI 编程助手opencode 值得花一个下午认真折腾一下。这篇文章我会从安装、配置模型、Skills、Playwright 测试、编辑器插件到常见报错把我这两周实际跑通的经验全部整理出来新手照着做就行老手也可以直接跳到问题排查部分对号入座。1. opencode 到底是什么为什么值得关注1.1 认识 opencode不是又一个聊天机器人opencode 是一个开放源代码的 AI 编程代理AI coding agent它的核心定位和 Claude Code、Codex CLI 类似在终端里启动一个智能体让它读你的项目代码、理解任务、调用工具、修改文件、运行命令最终帮你在真实项目里完成开发任务。但 opencode 有几个明显不一样的地方。第一它不绑定某一家模型厂商Anthropic、OpenAI、Google、本地模型都能接模型对你来说就是一个配置项。第二它把 agent 的能力拆成了可插拔的模块比如 Skills技能包、MCP模型上下文协议、LSP语言服务器协议你可以按需组合。第三它的团队背景很硬由开源社区里做无服务器框架出名的 SST 团队开发后来被 Anthropic 收入麾下所以底层设计和工程质量在同类工具里属于第一梯队。很多人问“opencode 是哪家公司的”这里顺便说清楚项目最初由 SST 团队发起并开源后续 Anthropic 完成了对 opencode 的收购现在它可以算作 Anthropic 生态里的开源成员但项目本身依然保持独立开源不强制你用 Anthropic 的模型。1.2 它能做什么从读懂项目到真正“动手改代码”opencode 在真实开发里的能力边界我用我自己的使用场景来举例。最基础的能力是项目级上下文理解。你启动 opencode 后它会扫描项目结构、读取关键文件、理解技术栈然后你只要描述需求它就能在你现有代码基础上做修改。比如我接过一个老旧的 Java Maven 项目直接让它定位某个接口的调用链路并给出重构方案它能顺着代码把上下游模块都翻出来比我自己翻快得多。再往上是多工具调用。opencode 内置了终端命令执行、文件编辑、代码搜索等工具配合 Playwright 还能做浏览器自动化测试——我经常让它改完前端代码后自己打开页面跑一遍交互流程看有没有把按钮点崩。配合 LSP 的话它还能直接利用 IDE 级别的语义分析能力做跨文件的符号跳转和类型检查而不只是简单的文本匹配。它适合谁我觉得是这几类人主力用终端和 VSCode/JetBrains 的开发者、需要在已有项目里做 AI 辅助开发的团队、喜欢折腾工具链并希望高度自定义 AI 工作流的折腾党。如果你只是想要一个开箱即用、什么都不用配的聊天窗口它可能不是最省事的但如果你愿意花一点时间配置它能给你的开发流带来的提升是全方位的。2. 安装 opencode从零到跑起来2.1 环境准备先确认 Node 版本再动手opencode 的安装方式有几种最常用的是通过 npm 全局安装所以第一步是确认本机有 Node.js。这里我踩过坑opencode 对 Node 版本有要求我一开始用的是 Node 16装完启动直接报错升到 Node 20 之后才正常。建议直接装 Node 20 或更高版本避免不必要的麻烦。node -v npm -v如果两个命令都能正常输出版本号说明 Node 环境没问题。接下来安装 opencode 本体二选一# 方式一npm 全局安装 npm install -g opencode-ai # 方式二curl 脚本安装自动识别系统架构 curl -fsSL https://opencode.ai/install | bash我自己的习惯是 npm 安装因为后续升级方便直接npm update -g opencode-ai就行。安装完成后验证一下opencode --version如果能看到版本号输出恭喜核心程序已经跑起来了。2.2 Windows 下“无法将 opencode 项识别为 cmdlet”的解决思路这个报错是热词里出现频率最高的一个几乎每个 Windows 用户在命令行装完 opencode 后都会遇到opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。先说原因。这个提示表示 PowerShell 在当前环境变量 PATH 里找不到 opencode 这个可执行文件。常见的坑有三个npm 全局安装目录没有被加入 PATH安装过程被权限拦截实际上没有写入成功当前终端是在安装之前打开的没有刷新环境变量。我的处理步骤是先查 npm 全局目录npm prefix -g拿到路径比如C:\Users\你的用户名\AppData\Roaming\npm检查这个目录下有没有opencode.cmd或opencode.ps1文件如果没有说明安装写入失败建议用管理员身份重新运行安装命令打开 Windows 设置 → 系统 → 关于 → 高级系统设置 → 环境变量把上面的 npm 目录追加到 Path 变量里保存后关闭当前终端重新打开一个新的 PowerShell 窗口再执行opencode --version。如果还是不行就检查 npm 是否被系统防护软件拦截了写入。实测下来大多数情况下都是 PATH 没配置好的问题重新打开终端这个动作很容易被忽略但恰恰是最后一步最关键。2.3 首次启动登录模型服务商安装完成后直接输入opencode启动交互界面。首次使用它会引导你配置模型服务商。这里要解释一下 opencode 的模型接入逻辑它本身不提供模型所有推理能力来自你配置的模型提供方。你可以选择 Anthropic、OpenAI、Google Gemini、本地 Ollama或者任何兼容 OpenAI API 格式的服务地址。选择之后会生成一个用于登录的链接浏览器打开后授权即可。如果你暂时没有付费 API key也可以先用本地模型比如通过 Ollama 跑一个量化版本的小模型体验完整流程。不过说实话本地模型的推理能力和顶级商业模型差距还是很大做日常聊天还行做真正的 agent 任务建议用商业模型。我第一次启动时图省事直接选了默认配置结果后面发现默认模型在某些工具调用场景下表现一般。后来我改成了自己的 API key效果立刻不一样。这部分配置不仅可以随时改还可以针对不同项目用不同的模型后面我会专门讲。3. 配置与模型选择把 opencode 调成适合你的样子3.1 理解 opencode.json 配置文件opencode 的所有配置都集中在一个 JSON 文件里项目级配置放在项目根目录的opencode.json全局配置放在用户主目录下的~/.config/opencode/opencode.jsonWindows 路径略有不同。它的作用类似项目的.env加vite.config的合体。一个最基本的配置文件长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-20250514, provider: { anthropic: { api_key: your-api-key, model: claude-sonnet-4-20250514 } } }注意model字段的格式是厂商/模型名比如openai/gpt-4o、google/gemini-2.0-flash、ollama/llama3。这个命名规范贯穿全系统你在命令行、配置文件、Skills 里指定模型时都遵循这个格式。配置字段里我强烈建议保留$schema这一行这样在 VSCode 里编辑 JSON 时能获得自动补全和字段校验省去查文档的功夫。3.2 模型服务商选择免费与付费怎么权衡关于模型选择这是最多人问的问题。搜索热词里也反复出现“opencode 免费模型”和“opencode go 订阅模型选择”。先说免费层面。opencode 官方内置了对 Ollama 的支持你本地装好 Ollama 并拉取模型后在 opencode 配置文件里加一块 provider 就行{ provider: { ollama: { model: ollama/qwen2.5-coder:14b } } }本地模型的好处是免费、数据不出本机、离线可用适合代码片段解释、简单重构这类轻量任务。缺点是推理速度看机器配置14B 参数模型在我这台 M 系列芯片上勉强能用换成 32B 就明显变慢机器差一点的建议从 7B 或 8B 起步。商业模型方面你可以自己申请各家的 API key也可以使用各种商业订阅服务。如果你看到别人讨论“opencode go 套餐”“opencode 订阅模型选择”那通常指的是通过第三方聚合订阅服务来访问多个模型。这部分配置的本质是在 opencode 里设置一个自定义 provider 的 baseURL我见过不少人把这类配置和工具链混在一起用但要注意的是这类第三方服务的稳定性、安全性和合规性参差不齐如果你要用建议选择信誉良好的正规服务并且不要把敏感项目的 API key 随意交给不熟悉的渠道。我的建议是日常主力用一个性能强的商业模型同时保留一个本地模型做快速验证两者通过 opencode 的交互式切换来区分任务场景。另外要留意一点不同模型对工具调用的遵循程度差别巨大如果出现“改了文件但改错了”“命令执行一半就停下来”这类问题先怀疑模型能力再怀疑配置问题别在弱模型上死磕。3.3 Provider 混用与多模型切换opencode 支持一个项目里同时配置多个 provider然后用快捷键或者斜杠命令切换当前模型。这个能力非常实用。我在实际开发里会同时挂三个场景推荐模型优势日常编码、重构、写测试Claude Sonnet 系列或 GPT-4o代码理解强工具调用稳定复杂多文件修改、长链路推理更强的旗舰模型如 Claude Opus上下文窗口大思考链路完整简单问答、解释代码片段本地 Ollama 模型免费、隐私安全、响应快配置多个 provider 之后在 opencode 交互界面里可以直接切换模型像切换输入法一样方便。同一个需求用便宜模型快速过一遍思路再用强模型执行最终修改这是我目前性价比最高的用法。4. 核心玩法拆解Skills、Playwright、LSP 和记忆系统4.1 Skills给 AI 定制“专业动作”Search 热词里“opencode skills”和“opencode oh-my-claudecode”被反复搜索说明这个功能是大家最想搞懂的点。简单说Skills 是 opencode 里的“预设技能包”一个 Skill 就是一段带说明文本的提示词模板告诉 AI“当你遇到这类任务时应该按照什么步骤做、调用什么工具、遵循什么规范”。一个 Skill 通常是一个目录里面有SKILL.md描述文件还可能包含脚本和参考模板。比如我想让 opencode 在写 Rust 代码时自动遵循我团队的 clippy 规范就可以建一个 rust-style 的 Skill~/.config/opencode/skills/rust-style/SKILL.mdSKILL.md的内容大致是--- name: rust-style description: 在生成 Rust 代码时强制执行团队规范 --- 当你需要编写或修改 Rust 代码时必须遵循以下步骤 1. 检查项目根目录是否存在 clippy.toml读取其中的 lint 配置 2. 所有新代码必须通过 cargo clippy 检查且无 warning 3. 错误处理使用 thiserror 或 anyhow禁止 unwrap 直接透出到上层 4. 修改完成后运行 cargo fmt 并给出 diff 摘要。配置好后当你对 opencode 说“给这个模块加一个配置解析函数”它就会自动加载对应 Skill按预设规范执行。你不需要每次在提示词里重复这些要求相当于把团队最佳实践“编译”进了 agent 的潜意识。网上还有人分享了一个叫 “Superpowers” 的技能集合项目它把需求拆解、任务规划、代码评审等环节都做成了一个个标准化的 Skill装进 opencode 之后 agent 的处理流程会更有条理。安装方式也很简单克隆仓库把 skills 目录软链到 opencode 的 skills 目录即可。我实测下来它对“把模糊需求拆成可执行步骤”这个环节提升最明显推荐一试。4.2 用 Playwright 做前端 Bug 验证热词里“opencode playwright 怎么测试前端 bug”是我认为最值得重点讲的场景因为在所有 AI 编程工具里能把“改代码”和“验证页面”闭环的真的不多。opencode 通过 MCP模型上下文协议接入 Playwright让 AI 有能力启动浏览器、打开页面、模拟点击、填写表单、截图、读取控制台日志。这意味着你修完一个前端 bug 后可以直接让 opencode 自己打开页面跑一遍复现步骤确认问题真的被解决了。我的实际操作流程是这样的先让 opencode 修复某个已知 bug比如“表单校验失败后没有错误提示”然后直接输入指令“用 Playwright 打开本地开发服务器访问 /register 页面提交空表单截图并检查是否出现错误提示元素”。opencode 会调用 Playwright 工具依次执行打开浏览器、导航、填写、点击、截图等一系列操作最后把截图和检查结果返回给我。如果校验文案还没出现它会根据当前代码状态再调一轮修改直到通过测试条件。这个循环能力非常强等于把“手动刷新页面→肉眼检查→来回调”变成了自动闭环。配置 MCP 的方式是在opencode.json里注册一个 mcp 服务块。官方文档有 Playwright MCP server 的现成配置照抄即可。第一次用之前记得先npm install -g playwright/mcp并安装浏览器内核否则会报找不到浏览器的错误。4.3 LSP 集成让 AI 具备 IDE 级别的代码理解LSPLanguage Server Protocol集成是 opencode 的另一大杀器。传统上 AI 读代码是靠文本抓取加关键词匹配而 LSP 让 AI 能调用语言服务器获得“符号定义在哪里、这个变量有哪些引用、这个函数的类型签名是什么”这类精确的语义信息。我在一个 TypeScript 项目里实测过以前让 Claude Code 重构一个函数它经常因为改了函数签名但没改调用方而报错但 opencode 接上 TypeScript LSP 后它可以自动定位所有调用点把调用处一起改掉。这相当于 AI 从“拿着地图找路”升级成了“带 GPS 导航”。配置 LSP 不复杂在opencode.json里声明要启用的语言服务器即可。opencode 自带了对部分语言的内置支持比如 TypeScript、Python、Go 等。对于本地装了对应语言工具链的项目通常一键就能启用不需要手动写 LSP server 的启动命令。启用后你可以让 AI “查找这个 symbol 的所有引用并逐个分析”它会给出带文件和行号的精确结果而不是模糊的全文搜索。4.4 Memory 记忆功能让 AI 记住你的偏好热词里出现的“opencode memory”指的是 opencode 的长期记忆能力。它允许把一些跨会话的关键信息和偏好写入一个名为AGENTS.md还有旧版叫memory.md的文件里之后每次会话启动时AI 都会自动加载这个文件作为背景知识。举个例子我在前端项目的AGENTS.md里写了这些内容# 项目规范 - 组件库使用 Ant Design禁止手写样式实现已有组件 - 接口请求统一走 src/api 目录下的封装禁止在业务组件里直接写 fetch - 所有新增功能需要同步补充单元测试测试框架使用 Vitest - 提交信息遵循 conventional commits 规范。写完之后每次启动 opencode 处理这个项目它都会主动遵守这些约定。这个文件既适合个人用也适合团队放进 Git 仓库里统一维护新人和 AI 都能快速了解项目规矩。它的价值在于把“上下文”从一次性的 prompt 升级成了持续生效的项目记忆是提升 agent 产出质量性价比最高的配置之一。5. 编辑器与桌面体验VSCode、IDEA 和桌面版怎么选5.1 VSCode 插件在编辑器里直接召唤 AIopencode 官方提供了 VSCode 插件装好之后你不需要切到终端就能在当前编辑器窗口里和 agent 对话。我每天的实际使用场景是编辑器左侧开着 opencode 面板选中一段代码 ShiftEnter 发给它它返回修改建议后我可以直接点击“应用”改动会以 diff 形式呈现在编辑器里确认没问题再合入。这个“预览确认”的流程比终端里直接改文件安全很多尤其适合对 AI 修改还不完全放心的团队协作场景。插件还有一个很实用的能力上下文自动携带当前打开文件以及鼠标光标所在的行号。你在代码里点一下然后让 opencode “解释这里的逻辑”它知道你说的“这里”是哪里不需要你手动贴代码。安装很简单在 VSCode 扩展市场搜 “opencode” 安装然后打开侧边栏的 opencode 图标选择模型并启动即可。如果你已经有一个正在跑的 opencode 会话插件还能直接接管它复用上下文和对话历史。5.2 JetBrains IDEA 插件Java 和 Kotlin 项目的救星写 Java/Kotlin 的朋友更关心的应该是 IDEA 插件。我身边用 IntelliJ IDEA 的同事对 opencode 评价很高原因就一个它终于让 AI 真正理解了 IDEA 项目的结构而不只是拿 Maven 或者 Gradle 文件当摆设。IDEA 插件支持从 opencode 的配置里读取模型和 provider 设置也就是说你不需要在 IDEA 里再配一遍密钥。用法和 VSCode 插件类似侧边栏直接对话上下文自动跟随当前文件和光标位置。实测下来对一个 Spring Boot 项目做“给 UserController 加一个分页查询接口”这类任务它能正确识别项目里已有的 Service 层、Mapper 层结构生成的代码风格和团队现有代码一致。这里特意说一句如果你用的 IDE 是 IDEA项目中还涉及 Maven 多模块结构使用前先让 opencode 打开项目的根目录不要打开子模块目录。它需要看到整个 Maven 聚合结构才能正确理解模块依赖关系否则会出现 import 路径张冠李戴的问题。5.3 桌面版和 CLI多端覆盖你的工作流opencode 还提供了桌面版应用适合不想开终端、就像用独立聊天软件一样用 AI 的场景。桌面版同样支持多会话管理、模型切换和 Skills 加载数据与 CLI 版本共用同一套配置这边配好那边直接同步。不过我个人的主力还是 CLI 版。原因很简单当你在终端里跑测试、看日志、敲 git 命令时直接在一个界面里让 AI 读取报错并定位问题效率比切窗口再粘贴报错日志高得多。桌面版更适合做非编码类的对话任务比如让 AI 整理需求文档、设计接口方案这类偏“聊天”的活儿。按照我现在的习惯日常编码开 VSCode 插件复杂重构直接切到终端跑 CLI桌面版用来做方案讨论和文档生成。三个入口各司其职但背后是同一个项目配置和记忆体验非常连贯。6. 常见问题与避坑手册6.1 高频报错排查速查表这段时间群里交流最多的问题我把它们整理成了一个速查表按频率从高到低排列报错信息原因解决办法无法将“opencode”项识别为 cmdletPATH 未配置 / 安装未生效重新打开终端手动加入 npm 全局目录管理员身份重装unexpected server error. check server logs模型服务商接口异常 / API key 配额耗尽检查 API 余额和 key 有效性切换其他模型验证查看 ~/.local/share/opencode/log 日志this model is not available in your country模型在账号所在区域不可用检查账号区域设置和订阅套餐权限更换其他可用模型或服务商Error: connection refused本地服务未启动 / 代理冲突确认 Ollama 等服务已启动检查本地端口占用和网络配置module not found: playwright/mcpPlaywright MCP 未安装执行npm install -g playwright/mcp并重试这里面值得展开说一下的是this model is not available这个报错。翻译过来是“当前国家/地区不支持使用该模型”。第一次遇到时我也头大但这里要说清楚这不是 opencode 的问题而是模型服务商对模型可用区域做了限制。正规的处理思路是检查账号主体所在的区域、订阅套餐是否覆盖该模型或者换一个同厂可用模型。我在项目里就会配置一个备选模型主模型不可用时用一条命令切换过去避免工作中断。该报错的本质是权限和区域策略问题不要在工具层面想着“绕过”而是从模型选择和账号配置层面解决。6.2 Linux 下修改 JSON 配置的小技巧热词里有“opencode linux 修改 json”这可能是很多从 Windows 转到 Linux 开发机的人会遇到的小别扭。opencode 的全局配置在 Linux 下位于~/.config/opencode/opencode.json注意不是~/.opencode也不是项目根目录。有些版本的程序对 JSON 解析非常严格如果你手改配置时多了一个逗号或者注释掉了某一项启动时会直接报 parse error。我的习惯是改完立刻用node -e JSON.parse(require(fs).readFileSync(opencode.json))验证一下语法再启动 opencode。另外Linux 服务器上如果 headless 运行没有图形界面安装 Playwright 浏览器内核时要额外加--with-deps参数否则会缺一堆系统动态链接库报错信息往往很隐晦。可以直接跑npx playwright install --with-deps chromium把依赖一次性装齐。6.3 新手最容易忽略的 4 个配置细节最后分享几个反复被人问到的细节都是真实踩坑总结。第一不要在配置里把 API key 硬编码进项目级 opencode.json。项目级配置会跟着仓库走一旦提交到远程就有泄漏风险。正确做法是配置里只写 provider 名称key 通过环境变量注入比如OPencode_ANTHROPIC_API_KEY这类变量名。opencode 会自动读取环境变量不必再写进 JSON 文件。第二模型名一定要写准确。很多人在这一块翻车明明 key 是好的但模型名少写一个后缀就会报模型不存在。最稳妥的办法是在 opencode 交互里输入/models查看可用列表直接复制。第三Skills 目录位置别放错。项目级 Skills 放在项目根的.opencode/skills/全局 Skills 放在~/.config/opencode/skills/放反了不会被加载。第四超大项目的启动速度问题。如果你的项目文件非常多opencode 首次扫描会消耗不少时间。可以在配置文件里加上.gitignore同款规则让 opencode 跳过node_modules、dist、build这类目录减少无效文件对上下文的污染也能明显提升响应速度。配置方式是在opencode.json里设置 ignore 字段我一般会把常见的构建产物目录全部列进去。最后再分享一个我自己的小习惯每次开始新项目前先在项目根目录建好AGENTS.md把技术栈、目录结构、代码规范、测试命令这些基础信息写清楚。这前后花不了十分钟但之后每次让 opencode 干活它给出的方案贴合度都明显更高。工具用得越久越会发现给它喂好“背景知识”比换更强的模型更能带来实际体验的提升。opencode 说到底是一个放大开发者意图的框架你定义得越清楚它执行得就越靠谱。
