# 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.