opencode 最近在 AI 编程圈子里热度起来得很快和 Claude Code、Codex CLI 这类终端型 AI 编程代理放在一起讨论的频率越来越高。如果你已经在用 Cursor 或 Continue 这类 IDE 插件又在琢磨怎么让 AI 更深入地参与整个开发流程opencode 值得花一个周末试试。这篇文章不是官方文档的复述而是结合我和社区里不少人实际跑过的流程把从安装、配置到接手项目、测试前端 bug 的完整链路讲清楚。1. opencode 在 AI 编程工具里处在什么位置1.1 先理清它和 Claude Code、Codex、Cursor 的差别很多人第一次看到 opencode 会下意识拿它和 Copilot 比其实这两类东西定位完全不同。Copilot 是行级补全你写代码它猜下一句而 opencode 属于代理式编程工具它拿到你的需求后自己规划步骤、读写文件、执行命令、跑测试像一个坐在你旁边干活的人。这个品类里目前最知名的是 Anthropic 官方的 Claude Code 和 OpenAI 的 Codex CLI。opencode 和它们最大的区别在于开源和开放性能力维度opencodeClaude CodeCodex CLI模型绑定可接 Anthropic / OpenAI / 本地模型等多家主要绑定 Claude 系列主要绑定 GPT 系列源码可见完全开源闭源闭源IDE 插件官方支持 VSCode、JetBrains官方不提供社区插件为主Skills 扩展支持自定义技能包支持Anthropic 生态支持度一般LSP 集成已支持有限有限一句话概括opencode 是不挑模型、不挑编辑器的通用型终端编码代理。它本身的定位不是某个云服务的专属客户端而是一个可以对接多种模型后端的协调层。1.2 为什么一个终端工具要内置 LSP、Playwright 这些能力热词里出现了 opencode skills、opencode LSP、opencode playwright这三个词其实反映了 opencode 的设计思路一个合格的编程代理光会读文件生成文本是不够的它得能和真实开发环境交互。LSPLanguage Server Protocol集成解决的是读代码的准确度问题。默认情况下agent 是靠关键词搜索和文件遍历来理解代码库的遇到跨文件的类型引用、接口实现就很容易猜错。接上 LSP 之后opencode 可以直接问语言服务器这个函数在哪里定义、被谁调用理解代码的方式和现代 IDE 一样。Playwright 集成解决的是前端 bug 验证问题。传统流程里AI 改完前端代码你得自己打开浏览器点一遍opencode 可以通过 Playwright 启动真实浏览器、模拟点击、截图、收集控制台报错然后把结果回传给模型用于下一轮修复。这个闭环对于跑改一行 CSS 导致布局错乱这类问题特别实用。Skills技能包则是把高频的操作流程封装成可复用的工具集。比如你可以定义一个生成符合仓库规范的组件的 skill里面包含项目目录规范、命名约定、辅助脚本之后 agent 每次创建组件时自动加载这些约束。这三样东西组合起来opencode 就不只是一个聊天机器人套壳而是一套能感知项目上下文、能执行端到端验证的自动化开发环境。2. 安装 opencode从下载到能跑起来2.1 三种安装方式怎么选opencode 官方推荐的安装方式依赖 Node.js要求 20 版本以上可以通过 npm、Homebrew 或者官方安装脚本安装# 方式一npm 全局安装最通用 npm install -g opencode-ai # 方式二macOS 使用 Homebrew brew install sst/tap/opencode # 方式三Linux/macOS 安装脚本 curl -fsSL https://opencode.ai/install | bash我的建议是主力环境用 npm原因有两个。第一npm 包更新频率高新功能比如 LSP 集成总是先发在 npm 上第二卸载和版本回退都方便npm install -g opencode-ai版本号就能切到指定版本。如果日常用 Docker 开发也可以考虑把 opencode 装进容器镜像里随开发环境一起分发团队协作时版本一致性更好。安装完成后执行opencode --version能正常输出版本号说明装好了。2.2 Windows 下无法将 opencode 识别为 cmdlet的修复热词里有一条很有代表性opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错在 Windows 上出现频率很高但原因通常不是 opencode 本身有问题而是 npm 全局包所在的目录不在系统 PATH 里。修复方法分两步。第一步确认 npm 全局安装目录npm config get prefix在 Windows 上通常得到的是C:\Users\你的用户名\AppData\Roaming\npm。第二步把这个目录加入系统环境变量打开设置 - 系统 - 关于 - 高级系统设置点击环境变量在下方的系统变量里找到Path点击编辑新建一行填入 npm 全局目录确定保存。保存后需要重新打开一个终端窗口才能生效。有个小提示PowerShell 里如果修改过执行策略有时还需要先允许本地脚本运行可以查看 Windows 官方执行策略文档按需设置为RemoteSigned这样既能运行 opencode 的启动脚本又不会全放开。2.3 模型 Provider 与 API Key 配置装好二进制文件之后最关键的一步是配置模型服务商。opencode 的配置逻辑和普通 CLI 工具不一样它不直接对接单一厂商而是要求你在配置里指定一个或多个 Provider模型服务商以及对应的 API Key。执行opencode进入交互界面首次启动会引导你配置我更推荐直接手动创建配置文件路径在~/.config/opencode/opencode.jsonLinux/macOS或%USERPROFILE%\.config\opencode\opencode.jsonWindows。最小可用配置长这样{ $schema: https://opencode.ai/config.json, provider: { anthropic: { apiKey: sk-ant-... } }, model: anthropic/claude-sonnet-5 }这里的provider是一个对象键是 Provider 名称值是认证信息。model 字段采用 服务商/模型名 的格式。社区里常见的一个坑是直接写模型名不带服务商前缀导致 opencode 找不到模型。日常使用我建议至少配置两个 Provider比如一个 Anhropic 模型用于复杂重构一个便宜的基础模型用于简单问答这样可以根据任务成本灵活切换不至于每次小改动也消耗高价 token。热词里还有ccswitch 配置 opencode和opencode go 需要配合 cc switch 等工具这里多解释一句ccswitch 是一个用来切换 API 接入点/配置文件的社区工具。我自己的体会是当你有多个 API 服务端、或者需要快速在不同团队项目之间切换 Key 时这类工具确实方便。你只需要在 ccswitch 里维护好不同场景的 API 配置切换完成后确保环境变量ANTHROPIC_BASE_URL、OPENAI_BASE_URL之类的值被正确设置opencode 会自动读取这些标准环境变量。注意不同厂商的模型服务端点格式不一样切换完最好先跑一次简单对话验证连通性避免在编码中途才发现请求全部失败。3. 把 opencode 接入你的工作流3.1 终端交互模式TUI 界面怎么用在项目根目录执行opencode会进入一个基于终端的交互界面TUI。界面底部是输入框可以直接输入自然语言指令比如帮我看看 src/components/button.tsx 这个文件有没有潜在的样式问题。opencode 收到指令后会在右侧面板流式显示当前正在读的文件、正在执行的命令以及模型思考过程。TUI 模式下最常用的几个快捷键CtrlN/CtrlP新建对话 / 切换会话CtrlE打开模型选择器快速切换模型CtrlB查看当前会话的文件变更列表Esc中断当前操作。操作逻辑和主流终端工具一致。交互模式下我建议养成先问再做的习惯也就是让 opencode 先解释它的计划确认无误后再让它动手改代码尤其是改动文件多的任务能让 AI 给出一个变更清单这个习惯能省掉很多返工时间。3.2 非交互模式opencode run 和脚本化如果你想把 opencode 集成进 CI/CD或者批处理任务用非交互模式更合适。基本用法opencode run 检查所有 .ts 文件里的未使用变量并修复run命令之后跟的字符串就是你的 prompt。它会在当前目录上下文里执行任务完成后直接退出中途的详细过程输出在终端里。对于批量任务可以在 prompt 里加约束后缀例如只修复编译错误不要修改业务逻辑能明显降低 AI 顺手优化导致变更范围失控的概率。脚本化场景里一个非常有用的参数是--format可以指定输出格式opencode run 给 login 方法补充单元测试 --format jsonJSON 格式输出里包含生成的文件列表、命令执行记录、token 消耗量很适合写脚本解析。我在团队内部做过一个小工具每晚定时跑一条 opencode 指令扫描遗留 TODO 并生成报告然后通过 webhook 推到团队沟通软件里整个流程全靠非交互模式实现。3.3 VSCode 与 JetBrains 插件的差异热词里 opencode vscode 和 opencode jetbrains idea 插件 的搜索量很高说明很多人都希望在编辑器里直接使用而不是来回切终端。opencode 官方对这两个编辑器都有插件支持但成熟度不一样。VSCode 插件体验更完整因为它底层基于同一套 opencode-server 架构你可以在侧边栏打开一个面向 opencode 的面板看到 agent 执行任务时修改了哪些文件还能直接在编辑器里 diff 变更。JetBrains 插件也支持核心的对话和代码修改但功能迭代相对慢一些主要用ShiftShift打开终端后在 Tool Window 里操作。两个插件都支持将 opencode 作为 MCPModel Context Protocol服务器暴露给 IDE。也就是说Cursor 或 Trae 这类支持 MCP 客户端的编辑器也可以把 opencode 的 Skills、LSP 能力当作外部工具来调用。这个思路特别适合已经有 Cursor 习惯、但又想把 opencode 的 Skills 体系接入的团队——不需要迁移工作环境两边功能并联使用。插件项目里乐器提到的 opencode desktop 暂时还不是官方功能社区里有一些原型如果你在视频平台看到有人演示一个独立的桌面客户端那大概率是个人项目不建议作为主力依赖。目前最稳定的组合依然是终端 TUI 做复杂任务VSCode 插件做轻量交互。4. 实战接手开发项目时的正确打开方式4.1 让 agent 先读代码再动手热词里opencode 接手开发项目不是一个空泛的概念我第一次用它接手一个中等规模的 Node.js 项目时踩过很痛的坑直接让它把订单模块的接口改成带版本号结果 AI 靠着关键词搜索在十几个模块里绕来绕去最终改错了 4 个文件。那次之后我总结出一个可以复用的路径。第一步让模型先建索引。在项目根目录执行opencode run 分析并总结本项目的主要技术栈、目录结构、核心模块及其依赖关系将结果写到 AGENTS.md 文件AGENTS.md 是 opencode 支持的项目上下文文件它会在模型处理任务前自动加载。这个文件写得越准确后续任务的成功率越高。AI 分析完目录结构、包管理器、入口文件、数据库连接方式之后生成的 AGENTS.md 就是项目地图。第二步拆解任务。接手一个项目时不要一次性提一长串需求而是把任务拆成可验证的小步骤。比如目标是给用户模块加导出历史功能拆成分析用户模块当前的 HTTP 路由和数据库表结构设计导出接口的数据结构实现接口和前端按钮运行测试并修复问题。每个步骤之间用CtrlC重启新会话或者让 agent 在上一步基础上继续但确保每个步骤都有明确验收标准。经验是让 AI 一次性写好 500 行代码的风险远大于让它分 5 次每次写 100 行并逐步验证——前面写错还能及时修正后面可以完全偏移。第三步用opencode plan模式。opencode 支持 plan 模式agent 只做分析和规划不实际写文件。在交互界面输入 plan: 分析当前代码库给出实现用户导出历史功能的技术方案它会在终端列出详细的实施步骤、涉及文件清单和潜在风险。确认无误后输入 do it才真正开始修改。4.2 配置 LSP 提升代码检索准确度opencode 的 LSP 集成这几年看了下最新版本已经比较成熟。它能在读代码时借助语言服务器获取类型信息、函数签名、引用关系等可以简单理解为opencode 的搜索不再只是靠关键词匹配而是做到语义级别的文件浏览。启用 LSP 需要在配置文件里打开开关{ experimental: { lsp: true } }我建议启用。实际测试中在没有 LSP 时opencode 理解 TypeScript 项目里某个接口的实现类在哪里这类问题经常答错开启 LSP 后它可以直接通过语言服务器的definition请求定位到实现位置准确率显著提升。有一个配套技巧对于大型 monorepo配置workspace根目录到 LSP 可以提升启动速度避免它把整个仓库都塞进内存{ experimental: { lsp: true, lspRoots: [packages/server, packages/web] } }这样 opencode 只在这两个子目录下启用 LSP搜索其他目录仍用传统关键词方式。如果你的项目是用 Python 写的记得给对应的 Python 目录也配置进去LSP 支持和语言无关关键在于启动对应的语言服务器。5. 用 opencode 排查前端 bugplaywright 场景复盘5.1 让 agent 自己跑浏览器复现问题有一次我遇到一个诡异的前端 bug用户在首页点击立即购买按钮偶尔会出现页面卡死刷新后恢复正常。这种偶发 bug 靠肉眼点半天不一定能复现但是让 opencode 配合 Playwright 自动化测试来复现效率就高很多。我在 opencode 交互界面里输入帮我写一个 Playwright 脚本在本地环境打开首页重复点击立即购买按钮 20 次每次点击后检查页面是否出现未捕获的 JavaScript 异常如果出现截图保存到 /tmp并输出控制台日志。opencode 自动生成了一段 Playwright 脚本然后通过内置的命令执行器运行它。关键点在于脚本运行过程中如果检测到异常它会立刻把截图和 console 日志传给模型。模型就能看到点击第 7 次时控制台出现Failed to fetch /api/order/cart页面卡死这类精确信息然后直接定位到请求拦截逻辑的问题。如果你是初次使用需要先安装 Playwright 相关的依赖包并确保项目里已经有测试环境配置npm init playwrightlatest之后在 opencode 里运行生成 Playwright 脚本就会走浏览器自动化流程。唯一要注意的是 opencode 执行浏览器操作时你的电脑需要满足图形界面环境如果是无头 Linux 服务器需要安装必要的系统依赖库。5.2 打磨可复现的 bug 报告前端 bug 最难的是让别人复现AI agent 也一样。如果你的问题是页面有些卡让 opencode 去排查它大概率无从下手但如果你给它一个 Playwright 脚本它立刻能跑起来并追踪每一步的异常输出。这就是为什么我强烈建议让 opencode 排查前端问题之前先让它生成/维护一个最小复现脚本。我通常的做法是针对经常回归的模块维护一个playwright/manual-repro目录存放一批可以自己跑的复现脚本脚本里只保留触发 bug 的最简路径不依赖复杂登录态、不依赖特定账号数据。当用户报了一个 bug我先让 opencode 在这个目录里找一个最接近的脚本改几个参数去复现复现成功后再让模型看代码、给出修复方案。这样做的额外收益是修复完成后这个复现脚本可以直接转成一个回归测试用例尤其在 CI 里跑一遍防止同一个问题在后续迭代中再次出现。6. 避坑清单我从社区热词里挑出的高频问题6.1 This model is not available in your country 怎么处理这个报错很直接你当前请求的模型服务端在你所在的区域不可用。opencode 本身不做区域限制限制来自上游 API 服务商。处理思路是换用可用的模型或接入点而不是强行绕过限制。我自己的经验是如果你用的是 Anthropic 系列模型但报这个错先检查ANTHROPIC_BASE_URL指向的接入端是否和模型匹配如果你用的是 GPT 系列模型检查OPENAI_BASE_URL和OPENAI_AUTH_TOKEN是否配置正确也可以换用 opencode 支持的本地模型比如 Ollama 或 LM Studio 提供的模型这类模型直接在你机器上运行不存在区域概念。opencode 配置文件里的写法类似{ provider: { ollama: { url: http://localhost:11434/v1, apiKey: ollama } }, model: ollama/llama3.1:8b }本地模型虽然能力不如大厂云端模型但在处理简单重构、补测试、做文本格式化等任务上完全够用而且数据不出机器隐私上也更安心。我的建议是云模型和本地模型各配一个云模型做复杂推理、本地模型做轻量任务这样既能减少区域报错对工作的打断也能控制成本。6.2 unexpected server error. check server logs 的排查思路热词里有这样一条c:\windows\system32opencode error: unexpected server error. check server logs。这个问题我在 Mac 和 Linux 上也遇到过报错隐藏得很深但不难排查只要按顺序检查三层第一层网络与 API 端点。先确认 bash 环境下执行curl请求一下模型服务的健康检查接口看能不能连通。这一步能快速排除网络代理、防火墙、服务宕机的问题。第二层配置文件格式。打开 opencode.json确认 JSON 没有语法错误Provider 名称和模型名称拼写正确。一个小技巧官方配置 schema 很长你可以把配置文件里的$schema字段指到官方在线 schema很多编辑器会自动提示和校验配置项。第三层opencode 服务日志。执行opencode --log trace run ping开启追踪级别的日志报错原因通常会写在输出里。常见的情况包括 token 配额不足、上下文长度超限、某个 API 返回了非预期格式的流式数据。排查时有个我强烈推荐的思路给 opencode 配置一个轻量兜底模型。曾有一次我用 Claude 模型跑一个超大仓库时连续遇到服务端超时把交互界面切换到本地 Ollama 模型后虽然质量下降但任务还是成功跑完。生产环境里模型不稳定是常态提前准备兜底方案远比临时想办法更可靠。6.3 opencode 配置与模型订阅选择建议热词里出现opencode go 套餐、opencode go 订阅模型选择、opencode 免费模型这里统一整理一下opencode 本身是开源软件不收费你付费的部分是它调用的模型 API。如果你使用 Anthropic 官方 API通常是按 token 计费优点是按量付费、不用预购缺点是大任务跑起来账单容易吓人一跳。如果你使用 OpenAI 系 API也类似。如果你通过第三方中转服务购买订阅制套餐要注意这类服务方不归 Anthropic/OpenAI 官方管理稳定性、数据隐私和合规性都要自己评估。我的建议是日常轻量任务用按量付费控制每次任务的 prompt 规模和上下文长度需要大量生成代码的场景用有预算上限的订阅方案更划算无论哪条路线都在 opencode 里设置 token 消耗提醒避免一次跑飞。免费模型方面Ollama 拉取开源模型如llama3.1、qwen2.5是最常用的方式配合opencode初始化 Ollama provider完全免费但显存要求高。如果不想本地跑几家头部模型服务商也提供免费额度不过配置方式大同小异在opencode.json里添加对应 provider 的apiKey即可。6.4 你迟早会遇到的 Windows/Linux 环境其他小坑中文路径问题项目目录如果有中文部分 Provider 的文件读取可能会出现乱码。遇到奇怪报错时先把项目路径改成纯英文试一试。并发任务冲突不要同时跑两个opencode run它们可能同时修改同一些文件产生难以察觉的交叉覆盖。我习惯在脚本代码里加文件锁或者串行排队执行任务。AGENTS.md 过长问题AGENTS.md 写得太长会占用大量上下文窗口导致模型忘掉你当前对话里的指令。建议把它控制在 200 行以内并且按模块分包到docs/agent/子目录用--agents-dir指向它们需要时再动态加载。版本升级带来的配置变更opencode 处于快速迭代期每一次大版本升级都要看下 release note。社区里出现过配置字段被重命名不兼容的情况升级完先跑一次opencode --version和简单对话确认没坏再继续日常使用。最后分享一个小技巧我用了大概两个月 opencode 之后最大的感受是它不会让程序员失业但真的会淘汰不愿意把需求描述清楚的工作方式。这个工具的价值上限取决于你给它的上下文质量。花十分钟维护 AGENTS.md、写清楚每个模块的约束和约定比在对话里反复纠正模型省力得多。如果你刚开始用不要贪多先把终端 TUI 一个模型 一个 Skill跑顺再逐步解锁 LSP、Playwright 和脚本化集成。等这条路走通了你会发现自己写代码的时间少了审代码的时间多了而后者才是真正值钱的部分。 AI编程代理opencode实战：安装配置、LSP与Playwright集成指南
opencode 最近在 AI 编程圈子里热度起来得很快和 Claude Code、Codex CLI 这类终端型 AI 编程代理放在一起讨论的频率越来越高。如果你已经在用 Cursor 或 Continue 这类 IDE 插件又在琢磨怎么让 AI 更深入地参与整个开发流程opencode 值得花一个周末试试。这篇文章不是官方文档的复述而是结合我和社区里不少人实际跑过的流程把从安装、配置到接手项目、测试前端 bug 的完整链路讲清楚。1. opencode 在 AI 编程工具里处在什么位置1.1 先理清它和 Claude Code、Codex、Cursor 的差别很多人第一次看到 opencode 会下意识拿它和 Copilot 比其实这两类东西定位完全不同。Copilot 是行级补全你写代码它猜下一句而 opencode 属于代理式编程工具它拿到你的需求后自己规划步骤、读写文件、执行命令、跑测试像一个坐在你旁边干活的人。这个品类里目前最知名的是 Anthropic 官方的 Claude Code 和 OpenAI 的 Codex CLI。opencode 和它们最大的区别在于开源和开放性能力维度opencodeClaude CodeCodex CLI模型绑定可接 Anthropic / OpenAI / 本地模型等多家主要绑定 Claude 系列主要绑定 GPT 系列源码可见完全开源闭源闭源IDE 插件官方支持 VSCode、JetBrains官方不提供社区插件为主Skills 扩展支持自定义技能包支持Anthropic 生态支持度一般LSP 集成已支持有限有限一句话概括opencode 是不挑模型、不挑编辑器的通用型终端编码代理。它本身的定位不是某个云服务的专属客户端而是一个可以对接多种模型后端的协调层。1.2 为什么一个终端工具要内置 LSP、Playwright 这些能力热词里出现了 opencode skills、opencode LSP、opencode playwright这三个词其实反映了 opencode 的设计思路一个合格的编程代理光会读文件生成文本是不够的它得能和真实开发环境交互。LSPLanguage Server Protocol集成解决的是读代码的准确度问题。默认情况下agent 是靠关键词搜索和文件遍历来理解代码库的遇到跨文件的类型引用、接口实现就很容易猜错。接上 LSP 之后opencode 可以直接问语言服务器这个函数在哪里定义、被谁调用理解代码的方式和现代 IDE 一样。Playwright 集成解决的是前端 bug 验证问题。传统流程里AI 改完前端代码你得自己打开浏览器点一遍opencode 可以通过 Playwright 启动真实浏览器、模拟点击、截图、收集控制台报错然后把结果回传给模型用于下一轮修复。这个闭环对于跑改一行 CSS 导致布局错乱这类问题特别实用。Skills技能包则是把高频的操作流程封装成可复用的工具集。比如你可以定义一个生成符合仓库规范的组件的 skill里面包含项目目录规范、命名约定、辅助脚本之后 agent 每次创建组件时自动加载这些约束。这三样东西组合起来opencode 就不只是一个聊天机器人套壳而是一套能感知项目上下文、能执行端到端验证的自动化开发环境。2. 安装 opencode从下载到能跑起来2.1 三种安装方式怎么选opencode 官方推荐的安装方式依赖 Node.js要求 20 版本以上可以通过 npm、Homebrew 或者官方安装脚本安装# 方式一npm 全局安装最通用 npm install -g opencode-ai # 方式二macOS 使用 Homebrew brew install sst/tap/opencode # 方式三Linux/macOS 安装脚本 curl -fsSL https://opencode.ai/install | bash我的建议是主力环境用 npm原因有两个。第一npm 包更新频率高新功能比如 LSP 集成总是先发在 npm 上第二卸载和版本回退都方便npm install -g opencode-ai版本号就能切到指定版本。如果日常用 Docker 开发也可以考虑把 opencode 装进容器镜像里随开发环境一起分发团队协作时版本一致性更好。安装完成后执行opencode --version能正常输出版本号说明装好了。2.2 Windows 下无法将 opencode 识别为 cmdlet的修复热词里有一条很有代表性opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错在 Windows 上出现频率很高但原因通常不是 opencode 本身有问题而是 npm 全局包所在的目录不在系统 PATH 里。修复方法分两步。第一步确认 npm 全局安装目录npm config get prefix在 Windows 上通常得到的是C:\Users\你的用户名\AppData\Roaming\npm。第二步把这个目录加入系统环境变量打开设置 - 系统 - 关于 - 高级系统设置点击环境变量在下方的系统变量里找到Path点击编辑新建一行填入 npm 全局目录确定保存。保存后需要重新打开一个终端窗口才能生效。有个小提示PowerShell 里如果修改过执行策略有时还需要先允许本地脚本运行可以查看 Windows 官方执行策略文档按需设置为RemoteSigned这样既能运行 opencode 的启动脚本又不会全放开。2.3 模型 Provider 与 API Key 配置装好二进制文件之后最关键的一步是配置模型服务商。opencode 的配置逻辑和普通 CLI 工具不一样它不直接对接单一厂商而是要求你在配置里指定一个或多个 Provider模型服务商以及对应的 API Key。执行opencode进入交互界面首次启动会引导你配置我更推荐直接手动创建配置文件路径在~/.config/opencode/opencode.jsonLinux/macOS或%USERPROFILE%\.config\opencode\opencode.jsonWindows。最小可用配置长这样{ $schema: https://opencode.ai/config.json, provider: { anthropic: { apiKey: sk-ant-... } }, model: anthropic/claude-sonnet-5 }这里的provider是一个对象键是 Provider 名称值是认证信息。model 字段采用 服务商/模型名 的格式。社区里常见的一个坑是直接写模型名不带服务商前缀导致 opencode 找不到模型。日常使用我建议至少配置两个 Provider比如一个 Anhropic 模型用于复杂重构一个便宜的基础模型用于简单问答这样可以根据任务成本灵活切换不至于每次小改动也消耗高价 token。热词里还有ccswitch 配置 opencode和opencode go 需要配合 cc switch 等工具这里多解释一句ccswitch 是一个用来切换 API 接入点/配置文件的社区工具。我自己的体会是当你有多个 API 服务端、或者需要快速在不同团队项目之间切换 Key 时这类工具确实方便。你只需要在 ccswitch 里维护好不同场景的 API 配置切换完成后确保环境变量ANTHROPIC_BASE_URL、OPENAI_BASE_URL之类的值被正确设置opencode 会自动读取这些标准环境变量。注意不同厂商的模型服务端点格式不一样切换完最好先跑一次简单对话验证连通性避免在编码中途才发现请求全部失败。3. 把 opencode 接入你的工作流3.1 终端交互模式TUI 界面怎么用在项目根目录执行opencode会进入一个基于终端的交互界面TUI。界面底部是输入框可以直接输入自然语言指令比如帮我看看 src/components/button.tsx 这个文件有没有潜在的样式问题。opencode 收到指令后会在右侧面板流式显示当前正在读的文件、正在执行的命令以及模型思考过程。TUI 模式下最常用的几个快捷键CtrlN/CtrlP新建对话 / 切换会话CtrlE打开模型选择器快速切换模型CtrlB查看当前会话的文件变更列表Esc中断当前操作。操作逻辑和主流终端工具一致。交互模式下我建议养成先问再做的习惯也就是让 opencode 先解释它的计划确认无误后再让它动手改代码尤其是改动文件多的任务能让 AI 给出一个变更清单这个习惯能省掉很多返工时间。3.2 非交互模式opencode run 和脚本化如果你想把 opencode 集成进 CI/CD或者批处理任务用非交互模式更合适。基本用法opencode run 检查所有 .ts 文件里的未使用变量并修复run命令之后跟的字符串就是你的 prompt。它会在当前目录上下文里执行任务完成后直接退出中途的详细过程输出在终端里。对于批量任务可以在 prompt 里加约束后缀例如只修复编译错误不要修改业务逻辑能明显降低 AI 顺手优化导致变更范围失控的概率。脚本化场景里一个非常有用的参数是--format可以指定输出格式opencode run 给 login 方法补充单元测试 --format jsonJSON 格式输出里包含生成的文件列表、命令执行记录、token 消耗量很适合写脚本解析。我在团队内部做过一个小工具每晚定时跑一条 opencode 指令扫描遗留 TODO 并生成报告然后通过 webhook 推到团队沟通软件里整个流程全靠非交互模式实现。3.3 VSCode 与 JetBrains 插件的差异热词里 opencode vscode 和 opencode jetbrains idea 插件 的搜索量很高说明很多人都希望在编辑器里直接使用而不是来回切终端。opencode 官方对这两个编辑器都有插件支持但成熟度不一样。VSCode 插件体验更完整因为它底层基于同一套 opencode-server 架构你可以在侧边栏打开一个面向 opencode 的面板看到 agent 执行任务时修改了哪些文件还能直接在编辑器里 diff 变更。JetBrains 插件也支持核心的对话和代码修改但功能迭代相对慢一些主要用ShiftShift打开终端后在 Tool Window 里操作。两个插件都支持将 opencode 作为 MCPModel Context Protocol服务器暴露给 IDE。也就是说Cursor 或 Trae 这类支持 MCP 客户端的编辑器也可以把 opencode 的 Skills、LSP 能力当作外部工具来调用。这个思路特别适合已经有 Cursor 习惯、但又想把 opencode 的 Skills 体系接入的团队——不需要迁移工作环境两边功能并联使用。插件项目里乐器提到的 opencode desktop 暂时还不是官方功能社区里有一些原型如果你在视频平台看到有人演示一个独立的桌面客户端那大概率是个人项目不建议作为主力依赖。目前最稳定的组合依然是终端 TUI 做复杂任务VSCode 插件做轻量交互。4. 实战接手开发项目时的正确打开方式4.1 让 agent 先读代码再动手热词里opencode 接手开发项目不是一个空泛的概念我第一次用它接手一个中等规模的 Node.js 项目时踩过很痛的坑直接让它把订单模块的接口改成带版本号结果 AI 靠着关键词搜索在十几个模块里绕来绕去最终改错了 4 个文件。那次之后我总结出一个可以复用的路径。第一步让模型先建索引。在项目根目录执行opencode run 分析并总结本项目的主要技术栈、目录结构、核心模块及其依赖关系将结果写到 AGENTS.md 文件AGENTS.md 是 opencode 支持的项目上下文文件它会在模型处理任务前自动加载。这个文件写得越准确后续任务的成功率越高。AI 分析完目录结构、包管理器、入口文件、数据库连接方式之后生成的 AGENTS.md 就是项目地图。第二步拆解任务。接手一个项目时不要一次性提一长串需求而是把任务拆成可验证的小步骤。比如目标是给用户模块加导出历史功能拆成分析用户模块当前的 HTTP 路由和数据库表结构设计导出接口的数据结构实现接口和前端按钮运行测试并修复问题。每个步骤之间用CtrlC重启新会话或者让 agent 在上一步基础上继续但确保每个步骤都有明确验收标准。经验是让 AI 一次性写好 500 行代码的风险远大于让它分 5 次每次写 100 行并逐步验证——前面写错还能及时修正后面可以完全偏移。第三步用opencode plan模式。opencode 支持 plan 模式agent 只做分析和规划不实际写文件。在交互界面输入 plan: 分析当前代码库给出实现用户导出历史功能的技术方案它会在终端列出详细的实施步骤、涉及文件清单和潜在风险。确认无误后输入 do it才真正开始修改。4.2 配置 LSP 提升代码检索准确度opencode 的 LSP 集成这几年看了下最新版本已经比较成熟。它能在读代码时借助语言服务器获取类型信息、函数签名、引用关系等可以简单理解为opencode 的搜索不再只是靠关键词匹配而是做到语义级别的文件浏览。启用 LSP 需要在配置文件里打开开关{ experimental: { lsp: true } }我建议启用。实际测试中在没有 LSP 时opencode 理解 TypeScript 项目里某个接口的实现类在哪里这类问题经常答错开启 LSP 后它可以直接通过语言服务器的definition请求定位到实现位置准确率显著提升。有一个配套技巧对于大型 monorepo配置workspace根目录到 LSP 可以提升启动速度避免它把整个仓库都塞进内存{ experimental: { lsp: true, lspRoots: [packages/server, packages/web] } }这样 opencode 只在这两个子目录下启用 LSP搜索其他目录仍用传统关键词方式。如果你的项目是用 Python 写的记得给对应的 Python 目录也配置进去LSP 支持和语言无关关键在于启动对应的语言服务器。5. 用 opencode 排查前端 bugplaywright 场景复盘5.1 让 agent 自己跑浏览器复现问题有一次我遇到一个诡异的前端 bug用户在首页点击立即购买按钮偶尔会出现页面卡死刷新后恢复正常。这种偶发 bug 靠肉眼点半天不一定能复现但是让 opencode 配合 Playwright 自动化测试来复现效率就高很多。我在 opencode 交互界面里输入帮我写一个 Playwright 脚本在本地环境打开首页重复点击立即购买按钮 20 次每次点击后检查页面是否出现未捕获的 JavaScript 异常如果出现截图保存到 /tmp并输出控制台日志。opencode 自动生成了一段 Playwright 脚本然后通过内置的命令执行器运行它。关键点在于脚本运行过程中如果检测到异常它会立刻把截图和 console 日志传给模型。模型就能看到点击第 7 次时控制台出现Failed to fetch /api/order/cart页面卡死这类精确信息然后直接定位到请求拦截逻辑的问题。如果你是初次使用需要先安装 Playwright 相关的依赖包并确保项目里已经有测试环境配置npm init playwrightlatest之后在 opencode 里运行生成 Playwright 脚本就会走浏览器自动化流程。唯一要注意的是 opencode 执行浏览器操作时你的电脑需要满足图形界面环境如果是无头 Linux 服务器需要安装必要的系统依赖库。5.2 打磨可复现的 bug 报告前端 bug 最难的是让别人复现AI agent 也一样。如果你的问题是页面有些卡让 opencode 去排查它大概率无从下手但如果你给它一个 Playwright 脚本它立刻能跑起来并追踪每一步的异常输出。这就是为什么我强烈建议让 opencode 排查前端问题之前先让它生成/维护一个最小复现脚本。我通常的做法是针对经常回归的模块维护一个playwright/manual-repro目录存放一批可以自己跑的复现脚本脚本里只保留触发 bug 的最简路径不依赖复杂登录态、不依赖特定账号数据。当用户报了一个 bug我先让 opencode 在这个目录里找一个最接近的脚本改几个参数去复现复现成功后再让模型看代码、给出修复方案。这样做的额外收益是修复完成后这个复现脚本可以直接转成一个回归测试用例尤其在 CI 里跑一遍防止同一个问题在后续迭代中再次出现。6. 避坑清单我从社区热词里挑出的高频问题6.1 This model is not available in your country 怎么处理这个报错很直接你当前请求的模型服务端在你所在的区域不可用。opencode 本身不做区域限制限制来自上游 API 服务商。处理思路是换用可用的模型或接入点而不是强行绕过限制。我自己的经验是如果你用的是 Anthropic 系列模型但报这个错先检查ANTHROPIC_BASE_URL指向的接入端是否和模型匹配如果你用的是 GPT 系列模型检查OPENAI_BASE_URL和OPENAI_AUTH_TOKEN是否配置正确也可以换用 opencode 支持的本地模型比如 Ollama 或 LM Studio 提供的模型这类模型直接在你机器上运行不存在区域概念。opencode 配置文件里的写法类似{ provider: { ollama: { url: http://localhost:11434/v1, apiKey: ollama } }, model: ollama/llama3.1:8b }本地模型虽然能力不如大厂云端模型但在处理简单重构、补测试、做文本格式化等任务上完全够用而且数据不出机器隐私上也更安心。我的建议是云模型和本地模型各配一个云模型做复杂推理、本地模型做轻量任务这样既能减少区域报错对工作的打断也能控制成本。6.2 unexpected server error. check server logs 的排查思路热词里有这样一条c:\windows\system32opencode error: unexpected server error. check server logs。这个问题我在 Mac 和 Linux 上也遇到过报错隐藏得很深但不难排查只要按顺序检查三层第一层网络与 API 端点。先确认 bash 环境下执行curl请求一下模型服务的健康检查接口看能不能连通。这一步能快速排除网络代理、防火墙、服务宕机的问题。第二层配置文件格式。打开 opencode.json确认 JSON 没有语法错误Provider 名称和模型名称拼写正确。一个小技巧官方配置 schema 很长你可以把配置文件里的$schema字段指到官方在线 schema很多编辑器会自动提示和校验配置项。第三层opencode 服务日志。执行opencode --log trace run ping开启追踪级别的日志报错原因通常会写在输出里。常见的情况包括 token 配额不足、上下文长度超限、某个 API 返回了非预期格式的流式数据。排查时有个我强烈推荐的思路给 opencode 配置一个轻量兜底模型。曾有一次我用 Claude 模型跑一个超大仓库时连续遇到服务端超时把交互界面切换到本地 Ollama 模型后虽然质量下降但任务还是成功跑完。生产环境里模型不稳定是常态提前准备兜底方案远比临时想办法更可靠。6.3 opencode 配置与模型订阅选择建议热词里出现opencode go 套餐、opencode go 订阅模型选择、opencode 免费模型这里统一整理一下opencode 本身是开源软件不收费你付费的部分是它调用的模型 API。如果你使用 Anthropic 官方 API通常是按 token 计费优点是按量付费、不用预购缺点是大任务跑起来账单容易吓人一跳。如果你使用 OpenAI 系 API也类似。如果你通过第三方中转服务购买订阅制套餐要注意这类服务方不归 Anthropic/OpenAI 官方管理稳定性、数据隐私和合规性都要自己评估。我的建议是日常轻量任务用按量付费控制每次任务的 prompt 规模和上下文长度需要大量生成代码的场景用有预算上限的订阅方案更划算无论哪条路线都在 opencode 里设置 token 消耗提醒避免一次跑飞。免费模型方面Ollama 拉取开源模型如llama3.1、qwen2.5是最常用的方式配合opencode初始化 Ollama provider完全免费但显存要求高。如果不想本地跑几家头部模型服务商也提供免费额度不过配置方式大同小异在opencode.json里添加对应 provider 的apiKey即可。6.4 你迟早会遇到的 Windows/Linux 环境其他小坑中文路径问题项目目录如果有中文部分 Provider 的文件读取可能会出现乱码。遇到奇怪报错时先把项目路径改成纯英文试一试。并发任务冲突不要同时跑两个opencode run它们可能同时修改同一些文件产生难以察觉的交叉覆盖。我习惯在脚本代码里加文件锁或者串行排队执行任务。AGENTS.md 过长问题AGENTS.md 写得太长会占用大量上下文窗口导致模型忘掉你当前对话里的指令。建议把它控制在 200 行以内并且按模块分包到docs/agent/子目录用--agents-dir指向它们需要时再动态加载。版本升级带来的配置变更opencode 处于快速迭代期每一次大版本升级都要看下 release note。社区里出现过配置字段被重命名不兼容的情况升级完先跑一次opencode --version和简单对话确认没坏再继续日常使用。最后分享一个小技巧我用了大概两个月 opencode 之后最大的感受是它不会让程序员失业但真的会淘汰不愿意把需求描述清楚的工作方式。这个工具的价值上限取决于你给它的上下文质量。花十分钟维护 AGENTS.md、写清楚每个模块的约束和约定比在对话里反复纠正模型省力得多。如果你刚开始用不要贪多先把终端 TUI 一个模型 一个 Skill跑顺再逐步解锁 LSP、Playwright 和脚本化集成。等这条路走通了你会发现自己写代码的时间少了审代码的时间多了而后者才是真正值钱的部分。