OpenCode 调试、网络与故障排除指南

OpenCode 连接着多个外部的 LLM 提供商，运行在多种操作系统和网络环境下。当出现问题时，掌握系统的调试和排查方法可以帮你快速恢复工作。本文覆盖日志分析、调试模式、网络代理配置和常见问题的解决方案。

一、调试模式

启用调试日志

在 opencode.json 中配置：

{
  "advanced": {
    "debug": true,
    "logLevel": "debug"
  }
}

或者在启动时通过命令行参数启用：

opencode --debug
opencode --log-level debug

日志级别

| 级别 | 内容 | 用途 |
|------|------|------|
| error | 仅错误信息 | 生产环境 |
| warn | 警告和错误 | 一般使用 |
| info | 关键操作日志 | 了解运行状态 |
| debug | 详细调试信息 | 排查问题 |
| trace | 最详细的执行记录 | 深度排查 |

日志位置

~/.config/opencode/logs/
├── opencode.log        # 主日志文件
├── errors.log          # 错误日志
├── network.log         # 网络请求日志
├── tools.log           # 工具调用日志
└── sessions/           # 会话记录
    └── 2026-07-29/

查看实时日志

# 实时查看
tail -f ~/.config/opencode/logs/opencode.log

# 只看错误
tail -f ~/.config/opencode/logs/errors.log

# 搜索特定内容
grep "ANTHROPIC" ~/.config/opencode/logs/opencode.log

诊断工具

# 运行完整诊断
opencode doctor

# 输出示例：
# ✓ OpenCode version: 0.1.x
# ✓ Node.js: v22.5.1
# ✓ Config file: ~/.config/opencode/opencode.json (valid)
# ✓ Provider: anthropic (configured)
# ✗ Network: Cannot reach api.anthropic.com (timeout)
# → 建议：检查代理配置或网络连接

二、网络与代理配置

HTTP 代理配置

{
  "network": {
    "proxy": "http://127.0.0.1:7890",
    "proxyExclusions": [
      "localhost",
      "127.0.0.1",
      "*.internal.company.com"
    ],
    "timeout": 120000
  }
}

环境变量方式

# 设置代理环境变量
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,.internal.com

# 然后启动 OpenCode
opencode

常见代理工具配置

# Clash / Clash Verge
export HTTPS_PROXY=http://127.0.0.1:7890

# V2Ray
export HTTPS_PROXY=http://127.0.0.1:10809

# Shadowsocks
export HTTPS_PROXY=socks5://127.0.0.1:1080

# 公司 HTTP 代理
export HTTPS_PROXY=http://proxy.company.com:8080

网络连通性测试

# 测试 Anthropic API
curl -I https://api.anthropic.com

# 测试 OpenAI API
curl -I https://api.openai.com

# 通过代理测试
curl -I --proxy http://127.0.0.1:7890 https://api.anthropic.com

自定义 API 端点

如果你的组织使用了代理转发服务：

{
  "provider": {
    "id": "anthropic",
    "apiKey": "${ANTHROPIC_API_KEY}",
    "baseUrl": "https://your-proxy.company.com/anthropic"
  }
}

这适用于：

  • 企业内网的 API 代理
  • API 中转服务（如 api2d、openai-sb 等）
  • 自建的 API 网关

三、常见问题排查

1. 连接提供商失败

症状：启动后提示无法连接到模型提供商

排查步骤：

# 1. 检查网络连通性
curl -I https://api.anthropic.com

# 2. 检查代理是否生效
opencode doctor

# 3. 检查 API Key 是否有效
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-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hello"}]}'

# 4. 检查 opencode.json 配置是否正确
cat ~/.config/opencode/opencode.json | grep -A5 provider

常见原因：

  • API Key 过期或无效
  • 网络连接问题（需要代理但未配置）
  • 账户余额不足
  • 提供商服务故障

2. OpenCode 启动后卡住/无响应

排查步骤：

# 1. 检查 Node.js 版本
node --version  # 需要 22+

# 2. 清理缓存
rm -rf ~/.config/opencode/cache/

# 3. 重新安装
npm uninstall -g opencode-ai
npm i -g opencode-ai@latest

# 4. 用 debug 模式启动查看具体问题
opencode --debug

3. 响应内容被截断

原因：模型的 maxOutputTokens 设置过小

解决：

{
  "model": "claude-sonnet-4-20250514",
  "options": {
    "maxOutputTokens": 16384
  }
}

4. AI 生成代码格式混乱

原因：未配置 Formatter 或 formatOnSave

解决：

{
  "formatters": {
    "prettier": {
      "command": "npx",
      "args": ["prettier", "--write"],
      "extensions": [".js", ".ts", ".jsx", ".tsx", ".json"]
    }
  },
  "formatOnSave": true
}

5. Token 消耗过快

排查：

# 查看当前会话 Token 使用
/cost

# 查看上下文大小
/context

优化：

{
  "session": {
    "maxContextTokens": 120000,
    "autoSummarize": true,
    "summarizeThreshold": 0.6
  },
  "context": {
    "maxFiles": 20,
    "exclude": [
      "node_modules", "dist", ".git",
      "*.lock", "*.map", "*.generated.*"
    ]
  }
}

6. 快捷键不生效

原因：终端模拟器拦截了快捷键

解决：

  • Windows Terminal：在设置中释放 Ctrl+Shift+C 等快捷键
  • macOS Terminal：设置 → 描述文件 → 键盘 → 将 Option 用作 Meta 键
  • iTerm2：Preferences → Keys → 修改被占用的快捷键

或者自定义快捷键避免冲突：

{
  "keybinds": {
    "submit": "Ctrl+Enter",
    "toggleSidebar": "F1",
    "toggleFiles": "F2"
  }
}

7. 内存/CPU 占用过高

排查：

# 检查 OpenCode 进程
ps aux | grep opencode

# 检查内存占用
top -p $(pgrep opencode)

优化：

{
  "advanced": {
    "maxConcurrency": 2,
    "indexOnStart": false
  },
  "context": {
    "exclude": ["node_modules", "dist", ".git", "vendor"]
  }
}

8. 配置文件不生效

排查：

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

# 查看生效的配置
opencode config show

# 检查配置加载顺序
opencode config show --sources

常见原因：

  • JSON 格式错误（逗号多余、引号不匹配）
  • 配置文件路径不对
  • 配置项名称拼写错误

9. MCP 服务器连接失败

# 手动测试 MCP 服务器是否能启动
npx -y @modelcontextprotocol/server-filesystem /tmp/test

# 列出已配置的 MCP 服务器
opencode mcp list

# 测试特定服务器
opencode mcp test filesystem

10. 更新后出现异常

# 清理并重新安装
npm uninstall -g opencode-ai
rm -rf ~/.config/opencode/cache/
rm -rf ~/.opencode/
npm i -g opencode-ai@latest

# 如果问题持续，安装特定版本
npm i -g opencode-ai@0.1.50

四、性能优化

启动速度优化

{
  "context": {
    "indexOnStart": false
  },
  "lazy": true
}

响应速度优化

  • 使用低延迟模型：Groq（Llama 系列）、DeepSeek
  • 减少上下文大小
  • 使用本地模型（Ollama）避免网络延迟

内存优化

{
  "advanced": {
    "maxConcurrency": 1,
    "session": {
      "maxContextTokens": 80000
    }
  }
}

五、系统化调试方法

遇到复杂问题时，使用 OpenCode 内置的 systematic-debugging 技能：

@systematic-debugging

帮我排查为什么 OpenCode 在大型项目上响应特别慢

AI 会按照系统化的调试流程帮你定位问题：

收集症状信息

形成假设

逐个验证假设

找到根本原因

验证修复方案

六、获取帮助

官方渠道

  • 文档：https://opencode.ai/docs
  • GitHub Issues：https://github.com/anomalyco/opencode/issues
  • Discord：https://discord.gg/opencode

提交 Bug Report 时包含

# 收集必要信息
opencode --version > bug-report.txt
echo "---" >> bug-report.txt
node --version >> bug-report.txt
echo "---" >> bug-report.txt
uname -a >> bug-report.txt
echo "---" >> bug-report.txt
opencode doctor >> bug-report.txt 2>&1
echo "---" >> bug-report.txt
cat ~/.config/opencode/logs/errors.log | tail -20 >> bug-report.txt

小结

掌握调试和故障排除技能是高效使用 OpenCode 的关键。从简单的 opencode doctor 诊断到深入分析日志文件，从网络代理配置到性能优化——有了这些知识，大部分问题都能快速自行解决。

下一篇是本系列的最后一篇——OpenCode 完全指南总目录，把所有内容串联起来，提供完整的学习路线。

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客