OpenClaw Configuration Details: A Complete Guide to openclaw.json & Best Practices

At 10 PM on a Friday, staring at the OpenClaw service just starting up in my terminal, I breathed a sigh of relief. Then I opened ~/.openclaw/openclaw.json, looking at the screen full of configuration parameters—gateway, channel, skills, provider… with a bunch of nested options under each field.

To be honest, I was a bit confused at that moment.

Although the installation went smoothly, facing this configuration file, I suddenly realized: I didn’t really know what these parameters were for. Should dmPolicy be set to pairing or allowlist? Is gateway.auth.token just a password? Should I enable all skills?

Vultr - High-performance NVMe VPS with 32 global locations, one-click Docker deploy

View Pricing →Ad

What’s even more concerning is that in late January 2026, OpenClaw just fixed a critical security vulnerability (CVE-2026-25253, CVSS score 8.8), where attackers could steal authentication tokens via URL parameters and execute arbitrary commands. With improper configuration, your AI assistant could become someone else’s backdoor.

This article is the guide I most wanted to see at that time. I will systematically break down all configuration modules of openclaw.json, telling you what each parameter means, why you need it, and how to set it up in a production environment. I’ll also share some pitfalls I’ve stepped into and a checklist for security configuration.

Basic Understanding of the Configuration File

Where it is, what it looks like

OpenClaw’s configuration file is saved at ~/.openclaw/openclaw.json by default. If you configured it via the installation wizard, this file is generated automatically; if installed manually, you might need to create it yourself.

Open it, and you’ll see five major modules:

• Gateway: Settings for gateway service port, authentication, logging, etc.
• Channel: Configuration for communication channels (WhatsApp, Telegram, etc.)
• Skills: Management and permissions for skill modules
• Provider: AI model providers (Anthropic, OpenAI, local models, etc.)
• Security: Security policies and access control

This structure is actually quite logical—Gateway manages entry, Channel manages communication, Skills manage capabilities, Provider manages the brain, and Security manages protection.

Configuration Methods and Priority

OpenClaw supports four configuration methods:

1. Interactive Wizard: Step-by-step selection during installation, suitable for beginners
2. Direct JSON Editing: Use vim or nano to modify the file directly, suitable for those familiar with config
3. Environment Variables: Suitable for containerized deployment or temporarily overriding a parameter
4. Script Automation: Generate configuration via scripts for batch deployment

Here’s the key: these methods have priorities. Environment Variables > Configuration File > Default Values.

What does this mean? For example, if you set gateway.port: 18789 in the config file, but also set the environment variable OPENCLAW_GATEWAY_PORT=9000, the distinct 9000 takes effect. This design is particularly useful during debugging—you can test by setting a temporary env var without modifying the config file.

The 2026 version also added support for MCP Servers (Model Context Protocol), allowing unified access to multiple search engines and tools. Additionally, the openclaw doctor command can now automatically check configuration status and offer fix suggestions for discovered issues.

Gateway Configuration Details

Gateway is the entry point for OpenClaw, responsible for Web interface access and remote client connections.

Basic Configuration: Port and Authentication

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token-here"
    },
    "remote": {
      "token": "your-remote-token-here"
    }
  }
}

• port: The access port for the Web interface, default is 18789. Accessing http://localhost:18789 brings up the OpenClaw control panel. If this port is occupied, just change it (e.g., to 19000).

• auth.token: This is the gateway’s authentication token, equivalent to a password. Anyone with this token can fully control your OpenClaw instance. The CVE-2026-25253 vulnerability was due to the token being leakable via URL parameters.

• remote.token: The token used when remote clients (like mobile Apps or desktop clients) connect. It’s separate from auth.token so it can be rotated independently.

Security Tip: The version from January 29, 2026, removed the "auth: none" option. Previously you could turn off auth for easier development, now using a token or password is mandatory. This is a hard fix for the security vulnerability.

Advanced Configuration: Logging and WebSocket

{
  "gateway": {
    "logging": {
      "redactSensitive": true
    }
  }
}

With redactSensitive set to true, logs are automatically redacted—sensitive info like API keys and tokens are replaced with ***. You don’t have to worry about accidentally copying keys into public issues when checking logs for errors.

The command to start the gateway service is openclaw gateway. Once the service is running, you’ll see output like this:

[Gateway] Listening on http://localhost:18789
[Gateway] Authentication: Token-based

Channel Configuration Strategy

The Channel module determines which platforms OpenClaw can use to talk to you.

Supported Channel Types

Currently supports four main channels:

1. WhatsApp: Scan QR code to pair, most commonly used
2. Telegram: Bot API, suitable for group scenarios
3. Discord: Suitable for technical communities
4. Mattermost: Enterprise team collaboration

Each channel is configured differently. WhatsApp uses a QR code pairing process, Telegram needs a Bot Token, and Discord requires creating an Application.

DM (Direct Message) Policy Configuration

This part is where many people get confused. dmPolicy decides whether strangers can send messages to your AI assistant.

There are four modes:

1. pairing (Default Mode)

{
  "channel": {
    "dmPolicy": "pairing"
  }
}

Unknown senders need to verify pairing first. OpenClaw generates a 6-digit pairing code, valid for 1 hour. You need to verify manually:

openclaw pairing approve whatsapp ABC123

This mode balances security and usability—when a friend contacts your AI assistant for the first time, you approve it, and then it’s smooth sailing.

2. allowlist (Allowlist Mode)

{
  "channel": {
    "dmPolicy": "allowlist",
    "allowFrom": [
      "+1234567890",
      "telegram:@username"
    ]
  }
}

Only people on the allowlist can send messages; others are blocked directly. Suitable for scenarios where you clearly know who will use it.

3. open (Open Mode)

{
  "channel": {
    "dmPolicy": "open",
    "allowFrom": ["*"]
  }
}

Anyone can send messages. Honestly, this mode is very risky. Unless you are doing a public demo or testing, it is not recommended.

4. disabled (Disabled Mode)

Completely disable private messaging function, only accept group messages.

Session Isolation for Multi-user Scenarios

If your OpenClaw service is used by multiple people (e.g., team sharing), session isolation is important:

Alibaba Cloud - Top choice for developers, exclusive 15% off for Lighthouse servers

Get 15% Discount →Ad

{
  "channel": {
    "session": {
      "dmScope": "per-channel-peer"
    }
  }
}

This way everyone’s conversation history is independent and won’t get mixed up.

Group Policy Configuration

Group configuration is relatively simple, but there’s a key setting: mentionGating (@mention gating).

{
  "channel": {
    "groupPolicy": "mention",
    "mentionGating": true
  }
}

When enabled, the AI assistant will only reply to messages that @mention it, instead of listening to every message in the group. Avoids becoming an “always-on” bot—you know, the kind that spams the group like crazy.

Skills Module Configuration

Skills is the most interesting part of OpenClaw—it decides what the AI assistant can do.

Skills Basic Concepts

Skills are modular capability extensions. OpenClaw comes with some built-in skills, and the ClawHub Skill Store has 700+ available skills:

• Calendar Management (Google Calendar, Outlook)
• Web Browsing (browser skill)
• File Management (file_manager)
• Terminal Commands (exec skill)
• Code Execution (python, node)

The installation path for skills is ~/.openclaw/skills/. Priority rule: Workspace Skills > User Skills > Built-in Skills.

What does this mean? If you put a custom browser skill in your project directory, it overrides the globally installed version. This design allows you to customize capabilities for specific projects.

Skill Configuration and Management

Each skill has a SKILL.md file defining metadata in YAML format:

---
name: google-calendar
description: Manage Google Calendar events
requirements:
  bins:
    - gcalcli
  env:
    - GOOGLE_CALENDAR_API_KEY
---

The bins field lists dependent binary programs. For example, this calendar skill needs the gcalcli command-line tool. If not installed on the system, the skill will fail to load.

Three installation methods:

1. GUI Installation: Click “Add Skill” in Web interface, search and install
2. CLI Installation: openclaw skill install google-calendar
3. Manual Installation: Copy skill directory to ~/.openclaw/skills/

Skill Troubleshooting

Skill load failure is a common issue. Check dependencies with this command:

openclaw skill check google-calendar

It will tell you what dependencies are missing, if env vars are set, and if OS config matches.

If problems persist, check Gateway logs:

openclaw gateway --verbose

Logs will show the detailed skill loading process, making it clear where it went wrong.

Optimization for Small Model Scenarios

If you’re using a local model with a small context window (like a 7B parameter quantized model), you might need to disable some skills to control context size. The more skills, the longer the system prompt, leaving less space for dialogue.

Restrictions on High-Risk Skills

Some skills have high privileges and need to be used with caution:

• exec: Execute arbitrary shell commands
• browser: Access any webpage
• web_fetch: Fetch external content
• web_search: Search engine queries

These skills can be abused if malicious input is provided. If not necessary, it’s recommended to disable them.

Provider Model Configuration

Provider decides which AI brain OpenClaw uses.

Supported AI Providers

1. Anthropic (Claude): Officially recommended, stable API, robust security features
2. OpenAI: Support coming soon (GPT-4 logic)
3. Local Models: LM Studio, Ollama, etc.
4. OpenRouter: Unified multi-model access interface, use all models with one API Key
5. MCP Servers: 2026 new feature, supporting Model Context Protocol

Provider Configuration Parameters

Simplest configuration (Using Anthropic):

{
  "provider": {
    "type": "anthropic",
    "apiKey": "sk-ant-..."
  }
}

But I suggest not writing the API Key directly in the config file, use environment variables:

export ANTHROPIC_API_KEY="sk-ant-..."

This allows the config file to be safely committed to version control without leaking the API Key.

Local Model Configuration

{
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "kimi-k2.5-chat"
  }
}

• baseURL: Local model server address (LM Studio defaults to port 1234)
• modelId: Specify the model name to use

MCP Server Configuration (New Feature)

{
  "provider": {
    "mcpServers": {
      "onesearch": {
        "command": "npx",
        "args": ["-y", "@onesearch/mcp-server"]
      }
    }
  }
}

OneSearch MCP lets you access multiple search engines (Google, Bing, Brave, etc.) via a unified interface, without configuring API Keys for each one separately.

Notes on Local Models

Honestly, local models have their advantages—privacy, cost, offline availability. But security features are indeed weaker than commercial models:

Railway - Modern deployment platform, zero-config, go live in minutes

Start Now →Ad

• Higher Prompt Injection Risk: Small models are easier to trick with malicious input
• Small Context Window: Security features need more system prompts, but small models can’t fit them
• Limitations of Quantized Models: After 4-bit quantization, instruction following capability drops

If you must use local models, typical suggestions:

• Strictly limit skill permissions
• Enable sandbox mode
• Do not run on machines with sensitive data

Security Configuration Best Practices

Security configuration is always priority number one. The lesson from CVE-2026-25253 tells us that improper configuration consequences can be severe.

Security Configuration Checklist

Basic Security (Must Do)

• ✅ Never share gateway token—like your house key, never give it to others
• ✅ Use firewall, expose only necessary ports (18789)
• ✅ Use key authentication for SSH instead of password
• ✅ Limit Web interface access (VPN or IP allowlist)
• ✅ DM Policy: Prioritize pairing or allowlist
• ✅ Group Policy: Enable mention gating

Advanced Security (Highly Recommended)

• ✅ Rotate tokens regularly (at least once a quarter)
• ✅ Enable log sensitive info redaction
• ✅ Restrict high-risk skills (exec, browser)
• ✅ Use dedicated server (don’t mix with main workstation)

Input Security and Sandbox

There is an iron rule: Treat all external input as malicious.

Links, attachments, pasted instructions—all could be carefully crafted attacks. OpenClaw’s sandbox function (opt-in) can isolate high-risk operations:

{
  "security": {
    "sandbox": {
      "enabled": true,
      "skills": ["exec", "browser"]
    }
  }
}

This way exec and browser skills run in an isolated environment, affecting nothing on the main system even if compromised.

Secrets Management

Management of API Keys, tokens, and other sensitive info:

1. Basic Solution: Transfer .env file to server via SCP, avoid pasting in chat
2. Advanced Solution: Use Doppler, HashiCorp Vault, etc. professional secrets managers

Things you should NEVER do:

• ❌ Send API Keys in Telegram messages
• ❌ Commit secrets to Git repository
• ❌ Paste logs in public issues (might contain token)

Security Audit and Maintenance

OpenClaw has built-in security audit commands:

# Basic Check
openclaw security audit

# Deep Check
openclaw security audit --deep

# Auto-apply Security Fixes
openclaw security audit --fix

This command checks:

• Is Token strength sufficient
• Is port exposed to public internet
• Are file permissions correct (~/.openclaw should be 700, config file 600)
• Are high-risk skills enabled
• Is DM policy safe

Local File Permissions

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

This ensures only you can read/write the config file; other users can’t even see it.

Things You Should NEVER Do

• ❌ Expose port 18789 to public internet
• ❌ Grant shell access without understanding risks
• ❌ Install skills from unverified sources
• ❌ Use dmPolicy: "open" without an allowlist
• ❌ Run OpenClaw on machines storing primary email/banking info

Practical Configuration Examples

Theory covered, let’s look at complete configs for some real scenarios.

Scenario 1: Personal Use, WhatsApp Only, Pairing Mode

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "generate-a-strong-random-token"
    },
    "logging": {
      "redactSensitive": true
    }
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "pairing",
    "session": {
      "dmScope": "per-channel-peer"
    }
  },
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "file_manager"
    ],
    "disabled": [
      "exec",
      "browser"
    ]
  },
  "provider": {
    "type": "anthropic"
  },
  "security": {
    "sandbox": {
      "enabled": true
    }
  }
}

This config is suitable for typical personal users—good security, enough features, high-risk skills disabled.

Scenario 2: Team Collaboration, Multi-Channel, Allowlist Mode

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "team-gateway-token"
    },
    "remote": {
      "token": "team-remote-token"
    }
  },
  "channel": [
    {
      "type": "telegram",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "telegram:@alice",
        "telegram:@bob",
        "telegram:@carol"
      ],
      "groupPolicy": "mention",
      "mentionGating": true
    },
    {
      "type": "discord",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "discord:123456789"
      ]
    }
  ],
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "github",
      "jira"
    ]
  },
  "provider": {
    "type": "anthropic"
  }
}

Multi-channel config uses an array format, each channel managing its allowlist independently. Groups enable mention gating to avoid spam.

Scenario 3: Local Model, Offline Use, Lean Skills

{
  "gateway": {
    "port": 19000
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "allowlist",
    "allowFrom": ["+1234567890"]
  },
  "skills": {
    "enabled": [
      "calculator",
      "file_manager"
    ]
  },
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "llama-3.1-8b"
  }
}

In local model scenarios, try to keep skills as lean as possible—small models’ context windows can’t hold too many system prompts.

Common Configuration Errors and Solutions

Error 1: Token mismatch causing connection failure

Symptom: Web interface shows “Authentication failed”

Vultr - High-performance NVMe VPS with 32 global locations, one-click Docker deploy

View Pricing →Ad

Solution: Check if gateway.auth.token exactly matches the token you entered (watch for spaces, newlines)

Error 2: Skill dependency missing causing load failure

Symptom: Log shows “Skill ‘google-calendar’ failed to load”

Solution: Run openclaw skill check google-calendar, follow prompts to install missing dependencies

Error 3: Port conflict causing Gateway failed start

Symptom: Error: listen EADDRINUSE :::18789

Solution: Change to another port, or find the process occupying 18789 and kill it

Error 4: Configuration file format error

Symptom: SyntaxError: Unexpected token } in JSON

Solution: Use JSON validator tool to check format, common issues are extra commas or mismatched quotes

Troubleshooting Commands

# Check service status
openclaw status

# Health check
openclaw doctor

# Verbose logs
openclaw gateway --verbose

Conclusion

Having said so much, the core points are just three:

First, the configuration file is the heart of OpenClaw. Understanding every parameter is worthwhile—not to show off, but to quickly pinpoint issues when they arise.

Second, security configuration is always the top priority. CVE-2026-25253 proves the risk of improper configuration is real. Tokens must be secret, ports restricted, DM policies tightened, high-risk skills cautiously enabled.

Third, configuration is not a one-time job. As usage scenarios change, team members come and go, new skills launch, configuration needs continuous optimization. Review your config every once in a while, run openclaw security audit once, ensure everything is under control.

Now, do three things immediately:

1. Run openclaw security audit --deep to check current config
2. Optimize your config item by item against the best practices checklist in this article
3. Backup the optimized config to a safe place (but don’t backup the token with it)

If you encounter problems during configuration, the OpenClaw community is very active, people on GitHub Discussions and Discord channels are helpful. Also welcome to share your configuration experience—everyone fumbles their way through like this.

13 min read · Published on: Feb 5, 2026 · Modified on: Feb 5, 2026

Easton

AI & Intelligence