Migrating a Tuya Zigbee Gateway to Zigbee2MQTT

If you own Tuya-branded Zigbee devices, motion sensors, plugs, water leak detectors, TS0601-family switches, paired to a Tuya multi-mode or Zigbee gateway, moving them to Zigbee2MQTT is possible. It isn’t a settings toggle or an export file, though. It’s a device-by-device re-pairing project, and knowing that going in saves a lot of confused troubleshooting.

That’s a different question from “how do I get a Tuya local key,” which comes up constantly for Tuya’s Wi-Fi devices. (Tuya’s Zigbee devices don’t need a local key the way its Wi-Fi devices do.) Zigbee devices sitting behind a Tuya gateway don’t use that mechanism at all. They talk Zigbee to whatever coordinator they’re joined to, and the gateway is just acting as that coordinator plus a cloud bridge.

Why Leave the Tuya Zigbee Gateway At All

What actually happens to Tuya’s cloud data covers the account and data side of this question in more depth. The short version relevant here: a Tuya Zigbee gateway still routes device state through Tuya’s cloud infrastructure for remote access and automation execution, even though the Zigbee radio traffic itself stays local. Once devices join Zigbee2MQTT instead, that dependency is gone. The coordinator talks directly to Home Assistant over MQTT, with no Tuya account, app, or cloud round-trip involved.

The One Rule That Makes This a Migration, Not a Swap

Here’s the fact that shapes the entire process: a Zigbee device can only be joined to one network at a time. There’s no protocol-level handoff that lets a device keep its existing pairing while you point it at a different coordinator. A Home Assistant Community thread on exactly this question confirms it’s a hard limit, not a Tuya-specific restriction. It’s how Zigbee networking works, regardless of vendor.

Practically, that means every device has to be factory-reset and re-paired to Zigbee2MQTT individually. There’s no bulk export, no backup file to restore onto the new coordinator, and no single button in either the Tuya app or Zigbee2MQTT’s frontend that migrates every device at once.

This is a per-device limit, not a per-house one. Two independent Zigbee networks, the Tuya gateway’s and a new Zigbee2MQTT coordinator’s, can run at the same time without interfering with each other, since each network operates on its own security keys and ideally a different channel. That’s what makes an incremental migration practical. Move a few devices at a time, confirm each one in Home Assistant, and leave the rest on the Tuya gateway until you’re ready for them.

Step 1: Pick and Set Up Your Zigbee2MQTT Coordinator

If you don’t already have a Zigbee2MQTT coordinator running, this is the point to set one up, since every device you migrate has to join it. Our SMLIGHT SLZB-06 Ethernet setup guide covers one common option, and a Sonoff ZBDongle-E-versus-ZBDongle-P coordinator is another worth weighing if you’re choosing hardware as part of this project.

One detail worth flagging if you’re also planning to swap coordinator hardware later, not just add a coordinator: Zigbee2MQTT’s adapter-to-adapter backup and restore feature, which lets you move an existing Z2M network to new coordinator hardware without re-pairing everything, only works between Z-Stack (Texas Instruments) or EmberZNet (Silicon Labs) based coordinators. It doesn’t apply to this specific migration, since you’re not moving a Z2M network here, you’re moving devices off a Tuya network Z2M was never part of. Knowing that up front stops you assuming a “backup and restore” workflow covers this case.

Step 2: Factory-Reset Each Device on the Tuya Gateway

Each device needs to be factory-reset before it can join a new network. This clears its existing Zigbee pairing info so it’s ready to pair fresh. The exact reset sequence varies by device model, commonly holding the device’s button for several seconds until its LED blinks rapidly, but the button, the hold time, and the LED behavior all differ across the Tuya Zigbee catalog. Check the specific device’s manual or its Zigbee2MQTT device page for the reset method before you start, since guessing wrong usually just leaves the device unresponsive to pairing.

Remove the device from the Tuya app or gateway’s device list before or right after the reset, too, so the gateway stops trying to reach a device that’s no longer on its network.

Step 3: Re-Pair Into Zigbee2MQTT

Put Zigbee2MQTT into pairing mode and reset the device using the same sequence from Step 2. Most Tuya-based Zigbee devices, including the widely-sold TS0601 family, connect directly to Zigbee2MQTT (or ZHA) without needing any Tuya hardware in the loop once they’ve joined. At that point they’re operating as ordinary Zigbee end devices or routers on your network, same as any other brand.

Give the device a moment to complete the interview process, Zigbee2MQTT reading back its model, endpoints, and clusters, before assuming the pairing failed. That’s the same step every new Zigbee device goes through, not something specific to devices coming off a Tuya gateway.

What Happens to Devices Without a Converter Yet

Zigbee2MQTT maintains a defined process for adding support for Tuya-manufactured devices it doesn’t already recognize, since Tuya’s OEM model produces a long tail of device model variants under the TS/_TZ product code families. If a device pairs but shows up with no exposed entities, or with generic, unnamed ones, that’s usually this gap rather than a failed migration. The device joined the network fine. Zigbee2MQTT just doesn’t have a converter mapped to its specific model ID yet.

How you apply that converter depends on the method. Dropping an external converter file into Zigbee2MQTT’s configuration requires a Zigbee2MQTT restart before it takes effect, while Zigbee2MQTT’s newer runtime option, saving a converter through its MQTT API, loads it without a restart. Either way, the device stays joined to the network. You’re adding the software definition Zigbee2MQTT was missing, not re-pairing the hardware.

Rebuilding Automations and Scenes After Migration

Factory-resetting a device doesn’t touch anything stored in Home Assistant. Your automations, scenes, and dashboards aren’t wiped by this process. But they’ll likely break anyway, for a more mundane reason: when a device re-pairs to Zigbee2MQTT, Zigbee2MQTT gives it a fresh entity, named by default from its IEEE address, a different identifier than whatever the Tuya integration was using for the same physical device. Any automation trigger, condition, or dashboard card pointing at the old entity ID needs to be repointed at the new one.

For a handful of devices this is a five-minute cleanup. For a house with dozens of Tuya Zigbee devices spread across multiple automations, it’s worth exporting or screenshotting the existing automation YAML before migrating, rather than reconstructing the logic from memory afterward.

This per-device rebuild step, more than the re-pairing itself, is the part that’s easy to underestimate going into the project. The pairing is mechanical. Untangling a dozen automations that reference renamed entities is where the real work is.

FAQ

Can I move my Tuya Zigbee gateway’s devices to Zigbee2MQTT without re-pairing them?
No. Zigbee’s single-network-per-device design means there’s no in-place transfer. Every device has to be factory-reset and re-paired to the new coordinator.

Does factory-resetting a Tuya Zigbee device erase its Home Assistant automations?
No, the reset only clears the device’s own Zigbee pairing state. Your Home Assistant automations and scenes stay intact, but they’ll likely reference the device’s old entity ID and need to be updated to point at the new one Zigbee2MQTT assigns after re-pairing.

Do Tuya Zigbee devices need a “local key” the way Tuya Wi-Fi devices do?
No. The local-key mechanism applies to Tuya’s Wi-Fi devices talking to Tuya’s cloud API. Zigbee devices behind a Tuya gateway communicate over Zigbee, not Tuya’s Wi-Fi protocol, so once they’re on Zigbee2MQTT there’s no key extraction step involved. Our guide on Tuya Zigbee devices and local keys covers this distinction in more depth.

What Zigbee coordinator should replace a Tuya gateway?
There’s no single right answer. It depends on whether you want Ethernet/PoE, USB, or a specific chipset. Our SLZB-06 Ethernet setup guide covers one option in active use in this cluster, and a Sonoff ZBDongle-E-versus-ZBDongle-P comparison covers another.

Can I run the Tuya gateway and Zigbee2MQTT side by side during migration?
Yes. They’re independent Zigbee networks and don’t need to interact, which is what makes migrating devices in batches practical instead of an all-or-nothing cutover.

Zigbee2MQTT’s own documentation doesn’t have anything planned for smoothing over Tuya-to-Z2M migrations specifically, which makes sense given how few publishers have even mapped out the process. Whether Tuya ever opens an export path in its own gateway-replacement flow is worth watching, though even if it does, it would likely still assume the destination is another Tuya gateway, not a third-party coordinator.