Connecting to Your OpenClaw Server

This guide covers every way to connect the Chitin apps — Chitin Phone, OpenClawAvatar, and ChitinDesktop — to an OpenClaw server running on your Mac. Use the table below to find the right section for your setup.

Which App for Which Setup?

Why the split? ChitinDesktop is a same-Mac companion — it runs on the same machine as OpenClaw and connects automatically over localhost. The iOS apps were built for remote access and include the full Bridge and Relay architecture for reaching your agent from anywhere. Desktop-to-remote-Desktop is on the roadmap but not shipping yet.

If you run into trouble, jump to Troubleshooting.

Table of Contents

1. Overview
2. Prerequisites
3. Configuring Your Agent for Voice Conversations
4. ChitinDesktop: Same-Mac Connection
5. Method 1: Gateway (LAN) — Direct Local Connection
6. Method 2: Relay (Cloud) — Remote Connection
7. Token Authentication
8. Troubleshooting
9. Future Improvements

Overview

ChitinDesktop (Same-Mac)

Desktop detects your local OpenClaw installation automatically and connects over localhost. No IP addresses, no tokens to copy. Desktop also doubles as a bridge for your iOS apps — once Desktop is running, your iPhone can reach your agent through the relay without a separate ChitinBridge install.

Gateway (LAN) — iOS apps

Your iPhone connects directly to OpenClaw over your local Wi-Fi using a WebSocket connection. This is the lowest-latency option — messages travel straight from your phone to the agent on your Mac with no cloud hops.

• Both devices must be on the same Wi-Fi network.
• URL format: ws://<your-mac-ip>:18789
• First-time connections require a one-time device approval on your Mac.

Relay (Cloud) — iOS apps

Your iPhone connects to the Chitin Relay cloud (wss://relay.chitin.chat), which forwards messages to a bridge running on your Mac — either ChitinBridge.app or ChitinDesktop — which talks to your local OpenClaw. Works from any network.

iOS App  →  Relay (cloud)  →  Bridge on your Mac  →  OpenClaw
iOS App  ←  Relay (cloud)  ←  Bridge on your Mac  ←  OpenClaw

• Works from cellular, coffee shop Wi-Fi, anywhere.
• Requires ChitinBridge.app or ChitinDesktop running on your Mac.
• Slightly higher latency due to the relay hop.
• Requires Chitin Plus.

Prerequisites

Before setting up any connection method, OpenClaw must be installed and running on your Mac.

1. Install OpenClaw (if you haven’t already):

   npm i -g openclaw

   Or with Homebrew:

   brew install openclaw

2. Start the OpenClaw gateway:

   openclaw gateway start

   If you installed it as a LaunchAgent, it starts automatically at login.

3. Verify it’s running:

   openclaw gateway status

   You should see the gateway active on port 18789.

Configuring Your Agent for Voice Conversations

The Chitin apps send messages to an OpenClaw agent. By default, OpenClaw’s main agent is optimized for code and complex tasks — not quick voice conversations. For a good experience, set up a dedicated mobile agent with a fast model and conversational personality.

Step 1: Create a Mobile Agent

openclaw agents create mobile --name "Mobile Avatar" --workspace ~/.openclaw/workspace-mobile

Or add it manually to your openclaw.json:

openclaw config set agents.list '[...existing entries..., {"id":"mobile","name":"Mobile Avatar","workspace":"~/.openclaw/workspace-mobile","model":{"primary":"openrouter/anthropic/claude-haiku-4.5"}}]'

Step 2: Choose a Fast Model

Voice conversations need low-latency responses. Heavy models like GPT-5 or Claude Opus are too slow for spoken conversation. Use something fast:

Recommended models (via OpenRouter):

• openrouter/anthropic/claude-haiku-4.5 — fast, conversational, inexpensive
• openrouter/google/gemini-2.0-flash — very fast, good for casual conversation

The model must also be registered in your mobile agent’s models.json at ~/.openclaw/agents/mobile/agent/models.json. If OpenClaw returns empty responses, this is usually why. Add the model to the openrouter.models array:

{
  "id": "anthropic/claude-haiku-4.5",
  "name": "Claude Haiku 4.5",
  "reasoning": true,
  "input": ["text"],
  "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
  "contextWindow": 200000,
  "maxTokens": 8192
}

For accurate cost values, look up the model at openrouter.ai/models — pricing changes over time and the values above are placeholders.

Step 3: Set Up the Personality

Create a SOUL.md in your mobile agent’s workspace:

cat > ~/.openclaw/workspace-mobile/SOUL.md << 'EOF'
Your name is [Your Agent's Name]. You are a warm, curious AI companion speaking through a mobile avatar. Your responses are spoken aloud via TTS.
 
Rules:
- Keep every response to 1-2 sentences maximum. Never exceed this.
- Never use emojis. Not one. Ever.
- Never use markdown, bullet points, code blocks, or any formatting.
- Never mention being an AI, a language model, or anything technical about yourself.
- Never offer disclaimers, caveats, or qualifications.
- Speak in plain, warm, natural sentences as if talking to a close friend.
- If asked a complex question, give the simplest useful answer in 1-2 sentences.
EOF

And an IDENTITY.md:

cat > ~/.openclaw/workspace-mobile/IDENTITY.md << 'EOF'
# IDENTITY.md
 
- **Name:** [Your Agent's Name]
- **Vibe:** Warm and curious
EOF

And an AGENTS.md to constrain for voice output:

cat > ~/.openclaw/workspace-mobile/AGENTS.md << 'EOF'
# Mobile Avatar Agent
 
You are a concise voice companion on a mobile device. Your output is spoken aloud.
 
Critical constraints:
- 1-2 sentences only. No exceptions.
- No emojis. No formatting. No lists. No markdown.
- Plain text responses only.
- Do not use tools unless explicitly asked.
- Do not run commands or write files.
- Just respond conversationally.
EOF

Step 4: Verify

openclaw agent --agent mobile --message "Hello, what's your name?"

You should get a short, conversational response. If you get “Unknown model” or an empty response, double-check that the model is registered in models.json (Step 2).

Step 5: Make Sure the Gateway Is LAN-Accessible

openclaw config set gateway.bind lan
openclaw gateway restart

Quick Verification Checklist

openclaw agents list          # Should show mobile agent with a fast model
openclaw health               # Gateway should be healthy
openclaw agent --agent mobile --message "tell me a joke"

ChitinDesktop: Same-Mac Connection

ChitinDesktop is designed for use on the same Mac as OpenClaw. It connects automatically — there is no IP address to find. When OpenClaw is installed in the default location under your user account, there is no token to copy either; Desktop reads it from your OpenClaw config automatically.

How It Connects

On first launch, Desktop detects your local OpenClaw installation by probing http://127.0.0.1:18789. If OpenClaw is running, Desktop connects immediately. The connection indicator in the companion window shows a green dot when connected, yellow while connecting, and red if the gateway is unreachable.

Manual URL Override

If your gateway uses a non-default port or address, you can override it:

1. Open Desktop’s Settings.
2. Under OpenClaw, enter the full endpoint in the Gateway URL field (example: http://127.0.0.1:9999).
3. Enter your gateway token in the Auth Token field if token auth is enabled.
4. Click Test Connection, then Save.

The URL field accepts any HTTP endpoint. However, Desktop is designed and tested for same-Mac use. Entering a remote URL (e.g., a Mac on another network via Tailscale) is not a supported configuration — edge cases have not been tested. For remote access from a different machine, use Chitin Phone or OpenClawAvatar with the Relay method instead.

Desktop as a Bridge for iOS

Installing ChitinDesktop gives you two things at once: a companion surface for your Mac, and a bridge that lets your iOS apps connect via the Relay. You do not need a separate ChitinBridge install if you are already running Desktop.

To pair your iPhone with Desktop’s bridge:

1. In Desktop’s menu bar, click the Chitin icon and choose Show QR Code (or find the QR code in the companion window).
2. On your iPhone, open Chitin Phone or OpenClawAvatar, go to Settings > OpenClaw > Relay (Cloud), and tap Scan Bridge QR Code.
3. Point your camera at the QR code on your Mac.
4. The app fills in the relay credentials automatically and connects.

Method 1: Gateway (LAN) — Direct Local Connection

This is the simplest setup for iOS users whose iPhone and Mac are on the same Wi-Fi network.

Step 1: Find Your Mac’s IP Address

Open System Settings, go to Wi-Fi, click Details on your connected network, and look for the IP address — something like 192.168.1.42 or 192.168.86.50.

Or from Terminal:

ifconfig en0 | grep inet

Look for the inet line (not inet6).

Step 2: Make Sure the Gateway Accepts LAN Connections

By default the gateway may only listen on localhost:

openclaw config set gateway.bind lan
openclaw gateway restart

Step 3: Configure the App

1. Open the app on your iPhone.
2. Go to Settings > OpenClaw > Gateway (LAN).
3. Shortcut: If you have ChitinBridge or ChitinDesktop running on your Mac, tap Scan QR Code and scan the QR code from Bridge/Desktop — it fills in the URL and token in one step. Skip to Step 4.
4. Or enter manually: set Gateway URL to ws://<your-mac-ip>:18789 (example: ws://192.168.86.50:18789). If your gateway uses token authentication, enter the token in the Auth Token field. See Token Authentication.
5. Tap Reconnect.

Step 4: Approve Your Device

The first time you connect, the gateway holds the connection as a pending pairing request. Approve it on your Mac:

1. List pending devices:

   openclaw devices list

2. Approve your device:

   openclaw devices approve <deviceId>

3. In the app, tap Reconnect — the indicator should turn green.

This approval is permanent. You won’t need to do it again for the same device.

Note: If you’re running the app in the iOS Simulator on the same Mac as OpenClaw, the device is auto-approved.

Step 5: Verify

Send a message. If you get a response, everything is working.

Method 2: Relay (Cloud) — Remote Connection

Use this method when you want to reach your OpenClaw agent from outside your home network. You need a Chitin Plus subscription and a bridge running on your Mac.

Two bridge options:

• Option A: ChitinBridge.app (recommended) — a native Mac app that runs in the menu bar, starts at login, no terminal required.
• Option B: Node bridge-agent.js (advanced) — manual terminal setup for headless Macs or server-side deployments.

Option A: ChitinBridge.app (Recommended)

Step 1: Download and install ChitinBridge

Download ChitinBridge from the Chitin website. Open the DMG, drag ChitinBridge to Applications, and launch it.

Step 2: Complete the setup wizard

On first launch, Bridge runs a setup wizard that:

• Detects your local OpenClaw installation automatically.
• Connects to the Chitin Relay using your Chitin account.
• Displays a QR code you can scan from your iPhone.
• Offers a “Start at Login” option (recommended — the bridge must be running for relay connections to work).

Step 3: Pair your iPhone

1. Open Chitin Phone or OpenClawAvatar on your iPhone.
2. Go to Settings > OpenClaw > Relay (Cloud).
3. Sign in with your Chitin account if prompted.
4. Tap Scan Bridge QR Code and point your camera at the QR code shown in ChitinBridge on your Mac.
5. The app fills in the relay credentials automatically and connects.

Step 4: Verify

Send a message. You should see a green connection indicator and get a response from your agent. If you enabled “Start at Login,” the bridge will be ready the next time your Mac boots — no terminal window required.

Option B: Node bridge-agent.js (Advanced)

Use this if you are on a headless Mac, prefer manual service management, or can’t run ChitinBridge.app. This is the legacy approach; most users should use Option A.

Prerequisites: Node.js installed; ~/chitin-relay/ directory from your Chitin account.

Step 1: Get your relay credentials

You need a bridgeId and bridgeToken from your Chitin account. If you’ve previously run the ChitinBridge setup wizard, these are already stored in your bridge-config.json. Otherwise, retrieve them from your Chitin account dashboard.

Step 2: Configure the bridge

Edit ~/chitin-relay/bridge-config.json:

{
  "bridgeId": "<your-bridge-id>",
  "bridgeToken": "<your-bridge-token>",
  "bridgeName": "My Mac",
  "relayUrl": "wss://relay.chitin.chat",
  "relayHttpUrl": "https://relay.chitin.chat",
  "openClawUrl": "http://127.0.0.1:18789",
  "openClawToken": "<your-gateway-token>",
  "openClawAgentId": "mobile"
}

Get your openClawToken with:

openclaw config get gateway.auth.token

Step 3: Start the bridge

node ~/chitin-relay/bridge-agent.js

You should see connection messages for both the relay and the local gateway. Keep this terminal open — the bridge must stay running.

Step 4: Configure the app

1. Open the app on your iPhone.
2. Go to Settings > OpenClaw > Relay (Cloud).
3. Sign in with your Chitin account.
4. Tap Reconnect.

After changing your gateway token: Update openClawToken in bridge-config.json and restart the bridge (Ctrl+C, then rerun the command).

Token Authentication

OpenClaw 2026.3 and later recommends token authentication for all connections. Here is how to set it up.

Enable Token Auth

openclaw config set gateway.auth.mode token
openclaw gateway restart

Retrieve Your Token

The gateway auto-generates a token. To see it:

openclaw config get gateway.auth.token

Copy this token. You need it in different places depending on your setup:

After Changing the Token

If you regenerate or change the token:

• iOS apps (LAN method): Update the Auth Token field in Settings and tap Reconnect.
• Node bridge-agent.js: Update bridge-config.json and restart the bridge.
• ChitinBridge.app or ChitinDesktop: Usually no action needed — they re-read the token from ~/.openclaw/openclaw.json automatically, as long as OpenClaw is installed in the default location under your user account. If the connection stays broken after a token change, re-run the gateway configuration step in Bridge or Desktop’s settings.

Forgetting to update the iOS app or node bridge after a token change causes silent authentication failures. See Troubleshooting if connections suddenly stop working.

Troubleshooting

”device signature invalid”

Your device’s identity could not be verified by the gateway. This usually means the app needs an update.

Fix: Update the app to the latest version from the App Store.

”token_missing” or “unauthorized”

Token authentication is enabled but the app sent no token or the wrong one.

Checklist:

• Open Settings > OpenClaw and confirm the Auth Token field is filled in.
• Confirm it matches openclaw config get gateway.auth.token.
• After entering or changing the token, tap Reconnect — the app does not automatically retry with a new token.

”Gateway not reachable” / Connection Times Out

The app cannot reach the gateway at all.

Checklist:

1. Is the gateway bound to LAN?

   openclaw config get gateway.bind

   If it says loopback or localhost:

   openclaw config set gateway.bind lan
   openclaw gateway restart

2. Is a firewall blocking port 18789? Check System Settings > Network > Firewall. OpenClaw (or Node.js) must be allowed to accept incoming connections.

3. Are both devices on the same subnet? Some routers isolate devices on different bands (2.4 GHz vs 5 GHz) or separate VLANs for IoT devices. Both your iPhone and Mac should have IP addresses in the same range (e.g., both starting with 192.168.86.x).

4. Has your Mac’s IP changed? DHCP leases expire. Re-check System Settings > Wi-Fi > Details and update the Gateway URL in the app if it changed.

Device Not Paired / “Approval Required”

When an iOS app connects via Gateway (LAN) for the first time, the gateway holds the connection until you approve it.

openclaw devices list
openclaw devices approve <deviceId>

Then tap Reconnect in the app. This is a one-time step per device.

Note: If you connect via ChitinBridge.app or ChitinDesktop (relay method), the bridge handles its own connection to OpenClaw automatically — you do not need to run these commands for relay connections. The manual approval is only required for direct iOS-to-gateway (LAN) connections.

Relay Returns 401

The bridge connected to the relay successfully, but the gateway rejected it with a 401.

Using ChitinBridge.app or ChitinDesktop: Open Settings and re-run the OpenClaw configuration step in the setup wizard. This refreshes the gateway token stored in Bridge.

Using node bridge-agent.js: The openClawToken in bridge-config.json no longer matches the gateway’s current token.

1. Get the current token:

   openclaw config get gateway.auth.token
2. Update the openClawToken value in ~/chitin-relay/bridge-config.json.
3. Restart the bridge: Ctrl+C, then node ~/chitin-relay/bridge-agent.js.

”HTTP 401 authentication_error: invalid x-api-key”

This is not a connection problem. Your app successfully reached the agent. The agent cannot call its AI model because the provider API key (Anthropic, OpenAI, etc.) is invalid or expired.

Fix:

1. Check which model the agent uses:

   openclaw agents list
2. Update the API credentials in your OpenClaw config, or switch to a model with valid credentials.

Connected but Getting Empty Responses (No Audio)

The app connects and sends messages, but the agent returns nothing. The avatar enters “thinking” mode but never speaks.

Common causes:

1. Model not registered. The agent’s default model isn’t listed in its models.json provider config. OpenClaw fails silently if the model ID isn’t recognized.

   openclaw agents list   # Check which model the mobile agent uses

   Verify that model ID exists in ~/.openclaw/agents/mobile/agent/models.json. See Configuring Your Agent.

2. Wrong agent. The app may be routing to the main agent instead of mobile. The session key should be agent:mobile:main.

3. Expired API key. Test the agent directly:

   openclaw agent --agent mobile --message "say hello"

   If this fails with an auth error, update your API keys in ~/.openclaw/agents/mobile/agent/auth-profiles.json.

Connected but Responses Are Very Slow

The agent responds, but it takes 10–60 seconds instead of 1–3 seconds.

Common causes:

1. Heavy model. Switch to a fast model like openrouter/anthropic/claude-haiku-4.5 or openrouter/google/gemini-2.0-flash.

2. Routing to the wrong agent. If using node bridge-agent.js, check bridge-config.json and confirm openClawAgentId is "mobile", not "main".

Connection Works but the Agent Has the Wrong Personality

OpenClaw agents have their own personality defined in SOUL.md and IDENTITY.md files in their workspace directory. The app’s built-in characters are separate from this.

Fix:

• In the app, go to Settings and use the Override Agent Personality toggle:
  • On: The app sends its own character personality to the agent, overriding the agent’s workspace files.
  • Off: The agent uses its own personality.
• Changing this toggle may require starting a new conversation session to take full effect.

Connection Was Working but Suddenly Stopped

Checklist:

• Did your Mac’s IP change? Update the Gateway URL in the app.
• Did the gateway token rotate? Check openclaw config get gateway.auth.token and update the app (LAN method) or bridge-config.json (node bridge) accordingly.
• Is the gateway still running? openclaw gateway status.
• Is the bridge still running? Check the Bridge menu bar icon (ChitinBridge or Desktop) or the terminal (node bridge).

Future Improvements

The following improvements are planned or under consideration.

iOS Bonjour Auto-Discovery

OpenClaw advertises itself on the local network via Bonjour (_openclaw-gw._tcp.local.). ChitinBridge and ChitinDesktop already use this to find your local OpenClaw installation automatically. The iOS apps could use the same mechanism to discover nearby gateways and present a list instead of requiring a manual IP entry — making LAN setup effectively zero-config.

Auto-Approval for QR-Paired iOS Connections

ChitinBridge and ChitinDesktop already handle their own device approval automatically when connecting to OpenClaw. The same auto-approval could be extended to iOS apps that connect using a QR-bootstrapped token — since possessing the QR code already implies physical access to the Mac, the manual openclaw devices approve step is redundant in that case.

In-App Connection Diagnostics

Currently the app shows a simple green/yellow/red status dot. More detailed diagnostics — “challenge received,” “token rejected,” “relay reachable but gateway not responding” — would help users identify problems without needing developer tools.

Expanding Desktop’s Surface Model

ChitinDesktop today is a same-Mac companion — it runs on the machine where OpenClaw is installed and connects over localhost. The longer-term direction is to make Chitin apps surface-agnostic: any device (phone, Mac, watch, ambient display) should be able to present any agent you have access to. The specific shape of how Desktop fits into that model — whether as a remote-gateway client, a relay-connected surface like Phone, or something else — is still being worked out. For now, use Chitin Phone or OpenClawAvatar on iOS for remote access; they were built for that topology from day one.