OpenCode 故障排查手册

在使用 OpenCode 的过程中偶尔会遇到启动失败、连接不上服务器、模型报错等意外状况。这篇文章汇总了常见的排查步骤和解决方法按照从简单到深入的顺序整理方便按图索骥地定位问题。文中出现的所有路径和命令都已按操作系统区分照做即可。日志文件OpenCode 会把运行日志写入本地磁盘出现问题时首先查看日志往往能直接找到原因。日志存放位置macOS / Linux~/.local/share/opencode/log/Windows按下WINR粘贴%USERPROFILE%\.local\share\opencode\log并回车日志文件以时间戳命名例如2025-01-09T123456.log最近 10 个日志文件会被保留。如果需要更详细的调试信息启动时可以加上--log-level参数。比如opencode --log-level DEBUG这样会输出 DEBUG 级别的日志信息更加详尽。存储目录OpenCode 在磁盘上保存了会话数据和应用数据目录位于macOS / Linux~/.local/share/opencode/Windows按下WINR粘贴%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.jsonmacOS / Linux较早版本安装~/.local/share/opencode/opencode.jsoncWindows按下WINR粘贴%USERPROFILE%\.config\opencode\opencode.jsonc并回车如果文件中配置了插件可以暂时移除plugin键或将其设为空数组{$schema:https://opencode.ai/config.json,plugin:[],}保存后重启应用。检查插件目录OpenCode 还会从本地磁盘加载插件。临时将这些目录移走或重命名文件夹然后重启桌面应用全局插件macOS / Linux~/.config/opencode/plugins/WindowsWINR后输入%USERPROFILE%\.config\opencode\plugins项目插件仅限使用了项目级配置的情况项目目录/.opencode/plugins/如果应用恢复正常再逐个将插件移回原位每恢复一个就重启一次以定位是哪个插件引起的故障。清理缓存如果禁用插件无效或者某个插件的安装卡住了可以清空缓存让 OpenCode 重新构建。完全退出 OpenCode 桌面版。删除缓存目录macOS打开访达按下CmdShiftG粘贴~/.cache/opencode并删除。Linux删除~/.cache/opencode可执行rm -rf ~/.cache/opencode。Windows按下WINR粘贴%USERPROFILE%\.cache\opencode并删除。重新启动 OpenCode 桌面版。修复服务器连接问题OpenCode 桌面版可以启动自己的本地服务器默认行为也可以连接用户配置的服务器 URL。如果看到“Connection Failed”对话框或者应用一直停留在启动画面就需要检查自定义服务器 URL 是否存在。清除桌面默认服务器 URL在主屏幕中点击带有状态指示圆点的服务器名称打开服务器选择器。在Default server部分点击Clear。从配置中移除 server.port / server.hostname打开opencode.json(c)配置文件如果其中有类似下面的server段落暂时将其整个删除然后重启桌面应用。检查环境变量如果系统中设置了OPENCODE_PORT环境变量桌面应用会尝试使用该端口作为本地服务器端口。可以取消设置OPENCODE_PORT或换成一个空闲端口然后重启应用。LinuxWayland / X11 问题在 Linux 上某些 Wayland 环境可能导致窗口空白或合成器错误。如果正使用 Wayland 且应用空白或崩溃可以尝试用OC_ALLOW_WAYLAND1启动。如果这样反而更糟就移除该变量改用 X11 会话启动。WindowsWebView2 运行时Windows 上的 OpenCode 桌面版依赖 Microsoft Edge WebView2 Runtime。如果应用打开时只显示空白窗口或根本无法启动请安装或更新 WebView2 运行时然后重试。Windows通用性能问题如果在 Windows 上遇到运行缓慢、文件访问异常或终端问题可以尝试使用 WSLWindows Subsystem for Linux。WSL 提供的 Linux 环境与 OpenCode 的各功能配合得更为顺畅。通知不显示OpenCode 桌面版只在同时满足两个条件时才会弹出系统通知操作系统设置中已经为 OpenCode 开启了通知权限应用窗口当前未被聚焦。重置桌面应用存储最后的手段如果应用完全无法启动且无法在界面内清除设置可以直接重置桌面应用的持久状态。完全退出 OpenCode 桌面版。找到并删除以下文件它们位于桌面应用的数据目录内opencode.settings.dat—— 桌面默认服务器 URLopencode.global.dat与opencode.workspace.*.dat—— 最近使用的服务器、项目等 UI 状态各操作系统快速定位该目录的方法macOS访达中按CmdShiftG前往~/Library/Application Support然后搜索上述文件名。Linux在~/.local/share下搜索上述文件名。Windows按下WINR输入%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.1openrouter/google/gemini-2.5-flashopencode/kimi-k2若要查看当前可访问的模型列表执行opencode modelsProviderInitError遇到ProviderInitError通常意味着配置无效或已损坏。解决方法如下先按照 providers 指南确认服务提供商的设置是否正确。如果问题依旧清空存储的配置rm-rf~/.local/share/opencodeWindows 系统上按WINR后输入并删除%USERPROFILE%\.local\share\opencode。在 TUI 中使用/connect命令重新认证。AI_APICallError 与提供程序包问题API 调用错误有时是由过期的提供程序包引起的。OpenCode 会根据需要动态安装各提供程序包OpenAI、Anthropic、Google 等并将它们缓存到本地。解决步骤清除提供程序包缓存rm-rf~/.cache/opencodeWindows按下WINR粘贴%USERPROFILE%\.cache\opencode并删除。重启 OpenCode它会重新下载最新版本的提供程序包。这往往能解决因模型参数或 API 变更导致的兼容性问题。Linux 上复制/粘贴失效Linux 用户需要安装剪贴板工具复制粘贴功能才能正常工作X11 系统aptinstall-yxclip# 或aptinstall-yxselWayland 系统aptinstall-ywl-clipboard无图形界面headless环境aptinstall-yxvfb# 然后运行Xvfb :99-screen01024x768x24/dev/null21exportDISPLAY:99.0OpenCode 会自动检测是否处于 Wayland 环境并优先使用 wl-clipboard否则会按xclip、xsel的顺序尝试寻找可用的剪贴板工具。以上便是 OpenCode 故障排查的完整流程。只要顺着日志、插件、缓存、服务器连接这条线索逐步检查绝大多数问题都能迎刃而解。如果还有难以解决的状况不妨到 GitHub 或 Discord 找社区一起诊断。