企业官网建设流程全解析

如果你最近在折腾AI编程工具，大概率会看到opencode这个名字频繁出现。它来自SST团队，一个做开发者基础设施的开源组织，和Claude Code、OpenAI Codex这类老牌终端Agent放在一起比较时，opencode最显眼的标签就是：开源、多模型、终端原生，以及一套非常干净的配置文件体系。

我大概是两周前把日常主力Agent从Claude Code切到了opencode，起因倒不是Claude Code不好用，而是项目里的MCP服务越来越多、模型也想在不同供应商之间换来换去，Claude Code的配置体系越卷越重。opencode把这一切收敛成了两个JSON文件加一个本地服务，模型可以随时换，运行日志也透明，这对我是刚需。这篇文章就记录我这段时间的完整上手过程，从安装到配置免费模型，从Skills到Memory，从VSCode/IDEA插件到用Playwright让Agent自己复现前端Bug，还包含大量报错排查记录，希望给正在观望或者已经装上但没玩明白的朋友一份能直接照着做的参考。

1. opencode是什么：一个重新思考过的终端AI编程Agent

1.1 为什么我从Claude Code迁移过来

先说结论：不是Claude Code不好，而是opencode更适合“模型中立”的开发者。Claude Code很强，但它的配置和生态始终围绕Anthropic的模型展开，一旦你想换成别的模型，或者想在同一套Agent里对比各家模型的表现，就会觉得很别扭。

opencode在这一点上做得非常彻底。它的模型抽象层基于Vercel AI SDK，只要是OpenAI兼容格式的API都能接进来，甚至你可以自定义一个本地兼容服务，把请求路由到任意模型上。对我来说这意味着：同一个项目、同一套Skills、同一条指令，我可以随时在Claude、Gemini、本地模型之间切换，而不需要改任何业务代码。

还有一个让我愿意切换的关键点是透明。opencode安装后会启动一个本地服务，所有请求和响应都会记录在日志里，出了问题可以直接看请求报文和响应报文。之前用Claude Code时，遇到“Agent自己改了配置”“上下文被悄悄截断”这类问题，排查起来非常痛苦。opencode把日志和diff都摊开给你看，心态上踏实很多。

1.2 与Codex、Claude Code、Pi的基础对比

这几款终端Agent我最近都实际用过，简单做个横向对比：

选型建议很简单：如果你重度依赖Anthropic模型，并且不打算换，Claude Code已经是天花板；如果你希望一套Agent配置同时应对多个模型供应商，并且享受“改JSON等于换模型”的灵活度，opencode更合适；如果你每天都在ChatGPT Plus生态里工作，Codex的集成度会让你更顺手。至于Pi，我试下来觉得它更适合偏聊天交互的场景，做严肃的工程重构时，opencode的Plan/Build模式更可控。

1.3 opencode适合什么类型的开发者

从我的体验来看，这批人最适合把opencode用起来：

• 开源项目维护者。需要频繁审视Agent提交的代码，opencode的权限控制和diff展示非常友好，不会让Agent乱动手脚。
• 需要在多个模型之间切换对比的人。无论是比效果还是比成本，opencode的模型配置就是一组JSON字段，切换成本几乎为零。
• 被桌面IDE卡到内存焦虑的人。opencode本体是一个终端TUI，资源占用比Electron类编辑器小太多，跑在老MacBook上很流畅。
• 团队需要标准化Agent行为的人。Skills机制可以把团队的代码规范、测试流程、发布检查变成Agent自动执行的技能，这是其他工具很难做到的。

2. opencode安装：从零到跑通第一个对话

2.1 三种安装方式与选择建议

opencode的安装方式很常规，官方提供了脚本、npm和Homebrew三种渠道。我个人的建议是：有Node.js环境就用npm，macOS用户用Homebrew也行，最省心的其实是官方脚本。

# 方式一：npm全局安装（需要Node.js） npm install -g opencode-ai # 方式二：Homebrew安装 brew install sst/tap/opencode # 方式三：官方脚本 curl -fsSL https://opencode.ai/install | bash

注意包名是opencode-ai，不是opencode。很多人在npm上找不到或者装错包，就是被这个名字坑了。Windows用户还可以用Scoop安装，scoop install opencode，但这个包未必是最新版本，我的建议还是走npm。

装完以后，直接在项目目录下运行opencode，会进入TUI交互界面。如果想跳过TUI直接执行任务，可以这样：

opencode "帮我分析一下src/main.go的入口流程，并输出调用关系"

这是opencode一个很香的设计，非交互模式可以直接挂在CI或者脚本里用，后面接--model参数还能临时切换模型，比如强制用便宜的模型跑一遍快速检查。

2.2 Windows报错“无法将‘opencode’项识别为cmdlet”的完整排查

这个报错在热搜里出现了，也是Windows用户装完后第一道坎。报错原文是：opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。别慌，基本上只有两个原因。

第一个原因是npm的全局安装目录根本不在你的PATH里。Node安装后，全局包路径默认在C:\Users\你的用户名\AppData\Roaming\npm，如果这个目录没加进系统变量，无论装什么全局命令都跑不起来。排查方法很简单：

npm root -g

把输出的路径添加到系统环境变量的Path里，重开终端，再试opencode --version。这时候如果还没好，多半是PowerShell执行策略挡住了。npm会在全局目录下生成opencode.ps1，而Windows默认执行策略可能禁止运行脚本，报错就变成“无法加载...因为在此系统上禁止运行脚本”。执行下面这行放开当前用户限制即可：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

这里有个小坑：RemoteSigned只信任远程签名脚本，本地创建的ps1可以跑，但如果是从网上直接下载的脚本，可能还是会被拦。如果不想动执行策略，也可以直接使用opencode.cmd，它不会受这个限制影响。

第二个常见原因是安装中断或者版本冲突。遇到这种情况，先卸载再重装，比人肉清残留变量快得多：

npm uninstall -g opencode-ai npm cache clean --force npm install -g opencode-ai

重装后再用where.exe opencode验证命令路径。如果能看到路径输出，说明命令本身已经生效了。

2.3 首次启动：认证、模型供应商与项目打开

装好后第一次运行opencode，最优先做的是认证。在TUI里输入/auth或者直接跑opencode auth login，会进入一个交互式面板，可以添加多个模型的API Key，比如Anthropic、OpenAI、Google Gemini，以及任意自定义供应商。

我强烈建议用系统钥匙串来存Key，而不是把Key写进终端环境变量。opencode在登录时会把Key安全地存到系统钥匙串里，之后运行不会再让你反复粘贴。如果实在要用环境变量，也记得以ANTHROPIC_API_KEY这类前缀命名，而不是找个随便的变量名硬塞。

首次启动时opencode会检查当前目录和上级目录里的配置文件，包括opencode.json、AGENTS.md、CLAUDE.md等，一旦发现项目级配置就会自动加载。所以打开项目的正确姿势是：先cd到项目根目录，再运行opencode。如果你在~下打开，它能看到的项目上下文就是空白的，回答质量会差很多。

另外提一嘴，opencode运行时会在本地起一个服务，终端会打印出类似Local: http://127.0.0.1:xxxxx的信息，这是IDE插件和桌面版连接它的通道，不用关掉。如果端口被占，可以在配置里改端口，后面讲配置的时候会提到。

3. opencode配置：模型、参数与免费模型接入

3.1 核心配置文件：opencode.json与config.json

opencode的配置体系很轻，但不同版本之间有过命名调整，早期版本用的是config.json，后来统一成了opencode.json。所以网上教程经常打架，有的人说改这个、有的人说改那个，其实是版本差异。我的建议是：先运行一次opencode，让它生成默认配置，然后用编辑器打开配置文件，带JSON Schema提示的那份就是你要改的。

opencode配置分两个层级。全局配置放在用户目录下，作用于所有项目；项目级配置放在项目根目录，会覆盖全局配置。我习惯把全局配置只放API Key和通用偏好，把模型列表、权限规则、MCP服务这些跟项目强相关的内容放在项目里，这样clone一个新仓库时，配置能跟着代码走。

一个典型的配置文件长这样：

{ "$schema": "https://opencode.ai/config.json", "autoupdate": true, "theme": "opencode", "model": "my-provider/my-model", "provider": { "my-provider": { "npm": "@ai-sdk/openai-compatible", "name": "My Provider", "options": { "baseURL": "https://api.example.com/v1", "apiKey": "{env:MY_API_KEY}" }, "models": { "my-model": { "name": "My Model" } } } }, "permission": { "edit": "ask", "bash": "ask", "webfetch": "allow" } }

provider定义了“模型从哪来”，models定义“有哪些模型可选”，model决定默认用哪个模型。这个结构非常直白，只要理解一遍，后面所有模型切换都靠它。

3.2 免费模型接入的通用做法

很多人问我opencode能不能用免费模型，答案是可以，而且配置思路和收费模型没有任何区别，就是增加一个provider。只要对方提供OpenAI兼容API，opencode就能适配。

最典型的免费渠道是Google Gemini系列。去官方平台申请一个API Key，创建自定义provider，填写兼容接口地址和Key，就可以在opencode里用Gemini的免费额度了。以Gemini为例，配置大概是这样：

{ "provider": { "gemini": { "npm": "@ai-sdk/openai-compatible", "name": "Google Gemini (OpenAI Compatible)", "options": { "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/", "apiKey": "{env:GEMINI_API_KEY}" }, "models": { "gemini-2.0-flash": { "name": "Gemini 2.0 Flash" } } } } }

另一个经常被用到的渠道是OpenRouter，它的免费模型都带:free后缀，配置方式就是设一个OpenAI兼容的provider，baseURL填https://openrouter.ai/api/v1，然后在models里列出你想用的模型名。这里要提醒一句：免费模型的稳定性参差不齐，同一个模型一天之内响应速度可能差好几倍，建议在opencode里配两个备选模型，一个主力一个救急。

网络上有些教程会推荐一些第三方聚合网关，说什么hy3-free之类，我的态度一直是：小众网关适合临时折腾，不适合当主力。这类服务挂掉就像吃饭吃到一半老板跑路，既影响效率又没法追责，真要用也一定要在项目配置里留好退路。

3.3 常用配置参数与模型选择建议

除了provider，下面几个配置项几乎没有争议，属于开箱必改。

permission是最重要的安全开关。我默认开"edit": "ask"和"bash": "ask"，这样Agent每次要改文件或者执行命令前都会征求我的意见，虽然多了一步确认，但能防止它脑补一个离谱的删库命令。如果你在写一个纯文档项目，可以把edit改成allow省得烦；如果你在做一个包含生产数据读取的运维脚本，我建议把bash也改成deny，彻底禁止Agent执行危险命令。

autoupdate建议设成true。opencode迭代非常快，旧版经常有奇奇怪怪的模型兼容问题，自动更新能少踩很多坑。theme按个人喜好来，我喜欢opencode默认主题，高亮对比度适中，长时间盯终端不疲劳。

模型参数上，代码任务我一般把temperature控制在0到0.3之间。超过0.5代码就开始“自由发挥”，经常给你整出一些看起来很优雅但根本跑不起来的方案。想快速验证配置是否生效，可以运行：

opencode models

它会列出当前配置里所有可用的模型。如果这里看不到你新加的模型，说明provider配置有问题，优先检查baseURL和apiKey。

4. 从聊天到写代码：核心使用方式复盘

4.1 Plan/Build双模式：先规划再动手

opencode的TUI里最核心的是Plan和Build两种模式。我把它理解为“先出方案，再动代码”，和真实团队里写方案再实施的工作流完全一致。

在Plan模式下，Agent会调研项目、分析代码、输出一份实施计划，但不改任何文件。你可以把它当成一个免费的技术顾问，先看它对整个任务的理解是否正确。确认方案没问题后，Tab切到Build模式，让它真正动手。这个设计让我避免了很多次“方向错了还改了一堆代码”的悲剧。

举个例子，有一次我让它重构一个用户登录模块。Plan模式下它发现了项目中已有一个我没有注意到的token刷新逻辑，然后建议把新逻辑挂在现有拦截器上，而不是另起一套。如果直接让它开干，大概率会好心办坏事，把原有鉴权逻辑一起推翻。Plan模式不是必须的流程，但对于复杂重构，花几十秒让它先列计划，收益非常高。

非交互模式也能使用Plan/Build模式区分，命令大致是这样：

opencode "分析当前支付模块的异常处理，列出需要加固的3个点" --agent plan

挂上--agent plan参数，opencode就只输出计划不碰代码。用脚本批量跑项目健康检查时，这个功能非常实用。

4.2 文件修改审批与LSP补全

在Build模式下，Agent每提出一个文件修改，opencode都会把改动以diff形式展示给你。配合permission.edit: ask，你可以逐文件审查，确认无误后再应用。

这里必须夸一下LSP集成，这是opencode和普通聊天Agent最大的区别之一。它在本地会启动语言服务器，意味着Agent“看到”的代码不是纯文本，而是带类型信息、带编译错误的语义化代码。实际效果就是：它改代码时会更合理，比如自动补齐未导入的类型，或者在你改了函数签名后，同步提醒调用方需要调整。这对TypeScript项目尤其明显，我在一个Vite + React项目里让opencode改接口返回结构，它居然自动把相关组件的类型标注一起修正了，这一点很多同类工具做不到。

如果你不想让Agent乱动格式，可以在项目配置里把格式化工具交给Prettier，让Agent只改逻辑不改格式。opencode本身支持外部格式化工具集成，具体配置位是format字段，设置成你的格式化命令即可。

4.3 Skill机制：给Agent装“岗位说明书”

Skills是目前opencode社区最热的话题之一。简单理解，Skills就是给Agent的一份“岗位说明书”。它不是一句临时prompt，而是放在项目里的结构化技能文件，Agent在处理相关任务时会自动加载并遵循。

创建方法很简单：在项目根目录建一个.opencode/skills目录，每个技能是一个Markdown文件，文件头部用YAML frontmatter写元信息，正文写详细操作步骤。一个代码审查技能的模板大概是这样的：

--- name: code-review description: 执行代码审查时，遵循团队的Checklist规则 --- # Code Review Checklist 1. 检查是否有未捕获的Promise异常 2. 检查是否直接修改了props或state 3. 检查是否有遗留的console.log 4. 检查样式是否依赖了全局class

写好之后，你在聊天里提到“帮我做一次代码审查”，Agent就会自动加载这个技能，按里面的Checklist逐项检查，而不是泛泛地看一遍。社区还流传一些成熟的技能包，比如superpowers这类集合，安装方式基本是clone下来，然后在配置里把skills路径指到对应目录。我这里多说一句：技能不是越多越好，如果一个项目放了几十个技能，Agent加载上下文会变得很重，实际响应会变慢。按需放三五个最常用的就够。

4.4 Memory配置：让Agent记住项目上下文

刚开始用opencode的人都有一个痛点：每个新会话Agent都像失忆了一样，忘了项目的技术栈、忘了代码风格、忘了之前定的规范。opencode的解法是让项目根目录的AGENTS.md来充当长期记忆。

我在每个项目里都会维护一份AGENTS.md，它可以在会话开始时被opencode自动读取，相当于给Agent一份“入职手册”。我的模板一般包含四部分：项目概览、代码规范、常用命令和架构约定。

# 项目概览 - 技术栈：React + TypeScript + Vite - 前端路由：React Router - 状态管理：Zustand # 代码规范 - 组件文件使用PascalCase命名 - 所有API请求统一走src/api/client.ts - UI样式优先使用Tailwind，禁止内联style # 常用命令 - 启动开发环境：pnpm dev - 运行测试：pnpm test - 构建产物：pnpm build # 架构约定 - 页面级组件在src/pages - 可复用组件在src/components - API类型定义在src/types/api.ts

有了这份文件，opencode新会话里写出来的代码明显更“懂规矩”。如果你有些全局习惯，比如提交信息规范、注释语言、变量命名风格，也可以放在全局配置的custom instructions里，这样任何项目都会遵守。实测效果是，切换新项目后第一次对话，Agent给出的代码风格和项目原有代码几乎一致，省了来回纠正的功夫。

5. 进阶玩法：插件、桌面版与老项目接手

5.1 在VSCode和JetBrains IDEA里用opencode

opencode不是只能活在终端里，官方提供了VSCode和JetBrains系插件。VSCode插件在扩展市场直接搜opencode就能装，装好后它会连接本地运行的opencode服务，你可以在编辑器侧边栏里看到当前会话、浏览diff、甚至把选中的代码块直接发给Agent。

IDEA插件同理，在插件市场搜opencode，安装后会在工具窗口里打开一个同步会话面板。我个人的使用习惯是：签入代码前用IDEA插件对比Agent的改动，方便和现有IDE的Git集成一起使用。插件的响应速度和终端TUI基本同步，因为底层共享同一个服务进程。

要注意的是，插件只是“遥控器”，核心的Agent进程还是在后台跑。如果你在终端里关了opencode，插件的会话也会断开。所以正确姿势是让opencode一直开着，终端可以关掉面板，服务不退出就行。

5.2 OpenCode Go与CC Switch的搭配

社区里很多人在讨论opencode go和cc switch，这两个工具实际上解决的是同一个问题的两个侧面。CC Switch是给Agent工具切换模型供应商配置的面板工具，而OpenCode Go则像一个模型聚合入口，把多个模型出口聚合成一个本地OpenAI兼容服务。

我用下来的感受是：这两个工具配合opencode，最大的价值是让“换模型”变成一件无感的事。比如你项目配置里只写了一个provider，指向OpenCode Go的本地地址，然后在CC Switch里切换出口用的是哪家的模型，opencode这边不需要改任何配置，下次请求自动走新出口。

我建议不要一开始就把这套组合架起来，容易一头雾水。先跑通opencode + 单个API Key，熟练之后再引入聚合入口。如果你在团队里经常帮同事排查模型配置问题，这套组合能让你少接很多“为什么我的opencode不响应”的咨询。

这里要多说一句：网络上很多聚合入口来自个人维护，稳定性没有保障，配置前建议先单独用curl验证一下地址是否可用。别把时间浪费在一个已经下线的服务上。

5.3 用opencode + Playwright定位前端Bug

前端调试是opencode比较惊艳我的一个场景。传统的流程是：报Bug → 自己启动项目 → 手动复现 → 看Network和Console → 定位问题。有了opencode + Playwright MCP插件，这个流程可以大幅自动化。

先说配置。opencode支持MCP服务，你可以注册一个Playwright的MCP Server，让Agent具备操作浏览器的能力。在项目配置里加一段：

{ "mcp": { "playwright": { "type": "local", "command": [ "npx", "@playwright/mcp@latest" ], "enabled": true } } }

配置好之后，在对话里给Agent下指令，比如：“启动开发环境，然后用浏览器打开登录页，输入错误密码，把控制台报错信息截图给我”。接下来opencode会自己启动浏览器、执行操作、读取Console和Network信息，再结合代码库分析问题根因。上次遇到一个按钮点击没反应的Bug，我人肉点了五分钟没看明白，Agent一次性就定位到事件监听器被上层stopPropagation拦截了。

用这个功能要注意两点：第一，确保本地开发服务已经跑起来，否则浏览器打开是404；第二，MCP工具调用比较吃资源，Agent连续开十几个页面时，旧电脑可能会卡，用完之后建议在配置里把enabled改成false，需要时再打开。

5.4 接手老项目：让opencode快速建立代码地图

接手一个从没见过的老项目，最耗时间的是建立“代码地图”。以前我都是自己翻package.json、找入口文件、画模块依赖关系，现在我会把这些全部丢给opencode。

第一次打开老项目，我会先给它一个Plan模式任务：“梳理src目录结构，找出核心入口和模块边界，输出一份项目架构说明，保存为ARCHITECTURE.md”。它会读目录、看配置文件、追踪依赖关系，生成一份开头很粗但其实框架正确的文档。随后我会在会话里逐步追问细节：“支付模块的调用链是什么”、“用户鉴权在哪里落库”，每一步都在原来的认知上加深理解。

如果是Java/Maven项目，可以让它先读pom.xml，梳理模块依赖，再定位Spring Boot入口和Controller路由。它会帮你把所有Request Mapping整理成表格，这份东西比人工翻代码快太多。我统计过，一个三十万行的老项目，用opencode建立初步认知大概只需要二十分钟，之后带着问题去精读代码，效率比盲翻高好几倍。

接手项目的过程中，AGENTS.md也派得上大用场。我会把opencode在梳理过程中发现的架构约定同步记录进去，让后续会话甚至团队其他成员都能共享这份认知，避免下一个人再从头开始交学费。

5.5 桌面版体验

如果你实在不习惯纯终端操作，opencode也有桌面版。它基于Tauri做的，本质上是一个带TUI界面的桌面壳子，启动后依然是连本地的opencode服务，配置文件和终端版完全通用。

桌面版最方便的是可以独立开一个窗口，不会和我的终端窗口混在一起。我会把终端版的opencode专门用来处理项目A，桌面版开项目B，两个项目并行推进，互不干扰。不过要提醒的是，桌面版的发版节奏跟着TUI走，偶尔会遇到版本滞后，如果遇到插件连接不上，先看桌面版是否需要更新。

6. 常见问题排查与避坑指南

6.1 报错速查表

整理一份我实际遇到过的报错和解决方案，按频率排序：

opencode debug是排查问题的第一利器，它会输出完整的系统信息、配置路径、服务端口和最近的错误日志。遇到任何诡异问题，先跑它看日志，比自己瞎猜快很多。

6.2 六个容易踩的坑

坑一：把API Key直接写进JSON。文件提交到Git仓库后Key就裸奔了，正确做法是用{env:NAME}占位符，配合环境变量注入。

坑二：权限全开爽一时，后悔一整天。把edit和bash直接设成allow，Agent确实更像自己的员工了，但一旦prompt描述有歧义，它可能直接改动几十个文件。我的经验是，至少在第一周保持ask，摸清它的行为习惯后再逐步放开。

坑三：让opencode和Claude Code同时维护一份AGENTS.md。两个Agent对规范的理解不一样，改出来的风格会互相打架。建议团队明确指定一个主力Agent，另一个只读不写。

坑四：免费模型扛主力。免费模型做补充、做测试、做简单任务都行，扛主力项目容易在中途碰到限流或服务降级，影响心态。我的策略是主力付费模型 + 备用免费模型，关键时刻切过去顶一下。

坑五：接MCP服务排行越多越好。每接入一个MCP服务，都会增加Agent要感知的工具数量，工具多了以后Agent容易选错工具，反而拖慢速度。我只保留Playwright、数据库查询两个主力MCP，其余按需启用。

坑六：升级不看release notes。opencode版本迭代很快，有时候改动是破坏性的，比如某个配置字段改名。我吃过一次亏，升级后直接跑不起来，查了半天发现是config.json换成了opencode.json。所以升级前一定先扫一眼官方的更新说明，有破坏性更新就按迁移文档走，别硬跑。

6.3 prompt使用习惯建议

最后聊几个我在使用中积累的prompt习惯。第一，给Agent明确的范围限制，比如“只修改src/pages/user目录下的文件”，比“帮我优化用户模块”更可控。第二，让它先汇报再行动，用Plan模式确认理解，比让它直接写代码再返工省时得多。第三，把大任务拆成多个小任务，一次性给它塞十个需求，往往每个都做得不彻底。

我把这些习惯跟身边朋友交流过，大家普遍反馈最值钱的是第一条：范围限制。越是老项目，Agent越容易在改动时顺手优化它看不顺眼的代码，最后diff变得一片混乱。加上范围限制后，Agent会变得克制很多，diff也干净得多，审查起来十分钟就能搞定。

如果你刚上手opencode，我建议先从一个小项目开始练手，把AGENTS.md建好、模型配好、权限设好，然后挑一个你熟悉的功能让它重构。等它在你的监督下完成第一次任务，你就能感受到这工具真正的边界和潜力在哪。我自己的体会是，opencode不是替你写代码的魔法棒，而是一个能听懂项目上下文、能按规范执行、还能让你随时介入审查的技术合伙人，用顺了之后一天的工作流里，至少有一半时间都在和它对话。