opencode这个项目我是从上篇的基础配置开始接触的当时觉得它不过是个能聊天的终端玩具。直到我试图把它真正接到编辑器、CI流水线里跑自动化才发现它的正确打开方式远不是“配个模型然后对话”那么简单。这篇文章是下篇重点放在上篇没深入的三件事工具调用这套执行循环、藏在终端背后的服务面server面架构以及把opencode集成进真实工作流的姿势。如果你已经装好opencode、能正常对话但卡在“不知道怎么让它在项目里自动干活”这篇应该能帮上忙。先讲个我这边的真实场景。有段时间我想把opencode的会话接到VSCode里跟其他插件一样随手选中代码就能问。折腾了半天终端里直接给我甩了一条看不清头尾的报错error from provider (console): opencodes free tier can only be used from within opencode。当时我第一反应是模型配置坏了跑去看key、看模型名、看环境变量全都没问题。后来才意识到问题根本不出在模型层而是我不理解opencode内部的三层结构。理解完这层结构很多配置和行为才说得通。1. 别急着调模型参数先搞懂 opencode 的三层结构1.1 为什么一个终端工具内部还藏着一个本地服务很多终端类的AI助手看起来是“一个命令跑起来”内部其实拆成了壳与服务两层。opencode也不例外你在终端里看到的交互界面只是一层壳shell它负责画界面、接收输入真正干活的是壳下面拉起的一个本地服务面。TUI、编辑器扩展、自动化脚本都是跟这个服务面通信的。用饭店来类比会更顺壳层是前厅服务面才是后厨。你可以换菜单、换服务员但菜品都是从同一个后厨出来的。你问“为什么不在一个进程里全干完”原因是服务面需要被多方同时调用。你想让VSCode扩展和终端会话共享同一个上下文就得有一个独立常驻的服务来统一维护会话状态而不是每个入口各建一套状态彼此不知道对方做了什么。这个设计还有一个隐藏好处权限控制可以集中。你在服务面里批准或拒绝一次命令执行所有入口都会遵守同一套规则。实际体验下来凡是遇到“编辑器扩展连不上”“扩展里能用但终端里报错”这类问题我第一反应永远是从服务面入手去查而不是重装扩展或者改模型。而服务面的启动状态、端口占用情况比配置文件更能说明问题。1.2 从服务面设计反推免费层限制那条报错回到开头那条报错。opencodes 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_MODELsome-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从“挺好玩的终端工具”变成“团队真在用的自动化底座”靠的不是某一次灵感而是把每一件值得固定的事都沉淀成文件权限规则写进项目配置项目约定写进项目说明文件排查经验写进团队笔记。下次开新会话、拉新项目不用从头再趟一遍。这个习惯相当管用。
opencode这个项目我是从上篇的基础配置开始接触的当时觉得它不过是个能聊天的终端玩具。直到我试图把它真正接到编辑器、CI流水线里跑自动化才发现它的正确打开方式远不是“配个模型然后对话”那么简单。这篇文章是下篇重点放在上篇没深入的三件事工具调用这套执行循环、藏在终端背后的服务面server面架构以及把opencode集成进真实工作流的姿势。如果你已经装好opencode、能正常对话但卡在“不知道怎么让它在项目里自动干活”这篇应该能帮上忙。先讲个我这边的真实场景。有段时间我想把opencode的会话接到VSCode里跟其他插件一样随手选中代码就能问。折腾了半天终端里直接给我甩了一条看不清头尾的报错error from provider (console): opencodes free tier can only be used from within opencode。当时我第一反应是模型配置坏了跑去看key、看模型名、看环境变量全都没问题。后来才意识到问题根本不出在模型层而是我不理解opencode内部的三层结构。理解完这层结构很多配置和行为才说得通。1. 别急着调模型参数先搞懂 opencode 的三层结构1.1 为什么一个终端工具内部还藏着一个本地服务很多终端类的AI助手看起来是“一个命令跑起来”内部其实拆成了壳与服务两层。opencode也不例外你在终端里看到的交互界面只是一层壳shell它负责画界面、接收输入真正干活的是壳下面拉起的一个本地服务面。TUI、编辑器扩展、自动化脚本都是跟这个服务面通信的。用饭店来类比会更顺壳层是前厅服务面才是后厨。你可以换菜单、换服务员但菜品都是从同一个后厨出来的。你问“为什么不在一个进程里全干完”原因是服务面需要被多方同时调用。你想让VSCode扩展和终端会话共享同一个上下文就得有一个独立常驻的服务来统一维护会话状态而不是每个入口各建一套状态彼此不知道对方做了什么。这个设计还有一个隐藏好处权限控制可以集中。你在服务面里批准或拒绝一次命令执行所有入口都会遵守同一套规则。实际体验下来凡是遇到“编辑器扩展连不上”“扩展里能用但终端里报错”这类问题我第一反应永远是从服务面入手去查而不是重装扩展或者改模型。而服务面的启动状态、端口占用情况比配置文件更能说明问题。1.2 从服务面设计反推免费层限制那条报错回到开头那条报错。opencodes 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_MODELsome-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从“挺好玩的终端工具”变成“团队真在用的自动化底座”靠的不是某一次灵感而是把每一件值得固定的事都沉淀成文件权限规则写进项目配置项目约定写进项目说明文件排查经验写进团队笔记。下次开新会话、拉新项目不用从头再趟一遍。这个习惯相当管用。
