my-project/doc/GATEWAY_CONFIGURATION.md

OpenClaw Gateway 配置详解

配置文件位置

• 默认位置: ~/.openclaw/openclaw.json
• 开发模式: ~/.openclaw-dev/openclaw.json

根配置结构

{
  // 元数据
  "meta": {},

  // 模型提供者
  "models": {},

  // Agent 配置
  "agents": {},

  // 通道配置
  "channels": {},

  // Gateway 配置
  "gateway": {},

  // 插件配置
  "plugins": {},

  // 日志配置
  "logging": {},

  // 消息配置
  "messages": {},

  // 环境变量
  "env": {},
}

gateway - Gateway 配置

基础配置

{
  "gateway": {
    "port": 18789,                    // WebSocket 端口
    "mode": "local",                  // 模式: local|remote
    "bind": "loopback",              // 绑定: loopback|lan|tailnet|auto|custom
    "auth": {
      "mode": "token",              // 认证模式: token|password
      "token": "your-token"         // 认证 Token
    }
  }
}

远程 Gateway

{
  "gateway": {
    "mode": "remote",
    "remote": {
      "url": "wss://gateway.example.com",
      "token": "remote-token"
    }
  }
}

绑定模式说明

模式	说明	认证要求
loopback	仅本地访问	可选
lan	局域网访问	必须
tailnet	Tailscale 网络	必须
auto	自动选择	取决于网络
custom	自定义地址	必须

logging - 日志配置

{
  "logging": {
    "level": "info",              // 文件日志级别: trace|debug|info|warn|error
    "file": "/tmp/openclaw/openclaw.log",  // 日志文件路径
    "consoleLevel": "info",       // 控制台日志级别
    "consoleStyle": "pretty",     // 控制台样式: pretty|compact|json
    "redactSensitive": "tools",   // 敏感信息脱敏: off|tools
    "redactPatterns": [           // 自定义脱敏规则
      "sk-.*"
    ]
  }
}

日志级别

• trace - 最详细
• debug - 调试信息
• info - 默认
• warn - 警告
• error - 错误

agents - Agent 配置

全局默认配置

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",      // 工作目录
      "model": {
        "primary": "deepseek/deepseek-chat"    // 默认模型
      },
      "sandbox": {
        "mode": "all",                         // 沙箱模式: off|non-main|all
        "scope": "session",                    // 沙箱范围: session|agent|shared
        "workspaceAccess": "rw"                // 工作目录访问: none|ro|rw
      },
      "groupChat": {
        "mentionPatterns": ["@openclaw"]       // 群聊触发词
      }
    }
  }
}

多 Agent 配置

{
  "agents": {
    "list": [
      {
        "id": "main",
        "name": "主 Agent",
        "workspace": "~/.openclaw/workspace",
        "model": {
          "primary": "deepseek/deepseek-chat",
          "fallbacks": ["minimax/minimax-m2.1"]
        }
      },
      {
        "id": "guardian",
        "name": "守护者",
        "workspace": "~/.openclaw/workspace-guardian"
      }
    ],
    "bindings": [
      { "agentId": "main", "match": { "channel": "telegram" } },
      { "agentId": "guardian", "match": { "channel": "whatsapp" } }
    ]
  }
}

channels - 通道配置

Telegram

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-bot-token",
      "dmPolicy": "pairing",           // pairing|allowlist|open|disabled
      "allowFrom": ["tg:123456789"],   // 允许发送者列表
      "groups": {
        "*": { "requireMention": true }
      },
      "replyToMode": "first",           // off|first|all
      "linkPreview": true,
      "streamMode": "partial",          // off|partial|block
      "actions": {
        "reactions": true,
        "sendMessage": true
      }
    }
  }
}

WhatsApp

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",            // pairing|allowlist|open|disabled
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": { "requireMention": true }
      },
      "textChunkLimit": 4000,
      "chunkMode": "length",
      "mediaMaxMb": 50
    }
  }
}

Discord

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "your-discord-token",
      "dm": {
        "enabled": true,
        "policy": "pairing"
      },
      "replyToMode": "off",
      "historyLimit": 20,
      "actions": {
        "reactions": true,
        "messages": true
      }
    }
  }
}

models - 模型配置

DeepSeek

{
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "sk-xxx",
        "api": "openai-completions",
        "models": [
          { "id": "deepseek-chat", "name": "DeepSeek" }
        ]
      }
    }
  }
}

MiniMax

{
  "models": {
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/v1",
        "apiKey": "sk-api-xxx",
        "models": [
          { "id": "minimax-m2.1", "name": "MiniMax M2.1" },
          { "id": "embo-01", "name": "Embodied" }
        ]
      }
    }
  }
}

配置验证

OpenClaw 使用严格的 JSON Schema 验证：

# 检查配置
openclaw doctor

# 自动修复
openclaw doctor --fix

常见验证错误

错误	解决
Unknown key	删除未知配置项
Invalid type	检查类型是否匹配
Config invalid	运行 openclaw doctor --fix

配置包含 ($include)

支持拆分配置文件：

// ~/.openclaw/openclaw.json
{
  "gateway": { "port": 18789 },
  "agents": { "$include": "./agents.json5" },
  "channels": { "$include": "./channels.json5" }
}

环境变量

内联环境变量

{
  "env": {
    "vars": {
      "OPENROUTER_API_KEY": "sk-or-..."
    }
  }
}

环境变量引用

{
  "models": {
    "providers": {
      "custom": {
        "apiKey": "${CUSTOM_API_KEY}"
      }
    }
  }
}

敏感信息脱敏

{
  "logging": {
    "redactSensitive": "tools",
    "redactPatterns": [
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi"
    ]
  }
}

---

最后更新: 2026-02-04