1. 环境准备与安装1.1 opencode到底是个什么工具先交代清楚opencode不是某个大厂出的商业IDE也不是什么闭源收费插件。它是一款开源终端AI编程代理AI Coding Agent由做Serverless框架Ion前SST的团队开源维护核心代码用Go写成所以它的安装包是一个体积不大、启动很快的独立二进制。它做的事情和Claude Code、Codex CLI这类工具很像你在终端里启动它它会读取你当前项目的文件结构、git变更、目录里的说明文档然后根据你的指令自动完成阅读代码、修改文件、执行命令、跑测试、提交代码这一整套开发动作。区别在于opencode的选择更开放——你不一定非要用Anthropic的模型OpenAI、Gemini、Ollama本地模型、各种兼容OpenAI协议的第三方服务都能接自由度比Claude Code高不少。这个工具适合谁适合这几类人一是已经在用Claude Code/Codex CLI但对模型供应商锁定感到不爽的人二是希望把AI编程助手彻底纳入自己工作流、愿意花半小时读配置文件的人三是想用本地模型跑编码助手、不想把代码内容传给云端API的隐私敏感用户。它不适合完全零基础的小白因为至少你得会开终端、懂一点JSON配置否则第一步就会卡住。1.2 官方支持的三种安装方式opencode的安装路径很多我实际用下来体验比较好的有三个第一种macOS用户直接走Homebrewbrew install sst/tap/opencode这一条命令装完就能直接用后续升级也方便brew upgrade opencode即可。第二种通用安装脚本适合Linux和Windows的Git Bash环境curl -fsSL https://opencode.ai/install | bash这个脚本会把二进制放到~/.opencode/bin下并在shell配置里追加PATH。如果你用的是zsh它一般会自动写进~/.zshrc用bash就写进~/.bashrc。第三种如果你本机有Go环境也可以直接用go命令安装go install github.com/sst/opencodelatest这种方式的好处是版本跟着源码仓库走适合想体验最新commit的玩家。缺点是你得有Go工具链而且GOBIN要配进PATH才能直接敲opencode命令。Windows用户如果不想折腾脚本最稳妥的办法是去GitHub Releases页面手动下载Windows平台的压缩包解压后把exe文件放到一个固定目录然后把这个目录加进系统环境变量Path。官方文档还提到可以用Scoop安装但我个人觉得手动下载反而更直观至少你能清楚知道自己把东西装到哪了。安装完成后终端执行opencode --version验证一下能打印版本号就说明装好了。注意opencode的终端界面依赖Node.js的一些能力新版已经做了自包含处理但如果你的TUI界面异常先检查是不是Node版本过旧建议Node 20以上。1.3 Windows下“无法将opencode识别为cmdlet”的经典坑这个报错是Windows用户安装任何命令行工具都会遇到的老问题搜索热度居高不下它长这样opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。翻译成大白话就是你在当前终端窗口里敲了一个命令但Windows根本不知道这个命令对应的程序文件在哪里。95%的情况是安装完成后没有重新打开终端或者安装脚本写入的PATH没有生效。处理方法按优先级排列关掉当前终端窗口重新开一个新的。手动确认安装位置。如果是curl脚本装的检查%USERPROFILE%\.opencode\bin或%LOCALAPPDATA%\opencode\bin下有没有opencode.exe。如果文件存在但命令还是找不到打开系统设置里的“编辑环境变量”把二进制所在目录手动加进用户变量Path。实在搞不定就退化到最笨的方法——每次敲完整路径比如C:\Users\你的名字\.opencode\bin\opencode.exe。我还见过一种情况终端里opencode能启动但VSCode内置终端里识别不到。这通常是因为VSCode是在环境变量修改之前启动的它继承的是旧的环境变量。解决办法是彻底退出VSCode再重新打开别只关窗口要在任务管理器里确认进程退出。2. 模型接入与配置文件解析2.1 全局配置文件opencode.json要放在哪opencode的配置继承关系清晰全局配置放用户目录项目配置放项目根目录项目配置会覆盖全局配置的同名字段。全局配置路径macOS/Linux~/.config/opencode/opencode.jsonWindows%USERPROFILE%\.config\opencode\opencode.json如果目录不存在就手动建。首次运行opencode后它也会自动生成一个默认配置文件里面主要是空的provider和model字段。强烈建议在配置文件第一行加上$schema声明这样在VSCode或JetBrains里编辑JSON时会有完整的字段提示和校验{ $schema: https://opencode.ai/config.json, provider: {}, model: }add一下这个schema声明不是可选项是让你少踩80%配置拼写错误的救命稻草。2.2 核心Provider配置官方模型与本地模型opencode把“模型供应商”统一抽象成了provider这个概念每个provider下面可以挂多个模型。配置格式大体是{ $schema: https://opencode.ai/config.json, provider: { anthropic: { apiKey: {env:ANTHROPIC_API_KEY}, models: { claude-sonnet-4-20250514: {} } }, openai: { apiKey: {env:OPENAI_API_KEY}, models: { gpt-4o: {} } }, ollama: { models: { qwen2.5-coder:14b: {} } } }, model: claude-sonnet-4-20250514 }注意看apiKey字段的写法{env:ANTHROPIC_API_KEY}。这是opencode推荐的做法——把密钥放在环境变量里配置文件只写引用关系避免密钥泄露。不用环境变量、直接把密钥明文写在配置文件里也能跑但只要你把配置文件分享出去或者提交到git仓库密钥就等于公开了。对于本地模型Ollama是最省事的方案。先安装Ollama并拉取模型ollama pull qwen2.5-coder:14b然后在opencode的provider配置里加ollama即可本地接口默认是http://localhost:11434/v1opencode会自动识别。2.3 主模型怎么选免费模型与订阅套餐的坑很多刚接触opencode的人都会问主模型到底选什么我的经验是有多大能力办多大事。如果你有可用的Anthropic或OpenAI官方API额度直接选对应旗舰模型体验最完整尤其是复杂项目的分析能力差距明显。如果没有官方订阅现在很多第三方模型聚合服务商也提供OpenAI兼容接口操作方法很简单在provider里填上服务商给的基础地址和API key然后把模型名写成服务商文档里标注的名称。这里多说一句市面上有相当多套餐名称里带“opencode go”或者“go订阅”字样的服务本质上就是打包了多个模型的订阅套餐配置方式并不会因为你用的是套餐而改变重点是把baseURL和API key写对模型名检查清楚。至于完全免费的模型Ollama本地模型是目前最稳的选择。之前社区里流传过一批免费模型端点今天能用明天可能就下线这属于常态别把免费端点当生产依赖。我的建议是本地模型兜底付费模型干活免费端点只用来临时试一试。2.4 在Linux下用jq快速改配置在Linux服务器上改JSON配置很多人第一反应是vim但vscode远程连过去再改也不错但其实还有更高效的方式——用jq命令直接改。举个例子我想往配置文件里塞一个ollama模型jq .provider.ollama.models[qwen2.5-coder:7b] {} ~/.config/opencode/opencode.json tmp.json mv tmp.json ~/.config/opencode/opencode.json这种方式的优势在于第一不用打开编辑器第二jq会保证JSON语法正确不会手滑删一个逗号导致整个配置无法解析第三可以塞进shell脚本做自动化。如果你需要频繁换模型、加provider建议抽空学一下jq的基本语法十分钟就能上手。3. 核心玩法从TUI操作到Skills技能3.1 TUI界面基本操作在项目目录下敲opencode你会进入一个全屏终端界面左侧是会话列表右侧是对话区域底部是输入框。这和Claude Code的纯文本交互风格不太一样更像一个终端里的IM工具。常用的操作底部输入框直接敲自然语言指令输入/new开启一个全新会话清空上下文输入/models弹出模型选择列表可以随时切换不同模型输入/agents切换Agent模式build/plan等输入/compact压缩当前会话上下文会话太长时特别好用输入/undo撤销最近一次文件修改输入/help查看所有可用命令按ShiftTab在输入框和命令面板之间切换第一次用的人最容易犯的错误是——上来就让它改代码改完发现不对劲想撤销却不知道有/undo只能手动去git恢复。所以品质建议是第一件事先敲/help把命令列表过一遍。3.2 Build模式与Plan模式让AI先想后做Agent模式是opencode的一大亮点它改变了“你问一句它答一句”的被动式交互变成一个可以自主完成任务的代理。默认build模式拥有执行命令和修改文件的完整权限适合直接派活。而plan模式是只读模式它只会分析代码、给出方案不会动任何文件。我强烈建议的工作流是先用plan模式让它出方案确认无误后再切换到build模式执行。特别是接手一个不熟悉的项目时让它在plan模式下读完整个项目结构输出一份“我认为问题出在哪、应该怎么改”的分析报告你审核通过后再放权让它动手。这样既保证了方向正确也大大降低AI乱改代码的风险。切换到plan模式的方式很简单输入/agents选择plan即可。也可以在启动opencode时直接指定opencode --agent plan3.3 Skills机制把团队规范固化成技能包opencode支持Skills机制这个设计和Claude Code的Skills基本一致。简单来说你可以在固定的目录下创建一个技能文件夹里面放一个SKILL.md文件描述这个技能是用来干什么的、步骤是什么、有哪些注意事项。之后在会话中只要提到相关需求opencode就会自动加载这个技能文件并按照里面的流程执行。技能目录位置全局技能~/.config/opencode/skills/项目技能.opencode/skills/举个例子我写了一个“代码审查”技能内容大概是这样# 代码审查 当用户要求进行代码审查时按照以下步骤执行 1. 先查看当前git diff理解所有变更 2. 检查变更中是否存在明显的bug、逻辑漏洞 3. 检查是否缺少错误处理 4. 检查是否有性能隐患 5. 输出审查结论按严重程度分级列出问题放到~/.config/opencode/skills/code-review/SKILL.md后每次让它“审查一下代码”它就会自动走这个流程输出结构稳定的审查报告。社区里还有一个叫superpowers的技能集原本是给Claude Code做的包含很多高质量的编码工作流模板有人已经把它适配到了opencode上。下载之后放到skills目录里就能用。另外oh-my-claudecode也是一套配置管理脚本原本是管理Claude Code的配置和技能的现在也有人拿它统一管理opencode的配置思路是共通的。这里分享一个我的习惯技能不只写“怎么干活”还要写“不要怎么干”。比如给一个项目写“代码提交”技能时我会明确写上“不要在没有测试的情况下提交代码”、“不要修改与本次任务无关的文件”这种负面约束在实际使用中比正面描述更能保护项目安全。3.4 LSP与MCP让AI看得懂符号和网页opencode做编码代理本质是文本到文本的操作它对代码的理解是靠读文件内容而不是像IDE那样有完整的语法树和符号索引。这就导致一个问题遇到复杂的跨文件调用时它可能找不到某个函数的定义。解决这个问题的手段是接入LSPLanguage Server Protocol。LSP的接入方式是通过MCPModel Context Protocol模型上下文协议来实现的。opencode内置了MCP客户端你可以在配置文件里声明要连接哪些MCP服务器。举一个实际例子——前端项目里最常见的需求是用Playwright做浏览器自动化测试{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest] } } }配置之后你让opencode“打开浏览器复现一下这个bug”它就能通过Playwright MCP实际启动浏览器、点击页面、截图真正跑一遍前端交互流程。这个功能用在排查前端Bug上非常爽后面第五部分我详细讲实操。至于LSPopencode对LSP的支持一直处于快速迭代状态。较新版本里可以直接通过命令开启语言服务让AI获得跳转定义、查看引用等IDE能力。如果你需要处理大型Java项目比如需要读Maven依赖、类结构建议优先确认当前opencode版本对LSP的支持程度把MCP配置好再干活体验和纯文本硬啃完全不同。4. 与VSCode、JetBrains及周边生态集成4.1 VSCode插件终端和编辑器双开虽然opencode本身在终端里完全可用但在屏幕左侧开着编辑器、右侧开着终端窗口的布局总归是别扭。所以官方和社区做了VSCode插件核心价值是让会话内容显示在编辑器面板里同时保留终端的操作逻辑。在VSCode扩展市场搜opencode安装后左侧边栏会出现一个图标点击就能进入会话界面。这个插件的主要用处不是替代终端版而是让你在阅读代码的同时和AI交互上下文更连贯。我自己用下来觉得VSCode插件还有两个亮点一是可以直接选中代码片段发送给opencode省去复制粘贴二是会以diff形式展示AI对文件的具体修改审阅变更时一目了然。注意一点VSCode插件需要先安装opencode本体插件本质上是一个GUI壳底层的核心逻辑还是那个Go二进制。4.2 JetBrains IDEA插件JetBrains系的插件IntelliJ IDEA、PyCharm、WebStorm等也有对应的opencode集成。从热度词里的idea opencode插件来看Java后端开发者对这个需求不少。JetBrains插件的安装路径是Settings - Plugins搜索opencode安装即可。和VSCode插件类似JetBrains插件同样支持代码片段发送、会话管理、diff查看。但有两点体验差异一是JetBrains系IDE本身比较重插件加载时会吃一些内存如果你的IDE已经经常卡顿建议还是用终端版二是IDEA里的Maven项目结构更复杂插件目前对Maven多模块项目的上下文收集能力有限复杂场景下还是先把相关文件路径明确告诉AI更靠谱。4.3 桌面版不想碰终端的人也有出路目前已有opencode桌面版Desktop在快速迭代中。桌面版本质上把终端、配置、会话历史全部打包进了原生应用窗口对不想碰命令行的人来说友好很多界面是图形化的配置项有输入框和下拉菜单不再需要手改那个opencode.json。不过坦白说以我实际体验来看桌面版目前更适合演示和轻度使用重度开发我还是回到终端版。原因很简单终端版能够和你的git、shell脚本、测试命令无缝配合桌面版的进程独立于你当前工作目录操作边界隔了一层。等它后续版本把工作目录绑定和终端面板做完善或许能成为主入口。4.4 用配置切换工具管理多个模型订阅很多重度用户手里不止一个模型订阅可能同时有Anthropic官方API、OpenAI账号、第三方套餐。这时候手动改opencode.json来切换provider就太痛苦了。社区里流行的做法是使用cc switch这类配置管理工具。它的工作方式不复杂你用cc switch维护好所有订阅源的密钥和配置模板切换时它会自动把这些信息写入你需要的工具配置文件里包括opencode。本质上它就是帮你在多个配置模板之间做切换和同步你不需要记住每个服务商的地址和模型名怎么写。另一个方向是把opencode和cc switch结合配合opencode这套命令行本身实现快速的模型切换。opencode里面的/models也能切但那只是在已经配置好的模型列表里切而cc switch解决的是“我今天换一个完全不同的供应商”这个需求。我的建议如果你只有一个订阅源没必要上cc switch这类工具直接编辑opencode.json就行如果你手上有三四个订阅来回倒那就值得花一小时把cc switch的配置模板配好后面每一次切换都是秒级完成。5. 实战用一个opencode完整接手项目并修复一个前端Bug5.1 场景设定为了说清楚opencode在真实项目里的工作流我设计一个具体场景假设你刚加入一个团队接手了一个React Vite Express的全栈项目代码在本地仓库里团队反馈最近登录页有个Bug——提交表单后页面会白屏但有时刷新一下就恢复正常。传统做法是先看代码、找表单提交逻辑、分析状态管理、复现问题、猜测原因、改代码、再验证。这套流程从前端开发的角度看少说也要一两个小时。用opencode我能把它压缩到二十分钟以内前提是你会引导它。5.2 第一步初始化会话让AI建立项目地图在项目根目录运行opencode进入会话后第一句话不要直接说“帮我修Bug”而应该让它先建立项目认知请先浏览项目结构阅读package.json、README、入口文件整理出一份项目技术栈和目录职责说明。等它输出完追加一句把这份项目说明保存到项目根目录的 CLAUDE.md 文件中如果已有更新它。这一步的意义在于opencode虽然有上下文窗口但它每次会话的上下文都是独立的下一次启动它会重新读文件。把项目说明沉淀到CLAUDE.md或者AGENTS.md后后续每次启动会话它都会优先读取这个文件避免反复做重复认知。如果opencode启用了memory能力它还会把这些上下文沉淀到全局记忆里跨项目也能复用这功能非常实用。5.3 第二步描述Bug先让AI用Playwright复现项目背景建立之后把Bug描述给它登录页填写用户名密码后点击提交页面会白屏。复现概率不稳定刷新后有时正常。请分析可能的原因并配置一个Playwright MCP来实际复现这个问题。这里的关键点是让它用Playwright真实跑一遍而不是静态读代码猜答案。如果MCP已经配好它可以自动打开浏览器、访问本地开发服务器、填写表单、点击提交然后把白屏时的控制台报错抓回来。实际执行中它会先启动dev server然后调用Playwright MCP操作页面。你要做的就是在旁边看着必要时提供一下测试账号或者验证码。等到它把控制台错误信息抓回来Bug的原因就已经定位了80%。常见的白屏原因无非几个某个字段为undefined导致渲染崩溃、异步请求失败返回了异常数据、路由跳转后组件没挂载。控制台报错一抓基本锁死。5.4 第三步确认修复方案再执行修改得到报错信息后不要立刻让它改先要求它切换plan模式给修复方案基于抓到的报错请分析根因并列出至少两个修复方案说明各自的风险和改动范围。等它输出方案你确认后再说切换到build模式按方案A修复。修复时只改必要的文件不要顺手重构其他代码。注意我用了“只改必要的文件”这个约束。这是防止AI在修复过程中自作主张优化代码、改动无关文件的关键词。opencode在build模式下是有能力自主修改多个文件的不加约束经常会带出来一堆无关diff。修改完成后要求它运行前端的类型检查和测试确认没有引入新问题。这一步不能省。AI改代码之后自己跑测试成功率比你自己再手动跑一遍高很多——至少在自动化测试覆盖的场景里它能证明自己改对了。如果团队有git提交规范再让它完成后提交代码commit信息按团队规范写。opencode会自动执行git add和commit整个过程你只需要确认diff内容没有异常。5.5 避坑提醒接手旧项目特别要注意的三点用opencode接手开发项目这三点很容易翻车第一旧项目的依赖版本可能很老。opencode在分析时可能按最新API的语法给你提建议但这些API在你项目里根本不存在或已经被废弃。强烈建议在项目说明文件里写清楚“本项目使用React 17不是18/19”这类版本约束AI踩坑概率会明显下降。第二旧项目的测试可能本身就处于红色状态。opencode跑完测试发现失败它会试图去“修复”那些和本次任务无关的失败用例。一定要给它明确边界——“本次任务只处理登录白屏问题其他失败用例不要管”。第三商业项目里有敏感配置。确保.gitignore覆盖了.env和配置文件同时确认opencode执行命令时不会把密钥传到远程模型。用本地模型或者经过选择的云端模型处理敏感代码是严谨团队的基本配置。6. 常见问题与排查实录6.1 “unexpected server error”怎么破这个报错全文通常是error: unexpected server error. check server logs它的出现原因比较杂但按我排查的经验优先级从高到低是API key无效或已过期——去provider控制台检查key状态账户余额不足——很多订阅套餐是按量计费的余额见底时报错最典型请求体太大——opencode会把大量文件内容塞进上下文如果超出模型的最大token限制服务端会直接拒绝第三方服务商服务端临时故障——这种没办法等一等重试排查方法在opencode里输入/logs查看详细日志或者直接用curl测试一下provider的接口是否正常响应。如果是请求体过大的问题就分段让AI处理不要一次性塞给它整个项目。6.2 “this model is not available in your country”是什么情况这个报错会让人很郁闷明明配置都对了模型却不可用。它的直接含义是不同模型服务商对不同地域的访问有不同策略当前配置的模型在哪个地域范围内不可用。我这里只讲合规的处理思路检查你当前账号的归属地区确认该模型是否在你所属区域的支持列表里换个没有地域限制的模型。比如官方旗舰模型限制多那就换成同服务商下的其他模型试试本地模型永远不会有这个问题——用Ollama跑一个qwen2.5-coder彻底绕开地域概念如果你用的是第三方聚合服务可以看看同服务商是否提供其他可用的模型版本不要尝试任何违规绕过手段尊重服务商的分区策略是基本常识。你的解决方向应该是“调整模型选型”而不是“挑战服务商策略”。6.3 模型明明很强为什么改代码改得稀烂这是一个调参型问题。如果你觉得opencode的答案质量波动大先别急着怪模型检查几件事上下文是否被塞满了。会话越长模型越容易捡了芝麻丢西瓜。用/compact压缩或者果断/new开新会话有没有给它足够的参考文件路径。它再聪明也是根据读到的文件做判断你不说某个工具函数在哪它就只能猜主模型和小模型的分工是否合理。opencode支持为不同任务分配不同模型把复杂的架构分析留给旗舰模型把简单的格式化、补日志丢给便宜的小模型这是性价比最高的用法有没有在配置里设置temperature。很多情况下编码任务希望输出确定性强一点可以在模型配置里适当调低temperature6.4 运行卡顿和内存占用偏大opencode毕竟是全屏TUI应用除了Go二进制本体它还会启动Node相关的服务进程用于TUI渲染和MCP通信。在比较大的Monorepo项目里它递归扫描文件时内存占用会明显上涨。我的处理习惯是项目里维护一份.opencodeignore文件把node_modules、dist、build、.git这些大目录排除掉扫描速度和内存都能改善会话历史别攒太多定期用/new开新会话如果同时开着VSCode插件、桌面版和终端版注意内存叠加日常开发保留一个入口就行MCP服务器不要一股脑全配只保留当前任务需要的。比如改前端Bug时开Playwright做后端接口时再开数据库MCP用完就停最后分享一点个人的使用体会。opencode最打动我的不是某一个具体功能而是它把“AI编程助手”这件事真正开放了——模型可以换技能可以写MCP可以接配置完全在自己手里。用久了你会发现它不再是一个“智能问答框”而是慢慢变成了一个可以被你塑形的开发搭档。花点时间把常用的技能、项目规范、模型组合沉淀到配置文件里后面每一次会话都会越来越顺手。这个投入值。