Walk the operator through wiring the first NanoClaw agent to a DM channel — resolve the operator's channel identity, select or create the agent, and trigger a welcome DM via the normal delivery path.
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add nanocoai/nanoclaw --skill init-first-agent -a cursor -y
Walk the operator through wiring the first NanoClaw agent to a DM channel — resolve the operator's channel identity, select or create the agent, and trigger a welcome DM via the normal delivery path. Use after channel credentials are configured and the service is running.
Walk the operator through wiring the first NanoClaw agent to a DM channel — resolve the operator's channel identity, select or create the agent, and trigger a welcome DM via the normal delivery path. Use after channel credentials are configured and the service is running.
Wire the first NanoClaw agent to a channel and verify end-to-end delivery by having the agent DM the operator. Everything the skill does is idempotent — rerunning is safe.
launchctl list | grep "$(. setup/lib/install-slug.sh && launchd_label)" (macOS) or systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)" (Linux). If stopped, tell the user to run /setup first./add-<channel> skill has run, credentials are in .env, and the adapter is uncommented in src/channels/index.ts.logs/nanoclaw.log — look for a recent channel setup / adapter connected line for the target channel.Read src/channels/index.ts to find enabled channels (uncommented imports). Cross-check .env for the relevant credentials.
AskUserQuestion: "Which channel should host the welcome DM?" with one option per enabled channel (Discord, Slack, Telegram, WhatsApp, Webex, Teams, Google Chat, Matrix, iMessage, Resend, …).
Record the choice as CHANNEL (lowercase, e.g. discord).
Read the channel's own skill for its ## Channel Info > how-to-find-id section (e.g. .claude/skills/add-discord/SKILL.md, .claude/skills/add-telegram/SKILL.md). Show those instructions to the user in plain text.
Then ask in plain text (NOT AskUserQuestion — these are free-form):
USER_HANDLE.dm-with-<normalized>) and as the welcome-message addressee. Record as DISPLAY_NAME.DISPLAY_NAME. Record as AGENT_NAME.This depends on whether the channel supports cold DM via adapter.openDM.
Channels without cold DM (direct-addressable): telegram, whatsapp, imessage, matrix, resend. The user handle doubles as the DM chat id. Set:
PLATFORM_ID=${CHANNEL}:${USER_HANDLE}
Skip to step 4.
Channels with cold DM (resolution-required): discord, slack, teams, webex, gchat. The bot can DM cold at runtime via Chat SDK, but this skill runs standalone — it can't call the adapter. Two resolutions:
Tell the user:
Send any single message to the bot as a DM from your account on
${CHANNEL}. The router will record the DM as a messaging group. Replydonehere when you've sent the message.
Wait for the user's confirmation. Then look up the most recent DM messaging groups:
pnpm exec tsx scripts/q.ts data/v2.db "SELECT id, platform_id, name, created_at FROM messaging_groups WHERE channel_type='${CHANNEL}' AND is_group=0 ORDER BY created_at DESC LIMIT 5"
Show the top rows to the user and confirm which platform_id is theirs (usually the most recent). Record as PLATFORM_ID. If none appeared, check logs/nanoclaw.log for unknown_sender drops — the adapter might be rejecting inbound due to connection or permission issues.
For Telegram only, there's an existing pair-code primitive. When you run this tool, take the output and extract the pairing code. Then show it to the user in plain text and ask the user to send the code in the Telegram chat to complete the pairing.
npx tsx setup/index.ts --step pair-telegram -- --intent new-agent:dm-with-<folder>
Parse the PAIR_TELEGRAM_ISSUED status block for CODE and follow the REMINDER_TO_ASSISTANT line in that block. Then wait for the PAIR_TELEGRAM block — read PLATFORM_ID and PAIRED_USER_ID from it. telegram.ts's interceptor has already upserted the user and granted owner if none existed yet. Use PLATFORM_ID and PAIRED_USER_ID directly in step 5.
List the existing agent groups and their wirings through the admin CLI:
ncl groups list --json
ncl wirings list --json
If setup already installed a template, it appears in the groups result even when it has no wiring. Show the user each group's name, folder, and id, and note which groups already appear as agent_group_id values in the wirings result.
AGENT_GROUP_ID; the init script will create one.id as AGENT_GROUP_ID. Do not infer it from the display name or folder.When creating a new agent, first pick the provider. Read src/providers/index.ts and collect the installed providers from its import './<name>.js'; lines — claude is always available as the built-in default. If a non-default provider is installed (e.g. codex), ask the user which one this agent should run on; if only claude is available, skip the question. An existing group keeps the provider and template configuration it already has.
npx tsx scripts/init-first-agent.ts \
--channel "${CHANNEL}" \
--user-id "${CHANNEL}:${USER_HANDLE}" \
--platform-id "${PLATFORM_ID}" \
--display-name "${DISPLAY_NAME}" \
--agent-name "${AGENT_NAME}"
When an existing group was selected, append its exact id:
--agent-group-id "${AGENT_GROUP_ID}"
When the channel runs a named adapter instance (e.g. a second Telegram bot registered as telegram-mega), append --instance "${INSTANCE}" with the registry key (never the short name) so the DM row, the wiring and the welcome all target that bot; omitted = the channel's default instance.
The new group is created on the instance default provider (DEFAULT_AGENT_PROVIDER in .env, or claude when unset). To put it on a different provider, switch after creation with ncl groups config update --id <group-id> --provider <name>. Add --welcome "System instruction: ..." to override the default welcome prompt.
The script:
users row and grants owner role if no owner exists.agent_groups row, or creates one and calls initGroupFilesystem at groups/dm-with-<name>/.messaging_groups row.messaging_group_agents (which auto-creates the companion agent_destinations row).data/cli.sock), targeting the DM messaging group. The service routes it into the DM session, which wakes the container synchronously. If the socket isn't reachable (service down), falls back to a direct inbound.db write that the next host sweep picks up.Show the script's output to the user.
The welcome DM is queued synchronously; the only wait is container cold-start (~60s on first launch) before the agent processes the message and the reply flows through outbound.db to the channel.
Do not tail the log or poll in a sleep loop. Ask the user in plain text:
The welcome DM should arrive shortly. Let me know when you've received it (or if it doesn't arrive within two minutes).
Wait for the user's reply. If they confirm receipt, the skill is done.
If they say it didn't arrive, then diagnose using the DB directly (no waiting loops required — the message either delivered or it didn't):
pnpm exec tsx scripts/q.ts data/v2-sessions/<agent-group-id>/<session-id>/outbound.db "SELECT id, status, created_at FROM messages_out ORDER BY created_at DESC LIMIT 5" — check for stuck pending rows. Replace <agent-group-id> and <session-id> with the values from the script's output.grep -E 'Unauthorized channel destination|container.*exited|error' logs/nanoclaw.log | tail -20 — look for ACL rejections or container crashes.ls data/v2-sessions/<agent-group-id>/*/outbound.db — confirm the session exists."Missing required args" — the script wants --channel, --user-id, --platform-id, --display-name at minimum. Re-check the command you assembled.
No messaging_groups row appears after the user DMs (step 3a) — auto-created rows are stamped with the channel adapter's declared unknown_sender_policy (two-level model: adapter declaration → per-row override; strict only when the adapter has no declaration). Under strict the router silently drops messages from unknown senders but still creates the messaging_groups row; under request_approval an approval card goes to an admin instead. If the row is missing entirely, the adapter isn't receiving the inbound message. Check logs/nanoclaw.log for adapter errors (auth, gateway disconnect, rate limit).
Owner already exists — hasAnyOwner() returned true, so the grant is skipped silently. That's fine; the script still creates the agent and wiring. Reassigning ownership needs a separate flow (not this skill).
Wrong person got the welcome DM — the --platform-id you passed is someone else's DM channel. Rerun with the correct one; the script is idempotent on user/messaging-group/agent-group but writes a new session welcome each run.
Agent group name collision — use step 4 to select the intended group by id. If creating a new agent and dm-with-<display-name> already exists, the script reuses it; pass a different --display-name to get a distinct folder.