Setup

How it works

The setup skill points you at the real entry point: running bash nanoclaw.sh in your terminal. That script handles the full end-to-end setup — from a fresh clone to a named agent you can message — without manual configuration-file edits. Run it directly, not inside a coding-harness session: it needs interactive prompts and real shell I/O for the Node/pnpm bootstrap, Docker, OneCLI, and the container build.

The script works through these steps:

Environment. Checks the basics — Node.js 20+ and pnpm 10+ — and installs them if missing, then pulls dependencies.

Container image. Verifies Docker is installed (installing it if not) and builds the agent container image that every agent session runs in.

OneCLI vault. Installs and configures the OneCLI Agent Vault, the credential proxy that keeps raw API keys out of containers.

Agent provider. Asks which runtime should power the first agent. Claude is the default; Codex can be installed inline. Claude accepts a subscription, OAuth token, or Anthropic API key. Codex accepts a ChatGPT subscription or OpenAI API key. The selected credential is stored in OneCLI, never in the container.

Mount allowlist. NanoClaw’s containers are isolated by default — agents can only access directories you explicitly allow. This step configures which host directories should be available inside the container.

Service. Registers NanoClaw as a background service so it starts automatically and stays running. On macOS this uses launchd; on Linux it uses systemd. After registration, it starts the service immediately.

CLI agent. Creates your first agent — a local “Terminal Agent” you can chat with from the command line.

Timezone. Auto-detects your timezone so scheduling behaves correctly, confirming with you if detection is ambiguous.

Channel pairing. Optionally pairs your first messaging channel — Telegram, Discord, or WhatsApp — or you can stick with the local CLI and add channels later.

Verify and first chat. A final check confirms all components are working, then drops you into a first chat with your new agent.

If a step fails partway through, the script offers provider-aware recovery when an appropriate coding harness is available and resumes from where it stopped.

After setup

Once setup completes, NanoClaw is running in the background. Messages sent to your registered chats are picked up, processed by the selected provider inside an isolated container, and returned through the same channel.

To add more channels later, run the individual channel skills (/add-telegram, /add-slack, etc.). To modify behavior, use /customize. To diagnose issues, use /debug.

The slash form above is Claude Code syntax. In Codex, invoke the same skills as $add-telegram, $customize, or $debug; OpenCode loads the same files through its skill tool.

Tips

• If setup is interrupted or a step errors out, re-running bash nanoclaw.sh resumes from where it stopped.
• Setup installs and uses Docker, the only supported container runtime.
• The service registration step can be skipped. You can run NanoClaw manually with pnpm start (after pnpm run build) if you prefer.

For the current wizard flow and provider choices, see the installation guide and quick start.