English | Русский

Personal Communication OS — AI assistant that communicates on your behalf across Telegram, WhatsApp, Discord, Signal, and more, with per-contact style personalization.

ClawMate reads and sends messages from your real Telegram account (via TDLib), supports multi-channel messaging via OpenClaw Gateway (WhatsApp, Discord, Signal, iMessage, etc.), personalizes the style for each contact, enforces safety policies, and lets you manage everything through a Telegram bot with inline buttons.

• Writes from your personal Telegram account (not a bot) using TDLib
• Multi-channel: WhatsApp, Discord, Signal, iMessage, Slack, Matrix, and more via OpenClaw Gateway
• Personalizes responses per contact: tone, formality, length, language, emoji
• Groups contacts: Work, Family, Friends, VIP — each with its own style
• Three modes: auto-reply, draft (review before send), or approval (for sensitive topics)
• Smart notifications: new contacts get Add/Skip buttons; drafts get Send/Edit/Reject — all inline, no inbox needed
• Policy engine: content filters, rate limiting, schedule rules (active hours/days)
• Long-term memory: remembers facts, preferences, events per contact — uses embeddings for semantic search
• Simulates human behavior: typing indicators, read receipts, natural delays
• Safety first: new contacts require explicit approval (Add/Skip); money, meetings, promises, legal, medical, personal data — always flagged for approval
• Detects sensitive topics automatically via intent classification

• Docker + Docker Compose
• Telegram account
• Telegram Bot (create via @BotFather)
• Telegram API credentials (get from my.telegram.org)
• One of (for LLM):
  • OpenClaw instance (recommended — no separate API keys needed!)
  • OpenAI API key (standalone mode)
  • Anthropic API key (standalone mode)

# Clone
git clone https://github.com/AbdrAbdr/ClawMate-oss.git
cd ClawMate-oss

# Configure
cp compose/.env.example compose/.env
# Edit compose/.env — fill in your tokens

# Launch
docker compose -f compose/docker-compose.yml up -d

ClawMate supports three LLM modes. OpenClaw is recommended — no separate API keys needed:

Option 1: OpenClaw (recommended) If you have OpenClaw running, just set the Gateway URL. Brain automatically routes all LLM calls through OpenClaw's configured model:

OPENCLAW_GATEWAY_URL=ws://your-openclaw-host:18789
OPENCLAW_GATEWAY_TOKEN=your_token
# No OPENAI_API_KEY or ANTHROPIC_API_KEY needed!

Option 2: Direct OpenAI (standalone)

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key

Option 3: Direct Anthropic (standalone)

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key

If LLM_PROVIDER is not set, auto-detection picks the best available: OpenClaw Gateway > OpenAI > Anthropic.

When the OpenClaw Gateway vars above are set, Brain also registers adapters for all OpenClaw channels (WhatsApp, Discord, Signal, iMessage, etc.). When not set, only Telegram (TDLib) is active.

1. Open your control bot in Telegram
2. Send /start
3. Use inline buttons to navigate:
   • Add Contact — forward a message, share a contact, pick from TDLib chats, or pick from OpenClaw channels
   • Groups — create groups (Work, Family, Friends, VIP) and set default styles
   • Persona — choose your communication style preset
   • Notifications — when someone new writes, you get a push with Add/Skip; for drafts — Send/Edit/Reject
   • Inbox — fallback list of pending drafts
   • Memory — browse, add notes, search per-contact memory
   • Settings — set global mode, quiet hours, LLM provider, filters

┌──────────────┐  ┌─────────────────┐  ┌───────────────┐
│  Control Bot  │  │      Brain      │  │  TDLib Bridge  │
│  (Telegram)   │──│   (Core API)    │──│  (Your Acct)   │
│  Inline UI    │  │  LLM + Policies │  │  Send/Receive  │
│  Memory Mgmt  │  │  Memory + Style │  │  Human Sim     │
└──────────────┘  └────────┬────────┘  └───────────────┘
                           │
                  ┌────────┴────────┐
                  │  OpenClaw Gateway│  (optional)
                  │  WS + HTTP       │
                  └────────┬────────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
         WhatsApp      Discord       Signal ...

No slash commands except /start. Everything is done through inline keyboard buttons.

Your Persona (global style)
  └─ Group defaults (e.g., "Work" = formal)
       └─ Contact overrides (e.g., "Boss" = extra formal, no emoji)

Each level can override: formality (0-10), length, emoji, humor, language, address form.

Rules are evaluated on every incoming message before LLM generation:

If a policy blocks a message, no response is generated. If it requires approval, a draft is created in the inbox.

Per-contact long-term memory with semantic search:

• Types: fact, preference, summary, event, note
• Embeddings: OpenAI text-embedding-3-small via OpenClaw Gateway or direct API (with offline hash fallback)
• Search: Cosine similarity over embeddings
• Context injection: Relevant memories are included in LLM prompts
• Management: Full CRUD via control bot or REST API

• Unknown contacts trigger a push notification with Add/Skip buttons — you decide inline
• Contacts can be muted (silently ignored) or active (processed by the pipeline)
• Money, meetings, promises, legal, medical, personal data always require your approval
• All messages are logged locally in SQLite
• Your TDLib session stays on your machine
• Rate limiting per contact
• Content filtering with customizable keywords
• Schedule enforcement (quiet hours, active days)

When connected to an OpenClaw Gateway, ClawMate supports:

All non-Telegram channels are routed through a single WebSocket connection to the OpenClaw Gateway. Each channel gets its own adapter registered in the Brain's channel router.

ClawMate-oss/
├── shared/          # Types, Zod schemas, constants
├── brain/           # Core engine (Fastify + Drizzle + SQLite)
│   ├── api/         #   REST endpoints (contacts, groups, personas, approvals, settings, memory, channels)
│   ├── pipeline/    #   Event processing pipeline
│   ├── prompt/      #   Style merging + prompt building
│   ├── llm/         #   LLM adapter (OpenClaw / OpenAI / Anthropic)
│   ├── policies/    #   Content filter, rate limiter, schedule
│   ├── memory/      #   Long-term memory with embeddings
│   ├── router/      #   Multi-channel router + adapters
│   │   ├── adapters/    Standalone: TDLib, WhatsApp, Discord, Signal
│   │   └── openclaw/    OpenClaw Gateway: WS client + per-channel adapters
│   └── storage/     #   Drizzle ORM schema + SQLite
├── control-bot/     # Telegram inline-only admin bot (grammY)
│   └── handlers/    #   10 modular handlers (contacts, groups, styles, notifications, memory, etc.)
├── tdlib-bridge/    # TDLib transport + human simulation
├── installer/       # npx clawmate-oss@latest CLI + OpenClaw skill
├── compose/         # Docker Compose + env template
└── .github/         # CI/CD workflows (build, test, Docker, release)

TypeScript, Node.js 20+, pnpm workspaces, Fastify, grammY, tdl (TDLib), SQLite (better-sqlite3), Drizzle ORM, Zod, OpenClaw Gateway (LLM + multi-channel), OpenAI, Anthropic, Pino, Docker, GitHub Actions

Install ClawMate as an OpenClaw skill:

npx clawmate-oss@latest

This installs the ClawMate skill into your OpenClaw instance, enabling incoming message forwarding from all connected channels to the Brain's event pipeline.

# Run all tests (186 unit tests)
pnpm test

# Build all packages
pnpm -r build

• Project structure & shared types
• Brain service (core engine with full API)
• Control bot (inline-only Telegram admin)
• TDLib bridge (personal account transport)
• Docker Compose one-click deploy
• Installer (npx clawmate-oss@latest)
• CI/CD pipeline (GitHub Actions)
• Policy engine (content filter, rate limiter, schedule)
• Multi-channel router (TDLib + WhatsApp + Discord + Signal)
• OpenClaw Gateway integration (unified multi-channel transport)
• Long-term memory with semantic search
• Memory management UI in control bot
• Channel discovery (pick contacts from OpenClaw channels)
• 186 unit tests across all packages
• OpenClaw LLM integration (Brain delegates all LLM calls through Gateway)
• UX overhaul: push notification-driven contact approval and draft management
• Contact statuses (unknown/active/muted) with inline Add/Skip flow
• Bot and group message filtering
• End-to-end testing
• Web dashboard
• Cloud SaaS version

AGPL-3.0 — see LICENSE

• ClawMate-Cloud — Managed SaaS version (private)
• OpenClaw — Multi-channel gateway