How to Configure OpenClaw Gateway Authentication
The OpenClaw gateway sits between users and your AI backend, making it the perfect place to enforce authentication. Without proper auth, anyone who finds your endpoint can use your OpenClaw instance, burning through API credits and accessing private data. This guide shows you how to configure API key authentication, set up per-user keys, implement rate limiting, and lock down access with IP allowlists.
Why This Is Hard to Do Yourself
These are the common pitfalls that trip people up.
No default authentication
OpenClaw gateway ships with auth disabled. Anyone with the URL can use your instance.
Key management complexity
Generating, rotating, and revoking API keys securely requires proper tooling and processes.
API abuse and cost
Without rate limiting, a single user can flood requests and generate massive API bills.
IP-based attacks
Attackers can brute-force API keys from anywhere unless you restrict by IP range.
Step-by-Step Guide
Enable API key authentication in gateway config
Turn on auth middleware in your gateway.yaml.
# In gateway.yaml:
auth:
enabled: true
type: api_key
header_name: X-OpenClaw-API-Key
key_storage: file # Or: redis, postgres
key_file: /app/data/api_keys.jsonGenerate API keys for users
Create unique API keys for each user or service.
# Using OpenClaw CLI:
openclaw gateway keys create --name "user@example.com" --expires 90d
# Or manually:
openssl rand -hex 32
# Then add to api_keys.json:
{
"keys": [
{
"key": "oclaw_abc123...",
"name": "user@example.com",
"created": "2025-01-16T10:00:00Z",
"expires": "2025-04-16T10:00:00Z"
}
]
}Warning: Store API keys securely. Never commit api_keys.json to version control. Use environment variables or secret management systems in production.
Configure rate limiting per API key
Prevent abuse by limiting requests per key.
# In gateway.yaml:
rate_limiting:
enabled: true
strategy: sliding_window
limits:
- scope: api_key
requests: 100
window: 60s
- scope: api_key
requests: 1000
window: 3600s # 1 hour
response:
status: 429
message: "Rate limit exceeded. Try again later."Set up IP allowlists
Restrict gateway access to specific IP ranges.
# In gateway.yaml:
ip_filtering:
enabled: true
mode: allowlist
allowed_ips:
- 192.168.1.0/24 # Internal network
- 100.64.0.0/10 # Tailscale range
- 203.0.113.5 # Specific external IP
blocked_response:
status: 403
message: "Access denied: IP not allowed"Test authentication
Verify that requests without keys are blocked.
# Without API key (should fail):
curl http://localhost:3000/chat
# Response: 401 Unauthorized
# With valid API key (should succeed):
curl http://localhost:3000/chat \
-H "X-OpenClaw-API-Key: oclaw_abc123..." \
-d '{"message": "Hello"}'Set up key rotation reminders
Regularly rotate API keys to limit exposure.
# Check for expiring keys:
openclaw gateway keys list --expiring 30d
# Rotate a key:
openclaw gateway keys rotate --key oclaw_abc123... --notify user@example.comGateway Auth Getting Messy?
We configure enterprise-grade gateway authentication with SSO, OAuth, multi-tenancy, and audit logging. Get production-ready auth without the trial and error.
Get matched with a specialist who can help.
Sign Up for Expert Help →