企业官网建设流程全解析

OpenCode 最近在 GitHub 趋势榜上热度一直没下去，我身边不少从 Claude Code、Cursor 转过来的朋友都在试它。但很多人装完刚跑起来，就撞上一句让人摸不着头脑的报错：error from provider (console): opencode's free tier can only be used from within opencode。这句话我看网上讨论不少，但真正把它讲明白的文章不多。这篇就围绕 OpenCode 是什么、怎么装、怎么配、免费额度到底怎么算、报错怎么解决这几个核心问题，把我实际用下来的经验从头梳理一遍。

这篇内容适合这几类人看：想在终端里用 AI 编程、但不想被某个特定模型厂商绑定的开发者；从 Claude Code 转过来想对比一下差异的；以及已经装好 OpenCode 但卡在免费额度或模型配置上的人。我会把安装、配置、日常使用、隐私边界、踩坑经验都过一遍，尽量做到每一步都能直接照着操作。

1. OpenCode 是什么：一个把 AI 编程放进终端里的新选择

1.1 它解决的痛点：终端里的结对编辑

先聊定位。OpenCode 是一个开源的 AI 编程助手，核心形态是终端里的 TUI（文本用户界面）工具，安装之后你直接在命令行里输入opencode就能进入一个全交互式的会话界面。它不像 Cursor 那样是个完整的 IDE，也不像 Copilot 那样是编辑器插件，它更像 Claude Code 这类 agent 形态的工具——你给它一个任务，它能自己读代码、改文件、跑命令、查测试结果，然后不断迭代直到完成。

我之所以从别的工具转过来，核心原因是它的"本地优先 + 多模型"设计。OpenCode 默认把所有配置、会话数据、密钥都存在本地，不上官方云；模型层则做了抽象，你可以自由切换 Anthropic、OpenAI、Google Gemini、Groq 以及本地模型（比如 Ollama 跑起来的 Llama）等多种后端，不用换工具就换模型。对经常同时接几个不同模型的开发者来说，这个体验非常舒服。

另外一个很实用的设计是权限控制。OpenCode 在改文件、跑命令之前会先征求你的同意，你可以按项目或者临时会话设置成只读、自动接受或者每次询问。这种"人在回路"的模式在 agent 工具里特别重要，毕竟 AI 自己乱改代码的代价我们谁都付过。

1.2 和 Claude Code、Codex CLI 这类工具比，OpenCode 的差异点

用了段时间之后，我的感受是它和目标竞品之间有几个很明显的差异：

首先是模型无关。Claude Code 天然绑死 Claude 系列模型，Codex CLI 又绑死 OpenAI 系，OpenCode 则是个"万能插座"。你甚至可以同时配置好几个 provider，在会话里用/models命令随时切换。这个灵活度对于需要对比不同模型输出质量的场景特别有用。

其次是console provider。OpenCode 官方提供了一个内置的模型通道（就是报错里出现的 console），刚装好的用户可以免配置、免 API key 直接体验，官方会在额度内给你分配免费请求。这是在安装门槛上比同类工具低一大截的设计——Claude Code 你至少得先有一个 Anthropic API key 或者订阅才能跑起来。

第三是会话管理能力更强。OpenCode 的会话是可以恢复、可以命名的，本地 session 列表用/sessions就能看。我经常开着五六个项目的会话，隔几天回来还能接着上下文聊，这点比很多同类工具做得扎实。

1.3 免费额度策略：OpenCode 官方托管的匿名额度是怎么运作的

说到免费额度，这可能是 OpenCode 被误解最深的地方。我刚开始也以为 console provider 就是"白嫖 Claude"，后来才知道不是。

它的逻辑是这样的：console 是官方托管的模型网关，OpenCode 客户端内置了免费的匿名额度，目的是让新用户在不配置任何 API key 的情况下完整体验到核心功能。但这个额度有严格的使用边界——只能在 OpenCode 应用内使用，官方在服务端会校验请求来源和设备身份。你如果把 console provider 的配置抠出来，复制到 curl、其他 IDE 插件或者自建的中间服务里调用，服务端会直接拒绝，返回的就是那句经典报错：

error from provider (console): opencode's free tier can only be used from within opencode

这句话翻译成人话就是：免费额度只在 OpenCode 内部有效，别想把它当公共 API 用。后面我会单独开一节详细讲这个报错的出现场景和正确的应对方式。

2. 安装与首次配置：三分钟跑通，但模型通道要想清楚

2.1 安装的三种方式

OpenCode 的安装方式很常规，和大多数 Node 生态工具一样。我推荐用 npm 全局安装：

npm install -g opencode-ai

装完直接输入opencode --version验证，能输出版本号就说明没问题。如果你本机没有 Node.js 环境，或者不想把工具装进 Node 生态，也可以用官方脚本安装：

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

这个脚本会自动检测系统架构并下载对应的编译产物，实际体验比 npm 方式更省心，不依赖 Node 运行时。另外如果你用 Homebrew，还可以brew install opencode，不过前提是你用的机器上装了 Homebrew。

这里给一个初次安装的关键建议：装完之后先别急着配任何东西，直接运行opencode，先体验一下内置 console 免费通道。这样的话，你不用输入任何 API key 就能看到它在真实项目里的表现，再决定要不要绑定自己的模型。我自己当初是先跑通了 console，才去配的 Anthropic key，这样出了问题也容易定位是谁的锅。

2.2 配置模型提供商：OpenCode 支持的 provider 体系

等你想用自己的模型渠道了，再来处理配置文件。OpenCode 的配置文件默认在~/.config/opencode/opencode.json（macOS/Linux 下是这个路径，Windows 在%USERPROFILE%\.config\opencode\opencode.json），里面可以配置 provider、模型、参数和授权方式。

provider 体系是 OpenCode 的一等公民。我常用的几个配置大概是这样的：

{ "$schema": "https://opencode.ai/config.json", "provider": { "anthropic": { "api_key": "sk-ant-...", "models": ["claude-sonnet-4-5", "claude-opus-4-1"] }, "openai": { "api_key": "sk-...", "models": ["gpt-4o", "gpt-4o-mini"] }, "ollama": { "models": ["llama3.2"] } }, "model": "claude-sonnet-4-5" }

实际配置时大部分 provider 的api_key也可以不写在配置文件里，OpenCode 支持通过环境变量注入，比如ANTHROPIC_API_KEY、OPENAI_API_KEY这些，它会自动识别。我倾向于用环境变量，因为配置文件经常会提交到仓库里或者同步到别的地方，环境变量至少不会把密钥直接暴露在明文里。

有一点要特别提醒：如果你只想用 console 免费额度，什么都不用写。一旦你配置了自己的 provider，默认model字段就会覆盖 console，之后每次对话都走你自带的 key 了。当时我有个朋友就是配好了 OpenAI key 但还在奇怪为什么免费额度用不了——那是正常的，因为你已经选了付费通道。

2.3 首次启动和最小可用配置

配置好之后，进到任意一个项目目录，运行：

opencode

终端就会进入 TUI 界面。首次启动它会做一个快速环境检测，然后给你一个输入框，类似于聊天界面。你直接输入自然语言就行，比如"帮我看一下这个项目的 README 并总结它做什么的"，它会用内置工具去读文件、分析结构、回你结论。

如果你不想进 TUI，OpenCode 也支持非交互式调用：

opencode run "帮我清理这个项目里的未使用依赖"

这个模式特别适合脚本化调用，或者像我现在这样把 OpenCode 接到 CI 流程里做简单的代码审查。run模式输出的是纯文本流，避免了 TUI 里复制粘贴的麻烦，后面在自动化场景里会很常用。

首次启动后还有一件事值得做：看看/help里有哪些斜杠命令。我常用的有/models切换模型、/sessions查看历史会话、/compact压缩上下文、/config打开当前项目的配置文件。这些命令是日常使用频率最高的，建议刚开始就花五分钟熟悉一下。

3. 新手最先撞上的那堵墙：opencode's free tier can only be used from within opencode

3.1 这个报错到底出现在哪

前面提到了这句报错，现在展开讲。这个报错的实际完整形式是：

error from provider (console): opencode's free tier can only be used from within opencode

根据我在社区里看到的反馈和我自己遇到的场景，它主要出现在三种情况下：

第一种是你试图把 console provider 当作独立 API 来消费。具体来说，有人在其他工具或代码里拿到 OpenCode 的请求地址和密钥，直接对着官方的模型网关发请求，希望绕过 OpenCode 客户端直接使用模型服务，结果服务器返回了这句报错。

第二种是OpenCode 客户端里的会话过期或设备校验失败。偶尔会在长时间挂着 TUI 会话、网络切换之后出现，客户端内部的设备令牌失效了，重新请求时被服务端拦下来。

第三种是并发请求超过了免费额度的速率限制。比如你在两个终端同时开着 OpenCode，一个跑长任务另一个还不停问问题，瞬时请求超过官方免费档的速率上限时，也会收到这条报错，因为它本质上是同一套校验机制。

3.2 这句话背后的限制逻辑

从技术上说，OpenCode 的免费额度是"客户端特权"，不是"开放 API"。官方为什么这么设计？

说白了，免费额度是一个获客成本，一个广告费。官方托管的模型网关背后连接的是 Anthropic、OpenAI 等商业模型服务，每次请求都会产生真实的 token 成本。如果这些人把 console 端点当成免费的公共 API 代理来用，一夜之间就能耗尽官方所有的预算。所以服务端必须校验每个请求是否来自正规的 OpenCode 客户端实例，并且要限制频率。

这个校验通常包含设备指纹、客户端版本信息、会话令牌等多项内容。换句话说，官方在服务端确认的是"你是不是一个真实的 OpenCode 用户在正常使用"，而不是"你有请求密钥就能用"。理解了这层逻辑，你就明白为什么报错文案里反复强调"only be used from within opencode"——这是产品边界，也是成本护栏。

3.3 想获得稳定额度：直接买 OpenCode GO 套餐

如果你试下来觉得免费额度不够用——说实话它确实不够深度使用者造——不要试图绕过，而是走官方的付费通道：OpenCode GO 套餐。

这个套餐具体分几档我记不太清，官方页面上有详细价格，我只说我确认过的体验：买了 GO 套餐之后，你可以在不配置任何第三方 API key 的情况下使用 OpenCode 内置的更高级模型（包括 Claude 系列和 GPT 系列），流量走官方底座，稳定性比 console 免费额度好非常多。对我这种重度使用者来说，这个钱值得花，因为省去了自己分别管理 Anthropic 和 OpenAI 两个账号的密钥、账单、限流的麻烦。

GO 套餐还有一个好处是支持按量计费还是包月订阅我有点拿不准，建议以官方文档为准，我只提醒一点：如果团队用，记得看清楚套餐是否支持共享额度，不然五个人各自刷各自的免费档很容易集体撞限流。

3.4 为什么我不建议"绕过"这个限制

网上确实能看到一些"把 console 变成通用 API"的讨论，我的建议是别碰，理由有三个。

第一是成本问题。官方免费额度是为真实用户试用设计的，一旦被恶意刷量，最直接的结果就是官方收紧甚至取消所有人的免费额度，这是典型的"劣币驱逐良币"。

第二是稳定问题。就算你技术上把请求伪装成了客户端，服务端随时可以加校验字段，今天能用的方案明天可能就失效了，你还要搭进去持续维护的成本。

第三是合规问题。任何服务的免费档都有明确的条款边界，绕过它本质上是对服务协议的违反。轻则密钥被封、IP 被拉黑，重则影响后续正常使用，没有必要为了省一点 API 费用去冒这个险。

正确的思路就一句话：免费额度拿来体验，付费套餐拿来干活，自备 API key 拿来掌控成本。这三条路是 OpenCode 官方设计好的三种消费路径，按需选择就好。

4. 日常高频用法：从单条命令到长会话管理

4.1 交互模式与三种调用入口

很多新手以为 OpenCode 只有 TUI 一种用法，其实它有三种调用形态，适用场景完全不同。

第一种是交互式 TUI，就是直接运行opencode进入的界面。适合你坐下来认真处理一个任务，上下文连续，你一句它一段，模型能逐步推进任务。日常编码推荐这种。

第二种是run 模式，也就是opencode run "描述任务"，一次性执行完退出。适合脚本化、自动化，或者快速问一个问题不想进界面的情况。我在写自动化脚本时经常这样用，比如批量给代码文件加注释：

opencode run "给 src/utils/ 下所有 .ts 文件加上文件头注释，说明该模块的功能"

第三种是作为 CLI 参数直接传递文件路径。opencode run -f src/index.ts "优化这个文件的性能瓶颈"这种方式可以在不进入完整 TUI 的情况下，精准地把某个文件作为上下文喂给模型，非常适合快速局部重构。

4.2 会话恢复与上下文控制

OpenCode 的会话机制是我觉得它做得比同类工具更成熟的地方。每个 TUI 会话都会被自动持久化到本地，你可以用/sessions列出所有历史会话，用/resume <id>恢复到某一次对话现场。我自己的习惯是每个功能模块一个会话，比如"登录模块重构""API 错误处理优化"，几天后要继续就/resume找回。

上下文管理上有一个关键动作：经常/compact。AI 会话的时间越长，上下文窗口里堆积的旧内容越多，一方面 token 费用直线上升，另一方面模型容易在大量历史信息中"迷失重点"。/compact会让模型把当前对话压缩成一份精简摘要，作为新的上下文起点。

实测下来，一次长会话在处理 1 万行规模的代码库时，如果不做 compact，token 消耗可能比做一次 compact 多 30% 以上，而且响应速度会明显变慢。所以我现在的习惯是：每完成一个子任务就/compact一次。

4.3 与 Git 工作流结合

OpenCode 在 Git 场景下有几个让我觉得离不开的用法。

生成 commit message 是我用得最频繁的。每次改完代码，直接opencode run "根据当前 git diff 生成一个规范的 commit message"，它对主流 commit 规范的理解很准确，生成的基本不用怎么改。

代码审查也一样。我现在的流程是：本地改完代码 →git diff自己过一遍 → 然后丢给 OpenCode 做第二轮 review。它能发现一些常见的人类盲区，比如忘了处理边界条件、命名不统一、潜在的空指针问题。有一次它甚至帮我找出一个在forEach里return以为会跳出循环的逻辑错误，这个 bug 我盯着看了两遍都没看出来。

分支清理和仓库维护类操作也可以交给它。比如"找出项目里已经合并却被遗忘的 git 分支并列出删除命令"这类任务，它做得又快又准。配合权限控制系统，我一般先把权限设成只读让它分析，确认命令没问题再手动执行，这样既利用 AI 的效率又保留人的最终控制权。

4.4 和编辑器配合：TUI 体验与终端多开技巧

有人可能会问：它只能在终端里用吗？能不能配 IDE？答案是：除了 TUI，它也能通过标准输入输出和编辑器集成。我目前的方案是 iTerm2 里开两个面板，左边是编辑器，右边是 OpenCode TUI。改代码在左边，对话和分析在右边，切换成本几乎为零。

如果你是 Vim / Neovim 用户，可以把它作为外部终端工具调用来配合使用。在 Vim 里用:!opencode run "..."直接执行命令并把输出带回编辑器，这个体验很接近"编辑器内 AI"，不过个人还是觉得独立 TUI 更顺手，因为 OpenCode 自己的界面里渲染 diff、文件树、工具调用结果更舒服。

一个小技巧：设置一个 shell 别名，比如alias oc='opencode'，输入效率会高不少。另外在 TUI 里按Ctrl+L清屏的时候注意，清掉的是终端显示，不是会话上下文，这点和很多聊天工具的逻辑不太一样，别误以为清了屏 AI 就"失忆"了。

5. 隐私边界与本地运行：哪些留在本机，哪些上了云

5.1 本地优先：配置、会话、工具调用记录都存在哪

用过 OpenCode 一段时间后，我对它的数据流向逐渐清晰了。它的设计是典型的本地优先（local-first）架构：配置文件、认证信息、历史会话、TUI 状态全部存本地磁盘，不依赖官方云账号体系。

具体来说，macOS 上这些数据通常在~/.config/opencode/和~/.local/share/opencode/下，里面能看到opencode.json、auth.json、sessions/等文件。你不需要登录任何 OpenCode 账号就能用，所有身份和上下文都绑定在本机。

这个设计的一个直接好处是：换网络、换公司、甚至离线状态下，你的会话历史都还在，项目上下文不会因为"云端同步失败"而丢失。如果有备份需求，直接把整个目录打包拷贝到新机器就行，不需要额外的云端迁移流程。

5.2 模型请求链路：什么时候你的代码会离开电脑

本地优先不等于完全离线。当你向 OpenCode 提问并要求它分析代码时，相关文件内容和对话会被发送到你配置的模型提供商那里——无论是 Anthropic、OpenAI、Google 还是 OpenCode 官方的 console 网关，这个请求必然经过公网。

这点一定要拎清楚：所有 AI 编程助手（包括 Claude Code、Cursor、Copilot）在处理真实代码时，都不可避免要把代码发送给模型服务端。OpenCode 也一样，区别只是你可以选择发给哪一家，以及你能清楚看到这份代码发给了谁。

我自己对敏感项目的做法是：在 OpenCode 配置里只启用本地或私有化部署的模型（比如 Ollama 加载的本地模型），这样代码完全不出内网。代价是模型能力会明显下降，复杂代码理解力不如大厂商用模型。所以这是一个需要你根据项目敏感程度做的权衡，没有什么"既要又要"的方案。

5.3 针对敏感仓库的降险做法

结合我实际在金融项目里用 OpenCode 的经验，给几个降险建议：

一是最小化上下文原则。用/git或显式文件路径等方式，只把当前改动涉及的文件交给模型，不要让它扫描整个仓库。OpenCode 支持限制工具访问范围，可以在配置里把不需要的目录从索引中排除。

二是脱敏预处理。给模型看代码时，把库名、内部服务名、具体 IP 地址等敏感标识替换成中性占位符。这个步骤虽然麻烦，但在非常高敏的环境里值得做。

三是只读模式优先。初次接入一个新项目时，先用只读模式让 OpenCode 分析和给出建议，确认它是可靠的再放开写权限。这样即便模型"发挥失常"产生了错误修改，也不至于直接污染你的代码库。

四是审阅输出。OpenCode 的每一次文件修改都会在 TUI 里展示 diff，记得养成交互式审阅的习惯，不要让它直接自动落盘改代码。这个习惯能挡住绝大多数 AI 误操作。

6. 我实际用下来觉得最值得注意的几个坑

6.1 大上下文时的 token 费用，比你想象的涨得快

第一个坑是费用。OpenCode 默认会把你当前会话里所有的历史消息一并发送给模型，作为上下文。当你在一个会话里连续问了 20 轮、每轮都带着大文件内容时，最后一轮的 token 数量可能已经非常惊人。

拿我自己的真实账单举例：用 Claude 类模型处理一个大型前端项目，有一天我连续在一个会话里做了 3 小时的重构，中间没有做过一次/compact，当天这一条会话的 API 花费就快追平我一周的咖啡钱。这让我意识到，在 OpenCode 里，控制 token 不是优化项，而是必备项。

操作上的建议很朴素：任务切换就开新会话，长会话每完成一个阶段就/compact，能传给模型的内容尽量精简。不要觉得"让它自己多看看"效果会更好，上下文太乱的时候模型输出的质量反而会下降。

6.2 长会话的"答非所问"：换 session 的时机

第二个坑和 token 相关但表现形式不同。我在使用中注意到，同一个会话延续太久之后，模型偶尔会开始答非所问——比如你问 A 函数怎么改，它却扯到之前某个完全不相关的讨论里去了。这不是模型坏了，而是上下文里的历史干扰信息太多，模型被"带偏"了。

判断时机的方法是观察输出质量：如果最近几次回复开始重复、答错上下文、忽略你明确补充的条件，就意味着该换会话了。OpenCode 的会话恢复机制足够好，你完全可以开一个新会话，把关键约束重新描述一遍，效果通常比硬着头皮在旧会话里纠正更好。

6.3 TUI 快捷键的学习曲线

第三个坑听起来很小，实际影响体验最大：OpenCode 的 TUI 界面是终端原生的，快捷键体系和传统 GUI 完全两码事。很多人刚进去会有点手足无措——怎么退出？怎么中断正在执行的任务？怎么查看工具的调用日志？这些操作都有对应的快捷键，但默认界面不会像 IDE 那样给一堆按钮提示。

我的建议是花二十分钟把/help里的内容完整看一遍。具体到我的习惯：中断当前任务用Ctrl+C，切会话用/sessions，强制清屏是Ctrl+L，查看本次会话的工具调用记录也有对应的命令。熟悉之后，全键盘操作的速度是 GUI 完全追不上的。

最后分享一个我目前的工作流作为收尾：日常开发时，我会把 OpenCode 当作"第二双眼睛"。写代码前先让它做方案分析，写完代码让它做 diff review，CI 挂了我也会第一时间丢给它看日志。重度任务用 GO 套餐的稳定流量，敏感场景切到自带 key 的受控模型，纯粹试玩的时候才会回到 console 免费额度。这几种模式互相补充，基本覆盖了我日常所有的编码场景。如果你刚开始接触 OpenCode，我的建议是先别急着配任何东西，直接跑一次opencode run "介绍一下这个项目"，感受一下它在终端里的工作方式，再决定要不要深入使用。