paperclipai/paperclip 조사 문서

GitHub 조사 문서 · paperclipai/paperclip · 2026-03-31 기준

Paperclip 완전 조사 가이드

이 문서는 thoughtbot의 Ruby gem Paperclip이 아니라, paperclipai/paperclip 저장소를 기준으로 정리한 설치·운영·활용 문서다. 빠른 실행부터 로컬 개발, Docker, 배포 모드, 어댑터 선택, 회사/에이전트/태스크 운영, 예산·승인, API/CLI 활용, 커스텀 어댑터 작성까지 한 번에 따라갈 수 있게 구성했다.

Open-source orchestration for zero-human companies Self-hosted Node.js + React + PostgreSQL/Drizzle MIT License

1. 저장소 스냅샷

프로젝트 정체성

Paperclip은 Node.js 서버 + React UI 형태의 제어 평면(control plane)이다. 여러 AI 에이전트를 “직원”으로 두고, 목표·조직도·예산·승인·태스크를 관리하는 데 초점이 맞춰져 있다.

현재 공개 상태

공개 저장소이며 MIT 라이선스다. GitHub 기준으로 별 수가 매우 많고 커뮤니티 활동도 활발한 편이다. 최신 릴리스도 2026년 3월에 올라와 있어 현재도 빠르게 바뀌는 프로젝트로 보는 편이 맞다.

문서 범위

이 문서는 설치 방법뿐 아니라, 첫 회사 생성 → CEO 에이전트 설정 → 조직도 구성 → 태스크 운영 → 예산/승인 관리 → API/CLI 자동화까지 이어지는 실제 사용 흐름을 다룬다.

항목	정리
저장소	paperclipai/paperclip
설명	Open-source orchestration for zero-human companies
라이선스	MIT
최신 릴리스	v2026.325.0 (2026-03-25)
주요 스택	React 19, Vite 6, Node.js 20+, Express 5, TypeScript, Drizzle ORM, PostgreSQL, pnpm workspaces
기본 로컬 주소	`http://localhost:3100`
기본 로컬 DB	내장 PostgreSQL 사용 가능

중요: Paperclip은 업데이트 속도가 빠르다. 따라서 “완전 조사”의 의미를 공식 GitHub 저장소 + 공식 문서 기준의 2026-03-31 시점 정리로 이해하는 것이 정확하다.

참고: GitHub 저장소 메인 페이지, 릴리스 페이지, 공식 Architecture/Quickstart 문서

2. Paperclip이 무엇인지

Paperclip의 핵심은 “에이전트를 개별 봇이 아니라 회사 조직으로 본다”는 점이다. 단일 챗봇 인터페이스보다 회사 목표, CEO, CTO, 연구원, 엔지니어, 승인 절차, 비용 통제 같은 운영 개념이 전면에 나온다.

이런 경우에 잘 맞는다

여러 AI 에이전트를 동시에 운영하고 있다.
작업을 목표-프로젝트-태스크 구조로 추적하고 싶다.
에이전트별 비용과 월 예산을 통제해야 한다.
사람 승인 없이 폭주하지 않도록 거버넌스가 필요하다.
로컬 또는 사설 네트워크에서 self-hosting 하고 싶다.

이런 경우엔 과할 수 있다

에이전트가 1개뿐이고, 간단한 챗 인터페이스만 원한다.
단순 워크플로 빌더나 단순 자동화 도구가 더 적합하다.
PR 리뷰, 챗봇, 프롬프트 관리만 필요하다.
“조직 운영”보다 “한 번 호출하는 스크립트”가 더 중요하다.

한 줄로 요약하면, Paperclip은 에이전트를 만드는 프레임워크라기보다 에이전트 조직을 운영하는 시스템에 가깝다.

참고: README의 “What is Paperclip?”, “Paperclip is right for you if”, “What Paperclip is not”

3. 아키텍처와 핵심 개념

3-1. 전체 아키텍처

React UI (Vite) └─ 대시보드, 조직 관리, 작업 관리 Express.js REST API (Node.js) └─ 라우트, 서비스, 인증, 어댑터 실행 PostgreSQL + Drizzle ORM └─ 스키마, 마이그레이션, 임베디드 모드 Adapters └─ Claude / Codex / Gemini / Cursor / OpenCode / OpenClaw / Process / HTTP

3-2. 저장소 구조

paperclip/
├── ui/           # React 프론트엔드
├── server/       # Express API 서버
├── packages/     # db/shared/adapter-utils/adapters
├── skills/       # 에이전트가 사용할 스킬
├── cli/          # setup/control-plane CLI
└── doc/          # 내부 개발 문서

3-3. 핵심 개념

개념	설명
Company	최상위 단위. 목표, 직원(에이전트), 조직도, 예산, 태스크 계층이 모두 회사 아래에 묶인다.
Agent	직원 역할을 하는 AI. 어댑터 종류, 역할, 보고 체계, 예산, 상태를 가진다.
Issue(Task)	실제 작업 단위. 제목, 설명, 상태, 우선순위, 담당자, 부모 태스크, 프로젝트/목표 연결을 가진다.
Heartbeat	에이전트가 짧은 실행 윈도로 깨어나 할당된 일을 처리하는 실행 사이클이다.
Approval	채용, CEO 전략 승인 등 핵심 결정에 대해 보드(사람)가 승인하거나 수정 요청할 수 있는 게이트다.
Goal	왜 이 일을 하는지에 대한 상위 목적이다. 회사 목표 → 팀 목표 → 에이전트 수준 목표로 이어진다.
Project / Workspace	프로젝트는 산출물 단위이며, 워크스페이스는 특정 저장소/디렉터리와 연결된다. 에이전트는 기본 워크스페이스를 작업 디렉터리로 사용한다.

3-4. Heartbeat 흐름

스케줄/할당/@멘션/수동 실행/승인 해결로 에이전트가 깨어난다.
Paperclip이 해당 에이전트의 어댑터를 호출한다.
어댑터가 로컬 CLI 또는 외부 런타임을 실행한다.
에이전트는 API를 호출해 할당 작업을 확인하고 checkout한 뒤 상태를 갱신한다.
어댑터가 stdout, 비용, 세션 상태를 수집한다.
Paperclip이 실행 기록과 비용 데이터를 저장한다.

참고: Architecture, Core Concepts, How Agents Work, Goals and Projects

4. 설치 전 준비사항

필수 준비

Node.js 20 이상
pnpm 9 이상 (문서상 9+, README/package.json 기준 9.15 계열)
로컬 개발 시 macOS/Linux/Windows 터미널 접근

선택 준비

Docker / Docker Compose
Claude/Codex/Gemini 등을 실제로 돌릴 API 키
사설 네트워크 접속 시 Tailscale/VPN/LAN
프로덕션 배포 시 외부 PostgreSQL 및 S3 호환 스토리지

에이전트 실행에 자주 필요한 키

키	주로 쓰는 곳
`ANTHROPIC_API_KEY`	`claude_local` 어댑터
`OPENAI_API_KEY`	`codex_local` 어댑터
`GEMINI_API_KEY` / `GOOGLE_API_KEY`	`gemini_local` 어댑터

빠르게 써보는 목적이라면 먼저 서버만 띄우고, 나중에 어댑터별 API 키를 넣는 방식이 가장 수월하다. Docker로 서버/UI를 먼저 확인한 뒤 어댑터 테스트를 붙여도 된다.

참고: Quickstart, Local Development, Docker, Claude Local, Codex Local, Gemini Local, package.json

5. 설치 방법

5-1. 가장 쉬운 방법: 빠른 온보딩

공식 Quickstart에서 권장하는 첫 실행 경로다.

npx paperclipai onboard --yes

이 경로는 기본 설정을 잡아 주고, 빠르게 로컬 인스턴스를 올리는 데 적합하다. 이미 설정이 있는 상태에서 다시 실행해도 기존 구성을 유지하는 쪽으로 동작한다.

5-2. 저장소를 클론해서 직접 실행

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

이 방식은 개발자 관점에서 가장 유리하다. API 서버와 UI가 http://localhost:3100에서 동작하고, 기본적으로 외부 DB 없이 내장 PostgreSQL을 사용한다.

5-3. 저장소 안에서 one-command bootstrap

pnpm paperclipai run

이 명령은 설정이 없으면 자동 온보딩을 하고, doctor를 자동 수리 옵션과 함께 실행한 뒤 서버를 시작한다. 로컬 repo를 직접 다루는 경우 특히 편하다.

5-4. Docker Compose Quickstart

docker compose -f docker-compose.quickstart.yml up --build

브라우저에서 http://localhost:3100를 열면 된다.

포트/데이터 경로 오버라이드

PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=./data/pc \
docker compose -f docker-compose.quickstart.yml up --build

5-5. 수동 Docker 실행

docker build -t paperclip-local .
docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -v "$(pwd)/data/docker-paperclip:/paperclip" \
  paperclip-local

컨테이너 안에서 Claude/Codex 로컬 어댑터까지 쓰려면

docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -e OPENAI_API_KEY=sk-... \
  -e ANTHROPIC_API_KEY=sk-... \
  -v "$(pwd)/data/docker-paperclip:/paperclip" \
  paperclip-local

Docker로 서버가 뜬다고 해서 모든 어댑터가 자동으로 준비되는 것은 아니다. 어댑터별 CLI 설치 여부와 API 키는 별도로 점검해야 한다.

참고: README Quickstart, Quickstart, Local Development, Docker, Setup Commands

6. 설치 후 기본 설정과 CLI

6-1. 먼저 확인할 것

curl http://localhost:3100/api/health
# {"status":"ok"}

curl http://localhost:3100/api/companies
# []

6-2. 자주 쓰는 CLI 명령

명령	용도
`pnpm paperclipai run`	자동 온보딩 + doctor + 서버 시작
`pnpm paperclipai onboard`	처음 설치용 인터랙티브 설정
`pnpm paperclipai onboard --yes`	기본값으로 빠르게 시작
`pnpm paperclipai doctor`	구성, DB, 시크릿, 저장소 등 점검
`pnpm paperclipai doctor --repair`	문제 자동 수리 시도
`pnpm paperclipai configure --section server`	서버/배포 모드 변경
`pnpm paperclipai configure --section secrets`	시크릿 설정 변경
`pnpm paperclipai configure --section storage`	스토리지 설정 변경
`pnpm paperclipai env`	현재 환경 해석 결과 확인
`pnpm paperclipai allowed-hostname my-host`	private/authenticated 모드에서 사설 호스트 허용

6-3. 설정 저장 위치

데이터	기본 경로
Config	`~/.paperclip/instances/default/config.json`
Database	`~/.paperclip/instances/default/db`
Storage	`~/.paperclip/instances/default/data/storage`
Secrets key	`~/.paperclip/instances/default/secrets/master.key`
Logs	`~/.paperclip/instances/default/logs`

6-4. 자주 쓰는 환경 변수

변수	설명
`PORT`	기본 포트. 기본값은 3100.
`HOST`	호스트 바인딩. 로컬은 기본적으로 127.0.0.1.
`DATABASE_URL`	외부 PostgreSQL 연결 문자열. 없으면 임베디드 모드 사용.
`PAPERCLIP_HOME`	모든 Paperclip 데이터의 루트 디렉터리.
`PAPERCLIP_INSTANCE_ID`	로컬 다중 인스턴스 구분용 ID.
`PAPERCLIP_DEPLOYMENT_MODE`	런타임 모드 오버라이드.
`PAPERCLIP_SECRETS_MASTER_KEY`	시크릿 암호화 키.
`PAPERCLIP_SECRETS_MASTER_KEY_FILE`	시크릿 키 파일 경로.
`PAPERCLIP_SECRETS_STRICT_MODE`	민감한 값의 inline 입력을 막고 secret ref를 강제.

6-5. 인스턴스를 분리해서 쓰고 싶다면

PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run

# 또는 임시 데이터 루트
pnpm paperclipai run --data-dir ./tmp/paperclip-dev

참고: Local Development, Environment Variables, Setup Commands, CLI Overview, Secrets Management

7. 첫 회사 만들기와 실전 활용 흐름

Paperclip의 활용은 “앱 켜기”로 끝나지 않는다. 실제 가치는 회사와 에이전트를 어떻게 설계하느냐에서 나온다. 공식 문서 흐름을 기반으로 가장 실용적인 시작 순서를 정리하면 아래와 같다.

7-1. 가장 권장되는 첫 실행 시나리오

회사 생성: 이름과 설명을 입력한다.
최상위 Goal 생성: 회사 존재 이유를 수치/기간 포함 형태로 정의한다.
CEO 에이전트 생성: 보통 Claude Local 같은 범용 어댑터로 시작한다.
조직도 확장: CTO, CMO, 연구원, 엔지니어를 보고 체계로 연결한다.
예산 설정: 회사 전체 예산 + 에이전트별 월 예산을 넣는다.
초기 태스크 생성: 목표를 프로젝트/상위 이슈/하위 이슈로 쪼갠다.
Heartbeat 활성화: 실제 작업을 돌리고, 대시보드와 승인 큐를 모니터링한다.

7-2. 추천 조직도 예시

Board (사람) └── CEO ├── CTO │ ├── EngineeringLead │ │ ├── BackendEngineer │ │ └── FrontendEngineer │ └── QAEngineer └── CMO ├── ContentResearcher └── GrowthAnalyst

7-3. 좋은 Goal 예시

“3개월 안에 AI 메모 앱 MVP를 출시하고 유료 사용자 100명을 확보한다.”
“Q2 안에 AI 마케팅 에이전시 프로세스를 표준화하고 첫 10개 고객사 대응을 자동화한다.”

7-4. 태스크를 잘 만드는 법

좋은 방식	피해야 할 방식
하나의 이슈가 명확한 완료 기준을 가진다.	“제품 잘 만들어”처럼 범위가 너무 넓다.
부모 이슈를 연결해 상위 목표를 추적한다.	Goal/Project 없이 태스크만 흩어 놓는다.
담당 에이전트가 하나다.	여러 에이전트가 동시에 같은 태스크를 암묵적으로 잡는다.
막히면 댓글과 상태 변경으로 드러낸다.	조용히 멈춘 채 오래 방치한다.

7-5. 실전 첫 10분 체크리스트

Quickstart나 Docker로 서버/UI를 띄운다.
회사를 하나 만들고 Top-level Goal을 정의한다.
CEO를 만든 뒤 어댑터 환경 테스트를 통과시킨다.
CEO 예산을 충분히 잡는다.
CTO와 Engineer를 1~2명만 먼저 두고 작은 조직으로 시작한다.
태스크 3~5개만 넣는다.
대시보드에서 blocked / stale / budget 상태를 바로 확인한다.

참고: Creating a Company, Managing Agents, Org Structure, Managing Tasks, Dashboard

8. 어댑터 선택과 활용법

Paperclip의 강점은 특정 모델에 종속되지 않는다는 점이다. 즉, Paperclip 자체가 LLM이 아니라 각종 에이전트 런타임을 붙이는 오케스트레이터다.

8-1. 기본 제공 어댑터

어댑터	키	언제 쓰면 좋은가
Claude Local	`claude_local`	범용 코딩 에이전트. 세션 지속성과 skills injection을 원할 때.
Codex Local	`codex_local`	OpenAI Codex CLI 기반 코딩 작업에 적합.
Gemini Local	`gemini_local`	Gemini CLI를 로컬에서 돌릴 때.
OpenCode Local	`opencode_local`	멀티 프로바이더 모델 조합이 필요할 때.
Cursor Local	`cursor`	Cursor CLI 연동이 필요할 때.
OpenClaw Gateway	`openclaw_gateway`	OpenClaw를 게이트웨이 방식으로 호출할 때.
Hermes / Pi Local	`hermes_local`, `pi_local`	해당 CLI 런타임을 이미 운영 중일 때.
Process	`process`	파이썬 스크립트나 커스텀 쉘 명령을 직접 실행하고 싶을 때.
HTTP	`http`	외부 서비스/클라우드 함수에 webhook으로 위임하고 싶을 때.

8-2. 어떤 어댑터를 고를까?

가장 무난한 시작

Claude Local 또는 Codex Local. 설정이 비교적 명확하고, 세션 지속이 있어 장기 작업에 잘 맞는다.

내가 만든 봇을 연결

Process. Python/Node 스크립트가 Paperclip API를 직접 호출하는 구조로 만들면 된다.

외부 런타임 사용

HTTP. 이미 클라우드에 에이전트를 띄워 두었다면 webhook 트리거 방식이 가장 단순하다.

8-3. Claude Local 예시

{
  "adapterType": "claude_local",
  "adapterConfig": {
    "cwd": "/absolute/path/to/workspace",
    "model": "claude-opus-4-6",
    "promptTemplate": "You are the CTO. Review company health, delegate work, and leave concise updates.",
    "timeoutSec": 600,
    "graceSec": 30
  }
}

전제: claude CLI가 설치되어 있고, 인증이 되어 있어야 한다.

8-4. Codex Local 예시

{
  "adapterType": "codex_local",
  "adapterConfig": {
    "cwd": "/absolute/path/to/workspace",
    "model": "gpt-5-codex",
    "promptTemplate": "You are an engineering lead. Pick the highest priority issue and update status clearly.",
    "timeoutSec": 600
  }
}

8-5. Gemini Local 예시

{
  "adapterType": "gemini_local",
  "adapterConfig": {
    "cwd": "/absolute/path/to/workspace",
    "model": "auto",
    "promptTemplate": "You are a researcher. Summarize findings and create follow-up tasks when needed.",
    "timeoutSec": 600,
    "yolo": false
  }
}

8-6. Process 어댑터 예시

{
  "adapterType": "process",
  "adapterConfig": {
    "command": "python3 /path/to/agent.py",
    "cwd": "/path/to/workspace",
    "timeoutSec": 300
  }
}

이 경우 스크립트는 Paperclip이 주입한 PAPERCLIP_AGENT_ID, PAPERCLIP_API_URL, PAPERCLIP_API_KEY 등을 이용해 API를 호출하면 된다.

8-7. HTTP 어댑터 예시

{
  "adapterType": "http",
  "adapterConfig": {
    "url": "https://my-agent.example.com/wake",
    "headers": {
      "X-Service-Token": "..."
    },
    "timeoutSec": 60
  }
}

HTTP 어댑터는 Paperclip이 외부 서비스에 실행 컨텍스트를 POST하고, 실제 작업은 외부 에이전트가 다시 Paperclip API에 콜백하는 구조다.

8-8. 운영 팁

처음에는 1~2개 어댑터만 써라. 너무 많은 런타임을 한 번에 붙이면 디버깅이 어렵다.
에이전트를 만들 때는 반드시 Test Environment를 먼저 통과시켜라.
cwd는 절대 경로를 쓰는 편이 안정적이다.
세션 지속이 중요한 장기 작업에는 claude_local/codex_local/gemini_local이 유리하다.

참고: Adapters Overview, Claude Local, Codex Local, Gemini Local, Process Adapter, HTTP Adapter

9. 운영 패턴: 태스크·승인·예산·대시보드

9-1. 태스크 운영의 핵심 규칙

작업 전 checkout 필수: 태스크를 in_progress로 바꾸기 전에 checkout해야 한다.
동시 작업 방지: 같은 태스크를 다른 에이전트가 먼저 잡으면 409 Conflict가 난다. 재시도하지 말고 다른 태스크를 골라야 한다.
댓글이 기본 커뮤니케이션: 진행 상황, 막힘, 핸드오프를 댓글로 남긴다.
@멘션은 실행 비용: @멘션은 상대 에이전트를 깨우므로 무분별하게 쓰지 않는다.
부모 태스크 유지: 하위 작업을 쪼갤 때는 항상 부모 관계를 넣어 “왜 하는지”를 잃지 않는다.

9-2. 상태 라이프사이클

backlog -> todo -> in_progress -> in_review -> done | | blocked ----------------------+ terminal: done, cancelled

9-3. 댓글과 @멘션 활용

POST /api/issues/{issueId}/comments
{ "body": "@EngineeringLead I need a review on this implementation." }

댓글은 가장 중요한 운영 기록이다. 상태만 바꾸고 설명이 없으면 나중에 원인을 추적하기 어렵다.

9-4. 승인(Approvals)

승인 유형	의미
`hire_agent`	매니저나 CEO가 새로운 부하 에이전트를 채용하려고 할 때
CEO strategy approval	CEO가 초반 전략 계획을 실행하기 전에 보드 승인을 받을 때

상태는 대체로 pending → approved/rejected 흐름이며, 수정 요청 후 재제출도 가능하다.

9-5. 예산과 비용 관리

구간	동작
80%	경고. 중요한 작업 위주로 집중하도록 유도.
100%	하드 스톱. 에이전트가 자동 pause 된다.

비용 이벤트는 어댑터가 모델, 입력 토큰, 출력 토큰, 금액을 파싱해서 서버로 보고한다.

9-6. 대시보드에서 꼭 봐야 할 것

Blocked tasks: 승인이나 개입이 필요한 지점이다.
Stale work: 오래 업데이트가 없는 작업은 stuck 가능성이 높다.
Budget utilization: 80%를 넘는 에이전트는 우선순위를 재조정해야 한다.
Recent activity: 누가 어떤 변경을 했는지 전체 흐름을 파악할 수 있다.

9-7. Activity Log의 가치

Paperclip은 변경 이력을 강하게 남긴다. 에이전트 생성/수정/중지, 이슈 상태 변경, 코멘트, 승인 처리, 예산 변경 등이 모두 activity log에 남는다. 무슨 일이 일어났는지 복기할 때 가장 먼저 봐야 할 화면이 activity log다.

참고: Managing Tasks, Comments and Communication, Approvals, Costs and Budgets, Dashboard, Activity Log, Heartbeat Protocol

10. API와 CLI 실전 예시

10-1. API 기본 규칙

기본 API 경로는 http://localhost:3100/api
인증은 Authorization: Bearer <token>
Heartbeat 중 상태 변경 요청은 X-Paperclip-Run-Id 헤더를 넣는 것이 권장/필수 흐름이다.
409는 누군가가 작업을 선점한 상태라는 뜻이다.

10-2. Goal 만들기

curl -X POST http://localhost:3100/api/companies/$COMPANY_ID/goals \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch MVP by Q1",
    "description": "Ship minimum viable product",
    "level": "company",
    "status": "active"
  }'

10-3. Issue 만들기

curl -X POST http://localhost:3100/api/companies/$COMPANY_ID/issues \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement caching layer",
    "description": "Add Redis caching for hot queries",
    "status": "todo",
    "priority": "high",
    "assigneeAgentId": "'"$AGENT_ID"'",
    "projectId": "'"$PROJECT_ID"'",
    "goalId": "'"$GOAL_ID"'"
  }'

10-4. 작업 checkout

curl -X POST http://localhost:3100/api/issues/$ISSUE_ID/checkout \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Paperclip-Run-Id: $RUN_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "'"$AGENT_ID"'",
    "expectedStatuses": ["todo", "backlog", "blocked"]
  }'

10-5. 작업 완료 처리 + 댓글

curl -X PATCH http://localhost:3100/api/issues/$ISSUE_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Paperclip-Run-Id: $RUN_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done",
    "comment": "Implemented caching with 90% hit rate."
  }'

10-6. 문서/아티팩트 관리

이슈는 단순 댓글만이 아니라 텍스트 문서와 파일 첨부도 가질 수 있다.

# keyed document 예시
PUT /api/issues/{issueId}/documents/plan
{
  "title": "Implementation plan",
  "format": "markdown",
  "body": "# Plan\n\n...",
  "baseRevisionId": "{latestRevisionId}"
}

10-7. CLI로도 많이 할 수 있다

# 이슈 목록
pnpm paperclipai issue list --status todo,in_progress

# 이슈 생성
pnpm paperclipai issue create --title "..." --description "..." --priority high

# 이슈 상세
pnpm paperclipai issue get <issue-id>

# 코멘트
pnpm paperclipai issue comment <issue-id> --body "Working on it"

# approval 목록
pnpm paperclipai approval list --status pending

# dashboard 조회
pnpm paperclipai dashboard get

# 특정 agent heartbeat 수동 실행
pnpm paperclipai heartbeat run --agent-id <agent-id> --api-base http://localhost:3100

10-8. 회사 export / import

# 회사 export
pnpm paperclipai company export <company-id> \
  --out ./exports/acme \
  --include company,agents

# import dry-run
pnpm paperclipai company import \
  --from ./exports/acme \
  --target new \
  --new-company-name "Acme Imported" \
  --include company,agents \
  --dry-run

참고: API Overview, Issues API, Goals and Projects API, Control-Plane Commands, latest release notes

11. 배포·보안·운영 전략

11-1. 배포 모드 선택

모드	언제 쓰는가
`local_trusted`	혼자 로컬에서 실험. 로그인 없이 빠르게 시작.
`authenticated + private`	Tailscale/VPN/LAN으로 팀이 접근하는 경우.
`authenticated + public`	인터넷에 공개된 클라우드 배포.

11-2. 모드 전환

pnpm paperclipai configure --section server

또는 런타임 오버라이드:

PAPERCLIP_DEPLOYMENT_MODE=authenticated pnpm paperclipai run

11-3. private 모드에서 Tailscale 호스트 허용

pnpm dev --tailscale-auth
pnpm paperclipai allowed-hostname my-machine

11-4. DB 선택 전략

방식	언제 적합한가
임베디드 PostgreSQL	개발/테스트/혼자 쓰는 인스턴스
로컬 PostgreSQL (Docker)	개발이지만 DB를 명시적으로 분리하고 싶을 때
외부 Hosted PostgreSQL	프로덕션, 팀 운영, 지속 배포 환경

외부 DB를 쓰려면

cp .env.example .env
# DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip

11-5. 스토리지 선택 전략

Provider	추천 시나리오
`local_disk`	단일 머신 로컬 운영
`s3`	프로덕션, 멀티 노드, 클라우드

스토리지 설정 변경

pnpm paperclipai configure --section storage

11-6. 시크릿 관리

Paperclip은 기본적으로 로컬 마스터 키로 시크릿을 암호화해 저장한다. 민감한 env 값은 secret reference 형태로 보관할 수 있고, strict mode를 켜면 *_API_KEY, *_TOKEN, *_SECRET 패턴 값을 inline으로 넣는 것을 막을 수 있다.

pnpm paperclipai configure --section secrets
pnpm paperclipai doctor

# 배포 환경에서는 권장
PAPERCLIP_SECRETS_STRICT_MODE=true

11-7. local_trusted → authenticated 전환 시 주의

문서상 이 전환 과정에서는 일회성 claim URL이 발급되어, 로그인한 사용자가 보드 소유권을 가져가는 흐름이 있다. 로컬 초기 관리자와 실제 운영 계정을 분리할 때 알아 두면 좋다.

참고: Deployment Overview, Deployment Modes, Local Development, Database, Storage, Secrets Management

12. 확장: 커스텀 어댑터 작성

Paperclip은 특정 런타임에 잠겨 있지 않다. 공식 문서에 따르면 어댑터는 server / ui / cli 세 모듈을 가진 패키지로 만들 수 있다.

packages/adapters/<name>/
  package.json
  tsconfig.json
  src/
    index.ts
    server/
      index.ts
      execute.ts
      parse.ts
      test.ts
    ui/
      index.ts
      parse-stdout.ts
      build-config.ts
    cli/
      index.ts
      format-event.ts

핵심 작성 순서

Root Metadata: type, label, models, 문서 문자열 정의
Server Execute: 실제 런타임 호출, 프롬프트 렌더링, stdout/cost/session 파싱
Environment Test: 설치/인증/경로/실행 가능 여부 점검
UI Module: stdout를 transcript로 바꾸고 설정 폼을 제공
CLI Module: 터미널용 포매터 작성
Registry 등록: server/ui/cli registry에 추가

확장할 때 기억할 점

에이전트 출력은 신뢰하지 말고 방어적으로 파싱한다.
시크릿은 프롬프트가 아니라 환경 변수로 주입한다.
타임아웃과 grace period를 항상 둔다.
가능하면 skills를 작업 디렉터리를 오염시키지 않는 방식으로 주입한다.

이미 사내 파이썬 에이전트나 자체 런타임이 있다면, 처음부터 깊은 통합을 하기보다 Process 또는 HTTP 어댑터로 빠르게 연결한 뒤, 필요할 때 전용 어댑터를 만드는 전략이 현실적이다.

참고: Creating an Adapter, Architecture, Adapters Overview

13. 최신 릴리스 하이라이트

2026-03-25 기준 최신 릴리스 v2026.325.0에서 눈에 띄는 변화는 다음과 같다.

Company import/export: 회사 구성을 내보내고 다시 들여오는 기능이 강화되었다.
Company skills library: 회사 범위의 스킬 관리 기능이 추가/강화되었다.
Routines / recurring tasks: 반복 작업과 루틴 엔진이 발전했다.
CLI auth 개선: 브라우저 기반 인증 흐름이 추가되었다.
Docker image CI: Docker 이미지 빌드/배포 쪽도 정비되었다.

릴리스 속도가 빠르기 때문에, 실제 운영에 들어가기 전에는 현재 설치하려는 버전의 release note를 한 번 더 읽는 것이 좋다.

참고: GitHub Releases - v2026.325.0

14. 트러블슈팅 체크리스트

14-1. 서버 자체가 안 뜰 때

pnpm paperclipai doctor --repair 실행
curl http://localhost:3100/api/health 확인
pnpm paperclipai env로 해석된 설정 확인
포트/호스트/DB 설정 충돌 여부 확인

14-2. 로컬 데이터를 초기화하고 싶을 때

rm -rf ~/.paperclip/instances/default/db
pnpm dev

14-3. 어댑터가 실행되지 않을 때

해당 CLI 명령(claude, codex, gemini)이 실제로 PATH에 있는지 확인
API 키 또는 로컬 인증 상태 확인
Agent detail 페이지에서 Test Environment를 먼저 통과
cwd를 절대 경로로 지정했는지 확인

14-4. 태스크가 진행되지 않을 때

담당 에이전트가 paused 상태가 아닌지 확인
예산 100% 초과로 자동 pause 되었는지 확인
승인이 필요한 흐름인지 approval queue 확인
activity log와 recent comments를 함께 읽어 blocker를 확인

14-5. 409 Conflict가 반복될 때

이는 설계상 정상적인 보호장치다. 같은 태스크를 다른 에이전트가 이미 checkout했다는 뜻이므로, 재시도 루프를 돌리지 말고 다른 태스크를 고르거나 상위 매니저에게 에스컬레이션해야 한다.

14-6. @멘션이 너무 많아 비용이 늘 때

댓글 멘션 하나가 곧 wake trigger이므로, 할당은 태스크 생성/배정으로 하고 멘션은 진짜 협업 신호에만 쓰는 것이 좋다.

참고: Local Development, Setup Commands, Managing Agents, Costs and Budgets, Comments and Communication, Heartbeat Protocol

15. 결론과 추천 사용 시나리오

가볍게 체험

npx paperclipai onboard --yes로 빠르게 올리고, 한 회사 + CEO + CTO 정도만 만들어 대시보드 흐름을 익힌다.

실전 개발팀 운영

로컬 혹은 Tailscale private 모드로 배포하고, 프로젝트/워크스페이스를 실제 Git 저장소에 연결해서 엔지니어링 태스크를 자동화한다.

고급 자동화

Process/HTTP 또는 커스텀 어댑터로 사내 에이전트 플랫폼과 연결하고, 승인/예산/감사 로그를 운영 규칙으로 삼는다.

정리하면, Paperclip은 “AI 여러 개를 돌리는 툴”이 아니라 AI 인력 조직을 운영하는 오픈소스 제어 평면이다. 단순 자동화보다 조직 구조, 작업 체크아웃, 승인 게이트, 예산 강제, 감사 로그가 중요할수록 진가가 커진다.

처음에는 회사 1개, CEO 1명, 기술 리드 1명, 작은 태스크 3~5개로 시작하라. Paperclip의 가치는 대규모 에이전트 수보다 운영 규율을 강제하는 구조에서 먼저 드러난다.

16. 공식 출처

아래 링크는 이 문서를 정리할 때 우선 사용한 공식 GitHub/공식 문서다.

'AI' 카테고리의 다른 글

OpenClaw 플러그인 추천 10선: 생산성·보안·메모리 확장까지 실전 가이드 (1)	2026.03.18
OpenClaw 사용 사례 10가지: AI 개인 비서 자동화 실전 활용법 총정리 (0)	2026.03.18
OpenClaw 사용기: 실제 AI 개인 비서 자동화 경험과 설정 방법 총정리 (0)	2026.03.18

Paperclip 완전 가이드: 설치부터 Docker·API·어댑터·운영 전략까지 한눈에 보는 paperclipai/paperclip

1. 저장소 스냅샷

프로젝트 정체성

현재 공개 상태

문서 범위

2. Paperclip이 무엇인지

이런 경우에 잘 맞는다

이런 경우엔 과할 수 있다

3. 아키텍처와 핵심 개념

3-1. 전체 아키텍처

3-2. 저장소 구조

3-3. 핵심 개념

3-4. Heartbeat 흐름

4. 설치 전 준비사항

필수 준비

선택 준비

에이전트 실행에 자주 필요한 키

5. 설치 방법

5-1. 가장 쉬운 방법: 빠른 온보딩

5-2. 저장소를 클론해서 직접 실행

5-3. 저장소 안에서 one-command bootstrap

5-4. Docker Compose Quickstart

포트/데이터 경로 오버라이드

5-5. 수동 Docker 실행

컨테이너 안에서 Claude/Codex 로컬 어댑터까지 쓰려면

6. 설치 후 기본 설정과 CLI

6-1. 먼저 확인할 것

6-2. 자주 쓰는 CLI 명령

6-3. 설정 저장 위치

6-4. 자주 쓰는 환경 변수

6-5. 인스턴스를 분리해서 쓰고 싶다면

7. 첫 회사 만들기와 실전 활용 흐름

7-1. 가장 권장되는 첫 실행 시나리오

7-2. 추천 조직도 예시

7-3. 좋은 Goal 예시

7-4. 태스크를 잘 만드는 법

7-5. 실전 첫 10분 체크리스트

8. 어댑터 선택과 활용법

8-1. 기본 제공 어댑터

8-2. 어떤 어댑터를 고를까?

가장 무난한 시작

내가 만든 봇을 연결

외부 런타임 사용

8-3. Claude Local 예시

8-4. Codex Local 예시

8-5. Gemini Local 예시

8-6. Process 어댑터 예시

8-7. HTTP 어댑터 예시

8-8. 운영 팁

9. 운영 패턴: 태스크·승인·예산·대시보드

9-1. 태스크 운영의 핵심 규칙

9-2. 상태 라이프사이클

9-3. 댓글과 @멘션 활용

9-4. 승인(Approvals)

9-5. 예산과 비용 관리

9-6. 대시보드에서 꼭 봐야 할 것

9-7. Activity Log의 가치

10. API와 CLI 실전 예시

10-1. API 기본 규칙

10-2. Goal 만들기

10-3. Issue 만들기

10-4. 작업 checkout

10-5. 작업 완료 처리 + 댓글

10-6. 문서/아티팩트 관리

10-7. CLI로도 많이 할 수 있다

10-8. 회사 export / import

11. 배포·보안·운영 전략

11-1. 배포 모드 선택

11-2. 모드 전환

11-3. private 모드에서 Tailscale 호스트 허용

11-4. DB 선택 전략

외부 DB를 쓰려면

11-5. 스토리지 선택 전략

스토리지 설정 변경

11-6. 시크릿 관리

11-7. local_trusted → authenticated 전환 시 주의

12. 확장: 커스텀 어댑터 작성

핵심 작성 순서

확장할 때 기억할 점

13. 최신 릴리스 하이라이트