이 가이드는 Xiaozhi AI의 자주 쓰는 음성 명령을 상황별로 “그대로 읽으면 되는” 목록으로 정리하고, 각 명령 뒤에 있는 기능도 설명합니다. 정해진 암호를 외울 필요는 없습니다 —— 말한 대로 그대로 동작합니다.
목 차
- 말 거는 방법
- 기기 제어
- 집 상태 확인
- 한마디로 루틴 통째로 실행
- 말로 만들기
- 수정·삭제·정리
- 캘린더·안내 방송·알림
- 시스템 업데이트와 문제 진단
- 이 명령의 뒷면
- 명령이 잘 통하는 작은 습관
01
말 거는 방법
- 호출: “Xiaozhi”라고 말하면 바로 대화가 시작됩니다. 휴대용 핸디 Xiaozhi와 핸디 단말은 버튼을 눌러 바로 깨울 수도 있습니다.
- 암호를 외울 필요 없음: 말한 표현을 기능과 즉석에서 매칭합니다. “외출”이라고 하면 외출 점검 루틴이 자동으로 선택되고, “자동화 진단”이라고 하면 문제 진단 기능을 찾아냅니다 —— “지원하지 않습니다”라고 퉁명스럽게 답하지 않습니다.
- 한 번에 여러 개: 한 문장에 여러 기기와 여러 동작을 담아도 순서대로 실행하고, 끝나면 음성으로 결과를 알려줍니다.
- 복잡한 조건도 이해: 대규모 모델을 연결하면 “거실에서 간접등을 제외한 모든 조명을 끄고 침대 옆 조명만 남겨줘” 같은 제외 조건이 있는 요청도 정확히 실행합니다.
- 다시 말하면 고쳐집니다: “○○를 △△로 바꿔줘”라고 하면 기존 대상을 먼저 찾아 수정합니다. 같은 것을 몰래 새로 만들지 않습니다.
i호출 방식은 기기마다 조금 다릅니다. AI 스피커와 본체는 음성으로 깨우고, 로봇 강아지 Xiaozhi와 핸디 Xiaozhi는 음성 대화를 지원하며, 핸디 단말은 다른 방의 스피커로 안내 방송을 보낼 수도 있습니다.
02
기기 제어
거실 조명 켜줘
해당 영역 조명이 즉시 켜집니다. 말을 마치면 바로 실행됩니다
거실 조명 꺼줘
지정한 조명이 꺼지고 실행 결과가 기록되어 나중에 확인할 수 있습니다
모든 조명 켜줘
방을 지정하지 않으면 현재 영역의 조명을 켜고, “집 안 모든 조명 켜줘”라고 하면 전체를 켤 수 있다고 안내합니다
집 안 모든 조명 켜줘
“조명”이 들어간 스위치를 포함해 집 안의 모든 조명이 켜집니다
안방 조명 켜줘
안방 조명만 켜지고 다른 방은 건드리지 않습니다
간접등 빨간색으로 해줘
간접등이나 라인 조명이 지정한 색으로 바뀝니다
바닥 난방 켜줘
해당 기기가 지원하는 모드(바닥 난방은 “난방”)를 자동으로 골라 한 번에 성공합니다
에어컨 26도로 맞춰줘
온도를 설정해 실행합니다. “이미 켜져 있습니다”라는 잘못된 응답은 더 이상 나오지 않습니다
커튼 열어줘 / 커튼 닫아줘
지시대로 커튼이 열리거나 닫힙니다
천장등, 현관등, 다운라이트, 라인 조명 켜고, 간접등 빨간색으로 하고, 커튼 닫고, 끝나면 음성으로 알려줘
여러 기기와 동작을 한 문장으로 실행하고 완료를 음성으로 보고합니다
거실에서 간접등을 제외한 모든 조명을 끄고 침대 옆 조명만 남겨줘
대규모 모델이 제외 조건을 이해해 거실의 천장등·다운라이트·스포트라이트를 끄고, 간접등과 침대 옆 조명은 남긴 뒤 “거실 조명 3개를 껐습니다”라고 보고합니다
03
집 상태 확인
다실에는 어떤 조명이 있어?
해당 방의 조명을 목록으로 반환합니다. “이 방에는 조명이 없습니다”라는 잘못된 판정은 이제 나오지 않습니다
안방에는 어떤 재실 센서가 있어?
방별로 센서를 조회합니다. 엔티티 우선·기기 보완 규칙으로 한 번에 모두 가져옵니다
방에 사람 있어?
센서로 재실을 판단해 “방에 사람이 있습니다” 또는 “없습니다”라고 답합니다
시스템 상태는 어때?
CPU 사용률·메모리·디스크 사용량·온도를 보고하고 결론을 덧붙입니다
오늘 일정 뭐 있어?
오늘 캘린더 일정을 정리해 하나씩 읽어줍니다
어떤 스크립트가 있어?
스크립트 목록을 반환합니다. 관리 화면을 뒤질 필요가 없습니다
로그 보여줘
시스템 로그를 조회합니다. 기간을 지정할 수도 있습니다
천장등은 오늘 언제 켜졌어?
기기 이력을 조회합니다. 시간은 사용자의 시간대에 맞춰 표시됩니다
거실 조명은 어젯밤 언제 꺼졌어?
날짜를 넘는 조회도 정확히 반환합니다
이 기기는 얼마나 켜져 있었어?
각 상태 구간의 지속 시간, 누적 켜짐/꺼짐 시간, 현재 상태 경과 시간을 반환합니다
오늘 최고 기온은?
오늘 기록된 날씨 값을 반환합니다. 일기예보를 찾아볼 필요가 없습니다
i조회는 모두 하나의 진입점으로 통일되어 있어 한마디면 결과를 얻습니다. 삭제도 진입점이 하나입니다(06절 참고).
04
한마디로 루틴 통째로 실행
아래 5가지 루틴은 한마디로 점검과 연동을 통째로 실행합니다. 하나씩 나눠 말할 필요가 없습니다.
외출 점검
아직 켜진 조명과 집에 사람이 있는지 확인하고, 켜진 조명은 꺼준 뒤 마지막에 “외출 점검 완료: 조명 3개를 껐습니다. 지금은 아무도 없습니다”라고 읽어줍니다
취침 점검
조명·커튼·도어락을 한 번에 확인하고, 필요하면 조명을 끄고 잘 자라고 인사합니다
아침 브리핑
오늘 날씨·일정·할 일을 한 번에 모아 음성으로 읽어줍니다
다녀왔어
거실 조명과 에어컨을 자동으로 켜고 환영 메시지를 재생합니다
시스템 점검
본체 CPU/메모리/디스크/온도, HA 상태, 사용 가능한 업데이트를 확인하고 결론을 읽어줍니다
i루틴은 상황에 맞게 움직입니다. 모든 조명이 이미 꺼져 있으면 외출 점검은 쓸데없는 조작을 하지 않고 확인과 보고만 합니다. 결과도 “아직 3개가 켜져 있습니다”처럼 구체적이며 “점검 완료”처럼 두루뭉술하게 말하지 않습니다. 루틴 전체에 45~60초 타임아웃이 있어, 일부 기기 응답이 느려도 어디까지 완료했는지 솔직하게 알려줍니다.
05
말로 만들기
장면·스크립트·자동화(블루프린트)·보조 요소는 모두 자연어 한 문장으로 만들 수 있습니다. 사용 가능한 모드를 골라주고 오프셋 같은 세부 설정도 채워서 실행합니다.
거실에 파티 장면 만들고 관련 기기 불러와줘
거실의 천장등·간접등·커튼을 찾아 장면을 구성하고 완료를 음성으로 알려줍니다
매일 저녁 8시에 실행되는, 집에 있는 상황을 흉내내는 스크립트 만들어줘
스크립트를 생성하고 실행 시간을 설정합니다. 구조는 간결해 편집하기 쉽습니다
천장등 켜는 동작을 1초 간격으로 5번 반복하는 스크립트 만들어줘
동작을 5번 복사하는 대신 실제 루프로 실행합니다
해가 뜨면 커튼 열고 해가 지면 닫는 자동화 만들어줘
일출·일몰 오프셋까지 고려한 재사용 가능한 블루프린트를 만듭니다. 커튼 엔티티를 골라 저장하기만 하면 됩니다
자동화 만들어줘: 실외 온도가 40도 이상이고 습도가 60% 이상일 때 해가 떠 있으면, 에어컨을 켜고 “지금 온도와 습도가 너무 높습니다. 열사병에 주의하세요”라고 음성으로 알려줘
이 문장을 트리거와 동작으로 나눠 자동화 관리 화면에 등록합니다
귀가 모드 스크립트 만들어줘. 천장등이 켜져 있으면 귀가 동작을 실행하고, 꺼지면 일시정지, 다시 켜지면 이어서 실행, 2분 동안 안 켜지면 종료
게이트형 스크립트 하나로 “기기가 켜지면 실행 / 꺼지면 일시정지 / 다시 켜지면 재개 / 시간 초과 시 종료”를 구현합니다
손님 버튼 보조 요소 만들고, 그걸로 손님 모드를 연동하는 자동화도 만들어줘
보조 요소를 먼저, 연동 자동화를 다음에. 한마디로 두 단계가 끝납니다
에어컨이 몇 대 켜져 있는지 실시간으로 세는 보조 요소 만들어줘
집계용 보조 요소를 생성하고 대시보드에 바로 표시할 수 있습니다
양방향 블루프린트 만들어줘 / 현관등과 천장등을 이 블루프린트에 연결해줘
양방향 동기화 블루프린트를 만들고 실제 조명을 연결해 2개소·다개소 제어를 구현합니다
귀가 모드를 귀가 버튼에, 외출 모드를 외출 버튼에 연결해줘
벽 스위치로 장면을 바로 실행할 수 있게 합니다. 10초 안에 완료됩니다
잘 자 장면 만들어줘
달 아이콘이 자동으로 붙습니다. “귀가 모드 만들어줘”는 집 아이콘, “매일 풍속 기록해줘”는 바람 아이콘입니다
i날씨 기록(당일 최고/최저 기온, 자외선, 풍속, 습도, 강수량 등)은 만든 뒤 매일 0시 5분에 그날 값이 자동으로 채워집니다. 게다가 만든 당일부터 조회할 수 있습니다. 하룻밤 기다릴 필요가 없습니다.
06
수정·삭제·정리
손님 장면에서도 라인 조명 켜줘
기존 장면을 먼저 찾아 수정합니다. 같은 이름의 장면을 새로 만들지 않습니다
날씨 업데이트 자동화 삭제해 / 손님 장면 삭제해 / 에어컨 대수 보조 요소 삭제해
“○○ 삭제”라는 하나의 진입점이 유형을 자동 판별해 한 번에 끝냅니다. 잘못된 대상을 지우는 일도 없습니다
현관 스위치를 입구 스위치로 이름 바꿔줘 / 대형등 이름을 천장등으로 바꿔줘
기기와 개별 엔티티 이름 변경 모두 즉시 반영됩니다
날씨 업데이트 자동화를 “날씨” 분류에 넣어줘
분류를 만들거나 재사용해 넣습니다. “분류에서 빼줘”라고 하면 해제됩니다
취침 알림과 조명 연동을 대기 모드로 바꿔줘
“동시에 실행”, “한 번에 하나만”도 지정할 수 있습니다. 동작이 서로 자리 다툼하는 것을 막습니다
모든 자동화에 어울리는 아이콘 붙여줘
이름의 키워드로 한꺼번에 매칭해 한 번에 갱신합니다
i“○○ 삭제”가 지원하는 범위: 보조 요소(버튼/스위치/숫자 등), 자동화, 장면, 스크립트, 할 일, 캘린더 일정, 분류, 태그, 그룹, 지오펜스, 구역, 층, 엔티티, 기기, 대시보드, 블루프린트.
07
캘린더·안내 방송·알림
캘린더에 일정 추가해줘. 7월 9일, 차 사기, 오전 11시
날짜·시간·내용을 추출해 디지털 캘린더에 동기화합니다
거실 스피커로 재생해줘: 밥 먹을 시간입니다, 식당으로 오세요
지정한 방의 스피커로 안내 방송을 보내고, 핸디 단말에도 “방송 완료”를 표시합니다
지금 온도와 습도가 너무 높습니다. 열사병에 주의하세요
자동화 안의 음성 메시지로 쓸 수 있습니다. 조건이 충족되면 자동으로 읽어줍니다
08
시스템 업데이트와 문제 진단
새 버전 있어? / 업데이트 확인해
현재 버전과 최신 버전을 읽어줍니다. 통합 페이지에서 직접 누를 필요가 없습니다
새 버전에서 뭐가 바뀌었어?
이번 업데이트 내용을 요약합니다. “자세히”라고 하면 상세히 말해줍니다
시스템 업그레이드해
먼저 “업그레이드 중에는 자동으로 재부팅되고 음성 비서가 1~2분 오프라인됩니다”라고 알리고, “업그레이드 확인”이라고 해야 시작합니다
거실 천장등이 왜 사용할 수 없음으로 표시돼? / ○○ 기기가 반응하지 않아 / 오프라인이야
기기 이상 진단: 엔티티 상태, 소속 통합, 이력과 로그를 차례로 확인한 뒤 원인과 해결책을 제시합니다
비 알림 자동화가 왜 작동하지 않아?
자동화 고장 진단: 비활성화되지 않았는지, 발동한 적이 있는지, 동작이 성공했는지, 참조 엔티티가 존재하는지 확인해 어느 단계에서 실패했는지 짚어줍니다
레인지 후드가 제어되지 않았어
기기가 피드백을 수집하고 오류 내용·발생 시각·조작 로그를 담은 버그 기록을 백엔드에 만듭니다
i두 진단 기능 모두 확인하면서 진행 상황을 알려줍니다(“먼저 설정을 봅니다…… 다음은 발동 기록을……”). 마지막에 결론을 정리합니다. 진단은 전부 읽기 전용이라 설정을 바꾸지 않습니다.
10
명령이 잘 통하는 작은 습관
- 방을 먼저, 기기를 나중에: “안방 조명”이 “그 조명”보다 훨씬 정확합니다.
- 집 전체면 “집 안”이라고 말하기: “모든 조명 켜줘”는 기본이 현재 영역입니다. “집 안 모든 조명 켜줘”라야 전체가 켜집니다.
- 복잡한 요청은 한 문장에: 조건·동작·읽어줄 내용을 한 문장에 담으면 알아서 나눕니다.
- 문제가 생기면 먼저 물어보기: “○○가 왜 안 돼”라고 하면 진단이 시작됩니다. 진단은 읽기 전용이라 설정이 바뀌지 않습니다.
- 이름 변경도 말로: 기기·엔티티 이름 변경은 즉시 반영됩니다. 이름을 바꾼 뒤에는 참조하는 자동화도 갱신해 두세요.
09
이 명령의 뒷면
1
음성 비서의 대규모 모델 연결(LTCN AI Conversation)
HA 기본 음성 비서는 예전에는 정해진 규칙으로만 말을 이해해서 조금만 복잡해도 못 알아들었습니다. 이제 대규모 모델에 연결할 수 있어 이해력이 크게 향상됩니다.
지원 모델
DeepSeek, OpenAI, Kimi, 즈푸, 퉁이치엔원, 실리콘플로, 로컬 Ollama 등 8곳
설치 방법
제공자 하나를 고르고 API 키만 붙여넣으면 됩니다. 모델 이름과 엔드포인트는 자동으로 설정됩니다
전환 방법
“관리”를 열고 음성 비서의 대화 에이전트를 LTCN AI로 바꿉니다. “로컬 처리 우선”을 켜면 토큰을 아낄 수 있습니다
2
기억·습관 에이전트
시스템은 자주 제어하는 기기와 평소 특정 시간에 하는 일을 자동으로 집계해, 이후 대화에서 그 습관을 참고합니다. 예를 들어 매일 밤 10시에 거실 조명을 끈다면 “조명 꺼줘”라고만 해도 거실 조명인 걸 알아듣습니다.
기억은 모두 본체 데이터베이스에 저장되며 외부로 전송되지 않습니다.
3
“루틴”과 “에이전트” 프레임워크
- 루틴: 여러 단계 작업을 한마디로 묶습니다. “외출 점검”은 조명을 보고 재실을 확인해 한 번에 결론을 냅니다.
- 상황에 맞게 동작: 조건이 성립하지 않으면 쓸데없는 동작을 하지 않습니다.
- 결과를 구체적으로: 안내 방송은 두루뭉술한 결론이 아니라 구체적인 숫자를 전합니다.
- 타임아웃 보호: 45~60초. 기기 하나가 느려도 루틴 전체가 멈추지 않습니다.
- 에이전트: 다단계 추론과 자동 진단 프레임워크가 준비되어 있고, 기기 이상 진단과 자동화 고장 진단이 첫 결과물입니다.
4
로컬 고빈도 제어 가속
조명·커튼·에어컨은 로컬 고빈도 제어 경로를 사용해 명령 분석부터 실행까지 0.006~0.009ms밖에 걸리지 않습니다. 1ms 목표를 크게 밑돕니다. 그래서 “거실 조명 켜줘” 같은 일상 조작은 말을 마치는 순간 실행됩니다.
5
진입점 통일과 응답 속도 향상
삭제는 “○○ 삭제”로, 조회는 하나의 진입점으로 통일했습니다. 동시에 사용 빈도가 낮은 많은 기능을 “상시 메뉴”에서 “필요 시 검색”으로 옮겨, 첫 인식 정확도가 올라가고 응답도 빨라지고 자원도 아낍니다.
6
외부 AI 도구 연결(MCP)
Cursor, Claude, Codex, Workbuddy 등 MCP를 지원하는 AI 클라이언트라면 무엇이든 연결해 자연어로 스마트홈을 제어할 수 있습니다.
- HA 통합 페이지에서 “API 키 보기”를 누르면 키가 알림에 표시되고 그대로 복사할 수 있습니다
- AI 도구에서 MCP 연결을 설정하고 키를 붙여넣습니다
- 그다음 “거실 조명 켜고 에어컨 26도로 맞춰줘”라고 말하면 됩니다
키 유출이 걱정되면 “API 키 재생성”을 누르면 됩니다. 이전 키는 즉시 무효가 됩니다. 외부 접속은 기존 HA 주소와 로그인 토큰을 재사용하며, 엔드포인트 경로는 /api/ltcn_mcp/mcp입니다. 공유기에 포트를 따로 열 필요가 없습니다.
7
자동화 설정의 문턱 낮추기
- 블루프린트: 파라미터 몇 개만 고르면 되는 자동화 템플릿. YAML을 직접 쓸 필요가 없습니다.
- 보조 요소: 버튼·스위치·숫자 테이블 등. 집계(에어컨 켜진 대수)에도 쓰고, 반대로 장면을 실행하는 데도 씁니다.
- 실행 모드: 동시 실행·대기열·한 번에 하나만. 동작끼리 간섭하는 것을 막습니다.
- 분류 정리: 자동화·장면·스크립트를 분류에 넣어 관리 화면을 정리할 수 있습니다.