openclaw-control-mcp

openclaw-control-mcp

OpenClaw のコントロールプレーン MCP サーバーです。 Claude Code、Cursor、または任意の MCP クライアントから、ゲートウェイの管理機能をすべて操作できます。cron の一覧表示と実行、セッションの確認、エージェントとチャネルの設定、スキルとシークレットの管理、doctor のメモリプレーンの操作、デバイスのペアリング、exec／プラグイン呼び出しの承認に対応しています。ゲートウェイが公開するすべての JSON-RPC メソッドを網羅する、型付きツールを 143 個備えています。

/v1/chat/completions のみをラップする上流版の openclaw-mcp とは異なります。こちらは OpenClaw Control パネルで使われる JSON-RPC プロトコルで通信するため、ゲートウェイを通じてチャットするだけでなく、ゲートウェイ自体（cron、セッション、エージェント、チャネル、スキル、シークレットなど）を操作できます。

なしの場合と導入後

openclaw-control-mcp がない場合 — Control パネルの UI、ターミナル、Claude Code の間を行き来することになります。「自分の cron を一覧表示して」と言われたら、SPA を開く必要があります。「このエージェントのセッションを追跡して」と言われたら、パネルを開いたまま更新し続ける必要があります。「このスキルが失敗した理由は？」と聞かれたら、logs.tail を手作業で調べなければなりません。アシスタントはゲートウェイ経由でチャットできますが、ゲートウェイを操作することはできません。

openclaw-control-mcp の導入後 — 同じアシスタントが openclaw_cron_list を呼び出し、続けて openclaw_sessions_tail で進行中のターンを確認し、診断データを openclaw_skills_status に問い合わせ、openclaw_secrets_set でシークレットをローテーションし、応答が止まった openclaw_exec_approval を承認できます。チャットを離れる必要はありません。Control パネルは日常的に操作する場所ではなく、監査インターフェースになります。

クイックスタート

# Claude Code — registers a stdio server under the default config
claude mcp add openclaw-control -- npx -y openclaw-control-mcp

対応クライアントからワンクリックでインストールできます。

初回起動時に、ラッパーが Ed25519 のデバイス ID を生成し、pairing request id を表示します。OpenClaw Control パネルで一度承認すると、ゲートウェイからデバイストークンが発行され、それ以降の呼び出しでは自動的に使用されます。ペアリングの詳しい手順は以下をご覧ください。

ステータス

0.8.3 — npm で公開済みで、公式 MCP Registry に io.github.smurfy92/openclaw-control-mcp として登録されています。複数インスタンスのゲートウェイ設定、ファイルベースのシークレット管理（.env ＋ store.json、モード 0600、OS のキーチェーンにはアクセスしません — ADR-006 を参照）、公開されている 128 個の JSON-RPC メソッドに対応する型付きツール 143 個に加え、2 つの拡張手段があります。openclaw_introspect はゲートウェイが hello-ok で公開するすべてのメソッド／イベントを列挙し、openclaw_call を使えば、まだ型付きラッパーのない任意のメソッドにアクセスできます。そのため、リリースを待たなくても新しいゲートウェイエンドポイントを利用できます。

Ed25519 署名付きハンドシェイクは、ゲートウェイ 2026.4.12+ で実際に検証済みです。初回起動時に、ラッパーは長期利用するデバイス ID を生成し、${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/store.json（モード 0600）に保存し、connect フレームに署名して、Control パネルから一度承認できるペアリングリクエスト ID を返します。承認後、ゲートウェイはデバイストークン（hello-ok.auth.deviceToken）を発行します。このトークンはゲートウェイごとにキャッシュされ、以降の接続でスコープの付与に使用されます。

ワイヤ形式（フレームの種類、フィールド名、署名の正規化方式、スコープ）は、Control パネルの縮小済みバンドル（/api-docs/assets/index-*.js）からリバースエンジニアリングし、openclaw/openclaw/scripts/dev/gateway-smoke.ts と照合しました。公式には文書化されていません。OpenClaw がゲートウェイを更新すると、予告なく動作が変わる可能性があります。

初回起動時／ペアリングの流れ

1. ラッパーを起動します（~/.claude.json に登録すると、Claude Code が自動的に起動します）。
2. Claude に openclaw_device_status の実行を依頼します。初回の呼び出しでは、次の処理が行われます。
   • Ed25519 のキーペアを生成してディスクに保存します。
   • ゲートウェイへの WS 接続を開きます。
   • 署名付きの connect フレームを送信します。
   • ゲートウェイが PAIRING_REQUIRED と requestId を返します。
   • ツールは { pendingPairing: { requestId }, nextStep: "approve in Control panel…" } を返します。
3. OpenClaw Control パネルを開き、Devices タブで、ID が一致するリクエストを承認します。
4. Claude に openclaw_device_status をもう一度実行するよう依頼します。今度はゲートウェイが接続を受け入れ、hello-ok で auth.deviceToken を返します。ラッパーはこれをキャッシュし、レスポンスに paired: true と付与されたスコープが表示されます。
5. 以降は、スコープ付きツール（openclaw_cron_list、_status など）が通常どおり動作します。

インストール

npm から（推奨）

claude mcp add openclaw-control -- npx -y openclaw-control-mcp

Claude Code を再起動し、設定 に進みます。

ソースから（コントリビューター向け）

git clone https://github.com/smurfy92/openclaw-control-mcp.git
cd openclaw-control-mcp
npm install
npm run build
claude mcp add openclaw-control -- node "$(pwd)/dist/index.js"

リリース（npm と公式 MCP Registry への公開。どちらも v*.*.* タグで .github/workflows/publish.yml から実行）の手順は、CONTRIBUTING.md に記載されています。

設定

ラッパーには、OpenClaw ゲートウェイの WebSocket URL が必要です。Hostinger の公開 HTTPS ホスト名からは WS エンドポイントにアクセスできません。Control パネルが内部で使用する URL が必要です。

ブラウザーで次の手順を実行して確認します。

1. Control パネルを開き、ログインします。
2. DevTools コンソールで次を実行します。

   Object.entries(localStorage).find(([k]) => k.startsWith("openclaw.control.settings.v1"))?.[1]
   

3. gatewayUrl フィールドをコピーします（通常は ws://127.0.0.1:18789、Tailscale の ws://100.x.y.z:18789、または専用の wss://… ホストです）。

Claude Code での使用

推奨：登録後、チャットで設定

最も簡単な方法です。~/.claude.json の編集も環境変数の設定も不要です。インストール後（npx またはソースから）、チャットで次のように入力します。

「ゲートウェイ wss://your-gateway.example.com とトークン <your-token> で OpenClaw を設定してください」

Claude が openclaw_setup({ gatewayUrl, gatewayToken }) を呼び出し、値は ~/.config/openclaw-control-mcp/store.json（モード 0600）に保存されます。次に openclaw_device_status を呼び出すと、WS ハンドシェイクとペアリングの流れが開始されます。

openclaw_setup_show は有効な設定を表示し、openclaw_setup_clear は保存済みの設定を消去します（デバイス ID／トークンには影響しません）。

代替方法：環境変数を使用する

環境変数を使う場合（保存済みの設定より優先されます）は、~/.claude.json を編集します。

"openclaw-control": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "openclaw-control-mcp"],
  "env": {
    "OPENCLAW_GATEWAY_URL": "wss://your-gateway.example.com",
    "OPENCLAW_GATEWAY_TOKEN": "<your-token>",
    "OPENCLAW_TIMEOUT_MS": "30000"
  }
}

Claude Code を再起動すると、openclaw_cron_list などを使用できるようになります。

シークレットと .env ファイル

サーバーが OS のキーチェーンにアクセスすることはありません。security や secret-tool の呼び出しも、権限の確認も、承認が必要な操作もありません。0.8.0 以降、シークレットは次の 3 か所から、この順序で読み込まれます。

#	ソース	備考
1	実際の環境変数	常に最優先されます。OPENCLAW_GATEWAY_TOKEN=… npx -y openclaw-control-mcp のように、一度だけ設定して上書きすることもできます。
2	.env ファイル	起動時に環境変数として読み込まれます。すでに設定されている変数は上書きしません。
3	store.json（モード 0600）	openclaw_setup とペアリングのフローで書き込まれる設定です。設定ディレクトリ内のプレーンな JSON ファイルです。

.env ファイルの候補は、優先度の高い順に次のとおりです。

1. $OPENCLAW_ENV_FILE — 明示的に指定したパス
2. ./.env — サーバーの起動元ディレクトリ
3. ${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/.env

.env.example をコピーして内容を記入し、chmod 600 .env を実行します。ほかのユーザーからファイルを読み取れる場合、サーバーは標準エラー出力に警告を表示します。パーサーは意図的に最小限の仕様となっており、KEY=value、export KEY=value、"quoted"、'''raw'''、# コメントに対応します。変数の展開には対応していないため、シークレットが展開されたり、別の解釈をされたりすることはありません。

シークレットをサーバーにディスクへ一切書き込ませたくない場合は、.env に OPENCLAW_DEVICE_PRIVATE_KEY と OPENCLAW_DEVICE_TOKEN を設定します（ペアリング済みのインストール環境から npx tsx scripts/export-ci-secrets.ts で取得できます）。環境変数で ID を指定すると、ストア全体が使われなくなります。

--health を実行すると、読み込まれた .env ファイルと、それらが設定した変数が表示されます。

0.5.0～0.7.0 からのアップグレード（キーチェーンの削除）

これらのバージョンでは、シークレットは OS のキーチェーンに保存され、store.json の該当フィールドは空のままになっていました。次のセッションを開始する前に、次の一度きりのインポートを実行してください。

npx -y openclaw-control-mcp --migrate-from-keychain

キーチェーンを読み取り、値を store.json（モード 0600）に書き込みます。その後、不要になった項目に対する security delete-generic-password …／secret-tool clear … コマンドを出力します。キーチェーンから項目が削除されることはありません。2 回実行しても何も起こりません。このパッケージでキーチェーンを読み取るコードはこれだけです。このフラグが指定された場合にのみ動的にインポートされ、通常の起動時には実行されません。

移行しない場合は、openclaw_device_repair で残存しているデバイス情報を消去できます。次回の接続時に、最初からペアリングし直します。

環境変数

変数	必須	説明
OPENCLAW_GATEWAY_URL	はい	ゲートウェイの WebSocket URL（ws:// または wss://）
OPENCLAW_GATEWAY_TOKEN	推奨	ゲートウェイのログイン用トークン
OPENCLAW_GATEWAY_PASSWORD	任意	追加のパスワード（一部のゲートウェイ設定で必要です）
OPENCLAW_TIMEOUT_MS	任意	接続／リクエストのタイムアウト（デフォルトは 30000）
OPENCLAW_DEBUG	任意	1 に設定すると、すべての WS フレームを stderr に記録します
OPENCLAW_CONTROL_HOME	任意	store.json の永続化に使用するディレクトリを上書きします（デフォルトは ${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/）。従来の OPENCLAW_CLAW_HOME も引き続きフォールバックとして読み込まれます。
OPENCLAW_ENV_FILE	任意	.env ファイルの明示的なパスです。ほかの処理が環境変数を読み込む前に読み込まれ、./.env および <configDir>/.env より優先されます。シークレットと .env ファイルを参照してください。
OPENCLAW_HTTP	任意	1 に設定すると、stdio の代わりに /mcp で Streamable HTTP 経由の MCP を公開します。--http を渡す場合と同じです。
OPENCLAW_HTTP_PORT	任意	HTTP ポート（デフォルトは 3333）。--http-port=N を渡す場合と同じです。
OPENCLAW_HTTP_HOST	任意	HTTP ホスト（デフォルトは 127.0.0.1）。--http-host=H を渡す場合と同じです。
OPENCLAW_MOCK	任意	1 に設定する（または --mock を渡す）と、WebSocket ゲートウェイをインメモリの MockGateway に切り替えます。実際のゲートウェイを用意せずに MCP を試せるため、CI、デモ、ドライランに利用できます。状態はプロセス内に保持され、終了時に破棄されます。

マルチインスタンス：呼び出しごとの instance パラメーター

すべてのツールは任意の instance フィールドを受け付けるため、アクティブなデフォルトを先に切り替えなくても、1 つの MCP から複数のゲートウェイを対象にできます。

// route this one call to the 'work' gateway, regardless of the active default
{ "name": "openclaw_cron_list", "arguments": { "instance": "work", "limit": 10 } }

各ゲートウェイは openclaw_setup({ instance: "work", gatewayUrl, gatewayToken }) で設定し、openclaw_setup_list で一覧表示できます。openclaw_setup_select_default でアクティブなデフォルトを切り替えます。環境変数に OPENCLAW_GATEWAY_URL が設定されている場合は、instance 引数を含むすべての設定より優先されます。常に環境変数による指定が優先されます。

HTTP モード

stdio に対応していないクライアント（Cursor、Continue、Cline、Zed、ブラウザー）では、MCP を Streamable HTTP サーバーとして実行します。

# Loopback (default 127.0.0.1:3333), no bearer — fine for local trust
npx -y openclaw-control-mcp --http --http-port=3333

# Same, but with bearer auth on (recommended even on loopback)
OPENCLAW_HTTP=1 OPENCLAW_HTTP_BEARER="$(openssl rand -hex 32)" \
  npx -y openclaw-control-mcp

# Bound to a public interface — bearer is REQUIRED (server refuses to start without)
OPENCLAW_HTTP=1 OPENCLAW_HTTP_HOST=0.0.0.0 OPENCLAW_HTTP_PORT=3333 \
  OPENCLAW_HTTP_BEARER="$(openssl rand -hex 32)" \
  npx -y openclaw-control-mcp

エンドポイント：POST/GET http://<host>:<port>/mcp（MCP Streamable HTTP、ステートフル — クライアントごとに独自のセッション ID が割り当てられます）。デフォルトは引き続き stdio です。HTTP サーバーは明示的に有効にした場合のみ起動します。

認証の動作：

• OPENCLAW_HTTP_BEARER が設定されている場合 → すべての /mcp リクエストに Authorization: Bearer <token> を含める必要があります。一致しないトークンまたはトークンがない場合は、WWW-Authenticate: Bearer realm="openclaw-control-mcp" ヘッダーを付けて 401 Unauthorized が返されます。比較は定時間で行われます。
• OPENCLAW_HTTP_BEARER が未設定で、ループバックにバインドされている場合 → stderr に警告を出して起動します。ローカルシェルにアクセスできる人は、すべてのツールを実行できます。
• OPENCLAW_HTTP_BEARER が未設定で、ループバック以外のホスト（0.0.0.0、パブリック IP など）にバインドされている場合 → サーバーは起動を拒否します。認証なしでパブリックにバインドすることは乗っ取りのリスクがあるため、例外は認められません。

リバースプロキシの背後で長期間稼働させる場合は、プロキシ（nginx、Caddy、Traefik）で TLS を終端し、127.0.0.1:3333/mcp に転送してください。ベアラートークンは、プロキシから MCP への通信も保護します。

モックモード（ゲートウェイ不要）

OPENCLAW_MOCK=1 に設定する（または --mock を渡す）と、WebSocket クライアントをインメモリのモックに切り替えます。次の用途に便利です。

• CI — 稼働中のゲートウェイなしでテストやデモを実行します。
• ワークフローのリハーサル — 本番環境を対象にする前に、cron.add／cron.update／config.patch 呼び出しの一連の処理をドライランします。
• オンボーディング — ゲートウェイインスタンスを用意せずに MCP を試します。

# stdio
OPENCLAW_MOCK=1 npx -y openclaw-control-mcp
# or HTTP
OPENCLAW_MOCK=1 OPENCLAW_HTTP=1 npx -y openclaw-control-mcp

状態（追加した cron ジョブ、設定パッチ、セッション）はプロセス内に保持され、終了時に破棄されます。モックには cron ジョブ（sample-weekly）が 1 つ、セッションが 1 つシードされているため、一覧表示の呼び出しで空でない結果が返されます。あらかじめハンドラーが用意されていないメソッドは { mock: true, ok: true } を返すため、エラーで停止することはありません。ほかのメソッドに固有の処理を追加するには、src/gateway/mock.ts を拡張してください。

Cron テンプレート（スケジュール構文を覚える必要はありません）

cron.add をベースにした4つのラッパーが、最も一般的なケース向けにワイヤ形式を生成します。

// every Friday at 09:00 Paris, send a weekly digest to a Telegram channel
{ "name": "openclaw_cron_add_weekly", "arguments": {
    "name": "weekly-digest", "dayOfWeek": "fri", "hour": 9, "minute": 0,
    "tz": "Europe/Paris", "message": "Compose the weekly digest …",
    "channel": "telegram", "to": "-1001234567890"
}}

// every day at 07:00 UTC
{ "name": "openclaw_cron_add_daily", "arguments": {
    "name": "morning-check", "hour": 7, "tz": "UTC", "message": "Run the morning checks."
}}

// every 15 minutes (clock-agnostic)
{ "name": "openclaw_cron_add_every", "arguments": {
    "name": "ping", "intervalMinutes": 15, "message": "ping the upstream"
}}

// one-shot reminder, auto-deletes after firing
{ "name": "openclaw_cron_add_once", "arguments": {
    "name": "remind-meeting", "at": "2026-12-25T09:00:00+01:00",
    "message": "Don't forget the holiday call."
}}

4つすべてで、標準のパラメーター（agentId?、model?、timeoutSeconds?（デフォルトは900）、channel? + to?、deliveryMode?（announce | direct | none）、instance?）を指定できます。

ツール

ゲートウェイが公開する128個の JSON-RPC メソッドをラップした、型付きツール143個と、単独のイントロスペクションツール2個があります。ペアリング後に openclaw_introspect を一度実行すると、お使いのゲートウェイで利用できるメソッドとイベントの一覧を確認できます。

イントロスペクション（スコープ不要）

ツール	備考
openclaw_introspect	ゲートウェイが hello-ok で公開するサーバーバージョン、ユーザーのロールとスコープ、methods[] / events[] の完全な一覧を返します。
openclaw_call	エスケープハッチ — 任意のパラメーターを指定して、任意の JSON-RPC メソッドを呼び出します。リリース間にゲートウェイへ新しいメソッドが追加された場合に便利です。型付きラッパーがある場合は、そちらを優先してください。

セットアップ（スコープ不要）

ツール	備考
openclaw_setup	{ gatewayUrl, gatewayToken, gatewayPassword? } をローカル設定に保存します。
openclaw_setup_show	トークンを表示せずに、有効な設定（環境変数とストアのどちらか）を報告します。
openclaw_setup_clear	保存済みのゲートウェイ設定を消去します。デバイスの ID とトークンは保持されます。

デバイスとペアリング（device.pair.*、device.token.*）

openclaw_device_status / openclaw_device_pair_list / _pair_approve / _pair_reject / _pair_remove / openclaw_device_token_revoke / _token_rotate。ローカルの Ed25519 ID と、発行されたゲートウェイごとのトークンを管理します。

ドメイン別のカバレッジ（operator.read / operator.write / operator.admin が必要）

ドメイン	ツール	ラップ対象の JSON-RPC メソッド
cron	7	list status run runs add update remove
sessions	17	list preview create patch send abort reset delete compact compaction.{list,get,restore,branch} subscribe/unsubscribe messages.subscribe/unsubscribe
agents	7	list create update delete files.{list,get,set}
chat	3	send history abort
channels	2	status logout
logs	1	tail
models	1	list
usage	2	status cost
ルートステータス	12	status health last-heartbeat set-heartbeats system-presence system-event wake send agent agent.identity.get agent.wait gateway.identity.get
config	6	get set patch apply schema schema.lookup
secrets	2	reload resolve
skills	6	status search detail install update bins
tools	2	tools.catalog tools.effective
exec.approval	9	list get request resolve waitDecision + グローバル / ノードごとのポリシー get/set
plugin.approval	4	list request resolve waitDecision
wizard	4	start next cancel status
doctor.memory	7	status dreamDiary backfillDreamDiary dedupeDreamDiary repairDreamingArtifacts resetDreamDiary resetGroundedShortTerm
node	16	list describe invoke + invoke.result event rename pair.{request,verify,approve,reject,list} pending.{ack,drain,enqueue,pull} canvas.capability.refresh
tts	6	status enable disable providers setProvider convert
talk	3	config mode speak
voicewake	2	get set
その他	3	update.run commands.list message.action

ツール名は openclaw_<domain>_<method> という形式です。メソッド名のドットはアンダースコアに変換されます。例：cron.list → openclaw_cron_list、sessions.compaction.restore → openclaw_sessions_compaction_restore。

破壊的なツール

これらのツールには、データ損失、サービス中断、アクセス権の取り消しなど、破壊的な副作用があります。description にその旨が記されているため、Claude Code の確認ゲートで各呼び出しの前に確認が求められます。

• Cron: cron_remove、cron_run（実際の実行）、cron_update
• Sessions: sessions_{abort,reset,delete,compaction_restore}
• Agents: agents_{delete,files_set}
• Chat: chat_abort
• Channels: channels_logout
• Device: device_{pair_remove,token_revoke,token_rotate}
• Config: config_{set,patch,apply}
• Secrets: secrets_resolve（シークレットの内容を返します）
• Doctor memory: doctor_memory_{resetDreamDiary,resetGroundedShortTerm,repairDreamingArtifacts,backfillDreamDiary,dedupeDreamDiary}
• Node: node_{invoke,rename,pending_drain,pending_enqueue,pending_ack,pair_approve,pair_reject}
• Skills: skills_{install,update}
• Approvals: exec_approval_resolve、exec_approvals_{set,node_set}、plugin_approval_resolve
• Self-update: update_run（ゲートウェイ全体に適用され、セッションが中断される場合があります）

例

MCP のペアリング後、Claude にそのまま貼り付けて使えるプロンプトです。それぞれ対応するツールを対象とし、自然言語の指示が具体的な呼び出しに変換される例を示します。

ヘルスチェックと状態確認

> Run a full openclaw health check.

→ openclaw_health を呼び出し、MCP のバージョン、ゲートウェイサーバーのバージョン、ペアリング済みデバイスのフィンガープリント、付与されたスコープ、最後に成功した呼び出しからの経過時間を報告します。

> What gateway methods do I have access to right now?

→ openclaw_introspect を呼び出し、ゲートウェイが hello-ok で公開する 128 個の JSON-RPC メソッドと 24 個のイベントを返します。

Cron

> List all openclaw cron jobs, including disabled ones.

→ openclaw_cron_list({ enabled: "all" })。

> Show me the last 5 runs of cron job <id> — compact mode, just the summaries.

→ openclaw_cron_runs({ id: "<job-id>", limit: 5, compact: true }) — 要約は 200 文字で切り詰められ、各エントリに runAtAgo: "3d ago" フィールドが追加されます。

> Create a cron that runs every Friday at 1pm Paris and posts a summary to Telegram group -1001234567890.

→ 適切な schedule.kind: "cron"、expr: "0 13 * * 5"、tz: "Europe/Paris"、delivery.mode: "announce" を含む openclaw_cron_add のペイロードを生成します。

セッション

> List the 10 most recent active openclaw sessions, ranked by last activity.

→ openclaw_sessions_list({ limit: 10, sortBy: "updatedAt", sortDir: "desc" })。

> Show me the last 8 messages of session agent:main:cron:<id>.

→ openclaw_sessions_preview({ keys: ["agent:main:cron:<id>"] }) — ゲートウェイからロールとテキストのやり取りを直接返します。

エージェントとチャンネル

> List the agents configured on this gateway and which model they use.

→ openclaw_agents_list。

> What's the connection state of my Telegram channel?

→ openclaw_channels_status。

緊急用の手段

> Use openclaw_call to invoke "config.schema" with no params and return the keys it exposes.

→ ゲートウェイ側のメソッドにまだ型付きラッパーがない場合や、ベータ版の機能を調べたい場合に便利です。

耐障害性

request() は一時的なエラー（ネットワーク切断、WebSocket の切断、タイムアウト、DNS）に対し、指数バックオフを使って再試行します。デフォルトは 1 秒 → 2 秒 → 4 秒で、最大 4 回試行します。再試行できないエラー（PAIRING_REQUIRED、INVALID、MISSING_SCOPE など）は即座に失敗します。権限の問題を再試行しても意味がないためです。次の設定で調整できます。

• OPENCLAW_RETRY_ATTEMPTS — 試行回数の合計（デフォルトは 4、範囲は 1～10）
• OPENCLAW_RETRY_BASE_MS — 初回のバックオフ時間（ミリ秒単位。デフォルトは 1000、範囲は 100～60000）
• OPENCLAW_DEBUG=1 — 再試行の判断をすべて stderr に出力します

リクエストが再試行を断念すると、スローされるエラーには gateway request '<method>' failed (attempt N/M): が接頭辞として付き、調査できるよう元のエラーが cause として保持されます。GatewayError の code、details、retryable フラグは、ラップ後も引き継がれます。

クライアントは、openclaw_health の lastSuccessAgo フィールド用に lastSuccessAtMs を記録します。「ゲートウェイはまだ応答しているか？」のデバッグに便利です。

診断 CLI

MCP をクライアントに接続せずに、一度だけヘルスチェックを行うには次のコマンドを実行します。

npx -y openclaw-control-mcp --health

JSON レポート（MCP のバージョン、ゲートウェイ URL、ペアリング状態、スコープ、サーバーのバージョン、最後に成功してからの経過時間、エラーがあればその内容）を出力し、失敗時はゼロ以外の終了コードで終了します。CI やスクリプトで便利です。

スキーマの柔軟性

ほとんどの v0.3.0 ラッパーは params に z.passthrough() を使用しています。ドキュメントに記載されたフィールドに加えて、それ以外のフィールドも受け入れ、ゲートウェイにそのまま渡します。これは、クライアント側での厳密な検証と引き換えに、将来の互換性を確保するものです。ゲートウェイが進化して新しいフィールドが追加されても、呼び出しが壊れることはありません。一方で、誤ったフィールドについては、ゲートウェイがリクエストを拒否するまで気付けません。「missing required property」エラーが発生した場合は、ゲートウェイの応答を確認してください。正確なワイヤー形式が示されています。それをもとに呼び出しを修正するか、ラッパーの Zod スキーマを厳密にするための issue または PR を作成してください。

脅威モデル

この MCP サーバーは、オペレーターが自然言語で操作する LLM に対して、秘密情報を扱う操作や副作用のあるゲートウェイ操作（config.*、secrets.*、cron.run、sessions.send、agent、チャンネルへの送信）を公開します。この機能範囲は、意図的に慎重に扱ってください。

• ゲートウェイトークン、デバイスの秘密鍵、ゲートウェイごとのデバイストークンは、${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/store.json に保存されます（ファイルモードは 0600）。0.8.0 以降、サーバーはOS のキーチェーンに一切アクセスしません。security や secret-tool の呼び出しも、アクセス許可の確認もありません。サーバーによって秘密情報をディスクに書き込まれないようにしたい場合は、代わりに .env ファイルから指定してください（Secrets & the .env file を参照）。store や .env をコミットしないでください。また、--health の出力を、伏せ字にせず投稿しないでください。
• openclaw_secrets_set は config.patch を通じてゲートウェイの設定ツリーに書き込みます。このラッパーに到達するツール呼び出しは、いずれもゲートウェイ側で確認される基盤の秘密情報をローテーションします。エージェントのプロンプトでは、明示的な人間による確認を必須にしてください。
• openclaw_call はエスケープハッチです。任意の JSON-RPC メソッド呼び出しを転送します。ゲートウェイはスコープごとの権限を適用しますが、クライアント側には入力フィルターがありません。信頼できないプロンプトがエージェントに届く可能性がある場合は、エージェントに表示するツールカタログを制限してください。
• OPENCLAW_DEVICE_PRIVATE_KEY／OPENCLAW_DEVICE_TOKEN 環境変数（ヘッドレス／CI／サービスアカウントでの使用向け）は、store より優先されます。これらは信頼できる実行環境（GitHub secrets、K8s secrets、パスワードマネージャーからのエクスポート、chmod 600 を適用した .env など）でのみ設定してください。シェルの履歴、Docker の --env、リポジトリにコミットした .env には絶対に設定しないでください。
• プロンプトインジェクションの攻撃対象：ゲートウェイの応答（セッションのプレビュー、ログ、エージェントの出力）は MCP クライアントに返されるため、攻撃者が制御するコンテンツを含む可能性があります。破壊的なツールを呼び出すかどうかを判断する際は、すべてのツール出力を信頼できないものとして扱ってください（破壊的な操作の一覧は §破壊的なツールに掲載されています。読み取りツールの出力を受けて書き込みツールを連続して呼び出す前に、確認してください）。
• HTTP トランスポートの攻撃対象：--http の実行時に OPENCLAW_HTTP_BEARER が設定されている場合、サーバーは一定時間で処理される Bearer チェックを実施します。設定されていない場合、ループバック以外のインターフェースへのバインドを拒否し、ループバックで設定なしに起動すると stderr に目立つ警告を出力します。Bearer はゲートウェイ管理者トークンと同様にローテーションしてください。これを読み取れる者は、secrets.* の書き込みを含むすべてのツールを呼び出せます。HTTP ポートをネットワークに公開する前に、リバースプロキシで TLS を終端してください。

脆弱性を発見した場合は、公開 issue ではなく、GitHub で非公開のセキュリティアドバイザリーを作成してください：https://github.com/smurfy92/openclaw-control-mcp/security/advisories/new。

ロードマップ

• 指数バックオフによる自動再接続 — 0.3.1 でリリース済み（client.request() はジッターを加えて再試行します。0.4.0 以降は OPENCLAW_RETRY_ATTEMPTS ／ OPENCLAW_RETRY_BASE_MS で調整できます）。
• セッションメッセージを MCP クライアントにストリーミングして返す（現在、sessions.subscribe はサーバー側で登録されますが、stdio では差分を Claude Code に渡せません）。
• 0.3.0 で追加されたラッパーの Zod スキーマを厳格化する — 各ドメインのゲートウェイの形状が完全に確定するまでは、ほとんどで passthrough() を使用しています。PR を歓迎します。
• stdio に加えて Streamable HTTP トランスポートに対応 — 0.5.0 でリリース済み（--http、http://127.0.0.1:3333/mcp）。ベアラートークン認証は 0.7.0 で追加されました（OPENCLAW_HTTP_BEARER）。ADR-005 を参照してください。
• Claude Desktop Extension（.mcpb）のパッケージ化。

openclaw-claw-mcp からの移行（早期導入者向け）

以前の名前（openclaw-claw-mcp）でラッパーを使用していた場合：

• 新しいパスが空の場合、Store はフォールバックとして ~/.config/openclaw-claw-mcp/store.json を自動的に読み込むため、ペアリング済みデバイスのトークンは引き続き機能します。
• 次回の接続が成功すると、新しいパス（~/.config/openclaw-control-mcp/store.json）が作成されます。その後、古いディレクトリを削除できます。
• ~/.claude.json のエントリー名を openclaw-claw から openclaw-control に更新してください（見た目だけの変更で、ツールのプレフィックス mcp__openclaw-control__* のみが変わります）。
• ローカルの作業ディレクトリ／ビルド出力は、クローンした先と同じパスを維持します。ほかに移動が必要なものはありません。

トラブルシューティング

• gateway request '…' failed: expected Uint8Array of length 32, got length=0 — 永続化された device.privateKey が空です。0.8.0 以降でよくある原因は、キーがまだ OS のキーチェーンに保存されている 0.5.0～0.7.0 からのアップグレードです。その場合は npx -y openclaw-control-mcp --migrate-from-keychain を一度実行してください。それ以外の場合は、openclaw_device_repair で復旧してください。背景情報：docs/troubleshooting/empty-private-key.md。
• gateway request '…' failed: device nonce mismatch — しばらくアイドル状態が続いた後に発生する場合、WS 接続が古くなり、再試行ループが使用済みの nonce を再利用しています。回避策：同じパラメーターで openclaw_setup を再度呼び出してください（新しいハンドシェイクが強制されます）。詳細と修正案：docs/troubleshooting/stale-connection-nonce-mismatch.md。

注意事項

• このプロトコルはリバースエンジニアリングされたもので、ドキュメント化されていません。ゲートウェイの更新に伴い、動作が変わる可能性があります。
• 接続フレームは、現在 openclaw/openclaw/scripts/dev/gateway-smoke.ts が送信するものと一致します（client.id: "openclaw-ios"、mode: "ui"、iOS オペレーターのデフォルトに基づくロールとスコープ）。client.id の値が異なると、サーバーのポリシーも異なります。たとえば openclaw-control-ui と openclaw-tui では、デバイスの ID に加えてセキュアコンテキストのオリジンも必要です。
• OPENCLAW_DEBUG=1 を指定すると、すべての WS フレームが stderr に記録されます（8 KB で切り詰められます）。ライブの Control パネル SPA とハンドシェイクを比較するときに便利です。