OpenClaw Security: Step-by-Step Safe Configuration Guide

OpenClaw can read files, edit files, run commands, call tools, and receive commands from Telegram, Discord, or other channels. Therefore, security does not lie in a single configuration line, but in gradually locking down each layer. If done in the right order, the system will be easier to control. If you open the bot or gateway to the outside too early, the risk will increase significantly.

This post follows the proper sequence that should be done in real deployment: choosing the model to use, locking the gateway, locking channels, narrowing tool permissions, enabling sandbox where needed, cleaning up secrets and logs, running audits, and finally reviewing common errors. The goal is to help you have a secure enough configuration for daily use and easy control when you need to review or expand.

Regarding how to apply the configuration, you can directly edit the file ~/.openclaw/openclaw.json and then run the check command or restart the corresponding service. If you are using OpenClaw in a session with sufficient permissions, you can also ask it to help edit the file, but you should still read the diff or changes before applying them on a running machine.

What to remember: OpenClaw is designed as a personal assistant model. This is not a strong multi-tenant boundary for multiple strangers to share the same gateway while maintaining separate permissions like a SaaS service.

Choose deployment method before opening permissions

Before editing openclaw.json, you should determine how you are using OpenClaw. This is the initial orientation step, but it directly affects how you configure the remaining parts.

• Use only on your own machine: this is the safest way to start. The gateway only needs to listen locally, no need to open LAN, no need to put the bot in a group.
• Use remotely via tailnet: suitable when you want to control a machine at home or VPS from a laptop, phone, or other machines. In this case, prioritize Tailscale or a similar private network layer instead of opening public ports.
• Put the bot in Telegram or Discord, especially groups: this is the case most likely to cause risks because more people can touch the bot, and any mistakes in channel policy or tool policy will be exposed very quickly.

If you don’t have clear needs yet, start with the first type. Many security errors with OpenClaw start from opening access permissions too early right after installation.

Lock gateway first: bind and auth are the first layer

The gateway is the first layer of the entire system. If this layer is too open, the following layers only serve to minimize damage, not save an architecture that was wrong from the start. When starting, you should set the gateway to listen on loopback.

{
  "gateway": {
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "a-long-random-hard-to-guess-token"
    }
  }
}

With this configuration, the gateway only listens on 127.0.0.1. It does not expose itself to LAN or the Internet. This is a suitable starting point to check tools, review policies, run audits, and confirm the system works correctly.

If you need a new token, you can quickly generate one with the command:

openclaw doctor --generate-gateway-token

Only when you really need remote access should you consider other modes like lan or tailnet. There is one point that is very easy to misunderstand: using Tailscale does not mean OpenClaw’s auth becomes unimportant. Tailscale only helps narrow the network surface. Access to the gateway still needs to be properly locked with tokens, passwords, or appropriate auth mechanisms.

If your machine runs multiple gateways, for example one for real use and one for lab, get into the habit of calling commands with clear targets. Don’t rely entirely on default targets.

openclaw gateway status
openclaw gateway health
openclaw gateway health --url ws://127.0.0.1:19021 --token YOUR_TOKEN

This type of error occurs quite frequently: the gateway is not broken, auth is not wrong, but the command is pointing to the wrong instance.

Now for channels: who gets permission to talk to the bot

After the gateway has been locked at a basic level, the next step is the channel. This is where you decide who can send requests to OpenClaw via Telegram, Discord, WhatsApp, or other channels. If this part is too open, the protection layers behind will be difficult to be effective.

For DM (Direct Message), the two modes to use most are pairing and allowlist. open should only be used when you understand exactly what you are trading off.

{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing"
    },
    "discord": {
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789012345678"]
    }
  }
}

If the bot is in a group, don’t just think about “getting the bot in is done.” For a clearer picture of practical deployment types, you can read more in the post about installing OpenClaw on VPS. In groups, you should have at least two additional layers:

• limit which groups or users are allowed to call the bot
• enable requireMention so the bot doesn’t jump into every sentence in the chat room

{
  "channels": {
    "discord": {
      "groupPolicy": "allowlist",
      "allowFrom": ["111111111111111111"],
      "requireMention": true
    }
  }
}

The short understanding is this: dmPolicy determines who gets to DM the bot, allowFrom determines who is actually allowed, and requireMention helps the bot only respond when called properly. These three parts need to go together to create a sufficiently tight configuration.

Many people add the bot to a group and then only enable requireMention and feel secure. This is not enough. If the policy is still too broad, anyone who has permission to mention the bot can still pull the bot to do things it shouldn’t do.

Lock tools according to actual needs, don’t grant broader than necessary

This is the part that determines the scope of impact when there is an incident. The agent is not risky because it is “smart,” but because of what permissions it is granted. With OpenClaw, tool permissions should always go from minimal and gradually open, not the other way around.

If you have to choose one tool to tighten first, tighten exec. The safe configuration for most personal machines is:

{
  "tools": {
    "exec": {
      "security": "allowlist",
      "ask": "on-miss"
    }
  }
}

Simply put: familiar commands in the allowlist can run, unfamiliar commands will ask. This is safer than opening full and expecting the model to always interpret requests correctly.

If you don’t really need it, turn off elevated completely. If you do need it, only open it for the right authorized users.

{
  "tools": {
    "elevated": {
      "enabled": true,
      "allowFrom": {
        "telegram": ["123456789"]
      }
    }
  }
}

For bots in groups or agents handling less trusted content, you should tighten further: deny tools like exec, process, write, edit, or browser if not needed.

{
  "agents": {
    "list": [
      {
        "id": "public",
        "tools": {
          "deny": ["exec", "process", "write", "edit", "browser"]
        }
      }
    ]
  }
}

Don’t forget a group of permissions that are easily underestimated: tools that control processes or sessions. They are not as flashy as shell, but still enough to open more attack surfaces that you don’t want in a broad channel.

Enable sandbox in the right places

Sandbox should be seriously considered, especially when sessions are not completely trusted or the bot operates in broad channels. But you need to understand its role correctly: sandbox helps reduce damage if the model runs wrong, it does not turn a loose policy into absolute security.

A configuration to start with is:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "scope": "session",
        "workspaceAccess": "none"
      }
    }
  }
}

If you want to quickly understand the three common modes:

• off: no sandbox, should only be used for personal sessions that you really control
• non-main: main session runs normally, secondary sessions go through sandbox
• all: tightest, suitable when many sources touch the bot

The part that often causes misunderstanding is workspaceAccess. If set to none, the agent in the sandbox will not see the main workspace. This is good for security, but also means some read file or edit file commands will fail by design. Seeing failures here does not necessarily mean an error. Sometimes the policy is doing its job correctly.

In addition, sandbox can also get caught up in very mundane things like missing binaries, no network to download packages, or not mounting what you need. Therefore, when debugging, you should ask yourself first: did the command fail because OpenClaw is broken, because the tool is missing, or because I’m locking it in a tighter environment?

Secrets, logs and transcripts

After gateway, channels and tools are stable, the next step is cleaning up the remaining things on disk. This is where most people are most complacent and forget that config files, logs and transcripts are also sensitive data.

The first thing to do is remove plaintext secrets from the main config. Instead of writing API keys directly, use SecretRef via environment variables or corresponding providers.

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "OPENAI_API_KEY"
        }
      }
    }
  }
}

You can quickly check with commands:

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets reload

For logs and transcripts, the right way of thinking is to view them as sensitive operational data. If you are using OpenClaw to monitor multiple machines, the post about managing multiple VPS with OpenClaw is also quite relevant because it shows the amount of operational information that the agent can access. Logs and transcripts may contain command output, file paths, connection metadata, chat content, pairing events and much data that should not be shared as-is.

At minimum, tighten file permissions for the configuration directory:

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

When you need to ask others to look at errors, prioritize sending condensed output from status or audit first. Only send raw logs when really necessary, and remember to remove tokens, secrets, sensitive paths or private data related to your system.

Run security audit, but don’t misunderstand its purpose

After locking the main layers, you should run an audit to see what’s still open. This is a very important step, but it’s also easy to have excessive expectations if you misunderstand the role of audit. Audit helps detect dangerous or overly broad configurations. It does not replace your architecture design and does not automatically fix all wrong operational decisions.

openclaw security audit
openclaw security audit --deep

If you want to try auto-fix for safe parts, you can run more. In practice, this should be seen as a support step after you have fixed the main locks in the configuration file, not a replacement for reviewing policies yourself:

openclaw security audit --fix

When reading the results, focus on these groups:

• gateway bind and auth
• DM or group policy that is too broad
• powerful tools but opened in broad channels
• file permissions still loose
• dangerous flags or break-glass configurations still remaining

Need to say straight: --fix is not a “security patched” button. It cannot automatically understand your deployment context to pull everything to optimal state. For example, it cannot decide for you which gateway should be loopback, which group should really be open, or who should use elevated.

On machines with multiple instances, remember to check the correct target before auditing. If you probe the wrong gateway, the results are very likely to look like auth errors or network errors, when the real problem is just looking at the wrong target.

Most common errors when first tightening OpenClaw security

Below are the most practical errors I see, and also the errors that cause users to lose the most debugging time.

1. Opening gateway to LAN too early

Switching to lan right after installation to “test for convenience” is a very common habit. A safer way is to test on loopback first, confirm everything is ok, then gradually expand.

2. Having Tailscale then thinking no need for auth

Tailscale helps narrow the network surface, does not replace OpenClaw’s auth. If the gateway is still opened incorrectly or the token is weak, you are still leaving the gateway in an insecure state.

3. Putting bot in group but forgetting to tighten tools

Bot in group but still keeping exec, process, write or edit too broad, then just one bad request is enough trouble. The broader the group, the tighter the tools must be.

4. Enabling sandbox then thinking every command must run like on host

Not true. Some commands fail because the sandbox has no binary, no network, or cannot see the main workspace. That’s an operational difference, not necessarily a product bug.

5. Multiple gateways on machine but still using default target

This is a very common operational error. When you have lab and prod on the same host, treat --url and --token as mandatory habits for important commands.

6. Sending raw logs to colleagues or support

Logs are very useful for troubleshooting, but can also easily expose data that should not be shared. Raw logs should be treated as internal documents and only extract the parts that are really needed.

Quick checklist before real use

If you want to quickly check whether an OpenClaw system is tight enough, you can review according to this list:

• ☐ I have clearly determined whether I am using local only, remote via tailnet, or bot in group.
• ☐ Gateway still set to bind: "loopback" if not really needed to expand.
• ☐ Gateway has auth with token or password strong enough.
• ☐ DM not open freely unless there’s a clear reason.
• ☐ Group has requireMention and appropriate allowlist.
• ☐ exec is at allowlist + ask: "on-miss" or tighter.
• ☐ elevated has been turned off or only opened for the right people.
• ☐ Agents in broad channels have removed dangerous tools that are not necessary.
• ☐ Sandbox has been enabled for less trusted sessions or agents.
• ☐ Secrets no longer exist in plaintext in config.
• ☐ File permissions for ~/.openclaw and openclaw.json are tight enough.
• ☐ I have run openclaw security audit and read the results according to the deployment context.
• ☐ I know where logs and transcripts are, and don’t share raw logs randomly.

Conclusion

Tightening security for OpenClaw will be easier to control if done in the right order: lock gateway first, then channels, tools, sandbox and data stored on disk. Don’t look for a single trick to solve the entire security problem. With OpenClaw, security comes from each layer being tight enough for your specific use context.

If you have to remember one sentence, it’s this: don’t expand access scope before clearly determining what permissions the bot has. Keep that principle, plus the habit of running periodic audits, and you will save yourself a lot of headaches when bringing OpenClaw into real use.