Before you start
What you need
- An iPhone with Yokwi installed.
- An AI agent that can stay connected in the background, Hermes OpenClaw Claude Code, or Telegram, where @YokwiBot routes the pairing.
- Your agent never makes audio. Yokwi speaks on the iPhone with its own on-device voice (Kokoro). Your agent sends text, and when it also supplies a separate spoken explanation, that is what you hear; a text-only answer is shown on screen instead of being read.
Step 1
Let Yokwi hear you
Allow Microphone and Speech Recognition when iOS asks. Apple's Speech framework turns your words into text, on the device or on Apple's servers depending on your device and language, under Apple's policy. Only that text goes to your agent.
First, let Yokwi hear you
Your voice is transcribed by Apple's Speech framework. Yokwi never sends your raw audio to its relay or to your agent.
Allow Microphone & Speech
Step 2
Choose your username
Create your unique username. It stays yours while your address is claimed, and it's how your agent finds you through our server. Tap Claim My Address.
Choose your username
Create your unique username, your agent reaches you here while your address stays claimed.
Claim My Address
Step 3
Design your Yokwi
Tap Generate Your Yokwi. Five siblings, each with its own aura, orbit, gaze and markings. Roll again if you like, its look and spirit travel to your agent so it can play the part.
Design your Yokwi
Every Yokwi grows its own aura, orbit, and quiet little markings.
Generate Your Yokwi
Step 4
Pair your agent
Two short messages, sent in order: the first gets your agent ready, the second is one command that pairs it. Send each with the Telegram button or Copy. Your agent connects, and three ticks land.
Agent message
Generated for you in the app, with your username and a one-time code filled in. Tap Copy Message there, or Send to your agent on Telegram.
Step 5
Run the voice test
Yokwi sends your agent a test turn and reads the agent's test reply aloud with its own on-device Kokoro voice; this one test doesn't need the separate spoken explanation that ordinary conversations use. You don't need to speak, keep the volume on. The test passes only when the phone actually plays the reply and the relay confirms it.
10
Testing voice
Keep the phone volume on while the agent test response comes back.
Voice test passed
The app and agent are paired. Your voice channel is ready.
Run Voice Test
That's it
Pairing is kept.
While your address and your agent's credentials stay valid, a dropped agent reconnects on its own with no new code and no new message. If the pairing is released or those credentials stop working, you send the pairing instructions again. Tap Start Talking.