portal（portal 演示文稿）

Portal

Turn any URL into a shareable live browser session. Viewers get a real browser running in a cloud VM — 10 minutes per session.

Install

openclaw plugins install openclaw-portal
openclaw gateway restart

Watch — AI clicks, scrolls, and narrates a guided demo. Play — Viewer explores freely with AI guardrails blocking unwanted areas.

Quick Reference

Sending URLs to the User

When any tool returns a URL the user needs to open (verification_url, hosted_url, portal link, checkout URL), you MUST send it to the user in the current chat. Do NOT attempt to run shell commands like open or xdg-open — the user is on a messaging channel (WhatsApp, Telegram, etc), not a local desktop.

Just include the URL in your reply. The user will tap it on their device.

Workflow

Follow these steps in order. Never skip the review step (Step 4).

Step 1 — Authenticate

Call portal_status. If not authenticated, call portal_login.

Returns verification_url and device_code. Send the verification URL to the user in the chat so they can open it and sign in.

Poll portal_login_check with the device_code every 5 seconds until approved.

New users get 3 creation credits + 10 view credits.

Step 2 — Classify the Site

Ask the user if you're unsure whether the site needs login.

Public site → skip to Step 3.

Needs login → capture auth state:

{"url": "https://app.example.com/login", "description": "Login to Example dashboard"}

Call save_login with the above. Response includes hosted_url — send it to the user so they can open the hosted browser and log in.

Poll get_session until status is ready. Do NOT ask the user if they're done — the tool tells you. When ready, grab saved_state_id.

Local file → zip the project (exclude node_modules, .git, dist), base64 encode. Pass contents as ptl.entry.source with entry.type: "local_file".

Step 3 — Generate Content

Offer the user 4 options if they don't specify:

1. Watch — AI script (default for landing pages)
2. Watch — Record yourself
3. Play — AI selectors (beta)
4. Play — Pick elements yourself

Watch — AI script (most common):

{
  "url": "https://stripe.com",
  "goals": [
    "Show the main value proposition",
    "Navigate to pricing page and highlight plans",
    "End with social proof or customer logos"
  ],
  "max_pages": 3
}

Use max_pages: 3 to get multi-page demos (homepage + pricing + features). Without it, demos stay on the homepage only.

Writing great goals:

• Be specific: "Navigate to pricing page" > "Show pricing"
• Ask for navigation: "Click to the features page" produces click actions, not just scrolls
• Ask for social proof: "End with customer logos or metrics" pulls real stats
• Ask for variety: "Include interactive elements like tabs or accordions"

Call create_script. It auto-polls internally and returns the complete draft directly — no need to call get_script.

Watch — Record yourself: Call record_demo. Send the hosted_url to the user so they can record in the hosted browser.

Play — AI selectors: Call create_script with mode: "play".

Play — User picks: Call pick_selectors. Send the hosted_url to the user so they can click elements in the hosted browser.

Step 4 — Review with User (MANDATORY)

Never skip this step. Show the user everything from the draft:

Watch mode:

• Each scene with narration text and actions
• Example Q&A pairs — ask if answers are accurate
• AI greeting and knowledge summary

Play mode:

• Blocked selectors and allowed URLs
• AI greeting and knowledge

Ask: "What do you want to call this? Look good to go?"

Slugify the name for the URL (lowercase, hyphens, no spaces).

Step 5 — Deploy

Call make_portal with the full PTL spec. Costs 1 creation credit.

It auto-polls internally until the portal is ready — the result includes the final portal URL. Send it to the user.

Step 6 — Post-Deploy (Offer These)

• Add CTA button: Call configure_portal with cta_text and cta_url
• Get embed snippet: Call configure_embed with allowed_origin
• View session replays: Call get_portal_sessions
• Debug issues: Call get_creation_logs

PTL Spec (Minimal)

The ptl parameter to make_portal MUST be a JSON object (not a string). Do NOT JSON.stringify it.

Play mode:

{
  "ptl": {
    "entry": { "url": "https://example.com" },
    "experience": {
      "mode": "play",
      "agent": {
        "greeting": "Welcome! Ask me anything.",
        "knowledge": "Summary of the site..."
      }
    },
    "guardrails": {
      "allowed_urls": ["example.com"],
      "disabled_elements": [
        { "selector": "a[href='/login']", "reason": "Auth disabled in demo" }
      ]
    }
  }
}

Watch mode:

{
  "ptl": {
    "entry": { "url": "https://example.com" },
    "experience": {
      "mode": "watch",
      "agent": {
        "goal": "Show key features",
        "greeting": "Welcome to the demo!",
        "scenes": [
          {
            "script": "Narration text here",
            "actions": [
              { "type": "scroll_to_element", "selector": "h2", "inner_text": "Key Features" },
              { "type": "wait", "ms": 2000 },
              { "type": "click", "selector": "a[href='/pricing']", "inner_text": "Pricing" }
            ]
          }
        ]
      }
    },
    "guardrails": {
      "allowed_urls": ["example.com"],
      "disabled_elements": []
    }
  }
}

Supported action types:

Scenes can have multiple actions (up to 20 per scene). A good scene flows: scroll → wait → click.

Server auto-fills version, region, entry.type. No need to call normalize_ptl or validate_ptl before make_portal — validation is built in.

Improving Script Quality

When reviewing drafts from create_script, improve them before deploying:

1. Add click actions for navigation: If the draft only has scroll_to_element actions, add click actions to navigate between pages (pricing, features, docs).
2. Add wait actions for pacing: Insert { "type": "wait", "ms": 2000 } between actions for natural pacing and emphasis.
3. Use multiple actions per scene: Don't limit scenes to 1 action — scroll to a section, wait, then click or highlight another element.
4. Include social proof: End with a scene that scrolls to customer logos, testimonials, or metrics.
5. Keep narrations concise: Under 2 sentences per scene — the viewer is watching, not reading.
6. Always include inner_text: On every click and scroll_to_element action — it's the fallback when CSS selectors break on dynamic pages.

Cursor Movement

Portal demos show a real cursor moving on screen. The cursor automatically:

• Moves to the target element before each action
• Follows scrolls smoothly
• Clicks precisely on elements with visual feedback

For best results:

• Use scroll_to_element with specific inner_text (not just body) so the cursor targets a visible heading
• Place click actions on prominent buttons/links with clear inner_text
• Use wait between actions so viewers can see the cursor position before the next move

Rules

• Do NOT use the built-in canvas tool for portal creation — use the portal_* tools from this plugin
• Never guess CSS selectors — only use what create_script or pick_selectors returns
• Never navigate authenticated sites autonomously — auth sites get single-page CDP grab only
• Always show draft and get user confirmation before make_portal
• Keep polling get_session — it blocks 30s server-side. Do NOT ask user if they're done
• Pass inner_text on all click and scroll_to_element actions — it's the fallback when selectors fail on dynamic pages
• Never create a second portal while one is provisioning — poll get_portal instead
• Send URLs to the user in the chat — do NOT run shell commands to open URLs. The user is on a messaging channel and will tap the link themselves
• Request multi-page demos — always pass max_pages: 3 (or higher) in create_script to get richer navigation beyond the homepage