XG CWork 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

安装

推荐同事通过 npm 安装，无需访问内部 Git；需要改源码时再从内部仓库克隆（方法 B）。

方法 A：通过 npm 包安装（推荐）

一条命令完成安装，依赖由 OpenClaw 自动处理：

openclaw plugins install @xgjktech/xg_cwork_im

运行 openclaw plugins list 确认列表中有 xg_cwork_im 即可。

方法 B：通过本地源码安装

如需二次开发或无法使用 npm 安装时，可从内部 Git 克隆后以链接模式安装：

git clone http://192.168.3.200/openclaw/openclaw-channel-xg-cwork-im.git
cd openclaw-channel-xg-cwork-im
npm install
openclaw plugins install -l .

方法 C：手动安装

1. 将本仓库下载或复制到 ~/.openclaw/extensions/xg_cwork_im（Windows 为 %USERPROFILE%\.openclaw\extensions\xg_cwork_im）。
2. 确保目录内包含 index.ts、openclaw.plugin.json、package.json。
3. 在该目录执行 npm install --omit=dev 或 npm run install:prod 安装依赖。
4. 运行 openclaw plugins list 确认 xg_cwork_im 已显示。

方法 D：国内网络环境（npm 镜像源）

若执行 openclaw plugins install @xgjktech/xg_cwork_im 时卡在「Installing plugin dependencies...」或出现 npm install failed，可临时指定国内镜像源：

NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @xgjktech/xg_cwork_im

若插件已半安装（扩展目录存在但依赖未装全），可进入插件目录手动补装：

cd ~/.openclaw/extensions/xg_cwork_im
# Windows: cd %USERPROFILE%\.openclaw\extensions\xg_cwork_im
rm -rf node_modules package-lock.json
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com npm install

更新已安装的插件

当插件发布新版本后，已安装的用户可按以下方式更新。

通过 npm 安装的（方法 A）

使用插件 id（不是 npm 包名）执行更新：

openclaw plugins update xg_cwork_im

更新完成后执行 openclaw gateway restart 使新版本生效。

国内网络可临时指定镜像源后再更新：

NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins update xg_cwork_im

通过本地源码 / 链接安装的（方法 B）

在插件目录拉取最新代码后重启网关：

cd openclaw-channel-xg-cwork-im   # 进入当时克隆的目录
git pull
npm install
openclaw gateway restart

手动安装的（方法 C）

重新从内部 Git 下载或复制最新代码到 ~/.openclaw/extensions/xg_cwork_im，在该目录执行 npm install --omit=dev 或 npm run install:prod，再执行 openclaw gateway restart。

配置

步骤 1：启用并信任插件

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

openclaw plugins enable xg_cwork_im

步骤 2：配置 Channel 账户信息

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

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

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

步骤 3：重启 Gateway

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

openclaw gateway restart

完整配置参考

~/.openclaw/openclaw.json 参考结构（示例使用 CWork 测试/生产域名，详细请参考 docs/im服务接口说明.md）：

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

生产环境配置示例

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

配置项说明

顶层配置（channels.xg_cwork_im）

| 选项 | 类型 | 默认值 | 说明 | |---|---|---|---| | 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-cwork-im/
├── index.ts                # 插件入口
├── src/
│   ├── types.ts            # 类型定义
│   ├── auth.ts             # 认证（appKey → token）
│   ├── connection.ts       # WebSocket 连接管理
│   ├── send-service.ts     # IM 消息发送
│   ├── group-history-tool.ts      # 拉取群消息历史的 Agent Tool
│   ├── send-group-message-tool.ts # 发送群消息的 Agent Tool
│   └── channel.ts          # Channel Plugin 主定义
├── package.json
├── tsconfig.json
├── openclaw.plugin.json
└── README.md

代码仓库与发布流程说明

• 代码仓库：本项目在内部 Git 管理，地址：http://192.168.3.200/openclaw/openclaw-channel-xg-cwork-im，不推送到 GitHub。
• 安装方式：同事安装请优先使用 npm（方法 A）；需要改源码时从内部 Git 克隆（方法 B）。
• 发布流程：在内部 Git 上开发、提交后，由维护者发布到 npm；同事通过 openclaw plugins install @xgjktech/xg_cwork_im 安装，无需访问 Git。

维护者：如何发布到 npm（详细步骤）

代码在内部 Git 上维护，发布到 npm 后同事即可一条命令安装。按下列步骤操作。

步骤 1：在 npm 注册 / 登录

1. 无 npm 账号：打开 https://www.npmjs.com/signup 注册。
2. 在项目根目录执行：

npm login

3. 按提示输入 Username、Password、Email。
4. 若账号开启了双因素认证（2FA），发布时必须使用：
   • 在 npm 网站 Access Tokens 里创建 Granular Access Token，勾选 Publish packages，并勾选 Bypass 2FA；或
   • 在命令行登录时使用 OTP（一次性密码）。
     否则会报错：Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages。

步骤 2：确认 scope 与权限

• 包名为 @xgjktech/xg_cwork_im，属于 scope @xgjktech。
• 在 npm 官网 登录 → Organizations → Create，创建组织名为 xgjktech，确保你的账号有该组织的发布权限。
• 若改用个人 scope（如 @你的用户名/xg_cwork_im），需修改 package.json 的 "name" 并同步改 README 中的安装命令。

步骤 3：发布前检查

在项目根目录执行：

npm pack --dry-run

确认列出的文件无敏感内容（如 .env、密钥）。发布内容由 package.json 的 "files" 控制。

步骤 4：执行发布

scoped 包必须加 --access public，否则会按私有包计费并可能报 402：

npm publish --access public

成功后可在此查看：
https://www.npmjs.com/package/@xgjktech/xg_cwork_im

步骤 5：后续更新（重新推送到 npm）

每次发新版本都按下面做一遍即可：

1. 在内部 Git 上改代码、提交、推送。
2. 在 package.json 里把 version 升高（如 1.0.0 → 1.0.1），保存。
3. 在项目根目录执行：

npm publish --access public

4. 通知同事执行 更新已安装的插件（见上文「更新已安装的插件」），例如：
   openclaw plugins update xg_cwork_im → openclaw gateway restart。

（若该 scope 已发过公开包，有时可只执行 npm publish，建议仍带 --access public 避免误发成私有。）

常见问题

| 报错或现象 | 原因 | 处理 | |-----------|------|------| | 403 Forbidden，且提示需 2FA 或 token | 账号开启 2FA 后，普通登录无法发布 | 使用 Granular Access Token（勾选 Publish + Bypass 2FA），或在发布时提供 OTP | | 403 Forbidden，无 2FA 提示 | 当前账号无 @xgjktech 发布权限 | 在 npm 创建/加入组织 xgjktech，或将包名改为个人 scope | | 402 Payment Required | 未加 --access public，scoped 包被视为私有 | 执行 npm publish --access public | | 国内网络登录/发布慢或超时 | 默认 registry 在国外 | 登录：npm login --registry=https://registry.npmjs.org/；发布时也可加 --registry=https://registry.npmjs.org/，不推荐长期用第三方镜像发布 |