ツール呼び出し API

• POST /tools/invoke
• Gateway と同じポート（WS + HTTP マルチプレックス）: http://<gateway-host>:<port>/tools/invoke
• デフォルトの最大リクエスト本文サイズ: 2 MB

​

認証

• 共有シークレット認証（gateway.auth.mode="token" または "password"）: Authorization: Bearer <token-or-password>
• 信頼済み ID 付き HTTP 認証（gateway.auth.mode="trusted-proxy"）: 設定済みの ID 対応プロキシ経由でルーティングし、必要な ID ヘッダーを注入させます
• プライベート ingress のオープン認証（gateway.auth.mode="none"）: 認証ヘッダーは不要です

• mode="token" は gateway.auth.token（または OPENCLAW_GATEWAY_TOKEN）を使用します。
• mode="password" は gateway.auth.password（または OPENCLAW_GATEWAY_PASSWORD）を使用します。
• mode="trusted-proxy" では、HTTP リクエストが設定済みの信頼済みプロキシソースから来る必要があります。同一ホストの loopback プロキシには、明示的な gateway.auth.trustedProxy.allowLoopback = true が必要です。
• プロキシを迂回する内部の同一ホスト呼び出し元は、ローカル直接フォールバックとして gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD を使用できます。Forwarded、X-Forwarded-*、または X-Real-IP ヘッダーの証拠がある場合、代わりにリクエストは trusted-proxy パスに留まります。
• gateway.auth.rateLimit が設定されていて認証失敗が多すぎる場合、エンドポイントは Retry-After 付きで 429 を返します。

​

セキュリティ境界（重要）

• ここでの HTTP bearer 認証は、狭いユーザー別スコープモデルではありません。
• このエンドポイント用の有効な Gateway トークン/パスワードは、所有者/オペレーターの認証情報と同様に扱うべきです。
• 共有シークレット認証モード（token と password）では、呼び出し元がより狭い x-openclaw-scopes ヘッダーを送信した場合でも、エンドポイントは通常の完全なオペレーター既定値を復元します。
• 共有シークレット認証では、このエンドポイントでの直接ツール呼び出しも owner-sender ターンとして扱います。
• 信頼済み ID 付き HTTP モード（trusted proxy 認証、またはプライベート ingress 上の gateway.auth.mode="none"）では、x-openclaw-scopes が存在する場合はそれを尊重し、存在しない場合は通常のオペレーター既定スコープセットにフォールバックします。
• このエンドポイントは loopback/tailnet/プライベート ingress のみに置いてください。公開インターネットへ直接公開しないでください。

​

リクエスト本文

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

• tool / name（文字列、必須）: 呼び出すツール名。両方が送信された場合は name が優先されます。
• action（文字列、省略可）: ツールスキーマが action プロパティをサポートし、args がまだ設定していない場合、args.action にマージされます。
• args（オブジェクト、省略可）: ツール固有の引数。
• sessionKey（文字列、省略可）: 対象セッションキー。省略された場合、または "main" の場合、Gateway は設定済みのメインセッションキーを使用します（session.mainKey と既定のエージェント、またはグローバルセッションスコープ内の global を尊重します）。
• agentId（文字列、省略可）: そのエージェントのセッションキーを解決します。すでに別のエージェントにマップされている明示的な sessionKey と競合する場合は 400 でエラーになります。
• idempotencyKey（文字列、省略可）: 呼び出し用の安定したツール呼び出し ID を導出するために使用されます。
• dryRun（ブール値、省略可）: 将来の使用のために予約されています。現在は無視されます。

​

ポリシー + ルーティング動作

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

• Exec 承認はオペレーターのガードレールであり、この HTTP エンドポイントの別個の認可境界ではありません。Gateway 認証 + ツールポリシーを通じてここでツールに到達できる場合、/tools/invoke は呼び出しごとの追加承認プロンプトを追加しません。
• ここで exec に到達できる場合、それは変更を伴うシェルサーフェスとして扱ってください。write、edit、apply_patch、または HTTP ファイルシステム書き込みツールを拒否しても、シェル実行が読み取り専用になるわけではありません。
• Gateway bearer 認証情報を信頼できない呼び出し元と共有しないでください。信頼境界をまたいだ分離が必要な場合は、別々の Gateway を実行してください（理想的には別々の OS ユーザー/ホスト上）。

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

• x-openclaw-message-channel: <channel>（例: slack、telegram）
• x-openclaw-account-id: <accountId>（複数アカウントが存在する場合）
• x-openclaw-message-to: <target>（メッセージツールポリシー用の配信対象）
• x-openclaw-thread-id: <threadId>（メッセージツールポリシー用のスレッドコンテキスト）

​

レスポンス

​

例

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": {}
  }'

​

関連

• Gateway プロトコル
• ツールと plugins