企业官网建设流程全解析

这一个月我基本把日常开发工作流从IDE侧边栏搬到了一个终端程序里，连带着把好几个项目的维护方式都改成了“先开opencode，再谈其他”。这个程序叫opencode，一个开源的终端AI编程助手。它和传统AI插件最大的区别在于：不是等着你提问然后贴一段代码，而是能自己翻代码、跨文件修改、执行命令、开浏览器验证结果。这篇东西不打算复读官方文档，我会以实际跑了几个月的用户身份，把安装、模型接入、配置、IDE配合、排错这些环节里真正值得注意的东西讲完，给想上手opencode但又在各种碎片信息里无从下手的人一条可复现的路径。

1. opencode不是又一个聊天窗口：先搞懂它的定位

1.1 它和“IDE里挂着AI侧边栏”的本质区别

如果你用过插件型的AI助手，你大概熟悉这个流程：选中一段代码，问它“这里怎么优化”，它给一段答案，你手动粘贴，再跑一下测试，哦豁报错了，再复制报错回去问它。这个流程本质上还是“搜索引擎式的问答”，你仍然是那个把上下文从一个窗口搬到另一个窗口的人。

opencode这类agent型工具换了一个思路。你在终端里给它一个目标，比如“把登录接口的超时时间改成可配置，并更新所有调用方”，它会自己去读代码库、定位调用位置、修改文件、运行测试，然后把改动给你看。你不再需要手把手地把每个文件内容喂给它，它自己就是那个“搬运上下文”的人。

这种差异在项目稍微大一点之后会非常明显。一个300个文件的中型项目，AI侧边栏助手往往只能理解你贴给它的几个文件，而opencode能把整个仓库的目录结构、类型定义、调用关系当作背景知识来使用。它不是聊天窗口，是一个在终端里运行的“实习生”——你需要给它指令，而不是替它做所有事。

1.2 opencode、Claude Code、Codex CLI、PI，主流agent怎么选

这个问题几乎是所有想入坑终端agent的人都会遇到的。我把几个主流工具按自己的使用体验做了张表，供参考：

这张表的结论不是“opencode最好”，而是“opencode给你的控制力最强”。配置是一个JSON文件，provider可以随便填，任何兼容OpenAI协议的服务都能接进去。Claude Code体验很顺，但你能动的旋钮没那么多。Codex CLI很好，但它的行为风格更“保守”，更适合偏探索式的交互。PI太轻，接不了我后面要说的那些复杂工作流。

1.3 我最终选择opencode的三个理由

第一，开源。这意味着配置格式、行为逻辑、更新节奏都是可预期的，我的配置可以放进Git仓库管理，换电脑几分钟恢复环境。第二，兼容层做得干净。它不绑定某一家模型，我可以根据任务切换不同的模型供应商，便宜模型用来做简单重构，强模型用来做复杂架构分析。第三，skills和AGENTS.md这套机制让我能把团队的工作规范沉淀成文件，任何新同事装好opencode后，进入项目就能获得和我一样的“代理能力”，而不是靠口头传递。

2. 安装与第一条报错：把“cmdlet”问题一次说透

2.1 跨平台安装的几种方式

opencode的安装方式比较多，官方提供了可复现的安装脚本、Homebrew、npm和直接下载二进制几种路径。

# macOS 使用 Homebrew brew install sst/tap/opencode # Linux/macOS 使用官方脚本 curl -fsSL https://opencode.ai/install | bash # 已有 Node.js 环境 npm install -g opencode-ai

Windows环境下通常两种做法：一是直接下载官方发布页里的exe可执行文件，放进一个已经加入PATH的目录；二是用scoop安装。如果你平时在Windows上用WSL开发，我更建议直接在WSL里装Linux版，因为opencode的配置文件路径和日志行为在Linux下更规整，后面排查问题会省事很多。

安装完成后，终端里先跑一条命令确认版本：

opencode --version

看到版本号输出，说明安装成功了。如果这一步就报了下面那个经典的错，那正好进入排查环节。

2.2 报错“无法将opencode项识别为cmdlet”的完整排查链路

这个报错在Windows PowerShell下太常见了：

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

第一次看到这个报错的人很容易慌，以为安装失败了。其实这句话翻译过来就是：PowerShell在当前PATH环境变量的所有目录里都找不到一个叫opencode的可执行文件。

按照这个顺序排查，基本能找到问题：

1. 确认可执行文件到底装到哪里。如果你用npm装的，执行npm ls -g opencode-ai --depth=0，看它实际装到了哪个目录。如果是下载的exe，看它下载到了哪里。
2. 检查那个目录是否在PATH里。执行echo $env:Path查看当前PATH。你会发现npm的全局bin目录（一般是%APPDATA%\npm）可能不在里面。
3. 如果PATH里确实没有，把对应目录加进用户环境变量。PowerShell里执行：

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:APPDATA\npm", "User")

1. 加完之后记得新开一个终端窗口再试。PATH是启动进程时读取的，已经打开的窗口不会自动刷新。
2. 如果你用的是scoop，问题大概率出在scoop shim目录（一般是%USERPROFILE%\scoop\shims）没进PATH。

这个报错本身不复杂，但它提醒了我一个更通用的经验：终端工具的“安装失败”里，大约有一半是环境变量问题，只有另一半才是真正的安装损坏。遇到任何命令行工具找不到的问题，先查PATH，不要急着卸载重装。

2.3 2.0版本的配置迁移与升级注意点

opencode的迭代速度很快，我遇到过几次跨小版本的配置不兼容。印象比较深的是从1.x升到2.0之后，原本写在配置文件里的某些CLI参数挪到了交互命令里，有些老键名直接不认了。

升级之后先跑一遍opencode --help，看看你最常用的参数还在不在。如果你发现某条命令提示“unknown option”，不要怀疑人生，去官方文档的changelog看字段变更，把旧配置逐项对着改。opencode的配置文件本质是一个JSON，用好官方提供的JSON Schema自动补全，能减少大量手打错误。

提示：升级前备份你的opencode.json。这个文件通常不大，但里面每一条都可能是你花了半天调出来的成果。

3. 模型接入：provider、订阅服务与两个高频报错

3.1 搞清楚provider、baseURL、model ID三者的关系

opencode的模型配置核心是provider机制。可以把provider理解成“一个模型服务的连接方式”，它由三部分组成：API地址（baseURL）、密钥（apiKey）、可用的模型列表（models）。这三者的关系很像外卖平台和餐厅的关系：provider是餐厅，baseURL是餐厅地址，apiKey是预约凭证，models是该餐厅菜单上你能点的菜。

默认情况下，opencode内置了Anthropic、OpenAI、Google等主流provider的配置，你只要填一个apiKey就能用。而当你买了第三方订阅服务或者想接Ollama本地模型时，需要手动加一个自定义provider。下面是一个openai兼容协议的示例：

{ "$schema": "https://opencode.ai/config.json", "model": "my-llm/latest", "provider": { "my-llm": { "npm": "@ai-sdk/openai-compatible", "name": "My LLM Service", "options": { "baseURL": "https://api.example.com/v1", "apiKey": "your-api-key" }, "models": { "my-llm/latest": { "name": "My Latest Model" } } } } }

注意npm字段。opencode通过Vercel AI SDK来对接模型服务，@ai-sdk/openai-compatible这个包让它能兼容所有实现了OpenAI协议的服务。这背后的意义是：只要一个服务能说OpenAI的“语言”，opencode就能听懂，不管它是托管服务还是你自己起的一个本地推理进程。

配置好之后，在opencode里切换模型用的是/models命令，或者直接在对话开头指定。多配几个provider之后，一个小技巧是给每个模型起一个好认的名字，比如fast/cheap、strong/expensive，免得聊天时在长串ID里猜哪个是哪个。

3.2 用OpenCode GO这类订阅服务搭配ccswitch管理多套配置

社区里很多人用一个API key订阅多个模型的聚合服务，比如热搜里总被提到的OpenCode GO。这类服务本质上是给你一个统一的baseURL和一个key，让你在opencode里用一个provider调用多个模型。好处很明显：不用每个模型分别开一个服务的账号，一个面板能看用量，切换模型只是改一下model字段。

但使用聚合服务有个绕不开的问题：你可能会同时持有官方直连key、聚合服务key、本地模型配置等多套环境。这时候ccswitch这类配置切换工具就派上用场了。ccswitch做的事情非常朴素：把多套opencode配置（或者说多套provider配置）保存成profile，需要哪套就一键切换。

我的使用习惯是分三层profile：第一层是官方直连，用来做重要任务；第二层是聚合服务，覆盖日常大部分需求；第三层是本地Ollama，纯粹离线练手或者验证小改动。没有ccswitch之前，我经常手动改配置文件改到怀疑人生，有了它之后，切换一套环境的成本从三五分钟降到一条命令。

3.3 this model is not available in your country到底怎么处理

这个报错在社区里非常高频。它的大致含义是：你当前请求的模型服务商，根据你的访问来源判断你不在它的服务范围内，所以拒绝了请求。

遇到这个报错，不要想着用什么非常规手段去绕，那既不安全也不稳定。正确的处理方式是：

1. 确认你配置的provider是否是“你确实有权访问”的服务端点。如果你买的是聚合订阅服务，就去服务商的面板里查一下它对可用地区有没有说明。
2. 检查模型ID是否真的属于当前provider。有些报错是模型名写错了，服务端返回了一个模糊的错误文案，看起来像地区限制，其实是模型不存在。
3. 换用其他可用的模型或provider。聚合服务一般会提供多个可用模型，面板里列出来的通常就是它能覆盖的。
4. 如果确认是服务商的地域策略问题，直接找客服或看文档，比在配置里折腾更高效。

我自己的经验是：遇到这类错误，先把模型ID核对一遍，再把provider换一圈，80%的情况会消失。剩下20%，该找服务商找服务商，不要把时间耗在和配置死磕上。

3.4 unexpected server error：先看日志再改配置

另一个高频报错长这样：

opencode error: unexpected server error. check server logs...

这类错误最大的特点是“信息量约等于零”。它只告诉你服务器那边出问题了，但没说是什么问题。很多人这时候会去反复改配置文件，其实顺序反了。

正确的排查顺序是：先找日志。

opencode的日志目录在Linux/macOS下一般是~/.local/share/opencode/log/，Windows下在%USERPROFILE%\.local\share\opencode\log\。用下面命令实时盯日志：

tail -f ~/.local/share/opencode/log/*.log

然后重新发起一次请求，看日志里具体输出了什么。常见的几种情况：

这个习惯——先看日志再改配置——才是真正能让你在agent工具里少走弯路的能力。配置文件翻来覆去改一百遍，不如日志里一行明文报错来得直接。

4. 让opencode真正懂你的项目：AGENTS.md、skills与memory

4.1 AGENTS.md：给agent一本项目说明书

绝大多数人用opencode的第一天都会有种“这玩意儿怎么这么笨”的感觉。原因通常只有一个：你什么都没告诉它，却希望它什么都懂。你让一个刚入职的实习生看一眼代码库就开始重构核心模块，他也会给你搞出一堆幺蛾子。AGENTS.md就是那份你理应递给实习生的项目说明书。

在项目根目录放一个AGENTS.md，内容大概长这样：

# AGENTS.md ## 技术栈 - 前端：React 18 + Vite + TypeScript - 后端：Node.js + Fastify + PostgreSQL - 测试：Vitest + Testing Library ## 常用命令 - 启动：npm run dev - 测试：npm test - 构建：npm run build ## 项目约定 - 组件文件使用 .tsx 扩展名 - API错误必须返回统一的 { code, message } 结构 - 新页面必须配套路由懒加载 - 修改后端接口后必须同步更新前端类型定义

opencode会在会话开始时自动读取项目里的AGENTS.md，把它作为背景知识。这份文件写得好不好，直接决定了agent给你的回答是“通用模板”还是“针对你这个项目的具体方案”。

写好AGENTS.md之后，我还习惯加一句提示词：“先读AGENTS.md，再开始任务。”虽然工具会自动加载，但有时候你会开多个会话，明确说一句能让agent把注意力放到项目规范上。

4.2 skills机制：把团队工作流沉淀为可复用能力

skills是opencode里最能拉开效率差距的功能。你可以把一段可复用的工作流写成一个skill，之后让agent执行某个操作时它会自动套用这套流程。skill本质上是一个目录，里面放一个带frontmatter的SKILL.md文件。

举个例子，我负责的项目每次新建页面都要走一套固定流程：建目录、建组件、注册路由、写测试、跑lint。我把这个流程写成了一个skill：

# .opencode/skills/create-page/SKILL.md --- name: create-page description: 在项目里创建新页面。当用户要求新增一个页面时使用。 --- 步骤： 1. 在 src/pages 下创建以页面名命名的目录 2. 创建 index.tsx，导出默认组件 3. 在 router.ts 中注册懒加载路由 4. 在 src/pages/__tests__ 下创建同名测试文件 5. 执行 npm run lint 和 npm test 验证

之后我在opencode里说“帮我新建一个用户协议页面”，它就会自动判断这属于create-page的能力范围，然后按步骤执行。不需要我反复解释项目规范，效率提升是实打实的。

skills的目录可以是项目级的.opencode/skills，也可以是用户级的~/.config/opencode/skills。项目级的放跟当前仓库强相关的流程，用户级的放通用能力，比如“做代码审查”“写commit message”“找问题根因”这类每个项目都用得上的技能。

4.3 社区配置直接抄：superpowers与oh-my-claudecode

skills还有一个巨大的好处：整个社区在互相分享。像superpowers、oh-my-claudecode这类项目，本质上就是把一群资深开发者常用的高质量prompt工作流打包成了一个一个的skill仓库。

superpowers原本是Claude Code生态里一个很受欢迎的技能包，包含写实施计划、做代码审查、规划重构等一整套高质量技能。因为opencode的SKILL.md格式和Claude Code的skills格式兼容，你完全可以直接把superpowers仓库克隆下来，把它的skills目录软链到自己的opencode skills目录里用。

git clone https://github.com/obra/superpowers.git ln -s "$(pwd)/superpowers/skills" ~/.config/opencode/skills

oh-my-claudecode也一样，它是一个社区配置集，提供了大量针对Claude Code的增强配置，里面有很多措辞和流程设计也能直接借鉴到opencode的AGENTS.md里。我的建议是：不要整个照搬，挑出适合自己项目的那几个流程，改改细节放进来。技能不在多，你真正高频复用的可能就三五个。

4.4 memory：跨会话记住偏好

memory功能解决的是另一个问题：AGENTS.md是固定的，但项目是活的。用户今天说“以后错误提示都改成中文”，明天说“测试文件统一放tests目录”，这些对话中产生的偏好如果只能靠typing记住，下一次会话就忘记了。

opencode的memory机制让我可以把这类增量约定持久化。你可以把跨会话要记住的内容写入memory目录下的markdown文件，之后每次会话开始，agent会自动加载这些记忆作为背景知识。

我的用法是分两类记忆：一类是项目的临时约定，放在项目.opencode/memory/下，跟着仓库走；另一类是个人工作习惯，放在用户级配置目录的memory下。比如“所有生成的commit message使用中文描述”“重构后必须跑一次全量测试”“不要随意修改package.json的依赖版本”。这些约定在一次会话里可能不起眼，但累积起来会让agent越来越“懂你”。

4.5 LSP：让agent真正“看懂”代码语义

文本类AI工具最大的局限是：它看到的是字符串，不是代码语义。它知道某个函数叫getUser，但它不知道这个函数在哪些地方被引用、有没有重载、当前作用域里有哪些类型。opencode对LSP的支持，就是为了补上这个短板。

LSP全称Language Server Protocol，是编辑器里实现代码补全、跳转定义、查找引用等功能的标准协议。VSCode、JetBrains IDE之所以能“理解”代码，靠的就是内置的LSP服务器。opencode把LSP能力接进来之后，agent不仅会读文本，还能向语言服务器查询类型信息、定义位置、引用列表和诊断信息。

如果你用TypeScript项目，可以这样在opencode.json里配置：

{ "lsp": { "typescript": { "command": "typescript-language-server", "args": ["--stdio"] } } }

配置好之后，让agent“找出所有调用某个废弃接口的文件并修改”，它的操作就不再是纯文本正则式猜测，而是基于真实引用关系去做修改。这一点在大型项目里非常关键，文本匹配很容易漏掉动态调用的场景，语义级别的理解可以覆盖更多边界情况。

Java项目则可以用jdtls作为LSP服务器。虽然配置LSP的过程有点折腾，但它带来的收益是：agent修改代码时能感知到编译诊断，在动手之前就发现类型错误，而不是改完了跑一遍编译才被现实教育。

5. 终端之外：VSCode、JetBrains和桌面版的使用场景

5.1 三类界面的定位差异

opencode并不只有终端TUI一种形态。它有VSCode插件、JetBrains插件，还有独立的桌面版。有人会困惑到底用哪个，我的理解是它们解决的问题不一样，不是替代关系。

终端TUI是主战场，适合你专心写代码、不想被其他界面干扰的时候。它的优势是启动快、全键盘操作、上下文的控制粒度细。VSCode插件适合你已经在IDE里打开一个项目、想把当前文件直接作为上下文丢给agent、然后看着它在终端面板里干活的场景。JetBrains插件同理，只是对应的是IDEA、WebStorm那套生态。桌面版则是一个独立的TUI窗口，适合你想给opencode一个单独的空间，又不希望和终端里的其他输出混在一起的情况。

5.2 VSCode插件：编辑器与终端会话协同

VSCode插件最实用的场景是“当前文件即上下文”。你在编辑器里打开一个出问题的组件，然后喊opencode说“帮我看看这个文件里为什么状态更新后不重新渲染”，它会自动把当前文件的内容和编辑器里的诊断信息带进对话，不需要你手动复制粘贴文件内容。

另外一个我觉得很舒服的用法是把opencode的会话和编辑器分屏。左边是编辑器，右边是opencode的webview面板，它修改完文件后，你在编辑器里能立刻看到diff，有问题直接提出来让它继续改。这种模式和传统AI插件的体验很接近，但背后的agent能力完全不是一回事。

插件本身不负责跑模型。它连接的是你本机配置好的opencode CLI和模型，所以前提是你已经装好CLI并且模型配置可用。如果插件里提示连不上，先回去查CLI能不能正常跑，八成是配置没填对。

5.3 JetBrains IDEA插件与Maven项目的实操细节

JetBrains用户的诉求其实和VSCode用户一样，但Java项目有个额外的痛点：Maven构建慢、模块多、依赖关系复杂。opencode如果不懂你的Maven结构，很容易画蛇添足。

我的建议是在AGENTS.md里写明白构建和测试命令：

## 后端命令 - 编译：mvn -q -DskipTests compile - 单测：mvn -q test -Dtest=ServiceNameTest - 打包：mvn -q -DskipTests package

然后配上jdtls这类Java LSP，让agent具备Java语义理解能力。比如让它“找到所有订单状态的引用并改成新枚举”，它能基于类型信息去做，而不是靠字符串匹配。

JetBrains插件平时我用的不算多，但有一个场景非常值得用：你在IDEA里改代码到一半，突然想重构一个接口，这时候打开opencode插件面板，让它基于当前上下文出方案，比切到终端重新描述一遍省力得多。也就是说，插件更适合“从编辑器发起任务”，终端更适合“从任务发起读代码”。

6. 实战：接手陌生项目与用Playwright复现前端bug

6.1 接手旧项目时我会先做的四件事

opencode接手不熟悉的项目时，如果你像我一样是个有点强迫症的人，很容易一上来就让它改这个改那个，然后被项目的诡异程度气到。所以我总结了一套接手项目的固定动作，每次都能把风险压住。

第一件事：让它读README和AGENTS.md，把项目目标和规范先灌进上下文。没有AGENTS.md的项目，我会让它先“基于代码库梳理一份AGENTS.md草稿”，跑完检查一遍再让它用起来。

第二件事：让它给出项目结构的“地图”。不是目录树打印那种没意义的东西，而是让它解释“这个项目分成几个模块，模块之间的依赖关系是什么，核心入口在哪里”。这一步能帮你判断这个项目的技术债到底有多重。

第三件事：先验证基线可用。命令就是构建和测试。项目在agent动手之前必须是能跑起来的，否则后面任何改动出了错，你都无法判断是agent改坏的还是本来就坏了。这一步我会卡得很死，基线不过，不进入任何功能开发。

第四件事：把当前关键问题写进AGENTS.md或memory。哪怕只是“我知道现状很乱，但先不要动架构，只做局部修改”，也要写下来。agent和人类一样，如果没有边界提示，很容易顺着“让代码更完美”的思路越改越失控。

6.2 让agent用Playwright自己复现前端bug

前端项目最耗时的一件事是复现bug。用户报“页面上点导出没反应”，你得自己起服务、开浏览器、登录账号、进到对应页面、复现一遍才能开始查。opencode的Playwright集成把这段流程自动化了，你可以让agent自己打开浏览器去操作页面。

我的常用prompt长这样：

用playwright复现以下bug： 1. 打开 http://localhost:5173/login 2. 用测试账号 test/demo1234 登录 3. 进入订单列表页面 4. 点击右上角的“导出CSV”按钮 5. 等待5秒，检查页面上是否出现报错 6. 把console里的错误信息和页面截图保存下来

opencode接到指令后，会启动无头或带界面的浏览器，一步一步执行操作。每一步的结果、截图、console输出都会回传，它基于这些信息继续分析。这个过程看起来像科幻片，实际原理就是工具调用：agent把“打开页面”“点击元素”“读取console”这些动作映射成Playwright的API调用，一步步执行并观察结果。

这个能力最大的价值不是“自动化测试”，而是“缩短反馈循环”。以前你发现前端bug后，要自己去复现、去截图、去猜原因。现在你可以让agent先复现，把现场信息收集齐，再根据结果做分析和修复。一次对话里就能完成“复现—定位—修复—验证”的闭环。

6.3 一次完整的排错实战记录

拿我上周遇到的一个例子来说。项目里有个用户反馈上传头像失败，我自己试了一下没复现，于是让opencode用Playwright走一遍流程。它在点击上传按钮后，从console里抓到了一个跨域相关的报错，并把报错堆栈截图保存了。我顺着截图往下查，发现是新加的图片压缩服务没有配置CORS白名单。整个定位过程大概十分钟，比我去翻各种日志快了很多。

但也不是每次都这么顺利。同一天下午，我让agent修改一个后端接口的返回结构，它改完之后自信地说“测试全部通过”。结果我一跑集成测试，挂了。看了一下它的操作记录，发现它只在本地起了Mock服务，并没有跑真正的集成测试。问题不是模型不聪明，而是它不知道“这个项目集成测试才是权威”。从那之后，我在AGENTS.md里的命令清单上加了粗体提示：

## 重要 - 所有涉及接口的修改，必须跑集成测试目录下的 test/integration - 单测通过不算完成

这也算是一个挺典型的教训：agent工具的强大和危险是同一件事。它有执行力，但它默认会选一条“最省力”的验证路径。你的职责是告诉它什么是“完成标准”。AGENTS.md、skill、memory，本质上都在做这一件事——把边界和标准写清楚。

那次之后我还发现一个经验：改代码前让agent先读一遍相关测试文件，确认它理解期望行为，再动手改实现。这个习惯帮我挡掉了不少“实现正确但语义跑偏”的问题。

结尾

如果你准备开始用opencode，我最想让你先记住的一件事：配置别贪多，先把AGENTS.md写起来。一个项目说明文件，比一百个花哨skill都重要。我见过太多人第一天装上工具就忙着搞各种插件、接一堆服务，结果什么都没用顺，反而把Agent最基本的“理解上下文”这一步跳过了。

等AGENTS.md跑顺了，再慢慢加skills、加memory、接LSP、配Playwright，每个能力都是在稳定地基上往上叠。我自己的节奏是：新项目先花半天把AGENTS.md和命令清单写好，之后省下的时间远远超过这半天。这个工具真正的分水岭不是你会不会装、会不会配模型，而是你有没有给它足够的上下文和边界。

最后再分享一个小技巧：每次会话结束前，花十几秒把今天的临时约定写进memory，日积月累，你的opencode会越来越像那个跟了你很久的老搭档。