에이전트가 지금 살아 있나 — OpenClaw가 흩어진 상태를 한 화면(Overview)에 모은 방법

오픈소스 개인 AI 어시스턴트 OpenClaw를 집 서버에 올려 두고 텔레그램·디스코드 같은 메신저로 부려 쓰다 보면, 어느 순간 이런 질문이 떠오른다 — "지금 얘가 살아 있긴 한가?" 메신저로 말을 걸어도 답이 없을 때, 그게 게이트웨이(메시지를 받는 중앙 프로세스)가 죽은 건지, 모델 인증이 만료된 건지, 예약 작업이 실패한 건지, 그냥 다른 작업을 하느라 바쁜 건지 알 길이 없다. OpenClaw의 Control UI(브라우저로 게이트웨이를 조작하는 관리 화면)는 이 질문에 답하는 첫 화면으로 Overview(개요) 메뉴를 둔다. 이 글은 "여러 프로세스·세션·작업이 동시에 도는 에이전트의 상태를, 한 화면에서 위에서 아래로 읽히게 어떻게 쌓았나"를 따라간다.

배경 — 에이전트의 상태는 원래 여러 곳에 흩어져 있다

OpenClaw 같은 AI 에이전트는 하나의 단순한 프로그램이 아니다. 메신저 메시지를 듣는 게이트웨이, 토큰·달러로 쌓이는 사용량, 사용자마다 이어지는 대화인 세션, 에이전트가 쓰는 스킬(기능 묶음), 예약 작업을 돌리는 cron, 그리고 모델 제공자(Anthropic·OpenAI 등)의 인증·쿼터 — 이 모든 게 동시에 돌아간다. 문제는 이 상태들이 서로 다른 곳에 흩어져 산다는 점이다.

다이어그램 설명. 이 그림은 "에이전트가 정상인가"라는 한 질문이 실제로는 일곱 갈래의 서로 다른 확인 작업으로 흩어진다는 걸 보여준다. 게이트웨이 생존은 접속 핸드셰이크와 가동 시간으로, 비용은 토큰·달러 집계로, 최근 활동은 세션 목록으로, 기능 건강은 스킬의 비활성·차단·의존성 상태로, 자동화는 예약 작업의 다음 실행 시각과 실패 건수로, 모델 접근은 (구독형 OAuth 로그인을 쓰는 경우에 한해) 인증 만료·쿼터 잔량으로, 직전에 무슨 일이 있었는지는 게이트웨이 로그를 직접 들여다봐야 알 수 있다. 모델 항목을 괄호로 묶은 이유는 이 신호가 인증 방식에 따라 갈리기 때문이다 — 구독형 OAuth 로그인은 토큰이 만료되니 감시 대상이지만, API 키나 로컬 모델은 스케줄대로 만료되는 자격증명이 없어 처음부터 이 확인이 필요 없다. 핵심은 판단은 하나인데 확인 경로가 일곱 개라는 점이다. 흔히 빠지는 오해가 "에이전트가 한 프로세스니 한 군데만 보면 된다"는 가정인데, 실제로는 비용·세션·스킬·작업·모델·로그가 각자 다른 곳에 상태를 들고 있다. 그래서 한눈에 보는 화면이 없으면 사람이 매번 이 일곱 갈래를 손으로 돌려야 한다.

핵심 문제 — "터미널 여러 번 두드리기"의 비용

Overview 화면이 없던 세상을 상상해 보자. 봇이 조용해졌을 때 운영자는 SSH로 서버에 붙어 명령을 줄줄이 친다. 게이트웨이 헬스를 받고, 세션 저장소를 뒤지고, 모델 인증이 만료됐나 확인하고, cron이 깨졌나 보고, 로그를 tail한다. 이 흐름에는 두 가지 구체적인 사고가 있다.

다이어그램 설명. 이 그림은 한눈에 보는 화면이 없을 때 갈라지는 두 가지 비용을 보여준다. 첫째, 증상은 "봇이 조용하다" 하나인데 원인 후보는 게이트웨이 다운·모델 인증 만료·cron 실패로 여러 개라, 명령을 하나씩 쳐 보며 범위를 좁혀야 한다. 둘째, 상태를 보려면 SSH로 서버에 붙어야 하는데, 정작 봇이 죽었다는 걸 깨닫는 순간은 폰으로 메시지를 보냈을 때다. 함정은 "원인이 빤하다"는 착각이다 — 메신저가 조용한 이유는 프로세스 죽음만이 아니라, 조용히 만료된 모델 토큰이나 새벽에 실패한 예약 작업처럼 겉으로 안 드러나는 곳일 때가 더 많다. 그래서 필요한 건 "프로세스가 떴나" 한 줄이 아니라, 흩어진 신호를 한 화면에 위에서 아래로 쌓아 주는 관제판이다.

해결 방법 — 한 화면을 네 개의 띠로 쌓는다

OpenClaw의 Control UI는 게이트웨이가 직접 띄우는 작은 단일 페이지 앱(Vite + Lit 기반)으로, 기본 주소는 http://<host>:18789/다. 이 화면은 별도 백엔드를 거치지 않고 같은 포트의 게이트웨이 WebSocket(서버와 양방향으로 계속 연결돼 있는 통신 채널)에 직접 말을 건다. 앞에서 흩어져 있던 상태 조회를 이 한 연결 위에서 끌어와, Overview는 화면을 위에서 아래로 네 개의 띠(band)로 쌓는다. 띠마다 답하는 질문이 다르다.

다이어그램 설명. 이 그림은 Overview가 하나의 WebSocket 연결 위에서 화면을 네 개의 띠로 쌓는 구조를 보여준다. 맨 위 접속·생존 띠는 "어디에 붙고 살아 있나"에, 그 아래 한눈 지표 띠는 "지금 무슨 일이 일어나고 있나"에, 주의 띠는 "당장 내가 손댈 게 있나"에, 맨 아래 로그 띠는 "방금 무슨 일이 있었나"에 답한다. 이렇게 위에서 아래로 쌓은 이유는 사람이 화면을 읽는 순서와 진단의 순서를 맞추기 위해서다 — 먼저 연결을 확인하고, 전체 그림을 훑고, 이상 신호를 집고, 마지막으로 로그로 파고든다. 놓치기 쉬운 점은 이게 "또 하나의 서버"가 아니라는 사실이다 — Overview는 게이트웨이가 원래 제공하던 조회 기능들을 한 화면에 배치한 뷰일 뿐이라, 게이트웨이가 죽으면 화면도 곧바로 연결 끊김을 보여 준다. 즉 화면이 무엇을 그려 내느냐가 그 자체로 첫 번째 헬스 신호다.

1띠 — Gateway Access와 Snapshot: 어디 붙고, 살아 있나

맨 위 두 카드는 "연결"과 "생존"을 책임진다. Gateway Access(게이트웨이 액세스) 카드는 대시보드가 어디에 붙고 어떻게 인증하는지를 모은 곳이다 — WebSocket 주소, 게이트웨이 토큰, (저장하지 않는) 비밀번호, 기본 세션 키, 그리고 화면 언어 설정까지 여기에 있다. 언어 변경이 별도 외관 메뉴가 아니라 이 접근 카드에 들어 있다는 게 헷갈리기 쉬운 지점이다. 아직 연결 전이라면 이 카드는 "게이트웨이를 띄우고 토큰 URL을 받아 붙여라"는 연결 안내 단계까지 펼쳐 준다.

바로 아래 Snapshot(스냅샷) 카드는 게이트웨이와 맺은 마지막 핸드셰이크 정보를 보여 준다 — 정상/오프라인 상태, 가동 시간(uptime), 틱 간격(tick interval), 채널 마지막 갱신 시각. 연결이 끊기면 상태가 곧바로 오프라인으로 바뀌고 에러 콜아웃에 페어링·인증·비보안 접속 힌트가 따라붙는다.

다이어그램 설명. 이 그림은 첫 번째 띠가 접속과 생존을 어떻게 나눠 맡는지를 보여준다. 왼쪽 접근 카드는 "어디에 어떻게 붙나"(주소·토큰·비밀번호·세션 키·언어)를 모으고, 오른쪽 스냅샷 카드는 "지금 붙어 있나"(상태·가동 시간·틱 간격·채널 갱신)를 보여 준다. 스냅샷은 상황에 따라 두 갈래로 갈린다 — 정상이면 채널을 연결하라는 안내를, 오프라인이면 무엇 때문에 못 붙는지(기기 페어링 필요, 인증 실패, HTTP 비보안 컨텍스트)를 짚어 준다. 이렇게 접근과 생존을 첫 줄에 둔 이유는, 아래의 모든 지표가 "연결이 살아 있다"는 전제 위에서만 의미를 갖기 때문이다. 한 가지 덧붙이면, 사람이 보는 이 풍부한 스냅샷과 별개로 OpenClaw는 기계 모니터링용으로 세션도 모델 호출도 만들지 않는 가벼운 헬스 엔드포인트를 따로 둔다 — 사람은 스냅샷을, UptimeRobot 같은 기계는 가벼운 핑을 쓰도록 "누가 묻느냐에 따라 답하는 깊이를 다르게" 갈라 둔 설계다.

2띠 — 비용·세션·스킬·크론: 한눈 지표이자 점프대

두 번째 띠는 작은 스탯 카드들이 가로로 깔리는 곳이다. 항상 보이는 네 장은 비용·세션·SKILLS·CRON이고, 모델 제공자가 OAuth 인증을 쓰면 쿼터·모델 인증 카드가 조건부로 더 붙는다. 각 카드는 큰 숫자 하나와 작은 보조 설명(hint)으로 이뤄진다.

• 비용 — 누적 비용을 달러 금액으로 보여 주고, 보조 줄에 토큰 수와 메시지 수를 단다.
• 세션 — 게이트웨이가 추적 중인 세션 개수.
• SKILLS — 활성/전체 비율(예: 12/15). 차단된 스킬이 있으면 "N blocked"로 경고색이 뜬다.
• CRON — 활성 작업 수 또는 "disabled". 다음 실행 시각을 보조로 달고, 실패한 작업이 있으면 "N failed"로 붉게 뜬다.

이 띠의 진짜 설계 포인트는 따로 있다. 카드가 단순한 표시기가 아니라 클릭하면 해당 상세 탭으로 점프하는 버튼이라는 점이다. 비용 카드를 누르면 사용량 화면으로, 세션 카드는 세션 목록으로, 스킬·크론 카드는 각자의 관리 화면으로 데려간다. 그래서 Overview는 "상태를 보여 주는 판"이면서 동시에 "상태가 이상할 때 곧바로 파고드는 출발점"이 된다. 띠 바로 아래에는 최근 세션 다섯 개가 목록으로 깔리는데, 세션 키에 섞인 긴 숫자(전화번호 같은 식별자)는 자동으로 흐리게 처리해 어깨너머 노출을 막는다.

다이어그램 설명. 이 그림은 두 번째 띠의 카드들이 단순 표시기가 아니라 상세 화면으로 가는 점프대라는 걸 보여준다. 비용·세션·스킬·크론 카드는 각각 사용량·세션 목록·스킬 관리·예약 작업 화면으로 곧장 연결되고, 맨 아래엔 최근 세션 다섯 개가 식별자 숫자를 흐리게 처리한 채 깔린다. 이렇게 만든 이유는, 한눈에 본 숫자가 이상할 때(비용이 튀거나, 스킬이 차단됐거나, cron이 실패했거나) 사람이 다시 메뉴를 찾아 헤매지 않고 카드를 바로 눌러 들어가게 하기 위해서다. 놓치기 쉬운 점은 숫자 블러가 단순 장식이 아니라는 것이다 — 개인 서버의 Overview는 화면 공유나 스크린샷에 그대로 노출되기 쉬운데, 세션 키에 든 전화번호 같은 식별자를 흐리게 처리해 그 위험을 줄인다.

3띠 — 주의(Attention): 데이터에서 파생된 "지금 손봐야 할 것"

세 번째 띠가 Overview의 가장 영리한 부분이다. 주의(Attention) 영역은 새로 무언가를 조회하지 않는다. 대신 위 띠들이 이미 가져온 데이터를 다시 훑어, "사람이 지금 당장 손봐야 할 것"만 추려 경고 카드로 띄운다. 게이트웨이 에러, 읽기 권한(operator.read scope) 누락, 의존성이 빠진 스킬, 차단된 스킬, 실패한 cron, 5분 넘게 밀린 cron, 만료됐거나 곧 만료될 모델 인증 — 이런 항목이 심각도(에러=빨강, 경고=노랑)별로 쌓이고, 해당하는 경우 문서 링크까지 붙는다.

가장 중요한 동작은 이것이다 — 아무 문제가 없으면 이 띠는 화면에서 통째로 사라진다. 항상 떠 있는 빈 "이상 없음" 패널이 아니라, 손댈 게 있을 때만 나타나는 영역이다. 그래서 Overview에 주의 카드가 보인다는 사실 자체가 신호다 — 한눈에 "오늘은 빨간 게 있나 없나"를 가른다.

다이어그램 설명. 이 그림은 주의 띠가 어떻게 "새 조회 없이" 만들어지는지를 보여준다. 게이트웨이 에러, 권한 누락, 스킬의 의존성·차단, cron의 실패·지연, 모델 인증의 만료·임박 — 이 모든 판단이 이미 위 띠가 가져온 같은 데이터에서 파생되고, 해당하는 항목만 심각도색과 문서 링크를 단 경고 카드로 모인다. 그리고 아무것도 해당하지 않으면 띠 전체가 화면에서 빠진다. 이렇게 설계한 핵심 이유는, 스탯 카드가 보여 주는 "현황"과 사람이 알고 싶은 "이상 여부"가 다른 질문이기 때문이다 — cron 카드의 "12 jobs"는 정상으로 보이지만 그중 하나가 새벽에 실패했을 수 있고, 주의 띠는 바로 그 한 건을 끌어올려 빨갛게 띄운다. 함정은 "지표가 초록이면 괜찮다"는 착각이다. 주의 띠는 같은 데이터를 "이상 신호" 관점으로 한 번 더 걸러, 평온해 보이는 숫자 뒤에 숨은 문제를 표면으로 끌어낸다.

4띠 — 이벤트 로그 vs Gateway 로그: 두 결의 로그

맨 아래 띠는 로그 둘이 나란히 놓인다. 이름이 비슷해 헷갈리지만 결이 다르다.

이벤트 로그(Event Log)는 게이트웨이가 WebSocket으로 흘려보낸 구조화된 이벤트와, 브라우저 화면 쪽의 성능 이벤트(느린 렌더·긴 작업 등)를 한 버퍼에 섞어 최근 것부터 보여 준다. 각 줄은 시각·이벤트 이름·페이로드 미리보기로 이뤄진 가벼운 타임라인이다. 반면 Gateway 로그(Gateway Logs)는 게이트웨이에게 logs.tail(서버 로그의 끝부분을 달라는 호출)을 보내 받은 실제 서버 측 로그 원문이다. 터미널 색상 코드(ANSI)를 벗겨 읽기 좋게 다듬고, 마지막 줄들을 그대로 펼친 뒤 새로고침 버튼과 줄 수 배지를 단다.

이 구분이 중요한 이유는, "내 브라우저 탭이 버벅이는 것"과 "서버가 실제로 토해낸 에러"를 갈라 주기 때문이다. (드래프트 초안에서 하단 로그를 "브라우저 화면의 동작 타이밍을 모은 것"이라고만 적었는데, 실제로는 구조화된 이벤트 타임라인과 진짜 서버 로그 tail이라는 두 결의 로그가 나란히 있다.)

다이어그램 설명. 이 그림은 마지막 띠의 로그 두 개가 서로 다른 결이라는 걸 보여준다. 왼쪽 이벤트 로그는 게이트웨이가 보낸 구조화된 이벤트와 브라우저 쪽 성능 이벤트를 섞어 시각·이름·페이로드 미리보기로 보여 주는 가벼운 타임라인이고, 오른쪽 Gateway 로그는 서버 로그의 끝부분을 그대로 받아 색상 코드를 벗긴 원문이다. 둘을 나란히 둔 이유는 진단의 두 질문이 다르기 때문이다 — "이벤트가 화면까지 오고 있나, 아니면 내 탭이 느린가"는 이벤트 로그로, "서버가 진짜로 무슨 에러를 냈나"는 Gateway 로그로 가른다. 놓치기 쉬운 점은 이벤트 로그가 서버 로그의 축약본이 아니라는 사실이다 — 한쪽은 클라이언트가 받은 이벤트와 렌더 성능을, 다른 쪽은 서버가 파일에 남긴 원문 로그를 보여 주므로, 둘이 어긋날 때(이벤트는 끊겼는데 서버 로그는 멀쩡할 때) 그 차이 자체가 단서가 된다.

결과 — 무엇이 좋아졌나

Overview가 들어오면서 앞서 본 "흩어진 상태를 손으로 긁어모으던" 작업이 이렇게 정리된다.

이전 (흩어진 확인)	이후 (Overview 한 화면)
봇이 조용하면 SSH 붙어 명령 여러 번	브라우저 한 화면에서 접속·비용·세션·스킬·cron·인증을 위에서 아래로 훑기
화면 생존과 게이트웨이 생존이 따로 놂	화면이 연결 끊김을 즉시 표시 — 화면 자체가 첫 헬스 신호
지표는 초록인데 숨은 실패(만료된 인증·실패한 cron)를 놓침	주의 띠가 같은 데이터를 "이상 신호"로 다시 걸러 빨갛게 끌어올림
이상을 봐도 어느 화면으로 가야 할지 다시 헤맴	스탯 카드 클릭 = 해당 상세 탭으로 즉시 점프
"내 탭이 느린 건지 서버 에러인지" 구분 불가	이벤트 로그(클라이언트)와 Gateway 로그(서버 원문)를 나란히 비교

정리하면, Overview는 "여러 프로세스·세션·작업으로 흩어진 에이전트의 상태를, 한 화면에 위에서 아래로 쌓은 관제판"이다. 새 인프라를 쌓는 대신 게이트웨이가 원래 가진 조회 기능들을 한 WebSocket 위에 네 개의 띠 — 접속·지표·주의·로그 — 로 펼쳐, 운영자가 "지금 살아 있나"를 묻는 데 드는 비용을 SSH 여러 번에서 탭 하나로 줄였다. 특히 주의 띠가 "초록 지표 뒤에 숨은 빨간 한 건"을 끌어올리고, 스탯 카드가 곧장 상세로 점프시키는 두 장치가 Overview를 단순 상태판에서 관제판으로 끌어올린다. 자율 에이전트를 집 서버에 무인으로 돌리려면, 화려한 기능보다 먼저 "한눈에 살아 있는지, 손댈 게 있는지 보이는 화면"이 있어야 사람이 안심하고 손을 뗄 수 있다 — Overview는 그 안심을 만드는 토대다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.