2026_OPENCLAW
MCP_SKILLS_
GATEWAY_
TOKEN_RUNBOOK.

MCP やカスタム Skill 追加後にツール説明がコンテキストを圧迫したり、Gateway 再起動後も古い挙動のままになることがあります。ワークスペース優先度、Gateway の状態、MCP schema のトークン予算、launchd 環境の PATH/OAuth を表で整理し、リモート Mac 常駐の注意点をまとめます。関連:onboard と GatewayDocker 本番エラー対処

開発ツールチェーン

1. つまずきの本質:MCP と Skills は「ファイルが増えた」だけではない

(1)読み込み順が見えない:ワークスペース /skills、ユーザー領域、同梱 Skills の優先度が分からないと、編集したはずの SKILL が会話に反映されません。(2)Gateway のメモリスナップショット:実装によってはスキル版情報が RAM に残り、不完全な再起動ではディスク更新が見えません。(3)MCP schema の容積:複数サーバを同時接続すると、ツール定義だけで 16k〜32k 窓の大半を占有し、拒否や幻覚が増えます。(4)デーモン環境の PATH:launchd 下では nvm/fnm のシムが消え、対話シェルでは動くコマンドが Gateway から見えません。リモート Mac の 24/7 運用では、端末を常に開いていないためこの差分に気づきにくくなります。

2. Skills ディレクトリ優先度(対照表)

配布チャネルごとにパス表記が変わることがあります。下表は一般的な上書きの直感です。実際の絶対パスは、使用中バージョンの公式ドキュメントと Gateway ログで必ず突き合わせてください。

層(高→低)用途確認ポイント
ワークスペース /skills またはプロジェクト内チーム手順・リポジトリ固有Gateway の cwd が想定 workspace と一致するか
ユーザー skills ディレクトリ個人検証・ショートカットYAML frontmatter のインデント崩れでファイル全体が無視される例がある
同梱デフォルト製品標準スキルアップグレード後は changelog を先に読む

3. MCP 接続:最小クローズドループとトークン規律

まず MCP サーバを1 つだけ接続し、認証・ヘルスチェック・最小ツール呼び出しまで通します。その後にサーバを追加し、ログまたはプロンプト差分でツール定義のシリアライズ長を追跡します。system+tools が窓上限に近づいたら、チャネル別プロファイルでツール面を絞る、サブエージェントに遅延ロードする、コンテキストの大きいモデルへ切り替える、のいずれか(多くは組み合わせ)が必要です。サーバ数だけ増やして「モデルが弱い」と決めつけるのは典型的な誤診です。

4. 実践 5 ステップ検証

ステップ1:Gateway ログから workspace ルートと Skills 走査範囲を記録する。ステップ2:1 つの SKILL に目印となる文字列を入れ、Gateway を完全再起動して会話に反映されるか煙測する。ステップ3:MCP をすべて止め、1 本だけ有効化して tools トークン量を基準化し、順に足し戻す。ステップ4launchctl print 等でデーモンの環境変数と PATH を対話シェルと比較する。ステップ5:ステージングで OAuth を意図的に期限切れにし、失敗がログに出るか/静かに消えるかを確認する。

# ヘルス確認例(ポートは環境に合わせて変更) curl -sS http://127.0.0.1:18789/health 2>/dev/null || echo "adjust-endpoint"

5. Gateway 再起動後も「古いまま」:症状マトリクス

症状有力な原因対応
SKILL 変更が見えない別ディレクトリが優先検索パスをログ出力し、固有文字列で grep
ツール数が不安定MCP 接続失敗が握りつぶされているデバッグログを上げ、サーバ単体で切り分け
断続的にツール欠落トークン期限・リフレッシュ失敗再認可し、リフレッシュ処理がデーモン環境で動くか確認
ユーザ文が短いのに文脈が満杯複数大 schema の積み上げMCP を減らす/セッション分割/モデル変更

運用目安(ベンダー値ではなく現場向け):

  • 16k 級モデルで、フィルタなし MCP 説明が合計 10k トークン超は珍しくない。
  • 常駐ホストでは plist に node/python の絶対パスを書き、login shell に依存しない。
  • IM・Webhook など新チャネル公開のたびに、公開ツール集合を再監査する。

6. 考察:ツール統制がエージェント運用の中心になる理由

2026 年、MCP は外部連携を「一度きりのスクリプト」から「再利用可能なプラットフォーム能力」へ押し上げました。その代償として、コンテキスト消費と権限面が同時に膨らみます。従来のマイクロサービスと異なり、LLM は毎ターンツールを再スケジュールするため、schema とポリシーがずれるとトークン浪費と越権の両方が起きます。Apple Silicon の Mac は Gateway を静かに常駐させやすい一方、統合メモリはマルチチャネル・長セッションで圧力が上がります。これは単なる「タブを増やした」とは負荷形状が違い、ツール定義が system 側に長く滞留するからです。

変更多い開発をノートに残し、本番の Gateway+MCP を専用マシンへ分離すると、変更頻度と爆発半径を切り離せます。ノートは試行錯誤に最適ですが、スリープ、個人アプリ、不安定な上り帯域と運用 SLA を共有しがちです。

上り帯域の安定、デーモン衛生、24/7 監視がボトルネックになったら、MACGPU のリモート Mac に OpenClaw を載せ替えると同じ macOS/Metal スタックを保ったまま PATH と稼働時間を予測しやすくなります。従量課金は本番固定前のカナリアに向きます。ノート単体構成は学習とローカルデバッグには合理的ですが、グラフィックスや常時 AI ワークフローでは専用リモートの方が SLA を取りやすい——これは販売話術ではなく、配置の技術判断です。