2026 OpenClaw Playwright skill-browser on Headless Mac VPS: Same-Account Chromium Install, Parallel Limits, and Error Triage Runbook (Decision Matrix and FAQ)

1. Pain patterns: missing Chromium, OOM, and modal blocking

skill-browser extends OpenClaw failure modes into browser child processes. The gateway can show online while the first navigate still fails—a pattern that wastes on-call time when channel health looks green but tool calls time out silently.

1. Chromium not installed under the same account: CLI and launchd users differ, cache paths split, and logs report missing executables despite a manual SSH install.
2. Exit 137 from parallel contexts: Too many parallel browser contexts OOM-kill Chromium; the gateway surfaces only tool timeout, not exit code.
3. Split HOME directories: SSH smoke passes while launchd jobs fail on profile locks or non-writable config paths.
4. Modal blocking without blockedByDialog: Cookie banners and SSO overlays leave evaluate hanging; agents return empty snapshots.

2. Decision matrix: headless Mac VPS vs local Mac vs Docker browser

Local Mac with a display remains excellent for selector debugging and visual confirmation. Production agents that must share port eighteen thousand seven hundred eighty-nine with IM channels and survive reboots belong on a headless Mac VPS with launchd alignment. Docker browser stacks can work for short batch jobs; see the twenty-four-seven Compose runbook for health checks and rollback patterns.

3. Mac VPS preflight: Node 22, 18789, and same-account HOME

• Runtime: Node.js twenty-two or newer; run openclaw doctor and openclaw --version and resolve half-installed warnings before adding skills.
• Gateway listener: lsof -i :18789 or openclaw gateway status must show listening; if not, follow the gateway install runbook including bind and auth checks.
• Account alignment: Record launchd plist UserName and HOME; Chromium install and skill configuration must use that same user—not root, not your personal laptop account copied verbatim.
• Resources and audit: Plan at least eight GB RAM and twenty GB disk for Chromium cache growth; complete third-party skill audit before pulling from ClawHub.

4. skill-browser parameter table: headless, parallel, and timeout

skill-browser drives Playwright headless Chromium. Treat the table below as a review skeleton; after any OpenClaw upgrade, rerun openclaw doctor and diff your skill config against release notes.

5. Seven-step runbook: account → install → Chromium → probe → smoke → launchd

1. Align account and HOME: Verify launchd plist UserName; SSH as that user and confirm echo $HOME matches plist EnvironmentVariables.
2. Version pin and doctor: Back up openclaw.json, run openclaw doctor; for upgrades follow the May release-train runbook.
3. Install skill-browser: After audit, openclaw skills install skill-browser and confirm the skill appears in tools.profile.
4. Install Chromium: Same account: npx puppeteer browsers install chromium; note the cache path doctor prints.
5. Write parameters: Set headless, parallel contexts, timeout-ms, and blockedByDialog for your target sites.
6. Probe and smoke: Confirm eighteen thousand seven hundred eighty-nine listening; run a fixed-URL snapshot and record toolCallId in JSONL.
7. launchd acceptance: Load plist via launchctl, reboot or bootout/bootstrap cycle, rerun smoke without SSH intervention.

6. Three citeable KPIs: cold start, RSS, snapshot success rate

• Chromium cold start: First launch on Mac cloud should stay under eight seconds; above fifteen seconds, inspect disk IO and antivirus hooks before raising parallel contexts.
• Memory footprint: After single-context smoke, combined Gateway and Chromium RSS should stay below roughly sixty percent of available RAM on your SKU.
• Snapshot success rate: Twenty consecutive runs against a fixed URL should succeed at least ninety-five percent; below ninety percent, adjust modal policy and timeout before blaming selectors.

7. Error triage table and layered troubleshooting

When browser tool calls fail, walk layers in order: Chromium binary present → same-account HOME → headless and parallel settings → modals and timeout. Correlate each layer with JSONL toolCallId so IM-side reports map to gateway evidence.

8. Business examples: forms, monitoring, and IM integration

Support form autofill: Agent receives a Telegram ticket, skill-browser opens an internal form, fills fields, and returns a screenshot; SSO modals use fail-fast. Competitor monitoring: Cron fixed-selector snapshots to JSONL; keep parallel at one. Browse-then-reply: User asks via bot; agent navigates and summarizes login-gated pages.

9. FAQ

Question: Can skill-browser coexist with Ollama or multiple providers? Yes; browser subprocesses are independent. Set concurrency caps in tools.profile and watch RSS in gateway status --deep when LLM and browser peaks overlap.

Question: Must I re-verify after upgrading to v2026.5.x? Run doctor, reinstall Chromium under the launchd user, and execute minimal snapshot smoke; see the release-train runbook.

Question: Mac cloud vs Linux VPS or Docker? Choose Mac cloud for seven-day twenty-four-hour Gateway co-location; Docker suits short batch jobs but OOM and permission triage take longer.

10. Conclusion

Production-ready skill-browser means you can reconstruct skill install → same-account Chromium → port eighteen thousand seven hundred eighty-nine snapshot into one evidence chain during an incident. Laptops and WSL2 rarely sustain seven-day twenty-four-hour browser plus IM load; Linux Docker browser stacks often fight /dev/shm limits and headless detection. To run browser skills parallel with IM channels, rent a VPSMAC Apple Silicon Mac cloud node and keep Gateway, Chromium cache, and launchd in a single runbook; Docker remains valid for short batch work but does not replace the headless Mac production stack. See the Docker twenty-four-seven guide and skill audit articles for adjacent hardening.