The Layered Architecture at a Glance

NetClaw is organized as a five-layer stack that turns a natural-language request into an audited action against live network infrastructure. Each layer owns one concern and hands off to the next through explicit contracts, so interfaces, reasoning, tools, and backends can evolve independently.

flowchart TD
    L1["Layer 1: User Interface (Slack, WebEx, Web Chat, Voice)"]
    L2["Layer 2: Claude AI Agent + OpenClaw Framework"]
    L3["Layer 3: Skills (191 domain-automation routines)"]
    L4["Layer 4: MCP Servers (113 servers, JSON-RPC 2.0)"]
    L5["Layer 5: Backend Systems (devices, ITSM, cloud, telemetry)"]
    L1 -->|"natural-language message"| L2
    L2 -->|"selects a skill"| L3
    L3 -->|"invokes MCP tools"| L4
    L4 -->|"executes and parses to JSON"| L5
    L5 -.->|"structured JSON flows back up"| L1

┌─────────────────────────────────────────────────────────────┐
│ LAYER 1  User Interface   Slack · WebEx · Web Chat · Voice   │
├─────────────────────────────────────────────────────────────┤
│ LAYER 2  Claude AI Agent + OpenClaw Framework                │
├─────────────────────────────────────────────────────────────┤
│ LAYER 3  Skills           191 domain-automation routines     │
├─────────────────────────────────────────────────────────────┤
│ LAYER 4  MCP Servers      113 servers · JSON-RPC 2.0         │
├─────────────────────────────────────────────────────────────┤
│ LAYER 5  Backend Systems  devices · ITSM · cloud · telemetry │
└─────────────────────────────────────────────────────────────┘

Layer 1 — User Interface

The top layer is the input/output boundary. Users speak to NetClaw in natural language across four channels: Slack (bidirectional over WebSocket), Cisco WebEx (adaptive cards with interactive buttons), a Web Chat surface backed by a Three.js 3D operations dashboard, and Voice via Twilio for phone interactions. The layer accepts free-form queries and returns structured responses with embedded visualizations. It knows nothing about how a request is fulfilled; its only contract with the layer below is "carry this message in, carry a formatted answer out." That isolation means a new channel can be added without touching reasoning or tooling.

Layer 2 — Claude AI Agent and the OpenClaw Framework

The decision-making layer runs on Anthropic's Claude Agent SDK, with the OpenClaw framework supplying the runtime around it. OpenClaw handles session management and persistent context, gateway authentication and channel routing, file-based daily logs, and MemPalace semantic memory. At session start it loads a set of workspace files — SOUL.md, AGENTS.md, IDENTITY.md, USER.md, and TOOLS.md — and injects them "under 'Project Context' in the system prompt." This is where NetClaw decides what to do: it interprets the user's intent, selects the appropriate skill, and later composes the final report. It does not itself call device APIs; it reasons and delegates downward.

Layer 3 — Skills

Skills are the orchestration layer: 191 domain-automation routines that encode network-engineering procedure and drive the layers beneath them. Representative examples include pyats-health-check (an "8-step health procedure with threshold tables and severity ratings"), netbox-reconcile (detects "7 discrepancy types" between NetBox intent and device reality), fmc-firewall-ops, meraki-network-ops (roughly 804 API endpoints), and grafana-observability (75+ tools). Skills convert a high-level goal into an ordered sequence of tool calls, apply ServiceNow CR gating before any destructive change, write GAIT Git-based audit trails, and emit "severity-rated consolidated reports." The skill decides how a task is carried out; the agent above chose which skill.

Layer 4 — MCP Servers

Below skills sit 113 Model Context Protocol (MCP) servers, each a thin, typed wrapper that exposes one vendor or platform API as callable tools. MCP standardizes this integration as JSON-RPC 2.0 messages, so a skill invokes any backend the same way regardless of vendor. NetClaw uses four transport styles:

stdio (Python/Node)   local subprocess   pyATS · NetBox · Juniper JunOS
Docker                containerized      GitHub
HTTP (remote)         cloud endpoint     Grafana (uvx) · Kubeshark :8898
FastMCP               streamable HTTP    HumanRail :8100 · Meraki Magic

Servers are grouped by domain — device automation (pyATS, JunOS, F5, Catalyst Center, Arista CVP), infrastructure sources of truth (NetBox, Nautobot, Infrahub), security (ISE, FMC, Check Point, NSO), cloud (AWS, GCP, Azure, Cloudflare), and observability (Grafana, Prometheus, Kubeshark, SuzieQ). The MCP layer is the choke point for authentication, execution, and — critically — turning raw device output into structured JSON.

Layer 5 — Backend Systems

The bottom layer is everything real: live network devices (IOS-XE/NX-OS/IOS-XR, Juniper, Arista, F5, Aruba), ITSM platforms (ServiceNow incidents, changes, CMDB), cloud providers (AWS, Azure, GCP), observability stacks (Grafana, Prometheus, Datadog, Splunk), telemetry feeds (gNMI streams, NetFlow/IPFIX, SNMP traps, syslog), and version control (GitHub, GitLab). The LLM is never exposed to this layer directly; it reaches production systems only through the validated, audited MCP tools above it.

How the Layers Hand Off

Each boundary is a defined contract. The UI passes a natural-language string to the agent; the agent selects a skill; the skill invokes MCP tools; MCP servers execute JSON-RPC 2.0 calls over stdio against backends and parse the responses back into structured JSON that flows up the stack. A worked example — an interface health check — shows the full round trip:

sequenceDiagram
    participant U as "User (Slack)"
    participant A as "OpenClaw Gateway + Claude Agent"
    participant S as "Skill (pyats-health-check)"
    participant M as "MCP: pyATS (stdio)"
    participant D as "Device (router-1)"
    U->>A: "Check interface health on router-1"
    A->>S: "selects pyats-health-check"
    S->>M: "JSON-RPC 2.0: show_command (show interfaces)"
    M->>D: "raw CLI command"
    D-->>M: "raw CLI text"
    M-->>S: "structured JSON via Genie parser"
    S-->>A: "GCF-encoded data + GAIT audit + ServiceNow CR"
    A-->>U: "Interface Gi0/0: UP (98.2% uptime)"

User (Slack): "Check interface health on router-1"
  → OpenClaw Gateway + Claude Agent      selects pyats-health-check
  → Skill (pyats-health-check)           begins 8-step procedure
  → MCP: pyATS (stdio)                   JSON-RPC 2.0: show_command("show interfaces")
  → Device (router-1)                    raw CLI text
  → MCP: pyATS (Genie parser)            structured JSON {interfaces, status, ...}
  → Skill (GCF encoding)                 55–83% token savings via Graph Compact Format
  → MCP: GAIT + ServiceNow               audit commit + CR if degraded
  → Claude Agent                         markdown report with severity ratings
  → Slack: "Interface Gi0/0: UP (98.2% uptime) ✓"

Two mechanisms make the handoffs efficient and safe. First, JSON-RPC 2.0 over stdio is the uniform tool-call contract between skills and MCP servers: the client launches the server as a subprocess and exchanges typed requests and responses, giving a strong security boundary with no network exposure for local tools. Second, the Graph Compact Format (GCF) compresses MCP responses on the way up, achieving 55–83% token savings on network data, rising to 91% by the third call through session deduplication and up to 99% on re-queries via delta encoding (tunable through NETCLAW_GCF_MODE: full, graph, generic, or off). The pyATS server also illustrates the transformation each MCP layer performs — its Genie parsers convert unstructured CLI text into machine-readable JSON, so the skill and agent above reason over data instead of screen-scraped strings. The result is a stack where reasoning, procedure, integration, and infrastructure each change independently, while every action leaves an audited trail.

References