What is Pinclaw?

Pinclaw is a complete personal AI agent system — not just a gadget, not just an app. It's an entire ecosystem purpose-built for OpenClaw:

🔧 Hardware — A tiny clip with a microphone, powered by XIAO nRF52840 Sense. Clip it on, forget it's there.

📱 iPhone App — Real-time speech recognition, intelligent routing, and device skill integration. Your phone becomes the bridge between you and your agent.

☁️ Cloud — Your own OpenClaw instance with your own database, your own agent, your own scheduling. Not shared. Yours.

You speak → Pinclaw Clip (BLE) → iPhone App → OpenClaw Plugin → Gateway → AI
                                                                          ↓
You hear  ← iPhone App ← Plugin ← ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─  AI Response

Quick Start

Already running OpenClaw? Get Pinclaw working in 30 seconds:

# Install the plugin
openclaw plugin add pinclaw

# Start your agent
openclaw gateway run

# In the OpenClaw terminal, login to auto-configure relay:
/pinclaw login

Download the Pinclaw iOS app, sign in with the same account, and you're connected.

CLI Commands

| Command | Description | | ----------------- | ------------------------------------------------ | | /pinclaw login | Open browser to sign in and auto-configure relay | | /pinclaw status | Check current relay configuration | | /pinclaw logout | Remove relay config |

How It Works

The Ecosystem

| Layer | What | Role | | ---------------- | ------------------- | ---------------------------------------------------------------- | | Pinclaw Clip | XIAO nRF52840 Sense | Always-on voice capture, BLE streaming to iPhone | | iPhone App | Swift, native | Speech recognition (Apple + Deepgram), device skills, AI routing | | This Plugin | pinclaw | Channel adapter — bridges iPhone ↔ OpenClaw Gateway | | OpenClaw | Gateway + Agent | Your personal AI runtime, database, scheduling |

Two Ways to Use

Cloud Mode — We run everything. Buy the clip, download the app, and your personal OpenClaw instance is ready. No setup.

My OpenClaw Mode — You run OpenClaw on your own machine. The plugin connects via relay through our cloud, so your iPhone can reach your home server from anywhere.

Device Skills

Your iPhone isn't just a dumb pipe. It registers native capabilities as skills that your AI agent can call:

• Calendar — Read and create events
• Reminders — Manage tasks and to-do lists
• Screenshot — Capture what's on screen
• And more — Any iOS capability can become an agent tool

The AI sees these as tools and calls them when relevant. Say "schedule a meeting tomorrow at 3pm" and the agent calls your iPhone's calendar directly.

Context Awareness

The plugin maintains awareness of your device state — battery level, current calendar events, active reminders. Your agent knows what's happening on your phone even when you don't explicitly tell it.

Architecture

┌─────────────────────────────────────────────────────┐
│                    iPhone App                         │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ BLE Recv │  │ Apple STT│  │ Device Skills      │  │
│  │ (Clip)   │→ │ Deepgram │→ │ Calendar/Reminders │  │
│  └──────────┘  └──────────┘  └───────────────────┘  │
│                      │                                │
│              Unified WebSocket                        │
└──────────────────────┼───────────────────────────────┘
                       │
            ┌──────────▼──────────┐
            │   Pinclaw Cloud     │
            │   (Relay Server)    │
            └──────────┬──────────┘
                       │
            ┌──────────▼──────────┐
            │   This Plugin       │
            │   pinclaw            │
            │                     │
            │  • WS Handler       │
            │  • Device Manager   │
            │  • AI Pipeline      │
            │  • Cron Proxy       │
            │  • Server Tools     │
            └──────────┬──────────┘
                       │
            ┌──────────▼──────────┐
            │   OpenClaw Gateway  │
            │   Your AI Agent     │
            └─────────────────────┘

Plugin Structure

plugin/
├── index.ts                 # Plugin entry — registers channel, injects soul & device context
├── openclaw.plugin.json     # Plugin metadata
├── src/
│   ├── channel.ts           # Channel adapter (config, outbound, lifecycle)
│   ├── types.ts             # WebSocket protocol definitions
│   ├── relay-client.ts      # Cloud relay connection
│   ├── interactive-ai.ts    # Play button — lightweight standalone AI calls
│   ├── core/
│   │   ├── server.ts        # HTTP + WebSocket server
│   │   ├── ws-handler.ts    # Message routing (auth, text, tools, media)
│   │   ├── device-manager.ts# Device connections, skills, context persistence
│   │   ├── gateway-rpc.ts   # Gateway WebSocket RPC
│   │   ├── ai-pipeline.ts   # Message → AI flow with tool context injection
│   │   ├── cron-proxy.ts    # Scheduled task management
│   │   └── skills-crud.ts   # OpenClaw skill file management
│   └── tools/
│       ├── registry.ts      # Auto-discovery of server-side tools
│       └── types.ts         # Tool interface definitions

Configuration

The plugin configures itself through ~/.openclaw/openclaw.json:

{
  "plugins": {
    "allow": ["pinclaw"]
  },
  "channels": {
    "pinclaw": {
      "enabled": true,
      "wsPort": 18790,
      "authToken": "your-secret-token",
      "relay": {
        "enabled": true,
        "token": "your-relay-token",
        "url": "wss://api.pinclaw.ai"
      }
    }
  }
}

Or via environment variables:

| Variable | Purpose | | ------------------------- | --------------------------- | | PINCLAW_RELAY_TOKEN | Relay authentication token | | PINCLAW_RELAY_URL | Relay server URL | | INTERACTIVE_AI_KEY | API key for Play button AI | | INTERACTIVE_AI_BASE_URL | Base URL for Play button AI | | INTERACTIVE_AI_MODEL | Model for Play button AI |

API Endpoints

The plugin exposes HTTP endpoints on port 18790:

| Endpoint | Method | Description | | ----------------------- | ------ | ------------------------------------------- | | /health | GET | Health check (device count, gateway status) | | /ai-health | GET | AI health check (model, latency) | | /api/cron/list | GET | List scheduled tasks | | /api/cron/create | POST | Create a scheduled task | | /api/skills/list | GET | List available skills | | /api/skills/get/:name | GET | Get skill details | | /api/media/upload | POST | Upload media files |

Adding Server Tools

Create a file in src/tools/ and it will be auto-discovered:

// src/tools/weather.ts
import type { ServerTool } from "./types.js";

export default {
  name: "get_weather",
  description: "Get current weather for a location",
  parameters: [
    { name: "city", type: "string", description: "City name", required: true },
  ],
  async execute({ city }) {
    // Your implementation
    return { temperature: 22, condition: "sunny", city };
  },
} satisfies ServerTool;

The AI agent will automatically see and use your tools.

Links

| | | | -------------------- | ------------------------------------------------------------ | | 🌐 Website | pinclaw.ai | | 📱 iOS App | App Store | | 📖 Documentation | pinclaw.ai/doc | | 💬 Discord | Join our community | | 🐦 Twitter | @EricShang98 | | 🛒 Buy Pinclaw | pinclaw.ai | | 🔧 OpenClaw | openclaw.ai |

Contributing

We welcome contributions! Pinclaw is fully open source.

1. Fork this repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes
4. Push and open a Pull Request

Join our Discord to discuss ideas and get help.

License

MIT License. See LICENSE for details.