Ansible로 OpenClaw 설치하기

새로운 프로젝트를 서버에 올릴 때마다 보안 설정이나 의존성 관리 때문에 머리 아픈 적 많으시죠? 방화벽을 하나하나 설정하고, VPN을 연결하고, 런타임 환경을 맞추다 보면 정작 중요한 개발보다 설정에 더 많은 시간을 쓰게 되곤 해요.

OpenClaw는 이런 번거로움을 줄이기 위해 **openclaw-ansible**이라는 자동화 도구를 제공해요. 보안을 최우선으로 고려한 아키텍처를 클릭 몇 번으로 구축할 수 있도록 도와줍니다.

필요한 것

설치를 시작하기 전에 다음 조건이 충족되었는지 확인해 주세요.

• OS: Debian 11+ 또는 Ubuntu 20.04+
• 권한: Root 또는 sudo 권한
• 네트워크: 패키지 설치를 위한 인터넷 연결
• Ansible: 2.14+ (퀵 스타트 스크립트가 자동으로 설치해 줘요)

빠른 시작

단 한 줄의 명령어로 설치를 끝낼 수 있어요.

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: 격리된 샌드박스 컨테이너를 사용하며, 로컬호스트 바인딩만 허용해요.
• 4단계 방어 체계: 계층화된 보안 아키텍처를 적용해요.
• 한 번의 명령으로 설정: 몇 분 안에 전체 배포를 완료해요.
• Systemd 통합: 부팅 시 자동 시작 및 보안 강화 설정을 포함해요.

설치되는 항목들

Ansible 플레이북이 다음 항목들을 자동으로 설치하고 설정해 줘요.

1. Tailscale: 안전한 원격 접속을 위한 메시 VPN
2. UFW 방화벽: SSH 및 Tailscale 포트만 허용
3. Docker CE + Compose V2: 에이전트 샌드박스용
4. Node.js 22.x + pnpm: 런타임 의존성
5. OpenClaw: 호스트 기반 설치 (컨테이너 방식 아님)
6. Systemd 서비스: 보안 강화 설정이 적용된 자동 시작 서비스

참고로 Gateway는 Docker가 아닌 호스트에서 직접 실행돼요. 하지만 에이전트 샌드박스는 격리를 위해 Docker를 사용합니다. 자세한 내용은 Sandboxing 문서를 확인해 보세요.

설치 후 작업

설치가 끝나면 openclaw 사용자로 전환해서 설정을 마무리해야 해요.

sudo -i -u openclaw

이후 나타나는 스크립트가 다음 과정을 안내해 줄 거예요.

1. 온보딩 마법사: OpenClaw 설정 구성
2. 프로바이더 로그인: WhatsApp, Telegram, Discord, Signal 연결
3. Gateway 테스트: 설치 상태 확인
4. Tailscale 설정: VPN 메시 연결

유용한 명령어

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

# 실시간 로그 확인
sudo journalctl -u openclaw -f

# Gateway 재시작
sudo systemctl restart openclaw

# 프로바이더 로그인 (openclaw 사용자로 실행)
sudo -i -u openclaw
openclaw channels login

Security Architecture

4단계 방어 체계

1. 방화벽 (UFW): SSH(22)와 Tailscale(41641/udp) 포트만 공용으로 노출해요.
2. VPN (Tailscale): VPN 메시를 통해서만 Gateway에 접근할 수 있어요.
3. Docker 격리: DOCKER-USER iptables 체인을 사용해 외부 포트 노출을 차단해요.
4. Systemd 보안 강화: NoNewPrivileges, PrivateTmp, 비특권 사용자 실행을 적용해요.

보안 검증

서버의 외부 공격 표면을 직접 테스트해 볼 수 있어요.

nmap -p- YOUR_SERVER_IP

결과에 22번 포트(SSH)만 열려 있다고 나와야 정상이에요. Gateway와 Docker를 포함한 다른 모든 서비스는 외부에서 접근할 수 없게 잠겨 있습니다.

Docker 활용 범위

Docker는 Gateway 실행용이 아니라 에이전트 샌드박스(격리된 도구 실행 환경)를 위해 설치돼요. Gateway는 로컬호스트에만 바인딩되며 Tailscale VPN을 통해서만 접속 가능합니다.

샌드박스 설정은 Multi-Agent Sandbox & Tools 문서를 참고해 주세요.

Manual Installation

자동화 대신 수동 제어를 선호하신다면 다음 단계를 따라주세요.

# 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. 플레이북 실행
./run-playbook.sh

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

OpenClaw 업데이트

Ansible로 설치한 OpenClaw는 수동 업데이트가 가능하도록 설정돼요. 일반적인 업데이트 흐름은 Updating 문서를 확인하세요.

설정 변경 등을 위해 Ansible 플레이북을 다시 실행하려면 다음 명령어를 사용하세요.

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 샌드박스 문제

# Docker 실행 여부 확인
sudo systemctl status docker

# 샌드박스 이미지 확인
sudo docker images | grep openclaw-sandbox

# 이미지가 없다면 직접 빌드
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh

프로바이더 로그인 실패

반드시 openclaw 사용자로 실행하고 있는지 확인해 주세요.

sudo -i -u openclaw
openclaw channels login

설치 과정에서 궁금한 점이 생기면 언제든 AI Setup Assistant에게 물어봐 주세요!

다음 단계

• openclaw-ansible — 전체 배포 가이드
• Docker — 컨테이너 기반 Gateway 설정
• Sandboxing — 에이전트 샌드박스 설정
• Multi-Agent Sandbox & Tools — 에이전트별 격리 환경