)
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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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-authlatest, oh-my-opencode3.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 installOpenCode 首次启动会自动下载。MCP 分两种类型remote是远程服务只需要填 URL 和鉴权头local是本地进程需要本机有对应的运行环境比如 Node 或 uv。如果你不用 Google 模型可以删掉 provider 配置块不影响其他功能。各 MCP 服务的作用对照如下方便你按需取舍MCP 服务类型作用web-readerremote读取指定 URL 的网页内容web-search-primeremote联网搜索zread-reporemote阅读 GitHub 仓库结构与代码zai-4.6V-mcp-serverlocal基于多模态模型的图像 / PDF 理解lanhulocal读取蓝湖设计稿可选如果你需要蓝湖 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.zip4. 验证请求多智能体调用与 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强度不要全开 maxtoken 消耗会明显上升。我的做法是主编排和规划角色用 max检索和评审用 high视觉用 medium日常小任务走 quick 档位。这样在保证质量的同时成本可控。技能包也一样不是越多越好挑真正约束生成风格的几个装上比堆一堆用不上的更有效。