跳到主要内容

调试命令

📋 概述​

调试命令用于排查和解决 OpenCode 使用过程中的问题，包括查看日志、测试连接、诊断系统状态等。

📊 查看日志​

查看系统运行日志

日志级别：

  • DEBUG: 详细调试信息
  • INFO: 一般信息
  • WARN: 警告信息
  • ERROR: 错误信息

查看选项：

  • 无参数：查看所有日志
  • --tail: 显示最后 N 行
  • --follow: 持续跟踪日志
  • --level: 过滤特定级别

使用场景：

  • 查看运行状态
  • 定位错误原因
  • 监控系统行为
  • 性能分析

使用示例：

# 查看所有日志
opencode logs

# 查看最后 100 行
opencode logs --tail 100

# 持续跟踪日志
opencode logs --follow

# 只查看错误日志
opencode logs --level ERROR

🧪 测试连接​

测试 OpenCode 的各项连接

测试内容：

API 连接测试​

测试与 AI 提供商的 API 连接

测试项目：

  • 网络连接状态
  • API 密钥有效性
  • 响应时间
  • 配额剩余

提供商支持：

  • OpenAI
  • Anthropic
  • Google
  • 其他兼容提供商

使用示例：

# 测试所有提供商
opencode test

# 测试特定提供商
opencode test --provider openai
opencode test --provider anthropic

# 测试特定模型
opencode test --provider openai --model gpt-4o

代理连接测试​

测试代理配置是否正确

测试项目：

  • 代理连接状态
  • 代理认证
  • 代理性能

使用示例：

opencode test --proxy

服务连接测试​

测试本地服务状态

测试项目：

  • 服务运行状态
  • 端口监听状态
  • 响应正常性

使用示例：

opencode test --service

🔍 诊断问题​

运行系统诊断，找出潜在问题

诊断项目：

环境检查​

  • Node.js 版本
  • 操作系统版本
  • 内存使用情况
  • 磁盘空间

配置检查​

  • 配置文件语法
  • 配置项合法性
  • 配置冲突检测

依赖检查​

  • 核心依赖完整性
  • 版本兼容性
  • 缺失依赖检测

权限检查​

  • 文件系统权限
  • 目录访问权限
  • 网络访问权限

诊断输出：

  • 问题列表
  • 严重程度
  • 修复建议

使用示例：

opencode diagnose

🐛 常见问题诊断​

服务无法启动​

诊断步骤：

  1. 检查端口占用
  2. 查看错误日志
  3. 验证配置文件
  4. 检查依赖安装

解决方案：

  • 更换端口
  • 修复配置错误
  • 重新安装依赖

API 调用失败​

诊断步骤：

  1. 测试 API 连接
  2. 验证 API 密钥
  3. 检查网络连接
  4. 查看配额余额

解决方案：

  • 更新 API 密钥
  • 配置代理
  • 检查配额

工具执行失败​

诊断步骤：

  1. 查看工具日志
  2. 检查工具权限
  3. 验证参数正确性
  4. 测试工具配置

解决方案：

  • 启用工具
  • 调整权限
  • 修正参数

响应速度慢​

诊断步骤：

  1. 测试网络连接
  2. 检查 API 响应时间
  3. 分析工具执行时间
  4. 查看资源占用

解决方案：

  • 优化网络
  • 切换模型
  • 减少工具调用

📈 性能监控​

资源使用情况​

查看系统资源使用

监控指标：

  • CPU 使用率
  • 内存使用量
  • 磁盘 I/O
  • 网络流量

API 使用统计​

查看 API 调用统计

统计信息：

  • 调用次数
  • Token 使用量
  • 成本估算
  • 响应时间

工具使用统计​

查看工具使用情况

统计信息：

  • 调用次数
  • 成功率
  • 平均执行时间
  • 常用工具排行

🔧 高级调试​

启用调试模式​

开启详细的调试输出

配置方法：

opencode config set log.level DEBUG

调试信息包括：

  • 详细调用栈
  • 中间状态
  • 内部处理流程

导出诊断报告​

生成完整的诊断报告

报告内容包括：

  • 系统信息
  • 配置信息
  • 日志摘要
  • 问题列表
  • 修复建议

使用示例：

opencode diagnose --export report.txt

远程调试​

支持远程调试支持

使用场景：

  • 向技术支持提供诊断信息
  • 社区求助时共享问题

💡 调试技巧​

逐步排查​

采用系统化的排查方法

排查流程：

  1. 确认问题现象
  2. 复现问题
  3. 收集日志
  4. 分析原因
  5. 尝试修复
  6. 验证结果

缩小范围​

逐步缩小问题范围

方法：

  • 简化输入
  • 减少工具调用
  • 使用简单模型
  • 最小化配置

对比测试​

通过对比找出差异

对比维度：

  • 正常 vs 异常
  • 不同模型
  • 不同配置
  • 不同环境

📝 常见问题​

Q: 日志文件在哪里？​

A: 日志文件通常位于 ~/.opencode/logs/ 目录下。

Q: 如何启用更详细的日志？​

A: 使用 config set log.level DEBUG 命令启用调试级别日志。

Q: 诊断报告包含哪些信息？​

A: 包含系统信息、配置信息、日志摘要、问题列表和修复建议。

Q: 如何向技术支持寻求帮助？​

A: 运行 diagnose --export 导出诊断报告，附上问题描述，通过 GitHub Issues 联系。

📖 相关文章​