OpenClaw Configuration Best Practices for Production

Running OpenClaw in a development environment is forgiving. Running it in production, where real teams depend on it daily, requires deliberate configuration choices. This guide covers the settings and practices that separate a reliable deployment from a fragile one.

Environment Variable Hygiene

Environment variables are the primary way to configure an OpenClaw deployment. Getting them right is the foundation of everything else.

Always Set Explicit Tokens

The OPENCLAW_GATEWAY_TOKEN variable controls authentication between the wrapper and the internal gateway. If you don't set it, the system generates a random token automatically. That works for development, but in production, an auto-generated token changes whenever the container starts fresh, which breaks existing sessions and can cause gateway startup failures.

Generate a stable token once and set it as a permanent environment variable:

export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

Store this in your deployment platform's secret management system, not in source code or plain-text configuration files.

Use Strong Setup Passwords

The SETUP_PASSWORD protects the /setup wizard, which has the power to reconfigure your entire instance. Treat it with the same care as a database admin password. Use a randomly generated string of at least 20 characters and rotate it periodically.

Separate State and Workspace Directories

While both OPENCLAW_STATE_DIR and OPENCLAW_WORKSPACE_DIR can technically point to the same parent directory, keeping them separate has operational benefits:

• State directory (/data/.openclaw): Contains configuration files, credentials, and session data. This is small and changes infrequently. It benefits from frequent backups.
• Workspace directory (/data/workspace): Contains files the AI agent works with. This can grow large and changes frequently. It benefits from generous disk allocation.

Separating them lets you apply different backup strategies and storage policies to each.

Gateway Configuration Tuning

The gateway is the core process that handles AI interactions. Its configuration lives in openclaw.json within the state directory.

Port and Bind Settings

The internal gateway port (default 18789) should never be exposed externally. The wrapper's reverse proxy handles all external traffic and injects authentication headers. If you need to change the internal port, set the INTERNAL_GATEWAY_PORT environment variable -- don't edit openclaw.json directly, as the wrapper manages that field.

Authentication Settings

For deployments behind the wrapper's reverse proxy, the following gateway settings should always be enabled:

• gateway.controlUi.allowInsecureAuth: true -- The wrapper handles TLS termination
• gateway.controlUi.dangerouslyDisableDeviceAuth: true -- Device pairing is unnecessary when the wrapper manages authentication

These settings are applied automatically by the setup wizard. If you're configuring manually, verify they're set correctly to avoid "pairing required" errors in the Control UI.

Trusted Proxies

When running behind a reverse proxy (which you should in production), configure the gateway to trust the proxy's forwarded headers. The wrapper sets gateway.trustedProxies during onboarding, but verify this is configured correctly if you're adding additional proxy layers.

AI Provider Configuration

API Key Management

Never hardcode API keys in configuration files that might be committed to version control. Use environment variables or your platform's secrets management. The setup wizard writes API keys to openclaw.json, which lives in the persistent data volume and is excluded from the application repository.

Model Selection

The model configuration uses the format { primary: "provider/model" } under agents.defaults.model. Choose your model based on the balance between capability and cost that fits your use case:

• For code generation tasks, larger models generally produce better results
• For simple Q&A or documentation lookups, smaller models save significant API costs
• Consider setting different models for different use cases if your provider supports it

Operational Reliability

Health Checks

The gateway exposes multiple health check endpoints: /openclaw, /, and /health. Different OpenClaw builds may expose different subsets of these. Configure your monitoring to check at least two of them:

curl -f http://localhost:18789/health || curl -f http://localhost:18789/

The wrapper already polls these endpoints during startup. For external monitoring, check the wrapper's public URL rather than the internal gateway port.

Log Management

The gateway process inherits its standard output and error streams from the wrapper, so all logs appear in a single stream. In production, route these logs to a centralized logging service. Look for these key log prefixes:

• [gateway] -- Gateway lifecycle events (start, stop, ready)
• [proxy] -- Reverse proxy events and errors
• [setup] -- Setup wizard actions

Graceful Restarts

When updating configuration that requires a gateway restart, the wrapper handles the restart sequence automatically. It stops the existing gateway process, applies configuration changes, starts a new process, and waits for readiness before resuming traffic proxying.

Avoid killing the container abruptly during this process. If you need to restart the container, let the wrapper handle shutdown gracefully by sending a SIGTERM signal.

Backup Strategy

Automated Exports

The /setup/export endpoint creates a compressed archive of both the state and workspace directories. For automated backups, call this endpoint on a schedule:

curl -u "admin:$SETUP_PASSWORD" \
  https://your-instance.example.com/setup/export \
  -o "backup-$(date +%Y%m%d).tar.gz"

Store backups in a separate location from your deployment. Cloud object storage services work well for this purpose.

What to Back Up

At minimum, back up the state directory. It contains openclaw.json (all configuration), API credentials, and gateway tokens. Losing this data means reconfiguring the instance from scratch.

The workspace directory is important if it contains project files or context that took time to build. Its importance varies by use case.

Configuration Validation Checklist

Before considering your production deployment ready, verify each of these items:

• OPENCLAW_GATEWAY_TOKEN is set to a stable, randomly generated value
• SETUP_PASSWORD is strong and stored securely
• TLS is terminated before traffic reaches the wrapper
• The data volume is persistent and survives container restarts
• Health monitoring is configured and alerting is enabled
• Backup exports are scheduled and tested
• API keys are stored as secrets, not in source code
• Gateway authentication settings match your proxy topology

Production configuration is not a one-time task. Review these settings whenever you update OpenClaw, change your infrastructure, or modify your proxy setup. A few minutes of verification prevents hours of debugging.