Airtap#

Use the bundled scripts/airtap.py CLI to interact with Airtap tasks.

Safety#

• Use this skill for Airtap or mobile-app requests that can be delegated to an Airtap device.
• Prefer --receiver-id cloud. Do not target a physical receiver unless the user explicitly asks for that device.
• task poll is local-only by default. Use OpenClaw delivery only when the host explicitly wants mirrored updates.
• Do not ask the user to paste tokens into chat. Use preconfigured environment variables or the local scripts/.env file.
• Never invent OpenClaw targets, thread IDs, reply IDs, or account scopes.

Setup#

Run commands from the skill directory.

First, sign in to https://airtap.ai/app, open Settings, create a personal access token, and copy it.

Create or update scripts/.env with:

bash

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

Or copy the template and fill in the personal access token:

bash

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

The script loads scripts/.env on startup and values from that file override same-named shell environment variables.

Requires requests and python-dotenv. If missing:

bash

pip3 install -r requirements.txt

Command Reference#

Run all commands as python3 scripts/airtap.py <resource> <action> ....

CommandUse whenNotesreceiver get-listYou need to choose a receiver.Helpful before task creation.model get-listModel choice matters for the task.Main Airtap choices are airtap-1.0 and airtap-1.0-flash.task createYou want to start a new task.Add --model-id <id> only to override the default model.task get-listYou need recent tasks.Useful when you need to recover a taskId.task get-detailsYou need a one-time task snapshot.Useful for debugging or inspecting the final state.task pollYou need to monitor a running task.Polls locally by default and can optionally forward updates into OpenClaw.task add-user-messageThe task needs more input.Use for clarification, continuation, or resuming work.task cancelThe task should stop.Use when the user no longer wants the task to continue.user update-locationThe task depends on user location.Send the location as raw JSON.

Choosing A Model#

• Only list models when model choice matters. Do not call model get-list for every task.
• If you do not send modelId during task creation, Airtap defaults to airtap-1.0-flash.
• Airtap 1.0 Flash ( airtap-1.0-flash) is the default. Use it for shorter tasks that benefit from lower latency.
• Airtap 1.0 ( airtap-1.0) is slower. Use it for more complex tasks where better reliability is worth the extra latency.
• model get-list returns the models available to the current account. Most users see airtap-1.0 and airtap-1.0-flash. Debug users may also see airtap-1.0-lite.

Monitoring Long-Running Tasks#

Airtap tasks can take a few seconds to several minutes. Treat them as long-running jobs.

1. Create the task and capture the returned taskId.
2. If you only need a local wait loop, call python3 scripts/airtap.py task poll --task-id "<task-id>".
3. If the host explicitly wants OpenClaw channel updates, read references/openclaw.md and call task poll with --openclaw-target and any routing fields required for the destination conversation.
4. Let task poll keep polling until taskState reaches one of the states in the task-state glossary below.
5. Read the final JSON response from task poll.

task poll is the main monitoring command:

• It polls task get-details internally every 10 seconds by default.
• It stops automatically when the task completes, fails, is cancelled, or needs user input.
• It returns the same task details payload plus a _poll summary.
• Bare task poll --task-id ... only polls Airtap locally.
• OpenClaw delivery requires --openclaw-target.
• OpenClaw delivery is milestone-based by default: acknowledgement, one plan/start update, and the final or waiting-state update.
• Add --openclaw-verbose only when the host explicitly wants every Airtap agent update forwarded.
• Detailed OpenClaw routing flags and examples live in references/openclaw.md.

How to read the task details returned by task poll or task get-details:

• messages is ordered conversation history. The first message is typically the original user request. Later entries are usually agent updates.
• Most progress updates come from the latest type: "agent" message.
• Inside an agent message, inspect text parts first.
• text is the main progress update.
• group and subGroup are UI grouping fields that help categorize the update.
• queuedUserMessages may contain user follow-ups that have been accepted but not processed yet.

Task States#

• COMPLETED: the task finished successfully.
• FAILED: the task could not be completed.
• CANCELLED: the task was cancelled.
• WAITING_FOR_USER_INTERVENTION: the user must perform some action on the device.
• WAITING_FOR_USER_INPUT: the agent needs clarification before continuing the task.
• WAITING_FOR_USER_CONTINUE: the task reached the maximum step limit and needs approval to keep going.

Required Agent Behavior#

• If the host expects OpenClaw channel updates while Airtap is running, call task poll with --openclaw-target and the required routing flags. Otherwise use local-only task poll.
• Use milestone-only OpenClaw delivery by default. Add --openclaw-verbose only when the host explicitly wants every Airtap step forwarded.
• On WAITING_FOR_USER_INPUT, ask the user the needed clarification, then forward the answer with task add-user-message.
• On WAITING_FOR_USER_INTERVENTION, tell the user exactly what action they need to perform on the device, wait for confirmation, then resume with task add-user-message.
• On WAITING_FOR_USER_CONTINUE, summarize the progress so far, ask whether to continue, and if the user approves, resume with task add-user-message.
• On COMPLETED, summarize the result using the latest agent updates.
• On FAILED or CANCELLED, report the final state and any useful context from the latest agent message.
• If any Airtap API call returns 404 or another request failure, tell the user to get an updated version of the Airtap skill before retrying.

Examples#

Create a task with the default model:

bash

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

List available models when the task is complex:

bash

python3 scripts/airtap.py model get-list

Create a task with the more reliable Airtap model:

bash

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

Monitor a running task locally only:

bash

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

Answer a clarification request or continue a paused task:

bash

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

Cancel a task:

bash

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

Notes#

• Image attachments are supported for task create and task add-user-message via --image-file.
• For OpenClaw relay details and examples, read references/openclaw.md.