最近这半年我的终端里一直同时躺着几个 AI 编程智能体在吃灰Claude Code 用来写复杂重构Codex CLI 偶尔接一下 OpenAI 的任务还有个叫 opencode 的命令行工具起初我以为是又一个“套壳玩具”结果在连续替换掉我日常 70% 的编码自动化工作之后我决定专门写一篇关于它的完整记录——从安装、配模型、接 IDE到让它自己开 Playwright 测前端 bug 的实战链路都捋一遍。这篇文章不是什么官方文档的中文翻译而是一个重度使用者踩坑之后的复盘笔记适合那些已经在用或者在纠结要不要用 AI Agent 写代码的人。opencode 最吸引我的点就一句话它不绑死任何一家模型谁好用、谁便宜、谁在本地跑全都可以通过配置随时切换。这和 Claude Code 那种深度绑定 Anthropic 生态的思路完全不同。下面我按照从零到一的使用顺序把整个过程拆开讲清楚。1. opencode 是个什么来头它能从 Claude Code 和 Codex 嘴里抢食的底气先说背景免得有人上来就懵。opencode 是那个做了 SST 框架的团队对就是搞 Serverless 的那帮人开源的一个 AI 编程智能体。它主要有两个形态一个是用 Go 写的命令行工具也就是大家天天在热搜里刷到的“opencode go”单文件二进制启动快得离谱另一个是基于 TypeScript/React 的桌面版叫 opencode desktop适合不爱碰终端的同学。两个形态共享同一套引擎和配置所以不是两套产品是同一个东西的两张脸。那它凭什么能从 Claude Code 和 Codex CLI 嘴里抢食我列一下我这半年用下来最真实的感受模型自由它内部通过 Vercel AI SDK 对接各家模型OpenAI 系的、Anthropic 系的、Google 系的以及国内能直接调用的 DeepSeek、智谱、Kimi甚至本地 Ollama 跑的模型都能进同一个对话界面。这一点对国内开发者极其友好因为很多时候你不想把代码发给海外 API或者就是单纯想省钱用国产模型opencode 能做到“换模型不换工作流”。开源透明CLI 本体开源配置也是文本文件你可以清楚地看到 Agent 每一步做了什么而不是一个黑盒。项目级上下文它能读目录结构、搜文件、打开具体代码行、执行命令而不是像普通 IDE 插件那样只聊当前打开的文件。Skills 和 Memory 机制这是 2.0 之后的重头戏后面专门开一节讲。简单说是你可以在项目里教 Agent 记住规定动作和长期约定让它越用越懂你的项目。来个直观对比市面上几个常见 CLI Agent 的差异大概是这样工具模型绑定程度配置自由度插件/技能机制桌面端或 IDE 支持opencode低几乎全兼容高文本配置为主有 Skills / Memory / 第三方技能包CLI、桌面端、VSCode、JetBrainsClaude Code高主要面向 Claude中有 Skills 但要折腾CLI 为主Codex CLI中偏向 OpenAI中弱一些CLI 为主其他同类 CLI Agent各不相同各有取舍多数还在抄作业不一定齐全这个表不是要分高下而是帮你看清定位opencode 属于“通吃型”工具什么模型都能接什么界面都能给核心逻辑都一致。所以网上才会有“opencode、codex、claude code 哪个 agent 好用”这种永恒争论——在我看来答案是如果你只想在一个模型生态里深耕原生工具值得用如果你想保留随时换模型的权利opencode 是更稳的底座。2. 安装与掉坑PowerShell 不认 opencode 命令时我在想什么安装这事看着简单实际是新手问得最多的环节尤其是 Windows 用户。热搜里那句“opencode : 无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名”我敢说半数以上的人都遇过包括我自己第一次装的时候也翻车了。先把几种安装方式都写清楚再说怎么排查。2.1 三种安装方式按场景选方式一官方安装脚本macOS / Linux / WSL 推荐。在一行命令里直接装curl -fsSL https://opencode.ai/install | bash脚本会把编译好的二进制放到用户目录下具体路径因版本而异装完终端里会提示你。这种方式最省心因为脚本会检测系统架构、下载对应版本、并提示你配置 PATH。方式二npm 全局安装。如果你已经有 Node.js 18 以上的环境也可以npm install -g opencode-ai注意npm 包本质上只是个下载器它会把真正的 Go 二进制拉到本地所以你装完最好确认一下 bin 目录是否在 PATH 里。方式三Go 源码安装。Go 版本 1.22 的时候可以用go install github.com/sst/opencodelatest装完二进制在$(go env GOPATH)/bin目录下一般是~/go/bin。这种方式适合那些本来就要折腾源码、或者想锁定特定版本的人。2.2 为什么 PowerShell 不认这个命令这个报错的本质就一句话当前终端进程的 PATH 环境变量里找不到 opencode 可执行文件。但深挖一层还有几个隐藏原因我逐一列一下安装目录根本没进 PATH。这是最常见的情况尤其是手动解压二进制到某个自定义目录时。安装已经完成但你在同一个终端窗口继续执行命令。PATH 修改不会实时生效必须重开终端。npm 全局安装时npm 的全局 bin 目录不在系统 PATH 里。用户 PATH 和系统 PATH 的刷新时机不同某些 IDE 内嵌终端不会继承最新的用户 PATH。排查思路也很简单先在当前终端打印 PATH 看看echo $env:Path如果发现里面没有安装目录就手动加进去。假设你的二进制被装到了%USERPROFILE%\.opencode\bin那么在 PowerShell 里执行[Environment]::SetEnvironmentVariable(Path, $env:Path ;$env:USERPROFILE\.opencode\bin, User)然后重开终端运行opencode --version能输出版本号说明装好了。npm install -g的朋友同理找到 npm 的全局目录通常是%APPDATA%\npm加到 PATH 即可。这里我得说个亲身体会在 Windows 上如果只是玩 CLI我强烈建议干脆用 WSL。不是 PowerShell 不行而是 opencode 启动后经常要调用 shell 执行命令、处理文件权限、跑测试脚本WSL 底层的进程管理和路径映射比 Windows 原生少很多莫名其妙的幺蛾子。如果你主要在 Windows 里用 IDE 插件那另说后面第四节会展开讲。提示无论哪种安装方式装完第一件事就是打开一个新终端先跑opencode --version确认环境而不是急着直接敲opencode进交互界面。2.3 另一个常见启动报错unexpected server error热搜里还有一条很具体“c:\windows\system32opencode error: unexpected server error. check server logs”。这种报错我碰到过两次第一次还以为是安装坏了后来排查半天发现是配置里写了一个不可达的 API 地址导致 CLI 启动时连不上后端服务。处理思路是这样的先确认 opencode 本身没坏跑一下opencode doctor如果有这个命令看环境诊断信息再检查你的模型配置、API Key、Base URL 是否有效最后看日志输出。opencode 一般会把日志写到本地临时目录你可以通过opencode --log-level debug启动直接看它到底卡在哪一步。这个报错的根因80% 都和第三节说的“模型接入配置”有关。3. 模型接入与 ccswitch 配合一套配置应付所有供应商opencode 的灵魂不在界面而在“模型随便换”的底层设计。这一节我重点讲怎么配置模型以及为什么网上都在说“opencode go 需要配合 ccswitch 这类工具”。3.1 直接在配置里指定模型opencode 支持两种层级的配置全局配置一般在~/.config/opencode/config.json和项目配置项目根目录下的opencode.json。项目配置优先这个设计很实用——每个仓库可以用不同的模型和命令互不污染。比如我想在项目里默认使用 DeepSeek{ $schema: https://opencode.ai/config.json, model: deepseek/deepseek-chat, provider: { deepseek: { apiKey: {env:DEEPSEEK_API_KEY}, npm: ai-sdk/deepseek } } }如果你用 Anthropic 家的模型大概是{ model: anthropic/claude-sonnet-4, provider: { anthropic: { apiKey: {env:ANTHROPIC_API_KEY} } } }因为 opencode 底层封装了很多模型供应商的 SDK不同 provider 的字段会略有差异所以最稳妥的办法是第一次配置时打开它的官方配置文档或者直接在交互界面里用/models命令查看当前可用的模型列表。3.2 免费模型和本地模型热搜里“opencode免费模型”的搜索量一直居高不下大家关心的无非就是“不想花钱能不能跑起来”。我可以负责任地说能。但你要分清两种“免费”第一种是厂商送的额度比如 Google Gemini 的免费层、部分国产模型的开发者赠送 token。这类模型接进 opencode 后日常写写小函数、解释代码、写测试用例完全够用。第二种是本地跑模型比如通过 Ollama 拉一个qwen2.5-coder或者llama3.1然后把 baseURL 指向http://localhost:11434/v1。这类方案的好处是数据不出本机敏感项目和离线环境首选。用 Ollama 的配置示例{ provider: { ollama: { npm: ai-sdk/ollama, options: { baseURL: http://localhost:11434/v1 } } } }不过说实话本地模型目前的代码能力跟顶级商业模型还是有肉眼可见的差距特别是让 Agent 自主修改多文件代码的时候容易犯错。我的建议是本地模型适合做辅助问答和上下文总结真到“放手让它改代码”的关键环节还是用强一点的商业模型比较稳。注意网上有些人把“免费模型”吹得天花乱坠但实际上很多是套了层中转接口稳定性存疑还会把你的代码送到未知服务器。我个人原则是能用官方 API 就用官方能用本地就跑本地别贪小便宜。3.3 ccswitch 到底解决了什么问题很多人第一次看到“ccswitch”是在别人的工作流截图里以为是什么高级插件。其实它的本质非常简单一个配置文件切换器。你在多个模型供应商之间来回切换时如果每次都要手动改环境变量或改配置文件既容易错又费时间。ccswitch 的思路是——你先把所有供应商的 API Key 和 Base URL 存好然后通过一条命令切到某个配置它会把对应的环境变量注入当前终端之后启动的 opencode 自动继承。举个例子ccswitch add company-a --provider openai --base-url https://api.company-a.com --api-key sk-xxx ccswitch add local-ollama --provider openai --base-url http://localhost:11434/v1 --api-key ollama ccswitch use company-a然后在同一个终端里启动opencode它就会用company-a的配置。为什么 opencode 用户这么热衷于 ccswitch因为 opencode 的设计哲学是“把模型选择权完全交给外部环境”它自己只负责认真读代码、跑命令。你可以在上班时切到公司的合规模型回家后切到本地模型写博客时切到便宜的大模型全程都是一条命令的事不用改配置文件也不用记一堆环境变量名。这个体验用习惯了真的回不去。4. 插件化使用VSCode 与 IDEA 里的 opencode 工作流CLI 用久了你会自然而然地想让 opencode 出现在编辑器里。原因是CLI 里看代码改动始终隔了一层你得让 Agent 把 diff 列出来再手动跳到对应文件看上下文而 IDE 插件可以做到“边聊边改、逐行审阅”体验完全不一样。4.1 VSCode 插件侧边栏里的项目协作VSCode 装好 opencode 插件后最核心的入口是侧边栏面板。你可以直接选中一段代码右键发给 opencode 提问它会基于整个项目上下文回答而不是只看选中那一截。我日常用得最多的几个操作选中报错信息问“这个异常最可能的原因是什么”。让它定位某个功能对应的代码位置并给出一份改动方案但先不改代码。让它批量给当前目录下所有测试文件补充注释或者补测试用例。在侧边栏直接看 AI 产生的 diff一处处确认后再接受而不是让它偷偷改文件。这里的核心技巧是前面几轮对话先让它输出方案和影响面分析等你确认了再让它动手。opencode 也支持把修改模式设置成“每次修改前先征求同意”对保守派来说很实用。4.2 IDEA 插件与 Maven 项目的特殊处理Java 或 Kotlin 项目用 JetBrains IDE 的直接在插件市场搜 opencode 安装。这类项目的痛点不在“能不能改代码”而在“改完以后怎么验证”。你让 Agent 改了pom.xml里的依赖它总得知道怎么跑构建吧。这就引出热搜里的“opencode mvn配置”。在 opencode 的配置里你可以预置一些“项目命令”让 Agent 在需要的时候直接调用而不是靠猜。比如{ commands: { build: mvn clean compile -DskipTests, test: mvn test -DfailIfNoTestsfalse, package: mvn package -DskipTests } }配置好以后你在对话里说“帮我跑一下 build”agent 就会执行mvn clean compile -DskipTests然后把输出拿回来分析。对 Java 老项目来说这个“命令预置”模式比让它自己从 README 里猜要靠谱一万倍因为很多远古项目的构建方式根本不在文档里。4.3 三端如何使用才不会打架我的个人经验是CLI 负责重活IDE 插件负责精活桌面版负责展示。CLI/TUI适合大范围搜索、重构、批量改文件、跑测试、和 CI 脚本集成。IDE 插件适合局部代码理解、逐行审阅 diff、快速提问。桌面版适合看着对话记录做决策比如让 Agent 同时处理几个独立任务时桌面版的信息密度更高。三者共享同一个项目配置和 session只要你装的是同一版本的引擎就不会出现“插件里说的话 CLI 不知道”的割裂感。当然前提是你别瞎改配置文件保持两边同步。5. 把 opencode 训练成项目老手Skills、Memory 与 Superpowers这个章节我觉得是最“值钱”的部分。很多人在热搜里搜“opencode skills”“opencode memory”“opencode oh-my-claudecode”其实就是想知道怎么让 Agent 不是个每次失忆的临时工而是真的懂这个项目的长期伙伴。5.1 Skills把团队流程写成人话给 Agent 看Skills 机制简单说就是你把项目的特定操作流程写成一个 Markdown 文件放在.opencode/skills/目录下Agent 在执行相关任务时就会自动读取并遵循这个流程。它适合沉淀那些“文档里没有、但团队每个人都知道”的规矩。比如你的项目规定“提交代码前必须跑 lint 和类型检查、不能直接提交到 main 分支”可以写一个 skill--- name: project-conventions description: 项目开发规范新开发任务必须遵守 --- - 修改代码后必须运行 npm run lint 和 npx tsc --noEmit - 提交代码必须创建 feature 分支禁止直接推到 main - 所有请求封装放在 src/api 目录下 - 新页面必须使用项目统一的 Table 组件禁止自己拼表格有了这个 skillAgent 后续的每一次自动修改都会带上这些约束省去你反复在对话里提醒的麻烦。你也可以为特定任务写专门的 skill比如“部署预览环境”“生成 API 文档”“跑性能回归”本质上就是给它一本操作手册。5.2 Memory让 Agent 记住上次聊了什么Memory 是 opencode 2.0 之后强调的能力。你可以在对话里直接说“记住本项目的状态管理用的是 zustand不要在组件里直接写 useState 管理全局数据”。Agent 会把这条约定写入 memory 文件之后每次启动都会自动加载。这个能力最适合“接手老项目”的场景也就是热搜里那句“opencode 接手开发项目”先让 Agent 读一遍项目结构、启动方式、技术栈再让它总结成 memory。然后让它基于 memory 去理解代码、找 bug、给方案。之后你会发现它不会反复问“这个项目为什么这么写”“路由在哪个文件”这类基础问题因为它已经记住了。那些“换了个 Agent 就跟换了个同事”的抱怨大部分就是因为没给它建立 memory。花二十分钟喂数据后面能省几十个小时。5.3 Superpowers 和 oh-my-claudecode别人的配置能不能直接抄社区里很火的 superpowers 本尊是一套给 Claude Code 设计的技能包里面塞了大量精心编写的 skills 和提示词模板。opencode 因为也支持 skills 机制所以很多人直接把 superpowers 的目录搬过来用效果还行。市面上还有 oh-my-claudecode 这类“配置大全”项目相当于给 Agent 用的“oh-my-zsh”装完后一堆预设技能、别名、工作流模板。我的建议是这样可以抄但别全抄。superpowers 里有些 skill 写得非常啰嗦加载到上下文里会白白消耗 token而且未必符合你的项目习惯。更好的方式是借鉴它的目录结构和写法然后自己按照项目需求精简。毕竟对 Agent 来说上下文里塞一百个用不到的 skill跟人脑里塞一堆没用的说明书一样都会影响判断。提示无论用哪种技能包先把 memory 里喂进项目的核心约束再谈 Skills顺序反了容易让 Agent 拿着一堆通用模板去套你的特殊场景效果反而更差。6. 实战复盘让 opencode 接手前端项目并用 Playwright 自测 Bug理论知识说再多不如图一乐我拿一个真实工作流复盘一下怎么用 opencode 修一个前端 bug。这个案例是我最近给一个电商后台管理系统做的改造问题复现条件很明确订单列表页筛选状态后列表没有刷新控制台偶尔报一个 undefined 错误。6.1 先让 Agent 做项目侦察别急着改代码启动 opencode 后我的第一轮指令是先不要改任何代码。把项目结构、技术栈、启动命令、测试命令读一遍然后告诉我这个项目最可能有问题的文件是哪些。它会先列出目录树、读取 package.json、找到入口文件、分析路由和状态管理并给出一个“我认为订单筛选逻辑在哪些文件里”的判断。这一步的价值在于确认 Agent 理解项目没跑偏。如果它连看都没看就开始答你就能及时喊停而不是等它改了一堆文件才发现方向错了。6.2 定位筛选不刷新的根因接着我让它打开疑似组件打开订单列表组件把筛选状态变化到数据请求的链路给我梳理一遍重点看 useEffect 的依赖项。Agent 会搜索相关代码然后总结几条可能原因和对应证据。那次它给出的结论是筛选条件更新后接口请求还是用的旧的 query 参数因为 useEffect 的依赖数组里漏掉了筛选状态字段。它还顺带发现了一个潜在的内存泄漏组件卸载时没有取消异步请求。我选择先问清楚再让它改你觉得最小改动方案是什么只改筛选刷新这个问题不要顺手重构。这个指令很重要可以防止 Agent 突然给你来一次“顺手优化”把无关变量一起改掉增加回归风险。6.3 自动修复与 Playwright 验证闭环修复方案确认后我让它直接改并且在动手前加了这句话改完后用 playwright 打开本地 dev server操作筛选控件确认列表刷新了并把结果告诉我。opencode 支持在对话中生成并执行 Node 脚本。它当时做了一件堪称“杀手级体验”的事自己启动了 dev server因为是 Vite 项目写了一个临时 Playwright 脚本通过浏览器操作真实页面点击状态筛选、等待接口返回、断言列表行数变化最后还截了图。我看它截图确认没问题后又追加了一轮回归指令再跑一遍之前的测试用例确保筛选修复没有影响其他功能。它把失败测试抓出来后顺带修掉了另一个断言因异步时序不稳导致的问题。这次实战里真正节省我时间的不是“它会写代码”而是它把“定位问题→改代码→启动服务→浏览器操作→断言结果”这整条链路串起来了。这在之前的纯编辑器插件工作流里几乎不可能实现因为那些工具没有能力同时操纵开发服务器和浏览器。6.4 对 Playwright 能力的边界提醒opencode 的 Playwright 能力确实强但不是万能的。它适合验证“页面能打开、点击按钮有反应、接口有响应、列表渲染正确”这类显性结果如果你要测复杂的登录态、扫码流程、权限矩阵还是老老实实写正式的端到端测试脚本吧。另外Agent 写 Playwright 脚本时对选择器的依赖很强如果项目里到处是动态 class 名它很容易定位失败我建议项目里尽量给可测试的关键元素加上稳定的>