fix: clarify WhatsApp owner number prompts

CHANGELOG.md

@@ -55,6 +55,7 @@
 - Onboarding: avoid “token expired” for Codex CLI when expiry is heuristic.
 - Onboarding: QuickStart jumps straight into provider selection with Telegram preselected when unset.
 - Onboarding: QuickStart auto-installs the Gateway daemon with Node (no runtime picker).
+- Onboarding: clarify WhatsApp owner number prompt and label pairing phone number.
 - Daemon runtime: remove Bun from selection options.
 - CLI: restore hidden `gateway-daemon` alias for legacy launchd configs.
 - Onboarding/Configure: add OpenAI API key flow that stores in shared `~/.clawdbot/.env` for launchd; simplify Anthropic token prompt order.

docs/providers/whatsapp.md

@@ -43,6 +43,7 @@ If you want pairing instead of allowlist, set `whatsapp.dmPolicy` to `pairing`.
 
 ### Personal number (fallback)
 Quick fallback: run Clawdbot on **your own number**. Message yourself (WhatsApp “Message yourself”) for testing so you don’t spam contacts. Expect to read verification codes on your main phone during setup and experiments. **Must enable self-chat mode.**
+When the wizard asks for your personal WhatsApp number, enter the phone you will message from (the owner/sender), not the assistant number.
 
 **Sample config (personal number, self-chat):**
 ```json

docs/start/wizard.md

@@ -34,7 +34,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
 - Gateway port **18789**
 - Gateway auth **Off** (loopback only)
 - Tailscale exposure **Off**
-- Telegram + WhatsApp DMs default to **allowlist** (you’ll be prompted for a number)
+- Telegram + WhatsApp DMs default to **allowlist** (you’ll be prompted for your phone number)
 
 **Advanced** exposes every step (mode, workspace, gateway, providers, daemon, skills).
 

src/commands/onboard-providers.ts

@@ -541,8 +541,12 @@ async function promptWhatsAppAllowFrom(
   const existingResponsePrefix = cfg.messages?.responsePrefix;
 
   if (options?.forceAllowlist) {
+    await prompter.note(
+      "We need the sender/owner number so Clawdbot can allowlist you.",
+      "WhatsApp number",
+    );
     const entry = await prompter.text({
-      message: "Your WhatsApp number (E.164)",
+      message: "Your personal WhatsApp number (the phone you will message from)",
       placeholder: "+15555550123",
       initialValue: existingAllowFrom[0],
       validate: (value) => {
@@ -604,8 +608,12 @@ async function promptWhatsAppAllowFrom(
   })) as "personal" | "separate";
 
   if (phoneMode === "personal") {
+    await prompter.note(
+      "We need the sender/owner number so Clawdbot can allowlist you.",
+      "WhatsApp number",
+    );
     const entry = await prompter.text({
-      message: "Your WhatsApp number (E.164)",
+      message: "Your personal WhatsApp number (the phone you will message from)",
       placeholder: "+15555550123",
       initialValue: existingAllowFrom[0],
       validate: (value) => {

src/pairing/pairing-messages.test.ts

@@ -26,7 +26,7 @@ describe("buildPairingReply", () => {
     },
     {
       provider: "whatsapp",
-      idLine: "Your WhatsApp sender id: +15550003333",
+      idLine: "Your WhatsApp phone number: +15550003333",
       code: "MNO345",
     },
   ] as const;

src/web/inbound.ts

@@ -313,7 +313,7 @@ export async function monitorWebInbox(options: {
                   await sock.sendMessage(remoteJid, {
                     text: buildPairingReply({
                       provider: "whatsapp",
-                      idLine: `Your WhatsApp sender id: ${candidate}`,
+                      idLine: `Your WhatsApp phone number: ${candidate}`,
                       code,
                     }),
                   });

src/web/monitor-inbox.test.ts

@@ -671,7 +671,7 @@ describe("web monitor inbox", () => {
     expect(sock.readMessages).not.toHaveBeenCalled();
     expect(sock.sendMessage).toHaveBeenCalledTimes(1);
     expect(sock.sendMessage).toHaveBeenCalledWith("999@s.whatsapp.net", {
-      text: expect.stringContaining("Your WhatsApp sender id: +999"),
+      text: expect.stringContaining("Your WhatsApp phone number: +999"),
     });
     expect(sock.sendMessage).toHaveBeenCalledWith("999@s.whatsapp.net", {
       text: expect.stringContaining("Pairing code: PAIRCODE"),
@@ -1125,7 +1125,7 @@ describe("web monitor inbox", () => {
     expect(onMessage).not.toHaveBeenCalled();
     expect(sock.sendMessage).toHaveBeenCalledTimes(1);
     expect(sock.sendMessage).toHaveBeenCalledWith("999@s.whatsapp.net", {
-      text: expect.stringContaining("Your WhatsApp sender id: +999"),
+      text: expect.stringContaining("Your WhatsApp phone number: +999"),
     });
     expect(sock.sendMessage).toHaveBeenCalledWith("999@s.whatsapp.net", {
       text: expect.stringContaining("Pairing code: PAIRCODE"),
@@ -1281,7 +1281,7 @@ describe("web monitor inbox", () => {
     expect(onMessage).not.toHaveBeenCalled();
     expect(upsertPairingRequestMock).toHaveBeenCalledTimes(1);
     expect(sock.sendMessage).toHaveBeenCalledWith("999@s.whatsapp.net", {
-      text: expect.stringContaining("Your WhatsApp sender id: +999"),
+      text: expect.stringContaining("Your WhatsApp phone number: +999"),
     });
     expect(sock.sendMessage).toHaveBeenCalledWith("999@s.whatsapp.net", {
       text: expect.stringContaining("Pairing code: PAIRCODE"),