企业官网建设流程全解析

兄弟们，最近群里多了好多问 OpenCode 的。装倒是装得快，真正卡住的全是些细枝末节——不是提示“无法将 opencode 项识别为 cmdlet”，就是进去了不知道模型怎么接，要么就是运行半天报一个 unexpected server error。刚好我之前从安装到日常使用折腾了好几轮，踩了不少坑，这篇就当第二期食用指南，把大家问得最多的问题一次性串起来。

先说 OpenCode 是什么。它是一个跑在终端里的开源 AI 编程助手，名字里的 Code 很直白，核心就是帮你读项目、改代码、跑命令、修 bug。它和 Claude Code 这类工具最大的区别是：模型不是绑死的，你想接哪个模型服务、用什么样的模型，都可以自己配。所以很多开发者本身就把它当成默认 Agent 在工作流里用。

这篇内容适合谁？装了 OpenCode 还没跑通的人、从其他 Agent 转过来不知道怎么配置的人、以及想把它接入 VSCode/IDEA 甚至桌面端的人。我会尽量把“为什么这么做”也讲清楚，而不是只丢给你一堆命令。

1. 安装与启动：先把环境盘明白

1.1 为什么选 OpenCode，安装前要检查什么

OpenCode 是 SST 团队维护的开源项目，许可证很宽松，社区活跃度也不错。相比同类命令行 Agent，它最大的优势是配置透明：你能清楚地看到自己用的是哪个模型、什么参数、请求发到了哪里，而不是被封闭在某个厂商的生态里。

不过在安装之前，我建议先检查一下本机环境。OpenCode 的包是通过 Node.js 生态分发的，所以 Node 版本太老会直接装不上或者装完启动报错。我自己的习惯是先跑两条命令：

node -v npm -v

只要 Node 是 20 以上的 LTS 版本，大概率没问题。如果你用的是 Windows，还有一个很容易忽略的点：npm 的全局安装目录到底在哪里。很多人报“opencode 无法识别”其实就是因为全局 bin 目录没有进 PATH，这个我待会专门讲。

另外提醒一句，如果你以前装过其他命令行 Agent，建议先把它们的环境变量、全局 npm 包列表看一眼，避免 OpenCode 装好后启动时读到旧配置，到时候排查起来很头疼。

1.2 三种安装方式与常见环境问题

我推荐按场景选安装方式。

第一种，npm 全局安装，适合绝大多数开发环境。

npm install -g opencode-ai

安装包名是 opencode-ai，但命令名是 opencode，别搞混。装完先跑一下opencode --version，能输出版本号就说明基本没问题。

第二种，官方一键脚本。如果你不想让 Node 全局目录变得太乱，或者你在 Linux/macOS 上更习惯二进制方式，直接用官方安装脚本：

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

这种方式会把可执行文件放到用户目录下，不需要 sudo，也更好清理。

第三种，桌面版。OpenCode 官方还提供了桌面端安装包，不想碰命令行的朋友可以直接下载安装。桌面版本质还是同一套配置，所以后面讲的配置文件它全都认，只是交互方式从终端换成了图形界面。

安装成功后真正的劝退点来了。如果你在 Windows 的 PowerShell 里执行 opencode 报“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”，先别急着重装。用下面这条命令看看 npm 全局目录在哪：

npm prefix -g

然后把输出的目录下的 node_modules/.bin 或者对应的 bin 目录加到系统的 PATH 环境变量里。改完 PATH 后记得重新开一个终端窗口，因为旧窗口的环境变量不会自动刷新。

还要注意一个很容易踩的坑：不要为了加速 npm 安装乱改 registry。改坏了之后，装包会一直卡住或者装出一个半成品，OpenCode 启动时会报各种莫名其妙的错误。真要用镜像源，也请选公共 npm 镜像，装完再关掉，不要长期指向不稳定的地址。

1.3 第一次启动：进入 TUI 并确认模型链路

环境没问题后，直接在终端输入：

opencode

会进入一个全屏的 TUI 交互界面。第一次启动时它会引导你选择模型服务或者填写 API Key。如果你暂时不想进全屏界面，我更推荐先用一次性任务模式验证安装：

opencode run "用一句话介绍你自己"

能正常回复就说明安装和模型链路都通了。这一步非常关键，因为它把“安装问题”和“模型配置问题”在早期就切分开了。很多朋友一上来直接进 TUI 操作，结果发现无法对话，就误以为是 OpenCode 坏了，其实可能只是模型没配好。

2. 模型接入与配置：把模型路线彻底打通

2.1 Provider、模型、BASE_URL 的关系

OpenCode 本身不生产回答，它只是帮你调度模型。你可以把它理解成一个手机输入法，系统键盘是固定的，但输入法皮肤、词库、语音引擎都能换。OpenCode 把每次请求抽象成三样东西：Provider、模型 ID、BASE_URL。

BASE_URL 是模型服务的入口地址，API Key 是你的身份凭证，模型 ID 决定具体调用哪个模型。OpenCode 的整体配置其实就围绕这三者展开。

配置可以写在两个地方：

• 全局配置：~/.config/opencode/opencode.json
• 项目配置：项目根目录下的opencode.json

项目配置的优先级更高，这样你可以在不同项目里切换不同模型，而不用频繁改动全局配置。

配置结构很简单，核心是 provider 这段。一个最小的自定义 Provider 大概长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "custom-openai-compatible": { "npm": "@ai-sdk/openai-compatible", "name": "自定义模型服务", "options": { "baseURL": "https://api.example.com/v1", "apiKey": "{env:MY_API_KEY}" }, "models": { "main": { "name": "主模型" } } } }, "model": "custom-openai-compatible/main" }

这里的关键点是@ai-sdk/openai-compatible。OpenCode 底层用的是 Vercel AI SDK，它对 OpenAI 兼容协议的支持最省事。市面上绝大多数模型服务都提供了 OpenAI 兼容接口，所以你拿到一个服务的 baseURL 和 API Key 后，通常只需要改这两个字段就能接上。

{env:MY_API_KEY}这种写法是我强烈推荐的，不要在配置文件里硬编码 Key，否则你一不小心把项目传到公网仓库就泄露了。把 Key 放到环境变量里，既安全又方便多台机器同步配置。

2.2 免费模型与 ccswitch 的配合使用

很多人搜索“opencode 免费模型”和“opencode go 需要配合 ccswitch 等工具”，其实它们说的是同一个需求：OpenCode 不限制你用什么模型，有些公开平台会提供免费额度或限时赠送，你只要把对应的 API 配置填进去就能用。

但问题也随之而来：同时用好几个模型服务时，今天用 A，明天用 B，手改 baseURL 和 Key 很容易出错。ccswitch 就是干这个用的。它是一个模型配置切换工具，你可以把多套接口配置统一放在里面，切换时点一下，OpenCode 等工具就能读到对应的配置。

我自己用下来的感受是：ccswitch 的价值不在于省那几秒钟，而在于它把“模型切换”变成了一个确定性的操作，不用每次去翻配置文件，也不用担心改错格式。尤其当你同时在 OpenCode 和别的 Agent 工具之间切换时，一份配置多处使用，体验要顺滑得多。

要提醒的是，免费模型普遍存在不稳定、额度有限、偶尔下线的现象。今天还能用的接口，明天可能就返回 401 或者超时。这不是 OpenCode 的问题，而是上游服务变动。我建议把免费模型当成尝鲜和辅助，核心的、不能断的日常工作还是配一个稳定可用的量产模型。

2.3 配置文件推荐写法与参数解读

除了 Provider，配置文件里还有几个参数值得关注。

• model：默认模型，可以是自定义 Provider 下的模型 ID，也可以是 OpenCode 内置支持的模型。
• temperature：控制回答的随机性。写代码、改 bug 我习惯设低一点，比如 0.2 到 0.4，太高的温度容易让它“自由发挥”写出不靠谱的代码。
• system：系统提示词。你可以在这里写一些通用规则，比如“所有代码必须有注释”或者“不要修改锁文件”。
• autoupdate：控制 OpenCode 是否自动更新。如果你在公司内网或网络受限环境，我建议关掉，避免启动时卡在更新检查上。
• theme：TUI 主题，纯个人喜好，不影响功能。

如果你用的是 Maven 项目，还有一个很容易被忽略的点。有热搜词是“opencode mvn 配置”，实际上这不是 OpenCode 配置文件里的东西，而是你的 Java/Maven 环境变量问题。OpenCode 在帮你执行mvn test或mvn compile时，需要能找到JAVA_HOME和mvn命令。所以装 OpenCode 之前，先在终端里确认：

java -version mvn -version

如果这两条命令都能正常输出，那 OpenCode 调用 Maven 就没问题。反过来，IDEA 插件里遇到 Maven 相关报错，十有八九也是环境变量没传进去。

3. 实战集成：VSCode、IDEA 与桌面版

3.1 VSCode 插件：从终端走进编辑器

OpenCode 虽然出生在终端，但日常写代码时大家还是更习惯待在编辑器里。VSCode 插件的好处是，它和全局配置完全打通，你在终端里配好的模型、Skills、AGENTS.md，插件都能直接复用。

安装方式很简单：在 VSCode 扩展市场搜“OpenCode”，装好后左侧会多出对话面板。你可以直接选中一段代码，让它解释、重构或者补测试。它给出的修改会以 diff 形式呈现，你自己确认后再 apply，而不是一言不合直接改文件。

用下来我最喜欢的是“选代码提问”这个场景。比如从一个大类里选中一个方法，问问它这段逻辑有没有边界问题，它给出的答案通常比在终端里描述半天上下文要准确得多，因为上下文就是当前文件本身。

有个细节需要注意：VSCode 插件安装后要确保它能找到opencode可执行文件。如果你在终端里明明能跑，插件却报找不到，多半是插件启动时的 PATH 和终端不一致。直接在插件配置里把 opencode 的绝对路径填上最省事。

3.2 IDEA 插件：Java/Kotlin 项目的舒适圈

如果你是 Java 开发者，JetBrains IDEA 也有对应的 OpenCode 插件，安装后在右侧工具窗口就能直接对话。IDEA 插件和 VSCode 插件的使用逻辑一样，但有一个非常典型的问题：IDEA 本身是从桌面图标启动的，它的 PATH 环境变量可能不包含你终端里配置的那些路径。

所以你在 IDEA 插件里配 OpenCode 时，不要想当然地以为它能自动找到命令。我建议在插件设置里手动指定 opencode 可执行文件的绝对路径，比如 Windows 下的C:\Users\你的用户名\AppData\Roaming\npm\opencode.cmd，或者 mac 下的/usr/local/bin/opencode。

另外，Maven 项目在 IDEA 插件中跑构建时，如果出现“mvn 命令找不到”或者“JAVA_HOME 找不到”，不要怪 OpenCode，看看 IDEA 本身能不能正常执行 Maven。这里有个很实用的排查方法：在 OpenCode 对话里直接让它运行mvn -version，看返回的结果，如果这一步就不通过，那问题出在环境变量，而不是 Agent 本身。

3.3 桌面版与 CLI 工作流的取舍

桌面版适合刚入门、不想记命令的人。它能用图形界面完成模型配置、对话和文件修改确认，体验比较友好。但我个人的观点是：如果你已经是一个会写代码的人，CLI + TUI 的收益其实更高。原因是 CLI 可以编进脚本，可以做自动化，可以在任意的项目目录里快速启动，而桌面版更适合点一点、看一看的轻量使用。

日常我比较推荐用opencode run做一次性任务，比如：

opencode run "看一下 src 目录下的代码，找出没有错误处理的函数"

这种用法比每次都开全屏 TUI 更快，也方便你把它接进自己的项目脚本里。桌面版、IDE 插件、CLI 三者可以共存，底层共用同一套配置，所以不用担心冲突。我的建议是：终端党直接用 CLI，IDE 重度用户装插件，完全不想碰命令行的用桌面版。

4. Skills 与 Memory：从“能用”到“好用”

4.1 AGENTS.md：给 OpenCode 一份项目说明书

很多人的 OpenCode 装完之后只会简单问答，但真正好用的 Agent 应该知道你的项目是怎么组织的。AGENTS.md 就是干这个的。

你可以把它理解成给每个新入职的工程师准备的交接文档。模型本身没有记忆，每次对话它都是“新人”，而 AGENTS.md 能让它快速了解项目的技术栈、目录结构、构建命令、编码规范。

一个典型的 AGENTS.md 长这样：

# 项目说明 这是一个基于 Vue 3 + TypeScript 的前端项目，包管理工具使用 pnpm。 ## 常用命令 - 安装依赖：pnpm install - 启动开发服务：pnpm dev - 运行测试：pnpm test ## 代码规范 - 组件文件统一放在 src/components 下 - 状态管理使用 Pinia - 不要修改锁文件，除非升级依赖 - 所有对外接口必须有类型定义 ## 注意事项 - 测试环境接口地址在 .env.development 中配置 - 修改后端接口时需要同步更新 src/api 下的文件

写完之后放到项目根目录，OpenCode 在项目里启动时会自动读取它。全局规则可以放在~/.config/opencode/AGENTS.md，这样所有项目都生效；项目级规则就放项目根目录，只对当前项目生效。

我自己实测下来，写完 AGENTS.md 之后，OpenCode 生成的代码风格明显更贴近项目实际，减少了很多来回纠正的次数。这比你在每次对话里重复说明命令要高效得多。

4.2 Skills 机制：让 Agent 具备专项技能

OpenCode 较新的版本支持 Skills 机制。简单来说，你可以把一组提示词和脚本打包成一个“技能”，比如代码审查技能、Docker 运维技能、日志排查技能。模型在遇到对应场景时，会主动调用这些技能，而不是每次从零开始理解你的需求。

这种思路和 oh-my-claudecode、superpowers 这些社区项目是相通的。它们本质上都是把大量实用的提示词和技能目录整理好，让你复制到自己的环境里直接用。OpenCode 2.0 之后，这种“技能包”的使用越来越顺手，很多原本在 Claude Code 里流行的玩法都能平移到 OpenCode 里。

如果你下载了某个技能包，注意看它的目录结构，通常里面会带 skill 描述文件和相关的脚本。把这些内容放到项目根目录的 skills 目录，或者放到全局配置对应的 skills 目录，重启 OpenCode 后就能看到技能列表。我自己更倾向于先用原生的 AGENTS.md 把项目规范喂给模型，再按需引入技能包，避免一上来就装一堆技能反而不知道该用哪个。

4.3 用 Playwright 做前端 Bug 自动修复

“opencode playwright 怎么测试前端 bug”这个问题问得非常多，我展开说一下。

在很多前端项目里，bug 并不是靠看代码就能定位的，尤其是复杂的交互问题，需要真实打开浏览器复现。OpenCode 配合 Playwright 技能，可以自动启动浏览器、访问本地开发地址、点击元素、抓取控制台报错和网络请求，然后把完整现场信息交回给模型分析。

操作流程大概是这样的：

1. 让 OpenCode 用 Playwright 打开本地开发服务，比如http://localhost:5173。
2. 让它执行你描述的操作，比如“点击提交按钮”。
3. 它会返回页面截图、控制台报错和关键网络请求信息。
4. 模型基于这些信息分析问题根源，再回到代码里给出修复方案。

一个比较实用的 prompt 示例：

opencode run "用 Playwright 打开 http://localhost:5173，点击登录按钮，如果出现报错或者页面无法跳转，把控制台错误和页面截图发给我，然后定位原因并给出修复建议"

需要注意的是，用这个功能前你得确保本地已经装好 Playwright 和对应浏览器。如果项目里已经集成了 Playwright 测试框架，那 OpenCode 会直接复用现有环境，体验更好。

这条链路是我目前觉得 OpenCode 最有价值的使用方式：它不只是“帮你写一段代码”，而是“帮你复现问题、分析问题、再给出修复方案”。对于复杂前端 bug，这一套流程能把排查时间从几小时压缩到几分钟。

5. 常见问题与避坑速查

5.1 Windows 命令无法识别怎么办

这个问题的出现频率最高，尤其是在 Windows + PowerShell 环境。报错信息一般是：

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

我直接给一个排查顺序：

如果 PATH 已经配好，但还是不行，可以在终端里输入Get-Command opencode看看系统到底找没找到这个命令。找到的话它会显示完整路径，找不到就继续排查 PATH。

5.2 unexpected server error 的排查思路

这个报错的完整提示通常是：

error: unexpected server error. check server logs

很多人以为这是安装问题，其实不是。出现这种报错，OpenCode 本身已经启动成功了，但它向后端模型服务发请求时失败了。常见原因包括：

• API Key 填错了或者已经失效。
• BASE_URL 地址不可达，或者路径写错。
• 模型 ID 在当前服务下不存在。
• 免费模型额度耗尽或者服务已经下线。
• 网络超时，请求迟迟没有响应。

排查思路是先在项目目录里跑一条最简单的命令：

opencode run "你好"

如果连最简单的对话都报错，那就是模型配置问题。换一个已知可用的模型服务测试，或者打开 OpenCode 的日志目录，通常位于用户目录下的~/.local/share/opencode/log，看具体的错误信息。如果你用的是免费模型，刚看到这个报错第一反应应该是去查上游服务状态，而不是反复重装 OpenCode。网上经常有人问“hy3-free 下线了吗”这种问题，本质上就是因为免费模型的上线、下线、额度耗尽都会让用户产生“是不是我装错了”的错觉。

5.3 OpenCode、Codex、Claude Code 怎么选

这个问题基本每周都有人问。我根据自己的使用感受做个横向对比：

如果你喜欢折腾、想让 Agent 按自己的规则来，OpenCode 是最合适的。如果你只想开箱即用，并且主要工作在 GitHub 上进行，Codex 会更顺手。如果你对写码质量要求极高，也不介意模型绑定，Claude Code 的体验确实顶。

老板问“Opencode 是哪家公司的”，简单说一句就是 SST 团队的开源项目，不是某个大厂闭门造的车。它也正因为开源，才让插件、技能包、模型接入这些事情玩得这么花。

最后分享一个我实际工作中的小体会：OpenCode 真正让我留下来的是opencode run加上 AGENTS.md 和 Playwright 这条链路。它改变了我处理 bug 的方式——以前是我自己开浏览器、抓报错、猜根因，现在是我把问题描述清楚，Agent 带着工具先去收集现场，再回到代码里给方案。装好之后别急着折腾一堆技能，先把最小链路跑通：安装、配模型、写 AGENTS.md、执行一次真实任务。这条路走顺了，后面所有扩展都是锦上添花。