Tools invoke API

기준일: 2026-07-26
공식 기준: Tools invoke API

Tools invoke API 문서는 OpenClaw 공식 문서(gateway/tools-invoke-http-api)를 한국어로 정리한 가이드입니다. Invoke a single tool directly via the Gateway HTTP endpoint 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Invoke a single tool directly via the Gateway HTTP endpoint

한국어 가이드 범위: gateway/tools-invoke-http-api 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

인증
Security boundary (important)
Request body
Policy + routing behavior
Responses
예제
관련 문서

상세 내용

본문

OpenClaw's Gateway exposes an HTTP endpoint for invoking a single tool directly. It is always enabled and uses Gateway auth plus tool policy. Like the OpenAI-compatible /v1/* surface, shared-secret bearer auth is treated as trusted operator access for the whole gateway.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

POST /tools/invoke
Same port as the Gateway (WS + HTTP multiplex): http://<gateway-host>:<port>/tools/invoke
Default max request body size: 2 MB

인증

주요 항목:

shared-secret auth (gateway.auth.mode="token" or "password"): Authorization: Bearer <token-or-password>
trusted identity-bearing HTTP auth (gateway.auth.mode="trusted-proxy"): route through the configured identity-aware proxy and let it inject the required identity headers
private-ingress open auth (gateway.auth.mode="none"): no auth header required
mode="token" uses gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN).
mode="password" uses gateway.auth.password (or OPENCLAW_GATEWAY_PASSWORD).
mode="trusted-proxy" requires the HTTP request to come from a configured trusted proxy source; same-host loopback proxies require explicit gateway.auth.trustedProxy.allowLoopback = true.
Internal same-host callers that bypass the proxy can use gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD as a local direct fallback. Any Forwarded, X-Forwarded-*, or X-Real-IP header evidence keeps the request on the trusted-proxy path instead.
If gateway.auth.rateLimit is configured and too many auth failures occur, the endpoint returns 429 with Retry-After.

Security boundary (important)

Treat this endpoint as a full operator-access surface for the gateway instance.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

HTTP bearer auth here is not a narrow per-user scope model.
A valid Gateway token/password for this endpoint should be treated like an owner/operator credential.
For shared-secret auth modes (token and password), the endpoint restores the normal full operator defaults even if the caller sends a narrower x-openclaw-scopes header.
Shared-secret auth also treats direct tool invokes on this endpoint as owner-sender turns.
Trusted identity-bearing HTTP modes (trusted proxy auth, or gateway.auth.mode="none" on a private ingress) honor x-openclaw-scopes when present and otherwise fall back to the normal operator default scope set.
Keep this endpoint on loopback/tailnet/private ingress only; do not expose it directly to the public internet.

Auth mode	Behavior
`token` or `password` + `Authorization: Bearer ...`	Proves possession of the shared gateway operator secret. Ignores narrower `x-openclaw-scopes`. Restores the full default operator scope set: `operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`. Treats direct tool invokes as owner-sender turns.
Trusted identity-bearing HTTP (trusted proxy auth, or `mode="none"` on private ingress)	Authenticates an outer trusted identity or deployment boundary. Honors `x-openclaw-scopes` when present. Falls back to the normal operator default scope set when the header is absent. Only loses owner semantics when the caller explicitly narrows scopes and omits `operator.admin`.

Request body

주요 항목:

tool / name (string, required): tool name to invoke. name takes precedence if both are sent.
action (string, optional): merged into args.action if the tool schema supports an action property and args did not already set one.
args (object, optional): tool-specific arguments.
sessionKey (string, optional): target session key. If omitted or "main", the Gateway uses the configured main session key (honors session.mainKey and the default agent, or global in global session scope).
agentId (string, optional): resolves the session key for that agent. Errors with 400 if it conflicts with an explicit sessionKey that already maps to a different agent.
idempotencyKey (string, optional): used to derive a stable tool-call id for the invocation.
dryRun (boolean, optional): reserved for future use; currently ignored.

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

Policy + routing behavior

Tool availability is filtered through the same policy chain used by Gateway agents:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

tools.profile / tools.byProvider.profile
tools.allow / tools.byProvider.allow
agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
group policies (if the session key maps to a group or channel)
subagent policy (when invoking with a subagent session key)
Exec approvals are operator guardrails, not a separate authorization boundary for this HTTP endpoint. If a tool is reachable here via Gateway auth + tool policy, /tools/invoke does not add an extra per-call approval prompt.
If exec is reachable here, treat it as a mutating shell surface. Denying write, edit, apply_patch, or HTTP filesystem-write tools does not make shell execution read-only.
Do not share Gateway bearer credentials with untrusted callers. If you need separation across trust boundaries, run separate gateways (ideally on separate OS users/hosts).
x-openclaw-message-channel: <channel> (example: slack, telegram)
x-openclaw-account-id: <accountId> (when multiple accounts exist)
x-openclaw-message-to: <target> (delivery target for message-tool policy)
x-openclaw-thread-id: <threadId> (thread context for message-tool policy)

Tool	Reason
`exec`	Direct command execution (RCE surface)
`spawn`	Arbitrary child process creation (RCE surface)
`shell`	Shell command execution (RCE surface)
`fs_write`	Arbitrary file mutation on the host
`fs_delete`	Arbitrary file deletion on the host
`fs_move`	Arbitrary file move/rename on the host
`apply_patch`	Patch application can rewrite arbitrary files
`sessions_spawn`	Session orchestration; spawning agents remotely is RCE
`sessions_send`	Cross-session message injection
`cron`	Persistent automation control plane
`gateway`	Gateway control plane; prevents reconfiguration via HTTP
`nodes`	Node command relay can reach `system.run` on paired hosts

{
  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"],
    },
  },
}

Responses

Status	Meaning
`200`	`{ ok: true, result }`
`400`	`{ ok: false, error: { type, message } }` (invalid request or tool input error)
`401`	Unauthorized
`403`	`{ ok: false, error: { type, message, requiresApproval? } }` (tool call blocked by policy)
`404`	Tool not available (not found or not allowlisted)
`405`	Method not allowed
`408`	Request body read timed out
`413`	Request body exceeded the max payload size
`429`	Auth rate-limited (`Retry-After` set)
`500`	`{ ok: false, error: { type, message } }` (unexpected tool execution error; sanitized message)

예제

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/tools-invoke-http-api
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

{
  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"],
    },
  },
}

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

Tools invoke API

기준일: 2026-07-26
공식 기준: Tools invoke API

핵심 요약

Invoke a single tool directly via the Gateway HTTP endpoint

한국어 가이드 범위: gateway/tools-invoke-http-api 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

인증
Security boundary (important)
Request body
Policy + routing behavior
Responses
예제
관련 문서

상세 내용

본문

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

POST /tools/invoke
Same port as the Gateway (WS + HTTP multiplex): http://<gateway-host>:<port>/tools/invoke
Default max request body size: 2 MB

인증

주요 항목:

shared-secret auth (gateway.auth.mode="token" or "password"): Authorization: Bearer <token-or-password>
trusted identity-bearing HTTP auth (gateway.auth.mode="trusted-proxy"): route through the configured identity-aware proxy and let it inject the required identity headers
private-ingress open auth (gateway.auth.mode="none"): no auth header required
mode="token" uses gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN).
mode="password" uses gateway.auth.password (or OPENCLAW_GATEWAY_PASSWORD).
mode="trusted-proxy" requires the HTTP request to come from a configured trusted proxy source; same-host loopback proxies require explicit gateway.auth.trustedProxy.allowLoopback = true.
Internal same-host callers that bypass the proxy can use gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD as a local direct fallback. Any Forwarded, X-Forwarded-*, or X-Real-IP header evidence keeps the request on the trusted-proxy path instead.
If gateway.auth.rateLimit is configured and too many auth failures occur, the endpoint returns 429 with Retry-After.

Security boundary (important)

Treat this endpoint as a full operator-access surface for the gateway instance.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

HTTP bearer auth here is not a narrow per-user scope model.
A valid Gateway token/password for this endpoint should be treated like an owner/operator credential.
For shared-secret auth modes (token and password), the endpoint restores the normal full operator defaults even if the caller sends a narrower x-openclaw-scopes header.
Shared-secret auth also treats direct tool invokes on this endpoint as owner-sender turns.
Trusted identity-bearing HTTP modes (trusted proxy auth, or gateway.auth.mode="none" on a private ingress) honor x-openclaw-scopes when present and otherwise fall back to the normal operator default scope set.
Keep this endpoint on loopback/tailnet/private ingress only; do not expose it directly to the public internet.

Auth mode	Behavior
`token` or `password` + `Authorization: Bearer ...`	Proves possession of the shared gateway operator secret. Ignores narrower `x-openclaw-scopes`. Restores the full default operator scope set: `operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`. Treats direct tool invokes as owner-sender turns.
Trusted identity-bearing HTTP (trusted proxy auth, or `mode="none"` on private ingress)	Authenticates an outer trusted identity or deployment boundary. Honors `x-openclaw-scopes` when present. Falls back to the normal operator default scope set when the header is absent. Only loses owner semantics when the caller explicitly narrows scopes and omits `operator.admin`.

Request body

주요 항목:

tool / name (string, required): tool name to invoke. name takes precedence if both are sent.
action (string, optional): merged into args.action if the tool schema supports an action property and args did not already set one.
args (object, optional): tool-specific arguments.
sessionKey (string, optional): target session key. If omitted or "main", the Gateway uses the configured main session key (honors session.mainKey and the default agent, or global in global session scope).
agentId (string, optional): resolves the session key for that agent. Errors with 400 if it conflicts with an explicit sessionKey that already maps to a different agent.
idempotencyKey (string, optional): used to derive a stable tool-call id for the invocation.
dryRun (boolean, optional): reserved for future use; currently ignored.

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

Policy + routing behavior

Tool availability is filtered through the same policy chain used by Gateway agents:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

tools.profile / tools.byProvider.profile
tools.allow / tools.byProvider.allow
agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
group policies (if the session key maps to a group or channel)
subagent policy (when invoking with a subagent session key)
Exec approvals are operator guardrails, not a separate authorization boundary for this HTTP endpoint. If a tool is reachable here via Gateway auth + tool policy, /tools/invoke does not add an extra per-call approval prompt.
If exec is reachable here, treat it as a mutating shell surface. Denying write, edit, apply_patch, or HTTP filesystem-write tools does not make shell execution read-only.
Do not share Gateway bearer credentials with untrusted callers. If you need separation across trust boundaries, run separate gateways (ideally on separate OS users/hosts).
x-openclaw-message-channel: <channel> (example: slack, telegram)
x-openclaw-account-id: <accountId> (when multiple accounts exist)
x-openclaw-message-to: <target> (delivery target for message-tool policy)
x-openclaw-thread-id: <threadId> (thread context for message-tool policy)

Tool	Reason
`exec`	Direct command execution (RCE surface)
`spawn`	Arbitrary child process creation (RCE surface)
`shell`	Shell command execution (RCE surface)
`fs_write`	Arbitrary file mutation on the host
`fs_delete`	Arbitrary file deletion on the host
`fs_move`	Arbitrary file move/rename on the host
`apply_patch`	Patch application can rewrite arbitrary files
`sessions_spawn`	Session orchestration; spawning agents remotely is RCE
`sessions_send`	Cross-session message injection
`cron`	Persistent automation control plane
`gateway`	Gateway control plane; prevents reconfiguration via HTTP
`nodes`	Node command relay can reach `system.run` on paired hosts

{
  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"],
    },
  },
}

Responses

Status	Meaning
`200`	`{ ok: true, result }`
`400`	`{ ok: false, error: { type, message } }` (invalid request or tool input error)
`401`	Unauthorized
`403`	`{ ok: false, error: { type, message, requiresApproval? } }` (tool call blocked by policy)
`404`	Tool not available (not found or not allowlisted)
`405`	Method not allowed
`408`	Request body read timed out
`413`	Request body exceeded the max payload size
`429`	Auth rate-limited (`Retry-After` set)
`500`	`{ ok: false, error: { type, message } }` (unexpected tool execution error; sanitized message)

예제

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/tools-invoke-http-api
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

{
  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"],
    },
  },
}

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

Tools invoke API

핵심 요약

문서 구성

상세 내용

본문

인증

Security boundary (important)

Request body

Policy + routing behavior

Responses

예제

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Tools invoke API

핵심 요약

문서 구성

상세 내용

본문

인증

Security boundary (important)

Request body

Policy + routing behavior

Responses

예제

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드