Tools Invoke HTTP API

+15 Mana ✨
OpenClaw Tools HTTP API(DOCUMENTATION)

Introduction

Beyond chat completions, OpenClaw exposes an API for directly invoking agent tools from external applications. This lets you programmatically trigger file reads, searches, deployments, or any other tool your agent has access to — without going through a conversational interface.

Key Concepts

  • Tool Invocation Endpoint: A REST API endpoint that accepts a tool name and parameters, executes the tool, and returns the result.
  • Direct Tool Access: Skip the conversational layer and call tools directly for programmatic automation.
  • Tool Discovery: The API lists all available tools and their parameter schemas.
  • Session Context: Tool invocations can optionally run within an existing session to access session-specific state.

Real World Context

A CI/CD pipeline needs to ask the OpenClaw deployment agent to check the status of a Kubernetes cluster. Instead of sending a chat message and parsing the response, the pipeline calls the tool invocation API directly with the kubectl_status tool, getting structured JSON back that can be programmatically processed.

Deep Dive

List available tools for an agent:

bash
curl http://localhost:18789/v1/tools \
  -H "Authorization: Bearer ${OPENCLAW_API_KEY}" \
  -H "X-Agent-Id: deployer"

# Response:
# {
#   "tools": [
#     {"name": "bash", "description": "Execute shell commands", "parameters": {...}},
#     {"name": "file_read", "description": "Read a file", "parameters": {...}},
#     {"name": "deploy", "description": "Deploy to production", "parameters": {...}}
#   ]
# }

The X-Agent-Id header specifies which agent's tools to list. Each tool includes its name, description, and JSON Schema parameters.

Invoke a tool directly:

bash
curl -X POST http://localhost:18789/v1/tools/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${OPENCLAW_API_KEY}" \
  -H "X-Agent-Id: deployer" \
  -d '{
    "tool": "bash",
    "parameters": {
      "command": "kubectl get pods -n production"
    }
  }'

This sends a tool invocation request to the deployer agent, executing the kubectl command and returning the output as structured JSON. The response includes the tool output, exit code, and any errors.

Common Pitfalls

  1. Invoking tools without proper authorization — Tool invocation bypasses the conversational safety layer. Ensure the API key has appropriate permissions for the tools being called.
  2. Missing the X-Agent-Id header — Without specifying the agent, the request goes to the default agent, which may not have the required tools.

Best Practices

  1. Use tool invocation for automation, conversation for interaction — Humans should use the conversational interface; machines should use the tool API.
  2. Scope API keys per agent — Create separate API keys with permissions limited to specific agents and tools.

Summary

  • The tools invoke API lets external applications call agent tools directly
  • Tool discovery lists available tools with their parameter schemas
  • The X-Agent-Id header routes invocations to the correct agent
  • Tool invocations can run in existing sessions for state access
  • Use scoped API keys to limit which tools each client can invoke
✓ Completed