配置参考
本文档列出 Gateway 所有可用配置项及其默认值、类型说明和使用示例。
General（通用配置）
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
gateway.port | number | 18789 | 监听端口 |
gateway.host | string | "127.0.0.1" | 绑定地址 |
gateway.reloadMode | string | "hybrid" | 热加载模式：off / hot / restart / hybrid |
gateway.logLevel | string | "info" | 日志级别：trace / debug / info / warn / error |
gateway.dataDir | string | "~/.openclaw" | 数据存储目录 |
gateway.maxSessions | number | 50 | 最大并发会话数 |
gateway.sessionTimeout | number | 86400 | 会话超时时间（秒） |
json5
{
"gateway": {
"port": 18789,
"host": "127.0.0.1",
"reloadMode": "hybrid",
"logLevel": "info",
"dataDir": "~/.openclaw",
"maxSessions": 50,
"sessionTimeout": 86400
}
}Channels（通道配置）
配置 LLM（大语言模型）提供商连接。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
channels[].name | string | — | 通道名称（唯一标识） |
channels[].provider | string | — | 提供商：openai / anthropic / google / ollama |
channels[].apiKey | string | — | API 密钥（推荐使用 Secrets 管理） |
channels[].baseUrl | string | 提供商默认 | 自定义 API 端点 |
channels[].models | string[] | ["*"] | 允许使用的模型列表 |
channels[].maxConcurrency | number | 10 | 最大并发请求数 |
channels[].timeout | number | 120000 | 请求超时（毫秒） |
channels[].retries | number | 2 | 失败重试次数 |
json5
{
"channels": [
{
"name": "openai-main",
"provider": "openai",
"apiKey": "${OPENAI_API_KEY}", // 引用环境变量
"models": ["gpt-4o", "gpt-4o-mini"],
"maxConcurrency": 10,
"timeout": 120000,
"retries": 2
}
]
}密钥引用
使用 ${VAR_NAME} 语法引用环境变量或 Secrets 中的值，避免在配置文件中明文存储密钥。
Models（模型路由）
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
models.default | string | — | 默认模型标识 |
models.routing | object | {} | 模型到 Channel 的路由映射 |
models.fallback | string[] | [] | 模型不可用时的回退链 |
json5
{
"models": {
"default": "gpt-4o",
"routing": {
"gpt-4o": "openai-main",
"claude-sonnet-4-20250514": "anthropic-main"
},
"fallback": ["gpt-4o-mini"]
}
}Automation（自动化配置）
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
automation.heartbeat.enabled | boolean | true | 是否启用心跳 |
automation.heartbeat.interval | number | 60000 | 心跳间隔（毫秒） |
automation.autoApprove | string[] | [] | 自动批准的工具列表 |
automation.maxTurns | number | 25 | 单次对话最大轮次 |
json5
{
"automation": {
"heartbeat": {
"enabled": true,
"interval": 60000
},
"autoApprove": ["read_file", "list_files"],
"maxTurns": 25
}
}Security（安全配置）
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
security.sandbox.enabled | boolean | true | 启用沙箱隔离 |
security.sandbox.mode | string | "standard" | 沙箱模式：off / standard / strict |
security.toolPolicy.denied | string[] | [] | 禁用的工具列表 |
security.toolPolicy.requireApproval | string[] | ["execute_command"] | 需要人工批准的工具 |
security.trustedProxy.enabled | boolean | false | 启用可信代理认证 |
security.trustedProxy.headers | string[] | ["X-Forwarded-For"] | 可信头列表 |
json5
{
"security": {
"sandbox": {
"enabled": true,
"mode": "standard"
},
"toolPolicy": {
"denied": ["dangerous_tool"],
"requireApproval": ["execute_command", "write_file"]
},
"trustedProxy": {
"enabled": false,
"headers": ["X-Forwarded-For"]
}
}
}Authentication（认证配置）
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
gateway.auth.method | string | "token" | 认证方式：token / password / both |
gateway.auth.rateLimitAttempts | number | 5 | 最大失败尝试次数 |
gateway.auth.rateLimitWindow | number | 60 | 速率限制窗口（秒） |
gateway.auth.sessionTimeout | number | 86400 | 会话超时（秒） |
环境变量映射
所有配置项可通过环境变量覆盖：
text
gateway.port → OPENCLAW_GATEWAY_PORT
gateway.host → OPENCLAW_GATEWAY_HOST
gateway.auth.method → OPENCLAW_GATEWAY_AUTH_METHOD
security.sandbox.mode → OPENCLAW_SECURITY_SANDBOX_MODE
automation.heartbeat.interval → OPENCLAW_AUTOMATION_HEARTBEAT_INTERVAL