如果你用过 Claude Code 再回头看 opencode会有一种“这工具怎么越做越像个活物”的感觉。上篇讲完了基础安装和日常用法这篇我打算把大家问得最多的几个层面一次性聊透opencode 在整套 AI 编码工具链里到底处于什么生态位、它的模型服务面尤其是免费 tier 和 go 套餐是怎么回事、终端和 VSCode 的外壳集成有哪些坑以及最后怎么从零搭一个真正能用的 Skill 接到自己的工作流里。这几个话题几乎覆盖了最近社区里关于 opencode 的大部分问题包括那个最经典的error from provider (console): opencodes free tier can only be used from within opencode报错。1. opencode 的定位终端 Agent 而不是又一个 IDE1.1 为什么上篇之后我还要单独谈“工具”这件事很多人第一次打开 opencode 会下意识拿它跟 Cursor、Continue 这类编辑器插件对比然后很快产生疑惑这东西怎么连代码补全都没有对话框也这么朴素其实这是把它放错了坐标系。opencode 的定位更接近 Claude Code——它不是一个帮你打字的编辑器而是一个跑在终端里、能自己调工具、自己改文件、自己执行命令的 Agent 运行环境。它负责的事情是“理解任务、拆解步骤、调用工具、验证结果”而不是每一行代码都等你确认。这一点没想清楚后面所有配置都会别扭。比如你会纠结“为什么 opencode 没有代码高亮提示”但实际用的时候你根本不需要它高亮因为你是让它改代码不是手写代码。把这个心智模型切换过来后面看它的服务面、外壳、Skill 机制都会顺很多。1.2 与 Claude Code、Cursor、Continue 的横向对比我用一张表把几个常见工具的本质区别列出来看完你就知道什么场景选什么工具本质形态擅长任务不擅长的场景Cursor编辑器 补全 对话手动编码时的智能补全、单文件修改跨多文件的自主重构、长链路任务ContinueIDE 插件/SDK嵌在现有编辑器里的对话补全独立终端里自主执行命令Claude Code终端 Agent多步骤任务自主执行、工具调用视觉化编辑、交互式调试opencode终端 Agent 可自定义 Skill类似 Claude Code但模型/服务商更开放需要强 GUI 支持的场景说实话Claude Code 和 opencode 是同一类东西真正的差异在开放度。Claude Code 默认绑定 Anthropic 的服务生态虽然也能改环境变量接别的opencode 从设计上就把“ provider 可插拔”放在了第一位你想接 DeepSeek、本地 Ollama、各种聚合网关都行。所以我会把 opencode 定位成“中立终端 Agent 壳”这是它跟 Claude Code 最大的区别也是很多人从后者迁过来的核心原因。1.3 核心概念Session、Provider、Skill 是怎么串起来的用 opencode 的过程其实就三个概念Session会话、Provider模型服务商、Skill技能包。Session 是你和 Agent 之间的一次连续对话它保存在本地可以随时恢复。Provider 决定这次会话的大脑是谁opencode 启动后你可以用/model随时切换而不用重启程序。Skill 则是一份提前写好的“角色设定 工作流程”类似给 Agent 塞了一本操作手册。打个比方Session 像是你在公司里的一个项目文件夹Provider 像你这次项目请哪位顾问Skill 像你给顾问的一套公司规章制度。三者互相独立又可以组合同一个 Session 里前半段用便宜模型做草稿后半段切到更强的模型做精修中间随时让 Agent 加载一个 Skill 改变工作方式这套组合拳才是 opencode 真正的玩法。2. 服务面免费 tier 限制、go 套餐额度与模型接入2.1 那条报错的真实含义免费额度绑定了运行环境如果你在第三方环境里用 opencode 的免费模型大概率会遇到这个报错error from provider (console): opencodes free tier can only be used from within opencode我最初以为这是网络问题或者密钥写错了后来才发现它根本不是技术故障而是策略限制。opencode 控制台给每个账号提供了一些免费额度但服务端会校验发起请求的客户端来源——只有在 opencode 官方客户端环境里发起的请求才会放行你通过 VSCode 插件、cc-switch 这类切换工具、或者自己写脚本去调它的免费通道都会被拒。想明白这条逻辑之后处理方案就清晰了要么老老实实在 opencode 终端里用这个免费额度要么别把免费额度当成主力去接真正属于你自己的 API Key。很多人一上来图省事填了免费通道然后发现换到编辑器插件里就报错其实不是配置错了而是你踩了它的“环境绑定”设计。这一点官方文档写得不算醒目踩过的人基本都懵过一阵。2.2 opencode go 套餐按模型分开算额度是个什么体验再来说 opencode go 套餐。这个套餐本质是官方推出的聚合订阅服务一次订阅能用到多家模型不用你自己分别注册各家 API。社区里问得最多的一个问题是套餐额度到底是总量池还是分池我明确说按模型分开计算额度。也就是说套餐里 Claude 系列的用量、GPT 系列的用量、DeepSeek 系列的用量是各自独立的池子用光了其中一个并不会把另一个的额度挪过来。这个设计其实合理因为不同模型的上游成本差很多合在一起算总额度的话所有人都会只挑贵的模型用套餐根本撑不住。但它对使用习惯的影响很大你以为买了套餐就随便用结果某一天发现 Claude 的池子烧完了GPT 还剩一大半这时候你就只能切模型。所以用 go 套餐的正确姿势是别死磕某一个模型谁有配额用谁配合 opencode 的/model切换反而很舒服。顺带一提 go 套餐的 v2 版本出来后配合 cc-switch 这类 provider 切换工具很多人以为可以把 go 的额度导到其他客户端用。这里提醒一句这类操作能不能成功是一回事协议允不允许是另一回事服务端策略一变你可能突然就断了别把生产环境的稳定性押在这种灰色操作上。2.3 自己接模型DeepSeek、Hermes 等不同路线的取舍如果不走官方套餐自己接模型是 opencode 的另一大乐趣。社区里最常拿来对比的是 DeepSeek 系和 Hermes 系。我的实际体验是日常编码任务DeepSeek 系列更稳尤其是工具调用Function Calling的格式遵循度、多轮对话的上下文一致性明显比很多开源模型强。Hermes 系我也试过它的风格更“话痨”创意写作类任务有意思但在严格的“改代码—跑测试—报错重试”循环里稳定性差一点。如果你在 Ubuntu 上跑 opencode 并且打算本地推理我建议优先考虑显存能装下的量化版本然后设好较低的温度参数0.2 左右否则模型自由发挥的空间太大Agent 经常改出莫名其妙的代码。云端 API 则优先看三件事上下文窗口、价格、限流策略。上下文小于 64K 的一律不建议用来做 Repository 级任务因为 opencode 会把多文件内容塞进上下文窗口太小会频繁截断。2.4 兼容层接入不是只有官方渠道一条路还有一类服务是聚合网关或者中转服务比如社区经常提到的 JeV 这类“接入 Claude Code”的思路。它的玩法其实不复杂Claude Code 支持通过环境变量覆盖 API 地址和密钥你只要有一个兼容 Anthropic 协议的服务端设置好ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN就能把流量导向任何兼容服务。opencode 因为 provider 设计更开放同样可以这么接只是配置文件写法不同一般在 opencode.json 里声明一个自定义 provider填上 baseURL 和 apiKey 就行。我个人的建议是这类兼容层适合“尝鲜”和“备用通道”不适合做唯一依赖。因为兼容层的稳定性取决于上游服务商它今天能用、明天可能就限流你今天调通了的配置、下周可能就失效。真要长期用还是得回到官方 API 或者本地模型两条主路上来。3. 外壳集成Ubuntu 安装、VSCode 与终端实操3.1 Ubuntu 下安装 opencode 的三种方式和我的推荐先解决一个高频问题Ubuntu 怎么装。官方提供了好几种方式实测下来我给三个选项官方一键脚本适合懒得折腾的人但注意它会写入系统级目录需要 sudonpm 全局安装适合你本来就要装 Node 环境升级方便直接下载二进制包适合不想引入 Node 依赖的场景。我自己的选择是 npm 全局安装因为要配合其他前端工具链Node 反正都在。安装完第一步先跑opencode auth login它会引导你完成控制台登录如果你要自接模型就直接改配置文件不用走这个命令。有一点很多人忽略装完之后确保 shell 里能直接opencode --version如果提示找不到命令大概率是 npm 全局 bin 目录没进 PATH跟 opencode 本身无关。Ubuntu 下还会遇到一个跟系统相关的小问题某些终端字体对 opencode TUI 的图标渲染不全显示成方框。解决办法是装一个 Nerd Font 字体并在终端配置文件里启用这一步虽然不影响功能但影响心情建议提前搞定。3.2 VSCode 集成编辑器面板里的会话不只是一个“终端”VSCode 怎么和 opencode 一起工作这也是高频问题。官方的做法是装 opencode 扩展装完后你可以从命令面板启动一个新会话或者 attach 到终端里已经存在的会话。注意这里的差别attach 模式只是把终端里的 opencode 画面“接到”编辑器面板里看你在面板里的操作仍然作用于原来的会话新建会话则是从头开始。我试过两种日常更推荐 attach因为终端里已经跑着的会话保留了完整的上下文和文件变更记录你切到面板只是换个窗口看它干活。如果是新开会话还要重新说明项目背景对于已经开发到一半的项目来说很啰嗦。另外VSCode 扩展能读取当前打开的文件作为上下文这意味着你可以直接对 Agent 说“把当前文件的函数拆出去”它知道你说的是哪个文件这个体验比纯终端好不少。有个小坑是扩展版本和终端里的 opencode 版本不一致时有时候 attach 会失败或者只读。遇到这种情况别急着重装先对比一下两边版本一致了再试。我踩过一次折腾半天发现是版本差了一位。3.3 终端外壳里的高频操作斜杠命令、文件与快捷键不管在 VSCode 里还是纯终端里opencode 的交互逻辑是一样的。说几个我每天必用的输入/model随时切换模型切换后对话上下文保留这个比很多工具强输入/skill可以查看和加载已安装的 Skill在对话里用文件名显式引用文件比贴一大段代码进来清爽得多选中输入框内容后Tab 可以快速补全历史。快捷键方面CtrlL清空上下文、CtrlD退出当前会话这类基础操作就不多说了。这里重点提醒一个使用习惯opencode 的上下文是累积的一个长会话到后期会越来越慢、越来越贵。我现在的做法是一个任务干完立刻用CtrlL清空或者直接开新会话只保留需要延续的信息。不要养成“一个 Session 用一天”的习惯那是把它当成普通聊天软件了Agent 的上下文很贵。至于 opencode 新出的 zen 模式如果你喜欢极简界面切过去之后侧栏和状态栏都会收起来整个屏幕只有对话区纯写代码的时候干扰确实少。但这只是界面变化功能没有增减用不用看个人口味。4. 从零搭一个 Skill代码审查与提交信息生成的实战4.1 Skill 机制原理不过是一份写得很好的提示词包有人把 Skill 说得很玄其实拆开看就是一套有结构的提示词包一份说明文件加上可选的一些引用资源放到指定目录下opencode 就能识别它。Agent 在合适的时候会读这份提示词包然后按照里面定义的角色和工作流来执行任务。你可以把它理解为“给 Agent 发了一份岗位说明书”。没有 Skill 时Agent 只凭系统提示词干活像个什么都会但没经验的新人有了 Skill它就有了具体岗位的工作规范知道先做什么、后做什么、输出长什么样。这也是“如何通过 opencode 搭建一个 skill”这个问题的核心答案——不是写代码而是组织好提示词。4.2 Skill 文件结构frontmatter、说明与引用资源Skill 目录一般在~/.config/opencode/skills/下面每个 Skill 一个子目录核心文件是 SKILL.md。它的结构长这样~/.config/opencode/skills/ └── commit-helper/ ├── SKILL.md └── rules/ └── commit-style.mdSKILL.md 开头必须有 YAML frontmatter至少包含 name 和 description 两个字段。description 至关重要因为它是 opencode 判断“什么时候该用这个 Skill”的依据写得越具体触发越准确。后面紧跟正文正文里写清楚角色、执行步骤、输出格式、参考标准。--- name: commit-helper description: 当需要生成 git 提交信息或 review 当前提交时使用。尤其适用于用户输入 commit、提交信息、commit message 等关键词时。 --- # Git 提交助手 你是一名熟悉 Conventional Commits 规范的工程师。 请严格按照以下步骤执行 1. 运行 git status 查看工作区状态 2. 运行 git diff --staged 获取暂存区变化 3. 根据变化类型feat/fix/docs/refactor 等生成提交信息 4. 如果存在 rules/commit-style.md以其中的风格为准这里有个容易被忽略的细节description 不要写得太宽泛比如“处理 git 相关操作”因为宽泛描述会让 Agent 动不动就加载这个 Skill反而干扰了其他任务。我的经验是把触发词写具体宁可让它错过触发也比误触发好。4.3 两个可以直接用的 Skill 示例第一个示例就是上面这个 commit-helper。如果你希望它严格遵守团队规范可以把规范单独放在一个文件里引用这样修改规范不需要动 SKILL.md维护起来很清爽。我自己会把提交信息语言、是否加 issue 编号等规则都放进去生成出来的 commit message 基本不用改。第二个示例是代码审查 Skill这个比 commit 更实用--- name: code-reviewer description: 当用户要求 review 代码、审查 PR、检查代码质量时使用。 --- # 代码审查专家 你是一名资深代码审查员请从以下维度审查变更 1. 安全性SQL 注入、路径穿越、敏感信息硬编码 2. 可维护性重复代码、魔法数字、函数复杂度 3. 性能明显低效的循环、无索引查询、无谓的对象拷贝 4. 边界空值处理、并发安全、资源释放 输出格式 - 按严重程度从高到低列出问题 - 每个问题标注文件、行号、问题描述、修改建议 - 最后给出总体结论通过 / 需修改后通过 / 不通过我把这个 Skill 安装后直接绑到了提 PR 之前的流程里让 Agent 先按这套标准自检一遍比自己肉眼查效率高很多。4.4 Skill 与工作流联动自动加载、团队共享、版本管理Skill 装好之后不用手动激活opencode 会根据当前对话内容自动决定是否加载。如果你希望特定项目强制使用某个 Skill可以在项目的.opencode/skills目录里也放一份这样跟着项目走team 成员 clone 下来就有同样配置不用大家各自手动装。版本管理上我强烈建议把整个 skills 目录纳入 dotfiles 仓库。这样换新机器只需要一条命令同步下来不用重新凭记忆重建。团队协作的话Skill 文件本身是纯文本review 起来很容易而且因为它是提示词不是代码非工程师同事也能参与维护。我们组现在的做法是谁发现某个重复性工作能让 Agent 干就写一个 Skill 提交到仓库Review 通过后大家共用。这套机制跑起来之后Agent 的实际利用率提升非常明显。5. 踩坑记录三条让我差点卸载的报错与排查过程5.1 报错一免费额度只能在 opencode 内使用这节专门讲坑。第一个坑就是前面提过的 free tier 报错我遇到时候的完整排查链路给你们复盘一下。报错出现后我第一步检查配置文件确认 provider 名字和 API Key 没写错——结果是对的。第二步去控制台看额度发现免费额度还在——问题没解决。第三步我把同一个 Key 拿去 curl 测试发现能通——这就奇怪了。最后我去翻社区的 issue 才明白是服务端校验了客户端来源。当时的感觉是庆幸又无语庆幸不是配置问题无语于这个限制确实藏得深。排查思路记住一个原则先用最简单的 curl 排除网络和 Key 问题再考虑策略限制不要上来就重装。5.2 报错二VSCode 插件连不上终端里的会话第二个坑是 VSCode 扩展 attach 失败一直转圈。这个排查了我一下午最后发现是版本不匹配扩展更新到新版终端里的 opencode 还是旧版双方握手协议对不上。解决办法很简单两条命令统一版本opencode update或者干脆npm i -g opencode-ailatest然后重载窗口就好了。这里有个更隐蔽的细节如果你通过包管理器装的 opencode 和 VSCode 扩展各自自动更新很可能哪天又悄悄出现版本差。我现在的习惯是把 opencode 的自动更新关掉固定在某个稳定版本要升级的时候手动来省得扩展和 CLI 各跑各的版本。5.3 报错三Skill 不生效总是“未找到”第三个坑是 Skill 明明放进去了用的时候却提示找不到。我检查了目录位置、frontmatter 格式都没问题后来才发现是文件名的问题——SKILL.md 必须严格用大写 SKILL我当时写成了skill.md在 Linux 下大小写敏感自然读不到。这个错误相当低级但很典型。还有一个原因是 description 写得太泛Agent 根本就没触发加载 Skill 的判断所以不是 Skill 坏了是它没意识到该用。遇到这类问题先手动输入/skill看列表里有没有列表里没有就是目录或文件名问题列表里有但对话不触发就去改 description。5.4 一些小习惯什么时候该换模型、什么时候该清上下文最后说几个用久了才总结出来的小习惯。第一任务性质决定了模型选择简单的解释性问答用小模型就行真正的代码重构、跨文件修改再上强模型不要一视同仁。第二上下文清理要主动完成一个阶段就清空别心疼那些历史记录opencode 的 Session 本来就支持历史回看真需要的时候恢复旧会话就行不耽误事。第三Skill 要持续迭代写好的 Skill 用几次就会发现描述不精准、步骤有漏改就是了它只是文本文件改完重启会话就能生效。我在实际使用中的体会是opencode 这套工具真正难的不是某个具体配置而是你愿不愿意把一部分编码工作流程“标准化”成 Skill 让它自动跑。一旦你迈过这道坎把重复劳动都沉淀成可复用的提示词包那种“越用越顺”的感觉就出来了。最后分享一个小技巧每次新项目开始先花十分钟写一个这个项目的专属 Skill把项目架构、代码风格、常用命令塞进去后面所有会话它都会带着这份“背景知识”干活效果比你反复在对话里解释好太多。
如果你用过 Claude Code 再回头看 opencode会有一种“这工具怎么越做越像个活物”的感觉。上篇讲完了基础安装和日常用法这篇我打算把大家问得最多的几个层面一次性聊透opencode 在整套 AI 编码工具链里到底处于什么生态位、它的模型服务面尤其是免费 tier 和 go 套餐是怎么回事、终端和 VSCode 的外壳集成有哪些坑以及最后怎么从零搭一个真正能用的 Skill 接到自己的工作流里。这几个话题几乎覆盖了最近社区里关于 opencode 的大部分问题包括那个最经典的error from provider (console): opencodes free tier can only be used from within opencode报错。1. opencode 的定位终端 Agent 而不是又一个 IDE1.1 为什么上篇之后我还要单独谈“工具”这件事很多人第一次打开 opencode 会下意识拿它跟 Cursor、Continue 这类编辑器插件对比然后很快产生疑惑这东西怎么连代码补全都没有对话框也这么朴素其实这是把它放错了坐标系。opencode 的定位更接近 Claude Code——它不是一个帮你打字的编辑器而是一个跑在终端里、能自己调工具、自己改文件、自己执行命令的 Agent 运行环境。它负责的事情是“理解任务、拆解步骤、调用工具、验证结果”而不是每一行代码都等你确认。这一点没想清楚后面所有配置都会别扭。比如你会纠结“为什么 opencode 没有代码高亮提示”但实际用的时候你根本不需要它高亮因为你是让它改代码不是手写代码。把这个心智模型切换过来后面看它的服务面、外壳、Skill 机制都会顺很多。1.2 与 Claude Code、Cursor、Continue 的横向对比我用一张表把几个常见工具的本质区别列出来看完你就知道什么场景选什么工具本质形态擅长任务不擅长的场景Cursor编辑器 补全 对话手动编码时的智能补全、单文件修改跨多文件的自主重构、长链路任务ContinueIDE 插件/SDK嵌在现有编辑器里的对话补全独立终端里自主执行命令Claude Code终端 Agent多步骤任务自主执行、工具调用视觉化编辑、交互式调试opencode终端 Agent 可自定义 Skill类似 Claude Code但模型/服务商更开放需要强 GUI 支持的场景说实话Claude Code 和 opencode 是同一类东西真正的差异在开放度。Claude Code 默认绑定 Anthropic 的服务生态虽然也能改环境变量接别的opencode 从设计上就把“ provider 可插拔”放在了第一位你想接 DeepSeek、本地 Ollama、各种聚合网关都行。所以我会把 opencode 定位成“中立终端 Agent 壳”这是它跟 Claude Code 最大的区别也是很多人从后者迁过来的核心原因。1.3 核心概念Session、Provider、Skill 是怎么串起来的用 opencode 的过程其实就三个概念Session会话、Provider模型服务商、Skill技能包。Session 是你和 Agent 之间的一次连续对话它保存在本地可以随时恢复。Provider 决定这次会话的大脑是谁opencode 启动后你可以用/model随时切换而不用重启程序。Skill 则是一份提前写好的“角色设定 工作流程”类似给 Agent 塞了一本操作手册。打个比方Session 像是你在公司里的一个项目文件夹Provider 像你这次项目请哪位顾问Skill 像你给顾问的一套公司规章制度。三者互相独立又可以组合同一个 Session 里前半段用便宜模型做草稿后半段切到更强的模型做精修中间随时让 Agent 加载一个 Skill 改变工作方式这套组合拳才是 opencode 真正的玩法。2. 服务面免费 tier 限制、go 套餐额度与模型接入2.1 那条报错的真实含义免费额度绑定了运行环境如果你在第三方环境里用 opencode 的免费模型大概率会遇到这个报错error from provider (console): opencodes free tier can only be used from within opencode我最初以为这是网络问题或者密钥写错了后来才发现它根本不是技术故障而是策略限制。opencode 控制台给每个账号提供了一些免费额度但服务端会校验发起请求的客户端来源——只有在 opencode 官方客户端环境里发起的请求才会放行你通过 VSCode 插件、cc-switch 这类切换工具、或者自己写脚本去调它的免费通道都会被拒。想明白这条逻辑之后处理方案就清晰了要么老老实实在 opencode 终端里用这个免费额度要么别把免费额度当成主力去接真正属于你自己的 API Key。很多人一上来图省事填了免费通道然后发现换到编辑器插件里就报错其实不是配置错了而是你踩了它的“环境绑定”设计。这一点官方文档写得不算醒目踩过的人基本都懵过一阵。2.2 opencode go 套餐按模型分开算额度是个什么体验再来说 opencode go 套餐。这个套餐本质是官方推出的聚合订阅服务一次订阅能用到多家模型不用你自己分别注册各家 API。社区里问得最多的一个问题是套餐额度到底是总量池还是分池我明确说按模型分开计算额度。也就是说套餐里 Claude 系列的用量、GPT 系列的用量、DeepSeek 系列的用量是各自独立的池子用光了其中一个并不会把另一个的额度挪过来。这个设计其实合理因为不同模型的上游成本差很多合在一起算总额度的话所有人都会只挑贵的模型用套餐根本撑不住。但它对使用习惯的影响很大你以为买了套餐就随便用结果某一天发现 Claude 的池子烧完了GPT 还剩一大半这时候你就只能切模型。所以用 go 套餐的正确姿势是别死磕某一个模型谁有配额用谁配合 opencode 的/model切换反而很舒服。顺带一提 go 套餐的 v2 版本出来后配合 cc-switch 这类 provider 切换工具很多人以为可以把 go 的额度导到其他客户端用。这里提醒一句这类操作能不能成功是一回事协议允不允许是另一回事服务端策略一变你可能突然就断了别把生产环境的稳定性押在这种灰色操作上。2.3 自己接模型DeepSeek、Hermes 等不同路线的取舍如果不走官方套餐自己接模型是 opencode 的另一大乐趣。社区里最常拿来对比的是 DeepSeek 系和 Hermes 系。我的实际体验是日常编码任务DeepSeek 系列更稳尤其是工具调用Function Calling的格式遵循度、多轮对话的上下文一致性明显比很多开源模型强。Hermes 系我也试过它的风格更“话痨”创意写作类任务有意思但在严格的“改代码—跑测试—报错重试”循环里稳定性差一点。如果你在 Ubuntu 上跑 opencode 并且打算本地推理我建议优先考虑显存能装下的量化版本然后设好较低的温度参数0.2 左右否则模型自由发挥的空间太大Agent 经常改出莫名其妙的代码。云端 API 则优先看三件事上下文窗口、价格、限流策略。上下文小于 64K 的一律不建议用来做 Repository 级任务因为 opencode 会把多文件内容塞进上下文窗口太小会频繁截断。2.4 兼容层接入不是只有官方渠道一条路还有一类服务是聚合网关或者中转服务比如社区经常提到的 JeV 这类“接入 Claude Code”的思路。它的玩法其实不复杂Claude Code 支持通过环境变量覆盖 API 地址和密钥你只要有一个兼容 Anthropic 协议的服务端设置好ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN就能把流量导向任何兼容服务。opencode 因为 provider 设计更开放同样可以这么接只是配置文件写法不同一般在 opencode.json 里声明一个自定义 provider填上 baseURL 和 apiKey 就行。我个人的建议是这类兼容层适合“尝鲜”和“备用通道”不适合做唯一依赖。因为兼容层的稳定性取决于上游服务商它今天能用、明天可能就限流你今天调通了的配置、下周可能就失效。真要长期用还是得回到官方 API 或者本地模型两条主路上来。3. 外壳集成Ubuntu 安装、VSCode 与终端实操3.1 Ubuntu 下安装 opencode 的三种方式和我的推荐先解决一个高频问题Ubuntu 怎么装。官方提供了好几种方式实测下来我给三个选项官方一键脚本适合懒得折腾的人但注意它会写入系统级目录需要 sudonpm 全局安装适合你本来就要装 Node 环境升级方便直接下载二进制包适合不想引入 Node 依赖的场景。我自己的选择是 npm 全局安装因为要配合其他前端工具链Node 反正都在。安装完第一步先跑opencode auth login它会引导你完成控制台登录如果你要自接模型就直接改配置文件不用走这个命令。有一点很多人忽略装完之后确保 shell 里能直接opencode --version如果提示找不到命令大概率是 npm 全局 bin 目录没进 PATH跟 opencode 本身无关。Ubuntu 下还会遇到一个跟系统相关的小问题某些终端字体对 opencode TUI 的图标渲染不全显示成方框。解决办法是装一个 Nerd Font 字体并在终端配置文件里启用这一步虽然不影响功能但影响心情建议提前搞定。3.2 VSCode 集成编辑器面板里的会话不只是一个“终端”VSCode 怎么和 opencode 一起工作这也是高频问题。官方的做法是装 opencode 扩展装完后你可以从命令面板启动一个新会话或者 attach 到终端里已经存在的会话。注意这里的差别attach 模式只是把终端里的 opencode 画面“接到”编辑器面板里看你在面板里的操作仍然作用于原来的会话新建会话则是从头开始。我试过两种日常更推荐 attach因为终端里已经跑着的会话保留了完整的上下文和文件变更记录你切到面板只是换个窗口看它干活。如果是新开会话还要重新说明项目背景对于已经开发到一半的项目来说很啰嗦。另外VSCode 扩展能读取当前打开的文件作为上下文这意味着你可以直接对 Agent 说“把当前文件的函数拆出去”它知道你说的是哪个文件这个体验比纯终端好不少。有个小坑是扩展版本和终端里的 opencode 版本不一致时有时候 attach 会失败或者只读。遇到这种情况别急着重装先对比一下两边版本一致了再试。我踩过一次折腾半天发现是版本差了一位。3.3 终端外壳里的高频操作斜杠命令、文件与快捷键不管在 VSCode 里还是纯终端里opencode 的交互逻辑是一样的。说几个我每天必用的输入/model随时切换模型切换后对话上下文保留这个比很多工具强输入/skill可以查看和加载已安装的 Skill在对话里用文件名显式引用文件比贴一大段代码进来清爽得多选中输入框内容后Tab 可以快速补全历史。快捷键方面CtrlL清空上下文、CtrlD退出当前会话这类基础操作就不多说了。这里重点提醒一个使用习惯opencode 的上下文是累积的一个长会话到后期会越来越慢、越来越贵。我现在的做法是一个任务干完立刻用CtrlL清空或者直接开新会话只保留需要延续的信息。不要养成“一个 Session 用一天”的习惯那是把它当成普通聊天软件了Agent 的上下文很贵。至于 opencode 新出的 zen 模式如果你喜欢极简界面切过去之后侧栏和状态栏都会收起来整个屏幕只有对话区纯写代码的时候干扰确实少。但这只是界面变化功能没有增减用不用看个人口味。4. 从零搭一个 Skill代码审查与提交信息生成的实战4.1 Skill 机制原理不过是一份写得很好的提示词包有人把 Skill 说得很玄其实拆开看就是一套有结构的提示词包一份说明文件加上可选的一些引用资源放到指定目录下opencode 就能识别它。Agent 在合适的时候会读这份提示词包然后按照里面定义的角色和工作流来执行任务。你可以把它理解为“给 Agent 发了一份岗位说明书”。没有 Skill 时Agent 只凭系统提示词干活像个什么都会但没经验的新人有了 Skill它就有了具体岗位的工作规范知道先做什么、后做什么、输出长什么样。这也是“如何通过 opencode 搭建一个 skill”这个问题的核心答案——不是写代码而是组织好提示词。4.2 Skill 文件结构frontmatter、说明与引用资源Skill 目录一般在~/.config/opencode/skills/下面每个 Skill 一个子目录核心文件是 SKILL.md。它的结构长这样~/.config/opencode/skills/ └── commit-helper/ ├── SKILL.md └── rules/ └── commit-style.mdSKILL.md 开头必须有 YAML frontmatter至少包含 name 和 description 两个字段。description 至关重要因为它是 opencode 判断“什么时候该用这个 Skill”的依据写得越具体触发越准确。后面紧跟正文正文里写清楚角色、执行步骤、输出格式、参考标准。--- name: commit-helper description: 当需要生成 git 提交信息或 review 当前提交时使用。尤其适用于用户输入 commit、提交信息、commit message 等关键词时。 --- # Git 提交助手 你是一名熟悉 Conventional Commits 规范的工程师。 请严格按照以下步骤执行 1. 运行 git status 查看工作区状态 2. 运行 git diff --staged 获取暂存区变化 3. 根据变化类型feat/fix/docs/refactor 等生成提交信息 4. 如果存在 rules/commit-style.md以其中的风格为准这里有个容易被忽略的细节description 不要写得太宽泛比如“处理 git 相关操作”因为宽泛描述会让 Agent 动不动就加载这个 Skill反而干扰了其他任务。我的经验是把触发词写具体宁可让它错过触发也比误触发好。4.3 两个可以直接用的 Skill 示例第一个示例就是上面这个 commit-helper。如果你希望它严格遵守团队规范可以把规范单独放在一个文件里引用这样修改规范不需要动 SKILL.md维护起来很清爽。我自己会把提交信息语言、是否加 issue 编号等规则都放进去生成出来的 commit message 基本不用改。第二个示例是代码审查 Skill这个比 commit 更实用--- name: code-reviewer description: 当用户要求 review 代码、审查 PR、检查代码质量时使用。 --- # 代码审查专家 你是一名资深代码审查员请从以下维度审查变更 1. 安全性SQL 注入、路径穿越、敏感信息硬编码 2. 可维护性重复代码、魔法数字、函数复杂度 3. 性能明显低效的循环、无索引查询、无谓的对象拷贝 4. 边界空值处理、并发安全、资源释放 输出格式 - 按严重程度从高到低列出问题 - 每个问题标注文件、行号、问题描述、修改建议 - 最后给出总体结论通过 / 需修改后通过 / 不通过我把这个 Skill 安装后直接绑到了提 PR 之前的流程里让 Agent 先按这套标准自检一遍比自己肉眼查效率高很多。4.4 Skill 与工作流联动自动加载、团队共享、版本管理Skill 装好之后不用手动激活opencode 会根据当前对话内容自动决定是否加载。如果你希望特定项目强制使用某个 Skill可以在项目的.opencode/skills目录里也放一份这样跟着项目走team 成员 clone 下来就有同样配置不用大家各自手动装。版本管理上我强烈建议把整个 skills 目录纳入 dotfiles 仓库。这样换新机器只需要一条命令同步下来不用重新凭记忆重建。团队协作的话Skill 文件本身是纯文本review 起来很容易而且因为它是提示词不是代码非工程师同事也能参与维护。我们组现在的做法是谁发现某个重复性工作能让 Agent 干就写一个 Skill 提交到仓库Review 通过后大家共用。这套机制跑起来之后Agent 的实际利用率提升非常明显。5. 踩坑记录三条让我差点卸载的报错与排查过程5.1 报错一免费额度只能在 opencode 内使用这节专门讲坑。第一个坑就是前面提过的 free tier 报错我遇到时候的完整排查链路给你们复盘一下。报错出现后我第一步检查配置文件确认 provider 名字和 API Key 没写错——结果是对的。第二步去控制台看额度发现免费额度还在——问题没解决。第三步我把同一个 Key 拿去 curl 测试发现能通——这就奇怪了。最后我去翻社区的 issue 才明白是服务端校验了客户端来源。当时的感觉是庆幸又无语庆幸不是配置问题无语于这个限制确实藏得深。排查思路记住一个原则先用最简单的 curl 排除网络和 Key 问题再考虑策略限制不要上来就重装。5.2 报错二VSCode 插件连不上终端里的会话第二个坑是 VSCode 扩展 attach 失败一直转圈。这个排查了我一下午最后发现是版本不匹配扩展更新到新版终端里的 opencode 还是旧版双方握手协议对不上。解决办法很简单两条命令统一版本opencode update或者干脆npm i -g opencode-ailatest然后重载窗口就好了。这里有个更隐蔽的细节如果你通过包管理器装的 opencode 和 VSCode 扩展各自自动更新很可能哪天又悄悄出现版本差。我现在的习惯是把 opencode 的自动更新关掉固定在某个稳定版本要升级的时候手动来省得扩展和 CLI 各跑各的版本。5.3 报错三Skill 不生效总是“未找到”第三个坑是 Skill 明明放进去了用的时候却提示找不到。我检查了目录位置、frontmatter 格式都没问题后来才发现是文件名的问题——SKILL.md 必须严格用大写 SKILL我当时写成了skill.md在 Linux 下大小写敏感自然读不到。这个错误相当低级但很典型。还有一个原因是 description 写得太泛Agent 根本就没触发加载 Skill 的判断所以不是 Skill 坏了是它没意识到该用。遇到这类问题先手动输入/skill看列表里有没有列表里没有就是目录或文件名问题列表里有但对话不触发就去改 description。5.4 一些小习惯什么时候该换模型、什么时候该清上下文最后说几个用久了才总结出来的小习惯。第一任务性质决定了模型选择简单的解释性问答用小模型就行真正的代码重构、跨文件修改再上强模型不要一视同仁。第二上下文清理要主动完成一个阶段就清空别心疼那些历史记录opencode 的 Session 本来就支持历史回看真需要的时候恢复旧会话就行不耽误事。第三Skill 要持续迭代写好的 Skill 用几次就会发现描述不精准、步骤有漏改就是了它只是文本文件改完重启会话就能生效。我在实际使用中的体会是opencode 这套工具真正难的不是某个具体配置而是你愿不愿意把一部分编码工作流程“标准化”成 Skill 让它自动跑。一旦你迈过这道坎把重复劳动都沉淀成可复用的提示词包那种“越用越顺”的感觉就出来了。最后分享一个小技巧每次新项目开始先花十分钟写一个这个项目的专属 Skill把项目架构、代码风格、常用命令塞进去后面所有会话它都会带着这份“背景知识”干活效果比你反复在对话里解释好太多。
