OpenClaw Gateway网关配置完全指南

前言

如果你刚接触 OpenClaw，可能会好奇它到底是怎么把各种聊天应用和 AI 模型串联起来的。答案就在 Gateway（网关）这个核心组件上。官方文档将 OpenClaw 定位为"连接聊天应用与编程代理的 Gateway 网络"，而 Gateway 正是这张网络的枢纽。

本文将从 Gateway 的核心概念入手，详细讲解配置方法、启动参数和实际使用中的关键设置。

Gateway 是什么？

Gateway 是 OpenClaw 的核心架构层，所有消息的收发、路由、转发都通过它来完成。你可以把它理解为一个"消息中间站"：

聊天应用（WhatsApp / Telegram / Discord / ...）
        ↕
   OpenClaw Gateway（单进程，多频道）
        ↕
   AI 模型（Claude / GPT / Ollama / ...）

Gateway 的设计哲学是单进程、多频道——你只需要启动一个 Gateway 进程，就能同时管理所有聊天频道的连接。这意味着部署简单、资源占用低，同时又具备灵活的扩展能力。

配置文件位置

Gateway 的配置写在 OpenClaw 的主配置文件中。默认路径如下：

平台	路径
Linux / macOS	`~/.config/openclaw/openclaw.json5`
Windows	`%USERPROFILE%\.config\openclaw\openclaw.json5`
Docker	`/app/config/openclaw.json5`

你也可以通过环境变量自定义路径：

export OPENCLAW_CONFIG=/path/to/your/openclaw.json5

Gateway 核心配置

编辑配置文件中的 gateway 段，以下是一个完整的配置示例：

{
  gateway: {
    // 监听端口，默认 18789
    port: 18789,

    // 监听地址
    // "127.0.0.1" — 仅本机可访问（开发环境推荐）
    // "0.0.0.0" — 允许所有网络访问（生产环境需配合防火墙）
    host: "0.0.0.0",

    // Dashboard 访问密码
    dashboardPassword: "your-strong-password",

    // API 密钥（用于外部系统调用 OpenClaw API）
    apiKey: "your-api-key",

    // 请求超时时间（毫秒），默认 120 秒
    timeout: 120000,

    // 最大请求体大小，控制媒体文件上传上限
    maxBodySize: "10mb",

    // CORS 跨域设置
    cors: {
      enabled: true,
      origins: ["*"],
    },
  },
}

参数速查表

参数	类型	默认值	说明
`port`	number	18789	Gateway 监听端口
`host`	string	"127.0.0.1"	监听地址
`dashboardPassword`	string	无	Dashboard 登录密码
`apiKey`	string	无	API 认证密钥
`timeout`	number	120000	请求超时（ms）
`maxBodySize`	string	"10mb"	最大请求体大小

启动 Gateway

配置完成后，使用以下命令启动 Gateway：

openclaw gateway --port 18789

如果配置文件中已设置端口，也可以直接用简写方式启动：

openclaw up

后台运行：

openclaw up -d

启动后，Gateway 会开始监听指定端口，并自动连接所有已启用的频道。

访问控制

在生产环境中，访问控制至关重要。OpenClaw 提供了多层安全机制。

IP 白名单与黑名单

通过 security 配置段限制可访问的 IP 地址：

{
  security: {
    // 仅允许以下 IP 访问（留空则不限制）
    ipWhitelist: [
      "192.168.1.0/24",
      "10.0.0.5",
    ],

    // 屏蔽特定 IP
    ipBlacklist: [
      "203.0.113.50",
    ],

    // 请求频率限制
    rateLimit: {
      enabled: true,
      maxRequests: 60,
      windowMs: 60000,
    },
  },
}

频道级别的用户限制

每个频道还可以单独设置允许的用户或群组，以 Telegram 为例：

{
  channels: {
    telegram: {
      enabled: true,
      token: "your-bot-token",
      // 仅允许这些用户 ID 使用
      allowedUsers: [12345678, 87654321],
      // 仅允许这些群组
      allowedGroups: [-100123456789],
    },
  },
}

这种双重控制（Gateway 级别 + 频道级别）让你能精细管理谁可以访问 AI 服务。

多频道路由

Gateway 的一大特色是插件式频道扩展。每个聊天平台的对接都是一个独立的频道插件，Gateway 负责统一管理和消息路由。

{
  channels: {
    whatsapp: {
      enabled: true,
      phoneNumber: "+86138xxxx",
      responseMode: "all",
    },

    telegram: {
      enabled: true,
      token: "your-bot-token",
      responseMode: "mention",
    },

    discord: {
      enabled: true,
      token: "your-discord-token",
      responseMode: "mention",
      allowedChannels: ["general", "ai-chat"],
    },
  },
}

每个频道可以设置不同的响应模式：

"all"：回复所有消息
"mention"：仅在被 @ 提及时回复

多 Agent 路由与会话隔离

当你配置了多个 AI 模型时，Gateway 支持基于规则的多 Agent 路由。不同频道可以路由到不同的模型，且每个频道的对话上下文默认相互隔离。

{
  context: {
    // 隔离策略
    // "channel" — 按频道隔离（默认，推荐）
    // "user" — 按用户隔离（同一用户跨频道共享上下文）
    // "global" — 全局共享
    isolation: "channel",

    // 上下文窗口大小
    maxMessages: 50,

    // 上下文过期时间（秒）
    ttl: 3600,
  },
}

会话隔离机制确保了不同频道之间的对话不会互相干扰。比如 Telegram 上的对话不会泄漏到 Discord 中，反之亦然。

媒体支持

Gateway 内置对多种媒体类型的支持，包括图片、音频和文档。当用户在聊天中发送图片时，Gateway 会将其传递给支持视觉功能的模型进行处理。

通过调整 maxBodySize 参数可以控制上传文件的大小上限：

{
  gateway: {
    // 如果需要处理大文件，可以适当调大
    maxBodySize: "25mb",
  },
}

Web 控制面板

Gateway 内置了 Web Dashboard，方便你在浏览器中监控和管理服务：

openclaw dashboard

Dashboard 提供以下功能：

查看各频道的实时连接状态
监控消息收发统计
查看模型调用次数和 Token 消耗
实时日志流查看

访问 Dashboard 时需要输入 dashboardPassword 中设置的密码。如果未设置密码，建议在生产环境中务必添加。

配置验证与排错

修改 Gateway 配置后，建议先验证配置文件是否正确：

# 运行诊断，检查配置和各组件状态
openclaw doctor

# 仅验证配置文件语法
openclaw doctor --config-only

如果 Gateway 启动后出现问题，可以查看日志排查：

# 查看实时日志
openclaw logs

# 查看特定频道日志
openclaw logs --channel telegram

小结

Gateway 是 OpenClaw 的核心枢纽，理解它的工作方式能帮你更好地部署和管理 AI 聊天服务。关键要点回顾：

单进程多频道：一个 Gateway 进程即可管理所有聊天平台连接
配置集中：所有设置统一在 openclaw.json5 中管理
分层安全：Gateway 级别 + 频道级别的双重访问控制
会话隔离：多频道间的对话上下文默认相互独立
插件扩展：通过插件机制灵活接入新的聊天平台

建议从最小化配置开始，先跑通一个频道，再逐步添加更多频道和高级设置。