Ansible 설치

프로덕션 서버에 OpenClaw를 배포하는 권장 방법은 openclaw-ansible — 보안 우선 아키텍처를 갖춘 자동화된 설치 프로그램을 사용하는 것입니다.

빠른 시작

한 줄 명령 설치:

curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

📦 전체 가이드: github.com/openclaw/openclaw-ansible

openclaw-ansible 저장소가 Ansible 배포의 신뢰할 수 있는 소스입니다. 이 페이지는 빠른 개요입니다.

제공되는 기능

  • 🔒 방화벽 우선 보안: UFW + Docker 격리 (SSH + Tailscale만 접근 가능)
  • 🔐 Tailscale VPN: 서비스를 공개적으로 노출하지 않고 안전한 원격 액세스
  • 🐳 Docker: 격리된 sandbox 컨테이너, localhost 전용 바인딩
  • 🛡️ 심층 방어: 4계층 보안 아키텍처
  • 🚀 한 줄 명령 설정: 몇 분 안에 완전한 배포
  • 🔧 Systemd 통합: 강화와 함께 부팅 시 자동 시작

요구 사항

  • OS: Debian 11+ 또는 Ubuntu 20.04+
  • 액세스: Root 또는 sudo 권한
  • 네트워크: 패키지 설치를 위한 인터넷 연결
  • Ansible: 2.14+ (빠른 시작 스크립트로 자동 설치)

설치되는 항목

Ansible playbook은 다음을 설치하고 구성합니다:

  1. Tailscale (안전한 원격 액세스를 위한 mesh VPN)
  2. UFW 방화벽 (SSH + Tailscale 포트만)
  3. Docker CE + Compose V2 (agent sandbox용)
  4. Node.js 22.x + pnpm (런타임 의존성)
  5. OpenClaw (호스트 기반, 컨테이너화되지 않음)
  6. Systemd 서비스 (보안 강화와 함께 자동 시작)

참고: Gateway는 호스트에서 직접 실행되지만(Docker에서 실행되지 않음), agent sandbox는 격리를 위해 Docker를 사용합니다. 자세한 내용은 Sandboxing을 참조하세요.

설치 후 설정

설치가 완료되면 openclaw 사용자로 전환하세요:

sudo -i -u openclaw

설치 후 스크립트가 다음 과정을 안내합니다:

  1. 온보딩 마법사: OpenClaw 설정 구성
  2. Provider 로그인: WhatsApp/Telegram/Discord/Signal 연결
  3. Gateway 테스트: 설치 확인
  4. Tailscale 설정: VPN mesh 연결

빠른 명령

# 서비스 상태 확인
sudo systemctl status openclaw

# 실시간 로그 보기
sudo journalctl -u openclaw -f

# Gateway 재시작
sudo systemctl restart openclaw

# Provider 로그인 (openclaw 사용자로 실행)
sudo -i -u openclaw
openclaw channels login

보안 아키텍처

4계층 방어

  1. 방화벽 (UFW): SSH (22) + Tailscale (41641/udp)만 공개적으로 노출
  2. VPN (Tailscale): VPN mesh를 통해서만 Gateway 액세스 가능
  3. Docker 격리: DOCKER-USER iptables 체인이 외부 포트 노출 방지
  4. Systemd 강화: NoNewPrivileges, PrivateTmp, 비권한 사용자

검증

외부 공격 표면 테스트:

nmap -p- YOUR_SERVER_IP

포트 22 (SSH)만 열려 있어야 합니다. 다른 모든 서비스(Gateway, Docker)는 잠겨 있습니다.

Docker 가용성

Docker는 Gateway 자체를 실행하는 것이 아니라 agent sandbox (격리된 도구 실행)용으로 설치됩니다. Gateway는 localhost에만 바인딩되며 Tailscale VPN을 통해 액세스할 수 있습니다.

sandbox 구성에 대한 내용은 Multi-Agent Sandbox & Tools를 참조하세요.

수동 설치

자동화보다 수동 제어를 선호하는 경우:

# 1. 전제 조건 설치
sudo apt update && sudo apt install -y ansible git

# 2. 저장소 클론
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible

# 3. Ansible 컬렉션 설치
ansible-galaxy collection install -r requirements.yml

# 4. playbook 실행
./run-playbook.sh

# 또는 직접 실행 (이후 /tmp/openclaw-setup.sh를 수동으로 실행)
# ansible-playbook playbook.yml --ask-become-pass

OpenClaw 업데이트

Ansible 설치 프로그램은 수동 업데이트를 위해 OpenClaw를 설정합니다. 표준 업데이트 플로우는 Updating을 참조하세요.

Ansible playbook을 다시 실행하려면 (예: 구성 변경):

cd openclaw-ansible
./run-playbook.sh

참고: 이것은 멱등성이 있으며 여러 번 실행해도 안전합니다.

문제 해결

방화벽이 연결을 차단함

잠금된 경우:

  • 먼저 Tailscale VPN을 통해 액세스할 수 있는지 확인하세요
  • SSH 액세스(포트 22)는 항상 허용됩니다
  • Gateway는 설계상 Tailscale을 통해서만 액세스할 수 있습니다

서비스가 시작되지 않음

# 로그 확인
sudo journalctl -u openclaw -n 100

# 권한 확인
sudo ls -la /opt/openclaw

# 수동 시작 테스트
sudo -i -u openclaw
cd ~/openclaw
pnpm start

Docker sandbox 문제

# Docker가 실행 중인지 확인
sudo systemctl status docker

# sandbox 이미지 확인
sudo docker images | grep openclaw-sandbox

# sandbox 이미지가 없는 경우 빌드
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh

Provider 로그인 실패

openclaw 사용자로 실행하고 있는지 확인하세요:

sudo -i -u openclaw
openclaw channels login

고급 구성

자세한 보안 아키텍처 및 문제 해결:

관련 자료

← 문서로 돌아가기