직원이 전부 AI인 회사를 여는 Paperclip 입문 가이드

추석 AI 부트캠프 하루 6시간 만에
AI 기초부터 나만의
서비스까지 완성 이번 연휴를 기회로 삼으세요일정 보기 ↗

역할: Paperclip의 설치와 첫 회사 개설을 맡는 담당입니다.

맥락: 사용자는 macOS 또는 Linux를 씁니다.
설치 대상은 [Paperclip 공식 GitHub](https://github.com/paperclipai/paperclip) 오픈소스이고,
공식 안내는 저장소 README와 doc/INSTALLING.md 에 있습니다.

입력
  운영체제: <macOS / Linux / WSL2>
  회사 이름: <한 단어>
  회사 목표: <기한과 숫자가 들어간 한 문장>

작업
  1. README와 doc/INSTALLING.md 를 읽고 현재 권장 설치 경로를 확인한다.
     내가 적은 명령이 문서와 다르면 문서를 따른다.
  2. bash 버전을 먼저 확인한다. 3.x 이면 install.sh 가 실행되지 않으므로
     npx 경로로 우회한다.
  3. 셸에 DATABASE_URL 이 설정돼 있으면 지운 상태로 실행한다.
     Paperclip 이 내장 데이터베이스 대신 그 주소로 붙으려다 죽는다.
  4. 서버가 뜨면 브라우저 온보딩 5단계를 마친다.

제약
  - 추측하지 않는다. 문서에 없는 명령을 지어내지 않는다.
  - API 키·토큰 값을 화면에 출력하지 않는다.
  - 권한 상승이 필요한 명령은 실행 전에 나에게 먼저 보여준다.

출력: 실행한 명령과 각 명령의 결과를 순서대로 보여준다.

검증: curl http://localhost:3100/api/health 가
      "status":"ok" 와 "bootstrapStatus":"ready" 를 반환해야 합니다.
      하나라도 실패하면 완료로 보고하지 말고 실패 지점과 다음 조치를 알려주세요.

이걸 깔면 무엇이 달라지나

클로드 코드는 창 하나에서 일합니다. 창을 여러 개 띄우면 일이 여러 개 도는 것처럼 보이지만 서로를 모릅니다. 어느 창이 무엇을 맡았는지, 얼마를 썼는지, 끝났는지를 사람이 기억해야 합니다. 컴퓨터를 껐다 켜면 그 기억마저 사라집니다.

Paperclip은 그 위에 한 겹을 올립니다. 저장소 첫 줄이 차이를 한 문장으로 적어 두었습니다.

> If OpenClaw is an *employee*, Paperclip is the *company*.

> 오픈클로가 직원이라면, Paperclip은 회사입니다.

에이전트마다 직책과 상사와 월 예산이 생깁니다. 할 일은 티켓이 되고, 대화는 스레드로 남고, 세션은 재부팅을 넘어 이어집니다. 예산을 다 쓴 직원은 스스로 멈춥니다.

MetaGPT나 ChatDev 같은 도구와 갈리는 지점이 여기입니다. 그쪽은 개발팀을 자동화하고, Paperclip은 회사를 자동화합니다. 문서가 쓰는 말도 코드가 아니라 경영 쪽입니다.

> Manage business goals, not pull requests.

> 풀 리퀘스트가 아니라 사업 목표를 관리하세요.

시작 흐름은 세 줄입니다.

1. 목표를 정한다 — "AI 노트앱 1위로 만들어서 월 매출 100만 달러"
2. 팀을 고용한다 — CEO · CTO · 엔지니어 · 디자이너 · 마케터
3. 승인하고 돌린다 — 전략을 검토하고, 예산을 정하고, 시작합니다

무엇이 필요한가

• Node.js 24.11 이상
• 클로드 코드 또는 Codex 중 하나가 이미 로그인된 상태
• 터미널 몇 줄. 나머지는 브라우저에서 합니다

두 번째가 중요합니다. Paperclip은 자기 모델을 갖고 있지 않고 여러분이 이미 쓰는 CLI를 대신 굴립니다. 그 CLI가 로그인돼 있지 않으면 온보딩은 통과해도 첫 직원이 실패합니다. 아래 STEP 6에서 실제로 그렇게 됐습니다.

Quick Start

전체 25분이면 첫 회사가 돌아갑니다.

STEP 1 · 3분설치 파일을 검증합니다

이 단계에서는 설치 파일이 중간에 바뀌지 않았는지 확인합니다. 스크립트를 그대로 받아 실행하면 무엇이 실행되는지 모른 채 권한을 넘기게 되기 때문입니다.

curl -fsSLO https://paperclip.ing/install.sh
curl -fsSLO https://paperclip.ing/install.sh.sha256
shasum -a 256 -c install.sh.sha256

성공하면 install.sh: OK 가 보입니다. FAILED 가 나오면 실행하지 말고 두 파일을 다시 받으세요.

STEP 2 · 1분맥이라면 여기서 한 번 막힙니다

이 단계에서는 bash 버전을 확인합니다. 공식 설치 스크립트가 bash 4 이상의 문법을 쓰는데, 맥에 기본으로 깔린 bash는 3.2 이기 때문입니다.

/bin/bash --version | head -1

GNU bash, version 3.2.57(1)-release (arm64-apple-darwin25)

이 상태로 설치 스크립트를 돌리면 이렇게 끊깁니다.

install.sh: line 57: ${value,,}: bad substitution

${value,,} 는 소문자로 바꾸는 bash 4 문법입니다. 3.2 에는 없습니다. zsh 로 바꿔 실행해도 같은 자리에서 멈춥니다.

해결은 둘 중 하나입니다. brew install bash 로 새 bash를 깔고 그것으로 실행하거나, 아래 STEP 3의 npx 경로로 우회하면 됩니다. 이 가이드는 아무것도 새로 깔지 않는 두 번째 길로 갑니다.

STEP 3 · 6분npx 로 설치 없이 띄웁니다

이 단계에서는 컴퓨터에 영구 설치를 하지 않고 CLI를 임시로 받아 씁니다. 도구가 내 방식에 맞는지 먼저 보고 결정하는 편이 낫기 때문입니다.

npx --yes --registry https://registry.npmjs.org paperclipai --help

성공하면 install · onboard · doctor · company · agent · heartbeat · budget · org 같은 명령이 쭉 나옵니다. E404 가 나오면 사내 npm 저장소를 보고 있는 것입니다. npm config get registry 로 확인하고 위처럼 --registry 를 붙여 공개 저장소를 강제하세요.

npx --yes --registry https://registry.npmjs.org paperclipai onboard --yes

STEP 4 · 2분서버가 실제로 살아 있는지 봅니다

이 단계에서는 설치가 끝났는지가 아니라 서버가 응답하는지를 봅니다. 설치만 되고 서비스가 안 올라오면 뒤 단계가 전부 막히기 때문입니다.

curl -s http://localhost:3100/api/health

{"status":"ok","version":"2026.817.0","deploymentMode":"local_trusted",
 "deploymentExposure":"private","authReady":true,"bootstrapStatus":"ready"}

성공하면 "status":"ok" 와 "bootstrapStatus":"ready" 가 함께 보입니다. local_trusted 는 내 컴퓨터에서만 열리는 모드라는 뜻입니다. 밖에서도 접근하려면 온보딩 때 --bind lan 이나 --bind tailnet 을 붙입니다.

설치된 자리는 ~/.paperclip 이고, 첫 설치 직후 용량은 76MB 입니다. 내장 Postgres가 같이 들어 있기 때문입니다.

STEP 5 · 8분브라우저에서 회사를 만듭니다

이 단계에서는 화면으로 넘어갑니다. http://localhost:3100 을 열면 다섯 단계짜리 마법사가 뜹니다.

1단계 — 회사 이름. Paperclip에서는 회사가 가장 바깥 단위여서, 직원도 예산도 회사 아래에 붙습니다.

2단계 — 미션. 직접 적거나(I know my mission), 몇 가지 질문에 답해 만들 수 있습니다(Help me figure it out). 아래 칩으로 Build a SaaS product · Scale a content business · Launch a marketplace 예시도 줍니다.

목표는 막연하게 적으면 안 됩니다. 문서의 예시가 기준입니다.

Create the #1 AI note-taking app that does $1M MRR within 3 months
3개월 안에 월 매출 100만 달러를 내는 AI 노트앱 1위 만들기

기한과 숫자가 들어가야 합니다. 모든 할 일이 이 목표로 거슬러 올라가기 때문에, 목표가 흐리면 아래 일도 흐려집니다. 한국어로 적어도 그대로 저장됩니다.

3단계 — 팀 리드. 직원을 한 명만 만듭니다. 기본 이름이 Chief of staff 이고 바꿔도 됩니다. 문서가 CEO부터 정하고 거기서 뻗어 나가라고 적고 있습니다.

4단계 — 어댑터 연결. 이 직원이 무엇으로 돌지 고릅니다. Claude Code 와 Codex 가 추천으로 뜨고, More Agent Adapter Types 를 열면 Gemini·Cursor·OpenCode 등이 더 있습니다.

여기 Adapter environment check 가 있습니다. Test now 를 누르면 어댑터 CLI에 실제로 인사를 걸어 봅니다.

5단계 — 검토. 회사 이름 · 미션 · 직원 생성 · 모델 연결 네 항목에 체크가 붙고, Get started 로 대시보드에 들어갑니다.

STEP 6 · 5분첫 직원이 스스로 일을 만듭니다

이 단계에서는 사람이 아무것도 시키지 않은 상태로 대시보드를 봅니다. Paperclip이 정해진 주기마다 직원을 깨우는 구조라, 들어가자마자 이미 움직이고 있기 때문입니다.

들어가면 직원 셋이 이미 있습니다. Chief of staff(대표 역할) · Reflection Coach · Summarizer. 뒤 둘은 일시정지 상태로 만들어져 있습니다.

그리고 팀 리드가 자기 첫 할 일을 스스로 만들어 둡니다.

EVE-1 — Hire your first engineer and create a hiring plan
첫 엔지니어를 채용하고 채용 계획을 세워라

내가 시킨 적이 없습니다. 미션만 적었을 뿐인데 팀 리드가 거기서 첫 과제를 뽑았습니다.

집계 네 칸이 이 도구의 성격을 보여줍니다.

• Agents Enabled — 직원 수와 상태(도는 중 / 멈춤 / 오류)
• Tasks In Progress — 진행 중인 할 일
• Month Spend — 이번 달 쓴 돈. 예산을 안 걸면 Unlimited budget
• Pending Approvals — 내 결재를 기다리는 것

온보딩을 통과해도 실패할 수 있습니다

여기가 이 가이드에서 가장 중요한 부분입니다.

4단계의 Adapter environment check 는 ✓ Passed 로 나왔습니다. 그런데 첫 할 일은 1초 만에 실패했습니다.

EVE-1 — Hire your first engineer and create a hiring plan
⚠ Recovery needed
Chief of staff · failed after 1 second
Agents Enabled 3 — 0 running, 2 paused, 1 errors

로그를 열어 보니 원인이 한 줄이었습니다.

Failed to authenticate: OAuth session expired and could not be refreshed

클로드 코드 로그인이 만료돼 있었습니다. Paperclip은 자기 모델을 갖고 있지 않고 그 CLI를 대신 실행하기 때문에, CLI가 로그인돼 있지 않으면 그대로 실패합니다.

그런데 Test now 는 통과했습니다. 환경 점검은 CLI가 실행되는지만 보고, 로그인까지는 보지 않습니다. 통과 표시를 믿고 넘어가면 여기서 걸립니다.

해결은 순서입니다. Paperclip을 깔기 전에 터미널에서 claude 를 한 번 실행해 로그인이 살아 있는지 먼저 확인하세요. 로그인 상태로 만든 뒤에 Paperclip을 띄우면 그대로 이어받습니다.

자주 막히는 곳

install.sh: line 57: ${value,,}: bad substitution

맥 기본 bash가 3.2 라서 그렇습니다. brew install bash 로 4 이상을 깔아 그것으로 실행하거나, npx 경로로 우회하세요.

서버가 뜨다가 (ENOTFOUND) tenant/user postgres.… not found 로 죽습니다.

셸에 DATABASE_URL 이 설정돼 있으면 Paperclip이 내장 데이터베이스 대신 그 주소로 붙으려 합니다. 다른 프로젝트의 .env 를 통째로 불러온 셸에서 실행하면 이렇게 됩니다. 그 변수를 지운 상태로 실행하세요.

env -u DATABASE_URL npx --yes --registry https://registry.npmjs.org paperclipai run

npx 가 E404 를 냅니다.

사내 npm 저장소를 보고 있는 경우입니다. npm config get registry 로 확인한 뒤 --registry https://registry.npmjs.org 를 붙이세요.

직원이 Recovery needed 로 멈춰 있습니다.

어댑터 CLI의 로그인을 먼저 확인하세요. 그다음 로그를 봅니다. 실패 이유는 ~/.paperclip/instances/default/data/run-logs/ 아래 .ndjson 파일에 그대로 적힙니다.

직원이 아무 일도 안 합니다.

기본은 정해진 주기에만 깨어나는 방식이라 주기가 길면 한참 뒤에 움직입니다. 할 일이 배정되거나 @ 로 불릴 때도 깨어납니다.

터미널에서 상태 보기

화면 없이 확인할 때 쓰는 명령입니다. 회사 아이디는 대시보드 주소나 활동 로그에 나옵니다.

npx paperclipai agent list -C <회사ID>

name=Chief of staff status=error role=ceo budgetMonthlyCents=0
name=Reflection Coach status=paused role=general reportsTo=…
name=Summarizer      status=paused role=general reportsTo=…

npx paperclipai doctor

성공하면 All checks passed! 가 나옵니다. 백업이 아직 없으면 database_backup_missing 경고가 하나 붙는데, 처음엔 정상입니다.

npx paperclipai activity issue EVE-1

FAQ

회사를 여러 개 돌릴 수 있나요.

할 수 있습니다. 설치 하나로 회사를 개수 제한 없이 돌리고, 회사끼리 데이터가 완전히 분리됩니다.

클로드 코드나 오픈클로와 뭐가 다른가요.

Paperclip은 그것들을 씁니다. 조직도·예산·목표·결재를 붙여 하나의 회사로 묶는 쪽입니다.

직원이 계속 돌아가나요.

기본은 정해진 주기에 깨어나는 방식입니다. 할 일이 배정되거나 @ 로 불릴 때도 깨어납니다. 계속 도는 에이전트를 따로 연결할 수도 있습니다.

밖에서도 볼 수 있나요.

됩니다. 1인 사업자라면 Tailscale로 연결해 이동 중에 확인하고, 나중에 필요해지면 클라우드에 올리면 된다고 문서가 안내합니다.

공짜인가요.

오픈소스이고 MIT 라이선스입니다. 직접 설치해 쓰는 데 계정이 필요 없습니다. 다만 안에서 부리는 에이전트의 모델 사용료는 따로 나갑니다.

지우려면요.

npx paperclipai uninstall 이 관리형 설치본을 지우고 데이터는 남깁니다. 데이터까지 지우려면 ~/.paperclip 을 통째로 지웁니다.

알아 둘 한계

아직 어립니다. 저장소가 2026년 3월 2일에 만들어졌습니다. 5개월 남짓입니다. 로드맵에 아직 안 끝난 항목이 남아 있습니다 — 기억·지식, 작업 대기열, 자기 조직화.

맥에서 공식 설치 경로가 막힙니다. 위 STEP 2 문제입니다. 문서에는 이 안내가 없습니다.

돈이 듭니다. Paperclip 자체는 무료지만, 직원이 도는 만큼 모델 사용료가 나갑니다. 예산을 먼저 걸고 시작하세요. 안 걸면 Unlimited budget 으로 표시됩니다.

터미널이 필요합니다. 화면은 브라우저로 보지만, 세우는 것은 명령 몇 줄로 합니다.

공식 자료

• Paperclip 공식 GitHub
• paperclip.ing 공식 사이트
• Paperclip 공식 문서
• 설치 상세 doc/INSTALLING.md
• 제품 정의 doc/PRODUCT.md
• CLI 전체 doc/CLI.md

> 이 가이드의 화면과 오류는 2026년 8월 25일 macOS(Apple Silicon)에서 직접 설치하며 얻은 것입니다.

> 버전 2026.817.0 기준입니다.