Kernel云浏览器自动化技能：使用agent-browser处理机器人检测、会话保持与iframe

kernel-agent-browser by kernel/skills

200 周安装量

3 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/kernel/skills --skill kernel-agent-browser

自动化云服务测试

🇨🇳中文介绍

使用 Kernel 云浏览器的 Agent-Browser

此技能记录了使用 agent-browser 内置的 Kernel 提供程序 (-p kernel) 进行云浏览器自动化的最佳实践。

何时使用此技能

在以下情况下使用此技能：

使用 agent-browser -p kernel 命令自动化网站
处理具有激进反机器人措施的网站上的机器人检测
使用配置文件在自动化运行之间保持登录会话
处理 iframe，包括跨域支付表单
获取实时查看 URL 用于调试或手动干预
查找底层的 Kernel 会话 ID 用于高级 Playwright 脚本编写
为新的网站创建特定于站点的自动化技能

参考资料

创建特定于站点的技能 - 为特定网站构建自动化技能的指南

先决条件

加载 kernel-cli 技能以进行 Kernel CLI 安装和身份验证。

环境变量

在首次调用之前设置这些变量。CLI 在调用之间保持状态。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

Azure Data Explorer (Kusto) 查询技能：KQL数据分析、日志遥测与时间序列处理

119,800 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

117,000 周安装

Azure 配额管理指南：服务限制、容量验证与配额增加方法

96,900 周安装

变量	描述	默认值
`KERNEL_API_KEY`	必需。用于身份验证的 Kernel API 密钥	(无)
`KERNEL_HEADLESS`	在无头模式下运行浏览器 (`true`/`false`)	`false`
`KERNEL_STEALTH`	启用隐身模式以避免机器人检测 (`true`/`false`)	`true`
`KERNEL_TIMEOUT_SECONDS`	会话超时时间（秒）	`300`
`KERNEL_PROFILE_NAME`	用于持久化 cookie/登录的浏览器配置文件名称	(无)

# 通过 ARIA 角色 + 可访问名称（最稳定）
agent-browser -p kernel find role button click --name "Log In"
agent-browser -p kernel find role textbox fill "user@email.com" --name "Email"

# 通过可见文本内容
agent-browser -p kernel find text "View Menus" click
agent-browser -p kernel find text "Submit Order" click

# 通过表单标签（非常适合输入框）
agent-browser -p kernel find label "Username" fill "myuser"
agent-browser -p kernel find label "Password" fill "secret123"

# 通过占位符文本
agent-browser -p kernel find placeholder "Search..." type "query"

# 通过 data-testid（如果网站使用它们）
agent-browser -p kernel find testid "submit-btn" click

# 通过位置（需要时）
agent-browser -p kernel find first "li.item" click
agent-browser -p kernel find nth 2 ".card" hover

选择器类型	最适合	稳定性
`find role --name`	按钮、链接、导航	⭐⭐⭐ 最稳定
`find label`	带有标签的表单输入框	⭐⭐⭐ 最稳定
`find text`	可点击的文本元素	⭐⭐ 稳定
`find testid`	带有测试属性的网站	⭐⭐⭐ 最稳定
`find placeholder`	搜索框、输入框	⭐⭐ 稳定
`@e` 引用	未知网站、快速迭代	⭐ 临时性

获取实时查看 URL：
```
kernel browsers list
```
通过配置文件名称找到你的会话

kernel browsers view <session-id>
与用户共享实时查看 URL，并要求他们手动完成登录
一旦登录，继续自动化——配置文件将保存认证状态

# 通过 CSS 选择器点击
agent-browser -p kernel eval "document.querySelector('.submit-btn').click()"

# 通过选择器填充（附带事件分发）
agent-browser -p kernel eval "
  const el = document.querySelector('#email');
  el.value = 'user@example.com';
  el.dispatchEvent(new Event('input', {bubbles: true}));
  el.dispatchEvent(new Event('change', {bubbles: true}));
"

# 通过测试 ID 点击
agent-browser -p kernel eval "document.querySelector('[data-testid=\"submit\"]').click()"

找到会话 ID：
```
kernel browsers list
```
执行 Playwright 脚本：
```
kernel browsers exec <session-id> --code "
```
const frame = page.frameLocator('#payment-iframe'); await frame.locator('#card-number').fill('4111111111111111'); await frame.locator('#submit').click(); "

# 等待页面加载状态
agent-browser -p kernel wait --load domcontentloaded  # DOM 准备就绪
agent-browser -p kernel wait --load networkidle       # 网络稳定

# 等待特定的 URL 模式（非常适合登录后的重定向）
agent-browser -p kernel wait --url "**/dashboard"
agent-browser -p kernel wait --url "**/order-confirmation"

# 等待文本出现（非常适合动态内容）
agent-browser -p kernel wait --text "Password"        # 字段出现
agent-browser -p kernel wait --text "Order confirmed" # 成功消息

# 等待 JavaScript 条件
agent-browser -p kernel wait --fn "window.appReady === true"
agent-browser -p kernel wait --fn "document.querySelector('.spinner') === null"

# 通过 CSS 选择器等待元素
agent-browser -p kernel wait "#login-form"
agent-browser -p kernel wait ".results-loaded"

agent-browser -p kernel open https://example.com/login
agent-browser -p kernel wait --load domcontentloaded

# 使用语义选择器以提高稳定性
agent-browser -p kernel find label "Email" fill "user@example.com"
agent-browser -p kernel find label "Password" fill "secret123"
agent-browser -p kernel find role button click --name "Sign In"

# 等待实际的重定向，而不是任意的超时
agent-browser -p kernel wait --url "**/dashboard"

agent-browser -p kernel open https://example.com/login
agent-browser -p kernel wait --load domcontentloaded

# 步骤 1：用户名
agent-browser -p kernel find label "Username" fill "myuser"
agent-browser -p kernel press Enter

# 等待密码字段出现（不是固定的休眠！）
agent-browser -p kernel wait --text "Password"

# 步骤 2：密码
agent-browser -p kernel find label "Password" fill "secret123"
agent-browser -p kernel press Enter

# 等待成功的重定向
agent-browser -p kernel wait --url "**/home"

# 旧版（缓慢、脆弱）：
agent-browser -p kernel wait 2000
agent-browser -p kernel fill @e1 "username"
agent-browser -p kernel wait 2000
agent-browser -p kernel fill @e3 "password"
agent-browser -p kernel wait 5000

# 优化版（快速、稳定）：
agent-browser -p kernel wait --load domcontentloaded
agent-browser -p kernel find label "Username" fill "username"
agent-browser -p kernel wait --text "Password"
agent-browser -p kernel find label "Password" fill "password"
agent-browser -p kernel wait --url "**/dashboard"

# 点击登录链接打开模态框
agent-browser -p kernel find text "Log In" click
agent-browser -p kernel wait --text "Password"  # 等待模态框

# 填充模态框字段
agent-browser -p kernel find label "Email" fill "user@example.com"
agent-browser -p kernel find label "Password" fill "password123"
agent-browser -p kernel find role button click --name "Sign In"
agent-browser -p kernel wait --url "**/dashboard"

agent-browser -p kernel eval "document.querySelector('.login-link').click()"
agent-browser -p kernel wait 1000

agent-browser -p kernel eval "
  document.getElementById('username').value = 'user@example.com';
  document.getElementById('username').dispatchEvent(new Event('input', {bubbles: true}));
  document.getElementById('password').value = 'password123';
  document.getElementById('password').dispatchEvent(new Event('input', {bubbles: true}));
  document.querySelector('button[type=submit]').click();
"
agent-browser -p kernel wait --url "**/dashboard"

导航后引用会改变：点击链接或提交表单后，始终重新获取快照。
操作后等待：在触发页面加载或 AJAX 的点击/提交操作后添加等待。
配置文件未保存：确保运行 agent-browser -p kernel close 以保存配置文件状态。
超时太短：对于有用户暂停或页面加载缓慢的工作流程，增加 KERNEL_TIMEOUT_SECONDS。
隐身模式无效：尽管启用了隐身模式，一些网站仍能检测到机器人。使用手动登录回退。
针对顽固元素使用 eval：如果 fill 或 click 无效，尝试使用 eval 进行直接的 DOM 操作。
跨域 iframe：无法通过 agent-browser 命令交互。使用 Kernel 的 Playwright 执行。

# 使用配置文件持久化启动会话
export KERNEL_PROFILE_NAME=mysite
export KERNEL_TIMEOUT_SECONDS=600
agent-browser -p kernel open https://example.com

# 使用语义选择器进行基本交互（推荐）
agent-browser -p kernel wait --load domcontentloaded
agent-browser -p kernel find label "Email" fill "user@example.com"
agent-browser -p kernel find label "Password" fill "secret"
agent-browser -p kernel find role button click --name "Submit"
agent-browser -p kernel wait --url "**/success"

# 替代方案：快照 + 引用（用于探索）
agent-browser -p kernel snapshot -i
agent-browser -p kernel fill @eN "text"
agent-browser -p kernel click @eM

# 获取会话信息以进行手动干预
kernel browsers list
kernel browsers view <session-id>

# 清理
agent-browser -p kernel close

# 按钮和链接
agent-browser -p kernel find role button click --name "Submit"
agent-browser -p kernel find role link click --name "Next"
agent-browser -p kernel find text "Click here" click

# 表单输入框
agent-browser -p kernel find label "Email" fill "user@example.com"
agent-browser -p kernel find placeholder "Search" type "query"
agent-browser -p kernel find testid "username-input" fill "myuser"

# 智能等待
agent-browser -p kernel wait --load domcontentloaded
agent-browser -p kernel wait --text "Success"
agent-browser -p kernel wait --url "**/dashboard"
agent-browser -p kernel wait --fn "window.loaded === true"

🇺🇸English

Agent-Browser with Kernel Cloud Browsers

This skill documents best practices for using agent-browser's built-in Kernel provider (-p kernel) for cloud browser automation.

When to Use This Skill

Use this skill when you need to:

Automate websites using agent-browser -p kernel commands
Handle bot detection on sites with aggressive anti-bot measures
Persist login sessions across automation runs using profiles
Work with iframes including cross-origin payment forms
Get live view URLs for debugging or manual intervention
Find the underlying Kernel session ID for advanced Playwright scripting
Create site-specific automation skills for new websites

References

Creating Site-Specific Skills - Guide for building automation skills for specific websites

Prerequisites

Load the kernel-cli skill for Kernel CLI installation and authentication.

Environment Variables

Set these before your first agent-browser -p kernel call. The CLI holds state between invocations.

Variable	Description	Default
`KERNEL_API_KEY`	Required. Your Kernel API key for authentication	(none)
`KERNEL_HEADLESS`	Run browser in headless mode (`true`/`false`)	`false`
`KERNEL_STEALTH`	Enable stealth mode to avoid bot detection (`true`/)

Recommended Configuration

export KERNEL_API_KEY="your-api-key"
export KERNEL_TIMEOUT_SECONDS=600     # 10-minute timeout for complex workflows
export KERNEL_STEALTH=true            # Avoid bot detection (default)
export KERNEL_PROFILE_NAME=mysite     # Persist login sessions across runs

Profile Persistence

When KERNEL_PROFILE_NAME is set:

The profile is created if it doesn't exist
Cookies, logins, and session data are automatically saved when the browser session ends
Future sessions with the same profile name restore the saved state

This is especially useful for sites requiring login—authenticate once, reuse across sessions.

Basic Usage

agent-browser -p kernel open <url>        # Navigate to page
agent-browser -p kernel snapshot -i       # Get interactive elements with refs
agent-browser -p kernel click @e1         # Click element by ref
agent-browser -p kernel fill @e2 "text"   # Fill input by ref
agent-browser -p kernel close             # Close browser and save profile

Always use the -p kernel flag with each command.

Semantic Selectors (Recommended)

Instead of ephemeral @e refs that change on every page load, use semantic selectors via the find command for more stable, readable automation:

# By ARIA role + accessible name (most stable)
agent-browser -p kernel find role button click --name "Log In"
agent-browser -p kernel find role textbox fill "user@email.com" --name "Email"

# By visible text content
agent-browser -p kernel find text "View Menus" click
agent-browser -p kernel find text "Submit Order" click

# By form label (great for inputs)
agent-browser -p kernel find label "Username" fill "myuser"
agent-browser -p kernel find label "Password" fill "secret123"

# By placeholder text
agent-browser -p kernel find placeholder "Search..." type "query"

# By data-testid (if the site uses them)
agent-browser -p kernel find testid "submit-btn" click

# By position (when needed)
agent-browser -p kernel find first "li.item" click
agent-browser -p kernel find nth 2 ".card" hover

When to Use Which Selector

Selector Type	Best For	Stability
`find role --name`	Buttons, links, navigation	⭐⭐⭐ Most stable
`find label`	Form inputs with labels	⭐⭐⭐ Most stable
`find text`	Clickable text elements	⭐⭐ Stable
`find testid`	Sites with test attributes	⭐⭐⭐ Most stable
`find placeholder`	Search boxes, inputs

Recommendation : Use find for production automation. Use @e refs for exploration and quick prototyping, then convert to semantic selectors.

Finding Session ID and Live View URL

agent-browser creates a Kernel browser session under the hood. To get the session ID or live view URL:

# List all Kernel browsers (find yours by profile name or creation time)
kernel browsers list

# Get live view URL for a specific session
kernel browsers view <session-id>

This is useful when:

You need to execute Playwright scripts directly against the session
You want to share a live view URL with the user for manual intervention
You're debugging and want to watch the browser in real-time

Handling Bot Detection

Stealth Mode

Stealth mode (KERNEL_STEALTH=true) is enabled by default and helps avoid detection. However, some sites have aggressive bot detection that still triggers.

Manual Login Fallback

If login automation fails due to bot detection:

Get the live view URL:

kernel browsers list # Find your session by profile name kernel browsers view <session-id>
Share the live view URL with the user and ask them to complete the login manually
Once logged in, continue automation—the profile will save the authenticated state

JavaScript Fallback for Tricky Elements

Some elements (especially on bot-protected sites) don't respond to standard commands:

# Click by CSS selector
agent-browser -p kernel eval "document.querySelector('.submit-btn').click()"

# Fill by selector (with event dispatch)
agent-browser -p kernel eval "
  const el = document.querySelector('#email');
  el.value = 'user@example.com';
  el.dispatchEvent(new Event('input', {bubbles: true}));
  el.dispatchEvent(new Event('change', {bubbles: true}));
"

# Click by test ID
agent-browser -p kernel eval "document.querySelector('[data-testid=\"submit\"]').click()"

Anti-Bot Form Fields

Some payment processors (e.g., Point and Pay) use decoy form fields. Only fill fields matching specific patterns:

agent-browser -p kernel eval "
  const realInputs = Array.from(document.querySelectorAll('input'))
    .filter(el => el.name && el.name.startsWith('xeiinput'));
  // Fill only these inputs
"

Handling Iframes

Same-Origin Iframes

Use the frame command to switch context:

agent-browser -p kernel frame "#iframe-id"   # Switch to iframe
agent-browser -p kernel snapshot -i          # Snapshot within iframe
agent-browser -p kernel click @e1            # Interact within iframe
agent-browser -p kernel frame main           # Return to main frame

Cross-Origin Iframes

Cross-origin iframes require executing a Playwright script directly against the Kernel session:

Find the session ID:

kernel browsers list
Execute a Playwright script:

kernel browsers exec <session-id> --code " const frame = page.frameLocator('#payment-iframe'); await frame.locator('#card-number').fill('4111111111111111'); await frame.locator('#submit').click(); "

See the kernel-cli skill for more details on executing Playwright code.

Waiting Strategies

Smart waits are critical for fast, reliable automation. Using condition-based waits instead of fixed timeouts can reduce execution time by 50%+ while improving reliability.

Smart Waits (Recommended)

# Wait for page load states
agent-browser -p kernel wait --load domcontentloaded  # DOM ready
agent-browser -p kernel wait --load networkidle       # Network settled

# Wait for specific URL pattern (great for redirects after login)
agent-browser -p kernel wait --url "**/dashboard"
agent-browser -p kernel wait --url "**/order-confirmation"

# Wait for text to appear (great for dynamic content)
agent-browser -p kernel wait --text "Password"        # Field appeared
agent-browser -p kernel wait --text "Order confirmed" # Success message

# Wait for JavaScript condition
agent-browser -p kernel wait --fn "window.appReady === true"
agent-browser -p kernel wait --fn "document.querySelector('.spinner') === null"

# Wait for element by CSS selector
agent-browser -p kernel wait "#login-form"
agent-browser -p kernel wait ".results-loaded"

Fixed Waits (Last Resort)

# Only when no condition is available
agent-browser -p kernel wait 2000

Element Refs Best Practices

Element refs (@e1, @e2, etc.) are ephemeral and change:

After page navigation
After significant DOM updates
Between browser sessions

Always take a fresh snapshot before interacting:

agent-browser -p kernel snapshot -i
# Now use the refs from this snapshot
agent-browser -p kernel click @e5

Filtering Snapshots

# Filter for specific elements
agent-browser -p kernel snapshot -i | grep -i "button\|submit"

# Scope to a specific area
agent-browser -p kernel snapshot -s "#main-content" -i

Login Patterns

Single-Page Form (Optimized)

Username and password on the same page:

agent-browser -p kernel open https://example.com/login
agent-browser -p kernel wait --load domcontentloaded

# Use semantic selectors for stability
agent-browser -p kernel find label "Email" fill "user@example.com"
agent-browser -p kernel find label "Password" fill "secret123"
agent-browser -p kernel find role button click --name "Sign In"

# Wait for actual redirect, not arbitrary timeout
agent-browser -p kernel wait --url "**/dashboard"

Two-Step Form (Optimized)

Username first, then password on a second screen:

agent-browser -p kernel open https://example.com/login
agent-browser -p kernel wait --load domcontentloaded

# Step 1: Username
agent-browser -p kernel find label "Username" fill "myuser"
agent-browser -p kernel press Enter

# Wait for password field to appear (not a fixed sleep!)
agent-browser -p kernel wait --text "Password"

# Step 2: Password
agent-browser -p kernel find label "Password" fill "secret123"
agent-browser -p kernel press Enter

# Wait for successful redirect
agent-browser -p kernel wait --url "**/home"

Comparison: Old vs Optimized

# OLD (slow, fragile):
agent-browser -p kernel wait 2000
agent-browser -p kernel fill @e1 "username"
agent-browser -p kernel wait 2000
agent-browser -p kernel fill @e3 "password"
agent-browser -p kernel wait 5000

# OPTIMIZED (fast, stable):
agent-browser -p kernel wait --load domcontentloaded
agent-browser -p kernel find label "Username" fill "username"
agent-browser -p kernel wait --text "Password"
agent-browser -p kernel find label "Password" fill "password"
agent-browser -p kernel wait --url "**/dashboard"

Modal Login

# Click login link to open modal
agent-browser -p kernel find text "Log In" click
agent-browser -p kernel wait --text "Password"  # Wait for modal

# Fill modal fields
agent-browser -p kernel find label "Email" fill "user@example.com"
agent-browser -p kernel find label "Password" fill "password123"
agent-browser -p kernel find role button click --name "Sign In"
agent-browser -p kernel wait --url "**/dashboard"

Fallback: JavaScript for Tricky Modals

Some modals don't expose accessible labels:

agent-browser -p kernel eval "document.querySelector('.login-link').click()"
agent-browser -p kernel wait 1000

agent-browser -p kernel eval "
  document.getElementById('username').value = 'user@example.com';
  document.getElementById('username').dispatchEvent(new Event('input', {bubbles: true}));
  document.getElementById('password').value = 'password123';
  document.getElementById('password').dispatchEvent(new Event('input', {bubbles: true}));
  document.querySelector('button[type=submit]').click();
"
agent-browser -p kernel wait --url "**/dashboard"

Handling New Tabs

Some links open in new tabs:

# Click link that opens new tab
agent-browser -p kernel click @e38
agent-browser -p kernel tab 1           # Switch to new tab (0-indexed)
agent-browser -p kernel wait 2000
agent-browser -p kernel snapshot -i     # Interact with new tab

Screenshots and Debugging

# Take screenshot
agent-browser -p kernel screenshot ~/Downloads/page.png

# Full page screenshot
agent-browser -p kernel screenshot ~/Downloads/full.png --full

# View console messages
agent-browser -p kernel console

# View page errors
agent-browser -p kernel errors

# Get current URL
agent-browser -p kernel get url

Session Management

Cleanup

Always close the browser when done to save the profile:

agent-browser -p kernel close

Multiple Sessions

Run parallel browser sessions with named sessions:

agent-browser -p kernel --session site1 open https://site1.com
agent-browser -p kernel --session site2 open https://site2.com
agent-browser -p kernel session list

Common Gotchas

Refs change after navigation : Always re-snapshot after clicking links or submitting forms.
Wait after actions : Add waits after clicks/submits that trigger page loads or AJAX.
Profile not saving : Make sure to run agent-browser -p kernel close to save the profile state.
Timeout too short : Increase KERNEL_TIMEOUT_SECONDS for workflows with user pauses or slow pages.
Stealth not working : Some sites detect bots despite stealth. Use manual login fallback.
eval for stubborn elements : If fill or click don't work, try eval with direct DOM manipulation.
Cross-origin iframes : Can't interact via agent-browser commands. Use Kernel's Playwright execution.

Quick Reference

# Start session with profile persistence
export KERNEL_PROFILE_NAME=mysite
export KERNEL_TIMEOUT_SECONDS=600
agent-browser -p kernel open https://example.com

# Basic interaction with semantic selectors (recommended)
agent-browser -p kernel wait --load domcontentloaded
agent-browser -p kernel find label "Email" fill "user@example.com"
agent-browser -p kernel find label "Password" fill "secret"
agent-browser -p kernel find role button click --name "Submit"
agent-browser -p kernel wait --url "**/success"

# Alternative: snapshot + refs (for exploration)
agent-browser -p kernel snapshot -i
agent-browser -p kernel fill @eN "text"
agent-browser -p kernel click @eM

# Get session info for manual intervention
kernel browsers list
kernel browsers view <session-id>

# Cleanup
agent-browser -p kernel close

Selector Cheat Sheet

# Buttons and links
agent-browser -p kernel find role button click --name "Submit"
agent-browser -p kernel find role link click --name "Next"
agent-browser -p kernel find text "Click here" click

# Form inputs
agent-browser -p kernel find label "Email" fill "user@example.com"
agent-browser -p kernel find placeholder "Search" type "query"
agent-browser -p kernel find testid "username-input" fill "myuser"

# Smart waits
agent-browser -p kernel wait --load domcontentloaded
agent-browser -p kernel wait --text "Success"
agent-browser -p kernel wait --url "**/dashboard"
agent-browser -p kernel wait --fn "window.loaded === true"

Weekly Installs

200

Repository

kernel/skills

GitHub Stars

First Seen

Jan 28, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

cursor190

codex188

claude-code161

opencode74

gemini-cli70

github-copilot68

Kernel云浏览器自动化技能：使用agent-browser处理机器人检测、会话保持与iframe

🇨🇳中文介绍

使用 Kernel 云浏览器的 Agent-Browser

何时使用此技能

参考资料

先决条件

环境变量

相关 Skills

推荐配置

配置文件持久化

基本用法

语义选择器（推荐）

何时使用哪种选择器

查找会话 ID 和实时查看 URL

处理机器人检测

隐身模式

手动登录回退

通过配置文件名称找到你的会话

针对棘手元素的 JavaScript 回退

反机器人表单字段

处理 Iframe

同源 Iframe

跨域 Iframe

等待策略

智能等待（推荐）

固定等待（最后手段）

元素引用最佳实践

过滤快照

登录模式

单页表单（优化）

两步表单（优化）

对比：旧版 vs 优化版

模态框登录

回退：针对棘手模态框的 JavaScript

处理新标签页

截图和调试

会话管理

清理

多个会话

常见陷阱

快速参考

选择器速查表