doanbactam_openclaw-anything/references/config-schema.md

OpenClaw Configuration Reference

Reference normalized against:

• https://docs.openclaw.ai/cli/config
• https://docs.openclaw.ai/gateway/configuration
• Individual CLI pages for models, channels, agents, hooks, cron, security, secrets

Last verified: 2026-02-27.

Config File Location

Default state directory:

• ~/.openclaw

Default config file:

• ~/.openclaw/openclaw.json

Profile-based isolation:

• --dev flag → ~/.openclaw-dev
• --profile <name> flag → ~/.openclaw-<name>

CLI Config Management

Use CLI sub-commands (not flags) to manage config:

• openclaw config get <key>: Read a config value.
• openclaw config set <key> <value>: Write a config value.
• openclaw config unset <key>: Remove a config value.

Interactive wizard:

• openclaw configure: Full interactive config setup.

Gateway RPC config methods:

• config.apply: Validate + write config + restart + wake.
• config.patch: Merge a partial update + restart + wake.
• config.get: Get current config via RPC.
• update.run: Run update + restart.

Strict Validation

When config fails schema validation:

• Gateway does not boot.
• Only diagnostic commands work: openclaw doctor, openclaw logs, openclaw health, openclaw status.
• Run openclaw doctor to see exact issues.
• Run openclaw doctor --fix (or --yes) to apply repairs.

Minimal Config Example

{
  "gateway": {
    "bind": "127.0.0.1",
    "port": 18789,
    "auth": {
      "token": "replace-with-strong-token"
    }
  },
  "channels": {
    "whatsapp": {
      "allowFrom": ["+1234567890"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "claude-3-5-sonnet-latest"
      },
      "imageModel": {
        "primary": "gpt-4o"
      }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}

High-impact Keys

• gateway.bind: Interface binding. Keep 127.0.0.1 unless remote access is required.
• gateway.port: Gateway port (default 18789).
• gateway.auth.token: Required when binding beyond loopback.
• channels.*: Channel-specific policy and auth settings.
• channels.<name>.allowFrom: Restrict who can message the agent.
• channels.<name>.groups.*.requireMention: Require mention in group chats.
• agents.defaults.workspace: Base workspace for agent tasks.
• agents.defaults.model.primary: Default model used by agents.
• agents.defaults.imageModel.primary: Default image model.
• messages.groupChat.mentionPatterns: Patterns to trigger agent in group chats.
• commands.debug: Enable /debug slash command (default false).

Environment Variables

OpenClaw Runtime Variables

• OPENCLAW_CONFIG_PATH: Override config file path.
• OPENCLAW_STATE_DIR: Override state directory.
• OPENCLAW_HOME: Override OpenClaw home directory.
• OPENCLAW_GATEWAY_TOKEN: Gateway token (also set by --token flag).
• OPENCLAW_GATEWAY_PASSWORD: Gateway password (also set by --password flag).
• OPENCLAW_LOAD_SHELL_ENV=1: Import shell environment variables at startup.
• OPENCLAW_AGENT_DIR / PI_CODING_AGENT_DIR: Scope agent context.
• CLAUDE_WEB_SESSION_KEY / CLAUDE_WEB_COOKIE: Session keys for Claude channel.
• NO_COLOR=1: Disable ANSI output styling.

Wrapper Variable

• OPENCLAW_WRAPPER_ALLOW_RISKY=1: Enable high-risk commands in wrapper.

Env File Loading

• .env from CWD (if present)
• ~/.openclaw/.env (global fallback)

Inline Environment Variables

Define env vars directly in config:

{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-...",
    "vars": { "GROQ_API_KEY": "gsk-..." }
  }
}

Shell Environment Import

{
  "env": {
    "shellEnv": { "enabled": true, "timeoutMs": 15000 }
  }
}

Also activated via OPENCLAW_LOAD_SHELL_ENV=1.

Config Value Substitution

Use ${VAR_NAME} in config values (uppercase only: [A-Z_][A-Z0-9_]*).

• Missing/empty vars throw error at load time.
• Escape with $${VAR} for literal output.
• Works inside $include files.
• Example: "${BASE}/v1" → "https://api.example.com/v1"

Secret Refs

Replace plaintext secrets with structured refs:

{
  "models": { "providers": { "openai": {
    "apiKey": { "source": "env", "provider": "default", "id": "OPENAI_API_KEY" }
  }}},
  "skills": { "entries": { "my-skill": {
    "apiKey": { "source": "file", "provider": "filemain", "id": "/skills/entries/my-skill/apiKey" }
  }}},
  "channels": { "googlechat": {
    "serviceAccountRef": { "source": "exec", "provider": "vault", "id": "channels/googlechat/serviceAccount" }
  }}
}

Sources: env, file, exec. Providers defined in secrets.providers config.

Use openclaw secrets configure to set up providers and map credentials interactively. Use openclaw secrets audit to check for plaintext residues.

Config Hot Reload

Gateway watches openclaw.json for changes.

Reload modes (gateway.reload.mode):

• hybrid (default): hot-apply safe fields, restart for structural changes.
• hot: hot-apply only.
• restart: full restart on any change.
• off: no auto-reload.

Config:

{ "gateway": { "reload": { "mode": "hybrid", "debounceMs": 300 } } }

Hot-apply fields: channels.*, web, agent, agents, models, routing, hooks, cron, session, messages, tools, browser, skills, audio, talk, ui, logging, identity, bindings.

Restart-required fields: gateway.*, discovery, canvasHost, plugins, gateway.reload, gateway.remote.