Gateway Configuration Complete Reference

Overview

This is the complete reference manual for OpenClaw Gateway configuration, covering all available options along with their default values, types, and usage instructions.

Config File Location

The Gateway configuration file is located at:

~/.openclaw/config.json

You can also specify a path via environment variable:

export OPENCLAW_CONFIG="/path/to/config.json"

Full Configuration Structure

{
  "gateway": {},
  "providers": {},
  "models": {},
  "channels": {},
  "skills": {},
  "tools": {},
  "security": {},
  "logging": {}
}

Gateway Core Configuration

{
  "gateway": {
    "host": "0.0.0.0",
    "port": 3000,
    "baseUrl": "https://your-domain.com",
    "corsOrigins": ["*"],
    "maxRequestSize": "10mb",
    "timeout": 120000,
    "keepAliveTimeout": 65000,
    "healthCheck": {
      "enabled": true,
      "path": "/health",
      "interval": 30000
    }
  }
}

Field	Type	Default	Description
host	string	"0.0.0.0"	Listen address
port	number	3000	Listen port
baseUrl	string	-	Public-facing URL
corsOrigins	string[]	["*"]	Allowed CORS origins
maxRequestSize	string	"10mb"	Max request body size
timeout	number	120000	Request timeout (ms)

Provider Configuration

{
  "providers": {
    "provider-name": {
      "type": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "{{ENV_VAR_NAME}}",
      "models": ["gpt-4o"],
      "timeout": 30000,
      "retries": 3,
      "retryDelay": 1000,
      "proxy": null,
      "headers": {},
      "costTracking": false,
      "dailyBudget": null,
      "alertThreshold": 0.8
    }
  }
}

Field	Type	Default	Description
type	string	-	Provider type (openai/anthropic/ollama)
baseUrl	string	-	API base URL
apiKey	string	-	API key (supports env var references)
models	string[]	[]	Available model list
timeout	number	30000	Per-request timeout
retries	number	3	Retry count
retryDelay	number	1000	Retry interval (ms)
proxy	string	null	HTTP proxy address
costTracking	boolean	false	Enable cost tracking

Model Configuration

{
  "models": {
    "model-alias": {
      "provider": "provider-name",
      "model": "actual-model-id",
      "temperature": 0.7,
      "maxTokens": 4096,
      "topP": 1.0,
      "frequencyPenalty": 0,
      "presencePenalty": 0,
      "stopSequences": [],
      "responseFormat": null,
      "supportsFunctionCalling": false,
      "fallback": null,
      "systemPrompt": null
    }
  }
}

Field	Type	Default	Description
provider	string	-	Associated provider name
model	string	-	Model identifier
temperature	number	0.7	Sampling temperature
maxTokens	number	4096	Max generation tokens
topP	number	1.0	Nucleus sampling parameter
fallback	string	null	Fallback model name

Channel Configuration

{
  "channels": {
    "channel-name": {
      "type": "telegram",
      "model": "model-alias",
      "systemPrompt": "You are a helpful assistant.",
      "historyLimit": 20,
      "allowedUsers": [],
      "blockedUsers": [],
      "tools": ["web_search", "code_exec"],
      "webhookPath": "/webhook/telegram",
      "rateLimit": {
        "maxMessages": 30,
        "window": 60
      }
    }
  }
}

Field	Type	Default	Description
type	string	-	Channel type
model	string	-	Model to use
systemPrompt	string	-	System prompt
historyLimit	number	20	Conversation history count
tools	string[]	[]	Available tools

Security Configuration

{
  "security": {
    "allowlist": {
      "enabled": false,
      "users": []
    },
    "rateLimit": {
      "global": {
        "maxRequests": 100,
        "window": 60
      }
    },
    "contentFilter": {
      "enabled": false,
      "blockPatterns": []
    },
    "audit": {
      "enabled": true,
      "logFile": "~/.openclaw/logs/audit.log"
    }
  }
}

Logging Configuration

{
  "logging": {
    "level": "info",
    "format": "json",
    "file": "~/.openclaw/logs/gateway.log",
    "maxSize": "50m",
    "maxFiles": 5,
    "console": true,
    "timestamps": true
  }
}

Field	Type	Default	Description
level	string	"info"	Log level
format	string	"json"	Output format (json/text)
maxSize	string	"50m"	Max single file size
maxFiles	number	5	Number of files to retain

Environment Variable References

Configuration files can reference environment variables:

{
  "providers": {
    "openai": {
      "apiKey": "{{OPENAI_API_KEY}}"
    }
  }
}

Secrets managed by openclaw secrets use the same syntax.

Validate Configuration

openclaw configure --validate
openclaw configure --show

Summary

This reference manual covers all core Gateway configuration fields. It is recommended to always run openclaw configure --validate after modifying configuration to avoid service disruptions from configuration errors.