Podman에서 OpenClaw 게이트웨이 실행하기: 빠른 설정 가이드
새로운 도구를 설치할 때 시스템이 지저분해지거나 보안 권한 때문에 고민한 적 있으신가요? OpenClaw를 더 안전하고 깔끔하게 관리하고 싶은 개발자분들을 위해 Podman을 활용한 설치 방법을 준비했습니다.
OpenClaw Gateway를 rootless Podman 컨테이너에서 실행해 보세요. Docker와 동일한 이미지를 사용하며, 저장소의 Dockerfile에서 직접 빌드하여 사용할 수 있습니다.
Requirements (요구 사항)
섹션 제목: “Requirements (요구 사항)”- Podman (rootless 모드)
- 초기 설정을 위한 Sudo 권한 (사용자 생성 및 이미지 빌드용)
Quick start (빠른 시작)
섹션 제목: “Quick start (빠른 시작)”1. 초기 설정 (저장소 루트에서 실행하며, 사용자를 생성하고 이미지를 빌드한 뒤 실행 스크립트를 설치합니다):
./setup-podman.sh이 과정에서 최소한의 ~openclaw/.openclaw/openclaw.json 파일이 생성되고 gateway.mode="local"로 설정됩니다. 덕분에 별도의 마법사 실행 없이도 Gateway를 바로 시작할 수 있어요.
기본적으로 컨테이너는 systemd 서비스로 설치되지 않으므로 수동으로 시작해야 합니다. 자동 시작이나 재시작 기능이 필요한 운영 환경이라면, 대신 systemd Quadlet 사용자 서비스로 설치해 보세요:
./setup-podman.sh --quadlet(또는 OPENCLAW_PODMAN_QUADLET=1을 설정해도 됩니다. 컨테이너와 실행 스크립트만 설치하려면 --container 옵션을 사용하세요.)
빌드 시 사용할 수 있는 선택적 환경 변수 (setup-podman.sh 실행 전 설정):
OPENCLAW_DOCKER_APT_PACKAGES— 이미지 빌드 중에 추가 apt 패키지를 설치합니다.OPENCLAW_EXTENSIONS— 확장 프로그램 의존성을 사전에 설치합니다 (공백으로 구분된 확장 프로그램 이름, 예:diagnostics-otel matrix).
2. Gateway 시작 (빠른 테스트를 위한 수동 실행):
./scripts/run-openclaw-podman.sh launch3. 온보딩 마법사 (채널이나 Provider를 추가하고 싶을 때):
./scripts/run-openclaw-podman.sh launch setup그 다음 http://127.0.0.1:18789/를 열고 ~openclaw/.openclaw/.env에 적힌 토큰(또는 설정 과정에서 출력된 값)을 입력하면 됩니다.
Systemd (Quadlet, 선택 사항)
섹션 제목: “Systemd (Quadlet, 선택 사항)”./setup-podman.sh --quadlet 또는 OPENCLAW_PODMAN_QUADLET=1 옵션으로 설치했다면, Podman Quadlet 유닛이 설치됩니다. 이를 통해 Gateway가 openclaw 사용자의 systemd 사용자 서비스로 실행되며, 설정 마지막 단계에서 서비스가 자동으로 활성화되고 시작됩니다.
# 시작sudo systemctl --machine openclaw@ --user start openclaw.service# 중지sudo systemctl --machine openclaw@ --user stop openclaw.service# 상태 확인sudo systemctl --machine openclaw@ --user status openclaw.service# 로그 확인sudo journalctl --machine openclaw@ --user -u openclaw.service -fQuadlet 파일은 ~openclaw/.config/containers/systemd/openclaw.container에 위치합니다. 포트나 환경 변수를 변경하려면 해당 파일(또는 파일이 참조하는 .env)을 수정한 뒤, sudo systemctl --machine openclaw@ --user daemon-reload를 실행하고 서비스를 재시작하세요. openclaw 사용자에 대해 lingering이 활성화되어 있다면(loginctl을 사용할 수 있는 환경에서 설정 시 처리됨) 부팅 시 서비스가 자동으로 시작됩니다.
초기 설정 당시에 Quadlet을 사용하지 않았다면, 나중에 ./setup-podman.sh --quadlet을 다시 실행하여 추가할 수 있습니다.
The openclaw user (non-login) (openclaw 사용자 (로그인 불가))
섹션 제목: “The openclaw user (non-login) (openclaw 사용자 (로그인 불가))”setup-podman.sh는 전용 시스템 사용자 계정인 openclaw를 생성합니다:
-
Shell:
nologin— 대화형 로그인을 제한하여 보안 공격 노출 면적을 줄입니다. -
Home: 예:
/home/openclaw— 설정과 workspace가 담긴~/.openclaw폴더와 실행 스크립트run-openclaw-podman.sh가 저장됩니다. -
Rootless Podman: 해당 사용자는 subuid와 subgid 범위를 가지고 있어야 합니다. 대부분의 배포판은 사용자 생성 시 이를 자동으로 할당하지만, 설정 중 경고가 나타나면
/etc/subuid와/etc/subgid에 다음 내용을 직접 추가해 주세요:openclaw:100000:65536그 후 해당 사용자로 Gateway를 시작할 수 있습니다 (예: cron 또는 systemd 사용 시):
Terminal window sudo -u openclaw /home/openclaw/run-openclaw-podman.shsudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup -
Config: 오직
openclaw사용자와 root만/home/openclaw/.openclaw에 접근할 수 있습니다. 설정을 수정하려면 Gateway 실행 후 Control UI를 이용하거나,sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json명령어를 사용하세요.
Environment and config (환경 및 설정)
섹션 제목: “Environment and config (환경 및 설정)”- Token:
~openclaw/.openclaw/.env파일에OPENCLAW_GATEWAY_TOKEN으로 저장됩니다.setup-podman.sh와run-openclaw-podman.sh는 토큰이 없을 경우 자동으로 생성합니다 (openssl,python3, 또는od활용). - 선택 사항: 해당
.env파일에서 Provider 키(예:GROQ_API_KEY,OLLAMA_API_KEY) 및 기타 OpenClaw 환경 변수를 설정할 수 있습니다. - Host ports: 기본적으로 스크립트는
18789(gateway)와18790(bridge) 포트를 매핑합니다. 실행 시OPENCLAW_PODMAN_GATEWAY_HOST_PORT와OPENCLAW_PODMAN_BRIDGE_HOST_PORT변수를 통해 호스트 포트 매핑을 변경할 수 있습니다. - Gateway bind: 기본적으로
run-openclaw-podman.sh는 안전한 로컬 접속을 위해--bind loopback옵션으로 시작합니다. LAN 환경에 노출하려면OPENCLAW_GATEWAY_BIND=lan으로 설정하고,openclaw.json에서gateway.controlUi.allowedOrigins를 구성하거나 host-header fallback을 명시적으로 활성화하세요. - Paths: 호스트의 설정 및 workspace 기본 경로는
~openclaw/.openclaw와~openclaw/.openclaw/workspace입니다. 실행 스크립트가 사용하는 호스트 경로는OPENCLAW_CONFIG_DIR및OPENCLAW_WORKSPACE_DIR변수로 덮어쓸 수 있습니다.
Storage model (스토리지 모델)
섹션 제목: “Storage model (스토리지 모델)”- 지속성 호스트 데이터:
OPENCLAW_CONFIG_DIR과OPENCLAW_WORKSPACE_DIR은 컨테이너에 bind-mount되어 호스트에 데이터가 유지됩니다. - 휘발성 sandbox tmpfs:
agents.defaults.sandbox를 활성화하면 도구 sandbox 컨테이너가/tmp,/var/tmp,/run경로에tmpfs를 마운트합니다. 이 경로들은 메모리에 저장되며 sandbox 컨테이너가 종료되면 사라집니다. 최상위 Podman 컨테이너 설정에는 자체적인 tmpfs 마운트가 추가되지 않습니다. - 디스크 사용량 주의 지점: 데이터가 쌓일 수 있는 주요 경로는
media/,agents/<agentId>/sessions/sessions.json, transcript JSONL 파일,cron/runs/*.jsonl, 그리고/tmp/openclaw/(또는 설정한logging.file) 아래의 롤링 로그 파일입니다.
setup-podman.sh는 이제 이미지 tar 파일을 비공개 임시 디렉토리에 준비하며, 설정 중에 선택된 베이스 디렉토리를 출력합니다. root가 아닌 실행 시에는 해당 베이스가 안전할 때만 TMPDIR을 사용하고, 그렇지 않으면 /var/tmp나 /tmp를 사용합니다. 저장된 tar 파일은 소유자만 접근 가능하며 대상 사용자의 podman load로 스트리밍되므로, 호출자의 비공개 임시 디렉토리 때문에 설정이 막히는 일이 없습니다.
Useful commands (유용한 명령어)
섹션 제목: “Useful commands (유용한 명령어)”- 로그 확인: Quadlet 사용 시:
sudo journalctl --machine openclaw@ --user -u openclaw.service -f. 스크립트 사용 시:sudo -u openclaw podman logs -f openclaw - 중지: Quadlet 사용 시:
sudo systemctl --machine openclaw@ --user stop openclaw.service. 스크립트 사용 시:sudo -u openclaw podman stop openclaw - 다시 시작: Quadlet 사용 시:
sudo systemctl --machine openclaw@ --user start openclaw.service. 스크립트 사용 시: 실행 스크립트를 다시 실행하거나podman start openclaw - 컨테이너 제거:
sudo -u openclaw podman rm -f openclaw— 호스트에 저장된 설정과 workspace는 삭제되지 않고 유지됩니다.
Troubleshooting (문제 해결)
섹션 제목: “Troubleshooting (문제 해결)”- 설정 또는 auth-profiles 권한 거부 (EACCES): 컨테이너는 기본적으로
--userns=keep-id옵션을 사용하며 스크립트를 실행하는 호스트 사용자와 동일한 uid/gid로 실행됩니다. 호스트의OPENCLAW_CONFIG_DIR및OPENCLAW_WORKSPACE_DIR소유권이 해당 사용자에게 있는지 확인하세요. - Gateway 시작 차단 (
gateway.mode=local누락):~openclaw/.openclaw/openclaw.json파일이 존재하고gateway.mode="local"로 설정되어 있는지 확인하세요.setup-podman.sh는 이 파일이 없으면 자동으로 생성해 줍니다. - openclaw 사용자의 Rootless Podman 실패:
/etc/subuid와/etc/subgid에openclaw사용자에 대한 설정(예:openclaw:100000:65536)이 있는지 확인하세요. 없다면 추가하고 시스템을 재시작하세요. - 컨테이너 이름 중복: 실행 스크립트는
podman run --replace를 사용하므로 다시 시작할 때 기존 컨테이너를 자동으로 교체합니다. 수동으로 정리하려면podman rm -f openclaw를 실행하세요. - openclaw 사용자로 실행 시 스크립트를 찾을 수 없음:
setup-podman.sh가 정상적으로 실행되어run-openclaw-podman.sh가 openclaw의 홈 디렉토리(예:/home/openclaw/run-openclaw-podman.sh)로 복사되었는지 확인하세요. - Quadlet 서비스를 찾을 수 없거나 시작 실패:
.container파일을 수정한 후에는 반드시sudo systemctl --machine openclaw@ --user daemon-reload를 실행해야 합니다. 또한 Quadlet은 cgroups v2가 필요하므로,podman info --format '{{.Host.CgroupsVersion}}'명령어로2가 출력되는지 확인하세요.
Optional: run as your own user (선택 사항: 본인 계정으로 실행)
섹션 제목: “Optional: run as your own user (선택 사항: 본인 계정으로 실행)”별도의 openclaw 사용자 없이 본인의 일반 계정으로 Gateway를 실행하고 싶다면, 이미지를 직접 빌드하고 OPENCLAW_GATEWAY_TOKEN이 포함된 ~/.openclaw/.env를 생성하세요. 그 후 --userns=keep-id 옵션과 본인의 ~/.openclaw를 마운트하는 설정을 추가하여 컨테이너를 실행하면 됩니다. 제공되는 실행 스크립트는 openclaw 사용자 흐름에 최적화되어 있으므로, 개인 계정 설정 시에는 스크립트 내의 podman run 명령어를 참고하여 수동으로 실행하는 것을 권장합니다. 하지만 대부분의 경우에는 설정과 프로세스가 깔끔하게 격리되는 setup-podman.sh 방식(openclaw 사용자 실행)을 추천드려요.
OpenClaw Expert
아직 막혀 있나요?
이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.