turix-cua

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TuriX-CUA Skill

This skill enables OpenClaw to control macOS desktop visually using the TuriX Computer Use Agent (CUA). TuriX uses a multi-model architecture (Brain, Actor, Planner, Memory) to understand tasks, plan steps, and execute precise UI actions.

该Skill支持OpenClaw借助TuriX Computer Use Agent（CUA）可视化控制macOS桌面。TuriX采用多模型架构（Brain、Actor、Planner、Memory）来理解任务、规划步骤并执行精准的UI操作。

📋 When to Use

📋 适用场景

Use TuriX-CUA when:

Desktop GUI automation: "Open Spotify and play my liked songs"
Apps without CLI/API: Navigate applications that lack command-line interfaces
Multi-step visual workflows: "Find the latest invoice in my email and upload it to the company portal"
Complex UI interactions: Tasks requiring visual understanding and planning
Cross-app workflows: "Search iPhone price, create Pages document, and send to contact"

Do NOT use for:

Tasks that can be done via CLI (use
```
exec
```
instead)
Simple file operations (use file tools)
Web scraping (use
```
web_fetch
```
or
```
browser
```
tools)
Tasks requiring system-level permissions without warning

在以下场景中使用TuriX-CUA：

桌面GUI自动化："打开Spotify并播放我喜欢的歌曲"
无CLI/API的应用操作：操作不支持命令行界面的应用
多步骤可视化工作流："在我的邮箱中找到最新的发票并上传到公司门户"
复杂UI交互：需要视觉理解和规划的任务
跨应用工作流："搜索iPhone价格，创建Pages文档并发送给联系人"

请勿用于以下场景：

可通过CLI完成的任务（请使用
```
exec
```
替代）
简单文件操作（请使用文件工具）
网页爬虫（请使用
```
web_fetch
```
或
```
browser
```
工具）
未提前告知需要系统级权限的任务

🚀 Quick Start

🚀 快速开始

Prerequisites

前置要求

Install TuriX-CUA:

bash

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

Grant macOS Permissions:
- Accessibility: System Settings → Privacy & Security → Accessibility → Add Terminal/VSCode
- Safari Automation: Safari → Settings → Advanced → Show features for web developers
  - Develop menu → Allow Remote Automation
  - Develop menu → Allow JavaScript from Apple Events

Configure API in

examples/config.json

json

{
  "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"
  }
}

Or use Ollama (local models):

json

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

安装TuriX-CUA:

bash

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

授予macOS权限:
- 辅助功能权限: 系统设置 → 隐私与安全性 → 辅助功能 → 添加终端/VSCode
- Safari自动化权限: Safari → 设置 → 高级 → 显示Web开发人员功能
  - 开发菜单 → 允许远程自动化
  - 开发菜单 → 允许来自Apple事件的JavaScript

在
examples/config.json
中配置API:

json

{
  "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（本地模型）:

json

{
  "brain_llm": {
    "provider": "ollama",
    "model_name": "llama3.2-vision",
    "base_url": "http://localhost:11434"
  }
  // actor、memory、planner配置同上
}

Basic Usage

基础用法

bash

undefined

bash

undefined

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

undefined

skills/turix-cua/scripts/run_turix.sh --resume my-task-001

undefined

📁 File Structure

📁 文件结构

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)

skills/turix-cua/
├── SKILL.md              # 当前文件
├── README.md             # 详细文档
├── scripts/
│   └── run_turix.sh      # 主执行脚本
└── examples/
    └── config.json       # TuriX配置（由脚本管理）

⚙️ Configuration Options

⚙️ 配置选项

Option	Description	Default
`use_plan`	Enable planning for complex tasks	`false`
`use_skills`	Enable skill selection	`false`
`resume`	Resume from previous interruption	`false`
`agent_id`	Stable ID for task resumption	auto-generated
`max_steps`	Limit total steps	`100`
`max_actions_per_step`	Actions per step	`5`

选项	描述	默认值
`use_plan`	为复杂任务启用规划功能	`false`
`use_skills`	启用技能选择	`false`
`resume`	从之前的中断处恢复执行	`false`
`agent_id`	用于任务恢复的稳定ID	自动生成
`max_steps`	限制总步骤数	`100`
`max_actions_per_step`	每步最多执行的操作数	`5`

📋 Task Examples

📋 任务示例

✅ Good Tasks

✅ 合适的任务

Simple:

"Open Safari, go to google.com, search for 'TuriX AI', click first result"
"Open System Settings, click on Dark Mode, return to System Settings"
"Open Finder, navigate to Documents, create folder 'Project X'"

Complex (use
--use-plan
):

"Search iPhone 17 price on Apple store, create Pages document with findings, send to contact John"
"Open Discord, find message with Excel file from boss, download it, create chart in Numbers, insert to PowerPoint"
"Search AI news on 36kr and Huxiu, summarize top 5 stories, save to Word document"

简单任务:

"打开Safari，访问google.com，搜索'TuriX AI'，点击第一个搜索结果"
"打开系统设置，点击深色模式，返回系统设置"
"打开访达，进入文档目录，创建文件夹'Project X'"

复杂任务（需使用
--use-plan
）:

"在苹果商店搜索iPhone 17价格，将结果整理到Pages文档，发送给联系人John"
"打开Discord，找到老板发的带Excel文件的消息，下载文件，在Numbers中创建图表，插入到PowerPoint"
"在36氪和虎嗅上搜索AI新闻，总结排名前5的报道，保存到Word文档"

❌ Avoid

❌ 应避免的任务

Vague: "Help me" or "Fix this"
Impossible: "Delete all files"
Without context: "Do it" (unclear what "it" is)
System-level: "Install software" (requires permissions)

模糊描述："帮我"或"修复这个问题"
不可行任务："删除所有文件"
无上下文："做这个"（不清楚"这个"指代什么）
系统级操作："安装软件"（需要额外权限）

🔧 Script Usage

🔧 脚本用法

run_turix.sh

bash

undefined

bash

undefined

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

设置自定义agent ID

./run_turix.sh "Task" --agent-id custom-id-123


**Options:**
- `--use-plan`: Enable planning (for complex multi-step tasks)
- `--use-skills`: Enable skill selection
- `--background`: Run in background (non-blocking)
- `--agent-id <id>`: Set custom agent ID for resumption
- `--resume`: Resume interrupted task

./run_turix.sh "Task" --agent-id custom-id-123


**参数说明:**
- `--use-plan`: 启用规划功能（适用于复杂多步骤任务）
- `--use-skills`: 启用技能选择
- `--background`: 后台运行（非阻塞）
- `--agent-id <id>`: 设置用于恢复任务的自定义agent ID
- `--resume`: 恢复被中断的任务

How It Works

工作原理

The script:

Updates
```
examples/config.json
```
with task and options
Sets PATH correctly (includes
```
/usr/sbin
```
for
```
screencapture
```
)
Activates conda environment
Runs TuriX agent
Handles UTF-8/Chinese text correctly via Python

脚本会执行以下操作：

使用任务和参数更新
```
examples/config.json
```
正确设置PATH（包含
```
/usr/sbin
```
以支持
```
screencapture
```
）
激活conda环境
运行TuriX agent
通过Python正确处理UTF-8/中文文本

📊 Monitoring & Debugging

📊 监控与调试

Check Status

查看状态

bash

undefined

bash

undefined

Check if TuriX is running

检查TuriX是否正在运行

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

undefined

ls -lt TuriX-CUA/examples/.turix_tmp/brain_llm_interactions.log_brain_*.txt

undefined

Log Files

日志文件

File	Description
`.turix_tmp/logging.log`	Main execution log
`brain_llm_interactions.log_brain_N.txt`	Brain reasoning for step N
`actor_llm_interactions.log_actor_N.txt`	Actor actions for step N

文件	描述
`.turix_tmp/logging.log`	主执行日志
`brain_llm_interactions.log_brain_N.txt`	第N步的Brain推理日志
`actor_llm_interactions.log_actor_N.txt`	第N步的Actor操作日志

Key Log Markers

关键日志标记

```
📍 Step N
```
- New step started
```
✅ Eval: Success/Failed
```
- Step evaluation
```
🎯 Goal to achieve this step
```
- Current goal
```
🛠️ Action
```
- Executed action
```
✅ Task completed successfully
```
- Task done

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

Force Stop

强制停止

Hotkey:

Cmd+Shift+2

(in the running terminal)

Command:

bash

pkill -f "python examples/main.py"

快捷键:

Cmd+Shift+2

（在运行脚本的终端中使用）

命令:

bash

pkill -f "python examples/main.py"

🧩 Skills System

🧩 技能系统

TuriX supports Skills: markdown playbooks for specific domains.

TuriX支持Skills：针对特定领域的Markdown操作手册。

Built-in Skills

内置技能

```
github-web-actions
```
: GitHub navigation, repo search, starring
```
browser-tasks
```
: General web browser operations

```
github-web-actions
```
：GitHub导航、仓库搜索、点赞
```
browser-tasks
```
：通用网页浏览器操作

Create Custom Skill

创建自定义技能

Create

.md

file in

TuriX-CUA/skills/

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

在

TuriX-CUA/skills/

目录下创建

.md

文件：

---
name: my-skill-name
description: 该技能的适用场景（Planner会匹配该描述）
---

Skill Instructions

技能说明

Guidelines

操作指南

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

步骤1：先执行该操作
步骤2：然后执行该操作
步骤3：验证结果

Safety

安全说明

Confirm before important actions

undefined

执行重要操作前需确认

undefined

Enable Skills

启用技能

examples/config.json

json

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

在

examples/config.json

中配置：

json

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

📝 Best Practices

📝 最佳实践

1. Workflow Design

1. 工作流设计

Recommended pattern:

Use
```
web_fetch
```
to gather information
Use Python to create documents (faster, more reliable)
Use TuriX only for GUI tasks it excels at (sending files, app navigation)

Example:

python

undefined

推荐模式:

使用
```
web_fetch
```
收集信息
使用Python创建文档（速度更快、更可靠）
仅将TuriX用于它擅长的GUI任务（发送文件、应用导航）

示例:

python

undefined

1. Fetch news (OpenClaw)

1. 获取新闻（OpenClaw）

news = web_fetch("https://36kr.com")

2. Create Word doc (OpenClaw)

2. 创建Word文档（OpenClaw）

doc = Document() doc.add_heading('AI News') doc.save('news.docx')

3. Send via Messages (TuriX)

3. 通过信息发送（TuriX）

run_turix.sh "Open Messages, send news.docx to contact John"

undefined

run_turix.sh "Open Messages, send news.docx to contact John"

undefined

2. Task Instructions

2. 任务说明编写规范

Be specific:

✅ "Open Safari, go to google.com, search 'AI news'"
❌ "Search the web"

Break down complex tasks:

✅ "Open Finder, go to Documents, create folder 'Projects'"
❌ "Organize my files"

Don't mention coordinates:

✅ "Click the Settings button"
❌ "Click at x=100, y=200"

尽可能具体:

✅ "打开Safari，访问google.com，搜索'AI news'"
❌ "搜索网页"

拆分复杂任务:

✅ "打开访达，进入文档目录，创建文件夹'Projects'"
❌ "整理我的文件"

不要提及坐标:

✅ "点击设置按钮"
❌ "点击x=100, y=200的位置"

3. Performance Tips

3. 性能优化建议

First run: 2-5 minutes to load AI models
Subsequent runs: Much faster (models cached)
Complex tasks: Use
```
--use-plan
```
for better success rate
Long tasks: Use
```
--background
```
and monitor logs

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

4. Chinese Text Support

4. 中文文本支持

The script handles UTF-8 correctly:

Uses Python for config updates (not shell interpolation)
Reads/writes with
```
encoding='utf-8'
```
Uses
```
ensure_ascii=False
```
in JSON

脚本会正确处理UTF-8编码：

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

⚠️ Troubleshooting

⚠️ 问题排查

Error	Solution
`NoneType has no attribute 'save'`	Grant Screen Recording permission
`Screen recording access denied`	Run Safari trigger command, click Allow
`Conda environment not found`	`conda create -n turix_env python=3.12`
Module import errors	`conda activate turix_env && pip install -r requirements.txt`
Keyboard listener errors	Add Terminal to Accessibility permissions
Task stuck on step 1	Check `.turix_tmp/` directory exists
No log output	Check `config.json` logging_level

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

🔐 Security Notes

🔐 安全说明

TuriX runs locally - no data sent externally (unless using cloud APIs)
Grant minimal permissions needed
Review tasks before execution
Use
```
--background
```
for long-running tasks with monitoring

TuriX在本地运行 - 不会向外发送数据（除非使用云API）
仅授予所需的最小权限
执行任务前请确认任务内容
长耗时任务使用
```
--background
```
运行并做好监控

📚 Resources

📚 相关资源

GitHub: https://github.com/TurixAI/TuriX-CUA
ClawHub: https://clawhub.ai/Tongyu-Yan/turix-cua
Discord: https://discord.gg/yaYrNAckb5
Website: https://turix.ai
API Platform: https://turixapi.io

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

🎯 Example OpenClaw Integration

🎯 OpenClaw集成示例

python

undefined

python

undefined

In OpenClaw skill or workflow:

在OpenClaw skill或工作流中使用：

1. Simple task

1. 简单任务

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

2. Complex task with planning

2. 带规划的复杂任务

exec('skills/turix-cua/scripts/run_turix.sh "Search AI news and summarize" --use-plan')

3. Monitor progress

3. 监控进度

exec('tail -f TuriX-CUA/.turix_tmp/logging.log')

4. Check completion

4. 检查执行状态

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


---

**Version**: 1.0.0  
**Last Updated**: 2026-02-23  
**Compatibility**: OpenClaw + TuriX-CUA v0.3+  
**Platform**: macOS 15+

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


---

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