干这行久了工具换了一茬又一茬但真正能让我从“写代码”变成“审代码”的opencode算是头一个。如果你最近在关注AI编程助手大概率已经刷到过这个名字——SST团队开源的终端AI代理2.0重写之后直接用Go干掉了原来那套Node.js运行时启动速度、内存占用、长任务的稳定性都上了一个台阶。它跟Claude Code、Codex这类Agent最大的区别在于opencode不锁定某一家模型你可以自由接入Anthropic、OpenAI、Ollama本地模型甚至社区提供的各种兼容端点它还自带一套client/server架构TUI界面能看进度、能改计划、能直接编辑文件。这篇文章不打算写官方README的翻译版。我会从安装到配置、从TUI实操到IDE集成、从Skills到Memory把我这几个月在真实项目里用opencode的完整经验梳理出来。包括Windows上那个恶名昭彰的“无法将opencode项识别为cmdlet”报错怎么治、怎么用免费/本地模型跑起来、ccswitch跟它怎么配合、如何让opencode自己用Playwright去测前端bug。内容偏干建议收藏后照着一步步操作。1. opencode到底是什么搞清楚定位再动手1.1 它与Claude Code、Codex、Cursor的本质差异先说清楚opencode在AI编程工具谱系里的位置。它属于终端Agent而不是IDE插件或编辑器内核。终端Agent的特点就是它不依赖某一个IDE在命令行启动后可以自己读取代码库、自己执行命令、自己编辑文件、自己运行测试。跟Claude Code比opencode最大的优势是模型无关跟Codex比opencode完全不限制你用什么模型跟Cursor比opencode更轻、更自动化适合跑长任务而不是手动选代码块补全。我用一张表来对比目前主流几个工具的实际差异维度opencodeClaude CodeCodex CLICursor运行形态终端TUI Server终端TUI终端CLI桌面IDE模型绑定任意模型/多Provider主要绑定AnthropicOpenAI系列多种但以自家为主开源是MIT否否否长任务稳定性强Go守护进程中中中自定义Skills支持目录配置支持弱部分多项目管理有全局配置项目配置有较弱有上手门槛中等中等低最低所以我的判断是如果你手里有可用的模型API key又习惯在终端里工作opencode值得重度使用如果你只想要一个开箱即用的编辑器那就继续用Cursor也不冲突。1.2 2.0重写的核心变化为什么Go版本值得升级opencode 2.0不是小版本改动等于把整个内核都换了。最早的opencode基于Node.js装上之后会拉起一个大的运行时内存占用动辄上GB。2.0用Go重写后CLI本体是一个静态编译的二进制文件启动时间从秒级降到毫秒级长任务跑起来也不会因为Node进程的内存泄漏越来越卡。另外2.0引入了真正的client/server模式。CLI是客户端后台有一个常驻的opencode server进程负责跟模型API通信、管理会话状态、执行工具调用。这意味着你可以同时开多个终端窗口连同一个server也能在这个server之上构建自己的辅助工具。TUI界面比以前流畅很多输出是流式渲染的滚动和搜索都不卡顿。还有一个很实用的改进断点续跑。以前任务跑到一半网络断了整个对话就废了现在server端的session是持久化的重开TUI可以接着上次的上下文继续。有一点你需要注意网上的教程很多还停留在1.x时代opencode.json的结构和CLI参数在2.0里有调整。比如1.x是用opencode serve2.0变成opencode server配置字段的命名也统一了。所以我建议你装就直接装最新稳定版不要看老教程去降级。2. 安装与环境准备先跨过那些坑2.1 不同系统安装方式与升级方法opencode的安装方式很多官方支持curl脚本、npm、Homebrew、Go install、Docker、二进制包。我实际用下来不同系统有不同的推荐方案macOS / Linux# 方式一官方脚本最省事 curl -fsSL https://opencode.ai/install | bash # 方式二Homebrew brew install opencode-ai # 方式三Go install如果你已经装了Go go install github.com/sst/opencodelatestWindowsWindows有两个思路。一是用npm安装二是直接下载二进制zip包解压。npm方式要求你机器上有Node.js环境注意已经装过的老版本opencode就是npm包安装命令是npm install -g opencode-ai新版本依然保留了npm发布渠道但内部已经是Go二进制了npm install -g opencode-ai装完之后验证opencode --version升级也很简单脚本安装的重新跑一次原命令npm装的重新install一次全局包就行。Go install方式升级就是重新go install同一个路径它会拉到最新版本。2.2 Windows报错的真正解法cmdlet识别不了搜索热词里有这么一条很典型“opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名”。这个报错本质上是可执行文件不在PATH环境变量里或者你安装了但没重开终端。不是opencode特有的任何命令行工具都可能遇到。我的排查顺序是这样的先确认安装位置。npm全局包的默认目录通常是C:\Users\你的用户名\AppData\Roaming\npm如果是go install方式则默认在C:\Users\你的用户名\go\bin。在PowerShell里手动执行完整路径比如C:\Users\你的用户名\AppData\Roaming\npm\opencode.exe --version。如果这样能运行说明二进制没坏就是PATH问题。把对应目录加进系统PATH按Win R输入sysdm.cpl切到“高级→环境变量”在“用户变量”的Path里新增那条路径点确定后重开PowerShell。如果重开还不行用where.exe opencode看一下系统到底找到了什么大概率会显示找不到那就说明还是Path没生效。提示Windows上千万不要用set PATH...这种命令临时设置完就完事重启终端就失效了。正确做法一定是在系统环境变量面板里改改完重启PowerShell或Windows Terminal。还有一类情况VSCode的内置终端不认但Windows Terminal可以。这是因为VSCode终端继承的环境变量来自它启动时的进程环境VSCode需要完全重启不是重开窗口是彻底退出再启动才能拿到新的PATH。类似的教训还有JetBrains系的IDE改完环境变量必须重启IDE。2.3 全局配置目录和第一个初始化动作装好之后先别急着用。opencode的配置体系分两层全局配置和项目配置。全局配置目录在~/.config/opencode/Windows在C:\Users\你的用户名\.config\opencode\里面主要放opencode.json全局配置和日志文件。项目配置是项目根目录下的opencode.json可以单独控制这个项目用哪些provider、哪些模型、系统提示词等。首次运行建议先执行一次opencode auth login它会让你选模型提供商然后引导你填入API Key。如果暂时没有key可以跳过后面用配置文件的方式接入provider。运行完opencode auth login之后你会在全局配置目录里看到credentials相关文件provider的密钥会安全存放并不会被明文打印出来。3. 模型接入与配置从官方API到免费本地模型3.1 Provider体系说明为什么说opencode不锁模型opencode把“模型能力”抽象成一层统一的Provider接口。你在配置里只需要声明provider、model然后用环境变量或配置文件提供API密钥和端点地址。它的Provider实现很广官方内置了Anthropic、OpenAI、Ollama也支持很多兼容接口的第三方服务。最妙的是opencode支持你自定义provider的baseURL这意味着任何兼容OpenAI或Anthropic协议的服务都能被当成一个普通Provider接入。这是它跟“绑定模型”的工具最大的不同。你有几个实际选择官方API直接用Anthropic Claude、OpenAI GPT。稳定账单看得见。本地模型通过Ollama跑Qwen、Llama、DeepSeek等开源模型完全免费数据不出本机。第三方兼容端点社区或云厂商提供的兼容接口接入方式就是填一个baseURL和key。我日常的主力配置是简单任务用快速的模型复杂重构和长任务用更强的模型。opencode可以在同一个会话里通过/models命令切换这种灵活性用起来很舒服。3.2 接入Ollama实现本地免费模型如果你既想体验opencode又不想花钱Ollama是目前最顺滑的免费方案。先装好Ollama然后拉一个代码能力还不错的模型比如Qwen2.5 Coder系列或Llama 3.1ollama pull qwen2.5-coder:14b ollama serve然后在项目根目录或全局配置的opencode.json里声明Ollama provider{ $schema: https://opencode.ai/schema.json, provider: { ollama: { models: { qwen2.5-coder:14b: { name: qwen-coder-14b } } } }, model: ollama/qwen2.5-coder:14b }注意这里的model字段格式是provider_id/model_id。opencode会自动识别Ollama的本地API地址默认http://localhost:11434/v1所以如果没有改端口连baseURL都不用写。提示本地模型跑opencode建议选14B以上的参数规模7B模型在理解大代码库时经常答非所问。另外Ollama的并行请求默认是1如果你想让opencode同时跑多个工具调用可以在Ollama里开启OLLAMA_NUM_PARALLEL环境变量但显存不高的话不建议开容易OOM。3.3 用ccswitch管理多个服务商配置ccswitch全称大概是Claude Code Switch这个工具最初是给Claude Code管理多套provider配置的因为很多人会同时用不止一家的API端点。opencode本身不依赖ccswitch但如果你和我一样同时用Claude Code和opencodeccswitch可以帮你统一管理API端点和密钥避免在两个工具里重复维护同样的信息。实操上我会在ccswitch里配置好不同的“提供商档案”每个档案写明baseURL、API key、模型列表。然后用它一键切换到某套配置再在opencode里通过环境变量继承对应的配置。比如ccswitch切换后会在你的shell环境里注入某些环境变量opencode的provider配置可以直接引用这些变量{ provider: { my-provider: { npm: ai-sdk/openai-compatible, options: { baseURL: ${CC_SWITCH_BASE_URL}, apiKey: ${CC_SWITCH_API_KEY} }, models: { my-model: { name: My Model } } } } }这样做的价值是你在ccswitch里改了端点配置opencode下次启动自动用新配置不用手动改文件。特别是你有多个项目、多个环境的时候这套组合拳能让“换模型”变成一条命令的事。3.4 常见配置错误与日志排查实战很多人在跑opencode时遇到“error: unexpected server error. check server logs”这个报错太笼统了根本没有指向性。我的经验是先分两类排查第一类网络/API网关错误。检查你填的baseURL是否正确或者端点是否无法连通。curl一下你的端点地址看返回什么。如果端点没问题再确认API key是否有效、额度是否够用。第二类opencode server本身报错。查看server日志。日志位置在全局配置目录下通常~/.config/opencode/log/里面。你直接打开最新的日志文件搜error比在终端等一个笼统报错靠谱多了。有一次我遇到“unexpected server error”是因为models字段里写错了模型名provider返回404但opencode没有把原始错误透传出来日志里才找到真正的报错是model not found。注意改完opencode.json后一定要重启opencode进程或者执行TUI里的/config让配置重新加载。有几次我改了模型配置发现还在用旧模型就是因为忘了重载。4. 项目实战让opencode真正接手开发任务4.1 项目初始化和AGENTS.md的魔力想让opencode在项目里干得好第一步不是直接开对话而是把“上下文”准备好。opencode会读取项目根目录下的AGENTS.md作为全局指令文件你可以在这个文件里写清楚项目的架构、技术栈、代码规范、常用命令、目录结构等。这相当于你入职第一天拿到的手册agent读完之后对你的代码库就有基本认知。我的AGENTS.md一般是这么组织的# 项目概览 这是一个前后端分离的电商后台前端Vue3 Vite后端Go Gin数据库MySQL。 # 常用命令 - 启动前端: pnpm dev - 运行后端: go run main.go - 跑全量测试: pnpm test go test ./... # 代码规范 - 组件文件用PascalCase命名 - API路由统一挂在/api/v1下 - 后端错误处理必须返回统一JSON结构 # 架构约束 - 新增数据库表必须通过gorm migration脚本禁止手动改库 - 所有外部请求必须经过service层不允许在handler里直接查库有了这玩意儿opencode生成的代码明显更贴项目风格而不是泛泛的通用建议。我建议项目里至少写10行AGENTS.md越具体越有效。4.2 用CLI模式跑一个非交互任务除了TUI交互模式opencode还支持直接跑一次性任务。这个非常适合在CI里用或者你在终端里临时想让它做点事opencode run 给登录接口加上IP限流每IP每分钟最多30次返回429时错误码设为RATE_LIMITEDopencode会在这个模式下自动读取代码库、定位登录接口、修改代码、跑测试直到任务完成为止。run模式默认不会停下来问你问题它会自己根据情况决策。如果你希望它执行关键操作前先确认可以加--dangerously-bypass-approvals的反向参数或者配置权限级别。默认情况下opencode对写操作会有提示但你可以设置全自动。我在CI里会配合超时和--agent参数使用比如opencode run --agent build 执行构建流程修复所有报错最后输出构建产物4.3 TUI交互实操计划、会话、权限与快捷键进入TUI是直接输入opencode不带子命令。TUI界面左侧是会话和文件列表中间的输入框支持Markdown、代码块、/命令。下面说几个我高频使用的操作斜杠命令是效率关键。输入/会弹出命令菜单其中/models切换模型/sessions回到会话列表/new开新会话/config重载配置/share生成分享链接/context查看当前上下文用了哪些文件。你还可以自己定义slash commands放在.opencode/command/目录下比如我建了一个/review命令让它以资深审查者的视角读代码并挑问题。权限控制要设置好。TUI顶部能看到权限模式。默认每次写文件或执行命令都会弹确认安全但效率低。我平时会切到“edit权限”让它直接改文件、但执行命令仍需要确认等到我完全信任它的场景比如跑一个纯代码格式化再切“full access”。快捷键方面CtrlL清屏、Esc中断当前回复、CtrlN新会话这几个最常用。opencode的流式输出里代码块和普通文本是不同的渲染块滚动复制都不卡。4.4 接手老项目时的推荐工作流opencode接老项目比接新项目更容易踩坑因为老项目有历史包袱遗留的构建脚本、奇怪的依赖、不完整的文档。我总结了一套我自己验证过的工作流先读后写第一轮对话不要直接让它改代码。先让它“通读项目结构分析技术栈总结模块划分指出可能的坑”。确认边界明确告诉它哪些目录不要动哪些文件是生成的不许改。用AGENTS.md或对话里的约束都行。小步提交让它每次只改一个模块每步完成后你本地跑一下验证。别让它一次性改十个文件出了问题你连回滚都不知道从哪开始。让代码说话如果它说“我修好了xxx”请让它“运行相关测试并贴出结果”只看它说的结论没用要看测试输出。有一次我接一个维护了四年的老后端服务opencode通过分析日志文件和代码调用链帮我定位到一个慢查询的根因——不是SQL本身慢而是N1查询在循环里被触发了几百次。它给出的修复方案还附带了一条回归测试建议。这种项目如果你不让它先做通读它根本不知道去查循环里的查询一上来就改几乎必翻车。5. Skills与Memory让Agent越用越懂你的代码库5.1 Skills是什么跟自己写Prompt有什么区别opencode的Skills机制类似于其他Agent生态里的“技能包”本质是一组预定义的指令示例放在项目或全局的.opencode/skills/目录下。一个Skill就是一个文件夹或者一个Markdown文件内容告诉模型“在什么场景下按照什么步骤以什么格式输出”。跟你在对话里写Prompt的区别在于Skill可以被复用、被共享、被动触发。你可以给团队里所有人都装上同一套Skill保证他们用opencode干活时的输出风格和质量是一致的也可以让它根据任务自动匹配相关Skill。比如我写了一个“TypeScript类型安全审查”的Skill凡是交给opencode修改TS代码的任务它都会自动应用那套审查规范。5.2 用Memory维护长期上下文和项目要点Memory机制解决的是“Agent没有记忆”的问题。opencode会读取MEMORY.md或.opencode/memory.md作为长期记忆文件。你可以随时让它在学习到重要信息后更新这个文件比如某个模块的架构决策、某个命令的坑、某段代码为什么这么写。我的习惯是每次让opencode做完一个复杂任务后追加一句“你这次学到了什么值得沉淀的结论”把它写进Memory。这样下次新会话它不用重新摸索看一眼Memory就明白项目的隐性知识。比如我有个项目里有个自定义脚手架工具不是常规的Vite每次新人接手都不知道怎么启动。我让opencode把“启动开发服务器的正确命令是pnpm scaffold dev不是pnpm dev”写进Memory之后它再也不会拿错误的命令去跑项目。5.3 示例一个后端CRUD接口的Skill文件我直接贴一个我实际在用的Skill看这个就懂Skills怎么写了。在.opencode/skills/create-crud-md目录下建SKILL.md--- name: create-crud-endpoint description: 当用户需要新增一个标准CRUD接口时自动使用本技能 --- 实现一个标准CRUD接口时必须遵循以下步骤 1. 在handler层定义5个方法Create、Get、List、Update、Delete。 2. 每个方法必须校验请求参数并返回统一JSON格式 {code: 0, data: ..., msg: ok} 3. 错误场景返回非0的codemsg必须是人可读的英文描述。 4. service层负责业务逻辑禁止在handler里直接写业务。 5. 新增接口后必须在docs/api.md里补充API文档。 6. 注意List接口必须支持分页参数page和page_size默认值1和20。当用户说“给订单模块加个CRUD”opencode就会翻出这个Skill按照里面的规范生成代码。如果没有Skill它可能生成一套完全不同的风格然后你还得手动改半天。5.4 团队共享Skills的两个落地心得一个是把Skills目录提交到Git仓库用Git权限控制谁可以改。二是不要贪多每个Skill都要精简避免写成一堆正确但没有操作性的废话。我见过有人把“代码规范”写了200行模型每次都被误导去改不该改的地方。Skills的价值在于给模型一个清晰的决策框架而不是把它绑死。6. IDE集成与工具生态VSCode、JetBrains、Playwright实测6.1 VSCode插件断点调试和可视化文件变更opencode官方VSCode插件大概是最成熟的IDE集成方式。装好插件后你可以在VSCode里直接推荐一个侧边栏面板把opencode的会话界面嵌进去。这个面板的功能比终端里更直观它能显示文件变更的diff你可以在面板里直接接受或拒绝修改能显示当前正在执行的命令和工具调用还能对代码文件做断点调试。我实测的一个典型场景是在VSCode里选中一段代码让opencode“分析这段代码的问题”它的回复可以直接插入到编辑器旁边的panel点击“应用到文件”就自动改了当前文件。这个流程比切到终端再复制粘贴舒服太多。而且插件的“文件变更”面板会列出所有被修改的文件和具体diff你可以在合并之前逐条审查安全感拉满。6.2 JetBrains IDEA插件使用注意JetBrains的opencode插件起步比VSCode晚一些但现在IDEA里也能用。安装后在“Sidecar”窗口里打开功能和VSCode版本类似。我实际用下来的经验是IDEA插件对Maven/Gradle项目的操作比VSCode版本更顺手因为IDEA内置了对Java构建链路的深刻理解。opencode在IDEA里跑Maven测试时插件能直接从IDE的build output里parse信息报错定位更准确。你搜到的“opencode mvn配置”大概率就是设置Maven的JVM参数和工作目录让opencode能正确触发构建。我在IDEA里遇到的一个坑是插件默认会用系统JDK跑Maven如果你的项目要求JDK17但系统默认JDK是11./mvnw就会报错。解决方式是让opencode直接用项目内的Maven Wrapper而不是系统mvn并且通过环境变量JAVA_HOME指向项目需要的JDK路径。6.3 通过Playwright MCP让opencode自己测试前端Bug这个是我近几个月觉得最值的一个玩法。opencode支持MCP服务器接入MCP是模型上下文协议相当于给Agent外挂“工具”。Playwright官方提供了一个MCP服务器装上之后opencode就能获得浏览器控制能力打开页面、点击按钮、填表单、截图、查看控制台报错。安装和配置流程在你的opencode配置里添加Playwright这个MCP server{ mcp: { playwright: { type: local, command: [npx, playwright/mcplatest], enabled: true } } }重启opencode让它加载新的MCP工具列表。给opencode一个前端bug描述比如“登录按钮点击没反应打开浏览器复现一下”。opencode会自动调用Playwright MCP启动一个Chromium实例访问本地开发服务器把页面上控制台的报错抓出来分析是JS错误还是接口问题。我在一个Vue项目里用这个方式让opencode定位了一个只在移动端出现的样式闪烁问题。它打开浏览器设备模拟器截图后发现是某个CSS动画触发了重排它直接给出了修复代码并验证通过。注意MCP里command数组的写法在不同opencode版本有细微差别新版要求用数组老版本有的接受字符串。如果你的配置加载失败优先检查这里。6.4 桌面版与纯CLI的取舍opencode现在也出了桌面版客户端。桌面版本质上是一个封装好的图形界面底层还是跑CLI和server。它的优势是安装更傻瓜、自带配置界面、不用记命令。但我的建议是桌面版适合体验重度工作还是回终端。因为终端里你能同时开多个会话、用tmux管理、配合其他shell工具做管道操作这些在桌面版里折腾不出来。桌面版未来如果能把多会话管理和配置可视化做得更完善倒是值得切换。7. 常见问题速查我踩过的坑和排查实录7.1 问题对照表报错/现象常见原因解决方法“无法将opencode识别为cmdlet、函数、脚本文件或可运行程序的名称”PATH没有包含opencode安装目录或环境变量未刷新把安装目录加进用户PATH完全重启终端/IDE“error: unexpected server error. check server logs”provider配置、模型名错误或网络端点不通查看~/.config/opencode/log/日志用curl验证端点模型输出很慢或一直转圈本地模型显存不足或并行度太低换更小模型或降低并发Ollama可调OLLAMA_NUM_PARALLEL明明改了配置还在用老模型配置未重载TUI里执行/config或重启opencode执行命令权限太烦权限模式设置太保守切换权限级别从“确认所有命令”改为“确认危险命令”会话丢失/重启后历史没了server没有正常持久化session检查server进程是否被杀2.0一般会自动恢复sessionMCP工具不显示配置格式错误或MCP server没起来先单独运行MCP command确认能启动再配置7.2 免费模型服务下线的应对思路很多人用第三方或社区免费模型时最怕的事情就是服务突然下线。opencode社区里那些“hy3-free”之类的免费模型端点说实话都不够稳定。如果你依赖某个免费端点跑了重要任务遇到宕机一定要有Plan B。我的应对策略是“本地优先”免费端点倒掉时立刻切到Ollama本地模型虽然能力弱一些但至少不会中断任务。等到官方API或稳定端点恢复再切回来。另外不要把所有项目都绑在一个免费端点上至少要留一条“能跑”的本地路径。我自己就把Ollama当兜底无论用哪家端点Ollama始终装着。7.3 任务跑到一半卡死的处理技巧opencode跑长任务时偶尔会卡在“等待模型响应”的状态。我的处理套路是先看TUI左下角的状态如果显示“running”但迟迟没有新输出可以按Esc中断当前token流然后发送一个轻量消息比如“continue”让它恢复如果彻底没反应再开一个新终端连到同一个server查看进程状态。实在不行就pkill opencode然后重开。由于session是持久化的重新启动之后还能接上之前的上下文。这个体验比Claude Code断线丢会话强很多也是我日常主力用它的一个重要原因。7.4 一次真实的“接手项目”排错实录最后分享一个我真实的项目接手过程这能帮你理解完整的工作流。上个月我接手了一个内部数据平台后端Python FastAPI前端React。第一件事我不是直接看代码而是在AGENTS.md里写下“启动后端用uvicorn app.main:app --reload前端用pnpm dev测试框架用pytest”。然后给了opencode一个任务“梳理这个平台的登录认证流程画出数据流向找出安全隐患”。它先读了认证模块的代码发现token校验逻辑分散在三个文件里而且JWT secret硬编码在配置文件中。它建议把secret迁移到环境变量并统一token校验中间件。后来我让它直接改它先是修改了配置读取逻辑然后更新了认证模块最后跑了一遍pytest——其中两个测试因为新逻辑不兼容报错了它自己看完报错又修了测试断言。整个流程我只在中途做了一次代码review其余时间都是它在跑。这个体验让我相信opencode真的可以当半个正式开发用关键是把上下文和信息铺到位。我个人在实际操作中的体会是opencode最舒服的地方不是它“一次性写对”而是它敢上手、能迭代。它在改代码的过程中会自己发现问题、自己修问题这个闭环能力比很多“一次性生成”的工具强太多。如果你也准备入坑建议第一周先拿小项目练手把AGENTS.md、Skills和权限模式这套工作流跑顺再放到核心业务上。慢慢你会发现你花在“改AI生成的错误代码”上的时间其实比“自己从零写”还是要少的前提是——你把上下文喂得好把边界划得清。