서비스 이용 불가라고 표시되는 OpenClaw가 단일 장애 원인을 의미하지는 않습니다. 2026년 2월 IceWhale 커뮤니티 스레드에서 문제를 해결하는 과정에서 필요한 게이트웨이 토큰, ZimaOS 호스트 계정의 Docker 확인 권한 부족, 그리고 마지막으로 초기 구성을 완료하지 않은 OpenClaw 컨테이너라는 세 가지 계층이 차례로 드러났습니다.
이 글이 특히 유용한 이유는 일부 중간 제안이 Big-Bear 패키지 이미지에는 잘못된 것으로 밝혀졌기 때문입니다. 임의로 만든 GATEWAY_MODE 환경 변수만으로는 재시작 루프가 해결되지 않았으며, 여기에 추가하면 --gateway.mode=local 잘못된 명령에 사용하면 다음 오류가 발생합니다. 알 수 없는 옵션 오류입니다. 현재 OpenClaw 문서에서는 다음을 확인합니다. gateway.mode=local OpenClaw의 영구 구성에 포함되어야 하며, Docker 배포에서는 해당 구성을 생성하기 위해 온보딩 또는 설정을 실행해야 한다는 의미입니다.
먼저 OpenClaw 컨테이너가 실제로 실행 중인지 확인하세요
최초 게시물에는 OpenClaw 앱이 애플리케이션이 제대로 실행되지 않고 있다고 보고하며 다음과 같은 팁을 표시하는 모습이 담겼습니다. OPENCLAW_GATEWAY_TOKEN.
애플리케이션 설정을 변경하기 전에 ZimaOS 또는 CasaOS 호스트에서 컨테이너 상태를 확인하세요.
docker ps -a | grep openclaw컨테이너가 재시작 중이거나 종료된 상태라면 로그를 확인하세요.
docker logs big-bear-openclaw --tail 100정확한 컨테이너 이름은 다를 수 있습니다. 다음을 사용하세요. docker ps -a 항상 동일하다고 가정하지 말고 실제 이름을 확인하려면 big-bear-openclaw.
OPENCLAW_GATEWAY_TOKEN 생성 및 저장
커뮤니티에서 처음 제안한 방법은 강력한 무작위 게이트웨이 토큰을 생성하는 것이었습니다.
openssl rand -hex 32OpenSSL을 사용할 수 없는 경우, 해당 글에서는 로컬에서 무작위 바이트를 생성하는 대안을 제시했습니다.
head -c 32 /dev/urandom | xxd -p -c 32현재 공식 OpenClaw Docker 문서에서도 다음 명령을 사용합니다. OPENCLAW_GATEWAY_TOKEN 게이트웨이 인증에 사용됩니다. 표준 설정 스크립트는 토큰을 생성하고 배포 환경의 .env 파일에 자동으로 저장합니다. 수동으로 패키징한 CasaOS 애플리케이션에서는 생성된 값을 해당 이미지에서 요구하는 환경 변수 필드에 입력하세요.
이 토큰은 비밀로 취급하세요. 공개 포럼, 스크린샷, 지원 티켓 또는 저장소에 붙여 넣지 마세요.
Docker 권한 오류는 OpenClaw 권한 오류가 아닙니다
토큰을 추가한 후 원 작성자는 다음 오류를 겪었습니다.
Docker 데몬 소켓에 연결하려는 동안 권한이 거부됨
/var/run/docker.sock: 연결할 수 없음: 권한이 거부됨
커뮤니티에서는 관리자 권한이 필요한 Docker 명령을 실행하기 전에 일시적으로 권한을 상승하라고 권장했습니다.
sudo -i
docker ps진정으로 필요한 명령에만 루트 권한을 사용하세요. 다음 권한을 약화하지 마세요. /var/run/docker.sock 오류를 없애기 위해 권한을 완화하거나 Docker 소켓을 모든 사용자가 쓸 수 있도록 설정하지 마세요. Docker 접근 권한은 사실상 호스트에 대한 관리자 제어 권한을 부여합니다.
실제 OpenClaw 오류는 “Missing config”였습니다
Docker 로그에 접근할 수 있게 되자 다음과 같은 중요한 메시지가 나타났습니다.
구성이 없습니다. `openclaw setup`을 실행하거나 gateway.mode=local을 설정하세요
이는 일반적인 Service Unavailable 페이지보다 더 실행 가능한 안내였습니다. 현재 OpenClaw 게이트웨이 문서에서는 구성이 다음 내용을 포함하지 않으면 게이트웨이가 정상적으로 시작되지 않는다고 확인합니다.
gateway.mode = local현재 OpenClaw는 또한 다음 두 방법 중 하나를 사용할 수 있다고 설명합니다. openclaw 설정 또는 openclaw onboard --mode local 영구 구성에 로컬 게이트웨이 모드를 기록합니다.
GATEWAY_MODE=local이 이 이미지에서 문제를 해결하지 못한 이유
환경 변수를 추가하라는 제안이 있었습니다.
GATEWAY_MODE=local사용자는 이를 시도했지만 재시작 루프가 계속되었습니다. 이 중요한 정정 사항을 반드시 유지해야 합니다. 현재 공식 OpenClaw 문서에는 범용 GATEWAY_MODE 영구적으로 저장되는 설정을 대체하는 gateway.mode 이 워크플로에서 사용하는 설정.
모든 점 표기 OpenClaw 구성 키를 임의로 만든 대문자 환경 변수로 변환하지 마세요. 정확한 OpenClaw 이미지 또는 배포 템플릿에 문서화된 구성 방법을 사용하세요.
--gateway.mode=local이 “Unknown option”을 반환한 이유
이후 다른 커뮤니티 사용자가 다음 항목을 추가했습니다.
--gateway.mode=localCasaOS 컨테이너 명령에 추가되었습니다. 그러자 이미지가 다음 오류를 반환했습니다.
알 수 없는 옵션 '--gateway.mode'스레드에서는 그 이유를 정확히 파악했습니다. CasaOS가 해당 플래그를 지원하지 않는 명령 계층에 추가하고 있었던 것입니다. 현재 OpenClaw CLI는 다음과 같은 명령을 사용합니다. openclaw gateway, openclaw 설정, openclaw onboard및 openclaw config set; gateway.mode 이는 구성 키이지, 컨테이너 명령의 어디에나 배치할 수 있는 범용 최상위 런타임 플래그가 아닙니다.
Big-Bear 이미지에는 영구적으로 사용할 초기화된 구성 디렉터리가 필요했습니다
최종 커뮤니티 진단은 다음 마운트에 초점을 맞췄습니다.
/DATA/AppData/big-bear-openclaw
→ /home/node/.openclaw컨테이너는 다음 경로에 구성을 저장하도록 되어 있었습니다. /home/node/.openclaw, 하지만 마운트된 디렉터리는 초기화되지 않은 상태였습니다. 이는 현재 OpenClaw Docker 문서의 내용과 일치합니다. 마운트된 구성 디렉터리에는 영구적으로 저장되는 openclaw.json, 인증 프로필 데이터 및 환경 변수로 제공되는 시크릿.
스레드의 마지막 제안은 컨테이너 내부에서 설정을 실행하여 마운트된 디렉터리에 실제 OpenClaw 구성이 생성되도록 하자는 것이었습니다. 그러나 원 게시자는 마지막 답변 이후 최종 확인을 남기지 않았습니다. 따라서 이는 스레드에서 가장 유력한 진단으로 간주하되, 검증된 최종 해결책으로 보지는 마세요.
새로 설치할 때는 최신 OpenClaw Docker 온보딩을 우선 사용하세요
현재 배포에서는 2026년 문제 해결 과정을 오류가 발생할 때마다 하나씩 재구성하기보다 공식 OpenClaw Docker 설치 가이드를 따르세요.
현재 OpenClaw은 다음 작업을 수행하는 Docker 설정 스크립트를 제공합니다.
- 게이트웨이 이미지를 빌드하거나 가져옵니다.
- 온보딩을 실행합니다.
- 게이트웨이 토큰을 생성합니다.
- 영구 구성을 기록합니다.
- 필요한 비밀 디렉터리를 생성합니다.
- Docker Compose를 통해 게이트웨이를 시작합니다.
헤드리스 Docker 배포를 위해 현재 OpenClaw은 로컬 게이트웨이 모드 및 토큰 인증을 사용하는 비대화형 온보딩도 문서화하고 있습니다. 이는 환경 변수를 임의로 만들거나 지원되지 않는 플래그를 추가하는 것보다 적절합니다.
현재 수동 구성 방식
OpenClaw의 최신 Docker 가이드에는 다음과 동등한 수동 설정 방식이 문서화되어 있습니다.
openclaw onboard --mode local --no-install-daemon
openclaw config set gateway.mode local
openclaw config set gateway.bind lanDocker Compose에서는 일반적으로 프로젝트에서 정의한 전용 CLI 또는 온보딩 컨테이너를 통해 이러한 명령을 실행합니다. 먼저 진입점과 마운트를 확인하지 않았다면 호스트에서 실행하는 명령을 패키징된 CasaOS 이미지에 그대로 붙여넣지 마세요.
현재 OpenClaw Gateway CLI 문서에는 openclaw setup 및 openclaw onboard --mode local이 필요한 로컬 게이트웨이 구성을 생성한다고 명시되어 있습니다.
Control UI에서 동일한 게이트웨이 토큰 사용
현재 OpenClaw Docker 문서에서는 Control UI를 다음 포트에 노출합니다. 18789 표준 Compose 설정에서 게이트웨이 토큰을 배포 환경에서 복사해 UI 설정에 붙여넣도록 안내합니다.
토큰 불일치로 인해 게이트웨이가 정상 작동한 후에도 인증 오류가 발생할 수 있지만, 이는 구성이 없어 컨테이너가 반복적으로 종료되는 문제와는 다릅니다. 먼저 시작 문제를 진단한 다음 UI 인증을 확인하세요.
--allow-unconfigured를 영구적인 해결책으로 사용하지 마세요
OpenClaw은 다음을 제공합니다 --allow-unconfigured 임시 또는 개발용 시작에 사용됩니다. 현재 문서에는 이 옵션이 로컬 모드 보호 기능을 우회하지만 구성을 작성하거나 복구하지는 않는다고 명시되어 있습니다. 테스트에는 유용하지만 영구 서버의 적절한 온보딩을 대신할 수는 없습니다.
OpenClaw 서비스를 사용할 수 없을 때의 문제 해결 체크리스트
- OpenClaw 컨테이너가 실행 중인지, 종료되었는지, 아니면 재시작 중인지 확인하세요.
- 설정을 변경하기 전에 현재 컨테이너 로그를 읽으세요.
- 확인
OPENCLAW_GATEWAY_TOKEN존재하며 보안 비밀로 취급되는지 확인하세요. - Docker 명령이 소켓 권한 거부로 실패하면 Docker 소켓 권한을 약화하지 말고 권한이 있는 관리자 셸을 사용하세요.
- 다음을 특히 확인하세요.
구성 누락또는gateway.mode=local오류. - 호스트 AppData 경로가 이미지에서 요구하는 OpenClaw 구성 디렉터리에 마운트되어 있는지 확인하세요.
- 지원되는 OpenClaw 설정/온보딩 흐름을 실행하여
openclaw.json영구 저장소에 - 에 의존하지 마세요.
GATEWAY_MODE=local정확한 이미지 문서에서 명시적으로 정의한 경우가 아니라면 - 을 추가하지 마세요.
--gateway.mode=local임의의 CasaOS 컨테이너 명령에 - 구성이 기록된 후 컨테이너를 다시 시작하고 로그를 다시 확인하세요.
- 게이트웨이가 계속 실행된 후에만 Control UI 토큰 인증이나 모델 제공업체 구성을 점검하세요.
OpenClaw 서비스 이용 불가 FAQ
OpenClaw에 OPENCLAW_GATEWAY_TOKEN이 필요한가요?
현재 OpenClaw Docker 배포에서는 일반적으로 다음을 지원하고 사용합니다. OPENCLAW_GATEWAY_TOKEN 게이트웨이 인증용입니다. 공식 설정 스크립트에서 자동으로 생성할 수 있습니다. 서드파티 패키지 이미지에서는 이 값을 다른 방식으로 노출할 수 있으므로, 해당 이미지의 실제 환경 변수 스키마를 따르세요.
“permission denied /var/run/docker.sock”은 무슨 뜻인가요?
현재 호스트 사용자가 Docker 데몬에 액세스할 수 없다는 뜻입니다. 이것만으로 OpenClaw의 내부 데이터 디렉터리에 쓰기 권한이 없다는 의미는 아닙니다. Docker 진단에는 권한이 있는 관리자 계정을 사용하세요.
gateway.mode=local은 어떻게 설정하나요?
OpenClaw에서 지원하는 설정, 온보딩 또는 구성 명령을 사용하여 값을 영구 저장소에 기록하세요. openclaw.json. 현재 문서에는 다음과 같이 나와 있습니다. openclaw 설정 또는 openclaw onboard --mode local 이 설정을 생성합니다.
GATEWAY_MODE=local을 추가해야 하나요?
이 제안은 이 스레드에 근거한 것이 아닙니다. 해당 제안으로는 사용자의 패키지 이미지 재시작 루프가 해결되지 않았으며, 현재 업스트림 문서에서는 gateway.mode 일반 환경 변수 이름이 아니라 구성으로 GATEWAY_MODE.
--gateway.mode=local이 알 수 없는 옵션이라고 표시되는 이유는 무엇인가요?
CasaOS 패키지에서 해당 옵션이 잘못된 명령 계층에 추가되었기 때문입니다. 점 표기 구성 키가 모든 OpenClaw 바이너리나 엔트리포인트에서 자동으로 유효한 명령줄 플래그가 되는 것은 아닙니다.
커뮤니티 스레드에서 문제가 확실히 해결되었나요?
스레드에서는 초기화되지 않은 영구 구성 디렉터리라는 유력한 최종 진단에 도달했으며, 다음 명령을 실행할 것을 권장했습니다. openclaw 설정 컨테이너 내부. 원 게시자는 마지막 지침 이후 최종 확인을 게시하지 않았으므로, 페이지에서 출처에 없는 검증된 해결을 주장해서는 안 됩니다.
