VoiceClaw Realtime Companion is the macOS bridge for VoiceClaw Realtime on iPhone and Apple Watch. It lets the mobile app reach agent tools that run on your own Mac, including OpenClaw and Hermes Agent, through a private Tailscale URL.
The Companion app installs a local bridge, keeps it running with a user LaunchAgent, configures Tailscale Serve, checks the Mac permissions VoiceClaw Realtime needs, and gives VoiceClaw Realtime a QR code or setup link for pairing. It is meant for people who want VoiceClaw Realtime to use their own Mac, their own tailnet, their own local models, and their own API credentials instead of routing work through someone else's computer.
Use VoiceClaw Realtime Companion if you want to:
- Talk to OpenClaw from VoiceClaw Realtime on iPhone or Apple Watch.
- Route spoken requests to Hermes Agent when the
hermesCLI is installed. - Use VoiceClaw Realtime iOS/watchOS with a Mac-side bridge for private computer access.
- Keep the bridge local to your Mac and reachable only through your Tailscale tailnet by default.
- Pair, diagnose, and update the Mac bridge without manually editing local launch agents or Tailscale Serve mappings.
- Monitor delegated OpenClaw, Hermes Agent, and Codex tasks and manage files explicitly returned to the Companion Artifact Inbox.
You probably do not need this app if you only want a standalone iPhone voice assistant and do not need your phone or watch to reach agent tools on a Mac.
VoiceClaw Realtime on iPhone / Apple Watch
|
| private HTTPS URL from Tailscale Serve
v
VoiceClaw Realtime Companion on Mac
|
| local bridge on 127.0.0.1, default port 12321
v
OpenClaw / Hermes Agent / Codex routes and GPT Realtime setup
The iPhone/watch app owns the mobile voice experience. VoiceClaw Realtime Companion owns the Mac-side bridge. Tailscale supplies the private network path between them.
The bridge can expose several route types to VoiceClaw Realtime:
- Tailscale/OpenClaw: sends requests to an OpenClaw install on this Mac,
usually at
~/.openclaw. - Tailscale/Hermes: sends requests to Hermes Agent through the
hermescommand orHERMES_BIN. - GPT Realtime Live: uses OpenAI Realtime from the mobile app, with the Companion available for Mac-side tools and auth setup.
- Codex: sends durable work through Codex app-server without modifying the user's Codex installation.
Realtime should handle ordinary conversation directly when it can. OpenClaw or Hermes should be used when the request needs the Mac, local files, local tools, or a specific agent route.
Before installing, prepare:
- A Mac running macOS 13 Ventura or later. Current release builds are intended for Apple silicon Macs.
- Tailscale for Mac, signed in to the same tailnet as the iPhone.
- Tailscale HTTPS certificates enabled for the tailnet. If you are not the tailnet owner or admin, ask that person to enable them.
- Node.js 22 or newer installed on the Mac. Companion checks common Homebrew and system locations and links to the installer if it is missing or outdated.
- VoiceClaw Realtime installed on iPhone and signed in.
- At least one Mac-side agent route:
- OpenClaw installed on the Mac, usually at
~/.openclaw, withopenclaw.jsonin that folder. - Or Hermes Agent installed so
hermes --helpworks in Terminal.
- OpenClaw installed on the Mac, usually at
For GPT Realtime Live, ChatGPT Plan (OAuth) is supported and preferred when available. You can also use an OpenAI API key explicitly, or allow the iPhone app to fall back to an available API key when its fallback setting is enabled. The setup QR can carry the Companion-minted OAuth credential and, when you choose to include it, an OpenAI API key.
The dormant Companion Voice and Powerhouse implementations are preserved for a possible future release, but current product policy hides their controls and excludes their dependencies from setup guidance and overall readiness.
- Open the VoiceClaw Realtime Companion download page.
- Download the current signed and notarized
.dmg. - Open the DMG and drag VoiceClaw Realtime Companion into Applications.
- Open VoiceClaw Realtime Companion.
- Approve the macOS open prompt if one appears.
- Click Install and Start.
- Open Access and use the buttons there to prepare Login Items, Local Network, Microphone, Files and Folders, Full Disk Access, and OpenClaw/Hermes folders before your first real session.
Install and Start creates ~/.voiceclaw/bridge.json, installs
~/Library/LaunchAgents/ai.voiceclaw.bridge.plist, starts the bridge, and
configures Tailscale Serve for the selected port.
The default bridge port is 12321. Leave it unchanged unless that port is
already in use or you are deliberately testing a fresh pairing. If you change
the port, pair the iPhone again with the new QR code.
- Finish Install and Start on the Mac.
- Open Pair Phone in VoiceClaw Realtime Companion.
- Open VoiceClaw Realtime settings on iPhone.
- Scan the QR code, or copy the setup link/JSON if scanning is inconvenient.
- Choose the route you want in VoiceClaw Realtime, such as Tailscale/OpenClaw, Tailscale/Hermes, Codex, or GPT Realtime.
The Include API Key in Setup QR toggle controls whether the setup payload includes your OpenAI API key. When enabled, the iPhone can store the key in its Keychain during pairing. The Companion preview redacts the key so you can inspect the setup payload without displaying the full secret.
The Non-Tailscale HTTPS Bridge field is optional and advanced. Leave it empty for the normal private Tailscale setup. Only enter a public HTTPS tunnel if you intentionally want VoiceClaw Realtime to reach this Mac outside Tailscale and you understand the exposure.
- Native macOS setup, pairing, Tailscale, and diagnostics screens.
- An Access screen that checks and opens the macOS settings panes users need before voice sessions get blocked by missing permissions.
- A menu bar item for status checks, setup copying, update checks, and app access.
- Private Tailscale Serve publishing for the local bridge.
- QR code, setup link, and setup JSON generation for iPhone pairing.
- OpenClaw path configuration for installs that are not at
~/.openclaw. - Hermes routing through the existing CLI environment rather than a separate Hermes path field.
- Readiness checks for the local bridge, Tailscale Serve, OpenClaw, Hermes, Realtime auth, required Mac access, and app updates.
- A Tasks & Files screen for route-task status and a bounded Artifact Inbox with authenticated metadata, 50 MB per-file and 500 MB total limits, and explicit manual deletion. Files are never evicted automatically.
- Authenticated task-scoped input uploads for iPhone requests. The iPhone preallocates a task ID, uploads each attachment before task creation, and then creates the task with the uploaded attachment IDs. The Companion verifies byte count and SHA-256 before giving an ordinary route turn the exact private file paths; it does not modify OpenClaw, Hermes, or Codex.
- Signed update checks through the VoiceClaw Realtime release feed.
- Reset actions that remove only VoiceClaw Realtime Companion state and, when proven safe, only the matching Tailscale Serve mapping.
Task input attachments use a separate private store at
~/Library/Application Support/VoiceClaw Realtime Companion/Input Attachments.
The authenticated raw PUT /realtime/tasks/:taskID/attachments/:attachmentID
contract accepts Content-Type, Content-Length,
X-VoiceClaw-Filename-Base64, X-VoiceClaw-Content-SHA256, and
X-VoiceClaw-Byte-Count. Each file is limited to 50 MB, each task to 20 files,
and the store to 500 MB. Verified input files are removed when their task
completes, fails, or is cancelled. Uploads whose task is never created are
removed after 24 hours. These input files never enter the Artifact Inbox.
Set OpenClaw Install Path to the folder that directly contains
openclaw.json. The usual value is:
~/.openclaw
VoiceClaw Realtime Companion uses this path when creating the bridge configuration and
when reporting readiness. Do not point the field at a parent folder unless that
parent folder itself contains openclaw.json.
VoiceClaw Realtime Companion does not have a Hermes install path field. The bridge calls Hermes through the Mac user's command-line environment.
Check Hermes in Terminal first:
hermes --helpIf hermes is installed somewhere unusual, set HERMES_BIN for the bridge
environment. Hermes can also use HERMES_HOME when your Hermes setup requires
it.
VoiceClaw Realtime Companion is designed around local ownership:
- The bridge listens locally on
127.0.0.1and is forwarded by Tailscale Serve. - The Tailscale URL is private to your tailnet by default.
- Bridge configuration is stored at
~/.voiceclaw/bridge.json. - The user LaunchAgent is stored at
~/Library/LaunchAgents/ai.voiceclaw.bridge.plist. - The OpenAI API key is stored by the Companion app in Keychain.
- Setup QR codes and setup links can include secrets if you choose to include them.
- Setup previews redact the API key, but screenshots, logs, setup JSON, setup links, and bridge URLs may still reveal private tailnet hostnames or tokens.
Do not share setup payloads, bridge URLs, screenshots, or logs unless you have checked that they do not contain private hostnames, tokens, or API keys.
VoiceClaw Realtime Companion does not make your Mac public unless you intentionally configure a separate public HTTPS tunnel and put that URL into the advanced Non-Tailscale field.
VoiceClaw Realtime Companion checks the VoiceClaw Realtime release feed for signed updates. Automatic checks are enabled by default and can be adjusted in Diagnostics.
When an update is available, the main window and menu bar item show it. Use the in-app update action or open the Companion download page and download the notarized DMG manually.
- Confirm Tailscale is installed and signed in on both Mac and iPhone.
- Confirm both devices are in the same tailnet.
- Confirm Tailscale HTTPS certificates are enabled in the tailnet admin console.
- In VoiceClaw Realtime Companion, open Diagnostics and click Check Again.
- If the bridge port changed, scan the current QR code again.
Install Tailscale's command-line integration:
- Open Tailscale on the Mac.
- Go to Settings.
- Find CLI integration and click Show me how.
- Choose Add "tailscale" command to PATH.
- Return to VoiceClaw Realtime Companion and click Install and Start again.
Set OpenClaw Install Path to the folder that contains openclaw.json,
usually ~/.openclaw, then run Install and Start again.
Run hermes --help in Terminal. If that fails, install or repair Hermes first.
If it works only from a custom shell setup, configure HERMES_BIN for the bridge
environment so Companion can call the same executable.
Confirm that either ChatGPT Plan (OAuth) is signed in or an OpenAI API key is available for explicit API-key use. Re-pair the iPhone if the Companion-minted OAuth credential has changed. If OAuth is selected, an API key is used only when Fall back to API Key if OAuth fails is enabled.
Reset First-Run State removes only VoiceClaw Realtime Companion's local bridge state:
~/Library/LaunchAgents/ai.voiceclaw.bridge.plist~/.voiceclaw/bridge.json
It does not uninstall Tailscale, change tailnet settings, remove OpenClaw, remove Node.js, remove Hermes, or delete iPhone settings.
Reset App + Tailscale Mapping also removes the selected Tailscale Serve
mapping only when diagnostics prove that mapping points exactly to VoiceClaw Realtime's
local bridge. It refuses to remove unrelated Serve mappings and does not run
Tailscale's full serve reset command.