1. 为什么要在 OpenCode 里折腾多智能体、MCP 和技能包
如果你已经在终端里用 OpenCode 写过代码，大概率经历过这个阶段：单模型、单会话，问一句答一句，遇到复杂任务就开始来回粘贴上下文。OpenCode 本身是个开源的终端 AI 编程工具，能读写代码、执行命令，但真正把它从「聊天框」变成「工程化开发环境」的，是后面这三层扩展：多智能体负责分工，MCP 服务负责给模型接上外部感官，技能包负责把领域规范沉淀成可复用的知识。
我这次的目标很明确：在本地开发机上，把 OpenCode 从单一模型对话，扩展成一套能跑通完整链路的环境。具体来说，要交付四样东西——一份可复制的opencode.json配置、MCP 服务的注册步骤、技能包的目录结构，以及多智能体调用和 MCP 连通性的验证动作。适合谁看？适合已经装过 OpenCode、想进一步做工程化配置的开发者，尤其是前端方向、需要读设计稿和查文档的场景。
整套环境用到的组件大致是这样：OpenCode 主程序作为入口，oh-my-opencode插件提供多智能体编排，5 个 MCP 服务分别负责网页读取、联网搜索、图像理解、GitHub 仓库阅读和蓝湖设计稿读取，技能包则分全局和工程两层。模型层我选了一个能力均衡的默认模型，视觉任务单独走多模态模型。下面按配置链路一步步来，每一步都给可复制的片段。
先说一下整体架构，方便你建立心智模型。用户在终端输入 → OpenCode 主程序 → 多智能体层（编排、检索、评审、视觉）→ MCP 工具层（联网、读网页、看图、读仓库、读设计稿）→ 技能包层（领域知识与规范）→ 模型层。这五层里，模型层是底座，多智能体层做任务拆解，MCP 层扩展模型的「感官」，技能层约束生成风格。各层相互独立，你可以只装主程序加一个 MCP，也完全能用。
2. 前置准备：Node 环境、账号与统一 Key 接入
在动配置文件之前，先把地基打好。软件依赖主要是 Node.js，版本要求 20 以上，我用的是 22.x，用 fnm 做版本管理。另外蓝湖 MCP 需要 uv，这个是可选项，不用蓝湖可以跳过。账号方面，你需要一个能开通 Coding Plan 的账号来获取 API Key，智谱系的几个 MCP 共用同一个 Key，这点后面配置时会体现。
这里要重点说一下统一 Key 接入的思路。很多人在配 MCP 时最头疼的就是每个服务一个 Key，管理起来乱。TaoToken 的做法是提供一个统一的 API 入口，你只需要维护一份 Key，就能在多个模型和工具之间复用。它的官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。这个统一 Key 的价值在于：你配置opencode.json时，模型调用和 MCP 鉴权可以走同一套凭据，迁移到新机器时只需要替换一处占位符。
安装 OpenCode 本身很简单，一条 npm 命令搞定。装完之后先验证版本，确保不低于 1.18.19，低版本可能不支持某些 MCP 类型。然后登录、拉取模型列表，确认默认模型可用。如果模型列表里找不到你要的，先升级 OpenCode 再试。这一步的完整命令如下：
# 安装 Node 22（已装可跳过） winget install Schniz.fnm fnm install 22; fnm use 22; fnm default 22 # 安装 OpenCode npm install -g opencode-ai opencode --version # 需 >= 1.18.19 # 登录并验证模型 opencode auth login opencode models | findstr glm登录时选择对应的 Coding Plan，粘贴你的 API Key。验证模型是否可用，可以用opencode models看列表，也可以直接进对话问一句。如果列表里没有目标模型，先执行npm update -g opencode-ai升级后再试。这一步踩过的坑是：有些人装完直接改配置，结果模型根本没登录成功，后面所有 MCP 都报鉴权错误，排查半天才发现是登录环节漏了。
环境准备好之后，建议先跑一次最简对话，确认主程序本身没问题，再往上叠多智能体和 MCP。这样出问题时能快速定位是哪一层的问题，而不是一锅乱炖。
3. 可复制配置：opencode.json 与 MCP 服务注册
这一节是核心，直接给可复制的配置片段。Windows 下配置文件路径是~\.config\opencode\opencode.json，其他系统在对应的用户配置目录下。下面这份骨架里，<你的APIKey>占位符一共出现 4 处，替换成你自己的 Key 即可。注意 Base URL、Key、Model ID 这三件套要写全，缺一个都会导致调用失败。
{ "$schema": "https://opencode.ai/config.json", "model": "zai-coding-plan/glm-5.3", "plugin": ["opencode-antigravity-auth@latest", "oh-my-opencode@3.17.5"], "mcp": { "web-reader": { "type": "remote", "url": "https://open.bigmodel.cn/api/mcp/web_reader/mcp", "headers": { "Authorization": "Bearer <你的APIKey>" } }, "web-search-prime": { "type": "remote", "url": "https://open.bigmodel.cn/api/mcp/web_search_prime/mcp", "headers": { "Authorization": "Bearer <你的APIKey>" } }, "zread-repo": { "type": "remote", "url": "https://open.bigmodel.cn/api/mcp/zread/mcp", "headers": { "Authorization": "Bearer <你的APIKey>" } }, "zai-4.6V-mcp-server": { "type": "local", "command": ["npx", "-y", "@z_ai/mcp-server"], "environment": { "Z_AI_API_KEY": "<你的APIKey>", "Z_AI_MODE": "ZHIPU" } } } }配置里有几个关键点要解释。plugin数组里的插件不需要手动 npm install，OpenCode 首次启动会自动下载。MCP 分两种类型：remote是远程服务，只需要填 URL 和鉴权头；local是本地进程，需要本机有对应的运行环境，比如 Node 或 uv。如果你不用 Google 模型，可以删掉 provider 配置块，不影响其他功能。
各 MCP 服务的作用对照如下，方便你按需取舍：
| MCP 服务 | 类型 | 作用 |
|---|---|---|
| web-reader | remote | 读取指定 URL 的网页内容 |
| web-search-prime | remote | 联网搜索 |
| zread-repo | remote | 阅读 GitHub 仓库结构与代码 |
| zai-4.6V-mcp-server | local | 基于多模态模型的图像 / PDF 理解 |
| lanhu | local | 读取蓝湖设计稿（可选） |
如果你需要蓝湖 MCP，先装 uv，再装蓝湖服务，然后在mcp里追加一段。注意command里的 python 路径包含用户名，要改成自己机器上的实际路径；蓝湖 Cookie 会过期，失效后从浏览器开发者工具的请求头里重新复制完整值替换。
"lanhu": { "enabled": true, "type": "local", "command": ["C:\\Users\\<你的用户名>\\AppData\\Roaming\\uv\\tools\\lanhu-mcp-server\\Scripts\\python.exe", "-m", "lanhu_mcp_server"], "environment": { "MCP_TRANSPORT": "stdio", "LANHU_COOKIE": "<你的蓝湖Cookie>" } }多智能体的配置单独放在~\.config\opencode\oh-my-openagent.json。每个智能体的模型和思考强度通过variant控制，取值有 medium / high / max / xhigh。我的分配策略是多数智能体统一用默认模型，视觉智能体用多模态模型，重要角色分配 max 强度。下面列出三个关键角色，其余按同样格式补全：
{ "agents": { "sisyphus": { "model": "zai-coding-plan/glm-5.3", "variant": "max" }, "oracle": { "model": "zai-coding-plan/glm-5.3", "variant": "high" }, "multimodal-looker": { "model": "zai-coding-plan/glm-4.6v", "variant": "medium" } } }技能包的本质是一个包含SKILL.md文件的目录，放进指定位置就生效，不需要注册。我配了两层：全局技能放在~\.config\opencode\skills\，工程技能放在~\.agents\skills\。目录结构必须是skills\<技能名>\SKILL.md，改完重启 OpenCode 才生效。技能目录不含密钥，可以直接打包迁移：
Compress-Archive -Path "$env:USERPROFILE\.config\opencode\skills" -DestinationPath "D:\opencode-skills.zip" Compress-Archive -Path "$env:USERPROFILE\.agents\skills" -DestinationPath "D:\agents-skills.zip"4. 验证请求：多智能体调用与 MCP 连通性检查
配置写完不代表跑通，必须逐项验证。启动 OpenCode 后，按下面的清单一项项过，每项都对应一个具体的触发动作和预期结果。这套验证动作能帮你快速定位是哪一层没生效。
第一项，主模型验证。直接问一个普通问题，看默认模型是否正常回答。如果这里就报错，说明登录或模型配置有问题，先解决这一层再往下。
第二项，联网搜索。输入「搜一下 xxx 最新消息」，预期触发web-search-prime。如果模型回答里带了实时信息，说明远程 MCP 连通正常。
第三项，视觉理解。发送一张截图，预期触发zai-4.6V-mcp-server。这个走的是本地进程，如果没反应，先在终端手动执行npx -y @z_ai/mcp-server，确认本地环境能拉起服务。
第四项，网页读取。输入「读一下这个网页 https://...」，预期触发web-reader。远程 MCP 失败多数是 Key 填错，检查Authorization头里的 Bearer 值。
第五项，设计稿读取（可选）。发送一个蓝湖链接，预期触发lanhu。如果失败，先uv tool list确认蓝湖服务装好了，再检查 Cookie 是否过期。
第六项，技能列表。输入/，看能否看到已安装的技能列表。看不到说明目录结构不对，或者没重启。
多智能体的验证稍微不同，它不是靠单个命令触发，而是看任务分派是否合理。你可以给一个稍复杂的任务，比如「帮我审查这段代码并给出重构建议」，观察是否触发了检索和评审角色。如果所有任务都堆在主编排上，说明oh-my-openagent.json里的角色配置没生效，检查文件路径和 JSON 格式。
验证过程中，建议开一个终端窗口专门看 OpenCode 的日志输出，MCP 的连接状态、工具调用记录都会打出来。这样出问题时不用猜，直接看日志里哪一步断了。全部通过，说明环境搭建完成，可以进入日常使用。
5. 常见报错排查：401、local proxy failed 与技能不生效
配置过程中最容易撞上的几类报错，我按真实错误信息整理一下排查思路。这些报错在 MCP 接入场景里非常典型，对照着看能省不少时间。
401 Unauthorized。这是最常见的鉴权错误，出现在远程 MCP 调用时。原因通常是 API Key 填错、Key 过期，或者Authorization头的格式不对。排查动作：先确认 Key 没有多余空格，Bearer 后面有一个空格；再确认这个 Key 在控制台里还有效；如果用的是统一 Key 接入，确认 Base URL 和 Key 是配套的。改完配置记得重启 OpenCode。
local proxy failed。这个报错一般出现在本地 MCP 启动时，说明 OpenCode 拉不起本地进程。排查动作：先在终端手动执行对应的启动命令，比如npx -y @z_ai/mcp-server，看能不能正常跑。如果手动也失败，是本地环境问题，检查 Node 版本或依赖是否装全。如果手动能跑但 OpenCode 里失败，检查command路径是否写对，尤其是 Windows 下的反斜杠转义。
reading choices 相关报错。这类报错通常和模型返回格式有关，出现在模型调用层。排查动作：确认 Model ID 写对了，没有拼写错误；确认这个模型在你的账号权限范围内；如果是多模态任务，确认用的是支持视觉的模型，别拿纯文本模型去处理图片。
OAuth 相关报错。如果你用了需要 OAuth 的插件，登录态失效会报这个。排查动作：重新执行opencode auth login，走一遍授权流程。注意~\.local\share\opencode\auth.json是登录凭据文件，不要手动编辑，也不要分享出去。
技能不生效。这个不算报错，但很常见。排查动作：确认目录结构是skills\<技能名>\SKILL.md，文件名大小写要对；确认修改后重启了 OpenCode；确认技能目录放对了位置，全局和工程两层路径不同。
模型列表里找不到目标模型。排查动作：确认登录时选对了 Coding Plan；执行npm update -g opencode-ai升级版本；如果还不行，检查配置文件里的model字段拼写。
排查的核心思路是分层定位：先确认主程序本身正常，再确认模型调用正常，最后确认 MCP 和技能层。不要一上来就改配置，先用最小可复现的动作确认问题出在哪一层。日志是你的朋友，出问题时先看日志再动手。
6. 长期使用建议与接入入口
环境跑通之后，日常使用还有几个习惯值得养成。第一，配置即代码，把opencode.json和oh-my-openagent.json纳入版本管理，但记得用占位符，别把真实 Key 提交上去。第二，技能包按项目沉淀，工程相关的规范放工程目录，通用的放全局目录，迁移时只打包 skills 目录，不要打包整个配置目录，因为里面可能含凭据。第三，Key 疑似泄露时立即在控制台作废重建，蓝湖 Cookie 泄露则退出所有会话。
如果你还没开始配，建议的路径是：先装主程序加一个远程 MCP，跑通最小链路，再逐步加多智能体和技能包。这样每一步都有反馈，出问题也好定位。统一 Key 接入的好处在这里体现得很明显——模型调用和 MCP 鉴权共用一套凭据，迁移和轮换都省事。
需要进一步操作的话，可以走这几个入口：配置 API Key 和查看接入文档，去 https://taotoken.net/api-keys 和 https://taotoken.net/doc ；想先验证模型效果，用模型对话 https://taotoken.net/chat ；如果是长期编码或跑 Agent 任务，看 Coding Plan https://taotoken.net/coding-plan 。控制台在 https://taotoken.net/console ，API 入口是 https://taotoken.net/api 。这些链接都带了归因参数，方便你直接跳转。
最后说一个实用技巧：多智能体的variant强度不要全开 max，token 消耗会明显上升。我的做法是主编排和规划角色用 max，检索和评审用 high，视觉用 medium，日常小任务走 quick 档位。这样在保证质量的同时，成本可控。技能包也一样，不是越多越好，挑真正约束生成风格的几个装上，比堆一堆用不上的更有效。
