From 4e1d0707ba60a3465f6386f6e95f054f739c8666 Mon Sep 17 00:00:00 2001 From: hotwa Date: Wed, 18 Mar 2026 15:14:08 +0800 Subject: [PATCH] Add mac-7 browser worker runbook --- daily/2026-03-18.md | 3 + .../projects/mac7-browser-worker-runbook.md | 173 ++++++++++++++++++ 2 files changed, 176 insertions(+) create mode 100644 shared/long-term/projects/mac7-browser-worker-runbook.md diff --git a/daily/2026-03-18.md b/daily/2026-03-18.md index c60842a..ceac830 100644 --- a/daily/2026-03-18.md +++ b/daily/2026-03-18.md @@ -131,3 +131,6 @@ - 已清空 mac-7 上相关历史日志： - `~/Library/Logs/chrome-cdp-mac7.stdout.log` - `~/Library/Logs/chrome-cdp-mac7.stderr.log` +- 已新增长期 runbook： + - `shared/long-term/projects/mac7-browser-worker-runbook.md` + - 用于集中记录 mac-7 browser worker 的 LaunchAgent、脚本、端口、验证命令、事故根因与排障入口 diff --git a/shared/long-term/projects/mac7-browser-worker-runbook.md b/shared/long-term/projects/mac7-browser-worker-runbook.md new file mode 100644 index 0000000..714babf --- /dev/null +++ b/shared/long-term/projects/mac7-browser-worker-runbook.md @@ -0,0 +1,173 @@ +# 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: + +```bash +lsof -nP -iTCP:9333 -sTCP:LISTEN +lsof -nP -iTCP:9223 -sTCP:LISTEN +``` + +Check local CDP: + +```bash +curl http://127.0.0.1:9333/json/version +``` + +Check tailnet CDP: + +```bash +curl http://100.64.0.23:9223/json/version +``` + +Check LaunchAgent state: + +```bash +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: + +```bash +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.