LowHow 文档

中文

English

中文

English

深色模式

OpenCode 常见问题排查实战指南：从日志定位到一键修复 ​

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

你将学到什么 ​

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

  • [ ] 定位并查看 OpenCode 的日志文件以诊断问题
  • [ ] 通过禁用插件、清理缓存等方法解决 90% 的启动/运行异常
  • [ ] 处理服务器连接失败、API 认证错误等常见问题
  • [ ] 在 Linux 下正确配置剪贴板功能

最终效果 ​

你将掌握一套系统性的故障排除方法，当 OpenCode 出现“无法启动”、“连接失败”、“模型不可用”等错误时，能独立、快速地找到原因并修复，而无需盲目搜索。

前置准备 ​

在开始排查前，请确认你拥有对以下路径的读写权限（通常你拥有自己家目录的权限）。

检查项路径/命令说明
日志目录请见下方第 1 步查看错误的第一现场
配置目录请见下方第 2 步存放插件和全局设置

第 1 步：查看日志，定位错误 ​

🎯 目标：找到 OpenCode 生成的日志文件，这是所有排查工作的起点。

📝 操作：

日志文件是 .log 后缀，按时间戳命名。请根据你的操作系统找到它们：

macOS / Linux：

bash
# 进入日志目录
$ cd ~/.local/share/opencode/log/

# 列出最近的日志文件（按时间排序）
$ ls -lt

Windows：

  1. 按下键盘上的 WIN + R 键，打开“运行”对话框。
  2. 输入以下路径并点击“确定”：
    text
    %USERPROFILE%\.local\share\opencode\log

✅ 验证： 你应该能看到类似 2025-01-09T123456.log 的文件。文件名中的时间戳就是日志生成的时间。

💡 提示：如果需要更详细的调试信息，可以在启动 OpenCode 时加上 --log-level DEBUG 参数。例如：

bash
# 以 DEBUG 级别启动，输出更详细的信息到终端
$ opencode --log-level DEBUG

第 2 步：快速检查与核心修复 ​

🎯 目标：执行一系列快速检查，解决最常见的问题。

📝 操作：

2.1 彻底重启 ​

首先，完全退出 OpenCode（不仅仅是关闭窗口），然后重新启动它。

  • macOS: 在菜单栏点击 OpenCode -> Quit OpenCode。
  • Windows/Linux: 在系统托盘右键点击 OpenCode 图标，选择退出。

2.2 检查并禁用插件 ​

插件是导致崩溃或行为异常的头号嫌疑犯。

  1. 找到全局配置文件：

    • macOS/Linux: ~/.config/opencode/opencode.jsonc (或 .json)
    • Windows: 按下 WIN + R，输入 %USERPROFILE%\.config\opencode\opencode.jsonc 并回车。

  2. 编辑配置文件：用文本编辑器打开它。找到 plugin 这一项。如果里面有插件列表，暂时将其清空或删除整行。

    jsonc
    // opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  // [!code --] "plugin": ["some-plugin"],  // 删除或注释掉这一行
  "plugin": [] // [!code ++]  // 改为空数组
}

  3. 移动本地插件目录（可选）：如果你从本地加载了插件，可以暂时将它们移走。

    bash
    # 移动全局插件
$ mv ~/.config/opencode/plugins ~/.config/opencode/plugins_backup

# 移动项目级插件（如果存在）
$ mv ./.opencode/plugins ./.opencode/plugins_backup

✅ 验证： 重启 OpenCode。如果问题消失，说明是某个插件导致的。请逐个将插件加回，直到找到问题插件。

2.3 清理缓存 ​

如果禁用插件无效，或某个插件安装卡住了，请清理缓存。

bash
# 先完全退出 OpenCode

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

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

# Windows：按下 WIN+R，输入 %USERPROFILE%\.cache\opencode，然后删除整个文件夹。

✅ 验证： 重启 OpenCode。应用会自动重建缓存。

⚠️ 常见错误：如果 rm -rf 命令提示权限不足，请确保你已经完全退出了 OpenCode 应用。

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

🎯 目标：解决 OpenCode 桌面端无法连接到后端服务器的错误。

📝 操作：

如果你的应用卡在启动画面或显示“Connection Failed”，通常是服务器连接配置有误。

  1. 清除自定义服务器 URL：

    • 如果能进入主界面，点击左下角带有状态圆点的服务器名称。
    • 在弹出的“服务器选择器”中，找到“默认服务器”部分，点击“清除”按钮。

  2. 从配置文件中移除服务器设置：

    • 打开你的全局配置文件（路径见第 2.2 步）。
    • 找到 server 配置块，将其整个删除或注释掉。
    jsonc
    // opencode.jsonc
{
  // [!code --] "server": {  // 删除或注释掉这个块
  //   "port": 8080,
  //   "hostname": "localhost"
  // }
}

  3. 检查环境变量： 打开终端，检查是否设置了 OPENCODE_PORT 环境变量。

    bash
    # 检查环境变量
$ echo $OPENCODE_PORT

    如果输出了数字（如 3000），这会导致 OpenCode 尝试使用该端口。请取消设置它：

    bash
    # 取消设置环境变量（仅在当前终端会话中生效）
$ unset OPENCODE_PORT

✅ 验证： 重启 OpenCode 桌面端。如果问题解决，说明是之前的服务器配置或环境变量导致的问题。

第 4 步：处理 Linux 特有与常见 API 问题 ​

🎯 目标：解决特定于 Linux 系统以及 API 认证相关的常见错误。

📝 操作：

4.1 Linux: 解决剪贴板/界面问题 ​

场景 A：复制粘贴不工作

这通常是因为缺少剪贴板工具。请根据你的显示服务器安装对应工具。

  1. 判断显示服务器：

    bash
    $ echo $XDG_SESSION_TYPE
# 输出可能是 x11 或 wayland

  2. 安装对应工具：

    bash
    # 如果是 X11 系统
$ sudo apt install -y xclip   # 或者 xsel

# 如果是 Wayland 系统
$ sudo apt install -y wl-clipboard

场景 B：窗口空白或崩溃

如果你在使用 Wayland 时遇到空白窗口，尝试用以下命令启动：

bash
# 允许 OpenCode 使用 Wayland
$ OC_ALLOW_WAYLAND=1 opencode

如果情况更糟，则移除该环境变量，并在 X11 会话下运行。

4.2 处理认证与模型问题 ​

场景 A：模型不可用 (ProviderModelNotFoundError)

这个错误通常是因为模型名称写错了。正确的格式是 <providerId>/<modelId>。

text
# 正确示例
openai/gpt-4.1
openrouter/google/gemini-2.5-flash

# 错误示例（缺少 providerId）
gpt-4.1

要查看你当前可用的模型列表，在终端运行：

bash
$ opencode models

场景 B: ProviderInitError

这表示你的提供商配置无效或已损坏。

  1. 重新配置：参考 OpenCode 的提供商配置指南（此链接为示意，请替换为真实链接），重新进行认证。
  2. 清空存储并重试：
    bash
    # macOS/Linux
$ rm -rf ~/.local/share/opencode

# Windows: 按下 WIN+R，删除 %USERPROFILE%\.local\share\opencode
    之后，再次使用 /connect 命令重新进行认证。

场景 C：API 调用错误

这可能是由于过时的提供商程序包导致的。请清理程序包缓存，让 OpenCode 重新下载最新版本。

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

# Windows: 按下 WIN+R，删除 %USERPROFILE%\.cache\opencode

✅ 验证： 重启 OpenCode。对于剪贴板问题，尝试在 OpenCode 中输入文本并复制；对于模型问题，尝试发送一条消息，看是否不再报错。

进阶技巧（可选） ​

重置桌面端存储（最后手段） ​

如果应用完全无法启动，且以上所有方法都无效，可以重置桌面应用的保存状态。

  1. 完全退出 OpenCode。
  2. 找到并删除以下文件（它们位于 OpenCode 桌面应用的专属数据目录中）：
    • 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%，然后搜索。

常见问题 (FAQ) ​

Q1: 我在日志里看到一堆看不懂的错误，怎么办？A: 这是好消息！日志是诊断问题的金矿。你可以：

  1. 复制日志内容。
  2. 访问 OpenCode GitHub Issues 页面，搜索相关错误信息。
  3. 如果找不到，创建一个新的 Issue，并附上日志内容和你尝试过的步骤。

Q2: 我的 Windows 版本 OpenCode 打开后是空白窗口？A: 这通常是因为缺少 Microsoft Edge WebView2 运行时。请前往微软官方网站下载并安装最新版本的 WebView2 Runtime。

Q3: 我如何获取实时帮助？A: 加入 OpenCode 的 Discord 服务器，那里有活跃的社区和开发者可以协助你。

总结 ​

恭喜你掌握了 OpenCode 的系统性排错方法！🎉

回顾一下我们今天学到的核心内容：

  1. 查看日志：排查任何问题的第一步，永远从 ~/.local/share/opencode/log/ 开始。
  2. 核心三连：遇到问题，优先尝试“重启应用 -> 禁用插件 -> 清理缓存”。
  3. 配置排查：检查 opencode.jsonc 中的 plugin 和 server 配置，以及环境变量 OPENCODE_PORT。
  4. 平台差异：Linux 用户需注意剪贴板工具和 Wayland/X11 兼容性；Windows 用户需确保 WebView2 已安装。

© 2026 LowHow