OpenClaw로 개인 비서 만들기

OpenClaw는 Pi 에이전트를 위한 WhatsApp + Telegram + Discord + iMessage 게이트웨이입니다. 플러그인으로 Mattermost를 추가할 수 있습니다. 이 가이드는 "개인 비서" 설정으로, 항상 켜져 있는 에이전트처럼 동작하는 전용 WhatsApp 번호를 사용합니다.

⚠️ 안전이 최우선입니다

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

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

보수적으로 시작하세요:

  • 항상 channels.whatsapp.allowFrom을 설정하세요 (개인 Mac에서 전 세계에 공개된 상태로 실행하지 마세요).
  • 비서용 전용 WhatsApp 번호를 사용하세요.
  • Heartbeat은 이제 기본적으로 30분마다 실행됩니다. 설정을 신뢰할 때까지 agents.defaults.heartbeat.every: "0m"으로 설정하여 비활성화하세요.

사전 요구사항

  • Node 22+
  • PATH에서 사용 가능한 OpenClaw (권장: 전역 설치)
  • 비서용 두 번째 전화번호 (SIM/eSIM/선불)
npm install -g openclaw@latest
# 또는: pnpm add -g openclaw@latest

소스에서 설치 (개발):

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 첫 실행 시 UI deps 자동 설치
pnpm build
pnpm link --global

두 개의 전화기 설정 (권장)

다음과 같은 구조를 원합니다:

귀하의 전화기 (개인)          두 번째 전화기 (비서)
┌─────────────────┐           ┌─────────────────┐
│  귀하의 WhatsApp │  ──────▶  │  비서 WA        │
│  +1-555-YOU     │  메시지   │  +1-555-ASSIST  │
└─────────────────┘           └────────┬────────┘
                                       │ QR로 연결
                                       ▼
                              ┌─────────────────┐
                              │  귀하의 Mac     │
                              │  (openclaw)      │
                              │    Pi 에이전트  │
                              └─────────────────┘

개인 WhatsApp을 OpenClaw에 연결하면 귀하에게 오는 모든 메시지가 "에이전트 입력"이 됩니다. 이것은 원하는 것이 아닐 가능성이 높습니다.

5분 빠른 시작

  1. WhatsApp Web 페어링 (QR 표시; 비서 전화기로 스캔):
openclaw channels login
  1. Gateway 시작 (실행 상태 유지):
openclaw gateway --port 18789
  1. ~/.openclaw/openclaw.json에 최소 설정 넣기:
{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

이제 허용 목록에 등록된 전화기에서 비서 번호로 메시지를 보내세요.

온보딩이 완료되면 게이트웨이 토큰과 함께 대시보드가 자동으로 열리고 토큰화된 링크가 출력됩니다. 나중에 다시 열려면: openclaw dashboard.

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

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

기본적으로 OpenClaw는 ~/.openclaw/workspace를 에이전트 워크스페이스로 사용하며, 설정/첫 번째 에이전트 실행 시 자동으로 생성합니다 (시작용 AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md 포함). BOOTSTRAP.md는 워크스페이스가 완전히 새 것일 때만 생성됩니다 (삭제 후 다시 나타나지 않아야 합니다).

팁: 이 폴더를 OpenClaw의 "메모리"처럼 취급하고 git 저장소로 만드세요 (가급적 비공개). 그러면 AGENTS.md + 메모리 파일이 백업됩니다. git이 설치되어 있으면 새 워크스페이스가 자동으로 초기화됩니다.

openclaw setup

전체 워크스페이스 레이아웃 + 백업 가이드: Agent workspace 메모리 워크플로우: Memory

선택사항: agents.defaults.workspace로 다른 워크스페이스 선택 (~ 지원).

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

저장소에서 자체 워크스페이스 파일을 이미 제공하는 경우 부트스트랩 파일 생성을 완전히 비활성화할 수 있습니다:

{
  agent: {
    skipBootstrap: true
  }
}

"비서"로 바꾸는 설정

OpenClaw는 기본적으로 좋은 비서 설정을 제공하지만 일반적으로 조정하고 싶을 것입니다:

  • SOUL.md의 페르소나/지침
  • thinking 기본값 (원하는 경우)
  • heartbeat (신뢰할 때)

예시:

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-5",
    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]는 세션 컨텍스트를 압축하고 남은 컨텍스트 예산을 보고합니다.

Heartbeat (능동 모드)

기본적으로 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에 대한 아웃바운드 전달을 억제합니다.
  • Heartbeat은 전체 에이전트 턴을 실행합니다 — 짧은 간격은 더 많은 토큰을 소비합니다.
{
  agent: {
    heartbeat: { every: "30m" }
  }
}

미디어 입출력

인바운드 첨부 파일 (이미지/오디오/문서)은 템플릿을 통해 명령에 표시될 수 있습니다:

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

에이전트의 아웃바운드 첨부 파일: 자체 줄에 MEDIA:<path-or-url>을 포함합니다 (공백 없음). 예시:

여기 스크린샷입니다.
MEDIA:/tmp/screenshot.png

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

운영 체크리스트

openclaw status          # 로컬 상태 (자격 증명, 세션, 대기 중인 이벤트)
openclaw status --all    # 전체 진단 (읽기 전용, 붙여넣기 가능)
openclaw status --deep   # 게이트웨이 상태 프로브 추가 (Telegram + Discord)
openclaw health --json   # 게이트웨이 상태 스냅샷 (WS)

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

다음 단계

← 문서로 돌아가기