Narzędzia wywołują API

• POST /tools/invoke
• Ten sam port co Gateway (multipleksowanie WS + HTTP): http://<gateway-host>:<port>/tools/invoke
• Domyślny maksymalny rozmiar treści żądania: 2 MB

​

Uwierzytelnianie

• uwierzytelnianie współdzielonym sekretem (gateway.auth.mode="token" lub "password"): Authorization: Bearer <token-or-password>
• zaufane uwierzytelnianie HTTP przenoszące tożsamość (gateway.auth.mode="trusted-proxy"): skieruj ruch przez skonfigurowane proxy rozpoznające tożsamość i pozwól mu wstrzyknąć wymagane nagłówki tożsamości
• otwarte uwierzytelnianie na prywatnym wejściu (gateway.auth.mode="none"): nagłówek uwierzytelniania nie jest wymagany

• mode="token" używa gateway.auth.token (lub OPENCLAW_GATEWAY_TOKEN).
• mode="password" używa gateway.auth.password (lub OPENCLAW_GATEWAY_PASSWORD).
• mode="trusted-proxy" wymaga, aby żądanie HTTP pochodziło ze skonfigurowanego zaufanego źródła proxy; proxy local loopback na tym samym hoście wymagają jawnego ustawienia gateway.auth.trustedProxy.allowLoopback = true.
• Wewnętrzni wywołujący na tym samym hoście, którzy omijają proxy, mogą użyć gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD jako lokalnego bezpośredniego mechanizmu awaryjnego. Obecność dowolnego nagłówka Forwarded, X-Forwarded-* lub X-Real-IP powoduje, że żądanie pozostaje na ścieżce zaufanego proxy.
• Jeśli skonfigurowano gateway.auth.rateLimit i wystąpi zbyt wiele nieudanych prób uwierzytelnienia, punkt końcowy zwraca 429 z nagłówkiem Retry-After.

​

Granica bezpieczeństwa (ważne)

• Uwierzytelnianie HTTP typu bearer nie stanowi tutaj modelu wąskiego zakresu dla poszczególnych użytkowników.
• Prawidłowy token lub hasło Gateway dla tego punktu końcowego należy traktować jak dane uwierzytelniające właściciela lub operatora.
• W trybach uwierzytelniania współdzielonym sekretem (token i password) punkt końcowy przywraca standardowe pełne domyślne uprawnienia operatora, nawet jeśli wywołujący wysyła węższy nagłówek x-openclaw-scopes.
• Uwierzytelnianie współdzielonym sekretem powoduje również, że bezpośrednie wywołania narzędzi w tym punkcie końcowym są traktowane jako tury nadawcy będącego właścicielem.
• Zaufane tryby HTTP przenoszące tożsamość (uwierzytelnianie przez zaufane proxy lub gateway.auth.mode="none" na prywatnym wejściu) respektują nagłówek x-openclaw-scopes, jeśli jest obecny, a w przeciwnym razie używają standardowego domyślnego zestawu zakresów operatora.
• Udostępniaj ten punkt końcowy wyłącznie przez local loopback, tailnet lub prywatne wejście; nie wystawiaj go bezpośrednio do publicznego Internetu.

​

Treść żądania

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

• tool / name (ciąg znaków, wymagane): nazwa narzędzia do wywołania. Jeśli wysłano oba pola, name ma pierwszeństwo.
• action (ciąg znaków, opcjonalne): scalane z args.action, jeśli schemat narzędzia obsługuje właściwość action, a w args nie została ona jeszcze ustawiona.
• args (obiekt, opcjonalne): argumenty specyficzne dla narzędzia.
• sessionKey (ciąg znaków, opcjonalne): klucz sesji docelowej. Jeśli zostanie pominięty lub ma wartość "main", Gateway używa skonfigurowanego klucza sesji głównej (uwzględnia session.mainKey i domyślnego agenta albo global w globalnym zakresie sesji).
• agentId (ciąg znaków, opcjonalne): określa klucz sesji dla danego agenta. Zwraca błąd 400, jeśli występuje konflikt z jawnym sessionKey, który jest już przypisany do innego agenta.
• idempotencyKey (ciąg znaków, opcjonalne): używany do utworzenia stabilnego identyfikatora wywołania narzędzia.
• dryRun (wartość logiczna, opcjonalne): zarezerwowane do przyszłego użytku; obecnie ignorowane.

​

Zachowanie zasad i routingu

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• zasady grup (jeśli klucz sesji jest przypisany do grupy lub kanału)
• zasady podagenta (podczas wywoływania z kluczem sesji podagenta)

• Zatwierdzenia wykonywania stanowią zabezpieczenia operatora, a nie odrębną granicę autoryzacji dla tego punktu końcowego HTTP. Jeśli narzędzie jest tutaj dostępne na podstawie uwierzytelniania Gateway i zasad narzędzi, /tools/invoke nie dodaje dodatkowego monitu o zatwierdzenie dla każdego wywołania.
• Jeśli exec jest tutaj dostępne, traktuj je jako interfejs powłoki umożliwiający modyfikacje. Odmowa dostępu do write, edit, apply_patch lub narzędzi HTTP zapisujących w systemie plików nie sprawia, że wykonywanie poleceń powłoki staje się tylko do odczytu.
• Nie udostępniaj danych uwierzytelniających typu bearer Gateway niezaufanym wywołującym. Jeśli potrzebujesz rozdzielenia granic zaufania, uruchom oddzielne instancje Gateway (najlepiej jako oddzielni użytkownicy systemu operacyjnego lub na oddzielnych hostach).

{
  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> (przykład: slack, telegram)
• x-openclaw-account-id: <accountId> (gdy istnieje wiele kont)
• x-openclaw-message-to: <target> (cel dostarczania dla zasad narzędzia wiadomości)
• x-openclaw-thread-id: <threadId> (kontekst wątku dla zasad narzędzia wiadomości)

​

Odpowiedzi

​

Przykład

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

​

Powiązane

• Protokół Gateway
• Narzędzia i pluginy