企业官网建设流程全解析

OpenCode 最近在终端 AI 编程助手这个圈子里讨论度很高。简单说，它是一个跑在命令行里的开源 Agent：你告诉它“把这个接口的鉴权逻辑补上”，它会自己读代码、定位文件、改完再跑一遍测试给你看。跟 Claude Code、Codex 这类产品相比，OpenCode 最大的特点是配置透明、模型自由、社区迭代快。这篇文章我会把我从安装、接模型、装插件到拿它实际接手一个存量项目的完整过程写下来，中间穿插大量踩坑记录，希望能帮你省掉不少查文档的时间。

1. 先把 OpenCode 装好：跨平台安装与初始化

1.1 安装方式与版本选择

在开始折腾之前，先说结论：OpenCode 的安装方式非常多样，官方推荐的是脚本安装，但实际工作中，不同操作系统的人往往习惯不同的包管理器。我目前见过的最顺手的几种组合是这样：

• macOS 上可以直接用 Homebrew：brew install sst/tap/opencode
• Linux 上一般用官方脚本：curl -fsSL https://opencode.ai/install | bash
• Windows 上最稳妥的是 npm 全局安装：npm install -g opencode-ai，前提是机器上已经有 Node.js 18 以上版本
• 如果不想全局安装，也可以用npx opencode-ai@latest临时跑一次

如果你所在的环境没法直接访问公开软件源，或者公司内网有软件源审计要求，其实也可以从 GitHub Releases 页面手动下载对应平台的二进制压缩包，解压之后把可执行文件放到 PATH 目录里。这种方式看着笨，但在 Windows 服务器和离线开发机上是最可靠的。我自己就在一台不能随便装东西的 CI 机器上这么干过，五分钟不到，比跟网络策略搏斗一整天舒服多了。

这里插一句版本选择的问题。热搜词里有人提到“opencode 2.0”，我自己的体感是 2.x 版本之后界面和会话管理进步很大。早期版本用起来更像一个“能聊天的终端”，现在的版本才真正有了 Agent 的样子，多文件改动、审批流程、会话恢复这些能力都跟上来了。所以我的建议很直接：只要没有特殊兼容性包袱，尽量装最新版，别拿一年前的教程去对着现在的界面操作，很多按钮和命令已经变了。

1.2 初始化配置与项目级 AGENTS.md

安装完成后，在任意项目目录里输入opencode，如果能看到一个全屏的终端交互界面，就说明装成功了。第一次进入界面，我建议先别急着跟它对话，而是先做三件事：

• 输入/init，让 OpenCode 扫描当前目录结构。它会主动去读 README、package.json、pom.xml 这些关键文件，生成一份项目心智模型。
• 输入/models看看当前可用的模型列表。如果还没有配置任何 API key，这里通常只会有本地模型入口。
• 确认配置文件位置。在 Linux/macOS 上一般是~/.config/opencode/opencode.json，Windows 通常在%USERPROFILE%\.config\opencode\下。这个路径后面会频繁用到。

配置文件采用 JSONC 格式，也就是允许写注释的 JSON。OpenCode 官方提供了 schema 校验，配置字段拼错会直接标红，这一点对新手很友好。我印象很深的一次踩坑是配置 provider 时把models写成了model，结果模型列表一直加载不出来，后来才发现是单词拼错。这种错误在普通 JSON 配置里很难一眼看出来，schema 校验至少能帮你把低级问题挡在启动之前。

项目级配置放在.opencode/目录下。我强烈建议在项目根目录放一个AGENTS.md，把构建命令、目录结构、团队规范写进去，OpenCode 每次开始会话都会自动读取，相当于给 Agent 喂了一份“项目说明书”。这个习惯越早养成越好，尤其是团队协作项目，它能让所有成员的 Agent 行为保持一致，而不是每个人都靠口头沟通去建立自己对项目的理解。

2. 模型接入是重中之重：从本地模型到商业 API

2.1 环境变量与配置文件两种接法

OpenCode 底层基于 Vercel AI SDK 的 provider 机制，这意味着市面上绝大多数大模型服务商，只要提供 OpenAI 兼容接口，基本都能接进来。最简单的接法是直接用环境变量：

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

然后启动 opencode，它就会自动识别出对应的模型。这种方式适合个人快速试用，缺点是不太好管理“多套配置”：换一个 key 就要改环境变量，时间一长很容易乱。我自己早期就是这么用的，直到有一天在三个项目之间来回切配置，切到怀疑人生，才老老实实改成配置文件管理。

我更推荐的方式是在opencode.json里声明 provider，把 baseURL、apiKey、模型 ID 集中放在一起。以本地 Ollama 服务为例，配置大概长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama-local": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama Local", "options": { "baseURL": "http://localhost:11434/v1", "apiKey": "ollama" }, "models": { "qwen2.5-coder:14b": { "name": "Qwen 2.5 Coder 14B" } } } } }

这里有几个字段值得解释清楚。npm字段是告诉 OpenCode 用哪个 SDK 适配器，对 OpenAI 兼容接口来说填@ai-sdk/openai-compatible即可；baseURL是模型服务的 API 地址；apiKey有些本地服务并不校验，但字段必须存在，随便填一个占位符就行。models下面每个键都是模型 ID，这个名字必须和模型服务实际返回的模型名完全一致，否则请求会报错。这也是很多人配置完发现“模型能用但 OpenCode 里选不到”的最常见原因。

2.2 用 CC Switch 管理多套模型配置

热搜词里有一条“opencode go 需要配合 cc switch 等工具”，这里的 go 指的是社区里一种把多模型请求做统一转发的“网关式”用法，而 cc-switch 是这类场景里很常用的一个桌面配置管理工具。它的核心功能其实很朴素：你把不同服务商的 key、baseURL 整理成一组一组的“环境配置”，然后在图形界面里一键切换，切换后相关的终端工具（包括 OpenCode）会自动读取到新的环境变量配置。

实际操作中我一般会存三套配置：一套是团队共享的正式 key，一套是本地模型的 baseURL，一套是个人自用的测试 key。日常开发用团队 key，模型服务商限流严重的时候一键切到本地模型兜底，体验非常丝滑。cc-switch 本身不产生任何模型请求，它只负责改写配置，所以不用担心性能或者安全问题。这套组合拳在团队里推广起来也容易，因为它把“改配置”这个最容易出错的环节变成了点按钮。

有一个细节需要提醒：cc-switch 切换配置之后，最好把正在运行的 OpenCode 会话关掉重开。OpenCode 的环境变量是在启动时读取的，你不重启它就一直用旧配置，这时候还容易产生“明明切了模型为什么没生效”的误会。我一开始就因为这个多折腾了十分钟。

2.3 内网与离线环境怎么接模型

再聊一个很多人关心的场景：开发机在隔离内网，模型服务也在内网，怎么接？核心思路就一句话：OpenCode 不关心模型跑在哪里，它只认 baseURL。你在内网用 vLLM、Ollama 或者任何 OpenAI 兼容框架起一个模型服务，然后在opencode.json里把 baseURL 指到内网地址，比如http://llm-internal.corp:8000/v1，就能正常工作，完全不需要碰公网。

要注意的是，别把“免费模型”和“奇怪接口”混为一谈。社区里偶尔会有人分享来路不明的第三方 API 地址，号称零成本用大模型，我劝你别碰。你把项目代码发过去的那一刻，等于把源码送给了不明服务方，这个风险远比省的那点钱大。要找物美价廉的方案，就老老实实用开源模型本地部署，或者选正规云厂商的推理服务。本地部署的开源模型虽然能力上限不一定比得上顶级商业模型，但胜在数据可控、按需定制，很多对隐私敏感的团队都在这么干。

3. 编辑器插件：VS Code 与 JetBrains 全家桶

3.1 VS Code 插件：把 Agent 带进编辑器

虽然 OpenCode 本身是终端工具，但长时间在 TUI 和编辑器之间来回切换确实很累，所以官方和社区都在做编辑器插件。目前 VS Code 生态里能搜到的 OpenCode 插件，体验已经比较成熟了。安装方式跟普通扩展一样，直接在扩展市场搜索 OpenCode 安装即可。

装完之后，左侧边栏会多出一个 Agent 面板。你在编辑器里选中一段代码，右键选择发送给 OpenCode，它就会带着这段代码和当前文件的路径进入对话。改完的代码可以一键应用回文件，也可以先看 diff 再决定合不合并。我最常用的场景是让 Agent 补 JSDoc 注释、修 eslint 报错、做单个函数的逻辑重构，这些任务范围小、上下文清楚，在编辑器里完成比切到终端更快。

不过我的经验是，编辑器插件适合做“局部修改”，而全局性任务，比如“从零实现一个模块”“梳理整个项目的调用关系”，还是回到终端里跑更好。终端 TUI 在展示多文件变更时的信息密度更高，它会把所有改动文件列出来，你可以逐个看 diff，也可以全部合并，这种体验在编辑器侧边栏里暂时还差点意思。另外，两个入口同时开着也不是不行，但注意别在同一项目里开两个不同会话，否则 Agent 对文件状态的认知会互相干扰，改着改着就冲突了。

3.2 JetBrains 插件与 Java 工程的 mvn 配置

JetBrains 系现在也能装 OpenCode 插件，IDEA、PyCharm 都能用，安装路径是 Settings → Plugins → Marketplace 搜索 OpenCode。相比 VS Code，这个插件在 Java 项目里的价值更明显，但也更考验项目配置的完整度。

原因很简单：OpenCode 要帮你改 Java 代码、跑测试，它必须先能编译项目。Maven 项目里如果少了 mvn wrapper，或者依赖没有完整拉过一遍，Agent 执行mvn compile就会一头雾水，然后给出一些看起来合理但根本编译不过的“修复”。我建议在让 OpenCode 动 Java 代码之前，先在项目根目录放一个 AGENTS.md，明确写上：

• 构建命令：mvn -q -DskipTests clean compile
• 测试命令：mvn -q test
• 关键依赖说明：项目用了 Lombok，代码生成发生在编译期，IDE 里报红不代表编译错误

这样再配合 IDEA 插件做代码审查，体验会顺很多。另外补充一个实操细节：IDEA 插件第一次连接 OpenCode 时，可能会要求指定二进制路径。如果你装的是 npm 版，建议把 npm 全局 bin 目录加到插件的 PATH 配置里，否则插件日志里全是“command not found”，看起来很像 OpenCode 坏了，其实是插件找不到可执行文件。

4. 让 Agent 更聪明的三板斧：Skills、Memory 与 Superpowers

4.1 Skills：把工程规范变成 Agent 的规则库

用过一阵子 OpenCode 之后，你会发现它最大的瓶颈不是模型，而是“不了解你的团队规范”。比如你们规定前端组件必须用 CSS Modules、禁止行内样式，模型并不知道这件事，于是生成的代码总是要你二次修改。这时候就要用到 Skills 机制。

OpenCode 的 Skills 本质上是一组带说明文档的规则文件，一般放在两个位置：全局的~/.config/opencode/skills/<skill-name>/SKILL.md，或者项目根目录的.opencode/skills/<skill-name>/SKILL.md。两者区别在于作用范围，全局的对你本机所有项目生效，项目级的只对当前项目生效。SKILL.md 的开头是描述这个 Skill 用途的元信息，正文就是具体规则。我随手写一个前端组件的例子：

--- name: fe-component description: 当需要新增或修改前端 React 组件时使用，约束组件目录、类型与样式规范 --- - 组件文件统一放在 src/components/<组件名>/ 下 - 每个组件必须同时包含 index.tsx 和 types.ts - 样式使用 CSS Modules，禁止行内 style - 提交代码前运行 npm run lint，确保无 error

当你在对话里请求“新增一个登录表单组件”时，OpenCode 如果识别到fe-component这个描述和当前任务匹配，就会把这套规则加载进上下文，生成的代码自然就符合规范。这个机制最让我满意的地方是规则文件是纯文本，可以直接放进 git 仓库，新同事拉下来就有同样的 Agent 行为，不需要任何人花时间口头科普。

4.2 Memory：跨会话记住项目背景

“上个会话不是已经说过这个项目用 pnpm 吗？怎么这次又问我？”这是刚用 Agent 编程工具的人经常遇到的困惑。OpenCode 的 Memory 机制就是为了解决这类问题设计的，但它的实现方式比较轻量，不像给人用的产品那样是一个庞大记忆库，更像一种上下文持久化策略。

我自己常用的做法分两层。第一层是长期事实，放进项目根目录的 AGENTS.md，包括项目架构、构建命令、代码风格、已知坑位。第二层是会话内偏好，遇到只有当前任务相关的信息，就在对话里说清楚即可，不需要写进 AGENTS.md。如果你发现某条偏好反复出现在多个会话里，比如“后端接口统一用 /api 前缀”，那就应该把它提升到 AGENTS.md，只有这样才能真正跨会话生效。有些版本还支持直接在对话里要求 Agent“把这条规范追加到 AGENTS.md”，我会检查一下它追加的位置对不对，再让它保存，毕竟 Agent 偶尔也会把规则写到离谱的地方去。

4.3 Superpowers：一键接入开源技能包

热搜词里“opencode 安装 superpowers”“opencode 接入 superpower”，指的就是把 GitHub 上开源的技能包直接装进 OpenCode。最出名的是 obra/superpowers，里面维护了一批面向编程任务的 Skill，比如“TDD 工作流”“代码 review 清单”“重构步骤模板”等，省去了自己写规则的功夫。

安装方式不复杂，先克隆仓库，再把它的 skills 目录软链到 OpenCode 的全局 skills 目录：

git clone https://github.com/obra/superpowers ~/superpowers mkdir -p ~/.config/opencode/skills for s in ~/superpowers/skills/*; do ln -s "$s" ~/.config/opencode/skills/$(basename "$s") done

装完之后开一个新的 OpenCode 会话，再请求相关任务时，对应的 Skill 就会自动生效。我的建议是别一口气把全部技能都链接过去。技能包本质上是一堆 prompt 模板，加载得越多，模型处理每个请求时要做匹配的开销就越大，上下文也更容易被无关信息挤占。挑你日常用得到的三五个就够了，剩下的做成一个备选清单，需要时再逐个开。Skill 的选择跟选插件一样，贵精不贵多。

5. 实战记录：用 OpenCode 接手一个存量项目

5.1 项目概览与 /init 初始化

为了写这篇文章，我专门找了一个真实的存量项目重新走了遍完整流程。项目是一个前后端分离的电商后台，前端 React + Vite，后端 Java Spring Boot 用 Maven 管理，代码量不算小，而且没有完善的 README，属于典型的“人走茶凉”型代码库。

我的第一步是在项目根目录运行opencode，然后直接输入/init。这里要提醒一下，/init不是聊天，它是一个让 Agent 认真读项目结构的指令。等它跑完，我会再追问几个问题：“项目有哪几个模块？前端构建命令是什么？后端启动需要哪些配置？”通过这种问答，我既能验证它对项目的理解是否准确，也能顺便发现/init生成的 AGENTS.md 里有没有遗漏的地方。

这一步做完，后面的效率提升会非常明显。OpenCode 不再把 src 目录当成统统要猜的地方，它知道哪块是页面、哪块是 API 层、哪块是公共组件。个人建议不管项目多小，接手的第一天都花十分钟做这个初始化。这个习惯帮我省过太多次“Agent 改错文件”的尴尬了，花十分钟换未来无数个正确的文件定位，非常划算。

5.2 用 Playwright 定位前端 Bug

这次实战我故意挑了一个玄学 bug：用户反馈登录页偶发白屏，但本地偶尔能复现、偶尔不能。靠人肉刷新页面很折磨，我决定让 OpenCode 写一个 Playwright 脚本来自动化复现。在对话里我给出的指令很简单：“写一个 Playwright 脚本，打开本地登录页，循环访问 20 次，采集每次的 console 报错和是否白屏，把结果输出到 report.txt。”

OpenCode 很快就生成了类似这样的脚本：

const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch(); const page = await browser.newPage(); const errors = []; page.on('console', msg => { if (msg.type() === 'error') errors.push(msg.text()); }); page.on('pageerror', err => errors.push(err.message)); for (let i = 0; i < 20; i++) { await page.goto('http://localhost:5173/login', { waitUntil: 'networkidle' }); const visible = await page.locator('#app').isVisible(); console.log(`${i + 1}: visible=${visible}`); } await browser.close(); })();

跑完之后，脚本在日志里暴露了一个 React 组件在未登录态下访问 localStorage 中一个不存在的 key，导致整个渲染抛异常，白屏根因确认。接着我让 OpenCode 针对这个错误修复代码，并再次运行脚本验证连续 20 次都没有再出现白屏。整个过程下来，Agent 真正发挥了它“会自动交叉验证”的价值。这也让我养成了一个习惯：改完代码，一定要让 Agent 用脚本自证，而不是看完 diff 就拍板。

5.3 用 OpenCode 做日常 Code Review

除了写代码，OpenCode 还能做代码审查。它提供了非交互的运行模式，你可以把一次 review 任务当作一条命令来执行，这给日常流水线留了很大的想象空间。我常用的命令格式类似：

opencode run "review 当前分支相对 main 的改动，检查潜在 bug、安全问题、命名一致性，输出问题清单" --model <你的模型ID>

在团队里，我会把它跟 git 操作组合起来，形成一套“提交前自检”流程：开发完一个 feature，先执行 review，对自己代码里的低级问题做一轮清洗，再把改动推上去让同事人工 review。这样同事的关注点能更集中在架构和业务逻辑上，而不是浪费时间挑“这个变量没判空”这种细碎问题。

这里必须泼一盆冷水：AI review 目前更适合当成前置过滤器。它抓的是变量未定义、错误处理缺失、明显的重复代码这类表面问题，对于业务逻辑是否合理、接口设计是否优雅，价值有限。你要是完全相信 review 报告，会在一些看起来“代码很漂亮但业务完全跑偏”的方案上栽跟头。我见过一个案例，Agent 把某个功能“重构”得很干净，但重构时把一个业务分支漏掉了，review 报告完全没发现，最后还是人工 review 捞回来的。

6. 横向对比：OpenCode、Claude Code、Codex 与 Pi 怎么选

6.1 四个热门终端 Agent 的定位差异

热搜词里有人直接问“opencode codex claude code 哪个 agent 好用”，还有人把 Pi 也拉进来比。我个人的看法是，这题没有标准答案，但有比较清晰的定位差异：

除了这四类，社区里还不断有新的终端 Agent 冒出来，但大部分要么是模型数量太少，要么是配置方式不透明。OpenCode 能在其中保持热度，很大程度上是因为它把“模型自由”和“规则可沉淀”这两件事做到了足够好的平衡。很多开发者选它不是因为功能最全，而是因为不想被单一模型厂商绑定。

6.2 我的选型建议与使用思路

如果团队已经有稳定的模型供应商，那选型核心就看两点：第一，你愿不愿意接受“模型被绑定”；第二，你需不需要 Agent 的规则体系能够被团队共享和 git 管理。从这个角度看，OpenCode 对“不想被绑定”的人最友好，因为换模型只是改配置，不牵动工具本身。而 Claude Code 的优势则在于开箱即用，你不必纠结 provider 怎么配、模型怎么选，装上就是完整的 Agent 体验，适合追求效率而不是折腾配置的团队。

但我也要诚实一点：OpenCode 的配置灵活是双刃剑。模型换成开源小参数模型时，Agent 的规划能力会肉眼可见地下降，这时候别怪 OpenCode，它只是把模型的真实水平暴露出来了。所以我的建议是，日常重活交给强模型，用免费或低成本模型做简单重构和批处理，这才是 OpenCode 最舒服的用法。工具本身没有绝对的好坏，关键看你的容忍度和场景匹配度。

7. 常见报错与排查心得

7.1 Windows 下无法识别 opencode 命令

“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”这条报错，基本是所有 Windows 用户第一次装 OpenCode 时都会遇到的，热搜里也有。原因大概率有两个。

第一个是 npm 全局安装后，全局 bin 目录没有加到 PATH。你可以先在 PowerShell 里执行npm config get prefix查看 npm 全局根目录，正常情况下 Windows 是C:\Users\<用户名>\AppData\Roaming\npm，把这个路径加到系统环境变量 PATH 里，再重启终端就解决了。第二个是安装静默失败，这时候执行npm ls -g --depth=0看看 opencode-ai 是否真的在列表里，如果不在，就需要清理 npm 缓存重新装。

临时救急的方法也有：用npx opencode-ai@latest直接运行，npx 会自动找到本地缓存里的包。这个方法不适合长期使用，因为每次都要解析版本，启动会慢一些，但至少能让你先跑起来看效果。我一般会先救急跑通流程，等有空了再认真处理 PATH，毕竟第一印象很重要，装完就跑不起来很容易打击积极性。

7.2 unexpected server error 到底是谁的锅

报错完整文本是 “error: unexpected server error. check server logs”，很多人第一反应以为是 OpenCode 崩了，其实 OpenCode 只是把后端模型服务的错误转发给你看。排查思路应该按顺序进行。

第一步，确认模型服务的连通性。比如你配置的 baseURL 是http://localhost:11434/v1，那就先用 curl 发一个最简单的请求，验证模型服务和模型 ID 是否可用：

curl -X POST http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "qwen2.5-coder:14b", "messages": [{"role": "user", "content": "hi"}]}'

第二步，确认模型 ID 和配置文件里完全一致。很多平台页面上显示的“模型名称”跟 API 里用的“模型 ID”并不是同一个东西，多一个点、少一个冒号都会导致请求失败。第三步，去看日志。OpenCode 在 Linux/macOS 上的日志一般在~/.local/share/opencode/log下，Windows 则在%LOCALAPPDATA%\opencode\log，在里面搜 error 关键词，能看到是 HTTP 403 还是 timeout，问题性质完全不同。403 基本是 key 或鉴权问题，timeout 则要查网络和模型服务负载。

7.3 杂项问题速查表

最后整理一个我在各种交流渠道里收集到的高频问题速查表，方便你遇到类似情况时快速定位：

写到这里，OpenCode 从安装到实战的基本链路已经完整了。我个人在实际项目里跑了大半年，最有感触的一点是：这工具真正的学习门槛不在命令和配置，而在“你愿不愿意把团队的规范沉淀成文件”。AGENTS.md 写得好不好，Skills 覆盖得准不准，直接决定了 Agent 是高级补全还是半个团队成员。

最后再分享一个小技巧：每次让 OpenCode 完成一坨任务后，记得花一分钟把这次任务里涉及的新规范追加到 AGENTS.md 或者对应的 Skill 里。积累两三个星期，你会发现这个 Agent 越来越“懂你们项目”，这才是 OpenCode 最值得投入的地方。