1. 从"能跑"到"好用"：opencode 工具链的完整拼图
很多人第一次接触 opencode，注意力都放在"怎么装、怎么连上模型、怎么让它回话"这三件事上。等这几步跑通之后，真正的困惑才刚开始：为什么别人的 opencode 能读文件、能跑命令、能查数据库、能调外部服务，而我的只能干聊？答案就在"工具"和"服务面"这两个概念上。
这篇是下篇，上篇我们把 opencode 的核心机制和基础配置过了一遍，这一篇专门啃硬骨头：工具系统怎么设计、服务面（service surface）到底暴露了什么、外壳（shell/wrapper）层怎么和编辑器打通，以及最后怎么把这些东西拼成一个真正能用的实战集成方案。关键词里的 opencode、工具、服务面、外壳、实战集成，其实就是这篇文章的五条主线。
适合谁看？如果你已经能让 opencode 跑起来，但卡在"怎么让它真正干活"这一步，这篇就是给你写的。如果你还在纠结安装，建议先回去看上篇。下面所有内容都基于我自己的实操经验，涉及具体参数和步骤的地方我会把"为什么这么选"讲清楚，而不是甩一堆命令让你抄。
先说一个反直觉的结论：opencode 的能力上限，八成不取决于你用什么模型，而取决于你给它配了哪些工具、这些工具怎么被服务面暴露出来、外壳层怎么把它们串起来。模型决定"想得多聪明"，工具决定"能碰多少东西"。一个中等模型配上完整的工具链，实际产出往往吊打一个顶级模型裸奔。
2. opencode 工具系统的分层设计：为什么不是"插件越多越好"
2.1 工具的三层结构：内置、扩展、外部进程
opencode 的工具系统我习惯分成三层来看，这个分法不是官方文档写的，是我踩了几个月坑之后自己总结的，因为它能解释很多"为什么这个工具不生效"的问题。
第一层是内置工具，也就是 opencode 本体自带的那些能力，比如读写文件、执行 shell 命令、搜索代码库。这些工具的特点是零配置、开箱即用，但边界很死——它只能碰 opencode 进程有权限碰的东西。你在容器里跑，它就只能在容器里折腾；你给它只读挂载，它写文件就会失败。
第二层是扩展工具，通过配置或插件机制挂进去的，比如数据库查询工具、HTTP 请求工具、特定领域的解析工具。这一层是能力扩展的主力，也是问题最多的地方，因为每个扩展工具都有自己的依赖、自己的权限模型、自己的超时策略。
第三层是外部进程工具，本质上是 opencode 去调用一个独立的命令行程序或服务，把结果拿回来。像 adb、ssh、各种 CLI 工具都属于这一类。这一层最灵活，但也最脆弱，因为进程间的输入输出格式、错误码、编码问题全都要你自己兜底。
理解这三层的意义在于：当某个工具"不工作"时，你要先判断它属于哪一层，再去对应的层面排查。内置工具出问题，八成是权限或路径；扩展工具出问题，八成是配置或依赖；外部进程工具出问题，八成是环境变量或输出解析。
2.2 工具描述（tool description）才是真正的"提示词"
这是我最想强调的一点，也是绝大多数人忽略的地方。你给 opencode 挂一个工具，它怎么知道什么时候该用这个工具？靠的是工具的描述文本。这段描述不是给人看的文档，是给模型看的提示词。
我见过太多人把工具描述写成"查询数据库"这种四个字，然后抱怨模型从来不用这个工具。问题就出在这里——模型看到"查询数据库"，它不知道这个工具能查什么库、接受什么参数、返回什么格式、什么时候该用什么时候不该用。它当然不敢用。
正确的做法是把工具描述当成一段微型提示词来写，至少包含四要素：这个工具做什么、什么场景下用、输入参数的含义和格式、返回结果的结构。举个例子，同样是数据库工具，差的描述是"执行 SQL"，好的描述是"对只读副本执行 SELECT 查询，参数为单条 SQL 语句字符串，返回 JSON 数组，每行一个对象；仅用于数据查询，禁止用于写操作"。
实测下来，工具描述的质量对工具调用成功率的影响，比模型档次的差异还大。我做过对比，同一个中等模型，工具描述从一句话扩写到四要素版本，正确调用率从大概三成提到了八成以上。这个投入产出比高得离谱，值得你花时间打磨每一个工具的描述。
2.3 工具数量与选择成本的权衡
新手容易犯的另一个错是"工具越多越好"，恨不得把能挂的全挂上。结果模型面对几十个工具，选择成本飙升，经常选错工具或者该用的时候不用。
我的经验是：常驻工具控制在 8 到 12 个，这是一个比较舒服的区间。超过这个数，模型的选择准确率会明显下降。那剩下的工具怎么办？按场景分组，用的时候再挂。比如你做前端调试时挂浏览器相关工具，做数据排查时挂数据库工具，不要一股脑全塞进去。
还有一个技巧是给工具做"命名分组"，让名字本身就带场景信息。比如db_query_readonly、fs_read_text、shell_exec_safe，模型光看名字就能大致判断用途，选择成本会低很多。命名这件事看着小，实际影响很大。
3. 服务面（service surface）到底暴露了什么
3.1 服务面的本质：能力边界与调用契约
"服务面"这个词听起来玄乎，说白了就是 opencode 对外暴露的、可以被调用的能力集合，以及这些能力的调用契约。它决定了"外面能怎么用 opencode"和"opencode 能怎么用外面"。
服务面有两个方向。一个是入向服务面，就是外部怎么驱动 opencode，比如通过命令行、通过编辑器插件、通过一个本地服务端口。另一个是出向服务面，就是 opencode 怎么去调用外部能力，也就是上一节讲的工具系统。这两个方向经常被混为一谈，但排查问题时必须分开看。
入向服务面最典型的就是编辑器集成。你在编辑器里选中一段代码，让 opencode 处理，这背后就是编辑器通过某种协议把上下文传给 opencode，opencode 处理完再回传。这个链路上任何一环断了，表现都是"没反应"或者"结果不对"。所以当编辑器集成出问题时，先确认是编辑器没发出去、还是 opencode 没收到、还是收到了但处理失败，这三段要分开验证。
3.2 入向服务面的三种典型形态
第一种是命令行形态，最直接，也最适合脚本化和自动化。你可以在 CI 里、在定时任务里、在 git hook 里调用它。这种形态的坑在于环境隔离——命令行跑的时候，工作目录、环境变量、PATH 可能和你交互式使用时完全不同，工具找不到、路径不对是家常便饭。
第二种是编辑器插件形态，体验最好，上下文最丰富，因为编辑器知道你现在打开的是哪个文件、光标在哪、选了什么。但这种形态对版本匹配很敏感，编辑器升级、插件升级、opencode 升级，三者版本错位就会出各种诡异问题。我的建议是锁定版本，升级前先在小项目里验证。
第三种是本地服务形态，opencode 起一个本地端口，其他程序通过这个端口和它通信。这种形态最灵活，能对接任意前端，但安全边界要自己把控——本地端口谁能访问、要不要鉴权、请求体大小限制，这些都得想清楚。别小看这个，本地服务被同机器上的其他程序乱调，是很常见的翻车场景。
3.3 出向服务面的权限收敛
出向服务面，也就是工具调用外部能力这一侧，核心原则是权限收敛。什么意思？就是每个工具只给它完成本职工作所需的最小权限，多一分都不给。
举个具体例子。你挂一个读文件的工具，就只给读权限，别顺手把写权限也开了。你挂一个查数据库的工具，就连到只读副本上，别连主库。你挂一个执行 shell 的工具，就限制它能执行的命令白名单，别给它一个万能 shell。
为什么这么强调？因为模型是会犯错的，工具描述写得再好，它也可能在边界情况下调错工具、传错参数。权限收敛就是你的最后一道防线——就算模型调错了，损失也可控。我见过有人给 opencode 挂了主库的写权限，结果模型理解偏差执行了一条 UPDATE，虽然最后回滚了，但那种心跳加速的感觉，一次就够了。
权限收敛还有个附带好处：它逼你把每个工具的职责想清楚。一个工具如果没法用一句话说清它该干什么、不该干什么，那它大概率设计得有问题，应该拆开。
4. 外壳层：opencode 与编辑器、终端之间的那层"胶水"
4.1 外壳层解决的核心问题：上下文搬运
外壳（shell/wrapper）这个词在不同语境下含义不同，在 opencode 这个场景里，我把它定义为"连接 opencode 和你的日常工作环境的那层适配代码"。它的核心职责就一件事：把正确的上下文搬进 opencode，把 opencode 的结果搬回你的工作流。
为什么需要这一层？因为 opencode 本身不知道你在哪个项目、当前分支是什么、改了哪些文件、报错日志在哪。这些信息要么靠你手动喂，要么靠外壳层自动采集。手动喂效率低还容易漏，自动采集才是正解。
一个合格的外壳层，至少要能自动提供：当前工作目录和项目根路径、当前 git 分支和最近改动、相关文件的路径和内容片段、最近的错误输出。有了这些，opencode 才能给出贴合你实际情况的回答，而不是泛泛而谈。
4.2 编辑器集成的关键：vscode 与 opencode 怎么配合
关键词里出现了"vscode 怎么和 opencode 工作"，这是问得最多的。我自己的用法是这样的：编辑器负责"看"和"选"，opencode 负责"想"和"改"，两者通过文件系统和剪贴板做最朴素的桥接，反而比深度集成更稳。
具体来说，我在编辑器里选中要处理的代码，通过一个快捷键把选中内容和文件路径拼成一段结构化文本，丢给 opencode。opencode 处理完，把结果写到一个约定的临时文件，编辑器再读这个文件展示 diff。这套流程土是土，但胜在透明、可调试、不依赖任何特定插件版本。
为什么不直接用深度集成插件？因为深度集成把太多东西藏在黑盒里，出问题时你根本不知道是编辑器的问题、插件的问题还是 opencode 的问题。土办法每一步都看得见，坏了也好修。当然，如果你追求开箱即用的体验，用官方或社区的集成插件也没问题，只是要接受它的黑盒性。
4.3 终端外壳：让 opencode 融入命令行工作流
终端场景下，外壳层的价值在于把重复的上下文准备自动化。我给自己写了一个小脚本，做的事情很简单：进入项目目录、采集 git 状态、把最近改动的文件列表和当前分支信息拼成一段前缀，然后带着这段前缀启动 opencode。这样每次启动，opencode 就已经知道我在哪个项目、改了什么，不用我再复述一遍。
这个脚本还有个变体，专门用于排错场景：它会把最近的错误日志尾部、相关配置文件内容一起带上。排查线上问题时，这个变体省了我大量复制粘贴的时间。
外壳层的设计哲学是：能自动采集的绝不手动输入，能固化成脚本的绝不每次重来。你花在打磨外壳层上的每一分钟，都会在后续几百次使用里加倍还回来。
5. 实战集成：把工具、服务面、外壳拼成一个能用的系统
5.1 一个完整的集成场景拆解
光讲概念没意思，我们来看一个完整的集成场景：让 opencode 帮你排查一个后端服务的报错。这个场景会用到工具、服务面、外壳三层的所有东西。
第一步，外壳层采集上下文：当前项目路径、git 分支、最近改动的文件、服务的错误日志尾部。这些信息拼成一段结构化前缀。
第二步，入向服务面把这段前缀和你的问题一起送进 opencode。这里用的是命令行形态，因为排查场景通常发生在终端。
第三步，opencode 分析问题，判断需要更多信息，于是调用出向服务面的工具：读相关源码文件、查最近的提交记录、可能还查一下数据库里相关表的状态。
第四步，工具返回结果，opencode 综合判断，给出可能的原因和验证步骤。
第五步，结果通过外壳层回写到终端，你按建议去验证。
这个链路里，任何一环设计得不好，体验都会大打折扣。比如外壳层采集的日志不完整，opencode 就得反复问你要；比如工具描述写得含糊，opencode 就不知道该查哪个文件；比如服务面权限太宽，opencode 可能做出危险操作。
5.2 工具选型的取舍：内置优先，扩展按需，外部谨慎
在实战集成里，工具选型有个优先级：能用内置的就不用扩展，能用扩展的就不用外部进程。
内置工具最稳，因为它和 opencode 同生命周期，不会有版本错位、依赖缺失的问题。扩展工具次之，虽然要配置，但至少在同一进程空间里，通信可靠。外部进程工具最灵活也最脆弱，进程启动失败、输出格式变化、编码问题、超时，全是坑。
那什么时候不得不用外部进程工具？当你要调用的能力本身就是一个独立程序时，比如 adb、ssh、各种专用 CLI。这时候要做的是给它包一层健壮的适配：设置合理的超时、捕获并规范化错误输出、处理编码、限制输出大小。别让一个卡死的外部进程拖垮整个 opencode 会话。
我踩过的一个坑：挂了一个外部工具去调某个 CLI，那个 CLI 在某些情况下会进入交互式等待，结果 opencode 一直等它返回，整个会话卡死。后来我给所有外部工具调用都加了硬超时，并且强制非交互模式，这个问题才根治。这个教训是：外部进程工具必须假设它会以最坏的方式失败。
5.3 服务面的安全边界设计
实战集成里，服务面的安全边界是必须提前设计的，不能等出事再补。
入向服务面这边，如果开了本地服务端口，至少要限制监听地址为本地回环，别监听所有网卡。如果可能被其他程序调用，加一个简单的 token 鉴权。请求体大小设个上限，防止被塞爆内存。
出向服务面这边，每个工具的权限要收敛到最小。文件工具限制在项目目录内，别让它读到系统敏感文件。命令执行工具用白名单，别给万能 shell。数据库工具连只读副本，别连主库。网络请求工具限制目标域名，别让它随便访问。
这些边界设计看着繁琐，但都是血泪教训换来的。我见过太多"图省事全开权限"最后翻车的案例，包括但不限于：模型误删文件、误改配置、误发请求。权限收敛不是不信任模型，是给不可预测性留缓冲。
5.4 集成后的验证与调优
集成搭好之后，别急着上生产，先做一轮系统验证。我的验证清单是这样的：
| 验证项 | 验证方法 | 通过标准 |
|---|---|---|
| 上下文采集 | 故意改几个文件，看外壳层是否采集到 | 改动文件出现在上下文里 |
| 工具调用 | 提一个必须用工具才能答的问题 | 模型正确选择并调用工具 |
| 权限边界 | 让模型尝试越权操作 | 操作被拒绝且有清晰提示 |
| 错误处理 | 故意让外部工具失败 | 会话不卡死，有错误反馈 |
| 结果回写 | 检查结果是否正确回到工作流 | 终端/编辑器正确展示 |
验证通过之后，还有调优空间。最常见的调优点是工具描述——根据实际调用情况，把模型经常用错的工具描述再打磨一遍。其次是上下文采集的粒度，采集太多会稀释重点，采集太少又不够用，这个平衡要在实际使用中慢慢找。
6. 那些文档不会告诉你的实操心得
6.1 工具描述要"防呆"，不是"防聪明"
写工具描述时，很多人下意识地写得"高级"，用一堆术语。但模型需要的是"防呆"——把最容易搞错的点明确写出来。比如参数是路径还是路径数组、是绝对路径还是相对路径、多个值怎么分隔，这些细节写清楚，比用多华丽的词都管用。
我现在的习惯是，每个工具描述末尾都加一句"常见错误"提示，比如"注意：此工具不接受通配符，需传入具体文件路径"。就这一句话，能挡掉大量无效调用。
6.2 服务面出问题时，先看"谁在等谁"
服务面相关的问题，表现往往是"卡住"或"没反应"。这时候第一件事是判断"谁在等谁"：是 opencode 在等工具返回，还是工具在等外部进程，还是外部进程在等一个永远不会来的输入。用系统的进程查看工具看一眼调用栈，通常几秒钟就能定位。
我遇到过的经典案例：opencode 等工具、工具等一个 CLI、CLI 在等标准输入。三层都在等，谁都不动。解决办法是给 CLI 调用强制加非交互参数，或者把标准输入重定向到空。这个坑很隐蔽，因为从 opencode 这层看，就是"工具没返回"，完全看不出是 CLI 在等输入。
6.3 外壳层要"薄"，不要"厚"
外壳层最容易犯的错是越写越厚，最后变成一个大杂烩，什么都往里塞。我的原则是外壳层要"薄"——只做上下文搬运和结果回写，不做业务逻辑。业务逻辑应该放在 opencode 侧或者工具侧，外壳层保持简单透明。
为什么？因为外壳层是最难测试、最难调试的一层，它夹在中间，出问题两边都怀疑它。保持它薄，出问题时容易排除。一旦它变厚，各种隐式依赖就出来了，维护成本指数上升。
6.4 版本锁定是稳定性的前提
opencode、编辑器、插件、外部工具，这一串东西的版本组合是个大坑。我的做法是全部锁定版本，用一个清单文件记录每个组件的版本号，升级时整体评估、小范围验证、再全量推。别小看这个，版本错位导致的诡异问题，排查起来能耗掉你一整天。
6.5 给模型"退路"，别逼它硬猜
集成设计里有个容易被忽略的点：要给模型留"退路"。什么意思？当模型不确定该用哪个工具、或者信息不足时，它应该能明确地说"我需要更多信息"或者"我不确定该用哪个工具"，而不是硬猜一个然后调错。
实现方式是在工具描述和系统提示里明确告诉模型：信息不足时可以提问，不确定时可以说明。这比逼它硬猜强得多，因为硬猜的代价是错误操作，而提问的代价只是多一轮交互。
7. 从集成到日常：让这套系统真正长在你手上
集成搭好只是开始，真正让它产生价值的是日常使用中的磨合。我自己的经验是，前两周会频繁调整——工具描述改、外壳脚本改、权限边界调。这个阶段别嫌烦，每一次调整都是在把系统往你的实际工作习惯上靠。
过了磨合期，你会发现一些高频场景可以固化成"配方"：比如"排查报错"配方、"代码审查"配方、"数据核对"配方。每个配方就是一套预设的上下文采集加工具组合，用的时候一键调用。这些配方积累起来，才是这套系统真正的价值所在。
还有个小技巧：定期回顾你的工具调用日志，看看哪些工具几乎没用过、哪些工具经常被误用。没用的考虑下线，减少选择成本；误用的回去改描述。这个回顾我一般一个月做一次，每次都能发现几个可以优化的点。
最后说个心态上的事。opencode 这类工具的价值，不在于它一次能帮你做多少，而在于它能不能稳定地、可预期地融入你的工作流。一个能力一般但稳定可靠的集成，胜过一个能力很强但三天两头出问题的集成。把稳定性放在第一位，能力扩展放在第二位，这个顺序别搞反了。
