企业官网建设流程全解析

最近我被同一个词刷屏了——opencode。先是技术群里有人晒TUI截图，接着VSCode和JetBrains的插件市场都能搜到它，连我那个几乎不发朋友圈的前同事都在问这玩意儿能不能用来接手一个快烂尾的前端项目。作为一个把Claude Code当日常工具用了大半年的人，我本来对“又一个终端AI编程工具”已经免疫了，但两周实测下来，opencode确实值得单独写一篇。

这篇文章按“是什么—怎么装—怎么配模型—怎么干活—报错怎么解”的顺序整理，覆盖安装、模型接入、Skills、Memory、Playwright测试、编辑器插件、桌面版和常见报错，适合刚听说过opencode的人，也适合正在Claude Code和opencode之间犹豫的开发者。先说结论：它不是一个套壳工具，模型自由度、部署轻量度都比我想象中强，但也有一些坑等着你踩。

1. opencode不是又一个Claude Code壳子：项目出身与核心定位

1.1 出身自SST团队，但和Serverless没有绑定

opencode是SST团队开源的项目，源码仓库在sst/opencode。SST本身是做全栈Serverless框架的，所以不少人以为opencode是SST框架的场景配套，实际上不是。它是一个独立的终端AI编程Agent，目标是把Claude Code那套交互体验做成开源、可自托管、模型供应商自由的东西。第一眼看上去确实像Claude Code，但用下来你会感觉到它更偏“工程工具”，而不是把AI聊天框平移到终端。

我特别想强调一个技术点：opencode是Go写的，单二进制分发，不依赖Node.js运行时。这意味着你在一个干净的Linux服务器上，下载一个文件就能跑，不用先装Node、再装npm包、再处理版本冲突。这点对经常要在不同环境里碰代码的人来说太重要了。Claude Code虽然也能装，但每次换环境都要重新折腾一遍npm，opencode直接把二进制拷过去就完事，这也是我把opencode作为主力工具的最初动因。

1.2 终端Agent该有的能力它基本都有

• TUI交互界面：和Claude Code类似的终端界面，但更现代，底部有模式、模型、会话状态的提示，输入框、工具调用、输出分层清楚，看Log不会眼花。
• 三种工作模式：Build、Plan、Agent。Build就是直接改代码；Plan先给方案，你确认了再动手；Agent可以自己连续调工具、跑命令、改文件，遇到问题还能自己退回来调整。
• 内置LSP诊断：这是opencode非常良心的一点。它内置了很多语言服务器，你打开一个项目，它会自己识别语言、做代码诊断，不需要你先跑build才有错误上下文。写代码时，Agent是在一个“能看到编译诊断”的状态下干活的，而不是瞎猜。
• Git集成：分析diff、生成commit信息等，接手旧项目时候会非常有用。
• 模型供应商自由：Anthropic、OpenAI、Gemini、DeepSeek、Ollama、OpenRouter……几乎你能想到的都支持，OpenAI兼容协议的自定义接口也可以接。

1.3 和Claude Code、Codex CLI放在一起看

现在终端AI编程Agent大致分三派：Claude Code闭源但生态最大，Codex CLI是OpenAI官方的开源CLI，opencode是社区驱动的开源实现。opencode相对Claude Code的优势是开源可审计、模型自由、单文件部署；劣势是第三方技能数量暂时没Claude Code那么庞大，但Skills机制已经能复用大部分Claude Code技能包，很多社区脚本也正在往opencode平移。

如果你是个人开发者，喜欢自己掌控配置，opencode的友好度会更高；如果你重度依赖Anthropic全家桶和Claude Code的成熟插件，那就不急着换。我的看法是：工具没有绝对优劣，取决于你想不想被一家模型厂商捆住。

2. 半小时跑通：安装、初始化和Windows那俩坑

2.1 三种安装方式

macOS用户直接用Homebrew：

brew install sst/tap/opencode

Linux和macOS通用，用官方安装脚本：

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

Windows用户建议直接到GitHub Releases页面下载Windows二进制，放到一个固定目录（比如C:\Users\你的用户名\bin），然后把该目录加进PATH环境变量。安装完成后运行opencode --version验证。

我个人的习惯是：macOS上用Homebrew，远程服务器上用脚本或直接拷贝二进制。为什么不用源码编译？因为没必要，官方Release已经做得挺干净。你非要体验从源码build，那也可以，Go项目编译无非就是clone、go build两条命令，但对大多数使用者来说没有意义。

2.2 第一次启动：配置Provider和模型

在项目目录直接敲opencode，第一次启动会进入初始化流程，让你选模型供应商。它会问你把API Key存到系统钥匙串还是配置文件里。如果选配置文件，配置写在~/.config/opencode/opencode.json（Windows是%USERPROFILE%\.config\opencode\opencode.json）。也可以随时用opencode auth login重新登录供应商。

我的建议：本地日常使用，用系统钥匙串存Key比较省心；公司电脑、多环境同步场景，用配置文件更可控。之前我图省事全用钥匙串，结果换电脑时所有配置都要重来，从那之后我就改成配置文件了。

2.3 Windows“无法识别opencode”的根因与修复

热搜里有一条非常经典的报错：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名

这类问题本质是PATH里没有opencode所在目录。安装脚本通常会把二进制放到%USERPROFILE%\.local\bin或类似目录，但PowerShell如果是在安装之前打开的，它读的是旧的环境变量，所以新开一个终端就行。还不行就手动确认目录被加进了用户PATH。

另外一个Windows坑是：要用Windows Terminal运行opencode，而不是老的conhost窗口，否则ANSI颜色乱码和TUI刷新会异常。实测在VS Code集成的终端里也可以，只要它底层是Windows Terminal。这两个坑其实是“新终端工具在Windows上的通病”，大家遇到先别怀疑工具坏了，往PATH和终端模拟器方向查。

2.4 验证一下TUI基本操作

跑起来之后，你会看到底部有一个输入框。先让它分析当前项目：

请先看一遍README和目录结构，然后告诉我这个项目主要做什么。

观察它会调用ls、read之类工具，这正常，不是聊天幻觉，是真的在翻代码。切换模式一般在TUI底部有快捷键提示。第一次跑通建议先在demo项目上试，别一上来就丢生产项目，否则你还没熟悉它的行为模式，就被它一顿工具调用吓到了。

3. 模型接入是灵魂：从Anthropic到Ollama的完整配置路径

3.1 两种配置方式：auth login和opencode.json

opencode的模型配置核心是opencode.json，下面是一个最小化的Anthropic配置示例：

{ "$schema": "https://opencode.ai/config.json", "provider": { "anthropic": { "models": { "claude-sonnet-4-20250514": {} } } } }

注意：具体模型ID以你手里的官方模型列表为准，opencode支持opencode models查看当前可用的模型。如果接自定义的OpenAI兼容服务，配置里需要加baseURL字段，这是最常见的模式。遇到报“model not found”或者“unexpected server error”时，优先检查模型ID是否写错、账号是否有该模型的权限。

3.2 用Ollama跑本地编码模型

本地模型最大的价值是代码不出机器，离线也能用，这对处理敏感项目特别重要。配置provider.ollama，模型名写你在Ollama里拉好的名字，比如qwen2.5-coder:32b。配置好之后，在TUI里/models切换到本地模型就能用。

我实测下来：本地模型的速度和显存强相关，16G显存跑14b左右的编码模型还可以接受，32b会明显慢。本地模型适合“代码补全、单文件修改、解释代码”这类轻任务，重量级跨文件重构还是云端模型更靠谱。如果你的机器跑不动大模型，不要死磕本地，老老实实接云端API，体验会好很多。

3.3 免费与低价模型的接入思路

热搜里有“opencode免费模型”和“opencode hy3-free下线了吗”，我说一下我的看法。社区偶尔会有一些第三方免费接口流传，这类东西最大的问题是不稳定，随时可能下线，而且把代码通过陌生接口传过去也有安全隐患。我不建议把它作为日常工作依赖。

真正稳的思路有这么几条：

• 用厂商官方免费额度，比如新账号的试用额度，适合先跑通流程。
• 用Ollama跑开源模型，零成本但有硬件门槛。
• 用价格很低的开源模型API（比如DeepSeek这类），编码场景性价比不错。

opencode最大的好处是这些全都能接，你可以在一个工具里自由切换。我自己日常是Anthropic为主、本地模型兜底，断网或者接口抽风时切到本地模型至少还能继续干活。

3.4 多供应商切换：CC Switch和oh-my-claudecode

同时配两三套供应商之后，你很快会发现手动改JSON有点烦。社区里有个小工具叫CC Switch，专门干这件事：GUI界面里维护多套模型服务商配置，一键切换，目前主流的几个终端Agent都可以切，opencode也支持。它本质上是帮你改配置文件，省得每次手敲，适合同时用Claude Code和opencode、且有好几套API端点的人。

还有一个经常被一起提的是oh-my-claudecode，它最初是给Claude Code做终端美化/增强的工具链，后来有人把主题和脚本适配到了opencode。我自己的建议：先用原版跑两周，别一上来就叠美化层，否则真出问题时你分不清是工具的问题还是美化层的问题。

4. 真实干活体验：Skills、Memory、Playwright与旧项目接手

4.1 三种工作模式和怎么选

Build、Plan、Agent三种模式不是摆设，选错了体验差别很大。

• Build模式：适合你已经想好方案，让它直接改。比如“把这个接口的异常处理加上”。它不会问太多，说干就干，效率高。
• Plan模式：适合需求模糊、或者要动大结构。它会先读代码、出方案、列改动清单，你点头才动手。接手不熟悉的项目时，先用Plan模式让它把方案摊开给你看，能避免很多翻车。
• Agent模式：适合探索性任务，你给它一个目标，它自己定步骤、自己执行。这个模式最容易出问题的地方是在不熟悉的项目里瞎改，所以我的铁律是：不熟悉的项目从Plan开始，跑通了再切Agent。

4.2 用opencode接手旧项目

接手一个从没见过的项目，直接说“帮我加个功能”是最浪费钱和时间的用法。我的提示词分三步走：

第一步，先看地图：

先不看任何代码，把仓库根目录的README、package.json/pom.xml/go.mod、docs目录列出来，总结这个项目的技术栈、启动方式和测试命令。

第二步，摸底现状：

跑一下测试或lint，把当前的失败项列出来。

第三步，再给具体任务。这样“先地图后攻坚”的顺序非常关键，比一上来就丢任务靠谱得多。opencode会通过LSP建立索引，阅读能力比纯文本检索强，面对大仓库能更准。实操中我给任务时还会带上具体的文件路径或模块名，AI模型的注意力有限，你把地图坐标给清楚，它干活就利索。

4.3 Skills：把superpowers之类的技能包搬进来

opencode支持类似Claude Code Skills的机制，技能就是放一个SKILL.md文件，里面写清楚这个技能在什么场景用、怎么用。全局技能放配置目录的skills文件夹，项目技能放在项目下的.opencode/skills目录。

我写一个小例子：

--- name: debug-frontend description: 当用户报一个前端页面bug时，使用Playwright打开本地URL，复现并定位console报错。 --- 1. 启动项目的dev server 2. 用Playwright打开对应URL 3. 收集console错误与网络失败请求 4. 给出修复建议

这样你只要对opencode说“用debug-frontend帮我看看登录页为什么白屏”，它就会按这个流程走，得到的结果比让它自由发挥稳定得多。社区里热度很高的superpowers技能包也能接进来，它本质上是一个庞大的技能集合，等于给Agent赋予了更结构化的思考方式。我用了之后最大的感受是：技能的真正价值不是让AI记住几个命令，而是把“你希望它怎么做”这件事固化下来，团队的规范也能通过技能文件传承。

4.4 Memory：让AI记住你的项目约定

opencode的Memory功能解决的是“这周记了，下周又忘了”的问题。你可以把项目约定、常用命令、编码规范写进memory，之后每个新会话它都能读到。我第一次在项目里用memory就是把“测试命令用pnpm test --runInBand”和“不要修改generated目录”两条写进去，后面它基本没有再犯同样的错。

建议把你反复纠正过Agent的话沉淀成memory，这是减少重复劳动最见效的做法。比如它老是忘记某个目录的用途，你就明确写一条；它老是生成不合规范的文件命名，也写进去。好的记忆管理比好的提示词更能提升长期使用体验，因为提示词每次都要写，memory是全局的。

4.5 Playwright：让Agent自己复现前端Bug

写前端的人最烦的是AI看不到网页。opencode内置了Playwright，你可以让它打开浏览器、点按钮、填表单、截图。我实际用过的prompt：

用Playwright打开 http://localhost:5173/login，输入测试账号，点击登录，观察是否有报错，把控制台的错误原样输出，并截图。

注意，第一次使用需要装Playwright的浏览器内核，否则会报browser not found。我的经验是：让Playwright测试“稳定复现路径”非常靠谱，但前端页面如果用了大量动态渲染或登录态复杂，需要你先拿到可用的cookie或token再交给它。另外这个功能极其消耗上下文，任务完成尽快开启新会话，不要让它把屏幕截图反复贴到长对话里。

5. 编辑器集成和桌面版：什么时候用终端、什么时候用IDE

5.1 VSCode插件配置

在VSCode插件市场搜opencode，装好后左侧会有面板。它会复用你当前编辑器的文件作为上下文，也能把修复建议直接显示成diff。配置项主要指定opencode可执行文件的路径。

如果VSCode内提示command not found，多半是PATH没带过去。macOS上从Dock或Spotlight启动的VSCode经常遇到这个问题，解决办法是在设置里把opencode的绝对路径填进去：

{ "opencode.path": "/opt/homebrew/bin/opencode" }

5.2 JetBrains插件

JetBrains系（IDEA、PyCharm等）也有opencode插件，用法类似。对于重度IDEA用户，插件的意义是“不用切窗口”。我个人的完整工作方式是：代码阅读、写实现方案用终端TUI；单文件修改、review diff用IDE插件。终端TUI在多文件搜索替换时效率特别高，IDE插件在单文件上下文和diff审阅时更顺手。

5.3 opencode Desktop

桌面版是近期社区讨论比较多的一块，把终端TUI搬到了一个独立桌面窗口里，好处是可以和IDE并行摆放、多显示器工作流更顺。我用下来的感觉是：桌面版更像是终端版的美化外壳，核心还是同一个Agent，不用期望它多出什么魔法能力。如果你习惯IDE插件，也没有必要专门为了桌面版换工作流；如果你是终端重度用户，桌面版确实比开一个Terminal tab舒服一些。

5.4 我的选择逻辑

最终看你的工作流：如果主要用VSCode/JetBrains，建议直接插件起步；如果你经常SSH到服务器上改代码，那终端版才是主力；如果团队协作有统一规范，建议尽量用配置文件统一模型和权限，桌面版和插件都只当客户端，这样新成员接入的时候成本最低。

6. 高频报错排查记录

6.1 “无法将opencode识别为cmdlet、函数、脚本文件或可运行程序的名”

这是Windows用户遇到最多的报错，根因上面说过，就是PATH没生效。排查顺序：

1. 新开一个PowerShell窗口，再跑一次opencode。
2. 确认opencode可执行文件在哪个目录，执行where.exe opencode看能不能找到。
3. 找到之后把目录加进用户PATH，重启终端。

记住：改完PATH一定要开新终端，不是刷新，是彻底关掉重新开。

6.2 “error: unexpected server error. check server logs”

这个报错看起来像opencode自身崩了，其实绝大多数是模型服务端返回了异常。我从排查经验里总结的优先级：

1. 先跑opencode auth list，确认当前用的哪个供应商、哪个Key。
2. 换一个模型试试，比如从大模型换到小模型，排除模型ID或权限问题。
3. 到对应模型服务商的控制台看调用记录和计费情况，确认是不是量用完了。
4. 检查配置里baseURL是否写对，有没有多余空格或末尾斜杠。

这类报错80%以上是Key失效、额度不足、模型ID不合法三件事，真正是opencode自身的bug反而很少。

6.3 模型超时或响应慢

如果你觉得某个模型时快时慢，先确认它是不是官方直连。另一个常见原因是把供应商的免费或低价模型当主力用，高峰期排队严重。我的对策：主力模型选延迟稳定的，重试任务用廉价模型，批量任务用本地模型，三层分工。

6.4 Playwright报browser not found

opencode内置了Playwright驱动，但浏览器内核需要单独装：

npx playwright install chromium

如果项目里已经有Playwright依赖，尽量让opencode复用项目里的浏览器实例，避免装了两套内核互相冲突。

6.5 VSCode插件找不到opencode

原因基本是PATH没生效，处理方式见5.1，在插件设置里指定绝对路径。macOS特别注意，从Finder启动的应用不继承shell的PATH。

6.6 Skills不生效

先检查文件名和目录名，必须是SKILL.md，放错目录不会被加载。其次看技能描述里的trigger是否清晰，AI是靠description匹配技能的，描述写得太模糊，它大概率不会主动用。最后，改完技能文件要新开会话，当前会话里它读不到最新文件。

最后分享一个我自己的经验：opencode更新节奏很快，GitHub上几乎每周都有新版本，遇到行为异常，先升个级看看，很多你在issue里看到的问题其实已经修了。工具是工具，重点是它能不能融入你的工作流。我现在的主力组合是opencode终端版加本地模型兜底，编辑器插件只在看diff时用，整个链路跑顺之后，效率提升确实很明显。你如果也打算从Claude Code切过来，我的建议是不要急着删旧工具，两个并行用一周，哪个顺手留哪个。