주요 콘텐츠로 건너뛰기
AI 튜토리얼

Agent Autoloop 튜토리얼: Claude Code, Codex 등의 CLI 에이전트가 백그라운드에서 작업을 자동으로 받아 지속적으로 후속 처리하도록 설정하기

이 튜토리얼에서는 Agent Autoloop을 설치하고 첫 실행을 완료한 뒤, 예약 및 이벤트 규칙을 작성하는 방법과 수동 승인, 세션 재개, 플러그인 확장, 보안 메커니즘을 알아봅니다.

약 17분 소요
Agent Autoloop 튜토리얼: Claude Code, Codex 등의 CLI 에이전트가 백그라운드에서 작업을 자동으로 받아 지속적으로 후속 처리하도록 설정하기

Agent Autoloop이란?

Claude Code, Codex와 같은 명령줄 Agent는 일반적으로 터미널 앞에서 지속적으로 상호작용해야 합니다. 작업을 입력하고, 실행을 기다리고, 질문에 답한 뒤 계속 진행하도록 해야 합니다. 터미널이 닫히거나 사용자가 잠시 자리를 비우면 작업 흐름이 중단되는 경우가 많습니다.

Agent Autoloop은 명령줄 Agent를 위한 경량 자동화 허브입니다. 작업 스케줄링을 런타임 의존성이 없는 코어에 넣고, 이벤트 소스, Agent, 알림 채널 및 전달 파이프라인을 교체 가능한 플러그인으로 분리합니다. 로컬 Mac 또는 Linux 컴퓨터에서 실행할 수 있으며, 클라우드 서버를 구매하거나 공용 인터넷 포트를 개방할 필요가 없습니다.

핵심 동작 방식은 다음과 같습니다. 이벤트가 들어오면 규칙에 따라 Agent에 전달됩니다. Agent는 한 차례 작업을 완료하면 종료됩니다. 데이터 삭제, 서비스 재시작, 비용 지출 또는 외부 메시지 전송과 같은 불확실한 작업이 발생할 때만 시스템이 알림 카드를 통해 사용자에게 결정을 요청합니다. 사용자가 답변하면 기존 세션을 이어 받아 남은 작업을 완료합니다.

핵심 기능

  • 로컬 실행: macOS 또는 Linux 컴퓨터 한 대에 배포할 수 있으며, 별도의 클라우드 백엔드가 필요하지 않습니다.
  • 간편한 Agent 연동: 프롬프트를 받고 최종 답변을 출력할 수 있는 명령줄 도구라면 범용 명령 플러그인을 통해 연동할 수 있습니다.
  • 대기 중 Agent 사용량 0: 사람의 답변을 기다릴 때 Agent 프로세스가 즉시 종료되므로 Token을 계속 소비하지 않습니다. 대기 상태는 데이터베이스에 저장됩니다.
  • 규칙 기반: rules.json으로 어떤 이벤트를 어느 Agent에 전달할지, 어느 디렉터리에서 실행할지를 지정할 수 있어 접착 코드를 작성할 필요가 없습니다.
  • 필요할 때만 알림: 데스크톱 알림, Feishu, DingTalk, WeCom, Slack 및 Discord Webhook 템플릿을 지원합니다.
  • 세션 이어받기: 사용자가 답변한 후 기존 대화를 이어서 처리하므로 작업을 처음부터 반복하지 않습니다.
  • 추적 가능: 상태는 추가 전용 로그로 계산되며, 각 작업 라운드의 트리거 원인과 처리 결과를 조회할 수 있습니다.
  • 플러그인화: 이벤트 소스, Agent, 알림 채널 및 CI/CD 전달 흐름을 확장하거나 교체할 수 있습니다.

설치 전 준비

시작하기 전에 시스템이 macOS 또는 Linux인지 확인하고 다음 도구를 설치하세요.

  • Node 24
  • Git
  • curl
  • 설치 및 로그인이 완료된 명령줄 Agent 하나 이상(예: Claude Code 또는 Codex)

설치와 로컬 시험 실행에는 GitHub 계정이 필요하지 않습니다. Agent Autoloop은 컴퓨터에 이미 설치된 명령줄 도구를 직접 호출하며, 해당 도구의 계정 인증 정보를 읽거나 전송하지 않습니다.

1단계: Agent Autoloop 설치

터미널에서 공식 설치 스크립트를 실행하세요.

curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | sh

설치 세부 정보를 먼저 확인하려면 프로젝트의 설치 안내를 읽어 보세요. README에서는 이 안내를 로컬 Agent에 전달해 설치를 지원받는 방법도 권장합니다.

2단계: 최초 대화형 시험 실행

설치가 완료되면 다음을 실행하세요.

agent-autoloop try

이 명령은 로컬 Agent를 사용해 전체 흐름을 시연합니다. 작업을 전송하고, Agent가 질문한 뒤 종료하여 대기하고, 사용자의 결정을 받은 다음 세션을 이어서 작업을 완료합니다.

시험 실행 중에는 다음과 비슷한 결과가 표시됩니다.

이벤트가 전송되었고 Agent가 작업을 시작했습니다……

Agent가 이번 라운드를 종료하며 질문을 남겼습니다. 현재 프로세스를 점유하지 않으며 Token도 소비하지 않습니다.

【결정을 기다리는 중】#1 시험 실행: 색상 하나 선택
시험 실행이므로 어느 것을 선택해도 됩니다.
  1. 파란색
  2. 초록색

대화형 터미널에서는 옵션 번호를 바로 입력하고 Enter 키를 누르면 됩니다. 비대화형 터미널에서는 첫 번째 카드에 명시적으로 답하고 두 번째 옵션을 선택할 수 있습니다.

agent-autoloop answer 1 2

그런 다음 전체 상태를 조회하세요.

agent-autoloop status

정상적으로 작동하면 Agent가 기존 세션을 이어 받아 선택 결과를 확인하는 것을 볼 수 있습니다. 상태 명령은 당일 및 최근 7일의 실행 라운드 수, Token 및 비용 통계도 표시합니다.

3단계: 작업이 자동으로 실행되는 방식 이해

  1. 이벤트 유입: 예약 작업, GitHub Issue 또는 비즈니스 시스템 오류가 표준 이벤트로 변환됩니다.
  2. 규칙 매칭: 코어가 로컬 규칙에 따라 사용할 Agent와 작업 디렉터리를 결정합니다.
  3. 한 라운드 실행: Agent가 작업을 처리하고 마지막 답변에 결과를 설명한 뒤 프로세스를 종료합니다.
  4. 필요할 때 승인 요청: 사람의 판단이 필요한 작업이 있으면 허브가 알림 카드를 보내고 대기 상태를 저장합니다.
  5. 답변 후 이어서 실행: 사용자가 선택을 제출하면 시스템이 기존 대화를 복원하고 작업을 계속 완료합니다.

사람의 개입이 필요하지 않은 작업은 Agent가 바로 종료하거나 나중에 다시 확인하도록 예약할 수 있습니다. 또한 시스템은 대기 중 같은 작업에 새로 들어온 메시지를 통합하여 한 번의 작업 라운드에서 처리합니다.

4단계: 첫 번째 자동화 규칙 작성

일상적인 설정 파일은 다음 위치에 있습니다.

~/.agent-autoloop/rules.json

각 규칙에는 최소한 언제 트리거되는지, 누가 처리하는지, 어느 디렉터리에서 작업하는지를 지정해야 합니다. to에는 설정의 agents에 이미 존재하는 이름을 사용해야 합니다.

예시: 매일 오전 9시에 데일리 브리핑 생성

{
  "name": "데일리 브리핑",
  "when": { "cron": "0 9 * * *" },
  "to": "codex",
  "cwd": "~/notes",
  "prompt": "어제의 노트와 커밋을 정리하여 오늘의 데일리 브리핑을 작성하세요."
}

이 규칙은 매일 9시에 codex라는 Agent에 작업을 전달하고, ~/notes 디렉터리에서 노트와 Git 커밋을 정리하도록 합니다.

예시: 새로 생성된 GitHub Issue 처리

외부 이벤트 규칙의 구조도 비슷하지만, 먼저 sources에 해당 이벤트 소스를 등록해야 합니다. 다음 규칙은 GitHub의 issues.opened 이벤트를 감시합니다.

{
  "name": "이슈 처리",
  "when": {
    "source": "github",
    "types": ["issues.opened"]
  },
  "to": "codex",
  "cwd": "~/code/app",
  "skill": "handle-issue",
  "parallel": 3
}

skill은 작업 처리에 필요한 Skill을 지정하고, parallel은 병렬 실행 수를 3으로 설정합니다. 이벤트 소스 등록 방식은 프로젝트 설정 안내에 따라 진행해야 합니다.

규칙을 저장하면 몇 초 안에 자동으로 적용됩니다. 즉시 다음 명령을 실행해 확인하는 것이 좋습니다.

agent-autoloop check

새 규칙에 오류가 있으면 시스템은 기존 규칙을 계속 사용해 실행하고, 카드로 구체적인 문제를 알려 줍니다. 따라서 잘못된 설정이 기존 자동화를 바로 중단하지 않습니다.

5단계: Agent가 사람의 결정을 요청하도록 설정

Agent Autoloop이 Agent에 요구하는 핵심 사항은 마지막 답변에 결과를 설명하는 것입니다. 작업이 완료되었다면 결론을 정상적으로 출력하면 됩니다. 사람의 선택이 필요하다면 답변 끝에 agent-autoloop 영수증 코드 블록을 추가하세요.

주문 확인을 완료했으며 재고가 충분합니다.

```agent-autoloop
{
  "ask": [{
    "title": "어떻게 배송할까요?",
    "text": "두 가지 방법 모두 오늘 발송할 수 있습니다.",
    "options": ["택배", "방문 수령"],
    "key": "shipping"
  }]
}
```

여기서 ask는 두 가지 옵션이 포함된 결정 카드를 생성합니다. 질문 외에도 영수증은 다음 작업을 지원합니다.

  • notice: 알림을 보냅니다.
  • resolve: 이미 해결된 카드를 닫습니다.
  • later: 미래의 특정 시각에 다시 확인하도록 예약합니다.
  • events: 새 이벤트를 트리거합니다.

Agent가 출력한 JSON이 잘못되면 허브는 기존 세션에서 마지막 영수증 부분만 다시 작성하도록 요청합니다. 이미 완료된 비즈니스 작업을 다시 실행하지는 않습니다. 다시 작성하는 데에도 실패하면 시스템은 원래 결론을 보존하고 영수증이 적용되지 않았음을 알립니다.

기존 시나리오 템플릿 사용

프로젝트는 규칙, 작업 Skill 및 활성화 안내가 포함된 여러 템플릿을 제공하며, 실제 설정의 출발점으로 사용할 수 있습니다.

  • 일일 브리핑: 로컬 노트와 Git 커밋을 정리하고 날짜를 이름으로 사용하는 파일에 기록합니다.
  • GitHub Issue 후속 처리: 새 Issue를 정기적으로 확인하고 로컬에서 코드를 수정한 뒤 확인을 요청합니다. 기본적으로 커밋, 푸시 및 Issue 답변은 하지 않습니다.
  • 온라인 장애 알림 조사: 오류를 수신하고 코드와 대조하여 원인을 분석하며, 재시작 작업이 필요하면 먼저 승인을 요청합니다.
  • 사용자 피드백 처리: 피드백 상태를 확인하고 문제를 수정한 뒤 결과를 검증하고 답변을 준비합니다. 결정이 필요하면 Feishu를 통해 질문합니다.
  • 웹사이트 점검: 상태와 핵심 콘텐츠를 정기적으로 확인하고 지속적인 이상으로 인한 중복 알림을 방지하며, 복구 후 기존 카드를 업데이트합니다.
  • Feishu 주간 보고서 및 비즈니스 요약: 권한에 따라 보고서와 지정된 표를 읽고 전체 요약을 로컬에 저장하며, Feishu에는 짧은 내용만 보냅니다.
  • PR 자동 전달: 코드 리뷰부터 시작하여 CI를 기다리고 PR을 병합한 뒤 배포를 기다린 다음 온라인 버전을 확인합니다.

템플릿을 활성화하려면 작업 Skill을 사용하는 Agent의 skills 디렉터리에 넣고, 예시 규칙을 ~/.agent-autoloop/rules.json에 병합한 다음 경로와 컴퓨터 이름을 교체하고 agent-autoloop check를 실행해야 합니다.

README의 특별 안내: 피드백 처리, 웹사이트 점검 및 Feishu 요약에 포함된 샘플 데이터는 허구입니다. 관련 스크립트와 영수증은 로컬 HTTP 및 모의 Feishu CLI를 통해서만 검증되었으며, 실제 계정에서 전체 비즈니스 흐름을 테스트하지 않았습니다.

다양한 Agent 및 알림 채널 연동

내장 Agent 플러그인

프로젝트에는 Claude Code, Codex, ACP 및 범용 명령 플러그인이 내장되어 있습니다. Claude Code, Codex 및 공식 Codex ACP 어댑터는 여러 차례의 질의응답과 프로세스 간 세션 이어받기 테스트를 완료했습니다.

범용 명령으로 다른 Agent 연동

다른 명령줄 Agent의 경우 use: "command"를 설정하고 명령 배열을 제공할 수 있습니다. 자리 표시자 {prompt}는 독립적인 인수로 전달되며 Shell 코드로 실행되지 않습니다.

README에는 각 도구의 공식 문서를 바탕으로 DeepSeek Harness, pi, OpenClaw, Hermes, Cursor 및 WorkBuddy／CodeBuddy의 명령 예시가 정리되어 있습니다. 다만 이러한 명령은 아직 하나씩 실제 테스트되지 않았다는 점도 명시되어 있습니다. 따라서 정식으로 사용하기 전에 격리된 디렉터리에서 인수, 출력 형식 및 세션 동작을 먼저 검증해야 합니다.

서드파티 플러그인 설치

서드파티 플러그인은 Git 주소로 설치할 수 있습니다.

agent-autoloop add <git 주소>

직접 플러그인을 개발하려면 프로젝트에서 제공하는 최소 Agent, 채널 및 이벤트 플러그인 템플릿으로 시작하고 플러그인 개발 안내를 참고하세요.

알림 채널 선택

데스크톱 알림은 기본적으로 활성화되어 있습니다. Feishu에서는 전송, 버튼 콜백 및 카드 업데이트를 실제로 테스트했습니다. DingTalk, WeCom, Slack 및 Discord는 Webhook 템플릿을 사용하며, 현재 로컬 모의 서비스에서만 검증되었습니다.

이러한 텍스트 채널은 응답 링크를 통해 결정을 제출하므로 hub.publicUrl을 휴대폰이나 컴퓨터에서 접근할 수 있는 주소로 구성해야 합니다. 공용 네트워크 접근이 필요한지는 기본적인 로컬 실행 자체가 아니라 선택한 채널과 네트워크 환경에 따라 달라집니다.

고급 팁과 안정성 설계

특정 작업 라운드가 실행된 이유 조회

why 명령을 사용하면 지정한 라운드의 트리거 이벤트, 규칙 버전, 담당자 및 최종 결과를 확인할 수 있습니다.

agent-autoloop why 1

잘못된 규칙, 중복 이벤트 또는 예상치 못한 작업 할당을 조사할 때 특히 유용합니다.

네 가지 핵심 메커니즘 이해

  • 일시 중지 시 비용 없음: 사람의 응답을 기다리는 동안 Agent 프로세스는 종료되고 상태는 데이터베이스에 남습니다. 응답 후에는 기존 세션이 다시 시작됩니다.
  • 이벤트 소싱: 모든 상태는 추가 전용 로그에서 계산됩니다. 로그와 인덱스는 동일한 트랜잭션으로 디스크에 기록되며, 형식이 변경된 후에도 로그에서 상태를 재구성할 수 있습니다.
  • 명령과 데이터 분리: Issue 제목과 본문 같은 외부 콘텐츠는 자료로 저장되며 프롬프트에 직접 결합되지 않습니다. Agent, 작업 디렉터리 및 권한은 로컬 규칙으로만 결정됩니다. 이벤트의 cwd, agent, access 필드는 거부됩니다.
  • 홉 수 회로 차단: Agent가 트리거한 새 이벤트는 홉 수를 누적하며, 사람에게 묻는 작업과 예약된 재확인은 홉 수를 초기화하지 않습니다. 8단계를 초과하면 기록만 하고 작업을 계속 할당하지 않으며 사용자에게 카드를 보냅니다.

시뮬레이션 및 성능 테스트 실행

프로그램 디렉터리로 이동합니다.

cd ~/.agent-autoloop/app

그다음 README에 제공된 검증 명령을 실행할 수 있습니다.

node sim/random.ts 24301 200000
node sim/crash.ts 1000 12648430
npm run benchmark

첫 번째 명령은 네트워크 단절, 패킷 손실, 충돌 및 중복 제출을 시뮬레이션합니다. 두 번째 명령은 프로세스를 반복적으로 강제 종료하여 확인된 레코드가 손실되지 않는지 검사합니다. 세 번째 명령은 성능 벤치마크를 실행합니다. README의 기준선은 Apple M5 Pro, 24 GB 메모리 및 Node 24.21.0을 기준으로 하며, 다른 컴퓨터에서는 하드웨어 차이로 인해 기준을 충족하지 못한 것으로 표시될 수 있습니다.

과거 로그가 증가하면 상태 요약이 느려지고 로그와 인덱스가 디스크 공간을 계속 차지합니다. 데이터 형식이 변경된 후 첫 시작에서는 전체 재구성이 필요할 수 있으므로, 장기간 실행할 때는 디스크 공간과 시작 시간을 확인해야 합니다.

배포 파이프라인의 사용 범위

Agent Autoloop은 delivery 플러그인을 제공합니다. GitHub PR에 deliver 라벨을 추가하면 “코드 검토, CI 대기, PR 병합, 배포 대기, 운영 버전 확인” 순서로 지속적으로 후속 작업을 진행할 수 있습니다.

검토 및 배포 구성은 main 브랜치에서만 읽으며, 작업을 수락한 컴퓨터에서 PR의 코드를 체크아웃하거나 실행하지 않습니다. 대기열, 동시성 및 재시도는 동일한 핵심 메커니즘을 사용합니다. 정식으로 활성화하기 전에 저장소 권한과 릴리스 프로세스를 고려하여 보안 경계 설명을 읽어야 합니다.

사용량 및 규정 준수 권장 사항

모델 호출 비용은 본인 계정에 청구되며, 할당량과 사용 범위는 해당 모델 제공업체의 서비스 약관을 따릅니다. README에서는 빈번한 자동화 시나리오에 일반적으로 API Key를 사용하는 것이 더 적합하다고 안내합니다. 개인 구독 할당량은 주로 일상적인 수동 상호작용을 대상으로 합니다. 이 도구를 사용해 외부에 서비스를 제공하는 경우 API Key를 사용하고, 서비스 약관 및 규정 준수 요건을 직접 확인해야 합니다.

Agent Autoloop은 독립적인 오픈 소스 프로젝트이며 Anthropic, OpenAI 등 모델 제공업체와 소속 또는 보증 관계가 없습니다.

맺음말

Agent Autoloop의 핵심은 Agent를 영구적으로 실행하는 것이 아니라 작업을 안정적으로 일시 중지하고, 대기하고, 이어서 실행할 수 있도록 하는 데 있습니다. 먼저 agent-autoloop try로 상호작용의 전체 흐름을 검증한 다음, 매일 아침 보고서나 GitHub Issue 템플릿부터 규칙을 작성할 수 있습니다. 로컬 프로세스가 안정적으로 작동하는 것을 확인한 후 Feishu, Webhook, 외부 이벤트 및 PR 배포 파이프라인을 단계적으로 연결하십시오.

추가 구성은 규칙 및 배포 구성 매뉴얼, 전체 통신 프로토콜 및 플러그인 개발 문서를 참조하십시오.