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，且该文件中的值会覆盖同名的 Shell 环境变量。

需要安装 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，并调用 task poll，同时传入 --openclaw-target 和目标对话所需的路由字段。
4. 让 task poll 持续轮询，直到 taskState 达到下方任务状态表中的某种状态。
5. 读取 task poll 返回的最终 JSON 响应。

task poll 是主要的监控命令：

• 默认情况下，它每隔 10 秒在内部轮询一次 task get-details。
• 任务完成、失败、取消或需要用户输入时，它会自动停止。
• 它会返回相同的任务详情负载，外加一个 _poll 摘要。
• 直接运行 task poll --task-id ... 只会在 Airtap 本地轮询。
• 通过 OpenClaw 发送更新需要传入 --openclaw-target。
• 默认情况下，OpenClaw 会按里程碑发送更新：确认消息、一条计划／开始更新，以及最终状态或等待状态更新。
• 仅当宿主明确要求转发 Airtap Agent 的每条更新时，才添加 --openclaw-verbose。
• 详细的 OpenClaw 路由标志和示例见 references/openclaw.md。

如何查看 task poll 或 task get-details 返回的任务详情：

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

任务状态

• COMPLETED：任务已成功完成。
• FAILED：任务未能完成。
• CANCELLED：任务已取消。
• WAITING_FOR_USER_INTERVENTION：用户必须在设备上执行某项操作。
• WAITING_FOR_USER_INPUT：Agent 需要进一步说明才能继续。
• WAITING_FOR_USER_CONTINUE：任务已达到最大步骤限制，需要获得继续执行的批准。

Agent 必须遵循的行为

• 如果宿主希望在 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 时，根据最新的 Agent 更新总结结果。
• 遇到 FAILED 或 CANCELLED 时，报告最终状态，并提供最新 Agent 消息中的有用信息。
• 如果任何 Airtap API 调用返回 404 或其他请求失败，请告知用户先获取更新版本的 Airtap skill，再重试。

示例

使用默认模型创建任务：

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"

说明

• task create 和 task add-user-message 支持通过 --image-file 添加图像附件。
• 有关 OpenClaw 中继的详情和示例，请阅读 references/openclaw.md。