Session Lifecycle and End-to-End Execution Flow

NetClaw's operation unfolds across four distinct stages: two one-time setup phases, a per-session context-loading step, and a per-task execution loop. The setup phases stand up the agent and its domain knowledge; runtime context loading rebuilds NetClaw's working memory at the start of every conversation; and the execution loop turns a plain-language request into device queries, structured data, severity-rated findings, and durable artifacts. This section traces that path end to end, using an interface-status check as the worked example, then generalizes it to OSI-layer troubleshooting and fleet-wide parallel queries.

Two Setup Phases and Runtime Context Loading

NetClaw is bootstrapped in two ordered phases. Phase 1 — OpenClaw onboarding runs the integrated openclaw onboard wizard, which configures the AI provider (Anthropic, OpenAI, Bedrock, Vertex, and 30+ options), the gateway (local mode, authentication, port binding), channel connectivity (Slack, Discord, Telegram, WhatsApp, etc.), and installs the background daemon service. Phase 2 — NetClaw platform setup runs ./scripts/setup.sh for domain-specific configuration: editing the pyATS testbed.yaml device inventory, entering platform credentials tailored to the installed components, and capturing user identity (name, role, timezone) that feeds USER.md.

Once set up, every session begins with runtime context loading. OpenClaw injects the workspace's six markdown files into the system prompt under a "Project Context" heading, each capped at 20,000 characters. This is how NetClaw "remembers" who it is and what it manages without any fine-tuning.

Sub-agents spawned for parallel work receive only AGENTS.md and TOOLS.md — enough operating discipline and infrastructure grounding to act, without the full personality and user context the primary session carries.

flowchart TD
    P1["Phase 1: OpenClaw onboarding (provider, gateway, channels, daemon)"]
    P2["Phase 2: NetClaw setup (testbed.yaml, credentials, USER.md)"]
    CTX["Runtime context loading (inject six markdown files each session)"]
    LOOP["Per-task execution loop (receive, plan, call tools, aggregate, respond)"]
    OUT["Severity-rated report and artifacts"]

    P1 --> P2
    P2 --> CTX
    CTX --> LOOP
    LOOP --> OUT
    LOOP -.-> CTX

Worked Example: "Check interface status across the network"

When a user types "show me interface status on core-switch-1" into Slack, NetClaw runs its agent loop: receive request, plan (select a skill), call tools, aggregate results, respond. The plan resolves to the pyats-health-check skill, which drives the pyATS MCP tools through scripts/mcp-call.py using JSON-RPC 2.0 over stdio.

sequenceDiagram
    participant UI as "Slack UI"
    participant Agent as "NetClaw Agent"
    participant Skill as "Skill"
    participant MCP as "pyATS MCP"
    participant Device as "Device"
    participant Genie as "Genie"

    UI->>Agent: "Check interface status on core-switch-1"
    Agent->>Skill: "Plan: select pyats-health-check"
    Skill->>MCP: "mcp-call.py (JSON-RPC 2.0 over stdio)"
    MCP->>Device: "Run show interfaces"
    Device-->>MCP: "Raw CLI output"
    MCP->>Genie: "Parse raw output"
    Genie-->>MCP: "Structured JSON"
    MCP-->>Skill: "Severity rating and NetBox reconcile"
    Skill-->>Agent: "GAIT audit: record turn to Git"
    Agent-->>UI: "Severity summary, Draw.io topology, ServiceNow incident"

UI (Slack)  "Check interface status on core-switch-1"
   |
   v
NetClaw agent  ── plan ──▶ select skill: pyats-health-check
   |
   v
Skill  ── scripts/mcp-call.py (JSON-RPC 2.0 / stdio) ──▶ pyats-network MCP
   |
   v
[1] Device query      run `show interfaces` on core-switch-1
[2] Genie parse       100+ IOS-XE parsers → structured JSON
[3] Severity rating   down = CRITICAL, err-disabled = WARNING, up = INFO
[4] NetBox reconcile  expected (source-of-truth) vs actual device state
[5] GAIT audit        record turn (prompt / response / artifacts) to Git
   |
   v
Response  ── aggregate, severity-sort ──▶
   • severity-rated summary
   • Draw.io topology (red/yellow/green)
   • ServiceNow incident (only if CRITICAL)

Steps 2–4 are the analytical core. Genie converts the raw show interfaces CLI text into an OS-agnostic Python dict (rendered as JSON) via schema-driven parsers — effectively giving the agent a REST-like structured response instead of fragile screen-scraping. The severity stage cross-references each interface against thresholds (a down interface is CRITICAL; err-disabled is WARNING). NetBox reconciliation then compares device reality against the source-of-truth intent, catching drift such as a missing expected uplink. Finally, GAIT records the entire interaction as an append-only Git commit at ~/.openclaw/n2n/gait/, so there is always an answer to "what did the AI do and why." All MCP responses are token-compressed with GCF (Graph Compact Format) for 55–83% savings on graph-shaped network data.

OSI-Layer Troubleshooting and Fleet-Wide Parallel Queries

When the symptom is a fault rather than a status check, NetClaw's pyats-troubleshoot skill applies a structured OSI-layer methodology across four symptom types:

• Connectivity loss — walk Layer 1 (interface up), Layer 2 (MAC reachability), Layer 3 (routing table, next-hop).
• Adjacency down — inspect protocol neighbor state (BGP, OSPF) and keepalive timing.
• Slow performance — separate latency (path length), loss (CRC errors, tail drops), and jitter (queue depth).
• Interface flapping — check threshold crossings (speed/duplex mismatch) and device resource exhaustion (CPU, memory).

This mirrors the classic bottom-up (start at L1, best for physical symptoms), top-down (start at L7, best for app errors on stable networks), and divide-and-conquer (test L3/L4 first, then move up or down) strategies — run one or two focused checks per layer, then deliberately move.

For anything touching more than one device, NetClaw uses fleet-wide pCall: queries are grouped by device role or site and executed simultaneously. The design goals are failure isolation (one device's timeout does not block the others), severity-sorted result aggregation, and clean scaling from 1 to 50+ devices. A single "across the network" request thus becomes many concurrent device sessions whose parsed results converge into one consolidated view.

Outputs: Severity Summaries and Artifacts

Every task terminates in a severity-rated consolidated report. Findings are consolidated by priority: CRITICAL (immediate action) outranks WARNING (monitor), which outranks INFO (documented). That ranking drives the artifacts NetClaw emits:

• Severity summary — the primary channel reply, sorted CRITICAL → WARNING → INFO, with each finding tied to a device and interface.
• Draw.io topology diagram — a visual map color-coded to match severity: red for CRITICAL/down, yellow for WARNING/degraded, green for healthy.
• ServiceNow incident — created automatically only when a critical finding exists, so the operational ticketing system stays in sync with reality without noise from routine checks.

Because GAIT captured every turn along the way, the summary and its artifacts are fully reproducible and auditable after the fact — closing the loop from a plain-language request back to a governed, evidence-backed answer.

References