도구가 API를 호출함

• POST /tools/invoke
• Gateway와 동일한 포트(WS + HTTP 멀티플렉싱): http://<gateway-host>:<port>/tools/invoke
• 기본 최대 요청 본문 크기: 2 MB

​

인증

• 공유 비밀 인증(gateway.auth.mode="token" 또는 "password"): Authorization: Bearer <token-or-password>
• 신뢰할 수 있는 ID 포함 HTTP 인증(gateway.auth.mode="trusted-proxy"): 구성된 ID 인식 프록시를 통해 라우팅하고 필요한 ID 헤더를 주입하도록 합니다.
• 비공개 인그레스 개방형 인증(gateway.auth.mode="none"): 인증 헤더가 필요하지 않습니다.

• mode="token"은 gateway.auth.token(또는 OPENCLAW_GATEWAY_TOKEN)을 사용합니다.
• mode="password"는 gateway.auth.password(또는 OPENCLAW_GATEWAY_PASSWORD)를 사용합니다.
• mode="trusted-proxy"는 HTTP 요청이 구성된 신뢰할 수 있는 프록시 소스에서 와야 합니다. 동일 호스트의 local loopback 프록시는 명시적인 gateway.auth.trustedProxy.allowLoopback = true 설정이 필요합니다.
• 프록시를 우회하는 동일 호스트 내부 호출자는 로컬 직접 대체 경로로 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD를 사용할 수 있습니다. Forwarded, X-Forwarded-*, X-Real-IP 헤더의 증거가 있으면 요청은 대신 신뢰할 수 있는 프록시 경로를 계속 사용합니다.
• gateway.auth.rateLimit이 구성되어 있고 인증 실패가 너무 많이 발생하면 엔드포인트는 Retry-After와 함께 429를 반환합니다.

​

보안 경계(중요)

• 여기서 HTTP 전달자 인증은 좁은 사용자별 범위 모델이 아닙니다.
• 이 엔드포인트의 유효한 Gateway 토큰/비밀번호는 소유자/운영자 자격 증명처럼 취급해야 합니다.
• 공유 비밀 인증 모드(token 및 password)에서는 호출자가 더 좁은 x-openclaw-scopes 헤더를 보내더라도 엔드포인트가 일반적인 전체 운영자 기본값을 복원합니다.
• 공유 비밀 인증은 이 엔드포인트의 직접 도구 호출도 소유자가 보낸 턴으로 취급합니다.
• 신뢰할 수 있는 ID 포함 HTTP 모드(신뢰할 수 있는 프록시 인증 또는 비공개 인그레스의 gateway.auth.mode="none")는 x-openclaw-scopes가 있으면 이를 따르고, 없으면 일반 운영자 기본 범위 집합으로 대체합니다.
• 이 엔드포인트는 local loopback/테일넷/비공개 인그레스에서만 유지하고, 공용 인터넷에 직접 노출하지 마세요.

​

요청 본문

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

• tool / name(문자열, 필수): 호출할 도구 이름입니다. 둘 다 전송되면 name이 우선합니다.
• action(문자열, 선택 사항): 도구 스키마가 action 속성을 지원하고 args에서 아직 설정하지 않은 경우 args.action에 병합됩니다.
• args(객체, 선택 사항): 도구별 인수입니다.
• sessionKey(문자열, 선택 사항): 대상 세션 키입니다. 생략하거나 "main"이면 Gateway는 구성된 기본 세션 키를 사용합니다(session.mainKey와 기본 에이전트를 따르며, 전역 세션 범위에서는 global).
• agentId(문자열, 선택 사항): 해당 에이전트의 세션 키를 해석합니다. 명시적 sessionKey가 이미 다른 에이전트에 매핑되어 충돌하면 400 오류가 발생합니다.
• idempotencyKey(문자열, 선택 사항): 호출에 사용할 안정적인 도구 호출 ID를 도출하는 데 사용됩니다.
• dryRun(불리언, 선택 사항): 향후 사용을 위해 예약되어 있으며 현재는 무시됩니다.

​

정책 및 라우팅 동작

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

• 실행 승인은 운영자 보호 장치이며, 이 HTTP 엔드포인트의 별도 권한 부여 경계가 아닙니다. Gateway 인증 및 도구 정책을 통해 도구에 접근할 수 있으면 /tools/invoke는 호출별 추가 승인 프롬프트를 제공하지 않습니다.
• 여기서 exec에 접근할 수 있으면 변경 가능한 셸 표면으로 취급하세요. write, edit, apply_patch 또는 HTTP 파일 시스템 쓰기 도구를 거부해도 셸 실행이 읽기 전용이 되지는 않습니다.
• 신뢰할 수 없는 호출자와 Gateway 전달자 자격 증명을 공유하지 마세요. 신뢰 경계를 분리해야 한다면 별도의 Gateway를 실행하세요(가능하면 별도의 OS 사용자/호스트에서 실행).

{
  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>(예: slack, telegram)
• x-openclaw-account-id: <accountId>(여러 계정이 있는 경우)
• x-openclaw-message-to: <target>(메시지 도구 정책의 전달 대상)
• x-openclaw-thread-id: <threadId>(메시지 도구 정책의 스레드 컨텍스트)

​

응답

​

예시

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

​

관련 문서

• Gateway 프로토콜
• 도구 및 Plugin