智能家居自动化进阶：基于crazyrouter-skill的跨平台规则引擎实战

1. 项目概述与核心思路

最近在折腾智能家居的自动化流程，发现市面上的主流平台虽然功能强大，但总感觉在设备联动和场景自定义上差了那么点意思。要么是支持的设备品牌有限，要么是逻辑编排不够灵活，想实现一个稍微复杂点的“如果A发生，并且B不处于C状态，就执行D和E，但只在晚上8点到10点之间生效”这样的规则，往往需要东拼西凑好几个自动化，维护起来头大。正是在这种背景下，我接触到了crazyrouter-skill这个项目。简单来说，它不是一个独立的智能家居平台，而是一个“技能包”或者说“集成插件”，它的目标是把不同来源、不同协议的设备和服务，通过一套统一的、高度灵活的规则引擎连接起来，让你能像搭积木一样构建复杂的自动化场景。

你可以把它想象成一个超级智能的“交通指挥中心”。你家里的每一个智能设备、每一项网络服务（比如天气API、日历提醒）都是一辆辆不同品牌、不同型号的车。crazyrouter-skill就是这个指挥中心的核心调度系统，它不仅能识别所有车辆（设备接入），还能理解复杂的交通规则（逻辑编排），并根据实时路况（设备状态变化、外部事件）做出精准的调度指令。它的核心价值在于“解耦”和“赋能”：将设备接入与业务逻辑分离，让用户专注于设计场景，而无需深究底层通信协议。

这个项目特别适合两类朋友：一是已经拥有多个品牌智能设备，苦于无法实现跨平台联动的资深玩家；二是喜欢钻研技术，不满足于图形化界面提供的有限功能，希望用代码级精度控制家庭自动化的开发者。接下来，我会详细拆解它的设计思路、如何部署使用，以及我在实际折腾过程中积累的一些实战心得和避坑指南。

2. 核心架构与组件解析

要玩转crazyrouter-skill，首先得理解它的几个核心组成部分。整个项目生态主要围绕crazyrouter-api-skill展开，这也是我们配置和交互的主要对象。

2.1 crazyrouter-api-skill：集成的枢纽

crazyrouter-api-skill是整个技能体系的核心接口。它本身不直接控制设备，而是扮演了一个“适配器”和“规则执行器”的角色。它的主要工作包括：

1. 协议转换与统一：它通过内部封装的各类插件（Plugin），与不同的智能家居平台（如Home Assistant、OpenClaw等）或设备协议（如MQTT、HTTP）进行通信。它将不同平台特有的API和数据格式，转换为一套内部统一的“事件”和“动作”模型。
2. 暴露标准化接口：对外，它提供一套清晰的RESTful API或WebSocket接口。这意味着你可以通过发送HTTP请求或监听WebSocket消息，来查询设备状态、触发动作，或者接收设备状态变更的通知。
3. 承载业务逻辑：虽然复杂的规则引擎可能由更上层的crazyrouter-core处理，但api-skill通常是规则触发的入口和出口。规则引擎判断条件满足后，会调用api-skill提供的接口来执行具体的设备操作。

注意：在开源生态中，项目名有时会变化或存在多个相关仓库。crazyrouter-skill可能指代一个更上层的概念或聚合项目，而crazyrouter-api-skill是其中一个具体的、提供集成接口的组件。实际操作时，务必根据官方文档确认你正在部署和配置的是哪个具体仓库。

2.2 与 OpenClaw 等平台的关系

关键词中提到了OpenClaw，这很可能是一个与crazyrouter项目紧密相关的智能家居平台或框架。它们之间的关系通常是这样的：

• OpenClaw 作为设备管理层：OpenClaw 可能负责最底层的设备发现、连接、驱动管理和状态维护。它直接和灯泡、插座、传感器等硬件打交道，维护着一个实时的设备状态库。
• crazyrouter-skill 作为自动化逻辑层：crazyrouter-api-skill通过特定的插件与 OpenClaw 的API进行对接。它从 OpenClaw 订阅设备状态变更事件（例如“客厅温度传感器读数更新为25°C”），同时也能向 OpenClaw 发送控制指令（例如“关闭卧室主灯”）。
• 分工协作：这种架构实现了关注点分离。OpenClaw 专心做好设备兼容性和稳定性；crazyrouter 则专注于提供强大的逻辑编排能力。两者通过api-skill这个桥梁高效协作。

2.3 “Skills” 技能生态

“Skills”是该项目一个非常重要的概念。你可以把一个 Skill（技能）理解为一个功能模块或一个场景应用。例如：

• “离家模式”技能：当所有家庭成员手机蓝牙离开WiFi范围时，自动执行关闭所有灯光、调低暖气、启动安防摄像头的系列动作。
• “影院模式”技能：对语音助手或点击一个按钮说“打开影院模式”，技能会依次调暗灯光、关闭窗帘、打开投影仪和功放。
• “清晨唤醒”技能：在工作日早上7点，缓慢点亮卧室灯光，播放轻柔的音乐，并播报当天的天气和日程。

在crazyrouter的体系中，这些技能可能以配置文件、脚本或插件的形式存在。crazyrouter-api-skill提供了触发和执行这些技能的接口。开发者可以编写自己的技能，丰富自动化场景。

3. 部署与基础配置实战

理论讲完了，我们动手把它跑起来。这里我会以在常驻服务器（例如家庭NAS、树莓派或云主机）上部署为例，假设我们使用的是crazyrouter-api-skill的Docker镜像，这是目前最通用和简洁的方式。

3.1 环境准备与部署

首先，确保你的服务器已经安装了 Docker 和 Docker Compose。这是后续所有操作的基础。

1. 获取配置文件：通常项目会提供一个docker-compose.yml示例文件。你需要创建项目目录并下载或创建此文件。

   mkdir -p ~/crazyrouter && cd ~/crazyrouter # 假设从项目仓库获取 compose 文件，请替换为实际地址 # wget https://raw.githubusercontent.com/xujfcn/crazyrouter-api-skill/main/docker-compose.yml # 这里我们手动创建一个基本的 cat > docker-compose.yml << 'EOF' version: '3.8' services: crazyrouter-api: image: xujfcn/crazyrouter-api-skill:latest # 请使用官方镜像标签 container_name: crazyrouter-api restart: unless-stopped ports: - "8080:8080" # 将容器内API端口映射到宿主机 volumes: - ./config:/app/config:ro # 挂载配置文件目录 - ./data:/app/data # 挂载数据持久化目录 environment: - TZ=Asia/Shanghai # 设置时区 # 更多环境变量根据文档配置 EOF

2. 配置对接信息：核心配置在于如何让api-skill连接到你的智能家居平台（如 OpenClaw）。这通常通过配置文件或环境变量完成。

   • 在项目目录下创建config文件夹和配置文件，例如config/settings.yaml。
   • 配置文件内容需要根据你要对接的平台来写。假设对接 OpenClaw，可能需要配置其服务器的IP、端口、认证令牌（API Token）等。

   # config/settings.yaml 示例 (具体结构请查官方文档) integrations: openclaw: enabled: true host: http://你的openclaw服务器IP:8123 # OpenClaw API地址 access_token: "你的OpenClaw长期访问令牌" # 在OpenClaw后台生成 # 可能还有其他选项，如事件过滤、实体选择等 api: host: 0.0.0.0 port: 8080 logging: level: INFO

   实操心得：access_token是关键，务必在 OpenClaw 的“用户配置”中创建一个用于长期访问的令牌，并妥善保管。不要使用管理员账户的密码。首次配置时，建议将logging.level设为DEBUG，以便在容器日志中查看详细的连接和通信过程，方便排错。

3. 启动服务：配置完成后，使用 Docker Compose 启动服务。

   docker-compose up -d

   使用docker-compose logs -f crazyrouter-api查看实时日志，确认服务正常启动，并且成功连接到了 OpenClaw 或其他配置的平台。

3.2 验证与初步测试

服务启动后，我们需要验证 API 是否工作正常。

1. 健康检查：访问http://你的服务器IP:8080/health或/，看是否返回成功状态。
2. 查看已接入设备：根据 API 文档，调用类似GET http://你的服务器IP:8080/api/devices的接口（具体端点请查证文档），应该能返回一份从 OpenClaw 同步过来的设备列表，其中包含了每个设备的唯一ID、名称、类型、状态等信息。
3. 测试设备控制：找一个简单的设备（比如一个开关灯），调用控制接口。例如：

   # 假设控制接口为 POST /api/devices/{device_id}/action # 设备ID可以从设备列表接口获取 curl -X POST http://localhost:8080/api/devices/light.bedroom_main/action \ -H "Content-Type: application/json" \ -d '{"action": "turn_on", "params": {"brightness": 75}}'

   如果配置正确，你应该能看到卧室主灯被打开并调至75%亮度，同时在crazyrouter-api和 OpenClaw 的日志中看到相应的动作记录。

避坑指南：首次测试时，最容易出现的问题是网络连通性和认证错误。

• 网络问题：确保crazyrouter-api容器能访问到 OpenClaw 服务器的IP和端口。如果它们不在同一台主机，检查防火墙规则。在docker-compose.yml中，如果使用主机网络模式（network_mode: "host"）可以简化网络配置，但要注意端口冲突。
• 认证错误：仔细检查配置文件中的access_token，确保没有多余的空格或换行。可以在命令行用curl直接测试 OpenClaw 的 API 是否可用：curl -H "Authorization: Bearer YOUR_TOKEN" http://openclaw-host:8123/api/states。
• 设备ID不匹配：从crazyrouter-api获取的设备ID，必须与调用控制接口时使用的ID完全一致。这些ID通常由平台（如OpenClaw）定义，是大小写敏感的。

4. 核心技能开发与规则编排

基础打通后，就进入了最有趣的部分——创建你自己的自动化技能。这里我们探讨两种常见方式：通过 API 触发预设技能，以及使用更灵活的规则引擎。

4.1 通过 API 调用技能

如果crazyrouter-api-skill管理着一些预定义的技能（比如“影院模式”、“睡眠模式”），那么通常会提供对应的API端点来触发它们。

1. 技能发现：首先调用技能列表接口，例如GET /api/skills，查看当前可用的技能及其ID。

2. 触发技能：向技能触发接口发送请求。例如，触发一个名为“goodnight”的技能：

   curl -X POST http://localhost:8080/api/skills/goodnight/execute

   这个请求会触发crazyrouter后端执行与“goodnight”技能关联的一系列动作序列。

3. 传递参数：更高级的技能可能支持参数。例如，一个“调节灯光”的技能可能需要颜色和亮度参数。

   curl -X POST http://localhost:8080/api/skills/adjust_living_room_light/execute \ -H "Content-Type: application/json" \ -d '{"color": "warm_white", "brightness": 50}'

   这种方式适合将复杂的联动封装成简单的HTTP调用，方便与语音助手（如自己搭建的Chatbot）、物理按钮（通过ESP8266发送HTTP请求）或移动端App集成。

4.2 使用规则引擎实现复杂逻辑

对于动态的、条件复杂的场景，预定义技能可能不够用。这时就需要用到规则引擎。crazyrouter的核心优势可能就在于其内置的或可扩展的规则引擎。规则通常由“触发器（Trigger）”、“条件（Condition）”和“动作（Action）”三部分组成。

假设我们想实现一个规则：“如果晚上10点后，客厅有人移动且主灯已关闭，则自动开启客厅小夜灯，并在5分钟后自动关闭。”

我们需要在crazyrouter的规则配置文件中定义这条规则。规则可能以YAML或JSON格式定义。

# rules/auto_night_light.yaml rules: - id: "auto_night_light_living_room" name: "客厅夜间自动小夜灯" description: "夜间有人活动且主灯关闭时，开启小夜灯并定时关闭" triggers: # 触发器1：时间表，晚上10点到早上6点 - platform: "time" at: "22:00" # 触发器2：运动传感器状态变为“on” - platform: "state" # 假设从OpenClaw接收状态事件 entity_id: "binary_sensor.living_room_motion" to: "on" conditions: # 条件1：当前时间在晚上10点后（或通过另一个时间条件） - condition: "time" after: "22:00" before: "06:00" # 条件2：客厅主灯状态是“off” - condition: "state" entity_id: "light.living_room_main" state: "off" # 条件3：可以添加星期条件，例如仅工作日 - condition: "time" weekday: - mon - tue - wed - thu - fri actions: # 动作1：立即打开小夜灯，亮度设为20% - service: "light.turn_on" # 这个服务名会由api-skill映射到具体平台调用 target: entity_id: "light.living_room_night_light" data: brightness_pct: 20 color_temp: 300 # 暖黄光 # 动作2：等待5分钟（300秒） - delay: minutes: 5 # 动作3：关闭小夜灯 - service: "light.turn_off" target: entity_id: "light.living_room_night_light"

规则解析与要点：

• 触发器：规则可以由多个触发器中的任意一个激活。这里配置了时间和运动两个触发器，意味着无论是晚上10点整，还是10点后任何时刻检测到运动，都会尝试执行规则。
• 条件：所有条件必须同时满足，规则的动作才会执行。即使运动传感器触发了，如果主灯是开着的，或者不是工作日，小夜灯也不会亮。这实现了“与”逻辑。
• 动作序列：动作按顺序执行。这里实现了“开灯 -> 等待 -> 关灯”的序列。
• 防抖与重置：这是一个实际应用中必须考虑的问题。如果5分钟内多次触发运动，我们不希望小夜灯被反复开关。这需要在规则引擎中设置“防抖”或“重置”逻辑。例如，在动作执行期间，忽略同一规则的再次触发；或者每次触发运动时，都重置5分钟的计时器。这通常取决于规则引擎的高级特性，可能需要查阅文档使用mode: single（单次）或for:等参数来实现。

经验之谈：编写复杂规则时，强烈建议先在测试环境或使用虚拟设备进行验证。可以临时修改时间条件或手动触发传感器来模拟场景。规则引擎的调试日志非常重要，确保日志级别打开，观察规则的触发、条件判断和动作执行流程。

5. 高级集成与外部系统联动

crazyrouter-api-skill的威力不仅在于控制设备，更在于它能成为智能家居的“消息总线”和“逻辑中枢”，与外部系统无缝集成。

5.1 与消息平台和语音助手集成

你可以通过调用其API，将智能家居状态或警报发送到钉钉、企业微信、Telegram等平台，或者接收来自这些平台的指令。

示例：当安防摄像头检测到陌生人时，发送照片和通知到Telegram。

1. 在crazyrouter中创建规则：触发器是安防AI事件，动作是调用一个“发送到Telegram”的技能或直接调用一个Webhook。
2. 编写一个简单的Web服务（或使用Serverless函数）：这个服务接收来自crazyrouter的Webhook请求（包含事件详情和图片URL），然后调用Telegram Bot API将消息发送到指定聊天。
3. 在crazyrouter规则中调用Webhook：

   actions: - service: "webhook" target: url: "https://你的服务地址/alert/telegram" data: event_type: "security.intrusion" camera_id: "camera.doorbell" image_url: "{{ trigger.event.data.snapshot_url }}" # 使用模板变量 timestamp: "{{ now() }}"

4. 反向控制：你也可以在Telegram Bot中设置命令，当用户发送/lights_on时，Bot向crazyrouter的API发送请求，触发对应的开灯技能。

5.2 利用Webhook实现无限可能

Webhook是crazyrouter-api-skill与外部世界交互的利器。它既可以作为动作（输出），也可以作为触发器（输入）。

• 作为输出：如上例，将家居事件推送给第三方服务。
• 作为输入：在crazyrouter中配置一个Webhook触发器，当收到特定URL的POST请求时，触发一条规则。这允许任何能发送HTTP请求的系统来控制你的智能家居。比如：
  • IFTTT / Zapier：可以将成千上万的应用服务与你的智能家居连接。
  • 日历服务：在Google Calendar上创建一个“电影之夜”事件，事件开始时自动触发家庭影院模式。
  • 自定义硬件：一个自制的物联网按钮，按下后发送Webhook请求来切换场景。

配置Webhook触发器通常需要在crazyrouter中生成一个唯一的、安全的URL端点，并可能设置一个认证令牌。

5.3 状态管理与历史数据

一个成熟的自动化系统离不开状态管理和历史记录。crazyrouter-api-skill可能本身不长期存储历史数据，但它可以与专门的时间序列数据库（如InfluxDB）或日志系统集成。

• 状态订阅：外部系统可以订阅crazyrouter的WebSocket流，实时接收所有设备的状态变更事件，用于更新自己的UI或进行实时分析。
• 数据上报：在规则动作中，可以添加将关键数据（如传感器读数、操作记录）通过HTTP API发送到InfluxDB或Home Assistant的历史记录组件进行存储。
• 基于历史的条件：更高级的规则可能需要查询历史数据作为条件，例如“如果过去一小时内平均温度高于28度，则打开空调”。这可能需要规则引擎支持调用外部查询接口，或者将数据先存储到crazyrouter可访问的数据库中。

6. 性能调优、监控与故障排查

当你的自动化规则越来越多，系统稳定运行就变得至关重要。

6.1 性能考量与优化建议

1. 规则复杂度：避免编写包含过多条件或嵌套过深的规则。复杂的规则会增加引擎的处理时间。尽量将大规则拆分成多个小规则，逻辑更清晰，也便于调试。
2. 触发器频率：高频触发器（如每秒都在更新的传感器）要谨慎处理。如果规则条件判断开销大，可能会拖慢整个系统。对于这类数据，考虑在规则中增加“条件过滤”或“采样率限制”，或者先在设备端或接入层进行预处理（如只在数值变化超过阈值时才上报）。
3. 动作延迟与超时：网络设备控制可能有延迟或失败。在规则动作中，要为设备服务调用设置合理的超时时间，并考虑失败重试机制。避免因一个设备无响应导致整个规则序列卡住。
4. 资源监控：监控运行crazyrouter-api-skill的容器的CPU、内存占用。如果规则非常多且复杂，可能需要调整Docker容器的资源限制（deploy.resources.limitsin compose）。

6.2 系统监控与日志分析

完善的日志是排查问题的生命线。

1. 结构化日志：确保crazyrouter-api-skill配置为输出结构化日志（如JSON格式），这样方便使用ELK（Elasticsearch, Logstash, Kibana）或Grafana Loki进行收集、索引和可视化。
2. 关键日志级别：
   • INFO：记录规则触发、动作执行等正常流程。
   • DEBUG：记录详细的HTTP请求/响应、设备状态变化、条件判断过程。调试时开启，生产环境酌情关闭以减少日志量。
   • WARNING和ERROR：重点关注对象，需要设置告警（如发送到钉钉/Telegram）。
3. 健康检查接口：除了基础的/health，可以自定义一个更详细的状态端点，返回当前连接的后端平台状态、活跃规则数量、队列深度等指标，并集成到你的监控系统（如Prometheus）中。

6.3 常见问题排查清单

下表总结了一些典型问题及排查思路：

最后一点个人体会：搭建这样一套系统，初期最大的挑战往往不是技术，而是梳理清楚自己真正的需求。不要试图一开始就构建一个庞大复杂的规则网络。从一个最简单的、能解决实际痛点的场景开始（比如“晚上回家自动开灯”），把它跑通、跑稳。然后在此基础上，像搭积木一样，一个一个地添加新的场景和规则。每添加一个，都充分测试。这样构建出来的系统才健壮、可维护。另外，文档和注释至关重要，尤其是那些复杂的、有特殊逻辑的规则，一定要写清楚设计意图，不然几个月后自己都看不懂当初为什么要这么写。