English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Gateway

ツール呼び出し API

OpenClaw の Gateway は、単一のツールを直接呼び出すためのシンプルな HTTP エンドポイントを公開します。これは常に有効で、Gateway 認証とツールポリシーを使用します。OpenAI 互換の /v1/* サーフェスと同様に、共有シークレットのベアラー認証は、Gateway 全体に対する信頼済みオペレーターアクセスとして扱われます。

  • POST /tools/invoke
  • Gateway と同じポート (WS + HTTP 多重化): http://<gateway-host>:<port>/tools/invoke

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

認証

Gateway 認証設定を使用します。

一般的な HTTP 認証パス:

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

注記:

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

セキュリティ境界 (重要)

このエンドポイントは、Gateway インスタンスに対する完全なオペレーターアクセスサーフェスとして扱ってください。

  • ここでの HTTP ベアラー認証は、狭いユーザー単位のスコープモデルではありません。
  • このエンドポイントに対する有効な Gateway トークン/パスワードは、所有者/オペレーター資格情報のように扱う必要があります。
  • 共有シークレット認証モード (token と password) では、呼び出し元がより狭い x-openclaw-scopes ヘッダーを送信した場合でも、エンドポイントは通常の完全なオペレーターデフォルトを復元します。
  • 共有シークレット認証では、このエンドポイントでの直接ツール呼び出しも所有者送信者ターンとして扱います。
  • 信頼済み ID 付き HTTP モード (たとえば信頼済みプロキシ認証、またはプライベートイングレス上の gateway.auth.mode="none") は、x-openclaw-scopes が存在する場合はそれを尊重し、存在しない場合は通常のオペレーターデフォルトスコープセットにフォールバックします。
  • このエンドポイントはループバック/tailnet/プライベートイングレス上のみに置いてください。公開インターネットに直接公開しないでください。

認証マトリクス:

  • gateway.auth.mode="token" または "password" + Authorization: Bearer ...
    • 共有 Gateway オペレーターシークレットの保持を証明します
    • より狭い x-openclaw-scopes を無視します
    • 完全なデフォルトオペレータースコープセットを復元します: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
    • このエンドポイントでの直接ツール呼び出しを所有者送信者ターンとして扱います
  • 信頼済み ID 付き HTTP モード (たとえば信頼済みプロキシ認証、またはプライベートイングレス上の gateway.auth.mode="none")
    • 外部の信頼済み ID またはデプロイ境界を認証します
    • ヘッダーが存在する場合は x-openclaw-scopes を尊重します
    • ヘッダーが存在しない場合は、通常のオペレーターデフォルトスコープセットにフォールバックします
    • 呼び出し元が明示的にスコープを狭め、operator.admin を省略した場合にのみ所有者セマンティクスを失います

リクエスト本文

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

フィールド:

  • tool (文字列、必須): 呼び出すツール名。
  • action (文字列、省略可): ツールスキーマが action をサポートし、args ペイロードで省略された場合に args にマッピングされます。
  • args (オブジェクト、省略可): ツール固有の引数。
  • sessionKey (文字列、省略可): 対象セッションキー。省略された場合または "main" の場合、Gateway は設定済みのメインセッションキーを使用します (session.mainKey とデフォルトエージェントを尊重し、グローバルスコープでは global)。
  • dryRun (ブール値、省略可): 将来の使用のために予約されています。現在は無視されます。

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

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

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

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

重要な境界注記:

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

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

  • 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 でカスタマイズできます。

json5
{  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"],    },  },}

gateway.tools.allow は公開オーバーライドであり、スコープ昇格ではありません。ID 付き HTTP モードでは、cron、gateway、nodes は、gateway.tools.allow に列挙されていても、所有者/admin ID (operator.admin) を持たない呼び出し元には引き続き利用できません。共有シークレットのベアラー認証は、上記の完全な信頼済みオペレータールールに従います。

グループポリシーがコンテキストを解決しやすくするため、任意で次を設定できます。

  • 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 } } (予期しないツール実行エラー。メッセージはサニタイズ済み)

例

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

関連

Was this useful?
On this page

On this page