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: 격리된 샌드박스 컨테이너, localhost 전용 바인딩
🛡️ 심층 방어: 4계층 보안 아키텍처
🚀 단일 명령 설정: 수분 내 전체 배포 완료
🔧 Systemd 통합: 보안 강화 옵션과 함께 부팅 시 자동 시작

요구 사항¶

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

설치되는 항목¶

Ansible 플레이북은 다음을 설치 및 구성합니다:

Tailscale (안전한 원격 액세스를 위한 메시 VPN)
UFW 방화벽 (SSH + Tailscale 포트만 허용)
Docker CE + Compose V2 (에이전트 샌드박스용)
Node.js 22.x + pnpm (런타임 의존성)
OpenClaw (컨테이너가 아닌 호스트 기반 실행)
Systemd 서비스 (보안 강화와 함께 자동 시작)

참고: Gateway(게이트웨이) 는 Docker 가 아닌 호스트에서 직접 실행 되며, 에이전트 샌드박스는 격리를 위해 Docker 를 사용합니다. 자세한 내용은 Sandboxing 을 참고하십시오.

설치 후 설정¶

설치가 완료되면 openclaw 사용자로 전환하십시오:

sudo -i -u openclaw

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

온보딩 마법사: OpenClaw 설정 구성
프로바이더 로그인: WhatsApp/Telegram/Discord/Signal 연결
Gateway 테스트: 설치 검증
Tailscale 설정: VPN 메시 연결

빠른 명령어¶

# Check service status
sudo systemctl status openclaw

# View live logs
sudo journalctl -u openclaw -f

# Restart gateway
sudo systemctl restart openclaw

# Provider login (run as openclaw user)
sudo -i -u openclaw
openclaw channels login

보안 아키텍처¶

4계층 방어¶

방화벽 (UFW): 외부에 공개되는 포트는 SSH (22) 와 Tailscale (41641/udp) 만 허용
VPN (Tailscale): Gateway 는 VPN 메시를 통해서만 접근 가능
Docker 격리: DOCKER-USER iptables 체인이 외부 포트 노출을 차단
Systemd 보안 강화: NoNewPrivileges, PrivateTmp, 비특권 사용자 실행

검증¶

외부 공격 표면을 테스트하십시오:

nmap -p- YOUR_SERVER_IP

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

Docker 사용 범위¶

Docker 는 에이전트 샌드박스 (격리된 도구 실행) 를 위해 설치되며, Gateway 자체를 실행하는 용도는 아닙니다. Gateway 는 localhost 에만 바인딩되며 Tailscale VPN 을 통해 접근합니다.

샌드박스 구성에 대해서는 Multi-Agent Sandbox & Tools 를 참고하십시오.

수동 설치¶

자동화 대신 수동 제어를 선호하는 경우:

# 1. Install prerequisites
sudo apt update && sudo apt install -y ansible git

# 2. Clone repository
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible

# 3. Install Ansible collections
ansible-galaxy collection install -r requirements.yml

# 4. Run playbook
./run-playbook.sh

# Or run directly (then manually execute /tmp/openclaw-setup.sh after)
# ansible-playbook playbook.yml --ask-become-pass

OpenClaw 업데이트¶

Ansible 설치 프로그램은 OpenClaw 를 수동 업데이트 방식으로 설정합니다. 표준 업데이트 절차는 Updating 을 참고하십시오.

구성 변경 등을 위해 Ansible 플레이북을 다시 실행하려면:

cd openclaw-ansible
./run-playbook.sh

참고: 이 작업은 멱등적이며 여러 번 실행해도 안전합니다.

문제 해결¶

방화벽이 연결을 차단하는 경우¶

접근이 차단된 경우 다음을 확인하십시오:

먼저 Tailscale VPN 을 통해 접근 가능한지 확인하십시오
SSH 접근 (포트 22) 은 항상 허용됩니다
Gateway 는 설계상 Tailscale 을 통해서만 접근 가능합니다

서비스가 시작되지 않는 경우¶

# Check logs
sudo journalctl -u openclaw -n 100

# Verify permissions
sudo ls -la /opt/openclaw

# Test manual start
sudo -i -u openclaw
cd ~/openclaw
pnpm start

Docker 샌드박스 문제¶

# Verify Docker is running
sudo systemctl status docker

# Check sandbox image
sudo docker images | grep openclaw-sandbox

# Build sandbox image if missing
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh

프로바이더 로그인 실패¶

다음 사용자로 실행 중인지 확인하십시오: openclaw 사용자:

sudo -i -u openclaw
openclaw channels login

고급 구성¶

자세한 보안 아키텍처 및 문제 해결 내용은 다음을 참고하십시오:

Install overview

Other install methods

Maintenance

Hosting and deployment

Advanced

Ansible