Tools Invoke (HTTP)

OpenClaw의 Gateway는 단일 tool을 직접 호출하기 위한 간단한 HTTP 엔드포인트를 노출합니다. 항상 활성화되어 있지만 Gateway 인증 및 tool 정책으로 게이트됩니다.

  • POST /tools/invoke
  • Gateway와 동일한 포트 (WS + HTTP 멀티플렉스): http://<gateway-host>:<port>/tools/invoke

기본 최대 페이로드 크기는 2 MB입니다.

인증

Gateway 인증 구성을 사용합니다. bearer token을 전송하세요:

  • Authorization: Bearer <token>

참고:

  • gateway.auth.mode="token"인 경우, gateway.auth.token (또는 OPENCLAW_GATEWAY_TOKEN)을 사용합니다.
  • gateway.auth.mode="password"인 경우, gateway.auth.password (또는 OPENCLAW_GATEWAY_PASSWORD)를 사용합니다.

요청 본문

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

필드:

  • tool (문자열, 필수): 호출할 tool 이름.
  • action (문자열, 선택): tool 스키마가 action을 지원하고 args 페이로드에서 생략된 경우 args에 매핑됨.
  • args (객체, 선택): tool별 인수.
  • sessionKey (문자열, 선택): 대상 세션 키. 생략되거나 "main"인 경우, Gateway는 구성된 main 세션 키를 사용합니다 (session.mainKey 및 기본 agent를 존중하거나 전역 scope에서는 global).
  • dryRun (부울, 선택): 향후 사용을 위해 예약됨; 현재 무시됨.

정책 + 라우팅 동작

Tool 가용성은 Gateway agent가 사용하는 것과 동일한 정책 체인을 통해 필터링됩니다:

  • tools.profile / tools.byProvider.profile
  • tools.allow / tools.byProvider.allow
  • agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
  • 그룹 정책 (세션 키가 그룹 또는 채널에 매핑되는 경우)
  • subagent 정책 (subagent 세션 키로 호출할 때)

tool이 정책에 의해 허용되지 않으면, 엔드포인트는 404를 반환합니다.

그룹 정책이 컨텍스트를 해결하는 데 도움이 되도록, 선택적으로 다음을 설정할 수 있습니다:

  • x-openclaw-message-channel: <channel> (예: slack, telegram)
  • x-openclaw-account-id: <accountId> (여러 계정이 존재하는 경우)

응답

  • 200 → { ok: true, result }
  • 400 → { ok: false, error: { type, message } } (유효하지 않은 요청 또는 tool 오류)
  • 401 → 승인되지 않음
  • 404 → tool을 사용할 수 없음 (찾을 수 없거나 허용 목록에 없음)
  • 405 → 메서드가 허용되지 않음

예제

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'
← 문서로 돌아가기