Integration Guide

Five ways to connect Open Face to your agent stack.

1. OpenClaw Plugin

Best for: local coding agents using OpenClaw

The plugin maps OpenClaw lifecycle events directly into face states and emotions. It handles thinking, working, speaking, and idle transitions automatically.

# Install the plugin
cp -r packages/plugin ~/.openclaw/plugins/openface

# Start the face server
bun run dev

# Open the dashboard
open http://localhost:9999/dashboard

The plugin uses the single-authority model: it owns state transitions, TTS owns audio, the viewer owns amplitude. It never pushes amplitude directly.

2. Claude / MCP Tools

Best for: Claude Desktop, VS Code, JetBrains integrations

Expose 8 face control tools to any Claude-compatible MCP client. Claude can set states, trigger speech, control gaze, and emote — all through natural language.

# Start MCP bridge
FACE_URL=http://127.0.0.1:9999 bun packages/mcp/src/index.ts

Tools: set_face_state, face_speak, set_face_look, face_wink, set_face_progress, face_emote, get_face_state, face_reset.

3. HTTP / WebSocket

Best for: custom stacks, Python, Go, shell scripts, automation

Push state updates from any runtime via REST or WebSocket. Works with any language that can send JSON.

# Push a state update
curl -X POST http://127.0.0.1:9999/api/state \
  -H "Content-Type: application/json" \
  -d '{"state":"speaking","emotion":"happy","text":"Hello!"}'

# Or use the TypeScript client
import { OpenFaceClient } from "@openface/client";
const face = new OpenFaceClient("http://127.0.0.1:9999");
await face.setState({ state: "thinking", emotion: "happy" });
await face.speaking("Hello world!");

See the API Reference for all endpoints.

4. Web Component

Best for: websites, dashboards, kiosks, overlays

Drop a single script tag and custom element into any HTML page. Works standalone (local animation) or server-backed (live WebSocket).

<!-- Load the component -->
<script type="module" src="open-face.js"></script>

<!-- Standalone (no server needed) -->
<open-face face="default" state="idle" emotion="neutral"></open-face>

<!-- Server-backed (live updates) -->
<open-face server="ws://localhost:9999/ws/viewer" face="default"></open-face>

Attributes: face, state, emotion, amplitude, server, style-variant, volume, debug-overlay.

5. Cloudflare Edge

Best for: internet-facing deployments, multi-room, low latency

Deploy the face server as a Cloudflare Worker with Durable Objects. Each room gets an isolated state holder with per-room WebSocket connections (up to 50 viewers, 5 agents).

# Deploy to Cloudflare
cd packages/server-edge
wr deploy

Rooms are created on demand: /room/my-room/ws/viewer. Same protocol, same behavior, deployed at the edge.

Quick Reference

# Start everything locally
bun install
bun run dev          # Build + start server on :9999

# Open face viewer
open http://localhost:9999

# Open dashboard
open http://localhost:9999/dashboard

# Run tests
bun run test         # 330+ tests