Enter fullscreen mode

OpenClaw is easiest to understand if you treat it as a local-first control plane for an AI assistant. The model is only one part of the system. The real behavior comes from the gateway, the channels you expose, the tools you allow, the workspace you give it, and the safety boundaries around all of that.

This is a practical pass through the basic configuration I would check before calling an OpenClaw setup "ready enough to use."

1. Start with onboarding unless you have a reason not to

For a new install, the recommended path is still:

openclaw onboard --install-daemon

The onboarding flow handles the boring but important parts: choosing a model provider, storing auth, configuring the gateway, and getting a first usable session running. After that, you can inspect and refine the generated config instead of writing everything from scratch.

That is the right order. Let the tool create a valid baseline, then edit deliberately.

2. Know where the config lives

OpenClaw reads an optional JSON5 config from:

~/.openclaw/openclaw.json

You can point OpenClaw somewhere else with:

OPENCLAW_CONFIG_PATH=/path/to/openclaw.json

The important detail: OpenClaw validates config strictly. Unknown keys, wrong types, or invalid values can stop the gateway from starting. That sounds fussy, but it is a useful guardrail for an agent that may be connected to real accounts and real tools.

A tiny config might look like this:

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    telegram: {
      enabled: true,
      dmPolicy: "pairing"
    }
  }
}

3. Use the CLI for small config edits

For one-off changes, prefer the config CLI over opening the file manually:

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

For larger edits, direct editing is fine, but validate immediately:

openclaw config validate
openclaw doctor

If the gateway refuses to start after a config change, openclaw doctor is the first command I would run.

4. Pick a primary model and define fallbacks

Model configuration is usually under agents.defaults.model.

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"]
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" }
      }
    }
  }
}

The convention is provider/model. If you define agents.defaults.models, that list becomes an allowlist for model selection. That is useful in team or multi-agent setups, but it can surprise you later when /model some-new-model fails because the model is not on the allowlist.

My rule of thumb:

Use a strong primary model for tool-enabled agents.
Add one or two fallbacks for reliability.
Avoid weak models for agents that read untrusted messages or operate real tools.

5. Lock down who can message the bot

This is the configuration area I would not skip.

Each channel has its own section, such as:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
      allowFrom: []
    }
  }
}

The common DM policies are:

pairing: unknown senders get a pairing code before they can interact.
allowlist: only approved senders can talk to the bot.
open: anyone can message it, and this should be rare.
disabled: DMs are ignored.

For a personal assistant, pairing is a sane default. For a public or team-facing channel, be much more explicit. The bot is not just chat UI; it may have tools behind it.

6. Treat sessions as part of privacy

Session configuration controls how conversation state is shared or isolated.

{
  session: {
    dmScope: "per-channel-peer",
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120
    }
  }
}

For single-user local experiments, a broad shared session can be convenient. For anything involving multiple people, channels, or accounts, isolate more aggressively. per-channel-peer is a good starting point because it avoids one person's context bleeding into another person's conversation.

7. Enable sandboxing before the agent meets messy inputs

OpenClaw can run tools with significant host access. That is powerful, and also exactly why sandboxing matters.

A basic sandbox posture:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "agent"
      }
    }
  }
}

The practical interpretation:

off: no sandboxing.
non-main: keep the trusted main session direct, sandbox other sessions.
all: sandbox everything.

If you are connecting group chats, webhooks, public channels, or feeds that may contain prompt injection, prefer stricter isolation. The more untrusted the input, the smaller the tool surface should be.

8. Keep secrets out of plain config when possible

OpenClaw reads environment variables from the parent process, a local .env, and ~/.openclaw/.env. You can reference env vars in config strings:

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  channels: {
    telegram: {
      botToken: "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

That is better than hardcoding tokens into a config file you might sync, back up, or paste into a ticket. For more advanced setups, OpenClaw also supports secret references through env, file, and exec-backed providers.

9. Use hot reload, but know its limits

The gateway watches ~/.openclaw/openclaw.json and can hot-apply many changes. Agent, model, channel, tool, session, cron, and logging changes are generally designed to apply without a full manual restart.

Gateway server settings are different. Port, bind address, TLS, auth, and similar gateway-level changes may require restart behavior.

So the habit is:

openclaw config validate
openclaw gateway status
openclaw doctor

If you changed a networking or auth-related setting, expect a restart to be involved.

10. A starter checklist

Before using OpenClaw for anything real, I would check:

openclaw onboard --install-daemon has completed successfully.
openclaw gateway status reports the gateway is running.
The primary model and fallbacks are configured.
Each channel has a deliberate dmPolicy.
Group chats require mention unless you truly want always-on behavior.
Multi-user setups use isolated session scope.
Sandbox mode is enabled for non-main or untrusted sessions.
Secrets come from env vars or secret refs, not pasted tokens.
openclaw doctor is clean.

The theme is simple: configure OpenClaw like an assistant with hands, not like a chatbot with text. Once it can touch tools, accounts, files, or other people, basic configuration becomes part of your safety model.

References: