OpenClaw smart home integration with Philips Hue and HomeKit

If you landed here you’re probably searching for one thing: how to control Philips Hue and HomeKit lights through OpenClaw so you can tell Slack “movie time” and watch the room dim itself. I spent a weekend wiring my apartment and wrote down every step so you don’t have to scrape forum threads.

Why run Hue from OpenClaw at all?

OpenClaw already answers questions, files GitHub issues, even orders coffee via Composio. Hooking it to Hue adds an obvious super-power: the same agent that knows your calendar and mood can now change the room to match. You type “/focus mode” in Telegram → desk lamp cranks to 6500 K, overheads go full, blinds open. Same brain, different actuation layer.

No extra app juggling: chat or voice is the UI you already use with the agent.
Cross-platform: works from phone, laptop, or the ClawCloud web gateway.
Programmable: schedule routines in JavaScript or let the LLM decide on the fly.

Prerequisites and versions that actually work

I hit several version mismatches before things clicked. Here’s the exact stack running in production as of March 2024.

OpenClaw v0.9.4 (requires Node 22+)
Philips Hue bridge firmware 1955082050 (2023-10)
homebridge v1.10.0 (only if you want HomeKit)
homebridge-hue v1.10.2
ClawCloud daemon build 6be2c8b

You’ll also need:

At least one Hue bridge on the same LAN as the machine running OpenClaw (ClawCloud users: use a WireGuard tunnel, explained later).
An Apple Home hub (Apple TV, HomePod) if you want remote Siri control.
NPM access to install extra plugins.

Step 1: create a Philips Hue API key

OpenClaw talks to Hue over the local REST API. Ignore the “Hue Remote V2” cloud docs—you want the classic bridge API because latency is sub-100 ms and zero cloud dependencies.

Find your bridge IP in the Hue app settings or via mDNS:
dig +short -t A Philips-hue.local
Press the physical link button on the bridge (blue LED starts blinking).
Within 30 seconds call:
curl -X POST -d '{"devicetype":"openclaw#livingroom"}' http://BRIDGE_IP/api
The response contains a username field—the 40-char API key we’ll store:
[{"success":{"username":"5xb6Ke7..."}}]

Write that key somewhere safe; the bridge won’t show it again.

Step 2: wire Hue into OpenClaw

OpenClaw uses the @openclaw/hue-tool helper library I pushed last month. It’s a thin wrapper around the bridge API with schema validation so the agent can reason about the available lights.

Install the tool


npm install @openclaw/hue-tool@0.3.1

Add to `claw.config.js`


module.exports = {
  tools: [
    {
      package: "@openclaw/hue-tool",
      config: {
        bridgeIp: "192.168.1.42",
        username: process.env.HUE_API_KEY,
        // optional: expose scenes as separate actions
        includeScenes: true
      }
    }
  ]
};

Restart OpenClaw:


npx openclaw daemon restart

The agent introspects the tool and builds function-calling JSON specs so the LLM can toggle lights without extra prompts.

Step 3: basic light control via chat

Open a connected channel (Slack works great). The following natural-language prompts now map to function calls:

“Turn off the bedroom light.”
“Set desk lamp to 30 percent, warm white.”
“Make the living room red.”

The hue-tool handles translation. Example raw trace for the last command:


{
  "name": "setLightState",
  "arguments": {
    "lightName": "Living Room",
    "state": {
      "on": true,
      "hue": 0,
      "sat": 254
    }
  }
}

I recommend enabling OPENCLAW_TRACE=1 during dev to watch these calls.

Step 4: scene automation — movie time, work, party

Hue scenes bundle brightness, color, and on/off for multiple lights. If you set includeScenes: true earlier, they show up as a secondary tool action activateScene.

Defining custom scenes

In the Hue app create a scene called Movie Time with 20 % warm light on the couch lamp, everything else off. Hue stores it with an ID like PvMYcz3jz33K9QM.

Chat usage

“Movie time.” → triggers activateScene("Movie Time").
“Workspace mode please.” → bright 6500 K overheads.

Because OpenClaw has memory, you can chain context:

“Start movie time.”
Agent dims the lights.
“Also turn on subtitles.” (Assuming you added a Plex integration.)

Step 5: bridging to HomeKit for Siri and ecosystem perks

Apple’s Home app can control Hue directly, but once you run automations through OpenClaw you’ll want the other direction: let HomeKit events (presence, humidity) invoke OpenClaw or vice versa. The easiest path is Homebridge + the hue plugin.

Homebridge install (local)


npm install -g --unsafe-perm homebridge homebridge-config-ui-x

Run once to generate config:


homebridge

Browse to http://localhost:8581 → Plugins → search “hue” → install homebridge-hue.

Configure the bridge


{
  "platform": "Hue",
  "name": "Hue",
  "username": "5xb6Ke7...", // same key as above
  "hosts": ["192.168.1.42"],
  "lights": true,
  "scenes": true
}

Restart Homebridge and add the generated QR code to the Home app. Now every Hue light appears twice in HomeKit—direct and Homebridge. Disable the direct ones unless you like duplicates.

Wiring HomeKit events into OpenClaw

Use the Homebridge @openclaw/webhook plugin if you need Home-initiated triggers (e.g., your kid’s playroom switch). But most folks just want Siri to forward commands to OpenClaw. Create a “Scene” in Home called Focus Mode with no direct accessories. Instead, add a HomeKit Shortcut:

When the scene runs, execute the Shortcut.
Shortcut action: Get contents of URL POST to your ClawCloud webhook
https://YOUR_AGENT.clawcloud.run/webhook/homekit
Body: {"intent":"focus_mode"}

On the OpenClaw side create a handler:


app.webhook("homekit", async (body) => {
  if (body.intent === "focus_mode") {
    await app.callTool("activateScene", { name: "Workspace" });
  }
});

Now “Hey Siri, focus mode” routes through HomeKit → Shortcut → OpenClaw → Hue.

Step 6: context-aware lighting — real example

This is where the agent shines: combining arbitrary data sources to adjust your environment.

Data we’ll use

Google Calendar via Composio
Ambient light sensor from Eve Room (HomeKit)
Local sunset time (simple JS)

Goal

If a meeting titled “Daily Standup” is active and ambient lux < 150, set desk light to 550 lx, color temp 4800 K. Else, follow normal circadian color temp schedule.

Implementation sketch


import { schedule } from "openclaw/scheduler";
import { getUpcomingEvents } from "@openclaw/composio-google-calendar";
import { lux } from "@openclaw/homekit";
import { setLightState } from "@openclaw/hue-tool";

schedule.everyMinute(async () => {
  const events = await getUpcomingEvents({ withinMinutes: 15 });
  const standup = events.find(e => /standup/i.test(e.summary));
  const currentLux = await lux("Office Sensor");

  if (standup && currentLux < 150) {
    await setLightState("Desk Lamp", {
      on: true,
      bri: 200, // ~550 lx on my lamp
      ct: 250   // 4800 K
    });
    return;
  }

  // Else circadian schedule
  const hours = new Date().getHours();
  const ct = hours < 12 ? 200 : hours < 18 ? 250 : 370;
  await setLightState("Desk Lamp", { on: true, ct });
});

The scheduler survives daemon restarts because persistent: true is the default in OpenClaw’s cron wrapper. If you’re on ClawCloud Free Tier, keep it under 500 invocations/day to avoid throttling.

Networking gotchas on ClawCloud

Running local IoT devices from a cloud agent means punching back into your LAN. Two approaches:

WireGuard reverse tunnel (recommended). Set up a tiny VPS or a Raspberry Pi at home that peers with your ClawCloud instance. Expose the bridge IP over the tunnel.
NAT hairpin with port forwarding. Open TCP 80 of the Hue bridge to the internet + restrict by ClawCloud egress IP. Risky and breaks after ISP CGNAT changes. Don’t.

Example WireGuard peer config on the Pi:


[Peer]
PublicKey = CLOUDFULL_PUB
Endpoint  = 13.52.XX.XX:51820
AllowedIPs = 100.96.0.2/32
PersistentKeepalive = 25

Then point bridgeIp in claw.config.js to the tunnel address 100.96.0.3.

Debugging checklist when the lights don’t change

401 Unauthorized: key revoked—Hue bridge wipes keys after a factory reset.
ETIMEDOUT from node-fetch: bridgeIp wrong or LAN/VPN path broken.
Light briefly changes then pops back: another Hue app or HomeKit automation fighting you. Disable “Power-on behavior” in Hue settings.
Scene not found: name mismatch; tool caches scene list on startup, restart after editing.

What’s next?

If you reached this line your lights already blinked at least once under OpenClaw’s command. The obvious next experiment is extending the same pattern to other endpoints: control LG webOS TVs for volume, tell the robot vacuum to wait until the movie ends, or use the fan during a heatwave detected by the Eve sensor. The plumbing is identical—just another tool in claw.config.js.

Have feedback? File an issue on GitHub or ping me on the Discord #smart-home channel.

Happy hacking, and may your lights never flash at 3 AM again.