企业官网建设流程全解析

我是在一个加班到晚上十一点的周五晚上第一次装上 opencode 的。当时项目里堆了十几个 issue，传统的工作流已经让我提不起劲：打开编辑器，翻代码，猜上下文，改完再跑测试，发现问题又得回头改。我真正想要的，是一个能在终端里听我说话、自己翻代码、自己跑命令、把改动直接落到文件里的工具，而不是又一个只会生成代码片段的聊天框。

opencode 就是冲着这个需求来的。它是做 serverless 框架 SST 的那个团队（Anomaly 公司）开源的一款 AI 编码智能体，定位很明确：终端优先、配置本地化、支持多模型、能真正读写文件并执行命令。到 2.0 版本之后，又补上了桌面版、VSCode 插件、JetBrains 插件，生态一下子完整了不少。这两天在各个技术群里，关于它的讨论热度明显在涨，问安装、问配置、问和 Codex CLI / Claude Code 对比的声音特别多。

这篇文章不是官方文档的翻译，而是我这两个月实际用下来的经验整理：从安装报错怎么排查，到模型怎么配才省钱，再到 Skills、Memory、Playwright 这些进阶玩法和真实踩坑记录。如果你正准备上手 opencode，或者已经装了但用不顺手，这篇应该能帮你省下不少折腾时间。

1. opencode 到底是什么：一个不甘心只做“聊天助手”的开源编码智能体

1.1 出身与定位：SST 团队为什么做这个

很多人第一次听到 opencode，第一反应是"SST 不是做无服务器框架的吗，怎么跑来做 AI 工具了"。没错，正是那个团队。可能正因为常年做开发者基础设施，他们对开发者工作流的理解非常实际：AI 编程工具不应该是一个网页对话框，而应该待在你本来就在的地方——终端和编辑器里。

opencode 和 Claude Code、Codex CLI 是同一类东西，业内管这类工具叫 terminal AI coding agent。它们和普通 AI 编程助手的核心区别不在"聊天能力"，而在"动手能力"：

• 能递归读取项目文件，理解整个代码库的结构和上下文
• 能直接创建、修改文件，而不是只给你一段代码让你自己粘贴
• 能执行 shell 命令，跑测试、跑构建、看报错
• 能基于命令输出自我修正，多轮迭代直到任务完成

opencode 开源是它很大的一个卖点。代码全部公开，配置存在本地，不强制绑定某一家模型厂商。你可以把 Anthropic、OpenAI、Google 的模型，甚至本地用 Ollama 跑的模型都配置进去，同一个工具随时切换。这一点对我这种喜欢"东用一下西用一下"的人来说非常友好。

1.2 它和传统 AI 编程工具有什么本质区别

如果你用过 Copilot 时代的补全工具，再用 opencode，体感是完全不同的。补全工具是"你写，它猜"，智能体是"你下达目标，它自己干"。举个我真实经历的例子：

有次我接了个活，要把项目里所有硬编码的错误提示文案抽到一个 i18n 文件里。以前这种活我要手动开十几个文件，一行一行找出来改。用 opencode，我只说了一句"把 src 下所有硬编码的中文错误提示抽到 locales/zh-CN.ts，更新所有引用，跑一遍测试确认没破"。它自己先列了改动清单，然后逐个文件改，再跑 yarn test，中途发现有个测试用例断言的是旧文案，又自己改掉，最后把结果汇报给我。整个过程我基本只在旁边看，偶尔喊停。

这种"目标驱动"的工作方式，把 AI 从配角变成了真正干活的角色。它不再是你问一句它答一句，而是你交代一个目标，它自己规划路径、执行、验证、交付。

1.3 适合谁，不适合谁

先说明白，opencode 不是给所有人的。

适合的人：有一定命令行基础、日常用终端或者 IDE 重度开发的程序员；想要一个能真正"干活"、而不是只会"建议"的 AI 工具的人；做全栈或者前端、经常需要改一堆相关文件的场景；喜欢自己掌控模型选择、不想被厂商锁定的人。

不适合的人：完全没接触过命令行的新手，可能先从编辑器里的 AI 插件上手更舒服；对"AI 直接改代码"这件事接受度低、必须自己逐行手敲的人；以及希望工具开箱即用、不想花十分钟看配置文档的人。opencode 的安装和配置已经不算复杂，但它毕竟是个面向开发者的开源工具，默认假设你有点折腾能力。

2. 装好 opencode：从下载、PATH 到“cmdlet 无法识别”的解决思路

2.1 三种安装方式怎么选

我接触到的 opencode 安装方式主要有三种：npm 安装、Go 安装、桌面版安装。三种我都试过，各有适用场景。

第一种，npm 全局安装。如果你平时用 Node.js 开发，这是最顺的一条路：

npm install -g opencode-ai

装完直接opencode就能进交互界面。我最早就是这条路装的，前后不到一分钟。需要留意的是，npm 包名可能会随版本调整，安装前最好去官方仓库确认一下当前的名字，别凭记忆装错包。

第二种，Go 安装。如果你机器上有 Go 环境，也可以用：

go install github.com/sst/opencode@latest

装完的可执行文件在$(go env GOPATH)/bin下。这种方式适合本来就在 Go 生态里的人，或者 npm 这边出了奇怪的权限问题作为备选。网上有些人说"opencode go 需要配合 cc switch 等工具来管理模型配置"，其实 go 安装和 npm 安装得到的核心程序是一样的，区别只是装到哪个目录、由谁管理版本，后面配模型时统一走配置文件即可。

第三种，桌面版。opencode 官方提供了桌面客户端，有图形界面，适合不想碰终端、或者想把 opencode 当作一个独立 App 来用的人。桌面版内置了终端面板，本质上还是同一套引擎，外面套了一层壳。我个人的建议是：如果你主力开发在终端或 IDE 里，用前两种就够；桌面版更像是"独立工具党"的选择。

2.2 Windows 下最常见的“无法识别”报错排查

很多人在 Windows 上装完 opencode，兴冲冲打开 PowerShell 敲opencode，结果看到这么一行红字：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。

我第一次看到这个报错也愣了一下，以为安装失败了。后来排查多了才明白，这条报错的本质是：系统在 PATH 环境变量列出的所有目录里，都没找到 opencode 这个可执行文件。也就是说，程序可能装上了，但系统"看不见"它。

常见原因有这么几个，按概率排序：

1. npm 全局安装目录不在 PATH 里。这是最普遍的原因。npm 全局包的安装目录默认不是 Windows 系统 PATH 的一部分，你要手动把它加进去。
2. 安装过程失败或者没装完。比如权限不足，npm 静默跳过了一些写入。这种重新用管理员权限装一次就好。
3. 装完后没重开终端。PATH 是 shell 启动时加载的，你装完立刻敲命令，当前这个 shell 还是旧环境。
4. 用了 nvm、fnm 这类 Node 版本管理工具。PATH 是由版本管理工具动态注入的，不同 shell 加载的路径可能不一致。

排查的步骤，我建议按这个顺序来：

node -v npm -v npm prefix -g npm ls -g --depth=0

第一条和第二条确认 Node 环境本身没问题；第三条确认 npm 全局包装到了哪个目录；第四条确认 opencode 确实在全局包里。如果npm ls里能看到 opencode，说明装成功了，纯粹是 PATH 问题。

接下来把 npm 全局目录加进用户 PATH。PowerShell 里可以直接执行：

setx PATH "$env:APPDATA\npm;%PATH%"

setx会写进用户环境变量，改完一定要新开一个终端窗口再试。如果你不想改全局 PATH，临时方案是直接用完整路径调用，$env:APPDATA\npm\opencode.exe，但这个只能救急，长期用还是改 PATH 省心。

2.3 验证安装与目录结构

装好并解决了 PATH 问题后，先跑一下版本号确认安装完整：

opencode --version

能正常输出版本号，就说明核心程序没问题。opencode 的配置和数据默认放在用户目录下，Linux/macOS 是~/.config/opencode/，Windows 是%USERPROFILE%\.config\opencode\，里面有全局配置文件、日志等；每个项目的配置则放在项目根目录的opencode.json或.opencode/目录里。熟悉这个目录结构挺重要，后面改模型配置、加 Skills 都要往这里放东西。

建议第一次启动前先确认自己有可用的模型 API Key，不然进去会卡在选择模型的环节。第一次真正跑起来的体验很重要，别让配置把你劝退了。

3. 模型配置是重中之重：免费模型、多 Provider 与 CC Switch 协同

3.1 先搞懂 opencode 的模型路由逻辑

opencode 的模型配置思路很清晰：它本身不生产模型，只负责把请求路由到你配置好的模型服务上。在配置文件里声明 provider（模型提供商），再指定默认用哪个模型的哪个版本。

全局配置文件位于~/.config/opencode/opencode.json，项目级配置文件放在项目根目录，支持opencode.json。一个典型的全局配置长这样：

{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4-5", "provider": { "openai": { "api_key": "{env:OPENAI_API_KEY}", "models": ["gpt-4o", "gpt-4o-mini"] }, "ollama": { "models": ["qwen2.5-coder:14b"] } } }

这里有个关键点：api_key可以用{env:变量名}的形式引用环境变量，我强烈建议你这么做，而不是把 Key 明文写进配置文件。一个是安全问题，另一个是配置文件可能会被提交到 Git 仓库，Key 一旦上去就收不回来了。我用了个笨办法——把配置模板提交到仓库，真实 Key 只存在本地环境变量里，这样换机器也不怕丢。

模型名的格式通常是provider/model，因为同一个提供商下面可能有多个模型版本，配置时把你要用的都列进models数组，运行时可以用快捷键切换，非常方便。

3.2 免费模型怎么接：本地模型和免费额度

"opencode 免费模型"是很多人搜得最多的关键词，也确实是最容易踩坑的地方。先说结论：opencode 本身是免费的，但模型服务是要花钱的——除非你用免费额度或者本地模型。

第一种方案是本地模型，用 Ollama 跑开源模型。装好 Ollama 后拉一个代码模型下来：

ollama pull qwen2.5-coder:14b

然后在配置里加上对应的 provider，就能在 opencode 里选到本地模型。好处是完全免费、数据不出本机、没有限流；坏处是效果和大厂闭源模型有差距，尤其复杂代码重构这种任务，14B 模型经常力不从心。我的经验是：本地模型适合做小改动、写测试、改文案这类轻任务，重活还是交给云端模型。

第二种方案是各家云厂商的免费额度。OpenAI、Google、Anthropic 以及一些模型服务平台都会给新用户一定量的免费调用额度，把对应的 API Key 配进去就能用。这种方案的优点是模型能力强，缺点是额度有限，用完了就得付费或者换一家。免费额度通常有有效期和速率限制，别拿来做自动化流水线。

第三种方案是社区维护的免费模型端点。这类端点确实存在过，网上也一直有讨论，比如最近就有人在问某个免费端点是不是下线了。我的态度很明确：社区免费端点的稳定性没法保证，今天能用明天可能就挂了，而且 Key 和流量都要经过第三方，敏感项目千万别用。玩玩可以，干正事强烈不建议。

3.3 用 CC Switch 管理多套配置

当你同时用 opencode、Claude Code、Codex CLI 几个工具，每个工具又要配置不同的模型和 Key 时，配置管理就开始变得烦人。每个工具一套配置文件，换模型要开好几个文件去改，很容易改出问题。

CC Switch 解决的就是这个问题。它是一个用来管理多套模型配置的图形化小工具，可以把你常用的配置组合（模型名、接口地址、API Key）存成一个个配置档，然后在不同配置档之间一键切换。它支持的配置档可以导出给 opencode、Claude Code、Codex 等多个工具使用，相当于给所有 AI 编程工具做了一个统一的"配置遥控器"。

我现在的用法是：在 CC Switch 里存三套配置档，一套用 Anthropic 的模型，一套用 OpenAI 的模型，一套用某个开源模型的商业托管版本。接不同项目时一键切过去，opencode 那边读到的配置就变了。省去了每次都要打开 JSON 文件手动改 Key 和模型名的麻烦。

不过要注意，CC Switch 这类工具本质上是替你写配置文件，它改的是 opencode 的配置文件内容。所以你还是得理解前面那个 JSON 的结构，不然切换出问题的时候会一脸懵。工具负责效率，原理负责兜底。

3.4 配置文件里的几个常见坑

我配置过程中踩过的坑，挑三个典型的说。

第一个坑是环境变量引用格式不对。{env:OPENAI_API_KEY}这套语法，有的版本支持，有的地方要求直接写$OPENAI_API_KEY，如果你照着老教程配完发现 Key 没被识别，先检查是不是格式问题。判断方法很简单：在 opencode 里跑一个简单请求，看日志里有没有报鉴权失败。

第二个坑是 models 数组和默认 model 不一致。你声明了 provider，但全局model字段写了一个 provider 里不存在的模型，启动时就会报错或者说"模型找不到"。改配置后一定要确认两边的模型 ID 拼写一致，别少个后缀多个横杠。

第三个坑是项目管理器和模型 provider 的命名冲突。你看网上教程的时候会发现，provider 的名字在不同版本里可能有差异，比如 Ollama 接口遵循 OpenAI 兼容格式，有的人就配成了 openai provider 的 custom baseURL，有的人配成独立的 ollama provider。两种思路都有人用，但混着来容易乱。我的建议是：本地模型用独立的 provider 配置，云厂商模型用官方 provider，逻辑清楚，排查也容易。

4. 建会话、下命令、看智能体干活：opencode 的核心使用逻辑

4.1 终端界面与会话基本操作

装好配好后，在项目目录里敲opencode，会进入一个交互式 TUI 界面。顶部是输入框，中间是会话内容区，底部有快捷键提示。整个界面是终端原生的，不依赖浏览器，SSH 到服务器上也能用，这点很对得起"终端优先"的定位。

基本操作逻辑和大多数终端聊天工具类似：输入自然语言指令，回车发送，AI 开始处理。会话历史会保存在本地，下次opencode --continue可以接续上次的对话继续干活，不用重新交代上下文。这是个很容易被忽略但实际很重要的功能——AI 编程往往需要多轮迭代，断一次会话从头再来非常让人崩溃。

在会话中你可以临时切换模型。我一般默认用能力强的大模型做规划，中途遇到简单机械的改动，切换到快一点、便宜一点的模型，能让成本降不少。具体快捷键不同版本略有差异，进去之后按?看帮助就懂了。

4.2 Agent 的工作循环：从计划到执行

很多第一次用 opencode 的人会困惑：它到底是怎么"干活"的？

核心是一个循环：解析任务 → 制定计划 → 调用工具执行 → 观察结果 → 调整计划 → 再执行，直到任务完成或者被你喊停。opencode 内置了几类关键工具：

• 文件工具：读取文件、写入文件、列目录，这是它改代码的基础
• 命令工具：在项目里执行 shell 命令，比如npm test、git diff
• 搜索工具：在代码库里按语义或正则搜索，定位相关代码
• Web 工具：抓取网页、查文档，通常用于解决依赖报错或查阅 API
• 浏览器工具：可以调用 Playwright 操作浏览器，用来测前端页面（后面细说）

每次它要执行一个操作时，界面上会显示意图和结果。你可以随时打断，也可以让它继续。我建议在前几次使用时不要全程当甩手掌柜，而是观察它的计划是否合理。比如让它改一个问题时，如果它打算动一个明显不相干的文件，这时候打断它还来得及，等它改错了再回来解释就麻烦了。

4.3 让 opencode 接手开发项目的正确打开方式

"opencode 接手开发项目"是个很诱人的说法，但千万不能一上来就丢给它一个"把这个项目的功能做完"这种巨型指令。我的经验是，把它当成一个能力很强但需要明确边界的新同事：任务颗粒度要合适，期望目标要清晰，验收标准要提前说。

一个比较科学的下指令框架是：背景 + 目标 + 约束 + 验证方式。举个例子，不要说"把这个页面的样式改好看点"，而是说：

"登录页的按钮在移动端被键盘顶起来了，固定底部栏盖住了输入框。请修复这个布局问题，保持现在的设计风格不变，只改相关组件的样式文件。改完后在本地跑一遍构建，确认没有报错。"

有背景（什么问题）、有目标（修复布局）、有约束（不动设计）、有验证（跑构建）。这样 AI 能快速定位范围，不会跑去重构你整个项目的 CSS。

还有一个技巧：让 opencode 在大动作前先输出计划，确认后再执行。大多数智能体工具都有 plan 模式或类似功能，opencode 也支持先规划再动手。对付十几个文件以上的重构任务，这个步骤能救你很多次。

4.4 几个我每天都在用的命令和技巧

除了自然语言对话，opencode 还支持一些快捷操作，我挑几个常用的：

• opencode：在项目目录启动，进入交互界面
• opencode --continue：接续上次会话
• /init：让 opencode 分析项目结构并生成一份项目说明文件（AGENTS.md），相当于给它自己建立上下文手册
• /help：查看可用命令和快捷键
• 会话中输入!开头可以直接执行 shell 命令，不用退出界面

/init这个命令特别推荐。它生成的 AGENTS.md 里包含项目结构、技术栈、开发和测试命令等关键信息，后续每次会话 opencode 都会自动把这份文件当作背景知识加载。相当于你先花五分钟教它"咱们项目是怎么回事"，后面它干活的质量会有明显提升。这个文件和后面要说的 Memory 机制配合起来，效果翻倍。

5. 把 opencode 搬进 IDE：VSCode 与 JetBrains 插件实战

5.1 VSCode 插件：侧边栏与选区上下文

命令行用久了，你会发现有些场景还是离不开 IDE：比如看某个函数的调用链、对比改动前后的 diff、直接在断点前调试。所以 opencode 官方做了 IDE 插件，让智能体能力可以直接在编辑器里用。

VSCode 插件装好之后，侧边栏会出现 opencode 面板，本质上是在编辑器里内嵌了一个会话窗口。它比终端多一个很实用的能力：可以直接把当前打开的文件、甚至选中的代码段作为上下文发送给 AI。比如你选中一段有问题的代码，让 opencode 分析这段代码的 Bug，它不需要先凭记忆找文件，上下文就在眼前，定位准确率会高很多。

另外一个我很常用的场景是配合 Git 工作。改完代码后，让 opencode 帮忙看一下git diff，生成 commit message，或者让它检查这次改动有没有遗漏的引用。因为这些操作都围绕当前工作区，IDE 插件的上下文感知比纯终端要自然。

安装 VSCode 插件之后，第一次使用会要求指定 opencode 可执行文件的路径。如果插件提示找不到 opencode，多半是前面 PATH 问题的余波——把 opencode 的完整路径填进插件设置里就能解决。

5.2 JetBrains IDEA 插件与 Maven 项目配置

JetBrains 全家桶的插件也是类似思路，在 IDEA、PyCharm 等产品的 Marketplace 里搜 opencode 就能安装。它同样支持侧边栏会话、选中代码发送上下文、查看 AI 对文件的改动。

不过 Java 项目这边有个特有的坑：opencode 要在项目里执行命令时，依赖你机器上已经配置好的构建工具，比如 Maven。如果你在终端里执行mvn是好的，但 opencode 在 IDEA 里执行mvn test却报错找不到命令，通常是因为 IDEA 内置终端的环境变量没有继承你用户配置的 PATH，尤其在你用 IDEA 自带的 JBR 时更容易出现。

解决办法有两个层面。一是确保 Maven 本身配置正确，包括M2_HOME环境变量、mvn在 PATH 中；二是让 opencode 知道的 JDK 路径，.mvn目录下可以配置toolchains.xml，或者直接在会话里告诉 opencode "用 jdk 17 跑 mvn test"。我实际用下来，大部分 Maven 相关报错都不是 opencode 的问题，而是环境变量没打通。先在系统终端里把mvn -v跑通，再去排查 opencode 那边就简单了。

5.3 终端和插件到底该用哪个

用了这两周，我的感受是：终端和 IDE 插件不是替代关系，而是各有分工。

终端适合"整个项目的活"——重构、批量改文件、跨多个模块的任务，让它自己有充分的自由度在代码库里搜索和修改。这类任务在终端里跑反而清爽，不会被编辑器内嵌面板限制。IDE 插件适合"当前文件附近的活"——分析一段代码、解释报错、生成单测、检查 git diff，这些任务强依赖你眼睛正在看的上下文，插件有天然优势。

我现在的习惯是：白天写代码时在 VSCode/IDEA 里开着插件面板处理局部问题；需要大范围改动时，开一个终端对着项目根目录跑 opencode 会话；晚上走之前看一眼所有待办，挑几个能委派的丢给 opencode，第二天早上看结果和汇报。

6. 再进一步：Skills、Memory 与 Playwright，把 opencode 调教成老手

6.1 Skills：给智能体装"技能包"

如果你用过 Claude Code 的 skills，对 opencode 的 Skills 机制会非常熟悉。它本质上是一组"预设能力和行为规范"的打包：把一个任务的专业流程、注意事项、处理模板写成结构化文档，放在指定目录下，当任务命中时，opencode 会自动加载这套指令来执行。

举个例子。我在团队里负责代码评审，以前每次 review PR 都要靠脑内清单：先看改动范围、再看核心逻辑、检查错误处理、最后看测试覆盖。后来我把这套流程写成了一个 Skill，命名为 code-review，内容包含：

• 评审顺序和重点检查项
• 常见反模式清单
• 输出格式要求（必须按"问题严重度 + 文件位置 + 修改建议"输出）

之后我让它 review 代码时，它会自动加载这个 Skill，按我定义的流程工作，输出质量比我临时口头描述稳定得多。对于一个团队来说，这相当于把资深工程师的经验沉淀成了可复用的资产。

创建 Skill 的流程不复杂：在~/.config/opencode/skills/下建一个目录，目录里放一个 SKILL.md 写说明和步骤，需要的话再加一些辅助脚本。具体格式建议看官方文档，版本更新比较快。社区里也有不少人分享现成的 Skills 集合，比如 Superpowers 这类项目把很多成熟的技能包做了整合，虽然最初可能为别的工具设计，但格式相通，思路可以迁移过来——装上后试一下，能用就留着，不行就当作参考自己改写。

6.2 Memory：让 opencode 记住项目规矩

Memory 机制解决的是"每次都要重新交代项目背景"的痛点。opencode 读取项目根目录的 AGENTS.md 作为项目级记忆，读取用户配置目录下的 AGENTS.md 作为个人级记忆，这些文件会在每次会话时自动作为系统背景注入，相当于给智能体一本"员工手册"。

我在项目 AGENTS.md 里一般会写这几类内容：

• 项目技术栈和目录结构，让它快速知道"什么东西在哪"
• 开发和测试命令，比如npm run dev、pnpm test
• 代码规范，比如"组件统一用函数式写法""错误文案必须走 i18n"
• 一些特殊约定，比如"不要改 generated 目录下的文件""数据库迁移必须经过确认"

这些内容写好了，opencode 的行为边界就清晰了，不会动不动踩到你的红线。我观察到一个规律：AGENTS.md 写得越具体，AI 的失误率越低。它就像给新同事的 onboarding 文档，质量直接决定这个人干活靠不靠谱。

Memory 要和 Skills 配合使用：AGENTS.md 负责"记住规矩"，Skills 负责"知道怎么做"。一个是背景知识，一个是操作流程，合在一起才是完整的"老手状态"。

6.3 用 Playwright 复现和定位前端 Bug

前端项目的 Bug 是最难用"想"来定位的，光看代码往往看不出问题，必须跑起来看页面表现。opencode 支持通过 Playwright 调用浏览器来测试前端页面，这让它可以做"复现 Bug → 定位问题 → 修复 → 验证"的完整闭环。

我实际用下来的操作流程是这样的。先在会话里给它描述 Bug，比如"列表页点击筛选后，URL 参数变了但数据没刷新"。然后让它用 Playwright 打开本地开发服务器，访问对应页面，执行筛选操作，观察网络请求和页面状态。

它会把操作过程、页面截图、控制台报错原样带回来，然后基于这些信息定位代码问题。有一次它发现筛选条件变化后请求参数没带上最新的 state，顺着组件树找到了一个有闭包陷阱的 handler，自己修完又用 Playwright 跑了一遍同样的操作确认修复生效。我在旁边看着它从头到尾把前端 Bug 的完整链路走了一遍，说实话当时有点感慨，这就是以前一个中级前端工程师干的事。

用 Playwright 测前端有一个实用技巧：让 opencode 先写一个最小化的复现脚本，而不是直接让它全量跑你的 E2E 测试套件。最小化复现脚本跑得快、失败信息明确，定位效率高得多。等它确认修好了，再跑完整的测试套件做回归。

6.4 社区技能集：Superpowers 这类资源的接入思路

现在围绕这类智能体工具，社区里已经形成了一个生态，各种 Skills 集合层出不穷，Superpowers 就是其中很出名的一个。它的思路是把很多资深工程师的工作方法固化成一个个可加载的技能包，从"如何写设计文档"到"如何进行调试"都有现成的模板。

接入思路很简单：把技能包的内容下载下来，按 opencode 的 Skills 目录格式放好，然后在 AGENTS.md 里提示 opencode"遇到 XX 类任务时优先使用对应 Skill"。要注意的是，这类社区资源更新频率不一，有的技能包很久没维护了，里面的命令或格式可能已经过时。用的时候保持"参考不盲从"的心态，把优秀的部分吸收，过时的部分自己改写成适合自己的。

我的经验是，Skills 这东西，自己动手写的永远比抄来的管用。因为你自己最清楚项目的痛点和团队的规范。社区资源的意义是给你灵感，告诉你"原来还可以这样沉淀经验"，最终还是要落到自己项目的实际需求上。

7. 和 Codex CLI、Claude Code、Pi 同场竞技，我为什么还在用 opencode

7.1 四款智能体的横向对比

用了这么久，群里被问得最多的就是"opencode、Codex CLI、Claude Code、Pi 到底哪个好用"。这个问题其实没有标准答案，因为每款工具的侧重点和擅长领域不一样。我按自己了解的情况整理了一张对比表：

这张表只是我目前了解的大致情况，版本更新太快，细节可能随时变化。

7.2 各自的适用场景

选型不是选"最好的"，而是选"最匹配你工作流和偏好的"。我的观察是这样的：

Claude Code 的优势在于 Anthropic 模型的自然语言理解和长上下文处理能力强，写代码时"懂人话"的程度很高，很多复杂重构任务交给它沟通成本低。缺点是闭源，有一定技术栈绑定，而且官方模型价格不便宜。

Codex CLI 背靠 OpenAI 生态，如果你们公司已经重度使用 OpenAI 的 API，衔接会很顺畅。它和 GitHub、IDE 的联动做得不错，适合已经泡在 OpenAI 生态里的人。缺点是如果你平时用的是 Anthropic 或 Google 的模型，就不太合适。

Pi 的定位更轻量，界面和交互做得比较顺手，适合快速问答和小范围改代码。它给我的感觉是"日常辅助"强于"大型重构"，重度复杂的多文件任务表现相对普通。

opencode 在里面最突出的特点是开放和灵活。模型随便换，配置全在本地，开源意味着你可以自己改它，甚至接入内部系统。对于我这种"今天用这个模型，明天想试试那个模型"的开发者来说，它是唯一一个不逼我做选择的工具。

7.3 我的选型思路

我现在的搭配是：主力日常用 opencode，因为它多模型切换最自由，一个工具能覆盖我手头的所有项目；涉及特别复杂的架构设计讨论时，我会临时切到 Claude Code，因为它的对话理解能力确实强，适合"头脑风暴型"任务；Codex CLI 主要在我需要和 GitHub Actions、OpenAI 生态联动的场景下用。Pi 装过但用得少，主要是界面确实舒服，轻任务时会顺手用一下。

这里想多说一句：工具比较网上天天有，但每个项目的代码库结构、技术栈、团队习惯都不同，别人的使用体验只能当参考。最靠谱的做法是给自己半天时间，四个都装上，拿一个真实的中等难度任务各跑一遍，看哪个最顺手。工具是为你服务的，不是用来集邮的。

8. 实战踩坑记录与上手建议

8.1 我遇到过的几个典型错误

两个月用下来，我踩过的坑不算少，挑几个有代表性的列出来，希望你能绕开。

第一个是error: unexpected server error. check server logs。这个报错我见过好几次，第一次遇到以为 opencode 坏了，折腾了半天。后来发现大部分时候是模型服务端返回了异常，比如模型名称不存在、API Key 对应的模型权限不足、或者模型服务本身在限流。处理思路很直接：先在同一个终端里用curl之类的工具直接请求一次模型 API，看能不能通。如果直接请求也有问题，那是模型服务的事；如果直接请求正常而 opencode 报错，再去看配置里的模型名和 Key 是不是对的。

第二个是"改了配置文件不生效"。opencode 的配置有全局和项目两个层级，项目级配置会覆盖全局配置。有时候你明明改了全局配置里的模型，项目里跑起来还是旧的，是因为项目根目录的opencode.json里也写了一个模型，把全局的覆盖了。排查时先看当前项目有没有项目级配置文件，别在全局文件里反复折腾。

第三个是长会话越来越慢、效果变差。这是所有智能体工具的共性问题，上下文窗口再大也有限。当你发现它开始"忘事"或者理解偏移，正确的做法不是继续追问，而是开一个新会话，把关键背景重新交代一遍，最好让它先读一遍 AGENTS.md。很多情况下，"重启会话"比"努力挽回旧会话"高效得多。

8.2 新手上手的顺序建议

如果让我给一个完全没用过 opencode 的人规划学习路径，我会建议按这个顺序来：

第一步，先装好、把模型配通，跑一个最简单的任务，比如"帮我把 README 里的错别字改了"。确认它能正常读写文件、执行命令就行。

第二步，学会/init生成 AGENTS.md，并手动补充项目的关键信息。这一步决定了后续所有会话的上下文质量。

第三步，尝试一个中等规模的真实任务，比如"把某个模块的错误处理统一重构一下"。观察它的工作计划，学会在计划不合理时打断和纠正。

第四步，开始配置自己的 Skills，把你最常做的任务流程固化下来。同时维护 AGENTS.md 里的规则，让工具的"默认行为"越来越贴合你的习惯。

第五步，再探索 Playwright 这类进阶能力，让它具备"自己验证自己"的能力。

按这个顺序走，基本上一周内就能进入顺手的状态。

8.3 一点个人体会

最后说点不那么技术的话。我见过很多人用这类工具的心态是"让 AI 帮我把活干完"，然后发现质量不行又收回来自己干，来回几次就下结论说"AI 编程不靠谱"。但我自己的体会是，AI 编码智能体更像是一个需要管理的执行者，它的产出质量取决于你交代任务的质量，也取决于你有没有给它沉淀足够的项目上下文。

把 AGENTS.md 写好、把常用流程固化成 Skills、在关键节点人工审查，这几件事做好了，opencode 就是一个相当得力的队友。它不会取代你思考，但它能把那些重复的、搜索式的、机械的工作从你身上卸下来，让你把精力留在真正需要判断力的事务上。

在我现在的日常里，opencode 已经变成了和编辑器、终端并列的固定工作台之一。它不是完美到无可替代，但"开源、本地配置、多模型自由切换"这一点，恰好满足了我对工具的全部核心诉求。如果你也是那种喜欢掌控工具、而不是被工具绑架的人，它值得你花一个周末来试试。