问题描述：

OpenCode + oh-my-opencode（已改名oh-my-openagent） 踩坑实录

前言

一直在用cladue code+glm系列模型 & 中转站的opus ，平时claude老是需要确认命令太烦了。试了OpenCode之后发现OpenCode在解决问题、调用agent的时候更积极，感觉更适合glm-5.1。于是打算在家里和公司的电脑（都是Windows）配置OpenCode+ oh-my-openagent组合拳。途中遇到很多问题，现在整理出来，希望对各位佬友有参考作用。

配置好OpenCode之后尽量不要随便升级，这玩意奇奇怪怪的bug太多了。有问题可以第一时间让它自己看日志

正文

OpenCode + oh-my-openagent 排障速查手册

遇到问题？Ctrl+F 搜报错关键词，直接跳到解决方案。适用于 macOS / Linux / Windows，不限 provider。

路径约定：~ = 用户主目录（macOS: /Users/<你>，Linux: /home/<你>，Windows: C:\Users\<你>）。

---

问题速查

报错关键词	章节
fetch() proxy.url must be a non-empty string	1. VPN 代理致插件安装失败
/agents 只看到 plan 和 build	1、2
oh-my-opencode vs oh-my-openagent	2. 包名已更名
缓存版本不一致	3. 两套缓存冲突
Model not found: opencode/<model>	4. 模型缺 provider 前缀
Invalid model format	4. 同上
Prometheus Unknown agent 但列表里有	5. 不可见 Unicode 字符
Loaded plugin version mismatch	6. 版本缓存不匹配
启动黑屏卡住 30+ 秒	7. 版本不一致触发重装

---

1. VPN 代理导致插件安装失败

报错：fetch() proxy.url must be a non-empty string

原因：OpenCode 的 fetch 对 HTTP_PROXY 处理有 bug，VPN 代理会阻断插件下载。

解决：启动前清掉代理，装完一次后会被缓存，之后不用再清。

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY && opencode

$env:HTTP_PROXY=""; $env:HTTPS_PROXY=""; $env:ALL_PROXY=""; opencode

---

2. 插件包名已更名

现象：配置里写的 oh-my-opencode，插件能装但可能警告或无法迁移。

解决：opencode.json 中改用新名：

{ "plugin": ["oh-my-openagent"] }

同时检查 ~/.config/opencode/package.json 的 dependencies 也指向 oh-my-openagent。

---

3. 两套缓存目录版本冲突

现象：装了新版本但行为异常，或 oh-my-opencode doctor 报版本不匹配。

原因：两套缓存独立维护版本：

目录	用途
~/.config/opencode/node_modules/	主缓存
~/.cache/opencode/node_modules/	辅助缓存

解决：删掉主缓存重装，两处版本会自动同步。

rm -rf ~/.config/opencode/node_modules/oh-my-openagent cd ~/.config/opencode && npm install oh-my-openagent

Remove-Item -Path "$HOME\.config\opencode\node_modules\oh-my-openagent" -Recurse -Force cd "$HOME\.config\opencode"; npm install oh-my-openagent

---

4. 模型名缺少 provider 前缀

报错：Model not found: opencode/<model> 或 Invalid model format "<model>"

你配置写的是裸名（如 my-model），但系统要求 provider/model 格式。裸名匹配失败后走内置 fallback chain，拼出完全不相关的模型名，报错。

解决：编辑 ~/.config/opencode/oh-my-opencode.json，所有 model 加上 provider/ 前缀：

{ "agents": { "oracle": { "model": "<your-provider>/<your-model>" }, "metis": { "model": "<your-provider>/<your-model>" }, "momus": { "model": "<your-provider>/<your-model>" }, "explore": { "model": "<your-provider>/<your-small-model>" }, "prometheus": { "model": "<your-provider>/<your-model>" } }, "categories": { "quick": { "model": "<your-provider>/<your-small-model>" }, "deep": { "model": "<your-provider>/<your-model>" } } }

把 <your-provider> 替换为你在 opencode.json 中配置的 provider 名。如有 .tmp 临时文件也同步改。改完重启。

---

5. Prometheus Agent 不可见 Unicode 字符

现象：调用 Prometheus 报 Unknown agent，但列表里明明有，名字看起来一样。

原因：注册名前缀含零宽度字符（\u200b\u200b\u200b），插件内部 bug。

解决：无法通过配置修复，用 plan 替代：

task(subagent_type="plan", ...) # 替代 Prometheus

---

6. 插件版本缓存不匹配

报错：Loaded plugin version mismatch - Cache expects X but loaded Y

解决：重装统一版本：

cd ~/.config/opencode && npm install oh-my-openagent

cd "$HOME\.config\opencode"; npm install oh-my-openagent

确认版本一致：

grep '"version"' ~/.config/opencode/node_modules/oh-my-openagent/package.json

---

7. 启动黑屏卡住 30+ 秒

现象：opencode 启动后黑屏，日志反复出现 installing package。

原因：Oh-My-OpenCode主包和平台二进制包（如 oh-my-openagent-windows-x64）版本不一致，每次启动都触发重装。（需要指定版本安装3.14的，我是因为主包更新到3.16，但是二进制包只有3.14导致的问题）

解决：同问题 6，重装统一版本。

---

诊断命令速查

命令	用途
opencode agent list --print-logs	最常用。查 agent 列表 + 插件加载日志，直接看到 ERROR
opencode agent list --print-logs --log-level DEBUG	更详细日志
opencode debug config --print-logs	查看已解析配置 + 插件状态
opencode debug agent <name>	查看特定 agent 的配置和模型
oh-my-opencode doctor	插件自带诊断，检查版本和模型兼容性
npm list --depth=0	检查已安装包版本（在 ~/.config/opencode 下执行）

排查顺序：agent list → agent list --print-logs → doctor → debug config

---

经验总结

1. 模型名必须带 provider 前缀：provider/model 格式，裸名会走 fallback chain 导致诡异报错
2. 启动前清代理：VPN 代理有可能会导致插件安装失败，装一次后缓存就不用再清了
3. 两套缓存要同步检查：~/.config/opencode/ 和 ~/.cache/opencode/ 的版本可能不一致
4. 配置改完必须重启：OpenCode 启动时读配置到内存，热修改不生效
5. MCP 用绝对路径：没有 cwd 字段，相对路径大概率找不到文件
6. 遇事不决先跑 doctor：oh-my-opencode doctor 能快速暴露版本和模型问题
7. 看启动日志：让另一个AI去看OpenCode的启动或者调用日志

---

附录：关键目录和文件索引

# OpenCode 配置目录 ~/.config/opencode/ opencode.json # 主配置（provider、model、plugin） oh-my-opencode.json # 插件配置（agent/category 模型映射） package.json # 依赖声明 node_modules/ oh-my-openagent/ # 插件本体 # 辅助缓存目录 ~/.cache/opencode/ package.json # 缓存依赖声明（注意版本一致性） # Skill 目录（存放 mcp.json 的位置） ~/.agents/skills/ # 项目级 skill（优先） ~/.claude/skills/ # 用户级 skill # MCP Server 代码（独立安装） <你选择的安装路径>/ # 自行选择的位置即可

配置文件模板：

opencode.json（主配置）：

{ "$schema": "https://opencode.ai/config.json", "provider": { "<your-provider>": { "options": { "apiKey": "your-api-key" } } }, "model": "<your-provider>/<your-model>", "small_model": "<your-provider>/<your-small-model>", "plugin": ["oh-my-openagent"] }

oh-my-opencode.json（插件配置）：

{ "agents": { "sisyphus": { "model": "<your-provider>/<your-model>" }, "oracle": { "model": "<your-provider>/<your-model>" }, "metis": { "model": "<your-provider>/<your-model>" }, "momus": { "model": "<your-provider>/<your-model>" }, "explore": { "model": "<your-provider>/<your-small-model>" }, "prometheus": { "model": "<your-provider>/<your-model>" }, "librarian": { "model": "<your-provider>/<your-model>" }, "hephaestus": { "model": "<your-provider>/<your-model>" } }, "categories": { "quick": { "model": "<your-provider>/<your-small-model>" }, "deep": { "model": "<your-provider>/<your-model>" }, "unspecified-low": { "model": "<your-provider>/<your-small-model>" }, "unspecified-high": { "model": "<your-provider>/<your-model>" } } }

MCP 配置模板：

Python stdio：

{ "<mcp-name>": { "type": "stdio", "command": "<uv 的绝对路径>", "args": ["run", "--project", "<项目绝对路径>", "python", "<项目绝对路径>/server.py"], "env": {} } }

Node.js stdio：

{ "<mcp-name>": { "type": "stdio", "command": "node", "args": ["<项目绝对路径>/index.js"], "env": {} } }

HTTP 远程：

{ "<mcp-name>": { "type": "http", "url": "https://your-server.example.com/mcp", "headers": { "Authorization": "Bearer <token>" } } }

---

适用于 macOS / Linux / Windows，不限 provider
最后更新：2026-04-11

网友解答：

---

--【壹】--：

bug确实多，刚刚发现上下文压缩compact命令用不了，去GitHub一看，又是一个提了issue的bug

---

--【贰】--：

谢谢佬友，经常就算出现代码行数写错了，模型上下文也没有压缩，总是写错之后我再人工去和它说写错行了。

---

--【叁】--：

感谢佬的分享，个人的经验是所有配置，能让 agent 给你配的，我是一点都不想碰了，尤其 OMO 这种 一大堆 sub-agent 配置，搞不清楚特点的，交给机器去搞明白就得了。

---

--【肆】--：

是文件内行数写错了？还是文件路径错了？文件路径错了在全局记忆加路径规则就好，如果是代码行数经常写错的话可能是模型上下文不够？

---

--【伍】--：

感谢佬友分享教程，我好像插件开得少，每次更新通知出来，我就更新了，运气好还没遇到问题

---

--【陆】--：

是不是服务开着重复了，我的obs也是遇到这样子文件，官方的opencode插件和网友的opencode插件一起开着就会这样子，你尝试用其他本地智能体去解决一下这个服务端口问题。

---

--【柒】--：

我启动之后经常白屏，不知道为什么。让ai修过好了一段时间之后还是出现。后面就没用了

---

--【捌】--：

佬，找到问题了，是配置文件出错了，多了switch和agent

---

--【玖】--：

我用的桌面版本的佬，没有用cli,然后我让Claude排查解决了

---

--【拾】--：

感谢佬的分享，正好最近想折腾omo能用上

---

--【拾壹】--：

opencode-cli进程是不是开两个了，用unlocker等之类的整个文件夹杀一下进程

---

--【拾贰】--：

佬，你们的opencode还能打开吗，我的为什么报错无法连接到 本地服务器

正在自动重试…
image1842×1191 40.9 KB

---

--【拾叁】--：

谢谢佬，这个真实用，opencode很好用但是乱七八糟问题也有点多了

---

--【拾肆】--：

感谢佬友的分享，不知道为什么使用opencode经常出现写入位置出错，不像claude会先阅读一下代码之后再写入，有无什么解决方法。

---

--【拾伍】--：

谢谢佬友，是代码行数写错了，用claudecode倒是没出现这个问题，codex却有编码问题，总的来说用了很多最后选择claude了，然后搭配佬友说的ccswitch切换自己的api

---

--【拾陆】--：

佬试试cc switch或者这个 发行版 AI Toolbox v0.8.0 · coulsontl/ai-toolbox
挺方便的

---

--【拾柒】--：

自从更新了opencode 1.4.0+，改个几行代码要一两个小时，本地服务经常挂掉；特别是修改代码阶段，不停的挂掉，然后过很长时间又重启；我看ohmyopenagent缓存都在～/.cache/opencode/packages下面，其他地方都没有，mac和windows都一致；试过删omo缓存，更新到最新也没什么用！

我发现～/.cache/opencode/node_modules下面也有omo，我删掉后重启没有安装，应该是多余的！～/.cache/opencode/packages下面删掉omo插件每次重启就会重新安装！

---

--【拾捌】--：

如果是路径错了，不妨开始之前先执行一下/init 应该就好很多

cc-switch确实好用，更新以后模型可以选择更好用了，AIToolbox导入newapi的调用方便一点支持插件ALL api hub直接导入