English | 简体中文

Pure Java SDK — talks to the OpenClaw Gateway through independent HTTP, SSE, WebSocket and local CLI channels 简体中文

Current branch: feature/2.0.x Version: 2.0.x.x.20260630-SNAPSHOT JDK baseline: 8 Project status: stable (1.0.x line). Not yet published to Maven Central; artifacts are distributed via the Aliyun Maven repository and GitHub Releases.

• 1. Project Overview
• 2. Features & Status
• 3. Requirements & Compatibility
• 4. Architecture & Modules
• 5. Installation
• 6. Quick Start
• 7. Configuration
• 8. Core Usage
• 9. Testing & Build
• 10. Versioning & Branches
• 11. Contributing & License

openclaw-java-sdk is a pure Java library for Java developers to integrate with the OpenClaw Gateway over all of its external communication surfaces: HTTP Chat Completions / Embeddings / Responses / Webhook / Tools invoke, a WebSocket control plane for bidirectional streaming, and the local openclaw CLI.

• Not the OpenClaw Gateway itself, and not an LLM inference engine.
• No Spring, Servlet or ORM dependencies.
• No promises about JDK/framework combinations that are not part of the compatibility matrix.

Version-line matrix:

Dependency boundary: the SDK depends only on OkHttp, Jackson, Java-WebSocket, commons-exec and SLF4J. No Spring dependency — Spring Boot applications should use the companion openclaw-spring-boot-starter.

[ Business Application ]
        |
        | openclaw-java-sdk
        v
+------------------------------------------+
| OpenClawClient (facade)                   |
|  HTTP   /v1/chat/completions, /v1/models  |
|         /v1/embeddings, /v1/responses,    |
|         /tools/invoke, /hooks/*           |
|  SSE    StreamingChatResponse             |
|  WS     connect / chatSend / sessionsSend |
|  CLI    local `openclaw` subprocess       |
+------------------------------------------+
        |
        v
[ OpenClaw Gateway ] -> [ LLM / Agents / Tools ]

Package layout:

Maven:

<dependency>
    <groupId>io.github.easy4j</groupId>
    <artifactId>openclaw-java-sdk</artifactId>
    <version>2.0.x.x.20260630-SNAPSHOT</version>
</dependency>

Gradle:

implementation 'io.github.easy4j:openclaw-java-sdk:2.0.x.x.20260630-SNAPSHOT'

Snapshot builds require an enabled snapshot repository (Aliyun Maven snapshot repository per distributionManagement in pom.xml).

import io.github.easy4j.openclaw.OpenClawClient;
import io.github.easy4j.openclaw.OpenClawClientConfig;
import io.github.easy4j.openclaw.api.model.ChatMessage;
import io.github.easy4j.openclaw.api.model.ChatResponse;
import java.util.List;

// 1. Configure
OpenClawClientConfig config = new OpenClawClientConfig();
config.getHttp().setGatewayBaseUrl("http://localhost:18789");
config.getHttp().setGatewayAuthToken("your-gateway-token");

// 2. Create the client (constructor runs the startup self-check)
OpenClawClient client = new OpenClawClient(config);

// 3. Chat
ChatResponse resp = client.chatCompletion(
        "openclaw/default", "gpt-4o",
        List.of(ChatMessage.ofUser("Hello")));
System.out.println(resp.getChoices().get(0).getMessage().getContent());

// 4. Release
client.close();

Expected result: with the default config the HTTP subsystem is enabled but startupCheckEnabled is false, so no blocking probe runs at startup; the call returns the agent's reply text. When startup checks are enabled, INFO logs OpenClaw HTTP health check passed: ... / OpenClaw CLI ready: ... appear, and a failing probe either throws IllegalStateException (fail-fast) or logs a WARN (non-fail-fast).

Configuration is object-based (no Spring properties in this library). Three config classes:

OpenClawHttpClientConfig properties:

OpenClawCliConfig properties:

Custom request headers via OpenClawHeaders.Builder:

Auth priority: webhook (/hooks/*) uses hooksToken; control plane (/v1/*, /tools/*, WebSocket) uses gatewayAuthToken → gatewayAuthPassword → hooksToken → none.

ChatRequest req = ChatRequest.builder()
        .agent("openclaw/default")
        .messages(List.of(ChatMessage.ofUser("What's the weather in Beijing?")))
        .tools(List.of(Tools.function("get_weather", "Get weather")
                .param("city", "string", "City name", true).build()))
        .toolChoice("auto")
        .build();

client.chatCompletionStream(req)
        .onDelta(delta -> System.out.print(delta))
        .onToolCall(toolCalls -> toolCalls.forEach(
                tc -> System.out.println(tc.getFunction().getName())))
        .onComplete(text -> System.out.println("\n[done]"))
        .onError(Throwable::printStackTrace);

HelloOk hello = client.connect();
client.chatSend("Hello", new ChatStreamHandler() {
    @Override public void onDelta(String text) { System.out.print(text); }
    @Override public void onComplete(String fullText) { System.out.println(); }
    @Override public void onError(String error) { System.err.println(error); }
});

OpenClawCliResult result = client.cli().version();        // openclaw --version
System.out.println(result.getStdout());

client.cli().gatewayHealth(                                // openclaw gateway health
        GatewayRpcOptions.builder().url("ws://127.0.0.1:18789").build());

mvn clean verify

• Unit tests cover config defaults, CLI args/execution, WS protocol, HTTP sub-clients and constructor contracts (23 test sources: 22 test classes + 1 mock CLI helper under src/test).
• JaCoCo runs prepare-agent, report and check on the verify phase with a 90% line-coverage rule (haltOnFailure=false).
• Release packaging (mvn -Prelease deploy) attaches sources and javadoc jars, GPG-signs artifacts and is wired for Sonatype Central Publishing; plain mvn deploy routes SNAPSHOT/release artifacts to the Aliyun Maven repository per distributionManagement.

Run mvn clean verify before opening a pull request and describe compatibility, testing, documentation and migration impact. This project is licensed under the Apache License 2.0.