ツールが 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 ヘッダーを挿入させます
• プライベートイングレスのオープン認証（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 ヘッダーの証拠がある場合、リクエストは引き続き信頼済みプロキシパスで処理されます。
• gateway.auth.rateLimit が設定されており、認証失敗が多すぎる場合、エンドポイントは Retry-After を設定した 429 を返します。

​

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

• ここでの HTTP Bearer 認証は、ユーザーごとの限定的なスコープモデルではありません。
• このエンドポイントで有効な Gateway トークン／パスワードは、所有者／オペレーターの認証情報と同等に扱う必要があります。
• 共有シークレット認証モード（token および password）では、呼び出し元がより狭い x-openclaw-scopes ヘッダーを送信しても、エンドポイントは通常の完全なオペレーターデフォルトを復元します。
• 共有シークレット認証では、このエンドポイントでの直接的なツール呼び出しも、所有者が送信者であるターンとして扱われます。
• 信頼済みの ID 情報を伴う HTTP モード（信頼済みプロキシ認証、またはプライベートイングレス上の gateway.auth.mode="none"）では、x-openclaw-scopes が存在する場合はそれに従い、存在しない場合は通常のオペレーターデフォルトスコープセットにフォールバックします。
• このエンドポイントは loopback／tailnet／プライベートイングレス上にのみ配置し、公開インターネットへ直接公開しないでください。

​

リクエスト本文

{
  "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: {
      // HTTP /tools/invoke 経由でブロックする追加ツール
      deny: ["browser"],
      // 所有者／管理者の呼び出し元について、デフォルト拒否リストから除外するツール
      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 プロトコル
• ツールと Plugin