ノード前置チェック
テンプレ変更前に全ノードを同格ピアとみなし、次を揃えます。
- OS／Xcode／CLI／OpenClawのマイナーまで parity。
- ホスト名・DNS／hosts・NTP（数秒以内）— ロックと TTL が時刻ずれに弱い。
- 空きディスク・inodeの下限（スキル展開・キャッシュ用）。
- シークレット・レジストリ・共有キューへの到達（キュー同期と整合）。
テンプレートとシークレット注入
Git にはテンプレ（例 openclaw.env.tpl）のみ。変数は機上の「隠し export」に頼らず列挙し、実値は Vault／secrets.d／CI からデプロイ時に注入します。
テンプレート変数チェックリスト
- ☐
NODE_ROLE（ingress／worker／signing／gateway）とログ相関用MESH_NODE_ID - ☐キュー／API は単一の正、テンプレ外への直書き禁止
- ☐スキルレジストリ URL と読み取り専用トークン（可能なら pull のみ）
- ☐フィーチャーフラグは
0/1や列挙で明示。「未設定＝オン」にしない - ☐ローテ向けシークレット名・所有者・周期をテンプレ付近に記載
カナリアで正常版との diff。欠落変数は起動失敗で検知し半起動を防ぐ。最小権限マウントも参照。
スキルパッケージのバージョン固定と検証
バージョン固定＝名前・版または digest・手順をコミットしたマニフェスト。全ノードが同一内容を同一順序で適用します。
スキルパッケージ版ファイルチェックリスト
- ☐リポジトリに
skills.lock.json（または同等）を 1 つ。ワークスペースがロックから外れたら CI で失敗 - ☐出所を記録：レジストリ URL＋digest または semver。本番メッシュでは
@latest禁止 - ☐インストール後フックで解決版を標準出力に出し、機械可読な
skills.resolved.jsonを書き出す
検証：doctor または dry-run で全スキルロード。skills.resolved.json をノード間比較し、差はブロッカー。
| 症状 | 想定原因 | 対処 |
|---|---|---|
| 特定ノードだけタスクスキーマエラー | スキルのマイナー差・部分インストール | ロックから再インストール、キャッシュ／wheel を掃除 |
| A では認証成功、B では 401 | テンプレ未レンダリング・ロール別 env の誤結合 | レンダリング済み env を diff、ロールごとのシークレット束を修正 |
| 断続的に「スキルが見つからない」 | ローリング再起動中のレース | キューを静穏化し、ingress 健全化後に worker を順次再起動 |
グレースケールとロールバック
変更はカナリア→バッチ→全台。直前のテンプレ版とロックをタグ保持し、ロールバックは参照を戻すだけにします。
ローリングリリースと検証チェックリスト
- キュー凍結／ドレインでカット中に長タスクを起こさない。
- カナリアに新 env＋ロック済みスキルを配布→再起動→スモーク（読取・投入・実行・通知）。
- 同一
trace_id等でカナリアと基準ノードのログを突合。 - 25%→50%→100% 拡大し、エラー率・p95 を見る。
- 失敗時は前テンプレ＋前ロックへ。ingress 共有なら worker から戻す等の順序を決める。
負荷分散・故障転送と併せ、ヘルスにスキル準備度も含める。
ログの揃えとトラブルシュート
フィールドを統一：timestamp、level、node_id、role、task_id、skill_version、template_revision。集約基盤がなければファイル規則と保存日数だけでも全台同一に。
- 相関：展開中は全ノードへ同一
deployment_id。 - 秘匿：ログでトークンをマスク、レンダリング env を CI に出さない。
- 切り分け：
skills.resolved.json・ビルド文字列・先頭スタックをノード横断比較してからコード変更。