企业官网建设流程全解析

“opencode”最近在终端 AI 编程工具圈子里出镜率非常高，我也是从 Claude Code 和 Codex CLI 双持，到最近把 opencode 加进工作流，再用了一段时间之后才敢写这篇东西。如果你跟我一样，装了不止一个 AI 编程助手，又经常在“这个任务交给谁”上犹豫半天，那这篇文章应该对你有用。我会把安装、模型配置、项目接入、Skills 实战、IDE 联动和典型报错排查全走一遍，尽量按我实际操作的顺序讲，不整虚的。

1. opencode 是谁家的，它到底解决什么问题

1.1 做 Serverless 起家的团队，为什么跑来做 AI Agent

opencode 来自 SST 团队（就是做 serverless-stack 框架那帮人）。早几年关注过云原生开发的人应该对这个团队有印象，他们做的 SST 框架在 AWS Lambda 生态里口碑一直不错。后来 AI 编程工具起来了，SST 团队转头做了 opencode，本质上还是那句话：开发者的工作流变了，基础设施提供商也得跟着变。

opencode 是开源项目，核心特点是“模型无关”。它不是某一家模型厂商的专用客户端，而是一个跑在终端里的 AI 编程 Agent。你可以把它理解成一个能看懂你项目、能改代码、能跑命令、能自己看报错再迭代的“命令行工程师”。它支持 Anthropic 的 Claude、OpenAI 的 GPT 系列、Google 的 Gemini，也支持各种 OpenAI 兼容接口，以及本地跑的 Ollama 模型。

这个定位很关键。Claude Code 和 Codex CLI 分别绑死自家模型，而 opencode 把“模型”和“Agent 能力”解耦了。你想用哪家模型，或者今天这家太贵想换那家，在 opencode 里改配置就行，不必换工具。

1.2 我理解的 opencode 和同类工具的差异

从实际体验来看，opencode 跟 Claude Code、Codex CLI 之间的差别主要有几点：

第一，界面信息密度更高。opencode 的 TUI（终端界面）做得很用心，文件变更列表、diff 预览、任务状态在同一个屏幕里展示得很清楚。以前我用 Claude Code 跑一个多文件重构，靠滚动日志去猜它改到哪了；用 opencode 可以一眼看到当前在第几步，哪些文件被修改，哪些命令在等待确认。

第二，自动化程度可调。opencode 有自动模式和手动确认模式。自动模式适合让它去跑测试、修简单报错；手动确认模式适合改代码这种高风险操作，每一步 diff 都要我点头才落盘。这个控制粒度对我来说很重要，尤其是接手不熟悉的项目时。

第三，插件和 Skills 体系。opencode 支持安装插件，也支持把一套“技能说明书”交给 Agent，让它按固定流程做事。后面我会单独写一节，这部分是 opencode 拉开差距的地方。

简单列个对比，方便按需选择：

这不是说 opencode 全面吊打谁，而是说它的定位不同：它是一个“模型中立”的 Agent 底座，适合愿意花点时间折腾配置、希望一个工具吃所有模型的人。

2. 装机、配模型、跑通第一个修复任务

2.1 安装方式与 Windows 上最经典的报错

opencode 的安装不算复杂，但不同平台的坑不一样。我目前用过三种方式：

官方脚本安装（macOS/Linux）：

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

Homebrew 安装（macOS）：

brew install sst/tap/opencode

Windows 上我建议直接去 GitHub Releases 下载对应平台的二进制包，解压到一个固定目录，比如C:\tools\opencode，然后把该目录加进系统 PATH。为什么我不推荐在 Windows 上跑 npm 方式？因为 npm 全局路径在不同终端工具里刷新时机不一致，经常出现装完了还是提示命令找不到。

说到这必须提那个出现频率非常高的报错：

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

这个报错原因就两个。一是安装后没开新终端，PATH 环境变量没刷新；二是安装目录真的不在 PATH 里。解决办法很简单：新开一个 PowerShell 窗口，执行：

Get-Command opencode

如果还是找不到，说明 PATH 没配上。手动把安装目录加进用户 PATH，然后重启终端。这个报错本身不复杂，但因为它出现的频率太高，我怀疑很多人根本没注意过安装脚本最后一行有没有输出安装路径。

2.2 模型配置：官方 key、兼容端点、本地模型都怎么接

装完 opencode，先别急着跑。它默认没有绑定任何模型，你得先告诉它用哪个模型干活。opencode 的配置文件在用户目录下的.opencode目录里，新版一般是opencode.json，老版本可能是config.toml，具体看版本和文档。

最简单的方式是直接设置环境变量。比如用 Anthropic 官方 API，就在终端里导出 key：

export ANTHROPIC_API_KEY=sk-ant-xxxx

然后跑opencode，在模型选择里选 Claude 系列。如果你用的是 OpenAI 兼容接口，那就要在配置文件里加 provider。这类配置网上版本很多，我这里贴一个经过实际验证的通用结构：

{ "provider": { "my_compatible": { "npm": "@ai-sdk/openai-compatible", "name": "My Compatible Provider", "options": { "baseURL": "https://your-endpoint.example.com/v1", "apiKey": "sk-xxxx" }, "models": { "my-model-name": { "name": "My Model Display Name" } } } } }

这里要提醒一句：opencode 底层用的是 Vercel AI SDK 那套 provider 体系，所以第三方兼容服务的配置都是按这个 pattern 来的。但不同小版本的字段名可能略有出入，遇到识别不了的情况，用opencode --help或者直接打开交互界面里的/models命令看实际支持的字段。

如果你不想花钱，也不想把数据交到第三方中转服务，那我建议装一个 Ollama，把本地模型接进来。配置方法也类似，baseURL 指向本地端口即可。本地模型的速度和效果肯定不如大厂 API，但它有个好处：完全可控，没有欠费断供的问题。

2.3 第一个任务：让它修一个前端可见的 Bug

配置完模型，直接运行opencode进入终端界面。第一次进 TUI 会有几个引导项，选好模型之后就可以在输入框里描述任务。我建议第一个任务不要搞太复杂的，先拿一个真实且范围明确的问题试水。

比如我曾经接手一个 React 项目，登录页在某些分辨率下按钮溢出。我给的指令是：

复现登录页按钮溢出的问题。先读 package.json 确认有没有 Playwright， 没有就建议安装，然后写一个临时脚本在不同视口尺寸下截图，定位根因后修复。

opencode 会先读项目结构，再决定怎么验证，不是上来就改代码。我记得它先把npm run dev起起来，又检查了页面 CSS，最后发现是一个媒体查询写错了断点值。整个过程它自己跑命令、自己看结果，我只在命令行允许执行时点了确认。这个体验和 Claude Code 很像，但界面上的文件 diff 更直观，我能提前知道它准备动哪个文件。

改完之后，架构会给出一个“接受 diff”的入口。这一步不要无脑接受，尤其是刚接触 opencode 的时候，把每处上下文看一遍再按确认也不迟。一旦接受了它的修改，它会继续检查有没有新的报错。这种循环反馈模型就是 Agent 类工具的核心价值。

2.4 无头模式：让 opencode 进 CI

除开交互式 TUI，opencode 还支持无头模式。我经常在修完一个需求后，直接用无头模式做快速自查：

opencode run "跑一遍 go test ./...，失败的话逐个修复并重新跑，直到通过"

这种模式不启动界面，直接执行完任务退出，非常适合接到 shell 脚本或者 CI 流程里。热词里有人搜“opencode go 需要配合 ccswitch 等工具”，这里的 go 大概率就是指 Go 项目的场景。我实践下来的感受是：opencode 在 Go 项目里跑得尤其顺，因为go test、go vet这类命令的反馈非常结构化，Agent 容易根据报错自动迭代。

3. 让 opencode 接手老项目：规则文件、记忆与 ccswitch

3.1 AGENTS.md：把项目潜规则写清楚

任何一个 Agent 工具，换到一个新项目里都有一个“冷启动”过程。它不知道你的项目用什么命令跑测试、代码风格是什么、目录结构里哪些文件不能动。这时候规则文件就派上用场了。

opencode 和 Codex 这类工具都认AGENTS.md这个文件名。它本质上是给 Agent 读的 README，但比普通 README 更偏向操作指南。我的经验是，至少要在里面写四类信息：

• 项目怎么安装依赖、怎么跑本地环境
• 测试命令是什么，单测和 E2E 分别怎么跑
• 代码风格约束，比如“禁止直接修改 src/api 下的文件，必须先过接口层”
• 常见的“坑”，比如某些目录是自动生成的，改了也会被覆盖

举个例子，一个 Java/Maven 项目的AGENTS.md可以这样开头：

# AGENTS.md ## 构建与测试 - 构建使用 JDK 17，执行 `mvn -q compile` - 单测执行 `mvn -q test`，不要跳过测试 - 本地联调需要先启动 `docker-compose up -d` ## 代码约定 - 所有新增接口必须放在 `controller` 包，禁止直接暴露 repository - 实体类不允许直接作为 Controller 入参，必须用 DTO ... ## 注意事项 - `target/` 目录是构建产物，永远不要改里面的文件

写完这份文件，再让 opencode 接手任务时，它的猜测成本会大幅下降。很多用户觉得 opencode 某些任务表现蠢，多半是没给规则文件，让它在一个 10 万行代码的项目里瞎猜。

3.2 memory：跨会话记住你已经说过的约定

热词里“opencode memory”也上了榜。我理解这里的 memory 是指 opencode 自己维护的一套跨会话记忆机制，用来保存项目约定和决策记录。它和AGENTS.md的区别是：

• 规则文件是你主动写的，告诉它“这个项目要这样跑”
• memory 更像是 Agent 自己记录的备忘录，比如“上次已经排查过某个模块，根因在数据库索引，不要再怀疑业务代码”

这个机制在长时间维护同一个项目的场景下非常有价值。因为模型每次会话都是无状态的，如果没有记忆，它可能每次都在同一个坑里重新爬一遍。我自己的用法是，在关键任务结束后，手动把结论追加到项目里一个docs/agent-notes.md文件，然后在AGENTS.md里让 opencode 每次开始前先读这个文件。虽然不如内置 memory 那么全自动，但至少可控且不依赖具体版本实现。

3.3 ccswitch：多套模型配置集中管

如果你同时用 Claude Code、Codex CLI 和 opencode，那你一定会遇到配置混乱的问题：三个工具各有一套 key 和环境变量，换模型时要改三个地方。ccswitch 就是解决这个问题的，它能把各终端 AI 工具的 model 配置、API key 集中管理，按项目或任务一键切换。

我现在的做法是这样的：ccswitch 里存三套配置，分别是“日常 Claude 模型”“OpenAI 兼容测试模型”“本地 Ollama 省钱模式”。接到不同任务时，我切到对应配置，然后启动对应的 Agent 工具。比如日常改代码用 Claude，批量跑 RAG 任务的脚本用 OpenAI 兼容端点，简单补测试用本地模型。

说句实在话，ccswitch 这类工具并不复杂，它本质上就是帮你改配置文件。但有了它之后，我不用再惦记~/.claude/settings.json、~/.codex/config.toml和 opencode 配置文件各自在哪了，所有 key 在一处管。出错概率低了，心理负担也小了。

3.4 opencode 2.0 和桌面版带来的变化

热词里有“opencode 2.0”和“opencode desktop”。从我体验的版本轨迹看，2.0 系列最大的变化是稳定性和插件体系完善了。早期版本跑大型重构偶尔会超时，2.0 之后这类问题少了很多。桌面版则把 TUI 的体验搬到了独立应用里，适合不想在终端里折腾的人。

但我不太建议新手直接上桌面版。原因很简单：opencode 的核心优势是融入命令行工作流，比如配合 git diff、pipe 输出、CI 调用。桌面版虽然界面好看，但这些终端特性会被削弱。我的建议是：先用命令行版跑通核心流程，桌面版当作“查看任务进度”的辅助工具。

4. Skills 实战：给 opencode 装上 superpowers 式的技能库

4.1 Skills 不是提示词，是操作手册

热词里“opencode skills”和“opencode 安装 superpowers”占了很大权重。这里我得先澄清一个概念：Skills 不是一段精挑细选的 prompt，而是一套结构化的 Markdown 文档。每个 Skill 描述一个具体能力，比如“用 Playwright 复现前端 Bug”“审查 API 安全”“写 commit message”，里面写了触发条件、执行步骤、输出格式和完成标准。

为什么这种形式比 prompt 好？因为 prompt 是临时性的，你输入一次它就忘一次；而 Skill 是持久化的，Agent 可以先读 Skill 再照着执行，相当于给它一本带有 SOP 的工具手册。这在小红书技术博主和开源社区里很流行，因为网上有大量现成的 Skills 仓库可以直接搬。

superpowers 就是这么一套技能包，最初是给 Claude Code 用的，里面包含了很多工程实践，后来社区把它适配到了其他 Agent 上。opencode 安装 superpowers 的常见做法是，在项目或全局的 skills 目录里引入它，然后在规则文件里声明“遇到复杂任务时先加载 superpowers”。

4.2 引入开源配置资产：oh-my-claudecode 怎么迁移

还有人在搜“opencode oh-my-claudecode”。oh-my-claudecode 是一套针对 Claude Code 的配置和指令资产集，类比一下就是 zsh 里的 oh-my-zsh。它里面最有价值的是各种场景化的 instructions，比如“如何做技术方案评审”“如何写安全代码”。

迁移思路很直接：不要贪多，把里面适合自己项目的指令摘出来，改写成 opencode 的规则文件格式。我见过最有效的迁移方式是，只保留那些能准确描述“完成标准”的指令，比如：

• 改完代码必须跑mvn -q test且不能跳过失败测试
• 涉及数据库变更必须先检查是否有 SQL migration 文件
• 每次修改必须说明影响范围

这些内容与其说是给模型看的“咒语”，不如说是工程规范。Agent 工具只是把你的团队规范执行得更彻底，所以配置资产的价值不在于多，而在于贴合你的项目场景。

4.3 实战：写一个用 Playwright 查前端 Bug 的 Skill

拿我自己写的一个 Skill 举例。因为经常用 opencode 处理前端反馈，我给它写了一个专门做前端 Bug 复现的技能，长这样：

--- name: frontend-bug-check description: 用 Playwright 复现前端 Bug，定位根因并输出截图证据 --- # 使用场景 收到前端 Bug 反馈时使用。先复现，再修复，最后验证。 # 执行步骤 1. 查看项目 package.json，确认是否安装了 Playwright 2. 如果没有，执行 `npm i -D @playwright/test` 并安装对应浏览器 3. 读取项目现有测试配置，了解 baseURL 和已有 test fixture 4. 根据 Bug 描述写一个最小复现用例，覆盖目标页面和交互路径 5. 运行测试并截图，记录控制台报错信息 6. 根据截图和报错定位嫌疑代码，修改后重新跑同一条用例 7. 通过后把测试保留下来，作为回归用例 # 完成标准 - 测试能在修复前稳定复现 Bug - 修复后同一条测试通过 - 有截图或控制台日志作为证据

这个 Skill 的用法是，我遇到了前端 Bug，直接跟 opencode 说“按 frontend-bug-check 流程处理，页面是 xxx，现象是 yyy”。它就会按照步骤，先确认环境、再写复现用例、再去定位和修复。

很多人觉得 Playwright 这类工具贵在编写成本，但把流程固化成 Skill 后，opencode 每次都会走同一套路径，不会临时发挥跳过某一步。这也是为什么我强烈建议：与其整天换模型，不如把团队踩过的坑写成 Skills 沉淀下来，这才是 Agent 工具的长期价值。

4.4 什么场景下不要用 Skills

Skills 也不是万能的。我踩过的教训是，不要把过于粗略的流程做成 Skill，比如“写一个高质量函数”这种纯主观描述，Agent 即使照做，输出质量也很难评估。

Skill 适合的是那些有明确完成标准的流程：构建、测试、部署检查、Bug 复现、代码扫描。判断标准很简单：如果你的流程每个步骤都有“通过/失败”的客观结果，就可以做成 Skill；如果靠感觉判断，那就别做。

5. 在 VS Code、JetBrains 和桌面端继续干活

5.1 VS Code 插件：把终端 Agent 嵌入编辑器

热词里有“opencode vscode 插件”，说明很多人希望在编辑器里直接使用，而不是频繁切到终端。VS Code 插件装好后，左侧会多一个图标，点开就能看到会话面板，可以选中一段代码作为上下文，直接问 opencode “这段代码的问题在哪里”或者“帮我把这个函数重构成 async”。

我的实际体验是，VS Code 插件适合做“文件级”的操作，比如重构单个组件、补类型、写单测。它跟 TUI 之间有一个很好的互补：TUI 适合跨多文件的大任务，插件适合改手头这一个文件。我一般先插一句话给它定位问题，看到它准备动文件时，再切到 TUI 里放权让它跑全局验证。

5.2 JetBrains 插件与 Maven 项目的联动

JetBrains 系（IDEA/GoLand/PyCharm）也有 opencode 插件。Java/Maven 项目里它更有用，因为 Java 项目的上下文信息比前端多：依赖管理器、模块划分、配置文件一堆。直接在 IDEA 里用 opencode，它能读取当前打开的文件内容和项目路径，省去在终端里切换目录的时间。

我之前在一台 Windows 开发机上用 IDEA 配 Maven 项目，当时遇到的问题是 opencode 给出的命令里用了mvnw，但项目里没有 wrapper，导致一直报错。后来我在AGENTS.md里加了“本项目使用全局 mvn，不使用 mvnw”，它就不再踩这个坑了。这再次说明规则文件的重要性，IDE 插件的表现也依赖它。

5.3 桌面版：给不喜欢终端的队友用的

opencode 桌面版把 TUI 做成了独立窗口，对习惯了图形界面的人来说友好很多。我在小团队里做过测试，不熟悉命令行的队友用桌面版上手速度明显更快，因为不需要记环境变量和配置文件位置。

但桌面版目前还是和 Terminal 版共用同一套配置，也就是说你在终端里配好的模型、skills，桌面版也能读到。不要把它当成另一套工具，它是同一个 opencode 的另一个外壳。

6. 故障排查实录：PowerShell 报错与 unexpected server error

6.1 PowerShell 不识别 opencode：PATH 的老问题

这个在前面提过，但它的排查链路值得完整走一遍，因为很多 Windows 用户卡在这里。

现象：

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

我的排查顺序：

1. 打开新 PowerShell 窗口，看Get-Command opencode是否返回结果。如果找不到，说明安装目录不在 PATH。
2. 执行echo $env:Path，检查里面有没有包含 opencode 的安装路径。
3. 如果安装时用的是官方脚本，脚本最后通常会输出安装路径，比如~/.opencode/bin或%USERPROFILE%\.opencode\bin。把这个路径加进用户环境变量 PATH。
4. 完全关闭所有终端窗口（不是开新 Tab，是彻底退出），重新打开。

这个坑最常见的原因其实是，安装成功了，但用户没重启终端就运行，于是被 PATH 刷新时机坑了。

6.2 unexpected server error：先看日志再动配置

另一个高频报错是这个：

opencode error: unexpected server error. check server logs

这个报错第一次出现时，我花了很长时间去搜配置，后来才意识到它根本不是配置语法问题，而是服务端（模型 API 或 opencode 本地服务）没正常返回。

它的排查链路是这样的：

1. 确认 API key 没写错。去 opencode 的配置文件或者环境变量里核对 key 是否带空格、是否完整。
2. 确认模型名称和访问地址匹配。很多人直接把 provider 的 baseURL 写成https://api.example.com而不是https://api.example.com/v1，导致请求路径少了一段，报 server error。
3. 用 curl 直接调一下上游接口，验证是不是模型服务本身的问题。比如 OpenAI 兼容接口可以执行：

curl -s https://your-endpoint.example.com/v1/models \ -H "Authorization: Bearer $API_KEY"

如果这一步返回 401 或 403，说明 key 或模型权限有问题，不是 opencode 的问题。 4. 如果 curl 正常，再看 opencode 自己的日志。日志一般在用户目录的.opencode/logs下，具体文件名和格式会随版本变化，但里面会详细记录每次请求的响应状态码和错误信息。没有的话，可以试试用 debug 模式运行 opencode，让日志直接打到前台。 5. 最后，把模型切换成一个已知可用的小模型，比如某些免费测试模型，用来判断是“所有模型都报错”还是“只有当前模型报错”。

我遇到的 case 中，绝大多数都是因为免费/第三方模型通道不稳定。那些挂在公开社区里的 hy3-free 之类的免费通道，本质上都是有人用中转服务把多家模型拼在一起免费或低价开放。这种通道本身就有波动，今天能用、明天 401、后天整个服务下线，都是正常现象。不应该在核心任务里使用这类通道，更不要把 opencode 的稳定性寄托在它们上面。

如果确实想低成本使用，优先考虑本地模型或者官方 API 的免费额度。至少出了问题你知道去哪里查账单和状态页，而不是去群里问“hy3-free 是不是下线了”。

6.3 其他值得注意的坑

我还在社区里看到一些零碎报错，比如 TUI 偶尔卡死、diff 无法接受等。这类问题大多出在版本过旧，opencode 迭代很快，升级到最新版很多问题会自动消失。如果你用的是插件市场里的旧版本，建议先执行版本更新再排查其他原因。

7. 选型建议：opencode、codex、claude code、pi 怎么选

7.1 我实测后的分工

热词里有个问题是“opencode codex pi 哪个 agent 好用”，还有个对比是“codex claude code”。这类问题没有一个标准答案，因为不同工具的任务能力差距在缩小，真正的差异在“场景适配”。

我目前的分工是：

• 日常在主项目里改代码、重构、调试：用 opencode。因为它模型中立，同一个 opencode 配置里，我可以自由切换 Claude 和 OpenAI 兼容模型，不会被 Android 绑死。
• 写前端交互复杂的页面：用 Claude Code 更顺手。Claude 对前端代码的理解能力确实有优势，而且 Claude Code 的长上下文保持得不错。
• 跑一些和 OpenAI 生态强相关的脚本、把任务丢给后台执行：用 Codex CLI。它的任务模式和云端集成在某些场景下比本地 Agent 更省心。
• pi 我也简单体验过，定位更像轻量级 Agent，适合快速的小任务。但它目前的生态和配置资产不如前几个丰富。

“哪个好用”本质上是“哪个更适合你现在的项目”。如果项目里已经沉淀了AGENTS.md，那 opencode 的优势就很大；如果你是 Claude 重度用户且不想折腾配置，Claude Code 更顺；如果你主要在 OpenAI API 和云端任务里打转，Codex CLI 更合适。

7.2 我的默认组合

我可以透露一下目前在团队里推广的组合：代码库规则文件统一用AGENTS.md；默认 Agent 是 opencode；重度前端交互任务临时切到 Claude Code；批量任务和 CI 集成走 opencode 无头模式。ccswitch 管所有配置。

这个组合的好处是，知识和经验沉淀在规则文件里，不绑定具体模型。就算某天把模型从 Claude 换成 GPT，Agent 的行为依然稳定，因为项目规则是显式的，不依赖模型的“灵性”。

7.3 不建议的情况

如果你不想维护配置文件，也不想理解 AGENTS.md 这类概念，那 opencode 可能不适合你。它的好处恰恰来自可配置性和生态，而这些都需要你投入时间去搭建。刚接触 AI 编程工具的人，从 Claude Code 或 Codex CLI 开始会更平滑。

如果你愿意在规则文件上花一点功夫，那 opencode 会给你一个很扎实的回报：只要规则写得好，换模型、换项目都能快速进入状态。

我个人在实际使用中还有一个心得：配置不要在第一天就做到极致，先跑通一个真实任务，再逐步往AGENTS.md里补规则。规则文件不是一开始就写出来的，是踩了坑之后再沉淀出来的。把每个“它怎么又改错”的瞬间，都转化成一两句规则写进文件里，过一个月你会发现，这个工具的工程化能力远超你最初的预期。