OpenClaw Gateway Initialization Error: gateway.mode=local Fix (Mac/Linux/WSL)

Last Updated: April 21, 2026 | Author: DevOps Engineering Team | Platforms: Linux / Raspberry Pi / macOS / WSL2

This is a configuration initialization error, not a system failure. It occurs when the OpenClaw Gateway lacks the required gateway.mode=local setting, often due to missing initialization or a corrupted config file — and can be fixed in 2 minutes.

Quick Answer

The OpenClaw Gateway initialization error “The Gateway refuses to start unless gateway.mode=local is set” happens when the OpenClaw Gateway is not configured with the mandatory gateway.mode=local parameter during service initialization. The fastest fix is to run this single CLI command:

openclaw config set gateway.mode local && openclaw gateway restart

• ✅ TOP RECOMMENDED: Use the CLI command above for an instant fix
• Edit the openclaw.json config file to add "mode": "local" under the gateway section
• Use the interactive setup wizard to reinitialize OpenClaw Gateway configuration
• Restore the config file from backup if it’s corrupted

This error is explicitly addressed in the OpenClaw official documentation, which states: “By default, the Gateway refuses to start unless gateway.mode=local is set in ~/.openclaw/openclaw.json”. Reference: OpenClaw CLI Gateway Documentation

The CLI fix is also recommended by the OpenClaw community: “Use openclaw config set gateway.mode local to resolve this issue in one step”. Reference: ClawTank Community Blog

Quick Fix (Fastest Solution)

1. Run the 1-click CLI command to set OpenClaw Gateway local mode
2. Verify the configuration is applied correctly
3. Restart the OpenClaw Gateway service
4. Confirm the gateway starts successfully

1-Click Fix Command

# Set OpenClaw Gateway local mode and restart (core fix)
openclaw config set gateway.mode local && openclaw gateway restart

# Verify the configuration
openclaw config get gateway.mode
# Expected output: "local"

# Check OpenClaw Gateway status
openclaw gateway status
# Expected output: "Runtime: running"

Quick Diagnosis Flow

• ✅ Fastest fix → Use the 1-click CLI command
• ✅ Config file corrupted → Restore from backup or reinitialize
• ✅ Setup not completed → Run openclaw setup wizard
• ✅ Configuration not applied → Restart the gateway and verify status

Real-World Causes

• Skipped the OpenClaw interactive setup wizard (openclaw setup), which automatically configures gateway.mode
• Corrupted openclaw.json file due to accidental edits or system errors
• Manually deleted the mode field from the gateway section in the config file
• Incomplete installation that failed to generate the default OpenClaw Gateway configuration
• Restored a backup config file that did not include the gateway.mode setting
• Modified the config file with invalid JSON syntax, causing the gateway to ignore missing fields

What Does This Error Mean?

The error “The Gateway refuses to start unless gateway.mode=local is set” is a service initialization block — the OpenClaw Gateway requires the gateway.mode parameter to be explicitly set to local to start in a local deployment environment.

This setting tells the OpenClaw Gateway local mode to run in a local, single-machine mode, which is required for initializing the gateway service on your local system (Mac, Linux, or WSL2). Without this setting, the gateway cannot complete its initialization process and will fail to start.

Key Note: The gateway.mode=local setting is mandatory for local gateway deployments, as specified in the OpenClaw CLI Gateway documentation. It ensures the gateway binds to the local network interface and uses the correct local configuration stack. Reference: OpenClaw CLI Gateway Documentation

Typical Error Output

[ERROR] OpenClaw Gateway Initialization Failed
[ERROR] The Gateway refuses to start unless gateway.mode=local is set
[INFO] Please set gateway.mode to 'local' in your OpenClaw configuration
[INFO] Use: openclaw config set gateway.mode local
[INFO] Or edit ~/.openclaw/openclaw.json and add "mode": "local" under "gateway"

Fix by Platform (Mac / Linux / WSL)

Fix on macOS

Use the CLI command for a 1-click fix, or edit the config file manually if the CLI is unavailable:

# Method 1: CLI Command (TOP RECOMMENDED)
openclaw config set gateway.mode local
openclaw config get gateway.mode # Verify
openclaw gateway stop && openclaw gateway start
openclaw gateway status # Confirm running

# Method 2: Edit Config File Manually
nano ~/.openclaw/openclaw.json
# Add "mode": "local" under the "gateway" section (see example below)
# Save (Ctrl+O) and exit (Ctrl+X)
openclaw gateway stop && openclaw gateway start

Fix on Linux / Raspberry Pi

The CLI method works universally; for corrupted config files, restore from backup or reinitialize:

# Method 1: CLI Command (TOP RECOMMENDED)
openclaw config set gateway.mode local
openclaw config get gateway.mode # Verify output is "local"
openclaw gateway stop
openclaw gateway start
openclaw gateway status # Should show "Runtime: running"

# Method 2: Restore Corrupted Config from Backup
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
openclaw config set gateway.mode local
openclaw gateway restart

Fix on WSL2

Ensure you’re working in the Linux file system (not Windows) and use the CLI or config edit method:

# Method 1: CLI Command (TOP RECOMMENDED)
openclaw config set gateway.mode local
openclaw config get gateway.mode # Verify
openclaw gateway stop && openclaw gateway start
openclaw gateway status # Confirm success

# Method 2: Reinitialize Setup (if config is severely corrupted)
openclaw setup
# Follow the wizard: Select "local" for Gateway mode, keep defaults for other options
openclaw gateway start

Step-by-Step Fixes

1. CLI Command (TOP RECOMMENDED)

This is the fastest and most reliable method, as it directly sets the required configuration via the OpenClaw CLI, ensuring compatibility with your system.

# 1. Set OpenClaw Gateway local mode
openclaw config set gateway.mode local

# 2. Verify the configuration is applied correctly
openclaw config get gateway.mode
# If successful, output will be: "local"

# 3. Restart the OpenClaw Gateway to apply changes
openclaw gateway stop
openclaw gateway start

# 4. Confirm the gateway is running
openclaw gateway status
# Expected output: "Runtime: running" (no errors)

This method is recommended by both the OpenClaw official documentation and the ClawTank community for resolving OpenClaw start errors related to missing gateway.mode settings.

2. Edit the OpenClaw Config File

If the CLI method fails (e.g., due to a corrupted CLI setup), manually edit the openclaw.json file — the core configuration file for OpenClaw, located in the ~/.openclaw/ directory.

# 1. Open the config file with a text editor (nano or VS Code)
nano ~/.openclaw/openclaw.json

# 2. Locate the "gateway" section (add it if missing) and add "mode": "local"
# Example of a valid gateway section:
{
  "gateway": {
    "mode": "local", // Add this line
    "port": 18789, // Default port (optional, keep default)
    "bind": "127.0.0.1" // Local binding (recommended for security)
  }
}

# 3. Save and exit (nano: Ctrl+O, Enter, Ctrl+X)

# 4. Restart the gateway
openclaw gateway stop && openclaw gateway start

# 5. Verify status
openclaw gateway status

Note: The openclaw.json file uses JSON5 format, which supports comments and trailing commas for flexibility. If the file is severely corrupted, replace it with a minimal valid config to ensure the gateway can start.

3. Reinitialize Gateway Configuration

If the config file is beyond repair, use the OpenClaw interactive setup wizard to reinitialize the gateway configuration, which automatically sets gateway.mode=local.

# 1. Run the interactive setup wizard
openclaw setup

# 2. Follow the wizard prompts:
# - Select "Gateway" when asked to configure components
# - Choose "local" as the Gateway mode (required)
# - Keep default settings for port and binding (18789 and 127.0.0.1)
# - Confirm the configuration when prompted

# 3. Start the gateway after setup completes
openclaw gateway start

# 4. Verify status
openclaw gateway status

4. Restore Corrupted Config from Backup

OpenClaw automatically creates a backup of the config file (openclaw.json.bak) in the ~/.openclaw/ directory. Use this backup to restore a working configuration.

# 1. Restore the backup config file
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

# 2. Set gateway.mode to local (in case the backup lacks it)
openclaw config set gateway.mode local

# 3. Restart the gateway
openclaw gateway stop && openclaw gateway start

# 4. Verify status
openclaw gateway status

5. Diagnose and Repair Config Issues

Use the OpenClaw diagnostic tool to identify and fix hidden config issues that may be causing the OpenClaw Gateway initialization error (e.g., invalid JSON syntax or missing fields).

# 1. Run basic diagnostic check
openclaw doctor

# 2. Run auto-repair for config issues
openclaw doctor --repair

# 3. Set gateway.mode to local if not already set
openclaw config set gateway.mode local

# 4. Restart the gateway
openclaw gateway restart

Common Search Variants

• OpenClaw Gateway initialization error
• The Gateway refuses to start unless gateway.mode=local is set
• openclaw gateway.mode=local missing
• openclaw gateway fails to start
• openclaw config gateway.mode local
• openclaw start error

Related Questions

• How to set OpenClaw Gateway local mode?
• Why does OpenClaw Gateway refuse to start?
• Where is the openclaw.json config file located?

FAQ (AI & Google Optimized)

Q: What does “The Gateway refuses to start unless gateway.mode=local is set” mean?

A: It means the OpenClaw Gateway cannot complete its initialization because the mandatory gateway.mode parameter is not set to local. This setting is required for local gateway deployments.

Q: How do I fix “The Gateway refuses to start unless gateway.mode=local is set”?

A: The fastest fix is to run openclaw config set gateway.mode local && openclaw gateway restart via the CLI. You can also edit the openclaw.json file to add the setting manually.

Q: Where is the openclaw.json config file located?

A: The core config file is located at ~/.openclaw/openclaw.json (user home directory) on Mac, Linux, and WSL2. It contains all OpenClaw configuration, including gateway settings.

Q: Why is gateway.mode=local required?

A: gateway.mode=local tells the OpenClaw Gateway to run in a local, single-machine mode, which is mandatory for initializing the service on your local system. It ensures the gateway uses the correct local network and configuration stack.

Q: What if my openclaw.json file is corrupted?

A: Restore the file from the automatic backup (openclaw.json.bak) in the same directory, or use openclaw setup to reinitialize the configuration. You can also use openclaw doctor --repair to fix minor corruption issues.

Q: Do I need to restart the gateway after setting gateway.mode=local?

A: Yes. The gateway must be restarted to apply the new configuration. Use openclaw gateway stop && openclaw gateway start to restart the service.

Q: What if the CLI command “openclaw config set” doesn’t work?

A: Manually edit the openclaw.json file to add "mode": "local" under the gateway section, then restart the gateway. If the CLI is broken, reinstall OpenClaw and try again.

Q: Can I use a different gateway mode instead of “local”?

A: For local gateway deployments (the most common use case), local is the only supported mode. Other modes are for remote or enterprise deployments, which require additional configuration not covered here.

Summary

The OpenClaw Gateway initialization error “The Gateway refuses to start unless gateway.mode=local is set” is a service initialization issue caused by a missing or incorrect gateway.mode setting in the OpenClaw configuration. The simplest and most reliable fix is to run the 1-click CLI command openclaw config set gateway.mode local && openclaw gateway restart.

If the config file is corrupted, restore it from backup, edit it manually, or reinitialize the configuration using the openclaw setup wizard. Always verify the gateway status after making changes to ensure successful initialization.

Official Best Practices

• ✅ Always run openclaw setup to complete initial service initialization
• ✅ Backup openclaw.json before modifying configuration (copy to openclaw.json.bak)
• ✅ Use openclaw doctor regularly to check config integrity and fix issues
• ✅ Avoid manual edits to openclaw.json unless necessary; use the CLI instead
• ✅ Always restart the OpenClaw Gateway after making any configuration changes
• ✅ Keep the gateway.mode set to local for local deployments (recommended by OpenClaw docs)
• ✅ On WSL2, always work inside the Linux file system, not Windows

Official References

• OpenClaw Official: CLI Gateway Documentation
• OpenClaw Official Install Guide
• OpenClaw Official: Configuration Guide
• ClawTank Community: OpenClaw Gateway Mode Fix

Related High-Performance Guides

• OpenClaw Error: gateway.mode missing (Config Corruption Fix) | Mac, Linux, WSL2
• Fix “openclaw doctor failed” (Environment Setup)
• Fix “node: command not found” (Mac, Linux, WSL) – Complete Guide