2026年 OpenClaw Skills の優先順位とマルチワークスペース衝突：独占リモート Mac（SSH）で「スキルが効かない／二重定義」の再現対照表＋FAQ
単一の専有リモート Mac に複数リポジトリや複数「ワークスペース」ディレクトリを載せると、Skills の読み込み順・マージ結果・キャッシュされたマニフェストがずれ、「スキルが一切効かない」「同名スキルが二重に見える」といった症状が出ます。本稿は SSH 当番がその場で辿れる対照表と、衝突パターン別の緩和方針を整理します。初手の環境構築は 2026年 OpenClaw 初心者ガイド：MacでのAIエージェント環境構築 5つのステップ、並列ジョブとホームの分断に近い論点は 2026年 独占リモート Mac CI：Xcode テストプランと並列テストのセルフホスト Runner 上の資源争奪——xcresult 集約、Simulator 並列度、SSH ヘッドレス flaky 再現の意思決定マトリクス＋FAQ と併読すると整理しやすいです。
1. 前提：Skills がぶつかる三つの軸
症状を分類する前に、衝突はだいたい次の軸で起きます。（1）解決順（優先度）——ユーザー／リポジトリ／ワークスペース／グローバルなど、どのマニフェストが最後に勝つか。（2）カレントディレクトリと「アクティブなワークスペース」——エージェントや gateway がどのルートを基準にスキルディレクトリを探索するか。（3）常駐プロセスの古いキャッシュ——launchd 上の gateway が再起動されず、更新後の SKILL 定義を読み直していない。SSH では「対話シェルで見えるパス」と「サービス環境の HOME／cwd」が食い違う典型に注意してください。
2. 再現対照表：症状 → 疑う原因 → 確認の一手
ログ断片の名称はリリースで変わり得るため、意味で対応づけています。
| 観測（挙動／ログのイメージ） | 疑うべき衝突 | 確認の一手（SSH 上） |
|---|---|---|
| 特定リポだけスキルが「無い」 | そのリポのワークスペース設定が別ルートを指している、または .openclaw 系の探索基準がカレントと不一致。 |
エージェント実行ユーザーで pwd とリポルート、スキルパスを並べて出力。対話 SSH と launchd の作業ディレクトリを揃える。 |
| 同名スキルが二重登録／どちらが有効か不明 | ユーザー層とリポ層の両方に同名 SKILL.md（またはレジストリエイリアス）があり、マージ順が文書化どおりに解決されていない。 |
検索パスに載っている定義を列挙し、優先ルール（後勝ち／明示オーバーライド）をバージョンのリリースノートと照合。不要な片方を退避。 |
| 更新したのに古い説明／古いツール束が残る | gateway プロセスが再起動されていない、または別ユーザー下に残った旧インストールを参照。 | 該当ユーザでプロセス一覧と起動時刻を確認し、ドキュメント通りのコールド再起動を実施。openclaw doctor 相当の健全性確認があれば実行。 |
| ClawHub／外部スキルは入ったのにローカル上書きが効かない | レジストリ優先度とローカル overrides の順序誤認、または読み取り専用マウント上に誤って配置。 |
実ファイルの所有者・パーミッション、マウントの読み取り専用属性を確認。上書き意図なら意図した層にだけ置く。 |
3. マルチワークスペース衝突の典型パターン
| パターン | 起きやすい症状 | 運用上の対策の骨子 |
|---|---|---|
| 同一ホームに複数リポをフラットに置く | デフォルト探索が「想定より広い」ツリーに当たり、別リポのスキルが紛れ込む。 | ジョブごとに 明示のワークスペースルート を渡す。可能ならリポ単位で OS ユーザーを分離。 |
| モノレポ内の複数パッケージ | サブディレクトリごとにスキルを切り替えたいが、親の .openclaw が常に勝つ。 |
パッケージ境界に合わせてスキル定義を集約するか、サブルート用の設定ファイルでスコープを限定。 |
| CI 用と対話用で同一マシンを共有 | CI が書き込んだ一時スキルが対話セッションに見えたり、逆に干渉したりする。 | HOME またはスキルキャッシュのルートをジョブ種別で分離。後処理で掃除。 |
4. SSH 上の推奨チェック順（短い runbook）
- 主体ユーザの固定： gateway／エージェントが動くユーザーと、メンテ用 SSH ログインが一致しているか。違う場合は双方でスキル探索パスを出力して比較。
- カレントと宣言ルート： 問題のリポで期待するワークスペースルートが、実際の
cwdと一致するか。 - 重複定義の列挙： 同名スキルが複数パスに存在する場合、優先ルールに従い片方をリネームまたは退避。
- 再起動： マニフェスト変更後は gateway を含めた関連プロセスを計画的に再起動し、古いメモリ上状態を排除。
- 監査ログ： 誰がどのスキル定義を入れたか追えるよう、リポジトリ側ではパスとコミット、マシン側では配置ディレクトリの変更履歴を残す。
5. FAQ
Q1: 「優先度」はバージョンごとに変わるか
変わり得ます。マージ順や探索ルートはリリースノートとドキュメントをソース・オブ・トゥルースにし、本番ノードでは OpenClaw のピン留めバージョンとスキルセットをセットで更新してください。
Q2: 二重定義を検知する最短の目視方法は
同名の SKILL.md（または組織の命名規則）をリポジトリ全体とユーザ設定ディレクトリから検索し、パス一覧を diff 用に保存します。論理名が同じで実体が二つある状態が多いです。
Q3: マルチワークスペースをやめて単一ルートに寄せるべきか
運用コストが許せば単一テナント（1 リポ＝1 ノード）が最も誤解が少ないです。コスト優先で同居させる場合は、本稿の表のとおり明示スコープと掃除をルール化してください。
Q4: SSH のエージェント転送や別シェルプロファイルが影響するか
対話シェルだけ PATH や OPENCLAW_* が変わり、サービス環境とズレることがあります。非対話セッション用の設定（launchd の EnvironmentVariables 等）を正として揃えます。
Q5: スキルが効かないとき最初に見るログは
gateway／エージェント側で「読み込んだスキル一覧」「解決に使ったワークスペースルート」「マージ警告」が出るチャネルを優先します。無ければ、起動時のカレントと設定ファイルの実パスをデバッグ出力に足す運用を検討してください。
Skills の衝突切り分けを載せるなら、macOS 単一テナントの土台が効く
スキル優先度の問題は、最終的にファイル実体の所在とプロセスがどの環境変数で起動したかに帰着します。Apple Silicon と macOS の組み合わせは、Unix ツールチェーンと開発者向けアプリの両方を同一マシンで安定稼働させやすく、Gatekeeper・SIP・FileVault によるベースラインも揃えやすいです。常時稼働の gateway を載せるなら、待機時おおよそ 4W前後に収まりやすい Mac mini M4 クラスは、独占リモートノードとして電気代と騒音のバランスが取りやすい選択肢です。
マルチワークスペースを安全に運ぶには、結局予測可能なディスクレイアウトと再起動手順が要ります。本稿の対照表と runbook を、静音で 24 時間回せるハードの上に載せたい場合は、2026 年時点でも Mac mini M4 はコストパフォーマンスの高い出発点の一つです。今すぐ導入し、スキル解決を再現可能な運用に揃えてください。
SSHMac のトップページで、ワークスペース数・並列度・ストレージに合う構成を選べます。