企业官网建设流程全解析

上周帮一个朋友排查前端项目，他还在手工截图、一步步点页面来复现 bug，我当场给他装了 opencode，让它用 playwright 把问题路径跑了一遍，不到十分钟就定位到了是哪次接口返回异常导致的。朋友当时就愣了，说这玩意儿比他自己点一上午效率高多了。

opencode 不是某个公司的商业闭源产品，而是一个开源的 AI 编程代理工具，定位跟 Claude Code、Codex CLI 类似，但它最大的特点就是“模型无关”——你想接 Claude、GPT、Gemini、还是本地跑的 Qwen、DeepSeek，它都支持。而且它天生带着终端 Agent 的基因，能自己读代码、改文件、跑命令、看报错，再决定下一步干什么。对天天坐在终端里的开发者来说，这东西本质上等于给你配了一个能自己动手写代码、跑测试的实习生，而且这个实习生还不会摸鱼。

这篇文章我打算把我这几个月实际使用 opencode 的经验完整梳理一遍，从安装、配置、模型接入，到接手项目的实战流程、Skills 自定义、Memory 长期记忆、VSCode/JetBrains 插件、桌面版，再到用 playwright 做前端 bug 复现，最后把高频报错和避坑点整理成速查表。不管你是刚听说 opencode 的小白，还是已经装好但不知道怎么玩出花样的老手，这篇文章应该都能让你少走不少弯路。

1. 整体认知与设计思路：opencode 到底是个什么东西

1.1 它不是聊天框，而是一个能动手干活的终端代理

很多人第一次打开 opencode，以为它就是一个跑在终端里的 ChatGPT。这么理解不能说全错，但会错过它最核心的价值。ChatGPT 那种网页聊天框，你问一句它答一段，代码要你自己复制粘贴回去。opencode 不是这样，它拿到你的需求之后，会自己规划步骤、自己读项目文件、自己改代码、自己跑命令验证，整个过程是循环式的：判断 -> 执行 -> 看结果 -> 再判断。

我打个比方，传统 AI 编程辅助像是给你一本说明书，你照着翻、照着做；opencode 更像是你雇了一个远程工作的初级工程师，你只需要把任务描述清楚，它会自己打开 IDE、读代码、动手改、跑测试，然后告诉你结果。这个差别在“接手一个不熟悉的项目”时尤其明显。

1.2 为什么选择 opencode 而不是 Claude Code 或 Codex

市面上的终端 AI 代理不少，我为什么最终把 opencode 当成主力？核心原因有三个。

第一，模型无关。Claude Code 基本绑定 Claude 系列模型，Codex CLI 更偏向 OpenAI 系。opencode 的 Provider 机制很灵活，官方支持的模型服务商很多，我甚至可以把自己内网部署的模型接进去。这意味着我不需要为了一个工具换掉自己习惯的模型。

第二，开源可改。opencode 的代码在 GitHub 上完全开源，社区活跃度很高，Issue 响应快。我用的时候偶尔会遇到一些小毛病，基本当天或者隔天就有 fix 版本。开源还有个好处，就是我可以直接进去看它某个动作是怎么实现的，心里有底。

第三，生态整合做得好。opencode 有官方的 VSCode / JetBrains 插件、桌面版，还支持 Skills、Memory、Agent 事件回调这些高阶功能。它不是单一的命令行工具，而是可以嵌进日常开发流程的一整套工作流。

1.3 它能解决什么问题

以我这几个月的实际体验，opencode 最适合解决这几类问题：

• 接手老项目，快速理清代码结构和业务逻辑。
• 写重复性的样板代码，比如 CRUD 接口、DTO、数据库迁移。
• 改 bug，尤其是那种报错信息明确但你不熟悉代码上下文的问题。
• 跑测试和修测试，它自己能执行命令、读失败日志、再改代码。
• 前端 bug 复现，配合 playwright 技能，它能自动开浏览器操作页面。
• 批量重构，比如重命名、提取公共方法、统一错误处理这类机械操作。

当然，它也不是万能的。架构设计、技术选型、重大性能优化这些事，它目前还替代不了人的判断。我的经验是，把它定位成“能执行任务的助手”而不是“能做决策的架构师”，用起来会顺很多。

2. 安装与环境准备：从零到能跑起来

2.1 几种安装方式的对比

opencode 的安装方式有好几种，官方文档里最常见的是 curl 脚本安装。但实际使用中，不同系统的开发者适合不同方式，我这里列个对比表：

我自己的主力环境是 macOS + Node，所以长期用的是 npm 全局安装。这里有个细节很多人会踩坑：npm 全局安装之后，如果终端提示找不到 opencode 命令，不是安装失败，而是 npm 的全局 bin 目录没有加到 PATH 里。

2.2 高频报错：无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称

这个报错在 Windows PowerShell 下出现的频率极高，热词里甚至有完整的报错原文。出现这个提示，99% 的原因是 opencode 的可执行文件路径没有被系统找到。它不是一个复杂的问题，但处理方式要分情况。

如果用的是 npm 安装，先执行npm config get prefix查看全局目录，正常情况下会输出一个路径，然后把%APPDATA%\npm或者对应的 bin 目录加到系统环境变量 PATH 里。加完之后一定要重新开一个终端窗口，因为环境变量的修改不会自动刷进已经打开的会话。如果用的是 curl 脚本安装，脚本默认会装到~/.opencode/bin，同样需要确认这个路径在 PATH 里。

还有一种情况，Windows 下如果提示“此系统上禁止运行脚本”，那不是 PATH 的问题，而是 PowerShell 执行策略默认禁止了脚本运行。解决办法是用管理员权限打开 PowerShell，执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，然后重新试一次。

2.3 安装后先跑一个最小验证

装好之后别急着接项目，先跑一下opencode命令，进入交互界面。如果它能正常启动并出现一个命令行输入框，说明安装没问题。这一步建议直接问一个简单问题，比如“1+1等于几”，看看模型能不能正常返回。这一步可以同时验证两件事：opencode 本体能跑、模型通道是通的。

我见过不少人装完就急着让它读项目，结果报了一堆错，最后发现是最开始模型 API Key 就没配好。所以最小验证这个习惯一定要养成，能帮你把安装问题、模型问题和项目问题在第一时间隔离开。

3. 模型接入与配置：把 opencode 接到你最顺手的模型上

3.1 登录认证与配置文件

opencode 的模型接入方式很直接。第一次运行时，它可以引导你执行opencode auth login，然后选择你要用的模型服务商，走 OAuth 或者粘贴 API Key 的流程。登录完成后，凭据会存储在本地。

所有配置的最终落点是一个 JSON 配置文件。不同系统的位置不一样，macOS 在~/.config/opencode/，Linux 在$XDG_CONFIG_HOME/opencode/，Windows 在%APPDATA%\opencode\。如果你用的是桌面版，配置文件路径可能稍有差异，但结构一样。我直接手动改配置文件的次数不少，因为有些自定义 Provider 必须手写 JSON 才能搞定。

3.2 模型服务商怎么选

opencode 对模型服务商的支持相当广泛，而且名字起得也很直白，就叫 Provider。配置方式类似于给模型起个小名，然后指定 Provider 和模型 ID：

{ "$schema": "https://opencode.ai/config.json", "provider": { "my-openai-compatible": { "npm": "@ai-sdk/openai-compatible", "name": "My OpenAI-compatible Gateway", "options": { "baseURL": "http://localhost:8000/v1", "apiKey": "my-secret-key" }, "models": { "my-model": { "name": "My Model" } } } } }

这里稍微解释一下这个配置的结构。my-openai-compatible是你给这个 Provider 起的标识名，@ai-sdk/openai-compatible是 opencode 用来跟这个服务通信的 SDK 包名，baseURL指向兼容 OpenAI 协议的服务地址，models下面定义这个 Provider 具体能调哪些模型。如果你用的是本地推理服务，只要它兼容 OpenAI 的/v1/chat/completions接口，理论上都可以用这种方式接进来。

我知道不少人在网上搜“opencode 免费模型”，这里我多说一句：不要为了省一点 API 费用去碰来路不明的第三方代理服务。那些服务一是稳定性没保证，二是你的代码片段、业务逻辑都会被对方看到，这是很大的安全隐患。想省钱有两条正路：一是用各家云厂商的免费试用额度，二是直接在你的内网用 Ollama 或 vLLM 部署开源模型，然后按上面的配置方式接进 opencode。

3.3 切换模型的两种姿势

opencode 的命令行界面里按快捷键就能切换模型，这个对多模型对比非常方便。我经常是让同一个任务分别用两个模型跑一遍，然后对比结果。实测下来，复杂的重构类任务我更倾向用 Claude 系列，纯代码生成类的任务 GPT 系和 Gemini 表现也都不错。但这个东西非常主观，跟任务类型、代码库语言都有关系，不建议照搬别人的结论，自己对比几次就有数了。

在配置文件里你也可以给不同模型设定不同的 temperature 等参数。我一般会保持默认，只在做代码解释、文档生成这类任务时把 temperature 调低一点，让输出更稳定。

4. 实战过程：用 opencode 接手一个真实开发项目

4.1 启动并描述任务

配置好之后，进入项目目录，直接运行opencode，会进入一个交互式命令行。此时你不需要输入任何复杂指令，就用自然语言描述任务就行。关键是要具体，比如“在 src/utils 下新增一个 formatDate 函数，要求处理时区”和“帮我写个日期格式化函数”，两者的效果差别很大。

opencode 的 Agent 会先自己读目录结构、关键文件，然后给出它的理解和计划。你可以在它动手前纠正方向。这非常重要，因为它一旦开始改文件，改错的代码有时候比不改还麻烦。我常用的模式是：“先不急着写代码，帮我梳理一下这个模块的调用链，输出一份 markdown 文档。”先让它读，再让它写，能大幅降低返工率。

4.2 Agent 模式与自动执行

opencode 的 Agent 模式是它最核心的能力之一。启用后，它不仅会读代码，还会自己执行命令，比如npm test、python manage.py migrate、git diff，然后根据输出结果决定下一步。这意味着它可以完成“改代码 -> 跑测试 -> 看失败 -> 继续修”这样一个完整的闭环。

第一次用的时候你可能会有点不放心，怕它乱跑危险命令。opencode 在 Agent 模式下执行命令前默认会请求确认，你可以选择同意、跳过或者直接允许所有类似命令。我在可信的项目里一般会先让它在测试命令上自动执行，这样效率更高。如果是操作数据库迁移、删除文件这类敏感命令，我建议还是手动确认一下，别偷懒。

4.3 使用 Skills 给 opencode 加技能

Skills 是 opencode 一个很实用的扩展机制，本质上就是一组预定义好的指令或脚本，让 Agent 在面对特定类型任务时能按固定流程执行。官方有superpowers这个技能集，社区还有一个叫oh-my-claudecode的项目也做了很多 Skills 适配。

我自己写过一个代码审查的 Skill，流程大致是：先读变更文件列表，再逐个文件读 diff，然后对照项目里的代码规范文档给出意见，最后输出一份审查报告。以前这个流程我要手动分四步操作，现在一个指令就搞定。

Skill 的安装可以放到配置文件里，也可以放到项目目录的.opencode/skills下。放到项目目录的好处是团队协作时可以一起提交到 Git，大家统一用同一套技能。

4.4 Memory：让 Agent 记住你的偏好

opencode 的 Memory 功能解决的是“同一个问题反复交代”的痛点。比如你希望所有新增接口都遵循项目里已有的错误码规范，希望日志统一打印请求 ID，这些偏好只要在 Memory 里写一次，之后 Agent 在生成代码时就会自动带上。

本质上 Memory 就是把一些长期有效的上下文注入到每次对话里。所以内容不用多，抓住高频、稳定的偏好即可。我会定期清理一下 Memory，避免注入的上下文太长影响模型效果。毕竟这个空间不是无限的，也不是越详细越好。

5. VSCode / JetBrains 插件与桌面版：不离开 IDE 也能用

5.1 VSCode 插件

如果你主要用 VSCode，opencode 的官方插件值得装。它的定位不是替代终端里的 opencode，而是让你在编辑器里直接调起 Agent，并把改动以 diff 的形式展示在编辑器里。这个体验很舒服，因为代码上下文就在眼前，审查改动非常直观。

插件的安装方式跟普通扩展一样，在扩展市场搜 opencode 即可。装完之后左侧会出现一个面板，可以输入任务、查看对话历史、切换模型。它跟终端版共用同一套配置，也就是说你之前配置好的 Provider、Skills、Memory 在插件里直接可用，不用重新配置。

5.2 JetBrains 插件（IDEA 系）

JetBrains 系的插件进度比 VSCode 稍微晚一点，但核心功能已经可用了。如果你是 IDEA 用户，直接在插件市场搜 opencode 装上。注意它跟 VSCode 插件一样需要依赖 opencode 本体，所以如果你还没装命令行版，插件会提示你先安装。

IDEA 插件我实测下来最顺手的一个场景是，直接在编辑器里选中一段代码，右键选择让 opencode 解释或者重构。它会把改动放到一个临时文件里，用 IDEA 自带的 diff 视图展示，这样你可以像 review 同事代码一样 review Agent 的改动。

5.3 桌面版

opencode 也提供了桌面版，适合不想跟终端打交道的用户。桌面版的界面会多一个图形化的设置面板，模型管理、Skills、Memory 这些都能在界面上直接操作。不过需要说明的是，桌面版目前的功能覆盖度不如命令行版，一些高级配置还是建议直接改 JSON 文件。

我个人主推的还是命令行版 + IDE 插件的组合。原因很简单：命令行版的自动化能力最强，IDE 插件的代码审查体验最好，两个配合，效率才是最高的。

6. 用 playwright 技能复现和修复前端 bug

6.1 为什么 Agent 需要浏览器自动化

前端 bug 一直是 AI 编程辅助最头疼的场景之一。原因在于前端问题往往依赖浏览器环境，报错信息只是表象，真正的问题可能藏在交互流程、接口返回、渲染时序里。如果 Agent 只能读代码，它就很难验证自己的修复是否真的解决了问题。

opencode 社区给出的一个答案就是结合 playwright。playwright 本身是微软开源的一套浏览器自动化测试工具，支持 Chromium、Firefox、WebKit。opencode 通过配置技能的方式，可以让 Agent 自己编写并执行 playwright 脚本，真实地打开页面、点击按钮、输入内容、断言结果。这样一来，Agent 就能像人一样操作浏览器来复现 bug。

6.2 一条指令让 Agent 复现前端问题

在 opencode 的对话里，如果你希望它复现一个前端 bug，指令要尽量描述清楚现象和路径。比如“首页搜索框输入关键词后点击搜索，页面白屏，请用 playwright 复现这个 bug，并定位原因”。

Agent 会先创建或修改一个 playwright 脚本，通常放在tests/或者临时目录里，然后执行脚本、观看结果。如果脚本执行失败，它会主动读错误信息，分析是脚本写错了还是业务代码真有问题。如果复现成功，它会继续读业务代码，给出根因分析和修复建议。

这里要提醒一下，首次运行 playwright 可能需要安装浏览器内核，命令是npx playwright install。这一步耗时比较长，而且部分地区下载会很慢，建议提前在项目里把浏览器内核装好，免得 Agent 跑一半卡住。

6.3 常见的坑

用 playwright 跑前端 bug 复现，我遇到过几个典型的坑：

第一，opencode 执行的 playwright 脚本是它自己写的，不一定符合你项目里已有的测试规范。所以如果你项目里本来就有 playwright 基础配置，最好提前告诉它“使用项目已有的 playwright 配置”。

第二，有些前端项目的开发服务器启动很慢，Agent 执行 playwright 时可能因为页面还没加载完就报元素找不到。这种情况可以提示它在脚本里加等待逻辑，或者先手动启动好 dev server 再让 Agent 跑。

第三，如果页面涉及登录态，Agent 默认是拿不到你浏览器里的登录 Cookie 的。这时候要么给它配置测试账号，要么把鉴权逻辑 mock 掉，否则它会一直卡在登录页。

7. 常见问题与排查技巧实录

7.1 高频报错速查表

我把这段时间遇到的报错和对应解法整理成了表格，方便各位直接对着排查。

7.2 配置 JSON 的坑

手改配置 JSON 时最容易出问题的是格式错误。JSON 不允许注释，不允许末尾多余逗号，这是两个高频雷区。opencode 在读取配置失败时一般会在终端里给出错误提示，但有时候提示不够直观。我的经验是改完配置先跑一下opencode，如果能正常进入交互界面，说明配置没问题；如果直接报解析错误，大概率就是某个逗号或括号写错了。

另外，provider配置里的models字段，模型 ID 必须和服务商平台上的 ID 完全一致，大小写也要一致。我之前就因为把gpt-4o写成了GPT-4o，白折腾了半天。

7.3 我第一次用 opencode 时踩过的三个坑

第一个坑是装完 npm 包后直接敲opencode，结果终端完全不认识这个命令。我当时第一反应是安装失败了，卸载重装了一遍，还是不行。最后才发现是 PATH 没配好，白白浪费了二十分钟。所以遇到命令找不到的问题，先查 PATH 和终端会话，不要急着卸载重装。

第二个坑是第一次让它跑一个 Python 项目的测试，它执行测试命令后一直失败，我以为是它改坏了代码，仔细看日志才发现是项目要求的 Python 虚拟环境没激活。从那以后我养成了习惯，让 Agent 干活前先把项目的 README、启动脚本和环境要求告诉它。

第三个坑是让它复现一个前端 bug，它写的 playwright 脚本在本地浏览器上通过了，但 CI 环境里挂掉了。后来排查发现是本地浏览器版本和 CI 的浏览器版本不一致。前端自动化这类事情，环境一致性是绕不开的问题，这个坑跟人写脚本会遇到的一模一样，Agent 也逃不掉。

7.4 让 opencode 更好用的四个小习惯

用久了之后，我慢慢总结出几个让 opencode 产出质量更高的习惯，这里一起分享给大家。

一是每次任务尽量聚焦。你让它“先看看这个项目，然后顺手优化一下登录模块的性能，再写几个单元测试”，它往往会顾此失彼。一次只交代一件事，比什么都写清楚，Agent 的执行质量反而更高。

二是关键约束要在任务描述里前置。比如“不要修改公共包的代码”“请保持现有代码风格”“接口返回格式必须兼容旧版本”，这些约束如果在 Agent 已经开始动手之后才提，它可能已经产生了大量需要重写的代码。

三是善于用--continue或opencode的多轮对话能力。如果上一次会话没有完成任务，下次可以继续对话而不是重新开一个，这样它能保留上下文，不需要重读项目，效率高很多。

四是定期把有用的指令沉淀为 Skill。比如你发现某个 prompt 组合在同类任务上效果非常好，就别每次手打一遍，直接把它固化成 Skill。这也是 opencode 生态里最值得花时间投入的部分。

最后再分享一个小技巧

按标题和热词来看，很多人是从 VSCode 插件、IDEA 插件、桌面版这些入口认识 opencode 的。但我个人还是建议，不管用什么前端界面，都先把命令行版的安装配置走一遍。原因是插件和桌面版都依赖 opencode 核心，命令行版就是那个最底层的引擎。你只有先把引擎跑通，再去套各种 UI，后面遇到问题才不至于一头雾水。

另外，opencode 迭代速度非常快，社区几乎每周都有新功能和修复。如果遇到某个 bug，可以先看看是不是版本太旧了，执行一次升级说不定问题就消失了。我用它这段时间最大的感受是，终端 Agent 这股趋势已经实实在在影响到了日常开发方式，而 opencode 目前是这条路上走得比较稳、也比较开放的一个选择。希望这篇经验分享能帮你少踩点坑，早点把它用顺手。