ClawTime — Local Installation with Cloudflare Tunnel

ClawTime is a private webchat UI connecting to the OpenClaw gateway via WebSocket.
Features: passkey (Face ID/Touch ID) auth, Piper TTS voice, 3D avatar.

Why Cloudflare is required: WebAuthn (passkeys) need HTTPS on a real domain.
http://localhost only works on the same machine — not from a phone on your network.

Architecture

CODEBLOCK0

Prerequisites

• - Node.js v22+
• INLINECODE1 CLI: INLINECODE2
• A domain with DNS on Cloudflare (free tier works)
• OpenClaw running: INLINECODE3
• (Optional) Piper TTS + ffmpeg for voice

Installation Steps

1. Clone & install

CODEBLOCK1

2. Set up Cloudflare Tunnel

CODEBLOCK2

~/.cloudflared/config.yml:
CODEBLOCK3

Then in Cloudflare DNS dashboard: add a CNAME record:

• - Name: portal → Target: <tunnel-id>.cfargotunnel.com (Proxied ✅)

3. Configure OpenClaw gateway

The gateway must whitelist ClawTime's origin:

CODEBLOCK4

⚠️ PUBLIC_URL must match this origin exactly — it's used as the WebSocket origin header for device auth.

4. Start ClawTime server

Minimum (no TTS):
CODEBLOCK5

With Piper TTS:
CODEBLOCK6

⚠️ TTS Security Note: The {{TEXT}} placeholder is substituted into a shell command.
ClawTime's server must sanitize text before substitution to prevent command injection.
The server should strip or escape shell metacharacters (; | & $ \ ( ) { } < >) from user input before passing it to the TTS command. If you're modifying the TTS pipeline, use childprocess.execFile() with argument arrays instead of childprocess.exec() with string interpolation. ### 5. Start Cloudflare tunnel CODEBLOCK7 ### 6. Register passkey (first time only) 1. Open https://portal.yourdomain.com/?setup= in **Safari** 2. Follow the passkey (Face ID / Touch ID) prompt 3. ❌ Do NOT use private/incognito mode — Safari blocks passkeys there 4. ❌ Do NOT use Chrome on iOS — use Safari After registration, access ClawTime at https://portal.yourdomain.com. --- ## Environment Variables | Variable | Required | Description | |----------|----------|-------------| | PUBLICURL | ✅ | Public HTTPS URL (must match allowedOrigins in gateway config) | | GATEWAYTOKEN | ✅ | OpenClaw gateway auth token | | SETUPTOKEN | For registration | Passphrase for ?setup= passkey registration URL | | TTSCOMMAND | For voice | Piper command with {{TEXT}} and {{OUTPUT}} placeholders | | BOTNAME | No | Display name (default: "Beware") | | BOTEMOJI | No | Avatar emoji (default: "🌀") | | PORT | No | Server port (default: 3000) | ### Storing Tokens Securely (recommended) Instead of passing tokens as plaintext env vars or in plist files, store them in macOS Keychain: CODEBLOCK8 Then retrieve them at launch time: CODEBLOCK9 This avoids storing secrets in plaintext on disk. --- ## Device Authentication (Critical) ClawTime authenticates with the OpenClaw gateway using Ed25519 keypair auth. This is where most installs break — see details in references/device-auth.md. **Quick summary:** - Keypair auto-generated in ~/.clawtime/device-key.json on first run - Device ID = SHA-256 of raw 32-byte Ed25519 pubkey (NOT the full SPKI-encoded key) - Signature payload format: v2|deviceId|clientId|clientMode|role|scopes|signedAtMs|token|nonce - If device auth fails → delete ~/.clawtime/device-key.json and restart --- ## Auto-Start on Boot (macOS launchd) See references/launchd.md for plist templates for both the server and tunnel. --- ## Managing Services CODEBLOCK10 --- ## Getting the Gateway Token CODEBLOCK11 --- ## Passkey Operations CODEBLOCK12 --- ## Troubleshooting See references/troubleshooting.md for all common errors and fixes. See references/device-auth.md` for deep-dive on gateway auth issues.