ツール呼び出し API

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

認証

• 共有シークレット認証（gateway.auth.mode="token" または "password"）: Authorization: Bearer <token-or-password>
• 信頼済み ID を持つ HTTP 認証（gateway.auth.mode="trusted-proxy"）: 設定済みの ID 対応プロキシを経由し、必要な ID ヘッダーを注入させます
• プライベート ingress のオープン認証（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 リクエストは設定済みの信頼済みプロキシソースから来る必要があります。同一ホストの loopback プロキシには、明示的な gateway.auth.trustedProxy.allowLoopback = true が必要です。
• gateway.auth.rateLimit が設定されていて認証失敗が多すぎる場合、エンドポイントは Retry-After 付きで 429 を返します。

​

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

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

• 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 モード（たとえば信頼済みプロキシ認証、またはプライベート ingress 上の gateway.auth.mode="none"）
  • 何らかの外側の信頼済み ID またはデプロイ境界を認証します
  • ヘッダーが存在する場合は x-openclaw-scopes を尊重します
  • ヘッダーが存在しない場合は通常のオペレーターのデフォルトスコープセットにフォールバックします
  • 呼び出し元が明示的にスコープを狭め、operator.admin を省略した場合にのみ所有者セマンティクスを失います

​

リクエスト本文

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

• tool（文字列、必須）: 呼び出すツール名。
• action（文字列、省略可）: ツールスキーマが action をサポートし、args ペイロードで省略されている場合に args にマッピングされます。
• args（オブジェクト、省略可）: ツール固有の引数。
• sessionKey（文字列、省略可）: 対象セッションキー。省略された場合、または "main" の場合、Gateway は設定済みのメインセッションキーを使用します（session.mainKey とデフォルトエージェントを尊重し、global スコープでは global）。
• 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 ユーザー/ホスト）を実行してください。

• exec - 直接コマンド実行（RCE サーフェス）
• spawn - 任意の子プロセス作成（RCE サーフェス）
• shell - シェルコマンド実行（RCE サーフェス）
• fs_write - ホスト上の任意のファイル変更
• fs_delete - ホスト上の任意のファイル削除
• fs_move - ホスト上の任意のファイル移動/名前変更
• apply_patch - パッチ適用は任意のファイルを書き換え可能
• sessions_spawn - セッションオーケストレーション。エージェントをリモートで spawn することは RCE
• sessions_send - セッション間メッセージ注入
• cron - 永続的な自動化コントロールプレーン
• gateway - Gateway コントロールプレーン。HTTP 経由の再設定を防ぎます
• nodes - ノードコマンドリレーはペアリング済みホスト上の system.run に到達可能
• whatsapp_login - ターミナル QR スキャンを必要とする対話型セットアップ。HTTP ではハングします

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

• 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 → ツールを利用できません（見つからない、または allowlist されていません）
• 405 → メソッドが許可されていません
• 500 → { ok: false, error: { type, message } }（予期しないツール実行エラー。メッセージはサニタイズ済み）

​

例

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