ninebot-device-skill

九号电动车(Ninebot)车辆信息查询，支持九号电动车、九号电动摩托车，提供车辆开关机状态、车辆充电状态、车辆位置、车辆剩余电量、车辆剩余里程、车辆剩余充电时间等数据的查询功能

Security Scan

The skill is internally consistent with its stated purpose: it only requests a Ninebot Device Service API key and contains a small script and docs to call Ninebot's API to fetch vehicle info.

Purpose & Capability

Name/description, required env var (NINEBOT_DEVICESERVICE_KEY), included script, and referenced API host (cn-cbu-gateway.ninebot.com) all align with a Ninebot vehicle-info query skill. There are no unrelated credentials, binaries, or services requested.

Instruction Scope

SKILL.md instructs the agent to prompt for an API key, read NINEBOT_DEVICESERVICE_KEY from env or config.json in the current working directory, and run scripts/ninebot_query.py. It also instructs editing references/api-spec.md and config.json to change mappings. These actions are within the stated scope but include saving the API key to a local plaintext config.json (a privacy/secret-storage concern). The instructions do not request other system files or unrelated data.

Install Mechanism

No install spec is provided (instruction-only with an included script). Nothing is downloaded or installed by the skill itself, so no high-risk install behavior is present.

Credentials

Only one credential is required: NINEBOT_DEVICESERVICE_KEY, which is the expected credential for this API. This is proportionate. Caveat: SKILL.md and the script recommend saving the API key in config.json (plaintext), which increases risk if that file is not protected.

Persistence & Privilege

always is false and the skill does not request persistent system privileges or modifications to other skills. It may write/expect a local config.json in the working directory (normal for this use case).

Assessment

This skill appears to do what it claims: query Ninebot's Device Service using a single API key. Before installing/providing your key: (1) only provide the NINEBOT_DEVICESERVICE_KEY if you trust the publisher and you actually have a Ninebot/OpenClaw key; (2) prefer using an environment variable rather than storing the key in a plaintext config.json file in a shared folder; (3) review the base URL (https://cn-cbu-gateway.ninebot.com) and confirm it matches Ninebot's official API for your region; (4) be aware of a minor implementation bug: the script expects an API success code of 0 while the included API examples use 1, which may cause errors—consider reviewing the code if you encounter unexpected failures. If the skill asked for additional unrelated credentials, unknown download URLs, or network hosts other than the Ninebot gateway, treat it as suspicious.

九号电动车辆信息查询服务 Skill

九号电动车辆信息查询服务向开发者提供完整的车辆信息查询服务，包括车辆状态、位置、电量等信息的查询功能。

功能特性

• 九号电动车开关机状态、充电状态查询
• 九号电动车剩余电量、剩余里程、剩余充电时间查询
• 九号电动车位置查询
• 支持多设备查询和选择

首次配置

首次使用时需要配置九号 Device Service Key:

1. 报名参加九号OpenClaw内测活动获取 Key，详情关注九号出行APP「圈子」。
2. 设置环境变量：export NINEBOT_DEVICESERVICE_KEY=your_key
3. 或运行时自动提示输入并保存到本地配置文件

当用户想要查询九号电动车辆信息（如开关机状态、充电状态、剩余电量、剩余里程、剩余充电时间、位置等）时，使用此 skill。

触发条件

用户表达了以下意图之一：

• 查询九号车辆开关机状态、充电状态（如"查询小九的开关机状态"、"小白正在充电吗"）
• 查询九号车辆剩余电量、剩余里程、剩余充电时间（如"小九还有多少电量"、"小白还能跑多远"）
• 查询九号车辆位置（如"小九现在在哪里"、"小白的位置"）

执行步骤

第一步：检查 API Key

• 如果用户已经配置好了环境变量 NINEBOT_DEVICESERVICE_KEY 或在本地 config.json 中提供了 Key，直接使用该 Key 进行后续 API 调用。
• 如果用户之前未提供过 Key，先提示用户提供九号 Device Service Key，等待用户回复后再继续
• 如果用户已提供 Key，直接使用

请求 Key 的回复模板：

🔑 查询九号车辆位置需要九号 Device Service Key，请提供你的 Key。

（报名参加九号OpenClaw内测活动并取得内测资格即可获取，详情关注九号出行APP「圈子」动态）

第二步：获取API Key

优先读取环境变量 NINEBOT_DEVICESERVICE_KEY，其次从本地 config.json 读取。也支持在命令行显式传入 --api-key。 请求头使用 Authorization: Bearer <API_KEY>。 参考 config.example.json 作为配置样例。

config.json 示例：

{
  "apiKey": "your_ninebot_device_service_key_here"
}

第三步：运行查询脚本

• 使用指定的脚本执行端到端的流程：

export NINEBOT_DEVICESERVICE_KEY=your_key_here
python3 scripts/ninebot_query.py \
  --lang "zh" \
  --device-name "小九"

• 如果脚本执行401 Unauthorized错误，说明 API Key 无效或未提供，提示用户提供有效的 API Key，等待用户回复后再继续。回复文案见下方「错误码与消息处理」。
• 如果脚本返回错误码/错误消息（如智能服务费到期），提示用户相应的错误信息和解决方案，等待用户回复后再继续。回复文案见下方「错误码与消息处理」。
• 如果账户有多个设备且未提供选择，脚本会返回一个列表供用户选择：

{"choose_device": [{"sn":"SN123","name":"小九"},{"sn":"SN456","name":"小白"}]}

然后使用 --device-name 或 --device-sn 重新运行脚本。

错误码与消息处理

当脚本返回错误码/错误消息时，使用以下固定回复文案：

• 401 Unauthorized → 🔑 提供的 API Key 无效，请检查后重新提供。
• "code":651001,"msg":"您的车辆智能服务费已到期" → ⚠️ 您的车辆智能服务费已到期（sn:XXXXXXXXXXXX），车辆数据查询功能已暂停。请登录九号出行APP完成续费，成功后功能将自动恢复。

说明：若有设备 SN，请将 XXXXXXXXXXXX 替换为实际 SN。

第四步：解析输出

脚本输出 JSON：

{
  "device_name": "九号电动E200P",
  "battery": 57,
  "powerStatus": "OFF",
  "chargingStatus": "not_charge",
  "location": "北京市海淀区东升(地区)镇后屯东路",
  "estimateMileage": 50.4,
  "remainChargingTime": ""
}

第五步： API 映射和配置

根据实际的九号 Device Service API 规范，更新 config.json 中的 API 映射配置，或直接更新 references/api-spec.md 中的 API 规范并同步更新 config.json。 使用以下方式更新 API 映射：

• 编辑 config JSON 并通过 --config 参数传入
• 编辑 references/api-spec.md 中的 API 规范，并将更改镜像到 config JSON 中

配置规范详细说明请参考 references/api-spec.md，其中包含了 API 规范和 config 映射的模板。

配置管理

配置文件位于 config.json，包含以下内容：

{
  "apiKey": "your_ninebot_device_service_key_here"
}

设置 Key 的方式：

1. 环境变量：export NINEBOT_DEVICESERVICE_KEY=your_key
2. 自动提示：首次运行时自动提示输入
3. 手动编辑：直接编辑 config.json 文件

资源

scripts/

• ninebot_query.py — 查询电动车信息脚本.

references/

• api-spec.md — API 规范和 config 映射模板。