XG-IM Channel for OpenClaw

公司内部 IM 机器人 Channel 插件，通过 WebSocket 长连接接收 @ 消息，由 OpenClaw AI 处理后自动回复。

工作原理

IM 系统  →  WebSocket  →  插件（本项目）  →  OpenClaw AI  →  IM 发送接口  →  IM 系统

1. 插件启动时用 appKey 换取 access_token 和 userId
2. 建立 WebSocket 长连接，接收 robotMention 事件
3. 将收到的消息转发给 OpenClaw 处理
4. OpenClaw AI 回复后，插件调用 IM 接口发送消息并 @ 原始发送者

前置条件

• 已安装 OpenClaw (>=2026.2.13)
• 已在 IM 后台注册机器人，获取到 appKey

安装

方式 A：推荐安装（npm）

这是最简单、快捷的安装方式。

openclaw plugins install @xgjktech/xgim

方式 B：本地源码安装（开发者）

如果你需要对插件进行二次开发或者调试，请克隆源码并以链接模式安装。

# 1. 克隆仓库
git clone <内部 Git 地址> openclaw-channel-xg-im
cd openclaw-channel-xg-im

# 2. 安装所有依赖
npm install

# 3. 以链接模式安装到 OpenClaw
openclaw plugins install -l .

方式 C：离线/手动安装

1. 下载项目源码并解压到 ~/.openclaw/extensions/xgim 目录。
2. 在该目录下执行 npm install --omit=dev。
3. 运行 openclaw plugins list 确认 xgim 已加载。

升级/更新

若需要将插件更新到最新版本，请执行：

openclaw plugins update @xgjktech/xgim

配置

步骤 1：启用并信任插件

执行以下命令，将 xgim 插件添加到 OpenClaw 的信任白名单中：

openclaw plugins enable xgim

步骤 2：配置 Channel 账户信息

编辑 ~/.openclaw/openclaw.json，添加以下配置：

{
  "channels": {
    "xgim": {
      "baseUrl": "https://test.xgjktech.com.cn",
      "wsBaseUrl": "wss://websocket.xgjktech.com.cn",
      "accounts": [
        { "appKey": "你的机器人 appKey", "agentId": "main", "name": "个人助手" }
      ]
    }
  }
}

多账户：如有多个机器人，在 accounts 数组里继续追加即可，每个账户可指定不同的 agentId 对应不同的 OpenClaw Agent。

步骤 3：重启 Gateway

配置完成后，重启网关使配置生效：

openclaw gateway restart

完整配置参考

~/.openclaw/openclaw.json 参考结构：

{
  "plugins": {
    "enabled": true,
    "allow": ["xgim"]
  },
  "channels": {
    "xgim": {
      "baseUrl": "https://test.xgjktech.com.cn",
      "wsBaseUrl": "wss://websocket.xgjktech.com.cn",
      "groupPolicy": "mention",
      "debug": false,
      "accounts": [
        { "appKey": "appKey_机器人A", "agentId": "main",  "name": "个人助手" },
        { "appKey": "appKey_机器人B", "agentId": "sales", "name": "销售助手" }
      ]
    }
  }
}

生产环境配置示例

{
  "channels": {
    "xgim": {
      "baseUrl": "https://xg.mediportal.com.cn",
      "wsBaseUrl": "wss://websocket.mediportal.com.cn",
      "groupPolicy": "mention",
      "debug": false,
      "maxConnectionAttempts": 20,
      "maxReconnectDelay": 120000,
      "accounts": [
        { "appKey": "你的生产 appKey", "agentId": "main", "name": "个人助手" }
      ]
    }
  }
}

配置项说明

顶层配置（channels.xgim）

| 选项 | 类型 | 默认值 | 说明 | |---|---|---|---| | baseUrl | string | 必填 | IM 服务域名（API 接口地址） | | wsBaseUrl | string | — | 可选。WebSocket 独立域名。若不填，插件将尝试自动映射。 | | groupPolicy | string | "mention" | open=收全部消息；mention=仅 @ 机器人触发 | | enabled | boolean | true | 是否启用 | | debug | boolean | false | 开启调试日志 | | maxConnectionAttempts | number | 10 | WebSocket 最大重连次数 | | initialReconnectDelay | number | 1000 | 初始重连延迟（ms） | | maxReconnectDelay | number | 60000 | 最大重连延迟（ms） | | reconnectJitter | number | 0.3 | 重连抖动因子（0-1） |

账户配置（accounts[n]）

| 选项 | 类型 | 默认值 | 说明 | |---|---|---|---| | appKey | string | 必填 | 机器人 appKey（IM 后台注册获取） | | agentId | string | "main" | 对应的 OpenClaw Agent ID | | name | string | — | 账户显示名称（仅用于日志标识） | | groupPolicy | string | 继承顶层 | 可覆盖顶层的 groupPolicy |

故障排除

收不到消息

• 确认 appKey 正确，且机器人已在 IM 后台激活
• 查看 OpenClaw 日志，确认 WebSocket 连接成功（WebSocket connected successfully）
• 群聊中确认已 @ 机器人

WebSocket 频繁断连

• 检查网络稳定性
• 适当增大 maxConnectionAttempts 和 maxReconnectDelay
• 开启 debug: true 查看详细日志

token 相关报错

• 确认 baseUrl 域名可达
• 确认 appKey 有效（可在 IM 后台查看机器人状态）

项目结构

openclaw-channel-xg-im/
├── index.ts                # 插件入口
├── src/
│   ├── types.ts            # 类型定义
│   ├── auth.ts             # 认证（appKey → token）
│   ├── connection.ts       # WebSocket 连接管理
│   ├── send-service.ts     # IM 消息发送
│   └── channel.ts          # Channel Plugin 主定义
├── package.json
├── tsconfig.json
├── openclaw.plugin.json
└── README.md