OpenClaw API 시작하기(2026): 홈서버에서 에이전트 자동화를 붙이는 최소 구성

이 글은 OpenClaw를 기준으로 “홈서버 자동화를 API/웹훅으로 연결하는 방법”을 정리한다. 단순히 챗봇처럼 말만 하는 게 아니라, 외부 이벤트(백업 완료, 디스크 임계치, CI 결과 등)가 들어왔을 때 OpenClaw가 요약/판단/도구 실행까지 하고 결과를 Telegram 같은 채널로 돌려주는 흐름이 핵심이다.

이 글의 목표(성공 기준)

openclaw gateway status가 정상으로 나온다.
openclaw dashboard(Control UI)에서 대화/상태 확인이 된다.
/hooks 엔드포인트를 켜고 토큰으로 보호한다.
/hooks/wake 또는 /hooks/agent로 외부에서 “에이전트 1턴 실행”이 된다.
결과가 Telegram 등으로 다시 전달된다(운영 루프 완성).

이 글에서 다루는 범위

초보자 기준으로 “설치 → 동작 확인 → 웹훅으로 외부 트리거 연결”까지 최소 구성을 다룬다. 반대로 대규모 운영(여러 에이전트/여러 채널/복잡한 RBAC)은 이후 확장 파트로 남긴다.

집에 홈서버(Proxmox/Ubuntu/N100 미니PC 등)를 꾸려두면, 결국 하고 싶은 건 하나입니다.

“상태 확인(디스크/컨테이너/백업) 같은 반복 작업을 내가 직접 안 하고”
“메신저(특히 Telegram)에서 한 줄 던지면 서버가 알아서 움직이고”
“필요할 때만 사람이 승인해서 실수는 줄이고”

이걸 ‘그럴듯한 챗봇’이 아니라, 실제로 도구를 호출하는 개인 비서로 만들려면 “외부 트리거(API/웹훅)”가 필요합니다.

오늘은 OpenClaw를 기준으로, Gateway를 홈서버에 올린 뒤 → WebChat/Control UI로 확인 → Telegram 연동 → Webhook(API)로 외부 트리거까지 이어지는 “최소 구성”을 정리합니다.

이 글의 목표: “내 홈서버에서 OpenClaw가 돌아가고, curl 한 번으로 에이전트를 깨워서 일을 시킬 수 있게” 만들기

OpenClaw에서 말하는 ‘API’는 뭐예요?

OpenClaw는 구조가 단순합니다.

Gateway: 세션/채널/도구/이벤트를 관리하는 컨트롤 플레인(제어면)
Agent: 실제로 대화를 처리하고 작업을 수행하는 실행 단위
Channels: Telegram/WhatsApp/Slack/Discord 등 “입출력 창구”
Hooks(Webhooks): 외부 시스템이 HTTP로 Gateway를 깨우는 “트리거”

많은 분들이 ‘API’라고 하면 REST로 CRUD를 떠올리는데, OpenClaw에서 실전에서 자주 쓰는 “OpenClaw API”는 보통 아래 2가지입니다.

1) Control UI / Dashboard: 브라우저에서 대화하고 상태를 확인하는 웹 UI 2) Webhooks: POST /hooks/...로 “지금 에이전트 실행해줘”를 외부에서 트리거

즉, “OpenClaw API”는 단순히 데이터 조회가 아니라,

외부 시스템의 이벤트를 OpenClaw로 넘기고
OpenClaw가 판단/정리/도구 실행까지 하고
결과를 다시 Telegram 같은 채널로 돌려주는

자동화의 연결부로 이해하는 게 맞습니다.

공식 문서(필수): – OpenClaw Docs: https://docs.openclaw.ai – Webhooks: https://docs.openclaw.ai/automation/webhook – Getting Started: https://docs.openclaw.ai/start/getting-started – GitHub: https://github.com/openclaw/openclaw

(비교) OpenClaw Webhook vs 크론 스크립트 vs n8n

홈랩 자동화에서 흔한 선택지를 현실적으로 비교해보면 이렇게 정리됩니다.

선택지	장점	단점	이런 분께 추천
단순 크론 + bash/python	가장 가볍고 예측 가능	대화형/승인 흐름이 약함, 맥락 유지 어려움	“정해진 작업만” 돌릴 때
n8n	UI가 편하고 커넥터 많음	에이전트형 판단(문서 읽고 요약/결정)이 약함	워크플로우 자동화 중심
OpenClaw + Webhook(API)	“메시지/승인/도구”가 한 시스템에서 연결됨	처음 진입 시 개념(세션/에이전트/훅)이 낯설 수 있음	홈서버에 개인 비서를 붙이고 싶을 때

저는 “외부 이벤트가 올 때마다 사람이 판단해야 하는 작업(알림 요약, 장애 상황 정리, 특정 조건일 때만 실행)”은 OpenClaw 스타일이 특히 잘 맞는 편이라고 봅니다.

최소 구성 아키텍처 (그림으로 이해하기)

OpenClaw는 ‘내 서버 안에서 도는 비서’에 가깝습니다.

홈서버(또는 작은 Linux 인스턴스)에 Gateway를 올리고
내 폰/PC에서는 Telegram이나 WebChat으로 대화하고
필요하면 노드(디바이스)를 붙여 카메라/스크린 같은 로컬 기능을 확장합니다.

아래 이미지는 OpenClaw 프로젝트(GitHub)에서 가져온 공식 소스 기반 시각 자료입니다.

(캡션) 출처: openclaw/openclaw (GitHub) https://github.com/openclaw/openclaw

1) 설치: 홈서버에 OpenClaw 올리기

공식 Getting Started의 권장 흐름은 간단합니다.

(1) 준비물

Node.js 22 이상
(권장) 홈서버 OS: Ubuntu 22.04/24.04

(2) 설치(권장: 설치 스크립트)

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

다른 설치 방식은 공식 Install 문서도 참고하세요.

(3) 온보딩 위저드 실행

openclaw onboard --install-daemon

위저드가 해주는 일(요약):

Gateway 실행(백그라운드 서비스)
기본 설정 파일 생성
(선택) 채널 연결 가이드

(4) Gateway 상태 확인

openclaw gateway status

2) “설정 파일은 어디 있죠?” (초보자에게 제일 중요한 부분)

OpenClaw을 만지다 보면, 결국 설정 파일 위치를 알아야 합니다.

기본 설정 파일은 보통 아래 경로에 있습니다.

~/.openclaw/openclaw.json

또는 환경변수로 경로를 바꿀 수도 있습니다.

OPENCLAW_CONFIG_PATH
OPENCLAW_HOME

이 글에서 소개하는 OpenClaw API(Webhook)를 켜는 작업도 결국 openclaw.json에 hooks 섹션을 추가하는 방식이라고 이해하시면 됩니다.

3) 제일 먼저 확인: Control UI(웹)로 대화가 되나요?

채널(Telegram)을 붙이기 전에, 먼저 Gateway가 제대로 도는지 확인하는 게 정신 건강에 좋습니다.

공식 문서에서는 이렇게 안내합니다.

openclaw dashboard
또는 Gateway 호스트에서 http://127.0.0.1:18789/ 접속

openclaw dashboard

여기까지 성공하면 “서버에 OpenClaw가 상주하고 있다”는 뜻이라, 그 다음 단계부터는 옵션입니다.

4) Telegram 연동(개념만 잡기)

OpenClaw는 여러 채널을 붙일 수 있지만, 홈랩에서는 Telegram이 제일 쓰기 쉬운 축에 듭니다.

흐름은 대략 이렇습니다.

1) Telegram에서 봇을 만들고 토큰을 발급 2) TELEGRAM_BOT_TOKEN(또는 설정 파일의 telegram 섹션)에 등록 3) “누구에게 응답할지” 정책을 정함

공식 문서: – Telegram 채널: https://docs.openclaw.ai/channels/telegram – DM 페어링/승인 흐름: https://docs.openclaw.ai/channels/pairing

팁: 처음엔 “내 계정 DM만 허용” 같은 최소 범위로 시작하는 편이 안정적입니다.

5) 핵심: OpenClaw Webhook(API)로 외부 트리거 붙이기

이제 오늘의 메인입니다.

홈서버 안에서 돌아가는 Gateway를
외부 시스템(예: NAS, 모니터링, GitHub Actions, n8n, Home Assistant 등)이
HTTP로 깨워서 “에이전트 1턴 실행”을 요청할 수 있습니다.

이게 왜 좋냐면요.

외부 시스템은 그냥 이벤트/로그를 던지기만 하면 되고
복잡한 판단(요약/우선순위/다음 액션 결정)은 OpenClaw가 가져갈 수 있습니다.

(1) hooks 활성화 설정

공식 문서의 예시는 아래와 같습니다.

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",

    // Optional: 특정 agentId로 라우팅을 허용할지
    allowedAgentIds: ["hooks", "main"],
  },
}

핵심 포인트는 2개입니다.

hooks.enabled=true일 때 token은 필수
토큰 전달은 쿼리스트링이 아니라 헤더로

(2) 토큰은 어떻게 보내나요?

공식 문서에서는 세 가지를 언급합니다.

Authorization: Bearer <token> (권장)
x-openclaw-token: <token>

그리고 중요한 규칙 하나:

?token=... 형태의 쿼리스트링 토큰은 거절됩니다.

(3) 엔드포인트: /hooks/wake

이건 말 그대로 “메인 세션 깨우기”입니다.

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

mode=now: 즉시 깨움
mode=next-heartbeat: 다음 주기 점검(하트비트)까지 대기

홈랩에 적용하면 이런 패턴이 됩니다.

“백업 완료” 같은 신호가 왔을 때 → wake로 깨워서 “오늘 백업 상태 요약해줘” 같은 정기 점검을 바로 실행

(4) 엔드포인트: /hooks/agent (가장 실전)

/hooks/agent는 외부에서 에이전트에게 “이 메시지 실행해줘” 라고 요청하는 방식입니다.

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

이 방식이 좋은 이유는 간단합니다.

외부 시스템은 복잡한 판단을 안 해도 되고
OpenClaw 쪽에서 “요약/정리/의사결정/도구 호출”을 맡게 할 수 있습니다.

추가로, 공식 문서에 따르면 /hooks/agent는 이런 필드를 더 받을 수 있습니다.

channel: 결과를 어느 채널로 보낼지(예: telegram)
to: 텔레그램 chat_id 같은 대상
model, thinking: 이 훅 실행 1회에 한해 모델/사고 수준을 바꾸기
timeoutSeconds: 훅 실행 제한 시간

즉, “OpenClaw API(Webhook)”를 붙이면 자동화가 ‘연결’이 됩니다.

6) 바로 써먹는 예시 3개 (홈서버 자동화 관점)

예시 A) 디스크 사용량이 임계치 넘으면: “원인 후보 + 정리 + 다음 행동”으로 변환

대부분의 홈서버 사고는 사실 이런 형태죠.

“디스크가 90% 찼다”
그런데 무엇이 찼는지 확인하려면 여러 명령을 실행해야 함

여기서 외부 시스템(크론/모니터링)은 측정만 하고, OpenClaw는 설명/정리를 맡기면 일이 편해집니다.

예를 들어 크론에서 이렇게 트리거할 수 있습니다.

#!/usr/bin/env bash
set -euo pipefail

THRESHOLD=85
USEP=$(df -P / | awk 'END{gsub(/%/,"",$5); print $5}')

if [ "$USEP" -ge "$THRESHOLD" ]; then
  PAYLOAD=$(jq -n --arg msg "루트(/) 디스크 사용량이 ${USEP}%입니다. 원인(큰 디렉터리/로그/도커) 후보를 단계별로 정리해주고, 제가 바로 할 수 있는 체크 명령도 함께 제안해줘." '{message:$msg,name:"disk",wakeMode:"now"}')

  curl -sS -X POST http://127.0.0.1:18789/hooks/agent \
    -H 'Authorization: Bearer SECRET' \
    -H 'Content-Type: application/json' \
    -d "$PAYLOAD" >/dev/null
fi

포인트는 이것뿐입니다.

크론은 “85% 넘었는지”만 판단
OpenClaw는 “왜 그럴 수 있는지/어떻게 확인할지”를 대화로 풀어줌

예시 B) n8n에서 복잡한 워크플로우를 돌리고, 판단은 OpenClaw에 맡기기

n8n은 “연결/전달”이 강합니다.

GitHub → Slack → Notion 같은 파이프를 만들기 좋고
Webhook으로 다른 시스템을 깨우는 것도 쉽습니다.

반대로 OpenClaw는 “문맥 + 요약 + 도구 실행”이 강합니다.

그래서 조합을 이렇게 잡으면 실용적입니다.

n8n이 여러 이벤트를 모아서
OpenClaw API(/hooks/agent)로 “하나의 메시지”로 변환해서 던지고
OpenClaw가 정리/우선순위/액션을 만들어서 Telegram으로 돌려주는 형태

예시 C) GitHub Actions에서 배포가 끝나면: ‘요약 보고서’를 자동으로 받기

CI/CD는 이벤트가 명확합니다.

성공/실패
변경된 내용
릴리즈 노트

GitHub Actions에서 배포가 끝나면, 마지막 스텝에서 curl로 /hooks/agent를 호출해 “배포 요약 + 체크리스트”를 받아보는 것도 가능합니다.

핵심은 똑같습니다.

Actions는 “사실(로그/결과)”만 전달
OpenClaw는 “사람이 읽기 좋은 브리핑”으로 변환

7) 훅(Webhook)을 쓸 때 주의할 것 (필수 보안 설정)

OpenClaw Webhook은 강력합니다. 그래서 최소한 아래 정도는 지키는 걸 권합니다.

훅 엔드포인트는 가능하면 로컬(127.0.0.1), 또는 신뢰 가능한 네트워크에서만 접근
토큰은 짧게 쓰지 말고, 채널 토큰과 별개로 관리
훅 페이로드에 민감정보를 그대로 넣지 않기(로그/히스토리에 남을 수 있음)
여러 에이전트를 운영한다면 allowedAgentIds로 라우팅 범위를 좁히기

공식 Webhooks 문서의 “Security” 섹션도 꼭 한 번 읽어보세요.

https://docs.openclaw.ai/automation/webhook

8) 내부 링크(추천 읽을거리)

OpenClaw를 홈랩에 붙이다 보면, 결국 로컬 LLM/툴 연동으로 확장하게 됩니다.

로컬 LLM 연동에서 자주 막히는 포인트:
OpenClaw 로컬 LLM 연동 트러블슈팅: N100 홈서버 Ollama + baseUrl 설정 완전정복 (2026)
로컬 LLM에 ‘도구’를 붙이는 MCP 입문(실전):
https://homelablog.com/ollama-mcp-%ec%8b%9c%ec%9e%91%ed%95%98%ea%b8%b02026-%eb%a1%9c%ec%bb%ac-llm%ec%97%90-%eb%8f%84%ea%b5%ac%ed%8c%8c%ec%9d%bc-%ec%9b%b9-%ea%b9%83-%ec%97%b0%ea%b2%b0%ed%95%98%eb%8a%94-%ec%8b%a4/

9) 자주 묻는 질문(FAQ)

Q1. “OpenClaw API”를 쓰려면 꼭 Telegram이 있어야 하나요?

아니요. 처음에는 Control UI(WebChat)만으로도 충분합니다.

openclaw dashboard
http://127.0.0.1:18789/

이게 열리면 OpenClaw 자체는 이미 돌아가고 있는 겁니다.

Q2. Webhook을 켰는데 401이 떠요

대부분 토큰 문제입니다.

Authorization: Bearer <token> 헤더가 있는지
x-openclaw-token을 썼다면 정확한 값인지
쿼리스트링으로 토큰을 보내고 있지 않은지(?token=은 거절)

Q3. /hooks/agent가 바로 응답을 안 주는 것 같아요

공식 문서에 따르면 /hooks/agent는 비동기(202)로 동작할 수 있습니다.

“훅 실행이 시작됐다”는 의미로 받아들이고
결과는 설정된 전달(channel/to) 또는 메인 세션 요약으로 확인하는 흐름이 자연스럽습니다.

10) 오늘 글의 체크리스트 (성공 기준)

아래 6개 중 4개만 통과해도, 이미 OpenClaw API(Webhook)를 “홈서버 자동화에 붙일 준비”는 끝났다고 봐도 됩니다.

[ ] openclaw gateway status가 정상
[ ] openclaw dashboard가 열림(또는 http://127.0.0.1:18789/ 접속)
[ ] ~/.openclaw/openclaw.json에서 hooks 설정을 추가했다
[ ] curl -X POST ... /hooks/wake가 200으로 응답한다
[ ] curl -X POST ... /hooks/agent가 202로 응답한다
[ ] (선택) Telegram에서 메시지를 주고받을 수 있다

이제 남은 건 “내 환경에서 어떤 이벤트를 훅으로 보낼지”를 하나만 정해서 붙여보는 겁니다.

마무리: “API가 있으면, 자동화는 ‘연결’이 된다”

OpenClaw를 써보면 결국 깨닫는 게 있습니다.

자동화의 핵심은 ‘스크립트’가 아니라
트리거(이벤트) + 대화(맥락) + 도구(실행)를 한 덩어리로 연결하는 것

오늘 정리한 최소 구성은 딱 여기까지입니다.

Gateway가 홈서버에서 돈다
Control UI로 기본 동작을 확인했다
OpenClaw Webhook(API)로 외부에서 “에이전트 1턴”을 깨울 수 있다

여기까지 되면, 그 다음은 취향입니다.

n8n과 섞어서 쓰거나
모니터링/로그 시스템을 훅으로 붙이거나
로컬 LLM(Ollama) + MCP로 도구를 더 붙이거나

원하는 방향으로 확장해도 기본 골격은 그대로 유지됩니다.

(다음 글 아이디어) hooks.mappings로 “내 시스템의 JSON 알림”을 OpenClaw 이벤트로 변환하는 실전 예시도 정리해볼 만 합니다.

자주 막히는 지점(트러블슈팅)

게이트웨이 타임아웃/접속 불가: 포트 충돌/방화벽/로컬 WS 상태부터 확인
훅 호출은 되는데 동작이 없음: 토큰/라우팅/에이전트 지정 값을 먼저 점검
브라우저 자동화 불안정: 탭 연결(프로필)과 타임아웃 설정을 조정

결론 + 다음 단계

OpenClaw는 설치보다 ‘연결’이 핵심입니다. 웹훅이 1번이라도 안정적으로 왕복하면 이후 자동화 확장은 빠릅니다. 다음 단계로는 (1) 자주 쓰는 체크(모니터링/백업)부터 훅으로 붙이고, (2) n8n/MCP 같은 도구 연계를 늘려 “반복 작업”을 줄이는 방향이 효율적입니다.

3줄 요약