OpenCode 故障排查手册

在使用 OpenCode 的过程中，偶尔会遇到启动失败、连接不上服务器、模型报错等意外状况。这篇文章汇总了常见的排查步骤和解决方法，按照从简单到深入的顺序整理，方便按图索骥地定位问题。文中出现的所有路径和命令都已按操作系统区分，照做即可。

---

日志文件

OpenCode 会把运行日志写入本地磁盘，出现问题时首先查看日志往往能直接找到原因。

日志存放位置：

• macOS / Linux ：~/.local/share/opencode/log/
• Windows ：按下 WIN+R，粘贴 %USERPROFILE%\.local\share\opencode\log 并回车

日志文件以时间戳命名，例如 2025-01-09T123456.log，最近 10 个日志文件会被保留。

如果需要更详细的调试信息，启动时可以加上 --log-level 参数。比如：

opencode --log-level DEBUG

这样会输出 DEBUG 级别的日志，信息更加详尽。

---

存储目录

OpenCode 在磁盘上保存了会话数据和应用数据，目录位于：

• macOS / Linux ：~/.local/share/opencode/
• Windows ：按下 WIN+R，粘贴 %USERPROFILE%\.local\share\opencode 并回车

该目录下包含：

• auth.json ------ 认证数据，如 API 密钥、OAuth 令牌
• log/ ------ 应用日志
• project/ ------ 项目专属数据，例如会话和消息记录如果项目处于 Git 仓库中，数据会存放在 ./<project-slug>/storage/ 下；如果不是 Git 仓库，则存放在 ./global/storage/ 下。

---

桌面版应用排查

OpenCode 桌面版在后台运行一个本地 OpenCode 服务器（也就是 opencode-cli 边车）。大多数问题都由异常插件、损坏的缓存或错误的服务器设置引起。

快速检查

• 完全退出应用，然后重新启动。
• 如果应用显示了错误界面，点击 Restart 并将错误详情复制下来。
• 仅 macOS ：点击菜单栏的 OpenCode → Reload Webview（适用于界面空白或卡死的情况）。

禁用插件

若桌面应用在启动时崩溃、卡住或行为异常，第一步就是尝试禁用插件。

检查全局配置

打开全局配置文件，查找 plugin 字段。

• macOS / Linux ：~/.config/opencode/opencode.jsonc（或 ~/.config/opencode/opencode.json）
• macOS / Linux（较早版本安装） ：~/.local/share/opencode/opencode.jsonc
• Windows ：按下 WIN+R，粘贴 %USERPROFILE%\.config\opencode\opencode.jsonc 并回车

如果文件中配置了插件，可以暂时移除 plugin 键，或将其设为空数组：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

保存后重启应用。

检查插件目录

OpenCode 还会从本地磁盘加载插件。临时将这些目录移走（或重命名文件夹），然后重启桌面应用：

• 全局插件
  • macOS / Linux：~/.config/opencode/plugins/
  • Windows：WIN+R 后输入 %USERPROFILE%\.config\opencode\plugins
• 项目插件 （仅限使用了项目级配置的情况）
  • <项目目录>/.opencode/plugins/

如果应用恢复正常，再逐个将插件移回原位，每恢复一个就重启一次，以定位是哪个插件引起的故障。

清理缓存

如果禁用插件无效，或者某个插件的安装卡住了，可以清空缓存，让 OpenCode 重新构建。

1. 完全退出 OpenCode 桌面版。
2. 删除缓存目录：
   • macOS ：打开访达，按下 Cmd+Shift+G，粘贴 ~/.cache/opencode 并删除。
   • Linux ：删除 ~/.cache/opencode（可执行 rm -rf ~/.cache/opencode）。
   • Windows ：按下 WIN+R，粘贴 %USERPROFILE%\.cache\opencode 并删除。
3. 重新启动 OpenCode 桌面版。

修复服务器连接问题

OpenCode 桌面版可以启动自己的本地服务器（默认行为），也可以连接用户配置的服务器 URL。如果看到"Connection Failed"对话框，或者应用一直停留在启动画面，就需要检查自定义服务器 URL 是否存在。

清除桌面默认服务器 URL

在主屏幕中，点击带有状态指示圆点的服务器名称，打开服务器选择器。在 Default server 部分，点击 Clear。

从配置中移除 server.port / server.hostname

打开 opencode.json(c) 配置文件，如果其中有类似下面的 server 段落，暂时将其整个删除，然后重启桌面应用。

检查环境变量

如果系统中设置了 OPENCODE_PORT 环境变量，桌面应用会尝试使用该端口作为本地服务器端口。可以取消设置 OPENCODE_PORT（或换成一个空闲端口），然后重启应用。

Linux：Wayland / X11 问题

在 Linux 上，某些 Wayland 环境可能导致窗口空白或合成器错误。

• 如果正使用 Wayland 且应用空白或崩溃，可以尝试用 OC_ALLOW_WAYLAND=1 启动。
• 如果这样反而更糟，就移除该变量，改用 X11 会话启动。

Windows：WebView2 运行时

Windows 上的 OpenCode 桌面版依赖 Microsoft Edge WebView2 Runtime。如果应用打开时只显示空白窗口，或根本无法启动，请安装或更新 WebView2 运行时，然后重试。

Windows：通用性能问题

如果在 Windows 上遇到运行缓慢、文件访问异常或终端问题，可以尝试使用 WSL（Windows Subsystem for Linux）。WSL 提供的 Linux 环境与 OpenCode 的各功能配合得更为顺畅。

通知不显示

OpenCode 桌面版只在同时满足两个条件时才会弹出系统通知：

• 操作系统设置中已经为 OpenCode 开启了通知权限；
• 应用窗口当前未被聚焦。

重置桌面应用存储（最后的手段）

如果应用完全无法启动，且无法在界面内清除设置，可以直接重置桌面应用的持久状态。

1. 完全退出 OpenCode 桌面版。
2. 找到并删除以下文件（它们位于桌面应用的数据目录内）：
   • opencode.settings.dat ------ 桌面默认服务器 URL
   • opencode.global.dat 与 opencode.workspace.*.dat ------ 最近使用的服务器、项目等 UI 状态
3. 各操作系统快速定位该目录的方法：
   • macOS ：访达中按 Cmd+Shift+G，前往 ~/Library/Application Support，然后搜索上述文件名。
   • Linux ：在 ~/.local/share 下搜索上述文件名。
   • Windows ：按下 WIN+R，输入 %APPDATA% 回车，然后搜索上述文件名。

删除后重新启动应用即可恢复初始状态。

---

获取帮助

如果自行排查后问题依旧，可以通过以下渠道获取支持。

在 GitHub 上报错

提交 bug 或功能请求的最佳途径是 OpenCode 的 GitHub 仓库：

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

在创建新 issue 之前，建议先搜索一下，看看是否已有相同问题被报告。

加入 Discord

如需实时帮助和社区讨论，可以加入 Discord 服务器：

https://opencode.ai/discord

---

常见问题场景

下面列举了一些反复出现的典型问题及对应解决办法。

OpenCode 无法启动

• 查看日志文件中的错误信息。
• 尝试以 --print-logs 参数运行，直接在终端看到输出。
• 通过 opencode upgrade 确保已安装最新版本。

认证问题

• 在 TUI 中使用 /connect 命令重新认证。
• 检查 API 密钥是否有效。
• 确认网络环境允许连接到相应服务提供商的 API。

模型不可用

• 检查是否已对相应提供商完成认证。
• 验证配置文件中的模型名称是否正确。
• 某些模型需要特定的访问权限或订阅。
• 如果遇到 ProviderModelNotFoundError，很可能是引用了不正确的模型名称。模型引用格式应为：<providerId>/<modelId>。例如：
  • openai/gpt-4.1
  • openrouter/google/gemini-2.5-flash
  • opencode/kimi-k2
• 若要查看当前可访问的模型列表，执行：

opencode models

ProviderInitError

遇到 ProviderInitError 通常意味着配置无效或已损坏。解决方法如下：

1. 先按照 providers 指南确认服务提供商的设置是否正确。
2. 如果问题依旧，清空存储的配置：

rm -rf ~/.local/share/opencode

Windows 系统上，按 WIN+R 后输入并删除 %USERPROFILE%\.local\share\opencode。

3. 在 TUI 中使用 /connect 命令重新认证。

AI_APICallError 与提供程序包问题

API 调用错误有时是由过期的提供程序包引起的。OpenCode 会根据需要动态安装各提供程序包（OpenAI、Anthropic、Google 等），并将它们缓存到本地。

解决步骤：

1. 清除提供程序包缓存：

rm -rf ~/.cache/opencode

Windows：按下 WIN+R，粘贴 %USERPROFILE%\.cache\opencode 并删除。

2. 重启 OpenCode，它会重新下载最新版本的提供程序包。这往往能解决因模型参数或 API 变更导致的兼容性问题。

Linux 上复制/粘贴失效

Linux 用户需要安装剪贴板工具，复制粘贴功能才能正常工作：

• X11 系统：

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

• Wayland 系统：

apt install -y wl-clipboard

• 无图形界面（headless）环境：

apt install -y xvfb
# 然后运行：
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

OpenCode 会自动检测是否处于 Wayland 环境，并优先使用 wl-clipboard；否则会按 xclip、xsel 的顺序尝试寻找可用的剪贴板工具。

---

以上便是 OpenCode 故障排查的完整流程。只要顺着日志、插件、缓存、服务器连接这条线索逐步检查，绝大多数问题都能迎刃而解。如果还有难以解决的状况，不妨到 GitHub 或 Discord 找社区一起诊断。