Podman

Podman 문서는 OpenClaw 공식 문서(install/podman)를 한국어로 정리한 가이드입니다. Run OpenClaw in a rootless Podman container 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Run OpenClaw in a rootless Podman container

한국어 가이드 범위: install/podman 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

사전 요구사항
빠른 시작
Podman and Tailscale
Systemd (Quadlet, optional)
Config, env, and storage
Upgrading images
Useful commands
트러블슈팅
관련 문서

상세 내용

본문

Run the OpenClaw Gateway in a rootless Podman container, managed by your current non-root user.

주요 항목:

Podman runs the gateway container.
Your host openclaw CLI is the control plane.
Persistent state lives on the host under ~/.openclaw by default.
Day-to-day management uses openclaw --container <name> ... instead of sudo -u openclaw, podman exec, or a separate service user.

사전 요구사항

주요 항목:

Podman in rootless mode
OpenClaw CLI installed on the host
**선택: ** systemd --user if you want Quadlet-managed auto-start
**선택: ** sudo only if you want loginctl enable-linger "$(whoami)" for boot persistence on a headless host

빠른 시작

From the repo root, run ./scripts/podman/setup.sh.

./scripts/podman/setup.sh --quadlet

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

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

export OPENCLAW_CONTAINER=openclaw

Podman and Tailscale

For HTTPS or remote browser access, follow the main Tailscale docs.

주요 항목:

Keep the Podman publish host at 127.0.0.1.
Prefer host-managed tailscale serve over openclaw gateway --tailscale serve.
On macOS, if local browser device-auth context is unreliable, use Tailscale access instead of ad hoc local tunnel workarounds.

Systemd (Quadlet, optional)

If you ran ./scripts/podman/setup.sh --quadlet, setup installs a Quadlet file at ~/.config/containers/systemd/openclaw.container.

Action	Command
Start	`systemctl --user start openclaw.service`
Stop	`systemctl --user stop openclaw.service`
Status	`systemctl --user status openclaw.service`
Logs	`journalctl --user -u openclaw.service -f`

systemctl --user daemon-reload
systemctl --user restart openclaw.service

sudo loginctl enable-linger "$(whoami)"

Config, env, and storage

The launch script and Quadlet bind-mount host state into the container: OPENCLAW_CONFIG_DIR -> /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace. By default those are host directories, not anonymous container state, so openclaw.json, per-agent auth-profiles.json, channel/provider state, sessions, and workspace survive container replacement. Setup also seeds gateway.controlUi.allowedOrigins for 127.0.0.1 and localhost on the published gateway port so the local dashboard works with the container's non-loopback bind.

주요 항목:

Config dir: ~/.openclaw
Workspace dir: ~/.openclaw/workspace
Token file: ~/.openclaw/.env
Launch helper: ./scripts/run-openclaw-podman.sh

Var	Default	Effect
`OPENCLAW_PODMAN_CONTAINER`	`openclaw`	Container name
`OPENCLAW_PODMAN_IMAGE` / `OPENCLAW_IMAGE`	`openclaw:local`	Image to run
`OPENCLAW_PODMAN_GATEWAY_HOST_PORT`	`18789`	Host port mapped to container `18789`
`OPENCLAW_PODMAN_BRIDGE_HOST_PORT`	`18790`	Host port mapped to container `18790`
`OPENCLAW_PODMAN_PUBLISH_HOST`	`127.0.0.1`	Host interface for published ports
`OPENCLAW_GATEWAY_BIND`	`lan`	Gateway bind mode inside the container
`OPENCLAW_PODMAN_USERNS`	`keep-id`	`keep-id`, `auto`, or `host`

Upgrading images

After you rebuild or pull a new image, restart the container or Quadlet service. On first startup for a new OpenClaw version, the gateway runs safe state and plugin repairs before reporting ready.

OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"
OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-$OPENCLAW_CONFIG_DIR/workspace}"
OPENCLAW_PODMAN_IMAGE="${OPENCLAW_PODMAN_IMAGE:-${OPENCLAW_IMAGE:-openclaw:local}}"

podman run --rm -it \
  --userns=keep-id \
  --user "$(id -u):$(id -g)" \
  -e HOME=/home/node \
  -e NPM_CONFIG_CACHE=/home/node/.openclaw/.npm \
  -v "$OPENCLAW_CONFIG_DIR:/home/node/.openclaw:rw" \
  -v "$OPENCLAW_WORKSPACE_DIR:/home/node/.openclaw/workspace:rw" \
  "$OPENCLAW_PODMAN_IMAGE" \
  openclaw doctor --fix

Useful commands

주요 항목:

Container logs: podman logs -f openclaw
Stop container: podman stop openclaw
Remove container: podman rm -f openclaw
Open dashboard URL from host CLI: openclaw dashboard --no-open
Health/status via host CLI: openclaw gateway status --deep (RPC probe + extra service scan)

트러블슈팅

주요 항목:

Permission denied (EACCES) on config or workspace: The container runs with --userns=keep-id and --user <your uid>:<your gid> by default. Ensure the host config/workspace paths are owned by your current user.
Gateway start blocked (missing gateway.mode=local): Ensure ~/.openclaw/openclaw.json exists and sets gateway.mode="local". scripts/podman/setup.sh creates this if missing.
Container restarts after an image update: Run the one-off openclaw doctor --fix command in Upgrading images, then start the gateway again.
Container CLI commands hit the wrong target: Use openclaw --container <name> ... explicitly, or export OPENCLAW_CONTAINER=<name> in your shell.
openclaw update fails with --container: Expected. Rebuild/pull the image, then restart the container or the Quadlet service.
Quadlet service does not start: Run systemctl --user daemon-reload, then systemctl --user start openclaw.service. On headless systems you may also need sudo loginctl enable-linger "$(whoami)".
SELinux blocks bind mounts: Leave the default mount behavior alone; the launcher auto-adds :Z on Linux when SELinux is enforcing or permissive.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/podman
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

./scripts/podman/setup.sh --quadlet

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

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

export OPENCLAW_CONTAINER=openclaw

openclaw dashboard --no-open
    openclaw gateway status --deep   # includes extra service scan
    openclaw doctor
    openclaw channels login

systemctl --user daemon-reload
systemctl --user restart openclaw.service

Podman

핵심 요약

Run OpenClaw in a rootless Podman container

한국어 가이드 범위: install/podman 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

사전 요구사항
빠른 시작
Podman and Tailscale
Systemd (Quadlet, optional)
Config, env, and storage
Upgrading images
Useful commands
트러블슈팅
관련 문서

상세 내용

본문

Run the OpenClaw Gateway in a rootless Podman container, managed by your current non-root user.

주요 항목:

Podman runs the gateway container.
Your host openclaw CLI is the control plane.
Persistent state lives on the host under ~/.openclaw by default.
Day-to-day management uses openclaw --container <name> ... instead of sudo -u openclaw, podman exec, or a separate service user.

사전 요구사항

주요 항목:

Podman in rootless mode
OpenClaw CLI installed on the host
**선택: ** systemd --user if you want Quadlet-managed auto-start
**선택: ** sudo only if you want loginctl enable-linger "$(whoami)" for boot persistence on a headless host

빠른 시작

From the repo root, run ./scripts/podman/setup.sh.

./scripts/podman/setup.sh --quadlet

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

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

export OPENCLAW_CONTAINER=openclaw

Podman and Tailscale

For HTTPS or remote browser access, follow the main Tailscale docs.

주요 항목:

Keep the Podman publish host at 127.0.0.1.
Prefer host-managed tailscale serve over openclaw gateway --tailscale serve.
On macOS, if local browser device-auth context is unreliable, use Tailscale access instead of ad hoc local tunnel workarounds.

Systemd (Quadlet, optional)

If you ran ./scripts/podman/setup.sh --quadlet, setup installs a Quadlet file at ~/.config/containers/systemd/openclaw.container.

Action	Command
Start	`systemctl --user start openclaw.service`
Stop	`systemctl --user stop openclaw.service`
Status	`systemctl --user status openclaw.service`
Logs	`journalctl --user -u openclaw.service -f`

systemctl --user daemon-reload
systemctl --user restart openclaw.service

sudo loginctl enable-linger "$(whoami)"

Config, env, and storage

주요 항목:

Config dir: ~/.openclaw
Workspace dir: ~/.openclaw/workspace
Token file: ~/.openclaw/.env
Launch helper: ./scripts/run-openclaw-podman.sh

Var	Default	Effect
`OPENCLAW_PODMAN_CONTAINER`	`openclaw`	Container name
`OPENCLAW_PODMAN_IMAGE` / `OPENCLAW_IMAGE`	`openclaw:local`	Image to run
`OPENCLAW_PODMAN_GATEWAY_HOST_PORT`	`18789`	Host port mapped to container `18789`
`OPENCLAW_PODMAN_BRIDGE_HOST_PORT`	`18790`	Host port mapped to container `18790`
`OPENCLAW_PODMAN_PUBLISH_HOST`	`127.0.0.1`	Host interface for published ports
`OPENCLAW_GATEWAY_BIND`	`lan`	Gateway bind mode inside the container
`OPENCLAW_PODMAN_USERNS`	`keep-id`	`keep-id`, `auto`, or `host`

Upgrading images

After you rebuild or pull a new image, restart the container or Quadlet service. On first startup for a new OpenClaw version, the gateway runs safe state and plugin repairs before reporting ready.

OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"
OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-$OPENCLAW_CONFIG_DIR/workspace}"
OPENCLAW_PODMAN_IMAGE="${OPENCLAW_PODMAN_IMAGE:-${OPENCLAW_IMAGE:-openclaw:local}}"

podman run --rm -it \
  --userns=keep-id \
  --user "$(id -u):$(id -g)" \
  -e HOME=/home/node \
  -e NPM_CONFIG_CACHE=/home/node/.openclaw/.npm \
  -v "$OPENCLAW_CONFIG_DIR:/home/node/.openclaw:rw" \
  -v "$OPENCLAW_WORKSPACE_DIR:/home/node/.openclaw/workspace:rw" \
  "$OPENCLAW_PODMAN_IMAGE" \
  openclaw doctor --fix

Useful commands

주요 항목:

Container logs: podman logs -f openclaw
Stop container: podman stop openclaw
Remove container: podman rm -f openclaw
Open dashboard URL from host CLI: openclaw dashboard --no-open
Health/status via host CLI: openclaw gateway status --deep (RPC probe + extra service scan)

트러블슈팅

주요 항목:

Permission denied (EACCES) on config or workspace: The container runs with --userns=keep-id and --user <your uid>:<your gid> by default. Ensure the host config/workspace paths are owned by your current user.
Gateway start blocked (missing gateway.mode=local): Ensure ~/.openclaw/openclaw.json exists and sets gateway.mode="local". scripts/podman/setup.sh creates this if missing.
Container restarts after an image update: Run the one-off openclaw doctor --fix command in Upgrading images, then start the gateway again.
Container CLI commands hit the wrong target: Use openclaw --container <name> ... explicitly, or export OPENCLAW_CONTAINER=<name> in your shell.
openclaw update fails with --container: Expected. Rebuild/pull the image, then restart the container or the Quadlet service.
Quadlet service does not start: Run systemctl --user daemon-reload, then systemctl --user start openclaw.service. On headless systems you may also need sudo loginctl enable-linger "$(whoami)".
SELinux blocks bind mounts: Leave the default mount behavior alone; the launcher auto-adds :Z on Linux when SELinux is enforcing or permissive.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/podman
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

./scripts/podman/setup.sh --quadlet

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

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

export OPENCLAW_CONTAINER=openclaw

openclaw dashboard --no-open
    openclaw gateway status --deep   # includes extra service scan
    openclaw doctor
    openclaw channels login

systemctl --user daemon-reload
systemctl --user restart openclaw.service

Podman

핵심 요약

문서 구성

상세 내용

본문

사전 요구사항

빠른 시작

Podman and Tailscale

Systemd (Quadlet, optional)

Config, env, and storage

Upgrading images

Useful commands

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Podman

핵심 요약

문서 구성

상세 내용

본문

사전 요구사항

빠른 시작

Podman and Tailscale

Systemd (Quadlet, optional)

Config, env, and storage

Upgrading images

Useful commands

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드