Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nanoclaw.dev/llms.txt

Use this file to discover all available pages before exploring further.

From a fresh machine to an agent you can message — one command, a handful of prompts, a few minutes.
This guide covers the default installer. If you want to skip steps, reuse an existing OneCLI instance, or point Anthropic traffic at a custom endpoint, see Installation.

​
The one-command flow

1

Clone the repository

Clone upstream directly if you just want to try things out:
git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw
If you plan to customize, fork qwibitai/nanoclaw on GitHub first and clone your fork. You can always add the fork remote later — the installer and /update-nanoclaw skill handle both shapes.
2

Run the installer

bash nanoclaw.sh
This is the whole install command. nanoclaw.sh walks you through:
  • Installing Node 22, pnpm, and Docker if they’re missing
  • Verifying your environment (platform, WSL detection, container runtime)
  • Building the agent container image
  • Registering your Anthropic credential with OneCLI
  • Pairing your first channel (Telegram, Discord, WhatsApp, Signal, Teams, Slack, iMessage, or the local CLI)
  • Installing a systemd or launchd service so NanoClaw starts with your machine
If any step fails, Claude Code is invoked automatically to diagnose and resume from where it broke. You don’t have to debug the installer yourself.
3

Answer the setup prompts

Running through clack, you’ll be asked:
  • Display name — what you want your agent to be called (default: Andy)
  • Anthropic credential method — Claude subscription (OAuth), Anthropic API key, or skip
  • First channel — Telegram, Discord, WhatsApp, Signal, Teams, Slack, iMessage, or local CLI. You can add more later.
  • Channel-specific auth — pairing code, QR code, bot token, app credentials, or no extra auth for CLI, depending on the platform
The flow is linear. One question at a time. You can Ctrl+C and restart; the installer picks up where you left off.
4

Authorize Anthropic

The one step that hands off from the scripted flow: claude setup-token opens a browser for OAuth and prints a long-lived token back into your terminal. The installer captures the status and returns to the clack flow once the token is stored in OneCLI.If you chose to skip Anthropic auth or use an API key instead, this step is skipped or replaced with a password prompt.
5

Send your first message

When the installer finishes, it prints the invocation pattern for your chosen channel. For Telegram that looks like:
@Andy hello!
For the local CLI:
pnpm run chat hi
Your agent responds. You’re set.

​
What the installer writes to disk

NanoClaw is transparent about what it does. Every run produces three log streams:
LevelWhereWhat’s in it
Terminal (clack)Your screenBranded status + prompts, spinner per step
Progression loglogs/setup.logOne entry per step: timestamp, duration, status, key facts
Raw per-step logslogs/setup-steps/NN-step-name.logFull verbatim stdout + stderr from the step
If something looks wrong after install, logs/setup.log is the first file to read.

​
What happens behind the scenes

  • Installs Node 22 via nvm, corepack-enables pnpm
  • Runs pnpm install --frozen-lockfile
  • Verifies better-sqlite3 loads on your platform
  • Detects WSL, headless environments, and Apple Silicon
  • Emits a BOOTSTRAP status block to the progression log
Driven by setup/auto.ts. Each sub-step emits a structured status block and writes its raw output to logs/setup-steps/NN-<name>.log:
  • environment — Docker / Apple Container detection, runtime selection
  • container — builds the checkout-scoped agent image via container/build.sh
  • onecli — installs OneCLI Agent Vault or reuses an existing configured instance
  • auth — registers Anthropic credentials in OneCLI
  • cli-agent — wires the terminal agent and confirms it responds before optional channel setup
  • timezone — detects or resolves your IANA timezone
  • channel pairing — runs the selected setup flow for Telegram, Discord, WhatsApp, Signal, Teams, Slack, or iMessage
  • service — launchd (macOS) / systemd (Linux) / start-nanoclaw.sh wrapper (WSL without systemd)
  • verify — checks credentials, service status, registered groups, and first-agent connectivity
  • diagnostics — optional opt-in PostHog event with platform + channel choice
claude setup-token owns the TTY during OAuth. It opens your browser, prints the token, and inherits stdio fully — we don’t mirror the token to any log file (that would add attack surface). Control returns to the clack flow on exit.
  • macOS — creates a launchd service named like com.nanoclaw-v2-<slug> in ~/Library/LaunchAgents/
  • Linux (systemd) — user service named like nanoclaw-v2-<slug>.service; enables loginctl linger so the service survives SSH logout
  • WSL without systemd — creates a start-nanoclaw.sh wrapper; you run it manually on login or wire it to .bashrc

​
Usage examples

@Andy what's the weather like today?
@Andy write a Python script to parse CSV files
@Andy summarize this document [attach file]

​
Monitoring and logs

# Live log stream
tail -f logs/nanoclaw.log

# Service status
launchctl list | grep nanoclaw     # macOS
systemctl --user list-units 'nanoclaw*'  # Linux
Or just ask: 
@Andy why isn't the scheduler running?
@Andy show me the last 50 log lines
@Andy why did this message not get a response?

​
Next steps

Add more channels

/add-slack, /add-whatsapp, /add-signal — install or wire channels from the current channel setup flows

Customize

Change the trigger word, tune timeouts, adjust engage modes

Security model

Sender allowlists, user roles, unknown-sender policies

Troubleshooting

Common issues and how Claude Code helps you fix them

​
Updating NanoClaw

To pull upstream changes and merge with your customizations: 
/update-nanoclaw
This skill fetches upstream/main, merges with your local changes, runs any migrations, rebuilds the container if needed, restarts the service, and scans the changelog for [BREAKING] entries — offering to run the /migrate-nanoclaw skill when a breaking change applies.
Migrating from v1? Run /migrate-nanoclaw for a clean-base replay of your customizations on top of v2, or /update-nanoclaw for a selective cherry-pick. A dedicated v1 → v2 migration guide is coming; until then, the upstream CHANGELOG covers every breaking change.
Last modified on April 28, 2026