如果需要调试 OpenCode 的任何问题，你可以查看它本地存储的 logs（日志）或 session data（会话数据）。

Logs（日志）

日志文件存放在以下路径：

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

日志文件以 timestamps（时间戳）命名（例如：2025-01-09T123456.log），并且最多只保留最近的 10 个日志文件。

你可以通过 --log-level command-line option（命令行参数）来设置日志级别，以获取更详细的 debug information（调试信息）。 例如：opencode --log-level DEBUG。

Storage（存储）

opencode 会将 session data（会话数据）以及其他 application data（应用数据）存储在本地磁盘：

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

该目录包含：

  • auth.json —— Authentication data（认证数据），例如 API keys、OAuth tokens
  • log/ —— Application logs（应用日志）

  • project/ —— Project-specific data（项目级数据），例如 session 和 message 数据

    • 如果项目位于 Git repo 中，则存储在 ./<project-slug>/storage/
    • 如果项目不在 Git repo 中，则存储在 ./global/storage/

Getting help（获取帮助）

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

1. 在 GitHub 上提交 issue

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

github.com/anomalyco/opencode/issues

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

2. 加入 Discord 社区

如果需要实时帮助或参与社区讨论，可以加入官方 Discord server：

opencode.ai/discord

Common issues（常见问题）

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

OpenCode 无法启动

  1. 查看 logs，确认是否有 error messages（错误信息）
  2. 使用 --print-logs 参数运行，在 terminal 中直接查看输出
  3. 确认你使用的是最新版本：opencode upgrade

Authentication issues（认证问题）

  1. 在 TUI 中使用 /connect 命令重新认证
  2. 检查你的 API keys 是否有效
  3. 确认你的网络允许访问 provider 的 API

Model not available（模型不可用）

  1. 确认你已经完成 provider 的认证
  2. 检查 config 中的 model name 是否正确
  3. 某些模型可能需要特定权限或订阅

如果遇到 ProviderModelNotFoundError，通常意味着你在某处错误引用了模型名称。

模型的引用格式应为：

  1. <providerId>/<modelId>

示例：

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

要查看你当前可用的 models，可以运行：

  1. opencode models

ProviderInitError

如果遇到 ProviderInitError，通常说明你的配置无效或已损坏（invalid / corrupted configuration）。

解决步骤：

  1. 首先按照 providers guide 确认 provider 配置是否正确

  2. 如果问题仍然存在，尝试清空本地配置数据：

    1. rm -rf ~/.local/share/opencode

  3. 在 TUI 中使用 /connect 命令重新进行认证

AI_APICallError 和 provider package 问题

如果遇到 API call errors，可能是由于 provider packages 版本过旧导致的。 opencode 会按需动态安装 provider packages（例如 OpenAI、Anthropic、Google 等），并缓存在本地。

解决方法：

  1. 清空 provider package 缓存：

    1. rm -rf ~/.cache/opencode

  2. 重启 opencode，让它重新安装最新的 provider packages

这样会强制 opencode 下载最新版本的 provider packages，通常可以解决由于 model parameters 或 API 变更带来的兼容性问题。

Linux 下复制 / 粘贴不可用

Linux 用户需要安装以下 clipboard utilities（剪贴板工具）之一，复制 / 粘贴功能才能正常工作。

X11 系统：

  1. apt install -y xclip
  2. # 或
  3. apt install -y xsel

Wayland 系统：

  1. apt install -y wl-clipboard

Headless 环境：

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

opencode 会自动检测你是否在使用 Wayland，并优先使用 wl-clipboard；否则会按顺序尝试查找剪贴板工具：xclip → xsel。