OpenClaw HTTP API로 도구 즉시 실행하기

개발을 하다 보면 복잡한 에이전트 대화 흐름을 거치지 않고, 특정 도구만 즉시 실행하고 싶을 때가 있죠. 매번 전체 컨텍스트를 구성하는 대신 HTTP 요청 한 번으로 원하는 기능을 호출할 수 있다면 정말 편할 거예요.

OpenClaw Gateway는 단일 도구를 직접 호출할 수 있는 심플한 HTTP 엔드포인트를 제공해요. 이 기능은 항상 활성화되어 있으며, Gateway 인증과 도구 정책을 그대로 사용합니다. OpenAI 호환 /v1/* 인터페이스와 마찬가지로, 공유 비밀(shared-secret) 방식의 Bearer 인증은 전체 Gateway에 대한 신뢰할 수 있는 운영자 접근으로 처리돼요.

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

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

인증 (Authentication)

Gateway 인증 설정을 사용해요. 다음과 같이 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를 반환해요.

보안 경계 (보안상 중요)

이 엔드포인트는 Gateway 인스턴스에 대한 전체 운영자 권한(full operator-access) 인터페이스로 취급해야 해요.

여기서 사용하는 HTTP Bearer 인증은 사용자별로 범위를 좁게 제한하는 모델이 아니에요.
이 엔드포인트에 유효한 Gateway 토큰이나 비밀번호는 소유자 또는 운영자 자격 증명과 동일하게 다뤄야 합니다.
공유 비밀 인증 모드(token 및 password)의 경우, 호출자가 더 좁은 범위의 x-openclaw-scopes 헤더를 보내더라도 엔드포인트는 일반적인 전체 운영자 기본값을 복원해요.
또한 공유 비밀 인증은 이 엔드포인트에서의 직접적인 도구 호출을 소유자 전송 턴(owner-sender turns)으로 처리합니다.
신뢰할 수 있는 ID 기반 HTTP 모드(예: 신뢰할 수 있는 프록시 인증 또는 프라이빗 인그레스의 gateway.auth.mode="none")는 요청에 선언된 운영자 범위를 여전히 준수해요.
이 엔드포인트는 loopback, tailnet, 또는 프라이빗 인그레스에서만 유지하고, 공용 인터넷에 직접 노출하지 마세요.

인증 매트릭스:

gateway.auth.mode="token" 또는 "password" + Authorization: Bearer ...
- 공유된 Gateway 운영자 비밀 키 소유를 증명함
- 더 좁은 범위의 x-openclaw-scopes를 무시함
- 전체 기본 운영자 범위 세트를 복원함
- 이 엔드포인트에서의 직접 도구 호출을 소유자 전송 턴으로 처리함
신뢰할 수 있는 ID 기반 HTTP 모드 (예: 신뢰할 수 있는 프록시 인증, 또는 프라이빗 인그레스의 gateway.auth.mode="none")
- 외부의 신뢰할 수 있는 ID 또는 배포 경계를 인증함
- 선언된 x-openclaw-scopes 헤더를 준수함
- 선언된 범위에 operator.admin이 실제로 포함된 경우에만 소유자 의미론(owner semantics)을 가짐

요청 본문 (Request body)

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

필드 설명:

tool (string, 필수): 호출할 도구 이름.
action (string, 선택): 도구 스키마가 action을 지원하고 args 페이로드에서 생략된 경우 args로 매핑됨.
args (object, 선택): 도구별 인자.
sessionKey (string, 선택): 대상 세션 키. 생략하거나 "main"으로 설정하면 Gateway에 설정된 메인 세션 키를 사용해요 (session.mainKey 및 기본 에이전트, 또는 글로벌 범위의 global 준수).
dryRun (boolean, 선택): 향후 사용을 위해 예약됨. 현재는 무시됩니다.

정책 및 라우팅 동작

도구 가용성은 Gateway 에이전트가 사용하는 것과 동일한 정책 체인을 통해 필터링돼요.

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

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

중요한 경계 사항:

실행 승인(Exec approvals)은 운영자 가드레일이며, 이 HTTP 엔드포인트를 위한 별도의 권한 부여 경계가 아니에요. 도구가 Gateway 인증 및 도구 정책을 통해 여기서 접근 가능하다면, /tools/invoke는 호출 시마다 별도의 승인 프롬프트를 추가하지 않습니다.
신뢰할 수 없는 호출자에게 Gateway Bearer 자격 증명을 공유하지 마세요. 신뢰 경계 간의 분리가 필요하다면 별도의 Gateway를 실행하는 것이 좋습니다 (가급적 별도의 OS 사용자나 호스트 사용 권장).

Gateway HTTP는 세션 정책이 도구를 허용하더라도 기본적으로 강력한 거부 목록(deny list)을 적용해요.

exec — 직접 명령 실행 (RCE 위험)
spawn — 임의의 자식 프로세스 생성 (RCE 위험)
shell — 쉘 명령 실행 (RCE 위험)
fs_write — 호스트의 임의 파일 수정
fs_delete — 호스트의 임의 파일 삭제
fs_move — 호스트의 임의 파일 이동/이름 변경
apply_patch — 패치 적용을 통한 임의 파일 재작성 가능
sessions_spawn — 세션 오케스트레이션. 원격으로 에이전트를 생성하는 것은 RCE와 같음
sessions_send — 교차 세션 메시지 주입
cron — 지속적인 자동화 제어 평면
gateway — Gateway 제어 평면. HTTP를 통한 재설정 방지
nodes — 노드 명령 릴레이를 통해 연결된 호스트의 system.run에 접근 가능
whatsapp_login — 터미널 QR 스캔이 필요한 대화형 설정. HTTP에서 응답 대기 상태에 빠질 수 있음

gateway.tools를 통해 이 거부 목록을 커스터마이징할 수 있어요.

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list
      allow: ["gateway"],
    },
  },
}

그룹 정책이 컨텍스트를 확인하는 데 도움을 주려면 다음을 선택적으로 설정할 수 있어요.

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

응답 (Responses)

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

예시 (Example)

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

AI Setup Assistant

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.