企业官网建设流程全解析

如果你最近和我一样，被 Claude Code 和 Codex CLI 这类终端 AI 编码 Agent 搅得心痒痒，那你大概率也刷到了opencode这个名字。它不是哪家大厂出的，而是开源基础设施团队 SST 发起的一个项目，主打开箱即用、多模型通吃。我把它当主力工具用了大概两个月，期间经历了从 1.x 到 2.0 的升级，踩了不少安装、配置、模型切换的坑，也把 Skills、Memory、MCP 这些高阶玩法都试了一遍。这篇文章不是官方文档的翻译，而是我基于实际项目操作记录的完整复盘，从零开始讲清楚 opencode 是什么、怎么装、怎么配、怎么用到真实项目里，最后附上高频问题排查表。

我默认你是一个会用终端、跑过 Git 命令、接触过 AI 编程助手的开发者。如果你完全是新手，也没关系，前两部分我会把环境准备、安装路径、常见报错都写得很啰嗦，照做就能跑起来。

1. opencode 到底是什么，为什么我又多装了一个终端工具

1.1 从 Claude Code 和 Codex 说起：终端 Agent 的爆发

过去一年，AI 编程助手从“编辑器里的补全插件”进化成了“终端里能自主干活的 Agent”。Claude Code 让 AI 直接读代码、跑命令、改文件；Codex CLI 把 OpenAI 的模型能力塞进了命令行。这类工具的共同点是：不需要图形界面，AI 可以像人一样在项目目录里探索、执行测试、提交代码。但它们也各有痛点——有的只支持自家模型，有的配置隐藏在 JSON 里，有的想扩展第三方工具特别费劲。

opencode 就是这个赛道里杀出来的一个“全家桶型”选手。它做对了三件事：第一，模型不绑定，Anthropic、OpenAI、Google Gemini、OpenRouter、本地模型都能接，甚至任何 OpenAI 兼容的服务都能配进来；第二，它把终端 TUI 界面做得相当舒服，不是简单打印日志，而是有交互面板、文件树、对话流；第三，它是真开源（GitHub 上的 sst/opencode），社区迭代速度极快，插件机制、Skills 机制、内置浏览器调试都能用。

1.2 opencode 的特殊定位：不是大厂产品，但是工程化社区的选择

先说一个很多人问的问题：opencode 是哪家公司的？它是 SST 团队主导的开源项目。SST 这个团队之前在 Serverless 领域挺有名，做了一套部署框架，他们的技术审美很“工程化”，写出来的工具通常文档清晰、CLI 体验好、默认配置合理。opencode 也是这种调性——装完之后，第一次运行会让你选模型提供商，然后自动生成配置文件，不需要你去翻几十页文档。

它的核心架构可以理解为：一个用 Go/TUI 写的前端客户端 + 一套灵活的 Provider 适配层 + 可插拔的工具调用机制。你可以在里面跑 Agent 对话、让它操作文件、运行命令、搜索代码，也可以让它调用外部 MCP 服务，比如浏览器自动化、数据库查询。2.0 之后，官方还加入了 TypeScript SDK 和更成熟的 Skills 机制，基本向 Claude Code 的能力看齐，甚至某些方面更好用。

1.3 适合谁用：终端党、多模型党、团队标准化需求

我个人的体感是，opencode 适合三类人：

• 长期泡在终端里的开发者，习惯了 vim/neovim 或只是不想开 IDE 的轻量操作场景；
• 手头有多个模型 API（公司采购的、自建的、第三方平台的），想在一个工具里统一切换的人；
• 想给团队统一配置 AI 编码 Agent 行为的负责人，因为 opencode 的配置文件是项目级的，可以提交到 Git 仓库里，成员 clone 下来就能用同一套规则。

如果你现在的日常是 Cursor 重度用户，倒也没必要立刻换，但 opencode 作为终端补充工具，配合插件体系，完全能承担“写测试、修 bug、查文档、批量重构”这类脏活累活。

2. 安装与第一跑通：三步绕开最常见的坑

2.1 环境准备：Node.js 18+、Git、一个终端

opencode 的安装方式多种多样，但无论哪种，底层都依赖 Node.js 环境和 Git。Node.js 建议 18 以上，我用的是 20 LTS。Git 必须有，因为 Agent 执行 git diff、git commit 这些操作时，底层就是调 git 命令。Windows 上建议直接装 Git for Windows，它自带了一个 bash 环境，很多奇怪的路径问题能少很多。

检查命令我直接贴一下：

node -v git --version

只要两个命令都有输出，环境就算过关。如果 node 没有，去官网下 LTS 版本即可，这里就不赘述了。

2.2 三种安装方式：curl、npm、Homebrew 怎么选

opencode 官方推荐用 curl 脚本一键安装：

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

这个脚本会把二进制放到用户目录下的特定位置，同时打印出需要添加 PATH 的路径。目前在 macOS 和 Linux 上体验很顺。Windows 用户如果开了 WSL，也建议直接在 WSL 里跑。

我实际更常用的是 npm 安装，好处是升级方便：

npm install -g opencode-ai

注意包名是opencode-ai，不是opencode。npm 源里有另一个不相关的包占了 opencode 这个名字，官方包是这个带后缀的。如果你喜欢 Homebrew，也有现成 formula：

brew install sst/tap/opencode

不管哪种方式，装完先跑一下opencode --version确认。如果提示没找到命令，优先检查 PATH。这一步是新手最高的报错来源，我专门放到下一节讲。

另外，如果你以前装过 Go 环境，网上老教程会写go install github.com/sst/opencode@latest。这条路在早期版本确实可以，但现在官方发布物已经不太推这种方式了，因为复杂依赖和 TUI 资源文件打包会导致 go 安装版本不完整。我建议直接用 curl 或 npm，省事。

2.3 Windows PowerShell 报“无法识别 cmdlet”怎么破

这是搜索热词里出现次数最多的问题：

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

本质原因只有一个：可执行文件没有被系统找到。打开 PowerShell，输入：

where.exe opencode

如果没有输出，说明安装路径不在 PATH 里。用 curl 脚本安装时，它通常会装到%USERPROFILE%\.opencode\bin\opencode.exe或%LOCALAPPDATA%\opencode\bin之类的位置。解决办法是把对应目录加进 PATH：

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

这一步只是当前会话有效。想让下次打开终端也生效，需要设置用户级环境变量：

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.opencode\bin", "User")

然后完全关掉终端窗口再重新打开，不要偷懒只开新标签页。PowerShell 对 PATH 的缓存有时会让人误以为没生效，重启终端是最直接的验证方式。

2.4 首次运行：选 Provider 并完成登录

安装成功后，在任意项目目录下运行：

opencode

第一次启动会进入引导模式，让你选择要使用的模型提供商。常见选项有 Anthropic、OpenAI、Google、OpenRouter、Ollama 等。选了之后，它会把对应的 API Key 写入配置文件（后面会细讲），然后你就进入交互式 TUI 界面了。

这里我的经验是：第一次别贪多，先选一个最方便拿到的 key 跑通流程。比如有 Anthropic 账号就选 Anthropic，没有就选 OpenRouter 注册一个免费账号，用里面的免费模型也能体验全流程。等跑通了，再去配置多个 Provider 来回切换。

3. 模型接入与配置文件：真正用起来的核心

3.1 opencode.json：一份配置管理多套模型

opencode 的配置采用项目级优先的方式。运行opencode时，它会自动查找当前目录的opencode.json，找不到就往用户全局目录（~/.config/opencode/opencode.json）去找。项目级配置会被提交到 Git，团队成员拉代码后自动共享。

一个最基础的配置文件长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "anthropic": { "npm": "@ai-sdk/anthropic", "name": "Anthropic", "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" }, "models": { "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" } } } }, "model": "claude-sonnet-4-20250514" }

通常情况下你不用手写这么完整，运行opencode后输入/models命令，它会列出当前已经配置好的 Provider 和模型，直接选就行。真正需要手写配置的场景是：接入非标准的 API 服务，或者想给模型自定义名称。

3.2 免费模型怎么接：OpenRouter 与本地 Ollama

搜索热词里有个高频词是“opencode 免费模型”。这确实是 opencode 的一大优势——它不强绑付费 API。最常见的免费路径有两条。

第一条，OpenRouter。注册账号后生成 API Key，然后在配置里添加：

{ "provider": { "openrouter": { "npm": "@openrouter/ai-sdk-provider", "name": "OpenRouter", "options": { "apiKey": "{env:OPENROUTER_API_KEY}" }, "models": { "meta-llama/llama-3.3-70b-instruct:free": { "name": "Llama 3.3 70B Free" } } } } }

OpenRouter 的免费模型列表会变，有些模型今天免费明天收费，用/models刷新就能看到最新状态。它的优势在于模型丰富，一个 key 能测很多不同的模型，适合做横向对比。

第二条，本地模型 Ollama。如果你机器配置不错，不想把代码发给任何第三方服务，可以装 Ollama 拉一个模型起来：

ollama pull qwen2.5-coder:14b

然后在 opencode 里添加 Ollama Provider：

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

本地模型的好处是隐私和免费，缺点是能力和云端大模型差距明显。我建议用本地模型做小改、补全、简单解释代码；复杂的架构设计、跨文件重构还是交给云端模型。

3.3 ccswitch 这类切换工具：多套配置如何并行

实际用起来你会发现，光靠 opencode 自带的/models切换，配置管理有时还是不够优雅。尤其当你手上同时有公司内网服务、个人付费 API、临时测试的中转 key 时，频繁改环境变量很痛苦。

这时候社区流行的做法是配一个ccswitch之类的切换工具。这类工具统一管理多个 AI 工具（Claude Code、Codex CLI、opencode）的配置，切换时自动改写对应工具的配置文件。比如你运行ccswitch use work，它会把 opencode.json 里的 provider 全部替换成公司那套服务，还会同步设置好环境变量文件。

这种“工具再套工具”的方案听上去复杂，但实际体验很爽。我个人的配置习惯是：每个场景建一个独立的 profile，里面写好该场景的 provider、model、环境变量，然后通过 ccswitch 一键切换，再也不用手动备份和覆盖配置文件。

3.4 环境变量与自定义端点：没有模板也能跑通

接入第三方服务时，最怕的是目标服务兼容 OpenAI 格式，但 base URL 不确定。opencode 的 provider 配置给了你很大自由度，只要服务兼容 OpenAI 接口，你可以手动指定：

{ "provider": { "custom": { "npm": "@ai-sdk/openai-compatible", "name": "My Custom API", "options": { "baseURL": "https://your-api-endpoint.example.com/v1", "apiKey": "{env:CUSTOM_API_KEY}" }, "models": { "your-model-name": { "name": "Your Model Name" } } } } }

注意npm用的是@ai-sdk/openai-compatible，opencode 依赖 Vercel AI SDK，这套 provider 机制本质上就是 AI SDK 的 provider 体系。理解了这一点，你就能明白为什么它接模型这么灵活。

环境变量引用用{env:xxx}的写法，好处是 API Key 不会出现在配置文件里，适合把配置文件提交到 Git 仓库。我把项目级配置提交到仓库后，团队成员只要各自设置环境变量就能跑同一套 Agent 规则。

4. 把 opencode 真正用到项目里：Agent、Skills、Memory

4.1 接手一个老项目的正确打开方式

搜索热词里有“opencode 接手开发项目”，这是个特别好的场景。我最近用 opencode 接手了一个遗留的 Java Maven 项目，代码量十几万行，模块依赖复杂，老成员留下的文档基本等于没有。

我的做法是三步走：

第一步，先让 opencode 读项目结构，输入指令：

/init

它会生成一个 AGENTS.md 文件，记录项目的技术栈、构建命令、目录约定、测试方式。这个文件相当于给 Agent 的“入职手册”，之后每次对话它都会自动参考。对于老项目，我建议手动补充这个文件，把已知的坑、特殊配置都写进去。

第二步，让 Agent 跑一遍构建流程：

请先看一下项目的 pom.xml，跟我说清楚这是一个什么项目，然后帮我跑 mvn compile 试试

注意要明确告诉它先“看”再做，避免它上来就大改。opencode 在终端里执行命令前会显示将要运行的命令，按 y 确认后才会执行，所以就算它想乱跑，你有机会拦截。

第三步，拆任务。老项目代码维护最大风险不是 AI 不会写，而是 AI 改完不知道影响范围。我通常要求它每改一个模块就执行对应的单元测试，并且把改动按文件粒度拆成多个 commit。在 opencode 里可以直接说：“修改完成后，分别对 A 模块和 B 模块运行 mvn test，通过了再提交”，它会一步步执行，过程透明可控。

4.2 多 Agent 工作流与权限控制

很多终端 Agent 工具是单线程的，一个对话一个 Agent 全程操作。opencode 在这方面更灵活，你可以在 TUI 里输入/agents查看和切换不同的 Agent 实例。比如我跑前后端联调时，会让一个 Agent 专看前端逻辑，另一个 Agent 查后端接口，然后我把两个 Agent 的结论汇总到主对话里。

权限控制体现在文件规划和命令确认上。opencode 支持在配置里自定义 Agent 的权限规则，比如禁止 Agent 执行rm -rf、禁止修改package-lock.json、只允许在src/目录下写文件。这类规则写在配置文件的permission字段里：

{ "permission": { "deny": [ "rm -rf", "git push" ], "allow": [ "mvn test", "npm test", "git add", "git commit" ] } }

这个功能在团队场景尤其重要。新人不熟悉仓库时，经常一句话让 Agent 乱跑命令，权限规则可以兜底。

4.3 Skills 技能扩展：把 Claude Code 生态迁移过来

opencode 的Skills机制是我最喜欢的特性。简单说，Skills 是一组预置的指令和提示词，放到项目目录的.opencode/skills/下，Agent 遇到对应场景会自动加载。它的灵感来自 Claude Code 社区的 skills 实践，但 opencode 做了更规范化、更易写的实现，支持 Markdown 或 JS/TS 格式。

一个最简 Skill 长这样：

--- name: unit-tester description: 当用户要求写单元测试时，自动使用此 skill --- 先分析源文件的依赖关系，然后针对每个 public 方法生成对应的测试文件。 测试文件放在与源文件相同的目录下，命名规则为 <原文件名>.test.ts。 运行测试命令前先检查依赖是否安装。

把这个文件放在.opencode/skills/unit-tester/SKILL.md，并在配置里启用 skills 目录，Agent 就会在相关场景下自动读取这段说明，改变它的行为。

我知道不少人在 Claude Code 里用的是 “superpowers” 这类技能合集，那套体系里有很多精心打磨的 skill 文件。迁移到 opencode 是可行的：因为技能本质上是提示词加规则，把.claude/skills/下的 Markdown 文件复制到.opencode/skills/，再做少量格式调整即可。opencode 社区也有脚本能自动转换，我自己手动迁移过两次，成本很低。真正值钱的其实是那些规则文本，不是存放它们的文件夹。

4.4 Memory 记忆：让 Agent 记住项目约定与偏好

AI 编码 Agent 最气人的一点是：今天告诉它的约定，明天可能就忘了。opencode 提供了一个规范化的记忆机制，配置项里可以设置全局记忆文件和项目记忆文件。默认情况下，全局记忆在~/.config/opencode/memory.md，项目记忆在.opencode/memory.md。

它的工作方式是这样的：每次会话开始时，Agent 会读取这些记忆文件作为上下文；会话过程中，如果发现需要记录新的约定，可以直接要求它“把这个规则记到 memory”，它会主动更新对应文件。我用了一段时间后，项目记忆里积累了不少有价值的内容，比如“不要修改公共 API 的返回结构，除非通过新增参数方式兼容”“部署分支是 release，不要直接推 main”。

配合 AGENTS.md 使用，效果更好。AGENTS.md 偏向项目的静态事实，memory.md 偏向动态经验。前者可以提交到 Git 仓库给所有人共享，后者可以只在本地维护。当然你也可以都提交，看团队习惯。

4.5 用 Playwright 驱动前端 bug 排查

再讲一个搜索热词里出现过的具体场景：“opencode playwright 怎么测试前端 bug”。这在之前的版本里要自己配置半天，现在 opencode 2.0 自带了浏览器调试工具，通过 MCP 协议接入了 Playwright 自动化能力。

实测流程是这样的：在 opencode 的对话里直接说“打开浏览器，访问本地 5173 端口，打开页面后点击登录按钮，看看控制台有没有报错”。Agent 会自动启动一个 Playwright 驱动的浏览器实例，执行点击、输入、截图、读取控制台日志等操作，然后把结果反馈到你面前。

我遇到过一个很隐蔽的前端 bug：某个弹窗组件在特定分辨率下不会正常弹出，单纯看代码很难定位。我让 opencode 用 Playwright 打开页面，把视口改成 1366x768，点击触发按钮，它通过截图和控制台日志帮我确认了问题出在 CSS 媒体查询和弹窗挂载时机冲突。整个排查过程几分钟搞定，比我手动开 devtools 快很多。

5. 编辑器与桌面端：不止是黑窗口

5.1 VSCode 插件：边看代码边对话

虽然 opencode 主阵地是终端 TUI，但官方提供了 VSCode 插件，扩展 ID 可以搜 “opencode”。安装后，编辑器左侧会多一个面板，能直接基于当前打开文件发起对话、查看 opencode 正在执行的命令、浏览 Agent 产生的 diff。这个插件适合在“需要边看代码边指挥 Agent”的场景。

我用 VSCode 插件时，最顺手的是把 opencode 作为“代码解释器”：选中一段不熟悉的代码，右键选择“用 opencode 解释”，它会把解释结果输出到侧边栏，不用切到终端去问。这比传统的人工去翻调用链效率高很多。

当然有个前提：VSCode 插件本质上是 opencode CLI 的壳，你必须先保证opencode命令能在系统终端里直接运行，插件才能正常连接到核心进程。

5.2 JetBrains IDEA 插件与 Maven 项目配置

搜索热词里还有 “opencode jetbrains idea 插件” 和 “opencode mvn 配置”，这俩是连在一起的。官方确实有 JetBrains 插件，支持 IntelliJ IDEA、PyCharm、WebStorm 等基于 IntelliJ 平台的 IDE。插件用法和 VSCode 版类似，安装后会在右侧打开一个 opencode 工具窗口。

对于 Maven 项目的配置，我的建议是：不要把 Java 构建交给 AI 自由发挥，而是事先在 opencode 配置里把常用 Maven 命令写成快捷方式。比如在配置文件中自定义一个 agent 指令：

{ "agent": { "mvn-test": { "prompt": "对当前 Maven 项目执行 mvn test，只汇报测试失败项，不要修改任何代码" } } }

这样每次只要输入/agent mvn-test，它就只干活不乱动。Java 项目构建时间长，Agent 在执行命令时如果超时，需要调大 TUI 里的超时时间或手动延长命令等待，这个我放在常见问题里讲。

5.3 桌面版与内置 UI 日志

opencode 桌面版是后来才有的，适合不喜欢终端交互的人。它能以桌面应用方式运行，相当于把 TUI 界面平移到了独立窗口里，同时增加了日志查看面板。如果你在 IDE 插件和终端之间切换觉得割裂，桌面版可以考虑作为中转站。

我实际使用经验是，桌面版的价值主要体现在两点：一是进程崩溃时能直接看到底层日志，不用去终端里翻；二是可以同时开多个项目窗口，每个项目一个 Agent 会话，互不干扰。终端里同时开多个 opencode 会话也能做到，但窗口管理没桌面版直观。

6. 高频问题排查与配置速查

6.1 常见报错对照表

这些是我在各大社区里看到以及自己踩过的坑，整理成表方便查阅：

6.2 关于“opencode 套餐”和费用问题

很多人问 opencode 收不收费、有没有套餐。opencode 本体是开源免费的，你需要付费的只是底层模型 API 的调用费用。如果你用 Anthropic 或 OpenAI 的官方 API，费用按 Tokens 计费；用 OpenRouter 免费模型或本地 Ollama，就接近零成本。没有所谓的“opencode 官方套餐”，如果有人向你推销，请谨慎判断，大概率是套了一层壳的第三方服务。

6.3 2.0 升级的关键变化

如果你和我一样是从早期版本升上来的，需要注意几个变化。2.0 重构了客户端架构，TUI 界面响应更快，新增了更清晰的 Agent 切换面板；Skills 机制从实验性变成了一等公民；记忆文件路径有调整，旧的~/.config/opencode结构建议迁移到新格式；插件生态也开始规范化，VSCode、JetBrains 插件都同步更新了连接协议。

升级后如果发现旧项目里 Agent 行为突然变了，先检查AGENTS.md和.opencode目录是否被旧的流程覆盖，必要时重新跑一遍/init生成适配 2.0 的说明文件。

7. 什么情况下我依然会切回其他工具

说了这么多 opencode 的优点，最后讲点实在的个人感受，也算给还在观望的朋友一个参考。

opencode 并不是所有场景的银弹。如果你团队全员重度使用 IntelliJ 系 IDE，习惯 Cursor 那种“代码块内联补全 + 对话改代码”的交互，那直接给每个人都装终端 Agent 不一定合适，学习成本和习惯冲突都真实存在。另外，如果你的项目高度依赖专属 IDE 的智能索引（比如大型 Java 工程的复杂重构），opencode 的能力边界会明显，它更适合做“读代码、解释、写测试、批量改小逻辑”这类事情，而不是替代你思考整体架构。

我现在的工作流是：每天开机会打开 opencode 的桌面版挂在旁边，日常改 bug、写单测、整理文档都交给它；遇到需要大范围重写或跨模块协调的活儿，我会切回 IDE 里的完整工具链。Claude Code 和 Codex 我也还在用，opencode 胜在模型自由和开源透明，但对 Anthropic 官方模型的原生调优深度，仍然是 Claude Code 体验最顺。所以准确说，不是选一个抛弃另一个，而是让它们各自做最擅长的事。

如果在配置过程中遇到某个具体报错，最好把完整的错误信息连同 opencode 版本号贴给社区或翻一下官方 issue。这个项目更新频率很高，很多坑在下一个版本就修掉了，别卡在一个地方太久。