Paperclip 인증 모드 설정 가이드 - 외부 접속 가능한 AI 에이전트 서버 구축하기

Paperclip을 로컬에서만 쓰다가, 팀원이나 외부 네트워크에서도 접속할 수 있게 만들고 싶다면 인증 모드(authenticated mode)로 전환해야 합니다. 기본 설치는 local_trusted 모드로 127.0.0.1에만 바인딩되어 외부 접속이 차단됩니다. 이 가이드에서는 인증 모드 설정, CEO 초대 링크 생성, 허용 호스트네임 관리, 그리고 Tailscale을 활용한 프라이빗 네트워크 접속까지 단계별로 안내합니다.

배포 모드 이해하기

Paperclip은 세 가지 배포 모드를 지원합니다. 외부 접속을 위해서는 반드시 authenticated 모드가 필요합니다.

방법 1: 새로 설치하면서 인증 모드 선택

아직 Paperclip을 설치하지 않았거나 초기화할 수 있다면 가장 깔끔한 방법입니다.

# 기존 설정 초기화 (필요 시)
rm -rf ~/.paperclip

# 온보딩 실행
npx paperclipai onboard

대화형 마법사에서 다음을 선택합니다:

1. Advanced setup 선택
2. Deployment mode: Authenticated 선택
3. Exposure profile: Private network 선택
4. Bind address: 0.0.0.0 입력

온보딩이 완료되면 서버가 0.0.0.0:3100에서 시작되며, 같은 네트워크의 다른 기기에서 접속할 수 있습니다.

방법 2: 기존 설치를 인증 모드로 전환

이미 local_trusted로 설치했다면, 설정 파일을 수정하여 전환합니다.

Step 1: config.json 수정

# 설정 파일 위치 확인
ls ~/.paperclip/instances/default/config.json

# 편집
nano ~/.paperclip/instances/default/config.json

다음 값을 변경합니다:

{
  "deployment": {
    "mode": "authenticated",
    "exposure": "private"
  },
  "server": {
    "host": "0.0.0.0",
    "port": 3100
  }
}

Step 2: CEO 초대 링크 생성

인증 모드에서는 첫 번째 관리자(CEO)를 초대해야 합니다:

paperclipai auth bootstrap-ceo

이 명령은 일회용 초대 링크를 생성합니다. 기본 72시간 유효하며, 최대 720시간(30일)까지 설정 가능합니다.

Step 3: 외부 접속 URL로 초대 링크 생성

외부에서 접속할 URL이 있다면 --base-url을 지정합니다:

# Tailscale 사용 시
paperclipai auth bootstrap-ceo --base-url https://my-server.tail1234.ts.net:3100

# 고정 IP 사용 시
paperclipai auth bootstrap-ceo --base-url http://192.168.1.100:3100

# 도메인 사용 시
paperclipai auth bootstrap-ceo --base-url https://paperclip.example.com

생성된 링크를 브라우저에서 열면 CEO 계정 등록 화면이 나타납니다.

방법 3: Tailscale로 프라이빗 네트워크 접속

가장 안전하면서 간편한 외부 접속 방법입니다. Tailscale은 VPN 없이 기기 간 프라이빗 네트워크를 구성합니다.

Step 1: Tailscale 인증 모드로 실행

# 소스에서 빌드한 경우
pnpm dev --tailscale-auth

# 또는 npx로 설치한 경우
paperclipai run --tailscale-auth

이 플래그가 자동으로 인증 모드 활성화 + 0.0.0.0 바인딩을 처리합니다.

Step 2: Tailscale 호스트네임 허용

# 접속할 기기의 Tailscale 호스트네임 추가
paperclipai allowed-hostname my-macbook-pro
paperclipai allowed-hostname team-member-laptop

Step 3: CEO 초대

paperclipai auth bootstrap-ceo --base-url https://my-server.tail1234.ts.net:3100

이후 Tailscale 네트워크에 연결된 모든 허용 기기에서 대시보드에 접속할 수 있습니다.

허용 호스트네임 관리

인증 모드에서는 허용 호스트네임 목록(allowlist)으로 접속을 제한합니다:

# 호스트네임 추가
paperclipai allowed-hostname my-macbook-pro
paperclipai allowed-hostname office-desktop
paperclipai allowed-hostname team-server

# Tailscale 머신 이름도 사용 가능
paperclipai allowed-hostname john-mbp.tail1234.ts.net

보안 파일 구조

인증 모드에서 Paperclip이 관리하는 보안 파일들입니다:

~/.paperclip/instances/default/
  config.json      # 메인 설정 (배포 모드, 바인딩 주소)
  .env.local       # JWT 시크릿 (세션 토큰 서명용)
  secrets/
    master.key     # 민감 데이터 암호화 키
  context.json     # CLI 컨텍스트 프로파일

환경변수로 설정하기

설정 파일 대신 환경변수로도 배포 모드를 제어할 수 있습니다. Docker나 클라우드 배포 시 유용합니다:

# 배포 모드 설정
export PAPERCLIP_DEPLOYMENT_MODE="authenticated"
export PAPERCLIP_DEPLOYMENT_EXPOSURE="private"

# 바인딩 설정
export HOST="0.0.0.0"
export PORT="3100"

# AI 에이전트 API 키
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# 서버 실행
paperclipai run

트러블슈팅

핵심 정리

• 외부 접속을 위해서는 authenticated 모드 + 0.0.0.0 바인딩이 필수
• 새 설치: 온보딩에서 Advanced setup → Authenticated → Private network → 0.0.0.0 선택
• 기존 설치: config.json에서 mode와 host 수정
• paperclipai auth bootstrap-ceo --base-url [URL]로 첫 관리자 초대
• paperclipai allowed-hostname [이름]으로 접속 허용 기기 관리
• Tailscale: --tailscale-auth 플래그로 가장 간편하게 프라이빗 접속 구성
• 보안 파일(.env.local, master.key)은 절대 외부 노출 금지

참조 링크

• Paperclip CLI Overview - auth bootstrap-ceoCLI 인증 명령어 공식 문서
• Paperclip Local Deployment Guide로컬 배포 모드, Tailscale 연동, 바인딩 설정
• Issue #65: Unable to bind 0.0.0.0 during onboarding0.0.0.0 바인딩 문제 해결 방법 (커뮤니티 솔루션)
• paperclipai/paperclip - GitHub공식 저장소 (소스 코드, 이슈 트래커)