setup

name	setup
description	Run initial NanoClaw setup. Use when user wants to install dependencies, configure QQ bot, register their main channel, or start the background services. Triggers on "setup", "install", "configure nanoclaw", or first-time setup requests.

NanoClaw Setup

Run setup steps automatically. Only pause when user action is required (entering credentials, configuration choices). Setup uses bash setup.sh for bootstrap, then npx tsx setup/index.ts --step <name> for all other steps. Steps emit structured status blocks to stdout. Verbose logs go to logs/setup.log.

Principle: When something is broken or missing, fix it. Don't tell the user to go fix it themselves unless it genuinely requires their manual action (e.g. pasting a secret token). If a dependency is missing, install it. If a service won't start, diagnose and repair. Ask the user for permission when needed, then do the work.

UX Note: Use AskUserQuestion for all user-facing questions.

1. Bootstrap (Node.js + Dependencies)

Run bash setup.sh and parse the status block.

• If NODE_OK=false → Node.js is missing or too old. Use AskUserQuestion: Would you like me to install Node.js 22? If confirmed:
  • macOS: brew install node@22 (if brew available) or install nvm then nvm install 22
  • Linux: curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs, or nvm
  • After installing Node, re-run bash setup.sh
• If DEPS_OK=false → Read logs/setup.log. Try: delete node_modules and package-lock.json, re-run bash setup.sh. If native module build fails, install build tools (xcode-select --install on macOS, build-essential on Linux), then retry.
• If NATIVE_OK=false → better-sqlite3 failed to load. Install build tools and re-run.
• Record PLATFORM and IS_WSL for later steps.

2. Check Environment

Run npx tsx setup/index.ts --step environment and parse the status block.

• If HAS_QQ_CONFIG=true → note that QQ Bot is configured
• If HAS_WHATSAPP_AUTH=true → note that WhatsApp auth exists (if using WhatsApp)
• If HAS_REGISTERED_GROUPS=true → note existing config, offer to skip or reconfigure
• Record APPLE_CONTAINER and DOCKER values for step 3
• Record ENABLE_QQ and ENABLE_WHATSAPP values for channel setup

3. Container Runtime

3a. Choose runtime

Check the preflight results for APPLE_CONTAINER and DOCKER, and the PLATFORM from step 1.

• PLATFORM=linux → Docker (only option)
• PLATFORM=macos + APPLE_CONTAINER=installed → Use AskUserQuestion: Docker (default, cross-platform) or Apple Container (native macOS)? If Apple Container, run /convert-to-apple-container now, then skip to 3c.
• PLATFORM=macos + APPLE_CONTAINER=not_found → Docker (default)

3a-docker. Install Docker

• DOCKER=running → continue to 3b
• DOCKER=installed_not_running → start Docker: open -a Docker (macOS) or sudo systemctl start docker (Linux). Wait 15s, re-check with docker info.
• DOCKER=not_found → Use AskUserQuestion: Docker is required for running agents. Would you like me to install it? If confirmed:
  • macOS: install via brew install --cask docker, then open -a Docker and wait for it to start. If brew not available, direct to Docker Desktop download at https://docker.com/products/docker-desktop
  • Linux: install with curl -fsSL https://get.docker.com | sh && sudo usermod -aG docker $USER. Note: user may need to log out/in for group membership.

3b. Apple Container check (if needed)

If the chosen runtime is Apple Container, ensure the source code has been converted. Run:

grep -q "CONTAINER_RUNTIME_BIN = 'container'" src/container-runtime.ts && echo "OK" || echo "NEEDS_CONVERSION"

If NEEDS_CONVERSION, run the /convert-to-apple-container skill NOW, before proceeding to 3c.

If the chosen runtime is Docker, no conversion is needed. Continue to 3c.

3c. Pull and test

Run npx tsx setup/index.ts --step container -- --runtime <chosen> and parse the status block.

If PULL_OK=false: Read logs/setup.log tail for the pull error.

• Network issue: check internet connection and retry
• Auth issue: may need docker login if using private registry

If TEST_OK=false but PULL_OK=true: The image pulled but won't run. Check logs — common cause is runtime not fully started. Wait a moment and retry the test.

4. iFlow Authentication (No Script)

If HAS_ENV=true from step 2, read .env and check for IFLOW_API_KEY or IFLOW_OAUTH_TOKEN. If present, confirm with user: keep or reconfigure?

AskUserQuestion: iFlow OAuth token vs API key?

OAuth Token: Tell user to run iflow login in another terminal, copy the token, add IFLOW_OAUTH_TOKEN=<token> to .env. Do NOT collect the token in chat.

API Key: Tell user to add IFLOW_API_KEY=<key> to .env.

5. QQ Bot Configuration

QQ Bot 使用环境变量配置，不需要扫码认证。

AskUserQuestion: 是否配置 QQ Bot 作为默认渠道？

需要的配置项：

• QQ_APP_ID: 机器人的 AppID（从 QQ 开放平台获取）
• QQ_CLIENT_SECRET: 机器人的 ClientSecret（从 QQ 开放平台获取）
• QQ_SANDBOX: 是否使用沙箱模式（可选，默认 true）
• QQ_AUTO_REGISTER: 是否自动注册新对话（可选，默认 true）

告诉用户在 .env 文件中添加：

ENABLE_QQ=true
QQ_APP_ID=your_app_id
QQ_CLIENT_SECRET=your_client_secret
QQ_SANDBOX=true
QQ_AUTO_REGISTER=true

可选：WhatsApp 配置

如果用户需要使用 WhatsApp，在 .env 中设置：

ENABLE_WHATSAPP=true

然后运行 npm run auth 进行 WhatsApp 认证。

6. Configure Trigger and Channel Type

AskUserQuestion: Trigger word? → AskUserQuestion: Main channel type?

默认渠道类型： QQ Bot (推荐)

可选渠道：

• QQ Bot (默认)
• WhatsApp
• DingTalk
• Terminal (调试用)

7. Sync and Select Group (If Group Channel)

QQ Bot: QQ Bot 默认启用 QQ_AUTO_REGISTER，会自动注册新的群聊和私聊。无需手动同步。

WhatsApp (如果使用):

1. npx tsx setup/index.ts --step groups (Bash timeout: 60000ms)
2. BUILD=failed → fix TypeScript, re-run. GROUPS_IN_DB=0 → check logs.
3. npx tsx setup/index.ts --step groups -- --list for pipe-separated JID|name lines.
4. Present candidates as AskUserQuestion (names only, not JIDs).

8. Register Channel

QQ Bot: 如果 QQ_AUTO_REGISTER=true，首次发送消息时会自动注册。

手动注册： Run npx tsx setup/index.ts --step register -- --jid "JID" --name "main" --trigger "@TriggerWord" --folder "main" plus --no-trigger-required if personal/DM/solo, --assistant-name "Name" if not Andy.

9. Mount Allowlist

AskUserQuestion: Agent access to external directories?

No: npx tsx setup/index.ts --step mounts -- --empty Yes: Collect paths/permissions. npx tsx setup/index.ts --step mounts -- --json '{"allowedRoots":[...],"blockedPatterns":[],"nonMainReadOnly":true}'

10. Start Service

If service already running: unload first.

• macOS: launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
• Linux: systemctl --user stop nanoclaw (or systemctl stop nanoclaw if root)

Run npx tsx setup/index.ts --step service and parse the status block.

If FALLBACK=wsl_no_systemd: WSL without systemd detected. Tell user they can either enable systemd in WSL (echo -e "[boot]\nsystemd=true" | sudo tee /etc/wsl.conf then restart WSL) or use the generated start-nanoclaw.sh wrapper.

If DOCKER_GROUP_STALE=true: The user was added to the docker group after their session started — the systemd service can't reach the Docker socket. Ask user to run these two commands:

1. Immediate fix: sudo setfacl -m u:$(whoami):rw /var/run/docker.sock
2. Persistent fix (re-applies after every Docker restart):

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/socket-acl.conf << 'EOF'
[Service]
ExecStartPost=/usr/bin/setfacl -m u:USERNAME:rw /var/run/docker.sock
EOF
sudo systemctl daemon-reload

Replace USERNAME with the actual username (from whoami). Run the two sudo commands separately — the tee heredoc first, then daemon-reload. After user confirms setfacl ran, re-run the service step.

If SERVICE_LOADED=false:

• Read logs/setup.log for the error.
• macOS: check launchctl list | grep nanoclaw. If PID=- and status non-zero, read logs/nanoclaw.error.log.
• Linux: check systemctl --user status nanoclaw.
• Re-run the service step after fixing.

11. Verify

Run npx tsx setup/index.ts --step verify and parse the status block.

If STATUS=failed, fix each:

• SERVICE=stopped → npm run build, then restart: launchctl kickstart -k gui/$(id -u)/com.nanoclaw (macOS) or systemctl --user restart nanoclaw (Linux) or bash start-nanoclaw.sh (WSL nohup)
• SERVICE=not_found → re-run step 10
• CREDENTIALS=missing → re-run step 4
• QQ_CONFIG=not_configured → re-run step 5 (add QQ_APP_ID and QQ_CLIENT_SECRET to .env)
• WHATSAPP_AUTH=not_found → re-run step 5 (if using WhatsApp)
• REGISTERED_GROUPS=0 → re-run steps 7-8 (or send a message to QQ bot if auto-register enabled)
• MOUNT_ALLOWLIST=missing → npx tsx setup/index.ts --step mounts -- --empty

Tell user to test: send a message in their registered chat. Show: tail -f logs/nanoclaw.log

Troubleshooting

Service not starting: Check logs/nanoclaw.error.log. Common: wrong Node path (re-run step 10), missing .env (step 4), missing auth (step 5).

Container agent fails ("iFlow agent process exited with code 1"): Ensure the container runtime is running — open -a Docker (macOS Docker), container system start (Apple Container), or sudo systemctl start docker (Linux). Check container logs in groups/main/logs/container-*.log.

No response to messages: Check trigger pattern. Main channel doesn't need prefix. Check DB: npx tsx setup/index.ts --step verify. Check logs/nanoclaw.log.

QQ Bot not responding: Check QQ_APP_ID and QQ_CLIENT_SECRET are set correctly in .env. Check logs for WebSocket connection errors.

WhatsApp disconnected: npm run auth then rebuild and restart: npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw (macOS) or systemctl --user restart nanoclaw (Linux).

Unload service: macOS: launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist | Linux: systemctl --user stop nanoclaw