Add mac-7 browser worker runbook

2026-03-18 15:14:08 +08:00
parent afa9ebde67
commit 4e1d0707ba
2 changed files with 176 additions and 0 deletions
--- 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、脚本、端口、验证命令、事故根因与排障入口
--- a/shared/long-term/projects/mac7-browser-worker-runbook.md
+++ 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.