Features

3 min read

nclaw provides a rich set of features that make your AI assistant accessible and useful through Telegram. All features work identically across every supported CLI backend.

Multiple CLI Agents

nclaw supports five CLI backends. Set NCLAW_CLI to switch between them:

The multi-model backend auto-selects when NCLAW_MODEL is set — no need to set NCLAW_CLI explicitly. See Multi-Model for provider details.

Session Persistence

Each chat/topic maintains its own session. Conversations are preserved across messages, so you can pick up where you left off. Session data is stored per-chat in the configured NCLAW_DATA_DIR.

Telegram Topics

Each topic in a group chat is a separate project with its own working directory. One group chat with topics becomes a multi-project workspace — each topic gets isolated context, history, and files.

File Handling

Inbound Files

Send any file type to the assistant through Telegram:

• Documents — PDFs, spreadsheets, text files
• Photos — screenshots, diagrams, images
• Audio — voice messages, audio files
• Video — screen recordings, video files
• Stickers — image stickers

Files are downloaded to the chat directory and passed to the assistant. They’re cached by unique ID and size to avoid re-downloading.

Outbound Files

The assistant can send files back to you. When it generates a file (reports, code, exports), it’s delivered as a Telegram document.

Scheduled Tasks

Create recurring or one-time tasks using natural language:

Remind me to check the deployment every weekday at 9am
Every 30 minutes, check if the staging server is healthy
At 3pm today, generate a summary of today's git commits

Tasks support three schedule types:

• Cron — standard cron expressions for complex schedules
• Interval — repeat every N minutes/hours
• One-time — run once at a specified time

Tasks persist in SQLite and reload on startup. Each task can continue the existing chat session or run in a fresh isolated context.

Webhooks

Register HTTP endpoints that forward incoming requests to the assistant:

Create a webhook that receives GitHub push events and summarizes the changes
Set up a webhook for my package tracking updates
Listen for smart home alerts and notify me about unusual activity

When an external service calls the webhook URL, the request (method, headers, query params, body) is forwarded to the assistant in the originating chat. The HTTP endpoint returns 200 immediately; the assistant processes the request asynchronously. Webhooks persist across restarts.

Requires NCLAW_WEBHOOK_BASE_DOMAIN to be set. Webhook URLs follow the pattern https://{BASE_DOMAIN}/webhooks/{UUID}.

Rich Runtime

The Docker image includes git, gh CLI, Chromium, Go, Node.js, and Python/uv. The assistant can install additional packages on the fly as needed — for example, apk add ffmpeg to process video, npm install -g prettier to format code, or pip install pandas to analyze data.

Message Formatting

Responses render using Telegram’s HTML formatting with plain-text fallback. Long messages are automatically split at newline boundaries (max 4096 chars per message) to stay within Telegram’s limits.