Add WhatsApp pairing code support as alternative to QR scanning

buggy324234 · claude · buggy324234 · commit cd70481b184f · 2026-05-18T15:57:05.000+09:00
Adds --phone flag to `openclaw channels login` that uses Baileys'
requestPairingCode() to generate an 8-digit code instead of a QR.
Users enter the code in WhatsApp &gt; Linked Devices &gt; Link with phone number.

This enables WhatsApp linking without a second device for QR scanning,
which is critical for automated/headless deployment flows.

Usage:
  openclaw channels login --channel whatsapp --phone +353830836798

Changes:
- session.ts: Accept phoneNumber option, call requestPairingCode() when
  QR is generated and phone number is provided, fall back to QR on error
- login.ts: Add phoneNumber parameter to loginWeb(), normalize phone format
- channel.ts: Pass phoneNumber from auth login callback to loginWeb()
- channels-cli.ts: Add --phone option to `channels login` command
- channel-auth.ts: Add phoneNumber to ChannelAuthOptions, pass through
- types.adapters.ts: Add phoneNumber to ChannelAuthAdapter login params

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/extensions/whatsapp/src/channel.ts b/extensions/whatsapp/src/channel.ts
@@ -167,14 +167,14 @@ export const whatsappPlugin: ChannelPlugin<ResolvedWhatsAppAccount> =
       },
       approvalCapability: whatsappApprovalAuth,
       auth: {
-        login: async ({ cfg, accountId, runtime, verbose }) => {
+        login: async ({ cfg, accountId, runtime, verbose, phoneNumber }) => {
           const resolvedAccountId =
             accountId?.trim() ||
             whatsappPlugin.config.defaultAccountId?.(cfg) ||
             DEFAULT_ACCOUNT_ID;
           await (
             await loadWhatsAppChannelRuntime()
-          ).loginWeb(Boolean(verbose), undefined, runtime, resolvedAccountId);
+          ).loginWeb(Boolean(verbose), undefined, runtime, resolvedAccountId, phoneNumber);
         },
       },
       lifecycle: {
diff --git a/extensions/whatsapp/src/login.ts b/extensions/whatsapp/src/login.ts
@@ -15,6 +15,7 @@ export async function loginWeb(
   waitForConnection?: typeof waitForWaConnection,
   runtime: RuntimeEnv = defaultRuntime,
   accountId?: string,
+  phoneNumber?: string,
 ) {
   const cfg = getRuntimeConfig();
   const account = resolveWhatsAppAccount({ cfg, accountId });
@@ -30,10 +31,19 @@ export async function loginWeb(
         runtime.error(`failed rendering WhatsApp QR: ${String(err)}`);
       });
   };
+  const onPairingCode = (code: string) => {
+    runtime.log(
+      `Enter this pairing code in WhatsApp > Linked Devices > Link with phone number:\n\n  ${code}\n`,
+    );
+  };
+  // Normalize phone number: remove + prefix and non-digit characters
+  const normalizedPhone = phoneNumber?.replace(/[^0-9]/g, "") || undefined;
   let sock = await createWaSocket(false, verbose, {
     authDir: account.authDir,
     ...socketTiming,
     onQr,
+    phoneNumber: normalizedPhone,
+    onPairingCode,
   });
   logInfo("Waiting for WhatsApp connection...", runtime);
   try {
diff --git a/extensions/whatsapp/src/session.ts b/extensions/whatsapp/src/session.ts
@@ -134,6 +134,8 @@ export async function createWaSocket(
   opts: {
     authDir?: string;
     onQr?: (qr: string) => void;
+    phoneNumber?: string;
+    onPairingCode?: (code: string) => void;
   } & WhatsAppSocketTimingOptions = {},
 ): Promise<ReturnType<typeof makeWASocket>> {
   const baseLogger = getChildLogger(
@@ -184,11 +186,35 @@ export async function createWaSocket(
     fetchAgent: fetchAgent as Agent | undefined,
   });
 
+  let pairingCodeRequested = false;
   sock.ev.on("creds.update", () => enqueueSaveCreds(authDir, saveCreds, sessionLogger));
   sock.ev.on("connection.update", async (update: Partial<import("baileys").ConnectionState>) => {
     try {
       const { connection, lastDisconnect, qr } = update;
-      if (qr) {
+      if (qr && opts.phoneNumber && !pairingCodeRequested && !state.creds.registered) {
+        // Use pairing code instead of QR when phone number is provided
+        pairingCodeRequested = true;
+        try {
+          const code = await sock.requestPairingCode(opts.phoneNumber);
+          sessionLogger.info({ phoneNumber: opts.phoneNumber }, `Pairing code generated: ${code}`);
+          opts.onPairingCode?.(code);
+          if (printQr) {
+            console.log(
+              `Enter this pairing code in WhatsApp > Linked Devices > Link with phone number:\n\n  ${code}\n`,
+            );
+          }
+        } catch (err) {
+          sessionLogger.error({ error: String(err) }, "Failed to request pairing code, falling back to QR");
+          // Fall back to QR
+          opts.onQr?.(qr);
+          if (printQr) {
+            console.log("Open the WhatsApp app, go to Linked Devices, then scan this QR:");
+            void printTerminalQr(qr).catch((qrErr) => {
+              sessionLogger.warn({ error: String(qrErr) }, "failed rendering WhatsApp QR");
+            });
+          }
+        }
+      } else if (qr) {
         opts.onQr?.(qr);
         if (printQr) {
           console.log("Open the WhatsApp app, go to Linked Devices, then scan this QR:");
diff --git a/src/channels/plugins/types.adapters.ts b/src/channels/plugins/types.adapters.ts
@@ -365,6 +365,7 @@ export type ChannelAuthAdapter = {
     runtime: RuntimeEnv;
     verbose?: boolean;
     channelInput?: string | null;
+    phoneNumber?: string;
   }) => Promise<void>;
 };
 
diff --git a/src/cli/channel-auth.ts b/src/cli/channel-auth.ts
@@ -23,6 +23,7 @@ type ChannelAuthOptions = {
   channel?: string;
   account?: string;
   verbose?: boolean;
+  phoneNumber?: string;
 };
 
 type ChannelPlugin = NonNullable<ReturnType<typeof getChannelPlugin>>;
@@ -249,6 +250,7 @@ export async function runChannelLogin(
     runtime,
     verbose: Boolean(opts.verbose),
     channelInput,
+    phoneNumber: opts.phoneNumber,
   });
   await reconcileGatewayRuntimeAfterLocalLogin({
     cfg,
diff --git a/src/cli/channels-cli.ts b/src/cli/channels-cli.ts
@@ -256,6 +256,7 @@ export async function registerChannelsCli(
     .description("Link a channel account (if supported)")
     .option("--channel <channel>", "Channel alias (auto when only one is configured)")
     .option("--account <id>", "Account id (accountId)")
+    .option("--phone <number>", "Phone number for pairing code login (WhatsApp only, e.g. +1234567890)")
     .option("--verbose", "Verbose connection logs", false)
     .action(async (opts) => {
       await runChannelsCommandWithDanger(async () => {
@@ -264,6 +265,7 @@ export async function registerChannelsCli(
             channel: opts.channel as string | undefined,
             account: opts.account as string | undefined,
             verbose: Boolean(opts.verbose),
+            phoneNumber: opts.phone as string | undefined,
           },
           defaultRuntime,
         );
