Support
Something's quiet? Start here.
Most problems come down to a few things to check: your agent's connection, whether iOS has been allowed to listen, and whether the agent included a spoken explanation and the phone could speak and play it. Text replies are normal: the phone shows them and reads aloud only the separate spoken explanation. Each check is below. If none of them is yours, ask in the Yokwi Discord, include your username and what the pairing screen says.
- The pairing screen is stuck on "Waiting for Agent".
- Your phone is connected; your agent hasn't joined yet. Send message 1 first and wait for "ready", then message 2, the pair command. The agent has to run that command as something that stays on in the background, not answer it as a chat reply. If the code has expired, tap Generate New Pairing Code and send the new message.
- "Agent connected" is ticked but the voice test fails.
- Read the reason on the failure screen. If it says the reply never arrived or wasn't in the expected shape, use Copy Reply Commands to show your agent the exact reply format, then run the test again. If it says the phone could not generate or play speech, check the volume, silent switch and audio output on the phone; that part doesn't depend on your agent.
- The test says the agent disconnected.
- Your agent dropped off. While its retained credentials stay valid it reconnects on its own without a new code, so check that its process is still running and the machine it lives on hasn't gone to sleep. On a Mac, keep it running as a background job, not in a terminal tab you'll close. If the pairing was released or its credentials no longer work, pair it again from the app.
- Yokwi shows the answer but doesn't say it.
- Yokwi reads aloud the separate spoken explanation your agent supplies alongside its answer, and only that. When the agent sends text alone, the app shows the full answer and tells you no spoken explanation was included; what is read is decided by what your agent puts in that explanation, not by Yokwi filtering the answer. Ask your agent (or its bridge setup) to include the spoken explanation; see the pairing guide at your address's
/pair.
- It's taking a long time to answer.
- If the window in the app is showing steps, your agent is working: a web search or running some code can take five to ten seconds, and it tells you what it's doing while it does. Why the wait explains what's normal. If the window stays blank for more than a minute, the connection is one thing to check (see above), but your agent may also be slow or may not report its steps while it works; a blank window alone doesn't prove the connection dropped.
- I hear nothing at all.
- Check the ring/silent switch and volume, then where the audio is going, if AirPods or a car are connected, it plays there. Bluetooth headsets sometimes take a second to switch over; say something again.
- It says Yokwi can't hear me.
- Microphone or Speech Recognition was declined. Open iOS Settings → Yokwi and turn both on. Speech recognition comes from Apple's Speech framework, on the device or on Apple's servers depending on device and language; without it the app has no text to send.
- Can I change my username?
- Choose a different one during onboarding, or ask in the Discord and we'll release your old name. Your agent will need to pair again with the new username.
- Which agents work?
- Any agent you already run that can stay connected in the background, Hermes and OpenClaw pair out of the box, and Claude Code and most others do too. Or message @YokwiBot on Telegram and it routes the pairing for you. The setup guide walks through it.
- Does Yokwi work without my own agent?
- No. That's the point of it. Yokwi is the voice and face for the agent you already run. It doesn't come with a brain in the cloud, and it doesn't send your words to one.
- Does it record me?
- Yokwi doesn't keep your audio. Apple's Speech framework turns your voice into text (on the device or on Apple's servers, depending on device and language), and each finished turn goes as text only to your own agent. The privacy policy walks through it step by step.
Still stuck
Post in
#pairing-help on the Yokwi Discord with your username, which agent you're using, and a screenshot of the pairing or voice-test screen. Real replies from the person who built it.