Skip to main content
Jalankan Gateway OpenClaw dalam kontainer Podman tanpa root, yang dikelola oleh pengguna non-root Anda saat ini. Modelnya:
  • Podman menjalankan kontainer Gateway.
  • CLI openclaw pada host Anda berfungsi sebagai bidang kendali.
  • Status persisten secara default disimpan pada host di bawah ~/.openclaw.
  • Pengelolaan sehari-hari menggunakan openclaw --container <name> ..., bukan sudo -u openclaw, podman exec, atau pengguna layanan terpisah.

​
Prasyarat

  • Podman dalam mode tanpa root
  • CLI OpenClaw terinstal pada host
  • Opsional: systemd --user jika Anda menginginkan mulai otomatis yang dikelola Quadlet
  • Opsional: sudo hanya jika Anda ingin menjalankan loginctl enable-linger "$(whoami)" agar tetap berjalan setelah boot pada host tanpa monitor

​
Mulai cepat

1

Penyiapan satu kali

Dari root repositori, jalankan ./scripts/podman/setup.sh.Perintah ini membangun openclaw:local di penyimpanan Podman tanpa root Anda (atau menarik OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE jika ditetapkan), membuat ~/.openclaw/openclaw.json dengan gateway.mode: "local" jika belum ada, dan membuat ~/.openclaw/.env dengan OPENCLAW_GATEWAY_TOKEN yang dihasilkan jika belum ada.Variabel lingkungan waktu pembangunan opsional:Untuk penyiapan yang dikelola Quadlet sebagai gantinya (khusus Linux + layanan pengguna systemd):
Atau tetapkan OPENCLAW_PODMAN_QUADLET=1.
2

Mulai kontainer Gateway

Memulai kontainer dengan uid/gid Anda saat ini menggunakan --userns=keep-id dan memasang-terikat status OpenClaw Anda ke dalam kontainer.
3

Jalankan orientasi awal di dalam kontainer

Kemudian buka http://127.0.0.1:18789/ dan gunakan token dari ~/.openclaw/.env.Autentikasi model: gunakan autentikasi yang dikelola OpenClaw selama penyiapan (kunci API Anthropic, atau autentikasi OAuth peramban/kode perangkat OpenAI Codex untuk OpenAI yang didukung Codex). Peluncur Podman tidak memasang direktori kredensial CLI host seperti ~/.claude atau ~/.codex ke dalam kontainer penyiapan atau Gateway. Login CLI host yang sudah ada hanya merupakan jalur kemudahan pada host yang sama — untuk instalasi kontainer, simpan autentikasi penyedia dalam status ~/.openclaw terpasang yang dikelola oleh penyiapan.
4

Kelola kontainer yang berjalan dari CLI host

Setelah itu, perintah openclaw biasa berjalan secara otomatis di dalam kontainer tersebut:
Di macOS, mesin Podman dapat membuat peramban tampak tidak lokal bagi Gateway. Jika UI Kontrol melaporkan kesalahan autentikasi perangkat setelah peluncuran, gunakan panduan Tailscale dalam Podman dan Tailscale.
Peluncur manual hanya membaca daftar izin kecil berisi kunci terkait Podman dari ~/.openclaw/.env dan meneruskan variabel lingkungan waktu jalan secara eksplisit ke kontainer; peluncur tidak menyerahkan seluruh berkas lingkungan kepada Podman.

​
Podman dan Tailscale

Untuk HTTPS atau akses peramban jarak jauh, ikuti dokumentasi utama Tailscale. Catatan khusus Podman:
  • Pertahankan host publikasi Podman pada 127.0.0.1.
  • Utamakan tailscale serve yang dikelola host daripada openclaw gateway --tailscale serve.
  • Di macOS, jika konteks autentikasi perangkat peramban lokal tidak dapat diandalkan, gunakan akses Tailscale sebagai pengganti solusi sementara terowongan lokal ad hoc.
Lihat Tailscale dan UI Kontrol.

​
Systemd (Quadlet, opsional)

Jika Anda menjalankan ./scripts/podman/setup.sh --quadlet, penyiapan menginstal berkas Quadlet di ~/.config/containers/systemd/openclaw.container. Setelah mengedit berkas Quadlet:
Agar tetap berjalan setelah boot pada host SSH/tanpa monitor, aktifkan lingering untuk pengguna Anda saat ini:
Layanan Quadlet yang dihasilkan mempertahankan bentuk bawaan tetap yang diperkeras: port yang dipublikasikan pada 127.0.0.1 (18789 untuk Gateway, 18790 untuk jembatan), --bind lan di dalam kontainer, ruang nama pengguna keep-id, OPENCLAW_NO_RESPAWN=1, Restart=on-failure, dan TimeoutStartSec=300. Layanan ini membaca ~/.openclaw/.env sebagai EnvironmentFile waktu jalan untuk nilai seperti OPENCLAW_GATEWAY_TOKEN, tetapi tidak menggunakan daftar izin penggantian khusus Podman milik peluncur manual. Untuk port publikasi khusus, host publikasi, atau flag lain saat menjalankan kontainer, gunakan peluncur manual sebagai gantinya, atau edit ~/.config/containers/systemd/openclaw.container secara langsung, lalu muat ulang dan mulai ulang layanan.

​
Konfigurasi, lingkungan, dan penyimpanan

  • Direktori konfigurasi: ~/.openclaw
  • Direktori ruang kerja: ~/.openclaw/workspace
  • Berkas token: ~/.openclaw/.env
  • Pembantu peluncuran: ./scripts/run-openclaw-podman.sh
Skrip peluncuran dan Quadlet memasang-terikat status host ke dalam kontainer: OPENCLAW_CONFIG_DIR -> /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace. Secara bawaan, lokasi tersebut merupakan direktori host, bukan status kontainer anonim, sehingga openclaw.json, auth-profiles.json per agen, status kanal/penyedia, sesi, dan ruang kerja tetap ada setelah kontainer diganti. Penyiapan juga mengisi awal gateway.controlUi.allowedOrigins untuk 127.0.0.1 dan localhost pada port Gateway yang dipublikasikan agar dasbor lokal berfungsi dengan pengikatan non-loopback kontainer. Variabel lingkungan yang berguna untuk peluncur manual (simpan secara persisten di ~/.openclaw/.env; peluncur membaca berkas tersebut sebelum menetapkan nilai bawaan akhir kontainer/citra): Jika Anda menggunakan OPENCLAW_CONFIG_DIR atau OPENCLAW_WORKSPACE_DIR nonbawaan, tetapkan variabel yang sama untuk perintah ./scripts/podman/setup.sh dan ./scripts/run-openclaw-podman.sh launch berikutnya — peluncur lokal repositori tidak menyimpan penggantian jalur khusus secara persisten antar-shell.

​
Memutakhirkan citra

Setelah Anda membangun ulang atau menarik citra baru, mulai ulang kontainer atau layanan Quadlet. Pada penyalaan pertama untuk versi OpenClaw baru, Gateway menjalankan perbaikan status dan plugin secara aman sebelum melaporkan bahwa sistem siap. Jika Gateway berhenti alih-alih menjadi siap, jalankan citra yang sama satu kali dengan openclaw doctor --fix terhadap status/konfigurasi terpasang yang sama, lalu mulai ulang Gateway secara normal:
Pada host SELinux, tambahkan ,Z ke kedua pemasangan terikat jika Podman memblokir akses ke status terpasang.

​
Perintah yang berguna

  • Log kontainer: podman logs -f openclaw
  • Hentikan kontainer: podman stop openclaw
  • Hapus kontainer: podman rm -f openclaw
  • Buka URL dasbor dari CLI host: openclaw dashboard --no-open
  • Kesehatan/status melalui CLI host: openclaw gateway status --deep (pemeriksaan RPC + pemindaian layanan tambahan)

​
Pemecahan masalah

  • Izin ditolak (EACCES) pada konfigurasi atau ruang kerja: Kontainer secara bawaan berjalan dengan --userns=keep-id dan --user <uid Anda>:<gid Anda>. Pastikan jalur konfigurasi/ruang kerja host dimiliki oleh pengguna Anda saat ini.
  • Mulainya Gateway diblokir (gateway.mode=local tidak ada): Pastikan ~/.openclaw/openclaw.json ada dan menetapkan gateway.mode="local". scripts/podman/setup.sh membuatnya jika belum ada.
  • Kontainer dimulai ulang setelah pembaruan citra: Jalankan perintah sekali pakai openclaw doctor --fix dalam Memutakhirkan citra, lalu mulai kembali Gateway.
  • Perintah CLI kontainer mengakses target yang salah: Gunakan openclaw --container <name> ... secara eksplisit, atau ekspor OPENCLAW_CONTAINER=<name> dalam shell Anda.
  • openclaw update gagal dengan --container: Ini sesuai harapan. Bangun ulang/tarik citra, lalu mulai ulang kontainer atau layanan Quadlet.
  • Layanan Quadlet tidak dimulai: Jalankan systemctl --user daemon-reload, lalu systemctl --user start openclaw.service. Pada sistem tanpa monitor, Anda mungkin juga perlu menjalankan sudo loginctl enable-linger "$(whoami)".
  • SELinux memblokir pemasangan terikat: Biarkan perilaku pemasangan bawaan apa adanya; peluncur secara otomatis menambahkan :Z di Linux ketika SELinux berada dalam mode enforcing atau permissive.

​
Terkait