Paperclip 쓰는 법
paperclipai/Paperclip으로 AI 에이전트 팀을 회사처럼 돌리는 오픈소스 컨트롤 플레인 설치·온보딩 가이드다. Node 24.11+에서 매니지드 install·npx onboard·test-drive·pnpm dev까지 공식 문서 경로만 정리한다.
Paperclip(paperclipai/paperclip)은 AI 에이전트 팀을 회사처럼 운영하기 위한 오픈소스 컨트롤 플레인(제어면)·오케스트레이션 앱이다. 공식 한 줄로 말하면, “OpenClaw가 직원이라면 Paperclip은 회사”다. MIT 라이선스, npm 패키지 paperclipai 최신 2026.916.1(릴리스 태그 v2026.916.1, 2026-09-21), GitHub 스타는 작성 시점 API 기준 약 8.5만. 홈페이지 paperclip.ing · 문서 docs.paperclip.ing.
이 글은 “Paperclip 쓰는 법”만 따라간다. 매니지드 설치 → 온보딩 → test-drive → 소스 개발(pnpm dev) → 첫 회사·CEO 에이전트까지, README·INSTALLING·퀵스타트 문서만 근거로 적는다.
핵심 요약 (TL;DR)
- 무엇인가: Node.js 서버 + React UI로, 여러 AI 에이전트에 목표·예산·조직도를 주고 대시보드에서 일·비용을 추적하는 셀프호스트형 오케스트레이션.
- 요구사항(공식): Node.js 24.11.0 이상. 소스/개발은 pnpm 9.15+(packageManager
[email protected]). 로컬 기본은 임베디드 PostgreSQL — 외부 DB 없이http://localhost:3100. - 버전(작성 시점):
[email protected]. 라이선스 MIT. - 추천 경로(macOS/Linux/WSL2):
install.sh체크섬 확인 후 실행 → 매니지드 CLI(~/.paperclip/cli) → 온보딩. 빠르게 쓰려면npx … paperclipai onboard --yes또는test-drive. - 어댑터(공식): OpenClaw, Claude Code, Codex, Cursor, Bash, HTTP. 네 기둥: Agentic Task Manager, Org Chart for Agents, Agent Employee Training, Agentic OS.
할 수 있는 일
먼저 용어만 짧게 풀어 둔다.
- 에이전트: Claude Code·Codex·Cursor·OpenClaw처럼 목표를 받고 도구를 쓰며 일을 진행하는 AI 실행 단위. Paperclip은 에이전트를 “만드는” 프레임워크가 아니라, 이미 있는 에이전트를 회사 조직으로 묶는다.
- 하트비트(heartbeat): 에이전트가 일정·이벤트에 맞춰 깨어나 할 일을 확인하고 행동하는 주기적 깨우기. README 표현대로 “하트비트를 받을 수 있으면 고용”이다.
- 어댑터(adapter): 특정 런타임(Claude Code, Codex, Cursor, Bash, HTTP 등)을 Paperclip에 연결하는 플러그 지점.
- 하네스(harness): test-drive 등에서 어떤 실행 환경·에이전트 스택을 쓸지 고르는 옵션(예:
--harness codex). TWMS 표기는 하네스. - 거버넌스: 채용 승인, 전략 오버라이드, 에이전트 일시정지·종료처럼 사람이 통제권을 유지하는 승인·정책 층.
- 예산(budget): 에이전트·회사 단위로 토큰/비용을 한도 걸고, 한도에 닿으면 실행을 멈추는 비용 가드.
- 컨트롤 플레인: 개별 에이전트 채팅창이 아니라, 조직도·태스크·비용·감사를 한곳에서 보는 운영 대시보드.
공식 README·docs 기준으로 바로 할 수 있는 일은 대략 이렇다.
- 목표 정의 → 팀 고용 → 승인 후 실행: “무엇을 만들지”를 회사 목표로 두고 CEO 등 역할을 고용한 뒤, 전략을 리뷰하고 예산을 건 다음 대시보드에서 모니터한다.
- 여러 에이전트를 한 조직도로: OpenClaw·Claude Code·Codex·Cursor·Bash·HTTP를 같은 회사 안에서 역할·보고 라인·권한과 함께 돌린다.
- 티켓·감사·세션 유지: 대화·결정·툴 호출이 티켓에 묶이고, 재부팅 후에도 컨텍스트가 이어지도록 설계되어 있다(README “Problems Paperclip solves”).
- 비용 한도: 에이전트별 월간 예산. 한도 도달 시 중단.
- 멀티 조직: 한 배포로 여러 회사를 돌리되 데이터는 격리.
- 루틴·스케줄: 반복 업무를 하트비트·크론·웹훅으로 깨운다.
- 모바일·원격 접근 전제: 기본 퀵스타트는 로컬 루프백 신뢰 모드. LAN/Tailscale 바인드로 인증 모드를 바꿀 수 있다.
필요한 것
| 항목 | 공식 근거 | 메모 |
|---|---|---|
| Node.js | README Requirements / INSTALLING / engines | ≥ 24.11.0 (node --version). 서비스는 셸이 아닌 실제 실행 바이너리 PATH를 본다 |
| pnpm (소스/개발) | README / packageManager | 9.15+ ([email protected]) |
| 패키지 | npm registry / 릴리스 | paperclipai 2026.916.1 (작성 시점 latest) |
| 로컬 DB | README Quickstart | 임베디드 PostgreSQL 자동 생성 — 로컬에 외부 DB 불필요 |
| 기본 포트 | README | 개발 서버 http://localhost:3100 |
| API 키(실사용) | docs quickstart | Anthropic(Claude 로컬 어댑터) 또는 OpenAI(Codex) 등. 에이전트 호출은 과금됨 — 문서가 $5–20 시험 / 월 $20–100대 활성 회사 예시를 제시. 하트비트 켜기 전 예산 설정 권장 |
| 라이선스 | README / LICENSE | MIT |
| 스타(참고) | GitHub API (작성 시점) | 약 84,880 |
링크: GitHub · Homepage · Quickstart · INSTALLING.md · npm.
설치 / 단계
1) 추천: 매니지드 설치 (macOS / Linux / WSL2)
curl -fsSLO https://paperclip.ing/install.sh
curl -fsSLO https://paperclip.ing/install.sh.sha256
# 체크섬 확인 후:
# sha256sum -c install.sh.sha256 # 또는 shasum -a 256 -c …
bash install.sh
설치 스크립트는 Node 24.11+를 확보하고, 매니지드 CLI를 ~/.paperclip/cli에 둔 뒤 대화형 온보딩을 시작한다. 체크섬은 전송·게시 실수 감지용이며, 스크립트와 같은 origin에서 제공된다. 독립 출처가 필요하면 릴리스 태그·커밋으로 고정한 GitHub raw 복사본을 검토한 뒤 실행하라고 INSTALLING이 안내한다.
비대화형:
curl -fsSL https://paperclip.ing/install.sh | bash -s -- --no-prompt --no-onboard
paperclipai onboard --yes
파이프 형태는 이미 지원 Node·npm·npx가 있어야 한다. Node 부트스트랩이 필요하면 파이프 대신 파일을 받아 검토한 뒤 실행한다.
2) 영구 설치 없이 체험 (npx)
npx --registry https://registry.npmjs.org paperclipai onboard --yes
# 이후
npx paperclipai run
사설 npm 레지스트리(~/.npmrc) 때문에 paperclipai가 E404 나면, 위처럼 공개 레지스트리를 강제로 지정한다. 진단: npm config get registry.
3) test-drive (포그라운드, 임시 데이터)
ANTHROPIC_API_KEY=… npx paperclipai test-drive
OPENAI_API_KEY=… npx paperclipai test-drive --harness codex
서비스 설치 없이 CEO 에이전트가 준비된 격리 인스턴스를 띄운다. --data-dir 없으면 임시 디렉터리를 만들고 경로를 출력한다. --no-browser로 브라우저 자동 오픈을 끌 수 있다.
4) 소스에서 개발
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev # http://localhost:3100
5) 서비스·업데이트
paperclipai service install
paperclipai service status
paperclipai service start|stop|restart
paperclipai service logs -f
paperclipai service uninstall
paperclipai update
paperclipai update --rollback
paperclipai doctor
바인드·인증 모드: 기본 퀵스타트는 로컬 루프백 신뢰 모드. 인증/프라이빗으로 시작하려면:
paperclipai onboard --yes --bind lan
# 또는
paperclipai onboard --yes --bind tailnet
6) 첫 회사 (문서 퀵스타트 요약)
인스턴스가 떠 있으면 docs 퀵스타트는 대략 5분 경로를 제시한다.
- Create Your First Company — 회사 이름(목표는 이후에 추가).
- Hire Your First Agent — CEO 에이전트 구성, 상태
idle. - Watching Agents Work — 하트비트 → 전략 승인 대기 → 승인 후 Issues에 첫 태스크.
끝나면 Companies에 목표, Agents에 CEO(하트비트 on), Approvals에 전략 초안, Issues에 todo/backlog, Runs에 트랜스크립트가 보인다. Claude 로컬 어댑터를 쓰려면 같은 머신에 Claude Code가 설치되어 있어야 한다고 문서가 명시한다.
막히는 지점 / 표
| 증상·헷갈림 | 원인 | 해결 힌트 |
|---|---|---|
npx paperclipai E404 | 사설 npm 레지스트리 | npx --registry https://registry.npmjs.org paperclipai …. npm config get registry로 확인 |
| 서비스만 옛 Node로 뜸 | systemd/launchd가 셸 nvm PATH를 안 읽음 | 실행 중 바이너리(/proc/…/exe 등)를 확인하고, 지원 Node로 설치를 다시 핀한 뒤 서비스 재시작(INSTALLING “Node runtime used by background services”) |
| 파이프 설치가 Node 부트스트랩에서 멈춤 | 파이프는 사전 Node 필요 | install.sh를 받아 검토한 뒤 로컬 실행. 또는 이미 Node 24.11+인 환경에서 --no-prompt --no-onboard |
| 외부에서 대시보드 안 열림 | 기본은 루프백 신뢰 모드 | --bind lan / --bind tailnet으로 온보딩. Tailscale 등 문서 FAQ 참고 |
| 비용이 갑자기 뜀 | 에이전트 API 호출 | 하트비트 전에 per-agent·company 예산. 한도 100%면 자동 일시정지(퀵스타트 경고) |
paperclipai run 거부 | 같은 인스턴스가 이미 서비스 감독 중 | 서비스 stop 후 run, 또는 의도적 단일 작성자 위험을 감수할 때만 --force |
| 온보딩을 다시 돌림 | 기존 설정 유지 | 재실행은 설정을 덮어쓰지 않음. 변경은 paperclipai configure |
마치며
Paperclip은 “에이전트 하나를 더 똑똑하게”가 아니라, 이미 쓰는 여러 에이전트를 회사처럼 돌리게 만드는 쪽에 가깝다. Node 24.11+, 매니지드 설치 또는 npx onboard, 그다음 회사·CEO·예산·하트비트 순으로 가면 문서가 말하는 첫 경로가 열린다. 버전·명령은 릴리스에 따라 바뀔 수 있으니 설치 직전 README·INSTALLING·docs를 한 번 더 보는 편이 안전하다.
이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.