OpenClaw 멀티 에이전트에서 응답이 없거나 다른 대화로 결과가 간다면, 에이전트를 더 추가하기 전에 요청이 어느 단계까지 도착했는지 확인하세요. 이 글은 2026년 4월 1일 운영 기록을 바탕으로 역할 분리, 설정 변경, 장애 복구의 점검 순서를 안내합니다.
설정 키와 명령은 버전에 따라 달라질 수 있습니다. 아래 예시는 그대로 복사하는 완성 설정이 아니라 구조를 설명하기 위한 자료입니다. 실제 변경 전에는 현재 설치 버전의 공식 문서와 도움말을 확인하고 설정 파일을 백업하세요.
에이전트를 늘리기 전에 병목부터 찾습니다
에이전트 수가 많다고 자동으로 처리량이 늘지는 않습니다. 같은 계정, 같은 브라우저 세션, 같은 데이터베이스를 공유하면 충돌 지점만 늘어날 수 있습니다. 먼저 오래 걸리는 작업, 높은 권한이 필요한 작업, 정기 실행 작업을 구분합니다.
| 분리 기준 | 확인할 질문 | 분리 효과 |
|---|---|---|
| 실행 시간 | 긴 작업이 대화를 막고 있는가 | 대화와 배치 작업의 대기열 분리 |
| 권한 | 읽기 전용 작업에 쓰기 권한이 필요한가 | 실수의 영향 범위 축소 |
| 도구 | 특정 채널·브라우저·서버만 쓰는가 | 불필요한 도구 접근 제한 |
| 비용 | 모든 작업에 같은 모델이 필요한가 | 작업별 모델과 예산 분리 |
역할보다 소유 범위를 먼저 적습니다
메인, 분석, 기록처럼 이름을 정하는 것보다 각 에이전트가 무엇을 읽고 바꿀 수 있는지를 적는 편이 중요합니다. 작업 폴더, 도구, 채널, 저장 위치를 겹치지 않게 나누고 공유 자원에는 한 명의 쓰기 담당자를 둡니다.
설정 전에 남길 최소 항목
- 에이전트 식별자와 담당 작업
- 허용 도구와 금지 도구
- 읽기·쓰기 가능한 파일 및 서비스 범위
- 결과를 돌려줄 채널과 대화
- 완료·실패·취소 시 정리할 세션
- 동시 실행 수와 작업별 비용 한도
텔레그램 봇 토큰이나 API 키는 예시 설정, 스크린샷, Git 저장소에 넣지 않습니다. 채널을 여러 개 연결할 때는 어느 계정의 메시지를 어느 에이전트가 처리하는지 매핑하고, 허용된 발신자와 응답 위치를 별도로 검증합니다.
설정 변경은 백업·검증·재시작 순서로
설정 파일을 직접 수정한다면 먼저 실제 설정 위치를 확인하고 사본을 만듭니다. 아래는 설정 위치가 현재 설치와 같을 때의 백업·상태 조회 예시입니다. 설정 문법은 설치 버전이 지원하는 검증 방법으로 따로 확인합니다.
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup-$(date +%Y%m%d-%H%M%S)
openclaw statusJSON5 주의: 2026-09-10에 확인한 OpenClaw 공식 설정 문서는 설정 형식을 JSON5로 안내합니다. 원본 예시의 python3 -m json.tool은 순수 JSON 검사이므로 주석 등 JSON5 문법이 있는 정상 설정을 오류로 판단할 수 있습니다. 이 오류만으로 설정을 고치지 말고, 설치 버전이 제공하는 설정 검증과 실제 로드 결과를 확인하세요. 이 혼동을 줄이기 위해 순수 JSON 검사 명령은 위 기본 절차에서 제외했습니다.
문법 검사 통과는 설정 값이 올바르다는 뜻이 아닙니다. 존재하지 않는 모델명, 잘못된 작업 폴더, 중복된 채널 바인딩은 별도로 확인해야 합니다. 자동 수정 옵션은 변경 내용을 검토하고 복원 방법을 확보한 뒤에만 사용합니다.
장애는 관찰된 범위부터 좁힙니다
1. 프로세스와 게이트웨이 상태
먼저 전체 서비스를 재설치하지 말고 현재 상태와 최근 로그를 확인합니다.
openclaw status
openclaw gateway status
openclaw logs --follow명령 이름이 현재 버전에서 지원되는지 openclaw --help와 하위 명령 도움말로 확인하세요. 로그를 외부에 공유할 때는 토큰, 사용자 ID, 내부 경로와 대화 내용을 제거합니다.
2. 채널은 수신·처리·발신을 나눠 확인
- 봇 또는 채널 계정이 활성 상태인지
- 보낸 사람이 허용 목록에 포함되는지
- 메시지가 올바른 에이전트에 바인딩되는지
- 처리는 끝났지만 발신 단계에서 실패한 것은 아닌지
확인 없이 토큰을 재발급하면 정상 연결까지 끊을 수 있습니다. 오류 코드와 발생 시각을 먼저 기록한 뒤 필요한 자격 증명만 교체합니다.
한 요청을 기준으로 장애 구간을 추적합니다
테스트 요청 하나의 시각과 원래 대화를 정한 뒤 아래처럼 관찰을 연결합니다. 여러 채널을 동시에 시험하면 어느 요청의 결과인지 다시 혼동할 수 있습니다.
| 관찰된 상태 | 먼저 볼 항목 | 피할 조치 |
|---|---|---|
| 수신 흔적이 없음 | 채널 계정 상태와 허용 발신자 | 모델을 무작정 교체 |
| 수신됐지만 다른 에이전트가 처리 | 해당 대화의 바인딩과 소유 범위 | 모든 세션 초기화 |
| 처리가 시작됐지만 완료 근거 없음 | 실행 세션, 도구 오류, 부분 결과 | 같은 쓰기 작업을 즉시 재실행 |
| 완료됐지만 답변이 안 보임 | 발신 오류와 원래 대화 참조 | 완료된 분석·편집을 다시 수행 |
긴 실행 자체가 병목이면 상시 수신과 세션형 작업 분리 사례를 참고하세요. 응답은 돌아오지만 행동 규칙이 어긋나는 경우에는 채널 장애와 구분해 지침 우선순위와 승인 경계를 점검합니다.
3. 응답 품질 문제는 세션과 지침을 구분
맥락을 잊거나 규칙을 따르지 않는 문제는 세션 길이, 작업 지침 파일, 모델 변경, 도구 실패 등 원인이 다를 수 있습니다. 세션 초기화는 대화 맥락을 지우므로 중요한 결정과 미완료 작업을 먼저 기록합니다. 작업 공간 파일이 남는지 또한 현재 설정에서 확인해야 합니다.
테스트 메시지도 전송 작업입니다
2026년 4월 1일 운영 점검 일기에는 게이트웨이 복구 확인용 하트비트 메시지가 사용자 Telegram 대화로 직접 전송된 실수가 남아 있습니다. 따라서 채널 테스트 대상과 발송 승인은 복구 전에 정하고, 가능하면 별도 테스트 대화에서 요청 하나만 추적해야 합니다.
같은 날 기록된 LaunchAgent의 entry.js/index.js 불일치는 프로세스 실행 경로 문제였고, 고아 세션 8개 정리는 별개 작업이었습니다. 두 조치를 한꺼번에 복구 처방으로 복사하지 말고 현재 서비스 정의의 파일 경로와 실제 파일 존재 여부부터 읽기 전용으로 대조합니다. 자동 수정으로 지운 파일 수가 채널 복구의 증거는 아닙니다.
복구 뒤에는 같은 조건으로 재검증합니다
| 확인 항목 | 완료 근거 |
|---|---|
| 설정 | 문법 검사와 현재 버전의 설정 로드 성공 |
| 채널 | 허용된 테스트 메시지 1건의 수신·응답 확인 |
| 도구 | 에이전트별 허용·차단 동작 확인 |
| 동시 작업 | 공유 파일과 대화가 섞이지 않는지 확인 |
| 비용 | 작업별 모델과 사용량이 의도와 일치 |
| 정리 | 완료된 브라우저·프로세스·임시 파일 정리 |
재시작 후 한 번 응답했다는 사실만으로 복구가 끝난 것은 아닙니다. 장애가 발생한 원래 경로를 가장 작은 테스트로 다시 실행하고, 예상 결과와 로그를 함께 남깁니다.
사례 기준일: 2026-04-01. 2026-09-03 재구성, 2026-09-10 JSON5 제한과 판단 절차 보완. 최신 버전의 명령·설정 키와 현재 운영 상태는 재검증하지 않았습니다.
편집: 2026-09-13. 기존 기록의 구조를 정리한 것으로 새 실행·성능 시험이나 현재 서비스 상태 확인을 뜻하지 않습니다.
정정: 2026-09-27. JSON5 형식과 혼동을 만드는 순수 JSON 검사 명령을 기본 예시에서 제외했습니다. 새 실행 성공을 추가한 것은 아닙니다.