如果你用过 Claude Code 再回头看 opencode，会有一种“这工具怎么越做越像个活物”的感觉。上篇讲完了基础安装和日常用法，这篇我打算把大家问得最多的几个层面一次性聊透：opencode 在整套 AI 编码工具链里到底处于什么生态位、它的模型服务面（尤其是免费 tier 和 go 套餐）是怎么回事、终端和 VSCode 的外壳集成有哪些坑，以及最后怎么从零搭一个真正能用的 Skill 接到自己的工作流里。这几个话题几乎覆盖了最近社区里关于 opencode 的大部分问题，包括那个最经典的error from provider (console): opencode's free tier can only be used from within opencode报错。
1. opencode 的定位：终端 Agent 而不是又一个 IDE
1.1 为什么上篇之后我还要单独谈“工具”这件事
很多人第一次打开 opencode 会下意识拿它跟 Cursor、Continue 这类编辑器插件对比，然后很快产生疑惑：这东西怎么连代码补全都没有？对话框也这么朴素？其实这是把它放错了坐标系。opencode 的定位更接近 Claude Code——它不是一个帮你打字的编辑器，而是一个跑在终端里、能自己调工具、自己改文件、自己执行命令的 Agent 运行环境。它负责的事情是“理解任务、拆解步骤、调用工具、验证结果”，而不是每一行代码都等你确认。
这一点没想清楚，后面所有配置都会别扭。比如你会纠结“为什么 opencode 没有代码高亮提示”，但实际用的时候你根本不需要它高亮，因为你是让它改代码，不是手写代码。把这个心智模型切换过来，后面看它的服务面、外壳、Skill 机制都会顺很多。
1.2 与 Claude Code、Cursor、Continue 的横向对比
我用一张表把几个常见工具的本质区别列出来，看完你就知道什么场景选什么：
| 工具 | 本质形态 | 擅长任务 | 不擅长的场景 |
|---|---|---|---|
| Cursor | 编辑器 + 补全 + 对话 | 手动编码时的智能补全、单文件修改 | 跨多文件的自主重构、长链路任务 |
| Continue | IDE 插件/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): opencode's 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 怎么装。官方提供了好几种方式，实测下来我给三个选项：
- 官方一键脚本，适合懒得折腾的人，但注意它会写入系统级目录，需要 sudo；
- npm 全局安装，适合你本来就要装 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 可以快速补全历史。
快捷键方面，Ctrl+L清空上下文、Ctrl+D退出当前会话这类基础操作就不多说了。这里重点提醒一个使用习惯：opencode 的上下文是累积的，一个长会话到后期会越来越慢、越来越贵。我现在的做法是，一个任务干完立刻用Ctrl+L清空，或者直接开新会话，只保留需要延续的信息。不要养成“一个 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-ai@latest然后重载窗口就好了。这里有个更隐蔽的细节：如果你通过包管理器装的 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，把项目架构、代码风格、常用命令塞进去，后面所有会话它都会带着这份“背景知识”干活，效果比你反复在对话里解释好太多。
