1. opencode 是什么：为什么最近大家都在把 AI 编程工作流往它身上迁
opencode 最近在终端 AI 编程这个圈子里刷屏的频率，已经高到没办法忽视了。它本质上是一个开源的、跑在命令行里的 AI 编程助手：你在终端里敲一句自然语言需求，它会自己拆任务、读项目、改代码、执行命令、跑测试，整个过程就像多了一个能随时支使的结对程序员。和 Claude Code、Codex CLI、pi 这些同类工具放在一起看，opencode 最核心的差异是"模型无关"——它不绑死某一家模型服务商，而是通过统一的 provider 机制接入 OpenAI 系、Anthropic 系、Google 系、国产模型，甚至本地模型。这意味着你完全可以今天用 A 家的模型干活，明天切到 B 家，不需要重新学一套工具。
很多人第一次听说 opencode 时会有一个困惑：它到底是哪家公司的？这是个非常合理的疑问，因为市面上有两个叫 opencode 的项目。早期那个是 SST 团队做的、已经不再维护的旧项目；现在大家讨论的、热搜里这个，是 opencode-ai 这个开源社区项目。两者没有继承关系，只是撞了名字。如果你在 GitHub 上搜 opencode 的时候看到仓库状态还停留在两三年前，那基本就是找错仓库了。认准 opencode-ai 这个关键标识，后面的一切讨论都以它为准。
它解决的核心问题是"重复劳动"。举个例子：接手一个别人留下的中型项目，传统流程是先读 README、梳理目录结构、找入口文件、理解构建脚本，然后才能开始改需求。这个过程快则半小时，慢则一上午，而且全是机械操作。用 opencode 的话，我通常直接一句"先帮我看懂这个项目，告诉我入口在哪、怎么跑起来、主要模块之间什么关系"，它会把文件读一遍，给我一份带依据的梳理结果。省下来的时间不是一点半点。
这个工具适合谁？如果你已经在用 Claude Code 或 Codex CLI 这类终端 Agent，那 opencode 是值得对比体验的替代方案；如果你还没接触过终端 AI 编程，只想找一个能接各种模型、不被单一厂商绑定的入口，那它同样是目前门槛最低的选择之一。下面我会把从安装、配模型、到核心功能实战、再到接手工地的完整过程拆开讲，包括我踩过的坑。
1.1 终端 Agent 的"对话式开发"到底是怎么运作的
opencode 在终端里建立的是一个循环：你给自然语言指令，它把指令拆成若干步骤，然后通过一系列内置工具去执行——读写文件、执行 shell 命令、做模糊搜索、调用 LSP 拿代码诊断。每执行一步，它会把结果拿回来作为下一步的上下文，然后继续推进，直到任务完成或者它发现自己搞不定需要向你确认。
这个"循环"和你在 ChatGPT 网页里一问一答有本质区别。网页对话是"说给 AI 听"，AI 给你建议，你手动去改代码；opencode 是直接把操作权限交给 AI，它自己动手改，改完你去 review。所以这里也引出一个非常重要的使用习惯：永远不要把 opencode 当成一个自动写代码的机器人，而要当成一个需要你先交代清楚边界、再检查它成果的临时同事。权限越大，越是需要 review 纪律。我见过太多人第一次用就让 Agent 全自动改完一个模块，然后代码库就出问题了。这个工具的正确打开方式是"人在回路"，而不是"人走开"。
1.2 和 Claude Code、Codex CLI、pi 的横向对比
| 工具 | 开源 | 模型绑定 | 编辑器插件 | LSP | 浏览器自动化 | 上手门槛 | |---------------|------|----------|------------|-----|--------------|----------| | opencode | 是 | 无 | VS Code/IDEA | 支持 | 支持 | 中低 | | Claude Code | 否 | Anthropic 系 | 一般 | 有限 | 有限 | 低 | | Codex CLI | 部分 | OpenAI 系 | 一般 | 有限 | 有限 | 低 | | pi | 是 | 无 | 少 | 部分 | 部分 | 中 |说几个实测下来比较直观的感受。Claude Code 胜在默认模型本身的能力很强，开箱即用体验成熟，但代价是模型绑定严重、费用也比较可观；Codex CLI 同理，和 OpenAI 体系贴合度最高，但一旦你想用别的模型就费劲了。pi 比较轻量，适合简单任务，复杂项目里上下文处理能力明显弱一截。
opencode 的定位恰恰是"中间派"：它不跟任何模型绑定，又提供了足够的工程化能力。代价是配置复杂度比 Claude Code 高——模型、密钥、LSP、浏览器工具都得你自己搭。这也解释了为什么热搜里 "opencode 配置""opencode 安装教程""opencode 使用教程" 会出现这么高的频次：它不是装完就能躺平的工具，前半小时的配置成本是省不掉的，但换来的是长期的模型自由。
2. 从零装好 opencode：Windows 报错与 Linux 配置文件那些事
安装这块，网上乱七八糟的信息特别多，我先给一个可以直接抄的版本。官方主推的有三种方式：npm 全局安装、brew 安装、以及官方安装脚本。
# macOS / Linux 用 brew brew install opencode # 任意平台只要装了 Node.js 18+ 就能用 npm npm install -g opencode-ai # 官方安装脚本（Linux 较常见） curl -fsSL https://opencode.ai/install | bash我个人的建议是：机器上有 Node 生态就优先走 npm，因为后续升级、看版本号都统一；macOS 上走 brew 也完全没问题，两个源的更新节奏几乎同步。装完之后用opencode --version验证一下，能输出版本号就说明核心程序已经落盘了。
这里需要注意一个很坑的细节：npm 上的包名带-ai后缀，是opencode-ai，不是opencode。opencode这个包名大概率属于那个已经停止维护的旧项目，装错的话你会拿到一个完全不一样的东西，然后各种功能对不上。我一开始就踩过这个坑，排查了半天才发现装错了包。看到"无法将 opencode 项识别为 cmdlet"这种报错时，先确认一下装的到底是不是 opencode-ai。
2.1 Windows 下 "无法将 opencode 项识别为 cmdlet" 的根源与修复
这是 Windows 用户碰到频率最高的报错，整句是这样的：opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。字面意思很好懂：PowerShell 在当前 PATH 环境变量里找不到叫 opencode 的可执行文件。但为什么明明 npm install 成功了，PowerShell 还是找不到？
根源在于 npm 全局安装的可执行文件放到了 npm 的全局 bin 目录里，而这个目录没有被加入 PATH。在 Windows 上，这个目录通常是%APPDATA%\npm。你可以手动验证一下：
npm config get prefix执行后会输出一个路径，npm 全局命令的可执行文件就放在这个路径下的 Node.js 同名目录里。如果这个路径不在系统 PATH 里，PowerShell 就永远找不到它。
修复方式有两种。第一种是打开"系统属性 -> 环境变量 -> 编辑 Path"，把%APPDATA%\npm手动加进去，然后重启终端。第二种更省事：直接用 nvm-windows 管理 Node.js 版本，nvm 装的 Node 会把全局 bin 目录自动写进 PATH，后面装任何全局工具都少折腾。
还有一个冷门但真实存在的情况：即使 PATH 正确，如果当前 PowerShell 会话是在修改 PATH 之前打开的，它也不会自动刷新。遇到这种情况不用慌，关掉终端重新开一个就好。
2.2 Linux 下修改 opencode 配置文件的正确姿势
Linux 用户遇到的更多问题集中在"改 JSON 配置"上。opencode 的配置分成两层：项目级配置opencode.json放在项目根目录，只对当前项目生效；全局配置放在~/.config/opencode/opencode.json，影响所有项目。全局配置适合放 API 密钥、默认模型这些通用项，项目配置放模型、LSP 设置、插件启用这些跟着项目走的项。
修改配置之后，如果是在终端里运行，重启 opencode 会话即可生效；如果你用的是 VS Code 插件，需要在插件面板里重新加载窗口。Linux 下常见的疑问还有一个：配置文件改了为什么没反应。多数原因是 JSON 格式错误——少个逗号、多了一个尾逗号、注释残留，这些在严格 JSON 解析器里都过不去。我建议改完先跑一遍opencode doctor或者直接打开opencode 设置菜单看是否有报错提示，而不是反复重启然后怀疑人生。
3. 模型接入是重头戏：免费模型、opencode go、cc switch 这类网关工具怎么搭
装好只是开始，真正决定 opencode 好不好用的是模型接入。这也是热搜里密度最高的需求点："opencode 免费模型""opencode go 订阅模型选择""opencode go 套餐""opencode 接入 superpower""ccswitch 配置 opencode"。
opencode 的模型接入走的是 AI SDK 的 provider 架构。你要做的核心事情就两件：第一，告诉 opencode 某个模型的接口地址和密钥；第二，给这个模型起个名字方便选择。经典配置长这样：
{ "$schema": "https://opencode.ai/config.json", "model": "my-qwen", "provider": { "openai-compatible": { "options": { "baseURL": "https://api.example.com/v1", "apiKey": "sk-你的密钥" }, "models": { "my-qwen": { "name": "通义千问 Coder" } } } } }注意这里openai-compatible是关键——几乎所有主流模型服务商都提供 OpenAI 兼容接口，所以只要你拿到的服务商有/v1风格接口，都可以用这个方式接入。模型名my-qwen只是本地别名，真正的模型路由由服务商那边决定。
写完之后，在 opencode 交互界面里输入/models就能看到你配置的模型列表，按方向键切换。这也是 opencode 比 Claude Code 舒服的一个地方：切换模型不用改代码改配置，界面里一键换。
3.1 免费模型：有，但把预期放低一点
"opencode 免费模型"是高频搜索，说明大家对白嫖这件事还是有刚需的。实际情况是：opencode 本身不提供模型，免费模型取决于你接的服务商。本地跑 Ollama 的话，qwen2.5-coder、deepseek-coder 这些开源模型都能用，效果在小任务上完全能打；社区里也有人分享各种免费 API 端点，但这类东西起起落落，稳定性没法保证。热搜里"opencode hy3-free 下线了吗"问的就是这类社区免费端点的存亡问题——我的态度很明确：可以玩，但别把生产环境压在上面。免费端点通常有速率限制，而且随时可能停，真干活的时候还是得靠正式订阅或者自己有 key 的服务商。
本地模型的配置比远程模型多一步：你不需要 API key，但需要确认 Ollama 服务在跑，并且模型已经拉取到本地。然后 provider 类型用ollama，模型名写你本地拉取的名字就行。实测体验是：代码理解、注释补充、单测生成这类任务，本地小模型也能给出可用的结果；但涉及跨文件重构、复杂架构调整，本地模型和头部商业模型差距还是很明显。建议本地模型用于日常轻量任务，重活交给商业模型。
3.2 opencode go 和 cc switch：订阅聚合与配置切换的经验
热搜里的 opencode go，说的是面向 opencode 用户的一类订阅服务/聚合网关：你买它一个套餐，它会给你一个统一的 API 入口，入口背后可以路由到多个主流模型。这类服务的价值在于"一个套餐、一个密钥、多个模型"，对不想同时维护好几家账号的人很方便；cc switch 则是本地配置切换工具，把不同服务商的接口地址、密钥、模型名分别存成配置档，用的时候一键切换。
实际的配合方式大概是：你在 cc switch 里建好"服务商 A 配置""服务商 B 配置"两个档位，每个档位对应不同的 baseURL、apiKey 和模型列表；切档之后，opencode 里对应的环境变量或配置也随之变化。对同时使用多个模型服务商的人来说，这套流程比每次手动改 opencode.json 优雅很多。
但这里我必须给一个实在的提醒：凡是涉及聚合网关、转发服务的东西，挑选时要把"稳定性和服务商信誉"放在第一位。我见过不少人是看着便宜套餐上的车，结果用了两周服务商跑路，key 全废。建议先小额试用、观察一段时间，再决定是否年付。另外，聚合网关一般都会在多租户环境下共享 IP，对延迟敏感的任务可能受到影响。能用官方直连的模型，优先官方直连。
3.3 "this model is not available in your country" 到底怎么处理
这个报错应该是热搜里最让人抓狂的一条，尤其是后面还跟着 "muse spark 1.3 fr" 这种模型名。其实这个错误信息已经说得很清楚了：当前配置的模型在你这片区域不被服务商授权使用。这跟 opencode 本身没关系，是上游 API 服务商按照区域许可做的限制。
处理思路就三条：第一，把模型切换成同一个服务商下对当前区域开放的模型，这是最省事的办法，/models里看看有没有备选项；第二，换一个明确支持你所在区域的服务商，很多国产模型服务商对国内区域的支持就非常完整；第三，确认你用的套餐是否包含该模型的区域权限，有时候是套餐档位不够，而不是模型本身被禁。核心原则是：不要在报错之后反复重试同一个模型，那只是在浪费时间。直接换模型或换服务商，五秒钟就能解决问题。顺带说一句，这类错误也会出现在免费端点身上，因为免费端点背后的上游本来就有地域限制，所以看到这个报错时先检查服务商的区域说明，比在网上到处搜"怎么绕"有效得多。
4. 拉开体验差距的核心功能：Skills、Memory、LSP、Playwright
模型接入解决的是"AI 聪不聪明"的问题，而核心功能解决的是"AI 好不好用"的问题。同样是接同一个模型，有人用 opencode 用得行云流水，有人觉得它就是个高级版自动补全，差别就在这四块：Skills、Memory、LSP、Playwright。
4.1 Skills：把可复用的能力封装成"技能"
我先讲一个直观的场景。假设你经常需要给项目里的每个 API 接口写一个错误处理包装：读文件、生成代码、跑测试、修 lint。这个过程有固定套路，但每次都让 AI 从头摸索一遍，质量和效率都不稳定。Skills 就是用来解决这个问题的：把一段可复用的操作流程、约束和示例封装成一个"技能"，之后一句话就能让 AI 按这套流程执行。
在 opencode 里，Skills 通常以 Markdown 文件的形式定义，里面写清楚这个技能在什么场景下触发、需要哪些上下文、执行步骤是什么、有哪些禁忌。相当于给 AI 一本"岗位 SOP"。社区里很多人把我的世界里的 superpowers 这类技能库移植到 opencode 上来用，所以你会看到"opencode 接入 superpower"这种热搜。实际体验下来，一个写得好、描述清晰的 Skill，比每次对话时临时交代一堆要求要稳定得多，特别适合团队标准化开发流程。
我的建议是：不要一开始就想搞一个覆盖所有场景的大技能库，先把手头重复三次以上的任务沉淀成第一个 Skill，用熟练了再慢慢扩充。技能文档里最忌讳写"应该怎么做"而不写"不能怎么做"——AI 对限制的理解远比你对它的期待要弱，限制条件写得越明确，翻车概率越低。
4.2 Memory：让 AI 记得上下文，而不是每轮都"失忆"
终端 Agent 的一个通病是：每轮对话之间、每个会话之间的上下文是割裂的，上一轮你让它改过的代码，下一轮它可能完全不知道。opencode 的 Memory 机制就是为了缓解这个问题。
实践中比较常见的手法有两种。第一种是项目内维护一个AGENTS.md或者类似约定文件，里面写清项目架构约定、代码风格、常用命令。opencode 在开始处理任务时会自动读取这些文件，相当于每次都能"带着工作笔记"干活。第二种是让 opencode 把重要的决策、踩过的坑、后续要做的 TODO 主动记录到 memory 目录里，下次对话时它可以主动引用。
我自己最喜欢的一个用法是：每次收工前让 opencode "总结一下当前进度、未完成事项和关键决策，写入 memory"。第二天打开新会话，先让它读 memory，它就能无缝续上昨天的活。这个习惯看起来不起眼，但对跨天、跨会话的项目维护帮助极大。千万别指望 AI 自己在多个会话之间保持记忆，培养"主动记忆-主动恢复"的工作流，才是正解。
4.3 LSP：让 AI 真正"看懂"代码而非"猜"代码
LSP（Language Server Protocol，语言服务器协议）解释起来有点抽象，但你可以把它理解成"给 AI 配了一副眼镜"：没有 LSP 的 AI 只是靠文本匹配去猜代码之间的关系；有了 LSP，AI 能真正拿到类型信息、定义跳转、错误诊断、引用关系这些"硬信息"。
比如 AI 在改一个 TypeScript 函数时，如果没有 LSP，它可能不知道这个函数在哪几处被调用，改完参数类型导致调用方全部报错，它也不知道。有了 LSP，它会提前拿到调用关系，主动检查调用方是否需要同步修改。
opencode 的 LSP 配置思路如下：在配置里为对应语言指定 language server 的启动命令，比如 TypeScript 用typescript-language-server，Python 用pyright-langserver。确保这些 server 已经通过 npm 或 pip 全局安装。
{ "lsp": { "typescript": { "command": "typescript-language-server", "args": ["--stdio"] }, "python": { "command": "pyright-langserver", "args": ["--stdio"] } } }配完之后重开会话，让 AI 做一次跨文件的类型重构试试，你会明显感觉它"靠谱了"。不过 LSP 实例也有内存占用，项目特别大的时候，建议只给主力语言配 LSP，不要贪多。
4.4 Playwright：让 AI 自己打开浏览器找前端 bug
"opencode playwright 怎么测试前端 bug"也是高频搜索词。这个场景非常实在：前端 bug 往往不是代码编译错误，而是运行时行为不对——页面点了没反应、接口返回了但界面没刷新、控制台报了错但不确定是哪行触发的。传统排查流程是你自己开 DevTools 一步步复现,现在可以让 opencode 通过 Playwright 自动化这个流程。
实际操作路径分三步：第一步，确保项目里有 Playwright 依赖，并已经装好浏览器内核；第二步，让 opencode 启动本地开发服务器，默认一般是npm run dev或类似命令；第三步，给 opencode 一个可复现的 bug 描述，比如"打开首页后点击登录按钮，控制台抛了一个未捕获的 TypeError，帮我截图并找到报错来源"。
opencode 会借助 Playwright 工具打开指定页面、监听 console 消息、截取页面状态、读取 DOM 结构，然后把收集到的信息作为排查上下文。你大概率会看到它做这样的事：打开页面 -> 点击按钮 -> 抓 console -> 看到某行报错 -> 回去定位对应组件代码 -> 给出修复建议。这一套流程如果让你手动来，至少十分钟起步，它可以在几分钟内完成，而且很多定位信息是它比你更快的——因为 console 报错它直接就能读到，而你还要自己眼睛扫。
实测下来这个功能对"组件渲染类 bug""接口联动类 bug"尤其高效，但对"需要复杂登录态、多步骤操作才能复现"的场景，建议你先手动把页面带到临界状态，再让 AI 接管，否则它会卡在登录这一步来回试探。
5. VSCode 插件、IDEA 插件和桌面版：编辑器配合的选型思路
opencode 的根在终端，但很多人用不惯纯命令行界面，于是就有了"opencode vscode""opencode idea 插件""opencode 桌面版"这些搜索需求。我的判断是：终端模式适合深度任务和批处理，编辑器插件适合你正在写代码时顺手呼唤 AI，桌面版适合想可视化看进度的人。三个不冲突，可以结合使用。
5.1 VSCode 和 IDEA 插件的定位差异
VSCode 插件和 IDEA 插件解决的问题是一样的：在不离开编辑器的情况下调用 opencode 的能力。但两个生态的成熟度不一样。VSCode 插件目前明显更完善，安装后左侧面板会多出一个 opencode 视图，能直接看会话列表、模型切换、文件修改记录；选中代码后右键就能让 AI 解释或者重构，支持 diff 审查，改动会以行级 diff 的形式展示，你可以逐段接受或拒绝。
IDEA 插件起步晚一些，基础对话功能可用，但一些高级特性（比如 LSP 集成、Playwright 工具）在 IDE 里的整合度还没有 VSCode 那么顺滑。这里有个很现实的选择建议：如果你的主力 IDE 是 IntelliJ 系，日常写 Java/Kotlin 较多，那还是优先用 IDEA 插件 + 终端配合；如果是写前端、Python、脚本类项目，VSCode + opencode 的体验是更能拉满的。
还有一个容易被忽略的点：插件模式本质是"终端进程 + 编辑器 UI"，所以你在插件界面里开的会话，和你在终端开的会话是独立的。注意别开太多会话，模型 tokens 消耗会叠加，月底账单会教你做人。
5.2 桌面版值不值得装
桌面版适合两种人：不想碰终端、只想有一个图形窗口操作 AI 的初学者；以及需要同时盯多个项目的重度用户，桌面版可以多窗口并行。但我体验下来的感受是：桌面版目前更像终端能力和编辑器插件的"中间态"。它能完成基本的对话、文件修改、模型切换，但精细度上比编辑器插件差一些，也没有终端模式那么轻快。
所以我个人给的是优先级建议：终端模式排第一，VSCode 插件排第二，桌面版排第三，按需取用。装了桌面版之后，它和 VSCode 插件可能会争抢同一个配置目录，导致你改了配置一边生效另一边不生效，遇到这种优先排查配置目录归属，别在功能设置里反复找原因。
6. 接手一个陌生项目的完整操作流程与高频报错排查
不管你是个人开发者还是团队里的成员，迟早会遇到"把 opencode 丢进一个从没见过的旧项目"这种场景。这一步做好了，后面所有任务都顺；做不好，你会觉得 AI 还不如你手动看代码。下面是我在某次接手上线排障项目时实际跑通的一套流程，直接照抄即可。
6.1 我把 opencode 丢进旧项目时的操作顺序
第一步，先不急着让它写代码，先做项目侦察。进入项目根目录，开一个会话，原话是："先读一下 README、package.json（或对应语言的依赖清单）、构建配置，简单告诉我这个项目做什么、入口在哪、怎么本地运行、测试怎么跑。"
第二步，让它梳理架构。"找出项目里主要的模块/目录划分，画出模块依赖关系（用文字描述就行），告诉我最核心的数据流是什么。"这一步能帮你在几分钟内建立起对项目的全局认知，省掉自己读半天文档的时间。
第三步，理完架构之后，明确当前任务的目标和边界。这里的关键是给 AI 划清"能改什么、不能改什么、验证标准是什么"。比如："我要给登录接口加上刷新 token 的逻辑，只能改 auth 模块，不能动其他模块，改完必须跑过 auth 相关的测试。"目标和边界越清晰，输出越可控。
第四步，让它给出执行计划，确认后再动手。我通常会让它"先列一个计划：要改哪些文件、每处改什么、怎么验证"。审核计划这一步绝对不能跳过，计划里的方向不对，后面执行得再好都是白搭。
第五步，分步执行 + 每步确认。让它每次只改一个文件，改完展示 diff，你 review 后再继续下一个。虽然效率看起来慢了，但这是防止 AI 在旧项目里"自由发挥"的唯一可靠办法。
6.2 高频报错和对应处置清单
| 报错场景 | 通常原因 | 快速处置 | |---------|---------|---------| | 无法将 opencode 识别为 cmdlet | npm 全局 bin 目录不在 PATH | 把 %APPDATA%\npm 加入环境变量，重开终端 | | error: unexpected server error. check server logs | 网关/服务商接口故障或限流 | 检查服务商状态页，切换到备选模型，查看 opencode 日志 | | this model is not available in your country | 上游服务商区域许可限制 | 换同服务商可用模型，或换服务商 | | LSP 不生效 | language server 未安装或命令名不对 | 确认全局装了对应 server，检查配置 command 路径 | | Playwright 无法启动浏览器 | 浏览器内核未安装 | 执行 npx playwright install 安装内核 | | 模型响应超时 | 网络问题或服务商负载高 | 降低上下文长度，切轻量模型，重试 |"unexpected server error"这个报错值得多说一句。它后面往往跟着 "check server logs"，意思是 opencode 的服务端进程出了问题，要去查日志定位。日志位置一般在~/.local/share/opencode/log/或者~/Library/Logs/opencode/（macOS），具体路径跟你系统有关。大多数人遇到这个报错的第一反应是重装，但查日志往往更快：如果是服务商返回了 429 限流，那就等一下再试；如果是 key 失效，换 key；如果是本地网关服务崩了，重启那个服务。先看日志，再动手，是排查这类问题的基本素养。
还有一个热搜提到过的 "opencode memory" 和 "opencode linux 修改 json"，前者我在第 4 节已经写了用法，后者在第 2 节也覆盖了。这些看起来零散的问题，根源其实都是同一个：对工具的配置模型和运行机制没有建立整体认知。把这篇文章里的安装、配置、功能三条主线理清，再遇到具体报错时，你就能判断它属于哪一环，而不是像无头苍蝇一样瞎搜。
7. 收尾前再分享几个我实测下来的小技巧
最后说几个不占篇幅但很实用的细节。
第一个是/status命令。开了很久的会话之后，上下文会越来越长，模型响应变慢、开始丢掉早期的信息，这时候用/status看当前会话的 token 消耗和上下文长度，心里有数之后决定是压缩上下文、精简对话还是开新会话。
第二个是给 opencode 一个固定的人设约束。在AGENTS.md里写清楚：代码风格偏好、不要改动哪些文件、测试通过前不要宣称完成、每个改动必须解释影响范围。这些约束会显著降低 AI 在复杂任务里的"自作主张"概率。相当于给它立规矩，而不是每次软绵绵地提醒。
第三个是善用/undo。AI 执行完一步之后发现改错了，不用慌张，用/undo回退最近一次操作，这是终端 Agent 比很多可视化工具更优雅的地方。但我还是提醒一句：重要操作前，让 AI 先确认计划也好，手动备份敏感文件也好，不要把"回退"当成救命稻草，有些操作（比如批量删除、git 历史改写）是回退救不回来的。
最后一个建议是版本和升级节奏。opencode 迭代非常快，新功能、新修复几乎每周都有。但我不建议每次更新都无脑追最新，因为新版本偶尔会带来配置格式变动、插件兼容性问题。我的习惯是：线上正在跑的任务不动，等任务空隙再升级，升级之后先跑一遍doctor确认配置没坏。
opencode 不是一个完美的工具，它也有自己的毛病——配置门槛比竞品高、部分功能需要自己组装、社区版本迭代有时候让人追得心累。但如果你愿意花那半小时把模型接入和核心功能配好，它回馈给你的是真正的模型自由和高效工作流。以上都是我在这段时间实际使用中摸出来的经验，希望能帮你少踩几个坑。
