이 문서는 멀티 에이전트 환경에서 크론잡을 설계·운영하는 사람이 반드시 확인해야 할 주의사항을 정리한 가이드입니다. 핵심 목적은 자동 실행은 되었지만 결과가 잘못된 대상에게 전달되는 사고를 줄이는 것입니다.

특히 여러 에이전트가 함께 동작하는 환경에서는, 단순히 작업이 성공했는지만 볼 것이 아니라 어느 에이전트가 실행했는지, 어느 계정으로 동작했는지, 누구에게 결과가 전달되는지를 사람이 명확하게 통제해야 합니다.

크론잡은 한 번 설정해두면 반복 실행됩니다. 따라서 설정이 잘못된 상태로 배포되면 같은 문제가 계속 반복될 수 있습니다.

멀티 에이전트 환경에서는 특히 아래와 같은 사고가 발생할 수 있습니다.

• A 사용자를 위한 결과가 B 사용자에게 전달됨
• 테스트용 메시지가 실제 운영 채널로 발송됨
• 다른 에이전트의 계정/설정을 참조해 잘못 동작함
• 대상 정보가 비어 있는데도 기본값으로 발송됨

이 문서는 이런 종류의 운영 실수를 예방하기 위한 사람 중심 체크리스트입니다.

크론잡은 누가 실행하느냐보다, 결과가 정확히 어디로 가느냐를 더 엄격하게 관리해야 합니다.

운영자가 반드시 지켜야 할 기본 원칙은 아래와 같습니다.

• 목적지 정보가 불명확하면 보내지 않는다.
• 기본값에 기대지 않는다.
• 최근 대화나 마지막 세션 정보를 재사용하지 않는다.
• 이름이 아니라 식별자 기준으로 목적지를 관리한다.
• 테스트와 운영 목적지를 절대 섞지 않는다.

즉, 애매하면 발송하지 않는 것이 일단 보내고 나중에 수정하는 것보다 훨씬 안전합니다.

가장 위험한 경우는 결과를 보낼 대상 정보가 빠져 있는데, 시스템이 임의의 기본값이나 이전 컨텍스트를 사용해 메시지를 보내는 경우입니다.

예시:

• chat_id 없이 발송
• accountId 없이 발송
• 대상 세션 정보 없이 마지막 세션에 의존

이 경우 운영자는 왜 저 사람에게 갔는지 원인을 추적하기 어렵고, 수신자는 예상하지 못한 메시지를 받게 됩니다.

처음에는 테스트 채널로 보내던 크론잡이, 설정 변경 후 운영 채널로 그대로 나가는 경우가 있습니다.

예시:

• 테스트용 목적지를 운영 목적지로 덮어씀
• 검증용 계정으로 만들었는데 실제 계정으로 전송됨

멀티 에이전트 환경에서는 비슷한 이름의 세션이나 설정이 존재할 수 있습니다. 이때 마지막 값 재사용 방식은 매우 위험합니다.

예시:

• 다른 에이전트의 accountId 사용
• 다른 세션의 delivery context 재사용
• 동일 이름 사용자 간 혼동

크론잡을 설계하거나 검토할 때 아래 정보는 필수 항목으로 봐야 합니다.

• 실행 에이전트 ID
• 채널 종류 (예: googlechat, discord, telegram)
• accountId
• 정확한 목적지 식별자 (chat_id 또는 sessionKey 등)
• 개인 대상인지 그룹 대상인지
• 목적지 누락 시 어떻게 처리할지
• 실패 시 재시도 여부
• 중복 발송 방지 기준

이 항목 중 하나라도 비어 있다면, 운영 관점에서는 완성되지 않은 크론으로 보는 것이 안전합니다.

사람 이름, 채널 이름, 별칭은 바뀌거나 중복될 수 있습니다. 가능하면 아래처럼 식별자를 직접 관리하는 편이 안전합니다.

• 이름보다 chat_id
• 별칭보다 sessionKey
• 감으로 아는 계정보다 accountId

목적지가 비어 있거나 애매한데도 발송되게 두면 사고 가능성이 큽니다. 운영자는 전송 실패를 두려워하기보다 오발송을 더 위험하게 봐야 합니다.

즉,

• 목적지 없음 → 발송 금지
• accountId 없음 → 발송 금지
• 채널 불명확 → 발송 금지

이런 규칙이 기본이어야 합니다.

테스트 중인 크론잡은 반드시 별도 목적지에서 검증해야 합니다.

권장 방식:

• 테스트용 채널 별도 운영
• 테스트용 accountId 별도 확인
• 실제 대상과 동일한 이름을 가진 테스트 대상을 만들지 않기

가능하면 크론잡을 아래처럼 나눠 생각하는 것이 좋습니다.

• 1단계: 정보 조회 / 분석 / 정리
• 2단계: 목적지 검증 / 발송

이렇게 하면 조회는 성공했더라도, 목적지 검증에 실패하면 발송만 중단할 수 있습니다.

아래 항목은 실제 배포 전에 반드시 사람이 확인해야 합니다.

• 이 크론은 어떤 에이전트가 실행하는가?
• 어떤 계정으로 메시지를 보내는가?
• 목적지 식별자가 정확히 입력되어 있는가?
• 목적지가 개인인지 그룹인지 명확한가?
• 목적지 정보가 없을 때 발송이 막히는가?
• 테스트 채널에서 먼저 검증했는가?
• 동일 메시지 중복 전송 방지 기준이 있는가?
• 문제가 생기면 즉시 중단할 수 있는가?

이 체크리스트를 통과하지 못하면 운영 배포를 보류하는 것이 안전합니다.

아래 방식은 편해 보여도 멀티 에이전트 환경에서는 사고 가능성이 높습니다.

• 최근 대화 상대를 목적지로 간주하는 방식
• 마지막 활성 세션을 재사용하는 방식
• 사람 이름만 보고 목적지를 고르는 방식
• 기본 계정에 의존하는 방식
• 테스트와 운영을 같은 채널에서 진행하는 방식
• 실패 원인 기록 없이 자동 재시도만 반복하는 방식

크론잡을 만들 때는 최소한 아래 수준으로 문서화하는 것이 좋습니다.

• 실행 에이전트: sungyong
• 채널: googlechat
• accountId: acc_sungyong
• 목적지 chat_id: googlechat:spaces/XXXXX
• 대상 유형: 개인 DM / 그룹 채널
• 목적지 누락 시 동작: 발송 금지 및 로그 기록
• 중복 방지 기준: 동일 키 1회만 전송
• 테스트 목적지: 별도 검증 채널 사용

이 문서화가 되어 있어야, 나중에 문제가 생겼을 때 운영자가 원인을 빠르게 추적할 수 있습니다.

멀티 에이전트 환경에서 크론잡 운영의 핵심은 자동 실행 자체가 아니라, 정확한 계정과 정확한 목적지로만 안전하게 보내는 것입니다.

특히 목적지 정보가 불명확한 상태에서는 보내지 않는 것이 기본 원칙이며, 이 원칙이 오발송과 운영 사고를 줄이는 가장 중요한 안전장치입니다.

OpenClaw 기반 크론잡은 세션이 길어지거나, 대화 이력이 누적되거나, 세션이 초기화되는 상황을 완전히 피할 수 없습니다. 이 경우 사람이 보기에는 분명했던 맥락이 실행 시점에는 충분히 남아 있지 않을 수 있습니다.

특히 아래와 같은 상황에서 문제가 커집니다.

• 세션이 재시작되어 이전 대화 맥락이 약해진 경우
• 대화가 너무 길어져 과거 지시가 뒤로 밀린 경우
• 크론 설명이 짧고 추상적으로만 적혀 있는 경우
• “전에 하던 방식대로” 같은 암묵적 지시에 의존하는 경우

이런 환경에서는 두루뭉술하게 작성된 크론잡일수록 실행 실패 확률이 높아집니다. 또는 실행은 되더라도 사람이 기대한 방식과 조금씩 다른 결과가 나올 수 있습니다.

이 문제를 줄이기 위한 가장 현실적인 방법은, 크론잡 자체를 짧게만 적어두는 것이 아니라 작업 기준을 매우 자세히 적은 매뉴얼 문서(MD)를 별도로 유지하고, 크론 실행 시 그 문서를 먼저 읽도록 지침에 포함하는 것입니다.

이 방식의 장점은 아래와 같습니다.

• 세션 상태와 관계없이 항상 동일한 기준을 다시 불러올 수 있음
• 과거 대화 기억에 덜 의존하게 됨
• 담당자가 바뀌어도 운영 기준이 유지됨
• 결과 품질 편차를 줄이고 균일성을 높일 수 있음
• 크론 설명문은 짧게 유지하면서도 실제 판단 기준은 상세하게 관리 가능함

즉, 크론 자체에는 무엇을 언제 실행할지를 적고, 별도 매뉴얼 문서에는 어떻게 판단하고 어떤 형식으로 결과를 만들지를 상세히 적는 구조가 바람직합니다.

크론잡이 참조할 매뉴얼 문서에는 최소한 아래 항목을 상세하게 적는 것이 좋습니다.

• 작업 목적
• 입력 데이터의 위치와 형식
• 반드시 확인해야 하는 전제 조건
• 예외 상황 처리 방식
• 결과 정리 형식
• 금지해야 할 행동
• 전송 대상과 전송 조건
• 실패 시 대응 방식
• 예시 입력 / 예시 출력
• 사람이 기대하는 문체 또는 보고 형식

가능하면 애매한 표현보다, 실행자가 그대로 따를 수 있는 수준으로 구체적으로 적는 것이 좋습니다.

좋지 않은 예:

• 최근 내용 보고 적절히 정리해서 보내기

좋은 예:

• 지정 문서 A를 먼저 읽고,
• 시트 B의 특정 범위를 확인한 뒤,
• 누락 행이 있으면 제외 사유를 기록하고,
• 결과는 3줄 요약 + 상세 항목 형식으로,
• 지정된 chat_id에만 전송하기

크론 설정 또는 지침에는, 실행 전에 특정 매뉴얼 문서를 반드시 읽도록 명시하는 것이 좋습니다.

예시 방향:

• 실행 전 지정된 MANUAL.md 문서를 먼저 읽을 것
• 과거 대화 맥락에 의존하지 말고 문서 기준으로 판단할 것
• 문서에 없는 사항은 추정하지 말고 보수적으로 처리할 것
• 목적지 정보가 누락되면 전송하지 말 것

핵심은, 크론이 기억에 기대지 않고 문서화된 기준에 기대도록 설계하는 것입니다.

이 방식을 적용하면 아래와 같은 효과를 기대할 수 있습니다.

• 세션 길이에 따른 품질 흔들림 감소
• 재시작 이후에도 동일한 기준 유지
• 운영자 의도와 결과물 간 편차 축소
• 신규 담당자 인수인계 용이
• 크론 실행 실패 및 오해석 가능성 감소

특히 정기 실행 작업은 한 번 잘 되는 것보다 매번 비슷한 품질로 안정적으로 동작하는 것이 중요하므로, 문서 기반 실행 방식이 장기적으로 더 안전합니다.

복잡한 작업을 한 번의 크론 실행 안에서 모두 처리하려고 하면, 중간 판단이 많아지고 예외 상황이 늘어나면서 실패 확률이 높아집니다.

특히 아래와 같은 작업은 단일 단계로 처리할수록 불안정해질 가능성이 큽니다.

• 여러 데이터 소스를 동시에 읽어야 하는 작업
• 조회 → 정리 → 판단 → 전송이 모두 포함된 작업
• 표 분리, 문서 읽기, 예외 처리, 보고 형식 결정이 함께 필요한 작업
• 사람마다 다른 목적지나 다른 기준을 적용해야 하는 작업

이런 유형은 가능한 한 업무 단계를 나누어 쪼개서 설계하는 것이 좋습니다.

복잡한 작업을 단계별로 나누면 아래와 같은 장점이 있습니다.

• 각 단계의 역할이 명확해집니다.
• 어느 단계에서 실패했는지 원인 추적이 쉬워집니다.
• 중간 결과를 검증할 수 있습니다.
• 발송 단계 전에 검토/차단이 가능합니다.
• 세션 컨텍스트가 짧아져도 각 단계의 목적이 덜 흔들립니다.
• 동일한 로직을 다른 크론에서도 재사용하기 쉬워집니다.

즉, 한 번에 다 하게 하는 방식보다 잘게 나눈 뒤 순서대로 처리하는 방식이 안정성과 재현성 측면에서 유리합니다.

복잡한 크론잡은 보통 아래처럼 나누어 생각하는 것이 좋습니다.

• 1단계: 데이터 조회
• 2단계: 데이터 정리 / 전처리
• 3단계: 해석 / 판단
• 4단계: 결과 포맷팅
• 5단계: 목적지 검증 후 발송

모든 작업이 반드시 5단계일 필요는 없지만, 최소한 조회와 발송은 분리하는 것이 안전합니다.

예를 들어, 여러 표가 섞여 있는 Google 스프레드시트를 읽고 요약 보고를 보내는 크론이 있다고 가정합니다.

좋지 않은 방식:

• 스프레드시트를 읽는다
• 여러 표를 한 번에 해석한다
• 바로 요약을 만든다
• 곧바로 메시지를 발송한다

이 방식은 중간 검증이 어렵고, 표 구조를 잘못 읽었을 때 오해석된 결과가 그대로 발송될 가능성이 있습니다.

권장 방식:

• 1단계: 시트를 읽고 ◆ 기준으로 큰 표를 분리한다
• 2단계: 각 표 안에서 ▶, ■, ▷ 기준으로 내부 구조를 다시 정리한다
• 3단계: 표별 요약 데이터를 만든다
• 4단계: 표별 요약을 최종 보고 형식으로 합친다
• 5단계: 목적지와 accountId를 검증한 뒤 발송한다

이렇게 나누면, 어느 단계에서 오류가 났는지 확인하기 쉽고, 문제 발생 시 발송 전에 멈출 수 있습니다.

예를 들어 매일 특정 데이터를 확인해 이상 징후가 있을 때만 알림을 보내는 크론의 경우에도, 한 번에 처리하기보다 아래처럼 나누는 것이 좋습니다.

권장 방식:

• 1단계: 원본 데이터 조회
• 2단계: 기준값과 비교해 예외 후보 추출
• 3단계: 예외 후보 중 실제 알림 대상만 선별
• 4단계: 알림 문구 생성
• 5단계: 전송 대상 검증 후 발송

이렇게 하면 이상치 탐지와 메시지 발송이 분리되므로, 탐지 로직만 수정하거나 발송 단계만 별도 점검하기가 쉬워집니다.

크론잡 설명이나 매뉴얼 문서도, 작업을 한 문단으로 뭉뚱그려 적기보다 단계별로 적는 편이 좋습니다.

좋지 않은 예:

• 매일 아침 데이터를 확인해서 적당히 요약하고 필요한 사람에게 보내기

권장 예:

• 1단계: 문서 A와 시트 B를 읽기
• 2단계: 누락 행과 예외 행을 분리하기
• 3단계: 예외 행만 기준 규칙으로 재분류하기
• 4단계: 지정된 형식으로 보고문 만들기
• 5단계: 목적지 식별자를 검증한 뒤 전송하기

이런 식으로 문서화하면, 실행 주체가 사람이든 에이전트든 동일한 순서로 작업을 재현하기 쉬워집니다.

복잡한 크론잡은 한 번에 처리하게 만들수록 실패 확률이 높아집니다. 반대로 작업을 단계별로 잘게 나누면, 원인 추적, 중간 검증, 예외 처리, 발송 통제가 쉬워져 안정성이 올라갑니다.

따라서 복잡한 자동화 작업일수록 한 개의 큰 지시보다 잘게 쪼갠 여러 단계의 지시로 설계하는 것이 권장됩니다.