Skip to content
OpenCode 中文文档
HomeDocs

故障排除

常见问题及其解决方法。

要调试 OpenCode 的任何问题，你可以查看日志或其存储在本地的会话数据。

日志

日志文件写入位置：

  • macOS/Linux: ~/.local/share/opencode/log/
  • Windows: %USERPROFILE%\.local\share\opencode\log/

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

你可以通过 --log-level 命令行选项设置日志级别，以获取更详细的调试信息。例如，opencode --log-level DEBUG。

存储

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

  • macOS/Linux: ~/.local/share/opencode/
  • Windows: %USERPROFILE%\.local\share\opencode

此目录包含：

  • auth.json - 身份验证数据，如 API 密钥、OAuth 令牌
  • log/ - 应用程序日志
  • project/ - 特定于项目的数据，如会话和消息数据
    • 如果项目位于 Git 仓库中，数据存储在 ./<project-slug>/storage/
    • 如果不是 Git 仓库，则存储在 ./global/storage/

获取帮助

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

  1. 在 GitHub 上提交 Issue

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

    github.com/anomalyco/opencode/issues

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

  2. 加入我们的 Discord

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

    opencode.ai/discord

常见问题

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

OpenCode 无法启动

  1. 检查日志中的错误消息
  2. 尝试运行 opencode --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. 如果问题仍然存在，请尝试清除存储的配置：

    Terminal window
    rm -rf ~/.local/share/opencode

  3. 在 TUI 中使用 /connect 命令重新与你的提供商进行身份验证。

AI_APICallError 和提供商包问题

如果你遇到 API 调用错误，这可能是由于提供商包过时导致的。OpenCode 会根据需要动态安装提供商包（OpenAI、Anthropic、Google 等）并将其缓存在本地。

解决提供商包问题：

  1. 清除提供商包缓存：

    Terminal window
    rm -rf ~/.cache/opencode

  2. 重启 OpenCode 以安装最新的提供商包。

这将强制 OpenCode 下载提供商包的最新版本，通常可以解决与模型参数和 API 变更相关的兼容性问题。

Linux 上无法复制/粘贴

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

对于 X11 系统：

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

对于 Wayland 系统：

Terminal window
apt install -y wl-clipboard

对于无界面 (headless) 环境：

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

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