OpenClaw 업데이트 오류와 롤백 - 멀티에이전트 첫 장애 기록

사건 개요

첫 설치 이후 필요에 따라 에이전트를 추가하다 보니 현재 모두 세 명의 멀티 에이전트를 운영 중이다. 그러던 중 첫 장애가 발생했다. 때는 2026년 2월 14일 아침, OpenClaw를 최신 버전인 2026.2.12로 올렸다. 별문제 없이 게이트웨이가 재시작됐지만 메인 에이전트를 제외한 두 명의 에이전트가 텔레그램에 메시지를 보내도 반응이 없었다. 설정을 건드린 적도 없고 네트워크 문제도 아니었다. 에이전트 둘이 동시에 알 수 없는 이유로 조용히 죽은 것이다. 그리고.. 원인은 예상치 못한 곳에 있었다. 두둥!

출처: https ://openclaw.ai/

사건 기록

대한민국 서울, 2월 14일 오전 8시 50분경. OpenClaw 새 업데이트가 나왔길래 별생각 없이 버전을 올렸다.

openclaw update --tag 2026.2.12

게이트웨이 재시작 후 텔레그램으로 세 명의 에이전트 중 하나인 Ruth에게 말을 걸었다. 응답 없음. Dani도 마찬가지. Eli(메인 에이전트)만 내 메시지에 반응했다. 최근 추가한 두 명의 에이전트만 먹통이다. 입술이 바싹 말랐다. 숨을 가다듬고 게이트웨이 로그를 열었다.

openclaw gateway logs --tail 50

[ERROR] Session file path must be within sessions directory
[ERROR] Failed to bind agent ruth to telegram
[ERROR] Failed to bind agent dani to telegram

에러 메시지가 명확했다. 세션 파일 경로가 세션 디렉터리 안에 있어야 한다는 검증에서 걸렸다. 이전 버전에서는 없던 검증이다.

 

세션 경로 검증이란?

OpenClaw는 에이전트별로 세션 파일을 관리한다. 경로는 보통 이렇게 생겼다.

~/.openclaw/agents/ruth/sessions/session.json
~/.openclaw/agents/dani/sessions/session.json

반응형

2026.2.12에서 보안 강화를 위해 세션 파일 경로가 반드시 'sessions/' 디렉터리 하위에 있어야 한다는 검증이 추가됐다.

Sessions/Gateway: harden transcript path resolution and reject unsafe session IDs/file paths so session operations stay within agent sessions directories. Thanks @akhmittra.

https://github.com/openclaw/openclaw/releases/tag/v2026.2.12

Release openclaw 2026.2.12 · openclaw/openclaw

문제는 이 변경점이 멀티에이전트 환경에서의 에이전트별 sessions 디렉토리 위치를 고려하지 않았다는 점이다. 이전 버전에서는 세션 파일 위치에 제한이 없었지만, 2.12에서 'sessions/' 디렉터리 하위로 강제하면서 기존 경로가 검증에 걸린 것이다.

nano banana 생성 이미지

 

디버깅 과정

1. 로그 확인

openclaw gateway logs --tail 100 | grep -i "session"

TMI 같지만 부연 설명을 하자면.. openclaw gateway logs는 게이트웨이 데몬의 실시간 로그를 출력한다. --tail 100은 최근 100줄만, grep -i "session"은 세션 관련 로그만 필터링한다. 장애 상황에서 어떤 에러가 반복되는지 빠르게 파악할 때 쓴다.

Error: Session file path must be within sessions directory
Error: Session file path must be within sessions directory
Error: Session file path must be within sessions directory
...

동일한 에러가 반복적으로 찍히고 있었다. 세션 파일 경로가 허용된 디렉터리 밖에 있다는 뜻인데, 메인 에이전트를 제외한 두 에이전트(Ruth, Dani) 모두 같은 에러였다. 에이전트별 설정 문제가 아니라 공통적인 경로 검증 문제라는 걸 알 수 있었다.

 

2. 커뮤니티 검색

GitHub Issues에서 에러 메시지를 검색했다. 이미 이슈가 여럿 올라와 있었다. 새삼 멀티 에이전트를 돌리는 사람들이 꽤 많다는 사실을 알게 됐다.

• #15326 — (아마도) 최초 보고. 업데이트 후 세션 바인딩 깨짐
• #15629 — 멀티 에이전트 환경에서 재현 확인
• #15665 — 텔레그램 바인딩 전원 실패 (내 케이스와 동일)
• #15725 — Windows 환경에서도 동일 현상
• #15674 — openclaw doctor --fix도 이 문제를 못 고침

다섯 개 이슈가 같은 버그를 가리키고 있었다. 아래는 최초 보고된 이슈의 링크다.

https://github.com/openclaw/openclaw/issues/15326

Bug: Session file path must be within sessions directory · Issue #15326 · openclaw/openclaw

 

3. 커뮤니티 임시 해결책

이슈 #15629에서 누군가 제안한 방법을 적용해 봤다.

{
  "agents": {
    "ruth": {
      "sessionFile": "/Users/.../.openclaw/sessions/ruth/session.json"  // ← 이 줄 삭제
    }
  }
}

sessionFile을 삭제하면 OpenClaw가 기본 경로를 사용하고, 새 검증을 통과한다는 논리였다. 일부 사용자에게는 효과가 있는 것 같았지만 멀티 에이전트 두 명의 세션이 꼬여 있는 내 상황에서는 해결책이 아니었다.

 

해결 시도 (시간순)

시도 1: openclaw doctor --fix

openclaw doctor --fix

✗ Session path validation failed for agent: ruth
✗ Session path validation failed for agent: dani
✗ Session path validation failed for agent: eli
[!] Auto-fix failed: cannot resolve session path conflict

OpenClaw 운영 중 뭔가 안 된다 싶을 때, 터미널에서 'openclaw doctor'를 실행하면 웬만해선 원인 파악 및 자동 복구에 성공한다. 하지만 이번엔 실패(#15674 이슈 참고).

시도 2: sessionFile 삭제

중복된 내용이지만 시간 순으로 정리하냐고 한 번 더 쓴다. 커뮤니티에 공유된 임시 해결책(이슈 #15629)에서 제안하는 내용과 같이 sessionFile을 삭제해 봤지만 효과가 없었다.

시도 3: 롤백 (성공)

어느새 이 문제로 씨름한 지 1시간이 더 지났다. 핫픽스를 기다릴 여유는 없었다. 업데이트 이전에 정상 동작했던 2026.2.9 버전으로의 롤백을 결정했다.

openclaw update --tag 2026.2.9
# 게이트웨이 자동 재시작됨

✓ Gateway started
✓ Agent ruth bound to telegram
✓ Agent dani bound to telegram  
✓ Agent eli bound to telegram

에이전트 세 명 전원이 정상 복귀됐다. 총 장애 시간은 약 1시간이다.

openclaw status
# Running | 3 agents | 3 channels bound

장애 복구에 성공했다기보다는 정확한 원인을 찾지 못해서 롤백을 시도했는데 다행히 성공했다고 말하는 게 정확하겠다.

 

후일담: 2026.2.13 버전에서 이슈 수정됨

이 버그는 #15141, #15103 PR로 2026.2.13에서 수정됐다. 원인은 게이트웨이의 세션 로더를 호출하는 쪽에서 agentId를 전달하지 않은 것이었다. agentId가 없으면 로더는 기본 에이전트(main)의 sessions 디렉터리를 기준으로 경로를 검증하기 때문에 다른 에이전트의 정상적인 세션 파일도 '디렉터리 밖'으로 판정돼 거부됐다. 수정 후에는 모든 호출 경로에서 agentId를 전달해, 해당 에이전트의 올바른 sessions 디렉터리 기준으로 검증하도록 바뀌었다.

Sessions/Agents: pass agentId when resolving existing transcript paths in reply runs so non-default agents and heartbeat/chat handlers no longer fail with Session file path must be within sessions directory. (#15141) Thanks @Goldenmonstew.

Sessions/Agents: pass agentId through status and usage transcript-resolution paths (auto-reply, gateway usage APIs, and session cost/log loaders) so non-default agents can resolve absolute session files without path-validation failures. (#15103) Thanks @jalehman.

https://github.com/openclaw/openclaw/releases/tag/v2026.2.13

Release openclaw 2026.2.13 · openclaw/openclaw

2026.2.13으로 업데이트해서 정상 동작까지 확인했다. 작성 시점 기준, 최신 버전(2026.2.15)에는 보안 패치가 다수 포함되어 있으니 가능하면 아예 최신으로 올리는 걸 추천한다. 관련해서 OpenClaw의 Gateway와 Node 구조가 궁금하다면 아래 포스트를 참고하기 바란다.

2026.02.02 - [개발 스터디/AI - OpenClaw] - OpenClaw 설치 다음 단계 - Gateway, Node, macOS 앱 한번에 정리

OpenClaw 설치 다음 단계 - Gateway, Node, macOS 앱 한번에 정리

 

세줄 요약 (TL;DR)

• 증상: 멀티 에이전트의 텔레그램 수신이 중단되는 현상 발생
• 원인: 2026.2.12 세션 경로 검증과 기존 설정 충돌
• 해결: 2026.2.9 롤백 후 복구, 이후 2026.2.13에서 수정 확인

 

교훈

1. 멀티 에이전트 환경에서 업데이트는 위험하다

에이전트가 하나라면 문제가 생겨도 빠르게 대응할 수 있다. 하지만 여럿이 동시에 죽으면 어디서부터 봐야 하는지조차 혼란스럽다. 처음에는 텔레그램 쪽 문제인 줄 알고 시간을 낭비했다.

멀티에이전트 전체 무응답 시 대응

1. 'openclaw gateway logs --tail 100' 확인
2. GitHub Issues에서 에러 메시지 검색
3. 'openclaw doctor --fix' 시도
4. 안 되면 이전 버전으로 롤백: 'openclaw update --tag <이전버전>'
5. 'openclaw gateway restart'

2. 업데이트 전에 버전을 기록하자

롤백하려면 이전 버전 번호를 알아야 한다. 업데이트 전에 아래와 같이 버전을 기록한다.

openclaw --version >> ~/openclaw-version-history.txt	# 현재 버전 append
date >> ~/openclaw-version-history.txt	# 기록 시점 append

그런데 솔직히 이건 좀 원시적인 방법이다. openclaw update 하면 어차피 이전 버전 로그가 남는다. 필수는 아니고 마음의 안정을 위한 이중 대응 정도로 보면 된다.

3. 커뮤니티를 먼저 확인해라

이건 좀 중요하다. 새벽에 혼자 삽질하기 전에 (영어랑 친하지 않다면 번역 앱을 돌려서라도) GitHub Issues를 검색하면 시간을 아낄 수 있다. 이번에도 이미 4개 이슈가 이미 올라와 있었다.

https://github.com/openclaw/openclaw/issues

GitHub - openclaw/openclaw: Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

4. openclaw doctor가 만능은 아니다.

새 버전에서 추가된 검증 로직과 관련된 버그는 doctor 자체도 같은 버전의 로직을 쓰기 때문에 고칠 수 없다. 이런 경우 롤백이 가장 확실하다.

5. 업데이트는 낮에 하자

꼭 낮이라기보다는 장애 발생 시 대응할 수 있는 충분한 시간 여유가 있을 때 하자. 나처럼 아침에 하면 출근 시간(또는 등교)이라는 제한 시간을 스스로 정한 꼴이라 가슴을 졸이게 된다. 또 새벽에 하면 잠을 못 잔다. 끝.