obsidian/openclaw/openclaw-manual.md at 71a1e08a476ce0e25156258d505b9d7d8c494ccc

Files

kappa 71a1e08a47 openclaw: 공식 문서 기반 매뉴얼 전면 재작성

기존 2개 섹션(4/8, 6/8)에서 14개 섹션 완전 체계로 확장:
1. 개요/설치, 2. 아키텍처, 3. 에이전트 런타임, 4. 도구,
5. 스킬, 6. 플러그인, 7. 세션, 8. 채널, 9. 게이트웨이,
10. 메모리, 11. 멀티에이전트, 12. 하트비트, 13. 자동화, 14. 보안

출처: https://docs.openclaw.ai/

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-18 16:53:35 +09:00

8.9 KiB

Raw Blame History

title, updated, tags

title

updated

1. 개요 및 설치

오픈소스 AI 에이전트 프레임워크. 메시징 앱(WhatsApp, Telegram, Discord, Slack, Signal, iMessage 등)을 통해 LLM과 대화하고, 셸 명령, 브라우저 자동화, 이메일, 파일 작업 등을 자율 수행.

설치:

# macOS/Linux
curl -fsSL https://openclaw.ai/install.sh | bash

# 온보딩 (인증, 게이트웨이, 채널 설정)
openclaw onboard --install-daemon

요구사항: Node 24 권장 (22.16+ 호환)

환경변수:

OPENCLAW_HOME: 홈 디렉토리
OPENCLAW_STATE_DIR: 상태 디렉토리
OPENCLAW_CONFIG_PATH: 설정 파일 경로

2. 아키텍처

게이트웨이(Gateway)가 중앙 데몬으로 모든 메시징 채널을 관리. 호스트당 1개만 존재. 기본 127.0.0.1:18789.

채널(WhatsApp/Telegram/Discord...) ← WebSocket → 게이트웨이 ← WebSocket → 클라이언트(CLI/macOS앱/웹UI)
                                                      ↕
                                                   노드(macOS/iOS/Android)

구성요소:

게이트웨이: 메시징 연결 유지, WebSocket API, JSON Schema 검증
클라이언트: 게이트웨이에 WebSocket 연결, send/agent/status 요청
노드: role: node로 연결, 기기 ID 기반 페어링, camera/screen 등 명령

연결 프로토콜:

첫 프레임은 반드시 connect 요청
요청/응답: {type:"req", id, method, params} ↔ {type:"res", id, ok, payload}
이벤트: {type:"event", event, payload}
보안: 새 기기는 페어링 승인 필요, 로컬은 자동 승인
원격: Tailscale/VPN 또는 SSH 터널 (ssh -N -L 18789:127.0.0.1:18789 user@host)

3. 에이전트 런타임

pi-mono 기반 단일 임베디드 에이전트 런타임. 세션 관리와 도구 연동은 OpenClaw가 직접 담당.

워크스페이스 구조:

AGENTS.md — 운영 지침 및 메모리
SOUL.md — 페르소나, 경계, 톤
TOOLS.md — 도구 사용법 가이드
IDENTITY.md — 에이전트 이름/이모지
USER.md — 사용자 프로필
BOOTSTRAP.md — 일회성 초기화 (완료 후 삭제)
HEARTBEAT.md — 하트비트 체크리스트 (선택)

모델 참조: provider/model 형식 (예: anthropic/claude-opus-4-6)

설정 파일: ~/.openclaw/openclaw.json (JSON5)

4. 도구 시스템

도구 접근 제어: tools.allow/tools.deny (deny 우선)

프로필:

minimal: 세션 상태만
coding: 파일시스템, 런타임, 세션, 메모리, 이미지
messaging: 메시징 관련
full: 제한 없음

핵심 도구:

카테고리	도구	기능
파일/실행	exec, process, read, write, edit, apply_patch	셸 명령, 백그라운드 관리, 파일 조작
웹	web_search, web_fetch	Brave/Firecrawl 검색, URL 콘텐츠 추출
UI 자동화	browser, canvas	브라우저 제어, 캔버스 드라이브
노드	nodes, device_status	페어링 노드, 카메라/화면 캡처
메시징	message	Discord/Slack/Telegram/WhatsApp 메시지 전송
세션	sessions_list, sessions_history, sessions_send, sessions_spawn	세션 관리, 서브에이전트
이미지	image, image_generate, pdf	이미지 분석/생성, PDF 분석
자동화	cron, gateway	크론 작업, 게이트웨이 설정

도구 그룹: group:fs, group:runtime, group:sessions, group:web, group:ui

5. 스킬 시스템

AgentSkills 호환 스킬 폴더. 각 스킬은 SKILL.md (YAML frontmatter) 포함 디렉토리.

로드 우선순위: 워크스페이스 skills/ > ~/.openclaw/skills/ > 번들

SKILL.md 형식:

---
name: 스킬-이름
description: 설명
user-invocable: true
metadata: { "openclaw": { "requires": { "bins": [], "env": [], "config": [] }, "os": ["darwin","linux"] } }
---
스킬 본문 (사용법, 도구 호출 가이드)

설정 오버라이드: openclaw.json의 skills.entries에서 활성화/비활성화, API 키, 환경변수 주입

ClawHub: 공개 스킬 레지스트리 — clawhub install/update/sync

6. 플러그인 시스템

매니페스트: openclaw.plugin.json (id, configSchema 필수)
슬롯: plugins.slots.memory (기본: memory-core), contextEngine
명령: openclaw plugins list|info|install|enable|disable|doctor
플러그인은 자체 스킬 디렉토리 배포 가능

7. 세션 관리

dmScope (DM 격리 방식):

값	동작
`main` (기본)	모든 DM 주 세션 공유
`per-peer`	발신자 ID로 격리
`per-channel-peer`	채널+발신자로 격리 (다중 사용자 필수)
`per-account-channel-peer`	계정+채널+발신자로 격리

세션 키 체계:

DM: agent:<agentId>:main 또는 agent:<agentId>:direct:<peerId>
그룹: agent:<agentId>:<channel>:group:<id>
Telegram 토픽: ...group:<id>:topic:<threadId>
Cron: cron:<job.id>, 웹훅: hook:<uuid>

리셋 정책:

daily (기본, atHour:4) 또는 idle (idleMinutes)
/new, /reset 명령으로 즉시 리셋
resetByType으로 direct/group/thread별, resetByChannel로 채널별 재정의

유지보수: pruneAfter:30d, maxEntries:500, maxDiskBytes:500mb (mode: warn|enforce)

저장소: ~/.openclaw/agents/<agentId>/sessions/sessions.json

8. 채널

각 채널은 openclaw.json에 설정 섹션이 있으면 자동 시작.

DM 정책: pairing(기본)|allowlist|open|disabled

주요 채널:

Telegram: botToken, streaming(off|partial|block|progress), groups, topics
Discord: token, guilds, channels, voice, thread bindings
WhatsApp: dmPolicy, allowFrom, textChunkLimit, mediaMaxMb
Slack: botToken + appToken (Socket Mode), slash commands
Signal, iMessage, IRC, Matrix, Mattermost, MS Teams, LINE, Google Chat, Nostr, Twitch, Zalo 등

9. 게이트웨이

mode: local|remote, port: 18789
bind: loopback|lan|tailnet|custom|auto
auth: none|token|password|trusted-proxy
Tailscale: mode=off|serve|funnel
서비스: openclaw gateway install|start|stop|restart|status|uninstall
RPC: openclaw gateway call {method} --params {json}
헬스: openclaw gateway health|probe|discover
HTTP API: chatCompletions, responses (OpenAI 호환)
Control UI: openclaw dashboard 또는 http://127.0.0.1:18789/

10. 메모리 시스템

평문 마크다운 파일이 유일한 진실 공급원.

파일 구조:

memory/YYYY-MM-DD.md — 일일 로그 (추가 전용)
MEMORY.md — 장기 메모리 (정선된 지속 정보)

메모리 도구: memory_search (벡터 검색), memory_get (파일 읽기)

벡터 검색:

기본 활성화, 마크다운 변경 자동 감시
제공자: local(node-llama-cpp) → openai → gemini → voyage → mistral
하이브리드 검색: BM25(30%) + 벡터(70%)
시간 감쇠: 반감기 30일 (MEMORY.md는 감쇠 없음)

메모리 플러시: 컴팩션 전 자동으로 메모리 저장 트리거 (softThresholdTokens: 4000)

11. 멀티 에이전트

각 에이전트는 독립된 워크스페이스, 세션, 인증 프로필 보유.

설정:

agents: {
  list: [
    { id: "home", workspace: "~/.openclaw/workspace-home" },
    { id: "work", workspace: "~/.openclaw/workspace-work" }
  ]
},
bindings: [
  { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
  { agentId: "work", match: { channel: "discord", guildId: "123" } }
]

라우팅 우선순위: peer > parentPeer > guildId+roles > guildId > teamId > accountId > channel > 기본

에이전트 관리: openclaw agents add|list|remove, 에이전트별 샌드박스/도구 제한 가능

12. 하트비트

정기적 에이전트 실행으로 백그라운드 작업/상태 확인 자동화.

설정:

heartbeat: {
  every: "30m",
  activeHours: "09:00-22:00",
  model: "openai/gpt-5.2-mini",
  to: "last",
  isolatedSession: true
}

HEARTBEAT_OK 응답 시 자동 제거 (알림 없음)
isolatedSession: true로 토큰 100K → 2-5K 절감
HEARTBEAT.md 파일로 체크리스트 관리

13. 자동화

Cron: openclaw cron list|add|remove, 게이트웨이 내장 스케줄러
Hooks: 이벤트 기반 트리거 (automation/hooks)
Webhooks: 외부 서비스 연동 (automation/webhook)
Polls: 주기적 외부 상태 확인 (automation/poll)
Gmail PubSub: Gmail 실시간 알림 (automation/gmail-pubsub)

14. 보안 및 샌드박싱

샌드박스 모드:

off: 제한 없음
non-main: 메인 에이전트 외 샌드박스 적용
all: 모든 에이전트 샌드박스

도구 정책: exec deny(기본)|allowlist|full

기기 페어링: 새 기기는 승인 필요, 로컬은 자동, 원격은 명시적

스킬 보안: 제3자 스킬은 신뢰할 수 없는 코드로 취급, 활성화 전 검토 필수

8.9 KiB Raw Blame History