故障排除

常见问题及其解决方法。

要调试 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 tokens
• log/ - 应用程序日志
• project/ - 项目特定数据，如会话和消息数据
  • 如果项目在 Git 仓库中，它存储在 ./<project-slug>/storage/
  • 如果不是 Git 仓库，它存储在 ./global/storage/

---

# 获取帮助#

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

1. 在 GitHub 上报告问题

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

   github.com/anomalyco/opencode/issues↗

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

2. 加入我们的 Discord

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

   opencode.ai/discord↗

---

# 常见问题#

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

---

## OpenCode 无法启动#

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

   bash
   复制
   rm -rf ~/.local/share/opencode

3. 在 TUI 中使用 /connect 命令重新与提供商认证。

---

## AI_APICallError 和提供商包问题#

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

要解决提供商包问题：

1. 清除提供商包缓存：

   bash
   复制
   rm -rf ~/.cache/opencode

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

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

---

## Linux 上复制/粘贴不工作#

Linux 用户需要安装以下剪贴板工具之一才能使复制/粘贴功能工作：

对于 X11 系统：

bash
复制
apt install -y xclip
# 或
apt install -y xsel

对于 Wayland 系统：

bash
复制
apt install -y wl-clipboard

对于无头环境：

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

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