Pinclaw

OpenClaw Pinclaw hardware voice interface channel plugin

Install

openclaw plugins install clawhub:pinclaw

Pinclaw

The first hardware product built for OpenClaw. A tiny wearable AI clip that gives your OpenClaw agent a voice, ears, and a body.

Website | App Store | Docs | Discord | Twitter

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.

text

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

Quick Start

Prerequisites

OpenClaw v2026.5.0 or later
Node.js 22+
Pinclaw iOS app

1. Install the plugin

bash

openclaw plugins install pinclaw --dangerously-force-unsafe-install

Why --dangerously-force-unsafe-install?

OpenClaw's security scanner blocks plugins that read environment variables combined with network requests. Pinclaw does this for legitimate reasons:

process.env + fetch — Reading API keys (IMAGE_API_KEY, TTS_API_KEY) to call AI generation APIs
child_process — Auto-restarting the gateway after login

This plugin is fully open source. Review the code here before installing if you have concerns.

2. Login

bash

openclaw pinclaw login

Enter your pinclaw.ai email and password. Everything else is automatic — relay configuration, gateway restart, and connection verification. You'll see Relay connected! when it's done.

You can also pass credentials directly:

bash

openclaw pinclaw login --email you@example.com --password yourpassword

3. Connect the app

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

Verify

bash

openclaw pinclaw status

You should see relay: configured.

CLI Commands

Command	Description
`openclaw pinclaw login`	Sign in to pinclaw.ai, configure relay, restart gateway — all automatic
`openclaw pinclaw status`	Show relay connection status
`openclaw pinclaw logout`	Remove relay connection

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

text

┌─────────────────────────────────────────────────────┐
│                    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

text

├── index.ts                 # Plugin entry — registers channel, hooks, CLI commands
├── build.mjs                # esbuild script (TS → JS transpile for npm)
├── openclaw.plugin.json     # Plugin manifest (channelConfigs, configSchema)
├── package.json             # npm package config
├── src/
│   ├── channel.ts           # Channel adapter (config, outbound, lifecycle)
│   ├── types.ts             # WebSocket protocol definitions
│   ├── relay-client.ts      # Cloud relay connection
│   ├── cli-auth.ts          # Login/logout/status CLI handlers
│   ├── runtime.ts           # Shared runtime state
│   ├── ws-server.ts         # WebSocket server exports
│   ├── interactive-ai.ts    # Play button — lightweight standalone AI calls
│   ├── core/                # Standalone server (HTTP + WS + device management)
│   ├── acp/                 # Agent Control Protocol (local agent orchestration)
│   └── tools/               # Server-side tools (image gen, audio gen, etc.)
└── dist/                    # Build output (generated, not committed)

Configuration

The plugin configures itself through ~/.openclaw/openclaw.json. Most settings are auto-configured via /pinclaw login:

json

{
  "channels": {
    "pinclaw": {
      "enabled": true,
      "wsPort": 18790,
      "relay": {
        "enabled": true,
        "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:

typescript

// 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.

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

Join our Discord to discuss ideas and get help.

License

MIT License. See LICENSE for details.

Built for OpenClaw
_{The first hardware-native AI wearable for the open-source agent platform.}