diff --git a/README.md b/README.md
index 8850e952..8deec263 100644
--- a/README.md
+++ b/README.md
@@ -47,6 +47,7 @@ powershell -ExecutionPolicy Bypass -File .\scripts\start_all.ps1 -Background
 
 - **8787 端口占用 / 重启不生效**：`powershell -ExecutionPolicy Bypass -File .\scripts\stop_gateway.ps1 -Force` 后再启动。
 - **更细的从零教程**：`docs/RUNBOOK.md` →「开源快速安装（从零到跑起来）」。
+- **WhatsApp 安装与启停**：见 `docs/RUNBOOK.md` →「4.2 WhatsApp（实验接入）」。
 - **更换品牌 Logo（外部优先）**：见 `docs/BRANDING.md`（将资源放到 `_local/branding/`）。
 
 ### 可选：运维专家（network_ops）与 netx
@@ -109,6 +110,7 @@ Notes:
 - Admin supports channel dispatch controls for Weixin/WhatsApp (bind specialist / comprehensive), with default `generalist`.
 
 Full runbook (recommended): see `docs/RUNBOOK.md` → “开源快速安装（从零到跑起来）”.
+WhatsApp install/start guide: see `docs/RUNBOOK.md` → “4.2 WhatsApp（实验接入）”.
 
 Minimal onboarding guide: `docs/OPEN_SOURCE_QUICKSTART.md`.
 Branding guide (external-first assets under `_local/branding`): `docs/BRANDING.md`.
diff --git a/runtime/operations/scripts/whatsapp_login.ps1 b/runtime/operations/scripts/whatsapp_login.ps1
index 21ada231..662d38c3 100644
--- a/runtime/operations/scripts/whatsapp_login.ps1
+++ b/runtime/operations/scripts/whatsapp_login.ps1
@@ -1,5 +1,6 @@
 param(
-  [string]$ChannelId = "whatsapp"
+  [string]$ChannelId = "whatsapp",
+  [switch]$VerboseRunner
 )
 
 $ErrorActionPreference = "Stop"
@@ -25,8 +26,17 @@ if (-not (Test-Path (Join-Path $sidecarRoot "baileys_runner.ts"))) {
 Push-Location $sidecarRoot
 try {
   $env:OCLAW_STATE_DIR = $stateDir
-  $args = @("/c", "set OCLAW_STATE_DIR=$stateDir&& npx.cmd -y tsx baileys_runner.ts --login")
-  Start-Process -FilePath "cmd.exe" -ArgumentList $args -WorkingDirectory $sidecarRoot -Wait
+  Write-Host "[info] whatsapp login started (foreground)."
+  Write-Host "[info] If QR appears, scan it in WhatsApp -> Linked devices."
+  $runnerArgs = @("-y", "tsx", "baileys_runner.ts", "--login")
+  if ($VerboseRunner) {
+    $runnerArgs += "--verbose"
+  }
+  & npx.cmd @runnerArgs
+  if ($LASTEXITCODE -ne 0) {
+    throw "whatsapp login runner exited with code $LASTEXITCODE"
+  }
+  Write-Host "[ok] whatsapp login finished"
 } finally {
   Pop-Location
 }