企业官网建设流程全解析

先给结论：opencode 是目前终端里最值得花一个晚上折腾的AI编程Agent之一。它本质上是开源社区对 Claude Code、Codex CLI 这类工具的"开放替代品"，代码在你本机跑，模型随便换，配置全部是 JSON 明文，还能接上 LSP、MCP、Playwright 这些真实工程能力。这篇文章我会从零开始，把安装、模型接入、日常配置、编辑器插件，到实战中用 Playwright 修前端 Bug、接手老项目，再到各种报错的排查方法，一次性讲透。适合刚听说 opencode 的新手，也适合已经在用但是被模型接入和报错折磨过的老手。

1. opencode 到底是什么，为什么值得折腾

1.1 一句话定位：开源的终端AI编程 Agent

opencode 是一个跑在终端里的 AI 编程代理，由开源社区维护（项目主仓库在 GitHub 上，官网是 opencode.ai）。它做的事情和 Claude Code 类似：你给它一个任务，它自己去读代码、改文件、执行命令、跑测试、看结果，然后迭代直到搞定。但它和闭源产品的核心区别在于，模型层是完全开放的，OpenAI 兼容接口、Anthropic 接口、本地 Ollama，只要能通过标准接口拿到模型回复，它都能用。

我第一次用的时候最大的感受是：这东西不像一个"聊天框"，更像一个"临时同事"。你说"帮我把这个接口的鉴权逻辑理清楚"，它不会只给你一段建议，而是真的会去翻项目里的路由、中间件、配置和测试文件，最后直接给你一份改动方案，问你要不要执行。

1.2 和 Claude Code / Codex CLI 的定位差异

Claude Code 很强，但有两个痛点：绑死 Anthropic 的模型，而且核心能力跟账号和付费强相关。Codex CLI 同样绑了 OpenAI 的生态。如果你团队已经买了别的模型服务，或者公司数据合规要求敏感代码不能出内网，这两个闭源工具就用得很憋屈。

opencode 的思路是"我提供的是 Agent 的骨架和工程能力，模型你自己接"。这意味着你可以用 GPT、Claude、Gemini、通义、DeepSeek，甚至是内网部署的开源模型。我自己的环境里就同时配了三家供应商，还有一个 Ollama 本地模型做兜底，哪家抽风就/models切一下，完全不影响工作流。

1.3 它能帮你干哪些正经事

• 跨文件理解代码：配合 LSP 之后，能看懂"这个函数被谁调用""这个类型定义在哪个包"，不是纯文本猜测。
• 一键跑测试和静态检查：代理自己执行npm test、go test、mvn test，看失败信息，改代码，再跑。
• 浏览器自动化验证：内置 Playwright 能力，让代理自己写脚本、起浏览器、复现前端 Bug，再把 console 报错带回来。
• 接手老项目：给一个陌生仓库，它能先读文档、理结构、列启动步骤，你再让它改，不会乱动。
• 团队规范落地：通过 skills 技能包，把你团队的"代码审查清单""提交规范"沉淀成流程。

我个人的建议是别把它当成"全能程序员"，而是当成一个"干活特别快、但需要你把需求和验收条件说清楚的实习生"。你的需求越具体，它给你的结果越能直接用。

2. 安装：从零到上手，含 Windows 专属大坑

2.1 几种安装方式怎么选

opencode 官方提供了好几种安装方式，我实际试过的有以下三条。

# 方式一：npm 全局安装（推荐，方便后续升级） npm install -g opencode-ai # 方式二：官方安装脚本（适合不想装 Node 的环境） curl -fsSL https://opencode.ai/install | bash # 方式三：Go 用户喜欢的方式 go install github.com/sst/opencode/cmd/opencode@latest

如果你机器上本来就有 Node.js 环境，直接走方式一最省心，之后opencode upgrade就能更新，不用再去官网重新下载。如果是干净的服务器或者只想快速试水，用方式二。方式三适合本来就是 Go 开发者、习惯用go install管理工具链的人。

装完之后，在终端里输入：

opencode

如果进入了交互式终端，说明安装成功。

2.2 Windows 上最常见的坑：无法将 opencode 项识别为 cmdlet

这是新手问得最多的问题，报错长这样：

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

这个报错的原因只有一个：opencode.exe所在的目录没有被加进系统 PATH 环境变量。npm 全局安装的可执行文件，默认会被放到 npm 的全局 bin 目录下，但这个目录不一定在 PATH 里，尤其是 Windows 上，不同方式安装的 Node.js，默认目录还不一样。

排查步骤：

1. 打开 PowerShell，确认 npm 全局目录在哪里：

npm config get prefix

2. 我机器上输出的是C:\Users\你的用户名\AppData\Roaming\npm，一般情况下这个目录就是 bin 所在地。你可以看下这个目录里有没有opencode或opencode.cmd文件。

3. 把上述目录加到 PATH：

   • 按Win键，搜索"编辑系统环境变量"；
   • 点击"环境变量"；
   • 在"用户变量"里选中Path，点"编辑"；
   • 新建一行，把 npm 目录完整路径粘进去；
   • 一路确定保存，然后重新开一个终端。

第一步装完后很多教程没说：PowerShell 里执行opencode报的"禁止运行脚本"错误，跟上面的 cmdlet 报错不是一回事。如果是红色文字提示"无法加载文件 ... 因为在此系统上禁止运行脚本"，那是执行策略问题。解决办法是在 PowerShell 里执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后输Y确认。这个操作只影响当前用户，不会影响系统安全配置。

2.3 安装完先跑一下自检

opencode 自带一个诊断命令，我建议每次配完环境、或者遇到莫名其妙的问题时先跑它：

opencode doctor

这个命令会检查核心配置是否存在、认证信息是否可用、模型 ID 能不能正常解析。它会把检查结果直接列出来，哪一行是 warning 就优先处理哪个，能省掉后续很多玄学问题。

2.4 桌面版和 CLI 版怎么选

现在 opencode 有 CLI（终端版）和桌面版两种形态。我的建议是：日常开发，优先使用 CLI。原因在于，终端版对项目的感知能力最直接，能跟随你当前所在的目录自动加载项目配置，而且跟 Git、终端命令的配合是无缝的。桌面版更适合纯可视化操作、或者不想和终端打交道的人，但它本质上是把同一个引擎包了一层窗口，功能上并没有超集。

你完全可以在两者之间切换，配置是同一份。我自己的习惯是快速改文件用 CLI，需要截屏对比 UI 问题时打开桌面版辅助。

3. 模型接入与配置：搞定模型，就搞定了一半

3.1 配置文件到底放在哪

opencode 的全局配置文件默认在用户目录下，Linux/macOS 是~/.config/opencode/opencode.json，Windows 上是%USERPROFILE%\.config\opencode\opencode.json。如果项目里放了一个.opencode/opencode.json，它会被自动合并进去，实现"项目级覆盖全局"的效果。

我第一次用的时候在项目根目录创建了配置文件，结果全局没生效，折腾半天才发现全局和项目是合并逻辑，不是覆盖逻辑。项目配置优先级更高，但全局配置里 provider 和模型定义要写全。

下面是我常用的最小配置模板：

{ "$schema": "https://opencode.ai/config.json", "model": "gpt-4o-mini", "provider": { "openai": { "options": { "baseURL": "https://api.example.com/v1", "apiKey": "sk-你的key" }, "models": { "gpt-4o-mini": { "name": "主力轻量模型" } } }, "anthropic": { "options": { "baseURL": "https://api.anthropic.com", "apiKey": "sk-ant-你的key" }, "models": { "claude-sonnet-4-20250514": { "name": "复杂推理用" } } } } }

配置文件里的provider是一个对象，键名是供应商标识，models下面列出你想用的模型。baseURL是关键，只要你的模型服务商提供 OpenAI 兼容接口，基本都能通过这种方式接入。

3.2 接入 OpenAI 兼容接口：服务商怎么选

如果你有云厂商的模型服务、或者第三方聚合服务，核心就是拿到三个东西：baseURL、apiKey、model ID。然后填进配置文件。实测下来，很多聚合服务用的是和 OpenAI 一模一样的/v1/chat/completions接口，所以直接在options里写baseURL就能通。

这里给一个我踩过坑后的建议：先用小模型验证连通性，再切大模型。我之前一次性配好了复杂模型，结果 key 写错，报错信息里又看不出是鉴权问题，排查了好久。现在每次新接一个供应商，都先用一个便宜的轻量模型，确认跑通了再切重量级模型。

3.3 免费匿名模型和订阅套餐怎么选

opencode 的一个亮点是内置了 Anon 匿名认证，可以让你不配任何 key 先体验一把。在会话里输入/auth，选 Anon，再选一个免费模型就能开始。适合第一次安装后想立刻验证"这工具到底能不能跑"的场景。

但社区里很热门的"go 套餐"这类第三方订阅服务，我要特别提醒一句：它们本质上是模型聚合服务，用一个订阅号换取多个高价模型的访问额度。我的使用心得是：

• 优先选支持"按量计费"的，不要一上来买年付，因为你不知道自己一个月实际消耗多少。
• 确认它有 OpenAI 兼容接口，且支持自定义baseURL。
• 确认服务的可用性和更新频率，别买完之后几天没人维护。

免费模型（比如社区里流传的 hy3-free 这类匿名免费池）更适合尝鲜。它最大的问题是不稳定，随时可能下线、限流、或者突然提示模型不存在。我之前连续两天早上打开都报 404，后来被逼着配了正式供应商才踏实。

3.4 多供应商切换工具：ccswitch、Superpower 怎么配合用

当你手上有多个供应商 key，手动去改 opencode.json 会很烦。社区里常用 ccswitch 这类工具来管理多套配置。它的思路简单直接：预先保存好几套完整配置（比如"家用的聚合服务""公司的内部网关""本地的 Ollama"），通过命令行一键切换，切换时会自动把目标配置写到 opencode 的配置文件夹里，然后你重启 opencode 就生效。

Superpower（社区里也写作 superpowers）则是给 Agent 加"技能"的增强包，它本质是一堆结构化的 markdown 技能文件，让代理按照更成熟的工作流程干活。opencode 对这类技能包的兼容性做得不错，装完之后代理在动手改代码前会先做需求澄清、方案评审，减少"瞎改"的情况。

我的个人工作流是：ccswitch 管"用哪家模型"，Superpower 管"用哪种工作方式"。两层解耦，互不干扰，非常适合 team 内部推广。

3.5 区域策略报错：this model is not available in your country 怎么处理

这个报错原文是：

this model is not available in your country.

原因很直接：模型服务商（尤其是一些境外厂商）会根据请求来源 IP 所在的地区做合规审查，你的账号和 key 都没问题，纯粹是地区策略限制。很多人会去换 key、重装 opencode，根本没用，因为问题出在服务端而不是本地。

合规的处理办法有三个方向，我按推荐程度排序：

1. 换用支持你当前所在地区的模型服务商。国内就有很成熟的 OpenAI 兼容服务，通义、DeepSeek、智谱都提供标准接口，填进baseURL就能用。
2. 在项目里使用自建的模型网关。如果你的团队有部署在海外的合规云服务器，可以自己搭建一个只转发模型 API 的网关，然后把baseURL指向这个网关。注意这里的前提是你自己的服务器、自己的密钥、合法的业务用途。
3. 直接彻底绕开云端，用本地模型跑。现在 Ollama 上优秀的开源编码模型很多，本地跑完全可控，没有任何区域问题。

这个报错正确的定位顺序是：先看报错文案里有没有 "country" 字样，有就是区域策略，别浪费时间在配置上；没有再怀疑 key 或 baseURL 写错。

3.6 本地模型：用 Ollama 把模型完全掌握在自己手里

内网部署和离线开发我都是走 Ollama。先启动本地模型服务：

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

然后在 opencode.json 里加一个 provider：

{ "provider": { "ollama": { "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "qwen2.5-coder:14b": {} } } } }

这里的 baseURL 指向 Ollama 的兼容端点，模型 ID 直接写你 pull 下来的名字就行。本地模型的优点是隐私和可控，缺点是推理速度和大模型的智商天花板，日常做重构和写测试够用，但复杂架构设计还是得上云端模型。我通常把本地模型当成"不能联网时的兜底"，而不是主力。

4. 日常使用配置：skills、记忆、LSP、MCP 一个都不能少

4.1 Skills 技能：把团队规范变成 Agent 的本能

很多人用了很久 opencode，还停留在"聊天->手动复制代码->手动改"的阶段，其实是很浪费的。skills 才是让 Agent 真正"懂你团队"的关键。

opencode 的技能本质上是 markdown 文件，放在项目.opencode/skills/目录下，或者全局用户配置目录下。每一个 skill 文件包含一段 frontmatter 描述，以及正文里的操作步骤。我在团队里最常用的一个 skill 是"代码审查清单"，内容大概是这样：

--- name: code-review description: 在提交 MR 前，按团队规范执行代码审查 --- 1. 运行当前分支的测试命令，记录失败项。 2. 检查所有新增的 API 接口是否补充了错误处理。 3. 审查日志是否包含请求 ID 和链路追踪字段。 4. 输出审查报告，按 P0/P1/P2 分级。

配置好之后，你在会话里说"帮我按规范审查一下最近的改动"，Agent 就会真正执行这些步骤，而不是凭感觉瞎说。如果你接触过社区里的 superpowers 技能包，会发现它就是这种 markdown 技能的集合，完全可以导入进来。

4.2 记忆与会话持久化：Agent 能不能记住你的偏好

opencode 的"记忆"不是像 ChatGPT 那样有一个全局记忆库，而是靠两套机制：

一是项目级的规则文件。在项目根目录维护一份AGENTS.md，把项目的启动命令、测试命令、代码风格约定写清楚，每次会话初始加载时代理都会先读它。这比每次对话都重新解释上下文高效得多。

二是配置文件本身。你在opencode.json里写的模型偏好、供应商、默认行为，本身就是一种"记忆"。

我的建议是：项目规则写进AGENTS.md，个人偏好写进全局配置，不要把项目专用信息放到全局配置里，否则换项目时会互相污染。

4.3 LSP：让 Agent 像 IDE 一样理解代码

这是 opencode 比很多纯对话式 AI 工具强的地方——它内置了 LSP（Language Server Protocol）客户端。LSP 就是 IDE 用来提供"跳转定义""查找引用""自动补全"的底层协议。opencode 接入 LSP 之后，代理看代码就不再是"猜"，而是能真正理解符号之间的关系。

具体配置上，opencode 会自动检测语言和服务服务，前提是你本地装了对应的 language server。以 TypeScript 项目为例，你需要装：

npm install -g typescript-language-server typescript

Java 的 Maven 项目我会直接在 IDEA 插件里用，让 IDE 自带 JDK 和 Maven 环境去配合，比纯终端里配 jdtls 省心很多。

打开 LSP 功能的开关后，你会发现代理在回答"这个函数是否安全""这个改动会影响哪些调用方"这类问题时，准确率高了一大截。代价是启动时会先建立索引，大项目会慢几秒，但完全值得。

4.4 MCP：对外部工具的能力扩展

MCP（Model Context Protocol）是现在 AI Agent 社区的标准扩展协议，opencode 支持直接配置 MCP server。它解决的是什么问题？就是让 Agent 能够调用外部工具：读数据库、查监控、操作文件系统，而不仅仅是读代码。

配置方式是在opencode.json里加mcp字段：

{ "mcp": { "playwright": { "type": "stdio", "command": ["npx", "-y", "@playwright/mcp@latest"] }, "filesystem": { "type": "stdio", "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"] } } }

这里的核心逻辑是：每个 MCP server 都是一个本地子进程，Agent 通过标准输入输出跟它通信。配好之后，在会话里输入/mcp就能看到当前已加载的 server 列表。我强烈建议至少配一个 Playwright MCP，这是后面做前端 Bug 复现的底气。

5. 编辑器集成：VSCode / JetBrains 插件的正确打开方式

5.1 VSCode 插件：在侧边栏里指挥 Agent

VSCode 插件在插件市场直接搜 "opencode" 就能找到，安装后左侧会出现一个专门的图标。使用起来主要是两种模式：

一是打开聊天面板，和终端里一样对话，但可以选中代码直接发送给 Agent，省掉写路径和时间。二是可以直接在集成终端里启动opencode，我实测这样最接近终端原生体验，而且能直接复用 VSCode 的终端环境和环境变量。

插件模式下最顺手的操作是：遇到一段不知道在干什么的代码，选中右键选择"Send to Opencode"，问它"这段代码在做什么，有没有潜在 Bug"。响应速度取决于你用的大模型，但整体体验很流畅。

5.2 JetBrains IDEA 插件：检视 diff 和接受改动

IDEA 用户在 Settings -> Plugins 里搜 "opencode" 安装插件，装完后在右侧工具窗口能找到。这个插件的好处是它和 IDEA 的 VCS、diff 工具深度集成，Agent 改完代码后，你可以像 review 同事代码一样逐个文件看 diff，接受或拒绝。

我建议用 JetBrains 插件的场景是：改动的文件多、涉及面广、你不想被 Agent 直接改坏整个项目。插件模式下，所有变更都可以先进入"待确认"状态，你有完全的掌控权。

5.3 命令行、桌面版、插件，到底怎么配合

我在实际工作里的分工是这样：

• 终端 CLI：日常小改动、快速提问、执行测试，效率最高。
• VSCode 插件：写前端和 TS 代码时使用，因为选中代码传上下文太方便。
• IDEA 插件：Java/后端项目的主力，diff 审阅体验碾压终端。
• 桌面版：演示和截图场景用，平时基本不常开。

一句话总结：代码在哪写，opencode 就开在哪。环境是工具链的一部分，不用在一棵树上吊死。

6. 实战：用 Playwright 测前端 Bug，以及高效接手老项目

6.1 让 Agent 自己打开浏览器：前端 Bug 复现不再靠猜

前端 Bug 最烦人的地方是"用户报了问题，但我本地复现不出来"。opencode 配合 Playwright 能很大程度缓解这个问题。

第一步，确认项目里能跑 Playwright。在项目根目录执行：

npm install -D @playwright/test npx playwright install chromium

第二步，进入 opencode 会话，给它一个具体的复现描述。我一般这样说：

使用 Playwright 打开 http://localhost:5173 复现步骤： 1. 点击右上角的设置按钮 2. 切换主题为深色 3. 点击保存 期望：页面不刷新且设置生效 实际：页面刷新，设置丢失 请写一个脚本复现，运行并贴出 console 报错。

Agent 会自己写 Playwright 脚本、启动浏览器、执行操作、收集页面 console 日志和网络请求。有一次它甚至帮我发现了一个只有在商品详情页特定状态下才会抛出的 React key 警告，换作我自己手工点，可能半天都发现不了。

6.2 接手老项目：先理解，再动手

很多人接手老项目都会犯一个错——上来就让人改 Bug，结果 Agent 一顿操作把不相关的地方也改了。正确打开方式是这样：

第一步，让 Agent 先做"项目体检"：

先不要改任何代码。 请通读项目 README、启动配置、目录结构，告诉我： 1. 技术栈和框架版本 2. 本地启动和测试的命令 3. 项目里最核心的三个模块 4. 代码里是否有明显的 TODO 或遗留问题

这一步的输出会变成你理解项目的骨架。第二步，让它"定位"而不是"修复"：

不要直接修复。 先找到用户登录后头像不显示的问题，定位到具体文件和代码行，给我说明原因。

要让 Agent 先做侦察兵，再做工兵，否则它很容易把"修复"变成"重写"。

6.3 一个完整可复现的流程示例

这里简单记录一次我实际操作的流程。任务是修一个"搜索框输入中文后，按下回车无响应"的问题。

我在项目根目录进入opencode，发了两条消息：

第一条消息让它定位，并且要求附带筛选后的日志。第二条消息让它给出修复方案，但先不要执行。确认方案合理后，我又发了一条指令让它执行，并且跑相关的单元测试。

整个过程下来，最有价值的不是它真的改了代码，而是我在每一条指令里都规定了明确的交付物：第一步交付"分析报告"，第二步交付"改动方案"，第三步才交付"实际变更"。这种渐进式交互，比一次性给一个宏大任务要稳定得多。

7. 常见报错速查表与避坑经验

再分享一个通用排查思路：遇到任何模型相关的异常，先在 opencode 会话里输入/models查看当前实际加载的模型列表，再用/config确认当前生效的配置。这两个命令能排除掉 80% 的"配置没生效"问题。

另外，如果你在 Windows 上使用 PowerShell，一定要记得分开排查"命令找不到"和"脚本被禁止执行"两类问题，它们的解决方案完全不同，千万别混在一起处理。

一点经验之谈

用了一段时间 opencode 以后，我最大的体会是：这类 Agent 工具的上限，其实不取决于模型多强、功能多全，而取决于你能不能写出足够清晰的任务边界。每一条指令都带上"期望我交付什么""验收标准是什么"，它给你的结果就能直接用。opencode 只是把模型、编辑器、终端这些碎片拼成了一个新的工作流，真正让工作流发挥价值的，还是背后拆解问题的人。

另外一个很实在的建议：别一上来就把工作和重要分支完全交给它。先用一个小项目、一小段代码跑通这套流程，慢慢把你的团队规范、skill 包、模型供应商都沉淀好，再逐步放大使用范围。我踩过不少坑之后的感受是，工具永远在快速迭代，但一套稳定的工作方法，才是能跟着你走很久的东西。