Skip to content

AI Integration

Jump to bottom
Justin Gu edited this page May 1, 2026 · 2 revisions

AI Agent 集成指南

米家控制系统提供标准 REST API，任何能发起 HTTP 请求的 AI Agent 框架都可以直接对接，实现自然语言控制智能家居。

核心思路

用户语音/文字 → AI Agent → REST API → 米家设备

AI Agent 只需要：

  1. 一个有效的 JWT Token
  2. 调用 HTTP API 的能力
  3. 理解设备属性和动作的语义映射

认证配置

获取 JWT Token

# 方式一：CLI 登录获取
mijia-control login

# 方式二：API 登录获取
curl -X POST http://127.0.0.1:5000/api/auth/jwt/login \
  -H "Content-Type: application/json" \
  -d '{"username": "myuser", "password": "123456"}'

响应中的 access_token 即为 Agent 所需的 Bearer Token，有效期 24 小时。

使用 API Token（推荐）

为 Agent 创建专用的 API Token，避免使用用户密码：

  1. 登录 Web UI → 设置 → API Token
  2. 创建新 Token，命名为 "My Agent"
  3. 将生成的 Token 配置到 Agent 中
# 或通过 API 创建
curl -X POST http://127.0.0.1:5000/api/tokens/ \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "permissions": "read_write"}'

MCP Server（推荐）

本项目内置 MCP Server，支持 Claude Code、Hermes Agent 等任何兼容 MCP 协议的 AI Agent 直接调用，无需手动编写 HTTP 请求。

安装

pip install -e ".[mcp]"

环境变量

export MIJIA_API_URL=http://127.0.0.1:5000/api
export MIJIA_TOKEN=eyJhbGci...   # JWT Token 或 API Token

Claude Code 中使用

# 注册 MCP 服务器
claude mcp add mijia -- python -m mcp_server

# 之后在对话中直接说
# "帮我把客厅的灯关掉"
# "查看所有设备的在线状态"
# "执行回家场景"

可用工具

工具 功能
list_devices 列出所有设备
get_device 查看设备详情与规格（属性列表、动作列表）
get_property 读取设备属性（亮度、温度、开关状态等）
set_property 设置设备属性（开灯、调亮度、设温度等）
run_action 执行设备动作（开始清扫、回充等）
list_scenes 列出所有场景
run_scene 执行场景
list_homes 列出所有家庭
get_home 查看家庭详情

其他 MCP 客户端

任何支持 MCP 协议的客户端都可以连接。服务启动命令：

python -m mcp_server

OpenClaw 集成

OpenClaw 是一个开源 AI Agent 框架，支持通过 HTTP 工具调用外部 API。

配置工具定义

在 OpenClaw 的工具配置中添加：

{
  "tools": [
    {
      "name": "mijia_list_devices",
      "description": "列出米家智能家居设备",
      "url": "http://127.0.0.1:5000/api/devices/",
      "method": "GET",
      "headers": {
        "Authorization": "Bearer ${MIJIA_TOKEN}"
      }
    },
    {
      "name": "mijia_set_property",
      "description": "设置米家设备属性，如开关灯、调亮度等",
      "url": "http://127.0.0.1:5000/api/devices/{did}/props/{prop_name}",
      "method": "PUT",
      "headers": {
        "Authorization": "Bearer ${MIJIA_TOKEN}",
        "Content-Type": "application/json"
      },
      "body": {
        "value": "{value}"
      }
    },
    {
      "name": "mijia_run_scene",
      "description": "执行米家场景",
      "url": "http://127.0.0.1:5000/api/scenes/{scene_id}/run",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer ${MIJIA_TOKEN}"
      }
    }
  ]
}

环境变量

export MIJIA_TOKEN=eyJhbGci...

Hermes Agent 集成

Hermes Agent 支持通过 OpenAPI/Swagger 规范自动生成工具调用。

直接使用 Swagger 文档

本项目已内置 Swagger UI，Agent 可直接读取 API 规范：

GET http://127.0.0.1:5000/api/docs/

Swagger JSON 地址：

GET http://127.0.0.1:5000/apispec_1.json

将此 URL 配置到 Hermes Agent 的 API 规范源中即可自动注册所有工具。

手动配置示例

# hermes-config.yaml
tools:
  - name: mijia_control
    type: openapi
    spec_url: http://127.0.0.1:5000/apispec_1.json
    auth:
      type: bearer
      token: ${MIJIA_TOKEN}

通用集成方案

任何支持 HTTP 调用的 Agent 框架都可以按以下模式集成。

第一步：发现设备

# 获取所有设备
curl http://127.0.0.1:5000/api/devices/ \
  -H "Authorization: Bearer <token>"

返回的每个设备包含 did（设备ID）、名称、型号和可用的属性/动作列表。

第二步：读取状态

# 读取设备属性
curl http://127.0.0.1:5000/api/devices/<did>/props/<prop_name> \
  -H "Authorization: Bearer <token>"

第三步：控制设备

# 设置属性
curl -X PUT http://127.0.0.1:5000/api/devices/<did>/props/<prop_name> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"value": <value>}'

# 执行动作
curl -X POST http://127.0.0.1:5000/api/devices/<did>/actions/<action_name> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"value": {}}'

# 执行场景
curl -X POST http://127.0.0.1:5000/api/scenes/<scene_id>/run \
  -H "Authorization: Bearer <token>"

常见设备控制映射

以下是一些常见设备的属性名称参考（具体以 device show 返回的 spec 为准）：

灯光控制

属性 power: "on" / "off"        — 开关
属性 brightness: 0-100          — 亮度
属性 color_temperature: 2700-6500  — 色温

# 开灯
curl -X PUT .../devices/<did>/props/power -d '{"value": "on"}'

# 调亮度到 80%
curl -X PUT .../devices/<did>/props/brightness -d '{"value": 80}'

空调控制

属性 power: "on" / "off"
属性 temperature: 16-30
属性 mode: "cool" / "heat" / "auto" / "fan"
属性 fan_level: 1-4

扫地机器人

动作 start-sweep    — 开始清扫
动作 stop-sweeping  — 停止
动作 start-charge   — 回充
属性 status         — 当前状态
属性 battery_level  — 电量

插座 / 开关

属性 power: "on" / "off"

Prompt 模板

为 AI Agent 编写系统提示时，可以参考以下模板：

你是一个智能家居控制助手。用户会告诉你他们想要做什么，
你需要将其转化为米家 API 调用。

可用操作：
1. 列出设备：GET /api/devices/
2. 读取属性：GET /api/devices/{did}/props/{prop_name}
3. 设置属性：PUT /api/devices/{did}/props/{prop_name}
4. 执行动作：POST /api/devices/{did}/actions/{action_name}
5. 执行场景：POST /api/scenes/{scene_id}/run
6. 列出场景：GET /api/scenes/

规则：
- 控制设备前先确认目标设备的 did
- 操作完成后汇报结果
- 如果不确定用户的意图，先询问
- 所有请求需携带 Authorization: Bearer <token>

安全建议

  • 为每个 Agent 创建独立的 API Token
  • 使用 read_only 权限的 Token 用于只查询场景
  • 避免在 Prompt 中硬编码 Token
  • 定期轮换 Token
  • 如果 Agent 部署在公网，确保 API 使用 HTTPS

下一步：Development — 开发与贡献指南。

Clone this wiki locally