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

``bash


Clone and install

git clone
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:

`bash
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:

`bash
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//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:

`bash
npm run docs:dev
`

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

Development

`bash
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