Bridge Setup Guide

Connect your AI companion apps to your local AI server

Welcome

Chitin Bridge is a free macOS menu bar app that connects your Chitin companion apps (Chitin Avatar and Chitin Phone) to your local AI server. Once installed, your AI companion works from anywhere — at home on WiFi, or remotely through the Chitin relay.

What You'll Need

1

Download & Install

  1. Download ChitinBridge.dmg from chitin.chat/bridge
  2. Open the .dmg file
  3. Drag "Chitin Bridge" to your Applications folder
  4. Launch Chitin Bridge from Applications (or Spotlight)
  5. If macOS shows a security warning: Open System Settings → Privacy & Security → Click "Open Anyway"
  6. You'll see a small bridge icon appear in your menu bar — this means the app is running
2

Create Your Account

  1. The setup wizard opens automatically on first launch
  2. Click "Get Started"
  3. Choose "Create Account" or "Sign In" if you already have one
  4. Enter your email and password
  5. Click the button to continue
3

Connect Your Phone

You have two options:

Option A: QR Code (Recommended)

  1. A QR code appears on your Mac screen
  2. On your iPhone, open Chitin Avatar or Chitin Phone
  3. Go to Settings → Scan QR Code
  4. Point your camera at the QR code on your Mac
  5. The apps connect automatically — you'll see the wizard advance to the next step

Option B: Manual Pairing Code

  1. On your iPhone, open Chitin Avatar or Chitin Phone
  2. Go to Settings → Relay → Pair New Bridge
  3. A code like KTVW-8886 appears on your phone
  4. Type this code into the text field on your Mac
  5. Click "Connect"
4

OpenClaw Configuration

Chitin Bridge auto-detects your OpenClaw installation. You'll see:

If everything looks correct, click "Use These Settings."

OpenClaw not detected?

Click "Configure Manually" and enter your OpenClaw endpoint URL. For the gateway token, open Terminal and run:

openclaw config get gateway.auth.token

Paste the token and click "Test Connection" to verify.

Important: LAN Access

If your OpenClaw gateway is set to "loopback" mode (local connections only), the wizard will offer to enable LAN access. This is needed if you want your phone to connect directly over WiFi (in addition to relay). Click "Enable LAN Access" to configure this automatically.

5

Auto-Start

Toggle "Start at Login" to ON (recommended). This ensures Chitin Bridge runs automatically whenever you log into your Mac — your AI companion is always reachable.

6

Done!

Click "Done." The setup wizard closes and Chitin Bridge is running in your menu bar.

Using Chitin Bridge

Menu Bar Icon Colors

Menu Bar Options

Click the bridge icon to see:

Troubleshooting

Bridge shows yellow (OpenClaw unreachable)

  • Make sure OpenClaw is running. Open Terminal and run: 
    openclaw gateway status
  • If it says "not running," start it: 
    openclaw gateway start
  • Check the endpoint URL in Bridge settings matches your OpenClaw port

Bridge shows red (disconnected from relay)

  • Check your internet connection
  • The bridge will automatically reconnect — wait a moment
  • If it persists, click the menu bar icon → Disable, then Enable again

QR code won't scan

  • Make sure your iPhone camera has permission for the Chitin app
  • Hold your phone steady, about 6–12 inches from the screen
  • Make sure the QR code is fully visible
  • Try the manual pairing code option instead

"OpenClaw not detected" during setup

  • OpenClaw may not be installed, or installed in a non-standard location
  • Use "Configure Manually" and enter the endpoint URL directly
  • Default is http://127.0.0.1:18789

Bridge doesn't start on login

  • Open the menu bar menu and make sure "Start at Login" is checked
  • In System Settings → General → Login Items, verify "Chitin Bridge" is listed

Messages aren't going through

  • Check both indicators are green (relay + OpenClaw)
  • Make sure your iPhone app is set to Relay mode (not WiFi/Gateway mode)
  • Try sending a test message

Privacy & Security

Getting Help

© 2026 Chitin LLC. All rights reserved.

chitin.chat