Opencode 常见问题排查：Bad Request、连接失败等问题解决

使用 Opencode 时难免会遇到各种问题。本文汇总了最常见的错误及其解决方案，帮助你快速排查和修复问题。

连接相关问题

问题 1：Bad Request (400 错误)

错误信息：

Error: Bad Request (400)
Invalid request format

常见原因：

  1. API Key 格式错误
  2. 请求参数不正确
  3. 模型名称拼写错误
  4. 配置文件格式问题

解决方案：

步骤 1：检查 API Key

# 查看当前配置
opencode config list

# 重新设置 API Key
opencode config set anthropic.apiKey sk-ant-xxx

确保 API Key：

  • 以正确的前缀开头（sk-ant- 或 sk-）
  • 没有多余的空格或换行
  • 没有过期

步骤 2：验证配置文件格式

检查 ~/.config/opencode/config.json：

{
  "apiKeys": {
    "anthropic": "sk-ant-xxx",
    "openai": "sk-xxx"
  },
  "modelPreferences": {
    "default": "claude-3-5-sonnet-20241022"
  }
}

步骤 3：测试连接

opencode test-connection

问题 2：连接超时

错误信息：

Error: Request timeout
Failed to connect to API server

解决方案：

方法 1：检查网络连接

# 测试网络
ping api.anthropic.com
curl -I https://api.anthropic.com

方法 2：配置代理

如果在国内网络环境：

# 设置代理
opencode config set proxy.http http://127.0.0.1:7890
opencode config set proxy.https http://127.0.0.1:7890

# 或使用环境变量
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

方法 3：增加超时时间

{
  "network": {
    "timeout": 60000,
    "retries": 3
  }
}

问题 3：API 配额超限

错误信息：

Error: Rate limit exceeded
Too many requests

解决方案：

方法 1：检查使用量

opencode usage --month 2025-06

方法 2：切换到本地模型

# 安装 Ollama
brew install ollama
ollama pull qwen2.5-coder:7b

# 配置 Opencode 使用本地模型
opencode config set model.default qwen2.5-coder:7b

方法 3：使用速率限制

{
  "rateLimit": {
    "requestsPerMinute": 10,
    "tokensPerMinute": 50000
  }
}

性能问题

问题 4：响应速度慢

症状：

  • AI 响应时间超过 10 秒
  • 代码生成卡顿
  • 界面无响应

诊断：

# 运行性能诊断
opencode doctor --verbose

# 查看日志
opencode logs --tail 100

解决方案：

优化 1：使用更快的模型

{
  "modelPreferences": {
    "fast": "claude-3-5-haiku-20241022"
  }
}

优化 2：减少上下文大小

{
  "context": {
    "maxTokens": 8000,
    "maxFiles": 10
  }
}

优化 3：启用缓存

{
  "cache": {
    "enabled": true,
    "ttl": 3600
  }
}

问题 5：内存占用过高

症状：

  • 系统变慢
  • Opencode 崩溃
  • 内存不足警告

解决方案：

方法 1：限制内存使用

{
  "performance": {
    "maxMemory": "2GB",
    "gcInterval": 300
  }
}

方法 2：清理缓存

# 清理所有缓存
opencode cache clear

# 清理旧日志
opencode logs clean --days 7

方法 3：使用轻量级模型

# 切换到本地轻量级模型
ollama pull mistral:7b
opencode config set model.default mistral:7b

配置问题

问题 6：配置文件找不到

错误信息：

Error: Configuration file not found

解决方案：

步骤 1：检查配置文件位置

# macOS/Linux
ls -la ~/.config/opencode/

# Windows
dir %APPDATA%\opencode\

步骤 2：创建默认配置

opencode config init

步骤 3：手动创建配置文件

# macOS/Linux
mkdir -p ~/.config/opencode
cat > ~/.config/opencode/config.json << 'EOF'
{
  "apiKeys": {},
  "modelPreferences": {
    "default": "claude-3-5-sonnet-20241022"
  }
}
EOF

问题 7：配置优先级混乱

症状：

  • 配置不生效
  • 使用了错误的模型
  • API Key 不正确

理解配置优先级：

环境变量 > 工作区配置 > 用户配置 > 默认配置

检查配置来源：

opencode config show --source

输出示例：

anthropic.apiKey: sk-ant-xxx (from: environment)
model.default: claude-3-5-sonnet (from: workspace)
proxy.http: http://127.0.0.1:7890 (from: user)

模型相关问题

问题 8：模型不可用

错误信息：

Error: Model not found
The requested model is not available

解决方案：

步骤 1：检查模型名称

# 列出可用模型
opencode models list

步骤 2：更新模型配置

# 使用正确的模型名称
opencode config set model.default claude-3-5-sonnet-20241022

步骤 3：检查 API 权限

确保你的 API Key 有权访问该模型。

问题 9：本地模型无法启动

错误信息：

Error: Failed to connect to Ollama
Connection refused at localhost:11434

解决方案：

步骤 1：检查 Ollama 是否运行

# 检查进程
ps aux | grep ollama

# 启动 Ollama
ollama serve

步骤 2：验证模型已下载

# 列出已下载的模型
ollama list

# 下载模型
ollama pull qwen2.5-coder:7b

步骤 3：检查端口

# 测试连接
curl http://localhost:11434/api/tags

代码生成问题

问题 10：生成的代码有错误

症状：

  • 语法错误
  • 逻辑错误
  • 不符合项目规范

解决方案：

方法 1：提供更多上下文

创建 AGENTS.md 文件：

# 项目上下文

## 技术栈
- TypeScript 5.0
- React 18
- Node.js 20

## 代码规范
- 使用函数式组件
- 严格的类型检查
- ESLint + Prettier

## 常见模式
[提供代码示例]

方法 2：使用更强的模型

opencode config set model.default claude-3-5-sonnet-20241022

方法 3：分步骤执行

不要一次性要求太多，分解任务：

步骤 1："创建数据模型"
步骤 2："实现 API 接口"
步骤 3："添加错误处理"

问题 11：AI 不理解项目结构

解决方案：

方法 1：使用项目索引

# 生成项目索引
opencode index create

# 更新索引
opencode index update

方法 2：明确指定文件路径

"在 src/components/UserProfile.tsx 中添加..."

方法 3：提供项目结构说明

在 AGENTS.md 中添加：

## 项目结构
src/
├── components/  # 公共组件
├── features/    # 功能模块
│   ├── auth/    # 认证相关
│   └── user/    # 用户相关
├── utils/       # 工具函数
└── types/       # 类型定义

权限和安全问题

问题 12：权限被拒绝

错误信息：

Error: Permission denied
EACCES: permission denied

解决方案：

macOS/Linux：

# 修复权限
sudo chown -R $(whoami) ~/.config/opencode

# 或使用 sudo 运行
sudo opencode [command]

Windows：

以管理员身份运行 PowerShell 或 CMD。

问题 13：API Key 泄露风险

最佳实践：

方法 1：使用环境变量

# 不要在配置文件中硬编码
export ANTHROPIC_API_KEY=sk-ant-xxx
export OPENAI_API_KEY=sk-xxx

方法 2：使用 .env 文件

创建 .env 文件（添加到 .gitignore）：

ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx

方法 3：使用密钥管理工具

# macOS Keychain
security add-generic-password -a opencode -s anthropic -w sk-ant-xxx

# 读取
security find-generic-password -a opencode -s anthropic -w

诊断工具

使用 opencode doctor

# 全面检查
opencode doctor

# 详细输出
opencode doctor --verbose

# 检查特定组件
opencode doctor --check api
opencode doctor --check config
opencode doctor --check models

查看日志

# 实时日志
opencode logs --follow

# 最近 100 行
opencode logs --tail 100

# 按级别过滤
opencode logs --level error

# 导出日志
opencode logs --export debug.log

性能分析

# 性能报告
opencode perf report

# 追踪特定操作
opencode perf trace --operation "code-generation"

获取帮助

如果以上方法都无法解决问题：

  1. 查看官方文档：https://opencode.ai/docs
  2. 搜索社区讨论：https://github.com/opencode/opencode/discussions
  3. 提交 Issue：https://github.com/opencode/opencode/issues
  4. 加入 Discord：https://discord.gg/opencode

提交 Issue 时请包含：

  • Opencode 版本：opencode --version
  • 操作系统信息
  • 错误信息和日志
  • 复现步骤
  • 配置文件（删除敏感信息）

小结

大多数 Opencode 问题都可以通过以下步骤解决：

  1. 运行诊断：opencode doctor
  2. 检查日志：opencode logs --tail 100
  3. 验证配置：opencode config show
  4. 测试连接：opencode test-connection
  5. 查看文档：参考官方文档和社区讨论

记住，遇到问题不要慌，系统地排查，大部分问题都有简单的解决方案。

需要更多帮助？访问故障排查中心或加入社区讨论。

最近更新: