企业官网建设流程全解析

1. 从一次工具迁移说起：opencode 到底是做什么的

最近小半个月，我把日常的编码主力从一个很火的商业 Agent 慢慢换到了 opencode 上。起因很简单：我想在同一个终端工具里自由切换不同厂商的模型，又不想把所有代码会话都绑在一家生态里，于是试了一圈开源的终端 AI 编码助手，最后留下的是它。

这个 opencode 是什么？说得直接一点，它是一个用 Go 写的开源 TUI 编程助手，放在命令行里运行，给它一个任务，它会自己翻你项目里的代码、调用工具、改文件、跑测试，然后把改动结果拿给你审。很多人在搜索记录里看到“opencode go”这个词，其实就是指它是 Go 语言实现这件事，不是某个独立命令。因为核心是用 Go 写的，所以启动速度快、单文件分发、跨平台安装也简单，这是它和一大批 Node 系 AI 命令行工具最直观的区别。

如果你也正在纠结 opencode 是不是又一个换壳玩具，或者刚下载完就在 Windows 上碰到“无法将 opencode 项识别为 cmdlet”的报错，又或者听别人说它能接免费模型但不知道具体怎么配，这篇文章基本就是为你准备的。我会从它是什么、到底解决了什么问题开始，一路讲到安装、配置、MCP、skills、日常接老项目、用 Playwright 测前端 bug 的实战，最后再给一个高频报错速查表。全程不堆官方文档的复制粘贴，尽量把“我实际跑通过”的细节写清楚。

1.1 和 codex、claude code、pi 这类 Agent 怎么选

现在终端 AI 编码助手已经不是新鲜概念了，Claude Code、Codex CLI、OpenCode，还有更新一点的 pi 之类的项目，都在抢占同一个场景：让模型直接在终端里操作代码。很多人会直接问“哪个 agent 好用”，但我的体会是，它们定位差得挺远，先想明白自己要什么，再选工具。

Claude Code 最突出的地方是“开箱即用”的成熟度，它对 Claude 模型的指令遵循、工具调用做得很顺，项目里写一个 CLAUDE.md 就能长期保持上下文；但同时它天然偏向 Anthropic 生态，想接别的模型要绕不少路。Codex CLI 是 OpenAI 阵营的开源终端 Agent，如果你主要用 OpenAI 的模型，体验很顺，但它和其他模型提供方的适配程度同样有限。opencode 和它们的核心差异是两个：一是完全开源，代码随便翻，出问题可以自己改；二是模型中立，Anthropic、OpenAI、Gemini、本地 Ollama、第三方 OpenAI 兼容接口都能接，同一个任务可以在不同模型之间横跳对比。至于 pi 这种新秀，思路更极客，适合喜欢整天换工具、追新版本的人，但生态成熟度还在早期。

如果你问我现在团队导入用哪个，我一般这么建议：追求稳定省心、团队全是 Claude 用户，用 Claude Code；重度 OpenAI 生态、想要官方支持，用 Codex CLI；想多模型切换、想把 AI 编码能力沉淀成团队自己的 skills、或者需要对接国内模型网关的，优先看 opencode。

1.2 “opencode 是哪家公司的”可能是最容易误会的问题

我在好几个技术群里都看到有人问“opencode 是哪家公司的”，这里统一说清楚：它不是一个商业公司的闭源产品，核心是个人和开源社区驱动的项目，由做 Serverless 开发框架的 SST 团队核心成员发起，代码完整放在 GitHub 上，协议也是常见的开源许可证。所以它没有“官方客服”，没有“套餐价格表”，遇到问题主要靠 GitHub Issues、Discord 社区和文档。

这一点既是优点也是坑。优点是迭代真的快，社区提的 feature 可能几周就上线；缺点是你别指望它有商业产品那种保姆级支持，有些边角功能坏了要等下一个版本修复，遇到问题得学会自己看日志。我在实际使用中的策略是：生产环境尽量用稳定发布版，新功能先在测试项目里试，每周固定时间升一次版，而不是天天追最新。后面第 7 节我会专门讲怎么看日志排查问题。

2. 安装与首次启动：三分钟跑起来，含 Windows 报错解法

2.1 三种安装方式，按你的环境挑一个

安装 opencode 其实就几条路，挑一个适合你环境的就行。

macOS 用户如果装了 Homebrew，最简单的方式是：

brew install sst/tap/opencode

Linux 和大部分 Unix 环境可以用官方安装脚本：

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

Windows 用户我个人最推荐用 npm 全局安装，因为最不容易踩权限坑：

npm i -g opencode-ai

装完先验证一下版本，能正常输出就说明命令已经进入 PATH：

opencode --version

另外还有一个保底方案是去 GitHub 的 Release 页面直接下载对应平台的可执行文件，Windows 就是下载 exe，解压之后放进一个目录，手动把这个目录加到 PATH 里。这个方法特别适合那些公司网络对 GitHub 访问不稳定、又不想折腾镜像源的场景。

2.2 Windows 专属报错：无法将“opencode”项识别为 cmdlet

这个报错的热度在中文搜索里非常高，我几乎可以确定你装完 opencode 在 PowerShell 里敲opencode时弹出来的就是这句：

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

先说结论：99% 的情况不是 opencode 坏了，而是你刚装的命令没有被当前的 PowerShell 找到。原因通常是两类。一类是安装完成后没有重启终端，PowerShell 里的 PATH 环境变量还是旧的，这种情况关掉终端重新打开一个就行。另一类是 npm 的全局安装目录根本不在系统 PATH 里，命令装到了某个文件夹，但系统不知道去哪儿找它。

第二种的解决办法是打开 PowerShell，先执行：

npm config get prefix

这会输出 npm 全局安装根目录，在 Windows 上通常是C:\Users\你的用户名\AppData\Roaming\npm。确认这个路径后，去系统环境变量设置里把%APPDATA%\npm加进 Path，保存后重开终端。如果不想动环境变量，还有一个懒人办法：直接用绝对路径跑，例如C:\Users\xxx\AppData\Roaming\npm\opencode.exe，能跑通再去改环境变量。

2.3 首次启动：认证、模型选择、跑通第一个任务

安装完成后，直接在终端里输入opencode就会进入它的 TUI 界面。第一次进入会让你选择模型提供方，并且要通过登录或者填 API Key 的方式完成认证。如果你更习惯命令行操作，也可以先用这条命令：

opencode auth login

登录完成后，一行式任务可以用opencode run跑。比如我想让它解释当前目录的项目结构：

opencode run "简要分析一下这个项目的目录结构和主要模块"

如果当前目录没有项目，它会提示你；如果有，它会开始读文件、分析代码，然后在终端里输出结论。第一次跑的时候你会发现它像真人一样先看 package.json、README、入口文件之类，再给结论，这种感觉和单纯的“聊天框问答”完全不一样。

提示：首次使用建议先跑一个简单任务，确认模型连通、文件读取正常，再开始接真实项目。不要在没验证过环境的情况下直接让它改代码。

3. 配置是灵魂：模型、MCP、skills、memory 一次讲透

3.1 两个核心配置：opencode.json 和 auth.json

opencode 的配置机制不复杂，记住两个关键位置就好：一个是全局目录下的配置文件，Linux/macOS 在~/.config/opencode/，Windows 在%USERPROFILE%\.config\opencode\；另一个是项目根目录下的opencode.json。

其中auth.json保存的是各模型提供方的密钥，这个文件默认不会提交到 Git，千万别手动把它放到仓库里。opencode.json是主配置，可以配置默认模型、MCP 服务、启动参数等。项目根目录下的配置会覆盖全局配置，所以同一个团队可以约定把 opencode.json 提交进仓库，让所有人统一 MCP 和模型策略。

一个最小化的项目配置大概是这样的：

{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4", "autoupdate": true }

注意model的格式是“提供方/模型名”，这是 opencode 里识别模型的基本写法。如果你不用这个字段，TUI 启动时会用上次选择的模型，或者要求你手动选择。

3.2 免费模型怎么接？说说几条靠谱路径

“opencode 免费模型”是搜索热词，我得先泼点冷水：完全免费且稳定的大模型 API 在 2025 年的现实世界里基本不存在，所谓的免费模型通常有额度限制、速度限制、或者只适合低强度试用。实际工作中我见过的靠谱路径是三条。

第一条是用本地模型，例如 Ollama。跑一个 7B 左右的中小模型在本地做日常重构、代码解释完全够用，隐私也好，适合不愿意把代码发给外部 API 的场景。opencode 对 OpenAI 兼容接口的支持很成熟，把 Ollama 的本地接口配进来就行，比如：

ollama pull qwen2.5-coder:7b ollama serve

然后在 opencode 配置里加一个指向http://localhost:11434/v1的 provider，模型名填你拉取的模型名。好处是不花钱、不出网；坏处是模型能力上限就摆在那，复杂架构设计和长链路排错还是会吃力。

第二条是用模型聚合平台或者云厂商提供的体验额度。很多云平台和聚合服务商会提供 OpenAI 兼容的 API 地址、有限度的免费调用次数，把这类接口作为一个 provider 配到 opencode 里，就能当“免费模型”用。配置方式和本地模型一样，只是 baseURL 换成服务商给的地址。这类服务五花八门，我不在这里具体点名，但有三个判断标准：是否支持 OpenAI 兼容协议、是否把密钥明文暴露、文档里有没有明确写清免费额度和续费规则。三条都满足再往生产环境接。

第三条是参与开源社区贡献换取额度。opencode 和部分模型服务商有合作，对开源项目的有效贡献者会提供免费的使用额度，这是合规又稳的一条路，但门槛显然比前两条高。如果只是自己玩一玩，本地 Ollama 是最快能跑通的方式。

提示：尽量别把来源不明的“免费 API Key”用在公司项目里，轻则数据外泄，重则合规风险。个人学习随便试，但要时刻记住代码是资产。

3.3 MCP 配置：让 agent 真正“动手”

MCP（Model Context Protocol）是一个把外部工具接入 AI 模型的标准协议。opencode 对 MCP 支持得相当好，配置文件里加一个 mcp 字段，就能让它在会话里调用外部服务。很多人在搜“opencode mvn 配置”，我怀疑是“opencode MCP 配置”的口误，因为两者发音有点像，而 MCP 恰恰是配置里最值得花时间的部分。

一个典型的项目配置长这样：

{ "mcp": { "playwright": { "type": "local", "command": ["npx", "-y", "@playwright/mcp@latest"], "enabled": true } } }

这个配置的作用是让 opencode 能调用 Playwright，打开真实浏览器去测试前端页面。配置完成后重启 opencode 会话，对话里就能直接说“用 Playwright 打开当前页面，看一眼控制台有没有报错”，它会自己启动浏览器做操作、截屏、抓日志。这类 MCP 工具还有文件系统、数据库、浏览器调试、Git 操作等方向，团队可以根据开发场景按需接入。我的建议是不要一上来接一堆，先接一个真正解决痛点的，跑顺了再扩展。

3.4 skills 和 memory：把团队经验沉淀下来

opencode 的 skills 机制是我最看重的功能之一。简单说，它允许你把一段经常要做的操作写成一个带结构化描述的 Markdown 指令，之后在对话里通过名字唤起，agent 就按照你预定义的流程执行。社区里很火的 superpowers、oh-my-claudecode 这类项目，本质上就是把大量技巧预置成 skills，opencode 的机制也能吸收这种玩法。

一个最简单的技能示例，保存为.opencode/skills/code-review.md：

--- name: code-review description: 对当前分支做一次代码评审，输出问题和改进建议 --- 请对当前 Git 分支相对 main 的改动做代码评审： 1. 先运行 git diff main...HEAD --stat 了解改动范围。 2. 按文件逐个阅读 diff，重点关注逻辑错误、边界条件、安全隐患。 3. 输出格式：问题列表（严重程度 + 文件位置 + 原因 + 修改建议）。 4. 最后总结改动里做得好的地方。

写好后，在对话里说“做个 code review”，它就会执行这套流程。memory 则对应项目里的长上下文，最实用的做法是在项目根目录维护一个 AGENTS.md，把目录结构、启动命令、测试命令、代码约定都写进去，opencode 会在会话开始时自动读取这份文件。配合 skills，相当于把一个团队的开发规范直接注入到模型的工作记忆里，这才是它比纯聊天式工具更有长期价值的地方。

4. 日常开发实战：怎么把 opencode 变成团队搭档

4.1 我日常最顺手的 TUI 操作路径

TUI 界面刚上手的人容易懵，因为满屏幕都是信息，但其实高频操作就那么几个。进入会话后，直接在输入框写任务；想切换模型，输入/model会弹出选择器，平时我至少会保留一个强模型和一个便宜模型，简单任务用便宜的，复杂架构讨论切强模型；想查看当前会话可用的工具，输入/mcp能看到 MCP 服务状态；需要放弃当前改动，对话里说“把所有改动撤销”，它会根据 Git 状态判断并执行。

我最常用的一个习惯是“先看后改”。拿到一个任务，我不会让它直接改，而是先下指令：

先不要改代码。请阅读相关文件，告诉我你的修改方案，包括影响范围、要动哪些文件、怎么测试，确认后再动手。

这能极大避免模型乱改一团。另一个习惯是给任务加边界，比如“只改 xxx 目录下的文件，其他文件不要动”“不要改 package-lock.json”“不要执行 git push”。模型在开放式任务里容易自作主张，把边界写在指令里比事后回滚省事得多。

4.2 接手老项目：从一脸懵到顺利改动

“opencode 接手开发项目”这个搜索词，我觉得背后是很多人的真实痛点：新项目还好，老项目代码乱、文档缺、历史包袱重，人和 AI 都容易栽跟头。我接手老项目的标准流程是这样的。

第一步，先让 opencode 跑一次全项目梳理。给它的指令是：

先阅读这个项目的 README、package.json、构建配置和入口文件，帮我弄清楚三件事： 1. 项目怎么启动、怎么跑测试 2. 目录结构和核心模块职责 3. 有没有明显的遗留技术债 结果写到 AGENTS.md，之后我们所有会话都要参考这个文件。

这个操作我会显式要求它写进 AGENTS.md，因为之后每一次新会话它都会重新读这份文件，相当于给项目建立了一份“活的交接文档”。第二步，我会根据 AGENTS.md 里的启动命令，让 opencode 先把项目跑起来。很多 AI 工具改代码时根本不跑项目，导致改完才发现编译都过不了，所以在老项目里“能跑起来”是第一原则。

第三步，才让它开始改需求。但改之前我会明确任务的最小范围，比如“在订单列表页增加一个导出按钮，只改前端页面和对应接口调用，不动后端”，并强调改完以后跑一次相关的测试命令。这套流程下来，即使一个我从没接触过的老仓库，通常也可以在一小时内进入可维护状态。

4.3 我最推荐的团队工作流

把 opencode 引入团队时，我见过两种极端：一种是不让任何人用，怕乱改代码；另一种是塞给新员工当“万能工具”，出问题甩锅给 AI。这两种都不对。比较合理的落法是把它当成一个“严格的结对实习生”：可以做任务，但每一步都要人来审。

我所在团队现在的基本规范是三条。第一，opencode 的改动必须在独立 git 分支上，不允许直接在主分支或者自己正在开发的分支上让它乱动。第二，任务指令必须包含可验证的完成标准，比如“跑通某条测试”“页面能正常打开”，不允许只写“优化一下”。第三，涉及删除、回滚、推送远程仓库这类高风险操作，由人手动执行，不让 agent 代劳。

另外，每周我们会有一次“技能共建”时间，把上一周遇到的高频操作写成 skills 放进仓库。一开始很慢，但积累到二十来个 skills 之后，团队做需求的速度明显提升，因为很多重复工作都被标准化了。opencode 在这里的价值不只是“帮你写代码”，而是帮你把隐性经验显性化，变成团队资产。

5. 从终端走向界面：桌面版、VSCode 和 IDEA 插件

5.1 桌面版适合谁

虽然 opencode 本质是终端工具，但现在也有桌面版的形式，本质上是把 TUI 界面包装在一个独立图形窗口里。对一部分开发者来说，这比塞在终端里更好用，尤其是需要长时间盯着会话输出、或者同时开多个会话对比不同模型结果的时候。

用桌面版最大的好处是窗口管理更自由：左边是聊天和任务列表，右边可以看 diff 和文件变更，不需要在终端和编辑器之间来回切。不过它的底层还是同一个 opencode 核心，配置文件和命令行版本完全通用，不存在“桌面版功能比 CLI 少”的问题。我的建议是终端用户没必要专门换，但如果你习惯 GUI、或者给非技术同事演示，桌面版确实更友好。

5.2 VSCode 插件：编辑和对话无缝衔接

VSCode 插件让 opencode 的使用场景从“终端里发指令”变成了“编辑器里发指令”。搜索安装 opencode 插件后，左侧边栏会出现一个对话面板。你可以选中一段代码，直接右键发送给 opencode，让它解释、重构、写测试；也可以在对话里@引用当前打开的文件，让它基于文件内容回答问题。

我把这个场景用得最多的是“圈定范围”。在终端里让它改文件，它可能会自己猜要改哪里，但插件模式下，我选中需要改的函数或文件，指令就会变得精确很多。还有一个很实用的小技巧：在 VSCode 里让 opencode 读终端的报错日志，然后直接把修复方案贴回来，省掉了一大段人工复制描述的过程。插件本质上还是调用同一个模型和配置，所以不用担心两边的模型不一致。

5.3 IDEA 插件：Java 系开发者怎么跟 opencode 配合

JetBrains 系（IDEA、GoLand、PyCharm）现在也有 opencode 插件了。Java/Go 项目往往是多模块工程，结构比前端项目复杂，插件的作用主要体现在两点：一是可以直接让插件读取当前模块的上下文，不用在终端里手动解释模块结构；二是可以把 AI 会话和 IDE 的错误提示联动起来，比如把一个编译错误的 stack trace 发给 opencode，让它直接定位到相关类。

IDEA 插件装完后有个常见问题：如果插件找不到 opencode 命令，通常是因为 IDEA 的启动环境没有继承终端里的 PATH。解决办法是在插件设置里手动填 opencode 可执行文件的绝对路径。Windows 上尤其容易遇到这种情况，路径一般就是 npm 全局目录下的 opencode.exe，前面第 2 节已经讲过怎么查npm全局目录，这里填进去就行。

6. 真实场景复现：用 opencode + Playwright 定位前端 Bug

6.1 场景描述：为什么前端 Bug 那么难用 AI 排查

日常开发里有一类问题特别折腾：页面渲染出来的表现和预期不一致，但没有明显报错，打开控制台也只有一堆噪音。这类“前端交互 Bug”以前很难用 AI 排查，因为模型看不到页面，只能靠人描述，而人的描述往往不准确。

opencode 接入 Playwright MCP 之后，这个场景基本被解决了。Playwright 可以控制真实浏览器，opencode 通过 MCP 调用它，就能打开页面、点击、输入、截图、抓 console 日志，整个流程是模型自己操作的。这相当于给了 agent 一双眼睛，让它自己去看页面到底发生了什么。

6.2 一次完整的前端 Bug 排查过程

我先在项目根目录的 opencode.json 里接好 Playwright MCP，然后重启 opencode 会话。假设现在的问题是：移动端登录页在点击登录按钮后没有任何反应，也没有报错。

我会这样下指令：

先启动项目的 dev server，然后用 Playwright 打开移动端登录页。 帮我复现这个操作：输入一个测试账号和密码，点击登录按钮，然后把控制台日志、网络请求和页面截图都给我看一下。 最后分析为什么点击登录没有反应。

opencode 会先找到 dev server 启动命令，跑起来，再调 Playwright 打开对应端口页面，模拟点击。如果它足够顺利，会在几轮交互后告诉你：控制台没报错，但点击按钮时有一个 JavaScript 异常被 catch 掉了，或者请求发送失败但页面没有错误提示，或者按钮被某个元素遮挡所以点击事件根本没触发。

找到原因后，我会继续让它给出修复方案，再让它直接改代码并重新跑一次页面验证。这里有一个重要的操作原则：让它修复后必须自己复测，不要改完就说“好了”。模型写代码和验证代码是两种能力，显式要求“改完以后用 Playwright 重新跑一遍同样的流程”能避免大量“看起来修了、实际没修好”的假完成。

6.3 这个玩法的常见坑

第一，Playwright 会打开真实的浏览器窗口，在无图形界面的服务器上需要额外配置 headless 模式，默认打开真实窗口会把服务器卡死。第二，测试环境如果有验证码、短信登录这类环节，必须提前处理，要么 mock 掉，要么准备测试账号，否则每次复测都会卡在验证环节。第三，不要让 opencode 用生产环境账号去跑 Playwright，风险很大，有一次它差点在测试环境发了一笔真实的支付请求，从那以后我配置里就强制绑定了测试环境域名。第四，Playwright 启动浏览器会比较耗资源，尤其是同时开多个会话的时候，尽量一次只跑一个浏览器任务。

7. 高频问题与报错速查

7.1 一张表解决大部分上手问题

日志是我排查问题的第一入口，尤其是unexpected server error这类笼统报错。opencode 会在配置目录下保留日志文件，Windows 上一般在%USERPROFILE%\.config\opencode\log，Linux/macOS 在~/.config/opencode/log。看到报错不要急着重新安装，先把最后几十行日志打开看看，多半能直接找到是网络问题、API Key 问题还是模型服务商的问题。

7.2 最后分享一个我的使用习惯

工具选型这件事，没有绝对的最好，只有合不合适。opencode 目前是我用的最多的终端 Agent，并不是因为它每个方面都比 Claude Code 强，而是它把“模型自由”和“可配置性”放在第一位，这让它成了一个能跟着团队需求长期演进的底座。用了这段时间，我最大的体会是：不要把 agent 当成自动写代码的机器，要把 agent 当成一个需要你写清楚需求、给足上下文、事后认真 review 的协作对象。你越是把团队的知识、规范、踩坑记录沉淀成 AGENTS.md 和 skills，它给你的回报就越明显。希望你也能在项目里把它用起来，少踩几个我踩过的坑。