5.22 调试与诊断

💡 一句话总结：掌握问题排查方法，快速定位和解决 OpenCode 的各种问题。

学完你能做什么

理解 OpenCode 的常见问题类型
使用诊断工具定位问题
根据错误信息判断问题根源
快速找到解决方案

你现在的困境

OpenCode 出问题了不知道怎么排查
错误信息看不懂
不知道从哪里开始调试
遇到问题只能重启

什么时候用这一招

当你需要：解决 OpenCode 的各种问题
而且不想：浪费时间盲目尝试

🎒 开始前的准备

确保你已经完成以下事项：

[ ] 完成了 5.1b 配置进阶
[ ] 了解 OpenCode 的基本结构

核心思路

调试方法论

问题发现
    ↓
信息收集（日志、错误信息）
    ↓
问题分类（配置、网络、权限等）
    ↓
定位根源（哪个组件）
    ↓
解决方案
    ↓
验证修复

问题类型

类型	常见表现	难度	频率
配置错误	配置文件不对、参数错误	低	高
网络问题	连接超时、API 调用失败	中	中
权限问题	文件访问被拒绝	低	中
性能问题	响应慢、卡顿	高	低
Bug	功能异常、崩溃	高	低
环境问题	版本不兼容、依赖缺失	中	中

诊断工具

1. 日志系统

启用调试日志：

yaml

# AGENTS.md
logging:
  level: "debug"  # debug | info | warn | error
  output: "file"  # file | console | both
  path: "~/.opencode/logs"
  max_size: "10M"
  max_files: 5

日志级别说明：

级别	输出内容	使用场景
debug	最详细，所有操作	开发和调试
info	关键操作和状态	正常使用
warn	警告信息	发现问题
error	错误信息	发生错误

查看日志：

bash

# 查看最新日志
tail -f ~/.opencode/logs/opencode.log

# 搜索错误
grep ERROR ~/.opencode/logs/opencode.log

# 查看特定时间段
sed -n '/2026-02-04 16:00/,/2026-02-04 17:00/p' ~/.opencode/logs/opencode.log

2. 诊断命令

运行全面诊断：

bash

opencode doctor

输出示例：

OpenCode 诊断报告
===================

配置文件:
  ✅ AGENTS.md 存在
  ✅ 语法正确
  ❌ 缺少必填项: agents.default

环境:
  ✅ Node.js 18.17.0
  ✅ npm 9.6.7
  ✅ Git 2.39.2

网络:
  ✅ API 连接正常 (50ms)
  ✅ WebSocket 连接正常
  ❌ 代理设置可能有问题

工具:
  ✅ Prettier 可用
  ❌ Python 未安装
  ✅ TypeScript 可用

总体状态: 2 个问题需要修复

3. 状态检查

检查当前状态：

bash

opencode status

输出示例：

会话状态:
  当前会话: ses_abc123
  消息数: 23
  Token 使用: 12,450 / 100,000
  后台任务: 2 个运行中

Agent 状态:
  当前 Agent: developer
  最后活动: 2 分钟前

缓存状态:
  LSP 缓存: 145 条
  文件缓存: 89 个
  压缩缓存: 56 个

常见问题诊断

问题 1: 配置文件错误

症状：

错误: 无法加载 AGENTS.md
或
配置验证失败: 缺少必填项

诊断步骤：

bash

# 1. 检查文件是否存在
ls -la AGENTS.md

# 2. 检查语法（如果是 JSON/YAML）
cat AGENTS.md | python -m json.tool

# 3. 验证配置
opencode validate AGENTS.md

# 4. 查看详细错误
opencode logs --level error

常见原因：

原因	解决方法
缩进错误	检查 YAML 缩进，使用空格而非 Tab
引号问题	确保字符串正确用引号
缺少必填项	查看文档补全必填字段
格式不匹配	确保 JSON/YAML 格式正确

问题 2: API 连接失败

症状：

错误: 无法连接到 OpenCode API
网络错误: 请求超时

诊断步骤：

bash

# 1. 测试网络连接
ping api.opencode.ai

# 2. 测试端口
nc -zv api.opencode.ai 443

# 3. 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 4. 查看详细日志
opencode logs --filter "api"

常见原因：

原因	解决方法
网络断开	检查网络连接
代理问题	配置正确的代理或关闭代理
防火墙阻止	添加白名单或临时关闭
DNS 问题	尝试更换 DNS 服务器

问题 3: 权限问题

症状：

错误: 权限被拒绝
无法写入文件: xxx.md

诊断步骤：

bash

# 1. 检查文件权限
ls -l xxx.md

# 2. 检查目录权限
ls -ld .

# 3. 检查当前用户
whoami

# 4. 尝试修复权限
chmod 644 xxx.md
chmod 755 .

常见原因：

原因	解决方法
文件只读	修改权限 `chmod +w`
目录无写入权	修改目录权限
用户切换了	使用正确的用户
SELinux 限制	临时关闭或配置规则

问题 4: LSP 工作异常

症状：

LSP 工具无响应
符号列表为空
无法跳转到定义

诊断步骤：

bash

# 1. 检查 LSP 服务器状态
opencode lsp status

# 2. 重启 LSP 服务器
opencode lsp restart

# 3. 查看详细日志
opencode logs --filter "lsp"

# 4. 手动测试 LSP
opencode lsp test typescript

常见原因：

原因	解决方法
LSP 服务器未安装	安装对应语言服务器
项目缺少配置文件	创建 tsconfig.json 等
缓存过期	清空缓存
端口冲突	重启或更换端口

问题 5: 性能问题

症状：

响应很慢
占用内存过高
CPU 使用率高

诊断步骤：

bash

# 1. 查看系统资源
top
htop

# 2. 检查内存使用
free -h

# 3. 分析性能日志
opencode logs --filter "performance"

# 4. 清理缓存
opencode cache clean

常见原因：

原因	解决方法
缓存太大	清理缓存 `opencode cache clean`
思考深度太深	降低思考深度
项目太大	使用上下文压缩
LSP 缓存过多	重启 LSP

问题 6: Token 超限

症状：

错误: Token 超限
上下文窗口已满

诊断步骤：

bash

# 1. 查看 Token 使用
opencode token-usage

# 2. 查看历史记录
opencode history

# 3. 清理不必要的上下文
opencode context clear-old

常见原因：

原因	解决方法
上下文积累太多	清理历史记录
文件太大	使用上下文压缩
对话太长	总结并清理旧对话
未启用压缩	启用上下文压缩策略

跟我做

实战 1: 诊断配置问题

目标：定位并修复配置文件错误

故意引入错误到 AGENTS.md：

yaml

# 错误：缺少冒号
agents
  default: developer

# 或缩进错误
agents:
    default: developer  # 多了两个空格

尝试启动 OpenCode，观察错误信息
运行诊断：

bash

opencode validate AGENTS.md

根据错误信息修复配置
再次验证：

bash

opencode validate AGENTS.md

你应该看到：错误被准确指出，修复后验证通过

实战 2: 诊断网络问题

目标：排查 API 连接问题

模拟网络问题（断网或更改代理）
运行诊断：

bash

opencode doctor

查看详细日志：

bash

opencode logs --filter "network" --level error

尝试手动测试连接：

bash

curl -I https://api.opencode.ai/health

修复网络问题（恢复网络或调整代理）

你应该学到：如何系统地排查网络问题

实战 3: 诊断性能问题

目标：识别性能瓶颈并优化

触发性能问题：
- 大量文件读取
- 深度思考模式
- 复杂查询
查看资源占用：

bash

top -p $(pgrep opencode)

分析日志：

bash

opencode logs --filter "performance"

检查缓存：

bash

opencode cache stats

实施优化：
- 清理缓存
- 调整思考深度
- 启用压缩

你应该看到：优化后性能明显提升

📋 诊断流程图

问题出现
    ↓
是配置错误吗？
    ├─ 是 → 验证配置文件
    │       ↓
    │       修复并重启
    │
    └─ 否 → 是网络问题吗？
            ├─ 是 → 测试连接
            │       ↓
            │       检查代理/防火墙
            │
            └─ 否 → 是权限问题吗？
                    ├─ 是 → 检查文件权限
                    │       ↓
                    │       修复权限
                    │
                    └─ 否 → 是性能问题吗？
                            ├─ 是 → 检查资源占用
                            │       ↓
                            │       清理缓存
                            │
                            └─ 否 → 查看详细日志
                                    ↓
                                    分析日志定位问题

检查点 ✅

全部通过才能继续

[ ] 能运行诊断命令
[ ] 能看懂错误日志
[ ] 掌握了常见问题的排查方法
[ ] 能独立解决基本问题

踩坑提醒

错误	常见误判	正确做法
配置错误	以为是 Bug	先用 validate 检查
网络超时	以为是 API 故障	检查本地网络设置
权限被拒	以为是软件 Bug	检查文件和目录权限
响应慢	以为是性能问题	检查思考深度设置
Token 超限	以为是限额不够	使用上下文压缩

最佳实践

1. 定期检查

bash

# 每天运行一次
opencode doctor

# 每周清理一次缓存
opencode cache clean

# 每月检查日志
opencode logs --level error

2. 保留关键日志

遇到问题时，保存诊断信息：

bash

# 导出诊断报告
opencode doctor > diagnostic-report-$(date +%Y%m%d).txt

# 导出日志
opencode logs > opencode-log-$(date +%Y%m%d).txt

3. 问题记录模板

## 问题描述
[具体描述问题]

## 复现步骤
1. ...
2. ...

## 错误信息
[粘贴错误信息]

## 诊断信息
[粘贴 opencode doctor 输出]

## 环境信息
- OS: ...
- Node.js: ...
- OpenCode 版本: ...

## 尝试过的解决方案
[列出已尝试的方法]

4. 寻求帮助前

在寻求帮助前，准备好以下信息：

bash

# 收集诊断信息
opencode doctor > diagnosis.txt
opencode status > status.txt
opencode logs --level error > errors.txt

# 压缩打包
tar -czf opencode-debug.tar.gz diagnosis.txt status.txt errors.txt

高级技巧

1. 自定义诊断脚本

bash

#!/bin/bash
# my-diagnostic.sh

echo "=== OpenCode 自定义诊断 ==="
echo ""

echo "1. 配置检查"
opencode validate AGENTS.md
echo ""

echo "2. 网络检查"
ping -c 3 api.opencode.ai
echo ""

echo "3. LSP 状态"
opencode lsp status
echo ""

echo "4. 缓存统计"
opencode cache stats
echo ""

echo "5. 最近错误"
opencode logs --level error --tail 10

2. 监控模式

bash

# 实时监控日志
opencode logs --follow

# 监控特定类型
opencode logs --follow --filter "error"

3. 性能分析

bash

# 分析慢查询
opencode logs --filter "slow"

# 分析 Token 使用
opencode token-usage --history

# 生成性能报告
opencode performance-report

获取帮助

文档资源

社区支持

GitHub Issues: https://github.com/opencode/opencode/issues
Discord 社区: https://discord.gg/opencode
邮件支持: support@opencode.ai

联系支持

如果问题无法通过上述方法解决：

bash

# 生成支持请求包
opencode support package --email your@email.com

本课小结

你学会了：

OpenCode 的诊断工具使用方法
常见问题的排查流程
如何分析错误日志
性能问题的诊断和优化
问题记录和寻求帮助的技巧

阶段总结

恭喜！你完成了 5-advanced 进阶手册 的所有课程。

你现在已经掌握：

📚 已学模块

✅ 5.17 内置工具 - 掌握所有工具的使用
✅ 5.18 代码格式化器 - 统一代码风格
✅ 5.19 LSP 服务器 - 智能代码分析
✅ 5.20 上下文压缩 - 优化 Token 使用
✅ 5.21 思考深度 - 平衡速度与质量
✅ 5.22 调试与诊断 - 解决各种问题

🎯 你的能力

深度定制 OpenCode 配置
开发自定义 Agent 和 Skill
优化性能和资源使用
独立排查和解决问题
充分利用 OpenCode 的所有能力

📖 继续学习

🎉 恭喜你完成了进阶手册！现在你已经是 OpenCode 高级用户了！

📚 更多完整模板：Prompt 模板库

5.22 调试与诊断 ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

核心思路 ​

调试方法论 ​

问题类型 ​

诊断工具 ​

1. 日志系统 ​

2. 诊断命令 ​

3. 状态检查 ​

常见问题诊断 ​

问题 1: 配置文件错误 ​

问题 2: API 连接失败 ​

问题 3: 权限问题 ​

问题 4: LSP 工作异常 ​

问题 5: 性能问题 ​

问题 6: Token 超限 ​

跟我做 ​

实战 1: 诊断配置问题 ​

实战 2: 诊断网络问题 ​

实战 3: 诊断性能问题 ​

📋 诊断流程图 ​

检查点 ✅ ​

踩坑提醒 ​

最佳实践 ​

1. 定期检查 ​

2. 保留关键日志 ​

3. 问题记录模板 ​

4. 寻求帮助前 ​

高级技巧 ​

1. 自定义诊断脚本 ​

2. 监控模式 ​

3. 性能分析 ​

获取帮助 ​

文档资源 ​

社区支持 ​

联系支持 ​

本课小结 ​

阶段总结 ​

📚 已学模块 ​

🎯 你的能力 ​

📖 继续学习 ​

5.22 调试与诊断

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

调试方法论

问题类型

诊断工具

1. 日志系统

2. 诊断命令

3. 状态检查

常见问题诊断

问题 1: 配置文件错误

问题 2: API 连接失败

问题 3: 权限问题

问题 4: LSP 工作异常

问题 5: 性能问题

问题 6: Token 超限

跟我做

实战 1: 诊断配置问题

实战 2: 诊断网络问题

实战 3: 诊断性能问题

📋 诊断流程图

检查点 ✅

踩坑提醒

最佳实践

1. 定期检查

2. 保留关键日志

3. 问题记录模板

4. 寻求帮助前

高级技巧

1. 自定义诊断脚本

2. 监控模式

3. 性能分析

获取帮助

文档资源

社区支持

联系支持

本课小结

阶段总结

📚 已学模块

🎯 你的能力

📖 继续学习