OpenClaw 개인 비서 구축: 5분 만에 왓츠앱 에이전트 연결

매번 AI와 대화하기 위해 브라우저 탭을 열거나 전용 앱을 켜는 게 번거로우셨나요? 개발자라면 누구나 반복적인 작업이나 정보 요약을 더 편하게 처리하고 싶어 하죠. 내가 가장 자주 쓰는 메시지 앱에서 바로 나만의 AI 비서와 대화할 수 있다면 업무 효율이 완전히 달라질 거예요.

OpenClaw는 WhatsApp, Telegram, Discord, iMessage 등을 AI 에이전트에 연결해 주는 셀프 호스팅 Gateway입니다. 이 가이드에서는 언제나 대기 중인 나만의 AI 어시스턴트처럼 작동하는 전용 WhatsApp 번호를 설정하는 방법을 알아볼게요.

⚠️ 안전이 최우선이에요

에이전트에게 다음과 같은 권한을 부여하게 된다는 점을 꼭 기억하세요.

• 내 머신에서 명령 실행 (도구 정책에 따라 다름)
• 워크스페이스 내 파일 읽기 및 쓰기
• WhatsApp/Telegram/Discord/Mattermost(플러그인)를 통해 메시지 외부 전송

처음에는 보수적으로 시작하는 게 좋아요.

• 항상 channels.whatsapp.allowFrom을 설정하세요 (개인용 Mac에서 전 세계에 공개된 상태로 실행하지 마세요).
• 어시스턴트 전용 WhatsApp 번호를 사용하세요.
• Heartbeats 기본 주기는 30분입니다. 설정을 완전히 신뢰하기 전까지는 agents.defaults.heartbeat.every: "0m"으로 설정해 비활성화해 두세요.

사전 준비 사항

• OpenClaw 설치 및 온보딩 완료 — 아직 하지 않았다면 Getting Started를 참고하세요.
• 어시스턴트용 보조 전화번호 (SIM/eSIM/선불폰)

두 개의 폰을 사용하는 설정 (권장)

다음과 같은 구조를 만드는 것이 좋습니다.

flowchart TB
    A["<b>Your Phone (personal)<br></b><br>Your WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Second Phone (assistant)<br></b><br>Assistant WA<br>+1-555-ASSIST"]
    B -- linked via QR --> C["<b>Your Mac (openclaw)<br></b><br>AI agent"]

개인용 WhatsApp을 OpenClaw에 직접 연결하면, 나에게 오는 모든 메시지가 “에이전트 입력값”이 되어버려요. 이건 우리가 원하는 상황이 아니죠.

5분 퀵스타트

1. WhatsApp Web 페어링 (QR 코드가 표시되면 어시스턴트용 폰으로 스캔하세요):

openclaw channels login

2. Gateway 시작 (계속 실행 상태로 두세요):

openclaw gateway --port 18789

3. ~/.openclaw/openclaw.json에 최소 설정을 추가하세요:

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

이제 허용 목록(allowlist)에 추가한 폰으로 어시스턴트 번호에 메시지를 보내보세요.

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

에이전트에게 워크스페이스 제공하기 (AGENTS)

OpenClaw는 워크스페이스 디렉토리에서 작동 지침과 “메모리”를 읽어옵니다.

기본적으로 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

전체 워크스페이스 구조 및 백업 가이드: Agent workspace 메모리 워크플로우: Memory

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

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

이미 저장소에서 관리 중인 워크스페이스 파일이 있다면 bootstrap 파일 생성을 완전히 끌 수 있습니다.

{
  agent: {
    skipBootstrap: true,
  },
}

”어시스턴트”로 만들어주는 설정

OpenClaw는 기본적으로 훌륭한 어시스턴트 설정을 제공하지만, 보통은 다음 항목들을 튜닝하고 싶을 거예요.

• SOUL.md의 페르소나/지침
• 생각하기(thinking) 기본값 (필요한 경우)
• Heartbeats (설정을 신뢰하게 된 이후)

예시:

{
  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]는 세션 컨텍스트를 압축하고 남은 컨텍스트 용량을 보고합니다.

Heartbeats (능동적 모드)

기본적으로 OpenClaw는 30분마다 다음 프롬프트와 함께 heartbeat를 실행합니다. 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 같은 마크다운 헤더만 있는 경우), OpenClaw는 API 호출을 아끼기 위해 heartbeat 실행을 건너뜁니다.
• 파일이 없으면 heartbeat가 실행되며 모델이 수행할 작업을 결정합니다.
• 에이전트가 HEARTBEAT_OK라고 응답하면(짧은 패딩 포함 가능, agents.defaults.heartbeat.ackMaxChars 참고), OpenClaw는 해당 heartbeat에 대한 외부 메시지 전송을 억제합니다.
• 기본적으로 user:<id> 형태의 DM 대상에 대한 heartbeat 전송은 허용됩니다. heartbeat 실행은 유지하면서 직접 전송만 막으려면 agents.defaults.heartbeat.directPolicy: "block"으로 설정하세요.
• Heartbeats는 에이전트의 전체 턴을 실행하므로, 주기가 짧을수록 더 많은 토큰을 소모합니다.

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

미디어 송수신

수신된 첨부 파일(이미지/오디오/문서)은 템플릿을 통해 명령어로 전달될 수 있습니다.

• {{MediaPath}} (로컬 임시 파일 경로)
• {{MediaUrl}} (가상 URL)
• {{Transcript}} (오디오 전사 기능이 활성화된 경우)

에이전트가 외부로 미디어를 보낼 때는 별도의 줄에 MEDIA:<path-or-url>을 포함하세요 (공백 없이). 예시:

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

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

로컬 경로 동작은 에이전트의 파일 읽기 신뢰 모델을 따릅니다.

• tools.fs.workspaceOnly가 true인 경우, 외부로 나가는 MEDIA: 로컬 경로는 OpenClaw 임시 루트, 미디어 캐시, 에이전트 워크스페이스 경로 및 샌드박스 생성 파일로 제한됩니다.
• tools.fs.workspaceOnly가 false인 경우, 에이전트가 이미 읽기 권한을 가진 호스트 로컬 파일을 MEDIA:로 사용할 수 있습니다.
• 호스트 로컬 전송은 미디어 및 안전한 문서 유형(이미지, 오디오, 비디오, PDF, Office 문서)만 허용됩니다. 일반 텍스트나 비밀번호 같은 파일은 전송 가능한 미디어로 취급되지 않습니다.

즉, fs 정책이 읽기를 허용한다면 워크스페이스 외부에서 생성된 이미지나 파일도 전송할 수 있으며, 임의의 호스트 텍스트 파일이 유출될 위험은 방지합니다.

운영 체크리스트

openclaw status          # local status (creds, sessions, queued events)
openclaw status --all    # full diagnosis (read-only, pasteable)
openclaw status --deep   # adds gateway health probes (Telegram + Discord)
openclaw health --json   # gateway health snapshot (WS)

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

다음 단계

• WebChat: WebChat
• Gateway 운영: Gateway runbook
• Cron + 웨이크업: Cron jobs
• macOS 메뉴바 컴패니언: OpenClaw macOS app
• iOS node 앱: iOS app
• Android node 앱: Android app
• Windows 상태: Windows (WSL2)
• Linux 상태: Linux app
• 보안: Security

AI Setup Assistant