| 项目 |
说明 |
| 症状 |
模型列表接口正常，但实际请求无响应 |
| 解决方案 |
设置 OPENCODE_USE_ISOLATED_HOME=false 让 OpenCode 复用本机登录态（config.json 中用短键 USE_ISOLATED_HOME） |
OPENCODE_USE_ISOLATED_HOME=false
| 项目 |
说明 |
| 症状 |
返回 model_not_found 错误 |
| 解决方案 |
检查可用模型列表，确认模型 ID 正确 |
curl http://127.0.0.1:10000/v1/models
| 项目 |
说明 |
| 症状 |
发送了 reasoning_effort 但没有推理输出 |
| 解决方案 |
使用 stream: true 的 Responses API |
| 项目 |
说明 |
| 症状 |
客户端意外触发了 OpenCode 工具调用 |
| 解决方案 |
保持 DISABLE_TOOLS=true |
| 项目 |
说明 |
| 症状 |
Error: listen EADDRINUSE: address already in use |
| 解决方案 |
更改端口或检查端口占用 |
# 检查端口占用
lsof -i :10000
lsof -i :10001
# 更改端口
OPENCODE_PROXY_PORT=10002
OPENCODE_SERVER_PORT=10003
| 项目 |
说明 |
| 症状 |
Cannot verify OpenCode installation |
| 解决方案 |
安装 OpenCode CLI |
# Windows
npm install -g opencode-ai
# Linux/macOS
curl -fsSL https://opencode.ai/install | bash
| 项目 |
说明 |
| 症状 |
容器启动失败或立即退出 |
| 解决方案 |
检查日志和配置 |
# 查看日志
docker compose logs
# 检查端口
netstat -tulpn | grep -E '10000|10001'
| 项目 |
说明 |
| 症状 |
返回 401 Unauthorized |
| 解决方案 |
确认 API_KEY 配置正确 |
curl -H "Authorization: Bearer YOUR_API_KEY" ...
| 项目 |
说明 |
| 症状 |
非原生协议客户端收到缺字段、空工具调用、usage 为 0、截断信号丢失 |
| 说明 |
网关建议各客户端使用原生协议端点（OpenAI SDK → /v1/chat/completions 或 /v1/responses，Anthropic SDK → /v1/messages，Gemini SDK → /v1beta/interactions）。跨协议转换是 best-effort，目前仅 POST /v1/messages 入站走转换矩阵，其余路径可能降级（纯文本 + 零填充用量），属已知限制而非后端故障 |
提 issue 前请先排除偶发因素：
# 1. 重试一次，并检查后端状态（排除波动/限流）
curl -H "Authorization: Bearer YOUR_API_KEY" http://127.0.0.1:10000/health/details
# 2. 用原生协议端点复现同一请求（确认是转换问题，而非模型/后端问题）
# 3. 开调试日志抓最小复现
OPENCODE_PROXY_DEBUG=true
提 issue 时请附（并删掉 API_KEY 等密钥）：端点 + 协议方向（如 messages→chat）、最小请求 JSON、期望 vs 实际响应、模型 ID、原生端点是否同样复现。
开启调试日志:
# 环境变量
OPENCODE_PROXY_DEBUG=true
调试日志会输出详细的请求和响应信息。
📖 Docs Index | 🏠 Main README
