首页 ▸ Integrations ▸

Google 助理

google_assistant 集成允许您通过移动设备、平板电脑或 Google Home 设备上的 Google 助理控制您的 Home Assistant 设备。

如果您希望向 Google 助理发送命令以控制 Google 助理支持但 Home Assistant 不支持的设备，或者在不中断音乐/视频播放的情况下向 Google 助理扬声器和显示器广播消息，请查看 Google 助理 SDK 集成。

通过 Home Assistant Cloud 自动设置

使用 Home Assistant Cloud，您可以通过简单的几次点击将您的 Home Assistant 实例连接到 Google 助理。使用 Home Assistant Cloud，您无需处理动态 DNS、SSL 证书或在路由器上打开端口。只需通过用户界面登录，即可与云建立安全连接。Home Assistant Cloud 在 30 天免费试用后需要付费订阅。

对于 Home Assistant Cloud 用户，可以在此处找到文档。

手动设置（如果您没有 Home Assistant Cloud）

Google 助理集成（没有 Home Assistant Cloud）由于 Google 要求设置助理应用程序的方式，比大多数集成需要更多的设置。

先决条件

要使用 Google 助理，您的 Home Assistant 配置必须通过主机名和 SSL 证书外部可访问。

如果您尚未配置，请在继续之前完成此操作。
如果您通过 DNS 更改实现此目的，请确保您已等待最多 48 小时以使 DNS 更改生效，否则 Google 可能无法访问您的服务器。
一旦您确认可以从家庭网络外部访问您的 Home Assistant，您就可以设置 Google 集成：

Google Cloud Platform 配置

在 Google Developer Console 中创建一个新项目。
1. 选择 创建项目
2. 在 开始使用 页面上，选择 创建项目。
  - 为您的项目命名并选择 创建项目。
3. 保存您的项目 ID（在主项目名称下方）以供下面使用。
4. 选择 添加云到云集成。
5. 在右下角，选择 下一步：开发，然后选择 下一步：设置。
6. 选择所有适用的设备类型（您可以选择全部）。
7. 创建一个 144 x 144 像素的应用图标并上传。
8. 在 帐户链接 下，在 OAuth 客户端 ID 字段中，输入 https://oauth-redirect.googleusercontent.com/r/[YOUR_PROJECT_ID]。
9. 将 [YOUR_PROJECT_ID] 替换为上面的项目 ID。
10. 填写详细信息：
  - 在 客户端密钥 字段中，添加任意字符串（不含特殊字符）。Home Assistant 不需要此字段。
  - 在 授权 URL 字段中，输入 https://[yourdomain:port]/auth/authorize。
  - 在 令牌 URL 字段中，输入 https://[yourdomain:port]/auth/token。
  - 在 云履行 URL 字段中，输入 https://[yourdomain:port]/api/google_assistant。
  - 目前，跳过 本地履行 和 应用翻转。
  - 在范围下，输入 email。选择 添加范围 并输入 name。
  - 保持 让 Google 通过 HTTP 基本身份验证头传输客户端 ID 和密钥 复选框未选中/清除。
  - 选择保存。
    - 结果：您将看到您的项目已保存，状态为草稿。
    - 您不需要测试。
在项目的左侧菜单中，选择分析链接。
- 选择左上角的汉堡菜单并选择 API 和服务。
启用设备同步（请参阅下面的更多信息）。
1. 在左侧菜单中，选择凭据。
2. 在凭据视图中，选择 创建凭据，然后选择 服务帐户。
  1. 服务帐户名称：为您的帐户选择一个自选名称。
  2. 选择 创建并继续。
  3. 在 选择角色 下，选择 服务帐户 > 服务帐户令牌创建者。
  4. 选择继续，然后选择完成。
3. 在 服务帐户 下，现在应该有一个名为 [name from 3.2.1]@[projectname].iam.gserviceaccount.com 的帐户。
4. 选择该服务帐户的铅笔按钮。
5. 转到密钥并 添加密钥。
6. 以 JSON 格式创建一个私钥。
7. 这将开始下载一个 JSON 文件。
  1. 将文件重命名为 SERVICE_ACCOUNT.JSON。
  2. 在 Home Assistant 中，将此文件添加到您的配置文件夹中。这将是与 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 相同的文件夹。
8. 转到顶部中间的 搜索 (/) 资源、文档、产品等 并搜索 Homegraph API 并选择它。
9. 启用 HomeGraph API。
将 google_assistant 集成配置添加到您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中，并按照下面的配置指南重新启动 Home Assistant。
在 Google Home 应用中添加服务（请注意，应用版本可能略有不同）。
1. 打开 Google Home 应用。
2. 选择底部的设备选项卡，然后选择右下角的 + 添加 按钮。
3. 在 选择设备 屏幕中，选择 与 Google Home 配合使用。您应该在 添加新设备 下看到 [test] <Action Name>。选择它应该会引导您登录到您的 Home Assistant 实例，然后重定向回一个屏幕，您可以在其中为您的设备设置房间和昵称（如果需要）。

Important

如果您已将 Home Assistant 添加到手机的主屏幕，您必须先将其从主屏幕中删除。否则，此 HTML5 应用程序将显示而不是浏览器。使用它会阻止 Home Assistant 重定向回 Google Home 应用。

允许其他用户

如果您希望允许其他家庭用户控制设备：

打开您在 Google Developer Console 中创建的项目。
选择页面顶部的成员。这会将您重定向到 Google Cloud Platform IAM 权限页面。
选择页面中间的 授予访问权限。
1. 输入您要添加的用户的电子邮件地址。
2. 选择 选择角色 并选择项目 > 查看者。
3. 选择保存。
4. 将项目链接 (https://console.home.google.com/projects/YOUR_PROJECT_ID) 复制并分享给新用户。
让新用户使用他们自己的 Google 帐户打开链接，同意 服务条款 弹出窗口。
让新用户转到他们的 Google 助理 应用程序，将 [test] your app name 添加到他们的帐户。

利用设备同步

您现在可以支持向 Google 服务器主动报告状态（配置选项 report_state）并使用 Google Home 应用同步 Home Assistant 设备（google_assistant.request_sync 服务）。

试试“OK Google，同步我的设备” - Google Home 应用应该会导入您公开的 Home Assistant 设备，并提示您将它们分配到房间。

启用本地履行

Google 助理设备可以将其命令本地发送到 Home Assistant，从而更快地响应。

您的 Home Assistant 实例需要连接到与您正在交谈的 Google 助理设备相同的网络，以便通过 mDNS 发现（UDP 广播）进行发现。

您的 Google 助理设备仍将通过互联网进行通信：

获取凭据以建立本地连接。
发送涉及安全设备的命令。
如果本地履行失败，则发送命令。

Important

HTTP 集成必须不配置为使用带有 ssl_certificate 选项的 SSL 证书。

这是因为 Google 助理设备将直接连接到您的 Home Assistant 实例的 IP，如果遇到无效的 SSL 证书将失败。

对于安全的远程访问，请使用反向代理，例如 NGINX SSL 插件，而不是将外部流量直接引导到 Home Assistant。

打开您在 Google Developer Console 中创建的项目。
展开左侧的 云到云 菜单，选择开发，然后选择您的集成旁边的编辑。
向下滚动并启用 本地履行
上传 Javascript 文件
1. 从此处下载 app.js
2. 选择 上传您的 JavaScript 目标 Node 并上传步骤 4.1 中的 app.js。
3. 选择 上传您的 JavaScript 目标 Chrome（浏览器） 并上传步骤 4.1 中的相同 app.js。
选中 支持本地查询 复选框。
添加设备扫描配置：
1. 如果没有配置，请选择 + 添加扫描配置。
2. 对于发现协议，选择 mDNS。
3. 将 输入 mDNS 服务名称 设置为 _home-assistant._tcp.local
4. 选择 添加字段，然后在 选择字段 下，选择名称。
5. 将新的值字段设置为 .*\._home-assistant\._tcp\.local
向下滚动页面并保存更改。
等待 30 分钟，或重新启动所有 Google 助理设备。
重新启动 Home Assistant Core。
使用 Google 助理设备，尝试说“OK Google，同步我的设备。” 这有助于避免问题，特别是如果您在添加云 Google 助理支持后某个时间启用本地履行。

您可以按照这些说明进行调试。

YAML 配置

现在将您的设置添加到您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中，例如：

# 示例 configuration.yaml 条目
google_assistant:
  project_id: YOUR_PROJECT_ID
  service_account: !include SERVICE_ACCOUNT.JSON
  report_state: true
  exposed_domains:
    - switch
    - light
  entity_config:
    switch.kitchen:
      name: CUSTOM_NAME_FOR_GOOGLE_ASSISTANT
      aliases:
        - BRIGHT_LIGHTS
        - ENTRY_LIGHTS
    light.living_room:
      expose: false
      room: LIVING_ROOM

Configuration Variables

Looking for your configuration file?

project_id string Required

来自 Actions on Google 控制台的项目 ID（看起来像 words-2ab12）

secure_devices_pin string (Optional)

与安全设备交互时要说的 PIN 码。

service_account map Required

服务帐户信息。您可以使用包含语句与下载的 JSON 文件，直接在此处输入数据或使用秘密文件填充。

private_key string Required

PEM 格式的私钥

client_email string Required

服务电子邮件地址

report_state boolean (Optional, default: false)

主动报告实体的状态变化。这加快了影响多个实体的操作的响应时间，因为 Google 助理预先知道它们的状态。它也是某些视觉控制功能所必需的。

expose_by_default boolean (Optional, default: true)

默认情况下公开所有支持域中的设备。如果设置了 exposed_domains 域，则仅默认公开这些域。如果 expose_by_default 设置为 false，则必须在 entity_config 中手动公开设备。

exposed_domains list (Optional)

如果 expose_by_default 设置为 true，则公开给 Google 助理的实体域列表。如果 expose_by_default 设置为 false，则此设置无效。

entity_config map (Optional)

Google 助理的实体特定配置

YOUR_ENTITY_ID map (Optional)

要配置的实体

name string (Optional)

在 Google 助理中显示的实体名称

expose boolean (Optional, default: true)

强制公开/排除实体。

aliases list (Optional)

也可以用来指代此实体的别名

room string (Optional)

允许将此设备与 Google 助理中的房间关联。

可用域

目前，以下域可用于 Google 助理，列出了它们的默认类型：

alarm_control_panel (arm/disarm)
button (scene)
camera (streaming, requires compatible camera)
climate (on/off, temperature setting, hvac_mode)
cover (on/off/set position/stop/start=toggle cover)
event (only entities with device class doorbell are supported)
fan (on/off/speed percentage/preset mode)
group (on/off)
humidifier (humidity setting/on/off/mode)
input_boolean (on/off)
input_button
input_select (option/setting/mode/value)
light (on/off/brightness/rgb color/color temp)
lock
media_player (on/off/set volume (via set volume)/source (via set input source)/control playback)
scene (on)
script (on)
select
sensor (temperature setting for temperature sensors and humidity setting for humidity sensors)
switch (on/off)
vacuum (dock/start/stop/pause)
valve (open/close/set position/stop/start=toggle valve)
water_heater (on-off/temperature setting/operation mode)

Note

某些设备可能无法在 Google Home 应用中正确显示，例如 media_player，但语音命令仍然有效。

安全设备

某些设备被认为是安全的。这包括 lock 域中的设备、alarm_control_panel 域中的设备以及设备类型为 door、garage 或 gate 的 covers。

默认情况下，除非设置了 secure_devices_pin 代码，否则 Google 助理无法打开安全设备。要允许打开，请将 secure_devices_pin 设置为某个值。然后在打开设备时会提示您说出 PIN。关闭或锁定这些设备不需要 PIN。

如果为报警控制面板设置了代码，则它必须与 secure_devices_pin 相同。如果 code_arm_required 设置为 false，系统将在不提示输入 PIN 的情况下进行布防。

房间/区域支持

未明确分配到房间但已放置在 Home Assistant 区域中的实体将返回带有这些区域中设备的房间提示给 Google。

Note

某些设备（例如 scene 或 script）必须分配到 area，然后共享 Google Home 家庭的其他成员才能使用它们。这是因为在共享的 Google Home 中，家庭成员将无法查看未分配到房间的设备，除非他们是将服务链接到 Google Home 的用户。这个问题并不明显，因为 script 和 scene 设备在 Google Home 主仪表板中不可见。

当您的 Google 帐户中设置了多个家庭时，自动房间分配将不起作用。

气候操作模式

Home Assistant 和 Google 助理之间的可用操作模式没有完全的 1 对 1 匹配。以下是当前可用的模式：

off
heat
cool
heatcool (auto)
fan-only
dry
eco

电视频道

Home Assistant 中没有电视频道对象。电视频道只能通过数字更改，而不能通过名称更改（例如，“转到频道二”）。

故障排除

请求同步时的 404 错误

由于您的 Actions on Google 应用实际上处于测试模式且从未发布，Google 助理的同步可能会在一段时间后失败，可能大约 30 天。设备控制将继续工作，但同步可能不会。如果您说“Ok Google，同步我的设备”并收到响应“无法同步 Home Assistant”（或您命名的项目），通常可以通过返回到 Actions on Google 控制台中的测试应用并单击 模拟器 下的 测试 来解决。重新生成草稿版本的测试应用并尝试再次要求 Google 同步您的设备。如果重新生成草稿不起作用，请返回到 操作 部分并仅按 enter 键以重新创建预览。

从 Home Assistant 同步将始终有效，并将自动更新实体更改。

request_sync 服务要求来自 Google 的初始同步包含 agent_user_id。如果没有，服务将记录一个错误，内容类似于“请求包含无效参数”。如果发生这种情况，请取消链接帐户并重新链接。

如果 HomeGraph API 的 project_id 与 Actions on Google 控制台中的 Actions SDK 的 project_id 不同，则 request_sync 服务可能会失败并显示 404。通过以下方式解决此问题：

从 Google Cloud API 控制台中删除您的项目。
将新项目添加到 Actions on Google 控制台在此处，您将获得一个新的 project_id。
运行前面提到的 [Actions on Google 控制台] 设置说明，直到创建 service_account 的步骤。
一旦您开始在 [Google Cloud API 控制台] 中创建新的 service_account，请确保通过验证 project_id 选择在 [Actions on Google 控制台] 中创建的项目。
启用 HomeGraph API 到新项目。

验证 Google 助理是否可在 https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant 上使用如果它正常工作，则在浏览器或通过 curl 打开时应返回 405: Method Not Allowed。

请求同步时的 403 错误

如果未启用 HomeGraph API，则 request_sync 操作可能会失败并显示 403。转到 Google API 控制台并验证 HomeGraph API 是否已为您的项目启用。

报告状态时的 404 错误

如果您在日志中收到与报告状态相关的 404 错误，Home Assistant 正在报告从未同步到 Google 的实体的状态。请让您的 Google Home 同步我的设备 或运行 google_assistant.request_sync 操作。

链接期间出错：“无法更新设置。请检查您的连接”

您的履行 URL 可能无效或无法访问。重新检查手动设置中指定的 履行 URL 并验证它是否可公开访问。

请求同步时的 500 / 429 错误

如果服务密钥无效，可能会发生此错误。尝试删除并创建一个新的服务帐户和密钥。

NGINX

使用 NGINX 时，请确保您的 proxy_pass 行没有结尾 /，因为这会导致错误。您的行应如下所示：

proxy_pass http://localhost:8123;

取消链接并重新链接

如果您在取消链接服务后遇到 帐户链接失败 问题，请尝试清除浏览器历史记录和缓存。

链接失败 - 无法更新设置。请检查您的连接

如果您在登录到 Home Assistant 实例后遇到链接帐户问题，错误消息为 无法更新设置。请检查您的连接，请尝试设置 expose_by_default: false，然后公开单个简单设备（最好是灯或开关）。如果您遇到问题，还值得检查是否禁用了任何家庭广告拦截器。

帮助我们改进翻译

建议编辑此页面，或提供/查看此页面的反馈。

编辑提供反馈查看待处理的反馈