企业官网建设流程全解析

最近一个月，我把大部分日常编码工作流从 Claude Code 迁到了一个叫 OpenCode 的开源终端 AI Agent 上。起因是团队里接手的项目越来越多，闭源的 Agent 工具在模型选择、配置管理和多人协作上越来越别扭，碰巧看到 OpenCode 的讨论热度上来，就抽了个周末整体迁移。这一试就回不去了：它开源、模型不锁死、配置落在项目里的opencode.json，团队拉下仓库就是同一套 Agent 规则。这篇文章从安装、模型接入、Skills 与 LSP 配置，到 Playwright 调前端 Bug 的实测过程都整理一遍，最后附上我踩过的高频报错和排查思路，给正在选型或准备迁移的人一个参考。

1. 终端 AI Agent 到底在解决什么问题，OpenCode 凭什么上位

1.1 从“自动补全”到“能自己动工的初级工程师”

过去几年大多数人用的 AI 编程工具还停留在 IDE 补全插件层面，它能帮你写函数、补注释，但理解不了跨文件的调用关系。比如一个前端筛选组件失灵，根因可能藏在某个 hook 的依赖数组里，IDE 补全完全插不上手。OpenCode 这类终端 Agent 解决的是更上层的问题：它能把仓库读一遍，定位相关代码，自己跑测试，改完文件后给你看 diff。本质上，它承担的是一个初级工程师的角色——你给它布置任务，它去执行，执行过程中发现矛盾还会停下来问你。

这也是为什么这类工具适合“接手开发项目”的场景。新接一个老项目时，最快的方式不是逐行读代码，而是让 Agent 先梳理入口、依赖、启动方式、测试命令，把整个项目的结构文档化，你再针对关键路径做人工核对。

1.2 OpenCode 与 Claude Code、Codex CLI 的关键差异

我在迁移前后把三个主流终端 Agent 都跑了一遍，差异主要体现在下面几个维度：

坦白说，Claude Code 在 Anthropic 系模型上的完成度确实高，但项目一旦需要切换模型，或者团队里有人想用别的供应商，闭源工具就有点绑手绑脚。OpenCode 的做法是把模型抽象成 Provider，同样的配置结构可以指向 Anthropic、OpenAI、本地 Ollama，也可以指向其他兼容 OpenAI 协议的服务，换模型改一行配置就行。这个灵活度很适合多模型对比和预算敏感的场景。

2. 安装与启动：命令行、桌面版、IDE 插件一次讲完

2.1 一条命令装好：macOS/Linux 与 Windows 的区别

官方主推的方式是终端一键安装脚本，macOS 和 Linux 下直接在终端执行官网给的那条curl ... | bash命令就能装好。如果你不习惯这种联网执行脚本的方式，有几个替代路径：

• npm 全局安装：执行npm i -g opencode-ai，装完后终端里可用的命令是opencode，不是opencode-ai。这个细节很多人会忽略，装完直接敲opencode-ai当然会提示找不到命令。
• Homebrew：macOS 用户也可以走brew install的路径，好处是升级、卸载都归 brew 管，适合不喜欢手动管全局包的人。
• Windows：建议优先用官方安装脚本，或者包管理器方式，因为 Windows 的 PATH 问题很多。装完如果 PowerShell 还是提示无法识别opencode，先重开一个终端窗口再试，大概率是会话环境变量没刷新。

装好以后执行opencode --version，能打出版本号就说明命令行部分没问题。终端 TUI 界面会在你直接执行opencode时启动，里面是类似聊天的交互界面，支持几个常用斜杠命令，比如/help查看所有命令、/models切换模型、/init在当前目录生成配置文件。

2.2 首次启动与认证：跑通第一轮对话

首次启动时，OpenCode 会引导你登录。它会把你选择的 Provider 和认证信息写入本机的配置目录，实际 Key 不会出现在项目里，这一点做得比较干净。如果你习惯用环境变量管理密钥，也可以在启动前把对应的变量导好，比如 Anthropic 的ANTHROPIC_API_KEY、OpenAI 的OPENAI_API_KEY。OpenCode 在启动时会自动读取这些标准环境变量，省掉一次手动登录。

我个人更推荐的做法是：在项目根目录放一个opencode.json，通过它声明某个目录默认用哪个模型、权限边界是什么，而不是在全局配置里塞一堆 Key。这样一个仓库就是一个完整上下文，换机器、换人都能快速复现。

2.3 桌面版和编辑器插件的适用范围

OpenCode 不仅有终端 TUI，现在也有桌面版，以及 VSCode 和 JetBrains 系插件。我的实际使用习惯是：终端 TUI 用于批量任务和跑测试，IDE 插件用于“边看代码边让 Agent 改”，尤其看 diff 的时候 IDE 插件体验更好，能直接看到每个文件修改位置，还可以点开上下文。

桌面版适合那类不想开终端、想有个独立窗口管理多个项目的用户。不过它本质上是把终端和配置管理包了一层 GUI，底层逻辑没变。如果你已经熟悉命令行，直接用 TUI 就行，桌面版更多的价值是降低新手上手门槛。

3. 模型接入与配置：从官方 API 到免费模型的正确姿势

3.1 API Key 不要写进代码，用 auth 命令管理

最常见的新手错误是把 Key 写进项目里的配置文件，然后提交到仓库。OpenCode 提供认证命令来管理这些敏感信息，运行后按提示选择模型服务商并粘贴 Key，它会安全地保存到系统配置目录，项目文件里不残留任何密钥。

如果团队用 CI/CD 或者需要自动化调用，可以改成环境变量注入的方式。这里有一个优先级需要了解：环境变量通常优先于配置文件里的明文设置，所以哪怕项目里有人不小心写了测试 Key，也不会覆盖你环境里的真实 Key。这也是排查“为什么我配置了 A 模型却实际调用了 B 模型”时最先要检查的地方。

3.2 opencode.json 的核心配置长什么样

配置文件的入口字段不多，但每个都很关键。我一般会至少配置这几项：

• model：默认模型标识，写明完整的模型名，避免每次启动都手动选。
• provider：模型服务商，也可以是兼容 OpenAI 协议的自定义端点。
• permission：控制哪些命令需要你确认，比如bash操作、文件写入、网络请求。这是安全底线，不能省。
• mcp：如果需要接入 MCP Server，在这里注册。
• instructions：指向一个说明文件路径，里面写项目规范、编码约束、禁用规则。团队协作时部门规范全放这里。

具体字段名和可选值建议以你安装版本执行/config看到的为准，因为项目迭代快，字段名有变化是正常的。关键是把配置放进仓库后，让团队成员都执行一次opencode /init，生成基于项目结构的新配置，再对比我上面列的核心项做增量修改，不要直接复制别人机器上的整个文件。

3.3 免费模型怎么选：官方免费额度、本地模型与第三方网关的取舍

热搜里“opencode 免费模型”出现频率很高。真实可用的免费路径大概有三类：

1. 官方平台的试用额度：主流模型服务商注册后会送一定量的免费调用额度，用于评估和测试完全够用。缺点是额度有限，不适合高强度的日常开发。
2. 本地模型：通过 Ollama 这类工具在本地跑开源模型，比如 Qwen 系列、Llama 系列。优点是不花钱、数据不会出机器，缺点是中等参数模型在代码理解深度上跟商用闭源模型还有差距，更适合敏感项目和个人学习。
3. 第三方模型网关：市面上有一些把多家模型 API 聚合到一起的服务，OpenCode 也能对接。这类服务省去了分别管理多个 Key 的麻烦，但风险点在于数据会经过第三方，且服务质量参差不齐。我的态度很明确：对于涉及商业代码的项目，优先走官方 API；个人折腾可以尝试，但不要在非官方渠道买所谓“共享 Key”或“不限量套餐”，这类渠道很容易泄漏 Key，而且稳定性毫无保障。

我自己的选择是：主力开发用官方 API 对应的强模型，本地用 Ollama 跑一个小模型作为离线兜底，这样断网时也能做一些简单重构。

3.4 Provider 配置错了最容易出现的症状

Provider 配置错误的典型症状是：对话能正常开始，但一执行代码类工具就报错，或者模型返回的内容特别“空”，明显不对。排查路径是先确认opencode.json里的provider和实际端点是否匹配，再确认环境变量没被覆盖，最后看日志。OpenCode 有调试日志开关，运行时可以打开 verbose 模式，它会把每次 API 请求的模型名、token 数、耗时打出来，一眼就能看出有没有走错服务商。

4. Skills、Memory 与 LSP：让 Agent 真正吃透你的工程

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

Skills 这个概念最早是从 Anthropic 的技能体系里火起来的，OpenCode 社区也支持类似机制。本质上它是一组可以随时被 Agent 调用的“技能包”，以目录和SKILL.md的形式组织。你可以把日常反复做的工作沉淀成技能，比如：

• 新页面开发规范：路由怎么加、组件放哪个目录、样式用哪套 Token。
• 组件测试模板：提交代码前必须生成哪些测试用例、断言风格是什么。
• 代码审查清单：检查性能、边界、可访问性、日志规范。

每个技能目录里有一个SKILL.md，用自然语言描述技能用途和调用方式，还可以附带参考文件。Agent 遇到与技能相关的任务时，会按技能文件里的指导执行。这样团队规范不是躺在文档里吃灰，而是真正长在 Agent 的行为逻辑里。

4.2 Memory：让 Agent 记住项目上下文和你的口味

Memory 解决的是“这次会话结束后，Agent 忘了你上回交代的事”这个痛点。你可以在配置里指定记忆文件的读取路径，也可以要求 Agent 在会话结束时把关键决策追加到记忆文件里。比如项目用的包管理器、测试命令、代码风格偏好，都可以沉淀下来。

我通常会把三类内容写进记忆：一是项目的地图，包括关键模块在哪、启动入口在哪；二是“不要做”清单，比如不要去改生成器产物、不要擅自升级某个核心依赖；三是当前迭代的重点方向，方便 Agent 在提出修改方案时优先匹配主线。这样即使隔了一周再打开 Opencode，它也能快速接上上下文，不用每次重建工程认知。

4.3 LSP：让 AI 写的代码先过编译器再给你看

LSP 集成大概是 OpenCode 比很多同类工具更“工程化”的一点。启动时会启动对应语言的 Language Server，用于提供代码诊断、跳转定义、引用查找等能力。这对 AI 编码质量的提升非常直接：Agent 改完代码后，编辑器里能立刻看到类型错误、未引用的变量、语法问题，不需要等编译才发现。

比如在 TypeScript 项目里，Agent 经常犯的错是引入一个不存在的导出，或者把一个可选属性当成必填属性用。有了 LSP，这类错误在 Agent 写完代码后马上被识别出来，它自己就能完成修复，不用把问题抛回给你。配置 LSP 的核心是告诉工具你的项目类型和入口，多数场景下它能自动检测，遇到复杂的 monorepo 才需要手动指定目录。

4.4 从 oh-my-claudecode、superpowers 这类社区配置集里能借鉴什么

社区里流传的配置集，比如 oh-my-claudecode、superpowers，本质上是一组预设好的 Skills、指令模板和工作流。如果你不想从零开始搭，可以直接拿它们的思路来做裁剪。我个人不建议全量套用，因为这类配置集往往包含大量通用规则，会显著增加 token 消耗，而且很多规范跟你团队的实际风格冲突。正确做法是：把这些配置集当成灵感库，挑出真正贴合自己场景的两三个技能，写进自己的 SKILL.md。

5. 实测复盘：用 OpenCode 配合 Playwright 修一个前端 Bug

5.1 场景与前置准备

这周同事报了一个问题：列表页的筛选条件在切换排序后丢失，刷新页面又恢复。这类问题很典型，根因通常在状态管理或 URL 参数同步。我当时决定让 OpenCode 配合 Playwright 来跑完整排查链路，验证它到底能不能独立解决“前端 Bug”这种需要交互验证的问题。

前置条件有两个：一是项目里已经装好了 Playwright 相关的测试依赖，二是 OpenCode 能在这个项目里读到测试脚本目录。如果你已经通过 MCP 接入了 Playwright Server，效果会更好，Agent 可以直接驱动浏览器完成打开页面、点击、断言、截图的动作。没接 MCP 也没关系，让 Agent 直接执行已有的 Playwright 测试用例文件，同样能定位大部分问题。

5.2 给 Agent 下达任务时的指令模板

这里有个关键经验：不要只丢一句“这个筛选 bug 帮我修一下”，要给出可验证的输入和期望输出。我当时的指令大概是：

• 在e2e目录下查看现有的筛选和排序测试用例，先跑一遍确认是否通过。
• 按 Bug 描述写一个最小复现用例：打开列表页，设置筛选条件 A，切换排序方式，断言筛选条件仍然生效。
• 跑测试，把失败信息作为线索，追查状态管理和 URL 参数相关代码。
• 修改代码后，重新跑测试，确保旧用例和新用例都通过。
• 最后用一句话总结根因，并给出改动文件清单。

OpenCode 的执行逻辑是先读取项目结构，找到相关页面组件和状态管理代码，再根据测试失败信息做代码定位。整个过程它会在终端里实时打印执行步骤，你能看到它在跑哪些命令、读了哪些文件。

5.3 执行结果与过程中暴露的问题

实测下来，Agent 定位根因的速度比我预期快。它通过测试失败信息很快锁定到排序状态没有写入 URL 参数，而是保留在组件内部 state 里，一旦触发重新渲染，筛选条件就被覆盖。修复方案也基本合理，在排序变化时把参数同步进 URL 查询字符串，再在初始化时读取。

但过程中暴露了两个值得注意的问题：

• Agent 第一次修复时只改了排序逻辑，没有考虑筛选条件和排序同时变化的时序问题，是回归测试跑出来的失败提醒了它补充处理。
• 它在修改代码后运行测试的命令比较激进，直接跑全量测试集，耗时较长。后来我在指令里加了“只跑相关测试文件”，执行效率明显提升。

5.4 把 Playwright 测试能力固化成常规手段

这次之后，我把“前端改动必须跑相关 e2e”写进了项目记忆里。以后 OpenCode 在修改任何前端组件时，都会主动检查有没有对应测试，没有的话先补一个再改代码。这比口头约束靠谱得多，因为规则嵌到了工作流里，不需要每次重新叮嘱。

如果你想更进一步，可以给 OpenCode 配置 Playwright 的 MCP Server，让 Agent 具备直接打开浏览器交互测试的能力。这样它不仅能跑已有测试，还能自己打开页面验证视觉表现、点击和滚动，甚至截图给你看。不过我建议在大规模启用前先跑通两三个试点项目，因为权限越大，误操作的风险也越高。

6. 常见报错与排查手册：从安装失败到模型不可用

6.1 Windows 提示“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”

这个报错本质是 PowerShell 在 PATH 里找不到opencode可执行文件。由低到高排查三步：

1. 确认安装真的成功：重新执行安装命令，看最后有没有输出安装路径或版本号。
2. 重开终端窗口：PowerShell 不会实时刷新环境变量，新装的全局命令往往要新开窗口才生效。
3. 检查 npm 全局 bin 目录是否在 PATH：执行npm prefix -g找到全局目录，确认对应的 bin 路径在系统 PATH 中。如果不在，把该路径加到用户环境变量里，再重开终端。

如果用的是官方一键脚本安装，安装器通常会处理好 PATH，问题多出在 npm 全局安装时机器上 Node.js 路径配置不完整。

6.2 运行时提示“unexpected server error. check server logs”

这个报错的含义是请求已经发出，但服务端返回了异常，OpenCode 自己也拿不到更多上下文，只能让你看日志。我遇到的概率分布大概是：API Key 无效占四成，Provider 端点配错占三成，限流或服务商临时故障占两成，剩下的是本地网络问题。

排查链路建议：先打开 verbose 日志，看请求发给了哪个 URL、返回的 HTTP 状态码是什么。如果状态码是 401，几乎可以确定是 Key 的问题；如果是 429 或 5xx，基本是限流或服务商侧故障；如果请求根本没发出，重点查本地网络和代理设置。日志里会打完整请求 URL，这一条信息能帮你区分 80% 的情况。

6.3 “this model is not available in your country”

这个报错跟模型服务商的区域分发策略有关，意味着当前网络出口区域没有获得该模型的调用许可。正确做法是：去官方文档查看该模型的支持范围，确认是否覆盖你所在的区域；如果服务商提供了兼容替代模型，切换到替代模型；如果仍不行，联系服务商获取准确的支持说明。不要在非官方渠道寻找所谓“解除限制”的方案，既不安全，也可能违反服务条款。这类问题本质上不是 OpenCode 的 bug，它在报错信息里已经写得很明确了，你换一个当前区域可用的模型或 Provider 就能继续工作。

6.4 接手大项目时 Agent 经常卡住怎么办

接手历史项目时，OpenCode 最容易卡在两件事上：依赖安装失败和本地服务起不来。代码本身读不懂的概率反而很小，因为 Agent 的上下文窗口足够大。我的建议是，在真正让它改代码之前，先花十分钟做一个“项目体检”：让它读一遍 README，梳理出启动命令、环境变量和关键目录，再让它启动本地服务并跑一遍现有测试。这个过程能暴露很多环境问题，而且成本很低。

如果项目依赖非常陈旧，安装依赖时反复出错，不用在同一个坑里耗太久，先看错误日志判断是网络源的问题还是依赖本身在新 Node 版本下不兼容。必要时手动装一下卡住的包，再继续让 Agent 推进。

6.5 Linux 下修改 opencode.json 不生效

很多人在 Linux 上改完配置文件发现不生效，原因通常是改错了文件路径。项目级配置应该放在项目根目录的opencode.json，而不是用户主目录里的全局配置。如果你确实想改全局默认值，要定位到 OpenCode 自己的配置目录，不同版本目录名可能不同，执行相关配置命令查看当前读取的配置路径最可靠。另外一个常见问题是 JSON 格式不合法——多一个逗号或少一个引号，整个文件会被静默忽略。改完配置后可以先确认 JSON 格式正确，再启动工具。

最后再分享一点我的实际使用体会

工具再好，也得有配合的工作习惯。OpenCode 这类 Agent 的上限不取决于模型有多强，而取决于你会不会把任务拆解清楚、把验证步骤交代清楚。我现在每次让它动手前，都会在指令里带上“怎么判断改成功”的标准，要么是测试通过，要么是特定命令输出符合预期，这比任何提示词技巧都管用。

如果你正在从其他终端 Agent 迁移过来，建议不要在第一个项目就全量切换。挑一个小型前端项目或脚本库，把配置、Skills、LSP、记忆全部跑通，再逐步扩大使用范围。等团队里所有人都在用同一套opencode.json和技能库时，你会明显感觉到：很多以前靠口头交代的工程约束，现在变成了 Agent 的默认行为，协作成本低了一大截。