ninebot-device-skill（Ninebot 设备技能）

九号电动车辆信息查询服务 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 映射模板。