Wire First NanoClaw Agent

5. Run the init script

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:

1. Upserts the users row and grants owner role if no owner exists.
2. Uses the selected agent_groups row, or creates one and calls initGroupFilesystem at groups/dm-with-<name>/.
3. Reuses or creates the DM messaging_groups row.
4. Wires them via messaging_group_agents (which auto-creates the companion agent_destinations row).
5. Hands the welcome message to the running service via its CLI socket (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.

6. Verify

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.

Troubleshooting

"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.