> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augmental.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Vox to OpenClaw

Sessions let you talk to your OpenClaw agent from Vox. Vox connects to one agent on your
gateway and joins its main session, the same one you use from your other chat apps.

Setup takes three steps: get your gateway ready, connect it in Vox, and approve Vox once
on the gateway.

<Info>
  Don't have OpenClaw yet? See [Get OpenClaw running](/other-apps/get-openclaw).
</Info>

## What you need

| | |
| - | - |
| **Gateway URL** | A `wss://` address your gateway answers on from the internet. Tailscale Funnel gives you one. |
| **Password** | Your gateway's password. The gateway must use password auth. |

<Warning>
  Vox reaches your gateway from the Vox cloud, not from your phone or Mac. An address that
  only works inside your tailnet or on your home network will not connect.
</Warning>

## Get your gateway ready

### Ask your OpenClaw

The quickest way. Copy this into a chat with your OpenClaw. Vox shows the same prompt, with
a copy button, on the **Get your gateway ready** step.

```text theme={null}
Set up this OpenClaw gateway for the Vox app:
1. Auth: use password mode (gateway.auth.mode "password"). Keep the current password if there is one, otherwise create a long random one.
2. Access: Vox connects from the cloud, so the gateway needs a public, secure URL. Turn on Tailscale Funnel (gateway.tailscale.mode "funnel") unless it already has a public wss:// URL.
3. Restart the gateway and check it's running.
Then reply with only these two lines:
Gateway URL: wss://...
Password: ...
```

<Tip>
  Copy the whole reply and paste it into the **Gateway URL** field in Vox. Vox fills in
  both fields for you.
</Tip>

### Or set it up yourself

In your OpenClaw config:

```json5 theme={null}
{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password", password: "a-long-random-password" },
  },
}
```

Restart the gateway. Your URL is your machine's Tailscale name, for example
`wss://your-machine.your-tailnet.ts.net`. Vox also accepts the `https://` address
Tailscale shows and switches it to `wss://`.

Funnel needs MagicDNS and HTTPS turned on for your tailnet. If your gateway already has a
public `wss://` address, use that instead.

## Connect in Vox

<Steps>
  <Step title="Open the connect step">
    It opens on its own when you turn Sessions on. Later, go to **Settings › Sessions**,
    choose **Add agent**, then **New channel**. It walks you through the same steps.
  </Step>

  <Step title="Paste the URL and password">
    Optionally give the gateway a name. It shows next to your agent in **Settings ›
    Sessions**, and defaults to your gateway's machine name. Then choose **Connect**. If
    your gateway runs a single agent, Vox connects to it. If it runs more than one, pick
    the agent Vox should talk to.
  </Step>

  <Step title="Approve Vox on your gateway">
    The first time only. See below.
  </Step>
</Steps>

## Approve Vox on your gateway

The first time Vox connects, OpenClaw holds the connection until you approve it. This is
OpenClaw's device pairing. It happens once per gateway, and again only if you remove the
gateway from Vox and add it back.

Vox shows **Approve Vox on your gateway** and waits. Approve it either way below, and Vox
connects on its own within a few seconds.

**Ask your OpenClaw:**

```text theme={null}
Approve the pending device pairing request from Vox on this gateway. It shows as VoxOS Backend in `openclaw devices list`. Approve it with `openclaw devices approve <requestId>`.
```

**Or, on the gateway's machine:**

```bash theme={null}
openclaw devices approve --latest
```

This shows the newest pending request and prints the exact command that approves it,
`openclaw devices approve <requestId>`. Run that command. The request from Vox shows as
**VoxOS Backend**.

Vox keeps checking for five minutes. If you approve after that, choose **Try again**.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Couldn't connect">
    Check the password and the URL for typos. Make sure the gateway is running with
    `openclaw gateway status`, and that its URL opens from a device outside your tailnet,
    for example your phone on cellular.
  </Accordion>

  <Accordion title="Stuck on Connecting">
    Vox can't reach the gateway. The URL most likely only works inside your tailnet or home
    network. Turn on Tailscale Funnel, or use a public `wss://` address.
  </Accordion>

  <Accordion title="Still waiting after approving">
    You may have approved a different request. Run `openclaw devices list` and approve the
    one from **VoxOS Backend**.
  </Accordion>

  <Accordion title="Pairing timed out">
    Approve the request, then choose **Try again** in Vox.
  </Accordion>

  <Accordion title="Changing the URL or password">
    Choose **Edit URL or password** on the connect step, or remove the agent in
    **Settings › Sessions** and add it again. Either way, approve Vox on the gateway again.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.