最近圈子里聊opencode的人明显变多了。如果你一直关注AI编程工具应该已经看到不少从Claude Code、Codex CLI迁移过来的帖子。我自己过去半年一直用Claude Code写原型和修bug但上个月把主力Agent换成了opencode配合VSCode插件、Skills、Memory一起用体验比预想的更稳。这篇文章不打算当官方文档的复读机而是把我从安装、配置、多模型切换、项目实战到各种报错排查的完整过程整理出来给想上手或者已经踩坑的朋友一个参考。先说结论opencode是个开源的、跑在终端里的AI编程Agent界面做得像IDE里的代码审查工具但它本身是模型无关的OpenAI、Anthropic、Ollama本地模型、OpenRouter都能接。最爽的一点是它不锁死任何一家模型厂商今天用Claude明天换GPT后天切回本地Qwen一条命令的事。再加上Skills和Memory机制它正在变成一个可以长期积累项目经验的“私人助理”而不只是“一次性问答机器人”。1. 先把话说清楚opencode到底是什么1.1 一个开源、模型无关的终端AI编程Agent很多人在搜索栏里敲“opencode是哪家公司的”其实它不来自任何大厂。opencode是SST团队就是做Serverless Stack那帮人维护的开源项目代码在GitHub上核心是用TypeScript写的所以安装它不需要额外装Go环境只要有Node.js就行。这点容易被网上各种教程带偏后面我专门说。它的启动界面不是普通命令行那种黑底白字而是一个TUI终端交互界面可以分栏显示代码diff、文件树和对话内容。用起来的感觉有点像在IDE里装了插件但你又确实活在终端里。正因为它什么都看得见——文件、diff、git状态、命令输出——它在处理真实项目时的效果好过那些只能“读代码”的工具。从版本节奏看opencode 2.0的完成度已经相当高了模型的切换、Tools调用权限、Skills目录这些核心机制都稳定了。我测试过它在React、Express、Java Spring Boot、Python后端等不同项目里的表现日常开发完全够用。1.2 和Claude Code、Codex CLI、Pi这几个热门Agent对比我身边经常有人问opencode、codex、claude code哪个agent好用。说实话这个问题没有标准答案因为它们的定位不太一样。我把自己试用过的感受整理成了表格方便你按需求选。对比项opencodeClaude CodeCodex CLIPi (Warp)开源是源码开放否部分开源否模型绑定模型无关任意切换绑定Claude系列绑定OpenAI系列绑定自家模型本地免费模型支持Ollama接入不支持不支持不支持Skills扩展有完整Skills机制有类似能力刚起步有限Memory记忆有跨会话弱一些弱弱IDE插件VSCode、JetBrains都有官方插件有限有桌面版有无无有我个人观点如果你只用一个生态比如重度依赖Claude或GPTClaude Code和Codex CLI确实顺手。但如果你经常换模型或者想用免费模型跑一些不敏感的小任务opencode的“模型无关”设计就是最大的优势。尤其是Ollama这套组合拳对预算敏感的朋友非常友好。1.3 opencode现在能干什么解释陌生项目把整个仓库丢给它让它梳理技术栈、模块关系、启动流程写代码和重构多文件修改、跨文件重命名、调整接口定义执行命令跑测试、装依赖、启动服务都会经过权限确认写测试和修bug结合Playwright可以做前端bug复现长期记忆把项目约定、目录规范、踩坑记录写进Memory下次自动读取自定义Skills比如让它按团队规范写commit信息、做代码审查简单说它不是一个只能“聊天”的助手而是一个能实际碰你代码、能跑命令、能翻Issue的工具。2. 安装、启动和那些经典报错2.1 安装方式npm和brew以及“不需要Go环境”的辟谣opencode的安装比大多数人想象中简单。如果你用的是macOS或Linux有Homebrew就直接执行brew install sst/tap/opencode如果是Windows或者想保持最新版推荐用npm全局安装npm install -g opencode-ai装完之后验证一下版本opencode --version这里我要专门辟个谣。网络热词里频繁出现“opencode go”有些教程写着写着变味了说“opencode是用Go写的要先装Go环境”。实际上它跟Go没有任何直接关系核心是TypeScript你装好Node.js 18以上版本就行。我见过不少人在这一步绕了远路装了一堆没必要的东西。装好之后在项目目录里直接运行opencode就会进入TUI界面。2.2 Windows下最常见的“无法将‘opencode’项识别为cmdlet”错误这个报错在Windows用户里出现频率极高几乎占了搜索热词的一大半。看到“opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称”别慌十有八九是npm全局安装目录没进PATH。先运行这条命令查看npm全局的bin路径npm prefix -gWindows下通常会得到类似这样的输出C:\Users\你的用户名\AppData\Roaming\npm把这个路径加到系统环境变量的PATH里然后重新打开一个PowerShell窗口opencode就能识别了。如果你用的是nvm-windows路径里会多一层nodejs版本目录原理一样。另外还有一种情况是PowerShell执行策略拦住了脚本。如果直接运行报“因为在此系统上禁止运行脚本”的错可以用管理员权限执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser实在懒得配环境变量也可以用npx临时跑一次npx opencode-ai但只建议应急用每次启动会慢一些。2.3 首次启动配置模型和API Key在项目目录里运行opencode后第一次会提示你配置模型。它优先读取环境变量里的ANTHROPIC_API_KEY和OPENAI_API_KEY你设置了哪个它默认就用哪个。如果你两个都没设置也不用急进入TUI后可以按快捷键打开配置指定模型来源。比较常规的做法是先把API Key设置到环境变量里避免直接写进项目代码export ANTHROPIC_API_KEYsk-ant-xxx export OPENAI_API_KEYsk-xxxWindows下用setx但设置完要重开终端才会生效。如果你用的不是官方模型而是OpenRouter、Ollama这些那就要靠配置文件了这一步建议直接看下一章。3. 配置文件与多模型切换opencode.json、CC Switch这些怎么搭3.1 opencode.json的完整结构opencode的配置集中在opencode.json里。全局配置文件在~/.config/opencode/opencode.jsonWindows是%USERPROFILE%\.config\opencode\opencode.json项目级配置在项目根的.opencode/opencode.json。优先级是项目级覆盖全局级这也是我推荐的用法全局只放通用模型和通用规则项目级放这个项目特有的东西。下面是一个常见的配置文件结构我加了注释方便理解{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet, provider: { openrouter: { npm: ai-sdk/openai-compatible, name: OpenRouter, options: { baseURL: https://openrouter.ai/api/v1 }, models: [ openai/gpt-4o, anthropic/claude-3.5-sonnet, deepseek/deepseek-chat ], api_key: sk-or-xxx }, ollama: { npm: ai-sdk/ollama, name: Ollama本地, options: { baseURL: http://localhost:11434/api }, models: [qwen2.5-coder:14b, llama3.1:8b] } }, permissions: { allow: [git status, git diff, npm run lint], deny: [rm -rf, git push --force] } }需要注意一点不同版本对字段的支持会有细微差异。最稳妥的办法是打开opencode的官方配置schema页面边填边校验。我建议第一次配置不要写太复杂能跑通一个模型再加下一个。3.2 免费模型怎么接Ollama、OpenRouter、社区免费端点很多人搜“opencode免费模型”核心诉求就一句话不花钱先跑起来。这方面opencode优势很大。第一种是Ollama本地模型。你本地装好Ollama之后拉一个代码能力不错的模型ollama pull qwen2.5-coder:14b ollama serve然后在opencode.json里配置上面那个ollama provider重启opencode就能看到本地模型选项。它在无网环境下也能跑代码生成和单测补全能力都还行对付日常脚本和内部项目绰绰有余。第二种是OpenRouter的免费模型。OpenRouter本身是一个模型聚合平台上面对话列表里可以筛选“Free”标签的模型拿到API Key之后配到配置文件里就行。缺点是免费档通常有速率限制高峰期偶尔会被排队。**第三种是各种社区免费端点。**我会把它单独拎出来说因为这里坑最多。像搜索热词里的“hy3-free下线了吗”说明很多人之前在用社区维护的免费端点这类端点确实经常出现关闭、限流、密钥失效的情况。我的态度是临时体验可以但不要把公司的业务代码或隐私信息发上去真要持续使用还是自己接Ollama或者付费API更稳。顺便说一下很多人问的“opencode套餐”opencode本身是开源免费的根本不存在“套餐”这个东西。你花钱花在的是模型提供方的API调用费或者某些第三方平台的订阅费跟opencode没有任何关系。3.3 用CC Switch管理多套Provider配置“opencode go 需要配合 cc switch 等工具”这个热搜词说的其实是很多人用CC Switch来管理多套API配置。CC Switch是一款开源的API配置切换工具它原本是给Claude Code用户用的后来因为支持了opencode的配置模式成了很多opencode玩家的标配。它的价值在哪儿如果你接入了OpenAI、Anthropic、OpenRouter、Ollama好几套模型手动改环境变量非常容易出错。CC Switch可以一键切换当前的默认提供方把对应的ANTHROPIC_API_KEY、OPENAI_API_KEY这些环境变量自动配好。我实际使用中的经验有几点在CC Switch里新增Provider时选择目标应用为opencode它会自动把key写到正确的位置。切换完Provider之后一定要重启你的终端再启动opencode环境变量才生效。如果opencode.json里手动写了api_key环境变量的优先级未必压得过它两处都写了容易产生“切了等于没切”的错觉。我建议配置里不写key统一交给CC Switch管。一句话总结opencode是引擎CC Switch是换挡器两者搭配才能真正做到模型随便切、配置不用愁。4. 进阶玩法Skills、Memory、权限与IDE插件4.1 Skills给Agent加自定义技能Skills是opencode最有想象力的功能之一。它允许你给Agent定义一套“行为预设”类似给zsh装oh-my-zsh、给Claude Code装oh-my-claudecode。每个Skill是一个Markdown文件里面有名字、描述和具体的提示词。当Agent发现当前任务匹配某个Skill的描述时就会自动加载它。Skill有两层位置项目级放在.opencode/skills/目录全局级放在~/.config/opencode/skills/目录。我举个例子比如我想让Agent用团队规范写Git提交信息就创建一个commit-message.md--- name: git-commit description: 根据git暂存区的diff生成符合Angular规范的提交信息 --- 你是一位严格的Git提交信息审核者。执行以下步骤 1. 运行 git status 和 git diff --staged 查看暂存内容 2. 判断本次提交的类型feat/fix/docs/refactor/test/chore 3. 检查提交信息是否超过50个字符 4. 只输出干净的提交信息不要额外解释写完保存后重启opencode以后它看到要生成提交信息时就会按这套规范执行。社区里还流行直接安装superpowers技能包这是一个聚合了代码审查、重构、测试生成等多种能力的Skills合集。安装也不复杂git clone https://github.com/obra/superpowers.git ~/.config/opencode/skills/superpowers之后重启opencode就能在对话里触发相关技能了。有一点要提醒Skill文件里的description一定要写得清晰、有辨识度否则Agent容易在无关任务里误触发白白浪费上下文窗口。4.2 Memory让Agent记住项目上下文“opencode memory”是很多人的搜索关键词。这个功能解决的是AI编程工具最让人头疼的问题每次开新会话Agent就把之前的上下文全忘了。Memory机制允许你把项目的重要信息持久化下来下次启动自动读取。使用场景很直接。比如你接手的项目里有套奇怪的启动命令或者某个目录约定不能动你可以直接对Agent说记住这个项目的dev server必须在终端执行 yarn dev:custom不能用 npm run dev。opencode会把它存到Memory文件里。也可以手动创建.opencode/memory/目录下的markdown文件结构可以自己定义建议按tech-stack.md、commands.md、conventions.md这种维度拆分别一个文件记到天荒地老否则后期很难维护。实测下来Memory对“接手陌生项目”的帮助最大。你把技术栈、启动命令、常见坑位全部写进去后面每次让Agent改代码它都能直接引用误差小很多。不过也要定期清理过时信息比如某个依赖已经换掉了旧记忆反而会误导它。4.3 权限系统哪些命令能跑哪些要问opencode会在执行命令之前弹出确认请求这设计很合理。但如果你觉得一个命令特别安全或者特别危险可以在配置文件里加权限规则。{ permissions: { allow: [ git status, git diff, npm run lint, npm run test ], deny: [ rm -rf, git push --force, npx kill-port ] } }我个人强烈建议像rm -rf、git push --force、直接操作生产环境的命令一律写进deny。虽然这会让Agent在执行某些操作时报错但安全第一尤其是团队协作项目你不想让Agent自作主张把别人分支推挂掉。另有一个细节命令匹配是“前缀匹配”的allow里的npm run lint不会放行npm run lint:fix所以尽量把规则写具体一点。如果不确定就保持默认等它每次询问的时候自己决定。4.4 桌面版、VSCode插件、IDEA插件怎么配合Maven项目opencode不是只有终端版。官方还提供了Desktop桌面版以及VSCode和JetBrainsIDEA插件。我自己用得最多的是VSCode插件安装后左侧能看到opencode面板可以浏览会话记录、把当前打开的代码文件作为上下文发送给Agent。它的好处是能让Agent“看到”你正在看的文件省得每次都要写一大堆自然语言描述。JetBrains全家桶也有对应插件。很多Java开发者在IDEA里跑opencode时会遇到“mvn配置”的困惑——这大概是热词“opencode mvn配置”的由来。我的经验是opencode本身不负责编译它只会去读pom.xml来理解项目结构。要让它能顺畅执行mvn test这类命令你得确保IDEA的Terminal环境能识别mvn命令。具体操作是在IDEA里进入 Settings - Build Tools - Maven确认Maven home path配置正确在系统的shell配置里比如~/.zshrc或Windows的环境变量设置好MAVEN_HOME和JAVA_HOME重开Terminal先手动执行一下mvn -v确认没问题再启动opencode桌面版我把它当成“图形化的会话管理器”来用。它适合不习惯纯终端的人也方便你翻历史会话、对比不同模型的输出。因为桌面版和CLI共享一套配置文件你在哪边改的Skills和Memory另一边也同样生效。5. 实战演练用opencode接手一个陌生项目5.1 第一步先让Agent读懂代码库别急着改代码很多人拿到opencode第一件事就是让它“改个样式”“修个bug”结果它理解错上下文一通乱改。正确姿势是先做代码库梳理。我最近接了一个维护了三年的ReactExpress旧项目操作思路很明确。在项目根目录启动opencode之后我给的第一个指令是先不要修改任何代码。通读项目根目录和src目录的文件结构分析技术栈、主要依赖、前后端数据流、启动方式输出一份项目概览。它还真的列了份结构清晰的总结包括用了哪些状态管理库、哪几个路由模块、后端怎么组织和数据库交互、测试文件放在哪。接着我又问了一句把这份概览写到 docs/project-overview.md并且把三个最重要的入口文件标记出来解释新手应该从哪开始读。这一步做完我已经能通过它输出的文档快速感知项目全貌。这种“先分析、后动手”的顺序价值很大能让Agent对代码库建立全局认知后面你让它改代码时它犯低级错误的概率小很多。5.2 前端bug定位opencode Playwright怎么测出真实问题前端bug是另一个高频场景。很多测试人员给AI工具提一句“页面白屏了”工具根本无从下手因为缺真实的浏览器环境。opencode配合Playwright可以解决这个问题让Agent自动打开页面、抓console错误、截图定位。我在一个ViteReact项目里遇到登录页样式错乱的问题对话大致是这样的用Playwright打开 http://localhost:5173/login - 等页面加载3秒 - 监听console和pageerror事件打印所有报错 - 截两张图一张正常视图一张全页截图 - 把截图和报错信息保存到 scripts/repro 目录下 - 根据报错定位到具体组件文件Agent先是问了一下Playwright是否安装确认没有之后自己执行了npm i -D playwright并安装了Chromium浏览器然后生成了一个临时复现脚本scripts/repro.mjs。脚本长这样import { chromium } from playwright; const browser await chromium.launch(); const page await browser.newPage(); page.on(console, (msg) { console.log([console], msg.type(), msg.text()); }); page.on(pageerror, (err) { console.log([pageerror], err.message); }); await page.goto(http://localhost:5173/login, { waitUntil: networkidle }); await page.waitForTimeout(2000); await page.screenshot({ path: scripts/repro/login.png, fullPage: true }); await browser.close();运行之后它立刻抓到了几条核心报错指向了某个组件里错误的CSS变量引用。接下来我让它顺着报错去改代码它先把相关组件文件打开阅读再修复样式引用最后重新跑了一遍复现脚本确认没有报错。整个过程从对话开始到fix完成大概10分钟比我人工排查快得多。这里有个关键提醒opencode本身不会自动帮你启动dev server。你得保证前端项目在后台处于运行状态否则Playwright会打开一个空页面。如果项目端口冲突Agent会报错这时你最好在指令里带上“先检查5173端口是否被占用被占用就换成5174”这类条件减少来回沟通。5.3 复盘这套工作流值不值得用用下来我认为opencodePlaywright的组合在下面这些场景最值页面报错但终端没输出需要真实浏览器还原现场表单交互、登录流程、路由跳转这类有时序依赖的前端问题需要同时看console报错和页面截图的定位问题它不太适合做大规模视觉回归测试那应该交给专门的自动化测试框架定期跑。opencode的定位还是“帮你快速找到问题在哪”而不是替代整套测试基建。6. 常见问题速查表你八成会遇到的坑6.1 高频问题与解决方案报错/现象常见原因解决方案无法将“opencode”项识别为 cmdlet、函数、脚本文件...npm全局目录不在PATH执行npm prefix -g把输出路径加入系统PATH重开终端opencode error: unexpected server error. check server logs模型服务端拒绝请求或网络异常检查API Key是否有效、额度是否用完、目标模型服务是否正常hy3-free下线了吗 / 免费端点失效社区免费端点不稳定经常下线换OpenRouter免费档或本地Ollama别依赖单一免费端点命令一直卡住Agent半天不响应模型请求超时或上下文过长切换更快的模型或清理对话开新会话中文乱码TUI在部分Windows终端下字体不支持换Windows Terminal或用VSCode终端运行权限问题 EACCESnpm全局安装无权限不要用sudo硬装配置npm全局目录到用户目录或改用HomebrewMemory里的旧信息误导Agent记忆过期未清理定期Review memory文件删掉失效内容不确定模型是否被正确加载配置写错或缓存没刷新在TUI里执行/models查看当前会话真实使用的模型6.2 几条实战心得根据我踩过的坑有以下几条建议送给想长期使用opencode的朋友。第一会话别太贪心。每次对话尽量只聚焦一个任务比如“修复登录页的样式”而不是“顺便重构整个表单组件并补上测试”。任务范围越大Agent越容易丢失重点也会消耗大量token。如果确实有大改动拆成几个短会话每个会话前先把目标和约束说清楚。第二API Key权限最小化。不要滥用一个满权限的Key跑所有行为操作。尤其是接OpenRouter或社区端点时尽量用独立的Key并且留意调用量。我在刚开始接入时因为Key写进了项目配置差点提交到远程仓库后来直接把所有Key统一交给CC Switch管理配置文件里只留$ENV占位符。第三善用.gitignore。项目级的.opencode/目录下可能包含Memory、Skills、临时脚本。如果里面有不想公开的东西务必加入.gitignore。像opencode.json这种带api_key的配置文件更不能随手提交。第四从最小配置开始。不要第一次就企图配好所有provider、所有权限、所有Skill。先用一个模型跑通一个简单任务再逐步加配置。不然出了问题你根本不知道是模型问题、配置问题还是权限问题。第五多看官方changelog。opencode迭代速度很快热词里的“opencode 2.0”已经是相对成熟的版本但新版本仍然会调整配置字段和插件接口。我见过有人参考三个月前的教程配新版本怎么都跑不通最后查changelog才发现字段已经改名了。我在实际使用中最明显的感受是opencode的“模型无关 Skills Memory”组合确实改变了我的工作方式。以前每次开新会话都要重复向AI解释项目的技术栈和业务逻辑现在这些都被写进了Memory我只需要说“修一下用户列表的排序”它能自己找到接口、定位组件、跑测试验证。回过头来想与其纠结哪个Agent的模型更强不如想清楚自己需要的是什么样的工作流。对一个经常要切换项目、切换模型、甚至偶尔要用免费模型跑任务的人来说opencode的开放生态比单点能力更有价值。最后分享一个小技巧新建项目时先花十分钟给opencode创建一份项目级memory和两三个基础Skill后面所有会话都会受益这十分钟是投入产出比最高的一笔投资。