最近我把主要工作流从 Claude Code 慢慢切到了 opencode，坦白说一开始只是抱着试试看的心态，毕竟终端 AI 编程助手这个赛道已经够拥挤了。结果用下来发现，这个工具解决了困扰我很长时间的一个核心问题：我不想被任何一家模型厂商锁死，也不想因为换个项目就得换一套操作习惯。opencode 从设计上就把"模型提供商"和"终端 Agent 壳"彻底拆开了，你想接 Claude、GPT、本地模型还是各种聚合服务，全靠配置文件里的一段声明。这个思路对同时维护多个项目、经常在不同技术栈之间跳来跳去的人来说，几乎是刚需。
这篇文章不打算写成官方文档的复述，我会按照实际踩坑的顺序来讲：先聊清楚 opencode 到底解决了什么问题，再讲安装和 Windows 环境下那些让人头大的报错，然后给出一份可以直接抄的多模型配置方案，接着进入实战工作流——接手陌生项目、写 Skills、用 Memory 记住项目约定、接 Playwright 定位前端 Bug，最后聊聊 VSCode 和 JetBrains 插件以及我遇到过的几个典型问题。文章比较长，适合准备认真试一下 opencode 的人慢慢看。
1. 从 Claude Code 到 opencode：为什么我会切换到这个终端 Agent
1.1 终端 Agent 赛道的选择困境
用过 Claude Code 和 Codex CLI 的人应该都有同感：这俩工具本身做得都挺好，但都有一个心结——它们和自家模型绑定得太死了。Claude Code 默认只能用 Anthropic 的模型，Codex CLI 则是 OpenAI 的生态。你当然可以通过各种环境变量和参数去 hack，比如给 Claude Code 换 base URL，但这种操作本质上是在逆着工具的设计意图走，每次升级都有可能出现兼容问题，维护成本很高。
我身边不少同事的做法是"哪个项目用哪个工具"：写前端用 Claude Code，做后端试 Codex CLI，本地喜欢折腾的再加个 Continue 或者 Cline。听起来灵活，实际用起来很割裂。每个工具的对话历史不互通，slash command 语法不一样，安装位置、配置文件路径也各自为政。一个星期切换七八次之后，我最大的感受不是哪个模型更强，而是这堆工具本身已经构成了认知负担。
opencode 吸引我的第一点就是它把所有终端 Agent 的通用能力——对话、文件读写、命令执行、上下文管理、Skills、多会话——做成了一个统一底座，模型只是这个底座上的一个插槽，随时可以换。你不需要为了换模型去学习一套新的操作语法，因为操作层始终是 opencode。
1.2 opencode 解决的是"多模型自由"问题
SST 团队做 opencode 时定下的核心抽象很简单：把模型提供商（Provider）和智能体（Agent）解耦。在 opencode 的配置文件里，你可以一次性声明很多个 provider，比如 Anthropic、OpenAI、OpenRouter、Ollama、Groq，甚至是一些自定义的兼容 OpenAI 协议的网关。每个 provider 底下再挂若干模型。启动会话之后随时通过/models命令切换，不需要退出程序，也不需要改环境变量重启。
这个看起来不大的设计，实际体验提升非常大。举个例子：我以前用 Claude 做常规编码，但遇到超长上下文分析任务时，Claude 的额度很快就烧完了，这时候我只需要在 opencode 里切到一个便宜模型继续对话，而整个会话上下文、已经修改过的文件状态、对话历史都还在，模型层面的切换对当前工作没有任何中断感。这在 Claude Code 里是做不到的，至少做不到这么干净。
另一个很实际的好处是成本控制。日常小改动用便宜模型甚至本地模型，关键重构再切回最强模型。模型能力再强，也不可能在所有任务上性价比最优，能自由切换才是真正适合自己的工作方式。
1.3 2.0 重写带来的实际体验改善
如果你之前刷到过早期的 opencode，可能印象是"一个挺不错的 TypeScript 项目"。但在 2.0 这个大版本，SST 团队用 Go 做了完全重写。这个决定对日常使用最直观的影响有两点：
第一是启动速度。终端工具一旦启动需要两三秒，我是不太愿意高频使用的。现在 go build 出来的二进制，基本是秒开，体感和打开一个普通命令行工具差不多。
第二是内存占用和稳定性。TypeScript 版本的 Node 运行时内存基线摆在那里，跑一段时间后偶尔会遇到莫名卡顿；Go 版本在资源占用上明显克制了很多，连续跑几个小时的会话也不会觉得越来越重。对于我这种经常让 Agent 在后台跑长任务的场景，这是个很实在的改善。
顺带说一句，2.0 之后 opencode 的配置语法和旧版有一些差异，你在网上搜教程时如果看到很旧的配置项，建议直接去官方文档对照一下当前版本，别被过时内容带偏。
2. 安装 opencode 的三种方式与 Windows 环境下的典型坑
2.1 npm / go install / 原生脚本三条路怎么选
opencode 官方提供了四种安装方式：npm、Homebrew、原生脚本、go install。国内用户最常用的基本是 npm 和 go install，我先给出命令，再说一下各自的适用场景。
# 方式一：npm 全局安装（最常见） npm install -g opencode-ai # 方式二：go install（适合本来就装了 Go 工具链的人） go install github.com/sst/opencode@latest # 方式三：官方安装脚本（macOS / Linux） curl -fsSL https://opencode.ai/install | bashnpm install -g opencode-ai是目前最稳妥的入口，因为 npm 会帮你把可执行文件放到系统 PATH 下，Windows 上尤其省心。go install适合你本来就用 Go 开发、go env GOPATH/bin也已经在 PATH 里的情况，装完路径和依赖都不需要额外处理。官方安装脚本在 macOS 和 Linux 上体验很好，会自动识别架构并放到/usr/local/bin，但 Windows 环境下我建议还是直接用 npm。
还有一点容易被忽略：opencode 2.0 要求 Node.js 版本比较新，如果你的全局 Node 还是 16 或者更老，npm install -g opencode-ai很可能会报 engine 不满足的警告。建议至少用 Node 18+，我目前在 Node 20 环境下没有遇到任何问题。
2.2 "无法将 opencode 项识别为 cmdlet"的根因与修复链路
如果你之前在 Windows 的 PowerShell 里用过 npx，大概率也见过这类提示：
opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错本身很简单：就是可执行文件不在 PATH 里。但有意思的是，很多人明明用 npm 安装提示成功了，为什么还是找不到命令？这里有两个典型原因。
第一个原因：npm 全局安装目录没有加入系统 PATH。你可以先执行下面这行命令确认 npm 的全局 bin 路径：
npm prefix -g正常情况下会输出一个路径，比如C:\Users\你的用户名\AppData\Roaming\npm。然后确认这个路径在系统环境变量 PATH 中。如果不在，把它加进去，重新打开终端即可。
第二个原因更隐蔽：你可能用的是npx opencode临时运行。npx 会在临时目录下载并缓存包，命令本身能跑通，但如果你以为这是"安装成功了"然后到处找opencode.exe，那当然找不到。我见过不少人是这么误会的。
还有一种在线搜索时很常见的组合报错，出现在打开系统终端后直接输入：
C:\Windows\System32>opencode error: unexpected server error. check server logs这类 "unexpected server error" 其实已经不是 PATH 问题，而是 opencode 二进制能找到，但后端模型服务没有正确响应。我在第 6 章会专门讲排查链路，你先知道它和 PATH 是两码事，别混在一起处理。
2.3 桌面版与终端版的适用场景
opencode 还有一个桌面版（opencode desktop），封装了 TUI 界面，适合不太习惯纯命令行的朋友。不过我个人实际用下来觉得，如果你希望 Agent 在终端里与 Git、构建工具、文件系统深度协作，终端版永远是体验最好的形态。桌面版的优势在于界面更友好、视觉效果更直观，适合做演示或者给团队里非技术背景的成员试用。
我的建议是：主力开发机装终端版，日常操作完全够用，桌面版当作可选项。因为 opencode 的很多功能——比如时分复用（同时跑多个会话）、读取本地文件上下文、与 IDE 插件联动——底层都是围绕命令行接口设计的，纯 GUI 操作反而多了一层抽象。
另外，无论你选择哪种安装方式，装完第一件事我都建议跑一下opencode --version，确认版本号是 2.x。如果你看到的是 0.x 的版本，说明可能装到了旧版包，需要卸载后重新安装。opencode 2.0 是分水岭，新功能基本都是基于 2.0 的配置体系。
3. provider 配置与模型接入：多模型切换的核心玩法
3.1 配置文件到底该放哪：项目级与全局级的管理
opencode 的配置是通过一个 JSON/JSONC 格式的opencode.json来管理的。有两个层级：全局配置和项目配置。全局配置文件的位置在 macOS / Linux 上是~/.config/opencode/opencode.json，Windows 上是%USERPROFILE%\.config\opencode\opencode.json；项目配置则是放在项目根目录下的opencode.json。
两者是合并关系：项目配置里的字段会覆盖全局配置的同名字段。我建议这样分工：全局配置放所有项目通用的 provider 声明、默认模型、常用 MCP server；项目配置只放这个项目特有的东西，比如项目专属的 agent 指令、Skills、只需要在某个项目中启用的 MCP 服务。
这样做的理由是：provider 的 API key 和模型路由属于个人偏好，放到全局可以避免每个项目复制一份；而项目级配置跟着 Git 仓库走，方便团队成员通过同一个仓库获得一致的 Agent 行为。如果你把 API key 写进了项目级配置并且提交到了 Git，那就等于泄露密钥了，我身边已经有人犯过这个错。
3.2 从官方模型到免费模型的一个完整配置示例
下面给一个可以直接改的opencode.json示例。我同时定义了 Anthropic、OpenRouter、Ollama 三个 provider，这样日常 Claude、聚合免费模型、本地模型都能无缝切换。
{ "$schema": "https://opencode.ai/config.json", "provider": { "anthropic": { "npm": "@ai-sdk/anthropic", "name": "Anthropic", "options": { "baseURL": "https://api.anthropic.com/v1", "apiKey": "{env:ANTHROPIC_API_KEY}" }, "models": { "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" } } }, "openrouter": { "npm": "@ai-sdk/openai-compatible", "name": "OpenRouter", "options": { "baseURL": "https://openrouter.ai/api/v1", "apiKey": "{env:OPENROUTER_API_KEY}" }, "models": { "anthropic/claude-sonnet-4": { "name": "Claude Sonnet 4 (OpenRouter)" }, "deepseek/deepseek-chat": { "name": "DeepSeek V3" }, "qwen/qwen-2.5-coder-32b": { "name": "Qwen Coder 32B" } } }, "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama Local", "options": { "baseURL": "http://localhost:11434/v1", "apiKey": "ollama" }, "models": { "qwen2.5-coder:32b": { "name": "Qwen Coder 32B Local" } } } } }我这里只是示例，具体模型的 ID 要以各家服务商最新文档为准，Anthropic 线上模型编号也经常变化。你需要关注三个关键配置点：
- 环境变量引用方式：
{env:ANTHROPIC_API_KEY}是 opencode 里的标准写法，它会从当前 shell 环境变量中读取 key，不用担心把密钥写进配置文件提交到 Git。 - OpenRouter 这类聚合服务，使用的是
@ai-sdk/openai-compatible这个 SDK 包，因为大多数第三方服务都兼容 OpenAI 的接口协议。 - Ollama 本地模型本质上也是在本地起了一个 OpenAI 兼容接口，所以 provider 类型同样是
@ai-sdk/openai-compatible，不需要额外 SDK。
免费方向的思路很简单：要么用 OpenRouter 上标记为免费（:free后缀）的模型，要么用 Ollama 本地跑开源模型。OpenRouter 上注册后会获得一个 API key，里面有免费模型的调用额度，适合低成本体验；本地模型的优势是完全离线、没有额度限制，但对机器配置有要求，至少要 32GB 内存才跑得动 30B 级别的量化模型。
3.3 ccswitch 在里面的真实角色
很多人在搜 opencode 配置时都会看到 ccswitch（比如热搜词里的 "ccswitch 配置 opencode"），我解释一下它到底是什么、和 opencode 什么关系。
ccswitch 最早是给 Claude Code 用户做多 provider 切换的小工具，作用相当于一个密钥和配置的集中管理台：你在里面存好各家 API 的 key，然后通过 ccswitch 切换不同的 provider 配置，它会帮你去更新对应的环境变量文件。opencode 本身并不依赖 ccswitch，它有自己的 provider 体系。但这两者确实可以配合：如果你平时已经用 ccswitch 管理 Anthropic 等模型的 key，在opencode.json里使用{env:ANTHROPIC_API_KEY}这类环境变量引用，就能直接复用 ccswitch 切换好的环境变量文件，不用单独维护一份密钥。
简单说，ccswitch 解决的是"密钥和 provider 配置的统一入口"问题，opencode 解决的是"终端 Agent 的运行时容器"问题。两者方向不同，但在实践中可以用得很顺。
3.4 /models、/agents，会话中切换模型的操作逻辑
配置完成后，在 opencode 的 TUI 里输入/models，会看到前面配置的所有模型列表，直接上下箭头选择回车就完成切换。如果你在某个项目里临时想用一个不在配置里的模型，也可以直接用/models里的搜索框输入模型 ID 临时加载。
opencode 还支持多个 Agent 角色。默认的 build 模式负责写代码、改文件、执行命令，plan 模式只做分析和规划、不直接动文件。你也可以在配置里自定义 agent，比如docs角色专门负责文档维护。每个 agent 可以绑定不同的模型和提示词，这让"复杂任务用强模型、简单任务用便宜模型"变成了一个可以自动化的规则，而不只是手动切换。
4. 实战工作流：项目接手、Skills 复用与前端 Bug 定位
4.1 用对话让 opencode 快速理解一个陌生项目
我经常需要接手别人留下的历史项目，最痛苦的不是代码难懂，而是没人告诉你项目里哪些约定是"只可意会不可言传"的。opencode 对这种场景的帮助是实实在在的。
第一步，在项目根目录启动 opencode，然后用自然语言发指令：
请先扫描这个仓库的整体结构，告诉我： 1. 这个项目是做什么的 2. 技术栈和目录职责划分 3. 从哪个入口文件开始阅读最合理 4. 有没有 README 里没写、但代码里反复出现的约定opencode 会自行读取文件、运行ls或find命令去探查目录结构，然后给出一份总结。你不用从一开始就提供几十个文件的上下文，它会自己决定看哪些文件。这个交互方式和传统"把代码贴给 AI 看"完全不同，Agent 具备文件系统的读取权，可以像真人一样先翻目录再深入。
第二步，让它生成一份ARCHITECTURE.md放到项目里。这个文件会沉淀你对项目的理解，后续所有 Agent 会话都能参考它，也方便下一个接手的人。我甚至会在生成后手动补充一些团队特有的规范，把它当作项目的"活文档"。
第三步，对于一个比较大的仓库，建议新会话开始时先让模型读一次ARCHITECTURE.md和入口文件，再开始具体需求。这比在对话中反复澄清"这个模块在哪里"高效得多。
4.2 Skills：把团队规范变成可复用的技能包
opencode 支持 Skills 机制，这意味着你可以把一套固定的操作流程封装成一个技能，随时被对话触发。比如我团队里有一个"为组件编写单测"的约定，包含了测试框架选择、文件命名规范、mock 方式、以及提交前要跑的检查命令。正常情况下一一告诉 Agent 非常啰嗦，而且每次都会有遗漏。
我的做法是在~/.config/opencode/skills/component-test/SKILL.md下创建一个 Skill：
--- name: component-test description: 当用户要求为前端组件编写单元测试时使用。适用于 React/Vue 组件，包含测试框架、命名规范和 mock 策略。 --- # 组件单测编写规范 1. 使用 Vitest 作为测试框架 2. 测试文件与组件同目录，命名为 `[组件名].test.tsx` 3. 所有外部依赖一律 mock，保持单测隔离 4. 测试覆盖组件渲染、交互事件、props 变化三个维度 5. 写完测试后运行 `npx vitest run [测试文件路径]` 确保通过配置好之后，新会话里只要需求涉及"组件单测"，opencode 会自动读取这个 Skill 并按照里面的规则执行。这个能力的价值不亚于换一个更强的模型——它把团队的隐性知识直接注入到每次对话里，新人也很难写出不符合规范的测试代码。
Skill 的目录路径，官方文档推荐的是~/.config/opencode/skills，也可以放到项目.opencode/skills下，区别在于前者全局可用、后者跟随项目。如果你的团队有统一的代码规范，把 Skill 放进项目仓库是最好的共享方式。
4.3 用 Memory 记住"这个项目不用 npm"
另一个让我觉得"回不去了"的功能是 Memory。简单理解，它就是一个长期记忆库，会把你在某个项目中反复提到的约定自动沉淀下来，在以后的会话中自动加载。
一开始我并没有意识到自己时刻在重复"这个项目用 pnpm，不要用 npm"。直到有一次我连续开了好几个会话都在提醒同一件事，才觉得应该把这个约定固化下来。在 opencode 里，你可以直接把这类约定写到项目的 Memory 目录里，比如.opencode/memory/project-conventions.md，内容是：
- 包管理器使用 pnpm，禁止 npm install - 构建命令为 pnpm build - 不要直接修改生成的 dist 文件 - 组件导出统一使用命名导出下次开启会话时，openopcode 会把这些内容作为上下文的一部分自动加载。于是"不用 npm"这类约定就不需要反复口头交代。不只是编码规范，你也可以让 Memory 记录一些项目背景，比如"这个仓库的服务部署在 Kubernetes 上，本地通过 kubectl port-forward 访问调试"。
建议定时清理 Memory 里的过时内容，因为 Agent 对于记忆和实际代码有冲突时，往往很难自己判断以哪个为准。你可以在 code review 时顺手检查一下 memory 文件，保持它和仓库现状一致。
4.4 接 Playwright，让 Agent 自己复现并修复前端 Bug
opencode 最让我喜欢的一个场景是用它配合 Playwright 定位前端 Bug。过去复现一个前端问题是件很麻烦的事情：你要启动开发服务器、打开浏览器、按步骤操作、打开 DevTools 看报错。现在可以让 Agent 替你完成大部分重复劳动。
前提是在opencode.json里配置 Playwright 的 MCP Server：
{ "$schema": "https://opencode.ai/config.json", "mcp": { "playwright": { "type": "local", "command": ["npx", "@playwright/mcp@latest"], "enabled": true } } }配置好重启 opencode 后，你可以这样下指令：
本地开发服务器已经跑在 http://localhost:5173，请打开首页，然后点击搜索按钮，把 console 里的报错抓给我，看看是哪个接口导致了白屏。opencode 会调用 Playwright 的工具打开浏览器页面，执行点击操作，读取 Console 和 Network 的信息，然后结合项目代码分析根因。如果问题定位到了某个组件，你可以直接让它看对应的源码，甚至直接出修复补丁。
这种工作流的效率提升在于：传统模式下你要在"浏览器—DevTools—编辑器—终端"四个工具之间来回切换，现在 Agent 一次性把问题链路走完了，你只需要 review 结论和补丁。当然，这个能力越强就越需要你把开发服务器的启动方式、端口号等基础信息提前告诉它，或者写在项目 Memory 里，否则它会卡在第一步。
5. VSCode 与 JetBrains 插件：把 opencode 塞进 IDE
5.1 VSCode 插件的基本使用
opencode 官方提供了 VSCode 插件，安装方法是在 VSCode 插件市场搜索 "opencode"。安装后侧边栏会多出一个 opencode 面板，你可以在编辑器里直接打开一个 opencode 会话，不需要切到终端窗口。
插件最实用的场景是：在编辑器里选中一段代码，右键选择 "Explain" 或者 "Refactor"，插件会把这段代码连同文件路径一起发给 opencode，然后在面板中展示回答和修改建议。对于局部代码的解释、重构、单测生成，这个交互比终端里粘贴代码快得多。
插件使用的前提是本地已经安装好了 opencode 的命令行工具，因为 VSCode 插件本质上是在后台调用opencode二进制。如果你在终端里用 npx 临时跑通了，但插件报"找不到 opencode"，大概率是 PATH 没配置到 VSCode 的启动环境里。重启 VSCode 一般能解决；还不行就把 opencode 的安装目录手动加进系统 PATH。
5.2 JetBrains 插件的安装与联动
JetBrains 全家桶（IDEA、PyCharm、WebStorm 等）也有 opencode 插件。安装路径是 Settings -> Plugins -> Marketplace，搜索 opencode 安装即可。装好之后，IDE 里会有一个打开 opencode 终端的入口，相当于把 TUI 作为 IDE 内部终端运行。
这时候你可以做到：左侧是代码编辑器，底部是 opencode TUI，右边是文件树。遇到问题时直接在终端里描述需求，Agent 改完文件后 IDE 会通过文件系统监控自动刷新显示出来。这个联动虽然没有 VSCode 侧边栏面板那么"图形化"，但对 JetBrains 用户来说足够顺手了，尤其是习惯了在 IDEA 里用内置终端跑命令的人，几乎零学习成本。
有一点要注意：JetBrains 插件和 VSCode 插件一样，不会自己装 opencode，你需要提前在系统里安装好 opencode 命令行工具。两个插件目前的体验都在持续迭代中，如果你发现某个功能不稳定，别急着下结论说 opencode 不行，很可能是插件层还没跟上 CLI 版本的更新。
5.3 终端与 IDE 的分工建议
很多读者可能会问：既然有了 IDE 插件，是不是就可以完全不用终端了？我的体感是，两者定位不同，最好并行使用。
我的分工方式是：
- 终端版负责大范围重构、跨文件分析、执行构建和测试、处理 Git 操作。这些操作需要 Agent 有能力运行命令和读取完整文件系统，终端 TUI 的信息密度也更高。
- IDE 插件负责局部代码的即时解释和修改建议。比如你在读一个函数看不懂，选中让插件解释一下，或者在写代码时让插件补全一个类型定义，这种轻量操作没必要切到终端。
- 遇到需要浏览器复现的前端 Bug，优先用终端版配合 Playwright MCP。这是重操作，终端版更稳定。
千万不要让 IDE 插件和终端版同时处理同一个文件的修改。Agent 不像人那样有冲突检测意识，两个会话同时改一个文件，后写的那个人大概率会覆盖先写的东西。opencode 的命令行支持多会话并行会话，但那是为了不同任务，不是同一个文件上的并发写操作。
6. 我实际使用中遇到的报错与排查方法
6.1 unexpected server error 的完整排查过程
前面提到的error: unexpected server error. check server logs是一个很容易劝退新手的报错。我第一次遇到时以为是安装出了问题，卸载重装了好几遍，后来才发现是模型服务端返回了异常，和本机安装没有半点关系。
完整的排查链路应该是这样的：
第一步，确认二进制能跑通。先执行opencode --version，如果能正常输出版本号，说明安装没问题。
第二步，确认模型服务的连通性。如果你是用了 Anthropic 的 key，直接看环境变量有没有设置、key 是否有效：
# macOS / Linux echo $ANTHROPIC_API_KEY # Windows PowerShell echo $env:ANTHROPIC_API_KEY如果环境变量为空，回到第 3 章的示例，检查opencode.json里是否写了{env:ANTHROPIC_API_KEY}。如果用了 OpenRouter 或自定义网关，还要确认 baseURL 拼写是否正确，很多网关地址末尾多了个/v1或少了个/v1都会导致服务端返回错误。
第三步，查看 opencode 自己的日志。在 TUI 里可以输入/logs直接打开日志面板；命令行下日志文件通常会输出到数据目录，macOS / Linux 是~/.local/share/opencode/log/，Windows 在%USERPROFILE%\.local\share\opencode\log\下。日志信息里通常会明确指出是哪个 provider、哪个 URL 返回了什么状态码。看到 401 就是 key 有问题，看到 404 多半是 baseURL 或模型 ID 不对。
6.2 多 provider 切换时一个容易被忽略的坑
还有一个我踩过几次的坑，和模型名称的类型有关。opencode 2.0 的配置文件里models字段有两种写法：一种是简化写法，直接写字符串"claude-sonnet-4-20250514"；另一种是对象写法，里面可以配置name、limit、cost等信息。很多示例教程会混用这两种风格，导致你按某个老教程配置后，/models里看到的模型名和实际请求时发出去的 model ID 对不上。
我的建议是：时刻记住，TUI 里显示的是name字段，而真正发给 API 的是配置项的键名。如果你在配置里写：
"models": { "claude-sonnet-4-20250514": { "name": "Sonnet" } }那么在/models列表里看到的是 "Sonnet"，但请求时会用claude-sonnet-4-20250514作为 model ID。如果看到"模型名不存在"的报错，优先检查是不是把两者搞混了。
6.3 几个能直接抄的小配置建议
最后分享几个我在实际使用中沉淀下来的配置偏好，你可以直接复制到自己的opencode.json里，按需要修改。
第一，限制单次请求的 token 输出量，防止遇到"一次性输出几万 token"的极端情况，既费钱又容易截断：
{ "provider": { "anthropic": { "models": { "claude-sonnet-4-20250514": { "options": { "maxOutputTokens": 8192 } } } } } }第二，给不同 Agent 设置不同的默认模型。比如 plan 模式用更便宜的模型，build 模式用最强模型：
{ "agent": { "plan": { "model": "qwen/qwen-2.5-coder-32b" }, "build": { "model": "claude-sonnet-4-20250514" } } }第三，如果团队项目多、每次都要新建 Skill 或 Agent，强烈建议把配置拆成全局和项目两层。全局配置保持精简，只放 provider 和 key 引用；项目配置里放这个项目独有的 agent、skill、mcp。这样切换到新项目时，全局部分自动生效，项目部分跟着仓库走，不会有配置漂移。
我在实际使用中的体感是，opencode 的配置体系灵活性很高，但正因为灵活，很多新手容易被各种教程里的"旁门左道"配置带偏。如果遇到边界问题，先想清楚"这在架构上是谁的职责"：模型能力问题找 provider，上下文记忆问题找 Memory，操作流程问题找 Skill，工具集成问题找 MCP。想清楚这一层，大部分问题都不会让你卡太久。opencode 还在快速迭代，2.x 版本的配置项和之前相比已经有很大变化，配置前多看一眼官方文档永远是值得的。
