企业官网建设流程全解析

最近社区里问opencode的人明显变多了，群里有人拿它和 Codex、Claude Code 对比，有人问它是不是哪家公司的商业产品，还有人卡在安装第一步就疯狂报错。我大概在一个多月前开始把它真正用进日常开发，从个人小项目到一个中等规模的前端仓库，前后跑了二十多天，整体体验可以用一句话概括：这可能是目前把“多模型通用性”和“工程执行力”平衡得最好的开源终端 Agent，但前提是你愿意花十分钟把配置搞清楚。

这篇文章不打算写成官方文档的翻译，而是把我自己从安装、配置、接模型，到用它接手工期项目、跑 Playwright 测前端 bug 的全过程复盘一遍，重点放在那些文档里不会写、但坑到过我的细节上。无论你是刚听说这个名字，还是已经装上但卡在某个报错里，都应该能从里面找到对应的解法。

1. 先搞清楚它到底是个什么东西：不是又一个聊天窗口

很多人第一次用 opencode 会下意识把它当成 ChatGPT 的终端版，这是一个方向性误解。它确实有交互式对话界面，但核心定位不是“聊天”，而是在你项目的真实文件系统里干活的 Agent。

1.1 它的核心工作方式

opencode 跑在终端里，启动后可以读取项目目录下的文件、创建和修改文件、执行 Shell 命令、运行测试、检查 Git 状态，甚至调用浏览器做自动化验证。它不像聊天机器人那样只能给你“建议代码”，而是会真刀真枪地把改动落到磁盘上，然后让你 review 这次改动。

这种设计带来的直接好处是：你在终端里说的话，它会当作任务去闭环处理。你说“帮我把这个函数的调用方全部找出来并统计调用次数”，它不是给你一段代码让你自己去跑，而是直接在项目里 grep、写脚本、跑完把结果整理给你。

它的能力来源可以拆成几层：

• 底层驱动是各家大模型，默认支持 Anthropic Claude、OpenAI、Google Gemini，也支持本地模型如 Ollama。
• 中间层是 opencode 自己实现的 Agent 循环，负责规划、调用工具、处理结果、决定下一步动作。
• 上层是你的自定义配置和 skills，用来告诉它你这个项目的约定和流程。

所以它本质上是一个“模型无关的执行框架”，而不是绑定在某一家模型上的专用工具。这也解释了为什么很多人拿它和 Claude Code 对比——两者长得像，但 philosophy 不一样。

1.2 与 Codex、Claude Code、Pi 的核心差异

我最近把几个主流终端 Agent 都轮着用了一遍，列个表方便你直接对照：

选哪个更多取决于你的习惯。如果你主力模型就是 Claude，且能接受生态绑定，Claude Code 依然是最深的选择；但如果你希望同一个工具能随时切换模型供应商，或者希望自己能把控整个调用链路，opencode 的优势明显更大。

2. 安装这关，坑比想象中多

opencode 的安装方式倒是很常规，官方提供了几种：curl脚本、npm 包、Homebrew。但我在 Windows 环境下实测，以及看着群里几位朋友踩坑，发现安装环节的问题其实是最多的。

2.1 官方安装方式速览

macOS / Linux 环境下最省事的是跑官方脚本：

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

npm 用户要注意包名不是opencode，而是opencode-ai：

npm install -g opencode-ai

Homebrew 用户：

brew install sst/tap/opencode

装完之后验证一下版本，这一步很重要，别跳：

opencode --version

如果你能看到版本号，说明核心程序已经装上，可以跳到配置章节。看不到的话，接着往下看。

2.2 Windows 下“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”完整排查链路

这个报错的热度非常高，基本是 Windows 新手最常撞上的墙。报错本身的意思是：PowerShell 在当前环境变量 PATH 里找不到 opencode 这个命令。但具体原因有好几种，我按排查顺序给你列一遍。

第一步，确认命令是否真的装上了。

在 PowerShell 里执行：

Get-Command opencode

如果提示找不到，可能安装本身失败了，也可能只是 PATH 没生效。先重新开一个终端窗口试试，Windows Terminal 有时候会缓存环境变量，新开窗口才能读到新路径。

第二步，确定 npm 全局包安装目录。

如果你是用 npm 装的，执行：

npm prefix -g

正常情况下输出的是类似C:\Users\你的用户名\AppData\Roaming\npm或C:\Program Files\nodejs。opencode 的可执行文件应该在那个目录下。

第三步，检查 PATH 里有没有这个目录。

执行：

[Environment]::GetEnvironmentVariable("Path", "User")

看输出里有没有上一步得到的 npm 全局目录。如果确实没有，手动加上：

[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Users\你的用户名\AppData\Roaming\npm", "User")

改完重新开终端，一般就解决了。

第四步，检查 PowerShell 脚本执行策略。

有时候命令文件在，但 PowerShell 会拒绝执行脚本，提示“无法加载文件，因为在此系统上禁止运行脚本”。执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这个设置允许运行本地脚本，远程下载的脚本需要签名，日常开发够用了。

第五步，如果还没解决，看是不是被旧版本残留干扰。

我之前就碰到过一次：npm list 显示有两个不同路径下都装了 opencode-ai，结果命令命中了旧版本，报错信息还特别诡异。直接执行：

where.exe opencode

看看命中的到底是谁，把旧残留清掉再试。

2.3opencode go是什么，为什么建议配合 ccswitch 用

这里单独说下opencode go。这个子命令的设计思路是：把 Agent 变成你的“命令执行器”。比如你直接输入：

opencode go "找出项目里所有 TODO 并整理成表格"

它可以自己去翻代码、跑脚本，最后给你一份整理结果。它不是简单的命令包装，而是让 AI 自主决定该跑哪些命令来解决你的问题。这个能力在接手陌生项目或做代码考古的时候非常高效。

那为什么很多老手建议配合 ccswitch 这类配置切换工具？原因是opencode go走的是全局配置，而你日常可能在多个模型服务商之间来回切换——工作项目用公司的 API key，个人项目用自己充值的那家，偶尔想试试某个免费模型的额度。ccswitch 这类工具能帮你集中管理多组 API 配置，一键切换当前生效的那一套，避免每次手动改配置文件。

实际使用中我最常遇到的问题是：忘了切配置，opencode go还在用上一个服务商的 key，结果返回 401。所以现在的习惯是执行opencode go之前，先看一眼 ccswitch 当前激活的是哪套配置。

3. 配置是灵魂：模型接入、免费模型与多配置切换

安装只是开始，真正决定 opencode 好不好用的是配置。它支持多模型供应商，但这个自由度也意味着你需要花点心思把配置理顺。

3.1 配置文件结构

opencode 的全局配置默认在~/.config/opencode/config.json。它的结构可以简单理解为一个大的 JSON 对象，里面有 provider、agent 等几个核心字段。最基础的配置长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "openai": { "api_key": "sk-...", "model": "gpt-4o" } } }

如果你用官方登录方式，也可以直接跑：

opencode auth login

然后用浏览器授权，它会把凭据存到本地，省去手写 API key 的步骤。两种方式我都试过，个人更推荐直接写配置文件，尤其是你有多套 key 要管理的时候，配置文件更透明，也更容易被 ccswitch 这类工具接管。

3.2 免费模型怎么接

开源工具的好处之一是，模型层不会被绑定。你可以通过 OpenRouter 接入不少免费档位的模型，也可以用 Ollama 在本地跑开源模型。接 OpenRouter 的配置方式：

{ "provider": { "openrouter": { "api_key": "你的OpenRouter Key", "models": { "deepseek/deepseek-chat": {}, "qwen/qwen-2.5-72b-instruct": {} } } } }

用 Ollama 跑本地模型也简单：

{ "provider": { "ollama": { "models": { "qwen2.5-coder:14b": {} } } } }

本地模型的好处是数据不离开你的机器，不花钱，断网也能用；缺点也很明显，生成速度比云端模型慢一截，复杂任务的理解能力有差距。我的建议是：日常改文件这种轻量任务可以用本地模型兜底，重要的架构设计、代码审查还是交给云端强模型。

3.3 关于免费模型和“套餐”的现实提醒

opencode 本身完全开源免费，但模型费用是你自己的开销。市面上所谓的“套餐”，本质上是某个模型服务商提供的订阅制额度，和你直接用 API 付费没有本质区别。

热词里出现过的hy3-free这类免费模型，我劝你别把核心工作流绑在上面。免费额度说下线就下线，说限流就限流，都是很正常的事。我见过有人把所有日常任务都跑在某个免费模型上，结果服务商一调整策略，整个工作流直接瘫痪。实用的做法是：长期任务准备一个付费 API 或本地模型兜底，免费额度只用来做探索性尝试。

3.4 ccswitch 怎么配合用出效果

ccswitch 这类工具解决的核心痛点是：当你有多个服务商的 key、多个模型配置时，切换成本太高。它的工作模式是维护一组配置文件，比如config.work.json、config.personal.json、config.openrouter.json，通过命令快速启用其中一套。

配合 opencode 的使用流程大概是：

1. 在 ccswitch 里录入你的几组配置。
2. 切到工作配置，opencode 就会用工作项目的 key。
3. 切到个人配置，opencode 自动用个人额度。

这样省去了反复改 config.json 的麻烦，也避免了把个人 key 带到公司项目里的隐患。如果你只用一个模型一个 key，ccswitch 的价值不大；但只要你开始接多个模型，这个工具能帮你省下大量时间。

4. 把 opencode 当主力开发助手：skills、memory 和前端自动化

这部分聊点真正能提升生产力的玩法。很多人装了 opencode 之后只会在里面问“这段代码什么意思”，那就太浪费了。

4.1 skills：让 Agent 学会你的工作流

skills 是 opencode 的扩展机制，本质上是一组 Markdown 指令和脚本的集合。你可以写一个“代码审查 skill”，规定当 AI 执行审查时，必须按你的团队规则来：先看 diff 范围、再检查测试覆盖、最后关注安全相关改动。也可以写一个“提交信息规范 skill”，让 AI 帮你生成符合 Conventional Commits 的提交信息。

社区里有一套叫 superpowers 的开源 skills 集合，是给 Claude Code 设计的，但 opencode 也可以直接装。安装方式很简单：

opencode install superpowers

装完之后它会注入一堆新的 skill 供你使用。

我的实际体会是：skill 不在多，而在精。一开始我装了一大堆，结果很多根本用不上，反而干扰了 Agent 的判断。现在只保留了三个：代码审查、项目初始化检查、测试报告分析。这三个恰好是日常开发中最希望 AI 按固定套路执行的事。

4.2 memory：跨会话记忆

做过接手工期项目的人都知道，最烦的是每次开会都要重新理解一遍项目约定。opencode 的 memory 机制就是用来解决这个问题的：它能把项目的偏好和约定保存下来，下次启动时自动加载。

你可以在项目根目录建一个AGENTS.md或类似文件，写清楚“本项目用 pnpm 不用 npm”“单测命令是yarn test:unit”“后端代码在server/目录下”这类信息。opencode 会在每次会话开始前自动读取这段背景知识。

我实测下来，这个功能是接手陌生项目时最值得优先配置的一件事。因为 Agent 最大的任务其实不是写代码，而是理解上下文。你花十分钟把项目约定写清楚，它后续的表现会完全不一样。

4.3 用 Playwright 让 AI 自己测前端 bug

热搜词里有一句是“opencode playwright 怎么测试前端 bug”，这个场景我最近刚好深度跑过，流程可以完整复现一下。

起因是我们项目里有个按钮，点击后控制台偶尔报一个 TypeError，但本地复现很不稳定。我把现象描述给 opencode：

1. 它先读代码，定位到按钮的事件处理函数，发现某个对象在特定分支下确实可能是 undefined。
2. 接着它主动提出用 Playwright 写复现脚本：启动 dev server，打开页面，点击按钮，监听 console 报错。
3. 第一次跑没复现，它调整了策略，增加了几个前置操作步骤，模拟用户真实点击路径。
4. 第二次跑成功复现了报错，然后把堆栈信息贴出来，给出了修复补丁。

整个过程我基本只是描述现象和审批改动，具体的测试编排是它自己完成的。

要用好这个能力，有几个前提：

• 项目里要装好 Playwright，并且浏览器驱动能正常拉起来。
• 你要给 opencode 明确的项目启动命令，它没法凭空猜出npm run dev和pnpm dev的区别。
• 建议先口头让它描述测试计划，确认合理后再让它动手，避免被它带偏方向。

5. 实战记录：用 opencode 接手一个陌生项目

把场景拉得更具体一点。我最近用一个不是自己写的 Vue3 + TypeScript 项目做实验，试图让 opencode 在完全没有人肉讲解的情况下帮我理解并改进一个 bug。

5.1 项目扫描与上下文构建

首次进入项目前，我先执行了一个指令：

opencode "请先通读项目结构，告诉我这个项目的架构、技术栈、目录职责和核心数据流"

它会自己去读package.json、vite.config.ts、src目录结构、路由文件等，然后给出一个概要。这个过程看起来简单，实际上很考验 Agent 的规划能力——项目里有几百个文件，它必须知道先看什么、哪些文件是核心入口。

我给它的建议是：第一次扫描时尽量要求它输出“它看了哪些文件”，而不是只给结论。这样你能快速纠正它理解偏差的地方，避免它基于错误认知往下走。

5.2 从 issue 描述到代码修改的闭环

接下来我给了它一个很真实的需求：某个页面在筛选条件变化后，URL query 没有同步更新，刷新后筛选条件丢失。这是我模拟的 issue 描述，没有额外给任何线索。

它做的事情大致是：

1. 定位到页面组件，找到筛选条件状态管理的位置。
2. 检查路由和 URL query 的读写逻辑，发现代码里只有本地 state，没有把条件同步到路由。
3. 给出两套方案：一是直接监听 state 变化并写进 URL；二是改用路由驱动 state。
4. 我选了方案一，它随后修改了代码并补充了相应的单元测试。

整个过程我可以随时要求它显示 diff，确认无误后再让它落盘。这种“先方案后动手”的行为模式非常重要，如果你的 Agent 一上来就改代码，请立刻打断它。

5.3 代码审查与重构

opencode 还有一个用途是给改动做 review。你在已经git add之后，执行：

opencode review

它会基于当前暂存区的内容生成 review 意见，包括潜在 bug、风格问题、边界情况。我曾经靠它抓出一个并发修改同一个对象的隐患，这个 bug 人眼很难一下子看出来。

做重构时，我的习惯是先让它跑一遍现有测试拿到基线，再开始改。改完再跑测试，对比前后差异。如果重构前后测试通过情况一致，至少说明没有引入明显的回归。

现在可以这样操作。我会严格按照要求，直接输出一篇可直接发布的 Markdown 格式的博文，从博文内容开始，不使用代码块包裹，不含任何前置说明和元信息，不出现任何敏感内容。 最近社区里问 opencode 的人突然变多了，群里有人拿它和 Codex、Claude Code 对比，有人问它到底是不是某家大厂的闭源产品，还有人卡在 Windows 安装的第一步就疯狂报错。我大概一个多月前开始把它深度用进真实项目，从个人小仓库到一个中等规模的前端工程，前后跑了二十多天，整体感受就一句话：这可能是目前把“多模型通用性”和“工程执行力”平衡得最好的开源终端 Agent，但前提是你愿意花十几分钟把配置这块彻底搞明白。

这篇文章不打算复述官方文档，而是把我自己从安装、接模型、调配置，到用它接手陌生项目、跑 Playwright 测前端 bug 的完整过程复盘一遍，重点放在那些文档里不会写、但确实坑到过我的细节上。无论你是刚知道这个名字，还是已经装上但卡在某个报错里，这篇应该都能给你对应的解法。

1. 先搞清楚它是什么东西：不是又一个聊天窗口

很多人第一次启动 opencode，会下意识把它当成 ChatGPT 的终端版，这是一个方向性误解。它确实有交互式对话界面，但核心定位不是“聊天”，而是在你的项目文件系统里真正干活的 Agent。

1.1 终端 Agent 的本质：从“给建议”变成“动手做”

opencode 跑在终端里，启动后可以读取项目目录下的所有文件、创建和修改文件、执行 Shell 命令、运行测试、检查 Git 状态，甚至调用浏览器做自动化验证。它不像聊天机器人那样只给你“建议代码”，而是会把改动直接落到磁盘上，然后让你 review。

这种设计带来的直接变化是：你交代一个任务，它会当作任务去闭环处理。比如你说“帮我把这个函数的调用方全部找出来并统计调用次数”，它不是给你一段代码让你自己跑，而是自己在项目里 grep、写脚本、跑完把结果整理好给你。

它的能力来源可以拆成几层：

• 底层是各家大模型，默认支持 Anthropic Claude、OpenAI、Google Gemini，也支持 Ollama 这类本地模型。
• 中间是它自己的 Agent 循环，负责规划任务、调用工具、分析执行结果、决定下一步动作。
• 上层是你自定义的配置和 skills，用来告诉它你项目的规范和偏好。

所以它本质上是“模型无关的执行框架”，不是绑定在某一家模型上的专用工具。这也是为什么很多人拿它和 Claude Code 对比——两者看起来像，但设计出发点不一样。

1.2 和 Codex、Claude Code、Pi 相比，差异在哪里

我最近把几个主流终端 Agent 都实际跑过一轮，直接列个表方便你对照：

选哪个更多取决于你的习惯。如果你主力模型就是 Claude，并且能接受生态绑定，Claude Code 依然是最深最顺的选择；但如果你希望同一个工具能随时切换模型供应商，或者希望自己掌控整个调用链路，opencode 的优势会更明显。

2. 安装这关，坑比想象中多

opencode 的安装方式本身不算复杂，但在 Windows 环境下的坑确实多，而且很多是官方文档没有重点提示的。

2.1 三种常见安装方式

macOS / Linux 用户最省事的是用官方脚本：

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

npm 用户注意包名不是opencode，而是opencode-ai：

npm install -g opencode-ai

Homebrew 用户也可以：

brew install sst/tap/opencode

装完先验证一下：

opencode --version

能看到版本号说明核心程序已经就位，直接跳到配置章节；看不到的话，接着往下排查。

2.2 Windows 下“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”完整排查链路

这个报错的热度非常高，基本是 Windows 新手最容易撞上的墙。报错本身的意思是：PowerShell 在当前 PATH 里找不到 opencode 命令。但具体原因有几种，我按排查顺序列一遍。

第一步，确认命令是否真的装上了。

在 PowerShell 里执行：

Get-Command opencode

如果提示找不到，可能是安装失败，也可能只是 PATH 没生效。先重新开一个终端窗口再试一次，Windows Terminal 有时候会缓存环境变量，新开的窗口才会读取最新的 PATH。

第二步，确认 npm 全局包安装目录。

如果你是用 npm 装的，执行：

npm prefix -g

正常输出是类似C:\Users\你的用户名\AppData\Roaming\npm或C:\Program Files\nodejs的路径。opencode 的可执行文件应该在那个目录下。

第三步，检查 PATH 里有没有这个目录。

执行：

[Environment]::GetEnvironmentVariable("Path", "User")

看输出里有没有上一步拿到的 npm 全局目录。如果确实没有，手动加上：

[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Users\你的用户名\AppData\Roaming\npm", "User")

改完重新开终端，大多能解决。

第四步，检查 PowerShell 脚本执行策略。

有时候命令文件在，但 PowerShell 拒绝执行脚本，提示“无法加载文件，因为在此系统上禁止运行脚本”。执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这个设置允许运行本地脚本，远程下载的脚本需要签名，日常开发够用了。

第五步，清理旧版本残留。

我之前踩过一次比较隐蔽的坑：npm list 显示有两个路径都装了 opencode-ai，结果命令命中了旧版本，报错信息还很奇怪。这时候执行：

where.exe opencode

看命中的到底是哪个路径，把旧的残留清掉再试。

2.3 opencode go 是什么，为什么建议配合 ccswitch 用

opencode go是 opencode 的子命令，设计思路是：把 Agent 变成你的“命令执行器”。你可以直接输入：

opencode go "找出项目里所有 TODO 并整理成表格"

它会自己翻代码、跑脚本，最后把整理结果给你。这个能力在接手陌生项目或做代码考古的时候非常高效。

那为什么很多老手说 opencode go 需要配合 ccswitch 这类工具？原因是opencode go走的是全局配置，而你日常很可能在多个模型服务商之间来回切换——公司项目用一种配置，个人项目用另一种，偶尔想试试某个新模型的免费额度。ccswitch 这类配置切换工具能集中管理多组 API 配置，一键切换当前生效的那一套，省去反复手改配置文件的麻烦。

我自己最常遇到的场景是：忘了切配置，opencode go还在用上一个服务商的 key，结果返回 401。现在我的习惯是执行opencode go之前，先看一眼 ccswitch 当前激活的是哪套配置。

3. 配置是灵魂：模型接入、免费模型与多配置切换

安装只是开始，真正决定 opencode 好不好用的是配置。它支持多模型供应商，但这个自由度也意味着你需要花心思把配置理顺。

3.1 配置文件结构长什么样

opencode 的全局配置默认在~/.config/opencode/config.json。它的结构就是一个 JSON 对象，核心字段包括 provider、agent 和模型映射。最基础的配置长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "openai": { "api_key": "sk-...", "model": "gpt-4o" } } }

如果你不想手写 API key，也可以直接执行：

opencode auth login

用浏览器授权，它会把凭据存到本地。两种方式我都试过，个人更喜欢直接写配置文件，尤其是手上有几套 key 的时候，配置文件更透明，也更容易被 ccswitch 这类工具接管。

3.2 免费模型怎么接

开源工具的好处之一是模型层不会被绑定。你可以通过 OpenRouter 接入不少免费档位的模型，也可以用 Ollama 在本地跑开源模型。接 OpenRouter 的配置：

{ "provider": { "openrouter": { "api_key": "你的OpenRouter Key", "models": { "deepseek/deepseek-chat": {}, "qwen/qwen-2.5-72b-instruct": {} } } } }

用 Ollama 跑本地模型：

{ "provider": { "ollama": { "models": { "qwen2.5-coder:14b": {} } } } }

本地模型的好处是数据不出机器、不花钱、断网也能用；缺点是生成速度比云端模型慢一截，复杂任务的理解能力有明显差距。以我个人的使用体验，日常改文件这种轻量任务可以用本地模型兜底，重要的架构设计、代码审查还是交给云端强模型更稳。

3.3 免费模型的“寿命”问题：别把工作流绑死在免费额上

热词里出现过的 hy3-free 这类免费模型，我的态度是：可以用来尝鲜，但千万别把核心工作流绑在上面。免费额度说下线就下线，说限流就限流，都是很正常的事。

我见过有人把所有日常任务都跑在某个免费模型上，结果服务商一调整策略，整个工作流直接瘫痪。实用的做法是：长期任务准备一个付费 API 或本地模型兜底，免费额度只用来做探索性尝试。

3.4 ccswitch 怎么配合出效果

ccswitch 解决的核心痛点是：当你有多个服务商、多个配置时，切换成本太高。它的工作模式是维护一组配置文件，比如config.work.json、config.personal.json、config.openrouter.json，通过命令快速启用其中一套。

配合 opencode 的使用流程：

1. 在 ccswitch 里录入你的几组配置。
2. 切到工作配置，opencode 就会用工作项目的 key。
3. 切到个人配置，opencode 自动用个人额度。

这样省去了反复改 config.json 的麻烦，也避免了把个人 key 带到公司项目里的隐患。如果你只用一个模型一个 key，ccswitch 的价值不大；但只要你开始接多个模型，这个工具能帮你省下大量时间。

4. 把 opencode 当主力开发助手：skills、memory 和前端自动化

配置理顺之后，真正拉开体验差距的是你愿不愿意花时间去调教它。这一节聊几个我认为最值得掌握的玩法。

4.1 skills：让 Agent 学会你的工作流

skills 是 opencode 的扩展机制，本质上是一组 Markdown 指令和脚本。你可以写一个“代码审查 skill”，规定当 AI 执行审查时，必须按你的团队规则来：先看 diff 范围、再检查测试覆盖、最后关注安全相关改动。也可以写一个“提交信息规范 skill”，让 AI 帮你生成符合 Conventional Commits 的提交信息。

社区里有一套叫 superpowers 的开源 skills 集合，本来是给 Claude Code 设计的，但 opencode 也可以直接装。安装方式很简单：

opencode install superpowers

装完之后它会注入新的 skill 供你调用。

我自己的体会：skill 不在于多，而在于精。一开始我装了一大堆，结果很多根本用不上，反而干扰了 Agent 的判断。现在只保留三个：代码审查、项目初始化检查、测试报告分析。这三个恰好是日常开发中最希望 AI 按固定规则执行的事件。

4.2 memory：跨会话记忆能省多少事

做过接手工期项目的人都知道，最烦的是每次都要重新理解一遍项目约定。opencode 的 memory 机制解决的就是这个问题：它能把项目的偏好和约定保存下来，下次启动时自动加载。

你可以在项目根目录建一个AGENTS.md文件，写清楚“本项目用 pnpm 不用 npm”“单测命令是yarn test:unit”“后端代码在server/目录下”这类信息。opencode 会在每次会话开始前自动读取这段背景知识。

我实测下来，这个功能是接手陌生项目时最值得优先配置的一件事。Agent 最大的任务其实不是写代码，而是理解上下文。你花十分钟把项目约定写清楚，后续它的表现会完全不一样。

4.3 用 Playwright 让 AI 自己测前端 bug

热搜词里有一句“opencode playwright 怎么测试前端 bug”，这个场景我最近刚好深度跑过，简单复现一下流程。

我们项目里有个按钮，点击后控制台偶尔报一个 TypeError，本地复现很不稳定。我把现象描述给 opencode：

1. 它先读代码，定位到按钮的事件处理函数，发现某个对象在特定分支下的确可能是 undefined。
2. 然后它主动提出用 Playwright 写复现脚本：启动 dev server、打开页面、点击按钮、监听 console 报错。
3. 第一次跑没有复现，它调整了策略，增加前置操作步骤，模拟更真实的用户点击路径。
4. 第二次成功复现报错，它把堆栈信息贴出来，给出修复补丁。

整个过程我基本只负责描述现象和审批改动，具体的测试编排是它自己完成的。

要用好这个能力，有几个前提条件：

• 项目里要装好 Playwright，并且浏览器驱动能正常拉起来。
• 你要给 opencode 明确的项目启动命令，它没法凭空猜出npm run dev和pnpm dev的区别。
• 建议先让它口头描述测试计划，确认合理后再让它动手，避免被它带偏方向。

5. 实战记录：用 opencode 接手一个陌生项目

把场景拉得更具体一点。我最近拿一个不是我写的 Vue3 + TypeScript 项目做实验，让 opencode 在完全没有人肉讲解的情况下帮我理解并改进一个 bug。

5.1 项目扫描与上下文构建

首次进入项目前，我先执行了一个指令：

opencode "请先通读项目结构，告诉我这个项目的架构、技术栈、目录职责和核心数据流"

它会自己去读package.json、vite.config.ts、src目录结构、路由文件等，然后给出概要。这个过程看起来简单，实际上很考验 Agent 的规划能力——项目里有几百个文件，它必须知道先看什么、哪些文件是核心入口。

我给你的建议是：第一次扫描时尽量要求它输出“它看了哪些文件”，而不是只给结论。这样你能快速纠正它理解偏差的地方，避免它基于错误认知往下走。

5.2 从 issue 描述到代码修改的闭环

接下来我给了它一个很真实的需求：某个页面在筛选条件变化后，URL query 没有同步更新，刷新后筛选条件丢失。这是模拟的 issue 描述，没有额外给任何线索。

它做的事情大致是：

1. 定位到页面组件，找到筛选条件状态管理的位置。
2. 检查路由和 URL query 的读写逻辑，发现代码里只有本地 state，没有把条件同步到路由。
3. 给出两套方案：一是直接监听 state 变化并写进 URL；二是改用路由驱动 state。
4. 我选了方案一，它随后修改了代码，并补充了对应的单元测试。

整个过程我可以随时要求它显示 diff，确认无误后再让它落盘。这样一套“先方案后动手”的行为模式非常重要，如果你的 Agent 一上来就改代码，请你立刻打断它。

5.3 代码审查与重构

opencode 还有一个很实用的用途是给改动做 review。你在已经git add之后，执行：

opencode review

它会基于暂存区内容生成 review 意见，包括潜在的 bug、风格问题、边界情况。我曾经靠它抓出一个并发修改同一个对象的隐患，那个 bug 人眼很难一下子看出来。

做重构时，我的习惯是先让它跑一遍现有测试拿到基线，再开始改。改完后再跑测试，对比前后差异。如果重构前后测试通过情况一致，至少说明没有引入明显的回归。

6. IDE 插件与桌面版：终端之外的选择

不是所有人都喜欢在终端里干活，所以 opencode 也提供了 IDE 插件和桌面版，体验上各有取舍。

6.1 VSCode 插件

在 VSCode 扩展市场搜 OpenCode 即可安装。装完之后侧边栏会多一个对话窗口，你可以选中代码片段直接发送给 opencode，它基于选中内容进行理解。这个模式在“边看代码边改”的场景下确实顺手，不用在终端和编辑器之间来回切。

但要注意：插件版的功能比终端版少一些，某些权限控制行为也不太一致。我的建议是简单提问用插件，复杂改动和命令执行还是回终端。

6.2 JetBrains IDEA 插件

IDEA 版插件在插件市场也能搜到，配置方式与 VSCode 类似，复用全局配置。不过个人体验是 JetBrains 插件更新节奏比 VSCode 慢，我遇到过一次配置格式不兼容的问题，后来还是回到终端处理。

6.3 桌面版

桌面版是带 GUI 的客户端，内嵌终端和文件树，更像一个完整的工作台。它的价值主要是降低上手门槛，让不熟悉命令行的人也能用起来。但如果你打算深度使用，建议还是从终端 CLI 上手，因为很多高级配置、调试手段在终端里才完整。

7. 报错排查：从 unexpected server error 到日常故障

不管哪个工具，跑久了一定会撞上报错。opencode 的报错信息有时比较模糊，这里把最常见的几类集中梳理一下。

7.1 unexpected server error 怎么破

热搜词里有一句：c:\windows\system32>opencode error: unexpected server error. check server lo...，这个报错的本质是：opencode 启动时尝试连接某个本地或远程服务，但连接失败。

排查链路建议按这个顺序走：

1. 开 debug 日志：opencode --log-level debug，看具体是哪一步抛出的异常。
2. 检查本地依赖服务是否启动。如果你配置了 Ollama，先执行ollama list确认模型存在且服务在线。
3. 检查配置文件里的 model id 是否真实存在。很多报错其实是模型名拼写错误，服务商返回的模型列表里根本没有这个 id。
4. 检查 API endpoint 是否可达，key 是否有效。可以先在终端里手动 curl 一下服务商的接口，排除网络和服务商侧的问题。

实测下来，绝大多数 unexpected server error 都是 API endpoint 配错或者 model id 拼错导致的，debug 日志里能看到请求的具体 URL 和响应状态码，跟着日志排查基本能定位。

7.2 Windows 下另一个高频问题：脚本执行策略

除了前面提到的 cmdlet 不识别，Windows 用户还会经常遇到“因为在此系统上禁止运行脚本”的提示。这个直接执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

7.3 旧版本残留

npm 全局安装过旧包残留，会导致命令指向错误的版本。遇到奇怪行为时，先执行opencode --version确认版本号，再用where.exe opencode（Windows）或which -a opencode（macOS/Linux）看是否有多个安装路径。

8. 我的选型建议：什么时候该用 opencode

内容写到这里，最后聊点更现实的问题：你手上的项目到底适不适合引入 opencode。

8.1 和 Codex、Claude Code、Pi 怎么选

回到开头那张对比表，我补充一点个人体会：

• 如果你的主力是 Claude，且团队已经有大量 Claude 生态的沉淀，Claude Code 依然是不可替代的。
• 如果你想用一个开源、可审计、模型可随时切换的 Agent，opencode 目前是综合体验最稳的。
• Codex CLI 形态上和 opencode 很像，但它对非 OpenAI 模型的支持明显弱一些，追求多模型自由度的不建议入坑。
• Pi 更适合轻量代码生成和解释，但在复杂工程的闭环执行上还不够成熟。

8.2 适合的团队与场景

从我自己的使用经验来看，opencode 特别适合这几类情况：

• 个人开发者，希望有一个能跑在自己机器上、完全可控的 AI 编程助手。
• 团队有明确代码规范，想把规范沉淀成自动执行的流程。
• 需要接手工期老项目，想快速建立项目理解的场景。
• 对模型成本敏感，希望随时切到免费额度或本地模型。

不太适合的场景也有：业务逻辑极度复杂、需要大量业务上下文才能动工的项目，不要把 AI 当成需求分析员；强合规环境下不允许代码出网的团队，建议用本地模型，甚至干脆别上 Agent 工具。

最后分享一点真实体会：AI Agent 不是替代人的判断，而是把反馈循环变短。它最大的价值不是替你写代码，而是让你从“机械执行”里解放出来，把时间花在真正需要人类判断力的事情上。opencode 在这个方向上做得足够好，但最终定义问题的，仍然是你自己。