@linchengyu-org/switchbot-channel

SwitchBot Channel for OpenClaw

Connect your SwitchBot smart home devices to OpenClaw platform for real-time device status monitoring | 将您的 SwitchBot 智能家居设备连接到 OpenClaw 平台，实时监控设备状态变化

🌐 Language | 语言

• 🇺🇸 English
• 🇨🇳 中文

English

📖 Project Overview

SwitchBot Channel is an official channel plugin for the OpenClaw platform that receives real-time SwitchBot device status changes via MQTT protocol. Whether it's contact sensors, temperature/humidity meters, or smart plugs, you can monitor device status in real-time through OpenClaw and set up intelligent notifications.

✨ Features

• 🔄 Real-time Sync: Receive device status via MQTT in real-time
• 🏠 Device Compatibility: Support for all mainstream SwitchBot devices
• 🔑 Auto Authentication: Intelligent credential management with auto-renewal
• 🚨 Smart Notifications: Send notifications only for important events to avoid interruptions
• 🔧 Zero Configuration: Out-of-the-box functionality with just SwitchBot Token and Secret
• 📊 History Records: Local storage of device status history
• 🛡️ High Availability: Auto-reconnection with automatic recovery after network interruptions

🚀 Quick Start

System Requirements

• OpenClaw: >= 2026.1.0
• Node.js: >= 18.0.0
• SwitchBot App: Latest version

Step 1: Install Plugin

Prerequisites

Before installing the plugin, ensure your OpenClaw environment has the required dependencies:

# Install pnpm if not already installed
npm install -g pnpm

# Install dependencies in your OpenClaw installation
pnpm install

Installation

# Install plugin from npm
openclaw plugins install @linchengyu-org/switchbot-channel

# Verify installation
openclaw plugins list

Step 2: Get SwitchBot Credentials

• Open SwitchBot App

• Enter Developer Options:

  • Tap "Settings" in bottom right
  • Find and tap "Developer Options"
  • If this option doesn't exist, ensure the App is updated to the latest version

• Get Credentials:

  • Record the Token (64-character string)
  • Record the Secret (32-character string)

⚠️ Important: Keep your Token and Secret secure and don't share them with others

Step 3: Configure OpenClaw

Edit OpenClaw configuration file ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "switchbot-channel": {
        "enabled": true
      }
    }
  },
  "channels": {
    "switchbot": {
      "enabled": true,
      "token": "your_switchbot_token_here",
      "secret": "your_switchbot_secret_here"
    }
  }
}

Step 4: Start Service

# Restart OpenClaw Gateway
openclaw gateway restart

# Check plugin status
openclaw status

⚙️ Configuration Details

Basic Configuration

{
  "channels": {
    "switchbot": {
      "enabled": true,
      "token": "xxxx",
      "secret": "xxxx"
    }
  }
}

📱 Usage Guide

Device Status Monitoring

After the plugin starts, it will automatically receive status changes from all devices. You can view them using:

# View device status
openclaw devices list switchbot

# View specific device
openclaw devices show <device_id>

🔍 Troubleshooting

Common Issues

Q: Plugin fails to start

A: Check configuration

# Check configuration syntax
openclaw config validate

# View detailed errors
openclaw gateway logs --follow

Debug Mode

Enable detailed logging for troubleshooting:

{
  "logging": {
    "level": "debug",
    "channels": {
      "switchbot": "debug"
    }
  }
}

View logs:

# View real-time logs
tail -f ~/.openclaw/logs/gateway.log | grep "SwitchBot"

# View error logs
openclaw gateway logs --level error

Reset Plugin

If you encounter serious issues, you can reset the plugin:

# Stop service
openclaw gateway stop

# Clear plugin cache
rm -rf ~/.openclaw/cache/plugins/switchbot

# Restart
openclaw gateway start

中文

📖 项目简介

SwitchBot Channel 是 OpenClaw 平台的官方渠道插件，通过 MQTT 协议实时接收 SwitchBot 设备状态变化。无论是门窗传感器、温湿度计还是智能插座，您都可以在 OpenClaw 中实时了解设备状态，并设置智能通知。

✨ 功能特性

• 🔄 实时同步：通过 MQTT 实时接收设备状态
• 🏠 设备兼容：支持所有主流 SwitchBot 设备
• 🔑 自动认证：智能管理凭证，自动续期
• 🚨 智能通知：仅在重要事件时发送通知，避免打扰
• 🔧 零配置：开箱即用，只需 SwitchBot Token 和 Secret
• 📊 历史记录：本地存储设备状态历史
• 🛡️ 高可用：自动重连，网络中断后自动恢复

🚀 快速开始

系统要求

• OpenClaw: >= 2026.1.0
• Node.js: >= 18.0.0
• SwitchBot App: 最新版本

第一步：安装插件

前置要求

安装插件前，请确保您的 OpenClaw 环境已安装所需依赖：

# 安装 pnpm（如果尚未安装）
npm install -g pnpm

# 在您的 OpenClaw 安装目录中安装依赖
pnpm install

安装插件

# 从 npm 安装插件
openclaw plugins install @linchengyu-org/switchbot-channel

# 验证安装
openclaw plugins list

第二步：获取 SwitchBot 凭证

• 打开 SwitchBot App

• 进入开发者选项：

  • 点击右下角 "设置"
  • 找到并点击 "开发者选项"
  • 如果没有此选项，请确保 App 为最新版本

• 获取凭证：

  • 记录 Token (64位字符串)
  • 记录 Secret (32位字符串)

⚠️ 重要提示：请妥善保管您的 Token 和 Secret，不要泄露给他人

第三步：配置 OpenClaw

编辑 OpenClaw 配置文件 ~/.openclaw/openclaw.json：

{
  "plugins": {
    "entries": {
      "switchbot-channel": {
        "enabled": true
      }
    }
  },
  "channels": {
    "switchbot": {
      "enabled": true,
      "token": "your_switchbot_token_here",
      "secret": "your_switchbot_secret_here"
    }
  }
}

第四步：启动服务

# 重启 OpenClaw Gateway
openclaw gateway restart

# 检查插件状态
openclaw status

⚙️ 配置详解

基本配置

{
  "channels": {
    "switchbot": {
      "enabled": true,
      "token": "xxxx",
      "secret": "xxxx"
    }
  }
}

📱 使用指南

设备状态监控

插件启动后会自动接收所有设备的状态变化，您可以通过以下方式查看：

# 查看设备状态
openclaw devices list switchbot

# 查看具体设备
openclaw devices show <device_id>

🔍 故障排除

常见问题

Q: 插件无法启动

A: 检查配置

# 检查配置语法
openclaw config validate

# 查看详细错误
openclaw gateway logs --follow

调试模式

启用详细日志进行问题诊断：

{
  "logging": {
    "level": "debug",
    "channels": {
      "switchbot": "debug"
    }
  }
}

查看日志：

# 实时查看日志
tail -f ~/.openclaw/logs/gateway.log | grep "SwitchBot"

# 查看错误日志
openclaw gateway logs --level error

重置插件

如果遇到严重问题，可以重置插件：

# 停止服务
openclaw gateway stop

# 清理插件缓存
rm -rf ~/.openclaw/cache/plugins/switchbot

# 重新启动
openclaw gateway start

Made with ❤️ by the SwitchBot Team