openclawloopchatplugin

v2026.1.31

Published

4 months ago

OpenClaw LoopChat channel plugin

Downloads

0High
0Medium
0Low

sodawater

LoopChat Plugin for OpenClaw

This plugin allows you to integrate your custom chat application with OpenClaw, enabling AI-powered interactions through your own social software.

项目背景

该插件是为了满足用户将自定义社交软件接入 OpenClaw 的需求而开发的。用户可以通过定制 API 和认证方法，实现与 OpenClaw 的无缝集成。

功能特性

多种认证方式：支持环境变量、配置文件和直接配置三种认证方式
灵活的消息处理：支持文本消息和图片消息的发送与接收
两种运行模式：支持 Webhook 和 Polling 两种消息获取模式
代理支持：可以通过代理服务器访问 API
安全的消息过滤：支持多种 DM 策略，包括配对、白名单、开放和禁用

数据流动

1. 配置流程

flowchart TD
    A[用户配置 LoopChat 插件] --> B[设置认证信息\n环境变量/配置文件/直接配置]
    B --> C[配置运行模式\nWebhook 或 Polling]
    C --> D[配置 DM 策略]
    D --> E[启动 OpenClaw]

2. 消息接收流程

Webhook 模式

flowchart TD
    A[用户发送消息到社交软件] --> B[社交软件服务器]  
    B --> C[社交软件调用 OpenClaw Webhook URL]
    C --> D[OpenClaw 接收并解析消息]
    D --> E[OpenClaw 处理消息并生成回复]
    E --> F[OpenClaw 发送回复到社交软件 API]
    F --> G[社交软件服务器]
    G --> H[用户收到回复]

Polling 模式

flowchart TD
    A[用户发送消息到社交软件] --> B[社交软件服务器]
    C[OpenClaw 定期轮询社交软件 API] --> B
    C --> D[OpenClaw 接收并解析消息]
    D --> E[OpenClaw 处理消息并生成回复]
    E --> F[OpenClaw 发送回复到社交软件 API]
    F --> B
    B --> G[用户收到回复]

3. 消息发送流程

flowchart TD
    A[OpenClaw 生成消息] --> B[LoopChat 插件]
    B --> C[解析目标用户 ID]
    C --> D[准备消息内容]
    D --> E[调用社交软件 API]
    E --> F[社交软件服务器]
    F --> G[用户收到消息]

接入指南

1. 准备工作

确保你的社交软件提供以下 API 接口：
- getMe：获取机器人信息
- sendMessage：发送文本消息
- sendPhoto：发送图片消息
- getUpdates：获取更新（Polling 模式）
- setWebhook：设置 Webhook（Webhook 模式）
- deleteWebhook：删除 Webhook
- getWebhookInfo：获取 Webhook 信息
准备认证 Token，用于访问你的社交软件 API

2. 配置步骤

修改 API 基础 URL：在 src/api.ts 文件中，修改 LOOPCHAT_API_BASE 为你的社交软件 API 地址：
```
const LOOPCHAT_API_BASE = "https://api.your-social-app.com";
```
配置认证信息：你可以通过以下三种方式之一配置认证信息：
- 环境变量：设置 LOOPCHAT_BOT_TOKEN 环境变量
- 配置文件：在 openclaw.config.json 中设置 botToken
- Token 文件：通过 tokenFile 指定包含 Token 的文件路径
配置运行模式：
- Webhook 模式：设置 webhookUrl、webhookSecret 和 webhookPath
- Polling 模式：不需要额外配置，默认使用此模式
配置 DM 策略：设置 dmPolicy 为以下值之一：
- pairing：需要配对才能发送消息
- allowlist：只允许白名单中的用户发送消息
- open：允许所有用户发送消息
- disabled：禁用直接消息

3. 安装插件

# 从 npm 安装
npm install @openclaw/loopchatplugin

# 或从本地安装
npm install /path/to/loopchatplugin

4. 启动 OpenClaw

openclaw start

配置示例

基础配置（Polling 模式）

{
  "channels": {
    "loopchat": {
      "enabled": true,
      "botToken": "your-token-here"
    }
  }
}

Webhook 模式配置

{
  "channels": {
    "loopchat": {
      "enabled": true,
      "botToken": "your-token-here",
      "webhookUrl": "https://your-server.com/webhook",
      "webhookSecret": "your-secret-here",
      "webhookPath": "/loopchat"
    }
  }
}

多账号配置

{
  "channels": {
    "loopchat": {
      "enabled": true,
      "defaultAccount": "main",
      "accounts": {
        "main": {
          "enabled": true,
          "botToken": "main-token-here",
          "name": "Main Bot"
        },
        "secondary": {
          "enabled": true,
          "botToken": "secondary-token-here",
          "name": "Secondary Bot"
        }
      }
    }
  }
}

API 接口要求

你的社交软件 API 需要实现以下接口：

1. getMe

请求：

POST https://api.your-social-app.com/bot{token}/getMe

响应：

{
  "ok": true,
  "result": {
    "id": "bot-id",
    "name": "Bot Name",
    "avatar": "https://example.com/avatar.jpg"
  }
}

2. sendMessage

请求：

POST https://api.your-social-app.com/bot{token}/sendMessage
Content-Type: application/json

{
  "chat_id": "user-id",
  "text": "Hello, world!"
}

响应：

{
  "ok": true,
  "result": {
    "message_id": "message-id",
    "from": {
      "id": "bot-id",
      "name": "Bot Name"
    },
    "chat": {
      "id": "user-id",
      "chat_type": "PRIVATE"
    },
    "date": 1620000000,
    "text": "Hello, world!"
  }
}

3. sendPhoto

请求：

POST https://api.your-social-app.com/bot{token}/sendPhoto
Content-Type: application/json

{
  "chat_id": "user-id",
  "photo": "https://example.com/image.jpg",
  "caption": "Photo caption"
}

响应：

{
  "ok": true,
  "result": {
    "message_id": "message-id",
    "from": {
      "id": "bot-id",
      "name": "Bot Name"
    },
    "chat": {
      "id": "user-id",
      "chat_type": "PRIVATE"
    },
    "date": 1620000000,
    "photo": "https://example.com/image.jpg",
    "caption": "Photo caption"
  }
}

4. getUpdates

请求：

POST https://api.your-social-app.com/bot{token}/getUpdates
Content-Type: application/json

{
  "timeout": "30"
}

响应：

{
  "ok": true,
  "result": {
    "event_name": "message.text.received",
    "message": {
      "message_id": "message-id",
      "from": {
        "id": "user-id",
        "name": "User Name"
      },
      "chat": {
        "id": "chat-id",
        "chat_type": "PRIVATE"
      },
      "date": 1620000000,
      "text": "Hello, bot!"
    }
  }
}

5. setWebhook

请求：

POST https://api.your-social-app.com/bot{token}/setWebhook
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "secret_token": "your-secret-here"
}

响应：

{
  "ok": true,
  "result": true
}

6. deleteWebhook

请求：

POST https://api.your-social-app.com/bot{token}/deleteWebhook

响应：

{
  "ok": true,
  "result": true
}

7. getWebhookInfo

请求：

POST https://api.your-social-app.com/bot{token}/getWebhookInfo

响应：

{
  "ok": true,
  "result": {
    "url": "https://your-server.com/webhook",
    "has_custom_certificate": false
  }
}

故障排查

认证失败：检查 Token 是否正确，以及是否有足够的权限
消息发送失败：检查 API 地址是否正确，以及网络连接是否正常
消息接收失败：检查运行模式配置是否正确，Webhook URL 是否可访问
代理问题：如果使用代理，检查代理配置是否正确

总结

通过本插件，你可以轻松将自己的社交软件接入 OpenClaw，实现 AI 驱动的交互体验。只需按照上述指南配置 API 地址、认证信息和运行模式，即可完成集成。

如果你有任何问题或需要进一步的帮助，请参考 OpenClaw 官方文档或联系支持团队。