OpenClaw Network Diagnostics

Overview

Run a pure network diagnostic worker from CLI to continuously monitor connectivity between:

1. OpenClaw runtime host
Telegram Bot API (api.telegram.org)
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)
INLINECODE3: complete example configuration
INLINECODE4: sample structured JSON logs
INLINECODE5: integration patterns with pros/cons
INLINECODE6: workflow for later AI-based log analysis

Prerequisites

Install and verify:

1. Python INLINECODE7
macOS networking tools: dig, ping, INLINECODE10
Telegram bot token and personal chat id

Install

From skill root:

CODEBLOCK0

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

CODEBLOCK1

Then edit config.json:

- INLINECODE12
INLINECODE13

Run Model

Foreground mode (manual stop via Ctrl+C)

CODEBLOCK2

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)

CODEBLOCK3

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).
Send Bot API probe (getMe) and measure round-trip latency.
Run delivery verification cycle (sendMessage + selected ack mode).
Run packet-loss probe (ping) and log packet loss indicators.
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. INLINECODE26

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

3. INLINECODE28

- 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.
INLINECODE29/callback_ack are practical approximations.

Default Tuning (Recommended)

- timeouts_ms.connect: INLINECODE32
INLINECODE33: INLINECODE34
INLINECODE35: INLINECODE36
INLINECODE37: INLINECODE38
INLINECODE39: INLINECODE40

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: INLINECODE41
total cap: logging.max_total_size_mb (set 500 for your requirement)

Sensitive data handling:

- enable/disable redaction via INLINECODE44

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
Prints summary JSON to stdout
Saves summary JSON to INLINECODE48

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 INLINECODE50
Compute quick counters locally
Feed focused window + summary into ChatGPT Codex with structured prompts
Ask for timeline, root-cause segmentation, anomaly clusters, and config recommendations

OpenClaw 网络诊断

概述

通过命令行运行纯网络诊断工作进程，持续监控以下连接：

1. OpenClaw 运行时主机
Telegram Bot API (api.telegram.org)
通过投递验证周期模拟个人 Telegram 客户端

保持诊断与 OpenClaw LLM 流程隔离：

- 不调用任何 LLM。
不消耗 AI Token。
在独立的异步工作循环中运行。

技能文件

- scripts/netdiag.py：独立的 CLI 工作进程（run/start/stop/status/validate-config）
references/config.example.json：完整示例配置
references/example-log-entries.jsonl：示例结构化 JSON 日志
references/openclaw-integration.md：集成模式及其优缺点
references/ai-log-analysis.md：后续基于 AI 的日志分析工作流程

前置条件

安装并验证：

1. Python 3.11+
macOS 网络工具：dig、ping、traceroute
Telegram 机器人令牌和个人聊天 ID

安装

从技能根目录执行：

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

根据示例创建真实配置文件并设置真实凭据：

bash
cp references/config.example.json config.json

然后编辑 config.json：

- telegram.bottoken
telegram.personalchat_id

运行模式

前台模式（通过 Ctrl+C 手动停止）

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

行为：

- 从 CLI 手动启动。
持续运行直至手动停止。
停止时向标准输出打印 JSON 摘要。
将摘要保存到 logging.summaryfilepath。

后台模式（非阻塞服务）

bash
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

使用此模式以避免阻塞 OpenClaw 主线程。

监控行为

每 intervals_sec.ping（默认 30s）执行一次活跃周期：

1. 使用 TTL 快照解析 DNS（系统 + 公共解析器）。
发送 Bot API 探测（getMe）并测量往返延迟。
运行投递验证周期（sendMessage + 选定确认模式）。
运行丢包探测（ping）并记录丢包指标。
更新中断/恢复和异常计数器。

额外周期性诊断：

- 路由追踪（intervalssec.traceroute）
通过 DF ping 二分搜索进行 MTU 发现（intervalssec.mtutest）
DNS 重新解析（intervalssec.dns_reresolve）

投递验证模式

设置 delivery_verification.mode：

1. botapiack（默认）

- 仅确认 Bot API 接受（sendMessage 成功）。
开销最低。
不证明手机端显示/阅读。

2. userreplyack

- 通过 getUpdates 等待用户回复。
更好地近似消息已到达客户端且用户已交互。
需要手动交互。

3. callback_ack

- 发送内联按钮并等待回调查询。
结构化确认事件。
需要点击按钮。

阅读确认说明：

- Telegram Bot API 不暴露机器人消息的直接已读回执。
userreplyack/callback_ack 是实用的近似方案。

默认调优（推荐）

- timeoutsms.connect：4000
timeoutsms.request：10000
retry.maxretries：2
retry.backoffbasems：500
diagnostics.latencyanomalythresholdms：1200

理由：

- 捕获瞬时故障而不隐藏持续性中断。
在限流/速率限制事件期间限制重试风暴风险。

日志模型

将 JSON 行写入轮转文件，并设置总预算上限。

每条记录包含必填字段：

- 毫秒级 UTC 时间戳
源/目标 IP + 端口
DNS 结果快照（含 TTL）
TLS 元数据（版本、密码套件、握手持续时间、会话复用启发式）
HTTP 请求/响应头和状态码
发送/接收的负载字节数
往返延迟
TCP 状态
重试/超时/套接字错误
丢包指标（执行探测时）
连接重置标志
限流元数据
异常堆栈跟踪

日志轮转：

- 每文件大小：logging.maxfilesizemb
总上限：logging.maxtotalsizemb（根据需求设置为 500）

敏感数据处理：

- 通过 logging.redactsensitivefields 启用/禁用脱敏

OpenClaw 集成选项

选项 A：外部进程（推荐）

使用 OpenClaw 任务钩子中的 start/stop/status 命令。

优点：

- 与 OpenClaw 运行时强隔离
设计上非阻塞
独立的重启和故障边界

缺点：

- 需要 PID 文件生命周期管理

选项 B：进程内任务

在 OpenClaw 循环内导入并运行工作进程。

优点：

- 单进程部署

缺点：

- 故障可能影响 OpenClaw 主运行时
对网络密集型诊断的隔离性较弱

生产监控默认使用选项 A。

停止与摘要

手动停止时（SIGINT/SIGTERM），工作进程将：

1. 刷新最终指标
向标准输出打印 JSON 摘要
将 JSON 摘要保存到 logging.summaryfilepath

摘要字段：

- 总运行时间
总 Ping 次数
失败 Ping 次数
平均延迟
最大延迟
连接断开次数
检测到的 DNS 变化
检测到的 MTU 变化
异常计数

后续使用 AI 工具分析日志

使用 references/ai-log-analysis.md。

推荐流程：

1. 从 logs/netdiag.jsonl 截取事件窗口
本地计算快速计数器
将聚焦窗口 + 摘要输入带有结构化提示的 ChatGPT Codex
请求时间线、根因分段、异常聚类和配置建议

openclaw-network-diagnosticsOpenClaw网络诊断