OpenClaw LaunchOpenClaw Launch
← 返回首页

教程

OpenClaw Gateway 配置指南

Token 设置、平台对接、Telegram 配对步骤与常见问题排查 — OpenClaw 网关完整教程。

什么是 Gateway（网关）？

Gateway 是 OpenClaw 的对外接入层。它是一个轻量级的 Web 服务，负责将来自各平台（Telegram、Discord、微信等）的消息路由到 OpenClaw 的 AI 引擎，并将 AI 回复发送回对应平台。

简单来说，Gateway 做三件事：

  • 身份验证 — 通过 Token 验证管理员身份，防止未授权访问
  • 用户配对 — 管理哪些外部用户有权使用你的机器人
  • 消息转发 — 在平台消息和 OpenClaw AI 引擎之间双向转发

Gateway 同时提供一个 Web 控制界面（Gateway UI），让你可以在浏览器中完成用户配对、查看连接状态等操作。

Gateway Token 设置

Gateway Token 是你访问 Gateway UI 和管理 OpenClaw 实例的凭证。在 openclaw.json 中，正确的配置格式如下：

{
  "gateway": {
    "auth": {
      "token": "your-strong-secret-token-here"
    }
  }
}

重要：gateway.auth 必须是一个对象，不能直接写成字符串。以下是错误示例，会导致 Gateway 无法启动：

// 错误写法 — 不要这样做
{
  "gateway": {
    "auth": "your-token"
  }
}

1. 打开 openclaw.json 配置文件

在你的 OpenClaw 部署目录中找到 openclaw.json 配置文件。如果是 Docker 部署，该文件通常挂载在 ~/.openclaw/openclaw.json 路径下。

2. 添加 gateway.auth 字段

在配置文件的顶层添加 gateway 对象，并设置 auth.token 字段。Token 是一个自定义的强密码字符串，建议使用 32 位以上的随机字符串，例如通过 openssl rand -hex 32 生成。

3. 确认 gateway.auth 的格式

注意：gateway.auth 必须是一个对象（{ "token": "..." }），而不是直接写字符串。常见错误是将 gateway.auth 设置为字符串，这会导致 Gateway 启动失败。

4. 保存配置并重启 OpenClaw

保存 openclaw.json 后，重启 OpenClaw 容器使配置生效。修改 gateway.auth 属于需要重启的变更（非热加载项），必须完整重启才能应用新 Token。

生成强 Token 的命令： openssl rand -hex 32（在终端运行，生成 64 位随机十六进制字符串）。

平台对接方式

OpenClaw Gateway 支持多种平台对接，不同平台采用不同的连接模式：

Telegram — 配对模式（pairing）

Telegram 推荐使用 dmPolicy: "pairing"（配对模式）。这是最安全的方式 — 只有通过 Gateway UI 完成配对的用户才能与机器人对话，有效防止陌生人滥用你的 API 额度。

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "7123456789:AAHxxxxxxx",
      "dmPolicy": "pairing"
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}

注意：不要将 Telegram 的 dmPolicy 设为 "open"，因为 Telegram 机器人可以被任何人搜索到并主动发起对话，开放模式会导致 API 额度被陌生人消耗。

Discord — 开放模式（open）

Discord 推荐使用 dmPolicy: "open" 配合 allowFrom: ["*"]。Discord 机器人是邀请制的 — 只有被你邀请进服务器的用户才能使用，因此开放模式是安全的。使用配对模式反而会造成糟糕的用户体验。

{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "your-discord-bot-token",
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  },
  "plugins": {
    "entries": {
      "discord": {
        "enabled": true
      }
    }
  }
}

注意：设置 dmPolicy: "open" 时必须同时设置 allowFrom: ["*"]，否则配置验证会失败。

Telegram 配对步骤

完成 openclaw.json 配置并启动 OpenClaw 后，按以下步骤完成 Telegram 配对：

1. 打开 Gateway UI

在浏览器中访问你的 OpenClaw Gateway 地址，通常为 https://your-server:端口号。首次访问需要输入 gateway.auth.token 进行身份验证。

2. 进入配对页面

登录 Gateway UI 后，找到 Telegram 频道对应的配对入口。点击"配对"或"Pair"按钮，系统会生成一个临时配对码（通常有效期为 5 分钟）。

3. 向机器人发送配对码

打开 Telegram，找到你的机器人，发送 Gateway UI 提供的配对码。机器人会确认配对成功，之后即可正常对话。

4. 完成连接

配对成功后，你的 Telegram 账号已与该 OpenClaw 实例绑定。其他未配对的用户无法使用该机器人，有效保护你的 API 额度。

提示：如果你使用 OpenClaw Launch 部署，配对流程完全自动化 — 部署完成后你会自动完成初始配对，无需手动操作。

如何停止 Gateway

停止 Gateway 即停止整个 OpenClaw 实例：

  • Docker 部署： 运行 docker stop 容器名称 停止容器，所有 Gateway 连接随之断开。
  • PM2 管理： 运行 pm2 stop openclaw 停止进程。
  • OpenClaw Launch： 在实例管理页面点击"停止"按钮，一键完成。

停止后，Telegram/Discord 机器人将不再响应消息，直到你重新启动 OpenClaw 实例。

常见问题

Gateway 启动失败：Token 格式错误

症状：OpenClaw 启动时报错，日志中出现 gateway.auth 相关错误。

原因：最常见的原因是 gateway.auth 被设置为字符串而非对象。

解决：确保配置为 "auth": { "token": "..." }，而不是 "auth": "..."。修改后重启 OpenClaw。

配对码已过期

症状：向机器人发送配对码后，机器人提示配对码无效或已过期。

原因：配对码通常有 5 分钟有效期，超时后自动失效。

解决：返回 Gateway UI，重新生成一个新的配对码，然后立即发送给机器人。

Gateway 启动失败：端口被占用

症状：Gateway 无法启动，日志显示 EADDRINUSE 或端口占用错误。

解决：检查是否有其他进程占用了 Gateway 端口，运行 lsof -i :端口号 查找并终止冲突进程，或在配置中修改 Gateway 端口。

Telegram 机器人不响应消息

症状：Gateway 已启动，但向 Telegram 机器人发送消息没有回复。

排查步骤：

  • 确认 channels.telegram.enabled 和 plugins.entries.telegram.enabled 都设置为 true
  • 确认 Bot Token 正确（在 BotFather 中可以查看和重新生成）
  • 确认该用户已完成配对（dmPolicy: "pairing" 模式下未配对用户的消息会被忽略）
  • 查看 OpenClaw 日志排查其他错误

Gateway UI 无法访问

症状：浏览器无法打开 Gateway UI 地址，或提示连接被拒绝。

排查步骤：确认 OpenClaw 容器正在运行；检查防火墙是否放行了 Gateway 端口；如果使用反向代理（Caddy/Nginx），检查代理配置是否正确。

使用 OpenClaw Launch 一键部署

以上所有 Gateway 配置、Token 生成、平台对接步骤，在使用 OpenClaw Launch 时都由平台自动完成。你无需手动编写 openclaw.json，无需管理 Gateway Token，无需操作配对流程。

OpenClaw Launch 提供可视化配置界面，10 秒完成部署：

  • 自动生成安全的 Gateway Token 并加密存储
  • 自动完成初始配对，部署后即可直接使用机器人
  • 自动配置 HTTPS，无需手动设置 SSL 证书
  • 支持 Telegram、Discord 等多平台一键对接
  • 月费 $3 起（首月），之后 $6/月，支持支付宝/微信支付

无需手动配置 Gateway — 一键部署

OpenClaw Launch 自动处理所有 Gateway 配置，10 秒部署，首月 $3，之后 $6/月。

立即开始部署