Personal AI Company 셋업 ②: Paperclip + Claude Code Max 셋업

들어가며

Personal AI Company 시리즈 1편에서 전체 아키텍처와 개념을 살펴봤다. 2편에서는 Paperclip을 실제로 설치하고 Claude Code Max와 연결하는 구체적인 절차를 다룬다. 이 글을 따라하면 로컬 또는 서버 환경에서 Paperclip API 서버가 실행되고, Claude Code가 에이전트로 동작하는 상태가 된다.

사전 요구사항

필수 항목 확인

아래 항목이 모두 준비되어 있어야 한다.

항목	버전 / 조건
Node.js	20 이상
pnpm	9.15 이상
Claude 구독	Max 플랜 (Claude Code 사용 필수)
운영 체제	macOS, Linux, Windows (WSL2)

Claude Max 구독이 필요한 이유

Paperclip은 Claude Code를 에이전트 런타임으로 사용한다. Claude Code는 Claude Max 플랜 이상에서 높은 사용량 한도로 에이전트 루프 실행이 가능하다. 구독 없이 시작하면 에이전트 실행이 즉시 제한되므로 시작 전에 반드시 확인한다.

Claude Max 구독 가격은 Anthropic 공식 사이트에서 확인한다 (공식 문서 없음, 추가 확인 필요).

Node.js와 pnpm 설치 확인

node --version   # 20.x 이상인지 확인
pnpm --version   # 9.15 이상인지 확인

# pnpm이 설치되어 있지 않다면
npm install -g pnpm

Paperclip 설치

npx 원커맨드 설치 (권장)

가장 빠른 설치 방법이다. 아래 한 줄로 Paperclip 설치와 초기 설정이 완료된다. 내장 PostgreSQL이 자동 생성되어 별도 DB 설정이 불필요하다.

npx paperclipai onboard --yes

이미 설정이 있는 경우 onboard를 재실행해도 기존 설정을 유지한다. 설정 변경이 필요한 경우 paperclipai configure 명령을 사용한다.

bind 모드 선택

--bind 옵션으로 서버의 접근 범위를 설정한다. 처음부터 자신의 용도에 맞는 모드를 선택하는 것이 중요하다.

모드	옵션	접근 범위	적합한 상황
로컬 (기본)	옵션 생략	localhost만	개발·테스트
LAN	--bind lan	같은 Wi-Fi 내 기기	팀 내부 공유
Tailscale	--bind tailnet	Tailscale 망 전체	원격·스마트폰 접근

# LAN 접근 허용 (같은 네트워크의 다른 기기에서 접근)
npx paperclipai onboard --yes --bind lan

# Tailscale 망 내 접근 (원격 접근, 스마트폰 관리용)
npx paperclipai onboard --yes --bind tailnet

수동 설치 (개발자용)

소스 코드를 직접 수정하거나 커스텀 환경을 구성할 때 사용한다.

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev

서버가 시작되면 API 서버는 http://localhost:3100에서 동작한다.

환경변수 설정

수동 설치의 경우 또는 기존 설정을 수정할 때 .env 파일을 직접 편집한다.

cp .env.example .env

주요 환경변수는 다음과 같다.

# PostgreSQL 연결 문자열
DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip

# API 서버 포트 (기본: 3100)
PORT=3100

# UI 서빙 여부 (별도 프론트엔드 서버 사용 시 false)
SERVE_UI=false

# 인증 시크릿 키 ⚠️ 프로덕션에서 반드시 변경
BETTER_AUTH_SECRET=paperclip-dev-secret

BETTER_AUTH_SECRET 설정

BETTER_AUTH_SECRET은 세션 인증에 사용하는 핵심 보안 키다. 기본값 paperclip-dev-secret은 개발 전용이며, 외부 접근이 가능한 환경에서는 반드시 강력한 난수로 교체해야 한다.

# macOS / Linux
openssl rand -base64 32

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

생성된 값을 .env 파일의 BETTER_AUTH_SECRET에 입력한다. 이 값이 유출되면 세션 위조가 가능하므로 Git에 커밋하지 않도록 .gitignore에 .env가 포함되어 있는지 반드시 확인한다. 값을 변경하면 모든 활성 세션이 무효화된다.

Claude CLI 설치 및 인증

Claude CLI 설치

npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

OAuth 인증 흐름

# Claude CLI 로그인 (브라우저 OAuth 팝업)
claude auth login

위 명령을 실행하면 브라우저가 열리고 Anthropic 계정 로그인 페이지로 이동한다. Claude Max 플랜이 연결된 계정으로 로그인한다. 인증이 완료되면 credentials가 ~/.claude/ 디렉토리에 저장된다.

# 인증 상태 확인
claude auth status

컨테이너 환경에서 credentials 전달

Docker 등 컨테이너 환경에서는 호스트의 ~/.claude/ 디렉토리를 컨테이너 내부에 전달해야 한다.

아래 내용은 공식 README에 Docker 가이드가 없으므로, 실제 운영 환경에서 관찰된 패턴 기반이다 (공식 문서 없음, 추가 확인 필요).

방법 1: Volume 마운트 (권장)

# docker-compose.yml
services:
  paperclip:
    volumes:
      - ~/.claude:/root/.claude:ro  # 읽기 전용 마운트

방법 2: 직접 복사

# 호스트에서 컨테이너로 복사
docker cp ~/.claude/. <container_id>:/root/.claude/

# 또는 컨테이너 내부에서 직접 인증
docker exec -it <container_id> claude auth login

트러블슈팅

T1. Node.js 버전 오류로 설치 실패

항목	내용
증상	Error: The engine "node" is incompatible with this module 오류
원인	Node.js 버전이 20 미만
해결책	nvm install 20 && nvm use 20 실행 또는 공식 Node.js 사이트에서 최신 LTS를 설치한다

T2. BETTER_AUTH_SECRET 미설정으로 인증 실패

항목	내용
증상	로그인 시도 시 세션이 즉시 만료되거나 "Invalid secret" 오류가 발생한다
원인	.env에 BETTER_AUTH_SECRET이 없거나 기본값(paperclip-dev-secret) 상태로 프로덕션 모드 실행
해결책	openssl rand -base64 32로 새 시크릿 생성 후 .env에 입력하고 서버를 재시작한다

T3. Claude 인증 후에도 에이전트가 "인증 오류" 반환

항목	내용
증상	claude auth status는 정상인데, Paperclip 에이전트 실행 시 "Authentication required" 오류
원인	컨테이너·격리 환경에서 ~/.claude credentials를 찾지 못함
해결책	호스트의 ~/.claude를 컨테이너 내부로 마운트하거나, 컨테이너 내부에서 직접 claude auth login을 실행한다

T4. 포트 3100 충돌로 서버 시작 실패

항목	내용
증상	Error: listen EADDRINUSE: address already in use :::3100
원인	다른 프로세스가 이미 3100 포트를 사용 중
해결책	.env에서 PORT=3101(또는 다른 빈 포트)로 변경 후 재시작. lsof -i :3100으로 충돌 프로세스를 먼저 확인한다

T5. Tailscale bind 모드에서 외부 접근 불가

항목	내용
증상	--bind tailnet으로 시작했는데 외부 기기에서 대시보드에 접근할 수 없다
원인	Tailscale이 설치되어 있지 않거나 호스트가 Tailscale 망에 미연결
해결책	Tailscale 설치 및 tailscale up으로 로그인 후 Paperclip을 재시작한다. 접근 시 Tailscale IP를 사용한다

다음 편 예고

3편에서는 Paperclip 위에서 동작하는 첫 에이전트를 직접 정의하고, CEO-Researcher-Creator 역할 분리 구조를 실제로 구성하는 방법을 다룬다.