openclaw update

Perbarui OpenClaw dan beralih antara saluran stable/extended-stable/beta/dev.

Jika Anda menginstal melalui npm/pnpm/bun (instalasi global, tanpa metadata git), pembaruan dilakukan melalui alur pengelola paket yang dijelaskan dalam Memperbarui.

Penggunaan

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel extended-stableopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --tag mainopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --acknowledge-clawhub-riskopenclaw update --jsonopenclaw --update

openclaw --update ditulis ulang menjadi openclaw update (berguna untuk shell dan skrip peluncur).

Opsi

Tidak ada flag --verbose. Gunakan --dry-run untuk melihat pratinjau tindakan yang direncanakan, --json untuk hasil yang dapat dibaca mesin, dan openclaw update status --json hanya untuk saluran/ketersediaan. Verbositas konsol Gateway (--verbose) dan tingkat log berkas (logging.level: "debug"/"trace") merupakan pengaturan terpisah; lihat Pencatatan log Gateway.

update status

Tampilkan saluran pembaruan aktif, tag/cabang/SHA git (hanya checkout sumber), dan ketersediaan pembaruan.

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

Untuk instalasi paket extended-stable, status menjalankan pemilih publik dan verifikasi paket persis yang sama seperti pembaruan latar depan. Status dapat melaporkan ahead of extended-stable ketika versi yang terinstal lebih baru. Kegagalan JSON mencakup registry.reason (selector_missing, selector_query_failed, exact_package_mismatch, atau unsupported_git_channel).

update repair

Jalankan kembali finalisasi pembaruan setelah paket inti berubah tetapi pekerjaan perbaikan berikutnya tidak selesai dengan baik. Ini adalah jalur pemulihan yang didukung ketika openclaw update menginstal paket inti baru, tetapi sinkronisasi plugin pascainti, metadata plugin npm terkelola, penyegaran registri, atau perbaikan Doctor tidak mencapai kondisi konvergen.

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json

update repair menjalankan openclaw doctor --fix, memuat ulang konfigurasi yang diperbaiki dan catatan instalasi, menyinkronkan plugin terlacak untuk saluran pembaruan aktif, memperbarui instalasi plugin npm terkelola, memperbaiki payload plugin terkonfigurasi yang hilang, menyegarkan registri plugin, dan menulis metadata catatan instalasi yang telah konvergen. Proses ini tidak menginstal paket inti baru dan tidak memulai ulang Gateway.

update wizard

Alur interaktif untuk memilih saluran pembaruan dan mengonfirmasi apakah Gateway akan dimulai ulang setelahnya (default-nya memulai ulang). Memilih dev tanpa checkout git menawarkan pembuatan checkout.

Cara kerjanya

Beralih saluran secara eksplisit (--channel ...) juga menjaga metode instalasi tetap selaras:

• dev -> memastikan adanya checkout git (default ~/openclaw, atau $OPENCLAW_HOME/openclaw ketika OPENCLAW_HOME ditetapkan; ganti dengan OPENCLAW_GIT_DIR), memperbaruinya, dan menginstal CLI global dari checkout tersebut.
• stable -> menginstal dari npm menggunakan latest.
• extended-stable -> menyelesaikan pemilih npm publik extended-stable, memverifikasi paket persis yang dipilih, dan menginstal versi persis tersebut. Proses ini tidak beralih ke pemilih lain sebagai fallback dan ditolak untuk checkout Git.
• beta -> mengutamakan dist-tag npm beta, dengan fallback ke latest ketika beta tidak tersedia atau lebih lama daripada rilis stable saat ini.

Serah terima mulai ulang

Pembaruan otomatis inti Gateway (ketika diaktifkan melalui konfigurasi) meluncurkan jalur pembaruan CLI di luar penangan permintaan Gateway yang aktif. Pembaruan pengelola paket bidang kontrol update.run dan pembaruan checkout git yang diawasi menggunakan serah terima layanan terkelola yang sama, alih-alih mengganti pohon paket atau membangun ulang dist/ di dalam proses Gateway yang aktif: Gateway memulai pembantu terpisah lalu keluar, dan pembantu tersebut menjalankan openclaw update --yes --json dari luar pohon proses Gateway. Jika serah terima tidak tersedia, update.run mengembalikan respons terstruktur berisi perintah shell aman untuk dijalankan secara manual.

Pilihan extended-stable yang tersimpan menerima petunjuk startup hanya-baca dan pembaruan 24 jam ketika update.checkOnStart diaktifkan. Pemeriksaan ini tidak pernah menerapkan pembaruan, memulai handoff, memulai ulang Gateway, menggunakan penundaan/jitter stable, atau menggunakan frekuensi polling beta. Pembaruan foreground eksplisit, pembaruan foreground tanpa argumen dengan update.channel: "extended-stable" tersimpan, status sesuai permintaan, dan handoff Gateway terkelolanya tetap didukung.

Ketika layanan Gateway terkelola lokal terpasang dan mulai ulang diaktifkan, pembaruan pengelola paket dan checkout git menghentikan layanan yang berjalan sebelum mengganti pohon paket atau memodifikasi keluaran checkout/build. Pembaru kemudian menyegarkan metadata layanan, memulai ulang layanan, dan memverifikasi Gateway yang dimulai ulang sebelum melaporkan Gateway: restarted and verified.. Pembaruan pengelola paket juga memverifikasi bahwa Gateway yang dimulai ulang melaporkan versi paket yang diharapkan; pembaruan checkout git memverifikasi kesehatan gateway dan kesiapan layanan setelah build ulang.

Pembaruan pengelola paket biasanya tetap menggunakan biner Node yang tercatat dalam layanan terkelola. Jika Node tersebut tidak dapat menjalankan rilis target, tetapi Node CLI saat ini dapat melakukannya dan layanan terbukti milik paket yang sedang diperbarui, pembaruan dengan mulai ulang diaktifkan menggunakan Node saat ini untuk finalisasi dan menulis ulang metadata layanan ke runtime tersebut. --no-restart tidak dapat memperbaiki metadata layanan, sehingga ketidakcocokan runtime yang sama menghentikan proses sebelum modifikasi paket.

Di macOS, pemeriksaan pascapembaruan juga memverifikasi bahwa LaunchAgent dimuat/berjalan untuk profil aktif dan port loopback yang dikonfigurasi dalam keadaan sehat. Jika plist terpasang tetapi launchd tidak mengawasinya, OpenClaw melakukan bootstrap ulang LaunchAgent secara otomatis dan menjalankan ulang pemeriksaan kesehatan/versi/ kesiapan channel (bootstrap baru memuat job RunAtLoad secara langsung, sehingga pemulihan tidak langsung kickstart -k Gateway yang baru dimunculkan). Jika Gateway masih tidak menjadi sehat, perintah keluar dengan nilai bukan nol dan mencetak jalur log mulai ulang beserta petunjuk mulai ulang, instal ulang, dan rollback paket.

Jika mulai ulang tidak dapat dijalankan, perintah mencetak Gateway: restart skipped (...) atau Gateway: restart failed: ... dengan petunjuk manual openclaw gateway restart. Dengan --no-restart, penggantian paket atau build ulang git tetap berjalan, tetapi layanan terkelola tidak dihentikan atau dimulai ulang, sehingga Gateway yang berjalan tetap menggunakan kode lama hingga Anda memulai ulang secara manual.

Bentuk respons bidang kontrol

Ketika update.run berjalan melalui bidang kontrol Gateway pada instalasi pengelola paket atau checkout git yang diawasi, handler melaporkan inisiasi handoff secara terpisah dari pembaruan CLI yang berlanjut setelah Gateway berhenti:

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started", dan handoff.status: "started": Gateway membuat handoff layanan terkelola dan menjadwalkan mulai ulangnya sendiri agar helper terlepas dapat menjalankan openclaw update --yes --json di luar proses layanan aktif.
• ok: false, result.reason: "managed-service-handoff-unavailable", dan handoff.status: "unavailable": OpenClaw tidak dapat menemukan batas layanan pengawas dan identitas layanan persisten untuk handoff yang aman (misalnya, handoff systemd memerlukan identitas unit OPENCLAW_SYSTEMD_UNIT, bukan hanya penanda proses systemd sekitar). Respons menyertakan handoff.command, perintah shell yang harus dijalankan dari luar Gateway.
• ok: false, result.reason: "managed-service-handoff-failed": Gateway mencoba membuat handoff tetapi tidak dapat memunculkan helper terlepas.

Payload sentinel ditulis sebelum Gateway berhenti, dan handoff CLI memperbarui sentinel mulai ulang yang sama setelah pemeriksaan kesehatan mulai ulang layanan terkelola selesai. Selama handoff, sentinel dapat membawa stats.reason: "restart-health-pending" tanpa kelanjutan sukses; Gateway yang dimulai ulang melakukan polling terhadapnya dan memicu kelanjutan hanya setelah CLI memverifikasi kesehatan layanan dan menulis ulang sentinel dengan hasil akhir ok. openclaw status dan openclaw status --all menampilkan baris Update restart saat sentinel tersebut tertunda atau gagal, dan update.status menyegarkan serta mengembalikan sentinel terbaru.

Alur checkout Git

Pemilihan channel

• stable: checkout tag non-beta terbaru, lalu build dan jalankan doctor.
• beta: prioritaskan tag -beta terbaru, dengan fallback ke tag stable terbaru ketika beta tidak tersedia atau lebih lama.
• dev: checkout main, lalu fetch dan rebase.
• extended-stable: tidak didukung untuk checkout Git; tidak ada modifikasi checkout yang dilakukan.

Langkah pembaruan

Detail sinkronisasi plugin

Pada channel beta, instalasi plugin npm dan ClawHub terlacak yang mengikuti jalur default/latest mencoba rilis @beta plugin terlebih dahulu. Jika plugin tidak memiliki rilis beta, OpenClaw menggunakan fallback ke spesifikasi default/latest yang tercatat dan melaporkan peringatan. Untuk plugin npm, OpenClaw juga menggunakan fallback ketika paket beta tersedia tetapi gagal dalam validasi instalasi. Peringatan fallback ini tidak menggagalkan pembaruan inti. Versi persis dan tag eksplisit tidak pernah ditulis ulang.

Setelah pembaruan inti extended-stable berhasil, integritas dan konvergensi plugin pasca-inti menargetkan plugin npm resmi yang memenuhi syarat pada versi inti terpasang yang persis sama. Untuk intent default/latest, OpenClaw tidak mengueri @extended-stable plugin atau menggunakan fallback ke latest npm; OpenClaw memperoleh versi paket dari inti yang terpasang. Pin versi eksplisit, tag eksplisit selain latest, paket pihak ketiga, dan sumber non-npm mempertahankan intent yang ada.

Untuk instalasi pengelola paket, openclaw update menentukan versi paket target sebelum memanggil pengelola paket. Instalasi global npm menggunakan instalasi bertahap: OpenClaw menginstal paket baru ke prefix npm sementara, memungkinkan paket kandidat memvalidasi versi Node host selama preinstall, dan memverifikasi inventaris dist yang dikemas di sana. Penjaga penyelesaian terkemas tetap berada di luar inventaris tersebut hingga preinstall berhasil, sehingga pengelola paket yang melewati skrip siklus hidup juga berhenti sebelum aktivasi. Pada npm 12 dan yang lebih baru, pembaru hanya menyetujui siklus hidup OpenClaw kandidat; skrip dependensi transitif tetap diblokir. OpenClaw kemudian menukar pohon paket yang bersih ke prefix global sebenarnya. Jika verifikasi gagal, doctor pascapembaruan, sinkronisasi plugin, dan pekerjaan mulai ulang tidak dijalankan dari pohon yang mencurigakan. Bahkan ketika versi terpasang sudah cocok dengan target, perintah menyegarkan instalasi paket global, lalu menjalankan sinkronisasi plugin, penyegaran penyelesaian perintah inti, dan pekerjaan mulai ulang. Hal ini menjaga sidecar terkemas dan catatan plugin milik channel tetap selaras dengan build OpenClaw yang terpasang, sekaligus menyerahkan build ulang penyelesaian perintah plugin secara penuh kepada eksekusi openclaw completion --write-state eksplisit.

Terkait

• openclaw doctor (menawarkan untuk menjalankan pembaruan terlebih dahulu pada checkout git)
• Channel pengembangan
• Memperbarui
• Referensi CLI