跳转到内容
展示 生态 源码解读 文档

故障排除

调试 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。

存储

opencode 将会话数据和其他应用数据存储在磁盘上的以下位置：

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

该目录包含：

  • auth.json — 认证数据，例如 API key、OAuth token
  • log/ — 应用日志
  • project/ — 项目特定的数据，例如会话和消息数据
    • 如果项目在 Git 仓库中，则存储在 ./<project-slug>/storage/
    • 如果不是 Git 仓库，则存储在 ./global/storage/

桌面应用

OpenCode Desktop 会在后台运行一个本地 OpenCode 服务器（opencode-cli sidecar）。大多数问题是由行为异常的插件、损坏的缓存或错误的服务器设置引起的。

快速检查

  • 完全退出后重新启动应用。
  • 如果应用显示错误页面，请点击 Restart 并复制错误详情。
  • 仅 macOS：OpenCode 菜单 -> Reload Webview（在 UI 空白或冻结时有用）。

禁用插件

如果桌面应用在启动时崩溃、卡住或行为异常，请先从禁用插件开始。

检查全局配置

打开你的全局配置文件，查找 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

如果配置了插件，请临时禁用它们，方法是删除该键或将其设置为空数组：

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

检查插件目录

OpenCode 也可以从磁盘加载本地插件。请临时将它们移走（或重命名文件夹），然后重启桌面应用：

  • 全局插件
    • macOS/Linux：~/.config/opencode/plugins/
    • Windows：按 WIN+R，粘贴 %USERPROFILE%\.config\opencode\plugins
  • 项目插件（仅当你使用项目级配置时）
    • <your-project>/.opencode/plugins/

如果应用恢复正常工作，请逐个重新启用插件，找出引发问题的那个。

清除缓存

如果禁用插件不起作用（或某个插件安装卡住了），请清除缓存以便 OpenCode 重新构建。

  1. 完全退出 OpenCode Desktop。
  2. 删除缓存目录：
  • macOS：Finder -> Cmd+Shift+G -> 粘贴 ~/.cache/opencode
  • Linux：删除 ~/.cache/opencode（或运行 rm -rf ~/.cache/opencode）
  • Windows：按 WIN+R，粘贴 %USERPROFILE%\.cache\opencode
  1. 重启 OpenCode Desktop。

修复服务器连接问题

OpenCode Desktop 可以启动自己的本地服务器（默认），也可以连接到你配置的某个服务器 URL。

如果出现 “Connection Failed” 对话框（或应用卡在启动画面），请检查是否设置了自定义的服务器 URL。

清除桌面默认服务器 URL

在主屏幕上，点击服务器名称（带状态圆点）以打开 Server 选择器。在 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 Desktop 需要 Microsoft Edge WebView2 Runtime。如果应用打开后窗口空白或无法启动，请安装/更新 WebView2 后重试。

Windows：常规性能问题

如果你在 Windows 上遇到性能缓慢、文件访问问题或终端问题，请尝试使用 WSL（Windows Subsystem for Linux）。WSL 提供了一个与 OpenCode 功能配合更顺畅的 Linux 环境。

通知未显示

OpenCode Desktop 仅在以下情况下显示系统通知：

  • 在操作系统的设置中为 OpenCode 启用了通知，并且
  • 应用窗口未处于聚焦状态。

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

如果应用无法启动，并且你无法在 UI 中清除设置，请重置桌面应用的已保存状态。

  1. 退出 OpenCode Desktop。
  2. 找到并删除以下文件（它们位于 OpenCode Desktop 的应用数据目录中）：
  • opencode.settings.dat（桌面默认服务器 URL）
  • opencode.global.dat 和 opencode.workspace.*.dat（UI 状态，例如最近的服务器/项目）

要快速找到该目录：

  • macOS：Finder -> Cmd+Shift+G -> ~/Library/Application Support（然后搜索上面的文件名）
  • Linux：在 ~/.local/share 下搜索上面的文件名
  • Windows：按 WIN+R -> %APPDATA%（然后搜索上面的文件名）

获取帮助

如果你在使用 OpenCode 时遇到问题：

  1. 在 GitHub 上报告问题

    报告 bug 或请求新功能的最佳方式是通过我们的 GitHub 仓库：

    github.com/anomalyco/opencode/issues

    在创建新 issue 之前，请先搜索现有 issue，看看你的问题是否已经被报告过。

  2. 加入我们的 Discord

    如需实时帮助和社区讨论，请加入我们的 Discord 服务器：

    opencode.ai/discord

常见问题

以下是一些常见问题及其解决方法。

OpenCode 无法启动

  1. 检查日志中的错误信息
  2. 尝试使用 --print-logs 运行以在终端中查看输出
  3. 使用 opencode upgrade 确保你使用的是最新版本

认证问题

  1. 尝试在 TUI 中使用 /connect 命令重新进行认证
  2. 检查你的 API key 是否有效
  3. 确保你的网络允许连接到对应 provider 的 API

模型不可用

  1. 检查你是否已与对应 provider 完成认证
  2. 验证配置中的模型名称是否正确
  3. 某些模型可能需要特定的访问权限或订阅

如果你遇到 ProviderModelNotFoundError，很可能是你在某处错误地引用了模型。 模型的引用格式应为：<providerId>/<modelId>

示例：

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

要查看你可用的模型，请运行 opencode models

ProviderInitError

如果你遇到 ProviderInitError，很可能是你的配置无效或已损坏。

解决方法：

  1. 首先，按照 providers 指南 验证你的 provider 配置是否正确

  2. 如果问题仍然存在，请尝试清除已存储的配置：

    rm -rf ~/.local/share/opencode

    在 Windows 上，按 WIN+R 并删除：%USERPROFILE%\.local\share\opencode

  3. 在 TUI 中使用 /connect 命令与你的 provider 重新进行认证。

AI_APICallError 和 provider 包问题

如果你遇到 API 调用错误，可能是由于 provider 包过时所致。opencode 会根据需要动态安装 provider 包（OpenAI、Anthropic、Google 等），并在本地进行缓存。

解决 provider 包问题的方法：

  1. 清除 provider 包的缓存：

    rm -rf ~/.cache/opencode

    在 Windows 上，按 WIN+R 并删除：%USERPROFILE%\.cache\opencode

  2. 重启 opencode 以重新安装最新的 provider 包

这将强制 opencode 下载最新版本的 provider 包，通常可以解决模型参数和 API 变更引起的兼容性问题。

Linux 上无法使用复制/粘贴

Linux 用户需要安装以下剪贴板工具之一，才能正常使用复制/粘贴功能：

对于 X11 系统：

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

对于 Wayland 系统：

apt install -y wl-clipboard

对于无显示环境：

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

opencode 会检测你是否正在使用 Wayland，并优先使用 wl-clipboard，否则会按 xclip、xsel 的顺序查找可用的剪贴板工具。