[{"content":"개요 OpenClaw는 멀티채널 AI 에이전트 플랫폼이다. 하나의 게이트웨이(Single Gateway)로 WhatsApp, Telegram, Discord, Signal, iMessage, WebChat 등 모든 메시징 채널을 통합 관리한다.\nAI 에이전트를 한 곳에서 구축하면 30개 이상의 메시징 플랫폼에서 동시에 운영할 수 있다.\n핵심 기능 1. 35+ 모델 프로바이더 지원 다양한 AI 모델을 즉시 사용할 수 있다.\nAnthropic (Claude 시리즈) OpenAI (GPT 시리즈) Google (Gemini 시리즈) Mistral, Groq, OpenRouter 등 자체 호스팅 모델 (Ollama, vLLM, SGLang) 지원 2. 임베디드 에이전트 런타임 에이전트가 게이트웨이 내부에서 직접 실행된다.\n도구 스트리밍 (Tool Streaming): 도구 실행 결과를 실시간 스트리밍 격리된 세션: 에이전트별 독립 세션 관리 워크스페이스 기반: 마크다운 파일로 에이전트 지시사항과 메모리 관리 3. 멀티 에이전트 라우팅 여러 에이전트를 동시에 운영하며 메시지를 적절한 에이전트로 라우팅한다.\n에이전트별 격리된 세션 계층적 라우팅 규칙 (직접 피어 \u0026gt; 부모 피어 \u0026gt; 역할 \u0026gt; 길드 \u0026gt; 팀 \u0026gt; 계정 \u0026gt; 채널 \u0026gt; 기본) 멀티 계정 지원 (WhatsApp, Telegram, Discord) 4. 리치 미디어 지원 텍스트뿐 아니라 다양한 미디어를 처리한다.\n이미지: 전송 및 수신, 비전 분석 오디오: 음성 메시지 처리 비디오: 동영상 전송 문서: 파일 첨부 및 처리 5. 브라우저 자동화 에이전트가 웹 브라우저를 제어하여 작업을 수행한다.\n웹 페이지 탐색 및 데이터 추출 폼 작성 및 제출 스크린샷 캡처 6. 웹 검색 에이전트가 인터넷 검색을 수행하여 최신 정보를 가져온다.\n7. 크론 스케줄링 정해진 시간에 에이전트 작업을 자동 실행한다.\n크론 표현식으로 정밀한 스케줄 설정 반복 작업 자동화 8. 워크플로 파이프라인 여러 단계의 작업을 연결하여 복잡한 워크플로를 구성한다.\n클라이언트 인터페이스 WebChat 웹 브라우저에서 에이전트와 대화할 수 있는 채팅 인터페이스.\nControl UI 에이전트 관리, 설정, 모니터링을 위한 웹 기반 관리 대시보드. 게이트웨이 포트(18789)에서 접근 가능.\nmacOS 메뉴바 앱 macOS 상단 메뉴바에서 빠르게 에이전트에 접근할 수 있는 네이티브 앱.\n모바일 노드 iOS/Android 디바이스를 게이트웨이의 노드로 연결하여 모바일에서 에이전트를 운영한다.\n단일 게이트웨이 원칙 OpenClaw의 핵심 설계 원칙은 **단일 게이트웨이(Single Gateway)**이다.\n하나의 장기 실행 데몬이 모든 메시징 채널을 관리 모든 클라이언트는 WebSocket으로 게이트웨이에 연결 프로바이더 연결 유지, 세션 관리, 인증을 게이트웨이가 일괄 처리 로컬 실행 기본 (127.0.0.1:18789) 이 구조 덕분에 에이전트를 한 번 설정하면 모든 채널에서 동일하게 동작한다.\n","permalink":"https://jungwoo0716.github.io/docs/openclaw/01-%EC%86%8C%EA%B0%9C%EC%99%80%EA%B8%B0%EB%8A%A5/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw는 \u003cstrong\u003e멀티채널 AI 에이전트 플랫폼\u003c/strong\u003e이다. 하나의 게이트웨이(Single Gateway)로 WhatsApp, Telegram, Discord, Signal, iMessage, WebChat 등 모든 메시징 채널을 통합 관리한다.\u003c/p\u003e\n\u003cp\u003eAI 에이전트를 한 곳에서 구축하면 30개 이상의 메시징 플랫폼에서 동시에 운영할 수 있다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"핵심-기능\"\u003e핵심 기능\u003c/h2\u003e\n\u003ch3 id=\"1-35-모델-프로바이더-지원\"\u003e1. 35+ 모델 프로바이더 지원\u003c/h3\u003e\n\u003cp\u003e다양한 AI 모델을 즉시 사용할 수 있다.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003eAnthropic\u003c/strong\u003e (Claude 시리즈)\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eOpenAI\u003c/strong\u003e (GPT 시리즈)\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eGoogle\u003c/strong\u003e (Gemini 시리즈)\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eMistral\u003c/strong\u003e, \u003cstrong\u003eGroq\u003c/strong\u003e, \u003cstrong\u003eOpenRouter\u003c/strong\u003e 등\u003c/li\u003e\n\u003cli\u003e자체 호스팅 모델 (Ollama, vLLM, SGLang) 지원\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3 id=\"2-임베디드-에이전트-런타임\"\u003e2. 임베디드 에이전트 런타임\u003c/h3\u003e\n\u003cp\u003e에이전트가 게이트웨이 내부에서 직접 실행된다.\u003c/p\u003e","title":"OpenClaw 소개와 기능"},{"content":"Paperclip은 자율 AI 회사를 위한 컨트롤 플레인입니다. AI 인력이 구조, 거버넌스, 책임성을 갖추고 운영할 수 있게 해주는 인프라 백본입니다.\n하나의 Paperclip 인스턴스로 여러 회사를 운영할 수 있습니다. 각 회사에는 직원(AI 에이전트), 조직 구조, 목표, 예산, 태스크 관리 등 실제 회사에 필요한 모든 것이 갖추어져 있습니다. 단, 운영 체제가 실제 소프트웨어라는 점만 다릅니다.\n문제점 태스크 관리 소프트웨어만으로는 충분하지 않습니다. 전체 인력이 AI 에이전트일 때, 단순한 할 일 목록이 아니라 회사 전체를 위한 컨트롤 플레인이 필요합니다.\nPaperclip이 하는 일 Paperclip은 AI 에이전트 회사의 지휘, 통신, 제어 플레인입니다. 하나의 장소에서 다음을 관리합니다:\n에이전트를 직원으로 관리 — 고용, 조직화, 누가 무엇을 하는지 추적 조직 구조 정의 — 에이전트가 실제로 운영되는 조직도 실시간 작업 추적 — 모든 에이전트가 현재 무엇을 하고 있는지 확인 비용 제어 — 에이전트별 토큰 급여 예산, 지출 추적, 소진율 목표 정렬 — 에이전트가 자신의 작업이 더 큰 미션에 어떻게 기여하는지 파악 자율성 거버넌스 — 보드 승인 게이트, 활동 감사 추적, 예산 집행 두 개의 레이어 1. 컨트롤 플레인 (Paperclip) 중추 신경계입니다. 다음을 관리합니다:\n에이전트 레지스트리 및 조직도 태스크 할당 및 상태 예산 및 토큰 지출 추적 목표 계층 구조 하트비트 모니터링 2. 실행 서비스 (어댑터) 에이전트는 외부에서 실행되고 컨트롤 플레인에 보고합니다. 어댑터가 서로 다른 실행 환경을 연결합니다 — Claude Code, OpenAI Codex, 셸 프로세스, HTTP 웹훅 또는 API를 호출할 수 있는 모든 런타임.\n컨트롤 플레인은 에이전트를 실행하지 않습니다. 오케스트레이션합니다. 에이전트는 자신이 실행되는 곳에서 실행되고 컨트롤 플레인에 보고합니다.\n핵심 원칙 \u0026ldquo;Paperclip을 보면 회사 전체를 한눈에 파악할 수 있어야 합니다 — 누가 무엇을 하고, 얼마나 비용이 들고, 작동하고 있는지.\u0026rdquo;\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/01-paperclip%EC%9D%B4%EB%9E%80/","summary":"\u003cp\u003ePaperclip은 \u003cstrong\u003e자율 AI 회사를 위한 컨트롤 플레인\u003c/strong\u003e입니다. AI 인력이 구조, 거버넌스, 책임성을 갖추고 운영할 수 있게 해주는 인프라 백본입니다.\u003c/p\u003e\n\u003cp\u003e하나의 Paperclip 인스턴스로 \u003cstrong\u003e여러 회사를 운영\u003c/strong\u003e할 수 있습니다. 각 회사에는 직원(AI 에이전트), 조직 구조, 목표, 예산, 태스크 관리 등 실제 회사에 필요한 모든 것이 갖추어져 있습니다. 단, 운영 체제가 실제 소프트웨어라는 점만 다릅니다.\u003c/p\u003e\n\u003ch2 id=\"문제점\"\u003e문제점\u003c/h2\u003e\n\u003cp\u003e태스크 관리 소프트웨어만으로는 충분하지 않습니다. 전체 인력이 AI 에이전트일 때, 단순한 할 일 목록이 아니라 \u003cstrong\u003e회사 전체를 위한 컨트롤 플레인\u003c/strong\u003e이 필요합니다.\u003c/p\u003e","title":"Paperclip이란?"},{"content":"설치부터 첫 메시지 전송까지 약 5분이면 완료된다.\n요구 사항 항목 조건 Node.js 24 권장 (22.14 이상 지원) API 키 Anthropic, OpenAI, Google 중 하나 이상 OS macOS, Linux, Windows 1단계: 설치 macOS / Linux curl -fsSL https://get.openclaw.dev | bash Windows (PowerShell) irm https://get.openclaw.dev/windows | iex 설치가 완료되면 openclaw 명령어를 사용할 수 있다.\n2단계: 온보딩 및 데몬 설치 openclaw onboard --install-daemon 이 명령어는 다음을 수행한다:\n초기 설정 마법사 실행 API 키 입력 (Anthropic, OpenAI, Google 등) 기본 모델 선택 게이트웨이 데몬 설치 및 시작 3단계: 게이트웨이 상태 확인 openclaw gateway status 정상적으로 실행 중이면 게이트웨이가 포트 18789에서 수신 대기 중이라는 메시지가 표시된다.\nGateway running on 127.0.0.1:18789 4단계: 대시보드 열기 openclaw dashboard Control UI가 기본 브라우저에서 열린다. 여기서 에이전트 관리, 채널 연결, 설정 변경 등을 할 수 있다.\n5단계: 첫 메시지 전송 Control UI에서 WebChat을 열고 에이전트에게 첫 메시지를 보낸다.\n또는 CLI에서 직접 메시지를 보낼 수도 있다:\nopenclaw agent --message \u0026#34;안녕하세요, OpenClaw!\u0026#34; 환경 변수 OpenClaw의 동작을 환경 변수로 커스터마이징할 수 있다.\n환경 변수 설명 기본값 OPENCLAW_HOME OpenClaw 홈 디렉토리 ~/.openclaw OPENCLAW_STATE_DIR 상태 데이터 저장 경로 $OPENCLAW_HOME/state OPENCLAW_CONFIG 설정 파일 경로 $OPENCLAW_HOME/openclaw.json 환경 변수 설정 예시 # .bashrc 또는 .zshrc에 추가 export OPENCLAW_HOME=\u0026#34;$HOME/.openclaw\u0026#34; export OPENCLAW_STATE_DIR=\u0026#34;$OPENCLAW_HOME/state\u0026#34; export OPENCLAW_CONFIG=\u0026#34;$OPENCLAW_HOME/openclaw.json\u0026#34; 다음 단계 설치가 완료되었다면 다음 문서를 참고하자:\n게이트웨이 아키텍처 - 게이트웨이 구조 이해 에이전트 런타임 - 에이전트 설정과 커스터마이징 채팅 채널 - WhatsApp, Telegram 등 채널 연결 설정 - 상세 설정 가이드 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/02-%EB%B9%A0%EB%A5%B8%EC%8B%9C%EC%9E%91/","summary":"\u003cp\u003e설치부터 첫 메시지 전송까지 약 \u003cstrong\u003e5분\u003c/strong\u003e이면 완료된다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"요구-사항\"\u003e요구 사항\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e항목\u003c/th\u003e\n          \u003cth\u003e조건\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eNode.js\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e24 권장 (22.14 이상 지원)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eAPI 키\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eAnthropic, OpenAI, Google 중 하나 이상\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eOS\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003emacOS, Linux, Windows\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003chr\u003e\n\u003ch2 id=\"1단계-설치\"\u003e1단계: 설치\u003c/h2\u003e\n\u003ch3 id=\"macos--linux\"\u003emacOS / Linux\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003ecurl -fsSL https://get.openclaw.dev | bash\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch3 id=\"windows-powershell\"\u003eWindows (PowerShell)\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-powershell\" data-lang=\"powershell\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003eirm https\u003cspan style=\"color:#960050;background-color:#1e0010\"\u003e:\u003c/span\u003e//get.openclaw.dev/windows | iex\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e설치가 완료되면 \u003ccode\u003eopenclaw\u003c/code\u003e 명령어를 사용할 수 있다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"2단계-온보딩-및-데몬-설치\"\u003e2단계: 온보딩 및 데몬 설치\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003eopenclaw onboard --install-daemon\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e이 명령어는 다음을 수행한다:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e초기 설정 마법사 실행\u003c/li\u003e\n\u003cli\u003eAPI 키 입력 (Anthropic, OpenAI, Google 등)\u003c/li\u003e\n\u003cli\u003e기본 모델 선택\u003c/li\u003e\n\u003cli\u003e게이트웨이 데몬 설치 및 시작\u003c/li\u003e\n\u003c/ul\u003e\n\u003chr\u003e\n\u003ch2 id=\"3단계-게이트웨이-상태-확인\"\u003e3단계: 게이트웨이 상태 확인\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003eopenclaw gateway status\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e정상적으로 실행 중이면 게이트웨이가 포트 \u003ccode\u003e18789\u003c/code\u003e에서 수신 대기 중이라는 메시지가 표시된다.\u003c/p\u003e","title":"빠른 시작"},{"content":"Paperclip은 자율 AI 작업을 5가지 핵심 개념으로 조직합니다.\n회사 (Company) 회사는 최상위 조직 단위입니다. 각 회사에는 다음이 포함됩니다:\n목표 — 존재 이유 (예: \u0026ldquo;1M MRR로 #1 AI 메모 앱 만들기\u0026rdquo;) 직원 — 모든 직원은 AI 에이전트 조직 구조 — 누가 누구에게 보고하는지 예산 — 센트 단위의 월간 지출 한도 태스크 계층 — 모든 작업이 회사 목표에 연결됨 하나의 Paperclip 인스턴스에서 여러 회사를 운영할 수 있습니다.\n에이전트 (Agents) 모든 직원은 AI 에이전트입니다. 각 에이전트에는 다음이 포함됩니다:\n어댑터 타입 + 설정 — 에이전트 실행 방법 (Claude Code, Codex, 셸 프로세스, HTTP 웹훅) 역할과 보고 체계 — 직함, 상사, 부하직원 능력 — 에이전트가 하는 일에 대한 간단한 설명 예산 — 에이전트별 월간 지출 한도 상태 — active, idle, running, error, paused, terminated 에이전트는 엄격한 트리 계층 구조로 조직됩니다. CEO를 제외한 모든 에이전트는 정확히 한 명의 매니저에게 보고합니다. 이 지휘 체계는 에스컬레이션과 위임에 사용됩니다.\n이슈 (태스크) 이슈는 작업의 단위입니다. 각 이슈에는 다음이 포함됩니다:\n제목, 설명, 상태, 우선순위 담당자 (한 번에 하나의 에이전트) 상위 이슈 (회사 목표까지 추적 가능한 계층 구조) 프로젝트 및 선택적 목표 연결 상태 라이프사이클 backlog → todo → in_progress → in_review → done | blocked 종료 상태: done, cancelled\nin_progress로 전환하려면 원자적 체크아웃이 필요합니다 — 한 번에 하나의 에이전트만 태스크를 소유할 수 있습니다. 두 에이전트가 동시에 같은 태스크를 체크아웃하면 하나는 409 Conflict를 받습니다.\n하트비트 (Heartbeats) 에이전트는 지속적으로 실행되지 않습니다. 하트비트 — Paperclip이 트리거하는 짧은 실행 창에서 깨어납니다.\n하트비트 트리거 방법:\n스케줄 — 주기적 타이머 (예: 매시간) 할당 — 새 태스크가 에이전트에게 할당됨 코멘트 — 누군가 에이전트를 @멘션 수동 — 사용자가 UI에서 \u0026ldquo;실행\u0026rdquo; 클릭 승인 해결 — 대기 중인 승인이 승인/거부됨 각 하트비트에서 에이전트는: 신원 확인 → 할당 검토 → 작업 선택 → 태스크 체크아웃 → 작업 수행 → 상태 업데이트. 이것이 하트비트 프로토콜입니다.\n거버넌스 (Governance) 일부 작업에는 보드(사람)의 승인이 필요합니다:\n에이전트 고용 — 에이전트가 부하를 고용 요청할 수 있지만, 보드가 승인해야 함 CEO 전략 — CEO의 초기 전략 계획은 보드 승인 필요 보드 오버라이드 — 보드가 에이전트를 일시정지, 재개, 종료하고 태스크를 재할당 가능 보드 운영자는 웹 UI를 통해 완전한 가시성과 제어권을 가집니다. 모든 변경은 활동 감사 추적에 기록됩니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/02-%ED%95%B5%EC%8B%AC%EA%B0%9C%EB%85%90/","summary":"\u003cp\u003ePaperclip은 자율 AI 작업을 5가지 핵심 개념으로 조직합니다.\u003c/p\u003e\n\u003ch2 id=\"회사-company\"\u003e회사 (Company)\u003c/h2\u003e\n\u003cp\u003e회사는 최상위 조직 단위입니다. 각 회사에는 다음이 포함됩니다:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e목표\u003c/strong\u003e — 존재 이유 (예: \u0026ldquo;1M MRR로 #1 AI 메모 앱 만들기\u0026rdquo;)\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e직원\u003c/strong\u003e — 모든 직원은 AI 에이전트\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e조직 구조\u003c/strong\u003e — 누가 누구에게 보고하는지\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e예산\u003c/strong\u003e — 센트 단위의 월간 지출 한도\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e태스크 계층\u003c/strong\u003e — 모든 작업이 회사 목표에 연결됨\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e하나의 Paperclip 인스턴스에서 여러 회사를 운영할 수 있습니다.\u003c/p\u003e\n\u003ch2 id=\"에이전트-agents\"\u003e에이전트 (Agents)\u003c/h2\u003e\n\u003cp\u003e모든 직원은 AI 에이전트입니다. 각 에이전트에는 다음이 포함됩니다:\u003c/p\u003e","title":"핵심 개념"},{"content":"개요 OpenClaw의 핵심은 **단일 장기 실행 게이트웨이(Single Long-lived Gateway)**이다. 이 게이트웨이 하나가 모든 메시징 채널을 관리한다.\n주요 구성 요소 1. Gateway (데몬) 게이트웨이는 백그라운드 데몬으로 실행되며 다음을 담당한다:\n프로바이더 연결 유지: AI 모델 프로바이더와의 연결을 지속적으로 관리 타입드 WebSocket API 제공: 모든 통신이 WebSocket을 통해 이루어짐 JSON Schema 프레임 검증: 송수신되는 모든 프레임을 JSON Schema로 검증 세션 관리: 에이전트별 세션 생성, 유지, 정리 인증 처리: 토큰 기반 접근 제어 기본 리스닝 주소:\n127.0.0.1:18789 2. Clients (클라이언트) 클라이언트는 게이트웨이에 연결하는 제어 평면(Control-plane) 인터페이스이다.\n클라이언트 설명 macOS 앱 메뉴바 앱으로 빠른 접근 CLI 터미널 명령어 인터페이스 Web UI 브라우저 기반 Control UI 모든 클라이언트는 WebSocket으로 127.0.0.1:18789에 연결한다.\n3. Nodes (노드) 노드는 role:node로 연결하는 디바이스이다.\niOS/Android 모바일 디바이스 원격 서버 IoT 디바이스 노드는 에이전트의 확장 인터페이스로 동작하며 메시지를 수발신한다.\n와이어 프로토콜 게이트웨이와 클라이언트 간 통신은 WebSocket/JSON 프로토콜을 사용한다.\n연결 흐름 클라이언트가 WebSocket 연결을 설정 첫 번째 프레임은 반드시 connect 메시지여야 함 게이트웨이가 연결을 검증하고 세션을 할당 이후 양방향 메시지 교환 connect 프레임 예시 { \u0026#34;type\u0026#34;: \u0026#34;connect\u0026#34;, \u0026#34;role\u0026#34;: \u0026#34;client\u0026#34;, \u0026#34;token\u0026#34;: \u0026#34;\u0026lt;OPENCLAW_GATEWAY_TOKEN\u0026gt;\u0026#34; } 프레임 검증 모든 프레임은 JSON Schema로 검증된다. 잘못된 형식의 프레임은 거부되며 오류 메시지가 반환된다.\n인증 게이트웨이 토큰 게이트웨이 접근은 OPENCLAW_GATEWAY_TOKEN 환경 변수로 제어한다.\nexport OPENCLAW_GATEWAY_TOKEN=\u0026#34;your-secret-token\u0026#34; 토큰이 설정되면 모든 클라이언트와 노드는 연결 시 이 토큰을 제공해야 한다.\n로컬 접근 기본적으로 게이트웨이는 127.0.0.1에서만 수신하므로 로컬 머신에서만 접근 가능하다.\n원격 접근 외부에서 게이트웨이에 접근해야 하는 경우, 직접 포트를 열지 말고 다음 방법을 사용할 것을 권장한다.\nTailscale (권장) # Tailscale을 통해 안전하게 원격 접근 tailscale up # 이후 Tailscale IP로 게이트웨이 접근 SSH 터널링 # 원격 서버의 게이트웨이를 로컬로 포워딩 ssh -L 18789:127.0.0.1:18789 user@remote-server 주의: 게이트웨이 포트를 공용 인터넷에 직접 노출하지 않도록 한다. 반드시 Tailscale이나 SSH 터널링을 사용하여 보안을 유지한다.\n아키텍처 다이어그램 ┌──────────────────────────────────────────────┐ │ Gateway │ │ 127.0.0.1:18789 │ │ │ │ ┌─────────┐ ┌─────────┐ ┌──────────────┐ │ │ │ Provider │ │ Session │ │ Frame │ │ │ │ Manager │ │ Manager │ │ Validator │ │ │ └─────────┘ └─────────┘ └──────────────┘ │ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ WebSocket API (JSON) │ │ │ └─────────────────────────────────────────┘ │ └──────────┬──────────┬──────────┬─────────────┘ │ │ │ ┌──────┴──┐ ┌─────┴───┐ ┌───┴──────┐ │ macOS │ │ CLI │ │ Web UI │ │ App │ │ │ │ │ └─────────┘ └─────────┘ └──────────┘ (client) (client) (client) │ ┌──────┴──────┐ │ Mobile │ │ Node │ │ (role:node) │ └─────────────┘ ","permalink":"https://jungwoo0716.github.io/docs/openclaw/03-%EA%B2%8C%EC%9D%B4%ED%8A%B8%EC%9B%A8%EC%9D%B4%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw의 핵심은 **단일 장기 실행 게이트웨이(Single Long-lived Gateway)**이다. 이 게이트웨이 하나가 모든 메시징 채널을 관리한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"주요-구성-요소\"\u003e주요 구성 요소\u003c/h2\u003e\n\u003ch3 id=\"1-gateway-데몬\"\u003e1. Gateway (데몬)\u003c/h3\u003e\n\u003cp\u003e게이트웨이는 백그라운드 데몬으로 실행되며 다음을 담당한다:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e프로바이더 연결 유지\u003c/strong\u003e: AI 모델 프로바이더와의 연결을 지속적으로 관리\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e타입드 WebSocket API 제공\u003c/strong\u003e: 모든 통신이 WebSocket을 통해 이루어짐\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eJSON Schema 프레임 검증\u003c/strong\u003e: 송수신되는 모든 프레임을 JSON Schema로 검증\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e세션 관리\u003c/strong\u003e: 에이전트별 세션 생성, 유지, 정리\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e인증 처리\u003c/strong\u003e: 토큰 기반 접근 제어\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e기본 리스닝 주소:\u003c/p\u003e","title":"게이트웨이 아키텍처"},{"content":"5분 이내에 Paperclip을 로컬에서 실행하세요.\n빠른 시작 (권장) npx paperclipai onboard --yes 설정을 안내하고, 환경을 구성하고, Paperclip을 실행합니다.\n로컬 개발 사전 요구사항: Node.js 20+, pnpm 9+\npnpm install pnpm dev API 서버와 UI가 http://localhost:3100에서 시작됩니다. 외부 데이터베이스 불필요 — Paperclip은 기본적으로 임베디드 PostgreSQL을 사용합니다.\n원커맨드 부트스트랩 pnpm paperclipai run 설정이 없으면 자동 온보딩하고, 헬스체크를 자동 복구하며, 서버를 시작합니다.\n다음 단계 웹 UI에서 첫 번째 회사 생성 회사 목표 정의 CEO 에이전트 생성 및 어댑터 설정 더 많은 에이전트로 조직도 구축 예산 설정 및 초기 태스크 할당 실행 — 에이전트가 하트비트를 시작하고 회사가 운영됨 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/03-%EB%B9%A0%EB%A5%B8%EC%8B%9C%EC%9E%91/","summary":"\u003cp\u003e5분 이내에 Paperclip을 로컬에서 실행하세요.\u003c/p\u003e\n\u003ch2 id=\"빠른-시작-권장\"\u003e빠른 시작 (권장)\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003enpx paperclipai onboard --yes\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e설정을 안내하고, 환경을 구성하고, Paperclip을 실행합니다.\u003c/p\u003e\n\u003ch2 id=\"로컬-개발\"\u003e로컬 개발\u003c/h2\u003e\n\u003cp\u003e\u003cstrong\u003e사전 요구사항:\u003c/strong\u003e Node.js 20+, pnpm 9+\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm install\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm dev\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003eAPI 서버와 UI가 \u003ccode\u003ehttp://localhost:3100\u003c/code\u003e에서 시작됩니다. 외부 데이터베이스 불필요 — Paperclip은 기본적으로 임베디드 PostgreSQL을 사용합니다.\u003c/p\u003e\n\u003ch2 id=\"원커맨드-부트스트랩\"\u003e원커맨드 부트스트랩\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai run\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e설정이 없으면 자동 온보딩하고, 헬스체크를 자동 복구하며, 서버를 시작합니다.\u003c/p\u003e\n\u003ch2 id=\"다음-단계\"\u003e다음 단계\u003c/h2\u003e\n\u003col\u003e\n\u003cli\u003e웹 UI에서 첫 번째 회사 생성\u003c/li\u003e\n\u003cli\u003e회사 목표 정의\u003c/li\u003e\n\u003cli\u003eCEO 에이전트 생성 및 어댑터 설정\u003c/li\u003e\n\u003cli\u003e더 많은 에이전트로 조직도 구축\u003c/li\u003e\n\u003cli\u003e예산 설정 및 초기 태스크 할당\u003c/li\u003e\n\u003cli\u003e실행 — 에이전트가 하트비트를 시작하고 회사가 운영됨\u003c/li\u003e\n\u003c/ol\u003e","title":"빠른 시작"},{"content":"Paperclip은 4개의 주요 레이어를 가진 모노레포입니다.\n스택 개요 ┌─────────────────────────────────────┐ │ React UI (Vite) │ │ 대시보드, 조직 관리, 태스크 │ ├─────────────────────────────────────┤ │ Express.js REST API (Node.js) │ │ 라우트, 서비스, 인증, 어댑터 │ ├─────────────────────────────────────┤ │ PostgreSQL (Drizzle ORM) │ │ 스키마, 마이그레이션, 임베디드 모드 │ ├─────────────────────────────────────┤ │ 어댑터 │ │ Claude, Codex, Gemini, Cursor, │ │ OpenCode, OpenClaw, Hermes, │ │ Process, HTTP │ └─────────────────────────────────────┘ 기술 스택 레이어 기술 프론트엔드 React 19, Vite 6, React Router 7, Radix UI, Tailwind CSS 4, TanStack Query 백엔드 Node.js 20+, Express.js 5, TypeScript 데이터베이스 PostgreSQL 17 (또는 임베디드 PGlite), Drizzle ORM 인증 Better Auth (세션 + API 키) 어댑터 Claude Code CLI, Codex CLI, Gemini CLI, Cursor CLI, OpenCode CLI, OpenClaw Gateway, Hermes, 셸 프로세스, HTTP 웹훅 패키지 매니저 pnpm 9 (워크스페이스) 레포지토리 구조 paperclip/ ├── ui/ # React 프론트엔드 │ ├── src/pages/ # 라우트 페이지 │ ├── src/components/ # React 컴포넌트 │ ├── src/api/ # API 클라이언트 │ └── src/context/ # React 컨텍스트 프로바이더 │ ├── server/ # Express.js API │ ├── src/routes/ # REST 엔드포인트 │ ├── src/services/ # 비즈니스 로직 │ ├── src/adapters/ # 에이전트 실행 어댑터 │ └── src/middleware/ # 인증, 로깅 │ ├── packages/ │ ├── db/ # Drizzle 스키마 + 마이그레이션 │ ├── shared/ # API 타입, 상수, 밸리데이터 │ ├── adapter-utils/ # 어댑터 인터페이스 및 헬퍼 │ └── adapters/ # 각 어댑터 패키지 │ ├── skills/ # 에이전트 스킬 ├── cli/ # CLI 클라이언트 └── doc/ # 내부 문서 요청 흐름 하트비트가 발생하면:\n트리거 — 스케줄러, 수동 실행 또는 이벤트(할당, 멘션)가 하트비트 트리거 어댑터 호출 — 서버가 설정된 어댑터의 execute() 함수 호출 에이전트 프로세스 — 어댑터가 에이전트(예: Claude Code CLI)를 Paperclip 환경변수와 프롬프트로 생성 에이전트 작업 — 에이전트가 Paperclip REST API를 호출하여 할당 확인, 태스크 체크아웃, 작업 수행, 상태 업데이트 결과 캡처 — 어댑터가 stdout 캡처, 사용량/비용 데이터 파싱, 세션 상태 추출 실행 기록 — 서버가 실행 결과, 비용, 다음 하트비트를 위한 세션 상태 기록 어댑터 모델 어댑터는 Paperclip과 에이전트 런타임 사이의 브릿지입니다. 각 어댑터는 3개의 모듈을 가진 패키지입니다:\n서버 모듈 — 에이전트를 생성/호출하는 execute() 함수 + 환경 진단 UI 모듈 — 실행 뷰어용 stdout 파서, 에이전트 생성 설정 폼 필드 CLI 모듈 — paperclipai run --watch용 터미널 포맷터 핵심 설계 결정 컨트롤 플레인, 실행 플레인 아님 — Paperclip은 에이전트를 오케스트레이션하지 실행하지 않음 회사 범위 — 모든 엔티티는 정확히 하나의 회사에 속함; 엄격한 데이터 경계 단일 담당자 태스크 — 원자적 체크아웃으로 동시 작업 방지 어댑터 불가지론 — HTTP API를 호출할 수 있는 모든 런타임이 에이전트로 작동 기본 임베디드 — 임베디드 PostgreSQL로 설정 없이 로컬 모드 지원 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/04-%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98/","summary":"\u003cp\u003ePaperclip은 4개의 주요 레이어를 가진 모노레포입니다.\u003c/p\u003e\n\u003ch2 id=\"스택-개요\"\u003e스택 개요\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003e┌─────────────────────────────────────┐\n│  React UI (Vite)                    │\n│  대시보드, 조직 관리, 태스크         │\n├─────────────────────────────────────┤\n│  Express.js REST API (Node.js)      │\n│  라우트, 서비스, 인증, 어댑터        │\n├─────────────────────────────────────┤\n│  PostgreSQL (Drizzle ORM)           │\n│  스키마, 마이그레이션, 임베디드 모드  │\n├─────────────────────────────────────┤\n│  어댑터                              │\n│  Claude, Codex, Gemini, Cursor,     │\n│  OpenCode, OpenClaw, Hermes,        │\n│  Process, HTTP                      │\n└─────────────────────────────────────┘\n\u003c/code\u003e\u003c/pre\u003e\u003ch2 id=\"기술-스택\"\u003e기술 스택\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e레이어\u003c/th\u003e\n          \u003cth\u003e기술\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e프론트엔드\u003c/td\u003e\n          \u003ctd\u003eReact 19, Vite 6, React Router 7, Radix UI, Tailwind CSS 4, TanStack Query\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e백엔드\u003c/td\u003e\n          \u003ctd\u003eNode.js 20+, Express.js 5, TypeScript\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e데이터베이스\u003c/td\u003e\n          \u003ctd\u003ePostgreSQL 17 (또는 임베디드 PGlite), Drizzle ORM\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e인증\u003c/td\u003e\n          \u003ctd\u003eBetter Auth (세션 + API 키)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e어댑터\u003c/td\u003e\n          \u003ctd\u003eClaude Code CLI, Codex CLI, Gemini CLI, Cursor CLI, OpenCode CLI, OpenClaw Gateway, Hermes, 셸 프로세스, HTTP 웹훅\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e패키지 매니저\u003c/td\u003e\n          \u003ctd\u003epnpm 9 (워크스페이스)\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"레포지토리-구조\"\u003e레포지토리 구조\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003epaperclip/\n├── ui/                          # React 프론트엔드\n│   ├── src/pages/              # 라우트 페이지\n│   ├── src/components/         # React 컴포넌트\n│   ├── src/api/                # API 클라이언트\n│   └── src/context/            # React 컨텍스트 프로바이더\n│\n├── server/                      # Express.js API\n│   ├── src/routes/             # REST 엔드포인트\n│   ├── src/services/           # 비즈니스 로직\n│   ├── src/adapters/           # 에이전트 실행 어댑터\n│   └── src/middleware/         # 인증, 로깅\n│\n├── packages/\n│   ├── db/                      # Drizzle 스키마 + 마이그레이션\n│   ├── shared/                  # API 타입, 상수, 밸리데이터\n│   ├── adapter-utils/           # 어댑터 인터페이스 및 헬퍼\n│   └── adapters/               # 각 어댑터 패키지\n│\n├── skills/                      # 에이전트 스킬\n├── cli/                         # CLI 클라이언트\n└── doc/                         # 내부 문서\n\u003c/code\u003e\u003c/pre\u003e\u003ch2 id=\"요청-흐름\"\u003e요청 흐름\u003c/h2\u003e\n\u003cp\u003e하트비트가 발생하면:\u003c/p\u003e","title":"아키텍처"},{"content":"개요 OpenClaw는 단일 임베디드 에이전트 런타임을 제공한다. 에이전트는 게이트웨이 내부에서 직접 실행되며, 워크스페이스 디렉토리의 마크다운 파일을 통해 설정된다.\n워크스페이스 구조 각 에이전트는 워크스페이스 디렉토리를 가지며, 다음 부트스트랩 파일들로 구성된다:\nworkspace/ ├── AGENTS.md # 에이전트 지시사항 + 메모리 ├── SOUL.md # 에이전트 페르소나 (성격, 말투) ├── TOOLS.md # 사용 가능한 도구 문서 ├── BOOTSTRAP.md # 초기 설정 지시사항 ├── IDENTITY.md # 에이전트 이름 및 정체성 ├── USER.md # 사용자 프로필 정보 └── memory/ # 일별 메모리 파일 ├── MEMORY.md └── YYYY-MM-DD.md 각 파일의 역할 AGENTS.md 에이전트의 핵심 지시사항과 장기 메모리를 담는 파일이다.\n# My Agent ## 지시사항 - 항상 한국어로 응답 - 비즈니스 톤 유지 - 코드 관련 질문에 상세히 답변 ## 메모리 - 사용자는 Next.js 프로젝트를 진행 중 - 선호 모델: Claude Sonnet SOUL.md 에이전트의 페르소나를 정의한다. 성격, 말투, 행동 원칙 등을 기술한다.\n# 페르소나 당신은 친절하고 전문적인 개발 도우미입니다. 기술 용어는 정확히 사용하되, 설명은 쉽게 합니다. TOOLS.md 에이전트가 사용할 수 있는 도구의 문서를 기술한다.\nBOOTSTRAP.md 에이전트가 최초 세션에서 실행해야 할 초기 설정 지시사항이다.\nIDENTITY.md 에이전트의 이름과 정체성 정보를 정의한다.\nUSER.md 대화 상대인 사용자의 프로필 정보를 담는다.\n부트스트랩 인젝션 세션의 첫 번째 턴에서 부트스트랩 파일들이 에이전트 컨텍스트에 주입된다.\n인젝션 순서:\nIDENTITY.md - 에이전트 정체성 SOUL.md - 페르소나 AGENTS.md - 지시사항과 메모리 TOOLS.md - 도구 문서 USER.md - 사용자 프로필 BOOTSTRAP.md - 초기 설정 이 파일들은 시스템 프롬프트의 일부로 삽입되어 에이전트의 동작을 정의한다.\n세션 관리 세션 저장 형식 세션은 JSONL (JSON Lines) 형식으로 저장된다.\n~/.openclaw/agents/\u0026lt;agentId\u0026gt;/sessions/ ├── \u0026lt;sessionId\u0026gt;.jsonl ├── \u0026lt;sessionId\u0026gt;.jsonl └── ... 각 줄은 하나의 메시지 또는 이벤트를 나타내는 JSON 객체이다.\n세션 격리 각 에이전트는 독립된 세션 공간을 가진다. 서로 다른 에이전트의 세션은 격리되어 있어 데이터가 섞이지 않는다.\n스킬 로딩 에이전트가 사용하는 스킬은 다음 우선순위로 로드된다:\n워크스페이스 스킬 (최고 우선순위) - 에이전트 워크스페이스 내 스킬 관리형 스킬 (managed) - openclaw skills install로 설치한 스킬 번들 스킬 (bundled) - OpenClaw에 기본 내장된 스킬 워크스페이스 스킬이 가장 높은 우선순위를 가지므로, 기본 스킬을 오버라이드할 수 있다.\n에이전트 디렉토리 구조 ~/.openclaw/ ├── openclaw.json # 글로벌 설정 ├── agents/ │ ├── default/ │ │ ├── workspace/ # 워크스페이스 파일들 │ │ │ ├── AGENTS.md │ │ │ ├── SOUL.md │ │ │ └── ... │ │ └── sessions/ # 세션 JSONL 파일들 │ │ └── *.jsonl │ └── custom-agent/ │ ├── workspace/ │ └── sessions/ └── skills/ # 설치된 스킬 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/04-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EB%9F%B0%ED%83%80%EC%9E%84/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw는 \u003cstrong\u003e단일 임베디드 에이전트 런타임\u003c/strong\u003e을 제공한다. 에이전트는 게이트웨이 내부에서 직접 실행되며, 워크스페이스 디렉토리의 마크다운 파일을 통해 설정된다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"워크스페이스-구조\"\u003e워크스페이스 구조\u003c/h2\u003e\n\u003cp\u003e각 에이전트는 워크스페이스 디렉토리를 가지며, 다음 부트스트랩 파일들로 구성된다:\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eworkspace/\n├── AGENTS.md       # 에이전트 지시사항 + 메모리\n├── SOUL.md         # 에이전트 페르소나 (성격, 말투)\n├── TOOLS.md        # 사용 가능한 도구 문서\n├── BOOTSTRAP.md    # 초기 설정 지시사항\n├── IDENTITY.md     # 에이전트 이름 및 정체성\n├── USER.md         # 사용자 프로필 정보\n└── memory/         # 일별 메모리 파일\n    ├── MEMORY.md\n    └── YYYY-MM-DD.md\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"각-파일의-역할\"\u003e각 파일의 역할\u003c/h3\u003e\n\u003ch4 id=\"agentsmd\"\u003eAGENTS.md\u003c/h4\u003e\n\u003cp\u003e에이전트의 핵심 지시사항과 장기 메모리를 담는 파일이다.\u003c/p\u003e","title":"에이전트 런타임"},{"content":"개요 에이전트 루프는 사용자 메시지가 들어오고 응답이 생성되기까지의 전체 실행 경로를 정의한다. 각 단계가 순차적으로 실행되며, 도구 호출이 필요하면 루프가 반복된다.\n실행 경로 intake → context assembly → model inference → tool execution → streaming replies → persistence 상세 흐름 ┌─────────────┐ │ Intake │ 메시지 수신 및 검증 └──────┬──────┘ │ ┌──────▼──────┐ │ Context │ 컨텍스트 조립 (부트스트랩 + 히스토리 + 토큰 예산) │ Assembly │ └──────┬──────┘ │ ┌──────▼──────┐ │ Model │ AI 모델 추론 요청 │ Inference │ └──────┬──────┘ │ ┌──────▼──────┐ │ Tool │ 도구 호출 필요 시 실행 │ Execution │ (없으면 건너뜀) └──────┬──────┘ │ ┌──────▼──────┐ │ Streaming │ 응답을 실시간 스트리밍 │ Replies │ └──────┬──────┘ │ ┌──────▼──────┐ │ Persistence │ 세션에 결과 저장 └─────────────┘ 진입점 (Entry Points) 에이전트 루프를 시작하는 두 가지 방법이 있다.\n1. Gateway RPC 게이트웨이 WebSocket API를 통한 호출:\nagent: 비동기 에이전트 실행 (스트리밍 응답) agent.wait: 동기 에이전트 실행 (완료까지 대기) 2. CLI agent 명령어 openclaw agent --message \u0026#34;작업을 수행해주세요\u0026#34; 실행 단계 상세 1. Validation (검증) 메시지 형식 검증 세션 존재 여부 확인 권한 확인 2. Resolve Model/Skills (모델 및 스킬 해석) 에이전트 설정에서 사용할 모델 결정 스킬 로딩 우선순위에 따라 사용 가능한 스킬 해석 도구 목록 구성 3. Run Runtime (런타임 실행) 컨텍스트 엔진으로 메시지 세트 구성 토큰 예산 내에서 히스토리 포함 AI 모델에 추론 요청 4. Stream Events (이벤트 스트리밍) 루프 실행 중 다음 유형의 이벤트가 스트리밍된다:\n이벤트 유형 설명 tool 도구 호출 및 결과 assistant 에이전트 텍스트 응답 (청크 단위) lifecycle 루프 상태 변경 (시작, 종료, 오류) 5. Completion (완료) 모든 도구 호출이 완료되고 최종 응답이 생성되면 루프 종료 세션 JSONL 파일에 결과 저장 세션 직렬화 동일 세션 키에 대한 실행은 **직렬화(serialize)**된다. 즉, 같은 세션에서 여러 메시지가 동시에 들어와도 순서대로 하나씩 처리된다.\n세션 A: 메시지1 → [처리 중] → 메시지2 → [대기] → [처리 중] → ... 세션 B: 메시지1 → [처리 중] → ... (A와 독립적으로 병렬 실행) 이는 컨텍스트 일관성을 보장하기 위함이다.\n훅 시스템 에이전트 루프의 특정 시점에 커스텀 로직을 삽입할 수 있다.\nInternal Gateway Hooks (내부 게이트웨이 훅) 게이트웨이 레벨에서 동작하는 내장 훅이다. 메시지 전처리, 후처리, 라우팅 결정 등에 사용된다.\nPlugin Hooks (플러그인 훅) 외부 플러그인이 등록하는 훅이다. 에이전트 루프의 각 단계에 개입하여 동작을 확장할 수 있다.\n훅을 사용하면 다음과 같은 작업이 가능하다:\n메시지 수신 시 전처리 (필터링, 변환) 도구 호출 전후 로깅 응답 후처리 (포맷 변환, 알림) 에러 발생 시 커스텀 처리 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/05-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EB%A3%A8%ED%94%84/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e에이전트 루프는 사용자 메시지가 들어오고 응답이 생성되기까지의 전체 실행 경로를 정의한다. 각 단계가 순차적으로 실행되며, 도구 호출이 필요하면 루프가 반복된다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"실행-경로\"\u003e실행 경로\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eintake → context assembly → model inference → tool execution → streaming replies → persistence\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"상세-흐름\"\u003e상세 흐름\u003c/h3\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003e┌─────────────┐\n│   Intake    │  메시지 수신 및 검증\n└──────┬──────┘\n       │\n┌──────▼──────┐\n│  Context    │  컨텍스트 조립 (부트스트랩 + 히스토리 + 토큰 예산)\n│  Assembly   │\n└──────┬──────┘\n       │\n┌──────▼──────┐\n│   Model     │  AI 모델 추론 요청\n│  Inference  │\n└──────┬──────┘\n       │\n┌──────▼──────┐\n│    Tool     │  도구 호출 필요 시 실행\n│  Execution  │  (없으면 건너뜀)\n└──────┬──────┘\n       │\n┌──────▼──────┐\n│  Streaming  │  응답을 실시간 스트리밍\n│   Replies   │\n└──────┬──────┘\n       │\n┌──────▼──────┐\n│ Persistence │  세션에 결과 저장\n└─────────────┘\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"진입점-entry-points\"\u003e진입점 (Entry Points)\u003c/h2\u003e\n\u003cp\u003e에이전트 루프를 시작하는 두 가지 방법이 있다.\u003c/p\u003e","title":"에이전트 루프"},{"content":"회사는 Paperclip의 기본 조직 단위입니다. 에이전트, 태스크, 목표, 예산의 컨테이너 역할을 합니다.\n단계 1: 회사 생성 웹 UI에서 \u0026ldquo;새 회사\u0026quot;를 선택하고 입력합니다:\n이름 (필수) 설명 (선택, 권장) 단계 2: 목표 설정 모든 회사에는 목표가 필요합니다 — 모든 작업이 추적되는 북극성입니다.\n예시:\n\u0026ldquo;3개월 내 $1M MRR로 #1 AI 메모 앱 만들기\u0026rdquo; \u0026ldquo;Q2까지 10개 클라이언트를 서비스하는 마케팅 에이전시 만들기\u0026rdquo; Goals 섹션에서 최상위 회사 목표를 설정합니다.\n단계 3: CEO 에이전트 생성 초기 에이전트 설정:\n이름: CEO (권장) 역할: ceo 어댑터 타입: Claude Local (권장) 프롬프트 템플릿: 지시사항 월간 예산: 센트 단위로 할당 단계 4: 조직도 구축 직속 부하를 추가합니다 (예: CTO, CMO). 각각 고유한 어댑터 설정, 역할, 예산을 가집니다.\n조직 트리는 엄격한 계층 구조를 강제합니다 — 모든 에이전트는 정확히 한 명의 매니저에게 보고합니다.\n단계 5: 예산 설정 Paperclip이 강제하는 기준:\n80% 사용률: 소프트 경고 100% 사용률: 하드 스톱 — 에이전트 자동 일시정지 단계 6: 실행 하트비트를 활성화하면 에이전트가 작업을 시작합니다. 대시보드에서 모니터링합니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/05-%ED%9A%8C%EC%82%AC%EB%A7%8C%EB%93%A4%EA%B8%B0/","summary":"\u003cp\u003e회사는 Paperclip의 기본 조직 단위입니다. 에이전트, 태스크, 목표, 예산의 컨테이너 역할을 합니다.\u003c/p\u003e\n\u003ch2 id=\"단계-1-회사-생성\"\u003e단계 1: 회사 생성\u003c/h2\u003e\n\u003cp\u003e웹 UI에서 \u0026ldquo;새 회사\u0026quot;를 선택하고 입력합니다:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e이름\u003c/strong\u003e (필수)\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e설명\u003c/strong\u003e (선택, 권장)\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"단계-2-목표-설정\"\u003e단계 2: 목표 설정\u003c/h2\u003e\n\u003cp\u003e모든 회사에는 목표가 필요합니다 — 모든 작업이 추적되는 북극성입니다.\u003c/p\u003e\n\u003cp\u003e\u003cstrong\u003e예시:\u003c/strong\u003e\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u0026ldquo;3개월 내 $1M MRR로 #1 AI 메모 앱 만들기\u0026rdquo;\u003c/li\u003e\n\u003cli\u003e\u0026ldquo;Q2까지 10개 클라이언트를 서비스하는 마케팅 에이전시 만들기\u0026rdquo;\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eGoals 섹션에서 최상위 회사 목표를 설정합니다.\u003c/p\u003e\n\u003ch2 id=\"단계-3-ceo-에이전트-생성\"\u003e단계 3: CEO 에이전트 생성\u003c/h2\u003e\n\u003cp\u003e초기 에이전트 설정:\u003c/p\u003e","title":"회사 만들기"},{"content":"에이전트 상태 상태 설명 active 작업을 받을 준비 완료 idle 활성이지만 현재 하트비트 실행 없음 running 현재 하트비트 실행 중 error 마지막 하트비트 실패 paused 수동 일시정지 또는 예산 초과로 일시정지 terminated 영구 비활성화 (되돌릴 수 없음) 에이전트 생성 요소 이름 — @멘션을 위한 고유 식별자 역할 — ceo, cto, manager, engineer, researcher 등 보고 대상 — 조직 트리에서의 매니저 어댑터 타입 — 실행 방법 어댑터 설정 — 작업 디렉토리, 모델, 프롬프트 등 런타임별 설정 능력 — 기능 설명 거버넌스 기반 고용 에이전트가 부하를 고용 요청할 수 있습니다. 이 경우 승인 큐에 hire_agent 승인이 나타납니다.\n설정 옵션 편집 가능한 설정:\n어댑터 설정: 모델, 프롬프트, 디렉토리, 변수 하트비트 설정: 주기, 쿨다운, 최대 동시 실행, 트리거 월간 예산 한도 \u0026ldquo;환경 테스트\u0026rdquo; 버튼으로 설정을 검증할 수 있습니다.\n제어 작업 일시정지/재개 POST /api/agents/{agentId}/pause POST /api/agents/{agentId}/resume 에이전트는 월간 예산의 100%에 도달하면 자동 일시정지됩니다.\n종료 POST /api/agents/{agentId}/terminate 종료는 영구적이고 되돌릴 수 없습니다. 종료 전에 일시정지를 권장합니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/06-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EA%B4%80%EB%A6%AC/","summary":"\u003ch2 id=\"에이전트-상태\"\u003e에이전트 상태\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e상태\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eactive\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e작업을 받을 준비 완료\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eidle\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e활성이지만 현재 하트비트 실행 없음\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003erunning\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e현재 하트비트 실행 중\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eerror\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e마지막 하트비트 실패\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003epaused\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e수동 일시정지 또는 예산 초과로 일시정지\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eterminated\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e영구 비활성화 (되돌릴 수 없음)\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"에이전트-생성-요소\"\u003e에이전트 생성 요소\u003c/h2\u003e\n\u003col\u003e\n\u003cli\u003e\u003cstrong\u003e이름\u003c/strong\u003e — @멘션을 위한 고유 식별자\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e역할\u003c/strong\u003e — ceo, cto, manager, engineer, researcher 등\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e보고 대상\u003c/strong\u003e — 조직 트리에서의 매니저\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e어댑터 타입\u003c/strong\u003e — 실행 방법\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e어댑터 설정\u003c/strong\u003e — 작업 디렉토리, 모델, 프롬프트 등 런타임별 설정\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e능력\u003c/strong\u003e — 기능 설명\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch2 id=\"거버넌스-기반-고용\"\u003e거버넌스 기반 고용\u003c/h2\u003e\n\u003cp\u003e에이전트가 부하를 고용 요청할 수 있습니다. 이 경우 승인 큐에 \u003ccode\u003ehire_agent\u003c/code\u003e 승인이 나타납니다.\u003c/p\u003e","title":"에이전트 관리"},{"content":"개요 컨텍스트 엔진은 각 에이전트 실행(run)에서 모델 컨텍스트 구성을 담당한다. 대화 히스토리, 시스템 프롬프트, 도구 결과 등을 토큰 예산 내에서 최적으로 조합하여 모델에 전달한다.\n4단계 생명주기 컨텍스트 엔진은 4개의 생명주기 포인트에서 동작한다.\n1. Ingest (수집) 새로운 메시지를 처리하는 단계이다.\n사용자 메시지, 도구 결과 등 새로 들어온 데이터 수집 메시지 형식 정규화 메타데이터 부착 (타임스탬프, 소스 등) 2. Assemble (조립) 토큰 예산에 맞게 메시지 세트를 구성하는 단계이다.\n순서에 맞게 메시지 정렬 토큰 예산 계산 예산 초과 시 오래된 메시지부터 제외 시스템 프롬프트, 부트스트랩 파일, 사용자 메시지, 도구 결과 등을 합산 ┌─────────────────────────────────────────┐ │ 토큰 예산 │ │ │ │ [시스템 프롬프트] ← 항상 포함 │ │ [부트스트랩 파일] ← 첫 턴에 포함 │ │ [요약된 히스토리] ← 압축된 과거 대화 │ │ [최근 대화] ← 가능한 많이 포함 │ │ [새 메시지] ← 항상 포함 │ │ │ └─────────────────────────────────────────┘ 3. Compact (압축) 오래된 히스토리를 요약하는 단계이다.\n토큰 예산을 초과하는 과거 대화를 자동 요약 요약본을 컨텍스트에 포함하여 장기 대화 지원 메모리 플러싱(flushing)이 압축 전에 자동 실행됨 4. After Turn (턴 이후) 에이전트 실행이 완료된 후 처리하는 단계이다.\n세션 데이터 업데이트 메모리 파일 업데이트 (필요한 경우) 통계 기록 내장 엔진: Legacy OpenClaw에는 **\u0026ldquo;legacy\u0026rdquo;**라는 내장 컨텍스트 엔진이 기본 제공된다.\n기본적인 토큰 카운팅과 히스토리 잘라내기 자동 요약(compaction) 지원 대부분의 사용 사례에 충분 플러그인 엔진 더 고급 컨텍스트 관리가 필요한 경우 플러그인 엔진을 설치할 수 있다.\nopenclaw plugins install \u0026lt;engine-name\u0026gt; 주의사항 한 번에 하나의 엔진만 활성화 가능하다 플러그인 엔진을 설정하면 내장 legacy 엔진 대신 사용됨 에이전트별로 다른 엔진을 지정할 수 있음 엔진 설정 예시 설정 파일에서 컨텍스트 엔진을 지정한다:\n{ \u0026#34;agents\u0026#34;: { \u0026#34;default\u0026#34;: { \u0026#34;contextEngine\u0026#34;: \u0026#34;legacy\u0026#34; // 또는 플러그인 엔진 이름 } } } 토큰 예산 관리 컨텍스트 엔진의 핵심 역할은 모델의 컨텍스트 윈도우 크기 내에서 최대한 유용한 정보를 포함하는 것이다.\n우선순위 항목 설명 1 (최고) 시스템 프롬프트 항상 포함 2 새 메시지 현재 턴의 입력 3 최근 대화 가장 가까운 과거 메시지 4 요약 히스토리 압축된 과거 대화 5 (최저) 오래된 대화 예산 초과 시 제외 자동 압축이 실행되면 오래된 메시지가 요약문으로 대체되어 토큰을 절약한다.\n","permalink":"https://jungwoo0716.github.io/docs/openclaw/06-%EC%BB%A8%ED%85%8D%EC%8A%A4%ED%8A%B8%EC%97%94%EC%A7%84/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e컨텍스트 엔진은 각 에이전트 실행(run)에서 \u003cstrong\u003e모델 컨텍스트 구성\u003c/strong\u003e을 담당한다. 대화 히스토리, 시스템 프롬프트, 도구 결과 등을 토큰 예산 내에서 최적으로 조합하여 모델에 전달한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"4단계-생명주기\"\u003e4단계 생명주기\u003c/h2\u003e\n\u003cp\u003e컨텍스트 엔진은 4개의 생명주기 포인트에서 동작한다.\u003c/p\u003e\n\u003ch3 id=\"1-ingest-수집\"\u003e1. Ingest (수집)\u003c/h3\u003e\n\u003cp\u003e새로운 메시지를 처리하는 단계이다.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e사용자 메시지, 도구 결과 등 새로 들어온 데이터 수집\u003c/li\u003e\n\u003cli\u003e메시지 형식 정규화\u003c/li\u003e\n\u003cli\u003e메타데이터 부착 (타임스탬프, 소스 등)\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3 id=\"2-assemble-조립\"\u003e2. Assemble (조립)\u003c/h3\u003e\n\u003cp\u003e토큰 예산에 맞게 메시지 세트를 구성하는 단계이다.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e순서에 맞게 메시지 정렬\u003c/li\u003e\n\u003cli\u003e토큰 예산 계산\u003c/li\u003e\n\u003cli\u003e예산 초과 시 오래된 메시지부터 제외\u003c/li\u003e\n\u003cli\u003e시스템 프롬프트, 부트스트랩 파일, 사용자 메시지, 도구 결과 등을 합산\u003c/li\u003e\n\u003c/ul\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003e┌─────────────────────────────────────────┐\n│            토큰 예산                      │\n│                                          │\n│  [시스템 프롬프트] ← 항상 포함              │\n│  [부트스트랩 파일] ← 첫 턴에 포함           │\n│  [요약된 히스토리] ← 압축된 과거 대화        │\n│  [최근 대화]      ← 가능한 많이 포함        │\n│  [새 메시지]      ← 항상 포함              │\n│                                          │\n└─────────────────────────────────────────┘\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"3-compact-압축\"\u003e3. Compact (압축)\u003c/h3\u003e\n\u003cp\u003e오래된 히스토리를 요약하는 단계이다.\u003c/p\u003e","title":"컨텍스트 엔진"},{"content":"개요 OpenClaw의 메모리 시스템은 플레인 마크다운 파일 기반이다. 에이전트의 장기 기억, 학습 내용, 일별 노트 등을 워크스페이스에 마크다운으로 저장한다.\n메모리 파일 구조 workspace/ ├── MEMORY.md # 장기 메모리 (영구 보존) └── memory/ ├── 2026-03-28.md # 일별 노트 ├── 2026-03-29.md ├── 2026-03-30.md └── 2026-04-01.md MEMORY.md 영구 장기 메모리 파일이다. 세션을 넘어서 지속되어야 하는 핵심 정보를 저장한다.\n# 메모리 ## 사용자 선호 - 한국어로 소통 선호 - Next.js + TypeScript 스택 사용 ## 프로젝트 정보 - CRM 프로젝트: Supabase + Claude 연동 - 배포 환경: Vercel ## 중요 결정 - 2026-03-15: DB를 Google Sheets에서 Supabase로 마이그레이션 결정 memory/YYYY-MM-DD.md 일별 노트 파일이다. 해당 날짜에 발생한 이벤트, 대화 요약, 작업 내용 등을 기록한다.\n# 2026-04-01 ## 오늘 작업 - OpenClaw 문서 한국어 번역 완료 - 게이트웨이 설정 변경 (포트 18789 → 커스텀) ## 메모 - 다음 주 Telegram 채널 연동 예정 메모리 도구 에이전트가 메모리를 검색하고 읽을 수 있는 내장 도구가 제공된다.\nmemory_search 시맨틱 검색으로 메모리를 찾는다.\n키워드가 아닌 의미 기반 검색 관련도 순으로 결과 반환 모든 메모리 파일 대상 memory_get 특정 파일을 직접 읽는다.\n파일 경로를 지정하여 내용 조회 MEMORY.md 또는 특정 날짜 파일 읽기 메모리 백엔드 메모리 저장 및 검색에 사용되는 백엔드를 선택할 수 있다.\n1. Builtin (기본) SQLite 기반 별도 설정 없이 바로 사용 가능 로컬 파일 시스템에 저장 기본 시맨틱 검색 지원 2. QMD 로컬 우선(Local-first) 아키텍처 리랭킹(Reranking) 지원으로 검색 정확도 향상 더 정교한 검색이 필요한 경우 사용 3. Honcho AI 네이티브 메모리 시스템 크로스 세션(Cross-session) 메모리 지원 여러 세션에 걸친 패턴과 인사이트 추출 클라우드 연동 가능 자동 메모리 플러싱 컨텍스트 엔진이 히스토리를 **압축(compaction)**하기 전에 자동으로 메모리 플러싱이 실행된다.\n플러싱 과정 컨텍스트가 토큰 예산에 가까워짐 압축 전 메모리 플러싱 자동 실행 중요한 정보를 MEMORY.md 또는 일별 파일에 저장 이후 히스토리 압축 진행 이 과정 덕분에 오래된 대화가 압축되더라도 핵심 정보는 메모리 파일에 보존된다.\n메모리 설정 예시 { \u0026#34;agents\u0026#34;: { \u0026#34;default\u0026#34;: { \u0026#34;memory\u0026#34;: { \u0026#34;backend\u0026#34;: \u0026#34;builtin\u0026#34;, // \u0026#34;builtin\u0026#34;, \u0026#34;qmd\u0026#34;, \u0026#34;honcho\u0026#34; \u0026#34;autoFlush\u0026#34;: true, // 자동 플러싱 활성화 \u0026#34;searchResults\u0026#34;: 10 // 검색 결과 최대 개수 } } } } ","permalink":"https://jungwoo0716.github.io/docs/openclaw/07-%EB%A9%94%EB%AA%A8%EB%A6%AC/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw의 메모리 시스템은 \u003cstrong\u003e플레인 마크다운 파일\u003c/strong\u003e 기반이다. 에이전트의 장기 기억, 학습 내용, 일별 노트 등을 워크스페이스에 마크다운으로 저장한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"메모리-파일-구조\"\u003e메모리 파일 구조\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eworkspace/\n├── MEMORY.md              # 장기 메모리 (영구 보존)\n└── memory/\n    ├── 2026-03-28.md      # 일별 노트\n    ├── 2026-03-29.md\n    ├── 2026-03-30.md\n    └── 2026-04-01.md\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"memorymd\"\u003eMEMORY.md\u003c/h3\u003e\n\u003cp\u003e\u003cstrong\u003e영구 장기 메모리\u003c/strong\u003e 파일이다. 세션을 넘어서 지속되어야 하는 핵심 정보를 저장한다.\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-markdown\" data-lang=\"markdown\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e# 메모리\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e## 사용자 선호\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#66d9ef\"\u003e-\u003c/span\u003e 한국어로 소통 선호\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#66d9ef\"\u003e-\u003c/span\u003e Next.js + TypeScript 스택 사용\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e## 프로젝트 정보\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#66d9ef\"\u003e-\u003c/span\u003e CRM 프로젝트: Supabase + Claude 연동\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#66d9ef\"\u003e-\u003c/span\u003e 배포 환경: Vercel\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e## 중요 결정\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#66d9ef\"\u003e-\u003c/span\u003e 2026-03-15: DB를 Google Sheets에서 Supabase로 마이그레이션 결정\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch3 id=\"memoryyyyy-mm-ddmd\"\u003ememory/YYYY-MM-DD.md\u003c/h3\u003e\n\u003cp\u003e\u003cstrong\u003e일별 노트\u003c/strong\u003e 파일이다. 해당 날짜에 발생한 이벤트, 대화 요약, 작업 내용 등을 기록한다.\u003c/p\u003e","title":"메모리 시스템"},{"content":"이슈(태스크)는 Paperclip의 작업 단위입니다. 회사 목표까지 모든 작업을 추적하는 계층 구조를 형성합니다.\n이슈 생성 웹 UI 또는 API로 생성하며 다음 항목을 포함합니다:\n제목 — 명확하고 실행 가능한 설명 설명 — 상세 요구사항 (마크다운 지원) 우선순위 — critical, high, medium, low 상태 — backlog, todo, in_progress, in_review, done, blocked, cancelled 담당자 — 작업을 맡은 에이전트 상위 이슈 — 태스크 계층 유지 프로젝트 — 관련 이슈를 납품물 기준으로 그룹화 태스크 계층 작업은 상위 관계를 통해 회사 목표에 연결되어야 합니다:\n회사 목표: #1 AI 메모 앱 만들기 └── 인증 시스템 구축 (상위 태스크) └── JWT 토큰 서명 구현 (현재 태스크) 이렇게 하면 에이전트가 항상 \u0026ldquo;왜 이걸 하는 거지?\u0026ldquo;에 답할 수 있습니다.\n작업 할당 assigneeAgentId를 설정하면 책임이 할당됩니다. 하트비트 wake-on-assignment가 자동 알림을 트리거할 수 있습니다.\n상태 라이프사이클 backlog → todo → in_progress → in_review → done | blocked → todo / in_progress 핵심 제약:\nin_progress는 단일 에이전트 체크아웃 필요 blocked 상태는 장애물을 설명해야 함 done과 cancelled은 영구 상태 진행 모니터링 다음을 통해 진행 상황 추적:\n코멘트 상태 로그 태스크 분포를 보여주는 대시보드 에이전트 하트비트 실행 기록 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/07-%ED%83%9C%EC%8A%A4%ED%81%AC%EA%B4%80%EB%A6%AC/","summary":"\u003cp\u003e이슈(태스크)는 Paperclip의 작업 단위입니다. 회사 목표까지 모든 작업을 추적하는 계층 구조를 형성합니다.\u003c/p\u003e\n\u003ch2 id=\"이슈-생성\"\u003e이슈 생성\u003c/h2\u003e\n\u003cp\u003e웹 UI 또는 API로 생성하며 다음 항목을 포함합니다:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e제목\u003c/strong\u003e — 명확하고 실행 가능한 설명\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e설명\u003c/strong\u003e — 상세 요구사항 (마크다운 지원)\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e우선순위\u003c/strong\u003e — critical, high, medium, low\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e상태\u003c/strong\u003e — backlog, todo, in_progress, in_review, done, blocked, cancelled\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e담당자\u003c/strong\u003e — 작업을 맡은 에이전트\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e상위 이슈\u003c/strong\u003e — 태스크 계층 유지\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e프로젝트\u003c/strong\u003e — 관련 이슈를 납품물 기준으로 그룹화\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"태스크-계층\"\u003e태스크 계층\u003c/h2\u003e\n\u003cp\u003e작업은 상위 관계를 통해 회사 목표에 연결되어야 합니다:\u003c/p\u003e","title":"태스크 관리"},{"content":"개요 OpenClaw는 35개 이상의 AI 모델 프로바이더를 지원한다. 모델은 provider/model 형식으로 지정한다.\nanthropic/claude-opus-4-6 openai/gpt-4o google/gemini-2.5-pro 내장 프로바이더 프로바이더 식별자 주요 모델 Anthropic anthropic claude-opus-4-6, claude-sonnet-4-6 OpenAI openai gpt-4o, gpt-4-turbo, o1 Google Gemini google gemini-2.5-pro, gemini-2.5-flash OpenCode opencode 다양한 오픈소스 모델 OpenRouter openrouter 여러 프로바이더 통합 라우터 Mistral mistral mistral-large, mistral-medium Groq groq llama-3, mixtral (초고속 추론) 커스텀 프로바이더 자체 호스팅 모델을 사용하려면 models.providers 설정으로 커스텀 프로바이더를 등록한다.\n지원 플랫폼 Ollama - 로컬 LLM 실행 vLLM - 고성능 추론 서버 SGLang - 구조화된 생성 지원 설정 예시 { \u0026#34;models\u0026#34;: { \u0026#34;providers\u0026#34;: { \u0026#34;my-ollama\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;openai-compatible\u0026#34;, \u0026#34;baseUrl\u0026#34;: \u0026#34;http://localhost:11434/v1\u0026#34;, \u0026#34;models\u0026#34;: [\u0026#34;llama3:8b\u0026#34;, \u0026#34;codellama:13b\u0026#34;] }, \u0026#34;my-vllm\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;openai-compatible\u0026#34;, \u0026#34;baseUrl\u0026#34;: \u0026#34;http://gpu-server:8000/v1\u0026#34;, \u0026#34;apiKey\u0026#34;: \u0026#34;${VLLM_API_KEY}\u0026#34;, \u0026#34;models\u0026#34;: [\u0026#34;meta-llama/Llama-3-70b\u0026#34;] } } } } API 키 설정 환경 변수 각 프로바이더의 API 키는 환경 변수로 설정한다.\nexport ANTHROPIC_API_KEY=\u0026#34;sk-ant-...\u0026#34; export OPENAI_API_KEY=\u0026#34;sk-...\u0026#34; export GOOGLE_API_KEY=\u0026#34;AIza...\u0026#34; export MISTRAL_API_KEY=\u0026#34;...\u0026#34; export GROQ_API_KEY=\u0026#34;gsk_...\u0026#34; API 키 로테이션 여러 API 키를 환경 변수에 등록하여 로테이션할 수 있다. 하나의 키가 rate limit에 도달하면 자동으로 다음 키로 전환된다.\nCLI 명령어 온보딩 (최초 설정) openclaw onboard 대화형 마법사를 통해 프로바이더 선택, API 키 입력, 기본 모델 설정을 진행한다.\n모델 목록 조회 openclaw models list 현재 설정된 모든 프로바이더와 사용 가능한 모델을 표시한다.\nanthropic ├── claude-opus-4-6 ├── claude-sonnet-4-6 └── claude-haiku-3-5 openai ├── gpt-4o └── gpt-4-turbo google ├── gemini-2.5-pro └── gemini-2.5-flash 기본 모델 변경 openclaw models set anthropic/claude-sonnet-4-6 에이전트의 기본 모델을 변경한다.\n에이전트별 모델 설정 각 에이전트마다 다른 모델을 지정할 수 있다.\n{ \u0026#34;agents\u0026#34;: { \u0026#34;default\u0026#34;: { \u0026#34;model\u0026#34;: \u0026#34;anthropic/claude-sonnet-4-6\u0026#34; }, \u0026#34;code-assistant\u0026#34;: { \u0026#34;model\u0026#34;: \u0026#34;anthropic/claude-opus-4-6\u0026#34; }, \u0026#34;quick-responder\u0026#34;: { \u0026#34;model\u0026#34;: \u0026#34;groq/llama-3-70b\u0026#34; } } } 모델 선택 가이드 용도 권장 모델 이유 범용 대화 anthropic/claude-sonnet-4-6 균형 잡힌 성능과 비용 복잡한 추론 anthropic/claude-opus-4-6 최고 수준의 추론 능력 빠른 응답 groq/llama-3-70b 초고속 추론 코드 생성 anthropic/claude-sonnet-4-6 뛰어난 코드 이해와 생성 비용 절약 google/gemini-2.5-flash 저렴하고 빠름 로컬 실행 커스텀 Ollama 외부 API 없이 로컬 실행 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/08-%EB%AA%A8%EB%8D%B8%ED%94%84%EB%A1%9C%EB%B0%94%EC%9D%B4%EB%8D%94/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw는 \u003cstrong\u003e35개 이상의 AI 모델 프로바이더\u003c/strong\u003e를 지원한다. 모델은 \u003ccode\u003eprovider/model\u003c/code\u003e 형식으로 지정한다.\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eanthropic/claude-opus-4-6\nopenai/gpt-4o\ngoogle/gemini-2.5-pro\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"내장-프로바이더\"\u003e내장 프로바이더\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e프로바이더\u003c/th\u003e\n          \u003cth\u003e식별자\u003c/th\u003e\n          \u003cth\u003e주요 모델\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eAnthropic\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003eanthropic\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003eclaude-opus-4-6\u003c/code\u003e, \u003ccode\u003eclaude-sonnet-4-6\u003c/code\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eOpenAI\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003eopenai\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003egpt-4o\u003c/code\u003e, \u003ccode\u003egpt-4-turbo\u003c/code\u003e, \u003ccode\u003eo1\u003c/code\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eGoogle Gemini\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003egoogle\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003egemini-2.5-pro\u003c/code\u003e, \u003ccode\u003egemini-2.5-flash\u003c/code\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eOpenCode\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003eopencode\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e다양한 오픈소스 모델\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eOpenRouter\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003eopenrouter\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e여러 프로바이더 통합 라우터\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eMistral\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003emistral\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003emistral-large\u003c/code\u003e, \u003ccode\u003emistral-medium\u003c/code\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eGroq\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003egroq\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003ellama-3\u003c/code\u003e, \u003ccode\u003emixtral\u003c/code\u003e (초고속 추론)\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003chr\u003e\n\u003ch2 id=\"커스텀-프로바이더\"\u003e커스텀 프로바이더\u003c/h2\u003e\n\u003cp\u003e자체 호스팅 모델을 사용하려면 \u003ccode\u003emodels.providers\u003c/code\u003e 설정으로 커스텀 프로바이더를 등록한다.\u003c/p\u003e\n\u003ch3 id=\"지원-플랫폼\"\u003e지원 플랫폼\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003eOllama\u003c/strong\u003e - 로컬 LLM 실행\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003evLLM\u003c/strong\u003e - 고성능 추론 서버\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eSGLang\u003c/strong\u003e - 구조화된 생성 지원\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3 id=\"설정-예시\"\u003e설정 예시\u003c/h3\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;models\u0026#34;: {\n    \u0026#34;providers\u0026#34;: {\n      \u0026#34;my-ollama\u0026#34;: {\n        \u0026#34;type\u0026#34;: \u0026#34;openai-compatible\u0026#34;,\n        \u0026#34;baseUrl\u0026#34;: \u0026#34;http://localhost:11434/v1\u0026#34;,\n        \u0026#34;models\u0026#34;: [\u0026#34;llama3:8b\u0026#34;, \u0026#34;codellama:13b\u0026#34;]\n      },\n      \u0026#34;my-vllm\u0026#34;: {\n        \u0026#34;type\u0026#34;: \u0026#34;openai-compatible\u0026#34;,\n        \u0026#34;baseUrl\u0026#34;: \u0026#34;http://gpu-server:8000/v1\u0026#34;,\n        \u0026#34;apiKey\u0026#34;: \u0026#34;${VLLM_API_KEY}\u0026#34;,\n        \u0026#34;models\u0026#34;: [\u0026#34;meta-llama/Llama-3-70b\u0026#34;]\n      }\n    }\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"api-키-설정\"\u003eAPI 키 설정\u003c/h2\u003e\n\u003ch3 id=\"환경-변수\"\u003e환경 변수\u003c/h3\u003e\n\u003cp\u003e각 프로바이더의 API 키는 환경 변수로 설정한다.\u003c/p\u003e","title":"모델 프로바이더"},{"content":"Paperclip은 모든 에이전트가 정확히 한 명의 매니저에게 보고하는 트리 구조를 가지며, CEO가 루트에 위치합니다.\n구조 규칙 CEO 포지션에는 매니저가 없음 다른 모든 에이전트는 reportsTo 필드로 매니저를 식별 순환 없음 — 엄격한 비순환 무결성 유지 각 에이전트는 정확히 한 명의 매니저를 가짐 API 조직 구조 조회:\nGET /api/companies/{companyId}/org 지휘 체계 에이전트는 직속 보고부터 CEO까지의 매니저 목록에 접근할 수 있으며, 세 가지 목적으로 사용됩니다:\n에스컬레이션 — 차단된 작업을 상위로 리디렉션 위임 — 매니저가 하위에 서브태스크 할당 가시성 — 감독 능력 작업 가이드라인 에이전트는 보고 라인 외부에서 태스크를 받을 수 있지만, 취소할 수 없음 대신 매니저를 통해 재할당해야 함 UI의 Agents 섹션에서 에이전트 상태 표시기와 함께 전체 보고 트리를 표시합니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/08-%EC%A1%B0%EC%A7%81%EA%B5%AC%EC%A1%B0/","summary":"\u003cp\u003ePaperclip은 \u003cstrong\u003e모든 에이전트가 정확히 한 명의 매니저에게 보고하는 트리 구조\u003c/strong\u003e를 가지며, CEO가 루트에 위치합니다.\u003c/p\u003e\n\u003ch2 id=\"구조-규칙\"\u003e구조 규칙\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003eCEO 포지션에는 매니저가 없음\u003c/li\u003e\n\u003cli\u003e다른 모든 에이전트는 \u003ccode\u003ereportsTo\u003c/code\u003e 필드로 매니저를 식별\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e순환 없음\u003c/strong\u003e — 엄격한 비순환 무결성 유지\u003c/li\u003e\n\u003cli\u003e각 에이전트는 정확히 한 명의 매니저를 가짐\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"api\"\u003eAPI\u003c/h2\u003e\n\u003cp\u003e조직 구조 조회:\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eGET /api/companies/{companyId}/org\n\u003c/code\u003e\u003c/pre\u003e\u003ch2 id=\"지휘-체계\"\u003e지휘 체계\u003c/h2\u003e\n\u003cp\u003e에이전트는 직속 보고부터 CEO까지의 매니저 목록에 접근할 수 있으며, 세 가지 목적으로 사용됩니다:\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e\u003cstrong\u003e에스컬레이션\u003c/strong\u003e — 차단된 작업을 상위로 리디렉션\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e위임\u003c/strong\u003e — 매니저가 하위에 서브태스크 할당\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e가시성\u003c/strong\u003e — 감독 능력\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch2 id=\"작업-가이드라인\"\u003e작업 가이드라인\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e에이전트는 보고 라인 외부에서 태스크를 받을 수 있지만, 취소할 수 없음\u003c/li\u003e\n\u003cli\u003e대신 매니저를 통해 재할당해야 함\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eUI의 Agents 섹션에서 에이전트 상태 표시기와 함께 전체 보고 트리를 표시합니다.\u003c/p\u003e","title":"조직 구조"},{"content":"개요 OpenClaw는 여러 에이전트를 동시에 운영하며, 들어오는 메시지를 적절한 에이전트로 라우팅한다. 각 에이전트는 별도의 워크스페이스, 에이전트 디렉토리, 세션을 가지며 완전히 격리되어 동작한다.\n에이전트 격리 각 에이전트는 다음이 독립적으로 분리되어 있다:\n항목 설명 워크스페이스 별도의 AGENTS.md, SOUL.md 등 에이전트 디렉토리 ~/.openclaw/agents/\u0026lt;agentId\u0026gt;/ 세션 독립된 세션 저장소 도구 설정 에이전트별 사용 가능 도구 지정 샌드박스 에이전트별 격리된 실행 환경 ~/.openclaw/agents/ ├── customer-support/ # 고객 지원 에이전트 │ ├── workspace/ │ └── sessions/ ├── code-review/ # 코드 리뷰 에이전트 │ ├── workspace/ │ └── sessions/ └── scheduler/ # 스케줄 관리 에이전트 ├── workspace/ └── sessions/ 라우팅 계층 메시지가 들어오면 다음 우선순위 순서로 라우팅 대상을 결정한다.\n1. direct peer (가장 높음) - 직접 지정된 피어 2. parent peer - 부모 피어 3. Discord role+guild - Discord 역할 + 길드 조합 4. guild - Discord 길드 5. team - 팀 단위 6. account - 계정 단위 7. channel - 채널 단위 8. default (가장 낮음) - 기본 에이전트 라우팅 예시 { \u0026#34;agents\u0026#34;: { \u0026#34;default\u0026#34;: { // 기본 에이전트 - 매칭되는 규칙 없을 때 사용 \u0026#34;model\u0026#34;: \u0026#34;anthropic/claude-sonnet-4-6\u0026#34; }, \u0026#34;vip-support\u0026#34;: { // 특정 WhatsApp 번호에서 오는 메시지 \u0026#34;routing\u0026#34;: { \u0026#34;peers\u0026#34;: [\u0026#34;+82-10-1234-5678\u0026#34;] } }, \u0026#34;discord-mod\u0026#34;: { // 특정 Discord 길드의 관리자 역할 \u0026#34;routing\u0026#34;: { \u0026#34;discord\u0026#34;: { \u0026#34;guild\u0026#34;: \u0026#34;123456789\u0026#34;, \u0026#34;roles\u0026#34;: [\u0026#34;admin\u0026#34;, \u0026#34;moderator\u0026#34;] } } }, \u0026#34;team-agent\u0026#34;: { // 팀 단위 라우팅 \u0026#34;routing\u0026#34;: { \u0026#34;teams\u0026#34;: [\u0026#34;engineering\u0026#34;] } } } } 멀티 계정 지원 하나의 게이트웨이에서 여러 메시징 계정을 동시에 운영할 수 있다.\n지원 플랫폼 플랫폼 멀티 계정 WhatsApp 여러 전화번호 동시 운영 Telegram 여러 봇 토큰 동시 운영 Discord 여러 봇 계정 동시 운영 설정 예시 { \u0026#34;channels\u0026#34;: { \u0026#34;whatsapp\u0026#34;: [ { \u0026#34;name\u0026#34;: \u0026#34;support-line\u0026#34;, \u0026#34;phone\u0026#34;: \u0026#34;+82-10-0000-0001\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;customer-support\u0026#34; }, { \u0026#34;name\u0026#34;: \u0026#34;sales-line\u0026#34;, \u0026#34;phone\u0026#34;: \u0026#34;+82-10-0000-0002\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;sales\u0026#34; } ], \u0026#34;telegram\u0026#34;: [ { \u0026#34;name\u0026#34;: \u0026#34;main-bot\u0026#34;, \u0026#34;token\u0026#34;: \u0026#34;${TELEGRAM_BOT_TOKEN_1}\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;default\u0026#34; }, { \u0026#34;name\u0026#34;: \u0026#34;admin-bot\u0026#34;, \u0026#34;token\u0026#34;: \u0026#34;${TELEGRAM_BOT_TOKEN_2}\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;admin\u0026#34; } ] } } 에이전트별 샌드박스와 도구 각 에이전트가 사용할 수 있는 도구와 실행 환경을 개별적으로 설정한다.\n{ \u0026#34;agents\u0026#34;: { \u0026#34;customer-support\u0026#34;: { \u0026#34;tools\u0026#34;: { \u0026#34;allowed\u0026#34;: [\u0026#34;web_search\u0026#34;, \u0026#34;memory_search\u0026#34;, \u0026#34;memory_get\u0026#34;], \u0026#34;denied\u0026#34;: [\u0026#34;shell\u0026#34;, \u0026#34;browser\u0026#34;] }, \u0026#34;sandbox\u0026#34;: { \u0026#34;enabled\u0026#34;: true, \u0026#34;network\u0026#34;: \u0026#34;restricted\u0026#34; } }, \u0026#34;code-review\u0026#34;: { \u0026#34;tools\u0026#34;: { \u0026#34;allowed\u0026#34;: [\u0026#34;shell\u0026#34;, \u0026#34;browser\u0026#34;, \u0026#34;web_search\u0026#34;], \u0026#34;denied\u0026#34;: [] }, \u0026#34;sandbox\u0026#34;: { \u0026#34;enabled\u0026#34;: true, \u0026#34;network\u0026#34;: \u0026#34;full\u0026#34; } } } } 이렇게 하면 고객 지원 에이전트는 셸 접근이 차단되고, 코드 리뷰 에이전트는 전체 네트워크 접근이 허용된다.\n","permalink":"https://jungwoo0716.github.io/docs/openclaw/09-%EB%A9%80%ED%8B%B0%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EB%9D%BC%EC%9A%B0%ED%8C%85/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw는 \u003cstrong\u003e여러 에이전트를 동시에 운영\u003c/strong\u003e하며, 들어오는 메시지를 적절한 에이전트로 라우팅한다. 각 에이전트는 별도의 워크스페이스, 에이전트 디렉토리, 세션을 가지며 완전히 격리되어 동작한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"에이전트-격리\"\u003e에이전트 격리\u003c/h2\u003e\n\u003cp\u003e각 에이전트는 다음이 독립적으로 분리되어 있다:\u003c/p\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e항목\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003e워크스페이스\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e별도의 \u003ccode\u003eAGENTS.md\u003c/code\u003e, \u003ccode\u003eSOUL.md\u003c/code\u003e 등\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003e에이전트 디렉토리\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e~/.openclaw/agents/\u0026lt;agentId\u0026gt;/\u003c/code\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003e세션\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e독립된 세션 저장소\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003e도구 설정\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트별 사용 가능 도구 지정\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003e샌드박스\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트별 격리된 실행 환경\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003e~/.openclaw/agents/\n├── customer-support/     # 고객 지원 에이전트\n│   ├── workspace/\n│   └── sessions/\n├── code-review/          # 코드 리뷰 에이전트\n│   ├── workspace/\n│   └── sessions/\n└── scheduler/            # 스케줄 관리 에이전트\n    ├── workspace/\n    └── sessions/\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"라우팅-계층\"\u003e라우팅 계층\u003c/h2\u003e\n\u003cp\u003e메시지가 들어오면 다음 \u003cstrong\u003e우선순위 순서\u003c/strong\u003e로 라우팅 대상을 결정한다.\u003c/p\u003e","title":"멀티 에이전트 라우팅"},{"content":"Paperclip은 모든 에이전트가 사용한 모든 토큰을 추적하고, 폭주 비용을 방지하기 위해 예산 한도를 강제합니다.\n비용 추적 각 에이전트 하트비트에서 보고되는 항목:\n프로바이더 — LLM 프로바이더 (Anthropic, OpenAI 등) 모델 — 사용된 모델 입력 토큰 — 모델에 보낸 토큰 출력 토큰 — 모델이 생성한 토큰 비용 — 센트 단위 비용 이 메트릭은 UTC 달력 월 기준으로 에이전트별 월간 집계됩니다.\n예산 설정 회사 수준 PATCH /api/companies/{companyId} { \u0026#34;budgetMonthlyCents\u0026#34;: 100000 } 에이전트 수준 PATCH /api/agents/{agentId} { \u0026#34;budgetMonthlyCents\u0026#34;: 5000 } 강제 임계값 임계값 조치 80% 소프트 경고 — 에이전트에게 중요 작업 우선 처리 경고 100% 하드 스톱 — 에이전트 자동 일시정지, 하트비트 중단 자동 일시정지된 에이전트는 예산 증가 또는 달력 월 전환으로 재개됩니다.\n비용 가시성 API 회사 합계: GET /api/companies/{companyId}/costs/summary 에이전트별 분석: GET /api/companies/{companyId}/costs/by-agent 프로젝트별 분석: GET /api/companies/{companyId}/costs/by-project 권장 사항 보수적인 예산으로 시작하고 상향 조정 대시보드에서 이상 징후 모니터링 에이전트별 한도로 리스크 관리 중요 역할에 더 높은 예산 할당 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/09-%EB%B9%84%EC%9A%A9%EA%B3%BC%EC%98%88%EC%82%B0/","summary":"\u003cp\u003ePaperclip은 모든 에이전트가 사용한 모든 토큰을 추적하고, 폭주 비용을 방지하기 위해 예산 한도를 강제합니다.\u003c/p\u003e\n\u003ch2 id=\"비용-추적\"\u003e비용 추적\u003c/h2\u003e\n\u003cp\u003e각 에이전트 하트비트에서 보고되는 항목:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e프로바이더\u003c/strong\u003e — LLM 프로바이더 (Anthropic, OpenAI 등)\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e모델\u003c/strong\u003e — 사용된 모델\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e입력 토큰\u003c/strong\u003e — 모델에 보낸 토큰\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e출력 토큰\u003c/strong\u003e — 모델이 생성한 토큰\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e비용\u003c/strong\u003e — 센트 단위 비용\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e이 메트릭은 UTC 달력 월 기준으로 에이전트별 월간 집계됩니다.\u003c/p\u003e\n\u003ch2 id=\"예산-설정\"\u003e예산 설정\u003c/h2\u003e\n\u003ch3 id=\"회사-수준\"\u003e회사 수준\u003c/h3\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePATCH /api/companies/{companyId}\n{ \u0026#34;budgetMonthlyCents\u0026#34;: 100000 }\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"에이전트-수준\"\u003e에이전트 수준\u003c/h3\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePATCH /api/agents/{agentId}\n{ \u0026#34;budgetMonthlyCents\u0026#34;: 5000 }\n\u003c/code\u003e\u003c/pre\u003e\u003ch2 id=\"강제-임계값\"\u003e강제 임계값\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e임계값\u003c/th\u003e\n          \u003cth\u003e조치\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e80%\u003c/td\u003e\n          \u003ctd\u003e소프트 경고 — 에이전트에게 중요 작업 우선 처리 경고\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e100%\u003c/td\u003e\n          \u003ctd\u003e하드 스톱 — 에이전트 자동 일시정지, 하트비트 중단\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003cp\u003e자동 일시정지된 에이전트는 예산 증가 또는 달력 월 전환으로 재개됩니다.\u003c/p\u003e","title":"비용과 예산"},{"content":"Paperclip은 중요한 조직 결정에 대한 인간 감독을 유지하기 위해 승인 게이트를 구현합니다.\n승인 카테고리 에이전트 고용 (hire_agent) 매니저나 CEO가 부하 고용을 요청하면 hire_agent 승인이 생성됩니다. 포함 내용:\n잠재 에이전트의 이름, 역할, 능력 어댑터 설정 예산 할당 CEO 전략 (approve_ceo_strategy) CEO의 초기 전략 계획은 태스크가 in_progress로 전환되기 전에 보드 승인이 필요합니다.\n워크플로우 상태 pending → approved / rejected pending → revision_requested → resubmitted → pending 검토 프로세스 승인 페이지에 표시되는 항목:\n요청자와 근거 컨텍스트를 제공하는 관련 이슈 전체 페이로드 (제안된 에이전트 설정 등) 보드 운영자 권한 보드 운영자는 추가 권한을 가집니다:\n에이전트 일시정지/재개 에이전트 영구 종료 에이전트 간 태스크 재할당 예산 제약 오버라이드 승인 워크플로우 없이 에이전트 직접 생성 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/10-%EC%8A%B9%EC%9D%B8/","summary":"\u003cp\u003ePaperclip은 중요한 조직 결정에 대한 인간 감독을 유지하기 위해 승인 게이트를 구현합니다.\u003c/p\u003e\n\u003ch2 id=\"승인-카테고리\"\u003e승인 카테고리\u003c/h2\u003e\n\u003ch3 id=\"에이전트-고용-hire_agent\"\u003e에이전트 고용 (hire_agent)\u003c/h3\u003e\n\u003cp\u003e매니저나 CEO가 부하 고용을 요청하면 \u003ccode\u003ehire_agent\u003c/code\u003e 승인이 생성됩니다. 포함 내용:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e잠재 에이전트의 이름, 역할, 능력\u003c/li\u003e\n\u003cli\u003e어댑터 설정\u003c/li\u003e\n\u003cli\u003e예산 할당\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3 id=\"ceo-전략-approve_ceo_strategy\"\u003eCEO 전략 (approve_ceo_strategy)\u003c/h3\u003e\n\u003cp\u003eCEO의 초기 전략 계획은 태스크가 \u003ccode\u003ein_progress\u003c/code\u003e로 전환되기 전에 보드 승인이 필요합니다.\u003c/p\u003e\n\u003ch2 id=\"워크플로우-상태\"\u003e워크플로우 상태\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003epending → approved / rejected\npending → revision_requested → resubmitted → pending\n\u003c/code\u003e\u003c/pre\u003e\u003ch2 id=\"검토-프로세스\"\u003e검토 프로세스\u003c/h2\u003e\n\u003cp\u003e승인 페이지에 표시되는 항목:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e요청자와 근거\u003c/li\u003e\n\u003cli\u003e컨텍스트를 제공하는 관련 이슈\u003c/li\u003e\n\u003cli\u003e전체 페이로드 (제안된 에이전트 설정 등)\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"보드-운영자-권한\"\u003e보드 운영자 권한\u003c/h2\u003e\n\u003cp\u003e보드 운영자는 추가 권한을 가집니다:\u003c/p\u003e","title":"승인"},{"content":"개요 OpenClaw는 30개 이상의 메시징 채널을 지원한다. 하나의 게이트웨이에서 모든 채널을 통합 관리하며, 에이전트를 한 번 설정하면 모든 채널에서 동작한다.\n지원 채널 목록 주요 메시징 플랫폼 채널 텍스트 미디어 리액션 비고 WhatsApp O O O 멀티 계정 지원 Discord O O O 멀티 계정, 길드/역할 라우팅 Telegram O O O 가장 빠른 설정, 멀티 봇 Signal O O O 프라이버시 중심 iMessage O O - BlueBubbles 연동 필요 Slack O O O 워크스페이스 연동 비즈니스 메시징 채널 텍스트 미디어 리액션 비고 Google Chat O - - Google Workspace 연동 Microsoft Teams O O - MS 365 연동 소셜 및 커뮤니티 채널 텍스트 미디어 리액션 비고 Matrix O O O 탈중앙화 프로토콜 LINE O O O 아시아 시장 IRC O - - 레거시 호환 Nostr O - - 탈중앙화 소셜 웹 기반 채널 텍스트 미디어 리액션 비고 WebChat O O - 내장 웹 채팅 위젯 참고: 텍스트는 모든 채널에서 지원되지만, 미디어(이미지, 오디오, 비디오, 파일)와 리액션(이모지 반응)은 채널별로 지원 여부가 다르다.\n빠른 시작: Telegram (가장 빠른 설정) Telegram은 가장 빠르게 설정할 수 있는 채널이다.\n1단계: Telegram 봇 생성 Telegram에서 @BotFather와 대화 /newbot 명령어 입력 봇 이름과 사용자명 설정 받은 봇 토큰 저장 2단계: 설정 추가 { \u0026#34;channels\u0026#34;: { \u0026#34;telegram\u0026#34;: { \u0026#34;token\u0026#34;: \u0026#34;${TELEGRAM_BOT_TOKEN}\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;default\u0026#34; } } } 3단계: 환경 변수 설정 export TELEGRAM_BOT_TOKEN=\u0026#34;1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ\u0026#34; 4단계: 대화 시작 Telegram에서 봇을 찾아 메시지를 보내면 에이전트가 응답한다.\nDM 페어링 특정 사용자와 에이전트를 1:1로 연결(pairing)할 수 있다. 해당 사용자의 DM은 항상 지정된 에이전트로 라우팅된다.\n{ \u0026#34;agents\u0026#34;: { \u0026#34;personal-assistant\u0026#34;: { \u0026#34;routing\u0026#34;: { \u0026#34;peers\u0026#34;: [ \u0026#34;whatsapp:+82-10-1234-5678\u0026#34;, \u0026#34;telegram:@username\u0026#34;, \u0026#34;discord:user-id-123\u0026#34; ] } } } } 허용 목록 (Allowlists) 보안을 위해 특정 사용자만 에이전트와 대화할 수 있도록 제한한다.\n{ \u0026#34;channels\u0026#34;: { \u0026#34;whatsapp\u0026#34;: { \u0026#34;allowlist\u0026#34;: [ \u0026#34;+82-10-1234-5678\u0026#34;, \u0026#34;+82-10-9876-5432\u0026#34; ] }, \u0026#34;telegram\u0026#34;: { \u0026#34;allowlist\u0026#34;: [ \u0026#34;@allowed_user1\u0026#34;, \u0026#34;@allowed_user2\u0026#34; ] } } } 허용 목록에 없는 사용자의 메시지는 무시된다. 허용 목록을 설정하지 않으면 모든 사용자의 메시지를 수신한다.\n채널별 기능 비교 요약 텍스트 이미지 오디오 비디오 문서 리액션 WhatsApp ✓ ✓ ✓ ✓ ✓ ✓ Discord ✓ ✓ ✓ ✓ ✓ ✓ Telegram ✓ ✓ ✓ ✓ ✓ ✓ Signal ✓ ✓ ✓ ✓ ✓ ✓ iMessage ✓ ✓ ✓ ✓ ✓ - Slack ✓ ✓ - - ✓ ✓ Google Chat ✓ - - - - - MS Teams ✓ ✓ - - ✓ - LINE ✓ ✓ ✓ ✓ - ✓ WebChat ✓ ✓ - - ✓ - ","permalink":"https://jungwoo0716.github.io/docs/openclaw/10-%EC%B1%84%EB%84%90/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw는 \u003cstrong\u003e30개 이상의 메시징 채널\u003c/strong\u003e을 지원한다. 하나의 게이트웨이에서 모든 채널을 통합 관리하며, 에이전트를 한 번 설정하면 모든 채널에서 동작한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"지원-채널-목록\"\u003e지원 채널 목록\u003c/h2\u003e\n\u003ch3 id=\"주요-메시징-플랫폼\"\u003e주요 메시징 플랫폼\u003c/h3\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e채널\u003c/th\u003e\n          \u003cth\u003e텍스트\u003c/th\u003e\n          \u003cth\u003e미디어\u003c/th\u003e\n          \u003cth\u003e리액션\u003c/th\u003e\n          \u003cth\u003e비고\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eWhatsApp\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e멀티 계정 지원\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eDiscord\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e멀티 계정, 길드/역할 라우팅\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eTelegram\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e가장 빠른 설정, 멀티 봇\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eSignal\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e프라이버시 중심\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eiMessage\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e-\u003c/td\u003e\n          \u003ctd\u003eBlueBubbles 연동 필요\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eSlack\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e워크스페이스 연동\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"비즈니스-메시징\"\u003e비즈니스 메시징\u003c/h3\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e채널\u003c/th\u003e\n          \u003cth\u003e텍스트\u003c/th\u003e\n          \u003cth\u003e미디어\u003c/th\u003e\n          \u003cth\u003e리액션\u003c/th\u003e\n          \u003cth\u003e비고\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eGoogle Chat\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e-\u003c/td\u003e\n          \u003ctd\u003e-\u003c/td\u003e\n          \u003ctd\u003eGoogle Workspace 연동\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eMicrosoft Teams\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e-\u003c/td\u003e\n          \u003ctd\u003eMS 365 연동\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"소셜-및-커뮤니티\"\u003e소셜 및 커뮤니티\u003c/h3\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e채널\u003c/th\u003e\n          \u003cth\u003e텍스트\u003c/th\u003e\n          \u003cth\u003e미디어\u003c/th\u003e\n          \u003cth\u003e리액션\u003c/th\u003e\n          \u003cth\u003e비고\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eMatrix\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e탈중앙화 프로토콜\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eLINE\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e아시아 시장\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eIRC\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e-\u003c/td\u003e\n          \u003ctd\u003e-\u003c/td\u003e\n          \u003ctd\u003e레거시 호환\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eNostr\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e-\u003c/td\u003e\n          \u003ctd\u003e-\u003c/td\u003e\n          \u003ctd\u003e탈중앙화 소셜\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"웹-기반\"\u003e웹 기반\u003c/h3\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e채널\u003c/th\u003e\n          \u003cth\u003e텍스트\u003c/th\u003e\n          \u003cth\u003e미디어\u003c/th\u003e\n          \u003cth\u003e리액션\u003c/th\u003e\n          \u003cth\u003e비고\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eWebChat\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n          \u003ctd\u003e-\u003c/td\u003e\n          \u003ctd\u003e내장 웹 채팅 위젯\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003cblockquote\u003e\n\u003cp\u003e\u003cstrong\u003e참고\u003c/strong\u003e: 텍스트는 모든 채널에서 지원되지만, 미디어(이미지, 오디오, 비디오, 파일)와 리액션(이모지 반응)은 채널별로 지원 여부가 다르다.\u003c/p\u003e","title":"채팅 채널"},{"content":"대시보드는 자율 회사 운영에 대한 실시간 가시성을 제공합니다.\n표시 항목 에이전트 상태 — active, idle, running, error 상태 수 태스크 분석 — 상태별 수 (todo, in progress, blocked, done) 정체된 태스크 — 최근 업데이트 없이 진행 중인 작업 비용 요약 — 예산 대비 월간 지출 및 소진율 최근 활동 — 최신 회사 변경사항 사용 방법 회사를 선택한 후 왼쪽 사이드바에서 대시보드에 접근합니다. 실시간 업데이트로 자동 갱신됩니다.\n주의해야 할 핵심 메트릭 차단된 태스크 — 주의 필요; 코멘트를 검토하여 차단 원인 파악 및 시정 조치 예산 사용률 — 100%에서 에이전트 자동 일시정지; 80% 임계값 모니터링 정체된 작업 — 최근 코멘트가 없는 태스크는 멈춘 에이전트를 나타낼 수 있음; 실행 기록 확인 대시보드 API GET /api/companies/{companyId}/dashboard 상태별 에이전트 수, 상태별 태스크 수, 비용 요약, 정체 태스크 알림을 반환합니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/11-%EB%8C%80%EC%8B%9C%EB%B3%B4%EB%93%9C/","summary":"\u003cp\u003e대시보드는 자율 회사 운영에 대한 실시간 가시성을 제공합니다.\u003c/p\u003e\n\u003ch2 id=\"표시-항목\"\u003e표시 항목\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e에이전트 상태\u003c/strong\u003e — active, idle, running, error 상태 수\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e태스크 분석\u003c/strong\u003e — 상태별 수 (todo, in progress, blocked, done)\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e정체된 태스크\u003c/strong\u003e — 최근 업데이트 없이 진행 중인 작업\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e비용 요약\u003c/strong\u003e — 예산 대비 월간 지출 및 소진율\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e최근 활동\u003c/strong\u003e — 최신 회사 변경사항\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"사용-방법\"\u003e사용 방법\u003c/h2\u003e\n\u003cp\u003e회사를 선택한 후 왼쪽 사이드바에서 대시보드에 접근합니다. 실시간 업데이트로 자동 갱신됩니다.\u003c/p\u003e\n\u003ch2 id=\"주의해야-할-핵심-메트릭\"\u003e주의해야 할 핵심 메트릭\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e차단된 태스크\u003c/strong\u003e — 주의 필요; 코멘트를 검토하여 차단 원인 파악 및 시정 조치\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e예산 사용률\u003c/strong\u003e — 100%에서 에이전트 자동 일시정지; 80% 임계값 모니터링\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e정체된 작업\u003c/strong\u003e — 최근 코멘트가 없는 태스크는 멈춘 에이전트를 나타낼 수 있음; 실행 기록 확인\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"대시보드-api\"\u003e대시보드 API\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eGET /api/companies/{companyId}/dashboard\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e상태별 에이전트 수, 상태별 태스크 수, 비용 요약, 정체 태스크 알림을 반환합니다.\u003c/p\u003e","title":"대시보드"},{"content":"개요 OpenClaw는 6가지 자동화 메커니즘을 제공한다. 에이전트가 사용자 메시지 없이도 스스로 작업을 수행하거나 외부 이벤트에 반응할 수 있다.\n6가지 자동화 메커니즘 1. Heartbeat (하트비트) 주기적으로 에이전트의 메인 세션에 턴을 발생시킨다.\n기본 주기: 30분 에이전트가 HEARTBEAT.md 파일을 읽고 할 일을 확인 할 일이 없으면 HEARTBEAT_OK 응답 상세 내용은 하트비트 문서 참고 2. Cron (크론) 정확한 시간에 스케줄링된 작업을 실행한다.\n{ \u0026#34;automation\u0026#34;: { \u0026#34;cron\u0026#34;: [ { \u0026#34;name\u0026#34;: \u0026#34;daily-report\u0026#34;, \u0026#34;schedule\u0026#34;: \u0026#34;0 9 * * *\u0026#34;, // 매일 오전 9시 \u0026#34;agent\u0026#34;: \u0026#34;default\u0026#34;, \u0026#34;message\u0026#34;: \u0026#34;오늘의 보고서를 생성해주세요.\u0026#34; }, { \u0026#34;name\u0026#34;: \u0026#34;weekly-summary\u0026#34;, \u0026#34;schedule\u0026#34;: \u0026#34;0 18 * * 5\u0026#34;, // 매주 금요일 오후 6시 \u0026#34;agent\u0026#34;: \u0026#34;default\u0026#34;, \u0026#34;message\u0026#34;: \u0026#34;이번 주 요약을 작성해주세요.\u0026#34; } ] } } 크론 표현식 형식: 분 시 일 월 요일\n필드 값 범위 분 0-59 시 0-23 일 1-31 월 1-12 요일 0-7 (0과 7 모두 일요일) 3. Hooks (훅) 이벤트 기반으로 스크립트를 실행한다.\n{ \u0026#34;automation\u0026#34;: { \u0026#34;hooks\u0026#34;: { \u0026#34;on_message_received\u0026#34;: { \u0026#34;script\u0026#34;: \u0026#34;./scripts/log-message.sh\u0026#34; }, \u0026#34;on_session_start\u0026#34;: { \u0026#34;script\u0026#34;: \u0026#34;./scripts/init-session.sh\u0026#34; }, \u0026#34;on_error\u0026#34;: { \u0026#34;script\u0026#34;: \u0026#34;./scripts/alert.sh\u0026#34; } } } } 4. Standing Orders (상시 지시) 시스템 프롬프트에 포함되는 지속적인 지시사항이다. 에이전트가 모든 대화에서 항상 따르는 규칙을 정의한다.\n\u0026lt;!-- AGENTS.md 에 작성 --\u0026gt; ## Standing Orders - 매 턴마다 할 일 목록을 확인하고 긴급한 것이 있으면 알린다 - 고객 문의가 10분 이상 미응답이면 알림을 보낸다 - 매일 자정에 당일 활동 요약을 메모리에 기록한다 5. Background Tasks (백그라운드 작업) 메인 대화와 분리된 독립 작업을 추적한다.\n장시간 실행되는 작업을 백그라운드로 분리 작업 상태 추적 및 완료 알림 메인 세션을 차단하지 않음 6. Webhooks (웹훅) 외부 HTTP 이벤트를 수신하여 에이전트를 트리거한다.\n{ \u0026#34;automation\u0026#34;: { \u0026#34;webhooks\u0026#34;: { \u0026#34;enabled\u0026#34;: true, \u0026#34;endpoints\u0026#34;: { \u0026#34;github\u0026#34;: { \u0026#34;path\u0026#34;: \u0026#34;/webhook/github\u0026#34;, \u0026#34;secret\u0026#34;: \u0026#34;${GITHUB_WEBHOOK_SECRET}\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;code-review\u0026#34;, \u0026#34;message_template\u0026#34;: \u0026#34;GitHub 이벤트: {{event}}\u0026#34; }, \u0026#34;stripe\u0026#34;: { \u0026#34;path\u0026#34;: \u0026#34;/webhook/stripe\u0026#34;, \u0026#34;secret\u0026#34;: \u0026#34;${STRIPE_WEBHOOK_SECRET}\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;billing\u0026#34;, \u0026#34;message_template\u0026#34;: \u0026#34;결제 이벤트: {{type}}\u0026#34; } } } } } 추가 자동화 기능 Gmail PubSub Gmail 수신 메일을 실시간으로 감지하여 에이전트를 트리거한다.\nGoogle Cloud Pub/Sub 연동 새 메일 수신 시 자동으로 에이전트에 전달 폴링 (Polling) 주기적으로 외부 서비스를 확인하여 변경 사항을 감지한다.\nAPI 엔드포인트 주기적 조회 상태 변경 시 에이전트 트리거 인증 모니터링 (Auth Monitoring) 연결된 채널의 인증 상태를 모니터링한다.\n토큰 만료 감지 재인증 필요 시 알림 자동 토큰 갱신 (지원 채널) 자동화 조합 예시 여러 자동화를 조합하여 복잡한 워크플로를 구성할 수 있다.\n[GitHub Webhook] → 코드 리뷰 에이전트 → [Slack 알림] | [매일 크론] → 일일 리포트 생성 → [이메일 전송] | [하트비트 30분] → 대기 중인 작업 확인 → [필요 시 처리] ","permalink":"https://jungwoo0716.github.io/docs/openclaw/11-%EC%9E%90%EB%8F%99%ED%99%94/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw는 \u003cstrong\u003e6가지 자동화 메커니즘\u003c/strong\u003e을 제공한다. 에이전트가 사용자 메시지 없이도 스스로 작업을 수행하거나 외부 이벤트에 반응할 수 있다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"6가지-자동화-메커니즘\"\u003e6가지 자동화 메커니즘\u003c/h2\u003e\n\u003ch3 id=\"1-heartbeat-하트비트\"\u003e1. Heartbeat (하트비트)\u003c/h3\u003e\n\u003cp\u003e주기적으로 에이전트의 메인 세션에 턴을 발생시킨다.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e기본 주기\u003c/strong\u003e: 30분\u003c/li\u003e\n\u003cli\u003e에이전트가 \u003ccode\u003eHEARTBEAT.md\u003c/code\u003e 파일을 읽고 할 일을 확인\u003c/li\u003e\n\u003cli\u003e할 일이 없으면 \u003ccode\u003eHEARTBEAT_OK\u003c/code\u003e 응답\u003c/li\u003e\n\u003cli\u003e상세 내용은 \u003ca href=\"12-%ED%95%98%ED%8A%B8%EB%B9%84%ED%8A%B8.md\"\u003e하트비트 문서\u003c/a\u003e 참고\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3 id=\"2-cron-크론\"\u003e2. Cron (크론)\u003c/h3\u003e\n\u003cp\u003e정확한 시간에 스케줄링된 작업을 실행한다.\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;automation\u0026#34;: {\n    \u0026#34;cron\u0026#34;: [\n      {\n        \u0026#34;name\u0026#34;: \u0026#34;daily-report\u0026#34;,\n        \u0026#34;schedule\u0026#34;: \u0026#34;0 9 * * *\u0026#34;,        // 매일 오전 9시\n        \u0026#34;agent\u0026#34;: \u0026#34;default\u0026#34;,\n        \u0026#34;message\u0026#34;: \u0026#34;오늘의 보고서를 생성해주세요.\u0026#34;\n      },\n      {\n        \u0026#34;name\u0026#34;: \u0026#34;weekly-summary\u0026#34;,\n        \u0026#34;schedule\u0026#34;: \u0026#34;0 18 * * 5\u0026#34;,       // 매주 금요일 오후 6시\n        \u0026#34;agent\u0026#34;: \u0026#34;default\u0026#34;,\n        \u0026#34;message\u0026#34;: \u0026#34;이번 주 요약을 작성해주세요.\u0026#34;\n      }\n    ]\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e크론 표현식 형식: \u003ccode\u003e분 시 일 월 요일\u003c/code\u003e\u003c/p\u003e","title":"자동화"},{"content":"개요 하트비트(Heartbeat)는 OpenClaw의 주기적 에이전트 실행 메커니즘이다. 일정 간격으로 에이전트의 메인 세션에 턴을 발생시켜, 에이전트가 자율적으로 할 일을 확인하고 처리할 수 있게 한다.\n동작 방식 설정된 간격(기본 30분)마다 하트비트 실행 에이전트에 HEARTBEAT.md 파일을 읽으라는 프롬프트 전송 에이전트가 대기 중인 작업 확인 할 일이 있으면 처리, 없으면 HEARTBEAT_OK 응답 [30분 경과] → 하트비트 프롬프트 → 에이전트가 HEARTBEAT.md 확인 │ ┌────────────┴────────────┐ │ │ 할 일 있음 할 일 없음 │ │ 작업 수행 HEARTBEAT_OK 설정 옵션 { \u0026#34;automation\u0026#34;: { \u0026#34;heartbeat\u0026#34;: { \u0026#34;every\u0026#34;: \u0026#34;30m\u0026#34;, // 실행 간격 \u0026#34;target\u0026#34;: \u0026#34;main\u0026#34;, // 전달 대상 (세션) \u0026#34;lightContext\u0026#34;: false, // 경량 컨텍스트 사용 여부 \u0026#34;isolatedSession\u0026#34;: false, // 격리 세션 사용 여부 \u0026#34;activeHours\u0026#34;: { // 활성 시간대 설정 \u0026#34;start\u0026#34;: \u0026#34;09:00\u0026#34;, \u0026#34;end\u0026#34;: \u0026#34;22:00\u0026#34;, \u0026#34;timezone\u0026#34;: \u0026#34;Asia/Seoul\u0026#34; } } } } 설정 항목 상세 every (간격) 하트비트 실행 간격을 설정한다.\n값 설명 \u0026quot;10m\u0026quot; 10분마다 \u0026quot;30m\u0026quot; 30분마다 (기본값) \u0026quot;1h\u0026quot; 1시간마다 \u0026quot;4h\u0026quot; 4시간마다 target (전달 대상) 하트비트 프롬프트를 전달할 대상을 지정한다.\n\u0026quot;main\u0026quot; - 메인 세션 (기본값) 특정 채널이나 세션 지정 가능 lightContext true로 설정하면 경량 컨텍스트로 실행한다. 과거 대화 히스토리를 최소한으로 포함하여 토큰을 절약한다.\nisolatedSession true로 설정하면 별도의 격리 세션에서 하트비트를 실행한다. 메인 세션의 컨텍스트를 사용하지 않는다.\nactiveHours (활성 시간대) 하트비트가 실행되는 시간대를 제한한다. 야간에는 하트비트를 중단하여 불필요한 비용을 절약한다.\n비용 최적화 하트비트는 주기적으로 실행되므로 비용에 주의해야 한다.\n일반 세션 실행 메인 세션에서 하트비트를 실행하면 전체 컨텍스트가 로드된다.\n약 ~100K 토큰/실행 소비 30분마다 실행 시 하루 48회 = 약 4.8M 토큰/일 isolatedSession 사용 (권장) 격리 세션에서 실행하면 최소한의 컨텍스트만 사용한다.\n약 ~2-5K 토큰/실행 소비 30분마다 실행 시 하루 48회 = 약 96K-240K 토큰/일 권장: isolatedSession: true로 설정하면 토큰 사용량을 95% 이상 절감할 수 있다.\n비용 최적화 설정 예시 { \u0026#34;automation\u0026#34;: { \u0026#34;heartbeat\u0026#34;: { \u0026#34;every\u0026#34;: \u0026#34;30m\u0026#34;, \u0026#34;isolatedSession\u0026#34;: true, // 격리 세션으로 비용 절감 \u0026#34;lightContext\u0026#34;: true, // 경량 컨텍스트 \u0026#34;activeHours\u0026#34;: { // 업무 시간만 실행 \u0026#34;start\u0026#34;: \u0026#34;09:00\u0026#34;, \u0026#34;end\u0026#34;: \u0026#34;22:00\u0026#34;, \u0026#34;timezone\u0026#34;: \u0026#34;Asia/Seoul\u0026#34; } } } } 이 설정으로:\n격리 세션: ~2-5K 토큰/실행 활성 시간 13시간: 하루 26회 실행 하루 총 약 52K-130K 토큰 HEARTBEAT.md 작성 가이드 워크스페이스에 HEARTBEAT.md 파일을 작성하여 하트비트 시 에이전트가 확인할 작업을 정의한다.\n# 하트비트 체크리스트 ## 확인 항목 - [ ] 미응답 고객 문의 확인 - [ ] 예약된 작업 실행 - [ ] 시스템 상태 모니터링 ## 현재 대기 작업 - 없음 ## 메모 - 할 일이 없으면 HEARTBEAT_OK로 응답 에이전트는 이 파일을 읽고 대기 중인 작업이 있으면 처리하고, 없으면 HEARTBEAT_OK를 응답한다.\n","permalink":"https://jungwoo0716.github.io/docs/openclaw/12-%ED%95%98%ED%8A%B8%EB%B9%84%ED%8A%B8/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e하트비트(Heartbeat)는 OpenClaw의 주기적 에이전트 실행 메커니즘이다. 일정 간격으로 에이전트의 메인 세션에 턴을 발생시켜, 에이전트가 자율적으로 할 일을 확인하고 처리할 수 있게 한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"동작-방식\"\u003e동작 방식\u003c/h2\u003e\n\u003col\u003e\n\u003cli\u003e설정된 간격(기본 30분)마다 하트비트 실행\u003c/li\u003e\n\u003cli\u003e에이전트에 \u003ccode\u003eHEARTBEAT.md\u003c/code\u003e 파일을 읽으라는 프롬프트 전송\u003c/li\u003e\n\u003cli\u003e에이전트가 대기 중인 작업 확인\u003c/li\u003e\n\u003cli\u003e할 일이 있으면 처리, 없으면 \u003ccode\u003eHEARTBEAT_OK\u003c/code\u003e 응답\u003c/li\u003e\n\u003c/ol\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003e[30분 경과] → 하트비트 프롬프트 → 에이전트가 HEARTBEAT.md 확인\n                                         │\n                             ┌────────────┴────────────┐\n                             │                         │\n                        할 일 있음                  할 일 없음\n                             │                         │\n                        작업 수행                  HEARTBEAT_OK\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"설정-옵션\"\u003e설정 옵션\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;automation\u0026#34;: {\n    \u0026#34;heartbeat\u0026#34;: {\n      \u0026#34;every\u0026#34;: \u0026#34;30m\u0026#34;,              // 실행 간격\n      \u0026#34;target\u0026#34;: \u0026#34;main\u0026#34;,           // 전달 대상 (세션)\n      \u0026#34;lightContext\u0026#34;: false,       // 경량 컨텍스트 사용 여부\n      \u0026#34;isolatedSession\u0026#34;: false,   // 격리 세션 사용 여부\n      \u0026#34;activeHours\u0026#34;: {            // 활성 시간대 설정\n        \u0026#34;start\u0026#34;: \u0026#34;09:00\u0026#34;,\n        \u0026#34;end\u0026#34;: \u0026#34;22:00\u0026#34;,\n        \u0026#34;timezone\u0026#34;: \u0026#34;Asia/Seoul\u0026#34;\n      }\n    }\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"설정-항목-상세\"\u003e설정 항목 상세\u003c/h3\u003e\n\u003ch4 id=\"every-간격\"\u003eevery (간격)\u003c/h4\u003e\n\u003cp\u003e하트비트 실행 간격을 설정한다.\u003c/p\u003e","title":"하트비트"},{"content":"활동 로그는 추가 전용이고 변경 불가능한 감사 추적입니다.\n기록되는 변경사항 에이전트 생성, 업데이트, 일시정지, 재개, 종료 이슈 및 승인 변경 예산 조정 설정 변경 조회 방법 웹 UI 에이전트, 엔티티 유형, 시간 범위로 필터링 가능\nAPI GET /api/companies/{companyId}/activity 파라미터: agentId, entityType, entityId\n기록 구성요소 각 항목에 포함되는 내용:\n액터 — 누가 수행했는지 액션 — 무엇이 발생했는지 엔티티 — 무엇이 변경되었는지 세부사항 — 구체적 변경 내용 타임스탬프 — 언제 발생했는지 디버깅 활용 활동 로그는 문제 해결 리소스로 활용됩니다:\n관련 엔티티 찾기 타임라인 필터링 누락된 상태 업데이트, 실패한 체크아웃, 예상치 못한 할당 등 이슈 식별 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/12-%ED%99%9C%EB%8F%99%EB%A1%9C%EA%B7%B8/","summary":"\u003cp\u003e활동 로그는 \u003cstrong\u003e추가 전용이고 변경 불가능한\u003c/strong\u003e 감사 추적입니다.\u003c/p\u003e\n\u003ch2 id=\"기록되는-변경사항\"\u003e기록되는 변경사항\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e에이전트 생성, 업데이트, 일시정지, 재개, 종료\u003c/li\u003e\n\u003cli\u003e이슈 및 승인 변경\u003c/li\u003e\n\u003cli\u003e예산 조정\u003c/li\u003e\n\u003cli\u003e설정 변경\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"조회-방법\"\u003e조회 방법\u003c/h2\u003e\n\u003ch3 id=\"웹-ui\"\u003e웹 UI\u003c/h3\u003e\n\u003cp\u003e에이전트, 엔티티 유형, 시간 범위로 필터링 가능\u003c/p\u003e\n\u003ch3 id=\"api\"\u003eAPI\u003c/h3\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eGET /api/companies/{companyId}/activity\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e파라미터: \u003ccode\u003eagentId\u003c/code\u003e, \u003ccode\u003eentityType\u003c/code\u003e, \u003ccode\u003eentityId\u003c/code\u003e\u003c/p\u003e\n\u003ch2 id=\"기록-구성요소\"\u003e기록 구성요소\u003c/h2\u003e\n\u003cp\u003e각 항목에 포함되는 내용:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e액터\u003c/strong\u003e — 누가 수행했는지\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e액션\u003c/strong\u003e — 무엇이 발생했는지\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e엔티티\u003c/strong\u003e — 무엇이 변경되었는지\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e세부사항\u003c/strong\u003e — 구체적 변경 내용\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e타임스탬프\u003c/strong\u003e — 언제 발생했는지\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"디버깅-활용\"\u003e디버깅 활용\u003c/h2\u003e\n\u003cp\u003e활동 로그는 문제 해결 리소스로 활용됩니다:\u003c/p\u003e","title":"활동 로그"},{"content":"개요 스킬(Skills)은 에이전트의 능력을 확장하는 모듈이다. AgentSkills 호환 형식의 폴더로 구성되며, SKILL.md 파일이 스킬의 핵심이다.\n스킬 구조 my-skill/ ├── SKILL.md # 스킬 정의 (필수) ├── tools/ # 도구 스크립트 (선택) │ └── my-tool.sh └── resources/ # 리소스 파일 (선택) └── template.md SKILL.md 형식 --- name: my_skill description: \u0026#34;이 스킬은 ...\u0026#34; metadata: openclaw: gates: - web_search - shell --- # My Skill ## 사용법 이 스킬은 다음과 같이 동작합니다... ## 도구 - `my-tool`: 특정 작업을 수행합니다 프론트매터 필드 필드 설명 필수 name 스킬 이름 (snake_case) O description 스킬 설명 O metadata.openclaw.gates 필요한 게이트(권한) 목록 - 로딩 우선순위 스킬은 다음 순서로 로드되며, 상위 항목이 우선한다.\n1. workspace (최고 우선순위) - 에이전트 워크스페이스 내 스킬 2. project - 프로젝트 레벨 스킬 3. personal - 사용자 개인 스킬 4. managed - openclaw skills install로 설치한 스킬 5. bundled (최저 우선순위) - OpenClaw 기본 내장 스킬 동일한 이름의 스킬이 여러 레벨에 존재하면 상위 레벨의 스킬이 사용된다. 이를 통해 기본 스킬을 오버라이드할 수 있다.\n스킬 저장 위치 workspace/skills/ # 워크스페이스 스킬 ~/.openclaw/skills/ # 개인 + 관리형 스킬 \u0026lt;openclaw-install\u0026gt;/skills/ # 번들 스킬 보안 주의사항 중요: 서드파티 스킬은 신뢰할 수 없는 것으로 취급해야 한다.\n스킬은 에이전트의 권한으로 실행됨 설치 전 SKILL.md와 도구 스크립트를 반드시 검토 알 수 없는 출처의 스킬은 샌드박스 환경에서 테스트 gates 설정으로 스킬이 접근할 수 있는 기능 제한 게이트(Gates) 설정 스킬이 요청하는 게이트를 통해 필요한 권한을 확인할 수 있다.\nmetadata: openclaw: gates: - web_search # 웹 검색 권한 - shell # 셸 명령어 실행 권한 - browser # 브라우저 자동화 권한 - network # 네트워크 접근 권한 ClawHub 레지스트리 ClawHub는 OpenClaw 스킬의 공식 레지스트리이다. 커뮤니티가 만든 스킬을 검색하고 설치할 수 있다.\n스킬 검색 openclaw skills search \u0026lt;keyword\u0026gt; 스킬 설치 openclaw skills install \u0026lt;slug\u0026gt; 예시:\n# 웹 스크래핑 스킬 설치 openclaw skills install web-scraper # 코드 리뷰 스킬 설치 openclaw skills install code-review # 이메일 관리 스킬 설치 openclaw skills install email-manager 설치된 스킬 목록 openclaw skills list 스킬 제거 openclaw skills uninstall \u0026lt;slug\u0026gt; 스킬 활성화/비활성화 에이전트별로 사용할 스킬을 설정할 수 있다.\n{ \u0026#34;agents\u0026#34;: { \u0026#34;default\u0026#34;: { \u0026#34;skills\u0026#34;: { \u0026#34;enabled\u0026#34;: [\u0026#34;web-scraper\u0026#34;, \u0026#34;code-review\u0026#34;], \u0026#34;disabled\u0026#34;: [\u0026#34;email-manager\u0026#34;] } } } } ","permalink":"https://jungwoo0716.github.io/docs/openclaw/13-%EC%8A%A4%ED%82%AC/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e스킬(Skills)은 에이전트의 능력을 확장하는 모듈이다. \u003cstrong\u003eAgentSkills 호환\u003c/strong\u003e 형식의 폴더로 구성되며, \u003ccode\u003eSKILL.md\u003c/code\u003e 파일이 스킬의 핵심이다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"스킬-구조\"\u003e스킬 구조\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003emy-skill/\n├── SKILL.md           # 스킬 정의 (필수)\n├── tools/             # 도구 스크립트 (선택)\n│   └── my-tool.sh\n└── resources/         # 리소스 파일 (선택)\n    └── template.md\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"skillmd-형식\"\u003eSKILL.md 형식\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-markdown\" data-lang=\"markdown\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003ename: my_skill\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003edescription: \u0026#34;이 스킬은 ...\u0026#34;\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003emetadata:\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e  openclaw:\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e    gates:\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e      \u003cspan style=\"color:#66d9ef\"\u003e-\u003c/span\u003e web_search\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e      \u003cspan style=\"color:#66d9ef\"\u003e-\u003c/span\u003e shell\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e# My Skill\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e## 사용법\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e이 스킬은 다음과 같이 동작합니다...\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e## 도구\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#66d9ef\"\u003e-\u003c/span\u003e \u003cspan style=\"color:#e6db74\"\u003e`my-tool`\u003c/span\u003e: 특정 작업을 수행합니다\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch4 id=\"프론트매터-필드\"\u003e프론트매터 필드\u003c/h4\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e필드\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n          \u003cth\u003e필수\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ename\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e스킬 이름 (snake_case)\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003edescription\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e스킬 설명\u003c/td\u003e\n          \u003ctd\u003eO\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003emetadata.openclaw.gates\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e필요한 게이트(권한) 목록\u003c/td\u003e\n          \u003ctd\u003e-\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003chr\u003e\n\u003ch2 id=\"로딩-우선순위\"\u003e로딩 우선순위\u003c/h2\u003e\n\u003cp\u003e스킬은 다음 순서로 로드되며, \u003cstrong\u003e상위 항목이 우선\u003c/strong\u003e한다.\u003c/p\u003e","title":"스킬"},{"content":"Paperclip 에이전트는 지속적으로 실행되는 프로세스가 아닌, 짧은 실행 주기로 작동하는 AI 직원입니다. 트리거에 의해 활성화되고, 작업을 수행하고, 휴면 상태에 들어갑니다.\n실행 흐름 트리거에 의한 활성화 어댑터 호출 런타임 생성 API 상호작용으로 태스크 관리 메트릭을 포함한 출력 캡처 실행 기록의 영구 저장 환경 변수 에이전트에 주입되는 변수:\n변수 설명 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 깨어난 이유 세션 간 메모리 에이전트는 세션 지속성을 통해 하트비트 간 대화 컨텍스트를 유지합니다. 세션 상태 직렬화로 중복 데이터 처리 없이 연속성을 제공합니다.\n상태 상태 설명 active 준비됨 idle 대기 중 running 실행 중 error 실패 paused 일시정지 terminated 비활성화 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/13-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EC%9E%91%EB%8F%99%EB%B0%A9%EC%8B%9D/","summary":"\u003cp\u003ePaperclip 에이전트는 지속적으로 실행되는 프로세스가 아닌, \u003cstrong\u003e짧은 실행 주기로 작동하는 AI 직원\u003c/strong\u003e입니다. 트리거에 의해 활성화되고, 작업을 수행하고, 휴면 상태에 들어갑니다.\u003c/p\u003e\n\u003ch2 id=\"실행-흐름\"\u003e실행 흐름\u003c/h2\u003e\n\u003col\u003e\n\u003cli\u003e트리거에 의한 활성화\u003c/li\u003e\n\u003cli\u003e어댑터 호출\u003c/li\u003e\n\u003cli\u003e런타임 생성\u003c/li\u003e\n\u003cli\u003eAPI 상호작용으로 태스크 관리\u003c/li\u003e\n\u003cli\u003e메트릭을 포함한 출력 캡처\u003c/li\u003e\n\u003cli\u003e실행 기록의 영구 저장\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch2 id=\"환경-변수\"\u003e환경 변수\u003c/h2\u003e\n\u003cp\u003e에이전트에 주입되는 변수:\u003c/p\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e변수\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_AGENT_ID\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 ID\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_COMPANY_ID\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e회사 ID\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_API_URL\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eAPI 엔드포인트\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_API_KEY\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e인증 토큰 (단기 JWT)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_RUN_ID\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e실행 ID\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_TASK_ID\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e태스크 ID (트리거 유형에 따라)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_WAKE_REASON\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e깨어난 이유\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"세션-간-메모리\"\u003e세션 간 메모리\u003c/h2\u003e\n\u003cp\u003e에이전트는 \u003cstrong\u003e세션 지속성을 통해 하트비트 간 대화 컨텍스트를 유지\u003c/strong\u003e합니다. 세션 상태 직렬화로 중복 데이터 처리 없이 연속성을 제공합니다.\u003c/p\u003e","title":"에이전트 작동 방식"},{"content":"개요 커스텀 스킬을 직접 만들어 에이전트의 능력을 확장할 수 있다. 스킬은 SKILL.md 파일이 있는 디렉토리로 구성된다.\n빠른 시작 1단계: 스킬 디렉토리 생성 mkdir -p workspace/skills/hello-world 2단계: SKILL.md 작성 cat \u0026gt; workspace/skills/hello-world/SKILL.md \u0026lt;\u0026lt; \u0026#39;EOF\u0026#39; --- name: hello_world description: \u0026#34;간단한 인사 스킬 예시\u0026#34; requires: bins: [] config: [] --- # Hello World 스킬 ## 설명 이 스킬은 간단한 인사 메시지를 생성합니다. ## 사용법 사용자가 인사하면 친근하게 응답합니다. ## 규칙 - 항상 한국어로 인사 - 시간대에 맞는 인사말 사용 (아침/오후/저녁) - 이모지 사용하지 않음 EOF 3단계: 스킬 로드 확인 워크스페이스 스킬은 자동으로 로드된다. 다음 명령어로 확인:\nopenclaw skills list 4단계: 테스트 openclaw agent --message \u0026#34;안녕하세요!\u0026#34; SKILL.md 메타데이터 상세 필수 필드 --- name: my_skill_name # 스킬 이름 (snake_case 필수) description: \u0026#34;스킬 설명\u0026#34; # 스킬의 역할을 간결하게 설명 --- 선택 필드 --- name: advanced_skill description: \u0026#34;고급 기능을 제공하는 스킬\u0026#34; requires: bins: # 필요한 외부 바이너리 - jq - curl - python3 config: # 필요한 설정/환경변수 - GITHUB_TOKEN - SLACK_WEBHOOK_URL metadata: openclaw: gates: # 필요한 게이트(권한) - shell - web_search - network --- name 규칙 snake_case 사용 (하이픈 - 아닌 언더스코어 _) 소문자만 사용 예: code_review, web_scraper, email_sender requires.bins 스킬이 동작하는 데 필요한 외부 프로그램 목록이다. 해당 프로그램이 시스템에 설치되어 있지 않으면 스킬 로드 시 경고가 표시된다.\nrequires.config 스킬에 필요한 설정 값이나 환경 변수이다. 설정되지 않은 항목이 있으면 스킬 로드 시 경고가 표시된다.\n스킬 본문 작성 가이드 SKILL.md의 프론트매터 아래 마크다운 본문은 에이전트의 시스템 프롬프트에 주입된다.\n효과적인 스킬 본문 구조 # 스킬 이름 ## 설명 이 스킬이 무엇을 하는지 한두 문장으로 설명. ## 사용 시점 이 스킬이 활성화되어야 하는 상황을 기술. ## 사용법 구체적인 동작 방식과 명령어 설명. ## 규칙 - 스킬이 따라야 할 규칙 - 제한 사항 - 예외 상황 처리 ## 예시 입력과 출력의 구체적 예시. 실전 예시: GitHub PR 리뷰 스킬 mkdir -p workspace/skills/pr-review --- name: pr_review description: \u0026#34;GitHub Pull Request를 리뷰하고 피드백을 제공하는 스킬\u0026#34; requires: bins: - gh config: - GITHUB_TOKEN metadata: openclaw: gates: - shell --- # PR Review 스킬 ## 설명 GitHub Pull Request의 변경 사항을 분석하고 코드 리뷰 피드백을 제공한다. ## 사용 시점 - 사용자가 PR 리뷰를 요청할 때 - PR URL이나 번호가 제공될 때 ## 사용법 1. `gh pr view \u0026lt;number\u0026gt; --json` 으로 PR 정보 조회 2. `gh pr diff \u0026lt;number\u0026gt;` 로 변경 사항 확인 3. 코드 품질, 버그, 성능, 보안 관점에서 리뷰 4. 구체적인 라인 레벨 피드백 제공 ## 규칙 - 긍정적인 부분도 함께 언급 - 버그나 보안 이슈는 반드시 지적 - 코드 스타일은 프로젝트 기존 스타일을 따름 - 제안은 구체적인 코드 예시와 함께 제공 워크스페이스 스킬의 장점 워크스페이스 스킬은 가장 높은 우선순위를 가진다.\n기본 내장 스킬을 오버라이드할 수 있음 에이전트별 맞춤 동작 정의 가능 버전 관리 (Git)에 포함하여 팀과 공유 가능 프로젝트 특화 기능을 스킬로 모듈화 workspace/ ├── skills/ │ ├── custom-search/ # 커스텀 검색 로직 │ │ └── SKILL.md │ ├── team-rules/ # 팀 코딩 규칙 │ │ └── SKILL.md │ └── deploy-helper/ # 배포 도우미 │ └── SKILL.md ├── AGENTS.md └── SOUL.md ","permalink":"https://jungwoo0716.github.io/docs/openclaw/14-%EC%8A%A4%ED%82%AC%EB%A7%8C%EB%93%A4%EA%B8%B0/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e커스텀 스킬을 직접 만들어 에이전트의 능력을 확장할 수 있다. 스킬은 \u003ccode\u003eSKILL.md\u003c/code\u003e 파일이 있는 디렉토리로 구성된다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"빠른-시작\"\u003e빠른 시작\u003c/h2\u003e\n\u003ch3 id=\"1단계-스킬-디렉토리-생성\"\u003e1단계: 스킬 디렉토리 생성\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003emkdir -p workspace/skills/hello-world\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch3 id=\"2단계-skillmd-작성\"\u003e2단계: SKILL.md 작성\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003ecat \u0026gt; workspace/skills/hello-world/SKILL.md \u003cspan style=\"color:#e6db74\"\u003e\u0026lt;\u0026lt; \u0026#39;EOF\u0026#39;\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e---\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003ename: hello_world\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003edescription: \u0026#34;간단한 인사 스킬 예시\u0026#34;\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003erequires:\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e  bins: []\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e  config: []\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e---\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e# Hello World 스킬\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e## 설명\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e이 스킬은 간단한 인사 메시지를 생성합니다.\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e## 사용법\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e사용자가 인사하면 친근하게 응답합니다.\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e## 규칙\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e- 항상 한국어로 인사\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e- 시간대에 맞는 인사말 사용 (아침/오후/저녁)\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003e- 이모지 사용하지 않음\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#e6db74\"\u003eEOF\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch3 id=\"3단계-스킬-로드-확인\"\u003e3단계: 스킬 로드 확인\u003c/h3\u003e\n\u003cp\u003e워크스페이스 스킬은 자동으로 로드된다. 다음 명령어로 확인:\u003c/p\u003e","title":"스킬 만들기"},{"content":"하트비트 프로토콜은 모든 에이전트가 활성화 시 따라야 하는 표준화된 절차입니다.\n핵심 단계 1. 신원 및 설정 GET /api/agents/me로 에이전트 레코드를 가져와 ID, 회사, 역할, 예산 정보를 확인합니다.\n2. 승인 처리 승인 ID가 설정되어 있으면 승인 상태를 확인하고 관련 이슈를 적절히 처리합니다.\n3. 태스크 할당 확인 GET /api/companies/{companyId}/issues로 자신의 ID와 관련 상태로 필터링하여 태스크 인박스를 가져옵니다.\n4. 작업 선택 in_progress 태스크를 먼저 작업하고, 그 다음 todo를 작업합니다. 환경 변수로 지정된 태스크나 코멘트 멘션에 특별 우선순위를 부여합니다.\n5. 필수 체크아웃 작업 시작 전 반드시 실행:\nPOST /api/issues/{issueId}/checkout 중요: 409 Conflict가 반환되면 \u0026ldquo;태스크가 다른 에이전트에게 속해 있음\u0026quot;을 의미합니다. 다른 작업을 선택해야 합니다.\n6. 컨텍스트 검토 이슈 세부사항과 코멘트 기록을 가져와 태스크 컨텍스트와 계보를 이해합니다.\n7. 작업 수행 도구와 능력을 활용하여 할당된 작업을 완료합니다.\n8. 상태 업데이트 모든 상태 변경에는 실행 ID 헤더와 적절한 상태 전환, 설명 코멘트가 필요합니다.\n9. 위임 보고 대상에 대한 서브태스크를 적절한 parentId 및 goalId 연결로 생성할 수 있습니다.\n필수 제약 조건 항상 작업 전 체크아웃할 것 409 응답을 절대 재시도하지 말 것 진행 중인 작업에 코멘트 유지 서브태스크에 parentId 설정 교차 팀 태스크 취소 금지 지휘 체계를 통해 차단 건 에스컬레이션 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/14-%ED%95%98%ED%8A%B8%EB%B9%84%ED%8A%B8%ED%94%84%EB%A1%9C%ED%86%A0%EC%BD%9C/","summary":"\u003cp\u003e하트비트 프로토콜은 모든 에이전트가 활성화 시 따라야 하는 표준화된 절차입니다.\u003c/p\u003e\n\u003ch2 id=\"핵심-단계\"\u003e핵심 단계\u003c/h2\u003e\n\u003ch3 id=\"1-신원-및-설정\"\u003e1. 신원 및 설정\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003eGET /api/agents/me\u003c/code\u003e로 에이전트 레코드를 가져와 ID, 회사, 역할, 예산 정보를 확인합니다.\u003c/p\u003e\n\u003ch3 id=\"2-승인-처리\"\u003e2. 승인 처리\u003c/h3\u003e\n\u003cp\u003e승인 ID가 설정되어 있으면 승인 상태를 확인하고 관련 이슈를 적절히 처리합니다.\u003c/p\u003e\n\u003ch3 id=\"3-태스크-할당-확인\"\u003e3. 태스크 할당 확인\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003eGET /api/companies/{companyId}/issues\u003c/code\u003e로 자신의 ID와 관련 상태로 필터링하여 태스크 인박스를 가져옵니다.\u003c/p\u003e\n\u003ch3 id=\"4-작업-선택\"\u003e4. 작업 선택\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003ein_progress\u003c/code\u003e 태스크를 먼저 작업하고, 그 다음 \u003ccode\u003etodo\u003c/code\u003e를 작업합니다. 환경 변수로 지정된 태스크나 코멘트 멘션에 특별 우선순위를 부여합니다.\u003c/p\u003e","title":"하트비트 프로토콜"},{"content":"개요 OpenClaw의 설정은 JSON5 형식의 단일 설정 파일로 관리된다. 주석과 후행 쉼표를 지원하여 가독성이 높다.\n설정 파일 위치 ~/.openclaw/openclaw.json 환경 변수 OPENCLAW_CONFIG로 경로를 변경할 수 있다.\n설정 방법 4가지 방법으로 설정을 변경할 수 있다.\n1. 온보딩 마법사 openclaw onboard 최초 설정 시 대화형 마법사를 통해 기본 설정을 완료한다.\n2. CLI config set # 기본 모델 변경 openclaw config set models.default \u0026#34;anthropic/claude-sonnet-4-6\u0026#34; # 하트비트 간격 변경 openclaw config set automation.heartbeat.every \u0026#34;1h\u0026#34; # 채널 활성화 openclaw config set channels.telegram.enabled true 3. Control UI 웹 브라우저에서 http://127.0.0.1:18789/에 접속하여 GUI로 설정을 변경한다.\n4. 직접 편집 설정 파일을 텍스트 에디터로 직접 편집한다.\n# VS Code로 열기 code ~/.openclaw/openclaw.json # vim으로 열기 vim ~/.openclaw/openclaw.json 설정 검증 설정 변경 시 JSON Schema로 자동 검증이 수행된다. 잘못된 설정 값은 거부되며 오류 메시지가 표시된다.\n# 설정 검증 실행 openclaw config validate 핫 리로드 설정 변경 시 게이트웨이를 재시작하지 않고 적용할 수 있다.\n리로드 모드 모드 설명 hybrid 가능한 항목은 핫 리로드, 나머지는 재시작 (기본값) hot 모든 변경 사항을 핫 리로드 시도 restart 변경 시 항상 게이트웨이 재시작 { \u0026#34;gateway\u0026#34;: { \u0026#34;reloadMode\u0026#34;: \u0026#34;hybrid\u0026#34; // \u0026#34;hybrid\u0026#34;, \u0026#34;hot\u0026#34;, \u0026#34;restart\u0026#34; } } 설정 파일 구조 { // === 채널 설정 === \u0026#34;channels\u0026#34;: { \u0026#34;telegram\u0026#34;: { \u0026#34;enabled\u0026#34;: true, \u0026#34;token\u0026#34;: \u0026#34;${TELEGRAM_BOT_TOKEN}\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;default\u0026#34; }, \u0026#34;discord\u0026#34;: { \u0026#34;enabled\u0026#34;: false, \u0026#34;token\u0026#34;: \u0026#34;${DISCORD_BOT_TOKEN}\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;default\u0026#34; }, \u0026#34;whatsapp\u0026#34;: { \u0026#34;enabled\u0026#34;: false } }, // === 모델 설정 === \u0026#34;models\u0026#34;: { \u0026#34;default\u0026#34;: \u0026#34;anthropic/claude-sonnet-4-6\u0026#34;, \u0026#34;providers\u0026#34;: { // 커스텀 프로바이더 설정 } }, // === 에이전트 설정 === \u0026#34;agents\u0026#34;: { \u0026#34;default\u0026#34;: { \u0026#34;model\u0026#34;: \u0026#34;anthropic/claude-sonnet-4-6\u0026#34;, \u0026#34;workspace\u0026#34;: \u0026#34;~/.openclaw/agents/default/workspace\u0026#34;, \u0026#34;skills\u0026#34;: {}, \u0026#34;tools\u0026#34;: {}, \u0026#34;sandbox\u0026#34;: {} } }, // === 자동화 설정 === \u0026#34;automation\u0026#34;: { \u0026#34;heartbeat\u0026#34;: { \u0026#34;every\u0026#34;: \u0026#34;30m\u0026#34;, \u0026#34;isolatedSession\u0026#34;: true }, \u0026#34;cron\u0026#34;: [], \u0026#34;hooks\u0026#34;: {}, \u0026#34;webhooks\u0026#34;: {} }, // === 세션 설정 === \u0026#34;sessions\u0026#34;: { \u0026#34;maxHistory\u0026#34;: 1000, // 최대 히스토리 메시지 수 \u0026#34;compactThreshold\u0026#34;: 0.8, // 컨텍스트 사용률 임계치 \u0026#34;ttl\u0026#34;: \u0026#34;7d\u0026#34; // 세션 만료 시간 }, // === 도구 설정 === \u0026#34;tools\u0026#34;: { \u0026#34;shell\u0026#34;: { \u0026#34;enabled\u0026#34;: true, \u0026#34;timeout\u0026#34;: 30000 // 밀리초 }, \u0026#34;browser\u0026#34;: { \u0026#34;enabled\u0026#34;: true, \u0026#34;headless\u0026#34;: true }, \u0026#34;web_search\u0026#34;: { \u0026#34;enabled\u0026#34;: true, \u0026#34;provider\u0026#34;: \u0026#34;default\u0026#34; } }, // === 게이트웨이 설정 === \u0026#34;gateway\u0026#34;: { \u0026#34;port\u0026#34;: 18789, \u0026#34;host\u0026#34;: \u0026#34;127.0.0.1\u0026#34;, \u0026#34;reloadMode\u0026#34;: \u0026#34;hybrid\u0026#34; } } 환경 변수 치환 설정 파일 내에서 ${VAR_NAME} 구문으로 환경 변수를 참조할 수 있다.\n{ \u0026#34;channels\u0026#34;: { \u0026#34;telegram\u0026#34;: { \u0026#34;token\u0026#34;: \u0026#34;${TELEGRAM_BOT_TOKEN}\u0026#34; // 환경 변수에서 읽음 }, \u0026#34;discord\u0026#34;: { \u0026#34;token\u0026#34;: \u0026#34;${DISCORD_BOT_TOKEN}\u0026#34; } }, \u0026#34;models\u0026#34;: { \u0026#34;providers\u0026#34;: { \u0026#34;custom\u0026#34;: { \u0026#34;apiKey\u0026#34;: \u0026#34;${CUSTOM_API_KEY}\u0026#34; } } } } 환경 변수 설정 # .env 파일 또는 셸 프로필에 설정 export TELEGRAM_BOT_TOKEN=\u0026#34;1234567890:ABCdefGHI...\u0026#34; export DISCORD_BOT_TOKEN=\u0026#34;MTIzNDU2Nzg5...\u0026#34; export CUSTOM_API_KEY=\u0026#34;sk-...\u0026#34; 환경 변수가 설정되지 않으면 빈 문자열로 치환되며, 필수 항목의 경우 검증 오류가 발생한다.\n주요 설정 항목 요약 섹션 설명 channels 메시징 채널 연결 설정 models AI 모델 프로바이더 및 기본 모델 agents 에이전트별 설정 (모델, 도구, 스킬) automation 하트비트, 크론, 훅, 웹훅 sessions 세션 관리 (히스토리, 압축, TTL) tools 도구 활성화 및 세부 설정 gateway 게이트웨이 포트, 호스트, 리로드 모드 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/15-%EC%84%A4%EC%A0%95/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw의 설정은 \u003cstrong\u003eJSON5 형식\u003c/strong\u003e의 단일 설정 파일로 관리된다. 주석과 후행 쉼표를 지원하여 가독성이 높다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"설정-파일-위치\"\u003e설정 파일 위치\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003e~/.openclaw/openclaw.json\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e환경 변수 \u003ccode\u003eOPENCLAW_CONFIG\u003c/code\u003e로 경로를 변경할 수 있다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"설정-방법\"\u003e설정 방법\u003c/h2\u003e\n\u003cp\u003e4가지 방법으로 설정을 변경할 수 있다.\u003c/p\u003e\n\u003ch3 id=\"1-온보딩-마법사\"\u003e1. 온보딩 마법사\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003eopenclaw onboard\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e최초 설정 시 대화형 마법사를 통해 기본 설정을 완료한다.\u003c/p\u003e\n\u003ch3 id=\"2-cli-config-set\"\u003e2. CLI \u003ccode\u003econfig set\u003c/code\u003e\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 기본 모델 변경\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003eopenclaw config set models.default \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;anthropic/claude-sonnet-4-6\u0026#34;\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 하트비트 간격 변경\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003eopenclaw config set automation.heartbeat.every \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;1h\u0026#34;\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 채널 활성화\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003eopenclaw config set channels.telegram.enabled true\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch3 id=\"3-control-ui\"\u003e3. Control UI\u003c/h3\u003e\n\u003cp\u003e웹 브라우저에서 \u003ccode\u003ehttp://127.0.0.1:18789/\u003c/code\u003e에 접속하여 GUI로 설정을 변경한다.\u003c/p\u003e","title":"설정"},{"content":"에이전트 태스크 관리의 표준 패턴으로, 동일 태스크에 대한 동시 작업을 방지하는 체크아웃 기반 시스템입니다.\n체크아웃 패턴 작업 시작 전 반드시 실행:\nPOST /api/issues/{issueId}/checkout 두 에이전트가 동시에 같은 태스크를 체크아웃하면, 정확히 하나만 성공하고 다른 하나는 409 Conflict를 받습니다. 실패한 체크아웃은 절대 재시도하지 말고 다른 작업을 선택하세요.\n작업-업데이트 패턴 진행 상황을 코멘트와 함께 PATCH 요청으로 소통합니다. 항상 X-Paperclip-Run-Id 헤더를 포함합니다.\n차단 패턴 진행이 중단되면:\n장애물 문서화 상태를 blocked로 전환 적절한 당사자에게 에스컬레이션 침묵보다는 에스컬레이션을 선택하세요.\n위임 패턴 매니저가 작업을 분해하여 서브태스크 생성:\nPOST /api/companies/{companyId}/issues parentId 참조로 태스크 계층을 유지합니다.\n릴리스 패턴 소유권을 반환할 때:\nPOST /api/issues/{issueId}/release 설명 코멘트가 필요합니다.\nIC 하트비트 워크플로우 예시 할당된 태스크 가져오기 진행 중인 작업 계속하기 항목 완료하기 순차적 체크아웃 작업으로 새 태스크 진행하기 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/15-%ED%83%9C%EC%8A%A4%ED%81%AC%EC%9B%8C%ED%81%AC%ED%94%8C%EB%A1%9C%EC%9A%B0/","summary":"\u003cp\u003e에이전트 태스크 관리의 표준 패턴으로, 동일 태스크에 대한 동시 작업을 방지하는 체크아웃 기반 시스템입니다.\u003c/p\u003e\n\u003ch2 id=\"체크아웃-패턴\"\u003e체크아웃 패턴\u003c/h2\u003e\n\u003cp\u003e작업 시작 전 반드시 실행:\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePOST /api/issues/{issueId}/checkout\n\u003c/code\u003e\u003c/pre\u003e\u003cblockquote\u003e\n\u003cp\u003e두 에이전트가 동시에 같은 태스크를 체크아웃하면, 정확히 하나만 성공하고 다른 하나는 \u003ccode\u003e409 Conflict\u003c/code\u003e를 받습니다. \u003cstrong\u003e실패한 체크아웃은 절대 재시도하지 말고\u003c/strong\u003e 다른 작업을 선택하세요.\u003c/p\u003e\n\u003c/blockquote\u003e\n\u003ch2 id=\"작업-업데이트-패턴\"\u003e작업-업데이트 패턴\u003c/h2\u003e\n\u003cp\u003e진행 상황을 코멘트와 함께 \u003ccode\u003ePATCH\u003c/code\u003e 요청으로 소통합니다. 항상 \u003ccode\u003eX-Paperclip-Run-Id\u003c/code\u003e 헤더를 포함합니다.\u003c/p\u003e\n\u003ch2 id=\"차단-패턴\"\u003e차단 패턴\u003c/h2\u003e\n\u003cp\u003e진행이 중단되면:\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e장애물 문서화\u003c/li\u003e\n\u003cli\u003e상태를 \u003ccode\u003eblocked\u003c/code\u003e로 전환\u003c/li\u003e\n\u003cli\u003e적절한 당사자에게 에스컬레이션\u003c/li\u003e\n\u003c/ol\u003e\n\u003cblockquote\u003e\n\u003cp\u003e침묵보다는 에스컬레이션을 선택하세요.\u003c/p\u003e","title":"태스크 워크플로우"},{"content":"개요 OpenClaw는 Docker 컨테이너로 배포할 수 있다. Docker 설치는 선택 사항이며, 서버 환경이나 격리된 실행이 필요한 경우에 사용한다.\n사전 요구 사항 Docker 및 Docker Compose 설치 충분한 디스크 공간 (이미지 + 데이터) AI 모델 프로바이더 API 키 빠른 설정 설정 스크립트 실행 ./scripts/docker/setup.sh 이 스크립트는 다음을 수행한다:\n필요한 디렉토리 생성 기본 설정 파일 생성 Docker 이미지 다운로드 컨테이너 시작 사전 빌드 이미지 GitHub Container Registry(GHCR)에서 사전 빌드된 이미지를 사용할 수 있다.\ndocker pull ghcr.io/openclaw/openclaw:latest 이미지 태그 태그 설명 latest 최신 안정 릴리스 x.y.z 특정 버전 nightly 최신 개발 빌드 Docker Compose 설정 예시 version: \u0026#39;3.8\u0026#39; services: openclaw: image: ghcr.io/openclaw/openclaw:latest ports: - \u0026#34;18789:18789\u0026#34; volumes: - ./config:/root/.openclaw # 설정 파일 - ./workspace:/root/.openclaw/agents/default/workspace # 워크스페이스 environment: - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} - OPENAI_API_KEY=${OPENAI_API_KEY} - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN} - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN} restart: unless-stopped healthcheck: test: [\u0026#34;CMD\u0026#34;, \u0026#34;curl\u0026#34;, \u0026#34;-f\u0026#34;, \u0026#34;http://127.0.0.1:18789/healthz\u0026#34;] interval: 30s timeout: 10s retries: 3 Control UI 접근 컨테이너가 실행되면 브라우저에서 Control UI에 접근할 수 있다.\nhttp://127.0.0.1:18789/ Control UI에서 에이전트 관리, 채널 설정, 실시간 대화 모니터링 등이 가능하다.\n에이전트 샌드박스 Docker 환경에서는 에이전트 샌드박스가 별도의 컨테이너에서 실행된다.\nservices: openclaw: # ... 메인 게이트웨이 agent-sandbox: image: ghcr.io/openclaw/openclaw-sandbox:latest network_mode: \u0026#34;none\u0026#34; # 네트워크 격리 (필요 시) volumes: - sandbox-data:/workspace security_opt: - no-new-privileges:true volumes: sandbox-data: 이를 통해 에이전트의 도구 실행(셸 명령어, 파일 접근 등)이 호스트 시스템으로부터 격리된다.\n스토리지 바인드 마운트 설정과 워크스페이스는 호스트 파일시스템에 바인드 마운트하여 영속성을 보장한다.\nvolumes: - ./config:/root/.openclaw # 설정 파일 - ./workspace:/root/.openclaw/agents/default/workspace # 워크스페이스 - ./sessions:/root/.openclaw/agents/default/sessions # 세션 데이터 디렉토리 구조 docker-openclaw/ ├── docker-compose.yml ├── .env # 환경 변수 (API 키 등) ├── config/ │ └── openclaw.json # 설정 파일 ├── workspace/ │ ├── AGENTS.md │ ├── SOUL.md │ └── MEMORY.md └── sessions/ # 세션 데이터 (자동 생성) 헬스 체크 게이트웨이의 상태를 확인하는 헬스 체크 엔드포인트가 제공된다.\ncurl http://127.0.0.1:18789/healthz 정상 응답:\n{ \u0026#34;status\u0026#34;: \u0026#34;ok\u0026#34;, \u0026#34;uptime\u0026#34;: 3600, \u0026#34;version\u0026#34;: \u0026#34;1.0.0\u0026#34; } Docker Compose 헬스 체크 healthcheck: test: [\u0026#34;CMD\u0026#34;, \u0026#34;curl\u0026#34;, \u0026#34;-f\u0026#34;, \u0026#34;http://127.0.0.1:18789/healthz\u0026#34;] interval: 30s timeout: 10s retries: 3 start_period: 15s 환경 변수 관리 Docker 환경에서는 .env 파일로 환경 변수를 관리한다.\n# .env ANTHROPIC_API_KEY=sk-ant-... OPENAI_API_KEY=sk-... TELEGRAM_BOT_TOKEN=1234567890:ABCdef... DISCORD_BOT_TOKEN=MTIzNDU2... OPENCLAW_GATEWAY_TOKEN=my-secret-gateway-token 주의: .env 파일은 .gitignore에 추가하여 버전 관리에서 제외해야 한다.\n운영 명령어 # 컨테이너 시작 docker compose up -d # 로그 확인 docker compose logs -f openclaw # 컨테이너 중지 docker compose down # 이미지 업데이트 docker compose pull \u0026amp;\u0026amp; docker compose up -d # 상태 확인 docker compose ps 문제 해결 포트 충돌 기본 포트 18789가 사용 중인 경우 다른 포트로 매핑한다.\nports: - \u0026#34;28789:18789\u0026#34; # 호스트 28789 → 컨테이너 18789 권한 문제 바인드 마운트 디렉토리의 권한을 확인한다.\nchmod -R 755 ./config ./workspace 컨테이너 리소스 제한 필요 시 컨테이너의 리소스를 제한한다.\nservices: openclaw: deploy: resources: limits: memory: 2G cpus: \u0026#39;2\u0026#39; ","permalink":"https://jungwoo0716.github.io/docs/openclaw/16-docker%EC%84%A4%EC%B9%98/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw는 Docker 컨테이너로 배포할 수 있다. Docker 설치는 \u003cstrong\u003e선택 사항\u003c/strong\u003e이며, 서버 환경이나 격리된 실행이 필요한 경우에 사용한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"사전-요구-사항\"\u003e사전 요구 사항\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003eDocker 및 Docker Compose 설치\u003c/li\u003e\n\u003cli\u003e충분한 디스크 공간 (이미지 + 데이터)\u003c/li\u003e\n\u003cli\u003eAI 모델 프로바이더 API 키\u003c/li\u003e\n\u003c/ul\u003e\n\u003chr\u003e\n\u003ch2 id=\"빠른-설정\"\u003e빠른 설정\u003c/h2\u003e\n\u003ch3 id=\"설정-스크립트-실행\"\u003e설정 스크립트 실행\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e./scripts/docker/setup.sh\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e이 스크립트는 다음을 수행한다:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e필요한 디렉토리 생성\u003c/li\u003e\n\u003cli\u003e기본 설정 파일 생성\u003c/li\u003e\n\u003cli\u003eDocker 이미지 다운로드\u003c/li\u003e\n\u003cli\u003e컨테이너 시작\u003c/li\u003e\n\u003c/ul\u003e\n\u003chr\u003e\n\u003ch2 id=\"사전-빌드-이미지\"\u003e사전 빌드 이미지\u003c/h2\u003e\n\u003cp\u003eGitHub Container Registry(GHCR)에서 사전 빌드된 이미지를 사용할 수 있다.\u003c/p\u003e","title":"Docker 설치"},{"content":"자동 추적 어댑터가 하트비트 완료 시 자동으로 사용량 메트릭을 추출합니다:\n프로바이더 — 사용된 LLM 프로바이더 (예: \u0026ldquo;anthropic\u0026rdquo;, \u0026ldquo;openai\u0026rdquo;) 모델 — 모델 이름 토큰 수 — 입력/출력 토큰 비용 — 센트 단위 직접 보고 API로 수동 비용 이벤트 제출 가능:\nPOST /api/companies/{companyId}/cost-events 프로바이더, 모델, 토큰 사양을 포함합니다.\n예산 관리 에이전트는 각 사이클 초반에 재정 할당을 확인해야 합니다:\nGET /api/agents/me에서 spentMonthlyCents vs budgetMonthlyCents 확인 강제 한도 80% 사용 — 비필수 작업 우선순위 낮춤 100% 사용 — 자동 일시정지 권장 사항 어댑터가 보고를 처리하게 하고, 수동 중복 보고 피하기 작업 시작 전 가용 예산 확인 예산 소진 시 우아하게 태스크 종료 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/16-%EB%B9%84%EC%9A%A9%EB%B3%B4%EA%B3%A0/","summary":"\u003ch2 id=\"자동-추적\"\u003e자동 추적\u003c/h2\u003e\n\u003cp\u003e어댑터가 하트비트 완료 시 자동으로 사용량 메트릭을 추출합니다:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e프로바이더\u003c/strong\u003e — 사용된 LLM 프로바이더 (예: \u0026ldquo;anthropic\u0026rdquo;, \u0026ldquo;openai\u0026rdquo;)\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e모델\u003c/strong\u003e — 모델 이름\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e토큰 수\u003c/strong\u003e — 입력/출력 토큰\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e비용\u003c/strong\u003e — 센트 단위\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"직접-보고\"\u003e직접 보고\u003c/h2\u003e\n\u003cp\u003eAPI로 수동 비용 이벤트 제출 가능:\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePOST /api/companies/{companyId}/cost-events\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e프로바이더, 모델, 토큰 사양을 포함합니다.\u003c/p\u003e\n\u003ch2 id=\"예산-관리\"\u003e예산 관리\u003c/h2\u003e\n\u003cp\u003e에이전트는 각 사이클 초반에 재정 할당을 확인해야 합니다:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ccode\u003eGET /api/agents/me\u003c/code\u003e에서 \u003ccode\u003espentMonthlyCents\u003c/code\u003e vs \u003ccode\u003ebudgetMonthlyCents\u003c/code\u003e 확인\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3 id=\"강제-한도\"\u003e강제 한도\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e80% 사용\u003c/strong\u003e — 비필수 작업 우선순위 낮춤\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e100% 사용\u003c/strong\u003e — 자동 일시정지\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"권장-사항\"\u003e권장 사항\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e어댑터가 보고를 처리하게 하고, 수동 중복 보고 피하기\u003c/li\u003e\n\u003cli\u003e작업 시작 전 가용 예산 확인\u003c/li\u003e\n\u003cli\u003e예산 소진 시 우아하게 태스크 종료\u003c/li\u003e\n\u003c/ul\u003e","title":"비용 보고"},{"content":"에이전트가 승인 시스템과 상호작용하는 방법: 승인 요청과 해결 응답.\n승인 유형 고용 요청 매니저와 CEO가 에이전트 세부사항과 함께 제출:\nPOST /api/companies/{companyId}/agent-hires 회사 정책이 요구하면 새로 요청된 에이전트는 자동으로 pending_approval 상태에 들어갑니다.\nCEO 전략 승인 전략 계획 검증이 필요한 CEO:\nPOST /api/companies/{companyId}/approvals 타입: approve_ceo_strategy\n응답 워크플로우 승인이 해결되면 에이전트는 다음 환경 변수를 받습니다:\nPAPERCLIP_APPROVAL_ID PAPERCLIP_APPROVAL_STATUS (approved/rejected) 연결된 이슈 식별자 에이전트는 승인 세부사항을 조회하고 관련 이슈를 관리해야 합니다 — 완전히 해결되면 닫거나, 상태 코멘트로 업데이트.\n모니터링 대기 중인 승인 조회:\nGET /api/companies/{companyId}/approvals?status=pending 참고: 개인 기여자(IC)는 매니저를 통해 고용을 요청해야 하며 직접 요청하면 안 됩니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/17-%EC%8A%B9%EC%9D%B8%EC%B2%98%EB%A6%AC/","summary":"\u003cp\u003e에이전트가 승인 시스템과 상호작용하는 방법: 승인 요청과 해결 응답.\u003c/p\u003e\n\u003ch2 id=\"승인-유형\"\u003e승인 유형\u003c/h2\u003e\n\u003ch3 id=\"고용-요청\"\u003e고용 요청\u003c/h3\u003e\n\u003cp\u003e매니저와 CEO가 에이전트 세부사항과 함께 제출:\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePOST /api/companies/{companyId}/agent-hires\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e회사 정책이 요구하면 새로 요청된 에이전트는 자동으로 \u003ccode\u003epending_approval\u003c/code\u003e 상태에 들어갑니다.\u003c/p\u003e\n\u003ch3 id=\"ceo-전략-승인\"\u003eCEO 전략 승인\u003c/h3\u003e\n\u003cp\u003e전략 계획 검증이 필요한 CEO:\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePOST /api/companies/{companyId}/approvals\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e타입: \u003ccode\u003eapprove_ceo_strategy\u003c/code\u003e\u003c/p\u003e\n\u003ch2 id=\"응답-워크플로우\"\u003e응답 워크플로우\u003c/h2\u003e\n\u003cp\u003e승인이 해결되면 에이전트는 다음 환경 변수를 받습니다:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ccode\u003ePAPERCLIP_APPROVAL_ID\u003c/code\u003e\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003ePAPERCLIP_APPROVAL_STATUS\u003c/code\u003e (approved/rejected)\u003c/li\u003e\n\u003cli\u003e연결된 이슈 식별자\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e에이전트는 승인 세부사항을 조회하고 관련 이슈를 관리해야 합니다 — 완전히 해결되면 닫거나, 상태 코멘트로 업데이트.\u003c/p\u003e","title":"승인 처리"},{"content":"개요 OpenClaw는 에이전트 실행마다 맞춤형 시스템 프롬프트를 구성한다. 단순히 고정된 프롬프트를 사용하는 것이 아니라, 에이전트의 도구, 스킬, 작업 환경, 보안 정책 등을 종합하여 매 턴마다 동적으로 프롬프트를 조립한다.\n프롬프트 구성 섹션 시스템 프롬프트는 다음 섹션들로 구성된다.\n섹션 설명 Tooling 사용 가능한 도구 목록 및 사용 방법 Safety 안전 가드레일 및 제한 사항 Skills 활성화된 스킬 정보 Workspace 작업 디렉토리 구조 및 파일 목록 Docs 주입된 문서 (AGENTS.md, SOUL.md 등) Injected Files 추가 주입 파일 Sandbox 샌드박스 환경 정보 Date/Time 현재 날짜 및 시간대 Runtime Specs 런타임 사양 (모델, 토큰 제한 등) 프롬프트 모드 에이전트 실행 컨텍스트에 따라 세 가지 모드를 지원한다.\nfull (전체) 기본 모드. 모든 섹션을 포함하여 완전한 시스템 프롬프트를 구성한다.\n주 에이전트 실행 시 사용 도구, 스킬, 워크스페이스, 문서 등 전체 정보 포함 최대 크기의 컨텍스트 활용 minimal (최소) 서브 에이전트 실행 시 사용한다.\n필수 도구 정보만 포함 워크스페이스 및 스킬 정보 축소 토큰 사용량 절감 none (없음) 아이덴티티 정보만 포함하는 최소 모드.\n에이전트 이름과 기본 정체성만 전달 특수 목적 실행에 사용 부트스트랩 파일 주입 매 턴마다 다음 부트스트랩 파일이 시스템 프롬프트에 주입된다.\n파일 역할 AGENTS.md 에이전트 지시사항 및 메모리 SOUL.md 에이전트 페르소나 정의 MEMORY.md 장기 기억 데이터 이 파일들은 워크스페이스 디렉토리에 위치하며, 에이전트가 실행될 때마다 최신 내용이 반영된다.\n크기 제한 항목 제한 파일당 최대 크기 20,000자 전체 주입 총량 150,000자 주입 파일이 크기 제한을 초과하면 잘려서 포함된다. 중요한 정보는 파일 상단에 배치하는 것을 권장한다.\n안전 가드레일 시스템 프롬프트에 포함되는 Safety 섹션은 권고(advisory) 수준이다. 모델에게 \u0026ldquo;이렇게 행동하라\u0026quot;는 지시를 제공하지만 강제력은 없다.\n실제 강제 적용은 다음 메커니즘으로 이루어진다.\n메커니즘 설명 도구 정책 (Tool Policies) 특정 도구의 사용 허용/차단 실행 승인 (Exec Approvals) 셸 명령 실행 전 허용 목록 검증 샌드박싱 격리된 환경에서의 도구 실행 프롬프트 수준의 가드레일은 모델의 행동을 안내하고, 하드 레벨의 메커니즘이 실제 보안을 담당하는 이중 구조이다.\n프롬프트 구성 예시 ┌─────────────────────────────────────┐ │ System Prompt │ ├─────────────────────────────────────┤ │ [Runtime Specs] │ │ model: claude-sonnet-4-20250514 │ │ maxTokens: 8192 │ ├─────────────────────────────────────┤ │ [Date/Time] │ │ 2026-04-01T09:00:00+09:00 │ ├─────────────────────────────────────┤ │ [Safety] │ │ advisory guardrails... │ ├─────────────────────────────────────┤ │ [Tooling] │ │ exec, read, write, edit, browser │ ├─────────────────────────────────────┤ │ [Skills] │ │ web-search, image-gen... │ ├─────────────────────────────────────┤ │ [Workspace] │ │ ~/.openclaw/workspace/ │ ├─────────────────────────────────────┤ │ [Docs] AGENTS.md, SOUL.md, MEMORY │ ├─────────────────────────────────────┤ │ [Sandbox] │ │ mode: docker, network: off │ └─────────────────────────────────────┘ ","permalink":"https://jungwoo0716.github.io/docs/openclaw/17-%EC%8B%9C%EC%8A%A4%ED%85%9C%ED%94%84%EB%A1%AC%ED%94%84%ED%8A%B8/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw는 에이전트 실행마다 \u003cstrong\u003e맞춤형 시스템 프롬프트\u003c/strong\u003e를 구성한다. 단순히 고정된 프롬프트를 사용하는 것이 아니라, 에이전트의 도구, 스킬, 작업 환경, 보안 정책 등을 종합하여 매 턴마다 동적으로 프롬프트를 조립한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"프롬프트-구성-섹션\"\u003e프롬프트 구성 섹션\u003c/h2\u003e\n\u003cp\u003e시스템 프롬프트는 다음 섹션들로 구성된다.\u003c/p\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e섹션\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eTooling\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e사용 가능한 도구 목록 및 사용 방법\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eSafety\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e안전 가드레일 및 제한 사항\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eSkills\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e활성화된 스킬 정보\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eWorkspace\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e작업 디렉토리 구조 및 파일 목록\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eDocs\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e주입된 문서 (AGENTS.md, SOUL.md 등)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eInjected Files\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e추가 주입 파일\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eSandbox\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e샌드박스 환경 정보\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eDate/Time\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e현재 날짜 및 시간대\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eRuntime Specs\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e런타임 사양 (모델, 토큰 제한 등)\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003chr\u003e\n\u003ch2 id=\"프롬프트-모드\"\u003e프롬프트 모드\u003c/h2\u003e\n\u003cp\u003e에이전트 실행 컨텍스트에 따라 세 가지 모드를 지원한다.\u003c/p\u003e","title":"시스템 프롬프트"},{"content":"개요 OpenClaw의 세션은 에이전트와 사용자 간의 대화 컨텍스트를 관리하는 단위이다. 메시지 출처(DM, 그룹, 크론)에 따라 세션이 구성되며, 격리 수준과 초기화 정책을 세밀하게 제어할 수 있다.\n메시지 출처별 세션 구성 출처 세션 동작 DM (1:1) 기본적으로 공유 세션 사용 그룹 그룹별 격리 세션 크론 실행마다 새로운 세션 생성 DM 격리 수준 DM 세션은 격리 수준에 따라 네 가지 모드를 지원한다.\nmain 모든 DM이 하나의 메인 세션을 공유한다.\n가장 단순한 구성 모든 대화가 하나의 컨텍스트에 섞임 per-peer 대화 상대(peer)별로 세션을 분리한다.\n사용자 A와의 대화와 사용자 B와의 대화가 분리됨 같은 사용자가 여러 채널에서 보내면 하나로 합쳐짐 per-channel-peer (권장) 채널 + 대화 상대 조합으로 세션을 분리한다.\nWhatsApp의 사용자 A ≠ Telegram의 사용자 A 가장 세밀한 격리 수준 권장 설정 per-account-channel-peer 계정 + 채널 + 대화 상대 조합으로 세션을 분리한다.\n멀티 계정 운영 시 사용 동일 채널의 서로 다른 봇 계정별 격리 세션 초기화 세션은 다음 조건에서 초기화된다.\n조건 설명 일일 리셋 매일 오전 4시(설정 가능) 자동 초기화 유휴 타임아웃 일정 시간 비활성 시 자동 초기화 수동 리셋 /new 또는 /reset 명령어 { \u0026#34;sessions\u0026#34;: { \u0026#34;dailyReset\u0026#34;: \u0026#34;04:00\u0026#34;, // 일일 리셋 시각 \u0026#34;idleTimeout\u0026#34;: \u0026#34;4h\u0026#34;, // 유휴 타임아웃 \u0026#34;timezone\u0026#34;: \u0026#34;Asia/Seoul\u0026#34; } } 세션 저장소 세션 데이터는 파일 시스템에 저장된다.\n~/.openclaw/agents/\u0026lt;agentId\u0026gt;/sessions/ ├── main/ │ └── history.json ├── dm-whatsapp-user123/ │ └── history.json ├── group-telegram-mygroup/ │ └── history.json └── cron-daily-report-20260401/ └── history.json 세션 검사 명령어 현재 세션 상태 확인 openclaw status 활성 세션 목록, 메시지 수, 마지막 활동 시각 등을 확인할 수 있다.\n세션 목록 JSON 출력 openclaw sessions --json 프로그래밍 방식으로 세션 데이터에 접근할 때 사용한다.\n[ { \u0026#34;id\u0026#34;: \u0026#34;dm-whatsapp-user123\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;my-agent\u0026#34;, \u0026#34;messages\u0026#34;: 42, \u0026#34;lastActive\u0026#34;: \u0026#34;2026-04-01T08:30:00Z\u0026#34;, \u0026#34;source\u0026#34;: \u0026#34;whatsapp\u0026#34; } ] 그룹 세션 그룹 메시지는 항상 그룹 단위로 격리된다.\n그룹 내 모든 참여자가 동일한 세션을 공유 에이전트가 그룹 컨텍스트를 이해하고 응답 그룹 나가기 시 세션 데이터 보존 (수동 삭제 필요) 크론 세션 크론 작업은 기본적으로 매 실행마다 새로운 세션을 생성한다.\nisolatedSession: true (기본값) 이전 실행의 컨텍스트가 다음 실행에 영향을 주지 않음 메인 세션에서 실행하려면 target: \u0026quot;main\u0026quot; 설정 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/18-%EC%84%B8%EC%85%98%EA%B4%80%EB%A6%AC/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw의 세션은 에이전트와 사용자 간의 대화 컨텍스트를 관리하는 단위이다. 메시지 출처(DM, 그룹, 크론)에 따라 세션이 구성되며, 격리 수준과 초기화 정책을 세밀하게 제어할 수 있다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"메시지-출처별-세션-구성\"\u003e메시지 출처별 세션 구성\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e출처\u003c/th\u003e\n          \u003cth\u003e세션 동작\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eDM (1:1)\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e기본적으로 공유 세션 사용\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003e그룹\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e그룹별 격리 세션\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003e크론\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e실행마다 새로운 세션 생성\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003chr\u003e\n\u003ch2 id=\"dm-격리-수준\"\u003eDM 격리 수준\u003c/h2\u003e\n\u003cp\u003eDM 세션은 격리 수준에 따라 네 가지 모드를 지원한다.\u003c/p\u003e\n\u003ch3 id=\"main\"\u003emain\u003c/h3\u003e\n\u003cp\u003e모든 DM이 하나의 메인 세션을 공유한다.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e가장 단순한 구성\u003c/li\u003e\n\u003cli\u003e모든 대화가 하나의 컨텍스트에 섞임\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3 id=\"per-peer\"\u003eper-peer\u003c/h3\u003e\n\u003cp\u003e대화 상대(peer)별로 세션을 분리한다.\u003c/p\u003e","title":"세션 관리"},{"content":"주요 소통 채널 이슈의 코멘트가 에이전트 상호작용의 주요 채널입니다: 상태 업데이트, 질문, 발견, 핸드오프.\n코멘트 게시 방법 1. 직접 코멘트 엔드포인트 POST /api/issues/{issueId}/comments 2. 이슈 업데이트 시 인라인 PATCH /api/issues/{issueId} comment 필드 사용.\n권장 코멘트 형식 구조화된 마크다운 사용:\n상태 헤더 변경된 내용 또는 차단된 내용에 대한 불릿 관련 링크 에이전트 멘션 @AgentName 구문으로 다른 에이전트에게 알림. 이름은 에이전트의 등록된 name 필드와 일치해야 합니다 (대소문자 무관).\n멘션 시 주의사항 과도한 멘션 금지 — 예산에 영향 태스크 할당에 멘션 사용 금지 — 대신 태스크를 생성하세요 예외: 직접 @멘션된 에이전트가 명시적 지시를 받으면 체크아웃으로 자체 할당 가능 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/18-%EC%BD%94%EB%A9%98%ED%8A%B8%EC%99%80%EC%BB%A4%EB%AE%A4%EB%8B%88%EC%BC%80%EC%9D%B4%EC%85%98/","summary":"\u003ch2 id=\"주요-소통-채널\"\u003e주요 소통 채널\u003c/h2\u003e\n\u003cp\u003e이슈의 코멘트가 에이전트 상호작용의 주요 채널입니다: 상태 업데이트, 질문, 발견, 핸드오프.\u003c/p\u003e\n\u003ch2 id=\"코멘트-게시-방법\"\u003e코멘트 게시 방법\u003c/h2\u003e\n\u003ch3 id=\"1-직접-코멘트-엔드포인트\"\u003e1. 직접 코멘트 엔드포인트\u003c/h3\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePOST /api/issues/{issueId}/comments\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"2-이슈-업데이트-시-인라인\"\u003e2. 이슈 업데이트 시 인라인\u003c/h3\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePATCH /api/issues/{issueId}\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e\u003ccode\u003ecomment\u003c/code\u003e 필드 사용.\u003c/p\u003e\n\u003ch2 id=\"권장-코멘트-형식\"\u003e권장 코멘트 형식\u003c/h2\u003e\n\u003cp\u003e구조화된 마크다운 사용:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e상태 헤더\u003c/li\u003e\n\u003cli\u003e변경된 내용 또는 차단된 내용에 대한 불릿\u003c/li\u003e\n\u003cli\u003e관련 링크\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"에이전트-멘션\"\u003e에이전트 멘션\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003e@AgentName\u003c/code\u003e 구문으로 다른 에이전트에게 알림. 이름은 에이전트의 등록된 \u003ccode\u003ename\u003c/code\u003e 필드와 일치해야 합니다 (대소문자 무관).\u003c/p\u003e\n\u003ch2 id=\"멘션-시-주의사항\"\u003e멘션 시 주의사항\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e과도한 멘션 금지\u003c/strong\u003e — 예산에 영향\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e태스크 할당에 멘션 사용 금지\u003c/strong\u003e — 대신 태스크를 생성하세요\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e예외\u003c/strong\u003e: 직접 @멘션된 에이전트가 명시적 지시를 받으면 체크아웃으로 자체 할당 가능\u003c/li\u003e\n\u003c/ul\u003e","title":"코멘트와 커뮤니케이션"},{"content":"스킬은 에이전트가 작업 중 호출하는 재사용 가능한 지시 세트입니다. 에이전트에게 특정 작업 수행 방법을 가르치는 마크다운 파일입니다.\n디렉토리 구조 skills/my-skill/ ├── SKILL.md └── references/ (선택) SKILL.md 요구사항 YAML 프론트매터에 두 필드가 필요합니다:\n--- name: my-skill # kebab-case 고유 식별자 description: | # 에이전트가 이 스킬을 사용할 때를 결정하는 라우팅 로직 use when: ... don\u0026#39;t use when: ... --- description은 에이전트가 전체 내용을 로드할지 여부를 결정합니다 — 홍보 텍스트가 아니라 결정 로직입니다.\n런타임 프로세스 에이전트가 컨텍스트에서 스킬 메타데이터(이름 + 설명) 확인 에이전트가 현재 태스크에 스킬이 관련 있는지 판단 관련 있으면 전체 SKILL.md 내용 로드 에이전트가 스킬의 지시를 따름 이 접근법은 필요할 때만 상세 지시를 로드하여 기본 프롬프트를 최소화합니다.\n핵심 가이드라인 조건부 로직으로 설명 작성 — \u0026ldquo;use when\u0026quot;과 \u0026ldquo;don\u0026rsquo;t use when\u0026rdquo; 기준 포함 지시를 구체적으로 — 모호하지 않게 실행할 수 있도록 구체적 API 호출과 명령 예시 포함 — 추상적 설명 대신 하나의 관심사에 하나의 스킬 파일 보충 자료는 references/ 디렉토리에 저장 스킬 디스커버리 어댑터가 에이전트에 스킬을 제공하는 방법을 제어합니다. 어댑터마다 다른 방법 사용 — 심링크가 있는 임시 디렉토리 또는 글로벌 스킬 디렉토리.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/19-%EC%8A%A4%ED%82%AC%EC%9E%91%EC%84%B1%ED%95%98%EA%B8%B0/","summary":"\u003cp\u003e스킬은 에이전트가 작업 중 호출하는 \u003cstrong\u003e재사용 가능한 지시 세트\u003c/strong\u003e입니다. 에이전트에게 특정 작업 수행 방법을 가르치는 마크다운 파일입니다.\u003c/p\u003e\n\u003ch2 id=\"디렉토리-구조\"\u003e디렉토리 구조\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eskills/my-skill/\n├── SKILL.md\n└── references/    (선택)\n\u003c/code\u003e\u003c/pre\u003e\u003ch2 id=\"skillmd-요구사항\"\u003eSKILL.md 요구사항\u003c/h2\u003e\n\u003cp\u003eYAML 프론트매터에 두 필드가 필요합니다:\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-yaml\" data-lang=\"yaml\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#f92672\"\u003ename\u003c/span\u003e: \u003cspan style=\"color:#ae81ff\"\u003emy-skill         \u003c/span\u003e \u003cspan style=\"color:#75715e\"\u003e# kebab-case 고유 식별자\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#f92672\"\u003edescription\u003c/span\u003e: \u003cspan style=\"color:#ae81ff\"\u003e|         \u003c/span\u003e \u003cspan style=\"color:#75715e\"\u003e# 에이전트가 이 스킬을 사용할 때를 결정하는 라우팅 로직\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e  \u003cspan style=\"color:#f92672\"\u003euse when\u003c/span\u003e: \u003cspan style=\"color:#ae81ff\"\u003e...\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e  \u003cspan style=\"color:#f92672\"\u003edon\u0026#39;t use when\u003c/span\u003e: \u003cspan style=\"color:#ae81ff\"\u003e...\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e\u003ccode\u003edescription\u003c/code\u003e은 에이전트가 전체 내용을 로드할지 여부를 결정합니다 — 홍보 텍스트가 아니라 결정 로직입니다.\u003c/p\u003e\n\u003ch2 id=\"런타임-프로세스\"\u003e런타임 프로세스\u003c/h2\u003e\n\u003col\u003e\n\u003cli\u003e에이전트가 컨텍스트에서 스킬 메타데이터(이름 + 설명) 확인\u003c/li\u003e\n\u003cli\u003e에이전트가 현재 태스크에 스킬이 관련 있는지 판단\u003c/li\u003e\n\u003cli\u003e관련 있으면 전체 SKILL.md 내용 로드\u003c/li\u003e\n\u003cli\u003e에이전트가 스킬의 지시를 따름\u003c/li\u003e\n\u003c/ol\u003e\n\u003cp\u003e이 접근법은 필요할 때만 상세 지시를 로드하여 기본 프롬프트를 최소화합니다.\u003c/p\u003e","title":"스킬 작성하기"},{"content":"개요 에이전트 워크스페이스는 에이전트의 주 작업 디렉토리이다. 에이전트의 지시사항, 페르소나, 메모리, 도구 설정 등 모든 부트스트랩 파일이 이 디렉토리에 위치한다.\n기본 경로: ~/.openclaw/workspace\n부트스트랩 파일 워크스페이스에 배치하는 핵심 파일들이다.\n파일 역할 필수 여부 AGENTS.md 에이전트 지시사항 + 메모리 권장 SOUL.md 에이전트 페르소나 정의 선택 USER.md 사용자 정체성 정보 선택 IDENTITY.md 에이전트 이름/식별 정보 선택 TOOLS.md 도구 사용 가이드라인 선택 HEARTBEAT.md 하트비트 시 확인할 작업 목록 선택 BOOT.md 에이전트 부팅 시 실행할 초기 작업 선택 AGENTS.md 에이전트의 핵심 지시사항 파일이다. 에이전트의 행동 규칙, 응답 스타일, 작업 범위 등을 정의한다.\n# 에이전트 지시사항 ## 역할 고객 지원 담당 AI 에이전트 ## 규칙 - 한국어로 응답 - 기술 용어는 영어 병기 - 모르는 질문은 솔직히 모른다고 답변 SOUL.md 에이전트의 성격과 페르소나를 정의한다.\n# 페르소나 - 이름: 클로 - 성격: 친절하고 전문적 - 말투: 존댓말, 간결한 문장 메모리 구조 워크스페이스 내 memory/ 디렉토리에 메모리 파일을 저장한다.\nworkspace/ ├── AGENTS.md ├── SOUL.md ├── MEMORY.md ← 장기 기억 (핵심 요약) └── memory/ ├── 2026-03-30.md ← 일별 메모리 ├── 2026-03-31.md └── 2026-04-01.md 파일 용도 MEMORY.md 장기 기억. 핵심 정보, 사용자 선호, 반복 패턴 등 memory/YYYY-MM-DD.md 일별 기억. 해당 날짜에 발생한 주요 이벤트 및 대화 요약 에이전트는 대화 중 중요한 정보를 발견하면 이 파일들에 기록하고, 다음 세션에서 참조한다.\n경로 해석 규칙 워크스페이스는 하드 샌드박스가 아니다.\n경로 유형 동작 상대 경로 (./data/report.csv) 워크스페이스 기준으로 해석 절대 경로 (/tmp/output.log) 해당 절대 경로로 접근 샌드박싱이 활성화되지 않은 상태에서는 에이전트가 절대 경로를 통해 시스템의 다른 디렉토리에 접근할 수 있다. 보안이 필요한 환경에서는 반드시 샌드박싱 설정을 함께 사용해야 한다.\n워크스페이스 관리 권장 사항 Git 연동 워크스페이스를 비공개 Git 저장소로 관리하는 것을 권장한다.\ncd ~/.openclaw/workspace git init git remote add origin git@github.com:user/openclaw-workspace.git 장점:\n지시사항 변경 이력 추적 메모리 파일 백업 여러 환경 간 동기화 디렉토리 구조 예시 workspace/ ├── AGENTS.md ├── SOUL.md ├── IDENTITY.md ├── USER.md ├── TOOLS.md ├── HEARTBEAT.md ├── BOOT.md ├── MEMORY.md ├── memory/ │ └── *.md ├── skills/ │ └── custom-skill/ ├── hooks/ │ └── custom-hook/ └── data/ └── (에이전트가 생성한 데이터) ","permalink":"https://jungwoo0716.github.io/docs/openclaw/19-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EC%9B%8C%ED%81%AC%EC%8A%A4%ED%8E%98%EC%9D%B4%EC%8A%A4/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e에이전트 워크스페이스는 에이전트의 \u003cstrong\u003e주 작업 디렉토리\u003c/strong\u003e이다. 에이전트의 지시사항, 페르소나, 메모리, 도구 설정 등 모든 부트스트랩 파일이 이 디렉토리에 위치한다.\u003c/p\u003e\n\u003cp\u003e기본 경로: \u003ccode\u003e~/.openclaw/workspace\u003c/code\u003e\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"부트스트랩-파일\"\u003e부트스트랩 파일\u003c/h2\u003e\n\u003cp\u003e워크스페이스에 배치하는 핵심 파일들이다.\u003c/p\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e파일\u003c/th\u003e\n          \u003cth\u003e역할\u003c/th\u003e\n          \u003cth\u003e필수 여부\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eAGENTS.md\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 지시사항 + 메모리\u003c/td\u003e\n          \u003ctd\u003e권장\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eSOUL.md\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 페르소나 정의\u003c/td\u003e\n          \u003ctd\u003e선택\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eUSER.md\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e사용자 정체성 정보\u003c/td\u003e\n          \u003ctd\u003e선택\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eIDENTITY.md\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 이름/식별 정보\u003c/td\u003e\n          \u003ctd\u003e선택\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eTOOLS.md\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e도구 사용 가이드라인\u003c/td\u003e\n          \u003ctd\u003e선택\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eHEARTBEAT.md\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e하트비트 시 확인할 작업 목록\u003c/td\u003e\n          \u003ctd\u003e선택\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eBOOT.md\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 부팅 시 실행할 초기 작업\u003c/td\u003e\n          \u003ctd\u003e선택\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"agentsmd\"\u003eAGENTS.md\u003c/h3\u003e\n\u003cp\u003e에이전트의 핵심 지시사항 파일이다. 에이전트의 행동 규칙, 응답 스타일, 작업 범위 등을 정의한다.\u003c/p\u003e","title":"에이전트 워크스페이스"},{"content":"개요 OpenClaw의 브라우저 도구는 에이전트가 격리된 브라우저 프로필을 통해 웹 페이지를 탐색하고 조작할 수 있게 한다. Chrome, Brave, Edge를 지원하며, 로컬 또는 원격 CDP(Chrome DevTools Protocol) 연결을 통해 작동한다.\n브라우저 프로필 프로필 설명 용도 openclaw OpenClaw가 관리하는 격리 프로필 기본 자동화 작업 user DevTools MCP를 통한 사용자 브라우저 로그인된 세션 활용 custom 원격 CDP 엔드포인트 연결 클라우드 브라우저 서비스 openclaw 프로필 (기본) OpenClaw가 자체 관리하는 브라우저 인스턴스를 사용한다. 사용자 브라우저와 완전히 격리되어 있어 기존 세션, 쿠키, 확장 프로그램에 영향을 주지 않는다.\nuser 프로필 사용자의 실제 브라우저에 DevTools MCP로 연결한다. 이미 로그인된 서비스에 접근할 때 유용하다.\ncustom 프로필 원격 CDP를 통해 클라우드 브라우저 서비스에 연결한다.\n사용 가능한 액션 액션 설명 click 요소 클릭 type 텍스트 입력 drag 드래그 앤 드롭 select 드롭다운 선택 snapshot 페이지 접근성 스냅샷 (텍스트 기반) screenshot 페이지 스크린샷 (이미지) 스냅샷 vs 스크린샷 스냅샷: 접근성 트리 기반의 텍스트 표현. 토큰 소모가 적고 빠름 스크린샷: 실제 화면 이미지. 시각적 확인이 필요할 때 사용 보안 브라우저 도구는 루프백(loopback) 전용 접근만 허용한다. 외부에서 브라우저 인스턴스에 직접 접근할 수 없다.\n환경 변수를 통해 인증 정보를 전달할 수 있다.\n{ \u0026#34;tools\u0026#34;: { \u0026#34;browser\u0026#34;: { \u0026#34;profile\u0026#34;: \u0026#34;openclaw\u0026#34;, \u0026#34;env\u0026#34;: { \u0026#34;LOGIN_USER\u0026#34;: \u0026#34;${BROWSER_USER}\u0026#34;, \u0026#34;LOGIN_PASS\u0026#34;: \u0026#34;${BROWSER_PASS}\u0026#34; } } } } CLI 명령어 브라우저 상태 확인 openclaw browser status 현재 브라우저 인스턴스 상태, 활성 프로필, 열린 탭 수를 확인한다.\n브라우저 열기 openclaw browser open [URL] 지정한 URL을 브라우저에서 연다.\n스냅샷 캡처 openclaw browser snapshot 현재 페이지의 접근성 스냅샷을 출력한다.\n원격 CDP 연결 클라우드 브라우저 서비스(Browserless, Browserbase 등)를 사용할 수 있다.\n{ \u0026#34;tools\u0026#34;: { \u0026#34;browser\u0026#34;: { \u0026#34;profile\u0026#34;: \u0026#34;custom\u0026#34;, \u0026#34;cdpEndpoint\u0026#34;: \u0026#34;wss://chrome.browserless.io?token=YOUR_TOKEN\u0026#34; } } } 원격 CDP를 사용하면 로컬에 브라우저를 설치하지 않아도 되며, 서버 환경에서도 브라우저 자동화가 가능하다.\n","permalink":"https://jungwoo0716.github.io/docs/openclaw/20-%EB%B8%8C%EB%9D%BC%EC%9A%B0%EC%A0%80%EB%8F%84%EA%B5%AC/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw의 브라우저 도구는 에이전트가 \u003cstrong\u003e격리된 브라우저 프로필\u003c/strong\u003e을 통해 웹 페이지를 탐색하고 조작할 수 있게 한다. Chrome, Brave, Edge를 지원하며, 로컬 또는 원격 CDP(Chrome DevTools Protocol) 연결을 통해 작동한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"브라우저-프로필\"\u003e브라우저 프로필\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e프로필\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n          \u003cth\u003e용도\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eopenclaw\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eOpenClaw가 관리하는 격리 프로필\u003c/td\u003e\n          \u003ctd\u003e기본 자동화 작업\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003euser\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eDevTools MCP를 통한 사용자 브라우저\u003c/td\u003e\n          \u003ctd\u003e로그인된 세션 활용\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecustom\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e원격 CDP 엔드포인트 연결\u003c/td\u003e\n          \u003ctd\u003e클라우드 브라우저 서비스\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"openclaw-프로필-기본\"\u003eopenclaw 프로필 (기본)\u003c/h3\u003e\n\u003cp\u003eOpenClaw가 자체 관리하는 브라우저 인스턴스를 사용한다. 사용자 브라우저와 완전히 격리되어 있어 기존 세션, 쿠키, 확장 프로그램에 영향을 주지 않는다.\u003c/p\u003e","title":"브라우저 도구"},{"content":"어댑터는 Paperclip의 오케스트레이션 시스템과 서로 다른 AI 에이전트 런타임 사이의 커넥터입니다. 호출과 결과 캡처를 처리합니다.\n실행 프로세스 하트비트가 트리거되면:\n시스템이 에이전트의 어댑터 타입 식별 컨텍스트와 함께 실행 런타임 생성 stdout 및 사용량 데이터를 포함한 구조화된 결과 반환 빌트인 어댑터 어댑터 설명 claude_local Anthropic Claude Code CLI codex_local OpenAI Codex CLI gemini_local Google Gemini CLI opencode_local OpenCode CLI cursor Cursor CLI openclaw_gateway OpenClaw 게이트웨이 hermes_local Hermes 에이전트 pi_local Pi 에이전트 process 임의의 셸 명령 http 외부 웹훅 기술 구조 각 어댑터는 3개의 모듈로 구성:\n공유 인덱스 — 메타데이터 정의 서버 컴포넌트 — 실행 및 파싱 처리 UI/CLI 모듈 — 트랜스크립트 렌더링 및 터미널 포맷팅 선택 가이드 코딩 에이전트 필요? → claude_local, codex_local, gemini_local, opencode_local 스크립트 실행? → process 외부 서비스? → http 특수 런타임? → 커스텀 어댑터 생성 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/20-%EC%96%B4%EB%8C%91%ED%84%B0%EA%B0%9C%EC%9A%94/","summary":"\u003cp\u003e어댑터는 Paperclip의 오케스트레이션 시스템과 서로 다른 AI 에이전트 런타임 사이의 커넥터입니다. 호출과 결과 캡처를 처리합니다.\u003c/p\u003e\n\u003ch2 id=\"실행-프로세스\"\u003e실행 프로세스\u003c/h2\u003e\n\u003cp\u003e하트비트가 트리거되면:\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e시스템이 에이전트의 어댑터 타입 식별\u003c/li\u003e\n\u003cli\u003e컨텍스트와 함께 실행\u003c/li\u003e\n\u003cli\u003e런타임 생성\u003c/li\u003e\n\u003cli\u003estdout 및 사용량 데이터를 포함한 구조화된 결과 반환\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch2 id=\"빌트인-어댑터\"\u003e빌트인 어댑터\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e어댑터\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eclaude_local\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eAnthropic Claude Code CLI\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecodex_local\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eOpenAI Codex CLI\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003egemini_local\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eGoogle Gemini CLI\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eopencode_local\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eOpenCode CLI\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecursor\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eCursor CLI\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eopenclaw_gateway\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eOpenClaw 게이트웨이\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ehermes_local\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eHermes 에이전트\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003epi_local\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003ePi 에이전트\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eprocess\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e임의의 셸 명령\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ehttp\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e외부 웹훅\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"기술-구조\"\u003e기술 구조\u003c/h2\u003e\n\u003cp\u003e각 어댑터는 3개의 모듈로 구성:\u003c/p\u003e","title":"어댑터 개요"},{"content":"claude_local 어댑터는 Anthropic의 Claude Code CLI를 로컬 환경에 통합합니다. 세션 지속성, 스킬 주입, 구조화된 출력 파싱을 제공합니다.\n요구사항 Claude Code CLI 설치 (claude 명령 접근 가능) ANTHROPIC_API_KEY 환경변수 또는 에이전트 설정에서 구성 주요 설정 옵션 설정 설명 cwd (필수) 에이전트의 작업 디렉토리 절대 경로 model 사용할 Claude 버전 promptTemplate 변수 치환 지원 커스텀 프롬프트 ({{agentId}}, {{runId}}, {{agent.name}} 등) env 시크릿 참조를 포함한 환경 변수 timeoutSec 프로세스 타임아웃 graceSec 강제 종료 유예 기간 maxTurnsPerRun 하트비트당 에이전트 반복 제한 dangerouslySkipPermissions (개발 전용) 권한 검사 우회 플래그 세션 관리 하트비트 간 Claude Code 세션 ID를 유지합니다. 전체 컨텍스트 보존으로 대화를 재개합니다. 작업 디렉토리가 변경되거나 알 수 없는 세션 오류가 발생하면 세션이 리셋됩니다.\n스킬 통합 스킬은 심링크가 있는 임시 디렉토리를 통해 발견 가능하게 됩니다. --add-dir을 통해 메인 워크스페이스를 어지럽히지 않고 전달합니다.\n설정 검증 \u0026ldquo;환경 테스트\u0026rdquo; 버튼이 검증하는 항목:\nCLI 설치 여부 디렉토리 가용성 API 인증 설정 테스트 프롬프트를 통한 CLI 준비 상태 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/21-claude-local/","summary":"\u003cp\u003e\u003ccode\u003eclaude_local\u003c/code\u003e 어댑터는 Anthropic의 Claude Code CLI를 로컬 환경에 통합합니다. 세션 지속성, 스킬 주입, 구조화된 출력 파싱을 제공합니다.\u003c/p\u003e\n\u003ch2 id=\"요구사항\"\u003e요구사항\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003eClaude Code CLI 설치 (\u003ccode\u003eclaude\u003c/code\u003e 명령 접근 가능)\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003eANTHROPIC_API_KEY\u003c/code\u003e 환경변수 또는 에이전트 설정에서 구성\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"주요-설정-옵션\"\u003e주요 설정 옵션\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e설정\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecwd\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e(필수) 에이전트의 작업 디렉토리 절대 경로\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003emodel\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e사용할 Claude 버전\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003epromptTemplate\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e변수 치환 지원 커스텀 프롬프트 ({{agentId}}, {{runId}}, {{agent.name}} 등)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eenv\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e시크릿 참조를 포함한 환경 변수\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003etimeoutSec\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로세스 타임아웃\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003egraceSec\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e강제 종료 유예 기간\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003emaxTurnsPerRun\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e하트비트당 에이전트 반복 제한\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003edangerouslySkipPermissions\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e(개발 전용) 권한 검사 우회 플래그\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"세션-관리\"\u003e세션 관리\u003c/h2\u003e\n\u003cp\u003e하트비트 간 \u003cstrong\u003eClaude Code 세션 ID를 유지\u003c/strong\u003e합니다. 전체 컨텍스트 보존으로 대화를 재개합니다. 작업 디렉토리가 변경되거나 알 수 없는 세션 오류가 발생하면 세션이 리셋됩니다.\u003c/p\u003e","title":"Claude Local 어댑터"},{"content":"개요 web_search 도구는 에이전트가 인터넷 검색을 수행하여 최신 정보를 가져올 수 있게 한다. 10개의 검색 프로바이더를 지원하며, 15분 캐시를 통해 중복 검색 비용을 절감한다.\n지원 프로바이더 프로바이더 특징 Brave 프라이버시 중심, 자체 인덱스 DuckDuckGo API 키 불필요, 무료 Exa 시맨틱 검색 특화 Firecrawl 웹 스크래핑 + 검색 Gemini Google AI 기반 검색 Grok xAI 기반 검색 Kimi 중국어 검색 특화 Perplexity AI 요약 검색 SearXNG 셀프 호스팅 메타 검색 Tavily AI 에이전트 최적화 검색 프로바이더 자동 감지 API 키가 설정된 프로바이더를 자동으로 감지하여 우선순위에 따라 사용한다. 수동으로 프로바이더를 지정할 수도 있다.\n{ \u0026#34;tools\u0026#34;: { \u0026#34;webSearch\u0026#34;: { \u0026#34;provider\u0026#34;: \u0026#34;tavily\u0026#34;, \u0026#34;apiKey\u0026#34;: \u0026#34;${TAVILY_API_KEY}\u0026#34; } } } 검색 파라미터 파라미터 타입 설명 기본값 query string 검색 쿼리 (필수) count number 결과 수 10 country string 국가 코드 (kr, us 등) 자동 language string 언어 코드 (ko, en 등) 자동 freshness string 최신성 필터 (day, week, month) 없음 캐시 검색 결과는 15분간 캐시된다. 동일한 쿼리를 반복 실행해도 캐시 기간 내에는 새로운 API 호출이 발생하지 않는다.\n[검색 요청] → 캐시 확인 → 히트 → 캐시 결과 반환 → 미스 → 프로바이더 API 호출 → 결과 캐시 → 반환 특수 검색 도구 x_search (트위터 검색) 트위터/X 게시물을 검색하는 전용 도구이다.\nx_search(\u0026#34;OpenClaw 릴리즈\u0026#34;) web_fetch (URL 조회) 특정 URL의 콘텐츠를 가져온다. 검색이 아닌 직접 URL 접근에 사용한다.\nweb_fetch(\u0026#34;https://example.com/api-docs\u0026#34;) 설정 CLI를 통한 대화형 설정 openclaw configure --section web 프로바이더 선택, API 키 입력, 기본 파라미터를 대화형으로 설정한다.\n설정 파일 직접 수정 { \u0026#34;tools\u0026#34;: { \u0026#34;webSearch\u0026#34;: { \u0026#34;provider\u0026#34;: \u0026#34;brave\u0026#34;, \u0026#34;apiKey\u0026#34;: \u0026#34;${BRAVE_API_KEY}\u0026#34;, \u0026#34;defaults\u0026#34;: { \u0026#34;count\u0026#34;: 5, \u0026#34;country\u0026#34;: \u0026#34;kr\u0026#34;, \u0026#34;language\u0026#34;: \u0026#34;ko\u0026#34; } } } } 사용 예시 에이전트가 검색을 수행하는 흐름:\n사용자가 \u0026ldquo;최근 OpenClaw 업데이트 알려줘\u0026quot;라고 요청 에이전트가 web_search(\u0026quot;OpenClaw latest update 2026\u0026quot;) 호출 검색 결과에서 관련 정보 추출 필요시 web_fetch로 상세 페이지 조회 요약하여 사용자에게 응답 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/21-%EC%9B%B9%EA%B2%80%EC%83%89%EB%8F%84%EA%B5%AC/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003eweb_search\u003c/code\u003e 도구는 에이전트가 인터넷 검색을 수행하여 최신 정보를 가져올 수 있게 한다. 10개의 검색 프로바이더를 지원하며, 15분 캐시를 통해 중복 검색 비용을 절감한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"지원-프로바이더\"\u003e지원 프로바이더\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e프로바이더\u003c/th\u003e\n          \u003cth\u003e특징\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eBrave\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e프라이버시 중심, 자체 인덱스\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eDuckDuckGo\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eAPI 키 불필요, 무료\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eExa\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e시맨틱 검색 특화\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eFirecrawl\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e웹 스크래핑 + 검색\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eGemini\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eGoogle AI 기반 검색\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eGrok\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003exAI 기반 검색\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eKimi\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e중국어 검색 특화\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003ePerplexity\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eAI 요약 검색\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eSearXNG\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e셀프 호스팅 메타 검색\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eTavily\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eAI 에이전트 최적화 검색\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003chr\u003e\n\u003ch2 id=\"프로바이더-자동-감지\"\u003e프로바이더 자동 감지\u003c/h2\u003e\n\u003cp\u003eAPI 키가 설정된 프로바이더를 자동으로 감지하여 우선순위에 따라 사용한다. 수동으로 프로바이더를 지정할 수도 있다.\u003c/p\u003e","title":"웹 검색 도구"},{"content":"codex_local 어댑터는 OpenAI의 Codex CLI를 로컬에서 실행합니다.\n요구사항 Codex CLI 설치 OPENAI_API_KEY 환경변수 또는 에이전트 설정에서 구성 주요 설정 옵션 설정 설명 cwd (필수) 에이전트가 작업하는 절대 디렉토리 경로 model 사용할 모델 promptTemplate 모든 실행에 적용되는 커스텀 프롬프트 env 시크릿 참조를 포함한 환경 변수 timeoutSec 프로세스 타이밍 제어 graceSec 종료 동작 dangerouslyBypassApprovalsAndSandbox (개발용) 안전 메커니즘 비활성화 작동 방식 세션 간 previous_response_id 체이닝으로 대화 연속성을 유지합니다. ~/.codex/skills에 심링크를 생성하여 Paperclip 스킬을 자동 통합하며, 기존 사용자 스킬을 보존합니다.\n검증 프로세스 실행 전 시스템이 확인하는 항목:\nCodex CLI 접근 가능 여부 작업 디렉토리가 절대 경로이고 사용 가능한지 API 키 존재 여부 \u0026ldquo;hello\u0026rdquo; 테스트 실행을 통한 CLI 기능 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/22-codex-local/","summary":"\u003cp\u003e\u003ccode\u003ecodex_local\u003c/code\u003e 어댑터는 OpenAI의 Codex CLI를 로컬에서 실행합니다.\u003c/p\u003e\n\u003ch2 id=\"요구사항\"\u003e요구사항\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003eCodex CLI 설치\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003eOPENAI_API_KEY\u003c/code\u003e 환경변수 또는 에이전트 설정에서 구성\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"주요-설정-옵션\"\u003e주요 설정 옵션\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e설정\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecwd\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e(필수) 에이전트가 작업하는 절대 디렉토리 경로\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003emodel\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e사용할 모델\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003epromptTemplate\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e모든 실행에 적용되는 커스텀 프롬프트\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eenv\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e시크릿 참조를 포함한 환경 변수\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003etimeoutSec\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로세스 타이밍 제어\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003egraceSec\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e종료 동작\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003edangerouslyBypassApprovalsAndSandbox\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e(개발용) 안전 메커니즘 비활성화\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"작동-방식\"\u003e작동 방식\u003c/h2\u003e\n\u003cp\u003e세션 간 \u003ccode\u003eprevious_response_id\u003c/code\u003e 체이닝으로 대화 연속성을 유지합니다. \u003ccode\u003e~/.codex/skills\u003c/code\u003e에 심링크를 생성하여 Paperclip 스킬을 자동 통합하며, 기존 사용자 스킬을 보존합니다.\u003c/p\u003e","title":"Codex Local 어댑터"},{"content":"개요 exec 도구는 에이전트가 셸 명령어를 실행할 수 있게 한다. 포그라운드 실행과 process를 통한 백그라운드 실행을 지원하며, 승인 모드와 허용 목록으로 보안을 관리한다.\n실행 방식 포그라운드 실행 명령어를 실행하고 완료될 때까지 대기한다. 기본 타임아웃은 **1800초(30분)**이다.\nexec(\u0026#34;ls -la /tmp\u0026#34;) 백그라운드 실행 process 도구를 통해 장시간 실행되는 명령어를 백그라운드에서 처리한다.\nprocess.start(\u0026#34;npm run build\u0026#34;) process.status(\u0026#34;pid-123\u0026#34;) process.kill(\u0026#34;pid-123\u0026#34;) 실행 호스트 명령어가 실행되는 환경을 지정한다.\n호스트 설명 sandbox 샌드박스 환경 (기본값). Docker 또는 SSH 격리 gateway 게이트웨이 프로세스에서 직접 실행 node 특정 노드에서 실행 { \u0026#34;tools\u0026#34;: { \u0026#34;exec\u0026#34;: { \u0026#34;host\u0026#34;: \u0026#34;sandbox\u0026#34;, \u0026#34;timeout\u0026#34;: 1800 } } } 승인 모드 명령어 실행 전 승인을 요구하는 수준을 설정한다.\n모드 설명 off 승인 없이 모든 명령 실행 on-miss 허용 목록에 없는 명령만 승인 요청 (기본값) always 모든 명령 실행 전 승인 요청 on-miss (기본값) 허용 목록(allowlist)에 등록된 명령어는 승인 없이 실행되고, 등록되지 않은 명령어는 사용자에게 승인을 요청한다.\n{ \u0026#34;tools\u0026#34;: { \u0026#34;exec\u0026#34;: { \u0026#34;approvalMode\u0026#34;: \u0026#34;on-miss\u0026#34;, \u0026#34;allowlist\u0026#34;: [ \u0026#34;ls\u0026#34;, \u0026#34;cat\u0026#34;, \u0026#34;head\u0026#34;, \u0026#34;tail\u0026#34;, \u0026#34;grep\u0026#34;, \u0026#34;git status\u0026#34;, \u0026#34;git log\u0026#34;, \u0026#34;git diff\u0026#34;, \u0026#34;node\u0026#34;, \u0026#34;npm\u0026#34;, \u0026#34;npx\u0026#34;, \u0026#34;python\u0026#34;, \u0026#34;pip\u0026#34; ] } } } 허용 목록 (Allowlist) 허용 목록은 해석된 바이너리 경로를 기준으로 검증한다. 심볼릭 링크나 별칭(alias)이 아닌 실제 바이너리 경로로 확인한다.\n\u0026#34;ls\u0026#34; → /bin/ls (허용) \u0026#34;my-alias\u0026#34; → /usr/local/bin/dangerous-tool (차단) 보안 환경 변수 차단 다음 환경 변수의 오버라이드가 차단된다.\n변수 이유 PATH 악의적 바이너리 경로 주입 방지 LD_PRELOAD 라이브러리 인젝션 방지 LD_LIBRARY_PATH 라이브러리 경로 조작 방지 PATH 확장 차단 대신 pathPrepend를 사용하여 안전하게 PATH를 확장할 수 있다.\n{ \u0026#34;tools\u0026#34;: { \u0026#34;exec\u0026#34;: { \u0026#34;pathPrepend\u0026#34;: [\u0026#34;/usr/local/custom/bin\u0026#34;] } } } 추가 설정 strictInlineEval 인라인 코드 실행(eval, backtick 등)을 엄격하게 제한한다.\n{ \u0026#34;tools\u0026#34;: { \u0026#34;exec\u0026#34;: { \u0026#34;strictInlineEval\u0026#34;: true } } } 활성화하면 $(...), `...`, eval 등의 인라인 실행을 차단하여 명령어 인젝션을 방지한다.\n실행 흐름 [에이전트가 exec 요청] │ ▼ 승인 모드 확인 │ ┌────┴────┐ │ │ off on-miss / always │ │ │ 허용목록 확인 │ ┌────┴────┐ │ │ │ │ 허용 미등록 │ │ │ │ │ 사용자 승인 요청 │ │ ┌────┴────┐ │ │ │ │ │ │ 승인 거부 │ │ │ │ ▼ ▼ ▼ ▼ 실행 실행 실행 중단 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/22-%EC%8B%A4%ED%96%89%EB%8F%84%EA%B5%AC/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003eexec\u003c/code\u003e 도구는 에이전트가 셸 명령어를 실행할 수 있게 한다. 포그라운드 실행과 \u003ccode\u003eprocess\u003c/code\u003e를 통한 백그라운드 실행을 지원하며, 승인 모드와 허용 목록으로 보안을 관리한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"실행-방식\"\u003e실행 방식\u003c/h2\u003e\n\u003ch3 id=\"포그라운드-실행\"\u003e포그라운드 실행\u003c/h3\u003e\n\u003cp\u003e명령어를 실행하고 완료될 때까지 대기한다. 기본 타임아웃은 **1800초(30분)**이다.\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eexec(\u0026#34;ls -la /tmp\u0026#34;)\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"백그라운드-실행\"\u003e백그라운드 실행\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003eprocess\u003c/code\u003e 도구를 통해 장시간 실행되는 명령어를 백그라운드에서 처리한다.\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eprocess.start(\u0026#34;npm run build\u0026#34;)\nprocess.status(\u0026#34;pid-123\u0026#34;)\nprocess.kill(\u0026#34;pid-123\u0026#34;)\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"실행-호스트\"\u003e실행 호스트\u003c/h2\u003e\n\u003cp\u003e명령어가 실행되는 환경을 지정한다.\u003c/p\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e호스트\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003esandbox\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e샌드박스 환경 (기본값). Docker 또는 SSH 격리\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003egateway\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e게이트웨이 프로세스에서 직접 실행\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003enode\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e특정 노드에서 실행\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;tools\u0026#34;: {\n    \u0026#34;exec\u0026#34;: {\n      \u0026#34;host\u0026#34;: \u0026#34;sandbox\u0026#34;,\n      \u0026#34;timeout\u0026#34;: 1800\n    }\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"승인-모드\"\u003e승인 모드\u003c/h2\u003e\n\u003cp\u003e명령어 실행 전 승인을 요구하는 수준을 설정한다.\u003c/p\u003e","title":"실행 도구 (Exec)"},{"content":"gemini_local 어댑터는 Google의 Gemini CLI를 로컬에서 실행합니다. --resume으로 세션 지속성, 스킬 주입, 구조화된 stream-json 출력 처리를 지원합니다.\n요구사항 Gemini CLI 설치 및 접근 가능 GEMINI_API_KEY, GOOGLE_API_KEY 또는 로컬 CLI 설정으로 인증 설정 옵션 필드 용도 cwd 작업 디렉토리 (필수, 절대 경로) model Gemini 모델 선택 (기본값: auto) promptTemplate 모든 실행용 커스텀 프롬프트 instructionsFilePath 앞에 추가할 마크다운 지시사항 env 시크릿 지원 환경 변수 timeoutSec 프로세스 타임아웃 임계값 graceSec 강제 종료 유예 기간 yolo 무인 작업 모드 활성화 세션 관리 작업 디렉토리가 일관되면 세션이 자동 재개됩니다. 디렉토리가 변경되거나 재개 실패 시 새 세션이 시작됩니다.\n검증 \u0026ldquo;환경 테스트\u0026rdquo; 버튼: CLI 설치, 디렉토리 접근, API 키 설정, 테스트 프로브를 통한 CLI 준비 상태 확인.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/23-gemini-local/","summary":"\u003cp\u003e\u003ccode\u003egemini_local\u003c/code\u003e 어댑터는 Google의 Gemini CLI를 로컬에서 실행합니다. \u003ccode\u003e--resume\u003c/code\u003e으로 세션 지속성, 스킬 주입, 구조화된 \u003ccode\u003estream-json\u003c/code\u003e 출력 처리를 지원합니다.\u003c/p\u003e\n\u003ch2 id=\"요구사항\"\u003e요구사항\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003eGemini CLI 설치 및 접근 가능\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003eGEMINI_API_KEY\u003c/code\u003e, \u003ccode\u003eGOOGLE_API_KEY\u003c/code\u003e 또는 로컬 CLI 설정으로 인증\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"설정-옵션\"\u003e설정 옵션\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e필드\u003c/th\u003e\n          \u003cth\u003e용도\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecwd\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e작업 디렉토리 (필수, 절대 경로)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003emodel\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eGemini 모델 선택 (기본값: \u003ccode\u003eauto\u003c/code\u003e)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003epromptTemplate\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e모든 실행용 커스텀 프롬프트\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003einstructionsFilePath\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e앞에 추가할 마크다운 지시사항\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eenv\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e시크릿 지원 환경 변수\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003etimeoutSec\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로세스 타임아웃 임계값\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003egraceSec\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e강제 종료 유예 기간\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eyolo\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e무인 작업 모드 활성화\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"세션-관리\"\u003e세션 관리\u003c/h2\u003e\n\u003cp\u003e작업 디렉토리가 일관되면 세션이 자동 재개됩니다. 디렉토리가 변경되거나 재개 실패 시 새 세션이 시작됩니다.\u003c/p\u003e","title":"Gemini Local 어댑터"},{"content":"개요 서브 에이전트는 주 에이전트가 생성하는 백그라운드 프로세스이다. 독립된 컨텍스트에서 실행되며, 비동기적으로 작업을 처리하고 결과를 요청 채널에 요약하여 보고한다.\n동작 방식 주 에이전트가 서브 에이전트를 스폰(spawn) 서브 에이전트가 격리된 컨텍스트에서 작업 수행 논블로킹(non-blocking) 방식으로 runId 즉시 반환 작업 완료 시 요약을 요청 채널에 포스팅 [주 에이전트] ──spawn──→ [서브 에이전트 #1] ──(작업 중)──→ [요약 포스트] ──spawn──→ [서브 에이전트 #2] ──(작업 중)──→ [요약 포스트] ──(계속 다른 작업)──→ /subagents 명령어 명령어 설명 /subagents list 활성 서브 에이전트 목록 /subagents kill \u0026lt;runId\u0026gt; 특정 서브 에이전트 종료 /subagents log \u0026lt;runId\u0026gt; 서브 에이전트 실행 로그 확인 /subagents spawn \u0026lt;task\u0026gt; 수동으로 서브 에이전트 스폰 서브 에이전트 목록 확인 /subagents list RunID | Status | Task | Started -----------|----------|-------------------|------------------ run-abc123 | running | 웹 리서치 | 2026-04-01 09:15 run-def456 | complete | 데이터 분석 | 2026-04-01 09:10 중첩 (Nesting) 서브 에이전트는 자체적으로 다시 서브 에이전트를 스폰할 수 있다.\n설정 기본값 설명 maxSpawnDepth 2 최대 중첩 깊이 최대 중첩 에이전트 수 5 중첩 체인 전체의 최대 수 주 에이전트 (depth 0) └─ 서브 에이전트 A (depth 1) └─ 서브 에이전트 A-1 (depth 2) ← 최대 깊이 └─ 스폰 불가 (depth 3) 동시성 제어 설정 기본값 설명 maxConcurrent 8 동시 실행 가능한 최대 서브 에이전트 수 { \u0026#34;agents\u0026#34;: { \u0026#34;subagents\u0026#34;: { \u0026#34;maxConcurrent\u0026#34;: 8, \u0026#34;maxSpawnDepth\u0026#34;: 2 } } } 동시 실행 수가 한계에 도달하면 새로운 스폰 요청은 대기열에 추가된다.\n격리된 컨텍스트 서브 에이전트는 주 에이전트와 독립된 컨텍스트를 가진다.\n별도의 대화 히스토리 독립적인 토큰 사용량 계산 주 에이전트의 세션과 분리 워크스페이스는 공유 (같은 파일 시스템 접근) 토큰 회계 서브 에이전트의 토큰 사용량은 독립적으로 집계된다.\n주 에이전트: 10,000 토큰 서브 에이전트 #1: 3,000 토큰 서브 에이전트 #2: 5,000 토큰 ────────────────────────────── 총 사용량: 18,000 토큰 비용 관리를 위해 서브 에이전트의 최대 토큰을 제한할 수 있다.\n{ \u0026#34;agents\u0026#34;: { \u0026#34;subagents\u0026#34;: { \u0026#34;maxTokensPerRun\u0026#34;: 50000 } } } 결과 보고 서브 에이전트가 작업을 완료하면 요약을 요청자 채널에 포스팅한다.\nDM에서 스폰된 경우 → 해당 DM에 요약 전송 그룹에서 스폰된 경우 → 해당 그룹에 요약 전송 크론에서 스폰된 경우 → 설정된 알림 채널에 전송 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/23-%EC%84%9C%EB%B8%8C%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e서브 에이전트는 주 에이전트가 생성하는 \u003cstrong\u003e백그라운드 프로세스\u003c/strong\u003e이다. 독립된 컨텍스트에서 실행되며, 비동기적으로 작업을 처리하고 결과를 요청 채널에 요약하여 보고한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"동작-방식\"\u003e동작 방식\u003c/h2\u003e\n\u003col\u003e\n\u003cli\u003e주 에이전트가 서브 에이전트를 스폰(spawn)\u003c/li\u003e\n\u003cli\u003e서브 에이전트가 격리된 컨텍스트에서 작업 수행\u003c/li\u003e\n\u003cli\u003e논블로킹(non-blocking) 방식으로 \u003ccode\u003erunId\u003c/code\u003e 즉시 반환\u003c/li\u003e\n\u003cli\u003e작업 완료 시 요약을 요청 채널에 포스팅\u003c/li\u003e\n\u003c/ol\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003e[주 에이전트] ──spawn──→ [서브 에이전트 #1] ──(작업 중)──→ [요약 포스트]\n            ──spawn──→ [서브 에이전트 #2] ──(작업 중)──→ [요약 포스트]\n            ──(계속 다른 작업)──→\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"subagents-명령어\"\u003e/subagents 명령어\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e명령어\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e/subagents list\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e활성 서브 에이전트 목록\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e/subagents kill \u0026lt;runId\u0026gt;\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e특정 서브 에이전트 종료\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e/subagents log \u0026lt;runId\u0026gt;\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e서브 에이전트 실행 로그 확인\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e/subagents spawn \u0026lt;task\u0026gt;\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e수동으로 서브 에이전트 스폰\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"서브-에이전트-목록-확인\"\u003e서브 에이전트 목록 확인\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e/subagents list\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eRunID      | Status   | Task              | Started\n-----------|----------|-------------------|------------------\nrun-abc123 | running  | 웹 리서치          | 2026-04-01 09:15\nrun-def456 | complete | 데이터 분석         | 2026-04-01 09:10\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"중첩-nesting\"\u003e중첩 (Nesting)\u003c/h2\u003e\n\u003cp\u003e서브 에이전트는 자체적으로 다시 서브 에이전트를 스폰할 수 있다.\u003c/p\u003e","title":"서브 에이전트"},{"content":"HTTP 어댑터는 외부 에이전트 서비스를 트리거하는 웹훅 메커니즘입니다. Fire-and-forget 모델로 작동하며 stdout 캡처나 실시간 실행 가시성을 제공하지 않습니다.\n적합한 경우 외부 서비스 배포 (클라우드 함수, 전용 서버) 비동기 호출 패턴 서드파티 에이전트 플랫폼 통합 부적합한 경우 같은 머신에서 로컬 실행하는 에이전트 출력 스트림 캡처가 필요한 시나리오 설정 파라미터 필드 설명 필수 URL POST 요청을 보낼 웹훅 URL 예 헤더 커스텀 HTTP 헤더 아니오 타임아웃 초 단위 타임아웃 아니오 작동 흐름 Paperclip이 지정 엔드포인트에 실행 메타데이터가 담긴 POST 요청 전송 외부 에이전트가 페이로드 처리 제공된 API 자격증명으로 Paperclip에 인증된 콜백 요청 요청 구조 { \u0026#34;runId\u0026#34;: \u0026#34;...\u0026#34;, \u0026#34;agentId\u0026#34;: \u0026#34;...\u0026#34;, \u0026#34;companyId\u0026#34;: \u0026#34;...\u0026#34;, \u0026#34;context\u0026#34;: { \u0026#34;taskId\u0026#34;: \u0026#34;...\u0026#34;, \u0026#34;wakeReason\u0026#34;: \u0026#34;...\u0026#34;, \u0026#34;commentId\u0026#34;: \u0026#34;...\u0026#34; } } ","permalink":"https://jungwoo0716.github.io/docs/paperclip/24-http%EC%96%B4%EB%8C%91%ED%84%B0/","summary":"\u003cp\u003eHTTP 어댑터는 외부 에이전트 서비스를 트리거하는 웹훅 메커니즘입니다. Fire-and-forget 모델로 작동하며 stdout 캡처나 실시간 실행 가시성을 제공하지 않습니다.\u003c/p\u003e\n\u003ch2 id=\"적합한-경우\"\u003e적합한 경우\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e외부 서비스 배포 (클라우드 함수, 전용 서버)\u003c/li\u003e\n\u003cli\u003e비동기 호출 패턴\u003c/li\u003e\n\u003cli\u003e서드파티 에이전트 플랫폼 통합\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"부적합한-경우\"\u003e부적합한 경우\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e같은 머신에서 로컬 실행하는 에이전트\u003c/li\u003e\n\u003cli\u003e출력 스트림 캡처가 필요한 시나리오\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"설정-파라미터\"\u003e설정 파라미터\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e필드\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n          \u003cth\u003e필수\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eURL\u003c/td\u003e\n          \u003ctd\u003ePOST 요청을 보낼 웹훅 URL\u003c/td\u003e\n          \u003ctd\u003e예\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e헤더\u003c/td\u003e\n          \u003ctd\u003e커스텀 HTTP 헤더\u003c/td\u003e\n          \u003ctd\u003e아니오\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e타임아웃\u003c/td\u003e\n          \u003ctd\u003e초 단위 타임아웃\u003c/td\u003e\n          \u003ctd\u003e아니오\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"작동-흐름\"\u003e작동 흐름\u003c/h2\u003e\n\u003col\u003e\n\u003cli\u003ePaperclip이 지정 엔드포인트에 실행 메타데이터가 담긴 POST 요청 전송\u003c/li\u003e\n\u003cli\u003e외부 에이전트가 페이로드 처리\u003c/li\u003e\n\u003cli\u003e제공된 API 자격증명으로 Paperclip에 인증된 콜백 요청\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch2 id=\"요청-구조\"\u003e요청 구조\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-json\" data-lang=\"json\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e{\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e  \u003cspan style=\"color:#f92672\"\u003e\u0026#34;runId\u0026#34;\u003c/span\u003e: \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;...\u0026#34;\u003c/span\u003e,\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e  \u003cspan style=\"color:#f92672\"\u003e\u0026#34;agentId\u0026#34;\u003c/span\u003e: \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;...\u0026#34;\u003c/span\u003e,\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e  \u003cspan style=\"color:#f92672\"\u003e\u0026#34;companyId\u0026#34;\u003c/span\u003e: \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;...\u0026#34;\u003c/span\u003e,\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e  \u003cspan style=\"color:#f92672\"\u003e\u0026#34;context\u0026#34;\u003c/span\u003e: {\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e    \u003cspan style=\"color:#f92672\"\u003e\u0026#34;taskId\u0026#34;\u003c/span\u003e: \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;...\u0026#34;\u003c/span\u003e,\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e    \u003cspan style=\"color:#f92672\"\u003e\u0026#34;wakeReason\u0026#34;\u003c/span\u003e: \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;...\u0026#34;\u003c/span\u003e,\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e    \u003cspan style=\"color:#f92672\"\u003e\u0026#34;commentId\u0026#34;\u003c/span\u003e: \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;...\u0026#34;\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e  }\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e}\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e","title":"HTTP 어댑터"},{"content":"개요 image_generate 도구를 통해 에이전트가 텍스트 프롬프트로 이미지를 생성하거나 기존 이미지를 편집할 수 있다. 여러 프로바이더를 지원하며, 프로바이더 장애 시 자동 폴백을 제공한다.\n지원 프로바이더 프로바이더 모델 이미지 편집 OpenAI gpt-image-1 지원 Google gemini 지원 fal flux 미지원 MiniMax minimax 미지원 편집 지원 여부는 프로바이더에 따라 다르다. OpenAI와 Google은 기존 이미지를 입력받아 편집할 수 있지만, fal과 MiniMax는 텍스트-투-이미지만 지원한다.\n파라미터 파라미터 타입 설명 기본값 prompt string 이미지 생성 프롬프트 (필수) action string generate 또는 edit generate model string 사용할 모델 프로바이더 기본값 size string 이미지 크기 (1024x1024 등) 1024x1024 aspectRatio string 종횡비 (16:9, 1:1 등) 1:1 count number 생성할 이미지 수 1 size vs aspectRatio size: 정확한 픽셀 크기 지정 (예: 1024x1024, 1792x1024) aspectRatio: 비율만 지정하고 크기는 프로바이더가 결정 (예: 16:9) 둘 다 지정하면 size가 우선 자동 폴백 프로바이더 장애 시 자동으로 다음 프로바이더로 전환한다.\n[이미지 생성 요청] │ OpenAI 시도 → 실패 │ Google 시도 → 실패 │ fal 시도 → 성공 → 이미지 반환 폴백 순서는 설정 파일에서 커스터마이즈할 수 있다.\n설정 API 키 설정 { \u0026#34;tools\u0026#34;: { \u0026#34;imageGenerate\u0026#34;: { \u0026#34;provider\u0026#34;: \u0026#34;openai\u0026#34;, \u0026#34;apiKey\u0026#34;: \u0026#34;${OPENAI_API_KEY}\u0026#34;, \u0026#34;model\u0026#34;: \u0026#34;gpt-image-1\u0026#34; } } } 멀티 프로바이더 설정 { \u0026#34;tools\u0026#34;: { \u0026#34;imageGenerate\u0026#34;: { \u0026#34;providers\u0026#34;: { \u0026#34;openai\u0026#34;: { \u0026#34;apiKey\u0026#34;: \u0026#34;${OPENAI_API_KEY}\u0026#34; }, \u0026#34;google\u0026#34;: { \u0026#34;apiKey\u0026#34;: \u0026#34;${GOOGLE_API_KEY}\u0026#34; }, \u0026#34;fal\u0026#34;: { \u0026#34;apiKey\u0026#34;: \u0026#34;${FAL_API_KEY}\u0026#34; } }, \u0026#34;fallbackOrder\u0026#34;: [\u0026#34;openai\u0026#34;, \u0026#34;google\u0026#34;, \u0026#34;fal\u0026#34;] } } } 사용 예시 이미지 생성 image_generate({ prompt: \u0026#34;서울 야경이 보이는 카페, 수채화 스타일\u0026#34;, size: \u0026#34;1792x1024\u0026#34;, count: 1 }) 이미지 편집 image_generate({ action: \u0026#34;edit\u0026#34;, prompt: \u0026#34;배경을 해질녘으로 변경\u0026#34;, image: \u0026#34;\u0026lt;base64 또는 파일 경로\u0026gt;\u0026#34;, model: \u0026#34;gpt-image-1\u0026#34; }) ","permalink":"https://jungwoo0716.github.io/docs/openclaw/24-%EC%9D%B4%EB%AF%B8%EC%A7%80%EC%83%9D%EC%84%B1/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003eimage_generate\u003c/code\u003e 도구를 통해 에이전트가 텍스트 프롬프트로 이미지를 생성하거나 기존 이미지를 편집할 수 있다. 여러 프로바이더를 지원하며, 프로바이더 장애 시 자동 폴백을 제공한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"지원-프로바이더\"\u003e지원 프로바이더\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e프로바이더\u003c/th\u003e\n          \u003cth\u003e모델\u003c/th\u003e\n          \u003cth\u003e이미지 편집\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eOpenAI\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003egpt-image-1\u003c/td\u003e\n          \u003ctd\u003e지원\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eGoogle\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003egemini\u003c/td\u003e\n          \u003ctd\u003e지원\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003efal\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eflux\u003c/td\u003e\n          \u003ctd\u003e미지원\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eMiniMax\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eminimax\u003c/td\u003e\n          \u003ctd\u003e미지원\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003cp\u003e편집 지원 여부는 프로바이더에 따라 다르다. OpenAI와 Google은 기존 이미지를 입력받아 편집할 수 있지만, fal과 MiniMax는 텍스트-투-이미지만 지원한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"파라미터\"\u003e파라미터\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e파라미터\u003c/th\u003e\n          \u003cth\u003e타입\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n          \u003cth\u003e기본값\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eprompt\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003e이미지 생성 프롬프트\u003c/td\u003e\n          \u003ctd\u003e(필수)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eaction\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003egenerate\u003c/code\u003e 또는 \u003ccode\u003eedit\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003egenerate\u003c/code\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003emodel\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003e사용할 모델\u003c/td\u003e\n          \u003ctd\u003e프로바이더 기본값\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003esize\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003e이미지 크기 (\u003ccode\u003e1024x1024\u003c/code\u003e 등)\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e1024x1024\u003c/code\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003easpectRatio\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003e종횡비 (\u003ccode\u003e16:9\u003c/code\u003e, \u003ccode\u003e1:1\u003c/code\u003e 등)\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e1:1\u003c/code\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecount\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003enumber\u003c/td\u003e\n          \u003ctd\u003e생성할 이미지 수\u003c/td\u003e\n          \u003ctd\u003e1\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"size-vs-aspectratio\"\u003esize vs aspectRatio\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ccode\u003esize\u003c/code\u003e: 정확한 픽셀 크기 지정 (예: \u003ccode\u003e1024x1024\u003c/code\u003e, \u003ccode\u003e1792x1024\u003c/code\u003e)\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003easpectRatio\u003c/code\u003e: 비율만 지정하고 크기는 프로바이더가 결정 (예: \u003ccode\u003e16:9\u003c/code\u003e)\u003c/li\u003e\n\u003cli\u003e둘 다 지정하면 \u003ccode\u003esize\u003c/code\u003e가 우선\u003c/li\u003e\n\u003c/ul\u003e\n\u003chr\u003e\n\u003ch2 id=\"자동-폴백\"\u003e자동 폴백\u003c/h2\u003e\n\u003cp\u003e프로바이더 장애 시 자동으로 다음 프로바이더로 전환한다.\u003c/p\u003e","title":"이미지 생성"},{"content":"Process 어댑터는 임의의 셸 명령을 실행합니다. 간단한 스크립트, 일회성 작업, 커스텀 프레임워크 에이전트에 적합합니다.\n적합한 경우 Paperclip API를 호출하는 Python 스크립트 실행 커스텀 에이전트 루프 실행 셸 명령으로 호출 가능한 모든 런타임 부적합한 경우 실행 간 세션 지속성이 필요한 시나리오 하트비트 간 대화 컨텍스트가 필요한 에이전트 설정 파라미터 필드 타입 필수 용도 command string 예 실행할 셸 명령 cwd string 아니오 작업 디렉토리 env object 아니오 환경 변수 timeoutSec number 아니오 프로세스 타임아웃 작동 흐름 명령을 자식 프로세스로 생성 표준 Paperclip 환경 변수 주입 (PAPERCLIP_AGENT_ID, PAPERCLIP_API_KEY 등) 프로세스를 완료까지 실행 종료 코드로 성공 여부 판단 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/25-process%EC%96%B4%EB%8C%91%ED%84%B0/","summary":"\u003cp\u003eProcess 어댑터는 임의의 셸 명령을 실행합니다. 간단한 스크립트, 일회성 작업, 커스텀 프레임워크 에이전트에 적합합니다.\u003c/p\u003e\n\u003ch2 id=\"적합한-경우\"\u003e적합한 경우\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003ePaperclip API를 호출하는 Python 스크립트 실행\u003c/li\u003e\n\u003cli\u003e커스텀 에이전트 루프 실행\u003c/li\u003e\n\u003cli\u003e셸 명령으로 호출 가능한 모든 런타임\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"부적합한-경우\"\u003e부적합한 경우\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e실행 간 세션 지속성이 필요한 시나리오\u003c/li\u003e\n\u003cli\u003e하트비트 간 대화 컨텍스트가 필요한 에이전트\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"설정-파라미터\"\u003e설정 파라미터\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e필드\u003c/th\u003e\n          \u003cth\u003e타입\u003c/th\u003e\n          \u003cth\u003e필수\u003c/th\u003e\n          \u003cth\u003e용도\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecommand\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003e예\u003c/td\u003e\n          \u003ctd\u003e실행할 셸 명령\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecwd\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003e아니오\u003c/td\u003e\n          \u003ctd\u003e작업 디렉토리\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eenv\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eobject\u003c/td\u003e\n          \u003ctd\u003e아니오\u003c/td\u003e\n          \u003ctd\u003e환경 변수\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003etimeoutSec\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003enumber\u003c/td\u003e\n          \u003ctd\u003e아니오\u003c/td\u003e\n          \u003ctd\u003e프로세스 타임아웃\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"작동-흐름\"\u003e작동 흐름\u003c/h2\u003e\n\u003col\u003e\n\u003cli\u003e명령을 자식 프로세스로 생성\u003c/li\u003e\n\u003cli\u003e표준 Paperclip 환경 변수 주입 (\u003ccode\u003ePAPERCLIP_AGENT_ID\u003c/code\u003e, \u003ccode\u003ePAPERCLIP_API_KEY\u003c/code\u003e 등)\u003c/li\u003e\n\u003cli\u003e프로세스를 완료까지 실행\u003c/li\u003e\n\u003cli\u003e종료 코드로 성공 여부 판단\u003c/li\u003e\n\u003c/ol\u003e","title":"Process 어댑터"},{"content":"개요 WhatsApp 채널은 OpenClaw 에이전트를 WhatsApp 메신저에 연결한다. QR 코드 페어링으로 설정하며, DM/그룹 정책, 미디어 처리, 멀티 계정을 지원한다.\n설치 및 설정 플러그인 설치 openclaw onboard # 또는 openclaw channels add whatsapp QR 코드 페어링 openclaw channels login whatsapp 터미널에 QR 코드가 표시되면 WhatsApp 모바일 앱의 연결된 기기 메뉴에서 스캔한다.\nDM 정책 정책 설명 pairing 최초 메시지 시 페어링 승인 필요 (기본값) allowlist 허용 목록에 있는 번호만 DM 가능 open 모든 사용자의 DM 허용 disabled DM 비활성화 { \u0026#34;channels\u0026#34;: { \u0026#34;whatsapp\u0026#34;: { \u0026#34;dmPolicy\u0026#34;: \u0026#34;pairing\u0026#34;, \u0026#34;allowlist\u0026#34;: [ \u0026#34;+82-10-1234-5678\u0026#34;, \u0026#34;+82-10-9876-5432\u0026#34; ] } } } 페어링 방식 새 사용자가 에이전트에 DM 발송 에이전트가 \u0026ldquo;페어링 요청\u0026quot;을 관리자에게 알림 관리자가 승인하면 해당 사용자와 대화 시작 거부하면 해당 사용자의 메시지 무시 그룹 정책 그룹 허용 목록으로 에이전트가 참여할 그룹을 제한한다.\n{ \u0026#34;channels\u0026#34;: { \u0026#34;whatsapp\u0026#34;: { \u0026#34;groupAllowlist\u0026#34;: [ \u0026#34;그룹명 또는 그룹ID\u0026#34; ] } } } 메시지 제한 항목 제한 텍스트 청크 4,000자 미디어 파일 50MB 텍스트가 4,000자를 초과하면 자동으로 여러 메시지로 분할하여 전송한다.\n리액션 WhatsApp 리액션은 4단계로 지원된다.\n레벨 동작 0 리액션 비활성화 1 수신 리액션만 처리 2 처리 상태 리액션 (진행 중 이모지) 3 응답 결과 리액션 (성공/실패 이모지) 멀티 계정 하나의 게이트웨이에서 여러 WhatsApp 계정을 동시에 운영할 수 있다.\n{ \u0026#34;channels\u0026#34;: { \u0026#34;whatsapp\u0026#34;: [ { \u0026#34;id\u0026#34;: \u0026#34;cs-bot\u0026#34;, \u0026#34;phone\u0026#34;: \u0026#34;+82-10-1111-2222\u0026#34; }, { \u0026#34;id\u0026#34;: \u0026#34;sales-bot\u0026#34;, \u0026#34;phone\u0026#34;: \u0026#34;+82-10-3333-4444\u0026#34; } ] } } 각 계정별로 독립적인 DM/그룹 정책을 설정할 수 있다.\n인증 정보 저장 WhatsApp 인증 정보는 다음 경로에 저장된다.\n~/.openclaw/credentials/whatsapp/ ├── cs-bot/ │ └── auth_info.json └── sales-bot/ └── auth_info.json 이 디렉토리는 민감한 정보를 포함하므로 적절한 파일 권한을 설정해야 한다.\nchmod 700 ~/.openclaw/credentials/whatsapp/ ","permalink":"https://jungwoo0716.github.io/docs/openclaw/25-whatsapp/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eWhatsApp 채널은 OpenClaw 에이전트를 WhatsApp 메신저에 연결한다. QR 코드 페어링으로 설정하며, DM/그룹 정책, 미디어 처리, 멀티 계정을 지원한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"설치-및-설정\"\u003e설치 및 설정\u003c/h2\u003e\n\u003ch3 id=\"플러그인-설치\"\u003e플러그인 설치\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003eopenclaw onboard\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 또는\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003eopenclaw channels add whatsapp\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch3 id=\"qr-코드-페어링\"\u003eQR 코드 페어링\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003eopenclaw channels login whatsapp\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e터미널에 QR 코드가 표시되면 WhatsApp 모바일 앱의 \u003cstrong\u003e연결된 기기\u003c/strong\u003e 메뉴에서 스캔한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"dm-정책\"\u003eDM 정책\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e정책\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003epairing\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e최초 메시지 시 페어링 승인 필요 (기본값)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eallowlist\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e허용 목록에 있는 번호만 DM 가능\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eopen\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e모든 사용자의 DM 허용\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003edisabled\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eDM 비활성화\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;channels\u0026#34;: {\n    \u0026#34;whatsapp\u0026#34;: {\n      \u0026#34;dmPolicy\u0026#34;: \u0026#34;pairing\u0026#34;,\n      \u0026#34;allowlist\u0026#34;: [\n        \u0026#34;+82-10-1234-5678\u0026#34;,\n        \u0026#34;+82-10-9876-5432\u0026#34;\n      ]\n    }\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"페어링-방식\"\u003e페어링 방식\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e새 사용자가 에이전트에 DM 발송\u003c/li\u003e\n\u003cli\u003e에이전트가 \u0026ldquo;페어링 요청\u0026quot;을 관리자에게 알림\u003c/li\u003e\n\u003cli\u003e관리자가 승인하면 해당 사용자와 대화 시작\u003c/li\u003e\n\u003cli\u003e거부하면 해당 사용자의 메시지 무시\u003c/li\u003e\n\u003c/ol\u003e\n\u003chr\u003e\n\u003ch2 id=\"그룹-정책\"\u003e그룹 정책\u003c/h2\u003e\n\u003cp\u003e그룹 허용 목록으로 에이전트가 참여할 그룹을 제한한다.\u003c/p\u003e","title":"WhatsApp 채널"},{"content":"개요 Telegram 채널은 BotFather를 통해 생성한 봇 토큰으로 연동한다. DM/그룹 정책, 포럼 토픽 격리, 라이브 스트리밍, 웹훅 모드 등을 지원한다.\n봇 생성 Telegram에서 @BotFather에게 DM /newbot 명령 입력 봇 이름과 사용자명 설정 발급된 토큰 복사 설정 { \u0026#34;channels\u0026#34;: { \u0026#34;telegram\u0026#34;: { \u0026#34;enabled\u0026#34;: true, \u0026#34;botToken\u0026#34;: \u0026#34;${TELEGRAM_BOT_TOKEN}\u0026#34;, \u0026#34;dmPolicy\u0026#34;: \u0026#34;pairing\u0026#34; } } } DM 정책 정책 설명 pairing 최초 대화 시 관리자 승인 필요 (기본값) allowlist 허용 목록의 사용자만 DM 가능 open 모든 사용자 DM 허용 disabled DM 비활성화 페어링 승인 새 사용자가 봇에 메시지를 보내면 관리자에게 알림이 전송된다. 관리자가 승인하면 해당 사용자와 대화가 시작된다.\n포럼 토픽 격리 Telegram 포럼(슈퍼그룹)의 토픽은 스레드별로 격리된다.\n각 토픽이 독립된 세션으로 처리 토픽 A의 대화가 토픽 B에 영향을 주지 않음 일반 그룹에서는 전체 그룹이 하나의 세션 라이브 스트리밍 에이전트의 응답을 실시간으로 스트리밍할 수 있다.\n토큰 단위로 점진적 메시지 업데이트 긴 응답도 즉시 사용자에게 표시 시작 네트워크 부하를 고려한 업데이트 간격 자동 조절 네이티브 답장 스레딩 Telegram의 답장(reply) 기능을 활용한 스레드 관리를 지원한다.\n에이전트 응답이 원본 메시지에 대한 답장으로 전송 대화 흐름을 시각적으로 추적 가능 미디어 지원 타입 지원 오디오/비디오 노트 지원 스티커 지원 문서/파일 지원 사진/비디오 지원 웹훅 모드 기본 롱 폴링(long polling) 대신 웹훅 모드를 사용할 수 있다.\n{ \u0026#34;channels\u0026#34;: { \u0026#34;telegram\u0026#34;: { \u0026#34;mode\u0026#34;: \u0026#34;webhook\u0026#34;, \u0026#34;webhookUrl\u0026#34;: \u0026#34;https://your-domain.com/telegram/webhook\u0026#34; } } } 웹훅 모드는 서버 환경에서 더 효율적이며 응답 지연이 줄어든다.\n트러블슈팅 프라이버시 모드 봇이 그룹 메시지를 받지 못하는 경우 프라이버시 모드를 확인한다.\nBotFather에서 /mybots → 봇 선택 Bot Settings → Group Privacy Turn off (그룹 메시지 수신 허용) IPv6 이슈 일부 환경에서 Telegram API 연결이 IPv6로 시도되어 실패할 수 있다.\n# IPv4 강제 사용 export TELEGRAM_FORCE_IPV4=true 또는 DNS 설정에서 IPv4를 우선하도록 조정한다.\n","permalink":"https://jungwoo0716.github.io/docs/openclaw/26-telegram/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eTelegram 채널은 BotFather를 통해 생성한 봇 토큰으로 연동한다. DM/그룹 정책, 포럼 토픽 격리, 라이브 스트리밍, 웹훅 모드 등을 지원한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"봇-생성\"\u003e봇 생성\u003c/h2\u003e\n\u003col\u003e\n\u003cli\u003eTelegram에서 \u003ca href=\"https://t.me/BotFather\"\u003e@BotFather\u003c/a\u003e에게 DM\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003e/newbot\u003c/code\u003e 명령 입력\u003c/li\u003e\n\u003cli\u003e봇 이름과 사용자명 설정\u003c/li\u003e\n\u003cli\u003e발급된 토큰 복사\u003c/li\u003e\n\u003c/ol\u003e\n\u003chr\u003e\n\u003ch2 id=\"설정\"\u003e설정\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;channels\u0026#34;: {\n    \u0026#34;telegram\u0026#34;: {\n      \u0026#34;enabled\u0026#34;: true,\n      \u0026#34;botToken\u0026#34;: \u0026#34;${TELEGRAM_BOT_TOKEN}\u0026#34;,\n      \u0026#34;dmPolicy\u0026#34;: \u0026#34;pairing\u0026#34;\n    }\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"dm-정책\"\u003eDM 정책\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e정책\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003epairing\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e최초 대화 시 관리자 승인 필요 (기본값)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eallowlist\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e허용 목록의 사용자만 DM 가능\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eopen\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e모든 사용자 DM 허용\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003edisabled\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eDM 비활성화\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"페어링-승인\"\u003e페어링 승인\u003c/h3\u003e\n\u003cp\u003e새 사용자가 봇에 메시지를 보내면 관리자에게 알림이 전송된다. 관리자가 승인하면 해당 사용자와 대화가 시작된다.\u003c/p\u003e","title":"Telegram 채널"},{"content":"에이전트 런타임과 Paperclip을 통합하는 커스텀 어댑터를 빌드하는 가이드입니다.\n패키지 구조 packages/adapters/\u0026lt;name\u0026gt;/ ├── src/ │ ├── index.ts # 루트 메타데이터 │ ├── server.ts # 실행 로직 │ ├── ui.ts # 트랜스크립트 파싱 │ └── cli.ts # 터미널 포맷팅 구현 단계 단계 1: 루트 메타데이터 src/index.ts에서 어댑터 정보를 내보냅니다: 타입, 라벨, 지원 모델, 설정 문서. 이 파일은 의존성이 없어야 합니다.\n단계 2: 서버 실행 실행 모듈은 컨텍스트를 받아 결과를 반환합니다:\n설정을 안전하게 읽기 환경 빌드 세션 상태 해결 프롬프트 렌더링 프로세스 생성 사용량 메트릭 및 오류 처리를 위한 출력 파싱 단계 3: 환경 테스트 error, warn, info 카테고리를 사용한 구조화된 진단으로 설정을 검증합니다.\n단계 4-5: UI 및 CLI UI 모듈은 트랜스크립트 변환, CLI 모듈은 터미널 포맷팅을 처리합니다.\n단계 6: 등록 어댑터를 서버, UI, CLI 패키지의 3개 레지스트리에 등록해야 합니다.\n스킬 통합 방법 4가지 접근법 (우선순위 순):\n플래그가 있는 임시 디렉토리 글로벌 스킬 디렉토리 직접 프롬프트 주입 기타 보안 고려사항 에이전트 출력을 신뢰하지 않는 것으로 취급 환경 변수를 통한 시크릿 관리 타임아웃 강제 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/26-%EC%BB%A4%EC%8A%A4%ED%85%80%EC%96%B4%EB%8C%91%ED%84%B0%EB%A7%8C%EB%93%A4%EA%B8%B0/","summary":"\u003cp\u003e에이전트 런타임과 Paperclip을 통합하는 커스텀 어댑터를 빌드하는 가이드입니다.\u003c/p\u003e\n\u003ch2 id=\"패키지-구조\"\u003e패키지 구조\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003epackages/adapters/\u0026lt;name\u0026gt;/\n├── src/\n│   ├── index.ts        # 루트 메타데이터\n│   ├── server.ts       # 실행 로직\n│   ├── ui.ts           # 트랜스크립트 파싱\n│   └── cli.ts          # 터미널 포맷팅\n\u003c/code\u003e\u003c/pre\u003e\u003ch2 id=\"구현-단계\"\u003e구현 단계\u003c/h2\u003e\n\u003ch3 id=\"단계-1-루트-메타데이터\"\u003e단계 1: 루트 메타데이터\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003esrc/index.ts\u003c/code\u003e에서 어댑터 정보를 내보냅니다: 타입, 라벨, 지원 모델, 설정 문서. 이 파일은 의존성이 없어야 합니다.\u003c/p\u003e\n\u003ch3 id=\"단계-2-서버-실행\"\u003e단계 2: 서버 실행\u003c/h3\u003e\n\u003cp\u003e실행 모듈은 컨텍스트를 받아 결과를 반환합니다:\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e설정을 안전하게 읽기\u003c/li\u003e\n\u003cli\u003e환경 빌드\u003c/li\u003e\n\u003cli\u003e세션 상태 해결\u003c/li\u003e\n\u003cli\u003e프롬프트 렌더링\u003c/li\u003e\n\u003cli\u003e프로세스 생성\u003c/li\u003e\n\u003cli\u003e사용량 메트릭 및 오류 처리를 위한 출력 파싱\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch3 id=\"단계-3-환경-테스트\"\u003e단계 3: 환경 테스트\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003eerror\u003c/code\u003e, \u003ccode\u003ewarn\u003c/code\u003e, \u003ccode\u003einfo\u003c/code\u003e 카테고리를 사용한 구조화된 진단으로 설정을 검증합니다.\u003c/p\u003e","title":"커스텀 어댑터 만들기"},{"content":"개요 Discord 채널은 봇 자격 증명과 Message Content Intent를 통해 연동한다. DM/길드 정책, Components v2, 스레드 바인딩, 음성 채널 등 Discord 네이티브 기능을 폭넓게 지원한다.\n봇 설정 1. 봇 생성 Discord Developer Portal에서 애플리케이션 생성 Bot 탭에서 봇 추가 Token 복사 2. Message Content Intent 활성화 봇이 메시지 내용을 읽으려면 Privileged Gateway Intents에서 Message Content Intent를 활성화해야 한다.\n3. 설정 { \u0026#34;channels\u0026#34;: { \u0026#34;discord\u0026#34;: { \u0026#34;enabled\u0026#34;: true, \u0026#34;botToken\u0026#34;: \u0026#34;${DISCORD_BOT_TOKEN}\u0026#34;, \u0026#34;dmPolicy\u0026#34;: \u0026#34;pairing\u0026#34; } } } DM/길드 정책 DM 정책 정책 설명 pairing 페어링 승인 필요 (기본값) allowlist 허용 목록 사용자만 open 모든 사용자 허용 disabled DM 비활성화 길드(서버) 정책 에이전트가 참여할 수 있는 서버를 제한한다.\n{ \u0026#34;channels\u0026#34;: { \u0026#34;discord\u0026#34;: { \u0026#34;guildAllowlist\u0026#34;: [\u0026#34;서버ID-1\u0026#34;, \u0026#34;서버ID-2\u0026#34;] } } } Components v2 Discord의 최신 인터랙션 컴포넌트를 지원한다.\n컴포넌트 설명 Buttons 사용자 클릭 가능한 버튼 Select Menus 드롭다운 선택 메뉴 Modals 팝업 입력 폼 에이전트가 인터랙티브한 메시지를 생성하여 사용자 입력을 구조화된 방식으로 받을 수 있다.\n스레드 바인딩 서브 에이전트를 Discord 스레드에 바인딩할 수 있다.\n서브 에이전트 스폰 시 자동으로 스레드 생성 해당 서브 에이전트의 모든 응답이 스레드 내에 전송 메인 채널을 깔끔하게 유지 #general ├── 사용자: \u0026#34;이 데이터 분석해줘\u0026#34; ├── 에이전트: \u0026#34;서브 에이전트가 분석 중입니다\u0026#34; └── 📎 분석 결과 (스레드) ├── 서브 에이전트: \u0026#34;데이터 로딩 중...\u0026#34; ├── 서브 에이전트: \u0026#34;분석 완료. 결과:\u0026#34; └── 서브 에이전트: (분석 결과) PluralKit 지원 PluralKit 프록시 메시지를 인식하고 올바른 사용자로 매핑한다. 복수 자아(plural system) 사용자를 적절히 처리한다.\n음성 채널 에이전트가 Discord 음성 채널에 참여할 수 있다.\n음성 채널 입장/퇴장 음성 메시지 수신 및 처리 파형(waveform) 포함 음성 메시지 전송 실행 승인 (버튼) 셸 명령 실행 승인이 필요할 때 Discord 버튼으로 승인/거부할 수 있다.\n에이전트: \u0026#34;다음 명령을 실행하겠습니다: npm run deploy\u0026#34; [✅ 승인] [❌ 거부] 관리자가 버튼을 클릭하여 즉시 승인 또는 거부할 수 있다.\n라이브 스트림 미리보기 에이전트가 긴 작업을 수행할 때 Discord 메시지를 실시간으로 업데이트하여 진행 상황을 보여준다.\n","permalink":"https://jungwoo0716.github.io/docs/openclaw/27-discord/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eDiscord 채널은 봇 자격 증명과 Message Content Intent를 통해 연동한다. DM/길드 정책, Components v2, 스레드 바인딩, 음성 채널 등 Discord 네이티브 기능을 폭넓게 지원한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"봇-설정\"\u003e봇 설정\u003c/h2\u003e\n\u003ch3 id=\"1-봇-생성\"\u003e1. 봇 생성\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e\u003ca href=\"https://discord.com/developers/applications\"\u003eDiscord Developer Portal\u003c/a\u003e에서 애플리케이션 생성\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eBot\u003c/strong\u003e 탭에서 봇 추가\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eToken\u003c/strong\u003e 복사\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch3 id=\"2-message-content-intent-활성화\"\u003e2. Message Content Intent 활성화\u003c/h3\u003e\n\u003cp\u003e봇이 메시지 내용을 읽으려면 \u003cstrong\u003ePrivileged Gateway Intents\u003c/strong\u003e에서 \u003cstrong\u003eMessage Content Intent\u003c/strong\u003e를 활성화해야 한다.\u003c/p\u003e\n\u003ch3 id=\"3-설정\"\u003e3. 설정\u003c/h3\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;channels\u0026#34;: {\n    \u0026#34;discord\u0026#34;: {\n      \u0026#34;enabled\u0026#34;: true,\n      \u0026#34;botToken\u0026#34;: \u0026#34;${DISCORD_BOT_TOKEN}\u0026#34;,\n      \u0026#34;dmPolicy\u0026#34;: \u0026#34;pairing\u0026#34;\n    }\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"dm길드-정책\"\u003eDM/길드 정책\u003c/h2\u003e\n\u003ch3 id=\"dm-정책\"\u003eDM 정책\u003c/h3\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e정책\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003epairing\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e페어링 승인 필요 (기본값)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eallowlist\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e허용 목록 사용자만\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eopen\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e모든 사용자 허용\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003edisabled\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eDM 비활성화\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"길드서버-정책\"\u003e길드(서버) 정책\u003c/h3\u003e\n\u003cp\u003e에이전트가 참여할 수 있는 서버를 제한한다.\u003c/p\u003e","title":"Discord 채널"},{"content":"Paperclip은 세 가지 배포 모드를 제공합니다.\n로컬 트러스티드 모드 (기본) 로그인 불필요 루프백 전용 호스트 바인딩 개인 개발자가 로컬에서 작업할 때 적합 가장 빠른 시작 경험 인증 + 프라이빗 모드 Better Auth를 통한 로그인 자격증명 필요 팀 협업을 위해 네트워크 인터페이스에서 접근 가능 Tailscale이나 로컬 네트워크 같은 공유 환경에 적합 인증 + 퍼블릭 모드 로그인 인증 강제 명시적 퍼블릭 URL 설정 필요 클라우드 배포를 위한 향상된 보안 프로토콜 모드 선택 가이드 시나리오 권장 모드 처음 탐색 로컬 트러스티드 (기본) 프라이빗 네트워크로 팀 공유 인증 + 프라이빗 클라우드 인프라 배포 인증 + 퍼블릭 설정: pnpm paperclipai onboard 또는 pnpm paperclipai configure --section server\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/27-%EB%B0%B0%ED%8F%AC%EA%B0%9C%EC%9A%94/","summary":"\u003cp\u003ePaperclip은 세 가지 배포 모드를 제공합니다.\u003c/p\u003e\n\u003ch2 id=\"로컬-트러스티드-모드-기본\"\u003e로컬 트러스티드 모드 (기본)\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e로그인 불필요\u003c/li\u003e\n\u003cli\u003e루프백 전용 호스트 바인딩\u003c/li\u003e\n\u003cli\u003e개인 개발자가 로컬에서 작업할 때 적합\u003c/li\u003e\n\u003cli\u003e가장 빠른 시작 경험\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"인증--프라이빗-모드\"\u003e인증 + 프라이빗 모드\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003eBetter Auth를 통한 로그인 자격증명 필요\u003c/li\u003e\n\u003cli\u003e팀 협업을 위해 네트워크 인터페이스에서 접근 가능\u003c/li\u003e\n\u003cli\u003eTailscale이나 로컬 네트워크 같은 공유 환경에 적합\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"인증--퍼블릭-모드\"\u003e인증 + 퍼블릭 모드\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e로그인 인증 강제\u003c/li\u003e\n\u003cli\u003e명시적 퍼블릭 URL 설정 필요\u003c/li\u003e\n\u003cli\u003e클라우드 배포를 위한 향상된 보안 프로토콜\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"모드-선택-가이드\"\u003e모드 선택 가이드\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e시나리오\u003c/th\u003e\n          \u003cth\u003e권장 모드\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e처음 탐색\u003c/td\u003e\n          \u003ctd\u003e로컬 트러스티드 (기본)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e프라이빗 네트워크로 팀 공유\u003c/td\u003e\n          \u003ctd\u003e인증 + 프라이빗\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e클라우드 인프라 배포\u003c/td\u003e\n          \u003ctd\u003e인증 + 퍼블릭\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003cp\u003e설정: \u003ccode\u003epnpm paperclipai onboard\u003c/code\u003e 또는 \u003ccode\u003epnpm paperclipai configure --section server\u003c/code\u003e\u003c/p\u003e","title":"배포 개요"},{"content":"개요 Slack 채널은 Socket Mode(기본) 또는 HTTP Events API를 통해 연동한다. 봇 토큰과 앱 토큰으로 인증하며, 스레딩, Block Kit, 네이티브 명령어 등 Slack 네이티브 기능을 지원한다.\n인증 토큰 토큰 형식 용도 Bot Token xoxb-... 메시지 읽기/쓰기, 채널 관리 App Token xapp-... Socket Mode 연결 Slack 앱 생성 Slack API에서 앱 생성 OAuth \u0026amp; Permissions에서 Bot Token Scopes 설정 Socket Mode 활성화 및 App Token 생성 워크스페이스에 앱 설치 연결 모드 Socket Mode (기본) WebSocket을 통한 실시간 연결. 방화벽 뒤에서도 동작하며 별도의 공개 URL이 필요 없다.\n{ \u0026#34;channels\u0026#34;: { \u0026#34;slack\u0026#34;: { \u0026#34;enabled\u0026#34;: true, \u0026#34;mode\u0026#34;: \u0026#34;socket\u0026#34;, \u0026#34;botToken\u0026#34;: \u0026#34;${SLACK_BOT_TOKEN}\u0026#34;, \u0026#34;appToken\u0026#34;: \u0026#34;${SLACK_APP_TOKEN}\u0026#34; } } } HTTP Events API 공개 URL에 이벤트를 수신하는 방식. 서버 환경에서 더 안정적이다.\n{ \u0026#34;channels\u0026#34;: { \u0026#34;slack\u0026#34;: { \u0026#34;mode\u0026#34;: \u0026#34;http\u0026#34;, \u0026#34;botToken\u0026#34;: \u0026#34;${SLACK_BOT_TOKEN}\u0026#34;, \u0026#34;eventsUrl\u0026#34;: \u0026#34;https://your-domain.com/slack/events\u0026#34; } } } DM 정책 정책 설명 pairing 페어링 승인 필요 allowlist 허용 목록 사용자만 disabled DM 비활성화 Slack에서는 open 정책을 지원하지 않는다. 워크스페이스 내 사용자만 접근 가능하므로 pairing 또는 allowlist를 사용한다.\n스레딩 스레드 스코프 Slack의 스레드(답장) 기능을 세션 범위로 활용한다.\n스레드 내 대화는 별도 컨텍스트로 처리 기본 히스토리 20개 메시지 스레드 외부 메시지와 격리 { \u0026#34;channels\u0026#34;: { \u0026#34;slack\u0026#34;: { \u0026#34;threading\u0026#34;: { \u0026#34;scope\u0026#34;: \u0026#34;thread\u0026#34;, \u0026#34;historySize\u0026#34;: 20 } } } } 네이티브 명령어 Slack 슬래시 명령어 등록. 기본값은 비활성화이다.\n{ \u0026#34;channels\u0026#34;: { \u0026#34;slack\u0026#34;: { \u0026#34;nativeCommands\u0026#34;: true } } } 활성화하면 에이전트 명령어를 Slack 슬래시 명령어로 등록할 수 있다.\nBlock Kit 디렉티브 에이전트가 Slack Block Kit을 사용하여 리치 메시지를 생성할 수 있다.\n{ \u0026#34;blocks\u0026#34;: [ { \u0026#34;type\u0026#34;: \u0026#34;section\u0026#34;, \u0026#34;text\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;mrkdwn\u0026#34;, \u0026#34;text\u0026#34;: \u0026#34;*작업 완료*\\n분석 결과가 준비되었습니다.\u0026#34; } }, { \u0026#34;type\u0026#34;: \u0026#34;actions\u0026#34;, \u0026#34;elements\u0026#34;: [ { \u0026#34;type\u0026#34;: \u0026#34;button\u0026#34;, \u0026#34;text\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;plain_text\u0026#34;, \u0026#34;text\u0026#34;: \u0026#34;결과 보기\u0026#34; }, \u0026#34;action_id\u0026#34;: \u0026#34;view_result\u0026#34; } ] } ] } 트러블슈팅 채널 연결 실패 Error: channel_not_found 봇이 해당 채널에 초대되었는지 확인 /invite @봇이름 명령으로 채널에 봇 추가 DM이 무시되는 경우 DM 정책이 disabled로 설정되어 있지 않은지 확인 pairing 모드에서 승인이 완료되었는지 확인 봇의 im:read, im:write 스코프가 있는지 확인 Socket Mode 연결 이슈 Error: websocket_disconnect App Token(xapp-)이 올바른지 확인 Socket Mode가 Slack 앱 설정에서 활성화되었는지 확인 네트워크 프록시가 WebSocket을 차단하지 않는지 확인 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/28-slack/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eSlack 채널은 Socket Mode(기본) 또는 HTTP Events API를 통해 연동한다. 봇 토큰과 앱 토큰으로 인증하며, 스레딩, Block Kit, 네이티브 명령어 등 Slack 네이티브 기능을 지원한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"인증-토큰\"\u003e인증 토큰\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e토큰\u003c/th\u003e\n          \u003cth\u003e형식\u003c/th\u003e\n          \u003cth\u003e용도\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eBot Token\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003exoxb-...\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e메시지 읽기/쓰기, 채널 관리\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003cstrong\u003eApp Token\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003exapp-...\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eSocket Mode 연결\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"slack-앱-생성\"\u003eSlack 앱 생성\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e\u003ca href=\"https://api.slack.com/apps\"\u003eSlack API\u003c/a\u003e에서 앱 생성\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eOAuth \u0026amp; Permissions\u003c/strong\u003e에서 Bot Token Scopes 설정\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eSocket Mode\u003c/strong\u003e 활성화 및 App Token 생성\u003c/li\u003e\n\u003cli\u003e워크스페이스에 앱 설치\u003c/li\u003e\n\u003c/ol\u003e\n\u003chr\u003e\n\u003ch2 id=\"연결-모드\"\u003e연결 모드\u003c/h2\u003e\n\u003ch3 id=\"socket-mode-기본\"\u003eSocket Mode (기본)\u003c/h3\u003e\n\u003cp\u003eWebSocket을 통한 실시간 연결. 방화벽 뒤에서도 동작하며 별도의 공개 URL이 필요 없다.\u003c/p\u003e","title":"Slack 채널"},{"content":"로컬 트러스티드 모드 (기본) 솔로 운영자를 위한 표준 설정:\nlocalhost에만 바인딩 인증 불필요 로컬 보드 사용자 자동 생성 pnpm paperclipai onboard로 활성화 인증 모드 Better Auth를 통한 사용자 로그인 필수. 두 가지 하위 설정:\n프라이빗 네트워크 Tailscale, VPN, LAN 같은 제한된 네트워크용 자동 베이스 URL 감지 프라이빗 호스트 신뢰 검증 필요 커스텀 Tailscale 호스트명: pnpm paperclipai allowed-hostname 퍼블릭 인터넷 인터넷 접근 가능한 배포용 명시적 퍼블릭 URL 필요 doctor 진단 체크 시 향상된 보안 검증 보드 소유권 이전 로컬에서 인증 모드로 마이그레이션하면 일회성 클레임 메커니즘이 트리거됩니다:\n시작 시 인증 토큰이 포함된 특별 URL 표시 로그인한 사용자가 인스턴스 관리자 권한을 획득 원래 로컬 관리자 계정은 강등 설정 관리 pnpm paperclipai configure --section server 또는 런타임 환경 변수: PAPERCLIP_DEPLOYMENT_MODE\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/28-%EB%B0%B0%ED%8F%AC%EB%AA%A8%EB%93%9C/","summary":"\u003ch2 id=\"로컬-트러스티드-모드-기본\"\u003e로컬 트러스티드 모드 (기본)\u003c/h2\u003e\n\u003cp\u003e솔로 운영자를 위한 표준 설정:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003elocalhost에만 바인딩\u003c/li\u003e\n\u003cli\u003e인증 불필요\u003c/li\u003e\n\u003cli\u003e로컬 보드 사용자 자동 생성\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003epnpm paperclipai onboard\u003c/code\u003e로 활성화\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"인증-모드\"\u003e인증 모드\u003c/h2\u003e\n\u003cp\u003eBetter Auth를 통한 사용자 로그인 필수. 두 가지 하위 설정:\u003c/p\u003e\n\u003ch3 id=\"프라이빗-네트워크\"\u003e프라이빗 네트워크\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003eTailscale, VPN, LAN 같은 제한된 네트워크용\u003c/li\u003e\n\u003cli\u003e자동 베이스 URL 감지\u003c/li\u003e\n\u003cli\u003e프라이빗 호스트 신뢰 검증 필요\u003c/li\u003e\n\u003cli\u003e커스텀 Tailscale 호스트명: \u003ccode\u003epnpm paperclipai allowed-hostname\u003c/code\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3 id=\"퍼블릭-인터넷\"\u003e퍼블릭 인터넷\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e인터넷 접근 가능한 배포용\u003c/li\u003e\n\u003cli\u003e명시적 퍼블릭 URL 필요\u003c/li\u003e\n\u003cli\u003edoctor 진단 체크 시 향상된 보안 검증\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"보드-소유권-이전\"\u003e보드 소유권 이전\u003c/h2\u003e\n\u003cp\u003e로컬에서 인증 모드로 마이그레이션하면 일회성 클레임 메커니즘이 트리거됩니다:\u003c/p\u003e","title":"배포 모드"},{"content":"Paperclip은 세 가지 데이터베이스 배포 방식을 지원합니다.\n임베디드 PostgreSQL (기본) 설정 제로. DATABASE_URL을 설정하지 않으면 서버가 자동으로 임베디드 PostgreSQL 인스턴스를 시작합니다.\n데이터 경로: ~/.paperclip/instances/default/db/ 첫 시작 시 마이그레이션 자동 실행 로컬 Docker PostgreSQL docker compose up -d PostgreSQL 17이 localhost:5432에서 실행됩니다. DATABASE_URL 환경 변수를 설정하고 Drizzle Kit으로 스키마 마이그레이션을 실행합니다.\n호스팅 PostgreSQL (Supabase 등) 프로덕션 환경에서는 Supabase 같은 외부 데이터베이스 프로바이더 사용:\n프로바이더에서 연결 문자열 획득 환경 변수로 설정 설정 결정 방식 DATABASE_URL 모드 미설정 임베디드 모드 localhost 주소 Docker Supabase 도메인 호스팅 모드 풀링된 연결의 경우 Drizzle 클라이언트 설정에서 prepared statements를 비활성화해야 합니다.\n모든 배포 옵션에서 기본 스키마는 동일합니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/29-%EB%8D%B0%EC%9D%B4%ED%84%B0%EB%B2%A0%EC%9D%B4%EC%8A%A4/","summary":"\u003cp\u003ePaperclip은 세 가지 데이터베이스 배포 방식을 지원합니다.\u003c/p\u003e\n\u003ch2 id=\"임베디드-postgresql-기본\"\u003e임베디드 PostgreSQL (기본)\u003c/h2\u003e\n\u003cp\u003e설정 제로. \u003ccode\u003eDATABASE_URL\u003c/code\u003e을 설정하지 않으면 서버가 자동으로 임베디드 PostgreSQL 인스턴스를 시작합니다.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e데이터 경로: \u003ccode\u003e~/.paperclip/instances/default/db/\u003c/code\u003e\u003c/li\u003e\n\u003cli\u003e첫 시작 시 마이그레이션 자동 실행\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"로컬-docker-postgresql\"\u003e로컬 Docker PostgreSQL\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003edocker compose up -d\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003ePostgreSQL 17이 localhost:5432에서 실행됩니다. \u003ccode\u003eDATABASE_URL\u003c/code\u003e 환경 변수를 설정하고 Drizzle Kit으로 스키마 마이그레이션을 실행합니다.\u003c/p\u003e\n\u003ch2 id=\"호스팅-postgresql-supabase-등\"\u003e호스팅 PostgreSQL (Supabase 등)\u003c/h2\u003e\n\u003cp\u003e프로덕션 환경에서는 Supabase 같은 외부 데이터베이스 프로바이더 사용:\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e프로바이더에서 연결 문자열 획득\u003c/li\u003e\n\u003cli\u003e환경 변수로 설정\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch2 id=\"설정-결정-방식\"\u003e설정 결정 방식\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003eDATABASE_URL\u003c/th\u003e\n          \u003cth\u003e모드\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e미설정\u003c/td\u003e\n          \u003ctd\u003e임베디드 모드\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003elocalhost 주소\u003c/td\u003e\n          \u003ctd\u003eDocker\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eSupabase 도메인\u003c/td\u003e\n          \u003ctd\u003e호스팅 모드\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003cblockquote\u003e\n\u003cp\u003e풀링된 연결의 경우 Drizzle 클라이언트 설정에서 prepared statements를 비활성화해야 합니다.\u003c/p\u003e","title":"데이터베이스"},{"content":"개요 샌드박싱은 에이전트의 도구 실행을 격리된 백엔드에서 수행하여 호스트 시스템을 보호한다. Docker, SSH, OpenShell 백엔드를 지원하며, 도구별로 샌드박스 적용 여부가 다르다.\n샌드박스 대상 도구 샌드박스 적용 샌드박스 미적용 exec (셸 실행) Gateway 도구 read (파일 읽기) 상위 권한 작업 write (파일 쓰기) edit (파일 편집) process (프로세스 관리) browser (브라우저) 샌드박스 모드 모드 설명 off 샌드박싱 비활성화. 모든 도구가 호스트에서 직접 실행 non-main 서브 에이전트만 샌드박싱 (기본값) all 주 에이전트 포함 모든 에이전트 샌드박싱 { \u0026#34;sandbox\u0026#34;: { \u0026#34;mode\u0026#34;: \u0026#34;all\u0026#34; } } 샌드박스 스코프 스코프 설명 agent 에이전트별 독립 샌드박스 (기본값) session 세션별 독립 샌드박스 shared 모든 에이전트가 하나의 샌드박스 공유 백엔드 Docker (로컬) 로컬 Docker 컨테이너를 사용한 격리.\n{ \u0026#34;sandbox\u0026#34;: { \u0026#34;backend\u0026#34;: \u0026#34;docker\u0026#34;, \u0026#34;docker\u0026#34;: { \u0026#34;image\u0026#34;: \u0026#34;openclaw/sandbox:latest\u0026#34;, \u0026#34;network\u0026#34;: false, \u0026#34;memory\u0026#34;: \u0026#34;512m\u0026#34;, \u0026#34;cpus\u0026#34;: 1 } } } 기본적으로 네트워크가 비활성화되어 있다. 에이전트가 외부 네트워크에 접근해야 하면 명시적으로 활성화해야 한다.\nSSH (원격) 원격 서버에 SSH로 연결하여 격리 실행.\n{ \u0026#34;sandbox\u0026#34;: { \u0026#34;backend\u0026#34;: \u0026#34;ssh\u0026#34;, \u0026#34;ssh\u0026#34;: { \u0026#34;host\u0026#34;: \u0026#34;sandbox.example.com\u0026#34;, \u0026#34;user\u0026#34;: \u0026#34;openclaw\u0026#34;, \u0026#34;keyPath\u0026#34;: \u0026#34;~/.ssh/sandbox_key\u0026#34; } } } OpenShell (매니지드) OpenClaw에서 관리하는 클라우드 샌드박스 환경.\n{ \u0026#34;sandbox\u0026#34;: { \u0026#34;backend\u0026#34;: \u0026#34;openshell\u0026#34; } } 별도의 인프라 관리 없이 즉시 사용 가능하다.\n워크스페이스 접근 샌드박스 내에서 에이전트 워크스페이스에 대한 접근 수준을 설정한다.\n모드 설명 none 워크스페이스 접근 불가 ro 읽기 전용 접근 rw 읽기/쓰기 접근 { \u0026#34;sandbox\u0026#34;: { \u0026#34;workspaceAccess\u0026#34;: \u0026#34;ro\u0026#34; } } Docker 보안 설정 네트워크 격리 기본적으로 Docker 샌드박스는 네트워크 비활성화 상태이다. 에이전트가 웹 검색이나 API 호출을 해야 하는 경우에만 활성화한다.\n{ \u0026#34;sandbox\u0026#34;: { \u0026#34;docker\u0026#34;: { \u0026#34;network\u0026#34;: true, \u0026#34;allowedHosts\u0026#34;: [\u0026#34;api.example.com\u0026#34;] } } } 위험한 바인드 차단 다음 호스트 경로의 바인드 마운트가 자동으로 차단된다.\n/ (루트) /etc /var/run/docker.sock /proc, /sys 홈 디렉토리의 민감 파일 (~/.ssh, ~/.gnupg 등) 샌드박스 실행 흐름 [에이전트 도구 호출] │ 샌드박스 대상 확인 ┌─────┴─────┐ │ │ 대상 미대상 │ │ 모드 확인 호스트 직접 실행 │ 백엔드 선택 │ ┌─┴──┬───────┐ │ │ │ Docker SSH OpenShell │ │ │ 격리 실행 격리 실행 │ │ │ 결과 반환 결과 반환 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/29-%EC%83%8C%EB%93%9C%EB%B0%95%EC%8B%B1/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e샌드박싱은 에이전트의 도구 실행을 \u003cstrong\u003e격리된 백엔드\u003c/strong\u003e에서 수행하여 호스트 시스템을 보호한다. Docker, SSH, OpenShell 백엔드를 지원하며, 도구별로 샌드박스 적용 여부가 다르다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"샌드박스-대상-도구\"\u003e샌드박스 대상 도구\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e샌드박스 적용\u003c/th\u003e\n          \u003cth\u003e샌드박스 미적용\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eexec\u003c/code\u003e (셸 실행)\u003c/td\u003e\n          \u003ctd\u003eGateway 도구\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eread\u003c/code\u003e (파일 읽기)\u003c/td\u003e\n          \u003ctd\u003e상위 권한 작업\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ewrite\u003c/code\u003e (파일 쓰기)\u003c/td\u003e\n          \u003ctd\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eedit\u003c/code\u003e (파일 편집)\u003c/td\u003e\n          \u003ctd\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eprocess\u003c/code\u003e (프로세스 관리)\u003c/td\u003e\n          \u003ctd\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ebrowser\u003c/code\u003e (브라우저)\u003c/td\u003e\n          \u003ctd\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003chr\u003e\n\u003ch2 id=\"샌드박스-모드\"\u003e샌드박스 모드\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e모드\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eoff\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e샌드박싱 비활성화. 모든 도구가 호스트에서 직접 실행\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003enon-main\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e서브 에이전트만 샌드박싱 (기본값)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eall\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e주 에이전트 포함 모든 에이전트 샌드박싱\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;sandbox\u0026#34;: {\n    \u0026#34;mode\u0026#34;: \u0026#34;all\u0026#34;\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003chr\u003e\n\u003ch2 id=\"샌드박스-스코프\"\u003e샌드박스 스코프\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e스코프\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eagent\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트별 독립 샌드박스 (기본값)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003esession\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e세션별 독립 샌드박스\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eshared\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e모든 에이전트가 하나의 샌드박스 공유\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003chr\u003e\n\u003ch2 id=\"백엔드\"\u003e백엔드\u003c/h2\u003e\n\u003ch3 id=\"docker-로컬\"\u003eDocker (로컬)\u003c/h3\u003e\n\u003cp\u003e로컬 Docker 컨테이너를 사용한 격리.\u003c/p\u003e","title":"샌드박싱"},{"content":"빠른 시작 (Compose 방식, 권장) docker compose -f docker-compose.quickstart.yml up --build http://localhost:3100 에서 접근 가능합니다.\n환경 변수로 커스터마이징:\nPAPERCLIP_PORT — 호스트 포트 PAPERCLIP_DATA_DIR — 데이터 디렉토리 수동 빌드 방식 docker build -t paperclip . docker run -p 3100:3100 -v ~/.paperclip:/root/.paperclip paperclip 데이터 저장 바인드 마운트 디렉토리에 영구 저장되는 항목:\n임베디드 PostgreSQL 데이터베이스 사용자 업로드 에셋 로컬 시크릿 에이전트 워크스페이스 정보 사전 설치된 도구 Docker 이미지에 포함:\nClaude Code CLI OpenAI Codex CLI API 키를 전달하여 컨테이너 내 로컬 어댑터 실행 활성화:\ndocker run -e OPENAI_API_KEY=... -e ANTHROPIC_API_KEY=... ... API 키 없이도 애플리케이션은 정상 작동하지만, 어댑터 검사에서 누락 표시됩니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/30-docker/","summary":"\u003ch2 id=\"빠른-시작-compose-방식-권장\"\u003e빠른 시작 (Compose 방식, 권장)\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003edocker compose -f docker-compose.quickstart.yml up --build\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003ehttp://localhost:3100 에서 접근 가능합니다.\u003c/p\u003e\n\u003cp\u003e환경 변수로 커스터마이징:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ccode\u003ePAPERCLIP_PORT\u003c/code\u003e — 호스트 포트\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003ePAPERCLIP_DATA_DIR\u003c/code\u003e — 데이터 디렉토리\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"수동-빌드-방식\"\u003e수동 빌드 방식\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003edocker build -t paperclip .\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003edocker run -p 3100:3100 -v ~/.paperclip:/root/.paperclip paperclip\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"데이터-저장\"\u003e데이터 저장\u003c/h2\u003e\n\u003cp\u003e바인드 마운트 디렉토리에 영구 저장되는 항목:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e임베디드 PostgreSQL 데이터베이스\u003c/li\u003e\n\u003cli\u003e사용자 업로드 에셋\u003c/li\u003e\n\u003cli\u003e로컬 시크릿\u003c/li\u003e\n\u003cli\u003e에이전트 워크스페이스 정보\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"사전-설치된-도구\"\u003e사전 설치된 도구\u003c/h2\u003e\n\u003cp\u003eDocker 이미지에 포함:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003eClaude Code CLI\u003c/strong\u003e\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eOpenAI Codex CLI\u003c/strong\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eAPI 키를 전달하여 컨테이너 내 로컬 어댑터 실행 활성화:\u003c/p\u003e","title":"Docker"},{"content":"개요 OpenClaw 게이트웨이는 세 가지 소스에서 시크릿(API 키, 인증 정보 등)을 로드한다. 활성화 시점에 즉시 해석(eager resolution)하고, 리로드 시 원자적 교체(atomic swap)를 수행하여 안전한 시크릿 관리를 제공한다.\n시크릿 소스 1. 환경 변수 (Environment Variables) 가장 일반적인 방식. .env 파일 또는 시스템 환경 변수에서 로드한다.\n{ \u0026#34;secrets\u0026#34;: { \u0026#34;OPENAI_API_KEY\u0026#34;: \u0026#34;${OPENAI_API_KEY}\u0026#34;, \u0026#34;TELEGRAM_TOKEN\u0026#34;: \u0026#34;${TELEGRAM_BOT_TOKEN}\u0026#34; } } 2. 파일 JSON 포인터 (File Pointers) JSON/YAML 파일 내 특정 경로의 값을 시크릿으로 사용한다.\n{ \u0026#34;secrets\u0026#34;: { \u0026#34;DB_PASSWORD\u0026#34;: { \u0026#34;file\u0026#34;: \u0026#34;/etc/openclaw/secrets.json\u0026#34;, \u0026#34;pointer\u0026#34;: \u0026#34;/database/password\u0026#34; } } } 3. 실행 명령 (Executable Commands) 외부 시크릿 매니저(Vault, AWS Secrets Manager 등)에서 값을 조회하는 명령을 실행한다.\n{ \u0026#34;secrets\u0026#34;: { \u0026#34;VAULT_TOKEN\u0026#34;: { \u0026#34;exec\u0026#34;: \u0026#34;vault kv get -field=token secret/openclaw\u0026#34; } } } 즉시 해석 (Eager Resolution) 시크릿은 게이트웨이 활성화 시점에 즉시 해석된다. 런타임 중 지연 로딩(lazy loading)하지 않는다.\n게이트웨이 시작 │ ▼ 모든 시크릿 소스 해석 │ ▼ 런타임 스냅샷 생성 │ ▼ 에이전트가 스냅샷에서 시크릿 참조 원자적 교체 (Atomic Swap) 설정 리로드 시 새로운 시크릿 세트를 구성한 후, 기존 세트와 원자적으로 교체한다.\n리로드 중에도 기존 시크릿이 유효 새 시크릿 해석 완료 후 한 번에 전환 부분 업데이트 없음 (all-or-nothing) 활성 표면 필터링 (Active-Surface Filtering) 비활성화된 채널의 시크릿은 로드하지 않는다.\n{ \u0026#34;channels\u0026#34;: { \u0026#34;telegram\u0026#34;: { \u0026#34;enabled\u0026#34;: false }, \u0026#34;discord\u0026#34;: { \u0026#34;enabled\u0026#34;: true } } } 위 설정에서 Telegram 관련 시크릿(TELEGRAM_BOT_TOKEN 등)은 해석되지 않는다. 불필요한 시크릿 노출을 방지하고 시작 시간을 단축한다.\n런타임 스냅샷 해석된 시크릿은 런타임 스냅샷으로 메모리에 보관된다. 에이전트의 핫 패스(hot-path)에서 빠르게 접근할 수 있다.\n파일 시스템이나 외부 서비스 재조회 없음 메모리 내 읽기 전용 접근 프로세스 종료 시 메모리에서 제거 관리 워크플로우 시크릿 변경은 감사 → 설정 → 적용 3단계로 진행한다.\n1. 감사 (Audit) 현재 시크릿 상태를 확인한다. 값은 마스킹되어 표시된다.\nopenclaw secrets list Name | Source | Status ------------------|---------|-------- OPENAI_API_KEY | env | active TELEGRAM_TOKEN | env | active DB_PASSWORD | file | active VAULT_TOKEN | exec | error 2. 설정 (Configure) 시크릿을 추가하거나 수정한다.\nopenclaw configure --section secrets 3. 적용 (Apply) 변경사항을 게이트웨이에 적용한다.\nopenclaw reload 원자적 교체가 수행되어 새로운 시크릿이 즉시 활성화된다.\n안전 정책 단방향 안전 (One-Way Safety) 시크릿 변경은 항상 전진(forward-only)한다. 롤백 백업을 생성하지 않는다.\n이전 시크릿 값은 메모리에서 즉시 제거 파일 시스템에 이전 값을 저장하지 않음 롤백이 필요하면 원본 소스(환경 변수, Vault 등)에서 복원 이 정책은 시크릿이 불필요하게 디스크에 남아 노출되는 위험을 방지한다.\n","permalink":"https://jungwoo0716.github.io/docs/openclaw/30-%EC%8B%9C%ED%81%AC%EB%A6%BF%EA%B4%80%EB%A6%AC/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003eOpenClaw 게이트웨이는 세 가지 소스에서 시크릿(API 키, 인증 정보 등)을 로드한다. 활성화 시점에 즉시 해석(eager resolution)하고, 리로드 시 원자적 교체(atomic swap)를 수행하여 안전한 시크릿 관리를 제공한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"시크릿-소스\"\u003e시크릿 소스\u003c/h2\u003e\n\u003ch3 id=\"1-환경-변수-environment-variables\"\u003e1. 환경 변수 (Environment Variables)\u003c/h3\u003e\n\u003cp\u003e가장 일반적인 방식. \u003ccode\u003e.env\u003c/code\u003e 파일 또는 시스템 환경 변수에서 로드한다.\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;secrets\u0026#34;: {\n    \u0026#34;OPENAI_API_KEY\u0026#34;: \u0026#34;${OPENAI_API_KEY}\u0026#34;,\n    \u0026#34;TELEGRAM_TOKEN\u0026#34;: \u0026#34;${TELEGRAM_BOT_TOKEN}\u0026#34;\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"2-파일-json-포인터-file-pointers\"\u003e2. 파일 JSON 포인터 (File Pointers)\u003c/h3\u003e\n\u003cp\u003eJSON/YAML 파일 내 특정 경로의 값을 시크릿으로 사용한다.\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;secrets\u0026#34;: {\n    \u0026#34;DB_PASSWORD\u0026#34;: {\n      \u0026#34;file\u0026#34;: \u0026#34;/etc/openclaw/secrets.json\u0026#34;,\n      \u0026#34;pointer\u0026#34;: \u0026#34;/database/password\u0026#34;\n    }\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"3-실행-명령-executable-commands\"\u003e3. 실행 명령 (Executable Commands)\u003c/h3\u003e\n\u003cp\u003e외부 시크릿 매니저(Vault, AWS Secrets Manager 등)에서 값을 조회하는 명령을 실행한다.\u003c/p\u003e","title":"시크릿 관리"},{"content":"개요 크론 잡은 게이트웨이의 내장 스케줄러로 에이전트 작업을 예약 실행한다. 일회성, 반복, cron 표현식을 지원하며, ~/.openclaw/cron/jobs.json에 영구 저장된다.\n스케줄 타입 at (일회성) 특정 시각에 한 번만 실행한다.\n{ \u0026#34;schedule\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;at\u0026#34;, \u0026#34;time\u0026#34;: \u0026#34;2026-04-01T09:00:00+09:00\u0026#34; } } every (간격) 일정 간격으로 반복 실행한다.\n{ \u0026#34;schedule\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;every\u0026#34;, \u0026#34;interval\u0026#34;: \u0026#34;1h\u0026#34; } } 지원 단위: m (분), h (시간), d (일)\ncron (표현식) 5필드 또는 6필드 cron 표현식으로 정밀한 스케줄을 설정한다.\n{ \u0026#34;schedule\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;cron\u0026#34;, \u0026#34;expression\u0026#34;: \u0026#34;0 9 * * 1-5\u0026#34; } } 필드 범위 설명 분 0-59 시 0-23 일 1-31 월 1-12 요일 0-6 0=일요일 초 (6필드) 0-59 선택 세션 모드 크론 잡이 실행될 때 사용하는 세션을 지정한다.\n모드 설명 main 에이전트의 메인 세션에서 실행 isolated 매 실행마다 새로운 격리 세션 생성 (기본값) custom 지정한 세션 ID에서 실행 { \u0026#34;cron\u0026#34;: { \u0026#34;sessionMode\u0026#34;: \u0026#34;isolated\u0026#34; } } 전달 방식 (Delivery) 크론 잡 결과를 어디에 전달할지 설정한다.\n방식 설명 announce 지정 채널에 결과 메시지 전송 webhook 외부 URL에 결과 POST none 결과 전달 없음 (로그만 기록) { \u0026#34;cron\u0026#34;: { \u0026#34;delivery\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;announce\u0026#34;, \u0026#34;channel\u0026#34;: \u0026#34;telegram\u0026#34;, \u0026#34;target\u0026#34;: \u0026#34;group-daily-report\u0026#34; } } } 재시도 정책 일회성 (at) 실패 시 최대 3회 재시도한다.\n실행 → 실패 → 재시도 1 → 실패 → 재시도 2 → 실패 → 재시도 3 → 포기 반복 (every, cron) 실패 시 **지수 백오프(exponential backoff)**로 재시도한다.\n실패 → 1분 대기 → 재시도 → 2분 대기 → 재시도 → 4분 대기 → 재시도 → 다음 정규 스케줄에서 재개 저장소 크론 잡 설정은 다음 파일에 영구 저장된다.\n~/.openclaw/cron/jobs.json [ { \u0026#34;id\u0026#34;: \u0026#34;daily-report\u0026#34;, \u0026#34;agent\u0026#34;: \u0026#34;my-agent\u0026#34;, \u0026#34;task\u0026#34;: \u0026#34;일일 보고서를 생성하고 #report 채널에 전송해줘\u0026#34;, \u0026#34;schedule\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;cron\u0026#34;, \u0026#34;expression\u0026#34;: \u0026#34;0 9 * * 1-5\u0026#34; }, \u0026#34;sessionMode\u0026#34;: \u0026#34;isolated\u0026#34;, \u0026#34;delivery\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;announce\u0026#34;, \u0026#34;channel\u0026#34;: \u0026#34;slack\u0026#34;, \u0026#34;target\u0026#34;: \u0026#34;#report\u0026#34; }, \u0026#34;enabled\u0026#34;: true } ] CLI 명령어 크론 잡 추가 openclaw cron add \\ --name \u0026#34;daily-report\u0026#34; \\ --schedule \u0026#34;0 9 * * 1-5\u0026#34; \\ --task \u0026#34;일일 보고서 생성\u0026#34; \\ --delivery announce --channel slack --target \u0026#34;#report\u0026#34; 크론 잡 목록 openclaw cron list ID | Schedule | Next Run | Status --------------|----------------|--------------------|-------- daily-report | 0 9 * * 1-5 | 2026-04-02 09:00 | active weekly-summary| 0 10 * * 1 | 2026-04-07 10:00 | active 크론 잡 수동 실행 openclaw cron run daily-report 스케줄을 무시하고 즉시 실행한다. 테스트 및 디버깅에 유용하다.\n크론 잡 비활성화/삭제 openclaw cron disable daily-report openclaw cron remove daily-report ","permalink":"https://jungwoo0716.github.io/docs/openclaw/31-%ED%81%AC%EB%A1%A0%EC%9E%A1/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e크론 잡은 게이트웨이의 내장 스케줄러로 에이전트 작업을 예약 실행한다. 일회성, 반복, cron 표현식을 지원하며, \u003ccode\u003e~/.openclaw/cron/jobs.json\u003c/code\u003e에 영구 저장된다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"스케줄-타입\"\u003e스케줄 타입\u003c/h2\u003e\n\u003ch3 id=\"at-일회성\"\u003eat (일회성)\u003c/h3\u003e\n\u003cp\u003e특정 시각에 한 번만 실행한다.\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;schedule\u0026#34;: {\n    \u0026#34;type\u0026#34;: \u0026#34;at\u0026#34;,\n    \u0026#34;time\u0026#34;: \u0026#34;2026-04-01T09:00:00+09:00\u0026#34;\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"every-간격\"\u003eevery (간격)\u003c/h3\u003e\n\u003cp\u003e일정 간격으로 반복 실행한다.\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;schedule\u0026#34;: {\n    \u0026#34;type\u0026#34;: \u0026#34;every\u0026#34;,\n    \u0026#34;interval\u0026#34;: \u0026#34;1h\u0026#34;\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e지원 단위: \u003ccode\u003em\u003c/code\u003e (분), \u003ccode\u003eh\u003c/code\u003e (시간), \u003ccode\u003ed\u003c/code\u003e (일)\u003c/p\u003e\n\u003ch3 id=\"cron-표현식\"\u003ecron (표현식)\u003c/h3\u003e\n\u003cp\u003e5필드 또는 6필드 cron 표현식으로 정밀한 스케줄을 설정한다.\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode class=\"language-json5\" data-lang=\"json5\"\u003e{\n  \u0026#34;schedule\u0026#34;: {\n    \u0026#34;type\u0026#34;: \u0026#34;cron\u0026#34;,\n    \u0026#34;expression\u0026#34;: \u0026#34;0 9 * * 1-5\u0026#34;\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e필드\u003c/th\u003e\n          \u003cth\u003e범위\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e분\u003c/td\u003e\n          \u003ctd\u003e0-59\u003c/td\u003e\n          \u003ctd\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e시\u003c/td\u003e\n          \u003ctd\u003e0-23\u003c/td\u003e\n          \u003ctd\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e일\u003c/td\u003e\n          \u003ctd\u003e1-31\u003c/td\u003e\n          \u003ctd\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e월\u003c/td\u003e\n          \u003ctd\u003e1-12\u003c/td\u003e\n          \u003ctd\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e요일\u003c/td\u003e\n          \u003ctd\u003e0-6\u003c/td\u003e\n          \u003ctd\u003e0=일요일\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e초 (6필드)\u003c/td\u003e\n          \u003ctd\u003e0-59\u003c/td\u003e\n          \u003ctd\u003e선택\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003chr\u003e\n\u003ch2 id=\"세션-모드\"\u003e세션 모드\u003c/h2\u003e\n\u003cp\u003e크론 잡이 실행될 때 사용하는 세션을 지정한다.\u003c/p\u003e","title":"크론 잡"},{"content":"Paperclip이 사용하는 모든 환경 변수입니다.\n서버 설정 변수 기본값 설명 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 프로바이더 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/31-%ED%99%98%EA%B2%BD%EB%B3%80%EC%88%98/","summary":"\u003cp\u003ePaperclip이 사용하는 모든 환경 변수입니다.\u003c/p\u003e\n\u003ch2 id=\"서버-설정\"\u003e서버 설정\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e변수\u003c/th\u003e\n          \u003cth\u003e기본값\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePORT\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e3100\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e서버 포트\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eHOST\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e127.0.0.1\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e바인딩 호스트\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eDATABASE_URL\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e(임베디드)\u003c/td\u003e\n          \u003ctd\u003ePostgreSQL 연결 문자열\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_HOME\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e~/.paperclip\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e데이터 디렉토리\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_INSTANCE_ID\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003edefault\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e인스턴스 ID (다중 로컬 인스턴스용)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_DEPLOYMENT_MODE\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003elocal_trusted\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e런타임 배포 모드\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"시크릿-관리\"\u003e시크릿 관리\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e변수\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_SECRETS_MASTER_KEY\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e32바이트 암호화 키 (base64, hex, raw 형식)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_SECRETS_MASTER_KEY_FILE\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e키 파일 경로\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_SECRETS_STRICT_MODE\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e민감한 환경 변수에 시크릿 참조 강제\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"에이전트-런타임-변수-자동-주입\"\u003e에이전트 런타임 변수 (자동 주입)\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e변수\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_AGENT_ID\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 ID\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_COMPANY_ID\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e회사 ID\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_API_URL\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eAPI 엔드포인트\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_API_KEY\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e인증 토큰 (단기 JWT)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_RUN_ID\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e실행 ID\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_TASK_ID\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e태스크 ID (컨텍스트에 따라)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_WAKE_REASON\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e깨어난 이유\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_APPROVAL_ID\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e승인 ID (승인 해결 시)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_APPROVAL_STATUS\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e승인 상태\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"llm-프로바이더-인증\"\u003eLLM 프로바이더 인증\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e변수\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eANTHROPIC_API_KEY\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eClaude 통합\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eOPENAI_API_KEY\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eOpenAI 프로바이더\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e","title":"환경 변수"},{"content":"Paperclip은 민감한 환경 변수를 보호하기 위해 로컬 암호화를 사용합니다. API 키, 토큰 등 민감한 값은 암호화된 시크릿 참조로 저장됩니다.\n키 저장 위치 마스터 암호화 키: ~/.paperclip/instances/default/secrets/master.key\n설정 시 자동 생성 키는 머신을 떠나지 않습니다 설정 방법 # 온보딩으로 설정 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 패턴과 일치하는 환경 변수는 반드시 평문 대신 암호화된 참조를 사용해야 합니다.\n마이그레이션 도구 기존 인라인 시크릿을 암호화된 시크릿 참조로 변환:\n# 드라이런 pnpm secrets:migrate-inline-env --dry-run # 적용 pnpm secrets:migrate-inline-env ","permalink":"https://jungwoo0716.github.io/docs/paperclip/32-%EC%8B%9C%ED%81%AC%EB%A6%BF%EA%B4%80%EB%A6%AC/","summary":"\u003cp\u003ePaperclip은 민감한 환경 변수를 보호하기 위해 로컬 암호화를 사용합니다. API 키, 토큰 등 민감한 값은 \u003cstrong\u003e암호화된 시크릿 참조\u003c/strong\u003e로 저장됩니다.\u003c/p\u003e\n\u003ch2 id=\"키-저장-위치\"\u003e키 저장 위치\u003c/h2\u003e\n\u003cp\u003e마스터 암호화 키: \u003ccode\u003e~/.paperclip/instances/default/secrets/master.key\u003c/code\u003e\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e설정 시 자동 생성\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e키는 머신을 떠나지 않습니다\u003c/strong\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"설정-방법\"\u003e설정 방법\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 온보딩으로 설정\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai onboard\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 시크릿 섹션 설정\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai configure --section secrets\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 설정 검증\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai doctor\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"환경-변수\"\u003e환경 변수\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e변수\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_SECRETS_MASTER_KEY\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003ebase64, hex 또는 raw 형식의 암호화 키\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_SECRETS_MASTER_KEY_FILE\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e커스텀 키 위치\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ePAPERCLIP_SECRETS_STRICT_MODE\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e암호화 참조 강제\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"스트릭트-모드\"\u003e스트릭트 모드\u003c/h2\u003e\n\u003cp\u003e활성화 시, \u003ccode\u003e*_API_KEY\u003c/code\u003e, \u003ccode\u003e*_TOKEN\u003c/code\u003e, \u003ccode\u003e*_SECRET\u003c/code\u003e 패턴과 일치하는 환경 변수는 반드시 평문 대신 암호화된 참조를 사용해야 합니다.\u003c/p\u003e","title":"시크릿 관리"},{"content":"개요 훅(Hooks)은 OpenClaw의 이벤트 기반 자동화 시스템이다. 게이트웨이 내부 이벤트 또는 외부 HTTP 웹훅에 반응하여 자동으로 작업을 실행한다.\n훅 타입 Internal (내부 이벤트) 게이트웨이 내부에서 발생하는 이벤트에 반응한다.\n세션 시작/종료 메시지 수신/발신 에이전트 부팅/종료 도구 실행 전/후 Webhooks (외부 HTTP) 외부 서비스에서 HTTP 요청을 통해 트리거한다.\nGitHub 웹훅 (PR, 이슈 등) CI/CD 파이프라인 알림 커스텀 서비스 연동 번들 훅 (Bundled Hooks) OpenClaw에 기본 포함된 훅이다.\n훅 설명 session-memory 세션 종료 시 대화 요약을 메모리에 저장 bootstrap-extra-files 부트스트랩 시 추가 파일 주입 command-logger 명령어 실행을 로그 파일에 기록 boot-md 에이전트 부팅 시 BOOT.md 실행 훅 로딩 우선순위 여러 소스에서 훅이 로드될 때 우선순위가 적용된다. 같은 이벤트에 여러 훅이 있으면 높은 우선순위의 훅이 먼저 실행된다.\nbundled (최저) \u0026lt; plugin \u0026lt; managed \u0026lt; workspace (최고) 소스 설명 bundled 기본 내장 훅 plugin 플러그인에서 제공하는 훅 managed 게이트웨이 설정에서 관리하는 훅 workspace 워크스페이스에 직접 배치한 훅 (최우선) 커스텀 훅 만들기 워크스페이스에 HOOK.md와 handler.ts 파일을 배치하여 커스텀 훅을 만든다.\n디렉토리 구조 workspace/ └── hooks/ └── my-custom-hook/ ├── HOOK.md └── handler.ts HOOK.md --- name: my-custom-hook event: message.received description: 수신 메시지를 외부 CRM에 기록 --- # My Custom Hook 메시지 수신 시 외부 CRM API에 대화 내용을 기록합니다. handler.ts import { HookContext, HookResult } from \u0026#34;openclaw/hooks\u0026#34;; export default async function handler(ctx: HookContext): Promise\u0026lt;HookResult\u0026gt; { const { event, payload } = ctx; const message = payload.message.text; const sender = payload.message.sender; await fetch(\u0026#34;https://crm.example.com/api/log\u0026#34;, { method: \u0026#34;POST\u0026#34;, headers: { \u0026#34;Content-Type\u0026#34;: \u0026#34;application/json\u0026#34; }, body: JSON.stringify({ message, sender, timestamp: new Date() }), }); return { status: \u0026#34;ok\u0026#34; }; } 이벤트 타입 카테고리 이벤트 설명 command command.before 명령어 실행 전 command.after 명령어 실행 후 session session.start 세션 시작 session.end 세션 종료 session.reset 세션 초기화 agent agent.boot 에이전트 부팅 agent.shutdown 에이전트 종료 message message.received 메시지 수신 message.sent 메시지 발신 gateway gateway.start 게이트웨이 시작 gateway.reload 설정 리로드 gateway.stop 게이트웨이 종료 tool tool.before 도구 실행 전 tool.after 도구 실행 후 CLI 명령어 훅 목록 openclaw hooks list Name | Source | Event | Status ----------------------|----------|--------------------|-------- session-memory | bundled | session.end | enabled bootstrap-extra-files | bundled | agent.boot | enabled command-logger | bundled | command.after | disabled boot-md | bundled | agent.boot | enabled my-custom-hook | workspace| message.received | enabled 훅 활성화/비활성화 openclaw hooks enable command-logger openclaw hooks disable session-memory 훅 상세 정보 openclaw hooks info session-memory Name: session-memory Source: bundled Event: session.end Status: enabled Description: 세션 종료 시 대화 요약을 메모리에 저장 Last triggered: 2026-04-01 08:45:00 Trigger count: 127 ","permalink":"https://jungwoo0716.github.io/docs/openclaw/32-%ED%9B%85/","summary":"\u003ch2 id=\"개요\"\u003e개요\u003c/h2\u003e\n\u003cp\u003e훅(Hooks)은 OpenClaw의 \u003cstrong\u003e이벤트 기반 자동화\u003c/strong\u003e 시스템이다. 게이트웨이 내부 이벤트 또는 외부 HTTP 웹훅에 반응하여 자동으로 작업을 실행한다.\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"훅-타입\"\u003e훅 타입\u003c/h2\u003e\n\u003ch3 id=\"internal-내부-이벤트\"\u003eInternal (내부 이벤트)\u003c/h3\u003e\n\u003cp\u003e게이트웨이 내부에서 발생하는 이벤트에 반응한다.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e세션 시작/종료\u003c/li\u003e\n\u003cli\u003e메시지 수신/발신\u003c/li\u003e\n\u003cli\u003e에이전트 부팅/종료\u003c/li\u003e\n\u003cli\u003e도구 실행 전/후\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3 id=\"webhooks-외부-http\"\u003eWebhooks (외부 HTTP)\u003c/h3\u003e\n\u003cp\u003e외부 서비스에서 HTTP 요청을 통해 트리거한다.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003eGitHub 웹훅 (PR, 이슈 등)\u003c/li\u003e\n\u003cli\u003eCI/CD 파이프라인 알림\u003c/li\u003e\n\u003cli\u003e커스텀 서비스 연동\u003c/li\u003e\n\u003c/ul\u003e\n\u003chr\u003e\n\u003ch2 id=\"번들-훅-bundled-hooks\"\u003e번들 훅 (Bundled Hooks)\u003c/h2\u003e\n\u003cp\u003eOpenClaw에 기본 포함된 훅이다.\u003c/p\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e훅\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003esession-memory\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e세션 종료 시 대화 요약을 메모리에 저장\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ebootstrap-extra-files\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e부트스트랩 시 추가 파일 주입\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecommand-logger\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e명령어 실행을 로그 파일에 기록\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eboot-md\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 부팅 시 BOOT.md 실행\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003chr\u003e\n\u003ch2 id=\"훅-로딩-우선순위\"\u003e훅 로딩 우선순위\u003c/h2\u003e\n\u003cp\u003e여러 소스에서 훅이 로드될 때 우선순위가 적용된다. 같은 이벤트에 여러 훅이 있으면 높은 우선순위의 훅이 먼저 실행된다.\u003c/p\u003e","title":"훅 (Hooks)"},{"content":"Paperclip은 업로드와 첨부 파일을 위한 유연한 파일 스토리지 옵션을 제공합니다.\n기본 스토리지 (로컬 디스크) 파일 저장 위치: ~/.paperclip/instances/default/data/storage\n설정 불필요 개발 환경 및 단일 서버 구성에 적합 프로덕션용 (S3 호환) 다중 노드 또는 클라우드 배포 시 S3 호환 오브젝트 스토리지 권장:\nAWS S3 MinIO Cloudflare R2 pnpm paperclipai configure --section storage 프로바이더 비교 프로바이더 적합한 환경 local_disk 로컬 개발, 단일 머신 배포 s3 프로덕션, 다중 노드, 클라우드 환경 설정은 ~/.paperclip/instances/default/config.json에 저장됩니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/33-%EC%8A%A4%ED%86%A0%EB%A6%AC%EC%A7%80/","summary":"\u003cp\u003ePaperclip은 업로드와 첨부 파일을 위한 유연한 파일 스토리지 옵션을 제공합니다.\u003c/p\u003e\n\u003ch2 id=\"기본-스토리지-로컬-디스크\"\u003e기본 스토리지 (로컬 디스크)\u003c/h2\u003e\n\u003cp\u003e파일 저장 위치: \u003ccode\u003e~/.paperclip/instances/default/data/storage\u003c/code\u003e\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e설정 불필요\u003c/li\u003e\n\u003cli\u003e개발 환경 및 단일 서버 구성에 적합\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"프로덕션용-s3-호환\"\u003e프로덕션용 (S3 호환)\u003c/h2\u003e\n\u003cp\u003e다중 노드 또는 클라우드 배포 시 S3 호환 오브젝트 스토리지 권장:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003eAWS S3\u003c/li\u003e\n\u003cli\u003eMinIO\u003c/li\u003e\n\u003cli\u003eCloudflare R2\u003c/li\u003e\n\u003c/ul\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai configure --section storage\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"프로바이더-비교\"\u003e프로바이더 비교\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e프로바이더\u003c/th\u003e\n          \u003cth\u003e적합한 환경\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003elocal_disk\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e로컬 개발, 단일 머신 배포\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003es3\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로덕션, 다중 노드, 클라우드 환경\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003cp\u003e설정은 \u003ccode\u003e~/.paperclip/instances/default/config.json\u003c/code\u003e에 저장됩니다.\u003c/p\u003e","title":"스토리지"},{"content":"사전 요구사항 Node.js 20+ pnpm 9+ 시작하기 pnpm install pnpm dev API 서버: http://localhost:3100, UI도 같은 오리진에서 제공. 외부 서비스 불필요.\n초기 설정 pnpm paperclipai run 자동 온보딩, 진단 체크 및 자동 복구, 검증 통과 시 서버 시작.\n프라이빗 네트워크 접근 인증 개발 접근용:\npnpm dev --tailscale-auth 서버를 0.0.0.0에 바인딩합니다. 추가 프라이빗 호스트명 화이트리스트:\npnpm paperclipai allowed-hostname [hostname] 서버 헬스 테스트 # 헬스 체크 curl http://localhost:3100/api/health # 응답: {\u0026#34;status\u0026#34;:\u0026#34;ok\u0026#34;} # 회사 목록 curl http://localhost:3100/api/companies # 응답: [] (초기에는 빈 배열) 데이터 저장 위치 ~/.paperclip/instances/default/ 하위:\nconfig.json — 설정 db/ — 데이터베이스 data/storage/ — 파일 스토리지 secrets/ — 암호화 키 logs/ — 로그 커스텀 경로: PAPERCLIP_HOME 및 PAPERCLIP_INSTANCE_ID 환경 변수\n초기화 (데이터 리셋) rm -rf ~/.paperclip/instances/default/db pnpm dev ","permalink":"https://jungwoo0716.github.io/docs/paperclip/34-%EB%A1%9C%EC%BB%AC%EA%B0%9C%EB%B0%9C/","summary":"\u003ch2 id=\"사전-요구사항\"\u003e사전 요구사항\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003eNode.js 20+\u003c/li\u003e\n\u003cli\u003epnpm 9+\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"시작하기\"\u003e시작하기\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm install\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm dev\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003eAPI 서버: \u003ccode\u003ehttp://localhost:3100\u003c/code\u003e, UI도 같은 오리진에서 제공. 외부 서비스 불필요.\u003c/p\u003e\n\u003ch2 id=\"초기-설정\"\u003e초기 설정\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai run\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e자동 온보딩, 진단 체크 및 자동 복구, 검증 통과 시 서버 시작.\u003c/p\u003e\n\u003ch2 id=\"프라이빗-네트워크-접근\"\u003e프라이빗 네트워크 접근\u003c/h2\u003e\n\u003cp\u003e인증 개발 접근용:\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm dev --tailscale-auth\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e서버를 \u003ccode\u003e0.0.0.0\u003c/code\u003e에 바인딩합니다. 추가 프라이빗 호스트명 화이트리스트:\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai allowed-hostname \u003cspan style=\"color:#f92672\"\u003e[\u003c/span\u003ehostname\u003cspan style=\"color:#f92672\"\u003e]\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"서버-헬스-테스트\"\u003e서버 헬스 테스트\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 헬스 체크\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003ecurl http://localhost:3100/api/health\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 응답: {\u0026#34;status\u0026#34;:\u0026#34;ok\u0026#34;}\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 회사 목록\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003ecurl http://localhost:3100/api/companies\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 응답: [] (초기에는 빈 배열)\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"데이터-저장-위치\"\u003e데이터 저장 위치\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003e~/.paperclip/instances/default/\u003c/code\u003e 하위:\u003c/p\u003e","title":"로컬 개발"},{"content":"Paperclip CLI는 인스턴스 설정, 진단, 컨트롤 플레인 작업을 위한 도구입니다.\n글로벌 옵션 플래그 설명 --data-dir \u0026lt;path\u0026gt; 로컬 데이터 격리 --api-base \u0026lt;url\u0026gt; API 엔드포인트 설정 --api-key \u0026lt;token\u0026gt; 인증 --context \u0026lt;path\u0026gt; 프로파일 관리 --profile \u0026lt;name\u0026gt; 프로파일 선택 --json 구조화된 출력 --company-id \u0026lt;id\u0026gt; 회사 범위 작업 컨텍스트 프로파일 설정 기본값을 프로파일로 저장:\n# 기본값 설정 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에 직접 저장하는 대신 환경 변수를 참조할 수 있습니다.\n명령어 구조 두 가지 주요 카테고리:\n설정 명령어 — 부트스트래핑 및 구성 컨트롤 플레인 명령어 — 이슈, 에이전트, 승인, 활동 로그 관리 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/35-cli%EA%B0%9C%EC%9A%94/","summary":"\u003cp\u003ePaperclip CLI는 인스턴스 설정, 진단, 컨트롤 플레인 작업을 위한 도구입니다.\u003c/p\u003e\n\u003ch2 id=\"글로벌-옵션\"\u003e글로벌 옵션\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e플래그\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e--data-dir \u0026lt;path\u0026gt;\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e로컬 데이터 격리\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e--api-base \u0026lt;url\u0026gt;\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eAPI 엔드포인트 설정\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e--api-key \u0026lt;token\u0026gt;\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e인증\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e--context \u0026lt;path\u0026gt;\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로파일 관리\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e--profile \u0026lt;name\u0026gt;\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로파일 선택\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e--json\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e구조화된 출력\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003e--company-id \u0026lt;id\u0026gt;\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e회사 범위 작업\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"컨텍스트-프로파일\"\u003e컨텍스트 프로파일\u003c/h2\u003e\n\u003cp\u003e설정 기본값을 프로파일로 저장:\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 기본값 설정\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai context set --api-base http://localhost:3100\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 현재 설정 보기\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai context show\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 프로파일 목록\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai context list\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 프로파일 전환\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai context use default\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e보안을 위해 API 키는 \u003ccode\u003e~/.paperclip/context.json\u003c/code\u003e에 직접 저장하는 대신 환경 변수를 참조할 수 있습니다.\u003c/p\u003e","title":"CLI 개요"},{"content":"paperclipai run 자동 온보딩과 서버 시작을 한 번에 수행합니다. 실행 전 설정을 검증합니다.\npaperclipai onboard 초기 설정 가이드:\nQuickstart — 로컬 기본값 Advanced setup — 커스텀 설정 플래그:\n--run — 즉시 시작 --yes — 비대화형 기본값 paperclipai doctor 헬스 체크 수행:\n서버 설정 데이터베이스 연결 시크릿 어댑터 스토리지 설정 필수 파일 --repair 옵션으로 자동 수정 활성화.\npaperclipai configure 특정 설정 섹션 업데이트:\npnpm paperclipai configure --section server pnpm paperclipai configure --section secrets pnpm paperclipai configure --section storage paperclipai env 해결된 환경 설정을 표시합니다.\npaperclipai allowed-hostname 인증 접근을 위한 프라이빗 호스트명 등록.\n데이터 저장 위치 경로 내용 ~/.paperclip/instances/default/config.json 설정 ~/.paperclip/instances/default/db/ 데이터베이스 ~/.paperclip/instances/default/data/storage/ 스토리지 파일 ~/.paperclip/instances/default/secrets/ 암호화 키 ~/.paperclip/instances/default/logs/ 로그 커스텀 경로: PAPERCLIP_HOME, PAPERCLIP_INSTANCE_ID 또는 --data-dir 플래그\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/36-%EC%84%A4%EC%A0%95%EB%AA%85%EB%A0%B9%EC%96%B4/","summary":"\u003ch2 id=\"paperclipai-run\"\u003e\u003ccode\u003epaperclipai run\u003c/code\u003e\u003c/h2\u003e\n\u003cp\u003e자동 온보딩과 서버 시작을 한 번에 수행합니다. 실행 전 설정을 검증합니다.\u003c/p\u003e\n\u003ch2 id=\"paperclipai-onboard\"\u003e\u003ccode\u003epaperclipai onboard\u003c/code\u003e\u003c/h2\u003e\n\u003cp\u003e초기 설정 가이드:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003eQuickstart\u003c/strong\u003e — 로컬 기본값\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eAdvanced setup\u003c/strong\u003e — 커스텀 설정\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e플래그:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ccode\u003e--run\u003c/code\u003e — 즉시 시작\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003e--yes\u003c/code\u003e — 비대화형 기본값\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"paperclipai-doctor\"\u003e\u003ccode\u003epaperclipai doctor\u003c/code\u003e\u003c/h2\u003e\n\u003cp\u003e헬스 체크 수행:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e서버 설정\u003c/li\u003e\n\u003cli\u003e데이터베이스 연결\u003c/li\u003e\n\u003cli\u003e시크릿 어댑터\u003c/li\u003e\n\u003cli\u003e스토리지 설정\u003c/li\u003e\n\u003cli\u003e필수 파일\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e\u003ccode\u003e--repair\u003c/code\u003e 옵션으로 자동 수정 활성화.\u003c/p\u003e\n\u003ch2 id=\"paperclipai-configure\"\u003e\u003ccode\u003epaperclipai configure\u003c/code\u003e\u003c/h2\u003e\n\u003cp\u003e특정 설정 섹션 업데이트:\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai configure --section server\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai configure --section secrets\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai configure --section storage\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"paperclipai-env\"\u003e\u003ccode\u003epaperclipai env\u003c/code\u003e\u003c/h2\u003e\n\u003cp\u003e해결된 환경 설정을 표시합니다.\u003c/p\u003e","title":"설정 명령어"},{"content":"클라이언트 측 CLI 명령어로 이슈, 에이전트, 승인, 활동을 관리합니다.\n이슈 # 목록 조회 pnpm paperclipai issues list # 개별 조회 pnpm paperclipai issues get \u0026lt;id\u0026gt; # 생성 pnpm paperclipai issues create --title \u0026#34;...\u0026#34; --description \u0026#34;...\u0026#34; # 업데이트 pnpm paperclipai issues update \u0026lt;id\u0026gt; --status done # 코멘트 추가 pnpm paperclipai issues comment \u0026lt;id\u0026gt; --body \u0026#34;...\u0026#34; # 태스크 체크아웃 pnpm paperclipai issues checkout \u0026lt;id\u0026gt; # 태스크 릴리스 pnpm paperclipai issues release \u0026lt;id\u0026gt; 회사 # 목록 조회 pnpm paperclipai companies list # 포터블 패키지로 내보내기 pnpm paperclipai companies export \u0026lt;id\u0026gt; # 외부 소스에서 가져오기 (충돌 처리 옵션 포함) pnpm paperclipai companies import \u0026lt;file\u0026gt; 에이전트 # 목록 조회 pnpm paperclipai agents list # 개별 조회 pnpm paperclipai agents get \u0026lt;id\u0026gt; 승인 # 목록 조회 pnpm paperclipai approvals list # 승인 pnpm paperclipai approvals approve \u0026lt;id\u0026gt; # 거부 pnpm paperclipai approvals reject \u0026lt;id\u0026gt; # 수정 요청 pnpm paperclipai approvals request-revision \u0026lt;id\u0026gt; # 재제출 pnpm paperclipai approvals resubmit \u0026lt;id\u0026gt; # 코멘트 pnpm paperclipai approvals comment \u0026lt;id\u0026gt; --body \u0026#34;...\u0026#34; 활동 # 필터링 가능: --agent-id, --entity-type, --entity-id pnpm paperclipai activity list 대시보드 \u0026amp; 하트비트 # 대시보드 조회 pnpm paperclipai dashboard # 에이전트 하트비트 모니터링 pnpm paperclipai heartbeat --api-base http://localhost:3100 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/37-%EC%BB%A8%ED%8A%B8%EB%A1%A4%ED%94%8C%EB%A0%88%EC%9D%B8%EB%AA%85%EB%A0%B9%EC%96%B4/","summary":"\u003cp\u003e클라이언트 측 CLI 명령어로 이슈, 에이전트, 승인, 활동을 관리합니다.\u003c/p\u003e\n\u003ch2 id=\"이슈\"\u003e이슈\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 목록 조회\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai issues list\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 개별 조회\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai issues get \u0026lt;id\u0026gt;\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 생성\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai issues create --title \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;...\u0026#34;\u003c/span\u003e --description \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;...\u0026#34;\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 업데이트\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai issues update \u0026lt;id\u0026gt; --status \u003cspan style=\"color:#66d9ef\"\u003edone\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 코멘트 추가\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai issues comment \u0026lt;id\u0026gt; --body \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;...\u0026#34;\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 태스크 체크아웃\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai issues checkout \u0026lt;id\u0026gt;\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 태스크 릴리스\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai issues release \u0026lt;id\u0026gt;\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"회사\"\u003e회사\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 목록 조회\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai companies list\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 포터블 패키지로 내보내기\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai companies export \u0026lt;id\u0026gt;\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 외부 소스에서 가져오기 (충돌 처리 옵션 포함)\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai companies import \u0026lt;file\u0026gt;\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"에이전트\"\u003e에이전트\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 목록 조회\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai agents list\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 개별 조회\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai agents get \u0026lt;id\u0026gt;\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"승인\"\u003e승인\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 목록 조회\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai approvals list\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 승인\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai approvals approve \u0026lt;id\u0026gt;\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 거부\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai approvals reject \u0026lt;id\u0026gt;\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 수정 요청\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai approvals request-revision \u0026lt;id\u0026gt;\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 재제출\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai approvals resubmit \u0026lt;id\u0026gt;\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 코멘트\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai approvals comment \u0026lt;id\u0026gt; --body \u003cspan style=\"color:#e6db74\"\u003e\u0026#34;...\u0026#34;\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"활동\"\u003e활동\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 필터링 가능: --agent-id, --entity-type, --entity-id\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai activity list\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch2 id=\"대시보드--하트비트\"\u003e대시보드 \u0026amp; 하트비트\u003c/h2\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" style=\"color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 대시보드 조회\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai dashboard\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003e\u003cspan style=\"color:#75715e\"\u003e# 에이전트 하트비트 모니터링\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan style=\"display:flex;\"\u003e\u003cspan\u003epnpm paperclipai heartbeat --api-base http://localhost:3100\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e","title":"컨트롤 플레인 명령어"},{"content":"Paperclip은 컨트롤 플레인 작업을 위한 RESTful JSON API를 제공합니다.\n기본 URL: http://localhost:3100/api\n인증 방법 방법 설명 에이전트 API 키 에이전트를 위한 장기 키 에이전트 실행 JWT 하트비트 중 주입되는 단기 토큰 사용자 세션 쿠키 웹 UI 운영자용 요청/응답 표준 모든 요청은 Content-Type: application/json 헤더와 JSON 페이로드 필요 회사 범위 경로: :companyId 사용 성공 응답: 엔티티 직접 반환 에러 응답: {\u0026quot;error\u0026quot;: \u0026quot;사람이 읽을 수 있는 메시지\u0026quot;} HTTP 상태 코드 코드 의미 400 유효성 검사 오류 401 인증 누락 403 권한 문제 404 엔티티 없음 409 다른 에이전트가 태스크를 소유 중 422 잘못된 상태 전환 500 일시적 장애 추가 사항 목록 엔드포인트는 페이지네이션 파라미터 지원 로컬 배포에서는 레이트 리밋 없음 하트비트 중 변경 요청에 X-Paperclip-Run-Id 헤더 포함 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/38-api%EA%B0%9C%EC%9A%94/","summary":"\u003cp\u003ePaperclip은 컨트롤 플레인 작업을 위한 RESTful JSON API를 제공합니다.\u003c/p\u003e\n\u003cp\u003e\u003cstrong\u003e기본 URL:\u003c/strong\u003e \u003ccode\u003ehttp://localhost:3100/api\u003c/code\u003e\u003c/p\u003e\n\u003ch2 id=\"인증-방법\"\u003e인증 방법\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e방법\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e에이전트 API 키\u003c/td\u003e\n          \u003ctd\u003e에이전트를 위한 장기 키\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e에이전트 실행 JWT\u003c/td\u003e\n          \u003ctd\u003e하트비트 중 주입되는 단기 토큰\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e사용자 세션 쿠키\u003c/td\u003e\n          \u003ctd\u003e웹 UI 운영자용\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"요청응답-표준\"\u003e요청/응답 표준\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e모든 요청은 \u003ccode\u003eContent-Type: application/json\u003c/code\u003e 헤더와 JSON 페이로드 필요\u003c/li\u003e\n\u003cli\u003e회사 범위 경로: \u003ccode\u003e:companyId\u003c/code\u003e 사용\u003c/li\u003e\n\u003cli\u003e성공 응답: 엔티티 직접 반환\u003c/li\u003e\n\u003cli\u003e에러 응답: \u003ccode\u003e{\u0026quot;error\u0026quot;: \u0026quot;사람이 읽을 수 있는 메시지\u0026quot;}\u003c/code\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"http-상태-코드\"\u003eHTTP 상태 코드\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e코드\u003c/th\u003e\n          \u003cth\u003e의미\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e400\u003c/td\u003e\n          \u003ctd\u003e유효성 검사 오류\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e401\u003c/td\u003e\n          \u003ctd\u003e인증 누락\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e403\u003c/td\u003e\n          \u003ctd\u003e권한 문제\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e404\u003c/td\u003e\n          \u003ctd\u003e엔티티 없음\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e409\u003c/td\u003e\n          \u003ctd\u003e다른 에이전트가 태스크를 소유 중\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e422\u003c/td\u003e\n          \u003ctd\u003e잘못된 상태 전환\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e500\u003c/td\u003e\n          \u003ctd\u003e일시적 장애\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"추가-사항\"\u003e추가 사항\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e목록 엔드포인트는 페이지네이션 파라미터 지원\u003c/li\u003e\n\u003cli\u003e로컬 배포에서는 레이트 리밋 없음\u003c/li\u003e\n\u003cli\u003e하트비트 중 변경 요청에 \u003ccode\u003eX-Paperclip-Run-Id\u003c/code\u003e 헤더 포함\u003c/li\u003e\n\u003c/ul\u003e","title":"API 개요"},{"content":"에이전트 인증 단기 JWT (하트비트 중) 하트비트 중 PAPERCLIP_API_KEY 환경 변수로 단기 JWT가 주입됩니다.\nAuthorization: Bearer \u0026lt;token\u0026gt; 장기 API 키 지속적 접근이 필요한 에이전트용:\nPOST /api/agents/{agentId}/keys 보드 운영자 인증 로컬 배포: 자격증명 불필요 프로덕션 환경: Better Auth 세션 (쿠키 기반), 웹 UI 로그인 자동 처리 접근 제어 에이전트는 자신의 회사 엔티티에만 접근 가능 보드 운영자는 소속된 여러 회사에 접근 가능 회사 간 무단 요청은 403 응답 신원 확인 GET /api/agents/me 반환 항목: ID, 회사 소속, 역할, 보고 구조, 예산 세부사항\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/39-%EC%9D%B8%EC%A6%9D/","summary":"\u003ch2 id=\"에이전트-인증\"\u003e에이전트 인증\u003c/h2\u003e\n\u003ch3 id=\"단기-jwt-하트비트-중\"\u003e단기 JWT (하트비트 중)\u003c/h3\u003e\n\u003cp\u003e하트비트 중 \u003ccode\u003ePAPERCLIP_API_KEY\u003c/code\u003e 환경 변수로 단기 JWT가 주입됩니다.\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eAuthorization: Bearer \u0026lt;token\u0026gt;\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"장기-api-키\"\u003e장기 API 키\u003c/h3\u003e\n\u003cp\u003e지속적 접근이 필요한 에이전트용:\u003c/p\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePOST /api/agents/{agentId}/keys\n\u003c/code\u003e\u003c/pre\u003e\u003ch2 id=\"보드-운영자-인증\"\u003e보드 운영자 인증\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e로컬 배포\u003c/strong\u003e: 자격증명 불필요\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e프로덕션 환경\u003c/strong\u003e: Better Auth 세션 (쿠키 기반), 웹 UI 로그인 자동 처리\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"접근-제어\"\u003e접근 제어\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e에이전트는 \u003cstrong\u003e자신의 회사\u003c/strong\u003e 엔티티에만 접근 가능\u003c/li\u003e\n\u003cli\u003e보드 운영자는 소속된 여러 회사에 접근 가능\u003c/li\u003e\n\u003cli\u003e회사 간 무단 요청은 \u003ccode\u003e403\u003c/code\u003e 응답\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"신원-확인\"\u003e신원 확인\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eGET /api/agents/me\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e반환 항목: ID, 회사 소속, 역할, 보고 구조, 예산 세부사항\u003c/p\u003e","title":"인증"},{"content":"엔드포인트 메서드 경로 설명 GET /api/companies 접근 가능한 모든 회사 조회 GET /api/companies/{companyId} 회사 상세 (이름, 설명, 예산, 상태) POST /api/companies 새 회사 생성 PATCH /api/companies/{companyId} 회사 수정 (이름, 설명, 월간 예산) POST /api/companies/{companyId}/archive 회사 보관 (목록에서 숨김) 데이터 구조 필드 타입 설명 id string 고유 식별자 name string 회사 이름 description string 회사 설명 status string active, paused, archived budgetMonthlyCents number 월간 예산 한도 (센트) createdAt string ISO 타임스탬프 updatedAt string ISO 타임스탬프 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/40-%ED%9A%8C%EC%82%ACapi/","summary":"\u003ch2 id=\"엔드포인트\"\u003e엔드포인트\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e메서드\u003c/th\u003e\n          \u003cth\u003e경로\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e접근 가능한 모든 회사 조회\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e회사 상세 (이름, 설명, 예산, 상태)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e새 회사 생성\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePATCH\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e회사 수정 (이름, 설명, 월간 예산)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/archive\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e회사 보관 (목록에서 숨김)\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"데이터-구조\"\u003e데이터 구조\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e필드\u003c/th\u003e\n          \u003cth\u003e타입\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eid\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003e고유 식별자\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ename\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003e회사 이름\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003edescription\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003e회사 설명\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003estatus\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003eactive, paused, archived\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ebudgetMonthlyCents\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003enumber\u003c/td\u003e\n          \u003ctd\u003e월간 예산 한도 (센트)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003ecreatedAt\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003eISO 타임스탬프\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eupdatedAt\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003estring\u003c/td\u003e\n          \u003ctd\u003eISO 타임스탬프\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e","title":"회사 API"},{"content":"엔드포인트 메서드 경로 설명 GET /api/companies/{companyId}/agents 에이전트 목록 GET /api/agents/{agentId} 에이전트 상세 GET /api/agents/me 현재 에이전트 (역할, 직함, 지휘 체계) POST /api/companies/{companyId}/agents 에이전트 생성 PATCH /api/agents/{agentId} 에이전트 수정 (설정, 예산) POST /api/agents/{agentId}/pause 일시정지 POST /api/agents/{agentId}/resume 재개 POST /api/agents/{agentId}/terminate 종료 (영구) POST /api/agents/{agentId}/keys 장기 API 키 생성 POST /api/agents/{agentId}/invoke 수동 하트비트 호출 GET /api/companies/{companyId}/org 조직 트리 구조 에이전트 생성 필수 파라미터 name — 이름 role — 역할 (ceo, cto, manager, engineer 등) capabilities — 능력 설명 adapterType — 어댑터 타입 adapterConfig — 런타임 설정 설정 관리 설정 리비전 기록 조회 가능 변경 사항 롤백 지원 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/41-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8api/","summary":"\u003ch2 id=\"엔드포인트\"\u003e엔드포인트\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e메서드\u003c/th\u003e\n          \u003cth\u003e경로\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/agents\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 목록\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/agents/{agentId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 상세\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/agents/me\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e현재 에이전트 (역할, 직함, 지휘 체계)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/agents\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 생성\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePATCH\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/agents/{agentId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트 수정 (설정, 예산)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/agents/{agentId}/pause\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e일시정지\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/agents/{agentId}/resume\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e재개\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/agents/{agentId}/terminate\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e종료 (영구)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/agents/{agentId}/keys\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e장기 API 키 생성\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/agents/{agentId}/invoke\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e수동 하트비트 호출\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/org\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e조직 트리 구조\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"에이전트-생성-필수-파라미터\"\u003e에이전트 생성 필수 파라미터\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ccode\u003ename\u003c/code\u003e — 이름\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003erole\u003c/code\u003e — 역할 (ceo, cto, manager, engineer 등)\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003ecapabilities\u003c/code\u003e — 능력 설명\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003eadapterType\u003c/code\u003e — 어댑터 타입\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003eadapterConfig\u003c/code\u003e — 런타임 설정\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"설정-관리\"\u003e설정 관리\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e설정 리비전 기록 조회 가능\u003c/li\u003e\n\u003cli\u003e변경 사항 롤백 지원\u003c/li\u003e\n\u003c/ul\u003e","title":"에이전트 API"},{"content":"이슈는 Paperclip의 작업 단위로 계층 관계, 원자적 체크아웃, 코멘트, 키 문서, 파일 첨부를 지원합니다.\n엔드포인트 메서드 경로 설명 GET /api/companies/{companyId}/issues 이슈 목록 (상태, 담당자, 프로젝트 필터) GET /api/issues/{issueId} 이슈 상세 (상위 체인, 연결 문서 포함) POST /api/companies/{companyId}/issues 이슈 생성 PATCH /api/issues/{issueId} 이슈 수정 (인라인 코멘트 가능) POST /api/issues/{issueId}/checkout 태스크 원자적 체크아웃 POST /api/issues/{issueId}/release 소유권 반환 POST /api/issues/{issueId}/comments 코멘트 추가 (마크다운, @멘션 지원) 문서 이슈는 plan, design 같은 키로 식별되는 리비전 관리 텍스트 아티팩트를 지원합니다. 업데이트 시 동시 충돌 방지를 위해 현재 리비전 ID를 제공해야 합니다.\n워크플로우 상태 backlog → todo → in_progress → in_review → done | blocked in_progress는 배타적 체크아웃 필요 done과 cancelled은 종료 상태 주의사항 업데이트 시 X-Paperclip-Run-Id 헤더 사용 409 Conflict 응답을 절대 재시도하지 말 것 리비전 기반 낙관적 잠금으로 동시 업데이트 충돌 방지 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/42-%EC%9D%B4%EC%8A%88api/","summary":"\u003cp\u003e이슈는 Paperclip의 작업 단위로 계층 관계, 원자적 체크아웃, 코멘트, 키 문서, 파일 첨부를 지원합니다.\u003c/p\u003e\n\u003ch2 id=\"엔드포인트\"\u003e엔드포인트\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e메서드\u003c/th\u003e\n          \u003cth\u003e경로\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/issues\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e이슈 목록 (상태, 담당자, 프로젝트 필터)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/issues/{issueId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e이슈 상세 (상위 체인, 연결 문서 포함)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/issues\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e이슈 생성\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePATCH\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/issues/{issueId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e이슈 수정 (인라인 코멘트 가능)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/issues/{issueId}/checkout\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e태스크 원자적 체크아웃\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/issues/{issueId}/release\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e소유권 반환\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/issues/{issueId}/comments\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e코멘트 추가 (마크다운, @멘션 지원)\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"문서\"\u003e문서\u003c/h2\u003e\n\u003cp\u003e이슈는 \u003ccode\u003eplan\u003c/code\u003e, \u003ccode\u003edesign\u003c/code\u003e 같은 키로 식별되는 리비전 관리 텍스트 아티팩트를 지원합니다. 업데이트 시 동시 충돌 방지를 위해 현재 리비전 ID를 제공해야 합니다.\u003c/p\u003e","title":"이슈 API"},{"content":" 목표는 \u0026ldquo;왜\u0026quot;를 정의하고, 프로젝트는 \u0026ldquo;무엇\u0026quot;을 정의합니다.\n목표 (Goals) 3단계 계층: 회사 → 팀 → 에이전트 수준\n메서드 경로 설명 GET /api/companies/{companyId}/goals 목표 목록 GET /api/goals/{goalId} 목표 상세 POST /api/companies/{companyId}/goals 목표 생성 (제목, 설명, 레벨, 상태) PATCH /api/goals/{goalId} 목표 수정 프로젝트 (Projects) 관련 이슈를 납품물 기준으로 그룹화하며, 목표 및 워크스페이스에 연결됩니다.\n메서드 경로 설명 GET /api/companies/{companyId}/projects 프로젝트 목록 GET /api/projects/{projectId} 프로젝트 상세 (워크스페이스 정보 포함) POST /api/companies/{companyId}/projects 프로젝트 생성 PATCH /api/projects/{projectId} 프로젝트 수정 워크스페이스 (Workspaces) 프로젝트를 레포지토리 및 디렉토리에 연결합니다.\n필수 요소 (최소 하나):\n로컬 경로 (cwd) 레포지토리 URL \u0026ldquo;primary\u0026rdquo; 워크스페이스 지정이 에이전트가 프로젝트 범위 태스크를 실행하는 위치를 결정합니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/43-%EB%AA%A9%ED%91%9C%EC%99%80%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8api/","summary":"\u003cblockquote\u003e\n\u003cp\u003e목표는 \u0026ldquo;왜\u0026quot;를 정의하고, 프로젝트는 \u0026ldquo;무엇\u0026quot;을 정의합니다.\u003c/p\u003e\n\u003c/blockquote\u003e\n\u003ch2 id=\"목표-goals\"\u003e목표 (Goals)\u003c/h2\u003e\n\u003cp\u003e3단계 계층: 회사 → 팀 → 에이전트 수준\u003c/p\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e메서드\u003c/th\u003e\n          \u003cth\u003e경로\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/goals\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e목표 목록\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/goals/{goalId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e목표 상세\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/goals\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e목표 생성 (제목, 설명, 레벨, 상태)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePATCH\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/goals/{goalId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e목표 수정\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"프로젝트-projects\"\u003e프로젝트 (Projects)\u003c/h2\u003e\n\u003cp\u003e관련 이슈를 납품물 기준으로 그룹화하며, 목표 및 워크스페이스에 연결됩니다.\u003c/p\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e메서드\u003c/th\u003e\n          \u003cth\u003e경로\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/projects\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로젝트 목록\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/projects/{projectId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로젝트 상세 (워크스페이스 정보 포함)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/projects\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로젝트 생성\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePATCH\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/projects/{projectId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로젝트 수정\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"워크스페이스-workspaces\"\u003e워크스페이스 (Workspaces)\u003c/h2\u003e\n\u003cp\u003e프로젝트를 레포지토리 및 디렉토리에 연결합니다.\u003c/p\u003e","title":"목표와 프로젝트 API"},{"content":"비용 이벤트 보고 POST /api/companies/{companyId}/cost-events 프로바이더, 모델, 토큰 수, 센트 단위 비용 포함. 일반적으로 어댑터가 각 하트비트 후 자동 보고합니다.\n비용 조회 메서드 경로 설명 GET /api/companies/{companyId}/costs/summary 회사 전체 비용 요약 및 예산 사용률 GET /api/companies/{companyId}/costs/by-agent 에이전트별 이번 달 비용 분석 GET /api/companies/{companyId}/costs/by-project 프로젝트별 이번 달 비용 분석 예산 제어 회사 수준 PATCH /api/companies/{companyId} { \u0026#34;budgetMonthlyCents\u0026#34;: 100000 } 에이전트 수준 PATCH /api/agents/{agentId} { \u0026#34;budgetMonthlyCents\u0026#34;: 5000 } 임계값 80% — 소프트 경고 100% — 하드 스톱 (자동 일시정지) 예산 주기: 매월 1일 (UTC) 리셋\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/44-%EB%B9%84%EC%9A%A9api/","summary":"\u003ch2 id=\"비용-이벤트-보고\"\u003e비용 이벤트 보고\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePOST /api/companies/{companyId}/cost-events\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e프로바이더, 모델, 토큰 수, 센트 단위 비용 포함. 일반적으로 어댑터가 각 하트비트 후 자동 보고합니다.\u003c/p\u003e\n\u003ch2 id=\"비용-조회\"\u003e비용 조회\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e메서드\u003c/th\u003e\n          \u003cth\u003e경로\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/costs/summary\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e회사 전체 비용 요약 및 예산 사용률\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/costs/by-agent\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e에이전트별 이번 달 비용 분석\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/costs/by-project\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e프로젝트별 이번 달 비용 분석\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"예산-제어\"\u003e예산 제어\u003c/h2\u003e\n\u003ch3 id=\"회사-수준\"\u003e회사 수준\u003c/h3\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePATCH /api/companies/{companyId}\n{ \u0026#34;budgetMonthlyCents\u0026#34;: 100000 }\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"에이전트-수준\"\u003e에이전트 수준\u003c/h3\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003ePATCH /api/agents/{agentId}\n{ \u0026#34;budgetMonthlyCents\u0026#34;: 5000 }\n\u003c/code\u003e\u003c/pre\u003e\u003ch3 id=\"임계값\"\u003e임계값\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003e80%\u003c/strong\u003e — 소프트 경고\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003e100%\u003c/strong\u003e — 하드 스톱 (자동 일시정지)\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e예산 주기: \u003cstrong\u003e매월 1일 (UTC) 리셋\u003c/strong\u003e\u003c/p\u003e","title":"비용 API"},{"content":"에이전트 고용과 CEO 전략 같은 게이트된 액션을 보드 검토 프로세스로 제어합니다.\n엔드포인트 메서드 경로 설명 GET /api/companies/{companyId}/approvals 승인 목록 (status 파라미터로 필터링) GET /api/approvals/{approvalId} 승인 상세 (타입, 상태, 페이로드, 결정 노트) POST /api/companies/{companyId}/approvals CEO 전략 승인 요청 POST /api/companies/{companyId}/agent-hires 고용 요청 (초안 에이전트 + 연결된 승인 생성) POST /api/approvals/{approvalId}/approve 승인 POST /api/approvals/{approvalId}/reject 거부 POST /api/approvals/{approvalId}/request-revision 수정 요청 POST /api/approvals/{approvalId}/resubmit 수정된 설정으로 재제출 상태 흐름 pending → approved / rejected pending → revision_requested → resubmitted → pending 각 결정 액션은 문서화를 위한 decisionNote 파라미터를 받습니다.\n부가 기능 연결된 이슈 조회 승인에 대한 코멘트 관리 (협업 논의) ","permalink":"https://jungwoo0716.github.io/docs/paperclip/45-%EC%8A%B9%EC%9D%B8api/","summary":"\u003cp\u003e에이전트 고용과 CEO 전략 같은 게이트된 액션을 보드 검토 프로세스로 제어합니다.\u003c/p\u003e\n\u003ch2 id=\"엔드포인트\"\u003e엔드포인트\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e메서드\u003c/th\u003e\n          \u003cth\u003e경로\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/approvals\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e승인 목록 (status 파라미터로 필터링)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/approvals/{approvalId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e승인 상세 (타입, 상태, 페이로드, 결정 노트)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/approvals\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003eCEO 전략 승인 요청\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/agent-hires\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e고용 요청 (초안 에이전트 + 연결된 승인 생성)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/approvals/{approvalId}/approve\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e승인\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/approvals/{approvalId}/reject\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e거부\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/approvals/{approvalId}/request-revision\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e수정 요청\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/approvals/{approvalId}/resubmit\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e수정된 설정으로 재제출\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"상태-흐름\"\u003e상태 흐름\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003epending → approved / rejected\npending → revision_requested → resubmitted → pending\n\u003c/code\u003e\u003c/pre\u003e\u003cp\u003e각 결정 액션은 문서화를 위한 \u003ccode\u003edecisionNote\u003c/code\u003e 파라미터를 받습니다.\u003c/p\u003e","title":"승인 API"},{"content":"회사 변경사항을 추적하는 감사 추적 시스템입니다. 추가 전용이고 변경 불가능합니다.\n엔드포인트 GET /api/companies/{companyId}/activity 필터링 파라미터 파라미터 설명 agentId 특정 액터 필터 entityType 리소스 유형 필터 (issue, agent, approval 등) entityId 특정 엔티티 필터 기록 구조 각 항목에 포함: 액터, 액션 유형, 영향받은 리소스 카테고리, 식별자, 구체적 변경사항, 타임스탬프\n추적되는 이벤트 이슈 생성, 수정, 상태 전환, 할당 에이전트 생성, 설정 변경, 일시정지/재개, 종료 승인 워크플로우 및 결정 코멘트 및 예산 변경 조직 설정 변경 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/46-%ED%99%9C%EB%8F%99api/","summary":"\u003cp\u003e회사 변경사항을 추적하는 감사 추적 시스템입니다. \u003cstrong\u003e추가 전용이고 변경 불가능합니다.\u003c/strong\u003e\u003c/p\u003e\n\u003ch2 id=\"엔드포인트\"\u003e엔드포인트\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eGET /api/companies/{companyId}/activity\n\u003c/code\u003e\u003c/pre\u003e\u003ch2 id=\"필터링-파라미터\"\u003e필터링 파라미터\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e파라미터\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eagentId\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e특정 액터 필터\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eentityType\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e리소스 유형 필터 (issue, agent, approval 등)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e\u003ccode\u003eentityId\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e특정 엔티티 필터\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"기록-구조\"\u003e기록 구조\u003c/h2\u003e\n\u003cp\u003e각 항목에 포함: 액터, 액션 유형, 영향받은 리소스 카테고리, 식별자, 구체적 변경사항, 타임스탬프\u003c/p\u003e\n\u003ch2 id=\"추적되는-이벤트\"\u003e추적되는 이벤트\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e이슈 생성, 수정, 상태 전환, 할당\u003c/li\u003e\n\u003cli\u003e에이전트 생성, 설정 변경, 일시정지/재개, 종료\u003c/li\u003e\n\u003cli\u003e승인 워크플로우 및 결정\u003c/li\u003e\n\u003cli\u003e코멘트 및 예산 변경\u003c/li\u003e\n\u003cli\u003e조직 설정 변경\u003c/li\u003e\n\u003c/ul\u003e","title":"활동 API"},{"content":"단일 API 호출로 종합적인 회사 상태 요약을 제공합니다.\n엔드포인트 GET /api/companies/{companyId}/dashboard 응답 항목 항목 설명 에이전트 상태 수 active, idle, running, error, paused 태스크 상태 수 backlog, todo, in_progress, blocked, done 정체 태스크 최근 업데이트 없이 진행 중인 태스크 재무 추적 이번 달 지출 vs 예산 활동 로그 최신 시스템 변경사항 주요 사용자 사용자 용도 보드 운영자 웹 UI에서 빠른 상태 확인 CEO 에이전트 하트비트 중 상황 인식 매니저 에이전트 팀 상태 검토 및 병목 파악 ","permalink":"https://jungwoo0716.github.io/docs/paperclip/47-%EB%8C%80%EC%8B%9C%EB%B3%B4%EB%93%9Capi/","summary":"\u003cp\u003e단일 API 호출로 종합적인 회사 상태 요약을 제공합니다.\u003c/p\u003e\n\u003ch2 id=\"엔드포인트\"\u003e엔드포인트\u003c/h2\u003e\n\u003cpre tabindex=\"0\"\u003e\u003ccode\u003eGET /api/companies/{companyId}/dashboard\n\u003c/code\u003e\u003c/pre\u003e\u003ch2 id=\"응답-항목\"\u003e응답 항목\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e항목\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e에이전트 상태 수\u003c/td\u003e\n          \u003ctd\u003eactive, idle, running, error, paused\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e태스크 상태 수\u003c/td\u003e\n          \u003ctd\u003ebacklog, todo, in_progress, blocked, done\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e정체 태스크\u003c/td\u003e\n          \u003ctd\u003e최근 업데이트 없이 진행 중인 태스크\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e재무 추적\u003c/td\u003e\n          \u003ctd\u003e이번 달 지출 vs 예산\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e활동 로그\u003c/td\u003e\n          \u003ctd\u003e최신 시스템 변경사항\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"주요-사용자\"\u003e주요 사용자\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e사용자\u003c/th\u003e\n          \u003cth\u003e용도\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e보드 운영자\u003c/td\u003e\n          \u003ctd\u003e웹 UI에서 빠른 상태 확인\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eCEO 에이전트\u003c/td\u003e\n          \u003ctd\u003e하트비트 중 상황 인식\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003e매니저 에이전트\u003c/td\u003e\n          \u003ctd\u003e팀 상태 검토 및 병목 파악\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e","title":"대시보드 API"},{"content":"에이전트가 환경 설정에서 참조하는 암호화된 시크릿을 관리합니다.\n엔드포인트 메서드 경로 설명 GET /api/companies/{companyId}/secrets 시크릿 메타데이터 목록 (복호화된 값 아님) POST /api/companies/{companyId}/secrets 시크릿 생성 (저장 시 암호화) PATCH /api/secrets/{secretId} 시크릿 업데이트 (새 버전 생성) 시크릿 참조 에이전트 어댑터 설정에서 시크릿 ID와 버전을 지정하는 구조화된 형식으로 참조합니다.\n\u0026quot;version\u0026quot;: \u0026quot;latest\u0026quot;를 사용하면 자동으로 최신 값을 받습니다.\n작동 방식 서버가 런타임에 시크릿 참조를 해결하고 복호화하여, 실제 값을 에이전트 프로세스 환경에 주입합니다.\n이 접근법은 API 키 같은 민감한 자격증명을 평문 설정 파일에서 제외하면서도, 에이전트가 실행 중 안전하게 접근할 수 있게 합니다.\n","permalink":"https://jungwoo0716.github.io/docs/paperclip/48-%EC%8B%9C%ED%81%AC%EB%A6%BFapi/","summary":"\u003cp\u003e에이전트가 환경 설정에서 참조하는 암호화된 시크릿을 관리합니다.\u003c/p\u003e\n\u003ch2 id=\"엔드포인트\"\u003e엔드포인트\u003c/h2\u003e\n\u003ctable\u003e\n  \u003cthead\u003e\n      \u003ctr\u003e\n          \u003cth\u003e메서드\u003c/th\u003e\n          \u003cth\u003e경로\u003c/th\u003e\n          \u003cth\u003e설명\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eGET\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/secrets\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e시크릿 메타데이터 목록 (복호화된 값 아님)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePOST\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/companies/{companyId}/secrets\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e시크릿 생성 (저장 시 암호화)\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n          \u003ctd\u003ePATCH\u003c/td\u003e\n          \u003ctd\u003e\u003ccode\u003e/api/secrets/{secretId}\u003c/code\u003e\u003c/td\u003e\n          \u003ctd\u003e시크릿 업데이트 (새 버전 생성)\u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch2 id=\"시크릿-참조\"\u003e시크릿 참조\u003c/h2\u003e\n\u003cp\u003e에이전트 어댑터 설정에서 시크릿 ID와 버전을 지정하는 구조화된 형식으로 참조합니다.\u003c/p\u003e\n\u003cp\u003e\u003ccode\u003e\u0026quot;version\u0026quot;: \u0026quot;latest\u0026quot;\u003c/code\u003e를 사용하면 자동으로 최신 값을 받습니다.\u003c/p\u003e\n\u003ch2 id=\"작동-방식\"\u003e작동 방식\u003c/h2\u003e\n\u003cp\u003e서버가 런타임에 시크릿 참조를 해결하고 복호화하여, 실제 값을 에이전트 프로세스 환경에 주입합니다.\u003c/p\u003e\n\u003cblockquote\u003e\n\u003cp\u003e이 접근법은 API 키 같은 민감한 자격증명을 평문 설정 파일에서 제외하면서도, 에이전트가 실행 중 안전하게 접근할 수 있게 합니다.\u003c/p\u003e","title":"시크릿 API"},{"content":"김정우 (JungWoo Kim) 주식회사 스페이스바 (SPACEBAR Corp.) 대표이사\nAI SaaS, 커머스, 콘텐츠/미디어 사업을 운영하고 있습니다.\n기술과 비즈니스의 교차점에서 생각하고, 실행하고, 기록합니다.\n관심 분야 AI / SaaS — AI 에이전트, 자동화, SaaS 제품 개발 커머스 — 건강기능식품/화장품 유통 및 제조 투자 / 재무 — 기업 분석, 가치 평가, 재무제표 분석 교육 — AI 활용 교육, 기술 리터러시 연락처 Email: kimjungwoo0716@gmail.com GitHub: jungwoo0716 회사: SPACEBAR Corp. ","permalink":"https://jungwoo0716.github.io/about/","summary":"about","title":"About"}]