airtap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Airtap

Use the bundled

scripts/airtap.py

CLI to interact with Airtap tasks.

使用附带的

scripts/airtap.py

CLI与Airtap任务进行交互。

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.

将此技能用于可委托给Airtap设备的Airtap或移动应用请求。
优先使用
```
--receiver-id cloud
```
。除非用户明确指定，否则不要针对物理接收端设备。
```
task poll
```
默认仅本地运行。仅当主机明确需要同步更新时，才使用OpenClaw推送。
不要要求用户在聊天中粘贴令牌。使用预配置的环境变量或本地
```
scripts/.env
```
文件。
切勿编造OpenClaw目标、线程ID、回复ID或账户范围。

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

从技能目录运行命令。

首先，登录

https://airtap.ai/app

，打开设置，创建个人访问令牌并复制。

通过以下命令创建或更新

scripts/.env

：

bash

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

或者复制模板并填写个人访问令牌：

bash

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

脚本启动时会加载

scripts/.env

，该文件中的值会覆盖同名的Shell环境变量。

需要依赖

requests

和

python-dotenv

。如果缺失：

bash

pip3 install -r requirements.txt

Command Reference

命令参考

Run all commands as

python3 scripts/airtap.py <resource> <action> ...

Command	Use when	Notes
`receiver get-list`	You need to choose a receiver.	Helpful before task creation.
`model get-list`	Model choice matters for the task.	Main Airtap choices are `airtap-1.0` and `airtap-1.0-flash` .
`task create`	You want to start a new task.	Add `--model-id <id>` only to override the default model.
`task get-list`	You need recent tasks.	Useful when you need to recover a `taskId` .
`task get-details`	You need a one-time task snapshot.	Useful for debugging or inspecting the final state.
`task poll`	You need to monitor a running task.	Polls locally by default and can optionally forward updates into OpenClaw.
`task add-user-message`	The task needs more input.	Use for clarification, continuation, or resuming work.
`task cancel`	The task should stop.	Use when the user no longer wants the task to continue.
`user update-location`	The task depends on user location.	Send the location as raw JSON.

所有命令格式为

python3 scripts/airtap.py <资源> <操作> ...

。

命令	使用场景	说明
`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格式发送位置信息。

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
```
.

仅在模型选择对任务有影响时列出模型。不要每次任务都调用
```
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
```
。

Monitoring Long-Running Tasks

监控长时间运行的任务

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

Create the task and capture the returned
```
taskId
```
.

If you only need a local wait loop, call

python3 scripts/airtap.py task poll --task-id "<task-id>"

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.
Let
```
task poll
```
keep polling until
```
taskState
```
reaches one of the states in the task-state glossary below.
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

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.

Airtap任务可能需要几秒到几分钟的时间，将其视为长时间运行的作业。

创建任务并记录返回的
```
taskId
```
。

如果仅需要本地等待循环，调用

python3 scripts/airtap.py task poll --task-id "<task-id>"

。

如果主机明确需要OpenClaw频道更新，请阅读
```
references/openclaw.md
```
，并调用带有
```
--openclaw-target
```
和目标对话所需路由字段的
```
task poll
```
。
让
```
task poll
```
持续轮询，直到
```
taskState
```
达到下方任务状态术语表中的某一状态。
读取
```
task poll
```
返回的最终JSON响应。

task poll

是主要的监控命令：

默认每10秒内部调用一次
```
task get-details
```
进行轮询。
当任务完成、失败、被取消或需要用户输入时自动停止。
返回与
```
task get-details
```
相同的任务详情负载，外加
```
_poll
```
摘要。
仅使用
```
task poll --task-id ...
```
时仅在本地轮询Airtap。
OpenClaw推送需要
```
--openclaw-target
```
参数。
OpenClaw推送默认基于里程碑：确认消息、一次计划/启动更新，以及最终或等待状态更新。
仅当主机明确要求转发每一步Airtap代理更新时，才添加
```
--openclaw-verbose
```
参数。
详细的OpenClaw路由标志和示例请查看
```
references/openclaw.md
```
。

如何解读

task poll

或

task get-details

返回的任务详情：

```
messages
```
是按顺序排列的对话历史。第一条消息通常是原始用户请求，后续条目通常是代理更新。
大多数进度更新来自最新的
```
type: "agent"
```
消息。
在代理消息中，先检查文本部分。
```
text
```
是主要的进度更新内容。
```
group
```
和
```
subGroup
```
是UI分组字段，用于对更新进行分类。
```
queuedUserMessages
```
可能包含已被接受但尚未处理的用户跟进消息。

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.

```
COMPLETED
```
：任务成功完成。
```
FAILED
```
：任务无法完成。
```
CANCELLED
```
：任务已被取消。
```
WAITING_FOR_USER_INTERVENTION
```
：用户必须在设备上执行某些操作。
```
WAITING_FOR_USER_INPUT
```
：代理需要用户澄清才能继续任务。
```
WAITING_FOR_USER_CONTINUE
```
：任务已达到最大步骤限制，需要用户批准才能继续。

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.

如果主机期望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技能后再重试。

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"

使用默认模型创建任务：

bash

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

当任务复杂时列出可用模型：

bash

python3 scripts/airtap.py model get-list

使用更可靠的Airtap模型创建任务：

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

仅本地监控运行中的任务：

bash

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

回复澄清请求或恢复暂停的任务：

bash

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

取消任务：

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
```
.

task create

和

task add-user-message

支持通过

--image-file

参数添加图片附件。

有关OpenClaw转发的详细信息和示例，请阅读
```
references/openclaw.md
```
。