turix-mac

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TuriX-Mac Skill

TuriX-Mac 技能

This skill allows Clawdbot to control the macOS desktop visually using the TuriX Computer Use Agent.

该技能允许Clawdbot通过TuriX计算机使用代理（Computer Use Agent）可视化控制macOS桌面。

When to Use

适用场景

When asked to perform actions on the Mac desktop (e.g., "Open Spotify and play my liked songs").
When navigating applications that lack command-line interfaces.
For multi-step visual workflows (e.g., "Find the latest invoice in my email and upload it to the company portal").
When you need the agent to plan, reason, and execute complex tasks autonomously.

当被要求在Mac桌面执行操作时（例如"Open Spotify and play my liked songs"）。
当操作没有命令行界面的应用程序时。
用于多步骤可视化工作流（例如"Find the latest invoice in my email and upload it to the company portal"）。
当你需要代理自主规划、推理并执行复杂任务时。

Key Features

核心功能

🤖 Multi-Model Architecture

🤖 多模型架构

TuriX uses a sophisticated multi-model system:

Brain: Understands the task and generates step-by-step plans
Actor: Executes precise UI actions based on visual understanding
Planner: Coordinates high-level task decomposition (when
```
use_plan: true
```
)
Memory: Maintains context across task steps

TuriX采用成熟的多模型系统：

Brain：理解任务并生成分步执行计划
Actor：基于视觉理解执行精准的UI操作
Planner：当
```
use_plan: true
```
时，协调高层任务拆解
Memory：在多个任务步骤间维护上下文信息

📋 Skills System

📋 技能系统

Skills are markdown playbooks that guide the agent for specific domains:

```
github-web-actions
```
: GitHub navigation, repo search, starring
```
browser-tasks
```
: General web browser operations
Custom skills can be added to the
```
skills/
```
directory

技能是指导代理在特定领域执行任务的Markdown操作手册：

```
github-web-actions
```
：GitHub导航、仓库搜索、点赞操作
```
browser-tasks
```
：通用网页浏览器操作
可在
```
skills/
```
目录下添加自定义技能

🔄 Resume Capability

🔄 断点续跑能力

The agent can resume interrupted tasks by setting a stable

agent_id

通过设置稳定的

agent_id

，代理可以恢复被中断的任务。

Running TuriX

运行TuriX

Basic Task

基础任务

bash

skills/local/turix-mac/scripts/run_turix.sh "Open Chrome and go to github.com"

bash

skills/local/turix-mac/scripts/run_turix.sh "Open Chrome and go to github.com"

Resume Interrupted Task

恢复中断的任务

bash

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

✅ Note:
run_turix.sh
updates
examples/config.json
for you (task, resume,
use_plan
,
use_skills
). If you want to keep a hand-edited config, skip passing a task and edit
examples/config.json
directly.

bash

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

✅ 注意：
run_turix.sh
会自动为你更新
examples/config.json
（任务、续跑、
use_plan
、
use_skills
）。如果你想保留手动编辑的配置，不要传入任务参数，直接编辑
examples/config.json
即可。

Tips for Effective Tasks

高效提交任务的提示

✅ Good Examples:

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

❌ Avoid:

Vague instructions: "Help me" or "Fix this"
Impossible actions: "Delete all files"
Tasks requiring system-level permissions without warning

💡 Best Practices:

Be specific about the target application
Break complex tasks into clear steps, but do not mention the precise coordinates on the screen.

✅ 优秀示例：

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

❌ 禁止提交：

模糊指令："Help me" 或 "Fix this"
不可执行的操作："Delete all files"
未提前告知需要系统级权限的任务

💡 最佳实践：

明确指定目标应用程序
将复杂任务拆分为清晰的步骤，但不要提及屏幕上的精确坐标。

Hotkeys

快捷键

Force Stop:
```
Cmd+Shift+2
```
- Immediately stops the agent

强制停止：
```
Cmd+Shift+2
```
- 立即停止代理

Monitoring & Logs

监控与日志

Logs are saved to

.turix_tmp/logging.log

in the project directory. Check this for:

Step-by-step execution details
LLM interactions and reasoning
Errors and recovery attempts

日志保存在项目目录下的

.turix_tmp/logging.log

中，可查看以下内容：

分步执行详情
LLM交互与推理过程
错误与恢复尝试

Important Notes

重要注意事项

How TuriX Runs

TuriX运行方式

TuriX can be started via clawdbot
```
exec
```
with
```
pty:true
```
mode
The first launch takes 2-5 minutes to load all AI models (Brain, Actor, Planner, Memory)
Background output is buffered - you won't see live progress until task completes or stops

可通过Clawdbot的
```
exec
```
命令以
```
pty:true
```
模式启动TuriX
首次启动需要2-5分钟加载所有AI模型（Brain、Actor、Planner、Memory）
后台输出是缓冲的，在任务完成或停止前你不会看到实时进度

Before Running

运行前准备

Always set PATH first:

bash

export PATH="/usr/sbin:$PATH"
cd your_dir/TuriX-CUA
/opt/anaconda3/envs/turix_env/bin/python examples/main.py

Why? The

screencapture

tool is located at

/usr/sbin/screencapture

, which is not in the default PATH.

始终先设置PATH：

bash

export PATH="/usr/sbin:$PATH"
cd your_dir/TuriX-CUA
/opt/anaconda3/envs/turix_env/bin/python examples/main.py

为什么？

screencapture

工具位于

/usr/sbin/screencapture

，该路径不在默认PATH中。

Checking if TuriX is Running

检查TuriX是否正在运行

bash

undefined

bash

undefined

Check process

检查进程

ps aux | grep "python.*main" | grep -v grep

Should show something like:

应该输出类似内容：

user 57425 0.0 2.4 412396704 600496 s143 Ss+ 5:56PM 0:04.76 /opt/anaconda3/envs/turix_env/bin/python examples/main.py


**Note:** The `.turix_tmp` directory may not be created until TuriX starts executing steps.


**注意：** `.turix_tmp`目录可能要等到TuriX开始执行步骤后才会创建。

Troubleshooting

问题排查

Common Issues

常见问题

Error	Solution
`NoneType has no attribute 'save'`	Screen recording permission missing. Grant in System Settings and restart Terminal.
`Screen recording access denied`	Run: `osascript -e 'tell application "Safari" to do JavaScript "alert(1)"'` and click Allow
`Conda environment not found`	Ensure `turix_env` exists: `conda create -n turix_env python=3.12`
Module import errors	Activate environment: `conda activate turix_env` then `pip install -r requirements.txt`
Permission errors for keyboard listener	Add Terminal/IDE to Accessibility permissions

报错	解决方案
`NoneType has no attribute 'save'`	缺少屏幕录制权限。在系统设置中授予权限后重启终端即可。
`Screen recording access denied`	执行： `osascript -e 'tell application "Safari" to do JavaScript "alert(1)"'` 然后点击允许
`Conda environment not found`	确认 `turix_env` 存在： `conda create -n turix_env python=3.12`
Module import errors	激活环境： `conda activate turix_env` 然后执行 `pip install -r requirements.txt`
Permission errors for keyboard listener	将终端/IDE添加到辅助功能权限列表

Debug Mode

调试模式

Logs include DEBUG level by default. Check:

bash

tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log

日志默认包含DEBUG级别，可执行以下命令查看：

bash

tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log

Architecture

架构

User Request
     ↓
[Clawdbot] → [TuriX Skill] → [run_turix.sh] → [TuriX Agent]
                                              ↓
                    ┌─────────────────────────┼─────────────────────────┐
                    ↓                         ↓                         ↓
               [Planner]                 [Brain]                  [Memory]
                    ↓                         ↓                         ↓
                                         [Actor] ───→ [Controller] ───→ [macOS UI]

User Request
     ↓
[Clawdbot] → [TuriX Skill] → [run_turix.sh] → [TuriX Agent]
                                              ↓
                    ┌─────────────────────────┼─────────────────────────┐
                    ↓                         ↓                         ↓
               [Planner]                 [Brain]                  [Memory]
                    ↓                         ↓                         ↓
                                         [Actor] ───→ [Controller] ───→ [macOS UI]

Skill System Details

技能系统详情

Skills are markdown files with YAML frontmatter in the

skills/

directory:

---
name: skill-name
description: When to use this skill
---

技能是

skills/

目录下带有YAML前置元数据的Markdown文件：

---
name: skill-name
description: When to use this skill
---

Skill Instructions

High-level workflow like: Open Safari,then go to Google.


The Planner selects relevant skills based on name/description; the Brain uses full content for step guidance.

High-level workflow like: Open Safari,then go to Google.


Planner会根据名称/描述选择相关技能；Brain会使用完整内容作为步骤指导。

Advanced Options

高级选项

Option	Description
`use_plan: true`	Enable planning for complex tasks
`use_skills: true`	Enable skill selection
`resume: true`	Resume from previous interruption
`max_steps: N`	Limit total steps (default: 100)
`max_actions_per_step: N`	Actions per step (default: 5)
`force_stop_hotkey`	Custom hotkey to stop agent

选项	描述
`use_plan: true`	为复杂任务启用规划能力
`use_skills: true`	启用技能选择
`resume: true`	从之前的中断处恢复执行
`max_steps: N`	限制总步骤数（默认：100）
`max_actions_per_step: N`	单步最多执行动作数（默认：5）
`force_stop_hotkey`	自定义停止代理的快捷键

TuriX Skills System

TuriX技能系统

TuriX supports Skills: markdown playbooks that help the agent behave more reliably in specific domains.

TuriX支持技能：帮助代理在特定领域更可靠执行任务的Markdown操作手册。

1. Built-in Skills

1. 内置技能

Skill	Use
`github-web-actions`	GitHub web actions (search repos, star, etc.)

技能	用途
`github-web-actions`	GitHub网页操作（搜索仓库、点赞等）

2. Create a Custom Skill

2. 创建自定义技能

Create a

.md

file in the TuriX project's

skills/

directory:

---
name: my-custom-skill
description: When performing X specific task
---

在TuriX项目的

skills/

目录下创建

.md

文件：

---
name: my-custom-skill
description: When performing X specific task
---

Custom Skill

Guidelines

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


**Field definitions:**
- `name`: Skill identifier (used by the Planner to select)
- `description`: When to use this skill (Planner matches on this)
- The body below: Full execution guide (used by the Brain)

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


**字段定义：**
- `name`：技能标识符（Planner用于选择技能）
- `description`：技能适用场景（Planner基于该字段匹配）
- 下方正文：完整执行指南（供Brain使用）

3. Enable Skills

3. 启用技能

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

4. Run a Task with Skills

4. 带技能执行任务

bash

skills/local/turix-mac/scripts/run_turix.sh "Search for turix-cua on GitHub and star it"

The agent will automatically:

Planner reads the skill name and description
Selects relevant skills
Brain uses the full skill content to guide execution

bash

skills/local/turix-mac/scripts/run_turix.sh "Search for turix-cua on GitHub and star it"

代理会自动执行以下步骤：

Planner读取技能名称和描述
选择相关技能
Brain使用完整技能内容指导执行

5. Chinese Text Support

5. 中文文本支持

Background: Passing Chinese text through shell interpolation can mangle UTF-8, and interpolating untrusted text into a heredoc is unsafe.

Solution: The

run_turix.sh

script uses Python to handle UTF-8 correctly and reads task text from environment variables:

python

import json

背景： 通过Shell插值传递中文文本可能会破坏UTF-8编码，且将不可信文本插值到heredoc中存在安全风险。

解决方案：

run_turix.sh

脚本使用Python正确处理UTF-8编码，并从环境变量读取任务文本：

python

import json

Read with UTF-8

以UTF-8读取

with open(config_path, 'r', encoding='utf-8') as f: data = json.load(f)

Write without escaping non-ASCII text

写入时不转义非ASCII文本

with open(config_path, 'w', encoding='utf-8') as f: json.dump(data, f, indent=2, ensure_ascii=False)


**Key points:**
1. Always use `encoding='utf-8'` when reading/writing files
2. Use `ensure_ascii=False` to preserve non-ASCII text
3. Pass task content via environment variables or stdin, and use a single-quoted heredoc to avoid shell interpolation

with open(config_path, 'w', encoding='utf-8') as f: json.dump(data, f, indent=2, ensure_ascii=False)


**核心要点：**
1. 读写文件时始终指定`encoding='utf-8'`
2. 使用`ensure_ascii=False`保留非ASCII文本
3. 通过环境变量或stdin传递任务内容，使用单引号heredoc避免Shell插值

6. Document Creation Best Practices

6. 文档创建最佳实践

Challenges:

Asking TuriX to collect news, then create and send a document directly
TuriX is a GUI agent, so it can be slow and less deterministic. Prefer using TuriX only for tasks Clawdbot cannot do or where TuriX is faster.

Recommended approach: create the document yourself and let TuriX only send it

Create the Word document with python-docx
Let TuriX only send the file

python

from docx import Document
doc = Document()
doc.add_heading('Title')
doc.save('/path/to/file.docx')

Suggested workflow:

Use
```
web_fetch
```
to gather information
Use Python to create the Word document
Use TuriX to send the file. Specify the file path and say to send the file, not just the file name.
If you really need TuriX to manually create a Word document and type in collected information, put the content in turix skills (for large amounts) or in the task name (for small amounts).

挑战：

要求TuriX收集新闻，然后直接创建并发送文档
TuriX是GUI代理，执行速度较慢且确定性较低。建议仅在Clawdbot无法完成或TuriX执行速度更快的场景下使用TuriX。

推荐方案：自行创建文档，仅让TuriX执行发送操作

使用python-docx创建Word文档
仅让TuriX发送文件

python

from docx import Document
doc = Document()
doc.add_heading('Title')
doc.save('/path/to/file.docx')

建议工作流：

使用
```
web_fetch
```
收集信息
使用Python创建Word文档
使用TuriX发送文件。指定文件路径，明确要求发送文件，而不仅仅是文件名。
如果你确实需要TuriX手动创建Word文档并输入收集的信息，将内容放在TuriX技能中（内容量大时）或任务名称中（内容量小时）。

7. Example: Add a New Skill

7. 示例：添加新技能

Create

skills/browser-tasks.md

---
name: browser-tasks
description: When performing tasks in a web browser (search, navigate, fill forms).
---

创建

skills/browser-tasks.md

：

---
name: browser-tasks
description: When performing tasks in a web browser (search, navigate, fill forms).
---

Browser Tasks

Navigation

Use the address bar or search box to navigate
Open new tabs for each distinct task
Wait for page to fully load before proceeding

Use the address bar or search box to navigate
Open new tabs for each distinct task
Wait for page to fully load before proceeding

Forms

Click on input fields to focus
Type content clearly
Look for submit/button to complete actions

Click on input fields to focus
Type content clearly
Look for submit/button to complete actions

Safety

Confirm before submitting forms
Do not download files without user permission

undefined

Confirm before submitting forms
Do not download files without user permission

undefined

8. Skill Development Tips

8. 技能开发提示

Be precise in the description - helps the Planner select correctly
Make steps clear - the Brain needs explicit guidance
Include safety checks - confirmations for important actions
Keep it concise - recommended under 4000 characters

描述要精准 - 帮助Planner正确选择
步骤要清晰 - Brain需要明确的指导
包含安全检查 - 重要操作需确认
保持简洁 - 建议不超过4000字符

Monitoring and Debugging Guide

监控与调试指南

1. Run a Task

1. 执行任务

bash

undefined

bash

undefined

Run in background (recommended)

后台运行（推荐）

cd your_dir/clawd/skills/local/turix-mac/scripts ./run_turix.sh "Your task description" --background

Or use timeout to set a max runtime

或使用timeout设置最大运行时间

./run_turix.sh "Task" &

undefined

./run_turix.sh "Task" &

undefined

2. Monitor Progress

2. 监控进度

Method 1: Session logs

bash

undefined

方法1：会话日志

bash

undefined

List running sessions

列出运行中的会话

clawdbot sessions_list

View history

查看历史记录

clawdbot sessions_history <session_key>


**Method 2: TuriX logs**
```bash

clawdbot sessions_history <session_key>


**方法2：TuriX日志**
```bash

Tail logs in real time

实时查看日志

tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log

Or inspect completed step files

或查看已完成的步骤文件

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


**Method 3: Check processes**
```bash
ps aux | grep "python.*main.py" | grep -v grep

Method 4: Check generated files

bash

undefined

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


**方法3：检查进程**
```bash
ps aux | grep "python.*main.py" | grep -v grep

方法4：检查生成文件

bash

undefined

List files created by the agent

列出代理创建的文件

ls -la your_dir/TuriX-CUA/examples/.turix_tmp/*.txt

undefined

ls -la your_dir/TuriX-CUA/examples/.turix_tmp/*.txt

undefined

3. Log File Reference

3. 日志文件说明

File	Description
`logging.log`	Main log file
`brain_llm_interactions.log_brain_N.txt`	Brain model conversations (one per step)
`actor_llm_interactions.log_actor_N.txt`	Actor model conversations (one per step)

Key log markers:

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

文件	描述
`logging.log`	主日志文件
`brain_llm_interactions.log_brain_N.txt`	Brain模型对话记录（每步一个文件）
`actor_llm_interactions.log_actor_N.txt`	Actor模型对话记录（每步一个文件）

关键日志标记：

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

4. Common Monitoring Issues

4. 常见监控问题

Issue	Check
Process unresponsive	`ps aux
Stuck on step 1	Check whether `.turix_tmp/` was created
Model loading is slow	First run can take 1-2 minutes to load models
No log output	Check `config.json` `logging_level`

问题	检查项
进程无响应	`ps aux
卡在步骤1	检查 `.turix_tmp/` 目录是否已创建
模型加载慢	首次运行可能需要1-2分钟加载模型
无日志输出	检查 `config.json` 中的 `logging_level` 配置

5. Force Stop

5. 强制停止

Hotkey:

Cmd+Shift+2

- stop the agent immediately

Command:

bash

pkill -f "python examples/main.py"

快捷键：

Cmd+Shift+2

- 立即停止代理

命令：

bash

pkill -f "python examples/main.py"

6. View Results

6. 查看结果

After completion, the agent will:

Create interaction logs in
```
.turix_tmp/
```
Create record files (if
```
record_info
```
is used)
Keep screenshots in memory for subsequent steps

Example: view a summary file

bash

cat your_dir/TuriX-CUA/examples/.turix_tmp/latest_ai_news_summary_jan2026.txt

任务完成后，代理会：

在
```
.turix_tmp/
```
目录下生成交互日志
生成记录文件（如果使用了
```
record_info
```
）
在内存中保留截图供后续步骤使用

示例：查看摘要文件

bash

cat your_dir/TuriX-CUA/examples/.turix_tmp/latest_ai_news_summary_jan2026.txt

7. Debugging Tips

7. 调试提示

Inspect Brain reasoning: check

brain_llm_interactions.log_brain_*.txt

for

analysis

and

next_goal

Inspect Actor actions: check
```
actor_llm_interactions.log_actor_*.txt
```
for actions
Check screenshots: TuriX captures a screenshot each step (kept in memory)
Read record files: the agent uses
```
record_info
```
to save key info to
```
.txt
```
files

查看Brain推理过程：检查

brain_llm_interactions.log_brain_*.txt

中的

analysis

和

next_goal

查看Actor动作：检查
```
actor_llm_interactions.log_actor_*.txt
```
中的执行动作
检查截图：TuriX每步都会捕获截图（保存在内存中）
读取记录文件：代理使用
```
record_info
```
将关键信息保存到
```
.txt
```
文件中

8. Example Monitoring Flow

8. 监控流程示例

bash

undefined

bash

undefined

1. Run a task

1. 执行任务

./run_turix.sh "Search AI news and summarize" &

2. Wait a few seconds and check the process

2. 等待几秒后检查进程

sleep 10 && ps aux | grep main.py

3. Check if logs are being created

3. 检查是否已生成日志

ls -la your_dir/TuriX-CUA/examples/.turix_tmp/

4. Tail progress in real time

4. 实时查看进度

tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log

5. Check current step count

5. 查看当前步骤数

ls your_dir/TuriX-CUA/examples/.turix_tmp/brain_llm_interactions.log_brain_*.txt | wc -l

undefined

ls your_dir/TuriX-CUA/examples/.turix_tmp/brain_llm_interactions.log_brain_*.txt | wc -l

undefined