OpenWeb
Agent-native way to access any website. Bridging agent CLI and web GUI through API.
Load Discipline
- Do not read every file in this folder.
- Start with SKILL.md. Follow one route at a time.
Use Existing Site
1. Find the site
openweb sites # list all available sites
If the site has no package, do NOT say "unsupported." Route to add-site/guide.md.
2. Check readiness
openweb <site> # transport, auth, operations list
Requires browser: yes— browser auto-starts when needed; no manual setup requiredRequires login: yes— user must be logged in via their browser session
3. Read site notes
Prefer site docs when they exist in your workspace:
- Source repo: read
src/sites/<site>/SKILL.mdfor workflows and intent mapping, thensrc/sites/<site>/DOC.mdfor internals. - Shipped/runtime package: only
DOC.md, specs, manifest, examples, and adapters are guaranteed. Per-siteSKILL.mdandPROGRESS.mdare source-tree docs and are not shipped into$OPENWEB_HOME/sites/<site>/.
If only the shipped package is available, rely on openweb <site>, openweb <site> <op>, examples, and DOC.md.
4. Inspect the operation
openweb <site> <op> # params, response shape, permission tier
openweb <site> <op> --example # real example params from fixtures
Check the operation's permission tier before executing:
| Tier | Default | Behavior |
|---|---|---|
read |
allow | GET-like operations — execute freely |
write |
prompt | Creates/updates — ask user before executing |
delete |
prompt | Destructive — ask user before executing |
transact |
deny | Financial/irreversible — always skip |
5. Execute
openweb <site> <op> '{"key":"value"}' # stdout=JSON, stderr=JSON error
Auto-spill: responses over 4096 bytes write to a temp file.
openweb <site> exec <op> '{...}' is equivalent — exec can be omitted when the third arg is JSON.
6. On failure
Errors on stderr include failureClass:
| failureClass | Action |
|---|---|
needs_browser |
Browser auto-starts; if it fails, check Chrome installation. Fallback: openweb browser start |
needs_login |
openweb login <site> then openweb browser restart |
needs_page |
Open a tab to the site URL |
bot_blocked |
openweb browser restart --no-headless, user solves CAPTCHA in visible browser, then retry. For persistent sites, set "browser": {"headless": false} in config |
permission_denied |
Update permissions in $OPENWEB_HOME/config.json |
permission_required |
Ask user for confirmation, then retry |
retriable |
Wait a few seconds, retry (max 2) |
fatal |
Don't retry — fix params or check site name |
If the table above doesn't resolve it, read references/troubleshooting.md.
7. Missing site or coverage
Site doesn't exist or lacks needed operations? Read add-site/guide.md.
Add / Expand / Upgrade Site
Read add-site/guide.md
Fix a Problem
Read references/troubleshooting.md
File Map
All paths relative to skills/openweb/.
add-site/ (workflow — load in sequence)
| File | Load when |
|---|---|
add-site/guide.md |
Entry point for add/expand workflow |
add-site/probe.md |
Probe step: CDP browser-side discovery |
add-site/capture.md |
Capture step: recording browser traffic |
add-site/review.md |
Review step: reading analysis-summary.json |
add-site/curate-operations.md |
Curate: naming, noise, params, permissions |
add-site/curate-runtime.md |
Curate: auth, transport, extraction |
add-site/curate-schemas.md |
Curate: response schemas, examples, PII |
add-site/verify.md |
Verify: runtime + spec + doc loop |
add-site/document.md |
Document: per-site SKILL.md + DOC.md + PROGRESS.md, knowledge updates |
references/ (lookup — load independently)
| File | Load when |
|---|---|
references/cli.md |
CLI command syntax, flags, stdout/stderr |
references/x-openweb.md |
Full x-openweb field schema |
references/troubleshooting.md |
Something broke — classify, diagnose, fix |
knowledge/ (patterns — load at decision points)
| File | Load when |
|---|---|
knowledge/archetypes.md |
Expected operations by site category |
knowledge/auth-routing.md |
Auth type unknown — signal-to-family lookup |
knowledge/auth-primitives.md |
Configuring auth — config and gotchas |
knowledge/bot-detection.md |
Transport/capture decisions |
knowledge/extraction.md |
Extraction signals — SSR/DOM patterns |
knowledge/graphql.md |
GraphQL — persisted queries, batching |
knowledge/ws.md |
WebSocket — message/connection patterns |
knowledge/adapter-recipes.md |
Adapter patterns, code templates, pitfalls |
knowledge/transport-upgrade.md |
Transport tier decisions, node feasibility, API discovery |