자동화

자동화는 일정에 따라 지시를 실행하고 결과를 일반 채팅 세션으로 전달합니다. 매일 뉴스 요약, 주간 검토, 월간 보고서 등 각 실행은 서버에서 헤드리스로 처리되고 채팅 목록에 추가되며, 다른 대화처럼 열어서 이어갈 수 있습니다.

구성

자동화에는 이름, 자유 형식 지시, 하나 이상의 트리거, 선택적 모델(비워 두면 Auto, 즉 실행 시점의 기본 채팅 모델), 실행 대상 및 알림 설정(앱 내 알림 또는 끄기)이 있습니다. 실행 대상에 따라 결과가 달라집니다. 채팅 세션(기본값)은 지시를 대화로 대기열에 넣고, Work 작업은 지시를 첫 메시지로 사용해 격리된 Work 샌드박스를 시작합니다. 양식에서 이름이 지정된 Work 정책을 선택적으로 지정할 수도 있습니다. 알림을 켜면 실패한 실행이 알림 받은편지함에도 전달되므로 자동화 페이지가 닫혀 있어도 실패를 확인할 수 있습니다. 별도로, 설정 → 알림 → 이메일 알림에서 자동화 실행 결과를 켜면 관리자가 발신 메일 서버를 설정한 뒤부터 모든 실행의 결과가 이메일로 전송됩니다(자세한 내용은 알림 참고). 이름과 지시는 저장 시 암호화됩니다. 모든 자동화는 만든 사용자에게 속합니다.

트리거는 캘린더의 공유 모델인 once, hourly, daily, weekly, monthly, yearly를 재사용하며 자동화 하나에 최대 5개를 둘 수 있습니다. 다음 실행은 서버의 로컬 시간대에서 계산한 모든 트리거 중 가장 이른 예정 시각입니다.

이벤트 트리거

일곱 번째 종류인 event는 시계가 전혀 없습니다. 사용자의 알림 중 하나가 도착하면 실행됩니다.

{ "kind": "event", "event": "channel-mention", "match": "release" }

event에는 automation-failed를 제외한 모든 알림 유형을 지정할 수 있습니다. 루틴이 자신의 실패 알림으로 스스로를 다시 실행할 수 있어서는 안 되기 때문입니다. 선택적인 match는 알림 제목에 대한 대소문자를 구분하지 않는 부분 문자열 검사입니다. 지정하지 않으면 해당 유형의 모든 알림이 루틴을 실행시킵니다.

이벤트 트리거는 다음 실행 시각에 전혀 기여하지 않습니다. 모든 트리거가 이벤트뿐인 자동화는 다음 실행이 표시되지 않으며, 목록과 편집 대화상자에는 대신 … 시 실행이 표시됩니다. 이벤트 트리거와 일정을 함께 사용해도 괜찮습니다. 예약된 트리거가 여전히 시계를 구동합니다.

두 가지 보호 장치가 파급 범위를 제한합니다. 루틴은 스트림이 아무리 바빠도 이벤트로는 분당 최대 한 번만 실행되며, 실행 자체의 실패 알림이 그 실행을 만든 루틴을 다시 실행시키지 않습니다.

실행은 자신을 실행시킨 내용을 지시에 덧붙여 전달받습니다.

---
Trigger payload (JSON):
{"event":"channel-mention","title":"...","body":"...","href":"..."}

실행

스케줄러 틱은 조정 임대 뒤에서 매분 실행되므로 복제본 하나만 일정을 진행합니다. 자동화 실행 시각이 되면 틱이 실행을 기록하고 영속 automation.run.v1 작업을 대기열에 넣은 뒤 compare-and-set으로 next_run_at을 진행시켜 각 발생 시점이 최대 한 번만 실행되게 합니다. 작업은 자동화 이름으로 채팅 세션을 만들고 모든 대화에서 사용하는 동일한 영속 채팅 생성 파이프라인에 지시를 대기열로 넣습니다. 제공자 라우팅, 페르소나 기본값 및 영속성도 포함됩니다.

발생 시점에 서버가 중단되어 있었다면 다음 틱은 그 발생 건을 한 번 실행하고 그보다 오래전에 놓친 슬롯은 건너뜁니다. 자동화를 일시 중지하면 일정이 지워지고, 다시 시작하거나 편집하면 현재 시각을 기준으로 다시 계산됩니다. 자동화를 삭제하면 외래 키 연쇄 삭제로 실행 기록도 제거됩니다.

실행은 영속 작업 원장에서 확정됩니다. 채팅 생성이 완료되면 성공, 작업이 데드 레터 처리되면 실패, 대기열의 실행이 30분 안에 시작되지 않으면 stalled 실패가 됩니다.

Work 대상 실행도 채팅 작업 대신 Work 수명 주기를 사용하여 같은 방식으로 작동합니다. 실행 기록에는 생성된 작업이 저장되고 실행 탭에서 바로 연결됩니다. 에이전트가 완료하거나 입력을 요청하기 위해 멈추면 성공하고, 작업이 실패하거나 취소되면 실패합니다. Work 대상 실행의 결과 이메일에는 Work 실행 자체가 저장한 요약, 즉 에이전트가 끝맺은 내용이자 작업의 실행 기록에 표시되는 것과 같은 텍스트가 담깁니다. 요약이 저장되기 전의 실행이라면 대신 작업의 한 줄 상태로 대체됩니다. 일정 실행 시 Work 접근 권한을 적용하므로 사용자의 Work 접근 권한을 철회하면 해당 Work 대상 자동화도 실행되지 않습니다. 이 경우 조용히 건너뛰지 않고 work-access-denied로 실패합니다. 선택한 정책은 자동화를 저장할 때 검증되며 네트워크 기본값과 리소스 제한이 자동화가 시작하는 모든 작업에 적용됩니다. Work에서는 직접 모델 제공자만 실행되며 모델이 도구를 지원해야 합니다. Work 작성기와 같은 규칙입니다.

에이전트 루틴

Work 대상 자동화는 대신 workTaskId를 통해 기존 Work 작업에 연결할 수 있습니다. 이는 에이전트 세부 정보 패널의 루틴 섹션에서 사용하는 형태입니다. 연결된 루틴은 실행할 때마다 새 작업을 만들지 않습니다. 각 발생 건은 해당 작업 자체의 워크스페이스와 대화 안에서 작업의 모델, 제공자 및 런타임 정책을 사용해 실행을 시작합니다. 따라서 자동화 수준의 모델과 정책 필드는 적용되지 않으며 지정된 정책은 저장 시 제거됩니다. 자동화를 저장할 때 연결을 검증합니다(작업이 존재하며 호출자 소유여야 함). 실행 시 작업이 삭제되어 있으면 work-task-missing으로 실패하고, 작업이 이미 실행 중이거나 활성 미리보기를 유지하고 있으면 뒤에 대기시키지 않고 해당 발생 건이 work-task-busy로 명확히 실패합니다.

Webhook 트리거

일정 외에도 CI 파이프라인, cron 서비스, 홈 오토메이션 같은 외부 시스템이 자동화를 실행시킬 수 있습니다. 자동화 편집 대화상자에서 Webhook 트리거 → 사용을 선택하면 자동화별 시크릿이 생성됩니다. 저장되는 값은 SHA-256뿐이므로 평문은 딱 한 번만 표시됩니다. 시크릿을 교체하면 이전 값은 즉시 무효가 되고, Webhook을 끄면 엔드포인트가 다시 닫힙니다.

외부 시스템은 다음과 같이 자동화를 실행시킵니다.

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..."

(X-Libre-Webhook-Secret: lwh_... 헤더도 대체 수단으로 쓸 수 있습니다.) 응답은 대기열에 들어간 실행 id와 함께 202이며, 지금 실행과 같은 수동 실행 경로를 지나므로 실행의 종료 처리, 알림, 기록 표시가 동일합니다. 시크릿 비교는 상수 시간으로 이루어지고, 존재하지 않는 자동화와 잘못된 시크릿은 똑같은 응답을 돌려주며(자동화 id를 알아낼 수 없음), 일시 중지된 자동화는 409를 반환합니다. 소유자의 지금 실행과 달리 외부 호출자는 일시 중지를 넘어 실행시킬 수 없습니다.

요청 본문의 JSON 객체는 트리거 페이로드로 실행에 실려 들어가므로, 루틴은 자신이 무엇에 반응하고 있는지 알 수 있습니다.

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..." \
  -H "Content-Type: application/json" \
  -d '{"commit":"abc123","branch":"main"}'

페이로드는 실행이 수행할 지시에 Trigger payload (JSON): 제목 아래로 덧붙여집니다. 채팅 실행, 새 Work 작업, 작업에 연결된 루틴 모두 마찬가지입니다. JSON 객체만 전달되며(배열과 스칼라 값은 무시됩니다), 직렬화한 형태가 4000자를 넘는 페이로드는 잘라내지 않고 아예 버려지며 서버 로그에 경고가 남습니다. 본문이 없는 실행은 이전과 똑같이 동작합니다.

API

Webhook 실행을 제외한 모든 엔드포인트는 인증이 필요하며 호출자 자신의 자동화만 다룹니다. Webhook 실행은 대신 자동화별 시크릿으로 인증합니다.

메서드	경로	용도
GET	/api/automations	자동화 목록 조회
POST	/api/automations	자동화 생성
GET	/api/automations/occurrences?from=&to=	계산된 예정 발생 건 조회
GET	/api/automations/runs	실행 기록(필터 가능)
GET	/api/automations/runs/summary	보지 않은 개수 + 30일 버킷
POST	/api/automations/runs/seen	완료된 실행을 확인함으로 표시
GET	/api/automations/:automationId	자동화 하나 조회
PUT	/api/automations/:automationId	자동화 업데이트
DELETE	/api/automations/:automationId	자동화 삭제
POST	/api/automations/:automationId/pause	일정 일시 중지
POST	/api/automations/:automationId/resume	일정 다시 시작
POST	/api/automations/:automationId/run	지금 실행(실행 id와 함께 202 반환)
POST	/api/automations/:automationId/webhook	시크릿으로 실행(202)
POST	/api/automations/:automationId/webhook-secret	시크릿 생성/교체
DELETE	/api/automations/:automationId/webhook-secret	Webhook 사용 중지

사용자 한 명이 유지할 수 있는 자동화는 최대 50개입니다. 이름은 200자, 지시는 20,000자로 제한됩니다.