7.4 故障排除 - OpenCode深度教程

本章涵盖OpenCode使用过程中可能遇到的常见问题及其解决方案。

日志位置

排查问题的第一步是查看日志文件。

日志文件位置

# macOS
~/Library/Logs/opencode/

# Linux
~/.local/share/opencode/logs/
# 或
~/.config/opencode/logs/

# Windows
%APPDATA%\opencode\logs\

查看实时日志

# 查看最新日志
tail -f ~/.local/share/opencode/logs/opencode.log

# 启用详细日志模式运行
opencode --debug

# 或设置环境变量
export OPENCODE_LOG_LEVEL=debug
opencode

日志级别

# 可用级别：error, warn, info, debug, trace
export OPENCODE_LOG_LEVEL=debug

# 在配置文件中设置
{
  "logging": {
    "level": "debug",
    "file": true,
    "console": true
  }
}

常见问题及解决方案

启动问题

问题：OpenCode无法启动

# 检查是否正确安装
which opencode
opencode --version

# 重新安装
curl -fsSL https://opencode.ai/install | bash

# 检查依赖
# macOS需要Xcode命令行工具
xcode-select --install

# Linux需要基本开发工具
sudo apt install build-essential  # Debian/Ubuntu
sudo dnf groupinstall "Development Tools"  # Fedora

问题：终端显示异常

# 检查终端类型
echo $TERM

# 设置正确的终端类型
export TERM=xterm-256color

# 检查终端是否支持真彩色
printf "\x1b[38;2;255;100;0mTrueColor Test\x1b[0m\n"

# 禁用真彩色（如果不支持）
{
  "tui": {
    "trueColor": false
  }
}

问题：配置文件错误

# 验证配置文件语法
opencode config validate

# 查看当前配置
opencode config show

# 重置为默认配置
mv ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.bak
opencode

认证问题

问题：API密钥无效

# 检查环境变量是否设置
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

# 确保没有多余的空格或换行符
export ANTHROPIC_API_KEY="sk-ant-xxx"  # 使用引号

# 测试API密钥
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-haiku-20240307","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

问题：认证过期

# 重新登录
opencode auth login

# 清除缓存的认证信息
opencode auth logout
rm -rf ~/.config/opencode/auth/

# 检查认证状态
opencode auth status

问题：代理环境下认证失败

# 确保代理配置正确
export HTTPS_PROXY=http://proxy:8080
export HTTP_PROXY=http://proxy:8080

# 如果代理需要认证
export HTTPS_PROXY=http://user:pass@proxy:8080

# 排除不需要代理的地址
export NO_PROXY=localhost,127.0.0.1

模型可用性

问题：模型不可用

# 检查可用模型列表
opencode model list

# 检查提供商状态
opencode provider status

# 使用备用模型
opencode --model claude-3-haiku-20240307

问题：模型响应超时

# 增加超时时间
{
  "network": {
    "timeout": 120000
  }
}

# 或使用环境变量
export OPENCODE_TIMEOUT=120000

# 使用更快的模型
opencode --model claude-3-haiku-20240307

问题：达到速率限制

# 错误信息：Rate limit exceeded

# 解决方案1：等待后重试
# 大多数提供商的限制每分钟重置

# 解决方案2：配置自动重试
{
  "network": {
    "retries": 5,
    "retryDelay": 2000
  }
}

# 解决方案3：升级API计划或使用多个API密钥

提供商错误

问题：API返回错误

# 常见错误代码
# 400 - 请求格式错误
# 401 - 认证失败
# 403 - 权限不足
# 429 - 速率限制
# 500 - 服务器错误
# 503 - 服务不可用

# 查看详细错误信息
export OPENCODE_LOG_LEVEL=debug
opencode

# 检查API状态页面
# Anthropic: https://status.anthropic.com
# OpenAI: https://status.openai.com

问题：Azure OpenAI配置错误

# 确保所有必需的环境变量都已设置
export AZURE_OPENAI_API_KEY=xxx
export AZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com
export AZURE_OPENAI_DEPLOYMENT=gpt-4  # 部署名称

# 配置文件方式
{
  "provider": {
    "azure-openai": {
      "apiKey": "${AZURE_OPENAI_API_KEY}",
      "endpoint": "${AZURE_OPENAI_ENDPOINT}",
      "deployment": "gpt-4",
      "apiVersion": "2024-02-15-preview"
    }
  }
}

问题：自定义端点连接失败

# 检查端点是否可访问
curl -v https://your-endpoint.com/v1/health

# 检查SSL证书
openssl s_client -connect your-endpoint.com:443

# 使用自定义CA证书
export NODE_EXTRA_CA_CERTS=/path/to/ca.crt

剪贴板问题（Linux）

问题：复制粘贴不工作

# 检查剪贴板工具
which xclip xsel wl-copy

# 安装剪贴板工具
# X11系统
sudo apt install xclip
# 或
sudo apt install xsel

# Wayland系统
sudo apt install wl-clipboard

# 检查显示服务器类型
echo $XDG_SESSION_TYPE

问题：SSH环境下剪贴板不工作

# SSH时启用X11转发
ssh -X user@server

# 或使用OSC 52剪贴板序列
{
  "tui": {
    "clipboard": "osc52"
  }
}

# 确保终端支持OSC 52
# 支持的终端：iTerm2, Alacritty, kitty等

性能问题

问题：响应缓慢

# 检查网络延迟
ping api.anthropic.com

# 使用更快的模型
opencode --model claude-3-haiku-20240307

# 减少上下文大小
# 避免引用过大的文件

# 启用流式输出
{
  "streaming": true
}

问题：内存占用过高

# 限制会话历史
{
  "session": {
    "maxMessages": 50
  }
}

# 定期压缩会话
# 使用 /compact 命令

# 清理旧会话
opencode session prune --older-than 7d

获取帮助

社区资源

GitHub Issues - 报告Bug和功能请求
GitHub Discussions - 社区讨论
Discord - 实时交流
官方文档 - 完整文档

提交Bug报告

提交Bug报告时请包含以下信息：

# 收集系统信息
opencode debug info

# 输出示例：
# OpenCode Version: 1.2.3
# OS: macOS 14.0 (Darwin 23.0.0)
# Shell: zsh 5.9
# Terminal: iTerm2 3.5.0
# Node: v20.10.0
# Go: go1.21.5

收集调试信息

# 生成完整的调试包
opencode debug bundle --output debug-bundle.zip

# 包含内容：
# - 系统信息
# - 配置文件（敏感信息已脱敏）
# - 最近的日志
# - 终端能力检测结果

注意

提交调试包前，请确保其中不包含API密钥、密码等敏感信息。

企业支持

企业版用户可通过以下渠道获取优先支持：

专属Slack频道
邮件支持：support@opencode.ai
电话支持（仅限大型企业客户）

自助诊断清单

遇到问题时，按以下顺序排查：

检查OpenCode版本是否最新：opencode --version
验证配置文件语法：opencode config validate
确认API密钥正确设置
检查网络连接和代理配置
查看日志文件中的错误信息
尝试使用默认配置
搜索GitHub Issues中是否有类似问题
在社区寻求帮助

完成

恭喜你完成了OpenCode深度教程的学习！现在你已经掌握了从基础到高级的所有OpenCode功能。开始享受AI辅助编程的乐趣吧！