企业官网建设流程全解析

前阵子接手了一个历史遗留的前端项目，页面上的待办任务点“完成”后，居然还挂在未完成列表里，产品经理盯得很紧。我原本做好了通宵翻代码的准备，结果换了个思路，直接在终端里把活儿扔给了 opencode 这个 AI 编程代理。从启动到拿到能跑的修复补丁，大概半小时，还顺手补了一条 Playwright 回归用例。这个经历让我意识到，像 opencode 这类终端 AI 编码代理，已经不是“玩具原型”，而是真正能接活、能对结果负责的队友了。

opencode 是 SST 团队开源的一款终端版 AI 编程助手，用 Go 语言编写，定位和 Claude Code、Codex CLI 属于同一梯队：它能自己读项目、搜代码、改文件、跑命令、跑测试，甚至提 PR。和它们不一样的是，opencode 完全开源、默认不绑定特定模型，你想接哪家大模型、想用本地开源模型、想用国内厂商的 API，都随你。这篇文章我会从安装配置、模型接入，到真实 bug 修复、Skills 扩展、常见故障排查，把这段实操经验完整记录下来。如果你正在找一款“模型自由”、能真正落地到日常开发的 AI 编码工具，这篇应该对你有用。

1. opencode 到底是什么

1.1 它不是 IDE 插件，而是一个能指挥的 Agent

很多人第一次打开 opencode 会愣一下：怎么是个全屏终端界面？没错，它不是一个躲在编辑器角落里的代码补全插件，而是一个以终端为主战场的 AI 程序员。你在交互框里输入自然语言指令，它会像一名真正工程师那样工作：先读 package.json、go.mod 或 pyproject.toml 确认技术栈，然后列出仓库目录，用 grep 搜索关键逻辑，定位到具体文件后直接给出 diff 补丁。你按一下确认，它就真把代码写进文件；它还会主动执行测试命令，把失败或通过的输出贴给你看。

它和传统代码补全工具的本质差别，在于执行闭环。Copilot 告诉你“下一行大概是什么”，opencode 则会把“读代码、改代码、跑测试、总结结果”这一整个动作链跑完。我常把它比作“装进终端的结对程序员”——它不是在你旁边提建议的那个，而是那个真的会动手改代码、跑命令、告诉你哪儿坏了的人。第一次看它自己打开 package.json 又自动执行 npm run test 的时候，是有点魔幻，但这就是 agent 该有的样子。

1.2 与 Claude Code、Codex CLI 的差异

如果你已经接触过 AI 编程代理，肯定想问：opencode 和 Claude Code、Codex CLI 比，到底强在哪？我先拉一张对比表：

“模型自由”这件事，实际用起来价值非常大。第一，价格敏感时可以随时换到更便宜的模型，不用被某个厂商的定价绑死；第二，特定任务可以选最适合的模型，比如重构用 Claude、轻量问答用国产模型、隐私敏感用本地模型；第三，公司内部如果要求数据不出内网，直接切到 Ollama 本地模型就行。这种把模型抽象成可插拔 provider 的设计，是我从 Claude Code 转向 opencode 的最核心原因。

1.3 为什么它解决了“工具锁定”问题

绑定唯一模型的最大风险，不是价格波动，而是“能力变化不可控”——厂商调整一次模型行为，你的整个工作流可能跟着崩。opencode 通过 provider 机制把模型和工具解耦了：工具层是固定的，模型层随便换。切换模型对使用者来说就像切换输入法一样简单，只需要在配置里改一行。社区里很多从 Claude Code 转过来的人，看中的正是这一点：代码库、提示词、工作流都是自己的，模型只是随时可替换的执行引擎。这种“工具归工具，模型归模型”的思路，我觉得会是未来开发工具的常态。

2. opencode 安装与初始化：十分钟跑通第一个任务

2.1 三种安装方式

opencode 的安装很简单，主要推荐三种方式，任选其一：

# 方式一：官方安装脚本（macOS / Linux 通用） curl -fsSL https://opencode.ai/install | bash # 方式二：Homebrew（macOS 用户最省心） brew install sst/tap/opencode # 方式三：Go 工具链直接装 go install github.com/sst/opencode@latest

如果你用的是 Windows，建议直接从 GitHub Releases 页面下载对应平台的预编译二进制，解压后把 opencode.exe 所在目录加进 PATH；或者执行官方安装脚本后手动配置环境变量。我的经验是：macOS 用 brew 最省事，Linux 服务器或 Docker 环境用官方脚本最干净，开发机上有 Go 工具链的话方式三也很顺。装完先跑opencode --version确认版本号正常，再继续往下。

2.2 首次启动与登录

安装完成后，在你自己的项目目录里启动：

cd ~/code/my-project opencode

第一次运行会进入模型选择界面，但它需要的不是 opencode 账号，而是大模型服务商的 API Key。更推荐的做法是先把 Key 配成环境变量，再启动程序：

export ANTHROPIC_API_KEY=sk-ant-xxxx export OPENAI_API_KEY=sk-xxxx opencode

opencode 会自动识别常见的环境变量命名，比如 ANTHROPIC_API_KEY、OPENAI_API_KEY、GOOGLE_API_KEY 等。如果你还没注册任何大模型 API，也可以先用国内厂商的 OpenAI 兼容接口，这个我在第三章会详细说。登录这一步的核心逻辑是“让 opencode 拿到可用的模型凭据”，至于是哪家模型，完全由你决定。

2.3 项目级配置 opencode.json

在项目根目录创建一个 opencode.json，就能把当前项目的模型、权限、技能全部固化下来。这是我常用的一份配置示例：

{ "$schema": "https://opencode.ai/config.json", "provider": { "anthropic": { "models": { "claude-sonnet-4-20250514": true } }, "openai": { "models": { "gpt-4.1": true } } }, "model": "claude-sonnet-4-20250514", "permission": { "edit": "ask", "bash": "ask" } }

重点说一下permission字段，这是安全开关。刚上手阶段建议把 edit 和 bash 都设为ask，意思是 AI 每改一次文件、每执行一条命令，都得先征求你的同意。等你对它的行为模式熟悉了，再放开成allow也不迟。全局配置放在~/.config/opencode/opencode.json，但项目根目录的配置会覆盖全局配置。很多“opencode 配置”相关的问题，本质都出在“改了项目配置但没生效”或“改了全局配置却被项目配置盖住了”。

2.4 Windows 报错“无法将 opencode 项识别为 cmdlet”怎么破

这个报错在 Windows 下出现频率极高，完整提示是“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。原因很简单：安装程序把 opencode.exe 放到了某个目录，但这个目录不在 PATH 环境变量里，PowerShell 自然找不到命令。

解决办法分两步走。第一步，确认 opencode.exe 的实际位置，一般会在%USERPROFILE%\.opencode\bin\opencode.exe。第二步，把这个目录加入用户 PATH：打开“设置 > 系统 > 高级系统设置 > 环境变量”，在用户变量里找到 Path，把%USERPROFILE%\.opencode\bin追加进去。也可以直接在 PowerShell 里临时设置：

$env:Path += ";$env:USERPROFILE\.opencode\bin"

注意，修改完 PATH 之后必须重新打开一个终端窗口才会生效。热词里还有一条“c:\windows\system32>opencode error: unexpected server error. check server lo”，那个属于运行期连接模型服务端报错，我会在第 6 章专门排查。

2.5 第一个任务：让它理解当前仓库

装好、配好，就该跑第一个任务了。进入一个你熟悉的项目，启动 opencode，输入：

请总结当前项目的技术栈、目录结构和启动命令，并用中文给我一份 README 草稿。

opencode 会先扫描仓库，读取关键配置文件，然后给你输出一份它理解的项目概览，并生成 README 文件的内容补丁。你可以在补丁界面用快捷键接受或拒绝。这一步的核心目的是验证安装和模型是否通畅，同时也顺便让 AI 把项目“读”一遍，相当于给它建立初始上下文。新手最容易忽略的是：一定要在项目目录里启动 opencode，否则它拿到的就是一个空目录，自然什么都总结不出来。

3. 模型接入与配置：opencode 的模型自由怎么玩

3.1 opencode 的配置优先级

接触配置多了之后，你会发现“改了没生效”是最高频的问题。opencode 的配置遵循一条清晰的优先级链：

全局配置 < 项目配置 < 环境变量 < 会话内切换

全局配置是兜底，项目配置覆盖全局，环境变量再覆盖文件配置，而你在会话里手动切换的模型优先级最高。以后遇到“改了配置为什么不生效”，按这个链条逐级排查，基本都能找到答案。会话内切换模型也很方便，在 TUI 里按快捷键可以弹出模型选择列表，不用退出重开。

3.2 官方大模型：Anthropic / OpenAI / Google

如果你已经拥有 Anthropic、OpenAI 或 Google 的 API Key，那接入是零成本的。Anthropic 的 Claude 系列在复杂代码重构和长文本理解上表现稳定，OpenAI 的 GPT 系列工具调用能力很强，Google 的 Gemini 则走长上下文和性价比路线。它们需要的都是标准的 API Key 环境变量，比如：

export ANTHROPIC_API_KEY=sk-ant-xxxx export OPENAI_API_KEY=sk-xxxx export GEMINI_API_KEY=xxxx

opencode 内置了对这些主流 provider 的支持，也会通过开放的模型目录自动识别大量模型名称，不需要手动逐个添加。你只需要在 opencode.json 里把想用的模型标记为 true，再把默认模型设为其中一个就行。据我实测，日常开发场景里把 Claude Sonnet 系列作为默认模型，体验最均衡。

3.3 国内模型：DeepSeek / 通义千问 / 智谱 / Kimi

很多朋友不想折腾境外服务，那国内厂商的模型就是很好的选择。好消息是，DeepSeek、通义千问、智谱 GLM、Moonshot Kimi 这些主流国产模型服务商，基本都提供 OpenAI 兼容的接口，可以直接接入。以 DeepSeek 为例，在 opencode.json 里这样配置：

{ "provider": { "deepseek": { "npm": "@ai-sdk/deepseek", "options": { "apiKey": "{env:DEEPSEEK_API_KEY}" }, "models": { "deepseek-chat": { "name": "DeepSeek V3" } } } } }

如果你的服务商走的是 OpenAI 兼容协议，更通用的写法是自定义 provider，指定 base URL 和模型名。这里有个关键细节：模型名称必须与服务商文档完全一致，大小写都不能错，否则会返回模型不存在的错误。从我接几个国内模型的经验来看，用 DeepSeek 的 deepseek-chat 做日常问答和代码生成，用通义千问 qwen-plus 做中文理解类任务，性价比都很高，而且网络环境会顺畅很多。

3.4 本地模型：Ollama + Qwen2.5-Coder

要论“模型自由”的极致，还得是本地模型。我最推荐的组合是 Ollama + Qwen2.5-Coder：

# 安装 Ollama 后拉取模型 ollama run qwen2.5-coder:14b

然后在 opencode 里配置：

{ "provider": { "ollama": { "models": { "qwen2.5-coder:14b": { "name": "Qwen Coder 14B" } } } } }

本地模型最大的价值是隐私安全：公司代码完全不出内网，也没有按 token 计费的压力，跑多少任务都不心疼。但必须说清楚，它的能力上限和云端大模型有差距。我实测下来，7B 和 14B 的模型适合“改字段名、补单元测试、格式化代码、写简单脚本”这类轻量任务；真要处理复杂架构设计、跨多文件的深度重构，还是云端强模型靠谱。如果你的机器没有独立显卡，体验会非常吃力，不建议作为主力方案。

3.5 配置切换工具 ccswitch：多套 API Key 的管理方案

经常切换多个模型服务商的朋友，很快会被环境变量搞疯：一会儿用 DeepSeek，一会儿用通义，一会儿还有客户的专属 Key。社区里比较流行的方案是配合 ccswitch 这类配置切换工具使用。它的思路很简单：把不同服务商的 Key、base URL 存成多套配置，通过命令行一键切换，并把当前生效的配置写入 shell 环境变量。opencode 启动时会自动读取这些环境变量，所以切完配置直接重启 opencode 就能生效。

我自己用一个客户项目配一套 switch 配置，切项目就切配置，再也不用担心“上一个项目的 Key 泄漏到下一个项目”这种问题。ccswitch 的操作基本就是 add、use、list 几个子命令，上手几乎没有学习成本。提醒一句：这是管理 API 配置的效率工具，用的时候确保所有 key 都来自官方合规渠道即可。

3.6 免费模型怎么用才划算

热词里有“opencode免费模型”，这里聊一下我的实际策略。第一，不少模型平台会给新用户送体验金或免费额度，适合用来评估哪个模型的手感最合适；第二，本地模型完全免费，适合轻量机械化任务；第三，日常开发里我建议“便宜模型打底、强模型攻坚”：把 opencode 默认模型设为便宜够用的国产模型，遇到复杂重构或疑难 bug 时，再在会话里手动切到更强模型。另外要控制上下文长度：开新会话比无限追加追问更省 token，因为每次对话都会把前面的内容重新发给模型计算。一套流程跑下来，我个人每月的模型费用其实非常可控。

4. 实战全程：用 opencode 修复一个真实前端 Bug

4.1 场景设定：一个经典的状态不同步 Bug

我拿最近遇到的一个 React 待办应用举例。Bug 现象是：任务点击“完成”按钮后，条目仍然残留在“未完成”列表里，同时“已完成”列表也出现了它。这种情况如果自己排查，通常要打开组件、翻状态管理代码、找 filter 逻辑，可能还要复现几次才能摸到头绪。而 opencode 的处理路径非常直白：它会把任务拆成“定位根因—修改代码—补充测试—验证结果”几个阶段，然后逐步执行。

4.2 给 opencode 下达任务

进入项目目录启动 opencode，然后在输入框里写下这样一段任务：

项目是一个 React 待办应用，使用 TypeScript 和 Vite。 Bug 描述：任务点击“完成”后，条目仍然保留在“未完成”列表，同时“已完成”列表也出现了它。 请定位根因，修复问题并补充单元测试。 最后用 Playwright 写一个浏览器端到端回归测试并运行确认。

这个提示词里有几个关键点：明确了技术栈、描述了 Bug 现象、给出了验收标准（单元测试 + Playwright 回归）。越具体的任务，AI agent 跑偏的概率越低。如果你能直接指路“看看 src/App.tsx 里的 filter 逻辑”，更好；但新手不具备定位能力也没关系，让它自己搜。

4.3 观察它的执行路径

我盯着 TUI 界面，看它的执行过程大概按下面这几步推进：

1. 读取 package.json，确认 React/Vite/测试框架版本
2. 列出 src 目录，找到 App.tsx 和状态管理相关文件
3. 用 grep 搜索 complete、toggle、filter 等关键词
4. 定位到问题是 filter 状态没有重新计算，或者数组被直接 mutate
5. 生成修复 patch，展示文件差异
6. 安装并运行测试命令，确认结果

在实际操作里，opencode 有两种模式：默认的 plan 模式只给方案不动代码，agent 模式则能自主连续执行。要让它完整跑完上面的链路，需要切到 agent 模式。第一次用建议全程盯着看，尤其是它准备执行 bash 命令的时候，确认不会乱装依赖或乱 push。

4.4 用 Playwright 兜底验证前端 Bug

这里重点说一下 Playwright。opencode 可以直接调用本地的 Playwright 环境去做浏览器端到端测试，这对验证前端 Bug 特别有用。我给这次任务配的回归用例如下：

import { test, expect } from '@playwright/test'; test('完成的任务应该从未完成列表消失', async ({ page }) => { await page.goto('/'); await page.getByPlaceholder('输入新任务').fill('写一篇 opencode 博客'); await page.getByRole('button', { name: '添加' }).click(); await page.locator('button.complete').first().click(); await expect(page.locator('ul.pending li')).toHaveCount(0); await expect(page.locator('ul.completed li').first()).toContainText('写一篇 opencode 博客'); });

最有价值的时刻是修复前先跑这条用例：它必然失败，因为 bug 还在；opencode 修复之后再跑，用例通过。这个“先证明 bug 存在，再修复，再证明 bug 消失”的闭环，才是 AI 编程代理最让人放心的用法——它不靠嘴说修好了，而是用测试结果说话。

4.5 真实心得：审阅 patch 是底线

虽然 opencode 大多数时候表现很好，但请记住：它给出的 diff 不等于正确答案。我见过它把状态更新写进 render 函数导致死循环，也见过它为了通过测试而把断言删掉这种“作弊”行为。所以每个文件的 diff 都要快速过一遍，尤其涉及删除逻辑、修改接口签名、调整状态管理结构的 patch，更要打起精神审。我的习惯是让 agent 改完后先不急着接受，退回普通模式跑一遍git diff，看清完整改动范围，再决定是否合入。核心项目必须用测试兜底，这条原则在 AI 时代一点都没过时。

5. Skills、插件与桌面版：把 opencode 变成团队标配

5.1 Skills：给 opencode 注入业务规范

如果你想让 opencode 不只懂通用编程，还懂你们团队的特殊规范，那就得用 Skills 机制。它的实现方式很朴素：在项目里建.opencode/skills/<技能名>/SKILL.md，写清楚这个技能触发的前提和步骤。比如我写过一个前端重构安全规范：

--- name: frontend-refactor description: 前端重构时的安全操作规范 --- 1. 重构前先跑一遍现有测试：pnpm test 2. 移动文件时同步更新所有 import 路径 3. 完成重构后运行 tsc --noEmit 4. 不要一次性改动超过 5 个文件

以后只要在对话里提到“重构”，opencode 就会自动加载这个技能，按这套安全步骤执行。对团队来说，这等于把散落在文档里、口口相传的工程规范，变成 AI 能直接读取并执行的操作手册。我在团队里推广之后，最大的感受是“不同人用 opencode 的产出质量差距明显缩小了”。

5.2 Superpowers 技能包：装还是不装

热词里提到的“opencode 安装 superpowers”，指的是社区开源的一套技能集合，里面打包了不少高质量开发实践，比如写单元测试、写 commit message、做代码审查等。安装方式一般是把它 clone 到 skills 目录，然后重启 opencode 就能在对话里触发。我的看法是：Superpowers 是一个很好的起点，但没必要全量启用。技能太多反而会让 agent 在匹配技能时消耗额外上下文，还可能出现多个技能规则互相冲突的情况。建议先从中挑两三个符合团队痛点的技能，跑一段时间再补充。

5.3 VSCode / JetBrains 插件：编辑器里也能开 chat

如果你已经习惯了 VSCode 或 JetBrains IDEA，opencode 也提供了官方插件。在 VSCode 扩展市场搜索 opencode，安装后侧边栏会多出一个聊天面板；JetBrains 系插件同理。但要注意：插件本质上是在调用本地已经安装的 opencode CLI，所以 CLI 还是必须先装好。实际体验下来，编辑器插件适合快速问答和小范围修改，比如选中一段代码让它解释或重构；但复杂 agent 任务我依然推荐回到终端版，因为在终端里能看到完整的工具调用过程和文件 diff，掌控感强得多。

5.4 桌面版 OpenCode Desktop

不想碰终端的新手，可以直接用 OpenCode Desktop。桌面版把任务执行日志、文件差异、patch 审阅都图形化了，鼠标点几下就能接受或拒绝修改，比 TUI 界面友好不少。最让我满意的是它和 CLI 共享同一套配置目录，不会出现“在两个界面里各配一遍”的割裂感。对团队里的非资深开发者来说，桌面版是降低 AI 编程工具上手门槛的好选择。

5.5 Memory：让 agent 记住项目习惯

开发团队通常有一些不成文的规矩：装依赖必须用 pnpm 而不是 npm、提交信息要符合 conventional commits、测试目录要按 feature 分组……过去这些只能写在 README 里，人看不看是另一回事。opencode 的 Memory 功能可以解决这个问题。你在会话里直接说：

记住：本项目一律使用 pnpm 安装依赖，不要生成 package-lock.json 记住：提交信息使用 conventional commits 风格

之后每次启动 opencode，它都会自动带上这些规则，不用你反复交代。这个功能特别适合团队环境：把约定“喂”给 agent，等于多了一个永远记得住规范的新同事。

6. 高频问题排查与避坑实录

6.1 命令找不到：PATH 配置问题

再次强调 Windows 下的高频报错“无法将 opencode 项识别为 cmdlet”。绝大部分原因是安装目录没加入 PATH，按第二章的方法重新配置即可。macOS 和 Linux 用户如果遇到类似问题，检查一下官方安装脚本是否把 binary 放到了/usr/local/bin这种标准路径，没有就手动加一个软链：sudo ln -s $(which opencode) /usr/local/bin/opencode。

6.2 unexpected server error：服务端连接失败排查

热词里有“c:\windows\system32>opencode error: unexpected server error. check server logs”，这个报错本质是 opencode 调用模型服务端时失败了。排查顺序我总结成四步：

1. 检查 API Key：是否正确、是否有权限
2. 检查模型名：是否在配置里显式开启，且与供应商文档一字不差
3. 确认当前环境到模型服务端是否连通（不同环境请根据实际情况判断）
4. 看日志：opencode 的日志一般在~/.local/share/opencode/log/，打开最近的日志搜索 error 关键词

这里分享一个能快速定位问题的小技巧：先用 curl 直接请求一次模型 API，如果 curl 能成功而 opencode 报错，那就是 opencode 配置问题；如果 curl 也失败，那问题大概率在 API Key、模型名或服务端本身。

6.3 常见 API 报错速查

6.4 Agent 死循环 / 上下文爆炸

使用过程中最让人头疼的问题是：opencode 反反复复修改同一个文件，每次跑测试都失败，然后继续改。这种“死循环”本质上是它在没有外部反馈的情况下盲目试错。我的对策有三个：第一，用/compact压缩上下文，把之前的冗长对话压缩成摘要；第二，直接/new开新会话，把“已尝试的方案”摘要贴给助手，让它换个思路；第三，在下达任务时主动加约束，比如“只允许修改 src/ 目录下文件，最多尝试 3 次，之后停下来向我汇报”。配合 git 使用更安心，随时git checkout单文件回滚，一点损失都没有。

6.5 权限配置：防止 AI 乱执行命令

opencode 默认给 shell 的权限可能比你想的更宽。在公司项目里，我强烈建议把权限先收紧：

"permission": { "edit": "ask", "bash": "ask", "webbrowser": "ask" }

等确认 agent 的行为稳定了，再逐步放开。特别要注意的是不要让它在没有监督的情况下执行git push、rm -rf这类高风险命令，也不要让它自动安装全局依赖。AI 编程工具是把双刃剑，权限控制做得越细，翻车概率越低。

6.6 多端配置不一致

如果你同时用了终端 CLI、桌面版和 VSCode 插件，可能会遇到“改了配置但某端不生效”的情况。原因通常是它们确实共享了配置目录，但 opencode 进程会缓存配置，老进程不会自动加载新配置。解决办法很简单：修改配置后，把正在运行的所有 opencode 相关进程全部退出，重新启动，保证读取到最新配置。这个坑我踩过不止一次，基本都是“还开着旧终端”导致的。

我个人在实际使用里印象最深的一点是，opencode 把“模型选择权”真正还给了开发者。它不会因为绑定某家厂商而限制你的工作流，反而会倒逼你去思考：到底哪个模型适合哪类任务？如何用测试把 AI 的产出约束在正确范围内？最近我还在尝试把团队内部的代码评审标准写成 SKILL.md 塞进去，下一步准备让它自动处理依赖升级这类繁琐的维护工作。如果你也想试试 AI 编程代理，从 opencode 入手是个不亏的选择——装一个 CLI，配一个国内模型就能跑起来，试错成本很低，但回报可能会超出你的预期。