| name | claws-uis |
| description | CLAWS-UIS：人类示教的计算机操控智能体，支持 Windows 和 macOS。适用场景：(1) 录制人类操作演示（屏幕 + 鼠标 + 键盘），(2) 解析录制内容为语义化操作轨迹，(3) 基于学习到的轨迹执行 GUI 自动化任务，(4) 将工作流编译为可复用的混合 RPA+Agent 脚本，(5) 回放编译脚本并支持参数替换，(6) 配置双模型 API（Gemini + Kimi），(7) 涉及桌面自动化、GUI 智能体、录屏、轨迹学习或工作流编译的任何任务。触发关键词：录制演示、解析轨迹、运行智能体、编译工作流、回放脚本、CLAWS、Aloha、GUI 自动化、计算机操控智能体、RPA。 |
CLAWS-UIS
人类示教的计算机操控智能体。录制一次，永久执行。
快速决策树
你想做什么？
├─ 录制一段演示 → 下方"录制工作流"
├─ 执行任务（有演示） → 模式 1：hybrid_run.py
├─ 执行任务（无演示） → 模式 2：pipeline_run.py --mode agent-execute
├─ 执行任务 + 生成脚本 → 模式 3：pipeline_run.py --mode agent-only
├─ 将演示编译为脚本 → 模式 4：pipeline_run.py --mode compile-only
├─ 回放已编译的脚本 → 模式 5：workflow_run.py
├─ 配置 API 密钥 → "配置"章节
└─ 了解架构 → 参见 references/architecture.md
录制工作流
python -m Aloha_Learn.recorder.recorder_gui
python -m Aloha_Learn.recorder.recorder_app --project 项目名
cd Aloha_Learn && python parser.py 项目名
cp projects/项目名/项目名_trace.json ../Aloha_Act/trace_data/
执行工作流
五种模式——根据输入和期望输出选择：
模式 1：引导执行（有演示 + 新任务）
cd Aloha_Act
python scripts/hybrid_run.py --task "任务描述" --trace-id 轨迹名
模式 2：纯智能体执行（仅任务，无脚本输出）
cd Aloha_Act
python scripts/pipeline_run.py --mode agent-execute --task "任务描述"
模式 3：智能体 + 编译脚本（仅任务 -> 可复用脚本）
cd Aloha_Act
python scripts/pipeline_run.py --mode agent-only --task "任务描述"
模式 4：演示 -> 编译脚本（演示 -> 可复用脚本）
cd Aloha_Act
python scripts/pipeline_run.py --mode compile-only --trace-id 轨迹名
模式 5：脚本回放（编译脚本 + 参数）
cd Aloha_Act
python scripts/workflow_run.py --trace-id 轨迹名
python scripts/workflow_run.py 轨迹名 --参数名 参数值
python scripts/workflow_run.py --trace-id 轨迹名 --params '{"键":"值"}'
配置
环境搭建
python -m venv .venv
pip install -r requirements.txt
API 密钥（.env）
将 .env.example 复制为 .env。推荐双模型配置：
| 变量 | 用途 |
|---|
OPENAI_API_KEY | VLM 编译、定位器验证 |
OPENAI_BASE_URL | API 代理端点（如 aigc2d 代理 Gemini） |
PLANNER_MODEL | 编译模型（默认：gemini-3-flash-preview） |
AGENTS3_API_KEY | Agent-S3 执行引擎 |
AGENTS3_BASE_URL | Agent-S3 端点（如 DashScope） |
AGENTS3_MODEL | 执行模型（默认：kimi-k2.5） |
CLAUDE_API_KEY | 可选，仅在使用 Claude 作为 actor 后端时需要 |
优先级：.env > config.yaml > api_keys.json
单模型模式：只填 OPENAI_*，AGENTS3_* 留空即可。
模型配置（Aloha_Act/config/config.yaml）
planner_model: "gemini-3-flash-preview"
agents3:
model: "kimi-k2.5"
api_base: "https://coding.dashscope.aliyuncs.com/v1"
api_key: ""
os_name: "windows"
核心概念
- 轨迹（Trace）：记录每步 observation/think/action/expectation 的 JSON 文件
- 编译脚本（Compiled Script）：混合 RPA+Agent 脚本。RPA 步骤使用图像匹配（零 VLM 成本），Agent 步骤调用 VLM
- 自愈机制（Self-healing）：RPA 图像匹配失败时，自动回退到 Agent-S3
- 参数（Parameters）：编译脚本可包含可参数化变量（contact_name、message_text 等）
文件位置
| 路径 | 内容 |
|---|
Aloha_Learn/projects/{name}/ | 录制的演示项目 |
Aloha_Act/trace_data/ | 轨迹和编译脚本 |
Aloha_Act/agent_runs/{id}/ | 智能体执行日志 + 截图 |
Aloha_Act/config/config.yaml | 模型和系统配置 |
.env | API 密钥（项目根目录） |
常见问题排查
- API 密钥错误：检查项目根目录的
.env 文件
- 找不到轨迹：确认文件存在于
trace_data/（自动解析 {name}.json 或 {name}_trace.json）
- 坐标偏移：确认
selected_screen 与物理显示器布局匹配
- 解析器失败：确保
inputs/ 下恰好有一个日志文件 + 一个视频文件
参考资料
