2026 OPENCLAW
SKILLS_
SNAPSHOT_
STALE_
RESET.
2026년 ClawHub 또는 ~/.openclaw/skills/에 새 스킬을 올렸는데 Telegram·Slack 등 채널에서 Agent가 여전히 구버전처럼 동작한다면—/new와 sessions.reset을 실행해도 로그에 기대한 skillsSnapshot 갱신이 없고, 모델·인증이 auto model/auth 덮어쓰기에 끌려간다면—대개 스킬 패키지 미설치가 아니라 세션 스냅샷·디스크 매핑·Gateway 프로세스 캐시 세 층이 어긋난 상황입니다. 본문은 통증 분해·의사결정 표·6단계 Runbook·3게이트·심층 사례·업계 관점·인용 가능 임계값·FAQ를 제시하며, 사이트 내 invalid config·doctor --fix, Fallback 쓰기·sessions 정리, 다채널 JSONL·Bootstrap 정지와 상호 링크합니다. 필요 시 골드 대조 환경을 7×24 전용 원격 Apple Silicon Gateway 노드로 옮겨 검수하세요.
1. 통증 분해: reset은 「채팅」을 지우지, 「스킬 그래프 스냅샷」을 항상 지우지는 않습니다
① skillsSnapshot과 세션 reset 의미 불일치: /new·sessions.reset은 대개 대화 컨텍스트·라우팅 키만 초기화합니다. Gateway는 성능을 위해 스킬 디렉터리 파싱 결과(skillsSnapshot)를 캐시합니다. 캐시 키가 skills mtime 무효화를 따르지 않으면 「디스크 SKILL.md는 새로운데 런타임 도구 목록은 구버전」이 됩니다. ② auto model/auth 덮어쓰기 잔류: fallback·채널 정책이 한 번이라도 런타임 모델·provider 토큰을 세션 항목에 쓰면, reset이 sessions.json의 runtimeOverrides를 건드리지 않는 한 Agent는 구 모델 능력 경계로 새 스킬을 해석합니다(vision 필수 스킬이 텍스트 전용 티어로 라우팅 등). ③ sessions.json 매핑 노후: 다계정·다채널 공존 시 삭제된 sessionId·구 workspace 경로가 남아 reset 후 잘못된 슬롯을 조용히 재사용합니다. ④ CLI 재시작 ≠ Gateway 재시작: 대화 셸에서 openclaw status가 녹색이어도 launchd Gateway가 기동 시 스킬 그래프를 쥔 채일 수 있습니다. gateway restart --force --wait와 리슨 준비 검수가 필요합니다. ⑤ 원격 Mac 7×24 「가짜 새로고침」: 로컬 MacBook에만 스킬을 두고 원격 노드 미동기·미강제 재시작이면 인수인계 시 「OpenClaw 또 불안정」으로 오판하기 쉽습니다. 먼저 양단 skills 디렉터리 hash·Gateway PID 기동 시각을 맞추고 npm 재설치는 그다음입니다.
2. 의사결정 표: 스냅샷 확인, sessions 정리, force 재시작 중 무엇을 먼저?
| 현장 신호 | 1순위 조치 | 대안 / 금지 |
|---|---|---|
| 디스크에 새 스킬 있으나 도구 목록 불변 | skills mtime 대조 → Gateway force 재시작 → 신규 세션 프로브 | 채널만 갱신하고 Gateway 미재로드 금지 |
| reset 후에도 fallback 티어 모델 행동 | sessions.json runtimeOverrides/auto 필드 확인 | 백업 없이 전체 파일 삭제 금지 |
| 단일 채널만 노후, 타 채널 정상 | channelId 단위 매핑 항목 삭제 후 reset | sessions.json 일괄 삭제 금지 |
| v2026.5.x 이후 전체 「둔해짐」 | openclaw.json agents 절·doctor 출력 대조 | 스냅샷 없이 스킬·plist 병행 변경 금지 |
| 감사 가능한 프로덕션 창 필요 | 원격 대조 노드에서 동일 6단계 선행 | 피크에 프로덕션 sessions 직접 편집 금지 |
3. 6단계 Runbook: 「설명 가능」에서 「대조 검수 가능」으로
Step 1 증거 사원조 고정
작업 전 고정: openclaw 버전, Gateway PID 기동 시각, skills 디렉터리 파일 수/hash, 대상 channel session 키. openclaw status, openclaw gateway status, gateway 로그 최근 200줄을 티켓에 첨부하세요. 사원조 없이 「sessions 삭제 + 스킬 재설치 + plist 변경」을 병행하지 마세요.
Step 2 디스크 진실원 검증: 스킬 위치·권한
~/.openclaw/skills/ 또는 workspace 약정 경로에서 SKILL.md·manifest가 Gateway 실행 사용자에게 읽히는지 확인합니다. 원격 Mac은 rsync·배포 파이프라인으로 디렉터리를 맞추고 「로컬만·서버 없음」 분기를 막습니다. ClawHub 설치 시 패키지명·버전을 기록해 스냅샷 항목과 대조합니다.
Step 3 sessions.json 계층 정리(전량 삭제 아님)
먼저 cp sessions.json sessions.json.bak.$(date +%Y%m%d%H%M). jq로 대상 channel/account 항목만 찾아 runtimeOverrides, 노후 model, 공중에 떠 있는 sessionId 키만 제거하고 다른 채널 매핑은 유지합니다. 파일이 운영 임계(§7)를 넘으면 다채널 JSONL 전문의 박리·아카이브로 Bootstrap이 거대 jsonl에 막히지 않게 합니다.
Step 4 reset 직후 프로브 메시지로 검수
대상 채널에서 /new 또는 sessions.reset 후 즉시 프로브 지시(사용 가능 도구/스킬명 나열 등)를 보냅니다. 응답에 새 스킬이 없으면 reset을 2회 넘기지 말고 Step 5로 가세요.
Step 5 Gateway 강제 재시작·준비 대기
openclaw gateway restart --force --wait(또는 동등 RPC)로 구 프로세스 종료·스킬 디렉터리 재스캔을 보장합니다. 원격 launchd는 필요 시 launchctl kick -k 후 gateway status 3회. invalid config 전문과 같이 재시작 폭풍 중 openclaw.json 변경 금지.
Step 6 원격 7×24 대조 검수 매트릭스
대조 노드에서 Step 1–5를 반복하고 양단 로그의 skillsSnapshot 요약(도구 수, hash, 스캔 시간)을 비교합니다. 프로덕션 전환 전 연속 30분 프로브 무퇴행·channels.probe 무적색을 요구하고 검수 로그를 변경 티켓 closure에 붙이세요.
4. 3게이트: SOP에 쓰면 비과학이 아닙니다
1차 스냅샷 게이트: 재시작 후 로그·status의 skillsSnapshot 도구/스킬 수가 디스크 find 결과와 일치해야 합니다. 한 항목이라도 차이면 「스킬 적용 완료」를 선언하지 마세요. 2차 세션 게이트: 대상 channel reset 후 첫 프로브가 새 스킬에 맞아야 합니다. 10분 내 퇴행 시 sessions.json.bak 롤백·쓰기 동결. 3차 환경 일치 게이트: 대화 셸과 launchd의 OPENCLAW_*·skills 경로·Gateway PID 기동 시각을 항목 diff. 원격 프로덕션과 로컬 개발기 hash 불일치 시 변경 병합 금지.
5. 심층 사례: 「ClawHub 3스킬 설치, 채널은 옛 세 가지 도구만」
「원격 Mac mini 당번 Bot에 summarize·browser·calendar 설치, ClawHub 성공 표시. Telegram /new 연속에도 새 도구 없음. 로컬 MacBook 동일 openclaw.json은 정상—Gateway 11일 가동으로 skillsSnapshot 미갱신, sessions.json 해당 그룹 runtimeOverrides가 fallback 모델에 고정.」
2026년 5월 한 콘텐츠 운영팀이 OpenClaw를 7×24 요약 입구로 쓰며 ClawHub에서 스킬을 일괄 설치했습니다. 당일 Telegram 테스트는 구 내장 도구만 호출되었고, 운영은 /new 3회·CLI sessions.reset 성공 표시였으나 스킬 재스캔 로그 행이 전혀 없었습니다. 복기는 두 갈래입니다. 첫째, ps로 Gateway PID가 11일 전, skills 최신 mtime과 크게 어긋남—reset은 세션만 지우고 프로세스 내 스냅샷은 무효화하지 못함. gateway restart --force --wait 후 skills scan 요약이 나타나 도구 수 7→10. 둘째, sessions.json에서 해당 그룹에 429 이후 runtimeOverrides.model이 남아 browser 스킬이 능력 태그 불일치로 라우팅층에서 조용히 스킵. 본 Runbook대로 백업 후 해당 override만 삭제·30분 프로브 창 통과로 사건을 「감사 가능」으로 되돌렸습니다.
본 사례는 Fallback 설정 드리프트와 직렬입니다: fallback의 openclaw.json 쓰기는 설정 진실원, 본문은 세션 상태 + 프로세스 캐시 문제입니다. Gateway CPU 100%·신규 로그 없음이면 먼저 다채널 JSONL 팽창으로 Bootstrap 정지를 배제한 뒤 skills 스냅샷 검수로 돌아오세요. 거대 jsonl에서 reset 반복은 더 느려집니다.
당번 관점 최고 비용은 「OpenClaw가 신규 스킬 미지원」으로 오해해 Agent를 우회 스크립트로 옮기는 것입니다. 실체는 스냅샷·sessions 계층 정리 부족인 경우가 대부분입니다. 6단계 Runbook·3게이트를 변경 템플릿에 넣으면 2차 동종 장애 MTTR은 수시간→30분 이내로 줄고, 「왜 프로덕션 Gateway를 재시작했는가」 내부 감사에도 증거로 답할 수 있습니다.
6. 업계 관점: 2026 Agent 운영은 「패키지 설치」에서 「스냅샷 가시성」으로
2026 주류 Agent Gateway는 지연 절감을 위해 스킬 그래프 스냅샷을 씁니다. 지연에는 유리하지만 운영에는 「언제 프로세스 뷰를 force 갱신해야 하는가」 규율이 필요합니다. 발주·내부 감사가 보는 것은 「최신 스킬을 넣었는가」뿐 아니라 「설치 후 대조 가능한 스냅샷 기록이 있는가」—PID 기동 시각, skills hash, sessions 정리 전후 diff 포함. OpenClaw 같은 다채널 Gateway는 디스크 상태·세션 매핑·프로세스 캐시가 묶여 있어 로컬 MacBook 대화 기동만으로는 캐시 문제가 가려지고 7×24 원격에서 N일째에 집중 폭발합니다.
업계 BP에는 스킬 설치를 변경 창에 넣기, 설치 스크립트 말미 gateway restart --wait 강제, sessions.json 채널 항목 단위 정리가 포함됩니다. doctor·fail-closed와 병치하면 「OpenClaw 운용 여권」이 됩니다: 설정 합법성, 세션 매핑, 스킬 스냅샷, Gateway 준비—네 장 중 하나라도 빠지면 야간 머지를 피하세요.
로컬 MacBook은 SKILL.md 반복·단일 채널 검증에 적합합니다. 반면 다채널 7×24·장기 스냅샷 미갱신·원격·로컬 디렉터리 분기가 핵심이면 노트북만으로는 「로컬 녹·프로덕션 적」 대조 사각이 남습니다. 클론 가능 골드 환경, 티켓 재생 가능 sessions diff, GUI·launchd 혼합 테스트 회피가 필요하면 MACGPU 원격 Apple Silicon에서 대조 노드에 6단계 Runbook·30분 프로브 창을 먼저 통과한 뒤 변경 티켓을 프로덕션에 복사하세요. 양단 로그가 팀과 감사를 설득합니다.
7. 인용 가능 임계값(변경 티켓·당번 매뉴얼)
① Gateway 가동 7일 초과·skills 디렉터리 변경 시 설치 후 반드시 restart --force --wait, 세션 reset만으로는 부족. ② 동일 channel /new 2회 초과 무효 시 sessions.json 조사, 3회째 맹목 reset 금지. ③ sessions.json 2 MB, 단일 채널 jsonl 20 MB 초과 시 스킬 갱신 전 아카이브 박리(다채널 전문과 일치). ④ 스킬 유효 검수 창 ≥30분 도구 목록 무퇴행 시에만 티켓 종료. ⑤ 원격 대조·프로덕션 skills hash 불일치 시 프로덕션 업데이트 완료 선언 금지.
8. FAQ
Q: 스킬만 설치하고 Gateway 재시작 생략해도 되나요? A: 개발기 단기 테스트는 될 수 있으나 프로덕션 7×24 비권장. 스냅샷 캐시는 설계 트레이드오프이지 반드시 버그는 아닙니다. Q: sessions.reset vs /new? A: 채널 사용자는 /new, 운영 배치는 sessions.reset; 둘 다 Gateway 강제 재시작 대체 아님. Q: sessions.json rm? A: 지혈 가능하나 반드시 백업, 전 채널 매핑 상실—jq 항목 단위 정리 우선. Q: invalid config로 Gateway 진입 불가와 구분? A: 진입 불가는 doctor·fail-closed 로그 우선; 본문은 진입 가능·스킬 구버전 시나리오. Q: Windows/Linux 노드? A: 서비스·경로는 다르지만 스냅샷·sessions 계층 로직은 이식 가능.