1. 终端里的结对程序员OpenCode 的定位与它真正解决的事1.1 先搞清楚它和 IDE 插件、网页版编辑器的区别很多人第一次接触 AI 编程工具都是从网页版编辑器或者 IDE 插件开始的左边一个对话框右边一个代码区把需求敲进去等它把代码改出来。OpenCode 走的是另一条路——它把整个交互搬回了终端界面长得很像 Vim 或 Lazygit 那种 TUI文本用户界面你依然是在“命令行”里工作但这个命令行里的智能体能自己读仓库、执行命令、改文件、跑测试。从产品形态上说OpenCode 和 Claude Code、OpenAI Codex 是同一类东西业内叫 AI 编码智能体Agent不是简单的“代码补全工具”。它和你写提示词让 ChatGPT 给一段代码最大的区别是它能拿到你项目的完整上下文能运行 shell 命令能真实地落盘修改文件能把一次修改跑通验证后再交付给你。那为什么不干脆用 IDE 插件几个原因。第一是速度终端启动快、占用小服务器上也能用SSH 到一台开发机就能干活第二是可控性所有改动、命令、日志都留在终端会话里可回放、可存档第三是自由度它不绑定任何一家模型厂商你自己有 API key 或者本地模型接上就能用。从我的实际体验来说OpenCode 适合那种“已经在命令行里工作了一整天”的开发者你不需要从一个图形界面切换到另一个图形界面。1.2 什么项目适合用 OpenCode 把活干完它不是万能药我试过在几种典型场景下用得很顺手也有场景确实不合适。先说合适的方向接手一个陌生仓库时让它先梳理架构比人肉看代码快得多做跨文件重构时它能在多个文件里同步修改前端 bug 排查时它能自己启动浏览器复现问题写测试这种体力活它能稳定地产出可运行的用例。对于 Go、TypeScript、Python 这类生态成熟的语言配合 LSP 能力它的表现会超出预期。不太合适的场景也有完全不懂命令行的新手我还是会劝你先从 IDE 插件上手公司有严格的数据合规要求、不允许把代码发到外部模型服务时你就得接本地模型或者私有化部署的模型服务这个后面会展开还有一些特别冷门、文档稀少的框架模型训练数据里没见过它和你一样会两眼一抹黑。1.3 核心能力速览能力说明我的使用频率多模型接入支持 Anthropic、OpenAI、Gemini、Ollama 等可自定义 Provider每次会话TUI Headless 双模式终端交互界面也能用opencode run跑脚本每天LSP 接入借助语言服务拿到符号、跳转、诊断信息开项目必用Playwright 集成让智能体自己操作浏览器复现前端问题修前端 bug 时Skills 技能包用 SKILL.md 给智能体定义可复用的工作流程团队沉淀会话存档每次会话可恢复、可导出适合留痕长期项目必备IDE 插件官方/社区提供 VSCode、JetBrains 扩展看 diff 时用这张表我后面每一行都会展开讲尤其是 LSP 和 Playwright 这两个能力属于“用了就回不去”的类型。2. 把安装踩坑一次说透环境准备、报错排查和第一句指令2.1 基础环境Node、终端和 Windows 用户的特殊问题OpenCode 的安装方式一直在迭代我建议直接看官方 README因为命令更新频率挺高。我本地最常用的还是官方 curl 脚本curl -fsSL https://opencode.ai/install | bash装完之后opencode会装到用户目录下通常是在~/.opencode/bin或者~/.local/bin。如果 shell 提示找不到命令先别急着重装大概率是 PATH 没加载export PATH$HOME/.local/bin:$PATHWindows 用户在 PowerShell 里遇到的报错应该就是热搜里那条“opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这个报错的根因基本就三类Node.js 没有正确安装或者安装时没勾选“Add to PATH”npm 全局安装目录不在 PATH 里安装完成后终端没重启新的 PATH 没生效。排查顺序我建议这样先运行node -v和npm -v确认 Node 环境再看npm config get prefix拿到的目录最后把这个目录加到 PATH 环境变量里。如果之前是旧版本升级上来的顺手清理一下%APPDATA%\npm里残留的旧文件有些诡异问题就是新旧版本文件冲突。另外提醒一句如果你平时用 Windows Terminal Git Bash会比纯 PowerShell 省心一些要是开发环境跑在 WSL 里直接在 WSL 内安装使用是最顺滑的别在 Windows 侧硬较劲。2.2 首次启动和第一轮对话的正确姿势装好之后进到你的项目根目录直接运行opencode。首次启动会进入 TUI 界面它会引导你配置模型服务商。我没有账号相关配置时是先接的本地模型体验的后面第三节会讲具体配置方法如果你手里有 Anthropic 或 OpenAI 的 API key也可以直接用opencode auth login登录。第一句指令我强烈建议不要上来就让它改功能先让它“认路”。我会这么说先不要修改任何代码。请阅读 README 和项目主要目录给我一份模块结构说明标注出核心模块和它们之间的依赖关系。这一步的作用是让智能体建立项目地图同时你也能从它的回答判断它对这个技术栈熟不熟。此时你要观察它列出的文件是否准确如果它连项目入口都找错了后面的大改动就别指望了。热搜里有一条“opencode 如何导入一段程序代码并进行修改完善”这个我实测最顺手的做法不是复制粘贴大段代码到对话框——那样容易丢缩进、也容易让它丢失对项目环境的感知。正确姿势是把代码片段保存到项目里的一个临时文件比如/tmp/example.ts然后这样下指令请阅读 /tmp/example.ts这段代码目前的问题是 X我需要你把它改造成 Y。改完先不要写回原文件把完整的新版本输出给我。用引用文件路径它就能精确地读取内容同时不会污染项目目录。等确认方案没问题再让它直接修改目标文件。2.3 项目级配置文件的骨架OpenCode 的项目级配置文件是opencode.json部分版本也支持opencode.toml以你安装版本的文档为准。我的最小可用配置长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, provider: { ollama: { npm: ai-sdk/ollama, name: Ollama (Local), options: { baseURL: http://localhost:11434/api }, models: { qwen2.5-coder:7b: { name: Qwen 2.5 Coder 7B } } } } }这里model字段写默认模型provider下面可以注册你自己的模型服务商。一个很重要的经验永远不要在配置文件里明文写 API key而是用env:YOUR_KEY_NAME这种形式去读环境变量。我见过不止一次有人把 key 直接提交到 Git 仓库里然后被自动化扫描工具抓出来告警这个坑能躲就躲。3. 模型接入和 token 花费怎么平衡Provider 配置与本地模型实测3.1 从 API Key 到 Provider连接不同模型服务商OpenCode 的模型接入思路是“Provider 抽象层”它底层基于 AI SDK你可以把任意一个兼容 OpenAI 接口的服务商配置进来。常见的大模型服务商官方基本都内置好了只要设置好对应的环境变量就能用export ANTHROPIC_API_KEYsk-ant-... export OPENAI_API_KEYsk-... export GOOGLE_API_KEYAI...如果你的模型服务商不在内置列表里就手动在opencode.json里配置一个自定义 Provider比如用 OpenAI 兼容格式{ provider: { mycompany: { npm: ai-sdk/openai-compatible, name: My Company Models, options: { baseURL: https://api.example.com/v1, apiKey: env:MY_COMPANY_API_KEY }, models: { my-fast-model: { name: Fast Model } } } } }配置好之后在 TUI 里按快捷键或者输入模型切换命令就能在多个模型之间切换。我的习惯是做架构分析、大范围重构时用最强模型批量做一些简单机械的修改时切到便宜快速的模型这样整体费用能下降一大截。3.2 本地模型是被低估的一条路热搜里有“opencode免费模型”大部分人的第一反应是找网上的免费接口但我更推荐你试试本地模型。原因很简单数据不出机器、没有按量计费、请求无限。用 Ollama 跑一个 Qwen 系列的 Coder 模型配置就和 2.3 节那个示例一样在 Provider 里加一个 Ollama 入口就行。实测下来7B 到 14B 量级的本地模型能做这些事解释代码逻辑、写单元测试、做 diff review、按照明确的规范修改样式。但你要是让它做跨十几个文件的复杂重构它大概率会丢上下文甚至会自信地给出错误的 API 调用。所以本地模型更适合当“廉价劳动力”不适合当“架构师”。硬件条件上MacBook Pro 的 M 系列芯片跑 7B 模型基本流畅16G 内存是底线如果只有 CPU 没有 GPU速度会慢到我没什么耐心。另外启动 Ollama 后要记得先把模型拉下来ollama pull qwen2.5-coder:7b然后再启动 OpenCode让它连接http://localhost:11434/api。3.3 省 token 的几个实操细节用云端模型最怕的就是 token 哗哗流走我总结了四个亲测有效的控制手段。第一善用 ignore 规则。OpenCode 默认会忽略node_modules、.git、dist这类目录但如果你的项目里有体积巨大的生成文件、日志文件、二进制资源一定要把它们加进忽略列表否则它扫描文件时会浪费大量上下文。第二用精确指定上下文范围。不要让它“看一下整个项目”然后自己去翻你自己心里清楚问题出在哪个目录就明确告诉它。比如src/utils/format.ts它读取的文件越少留给推理的上下文就越多答案质量越高。第三阶段性压缩会话。聊了二三十轮之后历史记录会占用大量上下文此时用/compact命令把之前的对话压缩成摘要能立刻释放空间。这个操作看起来简单但对长任务的连续性帮助很大。第四大文件不要反复读。如果你已经让它把某个文件读到上下文里了后续提醒它“刚才那个文件里有个函数叫 X”它会直接从已有上下文里找而不是重新读一遍。养成这个习惯之后token 消耗能明显下降。4. “看懂”仓库这件事LSP 接入、AGENTS.md 与接手旧项目4.1 接手旧项目前先让它写一份“项目地图”如果你被丢到一个陌生的仓库别急着让智能体改需求先花二十分钟让它生成项目地图。我会用 headless 模式跑一条指令opencode run 阅读项目入口文件和关键配置输出一份 ARCHITECTURE.md内容包括模块划分、启动方式、核心数据流、现有测试策略。不要修改任何源码。它会自己扫描目录、读配置、梳理模块关系然后生成一份文档。我拿这份文档当基础再补上我看到但智能体没捕捉到的业务背景最后把修正版提交进仓库。这个文件对新加入项目的人非常有价值相当于把“项目里最资深的开发者的脑内地图”落在了纸面上。还有一个我觉得比 README 更重要的文件AGENTS.md。这是给 AI 看的项目说明书写在仓库根目录里面约定“这个项目的命令习惯是什么”“哪些目录绝对不能动”“测试怎么跑”。有了它以后每次启动 OpenCode智能体都会先读到这份约定行为会规矩很多。如果当前版本支持/init命令可以直接让它基于仓库现状生成一个初始版你再手动补充团队规范。4.2 接入 LSP 之后AI 像长了眼睛LSPLanguage Server Protocol本来是为了给编辑器提供“跳转定义、查找引用、诊断错误”等能力OpenCode 把它接给了智能体。这意味着 AI 不再靠“字符串匹配”理解代码而是能真正拿到编译层面的符号信息。举个例子我让它把某个工具函数从一个文件移到另一个文件同时更新所有调用方。没有 LSP 的时候它偶尔会漏掉某个动态导入的调用路径我得自己再查一遍接入 LSP 后它移动完文件会主动查“引用”然后发现遗漏的 import 并修正。对它来说这就像多了一双能看到“代码真实依赖关系”的眼睛而不是靠猜。如果你的某个语言 LSP 没生效先别赖 OpenCode大概率是本地缺少对应的 language server。Go 项目需要goplsPython 项目需要pyrightTypeScript 项目需要typescript-language-server先用各语言的包管理器装好。比如 Gogo install golang.org/x/tools/goplslatest然后再重新启动 OpenCode它通常能自动探测到新装的 LSP。4.3 高频命令和会话工作流我日常在 TUI 里用到的命令不算多但都很关键。/help查看当前版本支持的所有命令/compact压缩上下文/new开启新会话但保留当前项目上下文。接手旧项目时我习惯为每个大任务开独立会话读代码一个会话改代码一个会话跑测试验证再一个会话。这样每个会话的上下文都很干净不会互相干扰。headless 模式更是脚本党的福音opencode run review 当前 git diff指出潜在 bug 和风格问题这条命令可以直接接在 CI 流程里也可以配合git diff | opencode run -做管道输入。比如每次提交代码前我先在终端跑一遍这个 diff review它能用很低的成本帮我挡掉不少低级错误。注意 headless 模式默认没有 TUI 那种交互确认所以它执行命令时会更激进建议在配置里把危险命令比如git push、rm -rf放进禁止列表。5. Skills给智能体装上“职业素养”和团队规范5.1 SKILL.md 的基本结构与加载路径Skills 是 OpenCode 里我非常喜欢的一个机制简单说就是给智能体定义“遇到某类任务时按这个流程来”。每个 Skill 是一个目录里面有一个SKILL.md文件描述这个技能的触发条件、执行步骤、注意事项还可以附带脚本和模板。加载路径一般是用户级的~/.config/opencode/skills或者项目级的.opencode/skills后者跟着仓库走天然适合团队共享。一个最小的SKILL.md长这样--- name: code-review description: 当用户要求审查代码时执行此技能 --- - 先运行 git diff 获取改动内容 - 关注安全性、错误处理、可读性、性能 - 对每个问题给出文件和行号 - 最后按严重程度分级输出关键在于 frontmatter 里的descriptionOpenCode 会把它作为“何时调用这个技能”的依据。所以描述要写清楚适用场景不要用“处理代码”这种废话要写“当用户要求审查代码、做 code review、检查 pull request 时”。5.2 一个前端设计开发一体 Skill 的完整模板热搜里有一条“opencode 前端设计开发一体的skill”我正好沉淀了一个团队内部在用的版本。它的目的是让智能体在开发前端组件时遵循同一套设计规范和验证流程避免每次交出来的 UI 风格五花八门。我建议的SKILL.md结构如下你可以直接抄去改--- name: frontend-component-dev description: 开发或修改前端组件时使用。要求遵循设计令牌、响应式规范并用 Playwright 截图验证。 --- ## 设计规范 - 颜色使用项目设计令牌见 styles/tokens.css - 组件需适配 375px、768px、1280px 三档宽度 - 所有交互元素必须支持键盘操作 ## 执行流程 1. 阅读组件相关源码和现有样式 2. 按设计规范实现组件 3. 启动开发服务器 4. 用 Playwright 打开组件所在页面分别在三档宽度截图 5. 检查截图是否符合规范不符合则继续修改直到通过 6. 输出改动摘要和截图路径这个 Skill 的精髓不是给 AI 讲大道理而是把检查项变成可执行的动作——截图、分档位验证、对比规范。有了这套流程AI 每次开发完组件都会真的启动浏览器看效果而不是“我觉得应该没问题”。5.3 从 oh-my-claudecode 等项目借技能社区里有很多现成的 Skills 可以借鉴比如 oh-my-claudecode 这类项目原本是为 Claude Code 做命令管理和技能集成的。我的建议是可以大胆借鉴里面的SKILL.md写法和流程设计但不要直接整个搬进 OpenCode因为两个项目的插件机制、配置加载路径、工具权限模型不一样直接套用大概率会出一些莫名其妙的问题。我看到 OpenCode 用户经常在社区里讨论怎么把 Claude Code 生态里的 skills 迁移过来。实际做法通常是把 SKILL.md 拷贝到.opencode/skills目录然后删掉所有依赖 Claude Code 特定命令的步骤改成通用的 shell 命令。迁移完一定要实测一遍看智能体能不能在 OpenCode 里顺利走完整个流程不要迷信“能加载就是能用”。6. Playwright 实测让 AI 自己把前端 Bug 修完6.1 为什么要用浏览器自动化而不是只让 AI 读代码修前端 bug 最大的痛苦在于代码和人看到的页面之间存在一层“运行时复杂性”。组件 A 报错原因可能在父组件 B 的某个状态没传对而这种跨文件的运行时问题静态读代码很难发现。OpenCode 接入 Playwright 后智能体可以自己打开浏览器、点击按钮、收集控制台报错、截图然后根据真实运行结果去定位代码问题。这个模式的关键是“反馈闭环”。AI 改完代码后它不需要等你去验证而是自己重新打开页面再跑一遍流程如果问题还在就继续修直到控制台干净了才交付给你。我在实际项目里用这个方式处理过不少“点击按钮没反应”“弹窗位置不对”“某个功能在移动端样式错乱”的问题效率比我自己手动复现高很多。6.2 一次完整排查链路从描述到修完下面是一条我常用的 prompt 模板可以直接套用用 Playwright 复现并修复这个前端 bug 1. 启动开发服务器npm run dev 2. 打开 http://localhost:5173/page 3. 点击“提交”按钮 4. 收集控制台报错并截图 5. 根据报错分析原因修复 src/components/SubmitButton.tsx 6. 修完后再跑一次同样的流程确认控制台无报错并再次截图智能体会按照这个流程拆解动作。我观察到的执行顺序大致是步骤智能体的行为我如何确认启动环境运行npm run dev检查端口是否可访问看终端输出打开页面用 Playwright 访问目标 URL等待页面加载等待截图出现复现问题定位按钮元素点击捕获 console 和网络错误看控制台报错分析定位结合 LSP 和文件内容找到疑似根因看它引用的代码修改代码编辑目标文件尽量最小改动看 diff回归验证重新打开页面点击确认问题消失看第二次截图这个闭环跑完之后我一般还会补一句“把修改的 diff 给我并说明为什么这样改”。这样既能审计它的改动也能从中学到一些自己没想到的思路。6.3 权限、超时和登录态的几个坑Playwright 集成虽然强大但不是零成本我踩过几个坑值得说一下。第一是浏览器内核下载。首次使用 Playwright 前大概率需要手动装一次 Chromiumnpx playwright install chromium不装的话智能体运行测试脚本时会报找不到浏览器。这个问题在 CI 环境里尤其常见我通常会在项目的AGENTS.md里写一句“首次运行请先执行 npx playwright install chromium”。第二是权限确认。OpenCode 在 TUI 模式下执行命令前会征求确认对危险命令很谨慎。如果你确认某个命令绝对安全可以在配置里加入白名单省得每次弹窗打断节奏但也就意味着智能体以后可以无确认执行这条命令所以白名单一定要收紧。我的原则是允许npm run dev、npm test这类只读或本地只写命令禁止一切可能影响远端状态的操作。第三是登录态问题。很多页面的 bug 需要登录之后才能复现而 Playwright 默认的浏览器上下文是干净的。如果你碰到“页面一直跳转登录页”的情况可以让 Playwright 加载一个已保存的浏览器 profile或者先手动登录一次并把 cookie 持久化到本地文件然后在 prompt 里告诉智能体“使用 /tmp/profile 作为用户数据目录启动浏览器”。这属于偏高级的用法但一旦用上能排查的问题范围会大很多。7. 桌面版、VSCode/IDEA 插件和团队落地经验7.1 桌面版和 IDE 插件的正确使用姿势关于“opencode桌面版”我的看法是如果你已经习惯 TUI桌面版不是必需品如果你是团队里被“命令行恐惧”支配的成员桌面版能降低上手门槛。底层核心还是同一个只是外壳不同。VSCode 插件和 JetBrains IDEA 插件的价值我认为在于两点更方便地看 diff以及把 AI 的输出直接嵌入编辑器。终端里改完代码后我会习惯性地用 IDE 打开差异视图逐处检查检查没问题再提交。插件里的“选中代码右键发送给 Agent”功能在处理局部问题时很顺手不用为了一个小问题单独跑一遍完整会话。但我也要泼一盆冷水插件不是魔法它只是 OpenCode 的一个前端入口。如果你在终端里用不顺装了插件大概率也不顺。关键还是先把模型、LSP、Skills 这些基础配置搞对。7.2 把 AGENTS.md 和 Skills 放进 Git 仓库团队落地 OpenCode我最推荐的做法是把项目相关的资产直接提交进仓库AGENTS.md项目规范、常用命令、禁止操作.opencode/skills/团队沉淀的各类技能包opencode.json统一的项目级配置去掉 API key。新成员 clone 项目之后装好 OpenCode 就能直接用不需要手动调一堆配置。我们团队内部已经把这个流程跑了小半年效果很稳定。无论是谁用 OpenCode 改代码出来的风格都符合项目约定因为他一进项目就自动读到了这些约束。在 CI 里的落地方式也一样跑一个 headless 的 diff review 任务每天自动检查 PR输出的 review 结果直接贴在 PR 评论里。不要让它自动合并代码它只负责发现问题决策权还是在人手里。7.3 我踩过的几个真实坑最后分享几个不写在官方文档里的坑。第一个是 API key 泄露。我前面提过再强调一次所有 key 一律用环境变量引用配置文件里只写env:XXX。最好给 CI 和本地用不同的 key方便单独吊销。第二个是“AI 自信删代码”。有一次它认为某个工具函数没有被引用就直接删了结果那个函数是被动态导入的运行到对应功能时才炸。现在我的opencode.json里会把src/generated、scripts/archive这类目录加进禁止修改列表并且明确规定“处理引用关系前先做全局搜索确认”。第三个是长会话的“慢性污染”。一个会话里如果连续换了好几个任务后面的回答质量会肉眼可见地下降因为它上下文中积累了太多无关内容。遇到这种情况别硬扛/compact一次或者干脆/new开新会话成本很低收益却很大。第四个是免费模型接口不稳定。我理解大家想找免费资源但如果你跑的是真实项目我建议优先用本地模型或者正规的模型服务商哪怕花点钱。把时间浪费在调试不稳定的接口上远比 token 费用更贵。信息差这个东西终究是要还的。用了一年多 OpenCode我最深的体会是真正能提升效率的不是某个特别强的模型而是你沉淀下来的“项目资产”——AGENTS.md 里写的规范、Skills 里定义的流程、LSP 和 Playwright 搭好的验证闭环。这些东西不随模型升级而失效才是团队最值得投入的部分。你换一个模型它照样工作你换一个人它照样能快速上手。把它当成一个可以持续进化的“团队成员”而不是一个临时凑合的代码生成器你很快就会感受到它的价值。如果你刚开始接触 OpenCode建议从一个小项目开始先让它读代码、写测试、修一个简单的 bug跑通一次完整闭环。等你熟悉了它的工作方式和脾气再逐步放权。工具是死的但你和它配合的节奏是可以慢慢养出来的。