turix-cua

TuriX-CUA 技能

此技能可让 OpenClaw 使用 TuriX Computer Use Agent（CUA）以视觉方式控制 macOS 桌面。TuriX 采用多模型架构（Brain、Actor、Planner、Memory），以理解任务、规划步骤并执行精准的 UI 操作。

📋 适用场景

以下情况可使用 TuriX-CUA：

• 桌面 GUI 自动化：“打开 Spotify 并播放我点赞的歌曲”
• 没有 CLI/API 的应用：浏览缺少命令行界面的应用
• 多步骤视觉工作流：“在我的邮件中找到最新发票并上传到公司门户”
• 复杂 UI 交互：需要视觉理解和规划的任务
• 跨应用工作流：“搜索 iPhone 价格，创建 Pages 文档并发送给联系人”

请勿用于：

• 可通过 CLI 完成的任务（请改用 exec）
• 简单文件操作（请使用文件工具）
• 网页抓取（请使用 web_fetch 或 browser 工具）
• 未经警告就需要系统级权限的任务

🚀 快速开始

前提条件

1. 安装 TuriX-CUA：

   git clone https://github.com/TurixAI/TuriX-CUA.git
   cd TuriX-CUA
   conda create -n turix_env python=3.12
   conda activate turix_env
   pip install -r requirements.txt
   

2. 授予 macOS 权限：

   • 辅助功能：系统设置 → 隐私与安全性 → 辅助功能 → 添加 Terminal/VSCode
   • Safari 自动化：Safari → 设置 → 高级 → 显示网页开发者功能
     • Develop 菜单 → 允许远程自动化
     • Develop 菜单 → 允许来自 Apple Events 的 JavaScript

3. 在 examples/config.json 中配置 API：

   {
     "brain_llm": {
       "provider": "turix",
       "model_name": "turix-brain-model",
       "api_key": "YOUR_API_KEY",
       "base_url": "https://llm.turixapi.io/v1"
     },
     "actor_llm": {
       "provider": "turix",
       "model_name": "turix-actor-model",
       "api_key": "YOUR_API_KEY",
       "base_url": "https://llm.turixapi.io/v1"
     },
     "memory_llm": {
       "provider": "turix",
       "model_name": "turix-memory-model",
       "api_key": "YOUR_API_KEY",
       "base_url": "https://llm.turixapi.io/v1"
     },
     "planner_llm": {
       "provider": "turix",
       "model_name": "turix-planner-model",
       "api_key": "YOUR_API_KEY",
       "base_url": "https://llm.turixapi.io/v1"
     }
   }
   

   或使用 Ollama（本地模型）：

   {
     "brain_llm": {
       "provider": "ollama",
       "model_name": "llama3.2-vision",
       "base_url": "http://localhost:11434"
     }
     // ... same for actor, memory, planner
   }
   

基本用法

# Run a simple task
skills/turix-cua/scripts/run_turix.sh "Open Chrome and go to github.com"

# Run with planning enabled (for complex tasks)
skills/turix-cua/scripts/run_turix.sh "Search AI news and create summary" --use-plan

# Resume an interrupted task
skills/turix-cua/scripts/run_turix.sh --resume my-task-001

📁 文件结构

skills/turix-cua/
├── SKILL.md              # This file
├── README.md             # Detailed documentation
├── scripts/
│   └── run_turix.sh      # Main execution script
└── examples/
    └── config.json       # TuriX configuration (managed by script)

⚙️ 配置选项

选项	说明	默认值
use_plan	为复杂任务启用规划	false
use_skills	启用技能选择	false
resume	从之前中断处继续	false
agent_id	用于恢复任务的稳定 ID	自动生成
max_steps	限制总步骤数	100
max_actions_per_step	每个步骤的操作数	5

📋 任务示例

✅ 合适的任务

简单任务：

• “打开 Safari，访问 google.com，搜索 ‘TuriX AI’，点击第一个结果”
• “打开系统设置，点击深色模式，再返回系统设置”
• “打开 Finder，导航到 Documents，创建名为 ‘Project X’ 的文件夹”

复杂任务（使用 --use-plan）：

• “在 Apple Store 搜索 iPhone 17 的价格，创建包含搜索结果的 Pages 文档，并发送给联系人 John”
• “打开 Discord，找到老板发来的 Excel 文件消息并下载，在 Numbers 中创建图表，然后插入 PowerPoint”
• “在 36kr 和 Huxiu 搜索 AI 新闻，总结最热门的 5 条新闻，并保存到 Word 文档”

❌ 避免的任务

• 含糊不清：“帮帮我”或“修好这个”
• 不可能完成：“删除所有文件”
• 缺少上下文：“去做吧”（不清楚“它”指什么）
• 系统级任务：“安装软件”（需要权限）

🔧 脚本用法

run_turix.sh

# Basic usage
./run_turix.sh "Your task description"

# With options
./run_turix.sh "Task" --use-plan --use-skills --background

# Resume task
./run_turix.sh --resume my-task-001

# Set custom agent ID
./run_turix.sh "Task" --agent-id custom-id-123

选项：

• --use-plan：启用规划（适用于复杂的多步骤任务）
• --use-skills：启用技能选择
• --background：在后台运行（非阻塞）
• --agent-id <id>：设置自定义 Agent ID，以便恢复任务
• --resume：恢复中断的任务

工作原理

该脚本会：

1. 使用任务和选项更新 examples/config.json
2. 正确设置 PATH（包含 /usr/sbin，以便使用 screencapture）
3. 激活 conda 环境
4. 运行 TuriX Agent
5. 通过 Python 正确处理 UTF-8/中文文本

📊 监控与调试

检查状态

# Check if TuriX is running
ps aux | grep "python.*main.py" | grep -v grep

# View logs
tail -f TuriX-CUA/.turix_tmp/logging.log

# List step files
ls -lt TuriX-CUA/examples/.turix_tmp/brain_llm_interactions.log_brain_*.txt

日志文件

文件	说明
.turix_tmp/logging.log	主执行日志
brain_llm_interactions.log_brain_N.txt	第 N 步的 Brain 推理记录
actor_llm_interactions.log_actor_N.txt	第 N 步的 Actor 操作记录

关键日志标记

• 📍 Step N - 新步骤已开始
• ✅ Eval: Success/Failed - 步骤评估
• 🎯 Goal to achieve this step - 当前目标
• 🛠️ Action - 已执行操作
• ✅ Task completed successfully - 任务已完成

强制停止

快捷键：Cmd+Shift+2（在运行中的终端内）

命令：

pkill -f "python examples/main.py"

🧩 技能系统

TuriX 支持 技能：用于特定领域的 Markdown 操作指南。

内置技能

• github-web-actions：GitHub 导航、仓库搜索、加星标
• browser-tasks：常规网页浏览器操作

创建自定义技能

在 TuriX-CUA/skills/ 中创建 .md 文件：

---
name: my-skill-name
description: When to use this skill (Planner matches on this)
---
# Skill Instructions

## Guidelines
- Step 1: Do this first
- Step 2: Then do that
- Step 3: Verify result

## Safety
- Confirm before important actions

启用技能

在 examples/config.json 中：

{
  "agent": {
    "use_plan": true,
    "use_skills": true,
    "skills_dir": "skills",
    "skills_max_chars": 4000
  }
}

📝 最佳实践

1. 工作流设计

推荐模式：

1. 使用 web_fetch 收集信息
2. 使用 Python 创建文档（更快、更可靠）
3. 仅在擅长的 GUI 任务中使用 TuriX（发送文件、应用导航）

示例：

# 1. Fetch news (OpenClaw)
news = web_fetch("https://36kr.com")

# 2. Create Word doc (OpenClaw)
doc = Document()
doc.add_heading('AI News')
doc.save('news.docx')

# 3. Send via Messages (TuriX)
run_turix.sh "Open Messages, send news.docx to contact John"

2. 任务说明

具体明确：

• ✅ “打开 Safari，访问 google.com，搜索‘AI 新闻’”
• ❌ “搜索网络”

将复杂任务拆分：

• ✅ “打开 Finder，进入 Documents，创建文件夹‘Projects’”
• ❌ “整理我的文件”

不要提及坐标：

• ✅ “点击 Settings 按钮”
• ❌ “点击 x=100，y=200 处”

3. 性能提示

• 首次运行：加载 AI 模型需要 2-5 分钟
• 后续运行：速度会快得多（模型已缓存）
• 复杂任务：使用 --use-plan 提高成功率
• 长时间任务：使用 --background 并监控日志

4. 中文文本支持

该脚本可正确处理 UTF-8：

• 使用 Python 更新配置（而非 Shell 插值）
• 使用 encoding='utf-8' 读写
• 在 JSON 中使用 ensure_ascii=False

⚠️ 故障排除

错误	解决方案
NoneType has no attribute 'save'	授予屏幕录制权限
Screen recording access denied	运行 Safari 触发命令，然后点击 Allow
Conda environment not found	conda create -n turix_env python=3.12
模块导入错误	conda activate turix_env && pip install -r requirements.txt
键盘监听器错误	在辅助功能权限中添加 Terminal
任务卡在第 1 步	检查 .turix_tmp/ 目录是否存在
没有日志输出	检查 config.json 中的 logging_level

🔐 安全说明

• TuriX 在本地运行，不会向外部发送数据（使用云 API 时除外）
• 仅授予所需的最低权限
• 执行前检查任务
• 对于长时间运行的任务，使用 --background 并进行监控

📚 资源

• GitHub：https://github.com/TurixAI/TuriX-CUA
• ClawHub：https://clawhub.ai/Tongyu-Yan/turix-cua
• Discord：https://discord.gg/yaYrNAckb5
• 网站：https://turix.ai
• API 平台：https://turixapi.io

🎯 OpenClaw 集成示例

# In OpenClaw skill or workflow:

# 1. Simple task
exec('skills/turix-cua/scripts/run_turix.sh "Open Safari"')

# 2. Complex task with planning
exec('skills/turix-cua/scripts/run_turix.sh "Search AI news and summarize" --use-plan')

# 3. Monitor progress
exec('tail -f TuriX-CUA/.turix_tmp/logging.log')

# 4. Check completion
exec('ps aux | grep "python.*main.py" | grep -v grep')

---

版本：1.0.0
最后更新：2026-02-23
兼容性：OpenClaw + TuriX-CUA v0.3+
平台：macOS 15+