collective-memory-repo/shared/long-term/projects/mac7-browser-worker-runbook.md

mac-7 browser worker runbook

Date: 2026-03-18 Status: active

Purpose

Provide a single operational reference for the mac-7 = eyes browser worker setup used for unattended Chrome automation and remote CDP access from the tailnet.

Role in cluster

• mac-5 = brain: control plane / orchestration / local human-in-the-loop takeover
• mac-7 = eyes: browser automation worker / verification / remote CDP host

Active architecture

Local automation Chrome on mac-7

• Browser: Google Chrome
• Executable:
  • /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Dedicated automation profile dir:
  • /Users/lingyuzeng/.openclaw/browser/mac7-automation-profile
• Local CDP listener:
  • 127.0.0.1:9333
• Validation:
  • http://127.0.0.1:9333/json/version

Tailnet-facing CDP proxy

• Tailnet IP:
  • 100.64.0.23
• Stable remote CDP endpoint:
  • http://100.64.0.23:9223
• Forwarding:
  • 100.64.0.23:9223 -> 127.0.0.1:9333
• Validation:
  • http://100.64.0.23:9223/json/version

Durable components

LaunchAgents

1) Chrome automation launcher

• plist:
  • /Users/lingyuzeng/Library/LaunchAgents/com.lingyuzeng.chrome-cdp-mac7.plist
• current behavior:
  • runs /bin/zsh /Users/lingyuzeng/.openclaw/bin/start_chrome_cdp_mac7.sh
  • RunAtLoad = true
  • no KeepAlive

2) Tailnet proxy launcher

• plist:
  • /Users/lingyuzeng/Library/LaunchAgents/com.lingyuzeng.chrome-cdp-tailnet-proxy-mac7.plist
• current behavior:
  • runs /usr/local/bin/python3 /Users/lingyuzeng/.openclaw/bin/chrome_cdp_tailnet_proxy.py
  • RunAtLoad = true
  • KeepAlive = true

Scripts

1) Chrome startup wrapper

• path:
  • /Users/lingyuzeng/.openclaw/bin/start_chrome_cdp_mac7.sh
• responsibility:
  • check whether 127.0.0.1:9333 is already listening
  • if yes, exit without launching a second Chrome instance
  • if no, launch Chrome once with the dedicated automation profile and CDP flags

2) Tailnet proxy script

• path:
  • /Users/lingyuzeng/.openclaw/bin/chrome_cdp_tailnet_proxy.py
• responsibility:
  • bind 100.64.0.23:9223
  • forward raw TCP traffic to 127.0.0.1:9333

Verification commands

On mac-7

Check listeners:

lsof -nP -iTCP:9333 -sTCP:LISTEN
lsof -nP -iTCP:9223 -sTCP:LISTEN

Check local CDP:

curl http://127.0.0.1:9333/json/version

Check tailnet CDP:

curl http://100.64.0.23:9223/json/version

Check LaunchAgent state:

launchctl print gui/$(id -u)/com.lingyuzeng.chrome-cdp-mac7
launchctl print gui/$(id -u)/com.lingyuzeng.chrome-cdp-tailnet-proxy-mac7

From mac-5 / control plane

OpenClaw profile used for remote control:

• browser profile: remote-mac7
• cdpUrl: http://100.64.0.23:9223

Useful checks:

openclaw browser --browser-profile remote-mac7 status
openclaw browser --browser-profile remote-mac7 tabs
openclaw browser --browser-profile remote-mac7 snapshot

Known incident and fix

Incident: repeated blank tabs

Observed on 2026-03-18:

• many about:blank tabs kept appearing in the automation Chrome profile
• remote CDP profile on mac-5 showed the tab count growing continuously

Root cause

The original com.lingyuzeng.chrome-cdp-mac7 LaunchAgent was incorrect:

• it directly executed Chrome
• it used KeepAlive = true
• it included about:blank in ProgramArguments

On macOS, Chrome reopened into the existing browser session, printed 正在现有的浏览器会话中打开。, exited with code 0, and launchd immediately ran it again. That loop injected endless new blank tabs into the same automation session.

Correct pattern

Use a wrapper script that checks whether the CDP port is already active before launching Chrome. Do not restore the old pattern of:

• direct Chrome exec from launchd
• KeepAlive = true
• about:blank in LaunchAgent arguments

Logs

Chrome automation logs

• /Users/lingyuzeng/Library/Logs/chrome-cdp-mac7.stdout.log
• /Users/lingyuzeng/Library/Logs/chrome-cdp-mac7.stderr.log

Tailnet proxy logs

• /Users/lingyuzeng/Library/Logs/chrome-cdp-tailnet-proxy-mac7.stdout.log
• /Users/lingyuzeng/Library/Logs/chrome-cdp-tailnet-proxy-mac7.stderr.log

Operational rules

• Treat 127.0.0.1:9333 as the stable local automation endpoint on mac-7.
• Treat 100.64.0.23:9223 as the stable tailnet-facing remote CDP endpoint.
• Use mac-5 user / existing-session for local signed-in browser takeover.
• Use mac-7 browser worker for unattended automation and verification.
• If blank tabs start multiplying again, inspect the Chrome LaunchAgent first before blaming the OpenClaw remote profile.