Configure OpenClaw: Setup Gateway, Auth, and Web Search

Ever spent way too much time wrestling with a configuration file only to realize you missed a single bracket or put it in the wrong folder? We’ve all been there. Getting your setup right shouldn’t feel like a chore. Let’s look at how OpenClaw handles configuration so you can get back to building.

What format is the config? Where is it?

OpenClaw uses JSON5 for its configuration. It looks for an optional file at the path defined by $OPENCLAW_CONFIG_PATH. If you haven’t set that environment variable, it defaults to ~/.openclaw/openclaw.json.

If the file isn’t there, don’t worry. The system uses safe defaults, including setting your workspace to ~/.openclaw/workspace.

I set gateway.bind: "lan" (or "tailnet") and now nothing listens / the UI says unauthorized

When you move away from loopback binds, security becomes a priority. Non-loopback binds require authentication. You need to configure gateway.auth.mode and gateway.auth.token, or you can use the OPENCLAW_GATEWAY_TOKEN environment variable.

{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me"
    }
  }
}

Why do I need a token on localhost now?

The setup wizard generates a gateway token by default, even for loopback connections. This means local clients have to authenticate. This setup stops other local processes from calling your Gateway without permission.

If you prefer an open loopback and don’t mind the security trade-off, just remove the gateway.auth section from your config.

Do I have to restart after changing config?

The Gateway is smart enough to watch your config file for changes. It supports hot-reloading with a few different modes:

• gateway.reload.mode: "hybrid" (this is the default): It applies safe changes immediately and only restarts for critical settings.
• You can also use hot, restart, or off depending on your preference.

How do I enable web search (and web fetch)?

You can use web_fetch right away without any API keys. However, web_search needs a Brave Search API key to function.

I recommend running openclaw configure --section web. This helps you store the key correctly in tools.web.search.apiKey.

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE",
        maxResults: 5
      },
      fetch: { enabled: true }
    }
  }
}

config.apply wiped my config. How do I recover and avoid this?

The config.apply command is powerful because it replaces your entire config. If you send it a partial object, it assumes you want to delete everything else.

How to recover:

• Restore the file from a backup if you have one.
• If there is no backup, run openclaw doctor and go through the configuration process again.

How to avoid this:

• Use openclaw config set when you want to make small, specific changes.
• Use openclaw configure for a more interactive editing experience.

How do I run a central Gateway with specialized workers across devices?

A common way to scale is using one Gateway paired with nodes and agents:

• Gateway (central): This is the hub that owns your channels, routing, and sessions.
• Nodes (devices): Your Macs, iPhones, or Android devices connect as peripherals to share local tools.
• Agents (workers): These are separate brains or workspaces for specific roles.
• Sub-agents: These handle background tasks spawned by a main agent.
• TUI: You use this to connect to the Gateway and jump between different agents or sessions.

Can the OpenClaw browser run headless?

Yes, you can change this in your config. Here is how you set it:

{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } }
    }
  }
}

The default setting is false (headful). Keep in mind that running headless is more likely to trigger anti-bot checks on certain websites.

How do I use Brave for browser control?

If you prefer Brave, just set browser.executablePath to your Brave binary path. This works for most Chromium-based browsers. Once you save the change, restart the Gateway to apply it.

---

Need more help getting things running? Check out the AI Setup Assistant.

Next Steps

• Gateway Authentication Details
• Advanced Agent Configuration
• Node Connection Guide