- name
- config-diagnose
- description
- 智能配置诊断工具，帮助排查配置问题、环境变量、服务状态、文件搜索等。触发词：为什么不能、找不到配置、排查问题、诊断一下。
- version
- 1.0.0
- metadata
- openclaw
- emoji
- 🔍
- category
- utility
- version
- 1.0.0
- author
- 小帽
🔍 配置诊断 Skill
一句话描述：当用户遇到「为什么不能」「找不到配置」「不工作」等问题时，自动诊断并给出解决建议。
🎯 设计思路
核心理念
用户问题描述 → 关键词识别 → 执行诊断 → 返回结果 + 建议诊断层级
L1: 快速检查（环境变量、文件存在性）
L2: 深度检查（网络连接、权限验证）
L3: 修复建议（具体操作步骤）🔧 诊断能力
| 诊断类型 | 检查项 | 触发关键词 |
|---|---|---|
| 邮件诊断 | EMAIL_* 环境变量、IMAP/SMTP 连接 | 邮件、邮箱、mail、email |
| API 诊断 | API Key 设置、连接测试、权限范围 | API、Key、Token、认证 |
| 服务诊断 | 端口占用、进程状态、配置文件 | 服务、端口、启动、运行 |
| 文件诊断 | 文件搜索、权限检查、格式验证 | 找不到、文件、not found |
| 技能诊断 | 技能安装、依赖检查、配置完整性 | 技能、skill、安装 |
📁 文件结构
config-diagnose/
├── SKILL.md # 本文件
├── scripts/
│ ├── diagnose.sh # 主诊断脚本
│ └── full-diagnose.sh # 完整系统诊断
└── templates/
└── report.md # 诊断报告模板💻 使用方法
命令行
# 邮件配置诊断
bash ~/.openclaw/workspace/skills/config-diagnose/scripts/diagnose.sh email
# API 配置诊断
bash ~/.openclaw/workspace/skills/config-diagnose/scripts/diagnose.sh api
# 服务状态诊断
bash ~/.openclaw/workspace/skills/config-diagnose/scripts/diagnose.sh service
# 文件搜索
bash ~/.openclaw/workspace/skills/config-diagnose/scripts/diagnose.sh file "token.json"
# 完整诊断
bash ~/.openclaw/workspace/skills/config-diagnose/scripts/full-diagnose.sh对话触发
用户：为什么我的邮件读取不了？
AI：让我诊断一下邮件配置...
[调用 diagnose.sh email]
结果：EMAIL_PASSWORD 未设置
建议：请设置应用专用密码...
用户：为什么找不到 outlook-cli 的 token.json？
AI：让我帮你搜索...
[调用 diagnose.sh file "token.json"]
结果：文件不存在
建议：需要先运行 outlook-cli login 进行授权🔄 诊断流程图
用户描述问题
│
▼
┌────────────────┐
│ 关键词识别 │
│ 确定诊断类型 │
└────────────────┘
│
▼
┌────────────────┐
│ 执行检查脚本 │
│ - 环境变量 │
│ - 文件搜索 │
│ - 网络测试 │
│ - 服务状态 │
└────────────────┘
│
▼
┌────────────────┐
│ 分析结果 │
│ 生成诊断报告 │
└────────────────┘
│
▼
┌────────────────┐
│ 提供解决建议 │
│ 可执行命令 │
└────────────────┘📋 常见问题诊断表
邮件问题
| 问题 | 诊断结果 | 解决建议 |
|---|---|---|
| EMAIL_ADDRESS 未设置 | ✗ 未设置 | export EMAIL_ADDRESS="your@email.com" |
| EMAIL_PASSWORD 未设置 | ✗ 未设置 | Gmail 需生成应用专用密码 |
| IMAP 连接失败 | ✗ 不可达 | 检查网络或服务器地址 |
服务问题
| 问题 | 诊断结果 | 解决建议 |
|---|---|---|
| 端口被占用 | ✓ 已使用 | kill $(lsof -t -i:PORT) |
| 服务未启动 | − 未启动 | npm start 或对应启动命令 |
| 配置文件缺失 | ✗ 缺失 | 检查配置路径或重新安装 |
文件问题
| 问题 | 诊断结果 | 解决建议 |
|---|---|---|
| 文件不存在 | 未找到文件 | 检查是否需要先安装/创建 |
| 权限不足 | Permission denied | chmod +x 或 sudo |
| 路径错误 | 路径不存在 | 检查拼写或使用 find 搜索 |
🎨 输出格式
成功
✓ 配置完整
✓ 服务运行中
✓ 文件存在警告
⚠ 未设置（使用默认值）
⚠ 服务未启动
⚠ 文件权限不完整错误
✗ 未设置（必须配置）
✗ 服务异常
✗ 文件缺失🔗 与其他 Skill 配合
| 配合技能 | 场景 |
|---|---|
openclaw-email | 诊断邮件配置后配置邮箱 |
deploy | 部署前诊断配置是否完整 |
healthcheck | 系统健康检查 + 配置诊断 |
clawhub | 诊断技能安装问题 |
📝 更新日志
v1.0.0 (2026-03-19)
- 初始版本
- 支持邮件、API、服务、文件、技能诊断
- 完整系统诊断功能
- 彩色输出和建议生成
🔄 触发模式
模式一：被动响应（默认）
用户提问时触发，不主动打扰。
用户：为什么我的邮件读取不了？
AI：让我诊断一下... [调用诊断]模式二：主动监控（集成 heartbeat）
在定时心跳检查中集成关键诊断，发现严重问题主动提醒。
检查项（仅关键问题）：
- Gateway 服务崩溃
- 核心配置文件丢失
- 关键端口服务停止
触发条件：
# 在 HEARTBEAT.md 中添加
- 检查 Gateway 状态
- 检查关键服务端口
- 发现问题 → 主动通知用户模式三：智能触发
根据上下文自动判断是否需要诊断。
用户：帮我发封邮件
AI：[检测到邮件配置问题]
⚠️ 检测到邮件配置不完整，让我先诊断一下...
[自动执行邮件诊断]📋 主动提醒的优先级
| 级别 | 问题类型 | 是否主动提醒 |
|---|---|---|
| 🔴 严重 | Gateway 崩溃、配置丢失 | ✅ 立即提醒 |
| 🟡 警告 | 服务端口停止、依赖缺失 | ✅ 定时提醒 |
| 🔵 信息 | 环境变量未设置 | ❌ 按需触发 |
🛠️ Heartbeat 集成示例
# 添加到 heartbeat 检查脚本
check_critical() {
# 检查 Gateway
if ! pgrep -f "openclaw gateway" >/dev/null; then
echo "🔴 严重：Gateway 服务已停止"
return 1
fi
# 检查配置文件
if [ ! -f "/root/.openclaw/openclaw.json" ]; then
echo "🔴 严重：配置文件丢失"
return 1
fi
return 0
}👤 作者
小帽 (OpenClaw)
📅 创建时间
2026-03-19
📜 许可证
MIT