VPS에 OpenClaw AI 설치 가이드

VPS에 OpenClaw AI 에이전트 배포: 스크립트 포함 단계별 가이드

OpenClaw는 텔레그램을 통해 VPS를 관리하는 오픈소스 AI 에이전트입니다. 전체 스택: docker-compose, bash 도구 스크립트, 컨텍스트 설정. 레포 클론 후 .env에 API 키 설정하고 deploy.sh 실행 — 10분 만에 시스템 준비 완료. 에이전트는 컨테이너 모니터링, SQL 쿼리 실행, 서비스 재시작, 하트비트 확인 등을 처리합니다.

시스템 아키텍처

OpenClaw는 ghcr.io/openclaw/openclaw 도커 컨테이너에서 실행되며, /var/run/docker.sock, /var/www/projects, /var/log/nginx를 마운트합니다. workspace/SOUL.md의 컨텍스트가 동작을 정의합니다: PostgreSQL 컨테이너 목록, 프로젝트 테이블, 보안 규칙.

/tools/의 스크립트는 요청에 따라 트리거됩니다:

• docker-status.sh, docker-logs.sh, docker-restart.sh
• PostgreSQL용 db-discover.sh, db-query.sh
• HTTP 사이트 모니터링용 health-check.sh
• system-stats.sh, security-check.sh

에이전트는 자연어를 처리합니다: “auth 서비스 로그” → docker-logs.sh auth-container.

최소 요구 사항

• Ubuntu 20.04+ 또는 Docker Compose V2가 설치된 리눅스 (docker compose version)
• 2 GB RAM (에이전트 ~300–500 MB)
• OpenRouter API 키 (openrouter.ai/keys) — GPT-4o, Claude 모델용
• @BotFather에서 발급받은 텔레그램 봇 토큰

1단계: 레포 설정

ssh user@your-server
git clone https://github.com/ShyDamn/openclaw-devops-kit.git /tmp/openclaw-setup
cd /tmp/openclaw-setup

구조:

openclaw-devops-kit/
├── docker-compose.yml
├── .env.example
├── deploy.sh
├── config/openclaw.json
├── workspace/SOUL.md, USER.md, HEARTBEAT.md
└── tools/ (14개 스크립트: docker-*.sh, db-*.sh, health-check.sh 등)

2단계: 텔레그램 봇 및 .env 설정

• @BotFather → /newbot → 토큰 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
• @userinfobot → 사용자 ID 778921250

cp .env.example .env
nano .env

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx
YOUTRACK_TOKEN=perm:your-token-here  # 선택

config/openclaw.json에서:

"allowFrom": [
  "tg:778921250"
]

3단계: workspace/ 컨텍스트 설정

SOUL.md — 핵심 동작

PostgreSQL 컨테이너와 프로젝트 목록:

## PostgreSQL 컨테이너: db1, db2, db3

| Path | Project | Stack |
|------|---------|-------|
| /projects/my-app/ | SaaS | Next.js + PostgreSQL |
| /projects/api/ | Backend | NestJS |

규칙: 확인 없이 읽기, 수정 시 이중 확인.

USER.md — 사용자 프로필

타임존, 기술 스택, 주요 프로젝트.

HEARTBEAT.md — 시간별 체크리스트

리소스 모니터링, 컨테이너 상태, HTTP 사이트.

4단계: 사이트 모니터링

tools/health-check.sh에서:

SITES=(
  "mysite.com|mysite-frontend|mysite"
  "api.mysite.com|mysite-api|mysite"
)

형식: 도메인|컨테이너|프로젝트. 5xx/타임아웃 시 자동 재시작, 실패 시 알림.

5단계: 배포 및 실행

bash deploy.sh

자동화:

• Docker Compose V2 확인
• /var/www/openclaw/ 생성
• .env 권한 설정 (chmod 600)
• 이미지 풀
• 컨테이너 시작

텔레그램 페어링:

cd /var/www/openclaw
docker compose run --rm --profile cli openclaw-cli pairing approve telegram <CODE>

주요 스크립트 분석

docker-logs.sh

#!/bin/bash
CONTAINER="${1:?Usage: docker-logs.sh <container_name> [lines]}"
LINES="${2:-50}"
docker logs --tail "$LINES" "$CONTAINER" 2>&1

SOUL.md에서 컨테이너 자동 감지.

system-stats.sh

#!/bin/bash
echo "=== RAM ==="
free -h
echo ""
echo "=== DISK ==="
df -h / | tail -1
# ... CPU, docker stats

하트비트용 포괄적 출력.

db-discover.sh — 데이터베이스 탐색

#!/bin/bash
for c in $(docker ps --format '{{.Names}}' | grep -i postgres); do
  echo "=== $c ==="
  DB_USER=$(docker exec "$c" printenv POSTGRES_USER 2>/dev/null)
  # ...
  docker exec "$c" psql -U "$DB_USER" -d "$DB_NAME" -c "\dt"
done

모든 PostgreSQL 인스턴스 자동 발견, POSTGRES_USER/POSTGRES_DB 추출, 테이블 목록.

db-query.sh

컨테이너 파라미터로 SQL 실행.

주요 포인트

• SOUL.md 컨텍스트가 핵심: 프로젝트/컨테이너 테이블 없으면 세부 정보 요청.
• openclaw.json 화이트리스트: 텔레그램 ID만 접근, 유출 방지.
• health-check.sh 자동 재시작: 5xx → 재시작 → 검증 → 알림.
• MIT 라이선스: 스크립트/설정 완전 제어.
• OpenRouter: 실패 시 모델 로테이션 (GPT-4o, Claude), 단일 API.

— Editorial Team