想定読者：Gateway は動くが MCP ツールが出てこない、呼び出しがタイムアウトする、Skills が再起動後に消える、といった場面です。ゴール：初期構築はインストール記事とDocker 本番運用ランブックに、永続化はボリュームと Skills 権限の記事に任せます。本ランブックは宣言 → プロセス可視性 → Gateway 登録 → モデル／ツール／チャネルのトリアージを扱います。構成：六つの落とし穴、二つの表、設定スケッチ、注意喚起、六ステップ、三つの KPI、締めのガイダンスです。
MCP は Gateway と子プロセスまたはリモートエンドポイントとの間のJSON-RPC セッションです。設定に行があっても子が起動するとは限らず、起動してもスキーマが返るとは限りません。よくある六つの誤読は次のとおりです。
~/.zshrc の PATH や API キーを読みません。AGENTS.md と bootstrap 文面の重複：MCP と Skills の両方に同じ指示があるとコンテキストが膨らみます。境界はSkills 調整チェックリストに沿って分けます。openclaw doctor はインストール後 doctor の記事の順序で実行し、本稿はツール登録の証跡チェーンを足すものであり、別のインストール手順書ではありません。
MCP サーバーごとに一枚の「最小再現カード」を用意します。読み取りクエリ一つ、必ず拒否されるべき負のテスト一つ、ログで探すトークン三つを書き、オンコールが巨大なプロンプトを読み直さず設定退行を比較できるようにします。カードに許可された外向き通信とデータ分類を記載し、記録なしにトークン範囲を広げないようにします。
フィールド名は OpenClaw の版により異なります。本表は作業の順序を固定します。
| 症状 | 最初に集めるもの | 想定根本原因 | 監査可能な対応 |
|---|---|---|---|
| ツール一覧が空／一部だけ | Gateway ログ、子の終了コード | バイナリ欠落、cwd、permission denied | 絶対パスの command／args／cwd。子を Gateway と同一ユーザーで実行 |
| 初回だけ遅く、その後は問題ない | コールドスタート時間、パッケージ取得ログ | npx -y やランタイム JIT | プリウォーム、イメージでの版固定、初回呼び出しタイムアウトの緩和 |
| 定常タイムアウト | 子の生存、CPU、ファイルディスクリプタ | デッドロック、ブロッキング IO | 許可範囲内でサンプリング／トレース、読み取り専用ツールで A／B |
| 「ツールが登録されていない」 | スキーマログ、プロトコル版 | 実装の不一致 | MCP 版の整合、マイナー固定、上流の変更履歴の確認 |
能力マトリクスを公開し、一つのワークフローを三通りに説明しないようにします。
| ソース | 向いている用途 | バージョン管理 | リスク |
|---|---|---|---|
| ClawHub／マーケット | 迅速な試作 | コミットまたは semver 範囲を固定し週次で差分確認 | 上流の漂移。回帰テストが必要 |
リポジトリの SKILL.md／非公開パック | コンプライアンス重視のフロー | PR で本線に同梱 | 保守負荷。MCP のスコープと揃える |
| MCP（正規の接続点） | DB、チケット、社内 HTTP API | 独立したリリース周期 | 権限の過大なトークン。許可リストを維持 |
# 構造スケッチのみ。実キー、ネスト、ホットリロードは現行 OpenClaw ドキュメントに従います。
# 目的：Gateway が固定ユーザーで stdio 上の MCP サーバーを起動する。
#
# mcpServers:
# internal-readonly-lookup:
# command: /usr/local/bin/node
# args: ["/opt/mcp-servers/lookup/dist/index.js"]
# env:
# LOOKUP_API_TOKEN: "${LOOKUP_TOKEN_READONLY}"
#
# ClawHub Skill：チームの skills ディレクトリに展開／クローンし、
# 版に応じた skill インデックスの更新または公式の reload コマンドを実行します。
注意：MCP はアシスタントを本番データに接続します。最小権限と監査証跡が「とにかく動かす」より優先です。読み取り用と書き込み用サーバーを分け、トークンを分け、許可リストの抜粋を変更チケットに添付してください。
PATH、cwd、bind マウントを文書化します。memory_search やドキュメントツールへ移し、コンテキスト増大を抑えます。AGENTS.md の三か所に同じ操作が書かれている数。二を超えるものは署名付きの例外扱いにします。リモート Mac やクラウドホストでは、ディスク容量とログローテーションが一時ファイルを小さなシステム領域に書き出す MCP 子に影響し、モデル設定が変わっていなくてもタイムアウトがランダムに見えることがあります。ツール設定だけでなくホスト運用もあわせて確認してください。
HTTP／SSE 形式の MCP では、リバースプロキシのアイドルタイムアウト、Upgrade の扱い、TLS 終端を含めます。Gateway ログではハンドシェイク成功でも、エッジが 499／504 を返すことがあります。OpenClaw のタイムアウトだけ上げる前にNginx／Caddy リバプロの記事と突き合わせてください。
コミュニティ向けの方向性のメモ（ベンチマークではありません）：重い MCP を三つ以上載せ、広い検索を併用すると、キューの揺らぎが分単位になることがあります。SLA には能力マトリクスと許可リストの方が無限のプラグインより効きます。
スリープ、VPN の瞬断、パスの漂移により子プロセスと skill インデックスが不安定になります。実ビジネスデータに接続するには24 時間稼働、永続パス、監査可能な権限が必要です。
マルチリージョン選択や柔軟な契約のない自前機は、共有ホストに流れがちで、コールドスタートとログ IO が競合します。Gateway をディスクと外向き通信が予測できる専用 Apple Siliconに置くことは、プロ用 Mac クラウドでよくある選択です。MACCOME は地域横断のMac mini M4／M4 Proを柔軟なレンタル条件で提供し、Gateway とビルドファームの安定した土台になります。公開の料金とヘルプセンターの SLA を注文前に確認してください。
本ランブックの三つの検査を、イメージを全フリートに広げる前にリモート Mac で試し、「手元では動くが本番ではタイムアウト」のループを避けます。Gateway をインターネット公開する場合は TLS、レート制限、IP 許可リストを同じ変更に含め、後追いのパッチにしないでください。
よくある質問
チャネルオンボーディングの記事とどう組み合わせますか？
チャネル記事は Slack／Discord／Telegram の OAuth を扱い、本稿はツール発見を扱います。メッセージは Gateway に届くがツールだけ失敗するときは、表1から証拠を集めてから「接続はあるが無言」系の切り分けに戻ってください。
ロールバックに何を含めますか？
MCP エントリを削除し、再起動順序を記録し、読み取り専用の検証クエリを実行し、ダッシュボードでツール数がベースラインに戻ったことを確認します。課金の整合はレンタル料金で確認してください。
コンテナとベアメタルでパスが違うのはどうしますか？
ランタイムごとに絶対パスのマトリクスを維持し、モデルにチャットでパスを推測させません。ヘルプセンターと Docker ボリュームの記事を突き合わせてください。