[오픈소스 사용법] Paperclip — AI 에이전트 여러 명을 회사처럼 굴려 본 사람들의 사례 모음
· 바이브코드 운영팀
목차
Paperclip은 AI 에이전트 여러 명을 한 회사처럼 운영하게 해 주는 오픈소스예요. Claude Code나 Codex 같은 에이전트를 직원으로 두고, 해야 할 일은 티켓으로, 쓰는 돈은 예산으로, 중요한 결정은 사람의 승인으로 관리해요. README는 "OpenClaw가 직원이라면 Paperclip은 회사"라고 소개해요. 이 글은 직접 써 본 사람들의 후기와 사례를 모아서, 어디에 잘 맞고 어디서 걸리는지 먼저 보여 드리고 설치 방법을 이어서 정리했어요.
출처: paperclipai/paperclip README의 배너 (그림 속 글자는 영어예요)
이럴 때 쓰세요
- Claude Code 터미널을 여러 개 띄워 놓고 누가 무슨 일을 하는지 놓치고 있을 때
- 에이전트에게 반복 업무(보고서, 지원 문의 분류, PR 검토)를 일정에 맞춰 맡기고 싶을 때
- 에이전트가 쓰는 비용에 상한을 두고 싶을 때
- 에이전트가 낸 결과를 승인 단계를 거쳐 받고 싶을 때
에이전트가 하나뿐이라면 필요 없어요. README에도 "에이전트가 하나라면 Paperclip은 아마 필요 없다"고 적혀 있어요.
먼저 알아둘 구조
Paperclip은 에이전트를 대신 일하게 하는 도구가 아니에요. 일은 연결해 둔 에이전트(Claude Code, Codex, Gemini CLI, Cursor, OpenCode, OpenClaw 등)가 하고, Paperclip은 그 에이전트들에게 일을 나눠 주고 기록하고 비용을 세는 관리 화면이에요. 에이전트를 연결하는 부분을 어댑터(adapter)라고 불러요.
출처: paperclipai/paperclip README의 "네 기둥" 그림 (그림 속 글자는 영어예요)
핵심 개념은 이 정도예요.
- 회사와 조직도: 회사를 만들고 CEO, 엔지니어 같은 역할을 에이전트에게 줘요. 한 서버에서 회사를 여러 개 만들 수 있고 서로 완전히 분리돼요.
- 티켓: 일은 티켓 하나로 만들고, 담당자와 부모·자식 관계, 서로 막는 관계를 붙여요.
- 하트비트(heartbeat): 에이전트가 일정에 맞춰 깨어나 할 일이 있는지 확인하는 방식이에요.
- 예산과 승인: 에이전트별, 회사별 예산을 두고, 새 에이전트를 뽑는 것 같은 일은 사람이 승인해요.
사례 1. 4일 만에 사업 하나를 띄운 팀
Aron & Sharon(2026년 3월 글)은 Paperclip으로 소프트웨어 제품 하나를 처음부터 출시까지 만들었다고 해요. 글에 적힌 숫자는 이래요.
- 일 140개, 부서 7개, 기간 4일
- 에이전트 7명이 CEO의 조율 아래 동시에 일했어요. 워드프레스 개발, 디자인, 판매 문구, 마케팅, 지원 문서, SEO 담당이에요.
- 24시간 안에 VPS에 사이트를 열고 SSL까지 붙였어요.
- 맞춤 워드프레스 테마, 가격 3단계 상품, 문서 라이브러리, 이메일 가입 유도 흐름, 법적 고지 페이지를 만들고 PR 67개를 병합했어요.
- 마지막에 사람이 한 일은 결제(Stripe) 연결뿐이었다고 해요.
같은 글은 비용도 경고해요. 에이전트 여러 명이 일정에 맞춰 돌면서 작업마다 Claude API를 여러 번 부르니 금방 불어나고, 그래서 처음에는 예산을 빡빡하게 걸라고 권해요.
사례 2. 2주 동안 직접 굴려 본 개발자의 후기
Jayadeep의 2주 후기는 자기 오픈소스 프로젝트(Kubernetes AI SRE)를 맡겨 본 기록이에요. 배울 점이 많아요.
- 목표만 던진 CEO는 쓸모가 거의 없었어요. 프로젝트, 작업 폴더, 실행 환경을 먼저 정해 주고 나서야 일이 풀렸어요.
- CEO 에이전트는
AGENTS.md(역할),HEARTBEAT.md(깨어날 때 할 일),SOUL.md(말투),TOOLS.md(쓸 수 있는 도구) 네 파일로 운영 설명서를 갖고 있었어요. 반대로 새로 뽑힌 엔지니어의AGENTS.md는 두 줄뿐이라 실수가 잦았어요. - 네 파일을 엔지니어에게도 똑같이 만들어 주자 나아졌고, 일주일 동안 PR을 약 50개 만들었다고 해요. 그래도 "master에 바로 푸시하지 마라", "PR 전에 끝까지 검증하라" 같은 규칙을 계속
AGENTS.md에 보태야 했어요. - 모델 선택도 중요했어요. GPT 계열은 Codex로 잘 돌았고, MiniMax 2.5는 Paperclip 티켓을 제대로 다루지 못했어요.
- 결론은 "지금은 프로덕션용이 아니다. 만지작거리기를 즐기는 사람에게만 권한다"였어요. 조직도의 CEO, CFO 같은 역할은 "보기 좋은 장치에 가깝다"고 봤어요.
- 보안 때문에 자기 노트북에서는 돌리지 않고, 월 5달러짜리 VPS나 중고 PC의 가상 머신을 권했어요.
사례 3. 비용 상한이 값을 한 날
ToolCenter의 리뷰(2026년 5월)는 2주 사용기에서 두 가지 구성을 소개해요.
- 콘텐츠 파이프라인: 조사 담당, 초안 담당, 검토 담당 에이전트 3명이에요. 조사 담당이 일정에 맞춰 자료를 모아 티켓을 만들고, 초안 담당이 받아 쓰고, 검토 담당이 확인한 뒤 사람이 승인 단계를 통과시켜요. 순서와 예산은 지켜졌지만 글의 품질은 연결한 에이전트가 원래 내는 수준 그대로였어요. 조율은 해 줘도 실력을 올려 주지는 않는다는 뜻이에요.
- 사내 도구 팀: 엔지니어 2명과 QA 1명이 작은 저장소를 맡았어요. 한 에이전트가 모호한 티켓에서 같은 일을 반복하다 예산의 80%에서 경고가 왔고, 100%가 되면 자동으로 멈췄을 거라고 해요. 티켓을 고쳐 쓰고 넘어갔대요.
불편했던 점도 솔직하게 적혀 있어요. 하트비트 주기를 맞추는 데 시행착오가 있었고, 비밀 값(secret) 설정을 잘못해서 반나절 동안 조용히 실패했어요. 승인 단계도 사람이 실제로 확인해야 의미가 있어요.
사례 4. 일이 알아서 도착하니 토큰 사용량이 달라진 경우
Niran Evenchen의 글(2026년 9월)은 로컬 모델로 에이전트 팀을 돌리던 사례예요. 일을 티켓으로 만들고 부서마다 하트비트 타이머를 켜자 이런 일이 생겼다고 해요.
- 타이머를 켜기 전: 하루에 로컬 모델 실행이 약 10번, 토큰은 약 3만 개
- 타이머를 켠 뒤: 반복 업무와 보고서가 정기적으로 돌면서 하루에 수백만 토큰
- 같은 장비, 같은 모델이었어요. 달라진 것은 일이 사람 손을 거치지 않고 도착하기 시작했다는 점이에요.
파일마다 하나의 역할만 맡긴다는 원칙(정체성은 정체성 파일, 역할은 역할 파일)으로 에이전트 지침을 나눈 것도 눈여겨볼 만해요.
사례 5. 아무 일도 안 하는데 크레딧이 줄어든 경우
Open Source is Better의 테스트 글(2026년 4월)은 Docker Compose로 설치해 CEO와 디자이너 에이전트 두 명으로 시작했어요. CEO가 디자이너와 CTO를 뽑으며 서로 조율하는 모습은 재미있었다고 해요. 다만 화면에는 "에이전트가 일하는 중"이라고 뜨는데 실제 결과물은 없는 상태에서 하트비트와 상태 확인만으로 코딩 크레딧이 꾸준히 줄었어요. 처음에는 에이전트를 최소한으로 두고, 실행 기록(로그)을 자주 보라는 교훈을 얻을 수 있어요.
사례 6. 예산 상한이 구독 사용량은 막지 못한 경우
Sophrai의 3명 파일럿(2026년 11월)은 조사, 작성, 검토 에이전트 3명을 만들고 회사 한도 1달러, 에이전트별 한도 0.25달러로 하드스톱을 걸었어요.
- 실제로 돈 에이전트는 조사 담당뿐이고 약 4분 12초 걸렸어요. 나머지 둘은 만들어만 두고 실행하지 않았어요.
- Claude 구독으로 돌렸더니 Paperclip 장부에는 청구액 0달러로 기록됐어요. 제공사가 알려 준 API 환산 값은 약 1.50달러였어요.
- 그래서 청구액 기준 예산 상한이 구독 사용량은 막아 주지 못했어요. 글쓴이는 이것을 "0달러의 함정"이라고 불렀어요.
- 이 글의 결과는 한 번 실행한 가설이고, 매출이나 발행 결과는 없다고 스스로 밝혀요.
구독 로그인으로 연결할 때는 Paperclip 화면의 비용 숫자만 믿지 말고 제공사 쪽 사용량도 같이 확인하는 편이 안전해요.
어떤 사람에게 맞을까
andrew.ooo의 리뷰(2026년 10월)가 정리한 기준이 쓸 만해요.
잘 맞는 경우
- 에이전트 런타임을 둘 이상 쓰고, 작업·비용·기록을 한 곳에서 보고 싶을 때
- 지원 문의 분류, 주간 보고, PR 검토처럼 반복 일을 일정으로 돌리고 싶을 때
- 에이전트가 사람 없이 돈을 쓰니 하드스톱과 감사 기록이 필요할 때
안 맞는 경우
- 저장소 하나에 코딩 에이전트 하나만 쓸 때
- 끌어다 놓는 워크플로 빌더를 원할 때
- 쓰는 런타임이 어댑터 목록에 없고 직접 만들 생각도 없을 때
- 매일 나오는 나이틀리 빌드와 가끔 생기는 호환 깨짐을 견디기 어려울 때
같은 글은 운영 중 버그가 오케스트레이션보다 어댑터 경계(신원, 깨어남 정보, 토큰 집계)에서 많이 난다고 짚어요. 13명 규모 조직을 6주 굴린 한 운영자는 루프를 사람 없이 닫으려고 어댑터를 직접 만들어야 했다고 해요.
준비물
- Node.js 24.11 이상
- Claude 구독으로 로그인해 쓰려면 Python 3와 Claude Code CLI도 필요해요.
- 소스로 실행하려면 pnpm 9.15 이상이 필요해요.
- 계정 가입은 필요 없어요. 내 컴퓨터나 서버에서 직접 돌리는 방식이에요.
- 앞의 사례들처럼 에이전트가 계속 돌 수 있으니, 처음에는 예산을 낮게 두는 것을 추천해요.
설치
README가 추천하는 방법은 한 줄이에요.
npx paperclipai@latest onboard --yes
실행하면 로컬 데이터베이스가 만들어지고 http://localhost:3100에서 웹 화면이 열려요. 설정과 데이터는 내 컴퓨터에 남아요.
사설 npm 레지스트리를 쓰다가 E404가 나면 공식 레지스트리를 지정하세요.
npx --registry https://registry.npmjs.org paperclipai@latest onboard --yes
먼저 맛만 보고 싶다면 체험 명령이 있어요. 키 값은 본인 것으로 바꿔 넣으세요.
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY npx paperclipai test-drive
처음 실행해 보기
공식 Claude Code 연결 안내에 나온 순서예요.
- 같은 컴퓨터에 Claude Code를 설치해요.
- Paperclip에서 새 에이전트를 만들고 어댑터로 Claude Code 카드를 골라요.
- 연결 단계에서 구독 로그인을 하거나 Anthropic API 키를 입력해요.
- 모델을 고르고 "Run test"로 연결을 확인한 뒤 설정을 마쳐요.
- 프로젝트(Add Project)로 내 저장소를 추가하고 작업(Assign Task)을 만들어 에이전트에게 맡겨요.
- 결과를 사람이 확인한 뒤에 받고 싶다면 작업 속성에서 검토자나 승인자를 추가해요.
사례 2의 교훈을 따라, CEO에게 큰 목표를 던지기 전에 프로젝트와 작업 폴더를 먼저 만들고 에이전트별 AGENTS.md를 구체적으로 써 두세요.
관련 영상
모르면 진짜 개손해... AI로 회사 운영 해주는 Paper Clip. 심지어 무료 오픈소스 (코드팩토리 채널, 한국어) — npx paperclipai onboard --yes로 띄운 뒤 CEO를 만들고, 뉴스 리서처·콘텐츠 매니저·스크립트 라이터·SEO 라이터로 이뤄진 콘텐츠 제작 팀을 승인해 가며 꾸려 가는 과정을 한국어로 보여 줘요.
직원 없이 회사 운영? AI 조직이 다 해줘 (paperclip AI) (뉴트라이 채널, 한국어 쇼츠, 2026-04-05) — CEO 에이전트에게 목표만 던지면 개발·마케팅 같은 역할을 AI 직원이 나눠 맡는 개념을 짧게 소개해요.
알아둘 점
- 프로덕션용인지는 아직 조심해야 해요. 사례 2의 글쓴이는 안정적으로 쓰려면 기다리는 편이 낫다고 했고, 어댑터 쪽 버그 이야기도 여러 글에 나와요.
- 비용을 직접 확인하세요. 하트비트가 일 없이도 크레딧을 쓸 수 있고, 구독 로그인은 Paperclip의 청구 예산 상한에 잡히지 않을 수 있어요.
- 에이전트의 실력은 연결한 모델이 정해요. Paperclip은 순서와 기록, 상한을 맡아 줄 뿐이에요.
- 보안: 에이전트에게 파일과 비밀 값을 쓸 권한을 주게 되니 가능하면 노트북 대신 따로 둔 서버나 가상 머신에서 돌리세요. API 키는 비밀번호처럼 다루세요.
- 텔레메트리: README에 따르면 기본으로 켜져 있어요. 끄려면 환경 변수
PAPERCLIP_TELEMETRY_DISABLED=1을 쓰세요. - 위 사례는 각 글쓴이가 직접 밝힌 내용이에요. 이 글에서 따로 실행해 검증한 것은 아니에요.
더 보기
- 바이브코드 도구 상세: Paperclip
- 저장소: paperclipai/paperclip
- 공식 사이트: paperclip.ing
- 사례 원문: Aron & Sharon · Jayadeep · ToolCenter · Niran Evenchen · Open Source is Better · Sophrai · andrew.ooo
확인한 날짜 2026-11-18 · 라이선스 MIT · 별 약 11만 개 · 기준 커밋 ea154ce
글이 도움이 되었다면 좋아요를 눌러 주세요.