上周我在新装的机器上把 opencode 拉起来刚起一个新会话就撞见一条报错error from provider (console): opencodes free tier can only be used from within opencode。第一反应是怀疑自己把 provider 接错了查了一圈发现不是配置格式问题而是对“服务面”的理解有问题。正好那几天微博上不少读者留言问“vscode 怎么和 opencode 工作”也有人问“如何通过 opencode 搭建一个 skill”。这两个问题恰恰是 opencode 从“能跑”到“好用”之间的两个台阶中间还夹着一个“外壳”问题。这篇“下篇”就把工具、服务面、外壳和实战集成一起说透。适合已经装好 opencode、能跑通一次简单对话但对 provider 配置、扩展 Skill、和编辑器协作还有不少模糊地带的读者。1. 为什么要把 opencode 拆成工具、服务面、外壳三个层面看很多人在用这类终端里的 AI 编码工具时会陷入一个误区把它当成一个“黑盒聊天框”。我prompt里有需求它输出代码完事。但实际上 opencode 这类 agent 类工具的架构比普通聊天机器人多出一大截你只有把它的工作方式拆成三层来看才能解释清楚很多凭直觉理解不了的行为。1.1 我的运营视角黑盒聊天框为什么不够用如果你只是把代码贴进对话框让它改那你用的是它的“对话能力”而不是“工具能力”。opencode 真正值钱的地方在于它能自己去读项目文件、执行 shell 命令、跑测试、再看结果决定下一步。要做到这一点它需要知道三件事模型从哪里来、手里有哪些工具、界面怎么呈现。这三件事被我习惯性地叫成服务面、工具面、外壳。我之前帮团队里的同事排查问题他一上来就说“opencode 老是看不懂我的项目”结果我看了一眼他的配置provider 用的是默认免费模型上下文窗口小工具调用能力也弱文件一多就顾此失彼。这不是 opencode 的问题这是服务面选错了。反过来有人配了很强的大模型但 skill 里没有定义清楚调用边界AI 一上来就全仓扫文件输出跑偏这是工具面没做好。还有一部分人明明功能都通了但操作界面乱糟糟每次上下文都要滚动半天这是外壳层面没调舒服。1.2 三个层面分别解决什么问题服务面解决的是“AI 的脑子从哪来”是官方免费模型、你自己申请的模型 API key、还是本地跑的模型。它决定了能力上限、成本、以及隐私边界。工具面解决的是“AI 的手能伸多远”能不能读写文件、跑 shell 命令、调用浏览器以及通过 skill 给它装配固定动作流程。外壳解决的是“你每天实际接触的界面长什么样”终端 TUI、极简专注模式、VSCode 里的集成姿势以及衍生客户端和配置管理工具。理解了这个三层模型后面看任何 opencode 的问题都不会懵。遇到报错先问自己这是服务面问题、工具面问题还是外壳问题很多时候答案一目了然。比如那条 free tier 报错明明白白是服务面问题跟你的技能、外壳都没有关系。2. 服务面模型 Provider 的接入逻辑和那条免费额度限制的本质opencode 本身不是一个模型服务商它是一个容器。它通过 provider 配置去对接不同的模型来源你可以接官方内置的免费额度也可以接自己的 key甚至本地模型。这一章我把 provider 配置、免费额度那条报错、模型怎么选、套餐额度怎么算几件事一次说清。2.1 provider 配置的通用骨架别看文档先看结构不同版本 opencode 的配置文件位置有点差别但思路是一致的。常见的做法是在配置目录下声明 provider每个 provider 包含 baseURL、apiKey 和 models 列表。下面是一个典型的 provider 配置骨架看起来大概长这样{ provider: { my-provider: { npm: ai-sdk/openai-compatible, name: My Provider, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_PROVIDER_API_KEY} }, models: { fast-model: { name: Fast Model, limit: { context: 32000 }, cost: { input: 0.5, output: 1.5 } } } } } }注意我用的是通用结构具体字段名不同版本可能略有差异但逻辑是通用的告诉 opencode 去哪个地址、用谁的 key、有哪些模型可用。这里有几个容易踩的点。第一apiKey 里写成{env:XXX}的意思是从环境变量读取不要把密钥直接硬编码进配置文件。我见过有人为了省事把 key 明文写在opencode.json里结果不小心提交到仓库后面被扫描工具通知勒索被迫轮换密钥非常狼狈。第二npm字段表示用哪个 SDK 驱动这个 provider一般情况下 openai-compatible 类型可以兼容大多数模型网关。第三models 里的limit和cost是给 opencode 做“路由决策”用的不是强制限制但如果你用多家模型混跑这个字段能帮你观察每次会话花了多少钱。2.2 免费额度报错的真实含义先读懂再处理开头提到的那条报错error from provider (console): opencodes free tier can only be used from within opencode字面意思是“opencode 的免费额度只能在 opencode 内部使用”。其实这是官方对免费额度做了一层调用环境校验当检测到请求不是从官方客户端内部发出来时就直接拒绝。这件事的关键不是“怎么绕过去”而是理解它的定位免费额度是官方产品的一个推广属性用来让你在原生环境里体验它的能力它不是面向所有 API 调用者开放的免费 API。实际操作中如果你需要稳定的、大额度的模型服务正确做法是配置自己的模型 key或者使用官方付费套餐。非要通过第三方包装去绕过这个校验技术上也许能折腾但风险很高一方面违反服务条款另一方面关键路径依赖一个和你没有契约关系的通道哪天服务方调整策略你整条工作流就断了。合规使用的建议很简单免费模型拿来体验流程、跑小型 Demo正式项目或长期任务接一个按量付费的 provider 作为主力敏感代码用本地模型。这样既不会被额度限制卡脖子也不会在关键时候掉链子。2.3 免费模型、自带 key 的模型、本地模型三者在实操里怎么取舍网上常有人问“opencode 与 deepseek hermes 哪个好”这种问题其实把变量混在一起了。opencode 是客户端外壳deepseek 是一个模型家族hermes 风格模型通常是社区微调产物两者不是同一层的东西。真正的问题是在 opencode 里接哪类模型作为主力我给你一个简单的对照表按你自己的情况选方案成本稳定性隐私能力适用场景官方免费模型免费中等受额度限制数据会送到服务方适合轻量任务体验功能、跑通流程自带 key 的云模型按量付费高取决于服务方 SLA数据会送到服务方强可选大窗口日常主力、项目开发本地模型硬件成本高取决于本机资源数据不出本机取决于型号大小敏感代码、离线环境衡量模型适配 opencode不要光盯着跑分重点看四个维度工具调用的遵循度、上下文窗口是否匹配你的代码库规模、代码输出风格是否符合团队习惯、费用和隐私是否可接受。工具调用遵循度是最容易忽略的一点因为 opencode 这类 agent 的运转方式是先让模型决定“下一步调用哪个工具”如果模型不擅长 tool calling再强的对话能力也发挥不出来。建议你在小范围代码库里同时接入两个候选模型跑一遍同样的需求直接看谁的执行链路更合理比看 benchmark 有用得多。2.4 “套餐是每种模型分开计算额度吗”计费模型的两种常见模式很多人在问 opencode go 套餐的额度是不是每种模型单独算这其实取决于服务商。我自己总结下来就两种模式共享额度池和模型独立配额。共享额度池的意思是你买一个套餐里面的所有模型共用一个限额用哪个模型都从这个池子里扣。这样灵活性高但很可能被某个便宜模型吃光总额度。模型独立配额则是每个型号单独计数比如快模型每月 X 万 token、强模型每月 Y 万 token彼此不挪用。好处是每一类任务都有兜底坏处是人多的时候小模型额度经常用不完。实操建议在 opencode 里给每个 provider 配置一个“预算上限”或请求频率限制别等扣费账单出来再拍大腿。如果你团队共用账号优先选带独立配额的套餐并把大模型请求设成需要审批的权限避免一次批量任务把整月额度打穿。顺便说一句别只看单次价格还要算上下文成本——一个 32000 token 上下文的模型如果上下文利用率低同样的请求量费用可能比大窗口模型还贵因为输出 token 单价摆在那里。3. 工具面内置工具、Skill 和可控的 Agent 工作流服务面搞定之后opencode 的“脑子”就有了。但脑子再好手伸不出去也没用。工具面这层回答的就是“AI 具体能做什么”以及“你能约束它做什么”。这也是“如何通过 opencode 搭建一个 skill”这类问题的落点。3.1 内置工具面读写文件、执行命令、采集上下文一样都不能少opencode 这类终端 agent 的工具面通常包含几类能力文件读写和编辑、shell 命令执行、目录和文件搜索、以及读取 git 状态。它通过工具调用协议让模型按需选择而不是把整个仓库硬塞到上下文里。实际用下来我最大的体会是工具面越强大越要控制边界。默认情况下有些版本的工具会允许 AI 直接执行 shell 命令包括安装依赖、修改文件、甚至 push 分支。提升协作效率的同时也需要给它画好跑道。我个人的习惯是按“最小权限、逐步放权”的原则来配置。初始阶段只允许它读文件和跑 test 类命令跑一阵确认它的行为符合预期后再放开格式化、批量替换类的写操作等完全信任了才允许它执行构建和发布相关的命令。不要一上来就全放开尤其是团队合作的项目里它可能不理解哪些分支是保护分支哪条命令会触发 CI/CD随手一个破坏性操作别人一天的活儿就白干了。3.2 如何通过 opencode 搭建一个 skill从零开始的可复现步骤Skill 的本质是一段带触发条件的结构化指令文档。它不是一个程序不写逻辑代码而是告诉模型“当用户想干某事时按这个流程执行”。这也是 opencode 这类工具和普通聊天框之间一个巨大的分水岭。下面我用一个“自动生成 PR 描述”的 skill 作为例子走一遍完整搭建流程。第一步先找到 skill 目录。不同版本 opencode 对 skill 的存放路径不太一样一般是在配置目录下的 skills 文件夹里。你可以执行opencode --help或查看官方文档确认。如果你用的是某种衍生版本路径可能被改掉建议直接在配置里搜索 skillsDir 关键词。第二步在目录下新建一个 Markdown 文件文件名建议和功能名一致比如pr-description.md。文件头部写 frontmatter声明 skill 的名称和描述特别是描述里要写清楚“什么情况下触发”。这一步决定了模型在会话中是否会把用户请求路由到这个 skill。--- name: pr-description description: 根据当前分支的 git diff 和最近的 commit 生成 PR 描述。当用户要求写 PR、合并请求描述时优先使用。 --- 任务流程 1. 执行 git diff main...HEAD --stat了解改动覆盖的文件范围。 2. 执行 git log main..HEAD --oneline提取提交信息要点。 3. 按以下模板输出 PR 描述 - 背景为什么做这个改动 - 改动按模块列出变更点 - 测试方式对应仓库内真实存在的测试脚本 - 风险点涉及迁移、破坏性变更的部分 限制 - 不得编造 commit 或 diff 中不存在的内容。 - 测试方式必须基于仓库里实际可执行的命令。第三步在 opencode 会话里说“帮我写这个分支的 PR 描述”观察它是否自动套用 skill。如果没有触发回去看 description 是不是写得太泛或太具体。描述太泛会导致无关请求匹配到这个 skill太具体则会导致该触发的时候不触发。这一步反馈迭代通常要试两三次才能稳定。第四步逐步优化 skill 内容。比如你可以追加一条“如果 diff 超过 500 行先按模块拆分避免一次性输出过长描述”。这类细节是根据真实使用反馈逐步沉淀下来的单独用一次就想完美基本不现实。3.3 Skill 的进阶玩法多个 Skill 组合工具面才真正成型单个 skill 只是把一次提示词模板化真正高级的是让多个 skill 组合成一个工作流。比如我最近做“代码评审”这个场景就用到了两个 skill 的串联。第一个 skill 叫“diff-review”负责拉取指定分支的 diff并逐文件过一遍变更点标记可疑改动。第二个叫“test-plan”它拿到可疑改动后自动生成一份测试计划列清楚要跑哪些测试用例、覆盖哪些分支逻辑。在实际使用中你可以在第二个 skill 的指令里明确写“调用 test-plan 前先执行 diff-review并把它的输出作为输入”。这样模型就会按照你编排的顺序执行而不是东一榔头西一棒子。这个“skill 之间组合、再叠加内置工具调用”的玩法才是我说的工具面的真正价值。你完全可以让 opencode 变成一个自动化的编码搭子贴需求、它做计划、写代码、跑测试、出评审报告你在旁边只做关键节点的审批。4. 外壳终端 TUI、极简模式和多客户端协同服务面和工具面都是“芯”外壳则是你每天肉眼看到的东西。同样一个模型服务外壳设计得好不好直接影响你的使用频率。opencode 的外壳分为三层终端 TUI 本身的交互、极简专注模式就是人们常说的 opencode zen 模式、以及 VSCode 联动或衍生客户端这层“外部壳”。4.1 终端 TUI别小看快捷键和布局opencode 默认跑在终端里核心呈现方式是 TUIText User Interface。它通常是多栏布局左边是会话列表中间是当前对话底部是输入框。功能上它更像一个精简版 IDE而不只是一个聊天框。实际使用中我强烈建议你把快捷键过一遍。比如如何新建会话、切换会话、中断当前 AI 执行这些操作一旦熟练效率会有明显提升。很多人抱怨 opencode 输出太长滚得头晕其实是因为没学会用快捷键折叠或跳转。这里分享一个我个人的习惯把终端字体调大、背景透明度调低只保留当前会话窗口。因为 agent 类工具的输出本身就长再叠加上系统其他终端日志视觉噪音会成倍增加。4.2 zen 模式的适用场景沉浸式驾驶和前台的取舍opencode zen 这种极简模式核心思路是把界面退化成一屏纯净的对话流去掉侧边栏、状态栏、各种辅助信息让你只专注于当前任务。好处是信息熵低适合长时间的一对一深度任务坏处是你会丢失部分上下文面板比如文件列表或会话列表。我自己的使用姿势是这样的处理一个复杂重构任务时打开 zen 模式全屏只留对话和输出专注度确实高但如果是巡查多个项目、需要频繁切换会话的场景我会退出 zen保留会话列表和状态信息。有些人把 zen 当成“高级模式”其实不对它只是一个设计取舍不是一个更高阶的能力开关。按场景切换外衣内核还是同一套东西。4.3 衍生客户端和配置管理工具生态热的背面是配置迁移能力现在市面上已经能看到 opencode go 这类衍生形态以及 cc-switch 这类用于切换不同 AI 编码工具配置的管理工具。这说明 opencode 的生态已经不局限于官方 CLI。但在这里我要提个醒用的客户端可以变配置的可迁移性必须保住。我的建议是把 provider 配置、skill 配置、环境变量清单都独立管理最好能放进一个 git 仓库里。这样无论是官方 CLI、衍生客户端还是 VSCode 集成你都能快速复用同一套体系。我在换新机器时最怕的不是重新下载二进制而是各种配置文件散落各处环境变量忘了导出skill 目录找不到。现在我把这些统一放进 dotfiles 仓库新机器三分钟就能恢复同一个开发环境。这个习惯省下的时间不是一次两次而是每次换环境都在省。5. 实战集成VSCode 联合 opencode 的完整工作流热词里好几个都跟 VSCode 有关比如“vscode 怎么和 opencode 工作”。这一章聚焦这个高频问题给你一套能直接落地的方案再配上一个完整闭环案例。5.1 VSCode 里和 opencode 协作的三种姿势第一种是最简单的直接在 VSCode 的集成终端里跑 opencode。快捷键 Ctrl 打开集成终端切到项目根目录执行 opencode。这种方式的优点非常明显opencode 的工作目录和 VSCode 打开的是同一个文件夹它读到的相对路径、git 状态和你编辑器里看到的完全一致。你用编辑器打开文件看到第 42 行它改的也是同一份文件上下文不会错位。第二种是把集成终端拆成独立面板利用 VSCode 的终端分屏能力。左边主编辑器写代码右下角面板跑 opencode。需要它看代码时直接选中一段代码复制进对话框它改完文件后你切回编辑器查看 diff。这种方式适合频繁切换“写代码”和“问 AI”节奏的场景。第三种是使用外部终端窗口把 VSCode 和 opencode 分开。好处是互不抢占屏幕空间坏处是路径一致性需要自己维护偶尔会出现 opencode 在错误的目录里运行跑来跑去找不到文件的情况。我个人推荐前两种尤其是第二种平衡了信息密度和操作流畅度。5.2 一个完整闭环案例从需求到 PR 的辅助工作流纸上谈兵没意思我走一遍实际跑通的工作流。假设需求是给项目加一个--no-cache参数让某条命令在运行时跳过缓存读取逻辑。第一步我在 VSCode 集成终端里启动 opencode把需求原文贴进去并附加一句限制“只修改 src/command 目录和相关测试不要碰配置文件”。这句话很关键等于在开工前先画了边界避免 AI 顺手改动无关文件。第二步opencode 给出计划列出要改的两个文件和一个测试文件。我看了一眼计划觉得合理让它直接开始。执行过程中它先读取当前命令解析逻辑定位参数处理位置然后写入新参数再调用测试命令验证。我全程没有干预它的小步骤只在它准备跑测试时盯着输出。第三步测试通过后我让它生成一份变更总结并运行 skill 里的 pr-description 生成 PR 草稿。我没有让 opencode 直接 push 分支因为这是底线AI 改代码可以push 需要人来把最后一道关。我手动创建分支、提交、推送然后在 PR 页面粘贴它生成的描述稍微润色后发布。这个闭环看起来不复杂但每一步都有人的判断点边界限制、计划确认、测试验证、最后的人工审查。这些节点缺一不可。5.3 集成过程中的常见问题排查顺序如果你在集成环境里跑 opencode 遇到“找不到命令”或“环境变量丢失”别急着重装。先按这个顺序排查。先在普通终端里跑which opencode确认二进制路径存在。再跑echo $PATH看当前 PATH 是否包含该路径。如果在普通终端正常、VSCode 集成终端里失效基本可以断定是 PATH 不一致或终端启动配置没加载。常见原因是集成终端启动时用的 profile 文件和普通终端不一样尤其是 macOS 上 zsh 的.zprofile与.zshrc加载时机差异。解决办法是把 opencode 相关的环境变量和路径写入.zprofile或者直接在 VSCode 设置里指定集成终端的默认 profile。另一个常见坑是版本管理器如 nvm、fnm导致的 node/环境不一致。opencode 如果依赖 node 运行时PATH 里切换过 node 版本后有可能会出现某些 SDK 找不到的情况。这类问题一句话总结先在普通终端确认能跑再对比两种终端的环境变量差异就能定位。6. 三条边界问题额度、权限和数据的红线讲完上面的集成方法我想专门说一下边界这是我用了很久之后才形成的判断。很多文章只教你怎么用不告诉你哪里不能碰等碰了出事才后悔那代价就大了。6.1 免费额度的边界报错是信号不是待绕过的障碍回到开头那条 free tier 报错。它实际上在提醒你两件事第一你现在用的是官方提供的推广额度它绑定的是官方客户端环境第二如果你把它挪到别的调用环境中使用服务方有权拒绝。除非你确实搞清了授权边界否则不建议尝试各种绕过方式。更合适的做法是把它看作一个免费的试用台测试完流程后要么按量付费要么换本地模型根本不需要在那一条报错上死磕。我自己现在的做法是免费额度只用来跑小 Demo 和验证 skill 触发日常正式开发全部走自己的 key敏感仓库直接切本地模型。6.2 工具自动执行命令的权限边界最小权限、逐步放权opencode 很强大但强大本身就需要约束。特别是 shell 命令工具如果完全放开它可能会在某个不给你确认的机会下执行一条影响面很大的命令。我的经验是在配置里开启命令确认模式或者至少给写操作加一个白名单。第一次和 opencode 协作时我让它“修一下构建脚本”它直接执行了替换好在替换内容并没问题但我没亲眼看过那条命令这件事本身就很吓人。从那以后凡是它会执行写操作的场景我都要求它先列出命令清单由我确认后再执行。哪怕多花十几秒也值得。6.3 数据与隐私的边界远端模型意味着你的代码会被发送出去最后一条是最容易被忽略的你用 opencode 接云端模型时你喂给它的 prompt、它读过的文件内容、它产生的上下文本质上都会经过模型服务商的服务器。如果你的项目里有未发布的源码、客户数据、内部业务逻辑默认用公共模型就是把机密信息暴露给第三方。敏感场景下我的做法是三条一是能本地跑的模型优先本地哪怕能力弱一点但数据不出机器二是非本地不可时对代码做脱敏把变量名、表名替换成占位符后再贴给 AI三是团队里明确规范公司私有仓库不允许默认接公共模型除非经过审批。这不是谁的强迫要求而是你只要做过一次安全事故预演就会认同这条边界必须画清楚。边界问题不是唱反调而是为了让工具走得更远。opencode 是个好工具但好工具用在不同场景里配套的策略也完全不同。我把这些年的实践拆成三层写出来希望能帮你少走一些弯路。下一篇文章我计划写一些 skill 组合编排的高级用法到时候再和大家细聊。