@@ -195,6 +195,21 @@ Configuration is object-based (no Spring properties in this library). Three conf
 | `gatewayBaseUrl` | String | `http://localhost:18789` | Gateway base URL |
 | `gatewayAuthToken` | String | — | Control-plane token |
 | `gatewayAuthPassword` | String | — | Control-plane password mode |
+| `gatewayAuthBootstrapToken` | String | — | One-time device bootstrap token; requires `gatewayDeviceIdentity` |
+| `gatewayAuthDeviceToken` | String | — | Paired-device token; requires `gatewayDeviceIdentity` |
+| `gatewayApprovalRuntimeToken` | String | — | Local trusted approval-runtime token |
+| `gatewayAgentRuntimeIdentityToken` | String | — | Local backend Agent Runtime identity token |
+| `gatewayRole` | String | `operator` | WS role: `operator` or `node` |
+| `gatewayScopes` | List<String> | `operator.read/write` | WS handshake scopes; system-provenance fields require explicit `operator.admin`, and Gateway applies the final policy |
+| `gatewayClientId/displayName/version/platform/mode` | String | SDK defaults | Gateway client identity fields |
+| `gatewayClientDeviceFamily/modelIdentifier/instanceId` | String | — | Optional presence, audit, and device-signature metadata |
+| `gatewayCapabilities` | List<String> | empty | Declared Gateway capabilities |
+| `gatewayCommands` | List<String> | — | Commands exposed by a node client |
+| `gatewayPermissions` | Map<String, Boolean> | — | Host permission snapshot reported by a node client |
+| `gatewayPathEnv` | String | — | PATH snapshot reported by a node client |
+| `gatewayLocale` | String | JVM locale | Locale sent in the connect payload |
+| `gatewayUserAgent` | String | SDK version | User-Agent sent in the connect payload |
+| `gatewayDeviceIdentity` | `OpenClawGatewayDeviceIdentity` | — | Signs each server challenge dynamically with the device Ed25519 private key |
 | `hooksToken` | String | — | Webhook auth token |
 | `hooksPath` | String | `/hooks` | Webhook base path |
 | `hooksUseXOpenclawTokenHeader` | boolean | `false` | Send the hook token via `x-openclaw-token` header |
@@ -227,6 +242,8 @@ Custom request headers via `OpenClawHeaders.Builder`:
 
 Auth priority: webhook (`/hooks/*`) uses `hooksToken`; control plane (`/v1/*`, `/tools/*`, WebSocket) uses `gatewayAuthToken` → `gatewayAuthPassword` → `hooksToken` → none.
 
+Device authentication is not a static DTO-only field. When `gatewayDeviceIdentity` is configured, the SDK builds the OpenClaw v3 payload from the current challenge nonce, role, scopes, token and client metadata, then invokes `sign(payload)`. `gatewayAuthBootstrapToken` and `gatewayAuthDeviceToken` are rejected before the handshake when no device identity is configured. Runtime tokens are accepted by OpenClaw only for their trusted local backend scenarios; configuring an arbitrary value does not grant those privileges.
+
 <a id="8-core-usage"></a>
 ## 8. Core Usage
 
@@ -263,6 +280,23 @@ client.chatSend("Hello", new ChatStreamHandler() {
 });
 ```
 
+Use native `ChatSendParams` when a turn must override OpenClaw execution parameters:
+
+```java
+client.ws().chatSend(ChatSendParams.builder()
+        .sessionKey("agent:ops:conversation-42")
+        .agentId("ops")
+        .message("Analyze this turn")
+        .thinkingLevel(ThinkingLevel.MINIMAL)
+        .fastMode("auto")
+        .fastAutoOnSeconds(10)
+        .suppressCommandInterpretation(true)
+        .idempotencyKey("turn-42")
+        .build(), handler);
+```
+
+`ChatSendParams` matches the complete OpenClaw `2026.7.1-2` `chat.send` schema: session/agent selection, per-turn thinking, `fastMode`, auto-fast cutoff, delivery origin, attachments, timeout, system provenance, command-interpretation suppression, routing contract and idempotency. HTTP Chat Completions continues to emit only the OpenAI fields OpenClaw explicitly supports. `ResponseRequest` separately models the accepted-but-currently-ignored compatibility fields `max_tool_calls`, `reasoning`, `metadata`, `store`, and `truncation`.
+
 ### 8.3 Local CLI
 
 ```java
 
@@ -194,6 +194,21 @@ client.close();
 | `gatewayBaseUrl` | String | `http://localhost:18789` | Gateway 根地址 |
 | `gatewayAuthToken` | String | — | 控制面令牌 |
 | `gatewayAuthPassword` | String | — | 控制面密码模式 |
+| `gatewayAuthBootstrapToken` | String | — | 一次性设备引导令牌；必须配置 `gatewayDeviceIdentity` |
+| `gatewayAuthDeviceToken` | String | — | 已配对设备令牌；必须配置 `gatewayDeviceIdentity` |
+| `gatewayApprovalRuntimeToken` | String | — | 本地受信任审批运行时令牌 |
+| `gatewayAgentRuntimeIdentityToken` | String | — | 本地 backend Agent Runtime 身份令牌 |
+| `gatewayRole` | String | `operator` | WS 连接角色：`operator` 或 `node` |
+| `gatewayScopes` | List<String> | `operator.read/write` | WS 握手请求权限；系统来源字段需显式加入 `operator.admin`，最终权限由 Gateway 策略裁剪 |
+| `gatewayClientId/displayName/version/platform/mode` | String | SDK 默认值 | Gateway 客户端身份字段 |
+| `gatewayClientDeviceFamily/modelIdentifier/instanceId` | String | — | 可选 presence、审计和设备签名元数据 |
+| `gatewayCapabilities` | List<String> | 空列表 | 客户端声明的 Gateway 能力 |
+| `gatewayCommands` | List<String> | — | node 客户端向 Gateway 暴露的命令 |
+| `gatewayPermissions` | Map<String, Boolean> | — | node 客户端上报的宿主权限快照 |
+| `gatewayPathEnv` | String | — | node 客户端上报的 PATH 快照 |
+| `gatewayLocale` | String | JVM 默认区域 | connect 握手上报的区域设置 |
+| `gatewayUserAgent` | String | SDK 版本 | connect 握手上报的 User-Agent |
+| `gatewayDeviceIdentity` | `OpenClawGatewayDeviceIdentity` | — | 使用设备 Ed25519 私钥为每次服务端 challenge 动态签名 |
 | `hooksToken` | String | — | Webhook 鉴权令牌 |
 | `hooksPath` | String | `/hooks` | Webhook 基础路径 |
 | `hooksUseXOpenclawTokenHeader` | boolean | `false` | 用 `x-openclaw-token` 头传 Hook 令牌 |
@@ -226,6 +241,8 @@ client.close();
 
 认证优先级：Webhook（`/hooks/*`）使用 `hooksToken`；控制面（`/v1/*`、`/tools/*`、WebSocket）为 `gatewayAuthToken` → `gatewayAuthPassword` → `hooksToken` → 空。
 
+设备认证不是只做 DTO 字段映射。配置 `gatewayDeviceIdentity` 后，SDK 会使用本次 challenge 的 nonce、角色、权限范围、认证令牌和客户端元数据构造 OpenClaw v3 载荷，再调用 `sign(payload)`。配置 `gatewayAuthBootstrapToken` 或 `gatewayAuthDeviceToken` 却没有设备身份时，SDK 会在握手前拒绝请求。运行时令牌只在 OpenClaw 定义的本地受信任 backend 场景中生效，任意填写字符串不会获得对应权限。
+
 <a id="8-core-usage"></a>
 ## 8. 核心用法
 
@@ -261,6 +278,23 @@ client.chatSend("你好", new ChatStreamHandler() {
 });
 ```
 
+需要逐轮覆盖 OpenClaw 执行参数时，使用原生 `ChatSendParams`：
+
+```java
+client.ws().chatSend(ChatSendParams.builder()
+        .sessionKey("agent:ops:conversation-42")
+        .agentId("ops")
+        .message("分析这一轮问题")
+        .thinkingLevel(ThinkingLevel.MINIMAL)
+        .fastMode("auto")
+        .fastAutoOnSeconds(10)
+        .suppressCommandInterpretation(true)
+        .idempotencyKey("turn-42")
+        .build(), handler);
+```
+
+`ChatSendParams` 对齐 OpenClaw `2026.7.1-2` 的完整 `chat.send` Schema，包括会话/Agent、逐轮 thinking、`fastMode`、自动快速窗口、投递来源、附件、超时、系统来源证明、指令解释抑制、路由契约与幂等键。HTTP Chat Completions 继续只发送 OpenClaw 明确支持的 OpenAI 参数；`ResponseRequest` 另行建模了 OpenClaw 接受但当前忽略的 `max_tool_calls`、`reasoning`、`metadata`、`store`、`truncation`，便于兼容上层客户端。
+
 ### 8.3 本地 CLI
 
 ```java
 
@@ -472,6 +472,7 @@
         <junit-jupiter.version>5.11.4</junit-jupiter.version>
         <lombok.version>1.18.46</lombok.version>
         <okhttp3.version>4.12.0</okhttp3.version>
+        <okhttp3-extension.version>1.0.x.20260730</okhttp3-extension.version>
         <slf4j.version>2.0.18</slf4j.version>
         <!-- Maven Plugin versions -->
         <maven-central-publishing-plugin.version>0.11.0</maven-central-publishing-plugin.version>
@@ -495,6 +496,11 @@
     <!-- 依赖版本统一管理（dependencyManagement） -->
     <dependencyManagement>
         <dependencies>
+            <dependency>
+                <groupId>io.github.easy4j</groupId>
+                <artifactId>okhttp3-extension</artifactId>
+                <version>${okhttp3-extension.version}</version>
+            </dependency>
             <!-- For OkHttp -->
             <dependency>
                 <groupId>com.squareup.okhttp3</groupId>
@@ -565,6 +571,10 @@
 
     <!-- 项目依赖（dependencies） -->
     <dependencies>
+        <dependency>
+            <groupId>io.github.easy4j</groupId>
+            <artifactId>okhttp3-extension</artifactId>
+        </dependency>
         <!-- For OkHttp -->
         <dependency>
             <groupId>com.squareup.okhttp3</groupId>
 
@@ -1,20 +1,21 @@
 package io.github.easy4j.openclaw;
 
 import lombok.Data;
+import okhttp3.extension.logging.HttpLogLevel;
 
 /**
  * OpenClaw SDK 统一调试配置，用于控制生命周期、请求头和正文日志。
  *
  * <p>调试默认关闭。正文日志始终受长度限制，认证头和敏感令牌仍由客户端脱敏。</p>
  *
- * <p>{@link #level} 字段使用字符串表示日志级别。可选值：
+ * <p>{@link #level} 使用 {@link HttpLogLevel} 表示日志级别。可选值：
  * <ul>
  *     <li>{@code "NONE"} — 不输出</li>
  *     <li>{@code "BASIC"} — 仅方法/路径/状态/耗时</li>
  *     <li>{@code "HEADERS"} — BASIC + 请求/响应头</li>
  *     <li>{@code "BODY"} — HEADERS + 请求/响应正文（受 {@link #maxContentLength} 限制）</li>
  * </ul>
- * 当 classpath 上有 {@code io.github.easy4j:okhttp3-extension} 时，{@link #level} 会按相同语义传递给底层日志拦截器；否则仅用于 SDK 自身 DEBUG 输出。</p>
+ * 该类型继续作为 SDK 的公共 API，避免升级 SDK 后破坏既有调用方的源码和二进制兼容性。</p>
  *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  * @since 1.0.0
@@ -25,26 +26,47 @@ public class OpenClawDebugConfig {
     /** 是否允许 SDK 输出调试诊断信息。 */
     private boolean enabled;
 
-    /**
-     * 启用调试后的详细程度；字符串常量，对齐 {@code okhttp3.extension.logging.HttpLogLevel}。
-     */
-    private String level = "BASIC";
+    /** 启用调试后的详细程度。 */
+    private HttpLogLevel level = HttpLogLevel.BASIC;
 
     /** BODY 级别单项正文允许记录的最大字符数。 */
     private int maxContentLength = 2_000;
 
     /**
      * 判断指定级别的日志是否允许输出。
-     * <p>简单的字符串排序：{@code NONE &lt; BASIC &lt; HEADERS &lt; BODY}。</p>
+     * @param required 待输出信息要求的最低级别
+     * @return 调试已启用且当前级别满足要求时返回 {@code true}
+     */
+    public boolean allows(HttpLogLevel required) {
+        return enabled && level != null && required != null && level.allows(required);
+    }
+
+    /**
+     * 兼容短期使用字符串级别的调用方。
      *
-     * @param required 待输出信息要求的最低级别（字符串）
+     * @param required 待输出信息要求的最低级别名称
      * @return 调试已启用且当前级别满足要求时返回 {@code true}
      */
     public boolean allows(String required) {
-        if (!enabled || level == null || required == null) {
-            return false;
-        }
-        return rank(level) >= rank(required);
+        return required != null && allows(resolveLevel(required));
+    }
+
+    /**
+     * 设置日志级别，保持旧版 SDK 公共 API 的源码与二进制兼容性。
+     *
+     * @param level 日志级别
+     */
+    public void setLevel(HttpLogLevel level) {
+        this.level = level;
+    }
+
+    /**
+     * 兼容 Spring 配置及短期使用字符串级别的调用方。
+     *
+     * @param level 日志级别名称
+     */
+    public void setLevel(String level) {
+        this.level = resolveLevel(level);
     }
 
     /**
@@ -56,13 +78,14 @@ public int resolveMaxContentLength() {
         return Math.max(1, maxContentLength);
     }
 
-    private static int rank(String level) {
-        switch (level.toUpperCase()) {
-            case "BODY":    return 3;
-            case "HEADERS": return 2;
-            case "BASIC":   return 1;
-            case "NONE":    return 0;
-            default:        return 1;
+    private static HttpLogLevel resolveLevel(String level) {
+        if (level == null) {
+            return HttpLogLevel.BASIC;
+        }
+        try {
+            return HttpLogLevel.valueOf(level.trim().toUpperCase());
+        } catch (IllegalArgumentException ex) {
+            return HttpLogLevel.BASIC;
         }
     }
-}
+}
@@ -1,8 +1,14 @@
 package io.github.easy4j.openclaw;
 
 import io.github.easy4j.openclaw.util.OpenClawStrings;
+import io.github.easy4j.openclaw.ws.OpenClawGatewayDeviceIdentity;
 import lombok.Data;
+import lombok.ToString;
 
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 
 /**
@@ -61,13 +67,95 @@ public OpenClawHttpClientConfig(OpenClawDebugConfig debug) {
     /**
      * Gateway Bearer 认证令牌；解析认证头时优先于密码且日志必须脱敏。
      */
+    @ToString.Exclude
     private String gatewayAuthToken;
 
     /**
      * Gateway 密码认证值；仅在未配置 token 时使用且日志必须脱敏。
      */
+    @ToString.Exclude
     private String gatewayAuthPassword;
 
+    /**
+     * 设备首次受控接入使用的一次性引导令牌；必须配合 {@link #gatewayDeviceIdentity} 使用。
+     */
+    @ToString.Exclude
+    private String gatewayAuthBootstrapToken;
+
+    /**
+     * 已配对设备的认证令牌；必须配合 {@link #gatewayDeviceIdentity} 使用。
+     */
+    @ToString.Exclude
+    private String gatewayAuthDeviceToken;
+
+    /**
+     * 本地审批运行时令牌，仅用于受信任的 backend gateway-client 和审批权限范围。
+     */
+    @ToString.Exclude
+    private String gatewayApprovalRuntimeToken;
+
+    /**
+     * 本地 Agent Runtime 身份令牌，仅允许受信任的 backend gateway-client 使用。
+     */
+    @ToString.Exclude
+    private String gatewayAgentRuntimeIdentityToken;
+
+    /** Gateway connect 握手角色；OpenClaw 当前支持 {@code operator} 和 {@code node}。 */
+    private String gatewayRole = "operator";
+
+    /**
+     * WebSocket connect 握手请求的操作权限范围；Gateway 最终仍会按认证身份和服务端策略裁剪。
+     */
+    private List<String> gatewayScopes = Arrays.asList("operator.read", "operator.write");
+
+    /** Gateway 协议识别的客户端 ID。 */
+    private String gatewayClientId = "gateway-client";
+
+    /** Gateway presence 和审计记录中展示的客户端名称。 */
+    private String gatewayClientDisplayName = "OpenClaw Java SDK";
+
+    /** Gateway presence 和兼容性判断使用的客户端版本。 */
+    private String gatewayClientVersion = "1.0.0";
+
+    /** Gateway 记录和设备签名使用的客户端平台。 */
+    private String gatewayClientPlatform = "java";
+
+    /** Gateway 客户端运行模式。 */
+    private String gatewayClientMode = "backend";
+
+    /** 可选设备家族，会参与 v3 设备认证签名。 */
+    private String gatewayClientDeviceFamily;
+
+    /** 可选设备型号标识，用于客户端 presence 元数据。 */
+    private String gatewayClientModelIdentifier;
+
+    /** 可选客户端实例标识，用于区分同一程序的不同运行实例。 */
+    private String gatewayClientInstanceId;
+
+    /** 客户端声明的 Gateway 能力列表。 */
+    private List<String> gatewayCapabilities = Collections.emptyList();
+
+    /** node 类客户端可由 Gateway 调用的命令列表。 */
+    private List<String> gatewayCommands;
+
+    /** 客户端上报的宿主权限快照。 */
+    private Map<String, Boolean> gatewayPermissions;
+
+    /** node 类客户端执行命令时使用的 PATH 环境快照。 */
+    private String gatewayPathEnv;
+
+    /** connect 握手上报的区域设置；为空时使用 JVM 默认区域。 */
+    private String gatewayLocale;
+
+    /** connect 握手上报的 User-Agent；为空时使用 SDK 默认值。 */
+    private String gatewayUserAgent;
+
+    /**
+     * 可选 Gateway 设备身份签名器；配置后 SDK 会针对每次 challenge 动态生成签名。
+     */
+    @ToString.Exclude
+    private OpenClawGatewayDeviceIdentity gatewayDeviceIdentity;
+
     /**
      * HTTPS/WSS 是否校验证书和主机名；生产环境应保持开启。
      */
 
@@ -84,6 +84,11 @@ public CompletableFuture<ResponseResult> createResponseAsync(ResponseRequest req
                 .topP(request.getTopP())
                 .user(request.getUser())
                 .previousResponseId(request.getPreviousResponseId())
+                .maxToolCalls(request.getMaxToolCalls())
+                .reasoning(request.getReasoning())
+                .metadata(request.getMetadata())
+                .store(request.getStore())
+                .truncation(request.getTruncation())
                 .build();
 
         return postJsonAsync(OpenClawConstants.ENDPOINT_RESPONSES, normalized, headers, null)