# Home Assistant 手机推送通知：用 rest_command 实现漏水、洗衣机、门磁告警

> 用一个 rest_command 把 Home Assistant 告警推送到任意手机，支持从关键到低的优先级，还能在通知里直接点按钮关闭水阀。

*23.10.2026*

<!-- source: https://pocketalert.app/zh/blog/home-assistant-push-notifications -->

Home Assistant 的 Companion 应用对自己运行 Home Assistant 的人来说，通知功能已经很好用。但如果该知道地下室漏水的人是从没装过它的伴侣、父母，或者持有你备用钥匙的邻居，就麻烦了。为了让他们收到一条推送而给他们开一个 Home Assistant 账户，权限就给多了。

还有噪音的问题。“洗衣机已完成”和“浴室地板有水”不应该听起来一样。而且如果你的服务器告警已经通过另一个应用发送，你就得盯两个信息流。

本指南使用 Home Assistant 的 `rest_command` 通过 Pocket Alert 发送推送。它不需要任何插件或自定义集成，并涵盖三个自动化：水浸告警（关键级别）、洗衣完成（低级别），以及无人在家时门被打开。

## 准备工作

- 能访问 `configuration.yaml` 的 Home Assistant（使用 File editor 或 Studio Code Server 插件，或通过 SSH）。
- 一个 Pocket Alert 账户、来自 [API Keys](/account/apikeys) 的 API 密钥，以及需要接收告警的手机上的应用，[iPhone 或 Android](/get-app)。免费套餐每台设备每天可发送 50 条消息。

## rest_command

把密钥放进 `secrets.yaml`，与 `configuration.yaml` 位于同一文件夹：

```yaml
pocketalert_token: "YOUR_API_KEY"
```

然后在 `configuration.yaml` 中添加一个命令：

```yaml
rest_command:
  pocketalert:
    url: https://api.pocketalert.app/v1/messages
    method: post
    content_type: application/json
    timeout: 10
    headers:
      Token: !secret pocketalert_token
    payload: >-
      {% set body = {"title": title, "message": message,
                     "level": level | default("default")} %}
      {% if button_url is defined %}
        {% set req = {"url": button_url, "method": "POST"} | to_json %}
        {% set body = dict(body, actions=[{"type": "http",
              "label": button_label | default("Run"), "value": req}]) %}
      {% endif %}
      {{ body | to_json }}
```

重启 Home Assistant。现在你有了一个名为 `rest_command.pocketalert` 的操作，传入其 `data` 的内容会成为模板变量：`title`、`message`、可选的 `level`，以及可选的按钮。

为什么要用 `to_json` 构建 JSON，而不是手写？传感器名称里如果有引号，手写的字符串就会出错，而 `to_json` 会替你完成转义。Pocket Alert API 只接受 JSON，这也是设置 `content_type` 的原因：没有它，请求发出时不会带 JSON 的内容类型。

在 **Developer tools → Actions** 中测试：选择 `rest_command.pocketalert`，切换到 YAML 模式并运行：

```yaml
action: rest_command.pocketalert
data:
  title: "Hello from Home Assistant"
  message: "rest_command works"
```

推送应在一两秒内到达。

## 三个自动化

在自动化编辑器（**Edit in YAML**）中或 `automations.yaml` 里添加这些内容。把实体 ID 替换成你自己的。

### 水浸：关键

```yaml
alias: "Leak under the sink"
triggers:
  - trigger: state
    entity_id: binary_sensor.kitchen_leak
    to: "on"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Water leak: kitchen"
      message: "The sensor under the sink is wet. Check it now."
      level: critical
```

`critical` 用于那些不能等到早上的事情。在 iPhone 上，它会以独立音量播放，并穿透静音开关和勿扰模式；在 Android 上，它使用单独的通知渠道，绕过勿扰模式并占满屏幕。`critical` 属于付费套餐；在免费套餐中，同样的消息会以 `high` 送达，它仍能穿透专注模式，但无法穿透静音开关。

### 洗衣完成：低

没有“洗衣机已完成”的传感器，但带功率监测的智能插座可以告诉你：当功耗在几分钟内持续低于几瓦时，这一轮就结束了。

```yaml
alias: "Washer finished"
triggers:
  - trigger: numeric_state
    entity_id: sensor.washer_plug_power
    below: 5
    for: "00:03:00"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Washer finished"
      message: "Laundry is ready to hang."
      level: low
```

`low` 会安静送达，没有声音，也不会打断你。当你查看手机时它会出现在列表里，这恰好符合湿衣服的紧急程度。请根据你的机器调整 `below` 和 `for`：有些洗衣机在运行中途会暂停一两分钟。

### 无人在家时门被打开：高

`zone.home` 的状态是其中的人数，所以 `"0"` 表示所有人都不在家。

```yaml
alias: "Front door opened while away"
triggers:
  - trigger: state
    entity_id: binary_sensor.front_door
    to: "on"
conditions:
  - condition: state
    entity_id: zone.home
    state: "0"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Front door opened"
      message: "Opened at {{ now().strftime('%H:%M') }} and nobody is home."
      level: high
```

在 iPhone 上，`high` 会被标记为时间敏感，因此能穿透专注模式和定时发送的摘要。消息这一行是模板：`data` 中的值会在传给命令之前渲染完成。

## 关闭水阀的按钮

当你能直接操作时，漏水告警会更有用。Pocket Alert 通知最多可以带三个[操作按钮](/features/action-buttons)，而 `http` 按钮会**从手机本身**发送请求。Pocket Alert 不会代理它。这意味着只要手机能访问到，按钮就可以调用一个未对互联网开放的 Home Assistant Webhook。

首先，添加一个自动化，在其 Webhook 被调用时关闭水阀：

```yaml
alias: "Close main water valve (from push)"
triggers:
  - trigger: webhook
    webhook_id: "close-valve-9f2c41d7a3b8e605"
    allowed_methods:
      - POST
    local_only: true
actions:
  - action: valve.close_valve
    target:
      entity_id: valve.main_water
```

如果你的水阀显示为开关，就改用 `switch.turn_off`。请把 Webhook ID 设得足够长且随机：Home Assistant 的 Webhook 除了知道 ID 之外没有任何身份验证。

然后把按钮添加到漏水自动化中：

```yaml
actions:
  - action: rest_command.pocketalert
    data:
      title: "Water leak: kitchen"
      message: "The sensor under the sink is wet."
      level: critical
      button_label: "Close water valve"
      button_url: "https://ha.example.com/api/webhook/close-valve-9f2c41d7a3b8e605"
```

上面的 `rest_command` 会把 `button_url` 转换为方法为 POST 的 `http` 操作。点击按钮后，手机会在后台发送请求，无需打开应用。

使用哪个 URL：

- **仅在家中：** 你的手机在 Wi-Fi 下访问 Home Assistant 的地址。`local_only: true` 可让 Webhook 对互联网保持关闭。如果你的网络中有 `https://` 地址，建议优先使用。
- **在任何地方：** 漏水往往发生在你外出时。Home Assistant 文档指出，带 `local_only` 的 Webhook 仍然可以通过 Home Assistant Cloud（Nabu Casa）的 Webhook 工作，因此云端 URL 是最简单的选择。手机上的 VPN（例如 Tailscale 或 WireGuard）也可以配合局域网地址使用。

Home Assistant 官方建议不要把破坏性或不安全的操作放在 Webhook 后面，例如解锁门。关闭水阀是安全的方向；打开水阀则不是，因此不要把它放到手机按钮上。第二次点击会发送第二个请求，这在这里无害，因为关闭一个已关闭的水阀不会产生任何影响。

关于按钮有两点需要了解。它们属于付费套餐功能，在免费套餐中会从消息里移除，但告警本身仍会送达。另外，iOS 和 Android 都会直接在通知上显示你自定义的标签，即使 Pocket Alert 应用已关闭也是如此（2.0.1 或更高版本）。按钮也会随消息一起保存在应用中，因此横幅消失后你仍然可以点击它们。

## 给没有 Home Assistant 的人发告警

接收推送的人只需要 Pocket Alert 应用。有两种设置方式：

- **他们自己的账户。** 他们免费注册，创建 API 密钥并发送给你。再添加第二个命令 `pocketalert_family`，把他们的密钥放进 `secrets.yaml`，并在漏水自动化中同时调用这两个命令。你的服务器告警仍然留在你的账户中；他们只能看到你发给他们的内容。
- **你账户下的第二台设备。** 付费套餐包含多台设备。添加他们的手机，然后复制一份命令，并在 `body` 字典中加入 `"device_id": "THEIR_DEVICE_ID"`，这样只有家庭相关的告警会发送给他们。

无论哪种方式，他们都能收到同样级别和按钮的漏水告警，而无需你的 Home Assistant 账户。

## 一个应用管理家庭与其他一切

同一个 API 密钥也可用于 cron 任务、备份、可用性检查和 CI。如果你在运行家庭实验室，[Proxmox、NAS 和备份告警](/use-cases/homelab-alerts)会与漏水传感器进入同一个信息流，每条都有自己的级别，而且应用可以按级别过滤信息流，因此在四十条消息中也能轻松找到那两条重要的。其他传感器（ESP32 开发板、树莓派、Node-RED）请参阅[物联网与传感器告警](/use-cases/iot-sensor-alerts)。

对于只能发送 JSON Webhook 的设备，有一种无代码方案：在[控制台](/webhooks)中创建 Webhook，并根据负载模板化消息内容。请参阅 [Webhook 转推送](/tools/webhook)。

## 作为 notify 操作的 RESTful Notifications

如果你更喜欢 `notify.*` 操作，Home Assistant 的 RESTful Notifications 平台同样可以发送到 Pocket Alert：

```yaml
notify:
  - name: pocketalert
    platform: rest
    resource: https://api.pocketalert.app/v1/messages
    method: POST_JSON
    title_param_name: title
    headers:
      Token: !secret pocketalert_token
    data:
      level: high
```

`POST_JSON` 发送 JSON 请求体，`title_param_name` 将通知标题映射到我们的 `title` 字段，`data` 则添加固定字段。使用 `action: notify.pocketalert` 调用，并传入 `title` 和 `message`。级别按通知器固定，因此如果你需要多个级别，就为每个级别各创建一个；或者直接使用 `rest_command`，它还支持按钮。

## 如果什么都没收到

- **检查日志。** 请求失败时，`rest_command` 会记录一条带状态码的警告。`401` 表示 `secrets.yaml` 中的密钥有误；`400` 通常表示负载不是有效的 JSON。
- **第一次要重启。** 第一个 `rest_command` 配置块需要重启 Home Assistant 后操作才会出现；之后的修改可通过 `rest_command.reload` 操作加载。
- **手动运行操作。** 在 Developer tools 中运行。如果这样可以，问题出在自动化的触发器或条件上，请检查它的追踪记录。
- **按钮没反应：** 在手机浏览器中打开 Webhook URL 的主机。如果手机无法访问该地址处的 Home Assistant，按钮也就无法工作。
- **检查当日配额。** 免费套餐每天上限为 50 条消息，一个频繁触发的传感器很容易耗尽它。在触发器上加一个 `for:` 会有所帮助。

## 常见问题

### 我需要 Home Assistant Companion 应用吗？

不需要。推送来自 Pocket Alert，因此手机只需要安装 Pocket Alert 应用。你仍然可以保留 Companion 应用，用于它的传感器和位置追踪功能。

### 这能与 Home Assistant Cloud 一起使用吗？

可以。`rest_command` 直接从你的 Home Assistant 调用 Pocket Alert API，因此不依赖 Nabu Casa。只有在你不在家时，Home Assistant Cloud 才会对水阀按钮有帮助。

### 漏水告警能在夜里把我叫醒吗？

在 `critical` 级别下可以：在 iPhone 上它会穿透静音开关，在 Android 上会穿透勿扰模式。该级别需要付费套餐；在免费套餐中，它会以 `high` 送达。

### 我的 API 密钥会暴露吗？

密钥保存在 `secrets.yaml` 中，并通过 HTTPS 在 `Token` 请求头中发送。请为 Home Assistant 单独使用一个密钥，这样你可以撤销它而不影响其他脚本。

[免费注册账户](/signup)，添加一个 `rest_command`，让家里在需要你的时候告诉你。
