企业官网建设流程全解析

先从我的实际体验说起。过去大半年我一直在终端里工作和调试代码，IDE 里的 AI 插件虽然方便，但总觉得“被锁在编辑器里”了——代码在仓库里，上下文在终端里，运行结果在日志里，插件往往只看到了一个角落。而 opencode 这个终端 AI 编码助手改变了我的工作方式：它直接跑在终端里，能读仓库、改文件、跑命令、看输出、生成 patch，本质上是一个能主动干活的编码代理，而不是一个只能聊天的补全器。这篇文章就从安装、模型接入、日常修复 bug 的实际用法、Skills 扩展，再到我踩过的几个坑，完整梳理一遍。无论你是第一次听说 opencode，还是已经装上但被配置、报错卡住，都可以照着做。

1. 安装前先搞清楚：opencode 到底解决什么问题

opencode 最核心的价值是把 AI 会话放到真实的开发环境里。它不像很多 AI 对话工具只在聊天窗口里写代码，而是建立一个 agent 循环：AI 可以读取你的项目文件、执行终端命令、创建和修改文件，然后根据命令输出继续决策。你可以把它理解成一个“懂得用工具的结对程序员”，而不仅仅是一个“回答问题的搜索引擎”。实际用下来，它在下面几类场景最顺手：

• 修 bug：直接把报错信息丢给它，它能定位问题、改代码、跑测试验证。
• 做重构：读完整目录结构，跨文件改动，最后统一生成 diff。
• 处理重复劳动：批量改格式、加注释、补测试这类体力活。
• 学习陌生项目：让它先分析目录和入口，再总结模块关系和调用链。

opencode 的形态很灵活。平时我主要在终端里用它的 TUI 界面（Text User Interface），但其实它还有桌面版（opencode desktop）、VS Code 扩展、CLI 非交互模式，还支持opencode serve把能力暴露成服务给局域网内其他设备用。单就这一个特点，它就不是一个简单的“聊天客户端”能替代的。

根据搜索热词里高频出现的“opencode 安装”“opencode vscode”“opencode 桌面版”，大家其实是想把它接入到自己熟悉的开发环境。这没问题，但我的建议是：先装命令行版本，把配置跑通，再考虑桌面版或 VS Code 扩展。命令行版本是所有其他版本的基础，很多报错排查到最后，都会回到命令行版本上做验证。

2. 安装全记录：Linux、Windows、桌面版和 VS Code 扩展

2.1 Linux 下最快的安装方式

Linux 上安装最简单，官方脚本一条命令就能搞定：

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

这个脚本会自动检测系统，下载对应平台的可执行文件，然后放到用户目录下的~/.opencode/bin（具体路径会跟随版本变化）。装完手动把路径加进 shell 配置：

export PATH="$HOME/.opencode/bin:$PATH"

如果你的网络环境下载 GitHub Release 特别慢，也可以考虑走 npm 渠道。opencode 本身是 TypeScript 项目，npm 包里会带一份可执行文件，安装命令是：

npm install -g opencode-ai

用 npm 安装的好处是版本管理和 PATH 都不用自己操心，但前提是你本地已经有 Node.js 环境，建议 18 以上版本。我个人更推荐官方脚本，因为它不依赖 Node 运行时，而且升级频率很高，脚本的更新策略更可控。

还有一种情况是你在 Linux 服务器上用的是最小安装，缺 curl 和 unzip，脚本会提示你先装依赖。Debian/Ubuntu 上可以提前执行：

sudo apt update sudo apt install -y curl unzip git

不想用脚本，直接从源码构建也行。opencode 的仓库在 GitHub 上，克隆后需要 Bun 来构建：

git clone https://github.com/sst/opencode.git cd opencode bun install bun run build

源码构建适合想二次开发或者研究内部实现的人。日常使用没必要那么麻烦，官方二进制够用了。

2.2 Windows 上不要卡在 PowerShell 权限

Windows 上同样提供官方脚本：

iwr https://opencode.ai/install.ps1 | iex

执行前如果 PowerShell 提示脚本被禁止运行，那是因为执行策略默认是 Restricted。你可以用管理员身份打开 PowerShell，先执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后再运行安装命令。

装完之后，可执行文件在%USERPROFILE%\.opencode\bin。PowerShell 里如果直接输入opencode提示找不到命令，需要把这个目录加到系统 PATH。注意，Windows 上我遇到过几次安装脚本成功但 shell 缓存没刷新的情况，新开一个终端窗口再试就好了。

Windows 上另一个高频问题是终端类型。opencode 的 TUI 界面在 Windows Terminal 下表现最好，在老的 conhost 窗口里可能会出现光标闪烁、渲染错位的问题。如果遇到界面花掉，优先换 Windows Terminal 或 VS Code 内置终端。

2.3 桌面版和 VS Code 扩展怎么装

桌面版（opencode desktop）可以从官网首页下载对应操作系统的安装包。它的本质是给 TUI 套了一层本地 GUI 壳，模型配置、对话列表、session 数据这些和命令行都是共享的。所以哪怕你平时主要用桌面版，也建议把 CLI 版装上，排查问题会更方便。

VS Code 扩展在扩展市场里直接搜 opencode 就能找到，注意认准官方发布者。扩展装好后会在侧边栏出现一个新的 opencode 面板，你可以直接在面板里新建会话，也可以选中代码后右键发送给 opencode 分析。

这个扩展值得装，因为实际开发里“看代码”这个动作还是在编辑器里更舒服。扩展本身不承担重逻辑，它是通过本机 CLI 进程来通信的，所以使用前必须确认opencode命令能在终端里正常启动。

2.4 安装后的三分钟验证

装完别急着改配置，先跑几个命令确认基础环境正常：

opencode --version opencode --help

如果能正常输出版本号和帮助信息，说明可执行文件没问题。但这里有个隐藏问题：即使 CLI 能跑，也可能因为缺少 git、curl 等外部命令导致 agent 在执行任务时中途失败。建议一次性确认：

git --version curl --version node --version

在 Linux 上再确认一下你有没有 unzip，因为 opencode 解压或转换某些资源时会调用它。

之后直接在终端输入：

opencode

会进入 TUI 交互界面，第一次启动它会提示配置登录或选择模型。如果你先不登录，也能进入界面，但发消息大概率会报模型相关的错误。所以下一步就是接模型。

3. 模型接入详解：免费模型、OpenCode GO 套餐和本地模型

3.1 先理解 opencode 的“模型”概念

opencode 本身不生产模型，它是模型提供商（provider）的客户端。你可以在一个配置里同时填 OpenAI、Anthropic、本地 Ollama，甚至公司内部兼容 OpenAI 接口的网关。TUI 里按/models就能切换当前会话使用的模型。这个设计有点像一个“万能遥控器”：一个界面操作多套模型，不必为每个模型商单独装客户端，这也是 opencode 增长快的重要原因。

在开始用之前，你需要决定自己的主力模型走哪条路：

• 官方内置免费模型：适合尝鲜，有额度限制，且只能从官方客户端内使用。
• OpenCode GO 套餐：官方订阅制，一个套餐访问多款主流模型，按月付费，对编码代理这种高频 token 消费场景更划算。
• 自带 API Key：在 provider 里填自己的 Key，按用量计费。
• 本地模型：外接 Ollama，跑开源模型，数据不出机器，但速度和质量取决于你的显卡。

3.2 内置免费模型与“只能从 opencode 内使用”的提示

opencode 现在内置了免费的使用额度，不需要绑定支付方式就能体验部分模型。这个免费额度本质上是官方统一采购并转发给模型厂商的，不是你在模型厂商官网申请的免费试用，所以它有一个非常关键的使用边界：免费流量必须来自 opencode 官方产品内部。

这就是文章开头那个报错的原因：

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

见到这个错误，基本可以判断请求的来源没被识别为官方客户端。常见的触发场景包括：通过第三方客户端、自定义脚本、逆向接口、或者把 opencode 的接口地址填到了别的工具里。解决方式不是去绕，而是回到正常的用法：

• 确认你用的是官方 CLI、桌面版或 VS Code 扩展最新版，并重新在 TUI 里跑一次/login登录。
• 如果你确实在官方客户端里还报这个错，优先升级版本，旧版本有时因为认证信息格式变更导致来源校验失败。
• 别试图把免费额度伪装成自定义 Provider 拿去给其他工具用，这个行为官方设计上就禁止了，持续用下去只会封账号。

免费额度我一般只用来做快速验证、问概念问题，实际写代码任务还是用自己的 Key 或付费套餐，稳定性更重要。

3.3 OpenCode GO 套餐怎么选、怎么配

OpenCode GO 是官方推出的统一订阅套餐，你只需要一个 OpenCode 账号，订阅后就能访问套餐内包含的多家模型，费用集中在套餐里，不用分别到多个模型厂商后台充值。对国内用户来说，它还顺带解决了单一模型厂商账号申请、跨境支付之类繁琐的问题。

怎么接入？在 TUI 里输入：

/login

会生成一个登录链接，浏览器打开后用 OpenCode 账号授权登录。登录成功后，打开模型列表就能看到套餐内可用的模型。如果你之前已经登录但没有看到套餐模型，重新执行一次登录流程即可。

用 GO 套餐时，我建议把主要精力放在体验模型本身，而不是纠结“哪个模型最强”。套餐内的模型经常更新，每隔一段时间留意一下官方更新日志比你自己反复对比更高效。另外，编码代理场景非常吃 token，比如一次自动修 bug，AI 可能要读十几个文件、生成多次 diff，整个过程下来的 token 消耗比纯聊天大得多。如果你发现额度消耗飞快，不一定是配置错了，而是任务本身真的太重。

3.4 自带 Key 和自定义 Provider 的配置方式

如果你有自己的模型厂商 API Key，可以不登录套餐，直接用环境变量方式配置。平时最常改的变量是：

export ANTHROPIC_API_KEY="sk-ant-..." export OPENAI_API_KEY="sk-..."

也可以把配置写进~/.config/opencode/opencode.json：

{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4-20250514", "provider": { "openai": { "api_key": { "env": "MY_OPENAI_KEY" } } } }

有些公司或团队内部有兼容 OpenAI 协议的统一网关，只需把 base URL 指过去：

{ "provider": { "my_corp_gateway": { "npm": "@ai-sdk/openai-compatible", "name": "My Corp Gateway", "options": { "baseURL": "https://gateway.example.com/v1", "apiKey": "your-key" }, "models": { "my-model": { "name": "My Model" } } } } }

这里要留个心眼：如果自定义 Provider 配置有误，错误信息往往不是“配置错误”，而是“模型不存在”或“认证失败”。先打开模型列表，如果看不到你配置的模型名，多半是 JSON 解析失败或 models 字段格式不对。

3.5 本地模型：OpenCode 连接 Ollama，以 Granite 为例

本地模型场景下，Ollama 是最常见的搭档。安装 Ollama 后先拉模型，比如 IBM 的 Granite 系列：

ollama pull granite3.3

然后确保 Ollama 服务在后台运行：

ollama serve

启动 opencode 后打开模型列表，选择ollama/granite3.3即可。如果列表里没有，检查 Ollama 服务是否在同一台机器上、API 端口（默认 11434）是否可访问。有时候你重启过电脑，Ollama 没有设置开机自启，opencode 里就会报连接失败，这种问题跟 opencode 本身没关系，先在浏览器访问一下http://localhost:11434看看。

本地模型最明显的短板是响应速度和推理质量，它在代码理解和跨文件分析上不如云端大模型。我的用法是：本地模型处理小范围格式化、补注释、写单测这类任务，云端模型负责需要全局理解的重活。

4. 实战：让 opencode 自动跑本地项目并修改 bug

4.1 进入一个项目的正确姿势

opencode 对“项目”的理解是基于当前工作目录的。你启动它的方式会直接影响它的视野：

cd /path/to/your-project opencode

在 TUI 里输入/init可以生成或加载项目上下文说明，让 AI 了解项目技术栈、目录结构、构建命令。这一步很多人会忽略，但它对 agent 的后续判断影响极大。项目里如果已有 README 或 CONTRIBUTING 文档，agent 会更准确；没有的话，它也会快速扫描目录结构。

4.2 一次完整的 bug 修复过程

我随便用一个例子来说明。假设一个 Node.js 项目，用户反馈接口超时。我在 opencode 会话里发一句：

用户反馈 /api/list 接口在数据量大时超时，帮我看看可能是什么原因，并给出修复

opencode 会展开它的 agent 循环，大致是这样一个过程：

1. 读代码：它会从核心路由文件开始，找到接口实现，定位数据库查询部分。
2. 跑命令：尝试运行项目已有测试或启动服务，看能否复现。
3. 给出方案：在会话里说明问题根因，并列出准备修改的文件。
4. 改代码：生成完整的文件修改。
5. 运行验证：执行测试或 lint。
6. 输出 diff：在界面里展示变更内容，供你确认。

大多数情况下它会自动执行，但遇到“是否运行 xxx 命令”这类选择时，它会等你确认。我的经验是：给它的任务描述越具体越好。像“帮我优化接口”这种话它也能做，但效果远不如“这个接口在 10 万行数据时响应超过 3 秒，我怀疑是 N+1 查询，请定位并给修复方案”。

在 TUI 里/ask适合不产生代码的问答，/plan适合让它先做分析和修改计划，真正动手改代码的普通会话就是直接发消息。我建议涉及大改动时先走/plan让人工确认方案，再让它执行。不然有时候它会按照一种你不太认可的方案把代码写完了，回滚反而更费时间。

4.3 修改完成后必须做的事

很多新手看到 AI 改了代码就立刻进入下一轮对话，这是危险的。我总结了一套固定流程：

• 先看 diff，确认没有删除不该删的逻辑。
• 跑一遍完整的 lint 和测试，不能只听 AI 口述“测试通过”。
• 如果改了数据库相关代码，检查迁移或索引变化。
• 最后自己再读一遍核心变更文件，确保代码风格符合项目约定。

opencode 的 diff 视图和 git diff 几乎一样，你可以在 TUI 里直接按快捷键逐段 review。遇到不满意的改法，直接回一句“这个方案不行，换一种实现方式”，它会重新分析并给出新方案。

4.4 好用但容易忽略的参数

opencode run "修复 src/utils.js 里的内存泄漏"

这是非交互模式，适合在脚本或 CI 里调用。它会一次性执行任务并退出。配合--model指定模型，--agent指定 agent 类型。我在自动化流程里经常用它做“提交前自动审查”，很管用。

5. Skills 扩展：从安装到自己写

5.1 Skills 到底是个什么东西

Skills 可以理解为给 opencode 预定义的“行为模板”。默认情况下，AI 面对任务时会临场发挥；而 Skills 就是把“如何做代码审查”“如何写提交信息”“如何启动项目并且判断成功”这类流程固化下来，让它按步骤执行。它的核心是SKILL.md文件，里面描述了触发条件、执行步骤和注意事项。

搜索热词里大量出现“opencode skill 安装使用”，说明很多人已经发现：官方客户端只是基础能力，真正让 opencode 变高效的是给不同任务挂上对应的 Skills。

5.2 安装现成 Skills

社区里有不少公开的 Skill 仓库。opencode 提供了内置的安装命令，大致逻辑是：

opencode skill add <skill-name>

它会从官方或社区 Skill 仓库下载对应技能文件，放到本地的技能目录。装完可以在 TUI 里执行：

/skills

查看所有已安装技能。如果列表里没有刚装好的技能，重启 opencode 再看一次。

我个人建议先装这几个类型的 Skill：

• commit-message：自动根据 git diff 生成符合规范的提交信息。
• code-review：对当前分支 diff 做全面检查，输出问题清单。
• test-writer：为指定模块生成单元测试。
• docs-updater：代码改动后同步更新相关文档。

5.3 手写一个 Skill

自己写技能只需要创建目录和 Markdown 文件。默认技能目录位置：

• Linux:~/.config/opencode/skills
• Windows:%USERPROFILE%\.config\opencode\skills

在目录下建一个子目录，里面放SKILL.md：

--- name: check-http-api description: 对指定接口文件进行健壮性审查，重点检查参数校验和错误处理 --- # Check HTTP API - 读取指定的 route 文件，找出所有对外暴露的接口 - 对每个接口检查： 1. 参数是否有 schema 校验 2. 异常分支是否有统一错误返回 3. 是否记录了必要的访问日志 - 输出问题清单，每条给出严重级别和修改建议

保存后重启 opencode，TUI 里执行/check-http-api调用它。AI 读取description字段来判断什么时候适合自动调用这个技能。

5.4 使用 Skills 的几个注意点

Skills 不是魔法，它只是“提示词结构化”的升级版。模型能力不够时，再好的 skill 也跑不出高质量结果。另外，写 SKILL.md 时一定要具体——告诉 AI“检查参数校验”比“优化接口质量”有用得多，因为后者它不知道怎么落地。我见过很多新手写的 skill 特别宏大，AI 看完根本不知道从哪里下手，这种 skill 装了等于没装。把一个大任务拆成 5 个小步骤，每步写清楚动作和验收标准，这才是合格的 skill。

6. 踩坑记录：最高频的几个报错与处理

6.1 free tier 报错的完整排查链路

我前面提到过这个报错：

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

实际排查时可以按这个顺序检查：

1. 确认你当前用的模型是否属于免费额度范围。有些模型本身不参与免费，硬选的话报错信息可能让你误以为所有模型都不可用。
2. 检查客户端版本。旧版 TUI 或扩展可能出现认证头格式问题，导致官方网关不认这个请求。
3. 在 TUI 里执行/login重新登录一次，再切回免费模型。
4. 如果使用的是自定义 Provider 或第三方配置，请删掉该配置并回到官方渠道。

这个报错的本质是“来源认证失败”，不是额度用完。额度用完通常是另一个提示，比如 429 或 “quota exceeded”。很多人把这两类错误混在一起排查，白白浪费不少时间。

6.2 桌面版“模型列表一个都没有”的解决办法

热词里有“opencode desktop 选择模型那里一个模型也没有了”。这个我遇到过一次，当时是怎么发生的：我改了自定义 Provider 配置但 JSON 语法出错了，然后桌面版加载失败，把整个模型列表拉空。

解决办法：

• 先检查~/.config/opencode/opencode.json有没有语法错误，可以在终端里用jq .验证。
• 把配置文件暂时重命名，再重启桌面版。如果模型列表恢复，说明是配置里某个 provider 或 model 定义有问题。
• 不要忘了查看opencode logs。桌面版界面不会把所有错误都展示出来，很多关键报错在日志里。

另外，如果你登录过期，也会出现模型列表加载不出来的情况。这时候重新/login比折腾配置更有效。

6.3 归档的对话去哪了

“opencode 归档后去哪了”是高频搜索。TUI 里按/archive可以把当前会话归档，方便保持会话列表干净。归档后会话不会消失，它只是在主列表里不显示了。你可以在 TUI 里通过归档管理界面重新查看或恢复。真正重要的资料，我建议直接通过/export导出为 Markdown 或 JSON，存到自己的笔记系统里。归档功能方便日常整理，但不能替代外部备份。

会话数据在本地也是有文件落盘的，通常在用户数据目录下：

• Linux:~/.local/share/opencode
• Windows:%USERPROFILE%\.local\share\opencode

如果你想备份历史会话，把这些目录整体拷贝一份就行。

6.4 局域网使用：opencode serve 怎么用

热词里有“opencode serve 局域网”，这个功能适合什么场景呢？比如你在办公室有一台性能强劲的机器，想通过局域网让另一台电脑连过来用同一套模型和会话配置。可以先在这台机器上启动：

opencode serve --hostname 0.0.0.0 --port 34567

另一台电脑上的 opencode 客户端配置里把服务地址指向这台机器的内网 IP。需要注意的是，这样会暴露本地服务，务必只在可信的局域网内使用，不要映射到公网。模型请求本身自带 API Key，一旦被外部访问，Key 泄露风险非常高。我实际用下来，局域网模式下最稳的是相同版本客户端互连，混用版本偶尔会出现协议不兼容。

7. 数据安全与配置管理：我的一些底线

用 opencode 这类 AI 编码工具，数据安全问题绕不开。首先要明确一个基本事实：当你使用云端模型时，你的代码内容会被发送到模型提供商的服务器上用于生成回复。开源模型搭配本地部署，才能做到代码不出本机；但本地模型能力弱一些，需要接受这个权衡。

我的实践建议：

• 公司项目或涉及敏感数据的代码，优先走本地 Ollama 模型，或者内部兼容 OpenAI 协议的网关。
• 个人开源项目，用云模型无所谓，但提交前还是要看一眼哪些内容被发送了。
• 不要在聊天里粘贴 token、密码、私钥这类敏感字符串，AI 分析日志时经常会把环境变量也读进去，稍不注意就泄露出去了。

配置备份同样重要。~/.config/opencode/目录下除了opencode.json还有你可能存的 session 数据、auth 缓存、skills。建议把这个目录纳入你的 dotfiles 管理或者定期打包备份。我自己就吃过亏：换电脑后重新登录配置很繁琐，但提前做了备份的话，复制回来就能直接开始用。

8. 最后分享几个我觉得最有用的习惯

用 opencode 超过一段时间后，我最想强调的是：它强在“循环执行”，但也因为这种强，容易让开发者放弃思考。我的习惯是把它当成一个“执行能力很强的 junior 程序员”，每一步关键动作都要自己确认。它提的 refactor 方案十次里有七次能直接用，但剩下三次会因为不了解历史原因把代码改坏。

还有一个很实际的技巧：不要只在遇到 bug 时才打开 opencode。你可以在开始写新功能前先让它分析现有模块，问它“如果要在这个项目里加一个 xxx 功能，应该动哪些文件，注意哪些隐患”。这种低成本的前置沟通，反而能帮你省掉后面大把的改 bug 时间。

另外，opencode 每个月都在快速迭代，建议养成定期升级的习惯。很多诡异报错在升级后自然就消失了。如果你在旧版本里死磕一个疑似 bug 的问题，先去升级，大概率有惊喜。