--- read_when: - 完全なエージェントターンを実行せずにツールを呼び出す - ツールポリシーの適用が必要な自動化の構築 summary: Gateway HTTPエンドポイント経由で単一のツールを直接呼び出す title: ツールが API を呼び出す x-i18n: generated_at: "2026-07-11T22:17:22Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 6d07f765d63255e718d5e558b662589e77b2992538f43288cd83e6e3f2a06dda source_path: gateway/tools-invoke-http-api.md workflow: 16 --- OpenClaw の Gateway は、単一のツールを直接呼び出すための HTTP エンドポイントを公開します。このエンドポイントは常に有効で、Gateway 認証とツールポリシーを使用します。OpenAI 互換の `/v1/*` サーフェスと同様に、共有シークレットによるベアラー認証は、Gateway 全体に対する信頼済みオペレーターアクセスとして扱われます。 - `POST /tools/invoke` - Gateway と同じポート（WS + HTTP 多重化）: `http://:/tools/invoke` - デフォルトの最大リクエスト本文サイズ: 2 MB ## 認証 Gateway の認証設定を使用します。 一般的な HTTP 認証経路: - 共有シークレット認証（`gateway.auth.mode="token"` または `"password"`）: `Authorization: Bearer ` - 信頼済みの 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..tools.allow` / `agents..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: `（例: `slack`、`telegram`） - `x-openclaw-account-id: `（複数のアカウントが存在する場合） - `x-openclaw-message-to: `（メッセージツールポリシー用の配信先） - `x-openclaw-thread-id: `（メッセージツールポリシー用のスレッドコンテキスト） ## レスポンス | ステータス | 意味 | | ---------- | -------------------------------------------------------------------------------------------------- | | `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": {} }' ``` ## 関連項目 - [Gateway プロトコル](/ja-JP/gateway/protocol) - [ツールとプラグイン](/ja-JP/tools)