跳至内容
OpenCode
app.header.homeapp.header.docs

故障排除

常见问题及解决方法。

要调试 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 密钥、OAuth 令牌
  • log/ - 应用程序日志
  • project/ - 项目特定数据，如会话和消息数据
    • 如果项目在 Git 仓库中，它存储在 ./<project-slug>/storage/
    • 如果不是 Git 仓库，它存储在 ./global/storage/

桌面应用

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

快速检查

  • 完全退出并重新启动应用程序。
  • 如果应用程序显示错误屏幕，点击 重新启动 并复制错误详情。
  • 仅限 macOS: OpenCode 菜单 -> 重新加载 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.ac.cn/config.json",
  "plugin": [],
}

检查插件目录

OpenCode 还可以从磁盘加载本地插件。暂时将这些插件移开（或重命名文件夹），然后重新启动桌面应用。

  • 全局插件
    • macOS/Linux: ~/.config/opencode/plugins/
    • Windows: 按下 WIN+R 并粘贴 %USERPROFILE%\.config\opencode\plugins
  • 项目插件 (仅当您使用按项目配置时)
    • <your-project>/.opencode/plugins/

如果应用程序再次正常工作，请逐个重新启用插件以找出导致问题的插件。

清除缓存

如果禁用插件没有帮助（或插件安装卡住），请清除缓存，以便 OpenCode 可以重建它。

  1. 完全退出 OpenCode 桌面版。
  2. 删除缓存目录
  • macOS: Finder -> Cmd+Shift+G -> 粘贴 ~/.cache/opencode
  • Linux: 删除 ~/.cache/opencode (或运行 rm -rf ~/.cache/opencode)
  • Windows: 按下 WIN+R 并粘贴 %USERPROFILE%\.cache\opencode
  1. 重新启动 OpenCode 桌面版。

修复服务器连接问题

OpenCode 桌面版可以启动自己的本地服务器（默认）或连接到您配置的服务器 URL。

如果您看到 “连接失败” 对话框（或应用程序一直停留在启动画面），请检查是否有自定义服务器 URL。

清除桌面默认服务器 URL

在主屏幕上，点击服务器名称（带状态点）以打开服务器选择器。在 默认服务器 部分，点击 清除。

从您的配置中移除 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 运行时。如果应用打开后是空白窗口或无法启动，请安装/更新 WebView2 并重试。

Windows: 常见性能问题

如果您在 Windows 上遇到性能缓慢、文件访问问题或终端问题，请尝试使用 WSL（适用于 Linux 的 Windows 子系统）。WSL 提供了一个 Linux 环境，可以与 OpenCode 的功能更无缝地协作。

通知未显示

OpenCode 桌面版仅在以下情况下显示系统通知：

  • 您的操作系统设置中为 OpenCode 启用了通知，并且
  • 应用程序窗口未聚焦。

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

如果应用无法启动且您无法从 UI 内部清除设置，请重置桌面应用的保存状态。

  1. 退出 OpenCode 桌面版。
  2. 查找并删除这些文件（它们位于 OpenCode 桌面应用的应用程序数据目录中）
  • 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 上报告问题

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

    github.com/anomalyco/opencode/issues

    在创建新问题之前，请搜索现有问题，查看您的问题是否已被报告。

  2. 加入我们的 Discord

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

    opencode.ai/discord

常见问题

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

OpenCode 无法启动

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

认证问题

  1. 尝试在 TUI 中使用 /connect 命令重新进行认证
  2. 检查您的 API 密钥是否有效
  3. 确保您的网络允许连接到提供商的 API

模型不可用

  1. 检查您是否已向提供商进行认证
  2. 验证您配置中的模型名称是否正确
  3. 某些模型可能需要特定的访问权限或订阅

如果您遇到 ProviderModelNotFoundError，则很可能是在某个地方错误地引用了模型。模型应按以下方式引用：<providerId>/<modelId>

示例

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

要了解您可以访问哪些模型，请运行 opencode models

ProviderInitError

如果您遇到 ProviderInitError，您可能拥有无效或损坏的配置。

解决方法如下：

  1. 首先，请按照提供商指南验证您的提供商设置是否正确。

  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 以重新安装最新的提供商软件包

这将强制 opencode 下载最新版本的提供商软件包，这通常能解决模型参数和 API 更改带来的兼容性问题。

Linux 上复制/粘贴不起作用

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

对于 X11 系统

终端窗口
apt install -y xclip
# or
apt install -y xsel

对于 Wayland 系统

终端窗口
apt install -y wl-clipboard

对于无头环境

终端窗口
apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

opencode 会检测您是否在使用 Wayland 并优先选择 wl-clipboard，否则它将按 xclip 和 xsel 的顺序尝试查找剪贴板工具。