02. OpenClaw 에이전트가 bootstrapPending에서 멈출 때, 20분 복구 루틴

openclaw status를 보면 Agents 항목에 bootstrapping 숫자가 보이는데, 여기서 오래 멈추면 보통 “에이전트가 고장났다”고 느끼기 쉽습니다. 실제 현장에서는 고장보다 초기 세션 미생성, 실행 루트 혼선, 상태 확인 순서 누락이 원인인 경우가 훨씬 많습니다. 아래 루틴대로 하면 20분 안에 대부분 원인을 분리하고 복구할 수 있습니다.

안내: 이 문서는 생성형 AI를 활용해 초안을 작성했고, 공식 문서와 실제 운영 로그 패턴을 기준으로 정리했습니다.

flowchart LR
A[status에서 bootstrapping 확인] --> B[게이트웨이/에이전트 상태 분리 점검]
B --> C[스모크 실행으로 초기 세션 생성]
C --> D[로그 확인 + 재검증]
D --> E[재발 방지 설정]

🧠 칠판 치트시트

bootstrapping은 “죽음”이 아니라 “초기화 대기”인 경우가 많다

먼저 status → agents list → gateway status 순서로 분리 진단

그다음 대상 에이전트에 스모크 메시지 1회 보내 세션을 깨운다

마지막은 status 재확인 + 로그 한 줄 검증으로 닫는다

어디서 막히는지 먼저 구분하기

같은 bootstrapPending처럼 보여도 원인은 크게 세 갈래입니다.

상태 표기 이슈: 오래된 세션 정보가 남아 부팅 대기처럼 보이는 경우
실행 이슈: 해당 에이전트가 실제로 한 번도 턴을 받지 못한 경우
운영 이슈: heartbeat/cron이 꺼져 있어 자동 점검 루프가 없는 경우

아래 명령은 OpenClaw 공식 CLI 기준 점검 순서입니다.

status: https://docs.openclaw.ai/cli/status
agents: https://docs.openclaw.ai/cli/agents
gateway: https://docs.openclaw.ai/cli/gateway

openclaw status
openclaw agents list
openclaw gateway status

20분 복구 루틴 (실행 순서 고정)

0~5분: 전체 상태 스냅샷

openclaw status

여기서 Agents 줄의 N bootstrapping 숫자를 먼저 메모합니다. 복구 후 이 숫자가 줄거나, 대상 에이전트가 실제 세션을 만들면 1차 성공 신호입니다.

5~10분: 대상 에이전트 실재 여부 확인

openclaw agents list

에이전트가 목록에 있어도 “실행된 적이 없는 상태”일 수 있습니다. 이 구간에서는 삭제/재설치보다 먼저 스모크 실행이 우선입니다.

10~15분: 스모크 메시지로 초기 세션 강제 생성

openclaw agent --agent youtube-analyzer --message "AGENT_OK" --json
openclaw agent --agent youtube-planner --message "PLANNER_OK" --json

실제 운영 에이전트 ID로 바꿔 실행하세요.
JSON 응답에 에러가 없고 응답 본문이 생성되면 “초기화 완료”로 봅니다.
agent 명령 공식 문서: https://docs.openclaw.ai/cli/agent

15~20분: 로그/상태 재검증

openclaw status
openclaw logs --follow

status에서 bootstrapping 수치가 정리되는지 확인
logs --follow에서 반복 에러가 없는지 1~2분 관찰

현장형 미니 사례 2개

사례 A (실패 → 성공 전환)

증상: status에 bootstrapping이 계속 4로 고정.
실패 원인: agents 목록만 보고 “정상”으로 판단하고 종료.
전환 포인트: 대상 에이전트에 스모크 메시지를 보내자 세션이 생성되고 상태가 정리됨.

사례 B (재발)

증상: 한 번 복구했는데 다음날 다시 같은 경고.
원인: heartbeat/cron이 꺼져 있어서 미가동 상태를 자동 감지하지 못함.
해결: 최소 1개 점검용 cron(또는 heartbeat)을 켜고, 실패 시 알림 채널을 팀 방으로 고정.

15분 빠른 도입 루틴 (팀 공유용)

openclaw status 캡처
openclaw agents list로 대상 에이전트 ID 확인
에이전트별 스모크 실행 1회
openclaw status 재확인
openclaw logs --follow 1분 관찰 후 종료

이 5단계를 운영 위키에 붙여두면, 담당자가 바뀌어도 같은 순서로 복구가 가능합니다.

복구 완료 판정 체크리스트

openclaw status에서 bootstrapping 상태가 줄거나 정리되었는가
대상 에이전트 스모크 실행이 정상 응답을 반환했는가
로그에서 반복 에러가 멈췄는가
다음 점검 루프(heartbeat/cron)가 활성화되어 있는가

다음 읽기

운영 메모: 위 명령은 버전에 따라 출력 형식이 달라질 수 있으니, 실행 전 openclaw help와 공식 문서를 함께 확인하세요.

일하는 ai

탐색기