1. 为什么 UI 自动化总在 Locator 上翻车做 Python 桌面或网页自动化的朋友大概率都经历过这种场景脚本昨天还能跑今天一运行就报ElementNotFound或者干脆点错了按钮。问题往往不在业务逻辑而在 Locator——也就是“怎么找到那个 UI 元素”。Clicknium 这个库的思路和 Selenium、pywinauto 不太一样它把 Locator 从代码里抽出来单独存成.locator目录下的配置文件录制一次就能复用还能在 VS Code 里可视化调试。对刚入门 UI 自动化的同学来说这套机制能省掉大量手写 XPath 的痛苦。但 Clicknium 的中文资料确实少官方文档全英文很多概念第一次看会懵。这篇就聚焦一个最实际的目标用 Python Clicknium 跑通第一个自动化流程把 Locator 配置和项目骨架搭起来。同时我会把模型调用的 Key 统一走 TaoToken这样后面写脚本时不用在多个平台之间来回切换 Key一个 Key 就能覆盖对话、编码和自动化辅助场景。适合谁看写过一点 Python、想入门 Windows 桌面或浏览器自动化、又被 Locator 折磨过的开发者。2. TaoToken 前置统一 Key 与项目初始化TaoToken 在这里扮演的角色是“统一入口”。你写 Clicknium 脚本时难免要调模型来生成 Locator 片段、解释报错、或者让 Agent 帮你补全代码。如果每个模型都单独申请 Key管理起来很乱。TaoToken 提供一个兼容常见接口规范的 API 地址你只需要在环境变量里放一个 Key脚本里通过base_url指向它就行。先做两件事。第一去控制台创建一个 API Key地址是https://taotoken.net/console创建后复制保存后面配置环境变量用。第二确认你的 Python 环境是 3.8 以上Windows 系统Clicknium 的桌面自动化依赖 Windows UI AutomationMac 和 Linux 只能跑部分网页场景。安装 Clicknium 本身很简单pip install clicknium如果下载慢可以临时切清华源pip install clicknium -i https://pypi.tuna.tsinghua.edu.cn/simple装完后在 VS Code 扩展市场搜 Clicknium 安装插件插件会帮你管理 Recorder 和浏览器扩展。浏览器扩展支持 Chrome、Edge、Firefox 等网页自动化必须装桌面自动化可以跳过。环境变量配置 KeyWindows 下用 PowerShell$env:TAOTOKEN_API_KEY你的Key或者写进系统环境变量永久生效。脚本里读取时用os.getenv(TAOTOKEN_API_KEY)。这样做的目的是把 Key 和代码分离避免硬编码泄露。3. 可复制配置config.toml 与 settings.json 骨架Clicknium 项目跑起来后根目录会有一个.locator文件夹里面是 Locator 的存储。但很多人不知道项目根目录还可以放config.toml和settings.json来做全局配置。下面给一份可直接复制的骨架。config.toml放在项目根目录用来声明运行时的默认行为[general] project_name ClickniumSample default_timeout 30 screenshot_on_failure true log_level INFO [taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model gpt-4o-mini [browser] default_browser chrome headless false extension_wait 5settings.json放在.locator同级用来控制 Locator 的匹配策略{ locator: { match_mode: strict, fallback_to_fuzzy: true, retry_count: 3, retry_interval_ms: 500, attribute_priority: [automationId, name, className, tag] }, recorder: { snapshot_enabled: true, snapshot_dir: .locator/snapshots, max_depth: 8 }, validation: { auto_validate_on_save: true, timeout_seconds: 10 } }这两个文件不是必须的但加上之后Locator 失效时会有重试和模糊匹配兜底调试时能省不少时间。attribute_priority决定了 Recorder 抓取元素时优先用哪些属性automationId排第一是因为它通常最稳定。项目目录结构建议这样组织ClickniumSample/ ├── .locator/ │ ├── sample.cnstore │ └── snapshots/ ├── config.toml ├── settings.json ├── main.py └── requirements.txt.locator文件夹不要手动改交给 Recorder 和 VS Code 插件管理。main.py是你的入口脚本。4. 验证请求跑通第一个 Locator 定位配置就绪后写一个最小可运行脚本验证 Locator 能不能定位到元素。以打开 Bing 首页、在搜索框输入关键词为例。先录制 Locator。在 VS Code 里按CtrlShiftP输入Clicknium: Capture启动 Recorder。浏览器打开 Bing按住Ctrl点击搜索输入框Recorder 会生成一个 Locator命名比如bing.search_box。再录制搜索按钮命名bing.search_btn。然后写main.pyimport os from time import sleep from clicknium import clicknium as cc, locator def main(): api_key os.getenv(TAOTOKEN_API_KEY) if not api_key: raise RuntimeError(请先设置 TAOTOKEN_API_KEY 环境变量) tab cc.chrome.open(https://www.bing.com/) sleep(2) search_box tab.find_element(locator.bing.search_box) search_box.set_text(Clicknium Locator) search_btn tab.find_element(locator.bing.search_btn) search_btn.click() sleep(3) tab.close() if __name__ __main__: main()运行python main.py如果浏览器自动打开、输入文字、点击搜索说明 Locator 配置成功。这里find_element接收的就是 Recorder 生成的 Locator 对象set_text和click是 Clicknium 封装的通用操作。验证 Locator 是否有效还有更直接的办法在 VS Code 的 LOCATORS 面板里选中某个 Locator点右侧的 Validation 按钮。注意被定位的网页或应用必须处于打开状态Validation 不会主动帮你启动程序。如果 Validation 通过面板会高亮对应的 UI 元素失败则提示属性不匹配。参数化 Locator 是进阶用法。比如列表里多个结构相同的项只有索引不同可以在 Locator 属性里用{{index}}声明变量variables {index: 1} element tab.find_element(locator.bing.list_item, variables) text element.get_text() print(text)这样循环遍历时不用为每个项单独录制 Locator。5. 本篇常见错排查第一个坑ElementNotFound但元素明明在屏幕上。先检查 Locator 的层级属性是不是勾选过多。Clicknium 的 Locator 是层级结构第一层通常是应用进程第二层是窗口或标签页第三层才是具体元素。如果某一层属性不稳定比如窗口标题会变在 LOCATORS 面板里取消勾选那一层让定位更宽松。第二个坑set_text输入不进去。常见原因是输入框没激活。把by参数改成sendkey-after-click它会先模拟点击再输入search_box.set_text(hello, bysendkey-after-click)另外中文输入法会劫持键盘事件跑脚本前切到英文输入法。第三个坑浏览器扩展没装或没启用。网页自动化依赖 Clicknium 浏览器扩展如果cc.chrome.open报错先在 VS Code 的 Clicknium 面板里点install_or_update安装扩展然后手动打开浏览器确认扩展已启用。第四个坑超时时间太短。默认 30 秒但有些页面加载慢可以在config.toml里把default_timeout调大或者在单次调用时传timeout60。第五个坑Locator 文件冲突。多人协作时.locator目录容易冲突建议把它纳入版本控制但快照文件snapshots可以加进.gitignore因为快照只是辅助辨认不影响定位逻辑。如果排查时想看更详细的日志把config.toml里的log_level改成DEBUG运行时会输出每一步的定位过程。6. 下一步把 Key 和 Locator 串起来跑通第一个流程后你会发现 Clicknium 的核心就是 Locator 的管理和复用。接下来可以做的事用参数化 Locator 处理动态列表用get_property读取元素属性做断言或者把脚本封装成函数供多个流程调用。模型辅助方面如果你想让 Agent 帮你生成 Locator 片段或解释报错可以在脚本里通过 TaoToken 的统一接口调用。API 地址是https://taotoken.net/api配合前面设置的TAOTOKEN_API_KEY环境变量即可。需要管理多个 Key 或查看用量去控制台https://taotoken.net/console。如果后面要长期写编码类 Agent可以了解 Coding Plan地址是https://taotoken.net/coding-plan。接入文档在https://taotoken.net/docAPI Key 管理页在https://taotoken.net/api-keys。Locator 配置这件事录一次、验证一次、参数化一次基本就掌握了。剩下的就是多跑几个真实场景把踩过的坑记下来下次遇到类似报错能快速定位。