Gateway Daemon

Type: OpenClaw core infrastructure component

Definition

The Gateway daemon is the central long-running process that orchestrates everything in OpenClaw. It listens on all channels (WhatsApp, desktop, CLI), manages session contexts, executes cron jobs, maintains workspace state, and handles node connections. It runs as a singleton per machine — one persistent process that all channels connect to. After any configuration change to ~/.openclaw/openclaw.json, you must restart it with openclaw gateway restart for the changes to take effect.

How It Works

The Gateway sits at the center of the pipeline: You → Channel → Gateway → Agent → Tools → World. When a message comes in through any channel, the Gateway receives it, creates or resumes a session, loads the agent identity and memory, invokes the AI model, and coordinates tool execution. It handles routing between channels and agents, spinning up sub-agent sessions as needed and cleaning them up when done.

Configuration lives in ~/.openclaw/openclaw.json and controls runtime behavior: which tools are available, security policies, channel credentials, node connections, and cron schedules. The Gateway also manages the workspace filesystem — the directory where all agent work happens. Because it's a single persistent daemon, it maintains state across sessions and can run background jobs on schedule.

The Gateway is critical infrastructure: if it goes down, all channels stop working. That's why Kelly describes it as the "one persistent daemon per machine; all channels connect to it." It's designed to run continuously.

Key Properties

  • Singleton per machine — one persistent process handles all channels simultaneously
  • Pipeline hub — central routing point: Channel → Gateway → Agent → Tools → World
  • Configuration-driven — ~/.openclaw/openclaw.json controls behavior; requires openclaw gateway restart after changes
  • Session manager — creates, maintains, and cleans up agent sessions including sub-agents
  • Cron executor — runs scheduled background jobs defined in the config
  • Node handler — manages connections to remote OpenClaw nodes (mobile, other machines)
  • session-isolation — the Gateway creates and manages isolated sessions for each conversation
  • tool-policy-gating — tool security policies are enforced by the Gateway via openclaw.json
  • kelly-router — the Router pattern runs on top of the Gateway's session management

Source Chapters