企业官网建设流程全解析

最近折腾 opencode 折腾得比较深，从命令行到 IDE 插件，从改配置到让它自己跑 Playwright 定位前端 Bug，前前后后踩了不少坑，也沉淀出一套比较顺手的用法。如果你也在用或者准备用这类的终端 AI 编程代理，这篇文章应该能帮你少走很多弯路——我会从它是什么、怎么装、怎么配模型，一路讲到怎么用 skills、memory 和 MCP 把 opencode 调教成真正能干活的项目助理。

先说清楚一个点：opencode 不是某个大厂做的一个"套壳工具"，它是一套开源终端 AI 代理（terminal AI agent），核心思路是在命令行里给你一个能够读写文件、执行命令、调用各种工具的 AI 助手。它跟你平时用的代码补全插件是两码事，补全是在你写代码时给建议，而 opencode 是直接接手一个小任务，自己去读代码、改文件、跑测试。这两者的使用场景和思维方式完全不同，下面我会详细拆。

1. opencode 是什么，解决什么问题

1.1 一个终端里的 AI 编程代理

opencode 最早是 SST 团队开源的项目，作者 Dax Raad 在做 Serverless 开发工具时发现，开发者真正需要的不是一个"对话框"，而是一个能主动干活、能读懂项目上下文的代理。所以 opencode 的设计目标非常明确：在终端里跑一个和你在同一个代码仓库工作的 AI，它能调 shell、读文件、修改代码、调用 MCP 工具，还能和 Git 交互。

从用户视角看，你在命令行敲opencode就会进入一个交互式 TUI（文本界面），默认会加载当前目录的代码上下文。你可以直接问"这个项目的入口在哪，依赖注入是怎么组织的"，也可以下达实操指令"把 userService 里重复的三个 try-catch 抽成公共异常处理"。它俩的区别就在这：前者是问答，后者是任务执行。

我在实际使用中最常用的是后者。比如接手一个老项目时，我会直接跟 opencode 说"梳理一下这个仓库的技术栈、目录结构和核心模块，写一份 README 补充建议"。它会自己遍历目录、读取关键文件、归纳总结，不用我一个文件一个文件看。

1.2 它和普通代码补全工具的本质区别

用 Copilot 或者 Continue 这类补全插件时，你的工作流是"人在回路"：AI 给建议，你审核、接收、修改。opencode 的工作流更像是"目标委托"：你把一个明确的目标交给它，它自己规划步骤、逐个执行、遇到问题还可以自己修。

这个区别听起来不大，实际用起来差异巨大。补全工具是单向的，它永远不会主动发现"你的测试挂了，顺手给你跑一下"；但 opencode 可以。比如你让它"完成某个接口的重构"，它完成修改后可能会自己运行npm run test，看到报错再回来改代码，循环往复直到测试通过。

当然，这也意味着它需要的权限和上下文比补全工具大得多。所以 opencode 提供了非常细粒度的权限控制，你可以规定哪些命令可以自动执行、哪些操作需要确认、哪些目录不允许写。第一次用的人很容易忽略这个配置，后面我会详细讲。

1.3 适合谁用

三类人我觉得最适合用 opencode：

第一类是日常在终端里工作的后端和全栈工程师，尤其是经常要跨模块改代码、做重构、写测试的人，这类工作正好是代理型 AI 的强项。

第二类是经常要接手别人代码的人。opencode 的/init可以生成 AGENTS.md，相当于给 AI 看的一份"项目说明书"，把代码库结构、技术约束、常用命令都沉淀下来。接手新项目时这一步特别香。

第三类是愿意折腾、对模型选择有自己偏好的人。opencode 不锁死某个模型，你可以用 Anthropic、OpenAI、DeepSeek、智谱，也可以用本地部署的开源模型，配置灵活度远高于那些只绑官方服务的工具。

2. 安装与环境准备，从零跑通

2.1 三种常用安装方式

opencode 的安装方式现在比较成熟，主要用包管理器或者官方安装脚本。我自己在 macOS 和 Windows 上都装过，推荐方式如下：

• macOS 推荐用 Homebrew：brew install sst/tap/opencode，装完直接有opencode命令，升级也方便。
• Linux 或 WSL 推荐官方脚本：curl -fsSL https://opencode.ai/install | bash，默认装到~/.opencode/bin。
• Windows 原生环境或者 Node 生态用户可以用 npm：npm install -g opencode-ai，前提是本机有 Node.js 18 以上。

装完先跑一句opencode --version确认安装成功。如果输出一串版本号，说明基础环境没问题；如果提示找不到命令，大概率是 PATH 的问题，下一小节专门讲。

这里插一个体会：如果你平时主力机器是 Windows，但开发环境在 WSL 里，那就在 WSL 里装一份，别在 Windows 原生环境里装完再跨系统调用，文件路径和命令执行都会绕远路。

2.2 "无法将 opencode 项识别为 cmdlet"到底怎么解

这个报错在 Windows 上非常常见，很多人在 PowerShell 里运行opencode时直接看到：

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

这行中文报错本质上就是系统找不到opencode这个可执行文件。原因就两个：

第一个原因最简单——压根没装上，或者装了一半失败。先确认那三种安装方式至少成功了一种，再继续排查。

第二个原因是环境变量 PATH 没配好。用 npm 安装时，全局 bin 目录未必在 PATH 里。我用一条命令就能定位问题：

npm prefix -g

这条命令会输出全局安装根目录，比如C:\Users\你的用户名\AppData\Roaming\npm。检查这个目录下有没有opencode.cmd或者opencode.ps1。有的话，把该目录加进系统 PATH 就行。

官方脚本方式安装的话，可执行文件一般落在%USERPROFILE%\.opencode\bin，同样把它加入 PATH 后，重新开一个 PowerShell 窗口就好。

如果你不想改系统环境变量，还有一个临时但可靠的替代方案：直接用npx opencode-ai运行，或者运行完整路径。比如：

npx opencode-ai

这种方式适合应急确认"是不是 PATH 的问题"，但日常使用还是建议把 PATH 配好，否则每次都要记得包一层。

2.3 第一次启动需要做什么

装好后第一次运行opencode，它会检查你本机的模型配置。默认情况下它支持通过环境变量读取各家模型的 API Key，比如ANTHROPIC_API_KEY、OPENAI_API_KEY。你至少配好一个，才能正常对话和干活。

我建议第一次进 TUI 后先敲/models看当前可用模型列表，然后切到你计划用的那个模型。再敲/config打开配置面板，确认权限模式是否符合预期。

还有一个容易被忽略的细节：opencode 会把会话历史、配置、日志写入用户目录下的.local/share/opencode和.config/opencode。如果你的磁盘空间紧张或者有备份需求，要留意这两个目录。

3. 模型接入与配置管理

3.1 配置文件长什么样

opencode 的配置核心是 JSON 文件，全局配置默认在~/.config/opencode/opencode.json（Windows 下是%USERPROFILE%\.config\opencode\opencode.json），项目级别的配置放在仓库根目录的opencode.json里，后者会覆盖前者。

一个最小可用的配置大概是这样的：

{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4", "provider": { "anthropic": { "api_key": "env:ANTHROPIC_API_KEY" } }, "permission": { "default": "ask" } }

model字段指定默认模型，注意格式一般是提供商/模型名。provider下面是各家 API 的认证信息，推荐用env:变量名的写法而不是直接把密钥写进文件，因为配置文件经常要同步到多台机器甚至提交到仓库做团队共享，明文密钥容易出事。

permission控制工具的调用权限。"default": "ask"表示所有敏感操作都要先问过我，写代码、读文件这类相对安全的操作也建议保留确认。另一种常见玩法是"default": "allow"配合"deny"列表，适合完全信任场景，比如 CI 里跑自动化任务。

3.2 免费模型和低成本方案怎么选

opencode 本身不卖模型，它是纯粹的客户端工具。你担心的"套餐"问题，其实是模型提供方的计费策略。如果你不想一开始就花钱，有几条路可以走。

最稳的低成本路线是本地模型。用 Ollama 拉起一个开源编程模型，然后告诉 opencode 走本地接口就行。以 qwen2.5-coder 为例，本地装好 Ollama 后拉取模型：

ollama pull qwen2.5-coder:14b

然后在 opencode 配置里加一个 provider：

{ "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "qwen2.5-coder:14b": { "name": "Qwen Coder 14B" } } } }, "model": "ollama/qwen2.5-coder:14b" }

本地模型的优点是免费、数据不出机器、可以无限折腾；缺点是模型能力天花板有限，写复杂重构时容易给你"一本正经地写错代码"。我的建议是：本地开源模型适合做跑通流程、处理简单机械任务、敏感代码场景；需要高质量重构和架构决策时，还是切到能力更强的云 API。

云 API 方面，国内可以正常访问的服务商也有不少选择，比如 DeepSeek、智谱、Kimi 这些都有开发者接口。它们的计费普遍是预充值、按 token 消耗，对个人开发者来说，日常写代码辅助一个月成本其实很可控。还有一种思路是留意一些服务商的首充赠送额度或免费试用包，先把流程跑通再决定是否充值。

3.3 用配置工具统一管理多套模型配置

用 opencode 时间长了，你会发现自己手上不止一个 API Key，也不止一个模型。今天想用 A 模型做代码审查，明天想用 B 模型做前端调试，总不能每次都打开 JSON 改一遍。

这个场景下，很多人会引入 ccswitch 这类配置管理工具。它的核心作用是把"当前 API 的路由和 Key 指向"独立出来统一管理，让你在切换模型服务商时不用动 opencode 的配置结构，只需要在 opencode 里通过环境变量读取当前生效的配置即可。这类工具的好处是环境变量层面的解耦，多个终端工具（opencode、Codex CLI、其他 AI 助手）可以共享一套密钥管理和路由策略，避免每个工具里都维护一份重复的配置。

我自己实践下来的一个简化做法是这样的：不用额外工具，只是写了一个switch.sh脚本，里面导出不同服务商的环境变量，然后用不同的opencode配置目录启动。本质上是用 shell 脚本管理多套环境。但如果你同时用很多 AI 命令行工具，那上一个统一的配置工具确实更省心。

4. IDE 集成与完整实战工作流

4.1 VSCode 与 JetBrains 插件

opencode 不只在终端里能用。官方提供了 VSCode 插件和 JetBrains 插件，装好之后可以在编辑器里直接调起 opencode，选中的代码可以一键发送给 AI 让它分析或修改。

VSCode 插件直接在扩展市场搜 opencode 就能装。装完会在侧边栏或命令面板里看到一个入口，选中代码后右键，选"Open in OpenCode"（不同版本菜单位置可能略有差异），它会带着选中的代码上下文进入会话。这个功能在审查某段复杂逻辑时特别有用，不用自己手动复制粘贴一大坨代码，还要担心上下文丢失。

JetBrains 系的 IDEA 插件同理，装好后在编辑器内右键就可以把代码送进 opencode 会话。需要注意插件和 CLI 共享同一份全局配置和会话存储，所以你在终端里配置好的模型、skills、memory，在 IDE 里一样生效，不用重复配置。

我用下来的感受是：IDE 插件适合"局部代码理解"，比如看不懂一个函数的作用域和调用链；终端里的 TUI 适合"全仓库范围的任务"，比如跨模块重构、跑测试、批量替换。两者配合能覆盖从微观到宏观的所有场景。

4.2 接手存量项目的第一小时

这是我到目前为止觉得 opencode 最值回票价的使用场景。

拿到一个没见过的老仓库，我一般这样处理。首先进入项目根目录跑opencode /init，这一步会要求 AI 浏览整个代码库，生成一份 AGENTS.md。这份文件会写入仓库根目录，里面包含项目结构说明、技术栈、构建命令、约定规范等。AGENTS.md 既是给 AI 看的项目说明书，也是给你自己的极简开发者文档——接手新项目时它比很多陈旧 wiki 管用。

然后我会给 opencode 下达三个连续任务，把项目快速"啃"下来：

1. 让它定位入口文件和核心路由，梳理请求从上到下的调用链；
2. 让它找出数据模型和数据库迁移的关键定义，整理出一份字段关系说明；
3. 让它列出项目里明显的技术债，比如循环依赖、重复代码、过时的依赖版本。

这三个任务执行完，我对新项目的了解速度远超自己埋头读代码。关键点是每次任务描述要尽量明确输出格式，比如"用列表"，"标注文件路径"，"指出你拿不准的部分"。AI 代理最怕的就是模糊需求，给它越明确的产出要求，结果越可预期。

4.3 skills 让助手具备团队规范

opencode 的 skills 机制，简单理解就是给 AI 预置一些"专项技能"，让它在处理特定任务时遵循特定的流程和标准。它的形态是一组自定义指令文件，放在.opencode/skills目录下（项目级）或全局 skills 目录下。

每个 skill 一般由一个 YAML 头和一个 Markdown 说明组成。比如我想让 opencode 按团队规范审查 PR，可以建一个.opencode/skills/review.md：

--- name: review description: 按团队规范进行代码审查，重点关注正确性、可维护性和性能 --- 当执行代码审查任务时，必须遵循以下步骤： 1. 先梳理变更涉及的模块和影响范围 2. 检查错误处理是否完整，禁止吞掉异常 3. 确认所有新增依赖都有明确必要且版本锁定 4. 对可疑逻辑给出修改建议而不是只提出问题 5. 最终输出按"问题清单/建议清单/可忽略项"三部分组织

之后你在会话里告诉 opencode"用 review skill 审查这次的改动"，它就会按这个流程执行。它的价值在于把团队的工程规范沉淀成 AI 可执行的指令，而不是每次靠你现场口述。

skills 的粒度可以很细。我见过有人给前端项目做了一个"Vue 组件规范"的 skill，要求所有新组件必须用 script setup 语法、样式必须用 scoped、props 必须带默认值；也有人给后端项目做"接口设计"的 skill，规定所有 REST 接口必须补充 OpenAPI 注解。这些规范写进 skill 后，AI 生成的代码合规率明显提升。

4.4 memory 记住你的偏好

如果说 skills 解决的是"任务怎么做"，那 memory 解决的就是"长期偏好怎么存"。

opencode 的 memory 功能可以把一些零散的、跨会话要记住的信息持久化下来。比如你多次纠正 AI"这个项目测试框架是 vitest 不是 jest"，或者"数据库迁移不要直接改旧迁移文件，要新增一个"，这些偏好如果能被 AI 记住，后续会话就不用反复调教。

实际用法有两种：一种是会话里直接告诉 opencode"记住：本项目测试命令是 pnpm vitest"，它会写入记忆；另一种是手动编辑 memory 文件，全局记忆在~/.local/share/opencode/memory，项目级记忆在.opencode/memory。

我的建议是：凡是"和具体代码无关、只和团队习惯/项目长期约定有关"的偏好，都值得丢进 memory。这样即使隔一个月再打开这个项目，AI 仍然知道你的规矩，不会每回都从零开始猜。

4.5 用 Playwright MCP 定位前端 Bug

这个热词问的人很多：opencode 怎么用 Playwright 测试前端 Bug？答案是通过 MCP（Model Context Protocol）给它接一个 Playwright 服务。

MCP 是 AI 工具接入外部能力的标准协议，可以把它理解成"AI 的 USB 接口"。opencode 原生支持 MCP，所以只要跑一个 Playwright 的 MCP 服务，AI 就能启动浏览器、打开页面、点击元素、读取 console 日志、截图，然后把观察到的信息反馈到推理过程里。

配置方式是在 opencode.json 里加一段：

{ "mcp": { "playwright": { "type": "local", "command": ["npx", "-y", "@playwright/mcp@latest"], "environment": {} } } }

配置好之后，你可以在 opencode 会话里描述一个 Bug 现象，比如"点击登录按钮后没有跳转，控制台疑似报错，帮我定位一下"。opencode 会自己去打开页面复现，读取控制台信息，结合你给的上下文分析原因，甚至直接给出修复建议。

我实际踩过的一个坑是：Playwright MCP 启动的浏览器实例默认是带界面（headed）还是无头（headless）模式，直接影响了在服务器环境下的可用性。本地开发建议用带界面的，能看到它打开的是什么页面；在 CI 或远程环境则要切 headless，否则会因为没有显示器直接报错。具体配置项建议查一下当时的 Playwright MCP 文档，它更新比较勤。

5. 高频报错与横向横评

5.1 高频问题速查表

我把这段时间收集到的问题整理成了一张表，覆盖我见到的大部分初学痛点：

一个通用排查思路：opencode 的问题最好从日志入手。运行opencode --log-level DEBUG，启动后会输出详细的调试日志，包括它调了哪个模型、请求体大小、工具执行结果。大多数"莫名其妙"的问题都能在日志里找到答案，比自己瞎猜高效得多。

5.2 opencode vs Codex vs Claude Code，怎么选

最近社区里讨论最多的问题就是这个：这几个终端 AI Agent 到底选哪个？

Codex CLI 是 OpenAI 出品的官方 CLI，最大的优势是和 ChatGPT 生态深度绑定，登录 ChatGPT 账号就能用，初始配置成本极低。如果你重度使用 OpenAI 模型并且经常用到 OpenAI 系的工作流，选 Codex 很顺。它的主要限制也在这里——模型选择基本锁死在 OpenAI 体系内，私有化部署和多模型切换的灵活性比较弱。

Claude Code 是 Anthropic 的官方终端工具，在代码理解和长上下文处理上做得相当成熟，写复杂重构和大型项目分析时表现很强。但它同样绑定 Anthropic 模型，而且目前的授权方式对非订阅用户不太友好，想用免费或者低成本方案时比较尴尬。

opencode 的优势在于它的"中立性"。它不绑定任何模型，你可以自由选择不同提供商的模型，甚至可以切成多个模型协作。对于团队来说，这意味着可以按任务类型分配模型——简单任务用便宜模型，复杂架构任务用好模型，整体成本更容易控制。它还开源，遇到问题可以自己改代码修 Bug，社区也活跃。

我的建议是：如果你只想快速体验"终端 AI 代理"这件事，且已经有某个平台的订阅，那就直接用对应的官方工具，比如 Codex 或者 Claude Code。如果你打算长期把 AI Agent 作为日常开发基础设施，同时在意成本、隐私、可配置性，那 opencode 是更值得投入时间去折腾的那一个。它前期的配置成本比官方工具高一点，但把配置、skills、memory 和 MCP 体系搭好之后，你能获得的是一个完全按自己习惯定制的 AI 开发助手，这种掌控感是官方工具给不了的。

再说一个很多人问的：opencode 的"套餐"到底值不值。工具本身开源免费，你要是自己配模型，费用全在模型调用上。但如果你不想折腾配置，官方也提供托管方案，按订阅制收费，具体价格以官网为准。我个人的看法是：个人开发者先用自带配置的免费路径跑熟再说，团队再考虑付费托管，别一步到位买套餐。

这个内容后续还可以这样扩展：把团队工程规范全量沉淀成 skills，把项目的架构决策记录到 memory，再在 CI 里跑一个"opencode review"作为自动代码审查的一道关卡。我现在已经在自己维护的几个项目里跑通了一部分，最明显的变化是接手老项目的心态——以前是"这代码能跑就行，别动"，现在敢让 AI 去拆解、重构、补测试，因为每一步改动了什么、为什么改，它都能讲清楚。踩过几次坑之后，我最大的体会是：这种工具用得好不好，根本不取决于模型有多强，而取决于你有没有把项目上下文、团队规范、权限边界这三件事交代清楚。把这些做好了，opencode 是真的能在你的开发流程里顶一个人用的。