obsidian/openclaw/openclaw-reference.md at b1ba9f1d90e9f42ba7efd21ea34d5ecf4a643b7b

Files

kappa 8eb637cc22 Obsidian vault 리팩토링: openclaw 통합, 태그 정규화, 상호참조 보강

- openclaw: 14개 소형 레퍼런스 파일(10~30줄) → openclaw-reference.md 1개로 통합
  - 삭제: architecture, runtime, tools, skills, plugins, sessions, channels, gateway, memory, multi-agent, heartbeat, automation, security, install
  - 유지: agents(운영), jarvis(서버설정), ollama(통합가이드), manual(인덱스)
- 태그 추가 (10개 파일): tasks, dev-environment, infra-forge, vault, cert-manager, cloudflare, openclaw-agents, irondesk, irondesk-tax-legal, aws-ses, telegram-bot, twilio
- 상호참조: cloudflare.md에 netbis/cf-multisite/crowdsec/bunnycdn 링크 추가
- telegram-bot.md에 openclaw-jarvis 참조 추가

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

2026-04-04 15:10:20 +09:00

9.0 KiB

Raw Blame History

title, updated, tags

title

updated

개요 및 설치

오픈소스 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

온보딩 4단계:

openclaw onboard --install-daemon — 인증, 게이트웨이, 채널 설정
openclaw gateway status — 서비스 상태 점검
openclaw dashboard — 제어 UI (http://127.0.0.1:18789/)
제어 UI 정상 로드 확인

아키텍처

게이트웨이(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)

에이전트 런타임

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)

도구 시스템

도구 접근 제어: 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

스킬 시스템

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

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

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

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

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

플러그인 시스템

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

세션 관리

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

채널

각 채널은 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 등

게이트웨이

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/

메모리 시스템

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

파일 구조: 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)

멀티 에이전트

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

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, 에이전트별 샌드박스/도구 제한 가능

하트비트

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

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 파일로 체크리스트 관리

자동화

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

보안 및 샌드박싱

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

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

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

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

9.0 KiB Raw Blame History