feat: unify tiered diagnostic logging

Author: loong10k

pom.xml

@@ -471,6 +471,7 @@
         <junit.version>5.11.4</junit.version>
         <lombok.version>1.18.46</lombok.version>
         <okhttp3.version>4.12.0</okhttp3.version>
+        <okhttp3-extension.version>1.0.x.20260630-SNAPSHOT</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>
@@ -493,6 +494,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>
@@ -553,6 +559,10 @@
 
     <!-- 项目依赖（dependencies） -->
     <dependencies>
+        <dependency>
+            <groupId>io.github.easy4j</groupId>
+            <artifactId>okhttp3-extension</artifactId>
+        </dependency>
         <!-- For OkHttp -->
         <dependency>
             <groupId>com.squareup.okhttp3</groupId>

src/main/java/io/github/easy4j/openclaw/OpenClawCliConfig.java

@@ -2,6 +2,8 @@
 
 import lombok.Data;
 
+import java.util.Objects;
+
 /**
  * 本地 CLI 通道配置，定义可执行文件、工作目录、启动探测、命令超时和最大并发子进程数。
  *
@@ -11,6 +13,23 @@
 @Data
 public class OpenClawCliConfig {
 
+    /** CLI 与 HTTP/SSE 通道共享的调试策略。 */
+    private final OpenClawDebugConfig debug;
+
+    /** 使用独立的默认调试策略创建配置。 */
+    public OpenClawCliConfig() {
+        this(new OpenClawDebugConfig());
+    }
+
+    /**
+     * 使用指定调试策略创建配置。
+     *
+     * @param debug 客户端共享调试策略
+     */
+    public OpenClawCliConfig(OpenClawDebugConfig debug) {
+        this.debug = Objects.requireNonNull(debug, "debug");
+    }
+
     /**
      * 是否创建并开放对应通信通道；关闭后门面不会初始化该子系统。
      */

src/main/java/io/github/easy4j/openclaw/OpenClawClientConfig.java

@@ -11,14 +11,17 @@
 @Data
 public class OpenClawClientConfig {
 
+    /** 客户端所有通信通道共享的调试配置。 */
+    private final OpenClawDebugConfig debug = new OpenClawDebugConfig();
+
     /**
      * HTTP、SSE 和 WebSocket 通道共享的配置对象。
      */
-    private final OpenClawHttpClientConfig http = new OpenClawHttpClientConfig();
+    private final OpenClawHttpClientConfig http = new OpenClawHttpClientConfig(debug);
 
     /**
      * 本地 CLI 通道配置对象。
      */
-    private final OpenClawCliConfig cli = new OpenClawCliConfig();
+    private final OpenClawCliConfig cli = new OpenClawCliConfig(debug);
 
 }

src/main/java/io/github/easy4j/openclaw/OpenClawDebugConfig.java

@@ -0,0 +1,44 @@
+package io.github.easy4j.openclaw;
+
+import lombok.Data;
+import okhttp3.extension.logging.HttpLogLevel;
+
+/**
+ * OpenClaw SDK 统一调试配置，用于控制生命周期、请求头和正文日志。
+ *
+ * <p>调试默认关闭。正文日志始终受长度限制，认证头和敏感令牌仍由客户端脱敏。</p>
+ *
+ * @author <a href="https://github.com/loong10k">Loong Wan</a>
+ * @since 1.0.0
+ */
+@Data
+public class OpenClawDebugConfig {
+
+    /** 是否允许 SDK 输出调试诊断信息。 */
+    private boolean enabled;
+
+    /** 启用调试后的详细程度。 */
+    private HttpLogLevel level = HttpLogLevel.BASIC;
+
+    /** BODY 级别单项正文允许记录的最大字符数。 */
+    private int maxContentLength = 2_000;
+
+    /**
+     * 判断指定级别的日志是否允许输出。
+     *
+     * @param required 待输出信息要求的最低级别
+     * @return 调试已启用且当前级别满足要求时返回 {@code true}
+     */
+    public boolean allows(HttpLogLevel required) {
+        return enabled && level != null && level.allows(required);
+    }
+
+    /**
+     * 返回经过下限保护的正文日志长度。
+     *
+     * @return 至少为 1 的最大正文字符数
+     */
+    public int resolveMaxContentLength() {
+        return Math.max(1, maxContentLength);
+    }
+}

src/main/java/io/github/easy4j/openclaw/OpenClawHttpClientConfig.java

@@ -3,6 +3,8 @@
 import io.github.easy4j.openclaw.util.OpenClawStrings;
 import lombok.Data;
 
+import java.util.Objects;
+
 /**
  * HTTP、SSE 与 WebSocket 通道配置，定义 Gateway 地址、认证优先级、连接池、并发、超时、重试和日志开关。
  *
@@ -12,6 +14,25 @@
 @Data
 public class OpenClawHttpClientConfig {
 
+    /** HTTP、SSE 与 WebSocket 通道共享的调试配置。 */
+    private final OpenClawDebugConfig debug;
+
+    /**
+     * 使用默认关闭的调试配置创建 HTTP 配置。
+     */
+    public OpenClawHttpClientConfig() {
+        this(new OpenClawDebugConfig());
+    }
+
+    /**
+     * 使用客户端级共享调试配置创建 HTTP 配置。
+     *
+     * @param debug 客户端级调试配置
+     */
+    public OpenClawHttpClientConfig(OpenClawDebugConfig debug) {
+        this.debug = Objects.requireNonNull(debug, "debug");
+    }
+
     /**
      * 同步、流式或自动选择的 HTTP 响应消费模式。
      */
@@ -117,16 +138,6 @@ public class OpenClawHttpClientConfig {
      */
     private boolean retryOnConnectionFailure = true;
 
-    /**
-     * 是否输出脱敏后的请求头和截断响应体；默认关闭以控制日志量和泄露风险。
-     */
-    private boolean detailedLoggingEnabled = false;
-
-    /**
-     * 详细日志中响应体允许记录的最大字符数，超出部分截断。
-     */
-    private int maxLoggedBodyLength = 2_000;
-
     /**
      * Webhook 端点的基础路径，具体 Hook 名称在其后追加。
      */

src/main/java/io/github/easy4j/openclaw/api/OpenClawChatClient.java

@@ -9,6 +9,7 @@
 import io.github.easy4j.openclaw.api.sse.StreamingChatResponse;
 import lombok.extern.slf4j.Slf4j;
 import okhttp3.OkHttpClient;
+import okhttp3.extension.logging.HttpLogLevel;
 
 import java.net.URLEncoder;
 import java.util.HashMap;
@@ -137,7 +138,7 @@ public CompletableFuture<ChatResponse> chatCompletionAsync(ChatRequest request,
         String bodyModel = resolveModel(request);
 
         debug("Resolved body model (agent routing): {}", bodyModel);
-        debug("Headers to send: {}", headers);
+        debug(HttpLogLevel.HEADERS, "Headers to send: {}", headers);
 
         ChatRequest normalized = ChatRequest.builder()
                 .model(bodyModel)

src/main/java/io/github/easy4j/openclaw/api/OpenClawEmbeddingsClient.java

@@ -7,6 +7,7 @@
 import io.github.easy4j.openclaw.api.model.EmbeddingsResponse;
 import lombok.extern.slf4j.Slf4j;
 import okhttp3.OkHttpClient;
+import okhttp3.extension.logging.HttpLogLevel;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -61,7 +62,7 @@ public CompletableFuture<EmbeddingsResponse> createEmbeddingsAsync(EmbeddingsReq
         debug("=== Embeddings Request ===");
         debug("agent: {}", request.getAgent());
         debug("model: {}", request.getModel());
-        debug("input: {}", request.getInput());
+        debug(HttpLogLevel.BODY, "input: {}", request.getInput());
 
         // 验证请求
         validateRequest(request);

src/main/java/io/github/easy4j/openclaw/api/OpenClawHttpClient.java

@@ -10,6 +10,7 @@
 import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;
 import okhttp3.*;
+import okhttp3.extension.logging.HttpLogLevel;
 
 import java.io.IOException;
 import java.util.Map;
@@ -82,11 +83,11 @@ private OpenClawHttpClient(OpenClawHttpClientConfig config, ObjectMapper objectM
         this.objectMapper = objectMapper != null ? objectMapper : createObjectMapper();
         this.httpClient = Objects.requireNonNull(httpClient, "httpClient");
         this.ownsHttpClient = ownsHttpClient;
-        debug("OpenClaw HTTP client initialized: baseUrl={}, connectTimeoutMs={}, readTimeoutMs={}, "
-                        + "callTimeoutMs={}, retryOnConnectionFailure={}, detailedLoggingEnabled={}",
+        debug(HttpLogLevel.BASIC, "OpenClaw HTTP client initialized: baseUrl={}, connectTimeoutMs={}, readTimeoutMs={}, "
+                        + "callTimeoutMs={}, retryOnConnectionFailure={}, debugLevel={}",
                 config.getBaseUrl(), config.getConnectTimeoutMillis(), config.getReadTimeoutMillis(),
                 config.getCallTimeoutMillis(), config.isRetryOnConnectionFailure(),
-                config.isDetailedLoggingEnabled());
+                config.getDebug().getLevel());
     }
 
     /**
@@ -138,9 +139,7 @@ protected Request.Builder authedBuilder(String url, Map<String, String> headers)
             headers.forEach((k, v) -> {
                 if (k != null && v != null) {
                     builder.header(k, v);
-                    if (config.isDetailedLoggingEnabled()) {
-                        debug("Added header: {}={}", k, redactHeader(k, v));
-                    }
+                    debug(HttpLogLevel.HEADERS, "Added header: {}={}", k, redactHeader(k, v));
                 }
             });
         }
@@ -201,9 +200,7 @@ protected CompletableFuture<String> postJsonAsync(String path, Object body, Map<
 
         try {
             String json = objectMapper.writeValueAsString(body);
-            if (config.isDetailedLoggingEnabled()) {
-                debug("Request body: {}", truncate(json));
-            }
+            debug(HttpLogLevel.BODY, "Request body: {}", truncate(json));
 
             Request request = authedBuilder(url, headers)
                     .post(RequestBody.create(json, JSON))
@@ -284,10 +281,10 @@ protected CompletableFuture<String> executeAsync(Request request, String url,
                                                      HttpCallCancellation cancellation) {
         long requestId = REQUEST_SEQUENCE.incrementAndGet();
         long startedAt = System.nanoTime();
-        debug("HTTP request started: requestId={}, method={}, url={}", requestId, request.method(), request.url());
-        if (config.isDetailedLoggingEnabled()) {
-            debug("HTTP request details: requestId={}, headers={}", requestId, redactHeaders(request.headers()));
-        }
+        debug(HttpLogLevel.BASIC, "HTTP request started: requestId={}, method={}, url={}",
+                requestId, request.method(), request.url());
+        debug(HttpLogLevel.HEADERS, "HTTP request headers: requestId={}, headers={}",
+                requestId, redactHeaders(request.headers()));
 
         // 传输层只读取状态码和响应体；此处统一把非 2xx 响应转换为携带诊断信息的 SDK 异常。
         CompletableFuture<String> result = executeResponseAsync(request, cancellation).thenApply(response -> {
@@ -303,11 +300,9 @@ protected CompletableFuture<String> executeAsync(Request request, String url,
                         requestId, request.method(), request.url(), elapsedMillis(startedAt), unwrap(error).getMessage());
                 return;
             }
-            debug("HTTP request completed: requestId={}, method={}, url={}, bodyLength={}, elapsedMs={}",
+            debug(HttpLogLevel.BASIC, "HTTP request completed: requestId={}, method={}, url={}, bodyLength={}, elapsedMs={}",
                     requestId, request.method(), request.url(), respBody.length(), elapsedMillis(startedAt));
-            if (config.isDetailedLoggingEnabled()) {
-                debug("HTTP response body: requestId={}, body={}", requestId, truncate(respBody));
-            }
+            debug(HttpLogLevel.BODY, "HTTP response body: requestId={}, body={}", requestId, truncate(respBody));
         });
     }
 
@@ -450,11 +445,11 @@ private long elapsedMillis(long startedAt) {
         return (System.nanoTime() - startedAt) / 1_000_000L;
     }
 
-    private String truncate(String value) {
+    protected String truncate(String value) {
         if (Objects.isNull(value)) {
             return "";
         }
-        int limit = Math.max(0, config.getMaxLoggedBodyLength());
+        int limit = config.getDebug().resolveMaxContentLength();
         return value.length() <= limit ? value : value.substring(0, limit) + "...<truncated>";
     }
 
@@ -469,7 +464,7 @@ private Headers redactHeaders(Headers headers) {
     private String redactHeader(String name, String value) {
         if ("authorization".equalsIgnoreCase(name) || name.toLowerCase().contains("token")
                 || name.toLowerCase().contains("key")) {
-            return "██";
+            return "<redacted>";
         }
         return value;
     }
@@ -567,7 +562,18 @@ public CompletableFuture<Void> healthAsync() {
      * @param args 填充消息模板占位符的参数
      */
     protected void debug(String msg, Object... args) {
-        if (log.isDebugEnabled()) {
+        debug(HttpLogLevel.BASIC, msg, args);
+    }
+
+    /**
+     * 在统一调试配置允许指定级别且 SLF4J 开启 DEBUG 时记录日志。
+     *
+     * @param level 信息要求的最低 HTTP 日志级别
+     * @param msg 包含 SLF4J 占位符的日志消息模板
+     * @param args 填充消息模板占位符的参数
+     */
+    protected void debug(HttpLogLevel level, String msg, Object... args) {
+        if (config.getDebug().allows(level) && log.isDebugEnabled()) {
             log.debug(msg, args);
         }
     }

src/main/java/io/github/easy4j/openclaw/api/OpenClawSseClient.java

@@ -15,6 +15,7 @@
 import okhttp3.Request;
 import okhttp3.RequestBody;
 import okhttp3.Response;
+import okhttp3.extension.logging.HttpLogLevel;
 
 import java.io.IOException;
 import java.util.HashMap;
@@ -188,7 +189,7 @@ private void consume(Response response, SseSubscription subscription, SseEventHa
                 handler.onError(new OpenClawHttpException("SSE response body is null", null));
                 return;
             }
-            new SseStreamReader(objectMapper)
+            new SseStreamReader(objectMapper, config.getDebug())
                     .readChatCompletionStream(completed.body().byteStream(), handler);
         } catch (Exception error) {
             if (subscription.isActive()) {
@@ -268,11 +269,12 @@ private static ExecutorService createStreamExecutor(OpenClawHttpClientConfig con
     }
 
     private void logInitialization(OpenClawHttpClientConfig config) {
-        log.debug("OpenClaw SSE client initialized: baseUrl={}, maxRequests={}, "
-                        + "maxRequestsPerHost={}, eventQueueCapacity={}, reconnectPolicy=none, "
-                        + "detailedLoggingEnabled={}",
-                config.getBaseUrl(), config.getMaxRequests(), config.getMaxRequestsPerHost(),
-                config.getStreamQueueCapacity(), config.isDetailedLoggingEnabled());
+        if (config.getDebug().allows(HttpLogLevel.BASIC)) {
+            log.debug("OpenClaw SSE client initialized: baseUrl={}, maxRequests={}, "
+                            + "maxRequestsPerHost={}, eventQueueCapacity={}, reconnectPolicy=none, debugLevel={}",
+                    config.getBaseUrl(), config.getMaxRequests(), config.getMaxRequestsPerHost(),
+                    config.getStreamQueueCapacity(), config.getDebug().getLevel());
+        }
     }
 
     /**

src/main/java/io/github/easy4j/openclaw/api/OpenClawToolInvokeClient.java

@@ -9,6 +9,7 @@
 import io.github.easy4j.openclaw.api.model.ToolInvokeResult;
 import lombok.extern.slf4j.Slf4j;
 import okhttp3.*;
+import okhttp3.extension.logging.HttpLogLevel;
 
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
@@ -79,7 +80,7 @@ public CompletableFuture<ToolInvokeResult> invokeAsync(ToolInvokeRequest request
         debug("=== Tool Invoke Request ===");
         debug("tool: {}", request.getTool());
         debug("action: {}", request.getAction());
-        debug("args: {}", request.getArgs());
+        debug(HttpLogLevel.BODY, "args: {}", request.getArgs());
 
         if (OpenClawStrings.isBlank(request.getTool())) {
             String msg = "Tool name is required";
@@ -96,7 +97,7 @@ public CompletableFuture<ToolInvokeResult> invokeAsync(ToolInvokeRequest request
                 int status = response.getStatusCode();
                 String respBody = response.getBody();
                 debug("Tool invoke response status: {}", status);
-                debug("Tool invoke response body: {}", respBody);
+                debug(HttpLogLevel.BODY, "Tool invoke response body: {}", truncate(respBody));
 
                 if (status == 404) {
                     String msg = "Tool not available: " + request.getTool();