Gateway 配置完全参考手册

概述

本文是 OpenClaw Gateway 配置的完整参考手册，涵盖所有可用的配置项及其默认值、类型和使用说明。

配置文件位置

Gateway 配置文件默认位于：

~/.openclaw/config.json

也可以通过环境变量指定：

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

完整配置结构

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

Gateway 核心配置

{
  "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
    }
  }
}

字段	类型	默认值	说明
host	string	"0.0.0.0"	监听地址
port	number	3000	监听端口
baseUrl	string	-	公网访问 URL
corsOrigins	string[]	["*"]	CORS 允许的来源
maxRequestSize	string	"10mb"	最大请求体大小
timeout	number	120000	请求超时（毫秒）

Provider 配置

{
  "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
    }
  }
}

字段	类型	默认值	说明
type	string	-	供应商类型（openai/anthropic/ollama）
baseUrl	string	-	API 基础 URL
apiKey	string	-	API 密钥（支持环境变量引用）
models	string[]	[]	可用模型列表
timeout	number	30000	单次请求超时
retries	number	3	重试次数
retryDelay	number	1000	重试间隔（毫秒）
proxy	string	null	HTTP 代理地址
costTracking	boolean	false	启用费用追踪

Model 配置

{
  "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
    }
  }
}

字段	类型	默认值	说明
provider	string	-	关联的供应商名称
model	string	-	模型标识符
temperature	number	0.7	采样温度
maxTokens	number	4096	最大生成 Token 数
topP	number	1.0	核采样参数
fallback	string	null	备用模型名称

Channel 配置

{
  "channels": {
    "channel-name": {
      "type": "telegram",
      "model": "model-alias",
      "systemPrompt": "你是一个有用的助手。",
      "historyLimit": 20,
      "allowedUsers": [],
      "blockedUsers": [],
      "tools": ["web_search", "code_exec"],
      "webhookPath": "/webhook/telegram",
      "rateLimit": {
        "maxMessages": 30,
        "window": 60
      }
    }
  }
}

字段	类型	默认值	说明
type	string	-	频道类型
model	string	-	使用的模型
systemPrompt	string	-	系统提示词
historyLimit	number	20	对话历史条数
tools	string[]	[]	可用工具列表

Security 配置

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

Logging 配置

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

字段	类型	默认值	说明
level	string	"info"	日志级别
format	string	"json"	输出格式（json/text）
maxSize	string	"50m"	单文件最大大小
maxFiles	number	5	保留文件数

环境变量引用

配置文件中可以引用环境变量：

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

也可以使用 openclaw secrets 管理的密钥，语法相同。

验证配置

# 验证配置文件语法和逻辑
openclaw configure --validate

# 查看当前生效的配置
openclaw configure --show

总结

本参考手册涵盖了 Gateway 的所有核心配置项。建议在修改配置后始终运行 openclaw configure --validate 进行验证，避免配置错误导致服务异常。