OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk 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"）: 認証ヘッダーは不要です

注意:

  • mode="token" は gateway.auth.token（または OPENCLAW_GATEWAY_TOKEN）を使用します。
  • mode="password" は gateway.auth.password（または OPENCLAW_GATEWAY_PASSWORD）を使用します。
  • 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、またはプライベートイングレス上にのみ配置し、公開インターネットへ直接公開しないでください。

認証マトリクス:

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

リクエスト本文

json
{  "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（ブール値、任意）: 将来の使用のために予約されています。現在は無視されます。

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

ツールの利用可否は、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 Node コマンドリレーからペアリング済みホスト上の system.run に到達可能

cron、gateway、nodes は所有者専用でもあります。このデフォルト拒否リストの対象外であっても、所有者ではない呼び出し元はこのサーフェスからこれらを呼び出せません。

一般的な拒否リストは gateway.tools でカスタマイズします。

json5
{  gateway: {    tools: {      // HTTP /tools/invoke 経由でブロックする追加ツール      deny: ["browser"],      // 所有者または管理者の呼び出し元に対してデフォルト拒否リストから除外するツール      allow: ["gateway"],    },  },}

gateway.tools.allow は公開範囲の上書きであり、スコープの昇格ではありません。ID 情報を伴う HTTP モードでは、gateway.tools.allow に記載されていても、所有者または管理者の ID（operator.admin）を持たない呼び出し元は cron、gateway、nodes を引き続き利用できません。共有シークレットによるベアラー認証には、前述の完全な信頼済みオペレータールールが引き続き適用されます。

グループポリシーによるコンテキスト解決を補助するため、必要に応じて次を設定できます。

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

レスポンス

ステータス 意味
200 { ok: true, result }
400 { ok: false, error: { type, message } }（無効なリクエストまたはツール入力エラー）
401 未認証
403 { ok: false, error: { type, message, requiresApproval? } }（ツール呼び出しがポリシーによりブロックされた）
404 ツールを利用できない（見つからない、または許可リストに含まれていない）
405 メソッドは許可されていない
408 リクエスト本文の読み取りがタイムアウトした
413 リクエスト本文が最大ペイロードサイズを超えた
429 認証のレート制限（Retry-After が設定される）
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