企业官网建设流程全解析

最近有个朋友问我：从Claude Code换到OpenCode，到底图什么？我想了想，最大的理由其实就俩字——“不锁死”。OpenCode是目前我在终端AI编程助手里用得最顺手的一个开源方案，它能让我在同一个交互界面里自由切换Anthropic、OpenAI、DeepSeek、OpenRouter上的各种模型，不绑定某一家厂商；项目级配置和Skills扩展机制又足够灵活，特别适合我这种要在十几个微服务仓库之间来回折腾的人。这篇文章我就把自己从装到用、从踩坑到总结的全过程完整写出来，包含VSCode插件、JetBrains插件、Skills、Memory、Playwright联调等这些大家搜得最多的玩法。不管你是刚听说OpenCode想尝个鲜，还是已经装了但不知道怎么用得顺手，都可以照着我这套流程走一遍。

1. OpenCode到底是什么：它在AI编程工具链里的位置

1.1 终端Agent到底在解决什么问题

先说背景。过去很长一段时间，我们在IDE里用AI Copilot，本质上是“补全”：你写了一半，它帮你续半句，顶多帮你生成一个函数。这种模式在处理单文件小任务时很爽，但在面对多文件重构、全局搜索接口调用链、批量修测试用例、排查“为什么这个接口突然500”这种需要跨文件理解的任务时，体验就开始拉垮了。

终端Agent的“Agent”三个字，是这套工具和补全工具的本质区别。它不是在编辑器里帮你敲代码，而是像一个坐在终端前的新工程师：能看整个仓库的目录结构、能搜索代码、能执行Shell命令、能读写文件、能自动跑测试。你只需要把目标说清楚，它自己规划步骤，一步步把任务执行完，中途遇到编译错误还会自己修。Claude Code、OpenAI Codex、OpenCode都属于这一类产物，只是实现方式和生态各有取舍。

1.2 OpenCode的定位与优势

OpenCode是SST团队开源的一个MIT协议终端AI编程Agent，最初定位就是"开源的Claude Code替代品"。它有几个让我愿意长期用的理由：

• 多Provider支持。Anthropic、OpenAI、Google、DeepSeek、智谱、通义，甚至OpenRouter上的一大堆模型，它都支持。你在同一个会话里用/models就能切模型，不需要为每家模型单独开一个客户端。
• 配置即文本。全局配置、项目配置都是JSON和Markdown文件，可以被Git管理，团队协作时直接入库，新成员clone下来就能用同一套Agent行为规范。
• Skills和Plugin机制。可以给Agent挂载自定义技能包，也可以写插件做更复杂的扩展，这比很多闭源工具的“固定行为”灵活太多。
• IDE插件和桌面版齐全。VSCode、JetBrains都有官方插件，桌面版也出了，终端党、GUI党都能找到自己舒服的操作方式。

适用人群也很明确：重度用终端的人、需要在多家模型之间横跳的人、想深度定制Agent行为的人。如果你只是想找个国际象棋级别的代码补全工具，那OpenCode反而有点杀鸡用牛刀。

2. 安装与基础配置：新手上手全流程

2.1 三分钟完成安装

安装这一步其实没什么门槛，官方给了好几种方式，我实测下来最稳的还是Homebrew。

# macOS brew install opencode

如果不方便用Homebrew，也可以用官方的一键安装脚本：

curl -fsSL https://opencode.ai/install | bash

或者用npm全局安装：

npm install -g opencode-ai

装完先确认版本：

opencode --version

这里多说一句：很多人在Windows PowerShell下装完，一敲opencode就报“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”，这个我后面第5章会专门展开讲。本质上就是安装脚本把二进制放到了某个目录，但那个目录没有加进系统的PATH。类Unix系统也常见，装完脚本会提示“export PATH=xxx”，记得把这句话写进.zshrc或.bashrc再重开终端。

2.2 Provider配置：为什么我建议从OpenRouter或DeepSeek起步

OpenCode不像某些商业工具那样内置API Key，它默认让你自己配模型服务地址。第一次启动时，交互界面会引导你选择Provider并填写API Key，但我更喜欢手动写配置文件，方便后续用Git管理。

全局配置文件位置在~/.config/opencode/opencode.json，项目级配置则放在项目根目录的opencode.json。项目级配置会覆盖全局配置，这个优先级规则要记住。

以配置OpenRouter为例，格式是这样的：

{ "$schema": "https://opencode.ai/config.json", "provider": { "openrouter": { "models": [ "openai/gpt-4o", "anthropic/claude-sonnet-4" ] } } }

OpenRouter的API Key放到环境变量OPENROUTER_API_KEY里，OpenCode会自动读取。

如果只是想低成本快速体验，我更推荐先用DeepSeek。它价格低，而且新用户有免费额度，OpenCode对它的兼容做得很好。配置方式同样简单：

{ "provider": { "deepseek": { "models": ["deepseek-chat", "deepseek-reasoner"] } } }

环境变量用DEEPSEEK_API_KEY。类似的还有智谱、通义这些国内直接能注册的服务，都有不同力度的免费额度，合规又稳定。

提示：API Key属于敏感信息，千万别写进项目级opencode.json提交到Git仓库。我见过不止一个同事把Key写进配置文件然后推到Gitee，等发现时已经被机器人扫走盗刷。我个人的习惯是配置文件里只写模型名和参数，Key一律走环境变量。

2.3 启动并验证

配置完成后，在项目根目录直接敲opencode进入交互界面。第一次启动它会问你：“信任当前工作目录吗？”选信任，Agent才有权限执行命令、读写文件。

进入交互界面后，建议先试三个命令：

• /models：列出当前Provider下的所有模型，用数字键或方向键切换。
• /init：让OpenCode读取项目结构，生成一份AGENTS.md项目说明，相当于给Agent一份“项目地图”。
• /status：查看当前会话用了多少token，方便估算费用。

验证能不能正常工作，我习惯先给一个简单任务：“帮我看看README.md，然后补充一句这个项目是做什么的一句话简介。”如果它能顺利读文件、修改文件，说明整个链路已经通了。

3. 核心玩法拆解：Skills、Memory、Playwright，一个都不能少

3.1 多项目会话管理：一条命令快速进入状态

OpenCode的会话管理做得比较细。在项目根目录直接opencode会新建一个会话；想接上一回的对话，用：

opencode --continue

它会自动找到最近的会话继续聊。会话列表可以用/sessions查看，来回切换挺方便。对于那种一两句话就能搞定的小改动，我更推荐直接用非交互模式跑命令：

opencode run "给 src/utils/date.ts 里的 formatDate 函数补上UTC时间转换的单元测试"

这相当于一条龙服务：它自己找文件、自己写测试、自己跑测试，最后把结果打印到终端。适合放到命令行别名或者CI脚本里。

社区里现在有个很流行的轻量用法，被大家叫“opencode go”，意思是“少废话，直接干”。很多人在项目里写一个go.sh脚本，里面封装好固定的模型、固定的指令前缀，配合ccswitch这类配置切换工具，能在不同团队的模型服务配置之间秒切。ccswitch本质是一个社区开发的开源配置管理工具，用来统一管理、切换各家兼容API的endpoint配置，配置改完后OpenCode读到的模型服务地址就变了，特别适合那种要同时服务多个团队、多个模型供应商的测试场景。

3.2 Skills：把常用流程固化成能力

Skills是OpenCode最值得花时间研究的特性之一，功能类似Claude Code的Skills：把一组“什么时候用、怎么用”的指令写成文件，Agent在遇到匹配场景时自动加载并按步骤执行。

每个Skill占用一个目录，目录里至少要有一个SKILL.md，用YAML frontmatter写元信息，正文写操作步骤。

我自己写了一个“前端bug排查”Skill，目录结构如下：

~/.config/opencode/skills/frontend-bug-debug/ └── SKILL.md

内容是：

--- name: frontend-bug-debug description: 当用户需要排查前端页面bug、复现交互问题或分析控制台报错时使用。 --- # 前端Bug排查流程 1. 先运行 `npm run build`，确认是否有编译错误。 2. 启动本地开发服务，记录端口。 3. 使用Playwright打开目标页面，尝试复现用户描述的问题。 4. 收集浏览器 console 输出和 network 请求。 5. 定位到对应源码文件，分析可能原因。 6. 修改代码后重新构建，再跑一遍 Playwright 测试确认修复。

当用户说“帮我看看登录页为什么白屏”时，OpenCode会识别出这是前端bug排查场景，自动加载这个Skill，按步骤执行，而不是凭空发挥。

注意：Skill的描述字段写得好不好，直接决定Agent能不能在正确时机自动加载它。写得越具体、关键词越明确，触发越准。如果Agent老是不加载某个Skill，大概率是description里没有覆盖用户可能的表述。

3.3 Memory：让Agent记住你的代码规范

用OpenCode时间长了你会发现，Agent每次会话从零开始，同一个项目里你反复强调的“类型别用any”“提交前先跑lint”它下次还是会忘。这时候就该上Memory机制了。

OpenCode的Memory分两层：

• 全局记忆：~/.config/opencode/AGENTS.md，所有项目通用。
• 项目记忆：项目根目录的AGENTS.md，仅当前项目生效。

我把项目里要求Agent遵守的规则写进项目根目录的AGENTS.md：

# 项目规则 - 所有公共函数必须写JSDoc注释。 - 禁止在业务代码里使用 `any` 类型，优先 `unknown` 并做类型收窄。 - 修改前端代码前必须先跑 `npm run lint:fix`。 - 提交代码前必须补充或更新关联的单测。

这样每次会话开始时，OpenCode都会自动读取这个文件，相当于一见面就先给它“上规矩”。实测下来，遵守规则的稳定性比不写的时候高非常多。

3.4 用Playwright让Agent自己测前端bug

热搜里一直有人问“opencode playwright 怎么测试前端bug”。这其实是OpenCode+MCP工具联动的典型场景。OpenCode天然支持MCP（Model Context Protocol），所以你只要能配置好一个Playwright MCP服务，Agent就能自动控制浏览器、点击页面、读取控制台报错。

以npm包形式使用Playwright MCP，在opencode.json里加一段配置：

{ "mcp": { "playwright": { "type": "npm", "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } }, "provider": { "openrouter": { "models": ["anthropic/claude-sonnet-4"] } } }

配置好后，你可以直接说：“用Playwright打开http://localhost:5173，登录页输入测试账号，点击登录，把控制台报错找出来，定位代码问题。”OpenCode会调用Playwright MCP打开浏览器，一步一步执行操作，然后把console里收集的报错信息拿回来看，再定位到具体源码，提出修复建议甚至直接改代码。

我实际跑过一个小项目，复现一个“列表页点击筛选后白屏”的问题，Agent自己点开页面、触发筛选、抓到了控制台里“Cannot read properties of undefined (reading 'filter')”的错误，然后定位到是筛选结果数组在某分支下返回了undefined，最终修好并补了单测。整套流程在十分钟内完成，比自己人肉复现快太多了。

4. 与IDE集成：VSCode、JetBrains，我为什么还装了桌面版

4.1 VSCode插件怎么选怎么装

OpenCode官方在VSCode商场上的插件名就叫“OpenCode”，装好之后需要确保本机已经有OpenCode CLI。插件本身只是一个前端壳，核心执行逻辑还是走CLI。

安装流程很简单：VSCode扩展面板搜OpenCode，安装后在左侧侧边栏会多出一个OpenCode图标。打开后可以直接在侧边栏里和Agent对话，也可以选中一段代码右键发送给OpenCode做解释或重构。最常用的一个功能是“Open in OpenCode”：在VSCode里打开某个项目后，点一下插件面板里的入口，它会自动在集成终端里启动该项目的OpenCode会话，省去手动cd到目录的步骤。

我的实际体感是：写代码遇到报错时，直接把报错信息和当前文件代码一起丢进侧边栏Agent，让它给出修改建议，这个流程比切终端再描述一遍上下文顺畅很多。

4.2 JetBrains IDEA插件

JetBrains全家桶的插件在Plugins市场搜“OpenCode”同样有官方版本。装好之后，选中代码右键，菜单里会多出“Send to OpenCode”之类的选项，核心用法和VSCode插件一致。

这个插件对Java/Kotlin后端项目尤其友好。之前我带一个Spring Boot项目，同事用IDEA插件直接在代码里右键把Controller层代码发给OpenCode，让它根据现有的Service接口生成一个单元测试，速度飞快。不过JetBrains插件同样依赖CLI，IDEA里弹“opencode command not found”基本就是PATH问题，查一下IDEA是否继承了Shell环境变量就行。

4.3 终端、IDE、桌面版怎么选

桌面版是官方后来出的一个带GUI的客户端，我装它主要是为了给不习惯终端的同事演示用。现在我的选择逻辑是这样的：

终端版仍然是能力最完整的形态，桌面版和IDE插件都会受制于宿主环境，但胜在“好看好上手”。真要深度使用，我建议还是以终端为主，插件为辅。

5. 常见报错与排查实录：我踩过的坑

5.1 安装后“无法将opencode项识别为cmdlet”

这是Windows下最经典的坑。报错原文是：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

原因几乎都是：安装脚本把opencode装到了%USERPROFILE%\.opencode\bin（或类似目录），但该目录不在系统的PATH环境变量里。解决方法是手动把目录加到PATH：

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.opencode\bin", "User")

加完重开终端再执行opencode --version验证。类Unix系统遇到command not found也是一样的思路，检查安装脚本输出的路径是否写进了~/.zshrc或~/.bashrc。

5.2 “unexpected server error. check server logs”

另一个高频报错是：

c:\windows\system32>opencode error: unexpected server error. check server logs

这个报错信息比较笼统，我遇到的基本可以归成四类：

排查顺序建议是：先切模型——如果所有模型都报错，基本就是API Key或网络问题；如果只有某个模型报错，那就是该模型服务的问题。opencode log能输出非常详细的请求日志，很多“server error”都能在里面看到真实原因。

5.3 关于“免费模型”和第三方中转

很多新人冲着“免费模型”来用OpenCode，这里我要泼一盆冷水。社区里确实有一些第三方中转服务，价格极低甚至免费，但稳定性和安全性都没有保障。我见过太多这种例子：前一天还跑得好好的，第二天服务商就跑路，Key失效，正在跑的任务直接断掉；更严重的还有中转服务在日志里截留你的代码内容，这在商业项目里是不可接受的。像“hy3-free是否下线”这种问题，本质上就是第三方免费服务不稳定的缩影。

我的建议是用有官方免费额度的服务，或者极低成本的模型。DeepSeek、智谱、通义这类厂商注册都有体验额度，OpenRouter上也有很多带free标签的模型，适合翻译、写文案、快速原型这种轻量任务。真实的重构、Bug排查、代码生成，还是建议用稳定付费模型，算下来比你自己查半天文档省得多。

遗留下/cost命令可以随时查看当前会话的累计费用，我每隔一两天都会看一眼，心里有数。

5.4 上下文爆掉和权限误操作

长会话聊久了，OpenCode会提示上下文接近上限。这时候最推荐的操作是/compact，让Agent把之前的对话压缩成摘要再加回上下文，可以显著延长会话寿命。如果/compact之后还是经常断，说明这个会话承载的任务太杂了，我会直接新开会话，把关键结论复制过去。

权限管理也是新手容易翻车的地方。OpenCode默认每个命令执行都要你确认，这是好事，不要为了省事直接全部放行。我见过一个同事让Agent“自动执行全部命令”，结果Agent把生产环境数据库的一个表给清了。这种风险不是OpenCode特有问题，而是所有能执行Shell命令的Agent的通病。第一遍运行时我建议先让它“只读探索”，等看清楚了改动方案再手动执行变更类命令。

实际操作中我还会在AGENTS.md里写明“所有涉及删除、清空、DROP、rm -rf的操作必须经过用户二次确认”，尽量把风险挡在规则层。

6. 从个人工具到团队协作：我的实际体会

6.1 与Claude Code、Codex、PI的横向对比

总有朋友问“OpenCode、Codex、Claude Code、PI哪个Agent好用”。这个问题其实没有标准答案，我把几个关键维度列成表：

我的结论是：如果你重度绑定某家模型厂商，直接用对应官方的工具体验往往最好，因为第一方对模型的系统提示词调校更到位；但如果像我们团队一样，不同项目用了不同模型，甚至要在便宜模型和强模型之间横跳，那OpenCode这种开源多Provider方案就是最优解。PI我最近也试了下，确实很轻盈，但IDE集成和扩展生态还差OpenCode不少。

6.2 团队里怎么推广OpenCode

团队协作层面，我做得最成功的一件事是把OpenCode配置入库。项目根目录下放好opencode.json和AGENTS.md，再在文档里写清模型推荐和费用注意事项，新成员clone项目后装好CLI就能直接上手，不需要每个人重新“调教”一遍Agent。

Skills也可以入库。我们在公司内部建了一个skills仓库，把“前端抽查流程”“后端接口测试生成流程”“日志排查流程”这些高频场景都固化成Skill，团队成员按文档把Skills目录软链到本地即可，Agent的行为就能全员一致。这对质量保障是很大的提升——代码风格统一、测试覆盖逻辑统一，连AI写的注释口味都变得统一了。

6.3 几个我每天都在用的效率技巧

最后分享几个用了大半年才沉淀下来的小技巧，都是常规文档里不会写的那种。

第一个，opencode run是批量处理小任务的利器。比如“把src目录下所有文件头部的旧许可证注释换成新的”，这种机械重复的活儿，派给Agent批量跑，比自己写脚本正则替换要省心得多，而且Agent能理解“旧许可证”和“新许可证”各自的语义边界。

第二个，我习惯让Agent在提交代码前先看一遍git diff。指令很简单：“执行git diff，检查这次改动是否有调试日志残留、是否有无用的console.log、是否有未处理的错误分支。发现问题直接修改。”这相当于给代码提交加了一道AI审查，能拦下一大波低质量提交。

第三个，善用/doctor命令。OpenCode自带的诊断工具会检查配置、环境变量、依赖是否正常。每次配置改完或者突然出现诡异问题，先跑/doctor，它能帮你排除一大部分环境问题，比自己瞎猜高效得多。我在一次升级后发现所有Provider都连不上，跑完/doctor才发现是旧版本的全局配置里一个字段在新版本被弃用了，三分钟定位问题。

说到底，OpenCode这类工具的价值不是让你把写代码这件事完全交给AI，而是把大量重复性、机械性的底层工作甩给Agent，让你把精力放在真正需要判断力和优先级的地方。我个人现在的工作流已经离不开它了：新项目Clone下来先opencode初始化，遇到跨模块问题先丢给Agent梳理调用链，写测试用opencode run批量跑，提交前用git diff审查。你可以先从最小的场景开始试，比如让它帮你写一次测试或者重构一个函数，跑通之后大概率就会像我一样，越用越离不开。