NanoClaw Claude skills

Setting up NanoClaw step by step

NanoClaw runs on macOS or Linux. On Windows it runs through WSL2. You need Docker Desktop on macOS and Windows, or Docker Engine on Linux. The setup script installs Docker for you if it is missing, but it helps to know which one you will end up with.

1. Clone the repo and start the setup script. The README clones into a nanoclaw-v2 directory:

   git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
   cd nanoclaw-v2
   bash nanoclaw.sh
   

2. Let the script work through its stages: Node and pnpm, Docker, the credential gateway (where your Anthropic credential is registered), and the agent container build.

3. Pick a first channel. The options are Slack, Telegram, Discord, WhatsApp, iMessage, or a local CLI. The local CLI lets you talk to the agent before you create any bot tokens or chat accounts.

4. If you opted into the free account, setup opens the portal in your browser once. You sign in there and approve the terminal you are running from. The browser only sees a one-time sign-in code. The install token goes from the account service straight to your machine and is stored with the sign-in record in ~/.config/nanoclaw/account.json with mode 0600. To log a machine out later, forget it under Devices in the portal, and its token stops working.

Once the first agent answers, the README suggests asking Claude Code to walk you through the codebase before you change anything. NanoClaw is built around editing code rather than config files, so that walkthrough is how you learn where to make changes.

Migrating from NanoClaw v1

v1 users do not have to start over. Clone v2 into a fresh directory next to your existing install and run the migration script:

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash migrate-v2.sh

migrate-v2.sh looks for v1 in a sibling directory. If yours is somewhere else, set NANOCLAW_V1_PATH=/path/to/nanoclaw. The script merges your .env, seeds the v2 database from registered_groups, and copies group folders, session data and scheduled tasks. It also installs the channel adapters you select, copies channel auth state (including the Baileys keystore for WhatsApp), and builds the agent container. After that it hands off to Claude Code for the steps that need judgment: owner seeding, shared memory migration and replaying your fork customizations.

Run the script from a normal terminal, not inside a Claude session. The README says the deterministic part needs interactive prompts and real shell I/O for the Node and pnpm bootstrap, Docker, the credential gateway and the container build.

The script does not switch the system service over to v2. You can choose "switch to v2" at the prompt, or switch manually once you have tested it. Your v1 install stays untouched either way. The repo documents the differences in docs/v1-to-v2-changes.md.

What the add-* skills look like in practice

The setup skills are written as careful, multi-phase procedures. Each one checks whether it has already been applied and stops on conflicts.

add-anydoc shows the pattern. It adds local conversion of Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV and text-based PDF files to Markdown inside the agent container, using the Firecrawl AnyDoc CLI pinned at 0.1.6. Before touching any files, it has Claude read CONTRIBUTING.md, docs/skill-guidelines.md and the supply chain section of docs/SECURITY.md. It then checks the npm registry to confirm the version exists, is not deprecated, and has been published for at least 72 hours. It inspects container/cli-tools.json for duplicate or conflicting pins. It also installs a container skill, convert-documents-to-markdown, that the agent uses at runtime. That skill tells the agent to treat converted content as untrusted, to quote attachment paths safely, and never to upload a failed document to a hosted parser without your permission. Scanned and image-only PDFs are not supported because they need OCR.

add-atomic-chat-tool adds a stdio MCP server so the container agent can call local models served by the Atomic Chat desktop app on http://127.0.0.1:1337/v1. It exposes two tools, atomic_chat_list_models and atomic_chat_generate. Claude remains the orchestrator. The skill copies its source and tests into both the container (Bun) tree and the host (Node) tree. It registers the server in index.ts and forwards host environment variables in container-runner.ts. Atomic Chat is macOS only for now, according to the skill.

Some add-* folders contain nested container-skills directories, such as dial-cli under add-dial-tool. These are installed inside the agent's container, while the outer skill runs in Claude Code against your fork.

How container isolation and the credential gateway fit together

Each agent runs in its own Linux container and sees only what is explicitly mounted. Bash commands the agent runs execute inside that container, not on your host. The README contrasts this with OpenClaw, which it describes as nearly half a million lines of code, 53 config files and 70+ dependencies. OpenClaw relies on allowlists and pairing codes, and everything runs in one Node process with shared memory.

API keys are handled separately from the containers. Agents never hold raw keys. Outbound requests go through the credential gateway, which injects credentials at request time and enforces per-agent policies and rate limits.

The newest Slack setup builds on the same per-agent model. Setup provisions a separate Slack app for each agent, including manifest, avatar and workspace install, with no tokens to paste. You can spawn new teammates from chat. Each one gets its own bot identity, container and memory, and they share rooms and canvases.