155 lines
4.1 KiB
Markdown
155 lines
4.1 KiB
Markdown
# agent-browser-stealth
|
|
|
|
Stealth-focused fork of `agent-browser` for anti-bot evasion in production automation.
|
|
|
|
This fork keeps core browser automation capabilities in sync with upstream `agent-browser`, and focuses its own changes on stealth and anti-detection behavior.
|
|
|
|
## Positioning
|
|
|
|
- Core commands and workflows: aligned with upstream `agent-browser`
|
|
- Fork value: stronger anti-bot defaults and operational policies
|
|
- Default mindset: no extra stealth toggle, stealth is always on
|
|
|
|
## Installation
|
|
|
|
### Global (recommended)
|
|
|
|
```bash
|
|
npm install -g agent-browser-stealth
|
|
agent-browser install
|
|
```
|
|
|
|
### Quick try with npx
|
|
|
|
```bash
|
|
npx agent-browser-stealth install
|
|
npx agent-browser-stealth open example.com
|
|
```
|
|
|
|
### From source
|
|
|
|
```bash
|
|
git clone https://github.com/leeguooooo/agent-browser
|
|
cd agent-browser
|
|
pnpm install
|
|
pnpm build
|
|
pnpm build:native
|
|
pnpm link --global
|
|
agent-browser install
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
agent-browser open https://example.com
|
|
agent-browser snapshot -i
|
|
agent-browser click @e2
|
|
agent-browser fill @e3 "test@example.com"
|
|
agent-browser screenshot page.png
|
|
```
|
|
|
|
## Anti-Bot Measures
|
|
|
|
Stealth is always enabled. Legacy `launch.stealth` is accepted only for compatibility and ignored.
|
|
|
|
### 1) Fingerprint hardening
|
|
|
|
- Hides automation indicators such as `navigator.webdriver`
|
|
- Adds Chromium launch args to reduce automation fingerprints
|
|
- Rewrites headless UA markers (`HeadlessChrome`)
|
|
- Patches high-signal surfaces such as:
|
|
- `navigator.plugins` / `navigator.mimeTypes`
|
|
- `window.chrome.runtime`
|
|
- WebGL vendor/renderer exposure
|
|
- permissions/language/media/device related probes
|
|
- Applies both context init scripts and CDP-level UA overrides
|
|
- Preserves explicit custom UA from `--user-agent` or `launch({ userAgent })`
|
|
|
|
### 2) Behavioral humanization
|
|
|
|
- Randomized typing cadence when `--delay` is used
|
|
- Random wait ranges (`wait 2000-5000`)
|
|
- Bezier-curve mouse movement before click actions
|
|
- Randomized navigation pacing
|
|
|
|
### 3) Region signal alignment
|
|
|
|
- Auto-aligns locale/timezone/Accept-Language by target TLD
|
|
- Reduces locale-timezone mismatch risk on region-sensitive sites
|
|
|
|
### 4) Verification-aware retry
|
|
|
|
- Detects common captcha/verification interstitial patterns
|
|
- Retries navigation with randomized backoff when triggered
|
|
|
|
## Typing `--delay` Correctly
|
|
|
|
Use `--delay` as an option:
|
|
|
|
```bash
|
|
agent-browser type @e2 "iphone" --delay 120
|
|
agent-browser keyboard type "iphone" --delay 120
|
|
```
|
|
|
|
If literal text includes `--delay`, stop option parsing with `--`:
|
|
|
|
```bash
|
|
agent-browser type @e2 -- "--delay 120"
|
|
agent-browser keyboard type -- "--delay 120"
|
|
```
|
|
|
|
## Validation Snapshot
|
|
|
|
Manual checks were run against common public detection pages in headed mode, including:
|
|
|
|
- [bot.sannysoft.com](https://bot.sannysoft.com/)
|
|
- [CreepJS](https://abrahamjuliot.github.io/creepjs/)
|
|
- [areyouheadless](https://arh.antoinevastel.com/bots/areyouheadless)
|
|
- [detect-headless](https://infosimples.github.io/detect-headless)
|
|
|
|
Reproduce CreepJS check:
|
|
|
|
```bash
|
|
node scripts/check-creepjs-headless.js --binary ./cli/target/release/agent-browser
|
|
```
|
|
|
|
## Command Coverage And Docs
|
|
|
|
Core command set is intentionally kept compatible with upstream `agent-browser`.
|
|
|
|
- Full command reference: [upstream agent-browser docs](https://github.com/vercel-labs/agent-browser)
|
|
- Local help: `agent-browser --help`
|
|
|
|
## Fork Policies
|
|
|
|
This fork enforces a few operational policies:
|
|
|
|
- `--profile` / `AGENT_BROWSER_PROFILE` are forbidden
|
|
- `--channel` / `AGENT_BROWSER_CHANNEL` are forbidden
|
|
- Default mode expects an existing browser via CDP on `localhost:9333`
|
|
|
|
## Maintainer Notes (Fork Release)
|
|
|
|
- Keep `upstream-main` for clean upstream sync
|
|
- Merge upstream into short-lived sync branches, then PR into `main`
|
|
- Recommended release format: `<upstream>-fork.<fork>` (example: `0.14.0-fork.3`)
|
|
- Use npm Trusted Publishing (OIDC)
|
|
|
|
## OpenClaw Skill Sync
|
|
|
|
This repo includes a dedicated OpenClaw skill at:
|
|
|
|
- `skills/agent-browser-stealth/SKILL.md`
|
|
|
|
GitHub Actions auto-syncs skills to ClawHub on every push via:
|
|
|
|
- `.github/workflows/clawhub-sync.yml`
|
|
|
|
Required repository secret:
|
|
|
|
- `CLAWHUB_TOKEN`: API token used by `clawhub login --token ...`
|
|
|
|
## License
|
|
|
|
Apache-2.0
|