2026 Linux systemd 上の OpenClaw：アップグレード後にホーム環境の食い違いで設定が空に見えるときの doctor 統合手順
systemd --user で openclaw gateway を動かすと、アップグレード後にactive なのに設定が空に見えることがあります。SSH と異なる HOME／XDG_CONFIG_HOME を読みスケルトン化しているケースが多く、本稿では三段階の切り分けとマージ手順を整理します。
目次
1. 症状の三段階：プロセス／RPC／設定の空殻
プロセス層：systemctl --user status が active でも、実際に開いている設定ルートが運用者のホームと一致しているとは限りません。WorkingDirectory や HOME が未設定のままだと、パッケージ付近にスケルトンができ、見かけ上チャネルやプラグインが消えたように見えます。
RPC 層：openclaw gateway status でビルド ID と CLI のセマンティックバージョンが食い違う場合は、先に《split brain と meta.lastTouchedVersion》の手順を踏み、いきなりディレクトリを削除しないでください。
設定の空殻層：ディレクトリは存在するのに plugins や channels が空に見えるときは、別の XDG_CONFIG_HOME に書き込まれている可能性があります。アップグレードで探索順が変わると、旧バージョンのパスにだけ有効な JSON が残り、新パス側はスケルトンのままというパターンが典型です。
journalctl --userでENOENTやHOME、設定パスに関する行を拾う。- ログインシェル、非ログイン、
systemctl --user showの三つの環境を並べて比較する。 - マージ前に必ず tar でスナップショットを取得する。
2. status から gateway status、ログ、doctor までの順序
《公式の gateway プローブ手順》と同じく、まず待受と RPC を証明してから openclaw doctor に進みます。429 やプラグイン shape の疑いで HOME の取り違えを見逃さないようにしてください。
doctor の前後で openclaw gateway status を実行し、資格情報はチャネル安定後に最後へ移します。
3. 再起動のみ・マージ・install --force の判断表
短時間で判断するための表です。複数台ではカナリア一台で様子を見てください。
| 兆候 | 最初に行うこと | リスク |
|---|---|---|
HOME 未設定でスケルトン化 |
drop-in で HOME／WorkingDirectory を明示 |
低 |
| 旧パスに JSON、新パスは空 | ブロックマージと meta 更新 | 中 |
| CLI と GW の semver 分離 | 窓内で gateway install --force |
高 |
4. 七ステップのマージと検証
ユニット名は実際の Id= に合わせて読み替えてください。
# ユーザー単位の実環境を確認
systemctl --user show openclaw-gateway.service -p Environment -p WorkingDirectory
# 対話シェルと比較
echo "$HOME" "$XDG_CONFIG_HOME"
# スナップショット（パスは環境に合わせて調整）
tar czf ~/openclaw-premerge-$(date +%Y%m%d%H%M).tgz ~/.openclaw ~/.config/openclaw 2>/dev/null- 同一 JSON への同時編集と並列インストールを止める。
- root、ログインシェル、ユーザー単位の三つの環境変数ダンプを保存する。
gateway statusが示す設定ルートを正とする。channels、credentials、pluginsを順にマージする。doctorの後に status とチャネル疎通を再確認する。- ヘッドレスでは
loginctlの linger を確認する。 - 変更票にセマンティックバージョン、drop-in のハッシュ、rollback 用 tar のパスを記録する。
5. 運用でそのまま印刷できるチェック表
当番向けの短い行です。
| 確認項目 | コマンド／手掛かり | 期待値 |
|---|---|---|
ユーザー単位の HOME | systemctl --user show | 設定を所有するアカウントのホームと一致 |
| linger | loginctl show-user | SSH 切断後もユーザーマネージャが継続 |
| ジャーナル | journalctl --user -u | 設定読み込みの ENOENT が連続しない |
6. 関連記事との分担
split brain は semver と meta.lastTouchedVersion。Docker 記事は《Compose トークン》。macOS は《launchd 再起動》を参照し、Linux では User= と linger を優先します。
7. よくある質問
問：スケルトンを消してから旧ファイルをコピーしてよいですか。答：サービス停止とスナップショットが前提です。稼働中のコピーは JSON 破損の原因になります。
問：root と一般ユーザーで二重にゲートウェイを起動したらどうなりますか。答：ポートと設定ルートが衝突します。User= を明示し、余分なユニットを無効化してください。
8. まとめとリモート Mac への収束
正しい設定を読むには、HOME と XDG 系の変数を systemd の真実として揃え、公式の段階手順で RPC を検証することが先です。
自己ホストの Linux では drop-in の管理とマージ規律が常に必要で、アップストリームのリリース頻度が高いほど運用負荷も上がります。
ゲートウェイを安定したパスと Apple シリコン環境で長時間動かしたい場合は、SFTPMAC のリモート Mac レンタル とヘルプセンターの手順を参照し、毎週のマージ作業から注意力を解放する選択肢も比較してください。