페이퍼클립이란? 오픈 소스 멀티 에이전트 워크플로 완벽 가이드

터미널 창이 여러 개 열리고 어느 에이전트가 어떤 작업을 처리하는지 추적하기 어렵다면, 페이퍼클립은 작업·예산·승인·지속 상태를 한곳에 모으는 가장 빠른 해법입니다.

이번 주에는 에이전트가 1~2개뿐이면 도입하지 말고, 여러 작업이 계속 실행되거나 승인이 필요하다면 테스트 서버에 페이퍼클립을 먼저 배포하십시오. 페이퍼클립 멀티 에이전트 워크플로는 단일 에이전트 프레임워크가 아니라 에이전트 팀을 관리하는 오픈 소스 제어 평면에 가깝습니다.

이 글은 여러 클로드 코드, 코덱스 또는 자체 에이전트를 함께 운영하는 개발자를 위한 내용입니다. 승인과 비용 기록이 필요한 자동화 책임자, 자체 서버에서 멀티 에이전트 워크플로를 운영하려는 팀도 대상입니다.

마지막 업데이트: 2026년 8월 14일
자료 확인: 공식 저장소, 도커 배포 문서, 데이터베이스 문서, 시크릿 관리 문서, 공식 변경 기록을 기준으로 확인했습니다.

플랫폼 역할부터 구분하기

페이퍼클립은 에이전트 자체를 새로 만드는 도구가 아닙니다. 이미 설치된 에이전트 실행 환경과 연결해 작업을 배정하고, 실행 결과와 비용 이벤트를 기록하며, 사람의 승인 절차를 관리합니다.

공식 구조에서 어댑터는 조정 계층과 에이전트 실행 환경 사이를 연결합니다. 기본 제공 어댑터에는 로컬 클로드 코드, 로컬 코덱스, 오픈코드, 커서, 셸 명령 실행 방식과 외부 에이치티티피 호출 방식이 포함됩니다. 외부 어댑터 플러그인을 추가하는 구조도 지원합니다. 자세한 연결 범위는 공식 어댑터 개요에서 확인할 수 있습니다.

페이퍼클립 오픈 소스 플랫폼은 무엇을 하는가?

핵심은 다음 네 가지입니다.

작업과 댓글을 에이전트별로 배정합니다.
프로젝트와 조직의 목표를 실행 문맥에 전달합니다.
에이전트의 지속 실행 상태와 비용 이벤트를 기록합니다.
승인 대기, 예산 제한, 중지와 재배정을 관리합니다.

따라서 질문의 초점은 “어떤 모델이 더 똑똑한가”가 아닙니다. “여러 에이전트가 동시에 움직일 때 누가 무엇을 하고 있는지 통제할 수 있는가”에 가깝습니다.

개인 개발자의 도입 기준

개인 개발자가 모든 작업에 페이퍼클립을 붙일 필요는 없습니다. 단일 저장소에서 한 번의 수정만 시키거나, 하루에 몇 차례만 에이전트를 실행한다면 터미널과 간단한 작업 보드가 더 빠릅니다.

도입 비용은 화면을 여는 데서 끝나지 않습니다. 실행 호스트를 계속 켜 두어야 하고, 에이전트 인증 상태를 관리해야 하며, 작업 실패와 승인 지연을 확인할 담당자도 필요합니다. 이 운영 부담이 에이전트 통합으로 얻는 이익보다 크면 도입을 미루는 편이 맞습니다.

다음 조건이면 개인 개발자도 시험할 가치가 있습니다.

같은 프로젝트에서 코딩 에이전트가 계속 대기합니다.
조사, 구현, 검토를 서로 다른 에이전트에 나눕니다.
이전 대화와 작업 상태를 다시 불러와야 합니다.
비용 상한이나 수동 승인 없이는 실행하기 어렵습니다.
노트북을 닫아도 작업 상태가 남아야 합니다.

반대로 임시 작업만 처리하고 작업 이력을 별도로 보관하지 않는다면, 페이퍼클립은 관리 계층이 하나 더 늘어나는 선택입니다.

코딩 팀의 작업 흐름

여러 코딩 에이전트를 터미널에서 직접 실행하면 세 가지 문제가 빠르게 나타납니다.

첫째, 세션 위치가 분리됩니다. 어떤 에이전트가 어느 브랜치와 작업 공간을 쓰는지 사람이 기억해야 합니다. 둘째, 실패한 작업의 원인과 마지막 상태를 다시 찾기 어렵습니다. 셋째, 한 에이전트가 만든 결과를 다른 에이전트가 이어받을 때 프로젝트 문맥이 누락될 수 있습니다.

페이퍼클립은 작업, 프로젝트, 에이전트와 실행 문맥을 연결하는 관리 계층을 제공합니다. 로컬 어댑터는 호스트에 설치된 명령줄 도구를 호출하는 방식입니다. 즉, 페이퍼클립을 설치했다고 클로드 코드나 코덱스가 자동으로 설치되거나 인증되는 것은 아닙니다. 공식 실행 문서도 로컬 명령줄 어댑터가 호스트에 설치되고 인증되어 있다고 전제합니다. 에이전트 실행 환경 문서에서 이 경계를 확인해야 합니다.

페이퍼클립은 클로드 코드와 코덱스를 지원하는가?

지원합니다. 다만 완전한 원격 실행 서비스로 이해하면 안 됩니다. 로컬 어댑터는 페이퍼클립이 실행되는 호스트 또는 연결된 실행 대상에서 해당 명령줄 도구를 호출합니다. 코덱스는 인증 파일과 실행 환경의 위치가 중요하고, 클로드 코드도 인증 파일과 설정이 실행 대상에 있어야 합니다.

따라서 팀은 먼저 다음을 확인해야 합니다.

에이전트 명령줄 도구가 호스트에 설치되어 있는가
각 에이전트가 사용할 작업 공간이 분리되어 있는가
인증 파일을 어느 호스트가 소유하는가
실패한 실행을 사람이 중지하고 재배정할 수 있는가
에이전트가 생성한 로그와 결과물을 어디에 보관하는가

업무 조직과 위임 구조

코딩을 넘어 영업 조사, 문서 작성, 고객 응답, 보고서 검토까지 나누려면 단순한 작업 목록만으로 부족합니다. 조직 목표와 하위 작업의 관계가 필요합니다.

페이퍼클립은 회사 또는 조직 단위에서 에이전트와 프로젝트를 묶고, 작업을 만들며, 에이전트가 다른 작업을 생성하거나 위임하는 흐름을 지원하는 방향으로 설계되어 있습니다. 정해진 주기에 실행을 깨우는 방식도 사용하지만, 이것이 무인 운영을 보장한다는 뜻은 아닙니다.

정기 실행에서는 다음 문제가 생길 수 있습니다.

입력 자료가 갱신되지 않아 오래된 판단을 반복할 수 있습니다.
외부 서비스 장애가 같은 작업을 계속 실패시킬 수 있습니다.
위임이 반복되면서 비용과 작업 수가 늘어날 수 있습니다.
승인 없는 변경이 조직 규칙과 충돌할 수 있습니다.

주의: 정기 실행은 자동화 기능이지 책임자의 대체 수단이 아닙니다. 실제 운영에서는 중지 권한, 실패 알림, 작업 만료 조건을 함께 설정해야 합니다.

예산과 승인 통제

관리형 팀에서 페이퍼클립의 가치는 예산과 승인 기록에서 커집니다. 공식 구현 문서에는 회사 단위, 에이전트 단위, 선택적 프로젝트 단위의 예산 계층이 설명되어 있습니다. 비용 이벤트에는 제공자, 모델, 입력 토큰, 출력 토큰과 비용 값이 포함될 수 있습니다. 공식 구현 명세에서 세부 구조를 확인할 수 있습니다.

여기서 반드시 구분할 점이 있습니다. 페이퍼클립이 기록하거나 제한하는 비용과 모델 제공자가 실제로 청구하는 금액은 같은 개념이 아닙니다. 페이퍼클립의 비용 이벤트가 누락되거나 잘못 입력되면 실제 청구액과 차이가 날 수 있습니다. 따라서 제공자 콘솔의 청구 내역을 별도로 대조해야 합니다.

승인 기능은 에이전트 고용, 전략 승인, 예산 초과와 같은 요청을 사람이 검토하는 통로입니다. 에이전트는 승인 문을 우회하거나 조직 전체 예산을 직접 바꾸는 주체가 아니며, 관리자는 에이전트를 중지하거나 작업을 재배정할 수 있습니다.

자체 운영과 보안 경계

페이퍼클립은 도커로 배포할 수 있는가?

가능합니다. 공식 도커 문서는 단일 컨테이너 실행과 구성 파일 기반 배포를 모두 설명합니다. 기본 예시에서는 애플리케이션을 외부에 연결할 수 있도록 호스트 주소를 지정하고, 데이터 디렉터리를 /paperclip에 연결합니다. 데이터베이스 상태, 업로드 파일, 로컬 시크릿 키와 작업 공간을 지속 보관하려면 바인드 마운트나 볼륨이 필요합니다.

배포 순서는 다음처럼 진행하면 됩니다.

테스트용 호스트를 준비하고 도커와 구성 도구의 버전을 확인합니다.
공식 저장소의 배포 파일을 내려받고 외부에 노출할 포트를 정합니다.
인증용 비밀 값과 작업 서명용 비밀 값을 새로 생성합니다.
/paperclip 데이터 경로를 호스트 볼륨에 연결합니다.
클로드 코드, 코덱스 등 필요한 실행 도구와 인증 상태를 준비합니다.
테스트 작업을 생성하고 성공, 실패, 중지, 재실행을 차례로 확인합니다.
컨테이너를 다시 시작한 뒤 작업 기록과 데이터가 남는지 검증합니다.
외부 접속이 필요하면 방화벽, 역방향 프록시, 사용자 인증과 백업을 추가합니다.

데이터베이스는 설정에 따라 내장 방식으로 시작하거나 별도의 포스트그레스 데이터베이스 서버를 사용할 수 있습니다. 개발 환경에서는 기본 데이터가 인스턴스 디렉터리에 저장되지만, 운영 환경에서는 데이터베이스 백업과 이전 절차를 별도로 정해야 합니다.

시크릿은 저장 시 암호화된 참조로 관리할 수 있습니다. 실행 직전에 에이전트 프로세스의 환경 변수, 원격 명령, 샌드박스 또는 에이치티티피 요청에 주입되는 구조입니다. 그러나 값이 에이전트 프로세스에 전달된 뒤에는 절대적인 비밀 보장이 불가능합니다. 에이전트가 로그, 대화 기록, 하위 도구 또는 원격 호스트로 값을 보낼 가능성은 남습니다. 공식 시크릿 관리 문서도 이 경계를 명확히 설명합니다.

최소 권한 운영을 위해서는 에이전트마다 필요한 토큰만 연결해야 합니다. 짧은 수명의 자격 증명을 우선하고, 작업 종료 후 폐기하며, 의심스러운 실행이나 기록 유출 가능성이 있으면 즉시 교체해야 합니다.

도입 결정 체크리스트

아래 항목을 실제 운영 계획에 대입하십시오. 선택 결과가 분명하지 않으면 먼저 소규모 시험 환경에서 검증하십시오.

[ ] 에이전트가 3개 이상이거나 여러 작업을 동시에 처리합니다.
[ ] 작업 상태와 세션 문맥을 하루 이상 유지해야 합니다.
[ ] 배포, 외부 발송 또는 비용 증가 전에 사람의 승인이 필요합니다.
[ ] 에이전트별 예산과 실행 기록을 분리해야 합니다.
[ ] 인증 토큰을 에이전트별 최소 권한으로 관리해야 합니다.
[ ] 실행 호스트를 계속 온라인 상태로 유지할 수 있습니다.
[ ] 실패한 작업을 중지하거나 다른 에이전트에 재배정할 담당자가 있습니다.

체크 항목이 0~2개라면: 페이퍼클립을 바로 도입하지 마십시오. 터미널, 기존 작업 보드 또는 단순한 자동화 스크립트로 시작하는 편이 빠릅니다.

체크 항목이 3~5개라면: 테스트 서버에 배포하십시오. 하나의 프로젝트와 제한된 인증 정보만 연결하고, 작업 재실행과 데이터 복구를 확인한 뒤 확대하십시오.

체크 항목이 6개 이상이라면: 페이퍼클립 멀티 에이전트 워크플로를 운영 후보로 올릴 수 있습니다. 다만 예산 기록과 제공자 청구액을 대조하고, 시크릿 교체 절차와 담당자 승인 흐름을 먼저 문서화해야 합니다.

배포 위치도 다음 조건으로 나누면 됩니다.

로컬 맥: 개인 테스트, 물리 장치 접근, 짧은 개발 주기에 적합합니다.
원격 맥: 맥 전용 명령줄 도구와 장시간 실행이 필요하지만 직접 장비를 관리하고 싶지 않을 때 적합합니다.
일반 서버: 리눅스 기반 에이전트와 도커 중심 운영에 적합합니다. 다만 맥 전용 개발 도구나 물리 인터페이스가 필요하면 제약이 생깁니다.

장시간 온라인 환경을 처음 구성한다면 VPSSpark 소개를 확인한 뒤, 실제 작업량과 인증 요구를 기준으로 호스트를 선택하는 편이 안전합니다. 맥 환경이 필요한 팀은 한국 맥 렌탈 옵션도 비교할 수 있습니다.

터미널 여러 개와 개인 노트북만으로 시작하면 초기 부담은 낮습니다. 하지만 노트북이 절전 상태에 들어가고, 세션이 끊기며, 인증 파일이 개인 장비에 흩어지는 문제가 생깁니다. 일반 서버는 온라인 유지에는 유리하지만 맥 전용 개발 도구, 애플리케이션 테스트와 로컬 인증 흐름에서 제약이 생길 수 있습니다.

팀에서 페이퍼클립을 실제 업무에 연결하고 지속 실행과 승인을 요구한다면, 계속 켜 둔 맥 실행 환경이 운영 판단을 단순하게 만들 수 있습니다. 다만 장기간 무거운 작업을 고정적으로 돌리거나 물리 장치 접근이 핵심이라면 직접 장비를 구매하는 편이 더 적합할 수 있습니다. 반대로 일정 기간만 여러 에이전트를 검증하거나 팀의 지속 실행 환경을 시험하려는 경우에는 VPSSpark의 맥 렌탈을 비교 대상으로 두는 것이 현실적입니다.

도입 전에는 문의 페이지를 통해 필요한 실행 방식, 온라인 유지 조건과 보안 요구를 먼저 확인하십시오. 페이퍼클립의 기능보다 중요한 것은 에이전트가 실제로 실행될 호스트와 그 호스트의 권한 경계입니다.