OpenClaw 공식 문서 리서치 + 튜토리얼 1편

개요

이 문서는 OpenClaw 공식 문서를 바탕으로 제품 구조와 핵심 기능을 정리한 뒤, 처음 접하는 사람도 전체 그림을 잡을 수 있게 튜토리얼 형태로 다시 풀어쓴 자료입니다.

---

1. OpenClaw를 한 문장으로 정의하면

OpenClaw는 self-hosted AI agent gateway입니다.

이 말을 조금 풀어보면, 모델 하나를 띄워서 대화만 처리하는 도구라기보다

• 메신저 채널
• 에이전트 세션
• 디바이스 노드
• 주기 작업
• 운영 UI와 CLI

를 하나의 Gateway 프로세스 아래에서 통합 운영하게 해주는 런타임에 가깝습니다.

공식 문서에서도 비슷한 표현이 반복해서 나옵니다.

• self-hosted gateway
• multi-channel gateway for AI agents
• sessions, routing, channel connections의 single source of truth

문서를 쭉 읽고 나면 OpenClaw를 “메신저에 붙는 챗봇”보다 “AI 비서 운영 허브”로 보는 편이 더 정확하다는 느낌이 듭니다.

---

2. 공식 문서를 읽으며 보이는 핵심 축

1) Gateway 중심 아키텍처

OpenClaw의 중심은 분명히 Gateway입니다.

Gateway는

• 채널 연결을 유지하고
• 세션을 라우팅하고
• 이벤트를 처리하고
• WebSocket API를 제공하고
• heartbeat, cron, health 같은 운영 기능을 맡습니다.

그래서 OpenClaw는 채널 어댑터 여러 개를 옆으로 붙인 구조라기보다, 모든 표면을 하나로 묶는 제어면에 더 가깝게 보입니다.

2) 멀티 채널 허브

공식 문서 기준 주요 채널은

• WhatsApp
• Telegram
• Discord
• Slack
• Signal
• Google Chat
• WebChat
• BlueBubbles 기반 iMessage 경로
• 그리고 각종 plugin 채널

정도입니다.

중요한 건 채널 수보다, 한 Gateway가 여러 채널을 동시에 운영한다는 설계예요. OpenClaw는 애초에 “한 군데에만 붙는 봇”이 아니라 여러 대화 표면을 한 번에 다루는 걸 전제로 만들어졌습니다.

3) Agent-native 설계

문서 전반에서 반복해서 등장하는 개념도 꽤 선명합니다.

• sessions
• workspace
• memory
• multi-agent routing
• tool use
• cron / heartbeat

이 조합을 보면 OpenClaw는 대화 몇 번 주고받고 끝나는 챗 인터페이스보다, 계속 돌아가며 상태를 쌓고 일을 맡는 assistant runtime에 가깝습니다.

4) Nodes

OpenClaw를 다른 툴과 구분해주는 가장 흥미로운 축 중 하나는 nodes입니다.

공식 문서 기준 node는 iOS, Android, macOS, headless 디바이스가 Gateway WebSocket에 붙어서 capability를 제공하는 구조입니다.

노드가 제공하는 대표 기능을 보면

• `canvas.*`
• `camera.*`
• `screen.record`
• `location.get`
• `notifications.*`
• `system.*`
• Android의 `sms.send`

정도가 눈에 들어옵니다.

이 지점에서 OpenClaw는 메시지 게이트웨이를 넘어서, 디바이스 기능을 에이전트 쪽으로 끌어오는 capability bus처럼 읽힙니다.

5) 운영과 보안 모델

공식 문서는 기능 소개 못지않게 운영 안전성도 꽤 강하게 강조합니다.

대표적인 장치를 보면

• pairing
• allowlist
• dmPolicy / groupPolicy
• mention gating
• strict config validation
• sandboxing

같은 것들이 앞쪽에 자리합니다.

이걸 보면 OpenClaw는 “아무나 말 걸면 반응하는 공개형 봇”보다는, 접근 경계를 뚜렷하게 관리하는 개인 assistant 쪽 철학이 더 강합니다.

6) CLI + Web UI + Plugins

OpenClaw는 단순 데몬이 아니라 운영 도구까지 포함한 제품처럼 구성되어 있습니다.

대표적으로

• `openclaw` CLI
• Control UI
• cron / health / doctor / logs / status
• plugin 생태계

가 같이 묶여 있습니다.

문서를 읽다 보면 “만드는 법”뿐 아니라 “계속 굴리는 법”이 꽤 많이 보인다는 점도 인상적입니다.

---

3. 문서에서 읽히는 제품 철학

문서 톤을 종합해보면 OpenClaw는 몇 가지 방향을 아주 분명하게 밀고 있습니다.

self-hosted 우선

내 하드웨어에서, 내 채널 위에, 내 규칙으로 굴린다는 감각이 강합니다.

messaging-native

기존 메신저가 곧 인터페이스입니다. 사용자는 새 앱보다 이미 쓰는 채널에서 OpenClaw를 만나게 됩니다.

agent-native

세션, 메모리, 라우팅, 자동화가 중심에 있습니다. 단순 질의응답보다 지속성 있는 assistant를 염두에 둔 구조예요.

device-native

모바일과 맥 노드를 단순 보조 앱이 아니라 capability provider로 보는 시선도 선명합니다.

ops-conscious

health, doctor, logs, strict config 같은 운영 도구가 풍부하다는 점도 눈에 띕니다.

결국 OpenClaw는 데모용 프로젝트보다, 실제로 계속 켜두고 운영할 시스템 쪽에 훨씬 가깝습니다.

---

4. 공식 문서 기준 중요한 관찰

1) Gateway가 single source of truth다

채널, 세션, 라우팅의 중심은 결국 Gateway 하나입니다. 이 점이 구조를 단순하게 만들면서도 OpenClaw의 정체성을 분명하게 잡아줍니다.

2) Pi 중심 경로로 정리됐다

공식 features 문서에 따르면 legacy Claude, Codex, Gemini, Opencode 경로는 제거됐고, Pi가 유일한 coding agent path로 정리되어 있습니다.

이건 제품 전략 측면에서 꽤 큰 신호입니다. OpenClaw가 범용 에이전트 래퍼보다, 더 일관된 agent runtime 쪽으로 정리되고 있다고 볼 수 있기 때문입니다.

3) Workspace-as-memory 철학이 강하다

workspace 구조 안에

• `AGENTS.md`
• `SOUL.md`
• `TOOLS.md`
• `IDENTITY.md`
• `USER.md`
• `HEARTBEAT.md`
• optional `MEMORY.md`

같은 파일이 들어간다는 점은 상징적입니다.

OpenClaw는 기억을 세션 창 안에만 두지 않고, 파일 기반의 장기 문맥으로 다루는 편입니다.

4) Heartbeat와 Cron이 기본 구조 안에 들어 있다

OpenClaw는 사용자가 말을 걸었을 때만 움직이는 assistant를 넘어서, proactive assistant 운영을 전제로 설계된 느낌이 강합니다.

heartbeat는 주기적 check-in에 가깝고, cron은 정해진 시간에 일을 실행하는 스케줄러에 가깝습니다.

이 둘이 코어 문서 안에서 비중 있게 다뤄진다는 점도 꽤 의미 있습니다.

---

5. 지금 콘텐츠로 다루기 좋은 OpenClaw 포인트 5개

1) OpenClaw는 챗봇이 아니라 gateway다

설치법보다 이 프레이밍이 먼저 들어가야 전체 구조가 더 잘 보입니다.

2) OpenClaw의 진짜 차별점은 nodes다

메신저 연동보다 카메라, 캔버스, 스크린, 위치 같은 디바이스 기능 확장이 훨씬 더 독특합니다.

3) OpenClaw는 “계속 돌아가는 assistant” 운영 도구다

heartbeat, cron, sessions, workspace를 같이 봐야 이 제품의 결이 드러납니다.

4) self-hosted인데 운영성이 강하다

strict config, doctor, health, logs, pairing 같은 운영 요소가 풍부합니다.

5) Pi only path는 제품 집중 방향을 보여준다

앞으로 OpenClaw가 무엇을 핵심 축으로 삼을지 가늠하게 해주는 포인트입니다.

---

튜토리얼 1편, OpenClaw를 처음 이해하는 사람을 위한 구조 가이드

Step 1. OpenClaw를 “AI 비서 운영 허브”라고 생각하기

처음 보면 WhatsApp이나 Telegram에 붙는 봇처럼 보일 수 있습니다.

하지만 실제로는

• 여러 메신저에서 입력을 받고
• 하나의 Gateway가 이를 라우팅하고
• agent가 응답하고
• 필요하면 node를 통해 카메라, 화면, 위치, 시스템 기능까지 쓰는 구조입니다.

그래서 OpenClaw는 메신저 봇 하나라기보다, 메신저 봇 + agent runtime + device extension을 묶어놓은 플랫폼처럼 이해하는 편이 더 자연스럽습니다.

Step 2. 가장 중요한 구성요소 4개 이해하기

1) Gateway

OpenClaw의 중심 프로세스입니다. 모든 채널과 세션이 결국 여기로 모입니다.

2) Agent

실제 응답을 생성하는 brain입니다. workspace, auth, session store를 각자 가질 수 있습니다.

3) Channels

WhatsApp, Telegram, Discord 같은 사용자 접점입니다.

4) Nodes

iOS, Android, macOS, headless 장치로, 에이전트가 활용할 수 있는 디바이스 기능을 제공합니다.

Step 3. 아주 기본적인 시작 흐름 이해하기

공식 문서 기준 빠른 시작 흐름은 대략 이렇습니다.

설치

npm install -g openclaw@latest

온보딩

openclaw onboard --install-daemon

채널 로그인

openclaw channels login

Gateway 실행

openclaw gateway --port 18789

여기까지 하면 Gateway가 기동되고, Control UI와 채널 연결 기반이 만들어집니다.

Step 4. 최소 설정 개념 잡기

OpenClaw는 ~/.openclaw/openclaw.json에서 JSON5 설정을 읽습니다.

예시 최소 설정은 아래처럼 단순합니다.

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

결국 시작 단계에서 중요한 건 세 가지입니다.

• workspace를 둘 것
• 메시지를 받을 상대를 제한할 것
• 가능한 한 안전하게 시작할 것

Step 5. 왜 allowlist와 mention gating이 중요한가

공식 문서는 초반부터 보수적 운영을 권장합니다.

이유는 단순합니다. OpenClaw는 파일을 읽고 쓸 수 있고, 메시지를 다시 보낼 수 있고, 노드나 자동화 기능까지 붙으면 생각보다 넓은 행동 범위를 갖게 됩니다.

그래서 처음에는 “무엇을 할 수 있나”보다 “누가 이 assistant를 깨울 수 있나”를 먼저 설계하는 편이 좋습니다.

Step 6. Sessions와 Workspace를 같이 이해하기

OpenClaw에서 agent는 매번 새로 태어나는 존재가 아닙니다. session과 workspace를 통해 연속성을 가집니다.

• session은 대화 흐름과 상태를 잡아주고
• workspace는 파일 기반 장기 기억과 운영 규칙을 담습니다.

이 구조가 OpenClaw를 단발성 챗봇보다 운영형 assistant에 더 가깝게 만듭니다.

Step 7. Heartbeat와 Cron 차이 이해하기

heartbeat는 정기적으로 agent turn을 돌려 “지금 보고할 게 있나”를 살피는 루프에 가깝습니다.

반면 cron은 정해진 시간이나 주기에 맞춰 특정 작업을 실행하는 스케줄러입니다.

두 기능이 비슷해 보여도 성격은 꽤 다릅니다. heartbeat는 감각에 가깝고, cron은 일정표에 가깝다고 생각하면 이해가 쉽습니다.

Step 8. OpenClaw를 특별하게 만드는 Nodes

많은 사람이 여기서 OpenClaw의 진짜 개성을 느낄 수 있습니다.

노드를 붙이면 agent가

• 캔버스에 UI를 띄우고
• 카메라 사진을 찍고
• 화면을 녹화하고
• 위치를 확인하고
• 시스템을 실행하는 식으로

실제 디바이스 기능을 활용할 수 있게 됩니다.

이건 메시지로 말만 하는 assistant와는 확실히 다른 그림입니다.

Step 9. OpenClaw를 제대로 쓰려면 무엇부터 해야 하나

초기 우선순위는 이 순서가 무난합니다.

1. Gateway 올리기
2. 한 채널만 먼저 연결하기
3. workspace 파일 정리하기
4. allowlist와 mention gating 걸기
5. heartbeat는 보수적으로 켜기
6. cron은 한두 개만 붙여보기
7. 익숙해지면 nodes 붙이기

기능을 한꺼번에 다 여는 것보다, 운영 경계를 먼저 세우고 확장하는 쪽이 훨씬 안정적입니다.

---

결론

OpenClaw 공식 문서를 자세히 읽어보면, 이 프로젝트의 중심은 단순 메신저 챗봇이 아닙니다.

OpenClaw는

• self-hosted이고
• multi-channel이며
• agent-native이고
• node로 확장되고
• 운영 도구가 풍부한

assistant runtime에 가깝습니다.

그래서 OpenClaw를 설명할 때는 “어느 채널을 지원하나”보다, 어떻게 agent를 내 메신저와 디바이스 위에서 계속 운영할 수 있게 만드나를 중심에 두는 편이 더 정확합니다.

---

출처

• OpenClaw 공식 index ` /app/docs/index.md`
• Personal Assistant Setup ` /app/docs/start/openclaw.md`
• Features ` /app/docs/concepts/features.md`
• Architecture ` /app/docs/concepts/architecture.md`
• Configuration ` /app/docs/gateway/configuration.md`
• Channels ` /app/docs/channels/index.md`
• Nodes ` /app/docs/nodes/index.md`
• Heartbeat ` /app/docs/gateway/heartbeat.md`
• Cron jobs ` /app/docs/automation/cron-jobs.md`
• Multi-agent routing ` /app/docs/concepts/multi-agent.md`