Config Diagnose

智能配置诊断工具，帮助排查配置问题、环境变量、服务状态、文件搜索等。触发词：为什么不能、找不到配置、排查问题、诊断一下。

Security Scan

Skill mostly does what it claims (diagnose configs, env vars, services, files) but includes behaviors that could expose sensitive data and can be integrated into a persistent heartbeat — review before enabling or giving it broad access.

Purpose & Capability

Name/description match the implemented functionality: scripts check env vars, service ports, files, OpenClaw workspace and generate reports. However the scripts probe many API-related env vars (OPENAI_API_KEY, ANTHROPIC_API_KEY, BAIDU_API_KEY, GOOGLE_API_KEY, GITHUB_TOKEN) and print partial key prefixes, which is consistent with an "API diagnosis" feature but is sensitive and worth noting.

Instruction Scope

SKILL.md explicitly directs the agent to run the provided shell scripts and also suggests integrating with heartbeat (active monitoring). The scripts read system state under /root (directories, memory files, openclaw.json), enumerate installed skills, run network checks (ping, nc), run lsof/pgrep/ps/find/df. These are in-scope for diagnostics but they touch sensitive areas (/root, workspace, memory files) and the instructions encourage adding proactive checks to HEARTBEAT.md, which increases runtime scope.

Install Mechanism

No install spec (instruction-only skill with bundled scripts). No external downloads or package installs. Risk from install mechanism is low.

Credentials

The skill requires no declared env vars but reads many environment variables at runtime and prints them (for APIs it prints first 10 chars). Accessing and echoing API keys, EMAIL_PASSWORD, and other secrets is proportionate to "diagnose config" but increases exposure risk — especially if diagnostic output is logged, stored, or transmitted. The skill also examines files under /root/.openclaw and workspace which may contain credentials or private data.

Persistence & Privilege

always:false and agent invocation is normal. However SKILL.md describes an optional "主动监控" mode and provides a heartbeat-check script; if users integrate that into a scheduler or HEARTBEAT.md, the skill can become a periodic checker that actively notifies. That is not automatic here, but it is easy to enable and increases blast radius if enabled with high privileges.

What to consider before installing

This skill is internally consistent with a configuration-diagnostic tool, but review before enabling widely: 1) The scripts read /root and OpenClaw workspace paths — they list directories and check for files that may contain sensitive data. 2) The API/email checks print partial API keys and mention EMAIL_PASSWORD; if diagnostic output is logged, sent to external services, or visible to other users, secrets could be exposed. 3) The SKILL.md suggests adding a heartbeat/active monitoring mode — enabling that makes the skill run periodically and increases risk. Recommended actions: inspect the scripts locally, run them in an isolated environment (or with a non-privileged account), disable or do not integrate the heartbeat if you don't want periodic checks, and avoid sending diagnostic output to third-party endpoints or logs that are shared. If you need clearer behavior (e.g., skip printing key prefixes, limit search paths, or avoid /root), request those specific changes from the author before installing.

🔍 配置诊断 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="[e-mail]"
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