企业官网建设流程全解析

这几年终端 AI Agent 的迭代速度，真的比很多人想象中还要夸张。我从 Claude Code 用起，中途换过 Codex CLI，最后长期留在 opencode 上。倒不是因为它名字好记，而是它把“终端 Agent”这个概念做得足够开放：不锁死某一家模型，能接几乎所有主流模型，又提供了 Skills、LSP、Playwright 这类真正能提升代码工作流质量的扩展点。这篇文章就把我实际折腾下来的一些经验和踩坑细节整理出来，给正在考虑入坑或者已经遇到问题的朋友一个参考。

1. opencode 不是一个“套壳 CLI”，它是一个可以自己喂模型的终端 Agent

1.1 我为什么会从 Claude Code 和 Codex 换到 opencode

先说结论：opencode 本质上是一个跑在终端里的开源 AI 编程代理。你把它丢进一个项目目录，它自己会看项目结构、读代码、改文件、执行命令，甚至能自己打开浏览器去复现前端 bug。国内社区很多人喜欢拿它和 Claude Code、Codex CLI 放一起比，其实它们都是同一类东西，但定位差得挺远。

Claude Code 强归强，问题是它和 Anthropic 的模型绑定得太死。你想在里面换 GPT、换 DeepSeek、换本地模型，基本要绕很多路。Codex CLI 反过来，OpenAI 生态内很顺，出了 OpenAI 的服务范围，也显得封闭。opencode 最打动我的地方是"provider 可插拔"：配置文件里指定用哪家模型，它就接哪家，甚至连 Ollama 本地模型都能直接当后端用。对于一家同时要接不同价位居多模型的公司来说，这个自由度太重要了。

1.2 它真正解决的三类问题

我用了几个月，总结下来 opencode 主要解决三类问题：

• 多模型切换问题：前端开发想用 Claude 写复杂逻辑，日常小改动想用便宜模型省成本，本地环境又希望数据不出内网。opencode 把这三条路都通了，一份配置切换即可。
• 终端工作流补全问题：它不只给你聊天，而是真的在 shell 里执行命令。装依赖、跑测试、看 git diff，Agent 能自己干，你在旁边看着。
• 可扩展性问题：Skills 机制、LSP 接入、Playwright 浏览器自动化，这三样东西让 opencode 从一个"对话助手"变成一个真正有手有脚的 Agent。尤其是 LSP，后面的章节我会专门讲。

1.3 和 Claude Code、Codex、Pi 的横向对比

这里我给一张对比表，基于我当时使用时的公开版本整理。这类工具迭代非常快，具体能力请以各项目 README 和 install 后的--help为准。

建议别过度迷信"哪个最好用"，先想清楚一个问题：你手里能用哪些模型接入资源，以及你愿不愿意为开源项目补文档。opencode 的优势在自由度，也就是"模型自由 + 扩展自由"。

2. 第一次跑通 opencode：安装、认证、配置文件

2.1 三种安装方式，以及 Windows 上最容易翻车的 PATH 坑

opencode 的安装方式不算复杂，主流有三种：

1. 官方一键脚本：

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

2. 通过 npm 全局安装：

npm i -g opencode-ai

3. 从 GitHub Releases 页面下载对应平台的二进制包解压。

我刚上手的时候在 Windows 上用 PowerShell 执行完安装脚本，紧接着敲opencode，直接弹出来那条著名报错：opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

这不是安装失败，而是安装路径没进 PATH，或者当前终端会话没有刷新环境变量。常见解决路径是去确认安装目录（脚本默认装在用户目录下的.opencode/bin或类似位置），然后把它加进 PATH。以 Windows 为例：

setx PATH "$env:PATH;$env:USERPROFILE\.opencode\bin"

然后重新开一个终端窗口，再执行opencode --version验证。用 npm 装的话，确认 npm 全局 bin 目录在 PATH 里即可。

提示：改完 PATH 之后不重开终端，回去直接敲命令大概率还是老报错。这个“重开窗口”的动作很多人会漏掉，先检查它。

Linux / macOS 上没有 PATH 问题的同学也别急着跳过。Linux 下手动改配置的需求反而更多，我放到 2.3 节讲。

2.2 认证与模型凭据：auth login 与直接填 key 两种姿势

安装完成之后，第一次运行opencode会进入配置流程，其中最关键的一步是认证（auth）。opencode 的服务端抽象做得比较统一，认证方式大概分两类：

• 交互式登录：执行opencode auth login，按提示选择你的模型服务商，然后走 OAuth 或粘贴 API Key。它会帮你把凭据写到本机配置目录，session 复用时自动加载。
• 手写凭据：直接编辑配置文件，把OPENAI_API_KEY、ANTHROPIC_API_KEY这类环境变量或者 provider 配置写进去。适合服务器、CI 环境这种没法交互登录的场景。

我的建议是初次使用先用auth login跑通，成功之后再去看它写出来的配置内容，顺便理解它到底把 key 存在哪。这比一上来就手改 JSON 省很多事。

2.3 Linux 下手动改 JSON 配置文件：路径与关键字段

搜索热词里有一条 "opencode linux修改json"，说明不少人在 Linux 上折腾过配置文件。Linux / macOS 下 opencode 的全局配置默认在：

~/.config/opencode/opencode.json

项目级配置可以放在项目目录下的.opencode文件夹里，实现“不同项目不同模型”的效果。默认会对齐全局配置，项目级配置会覆盖全局配置的同名字段，这个优先级逻辑对团队协作非常有用。

配置的大致结构类似这样：

{ "provider": { "openai": { "models": { "gpt-4o": { "name": "gpt-4o" } } } }, "model": "gpt-4o", "theme": "opencode" }

真实版本里字段会比这段更丰富，具体 schema 以opencode config --help和你本地安装版本为准。关键是理解一点：JSON 配置不能写注释，不能有尾逗号。我见过很多次用户改完配置直接报解析错误，一查都是逗号问题。改完可以用jq . opencode.json验证一下再启动程序。

注意：这属于 JSON 标准对严格性的要求，与 opencode 无关。所有面向 JSON 的静态配置都有这个惯例。

3. 模型选择、GO 订阅和“你所在国家不提供此模型”的处理思路

3.1 opencode GO 是什么，套餐怎么选

搜索热词里频繁出现的 "opencode go"，指的是 opencode 官方提供的一个统一订阅服务。你可以把它理解成一个模型访问的统一入口：用一个 GO 的 Key，就能在 opencode 里切换到多款主流模型，不需要分别去各家平台开账号、充额度。

选择 GO 套餐时，我建议按三个维度来评估：

• 模型覆盖：你先看套餐里是否包含自己日常依赖的顶配模型，以及是否有便宜的轻量模型可以跑批量任务。
• 用量计费方式：有的套餐偏向包月无限，有的按 token 计量。团队协作场景优先选能开多个 Seat 的，避免几个人挤一个账号。
• 与现有工具链的兼容性：如果你已经在用 CC Switch 这类切换工具，可以看 GO 是否支持把 Key 同时配进去，让 Claude Code 也能共用同一份额度。社区里有人这么玩，具体支持程度以官方文档和 CC Switch 配置页面为准。

我的建议是：个人尝鲜先按月订，别一次性买年付。因为 Agent 类工具的模型选择策略变化很快，今天觉得划算的套餐，下个月可能因为模型价格调整又不划算了。

3.2 免费模型加本地模型，低成本跑通日常任务

如果你预算有限，opencode 也给了两条很实用的路：

• 免费额度模型：比如部分厂商提供的限时免费层，或者社区常见的 DeepSeek、Gemini Flash 等低价高性价比模型，写进 provider 配置就能用。适合做代码补全、简单重构、解释代码这类任务。
• 本地模型：通过 Ollama 跑 qwen2.5-coder 这类开源模型。先把模型拉下来：

ollama pull qwen2.5-coder:14b

然后在 opencode 配置里把 provider 指向 Ollama 的本地地址，就能让 Agent 在完全离线的情况下读代码、写代码。数据不出本机，对隐私敏感的项目是真香。

不过要说实话，本地模型日常写业务代码够用，但做跨文件的大范围重构、接住复杂上下文的时候，能力上限和云端顶配模型还是有差距。我的做法是本地模型负责简单任务，复杂任务切回云端模型，这就是 opencode 多 provider 的好处。

3.3 “this model is not available in your country” 的正规处理方式

很多人在 opencode 里遇到this model is not available in your country.这条报错。先说明一点：这个报错来自上游模型提供方，不是 opencode 本身的错误。它通常意味着该模型在你当前所在地区没有被官方开放，或者提供方法针对该地区做了限制。

正确的处理方式是回到“合法可用”的范围内：

• 查看你使用的模型提供方，在其官方渠道确认该模型支持的地区列表，直接切换到支持你所在地区的模型。
• 换一家你能够正常使用其服务的模型提供方配置进 opencode。
• 对隐私或合规要求高的场景，使用本地模型绕开外部接口的区域问题。
• 检查你自己的账号设置，包括账户地区、计费地址等信息是否与当前所处地区一致，避免误判。

千万不要去试那些打擦边球的手段，一是违反服务条款，二是不稳定。与其想方设法访问一个不开放的模型，不如换一个同等能力的替代模型。opencode 的多 provider 设计本来就是为了避免这种单一依赖。

4. VS Code 与 JetBrains 插件：IDE 里用 opencode 的正确打开方式

4.1 VS Code 插件：把终端窗口搬进编辑器

如果你和我一样主力是 VS Code，直接在扩展市场搜 opencode 就能找到官方插件。装完之后，编辑器和 CLI 是同一套认证体系，你在终端里配置好的 provider、key、模型都会在插件里生效。

插件提供的核心能力是让 Agent 直接在编辑器里配合你操作：你可以给它圈定一段代码，让它做解释或重构，它给出的 diff 会直接以可预览的形式出现在编辑器里，你觉得没问题再接受。这个体验和纯终端相比，省掉了“复制代码进终端再粘回来”的中间步骤。

这里有一个小细节容易忽略：装完插件之后，如果终端里已经跑着 opencode 的会话，插件大概率会尝试连接本机正在运行的服务。如果你开了多个终端窗口，注意关掉不必要的会话，避免多个会话同时占用同一个配置目录导致互相干扰。

4.2 JetBrains 插件：右键发送选中代码

JetBrains 全家桶用户（IDEA、PyCharm、GoLand）在插件市场同样能找到 opencode 插件。插件安装后，最实用的交互入口是编辑器右键菜单：选中一段代码，右键发送给 opencode，Agent 会结合上下文给建议。

这个“右键发送选中代码”的设计，本质上是在解决一个问题：Agent 拿到的上下文质量。你不给它选中区域，它只能按自己的策略去猜你要改哪段；给了之后，它的回答案中率明显高很多。我用 IDEA 插件处理 Java 项目时的体感尤其明显，因为 Java 这种强类型语言的改动经常涉及大量跨类引用，选中入口方法的代码片段再问，比整库扫一遍靠谱得多。

JetBrains 上还有一个方便之处是可以在插件面板里直接看到 Agent 的命令执行日志。它跑了什么命令、改了哪些文件、执行结果如何，都能按时间顺序回顾，排查问题的时候很有用。

4.3 我日常的“终端 + IDE”双会话工作流

很多人问我：有了 IDE 插件，是不是终端里的 opencode 就可以不学了？我的答案是两个都要用，但分工不同。

我把它们拆成两条线：

• 终端 opencode：负责整库级任务。比如接一个新需求，需要跨目录分析哪里改、哪里加，Agent 自己逛代码、自己跑测试，我在旁边观察就行。
• IDE 插件：负责文件级、选区级任务。改某个方法、修某个报错、生成某个类的样板代码，直接在编辑器里完成，既能看到代码高亮，也能随时看 diff。

两个入口共用的是同一份认证、同一套配置，所以我不会在两边重复维护配置。把 IDE 插件当作终端 Agent 的“编辑器前端”，这个心智模型一旦建立，日常使用就很顺畅了。如果你不喜欢开两个界面，opencode 也有桌面端形态可以参考，本质都是同一个 Agent 内核的不同外壳。

5. Skills、LSP、Playwright：三个扩展点把 Agent 变成“会写会查会测”的全能选手

5.1 Skills：给 Agent 装“操作手册”

Skills 是 opencode 非常值得投入时间去理解的功能。你可以把它理解为：给 Agent 预先写好的“操作手册”。当你告诉它“按团队规范做 code review”或者“帮我写符合常规格式的 commit message”时，它会去加载对应的 Skill 文件，按照里面的规则和步骤执行。

Skill 就是带特定格式的 Markdown 文件，放在约定的目录下。社区里常见的目录规则是全局的~/.config/opencode/skills，以及项目里的.opencode/skills。每个 Skill 文件夹里放一个SKILL.md，开头写清楚这个 Skill 的用途、适用场景，后面是具体指令和示例。

现在搜索热词里有 "opencode oh-my-claudecode"，这指的是把社区里为 Claude Code 开发的那套 skills 包迁移给 opencode 用。实操上不建议直接搬，因为两家对 Skill 元信息的解析字段不完全一样。正确做法是把.md里的指令正文拿过来，按 opencode 的格式重写一遍文件头。我自己迁移过几个常用的 code review skill，过程十分钟以内，收益却很直接：Agent 的产出风格会立刻规矩很多。

5.2 LSP：让 Agent 不再靠猜，而是真正看懂代码

LSP 全称是 Language Server Protocol，语言服务器协议。它本来是编辑器用来做语法提示、跳转定义、查找引用的底层技术，opencode 把它接进了 Agent 的上下文，让 Agent 在分析代码时不靠纯文本匹配，而是靠语言服务器提供的语义信息。

接上 LSP 之后，Agent 能做的事情会有一个质的提升。比如：

• 准确找到某个符号的定义位置，而不是用字符串搜索碰运气。
• 拿到引用某个函数的所有地方，从而评估一次改动的影响面。
• 读取诊断信息，直接知道哪一行有类型错误。

常见语言服务器的接入方式是在配置里指定命令和文件后缀。以 TypeScript 为例：

{ "lsp": { "typescript": { "command": ["typescript-language-server", "--stdio"], "extensions": [".ts", ".tsx"] } } }

前提是这些语言服务器本身已经装好，并且在 PATH 里。执行opencode --help或查看文档，通常能找到列出当前 LSP 状态的调试命令，用来确认到底有没有接上。

我的实战体会是：LSP 是否生效，直接决定了 Agent 做大型重构时的靠谱程度。没接 LSP 时，它改一个接口名，经常留下几处旧引用没改；接上之后，它会主动发现所有引用点，逐个处理。这个差异在 TypeScript、Go、Java 这类强类型项目里特别明显。如果你只在 JavaScript 小项目里用 opencode，没有 LSP 也能跑，但一旦项目变大，建议优先补上 LSP 配置。

5.3 Playwright：让它自己开浏览器复现并定位前端 bug

opencode 对 Playwright 的集成，是它区别于很多终端 Agent 的一大亮点。说白了，你可以在对话里要求 Agent “在浏览器里把这个问题复现出来”，它会启动一个真实浏览器，打开你的页面，模拟点击、输入，然后通过控制台日志、网络请求和截图来分析问题。

要启用这个能力，前提是项目里先把 Playwright 装好：

npm i -D playwright npx playwright install chromium

然后启动你的前端项目，告诉 opencode：“访问 http://localhost:5173 ，点击登录按钮，把控制台报错和页面截图拿给我，分析一下为什么登录失败。”

这里我分享一个真实场景。有一次我接了个工单，问题描述是“列表页筛选后表格是空的，控制台有报错”，但是手动复现了半天没头绪。我直接让 opencode 用 Playwright 打开页面、按工单步骤操作，它很快就把报错定位到了接口返回的字段名不匹配，甚至自己提出可以用临时脚本打印一下接口响应结构。最后我把修复推到分支上，它再跑一遍 Playwright 确认问题消失。整个流程从复现到验证，省掉了我大量手工操作。

提示：让 Agent 跑浏览器测试时，最好让它在临时目录或者 dev 环境里跑，别直接对着生产环境做写操作。Agent 再聪明，也顶不住它以为自己在测试环境但脚本里写的是生产地址。

6. 高频报错实录：从命令行不识别到接口报错的完整排查链路

6.1 “无法将 opencode 项识别为 cmdlet”：PATH 问题的三步定位

这条报错在 Windows 上最为常见，报错原文是：

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

排查链路我总结成三步：

1. 确认二进制是否真的装上。在终端执行Get-Command opencode，如果返回空，再回到安装目录找找可执行文件是否存在。找不到就说明安装没成功，重装一遍。
2. 确认 PATH 是否包含安装目录。执行echo $env:PATH，看里面有没有 opencode 的安装路径。没有就加，加完之后重开终端。
3. 确认是不是当前会话没刷新。改完 PATH 后必须重开终端窗口，不能指望当前会话自动加载。

如果以上都查完还是不行，就用where.exe opencode看看系统到底找到了哪个路径。有可能你机器上装了多个版本，命令被别的位置的同名文件抢先了。这类问题耐心顺着路径查，基本十分钟之内能解决。

6.2 “unexpected server error. Check server logs”：逐层往下查

有搜索热词提到opencode error: unexpected server error. check server lo，这是典型的通用服务端报错。它背后的原因可能很多，但排查顺序应该从外到内：

1. 先分清楚是哪一层报错：是连接模型 API 时报的，还是 opencode 自己的本地服务崩了？最简单的方法是临时切换到另一个已经验证可用的模型，看还会不会报。如果换了模型就好了，问题出在原来的模型端点。
2. 看日志：opencode 通常会在本地用户目录下写日志文件，具体路径以opencode --help给出的信息为准。把日志里的关键错误信息搜一下，能定位到是认证失败、超时还是返回格式异常。
3. 直接用 curl 测上游接口：如果你用的是某个 API 提供方，可以用你配好的 key 直接调一次上游 API，看返回是不是正常。这个步骤能帮你区分是“opencode 的 bug”还是“上游服务问题”。

这个报错最怕的就是不死心重试。很多情况下，上游模型服务在高峰期会有毛刺，隔几分钟再试就好了；但如果连续多次报错，就要认真查 key、查额度、查模型名是否写错。

6.3 配置不生效与 model 列表不对：JSON 和缓存的两个常见原因

还有两类很常见的“软故障”，不报错但行为不对：

一类是配置不生效。你改了模型或改了 provider，但 opencode 好像还是用旧配置。这种情况多半是配置读取时机的问题：很多配置只在启动会话时加载一次，改完配置之后要把当前会话退出重进，而不是在对话里继续发消息。另外，项目级配置优先级高于全局配置，如果你在项目里建过.opencode配置，它可能覆盖了全局配置，导致你以为 “我明明改了全局配置怎么没生效”。

另一类是 model 列表不对。你看到可选的模型列表和预期的不一样，通常是当前 provider 的模型列表没有同步，或者在配置里写的模型名跟 API 提供方实际支持的名称对不上。解决方案是先去官方文档确认准确的模型 ID，再更新配置。模型名这东西一点都不能差，差一个横杠、一个点都会报错。

7. 最后分享一个我在团队里落地 opencode 的实际经验

我们团队把 opencode 推广开之后，最实际的收益不是“改代码速度快了多少”，而是新同学接手项目时，Agent 作为“驻场老员工”一直在旁边待命。新需求来了，让 opencode 先梳理相关代码路径、列改动方案，新人再做 review 和实现，上手的门槛明显降低。

如果你准备在一个团队里推 opencode，我建议先立三条规矩：

• 统一模型配置：项目级配置里固定默认模型，避免每个人用不同模型导致产出风格差异过大。
• 统一 Skills 目录：把团队约定、编码规范做成 Skill 文件放进项目仓库，谁来用都是同一套“操作手册”。
• 统一审阅流程：Agent 的改动一律走 MR review，不允许直接推到主干。

说到底，opencode 是个工具，工具的边界由使用它的人决定。多花一点时间把配置、Skills、LSP 这些基础工作做扎实，后面省下来的时间远超前期投入。如果你刚入门，建议就从“装好它，在真实项目里跑一轮小改动”开始，遇到问题再回来翻上面这些排查链路。