airtap

Airtap

同梱されている scripts/airtap.py CLI を使用して、Airtap タスクを操作します。

安全性

• Airtap デバイスに委任できる Airtap またはモバイルアプリのリクエストには、このスキルを使用してください。
• --receiver-id cloud を優先してください。ユーザーからそのデバイスを明示的に指定された場合を除き、物理レシーバーを指定しないでください。
• task poll はデフォルトでローカルのみで実行されます。ホストが更新のミラーリングを明示的に希望している場合にのみ、OpenClaw への配信を使用してください。
• トークンをチャットに貼り付けるようユーザーに求めないでください。事前設定された環境変数またはローカルの scripts/.env ファイルを使用してください。
• OpenClaw のターゲット、スレッド ID、返信 ID、アカウントスコープを決して捏造しないでください。

セットアップ

スキルディレクトリからコマンドを実行してください。

まず、https://airtap.ai/app にサインインし、Settings を開いて、個人用アクセストークンを作成してコピーします。

以下の内容で scripts/.env を作成または更新します。

python3 scripts/airtap.py --add-token "your-personal-access-token"

または、テンプレートをコピーして、個人用アクセストークンを入力します。

cp scripts/env.example.txt scripts/.env

スクリプトは起動時に scripts/.env を読み込み、このファイル内の値は、同名のシェル環境変数より優先されます。

requests と python-dotenv が必要です。インストールされていない場合は、次を実行します。

pip3 install -r requirements.txt

コマンドリファレンス

すべてのコマンドは python3 scripts/airtap.py <resource> <action> ... として実行します。

コマンド	使用する場面	備考
receiver get-list	レシーバーを選ぶ必要がある場合。	タスクの作成前に実行すると便利です。
model get-list	タスクでモデルの選択が重要な場合。	Airtap の主な選択肢は airtap-1.0 と airtap-1.0-flash です。
task create	新しいタスクを開始する場合。	デフォルトのモデルを上書きする場合にのみ、--model-id <id> を追加します。
task get-list	最近のタスクが必要な場合。	taskId の復元が必要な場合に便利です。
task get-details	タスクのスナップショットを一度だけ取得する場合。	デバッグや最終状態の確認に便利です。
task poll	実行中のタスクを監視する場合。	デフォルトではローカルでポーリングし、必要に応じて更新を OpenClaw に転送できます。
task add-user-message	タスクに追加の入力が必要な場合。	明確化、続行、または作業の再開に使用します。
task cancel	タスクを停止する場合。	ユーザーがタスクの続行を望まなくなったときに使用します。
user update-location	タスクがユーザーの位置情報に依存する場合。	位置情報は未加工の JSON として送信します。

モデルの選択

• モデルの選択が重要な場合にのみ、モデル一覧を取得してください。すべてのタスクで model get-list を呼び出さないでください。
• タスク作成時に modelId を送信しない場合、Airtap はデフォルトで airtap-1.0-flash を使用します。
• Airtap 1.0 Flash（airtap-1.0-flash）はデフォルトです。レイテンシの低さが役立つ短いタスクに使用してください。
• Airtap 1.0（airtap-1.0）はより低速です。レイテンシが増えても信頼性の向上が重要となる、より複雑なタスクに使用してください。
• model get-list は、現在のアカウントで利用可能なモデルを返します。ほとんどのユーザーには airtap-1.0 と airtap-1.0-flash が表示されます。デバッグユーザーには airtap-1.0-lite も表示される場合があります。

長時間実行されるタスクの監視

Airtap のタスクは、数秒から数分かかることがあります。長時間実行されるジョブとして扱ってください。

1. タスクを作成し、返された taskId を取得します。
2. ローカルで待機ループを実行するだけでよい場合は、 python3 scripts/airtap.py task poll --task-id "<task-id>" を呼び出します。
3. ホストが OpenClaw チャネルでの更新を明示的に必要としている場合は、references/openclaw.md を読み、 宛先の会話に必要な --openclaw-target とルーティングフィールドを指定して task poll を呼び出します。
4. task poll が、以下のタスク状態の用語集に記載されている状態に taskState が到達するまで、ポーリングを続けるようにします。
5. task poll から最終的な JSON レスポンスを読み取ります。

task poll は、主な監視コマンドです。

• デフォルトでは、内部で task get-details を 10 秒ごとにポーリングします。
• タスクが完了、失敗、キャンセル、またはユーザー入力待ちになると、自動的に停止します。
• 同じタスク詳細のペイロードに _poll の概要を加えて返します。
• task poll --task-id ... のみを指定した場合は、Airtap をローカルでのみポーリングします。
• OpenClaw への配信には --openclaw-target が必要です。
• OpenClaw への配信はデフォルトでマイルストーン方式です。確認応答、計画／開始の更新 1 件、そして最終状態または待機状態の更新が配信されます。
• Airtap エージェントの更新をすべて転送するようホストが明示的に求めている場合にのみ、--openclaw-verbose を追加します。
• OpenClaw の詳細なルーティングフラグと例は、references/openclaw.md に記載されています。

task poll または task get-details から返されるタスク詳細の読み取り方：

• messages は順序付きの会話履歴です。最初のメッセージは通常、元のユーザーリクエストです。後続の項目は、通常、エージェントからの更新です。
• 進捗の更新の大半は、最新の type: "agent" メッセージに含まれます。
• エージェントのメッセージ内では、まずテキスト部分を確認します。
• text は主な進捗更新です。
• group と subGroup は、更新を分類するのに役立つ UI グループ化フィールドです。
• queuedUserMessages には、受け付けられたものの、まだ処理されていないユーザーからの追加メッセージが含まれる場合があります。

タスクの状態

• COMPLETED：タスクは正常に完了しました。
• FAILED：タスクを完了できませんでした。
• CANCELLED：タスクはキャンセルされました。
• WAITING_FOR_USER_INTERVENTION：ユーザーがデバイス上で操作を行う必要があります。
• WAITING_FOR_USER_INPUT：タスクを続行する前に、エージェントが確認を必要としています。
• WAITING_FOR_USER_CONTINUE：タスクが最大ステップ数に達したため、続行するには承認が必要です。

エージェントに求められる動作

• Airtap の実行中にホストが OpenClaw チャネルでの更新を期待している場合は、--openclaw-target と必要なルーティングフラグを指定して task poll を呼び出します。それ以外の場合は、ローカルのみの task poll を使用します。
• OpenClaw への配信は、デフォルトでマイルストーンのみとします。Airtap のすべてのステップを転送するようホストが明示的に求めている場合にのみ、--openclaw-verbose を追加します。
• WAITING_FOR_USER_INPUT の場合は、必要な確認事項をユーザーに尋ね、その回答を task add-user-message で転送します。
• WAITING_FOR_USER_INTERVENTION の場合は、デバイス上で行う必要がある操作をユーザーに正確に伝え、確認を待ってから、task add-user-message で再開します。
• WAITING_FOR_USER_CONTINUE の場合は、これまでの進捗を要約して続行するかどうかを尋ねます。ユーザーが承認した場合は、task add-user-message で再開します。
• COMPLETED の場合は、最新のエージェント更新を基に結果を要約します。
• FAILED または CANCELLED の場合は、最終状態と、最新のエージェントメッセージに含まれる有用な情報を報告します。
• Airtap API の呼び出しで 404 またはその他のリクエストエラーが返された場合は、再試行する前に Airtap スキルの最新バージョンを入手するようユーザーに伝えます。

例

デフォルトのモデルでタスクを作成します：

python3 scripts/airtap.py task create --message "Open Instagram" --receiver-id cloud

タスクが複雑な場合は、利用可能なモデルを一覧表示します：

python3 scripts/airtap.py model get-list

より信頼性の高い Airtap モデルでタスクを作成します：

python3 scripts/airtap.py task create \
  --message "Compare the price of a product on Amazon and Zepto" \
  --receiver-id cloud \
  --model-id airtap-1.0

実行中のタスクをローカルのみで監視します：

python3 scripts/airtap.py task poll --task-id "task_abc123"

確認要求に回答するか、一時停止中のタスクを続行します：

python3 scripts/airtap.py task add-user-message --task-id "task_abc123" --message "Continue"

タスクをキャンセルします：

python3 scripts/airtap.py task cancel --task-id "task_abc123"

注記

• --image-file を使用して、task create および task add-user-message に画像を添付できます。
• OpenClaw のリレーに関する詳細と例は、references/openclaw.md をお読みください。