DotClaw

Personal OpenRouter-based assistant for Telegram and Discord. Each request runs inside an isolated Docker container with long-term memory, scheduling, and tool governance.

Features

• Multi-provider messaging (Telegram + Discord) with per-group isolation
• Containerized agent runtime with strict mounts
• Rich I/O tools (file/photo/voice/audio/location/contact/poll/buttons/edit/delete)
• Incoming media ingestion to workspace (/workspace/group/inbox) for agent processing
• Voice transcription and text-to-speech
• Browser automation (Chromium in-container)
• MCP server integration (stdio transport)
• Lifecycle hooks (message, agent, task, memory events)
• Real-time streaming responses with edit-in-place delivery
• Long-term memory with embeddings and semantic search
• Scheduled tasks (cron and one-off)
• Tool policies and daily budgets
• Plugin tools and Autotune optimization
• Prometheus-compatible metrics and status dashboard

Prerequisites

• Node.js 20+
• Docker (running)
• At least one provider token:
  • Telegram bot token (from @BotFather), or
  • Discord bot token
• OpenRouter API key

Quick Start

# Clone and install
git clone <repo-url>
cd dotclaw
npm install

# Interactive setup (prompts for API keys, registers your main chat)
npm run bootstrap

# Build and start
npm run build
npm start

The bootstrap will create configuration in ~/.dotclaw/ and optionally build the Docker image.

CLI Commands

After installation, use the dotclaw CLI:

dotclaw setup        # Full setup (init + configure + build + install service)
dotclaw configure    # Re-configure API keys and model
dotclaw start        # Start the service
dotclaw stop         # Stop the service
dotclaw restart      # Restart the service
dotclaw logs         # View logs (add --follow to tail)
dotclaw status       # Show service status
dotclaw doctor       # Run diagnostics
dotclaw register     # Register a new chat (Telegram or Discord)
dotclaw unregister   # Remove a registered chat
dotclaw groups       # List registered chats
dotclaw build        # Build the Docker container image
dotclaw add-instance # Create and start an isolated instance
dotclaw instances    # List discovered instances
dotclaw install-service   # Install launchd/systemd service
dotclaw uninstall-service # Remove launchd/systemd service
dotclaw version      # Show installed version
dotclaw help         # Show help

Instance flags:

dotclaw status --id dev   # Run against a specific instance (~/.dotclaw-dev)
dotclaw restart --all     # Restart all instances

Configuration

All configuration and data is stored in ~/.dotclaw/:

~/.dotclaw/
  .env                    # Secrets (provider tokens, OpenRouter key, optional Brave/GH keys)
  config/
    runtime.json          # Runtime overrides
    model.json            # Model selection
    behavior.json         # Agent behavior tuning
    tool-policy.json      # Tool allow/deny rules
    tool-budgets.json     # Daily tool limits
  data/
    registered_groups.json
    store/                # SQLite databases
  groups/
    main/CLAUDE.md        # Main group memory
    global/CLAUDE.md      # Global memory
  logs/
  groups/<group>/logs/    # Per-group container logs

Mount allowlist (for additional container mounts) lives at:

~/.config/dotclaw/mount-allowlist.json

Documentation

Full documentation lives in docs/. View it locally:

npm run docs:dev

Or see:

• Getting started: docs/getting-started/quickstart.md
• Configuration: docs/configuration/index.md
• Operations: docs/operations/index.md

Development

npm run dev          # Run from source (tsx)
npm run dev:up       # Full dev cycle: rebuild container + kill stale daemons + start dev
npm run dev:down     # Remove all running dotclaw agent containers
npm run build        # Compile TypeScript (host)
npm run build:all    # Build both host and container
npm run lint         # Run ESLint
npm test             # Run tests
dotclaw build        # Rebuild agent container (or: ./container/build.sh)

License

MIT