Skip to content
BrainRoad BrainRoad
Documentation Menu

Configuration Reference

How to view and edit your OpenClaw agent's configuration file.

On this page

Your agent’s behavior is controlled by a single configuration file. You can view it, edit it, and watch changes take effect immediately — no restart required for most settings.

Config File Location

/home/node/.openclaw/openclaw.json

The file uses JSON5 format, which means you can include comments (//), trailing commas, and unquoted keys. This is the standard OpenClaw config format.

Viewing Configuration

To see the full config:

cat /home/node/.openclaw/openclaw.json

To read a specific value:

openclaw config get agents.defaults.model

The path uses dot notation to navigate the JSON structure. For example, channels.whatsapp.dmPolicy reads the dmPolicy field inside the whatsapp object inside channels.

Editing Configuration

There are three ways to change settings.

Interactive Editor

Launch a terminal-based UI that lets you navigate sections and edit values visually:

openclaw configure

This is the most approachable option if you are not sure what to change.

CLI One-Liners

Set a value directly from the command line:

openclaw config set channels.whatsapp.dmPolicy "open"
openclaw config unset channels.signal.allowFrom

Good for quick, targeted changes.

Direct File Edit

Open the config file in a text editor:

vi /home/node/.openclaw/openclaw.json

Best when you need to change multiple settings at once or want to see the full file in context.

Hot-Reload

OpenClaw watches the config file for changes. When you save an edit, the agent picks it up automatically within a few seconds. No restart is needed.

Exception: A small number of gateway-level settings require a full restart to take effect. These include gateway.port, gateway.bind, and gateway.mode. If you change one of these, restart the agent from the dashboard using the Stop and Start controls.

Config Sections

SectionWhat It Controls
gatewayPort, bind address, auth mode, Control UI settings
agentsDefault model, workspace path, sandbox mode, verbose logging
channelsWhatsApp, Signal, iMessage, Telegram, Discord, Slack, email — per-channel DM policy, allowlists, group settings
toolsShell execution policy (exec.ask, exec.security), web search, browser settings
browserCDP URL, headless mode, attach-only mode
sessionMaintenance schedules, pruning rules, DM scope
hooksWebhook endpoint configuration

Common Examples

Change the Default Model

openclaw config set agents.defaults.model "anthropic/claude-sonnet-4-6"

Open WhatsApp to All DMs

openclaw config set channels.whatsapp.dmPolicy "open"
openclaw config set channels.whatsapp.allowFrom '["*"]'

Enable Verbose Agent Logging

openclaw config set agents.defaults.verbose true

Check the Current Shell Execution Policy

openclaw config get tools.exec.ask

Auth Profiles (Separate File)

Your API keys are stored in a separate file:

/home/node/.openclaw/agents/main/agent/auth-profiles.json

This file is managed by BrainRoad’s Keys page. You generally do not need to edit it directly. To check which providers are configured:

cat /home/node/.openclaw/agents/main/agent/auth-profiles.json | head -20

See Managing Keys for the recommended way to add, update, or remove API keys.

BrainRoad-Managed Settings

Some config values are set by the platform each time your agent’s container starts. These ensure networking and authentication work correctly within the BrainRoad infrastructure.

  • gateway.bind, gateway.port, gateway.mode — container networking
  • gateway.auth.token — internal authentication token
  • gateway.controlUi.basePath — proxy path for the dashboard
  • gateway.trustedProxies — Kubernetes pod networking

These use a “set if not present” approach. Your customizations to other fields are always preserved. You do not need to worry about platform updates overwriting your settings.