企业官网建设流程全解析

去年底我接手了一个半死不活的前端项目，代码堆得像毛线团，文档约等于没有，我实在不想一行行去啃。群里有人丢给我一句话：试试 opencode。当时我以为是某个新的代码编辑器，结果它是一个跑在终端里的 AI 编程助手。这一试不要紧，我的开发工作流就彻底回不去了，后面连续几个项目我都是用它在终端里完成的。如果你最近也在关注 opencode，在犹豫要不要从 Claude Code 或者 Codex 换过来，或者说刚装上但不知道从哪下手，这篇东西应该能帮你省下好几天摸索时间。

opencode 是一个开源终端 AI 编程代理，最大的特点是模型自由、配置灵活、上手路径短。它不像某些工具把你绑死在特定厂商上，而是让你自己选模型、配服务、甚至接入本地模型。这篇文章我按"是什么、怎么装、怎么配、怎么用、踩了什么坑"的顺序来写，里面所有步骤和配置都是我在实际项目中验证过的，不是抄文档。

1. opencode是什么：一个用Go重写你终端工作流的AI编程Agent

1.1 一句话定位

如果你用过 Claude Code 或者 Codex CLI，那 opencode 的理解成本几乎为零。它也是一个跑在终端里的 AI 编程助手，你在命令行里启动它，它会根据你的指令去读代码、改文件、执行命令、跑测试，然后告诉你结果，循环往复直到任务完成。

但它和那几个工具又不太一样。opencode 是开源的，GitHub 上仓库热度一直很高，背后的团队是做 SST 那批人，所以这个工具从出生起就带着很强的工程效率基因。它用 Go 语言写的，发行物就是一个单二进制文件，不依赖 Node 运行时，也不强制你登录什么账号，你在哪台机器上装都是一样的手感。

很多朋友第一次打开 opencode 的界面会觉得它像个聊天工具，实际上它远不止聊天。它的 TUI（终端用户界面）里有一个主对话窗口，一个会话列表侧栏，还有一个很实用的功能：同一个问题你可以同时丢给多个模型，让它们各自给出方案，你再对比选优。这个功能在解决疑难 Bug 时特别好用，相当于同时请了两位不同风格的工程师会诊。

1.2 和Claude Code、Codex CLI、pi的对比

像 opencode 这种终端 Agent 现在不少，很多人都在纠结选哪个，我用了几个月之后的感觉是这样的：

注意上表的结论有个大前提：工具迭代非常快，半年后再看可能又是另一番局面。我的建议是不要听别人说哪个"最好"，而是看哪个最贴合你的工作习惯。opencode 的强项在于"中间路线"——它不像 Claude Code 那样开箱即用零配置，但也不像 pi 那样需要你搭积木一样拼出完整环境。你只需要配好模型服务，它能给到接近商业工具的完整体验，同时保留全部的灵活度。

我也见过一些人问"opencode codex pi 哪个 agent 好用"，这类问题其实很难有标准答案。我个人的经验是：如果你是个人开发者、自媒体、独立作品集作者，opencode 的性价比是最高的，因为你只需要为模型 API 付费，工具本身免费开源，也不存在账号层面的封禁风险。而如果你所在团队已经全员 Anthropic 生态、统一了工作流，那 Claude Code 的团队协作能力可能更省心。工具这东西，适合自己的就是最好的。

2. 从零安装到跑起第一个会话：不同平台的路径和Windows专属坑

2.1 三种安装方式，按场景选

opencode 的安装方式挺多，我只讲实际用下来最靠谱的三种。

macOS 和 Linux 上最省事的是用官方安装脚本：

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

我看到很多教程直接让你这么装，但它有个隐患：脚本安装的位置不一定在你的 PATH 里。装完提示命令找不到的话，可以用 Homebrew 再装一遍：

brew install sst/tap/opencode

如果你机器上已经有 Go 环境，也可以从源码装，顺便还能锁定特定版本：

go install github.com/sst/opencode@latest

Windows 上的路子有点不一样。官方推荐用 Scoop，装完之后会自动处理 PATH：

scoop install opencode

如果你不想装 Scoop，去 GitHub Releases 页面下载对应平台的压缩包，解压后把 opencode.exe 放到一个固定目录，再手动加进系统 PATH 也可以。我个人的建议是优先 Scoop，因为后续升级只需要scoop update opencode一条命令，比手动下载方便太多。

2.2 "无法将opencode项识别为cmdlet"到底是怎么回事

Windows 用户遇到最多的就是下面这条报错：

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

这条报错本身是无辜的，它只是告诉你 PowerShell 在当前所有 PATH 目录里找不到 opencode 这个可执行文件。但为什么找不到，原因通常是这几个：

第一，你用浏览器下载了 zip，解压之后忘了把 exe 所在目录加进 PATH。这种最常见，解决办法是把解压出来的目录复制到C:\tools\这种固定位置，然后去系统环境变量里把路径追加进去。

第二，你照着 macOS 的教程执行了curl ... | bash。PowerShell 对管道和 bash 脚本的处理方式跟 Linux 完全不同，这段脚本在 PowerShell 里根本不会按预期执行，看起来像执行了，实际上什么都没装好。

第三，你装的时候终端是开着的，装完后 PATH 没有刷新。关闭当前终端窗口重新开一个，或者执行$env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")强制刷新。

排查思路其实很简单：先在终端里输入Get-Command opencode，如果能返回路径说明命令可用，只是终端缓存问题；如果提示找不到，说明 PATH 没配好。也可以在文件管理器里找到 opencode.exe，直接双击运行，如果弹出一个终端界面，说明程序本身没问题，问题全在 PATH。

2.3 第一个会话：认证、选模型、界面认识

装好之后，在终端输入opencode就能进入 TUI。第一次启动它会引导你选择模型服务商，这一步在后面的章节我会详细讲。如果你想跳过引导直接配，也可以用命令行的非交互模式快速体验。比如：

opencode run "帮我看看当前目录下有哪些文件"

这个命令会直接在终端里执行一次对话并返回结果，适合脚本化和 CI 场景。日常开发我建议还是进入 TUI，因为它的体验比纯命令行好太多。

进入 TUI 后你看到的界面大致分三个区域：左侧是会话列表，中间是对话主窗口，底部是输入框。对话窗口里可以随时切换模型，也可以同时问多个模型，等它们都回答完再对比。快捷键方面你不需要背，按?就能看到当前所有快捷键。

第一次启动之后我建议做一件事：随便问它一个关于当前项目的问题，比如"这个项目的技术栈是什么"，确认整个链路是通的。哪怕答案不完美，至少证明安装、认证、模型调用都没问题，后面再根据实际需要去调整配置。

3. Provider接入与模型切换：API Key、ccswitch和免费模型的理性用法

3.1 配置文件里到底能配什么

opencode 的配置目录在~/.config/opencode/，Windows 上则是%USERPROFILE%\.config\opencode\。里面最重要的文件是opencode.json，它控制模型服务商、模型列表、MCP 服务器、全局规则等几乎所有东西。文件开头建议加上$schema字段，写配置文件时编辑器就能自动补全和提示：

{ "$schema": "https://opencode.ai/config.json", "provider": { "custom": { "npm": "@ai-sdk/custom", "name": "My Custom Provider", "options": { "baseURL": "https://api.example.com/v1", "apiKey": "{env:CUSTOM_API_KEY}" }, "models": { "my-model": { "name": "My Model" } } } } }

不过对大多数用户来说，根本不需要手写这种底层配置。opencode 内置了对主流服务商的支持，你只要用opencode auth login登录认证就行。这条命令会带出一个交互式菜单，列出当前支持的服务商，选一个，按提示粘贴 API Key 或者走 OAuth 流程，认证信息会被保存在系统钥匙串里。

如果你更喜欢环境变量，opencode 也支持常见变量名，比如ANTHROPIC_API_KEY、OPENAI_API_KEY、OPENROUTER_API_KEY、GEMINI_API_KEY等等。设置好一个就能在对应服务商下直接选模型。

我推荐的做法是：API Key 这种敏感信息不要写进opencode.json，优先用系统钥匙串或者环境变量。既安全，也方便后续引入 ccswitch 这类工具做集中管理。

3.2 ccswitch让多模型切换变成一键操作

在社区里搜索 opencode，大概率会看到"opencode 需要配合 ccswitch 使用"的说法。ccswitch 是一个命令行小工具，作用是集中管理多个 AI 服务的 API 配置，然后通过环境变量或者配置文件的方式，把当前选中的那组配置暴露给下游工具。它解决的问题很实在：你同时用着 opencode、Codex CLI、Claude Code 等多个工具，每个工具都要配一遍服务商信息，切换模型服务商的时候一个一个去改，实在太痛苦。

我用它的方式是这样的：在 ccswitch 里维护一个配置列表，比如"工作用 Anthropic 官方"、"测试用 OpenRouter 聚合"、"本地跑 Ollama"，每次切换只需要一行命令：

ccswitch use work-anthropic opencode

这样 opencode 启动时读取到的就是当前激活的配置，API 地址和 Key 都不用我手动改。配置转移方面，如果换了一台新电脑，只把 ccswitch 的配置目录拷过去，所有工具就都恢复原样，这对经常在多台机器之间换环境的人来说非常省事。

需要说明的是，opencode 本身不依赖 ccswitch，但如果你同时使用多个 AI 编程工具，你会感谢这个组合的。

3.3 免费模型：额度、开源模型和"下线焦虑"

网上很多人在搜"opencode 免费模型"，我得先泼一盆冷水：免费的东西在 AI 编程这件事上，从来不是免费的午餐。目前真正靠谱的免费途径就三类。

第一类是云厂商的免费额度，比如 Google AI Studio 给 Gemini 系列模型的免费层，OpenRouter 上也有一批限额免费模型，额度用完就停。这类服务稳定，适合入门体验。

第二类是本地开源模型，配合 Ollama 跑 Qwen、Llama、DeepSeek 这些，响应速度取决于你的显卡。本地模型胜在私密和无限量，但代码生成质量跟顶级商业模型还有差距，适合对隐私要求高的场景。

第三类是某些社区里流传的"免费中转源"，这类服务我不推荐绑定核心开发流程。原因很简单：稳定性没保证，随时可能 401。社区里很多人问"hy3-free 是不是下线了"，其实就是这类源的真实写照——今天还能用，明天就没了，不是故事，是很多人踩过的坑。

我的建议是：日常开发至少准备一个付费的、可靠的商业模型 API，免费额度作为补充或者备胎。省下来的那点钱，远不够弥补关键时刻掉链子浪费的时间。

3.4 关于MCP配置，以及那个被问烂的"mvn"

搜索记录里经常能看到"opencode mvn 配置"，如果你也是照着教程去搜的，大概率是把mcp打成了mvn。MCP 全称 Model Context Protocol，是让 Agent 接入外部工具的标准协议，这才是你真正要找的东西。

opencode 支持 MCP 服务器配置，在opencode.json里加一个mcp字段就能启用。比如接入 Playwright 让 Agent 能用真实浏览器去验证前端效果：

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

配上之后，Agent 就能在需要的时候自动启动浏览器、打开页面、截图、读取控制台报错，这对前端 Bug 的定位效率提升是肉眼可见的。后面我会专门写一节讲怎么用 Playwright 调前端问题，这里先记住一点：MCP 是 opencode 扩展能力的关键入口，学会配它，你的 Agent 才不算浪费。

4. 规则、记忆和Skills：把opencode调教成你的专属结对程序员

4.1 AGENTS.md：用项目规则约束Agent行为

如果你之前用过 Claude Code，一定会熟悉CLAUDE.md；在 opencode 里，这个角色由AGENTS.md承担。它和 README 不同，README 是给人看的，AGENTS.md 是给 AI 看的。文件里可以写明项目结构、代码风格、常用命令、禁止事项等。只要把AGENTS.md放在项目根目录，opencode 每次启动都会自动读取它，并在后续所有对话中遵循里面的约束。

比如我接手一个 Vue3 项目时会这样写：

# Project Rules - 这是一个 Vue 3 + TypeScript + Vite 项目 - 组件全部使用 <script setup> 语法 - 样式使用 Tailwind CSS，禁止写全局 CSS - 提交信息遵循 Conventional Commits 规范 - 修改代码前必须先读懂相关目录结构，不要盲目新增文件

写这文件花了我十分钟，但效果立竿见影：Agent 生成的代码风格明显更贴近项目现有代码，不会再出现一会儿 Options API 一会儿 Composition API 这种混乱情况。我强烈建议每个项目都维护一份 AGENTS.md，这可能是投入产出比最高的一项配置。

4.2 Memory：跨会话记忆的正确打开方式

opencode 有一个记忆功能，可以把跨会话的信息存下来，下次对话继续使用。比如你告诉过它"这个项目的数据请求统一走src/api目录下的模块"、"生产环境构建命令是pnpm build:prod"，这类信息会被沉淀到记忆里。

记忆功能好是好，但也会带来一个副作用：记忆不干净的话，Agent 会被过时信息误导。我建议定期清理记忆。我自己的习惯是每完成一个里程碑，就把旧的、不再适用的记忆删除，只保留当前模块相关的约束。记忆不是垃圾桶，别什么都往里丢。你存进去的每一句话，都在影响 Agent 后续所有判断。

4.3 Skills：自己写一个代码审查技能

Skills 是 opencode 里最像"插件"的东西，它本质上是一个带说明文档的行为模板。比如我想让 Agent 在每次改动后做一次代码审查，就创建~/.config/opencode/skills/code-review/SKILL.md，内容大致是：

--- name: code-review description: 对当前改动做一次代码审查，检查逻辑错误、安全隐患和代码风格问题。 --- 当你执行 code-review 时，请按以下步骤操作： 1. 使用 git diff 查看未提交的改动。 2. 逐个文件检查改动逻辑，重点关注边界条件和异常处理。 3. 检查是否硬编码了敏感信息。 4. 给出修改建议，标注严重级别。

然后在对话里输入"执行 code review"，它就会按这套流程走。你可以按自己的项目需求写大量类似的 skill：数据库迁移、依赖升级、接口对接、测试用例生成，都是很好的场景。Skill 的好处是把"你希望 Agent 怎么做"沉淀成文件，而不是每次都重新口头叮嘱一遍，换项目、换人、换机器都能复用。

4.4 安装Superpowers这类技能包

除了自己写 skill，社区里也有现成的技能包可以装。很多人问"opencode 安装 superpowers"怎么弄，其实思路和 Claude Code 时代类似：superpowers 是一套技能集合，里面包含了很多高质量 prompt 模板，覆盖代码审查、测试生成、性能调试、重构等常见任务。opencode 支持 skills 机制后，把技能包里的各个目录放进~/.config/opencode/skills/下，重启 opencode 就能加载。你可以用/skills命令查看当前已加载的技能列表。

前面提到的 oh-my-claudecode，本质上也是类似思路的配置集合，很多人之前用它来管理 Claude Code 的配置，现在也会沿用同样的习惯给 opencode 配一套。这种"配置即代码"的方式挺符合开发者直觉：一切都能放进仓库、能版本管理、能分享给队友。

5. 实战工作流：接手老项目、用Playwright调前端Bug、IDE侧车协作

5.1 接手老项目：先让Agent"读"再看

前面我提到那个毛线团项目，opencode 帮我做的就是"先读后写"。接手一个陌生项目时，我会先让 Agent 做一次全库扫描式提问，比如：

"读完项目根目录的 README 和 AGENTS.md，然后告诉我：这个项目用什么技术栈、有哪些核心模块、入口文件在哪、有哪些已知的坑。"

这一步会消耗一些 token，但非常值得。Agent 读完以后，你对项目的整体认知就有了一个基本盘，后面真正要改代码的时候，能给 Agent 更精确的上下文指引。很多人在 Agent 上翻车，不是工具不行，而是上来就丢一个任务"帮我改这个 bug"，但 Agent 连项目在哪、改哪个文件都不知道。让 Agent 先读代码，就像医生先看病历再开药方，这个顺序不能乱。

opencode 的会话延续功能也值得提一下：一次会话中断后，下次可以用opencode --continue接着上次的上下文继续聊，不会因为终端重启就前功尽弃。我在处理长任务时基本都会用到这个功能。

5.2 用Playwright复现前端Bug

前端最耗时间的环节不是改代码，而是复现 Bug。传统方式是先打开页面、手动操作 N 步、打开控制台看报错，然后把报错内容复制给 AI，让它猜。现在有了 MCP 接入 Playwright，这个流程可以整个交给 opencode。

我在第 3.4 节给了配置示例，配好之后你只需要描述现象：

"打开首页，点击登录按钮，输入错误密码，点击提交，然后检查页面上是否出现错误提示，把控制台报错截图发我。"

Agent 会用 Playwright 自动完成上述操作，把页面状态、控制台日志和截图返回给你。这中间最难的部分不是工具，而是你描述 Bug 的能力。描述得越具体，Agent 定位就越快。我自己的模板是：页面路径 + 前置操作步骤 + 期望行为 + 实际行为 + 环境信息（浏览器版本、是否登录态），五个要素缺一不可。

这个工作流尤其适合那种"只在生产环境出现、本地死活复现不了"的诡异 Bug。你让 Agent 开着浏览器去生产环境跑一遍流程，把真实报错抓回来，比你在本地反复翻代码高效太多。

5.3 VS Code和JetBrains插件：TUI之外的第二入口

opencode 虽然主场在终端，但官方也提供了 VS Code 插件和 JetBrains 插件，让你能在 IDE 里直接开一个 opencode 面板，不用频繁切换窗口。

我的实际体验是：终端版适合专注模式，全屏一个窗口，没有编辑器分屏干扰；IDE 插件适合边写边聊的模式，左侧是代码右侧是 AI 对话，看到哪段代码不理解直接丢给它。两者各有适用场景，不是替代关系。

需要提醒的是，IDE 插件本质上是 TUI 的"壳"，插件里跑的会话和终端里的会话是同一套底层。如果你在终端里开了一个会话，不要同时在 IDE 插件里对同一个项目再开一个，避免两个 Agent 同时改文件产生冲突。我遇到过一次两边同时对同一个文件做修改，结果互相覆盖，比人工合并还麻烦。

5.4 桌面版与常规协作场景

opencode 的桌面版（opencode desktop）其实就是把 TUI 包了一层桌面壳，对不熟悉命令行的团队成员比较友好。产品经理或者测试同学想自己跑一个 Agent 查看项目情况，不需要打开终端，双击桌面的图标就能进入同样的界面。

我自己的团队里，前端开发用终端版，设计偶尔要在本地起 dev server 看效果，我就让 TA 用桌面版把环境拉起来，Agent 帮忙启动、输出日志、定位启动报错，省去了很多"我帮你看看"的低效沟通。这种协作方式的前提是 Agent 配置统一，团队内最好共用一个配置文件，至少也要在 AGENTS.md 里统一规范，否则每个人调教出来的 Agent 行为会差很多。

6. 一个月多平台实测：那些踩过的坑和沉淀下来的习惯

6.1 从一条server error开始排查

我遇到过一次比较诡异的报错，在 Windows 上跑opencode，每次都提示：

error: unexpected server error. check server logs

这条报错只说"服务器出问题了"，但没说哪里有问题，很让人头大。我的排查链路是这样的：先确认不是模型服务商的问题，同样的 key 在别的工具里能用；再看日志，opencode 日志默认写在数据目录下，里面会记录每次请求的细节，结果发现是因为我在opencode.json里配置的模型 ID 和实际 API 返回的模型 ID 不一致，导致请求校验失败。

这类问题的排查思路其实通用：先缩小范围，确定是工具本身的问题还是上游服务的问题；然后看日志，不要猜；最后对照配置文档检查模型名、服务商名称这些容易出错的字符串。遇到 "server error" 别慌，大多数时候不是服务器挂了，而是配置对不上。

6.2 版本更新快：2.0前后的变化

opencode 的版本迭代速度非常快，社区里也很多人搜"opencode 2.0"。版本升级带来的体验提升是明显的，但副作用是配置格式和某些命令可能会变。我第一次升级之后就遇到过配置文件格式不兼容的情况，旧版的provider字段写法在新版里不再生效，导致模型列表变空。

这里给两个建议。第一，升级前看一眼 CHANGELOG，特别是大版本升级，确认配置格式是否有破坏性变更。第二，配置文件引入$schema字段，这样每次打开编辑器都会校验格式，错误能尽早暴露。别小看这两个习惯，它们能帮你避开 80% 的升级后"莫名其妙出问题"。

6.3 什么时候该用opencode，什么时候别用

用了一个多月，我逐渐摸清了 opencode 的边界。它最适合的任务是：有明确目标、涉及多个文件、需要反复试错的工程任务，比如实现一个新接口、重构一个模块、升级依赖版本、定位一个跨模块的 Bug。这类任务让 Agent 来回跑，比人肉高效得多。

它不太适合的任务是：需求本身非常模糊、需要大量业务判断的场景。比如"把登录流程优化一下"，这句子信息量太低了，Agent 无法判断你要优化交互还是性能，给了方案你也未必满意。这种情况下，花十分钟把需求想清楚再丢给它，效果会好十倍。

另外还有一个特别容易忽略的问题：并发会话。opencode 可以同时开多个会话，但每个会话都在消耗同一个 API 账号的额度。如果你一次性开五六个会话让它们同时干活，很快会触发限流，表面上看是工具卡了，实际上是 API 侧把你限了。我现在的习惯是同时最多两个会话，一个主任务，一个临时查问题，其他都排队。

6.4 几个让我效率起飞的小习惯

最后分享三个我用下来的实在习惯。

第一个是给 Agent 立规矩。第一次进入某个项目时，花几分钟写 AGENTS.md，把项目约定写清楚。这个行为帮我节省的返工时间是最多的。

第二个是善用/models快速切换模型。复杂任务用最强的模型，简单问题切到一个便宜的模型，成本能低不少。比如代码生成用 Claude 系，格式化、解释报错这类简单任务用一个轻量模型就够了。

第三个是定期清理会话和记忆。opencode 的 TUI 里会话多了之后会有点卡，记忆太杂也会影响回答质量。我每周五收工前会把本周的会话归档、记忆清理一遍，下周开工的时候环境是干净的。

我在实际使用中发现，opencode 这类工具真正考验人的不是"会不会用"，而是"会不会把需求讲清楚"。它像一个能力很强但需要明确指令的结对程序员，你给它越清晰的边界、越具体的上下文，它给你的回报就越超出预期。如果你正准备上手，我建议从一个小任务开始，比如重构一个工具函数、给一个页面写测试，跑通之后你自然会知道下一单该让它干什么。