Windows 11 PC에서 Paperclip을 처음 설치해 서버를 띄우고 Agent 연결 테스트까지 해 본 과정을 정리했습니다. 글에서 [직접 확인]은 제가 2026-11-10에 직접 해 본 것, [문서상]은 공식 문서에 적힌 설명이지만 제가 실행해 보지 않은 것입니다.
- 공식 README: https://github.com/paperclipai/paperclip
- 공식 문서: https://docs.paperclip.ing
1. Paperclip이 뭔가
오픈소스(MIT) AI Agent 오케스트레이션 도구입니다. Node.js 서버와 React UI로 구성되어 있고, Agent에게 티켓(작업)을 배정한 뒤 승인·예산·이력을 한곳에서 관리합니다.
2. 사전 설치 항목
Node.js 24.11 이상 (필수) [직접 확인]
Node 22.21.0 환경에서 paperclipai 점검(doctor)이 Node.js 22.21.0 is unsupported로 실패했고 서버가 시작되지 않았습니다. Windows에서는 winget으로 LTS를 설치했습니다.
winget install --id OpenJS.NodeJS.LTS --exact- 설치 중 관리자 권한 창이 눈에 보이지 않았지만 "설치 성공"으로 끝났습니다.
- 새 터미널을 열어
node -v로 확인합니다(저는 26.13.0). 기존 터미널은 옛 버전 경로를 그대로 쓸 수 있습니다.
Claude 구독 로그인 방식을 쓸 경우 [문서상 + 환경 확인]
README상 Python 3와 Claude CLI(Claude Code)가 PC에 있어야 합니다. 제 환경은 Python 3.13, Claude Code 2.1.x 였습니다. API 키 방식을 쓸 때의 요건은 확인하지 못했습니다.
3. 버전 함정: @latest 를 꼭 붙이세요 [직접 확인]
npx paperclipai ... 처럼 @latest 없이 실행하면 npx 캐시에 남은 옛 버전(2026.824.1)이 실행되어 test-drive 명령이 없다는 오류가 났습니다. 같은 시점에 npx --yes paperclipai@latest --version 은 2026.1106.0 이었습니다.
또 npx가 Ok to proceed? (y) 를 물을 때 한글 입력 상태에서 ㅛ 를 치면 취소됩니다. 영문 상태에서 y 를 입력하거나 --yes 옵션을 쓰세요.
4. 서버 시작 [직접 확인]
npx --yes paperclipai@latest run --data-dir D:\paperclip-data- 먼저 점검(doctor)을 돌리고, 내장 PostgreSQL(포트 54329)을 띄운 뒤,
http://127.0.0.1:3100에서 UI가 열립니다. - 로컬 전용이며 로그인이 없는 모드(
local_trusted)였습니다. - 같은
--data-dir로 다시 켜면 만들어 둔 조직과 Agent가 이어집니다. - 끌 때는 실행 중인 터미널에서 Ctrl-C.
test-drive 는 키가 없으면 바로 종료됩니다
test-drive 는 모델 키가 없으면 No credential found. Set ANTHROPIC_API_KEY... 라며 서버를 띄운 직후 종료했습니다. 키 없이 서버만 켜려면 run 을 쓰세요.
텔레메트리 끄기
익명 사용 통계 전송이 기본으로 켜져 있습니다. 끄려면 환경변수를 설정합니다.
$env:PAPERCLIP_TELEMETRY_DISABLED = '1'(다른 셸에서는 PAPERCLIP_TELEMETRY_DISABLED=1)
5. 첫 화면 온보딩 [직접 확인]
조직 이름 입력 → Agent(예: CEO/일반) 생성 → "Connect a model" 순서입니다.
여기서 "Claude Subscription" 로그인을 시도했더니 Sign-in ended before the account was connected 로 계속 실패했습니다. 그런데 이 연결(managed connection)은 필수가 아니었습니다.
- Agent 설정(Harness/Runtime)에
Existing authentication — not managed by Connections가 표시됩니다. - 이 경우 PC에 이미 로그인된 Claude Code(Local credentials)를 그대로 씁니다.
- 같은 화면 아래 "Test your agent → Run test" 를 눌러
Connection successful / runtime checks passed를 확인했습니다. 처음 한 번은Couldn't connect가 떴고 다시 누르니 성공했습니다.
6. 시작 직후 알아둘 것
- 대시보드에
All agents are paused경고가 뜹니다. 새 Agent는 중지 상태로 시작하므로 작업을 돌리려면 Agent를 resume 해야 합니다. [직접 확인: 경고 표시] - 예산은 기본 무제한이었습니다. Audit → Budgets 에서 월 상한을 정해 두는 것을 권합니다. [문서상] 80%에서 경고, 100%에서 해당 범위가 자동 중지되며, 이미 실행 중인 작업은 조금 더 쓸 수 있습니다.
7. 기본 사용 흐름 [문서상 — 직접 실행해 보지 않음]
- New Task 로 작업 생성
- 담당 Agent 지정(배정하면 Agent가 깨어남)
- 작업 상세·Audit, Runs 에서 진행 확인
- 코멘트로 추가 지시
- 승인 요청은 Inbox/승인 화면에서 승인·반려·수정요청
Agent는 기본적으로 타이머가 아니라 배정·코멘트·루틴 같은 이벤트로 깨어납니다. 솔직히, 제가 직접 해 본 것은 Agent 연결 테스트까지이고 실제 작업 배정 후 실행은 아직 해 보지 않았습니다.
8. Agent·스킬 설정을 파일로 관리 [직접 확인]
내보내기:
npx paperclipai@latest company export <조직ID> --out <폴더> --include company,agents,skills --api-base http://127.0.0.1:3100COMPANY.md, agents/<이름>/AGENTS.md, skills/.../SKILL.md, .paperclip.yaml 로 이루어진 마크다운 패키지가 생깁니다. 조직ID는 company list 로 확인합니다.
가져오기(미리보기 후 적용):
npx paperclipai@latest company import <폴더> --target existing -C <조직ID> --include agents --dry-run
npx paperclipai@latest company import <폴더> --target existing -C <조직ID> --include agents --yes이 방법으로 Agent 4개를 등록하는 데 성공했습니다.
9. 보안 주의 [직접 확인]
내보낸 Agent 설정 기본값에 다음이 들어 있었습니다. 실제 사용 전에 검토하세요.
dangerouslySkipPermissions: true(권한 확인 없이 도구 사용)- Agent 생성·스킬 생성 권한 true
- heartbeat 300초
그 밖에:
- Claude 로그인에 만료 경고가 뜰 수 있습니다.
claude auth login으로 갱신합니다. - 회사 PC라면 외부 패키지 설치와 모델 호출 경로에 대한 사내 승인을 먼저 받으세요.
정리
| 항목 | 상태 |
|---|---|
| Node 24.11+ 설치, 서버 시작, UI 접속 | 직접 확인 |
| Agent 생성, 연결 테스트 성공 | 직접 확인 |
| 설정 export/import | 직접 확인 |
| 작업 배정·실행·승인 흐름, 예산 동작 | 문서상 설명만, 확인하지 못함 |
다음 글에서는 실제 작업을 배정해 돌려 본 결과를 적어 보겠습니다.
댓글 없음:
댓글 쓰기