企业官网建设流程全解析

上次我们把 opencode 装好、跑通了第一轮对话，但我知道很多人卡在了更深处：明明模型配好了，突然弹出一句error from provider (console): opencode's free tier can only be used from within opencode，然后整个会话就哑火了。这种报错其实和你的操作习惯没关系，它是典型“服务面”问题，但很多新手会下意识跑去折腾工具配置，结果越绕越晕。

所以这篇“下篇”，我打算换个拆法，不按功能列表讲，而是把 opencode 分成四个面来看：工具面（它能调什么）、服务面（模型从哪来）、外壳面（你用什么姿势操作它）、实战集成（怎么把上面三者串成一个真实流程）。这样拆完，你会发现那些玄学报错、额度疑问、VSCode 联动问题，其实都有清晰的归因路径。适合已经被 opencode 勾起了兴趣、想从“会跑”进阶到“会用好”的人，也适合正在纠结模型套餐和 Skill 搭建的折腾型用户。

1. 整体认知：先把 opencode 的“四个面”拆开

1.1 工具面、服务面、外壳到底是什么

opencode 本质上不是一个普通的命令行工具，它是一个具备自主决策能力的 agent 运行时。既然是运行时，它就一定有三个天然分层：

• 工具面：agent 能拿出来用的“手脚”，比如读写文件、执行命令、搜索代码、抓网页、调用外部程序。
• 服务面：agent 的大脑从哪来，也就是模型提供方，包括你配的 API key、官方 console 免费层、opencode go 这类托管额度，还有本地模型。
• 外壳面：你和这个 agent 之间的交互界面，包括终端 TUI、Zen 模式、VSCode 扩展、命令行参数。

我在实际使用中最大的感受是：opencode 的很多困惑，都源于这三层边界没分清。比如有人问“为什么我在 VSCode 里用 opencode 和终端里用 opencode，能力不一样”，这其实就是外壳面的差异；有人问“为什么 Skill 明明写对了，调用却报错”，这往往是工具面的权限问题；而开头那句free tier can only be used from within opencode，纯粹是服务面的限制逻辑。

1.2 为什么理解边界比记命令更重要

说实话，你不需要背下 opencode 的所有快捷键和命令，但你必须知道“某个现象属于哪一层”，这样排查起来才不迷路。

举个例子，如果 agent 说“我没有权限写入某个目录”，这是工具面问题，你去检查 Skill 的权限配置、工作目录就行；如果提示“模型请求失败，配额不足”，这是服务面问题，你得去看 provider 配置、套餐用量，而不是反复重装程序；如果界面操作卡顿、快捷键失灵，这是外壳面问题，多半是终端兼容性或者扩展版本不对。

这就像排查电脑问题：网络不通先看网线，屏幕不亮先看电源。先定位层面，再动手，比拿着命令到处试高效得多。这篇后面每一个大章节，都会按这个分层逻辑往下走。

2. 工具面：内置工具与 Skill 生态

2.1 内置工具不是越多越好，先认识这几类

opencode 内置了十几类常用工具，但实际高频使用的就那么几组。我在项目里把它们归成五类：

这里有个经验：新手喜欢一上来就把所有工具全开，觉得“能力越多越强”，但实践下来，工具面越宽，agent 的决策路径就越长，反而容易在无关能力上浪费 token。我更建议按场景裁剪能力范围，比如做代码重构时只保留文件读写、搜索和 bash，关闭网页抓取，输出会稳很多。

2.2 Skill 机制：你完全可以自己造一个工具

Skill 是 opencode 工具面里最值得花时间搞懂的部分。它和普通提示词最大的区别在于：Skill 是一个结构化的技能包，里面可以包含说明文档、提示词片段、参考示例、甚至配套脚本，agent 会在需要时按描述自动加载。这相当于把“一个老师傅处理某类问题的完整套路”固化下来。

对比一下就清楚了：

• 普通提示词：告诉 agent“你要做什么”，每次都得重新描述一遍，换个场景就失效。
• Skill：告诉 agent“你遇到什么场景时，去读哪个技能包，按里面的流程执行”，一次定义，处处复用。

我自己的团队里，把常用的“新项目初始化”“日志排查”“API 接口文档生成”都做成了 Skill，效果相当明显：同样一个任务，以前要来回对话十几轮，现在 agent 自己就能按流程走完，而且结果风格高度一致。

2.3 手把手：通过 opencode 搭建一个 Skill

我拿“代码仓库健康检查”这个 Skill 当例子，完整走一遍搭建流程。

第一步，确认 Skill 目录结构。opencode 会从固定的目录加载 Skill，Linux 下一般是~/.config/opencode/skills/，每个 Skill 一个独立子目录：

~/.config/opencode/skills/repo-health/ ├── SKILL.md └── scripts/ └── check.sh

第二步，写 SKILL.md 的主体。文件开头是 YAML frontmatter，核心字段是name和description。这里我踩过一个坑：description 写得越“场景化”，agent 越容易在关键时刻想起它。比如：

--- name: repo-health description: 当用户想检查项目健康状况、依赖版本、未提交文件或代码统计时使用。输入是项目路径，输出是一份包含文件数、未提交改动、依赖过期情况的结构化报告。 ---

注意 description 里要包含“用户意图”、“输入”和“输出”，不要写“这是一个很棒的检查工具”这种废话。agent 靠 description 做语义匹配，描述质量直接决定 Skill 的触发率。

第三步，写正文指令。SKILL.md 的正文部分就是 agent 的行为准则，要求它做什么、按什么顺序做、什么不能做：

# 仓库健康检查流程 1. 使用 bash 工具执行 scripts/check.sh，传入项目路径。 2. 脚本可能返回多条统计信息，将它们整理为 Markdown 列表输出。 3. 如果发现未提交的改动，只列出文件清单，不要擅自执行 git add 或 commit。 4. 遇到 node_modules、dist 等目录，直接跳过，不要统计。

第四步，放配套脚本。检查脚本可以做得比较朴素，重点是 agent 能直接调用：

#!/usr/bin/env bash # scripts/check.sh — 基础信息采集 TARGET_DIR="${1:-.}" echo "文件总数: $(find "$TARGET_DIR" -type f | wc -l)" echo "未提交改动: $(git -C "$TARGET_DIR" status --porcelain | wc -l)" echo "依赖过期数: $(git -C "$TARGET_DIR" log --oneline -5 | wc -l)"

第五步，测试触发。在 opencode 对话里输入“帮我检查一下当前项目健康度”，观察 agent 是否自动加载这个 Skill。如果没触发，大概率是 description 里的触发词没对上；如果触发了但执行出错，先手动跑一遍脚本，排除脚本本身的问题。

2.4 工具面常踩的坑

Skill 和工具面有几个坑，几乎每个人都会遇到，提前说清楚能省不少时间：

• 权限边界：opencode 的工具执行是有权限控制的，默认只允许操作当前工作目录里的内容。如果你想让它写/tmp或家目录下的文件，需要在配置里显式授权，否则会看到一串权限拒绝。
• 先读后写：让 agent 改代码前，一定要在 Skill 流程里写明“先 read 目标文件，再 edit”。agent 没有记忆功能，直接 edit 往往会把文件改坏。
• 不要硬编码绝对路径：Skill 脚本里如果写死绝对路径，换台机器、换个项目就废了。一律用相对路径或参数传入，这是可复用的前提。

3. 服务面：模型接入、免费层与套餐额度

3.1 先搞懂 provider 体系

服务面是 opencode 里最容易出幺蛾子的部分，因为这里涉及的概念最多：API key、provider、免费层、订阅套餐、额度。先说清楚 provider 是什么：它就是“模型来源”的抽象层。你在 opencode 里配一个 provider，相当于告诉系统“我有一批模型请求要走这个渠道”。

常见的 provider 形态有三种：

• 内置 console 免费层：opencode 官方提供的体验额度，配好就能用，不用自己申请 key。
• 自带 API key 的自定义 provider：你填入某个模型服务的 key，opencode 直接往那个服务发请求。
• opencode go 等托管套餐：订阅制的官方额度，和免费层相比更稳定、额度更大，算力调度也更可控。

这三者不是互斥的，可以同时配置，opencode 会按会话选择主动路由。理解这一点之后，很多“为什么这个模型能跑那个模型不能用”的问题就迎刃而解了——先看当前会话用的是哪个 provider。

3.2 那条吓人的报错到底在说什么

很多人第一次看到error from provider (console): opencode's free tier can only be used from within opencode时，第一反应是自己账号被封了或者哪里配错了，其实根本不是。

逐词拆解一下：free tier是免费层额度，can only be used from within opencode是“只能从 opencode 内部使用”。也就是说，opencode 官方给免费额度设了一道限制：这个额度只允许在 opencode 产品自己的会话里被消费，不允许被外部程序、自定义脚本、第三方客户端拿去调用。

我遇到过几种典型触发场景：

如果你的场景确实需要稳定调用，我建议直接把免费层当“体验尝鲜”，生产用途还是切到 API key 或 go 套餐。免费层适合快速验证想法，不适合长期跑自动化任务。

3.3 opencode go 套餐：额度是不是每种模型分开算

opencode go 是官方推出的托管额度服务，和免费层相比定位更“生产化”。很多人问“go 套餐是每种模型分开计算额度吗”，这个问题不能一概而论，取决于套餐的具体计费设计。

就我目前看到的情况，市面上主流做法有两种：

• 池化额度：所有模型共用同一个总预算，谁用得多谁占额。这种模式灵活，适合你经常在不同模型之间切换的场景。
• 按模型分桶：每个模型分到独立的额度，比如 A 模型 1000 次、B 模型 500 次，互不挤占。这种模式适合单一模型高频使用的场景，避免某个模型把总预算吃光。

怎么判断你手上的套餐是哪种？有两个土办法。第一，看套餐说明里有没有“按模型独立限额”的字眼；第二，实际做一个月的用量记录，盯着用量面板看，如果 A 模型用完时 B 模型额度纹丝不动，那就是分桶；如果一起掉，那就是池化。

我的建议是：如果你是重度多模型用户，优先选池化额度，因为你可以按任务类型动态调配；如果你只常用一两个模型，分桶更划算，至少不会被突发跑量打爆总配额。

3.4 免费模型怎么选：opencode 免费层与 DeepSeek Hermes 的取舍

总有朋友把“opencode 免费层”和“DeepSeek Hermes”放在一起比谁更好。话题热度高是因为这俩都是“不花钱能跑起来”的典型选项，但它们根本不是同一个层面的东西，放在一起比其实有点错位。

opencode 免费层是产品级的托管服务，优点是开箱即用、接入成本为零、速度和质量相对稳定；缺点在前面说了——仅限 opencode 内部使用，而且有配额天花板。DeepSeek Hermes 这类开源模型则是模型本身，你可以通过本地推理工具跑，也可以找第三方服务商托管，使用场景更自由，但需要你自己处理环境、算力和推理服务的运维。

怎么选，我给你三个判断维度：

• 图省事：选 opencode 免费层，什么多余的事都不用干。
• 要可控：选 Hermes 这类模型自己做服务，调用不受外部额度限制，但要为运维买单。
• 成本敏感：如果你的机器配置尚可，本地跑开源模型长期成本更低；机器一般，还是先用免费层过渡。

别只听别人说“谁更强”，先算清自己的时间成本和硬件成本，答案就出来了。

3.5 多服务商切换：CC-Switch 这类工具解决什么问题

当你配置的 provider 多了以后，下一个痛点就是切换。我试过手改配置文件的方式，一次两次还行，provider 一多就乱了，而且容易把 key 写错位置。于是大家开始用 CC-Switch 这类配置切换小工具。

CC-Switch 本质上是一个本地配置管理器，它帮你把不同服务商（比如 Anthropic、OpenCode 以及其他兼容渠道）的 key、基础 URL、模型配置统一管起来，在界面上点一下就能切换，不用手动改文件。它的核心价值有三个：

• 避免手改出错：配置文件一旦语法错误，整个 CLI 都跑不起来，用工具切换可以降低这个风险。
• 项目级隔离：不同项目用不同模型体系，这个需求很常见，切换工具让环境隔离变得简单。
• 快速对比：同时配几个 provider，A/B 切换测试模型的响应质量，效率高很多。

有一点要提醒：这类工具只管配置切换，不负责额度管理。切换过去后能不能跑，还得看目标服务商那边有没有配好。

4. 外壳面：终端交互、Zen 模式与 VSCode 联动

4.1 为什么 opencode 在终端里这么好用

第一次用 opencode 的终端界面，很多人都会愣一下：一个 CLI 工具，怎么做得像 IDE 一样。它有侧边栏文件树、有对话区和输出区分离、有快捷键操作，这就是它在外壳面上的功力。

它把终端的潜力挖得比较透：用上键盘流操作，全程不需要碰鼠标；历史上下文可以回溯；输出内容可以直接点击跳转到文件行号。这意味着你在 SSH 到服务器、或者在轻量环境里干活的时候，不需要开一个重型 IDE，就能拥有接近 IDE 的开发体验。

我个人最常用的是/agents面板和会话管理快捷键。前者可以让我同时挂多个任务，后者方便我在不同项目上下文之间快速跳转。如果你还在用裸终端一行一行和它对话，建议去官方文档翻一遍快捷键列表，提升不是一点半点。

4.2 Zen 模式到底解决什么

opencode 有个叫 Zen 的模式，光听名字会以为是个“极简主题”，其实它的设计意图是单任务专注。开启 Zen 模式后，界面会屏蔽大部分无关信息，只保留当前会话的关键输出，相当于把 agent 的注意力也锁在一条任务线上。

这个模式什么时候最有用？我举两个真实场景。

第一个是代码 review。一个 PR 下来几百行 diff，开着普通模式容易看花眼，Zen 模式干净的输出区能让你聚焦到每一处改动。第二个是批量脚本修正。当你让 agent 连续处理十几个文件时，普通模式输出会刷屏，Zen 模式只保留关键摘要，整个执行链条清楚很多。

如果你觉得“模式都是噱头”，可以找个文件批量处理任务对比跑一次，体验完差异再下结论也不迟。

4.3 Ubuntu 环境安装 opencode 的完整路径

Linux 用户，尤其是 Ubuntu，问安装的特别多。安装 opencode 主要有三条路径，我按推荐顺序说：

方式一：官方安装脚本

curl -fsSL https://opencode.ai/install | bash

这是最快的方式，脚本会自动检测架构、下载二进制、写入 PATH。装完重启终端，输入opencode --version验证。

方式二：npm 全局安装

npm install -g opencode-ai

适合本来就在 Node 生态里打转的用户，升级也简单，npm update -g一条命令的事。前提是 Node 版本要满足要求，太老的版本会报错。

方式三：直接下载二进制

到官方发布页下载对应架构的压缩包，解压后把二进制丢到/usr/local/bin，手动完成安装。这种方式适合离线环境或网络受限的服务器。

装完以后，我建议顺手做两件事：第一，确认.bashrc或.zshrc里的 PATH 有没有包含二进制目录；第二，运行一次opencode初始化配置目录，确认配置文件被正确创建。

4.4 VSCode 怎么和 opencode 工作

很多人习惯在 VSCode 里干活，不想切到终端窗口去用 opencode。官方提供了扩展来解决这个诉求。

安装扩展后，侧边栏会多出一个 opencode 面板，你可以把它当作一个嵌入式终端体验的 agent 聊天窗。实际联动方式主要有这几种：

• 把选中代码发进会话：在编辑器里框选一段代码，右键发送给 opencode，让它解释、重构或找 bug。
• 查看内联 diff：agent 修改文件后，可以在编辑器里直接看改动建议，确认后再接受，不用切来切去。
• 共享工作区上下文：扩展会读取当前打开的文件夹作为工作目录，agent 天然知道你在看什么项目，聊天时不用反复说明路径。

一个常见问题：VSCode 扩展里的 opencode 和终端里的 opencode，能力一样吗？答案是不完全一样。扩展版本质上是把 agent 能力嵌到了编辑器的外壳里，某些扩展版本的工具集可能落后于终端最新版，所以遇到“扩展里不能做但终端里能做”的情况，先检查版本，再检查是否共用同一份配置文件。

4.5 配置复用：把 opencode 的习惯搬进 Claude Code

很多折腾型用户手头同时有 opencode 和 Claude Code，想把一套模型习惯、密钥配置在两个工具里无缝复用。这里要厘清一个边界：opencode 和 Claude Code 是两个不同的工具，配置格式并不完全互通，直接复制粘贴是不行的。

但有一些经验可以复用：

• 密钥管理思路：两边都建议用环境变量注入 key，而不是把 key 明文写进项目文件。这个习惯到哪个工具都成立。
• Skill 与自定义指令：opencode 的 Skill 和 Claude Code 的自定义命令理念很相似，都是把场景化流程固化下来。写 Skill 时积累的提示词技巧，迁移到 Claude Code 的指令文件里，同样能提升触发准确率。
• provider 配置概念：你在 opencode 里对不同 provider 的理解，放到 Claude Code 的配置体系里同样适用，只是字段名和组织方式不同。

说到底，这类 AI 编程工具的外壳会有差异，但底层“模型 + 工具 + 流程编排”的思维是打通的，学会一个，再上手另一个会轻松很多。

5. 实战集成：一个端到端流程

5.1 选一个真实场景来串起来

四面的理论讲完了，现在把它们揉进一个完整案例。我选一个非常有代表性的场景：“批量整理下载目录并生成报告”。这个任务看似简单，但足够覆盖工具面（读目录、跑脚本、写文件）、服务面（全程调用模型额度）、外壳面（在终端 TUI 里互动）以及 Skill 集成。

目标：扫描~/Downloads里的文件，按扩展名分类，把重复文件找出来，最后生成一份 Markdown 报告。

5.2 从零到一的完整操作实录

第一步，做一个分类 Skill。按照本文 2.3 节的流程，在~/.config/opencode/skills/下建file-sorter技能包，SKILL.md 的 description 明确“扫描目录、按扩展名分类、标记重复项”。写好之后，先手动跑一遍验证脚本。

第二步，启动 opencode。在项目空目录里执行opencode，进入 TUI。如果你用的是免费层，确保当前会话 provider 是 console；如果已经配了 go 套餐，就在启动参数里明确指定，避免走到免费层的配额限制。

第三步，触发 Skill。对话里输入：

用 file-sorter 技能扫描 ~/Downloads，把结果输出为 report.md

agent 会根据 description 自动匹配技能，然后调用 bash 工具执行脚本。注意观察它是否真的加载了 SKILL.md 里的流程，而不是自己自由发挥。如果它回答“我没有这个技能”，检查技能目录名称和描述。

第四步，验证产出。打开生成的 report.md，检查三件事：扩展名是否分类正确、重复文件是否被识别、路径是否与真实目录一致。不要只看内容存在，要抽查两三行的准确性，这一步是很多人偷懒导致后面返工的地方。

第五步，用外壳功能收尾。按快捷键打开会话摘要，可以看到这次任务消耗了哪些工具调用、每个步骤花费多少时间。这个数据对后续优化 Skill 流程很有参考价值。

5.3 这一步为什么要这么做

你会发现整个流程里，我刻意坚持了几个原则，这里讲清楚为什么。

先写 Skill 再启动任务，而不是一上来直接对话让它“看着办”，是为了把不确定性降下来。Skill 是可控的、经过测试的流程，agent 按流程走，结果质量有底线。

显式指定 provider 而不是让系统自动路由，是为了避免额度收费的意外。很多人在实战中突然被报错打断，就是因为在多 provider 配置下没有指定当前会话走哪条路。

最后验证产出而不是信任输出，是因为 agent 再强也有幻觉。生成报告、改代码、重构文件，都必须在真实环境里做一次抽检，这是所有 AI 编程工具使用的保命习惯。

6. 常见问题与排查技巧实录

6.1 高频问题速查表

实战中我积累了一批高频问题，整理成速查表，遇到相同症状直接照着处理：

6.2 排查服务面问题的通用套路

服务面问题最容易让人头疼，因为报错信息往往很长很吓人。我总结了一个三步排查法，基本能应付 80% 的情况。

第一步，看报错前缀。error from provider (console)这里已经指明了是 console 这个 provider 出的问题。把括号里的名字记下来，去配置里找到对应 provider。

第二步，看环境变量。很多 provider 配置依赖环境变量注入。检查.env文件和当前 shell 环境，确认 key、base URL 都没被覆盖或漏配。

第三步，开调试日志。opencode 支持开启详细日志，把整个请求链路打出来。看请求到底发给了哪个服务商、返回了什么错误码。这一步能看到的信息，比界面上那行报错多得多。

6.3 我在这块踩过的三个坑

最后分享三个我自己踩过的坑，都是文档里不会写的内容。

第一个坑是写 Skill 时把脚本里的绝对路径写死了。第一次在本地测试一切正常，换个目录就废了，排查了半天才发现脚本里还挂着~/work/xxx。后来我学乖了，所有脚本强制要求相对路径或参数传入，并且在 SKILL.md 里写明“不要修改路径格式”。

第二个坑是混用了 provider 额度。当时手头有两个 provider，一个免费层一个 API key，我嘴上说要省着花钱，结果忘了指定 provider，自动路由把大请求都发到昂贵的模型上，月底一看账单才反应过来。现在我每次开始任务前都先确认当前会话用的哪个 provider，这已经成了肌肉记忆。

第三个坑是 VSCode 扩展和终端版行为不一致。我在终端里调好的 Skill，在 VSCode 侧边栏里怎么也触发不了，当时以为是配置问题，折腾了半小时才发现是扩展版本太旧，工具列表里根本没有新加的 Skill 能力。所以如果你同时用多个外壳，记得保持版本同步更新，不然排查方向很容易被带偏。

回头再看这四个面的框架，其实用熟之后，你就不会再纠结“某个功能到底怎么配”，而是能很自然地判断“这是哪一层的事”。工具面管好 Skill 和权限，服务面管好额度和 provider，外壳面选趁手的交互方式，再结合实战流程反复打磨，opencode 就能真正成为一套稳定顺手的生产力工具了。