Gateway

Tools memanggil API

Gateway OpenClaw mengekspos endpoint HTTP sederhana untuk memanggil satu tool secara langsung. Endpoint ini selalu aktif dan menggunakan auth Gateway serta kebijakan tool. Seperti permukaan yang kompatibel dengan OpenAI /v1/*, auth bearer rahasia bersama diperlakukan sebagai akses operator tepercaya untuk seluruh gateway.

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

Ukuran payload maksimum default adalah 2 MB.

Autentikasi

Menggunakan konfigurasi auth Gateway.

Jalur auth HTTP umum:

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

Catatan:

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)

Perlakukan endpoint ini sebagai permukaan akses operator penuh untuk instance gateway.

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.

Matriks auth:

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

json

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

Field:

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

Ketersediaan tool difilter melalui rantai kebijakan yang sama dengan yang digunakan oleh agen Gateway:

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)

Jika tool tidak diizinkan oleh kebijakan, endpoint mengembalikan 404.

Catatan batas penting:

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).

HTTP Gateway juga menerapkan daftar penolakan keras secara default (meskipun kebijakan sesi mengizinkan tool):

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

Anda dapat menyesuaikan daftar penolakan ini melalui gateway.tools:

json5

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

gateway.tools.allow adalah override eksposur, bukan peningkatan cakupan. Dalam mode HTTP pembawa identitas, cron, gateway, dan nodes tetap tidak tersedia bagi pemanggil yang tidak memiliki identitas owner/admin (operator.admin) meskipun ketiganya tercantum dalam gateway.tools.allow. Auth bearer rahasia bersama tetap mengikuti aturan operator tepercaya penuh di atas.

Untuk membantu kebijakan grup menyelesaikan konteks, Anda dapat secara opsional menetapkan:

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

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

Terkait

Was this useful?