🚪 OpenClaw Gateway 入门指南

一句话理解 Gateway

Gateway 是 OpenClaw 的「电话交换机」 —— 它负责接听各种渠道（Telegram、Feishu、Discord 等）发来的消息，然后把消息转给 AI 助手处理，最后把回复送回去。

没有 Gateway，你的 AI 助手就像一部没插电话线的手机——功能再强大，也接不到外界的消息。

🎯 Gateway 解决什么问题？

想象一下这个场景：

你在 Telegram 上 @你的机器人："帮我查一下明天的天气"

↓

Gateway（电话交换机）收到这条消息

↓

OpenClaw 把消息交给 AI 助手处理

↓

AI 助手回复："明天北京晴，25°C"

↓

Gateway 把回复送回 Telegram

↓

你在 Telegram 上看到回复

Gateway 的核心作用：

1. 接收消息 —— 从 Telegram/Feishu/Discord 等平台接收用户消息
2. 身份验证 —— 确保只有合法的请求能进入
3. 消息转发 —— 把消息交给 OpenClaw 核心处理
4. 回复发送 —— 把 AI 的回复送回原来的渠道

🔧 Gateway 的三种「接线模式」

OpenClaw Gateway 就像电话交换机，有三种接线模式：

1️⃣ Loopback（本机模式）

┌─────────────────────────────────┐
│  你的电脑                        │
│  ┌─────────┐    ┌─────────────┐ │
│  │ Gateway │ ←→ │ OpenClaw    │ │
│  │ 127.0.0.1   │    │ 核心        │ │
│  └─────────┘    └─────────────┘ │
│       ↑                         │
│   只有本机能访问                  │
└─────────────────────────────────┘

• 适用场景：本地开发测试
• 特点：最安全，但只有本机能访问
• 配置：gateway.bind = "loopback"

2️⃣ LAN（局域网模式）

┌─────────────────────────────────────────┐
│  局域网                                  │
│  ┌─────────┐      ┌─────────────────┐  │
│  │ 你的电脑 │ ←──→ │ 同 WiFi 的其他   │  │
│  │ Gateway │      │ 设备（手机/平板） │  │
│  └─────────┘      └─────────────────┘  │
└─────────────────────────────────────────┘

• 适用场景：家庭/办公室内网使用
• 特点：局域网内设备都能访问
• 配置：gateway.bind = "lan"

3️⃣ Tailscale（虚拟专网模式）

┌──────────────┐     🔒 Tailscale     ┌──────────────┐
│   你的电脑    │ ←──────────────────→ │  云端服务器   │
│   Gateway    │      加密隧道         │   Gateway    │
└──────────────┘                      └──────────────┘

• 适用场景：异地设备安全互联
• 特点：像在同一个局域网，但有加密保护
• 配置：gateway.bind = "tailnet"

🚀 快速配置 Gateway

第一步：检查当前状态

openclaw gateway probe

这条命令会告诉你 Gateway 是否在运行，以及它的「接线模式」。

第二步：选择合适的模式

根据你的使用场景选择上面三种模式之一。

第三步：修改配置

编辑你的 OpenClaw 配置文件（通常在 ~/.openclaw/openclaw.json）：

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "你的安全令牌"
    }
  }
}

第四步：启动 Gateway

openclaw gateway

或者后台运行：

openclaw gateway &

🔐 安全建议

1. 使用 Token 认证

永远不要不用认证（"mode": "none"），这会让任何人都能访问你的 Gateway。

2. 绑定 Loopback（默认）

除非你有特殊需求，否则保持 bind: "loopback"，这样只有本机能访问。

3. 定期更换 Token

如果 Token 泄露了，立即更换：

openclaw config set gateway.auth.token "新令牌"

🐛 常见问题排查

问题 1：Gateway 启动失败

症状：运行 openclaw gateway 后报错 解决：

1. 检查配置：openclaw config get gateway
2. 确保 gateway.mode 已设置为 "local"
3. 检查端口是否被占用：lsof -i :18789

问题 2：无法从 Telegram 收到消息

症状：机器人不回复 解决：

1. 检查 Gateway 是否运行：openclaw gateway probe
2. 检查 Telegram Bot Token 是否正确
3. 检查 Webhook 是否指向正确的 Gateway 地址

问题 3：云端服务器无法访问 Gateway

症状：本地正常，云端连不上 解决：

1. 云端 Gateway 默认绑定 127.0.0.1，只能本机访问
2. 如果需要外部访问，使用 Tailscale 隧道
3. 不推荐：直接暴露到公网（安全风险）

💡 进阶：Gateway 的工作原理

如果你想更深入理解，这里是一个技术简化图：

┌─────────────────────────────────────────────────────────┐
│                    OpenClaw Gateway                     │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │ Telegram │  │  Feishu  │  │ Discord  │   ← 渠道插件 │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘             │
│       │             │             │                    │
│       └─────────────┴─────────────┘                    │
│                     │                                   │
│              ┌──────┴──────┐                          │
│              │   WebSocket   │ ← Gateway 核心          │
│              │   服务器      │                          │
│              └──────┬──────┘                          │
│                     │                                   │
│              ┌──────┴──────┐                          │
│              │  OpenClaw   │ ← AI 助手核心            │
│              │   核心      │                          │
│              └─────────────┘                          │
└─────────────────────────────────────────────────────────┘

关键概念：

• WebSocket：Gateway 使用的通信协议，支持实时双向通信
• 渠道插件：Telegram、Feishu 等平台的适配器
• Token 认证：验证请求是否合法的「密码」

📚 相关命令速查

命令	作用
openclaw gateway	启动 Gateway
openclaw gateway probe	检查 Gateway 状态
openclaw gateway health	查看健康状态
openclaw gateway install	安装为系统服务
openclaw config get gateway	查看 Gateway 配置

🎉 总结

Gateway 是 OpenClaw 与外界沟通的桥梁：

• Loopback：最安全，仅限本机
• LAN：局域网内共享
• Tailscale：异地安全互联

新手建议：先用 Loopback 模式在本地测试，熟悉后再考虑其他模式。

有问题？欢迎在 Telegram 群「小创-useclaw-」讨论！