Tools Invoke (HTTP)

OpenClaw の Gateway は、単一ツールを直接呼び出すためのシンプルな HTTP エンドポイントを提供します。このエンドポイントは常に有効ですが、Gateway 認証とツールポリシーによるゲートがかかっています。

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

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

認証

Gateway の認証設定を使用します。ベアラートークンを送信してください：

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 が設定されていて認証失敗が多すぎると、エンドポイントは 429 と Retry-After を返します。

リクエストボディ

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

フィールド：

tool（string、必須）：呼び出すツール名。
action（string、オプション）：ツールスキーマが action をサポートし、args ペイロードで省略されている場合に args にマッピングされます。
args（object、オプション）：ツール固有の引数。
sessionKey（string、オプション）：対象セッションキー。省略時または "main" の場合、Gateway は設定された main セッションキーを使用します（session.mainKey とデフォルトエージェントに従うか、グローバルスコープでは global）。
dryRun（boolean、オプション）：将来の使用のために予約済み。現在は無視されます。

ポリシーとルーティングの動作

ツールの利用可否は、Gateway エージェントが使用するのと同じポリシーチェーンでフィルタリングされます：

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

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

Gateway HTTP は、セッションポリシーがツールを許可している場合でもデフォルトでハード拒否リストを適用します：

sessions_spawn
sessions_send
gateway
whatsapp_login

この拒否リストは gateway.tools でカスタマイズできます：

{
  gateway: {
    tools: {
      // HTTP /tools/invoke 経由でブロックする追加ツール
      deny: ["browser"],
      // デフォルト拒否リストからツールを削除
      allow: ["gateway"],
    },
  },
}

グループポリシーがコンテキストを解決するのを助けるため、オプションで以下を設定できます：

x-openclaw-message-channel: <channel>（例：slack、telegram）
x-openclaw-account-id: <accountId>（複数アカウントが存在する場合）

レスポンス

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

使用例

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