Alat memanggil API

• POST /tools/invoke
• Port yang sama dengan Gateway (multipleks WS + HTTP): http://<gateway-host>:<port>/tools/invoke
• Ukuran maksimum default isi permintaan: 2 MB

​

Autentikasi

• autentikasi rahasia bersama (gateway.auth.mode="token" atau "password"): Authorization: Bearer <token-or-password>
• autentikasi HTTP tepercaya yang membawa identitas (gateway.auth.mode="trusted-proxy"): rutekan melalui proksi sadar-identitas yang dikonfigurasi dan biarkan proksi tersebut menyisipkan header identitas yang diperlukan
• autentikasi terbuka pada ingress privat (gateway.auth.mode="none"): header autentikasi tidak diperlukan

• mode="token" menggunakan gateway.auth.token (atau OPENCLAW_GATEWAY_TOKEN).
• mode="password" menggunakan gateway.auth.password (atau OPENCLAW_GATEWAY_PASSWORD).
• mode="trusted-proxy" mengharuskan permintaan HTTP berasal dari sumber proksi tepercaya yang dikonfigurasi; proksi local loopback pada host yang sama memerlukan gateway.auth.trustedProxy.allowLoopback = true secara eksplisit.
• Pemanggil internal pada host yang sama yang melewati proksi dapat menggunakan gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD sebagai fallback langsung lokal. Adanya bukti header Forwarded, X-Forwarded-*, atau X-Real-IP akan tetap mempertahankan permintaan pada jalur proksi tepercaya.
• Jika gateway.auth.rateLimit dikonfigurasi dan terjadi terlalu banyak kegagalan autentikasi, endpoint mengembalikan 429 dengan Retry-After.

​

Batas keamanan (penting)

• Autentikasi bearer HTTP di sini bukan model cakupan sempit per pengguna.
• Token/kata sandi Gateway yang valid untuk endpoint ini harus diperlakukan seperti kredensial pemilik/operator.
• Untuk mode autentikasi rahasia bersama (token dan password), endpoint memulihkan cakupan default operator penuh yang normal meskipun pemanggil mengirim header x-openclaw-scopes yang lebih sempit.
• Autentikasi rahasia bersama juga memperlakukan pemanggilan alat langsung pada endpoint ini sebagai giliran dari pengirim-pemilik.
• Mode HTTP tepercaya yang membawa identitas (autentikasi proksi tepercaya, atau gateway.auth.mode="none" pada ingress privat) mematuhi x-openclaw-scopes jika tersedia dan jika tidak, kembali ke kumpulan cakupan default operator yang normal.
• Pertahankan endpoint ini hanya pada local loopback/tailnet/ingress privat; jangan mengeksposnya secara langsung ke internet publik.

​

Isi permintaan

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

• tool / name (string, wajib): nama alat yang akan dipanggil. name diprioritaskan jika keduanya dikirim.
• action (string, opsional): digabungkan ke dalam args.action jika skema alat mendukung properti action dan args belum menetapkannya.
• args (objek, opsional): argumen khusus alat.
• sessionKey (string, opsional): kunci sesi target. Jika dihilangkan atau "main", Gateway menggunakan kunci sesi utama yang dikonfigurasi (mematuhi session.mainKey dan agen default, atau global dalam cakupan sesi global).
• agentId (string, opsional): menyelesaikan kunci sesi untuk agen tersebut. Menghasilkan kesalahan 400 jika bertentangan dengan sessionKey eksplisit yang sudah dipetakan ke agen lain.
• idempotencyKey (string, opsional): digunakan untuk menghasilkan ID pemanggilan alat yang stabil bagi pemanggilan tersebut.
• dryRun (boolean, opsional): dicadangkan untuk penggunaan mendatang; saat ini diabaikan.

​

Perilaku kebijakan + perutean

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• kebijakan grup (jika kunci sesi dipetakan ke grup atau kanal)
• kebijakan subagen (ketika memanggil dengan kunci sesi subagen)

• Persetujuan eksekusi adalah pagar pengaman operator, bukan batas otorisasi terpisah untuk endpoint HTTP ini. Jika suatu alat dapat dijangkau di sini melalui autentikasi Gateway + kebijakan alat, /tools/invoke tidak menambahkan permintaan persetujuan tambahan per panggilan.
• Jika exec dapat dijangkau di sini, perlakukan sebagai permukaan shell yang dapat mengubah keadaan. Menolak write, edit, apply_patch, atau alat tulis sistem berkas melalui HTTP tidak membuat eksekusi shell menjadi hanya-baca.
• Jangan bagikan kredensial bearer Gateway dengan pemanggil yang tidak tepercaya. Jika Anda memerlukan pemisahan lintas batas kepercayaan, jalankan gateway terpisah (idealnya pada pengguna OS/host yang terpisah).

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

• x-openclaw-message-channel: <channel> (contoh: slack, telegram)
• x-openclaw-account-id: <accountId> (ketika terdapat beberapa akun)
• x-openclaw-message-to: <target> (target pengiriman untuk kebijakan alat pesan)
• x-openclaw-thread-id: <threadId> (konteks utas untuk kebijakan alat pesan)

​

Respons

​

Contoh

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

​

Terkait

• Protokol Gateway
• Alat dan plugin