企业官网建设流程全解析

1. 从 Cursor 和 Claude Code 之间挤出来的位置：opencode 解决了我哪两个痛点

我平时的工作流长期是"编辑器写代码 + 终端跑 Agent"两条腿走路。写前端用 Cursor，写 Java 后端用 IDEA，跑代码审查和简单重构切到 Claude Code，后来又因为团队需要试过 Codex。工具很多，但问题也很明显：每个 Agent 都有自己的一套配置方式，模型供应商锁得死，会话记录散落在各自的目录里，切一次模型等于重新交代一遍项目背景。

真正让我开始认真用 opencode，是因为两个很具体的痛点。第一个痛点是终端 Agent 的模型切换。Claude Code 默认吃 Anthropic 的 key，Codex 默认吃 OpenAI 的 key，如果项目里既有 ChatGPT 的账号又有 Claude 的账号，或者想临时用一个便宜模型跑批量小任务，就得在不同的命令行工具之间来回跳，非常累。opencode 的做法是把它当成一个统一的终端入口，底层模型可以随时换，会话也能在换模型之后继续，不用每次从零开始。

第二个痛点是编辑器和终端的状态割裂。Cursor 里跑起来的 AI 上下文，到终端里就断了；终端里调好的 Agent，也没办法直接拿到编辑器里正在看的文件选区。opencode 的做法是保留了终端 TUI 作为核心，同时提供 VS Code 插件、JetBrains 插件和桌面版，这几个入口共享同一份会话数据和配置。也就是说，我在命令行里跑到一半的任务，可以到插件侧边栏里继续盯着看，不用担心状态丢失。

适合谁用？如果你平时主力是 Cursor、Copilot 这类编辑器 AI，但是又需要偶尔在终端里处理批量重构、脚本生成、多文件改动，那 opencode 值得试。如果你已经在用 Claude Code 或 Codex，觉得配置分散、模型绑得太死，那它正好能把这些入口收敛到一起。下面我从安装讲起，把 Windows 环境下最容易踩的坑先清理掉，然后依次说模型接入、插件配合、以及真正把它用进日常项目维护的方法。

2. 安装 opencode 的正确姿势与 Windows 上那三个坑

有人第一次接触 opencode 就卡在安装上，尤其 Windows 用户，报错的第一句话通常是"opencode : 无法将‘opencode‘项识别为 cmdlet、函数、脚本文件或可运行程序的名称"。这句话看着唬人，实际八成不是 opencode 的问题，是系统 PATH 没配对。下面把安装和排查一次性说清楚。

2.1 选哪种安装方式

如果你机器上有 Node.js 环境（前端项目大概率有），最省事的方式是全局安装命令行包：

npm install -g opencode-ai

装完直接在终端里敲opencode --version，能输出版本号就说明核心可用。

如果你不想依赖 Node，opencode 也提供官方安装脚本，macOS 和 Linux 上可以一句命令拉起来：

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

Windows 下我试过两种方式，一种是用 npm 装，另一种是去 GitHub Releases 页面下载对应平台的压缩包，解压到C:\opencode之类的目录，然后把该目录手动加进系统 PATH。如果你之前没配过环境变量，建议先走 npm 路径，它会自动把可执行文件放到 npm 的全局 bin 目录里，省去手动配置。

2.2 "无法识别为 cmdlet"的真正原因

这个报错出现时，先做两步确认。第一步，检查 npm 全局 bin 目录到底在哪：

npm prefix -g

如果输出的是C:\Users\你的用户名\AppData\Roaming\npm，那么opencode命令大概率是存在那个目录下的。第二步，确认这个目录加进系统 PATH 没有。Windows 11 的 PATH 配置界面里有一个很常见的坑：npm命令是能用的，但 npm 全局目录不在 PATH 里，因为你可能不是用官方安装包装的 Node，而是用 nvm-windows 装的。nvm 切换 Node 版本时，npm 全局包目录会跟着变动，有时候系统环境变量还残留着旧路径，或者干脆没把当前版本对应的全局目录同步上去。

修复方法很简单：在 PowerShell 里跑一行，把当前 npm 全局目录临时加进 PATH，验证问题：

$env:Path += ";$(npm prefix -g)" opencode --version

能跑通就说明是永久 PATH 配置问题，去系统环境变量里把%APPDATA%\npm加上，然后重开终端。这里要强调一点：改完环境变量必须完全关闭终端窗口再重新打开，不是新开一个标签页就能刷新的，很多人在这里反复踩坑。

2.3 首次启动的缓存目录和权限问题

opencode 首次启动会在用户目录下创建配置和数据目录，Linux 和 macOS 是~/.config/opencode，Windows 上对应%USERPROFILE%\.config\opencode。如果这台机器的用户目录权限被软件改过（比如装过某些优化工具），或者你是在公司域环境里跑，写配置文件时可能报权限错误。

解决方式是别把配置丢在需要管理员权限的地方，直接确认用户目录本身可写即可。如果以前用别的方式装过一次但中途失败，目录里可能留了半份配置文件，此时建议把整个.config/opencode目录备份后删掉，重新初始化一次。

2.4 升级不用反复重装

opencode 升级比较频繁，命令行里经常能看到 Upgrade available 的提示。npm 方式装的直接跑：

npm update -g opencode-ai

二进制方式装的看提示去下载新版即可。测试版本跑得勤的话，建议跟主版本走，热词里提到的"opencode 2.0"就是某个大版本的升级，2.x 之后配置目录结构和插件机制变化不小，升级前先看一眼官方更新日志，避免旧的 skills 配置失效。

3. 把模型接进来：API Key、免费模型和 CC Switch 的配合逻辑

opencode 默认不会绑死某一家模型。它的设计逻辑很像一个"终端侧的模型路由器"：你可以配 Anthropic、OpenAI、Gemini、DeepSeek 甚至本地 Ollama，每次在会话里临时切换。这一步解决了多账号多模型的人最大的痛点——不用再为每一个模型装一个独立的 Agent 工具。

3.1 最直接的接入方式

如果你只有一家模型的 API Key，直接在终端跑：

opencode auth login

它会列出支持的模型供应商，选一个，按提示粘贴 API Key 就行。Key 会保存在本地配置文件中，不会塞进项目代码里。多模型场景下，你也可以直接设置环境变量，比如：

• ANTHROPIC_API_KEY对应 Claude 系列
• OPENAI_API_KEY对应 GPT 系列
• GEMINI_API_KEY对应 Gemini 系列
• DEEPSEEK_API_KEY对应 DeepSeek

setx 在 Windows 下的写法是setx ANTHROPIC_API_KEY "sk-xxx"，设置完照样要重开终端才能生效，这一点和前面 PATH 一样，属于环境变量通用规则。

3.2 CC Switch 到底在配什么

很多人在网上搜"opencode 和 CC Switch 怎么配合"，搜半天看不懂。我用自己的话解释一下：CC Switch 是一个切换工具，它管理的不是 opencode 本身，而是模型供应商的凭据和 API 地址。举个例子，你可能有一个专门跑 Claude 的账号，还有一个走代理网关或者 API 聚合平台的账号，手动改环境变量很麻烦，CC Switch 做的事情就是帮你一键切换，切换完把环境变量写到当前会话或持久化配置里。

opencode 读取模型配置时走的是标准环境变量和配置文件，所以 CC Switch 切完，opencode 这边立刻就能感知到。热词里那句"opencode go 需要配合 cc switch 等工具"，我理解就是指这种场景：opencode 本身不帮你管理多个第三方网关账号，你需要一个外部工具把这些账号管起来，CC Switch 是其中用得比较多的一种。

实际配置时注意一点：CC Switch 和 opencode 不要同时管理同一个环境变量，否则会出现"我明明切到 A 模型了，opencode 里还是用的 B 模型"的情况。建议固定分工——已经用 CC Switch 管理 key 的话，opencode 这边就不要再单独去配环境变量，让它继承系统的值。

3.3 免费模型的真相

"opencode 免费模型"是搜索量很大的关键词，我说点实在的。各家厂商的免费额度、社区维护的开放模型通道、本地模型，确实都能接进 opencode，但免费通道普遍存在几个问题：请求限流厉害、上下文窗口被压缩、响应速度不稳定、隔三差五服务下线。网上说的某个免费通道突然失效，我猜指的就是这种第三方免费服务的不稳定性。

我的建议是：玩一玩、跑个小脚本，免费模型完全够用；但如果你要拿它接手开发项目或者处理真实业务代码，别把稳定性押在免费通道上。本地 Ollama 是不错的兜底，跑ollama pull qwen2.5-coder:7b这类参数小的代码模型，离线也能用，至少不会因为上游服务挂了而中断。缺点是 7B 规模的模型写复杂业务代码时理解能力有限，做重活还是要上云端强模型。

3.4 会话内切模型的实际体验

opencode 会话里可以直接用/model命令切换模型，比如我把一个需求从 GPT 切到 Claude，上下文还会保留，只是后续推理换模型。这意味着你可以把"快模型"和"强模型"组合起来用：简单的前端样式调整用快模型，遇到底层逻辑重构切强模型。这点比 Cursor 里面切模型还要顺手，因为终端会话里没有编辑器上下文同步的成本。

4. 从纯终端到全家桶：桌面版、VS Code 插件、IDEA 插件各自怎么用

opencode 最让我舒服的一点，是它没有强行把用户按在一个入口里。日常开发你有三种使用形态：纯终端 TUI、桌面版、编辑器插件。三者的关系不是三个独立产品，而是同一个 Agent 核心的不同外壳。

4.1 终端版是核心

终端里跑opencode会进入一个交互式 TUI，底部是输入框，左侧是会话文件列表，右侧是当前会话内容。第一次进入新项目时，建议先跑/init命令，它会阅读项目结构、构建方式、框架类型，自动生成一份AGENTS.md。这份文件是给 AI 看的项目说明书，后面所有模型在解析项目时都会参考它，相当于给 Agent 立规矩。

终端版最值钱的能力是处理大规模跨文件改动。比如"把这个模块里所有直接调用旧 API 的地方改成走新的 Service 层"，它能自己搜索、改写、检查。在这个场景下，编辑器的内联补全反而没有终端 Agent 方便，因为改动范围不是一行两行，而是一批文件。

4.2 VS Code 插件：前端开发的顺手形态

VS Code 插件装好后，侧边栏会多出一个 opencode 面板。它有几种用法：选中代码右键发送到对话、在面板里直接提问、生成的 diff 可以逐个文件审查后应用。

前端项目里我最常用它的"选区上下文"功能——在组件文件里框住一段 JSX，让 Agent 基于这段代码改样式或补逻辑，它不会跑偏到别的文件。如果你同时开着终端版和插件版，两个入口看到的会话是同一份，这个机制比 Cursor 的"对话只活在编辑器里"要灵活。

4.3 IntelliJ IDEA 插件：Java 后端的接驳方式

IDEA 插件的入口逻辑和 VS Code 类似，但实际使用时要注意 Maven 环境。opencode 在 IDEA 里执行 Java 项目构建时，需要能正确找到JAVA_HOME和 Maven 命令。如果你平时在 IDEA 里能跑mvn compile，不代表命令行里也能跑，因为 IDEA 内置的 Maven 不一定映射到系统 PATH。

解决办法是统一命令行环境：确保在终端里敲mvn -v有输出、echo $env:JAVA_HOME能看到 JDK 路径。opencode 插件继承的是启动 IDEA 时的环境变量，所以如果改了 JAVA_HOME，必须完全退出 IDEA 再重新打开，光重启窗口没用。热词里提到的"opencode mvn 配置"，十有八九就是卡在这个环节。

4.4 桌面版：不想开终端的场景

桌面版适合那些"只是想快速问个问题、不想进终端、也不想打开编辑器"的时刻。它和终端版共用同一个会话库，你在桌面版里起的会话，终端里也能继续。我个人的使用习惯是：写代码时用编辑器和终端，到了走查代码、整理思路的阶段会切到桌面版，把整个项目背景重新加载一遍再问整体性问题。

四个入口不必全装，按你的实际项目构成选。前端 TS 项目可以只用终端版 + VS Code 插件；Java 后端项目管理 IDEA 插件；偶尔移动办公的人桌面版更方便。装多了不会冲突，因为配置和会话文件是共享的，只是别在多个入口同时开同一个会话编辑，那可能出现文件锁冲突。

5. 让它真正接手开发项目：AGENTS.md、memory、skills 和一条完整实战流程

工具链搭好之后，真正决定 opencode 好不好用的是你怎么"教"它。很多人装完就开怼需求，结果模型乱猜一气，问题不在模型，在于没有给足项目上下文。opencode 提供的三样东西——AGENTS.md、memory、skills——就是用来解决这个问题的。

5.1 用/init把项目底细先告诉 Agent

我接手项目的第一件事永远是/init。这个命令会扫描项目，生成一份 AGENTS.md，里面通常包括：

• 项目是什么、用什么语言和主要框架
• 构建和测试命令是什么
• 代码结构的大致说明
• 项目特有的约定

生成之后我会打开手动改一遍，把一些只有在这个项目里才成立的东西加进去。比如某个后端项目里所有的数据库迁移脚本不能自动执行，必须人工确认；某个前端仓库里样式必须走 design token 不能硬编码颜色。这些约定写进 AGENTS.md 之后，Agent 每次操作都会先读一遍，比你在对话里反复强调效果好得多。

5.2 memory：把重复交代变成肌肉记忆

如果多个项目都共用一些规则，比如"提交信息必须用 conventional commit 格式""公共代码禁止引入 lodash""测试文件放在__tests__目录"，你可以把这些存进 opencode 的 memory。之后每次会话启动时，模型会自动带上这些全局偏好。

memory 是跨项目的，适合长期稳定不变的规则；AGENTS.md 是单项目的，适合跟特定仓库绑定的信息。两者不要混用。我自己吃过亏：把某个项目的路径信息写进 memory，结果别的项目里模型看着这些路径以为实际存在，浪费了不少时间。

5.3 skills：给 Agent 装一个"技能包"

skills 有点像给 Agent 加插件。社区里有人维护了一些常用技能包，有叫 superpowers 的，我理解它的思路是把一些高频工程动作封装成规范的技能，比如"写单元测试""做代码审查""补全文档"。装上之后，Agent 遇到这类任务会更规范，不会东一榔头西一棒子。

你也可以自己定义一个 skill。举一个实际例子：我写了一个最简单的 skill，内容是"执行 Java 项目构建时，先用mvn -q -DskipTests compile快速验证编译，编译通过后再跑相关测试，失败时不要立刻改代码，先把完整报错贴出来"。这个 skill 不复杂，但显著减少了模型在 Java 项目里瞎试的次数。定义好之后，我只要在会话里说"走一遍技能流程"，它就会按这个规范来。

5.4 接手一个陌生项目的完整链路

我前阵子接手一个同事留下的老项目，Spring Boot + Vue 前后端分离。我是这么用 opencode 处理的：

第一步，进项目根目录跑opencode，然后/init生成 AGENTS.md，重点看它识别出来的构建命令是否正确。如果项目用了 Maven 多模块结构，我会手工在 AGENTS.md 里写明根 POM 位置和常用模块路径，否则模型经常找错 build 目录。

第二步，用自然语言让它"读一遍代码结构，输出项目模块划分和核心业务链路，不要改任何文件"。这个任务相当于给模型做了一次"项目预习"，它输出的结构图虽然不一定 100% 准确，但能让我快速建立地图。

第三步，开始改 bug。我给它指了一个具体的报错现象，它自己定位到某个 Service 实现类，改完以后我要求它运行mvn -pl xxx -Dtest=xxxTest test验证。这个过程中我从不让它直接跑整个项目的全部测试，因为老项目全量测试动辄十几分钟，反馈链路太长，它容易在中途失去上下文。

第四步，全部改完以后，让它按 git 差异重新过一遍自己的改动，输出一份"改了哪些文件、动了哪些逻辑、影响哪些方法"的变更说明。这个习惯帮我堵住了好几次它偷偷改掉无关代码的情况。

5.5 用 Playwright 实测前端 bug

opencode 接入 Playwright 的用法很直接——你描述一个前端 bug，让 Agent 写一段 Playwright 脚本去真实浏览器里复现，再根据截图和 DOM 状态去定位原因。因为 opencode 的模型能自己改代码、执行命令、看终端输出，所以整个闭环可以全部在 Agent 内部完成。

我碰到过一个案例：某个页面在窗口宽度小于 768px 时，弹窗里的按钮溢出了。我跟 opencode 说"复现这个 bug，并找到根因"，它先用 Playwright 写了一个脚本，设置 viewport 为 375px，打开页面，点击触发弹窗，截图。看到截图上按钮确实超出边界后，它去查了对应组件的 CSS，发现弹窗用了固定宽度min-width: 600px，没有做响应式处理。

这个过程里最重要的不是它能写出那个 Playwright 脚本，而是它会根据截图反馈持续修正自己的假设。如果第一次脚本打开的是错误页面，它会看你给的提示，重新跳转，而不是死磕一个错误的定位器。这种"真实浏览器验证 + 代码修改"的闭环，比让模型干猜 CSS 问题靠谱得多。

6. 维护期最常碰到的五个错：从 cmdlet 报错到 unexpected server error

工具用得久了，问题基本集中在几个固定场景。我把自己踩过的坑集中列一下，很多人搜"opencode server error""opencode 无法识别"其实都是下面这些情况。

6.1 既有 cmdlet 报错的第二个变种

前面说的 npm 全局目录 PATH 问题是主因，还有一个分支场景：你换了终端程序。比如 Windows Terminal 里正常，但切到老的 conhost 或某些 IDE 内置终端又报无法识别。原因是 IDE 内置终端启动时读取的环境变量来自 IDE，而 IDE 可能是在 PATH 更新前启动的。解决方式是把 IDE 整个退出重开，而不是在 IDE 里重新加载窗口。

另外一个细节：如果你用 scoop 或 winget 装过不同的 Node 版本，PATH 里可能出现多条 npm 路径，opencode命令指向的还是旧包里残留的旧版本二进制。这种情况建议npm ls -g --depth=0看看全局装了什么，把旧版本的 opencode 卸掉，只保留一个来源。

6.2 unexpected server error. check server logs 的排查链路

这个报错是很多搜索记录的源头。opencode error: unexpected server error. check server logs的常见触发原因有三个。

第一个是本地服务没起来。opencode 的终端 TUI 依赖一个本地的服务进程，如果你用了代理类软件或系统代理配置不干净，它绑定的本地端口可能被抢占。排查办法是先看这个端口监听是否正常，或者直接退出重新执行opencode，让它重新初始化服务。

第二个是模型上游返回异常。有时候模型网关超时、返回了格式错误的数据，opencode 会把上游错误包装成这个通用提示。此时把模型切到另一个厂商的模型再请求一次，如果正常，基本可以断定是上游问题。

第三个是上下文过长。当会话文件过大、携带了太多历史消息，模型接口出错的概率会明显上升。此时用/new另起一个新会话，把关键背景重新粘一遍，报错往往就消失了。这个处理方式比来回重试更有效。

6.3 模型没配置时为什么表现得像"启动失败"

opencode启动时如果没有任何可用模型，界面可能会卡在初始化状态，或者看起来像"程序没反应"。很多人这时候以为是安装问题，重装了好几遍。正确做法是先确认你的环境变量有没有被当前终端继承：

echo $env:ANTHROPIC_API_KEY

如果输出为空，说明 Key 没进环境变量，或设置完没重开终端。在配置好 Key 之前，任何排查安装的动作都没有意义。

6.4 会话文件被占用导致上下文加载失败

opencode 的会话数据以文件形式存在本地，如果你同时开了桌面版和终端版，又恰好打开同一个会话，可能出现一个入口写入、另一个入口读取失败的情况。现象是对话历史莫名其妙少了，或者发送消息后一直转圈。这不是模型问题，关掉多余的入口，重新进入就好。我的习惯是同一时间只保留一个交互入口，其他入口保持关闭。

6.5 Windows 中文路径的隐藏问题

如果项目路径包含中文或空格，比如D:\项目\电商系统\backend，有概率出现配置文件找不到或者构建命令执行失败。原因在于某些子进程处理路径时编码不一致。不是所有机器都会触发，但如果你遇到奇怪的文件读取异常，可以先试试把项目挪到纯英文路径下看是否恢复。我后来固定把所有工作仓库统一放到D:\workspace下，路径全部小写英文加连字符，这类问题再没出现过。

6.6 我目前固定下来的一套组合

每次新机器装 opencode，我都是这套流程：Node 环境走 nvm 管理，npm i -g opencode-ai安装，CC Switch 管模型钥匙，Windows 上用纯英文路径建项目目录，进入项目先/init生成 AGENTS.md，然后把团队的公共约定写进 memory。这套组合看起来平淡，但踩完上面那些坑以后，你会发现稳定比花哨重要得多。真遇到模型答非所问的时候，我一般先怀疑上下文配得不对，再怀疑模型本身，这个顺序能省下不少排查时间。