Using the Gateway Tool for System Control

The gateway tool in OpenClaw provides powerful control over the Gateway daemon process, enabling restarts, configuration updates, and live system changes without manual intervention. This article explains how to use the gateway tool effectively and safely.

What is the Gateway?

The Gateway is OpenClaw's WebSocket server that handles all channel connections (WhatsApp, Telegram, Discord, etc.), node communications, session management, and hook processing. It's the central nervous system of your OpenClaw setup, running as a background service on your machine.

Gateway Tool Actions

The gateway tool supports several critical actions:

`gateway restart`

Immediately restarts the Gateway process. This is useful after making configuration changes that require a restart or when troubleshooting connectivity issues.

openclaw gateway restart

`config.get` and `config.schema`

Retrieve the current configuration or view the complete configuration schema:

openclaw gateway config.get
openclaw gateway config.schema

`config.apply` and `config.patch`

Apply configuration changes safely:

config.apply: Replace the entire configuration (requires base config hash for safety)
config.patch: Apply partial updates to the existing configuration

# Apply full config replacement
cat << 'EOF' | openclaw gateway config.apply --baseHash <current-hash>
{
  "gateway": { "port": 18789 },
  "agents": { "defaults": { "workspace": "~/.openclaw/workspace" } }
}
EOF

# Apply partial update
openclaw gateway config.patch --raw "{\"channels.whatsapp.allowFrom\":[\"+15555550123\"]}" --baseHash <current-hash>

`gateway status` and `gateway health`

Check the Gateway's operational status and health:

openclaw gateway status
openclaw gateway health

`gateway install` and `gateway uninstall`

Manage the Gateway service installation:

openclaw gateway install
openclaw gateway uninstall

Configuration Management

The Gateway's configuration is stored in ~/.openclaw/openclaw.json as JSON5 (supports comments and trailing commas). You can edit this file directly, but using the command-line tools ensures validation and proper reloading.

Hot Reload

The Gateway automatically detects and applies configuration changes. Most settings hot-reload without requiring a restart:

Hot-applies: Channels, agents, models, automation (cron, hooks), sessions, messages, tools, UI settings
Requires restart: Gateway server settings (port, bind, auth), infrastructure settings (discovery, canvasHost, plugins)

The default hybrid reload mode automatically restarts the Gateway when necessary configuration changes are detected.

Configuration Validation

The Gateway performs strict schema validation on configuration files. Invalid configurations will prevent the Gateway from starting:

Unknown keys, malformed types, or invalid values cause startup failure
Use openclaw doctor to diagnose configuration issues
Run openclaw doctor --fix to automatically repair common problems

Best Practices

Always use config.patch for minor changes - It's safer than replacing the entire configuration
Backup your config - Keep a copy of your working configuration before major changes
Test configuration changes - Validate your JSON5 syntax before applying
Use descriptive notes - When applying configuration changes, include a note about the change purpose

Security Considerations

Keep the Gateway bound to loopback (127.0.0.1) unless you need external access
Use authentication tokens for remote access
Restrict elevated exec access to trusted users only
Regularly audit your configuration for security settings

By mastering the gateway tool, you gain complete control over your OpenClaw instance, allowing for seamless maintenance, configuration updates, and troubleshooting.