企业官网建设流程全解析

最近把 Claude Code、Codex CLI、opencode 这几个终端 AI 编程工具挨个试了一遍，最后在日常项目里留下来的反而是 opencode。原因很直接：它开箱即用、模型随便换、还能接本地模型，配置文件看得见摸得着，出了问题自己就能查。opencode 本质上是一个开源（MIT 协议）的 AI 编程 Agent 终端工具，仓库在 GitHub 的 sst/opencode 下，做的事跟 Claude Code 一样——在终端里读懂你的项目、帮你改代码、跑命令、看报错、提 commit——但它没有锁定某一家模型，Anthropic、OpenAI、Google、DeepSeek、Ollama 本地模型都能接，这一点对常年在不同项目间切换的人来说太关键了。

这篇东西不是官方文档，是我自己从安装到日常使用踩完坑之后的完整记录。内容包括怎么装、怎么配 Provider、怎么接免费模型、怎么用 Skills 和 Memory、怎么在 VSCode 和 IDEA 里集成、以及我在 Windows 上遇到的几个典型报错和处理过程。想找一个能长期主力用的终端 AI 编程工具、或者对 Claude Code 的闭源生态有顾虑的朋友，这篇应该能帮你省不少时间。

1. opencode 是什么：开源 AI 编程 Agent 的新选择

1.1 一句话说清楚 opencode 的定位

opencode 是一个跑在终端里的 AI 编程代理。你给它一个任务，比如“把登录接口的超时重试逻辑加上”，它会自己读项目代码、定位文件、改代码、跑测试命令，然后告诉你改了什么、为什么这么改。整个过程不是简单的代码补全，而是真正在“干活”，它能看到项目结构、执行命令、根据报错反复调整，直到任务完成或它明确告诉你卡在哪。

它和 Claude Code 最核心的区别是：Claude Code 是 Anthropic 官方的闭源工具，模型绑定在 Claude 系列上；opencode 是纯开源项目，基于 Vercel 的 AI SDK 做模型适配层，凡是支持 OpenAI 兼容接口的模型都能接入，包括各种国产模型的官方 API 和本地跑的开源模型。对于需要数据不出内网、或者想控制模型成本的人来说，这是决定性的差异。

1.2 它凭什么值得日常使用

先说几个我用下来的真实感受。第一，TUI（终端交互界面）做得舒服，配色、布局、多会话切换都比同类工具成熟，长时间盯着不累。第二，任务粒度控制好，既可以纯对话式问答，也可以让它进入 Agent 模式自己动手改，遇到大规模重构还能先用 plan 模式只规划不执行。第三，配置是纯 JSON 文件，没有藏着掖着的黑盒，Provider、模型、指令都能自己改。

和同类工具放一起看更直观：

我个人选择 opencode 当主力还有一个很实际的理由：国内访问 Anthropic 或 OpenAI 官方接口始终有各种不稳定因素，而 opencode 可以无缝接入国内能直连的模型服务，比如 DeepSeek、智谱、通义，或者内网自建的 Ollama。底层的执行能力完全一致，变的只是模型来源，这种“模型可插拔”的架构让整个工具的使用寿命长了很多。

2. 安装与首次启动：把 opencode 跑起来

2.1 安装前确认环境

opencode 有两个版本：一个是 Node.js 版，通过 npm 安装，依赖 Node 18 以上；另一个是 Go 版，从源码编译或者下载预编译二进制。日常使用我建议先装 Node 版，生态最完整、更新最同步，遇到问题社区资料也多。Go 版启动更快、内存占用更低，适合机器配置紧巴巴的情况，但部分新功能会滞后一些。

安装前先确认环境：

node -v npm -v

如果没装或者版本太低，去 Node 官网装最新的 LTS 版本就行。Windows 用户还有一个额外步骤——确认 npm 全局安装目录在 PATH 里，这一步没做好的话，装完 opencode 会直接提示“无法识别”：

npm config get prefix

在 Windows 上这个路径通常是C:\Users\你的用户名\AppData\Roaming\npm，把它加到系统环境变量 PATH 里。macOS 和 Linux 一般默认就在 PATH 里，不用折腾。

2.2 三条安装路径：npm、安装脚本、Go 源码

根据场景选一条就行。

如果你是 macOS 或者 Linux，直接用官方安装脚本最省事：

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

它会自动检测系统架构、下载对应二进制、放到/usr/local/bin下，整个过程一分钟内完成。Windows 用户建议走 npm：

npm install -g opencode-ai

装完验证：

opencode --version

如果之前用过 Go 版或者想自己编译，也可以：

go install github.com/sst/opencode@latest

不过我提醒一句，Go 方式装完的二进制在$GOPATH/bin下，这个目录也要在 PATH 里才行。装完之后别急着用，先跑一下opencode --help，能看到完整的命令说明基本就说明环境没问题了。

2.3 第一次启动：模型连接配置

opencode 安装完成后第一次运行，会进入一个引导界面，让你登录或者配置模型 Provider。这里我建议别在引导界面里折腾，直接 Ctrl+C 退出，手动写配置文件，后面可控性高得多。

先确认配置目录。macOS/Linux 是~/.config/opencode/，Windows 是%USERPROFILE%\.config\opencode\，里面放一个config.json就是全局配置。另外项目根目录下的.opencode/config.json是项目级配置，优先级更高，团队协作时可以跟着代码库走。

最简单的起步方式：设置环境变量。opencode 会自动读取常见模型服务商的 API Key 环境变量：

export ANTHROPIC_API_KEY=sk-ant-xxx export OPENAI_API_KEY=sk-xxx export DEEPSEEK_API_KEY=sk-xxx

设置好环境变量后直接运行opencode，默认模型就会尝试连接。如果你想明确指定模型，可以在配置文件里写清楚，我后面会详细拆配置结构。先跑通一条链路再说，别一上来就把配置写复杂，出问题反而不好排查。

3. 配置详解：Provider、免费模型与 ccswitch 切换

3.1 config.json 核心结构

opencode 的配置核心是 Provider 机制。一个 Provider 就是一类模型接入方式的统称，包含服务商 API 地址、密钥、模型列表。看懂 Provider 配置，你就能自由组合任何模型。

先看一个完整的例子，我拿 DeepSeek 官方 API 作为示例，因为它国内直连、便宜、而且对中文代码任务表现不错：

{ "$schema": "https://opencode.ai/config.json", "provider": { "deepseek": { "npm": "@ai-sdk/openai-compatible", "name": "DeepSeek", "options": { "baseURL": "https://api.deepseek.com/v1", "apiKey": "sk-你的密钥" }, "models": { "deepseek-chat": { "name": "DeepSeek V3" }, "deepseek-reasoner": { "name": "DeepSeek R1" } } } }, "model": "deepseek/deepseek-chat" }

拆开看几个关键字段。

npm字段指定的是 AI SDK 的 Provider 适配包。对于绝大多数走 OpenAI 兼容接口的服务，都用@ai-sdk/openai-compatible，这一个包能覆盖市面上 90% 的模型服务商。options里的baseURL是 API 地址，apiKey就是密钥，如果不想把密钥明文写进配置，也可以不填，opencode 会去读环境变量。

models是这个 Provider 下的模型映射表。左侧是模型 ID，右侧的name是你在 TUI 里看到的名字。model字段则是全局默认模型，用“Provider名/模型ID”的格式引用。比如我想默认用 DeepSeek 的推理模型，就把model改成"deepseek/deepseek-reasoner"。

3.2 免费模型接入：OpenAI 兼容接口与本地模型

“免费模型”在 opencode 语境下有两层意思：一是各平台提供的免费额度或限时免费模型，二是完全本地跑的模型，不花一分钱。

先说本地模型方案。装一个 Ollama，拉一个代码模型下来：

ollama pull qwen2.5-coder:7b ollama run qwen2.5-coder:7b

然后在 config.json 里加一个本地 Provider：

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

之后对话时按下/model切换到Ollama Local / Qwen Coder 7B，整个链路就完全本地了。这个方案适合代码量不大、隐私要求高的场景，比如处理公司内部敏感代码。

再说在线免费模型。opencode 社区一直有人维护免费 Provider 列表，比如早期的 hy3-free 等，确实是零成本跑大模型的好路子。但这些免费 Provider 的生命周期无法保证，经常说下线就下线，我见过不少人前一天还用得顺畅，第二天启动直接报 provider 不存在。我的建议是：免费模型可以拿来体验、测试配置，真正干活至少用一个付费但便宜的模型，DeepSeek、硅基流动这类按量计费、国内直连的服务是更稳的选择。

3.3 用 ccswitch 管理多 Provider

场景一多，配置文件就会越来越长。手上同时有公司内网模型、个人 DeepSeek、本地 Ollama、偶尔用一下的 Claude，切换起来很麻烦。这时候就需要 ccswitch 这类配置切换工具。

ccswitch 最早是给 Claude Code 换 Provider 用的，后来支持了 opencode，原理很简单：它维护一份多 Provider 的配置集，执行切换命令时，把当前激活的配置写入 opencode 的config.json，相当于一个可视化的配置管家。

举个例子，我先用 ccswitch 添加两个配置：

ccswitch add deepseek ccswitch add ollama ccswitch use deepseek

执行ccswitch use deepseek之后，opencode 再启动就会自动读取 DeepSeek 的配置。用 opencode go 版的朋友应该尤其习惯这套工作流，因为 go 版本身没有独立的配置管理界面，配合 ccswitch 或者直接改 JSON 是主流做法。如果你只用一个模型服务商，ccswitch 可以不用；但只要多于两个，我强烈建议装上，省得每天手改 JSON 改到怀疑人生。

4. 日常使用：命令、Skills、Memory 与实战流程

4.1 TUI 常用命令速查

opencode 启动后进入 TUI 交互界面，平时我高频用到的操作整理成了一张表：

实际使用中，plan模式是我最喜欢的。它只读代码、出方案、不落笔修改，适合在动手前先让 AI 把思路讲清楚。确认没问题之后，再切换到build模式让它实际改代码，能避免不少“AI 自作主张”的坑。

4.2 Skills 机制：让 opencode 拥有专用技能

Skills 是 opencode 的一个核心插件机制，简单说就是给 AI 准备一批“说明书”，告诉它遇到某类任务时应该按什么流程、用什么框架去处理。这比每次都在提示词里重复强调高效得多。

opencode 2.0 开始原生支持 Skills，约定存放在项目根目录的.opencode/skills/下。每个 skill 是一个带SKILL.md的目录，里面用 Markdown 描述这个技能的触发条件、执行步骤、参考规范。比如我可以写一个“代码审查”的 skill：

--- name: code-review description: 当用户要求 code review 时使用 --- 1. 先 git diff 看清楚改动范围 2. 检查是否有敏感信息硬编码 3. 排除明显的边界条件遗漏 4. 给出分级修改建议

之后项目里只要提到“review 一下这段代码”，opencode 就会自动调用这个 skill。团队内部把编码规范、上线检查清单、测试标准都做成 skills 放进仓库，新成员上手速度会快很多。

社区里已经有不少现成的 skills 集，比如 opencode 社区有人把 Claude Code 的 oh-my-claudecode 配置迁移了过来，里面包含了几十个常用 skill，从系统设计到 debug 排查都有。我自己的经验是：刚开始不用贪多，先沉淀三五个自己工作流里最痛点的 skill，用顺手了再慢慢加。

4.3 会话记忆 Memory

很多用 opencode 的人最担心的一点是“换会话之后它还记得我项目的事情吗”。opencode 的 Memory 机制解决的就是这个问题。

Memory 分两层。第一层是项目级别的规则文件，在项目根目录创建AGENTS.md，写清楚项目的技术栈、目录结构、编码规范、常用命令，每次新会话启动时 opencode 都会自动加载这个文件。这个文件就是项目的“长期记忆”，我强烈建议每个项目都维护一份，效果立竿见影。

第二层是跨会话的对话摘要，opencode 的 session 系统会在结束对话时把关键上下文沉淀下来。下次用opencode -c继续会话时，它会带着之前的结论继续工作。但如果你开了全新会话，就不能指望它自动记住所有细节——这时候AGENTS.md的价值就体现出来了，把团队规范、模块说明、易踩坑点全写进去，比什么都好使。

我现在的习惯是：接一个新项目先花 20 分钟写AGENTS.md，把目录结构、构建命令、测试命令、常见的坑全写进去。这 20 分钟的效率投资，后面每天都能省回来。

4.4 接手一个开发项目的完整流程

结合前面说到的配置，我分享一下用 opencode 接手一个陌生项目的完整流程，这就是它最值钱的使用场景。

第一步，初始化项目配置。在项目根目录执行opencode init，它会扫描项目结构，生成基础的.opencode/config.json。

第二步，写AGENTS.md。重点写清楚：项目用的什么框架、怎么跑起来、怎么跑测试、有没有特殊构建步骤。这一步信息越准确，后面 AI 的执行准确率越高。

第三步，先用 plan 模式问“这个项目的整体架构是什么，入口在哪，核心数据流怎么走的”，让它先把项目的认知讲给你听，你顺便验证它读懂了没有。

第四步，确认理解无误后，切到 build 模式安排一个具体的小任务，比如“给用户列表页加一个状态筛选”。任务粒度刚开始要小，跑通一次完整链路（改代码、跑测试、看报错、再修）之后，再逐步分配更复杂的大任务。

第五步，代码完成后坚持人工 review。opencode 改的代码不是圣旨，我会让它用 git diff 把改动列出来，逐个确认，有问题的直接让它改，不自己动手。

这个流程走下来，我现在接手一个中型的后端项目，半天时间就能让 opencode 处理大部分结构性的增删改查任务，我专心看业务逻辑和代码质量就行。

5. 生态与集成：IDE 插件、桌面版与前端 Debug

5.1 VSCode 与 JetBrains 插件

虽然 opencode 是终端工具，但真正写代码时我还是更习惯在 IDE 里工作。好在两边都有官方或社区插件。

VSCode 用户直接在扩展市场搜opencode，安装后侧边栏会多出一个面板，把终端会话嵌进 IDE 里。它能直接读取当前打开的文件作为上下文，选中代码后右键“发送到 opencode”，不用复制粘贴，体验顺滑很多。JetBrains 全家桶（IDEA、PyCharm、WebStorm 等）在插件市场搜 opencode 也有对应插件，安装后在底部工具窗口能找到，功能逻辑和 VSCode 版类似。

我的建议是：终端版 opencode 负责重活、大任务，IDE 插件负责轻量、即时的代码解释和修改。比如读代码时选中一个复杂函数，右键让插件解释一下逻辑；或者写单测时让它按当前文件风格补测试用例。两边互补，各自的优势都能发挥出来。

5.2 opencode desktop 桌面版

如果在终端里工作让你觉得有压力，opencode 也有桌面版。桌面版本质上把 TUI 搬到了独立应用里，多了窗口管理、多项目切换、更直观的会话历史界面。安装方式是官网下载对应系统的 GUI 包。

桌面版适合两类人：一类是不习惯终端界面的新手，图形界面友好很多；另一类是同时开多个项目的人，桌面版的多标签页管理比终端切目录舒服。我的主力还是终端版，但桌面版在对外演示的时候是真方便，界面看起来专业多了，领导看着也直观。

5.3 superpowers、oh-my-claudecode 等增强玩法

Skills 生态里有两个名字绕不开：superpowers 和 oh-my-claudecode。

superpowers 是一个给 AI 编程终端工具注入系统化技能集的工具，作者是 Jesse Vincent（Obra 项目），原本主要支持 Claude Code，后来 opencode 社区也跟进适配了。安装后它会在项目里生成.superpowers/目录，里面是一整套 skill 文档，覆盖头脑风暴、系统设计、任务拆解、代码审查、Debug 排查等方法论。启用之后，opencode 遇到复杂任务会自动调用对应的 skill 流程，而不是盲目开干。

oh-my-claudecode 则是 Claude Code 的一套增强配置集，社区有人把它迁移到了 opencode 上，里面整理了大量实用 skill 和 prompt 模板。我的看法是，这些增强包的核心价值不是“魔法”，而是它们把很多优秀工程师的工作方法显性化了。你不需要全盘照搬，挑选适合你项目的 skill 改一改，效果远好于直接用默认配置。

5.4 用 Playwright 让 opencode 自己找前端 bug

这一节分享一个我最近用得非常顺手的场景：让 opencode 配合 Playwright 自己测前端 Bug。

前端问题最烦的是什么？很多界面上的 Bug 是“看起来不对”，但代码层面看不出明显的错。传统做法是自己手动点页面复现，然后开 DevTools 看报错。现在 opencode 可以直接驱动 Playwright 做这件事。

操作很简单，你只需要在对话里描述现象：“打开首页，点击右上角登录按钮，输入测试账号，看看控制台有没有报错”，opencode 会调用 Playwright 启动浏览器、执行一系列操作、截图、读取控制台日志，然后根据观察到的现象定位到具体的前端文件并给出修复方案。

这个场景对配置有一些要求：项目里需要装好 Playwright 以及浏览器内核（npx playwright install），opencode 要有权限在项目里执行命令。我实际用下来，对于登录流程、表单校验、列表分页这类固定路径的交互问题，opencode 的定位速度比我手动查快很多。它最擅长的就是把“复现路径”自动跑出来，再结合报错信息判断问题源头，我只需要最后确认修改方案合理即可。

6. 高频问题排查实录

6.1 Windows 下“无法将 opencode 项识别为 cmdlet”

这是我被问过最多次的问题，也是 Windows 用户绕不开的一道坎。执行opencode时提示“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”，本质原因只有一个：opencode 安装的目录不在系统 PATH 里。

排查步骤：

# 1. 确认 npm 全局安装目录 npm config get prefix # 2. 查看该目录下有没有 opencode ls $env:APPDATA\npm\opencode* # 3. 手动把目录加到当前会话 PATH 测试 $env:Path += ";$env:APPDATA\npm" opencode --version

如果第三步能正常运行，就把这个路径加到系统环境变量里，永久生效。还有一种情况是 Node 本身版本过低，npm 全局安装时报错但没提示，导致实际上没装上。遇到这种就更新 Node 到 LTS 版本，重新执行安装命令。

6.2 启动时报 unexpected server error

运行时出现error: unexpected server error. check server logs，这个报错看起来吓人，其实大部分时候是配置连接问题。优先级从高到低排查：

第一，模型服务商的 API Key 是否有效。免费模型、过期密钥、账户欠费都会导致连接异常，先换一个确定可用的 Key 测试。

第二，baseURL 是否填对。很多 OpenAI 兼容服务商的地址并不都是标准的/v1结尾，有的隐藏在后缀路径里，照着服务商文档核对一遍。

第三，模型 ID 是否真实存在。Provider 配置里的模型名必须和服务商实际提供的模型 ID 完全一致，多一个字符、少一个字符都会报错。

第四，查看 opencode 自身日志。用opencode --debug启动，或者去日志目录（Linux/macOS 在~/.local/share/opencode/log，Windows 类似）看最新日志，里面通常会指明具体是哪个 Provider、哪一步失败了。别瞎猜，看日志是最快的。

6.3 免费模型下线与降级处理

文章前面提到过的 hy3-free 这类免费 Provider 下线问题，最近确实又发生了一轮。现象通常是：前一天还正常，第二天启动时提示 Provider 不存在或认证失败，项目里所有依赖它的会话全部不可用。

处理方式分三步。第一步，确认是不是 Provider 彻底下线，去它的官网或社区公告看状态。第二步，如果确认下线，临时切到备用 Provider，这也就是为什么我一直建议多配两三个 Provider 的原因。第三步，长期来说，别让免费模型承载关键开发流程，至少准备一个便宜的付费模型作为兜底，按量计费那种，每天几毛钱就能换来稳定。

6.4 mvn 等命令在 opencode 里找不到

Java 项目里遇到的一个常见问题：在终端里mvn -v能正常运行，但 opencode 执行 Maven 命令时报找不到 mvn。原因一般出在环境变量传递上，opencode 启动时没有继承你终端里的所有环境变量，或者 IDE 插件启动时压根没有加载 shell 配置文件。

解决方式有两个。一是确保MAVEN_HOME或者 mvn 所在目录被写进了系统级 PATH，而不是只写在 shell 的.bashrc文件里。二是在AGENTS.md里明确告诉 opencode 用项目自带的 Maven 包装器，比如./mvnw compile，因为在很多项目里mvnw比全局 mvn 更可靠。对其它命令（比如 python、java、node）也是同理，最好统一用系统级环境变量或项目的 wrapper 脚本，别依赖某个 shell 的自定义配置。

7. 总结一下我现在的玩法

最后分享几个我实际操作里总结的习惯。第一，不要把 opencode 当成万能工具，它最适合的是结构性强的增删改查和跨文件重构，涉及到复杂业务判断时，我的做法是把它当成一个“带源码的实习生”，output 永远要 review。第二，AGENTS.md值得认真写，这是投入产出比最高的配置项。第三，Provider 至少配两个以上，模型挂了随时切。第四，坚持用 plan 模式先规划、再让 build 模式动手。

opencode 这个项目还在快速迭代，2.0 版本的 TUI 和 Skills 机制比最初的版本好用了不止一个档次。工具本身是开源的，你能看到它的每一步改动，也能在社区里找到大量真实使用案例。如果你也在寻找一个可以长期依赖、不被单一模型绑定的 AI 编程工具，花一个下午配好环境，把它塞进日常工作流里，大概率不会让你失望。