Tools memanggil API

• POST /tools/invoke
• Port yang sama dengan Gateway (multiplex WS + HTTP): http://<gateway-host>:<port>/tools/invoke

​

Autentikasi

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

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

​

Batas keamanan (penting)

• Auth bearer HTTP di sini bukan model cakupan per pengguna yang sempit.
• Token/kata sandi Gateway yang valid untuk endpoint ini harus diperlakukan seperti kredensial pemilik/operator.
• Untuk mode auth rahasia bersama (token dan password), endpoint memulihkan default operator penuh yang normal meskipun pemanggil mengirim header x-openclaw-scopes yang lebih sempit.
• Auth rahasia bersama juga memperlakukan pemanggilan tool langsung pada endpoint ini sebagai giliran owner-sender.
• Mode HTTP pembawa identitas tepercaya (misalnya auth proxy tepercaya atau gateway.auth.mode="none" pada private ingress) menghormati x-openclaw-scopes saat ada dan jika tidak ada akan fallback ke set cakupan default operator normal.
• Pertahankan endpoint ini hanya pada loopback/tailnet/private ingress; jangan mengeksposnya langsung ke internet publik.

• gateway.auth.mode="token" atau "password" + Authorization: Bearer ...
  • membuktikan kepemilikan rahasia operator gateway bersama
  • mengabaikan x-openclaw-scopes yang lebih sempit
  • memulihkan set cakupan operator default penuh: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • memperlakukan pemanggilan tool langsung pada endpoint ini sebagai giliran owner-sender
• mode HTTP pembawa identitas tepercaya (misalnya auth proxy tepercaya, atau gateway.auth.mode="none" pada private ingress)
  • mengautentikasi identitas tepercaya luar atau batas deployment tertentu
  • menghormati x-openclaw-scopes ketika header ada
  • fallback ke set cakupan default operator normal ketika header tidak ada
  • hanya kehilangan semantik pemilik ketika pemanggil secara eksplisit mempersempit cakupan dan menghilangkan operator.admin

​

Isi permintaan

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

• tool (string, wajib): nama tool yang akan dipanggil.
• action (string, opsional): dipetakan ke dalam args jika skema tool mendukung action dan payload args menghilangkannya.
• args (object, opsional): argumen khusus tool.
• sessionKey (string, opsional): kunci sesi target. Jika dihilangkan atau "main", Gateway menggunakan kunci sesi utama yang dikonfigurasi (menghormati session.mainKey dan agen default, atau global dalam cakupan global).
• dryRun (boolean, opsional): dicadangkan untuk penggunaan mendatang; saat ini diabaikan.

​

Perilaku kebijakan + routing

• 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 channel)
• kebijakan subagent (ketika memanggil dengan kunci sesi subagent)

• Persetujuan exec adalah guardrail operator, bukan batas otorisasi terpisah untuk endpoint HTTP ini. Jika sebuah tool dapat dijangkau di sini melalui auth Gateway + kebijakan tool, /tools/invoke tidak menambahkan prompt persetujuan ekstra per panggilan.
• Jika exec dapat dijangkau di sini, perlakukan itu sebagai permukaan shell yang memutasi. Menolak write, edit, apply_patch, atau tool HTTP penulisan-filesystem tidak membuat eksekusi shell menjadi read-only.
• Jangan bagikan kredensial bearer Gateway dengan pemanggil yang tidak tepercaya. Jika Anda memerlukan pemisahan lintas batas kepercayaan, jalankan gateway terpisah (dan idealnya pengguna/host OS terpisah).

• exec - eksekusi perintah langsung (permukaan RCE)
• spawn - pembuatan proses anak arbitrer (permukaan RCE)
• shell - eksekusi perintah shell (permukaan RCE)
• fs_write - mutasi file arbitrer pada host
• fs_delete - penghapusan file arbitrer pada host
• fs_move - pemindahan/penggantian nama file arbitrer pada host
• apply_patch - penerapan patch dapat menulis ulang file arbitrer
• sessions_spawn - orkestrasi sesi; men-spawn agen dari jarak jauh adalah RCE
• sessions_send - injeksi pesan lintas sesi
• cron - bidang kendali automasi persisten
• gateway - bidang kendali gateway; mencegah konfigurasi ulang melalui HTTP
• nodes - relay perintah node dapat menjangkau system.run pada host yang dipasangkan
• whatsapp_login - penyiapan interaktif yang memerlukan pemindaian QR terminal; hang pada HTTP

{
  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 ada beberapa akun)

​

Respons

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (permintaan tidak valid atau error input tool)
• 401 → tidak terotorisasi
• 429 → auth terkena rate limit (Retry-After ditetapkan)
• 404 → tool tidak tersedia (tidak ditemukan atau tidak masuk allowlist)
• 405 → metode tidak diizinkan
• 500 → { ok: false, error: { type, message } } (error eksekusi tool yang tidak terduga; pesan disanitasi)

​

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
• Tool dan plugin