Open Code 文档

主题

首页文档搜索

OpenCode 故障排除实战指南 ​

📚 分类: 工具配置与排错 ⏱️ 预计耗时: 15-30 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode (桌面版或 CLI 版)

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 快速定位 OpenCode 问题的根源（日志、缓存、插件）
  • [ ] 独立解决 OpenCode 启动失败、连接失败、模型不可用等常见问题
  • [ ] 在 Linux、macOS、Windows 三大平台上执行针对性排错
  • [ ] 掌握“重置”与“清除”等高级排错手段，而不丢失关键数据

最终效果 ​

你将不再惧怕 OpenCode 报错，能够像专家一样系统地排查并解决大部分常见问题，让你的开发环境始终保持稳定运行。

前置准备 ​

在开始排错前，请确认你已了解 OpenCode 的基本概念和文件位置。

1. 了解日志和数据存储位置 ​

OpenCode 将日志和用户数据存储在以下目录中：

操作系统日志目录 (用于调试)数据目录 (用于重置)
macOS / Linux~/.local/share/opencode/log/~/.local/share/opencode/
Windows按 Win+R，粘贴 %USERPROFILE%\.local\share\opencode\log按 Win+R，粘贴 %USERPROFILE%\.local\share\opencode

💡 提示：日志文件以时间戳命名（例如 2025-01-09T123456.log），OpenCode 会保留最近的 10 个日志文件。

2. 掌握启动调试模式 ​

bash
# 以 DEBUG 日志级别启动 OpenCode，获取最详细的错误信息
$ opencode --log-level DEBUG

✅ 验证：执行命令后，终端会输出大量调试信息，日志文件中的内容也会更加详细。

第 1 步：快速检查与重启 ​

🎯 目标：通过最简单的操作，解决因临时状态导致的 80% 的问题。

📝 操作：

  1. 完全退出并重启应用：关闭 OpenCode 窗口，确保后台进程也结束（可以通过任务管理器或 killall opencode 命令），然后重新打开。
  2. 重新加载 Webview (仅限 macOS)：如果 UI 界面空白或卡住，点击顶部菜单栏 OpenCode -> Reload Webview。

✅ 验证：应用正常启动，界面响应流畅。

第 2 步：禁用插件（排查启动崩溃/卡死） ​

🎯 目标：确定是否由于某个插件导致应用启动时崩溃、卡住或行为异常。

📝 操作：

  1. 找到全局配置文件：

    • macOS/Linux: ~/.config/opencode/opencode.jsonc (或 opencode.json)
    • Windows: 按 Win+R，粘贴 %USERPROFILE%\.config\opencode\opencode.jsonc

  2. 临时禁用所有插件：打开该文件，找到 plugin 键，将其值设置为空数组 []。

    json
    {
  "$schema": "https://opencode.ai/config.json",
  "plugin": [] // 临时禁用所有插件
}

  3. （可选）移动本地插件文件夹：如果配置文件中没有 plugin 键，插件可能存放在本地文件夹中。临时重命名这些文件夹。

    • 全局插件目录:
      • macOS/Linux: ~/.config/opencode/plugins/
      • Windows: 按 Win+R，粘贴 %USERPROFILE%\.config\opencode\plugins
    • 项目插件目录 (如果使用了项目级配置): <your-project>/.opencode/plugins/

  4. 重启 OpenCode。

🤔 为什么要这样做？ 插件是 OpenCode 功能扩展的重要部分，但一个不兼容或有 Bug 的插件会导致整个应用崩溃。通过禁用所有插件，我们可以快速判断问题是否由插件引起。

✅ 验证：如果应用恢复正常，说明问题出在插件上。请逐个重新启用插件，找出导致问题的那个。

第 3 步：清除缓存 ​

🎯 目标：清除损坏的缓存文件，解决插件安装卡住、UI 显示异常等问题。

📝 操作：

  1. 完全退出 OpenCode Desktop。
  2. 删除缓存目录：
    • macOS: 打开 Finder -> 按下 Cmd+Shift+G -> 粘贴 ~/.cache/opencode，然后删除整个文件夹。
    • Linux: 运行 rm -rf ~/.cache/opencode。
    • Windows: 按 Win+R，粘贴 %USERPROFILE%\.cache\opencode，然后删除整个文件夹。
  3. 重启 OpenCode Desktop。

✅ 验证：OpenCode 会像第一次启动一样，重新构建缓存，应用运行流畅。

第 4 步：修复服务器连接问题 ​

🎯 目标：解决应用始终停留在启动画面或显示“Connection Failed”的问题。

📝 操作：

  1. 清除桌面默认服务器 URL：
    • 在 OpenCode 主页面，点击顶部服务器名称（旁边有状态指示点）。
    • 在弹出的服务器选择器中，找到“默认服务器”部分，点击“清除”。
  2. 移除配置文件中的 server 部分：
    • 打开你的 opencode.json(c) 文件（路径同第 2 步）。
    • 找到并删除 server 相关的配置项，例如：
      json
      // 删除以下内容
"server": {
  "port": 8080,
  "hostname": "localhost"
}
  3. 检查环境变量：
    • 在终端中运行 echo $OPENCODE_PORT (macOS/Linux) 或检查系统环境变量 (Windows)。
    • 如果设置了该变量，取消设置它（例如，在 Linux/macOS 下运行 unset OPENCODE_PORT）。

✅ 验证：重启 OpenCode Desktop，应用能正常连接到默认的本地服务器。

第 5 步：平台特定问题排查 ​

🎯 目标：解决 Linux、Windows 上的特有兼容性问题。

5.1 Linux: Wayland / X11 问题 ​

  • 问题：在 Wayland 下窗口空白或合成器错误。
  • 操作：
    bash
    # 尝试强制使用 Wayland
$ OC_ALLOW_WAYLAND=1 opencode

# 如果情况更糟，移除该设置，并尝试在 X11 会话下启动（通常无需额外操作）
  • 验证：应用窗口正常显示。

5.2 Windows: WebView2 运行时 ​

  • 问题：应用打开后是空白窗口或无法启动。
  • 操作：下载并安装 Microsoft Edge WebView2 Runtime。
  • 验证：重启 OpenCode Desktop，界面正常渲染。

5.3 Windows: 常见性能问题 ​

  • 问题：性能缓慢、文件访问问题、终端问题。
  • 操作：使用 WSL (Windows Subsystem for Linux) 作为开发环境。
  • 验证：在 WSL 中运行 OpenCode，性能得到改善。

5.4 Linux: 复制/粘贴不可用 ​

  • 问题：在 Linux 下无法使用复制/粘贴功能。
  • 操作：根据你的图形系统安装相应的剪贴板工具。
    bash
    # 对于 X11 系统
$ sudo apt install xclip
# 或
$ sudo apt install xsel

# 对于 Wayland 系统
$ sudo apt install wl-clipboard

# 对于无头环境 (headless)
$ sudo apt install xvfb
# 然后运行虚拟显示器
$ Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
$ export DISPLAY=:99.0
  • 验证：在 OpenCode 中复制文本，粘贴到其他应用中正常。

第 6 步：重置桌面应用存储（最后手段） ​

🎯 目标：当应用完全无法启动，且无法通过 UI 或配置文件清除设置时，强制重置所有状态。

⚠️ 警告：此操作会清除你的桌面应用设置（如默认服务器 URL、UI 布局等），但不会删除你的项目数据和 API 密钥。

📝 操作：

  1. 完全退出 OpenCode Desktop。
  2. 找到并删除以下文件：它们位于 OpenCode Desktop 的应用数据目录中。
    • opencode.settings.dat (存储默认服务器 URL)
    • opencode.global.dat 和 opencode.workspace.*.dat (存储 UI 状态)
  3. 快速定位目录：
    • macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support，然后搜索上述文件名。
    • Linux: 在 ~/.local/share 下搜索上述文件名。
    • Windows: 按 Win+R -> %APPDATA%，然后搜索上述文件名。

✅ 验证：重启 OpenCode Desktop，应用将以出厂状态启动。

常见问题 (FAQ) ​

Q1: 如何查看 OpenCode 的日志？A: 按照“前置准备”中的路径找到日志目录，用文本编辑器打开最新的 .log 文件。或者在终端运行 opencode --print-logs 直接查看。

Q2: 遇到 ProviderInitError 怎么办？A: 这通常是提供商配置无效或损坏。首先，按照提供商指南检查配置。如果问题依旧，可以尝试清除已存储的配置：

bash
# macOS/Linux
$ rm -rf ~/.local/share/opencode

# Windows
# 按 Win+R，删除 %USERPROFILE%\.local\share\opencode

之后，在 TUI 中使用 /connect 命令重新进行身份验证。

Q3: 遇到 AI_APICallError 怎么办？A: 这可能是提供商包过期。清除提供商包缓存并重启：

bash
# macOS/Linux
$ rm -rf ~/.cache/opencode

# Windows
# 按 Win+R，删除 %USERPROFILE%\.cache\opencode

重启 OpenCode 后，它会自动下载最新版本的提供商包。

Q4: 模型引用格式是什么？A: 模型必须按 <providerId>/<modelId> 的格式引用。

  • ✅ 正确：openai/gpt-4.1
  • ✅ 正确：openrouter/google/gemini-2.5-flash
  • ✅ 正确：opencode/kimi-k2
  • ❌ 错误：gpt-4.1 (缺少提供商)

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心排错思路：

  1. 由简入繁：从重启、禁用插件开始，逐步深入到清除缓存、重置存储。
  2. 对症下药：针对不同平台（Linux, Windows）和不同错误（启动失败、连接失败、模型错误）使用特定的解决方法。
  3. 日志为王：学会查看日志是解决一切问题的第一步。

下一步 ​

如果你还想深入探索 OpenCode，建议学习：

💡 练习任务：尝试故意制造一个错误（例如，在配置文件中写一个错误的模型名），然后使用本教程学到的排错方法来解决它。

yaml

## 相关文档

- [OpenCode 安装故障排除实战指南](/docs/chang-jian-cuo-wu/opencode-an-zhuang-gu-zhang-pai-chu-shi-zhan-zhi-nan.html)

Open Code 文档社区

© 2026 Open Code. All rights reserved.