The OpenClaw Foundation and Agent Workspace Context

NetClaw is not a from-scratch agent. It is a domain-specific personality and toolset layered onto OpenClaw, a self-hosted open agent framework that supplies the plumbing every autonomous agent needs: session management, MCP (Model Context Protocol) server orchestration, channel integration, and persistent state tracking. Understanding NetClaw therefore begins with understanding two OpenClaw ideas. First, OpenClaw cleanly separates a communication and orchestration layer (the gateway) from a reasoning and action layer (the agent runtime). Second, OpenClaw programs the agent's behavior not through hard-coded logic but through a small set of Markdown context files that are injected into the model's system prompt at the start of every session. NetClaw is, in effect, "OpenClaw with a networking soul." This section walks through the runtime processes you actually launch, the six workspace files that define who NetClaw is, how those files reach the model, and the breadth of LLM providers OpenClaw can drive.

The OpenClaw Runtime: Gateway, TUI, and Onboarding

OpenClaw runs as a long-lived local process rather than a request-per-invocation script. In normal operation you run two processes in two terminals. The gateway is the control plane and de-facto message broker: it owns every channel connection (Slack, Discord, Teams, WebEx, Telegram, and browser clients), normalizes each inbound event into an internal envelope, routes it to the correct session and agent, and streams the reply back over the originating channel. The TUI is a local terminal chat client that connects to the gateway as just another channel, giving you direct chat, live tool-execution monitoring, and session inspection.

# Terminal 1 — start the control plane / message broker
openclaw gateway

# Terminal 2 — interactive terminal UI (chat + tool monitoring)
openclaw tui

flowchart LR
    CH["Channels: Slack, Discord, Teams, WebEx, Telegram"] --> GW["Gateway: control plane and message broker"]
    TUI["TUI: local terminal chat client"] --> GW
    GW --> RT["Agent runtime: reasoning and action"]
    RT --> GW
    GW --> CH

Setup is driven by two more commands. openclaw onboard runs an interactive wizard, and openclaw configure edits provider, gateway, and channel settings after the fact.

# First-run interactive setup wizard
openclaw onboard

# Re-run to change provider / gateway / channels later
openclaw configure

# Install ClawHub skills (e.g., computer-use)
openclaw skills install

Per the NetClaw README, the onboarding wizard has four steps: AI provider selection (Anthropic Claude is the recommended default), gateway configuration (local mode, authentication, port binding), channel connections (linking Slack, Discord, Telegram, WebEx, and Teams), and systemd daemon installation so the gateway runs as an auto-restarting user-level service. NetClaw's own ./scripts/setup.sh runs afterward to collect networking specifics — the testbed.yaml device inventory, platform credentials, and user identity written into USER.md.

The Six Workspace Context Files

The heart of NetClaw's behavior lives in six Markdown files stored alongside the gateway config (per the README, under ~/.openclaw/netclaw/). Each file is capped at 20,000 characters (20 KB); if a file exceeds that limit, OpenClaw truncates it with a warning. The files split cleanly into three groups: identity and expertise you should leave alone, personalization you are meant to edit, and machine-generated state.

This mapping reflects a well-established pattern in agent engineering: instruction/identity files (SOUL, AGENTS, IDENTITY) hold stable, prescriptive content, while personalization files (USER, TOOLS) carry the per-deployment context that makes the same agent useful on your network. SOUL.md functions as the agent's long-term identity and expertise, and AGENTS.md follows the increasingly common open convention of a "README for agents" — an operational, version-controllable rulebook distinct from a human-facing README. The README also documents two optional files: CLAUDE.md for Claude-specific prompt tuning, and TOOLS-REFERENCE.md, an auto-generated MCP tool reference produced by python3 scripts/inventory.py.

System-Prompt Injection Mechanics

Because modern LLMs are stateless, the system prompt is re-sent on every turn and outranks user text — so whatever OpenClaw injects there shapes behavior for the entire session. At session start OpenClaw reads the context files sequentially and concatenates them under a "Project Context" heading in the system prompt, before the user's message is processed. Per the README, the load order front-loads personality and expertise (IDENTITY and SOUL), then layers operating rules (AGENTS), user context (USER), and infrastructure notes (TOOLS). HEARTBEAT.md is not part of the per-turn prompt; it is consulted separately during periodic health cycles. In a federated "risk of NetClaws" deployment, sub-agents receive only AGENTS.md and TOOLS.md to keep context overhead low.

flowchart TD
    ID["IDENTITY.md: personality card"] --> PC["Project Context block"]
    SO["SOUL.md: expertise and rules"] --> PC
    AG["AGENTS.md: operating procedures"] --> PC
    US["USER.md: personalization"] --> PC
    TL["TOOLS.md: infrastructure notes"] --> PC
    PC --> SP["System prompt"]
    UM["User message"] --> SP
    SP --> LLM["Selected LLM provider"]
    HB["HEARTBEAT.md"] -.-> HC["Periodic health cycles"]

The end-to-end provider flow the README describes: openclaw configure stores provider credentials in ~/.openclaw/.env; at session start OpenClaw reads the chosen provider from ~/.openclaw/config.json, loads the API key from the environment, injects the context files into the system prompt, sends the combined prompt plus user message to the LLM, and streams the response back through the gateway. Figure 3.3 — End-to-end provider resolution flow at session start

flowchart TD
    CFG["openclaw configure stores credentials in .env"] --> START["Session start"]
    START --> PROV["Read provider from config.json"]
    PROV --> KEY["Load API key from environment"]
    KEY --> INJ["Inject context files into system prompt"]
    INJ --> SEND["Send prompt plus user message to LLM"]
    SEND --> STREAM["Stream response back through gateway"]

This layered arrangement — stable identity first, session context in the middle, personalization last — mirrors the standard "stable → context → volatile" structure used across agent frameworks and is why editing USER.md or TOOLS.md is enough to retarget NetClaw without touching its core behavior.

Multi-Provider Support

A significant OpenClaw feature the README highlights is breadth of model backing: 30+ LLM providers. Each provider integration handles model selection, token counting, rate limiting, and retry logic transparently, so switching the backing model does not change how NetClaw reasons about your network. Documented options include Anthropic Claude (recommended default), OpenAI (GPT-4/4o), AWS Bedrock, Google Vertex AI, Azure OpenAI, Hugging Face, local Ollama, XAI Grok, Perplexity, Groq, Fireworks.ai, Together.ai, IBM Watsonx, Oracle OCI Generative AI, Cohere, Mistral, and self-hosted runtimes such as vLLM, LM Studio, and Jan.ai, "and 10+ others." This range matters for network operations, where data-sovereignty and air-gap requirements often force a self-hosted or on-prem model — OpenClaw's provider abstraction lets NetClaw run against a local Ollama or vLLM endpoint with the same context files it would use against a frontier cloud model.

A note on sourcing. The runtime commands, the four-step wizard, the six context files, the 20 KB cap, and the provider list above are drawn from the NetClaw README (the primary source). Some third-party write-ups of OpenClaw internals (specific bind ports, envelope schemas, sub-agent federation details) are useful background but were not fully verifiable against the project itself; treat those specifics as illustrative rather than authoritative.

References