티스토리 뷰
들어가며
여러분의 메시징 앱이 AI 에이전트와 직접 대화할 수 있다면 어떨까요? OpenClaw는 WhatsApp, Telegram, Discord, 그리고 iMessage를 Pi 에이전트와 연결하는 강력한 게이트웨이입니다. 이는 단순한 챗봇이 아닙니다. 여러분의 컴퓨터에서 명령을 실행하고, 파일을 읽고 쓰며, 능동적으로 메시지를 보낼 수 있는 "항상 켜져있는" 개인 비서를 구축할 수 있는 플랫폼입니다.
오늘은 OpenClaw의 "개인 비서" 설정 가이드를 깊이 있게 살펴보고, 개발자들이 어떻게 자신만의 AI 비서를 안전하게 구축할 수 있는지 알아보겠습니다.
핵심 기능과 아키텍처
멀티 채널 통합
OpenClaw의 가장 큰 강점은 다양한 메시징 플랫폼을 하나의 게이트웨이로 통합한다는 점입니다:
- 기본 지원: WhatsApp, Telegram, Discord, iMessage
- 플러그인 확장: Mattermost 등 추가 플랫폼
- 통합 세션 관리: 모든 채널에서 일관된 대화 맥락 유지
2대 전화기 구조 (권장)
OpenClaw는 "2대 전화기" 설정을 강력히 권장합니다. 개인 WhatsApp 번호를 연결하면 받는 모든 메시지가 "에이전트 입력"이 되어버리기 때문입니다. 대신:
- 개인 전화기: 일상적인 커뮤니케이션용
- 비서 전화기: OpenClaw 전용 (SIM/eSIM/선불폰 가능)
이렇게 분리하면 개인 대화와 AI 비서와의 상호작용을 명확히 구분할 수 있습니다.
5분 퀵스타트
설정이 놀라울 정도로 간단합니다:
# WhatsApp Web 페어링 (QR 코드 스캔)
openclaw channels login
# 게이트웨이 실행
openclaw gateway --port 18789
# 기본 설정 (~/.openclaw/openclaw.json)
{
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
허용된 전화번호에서 비서 번호로 메시지를 보내면 바로 작동합니다.
보안 우선 설계
OpenClaw 문서가 가장 먼저 강조하는 것은 안전입니다. AI 에이전트에게 다음과 같은 권한을 주게 됩니다:
- 시스템 명령 실행
- 워크스페이스 파일 읽기/쓰기
- 메시징 플랫폼을 통한 메시지 발송
따라서 다음 보안 원칙을 철저히 지켜야 합니다:
필수 보안 설정
{
channels: {
whatsapp: {
allowFrom: ["+15555550123"], // 반드시 지정!
groups: {
"*": { requireMention: true } // 그룹에서는 멘션 필수
}
}
}
}
allowFrom을 반드시 설정하여 특정 번호만 접근 가능하도록 제한- 하트비트 기능은 신뢰할 수 있을 때까지 비활성화 (
every: "0m") - 전용 전화번호 사용으로 개인 정보 격리
에이전트 워크스페이스: AI의 "기억"
OpenClaw는 ~/.openclaw/workspace를 에이전트의 작업 공간으로 사용합니다. 이곳에는 다음과 같은 파일들이 자동 생성됩니다:
- AGENTS.md: 운영 지침
- SOUL.md: 에이전트의 페르소나와 성격
- TOOLS.md: 사용 가능한 도구 목록
- IDENTITY.md: 에이전트의 정체성
- USER.md: 사용자 정보
- HEARTBEAT.md: 능동적 작업 지침
- MEMORY.md: (선택) 세션 간 기억
Git으로 백업하기
문서는 워크스페이스를 Git 저장소로 만들 것을 권장합니다:
openclaw setup
Git이 설치되어 있다면 새 워크스페이스는 자동으로 초기화됩니다. 이렇게 하면 에이전트의 "기억"과 설정을 안전하게 버전 관리하고 백업할 수 있습니다.
세션 관리와 메모리
OpenClaw는 정교한 세션 관리 시스템을 제공합니다:
{
session: {
scope: "per-sender",
resetTriggers: ["/new", "/reset"],
reset: {
mode: "daily",
atHour: 4,
idleMinutes: 10080
}
}
}
- 세션 범위: 발신자별로 독립적인 대화 맥락 유지
- 리셋 트리거:
/new또는/reset명령으로 새 세션 시작 - 자동 리셋: 매일 새벽 4시 또는 7일(10,080분) 유휴 후 자동 초기화
- 컨텍스트 압축:
/compact명령으로 세션 최적화
세션 파일은 ~/.openclaw/agents/<agentId>/sessions/ 디렉토리에 JSONL 형식으로 저장됩니다.
하트비트: 능동적 AI 비서
가장 흥미로운 기능 중 하나는 하트비트(Heartbeat) 시스템입니다. 기본적으로 30분마다 에이전트가 자동으로 실행되며:
HEARTBEAT.md파일을 읽고 지침을 따름- 주의가 필요한 작업이 있는지 확인
- 필요 없으면
HEARTBEAT_OK응답 (메시지 발송 안 함)
{
agent: {
heartbeat: { every: "30m" } // 또는 "0m"으로 비활성화
}
}
이는 진정한 "능동적" AI 비서를 만듭니다. 예를 들어, 매일 아침 날씨 확인, 주기적인 서버 상태 모니터링, 정해진 시간에 리마인더 등을 자동으로 수행할 수 있습니다.
멀티미디어 지원
OpenClaw는 텍스트뿐만 아니라 미디어도 처리합니다:
인바운드
- 이미지, 오디오, 문서 첨부 가능
{{MediaPath}},{{MediaUrl}},{{Transcript}}템플릿 사용- 오디오 자동 전사 지원
아웃바운드
여기 스크린샷이 있습니다.
MEDIA:https://example.com/screenshot.png
에이전트가 MEDIA:<경로-또는-URL> 형식으로 응답하면 자동으로 미디어 첨부됩니다.
고급 설정 예제
실제 프로덕션 환경을 위한 설정 예시:
{
logging: { level: "info" },
agent: {
model: "anthropic/claude-opus-4-6",
workspace: "~/.openclaw/workspace",
thinkingDefault: "high",
timeoutSeconds: 1800,
heartbeat: { every: "0m" } // 신뢰 후 활성화
},
channels: {
whatsapp: {
allowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true }
}
}
},
routing: {
groupChat: {
mentionPatterns: ["@openclaw", "openclaw"]
}
},
session: {
scope: "per-sender",
resetTriggers: ["/new", "/reset"],
reset: {
mode: "daily",
atHour: 4,
idleMinutes: 10080
}
}
}
운영 및 모니터링
OpenClaw는 포괄적인 상태 확인 명령어를 제공합니다:
openclaw status # 로컬 상태 (인증, 세션, 이벤트 큐)
openclaw status --all # 전체 진단 (읽기 전용, 공유 가능)
openclaw status --deep # 게이트웨이 헬스 프로브 포함
openclaw health --json # 게이트웨이 헬스 스냅샷 (WebSocket)
로그는 기본적으로 /tmp/openclaw/openclaw-YYYY-MM-DD.log에 저장됩니다.
확장 생태계
OpenClaw는 다양한 플랫폼으로 확장 가능합니다:
- 웹챗: 브라우저 기반 인터페이스
- macOS: 메뉴 바 컴패니언 앱
- iOS/Android: 모바일 노드 앱
- Windows: WSL2 지원
- Linux: 네이티브 앱
개발자를 위한 인사이트
OpenClaw는 단순한 챗봇 프레임워크를 넘어, 에이전트 중심 아키텍처의 훌륭한 사례를 보여줍니다. 주목할 만한 설계 철학:
1. 보안 우선 접근
문서가 맨 처음 "⚠️ Safety first"로 시작하는 것은 의미심장합니다. AI 에이전트에게 시스템 권한을 줄 때 발생할 수 있는 위험을 정면으로 다루고 있습니다. allowFrom 필수 설정, 하트비트 점진적 활성화 등은 실무에서 바로 적용할 수 있는 모범 사례입니다.
2. 파일 기반 설정의 우아함
SOUL.md, HEARTBEAT.md 등 마크다운 파일로 에이전트를 설정하는 방식은 다음과 같은 장점이 있습니다: - 가독성: 코드가 아닌 자연어로 작성 - 버전 관리: Git으로 변경 이력 추적 - 협업: 비개발자도 페르소나 조정 가능 - 투명성: AI가 무엇을 기반으로 동작하는지 명확
3. 세션 관리의 깊이
per-sender 스코프, 자동 리셋, 컨텍스트 압축 등은 장기 실행되는 AI 비서의 핵심 과제들을 잘 해결했습니다. 특히 토큰 비용을 고려한 세션 최적화는 실용적입니다.
4. 하트비트의 혁신
대부분의 챗봇은 "반응형"입니다. 하지만 OpenClaw의 하트비트는 "능동형" 에이전트를 가능하게 합니다. HEARTBEAT_OK로 불필요한 알림을 억제하는 세심함도 돋보입니다.
개발자가 얻을 수 있는 것
- 멀티 채널 통합 경험: 여러 메시징 플랫폼을 하나의 백엔드로 관리하는 패턴
- 에이전트 아키텍처 설계: 워크스페이스, 세션, 메모리 관리의 실전 노하우
- 보안 베스트 프랙티스: AI 에이전트 운영 시 고려해야 할 보안 요소들
- 확장 가능한 구조: 플러그인 시스템, 다중 플랫폼 지원 등
주의사항
OpenClaw는 강력한 만큼 책임감 있게 사용해야 합니다: - 처음엔 항상 보수적으로 시작 (제한된 권한, 비활성화된 하트비트) - 워크스페이스는 반드시 비공개 Git 저장소로 관리 - 프로덕션 환경에서는 별도의 에이전트 인스턴스 사용 권장 - 토큰 비용을 고려한 하트비트 주기 설정
맺음말
OpenClaw는 AI 에이전트를 일상의 커뮤니케이션 도구에 통합하는 실용적이고 안전한 방법을 제시합니다. 보안을 최우선으로 하면서도 강력한 기능을 제공하는 균형 잡힌 설계가 인상적입니다.
특히 Git 기반 워크스페이스 관리, 세션 최적화, 능동적 하트비트 시스템은 다른 AI 에이전트 프로젝트에서도 참고할 만한 패턴입니다. 개인 비서부터 팀 협업 봇까지, OpenClaw는 다양한 사용 사례를 지원할 수 있는 견고한 기반을 제공합니다.
여러분만의 AI 비서를 구축할 준비가 되셨나요? OpenClaw로 시작해보세요. 단, 항상 보안을 최우선으로 하는 것을 잊지 마세요!