Podman

루트리스 Podman 컨테이너에서 OpenClaw 게이트웨이를 실행합니다. Docker와 동일한 이미지를 사용합니다(저장소 Dockerfile에서 빌드).

요구사항

Podman (루트리스)
일회성 설정(사용자 생성, 이미지 빌드)을 위한 Sudo

빠른 시작

1. 일회성 설정 (저장소 루트에서 실행; 사용자 생성, 이미지 빌드, 실행 스크립트 설치):

./setup-podman.sh

게이트웨이가 마법사 없이 시작할 수 있도록 최소한의 ~openclaw/.openclaw/openclaw.json(gateway.mode="local" 설정)도 생성합니다.

기본적으로 컨테이너는 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. 게이트웨이 시작 (수동, 빠른 스모크 테스트용):

./scripts/run-openclaw-podman.sh launch

3. 온보딩 마법사 (채널이나 프로바이더 추가 등):

./scripts/run-openclaw-podman.sh launch setup

이후 http://127.0.0.1:18789/를 열고 ~openclaw/.openclaw/.env의 토큰(또는 설정에서 출력된 값)을 사용합니다.

Systemd (Quadlet, 선택사항)

./setup-podman.sh --quadlet(또는 OPENCLAW_PODMAN_QUADLET=1)을 실행했다면, Podman Quadlet 유닛이 설치되어 게이트웨이가 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 -f

Quadlet 파일은 ~openclaw/.config/containers/systemd/openclaw.container에 있습니다. 포트나 환경을 변경하려면 해당 파일(또는 소스하는 .env)을 편집한 뒤 sudo systemctl --machine openclaw@ --user daemon-reload하고 서비스를 재시작하세요. 부팅 시 openclaw에 대한 링거링이 활성화되어 있으면(설정 시 loginctl이 사용 가능한 경우 자동으로 설정) 서비스가 자동으로 시작됩니다.

Quadlet을 사용하지 않은 초기 설정 이후에 추가하려면: ./setup-podman.sh --quadlet을 다시 실행하세요.

openclaw 사용자 (비로그인)

setup-podman.sh는 전용 시스템 사용자 openclaw을 생성합니다:

쉘: nologin — 대화형 로그인 없음. 공격 표면을 줄입니다.
홈: 예: /home/openclaw — ~/.openclaw(설정, 워크스페이스)과 실행 스크립트 run-openclaw-podman.sh를 보관합니다.
루트리스 Podman: 사용자에게 subuid와 subgid 범위가 있어야 합니다. 많은 배포판에서 사용자 생성 시 자동으로 할당합니다. 설정에서 경고가 출력되면 /etc/subuid와 /etc/subgid에 줄을 추가하세요:
```
openclaw:100000:65536
```
해당 사용자로 게이트웨이를 시작합니다(예: cron이나 systemd에서):
```
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup
```
설정: openclaw과 root만 /home/openclaw/.openclaw에 접근할 수 있습니다. 설정을 편집하려면: 게이트웨이가 실행 중일 때 Control UI를 사용하거나, sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json.

환경 및 설정

토큰: ~openclaw/.openclaw/.env에 OPENCLAW_GATEWAY_TOKEN으로 저장됩니다. setup-podman.sh와 run-openclaw-podman.sh가 없으면 생성합니다(openssl, python3, 또는 od 사용).
선택사항: .env에서 프로바이더 키(예: GROQ_API_KEY, OLLAMA_API_KEY)와 기타 OpenClaw 환경 변수를 설정할 수 있습니다.
호스트 포트: 기본적으로 스크립트는 18789(게이트웨이)와 18790(브릿지)를 매핑합니다. 실행 시 OPENCLAW_PODMAN_GATEWAY_HOST_PORT와 OPENCLAW_PODMAN_BRIDGE_HOST_PORT로 호스트 포트 매핑을 재정의할 수 있습니다.
게이트웨이 바인드: 기본적으로 run-openclaw-podman.sh는 안전한 로컬 접근을 위해 --bind loopback으로 게이트웨이를 시작합니다. LAN에 노출하려면 OPENCLAW_GATEWAY_BIND=lan을 설정하고 openclaw.json에서 gateway.controlUi.allowedOrigins를 설정하세요(또는 호스트 헤더 폴백을 명시적으로 활성화).
경로: 호스트 설정과 워크스페이스의 기본값은 ~openclaw/.openclaw과 ~openclaw/.openclaw/workspace입니다. 실행 스크립트에서 사용하는 호스트 경로를 OPENCLAW_CONFIG_DIR과 OPENCLAW_WORKSPACE_DIR로 재정의할 수 있습니다.

스토리지 모델

영구 호스트 데이터: OPENCLAW_CONFIG_DIR과 OPENCLAW_WORKSPACE_DIR이 컨테이너에 바인드 마운트되어 호스트에 상태를 유지합니다.
임시 샌드박스 tmpfs: agents.defaults.sandbox를 활성화하면, 도구 샌드박스 컨테이너가 /tmp, /var/tmp, /run에 tmpfs를 마운트합니다. 이 경로는 메모리 기반이며 샌드박스 컨테이너와 함께 사라집니다. 최상위 Podman 컨테이너 설정은 자체 tmpfs 마운트를 추가하지 않습니다.
디스크 증가 핫스팟: 주로 감시할 경로는 media/, agents/<agentId>/sessions/sessions.json, 트랜스크립트 JSONL 파일, cron/runs/*.jsonl, /tmp/openclaw/(또는 설정된 logging.file) 아래의 롤링 파일 로그입니다.

setup-podman.sh는 이제 비공개 임시 디렉토리에 이미지 tar를 스테이징하고 설정 중 선택된 기본 디렉토리를 출력합니다. 비루트 실행에서는 기본 디렉토리가 안전할 때만 TMPDIR을 수락하며, 그렇지 않으면 /var/tmp, /tmp 순으로 폴백합니다. 저장된 tar는 소유자 전용이며 대상 사용자의 podman load로 스트리밍되므로 비공개 호출자 임시 디렉토리가 설정을 차단하지 않습니다.

유용한 명령어

로그: 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 — 호스트의 설정과 워크스페이스는 유지됩니다

문제 해결

설정 또는 auth-profiles에서 권한 거부 (EACCES): 컨테이너는 기본적으로 --userns=keep-id를 사용하고 스크립트를 실행하는 호스트 사용자와 동일한 uid/gid로 실행됩니다. 호스트의 OPENCLAW_CONFIG_DIR과 OPENCLAW_WORKSPACE_DIR이 해당 사용자 소유인지 확인하세요.
게이트웨이 시작 차단 (gateway.mode=local 누락): ~openclaw/.openclaw/openclaw.json이 존재하고 gateway.mode="local"이 설정되어 있는지 확인하세요. setup-podman.sh가 없으면 이 파일을 생성합니다.
루트리스 Podman이 openclaw 사용자에서 실패: /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를 표시해야 합니다.

선택사항: 자신의 사용자로 실행

전용 openclaw 사용자 없이 일반 사용자로 게이트웨이를 실행하려면: 이미지를 빌드하고, ~/.openclaw/.env에 OPENCLAW_GATEWAY_TOKEN을 생성하고, --userns=keep-id와 ~/.openclaw에 대한 마운트로 컨테이너를 실행하세요. 실행 스크립트는 openclaw 사용자 플로우를 위해 설계되었습니다. 단일 사용자 설정에서는 스크립트의 podman run 명령을 수동으로 실행하고 설정과 워크스페이스를 자신의 홈으로 지정할 수 있습니다. 대부분의 사용자에게 권장: setup-podman.sh를 사용하고 openclaw 사용자로 실행하여 설정과 프로세스를 격리하세요.