OpenCode 装好之后，真正让人挠头的不是它会不会写代码，而是它偶尔一声不吭地甩给你一行报错，然后什么都不干。

前面几篇我把它的源码、装法、和别家怎么做对比都写过了。这一篇补上最后一块：报错。素材分两半，一半来自官方 troubleshooting 页，一半是我自己踩过的、以及在 GitHub issues 里翻到的真实案例。我按「症状 → 原因 → 修复」理一遍，目标是让你下次看到那几行英文的时候，不用再去翻帖子。

先把最常见的几个症状摆出来：

• opencode: command not found——明明装成功了
• 一启动就崩：Failed to initialize OpenTUI render library（终端 UI 的原生渲染库加载失败）
• ProviderModelNotFoundError——模型名格式或来源不对
• ProviderInitError——配置 / 凭证像坏掉了
• AI_APICallError 或 Failed to fetch models.dev——调用、拉取模型列表时报错
• 桌面版弹 Connection Failed，或者一直卡在启动画面
• Linux 上复制粘贴没反应

如果你还没装上，先看 《OpenCode 安装完全指南：从一行 curl 到 v2 共享服务，附 v1 迁移！》；想先搞清楚它内部在跑什么，看 《OpenCode 源码深度拆解：Effect TS 代数效应系统构建的智能编码 Agent》。

先记一条铁律：v1 和 v2 别混

排错前先确认你在哪条版本线上。这是最容易把人绕晕的一件事，因为两套文档、两个包名、两套服务模型是同名的。

一个很典型的场景：你在搜到一篇讲 opencode-ai 的帖子，照着它的办法清 ~/.local/share/opencode，结果发现自己装的是 v2，服务还挂着，清了也没用。先跑 opencode --version。 看版本号是 1.x 还是 2.x，再去对应的文档里找答案。这篇默认讲 v2，遇到 v1 单独标出来。

装完找不到命令：先别急着重装

最气人的一种失败——安装命令回了个「成功」，一敲 opencode 却是 command not found。原因通常有两个。

一是 PATH 没刷新。 用官方脚本或 brew 装完，当前这个终端进程还拿着老的 PATH。重开一个终端再试，八成就好了。如果你当时用了 --no-modify-path（比如给 Ansible、Nix 托管环境用），那得你自己把二进制目录加进 PATH。

二是 Bun / pnpm 把 postinstall 拦了。 这个是 npm 包装法的经典坑：@opencode/cli 靠一个 postinstall 脚本去挑对应平台的原生二进制，而 Bun 和 pnpm 默认会拦掉生命周期脚本。结果就是包「装上了」，真正的二进制没落下来，opencode 一跑就找不到文件。

修复办法是重装时显式放行：

# Bun
bun install -g --trust @opencode/cli

# pnpm
pnpm add -g --allow-build=@opencode/cli @opencode/cli

yarn、Vite+（vp install -g @opencode/cli）、npm 不需要额外参数。装完先确认一下：

which opencode
opencode --version

一启动就崩：OpenTUI render library

如果你看到的是这一行，说明程序进了启动阶段，但终端 UI 的原生渲染库没能加载：

ERROR service=default e=Failed to initialize OpenTUI render library:
Failed to open library "…/opentui-xxxx.dll": error code 126

这是 v1.0 之后 OpenCode 改用 OpenTUI 渲染 TUI 后引入的一类问题，GitHub 上有好几个变体。分平台看：

Linux（很隐蔽的一种）：/tmp 被挂成了 noexec。 OpenCode 会往临时目录里解压并加载 .so，如果 /tmp 禁止执行，库加载就会失败。查一下：

mount | grep /tmp        # 看有没有 noexec

有的话，把临时目录指到一个允许执行的路径，或者让运维去掉 noexec：

export TMPDIR=/var/tmp    # 或者你项目下任意可执行的目录

Windows：DLL 打不开（error code 126）。 这种多半是安装包损坏或杀软拦截了动态库。重新下一次独立二进制，或者换个版本装。顺便说一句，v2 在 Windows 上没有包管理器配方——别去翻 Chocolatey / Scoop / Winget，装独立二进制或者干脆进 WSL。

不管哪个平台，第一步都该是让错误打在终端上，而不是只写进日志：

opencode --print-logs
opencode --log-level DEBUG

--print-logs 会把日志同时输出到终端，比事后去翻日志文件快得多。

模型找不到：ProviderModelNotFoundError

报错长这样：

ProviderModelNotFoundError

意思只有一句：你引用了一个不存在（或名字写错）的模型。 两个检查点。

第一，格式必须是 <providerId>/<modelId>。官方给的例子：

openai/gpt-4.1
openrouter/google/gemini-2.5-flash
opencode/kimi-k2

注意 OpenRouter 这种中间商是两段斜杠：provider 是 openrouter，后面跟的是上游的 google/gemini-2.5-flash。手填很容易漏一段。

第二，就算 provider 那边确实有这个模型，OpenCode 也可能不认。因为它依赖 models.dev 维护的模型清单，清单里没有的模型，即使 OpenRouter 自己接受，也会报 ProviderModelNotFoundError（GitHub issue #916 就是这个情况——mistralai/mixtral-8x7b-instruct 不在 models.dev 的 openrouter 列表里）。

所以正确姿势是先让它把可用模型列出来，照抄名字：

opencode models              # 列出所有模型，格式 provider/model
opencode models anthropic    # 只看某一家
opencode models --refresh    # 强制刷新模型缓存

如果模型确实存在但列表里没有，那就是 models.dev 还没收录——换一个等价模型，或者等清单更新，别跟报错死磕。

ProviderInitError：配置或凭证坏了

ProviderInitError

官方对它的定性很直接：你的 provider 配置无效或已损坏。 排查分两步。

先按 provider 文档核对一遍配置对不对（baseURL、API Key、模型白名单这些）。如果配置看着没问题还是报错，就轮到「清掉本地存储重来」这一步：

rm -rf ~/.local/share/opencode

⚠️ 动手前想清楚：这个目录里除了损坏的配置，还有 auth.json（你的 API Key、OAuth token）和 project/（会话与消息历史）。删了会话就没了。 稳妥的做法是先备份，或者只想修凭证的话，单独处理 auth.json 再跑一次 /connect。

清完重启，在 TUI 里重新连一次：

/connect

AI_APICallError 和 Failed to fetch models.dev

这两个都属于「能启动、能进界面，但一调用就出问题」。

AI_APICallError，或者模型参数相关的报错，多数是 provider 包版本旧了。OpenCode 是按需动态下载 provider 包并本地缓存的，旧缓存在 provider 改了接口之后就会对不上。清缓存让它重拉：

rm -rf ~/.cache/opencode

重启后它会重新装最新一版 provider 包，兼容性问题通常就此消失。

Failed to fetch models.dev 是另一回事——它连不上模型清单这个源。常见于离线网络或公司内网（GitHub issue #10766 就是内网环境报的）。这时候清缓存没用，要在网络层解决：走代理，或者在企业版里配好离线的模型清单来源。判断方法很简单，看这台机器能不能直连外网；不能，就是这个问题。

注意别把 ~/.cache/opencode（provider 包缓存）和 ~/.local/share/opencode（配置、凭证、会话）搞混——前者删了无损，后者删了丢数据。

桌面版连不上：Connection Failed

桌面版和 CLI 共用同一个后台服务，所以它有自己专属的一类故障：弹出 Connection Failed，或者永远卡在启动画面。 根因通常是桌面端被指到了一个连不上的服务地址。按顺序排：

1. 清掉桌面端记的服务器 URL。 在 Home 页点那个带状态点的服务名，打开 Server picker，在 Default server 一栏点 Clear。
2. 把配置里的 server 段摘掉。 如果你的 opencode.json(c) 里有 server.port / server.hostname，先临时删掉再重启。
3. 检查 OPENCODE_PORT 环境变量。 设了这个变量，桌面端会拿它当本地服务端口；端口被占或不通就起不来。unset 掉或换一个空闲端口。

macOS 还有个界面层面的小技巧：菜单里的 Reload Webview，界面空白或卡住时先点它，比重启整个 App 快。

Linux 复制粘贴失灵 / 无头环境

在 Linux 上选中文字、按复制没反应，多半不是 OpenCode 的问题，而是系统根本没装剪贴板工具。官方要求按会话类型装：

# X11
apt install -y xclip
# 或
apt install -y xsel

# Wayland
apt install -y wl-clipboard

OpenCode 会检测你是不是在用 Wayland，是就优先用 wl-clipboard，否则按 xclip、xsel 的顺序找。

**无头环境（CI、容器、SSH）**连显示都没有，得先起一个虚拟显示：

apt install -y xvfb
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

v2 独有的坑：共享后台服务卡住

v2 把会话、权限、工具执行都收归一个共享后台服务管，好处是多客户端（TUI / 桌面 / Web / Docker）能接同一份状态。代价是：服务一旦卡住，所有客户端一起遭殃，表现还挺像「程序坏了」。

先看状态，再考虑重启：

opencode service status
opencode service restart      # 卡住就重启

临时想绕开共享服务、让这个终端用一份干净的服务，加 --standalone：

opencode --standalone

不想让它默认起共享服务，可以显式关掉：

opencode service set disabled true

但记住两点：关掉之后 Web 端的 opencode pair 就不能用了（它依赖共享服务）；--server 和手动 opencode service start 仍然可用。

⚠️ 排错时不要手贱去删或改 ~/.local/state/opencode/service.json、~/.config/opencode/service.json，也别去动 ~/.local/share/opencode/opencode.db。这些是服务的注册信息和会话数据库，乱动只会把好好的会话搞坏。要清就整个用 opencode uninstall 走正规流程。

三个平台的差异

同一行报错，在不同系统上的含义可能完全不一样。记一张表比死记命令有用：

Linux 桌面版在 Wayland 下窗口空白或 compositor 报错时，可以试：

OC_ALLOW_WAYLAND=1 opencode

如果这样反而更糟，就摘掉这个变量，改用 X11 会话启动。

不要踩的坑

一张清单，都是我在上面各节里踩过、或看到别人反复踩的：

• 别同时装多条安装路径。 curl、brew、npm 各往 PATH 里塞一个叫 opencode 的二进制，混装之后你根本不知道跑的是哪个。
• 别把 v1 的报错当 v2 解。 包名、服务模型都变了，opencode-ai 时代的经验经常不适用。
• 别删 service.json / opencode.db。 那是服务的注册与会话数据，不是缓存。
• 别把 ~/.local/share/opencode 当缓存删。 它含凭证和会话，清之前一定备份。
• 别信第三方对比博客里的命令。 它们的版本号和包名常年过时，命令一律以 opencode.ai 官方文档和 registry.npmjs.org 为准。
• 别在 Windows 上找包管理器配方。 v2 明确没有 Chocolatey / Scoop / Winget。

修好之后怎么验证

链接通了、模型能列出来了，用这几条确认整条链路是活的：

opencode --version                 # 装的是哪个版本
opencode service status            # 共享服务在不在
opencode models | head             # 能不能列出模型
opencode run "只回一句话：pong"     # 真打一次模型

最后一条 opencode run 最关键——它绕开 TUI，直接跑一次真实的模型调用，能一次区分「界面渲染问题」和「后端调用问题」。如果你的问题是前者，它会正常返回；是后者，报错会直接打在终端上。

需要看细节时，日志在 ~/.local/share/opencode/log/（最近留 10 个文件）。v2 的日志每行都带 run= 和 role= 字段，只看服务侧：

grep 'role=server' ~/.local/share/opencode/log/opencode.log | tail -50

FAQ

Q：日志到底在哪？怎么开详细日志？ A：macOS/Linux 是 ~/.local/share/opencode/log/；Windows 按 WIN+R 填 %USERPROFILE%\.local\share\opencode\log。想更细就加 --log-level DEBUG，想直接打在终端就加 --print-logs。

Q：ProviderInitError 清了存储，我的会话还在吗？ A：不在。~/.local/share/opencode 里既有损坏配置也有 auth.json 和会话数据，rm -rf 是一锅端。要保会话就只处理凭证，别整目录删。

Q：为什么模型 provider 明明有，OpenCode 却说找不到？ A：它靠 models.dev 的清单，清单没收录就没法引用（issue #916）。用 opencode models 看实际有哪些，照抄名字最保险。

Q：卸载想保留配置和会话怎么办？ A：先预览再执行，要留就加参数：

opencode uninstall --dry-run
opencode uninstall --keep-config --keep-data

Q：桌面版和 CLI 能同时用吗？ A：能，它们连的是同一个共享后台服务——这也正是「CLI 好好的、桌面版却 Connection Failed」的原因：问题不在服务本身，在桌面端配的地址。

Q：新项目到底该装 v1 还是 v2？ A：新装一律 v2。还在跑 v1 且依赖某个 v1 插件的话，先在隔离环境验证插件在 v2 上能跑，再换生产机器。

Q：这机器连不上外网，OpenCode 还能用吗？ A：能用，但走的是内部模型 API 的话，Failed to fetch models.dev 会跟着你——要么走代理，要么在企业版里配离线清单。

写在最后

把 OpenCode 这一路用下来，我的感受是：它的报错其实并不算多，就是面铺得广——原生渲染、动态 provider 包、共享服务、多客户端，每一层都能单独出问题。所以排错的关键不是背命令，而是先定位你卡在哪一层：是启动阶段（OpenTUI / 配置），是模型层（ProviderModelNotFoundError / AI_APICallError），还是连接层（共享服务 / 桌面端地址）。

先看 opencode --print-logs 把错误打到眼前，再对着这张表往下走，大部分问题三步之内能修好。

（相关阅读：本系列已经写完的三篇——《OpenCode 源码深度拆解：Effect TS 代数效应系统构建的智能编码 Agent》、《OpenCode 安装完全指南：从一行 curl 到 v2 共享服务，附 v1 迁移！》、《OpenCode vs Claude Code vs Cursor：三种 Coding Agent 哲学，你该把方向盘交给谁！》。如果你偏爱「状态码速查表」那种写法，可以对照 《Jev 报错排查完全指南：401、422、429、529 一次讲透！》。）

GitHub: https://github.com/anomalyco/opencode