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 스킬을 설치합니다:

npx clawhub@latest install home-assistant

설치를 확인하려면:

clawhub list

설치된 스킬 목록에 home-assistant가 표시되어야 합니다. 가장 빠른 설치 경험을 위해 clawhub CLI로 설치하세요.

Home Assistant 스킬 구성

이 스킬은 API 요청을 인증하기 위해 Home Assistant URL과 장기 액세스 토큰이 필요합니다.

장기 액세스 토큰 생성

1. http://YOUR_HA_HOST:8123에서 Home Assistant 대시보드를 엽니다.
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을 제공합니다 | | 리버스 프록시 | SSL 종료가 포함된 Nginx 또는 Caddy | | 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. 자동화 생성

사용자: "매일 밤 일몰에 현관 조명을 켜고 밤 11시에 끄는 자동화를 만들어 주세요."

에이전트가 일몰에 대한 sun 트리거와 23:00에 대한 time 트리거를 사용하여 Home Assistant 자동화를 구성합니다. API를 통해 자동화를 등록하고 설명적인 이름을 할당하며 활성화되었음을 확인합니다.

4. 씬 활성화

사용자: "영화 감상 씬을 활성화해 주세요."

에이전트가 scene.movie_night에 대해 scene.turn_on을 호출하여 조명을 어둡게 하고 블라인드를 닫으며 미디어 플레이어를 올바른 입력으로 설정합니다 — 모두 기존 씬 정의에 구성된 대로입니다.

5. 기기 상태 문제 해결

사용자: "현재 사용할 수 없거나 오프라인인 기기는 무엇인가요?"

에이전트가 unavailable 또는 unknown 상태인 모든 엔티티를 조회하고 통합별로 그룹화하여 진단 보고서를 반환합니다: "3개 기기 오프라인 — Zigbee 모션 센서 (마지막 확인 2시간 전), 스마트 플러그 주방 (연결 불가), 날씨 통합 (API 시간 초과)."

보안 및 모범 사례

스마트 홈을 안전하게 유지하기 위해 다음 지침을 따르세요:

• 최소 권한 원칙을 사용하세요. 에이전트가 제어할 방과 기기로 권한을 제한한 전용 Home Assistant 사용자를 생성하세요. 관리자 계정 토큰 사용을 피하세요.
• 확인 후 실행하세요. 에이전트는 자동화 삭제나 통합 비활성화와 같은 파괴적 작업을 실행하기 전에 수행할 내용을 설명합니다. 항상 작업 요약을 검토하세요.
• 토큰을 안전하게 보관하세요. 장기 액세스 토큰은 전체 API 접근 권한을 제공합니다. 환경 변수에 저장하고 일반 텍스트 파일에는 절대 저장하지 마세요. Home Assistant 프로필에서 주기적으로 토큰을 갱신하세요.
• HTTPS를 사용하세요. Home Assistant에 원격으로 접근하는 경우 항상 유효한 SSL 인증서와 함께 HTTPS를 사용하세요. 암호화 없이 인스턴스를 공용 인터넷에 노출하지 마세요.
• 네트워크 접근을 제한하세요. Home Assistant의 ip_bans 또는 방화벽 규칙을 사용하여 신뢰할 수 있는 IP 범위로 API 접근을 제한하세요. 일반적인 OpenClaw 보안 지침은 안전 체크리스트를 검토하세요.

일반적인 오류 해결

"401 Unauthorized — 유효하지 않은 액세스 토큰"

장기 액세스 토큰이 유효하지 않거나 만료되었습니다.

1. 토큰이 올바르게 설정되었는지 확인하세요:

echo $HOMEASSISTANT_TOKEN

2. Home Assistant 프로필 페이지에서 새 토큰을 생성하세요.
3. 토큰 값에 추가 공백이나 줄 바꿈이 없는지 확인하세요.

"Connection refused — 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를 재시작하여 엔티티 등록을 새로고침하세요.