故障排查

在排查 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 Key、OAuth token
• log/ —— 应用日志
• project/ —— 项目相关数据，如会话和消息
  • 如果项目位于 Git 仓库中，则存储路径为 ./<project-slug>/storage/
  • 如果不是 Git 仓库，则存储在 ./global/storage/

---

获取帮助

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

1. 在 GitHub 上提交 Issue

   报告 bug 或提需求的最佳方式是使用 GitHub 仓库：

   github.com/anomalyco/opencode/issues

   在创建新 Issue 前，先搜索一下是否已有人报告过类似问题。

2. 加入 Discord 社区

   如果需要实时帮助或想参与社区讨论，可以加入我们的 Discord：

   opencode.ai/discord

---

常见问题

下面是一些常见问题及对应解决方案。

---

OpenCode 无法启动

1. 查看日志中的错误信息
2. 尝试使用 --print-logs 参数运行，以便在终端中直接看到输出
3. 使用 opencode upgrade 确保当前为最新版本

---

认证问题

1. 在 TUI 中使用 /connect 重新进行认证
2. 检查 API Key 是否仍然有效
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

3. 然后在 TUI 中使用 /connect 重新进行认证

---

AI_APICallError 及提供商包问题

如果发生 API 调用错误，可能是因为本地缓存的提供商 SDK 版本过旧。OpenCode 会按需动态安装各提供商的 SDK，并保存在本地缓存中。

解决方案：

1. 清除提供商包缓存：

   rm -rf ~/.cache/opencode

2. 重启 OpenCode，让它重新安装最新版本的提供商 SDK

这样通常可以解决由于模型参数或 API 更新带来的兼容性问题。

---

Linux 上复制/粘贴不可用

在 Linux 上，为了让复制/粘贴正常工作，需要安装以下剪贴板工具之一：

X11 环境：

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

Wayland 环境：

apt install -y wl-clipboard

无头环境（Headless）：

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

OpenCode 会自动检测你是否在使用 Wayland，若是，则优先使用 wl-clipboard；否则会按 xclip、xsel 的顺序查找可用工具。