OpenClaw 멀티 에이전트 운영과 장애 점검 순서

OpenClaw 멀티 에이전트에서 응답이 없거나 다른 대화로 결과가 간다면, 에이전트를 더 추가하기 전에 요청이 어느 단계까지 도착했는지 확인하세요. 이 글은 2026년 4월 1일 운영 기록을 바탕으로 역할 분리, 설정 변경, 장애 복구의 점검 순서를 안내합니다.

설정 키와 명령은 버전에 따라 달라질 수 있습니다. 아래 예시는 그대로 복사하는 완성 설정이 아니라 구조를 설명하기 위한 자료입니다. 실제 변경 전에는 현재 설치 버전의 공식 문서와 도움말을 확인하고 설정 파일을 백업하세요.

에이전트를 늘리기 전에 병목부터 찾습니다

에이전트 수가 많다고 자동으로 처리량이 늘지는 않습니다. 같은 계정, 같은 브라우저 세션, 같은 데이터베이스를 공유하면 충돌 지점만 늘어날 수 있습니다. 먼저 오래 걸리는 작업, 높은 권한이 필요한 작업, 정기 실행 작업을 구분합니다.

분리 기준	확인할 질문	분리 효과
실행 시간	긴 작업이 대화를 막고 있는가	대화와 배치 작업의 대기열 분리
권한	읽기 전용 작업에 쓰기 권한이 필요한가	실수의 영향 범위 축소
도구	특정 채널·브라우저·서버만 쓰는가	불필요한 도구 접근 제한
비용	모든 작업에 같은 모델이 필요한가	작업별 모델과 예산 분리

역할보다 소유 범위를 먼저 적습니다

메인, 분석, 기록처럼 이름을 정하는 것보다 각 에이전트가 무엇을 읽고 바꿀 수 있는지를 적는 편이 중요합니다. 작업 폴더, 도구, 채널, 저장 위치를 겹치지 않게 나누고 공유 자원에는 한 명의 쓰기 담당자를 둡니다.

설정 전에 남길 최소 항목

에이전트 식별자와 담당 작업
허용 도구와 금지 도구
읽기·쓰기 가능한 파일 및 서비스 범위
결과를 돌려줄 채널과 대화
완료·실패·취소 시 정리할 세션
동시 실행 수와 작업별 비용 한도

텔레그램 봇 토큰이나 API 키는 예시 설정, 스크린샷, Git 저장소에 넣지 않습니다. 채널을 여러 개 연결할 때는 어느 계정의 메시지를 어느 에이전트가 처리하는지 매핑하고, 허용된 발신자와 응답 위치를 별도로 검증합니다.

설정 변경은 백업·검증·재시작 순서로

설정 파일을 직접 수정한다면 먼저 실제 설정 위치를 확인하고 사본을 만듭니다. 다음은 원래 기록의 명령이며, 위치와 파일명이 현재 설치와 같고 설정 내용이 순수 JSON일 때의 예시입니다.

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup-$(date +%Y%m%d-%H%M%S)
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null
openclaw status

JSON5 주의: 2026-09-10에 확인한 OpenClaw 공식 설정 문서는 설정 형식을 JSON5로 안내합니다. 원본 예시의 python3 -m json.tool은 순수 JSON 검사이므로 주석 등 JSON5 문법이 있는 정상 설정을 오류로 판단할 수 있습니다. 이 오류만으로 설정을 고치지 말고, 설치 버전이 제공하는 설정 검증과 실제 로드 결과를 확인하세요. 위 원본 명령은 이 제한과 함께 보존했습니다.

문법 검사 통과는 설정 값이 올바르다는 뜻이 아닙니다. 존재하지 않는 모델명, 잘못된 작업 폴더, 중복된 채널 바인딩은 별도로 확인해야 합니다. 자동 수정 옵션은 변경 내용을 검토하고 복원 방법을 확보한 뒤에만 사용합니다.

장애는 관찰된 범위부터 좁힙니다

1. 프로세스와 게이트웨이 상태

먼저 전체 서비스를 재설치하지 말고 현재 상태와 최근 로그를 확인합니다.

openclaw status
openclaw gateway status
openclaw logs --follow

명령 이름이 현재 버전에서 지원되는지 openclaw --help와 하위 명령 도움말로 확인하세요. 로그를 외부에 공유할 때는 토큰, 사용자 ID, 내부 경로와 대화 내용을 제거합니다.

2. 채널은 수신·처리·발신을 나눠 확인

봇 또는 채널 계정이 활성 상태인지
보낸 사람이 허용 목록에 포함되는지
메시지가 올바른 에이전트에 바인딩되는지
처리는 끝났지만 발신 단계에서 실패한 것은 아닌지

확인 없이 토큰을 재발급하면 정상 연결까지 끊을 수 있습니다. 오류 코드와 발생 시각을 먼저 기록한 뒤 필요한 자격 증명만 교체합니다.

한 요청을 기준으로 장애 구간을 추적합니다

테스트 요청 하나의 시각과 원래 대화를 정한 뒤 아래처럼 관찰을 연결합니다. 여러 채널을 동시에 시험하면 어느 요청의 결과인지 다시 혼동할 수 있습니다.

관찰된 상태	먼저 볼 항목	피할 조치
수신 흔적이 없음	채널 계정 상태와 허용 발신자	모델을 무작정 교체
수신됐지만 다른 에이전트가 처리	해당 대화의 바인딩과 소유 범위	모든 세션 초기화
처리가 시작됐지만 완료 근거 없음	실행 세션, 도구 오류, 부분 결과	같은 쓰기 작업을 즉시 재실행
완료됐지만 답변이 안 보임	발신 오류와 원래 대화 참조	완료된 분석·편집을 다시 수행

긴 실행 자체가 병목이면 상시 수신과 세션형 작업 분리 사례를 참고하세요. 응답은 돌아오지만 행동 규칙이 어긋나는 경우에는 채널 장애와 구분해 지침 우선순위와 승인 경계를 점검합니다.

3. 응답 품질 문제는 세션과 지침을 구분

맥락을 잊거나 규칙을 따르지 않는 문제는 세션 길이, 작업 지침 파일, 모델 변경, 도구 실패 등 원인이 다를 수 있습니다. 세션 초기화는 대화 맥락을 지우므로 중요한 결정과 미완료 작업을 먼저 기록합니다. 작업 공간 파일이 남는지 또한 현재 설정에서 확인해야 합니다.

복구 뒤에는 같은 조건으로 재검증합니다

확인 항목	완료 근거
설정	문법 검사와 현재 버전의 설정 로드 성공
채널	허용된 테스트 메시지 1건의 수신·응답 확인
도구	에이전트별 허용·차단 동작 확인
동시 작업	공유 파일과 대화가 섞이지 않는지 확인
비용	작업별 모델과 사용량이 의도와 일치
정리	완료된 브라우저·프로세스·임시 파일 정리

재시작 후 한 번 응답했다는 사실만으로 복구가 끝난 것은 아닙니다. 장애가 발생한 원래 경로를 가장 작은 테스트로 다시 실행하고, 예상 결과와 로그를 함께 남깁니다.

운영 원칙

멀티 에이전트의 장점은 에이전트 수가 아니라 책임과 실패 범위를 분리하는 데 있습니다. 추가하기 전에 소유 범위, 권한, 결과 위치, 비용, 종료 조건을 적고, 장애 때는 상태 확인에서 시작해 설정·채널·세션 순으로 범위를 좁히는 편이 안전합니다.

사례 기준일: 2026-04-01. 기존 운영 기록을 바탕으로 2026-09-03에 재구성했습니다. 이 글을 위해 최신 OpenClaw 버전의 모든 명령과 설정 키를 다시 실행 검증하지 않았으며, 현재 설치 환경에서는 공식 문서와 도움말을 우선 확인해야 합니다.

편집 보완: 2026-09-10. 기존 사례와 작성·재편집 날짜를 유지하며 판단 절차와 관련 글을 보강했습니다. 이 날짜는 새 설치·성능 시험 또는 현재 운영 상태 확인을 뜻하지 않습니다.