# 摘要 这篇文章将通过几个实实在在的案例，带你看看 OpenClaw Browser 在表单自动化上到底能玩出什么花样。 从最简单的登录表单，到那些步骤多、字段杂的复杂表单，逐一拆解实现的思路和技巧。 你会学到怎么分析表单、智能填写、处理验证、搞定错误恢复。整套流程下来，基本就能搭出一套靠谱的表单自动化方案了。 # 1. 引言 - 表单自动化的价值 ## 1.1 常见表单场景

场景	说明	自动化价值
用户注册	填写注册信息	批量创建测试账号
数据录入	填写业务表单	提高录入效率
在线申请	填写申请表格	自动化申请流程
信息提交	提交各类信息	减少重复劳动

## 1.2 表单自动化挑战

## 1.3 OpenClaw 解决方案

挑战	解决方案
元素定位	语义快照 + 智能匹配
动态内容	等待策略 + 重试机制
验证码	人工介入 + OCR 识别
错误处理	异常捕获 + 自动恢复

# 2. 表单分析基础 ## 2.1 表单元素识别 动手写自动化之前，第一件事就是把表单的结构摸清楚。 下面这段代码展示了一个常规的表单分析函数。它会遍历快照里的所有元素，按类型分门别类整理好。

def analyze_form(snapshot):
    """分析表单结构"""
    form_info = {
        "textboxes": [],
        "checkboxes": [],
        "radios": [],
        "selects": [],
        "buttons": []
    }
    
    for element in snapshot["elements"]:
        element_type = element.get("type")
        
        if element_type == "textbox":
            form_info["textboxes"].append({
                "ref": element["ref"],
                "label": element.get("label", ""),
                "placeholder": element.get("placeholder", ""),
                "required": element.get("required", False)
            })
        elif element_type == "checkbox":
            form_info["checkboxes"].append(element)
        elif element_type == "radio":
            form_info["radios"].append(element)
        elif element_type == "combobox":
            form_info["selects"].append(element)
        elif element_type == "button":
            form_info["buttons"].append(element)
    
    return form_info

## 2.2 表单字段映射 拿到结构之后，下一步就是把待填的数据映射到具体的字段上。 这里的关键是"智能匹配"。通过字段的 label 或 placeholder 中的关键词来锁定目标，而不是死板地按顺序填。

def map_form_fields(form_info, data):
    """将数据映射到表单字段"""
    mapping = {}
    
    for field in form_info["textboxes"]:
        label = field.get("label", "").lower()
        placeholder = field.get("placeholder", "").lower()
        
        # 智能匹配
        for key, value in data.items():
            key_lower = key.lower()
            if key_lower in label or key_lower in placeholder:
                mapping[field["ref"]] = value
                break
    
    return mapping

## 2.3 表单验证规则 很多表单在提交前会做校验，比如必填、格式、长度、范围。 我们需要提前把这些规则摸清楚，才好做对应的处理。

验证类型	说明	处理方式
必填	required 属性	确保填写
格式	email、phone 等	格式化数据
长度	min/max length	截断或补全
范围	min/max value	调整数值

# 3. 实战案例一：登录表单 ## 3.1 场景描述 最典型的一个场景：自动登录一个网站，需要输入用户名、密码，然后点登录按钮。 ## 3.2 实现代码

def auto_login(url, username, password):
    """自动登录"""
    # 1. 打开登录页面
    browser(action="open", targetUrl=url)
    
    # 2. 等待页面加载
    browser(action="act", kind="wait", timeMs=2000)
    
    # 3. 获取页面快照
    snapshot = browser(
        action="snapshot",
        interactive=True
    )
    
    # 4. 查找用户名输入框
    username_field = find_element_by_keywords(
        snapshot, 
        "textbox", 
        ["用户名", "username", "账号", "email"]
    )
    
    # 5. 输入用户名
    browser(
        action="act",
        kind="type",
        ref=username_field["ref"],
        text=username
    )
    
    # 6. 查找密码输入框
    password_field = find_element_by_keywords(
        snapshot,
        "textbox",
        ["密码", "password", "pwd"]
    )
    
    # 7. 输入密码
    browser(
        action="act",
        kind="type",
        ref=password_field["ref"],
        text=password
    )
    
    # 8. 查找登录按钮
    login_btn = find_element_by_keywords(
        snapshot,
        "button",
        ["登录", "login", "signin", "提交"]
    )
    
    # 9. 点击登录
    browser(
        action="act",
        kind="click",
        ref=login_btn["ref"]
    )
    
    # 10. 等待登录完成
    browser(action="act", kind="wait", timeMs=3000)
    
    # 11. 验证登录结果
    new_snapshot = browser(action="snapshot")
    return check_login_success(new_snapshot)

def find_element_by_keywords(snapshot, element_type, keywords):
    """通过关键词查找元素"""
    for element in snapshot["elements"]:
        if element.get("type") != element_type:
            continue
        
        text = element.get("text", "").lower()
        label = element.get("label", "").lower()
        placeholder = element.get("placeholder", "").lower()
        
        for keyword in keywords:
            if keyword.lower() in text or keyword.lower() in label or keyword.lower() in placeholder:
                return element
    
    return None

## 3.3 错误处理 网络波动、页面状态不稳定，都可能让登录失败。 所以最好加一层重试机制。失败了就刷新页面重新来，直到达到最大尝试次数。

def safe_auto_login(url, username, password, max_retries=3):
    """带错误处理的自动登录"""
    for attempt in range(max_retries):
        try:
            result = auto_login(url, username, password)
            return result
        except Exception as e:
            print(f"登录失败 (尝试 {attempt + 1}/{max_retries}): {e}")
            
            if attempt < max_retries - 1:
                # 刷新页面重试
                browser(action="na vigate", targetUrl=url)
                browser(action="act", kind="wait", timeMs=2000)
    
    raise Exception("登录失败，已达最大重试次数")

# 4. 实战案例二：注册表单 ## 4.1 场景描述 注册表单往往比登录复杂得多：多个文本字段、复选框、下拉框，甚至还有验证码。 下面展示一个通用的注册自动化流程。 ## 4.2 实现代码

def auto_register(url, user_data):
    """自动注册"""
    # 1. 打开注册页面
    browser(action="open", targetUrl=url)
    browser(action="act", kind="wait", timeMs=2000)
    
    # 2. 获取表单快照
    snapshot = browser(action="snapshot", interactive=True)
    
    # 3. 分析表单结构
    form_info = analyze_form(snapshot)
    
    # 4. 映射数据到字段
    field_mapping = map_form_fields(form_info, user_data)
    
    # 5. 填写文本字段
    for ref, value in field_mapping.items():
        browser(
            action="act",
            kind="type",
            ref=ref,
            text=str(value)
        )
        # 短暂等待，模拟人工输入
        browser(action="act", kind="wait", timeMs=300)
    
    # 6. 处理复选框（如同意条款）
    for checkbox in form_info["checkboxes"]:
        text = checkbox.get("text", "").lower()
        if "同意" in text or "条款" in text or "agree" in text.lower():
            browser(
                action="act",
                kind="click",
                ref=checkbox["ref"]
            )
    
    # 7. 处理下拉选择框
    for select in form_info["selects"]:
        label = select.get("label", "").lower()
        if "城市" in label or "city" in label:
            browser(
                action="act",
                kind="select",
                ref=select["ref"],
                value=user_data.get("city", "北京")
            )
    
    # 8. 提交表单
    submit_btn = find_element_by_keywords(
        snapshot,
        "button",
        ["注册", "register", "提交", "submit"]
    )
    
    if submit_btn:
        browser(
            action="act",
            kind="click",
            ref=submit_btn["ref"]
        )
    
    # 9. 等待响应
    browser(action="act", kind="wait", timeMs=3000)
    
    # 10. 检查结果
    result_snapshot = browser(action="snapshot")
    return check_register_result(result_snapshot)

## 4.3 验证码处理 验证码是个绕不开的坎。 常见做法有两种： - 一是用 OCR 自动识别 - 二是弹窗让人工手动输入 下面这段代码演示了如何定位验证码图片并填写识别结果。

def handle_captcha():
    """处理验证码"""
    # 获取快照
    snapshot = browser(action="snapshot")
    
    # 查找验证码图片
    captcha_img = find_element(snapshot, "image", "验证码")
    
    if captcha_img:
        # 截取验证码图片
        captcha_screenshot = browser(
            action="screenshot",
            element=captcha_img["ref"]
        )
        
        # 方案1：OCR识别
        captcha_text = ocr_recognize(captcha_screenshot)
        
        # 方案2：请求人工输入
        # captcha_text = request_human_input("请输入验证码")
        
        # 填写验证码
        captcha_input = find_element(snapshot, "textbox", "验证码")
        browser(
            action="act",
            kind="type",
            ref=captcha_input["ref"],
            text=captcha_text
        )

# 5. 实战案例三：多步骤表单 ## 5.1 场景描述 很多业务系统里的表单是分步骤完成的，比如订单填写、申请流程。 每一步需要单独处理，然后点击"下一步"或"提交"。我们用一个函数统一处理这类场景。 ## 5.2 实现代码

def multi_step_form(url, steps_data):
    """多步骤表单处理"""
    # 1. 打开页面
    browser(action="open", targetUrl=url)
    browser(action="act", kind="wait", timeMs=2000)
    
    # 2. 逐步处理
    for step_index, step_data in enumerate(steps_data):
        print(f"处理步骤 {step_index + 1}/{len(steps_data)}")
        
        # 获取当前页面快照
        snapshot = browser(action="snapshot", interactive=True)
        
        # 填写当前步骤的数据
        fill_current_step(snapshot, step_data)
        
        # 查找下一步按钮
        next_btn = find_element_by_keywords(
            snapshot,
            "button",
            ["下一步", "next", "继续", "continue"]
        )
        
        if next_btn:
            browser(
                action="act",
                kind="click",
                ref=next_btn["ref"]
            )
            browser(action="act", kind="wait", timeMs=2000)
        else:
            # 最后一步，查找提交按钮
            submit_btn = find_element_by_keywords(
                snapshot,
                "button",
                ["提交", "submit", "完成", "finish"]
            )
            
            if submit_btn:
                browser(
                    action="act",
                    kind="click",
                    ref=submit_btn["ref"]
                )
    
    # 3. 等待最终结果
    browser(action="act", kind="wait", timeMs=3000)
    
    # 4. 验证完成
    final_snapshot = browser(action="snapshot")
    return verify_completion(final_snapshot)

def fill_current_step(snapshot, step_data):
    """填写当前步骤的数据"""
    for field_name, value in step_data.items():
        # 查找对应字段
        element = find_element_by_keywords(
            snapshot,
            "textbox",
            [field_name]
        )
        
        if element:
            browser(
                action="act",
                kind="type",
                ref=element["ref"],
                text=str(value)
            )

## 5.3 步骤验证 每完成一步，最好做个检查。比如确认页面上出现了预期的元素，避免漏填或跳转错误。

def verify_step_completion(expected_elements):
    """验证步骤完成"""
    snapshot = browser(action="snapshot")
    
    for element_desc in expected_elements:
        found = find_element_by_keywords(
            snapshot,
            element_desc["type"],
            [element_desc["text"]]
        )
        
        if not found:
            return False
    
    return True

# 6. 高级技巧 ## 6.1 智能等待 页面上的元素可能是异步加载的，如果直接去定位很可能扑空。 与其写死等待时间，不如写个智能等待函数。不断获取快照，直到目标元素出现，超时再报错。

def smart_wait_for_element(element_type, keywords, timeout=10000):
    """智能等待元素出现"""
    start_time = time.time()
    
    while time.time() - start_time < timeout / 1000:
        snapshot = browser(action="snapshot", interactive=True)
        element = find_element_by_keywords(snapshot, element_type, keywords)
        
        if element:
            return element
        
        time.sleep(0.5)
    
    raise TimeoutError(f"等待元素超时: {element_type} - {keywords}")

## 6.2 表单数据预处理 填进去的数据不一定跟表单要求的格式完全匹配。比如电话号码需要去掉分隔符，邮箱要校验格式。 在正式填写之前，先做一遍数据预处理，能减少很多后期错误。

def preprocess_form_data(data, form_info):
    """预处理表单数据"""
    processed = {}
    
    for field in form_info["textboxes"]:
        label = field.get("label", "").lower()
        placeholder = field.get("placeholder", "").lower()
        
        # 根据字段类型处理数据
        if "邮箱" in label or "email" in placeholder:
            # 邮箱格式验证
            email = data.get("email", "")
            if "@" in email:
                processed[field["ref"]] = email
        
        elif "电话" in label or "phone" in placeholder:
            # 电话格式化
            phone = data.get("phone", "")
            processed[field["ref"]] = phone.replace("-", "").replace(" ", "")
        
        elif "日期" in label or "date" in placeholder:
            # 日期格式化
            date = data.get("date", "")
            processed[field["ref"]] = format_date(date)
        
        else:
            # 默认处理
            for key, value in data.items():
                if key.lower() in label or key.lower() in placeholder:
                    processed[field["ref"]] = str(value)
                    break
    
    return processed

## 6.3 错误恢复 万一填到一半挂了怎么办？ 一种思路是保存当前状态（比如已经填好的字段值）。然后刷新页面恢复状态继续填，而不是从头再来。

def form_fill_with_recovery(url, data, max_retries=3):
    """带错误恢复的表单填写"""
    sa ved_state = {}
    
    for attempt in range(max_retries):
        try:
            # 恢复之前的状态
            if sa ved_state:
                restore_state(sa ved_state)
            
            # 填写表单
            result = fill_form(url, data)
            return result
            
        except Exception as e:
            print(f"填写失败: {e}")
            
            # 保存当前状态
            sa ved_state = sa ve_current_state()
            
            if attempt < max_retries - 1:
                # 刷新页面
                browser(action="na vigate", targetUrl=url)
                browser(action="act", kind="wait", timeMs=2000)
    
    raise Exception("表单填写失败，已达最大重试次数")

# 7. 最佳实践 ## 7.1 表单自动化清单

步骤	说明	检查项
分析	分析表单结构	所有字段已识别
映射	映射数据到字段	数据格式正确
填写	填写表单数据	填写顺序合理
验证	验证填写结果	无错误提示
提交	提交表单	提交成功

## 7.2 常见陷阱 踩过的坑多了，自然就长记性。下面几个是高频问题：

陷阱	说明	解决方案
异步加载	元素动态加载	智能等待
隐藏字段	不可见但必填	检查隐藏元素
事件触发	需要触发事件	模拟完整交互
防机器人	检测自动化行为	模拟人工操作

## 7.3 性能优化 如果字段很多，逐字段填写时每步等300毫秒会累积成不小的延迟。 可以尝试批量填写，把等待时间压缩到最小。

# 批量操作
def batch_fill_fields(field_values):
    """批量填写字段"""
    snapshot = browser(action="snapshot", interactive=True)
    for ref, value in field_values.items():
        browser(
            action="act",
            kind="type",
            ref=ref,
            text=value
        )
        # 减少等待时间
        time.sleep(0.1)  # 最小等待

# 8. 总结 ## 核心要点

要点	说明
先分析后操作	先获取快照分析表单结构
智能匹配	使用语义匹配定位字段
错误处理	添加重试和恢复机制
验证结果	确认操作成功完成