Openclaw Network Diagnostics

Standalone advanced network diagnostics for OpenClaw to continuously test end-to-end connectivity from OpenClaw agent to Telegram Bot API and approximate del...

Security Scan

The skill's code and instructions are coherent with its stated purpose (continuous network diagnostics against Telegram Bot API); nothing in the package demands unrelated credentials or privileged system changes, but you should review config/log handling and run it isolated until you confirm behavior.

Purpose & Capability

Name/description match the files and runtime instructions: the worker probes DNS, ICMP, traceroute, MTU, and exercises the Telegram Bot API for delivery verification. Required artifacts (bot token, personal chat id) are consistent with the stated functionality and no unrelated cloud credentials or system-wide accesses are requested.

Instruction Scope

SKILL.md stays focused on diagnostics and gives explicit CLI commands and background/foreground modes. It recommends both external-process and in-process integration; the latter is explicitly flagged as higher-risk. Attention: the workflow and references encourage later AI-based log analysis and may involve sharing log slices externally — ensure tokens/PII are redacted before exporting logs.

Install Mechanism

No install spec is provided (instruction-only), so nothing is fetched or executed at install time. The runtime requires Python 3.11+ and common networking tools (dig/ping/traceroute) which are proportional to the task.

Credentials

The skill does not ask for unrelated environment credentials in registry metadata. It expects a config file containing a Telegram bot token and personal chat id (or NETDIAG_CONFIG can point to a config), which is appropriate. Be aware the tool writes detailed JSON logs that could include sensitive headers or tokens if redaction is disabled; default config sets redaction=true, but you should verify it's enabled.

Persistence & Privilege

The skill is not always-enabled and is user-invocable. It runs as a long-running process (writes PID file, logs) which is normal for a monitoring worker. The in-process integration option is documented and acknowledged to be riskier; prefer the external-process option to maintain isolation.

Assessment

This package appears to do what it says, but take these precautions before deploying: (1) Review the full scripts/netdiag.py source yourself (or have someone you trust) to confirm there are no unexpected network endpoints or hidden behaviors. (2) Keep your Telegram bot token and personal chat id out of world-readable locations; prefer a restricted config file and OS-level secret storage. (3) Ensure logging.redact_sensitive_fields is true before running; if you must share logs externally (AI analysis, etc.), mask tokens and PII first. (4) Run the worker as an external background process (the SKILL.md recommendation) rather than in-process to avoid impacting OpenClaw runtime. (5) Start in a sandboxed host or staging environment to observe actual network traffic and any subprocess invocation (ping/traceroute/dig) before deploying to production. (6) If you supply a proxy_url or NETDIAG_CONFIG via environment, double-check those values to prevent accidental routing of telemetry to an unintended server.

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)

• Confirm only Bot API acceptance (sendMessage success).
• Lowest overhead.
• Does not prove handset render/read.

2. user_reply_ack

• Wait for user reply via getUpdates.
• Better approximation of “message reached client and user interacted”.
• Requires manual interaction.

3. callback_ack

• Send inline button and wait callback query.
• Structured acknowledgement event.
• 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.

Default Tuning (Recommended)

• 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

Option A: External process (recommended)

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