Authentication Modes

+15 Mana ✨
OpenClaw Authentication Guide(DOCUMENTATION)OpenClaw Security Best Practices(DOCUMENTATION)

Introduction

The OpenClaw Gateway enforces authentication by default using a fail-closed security model. This means that if authentication is not explicitly configured, the Gateway denies all requests rather than allowing unauthenticated access. There are three authentication modes to choose from, each suited to different deployment scenarios.

Key Concepts

  • Fail-Closed Default: The Gateway rejects all requests when no authentication mode is configured, ensuring accidental exposure never results in open access.
  • Token Authentication: The recommended mode where clients present a bearer token with each request. The token is configured on the Gateway side.
  • Password Authentication: An environment-variable-based mode where a shared password is used for simpler setups.
  • Trusted-Proxy Authentication: Delegates authentication to a reverse proxy that sets trusted headers, useful when the Gateway sits behind an existing auth layer.

Real World Context

The fail-closed model mirrors best practices in API security and firewall design. Services like Kubernetes API server and HashiCorp Vault also default to denying access until authentication is explicitly configured. Token-based auth follows the same pattern as API keys used by services like Stripe, OpenAI, and GitHub. Trusted-proxy auth is common in enterprise environments where a centralized identity provider (like Okta or Auth0) handles authentication at the edge, and backend services trust headers set by the proxy.

Deep Dive

Let us examine each authentication mode in detail.

Token Authentication (Recommended)

Token authentication uses bearer tokens, similar to how you authenticate with the OpenAI API. You configure a token on the Gateway, and clients must include it in every request.

bash
# Start gateway with token auth
openclaw gateway --auth-mode token --auth-token "sk-my-secret-token-here"

After running this command, every request to the Gateway must include the token in the Authorization header. Here is how a client request looks:

bash
# Client request with bearer token
curl -H "Authorization: Bearer sk-my-secret-token-here" \
  http://localhost:18789/v1/chat/completions \
  -d '{"model": "anthropic:claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "Hello"}]}'

The Gateway validates the token before routing the request to any channel. If the token is missing or incorrect, the request is rejected with a 401 Unauthorized response. This is the recommended mode because tokens can be rotated, scoped, and revoked without restarting the Gateway.

Password Authentication

Password auth uses a shared secret stored in an environment variable. This is simpler to set up but less flexible than token auth.

bash
# Set the password via environment variable
export OPENCLAW_AUTH_PASSWORD="my-gateway-password"

# Start gateway with password auth
openclaw gateway --auth-mode password

The Gateway reads the password from the OPENCLAW_AUTH_PASSWORD environment variable. Clients authenticate by including the password in their requests. This mode is convenient for single-user setups or development environments where you want minimal configuration.

Trusted-Proxy Authentication

Trusted-proxy mode is designed for deployments where the Gateway sits behind a reverse proxy (like Nginx, Caddy, or Cloudflare Tunnel) that handles authentication.

bash
# Start gateway with trusted-proxy auth
openclaw gateway --auth-mode trusted-proxy --trusted-proxy-header "X-Authenticated-User"

In this mode, the Gateway trusts a specific HTTP header set by the reverse proxy. The proxy authenticates the user (via OAuth, SSO, mTLS, etc.) and passes the identity downstream via the configured header. The Gateway does not perform its own credential validation – it trusts the proxy entirely.

This mode is powerful but dangerous if misconfigured. If clients can reach the Gateway directly (bypassing the proxy), they can forge the trusted header. This is why non-loopback binding without proper network controls is rejected.

The Fail-Closed Default

If you start the Gateway without specifying an auth mode and attempt to use a non-loopback binding, the Gateway refuses to start:

bash
# This will be rejected
openclaw gateway --binding lan
# Error: non-loopback binding requires authentication. 
# Configure --auth-mode to proceed.

For loopback binding, the Gateway allows running without explicit auth since only local processes can connect. However, even on loopback, configuring authentication is recommended if multiple users share the machine.

Common Pitfalls

  • Using trusted-proxy without network isolation: If clients can bypass your reverse proxy and connect directly to the Gateway, they can forge the trusted header and impersonate any user. Always ensure the Gateway is only reachable through the proxy when using this mode.
  • Hardcoding tokens in scripts: Treat Gateway tokens like API keys. Use environment variables or secret managers instead of embedding them in shell scripts or config files that might be committed to version control.

Best Practices

  • Use token authentication for most deployments – it offers the best balance of security and simplicity.
  • Rotate tokens periodically and use distinct tokens for different clients or integrations to enable granular revocation.
  • When using trusted-proxy mode, bind the Gateway to loopback and let the reverse proxy handle external traffic to prevent header forgery.

Summary

  • The Gateway uses a fail-closed security model: no auth configured means all requests are denied.
  • Token auth (bearer tokens) is the recommended mode, offering rotation and revocation capabilities.
  • Password auth uses an environment variable and is simpler but less flexible.
  • Trusted-proxy auth delegates authentication to a reverse proxy via trusted headers.
  • Non-loopback binding without authentication is always rejected at startup.
✓ Completed