Skip to main content

​
Quick start

Get NanoClaw up and running in minutes. Claude Code handles everything: dependencies, authentication, container setup, and service configuration.
This guide assumes you have Node.js 20+ and Claude Code installed. See Installation for detailed requirements.

​
Setup process

1

Fork and clone the repository

Fork qwibitai/nanoclaw on GitHub, then clone your fork:
git clone https://github.com/<you>/nanoclaw.git
cd nanoclaw
Forking gives you a remote to push your customizations to. If you just want to try things out, git clone https://github.com/qwibitai/nanoclaw.git works too — you can migrate to a fork later.
2

Launch Claude Code

Open Claude Code in the NanoClaw directory:
claude
This launches Claude Code with access to the NanoClaw codebase.
3

Run the setup command

In Claude Code, run:
/setup
Claude Code will automatically handle:
  • Installing Node.js dependencies
  • Setting up your container runtime (Apple Container or Docker)
  • Building the agent container image
  • Authenticating with Claude
  • Installing the skills marketplace plugin
  • Asking which messaging channels you want
  • Running the setup skill for each selected channel
  • Starting the background service
The /setup skill is AI-native: no installation wizard, just Claude guiding you through each step.
4

Choose your messaging channels

Claude will ask which platforms you want to connect:
  • WhatsApp — via whatsapp-web.js (QR code or pairing code auth)
  • Telegram — via grammy (BotFather token)
  • Discord — via discord.js (bot application token)
  • Slack — via @slack/bolt (Socket Mode app)
  • Gmail — via Google API (OAuth credentials)
Pick one or more. Claude runs the corresponding /add-* skill for each selection, walking you through platform-specific authentication and configuration.
You can always add more channels later with /customize or by running individual skills like /add-telegram.
5

Configure your main channel

Claude will ask you to configure:Trigger word: The word that activates NanoClaw (default: @Andy)Main channel: The chat where you have full admin control over all groups. Depending on your platform this might be:
  • A self-chat or DM with the bot
  • A private group or channel
  • A dedicated conversation
Mount allowlist (optional): Allow agents to access external directories
Your main channel has admin privileges. Other groups get standard access.
6

Verify the setup

Claude will verify that everything is running correctly:✓ Service running ✓ Credentials configured ✓ Messaging channel(s) authenticated ✓ Main channel registered ✓ Container runtime readyIf any checks fail, Claude will help you fix them.
7

Send your first message

Open your connected messaging platform and send a message to your main channel:
@Andy hello!
NanoClaw should respond. You’re all set!
In self-chat or DM mode, the trigger word is optional. Just send any message and NanoClaw will respond.

​
What happens during setup?

Here’s what Claude Code does when you run /setup:
  • Verifies Node.js 20+ is installed
  • Runs npm install to install dependencies
  • Tests that native modules (better-sqlite3) load correctly
  • Detects your platform (macOS/Linux) and environment (WSL, headless)
  • macOS: Offers choice between Docker (default) or Apple Container (native)
  • Linux: Uses Docker (only option)
  • Installs the chosen runtime if not present
  • Starts the runtime service
  • Builds the agent container image
  • Tests that containers can run successfully
  • Asks if you have a Claude subscription (Pro/Max) or Anthropic API key
  • Subscription: Guides you to run claude setup-token and add token to .env
  • API key: Guides you to add ANTHROPIC_API_KEY to .env
  • These credentials allow agents to authenticate with Claude Code
  • Checks if the upstream remote exists; adds it if not: git remote add upstream https://github.com/qwibitai/nanoclaw.git
  • Verifies origin points to your fork (not qwibitai)
  • Installs the skills marketplace plugin so feature skills are available
  • Asks which messaging channels you want (WhatsApp, Telegram, Discord, Slack, Gmail)
  • Runs the corresponding /add-* skill for each selected channel
  • Each skill merges its skill/* branch and walks you through platform-specific auth
  • After a channel is set up, offers relevant add-ons (e.g., Agent Swarm, voice transcription)
  • Syncs groups/chats from your connected platforms
  • Registers your main channel in the database
  • Creates the main group folder at groups/main/
  • Sets up the CLAUDE.md memory file
  • Creates mount allowlist at ~/.config/nanoclaw/mount-allowlist.json
  • macOS: Creates launchd service at ~/Library/LaunchAgents/com.nanoclaw.plist
  • Linux: Creates systemd service (user or system level)
  • WSL without systemd: Creates start-nanoclaw.sh wrapper script
  • Starts the service
  • Verifies the service is running
At the end of setup, Claude may ask if you’d like to share anonymous diagnostics (OS, architecture, NanoClaw version, selected channels). You’ll see the exact data before anything is sent. Choose Yes, No, or Never ask again to permanently opt out. See Security overview for details.

​
Usage examples

Once setup is complete, you can start using NanoClaw from any connected channel: 
@Andy what's the weather like today?
@Andy write a Python script to parse CSV files
@Andy summarize this document [attach file]

​
Next steps

Customizing NanoClaw

Learn how to modify NanoClaw for your needs

Security model

Understand how container isolation works

Adding skills

Install additional capabilities like /add-telegram

Troubleshooting

Fix common issues

​
Monitoring and logs

Check what NanoClaw is doing: 
# View real-time logs
tail -f logs/nanoclaw.log

# Check service status
# macOS
launchctl list | grep nanoclaw

# Linux
systemctl --user status nanoclaw
Or just ask Claude Code: 
Why isn't the scheduler running?
What's in the recent logs?
Why did this message not get a response?
That’s the AI-native approach: no monitoring dashboard, just ask Claude what’s happening.

​
Updating NanoClaw

To pull upstream changes and merge with your customizations: 
/update-nanoclaw
Claude Code will:
  • Fetch the latest changes from upstream
  • Merge with your local modifications
  • Run any database migrations
  • Rebuild the container if needed
  • Restart the service
  • Optionally check for skill updates
Last modified on March 23, 2026