OpenClaw HTTP APIでツールを直接呼び出す方法

開発を進める中で、「特定のツールを1回だけ、さっと実行したい」という場面は多いですよね。複雑なオーケストレーションを組むまでもなく、使い慣れたHTTPリクエストで直接ツールを叩ければ、デバッグや自動化の効率はぐっと上がります。

OpenClawのGatewayは、単一のツールを直接呼び出すためのシンプルなHTTPエンドポイントを公開しています。この機能は常に有効になっており、Gatewayの認証（auth）とツールポリシーが適用されます。OpenAI互換の /v1/* エンドポイントと同様に、共有シークレットによるBearer認証は、Gateway全体に対する信頼されたオペレーターアクセスとして扱われます。

• POST /tools/invoke
• Gatewayと同じポートを使用（WS + HTTPマルチプレックス）: http://<gateway-host>:<port>/tools/invoke

デフォルトの最大ペイロードサイズは2 MBです。

認証 (Authentication)

Gatewayの認証設定を使用します。以下の形式でBearerトークンを送信してください。

• Authorization: Bearer <token>

注意点：

• gateway.auth.mode="token" の場合は、gateway.auth.token（または OPENCLAW_GATEWAY_TOKEN）を使用します。
• gateway.auth.mode="password" の場合は、gateway.auth.password（または OPENCLAW_GATEWAY_PASSWORD）を使用します。
• gateway.auth.rateLimit が設定されており、認証エラーが多発した場合は、エンドポイントは Retry-After を含む 429 を返します。

セキュリティ境界（重要） (Security boundary (important))

このエンドポイントは、Gatewayインスタンスに対するフルオペレーターアクセス権限を持つものとして扱ってください。

• ここでのHTTP Bearer認証は、ユーザーごとの狭いスコープを管理するモデルではありません。
• このエンドポイントに対する有効なGatewayトークンやパスワードは、オーナーまたはオペレーターの資格情報として扱う必要があります。
• 共有シークレット認証モード（token および password）では、呼び出し側がより狭い x-openclaw-scopes ヘッダーを送信したとしても、通常のフルオペレーター権限が復元されます。
• また、共有シークレット認証では、このエンドポイントでの直接的なツール呼び出しをオーナー送信者によるターンとして扱います。
• 信頼されたIDベースのHTTPモード（例：信頼されたプロキシ認証や、プライベートなIngressでの gateway.auth.mode="none"）では、リクエストで宣言されたオペレータースコープが尊重されます。
• このエンドポイントは、ループバック、TailscaleなどのTailnet、またはプライベートなIngressのみに配置し、パブリックなインターネットに直接公開しないでください。

認証マトリックス：

• gateway.auth.mode="token" または "password" + Authorization: Bearer ...
  • 共有されたGatewayオペレーターシークレットの所持を証明します。
  • 制限された x-openclaw-scopes は無視されます。
  • デフォルトのフルオペレータースコープセットを復元します。
  • このエンドポイントでの直接的なツール呼び出しをオーナー送信者によるターンとして扱います。
• 信頼されたIDベースのHTTPモード（例：信頼されたプロキシ認証、またはプライベートIngressでの gateway.auth.mode="none"）
  • 外部の信頼されたIDまたはデプロイメント境界を認証します。
  • 宣言された x-openclaw-scopes ヘッダーを尊重します。
  • 宣言されたスコープに operator.admin が実際に含まれている場合にのみ、オーナーとしてのセマンティクスが付与されます。

リクエストボディ (Request body)

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}

フィールド：

• tool (string, 必須): 呼び出すツールの名前。
• action (string, 任意): ツールのスキーマが action をサポートしており、かつ args ペイロードで省略されている場合に、args にマッピングされます。
• args (object, 任意): ツール固有の引数。
• sessionKey (string, 任意): ターゲットとなるセッションキー。省略されるか "main" が指定された場合、Gatewayは設定されたメインセッションキーを使用します（session.mainKey やデフォルトのエージェント、またはグローバルスコープの global を尊重します）。
• dryRun (boolean, 任意): 将来のために予約されています。現在は無視されます。

ポリシーとルーティングの動作 (Policy + routing behavior)

ツールの可用性は、Gatewayエージェントが使用するものと同じポリシーチェーンを通じてフィルタリングされます。

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• グループポリシー（セッションキーがグループやチャネルにマップされている場合）
• サブエージェントポリシー（サブエージェントのセッションキーで呼び出す場合）

ポリシーでツールが許可されていない場合、エンドポイントは 404 を返します。

境界に関する重要な注意点：

• 実行承認（Exec approvals）はオペレーター向けのガードレールであり、このHTTPエンドポイントのための独立した認可境界ではありません。Gateway認証とツールポリシーによってツールにアクセス可能な場合、/tools/invoke は呼び出しごとに追加の承認プロンプトを出すことはありません。
• GatewayのBearer資格情報を信頼できない呼び出し元と共有しないでください。信頼境界を分ける必要がある場合は、別のGatewayを実行してください（理想的には別のOSユーザーやホストで実行するのがベストです）。

Gateway HTTPは、セッションポリシーでツールが許可されている場合でも、デフォルトで以下のハードな拒否リスト（deny list）を適用します。

• exec — 直接的なコマンド実行（RCEのリスク）
• spawn — 任意の任意の子プロセス作成（RCEのリスク）
• shell — シェルコマンドの実行（RCEのリスク）
• fs_write — ホスト上の任意のファイル書き換え
• fs_delete — ホスト上の任意のファイル削除
• fs_move — ホスト上の任意のファイル移動・名前変更
• apply_patch — パッチ適用による任意のファイル書き換え
• sessions_spawn — セッションオーケストレーション。リモートでのエージェント起動はRCEに繋がります
• sessions_send — セッションをまたいだメッセージ注入
• cron — 永続的な自動化コントロールプレーン
• gateway — Gatewayコントロールプレーン。HTTP経由の再設定を防止します
• nodes — ノードコマンドリレーにより、ペアリングされたホストの system.run に到達可能です
• whatsapp_login — ターミナルでのQRスキャンを必要とする対話型セットアップ。HTTPではハングします

この拒否リストは gateway.tools を通じてカスタマイズ可能です。

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list
      allow: ["gateway"],
    },
  },
}

グループポリシーがコンテキストを解決しやすくするために、オプションで以下のヘッダーを設定できます。

• x-openclaw-message-channel: <channel> (例: slack, telegram)
• x-openclaw-account-id: <accountId> (複数のアカウントが存在する場合)

レスポンス (Responses)

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (無効なリクエストまたはツールの入力エラー)
• 401 → 認証エラー
• 429 → 認証のレート制限（Retry-After が設定されます）
• 404 → ツールが利用不可（見つからない、または許可リストに含まれていない）
• 405 → メソッド不許可
• 500 → { ok: false, error: { type, message } } (予期しないツールの実行エラー。メッセージはサニタイズされます)

例 (Example)

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'

AI Setup Assistant

次のステップ

• Gateway Authentication
• Tool Policies
• Session Management