Skip to content
BotServBotServ
OpenClawConfigurationopenclaw.jsonSecurityProxmox

OpenClaw Configuration

OpenClaw config files, environment variables and key options. JSON5, hot reload and security.

S

schutzgeist

4 min read
OpenClaw Configuration

OpenClaw Configuration

Internet Relay Chat und Linux-FAQs

IRC-Mania Die Seite rund um Sicherheit und Programmierung

Internet, Sicherheit , Internet Relay Chat

What this article covers

  • Where OpenClaw stores its configuration.
  • How openclaw.json is structured.
  • Key configuration sections: agents, models, gateway, and security.
  • Environment variables and hot reload.
  • Best practices for a secure and clean setup.

Introduction: OpenClaw Configuration

OpenClaw is controlled through a central JSON5 configuration file. You define agents, models, providers, the gateway, channels, skills, plugins, and security settings all in one place. Edit the file directly or manage it via the CLI using openclaw config. For local AI setups on Proxmox, clean configuration is critical to make OpenClaw work correctly with Claude, Ollama, and other tools.

This article walks through the structure, key configuration sections, and typical examples for openclaw.json.

Key terms

  • JSON5: Extended JSON that supports comments and trailing commas.
  • openclaw.json: Central configuration file.
  • State directory: The path ~/.openclaw, where configuration, logs, and runtime data are stored.
  • Hot reload: Gateway automatically loads configuration changes.
  • Profile: Ability to use different configuration sets.
  • SecretRef: Reference to a secret instead of storing the value in plaintext.
  • Schema: Structure against which OpenClaw validates configuration.

Configuration file

The default path is:

~/.openclaw/openclaw.json

Set a different path using an environment variable:

export OPENCLAW_CONFIG_PATH=/path/to/openclaw.json

Check the path with openclaw config file.

Format

openclaw.json uses JSON5. Comments and trailing commas are allowed. All fields are optional. OpenClaw uses secure defaults if something is missing.

{
  // Agent defaults
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },

  // Models and providers
  models: {
    default: {
      primary: "anthropic/claude-opus-4-8",
      fallbacks: ["ollama/llama3.1:8b"],
    },
    providers: {
      anthropic: {
        apiKey: { $secretRef: "anthropic-api-key" },
      },
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://127.0.0.1:11434",
      },
    },
  },

  // Gateway settings
  gateway: {
    bind: "127.0.0.1",
    port: 8080,
  },

  // Logging
  logging: {
    level: "info",
  },
}

Key configuration sections

agents

Define default values for agents such as workspace, behavior, or tools. Individual agents can override these values.

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
    entries: {
      AgentSmith: {
        // Agent-specific settings
      },
    },
  },
}

models

models specifies available providers, default models, and fallbacks.

{
  models: {
    default: {
      primary: "anthropic/claude-opus-4-8",
      fallbacks: ["ollama/llama3.1:8b"],
    },
    providers: {
      anthropic: {
        apiKey: { $secretRef: "anthropic-api-key" },
      },
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://127.0.0.1:11434",
      },
    },
  },
}

Important for Ollama: use the native endpoint http://host:11434, not /v1.

gateway

The gateway controls network access to OpenClaw.

{
  gateway: {
    bind: "127.0.0.1",
    port: 8080,
    auth: {
      token: { $secretRef: "gateway-token" },
    },
  },
}

Security note: Keep bind set to 127.0.0.1 if possible. For Tailscale or internal access, use an appropriate private IP, but never bind to 0.0.0.0 without additional hardening.

channels

Channels connect OpenClaw to messengers and other services. Examples include Slack, Discord, Telegram, or Matrix. Each channel has its own configuration fields.

{
  channels: {
    slack: {
      token: { $secretRef: "slack-token" },
    },
  },
}

skills

Skills are pre-built capabilities that agents can use. Configuration depends on the specific skill.

plugins

Plugins extend OpenClaw with additional functionality. Installed plugins can be enabled or disabled here.

security

Security settings like audit rules, token handling, or sandbox options.

{
  security: {
    audit: {
      enabled: true,
    },
  },
}

logging

{
  logging: {
    level: "info",
  },
}

Available levels are trace, debug, info, warn, error, and fatal.

env

Inline environment variables or instructions to import secrets from your shell environment.

{
  env: {
    ANTHROPIC_API_KEY: { $secretRef: "anthropic-api-key" },
  },
}

Secrets in configuration

OpenClaw supports SecretRefs to avoid storing sensitive values in plaintext. Secrets can be provided through a separate file or a secret manager.

{
  models: {
    providers: {
      anthropic: {
        apiKey: { $secretRef: "anthropic-api-key" },
      },
    },
  },
}

Environment variables

Important environment variables:

  • OPENCLAW_CONFIG_PATH: Path to the configuration file.
  • OPENCLAW_STATE_DIR: Path to the state directory.
  • OPENCLAW_PROFILE: Profile name.
  • OPENCLAW_NIX_MODE: Write protection for Nix installations.

Hot reload

The OpenClaw gateway watches openclaw.json and automatically loads changes. Still, check after major changes:

openclaw config validate
openclaw doctor

CLI configuration

Set values directly from the command line:

openclaw config set models.default.primary "anthropic/claude-opus-4-8"
openclaw config set models.providers.ollama.baseUrl "http://127.0.0.1:11434"
openclaw config get models.default.primary
openclaw config unset models.default.primary

Validation

Check configuration before restart:

openclaw config validate
openclaw doctor --lint

Common pitfalls

  • JSON5 syntax errors: Comments are allowed, but braces must match.
  • Unknown keys: OpenClaw refuses to start if unknown keys are present.
  • Wrong Ollama endpoint: /v1 is incorrect. http://host:11434 is right.
  • Gateway bound to 0.0.0.0: Security risk without additional hardening.
  • Secrets in plaintext: Use SecretRefs.
  • Config changes don’t take effect: Restart the gateway or check hot reload.

Further reading and resources

FAQ: OpenClaw Configuration

Where is the configuration file located? By default at ~/.openclaw/openclaw.json.

Can I add comments to the configuration? Yes, JSON5 supports comments.

Do I need to restart after making changes? The gateway usually loads changes automatically. Restart if you run into issues.

How do I protect API keys? Use SecretRefs or environment variables.

What happens if the configuration is invalid? OpenClaw refuses to start. Run openclaw config validate to see errors.

Sources and further reading

Summary: OpenClaw Configuration

VPS Hosting Angebot

Premium VPS Hosting

Schnelle und sichere VPS Server

OpenClaw is configured centrally via ~/.openclaw/openclaw.json. The JSON5 file supports comments and defines agents, models, providers, gateway, channels, skills, plugins, security, and logging. What matters most is using correct model endpoints, leveraging SecretRefs, binding the gateway securely, and validating regularly. With a well-structured configuration, you get stable and secure OpenClaw operation in your own network.

Back to Blog
Share:

Related Posts