No history yet

JSON-RPC 2.0 Internal Mechanics

Dissecting the Transport Layer

OpenClaw’s architecture decouples its reasoning engine from its client interfaces using a robust transport layer built on JSON-RPC 2.0. This isn’t a generic implementation. It's tailored for asynchronous, stateful communication that allows multiple clients, from a terminal to a custom web UI, to interact with a single agent instance cohesively. All communication between the OpenClaw App Server and its clients occurs over this protocol, typically via WebSockets or stdio streams.

At its core, MCP is just JSON-RPC 2.0 over newline-delimited streams.

Understanding this communication backbone is critical for advanced development, such as creating custom interfaces or intercepting commands for logging and analysis. Let's examine the fundamental request object. Every action a client wants the agent to take is formulated as a JSON-RPC request.

{
  "jsonrpc": "2.0",
  "method": "agent.run_task",
  "params": {
    "task_description": "Summarize the latest emails from 'Project Phoenix'.",
    "priority": "high"
  },
  "id": "client--a-1672531200"
}

The method string follows a namespace.action convention, like agent.run_task or skills.list. The params object contains the payload, which is specific to the method being called. The most crucial field for multi-client synchronization is id. OpenClaw clients are expected to generate a unique id that prefixes a client identifier. This allows the App Server to route responses and notifications correctly, and for clients to map incoming messages to their originating requests.

Requests, Responses, and Notifications

For every request with an id, the server must return a response object. A successful response mirrors the request's id and includes a result object. An error response, conversely, contains an error object.

// Success Response
{
  "jsonrpc": "2.0",
  "result": {
    "task_id": "task-98765",
    "status": "queued"
  },
  "id": "client-a-1672531200"
}

// Error Response
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params: 'priority' must be 'low', 'medium', or 'high'.",
    "data": {
      "invalid_field": "priority",
      "allowed_values": ["low", "medium", "high"]
    }
  },
  "id": "client-a-1672531200"
}

OpenClaw extends the standard JSON-RPC error codes. While it uses standard codes like -32602 for Invalid Params, it also introduces custom codes in the application-specific range (e.g., -32000 to -32099) for agent-specific failures like SKILL_NOT_FOUND or PERMISSION_DENIED. The data field in an error object is heavily utilized to provide rich contextual information for debugging.

The real power of the architecture comes from notifications. These are request objects without an id field. The server sends them to clients to provide unsolicited updates, such as the progress of a long-running task. Because they lack an id, clients do not send a response. This is the mechanism for achieving asynchronous communication without polling.

This diagram shows a typical lifecycle. The client initiates an action, gets an immediate acknowledgment, and then receives progress updates via server-pushed notifications. This is far more efficient than the client repeatedly asking, "Are you done yet?"

Payload Interception and Batching

For performance-sensitive applications, you can batch multiple requests into a single HTTP call. The server processes each request in the array and returns an array of response objects. The order of responses is not guaranteed to match the order of requests, so relying on the id field is essential. This reduces network overhead significantly when issuing many commands at once.

// Batch Request
[
  {
    "jsonrpc": "2.0", 
    "method": "skills.enable", 
    "params": ["email"], 
    "id": "batch-req-1"
  },
  {
    "jsonrpc": "2.0", 
    "method": "skills.list", 
    "id": "batch-req-2"
  }
]

The most powerful technique for 'digital alchemy' is raw payload interception. By creating a proxy between the client and the OpenClaw server, you can inspect, log, or even modify [{] calls in flight. For example, you could build a custom UI that visualizes the agent's internal state by listening for specific notifications. Or, you could inject additional parameters into a request to alter a skill's behavior without modifying the skill's source code.

This is achieved by setting up a local WebSocket or HTTP server that mimics the OpenClaw endpoint. Your custom client connects to this proxy, which forwards requests to the real server, then intercepts the responses and notifications before passing them back to the client. This [{] approach offers ultimate flexibility for building specialized tools and interfaces on top of the core OpenClaw agent.

Now that you understand the mechanics, let's test your knowledge.

Quiz Questions 1/5

What is the primary role of the JSON-RPC 2.0 transport layer in OpenClaw's architecture?

Quiz Questions 2/5

How does the OpenClaw server provide clients with asynchronous updates, such as the progress of a long-running task, without the client needing to poll for status?