Paperclip 설치 및 첫 실행 — Hostinger VPS 완전 초보 가이드

이번 단계에서 할 일

Hostinger VPS에 Paperclip을 설치하고, 브라우저에서 대시보드를 처음 여는 것까지 합니다. 코드를 한 번도 다뤄본 적 없는 분도 따라올 수 있도록 모든 명령어를 한 줄씩 설명합니다. 왜 이 명령어를 쓰는지도 같이 설명하니, 복붙만 하지 말고 이해하면서 진행해보세요.

시작 전 — 뭐가 필요한가요?

Hostinger VPS 사양 선택 가이드

Paperclip은 내장 PostgreSQL 데이터베이스를 서버 안에서 함께 실행합니다. 에이전트들이 일을 시작하면 AI API 호출도 계속 발생합니다. 이 때문에 RAM이 넉넉해야 안정적으로 운영됩니다.

운영 체제는 반드시 Ubuntu 22.04 또는 Ubuntu 24.04를 선택합니다. 이 가이드의 모든 명령어는 Ubuntu 기준으로 작성했습니다. CentOS나 AlmaLinux 등 다른 리눅스 배포판을 선택했다면 패키지 설치 명령어(apt 대신 yum 또는 dnf)가 달라집니다. 헷갈린다면 Ubuntu 22.04를 선택하는 것이 가장 안전합니다. 인터넷에서 찾을 수 있는 대부분의 튜토리얼이 Ubuntu 기준으로 작성되어 있기 때문입니다.

Step 0 — VPS에 SSH로 접속하기

SSH는 "Secure Shell"의 약자로, 인터넷을 통해 원격 서버에 안전하게 접속하는 방법입니다. 쉽게 말해, 내 노트북 터미널에서 VPS 터미널을 원격으로 조종하는 것입니다.

Windows에서 접속하기

Windows Terminal이나 PowerShell을 열고 아래를 입력합니다.

ssh root@여기에_VPS_IP_주소

예를 들어 VPS IP가 123.45.67.89라면 이렇게 씁니다.

ssh root@123.45.67.89

처음 접속할 때 나타나는 질문

처음 접속하면 이런 메시지가 나옵니다.

The authenticity of host '123.45.67.89' can't be established.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

yes를 입력하고 Enter를 누릅니다. 이 서버를 신뢰하겠다는 의미입니다. 앞으로 같은 서버에 접속할 때는 이 질문이 안 나옵니다.

비밀번호를 입력하라고 하면 Hostinger 패널에서 설정한 root 비밀번호를 입력합니다. 입력할 때 화면에 아무것도 표시되지 않는 것이 정상입니다. 그냥 입력하고 Enter를 누르면 됩니다.

접속에 성공하면 프롬프트가 이렇게 바뀝니다.

root@vps-xxxxx:~#

이제 내 노트북 터미널이 VPS 서버를 직접 조종하고 있습니다. 이후 모든 명령어는 이 화면에서 실행합니다.

Step 1 — 서버 패키지 업데이트

서버에 처음 접속하면 가장 먼저 패키지 목록을 업데이트합니다. 이 단계는 "새 집에 이사 왔을 때 전기, 수도, 가스 확인"과 같습니다. 최신 보안 패치도 함께 적용됩니다.

apt update && apt upgrade -y

이 명령어는 두 가지를 합쳐서 실행합니다.

• apt update — 설치 가능한 패키지 목록을 새로 받아옵니다
• apt upgrade -y — 오래된 패키지를 전부 최신 버전으로 업그레이드합니다. -y는 "다 yes로 자동 답변"이라는 뜻입니다

완료에 1~3분 걸릴 수 있습니다. 화면에 글자가 흘러내려가다가 프롬프트가 다시 나타나면 완료된 것입니다.

Step 2 — Node.js 20 설치

Paperclip은 Node.js 20 버전 이상이 필요합니다. Node.js는 브라우저 밖에서 JavaScript를 실행하는 런타임 환경입니다. Paperclip 서버 자체가 Node.js로 만들어져 있어서 반드시 필요합니다.

Ubuntu 기본 저장소에 있는 Node.js는 버전이 낮을 수 있기 때문에, NodeSource 공식 스크립트로 최신 버전을 설치합니다.

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs

설치가 끝나면 버전을 확인합니다.

node --version

아래처럼 v20 이상이 나오면 성공입니다.

v20.19.1

버전이 v18 이하로 나온다면 위 설치 명령어를 다시 실행하거나, setup_22.x로 바꿔서 시도해봅니다.

Step 3 — pnpm 설치

pnpm은 Node.js 패키지 관리자입니다. 많이 들어본 npm과 같은 역할인데, 더 빠르고 디스크를 효율적으로 씁니다. Paperclip 내부에서 pnpm을 사용하기 때문에 설치가 필요합니다.

npm install -g pnpm

설치 확인합니다.

pnpm --version

9.x 이상의 버전 숫자가 나오면 성공입니다.

Step 4 — PM2 설치

PM2는 Node.js 애플리케이션을 백그라운드에서 계속 실행해주는 프로세스 관리자입니다. PM2 없이 Paperclip을 실행하면, 터미널을 닫는 순간 서버가 꺼집니다. PM2를 사용하면 터미널을 닫아도 Paperclip이 계속 돌아갑니다.

npm install -g pm2

PM2는 서버 재부팅 시 자동 시작 설정도 지원합니다. VPS가 혹시라도 재시작되더라도 Paperclip이 자동으로 다시 켜집니다. 이 설정은 Step 8에서 합니다.

Step 5 — Paperclip 전용 계정 만들기 (보안)

보안 원칙상, root 계정으로 서비스를 직접 실행하는 것은 좋지 않습니다. root는 서버의 모든 권한을 가지기 때문에 보안 문제가 생기면 피해가 커집니다. paperclip이라는 전용 계정을 만들어서 Paperclip만 실행하도록 합니다.

adduser --disabled-password --gecos "" paperclip

이 명령어는 비밀번호 없이 paperclip 계정을 만듭니다. root에서만 이 계정으로 전환할 수 있어서 보안이 유지됩니다.

paperclip 계정으로 전환합니다.

su - paperclip

프롬프트가 이렇게 바뀌면 전환 성공입니다.

paperclip@vps-xxxxx:~$

이제부터 Paperclip 관련 명령어는 이 paperclip 계정에서 실행합니다.

Step 6 — Paperclip 설치 및 초기 설정 (핵심!)

드디어 핵심 단계입니다. 아래 명령어 하나로 Paperclip이 설치되고 초기 설정 마법사가 실행됩니다.

npx paperclipai onboard

처음 실행하면 npx가 자동으로 paperclipai 패키지를 다운로드합니다. 1~2분 정도 기다리면 마법사가 시작됩니다.

마법사에서 선택할 것들

마법사가 몇 가지를 물어봅니다. VPS용 설정을 아래에서 정확히 안내합니다.

설정 마법사 흐름 (VPS 기준 선택값)
══════════════════════════════════════════════════

[질문 1] 배포 모드를 선택하세요

  How would you like to deploy Paperclip?
  ○ local_trusted  ← 내 컴퓨터에서만 쓸 때
  ● authenticated  ← VPS, 외부 접속 필요할 때 ✅ 이걸 선택

[질문 2] 노출 범위를 선택하세요 (authenticated 선택 시)

  Exposure policy?
  ○ private  ← VPN이나 Tailscale 사용할 때
  ● public   ← 일반 IP로 접속할 때 ✅ 이걸 선택

[질문 3] 공개 URL을 입력하세요 (public 선택 시)

  Public URL for this deployment?
  → http://123.45.67.89:3100   (VPS IP로 변경)

══════════════════════════════════════════════════

설치가 완료되면 아래 메시지가 나옵니다.

✅ Paperclip is configured and ready to run
   Run: npx paperclipai run

이 화면이 나왔다면 설정이 완료된 것입니다. 아직 서버는 실행 중이 아닙니다. 다음 단계에서 PM2로 실행합니다.

Step 7 — Hostinger 방화벽에서 포트 열기

Paperclip은 3100번 포트를 사용합니다. 브라우저에서 http://IP:3100으로 접속하려면 이 포트가 열려있어야 합니다.

방화벽 설정이 필요한 곳이 두 군데입니다.

1) 서버 방화벽(ufw)에서 열기

먼저 root 계정으로 돌아갑니다.

exit

ufw(Ubuntu 기본 방화벽)에서 3100 포트를 허용합니다.

ufw allow 3100/tcp
ufw reload
ufw status

마지막 명령어 실행 후 아래처럼 나오면 성공입니다.

Status: active

To                         Action      From
--                         ------      ----
22/tcp                     ALLOW       Anywhere
3100/tcp                   ALLOW       Anywhere

2) Hostinger 패널 방화벽에서 열기

Hostinger VPS 관리 패널에도 별도의 방화벽이 있습니다. 패널에서 추가로 포트를 열어야 외부에서 접속됩니다.

Hostinger 패널 방화벽 설정 경로
────────────────────────────────────────────────
VPS 패널 접속
    → 왼쪽 메뉴에서 해당 VPS 클릭
    → Security 또는 Firewall 탭 선택
    → Inbound Rules(인바운드 규칙) 섹션
    → Add Rule(규칙 추가) 클릭
    → Port: 3100, Protocol: TCP, Source: Any
    → 저장
────────────────────────────────────────────────

서버 ufw와 Hostinger 패널 방화벽 둘 다 열어야 접속됩니다. 하나만 열면 접속이 안 됩니다.

Step 8 — PM2로 Paperclip 실행하기

paperclip 계정으로 다시 전환합니다.

su - paperclip

PM2로 Paperclip을 백그라운드에서 실행합니다. 이 명령어를 실행하면 터미널을 닫아도 Paperclip이 계속 실행됩니다.

pm2 start "npx paperclipai run" --name paperclip

상태를 확인합니다.

pm2 status

아래처럼 online 상태가 나오면 정상 실행 중입니다.

┌────┬────────────┬─────────────┬─────────┬──────────┐
│ id │ name       │ namespace   │ version │ status   │
├────┼────────────┼─────────────┼─────────┼──────────┤
│ 0  │ paperclip  │ default     │ N/A     │ online   │
└────┴────────────┴─────────────┴─────────┴──────────┘

실시간 로그를 보고 싶다면 이 명령어를 씁니다.

pm2 logs paperclip

에러 없이 로그가 흘러내려가면 정상입니다. Ctrl+C로 로그 보기를 종료합니다.

서버 재부팅 시 자동 시작 설정

VPS는 가끔 예기치 않게 재시작될 수 있습니다. 재시작 후에도 Paperclip이 자동으로 켜지도록 설정합니다.

pm2 save

root 계정으로 돌아가서 시스템 시작 프로그램에 등록합니다.

exit
pm2 startup

pm2 startup 실행 후, 아래와 비슷한 명령어가 출력됩니다.

[PM2] To setup the Startup Script, copy/paste the following command:
sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u root --hp /root

이 sudo env PATH=...로 시작하는 명령어를 통째로 복사해서 실행합니다. 그러면 서버가 재부팅될 때마다 PM2가 자동으로 시작되고, 저장해둔 Paperclip 프로세스도 자동으로 켜집니다.

Step 9 — 브라우저에서 대시보드 접속

이제 브라우저를 열고 주소창에 아래를 입력합니다.

http://VPS_IP_주소:3100

예시: http://123.45.67.89:3100

접속에 성공하면 Paperclip 회원가입 화면이 나타납니다.

첫 계정 만들기

이메일 주소와 비밀번호를 입력해서 계정을 만듭니다. 이 계정이 Paperclip의 이사회 의장(Board Admin) 계정입니다. 에이전트 채용, 예산 승인, 전략 검토 등 모든 최상위 결정권이 이 계정에 있습니다.

회원가입 후, 터미널로 돌아가서 아래 명령어를 실행합니다.

su - paperclip
npx paperclipai auth bootstrap-ceo

초대 링크(URL)가 출력됩니다. 이 링크를 브라우저 주소창에 붙여넣으면 방금 만든 계정이 이사회 의장 권한을 얻습니다. 이 단계는 authenticated 모드에서 최초 1회만 필요합니다.

Step 10 — 대시보드 첫 화면

로그인에 성공하면 Paperclip 대시보드가 나타납니다. 지금은 모든 것이 비어있는 것이 정상입니다.

대시보드 구성 (첫 접속 화면)
══════════════════════════════════════════════════

왼쪽 사이드바
├── Companies      → 운영 중인 회사 목록
│                    (처음엔 비어있음, 여기서 첫 회사 생성)
├── Agents         → 에이전트 목록 및 상태
├── Tasks          → 티켓 / 태스크 현황
├── Goals          → 목표 계층 구조
├── Budget         → 에이전트별 예산 사용량
├── Audit Log      → 모든 활동 감사 기록
└── Settings       → 서버 / 계정 설정

메인 영역
└── "Create your first company" 버튼이 표시됨

══════════════════════════════════════════════════

"Create your first company" 버튼을 눌러서 회사 이름과 미션을 입력하면, AI 에이전트 팀의 첫 번째 회사가 만들어집니다. 다음 단계(Step 3)에서 이 부분을 자세히 다룹니다.

API 키는 어디서, 어떻게 설정하나요?

Paperclip을 설치하는 단계에서는 API 키를 입력하지 않아도 됩니다. 에이전트를 실제로 등록할 때 각 에이전트마다 개별로 입력합니다. 이 구조 덕분에 에이전트마다 다른 AI 모델을 쓸 수 있습니다. 예산이 많이 드는 작업에는 Claude Opus를, 빠른 처리가 필요한 작업에는 GPT-4o를 쓰는 식으로 조합이 가능합니다.

지금 당장 필요한 것은 API 키를 준비해두는 것입니다.

API 키를 환경변수로 미리 서버에 등록해두면 에이전트 등록 시 자동으로 불러옵니다. paperclip 계정의 홈 디렉터리에 .env 파일을 만들어두는 방법입니다.

# paperclip 계정에서 실행
cat >> ~/.profile << 'EOF'
export ANTHROPIC_API_KEY="sk-ant-여기에_실제_키_입력"
export OPENAI_API_KEY="sk-여기에_실제_키_입력"
EOF
source ~/.profile

이렇게 해두면 Paperclip 서버가 시작될 때 자동으로 키를 불러옵니다. 대시보드 UI에서 입력하는 방법도 있으니, 이 단계는 선택 사항입니다.

도메인이 있다면 — Nginx 리버스 프록시 설정

IP 주소 대신 도메인 이름으로 접속하거나, https://를 쓰고 싶다면 Nginx 리버스 프록시를 설정합니다. 지금 당장 필요하지 않다면 이 섹션은 나중에 해도 됩니다.

Nginx를 설치합니다.

# root 계정에서 실행
apt install -y nginx

Nginx 설정 파일을 만듭니다.

cat > /etc/nginx/sites-available/paperclip << 'EOF'
server {
    listen 80;
    server_name 여기에_도메인_또는_IP;

    location / {
        proxy_pass http://127.0.0.1:3100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
    }
}
EOF

설정을 활성화합니다.

ln -s /etc/nginx/sites-available/paperclip /etc/nginx/sites-enabled/
nginx -t          # 설정 문법 확인
systemctl restart nginx
ufw allow 80/tcp  # 80번 포트 열기

이제 http://도메인 또는 http://IP로 포트 번호 없이 접속됩니다. Paperclip 설정에서 Public URL도 도메인으로 업데이트해야 합니다.

npx paperclipai configure --section server
# Public URL을 http://도메인 으로 변경

유용한 관리 명령어 모음

설치 후 자주 쓰게 될 명령어들입니다.

# Paperclip 상태 확인
pm2 status

# 실시간 로그 보기
pm2 logs paperclip

# Paperclip 재시작 (설정 변경 후)
pm2 restart paperclip

# Paperclip 중지
pm2 stop paperclip

# Paperclip 시작
pm2 start paperclip

# 설정 진단 및 자동 수리
npx paperclipai doctor

# 배포 모드 변경
npx paperclipai configure --section auth

# 허용 호스트네임 추가
npx paperclipai add-hostname 도메인이름.com

문제 해결 — 안 될 때 체크리스트

접속이 안 되거나 에러가 나면 아래 순서대로 확인합니다.

접속 안 될 때 체크리스트
────────────────────────────────────────────────
□ 브라우저 주소 확인
  - http:// 로 시작하는지 (https:// 아님!)
  - 포트 :3100 이 붙어있는지
  - IP 주소가 정확한지

□ Paperclip 실행 상태 확인
  → pm2 status
  → paperclip이 online 이면 정상
  → offline 이면: pm2 restart paperclip

□ 서버 방화벽 확인
  → ufw status
  → 3100/tcp 가 ALLOW 로 표시되는지

□ Hostinger 패널 방화벽 확인
  → 패널에서 Firewall → 3100 포트 열려있는지

□ 로그에서 에러 확인
  → pm2 logs paperclip
  → 에러 메시지 복사해서 검색
────────────────────────────────────────────────

에러별 해결 방법

"Unable to bind 0.0.0.0" 에러

원인: local_trusted 모드는 외부 IP 바인딩 불가

npx paperclipai configure --section auth
# → authenticated → public 선택 후 재시작
pm2 restart paperclip

npx paperclipai onboard 실패 (GitHub Issue #704)

root 계정으로 실행했을 때 발생합니다. paperclip 전용 계정에서 실행합니다.

su - paperclip
npx paperclipai onboard

포트 3100 접속 불가 (timeout)

서버 방화벽(ufw)과 Hostinger 패널 방화벽 둘 다 확인합니다.

# 서버 방화벽 재설정
ufw allow 3100/tcp
ufw reload
ufw status

pnpm 버전이 낮다는 경고

npm install -g pnpm@latest

전체 설정 진단이 필요할 때

Paperclip에는 설정 상태를 자동으로 검사하고 수리하는 명령어가 있습니다. 뭔가 이상하면 이 명령어부터 실행해보세요.

npx paperclipai doctor

문제가 있으면 원인과 해결 방법을 직접 알려줍니다.

전체 설치 명령어 한눈에 보기

처음부터 끝까지 순서대로 실행해야 할 명령어 전체 목록입니다. 복사해서 메모장에 저장해두면 편합니다.

# ====== root 계정에서 실행 ======

# 서버 업데이트
apt update && apt upgrade -y

# Node.js 20 설치
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs

# 전역 도구 설치
npm install -g pnpm pm2

# paperclip 전용 계정 생성
adduser --disabled-password --gecos "" paperclip

# 방화벽 열기
ufw allow 3100/tcp && ufw reload

# ====== paperclip 계정으로 전환 ======
su - paperclip

# Paperclip 초기 설정 마법사 실행
# → authenticated → public → http://VPS_IP:3100
npx paperclipai onboard

# PM2로 실행
pm2 start "npx paperclipai run" --name paperclip
pm2 save

# CEO 계정 부트스트랩 (회원가입 후 실행)
npx paperclipai auth bootstrap-ceo

# ====== root 계정으로 돌아와서 ======
exit

# 재부팅 자동 시작 설정
pm2 startup
# → 출력된 sudo 명령어를 복사해서 실행

# ====== 브라우저에서 ======
# http://VPS_IP:3100 접속 → 회원가입 → 대시보드 확인

Hostinger 원클릭 설치 옵션

Hostinger VPS는 Docker 앱으로 Paperclip 원클릭 설치도 지원합니다. 이 방식은 서버 설정에 익숙하지 않은 분들에게 훌륭한 출발점입니다.

Hostinger 패널 → VPS Apps → Docker Apps 메뉴에 Paperclip이 등록되어 있습니다. 클릭 한 번으로 Docker 컨테이너가 자동 구성됩니다. Node.js, pnpm, PM2를 직접 설치할 필요 없이 모두 자동 처리됩니다.

처음 시작하는 분께는 원클릭 방식이 가장 쉽습니다. 설정을 더 세밀하게 제어하거나 업데이트를 직접 관리하고 싶다면, 이 가이드처럼 npx 방식으로 직접 설치하는 것을 추천합니다. 처음에는 원클릭으로 맛보고, 익숙해지면 npx 방식으로 옮겨가는 것도 좋은 방법입니다.

npx vs Docker — 어떤 방식이 나한테 맞을까?

이 가이드에서는 npx paperclipai onboard 방식으로 설치했습니다. Paperclip에는 설치 방법이 네 가지 있습니다. 나중에 다른 방식으로 바꿀 때를 대비해서 각각의 특징을 알아둡니다.

마치며

브라우저에 Paperclip 대시보드가 나타나는 순간, 여러분만의 "AI 회사 서버"가 인터넷에 살아있는 것입니다.

이번 단계에서 완료한 것
────────────────────────────────
✅ Hostinger VPS에 Node.js 20 설치 완료
✅ Paperclip 초기 설정 마법사 완료
✅ 외부 접속 가능한 authenticated/public 모드 설정
✅ PM2로 서버 상시 실행 + 재부팅 자동 시작
✅ Hostinger 방화벽 포트 3100 개방
✅ 브라우저에서 대시보드 접속 + 이사회 의장 계정 생성
────────────────────────────────

다음 단계(Step 3)에서는 이 대시보드 안에서 첫 번째 에이전트를 등록합니다. 이미 만들어둔 OpenClaw 에이전트를 Paperclip 조직에 편입시키거나, 처음부터 새 에이전트를 설정하는 방법을 단계별로 살펴봅니다.