도구 호출 (HTTP)

OpenClaw 게이트웨이는 단일 도구를 직접 호출하기 위한 간단한 HTTP 엔드포인트를 제공합니다. 항상 활성화되어 있지만, 게이트웨이 인증 및 도구 정책에 의해 제어됩니다.

POST /tools/invoke
게이트웨이와 동일한 포트 (WS + HTTP 다중화): http://<gateway-host>:<port>/tools/invoke

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

인증

게이트웨이 인증 설정을 사용합니다. Bearer 토큰을 전송하세요:

Authorization: Bearer <token>

참고:

gateway.auth.mode="token"인 경우, gateway.auth.token (또는 OPENCLAW_GATEWAY_TOKEN)을 사용합니다.
gateway.auth.mode="password"인 경우, gateway.auth.password (또는 OPENCLAW_GATEWAY_PASSWORD)를 사용합니다.
gateway.auth.rateLimit이 설정되어 있고 인증 실패가 너무 많이 발생하면, 엔드포인트는 Retry-After와 함께 429를 반환합니다.

요청 본문

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

필드:

tool (문자열, 필수): 호출할 도구 이름.
action (문자열, 선택): 도구 스키마가 action을 지원하고 args 페이로드에서 생략된 경우 args에 매핑됩니다.
args (객체, 선택): 도구별 인수.
sessionKey (문자열, 선택): 대상 세션 키. 생략하거나 "main"이면, 게이트웨이가 설정된 메인 세션 키를 사용합니다 (session.mainKey와 기본 에이전트를 따르거나, 전역 범위에서 global).
dryRun (boolean, 선택): 향후 사용을 위해 예약됨. 현재 무시됩니다.

정책 + 라우팅 동작

도구 가용성은 게이트웨이 에이전트에서 사용하는 것과 동일한 정책 체인을 통해 필터링됩니다:

tools.profile / tools.byProvider.profile
tools.allow / tools.byProvider.allow
agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
그룹 정책 (세션 키가 그룹이나 채널에 매핑되는 경우)
서브에이전트 정책 (서브에이전트 세션 키로 호출 시)

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

게이트웨이 HTTP는 세션 정책에서 도구를 허용하더라도 기본적으로 하드 거부 목록을 적용합니다:

sessions_spawn
sessions_send
gateway
whatsapp_login

gateway.tools로 이 거부 목록을 커스터마이즈할 수 있습니다:

{
  gateway: {
    tools: {
      // HTTP /tools/invoke를 통해 추가로 차단할 도구
      deny: ["browser"],
      // 기본 거부 목록에서 제거할 도구
      allow: ["gateway"],
    },
  },
}

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

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

응답

200 → { ok: true, result }
400 → { ok: false, error: { type, message } } (잘못된 요청 또는 도구 입력 오류)
401 → 인증 실패
429 → 인증 속도 제한 (Retry-After 설정)
404 → 도구 사용 불가 (찾을 수 없거나 허용 목록에 없음)
405 → 잘못된 메서드
500 → { ok: false, error: { type, message } } (예기치 않은 도구 실행 오류, 메시지 정제됨)

예시

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