Skip to content

Commit 34b003b

Browse files
committed
docs: align SDK compatibility and version-line requirements
1 parent 87c2113 commit 34b003b

2 files changed

Lines changed: 37 additions & 31 deletions

File tree

‎README.md‎

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ Pure Java SDK — talks to the OpenClaw Gateway through independent HTTP, SSE, W
88
[简体中文](./README.zh-CN.md)
99

1010
> **Current branch**: `feature/3.0.x`
11-
> **Version**: `3.0.x.x.20260630-SNAPSHOT`
12-
> **JDK baseline**: 8
13-
> **Project status**: stable (1.0.x line). Not yet published to Maven Central; artifacts are distributed via the Aliyun Maven repository and GitHub Releases.
11+
> **Version**: `3.0.x.20260630-SNAPSHOT`
12+
> **JDK baseline**: 21
13+
> **Release notes**: [3.0.x.20260630](https://github.com/easy-4-java/openclaw-java-sdk/releases/tag/v3.0.x.20260630).
1414
1515
## Table of Contents
1616

@@ -30,7 +30,7 @@ Pure Java SDK — talks to the OpenClaw Gateway through independent HTTP, SSE, W
3030

3131
### 1.1 What it is
3232

33-
**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.
33+
**openclaw-java-sdk** is a pure Java library for Java developers to integrate with the OpenClaw Gateway over these interfaces: HTTP Chat Completions / Embeddings / Responses / Webhook / Tools invoke, a WebSocket control plane for bidirectional streaming, and the local `openclaw` CLI.
3434

3535
### 1.2 What it is not
3636

@@ -69,23 +69,26 @@ Pure Java SDK — talks to the OpenClaw Gateway through independent HTTP, SSE, W
6969

7070
| Component | Version | Notes |
7171
|---|---:|---|
72-
| JDK | 21+ | 1.0.x line baseline |
73-
| Maven | 3.0+ | Enforcer minimum |
72+
| JDK | 21+ | 3.0.x line baseline |
73+
| Maven | 4.0.0-rc-5 | Repository Maven Wrapper version |
7474
| OkHttp / okhttp-sse | 4.12.0 | HTTP + SSE transport |
75-
| Java-WebSocket | — | WebSocket transport |
76-
| Jackson databind | 2.17.x | JSON |
77-
| commons-exec | — | CLI subprocess execution |
75+
| okhttp3-extension | 2.0.x.20260630 | OkHttp |
76+
| Java-WebSocket | 1.6.0 | WebSocket transport |
77+
| `tools.jackson.core:jackson-databind` | 3.2.1 | JSON |
78+
| commons-exec | 1.6.0 | CLI subprocess execution |
7879
| SLF4J | 2.0.18 | Logging facade |
7980

81+
Live checks with Gateway 2026.7.1-2 and 2026.11.5 covered the protocol 4 WebSocket handshake, token authentication, and the `operator.read` requirement for `sessions.list`. The checks used the `gateway-client` client ID and `backend` mode. Live compatibility for HTTP, SSE, CLI, model calls and other RPCs remains unverified. [Verification record](https://github.com/easy-4-java/openclaw-java-sdk/blob/a191fa9598dbf492275da33da06d71018d6adb83/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-live-gateway.md)
82+
8083
Version-line matrix:
8184

8285
| Version line | Branch | JDK | Version pattern | Purpose |
8386
|---|---|---:|---|---|
84-
| 1.0.x | `feature/3.0.x` (this branch) | 8 | `1.0.x.*` | Legacy projects, Boot 2.x starter line |
87+
| 1.0.x | `feature/1.0.x` | 8 | `1.0.x.*` | Legacy projects, Boot 2.x starter line |
8588
| 2.0.x | `feature/2.0.x` | 17 | `2.0.x.*` | Main line (JDK 17) |
86-
| 3.0.x | `feature/3.0.x` | 21 | `3.0.x.*` | New projects |
89+
| 3.0.x | `feature/3.0.x` (this branch) | 21 | `3.0.x.*` | New projects |
8790

88-
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`.
91+
Dependency boundary: the SDK depends on OkHttp, okhttp3-extension, Jackson, Java-WebSocket, commons-exec and SLF4J. **No Spring dependency** — Spring Boot applications should use the companion `openclaw-spring-boot-starter`.
8992

9093
<a id="4-architecture--modules"></a>
9194
## 4. Architecture & Modules
@@ -132,14 +135,14 @@ Maven:
132135
<dependency>
133136
<groupId>io.github.easy4j</groupId>
134137
<artifactId>openclaw-java-sdk</artifactId>
135-
<version>3.0.x.x.20260630-SNAPSHOT</version>
138+
<version>3.0.x.20260630-SNAPSHOT</version>
136139
</dependency>
137140
```
138141

139142
Gradle:
140143

141144
```groovy
142-
implementation 'io.github.easy4j:openclaw-java-sdk:3.0.x.x.20260630-SNAPSHOT'
145+
implementation 'io.github.easy4j:openclaw-java-sdk:3.0.x.20260630-SNAPSHOT'
143146
```
144147

145148
Snapshot builds require an enabled snapshot repository (Aliyun Maven snapshot repository per `distributionManagement` in `pom.xml`).
@@ -286,9 +289,9 @@ mvn clean verify
286289

287290
| Branch | Version pattern | JDK | Maintenance policy |
288291
|---|---|---|---|
289-
| `feature/1.0.x` (this branch) | `1.0.x.*` | 8 | Compatibility fixes and JDK-8-safe dependency upgrades only |
292+
| `feature/1.0.x` | `1.0.x.*` | 8 | Compatibility fixes and JDK-8-safe dependency upgrades only |
290293
| `feature/2.0.x` | `2.0.x.*` | 17 | Main development line |
291-
| `feature/3.0.x` | `3.0.x.*` | 21 | New projects |
294+
| `feature/3.0.x` (this branch) | `3.0.x.*` | 21 | New projects |
292295

293296
<a id="11-contributing--license"></a>
294297
## 11. Contributing & License

‎README.zh-CN.md‎

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@
77
纯 Java SDK —— 通过 HTTP、SSE、WebSocket 与本地 CLI 等独立通道对接 OpenClaw Gateway
88

99
> **当前分支**:`feature/3.0.x`
10-
> **版本**:`3.0.x.x.20260630-SNAPSHOT`
10+
> **版本**:`3.0.x.20260630-SNAPSHOT`
1111
> **JDK 基线**:8
12-
> **项目状态**:稳定(1.0.x 线)。尚未发布 Maven Central;制品通过 Aliyun Maven 仓库与 GitHub Releases 分发。
12+
> **发布说明**:[3.0.x.20260630](https://github.com/easy-4-java/openclaw-java-sdk/releases/tag/v3.0.x.20260630).
1313
1414
## 目录
1515

@@ -29,7 +29,7 @@
2929

3030
### 1.1 是什么
3131

32-
**openclaw-java-sdk** 是面向 Java 开发者的纯 Java 库,通过 OpenClaw Gateway 的全部外部通信面进行对接:HTTP Chat Completions / Embeddings / Responses / Webhook / Tools Invoke、用于双向流式的 WebSocket 控制面,以及本地 `openclaw` CLI。
32+
**openclaw-java-sdk** 是面向 Java 开发者的纯 Java 库,通过以下 OpenClaw Gateway 接口进行对接:HTTP Chat Completions / Embeddings / Responses / Webhook / Tools Invoke、用于双向流式的 WebSocket 控制面,以及本地 `openclaw` CLI。
3333

3434
### 1.2 不是什么
3535

@@ -68,23 +68,26 @@
6868

6969
| 组件 | 版本 | 说明 |
7070
|---|---:|---|
71-
| JDK | 21+ | 1.0.x 线基线 |
72-
| Maven | 3.0+ | Enforcer 下限 |
71+
| JDK | 21+ | 3.0.x 线基线 |
72+
| Maven | 4.0.0-rc-5 | 仓库 Maven Wrapper 版本 |
7373
| OkHttp / okhttp-sse | 4.12.0 | HTTP 与 SSE 传输 |
74-
| Java-WebSocket | — | WebSocket 传输 |
75-
| Jackson databind | 2.17.x | JSON |
76-
| commons-exec | — | CLI 子进程执行 |
74+
| okhttp3-extension | 2.0.x.20260630 | OkHttp |
75+
| Java-WebSocket | 1.6.0 | WebSocket 传输 |
76+
| `tools.jackson.core:jackson-databind` | 3.2.1 | JSON |
77+
| commons-exec | 1.6.0 | CLI 子进程执行 |
7778
| SLF4J | 2.0.18 | 日志门面 |
7879

80+
真实 Gateway 验证覆盖 2026.7.1-2 与 2026.11.5 的 WebSocket 协议 4 握手、Token 认证和 `sessions.list` 的 `operator.read` 权限检查。验证使用 `gateway-client` 客户端标识和 `backend` 模式。HTTP、SSE、CLI、模型调用及其他 RPC 的真实 Gateway 兼容性待验证。 [验证记录](https://github.com/easy-4-java/openclaw-java-sdk/blob/a191fa9598dbf492275da33da06d71018d6adb83/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-live-gateway.md)
81+
7982
版本线矩阵:
8083

8184
| 版本线 | 分支 | JDK | 版本模式 | 用途 |
8285
|---|---|---:|---|---|
83-
| 1.0.x | `feature/3.0.x`(当前分支) | 8 | `1.0.x.*` | 存量项目、Boot 2.x Starter 线 |
86+
| 1.0.x | `feature/1.0.x` | 8 | `1.0.x.*` | 存量项目、Boot 2.x Starter 线 |
8487
| 2.0.x | `feature/2.0.x` | 17 | `2.0.x.*` | 主流线(JDK 17) |
85-
| 3.0.x | `feature/3.0.x` | 21 | `3.0.x.*` | 新项目 |
88+
| 3.0.x | `feature/3.0.x`(当前分支) | 21 | `3.0.x.*` | 新项目 |
8689

87-
依赖边界:SDK 仅依赖 OkHttp、Jackson、Java-WebSocket、commons-exec 与 SLF4J。**无 Spring 依赖**——Spring Boot 应用请使用配套的 `openclaw-spring-boot-starter`。
90+
依赖边界:SDK 依赖 OkHttp、okhttp3-extension、Jackson、Java-WebSocket、commons-exec 与 SLF4J。**无 Spring 依赖**——Spring Boot 应用请使用配套的 `openclaw-spring-boot-starter`。
8891

8992
<a id="4-architecture--modules"></a>
9093
## 4. 架构与模块
@@ -131,14 +134,14 @@ Maven:
131134
<dependency>
132135
<groupId>io.github.easy4j</groupId>
133136
<artifactId>openclaw-java-sdk</artifactId>
134-
<version>3.0.x.x.20260630-SNAPSHOT</version>
137+
<version>3.0.x.20260630-SNAPSHOT</version>
135138
</dependency>
136139
```
137140

138141
Gradle:
139142

140143
```groovy
141-
implementation 'io.github.easy4j:openclaw-java-sdk:3.0.x.x.20260630-SNAPSHOT'
144+
implementation 'io.github.easy4j:openclaw-java-sdk:3.0.x.20260630-SNAPSHOT'
142145
```
143146

144147
快照版本需要启用对应快照仓库(`pom.xml` 中 `distributionManagement` 指向 Aliyun Maven 仓库)。
@@ -285,9 +288,9 @@ mvn clean verify
285288

286289
| 分支 | 版本模式 | JDK | 维护策略 |
287290
|---|---|---|---|
288-
| `feature/1.0.x`(当前分支) | `1.0.x.*` | 8 | 仅接受兼容性修复与 JDK 8 安全的依赖升级 |
291+
| `feature/1.0.x` | `1.0.x.*` | 8 | 仅接受兼容性修复与 JDK 8 安全的依赖升级 |
289292
| `feature/2.0.x` | `2.0.x.*` | 17 | 主流开发线 |
290-
| `feature/3.0.x` | `3.0.x.*` | 21 | 新项目 |
293+
| `feature/3.0.x`(当前分支) | `3.0.x.*` | 21 | 新项目 |
291294

292295
<a id="11-contributing--license"></a>
293296
## 11. 贡献与许可证

0 commit comments

Comments
 (0)