Gateway - Neotask by Neotask Documentation | Neotask

Gateway

What Is the Gateway?

The Gateway is the heart of Open Claw — a single long-running service that manages all agent sessions, messaging channels, tool execution, and device connections. Everything flows through the Gateway.

It's a WebSocket server that listens for connections from clients (desktop app, mobile apps, web dashboard) and manages the entire AI assistant lifecycle.

Architecture

Components

  • WebSocket Server — Accepts client connections (default port 18789)
  • HTTP Server — Serves the Control UI, canvas host, and health endpoints
  • Channel Adapters — Maintain connections to messaging platforms (WhatsApp, Telegram, Discord, etc.)
  • Session Manager — Persists and manages agent conversation state
  • Cron Scheduler — Runs scheduled jobs and heartbeat wakeups
  • Plugin Runtime — Loads and manages plugin lifecycle
  • Browser Service — Controls Chromium instances for web automation

    • Binding Modes

    | Mode | Description | |------|-------------| | Loopback | Default. Only accessible from localhost (127.0.0.1) | | LAN | Accessible on your local network. Auto-discoverable via Bonjour/mDNS | | Tailnet | Accessible through Tailscale VPN with MagicDNS | | Custom | Bind to a specific address |

    Authentication

    | Method | Description | |--------|-------------| | Token | WebSocket bearer token (UUID or custom string) | | Password | Password-based auth (bcrypt hashed) | | Trusted Proxy | For reverse proxies with pre-auth headers | | Local Trust | Loopback connections auto-approved |

    Configuration

    The Gateway is configured via openclaw.json (JSON5 format). Key sections:

    | Section | Controls | |---------|----------| | agents | Agent list, defaults, workspaces | | gateway | Port, bind mode, auth, reload behavior | | channels | Per-channel config and credentials | | tools | Tool permissions, profiles, security | | plugins | Plugin loading, enabling, per-plugin config | | models | Provider auth, fallbacks, provider settings | | skills | Skill directories, per-skill configuration | | browser | Browser profiles, ports, headless mode | | cron | Scheduler configuration | | session | Reset rules, compaction thresholds | | messages | TTS settings, media policies | | memory | Memory indexing configuration | | security | Sandboxing, elevated mode, approvals |

    Hot Reload

    Configuration changes can be applied without restarting:

    | Mode | Behavior | |------|----------| | Hybrid (default) | Hot-apply safe changes, restart for others | | Hot | Only apply hot-safe changes, ignore others | | Restart | Restart on any reload-required change | | Off | No automatic reload |

    Remote Access

    Tailscale (Recommended)

    Tailscale provides secure, zero-config remote access:

  • Bind the Gateway to your Tailnet
  • Access from any device on the same Tailscale network
  • Automatic DNS via MagicDNS
  • Tailscale Serve can expose the dashboard with HTTPS

    • SSH Tunnel

    Forward the Gateway port through SSH:

  • Simple, secure, no configuration changes needed
  • Works with any SSH-capable machine
  • Supports the full WebSocket protocol and Control UI

    • Security Rules

  • Loopback + SSH/Tailscale is the safest combination
  • Non-loopback binding requires auth token configuration
  • TLS fingerprint pinning available for extra security
  • Browser control is disabled for remote connections by default

    • Health Monitoring

    Health Endpoint

    The /health HTTP endpoint returns:

  • Gateway status
  • RPC liveness
  • Per-channel health (connected, auth status, account count)
  • Browser readiness
  • Active agents and connected nodes
  • Uptime

    • Probes

  • RPC liveness — WebSocket connect + echo test
  • Channel health — Auth check + API ping per channel
  • Browser readiness — Port check, process check
  • Node connectivity — Last heartbeat timestamp

    • Discovery

    Bonjour/mDNS

    When bound to LAN, the Gateway advertises itself via multicast DNS:

  • Service type: _openclaw-gw._tcp
  • Includes port, transport, TLS status, and Tailscale DNS info
  • Companion apps discover the Gateway automatically

    • Wide-Area Discovery

    Discover gateways across your network with configurable timeouts. Supports both local Bonjour and Tailscale DNS discovery.

    Multiple Gateways

    You can run multiple Gateway instances on the same machine using profiles:

  • Each profile has separate config, workspace, sessions, and state
  • Different ports for each Gateway
  • Useful for isolation (personal vs work) or testing

    • Diagnostics

    Doctor

    The built-in diagnostic tool checks:

  • Configuration validity
  • File permissions
  • Channel connectivity
  • Model auth status
  • Node.js version compatibility
  • Common misconfigurations

    • It can automatically fix many issues when given permission.

    Logging

    Gateway logs are written to daily JSONL files:

  • Per-completion token usage tracking
  • Channel event logs
  • Error logging with structured context
  • Configurable log levels

    • View full documentation