개요 크론 잡은 게이트웨이의 내장 스케줄러로 에이전트 작업을 예약 실행한다. 일회성, 반복, cron 표현식을 지원하며, ~/.openclaw/cron/jobs.json에 영구 저장된다. 스케줄 타입 at (일회성) 특정 시각에 한 번만 실행한다. { "schedule": { "type": "at", "time": "2026-04-01T09:00:00+09:00" } } every (간격) 일정 간격으로 반복 실행한다. { "schedule": { "type": "every", "interval": "1h" } } 지원 단위: m (분), h (시간), d (일) cron (표현식) 5필드 또는 6필드 cron 표현식으로 정밀한 스케줄을 설정한다. { "schedule": { "type": "cron", "expression": "0 9 * * 1-5" } } 필드 범위 설명 분 0-59 시 0-23 일 1-31 월 1-12 요일 0-6 0=일요일 초 (6필드) 0-59 선택 세션 모드 크론 잡이 실행될 때 사용하는 세션을 지정한다. ...

Paperclip이 사용하는 모든 환경 변수입니다. 서버 설정 변수 기본값 설명 PORT 3100 서버 포트 HOST 127.0.0.1 바인딩 호스트 DATABASE_URL (임베디드) PostgreSQL 연결 문자열 PAPERCLIP_HOME ~/.paperclip 데이터 디렉토리 PAPERCLIP_INSTANCE_ID default 인스턴스 ID (다중 로컬 인스턴스용) PAPERCLIP_DEPLOYMENT_MODE local_trusted 런타임 배포 모드 시크릿 관리 변수 설명 PAPERCLIP_SECRETS_MASTER_KEY 32바이트 암호화 키 (base64, hex, raw 형식) PAPERCLIP_SECRETS_MASTER_KEY_FILE 키 파일 경로 PAPERCLIP_SECRETS_STRICT_MODE 민감한 환경 변수에 시크릿 참조 강제 에이전트 런타임 변수 (자동 주입) 변수 설명 PAPERCLIP_AGENT_ID 에이전트 ID PAPERCLIP_COMPANY_ID 회사 ID PAPERCLIP_API_URL API 엔드포인트 PAPERCLIP_API_KEY 인증 토큰 (단기 JWT) PAPERCLIP_RUN_ID 실행 ID PAPERCLIP_TASK_ID 태스크 ID (컨텍스트에 따라) PAPERCLIP_WAKE_REASON 깨어난 이유 PAPERCLIP_APPROVAL_ID 승인 ID (승인 해결 시) PAPERCLIP_APPROVAL_STATUS 승인 상태 LLM 프로바이더 인증 변수 설명 ANTHROPIC_API_KEY Claude 통합 OPENAI_API_KEY OpenAI 프로바이더

Paperclip은 민감한 환경 변수를 보호하기 위해 로컬 암호화를 사용합니다. API 키, 토큰 등 민감한 값은 암호화된 시크릿 참조로 저장됩니다. 키 저장 위치 마스터 암호화 키: ~/.paperclip/instances/default/secrets/master.key 설정 시 자동 생성 키는 머신을 떠나지 않습니다 설정 방법 # 온보딩으로 설정 pnpm paperclipai onboard # 시크릿 섹션 설정 pnpm paperclipai configure --section secrets # 설정 검증 pnpm paperclipai doctor 환경 변수 변수 설명 PAPERCLIP_SECRETS_MASTER_KEY base64, hex 또는 raw 형식의 암호화 키 PAPERCLIP_SECRETS_MASTER_KEY_FILE 커스텀 키 위치 PAPERCLIP_SECRETS_STRICT_MODE 암호화 참조 강제 스트릭트 모드 활성화 시, *_API_KEY, *_TOKEN, *_SECRET 패턴과 일치하는 환경 변수는 반드시 평문 대신 암호화된 참조를 사용해야 합니다. ...

개요 훅(Hooks)은 OpenClaw의 이벤트 기반 자동화 시스템이다. 게이트웨이 내부 이벤트 또는 외부 HTTP 웹훅에 반응하여 자동으로 작업을 실행한다. 훅 타입 Internal (내부 이벤트) 게이트웨이 내부에서 발생하는 이벤트에 반응한다. 세션 시작/종료 메시지 수신/발신 에이전트 부팅/종료 도구 실행 전/후 Webhooks (외부 HTTP) 외부 서비스에서 HTTP 요청을 통해 트리거한다. GitHub 웹훅 (PR, 이슈 등) CI/CD 파이프라인 알림 커스텀 서비스 연동 번들 훅 (Bundled Hooks) OpenClaw에 기본 포함된 훅이다. 훅 설명 session-memory 세션 종료 시 대화 요약을 메모리에 저장 bootstrap-extra-files 부트스트랩 시 추가 파일 주입 command-logger 명령어 실행을 로그 파일에 기록 boot-md 에이전트 부팅 시 BOOT.md 실행 훅 로딩 우선순위 여러 소스에서 훅이 로드될 때 우선순위가 적용된다. 같은 이벤트에 여러 훅이 있으면 높은 우선순위의 훅이 먼저 실행된다. ...

Paperclip은 업로드와 첨부 파일을 위한 유연한 파일 스토리지 옵션을 제공합니다. 기본 스토리지 (로컬 디스크) 파일 저장 위치: ~/.paperclip/instances/default/data/storage 설정 불필요 개발 환경 및 단일 서버 구성에 적합 프로덕션용 (S3 호환) 다중 노드 또는 클라우드 배포 시 S3 호환 오브젝트 스토리지 권장: AWS S3 MinIO Cloudflare R2 pnpm paperclipai configure --section storage 프로바이더 비교 프로바이더 적합한 환경 local_disk 로컬 개발, 단일 머신 배포 s3 프로덕션, 다중 노드, 클라우드 환경 설정은 ~/.paperclip/instances/default/config.json에 저장됩니다.

사전 요구사항 Node.js 20+ pnpm 9+ 시작하기 pnpm install pnpm dev API 서버: http://localhost:3100, UI도 같은 오리진에서 제공. 외부 서비스 불필요. 초기 설정 pnpm paperclipai run 자동 온보딩, 진단 체크 및 자동 복구, 검증 통과 시 서버 시작. 프라이빗 네트워크 접근 인증 개발 접근용: pnpm dev --tailscale-auth 서버를 0.0.0.0에 바인딩합니다. 추가 프라이빗 호스트명 화이트리스트: pnpm paperclipai allowed-hostname [hostname] 서버 헬스 테스트 # 헬스 체크 curl http://localhost:3100/api/health # 응답: {"status":"ok"} # 회사 목록 curl http://localhost:3100/api/companies # 응답: [] (초기에는 빈 배열) 데이터 저장 위치 ~/.paperclip/instances/default/ 하위: ...

Paperclip CLI는 인스턴스 설정, 진단, 컨트롤 플레인 작업을 위한 도구입니다. 글로벌 옵션 플래그 설명 --data-dir <path> 로컬 데이터 격리 --api-base <url> API 엔드포인트 설정 --api-key <token> 인증 --context <path> 프로파일 관리 --profile <name> 프로파일 선택 --json 구조화된 출력 --company-id <id> 회사 범위 작업 컨텍스트 프로파일 설정 기본값을 프로파일로 저장: # 기본값 설정 pnpm paperclipai context set --api-base http://localhost:3100 # 현재 설정 보기 pnpm paperclipai context show # 프로파일 목록 pnpm paperclipai context list # 프로파일 전환 pnpm paperclipai context use default 보안을 위해 API 키는 ~/.paperclip/context.json에 직접 저장하는 대신 환경 변수를 참조할 수 있습니다. ...

paperclipai run 자동 온보딩과 서버 시작을 한 번에 수행합니다. 실행 전 설정을 검증합니다. paperclipai onboard 초기 설정 가이드: Quickstart — 로컬 기본값 Advanced setup — 커스텀 설정 플래그: --run — 즉시 시작 --yes — 비대화형 기본값 paperclipai doctor 헬스 체크 수행: 서버 설정 데이터베이스 연결 시크릿 어댑터 스토리지 설정 필수 파일 --repair 옵션으로 자동 수정 활성화. paperclipai configure 특정 설정 섹션 업데이트: pnpm paperclipai configure --section server pnpm paperclipai configure --section secrets pnpm paperclipai configure --section storage paperclipai env 해결된 환경 설정을 표시합니다. ...

클라이언트 측 CLI 명령어로 이슈, 에이전트, 승인, 활동을 관리합니다. 이슈 # 목록 조회 pnpm paperclipai issues list # 개별 조회 pnpm paperclipai issues get <id> # 생성 pnpm paperclipai issues create --title "..." --description "..." # 업데이트 pnpm paperclipai issues update <id> --status done # 코멘트 추가 pnpm paperclipai issues comment <id> --body "..." # 태스크 체크아웃 pnpm paperclipai issues checkout <id> # 태스크 릴리스 pnpm paperclipai issues release <id> 회사 # 목록 조회 pnpm paperclipai companies list # 포터블 패키지로 내보내기 pnpm paperclipai companies export <id> # 외부 소스에서 가져오기 (충돌 처리 옵션 포함) pnpm paperclipai companies import <file> 에이전트 # 목록 조회 pnpm paperclipai agents list # 개별 조회 pnpm paperclipai agents get <id> 승인 # 목록 조회 pnpm paperclipai approvals list # 승인 pnpm paperclipai approvals approve <id> # 거부 pnpm paperclipai approvals reject <id> # 수정 요청 pnpm paperclipai approvals request-revision <id> # 재제출 pnpm paperclipai approvals resubmit <id> # 코멘트 pnpm paperclipai approvals comment <id> --body "..." 활동 # 필터링 가능: --agent-id, --entity-type, --entity-id pnpm paperclipai activity list 대시보드 & 하트비트 # 대시보드 조회 pnpm paperclipai dashboard # 에이전트 하트비트 모니터링 pnpm paperclipai heartbeat --api-base http://localhost:3100

Paperclip은 컨트롤 플레인 작업을 위한 RESTful JSON API를 제공합니다. 기본 URL: http://localhost:3100/api 인증 방법 방법 설명 에이전트 API 키 에이전트를 위한 장기 키 에이전트 실행 JWT 하트비트 중 주입되는 단기 토큰 사용자 세션 쿠키 웹 UI 운영자용 요청/응답 표준 모든 요청은 Content-Type: application/json 헤더와 JSON 페이로드 필요 회사 범위 경로: :companyId 사용 성공 응답: 엔티티 직접 반환 에러 응답: {"error": "사람이 읽을 수 있는 메시지"} HTTP 상태 코드 코드 의미 400 유효성 검사 오류 401 인증 누락 403 권한 문제 404 엔티티 없음 409 다른 에이전트가 태스크를 소유 중 422 잘못된 상태 전환 500 일시적 장애 추가 사항 목록 엔드포인트는 페이지네이션 파라미터 지원 로컬 배포에서는 레이트 리밋 없음 하트비트 중 변경 요청에 X-Paperclip-Run-Id 헤더 포함