H. 故障排除
💡 一句话总结：系统性地诊断和解决问题
日志和存储位置
日志文件
| 平台 | 路径 |
|---|---|
| macOS/Linux | ~/.local/share/opencode/log/ |
| Windows | %USERPROFILE%\.local\share\opencode\log\ |
bash
# 查看最新日志
ls -lt ~/.local/share/opencode/log/ | head
# 开启调试日志
opencode --log-level DEBUG
# 打印日志到终端
opencode --print-logs存储位置
| 数据类型 | 路径 |
|---|---|
| 配置文件 | ~/.config/opencode/opencode.json |
| 认证信息 | ~/.local/share/opencode/auth.json |
| 日志 | ~/.local/share/opencode/log/ |
| 项目数据 | ~/.local/share/opencode/project/ |
| 缓存 | ~/.cache/opencode/ |
启动问题
无法启动 / 命令找不到
症状：zsh: command not found: opencode
诊断步骤：
bash
# 1. 检查是否安装
which opencode
# 2. 检查 PATH
echo $PATH | tr ':' '\n' | grep -E "(npm|bin)"解决方案：
bash
# 重新安装
npm install -g opencode-ai
# 手动添加到 PATH
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc启动崩溃 / 白屏
症状：启动后立即退出或显示空白屏幕
诊断步骤：
bash
# 1. 查看错误日志
opencode --print-logs 2>&1 | head -50
# 2. 清除缓存重试
rm -rf ~/.cache/opencode
opencode
# 3. 重置配置
mv ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.bak
opencode认证问题
API Key 无效
症状：AuthenticationError: Invalid API key
诊断步骤：
bash
# 检查已配置的凭证
opencode auth list
# 检查环境变量
env | grep API_KEY解决方案：
bash
# 重新配置
opencode auth loginToken 配额超限
症状：RateLimitError: quota exceeded
解决方案：
- 等待配额重置
- 升级账户计划
- 切换到其他提供商/模型
bash
# 切换模型
opencode -m zhipu/glm-4-flash网络问题
连接超时
症状：ETIMEDOUT / ECONNREFUSED / ECONNRESET
诊断步骤：
bash
# 1. 测试基本网络
ping api.anthropic.com
# 2. 测试 HTTPS
curl -v https://api.anthropic.com解决方案：
bash
# 设置代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
# 或使用国产模型
/connect # 选择 Z.AI文件操作问题
文件写入失败
症状：AI 说修改了文件但实际没变
诊断步骤：
bash
# 1. 检查文件权限
ls -la path/to/file
# 2. 检查 OpenCode 权限设置
cat ~/.config/opencode/opencode.json | jq .permission诊断命令汇总
bash
# 版本信息
opencode --version
# 系统信息
uname -a
# 调试日志
opencode --log-level DEBUG --print-logs
# 查看已认证的提供商
opencode auth list
# 查看可用模型
opencode models📚 更多完整模板：Prompt 模板库