Connect the device to Wi-Fi

If the device has no internet connection, put it in setup mode: it opens a temporary setup network and a page that connects it to Wi-Fi. You join that network from a phone, pick your Wi-Fi network, and type its password; the device does the rest. The whole flow runs on the device, so it works with no internet and no cloud model.

Before you begin

• The device is powered on and has no internet connection over Wi-Fi.
• A phone.
• The paper insert that shipped with the device, if you have it: it prints the setup network’s password.
• To start by voice, a microphone and a speaker on the device through the local-audio audio bridge. See Use a microphone on the device.

Put the device in setup mode

Say “set up Wi-Fi” or “connect to Wi-Fi” at the device. While the device has no internet, either phrase starts setup mode without the agent: the device asks whether to go into setup mode, and after you say yes, it opens its setup network and says that it is in setup mode.

With TEAPORT_SETUP_ON_FIRST_BOOT on, a new device does this by itself. When it has never been online and still has no internet a minute after it starts, it goes into setup mode without a wake word or a question, and it introduces itself first. If you cancel, or nothing connects in time, it tells you to say “set up Wi-Fi” to try again, and it starts by itself again only at the next start-up. A setup you start by voice in the first minute counts as that start-up’s try. The first time the device is online, it stops doing this for good; if that happens during setup mode, for example when you plug in a network cable, it leaves setup mode by itself.

If the device is already online, the phrase is ordinary speech. The agent hears it and can start the same procedure with its Wi-Fi setup tool; ask the agent to run it. If no model is set up yet, there is no agent to ask, so the phrase starts setup mode online too.

Join the setup network

A device with a screen shows, under the title “Setup mode”, the setup network’s name, its password, and an address to open, with a QR code beside them when the screen can draw one. The device tells you what to do in the same order:

1. Join the setup network from your phone. With a QR code on the screen, scan it with the phone’s camera. Otherwise, join the network shown on the screen, named teaport-XXXX (teaport plus the last four characters of the device’s Wi-Fi MAC address, for example teaport-ab12), and type the password shown on the screen.
2. In the phone’s browser, go to the address on the screen. It is usually http://teaport-XXXX.local, or http://10.42.0.1, which always works.
3. Pick your Wi-Fi network and type its password. The setup network goes down and the device joins yours.

Say “repeat” to hear the network’s name, the password, and the address read out. A device without a screen reads them out straight away. Some phones open the page on their own after they join the setup network; if yours does not, use the address.

If you start setup by voice, the screen shows its words in the language that the device speaks; if you start it another way, in English. After you pick your network on the setup page, the screens that follow are in the page’s language. Network names appear as they are written. This depends on fonts for other scripts on the device: a device without them shows the words in English and drops the characters outside ASCII from a network’s name, for example “Cafe” for “Café”. If that changes the setup network’s name and a QR code is on the screen, the screen shows “(scan the code)” in place of the name.

The setup network uses WPA2. Its password is the one printed on the paper insert, stored on the device as WIFI_SETUP_PASSWORD in /etc/teaport/wifi-setup.env. Without that stored password, the device makes a fresh random one for each run: twelve characters in three groups of four, for example k7mq-x4tn-p9wr, lowercase letters and digits without look-alikes or sound-alikes (no 0 or o, no 1, l or i, no q). The hyphens are part of the password; type it as the screen shows it. The screen shows it, and the device reads it out, character by character with “dash” between the groups, when it has no screen or you say “repeat”. A password for the paper insert should use the same grouped form.

Connect your AI account

When the device’s language model endpoint is OpenRouter, the setup page also has an AI account section, which you can skip. Leave it closed to keep the account the device has now. To use your own OpenRouter account, open it and paste a key from that account before you tap Connect.

The setup network has no internet, so the device checks the key after it joins your network and is online. It saves the key only if OpenRouter accepts it and, on a device with OpenClaw, OpenClaw takes it too, as One key for OpenClaw too describes. When it says that it is connected, it also says whether your AI account is connected, and, if your OpenRouter account has no credit yet, that you need to add some on OpenRouter’s website before it can answer. If the key did not work, the device keeps the account it had; say “open my settings” to try again from your phone, as Open the settings from your phone shows.

Signing in to OpenRouter instead of pasting a key does not work in setup mode: neither the phone nor the device can reach the internet there. When the device offers the sign-in afterwards (it has a settings site, its endpoint is OpenRouter, and it has no key of your own), the section says so: leave the key empty, and when the device is online it offers the sign-in by itself, or you can say “open my settings”, as Connect your OpenRouter account shows.

If the device connects

The page tells you that the device is joining your network, so switch your phone back to it. The device leaves setup mode and says that it is connected to your network and online again; a screen shows “Connected to” and the network’s name under the title “Wi-Fi” for a few seconds.

If the join fails

The device drops the network profile it tried, the setup network comes back, and the page says what failed. Pick the network and type its password again.

If nothing has connected after 10 minutes

The device leaves setup mode on its own, undoes a half-finished join, and restores the connection it had before. The service stops itself at the 15-minute mark at the latest.

Leave setup mode

Say “cancel” at the device while it is in setup mode, stop it from the configuration page, or run this on the device:

sudo systemctl stop teaport-wifi-setup

The device takes the setup network down, undoes a half-finished join, and restores the previous connection.

What’s next

• Use a microphone on the device, for the spoken phrase.
• Settings reference, for the Wi-Fi setup settings, including the setup-network password.
• Troubleshooting, if the device does not come online.