OpenCode，别急着上手，分享我的自用经验

最近一段时间 OpenCode 的话题度很高，公众号和推上每隔几天就有人晒"一天配置、终身起飞"。我也凑过几次热闹，但说实话，真正把它当成日常开发工具并接入 AI 用，是在吃了几次亏、调过几次规则之后才稳定下来的。这一篇不是官方文档的搬运，也不是"hello world 教程"，我会先讲我为什么把 OpenCode 作为日常开发工具并接入 AI 用，列 8 条最容易踩的注意事项——尤其是"装上第一天别急着写规则"。如果你正在评估 OpenCode、或者已经装上却不知道从哪一步开始，这篇可能比"快速上手"那一份更值得花十分钟读完。蓝色高亮表示工具或事实，绿色高亮表示我的使用判断，红色高亮表示容易踩的坑，黄色高亮表示可以直接抄走的最小可用集。、

  • 先把"为什么用"想清楚：换模型不被绑架、过程可观察、本地运行——这三条都满足了，再谈下一步。
  • 从最小可用集开始：一份简短 AGENTS.md + 一个稳定 Provider + 一个默认 build 角色 + 启用的 LSP。够用就好。
  • 复杂任务先 plan 再 build：跨文件的改动，先看 diff 再下手，能避免一整轮返工。
  • 规则要可验证、规则要文件化：机器能判的才叫规则，读不懂的只是愿望。
  • 审查用只读 agent：把"看"和"改"分开，是让 AI 报告客观的前提。
  • 接入 MCP 时按"只读 → 受限可写 → 状态变更"分步放权：每一步都先想清楚"最危险的事是什么"。
  • 不要让关键检查静默失败：可见、可追溯、有人负责，三条缺一不可。
  • 把 AI 当草稿作者，把自己当责任编辑：最终交付的责任，不能下放给工具。

一、把 OpenCode 放进工作流之前，我给自己提过三个问题：它能不能让我换模型不被绑架？它能不能把每一步操作摊在我眼前？它能不能在我自己的机器上跑，而不是把代码交给一个远端托管？ OpenCode 在这三个问题上都给出了让我愿意留下来的答案，这也是我后来把它接入 AI 用作日常开发工具的真正原因。我把这三个答案按顺序写下来，因为它们不只是在"功能上"成立，更是OpenCode 与同类工具最明显的差异点：

  1. 开源、可审计、不绑定单一供应商：OpenCode 的客户端代码是公开的，关键行为可以在源码里核对；Provider（也就是模型供应商）走的是开放协议，我可以在同一个配置里同时挂上 OpenAI、Anthropic、本地 Ollama、自建代理，换模型不需要重写工作流，更不需要换一份订阅。对我来说这意味着两件事：第一，今天贵/限流的模型，明天可以被另一个模型接住；第二，今天数据合规的顾虑，明天可以通过本地模型或者自建网关绕过。这条不是装饰，它直接决定了我愿不愿意把生产代码交给它。
  2. 把"工具调用 + 文件编辑 + 命令执行"收进一个 TUI：比起网页聊天窗口，OpenCode 的好处是上下文连续。一次会话里，它可以直接读写我的文件、跑我的命令、调用我的 LSP，并把每一步的结果作为下一步输入。传统聊天窗口要靠我在不同窗口之间复制粘贴，OpenCode 把这些步骤变成了同一个会话里的多轮工具调用。对我而言这比"模型写得多聪明"更重要：我能在同一个界面里看见它读了什么、改了什么、跑过哪些命令、回滚时还能回到哪一步。信任不是靠宣传词建立的，是靠"可观察"建立的。
  3. 配置即文档，规则可以在 review 里被讨论：OpenCode 的绝大部分约定都放在纯文本文件里：项目根的 AGENTS.md 写规则，commands/*.md 写命令模板，agents/*.md 写角色，skills/*.md 写沉淀下来的做事方法。最常见的错误是把 AGENTS.md 当成无所不包的"价值观大全"，其实它的价值恰恰相反——把"我想要的工作方式"显式写下来，让工具按文件读，而不是每次新会话都让我重新解释一遍。规则在哪一步生效、谁负责什么，可以被同事直接读到，也可以在 review 里被讨论。这就是我把 OpenCode 当成"开发工具并接入 AI 用"的核心原因——AI 第一次成为工作流的一部分，而不是一个聊天侧栏。

二、装上 OpenCode 之后，先别急着让它"做项目"。我会先定一个最小可用集，把"模型 + 规则 + 角色 + 编辑器反馈"四件事按顺序配齐，再开始干正事。顺序不能乱，因为规则没写好之前，模型越强越容易跑偏。下面这 8 条技巧，前 4 条是"装好就能用"的最小集，后 4 条是"日常真正省时间"的核心姿势，全部按顺序展开，每一条都尽量具体到"打开哪个文件、敲哪条命令、看哪个输出"。我会刻意把"我踩过的坑"嵌在技巧后面写，而不是单独列一节，这样读起来不会割裂。

  1. 技巧一：选一个稳定的 Provider，并准备好备用项。Provider 是 OpenCode 接入模型的入口，我一般同时配两个：一个主力（适合写代码、做重构），一个便宜快（适合跑搜索、扫描、批处理）。Provider 在 ~/.config/opencode/config.json 里配置，启动时用 指定模型即可，模型换了不需要改其他配置。不要相信配置文件里写了什么，要相信命令实际返回了什么——所以接入之后我会用一段小代码同时测试三种能力：解释一段逻辑、生成一个新函数、修改一个现有文件，看它能不能在同一个会话里都跑得动。常见坑：把 provider 写成 gpt-4o-latest 这种"训练时常见写法"，结果实际接口已经下线，配置看着对、用起来 404。验证命令是 opencode --model xxx 起一次最小会话，看返回是不是空。
  2. 技巧二：AGENTS.md 短而具体，先只写三类信息。新人最容易把 AGENTS.md 写成"编码价值观大全"，把所有想得到的规则都塞进去。AI 什么都读到一点，结果什么都执行不到位。我自己的 AGENTS.md 始终控制在几十行以内，只写三类信息：项目语言、构建命令、测试命令；哪些目录/文件不能动（例如 generated/、migrations/、*.lock）；提交前必须经过哪些检查（例如 go test ./... 通过、gofmt 无差异）。规则必须可验证——例如"提交前必须 通过"，而不是"请保证代码优雅"。前一条规则机器能判，后一条机器读不懂，自然也不会执行。一个小判断标准：写完一条规则问自己"如果 AI 没遵守这条，我能用一行命令发现吗？"——能就保留，不能就改写或删除。
  3. 技巧三：先只用一个 build 角色，跑两三天再说。新人常犯的错是开局就建一堆 agents（plan / explore / scout / review），觉得这才是"正确姿势"。我的建议正好相反——先用默认的 build 角色把真实任务跑两三天，当你明确感到某一步总是出错，再为它建一个专门角色。角色的颗粒度应该来自反复出错的痛点，而不是来自"看起来专业"。一上来就分四个角色，等于在还没摸清自己需求的时候，先把工作流固化住了，后面想改也改不动。角色不是装饰品，是为反复出错的痛点准备的"专门通道"。
  4. 技巧四：打开 LSP，让 AI 拿到"接近 IDE 的反馈"。OpenCode 启动时会按项目语言自动加载对应的 LSP（Go 的 gopls、TypeScript 的 typescript-language-server、Rust 的 rust-analyzer 等），让 AI 拿到跳转、定义和类型信息。把 LSP 打开以后，"AI 凭幻觉写错接口"的概率会明显下降。如果项目用的语言不在默认列表，就在配置里加上 server 的启动命令。这一步几乎零成本，但收益是结构性的——AI 不再盲写。验证方式很简单：让 AI 在不读源码的情况下写一个用到 pkg.Foo 的调用，看它写的参数是不是真的存在。这就是我目前的最小可用集：一份简短的 AGENTS.md + 一个稳定 Provider + 一个默认 build 角色 + 启用的 LSP。
  5. 技巧五：复杂任务先用 plan 而不是直接 build。OpenCode 默认是 build（直接动手），而 plan 只产出步骤描述和预期 diff，不会改文件。我用 的频率远高于 ，尤其是在跨多个文件的任务里。plan 出来后我会自己问三件事：步骤是否可验证、是否包含回滚点、是否有我必须保留的约束没在里面。满足这三件事，我才让它进入 build。"先 plan 再 build"看起来比一次跑完慢，但它避免了我最怕的那种返工——AI 已经写完一个完整模块，最后才发现我根本没想清楚要的是什么。
  6. 技巧六：把高频 prompt 写成 commands。每周都会重复的 prompt，我会沉到 commands/*.md 里，比如 /commit、/review、/refactor。命令文件就是一个 Markdown 模板，参数用 $ARGUMENTS 占位。命令文件的价值不是"少打字"，而是把团队约定固化下来。新人加入项目只要看 commands/ 目录，就能上手一半的常用操作；老手换了机器也不用重新写 prompt。只要这条规则被遵守，OpenCode 就不只是一个我用的工具，而是一个团队能复用的工作流。 写命令文件时我会刻意遵守三条小规矩：标题用动词开头（如"提交"、"审查"、"重构"），参数只通过 $ARGUMENTS 透传，不要在命令里塞模型选择（模型由 --model 控制），输出结构要固定（避免每次 AI 给的格式都不一样）。
  7. 技巧七：用 agents 切分可写权限。我会建三类 agent：plan（只读，规划）：不能改文件，不能跑命令；explore（只读，调研）：可以跑查询命令，但不能改文件；build（可写）：默认角色。审查类任务坚决只用只读 agent，否则 AI 看到问题顺手就改完了，报告就不再客观。这一点是我上一篇文章里反复强调的——审查和修复必须是两个动作，否则修复完的代码又变成新的审查对象。具体到我自己：写代码用 build，审 PR 用 plan，调研陌生仓库用 explore。只读 agent 的报告价值远大于可写 agent 的"善意改完"——前者给的是信息，后者给的是又一次需要 review 的 diff。
  8. 技巧八：把跨项目知识沉淀进 skills，并按"触发/步骤/反例"三段写。项目里一些只属于本仓库的约定（比如"这个 monorepo 里改 API 必须同时改三个 SDK"、"这个服务的所有数据库访问都必须走 db.WithTx"），我会写进 skills/*.md。skill 不是 AI 自动生成的总结，而是我自己确认过的方法。我会刻意在每次完成一个非平凡任务后，回头补一份 skill，而不是寄希望于"AI 自己学会"。一个 skill 文件至少要写清楚三件事：触发条件（什么时候用）、步骤（怎么用）、反例（什么时候别用）。只有写完反例，skill 才不会变成"什么都能用"的废话。

三、工具再好也有边界。下面这 8 条注意事项，是我接入 AI 之前每次都会重新问自己一遍的问题，也是我身边朋友"装上 OpenCode 然后放弃"最常见的 8 个原因。每一条都给一个"我当时是怎么踩坑的 + 现在怎么避开"的双层写法，方便直接抄到自己的 checklist 里。

  1. 注意一：接入 AI 之前，先想好"什么不算成功"。我在交给 OpenCode 之前会明确：哪些 API 不能破坏、哪些行为必须保留、哪些错误路径必须覆盖。没有"完成标准"的 AI 任务，写得再快也只是把模糊需求放大成更复杂的代码。AI 不会替你定义成功，它只会按你给的边界去执行；边界越具体，结果越能用。 我自己踩过的典型坑：让 AI 写"统一一下错误处理风格"，没说哪些函数算"错误处理"，结果它把我设计好的 panic-recover 链路改成 error 返回，半个服务挂掉。
  2. 注意二：不要让关键检查静默失败。无论是 LSP、测试、密钥扫描还是 AI 自审，失败必须可见；用 || true 吞掉失败，是把责任推给未来的自己和同事。失败可见、可追溯、有人负责——这是任何 AI 流程能跑下去的前提。 我自己的一个小习惯：所有 pre-commit / pre-push 钩子都用 set -e，CI 的每一道检查都不允许 continue-on-error，避免"红着也能合并"。常见反模式：某个 AI 自审脚本失败时 CI 仍显示绿色，理由是"网络抖动下次就好"——这种放过一次，下次就会放过十次。
  3. 注意三：不要把所有对话都留在一个会话里。一个干净的小会话，比一个长到爆的会话更可靠。我会在切换任务时主动 /clear，把上下文控制在本次任务以内。OpenCode 不是聊天软件，它是带上下文的工具；上下文越短，工具越准。一旦上下文变长，AI 容易开始"猜我前面说过什么"，而猜错的代价比"我重新说一遍"大得多。具体到我自己：每次写完一个 PR 就 /clear，下次新任务开新会话。
  4. 注意四：不要用 OpenCode 替我做最终判断。它能查资料、写样板、改风格、跑测试，但它不能替我决定业务规则、权限边界、上线策略。"AI 通过了"不等于"可以合并"，更不等于"可以上线"。按下回车的人，必须知道自己在交付什么。 这条规则反过来也是检查清单：每次准备合并时问自己"如果这次 AI 写的代码出了问题，是我能背还是 AI 能背？"——能背就合，不能背就改。
  5. 注意五：经常回头看 AGENTS.md 和 commands。规则用一段时间就会过期，commands 里塞的参数会越加越多。我会每两周把规则读一遍，删掉没用的、加上一周内反复说过的话。规则文件不是写完就结束，它和代码一样需要 review、需要重构、需要下线。 我的具体做法：每月第一个周末花 30 分钟通读所有规则文件，做一次"留下 / 删除 / 改写"的标记。
  6. 注意六：不要把规则藏在 prompt 里。不少人会把"项目规范"塞进每次对话的 prompt 里，结果换个人、换台机器、换个会话，规范就消失了。规则应该是文件，而不是对话里的一段临时说明。规则文件的好处是：可以被版本管理、被 review、被新人阅读、被同事复用到其他项目。我自己的硬规矩：凡是会被重复说的规则，必须落到文件里；prompt 里只写"这次任务的目标 + 上下文"，不写"项目规范"。
  7. 注意七：不要把模型当永久事实。provider、模型、字段、价格都会变；配置更新后要用实际命令确认，而不是只看配置文件里写了什么。"我配了 Anthropic"不等于"我现在能用 Claude 4"，模型下线、限流、被墙都会让配置失效。每次新增 provider 之后，我都会跑一个小测试任务确认它真的能跑通。常见坑：训练数据里写的是 claude-3-opus，2026 年这个 id 早就下线了；配置文件看上去 OK，启动报 unknown model。
  8. 注意八：不要迷信"AI 自动生成的总结"。不管是 skills 的总结、commands 的标题、还是 review 的报告，AI 给的版本都只能作为草稿。我自己确认过的版本才是定稿，因为只有我知道"它是否符合这个项目的真实情况"。把 AI 当草稿作者，把自己当责任编辑——这是我对 AI 工具最重要的态度之一。 一个判断方法：每次拿到 AI 写的总结，我会问"如果未来三个月只有我自己看这份总结，我能照着做吗？"——能照着做才收，不能就改。

四、最后说一句心里话：OpenCode 不是"装上就更好"的工具，它是一套把"我想要的工作方式"显式化的协议。工具的价值不在于它替你做了什么，而在于它让你不得不把"自己想怎么工作"写下来。如果你也打算上手，建议从最小可用集开始，让真实任务逼出规则，再让规则反过来约束任务——这个循环一旦跑顺，AI 才真的从玩具变成工作流的一部分。给读者的 8 条启示：

  1. 先把"为什么用"想清楚：换模型不被绑架、过程可观察、本地运行——这三条都满足了，再谈下一步。
  2. 从最小可用集开始：一份简短 AGENTS.md + 一个稳定 Provider + 一个默认 build 角色 + 启用的 LSP。够用就好。
  3. 复杂任务先 plan 再 build：跨文件的改动，先看 diff 再下手，能避免一整轮返工。
  4. 规则要可验证、规则要文件化：机器能判的才叫规则，读不懂的只是愿望。
  5. 审查用只读 agent：把"看"和"改"分开，是让 AI 报告客观的前提。
  6. 接入 MCP 时按"只读 → 受限可写 → 状态变更"分步放权：每一步都先想清楚"最危险的事是什么"。
  7. 不要让关键检查静默失败：可见、可追溯、有人负责，三条缺一不可。
  8. 把 AI 当草稿作者，把自己当责任编辑：最终交付的责任，不能下放给工具。

我参考的公开资料：