OpenClaw로 개인 어시스턴트 구축하기

OpenClaw는 Pi 에이전트를 위한 WhatsApp + Telegram + Discord + iMessage 게이트웨이입니다. 플러그인으로 Mattermost도 지원합니다. 이 가이드는 “개인 어시스턴트” 구성을 다룹니다. 전용 WhatsApp 번호 하나를 상시 가동되는 에이전트처럼 사용하는 방식입니다.

보안 먼저

에이전트에게 다음 권한을 부여하게 됩니다:

머신에서 명령 실행 (Pi 도구 설정에 따라 다름)
워크스페이스 파일 읽기/쓰기
WhatsApp/Telegram/Discord/Mattermost(플러그인)를 통한 메시지 발신

보수적으로 시작하세요:

반드시 channels.whatsapp.allowFrom을 설정하세요 (개인 Mac에서 전체 공개로 실행하지 마세요).
어시스턴트 전용 WhatsApp 번호를 사용하세요.
하트비트는 기본 30분 간격으로 실행됩니다. 설정을 신뢰할 수 있을 때까지 agents.defaults.heartbeat.every: "0m"으로 비활성화하세요.

사전 요구사항

OpenClaw 설치 및 온보딩 완료 — 아직 안 했다면 시작하기를 참고하세요
어시스턴트용 두 번째 전화번호 (SIM/eSIM/선불)

투폰 구성 (권장)

다음과 같은 구조를 만드는 것이 목표입니다:

flowchart TB
    A["<b>내 폰 (개인용)<br></b><br>내 WhatsApp<br>+1-555-YOU"] -- message --> B["<b>두 번째 폰 (어시스턴트)<br></b><br>어시스턴트 WA<br>+1-555-ASSIST"]
    B -- linked via QR --> C["<b>내 Mac (openclaw)<br></b><br>Pi 에이전트"]

개인 WhatsApp을 OpenClaw에 연결하면 수신되는 모든 메시지가 “에이전트 입력”이 됩니다. 대부분의 경우 원하는 동작이 아닐 겁니다.

5분 빠른 시작

WhatsApp Web 페어링 (QR 표시 후 어시스턴트 폰으로 스캔):

openclaw channels login

Gateway 시작 (계속 실행 상태 유지):

openclaw gateway --port 18789

~/.openclaw/openclaw.json에 최소 설정 작성:

{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

이제 허용 목록에 등록한 폰에서 어시스턴트 번호로 메시지를 보내면 됩니다.

온보딩이 완료되면 대시보드가 자동으로 열리고 토큰이 포함되지 않은 깔끔한 링크가 출력됩니다. 인증을 요청하면 gateway.auth.token의 토큰을 Control UI 설정에 붙여넣으세요. 나중에 다시 열려면: openclaw dashboard.

에이전트 워크스페이스 설정 (AGENTS)

OpenClaw는 워크스페이스 디렉토리에서 운영 지침과 “메모리”를 읽습니다.

기본적으로 ~/.openclaw/workspace를 에이전트 워크스페이스로 사용하며, 설정/첫 실행 시 자동으로 생성됩니다(AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md 포함). BOOTSTRAP.md는 워크스페이스가 새로 만들어질 때만 생성됩니다(삭제 후 다시 나타나지 않아야 합니다). MEMORY.md는 선택 사항이며(자동 생성되지 않음), 존재할 경우 일반 세션에서 로드됩니다. 서브에이전트 세션에는 AGENTS.md와 TOOLS.md만 주입됩니다.

팁: 이 폴더를 OpenClaw의 “메모리”라고 생각하고 git 저장소(되도록 비공개)로 관리하면 AGENTS.md와 메모리 파일을 백업할 수 있습니다. git이 설치되어 있으면 새 워크스페이스가 자동으로 초기화됩니다.

openclaw setup

전체 워크스페이스 구조 + 백업 가이드: 에이전트 워크스페이스 메모리 워크플로우: 메모리

선택 사항: agents.defaults.workspace로 다른 워크스페이스 경로를 지정할 수 있습니다(~ 지원).

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

이미 자체 저장소에서 워크스페이스 파일을 관리하고 있다면 부트스트랩 파일 생성을 완전히 비활성화할 수 있습니다:

{
  agent: {
    skipBootstrap: true,
  },
}

“어시스턴트”로 만드는 설정

OpenClaw는 기본적으로 좋은 어시스턴트 구성을 제공하지만, 보통 다음 항목을 조정하게 됩니다:

SOUL.md의 페르소나/지침
사고(thinking) 기본값 (필요 시)
하트비트 (신뢰할 수 있게 된 후)

예시:

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-6",
    workspace: "~/.openclaw/workspace",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // 처음에는 0으로 시작하고 나중에 활성화하세요.
    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/agents/<agentId>/sessions/{{SessionId}}.jsonl
세션 메타데이터 (토큰 사용량, 마지막 라우트 등): ~/.openclaw/agents/<agentId>/sessions/sessions.json (레거시: ~/.openclaw/sessions/sessions.json)
/new 또는 /reset으로 해당 대화의 새 세션을 시작합니다(resetTriggers로 설정 가능). 단독으로 보내면 에이전트가 리셋 확인 인사를 답합니다.
/compact [instructions]로 세션 컨텍스트를 압축하고 남은 컨텍스트 예산을 보고합니다.

하트비트 (능동 모드)

기본적으로 OpenClaw는 30분마다 다음 프롬프트로 하트비트를 실행합니다: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. agents.defaults.heartbeat.every: "0m"으로 비활성화할 수 있습니다.

HEARTBEAT.md가 있지만 실질적으로 비어 있으면(빈 줄과 # Heading 같은 마크다운 헤더만 있는 경우) API 호출을 아끼기 위해 하트비트 실행을 건너뜁니다.
파일이 없으면 하트비트는 그대로 실행되고 모델이 할 일을 판단합니다.
에이전트가 HEARTBEAT_OK로 응답하면(선택적으로 짧은 패딩 포함, agents.defaults.heartbeat.ackMaxChars 참고) 해당 하트비트의 발신 전달을 억제합니다.
기본적으로 DM 형식의 user:<id> 대상에는 하트비트 전달이 허용됩니다. agents.defaults.heartbeat.directPolicy: "block"으로 직접 대상 전달을 차단하면서도 하트비트 실행 자체는 유지할 수 있습니다.
하트비트는 전체 에이전트 턴을 실행합니다. 간격이 짧을수록 토큰 소비가 늘어납니다.

{
  agent: {
    heartbeat: { every: "30m" },
  },
}

미디어 입출력

인바운드 첨부파일(이미지/오디오/문서)은 템플릿을 통해 커맨드에 전달할 수 있습니다:

{{MediaPath}} (로컬 임시 파일 경로)
{{MediaUrl}} (의사 URL)
{{Transcript}} (오디오 트랜스크립션이 활성화된 경우)

에이전트의 아웃바운드 첨부파일: 별도의 줄에 MEDIA:<경로 또는 URL>을 작성합니다(공백 없이). 예시:

Here's the screenshot.
MEDIA:https://example.com/screenshot.png

OpenClaw가 이를 추출하여 텍스트와 함께 미디어로 전송합니다.

운영 체크리스트

openclaw status          # 로컬 상태 (인증 정보, 세션, 큐에 대기 중인 이벤트)
openclaw status --all    # 전체 진단 (읽기 전용, 복사 가능)
openclaw status --deep   # Gateway 헬스 프로브 추가 (Telegram + Discord)
openclaw health --json   # Gateway 헬스 스냅샷 (WS)

로그는 /tmp/openclaw/ 아래에 저장됩니다(기본: openclaw-YYYY-MM-DD.log).

다음 단계

WebChat: WebChat
Gateway 운영: Gateway 운영 가이드
크론 + 웨이크업: 크론 잡
macOS 메뉴 바 컴패니언: OpenClaw macOS 앱
iOS 노드 앱: iOS 앱
Android 노드 앱: Android 앱
Windows 상태: Windows (WSL2)
Linux 상태: Linux 앱
보안: 보안