Linux systemd 사용자 유닛에서 동작하는 OpenClaw 게이트웨이 개념도

2026 Linux systemd OpenClaw：업그레이드 후 HOME·XDG 불일치로 설정이 비어 보일 때 doctor 복구

systemd --user 로 openclaw gateway 를 돌리면 업그레이드 직후 유닛은 active 인데 대시보드만 초기화된 것처럼 보일 수 있습니다. SSH 세션과 다른 HOME·XDG_CONFIG_HOME 을 읽어 스켈레톤 openclaw.json 만 생기는 경우가 흔합니다. 본문은 증상을 세 층으로 나누고 systemctl --user show 로 환경을 고정한 뒤 병합과 doctor 를 진행하는 순서를 정리합니다.

목차

1. 증상 세 층：프로세스·RPC·빈 설정

프로세스：systemctl --user status 가 active 여도 실제로 여는 설정 루트가 운영자 홈과 같다는 뜻은 아닙니다. WorkingDirectory·HOME 이 비어 있으면 패키지 근처에 스켈레톤이 생깁니다.

RPC：openclaw gateway status 의 빌드 ID 가 CLI 시맨틱 버전과 다르면 먼저 《split brain·meta.lastTouchedVersion》을 따르고 디렉터리 삭제는 뒤로 미룹니다.

설정 껍데기：디렉터리는 있는데 channels·plugins 가 비어 보이면 다른 XDG_CONFIG_HOME 에 쓰고 있을 수 있습니다. 업그레이드로 검색 순서가 바뀌면 이전 경로에만 유효한 JSON 이 남습니다.

  1. journalctl --user 에서 ENOENT·HOME·설정 경로 키워드를 찾습니다.
  2. 로그인 셸·비로그인·systemctl --user show 세 환경을 나란히 둡니다.
  3. 병합 전에 tar 스냅샷을 만듭니다.

2. status→gateway status→로그→doctor

《공식 gateway 프로브》와 같이 먼저 리스너와 RPC 를 증명한 뒤 openclaw doctor 로 넘어갑니다.

doctor 전후로 gateway status 를 저장하고, 자격 증명 디렉터리는 채널이 안정된 뒤 마지막에 옮깁니다.

3. 재시작·병합·install --force 판단표

짧은 의사결정용입니다. 여러 대면 이미지를 고정한 뒤 카나리아 한 대만 올립니다.

징후 우선 조치 위험
HOME 없이 스켈레톤 drop-in 으로 HOME·WorkingDirectory 명시 낮음
구 경로에 JSON·신 경로는 빈 껍데기 블록 병합·meta 기록 중간
CLI·GW 시맨틱 버전 분리 변경 창에서 gateway install --force 높음

4. 병합·검증 7단계

systemctl --user show openclaw-gateway.service -p Environment -p WorkingDirectory
echo "$HOME" "$XDG_CONFIG_HOME"
tar czf ~/openclaw-premerge-$(date +%Y%m%d%H%M).tgz ~/.openclaw ~/.config/openclaw 2>/dev/null
  1. 동일 JSON 동시 편집·병렬 설치 중지.
  2. root·로그인·유닛 환경 덤프 3종 저장.
  3. gateway status 의 설정 루트를 기준으로 삼기.
  4. channels→plugins→credentials 순 병합.
  5. doctor 후 status·채널 재검증.
  6. 헤드리스면 loginctl linger 확인.
  7. 티켓에 시맨틱 버전·drop-in 해시·rollback tar 경로 기록.

5. 인쇄용 체크 표

당직 인수인계에 붙일 짧은 행입니다. 스냅샷 tar 는 0바이트가 아닌지 ls -lh 로 1분 안에 확인합니다.

항목 명령 기대
유닛 HOMEsystemctl --user show설정 소유 계정 홈과 일치
lingerloginctl show-userSSH 종료 후에도 사용자 매니저 유지
저널journalctl --user -u설정 ENOENT 연속 없음

6. split brain·Docker·macOS 글과의 경계

split brain 은 시맨틱 버전·메타를 다룹니다. Docker 는 《Compose 토큰》을, macOS 는 《launchd 재시작》을 참고하고 Linux 에서는 User=·linger 를 우선합니다.

7. FAQ

Q 스켈레톤을 지우고 복사해도 됩니까. A 서비스 중지·스냅샷 후에 하십시오.

Q root 와 일반 사용자가 동시에 띄우면. A 포트·설정 루트가 충돌합니다. User= 로 하나로 모으십시오.

8. 요약과 원격 Mac

올바른 설정을 읽으려면 systemd 가 보는 HOME·XDG 를 먼저 맞추고 공식 단계로 RPC 를 검증해야 합니다.

자체 호스팅 Linux 은 drop-in·이미지·병합 규율이 계속 필요하고 릴리스가 잦을수록 드리프트가 반복됩니다.

장시간 게이트웨이와 Apple 실리콘 호환 경로를 맞추고 싶다면 SFTPMAC 원격 Mac 요금과 도움말을 비교해 보십시오.