2026년 7월 22일 공개된 공식 릴리스가 최신 표기로 남아 있습니다. 이 릴리스에는 에이전트별 비밀값 접근과 윈도우 환경의 로컬 실행 개선이 포함되었습니다. (github.com)
증상 → 에이전트가 늘수록 누가 무엇을 했는지 추적하기 어렵습니다.
가장 빠른 해법 → Paperclip을 모델이나 코딩 에이전트가 아닌 다중 에이전트 워크플로 제어 계층으로 두고, 작은 승인형 업무 하나부터 시작합니다.
이 글은 여러 기존 에이전트를 하나의 추적 가능한 흐름으로 묶으려는 개발자를 위한 안내서입니다. 작업 위임과 상태 관리가 필요한 자동화 팀, 장시간 실행 환경을 준비하는 기술 책임자에게 특히 유용합니다.
주의: Paperclip을 설치했다고 자동화가 완성되는 것은 아닙니다. 모델 계정, 에이전트 실행기, 도구 권한, 작업 폴더와 비밀값은 별도로 준비해야 합니다.
설치 전에 범위부터 자릅니다
Paperclip은 공식 설명상 여러 AI 에이전트를 조직처럼 배치하고, 목표와 작업, 비용과 운영 상태를 관리하는 애플리케이션입니다. 서버와 화면을 제공하지만 모델 자체를 대신 제공하지는 않습니다. 에이전트가 실제로 실행될 런타임과 모델 인증 정보는 별도로 연결해야 합니다. (github.com)
따라서 설치 전에 다음 세 가지가 준비되어 있어야 합니다.
- 이미 단독 실행되는 에이전트가 있어야 합니다.
- 사용할 모델 제공자의 인증 정보가 있어야 합니다.
- 성공 여부를 사람이 확인할 수 있는 업무 목표가 있어야 합니다.
이 경계를 무시하면 플랫폼 화면은 열리지만 작업은 진행되지 않습니다. 인증 토큰이 없으면 에이전트가 모델을 호출할 수 없고, 작업 폴더와 도구 권한이 정해지지 않으면 실패 원인을 분리하기 어렵습니다. 공식 설치 문서도 에이전트 실행 전에 모델 제공자용 API 키가 필요하다고 설명합니다. (docs.paperclip.ing)
Paperclip의 장점은 AI 에이전트 편성에 있습니다. 반대로 단순한 함수 호출 순서만 빠르게 시험하려는 경우에는 코드 중심 오케스트레이션 도구가 더 단순할 수 있습니다. Paperclip은 조직 구조, 승인, 비용, 작업 기록까지 함께 운영해야 할 때 가치가 커집니다.
첫 1시간은 최소 조직으로 시작합니다
처음부터 대규모 에이전트 회사를 불러오지 마십시오. 첫 실험에는 다음 정도면 충분합니다.
- 조정 역할: 목표를 쪼개고 결과를 검토합니다.
- 실행 역할: 한 가지 산출물을 만듭니다.
- 검토 역할: 형식과 오류를 확인합니다.
역할은 서로 겹치지 않아야 합니다. 조정 역할이 직접 코드를 수정하고, 실행 역할이 승인까지 수행하면 책임 경계가 사라집니다. 각 역할에는 입력, 출력, 완료 조건을 한 문장씩 적으십시오.
예를 들어 “저장소를 분석한다”는 목표는 너무 큽니다. 다음처럼 나누는 편이 안전합니다.
- 조정 에이전트가 분석 항목을 세 개의 작업으로 분리합니다.
- 실행 에이전트가 각 항목의 결과 파일을 만듭니다.
- 검토 에이전트가 파일과 근거를 검사합니다.
- 사람이 최종 결과를 승인합니다.
이 구조는 에이전트 작업 관리의 시작점입니다. 에이전트 수보다 중요한 것은 각 작업이 어디에서 시작되고, 누가 완료를 판정하며, 실패하면 어느 단계로 되돌아가는지입니다.
두 번째 단계에서 작업 상태를 검증합니다
Paperclip의 런타임은 에이전트를 계속 켜 두는 방식이 아니라 깨우기 신호에 따라 짧은 실행 구간을 만드는 방식입니다. 공식 런타임 문서에는 시간 예약, 작업 배정, 수동 실행, 자동화 신호가 깨우기 원인으로 설명되어 있습니다. 실행이 끝나면 상태, 사용량, 오류와 로그가 저장됩니다. (github.com)
첫 작업은 되돌릴 수 있는 업무로 고르십시오. 예를 들면 테스트 저장소에 문서 초안을 만들거나, 임시 폴더의 파일을 분류하는 작업이 적합합니다.
확인할 상태 흐름은 다음과 같습니다.
- 목표 생성
- 하위 작업 분리
- 담당 에이전트 배정
- 실행 중 상태 전환
- 결과 보고
- 검토 대기
- 승인 또는 반려
- 완료 또는 재시도
실패를 일부러 한 번 만들어 보는 것도 필요합니다. 존재하지 않는 파일을 읽게 하거나 제한된 명령을 호출하게 한 뒤, 실패가 기록되는지 확인하십시오. 재시도 때 같은 작업이 중복 생성되지 않는지도 확인해야 합니다.
상위 에이전트가 하위 작업 완료 뒤 다시 깨어나는 구조라면 반복 호출이 생길 수 있습니다. 완료 조건이 불명확하면 같은 작업을 다시 배정하거나, 이미 끝난 결과를 다시 검토하는 순환이 발생합니다.
첫날에는 실제 에이전트와 권한을 연결합니다
공식 문서는 Paperclip이 여러 실행기와 사용자 정의 연결 방식을 지원한다고 안내합니다. 저장소에는 클로드, 코덱스, 커서, 셸과 HTTP 연결 예시가 제시되어 있지만, 실제 호환 범위는 설치 시점의 공식 문서와 릴리스 기록으로 다시 확인해야 합니다. (github.com)
연결 순서는 다음처럼 진행하십시오.
- 에이전트마다 사용할 모델과 실행기를 지정합니다.
- 모델 인증 정보는 환경 변수나 비밀값 저장 기능에 넣습니다.
- 작업 폴더를 프로젝트별로 분리합니다.
- 읽기, 쓰기, 실행 권한을 업무에 필요한 범위로만 부여합니다.
- 테스트 작업을 실행하고 로그와 결과 파일을 함께 확인합니다.
- 실패 뒤 재시도할 때 권한이 확대되지 않는지 확인합니다.
특히 다음 세 가지는 첫날 반드시 시험해야 합니다.
- 에이전트가 다른 프로젝트의 파일을 읽을 수 있는가
- 담당 범위를 벗어난 작업을 새로 만들 수 있는가
- 배포 키나 운영 자원을 직접 변경할 수 있는가
Paperclip이 조직을 보여준다고 해서 권한이 자동으로 격리되는 것은 아닙니다. 실행 환경과 도구 권한을 별도로 설계해야 합니다. 2026년 7월 릴리스에는 에이전트별 허용된 비밀값을 실행 단위로 조회하고 감사 기록에 남기는 기능이 추가되었지만, 어떤 비밀값을 허용할지는 운영자가 정해야 합니다. (github.com)
첫 주에는 승인과 관측을 붙입니다
작업이 한 번 성공했다고 장기 운영이 가능한 것은 아닙니다. 첫 주에는 실제 업무를 넣고 다음 항목을 관찰하십시오.
- 승인 없이 외부 공개 단계로 넘어가는지
- 작업 시간 초과 뒤 재시도가 중복되는지
- 같은 목표가 반복 위임되는지
- 상위 에이전트가 하위 결과를 제대로 읽는지
- 모델 비용과 실행량이 예산 범위를 넘는지
- 오류가 사람에게 통지되는지
- 작업 중단 뒤 다시 이어지는지
Paperclip 공식 문서에는 작업, 승인, 예산, 활동 기록과 실행 정책이 별도 운영 영역으로 정리되어 있습니다. (docs.paperclip.ing)
승인은 모든 단계에 넣지 말고 위험이 바뀌는 지점에 두는 편이 낫습니다. 예를 들어 문서 초안 생성에는 자동 진행을 허용하되, 외부 게시와 운영 데이터 변경에는 사람의 승인을 요구할 수 있습니다.
비용도 에이전트 수로 계산하면 안 됩니다. 모델, 실행 시간, 재시도 횟수, 읽은 문서 양에 따라 달라집니다. 공식 설치 문서 역시 에이전트가 작업할 때 모델 제공자 호출 비용이 발생하며, 예산 제한을 설정해야 한다고 안내합니다. (docs.paperclip.ing)
서버 배포는 지속성부터 판단합니다
개인 컴퓨터에서 시험할 때는 설치와 디버깅이 빠릅니다. 다만 절전, 네트워크 변경, 사용자 로그아웃이 장기 작업을 끊을 수 있습니다.
원격 맥은 맥 전용 도구와 그래픽 기반 작업이 필요한 팀에 적합합니다. 리눅스 서버는 비용과 자동화 관리가 단순하고, 여러 사용자가 공유하는 환경은 접근 통제와 백업 정책을 먼저 마련해야 합니다.
공식 서버 설치 문서는 시작 단계로 리눅스 가상 서버와 2 기가바이트 메모리 환경을 안내하며, 노드 20 이상과 패키지 관리 도구를 요구합니다. 또한 외부에는 웹용 80번과 443번만 열고, Paperclip 내부 포트는 로컬에 묶도록 설명합니다. (docs.paperclip.ing)
배포 단계는 다음과 같습니다.
- 운영 목적에 맞는 개인, 원격 맥, 리눅스 서버 중 하나를 고릅니다.
- 전용 운영 계정과 프로젝트별 작업 폴더를 만듭니다.
- 도메인, 보안 셸, 암호화 인증서를 준비합니다.
- 내부 서비스 포트를 외부에 직접 공개하지 않습니다.
- 비밀값을 파일에 평문으로 남기지 않습니다.
- 데이터베이스와 작업 기록을 정기적으로 백업합니다.
- 업그레이드 전 복구 절차를 시험합니다.
- 에이전트 세션이 끊긴 뒤 재개되는지 확인합니다.
Paperclip은 로컬 실행과 서버 실행을 모두 고려할 수 있지만, 장기 운영에서는 화면이 열리는 것보다 세션 지속, 로그 보존, 인증서 갱신과 비밀값 교체가 더 중요합니다.
확장 전 마지막 검수 목록
다음 항목을 모두 확인한 뒤에만 에이전트 수를 늘리십시오.
- [ ] 하나의 목표가 명확한 하위 작업으로 분리됩니다.
- [ ] 각 역할의 입력과 출력이 겹치지 않습니다.
- [ ] 담당자가 없는 작업이 자동으로 발견됩니다.
- [ ] 실패 상태와 재시도 결과가 기록됩니다.
- [ ] 반복 위임과 순환 깨우기가 차단됩니다.
- [ ] 사람의 승인 지점이 위험 단계에 배치됩니다.
- [ ] 에이전트별 작업 폴더가 분리됩니다.
- [ ] 읽기와 쓰기 권한이 업무 범위 안에 있습니다.
- [ ] 모델 인증 정보가 로그에 노출되지 않습니다.
- [ ] 운영 자원 변경에는 별도 승인 절차가 있습니다.
- [ ] 중단된 세션을 복구할 수 있습니다.
- [ ] 백업에서 작업 기록을 복원해 보았습니다.
Paperclip을 지금 선택해도 되는 경우
Paperclip은 여러 에이전트를 조직과 업무 흐름으로 묶고, 목표부터 완료까지 추적하려는 팀에 적합합니다. 특히 작업 위임, 승인, 예산, 감사 기록을 한 운영 화면에서 관리해야 한다면 단순한 호출 라이브러리보다 실용적인 선택이 될 수 있습니다.
반대로 장기간 한 가지 작업만 반복하고, 물리 장치나 그래픽 환경이 필요하며, 서버를 직접 관리할 인력이 없다면 자체 환경을 처음부터 구축하는 방식은 부담이 큽니다. 개인 컴퓨터는 절전과 네트워크 중단에 취약하고, 일반 리눅스 서버는 맥 전용 도구와 화면 기반 작업에 제약이 있으며, 팀 공유 환경은 권한과 비밀값이 섞이기 쉽습니다.
이런 조건에서 Macstripe의 원격 맥 환경을 사용하면 장비 구매, 상시 전원 관리, 원격 접속 설정을 직접 떠안지 않고 Paperclip 실험용 실행 환경을 분리할 수 있습니다. 특히 단기간의 검증, 여러 프로젝트의 격리, 원격 협업과 지속 실행이 목적이라면 원격 맥 환경 선택 기준과 지원 안내를 먼저 확인한 뒤 필요한 기간만 운영하는 편이 합리적입니다.
안정적인 장기 중부하 작업이나 특정 물리 인터페이스가 필요한 경우에는 직접 장비를 운영하는 편이 더 적합할 수 있습니다. 반대로 Paperclip을 처음 시험하거나, 여러 에이전트의 권한과 작업 상태를 분리해야 한다면 원격 맥을 임시 운영 기반으로 검토할 가치가 있습니다. 필요한 조건이 정해졌다면 맥 환경 주문 설정에서 전달 방식과 사용 범위를 확인하십시오.
