turix-mac

TuriX-Mac スキル

このスキルを使うと、Clawdbot が TuriX Computer Use Agent を使用して、macOS デスクトップを視覚的に操作できます。

使用する場面

• Mac デスクトップ上での操作を依頼されたとき（例：「Spotify を開いて、いいねした曲を再生して」）。
• コマンドラインインターフェースのないアプリケーションを操作するとき。
• 複数の手順からなる視覚的なワークフローを実行するとき（例：「メールから最新の請求書を探し、会社のポータルにアップロードして」）。
• エージェントに複雑なタスクを自律的に計画、推論、実行させる必要があるとき。

主な機能

🤖 マルチモデルアーキテクチャ

TuriX は高度なマルチモデルシステムを使用します。

• Brain：タスクを理解し、手順ごとの計画を生成します
• Actor：視覚的な理解に基づいて、正確な UI 操作を実行します
• Planner：高レベルのタスク分解を調整します（use_plan: true の場合）
• Memory：タスクの手順を通じてコンテキストを維持します

📋 スキルシステム

スキルは、特定の分野でエージェントをガイドする Markdown のプレイブックです。

• github-web-actions：GitHub のナビゲーション、リポジトリ検索、スター付け
• browser-tasks：一般的なウェブブラウザー操作
• カスタムスキルは skills/ ディレクトリに追加できます

🔄 再開機能

agent_id を固定値に設定すると、中断したタスクをエージェントが再開できます。

TuriX の実行

基本的なタスク

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

中断したタスクの再開

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

✅ 注：run_turix.sh は examples/config.json（task、resume、use_plan、use_skills）を更新します。手動で編集した設定を保持する場合は、タスクを渡さずに examples/config.json を直接編集してください。

効果的なタスクのコツ

✅ 良い例：

• 「Safari を開いて google.com に移動し、『TuriX AI』を検索して、最初の検索結果をクリックして」
• 「システム設定を開き、ダークモードをクリックしてから、システム設定に戻って」
• 「Finder を開いて書類に移動し、『Project X』という名前の新しいフォルダを作成して」

❌ 避けること：

• 曖昧な指示：「手伝って」や「これを直して」
• 実行不可能な操作：「すべてのファイルを削除して」
• 警告なしでシステムレベルの権限を必要とするタスク

💡 ベストプラクティス：

1. 対象のアプリケーションを具体的に指定します
2. 複雑なタスクは明確な手順に分けます。ただし、画面上の正確な座標は指定しないでください。

ホットキー

• 強制停止：Cmd+Shift+2 — エージェントを直ちに停止します

モニタリングとログ

ログはプロジェクトディレクトリの .turix_tmp/logging.log に保存されます。以下を確認できます。

• 手順ごとの実行詳細
• LLM とのやり取りと推論
• エラーと復旧の試行

重要な注意事項

TuriX の実行方法

• TuriX は clawdbot exec の pty:true モードで起動できます
• 初回起動時は、すべての AI モデル（Brain、Actor、Planner、Memory）の読み込みに 2〜5 分かかります
• バックグラウンドの出力はバッファリングされるため、タスクが完了または停止するまで進行状況はリアルタイムで表示されません

実行前の準備

必ず最初に PATH を設定してください：

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 には含まれていません。

TuriX の実行状態の確認

# 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

注： .turix_tmp ディレクトリは、TuriX が手順の実行を開始するまで作成されない場合があります。

トラブルシューティング

よくある問題

エラー	解決策
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
モジュールのインポートエラー	環境を有効化します：conda activate turix_env の後に pip install -r requirements.txt を実行してください
キーボードリスナーの権限エラー	ターミナル／IDE にアクセシビリティ権限を付与してください

デバッグモード

ログにはデフォルトで DEBUG レベルの情報が含まれます。以下を確認してください。

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

アーキテクチャ

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

スキルシステムの詳細

スキルは skills/ ディレクトリにある、YAML フロントマター付きの Markdown ファイルです。

---
name: skill-name
description: When to use this skill
---
# Skill Instructions
High-level workflow like: Open Safari,then go to Google.

Planner は名前と説明に基づいて関連するスキルを選択し、Brain は手順のガイダンスとして内容全体を使用します。

高度なオプション

オプション	説明
use_plan: true	複雑なタスクの計画を有効にします
use_skills: true	スキルの選択を有効にします
resume: true	前回中断した箇所から再開します
max_steps: N	合計ステップ数を制限します（デフォルト：100）
max_actions_per_step: N	1ステップあたりのアクション数です（デフォルト：5）
force_stop_hotkey	エージェントを停止するカスタムホットキー

---

TuriX スキルシステム

TuriX はスキルに対応しています。スキルとは、特定の分野でエージェントがより確実に動作できるよう支援する Markdown 形式のプレイブックです。

1. 組み込みスキル

スキル	用途
github-web-actions	GitHub のウェブ操作（リポジトリの検索、スター付けなど）

2. カスタムスキルの作成

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

フィールドの定義：

• name：スキルの識別子（Planner が選択する際に使用します）
• description：このスキルを使用する状況（Planner はこれに基づいて判断します）
• 以下の本文：実行手順の全体（Brain が使用します）

3. スキルの有効化

examples/config.json で設定します。

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

4. スキルを使ってタスクを実行

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

エージェントは次の処理を自動的に行います。

1. Planner がスキル名と説明を読み取ります
2. 関連するスキルを選択します
3. Brain がスキルの内容全体を使って実行を支援します

5. 中国語テキストへの対応

背景： シェルの文字列補間を介して中国語テキストを渡すと UTF-8 が文字化けすることがあり、信頼できないテキストをヒアドキュメントに埋め込むのは安全ではありません。

解決策： run_turix.sh スクリプトは Python を使用して UTF-8 を正しく処理し、環境変数からタスクのテキストを読み取ります。

import json

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

# Write without escaping non-ASCII text
with open(config_path, 'w', encoding='utf-8') as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

重要なポイント：

1. ファイルの読み書きには、必ず encoding='utf-8' を使用します
2. ASCII 以外のテキストを保持するために、ensure_ascii=False を使用します
3. タスクの内容は環境変数または標準入力で渡し、シェルによる文字列補間を避けるために単一引用符付きのヒアドキュメントを使用します

6. ドキュメント作成のベストプラクティス

課題：

• TuriX にニュースを収集させた後、ドキュメントを直接作成して送信させること
• TuriX は GUI エージェントであるため、動作が遅く、再現性も低くなる場合があります。Clawdbot ではできないタスクや、TuriX のほうが速いタスクに限って TuriX を使用することをおすすめします。

推奨される方法： 自分でドキュメントを作成し、TuriX には送信だけを任せます

1. python-docx で Word ドキュメントを作成します
2. TuriX にはファイルの送信だけを任せます

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

推奨ワークフロー：

1. web_fetch を使って情報を収集します
2. Python を使って Word ドキュメントを作成します
3. TuriX を使ってファイルを送信します。ファイル名だけでなく、ファイルパスを指定してファイルを送信するよう伝えてください。
4. TuriX に手作業で Word ドキュメントを作成させ、収集した情報を入力させる必要がある場合は、内容が多ければ turix skills に、少なければタスク名に記載してください。

7. 例：新しいスキルの追加

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

## Forms
- 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

8. スキル開発のヒント

1. 説明を正確に記述する — Planner が適切に選択できるようになります
2. 手順を明確にする — Brain には具体的な指示が必要です
3. 安全確認を含める — 重要な操作には確認を設けます
4. 簡潔にまとめる — 4000 文字未満を推奨します

---

監視とデバッグのガイド

1. タスクの実行

# 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
./run_turix.sh "Task" &

2. 進行状況の監視

方法 1：セッションログ

# List running sessions
clawdbot sessions_list

# View history
clawdbot sessions_history <session_key>

方法 2：TuriX のログ

# 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

方法 3：プロセスの確認

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

方法 4：生成されたファイルの確認

# List files created by the agent
ls -la your_dir/TuriX-CUA/examples/.turix_tmp/*.txt

3. ログファイルの一覧

ファイル	説明
logging.log	メインログファイル
brain_llm_interactions.log_brain_N.txt	Brain モデルとの会話（ステップごとに 1 ファイル）
actor_llm_interactions.log_actor_N.txt	Actor モデルとの会話（ステップごとに 1 ファイル）

主なログマーカー：

• 📍 Step N - 新しいステップを開始しました
• ✅ Eval: Success/Failed - 現在のステップの評価
• 🎯 Goal to achieve this step - 現在の目標
• 🛠️ Action - 実行されたアクション
• ✅ Task completed successfully - タスクが正常に完了しました

4. よくある監視の問題

問題	確認方法
プロセスが応答しない	`ps aux
ステップ1で停止する	.turix_tmp/ が作成されたか確認します
モデルの読み込みが遅い	初回実行時は、モデルの読み込みに1～2分かかる場合があります
ログが出力されない	config.json の logging_level を確認します

5. 強制停止

ショートカットキー：Cmd+Shift+2 - エージェントを直ちに停止します

コマンド：

pkill -f "python examples/main.py"

6. 結果の表示

完了後、エージェントは次の処理を行います。

1. .turix_tmp/ に操作ログを作成します
2. （record_info が使用されている場合）記録ファイルを作成します
3. 後続のステップで使用するスクリーンショットをメモリに保持します

例：要約ファイルを表示する

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

7. デバッグのヒント

1. Brain の推論を確認する：brain_llm_interactions.log_brain_*.txt で analysis と next_goal を確認します
2. Actor のアクションを確認する：actor_llm_interactions.log_actor_*.txt でアクションを確認します
3. スクリーンショットを確認する：TuriX は各ステップでスクリーンショットを撮影します（メモリに保持されます）
4. 記録ファイルを読む：エージェントは record_info を使用して、重要な情報を .txt ファイルに保存します

8. 監視フローの例

# 1. Run a task
./run_turix.sh "Search AI news and summarize" &

# 2. Wait a few seconds and check the process
sleep 10 && ps aux | grep main.py

# 3. Check if logs are being created
ls -la your_dir/TuriX-CUA/examples/.turix_tmp/

# 4. Tail progress in real time
tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log

# 5. Check current step count
ls your_dir/TuriX-CUA/examples/.turix_tmp/brain_llm_interactions.log_brain_*.txt | wc -l