OpenClaw Home Assistant スキルガイド

OpenClaw Home Assistant スキル概要

Home AssistantスキルはOpenClawをHome Assistantインスタンスに接続し、AIエージェントを強力なスマートホームコントローラーに変えます。ダッシュボードを操作したりYAML設定ファイルを編集する代わりに、自然言語でスマートホーム全体を管理できます——照明の切り替え、センサー値の確認、オートメーションの作成、デバイス問題のトラブルシューティングまで、すべてターミナルから実行できます。

Home Assistantは世界最大のオープンソースホームオートメーションプラットフォームであり、Philips Hue、Zigbee、Z-Wave、Matterなど2,000以上のデバイス統合をサポートしています。OpenClaw Home AssistantスキルはHome Assistant REST APIを活用し、インスタンス上で動作するエンティティ、サービス、オートメーション、スクリプトへの直接アクセスをエージェントに提供します。

典型的なワークフロー：

1. OpenClawにリビングの照明をすべてオフにし、サーモスタットを20°Cに設定するよう依頼する。
2. エージェントがHome Assistant APIを呼び出し、該当するエンティティを特定してサービスコールを実行する。
3. 確認が即座に返される——Home Assistantアプリやダッシュボードを開く必要はありません。

このスキルは、すでにHome Assistantを運用しており、スマートホームへのより高速でスクリプト可能なアクセスを求める開発者に最適です。Slackスキルと組み合わせてスマートホーム通知をチームチャンネルに送信したり、Home Assistantをコンテナで実行している場合はDockerベースのデプロイと自然に統合できます。

Home Assistant スキルの前提条件

Home Assistantスキルをインストールする前に、以下を確認してください：

• OpenClawがインストールされ実行中（v1.0+）
• ネットワーク経由でアクセス可能なHome Assistantインスタンス（v2023.1+）——インストールガイド
• Home Assistantプロフィールから生成した長期アクセストークン
• マシンからHome Assistantインスタンスへのネットワークアクセス（ローカルまたはリモート）
• スキル管理用のclawhub CLIをインストール済み

セットアップを確認：

# OpenClawのバージョンを確認
openclaw --version

# Home Assistant APIの接続性をテスト
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://YOUR_HA_HOST:8123/api/ | head -1

# clawhub CLIを確認
clawhub --version

APIが{"message": "API running."}を返せば、Home Assistantインスタンスの準備は完了です。

Home Assistant スキルのインストール方法

Home Assistantスキルを1つのコマンドでインストール：

npx clawhub@latest install home-assistant

インストールを確認：

clawhub list

インストール済みスキルのリストにhome-assistantが表示されるはずです。最速のセットアップにはclawhub CLIでインストールしてください。

Home Assistant スキルの設定

このスキルではAPI リクエストの認証にHome AssistantのURLと長期アクセストークンが必要です。

長期アクセストークンの生成

1. Home Assistantダッシュボードをhttp://YOUR_HA_HOST:8123で開きます。
2. プロフィールアイコン（左下隅）をクリックします。
3. 長期アクセストークンまでスクロールし、トークンを作成をクリックします。
4. openclaw-agentと名前を付け、生成されたトークンをコピーします。

環境変数の設定

以下の環境変数を設定してください：

# Home AssistantインスタンスURL（非標準の場合はポートを含む）
export HOMEASSISTANT_URL="http://192.168.1.100:8123"

# 長期アクセストークン
export HOMEASSISTANT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6..."

シェルプロファイル（~/.bashrc、~/.zshrc）に追加するか、シークレットマネージャーと共に.envファイルを使用できます。

**重要：**トークンを設定ファイルにハードコードしたり、バージョン管理にコミットしないでください。環境変数または1Passwordのような専用のシークレットマネージャーを使用してください。

オプション：リモートアクセス

Home Assistantインスタンスが同じネットワーク上にない場合、以下の方法でリモートアクセスを設定してください：

| 方法 | 説明 | |------|------| | Nabu Casa | Home Assistant Cloud——最も簡単な方法、リモートURLを提供 | | リバースプロキシ | NginxまたはCaddyによるSSLターミネーション | | Tailscale/WireGuard | 安全なLANのようなアクセスのためのVPNトンネル |

Home Assistant スキルの使用例

1. 照明とデバイスの制御

あなた：「寝室の照明をすべてオフにして、リビングの明るさを40%に設定して。」

エージェントは寝室のエンティティに対してlight.turn_offを呼び出し、リビングの照明にはbrightness_pct: 40でlight.turn_onを呼び出します。ルーム割り当てでエンティティを特定し、確認サマリーを返します。

2. センサーデータの取得

あなた：「オフィスの現在の温度と今日の総エネルギー使用量を教えて。」

エージェントはsensor.office_temperatureとsensor.energy_dailyエンティティを照会し、フォーマットされた値を返します：「オフィスの温度：22.3°C。今日のエネルギー使用量：14.7 kWh。」単位変換を処理し、読みやすい形式でデータをフォーマットします。

3. オートメーションの作成

あなた：「日没時にポーチライトを点灯し、毎晩23時にオフにするオートメーションを作成して。」

エージェントは日没用のsunトリガーと23:00用のtimeトリガーを使用してHome Assistantオートメーションを構築します。API経由でオートメーションを登録し、わかりやすい名前を付けて、有効化されていることを確認します。

4. シーンの有効化

あなた：「映画鑑賞シーンを有効にして。」

エージェントはscene.movie_nightに対してscene.turn_onを呼び出します。これにより照明が暗くなり、ブラインドが閉まり、メディアプレーヤーが正しい入力に設定されます——すべて既存のシーン定義で設定済みです。

5. デバイスステータスのトラブルシューティング

あなた：「現在利用不可またはオフラインのデバイスはどれ？」

エージェントはunavailableまたはunknown状態のすべてのエンティティを照会し、統合別にグループ化して診断レポートを返します：「3台のデバイスがオフライン——Zigbeeモーションセンサー（最終確認2時間前）、キッチンのスマートプラグ（到達不能）、天気統合（APIタイムアウト）。」

セキュリティとベストプラクティス

スマートホームを安全に保つために、以下のガイドラインに従ってください：

• **最小権限の原則を使用。**OpenClaw用に専用のHome Assistantユーザーを作成し、エージェントが制御する部屋やデバイスに権限を限定してください。管理者アカウントのトークンの使用は避けてください。
• **確認してから実行。**エージェントはオートメーションの削除や統合の無効化など、破壊的な操作を実行する前に、計画している内容を説明します。常にアクションサマリーを確認してください。
• **トークンを安全に保管。**長期アクセストークンは完全なAPIアクセスを提供します。環境変数に保存し、プレーンテキストファイルには絶対に保存しないでください。Home Assistantプロフィールから定期的にトークンをローテーションしてください。
• **HTTPSを使用。**Home Assistantにリモートアクセスする場合、常に有効なSSL証明書付きのHTTPSを使用してください。暗号化なしでインスタンスをパブリックインターネットに公開しないでください。
• **ネットワークアクセスを制限。**Home Assistantのip_bansやファイアウォールルールを使用して、信頼できるIP範囲にAPIアクセスを制限してください。一般的なOpenClawセキュリティガイダンスについては安全チェックリストを参照してください。

よくあるエラーのトラブルシューティング

"401 Unauthorized — Invalid access token"

長期アクセストークンが無効または期限切れです。

1. トークンが正しく設定されているか確認：

echo $HOMEASSISTANT_TOKEN

2. Home Assistantプロフィールページから新しいトークンを生成してください。
3. トークン値に余分な空白や改行がないことを確認してください。

"Connection refused — Cannot reach Home Assistant"

エージェントがHome Assistantインスタンスに接続できません。

1. URLが正しくポートが含まれているか確認：

curl -s http://YOUR_HA_HOST:8123/api/

2. Home Assistantが実行中か確認：sudo systemctl status homeassistant（Supervisedインストールの場合）。
3. Dockerを使用している場合、コンテナが実行中か確認：docker ps | grep homeassistant。
4. ファイアウォールルールを確認——ポート8123がマシンからアクセス可能である必要があります。

"Entity not found — light.living_room"

エンティティIDがHome Assistant内のどのデバイスとも一致しません。

1. 利用可能なすべてのエンティティを一覧表示：

curl -s -H "Authorization: Bearer $HOMEASSISTANT_TOKEN" \
  http://YOUR_HA_HOST:8123/api/states | jq '.[].entity_id' | grep light

2. エンティティIDは大文字小文字を区別し、アンダースコアを使用します——タイプミスがないか確認してください。
3. デバイスが最近追加された場合、Home Assistantを再起動してエンティティ登録を更新してください。