查询设备事件

调用 ai-open-gateway 的事件查询接口 POST /api/event/query，支持自然语言查询设备事件，返回 AI 摘要和事件列表。Use when: 需要查询设备检测到的事件、了解某段时间内的活动情况，例如有没有人出现、有没有车开过、我的猫去哪里了等自然语言问题。⚠️ 需设置 AI_GATE...

Security Scan

The skill is internally consistent with its stated purpose (querying ai-open-gateway device events) and only requires the expected API key and python; minor implementation/ documentation mismatches are present but not indicative of malicious intent.

Purpose & Capability

Name/description, required binary (python3), and required env var (AI_GATEWAY_API_KEY) align with calling an HTTP API to query device events. Declared fallback config path (~/.openclaw/.env) is documented in SKILL.md and used by the code.

Instruction Scope

SKILL.md confines behavior to POST /api/event/query and specifies strict presentation rules for the agent; the script only calls that endpoint and outputs JSON. Two inconsistencies to be aware of: (1) SKILL.md's display guidance mentions showing up to 10 events when >10 exist, but the script truncates events to MAX_EVENTS=3 before printing; (2) SKILL.md mandates stripping the 'xxxxS_' prefix from device_id for display, but the script does not modify device_id (it returns API JSON and expects the agent to format). These are implementation/coordination mismatches, not evidence of exfiltration.

Install Mechanism

No install spec; this is an instruction+script skill that depends on the third-party library httpx. The script checks for httpx and instructs the user how to pip install it rather than downloading arbitrary code. No external download URLs or archive extraction are used.

Credentials

Only AI_GATEWAY_API_KEY (primary credential) is required, which is proportionate to a gateway API call. The skill reads ~/.openclaw/.env as a documented fallback — this shared-file fallback is a convenience but raises a potential credential-sharing risk between co-located skills; SKILL.md explicitly warns to use environment variables in production and provides AI_GATEWAY_NO_ENV_FILE to disable the fallback. Also note AI_GATEWAY_VERIFY_SSL can disable TLS verification (documented as for dev only).

Persistence & Privilege

always is false and the skill does not modify other skills or system-wide configuration. It only reads a shared fallback file and environment variables; it does not write persistent settings or request elevated privileges.

Assessment

This skill appears to do what it says: call the AI gateway event query API and return JSON for the agent to format. Before installing, ensure you: (1) provide a minimal-privilege AI_GATEWAY_API_KEY (event-query-only key if possible); (2) prefer passing the key via environment variables and set AI_GATEWAY_NO_ENV_FILE=true to avoid the shared ~/.openclaw/.env fallback; (3) verify AI_GATEWAY_HOST points to the expected trusted domain; (4) do not set AI_GATEWAY_VERIFY_SSL=false in production; and (5) be aware the SKILL.md presentation rules (e.g., stripping device_id prefixes, link formatting, and maximum display counts) are the agent's responsibility — the shipped script truncates results to 3 items, which differs from a 10-item display rule in the docs, so confirm the display behavior you expect.

事件查询接口

POST /api/event/query 是 AI 驱动的事件查询接口，支持自然语言查询，返回 AI 摘要和事件列表。

⚠️ 展示规则（MUST 严格遵守）

脚本输出 JSON 格式的结构化数据，这是预期行为。以下展示规则是给 agent 的格式化指令：agent MUST 解析脚本输出的 JSON，按下述规则转换为用户友好的格式后再展示，MUST NOT 直接展示原始 JSON。

1. 当 code == 0 且 data.events 非空时：

📋 AI 摘要：{summary}

时间	事件标签	场景描述
{time}	{ai_events 用逗号连接}	{ai_scene}

在表格之后，逐条展示每个事件的缩略图链接：

📷 {time} - {ai_events} 查看截图

关键规则：

• device_id MUST 去掉 xxxxS_ 前缀再展示
• pic_url MUST 用 [查看截图](url) Markdown 链接格式输出
• MUST NOT 使用 ![](url) 图片语法（部分客户端不支持内联图片渲染）
• MUST NOT 输出裸 URL 文本
• 超过 10 条只展示前 10 条，提示总数

2. 当 events 为空数组时，回复："查询时间范围内没有匹配的事件。"
3. 当 code != 0 时，回复："接口调用失败，错误码 {code}，原因：{message}"

前置依赖

脚本依赖 httpx。如果未安装，脚本会提示 python3 -m pip install httpx。

配置声明

本 skill 依赖以下配置项，agent 和用户 MUST 在运行前确认已正确配置。

必需配置

配置项	传递方式	说明
AI_GATEWAY_API_KEY	环境变量（推荐）、~/.openclaw/.env（fallback）、命令行 --api-key	API 密钥，用于接口鉴权。脚本按此优先级自动获取

可选配置

配置项	传递方式	默认值	说明
AI_GATEWAY_HOST	环境变量、~/.openclaw/.env	https://ai-open-gateway.closeli.cn	网关地址
AI_GATEWAY_VERIFY_SSL	环境变量	true	设为 false 可禁用 TLS 证书验证（仅限开发环境）
AI_GATEWAY_NO_ENV_FILE	环境变量	false	设为 true 可禁用 ~/.openclaw/.env fallback 读取（生产环境推荐）

Fallback 配置路径

脚本默认会读取 ~/.openclaw/.env 文件作为 fallback 配置源。该文件为所有 skill 共享，格式为 KEY=VALUE（每行一条）。生产环境 MUST 设置 AI_GATEWAY_NO_ENV_FILE=true 禁用此 fallback，改为通过环境变量直接传递所有配置。

安全注意事项

• 共享凭证文件 ~/.openclaw/.env 可被同一用户下所有 skill 读取。生产环境 MUST 通过环境变量传递 API_KEY，MUST NOT 依赖共享凭证文件
• TLS 证书验证默认启用，MUST NOT 在生产环境禁用（禁用会导致中间人攻击风险，攻击者可截获 API_KEY 和设备数据）
• 使用前 MUST 确认 AI_GATEWAY_HOST 指向可信域名
• MUST 使用最小权限的 API_KEY，避免复用高权限凭证。本 skill 仅需事件查询权限

网络访问声明

本 skill 仅访问以下端点（均为 AI_GATEWAY_HOST 下的路径）：

端点	方法	用途
/api/event/query	POST	自然语言查询设备事件

脚本不访问任何其他网络资源。

快速开始

python3 query_events.py \
  --device-ids "xxxxS_aabbccddeeff" \
  --start-date "2026-03-16" \
  --end-date "2026-03-18" \
  --query "今天有没有人来过"

请求格式

请求体

参数名	类型	必填	默认值	说明
device_ids	string[]	是	-	设备 ID 列表，不能为空。格式: xxxxS_<mac>
start_date	string	是	-	查询开始日期，格式 yyyy-MM-dd
end_date	string	是	-	查询结束日期，格式 yyyy-MM-dd
query	string	是	-	自然语言查询内容
locale	string	否	"zh_CN"	语言区域，影响 AI 摘要语言

响应格式

{
  "code": 0,
  "message": "success",
  "request_id": "<32位请求追踪ID>",
  "data": {
    "summary": "今天共检测到3次有人出现的事件。",
    "events": [...],
    "_total_count": 15
  }
}

data 字段

参数名	类型	说明
summary	string	AI 生成的事件摘要文本
events	array	事件列表（脚本已裁剪到前 3 条）
_total_count	integer	事件总数（脚本附加字段）

events 数组元素

参数名	类型	说明
device_id	string	设备 ID
event_id	string	事件 ID
time	string	格式化时间字符串
ai_events	string[]	AI 识别的事件标签列表
ai_scene	string	AI 描述的场景文字
pic_url	string	事件缩略图短链接（可能为空）

错误码

错误码	HTTP 状态码	说明
1001	401	未提供 api_key
1002	401	api_key 无效或已禁用
2001	400	缺少必要参数
3001	502	网关内部服务调用失败
5000	500	内部错误

注意事项

• device_ids 不能为空数组，否则返回错误码 2001
• start_date 和 end_date 格式为 yyyy-MM-dd
• query 支持自然语言
• 全局超时为 120 秒