Improve the web launcher and gateway integration across backend and frontend.

- add runtime model availability checks for local and OAuth-backed models
- support launcher-driven gateway host overrides and websocket URL resolution
- add gateway log clearing and keep incremental log sync consistent after resets
- migrate session history APIs to JSONL metadata-backed storage with legacy fallback
- expose session titles and improve chat history loading and error handling
- move shared backend runtime helpers into the web utils package
- avoid blocking web startup when automatic onboard initialization fails
- add backend tests covering gateway readiness, host resolution, models, logs, and sessions

web/backend/api/config.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"io"
 	"net/http"
-	"os"
 
 	"github.com/sipeed/picoclaw/pkg/config"
 )
@@ -17,36 +16,11 @@ func (h *Handler) registerConfigRoutes(mux *http.ServeMux) {
 	mux.HandleFunc("PATCH /api/config", h.handlePatchConfig)
 }
 
-// loadFilteredConfig loads the configuration and filters out default placeholder credentials
-// (like API limits/keys) if the configuration file has not been created yet by the user.
-func (h *Handler) loadFilteredConfig() (*config.Config, error) {
-	cfg, err := config.LoadConfig(h.configPath)
-	if err != nil {
-		return nil, err
-	}
-
-	configExists := false
-	if h.configPath != "" {
-		if _, err := os.Stat(h.configPath); err == nil {
-			configExists = true
-		}
-	}
-
-	if !configExists {
-		for i := range cfg.ModelList {
-			cfg.ModelList[i].APIKey = ""
-			cfg.ModelList[i].AuthMethod = ""
-		}
-	}
-
-	return cfg, nil
-}
-
 // handleGetConfig returns the complete system configuration.
 //
 //	GET /api/config
 func (h *Handler) handleGetConfig(w http.ResponseWriter, r *http.Request) {
-	cfg, err := h.loadFilteredConfig()
+	cfg, err := config.LoadConfig(h.configPath)
 	if err != nil {
 		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
 		return

web/backend/api/gateway.go

@@ -10,7 +10,6 @@ import (
 	"net/http"
 	"os"
 	"os/exec"
-	"path/filepath"
 	"runtime"
 	"strconv"
 	"strings"
@@ -19,6 +18,7 @@ import (
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/web/backend/utils"
 )
 
 // gateway holds the state for the managed gateway process.
@@ -36,6 +36,7 @@ var gateway = struct {
 func (h *Handler) registerGatewayRoutes(mux *http.ServeMux) {
 	mux.HandleFunc("GET /api/gateway/status", h.handleGatewayStatus)
 	mux.HandleFunc("GET /api/gateway/events", h.handleGatewayEvents)
+	mux.HandleFunc("POST /api/gateway/logs/clear", h.handleGatewayClearLogs)
 	mux.HandleFunc("POST /api/gateway/start", h.handleGatewayStart)
 	mux.HandleFunc("POST /api/gateway/stop", h.handleGatewayStop)
 	mux.HandleFunc("POST /api/gateway/restart", h.handleGatewayRestart)
@@ -89,11 +90,12 @@ func (h *Handler) gatewayStartReady() (bool, string, error) {
 		return false, fmt.Sprintf("default model %q is invalid", modelName), nil
 	}
 
-	hasCredential := strings.TrimSpace(modelCfg.APIKey) != "" ||
+	if !hasModelConfiguration(*modelCfg) {
-		strings.TrimSpace(modelCfg.AuthMethod) != ""
-	if !hasCredential {
 		return false, fmt.Sprintf("default model %q has no credentials configured", modelName), nil
 	}
+	if requiresRuntimeProbe(*modelCfg) && !probeLocalModelAvailability(*modelCfg) {
+		return false, fmt.Sprintf("default model %q is not reachable", modelName), nil
+	}
 
 	return true, "", nil
 }
@@ -131,14 +133,18 @@ func isCmdProcessAliveLocked(cmd *exec.Cmd) bool {
 
 func (h *Handler) startGatewayLocked() (int, error) {
 	// Locate the picoclaw executable
-	execPath := findPicoclawBinary()
+	execPath := utils.FindPicoclawBinary()
 
 	cmd := exec.Command(execPath, "gateway")
+	cmd.Env = os.Environ()
 	// Forward the launcher's config path via the environment variable that
 	// GetConfigPath() already reads, so the gateway sub-process uses the same
 	// config file without requiring a --config flag on the gateway subcommand.
 	if h.configPath != "" {
-		cmd.Env = append(os.Environ(), "PICOCLAW_CONFIG="+h.configPath)
+		cmd.Env = append(cmd.Env, "PICOCLAW_CONFIG="+h.configPath)
+	}
+	if host := h.gatewayHostOverride(); host != "" {
+		cmd.Env = append(cmd.Env, "PICOCLAW_GATEWAY_HOST="+host)
 	}
 
 	stdoutPipe, err := cmd.StdoutPipe()
@@ -207,10 +213,7 @@ func (h *Handler) startGatewayLocked() (int, error) {
 			if err != nil {
 				continue
 			}
-			healthHost := "127.0.0.1"
+			healthHost := gatewayProbeHost(h.effectiveGatewayBindHost(cfg))
-			if cfg.Gateway.Host != "" && cfg.Gateway.Host != "0.0.0.0" {
-				healthHost = cfg.Gateway.Host
-			}
 			healthPort := cfg.Gateway.Port
 			if healthPort == 0 {
 				healthPort = 18790
@@ -353,6 +356,20 @@ func (h *Handler) handleGatewayRestart(w http.ResponseWriter, r *http.Request) {
 	h.handleGatewayStart(w, r)
 }
 
+// handleGatewayClearLogs clears the in-memory gateway log buffer.
+//
+//	POST /api/gateway/logs/clear
+func (h *Handler) handleGatewayClearLogs(w http.ResponseWriter, r *http.Request) {
+	gateway.logs.Clear()
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status":     "cleared",
+		"log_total":  0,
+		"log_run_id": gateway.logs.RunID(),
+	})
+}
+
 // handleGatewayStatus returns the gateway run status, health info, and logs.
 //
 //	GET /api/gateway/status
@@ -375,9 +392,7 @@ func (h *Handler) handleGatewayStatus(w http.ResponseWriter, r *http.Request) {
 		host := "127.0.0.1"
 		port := 18790
 		if err == nil && cfg != nil {
-			if cfg.Gateway.Host != "" && cfg.Gateway.Host != "0.0.0.0" {
+			host = gatewayProbeHost(h.effectiveGatewayBindHost(cfg))
-				host = cfg.Gateway.Host
-			}
 			if cfg.Gateway.Port != 0 {
 				port = cfg.Gateway.Port
 			}
@@ -535,36 +550,6 @@ func (h *Handler) currentGatewayStatus() string {
 	return string(encoded)
 }
 
-// findPicoclawBinary locates the picoclaw executable.
-// Search order:
-//  1. PICOCLAW_BINARY environment variable (explicit override)
-//  2. Same directory as the current executable
-//  3. Falls back to "picoclaw" and relies on $PATH
-func findPicoclawBinary() string {
-	binaryName := "picoclaw"
-	if runtime.GOOS == "windows" {
-		binaryName = "picoclaw.exe"
-	}
-
-	// 1. Explicit override via environment variable
-	if p := os.Getenv("PICOCLAW_BINARY"); p != "" {
-		if info, _ := os.Stat(p); info != nil && !info.IsDir() {
-			return p
-		}
-	}
-
-	// 2. Same directory as the launcher executable
-	if exe, err := os.Executable(); err == nil {
-		candidate := filepath.Join(filepath.Dir(exe), binaryName)
-		if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
-			return candidate
-		}
-	}
-
-	// 3. Fall back to PATH lookup
-	return "picoclaw"
-}
-
 // scanPipe reads lines from r and appends them to buf. Returns when r reaches EOF.
 func scanPipe(r io.Reader, buf *LogBuffer) {
 	scanner := bufio.NewScanner(r)

web/backend/api/gateway_host.go

@@ -0,0 +1,66 @@
+package api
+
+import (
+	"net"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func (h *Handler) effectiveLauncherPublic() bool {
+	if h.serverPublicExplicit {
+		return h.serverPublic
+	}
+
+	cfg, err := h.loadLauncherConfig()
+	if err == nil {
+		return cfg.Public
+	}
+
+	return h.serverPublic
+}
+
+func (h *Handler) gatewayHostOverride() string {
+	if h.effectiveLauncherPublic() {
+		return "0.0.0.0"
+	}
+	return ""
+}
+
+func (h *Handler) effectiveGatewayBindHost(cfg *config.Config) string {
+	if override := h.gatewayHostOverride(); override != "" {
+		return override
+	}
+	if cfg == nil {
+		return ""
+	}
+	return strings.TrimSpace(cfg.Gateway.Host)
+}
+
+func gatewayProbeHost(bindHost string) string {
+	if bindHost == "" || bindHost == "0.0.0.0" {
+		return "127.0.0.1"
+	}
+	return bindHost
+}
+
+func requestHostName(r *http.Request) string {
+	reqHost, _, err := net.SplitHostPort(r.Host)
+	if err == nil {
+		return reqHost
+	}
+	if strings.TrimSpace(r.Host) != "" {
+		return r.Host
+	}
+	return "127.0.0.1"
+}
+
+func (h *Handler) buildWsURL(r *http.Request, cfg *config.Config) string {
+	host := h.effectiveGatewayBindHost(cfg)
+	if host == "" || host == "0.0.0.0" {
+		host = requestHostName(r)
+	}
+	return "ws://" + net.JoinHostPort(host, strconv.Itoa(cfg.Gateway.Port)) + "/pico/ws"
+}

web/backend/api/gateway_host_test.go

@@ -0,0 +1,59 @@
+package api
+
+import (
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+)
+
+func TestGatewayHostOverrideUsesExplicitRuntimePublic(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	launcherPath := launcherconfig.PathForAppConfig(configPath)
+	if err := launcherconfig.Save(launcherPath, launcherconfig.Config{
+		Port:   18800,
+		Public: false,
+	}); err != nil {
+		t.Fatalf("launcherconfig.Save() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	h.SetServerOptions(18800, true, true, nil)
+
+	if got := h.gatewayHostOverride(); got != "0.0.0.0" {
+		t.Fatalf("gatewayHostOverride() = %q, want %q", got, "0.0.0.0")
+	}
+}
+
+func TestBuildWsURLUsesRequestHostWhenLauncherPublicSaved(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	launcherPath := launcherconfig.PathForAppConfig(configPath)
+	if err := launcherconfig.Save(launcherPath, launcherconfig.Config{
+		Port:   18800,
+		Public: true,
+	}); err != nil {
+		t.Fatalf("launcherconfig.Save() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	h.SetServerOptions(18800, false, false, nil)
+
+	cfg := config.DefaultConfig()
+	cfg.Gateway.Host = "127.0.0.1"
+	cfg.Gateway.Port = 18790
+
+	req := httptest.NewRequest("GET", "http://launcher.local/api/pico/token", nil)
+	req.Host = "192.168.1.9:18800"
+
+	if got := h.buildWsURL(req, cfg); got != "ws://192.168.1.9:18790/pico/ws" {
+		t.Fatalf("buildWsURL() = %q, want %q", got, "ws://192.168.1.9:18790/pico/ws")
+	}
+}
+
+func TestGatewayProbeHostUsesLoopbackForWildcardBind(t *testing.T) {
+	if got := gatewayProbeHost("0.0.0.0"); got != "127.0.0.1" {
+		t.Fatalf("gatewayProbeHost() = %q, want %q", got, "127.0.0.1")
+	}
+}

web/backend/api/gateway_test.go

@@ -6,10 +6,13 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"testing"
 
+	"github.com/sipeed/picoclaw/pkg/auth"
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/web/backend/utils"
 )
 
 func TestGatewayStartReady_NoDefaultModel(t *testing.T) {
@@ -32,7 +35,8 @@ func TestGatewayStartReady_InvalidDefaultModel(t *testing.T) {
 	configPath := filepath.Join(t.TempDir(), "config.json")
 	cfg := config.DefaultConfig()
 	cfg.Agents.Defaults.Model = "missing-model"
-	if err := config.SaveConfig(configPath, cfg); err != nil {
+	err := config.SaveConfig(configPath, cfg)
+	if err != nil {
 		t.Fatalf("SaveConfig() error = %v", err)
 	}
 
@@ -54,7 +58,8 @@ func TestGatewayStartReady_ValidDefaultModel(t *testing.T) {
 	cfg := config.DefaultConfig()
 	cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
 	cfg.ModelList[0].APIKey = "test-key"
-	if err := config.SaveConfig(configPath, cfg); err != nil {
+	err := config.SaveConfig(configPath, cfg)
+	if err != nil {
 		t.Fatalf("SaveConfig() error = %v", err)
 	}
 
@@ -74,7 +79,8 @@ func TestGatewayStartReady_DefaultModelWithoutCredential(t *testing.T) {
 	cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
 	cfg.ModelList[0].APIKey = ""
 	cfg.ModelList[0].AuthMethod = ""
-	if err := config.SaveConfig(configPath, cfg); err != nil {
+	err := config.SaveConfig(configPath, cfg)
+	if err != nil {
 		t.Fatalf("SaveConfig() error = %v", err)
 	}
 
@@ -91,6 +97,195 @@ func TestGatewayStartReady_DefaultModelWithoutCredential(t *testing.T) {
 	}
 }
 
+func TestGatewayStartReady_LocalModelWithoutAPIKey(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetModelProbeHooks(t)
+
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
+		return false
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []config.ModelConfig{{
+		ModelName: "local-vllm",
+		Model:     "vllm/custom-model",
+		APIBase:   "http://localhost:8000/v1",
+	}}
+	cfg.Agents.Defaults.ModelName = "local-vllm"
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if ready {
+		t.Fatalf("gatewayStartReady() ready = true, want false without a running local service")
+	}
+	if !strings.Contains(reason, "not reachable") {
+		t.Fatalf("gatewayStartReady() reason = %q, want contains %q", reason, "not reachable")
+	}
+}
+
+func TestGatewayStartReady_LocalModelWithRunningService(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetModelProbeHooks(t)
+
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
+		return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model"
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []config.ModelConfig{{
+		ModelName: "local-vllm",
+		Model:     "vllm/custom-model",
+		APIBase:   "http://127.0.0.1:8000/v1",
+	}}
+	cfg.Agents.Defaults.ModelName = "local-vllm"
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if !ready {
+		t.Fatalf("gatewayStartReady() ready = false, want true with a running local service (reason=%q)", reason)
+	}
+}
+
+func TestGatewayStartReady_RemoteVLLMWithAPIKeyDoesNotProbe(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetModelProbeHooks(t)
+
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
+		t.Fatalf("unexpected OpenAI-compatible probe for %q (%q)", apiBase, modelID)
+		return false
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []config.ModelConfig{{
+		ModelName: "remote-vllm",
+		Model:     "vllm/custom-model",
+		APIBase:   "https://models.example.com/v1",
+		APIKey:    "remote-key",
+	}}
+	cfg.Agents.Defaults.ModelName = "remote-vllm"
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if !ready {
+		t.Fatalf("gatewayStartReady() ready = false, want true for remote vllm with api key (reason=%q)", reason)
+	}
+}
+
+func TestGatewayStartReady_LocalOllamaUsesDefaultProbeBase(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetModelProbeHooks(t)
+
+	probeOllamaModelFunc = func(apiBase, modelID string) bool {
+		return apiBase == "http://localhost:11434/v1" && modelID == "llama3"
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []config.ModelConfig{{
+		ModelName: "local-ollama",
+		Model:     "ollama/llama3",
+	}}
+	cfg.Agents.Defaults.ModelName = "local-ollama"
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if !ready {
+		t.Fatalf("gatewayStartReady() ready = false, want true with default Ollama probe base (reason=%q)", reason)
+	}
+}
+
+func TestGatewayStartReady_OAuthModelRequiresStoredCredential(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []config.ModelConfig{{
+		ModelName:  "openai-oauth",
+		Model:      "openai/gpt-5.2",
+		AuthMethod: "oauth",
+	}}
+	cfg.Agents.Defaults.ModelName = "openai-oauth"
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if ready {
+		t.Fatalf("gatewayStartReady() ready = true, want false without stored credential")
+	}
+	if !strings.Contains(reason, "no credentials configured") {
+		t.Fatalf("gatewayStartReady() reason = %q, want contains %q", reason, "no credentials configured")
+	}
+
+	err = auth.SetCredential(oauthProviderOpenAI, &auth.AuthCredential{
+		AccessToken: "openai-token",
+		Provider:    oauthProviderOpenAI,
+		AuthMethod:  "oauth",
+	})
+	if err != nil {
+		t.Fatalf("SetCredential() error = %v", err)
+	}
+
+	ready, reason, err = h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if !ready {
+		t.Fatalf("gatewayStartReady() ready = false, want true with stored credential (reason=%q)", reason)
+	}
+}
+
 func TestGatewayStatusIncludesStartConditionWhenNotReady(t *testing.T) {
 	configPath := filepath.Join(t.TempDir(), "config.json")
 	h := NewHandler(configPath)
@@ -122,6 +317,67 @@ func TestGatewayStatusIncludesStartConditionWhenNotReady(t *testing.T) {
 	}
 }
 
+func TestGatewayClearLogsResetsBufferedHistory(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	gateway.logs.Clear()
+	gateway.logs.Append("first line")
+	gateway.logs.Append("second line")
+	previousRunID := gateway.logs.RunID()
+
+	clearRec := httptest.NewRecorder()
+	clearReq := httptest.NewRequest(http.MethodPost, "/api/gateway/logs/clear", nil)
+	mux.ServeHTTP(clearRec, clearReq)
+
+	if clearRec.Code != http.StatusOK {
+		t.Fatalf("clear status = %d, want %d", clearRec.Code, http.StatusOK)
+	}
+
+	var clearBody map[string]any
+	if err := json.Unmarshal(clearRec.Body.Bytes(), &clearBody); err != nil {
+		t.Fatalf("unmarshal clear response: %v", err)
+	}
+
+	if got := clearBody["status"]; got != "cleared" {
+		t.Fatalf("clear status body = %#v, want %q", got, "cleared")
+	}
+
+	clearRunID, ok := clearBody["log_run_id"].(float64)
+	if !ok {
+		t.Fatalf("log_run_id missing or not number: %#v", clearBody["log_run_id"])
+	}
+	if int(clearRunID) <= previousRunID {
+		t.Fatalf("log_run_id = %d, want > %d", int(clearRunID), previousRunID)
+	}
+
+	statusRec := httptest.NewRecorder()
+	statusReq := httptest.NewRequest(http.MethodGet, "/api/gateway/status?log_offset=0&log_run_id="+strconv.Itoa(previousRunID), nil)
+	mux.ServeHTTP(statusRec, statusReq)
+
+	if statusRec.Code != http.StatusOK {
+		t.Fatalf("status code = %d, want %d", statusRec.Code, http.StatusOK)
+	}
+
+	var statusBody map[string]any
+	if err := json.Unmarshal(statusRec.Body.Bytes(), &statusBody); err != nil {
+		t.Fatalf("unmarshal status response: %v", err)
+	}
+
+	logs, ok := statusBody["logs"].([]any)
+	if !ok {
+		t.Fatalf("logs missing or not array: %#v", statusBody["logs"])
+	}
+	if len(logs) != 0 {
+		t.Fatalf("logs len = %d, want 0", len(logs))
+	}
+	if got := statusBody["log_total"]; got != float64(0) {
+		t.Fatalf("log_total = %#v, want 0", got)
+	}
+}
+
 func TestFindPicoclawBinary_EnvOverride(t *testing.T) {
 	// Create a temporary file to act as the mock binary
 	tmpDir := t.TempDir()
@@ -132,9 +388,9 @@ func TestFindPicoclawBinary_EnvOverride(t *testing.T) {
 
 	t.Setenv("PICOCLAW_BINARY", mockBinary)
 
-	got := findPicoclawBinary()
+	got := utils.FindPicoclawBinary()
 	if got != mockBinary {
-		t.Errorf("findPicoclawBinary() = %q, want %q", got, mockBinary)
+		t.Errorf("FindPicoclawBinary() = %q, want %q", got, mockBinary)
 	}
 }
 
@@ -142,9 +398,9 @@ func TestFindPicoclawBinary_EnvOverride_InvalidPath(t *testing.T) {
 	// When PICOCLAW_BINARY points to a non-existent path, fall through to next strategy
 	t.Setenv("PICOCLAW_BINARY", "/nonexistent/picoclaw-binary")
 
-	got := findPicoclawBinary()
+	got := utils.FindPicoclawBinary()
 	// Should not return the invalid path; falls back to "picoclaw" or another found path
 	if got == "/nonexistent/picoclaw-binary" {
-		t.Errorf("findPicoclawBinary() returned invalid env path %q, expected fallback", got)
+		t.Errorf("FindPicoclawBinary() returned invalid env path %q, expected fallback", got)
 	}
 }

web/backend/api/launcher_config_test.go

@@ -14,7 +14,7 @@ import (
 func TestGetLauncherConfigUsesRuntimeFallback(t *testing.T) {
 	configPath := filepath.Join(t.TempDir(), "config.json")
 	h := NewHandler(configPath)
-	h.SetServerOptions(19999, true, []string{"192.168.1.0/24"})
+	h.SetServerOptions(19999, true, false, []string{"192.168.1.0/24"})
 
 	mux := http.NewServeMux()
 	h.RegisterRoutes(mux)

web/backend/api/log.go

@@ -4,7 +4,7 @@ import "sync"
 
 // LogBuffer is a thread-safe ring buffer that stores the most recent N log lines.
 // It supports incremental reads via LinesSince and tracks a runID that increments
-// on each Reset (used to detect gateway restarts).
+// whenever the buffer is reset or cleared so clients can detect log history resets.
 type LogBuffer struct {
 	mu    sync.RWMutex
 	lines []string
@@ -45,6 +45,12 @@ func (b *LogBuffer) Reset() {
 	b.runID++
 }
 
+// Clear removes all buffered lines and increments the runID so clients treat
+// subsequent reads as a new log stream.
+func (b *LogBuffer) Clear() {
+	b.Reset()
+}
+
 // LinesSince returns lines appended after the given offset, the current total count, and the runID.
 // If offset >= total, no lines are returned. If offset is too old (evicted), all buffered lines are returned.
 func (b *LogBuffer) LinesSince(offset int) (lines []string, total int, runID int) {

web/backend/api/model_status.go

@@ -0,0 +1,324 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+const modelProbeTimeout = 800 * time.Millisecond
+
+var (
+	probeTCPServiceFunc            = probeTCPService
+	probeOllamaModelFunc           = probeOllamaModel
+	probeOpenAICompatibleModelFunc = probeOpenAICompatibleModel
+)
+
+func hasModelConfiguration(m config.ModelConfig) bool {
+	authMethod := strings.ToLower(strings.TrimSpace(m.AuthMethod))
+	apiKey := strings.TrimSpace(m.APIKey)
+
+	if authMethod == "oauth" || authMethod == "token" {
+		if provider, ok := oauthProviderForModel(m.Model); ok {
+			cred, err := oauthGetCredential(provider)
+			if err != nil || cred == nil {
+				return false
+			}
+			return strings.TrimSpace(cred.AccessToken) != "" || strings.TrimSpace(cred.RefreshToken) != ""
+		}
+		return true
+	}
+
+	if requiresRuntimeProbe(m) {
+		return true
+	}
+
+	return apiKey != ""
+}
+
+// isModelConfigured reports whether a model is currently available to use.
+// Local models must be reachable; remote/API-key models only need saved config.
+func isModelConfigured(m config.ModelConfig) bool {
+	if !hasModelConfiguration(m) {
+		return false
+	}
+	if requiresRuntimeProbe(m) {
+		return probeLocalModelAvailability(m)
+	}
+	return true
+}
+
+func requiresRuntimeProbe(m config.ModelConfig) bool {
+	authMethod := strings.ToLower(strings.TrimSpace(m.AuthMethod))
+	if authMethod == "local" {
+		return true
+	}
+
+	switch modelProtocol(m.Model) {
+	case "claude-cli", "claudecli", "codex-cli", "codexcli", "github-copilot", "copilot":
+		return true
+	case "ollama", "vllm":
+		apiBase := strings.TrimSpace(m.APIBase)
+		return apiBase == "" || hasLocalAPIBase(apiBase)
+	}
+
+	if hasLocalAPIBase(m.APIBase) {
+		return true
+	}
+
+	return false
+}
+
+func probeLocalModelAvailability(m config.ModelConfig) bool {
+	apiBase := modelProbeAPIBase(m)
+	protocol, modelID := splitModel(m.Model)
+	switch protocol {
+	case "ollama":
+		return probeOllamaModelFunc(apiBase, modelID)
+	case "vllm":
+		return probeOpenAICompatibleModelFunc(apiBase, modelID)
+	case "github-copilot", "copilot":
+		return probeTCPServiceFunc(apiBase)
+	case "claude-cli", "claudecli", "codex-cli", "codexcli":
+		return true
+	default:
+		if hasLocalAPIBase(apiBase) {
+			return probeOpenAICompatibleModelFunc(apiBase, modelID)
+		}
+		return false
+	}
+}
+
+func modelProbeAPIBase(m config.ModelConfig) string {
+	if apiBase := strings.TrimSpace(m.APIBase); apiBase != "" {
+		return normalizeModelProbeAPIBase(apiBase)
+	}
+
+	switch modelProtocol(m.Model) {
+	case "ollama":
+		return "http://localhost:11434/v1"
+	case "vllm":
+		return "http://localhost:8000/v1"
+	case "github-copilot", "copilot":
+		return "localhost:4321"
+	default:
+		return ""
+	}
+}
+
+func normalizeModelProbeAPIBase(raw string) string {
+	u, err := parseAPIBase(raw)
+	if err != nil {
+		return strings.TrimSpace(raw)
+	}
+
+	switch strings.ToLower(u.Hostname()) {
+	case "0.0.0.0":
+		u.Host = net.JoinHostPort("127.0.0.1", u.Port())
+	case "::":
+		u.Host = net.JoinHostPort("::1", u.Port())
+	default:
+		return strings.TrimSpace(raw)
+	}
+
+	if u.Port() == "" {
+		u.Host = u.Hostname()
+	}
+
+	return u.String()
+}
+
+func oauthProviderForModel(model string) (string, bool) {
+	switch modelProtocol(model) {
+	case "openai":
+		return oauthProviderOpenAI, true
+	case "anthropic":
+		return oauthProviderAnthropic, true
+	case "antigravity", "google-antigravity":
+		return oauthProviderGoogleAntigravity, true
+	default:
+		return "", false
+	}
+}
+
+func modelProtocol(model string) string {
+	protocol, _ := splitModel(model)
+	return protocol
+}
+
+func splitModel(model string) (protocol, modelID string) {
+	model = strings.ToLower(strings.TrimSpace(model))
+	protocol, _, found := strings.Cut(model, "/")
+	if !found {
+		return "openai", model
+	}
+	return protocol, strings.TrimSpace(model[strings.Index(model, "/")+1:])
+}
+
+func hasLocalAPIBase(raw string) bool {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return false
+	}
+
+	u, err := url.Parse(raw)
+	if err != nil || u.Hostname() == "" {
+		u, err = url.Parse("//" + raw)
+		if err != nil {
+			return false
+		}
+	}
+
+	switch strings.ToLower(u.Hostname()) {
+	case "localhost", "127.0.0.1", "::1", "0.0.0.0":
+		return true
+	default:
+		return false
+	}
+}
+
+func probeTCPService(raw string) bool {
+	hostPort, err := hostPortFromAPIBase(raw)
+	if err != nil {
+		return false
+	}
+
+	conn, err := net.DialTimeout("tcp", hostPort, modelProbeTimeout)
+	if err != nil {
+		return false
+	}
+	_ = conn.Close()
+	return true
+}
+
+func probeOllamaModel(apiBase, modelID string) bool {
+	root, err := apiRootFromAPIBase(apiBase)
+	if err != nil {
+		return false
+	}
+
+	var resp struct {
+		Models []struct {
+			Name  string `json:"name"`
+			Model string `json:"model"`
+		} `json:"models"`
+	}
+	if err := getJSON(root+"/api/tags", &resp); err != nil {
+		return false
+	}
+
+	for _, model := range resp.Models {
+		if ollamaModelMatches(model.Name, modelID) || ollamaModelMatches(model.Model, modelID) {
+			return true
+		}
+	}
+	return false
+}
+
+func probeOpenAICompatibleModel(apiBase, modelID string) bool {
+	if strings.TrimSpace(apiBase) == "" {
+		return false
+	}
+
+	var resp struct {
+		Data []struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	if err := getJSON(strings.TrimRight(strings.TrimSpace(apiBase), "/")+"/models", &resp); err != nil {
+		return false
+	}
+
+	for _, model := range resp.Data {
+		if strings.EqualFold(strings.TrimSpace(model.ID), modelID) {
+			return true
+		}
+	}
+	return false
+}
+
+func getJSON(rawURL string, out any) error {
+	req, err := http.NewRequest(http.MethodGet, rawURL, nil)
+	if err != nil {
+		return err
+	}
+
+	client := &http.Client{Timeout: modelProbeTimeout}
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("unexpected status %d", resp.StatusCode)
+	}
+
+	return json.NewDecoder(resp.Body).Decode(out)
+}
+
+func apiRootFromAPIBase(raw string) (string, error) {
+	u, err := parseAPIBase(raw)
+	if err != nil {
+		return "", err
+	}
+	return (&url.URL{Scheme: u.Scheme, Host: u.Host}).String(), nil
+}
+
+func hostPortFromAPIBase(raw string) (string, error) {
+	u, err := parseAPIBase(raw)
+	if err != nil {
+		return "", err
+	}
+
+	if port := u.Port(); port != "" {
+		return u.Host, nil
+	}
+	switch strings.ToLower(u.Scheme) {
+	case "https":
+		return net.JoinHostPort(u.Hostname(), "443"), nil
+	default:
+		return net.JoinHostPort(u.Hostname(), "80"), nil
+	}
+}
+
+func parseAPIBase(raw string) (*url.URL, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil, fmt.Errorf("empty api base")
+	}
+
+	u, err := url.Parse(raw)
+	if err == nil && u.Hostname() != "" {
+		return u, nil
+	}
+
+	u, err = url.Parse("//" + raw)
+	if err != nil || u.Hostname() == "" {
+		return nil, fmt.Errorf("invalid api base %q", raw)
+	}
+	if u.Scheme == "" {
+		u.Scheme = "http"
+	}
+	return u, nil
+}
+
+func ollamaModelMatches(candidate, want string) bool {
+	candidate = strings.TrimSpace(candidate)
+	want = strings.TrimSpace(want)
+	if candidate == "" || want == "" {
+		return false
+	}
+	if strings.EqualFold(candidate, want) {
+		return true
+	}
+
+	base, _, _ := strings.Cut(candidate, ":")
+	return strings.EqualFold(base, want)
+}

web/backend/api/models.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"net/http"
 	"strconv"
+	"sync"
 
 	"github.com/sipeed/picoclaw/pkg/config"
 )
@@ -45,13 +46,24 @@ type modelResponse struct {
 //
 //	GET /api/models
 func (h *Handler) handleListModels(w http.ResponseWriter, r *http.Request) {
-	cfg, err := h.loadFilteredConfig()
+	cfg, err := config.LoadConfig(h.configPath)
 	if err != nil {
 		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
 		return
 	}
 
 	defaultModel := cfg.Agents.Defaults.GetModelName()
+	configured := make([]bool, len(cfg.ModelList))
+
+	var wg sync.WaitGroup
+	wg.Add(len(cfg.ModelList))
+	for i, m := range cfg.ModelList {
+		go func(i int, m config.ModelConfig) {
+			defer wg.Done()
+			configured[i] = isModelConfigured(m)
+		}(i, m)
+	}
+	wg.Wait()
 
 	models := make([]modelResponse, 0, len(cfg.ModelList))
 	for i, m := range cfg.ModelList {
@@ -69,7 +81,7 @@ func (h *Handler) handleListModels(w http.ResponseWriter, r *http.Request) {
 			MaxTokensField: m.MaxTokensField,
 			RequestTimeout: m.RequestTimeout,
 			ThinkingLevel:  m.ThinkingLevel,
-			Configured:     m.APIKey != "" || m.AuthMethod != "",
+			Configured:     configured[i],
 			IsDefault:      m.ModelName == defaultModel,
 		})
 	}

web/backend/api/models_test.go

@@ -0,0 +1,313 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func resetModelProbeHooks(t *testing.T) {
+	t.Helper()
+
+	origTCPProbe := probeTCPServiceFunc
+	origOllamaProbe := probeOllamaModelFunc
+	origOpenAIProbe := probeOpenAICompatibleModelFunc
+	t.Cleanup(func() {
+		probeTCPServiceFunc = origTCPProbe
+		probeOllamaModelFunc = origOllamaProbe
+		probeOpenAICompatibleModelFunc = origOpenAIProbe
+	})
+}
+
+func TestHandleListModels_ConfiguredStatusUsesRuntimeProbesForLocalModels(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+	resetModelProbeHooks(t)
+
+	var mu sync.Mutex
+	var openAIProbes []string
+	var ollamaProbes []string
+	var tcpProbes []string
+
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
+		mu.Lock()
+		openAIProbes = append(openAIProbes, apiBase+"|"+modelID)
+		mu.Unlock()
+		return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model"
+	}
+	probeOllamaModelFunc = func(apiBase, modelID string) bool {
+		mu.Lock()
+		ollamaProbes = append(ollamaProbes, apiBase+"|"+modelID)
+		mu.Unlock()
+		return apiBase == "http://localhost:11434/v1" && modelID == "llama3"
+	}
+	probeTCPServiceFunc = func(apiBase string) bool {
+		mu.Lock()
+		tcpProbes = append(tcpProbes, apiBase)
+		mu.Unlock()
+		return apiBase == "http://127.0.0.1:4321"
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []config.ModelConfig{
+		{
+			ModelName:  "openai-oauth",
+			Model:      "openai/gpt-5.2",
+			AuthMethod: "oauth",
+		},
+		{
+			ModelName: "vllm-local",
+			Model:     "vllm/custom-model",
+			APIBase:   "http://127.0.0.1:8000/v1",
+		},
+		{
+			ModelName: "ollama-default",
+			Model:     "ollama/llama3",
+		},
+		{
+			ModelName: "vllm-remote",
+			Model:     "vllm/custom-model",
+			APIBase:   "https://models.example.com/v1",
+			APIKey:    "remote-key",
+		},
+		{
+			ModelName:  "copilot-gpt-5.2",
+			Model:      "github-copilot/gpt-5.2",
+			APIBase:    "http://127.0.0.1:4321",
+			AuthMethod: "oauth",
+		},
+	}
+	cfg.Agents.Defaults.ModelName = "openai-oauth"
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/models", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp struct {
+		Models []modelResponse `json:"models"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+
+	got := make(map[string]bool, len(resp.Models))
+	for _, model := range resp.Models {
+		got[model.ModelName] = model.Configured
+	}
+
+	if got["openai-oauth"] {
+		t.Fatalf("openai oauth model configured = true, want false without stored credential")
+	}
+	if !got["vllm-local"] {
+		t.Fatalf("vllm local model configured = false, want true when local probe succeeds")
+	}
+	if !got["ollama-default"] {
+		t.Fatalf("ollama default model configured = false, want true when default local probe succeeds")
+	}
+	if !got["vllm-remote"] {
+		t.Fatalf("remote vllm model configured = false, want true with api_key")
+	}
+	if !got["copilot-gpt-5.2"] {
+		t.Fatalf("copilot model configured = false, want true when local bridge probe succeeds")
+	}
+	if len(openAIProbes) != 1 || openAIProbes[0] != "http://127.0.0.1:8000/v1|custom-model" {
+		t.Fatalf("openAI probes = %#v, want only local vllm probe", openAIProbes)
+	}
+	if len(ollamaProbes) != 1 || ollamaProbes[0] != "http://localhost:11434/v1|llama3" {
+		t.Fatalf("ollama probes = %#v, want default local probe", ollamaProbes)
+	}
+	if len(tcpProbes) != 1 || tcpProbes[0] != "http://127.0.0.1:4321" {
+		t.Fatalf("tcp probes = %#v, want only local copilot probe", tcpProbes)
+	}
+}
+
+func TestHandleListModels_ConfiguredStatusForOAuthModelWithCredential(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+	resetModelProbeHooks(t)
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []config.ModelConfig{{
+		ModelName:  "claude-oauth",
+		Model:      "anthropic/claude-sonnet-4.6",
+		AuthMethod: "oauth",
+	}}
+	cfg.Agents.Defaults.ModelName = "claude-oauth"
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	if err := auth.SetCredential(oauthProviderAnthropic, &auth.AuthCredential{
+		AccessToken: "anthropic-token",
+		Provider:    oauthProviderAnthropic,
+		AuthMethod:  "oauth",
+	}); err != nil {
+		t.Fatalf("SetCredential() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/models", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp struct {
+		Models []modelResponse `json:"models"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if len(resp.Models) != 1 {
+		t.Fatalf("len(models) = %d, want 1", len(resp.Models))
+	}
+	if !resp.Models[0].Configured {
+		t.Fatalf("oauth model configured = false, want true with stored credential")
+	}
+}
+
+func TestHandleListModels_ProbesLocalModelsConcurrently(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+	resetModelProbeHooks(t)
+
+	started := make(chan string, 2)
+	release := make(chan struct{})
+
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
+		started <- apiBase + "|" + modelID
+		<-release
+		return true
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []config.ModelConfig{
+		{
+			ModelName: "local-vllm-a",
+			Model:     "vllm/custom-a",
+			APIBase:   "http://127.0.0.1:8000/v1",
+		},
+		{
+			ModelName: "local-vllm-b",
+			Model:     "vllm/custom-b",
+			APIBase:   "http://127.0.0.1:8001/v1",
+		},
+	}
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	recCh := make(chan *httptest.ResponseRecorder, 1)
+	go func() {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/api/models", nil)
+		mux.ServeHTTP(rec, req)
+		recCh <- rec
+	}()
+
+	for i := 0; i < 2; i++ {
+		select {
+		case <-started:
+		case <-time.After(200 * time.Millisecond):
+			t.Fatal("expected both local probes to start before the first one completed")
+		}
+	}
+	close(release)
+
+	rec := <-recCh
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+}
+
+func TestHandleListModels_NormalizesWildcardLocalAPIBaseForProbe(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+	resetModelProbeHooks(t)
+
+	var gotProbe string
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
+		gotProbe = apiBase + "|" + modelID
+		return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model"
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []config.ModelConfig{{
+		ModelName: "vllm-local",
+		Model:     "vllm/custom-model",
+		APIBase:   "http://0.0.0.0:8000/v1",
+	}}
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/models", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp struct {
+		Models []modelResponse `json:"models"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if len(resp.Models) != 1 {
+		t.Fatalf("len(models) = %d, want 1", len(resp.Models))
+	}
+	if !resp.Models[0].Configured {
+		t.Fatal("wildcard-bound local model configured = false, want true after probe host normalization")
+	}
+	if gotProbe != "http://127.0.0.1:8000/v1|custom-model" {
+		t.Fatalf("probe api base = %q, want %q", gotProbe, "http://127.0.0.1:8000/v1|custom-model")
+	}
+}

web/backend/api/pico.go

@@ -5,9 +5,7 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
-	"net"
 	"net/http"
-	"strconv"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/config"
@@ -30,7 +28,7 @@ func (h *Handler) handleGetPicoToken(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	wsURL := buildWsURL(r, cfg)
+	wsURL := h.buildWsURL(r, cfg)
 
 	w.Header().Set("Content-Type", "application/json")
 	json.NewEncoder(w).Encode(map[string]any{
@@ -58,7 +56,7 @@ func (h *Handler) handleRegenPicoToken(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	wsURL := fmt.Sprintf("ws://%s/pico/ws", net.JoinHostPort(cfg.Gateway.Host, strconv.Itoa(cfg.Gateway.Port)))
+	wsURL := h.buildWsURL(r, cfg)
 
 	w.Header().Set("Content-Type", "application/json")
 	json.NewEncoder(w).Encode(map[string]any{
@@ -123,7 +121,7 @@ func (h *Handler) handlePicoSetup(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	wsURL := buildWsURL(r, cfg)
+	wsURL := h.buildWsURL(r, cfg)
 
 	w.Header().Set("Content-Type", "application/json")
 	json.NewEncoder(w).Encode(map[string]any{
@@ -134,22 +132,6 @@ func (h *Handler) handlePicoSetup(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
-// buildWsURL creates a WebSocket URL for the Pico Channel.
-// When the gateway host is "0.0.0.0" or empty, it uses the hostname from the
-// incoming HTTP request so the browser gets a connectable address.
-func buildWsURL(r *http.Request, cfg *config.Config) string {
-	host := cfg.Gateway.Host
-	if host == "" || host == "0.0.0.0" {
-		// Use the hostname the browser used to reach this backend
-		reqHost, _, err := net.SplitHostPort(r.Host)
-		if err != nil {
-			reqHost = r.Host // r.Host might not have a port
-		}
-		host = reqHost
-	}
-	return "ws://" + net.JoinHostPort(host, strconv.Itoa(cfg.Gateway.Port)) + "/pico/ws"
-}
-
 // generateSecureToken creates a random 32-character hex string.
 func generateSecureToken() string {
 	b := make([]byte, 16)

web/backend/api/router.go

@@ -12,6 +12,7 @@ type Handler struct {
 	configPath           string
 	serverPort           int
 	serverPublic         bool
+	serverPublicExplicit bool
 	serverCIDRs          []string
 	oauthMu              sync.Mutex
 	oauthFlows           map[string]*oauthFlow
@@ -29,9 +30,10 @@ func NewHandler(configPath string) *Handler {
 }
 
 // SetServerOptions stores current backend listen options for fallback behavior.
-func (h *Handler) SetServerOptions(port int, public bool, allowedCIDRs []string) {
+func (h *Handler) SetServerOptions(port int, public bool, publicExplicit bool, allowedCIDRs []string) {
 	h.serverPort = port
 	h.serverPublic = public
+	h.serverPublicExplicit = publicExplicit
 	h.serverCIDRs = append([]string(nil), allowedCIDRs...)
 }
 

web/backend/api/session.go

@@ -1,7 +1,9 @@
 package api
 
 import (
+	"bufio"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"os"
 	"path/filepath"
@@ -33,12 +35,22 @@ type sessionFile struct {
 // sessionListItem is a lightweight summary returned by GET /api/sessions.
 type sessionListItem struct {
 	ID           string `json:"id"`
+	Title        string `json:"title"`
 	Preview      string `json:"preview"`
 	MessageCount int    `json:"message_count"`
 	Created      string `json:"created"`
 	Updated      string `json:"updated"`
 }
 
+type sessionMetaFile struct {
+	Key       string    `json:"key"`
+	Summary   string    `json:"summary"`
+	Skip      int       `json:"skip"`
+	Count     int       `json:"count"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
 // picoSessionPrefix is the key prefix used by the gateway's routing for Pico
 // channel sessions. The full key format is:
 //
@@ -47,7 +59,12 @@ type sessionListItem struct {
 // The sanitized filename replaces ':' with '_', so on disk it becomes:
 //
 //	agent_main_pico_direct_pico_<session-uuid>.json
-const picoSessionPrefix = "agent:main:pico:direct:pico:"
+const (
+	picoSessionPrefix          = "agent:main:pico:direct:pico:"
+	sanitizedPicoSessionPrefix = "agent_main_pico_direct_pico_"
+	maxSessionJSONLLineSize    = 10 * 1024 * 1024 // 10 MB
+	maxSessionTitleRunes       = 60
+)
 
 // extractPicoSessionID extracts the session UUID from a full session key.
 // Returns the UUID and true if the key matches the Pico session pattern.
@@ -58,6 +75,178 @@ func extractPicoSessionID(key string) (string, bool) {
 	return "", false
 }
 
+func extractPicoSessionIDFromSanitizedKey(key string) (string, bool) {
+	if strings.HasPrefix(key, sanitizedPicoSessionPrefix) {
+		return strings.TrimPrefix(key, sanitizedPicoSessionPrefix), true
+	}
+	return "", false
+}
+
+func sanitizeSessionKey(key string) string {
+	return strings.ReplaceAll(key, ":", "_")
+}
+
+func (h *Handler) readLegacySession(dir, sessionID string) (sessionFile, error) {
+	path := filepath.Join(dir, sanitizeSessionKey(picoSessionPrefix+sessionID)+".json")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return sessionFile{}, err
+	}
+
+	var sess sessionFile
+	if err := json.Unmarshal(data, &sess); err != nil {
+		return sessionFile{}, err
+	}
+	return sess, nil
+}
+
+func (h *Handler) readSessionMeta(path, sessionKey string) (sessionMetaFile, error) {
+	data, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return sessionMetaFile{Key: sessionKey}, nil
+	}
+	if err != nil {
+		return sessionMetaFile{}, err
+	}
+
+	var meta sessionMetaFile
+	if err := json.Unmarshal(data, &meta); err != nil {
+		return sessionMetaFile{}, err
+	}
+	if meta.Key == "" {
+		meta.Key = sessionKey
+	}
+	return meta, nil
+}
+
+func (h *Handler) readSessionMessages(path string, skip int) ([]providers.Message, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+
+	msgs := make([]providers.Message, 0)
+	scanner := bufio.NewScanner(f)
+	scanner.Buffer(make([]byte, 0, 64*1024), maxSessionJSONLLineSize)
+
+	seen := 0
+	for scanner.Scan() {
+		line := scanner.Bytes()
+		if len(line) == 0 {
+			continue
+		}
+
+		seen++
+		if seen <= skip {
+			continue
+		}
+
+		var msg providers.Message
+		if err := json.Unmarshal(line, &msg); err != nil {
+			continue
+		}
+		msgs = append(msgs, msg)
+	}
+	if err := scanner.Err(); err != nil {
+		return nil, err
+	}
+	return msgs, nil
+}
+
+func (h *Handler) readJSONLSession(dir, sessionID string) (sessionFile, error) {
+	sessionKey := picoSessionPrefix + sessionID
+	base := filepath.Join(dir, sanitizeSessionKey(sessionKey))
+	jsonlPath := base + ".jsonl"
+	metaPath := base + ".meta.json"
+
+	meta, err := h.readSessionMeta(metaPath, sessionKey)
+	if err != nil {
+		return sessionFile{}, err
+	}
+
+	messages, err := h.readSessionMessages(jsonlPath, meta.Skip)
+	if err != nil {
+		return sessionFile{}, err
+	}
+
+	updated := meta.UpdatedAt
+	created := meta.CreatedAt
+	if created.IsZero() || updated.IsZero() {
+		if info, statErr := os.Stat(jsonlPath); statErr == nil {
+			if created.IsZero() {
+				created = info.ModTime()
+			}
+			if updated.IsZero() {
+				updated = info.ModTime()
+			}
+		}
+	}
+
+	return sessionFile{
+		Key:      meta.Key,
+		Messages: messages,
+		Summary:  meta.Summary,
+		Created:  created,
+		Updated:  updated,
+	}, nil
+}
+
+func buildSessionListItem(sessionID string, sess sessionFile) sessionListItem {
+	preview := ""
+	for _, msg := range sess.Messages {
+		if msg.Role == "user" && strings.TrimSpace(msg.Content) != "" {
+			preview = msg.Content
+			break
+		}
+	}
+	title := strings.TrimSpace(sess.Summary)
+	if title == "" {
+		title = preview
+	}
+
+	title = truncateRunes(title, maxSessionTitleRunes)
+	preview = truncateRunes(preview, maxSessionTitleRunes)
+
+	if preview == "" {
+		preview = "(empty)"
+	}
+	if title == "" {
+		title = preview
+	}
+
+	validMessageCount := 0
+	for _, msg := range sess.Messages {
+		if (msg.Role == "user" || msg.Role == "assistant") && strings.TrimSpace(msg.Content) != "" {
+			validMessageCount++
+		}
+	}
+
+	return sessionListItem{
+		ID:           sessionID,
+		Title:        title,
+		Preview:      preview,
+		MessageCount: validMessageCount,
+		Created:      sess.Created.Format(time.RFC3339),
+		Updated:      sess.Updated.Format(time.RFC3339),
+	}
+}
+
+func isEmptySession(sess sessionFile) bool {
+	return len(sess.Messages) == 0 && strings.TrimSpace(sess.Summary) == ""
+}
+
+func truncateRunes(s string, maxLen int) string {
+	if maxLen <= 0 {
+		return ""
+	}
+	runes := []rune(strings.TrimSpace(s))
+	if len(runes) <= maxLen {
+		return string(runes)
+	}
+	return string(runes[:maxLen]) + "..."
+}
+
 // sessionsDir resolves the path to the gateway's session storage directory.
 // It reads the workspace from config, falling back to ~/.picoclaw/workspace.
 func (h *Handler) sessionsDir() (string, error) {
@@ -104,58 +293,76 @@ func (h *Handler) handleListSessions(w http.ResponseWriter, r *http.Request) {
 	}
 
 	items := []sessionListItem{}
+	seen := make(map[string]struct{})
 
 	for _, entry := range entries {
-		if entry.IsDir() || filepath.Ext(entry.Name()) != ".json" {
+		if entry.IsDir() {
 			continue
 		}
 
-		data, err := os.ReadFile(filepath.Join(dir, entry.Name()))
+		name := entry.Name()
-		if err != nil {
+		var (
-			continue
+			sessionID string
-		}
+			sess      sessionFile
+			loadErr   error
+			ok        bool
+		)
 
-		var sess sessionFile
+		switch {
-		if err := json.Unmarshal(data, &sess); err != nil {
+		case strings.HasSuffix(name, ".jsonl"):
-			continue
+			sessionID, ok = extractPicoSessionIDFromSanitizedKey(strings.TrimSuffix(name, ".jsonl"))
-		}
-
-		// Only include Pico channel sessions
-		sessionID, ok := extractPicoSessionID(sess.Key)
 			if !ok {
 				continue
 			}
-
+			sess, loadErr = h.readJSONLSession(dir, sessionID)
-		// Build a preview from the first user message
+			if loadErr == nil && isEmptySession(sess) {
-		preview := ""
+				continue
-		for _, msg := range sess.Messages {
+			}
-			if msg.Role == "user" && strings.TrimSpace(msg.Content) != "" {
+		case strings.HasSuffix(name, ".meta.json"):
-				preview = msg.Content
+			continue
-				break
+		case filepath.Ext(name) == ".json":
+			base := strings.TrimSuffix(name, ".json")
+			if _, statErr := os.Stat(filepath.Join(dir, base+".jsonl")); statErr == nil {
+				if jsonlSessionID, found := extractPicoSessionIDFromSanitizedKey(base); found {
+					if jsonlSess, jsonlErr := h.readJSONLSession(
+						dir,
+						jsonlSessionID,
+					); jsonlErr == nil &&
+						!isEmptySession(jsonlSess) {
+						continue
 					}
 				}
-		if len([]rune(preview)) > 60 {
-			preview = string([]rune(preview)[:60]) + "..."
 			}
-		if preview == "" {
+			data, err := os.ReadFile(filepath.Join(dir, name))
-			preview = "(empty)"
+			if err != nil {
+				continue
+			}
+			if err := json.Unmarshal(data, &sess); err != nil {
+				continue
+			}
+			if isEmptySession(sess) {
+				continue
+			}
+			sessionID, ok = extractPicoSessionID(sess.Key)
+			if !ok {
+				continue
+			}
+			if _, exists := seen[sessionID]; exists {
+				continue
+			}
+		default:
+			continue
 		}
 
-		// Only count non-empty user and assistant messages
+		if loadErr != nil {
-		validMessageCount := 0
+			continue
-		for _, msg := range sess.Messages {
-			if (msg.Role == "user" || msg.Role == "assistant") && strings.TrimSpace(msg.Content) != "" {
-				validMessageCount++
 		}
+		if _, exists := seen[sessionID]; exists {
+			continue
 		}
 
-		items = append(items, sessionListItem{
+		seen[sessionID] = struct{}{}
-			ID:           sessionID,
+		items = append(items, buildSessionListItem(sessionID, sess))
-			Preview:      preview,
-			MessageCount: validMessageCount,
-			Created:      sess.Created.Format(time.RFC3339),
-			Updated:      sess.Updated.Format(time.RFC3339),
-		})
 	}
 
 	// Sort by updated descending (most recent first)
@@ -209,20 +416,25 @@ func (h *Handler) handleGetSession(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// The sanitized filename replaces ':' with '_':
+	sess, err := h.readJSONLSession(dir, sessionID)
-	// agent:main:pico:direct:pico:<uuid> -> agent_main_pico_direct_pico_<uuid>.json
+	if err == nil && isEmptySession(sess) {
-	filename := strings.ReplaceAll(picoSessionPrefix+sessionID, ":", "_") + ".json"
+		err = os.ErrNotExist
-
+	}
-	data, err := os.ReadFile(filepath.Join(dir, filename))
 	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			sess, err = h.readLegacySession(dir, sessionID)
+			if err == nil && isEmptySession(sess) {
+				err = os.ErrNotExist
+			}
+		}
+		if err != nil {
+			if errors.Is(err, os.ErrNotExist) {
 				http.Error(w, "session not found", http.StatusNotFound)
+			} else {
+				http.Error(w, "failed to parse session", http.StatusInternalServerError)
+			}
 			return
 		}
-
-	var sess sessionFile
-	if err := json.Unmarshal(data, &sess); err != nil {
-		http.Error(w, "failed to parse session", http.StatusInternalServerError)
-		return
 	}
 
 	// Convert to a simpler format for the frontend
@@ -268,17 +480,25 @@ func (h *Handler) handleDeleteSession(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// The sanitized filename replaces ':' with '_':
+	base := filepath.Join(dir, sanitizeSessionKey(picoSessionPrefix+sessionID))
-	// agent:main:pico:direct:pico:<uuid> -> agent_main_pico_direct_pico_<uuid>.json
+	jsonlPath := base + ".jsonl"
-	filename := strings.ReplaceAll(picoSessionPrefix+sessionID, ":", "_") + ".json"
+	metaPath := base + ".meta.json"
-	filePath := filepath.Join(dir, filename)
+	legacyPath := base + ".json"
 
-	if err := os.Remove(filePath); err != nil {
+	removed := false
+	for _, path := range []string{jsonlPath, metaPath, legacyPath} {
+		if err := os.Remove(path); err != nil {
 			if os.IsNotExist(err) {
-			http.Error(w, "session not found", http.StatusNotFound)
+				continue
-		} else {
-			http.Error(w, "failed to delete session", http.StatusInternalServerError)
 			}
+			http.Error(w, "failed to delete session", http.StatusInternalServerError)
+			return
+		}
+		removed = true
+	}
+
+	if !removed {
+		http.Error(w, "session not found", http.StatusNotFound)
 		return
 	}
 

web/backend/api/session_test.go

@@ -0,0 +1,322 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/memory"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/session"
+)
+
+func sessionsTestDir(t *testing.T, configPath string) string {
+	t.Helper()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	dir := filepath.Join(cfg.Agents.Defaults.Workspace, "sessions")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatalf("MkdirAll() error = %v", err)
+	}
+	return dir
+}
+
+func TestHandleListSessions_JSONLStorage(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	store, err := memory.NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore() error = %v", err)
+	}
+
+	sessionKey := picoSessionPrefix + "history-jsonl"
+	if err := store.AddFullMessage(nil, sessionKey, providers.Message{
+		Role:    "user",
+		Content: "Explain why the history API is empty after migration.",
+	}); err != nil {
+		t.Fatalf("AddFullMessage(user) error = %v", err)
+	}
+	if err := store.AddFullMessage(nil, sessionKey, providers.Message{
+		Role:    "assistant",
+		Content: "Because the API still reads only legacy JSON session files.",
+	}); err != nil {
+		t.Fatalf("AddFullMessage(assistant) error = %v", err)
+	}
+	if err := store.AddFullMessage(nil, sessionKey, providers.Message{
+		Role:    "tool",
+		Content: "ignored",
+	}); err != nil {
+		t.Fatalf("AddFullMessage(tool) error = %v", err)
+	}
+	if err := store.SetSummary(nil, sessionKey, "JSONL-backed session"); err != nil {
+		t.Fatalf("SetSummary() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/sessions", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var items []sessionListItem
+	if err := json.Unmarshal(rec.Body.Bytes(), &items); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if len(items) != 1 {
+		t.Fatalf("len(items) = %d, want 1", len(items))
+	}
+	if items[0].ID != "history-jsonl" {
+		t.Fatalf("items[0].ID = %q, want %q", items[0].ID, "history-jsonl")
+	}
+	if items[0].MessageCount != 2 {
+		t.Fatalf("items[0].MessageCount = %d, want 2", items[0].MessageCount)
+	}
+	if items[0].Title != "JSONL-backed session" {
+		t.Fatalf("items[0].Title = %q, want %q", items[0].Title, "JSONL-backed session")
+	}
+	if items[0].Preview != "Explain why the history API is empty after migration." {
+		t.Fatalf("items[0].Preview = %q", items[0].Preview)
+	}
+}
+
+func TestHandleListSessions_TitleUsesTrimmedSummary(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	store, err := memory.NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore() error = %v", err)
+	}
+
+	sessionKey := picoSessionPrefix + "summary-title"
+	if err := store.AddFullMessage(nil, sessionKey, providers.Message{
+		Role:    "user",
+		Content: "fallback preview",
+	}); err != nil {
+		t.Fatalf("AddFullMessage() error = %v", err)
+	}
+	if err := store.SetSummary(
+		nil,
+		sessionKey,
+		"  This summary is intentionally longer than sixty characters so it must be truncated in the history menu.  ",
+	); err != nil {
+		t.Fatalf("SetSummary() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/sessions", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var items []sessionListItem
+	if err := json.Unmarshal(rec.Body.Bytes(), &items); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if len(items) != 1 {
+		t.Fatalf("len(items) = %d, want 1", len(items))
+	}
+	expectedTitle := truncateRunes(
+		"This summary is intentionally longer than sixty characters so it must be truncated in the history menu.",
+		maxSessionTitleRunes,
+	)
+	if items[0].Title != expectedTitle {
+		t.Fatalf("items[0].Title = %q", items[0].Title)
+	}
+	if items[0].Preview != "fallback preview" {
+		t.Fatalf("items[0].Preview = %q, want %q", items[0].Preview, "fallback preview")
+	}
+}
+
+func TestHandleGetSession_JSONLStorage(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	store, err := memory.NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore() error = %v", err)
+	}
+
+	sessionKey := picoSessionPrefix + "detail-jsonl"
+	for _, msg := range []providers.Message{
+		{Role: "user", Content: "first"},
+		{Role: "assistant", Content: "second"},
+		{Role: "tool", Content: "ignored"},
+	} {
+		if err := store.AddFullMessage(nil, sessionKey, msg); err != nil {
+			t.Fatalf("AddFullMessage() error = %v", err)
+		}
+	}
+	if err := store.SetSummary(nil, sessionKey, "detail summary"); err != nil {
+		t.Fatalf("SetSummary() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/sessions/detail-jsonl", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp struct {
+		ID       string `json:"id"`
+		Summary  string `json:"summary"`
+		Messages []struct {
+			Role    string `json:"role"`
+			Content string `json:"content"`
+		} `json:"messages"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if resp.ID != "detail-jsonl" {
+		t.Fatalf("resp.ID = %q, want %q", resp.ID, "detail-jsonl")
+	}
+	if resp.Summary != "detail summary" {
+		t.Fatalf("resp.Summary = %q, want %q", resp.Summary, "detail summary")
+	}
+	if len(resp.Messages) != 2 {
+		t.Fatalf("len(resp.Messages) = %d, want 2", len(resp.Messages))
+	}
+	if resp.Messages[0].Role != "user" || resp.Messages[0].Content != "first" {
+		t.Fatalf("first message = %#v, want user/first", resp.Messages[0])
+	}
+	if resp.Messages[1].Role != "assistant" || resp.Messages[1].Content != "second" {
+		t.Fatalf("second message = %#v, want assistant/second", resp.Messages[1])
+	}
+}
+
+func TestHandleDeleteSession_JSONLStorage(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	store, err := memory.NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore() error = %v", err)
+	}
+
+	sessionKey := picoSessionPrefix + "delete-jsonl"
+	if err := store.AddFullMessage(nil, sessionKey, providers.Message{
+		Role:    "user",
+		Content: "delete me",
+	}); err != nil {
+		t.Fatalf("AddFullMessage() error = %v", err)
+	}
+	if err := store.SetSummary(nil, sessionKey, "delete summary"); err != nil {
+		t.Fatalf("SetSummary() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodDelete, "/api/sessions/delete-jsonl", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusNoContent {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusNoContent, rec.Body.String())
+	}
+
+	base := filepath.Join(dir, sanitizeSessionKey(sessionKey))
+	for _, path := range []string{base + ".jsonl", base + ".meta.json"} {
+		if _, err := os.Stat(path); !os.IsNotExist(err) {
+			t.Fatalf("expected %s to be removed, stat err = %v", path, err)
+		}
+	}
+}
+
+func TestHandleGetSession_LegacyJSONFallback(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	manager := session.NewSessionManager(dir)
+	sessionKey := picoSessionPrefix + "legacy-json"
+	manager.AddMessage(sessionKey, "user", "legacy user")
+	manager.AddMessage(sessionKey, "assistant", "legacy assistant")
+	if err := manager.Save(sessionKey); err != nil {
+		t.Fatalf("Save() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/sessions/legacy-json", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+}
+
+func TestHandleSessions_FiltersEmptyJSONLFiles(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	base := filepath.Join(dir, sanitizeSessionKey(picoSessionPrefix+"empty-jsonl"))
+	if err := os.WriteFile(base+".jsonl", []byte{}, 0o644); err != nil {
+		t.Fatalf("WriteFile(jsonl) error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	listRec := httptest.NewRecorder()
+	listReq := httptest.NewRequest(http.MethodGet, "/api/sessions", nil)
+	mux.ServeHTTP(listRec, listReq)
+
+	if listRec.Code != http.StatusOK {
+		t.Fatalf("list status = %d, want %d, body=%s", listRec.Code, http.StatusOK, listRec.Body.String())
+	}
+
+	var items []sessionListItem
+	if err := json.Unmarshal(listRec.Body.Bytes(), &items); err != nil {
+		t.Fatalf("Unmarshal(list) error = %v", err)
+	}
+	if len(items) != 0 {
+		t.Fatalf("len(items) = %d, want 0", len(items))
+	}
+
+	detailRec := httptest.NewRecorder()
+	detailReq := httptest.NewRequest(http.MethodGet, "/api/sessions/empty-jsonl", nil)
+	mux.ServeHTTP(detailRec, detailReq)
+
+	if detailRec.Code != http.StatusNotFound {
+		t.Fatalf("detail status = %d, want %d, body=%s", detailRec.Code, http.StatusNotFound, detailRec.Body.String())
+	}
+}

web/backend/main.go

@@ -25,6 +25,7 @@ import (
 	"github.com/sipeed/picoclaw/web/backend/api"
 	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
 	"github.com/sipeed/picoclaw/web/backend/middleware"
+	"github.com/sipeed/picoclaw/web/backend/utils"
 )
 
 func main() {
@@ -51,7 +52,7 @@ func main() {
 	flag.Parse()
 
 	// Resolve config path
-	configPath := getDefaultConfigPath()
+	configPath := utils.GetDefaultConfigPath()
 	if flag.NArg() > 0 {
 		configPath = flag.Arg(0)
 	}
@@ -60,6 +61,10 @@ func main() {
 	if err != nil {
 		log.Fatalf("Failed to resolve config path: %v", err)
 	}
+	err = utils.EnsureOnboarded(absPath)
+	if err != nil {
+		log.Printf("Warning: Failed to initialize PicoClaw config automatically: %v", err)
+	}
 
 	var explicitPort bool
 	var explicitPublic bool
@@ -109,7 +114,7 @@ func main() {
 
 	// API Routes (e.g. /api/status)
 	apiHandler := api.NewHandler(absPath)
-	apiHandler.SetServerOptions(portNum, effectivePublic, launcherCfg.AllowedCIDRs)
+	apiHandler.SetServerOptions(portNum, effectivePublic, explicitPublic, launcherCfg.AllowedCIDRs)
 	apiHandler.RegisterRoutes(mux)
 
 	// Frontend Embedded Assets
@@ -128,13 +133,13 @@ func main() {
 	)
 
 	// Print startup banner
-	fmt.Print(banner)
+	fmt.Print(utils.Banner)
 	fmt.Println()
 	fmt.Println("  Open the following URL in your browser:")
 	fmt.Println()
 	fmt.Printf("    >> http://localhost:%s <<\n", effectivePort)
 	if effectivePublic {
-		if ip := getLocalIP(); ip != "" {
+		if ip := utils.GetLocalIP(); ip != "" {
 			fmt.Printf("    >> http://%s:%s <<\n", ip, effectivePort)
 		}
 	}
@@ -145,7 +150,7 @@ func main() {
 		go func() {
 			time.Sleep(500 * time.Millisecond)
 			url := "http://localhost:" + effectivePort
-			if err := openBrowser(url); err != nil {
+			if err := utils.OpenBrowser(url); err != nil {
 				log.Printf("Warning: Failed to auto-open browser: %v", err)
 			}
 		}()

web/backend/utils/banner.go

@@ -1,19 +1,10 @@
-package main
+package utils
-
-import (
-	"fmt"
-	"net"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-)
 
 const (
 	colorBlue  = "\x1b[38;2;62;93;185m"
 	colorRed   = "\x1b[38;2;213;70;70m"
 	colorReset = "\x1b[0m"
-	banner     = "\r\n" +
+	Banner     = "\r\n" +
 		colorBlue + "██████╗ ██╗ ██████╗ ██████╗ " + colorRed + " ██████╗██╗      █████╗ ██╗    ██╗\n" +
 		colorBlue + "██╔══██╗██║██╔════╝██╔═══██╗" + colorRed + "██╔════╝██║     ██╔══██╗██║    ██║\n" +
 		colorBlue + "██████╔╝██║██║     ██║   ██║" + colorRed + "██║     ██║     ███████║██║ █╗ ██║\n" +
@@ -22,40 +13,3 @@ const (
 		colorBlue + "╚═╝     ╚═╝ ╚═════╝ ╚═════╝ " + colorRed + " ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝\n" +
 		colorReset
 )
-
-// getDefaultConfigPath returns the default path to the picoclaw config file.
-func getDefaultConfigPath() string {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return "config.json"
-	}
-	return filepath.Join(home, ".picoclaw", "config.json")
-}
-
-// getLocalIP returns the local IP address of the machine.
-func getLocalIP() string {
-	addrs, err := net.InterfaceAddrs()
-	if err != nil {
-		return ""
-	}
-	for _, a := range addrs {
-		if ipnet, ok := a.(*net.IPNet); ok && !ipnet.IP.IsLoopback() && ipnet.IP.To4() != nil {
-			return ipnet.IP.String()
-		}
-	}
-	return ""
-}
-
-// openBrowser automatically opens the given URL in the default browser.
-func openBrowser(url string) error {
-	switch runtime.GOOS {
-	case "linux":
-		return exec.Command("xdg-open", url).Start()
-	case "windows":
-		return exec.Command("rundll32", "url.dll,FileProtocolHandler", url).Start()
-	case "darwin":
-		return exec.Command("open", url).Start()
-	default:
-		return fmt.Errorf("unsupported platform")
-	}
-}

web/backend/utils/onboard.go

@@ -0,0 +1,42 @@
+package utils
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+)
+
+var execCommand = exec.Command
+
+func EnsureOnboarded(configPath string) error {
+	_, err := os.Stat(configPath)
+	if err == nil {
+		return nil
+	}
+	if !os.IsNotExist(err) {
+		return fmt.Errorf("stat config: %w", err)
+	}
+
+	cmd := execCommand(FindPicoclawBinary(), "onboard")
+	cmd.Env = append(os.Environ(), "PICOCLAW_CONFIG="+configPath)
+	cmd.Stdin = strings.NewReader("n\n")
+
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		trimmed := strings.TrimSpace(string(output))
+		if trimmed == "" {
+			return fmt.Errorf("run onboard: %w", err)
+		}
+		return fmt.Errorf("run onboard: %w: %s", err, trimmed)
+	}
+
+	if _, err := os.Stat(configPath); err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf("onboard completed but did not create config %s", configPath)
+		}
+		return fmt.Errorf("verify config after onboard: %w", err)
+	}
+
+	return nil
+}

web/backend/utils/onboard_test.go

@@ -0,0 +1,101 @@
+package utils
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestEnsureOnboardedSkipsWhenConfigExists(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(configPath, []byte(`{}`), 0o644); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	origExecCommand := execCommand
+	defer func() { execCommand = origExecCommand }()
+
+	called := false
+	execCommand = func(name string, args ...string) *exec.Cmd {
+		called = true
+		return exec.Command("sh", "-c", "exit 1")
+	}
+
+	if err := EnsureOnboarded(configPath); err != nil {
+		t.Fatalf("EnsureOnboarded() error = %v", err)
+	}
+	if called {
+		t.Fatal("expected onboard command not to run when config already exists")
+	}
+}
+
+func TestEnsureOnboardedRunsOnboardWhenConfigMissing(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	t.Setenv("EXPECTED_CONFIG_PATH", configPath)
+
+	origExecCommand := execCommand
+	defer func() { execCommand = origExecCommand }()
+
+	var gotName string
+	var gotArgs []string
+	execCommand = func(name string, args ...string) *exec.Cmd {
+		gotName = name
+		gotArgs = append([]string(nil), args...)
+		return exec.Command(
+			"sh",
+			"-c",
+			`test "$PICOCLAW_CONFIG" = "$EXPECTED_CONFIG_PATH" &&
+mkdir -p "$(dirname "$PICOCLAW_CONFIG")" &&
+printf '{}' > "$PICOCLAW_CONFIG"`,
+		)
+	}
+
+	if err := EnsureOnboarded(configPath); err != nil {
+		t.Fatalf("EnsureOnboarded() error = %v", err)
+	}
+	if gotName == "" {
+		t.Fatal("expected onboard command to run")
+	}
+	if len(gotArgs) != 1 || gotArgs[0] != "onboard" {
+		t.Fatalf("command args = %#v, want []string{\"onboard\"}", gotArgs)
+	}
+	if _, err := os.Stat(configPath); err != nil {
+		t.Fatalf("expected config to be created: %v", err)
+	}
+}
+
+func TestEnsureOnboardedFailsWhenOnboardDoesNotCreateConfig(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+
+	origExecCommand := execCommand
+	defer func() { execCommand = origExecCommand }()
+
+	execCommand = func(name string, args ...string) *exec.Cmd {
+		return exec.Command("sh", "-c", "exit 0")
+	}
+
+	if err := EnsureOnboarded(configPath); err == nil {
+		t.Fatal("EnsureOnboarded() error = nil, want failure when onboard does not create config")
+	}
+}
+
+func TestEnsureOnboardedIncludesOnboardOutputOnFailure(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+
+	origExecCommand := execCommand
+	defer func() { execCommand = origExecCommand }()
+
+	execCommand = func(name string, args ...string) *exec.Cmd {
+		return exec.Command("sh", "-c", "echo onboarding failed >&2; exit 2")
+	}
+
+	err := EnsureOnboarded(configPath)
+	if err == nil {
+		t.Fatal("EnsureOnboarded() error = nil, want failure")
+	}
+	if !strings.Contains(err.Error(), "onboarding failed") {
+		t.Fatalf("error = %q, want onboard output included", err)
+	}
+}

web/backend/utils/runtime.go

@@ -0,0 +1,80 @@
+package utils
+
+import (
+	"fmt"
+	"net"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+)
+
+// GetDefaultConfigPath returns the default path to the picoclaw config file.
+func GetDefaultConfigPath() string {
+	if configPath := os.Getenv("PICOCLAW_CONFIG"); configPath != "" {
+		return configPath
+	}
+	if picoclawHome := os.Getenv("PICOCLAW_HOME"); picoclawHome != "" {
+		return filepath.Join(picoclawHome, "config.json")
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "config.json"
+	}
+	return filepath.Join(home, ".picoclaw", "config.json")
+}
+
+// FindPicoclawBinary locates the picoclaw executable.
+// Search order:
+//  1. PICOCLAW_BINARY environment variable (explicit override)
+//  2. Same directory as the current executable
+//  3. Falls back to "picoclaw" and relies on $PATH
+func FindPicoclawBinary() string {
+	binaryName := "picoclaw"
+	if runtime.GOOS == "windows" {
+		binaryName = "picoclaw.exe"
+	}
+
+	if p := os.Getenv("PICOCLAW_BINARY"); p != "" {
+		if info, _ := os.Stat(p); info != nil && !info.IsDir() {
+			return p
+		}
+	}
+
+	if exe, err := os.Executable(); err == nil {
+		candidate := filepath.Join(filepath.Dir(exe), binaryName)
+		if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
+			return candidate
+		}
+	}
+
+	return "picoclaw"
+}
+
+// GetLocalIP returns the local IP address of the machine.
+func GetLocalIP() string {
+	addrs, err := net.InterfaceAddrs()
+	if err != nil {
+		return ""
+	}
+	for _, a := range addrs {
+		if ipnet, ok := a.(*net.IPNet); ok && !ipnet.IP.IsLoopback() && ipnet.IP.To4() != nil {
+			return ipnet.IP.String()
+		}
+	}
+	return ""
+}
+
+// OpenBrowser automatically opens the given URL in the default browser.
+func OpenBrowser(url string) error {
+	switch runtime.GOOS {
+	case "linux":
+		return exec.Command("xdg-open", url).Start()
+	case "windows":
+		return exec.Command("rundll32", "url.dll,FileProtocolHandler", url).Start()
+	case "darwin":
+		return exec.Command("open", url).Start()
+	default:
+		return fmt.Errorf("unsupported platform")
+	}
+}

web/frontend/src/api/gateway.ts

@@ -14,6 +14,8 @@ interface GatewayStatusResponse {
 interface GatewayActionResponse {
   status: string
   pid?: number
+  log_total?: number
+  log_run_id?: number
 }
 
 const BASE_URL = ""
@@ -59,4 +61,10 @@ export async function restartGateway(): Promise<GatewayActionResponse> {
   })
 }
 
+export async function clearGatewayLogs(): Promise<GatewayActionResponse> {
+  return request<GatewayActionResponse>("/api/gateway/logs/clear", {
+    method: "POST",
+  })
+}
+
 export type { GatewayStatusResponse, GatewayActionResponse }

web/frontend/src/api/sessions.ts

@@ -2,6 +2,7 @@
 
 export interface SessionSummary {
   id: string
+  title: string
   preview: string
   message_count: number
   created: string

web/frontend/src/components/chat/chat-page.tsx

@@ -43,8 +43,15 @@ export function ChatPage() {
     handleSetDefault,
   } = useChatModels({ isConnected })
 
-  const { sessions, hasMore, observerRef, loadSessions, handleDeleteSession } =
+  const {
-    useSessionHistory({
+    sessions,
+    hasMore,
+    loadError,
+    loadErrorMessage,
+    observerRef,
+    loadSessions,
+    handleDeleteSession,
+  } = useSessionHistory({
     activeSessionId,
     onDeletedActiveSession: newChat,
   })
@@ -96,6 +103,8 @@ export function ChatPage() {
           sessions={sessions}
           activeSessionId={activeSessionId}
           hasMore={hasMore}
+          loadError={loadError}
+          loadErrorMessage={loadErrorMessage}
           observerRef={observerRef}
           onOpenChange={(open) => {
             if (open) {

web/frontend/src/components/chat/session-history-menu.tsx

@@ -17,6 +17,8 @@ interface SessionHistoryMenuProps {
   sessions: SessionSummary[]
   activeSessionId: string
   hasMore: boolean
+  loadError: boolean
+  loadErrorMessage: string
   observerRef: RefObject<HTMLDivElement | null>
   onOpenChange: (open: boolean) => void
   onSwitchSession: (sessionId: string) => void
@@ -27,6 +29,8 @@ export function SessionHistoryMenu({
   sessions,
   activeSessionId,
   hasMore,
+  loadError,
+  loadErrorMessage,
   observerRef,
   onOpenChange,
   onSwitchSession,
@@ -44,7 +48,14 @@ export function SessionHistoryMenu({
       </DropdownMenuTrigger>
       <DropdownMenuContent align="end" className="w-72">
         <ScrollArea className="max-h-[300px]">
-          {sessions.length === 0 ? (
+          {loadError && (
+            <DropdownMenuItem disabled>
+              <span className="text-destructive text-xs">
+                {loadErrorMessage}
+              </span>
+            </DropdownMenuItem>
+          )}
+          {sessions.length === 0 && !loadError ? (
             <DropdownMenuItem disabled>
               <span className="text-muted-foreground text-xs">
                 {t("chat.noHistory")}
@@ -60,7 +71,7 @@ export function SessionHistoryMenu({
                 onClick={() => onSwitchSession(session.id)}
               >
                 <span className="line-clamp-1 text-sm font-medium">
-                  {session.preview}
+                  {session.title || session.preview}
                 </span>
                 <span className="text-muted-foreground text-xs">
                   {t("chat.messagesCount", {

web/frontend/src/hooks/use-pico-chat.ts

@@ -1,6 +1,8 @@
 import dayjs from "dayjs"
 import { useAtomValue } from "jotai"
 import { useCallback, useEffect, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+import { toast } from "sonner"
 
 import { getPicoToken } from "@/api/pico"
 import { getSessionHistory } from "@/api/sessions"
@@ -100,6 +102,7 @@ export function formatMessageTime(dateRaw: number | string | Date): string {
 }
 
 export function usePicoChat() {
+  const { t } = useTranslation()
   const { status: gatewayState } = useAtomValue(gatewayAtom)
   const [messages, setMessages] = useState<ChatMessage[]>([])
   const [connectionState, setConnectionState] =
@@ -317,43 +320,38 @@ export function usePicoChat() {
   // Switch to a historical session
   const switchSession = useCallback(
     async (sessionId: string) => {
-      // Disconnect current WebSocket
+      if (sessionId === activeSessionIdRef.current) {
-      disconnect()
+        return
+      }
 
-      // Set new session ID
-      setActiveSessionId(sessionId)
-      setIsTyping(false)
-
-      // Load history from backend
       try {
         const detail = await getSessionHistory(sessionId)
-        // Set all history messages timestamp from the session updated time as fallback,
-        // since currently the backend doesn't return per-message timestamp in the history API.
-        // We'll use the session's updated time for now.
         const fallbackTime = detail.updated
-
+        const historyMessages = detail.messages.map((m, i) => ({
-        setMessages(
-          detail.messages.map((m, i) => ({
           id: `hist-${i}-${Date.now()}`,
           role: m.role as "user" | "assistant",
           content: m.content,
           timestamp: fallbackTime,
-          })),
+        }))
-        )
+
+        // Only switch the active websocket session after history has loaded successfully.
+        disconnect()
+        setActiveSessionId(sessionId)
+        setIsTyping(false)
+        setMessages(historyMessages)
       } catch (err) {
         console.error("Failed to load session history:", err)
-        setMessages([])
+        toast.error(t("chat.historyOpenFailed"))
+        return
       }
 
-      // Reconnect with new session ID (will use the updated ref)
-      // Small delay to ensure state has settled
       setTimeout(() => {
         if (gatewayState === "running") {
           connect()
         }
       }, 100)
     },
-    [disconnect, connect, gatewayState],
+    [connect, disconnect, gatewayState, t],
   )
 
   // Start a new empty chat

web/frontend/src/hooks/use-session-history.ts

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
 
 import { type SessionSummary, deleteSession, getSessions } from "@/api/sessions"
 
@@ -13,22 +14,26 @@ export function useSessionHistory({
   activeSessionId,
   onDeletedActiveSession,
 }: UseSessionHistoryOptions) {
+  const { t } = useTranslation()
   const observerRef = useRef<HTMLDivElement>(null)
   const [sessions, setSessions] = useState<SessionSummary[]>([])
   const [offset, setOffset] = useState(0)
   const [hasMore, setHasMore] = useState(true)
   const [isLoadingMore, setIsLoadingMore] = useState(false)
+  const [loadError, setLoadError] = useState(false)
 
   const loadSessions = useCallback(
     async (reset = true) => {
       try {
         const currentOffset = reset ? 0 : offset
         if (reset) {
+          setLoadError(false)
           setHasMore(true)
           setOffset(0)
         }
 
         const data = await getSessions(currentOffset, LIMIT)
+        setLoadError(false)
 
         if (data.length < LIMIT) {
           setHasMore(false)
@@ -45,8 +50,12 @@ export function useSessionHistory({
         }
 
         setOffset(currentOffset + data.length)
-      } catch {
+      } catch (err) {
-        // silently fail
+        console.error("Failed to fetch session history:", err)
+        setLoadError(true)
+        if (!reset) {
+          setHasMore(false)
+        }
       } finally {
         setIsLoadingMore(false)
       }
@@ -55,11 +64,16 @@ export function useSessionHistory({
   )
 
   useEffect(() => {
-    if (!observerRef.current || !hasMore || isLoadingMore) return
+    if (!observerRef.current || !hasMore || isLoadingMore || loadError) return
 
     const observer = new IntersectionObserver(
       (entries) => {
-        if (entries[0].isIntersecting && hasMore && !isLoadingMore) {
+        if (
+          entries[0].isIntersecting &&
+          hasMore &&
+          !isLoadingMore &&
+          !loadError
+        ) {
           setIsLoadingMore(true)
           void loadSessions(false)
         }
@@ -69,7 +83,7 @@ export function useSessionHistory({
 
     observer.observe(observerRef.current)
     return () => observer.disconnect()
-  }, [hasMore, isLoadingMore, loadSessions])
+  }, [hasMore, isLoadingMore, loadError, loadSessions])
 
   const handleDeleteSession = useCallback(
     async (id: string) => {
@@ -89,6 +103,8 @@ export function useSessionHistory({
   return {
     sessions,
     hasMore,
+    loadError,
+    loadErrorMessage: t("chat.historyLoadFailed"),
     observerRef,
     loadSessions,
     handleDeleteSession,

web/frontend/src/i18n/locales/en.json

@@ -25,6 +25,8 @@
     },
     "history": "History",
     "noHistory": "No chat history yet",
+    "historyLoadFailed": "Failed to load chat history",
+    "historyOpenFailed": "Failed to open this chat history",
     "loadingMore": "Loading more...",
     "deleteSession": "Delete session",
     "messagesCount": "{{count}} messages",
@@ -387,7 +389,9 @@
       "unsaved_changes": "You have unsaved changes."
     },
     "logs": {
-      "description": "System logs and monitoring."
+      "description": "System logs and monitoring.",
+      "clear": "Clear logs",
+      "empty": "Waiting for logs..."
     }
   }
 }

web/frontend/src/i18n/locales/zh.json

@@ -25,6 +25,8 @@
     },
     "history": "历史记录",
     "noHistory": "暂无对话历史",
+    "historyLoadFailed": "加载历史记录失败",
+    "historyOpenFailed": "打开该历史会话失败",
     "loadingMore": "加载更多...",
     "deleteSession": "删除会话",
     "messagesCount": "{{count}} 条消息",
@@ -387,7 +389,9 @@
       "unsaved_changes": "您有未保存的更改。"
     },
     "logs": {
-      "description": "系统日志和监控。"
+      "description": "系统日志和监控。",
+      "clear": "清空日志",
+      "empty": "等待日志中..."
     }
   }
 }

web/frontend/src/routes/logs.tsx

@@ -1,10 +1,12 @@
+import { IconTrash } from "@tabler/icons-react"
 import { createFileRoute } from "@tanstack/react-router"
 import { useAtomValue } from "jotai"
 import { useEffect, useRef, useState } from "react"
 import { useTranslation } from "react-i18next"
 
-import { getGatewayStatus } from "@/api/gateway"
+import { clearGatewayLogs, getGatewayStatus } from "@/api/gateway"
 import { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
 import { ScrollArea } from "@/components/ui/scroll-area"
 import { gatewayAtom } from "@/store/gateway"
 
@@ -15,12 +17,31 @@ export const Route = createFileRoute("/logs")({
 function LogsPage() {
   const { t } = useTranslation()
   const [logs, setLogs] = useState<string[]>([])
+  const [clearing, setClearing] = useState(false)
   const logOffsetRef = useRef<number>(0)
   const logRunIdRef = useRef<number>(-1)
+  const syncTokenRef = useRef<number>(0)
   const scrollRef = useRef<HTMLDivElement>(null)
 
   const gateway = useAtomValue(gatewayAtom)
 
+  const handleClearLogs = async () => {
+    setClearing(true)
+    try {
+      const data = await clearGatewayLogs()
+      syncTokenRef.current += 1
+      setLogs([])
+      logOffsetRef.current = data.log_total ?? 0
+      if (data.log_run_id !== undefined) {
+        logRunIdRef.current = data.log_run_id
+      }
+    } catch {
+      // Ignore clear failures silently to avoid noisy transient errors.
+    } finally {
+      setClearing(false)
+    }
+  }
+
   useEffect(() => {
     let mounted = true
     let timeout: ReturnType<typeof setTimeout>
@@ -40,17 +61,17 @@ function LogsPage() {
       }
 
       try {
+        const requestToken = syncTokenRef.current
+        const requestOffset = logOffsetRef.current
+        const requestRunId = logRunIdRef.current
         const data = await getGatewayStatus({
-          log_offset: logOffsetRef.current,
+          log_offset: requestOffset,
-          log_run_id: logRunIdRef.current,
+          log_run_id: requestRunId,
         })
 
-        if (!mounted) return
+        if (!mounted || requestToken !== syncTokenRef.current) return
 
-        if (
+        if (data.log_run_id !== undefined && data.log_run_id !== requestRunId) {
-          data.log_run_id !== undefined &&
-          data.log_run_id !== logRunIdRef.current
-        ) {
           logRunIdRef.current = data.log_run_id
           logOffsetRef.current = 0
           if (data.logs) {
@@ -90,7 +111,8 @@ function LogsPage() {
       <PageHeader title={t("navigation.logs")} />
 
       <div className="flex flex-1 flex-col overflow-hidden p-4 sm:p-8">
-        <div className="mb-4">
+        <div className="mb-4 flex items-start justify-between gap-4">
+          <div>
             <h1 className="text-2xl font-semibold tracking-tight">
               {t("navigation.logs")}
             </h1>
@@ -99,12 +121,23 @@ function LogsPage() {
             </p>
           </div>
 
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={handleClearLogs}
+            disabled={logs.length === 0 || clearing}
+          >
+            <IconTrash className="size-4" />
+            {t("pages.logs.clear")}
+          </Button>
+        </div>
+
         <div className="bg-muted/30 relative flex-1 overflow-hidden rounded-lg border">
           <ScrollArea className="h-full">
             <div className="p-4 font-mono text-sm leading-relaxed">
               {logs.length === 0 ? (
                 <div className="text-muted-foreground italic">
-                  Waiting for logs...
+                  {t("pages.logs.empty")}
                 </div>
               ) : (
                 logs.map((log, i) => (