OpenClaw gateway allowInsecureAuth: What It Does and When to Use It

Sixty percent of the "I can't get my gateway to connect" posts in the OpenClaw community trace back to TLS certificate errors. The fastest fix is a single boolean. The dangerous part is forgetting to remove it before you ship. Here's the complete picture so you never confuse a valid dev shortcut for a production setting.

What allowInsecureAuth Actually Does

The OpenClaw gateway communicates with upstream services — LLM providers, MCP servers, internal APIs, and agent registration endpoints — over HTTPS. By default, it validates every TLS certificate it encounters. If the certificate is expired, self-signed, or signed by an unknown CA, the gateway refuses the connection and throws an error.

allowInsecureAuth: true tells the gateway to skip that validation step. Connections still use TLS for encryption, but the gateway no longer verifies that the server presenting the certificate is who it claims to be.

The distinction matters. This is not "disable TLS." It's "trust any certificate." Those are very different threat profiles. In a completely isolated environment where you control all traffic, the second is acceptable. On any network with untrusted parties — including most corporate networks — it is not.

The error this setting typically fixes looks like this:

gateway: failed to connect to upstream service
  error: x509: certificate signed by unknown authority
  url: https://internal-service.local:8443/api
  hint: if using a self-signed certificate, set allowInsecureAuth: true (dev only)

That error is the gateway protecting you. The certificate on internal-service.local wasn't signed by a trusted CA — which is expected for a local dev service, but would be alarming on a public endpoint.

When allowInsecureAuth Is the Right Call

There are exactly two scenarios where this setting is appropriate.

Scenario 1: Local Development with Self-Signed Certificates

You're running OpenClaw locally and connecting to a local mock service, a locally-running MCP server, or a Docker container with a self-signed cert. Getting a CA-signed certificate for localhost or a .local domain is more friction than it's worth for a development environment.

Here's where most people stop — but before you turn this on, read Scenario 2 to understand the context requirement.

Scenario 2: Fully Air-Gapped Private Networks

You're running OpenClaw on a closed internal network with no external access, all traffic is between machines you control, and deploying a private CA is more infrastructure than the project warrants. This is a legitimate case, but it's rarer than developers assume. "We have a VPN" does not qualify as air-gapped.

Sound familiar? If you're nodding at Scenario 1, you're in the clear. If you're trying to rationalize Scenario 2 for a production SaaS deployment, stop and get a real certificate.

How to Configure allowInsecureAuth

The setting lives in gateway.yaml under the gateway block. Here's the minimal config that enables it alongside a basic token setup:

gateway:
  port: 8080
  token: "your-gateway-token"
  allowInsecureAuth: true   # dev only — remove before deploying

logging:
  level: debug

You can also set it via environment variable without modifying the config file:

export OPENCLAW_GATEWAY_ALLOW_INSECURE_AUTH=true
openclaw gateway start

The environment variable approach is useful in CI pipelines that test against local mock services. Set it in the CI environment, not in the committed config file.

Restart the gateway after changing this setting — it reads config at startup and changes don't take effect until the process restarts.

The Right Long-Term Alternative

The goal is to never need this setting in production. There are three paths depending on your setup.

Path 1: Let's Encrypt via Caddy (Easiest)

If your gateway is on a public domain, Caddy handles certificate issuance and renewal automatically. Put Caddy in front of OpenClaw and point your domain at the server. Caddy does the rest with zero cert management on your part.

your-domain.com {
  reverse_proxy localhost:8080
}

That's the entire Caddyfile. Caddy fetches the Let's Encrypt certificate, serves HTTPS, and renews before expiry. Zero cert management on your part.

Path 2: Let's Encrypt via Certbot (More Control)

For setups where you control Nginx or another reverse proxy directly, Certbot issues certificates from Let's Encrypt and sets up auto-renewal. As of early 2025, this is still the most common approach for teams running their own infrastructure.

Path 3: Private CA for Internal Services

For internal services that aren't publicly accessible, set up a private Certificate Authority using step-ca or HashiCorp Vault's PKI secrets engine. Distribute the CA certificate to all agents. The gateway trusts the CA, all internal services have CA-signed certs, and you get full certificate validation without the public CA requirement.

gateway:
  port: 8080
  token: "your-gateway-token"
  tlsCACert: "/etc/openclaw/internal-ca.crt"  # trust your private CA
  # allowInsecureAuth is not present — validation is on

Common Mistakes with allowInsecureAuth

• Leaving it enabled after dev is done — the most common error. Add a linter rule or pre-commit hook that fails if allowInsecureAuth: true appears in any file that gets deployed to production.
• Thinking it disables encryption — it doesn't. Traffic is still encrypted. Validation is skipped. The threat model changes, but you're not sending plaintext.
• Setting it to fix a production cert issue — if your production cert is broken, fix the cert. Don't disable verification. A broken cert in production means your cert expired or your domain configuration is wrong — both are fixable problems.
• Using it on a VPN-connected server — a VPN does not make a server air-gapped. Traffic from other VPN clients can still reach your server. allowInsecureAuth is only appropriate when you control all parties on the network.
• Not testing with it disabled before launch — test your production configuration with allowInsecureAuth explicitly set to false before go-live. Certificate errors in production have caused multiple community users to rediscover they forgot this step.

Frequently Asked Questions

What does allowInsecureAuth do in OpenClaw?

allowInsecureAuth tells the gateway to skip TLS certificate verification when connecting to upstream services. Connections still use TLS encryption, but the gateway no longer confirms the server's certificate is valid and trusted. Use only in local dev or fully isolated private networks where certificate validation is impractical.

Is allowInsecureAuth safe to use in production?

No. Enabling it in production removes certificate validation, exposing your gateway to man-in-the-middle attacks. Any attacker on the network path can intercept agent communications. Always use properly signed TLS certificates in production and keep this setting disabled.

Where do I set allowInsecureAuth in OpenClaw?

Set it in gateway.yaml under the gateway section: allowInsecureAuth: true. You can also use the environment variable OPENCLAW_GATEWAY_ALLOW_INSECURE_AUTH=true. Restart the gateway after changing this setting for it to take effect.

Does allowInsecureAuth affect all agents or just the gateway?

It affects gateway-level TLS verification — connections the gateway makes to upstream services and agent registrations. Individual agent channel TLS settings are configured separately per channel. Changing this setting does not automatically disable TLS on individual channel connections.

What error does allowInsecureAuth fix?

The most common error it fixes is "certificate signed by unknown authority" or "x509: certificate verify failed" when the gateway connects to a service using a self-signed certificate. It also resolves auth handshake failures on internal services without valid CA-signed certificates.

How do I replace allowInsecureAuth with a real certificate?

Use Let's Encrypt via Certbot or Caddy's built-in automatic HTTPS for public domains. For internal services, deploy a private CA and distribute the CA certificate to all agents. Set the CA certificate path in your gateway config — this gives you full validation without the security risk.