WebChat Plugin 接入指南 聊天页 管理后台

WebChat Plugin 接入指南

本指南帮助你在 OpenClaw Gateway 上安装并配置 WebChat Channel Plugin，接入浏览器聊天通道。

前置条件
已经准备好可用的 Chat Server 地址、appId 和 secret。
当前服务器：检测中...

1. 安装 Plugin

在 OpenClaw Gateway 所在机器执行：

openclaw plugins install openclaw-webchat-plugin

2. 配置 openclaw.json

编辑 OpenClaw Gateway 配置文件 ~/.openclaw/openclaw.json，在 channels 中添加 WebChat 配置。

单 Agent 示例（不需要 bindings，走默认路由）：

{
  "channels": {
    "openclaw-webchat": {
      "enabled": true,
      "serverUrl": "wss://your-domain.com/plugin",
      "accounts": {
        "my-webchat": {
          "appId": "wch_a1b2c3d4e5f60708",
          "secret": "***"
        }
      }
    }
  }
}

3. 配置说明

配置项说明
serverUrlChat Server 的 Plugin WebSocket 地址，通常以 /plugin 结尾。
appId当前 WebChat App 的身份 ID。
secret当前 WebChat App 的连接密钥，只应配置在 Gateway 侧。
bindings多 Agent 时，将 WebChat account 绑定到对应 Agent。单 Agent 可省略。

4. 重启 Gateway

openclaw gateway restart

5. 验证

查看 Channel 状态：

openclaw channels list

确认 openclaw-webchat 已安装、已配置并处于启用状态。

或者使用 probe 模式查看详细状态：

openclaw channels status --probe

正常输出示例：

WebChat dev-main: enabled, configured, running, dm:open, allow:*
WebChat dev-2nd: enabled, configured, running, dm:open, allow:*

关键状态说明：enabled（已启用）、configured（已配置）、running（运行中），三个都显示即为正常。

6. 多 Agent 配置 （可选）

如果同一个 Gateway 需要接入多个 WebChat App，可以配置多个 account，并通过 bindings 分别绑定到不同 Agent。

{
  "channels": {
    "openclaw-webchat": {
      "enabled": true,
      "serverUrl": "wss://your-domain.com/plugin",
      "accounts": {
        "dev-webchat": {
          "appId": "wch_dev0000000000000",
          "secret": "***"
        },
        "ops-webchat": {
          "appId": "wch_ops0000000000000",
          "secret": "***"
        }
      }
    }
  },
  "bindings": [
    {
      "agentId": "dev-agent",
      "match": {
        "channel": "openclaw-webchat",
        "accountId": "dev-webchat"
      }
    },
    {
      "agentId": "ops-agent",
      "match": {
        "channel": "openclaw-webchat",
        "accountId": "ops-webchat"
      }
    }
  ]
}

7. 常见问题

如何查看通道状态

openclaw channels status --probe

正常输出示例：

WebChat dev-main: enabled, configured, running, dm:open, allow:*
WebChat dev-2nd: enabled, configured, running, dm:open, allow:*

enabled（已启用）、configured（已配置）、running（运行中），三个都显示即为正常。

not configured

通常表示 openclaw.json 中缺少 openclaw-webchat 配置。

invalid_app

通常表示 appId 不存在或填错。

invalid_secret

通常表示 secret 与 appId 不匹配或填错。