最近折腾 opencode 折腾得比较深从命令行到 IDE 插件从改配置到让它自己跑 Playwright 定位前端 Bug前前后后踩了不少坑也沉淀出一套比较顺手的用法。如果你也在用或者准备用这类的终端 AI 编程代理这篇文章应该能帮你少走很多弯路——我会从它是什么、怎么装、怎么配模型一路讲到怎么用 skills、memory 和 MCP 把 opencode 调教成真正能干活的项目助理。先说清楚一个点opencode 不是某个大厂做的一个套壳工具它是一套开源终端 AI 代理terminal AI agent核心思路是在命令行里给你一个能够读写文件、执行命令、调用各种工具的 AI 助手。它跟你平时用的代码补全插件是两码事补全是在你写代码时给建议而 opencode 是直接接手一个小任务自己去读代码、改文件、跑测试。这两者的使用场景和思维方式完全不同下面我会详细拆。1. opencode 是什么解决什么问题1.1 一个终端里的 AI 编程代理opencode 最早是 SST 团队开源的项目作者 Dax Raad 在做 Serverless 开发工具时发现开发者真正需要的不是一个对话框而是一个能主动干活、能读懂项目上下文的代理。所以 opencode 的设计目标非常明确在终端里跑一个和你在同一个代码仓库工作的 AI它能调 shell、读文件、修改代码、调用 MCP 工具还能和 Git 交互。从用户视角看你在命令行敲opencode就会进入一个交互式 TUI文本界面默认会加载当前目录的代码上下文。你可以直接问这个项目的入口在哪依赖注入是怎么组织的也可以下达实操指令把 userService 里重复的三个 try-catch 抽成公共异常处理。它俩的区别就在这前者是问答后者是任务执行。我在实际使用中最常用的是后者。比如接手一个老项目时我会直接跟 opencode 说梳理一下这个仓库的技术栈、目录结构和核心模块写一份 README 补充建议。它会自己遍历目录、读取关键文件、归纳总结不用我一个文件一个文件看。1.2 它和普通代码补全工具的本质区别用 Copilot 或者 Continue 这类补全插件时你的工作流是人在回路AI 给建议你审核、接收、修改。opencode 的工作流更像是目标委托你把一个明确的目标交给它它自己规划步骤、逐个执行、遇到问题还可以自己修。这个区别听起来不大实际用起来差异巨大。补全工具是单向的它永远不会主动发现你的测试挂了顺手给你跑一下但 opencode 可以。比如你让它完成某个接口的重构它完成修改后可能会自己运行npm run test看到报错再回来改代码循环往复直到测试通过。当然这也意味着它需要的权限和上下文比补全工具大得多。所以 opencode 提供了非常细粒度的权限控制你可以规定哪些命令可以自动执行、哪些操作需要确认、哪些目录不允许写。第一次用的人很容易忽略这个配置后面我会详细讲。1.3 适合谁用三类人我觉得最适合用 opencode第一类是日常在终端里工作的后端和全栈工程师尤其是经常要跨模块改代码、做重构、写测试的人这类工作正好是代理型 AI 的强项。第二类是经常要接手别人代码的人。opencode 的/init可以生成 AGENTS.md相当于给 AI 看的一份项目说明书把代码库结构、技术约束、常用命令都沉淀下来。接手新项目时这一步特别香。第三类是愿意折腾、对模型选择有自己偏好的人。opencode 不锁死某个模型你可以用 Anthropic、OpenAI、DeepSeek、智谱也可以用本地部署的开源模型配置灵活度远高于那些只绑官方服务的工具。2. 安装与环境准备从零跑通2.1 三种常用安装方式opencode 的安装方式现在比较成熟主要用包管理器或者官方安装脚本。我自己在 macOS 和 Windows 上都装过推荐方式如下macOS 推荐用 Homebrewbrew install sst/tap/opencode装完直接有opencode命令升级也方便。Linux 或 WSL 推荐官方脚本curl -fsSL https://opencode.ai/install | bash默认装到~/.opencode/bin。Windows 原生环境或者 Node 生态用户可以用 npmnpm install -g opencode-ai前提是本机有 Node.js 18 以上。装完先跑一句opencode --version确认安装成功。如果输出一串版本号说明基础环境没问题如果提示找不到命令大概率是 PATH 的问题下一小节专门讲。这里插一个体会如果你平时主力机器是 Windows但开发环境在 WSL 里那就在 WSL 里装一份别在 Windows 原生环境里装完再跨系统调用文件路径和命令执行都会绕远路。2.2 无法将 opencode 项识别为 cmdlet到底怎么解这个报错在 Windows 上非常常见很多人在 PowerShell 里运行opencode时直接看到opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这行中文报错本质上就是系统找不到opencode这个可执行文件。原因就两个第一个原因最简单——压根没装上或者装了一半失败。先确认那三种安装方式至少成功了一种再继续排查。第二个原因是环境变量 PATH 没配好。用 npm 安装时全局 bin 目录未必在 PATH 里。我用一条命令就能定位问题npm prefix -g这条命令会输出全局安装根目录比如C:\Users\你的用户名\AppData\Roaming\npm。检查这个目录下有没有opencode.cmd或者opencode.ps1。有的话把该目录加进系统 PATH 就行。官方脚本方式安装的话可执行文件一般落在%USERPROFILE%\.opencode\bin同样把它加入 PATH 后重新开一个 PowerShell 窗口就好。如果你不想改系统环境变量还有一个临时但可靠的替代方案直接用npx opencode-ai运行或者运行完整路径。比如npx opencode-ai这种方式适合应急确认是不是 PATH 的问题但日常使用还是建议把 PATH 配好否则每次都要记得包一层。2.3 第一次启动需要做什么装好后第一次运行opencode它会检查你本机的模型配置。默认情况下它支持通过环境变量读取各家模型的 API Key比如ANTHROPIC_API_KEY、OPENAI_API_KEY。你至少配好一个才能正常对话和干活。我建议第一次进 TUI 后先敲/models看当前可用模型列表然后切到你计划用的那个模型。再敲/config打开配置面板确认权限模式是否符合预期。还有一个容易被忽略的细节opencode 会把会话历史、配置、日志写入用户目录下的.local/share/opencode和.config/opencode。如果你的磁盘空间紧张或者有备份需求要留意这两个目录。3. 模型接入与配置管理3.1 配置文件长什么样opencode 的配置核心是 JSON 文件全局配置默认在~/.config/opencode/opencode.jsonWindows 下是%USERPROFILE%\.config\opencode\opencode.json项目级别的配置放在仓库根目录的opencode.json里后者会覆盖前者。一个最小可用的配置大概是这样的{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, provider: { anthropic: { api_key: env:ANTHROPIC_API_KEY } }, permission: { default: ask } }model字段指定默认模型注意格式一般是提供商/模型名。provider下面是各家 API 的认证信息推荐用env:变量名的写法而不是直接把密钥写进文件因为配置文件经常要同步到多台机器甚至提交到仓库做团队共享明文密钥容易出事。permission控制工具的调用权限。default: ask表示所有敏感操作都要先问过我写代码、读文件这类相对安全的操作也建议保留确认。另一种常见玩法是default: allow配合deny列表适合完全信任场景比如 CI 里跑自动化任务。3.2 免费模型和低成本方案怎么选opencode 本身不卖模型它是纯粹的客户端工具。你担心的套餐问题其实是模型提供方的计费策略。如果你不想一开始就花钱有几条路可以走。最稳的低成本路线是本地模型。用 Ollama 拉起一个开源编程模型然后告诉 opencode 走本地接口就行。以 qwen2.5-coder 为例本地装好 Ollama 后拉取模型ollama pull qwen2.5-coder:14b然后在 opencode 配置里加一个 provider{ provider: { ollama: { npm: ai-sdk/openai-compatible, name: Ollama, options: { baseURL: http://localhost:11434/v1 }, models: { qwen2.5-coder:14b: { name: Qwen Coder 14B } } } }, model: ollama/qwen2.5-coder:14b }本地模型的优点是免费、数据不出机器、可以无限折腾缺点是模型能力天花板有限写复杂重构时容易给你一本正经地写错代码。我的建议是本地开源模型适合做跑通流程、处理简单机械任务、敏感代码场景需要高质量重构和架构决策时还是切到能力更强的云 API。云 API 方面国内可以正常访问的服务商也有不少选择比如 DeepSeek、智谱、Kimi 这些都有开发者接口。它们的计费普遍是预充值、按 token 消耗对个人开发者来说日常写代码辅助一个月成本其实很可控。还有一种思路是留意一些服务商的首充赠送额度或免费试用包先把流程跑通再决定是否充值。3.3 用配置工具统一管理多套模型配置用 opencode 时间长了你会发现自己手上不止一个 API Key也不止一个模型。今天想用 A 模型做代码审查明天想用 B 模型做前端调试总不能每次都打开 JSON 改一遍。这个场景下很多人会引入 ccswitch 这类配置管理工具。它的核心作用是把当前 API 的路由和 Key 指向独立出来统一管理让你在切换模型服务商时不用动 opencode 的配置结构只需要在 opencode 里通过环境变量读取当前生效的配置即可。这类工具的好处是环境变量层面的解耦多个终端工具opencode、Codex CLI、其他 AI 助手可以共享一套密钥管理和路由策略避免每个工具里都维护一份重复的配置。我自己实践下来的一个简化做法是这样的不用额外工具只是写了一个switch.sh脚本里面导出不同服务商的环境变量然后用不同的opencode配置目录启动。本质上是用 shell 脚本管理多套环境。但如果你同时用很多 AI 命令行工具那上一个统一的配置工具确实更省心。4. IDE 集成与完整实战工作流4.1 VSCode 与 JetBrains 插件opencode 不只在终端里能用。官方提供了 VSCode 插件和 JetBrains 插件装好之后可以在编辑器里直接调起 opencode选中的代码可以一键发送给 AI 让它分析或修改。VSCode 插件直接在扩展市场搜 opencode 就能装。装完会在侧边栏或命令面板里看到一个入口选中代码后右键选Open in OpenCode不同版本菜单位置可能略有差异它会带着选中的代码上下文进入会话。这个功能在审查某段复杂逻辑时特别有用不用自己手动复制粘贴一大坨代码还要担心上下文丢失。JetBrains 系的 IDEA 插件同理装好后在编辑器内右键就可以把代码送进 opencode 会话。需要注意插件和 CLI 共享同一份全局配置和会话存储所以你在终端里配置好的模型、skills、memory在 IDE 里一样生效不用重复配置。我用下来的感受是IDE 插件适合局部代码理解比如看不懂一个函数的作用域和调用链终端里的 TUI 适合全仓库范围的任务比如跨模块重构、跑测试、批量替换。两者配合能覆盖从微观到宏观的所有场景。4.2 接手存量项目的第一小时这是我到目前为止觉得 opencode 最值回票价的使用场景。拿到一个没见过的老仓库我一般这样处理。首先进入项目根目录跑opencode /init这一步会要求 AI 浏览整个代码库生成一份 AGENTS.md。这份文件会写入仓库根目录里面包含项目结构说明、技术栈、构建命令、约定规范等。AGENTS.md 既是给 AI 看的项目说明书也是给你自己的极简开发者文档——接手新项目时它比很多陈旧 wiki 管用。然后我会给 opencode 下达三个连续任务把项目快速啃下来让它定位入口文件和核心路由梳理请求从上到下的调用链让它找出数据模型和数据库迁移的关键定义整理出一份字段关系说明让它列出项目里明显的技术债比如循环依赖、重复代码、过时的依赖版本。这三个任务执行完我对新项目的了解速度远超自己埋头读代码。关键点是每次任务描述要尽量明确输出格式比如用列表标注文件路径指出你拿不准的部分。AI 代理最怕的就是模糊需求给它越明确的产出要求结果越可预期。4.3 skills 让助手具备团队规范opencode 的 skills 机制简单理解就是给 AI 预置一些专项技能让它在处理特定任务时遵循特定的流程和标准。它的形态是一组自定义指令文件放在.opencode/skills目录下项目级或全局 skills 目录下。每个 skill 一般由一个 YAML 头和一个 Markdown 说明组成。比如我想让 opencode 按团队规范审查 PR可以建一个.opencode/skills/review.md--- name: review description: 按团队规范进行代码审查重点关注正确性、可维护性和性能 --- 当执行代码审查任务时必须遵循以下步骤 1. 先梳理变更涉及的模块和影响范围 2. 检查错误处理是否完整禁止吞掉异常 3. 确认所有新增依赖都有明确必要且版本锁定 4. 对可疑逻辑给出修改建议而不是只提出问题 5. 最终输出按问题清单/建议清单/可忽略项三部分组织之后你在会话里告诉 opencode用 review skill 审查这次的改动它就会按这个流程执行。它的价值在于把团队的工程规范沉淀成 AI 可执行的指令而不是每次靠你现场口述。skills 的粒度可以很细。我见过有人给前端项目做了一个Vue 组件规范的 skill要求所有新组件必须用 script setup 语法、样式必须用 scoped、props 必须带默认值也有人给后端项目做接口设计的 skill规定所有 REST 接口必须补充 OpenAPI 注解。这些规范写进 skill 后AI 生成的代码合规率明显提升。4.4 memory 记住你的偏好如果说 skills 解决的是任务怎么做那 memory 解决的就是长期偏好怎么存。opencode 的 memory 功能可以把一些零散的、跨会话要记住的信息持久化下来。比如你多次纠正 AI这个项目测试框架是 vitest 不是 jest或者数据库迁移不要直接改旧迁移文件要新增一个这些偏好如果能被 AI 记住后续会话就不用反复调教。实际用法有两种一种是会话里直接告诉 opencode记住本项目测试命令是 pnpm vitest它会写入记忆另一种是手动编辑 memory 文件全局记忆在~/.local/share/opencode/memory项目级记忆在.opencode/memory。我的建议是凡是和具体代码无关、只和团队习惯/项目长期约定有关的偏好都值得丢进 memory。这样即使隔一个月再打开这个项目AI 仍然知道你的规矩不会每回都从零开始猜。4.5 用 Playwright MCP 定位前端 Bug这个热词问的人很多opencode 怎么用 Playwright 测试前端 Bug答案是通过 MCPModel Context Protocol给它接一个 Playwright 服务。MCP 是 AI 工具接入外部能力的标准协议可以把它理解成AI 的 USB 接口。opencode 原生支持 MCP所以只要跑一个 Playwright 的 MCP 服务AI 就能启动浏览器、打开页面、点击元素、读取 console 日志、截图然后把观察到的信息反馈到推理过程里。配置方式是在 opencode.json 里加一段{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest], environment: {} } } }配置好之后你可以在 opencode 会话里描述一个 Bug 现象比如点击登录按钮后没有跳转控制台疑似报错帮我定位一下。opencode 会自己去打开页面复现读取控制台信息结合你给的上下文分析原因甚至直接给出修复建议。我实际踩过的一个坑是Playwright MCP 启动的浏览器实例默认是带界面headed还是无头headless模式直接影响了在服务器环境下的可用性。本地开发建议用带界面的能看到它打开的是什么页面在 CI 或远程环境则要切 headless否则会因为没有显示器直接报错。具体配置项建议查一下当时的 Playwright MCP 文档它更新比较勤。5. 高频报错与横向横评5.1 高频问题速查表我把这段时间收集到的问题整理成了一张表覆盖我见到的大部分初学痛点症状原因解决方案opencode: command not foundPATH 未包含可执行目录检查安装目录并加入 PATH或改用npx opencode-ai应急cmdlet 报无法识别同上Windows 特例把 npm 全局目录或.opencode\bin加入系统 PATH重开终端error: unexpected server error. check server logs模型服务端返回异常可能是 Key 无效、额度用尽或网络不通先确认 API Key 正确、余额充足再看服务商状态页模型一直加载但无响应上下文中包含过多文件或本地模型性能不足减少加载目录范围用/compact压缩会话上下文权限弹窗太频繁打扰permission 配置过于保守在permission里针对常用命令设置allow白名单修改文件后格式乱了AI 不理解项目格式化规范在 AGENTS.md 或 skill 里写明使用项目的 prettier/eslint 配置修改后运行 formatmemory 不生效记忆文件写入后未正确匹配项目路径确认记忆是放在项目级还是全局目录会话里主动说记住...Playwright MCP 连不上浏览器端口冲突或环境变量缺失检查 npx 是否能单独启动 playwright/mcp确认浏览器已安装一个通用排查思路opencode 的问题最好从日志入手。运行opencode --log-level DEBUG启动后会输出详细的调试日志包括它调了哪个模型、请求体大小、工具执行结果。大多数莫名其妙的问题都能在日志里找到答案比自己瞎猜高效得多。5.2 opencode vs Codex vs Claude Code怎么选最近社区里讨论最多的问题就是这个这几个终端 AI Agent 到底选哪个Codex CLI 是 OpenAI 出品的官方 CLI最大的优势是和 ChatGPT 生态深度绑定登录 ChatGPT 账号就能用初始配置成本极低。如果你重度使用 OpenAI 模型并且经常用到 OpenAI 系的工作流选 Codex 很顺。它的主要限制也在这里——模型选择基本锁死在 OpenAI 体系内私有化部署和多模型切换的灵活性比较弱。Claude Code 是 Anthropic 的官方终端工具在代码理解和长上下文处理上做得相当成熟写复杂重构和大型项目分析时表现很强。但它同样绑定 Anthropic 模型而且目前的授权方式对非订阅用户不太友好想用免费或者低成本方案时比较尴尬。opencode 的优势在于它的中立性。它不绑定任何模型你可以自由选择不同提供商的模型甚至可以切成多个模型协作。对于团队来说这意味着可以按任务类型分配模型——简单任务用便宜模型复杂架构任务用好模型整体成本更容易控制。它还开源遇到问题可以自己改代码修 Bug社区也活跃。我的建议是如果你只想快速体验终端 AI 代理这件事且已经有某个平台的订阅那就直接用对应的官方工具比如 Codex 或者 Claude Code。如果你打算长期把 AI Agent 作为日常开发基础设施同时在意成本、隐私、可配置性那 opencode 是更值得投入时间去折腾的那一个。它前期的配置成本比官方工具高一点但把配置、skills、memory 和 MCP 体系搭好之后你能获得的是一个完全按自己习惯定制的 AI 开发助手这种掌控感是官方工具给不了的。再说一个很多人问的opencode 的套餐到底值不值。工具本身开源免费你要是自己配模型费用全在模型调用上。但如果你不想折腾配置官方也提供托管方案按订阅制收费具体价格以官网为准。我个人的看法是个人开发者先用自带配置的免费路径跑熟再说团队再考虑付费托管别一步到位买套餐。这个内容后续还可以这样扩展把团队工程规范全量沉淀成 skills把项目的架构决策记录到 memory再在 CI 里跑一个opencode review作为自动代码审查的一道关卡。我现在已经在自己维护的几个项目里跑通了一部分最明显的变化是接手老项目的心态——以前是这代码能跑就行别动现在敢让 AI 去拆解、重构、补测试因为每一步改动了什么、为什么改它都能讲清楚。踩过几次坑之后我最大的体会是这种工具用得好不好根本不取决于模型有多强而取决于你有没有把项目上下文、团队规范、权限边界这三件事交代清楚。把这些做好了opencode 是真的能在你的开发流程里顶一个人用的。