什么是 根因追踪？

根因追踪技能是一个强大的分析框架，旨在帮助 AI 代理看透表象症状，揭示 Bug 和系统故障的潜在驱动因素。通过实施 5 Whys 和故障树分析等结构化方法，它为解决复杂的技术债务和重复发生的事件提供了逻辑清晰且可重复的路径。该技能确保开发人员不仅仅是修补症状，而是根据经验证的证据实施永久性修复。

无论是处理 API 超时、身份验证循环还是基础设施瓶颈，该技能都能无缝集成到开发工作流中以提供深刻见解。通过利用 Openclaw Skills 进行根因分析，团队可以显著缩短平均恢复时间 (MTTR)，并通过数据驱动的事后分析和预防性对策提高系统稳定性。

下载入口:https://github.com/openclaw/skills/tree/main/skills/sa9saq/root-cause-tracing

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

根因追踪 应用场景

• 通过深入分析数据库和网络层来诊断间歇性 API 超时的来源。
• 通过映射微服务和外部提供商之间的依赖关系来解决身份验证失败问题。
• 通过追踪 Gas 消耗、Nonce 冲突和智能合约逻辑来分析区块链交易还原。
• 使用自动化版本控制追踪识别大型代码库中的回归起源。
• 执行事故后报告，为生产环境制定长期预防策略。

1. 症状记录：该技能记录错误消息、发生频率和特定的环境条件。
2. 假设生成：使用 5 Whys 深入研究逻辑，或使用故障树分析映射出所有可能的故障路径。
3. 证据收集：分析跨多个来源（应用、系统、网络）的日志，并追踪代码依赖项或堆栈跟踪。
4. 验证：运行重现测试或临时修复以验证假设的根本原因。
5. 报告：生成结构化的根因分析报告，包含即时修复和永久预防步骤。

根因追踪 配置指南

当检测到“root cause”或“why”等关键词时，该技能会在环境中自动触发。为确保完整功能，代理需要访问系统日志和 Git 仓库。您可以使用标准 CLI 命令测试基于日志的追踪：

# 分析错误周围的日志
grep -B30 -A10 "ERROR" app.log

# 按特定时间戳过滤日志
grep "2026-02-02 12:3" app.log

对于回归追踪，该技能利用 git bisect：

git bisect start
git bisect bad HEAD
git bisect good 

根因追踪 数据架构与分类体系

该技能将其发现组织成结构化的诊断报告，以确保清晰度和可操作性。

name: root-cause-tracing
description: Root cause analysis using 5 Whys, fault tree, and dependency tracing. Find the real source of problems.
auto_trigger: true
trigger:
  keyword: 原因|なぜ|root cause|why|どこから

Root Cause Tracing Skill

根本原因追跡スキル。5 Whys、フォールトツリー、依存関係追跡で真の原因を特定。

分析手法

1. 5 Whys分析

手法:
  「なぜ？」を5回繰り返して根本原因に到達

例:
  問題: APIがタイムアウトする

  Why 1: なぜタイムアウト？
    → データベースクエリが遅い

  Why 2: なぜクエリが遅い？
    → フルテーブルスキャンしている

  Why 3: なぜフルスキャン？
    → インデックスがない

  Why 4: なぜインデックスがない？
    → マイグレーションで追加し忘れた

  Why 5: なぜ追加し忘れた？
    → レビューチェックリストになかった

  根本原因: レビュープロセスの欠陥
  対策: チェックリストにインデックス確認を追加

2. フォールトツリー分析

手法:
  問題をトップダウンで分解し、可能な原因を網羅的に列挙

記法:
  [TOP] 問題
    ├── [OR] 原因A または
    │   ├── [AND] A-1 かつ
    │   └── [AND] A-2
    └── [OR] 原因B または
        └── 原因B-1

例:
  [TOP] ログインできない
    ├── [OR] 認証失敗
    │   ├── [AND] パスワード間違い
    │   └── [AND] ユーザー存在しない
    ├── [OR] ネットワーク問題
    │   └── APIサーバーダウン
    └── [OR] クライアント問題
        └── Cookie無効

3. 依存関係追跡

手法:
  エラーの発生箇所から依存関係を遡る

フロー:
  エラー発生箇所
      ↓
  呼び出し元を特定
      ↓
  その呼び出し元を特定
      ↓
  ...
      ↓
  根本原因に到達

ツール:
  - スタックトレース分析
  - コールグラフ生成
  - ログのタイムライン分析

追跡プロセス

問題発生
    ↓
1. 症状の記録
   - エラーメッセージ
   - 発生条件
   - 発生頻度
    ↓
2. 仮説生成
   - 5 Whys で深掘り
   - フォールトツリーで網羅
    ↓
3. 証拠収集
   - ログ分析
   - コード追跡
   - 依存関係確認
    ↓
4. 仮説検証
   - 再現テスト
   - 修正→再テスト
    ↓
5. 根本原因確定
   - 文書化
   - 再発防止策

ログ分析テクニック

タイムライン分析

手順:
  1. エラー発生時刻を特定
  2. その前後のログを収集
  3. 時系列で並べて異常を発見

コマンド例:
  # エラー前後30行
  grep -B30 -A10 "ERROR" app.log

  # 特定時刻のログ
  grep "2026-02-02 12:3" app.log

相関分析

手順:
  1. 複数のログソースを収集
  2. 同一タイムスタンプでマッチング
  3. 因果関係を特定

対象:
  - アプリケーションログ
  - システムログ
  - ネットワークログ
  - データベースログ

コード追跡テクニック

スタックトレース分析

読み方:
  1. 最下部 = 直接の原因
  2. 上に遡る = 呼び出し元
  3. 境界を見る = 外部ライブラリ/自コード

注目点:
  - 自分のコードで最初に現れる行
  - 例外がthrowされた箇所
  - 予期しない値が渡された箇所

Git Bisect

手法:
  動作していたコミットと壊れたコミットの間を二分探索

コマンド:
  git bisect start
  git bisect bad HEAD
  git bisect good <動作していたコミット>
  # テスト → good/bad を繰り返し
  git bisect reset

{AGENT_NAME}固有の追跡

API関連

追跡ポイント:
  - Cloudflare Workersのログ
  - AI Gatewayのログ
  - ブラウザコンテナのログ

よくある原因:
  - CF Access認証失敗
  - APIキー期限切れ
  - レート制限

暗号資産関連

追跡ポイント:
  - トランザクションハッシュ
  - ブロックチェーンエクスプローラー
  - ガス代の状態

よくある原因:
  - 残高不足
  - ガス代不足
  - Nonce競合
  - コントラクトリバート

出力フォーマット

根本原因分析レポート:

問題:
  [問題の簡潔な説明]

症状:
  - [症状1]
  - [症状2]

5 Whys分析:
  1. なぜ？ → [回答1]
  2. なぜ？ → [回答2]
  3. なぜ？ → [回答3]
  4. なぜ？ → [回答4]
  5. なぜ？ → [回答5]

根本原因:
  [特定された根本原因]

証拠:
  - [証拠1: ログ/コード/テスト結果]
  - [証拠2]

対策:
  即時: [すぐに行う修正]
  恒久: [再発防止策]

使用例

「なぜエラーが出る？」→ 5 Whys分析開始
「原因を追跡して」→ 依存関係追跡
「どこから問題が？」→ フォールトツリー分析

連携スキル

更新履歴

[2026-02-02] 初期作成