Paperclip: AI 에이전트 팀을 위한 오픈 소스 오케스트레이션

Quickstart · Docs · GitHub · Discord · Twitter · Website

full-tour.webm

AI 에이전트 팀을 위한 오픈 소스 오케스트레이션.

OpenClaw가 직원이면, Paperclip은 그 회사의 시스템입니다.

Paperclip은 비즈니스를 운영하는 AI 에이전트 팀을 오케스트레이션하는 Node.js 서버 및 React UI입니다. 자체 에이전트를 가져와 목표를 할당하고, 하나의 대시보드에서 작업과 비용을 추적할 수 있습니다. 각 에이전트에 맞는 모델과 하네스(harness)를 선택하면서도 팀의 작업, 기술, 권한, 이력을 한 곳에 보관할 수 있습니다.

이는 태스크 매니저처럼 보입니다. 하지만 내부적으로는 조직도(org charts), 예산(budgets), 거버넌스(governance), 목표 정렬(goal alignment), 그리고 에이전트 코디네이션을 처리합니다.

풀 리퀘스트가 아닌, 비즈니스 목표를 관리하세요.

다음과 함께 작동합니다 |
OpenClaw | Claude Code | Codex | Cursor+ Cloud | Gemini CLI | OpenCode | Pi | Hermes+ Gateway | Grok Build | Kimi Code |

심장 박동(heartbeat)을 받을 수 있다면, 고용된 것입니다.

커스텀 프로세스, HTTP 엔드포인트, 외부 어댑터 패키지를 통해 로스터를 확장할 수 있습니다. 설정 및 기능에 대한 내용은 어댑터 개요(adapter overview)를 참조하세요.

• ✅ 자율적인 AI 조직을 구축하고 싶다 - ✅ 공통 목표를 향해 여러 다른 에이전트(OpenClaw, Codex, Claude, Cursor)를 코디네이션해야 한다 - ✅ 동시에 20개의 Claude Code 터미널을 열고 모두가 무엇을 하는지 놓치고 싶지 않다 - ✅ 에이전트가 24/7 자율적으로 작동하길 원하지만, 여전히 작업을 감사하고 필요할 때 개입하고 싶다 - ✅ 비용을 모니터링하고 예산을 강제하고 싶다 - ✅ 마치 태스크 매니저를 사용하는 것처럼 느껴지는 에이전트 관리 프로세스를 원한다 - ✅ 휴대폰에서 자율적인 비즈니스를 관리하고 싶다

AI 에이전트 조직이 실제로 결과물을 내기 위해서는 네 가지 요소가 작동해야 합니다. 바로 태스크(tasks), 조직(org), 학습(training), 그리고 인프라(infrastructure)입니다. Paperclip은 정확히 이 네 가지 기둥을 중심으로 구축되었습니다.

어떤 에이전트든, 어떤 런타임 환경이든, 하나의 조직도(org chart)로 관리할 수 있습니다. 심장 박동(heartbeat)을 받을 수 있다면 고용 가능한 것입니다. | 작업과 프로젝트를 조직 목표에 연결하세요. 에이전트는 자신의 작업 뒤에 있는 목표 컨텍스트를 받습니다. | 에이전트는 할당된 작업, 후속 메시지 또는 설정된 스케줄에 따라 깨어납니다. 위임 흐름은 조직도 상하로 이동합니다. |
| 회사, 에이전트, 프로젝트 예산. 보고된 지출을 추적하고, 임계값 알림을 받고, 설정된 한도에서 작업을 일시 중지할 수 있습니다. | 하나의 배포(deployment)로 여러 조직 관리. 각 조직별로 작업, 에이전트, 권한 및 활동 기록을 분리합니다. | 대화, 계획, 장애물(blockers), 파일 및 실행 기록을 작업에 첨부하세요. 에이전트나 사람에게 작업을 할당할 수 있습니다. |
| 검토 및 승인 단계를 구성하고, 채용을 승인하며, 필요할 때 작업을 일시 중지하거나 재할당 또는 중단할 수 있습니다. | 계층 구조(Hierarchies), 역할(roles), 보고 라인(reporting lines). 에이전트에게는 상사, 직함, 그리고 직무 설명서가 있습니다. | 어디서든 자율적인 비즈니스를 모니터링하고 관리하세요. |
| ... |
실험적인 에이전트 채팅(Agent Chat) 및 **채팅/이메일 커넥터(chat/email connectors)**를 통해 Paperclip 내에서 에이전트와의 대화는 물론, Slack, Discord, Telegram, AgentMail 등 설정된 서비스를 통해서도 가능합니다. 관련 인스턴스 설정을 활성화하여 사용해 보세요.

원자적 태스크 체크아웃(Atomic task checkout). | 단일 할당자와 실행 잠금(execution locks)이 경쟁하는 실행이 동일한 태스크를 차지하는 것을 방지합니다. | 영속적인 작업 컨텍스트(Persistent work context). | 태스크, 댓글 및 문서는 Paperclip에 유지됩니다. 지원 어댑터는 여러 실행에 걸쳐 저장된 세션을 재개합니다. | 런타임 스킬 주입(Runtime skill injection). | 에이전트는 재훈련 없이도 런타임에서 Paperclip 워크플로우와 프로젝트 컨텍스트를 학습할 수 있습니다. | 롤백을 통한 거버넌스(Governance with rollback). | 승인 게이트가 적용되며, 설정 변경 사항은 버전 관리되고, 잘못된 변경 사항은 안전하게 롤백될 수 있습니다. | 책임 있는 연결(Accountable connections). | 인간 접근, 에이전트 적격성, 게이트웨이 작업 권한이 분리된 제어 기능을 가집니다. 한 번 통화를 승인하거나 취소 가능한 규칙을 저장할 수 있습니다. | 목표 인식 실행(Goal-aware execution). | 연결된 태스크와 프로젝트는 목표 계보(goal ancestry)를 가지고 있어 에이전트가 단순히 제목뿐만 아니라 '왜' 필요한지 알게 됩니다. | 이식 가능한 회사 템플릿(Portable company templates). | 비밀 정보 제거 및 충돌 처리 기능을 통해 조직, 에이전트, 스킬을 내보내기/가져오기가 가능합니다. | 조직 경계(Organization boundaries). | 회사 범위의 접근 확인 기능은 단일 배포 환경 내에서 각 조직의 작업, 에이전트, 활동을 분리하여 유지합니다.

Paperclip은 래퍼(wrapper)가 아니라 완전한 제어 평면(full control plane)입니다. 이 모든 것을 직접 구축하기 전에, 이미 존재한다는 것을 알아두세요:

┌──────────────────────────────────────────────────────────────┐
│ PAPERCLIP SERVER │
│ │
... 

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

단순한 챗봇이 아닙니다. | 대화가 작업(tasks), 계획(plans), 결정(decisions), 그리고 결과물(outputs)에 연결되어 유지됩니다. Experimental Agent Chat은 할 일을 지정된 작업으로 넘겨 처리할 수 있습니다. | 에이전트 프레임워크도 아닙니다. | 저희는 에이전트를 어떻게 구축해야 하는지 알려드리지 않습니다. 그 에이전트로 구성된 회사를 어떻게 운영하는지 알려드립니다. | 단순한 워크플로우 빌더도 아닙니다. | 루틴(Routines)과 실험적인 파이프라인은 역할, 목표, 예산, 거버넌스(governance)를 가진 조직 내에서 작동합니다. | 프롬프트 관리자도 아닙니다. | 에이전트는 자체적인 프롬프트, 모델, 런타임(runtimes)을 가져옵니다. Paperclip은 그들이 일하는 조직을 관리합니다. | 하나의 에이전트에 국한되지 않습니다. | 하나의 에이전트로 시작하여 공유된 기술, 위임, 검토가 있는 팀으로 성장할 수 있습니다. | 코드 리뷰에만 사용되는 것도 아닙니다. | 코딩 및 PR(Pull Request) 리뷰는 연구, 운영, 콘텐츠 및 기타 작업과 함께 수행될 수 있습니다.

오픈 소스입니다. 자체 호스팅이 가능하며 Paperclip 계정이 필요 없습니다. 안내된 퀵스타트(quickstart)를 따라 첫 번째 에이전트를 설정해 보세요.

설치 가이드를 에이전트와 공유하세요.

Node.js 24.11 이상이 설치되어 있는 경우:

npx paperclipai@latest onboard --yes

CLI는 npm의 캐시에서 실행되며, 인스턴스 구성과 데이터는 로컬에 유지됩니다.

관리형 설치(managed installs), 고정 버전(pinned versions), 카나리 및 git-ref 설치, 업데이트, 롤백(rollback), 서비스 관리, 제거에 대한 내용은 설치 가이드를 참조하세요.

CEO 에이전트로 이미 초기화된 격리된 수동 테스트 인스턴스를 사용하려면 test-drive를 사용하세요. 이는 포그라운드에서 유지되며, 서비스를 설치하거나 첫 번째 작업을 생성하지 않고, 설정 성공 후에만 브라우저를 엽니다:

ANTHROPIC_API_KEY=... npx paperclipai test-drive
OPENAI_API_KEY=... npx paperclipai test-drive --harness codex
OPENROUTER_API_KEY=... npx paperclipai test-drive \
...

--data-dir 없이 실행할 때마다 고유하고 유지되는 임시 디렉토리를 얻게 되며, 해당 절대 경로는 시작 시 출력됩니다. --data-dir을 전달하여 재사용하거나, 초기화된 인스턴스를 열지 않으려면 --no-browser를 사용하세요. 연결된 Git 작업 트리(linked Git worktree)에서 호출될 때, test-drive

또한 해당 작업 트리에서 작업 실행을 가능하게 합니다.
자격 증명 및 재사용 동작에 대한 내용은 test-drive 가이드를 참조하세요.

문제 해결: private npm registry의 .npmrc

다음과 같이 실패하는 경우:

E404

paperclipai (또는 유사한 이름)에 대해 발생하고, 전역 ~/.npmrc를 통해 private npm 레지스트리(예: GitHub Packages)를 사용하는 경우,

npx가 public npm 레지스트리가 아닌 해당 private 레지스트리에서 paperclipai를 해결할 수 있습니다. 진단:

npm config get registry

작업 방안 (이 명령에 대해 공용 npm 레지스트리를 강제합니다):

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

이제 quickstart 경로는 가장 빠른 첫 실행을 위해 기본적으로 신뢰할 수 있는 로컬 루프백 모드로 설정됩니다. 대신 인증된/private 모드에서 시작하려면, 바인드 프리셋을 명시적으로 선택하세요:

npx paperclipai@latest onboard --yes --bind lan
# 또는:

npx paperclipai@latest onboard --yes --bind tailnet

이미 Paperclip이 구성되어 있다면, onboard를 다시 실행해도 기존 설정이 유지됩니다. 설정을 편집하려면 npx paperclipai configure를 사용하세요.

또는 수동으로:

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

이것은 http://localhost:3100에서 UI와 API를 시작합니다. 임베디드 PostgreSQL 데이터베이스가 자동으로 생성되므로 설정할 필요가 없습니다.

요구 사항:
Node.js 24.11+, pnpm 9.15+

로컬 Claude 및 Codex 구독 로그인에는 Paperclip 호스트에 Python 3과 해당 제공자 CLI도 필요합니다. Docker 이미지는 이를 포함합니다.

소스 개발 시 활성화된 경우 네이티브 Paperclip Runner도 빌드됩니다(셀프 호스팅 기본값). Rust 툴체인을 설치하거나, PAPERCLIP_RUNNER_BINARY를 호환 가능한 사전 구축된 러너로 설정하세요.

Q: 이 프로젝트는 유지보수되고 있나요 아니면 그냥 임시적인가요?

A: Paperclip은 Paperclip 팀에서 유지보수하고 있습니다. 2,700개 이상의 풀 리퀘스트를 병합했습니다.

Q: 일반적인 설정은 어떻게 되나요?

Q: 일반적인 설정은 어떻게 되나요?

A: 로컬 환경에서는 단일 Node.js 프로세스가 내장된 Postgres와 로컬 파일 스토리지를 관리합니다. 프로덕션 환경에서는 사용자의 Postgres를 지정하고 원하는 방식으로 배포할 수 있습니다. 프로젝트, 에이전트, 목표를 설정하면 나머지 작업은 에이전트가 처리합니다.

원격 액세스를 위해서는 Tailscale과 같은 사설 네트워크 바인드(private-network bind)를 사용하는 인증된 모드를 사용하거나, Docker로 영구 서버를 배포할 수 있습니다. 배포 모드 및 Docker 가이드를 참고하십시오.

Q: 여러 회사를 운영할 수 있나요?

A: 예. 단일 배포에서 회사별 데이터와 접근 검사를 통해 여러 조직을 호스팅할 수 있습니다.

Q: Paperclip은 OpenClaw나 Claude Code 같은 에이전트와 어떻게 다른가요?

A: Paperclip은 그러한 에이전트를 사용합니다. 이를 회사 단위로 오케스트레이션하며, 조직도(org charts), 예산, 목표, 거버넌스, 책임 소재 등을 관리합니다.

Q: OpenClaw를 Asana나 Trello에 직접 연결하는 대신 Paperclip을 사용해야 하는 이유는 무엇인가요?

A: 에이전트 오케스트레이션에는 누가 작업을 체크아웃했는지 조정하는 방법, 세션을 유지하는 방법, 비용 모니터링, 거버넌스 확립 등 미묘한 차이가 있습니다. Paperclip이 이러한 작업들을 대신 처리해 줍니다.

(Bring-your-own-ticket-system은 로드맵에 있습니다)

Q: 에이전트는 지속적으로 작동하나요?

A: 에이전트는 할당된 작업과 후속 메시지가 있을 때 깨어나 작업을 수행합니다. 선택적 타이머 하트비트(timer heartbeats)를 통해 주기적으로 작업을 확인하게 할 수 있으며, 루틴(routines)은 자체 스케줄로 반복적인 작업을 생성합니다. OpenClaw와 같이 외부에서 실행되는 에이전트를 연결할 수도 있습니다. 단순히 언급하는 것만으로는 작업이 할당되거나 다른 에이전트가 깨어나지 않습니다.

pnpm dev # 전체 개발 (API + UI, 감시 모드)
pnpm dev:once # 파일 감시 없이 전체 개발
pnpm dev:server # 서버 전용
...

pnpm test는 Playwright를 실행하지 않습니다. 브라우저 스위트는 별도로 유지되며 일반적으로 해당 흐름을 작업하거나 CI에서만 실행됩니다.

전체 개발 가이드는 doc/DEVELOPING.md를 참고하십시오.