はじめに
本番環境で OpenClaw をアップグレードする際の最大のリスクはサービスの中断です。ユーザーが進行中の会話が途中で切断される可能性があり、Webhook コールバックがメッセージを失う可能性もあります。本記事では、ユーザー体験に影響を与えずにバージョン更新を完了するための、ゼロダウンタイムまたは最小ダウンタイムのアップグレード方式をいくつか紹介します。
一、アップグレード前の準備
1.1 現在のバージョンとターゲットバージョンの確認
# 現在の実行バージョンを確認
openclaw version
# 利用可能な最新バージョンを確認
openclaw update check
# 出力例
# 現在のバージョン: 1.2.0
# 最新バージョン: 1.3.0
# 更新タイプ: 機能更新 (minor)
# 変更ログ: https://openclaw.com/changelog/1.3.0
1.2 変更ログの確認
アップグレード前にターゲットバージョンの変更ログを必ず確認し、特に以下の点に注意してください。
- Breaking Changes：互換性のない設定フォーマットの変更があるか
- データベースマイグレーション：データフォーマットのマイグレーションが必要か
- 依存関係の変更：Node.js バージョンや他の依存関係の更新が必要か
- 新しい設定項目：手動で追加が必要な新しい設定があるか
# バージョン間の変更概要を確認
openclaw update changelog --from 1.2.0 --to 1.3.0
1.3 アップグレード前のバックアップ作成
# 完全バックアップ（必須ステップ）
openclaw backup create --output /backup/openclaw-pre-upgrade-$(date +%Y%m%d).tar.gz
# バックアップの整合性を検証
openclaw backup verify /backup/openclaw-pre-upgrade-$(date +%Y%m%d).tar.gz
1.4 テスト環境での検証
# テスト環境で先にアップグレードと検証を実施
OPENCLAW_ENV=staging openclaw update --to 1.3.0
OPENCLAW_ENV=staging openclaw doctor
二、PM2 ゼロダウンタイムリロード
PM2 で OpenClaw を管理している場合、PM2 の reload 機能を利用してゼロダウンタイム更新を実現できます。
2.1 基本フロー
# ステップ1：OpenClaw パッケージをアップグレード
npm install -g [email protected]
# ステップ2：PM2 reload を使用（ゼロダウンタイムリロード）
pm2 reload openclaw
# ステップ3：新バージョンを検証
openclaw version
curl -s http://localhost:18789/health | jq '.version'
2.2 PM2 reload と restart の違い
| 操作 | ダウンタイム | 原理 |
|---|---|---|
pm2 restart |
約 5-15 秒 | 旧プロセスを先に停止し、新プロセスを起動 |
pm2 reload |
ほぼ 0 | 新プロセスを先に起動し、準備完了後に旧プロセスを停止 |
2.3 グレースフルリロードの設定
PM2 reload を正しく動作させるには、グレースフルシャットダウンの設定が必要です。
// openclaw-ecosystem.config.js
module.exports = {
apps: [{
name: "openclaw",
script: "openclaw",
args: "up",
// グレースフルシャットダウン待機時間（ミリ秒）
kill_timeout: 15000,
// 新プロセスの準備完了待機時間
listen_timeout: 20000,
// 準備完了シグナルを待つ
wait_ready: true,
// リロード時の最大メモリ
max_memory_restart: "512M"
}]
};
OpenClaw は起動完了後にヘルスチェックを通過すると準備完了シグナルを送信し、PM2 がシグナルを受信してから旧プロセスを停止します。
2.4 リロードプロセスの監視
# リアルタイムでリロードプロセスを観察
pm2 logs openclaw --lines 20
# プロセスステータスの変化を確認
watch -n 1 pm2 status
三、Systemd グレースフルリスタート
3.1 ExecReload の使用
Systemd サービスファイルにリロードコマンドを設定します。
# /etc/systemd/system/openclaw.service
[Service]
ExecStart=/usr/local/bin/openclaw up
ExecReload=/bin/kill -SIGUSR2 $MAINPID
ExecStop=/bin/kill -SIGTERM $MAINPID
# グレースフルシャットダウンタイムアウト
TimeoutStopSec=30
Restart=always
RestartSec=5
# アップグレードフロー
npm install -g [email protected]
sudo systemctl daemon-reload
sudo systemctl reload openclaw
# reload がサポートされていない場合は restart を使用
sudo systemctl restart openclaw
3.2 Systemd のダウンタイム
Systemd の restart には短いダウンタイムが発生します。ゼロダウンタイムが必要な場合は、デュアルインスタンス方式や Nginx との併用を推奨します。
四、ブルーグリーンデプロイメント方式
ブルーグリーンデプロイメントは、真のゼロダウンタイムを実現する古典的な方式で、新旧の 2 つのバージョンを同時に実行し、トラフィック切り替えでアップグレードを完了します。
4.1 アーキテクチャ説明
ユーザーリクエスト → Nginx → ┬─ Blue (旧バージョン v1.2.0) ポート 18789
└─ Green (新バージョン v1.3.0) ポート 18790
4.2 デプロイ手順
# ステップ1：現在の本番環境（Blue）がポート 18789 で動作中
# 現在の状態を確認
curl -s http://localhost:18789/health
# ステップ2：新しいポートで新バージョン（Green）を起動
OPENCLAW_PORT=18790 openclaw up -d --name openclaw-green --config ~/.config/openclaw/openclaw.production.json5
# ステップ3：Green 環境の準備完了を待つ
sleep 20
curl -s http://localhost:18790/health
# ステップ4：Green 環境の機能が正常か検証
openclaw doctor --port 18790
# ステップ5：Nginx のトラフィックを Green に切り替え
Nginx 設定を変更してトラフィックを新しいポートに向けます。
upstream openclaw_backend {
# 切り替え前：Blue を指す
# server 127.0.0.1:18789;
# 切り替え後：Green を指す
server 127.0.0.1:18790;
}
server {
listen 443 ssl;
server_name openclaw.yourdomain.com;
location / {
proxy_pass http://openclaw_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
# Nginx 設定をリロード（ゼロダウンタイム）
sudo nginx -t && sudo nginx -s reload
# ステップ6：トラフィックが切り替わったことを確認
curl -s https://openclaw.yourdomain.com/health | jq '.version'
# "1.3.0" が返されるはず
# ステップ7：旧バージョン（Blue）を停止
openclaw stop --name openclaw-blue
4.3 クイックロールバック
新バージョンに問題が発生した場合、Nginx を旧ポートに切り替えるだけです。
# Nginx upstream を旧バージョンのポートに向けるよう変更
# server 127.0.0.1:18789;
sudo nginx -s reload
五、Docker ローリングアップグレード
5.1 Docker Compose の使用
# docker-compose.yml
version: '3.8'
services:
openclaw:
image: openclaw/openclaw:1.3.0
deploy:
update_config:
parallelism: 1
delay: 30s
order: start-first # 新コンテナを先に起動し、旧コンテナを後に停止
failure_action: rollback
rollback_config:
parallelism: 1
delay: 10s
healthcheck:
test: ["CMD", "curl", "-sf", "http://localhost:18789/health"]
interval: 15s
timeout: 5s
retries: 3
start_period: 30s
ports:
- "18789:18789"
volumes:
- openclaw-data:/root/.openclaw
restart: always
# 新しいイメージをプルしてローリング更新
docker compose pull
docker compose up -d
# Docker Compose は以下を実行:
# 1. 新コンテナを起動
# 2. ヘルスチェックの通過を待つ
# 3. 旧コンテナを停止
5.2 Docker Swarm ローリングアップグレード
# サービスイメージを更新
docker service update --image openclaw/openclaw:1.3.0 openclaw
# アップグレードの進捗を監視
docker service ps openclaw --format "table {{.ID}}\t{{.Image}}\t{{.CurrentState}}"
六、データマイグレーション処理
6.1 自動マイグレーション
OpenClaw はバージョンアップグレード時に必要なデータマイグレーションを自動的に検出・実行します。
# 起動時に自動マイグレーション
openclaw up
# [INFO] データフォーマットのマイグレーションが必要です: v1.2 → v1.3
# [INFO] 現在のデータをバックアップ中...
# [INFO] マイグレーション実行中: migrate_sessions_v1.3
# [INFO] マイグレーション完了、156 件のセッションレコードを処理
6.2 手動マイグレーション
自動マイグレーションが失敗した場合、手動で実行できます。
# 保留中のマイグレーションを確認
openclaw migrate status
# マイグレーションを実行
openclaw migrate run
# マイグレーションをロールバック
openclaw migrate rollback --to 1.2.0
七、アップグレードチェックリスト
毎回のアップグレード前に、以下のチェックリストに従って実行してください。
アップグレードチェックリスト：v1.2.0 → v1.3.0
================================
□ 変更ログを確認し、Breaking Changes がないことを確認
□ 完全なバックアップを作成
□ テスト環境で新バージョンを検証
□ テスト環境でチャンネル接続が正常であることを確認
□ テスト環境でメッセージの送受信が正常であることを確認
□ テスト環境でスキル実行が正常であることを確認
□ チームにアップグレード計画とタイムウィンドウを通知
□ トラフィックが最も少ない時間帯にアップグレードを実行
□ アップグレードを実行
□ 本番環境のヘルスチェックが通過していることを確認
□ すべてのチャンネルが再接続されていることを確認
□ テストメッセージを送信して機能が正常であることを確認
□ 30 分間監視して異常がないことを確認
□ アップグレード完了、アップグレードログを記録
八、ロールバック方式
8.1 クイックロールバック
# 方法1：PM2 環境でのダウングレード
npm install -g [email protected]
pm2 reload openclaw
# 方法2：バックアップからの復元
openclaw stop
openclaw backup restore /backup/openclaw-pre-upgrade-20260314.tar.gz
npm install -g [email protected]
openclaw up -d
8.2 ロールバック後の確認
# バージョンを確認
openclaw version # 1.2.0 が表示されるはず
# 診断を実行
openclaw doctor
# データの完全性を確認
openclaw stats --period 1h
ゼロダウンタイムアップグレードは一度限りの作業ではなく、標準化されたプロセスと継続的な演習が必要な運用プラクティスです。デプロイ規模に合ったアップグレード方式を選択し、毎回のアップグレード前に十分な準備を行うことで、アップグレードのリスクを最大限に低減できます。