Setup guide · about four minutes

Two short messages to your agent.
Then it stays paired.

Scroll, and a Yokwi walks you through it. Do this on a laptop with your phone next to you, the pasting is easier.

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.

Microphone
Speech Recognition
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.
App connected
Agent connected
Pairing confirmed
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.

Which agents work

The one you already have.

Any agent that can stay connected in the background. Hermes and OpenClaw pair out of the box. Claude Code and most others do too, paste the message and let it run. On Telegram, message @YokwiBot and it routes the pairing for you.

If the agent answers you in chat instead of connecting, tell it plainly: "This runs in the background, not as a chat reply." Then check the three ticks.