SkillHub

openclaw-network-diagnostics

v0.1.1

Standalone advanced network diagnostics for OpenClaw to continuously test end-to-end connectivity from OpenClaw agent to Telegram Bot API and approximate delivery to a personal Telegram client. Use when investigating latency spikes, packet loss, DPI/throttling/blocking suspicion, DNS instability, TL...

Sourced from ClawHub, Authored by h8kxrfp68z-lgtm

Installation

Please help me install the skill `openclaw-network-diagnostics` from SkillHub official store. npx skills add h8kxrfp68z-lgtm/openclaw-network-diagnostics

OpenClaw Network Diagnostics

Overview

Run a pure network diagnostic worker from CLI to continuously monitor connectivity between: 1. OpenClaw runtime host 2. Telegram Bot API (api.telegram.org) 3. Personal Telegram client approximation via delivery verification cycles

Keep diagnostics isolated from OpenClaw LLM flow: - Use no LLM calls. - Consume no AI tokens. - Run in independent async worker loops.

Skill Files

  • scripts/netdiag.py: standalone CLI worker (run/start/stop/status/validate-config)
  • references/config.example.json: complete example configuration
  • references/example-log-entries.jsonl: sample structured JSON logs
  • references/openclaw-integration.md: integration patterns with pros/cons
  • references/ai-log-analysis.md: workflow for later AI-based log analysis

Prerequisites

Install and verify: 1. Python 3.11+ 2. macOS networking tools: dig, ping, traceroute 3. Telegram bot token and personal chat id

Install

From skill root:

cd /Users/ivanbelugin/Documents/Connection Monitoring System/openclaw-network-diagnostics
python3 scripts/netdiag.py validate-config --config references/config.example.json

Create a real config file from the example and set real credentials:

cp references/config.example.json config.json

Then edit config.json: - telegram.bot_token - telegram.personal_chat_id

Run Model

Foreground mode (manual stop via Ctrl+C)

python3 scripts/netdiag.py run --config config.json --pid-file ./logs/netdiag.pid

Behavior: - Start manually from CLI. - Run continuously until manual stop. - Print JSON summary to stdout on stop. - Save summary to logging.summary_file_path.

Background mode (non-blocking service)

python3 scripts/netdiag.py start --config config.json --pid-file ./logs/netdiag.pid
python3 scripts/netdiag.py status --pid-file ./logs/netdiag.pid
python3 scripts/netdiag.py stop --pid-file ./logs/netdiag.pid

Use this mode to avoid blocking OpenClaw main thread.

Monitoring Behavior

Every intervals_sec.ping (default 30s) perform active cycle: 1. Resolve DNS with TTL snapshot (system + public resolvers). 2. Send Bot API probe (getMe) and measure round-trip latency. 3. Run delivery verification cycle (sendMessage + selected ack mode). 4. Run packet-loss probe (ping) and log packet loss indicators. 5. Update outage/recovery and anomaly counters.

Additional periodic diagnostics: - Traceroute (intervals_sec.traceroute) - MTU discovery via DF ping binary search (intervals_sec.mtu_test) - DNS re-resolution (intervals_sec.dns_reresolve)

Delivery Verification Modes

Set delivery_verification.mode:

  1. bot_api_ack (default)
  2. Confirm only Bot API acceptance (sendMessage success).
  3. Lowest overhead.

  4. Does not prove handset render/read.

  5. user_reply_ack

  6. Wait for user reply via getUpdates.
  7. Better approximation of “message reached client and user interacted”.

  8. Requires manual interaction.

  9. callback_ack

  10. Send inline button and wait callback query.
  11. Structured acknowledgement event.
  12. Requires button tap.

Read confirmation note: - Telegram Bot API does not expose direct read receipts for bot messages. - user_reply_ack/callback_ack are practical approximations.

  • timeouts_ms.connect: 4000
  • timeouts_ms.request: 10000
  • retry.max_retries: 2
  • retry.backoff_base_ms: 500
  • diagnostics.latency_anomaly_threshold_ms: 1200

Rationale: - Catch transient failures without hiding persistent outages. - Limit retry storm risk during throttling/rate-limit events.

Logging Model

Write JSON lines to rotating files with total budget cap.

Required fields are present in every record: - millisecond UTC timestamp - source/destination ip + ports - dns result snapshot (with TTL) - tls metadata (version, cipher, handshake duration, session reuse heuristic) - http request/response headers and status - payload bytes sent/received - round-trip latency - tcp state - retries/timeouts/socket errors - packet-loss indicator (when probe executed) - connection reset flag - rate-limit metadata - exception stacktrace

Log rotation: - per-file size: logging.max_file_size_mb - total cap: logging.max_total_size_mb (set 500 for your requirement)

Sensitive data handling: - enable/disable redaction via logging.redact_sensitive_fields

OpenClaw Integration Options

Use start/stop/status commands from OpenClaw task hooks.

Pros: - Strong isolation from OpenClaw runtime - Non-blocking by design - Independent restart and fault boundaries

Cons: - Requires pid-file lifecycle

Option B: In-process task

Import and run the worker inside OpenClaw loop.

Pros: - Single-process deployment

Cons: - Faults can impact OpenClaw main runtime - Weaker isolation for network-heavy diagnostics

Use Option A by default for production monitoring.

Stop and Summary

On manual stop (SIGINT/SIGTERM) the worker: 1. Flushes final metrics 2. Prints summary JSON to stdout 3. Saves summary JSON to logging.summary_file_path

Summary fields: - total runtime - total pings - failed pings - average latency - max latency - connection drops - dns changes detected - mtu changes detected - anomaly count

Analyze Logs Later with AI Tools

Use references/ai-log-analysis.md.

Recommended flow: 1. Slice incident window from logs/netdiag.jsonl 2. Compute quick counters locally 3. Feed focused window + summary into ChatGPT Codex with structured prompts 4. Ask for timeline, root-cause segmentation, anomaly clusters, and config recommendations