2026年版 OpenClaw 移行とコールドスタート運用：ディレクトリコピーから初回ゲートウェイ疎通まで（systemd と launchd）
~/.openclaw とワークスペースのツリーを新しいマシンへコピーしただけでは、本番相当のデプロイにはなりません。症状は「バイナリが見つからない」「HOME がずれた文脈でデーモンが起動する」「ペア済みに見えるのにチャネルが返事しない」などに集まりがちです。本稿では インストール手段、環境、サービス、チャネル の順に切り分け、社内運用票に貼れる systemd と launchd の対照表、コピペで回せる 7 段階のコールドスタート手順を示します。次のレイヤーとして、VPSMAC の記事「インストールパス」と「ステータスから doctor までの段階的トリアージ」も参照してください。
この記事の内容
1. つまずき：コピーしたツリーだけではそのまま動かない
ノート PC や旧 VPS から移行するチームは、「ディレクトリの中身が同じなら挙動も同じ」と仮定しがちです。OpenClaw は実際には四つの層が密接に結び付いています。PATH 上でどの openclaw バイナリが勝つか、~/.openclaw 以下の設定ツリー、ワークスペース相対の資産、そして systemd や launchd が与えるスーパーバイザの文脈です。どれか一つでも欠けると、SSH セッション内ではゲートウェイが動くのに切断や再起動後には消える、といった断続的な症状になります。
移行ウィンドウでは、まず「人間が SSH で叩いたとき」と「常駐サービスが起動したとき」の差分を一枚のチェックリストに書き出すと迷子になりにくいです。特に Mac クラウドではログインシェルの rc が LaunchAgent に引き継がれないため、開発者個人の nvm や任意の PATH 追記に依存した運用ほど、本番相当のノードでは静かに壊れます。
- マシン間での CLI のズレ：旧ホストはグローバル npm、新しい Mac クラウドイメージは Homebrew だけ、あるいは固定のインストールスクリプト配下、といった差は日常茶飯事です。JSON をコピーしてもバイナリは入りません。pnpm ワークスペースとグローバルパッケージが混ざると、バージョン文字列は一致していても動的ローダの探索パスが異なる、という罠もあります。
- デーモン文脈の破損：Linux では
systemd --userユニットがEnvironment=HOME=...を明示していることが多いです。macOS の LaunchAgent はログインシェルの rc を継承しないため、nvm 形式のプレフィックスは plist に絶対パスを書くか薄いラッパースクリプトを挟まないと消えます。WorkingDirectoryがずれると、ログや資格情報の参照先が静かに別の場所を向きます。 - 切り分け順序の誤り：
openclaw.jsonの構文とポート 18789 を確認する前にチャネルのペアリングへ飛ぶと、時間を浪費しがちです。外向きのメッセージング面に触る前に、ローカルプローブを緑に揃えましょう。 - rsync 後の所有者：root でコピーして後からアプリ用ユーザーへ渡したツリーは読めるのに書けず、標準エラーへのログが詰まって「謎のハング」に見えることがあります。移行直後に
ls -laで書き込み可否を確認しておくと後戻りが減ります。
2. systemd と launchd の環境対照表
次の表は変更チケットの付録として貼れるようにまとめています。「ファーストストップ」列は、チャットプロバイダやファイアウォールを疑う前にホスト側で確認すべき観点です。
長期稼働の Mac クラウドインスタンスが移行先なら、まず launchd で絶対パスとログファイルを固定し、そのうえで Docker による分離を取るかどうかを判断するのが現実的です。ボリュームや uid の複雑さは、その価値が明確なときだけ払うのがよいでしょう。Linux で既に他のユーザーレベル常駐を systemd --user で動かしているなら、OpenClaw も同じリソース境界に揃え、隣接する重い xcodebuild がゲートウェイ応答を飢えさせないようにします。
| 観点 | Linux（systemd ユーザーユニット） | macOS（LaunchAgent） | 移行直後のファーストストップ |
|---|---|---|---|
| 環境変数 | Environment= 行やドロップイン | シェル継承なし。plist かラッパーが必要 | HOME、PATH、API キー注入を確認 |
| 作業ディレクトリ | WorkingDirectory= | WorkingDirectory キー | 相対パスの秘密情報が指すワークスペース根に合わせる |
| ログ | journalctl --user -u ... | StandardOutPath / StandardErrorPath | ファイル所有者が書き込み可能か検証 |
| 起動の永続化 | enable --user | RunAtLoad と正しいブートストラップドメイン | SSH の子プロセスなしで再起動テスト |
| 権限 | uid と gid、任意で cgroup | サンドボックスやフルディスクアクセスはツールチェーン次第 | キーチェーンとプライバシー許可は別テストとして切り出す |
3. 初回疎通までのコールドスタート 7 ステップ
ここでの手順は、人間が読めるシグナルを先に出し、外部アカウントが要る作業は後ろへ回す意図です。夜間カットオーバーでは、各ステップの想定分数をメンテナンス票に書いておくと、インシデントリードが「続行かロールバックか」をその場で揉めずに選べます。
- バージョンとインストール手段を固定：旧ホストで
openclaw --version、npm か pnpm かインストールスクリプトかイメージダイジェストかを記録します。ツリーをコピーする前に、インストールパス記事を踏まえて新ホスト側の単一エントリポイントを決め、二重のバイナリを踏まないようにします。 - ディレクトリを同期：
rsync -aHなどで~/.openclawとワークスペースを揃え、巨大キャッシュの除外ルールを守ります。直後に重要ファイルの更新時刻とサイズを比較し、部分転送を早期に検知します。 - 権限とシークレット到達性：
ls -la ~/.openclawを実行します。Docker フローなら、インストールガイドの Docker 節を参照してバインドマウントと uid マッピングを再検証します。 - サービスユニットを書く：Linux は明示的な環境行を持つ
systemd --userユニット。macOS はProgramArgumentsにopenclawへの絶対パスを書いた LaunchAgent です。リリース間でデフォルトが動く場合は、待受アドレスとポートを明示します。 - 読み込みとコールドスタート：
systemctl --user daemon-reload && restart、あるいはlaunchctl bootstrapのあとkickstart。親プロセスが systemd か launchd になっているか、SSH セッションにぶら下がっていないかを確認します。 - ローカルプローブ：
lsof -i :18789、最小限の JSON 妥当性確認、そのうえでラダー記事に沿ったopenclaw doctor。プローブが赤の間はチャネルトークンのローテーションを避けます。 - チャネルのスモークテスト：ゲートウェイのログが健全に見えてからペアリングを直します。監査向けにコマンドのトランスクリプトを変更記録へ残します。
クイックコマンドブロック：which openclaw；openclaw --version；test -r ~/.openclaw/openclaw.json && echo ok；チーム方針に沿ったバインドアドレスへの curl 系プローブ。企業プロキシ背後のホストでは、個人の SSH アカウントではなく サービスユーザー でエグレス検査を実行し、人間は curl できるのにデーモンはできない、という偽陰性を避けます。
4. 参照メモ：パス、ポート 18789、監査で残す項目
この節はウィキの付録向けで、上の番号付き手順が物語の本線です。ふたつを併せると、事後検証でも順序と深さの両方を満たせます。
- JSON の単一の正：どのマシンが正規の
openclaw.jsonを持ち、バックアップをどう取るかを文書化します。移行後はサービス起動前に旧ファイルと新ファイルを diff し、半端なマージを避けます。 - ポート競合：一台の Mac クラウドで複数のラボ用ゲートウェイを動かすなら、ポートかラベルを分けます。競合は接続のフラッキーに見えがちです。
- 監査の最低限：インストール手段、セマンティックバージョン、ユニットか plist のラベル、コンテナならイメスト、初回の緑の doctor 要約、チャネルのアカウント識別子、ペアリング時刻、規制領域ならオペレータ ID。
- ロールバック：旧ホストに最後に健全だったユニットファイルとパッケージまたはイメージタグを残します。四半期ごとの訓練で、そのスナップショット以降に回したキーでも RTO 内に戻せるかを確認します。
- 上流リスク：インストールとスーパーバイザの層が通ったあと、ClawHub Skill のサプライチェーンは 2026 年 4 月の監査チェックリスト記事のとおり扱います。
- タイムゾーン：地域をまたいでファイルログを相関させる前に、NTP と表示タイムゾーンを揃え、因果の推論ミスを減らします。
5. よくある質問
Q: ワークスペースだけコピーして ~/.openclaw は移していません。ゲートウェイは起動できますか？
鍵やローカル状態が欠けます。どちらのツリーも移すか、旧ホストからの読み取り専用エクスポートのチェックリストに沿って秘密情報を意図的に再構築してください。
Q: launchctl では loaded に見えるのに 18789 で何も聞いていません。StandardErrorPath、WorkingDirectory、plist 内の PATH を確認します。エラーファイルが空なら、ログが書き込めないパスへ向いている可能性があります。
Q: Linux の systemd ユニットを macOS でそのまま再利用できますか？
いいえ。LaunchAgent に書き直し、環境変数とログのパスを一行ずつ再検証してください。
Q: チャネルは沈黙しているのに 18789 はローカルで応答します。
まずゲートウェイのログを読み、そのうえで上流のネットワークと許可リストを確認します。直近の編集でバインドアドレスが食い違っていないかを切り分ける前に、設定全体を初期化しない方が安全です。
Q: 比較用に旧インスタンスを並べておきたいです。
ポートとラベルを分け、ラボ用ユニットから本番 JSON への書き込みを禁止し、二重ライタによる破損を防ぎます。
6. パイロットから本番へ：ネイティブ Mac クラウドでの収束
運用票の複雑さは、SSH で入る開発者の環境と本番がどれだけ一致するかに比例します。ネストした仮想化は PATH、ボリューム、権限の驚きを増幅します。インストールガイドに沿った launchd を備えた専用 Mac クラウドは、監査可能なコールドスタートへの最短距離になりがちです。ネイティブ経路が退屈なほど安定するまで Docker のサンドボックスは足さず、最初の移行ウィンドウで混ぜないのが現実的です。
OpenClaw の長寿命ゲートウェイは CI ランナーと同列のインフラとして扱い、ディスクを確保し、ログをローテーションし、ノードにタグを付け、ログイン監査を配線します。全員が同じ plist とディレクトリ契約に従えば、将来の移行は毎回の即興ではなく、既知のプレイブックの反復になります。