opencode这个项目，我是从上篇的基础配置开始接触的，当时觉得它不过是个能聊天的终端玩具。直到我试图把它真正接到编辑器、CI流水线里跑自动化，才发现它的正确打开方式远不是“配个模型然后对话”那么简单。这篇文章是下篇，重点放在上篇没深入的三件事：工具调用这套执行循环、藏在终端背后的服务面（server面）架构，以及把opencode集成进真实工作流的姿势。如果你已经装好opencode、能正常对话，但卡在“不知道怎么让它在项目里自动干活”，这篇应该能帮上忙。
先讲个我这边的真实场景。有段时间我想把opencode的会话接到VSCode里，跟其他插件一样随手选中代码就能问。折腾了半天，终端里直接给我甩了一条看不清头尾的报错：error from provider (console): opencode's free tier can only be used from within opencode。当时我第一反应是模型配置坏了，跑去看key、看模型名、看环境变量，全都没问题。后来才意识到，问题根本不出在模型层，而是我不理解opencode内部的三层结构。理解完这层结构，很多配置和行为才说得通。
1. 别急着调模型参数，先搞懂 opencode 的三层结构
1.1 为什么一个终端工具内部还藏着一个本地服务
很多终端类的AI助手看起来是“一个命令跑起来”，内部其实拆成了壳与服务两层。opencode也不例外：你在终端里看到的交互界面只是一层壳（shell），它负责画界面、接收输入；真正干活的，是壳下面拉起的一个本地服务面。TUI、编辑器扩展、自动化脚本，都是跟这个服务面通信的。
用饭店来类比会更顺：壳层是前厅，服务面才是后厨。你可以换菜单、换服务员，但菜品都是从同一个后厨出来的。你问“为什么不在一个进程里全干完”，原因是服务面需要被多方同时调用。你想让VSCode扩展和终端会话共享同一个上下文，就得有一个独立常驻的服务来统一维护会话状态，而不是每个入口各建一套状态，彼此不知道对方做了什么。
这个设计还有一个隐藏好处：权限控制可以集中。你在服务面里批准或拒绝一次命令执行，所有入口都会遵守同一套规则。实际体验下来，凡是遇到“编辑器扩展连不上”“扩展里能用但终端里报错”这类问题，我第一反应永远是从服务面入手去查，而不是重装扩展或者改模型。而服务面的启动状态、端口占用情况，比配置文件更能说明问题。
1.2 从服务面设计反推免费层限制那条报错
回到开头那条报错。opencode's free tier can only be used from within opencode这句话，字面上是说：opencode的免费额度只能在opencode内部使用。但你一旦理解了服务面，就会发现它其实是在做来源校验。
免费层不是简单给你发一个API key就完事。它会把你的使用约束在opencode自己的服务面上下文里，校验的是“这次请求是不是从opencode发起的”。也就是说，免费额度跟整个服务会话绑定，跟外壳、操作入口强相关。如果你试图把同一个key灌进别的工具、别的客户端，或者自己写脚本绕过了opencode的身份上下文，请求一到Provider那边就会被打回来，然后被转成这条报错。
这个设计思路其实不难理解：免费层本质上是体验入口，不是让你拿去别处当通用资源的。只是它没把原因写在明面上，导致很多人在模型配置里翻半天找不出问题。理解了这一点，后续在第5章我会把这类报错的完整排查链路走一遍。先记住这个结论：服务面是理解opencode一切行为的地基，报错里凡是带“provider (console)”的，多半不是模型参数问题，而是服务来源或额度校验问题。
2. 工具调用机制：agent“动手干活”的核心循环
看懂了架构，下一个问题就是：它到底怎么“自己动手”的。很多人在终端里跟opencode聊天，觉得它跟普通聊天机器人差不多，只是多长了手。实际上它的工作方式完全不一样，背后是一个循环：你给需求，模型返回要不要调用工具、调用哪个工具，服务面负责执行工具，再把执行结果回填给模型，模型根据结果决定继续调工具还是给你最终答案。这个循环会一直走到任务结束。
2.1 工具列表：读文件、改文件、跑命令、搜网页
opencode提供了一组基础工具，覆盖面基本够日常使用。我常用的几个大概如下：
| 工具 | 作用 | 使用场景 |
|---|---|---|
| 读文件 | 查看指定文件内容，支持范围读取 | 让agent了解当前代码逻辑 |
| 写文件 | 新建或覆盖文件 | 生成新模块、写测试 |
| 编辑文件 | 局部替换、打补丁 | 做小范围修改，不整个重写 |
| 执行命令 | 在工作目录里跑shell命令 | 跑测试、lint、构建，验证结果 |
| 搜索文件 | 文件名或内容搜索 | 在大型仓库里定位相关代码 |
| 联网搜索 | 查资料、查API文档 | 模型不知道最新版本/用法时用 |
比如我经常让它“找出这个项目里未使用的import并清理掉”。一个典型的执行流程会是：先搜索项目里所有的import列表，再逐个读相关文件做分析，然后用编辑工具删掉无用项，最后跑一次lint确认没有语法问题。整个过程它自己就能循环推进，不需要我每一步都下指令。
2.2 权限模型：哪些操作要征求同意，怎么配置自动放行
工具能干活，但不可能让它无限制地乱跑。opencode默认会对有副作用的操作征求你的同意，尤其是执行命令和写文件这种。我第一次跑批量重构的时候，每动一次文件都弹确认，点得手都酸了。后来才知道权限规则是可以配置的。
配置集中在项目级或用户级的opencode.json里，通过permissions字段来管理。比如你可以放行npm test、git status这类安全的命令，同时对rm -rf、重定向覆盖之类的危险操作保持默认询问。实际操作中，我的建议是：跑一次性探索任务的时候把权限收紧；确认agent反复用到某几条可靠命令后，再逐步放宽，并把放行规则沉淀到项目配置里。
这里有个值得注意的细节：权限规则的粒度不只到命令名，它通常可以按命令模式匹配，甚至可以区分目录。也就是说，你可以只允许它在src/lib下写文件，不允许动deploy/目录。这种细粒度控制对团队协作特别重要，毕竟不同人对风险的容忍度完全不一样。
2.3 上下文管理：会话、记忆与项目约定
工具调用循环跑得再顺，也绕不开上下文长度的问题。opencode的会话历史会持续累积，但随着对话变长，你会明显感觉到它“忘事”，那不是模型变笨了，而是上下文被塞满了。
我的做法是：给agent开一个新会话时，先写清“只输出变更文件清单，不要一次性贴完整代码”，让它把总结性内容作为中间结果保存到文件里，而不是全堆在对话里。真正复杂的需求，我会先在仓库里写一个项目约定文件，把项目规范、目录结构、常用命令写进去，opencode启动时会自动加载这类文件。这样不管开多少个会话，每个新会话都能读到同一套项目背景，不需要每次都重新描述一遍。
有经验的用户会把这个文件管好，它就是你在跟opencode协作时的“项目说明书”。内容不用长，几行到几十行都行，关键是让agent知道你这个仓库的特殊约定，比如“测试用vitest而不是jest”“上传目录不要提交”“API路由统一放在某个文件夹”。这比你在对话里反复交代要高效得多。
3. 外壳体验：终端TUI和VSCode扩展是怎么协作的
3.1 终端TUI里的常用操作
聊完“里子”，再说说“面子”。opencode的终端界面不只是一个文本框，它是有会话管理的。我常用的操作包括：切换多个会话tab、分段查看工具执行记录、用快捷键调出模型切换面板。刚开始用的时候会有点懵，因为工具调用的输出和模型文本是混在一起的，区分不清哪些是它真跑的、哪些是它编的。我的习惯是时刻关注“工具执行记录”部分，模型说的不一定可信，但工具跑出来的结果是真实有效的。
模型切换这块也值得说。我在终端里最多时同时接了三四个不同的模型Provider，按任务类型切换：简单问答用轻量模型，代码生成用能力强一点的，长上下文整理用额度贵的。在外壳层面切换模型不会中断会话，但新模型能否正确读取已有上下文，取决于它本身的上下文长度，这个切换前心里要有数。
3.2 VSCode扩展是怎么通过服务面连上“内芯”的
很多人问“VSCode怎么和opencode工作”。其实原理就是第1章讲的架构：VSCode扩展不是一个独立的AI客户端，它是服务面的另一个入口。扩展装好后，需要连接到本机运行的服务面，连接成功后，你在VSCode里看到的会话跟终端里的会话是同源的，两边能共享同一个上下文。
实际操作上，我一般是先从终端启动opencode，让服务面跑起来，再打开VSCode扩展去连接。这样能避免扩展自己去拉进程时出现版本不一致的问题。连接成功后，选中一段代码，直接丢给agent，让它解释、重构、写测试，都非常顺手。关键是你不需要在VSCode里重新配一遍模型和key，所有配置都沿用服务面已有的那套。
如果你发现扩展里能用免费层模型，也不用惊讶，这不是漏洞。因为扩展里的请求仍然是从opencode自己的服务面发出去的，只是入口从终端换成了编辑器面板，来源校验自然能通过。反过来，如果你在VSCode里报出“only be used from within opencode”这类错误，先别怀疑是扩展坏了，八成是服务面的会话上下文或key状态出了问题，给它重启一下再说。
4. 实战集成：把 opencode 塞进团队工作流而不是单机玩具
单机玩得再溜，价值也有限。真正让opencode上限变高的，是把它接入团队流程，比如代码审查、持续集成、多人在同一套配置下协作。
4.1 用非交互模式在CI里做自动审查
opencode本身就提供了非交互执行模式，典型场景就是CI。拿GitLab CI举例，我可以做一个MR触发的小job：在流水线里安装opencode，配置一个有额度的key，然后让它以只读审查者的身份跑一遍diff review，把输出写成审查报告附到流水线里。大致结构是这样：
review: stage: test script: - curl -fsSL https://opencode.example.com/install.sh | bash - export OPENCODE_MODEL=some-model - opencode run "review the diff in this merge request, focus on logical errors and security risks; output concise markdown" > review.md artifacts: paths: - review.md when: always注意，这个场景里我特别强调用有额度的key，而不是免费层。原因很简单：CI环境是无头调用，不是opencode自己的交互外壳，免费层的来源校验大概率不让过；就算让过，免费额度的配额和速率也不适合给流水线里的批量任务用。把它当作一条“正式环境必须用正式凭证”的纪律，能帮你少踩很多坑。
团队里第一次引入这种自动审查时，我建议把agent的权限收敛到最小，只允许读代码和写审查报告，不允执行修改命令。给出的报告让开发人员决定是否采纳，而不是让agent直接改代码。自动化审查的价值是省掉第一遍通读的时间，不是代替人的判断。
4.2 Go套餐额度机制：每种模型分开计算，不是一个大池子
社区里经常有人问“opencode go套餐是每种模型分开计算额度吗”，我第一次也搞错过，以为充值后所有模型共享一个大池子。实际按照这类订阅服务的常见设计，额度是按模型维度分别累计的，每个模型各自有额度和速率限制，彼此不混用。
这样设计的原因不复杂：不同模型的单位成本差异很大，混在一起算，便宜模型会被贵模型挤掉，局面很难控。分开算的好处是你能清楚地看到钱花在哪个模型上，好做成本规划。团队用的建议是：在配置里把“默认模型”固定到成本合适的一款，把高成本模型只开放给明确的任务路径，避免agent自作主张频繁切到贵模型上去。
顺带一提，社区里有cc-switch这类用来切换多套模型配置的辅助工具。切换配置的时候注意别覆盖服务面自己的鉴权信息，不然你只是把模型名切过去了，服务面会话上下文里的身份状态可能已经变了，到时候报错又会绕回第1章那个问题。
4.3 项目级配置：一套约定，全组都跟着受益
opencode允许在项目根目录放一份配置，把模型选择、权限规则、工具开关都收进版本库。新成员拉下代码后，不需要手动去调自己机器上的全局配置，opencode的行为就是项目默认的那一套。
我在一个多仓库项目里就是这么干的：前端仓库默认模型用轻量款、放行构建和测试命令；后端仓库因为涉及数据变更，权限收紧很多，执行任何迁移类命令都要人工确认。这些差异不是各人自己记在脑子里，而是直接写进仓库的opencode.json，所有人共用同一套规则。
实际维护中你会慢慢发现，项目级配置本身也是一份文档，记录了这个仓库“允许agent做到什么程度”。对新人来说，这份配置比大段的说明文档更能帮他理解项目的自动化边界。
5. 一次完整的报错排查链路：从 error from provider (console) 说起
5.1 从报错文本到定位，这五步我走了很久才摸顺
回到开头那条让我卡了好几天的报错。这里我不想只给结论，把排查思路完整留个档：
- 先看报错前缀。
error from provider (console)里的“provider”说明问题出在模型服务方的返回，不是opencode本地解析失败。“console”则提示是控制台这一侧的状态，涉及账号、额度、调用许可。 - 区分是“模型没配好”还是“来源被拒”。如果你换一个确定可用的模型仍然报类似错误，那就不是模型路由表的问题，重点查调用许可。
- 检查当前会话用的是不是免费层模型。一旦确认是免费层，同时你又是在扩展脚本、转发服务、或者任何非opencode自身外壳的环境里调用，就极容易触发“only be used from within opencode”。
- 去看服务面日志。日志里通常能查到更细的内容：请求来源入口、当前会话关联的身份信息、以及被拒绝的具体原因。这一步能帮你把范围从“整个配置”缩小到“来源校验条件”。
- 修正调用方式。正式场景换成有额度的key；开发场景确保所有请求都从opencode外壳发起，包括编辑器扩展和终端本身。
这套流程走下来，大多数相关报错都能收敛到“来源校验”或者“额度归属”这一类，不会一直在模型参数里打转。
5.2 其他高频翻车现场：环境变量、模型映射和日志级别
除了来源校验，我实际踩过的高频坑还有几个，顺手列一下：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 改了环境变量不生效 | 服务面还在用旧配置 | 重启服务面进程再试 |
| 报了别的Provider的错误 | 模型别名和真实服务商名字映射写错 | 检查配置文件里的model映射关系 |
| 本地能跑，流水线里不行 | 无头环境的鉴权上下文缺失 | CI里换用正式key并显式配置模型 |
| 行为一会有一会没有 | 权限规则和会话状态不一致 | 统一项目级配置，避免依赖个人偏好 |
排查这个问题的小技巧是学会使用opencode的调试模式。遇到诡异行为时，用调试模式跑一遍，终端会输出大量过程信息，包括具体走的哪条调用链、中途哪个环节被拒。第一次看会比较轰炸，但比瞎猜快太多。
5.3 日志不是给人看的，是给问题留下的线索
说句实在话，opencode这类工具的日志，平时没人愿意读。但报错出现时，它比哪个文档都好使。我的习惯是：拿到一条报错，先把原文完整复制下来，再去日志里搜对应的错误码或关键词，而不是凭印象去猜。
我见过不少人在群里提问时只说“报错啦，怎么办”，却不肯附带日志。抛开信息不全的因素，这类问题的答案往往就是“去看日志里那条提示”。把日志当成排查的第一手现场，很多问题根本不用等别人回复，自己就能定位。
另一个容易被忽略的点是：每次升级opencode后，日志格式可能会变。旧版本里某个错误提示文案，新版本可能换词了。所以排查时尽量用当前版本的日志格式，别拿半年前的记忆去套。
最后分享一点个人的使用习惯。我花了不少时间才把opencode从“挺好玩的终端工具”变成“团队真在用的自动化底座”，靠的不是某一次灵感，而是把每一件值得固定的事都沉淀成文件：权限规则写进项目配置，项目约定写进项目说明文件，排查经验写进团队笔记。下次开新会话、拉新项目，不用从头再趟一遍。这个习惯相当管用。
