- Podman が Gateway コンテナを実行します。
- ホストの
openclawCLI がコントロールプレーンです。 - 永続状態はデフォルトでホスト上の
~/.openclaw配下に置かれます。 - 日常的な管理では、
sudo -u openclaw、podman exec、または別のサービスユーザーではなく、openclaw --container <name> ...を使用します。
前提条件
- rootless モードの Podman
- ホストにインストール済みの OpenClaw CLI
- 任意: Quadlet 管理の自動起動が必要な場合は
systemd --user - 任意: ヘッドレスホストで起動時の永続化に
loginctl enable-linger "$(whoami)"を使いたい場合のみsudo
クイックスタート
初回セットアップ
リポジトリルートから
代わりに Quadlet 管理のセットアップを使用する場合（Linux + systemd ユーザーサービスのみ）:または
./scripts/podman/setup.sh を実行します。これにより、rootless Podman ストアに openclaw:local がビルドされます（OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE が設定されている場合はそれを pull します）。また、存在しない場合は gateway.mode: "local" を含む ~/.openclaw/openclaw.json を作成し、存在しない場合は生成された OPENCLAW_GATEWAY_TOKEN を含む ~/.openclaw/.env を作成します。任意のビルド時環境変数:| 変数 | 効果 |
|---|---|
OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE | openclaw:local をビルドする代わりに、既存または pull 済みのイメージを使用します |
OPENCLAW_IMAGE_APT_PACKAGES | イメージビルド中に追加の apt パッケージをインストールします（レガシーの OPENCLAW_DOCKER_APT_PACKAGES も受け付けます） |
OPENCLAW_IMAGE_PIP_PACKAGES | イメージビルド中に追加の Python パッケージをインストールします。バージョンを固定し、信頼できるパッケージインデックスのみを使用してください |
OPENCLAW_EXTENSIONS | ビルド時に Plugin 依存関係を事前インストールします |
OPENCLAW_INSTALL_BROWSER | ブラウザー自動化用に Chromium と Xvfb を事前インストールします（1 に設定） |
OPENCLAW_PODMAN_QUADLET=1 を設定します。コンテナ内でオンボーディングを実行する
http://127.0.0.1:18789/ を開き、~/.openclaw/.env のトークンを使用します。モデル認証: セットアップ中は OpenClaw 管理の認証を使用します（Anthropic API キー、または Codex-backed OpenAI 用の OpenAI Codex ブラウザー OAuth/device-code 認証）。Podman ランチャーは、~/.claude や ~/.codex などのホスト CLI 認証情報ホームをセットアップコンテナや Gateway コンテナにマウントしません。既存のホスト CLI ログインは同一ホスト上の利便性のためのパスにすぎません。コンテナインストールでは、プロバイダー認証をセットアップが管理する、マウント済みの ~/.openclaw 状態に保持してください。ホスト CLI から実行中のコンテナを管理する
openclaw コマンドはそのコンテナ内で自動的に実行されます。~/.openclaw/.env から Podman 関連キーの小さな allowlist のみを読み取り、明示的なランタイム環境変数をコンテナに渡します。環境ファイル全体を Podman に渡すことはありません。
Podman と Tailscale
HTTPS またはリモートブラウザーアクセスについては、メインの Tailscale ドキュメントに従ってください。 Podman 固有の注意点:- Podman の publish host は
127.0.0.1のままにします。 openclaw gateway --tailscale serveよりも、ホスト管理のtailscale serveを推奨します。- macOS でローカルブラウザーのデバイス認証コンテキストが不安定な場合は、その場しのぎのローカルトンネル回避策ではなく Tailscale アクセスを使用してください。
Systemd（Quadlet、任意）
./scripts/podman/setup.sh --quadlet を実行した場合、セットアップは Quadlet ファイルを ~/.config/containers/systemd/openclaw.container にインストールします。
| 操作 | コマンド |
|---|---|
| 起動 | systemctl --user start openclaw.service |
| 停止 | systemctl --user stop openclaw.service |
| 状態 | systemctl --user status openclaw.service |
| ログ | journalctl --user -u openclaw.service -f |
127.0.0.1（18789 Gateway、18790 bridge）、コンテナ内は --bind lan、keep-id ユーザー名前空間、OPENCLAW_NO_RESPAWN=1、Restart=on-failure、TimeoutStartSec=300 です。OPENCLAW_GATEWAY_TOKEN などの値について、ランタイム EnvironmentFile として ~/.openclaw/.env を読み取りますが、手動ランチャーの Podman 固有 override allowlist は消費しません。カスタムの公開ポート、publish host、またはその他の container-run フラグを使う場合は、代わりに手動ランチャーを使用するか、~/.config/containers/systemd/openclaw.container を直接編集してからサービスを reload して restart してください。
設定、環境変数、ストレージ
- 設定ディレクトリ:
~/.openclaw - ワークスペースディレクトリ:
~/.openclaw/workspace - トークンファイル:
~/.openclaw/.env - 起動ヘルパー:
./scripts/run-openclaw-podman.sh
OPENCLAW_CONFIG_DIR -> /home/node/.openclaw、OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace です。デフォルトではこれらは匿名コンテナ状態ではなくホストディレクトリであるため、openclaw.json、エージェントごとの auth-profiles.json、チャネル/プロバイダー状態、セッション、ワークスペースはコンテナを置き換えても残ります。セットアップは、ローカルダッシュボードがコンテナの非 loopback bind で動作するよう、公開された Gateway ポート上の 127.0.0.1 と localhost に対して gateway.controlUi.allowedOrigins も seed します。
手動ランチャーで有用な環境変数（これらは ~/.openclaw/.env に永続化してください。ランチャーはコンテナ/イメージのデフォルトを確定する前にこのファイルを読み取ります）:
| 変数 | デフォルト | 効果 |
|---|---|---|
OPENCLAW_PODMAN_CONTAINER | openclaw | コンテナ名 |
OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGE | openclaw:local | 実行するイメージ |
OPENCLAW_PODMAN_GATEWAY_HOST_PORT | 18789 | コンテナの 18789 にマップされるホストポート |
OPENCLAW_PODMAN_BRIDGE_HOST_PORT | 18790 | コンテナの 18790 にマップされるホストポート |
OPENCLAW_PODMAN_PUBLISH_HOST | 127.0.0.1 | 公開ポート用のホストインターフェース |
OPENCLAW_GATEWAY_BIND | lan | コンテナ内の Gateway bind モード |
OPENCLAW_PODMAN_USERNS | keep-id | keep-id、auto、または host |
OPENCLAW_CONFIG_DIR または OPENCLAW_WORKSPACE_DIR を使用する場合は、./scripts/podman/setup.sh と、その後の ./scripts/run-openclaw-podman.sh launch コマンドの両方に同じ変数を設定してください。リポジトリローカルのランチャーは、シェルをまたいでカスタムパス override を永続化しません。
便利なコマンド
- コンテナログ:
podman logs -f openclaw - コンテナを停止:
podman stop openclaw - コンテナを削除:
podman rm -f openclaw - ホスト CLI からダッシュボード URL を開く:
openclaw dashboard --no-open - ホスト CLI 経由のヘルス/状態:
openclaw gateway status --deep（RPC probe + 追加サービススキャン）
トラブルシューティング
- 設定またはワークスペースで Permission denied（EACCES）: コンテナはデフォルトで
--userns=keep-idと--user <your uid>:<your gid>を使って実行されます。ホストの設定/ワークスペースパスが現在のユーザーの所有であることを確認してください。 - Gateway 起動がブロックされる（
gateway.mode=localがない）:~/.openclaw/openclaw.jsonが存在し、gateway.mode="local"を設定していることを確認してください。存在しない場合、scripts/podman/setup.shがこれを作成します。 - コンテナ CLI コマンドが間違ったターゲットに当たる:
openclaw --container <name> ...を明示的に使用するか、シェルでOPENCLAW_CONTAINER=<name>を export してください。 openclaw updateが--containerで失敗する: 想定どおりです。イメージを rebuild/pull してから、コンテナまたは Quadlet サービスを再起動してください。- Quadlet サービスが起動しない:
systemctl --user daemon-reloadを実行してから、systemctl --user start openclaw.serviceを実行します。ヘッドレスシステムでは、sudo loginctl enable-linger "$(whoami)"も必要になる場合があります。 - SELinux が bind mount をブロックする: デフォルトの mount 動作はそのままにしてください。SELinux が enforcing または permissive の Linux では、ランチャーが自動的に
:Zを追加します。