Merge branch 'sipeed:main' into main

.env.example

@@ -9,6 +9,10 @@
 # ── Chat Channel ──────────────────────────
 # TELEGRAM_BOT_TOKEN=123456:ABC...
 # DISCORD_BOT_TOKEN=xxx
+# Feishu (飞书)
+# PICOCLAW_CHANNELS_FEISHU_APP_ID=cli_xxx
+# PICOCLAW_CHANNELS_FEISHU_APP_SECRET=xxx
+# PICOCLAW_CHANNELS_FEISHU_RANDOM_REACTION_EMOJI=Typing,OneSecond
 
 # ── Web Search (optional) ────────────────
 # BRAVE_SEARCH_API_KEY=BSA...

.github/workflows/nightly.yml

@@ -0,0 +1,167 @@
+name: Nightly Build
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  generate-version:
+    name: Generate Version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      tag: ${{ steps.version.outputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Generate version
+        id: version
+        run: |
+          DATE=$(date -u +%Y%m%d)
+          SHA=$(git rev-parse --short=8 HEAD)
+          BASE_VERSION=$(git describe --tags --match "v*" --exclude "*nightly*" --abbrev=0 2>/dev/null || true)
+          if [ -z "$BASE_VERSION" ] || [ "$BASE_VERSION" = "v0.0.0" ]; then
+            VERSION="nightly-${DATE}-${SHA}"
+          else
+            VERSION="${BASE_VERSION}-nightly-${DATE}-${SHA}"
+          fi
+          TAG="nightly-${DATE}-${SHA}"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: generate-version
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - name: Build
+        env:
+          VERSION: ${{ needs.generate-version.outputs.version }}
+        run: make build-all VERSION="$VERSION"
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: picoclaw-binaries
+          path: build
+
+  build-docker:
+    name: Build Docker
+    runs-on: ubuntu-latest
+    needs: generate-version
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=${{ needs.generate-version.outputs.tag }}
+            type=raw,value=${{ needs.generate-version.outputs.version }}
+            type=raw,value=nightly
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./docker/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64,linux/riscv64
+          provenance: false
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: [generate-version, build, build-docker]
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v6
+        with:
+          name: picoclaw-binaries
+          path: ./build
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ needs.generate-version.outputs.tag }}"
+          TITLE="${{ needs.generate-version.outputs.version }}"
+          NOTES=$'Nightly build for **${{ needs.generate-version.outputs.version }}**\n\nThis is an automated build and may be unstable. Use with caution.'
+
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists, updating metadata and assets..."
+            gh release edit "$TAG" \
+              --title "$TITLE" \
+              --notes "$NOTES" \
+              --prerelease
+            gh release upload "$TAG" build/* --clobber
+          else
+            echo "Creating new release $TAG..."
+            gh release create "$TAG" \
+              --title "$TITLE" \
+              --notes "$NOTES" \
+              --target "${{ github.sha }}" \
+              --prerelease \
+              build/*
+          fi
+
+          echo "Updating rolling 'nightly' release..."
+          gh release delete nightly --cleanup-tag -y >/dev/null 2>&1 || true
+          sleep 2
+          gh release create nightly \
+            --title "Nightly Build" \
+            --notes "$NOTES" \
+            --target "${{ github.sha }}" \
+            --prerelease \
+            build/*
+
+          echo "Cleaning up old nightly releases (keeping only the most recent)..."
+          gh release list --limit 100 --json tagName -q '.[].tagName | select(startswith("nightly-"))' | tail -n +2 | while read -r old_tag; do
+            if [ -n "$old_tag" ] && [ "$old_tag" != "$TAG" ]; then
+              echo "Deleting old nightly release: $old_tag"
+              gh release delete "$old_tag" --cleanup-tag -y || true
+            fi
+          done

.github/workflows/release.yml

@@ -65,6 +65,14 @@ jobs:
         with:
           go-version-file: go.mod
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Setup pnpm
+        run: corepack enable && corepack prepare pnpm@latest --activate
+
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
 
@@ -96,6 +104,11 @@ jobs:
           GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
           DOCKERHUB_IMAGE_NAME: ${{ vars.DOCKERHUB_REPOSITORY }}
           GOVERSION: ${{ steps.setup-go.outputs.go-version }}
+          MACOS_SIGN_P12: ${{ secrets.MACOS_SIGN_P12 }}
+          MACOS_SIGN_PASSWORD: ${{ secrets.MACOS_SIGN_PASSWORD }}
+          MACOS_NOTARY_ISSUER_ID: ${{ secrets.MACOS_NOTARY_ISSUER_ID }}
+          MACOS_NOTARY_KEY_ID: ${{ secrets.MACOS_NOTARY_KEY_ID }}
+          MACOS_NOTARY_KEY: ${{ secrets.MACOS_NOTARY_KEY }}
 
       - name: Apply release flags
         shell: bash

.gitignore

@@ -47,6 +47,12 @@ docs/plans/
 
 # Added by goreleaser init:
 dist/
+*.vite/
 
 # Windows Application Icon/Resource
 *.syso
+
+# Keep embedded backend dist directory placeholder in VCS
+!web/backend/dist/
+web/backend/dist/*
+!web/backend/dist/.gitkeep

.goreleaser.yaml

@@ -6,8 +6,9 @@ before:
   hooks:
     - go mod tidy
     - go generate ./...
+    - sh -c 'cd web/frontend && pnpm install && pnpm build:backend'
     - go install github.com/tc-hib/go-winres@latest
-    - go-winres make --in cmd/picoclaw-launcher/winres/winres.json --out cmd/picoclaw-launcher/rsrc --product-version={{ .Version }} --file-version={{ .Version }}
+    - go-winres make --in web/backend/winres/winres.json --out web/backend/rsrc --product-version={{ .Version }} --file-version={{ .Version }}
 
 builds:
   - id: picoclaw
@@ -32,9 +33,13 @@ builds:
       - riscv64
       - loong64
       - arm
+      - s390x
+      - mipsle
     goarm:
       - "6"
       - "7"
+    gomips:
+      - softfloat
     main: ./cmd/picoclaw
     ignore:
       - goos: windows
@@ -59,10 +64,14 @@ builds:
       - riscv64
       - loong64
       - arm
+      - s390x
+      - mipsle
     goarm:
       - "6"
       - "7"
-    main: ./cmd/picoclaw-launcher
+    gomips:
+      - softfloat
+    main: ./web/backend
     ignore:
       - goos: windows
         goarch: arm
@@ -86,9 +95,13 @@ builds:
       - riscv64
       - loong64
       - arm
+      - s390x
+      - mipsle
     goarm:
       - "6"
       - "7"
+    gomips:
+      - softfloat
     main: ./cmd/picoclaw-launcher-tui
     ignore:
       - goos: windows
@@ -112,6 +125,23 @@ dockers_v2:
       - linux/arm64
       - linux/riscv64
 
+notarize:
+  macos:
+    - enabled: '{{ isEnvSet "MACOS_SIGN_P12" }}'
+      ids:
+        - picoclaw
+        - picoclaw-launcher
+        - picoclaw-launcher-tui
+      sign:
+        certificate: "{{.Env.MACOS_SIGN_P12}}"
+        password: "{{.Env.MACOS_SIGN_PASSWORD}}"
+      notarize:
+        issuer_id: "{{.Env.MACOS_NOTARY_ISSUER_ID}}"
+        key_id: "{{.Env.MACOS_NOTARY_KEY_ID}}"
+        key: "{{.Env.MACOS_NOTARY_KEY}}"
+        wait: true
+        timeout: 20m
+
 archives:
   - formats: [tar.gz]
     # this name template makes the OS and Arch compatible with the results of `uname`.
@@ -149,6 +179,11 @@ nfpms:
       - rpm
       - deb
     bindir: /usr/bin
+    contents:
+      - src: web/picoclaw-launcher.desktop
+        dst: /usr/share/applications/picoclaw-launcher.desktop
+      - src: web/picoclaw-launcher.png
+        dst: /usr/share/icons/hicolor/512x512/apps/picoclaw-launcher.png
 
 changelog:
   sort: asc

Makefile

@@ -111,6 +111,18 @@ build: generate
 	@echo "Build complete: $(BINARY_PATH)"
 	@ln -sf $(BINARY_NAME)-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/$(BINARY_NAME)
 
+## build-launcher: Build the picoclaw-launcher (web console) binary
+build-launcher:
+	@echo "Building picoclaw-launcher for $(PLATFORM)/$(ARCH)..."
+	@mkdir -p $(BUILD_DIR)
+	@if [ ! -f web/backend/dist/index.html ]; then \
+		echo "Building frontend..."; \
+		cd web/frontend && pnpm install && pnpm build:backend; \
+	fi
+	@$(GO) build $(GOFLAGS) -o $(BUILD_DIR)/picoclaw-launcher-$(PLATFORM)-$(ARCH) ./web/backend
+	@ln -sf picoclaw-launcher-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/picoclaw-launcher
+	@echo "Build complete: $(BUILD_DIR)/picoclaw-launcher"
+
 ## build-whatsapp-native: Build with WhatsApp native (whatsmeow) support; larger binary
 build-whatsapp-native: generate
 ## @echo "Building $(BINARY_NAME) with WhatsApp native for $(PLATFORM)/$(ARCH)..."

README.md

@@ -308,7 +308,7 @@ That's it! You have a working AI assistant in 2 minutes.
 
 ## 💬 Chat Apps
 
-Talk to your picoclaw through Telegram, Discord, WhatsApp, DingTalk, LINE, or WeCom
+Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, or WeCom
 
 > **Note**: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server.
 
@@ -317,6 +317,7 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, DingTalk, LINE, or We
 | **Telegram** | Easy (just a token)                |
 | **Discord**  | Easy (bot token + intents)         |
 | **WhatsApp** | Easy (native: QR scan; or bridge URL) |
+| **Matrix**   | Medium (homeserver + bot access token) |
 | **QQ**       | Easy (AppID + AppSecret)           |
 | **DingTalk** | Medium (app credentials)           |
 | **LINE**     | Medium (credentials + webhook URL) |
@@ -528,6 +529,40 @@ picoclaw gateway
 ```
 </details>
 
+<details>
+<summary><b>Matrix</b></summary>
+
+**1. Prepare bot account**
+
+* Use your preferred homeserver (e.g. `https://matrix.org` or self-hosted)
+* Create a bot user and obtain its access token
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), see [Matrix Channel Configuration Guide](docs/channels/matrix/README.md).
+
+</details>
+
 <details>
 <summary><b>LINE</b></summary>
 
@@ -952,6 +987,7 @@ The subagent has access to tools (message, web_search, etc.) and can communicate
 | `qwen`                     | LLM (Qwen direct)                       | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
 | `groq`                     | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com)                         |
 | `cerebras`                 | LLM (Cerebras direct)                   | [cerebras.ai](https://cerebras.ai)                                   |
+| `vivgrid`                  | LLM (Vivgrid direct)                    | [vivgrid.com](https://vivgrid.com)                                   |
 
 ### Model Configuration (model_list)
 
@@ -979,11 +1015,12 @@ This design also enables **multi-agent support** with flexible provider selectio
 | **NVIDIA**          | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [Get Key](https://build.nvidia.com)                              |
 | **Ollama**          | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | Local (no key needed)                                            |
 | **OpenRouter**      | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [Get Key](https://openrouter.ai/keys)                            |
-| **LiteLLM Proxy**   | `litellm/`        | `http://localhost:4000/v1                           | OpenAI    | Your LiteLLM proxy key                                            |
+| **LiteLLM Proxy**   | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | Your LiteLLM proxy key                                            |
 | **VLLM**            | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
 | **Cerebras**        | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
 | **火山引擎**        | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://console.volcengine.com)                        |
 | **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                |
+| **Vivgrid**         | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
 | **Antigravity**     | `antigravity/`    | Google Cloud                                        | Custom    | OAuth only                                                       |
 | **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                |
 

README.zh.md

@@ -299,6 +299,7 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方
 | **Telegram**         | ⭐ 简单     | 推荐，支持语音转文字，长轮询无需公网      | [查看文档](docs/channels/telegram/README.zh.md)                                                                 |
 | **Discord**          | ⭐ 简单     | Socket Mode，支持群组/私信，Bot 生态成熟  | [查看文档](docs/channels/discord/README.zh.md)                                                                  |
 | **Slack**            | ⭐ 简单     | **Socket Mode** (无需公网 IP)，企业级支持 | [查看文档](docs/channels/slack/README.zh.md)                                                                    |
+| **Matrix**           | ⭐⭐ 中等   | 联邦协议，支持自建 homeserver 与公开服务器 | [查看文档](docs/channels/matrix/README.zh.md)                                                                  |
 | **QQ**               | ⭐⭐ 中等   | 官方机器人 API，适合国内社群              | [查看文档](docs/channels/qq/README.zh.md)                                                                       |
 | **钉钉 (DingTalk)**  | ⭐⭐ 中等   | Stream 模式无需公网，企业办公首选         | [查看文档](docs/channels/dingtalk/README.zh.md)                                                                 |
 | **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(Webhook)、自建应用(API)和智能机器人(AI Bot) | [Bot 文档](docs/channels/wecom/wecom_bot/README.zh.md) / [App 文档](docs/channels/wecom/wecom_app/README.zh.md) / [AI Bot 文档](docs/channels/wecom/wecom_aibot/README.zh.md) |

cmd/picoclaw-launcher-tui/internal/ui/app.go

@@ -1,6 +1,7 @@
 package ui
 
 import (
+	"fmt"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -67,6 +68,7 @@ func Run() error {
 	root := tview.NewFlex().SetDirection(tview.FlexRow)
 	root.AddItem(bannerView(), 6, 0, false)
 	root.AddItem(state.pages, 0, 1, true)
+	root.AddItem(footerView(), 1, 0, false)
 
 	if err := state.app.SetRoot(root, true).EnableMouse(false).Run(); err != nil {
 		return err
@@ -102,7 +104,7 @@ func (s *appState) pop() {
 }
 
 func (s *appState) mainMenu() tview.Primitive {
-	menu := NewMenu("Config Menu", nil)
+	menu := NewMenu("Menu", nil)
 	refreshMainMenu(menu, s)
 	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
 		switch event.Key() {
@@ -110,10 +112,7 @@ func (s *appState) mainMenu() tview.Primitive {
 			s.requestExit()
 			return nil
 		}
-		if event.Rune() == 'q' {
+
-			s.requestExit()
-			return nil
-		}
 		return event
 	})
 
@@ -131,6 +130,32 @@ func (s *appState) refreshMenu(name string, menu *Menu) {
 	}
 }
 
+func (s *appState) countChannels() (enabled int, total int) {
+	c := s.config.Channels
+	entries := []bool{
+		c.Telegram.Enabled,
+		c.Discord.Enabled,
+		c.QQ.Enabled,
+		c.MaixCam.Enabled,
+		c.WhatsApp.Enabled,
+		c.Feishu.Enabled,
+		c.DingTalk.Enabled,
+		c.Slack.Enabled,
+		c.Matrix.Enabled,
+		c.LINE.Enabled,
+		c.OneBot.Enabled,
+		c.WeCom.Enabled,
+		c.WeComApp.Enabled,
+	}
+	total = len(entries)
+	for _, v := range entries {
+		if v {
+			enabled++
+		}
+	}
+	return enabled, total
+}
+
 func refreshMainMenuIfPresent(s *appState) {
 	if menu, ok := s.menus["main"]; ok {
 		refreshMainMenu(menu, s)
@@ -141,6 +166,7 @@ func refreshMainMenu(menu *Menu, s *appState) {
 	selectedModel := s.selectedModelName()
 	modelReady := selectedModel != ""
 	channelReady := s.hasEnabledChannel()
+	enabledCount, totalChannels := s.countChannels()
 	gatewayRunning := s.gatewayCmd != nil || s.isGatewayRunning()
 
 	gatewayLabel := "Start Gateway"
@@ -153,7 +179,7 @@ func refreshMainMenu(menu *Menu, s *appState) {
 	items := []MenuItem{
 		{
 			Label:       rootModelLabel(selectedModel),
-			Description: rootModelDescription(selectedModel),
+			Description: rootModelDescription(),
 			Action: func() {
 				s.push("model", s.modelMenu())
 			},
@@ -167,7 +193,7 @@ func refreshMainMenu(menu *Menu, s *appState) {
 		},
 		{
 			Label:       rootChannelLabel(channelReady),
-			Description: rootChannelDescription(channelReady),
+			Description: fmt.Sprintf("%d/%d enabled", enabledCount, totalChannels),
 			Action: func() {
 				s.push("channel", s.channelMenu())
 			},
@@ -311,16 +337,13 @@ func (s *appState) selectedModelName() string {
 
 func rootModelLabel(selected string) string {
 	if selected == "" {
-		return "Model (no model selected)"
+		return "Model (None)"
 	}
 	return "Model (" + selected + ")"
 }
 
-func rootModelDescription(selected string) string {
+func rootModelDescription() string {
-	if selected == "" {
+	return "Using SPACE to choose your model"
-		return "no model selected"
-	}
-	return "selected"
 }
 
 func rootChannelLabel(valid bool) string {
@@ -330,13 +353,6 @@ func rootChannelLabel(valid bool) string {
 	return "Channel"
 }
 
-func rootChannelDescription(valid bool) string {
-	if !valid {
-		return "no channel enabled"
-	}
-	return "enabled"
-}
-
 func (s *appState) startTalk() {
 	if !s.isActiveModelValid() {
 		s.showMessage("Model required", "Select a valid model before starting talk")
@@ -423,7 +439,7 @@ func (s *appState) hasEnabledChannel() bool {
 	c := s.config.Channels
 	return c.Telegram.Enabled || c.Discord.Enabled || c.QQ.Enabled || c.MaixCam.Enabled ||
 		c.WhatsApp.Enabled || c.Feishu.Enabled || c.DingTalk.Enabled || c.Slack.Enabled ||
-		c.LINE.Enabled || c.OneBot.Enabled || c.WeCom.Enabled || c.WeComApp.Enabled
+		c.Matrix.Enabled || c.LINE.Enabled || c.OneBot.Enabled || c.WeCom.Enabled || c.WeComApp.Enabled
 }
 
 func (s *appState) confirmApplyOrDiscard(onApply func(), onDiscard func()) {

cmd/picoclaw-launcher-tui/internal/ui/channel.go

@@ -12,7 +12,6 @@ import (
 
 func (s *appState) buildChannelMenuItems() []MenuItem {
 	return []MenuItem{
-		{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
 		channelItem(
 			"Telegram",
 			"Telegram bot settings",
@@ -61,6 +60,12 @@ func (s *appState) buildChannelMenuItems() []MenuItem {
 			s.config.Channels.Slack.Enabled,
 			func() { s.push("channel-slack", s.slackForm()) },
 		),
+		channelItem(
+			"Matrix",
+			"Matrix bot settings",
+			s.config.Channels.Matrix.Enabled,
+			func() { s.push("channel-matrix", s.matrixForm()) },
+		),
 		channelItem(
 			"LINE",
 			"LINE bot settings",
@@ -95,10 +100,6 @@ func (s *appState) channelMenu() tview.Primitive {
 			s.pop()
 			return nil
 		}
-		if event.Rune() == 'q' {
-			s.pop()
-			return nil
-		}
 		return event
 	})
 	return menu
@@ -233,6 +234,28 @@ func (s *appState) lineForm() tview.Primitive {
 	return wrapWithBack(form, s)
 }
 
+func (s *appState) matrixForm() tview.Primitive {
+	cfg := &s.config.Channels.Matrix
+	form := baseChannelForm("Matrix", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	form.AddInputField("Homeserver", cfg.Homeserver, 128, nil, func(text string) {
+		cfg.Homeserver = strings.TrimSpace(text)
+	})
+	form.AddInputField("User ID", cfg.UserID, 128, nil, func(text string) {
+		cfg.UserID = strings.TrimSpace(text)
+	})
+	form.AddInputField("Access Token", cfg.AccessToken, 128, nil, func(text string) {
+		cfg.AccessToken = strings.TrimSpace(text)
+	})
+	form.AddInputField("Device ID", cfg.DeviceID, 128, nil, func(text string) {
+		cfg.DeviceID = strings.TrimSpace(text)
+	})
+	form.AddCheckbox("Join On Invite", cfg.JoinOnInvite, func(checked bool) {
+		cfg.JoinOnInvite = checked
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
 func (s *appState) onebotForm() tview.Primitive {
 	cfg := &s.config.Channels.OneBot
 	form := baseChannelForm("OneBot", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))

cmd/picoclaw-launcher-tui/internal/ui/model.go

@@ -14,23 +14,7 @@ import (
 )
 
 func (s *appState) modelMenu() tview.Primitive {
-	items := make([]MenuItem, 0, 2+len(s.config.ModelList))
+	items := make([]MenuItem, 0, 1+len(s.config.ModelList))
-	items = append(items,
-		MenuItem{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
-		MenuItem{
-			Label:       "Add model",
-			Description: "Append a new model entry",
-			Action: func() {
-				s.addModel(
-					picoclawconfig.ModelConfig{ModelName: "new-model", Model: "openai/gpt-5.2"},
-				)
-				s.push(
-					fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
-					s.modelForm(len(s.config.ModelList)-1),
-				)
-			},
-		},
-	)
 	currentModel := strings.TrimSpace(s.config.Agents.Defaults.Model)
 	for i := range s.config.ModelList {
 		index := i
@@ -57,6 +41,23 @@ func (s *appState) modelMenu() tview.Primitive {
 			},
 		})
 	}
+	// Add model entry appended at the end so the models map to rows 1..N
+	items = append(items,
+		MenuItem{
+			Label:       "**Add model**",
+			Description: "Append a new model entry",
+			Action: func() {
+				newName := s.nextAvailableModelName("new-model")
+				s.addModel(
+					picoclawconfig.ModelConfig{ModelName: newName, Model: "openai/gpt-5.2"},
+				)
+				s.push(
+					fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
+					s.modelForm(len(s.config.ModelList)-1),
+				)
+			},
+		},
+	)
 
 	menu := NewMenu("Models", items)
 	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
@@ -64,14 +65,11 @@ func (s *appState) modelMenu() tview.Primitive {
 			s.pop()
 			return nil
 		}
-		if event.Rune() == 'q' {
+
-			s.pop()
-			return nil
-		}
 		if event.Rune() == ' ' {
 			row, _ := menu.GetSelection()
-			if row > 0 && row <= len(s.config.ModelList) {
+			if row >= 0 && row < len(s.config.ModelList) {
-				model := s.config.ModelList[row-1]
+				model := s.config.ModelList[row]
 				if !isModelValid(model) {
 					s.showMessage(
 						"Invalid model",
@@ -95,12 +93,23 @@ func (s *appState) modelForm(index int) tview.Primitive {
 	model := &s.config.ModelList[index]
 	form := tview.NewForm()
 	form.SetBorder(true).SetTitle(fmt.Sprintf("Model: %s", model.ModelName))
-	form.SetButtonBackgroundColor(tcell.NewRGBColor(80, 250, 123))
-	form.SetButtonTextColor(tcell.NewRGBColor(12, 13, 22))
 
 	addInput(form, "Model Name", model.ModelName, func(value string) {
+		if value == "" {
+			s.showMessage("Invalid model name", "Model Name cannot be empty")
+			return
+		}
+		if s.modelNameExists(value, index) {
+			s.showMessage("Duplicate model name", fmt.Sprintf("Model Name '%s' already exists", value))
+			return
+		}
+		oldName := model.ModelName
 		model.ModelName = value
+		if s.config.Agents.Defaults.Model == oldName {
+			s.config.Agents.Defaults.Model = value
+		}
 		s.dirty = true
+		form.SetTitle(fmt.Sprintf("Model: %s", model.ModelName))
 		refreshMainMenuIfPresent(s)
 		if menu, ok := s.menus["model"]; ok {
 			refreshModelMenuFromState(menu, s)
@@ -158,7 +167,21 @@ func (s *appState) modelForm(index int) tview.Primitive {
 	})
 
 	form.AddButton("Delete", func() {
-		s.deleteModel(index)
+		pageName := "confirm-delete-model"
+		if s.pages.HasPage(pageName) {
+			return
+		}
+		modal := tview.NewModal().
+			SetText("Are you sure you want to delete this model?").
+			AddButtons([]string{"Cancel", "Delete"}).
+			SetDoneFunc(func(buttonIndex int, buttonLabel string) {
+				s.pages.RemovePage(pageName)
+				if buttonLabel == "Delete" {
+					s.deleteModel(index)
+				}
+			})
+		modal.SetTitle("Confirm Delete").SetBorder(true)
+		s.pages.AddPage(pageName, modal, true, true)
 	})
 	form.AddButton("Test", func() {
 		s.testModel(model)
@@ -215,7 +238,7 @@ func modelStatusColor(valid bool, selected bool) *tcell.Color {
 
 func refreshModelMenu(menu *Menu, currentModel string, models []picoclawconfig.ModelConfig) {
 	for i, model := range models {
-		row := i + 1
+		row := i
 		label := fmt.Sprintf("%s (%s)", model.ModelName, model.Model)
 		isValid := isModelValid(model)
 		if model.ModelName == currentModel && currentModel != "" {
@@ -234,23 +257,7 @@ func refreshModelMenu(menu *Menu, currentModel string, models []picoclawconfig.M
 }
 
 func refreshModelMenuFromState(menu *Menu, s *appState) {
-	items := make([]MenuItem, 0, 2+len(s.config.ModelList))
+	items := make([]MenuItem, 0, 1+len(s.config.ModelList))
-	items = append(items,
-		MenuItem{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
-		MenuItem{
-			Label:       "Add model",
-			Description: "Append a new model entry",
-			Action: func() {
-				s.addModel(
-					picoclawconfig.ModelConfig{ModelName: "new-model", Model: "openai/gpt-5.2"},
-				)
-				s.push(
-					fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
-					s.modelForm(len(s.config.ModelList)-1),
-				)
-			},
-		},
-	)
 	currentModel := strings.TrimSpace(s.config.Agents.Defaults.Model)
 	for i := range s.config.ModelList {
 		index := i
@@ -277,6 +284,19 @@ func refreshModelMenuFromState(menu *Menu, s *appState) {
 			},
 		})
 	}
+	items = append(items,
+		MenuItem{
+			Label:       "**Add Model**",
+			Description: "Append a new model entry",
+			Action: func() {
+				newName := s.nextAvailableModelName("new-model")
+				s.addModel(
+					picoclawconfig.ModelConfig{ModelName: newName, Model: "openai/gpt-5.2"},
+				)
+				s.push(fmt.Sprintf("model-%d", len(s.config.ModelList)-1), s.modelForm(len(s.config.ModelList)-1))
+			},
+		},
+	)
 	menu.applyItems(items)
 }
 
@@ -287,6 +307,38 @@ func isModelValid(model picoclawconfig.ModelConfig) bool {
 	return hasKey && hasModel
 }
 
+func (s *appState) modelNameExists(name string, excludeIndex int) bool {
+	target := strings.TrimSpace(name)
+	if target == "" {
+		return false
+	}
+	for i := range s.config.ModelList {
+		if i == excludeIndex {
+			continue
+		}
+		if strings.TrimSpace(s.config.ModelList[i].ModelName) == target {
+			return true
+		}
+	}
+	return false
+}
+
+func (s *appState) nextAvailableModelName(base string) string {
+	name := strings.TrimSpace(base)
+	if name == "" {
+		name = "new-model"
+	}
+	if !s.modelNameExists(name, -1) {
+		return name
+	}
+	for i := 2; ; i++ {
+		candidate := fmt.Sprintf("%s-%d", name, i)
+		if !s.modelNameExists(candidate, -1) {
+			return candidate
+		}
+	}
+}
+
 func (s *appState) testModel(model *picoclawconfig.ModelConfig) {
 	if model == nil {
 		return

cmd/picoclaw-launcher-tui/internal/ui/style.go

@@ -41,3 +41,15 @@ func bannerView() *tview.TextView {
 	text.SetBorder(false)
 	return text
 }
+
+const footerText = "Esc: Back/Exit | Enter: Enter | ←↓↑→ : Move | Space: Select | Tab/Shift+Tab: Switch"
+
+func footerView() *tview.TextView {
+	text := tview.NewTextView()
+	text.SetTextAlign(tview.AlignCenter)
+	text.SetText(footerText)
+	text.SetBackgroundColor(tview.Styles.MoreContrastBackgroundColor)
+	text.SetTextColor(tview.Styles.PrimaryTextColor)
+	text.SetBorder(false)
+	return text
+}

cmd/picoclaw-launcher/README.md

@@ -1,290 +0,0 @@
-# PicoClaw Launcher
-
-> [!WARNING]
-> This project is a temporary solution and will be refactored in the future to provide a complete web service. Therefore, the APIs in this directory are not stable.
-
-A standalone launcher for PicoClaw, providing visual JSON editing and OAuth provider authentication management.
-
-## Features
-
-- 📝 **Config Editor** — Sidebar-based settings UI with model management, channel configuration forms, and a raw JSON editor
-- 🤖 **Model Management** — Model card grid with availability status (grayed out without API key), primary model selection, add/edit/delete with required/optional field separation
-- 📡 **Channel Configuration** — Form-based settings for 12 channel types (Telegram, Discord, Slack, WeCom, DingTalk, Feishu, LINE, WhatsApp, QQ, OneBot, MaixCAM, etc.) with documentation links
-- 🔐 **Provider Auth** — Login to OpenAI (Device Code), Anthropic (API Token), Google Antigravity (Browser OAuth)
-- 🌐 **Embedded Frontend** — Compiles to a single binary with no external dependencies
-- 🌍 **i18n** — Chinese/English language switching with browser auto-detection
-- 🎨 **Theme** — Light / Dark / System theme toggle with localStorage persistence
-
-## Quick Start
-
-```bash
-# Build
-go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
-
-# Run with default config path (~/.picoclaw/config.json)
-./picoclaw-launcher
-
-# Specify a config file
-./picoclaw-launcher ./config.json
-
-# Allow LAN access
-./picoclaw-launcher -public
-```
-
-Open `http://localhost:18800` in your browser.
-
-## CLI Options
-
-```
-Usage: picoclaw-config [options] [config.json]
-
-Arguments:
-  config.json    Path to the configuration file (default: ~/.picoclaw/config.json)
-
-Options:
-  -public        Listen on all interfaces (0.0.0.0), allowing access from other devices
-```
-
-## API Reference
-
-Base URL: `http://localhost:18800`
-
----
-
-### Static Files
-
-#### GET /
-
-Serves the embedded frontend (`index.html`).
-
----
-
-### Config API
-
-#### GET /api/config
-
-Reads the current configuration file.
-
-**Response** `200 OK`
-
-```json
-{
-  "config": { ... },
-  "path": "/Users/xiao/.picoclaw/config.json"
-}
-```
-
----
-
-#### PUT /api/config
-
-Saves the configuration. The request body must be a complete Config JSON object.
-
-**Request Body** — `application/json`
-
-```json
-{
-  "agents": { "defaults": { "model_name": "gpt-5.2" } },
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "auth_method": "oauth"
-    }
-  ]
-}
-```
-
-**Response** `200 OK`
-
-```json
-{ "status": "ok" }
-```
-
-**Error** `400 Bad Request` — Invalid JSON
-
----
-
-### Auth API
-
-#### GET /api/auth/status
-
-Returns the authentication status of all providers and any in-progress device code login.
-
-**Response** `200 OK`
-
-```json
-{
-  "providers": [
-    {
-      "provider": "openai",
-      "auth_method": "oauth",
-      "status": "active",
-      "account_id": "user-xxx",
-      "expires_at": "2026-03-01T00:00:00Z"
-    }
-  ],
-  "pending_device": {
-    "provider": "openai",
-    "status": "pending",
-    "device_url": "https://auth.openai.com/activate",
-    "user_code": "ABCD-1234"
-  }
-}
-```
-
-`status` values: `active` | `expired` | `needs_refresh`
-
-`pending_device` is only present when a device code login is in progress.
-
----
-
-#### POST /api/auth/login
-
-Initiates a provider login.
-
-**Request Body** — `application/json`
-
-```json
-{ "provider": "openai" }
-```
-
-Supported `provider` values: `openai` | `anthropic` | `google-antigravity`
-
-##### OpenAI (Device Code Flow)
-
-Returns device code info. The server polls for completion in the background.
-
-```json
-{
-  "status": "pending",
-  "device_url": "https://auth.openai.com/activate",
-  "user_code": "ABCD-1234",
-  "message": "Open the URL and enter the code to authenticate."
-}
-```
-
-The user opens `device_url` in a browser and enters `user_code`. Once authenticated, `GET /api/auth/status` will show `pending_device.status` as `success`.
-
-##### Anthropic (API Token)
-
-Requires a `token` field in the request:
-
-```json
-{ "provider": "anthropic", "token": "sk-ant-xxx" }
-```
-
-**Response:**
-
-```json
-{ "status": "success", "message": "Anthropic token saved" }
-```
-
-##### Google Antigravity (Browser OAuth)
-
-Returns an authorization URL for the frontend to open in a new tab:
-
-```json
-{
-  "status": "redirect",
-  "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
-  "message": "Open the URL to authenticate with Google."
-}
-```
-
-After authentication, Google redirects to `GET /auth/callback`, which saves the credentials and redirects back to the picoclaw-config UI.
-
----
-
-#### POST /api/auth/logout
-
-Logs out from a provider.
-
-**Request Body** — `application/json`
-
-```json
-{ "provider": "openai" }
-```
-
-Omit or leave `provider` empty to log out from all providers.
-
-**Response** `200 OK`
-
-```json
-{ "status": "ok" }
-```
-
----
-
-#### GET /auth/callback
-
-OAuth browser callback endpoint (used by Google Antigravity). Called by the OAuth provider's redirect — **not invoked directly by the frontend**.
-
-**Query Parameters:**
-- `state` — OAuth state for CSRF validation
-- `code` — Authorization code
-
-On success, redirects to `/#auth`.
-
-
-### Process API
-
-#### GET /api/process/status
-
-Gets the running status of the `picoclaw gateway` process.
-
-**Response** `200 OK` (Running)
-
-```json
-{
-  "process_status": "running",
-  "status": "ok",
-  "uptime": "1.010814s"
-}
-```
-
-**Response** `200 OK` (Stopped)
-
-```json
-{
-  "process_status": "stopped",
-  "error": "Get \"http://localhost:18790/health\": dial tcp [::1]:18790: connect: connection refused"
-}
-```
-
----
-
-#### POST /api/process/start
-
-Starts the `picoclaw gateway` process in the background.
-
-**Response** `200 OK`
-
-```json
-{
-  "status": "ok",
-  "pid": 12345
-}
-```
-
----
-
-#### POST /api/process/stop
-
-Stops the running `picoclaw gateway` process.
-
-**Response** `200 OK`
-
-```json
-{
-  "status": "ok"
-}
-```
-
----
-
-## Testing
-
-```bash
-go test -v ./cmd/picoclaw-launcher/
-```

cmd/picoclaw-launcher/README.zh.md

@@ -1,287 +0,0 @@
-# PicoClaw Launcher
-
-> [!WARNING]
-> 该项目属于临时解决方案，后续会重构并提供完整的 Web 服务，因此该目录下的接口并不稳定。
-
-PicoClaw 的独立启动器，提供可视化 JSON 配置编辑和 OAuth Provider 认证管理。
-
-## 功能
-
-- 📝 **配置编辑** — 侧边栏式设置 UI，支持模型管理、通道配置表单和原始 JSON 编辑器
-- 🤖 **模型管理** — 模型卡片网格，可用性状态显示（无 API Key 时灰色），主模型选择，增删改查，必填/选填字段分离
-- 📡 **通道配置** — 12 种通道类型（Telegram、Discord、Slack、企业微信、钉钉、飞书、LINE、WhatsApp、QQ、OneBot、MaixCAM 等）的表单化配置，附带文档链接
-- 🔐 **Provider 认证** — 支持 OpenAI (Device Code)、Anthropic (API Token)、Google Antigravity (Browser OAuth) 登录
-- 🌐 **嵌入式前端** — 编译为单一二进制文件，无需额外依赖
-- 🌍 **国际化** — 中英文切换，首次访问自动检测浏览器语言
-- 🎨 **主题** — 亮色 / 暗色 / 跟随系统，偏好保存在 localStorage
-
-## 快速开始
-
-```bash
-# 编译
-go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
-
-# 运行（使用默认配置路径 ~/.picoclaw/config.json）
-./picoclaw-launcher
-
-# 指定配置文件
-./picoclaw-launcher ./config.json
-
-# 允许局域网访问
-./picoclaw-launcher -public
-```
-
-启动后在浏览器中打开 `http://localhost:18800`。
-
-## 命令行参数
-
-```
-Usage: picoclaw-launcher [options] [config.json]
-
-Arguments:
-  config.json    配置文件路径（默认: ~/.picoclaw/config.json）
-
-Options:
-  -public        监听所有网络接口（0.0.0.0），允许局域网设备访问
-```
-
-## API 文档
-
-Base URL: `http://localhost:18800`
-
-### 静态文件
-
-#### GET /
-
-提供嵌入式前端页面（`index.html`）。
-
----
-
-### Config API
-
-#### GET /api/config
-
-读取当前配置文件内容。
-
-**Response** `200 OK`
-
-```json
-{
-  "config": { ... },
-  "path": "/Users/xiao/.picoclaw/config.json"
-}
-```
-
----
-
-#### PUT /api/config
-
-保存配置。请求体为完整的 Config JSON。
-
-**Request Body** — `application/json`
-
-```json
-{
-  "agents": { "defaults": { "model_name": "gpt-5.2" } },
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "auth_method": "oauth"
-    }
-  ]
-}
-```
-
-**Response** `200 OK`
-
-```json
-{ "status": "ok" }
-```
-
-**Error** `400 Bad Request` — 无效 JSON
-
----
-
-### Auth API
-
-#### GET /api/auth/status
-
-获取所有 Provider 的认证状态和进行中的 Device Code 登录信息。
-
-**Response** `200 OK`
-
-```json
-{
-  "providers": [
-    {
-      "provider": "openai",
-      "auth_method": "oauth",
-      "status": "active",
-      "account_id": "user-xxx",
-      "expires_at": "2026-03-01T00:00:00Z"
-    }
-  ],
-  "pending_device": {
-    "provider": "openai",
-    "status": "pending",
-    "device_url": "https://auth.openai.com/activate",
-    "user_code": "ABCD-1234"
-  }
-}
-```
-
-`status` 可选值: `active` | `expired` | `needs_refresh`
-
-`pending_device` 仅在有进行中的 Device Code 登录时返回。
-
----
-
-#### POST /api/auth/login
-
-发起 Provider 登录。
-
-**Request Body** — `application/json`
-
-```json
-{ "provider": "openai" }
-```
-
-支持的 `provider` 值: `openai` | `anthropic` | `google-antigravity`
-
-##### OpenAI (Device Code Flow)
-
-返回 Device Code 信息，后台自动轮询认证结果：
-
-```json
-{
-  "status": "pending",
-  "device_url": "https://auth.openai.com/activate",
-  "user_code": "ABCD-1234",
-  "message": "Open the URL and enter the code to authenticate."
-}
-```
-
-用户在浏览器中打开 `device_url` 并输入 `user_code`。认证完成后通过 `GET /api/auth/status` 的 `pending_device.status` 变为 `success` 通知前端。
-
-##### Anthropic (API Token)
-
-需在请求中附带 token：
-
-```json
-{ "provider": "anthropic", "token": "sk-ant-xxx" }
-```
-
-**Response:**
-
-```json
-{ "status": "success", "message": "Anthropic token saved" }
-```
-
-##### Google Antigravity (Browser OAuth)
-
-返回授权 URL，前端打开新标签页：
-
-```json
-{
-  "status": "redirect",
-  "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
-  "message": "Open the URL to authenticate with Google."
-}
-```
-
-认证完成后 Google 回调至 `GET /auth/callback`，自动保存凭据并重定向回 picoclaw-config 页面。
-
----
-
-#### POST /api/auth/logout
-
-登出 Provider。
-
-**Request Body** — `application/json`
-
-```json
-{ "provider": "openai" }
-```
-
-传空字符串或省略 `provider` 则登出所有 Provider。
-
-**Response** `200 OK`
-
-```json
-{ "status": "ok" }
-```
-
----
-
-#### GET /auth/callback
-
-OAuth Browser 回调端点（Google Antigravity 专用），由 OAuth Provider 重定向调用，**非前端直接使用**。
-
-**Query Parameters:**
-- `state` — OAuth state 校验
-- `code` — 授权码
-
-认证成功后重定向到 `/#auth`。
-
-### Process API
-
-#### GET /api/process/status
-
-获取 `picoclaw gateway` 进程的运行状态。
-
-**Response** `200 OK` (运行中)
-
-```json
-{
-  "process_status": "running",
-  "status": "ok",
-  "uptime": "1.010814s"
-}
-```
-
-**Response** `200 OK` (未运行)
-
-```json
-{
-  "process_status": "stopped",
-  "error": "Get \"http://localhost:18790/health\": dial tcp [::1]:18790: connect: connection refused"
-}
-```
-
----
-
-#### POST /api/process/start
-
-在后台启动 `picoclaw gateway` 进程。
-
-**Response** `200 OK`
-
-```json
-{
-  "status": "ok",
-  "pid": 12345
-}
-```
-
----
-
-#### POST /api/process/stop
-
-停止正在运行的 `picoclaw gateway` 进程。
-
-**Response** `200 OK`
-
-```json
-{
-  "status": "ok"
-}
-```
-
----
-
-## 测试
-
-```bash
-go test -v ./cmd/picoclaw-launcher/
-```

cmd/picoclaw-launcher/internal/server/auth_config.go

@@ -1,147 +0,0 @@
-package server
-
-import (
-	"log"
-	"strings"
-
-	"github.com/sipeed/picoclaw/pkg/auth"
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-// updateConfigAfterLogin updates config.json after a successful provider login.
-func updateConfigAfterLogin(configPath, provider string, cred *auth.AuthCredential) {
-	cfg, err := config.LoadConfig(configPath)
-	if err != nil {
-		log.Printf("Warning: could not load config to update auth_method: %v", err)
-		return
-	}
-
-	switch provider {
-	case "openai":
-		cfg.Providers.OpenAI.AuthMethod = "oauth"
-		found := false
-		for i := range cfg.ModelList {
-			if isOpenAIModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = "oauth"
-				found = true
-				break
-			}
-		}
-		if !found {
-			cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
-				ModelName:  "gpt-5.2",
-				Model:      "openai/gpt-5.2",
-				AuthMethod: "oauth",
-			})
-		}
-		cfg.Agents.Defaults.ModelName = "gpt-5.2"
-
-	case "anthropic":
-		cfg.Providers.Anthropic.AuthMethod = "token"
-		found := false
-		for i := range cfg.ModelList {
-			if isAnthropicModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = "token"
-				found = true
-				break
-			}
-		}
-		if !found {
-			cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
-				ModelName:  "claude-sonnet-4.6",
-				Model:      "anthropic/claude-sonnet-4.6",
-				AuthMethod: "token",
-			})
-		}
-		cfg.Agents.Defaults.ModelName = "claude-sonnet-4.6"
-
-	case "google-antigravity":
-		cfg.Providers.Antigravity.AuthMethod = "oauth"
-		found := false
-		for i := range cfg.ModelList {
-			if isAntigravityModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = "oauth"
-				found = true
-				break
-			}
-		}
-		if !found {
-			cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
-				ModelName:  "gemini-flash",
-				Model:      "antigravity/gemini-3-flash",
-				AuthMethod: "oauth",
-			})
-		}
-		cfg.Agents.Defaults.ModelName = "gemini-flash"
-	}
-
-	if err := config.SaveConfig(configPath, cfg); err != nil {
-		log.Printf("Warning: could not update config: %v", err)
-	}
-}
-
-// clearAuthMethodInConfig clears auth_method for a specific provider in config.json.
-func clearAuthMethodInConfig(configPath, provider string) {
-	cfg, err := config.LoadConfig(configPath)
-	if err != nil {
-		return
-	}
-
-	for i := range cfg.ModelList {
-		switch provider {
-		case "openai":
-			if isOpenAIModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = ""
-			}
-		case "anthropic":
-			if isAnthropicModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = ""
-			}
-		case "google-antigravity", "antigravity":
-			if isAntigravityModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = ""
-			}
-		}
-	}
-
-	switch provider {
-	case "openai":
-		cfg.Providers.OpenAI.AuthMethod = ""
-	case "anthropic":
-		cfg.Providers.Anthropic.AuthMethod = ""
-	case "google-antigravity", "antigravity":
-		cfg.Providers.Antigravity.AuthMethod = ""
-	}
-
-	config.SaveConfig(configPath, cfg)
-}
-
-// clearAllAuthMethodsInConfig clears auth_method for all providers in config.json.
-func clearAllAuthMethodsInConfig(configPath string) {
-	cfg, err := config.LoadConfig(configPath)
-	if err != nil {
-		return
-	}
-	for i := range cfg.ModelList {
-		cfg.ModelList[i].AuthMethod = ""
-	}
-	cfg.Providers.OpenAI.AuthMethod = ""
-	cfg.Providers.Anthropic.AuthMethod = ""
-	cfg.Providers.Antigravity.AuthMethod = ""
-	config.SaveConfig(configPath, cfg)
-}
-
-// ── Model identification helpers ─────────────────────────────────
-
-func isOpenAIModel(model string) bool {
-	return model == "openai" || strings.HasPrefix(model, "openai/")
-}
-
-func isAnthropicModel(model string) bool {
-	return model == "anthropic" || strings.HasPrefix(model, "anthropic/")
-}
-
-func isAntigravityModel(model string) bool {
-	return model == "antigravity" || model == "google-antigravity" ||
-		strings.HasPrefix(model, "antigravity/") || strings.HasPrefix(model, "google-antigravity/")
-}

cmd/picoclaw-launcher/internal/server/auth_config_test.go

@@ -1,222 +0,0 @@
-package server
-
-import (
-	"path/filepath"
-	"testing"
-
-	"github.com/sipeed/picoclaw/pkg/auth"
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-// ── Model identification helpers ─────────────────────────────────
-
-func TestIsOpenAIModel(t *testing.T) {
-	tests := []struct {
-		model string
-		want  bool
-	}{
-		{"openai", true},
-		{"openai/gpt-4o", true},
-		{"openai/gpt-5.2", true},
-		{"anthropic", false},
-		{"anthropic/claude-sonnet-4.6", false},
-		{"openai-compatible", false},
-		{"", false},
-	}
-	for _, tt := range tests {
-		if got := isOpenAIModel(tt.model); got != tt.want {
-			t.Errorf("isOpenAIModel(%q) = %v, want %v", tt.model, got, tt.want)
-		}
-	}
-}
-
-func TestIsAnthropicModel(t *testing.T) {
-	tests := []struct {
-		model string
-		want  bool
-	}{
-		{"anthropic", true},
-		{"anthropic/claude-sonnet-4.6", true},
-		{"openai", false},
-		{"openai/gpt-4o", false},
-		{"", false},
-	}
-	for _, tt := range tests {
-		if got := isAnthropicModel(tt.model); got != tt.want {
-			t.Errorf("isAnthropicModel(%q) = %v, want %v", tt.model, got, tt.want)
-		}
-	}
-}
-
-func TestIsAntigravityModel(t *testing.T) {
-	tests := []struct {
-		model string
-		want  bool
-	}{
-		{"antigravity", true},
-		{"google-antigravity", true},
-		{"antigravity/gemini-3-flash", true},
-		{"google-antigravity/gemini-3-flash", true},
-		{"openai", false},
-		{"antigravity-custom", false},
-		{"", false},
-	}
-	for _, tt := range tests {
-		if got := isAntigravityModel(tt.model); got != tt.want {
-			t.Errorf("isAntigravityModel(%q) = %v, want %v", tt.model, got, tt.want)
-		}
-	}
-}
-
-// ── Config update helpers ────────────────────────────────────────
-
-func writeTempConfigViaSave(t *testing.T, cfg *config.Config) string {
-	t.Helper()
-	dir := t.TempDir()
-	path := filepath.Join(dir, "config.json")
-	if err := config.SaveConfig(path, cfg); err != nil {
-		t.Fatalf("save config: %v", err)
-	}
-	return path
-}
-
-func loadTempConfig(t *testing.T, path string) *config.Config {
-	t.Helper()
-	cfg, err := config.LoadConfig(path)
-	if err != nil {
-		t.Fatalf("load config: %v", err)
-	}
-	return cfg
-}
-
-func TestUpdateConfigAfterLogin_OpenAI_ExistingModel(t *testing.T) {
-	cfg := &config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "gpt-4o", Model: "openai/gpt-4o"},
-		},
-	}
-	path := writeTempConfigViaSave(t, cfg)
-
-	cred := &auth.AuthCredential{AuthMethod: "oauth"}
-	updateConfigAfterLogin(path, "openai", cred)
-
-	result := loadTempConfig(t, path)
-
-	// Model-level auth_method persists through serialization
-	if len(result.ModelList) != 1 {
-		t.Fatalf("expected 1 model, got %d", len(result.ModelList))
-	}
-	if result.ModelList[0].AuthMethod != "oauth" {
-		t.Errorf("expected model auth_method=oauth, got %q", result.ModelList[0].AuthMethod)
-	}
-}
-
-func TestUpdateConfigAfterLogin_OpenAI_NoExistingModel(t *testing.T) {
-	cfg := &config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6"},
-		},
-	}
-	path := writeTempConfigViaSave(t, cfg)
-
-	cred := &auth.AuthCredential{AuthMethod: "oauth"}
-	updateConfigAfterLogin(path, "openai", cred)
-
-	result := loadTempConfig(t, path)
-
-	if len(result.ModelList) != 2 {
-		t.Fatalf("expected 2 models (original + added), got %d", len(result.ModelList))
-	}
-	if result.ModelList[1].Model != "openai/gpt-5.2" {
-		t.Errorf("expected added model openai/gpt-5.2, got %q", result.ModelList[1].Model)
-	}
-	if result.Agents.Defaults.ModelName != "gpt-5.2" {
-		t.Errorf("expected default model_name=gpt-5.2, got %q", result.Agents.Defaults.ModelName)
-	}
-}
-
-func TestUpdateConfigAfterLogin_Anthropic(t *testing.T) {
-	cfg := &config.Config{}
-	path := writeTempConfigViaSave(t, cfg)
-
-	cred := &auth.AuthCredential{AuthMethod: "token"}
-	updateConfigAfterLogin(path, "anthropic", cred)
-
-	result := loadTempConfig(t, path)
-
-	// Model should be added with correct auth_method
-	if len(result.ModelList) != 1 {
-		t.Fatalf("expected 1 model added, got %d", len(result.ModelList))
-	}
-	if result.ModelList[0].Model != "anthropic/claude-sonnet-4.6" {
-		t.Errorf("expected model anthropic/claude-sonnet-4.6, got %q", result.ModelList[0].Model)
-	}
-	if result.ModelList[0].AuthMethod != "token" {
-		t.Errorf("expected model auth_method=token, got %q", result.ModelList[0].AuthMethod)
-	}
-}
-
-func TestUpdateConfigAfterLogin_GoogleAntigravity(t *testing.T) {
-	cfg := &config.Config{}
-	path := writeTempConfigViaSave(t, cfg)
-
-	cred := &auth.AuthCredential{AuthMethod: "oauth"}
-	updateConfigAfterLogin(path, "google-antigravity", cred)
-
-	result := loadTempConfig(t, path)
-
-	// Model should be added with correct auth_method
-	if len(result.ModelList) != 1 {
-		t.Fatalf("expected 1 model added, got %d", len(result.ModelList))
-	}
-	if result.ModelList[0].Model != "antigravity/gemini-3-flash" {
-		t.Errorf("expected model antigravity/gemini-3-flash, got %q", result.ModelList[0].Model)
-	}
-	if result.ModelList[0].AuthMethod != "oauth" {
-		t.Errorf("expected model auth_method=oauth, got %q", result.ModelList[0].AuthMethod)
-	}
-}
-
-func TestClearAuthMethodInConfig(t *testing.T) {
-	cfg := &config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "gpt-4o", Model: "openai/gpt-4o", AuthMethod: "oauth"},
-			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
-		},
-	}
-	path := writeTempConfigViaSave(t, cfg)
-
-	clearAuthMethodInConfig(path, "openai")
-
-	result := loadTempConfig(t, path)
-
-	// Openai model auth_method should be cleared
-	if result.ModelList[0].AuthMethod != "" {
-		t.Errorf("expected openai model auth_method cleared, got %q", result.ModelList[0].AuthMethod)
-	}
-	// Anthropic model should be unchanged
-	if result.ModelList[1].AuthMethod != "token" {
-		t.Errorf("expected anthropic model auth_method unchanged, got %q", result.ModelList[1].AuthMethod)
-	}
-}
-
-func TestClearAllAuthMethodsInConfig(t *testing.T) {
-	cfg := &config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "gpt-4o", Model: "openai/gpt-4o", AuthMethod: "oauth"},
-			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
-			{ModelName: "gemini", Model: "antigravity/gemini-3-flash", AuthMethod: "oauth"},
-		},
-	}
-	path := writeTempConfigViaSave(t, cfg)
-
-	clearAllAuthMethodsInConfig(path)
-
-	result := loadTempConfig(t, path)
-
-	for i, m := range result.ModelList {
-		if m.AuthMethod != "" {
-			t.Errorf("model[%d] auth_method not cleared, got %q", i, m.AuthMethod)
-		}
-	}
-}

cmd/picoclaw-launcher/internal/server/auth_handlers.go

@@ -1,315 +0,0 @@
-package server
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"log"
-	"net/http"
-	"sync"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/auth"
-	"github.com/sipeed/picoclaw/pkg/providers"
-)
-
-// oauthSession stores in-flight OAuth state for browser-based flows.
-type oauthSession struct {
-	Provider    string
-	PKCE        auth.PKCECodes
-	State       string
-	RedirectURI string
-	OAuthCfg    auth.OAuthProviderConfig
-	ConfigPath  string
-}
-
-// deviceCodeSession stores in-flight device code flow state.
-type deviceCodeSession struct {
-	mu         sync.Mutex
-	Provider   string
-	Info       *auth.DeviceCodeInfo
-	OAuthCfg   auth.OAuthProviderConfig
-	ConfigPath string
-	Status     string // "pending", "success", "error"
-	Error      string
-	Done       bool
-}
-
-var (
-	oauthSessions   = map[string]*oauthSession{} // keyed by state
-	oauthSessionsMu sync.Mutex
-
-	activeDeviceSession   *deviceCodeSession
-	activeDeviceSessionMu sync.Mutex
-)
-
-// handleOpenAILogin starts the OpenAI device code flow and returns device code info to the frontend.
-func handleOpenAILogin(w http.ResponseWriter, configPath string) {
-	// Check if there's already a pending device code session
-	activeDeviceSessionMu.Lock()
-	if activeDeviceSession != nil {
-		activeDeviceSession.mu.Lock()
-		if !activeDeviceSession.Done {
-			resp := map[string]any{
-				"status":     "pending",
-				"device_url": activeDeviceSession.Info.VerifyURL,
-				"user_code":  activeDeviceSession.Info.UserCode,
-				"message":    "Device code flow already in progress. Enter the code in your browser.",
-			}
-			activeDeviceSession.mu.Unlock()
-			activeDeviceSessionMu.Unlock()
-			w.Header().Set("Content-Type", "application/json")
-			json.NewEncoder(w).Encode(resp)
-			return
-		}
-		activeDeviceSession.mu.Unlock()
-	}
-	activeDeviceSessionMu.Unlock()
-
-	// Request a device code
-	oauthCfg := auth.OpenAIOAuthConfig()
-	info, err := auth.RequestDeviceCode(oauthCfg)
-	if err != nil {
-		http.Error(w, fmt.Sprintf("Failed to request device code: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	session := &deviceCodeSession{
-		Provider:   "openai",
-		Info:       info,
-		OAuthCfg:   oauthCfg,
-		ConfigPath: configPath,
-		Status:     "pending",
-	}
-
-	activeDeviceSessionMu.Lock()
-	activeDeviceSession = session
-	activeDeviceSessionMu.Unlock()
-
-	// Start background polling
-	go func() {
-		deadline := time.After(15 * time.Minute)
-		ticker := time.NewTicker(time.Duration(info.Interval) * time.Second)
-		defer ticker.Stop()
-
-		for {
-			select {
-			case <-deadline:
-				session.mu.Lock()
-				session.Status = "error"
-				session.Error = "Authentication timed out after 15 minutes"
-				session.Done = true
-				session.mu.Unlock()
-				return
-			case <-ticker.C:
-				cred, err := auth.PollDeviceCodeOnce(oauthCfg, info.DeviceAuthID, info.UserCode)
-				if err != nil {
-					continue // Still pending
-				}
-				if cred != nil {
-					if saveErr := auth.SetCredential("openai", cred); saveErr != nil {
-						session.mu.Lock()
-						session.Status = "error"
-						session.Error = saveErr.Error()
-						session.Done = true
-						session.mu.Unlock()
-						return
-					}
-					updateConfigAfterLogin(configPath, "openai", cred)
-					session.mu.Lock()
-					session.Status = "success"
-					session.Done = true
-					session.mu.Unlock()
-					log.Printf("OpenAI device code login successful (account: %s)", cred.AccountID)
-					return
-				}
-			}
-		}
-	}()
-
-	// Return device code info to frontend
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]any{
-		"status":     "pending",
-		"device_url": info.VerifyURL,
-		"user_code":  info.UserCode,
-		"message":    "Open the URL and enter the code to authenticate.",
-	})
-}
-
-// handleAnthropicLogin saves a pasted API token for Anthropic.
-func handleAnthropicLogin(w http.ResponseWriter, token, configPath string) {
-	if token == "" {
-		http.Error(w, "Token is required for Anthropic login", http.StatusBadRequest)
-		return
-	}
-
-	cred := &auth.AuthCredential{
-		AccessToken: token,
-		Provider:    "anthropic",
-		AuthMethod:  "token",
-	}
-
-	if err := auth.SetCredential("anthropic", cred); err != nil {
-		http.Error(w, fmt.Sprintf("Failed to save credentials: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	updateConfigAfterLogin(configPath, "anthropic", cred)
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{
-		"status":  "success",
-		"message": "Anthropic token saved",
-	})
-}
-
-// handleGoogleAntigravityLogin generates a PKCE + auth URL and returns it to the frontend.
-func handleGoogleAntigravityLogin(w http.ResponseWriter, r *http.Request, configPath string) {
-	oauthCfg := auth.GoogleAntigravityOAuthConfig()
-
-	pkce, err := auth.GeneratePKCE()
-	if err != nil {
-		http.Error(w, fmt.Sprintf("Failed to generate PKCE: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	state, err := auth.GenerateState()
-	if err != nil {
-		http.Error(w, fmt.Sprintf("Failed to generate state: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	// Build redirect URI pointing to picoclaw-launcher's own callback
-	scheme := "http"
-	redirectURI := fmt.Sprintf("%s://%s/auth/callback", scheme, r.Host)
-
-	authURL := auth.BuildAuthorizeURL(oauthCfg, pkce, state, redirectURI)
-
-	// Store session for callback
-	oauthSessionsMu.Lock()
-	oauthSessions[state] = &oauthSession{
-		Provider:    "google-antigravity",
-		PKCE:        pkce,
-		State:       state,
-		RedirectURI: redirectURI,
-		OAuthCfg:    oauthCfg,
-		ConfigPath:  configPath,
-	}
-	oauthSessionsMu.Unlock()
-
-	// Clean up stale sessions after 10 minutes
-	go func() {
-		time.Sleep(10 * time.Minute)
-		oauthSessionsMu.Lock()
-		delete(oauthSessions, state)
-		oauthSessionsMu.Unlock()
-	}()
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{
-		"status":   "redirect",
-		"auth_url": authURL,
-		"message":  "Open the URL to authenticate with Google.",
-	})
-}
-
-// handleOAuthCallback processes the OAuth callback from Google Antigravity.
-func handleOAuthCallback(w http.ResponseWriter, r *http.Request) {
-	state := r.URL.Query().Get("state")
-	code := r.URL.Query().Get("code")
-
-	oauthSessionsMu.Lock()
-	session, ok := oauthSessions[state]
-	if ok {
-		delete(oauthSessions, state)
-	}
-	oauthSessionsMu.Unlock()
-
-	if !ok {
-		http.Error(w, "Invalid or expired OAuth state", http.StatusBadRequest)
-		return
-	}
-
-	if code == "" {
-		errMsg := r.URL.Query().Get("error")
-		w.Header().Set("Content-Type", "text/html")
-		fmt.Fprintf(
-			w,
-			`<html><body><h2>Authentication failed</h2><p>%s</p><p>You can close this window.</p></body></html>`,
-			errMsg,
-		)
-		return
-	}
-
-	cred, err := auth.ExchangeCodeForTokens(session.OAuthCfg, code, session.PKCE.CodeVerifier, session.RedirectURI)
-	if err != nil {
-		w.Header().Set("Content-Type", "text/html")
-		fmt.Fprintf(
-			w,
-			`<html><body><h2>Authentication failed</h2><p>%s</p><p>You can close this window.</p></body></html>`,
-			err.Error(),
-		)
-		return
-	}
-
-	cred.Provider = session.Provider
-
-	// Fetch user info for Google Antigravity
-	if session.Provider == "google-antigravity" {
-		if email, err := fetchGoogleUserEmail(cred.AccessToken); err == nil {
-			cred.Email = email
-		}
-		if projectID, err := providers.FetchAntigravityProjectID(cred.AccessToken); err == nil {
-			cred.ProjectID = projectID
-		}
-	}
-
-	if err := auth.SetCredential(session.Provider, cred); err != nil {
-		w.Header().Set("Content-Type", "text/html")
-		fmt.Fprintf(w, `<html><body><h2>Failed to save credentials</h2><p>%s</p></body></html>`, err.Error())
-		return
-	}
-
-	updateConfigAfterLogin(session.ConfigPath, session.Provider, cred)
-
-	// Redirect back to picoclaw-launcher UI
-	w.Header().Set("Content-Type", "text/html")
-	fmt.Fprintf(w, `<html><body>
-		<h2>Authentication successful!</h2>
-		<p>Redirecting back to Config Editor...</p>
-		<script>setTimeout(function(){ window.location.href = '/#auth'; }, 1000);</script>
-	</body></html>`)
-}
-
-// fetchGoogleUserEmail retrieves the user's email from Google's userinfo endpoint.
-func fetchGoogleUserEmail(accessToken string) (string, error) {
-	req, err := http.NewRequest("GET", "https://www.googleapis.com/oauth2/v2/userinfo", nil)
-	if err != nil {
-		return "", err
-	}
-	req.Header.Set("Authorization", "Bearer "+accessToken)
-
-	client := &http.Client{Timeout: 10 * time.Second}
-	resp, err := client.Do(req)
-	if err != nil {
-		return "", err
-	}
-	defer resp.Body.Close()
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", fmt.Errorf("reading userinfo response: %w", err)
-	}
-	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("userinfo request failed: %s", string(body))
-	}
-
-	var userInfo struct {
-		Email string `json:"email"`
-	}
-	if err := json.Unmarshal(body, &userInfo); err != nil {
-		return "", err
-	}
-	return userInfo.Email, nil
-}

cmd/picoclaw-launcher/internal/server/logbuffer_test.go

@@ -1,116 +0,0 @@
-package server
-
-import (
-	"fmt"
-	"sync"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestLogBuffer_Basic(t *testing.T) {
-	buf := NewLogBuffer(5)
-
-	// Empty buffer
-	lines, total, runID := buf.LinesSince(0)
-	assert.Nil(t, lines)
-	assert.Equal(t, 0, total)
-	assert.Equal(t, 0, runID)
-
-	// Append some lines
-	buf.Append("line1")
-	buf.Append("line2")
-	buf.Append("line3")
-
-	lines, total, runID = buf.LinesSince(0)
-	assert.Equal(t, []string{"line1", "line2", "line3"}, lines)
-	assert.Equal(t, 3, total)
-	assert.Equal(t, 0, runID)
-
-	// Incremental read
-	lines, total, _ = buf.LinesSince(2)
-	assert.Equal(t, []string{"line3"}, lines)
-	assert.Equal(t, 3, total)
-
-	// No new lines
-	lines, total, _ = buf.LinesSince(3)
-	assert.Nil(t, lines)
-	assert.Equal(t, 3, total)
-}
-
-func TestLogBuffer_Wrap(t *testing.T) {
-	buf := NewLogBuffer(3)
-
-	buf.Append("a")
-	buf.Append("b")
-	buf.Append("c")
-	buf.Append("d") // evicts "a"
-	buf.Append("e") // evicts "b"
-
-	lines, total, _ := buf.LinesSince(0)
-	assert.Equal(t, []string{"c", "d", "e"}, lines)
-	assert.Equal(t, 5, total)
-
-	// Incremental after wrap
-	lines, total, _ = buf.LinesSince(3)
-	assert.Equal(t, []string{"d", "e"}, lines)
-	assert.Equal(t, 5, total)
-
-	// Offset too old (before buffer start), get all buffered
-	lines, total, _ = buf.LinesSince(1)
-	assert.Equal(t, []string{"c", "d", "e"}, lines)
-	assert.Equal(t, 5, total)
-}
-
-func TestLogBuffer_Reset(t *testing.T) {
-	buf := NewLogBuffer(5)
-
-	buf.Append("before")
-	assert.Equal(t, 0, buf.RunID())
-
-	buf.Reset()
-	assert.Equal(t, 1, buf.RunID())
-	assert.Equal(t, 0, buf.Total())
-
-	lines, total, runID := buf.LinesSince(0)
-	assert.Nil(t, lines)
-	assert.Equal(t, 0, total)
-	assert.Equal(t, 1, runID)
-
-	buf.Append("after")
-	lines, total, runID = buf.LinesSince(0)
-	assert.Equal(t, []string{"after"}, lines)
-	assert.Equal(t, 1, total)
-	assert.Equal(t, 1, runID)
-}
-
-func TestLogBuffer_Concurrent(t *testing.T) {
-	buf := NewLogBuffer(100)
-	var wg sync.WaitGroup
-
-	// 10 writers
-	for i := range 10 {
-		wg.Add(1)
-		go func(id int) {
-			defer wg.Done()
-			for j := range 50 {
-				buf.Append(fmt.Sprintf("writer-%d-line-%d", id, j))
-			}
-		}(i)
-	}
-
-	// 5 readers
-	for range 5 {
-		wg.Add(1)
-		go func() {
-			defer wg.Done()
-			for range 100 {
-				buf.LinesSince(0)
-			}
-		}()
-	}
-
-	wg.Wait()
-
-	assert.Equal(t, 500, buf.Total())
-}

cmd/picoclaw-launcher/internal/server/process.go

@@ -1,232 +0,0 @@
-package server
-
-import (
-	"bufio"
-	"encoding/json"
-	"fmt"
-	"io"
-	"log"
-	"net"
-	"net/http"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-	"strconv"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-// gatewayLogs stores captured stdout/stderr from the gateway process launched by the launcher.
-var gatewayLogs = NewLogBuffer(200)
-
-// RegisterProcessAPI registers endpoints to start, stop and check status of the picoclaw gateway.
-func RegisterProcessAPI(mux *http.ServeMux, absPath string) {
-	mux.HandleFunc("GET /api/process/status", func(w http.ResponseWriter, r *http.Request) {
-		handleStatusGateway(w, r, absPath)
-	})
-	mux.HandleFunc("POST /api/process/start", handleStartGateway)
-	mux.HandleFunc("POST /api/process/stop", handleStopGateway)
-}
-
-func handleStartGateway(w http.ResponseWriter, r *http.Request) {
-	// Locate picoclaw executable:
-	// 1. Try same directory as current executable
-	// 2. Fallback to just "picoclaw" (relies on $PATH)
-	execPath := "picoclaw"
-
-	if exe, err := os.Executable(); err == nil {
-		dir := filepath.Dir(exe)
-		candidate := filepath.Join(dir, "picoclaw")
-		if runtime.GOOS == "windows" {
-			candidate += ".exe"
-		}
-
-		if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
-			execPath = candidate
-		}
-	}
-
-	cmd := exec.Command(execPath, "gateway")
-
-	stdoutPipe, err := cmd.StdoutPipe()
-	if err != nil {
-		log.Printf("Failed to create stdout pipe: %v\n", err)
-		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	stderrPipe, err := cmd.StderrPipe()
-	if err != nil {
-		log.Printf("Failed to create stderr pipe: %v\n", err)
-		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	// Clear old logs and increment runID before starting
-	gatewayLogs.Reset()
-
-	if err := cmd.Start(); err != nil {
-		log.Printf("Failed to start picoclaw gateway: %v\n", err)
-		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	// Read stdout and stderr into the log buffer
-	go scanPipe(stdoutPipe, gatewayLogs)
-	go scanPipe(stderrPipe, gatewayLogs)
-
-	// Wait for the process to exit in the background to avoid zombies
-	go func() {
-		if err := cmd.Wait(); err != nil {
-			log.Printf("Gateway process exited: %v\n", err)
-		}
-	}()
-
-	log.Printf("Started picoclaw gateway (PID: %d) from %s\n", cmd.Process.Pid, execPath)
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]any{
-		"status": "ok",
-		"pid":    cmd.Process.Pid,
-	})
-}
-
-// scanPipe reads lines from r and appends them to buf. It returns when r reaches EOF.
-func scanPipe(r io.Reader, buf *LogBuffer) {
-	scanner := bufio.NewScanner(r)
-	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024) // up to 1MB per line
-
-	for scanner.Scan() {
-		buf.Append(scanner.Text())
-	}
-}
-
-func handleStopGateway(w http.ResponseWriter, r *http.Request) {
-	var err error
-	if runtime.GOOS == "windows" {
-		// Kill via taskkill finding picoclaw.exe (though it might kill this config tool if it's named picoclaw-launcher.exe...? No, /IM does exact match usually, but just to be safe let's stop exactly picoclaw.exe)
-		// Alternatively, we use powershell to kill processes with commandline containing 'gateway'
-		psCmd := `Get-WmiObject Win32_Process | Where-Object { $_.CommandLine -match 'picoclaw.*gateway' } | ForEach-Object { Stop-Process $_.ProcessId -Force }`
-		err = exec.Command("powershell", "-Command", psCmd).Run()
-	} else {
-		// Linux/macOS
-		err = exec.Command("pkill", "-f", "picoclaw gateway").Run()
-	}
-
-	if err != nil {
-		log.Printf("Warning: Failed to stop gateway (perhaps not running?): %v\n", err)
-		// We still return 200 OK because pkill returns an error if no process was found
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]any{
-			"status": "ok", // or "not_found"
-			"msg":    "Stop command executed, but returned error (process might not be running).",
-			"error":  err.Error(),
-		})
-		return
-	}
-
-	log.Printf("Stopped picoclaw gateway processes.\n")
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{
-		"status": "ok",
-	})
-}
-
-func handleStatusGateway(w http.ResponseWriter, r *http.Request, absPath string) {
-	cfg, cfgErr := config.LoadConfig(absPath)
-	host := "127.0.0.1"
-	port := 18790
-	if cfgErr == nil && cfg != nil {
-		if cfg.Gateway.Host != "" && cfg.Gateway.Host != "0.0.0.0" {
-			host = cfg.Gateway.Host
-		}
-		if cfg.Gateway.Port != 0 {
-			port = cfg.Gateway.Port
-		}
-	}
-
-	url := fmt.Sprintf("http://%s/health", net.JoinHostPort(host, strconv.Itoa(port)))
-	client := http.Client{Timeout: 2 * time.Second}
-	resp, err := client.Get(url)
-
-	// Build the response data map
-	data := map[string]any{}
-
-	if err != nil {
-		data["process_status"] = "stopped"
-		data["error"] = err.Error()
-	} else {
-		defer resp.Body.Close()
-
-		if resp.StatusCode != http.StatusOK {
-			data["process_status"] = "error"
-			data["status_code"] = resp.StatusCode
-		} else {
-			var healthData map[string]any
-			if decErr := json.NewDecoder(resp.Body).Decode(&healthData); decErr != nil {
-				data["process_status"] = "error"
-				data["error"] = "invalid response from gateway"
-			} else {
-				// Gateway is running and responded properly — merge health data
-				for k, v := range healthData {
-					data[k] = v
-				}
-				data["process_status"] = "running"
-			}
-		}
-	}
-
-	// Append log data from the buffer
-	appendLogData(r, data)
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(data)
-}
-
-// appendLogData reads log_offset and log_run_id query params from the request and
-// populates the response data map with incremental log lines.
-func appendLogData(r *http.Request, data map[string]any) {
-	clientOffset := 0
-	clientRunID := -1
-
-	if v := r.URL.Query().Get("log_offset"); v != "" {
-		if n, err := strconv.Atoi(v); err == nil {
-			clientOffset = n
-		}
-	}
-
-	if v := r.URL.Query().Get("log_run_id"); v != "" {
-		if n, err := strconv.Atoi(v); err == nil {
-			clientRunID = n
-		}
-	}
-
-	runID := gatewayLogs.RunID()
-
-	// If runID is 0 (never reset = never launched from this launcher), report no source
-	if runID == 0 {
-		data["logs"] = []string{}
-		data["log_total"] = 0
-		data["log_run_id"] = 0
-		data["log_source"] = "none"
-		return
-	}
-
-	// If the client's runID doesn't match, send all buffered lines (gateway restarted)
-	offset := clientOffset
-	if clientRunID != runID {
-		offset = 0
-	}
-
-	lines, total, runID := gatewayLogs.LinesSince(offset)
-	if lines == nil {
-		lines = []string{}
-	}
-
-	data["logs"] = lines
-	data["log_total"] = total
-	data["log_run_id"] = runID
-	data["log_source"] = "launcher"
-}

cmd/picoclaw-launcher/internal/server/server.go

@@ -1,196 +0,0 @@
-package server
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"log"
-	"net/http"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/auth"
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-const DefaultPort = "18800"
-
-// providerStatus represents the auth status of a single provider in API responses.
-type providerStatus struct {
-	Provider   string `json:"provider"`
-	AuthMethod string `json:"auth_method"`
-	Status     string `json:"status"`
-	AccountID  string `json:"account_id,omitempty"`
-	Email      string `json:"email,omitempty"`
-	ProjectID  string `json:"project_id,omitempty"`
-	ExpiresAt  string `json:"expires_at,omitempty"`
-}
-
-// ── Route registration ───────────────────────────────────────────
-
-func RegisterConfigAPI(mux *http.ServeMux, absPath string) {
-	// GET /api/config — read config
-	mux.HandleFunc("GET /api/config", func(w http.ResponseWriter, r *http.Request) {
-		cfg, err := config.LoadConfig(absPath)
-		if err != nil {
-			http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
-			return
-		}
-		w.Header().Set("Content-Type", "application/json")
-		resp := map[string]any{
-			"config": cfg,
-			"path":   absPath,
-		}
-		enc := json.NewEncoder(w)
-		enc.SetIndent("", "  ")
-		if err := enc.Encode(resp); err != nil {
-			log.Printf("Failed to encode response: %v", err)
-		}
-	})
-
-	// PUT /api/config — save config
-	mux.HandleFunc("PUT /api/config", func(w http.ResponseWriter, r *http.Request) {
-		body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
-		if err != nil {
-			http.Error(w, "Failed to read request body", http.StatusBadRequest)
-			return
-		}
-		defer r.Body.Close()
-
-		var cfg config.Config
-		if err := json.Unmarshal(body, &cfg); err != nil {
-			http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
-			return
-		}
-
-		if err := config.SaveConfig(absPath, &cfg); err != nil {
-			http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
-			return
-		}
-
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
-	})
-}
-
-func RegisterAuthAPI(mux *http.ServeMux, absPath string) {
-	// GET /api/auth/status — all authenticated providers + pending login state
-	mux.HandleFunc("GET /api/auth/status", func(w http.ResponseWriter, r *http.Request) {
-		store, err := auth.LoadStore()
-		if err != nil {
-			http.Error(w, fmt.Sprintf("Failed to load auth store: %v", err), http.StatusInternalServerError)
-			return
-		}
-
-		result := []providerStatus{}
-		for name, cred := range store.Credentials {
-			status := "active"
-			if cred.IsExpired() {
-				status = "expired"
-			} else if cred.NeedsRefresh() {
-				status = "needs_refresh"
-			}
-			ps := providerStatus{
-				Provider:   name,
-				AuthMethod: cred.AuthMethod,
-				Status:     status,
-				AccountID:  cred.AccountID,
-				Email:      cred.Email,
-				ProjectID:  cred.ProjectID,
-			}
-			if !cred.ExpiresAt.IsZero() {
-				ps.ExpiresAt = cred.ExpiresAt.Format(time.RFC3339)
-			}
-			result = append(result, ps)
-		}
-
-		// Include pending device code state
-		var pendingDevice map[string]any
-		activeDeviceSessionMu.Lock()
-		if activeDeviceSession != nil {
-			activeDeviceSession.mu.Lock()
-			pendingDevice = map[string]any{
-				"provider":   activeDeviceSession.Provider,
-				"status":     activeDeviceSession.Status,
-				"device_url": activeDeviceSession.Info.VerifyURL,
-				"user_code":  activeDeviceSession.Info.UserCode,
-			}
-			if activeDeviceSession.Error != "" {
-				pendingDevice["error"] = activeDeviceSession.Error
-			}
-			if activeDeviceSession.Done {
-				activeDeviceSession.mu.Unlock()
-				activeDeviceSession = nil
-			} else {
-				activeDeviceSession.mu.Unlock()
-			}
-		}
-		activeDeviceSessionMu.Unlock()
-
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]any{
-			"providers":      result,
-			"pending_device": pendingDevice,
-		})
-	})
-
-	// POST /api/auth/login — initiate provider login
-	mux.HandleFunc("POST /api/auth/login", func(w http.ResponseWriter, r *http.Request) {
-		var req struct {
-			Provider string `json:"provider"`
-			Token    string `json:"token,omitempty"`
-		}
-		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-			http.Error(w, "Invalid request body", http.StatusBadRequest)
-			return
-		}
-
-		switch req.Provider {
-		case "openai":
-			handleOpenAILogin(w, absPath)
-		case "anthropic":
-			handleAnthropicLogin(w, req.Token, absPath)
-		case "google-antigravity", "antigravity":
-			handleGoogleAntigravityLogin(w, r, absPath)
-		default:
-			http.Error(
-				w,
-				fmt.Sprintf(
-					"Unsupported provider: %s (supported: openai, anthropic, google-antigravity)",
-					req.Provider,
-				),
-				http.StatusBadRequest,
-			)
-		}
-	})
-
-	// POST /api/auth/logout — logout a provider
-	mux.HandleFunc("POST /api/auth/logout", func(w http.ResponseWriter, r *http.Request) {
-		var req struct {
-			Provider string `json:"provider"`
-		}
-		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-			http.Error(w, "Invalid request body", http.StatusBadRequest)
-			return
-		}
-
-		if req.Provider == "" {
-			if err := auth.DeleteAllCredentials(); err != nil {
-				http.Error(w, fmt.Sprintf("Failed to logout: %v", err), http.StatusInternalServerError)
-				return
-			}
-			clearAllAuthMethodsInConfig(absPath)
-		} else {
-			if err := auth.DeleteCredential(req.Provider); err != nil {
-				http.Error(w, fmt.Sprintf("Failed to logout: %v", err), http.StatusInternalServerError)
-				return
-			}
-			clearAuthMethodInConfig(absPath, req.Provider)
-		}
-
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
-	})
-
-	// GET /auth/callback — OAuth browser callback for Google Antigravity
-	mux.HandleFunc("GET /auth/callback", handleOAuthCallback)
-}

cmd/picoclaw-launcher/internal/server/server_test.go

@@ -1,247 +0,0 @@
-package server
-
-import (
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-// ── Config API tests ─────────────────────────────────────────────
-
-func setupConfigMux(t *testing.T, cfg *config.Config) (*http.ServeMux, string) {
-	t.Helper()
-	dir := t.TempDir()
-	path := filepath.Join(dir, "config.json")
-	data, err := json.MarshalIndent(cfg, "", "  ")
-	if err != nil {
-		t.Fatalf("marshal config: %v", err)
-	}
-	if err := os.WriteFile(path, data, 0o600); err != nil {
-		t.Fatalf("write config: %v", err)
-	}
-
-	mux := http.NewServeMux()
-	RegisterConfigAPI(mux, path)
-	RegisterAuthAPI(mux, path)
-	return mux, path
-}
-
-func TestGetConfig(t *testing.T) {
-	cfg := &config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "gpt-4o", Model: "openai/gpt-4o"},
-		},
-	}
-	mux, path := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("GET", "/api/config", nil)
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusOK {
-		t.Fatalf("GET /api/config: expected 200, got %d: %s", w.Code, w.Body.String())
-	}
-
-	var resp struct {
-		Config config.Config `json:"config"`
-		Path   string        `json:"path"`
-	}
-	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
-		t.Fatalf("decode response: %v", err)
-	}
-
-	if resp.Path != path {
-		t.Errorf("expected path %q, got %q", path, resp.Path)
-	}
-	if len(resp.Config.ModelList) != 1 {
-		t.Errorf("expected 1 model, got %d", len(resp.Config.ModelList))
-	}
-}
-
-func TestGetConfig_MissingFile_ReturnsDefault(t *testing.T) {
-	mux := http.NewServeMux()
-	RegisterConfigAPI(mux, "/tmp/nonexistent-picoclaw-launcher-test/config.json")
-
-	req := httptest.NewRequest("GET", "/api/config", nil)
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	// LoadConfig returns a default empty config when file is missing
-	if w.Code != http.StatusOK {
-		t.Errorf("expected 200 for missing file (default config), got %d", w.Code)
-	}
-}
-
-func TestPutConfig(t *testing.T) {
-	cfg := &config.Config{}
-	mux, path := setupConfigMux(t, cfg)
-
-	newCfg := config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
-		},
-	}
-	body, _ := json.Marshal(newCfg)
-
-	req := httptest.NewRequest("PUT", "/api/config", strings.NewReader(string(body)))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusOK {
-		t.Fatalf("PUT /api/config: expected 200, got %d: %s", w.Code, w.Body.String())
-	}
-
-	saved, err := config.LoadConfig(path)
-	if err != nil {
-		t.Fatalf("load saved config: %v", err)
-	}
-	if len(saved.ModelList) != 1 {
-		t.Fatalf("expected 1 model saved, got %d", len(saved.ModelList))
-	}
-	if saved.ModelList[0].Model != "anthropic/claude-sonnet-4.6" {
-		t.Errorf("expected model anthropic/claude-sonnet-4.6, got %q", saved.ModelList[0].Model)
-	}
-}
-
-func TestPutConfig_InvalidJSON(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("PUT", "/api/config", strings.NewReader("{invalid"))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for invalid JSON, got %d", w.Code)
-	}
-}
-
-// ── Auth API tests ───────────────────────────────────────────────
-
-func TestAuthStatus(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("GET", "/api/auth/status", nil)
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusOK {
-		t.Fatalf("GET /api/auth/status: expected 200, got %d: %s", w.Code, w.Body.String())
-	}
-
-	var resp struct {
-		Providers     []providerStatus `json:"providers"`
-		PendingDevice map[string]any   `json:"pending_device"`
-	}
-	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
-		t.Fatalf("decode response: %v", err)
-	}
-
-	// providers should be a non-nil list (could be empty)
-	if resp.Providers == nil {
-		t.Error("providers should not be nil")
-	}
-}
-
-func TestAuthLogin_UnsupportedProvider(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	body := `{"provider": "unsupported"}`
-	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader(body))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for unsupported provider, got %d", w.Code)
-	}
-}
-
-func TestAuthLogin_AnthropicNoToken(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	body := `{"provider": "anthropic"}`
-	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader(body))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for anthropic without token, got %d", w.Code)
-	}
-}
-
-func TestAuthLogin_InvalidBody(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader("{bad"))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for invalid JSON body, got %d", w.Code)
-	}
-}
-
-func TestAuthLogout_InvalidBody(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("POST", "/api/auth/logout", strings.NewReader("{bad"))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for invalid body, got %d", w.Code)
-	}
-}
-
-func TestOAuthCallback_InvalidState(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("GET", "/auth/callback?state=invalid&code=test", nil)
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for invalid state, got %d", w.Code)
-	}
-}
-
-// ── Utility tests ────────────────────────────────────────────────
-
-func TestDefaultConfigPath(t *testing.T) {
-	path := DefaultConfigPath()
-	if path == "" {
-		t.Error("defaultConfigPath should not return empty")
-	}
-	if !strings.HasSuffix(path, filepath.Join(".picoclaw", "config.json")) {
-		t.Errorf("expected path ending with .picoclaw/config.json, got %q", path)
-	}
-}
-
-func TestGetLocalIP(t *testing.T) {
-	// Just ensure it doesn't panic; IP may or may not be available
-	ip := GetLocalIP()
-	if ip != "" {
-		// If returned, should look like an IP
-		if !strings.Contains(ip, ".") {
-			t.Errorf("getLocalIP returned non-IPv4 looking string: %q", ip)
-		}
-	}
-}

cmd/picoclaw-launcher/internal/server/utils.go

@@ -1,28 +0,0 @@
-package server
-
-import (
-	"net"
-	"os"
-	"path/filepath"
-)
-
-func DefaultConfigPath() string {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return "config.json"
-	}
-	return filepath.Join(home, ".picoclaw", "config.json")
-}
-
-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 ""
-}

cmd/picoclaw-launcher/main.go

@@ -1,127 +0,0 @@
-// PicoClaw Launcher - Standalone HTTP service
-//
-// Provides a web-based JSON editor for picoclaw config files,
-// with OAuth provider authentication support.
-//
-// Usage:
-//
-//	go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
-//	./picoclaw-launcher [config.json]
-//	./picoclaw-launcher -public config.json
-
-package main
-
-import (
-	"embed"
-	"flag"
-	"fmt"
-	"io/fs"
-	"log"
-	"net/http"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-	"time"
-
-	"github.com/sipeed/picoclaw/cmd/picoclaw-launcher/internal/server"
-)
-
-//go:embed internal/ui/index.html
-var staticFiles embed.FS
-
-func main() {
-	public := flag.Bool("public", false, "Listen on all interfaces (0.0.0.0) instead of localhost only")
-	flag.Usage = func() {
-		fmt.Fprintf(os.Stderr, "PicoClaw Launcher - A web-based configuration editor\n\n")
-		fmt.Fprintf(os.Stderr, "Usage: %s [options] [config.json]\n\n", os.Args[0])
-		fmt.Fprintf(os.Stderr, "Arguments:\n")
-		fmt.Fprintf(os.Stderr, "  config.json    Path to the configuration file (default: ~/.picoclaw/config.json)\n\n")
-		fmt.Fprintf(os.Stderr, "Options:\n")
-		flag.PrintDefaults()
-		fmt.Fprintf(os.Stderr, "\nExamples:\n")
-		fmt.Fprintf(os.Stderr, "  %s                          Use default config path\n", os.Args[0])
-		fmt.Fprintf(os.Stderr, "  %s ./config.json             Specify a config file\n", os.Args[0])
-		fmt.Fprintf(
-			os.Stderr,
-			"  %s -public ./config.json     Allow access from other devices on the network\n",
-			os.Args[0],
-		)
-	}
-	flag.Parse()
-
-	configPath := server.DefaultConfigPath()
-	if flag.NArg() > 0 {
-		configPath = flag.Arg(0)
-	}
-
-	absPath, err := filepath.Abs(configPath)
-	if err != nil {
-		log.Fatalf("Failed to resolve config path: %v", err)
-	}
-
-	var addr string
-	if *public {
-		addr = "0.0.0.0:" + server.DefaultPort
-	} else {
-		addr = "127.0.0.1:" + server.DefaultPort
-	}
-
-	mux := http.NewServeMux()
-	server.RegisterConfigAPI(mux, absPath)
-	server.RegisterAuthAPI(mux, absPath)
-	server.RegisterProcessAPI(mux, absPath)
-
-	staticFS, err := fs.Sub(staticFiles, "internal/ui")
-	if err != nil {
-		log.Fatalf("Failed to create sub filesystem: %v", err)
-	}
-	mux.Handle("/", http.FileServer(http.FS(staticFS)))
-
-	// Print startup banner
-	fmt.Println("=============================================")
-	fmt.Println("  PicoClaw Launcher")
-	fmt.Println("=============================================")
-	fmt.Printf("  Config file : %s\n", absPath)
-	fmt.Printf("  Listen addr : %s\n\n", addr)
-	fmt.Println("  Open the following URL in your browser")
-	fmt.Println("  to view and edit the configuration:")
-	fmt.Println()
-	fmt.Printf("    >> http://localhost:%s <<\n", server.DefaultPort)
-	if *public {
-		if ip := server.GetLocalIP(); ip != "" {
-			fmt.Printf("    >> http://%s:%s <<\n", ip, server.DefaultPort)
-		}
-	}
-	fmt.Println()
-	// fmt.Println("=============================================")
-
-	go func() {
-		// Wait briefly to ensure the server is ready before opening the browser
-		time.Sleep(500 * time.Millisecond)
-		url := "http://localhost:" + server.DefaultPort
-		if err := openBrowser(url); err != nil {
-			log.Printf("Warning: Failed to auto-open browser: %v\n", err)
-		}
-	}()
-
-	if err := http.ListenAndServe(addr, mux); err != nil {
-		log.Fatalf("Server failed: %v", err)
-	}
-}
-
-// openBrowser automatically opens the given URL in the default browser.
-func openBrowser(url string) error {
-	var err error
-	switch runtime.GOOS {
-	case "linux":
-		err = exec.Command("xdg-open", url).Start()
-	case "windows":
-		err = exec.Command("rundll32", "url.dll,FileProtocolHandler", url).Start()
-	case "darwin":
-		err = exec.Command("open", url).Start()
-	default:
-		err = fmt.Errorf("unsupported platform")
-	}
-	return err
-}

cmd/picoclaw/internal/gateway/helpers.go

@@ -19,6 +19,7 @@ import (
 	_ "github.com/sipeed/picoclaw/pkg/channels/irc"
 	_ "github.com/sipeed/picoclaw/pkg/channels/line"
 	_ "github.com/sipeed/picoclaw/pkg/channels/maixcam"
+	_ "github.com/sipeed/picoclaw/pkg/channels/matrix"
 	_ "github.com/sipeed/picoclaw/pkg/channels/onebot"
 	_ "github.com/sipeed/picoclaw/pkg/channels/pico"
 	_ "github.com/sipeed/picoclaw/pkg/channels/qq"

cmd/picoclaw/main.go

@@ -30,7 +30,7 @@ func NewPicoclawCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "picoclaw",
 		Short:   short,
-		Example: "picoclaw list",
+		Example: "picoclaw version",
 	}
 
 	cmd.AddCommand(

config/config.example.json

@@ -98,7 +98,8 @@
       "encrypt_key": "",
       "verification_token": "",
       "allow_from": [],
-      "reasoning_channel_id": ""
+      "reasoning_channel_id": "",
+      "random_reaction_emoji": []
     },
     "dingtalk": {
       "enabled": false,
@@ -114,6 +115,23 @@
       "allow_from": [],
       "reasoning_channel_id": ""
     },
+    "matrix": {
+      "enabled": false,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "device_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking... 💭"
+      },
+      "reasoning_channel_id": ""
+    },
     "line": {
       "enabled": false,
       "channel_secret": "YOUR_LINE_CHANNEL_SECRET",

docs/agent-refactor/README.md

@@ -0,0 +1,145 @@
+# Agent Refactor
+
+## What this directory is for
+
+This directory is the working area for the current Agent refactor.
+
+The purpose of this refactor is simple:
+
+the project needs a smaller, clearer, and more stable Agent model before more Agent-related behavior is added.
+
+The codebase already contains meaningful Agent behavior. What it still lacks is a sufficiently explicit and stable semantic boundary around that behavior.
+
+This refactor exists to fix that first.
+
+---
+
+## Refactor stance
+
+This is a maintenance-led consolidation effort.
+
+It is not a general invitation to expand Agent behavior in parallel.
+
+During this refactor window, Agent-related work should converge on the current refactor track instead of branching into new semantics.
+
+That means:
+
+- concept clarification before feature expansion
+- boundary tightening before abstraction growth
+- semantic consolidation before new behavior
+
+---
+
+## Core rule: minimum concepts only
+
+This refactor follows one hard rule:
+
+**do not introduce a new concept unless it is strictly necessary**
+
+More explicitly:
+
+- if an existing concept can be clarified, reuse it
+- if an existing boundary can be made explicit, do that first
+- if a behavior can be expressed without a new abstraction, do not add one
+- "future flexibility" is not enough justification on its own
+
+The goal of this refactor is not to grow the model.
+
+The goal is to reduce ambiguity.
+
+---
+
+## What is being clarified
+
+This refactor is currently concerned with the following questions:
+
+1. what an `Agent` is
+2. what an `AgentLoop` is
+3. what the lifecycle of `AgentLoop` is
+4. what the event surface around `AgentLoop` is
+5. how persona / identity is assembled
+6. how capabilities are represented
+7. how context boundaries and compression work
+8. how subagent coordination works
+
+These are the current working boundaries.
+
+If they need to be adjusted, they should be adjusted explicitly rather than drift implicitly in code.
+
+---
+
+## Status of this directory
+
+The documents here are working materials.
+
+They are not final or immutable.
+
+If current notes are incomplete, incorrectly split, or too broad, they should be revised. This directory should evolve with the refactor rather than pretending the first draft is complete.
+
+---
+
+## Suggested document split
+
+This directory may eventually contain notes such as:
+
+- `agent-overview.md`
+  - what an Agent is
+- `agent-loop.md`
+  - AgentLoop contract, lifecycle, event surface
+- `persona.md`
+  - persona and identity assembly
+- `capability.md`
+  - tools / skills / MCP capability semantics
+- `context.md`
+  - context scope, history, summary, compression
+- `subagent.md`
+  - subagent coordination rules
+
+These files should be added only when they help clarify the current refactor work.
+
+This directory should not turn into a generic architecture dump.
+
+---
+
+## What this directory is not for
+
+This directory is not intended for:
+
+- broad speculative architecture
+- future multi-node protocol design not required by the current refactor
+- parallel feature planning unrelated to Agent consolidation
+- adding new concepts before current ones are made clear
+
+If a topic does not directly help reduce ambiguity in the current Agent model, it probably does not belong here yet.
+
+---
+
+## Relationship to implementation
+
+Implementation changes should not keep redefining Agent semantics implicitly.
+
+If a PR changes or depends on Agent semantics, those semantics should either already exist here or be clarified in a linked issue first.
+
+This directory is here to make implementation narrower and more disciplined.
+
+---
+
+## Relationship to GitHub tracking
+
+The umbrella issue for this refactor should point here.
+
+The issue is the coordination surface.
+
+This directory is the repository-local working surface.
+
+---
+
+## Summary
+
+The main question of this refactor is not:
+
+- what more can Agent do
+
+The main question is:
+
+- what is the smallest stable model that current Agent behavior can be organized around

docs/channels/feishu/README.zh.md

@@ -26,7 +26,8 @@
 | app_secret         | string | 是   | 飞书应用的 App Secret            |
 | encrypt_key        | string | 否   | 事件回调加密密钥                 |
 | verification_token | string | 否   | 用于Webhook事件验证的Token       |
-| allow_from         | array  | 否   | 用户ID白名单，空表示允许所有用户 |
+| allow_from         | array  | 否   | 用户ID白名单，空表示所有用户   |
+| random_reaction_emoji | array | 否   | 随机添加的表情列表，空则使用默认 "Pin" |
 
 ## 设置流程
 
@@ -35,3 +36,4 @@
 3. 配置事件订阅和Webhook URL
 4. 设置加密(可选,生产环境建议启用)
 5. 将 App ID、App Secret、Encrypt Key 和 Verification Token(如果启用加密) 填入配置文件中
+6. 自定义你希望 PicoClaw react 你消息时的表情（可选, Reference URL: [Feishu Emoji List](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce))

docs/channels/matrix/README.md

@@ -0,0 +1,59 @@
+# Matrix Channel Configuration Guide
+
+## 1. Example Configuration
+
+Add this to `config.json`:
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "device_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking..."
+      },
+      "reasoning_channel_id": ""
+    }
+  }
+}
+```
+
+## 2. Field Reference
+
+| Field                | Type     | Required | Description |
+|----------------------|----------|----------|-------------|
+| enabled              | bool     | Yes      | Enable or disable the Matrix channel |
+| homeserver           | string   | Yes      | Matrix homeserver URL (for example `https://matrix.org`) |
+| user_id              | string   | Yes      | Bot Matrix user ID (for example `@bot:matrix.org`) |
+| access_token         | string   | Yes      | Bot access token |
+| device_id            | string   | No       | Optional Matrix device ID |
+| join_on_invite       | bool     | No       | Auto-join invited rooms |
+| allow_from           | []string | No       | User whitelist (Matrix user IDs) |
+| group_trigger        | object   | No       | Group trigger strategy (`mention_only` / `prefixes`) |
+| placeholder          | object   | No       | Placeholder message config |
+| reasoning_channel_id | string   | No       | Target channel for reasoning output |
+
+## 3. Currently Supported
+
+- Text message send/receive
+- Incoming image/audio/video/file download (MediaStore first, local path fallback)
+- Incoming audio normalization into existing transcription flow (`[audio: ...]`)
+- Outgoing image/audio/video/file upload and send
+- Group trigger rules (including mention-only mode)
+- Typing state (`m.typing`)
+- Placeholder message + final reply replacement
+- Auto-join invited rooms (can be disabled)
+
+## 4. TODO
+
+- Rich media metadata improvements (for example image/video size and thumbnails)

docs/channels/matrix/README.zh.md

@@ -0,0 +1,59 @@
+# Matrix 通道配置指南
+
+## 1. 配置示例
+
+在 `config.json` 中添加：
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "device_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking... 💭"
+      },
+      "reasoning_channel_id": ""
+    }
+  }
+}
+```
+
+## 2. 参数说明
+
+| 字段                 | 类型     | 必填 | 说明 |
+|----------------------|----------|------|------|
+| enabled              | bool     | 是   | 是否启用 Matrix 通道 |
+| homeserver           | string   | 是   | Matrix 服务器地址（例如 `https://matrix.org`） |
+| user_id              | string   | 是   | 机器人 Matrix 用户 ID（例如 `@bot:matrix.org`） |
+| access_token         | string   | 是   | 机器人 access token |
+| device_id            | string   | 否   | 设备 ID（可选） |
+| join_on_invite       | bool     | 否   | 是否自动加入邀请房间 |
+| allow_from           | []string | 否   | 白名单用户（Matrix 用户 ID） |
+| group_trigger        | object   | 否   | 群聊触发策略（支持 `mention_only` / `prefixes`） |
+| placeholder          | object   | 否   | 占位消息配置 |
+| reasoning_channel_id | string   | 否   | 思维链输出目标通道 |
+
+## 3. 当前支持
+
+- 文本消息收发
+- 图片/音频/视频/文件消息入站下载（写入 MediaStore / 本地路径回退）
+- 音频消息按统一标记进入现有转写流程（`[audio: ...]`）
+- 图片/音频/视频/文件消息出站发送（上传到 Matrix 媒体库后发送）
+- 群聊触发规则（支持仅 @ 提及时响应）
+- Typing 状态（`m.typing`）
+- 占位消息（`Thinking... 💭`）+ 最终回复替换
+- 自动加入邀请房间（可关闭）
+
+## 4. TODO
+
+- 富媒体细节增强（如 image/video 的尺寸、缩略图等 metadata）

go.mod

@@ -8,6 +8,7 @@ require (
 	github.com/bwmarrin/discordgo v0.29.0
 	github.com/caarlos0/env/v11 v11.3.1
 	github.com/chzyer/readline v1.5.1
+	github.com/ergochat/irc-go v0.5.0
 	github.com/gdamore/tcell/v2 v2.13.8
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
@@ -27,6 +28,7 @@ require (
 	golang.org/x/oauth2 v0.35.0
 	golang.org/x/time v0.14.0
 	google.golang.org/protobuf v1.36.11
+	maunium.net/go/mautrix v0.26.3
 	modernc.org/sqlite v1.46.1
 )
 
@@ -37,7 +39,6 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/elliotchance/orderedmap/v3 v3.1.0 // indirect
-	github.com/ergochat/irc-go v0.5.0 // indirect
 	github.com/gdamore/encoding v1.0.1 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
@@ -89,7 +90,7 @@ require (
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	golang.org/x/arch v0.24.0 // indirect
 	golang.org/x/crypto v0.48.0 // indirect
-	golang.org/x/net v0.50.0 // indirect
+	golang.org/x/net v0.51.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
 	golang.org/x/sys v0.41.0 // indirect
 )

go.sum

@@ -271,6 +271,8 @@ golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
 golang.org/x/net v0.19.0/go.mod h1:CfAk/cbD4CthTvqiEl8NpboMuiuOYsAr/7NOjZJtv1U=
 golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
 golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
+golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
+golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
 golang.org/x/oauth2 v0.23.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
 golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
 golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
@@ -361,6 +363,8 @@ gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+maunium.net/go/mautrix v0.26.3 h1:tWZih6Vjw0qGTWuPmg9JUrQPzViTNDPGQLVc5UXC4nk=
+maunium.net/go/mautrix v0.26.3/go.mod h1:v5ZdDoCwUpNqEj5OrhEoUa3L1kEddKPaAya9TgGXN38=
 modernc.org/cc/v4 v4.27.1 h1:9W30zRlYrefrDV2JE2O8VDtJ1yPGownxciz5rrbQZis=
 modernc.org/cc/v4 v4.27.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
 modernc.org/ccgo/v4 v4.30.1 h1:4r4U1J6Fhj98NKfSjnPUN7Ze2c6MnAdL0hWw6+LrJpc=

pkg/agent/instance.go

@@ -70,7 +70,8 @@ func NewAgentInstance(
 	toolsRegistry := tools.NewToolRegistry()
 
 	if cfg.Tools.IsToolEnabled("read_file") {
-		toolsRegistry.Register(tools.NewReadFileTool(workspace, readRestrict, allowReadPaths))
+		maxReadFileSize := cfg.Tools.ReadFile.MaxReadFileSize
+		toolsRegistry.Register(tools.NewReadFileTool(workspace, readRestrict, maxReadFileSize, allowReadPaths))
 	}
 	if cfg.Tools.IsToolEnabled("write_file") {
 		toolsRegistry.Register(tools.NewWriteFileTool(workspace, restrict, allowWritePaths))

pkg/agent/loop.go

@@ -581,15 +581,6 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 	}
 
 	route, agent, routeErr := al.resolveMessageRoute(msg)
-
-	// Commands are checked before requiring a successful route.
-	// Global commands (/help, /show, /switch) work even when routing fails;
-	// context-dependent commands check their own Runtime fields and report
-	// "unavailable" when the required capability is nil.
-	if response, handled := al.handleCommand(ctx, msg, agent); handled {
-		return response, nil
-	}
-
 	if routeErr != nil {
 		return "", routeErr
 	}
@@ -615,7 +606,7 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 			"route_channel": route.Channel,
 		})
 
-	return al.runAgentLoop(ctx, agent, processOptions{
+	opts := processOptions{
 		SessionKey:      sessionKey,
 		Channel:         msg.Channel,
 		ChatID:          msg.ChatID,
@@ -624,7 +615,15 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 		DefaultResponse: defaultResponse,
 		EnableSummary:   true,
 		SendResponse:    false,
-	})
+	}
+
+	// context-dependent commands check their own Runtime fields and report
+	// "unavailable" when the required capability is nil.
+	if response, handled := al.handleCommand(ctx, msg, agent, &opts); handled {
+		return response, nil
+	}
+
+	return al.runAgentLoop(ctx, agent, opts)
 }
 
 func (al *AgentLoop) resolveMessageRoute(msg bus.InboundMessage) (routing.ResolvedRoute, *AgentInstance, error) {
@@ -1055,9 +1054,12 @@ func (al *AgentLoop) runLLMIteration(
 				"target_channel": al.targetReasoningChannelID(opts.Channel),
 				"channel":        opts.Channel,
 			})
-		// Check if no tool calls - we're done
+		// Check if no tool calls - then check reasoning content if any
 		if len(response.ToolCalls) == 0 {
 			finalContent = response.Content
+			if finalContent == "" && response.ReasoningContent != "" {
+				finalContent = response.ReasoningContent
+			}
 			logger.InfoCF("agent", "LLM response without tool calls (direct answer)",
 				map[string]any{
 					"agent_id":      agent.ID,
@@ -1489,10 +1491,20 @@ func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) {
 		return
 	}
 
+	const (
+		maxSummarizationMessages = 10
+		llmMaxRetries            = 3
+		llmTemperature           = 0.3
+		fallbackMaxContentLength = 200
+	)
+
 	// Multi-Part Summarization
 	var finalSummary string
-	if len(validMessages) > 10 {
+	if len(validMessages) > maxSummarizationMessages {
 		mid := len(validMessages) / 2
+
+		mid = al.findNearestUserMessage(validMessages, mid)
+
 		part1 := validMessages[:mid]
 		part2 := validMessages[mid:]
 
@@ -1504,18 +1516,9 @@ func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) {
 			s1,
 			s2,
 		)
-		resp, err := agent.Provider.Chat(
+
-			ctx,
+		resp, err := al.retryLLMCall(ctx, agent, mergePrompt, llmMaxRetries)
-			[]providers.Message{{Role: "user", Content: mergePrompt}},
+		if err == nil && resp.Content != "" {
-			nil,
-			agent.Model,
-			map[string]any{
-				"max_tokens":       1024,
-				"temperature":      0.3,
-				"prompt_cache_key": agent.ID,
-			},
-		)
-		if err == nil {
 			finalSummary = resp.Content
 		} else {
 			finalSummary = s1 + " " + s2
@@ -1535,6 +1538,68 @@ func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) {
 	}
 }
 
+// findNearestUserMessage finds the nearest user message to the given index.
+// It searches backward first, then forward if no user message is found.
+func (al *AgentLoop) findNearestUserMessage(messages []providers.Message, mid int) int {
+	originalMid := mid
+
+	for mid > 0 && messages[mid].Role != "user" {
+		mid--
+	}
+
+	if messages[mid].Role == "user" {
+		return mid
+	}
+
+	mid = originalMid
+	for mid < len(messages) && messages[mid].Role != "user" {
+		mid++
+	}
+
+	if mid < len(messages) {
+		return mid
+	}
+
+	return originalMid
+}
+
+// retryLLMCall calls the LLM with retry logic.
+func (al *AgentLoop) retryLLMCall(
+	ctx context.Context,
+	agent *AgentInstance,
+	prompt string,
+	maxRetries int,
+) (*providers.LLMResponse, error) {
+	const (
+		llmTemperature = 0.3
+	)
+
+	var resp *providers.LLMResponse
+	var err error
+
+	for attempt := 0; attempt < maxRetries; attempt++ {
+		resp, err = agent.Provider.Chat(
+			ctx,
+			[]providers.Message{{Role: "user", Content: prompt}},
+			nil,
+			agent.Model,
+			map[string]any{
+				"max_tokens":       agent.MaxTokens,
+				"temperature":      llmTemperature,
+				"prompt_cache_key": agent.ID,
+			},
+		)
+		if err == nil && resp != nil && resp.Content != "" {
+			return resp, nil
+		}
+		if attempt < maxRetries-1 {
+			time.Sleep(time.Duration(attempt+1) * 100 * time.Millisecond)
+		}
+	}
+
+	return resp, err
+}
+
 // summarizeBatch summarizes a batch of messages.
 func (al *AgentLoop) summarizeBatch(
 	ctx context.Context,
@@ -1542,6 +1607,13 @@ func (al *AgentLoop) summarizeBatch(
 	batch []providers.Message,
 	existingSummary string,
 ) (string, error) {
+	const (
+		llmMaxRetries             = 3
+		llmTemperature            = 0.3
+		fallbackMinContentLength  = 200
+		fallbackMaxContentPercent = 10
+	)
+
 	var sb strings.Builder
 	sb.WriteString(
 		"Provide a concise summary of this conversation segment, preserving core context and key points.\n",
@@ -1557,21 +1629,40 @@ func (al *AgentLoop) summarizeBatch(
 	}
 	prompt := sb.String()
 
-	response, err := agent.Provider.Chat(
+	response, err := al.retryLLMCall(ctx, agent, prompt, llmMaxRetries)
-		ctx,
+	if err == nil && response.Content != "" {
-		[]providers.Message{{Role: "user", Content: prompt}},
+		return strings.TrimSpace(response.Content), nil
-		nil,
-		agent.Model,
-		map[string]any{
-			"max_tokens":       1024,
-			"temperature":      0.3,
-			"prompt_cache_key": agent.ID,
-		},
-	)
-	if err != nil {
-		return "", err
 	}
-	return response.Content, nil
+
+	var fallback strings.Builder
+	fallback.WriteString("Conversation summary: ")
+	for i, m := range batch {
+		if i > 0 {
+			fallback.WriteString(" | ")
+		}
+		content := strings.TrimSpace(m.Content)
+		runes := []rune(content)
+		if len(runes) == 0 {
+			fallback.WriteString(fmt.Sprintf("%s: ", m.Role))
+			continue
+		}
+
+		keepLength := len(runes) * fallbackMaxContentPercent / 100
+		if keepLength < fallbackMinContentLength {
+			keepLength = fallbackMinContentLength
+		}
+
+		if keepLength > len(runes) {
+			keepLength = len(runes)
+		}
+
+		content = string(runes[:keepLength])
+		if keepLength < len(runes) {
+			content += "..."
+		}
+		fallback.WriteString(fmt.Sprintf("%s: %s", m.Role, content))
+	}
+	return fallback.String(), nil
 }
 
 // estimateTokens estimates the number of tokens in a message list.
@@ -1590,6 +1681,7 @@ func (al *AgentLoop) handleCommand(
 	ctx context.Context,
 	msg bus.InboundMessage,
 	agent *AgentInstance,
+	opts *processOptions,
 ) (string, bool) {
 	if !commands.HasCommandPrefix(msg.Content) {
 		return "", false
@@ -1599,7 +1691,7 @@ func (al *AgentLoop) handleCommand(
 		return "", false
 	}
 
-	rt := al.buildCommandsRuntime(agent)
+	rt := al.buildCommandsRuntime(agent, opts)
 	executor := commands.NewExecutor(al.cmdRegistry, rt)
 
 	var commandReply string
@@ -1628,7 +1720,7 @@ func (al *AgentLoop) handleCommand(
 	}
 }
 
-func (al *AgentLoop) buildCommandsRuntime(agent *AgentInstance) *commands.Runtime {
+func (al *AgentLoop) buildCommandsRuntime(agent *AgentInstance, opts *processOptions) *commands.Runtime {
 	rt := &commands.Runtime{
 		Config:          al.cfg,
 		ListAgentIDs:    al.registry.ListAgentIDs,
@@ -1658,6 +1750,20 @@ func (al *AgentLoop) buildCommandsRuntime(agent *AgentInstance) *commands.Runtim
 			agent.Model = value
 			return oldModel, nil
 		}
+
+		rt.ClearHistory = func() error {
+			if opts == nil {
+				return fmt.Errorf("process options not available")
+			}
+			if agent.Sessions == nil {
+				return fmt.Errorf("sessions not initialized for agent")
+			}
+
+			agent.Sessions.SetHistory(opts.SessionKey, make([]providers.Message, 0))
+			agent.Sessions.SetSummary(opts.SessionKey, "")
+			agent.Sessions.Save(opts.SessionKey)
+			return nil
+		}
 	}
 	return rt
 }

pkg/channels/feishu/feishu_64.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"math/rand"
 	"net/http"
 	"os"
 	"path/filepath"
@@ -195,18 +196,30 @@ func (c *FeishuChannel) SendPlaceholder(ctx context.Context, chatID string) (str
 }
 
 // ReactToMessage implements channels.ReactionCapable.
-// Adds an "Pin" reaction and returns an undo function to remove it.
+// Adds a reaction (randomly chosen from config) and returns an undo function to remove it.
 func (c *FeishuChannel) ReactToMessage(ctx context.Context, chatID, messageID string) (func(), error) {
+	// Get emoji list from config
+	emojiList := c.config.RandomReactionEmoji
+	var chosenEmoji string
+	if len(emojiList) == 0 {
+		// Default to "Pin" if no config
+		chosenEmoji = "Pin"
+	} else {
+		idx := rand.Intn(len(emojiList))
+		chosenEmoji = emojiList[idx]
+	}
+
 	req := larkim.NewCreateMessageReactionReqBuilder().
 		MessageId(messageID).
 		Body(larkim.NewCreateMessageReactionReqBodyBuilder().
-			ReactionType(larkim.NewEmojiBuilder().EmojiType("Pin").Build()).
+			ReactionType(larkim.NewEmojiBuilder().EmojiType(chosenEmoji).Build()).
 			Build()).
 		Build()
 
 	resp, err := c.client.Im.V1.MessageReaction.Create(ctx, req)
 	if err != nil {
 		logger.ErrorCF("feishu", "Failed to add reaction", map[string]any{
+			"emoji":      chosenEmoji,
 			"message_id": messageID,
 			"error":      err.Error(),
 		})
@@ -214,6 +227,7 @@ func (c *FeishuChannel) ReactToMessage(ctx context.Context, chatID, messageID st
 	}
 	if !resp.Success() {
 		logger.ErrorCF("feishu", "Reaction API error", map[string]any{
+			"emoji":      chosenEmoji,
 			"message_id": messageID,
 			"code":       resp.Code,
 			"msg":        resp.Msg,

pkg/channels/manager.go

@@ -61,6 +61,7 @@ var channelRateConfig = map[string]float64{
 	"telegram": 20,
 	"discord":  1,
 	"slack":    1,
+	"matrix":   2,
 	"line":     10,
 	"qq":       5,
 	"irc":      2,
@@ -245,6 +246,13 @@ func (m *Manager) initChannels() error {
 		m.initChannel("slack", "Slack")
 	}
 
+	if m.config.Channels.Matrix.Enabled &&
+		m.config.Channels.Matrix.Homeserver != "" &&
+		m.config.Channels.Matrix.UserID != "" &&
+		m.config.Channels.Matrix.AccessToken != "" {
+		m.initChannel("matrix", "Matrix")
+	}
+
 	if m.config.Channels.LINE.Enabled && m.config.Channels.LINE.ChannelAccessToken != "" {
 		m.initChannel("line", "LINE")
 	}

pkg/channels/matrix/init.go

@@ -0,0 +1,13 @@
+package matrix
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("matrix", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewMatrixChannel(cfg.Channels.Matrix, b)
+	})
+}

pkg/channels/matrix/matrix_test.go

@@ -0,0 +1,291 @@
+package matrix
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"maunium.net/go/mautrix"
+	"maunium.net/go/mautrix/event"
+	"maunium.net/go/mautrix/id"
+)
+
+func TestMatrixLocalpartMentionRegexp(t *testing.T) {
+	re := localpartMentionRegexp("picoclaw")
+
+	cases := []struct {
+		text string
+		want bool
+	}{
+		{text: "@picoclaw hello", want: true},
+		{text: "hi @picoclaw:matrix.org", want: true},
+		{
+			text: "\u6b22\u8fce\u4e00\u4e0bpicoclaw\u5c0f\u9f99\u867e",
+			want: false, // historical false-positive case in PR #356
+		},
+		{text: "mail test@example.com", want: false},
+	}
+
+	for _, tc := range cases {
+		if got := re.MatchString(tc.text); got != tc.want {
+			t.Fatalf("text=%q match=%v want=%v", tc.text, got, tc.want)
+		}
+	}
+}
+
+func TestStripUserMention(t *testing.T) {
+	userID := id.UserID("@picoclaw:matrix.org")
+
+	cases := []struct {
+		in   string
+		want string
+	}{
+		{in: "@picoclaw:matrix.org hello", want: "hello"},
+		{in: "@picoclaw, hello", want: "hello"},
+		{in: "no mention here", want: "no mention here"},
+	}
+
+	for _, tc := range cases {
+		if got := stripUserMention(tc.in, userID); got != tc.want {
+			t.Fatalf("stripUserMention(%q)=%q want=%q", tc.in, got, tc.want)
+		}
+	}
+}
+
+func TestIsBotMentioned(t *testing.T) {
+	ch := &MatrixChannel{
+		client: &mautrix.Client{
+			UserID: id.UserID("@picoclaw:matrix.org"),
+		},
+	}
+
+	cases := []struct {
+		name string
+		msg  event.MessageEventContent
+		want bool
+	}{
+		{
+			name: "mentions field",
+			msg: event.MessageEventContent{
+				Body: "hello",
+				Mentions: &event.Mentions{
+					UserIDs: []id.UserID{id.UserID("@picoclaw:matrix.org")},
+				},
+			},
+			want: true,
+		},
+		{
+			name: "full user id in body",
+			msg: event.MessageEventContent{
+				Body: "@picoclaw:matrix.org hello",
+			},
+			want: true,
+		},
+		{
+			name: "localpart with at sign",
+			msg: event.MessageEventContent{
+				Body: "@picoclaw hello",
+			},
+			want: true,
+		},
+		{
+			name: "localpart without at sign should not match",
+			msg: event.MessageEventContent{
+				Body: "\u6b22\u8fce\u4e00\u4e0bpicoclaw\u5c0f\u9f99\u867e",
+			},
+			want: false,
+		},
+		{
+			name: "formatted mention href matrix.to plain",
+			msg: event.MessageEventContent{
+				Body:          "hello bot",
+				FormattedBody: `<a href="https://matrix.to/#/@picoclaw:matrix.org">PicoClaw</a> hello`,
+			},
+			want: true,
+		},
+		{
+			name: "formatted mention href matrix.to encoded",
+			msg: event.MessageEventContent{
+				Body:          "hello bot",
+				FormattedBody: `<a href="https://matrix.to/#/%40picoclaw%3Amatrix.org">PicoClaw</a> hello`,
+			},
+			want: true,
+		},
+	}
+
+	for _, tc := range cases {
+		if got := ch.isBotMentioned(&tc.msg); got != tc.want {
+			t.Fatalf("%s: got=%v want=%v", tc.name, got, tc.want)
+		}
+	}
+}
+
+func TestRoomKindCache_ExpiresEntries(t *testing.T) {
+	cache := newRoomKindCache(4, 5*time.Second)
+	now := time.Unix(100, 0)
+	cache.set("!room:matrix.org", true, now)
+
+	if got, ok := cache.get("!room:matrix.org", now.Add(2*time.Second)); !ok || !got {
+		t.Fatalf("expected cached group room before ttl, got ok=%v group=%v", ok, got)
+	}
+
+	if _, ok := cache.get("!room:matrix.org", now.Add(6*time.Second)); ok {
+		t.Fatal("expected cache miss after ttl expiry")
+	}
+}
+
+func TestRoomKindCache_EvictsOldestWhenFull(t *testing.T) {
+	cache := newRoomKindCache(2, time.Minute)
+	now := time.Unix(200, 0)
+
+	cache.set("!room1:matrix.org", false, now)
+	cache.set("!room2:matrix.org", false, now.Add(1*time.Second))
+	cache.set("!room3:matrix.org", true, now.Add(2*time.Second))
+
+	if _, ok := cache.get("!room1:matrix.org", now.Add(2*time.Second)); ok {
+		t.Fatal("expected oldest cache entry to be evicted")
+	}
+	if got, ok := cache.get("!room2:matrix.org", now.Add(2*time.Second)); !ok || got {
+		t.Fatalf("expected room2 to remain and be direct, got ok=%v group=%v", ok, got)
+	}
+	if got, ok := cache.get("!room3:matrix.org", now.Add(2*time.Second)); !ok || !got {
+		t.Fatalf("expected room3 to remain and be group, got ok=%v group=%v", ok, got)
+	}
+}
+
+func TestMatrixMediaTempDir(t *testing.T) {
+	dir, err := matrixMediaTempDir()
+	if err != nil {
+		t.Fatalf("matrixMediaTempDir failed: %v", err)
+	}
+	if filepath.Base(dir) != matrixMediaTempDirName {
+		t.Fatalf("unexpected media dir base: %q", filepath.Base(dir))
+	}
+
+	info, err := os.Stat(dir)
+	if err != nil {
+		t.Fatalf("media dir not created: %v", err)
+	}
+	if !info.IsDir() {
+		t.Fatalf("expected directory, got mode=%v", info.Mode())
+	}
+}
+
+func TestMatrixMediaExt(t *testing.T) {
+	if got := matrixMediaExt("photo.png", "", "image"); got != ".png" {
+		t.Fatalf("filename extension mismatch: got=%q", got)
+	}
+	if got := matrixMediaExt("", "image/webp", "image"); got != ".webp" {
+		t.Fatalf("content-type extension mismatch: got=%q", got)
+	}
+	if got := matrixMediaExt("", "", "image"); got != ".jpg" {
+		t.Fatalf("default image extension mismatch: got=%q", got)
+	}
+	if got := matrixMediaExt("", "", "audio"); got != ".ogg" {
+		t.Fatalf("default audio extension mismatch: got=%q", got)
+	}
+	if got := matrixMediaExt("", "", "video"); got != ".mp4" {
+		t.Fatalf("default video extension mismatch: got=%q", got)
+	}
+	if got := matrixMediaExt("", "", "file"); got != ".bin" {
+		t.Fatalf("default file extension mismatch: got=%q", got)
+	}
+}
+
+func TestExtractInboundContent_ImageNoURLFallback(t *testing.T) {
+	ch := &MatrixChannel{}
+	msg := &event.MessageEventContent{
+		MsgType: event.MsgImage,
+		Body:    "test.png",
+	}
+
+	content, mediaRefs, ok := ch.extractInboundContent(context.Background(), msg, "matrix:room:event")
+	if !ok {
+		t.Fatal("expected ok for image fallback")
+	}
+	if content != "[image: test.png]" {
+		t.Fatalf("unexpected content: %q", content)
+	}
+	if len(mediaRefs) != 0 {
+		t.Fatalf("expected no media refs, got %d", len(mediaRefs))
+	}
+}
+
+func TestExtractInboundContent_AudioNoURLFallback(t *testing.T) {
+	ch := &MatrixChannel{}
+	msg := &event.MessageEventContent{
+		MsgType:  event.MsgAudio,
+		FileName: "voice.ogg",
+		Body:     "please transcribe",
+	}
+
+	content, mediaRefs, ok := ch.extractInboundContent(context.Background(), msg, "matrix:room:event")
+	if !ok {
+		t.Fatal("expected ok for audio fallback")
+	}
+	if content != "please transcribe\n[audio: voice.ogg]" {
+		t.Fatalf("unexpected content: %q", content)
+	}
+	if len(mediaRefs) != 0 {
+		t.Fatalf("expected no media refs, got %d", len(mediaRefs))
+	}
+}
+
+func TestMatrixOutboundMsgType(t *testing.T) {
+	cases := []struct {
+		name        string
+		partType    string
+		filename    string
+		contentType string
+		want        event.MessageType
+	}{
+		{name: "explicit image", partType: "image", want: event.MsgImage},
+		{name: "explicit audio", partType: "audio", want: event.MsgAudio},
+		{name: "mime fallback video", contentType: "video/mp4", want: event.MsgVideo},
+		{name: "extension fallback audio", filename: "voice.ogg", want: event.MsgAudio},
+		{name: "unknown defaults file", filename: "report.txt", want: event.MsgFile},
+	}
+
+	for _, tc := range cases {
+		if got := matrixOutboundMsgType(tc.partType, tc.filename, tc.contentType); got != tc.want {
+			t.Fatalf("%s: got=%q want=%q", tc.name, got, tc.want)
+		}
+	}
+}
+
+func TestMatrixOutboundContent(t *testing.T) {
+	content := matrixOutboundContent(
+		"please review",
+		"voice.ogg",
+		event.MsgAudio,
+		"audio/ogg",
+		1234,
+		id.ContentURIString("mxc://matrix.org/abc"),
+	)
+	if content.Body != "please review" {
+		t.Fatalf("unexpected body: %q", content.Body)
+	}
+	if content.FileName != "voice.ogg" {
+		t.Fatalf("unexpected filename: %q", content.FileName)
+	}
+	if content.Info == nil || content.Info.MimeType != "audio/ogg" {
+		t.Fatalf("unexpected content type: %+v", content.Info)
+	}
+	if content.Info == nil || content.Info.Size != 1234 {
+		t.Fatalf("unexpected size: %+v", content.Info)
+	}
+
+	noCaption := matrixOutboundContent(
+		"",
+		"image.png",
+		event.MsgImage,
+		"image/png",
+		0,
+		id.ContentURIString("mxc://matrix.org/def"),
+	)
+	if noCaption.Body != "image.png" {
+		t.Fatalf("unexpected fallback body: %q", noCaption.Body)
+	}
+}

pkg/channels/telegram/telegram.go

@@ -88,7 +88,7 @@ func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChann
 		telegramCfg,
 		bus,
 		telegramCfg.AllowFrom,
-		channels.WithMaxMessageLength(4096),
+		channels.WithMaxMessageLength(4000),
 		channels.WithGroupTrigger(telegramCfg.GroupTrigger),
 		channels.WithReasoningChannelID(telegramCfg.ReasoningChannelID),
 	)
@@ -173,22 +173,57 @@ func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) err
 		return fmt.Errorf("invalid chat ID %s: %w", msg.ChatID, channels.ErrSendFailed)
 	}
 
-	htmlContent := markdownToTelegramHTML(msg.Content)
+	if msg.Content == "" {
+		return nil
+	}
 
-	// Typing/placeholder handled by Manager.preSend — just send the message
+	// The Manager already splits messages to ≤4000 chars (WithMaxMessageLength),
+	// so msg.Content is guaranteed to be within that limit. We still need to
+	// check if HTML expansion pushes it beyond Telegram's 4096-char API limit.
+	queue := []string{msg.Content}
+	for len(queue) > 0 {
+		chunk := queue[0]
+		queue = queue[1:]
+
+		htmlContent := markdownToTelegramHTML(chunk)
+
+		if len([]rune(htmlContent)) > 4096 {
+			ratio := float64(len([]rune(chunk))) / float64(len([]rune(htmlContent)))
+			smallerLen := int(float64(4096) * ratio * 0.95) // 5% safety margin
+			if smallerLen < 100 {
+				smallerLen = 100
+			}
+			// Push sub-chunks back to the front of the queue for
+			// re-validation instead of sending them blindly.
+			subChunks := channels.SplitMessage(chunk, smallerLen)
+			queue = append(subChunks, queue...)
+			continue
+		}
+
+		if err := c.sendHTMLChunk(ctx, chatID, htmlContent, chunk); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// sendHTMLChunk sends a single HTML message, falling back to the original
+// markdown as plain text on parse failure so users never see raw HTML tags.
+func (c *TelegramChannel) sendHTMLChunk(ctx context.Context, chatID int64, htmlContent, mdFallback string) error {
 	tgMsg := tu.Message(tu.ID(chatID), htmlContent)
 	tgMsg.ParseMode = telego.ModeHTML
 
-	if _, err = c.bot.SendMessage(ctx, tgMsg); err != nil {
+	if _, err := c.bot.SendMessage(ctx, tgMsg); err != nil {
 		logger.ErrorCF("telegram", "HTML parse failed, falling back to plain text", map[string]any{
 			"error": err.Error(),
 		})
+		tgMsg.Text = mdFallback
 		tgMsg.ParseMode = ""
 		if _, err = c.bot.SendMessage(ctx, tgMsg); err != nil {
 			return fmt.Errorf("telegram send: %w", channels.ErrTemporary)
 		}
 	}
-
 	return nil
 }
 

pkg/channels/telegram/telegram_test.go

@@ -0,0 +1,273 @@
+package telegram
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/mymmrac/telego"
+	ta "github.com/mymmrac/telego/telegoapi"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+)
+
+const testToken = "1234567890:aaaabbbbaaaabbbbaaaabbbbaaaabbbbccc"
+
+// stubCaller implements ta.Caller for testing.
+type stubCaller struct {
+	calls  []stubCall
+	callFn func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error)
+}
+
+type stubCall struct {
+	URL  string
+	Data *ta.RequestData
+}
+
+func (s *stubCaller) Call(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+	s.calls = append(s.calls, stubCall{URL: url, Data: data})
+	return s.callFn(ctx, url, data)
+}
+
+// stubConstructor implements ta.RequestConstructor for testing.
+type stubConstructor struct{}
+
+func (s *stubConstructor) JSONRequest(parameters any) (*ta.RequestData, error) {
+	return &ta.RequestData{}, nil
+}
+
+func (s *stubConstructor) MultipartRequest(
+	parameters map[string]string,
+	files map[string]ta.NamedReader,
+) (*ta.RequestData, error) {
+	return &ta.RequestData{}, nil
+}
+
+// successResponse returns a ta.Response that telego will treat as a successful SendMessage.
+func successResponse(t *testing.T) *ta.Response {
+	t.Helper()
+	msg := &telego.Message{MessageID: 1}
+	b, err := json.Marshal(msg)
+	require.NoError(t, err)
+	return &ta.Response{Ok: true, Result: b}
+}
+
+// newTestChannel creates a TelegramChannel with a mocked bot for unit testing.
+func newTestChannel(t *testing.T, caller *stubCaller) *TelegramChannel {
+	t.Helper()
+
+	bot, err := telego.NewBot(testToken,
+		telego.WithAPICaller(caller),
+		telego.WithRequestConstructor(&stubConstructor{}),
+		telego.WithDiscardLogger(),
+	)
+	require.NoError(t, err)
+
+	base := channels.NewBaseChannel("telegram", nil, nil, nil,
+		channels.WithMaxMessageLength(4000),
+	)
+	base.SetRunning(true)
+
+	return &TelegramChannel{
+		BaseChannel: base,
+		bot:         bot,
+		chatIDs:     make(map[string]int64),
+	}
+}
+
+func TestSend_EmptyContent(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			t.Fatal("SendMessage should not be called for empty content")
+			return nil, nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: "",
+	})
+
+	assert.NoError(t, err)
+	assert.Empty(t, caller.calls, "no API calls should be made for empty content")
+}
+
+func TestSend_ShortMessage_SingleCall(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return successResponse(t), nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: "Hello, world!",
+	})
+
+	assert.NoError(t, err)
+	assert.Len(t, caller.calls, 1, "short message should result in exactly one SendMessage call")
+}
+
+func TestSend_LongMessage_SingleCall(t *testing.T) {
+	// With WithMaxMessageLength(4000), the Manager pre-splits messages before
+	// they reach Send(). A message at exactly 4000 chars should go through
+	// as a single SendMessage call (no re-split needed since HTML expansion
+	// won't exceed 4096 for plain text).
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return successResponse(t), nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	longContent := strings.Repeat("a", 4000)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: longContent,
+	})
+
+	assert.NoError(t, err)
+	assert.Len(t, caller.calls, 1, "pre-split message within limit should result in one SendMessage call")
+}
+
+func TestSend_HTMLFallback_PerChunk(t *testing.T) {
+	callCount := 0
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			callCount++
+			// Fail on odd calls (HTML attempt), succeed on even calls (plain text fallback)
+			if callCount%2 == 1 {
+				return nil, errors.New("Bad Request: can't parse entities")
+			}
+			return successResponse(t), nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: "Hello **world**",
+	})
+
+	assert.NoError(t, err)
+	// One short message → 1 HTML attempt (fail) + 1 plain text fallback (success) = 2 calls
+	assert.Equal(t, 2, len(caller.calls), "should have HTML attempt + plain text fallback")
+}
+
+func TestSend_HTMLFallback_BothFail(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return nil, errors.New("send failed")
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: "Hello",
+	})
+
+	assert.Error(t, err)
+	assert.True(t, errors.Is(err, channels.ErrTemporary), "error should wrap ErrTemporary")
+	assert.Equal(t, 2, len(caller.calls), "should have HTML attempt + plain text attempt")
+}
+
+func TestSend_LongMessage_HTMLFallback_StopsOnError(t *testing.T) {
+	// With a long message that gets split into 2 chunks, if both HTML and
+	// plain text fail on the first chunk, Send should return early.
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return nil, errors.New("send failed")
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	longContent := strings.Repeat("x", 4001)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: longContent,
+	})
+
+	assert.Error(t, err)
+	// Should fail on the first chunk (2 calls: HTML + fallback), never reaching the second chunk.
+	assert.Equal(t, 2, len(caller.calls), "should stop after first chunk fails both HTML and plain text")
+}
+
+func TestSend_MarkdownShortButHTMLLong_MultipleCalls(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return successResponse(t), nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	// Create markdown whose length is <= 4000 but whose HTML expansion is much longer.
+	// "**a** " (6 chars) becomes "<b>a</b> " (9 chars) in HTML, so repeating it many times
+	// yields HTML that exceeds Telegram's limit while markdown stays within it.
+	markdownContent := strings.Repeat("**a** ", 600) // 3600 chars markdown, HTML ~5400+ chars
+	assert.LessOrEqual(t, len([]rune(markdownContent)), 4000, "markdown content must not exceed chunk size")
+
+	htmlExpanded := markdownToTelegramHTML(markdownContent)
+	assert.Greater(
+		t, len([]rune(htmlExpanded)), 4096,
+		"HTML expansion must exceed Telegram limit for this test to be meaningful",
+	)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: markdownContent,
+	})
+
+	assert.NoError(t, err)
+	assert.Greater(
+		t, len(caller.calls), 1,
+		"markdown-short but HTML-long message should be split into multiple SendMessage calls",
+	)
+}
+
+func TestSend_NotRunning(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			t.Fatal("should not be called")
+			return nil, nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+	ch.SetRunning(false)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: "Hello",
+	})
+
+	assert.ErrorIs(t, err, channels.ErrNotRunning)
+	assert.Empty(t, caller.calls)
+}
+
+func TestSend_InvalidChatID(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			t.Fatal("should not be called")
+			return nil, nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "not-a-number",
+		Content: "Hello",
+	})
+
+	assert.Error(t, err)
+	assert.True(t, errors.Is(err, channels.ErrSendFailed), "error should wrap ErrSendFailed")
+	assert.Empty(t, caller.calls)
+}

pkg/commands/builtin.go

@@ -12,5 +12,6 @@ func BuiltinDefinitions() []Definition {
 		listCommand(),
 		switchCommand(),
 		checkCommand(),
+		clearCommand(),
 	}
 }

pkg/commands/cmd_clear.go

@@ -0,0 +1,20 @@
+package commands
+
+import "context"
+
+func clearCommand() Definition {
+	return Definition{
+		Name:        "clear",
+		Description: "Clear the chat history",
+		Usage:       "/clear",
+		Handler: func(_ context.Context, req Request, rt *Runtime) error {
+			if rt == nil || rt.ClearHistory == nil {
+				return req.Reply(unavailableMsg)
+			}
+			if err := rt.ClearHistory(); err != nil {
+				return req.Reply("Failed to clear chat history: " + err.Error())
+			}
+			return req.Reply("Chat history cleared!")
+		},
+	}
+}

pkg/commands/runtime.go

@@ -13,4 +13,5 @@ type Runtime struct {
 	GetEnabledChannels func() []string
 	SwitchModel        func(value string) (oldModel string, err error)
 	SwitchChannel      func(value string) error
+	ClearHistory       func() error
 }

pkg/config/config.go

@@ -225,6 +225,7 @@ type ChannelsConfig struct {
 	QQ         QQConfig         `json:"qq"`
 	DingTalk   DingTalkConfig   `json:"dingtalk"`
 	Slack      SlackConfig      `json:"slack"`
+	Matrix     MatrixConfig     `json:"matrix"`
 	LINE       LINEConfig       `json:"line"`
 	OneBot     OneBotConfig     `json:"onebot"`
 	WeCom      WeComConfig      `json:"wecom"`
@@ -273,15 +274,16 @@ type TelegramConfig struct {
 }
 
 type FeishuConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_FEISHU_ENABLED"`
+	Enabled             bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_FEISHU_ENABLED"`
-	AppID              string              `json:"app_id"                  env:"PICOCLAW_CHANNELS_FEISHU_APP_ID"`
+	AppID               string              `json:"app_id"                  env:"PICOCLAW_CHANNELS_FEISHU_APP_ID"`
-	AppSecret          string              `json:"app_secret"              env:"PICOCLAW_CHANNELS_FEISHU_APP_SECRET"`
+	AppSecret           string              `json:"app_secret"              env:"PICOCLAW_CHANNELS_FEISHU_APP_SECRET"`
-	EncryptKey         string              `json:"encrypt_key"             env:"PICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEY"`
+	EncryptKey          string              `json:"encrypt_key"             env:"PICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEY"`
-	VerificationToken  string              `json:"verification_token"      env:"PICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKEN"`
+	VerificationToken   string              `json:"verification_token"      env:"PICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKEN"`
-	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_FEISHU_ALLOW_FROM"`
+	AllowFrom           FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_FEISHU_ALLOW_FROM"`
-	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	GroupTrigger        GroupTriggerConfig  `json:"group_trigger,omitempty"`
-	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
+	Placeholder         PlaceholderConfig   `json:"placeholder,omitempty"`
-	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_FEISHU_REASONING_CHANNEL_ID"`
+	ReasoningChannelID  string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_FEISHU_REASONING_CHANNEL_ID"`
+	RandomReactionEmoji FlexibleStringSlice `json:"random_reaction_emoji"   env:"PICOCLAW_CHANNELS_FEISHU_RANDOM_REACTION_EMOJI"`
 }
 
 type DiscordConfig struct {
@@ -335,6 +337,19 @@ type SlackConfig struct {
 	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_SLACK_REASONING_CHANNEL_ID"`
 }
 
+type MatrixConfig struct {
+	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_MATRIX_ENABLED"`
+	Homeserver         string              `json:"homeserver"              env:"PICOCLAW_CHANNELS_MATRIX_HOMESERVER"`
+	UserID             string              `json:"user_id"                 env:"PICOCLAW_CHANNELS_MATRIX_USER_ID"`
+	AccessToken        string              `json:"access_token"            env:"PICOCLAW_CHANNELS_MATRIX_ACCESS_TOKEN"`
+	DeviceID           string              `json:"device_id,omitempty"     env:"PICOCLAW_CHANNELS_MATRIX_DEVICE_ID"`
+	JoinOnInvite       bool                `json:"join_on_invite"          env:"PICOCLAW_CHANNELS_MATRIX_JOIN_ON_INVITE"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_MATRIX_ALLOW_FROM"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_MATRIX_REASONING_CHANNEL_ID"`
+}
+
 type LINEConfig struct {
 	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_LINE_ENABLED"`
 	ChannelSecret      string              `json:"channel_secret"          env:"PICOCLAW_CHANNELS_LINE_CHANNEL_SECRET"`
@@ -461,12 +476,14 @@ type ProvidersConfig struct {
 	ShengSuanYun  ProviderConfig       `json:"shengsuanyun"`
 	DeepSeek      ProviderConfig       `json:"deepseek"`
 	Cerebras      ProviderConfig       `json:"cerebras"`
+	Vivgrid       ProviderConfig       `json:"vivgrid"`
 	VolcEngine    ProviderConfig       `json:"volcengine"`
 	GitHubCopilot ProviderConfig       `json:"github_copilot"`
 	Antigravity   ProviderConfig       `json:"antigravity"`
 	Qwen          ProviderConfig       `json:"qwen"`
 	Mistral       ProviderConfig       `json:"mistral"`
 	Avian         ProviderConfig       `json:"avian"`
+	Minimax       ProviderConfig       `json:"minimax"`
 }
 
 // IsEmpty checks if all provider configs are empty (no API keys or API bases set)
@@ -486,12 +503,14 @@ func (p ProvidersConfig) IsEmpty() bool {
 		p.ShengSuanYun.APIKey == "" && p.ShengSuanYun.APIBase == "" &&
 		p.DeepSeek.APIKey == "" && p.DeepSeek.APIBase == "" &&
 		p.Cerebras.APIKey == "" && p.Cerebras.APIBase == "" &&
+		p.Vivgrid.APIKey == "" && p.Vivgrid.APIBase == "" &&
 		p.VolcEngine.APIKey == "" && p.VolcEngine.APIBase == "" &&
 		p.GitHubCopilot.APIKey == "" && p.GitHubCopilot.APIBase == "" &&
 		p.Antigravity.APIKey == "" && p.Antigravity.APIBase == "" &&
 		p.Qwen.APIKey == "" && p.Qwen.APIBase == "" &&
 		p.Mistral.APIKey == "" && p.Mistral.APIBase == "" &&
-		p.Avian.APIKey == "" && p.Avian.APIBase == ""
+		p.Avian.APIKey == "" && p.Avian.APIBase == "" &&
+		p.Minimax.APIKey == "" && p.Minimax.APIBase == ""
 }
 
 // MarshalJSON implements custom JSON marshaling for ProvidersConfig
@@ -645,6 +664,11 @@ type MediaCleanupConfig struct {
 	Interval   int `                                    env:"PICOCLAW_MEDIA_CLEANUP_INTERVAL" json:"interval_minutes"`
 }
 
+type ReadFileToolConfig struct {
+	Enabled         bool `json:"enabled"`
+	MaxReadFileSize int  `json:"max_read_file_size"`
+}
+
 type ToolsConfig struct {
 	AllowReadPaths  []string           `json:"allow_read_paths"  env:"PICOCLAW_TOOLS_ALLOW_READ_PATHS"`
 	AllowWritePaths []string           `json:"allow_write_paths" env:"PICOCLAW_TOOLS_ALLOW_WRITE_PATHS"`
@@ -661,7 +685,7 @@ type ToolsConfig struct {
 	InstallSkill    ToolConfig         `json:"install_skill"                                            envPrefix:"PICOCLAW_TOOLS_INSTALL_SKILL_"`
 	ListDir         ToolConfig         `json:"list_dir"                                                 envPrefix:"PICOCLAW_TOOLS_LIST_DIR_"`
 	Message         ToolConfig         `json:"message"                                                  envPrefix:"PICOCLAW_TOOLS_MESSAGE_"`
-	ReadFile        ToolConfig         `json:"read_file"                                                envPrefix:"PICOCLAW_TOOLS_READ_FILE_"`
+	ReadFile        ReadFileToolConfig `json:"read_file"                                                envPrefix:"PICOCLAW_TOOLS_READ_FILE_"`
 	SendFile        ToolConfig         `json:"send_file"                                                envPrefix:"PICOCLAW_TOOLS_SEND_FILE_"`
 	Spawn           ToolConfig         `json:"spawn"                                                    envPrefix:"PICOCLAW_TOOLS_SPAWN_"`
 	SPI             ToolConfig         `json:"spi"                                                      envPrefix:"PICOCLAW_TOOLS_SPI_"`

pkg/config/config_test.go

@@ -283,6 +283,9 @@ func TestDefaultConfig_Channels(t *testing.T) {
 	if cfg.Channels.Slack.Enabled {
 		t.Error("Slack should be disabled by default")
 	}
+	if cfg.Channels.Matrix.Enabled {
+		t.Error("Matrix should be disabled by default")
+	}
 }
 
 // TestDefaultConfig_WebTools verifies web tools config

pkg/config/defaults.go

@@ -98,6 +98,22 @@ func DefaultConfig() *Config {
 				AppToken:  "",
 				AllowFrom: FlexibleStringSlice{},
 			},
+			Matrix: MatrixConfig{
+				Enabled:      false,
+				Homeserver:   "https://matrix.org",
+				UserID:       "",
+				AccessToken:  "",
+				DeviceID:     "",
+				JoinOnInvite: true,
+				AllowFrom:    FlexibleStringSlice{},
+				GroupTrigger: GroupTriggerConfig{
+					MentionOnly: true,
+				},
+				Placeholder: PlaceholderConfig{
+					Enabled: true,
+					Text:    "Thinking... 💭",
+				},
+			},
 			LINE: LINEConfig{
 				Enabled:            false,
 				ChannelSecret:      "",
@@ -262,6 +278,14 @@ func DefaultConfig() *Config {
 				APIKey:    "",
 			},
 
+			// Vivgrid - https://vivgrid.com
+			{
+				ModelName: "vivgrid-auto",
+				Model:     "vivgrid/auto",
+				APIBase:   "https://api.vivgrid.com/v1",
+				APIKey:    "",
+			},
+
 			// Volcengine (火山引擎) - https://console.volcengine.com/ark
 			{
 				ModelName: "doubao-pro",
@@ -323,6 +347,14 @@ func DefaultConfig() *Config {
 				APIKey:    "",
 			},
 
+			// Minimax - https://api.minimaxi.com/
+			{
+				ModelName: "MiniMax-M2.5",
+				Model:     "minimax/MiniMax-M2.5",
+				APIBase:   "https://api.minimaxi.com/v1",
+				APIKey:    "",
+			},
+
 			// VLLM (local) - http://localhost:8000
 			{
 				ModelName: "local-model",
@@ -435,8 +467,9 @@ func DefaultConfig() *Config {
 			Message: ToolConfig{
 				Enabled: true,
 			},
-			ReadFile: ToolConfig{
+			ReadFile: ReadFileToolConfig{
-				Enabled: true,
+				Enabled:         true,
+				MaxReadFileSize: 64 * 1024, // 64KB
 			},
 			Spawn: ToolConfig{
 				Enabled: true,

pkg/config/migration.go

@@ -292,6 +292,23 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 				}, true
 			},
 		},
+		{
+			providerNames: []string{"vivgrid"},
+			protocol:      "vivgrid",
+			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+				if p.Vivgrid.APIKey == "" && p.Vivgrid.APIBase == "" {
+					return ModelConfig{}, false
+				}
+				return ModelConfig{
+					ModelName:      "vivgrid",
+					Model:          "vivgrid/auto",
+					APIKey:         p.Vivgrid.APIKey,
+					APIBase:        p.Vivgrid.APIBase,
+					Proxy:          p.Vivgrid.Proxy,
+					RequestTimeout: p.Vivgrid.RequestTimeout,
+				}, true
+			},
+		},
 		{
 			providerNames: []string{"volcengine", "doubao"},
 			protocol:      "volcengine",

pkg/config/migration_test.go

@@ -155,7 +155,8 @@ func TestConvertProvidersToModelList_AllProviders(t *testing.T) {
 			ShengSuanYun:  ProviderConfig{APIKey: "key11"},
 			DeepSeek:      ProviderConfig{APIKey: "key12"},
 			Cerebras:      ProviderConfig{APIKey: "key13"},
-			VolcEngine:    ProviderConfig{APIKey: "key14"},
+			Vivgrid:       ProviderConfig{APIKey: "key14"},
+			VolcEngine:    ProviderConfig{APIKey: "key15"},
 			GitHubCopilot: ProviderConfig{ConnectMode: "grpc"},
 			Antigravity:   ProviderConfig{AuthMethod: "oauth"},
 			Qwen:          ProviderConfig{APIKey: "key17"},
@@ -166,9 +167,9 @@ func TestConvertProvidersToModelList_AllProviders(t *testing.T) {
 
 	result := ConvertProvidersToModelList(cfg)
 
-	// All 20 providers should be converted
+	// All 21 providers should be converted
-	if len(result) != 20 {
+	if len(result) != 21 {
-		t.Errorf("len(result) = %d, want 20", len(result))
+		t.Errorf("len(result) = %d, want 21", len(result))
 	}
 }
 

pkg/migrate/sources/openclaw/common.go

@@ -22,6 +22,7 @@ var supportedChannels = map[string]bool{
 	"qq":        true,
 	"dingtalk":  true,
 	"slack":     true,
+	"matrix":    true,
 	"line":      true,
 	"onebot":    true,
 	"wecom":     true,

pkg/migrate/sources/openclaw/openclaw_config.go

@@ -371,6 +371,8 @@ func (c *OpenClawConfig) IsChannelEnabled(name string) bool {
 		return c.Channels.Discord == nil || c.Channels.Discord.Enabled == nil || *c.Channels.Discord.Enabled
 	case "slack":
 		return c.Channels.Slack == nil || c.Channels.Slack.Enabled == nil || *c.Channels.Slack.Enabled
+	case "matrix":
+		return c.Channels.Matrix == nil || c.Channels.Matrix.Enabled == nil || *c.Channels.Matrix.Enabled
 	case "whatsapp":
 		return c.Channels.WhatsApp == nil || c.Channels.WhatsApp.Enabled == nil || *c.Channels.WhatsApp.Enabled
 	case "feishu":
@@ -397,6 +399,11 @@ func GetChannelAllowFrom(ch any) []string {
 			return nil
 		}
 		return c.AllowFrom
+	case *OpenClawMatrixConfig:
+		if c == nil {
+			return nil
+		}
+		return c.AllowFrom
 	case *OpenClawWhatsAppConfig:
 		if c == nil {
 			return nil
@@ -627,6 +634,7 @@ type ChannelsConfig struct {
 	QQ       QQConfig       `json:"qq"`
 	DingTalk DingTalkConfig `json:"dingtalk"`
 	Slack    SlackConfig    `json:"slack"`
+	Matrix   MatrixConfig   `json:"matrix"`
 	LINE     LINEConfig     `json:"line"`
 }
 
@@ -687,6 +695,14 @@ type SlackConfig struct {
 	AllowFrom []string `json:"allow_from"`
 }
 
+type MatrixConfig struct {
+	Enabled     bool     `json:"enabled"`
+	Homeserver  string   `json:"homeserver"`
+	UserID      string   `json:"user_id"`
+	AccessToken string   `json:"access_token"`
+	AllowFrom   []string `json:"allow_from"`
+}
+
 type LINEConfig struct {
 	Enabled            bool     `json:"enabled"`
 	ChannelSecret      string   `json:"channel_secret"`
@@ -862,12 +878,26 @@ func (c *OpenClawConfig) convertChannels(warnings *[]string) ChannelsConfig {
 		}
 	}
 
+	if c.Channels.Matrix != nil && supportedChannels["matrix"] {
+		enabled := c.Channels.Matrix.Enabled == nil || *c.Channels.Matrix.Enabled
+		channels.Matrix = MatrixConfig{
+			Enabled:   enabled,
+			AllowFrom: c.Channels.Matrix.AllowFrom,
+		}
+		if c.Channels.Matrix.Homeserver != nil {
+			channels.Matrix.Homeserver = *c.Channels.Matrix.Homeserver
+		}
+		if c.Channels.Matrix.UserID != nil {
+			channels.Matrix.UserID = *c.Channels.Matrix.UserID
+		}
+		if c.Channels.Matrix.AccessToken != nil {
+			channels.Matrix.AccessToken = *c.Channels.Matrix.AccessToken
+		}
+	}
+
 	if c.Channels.Signal != nil {
 		*warnings = append(*warnings, "Channel 'signal': No PicoClaw adapter available")
 	}
-	if c.Channels.Matrix != nil {
-		*warnings = append(*warnings, "Channel 'matrix': No PicoClaw adapter available")
-	}
 	if c.Channels.IRC != nil {
 		*warnings = append(*warnings, "Channel 'irc': No PicoClaw adapter available")
 	}
@@ -1020,6 +1050,14 @@ func (c ChannelsConfig) ToStandardChannels() config.ChannelsConfig {
 			BotToken: c.Slack.BotToken,
 			AppToken: c.Slack.AppToken,
 		},
+		Matrix: config.MatrixConfig{
+			Enabled:      c.Matrix.Enabled,
+			Homeserver:   c.Matrix.Homeserver,
+			UserID:       c.Matrix.UserID,
+			AccessToken:  c.Matrix.AccessToken,
+			AllowFrom:    c.Matrix.AllowFrom,
+			JoinOnInvite: true,
+		},
 		LINE: config.LINEConfig{
 			Enabled:            c.LINE.Enabled,
 			ChannelSecret:      c.LINE.ChannelSecret,

pkg/migrate/sources/openclaw/openclaw_config_test.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -375,6 +376,96 @@ func TestConvertToPicoClawWithQQAndDingTalk(t *testing.T) {
 	}
 }
 
+func TestConvertToPicoClawWithMatrix(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+
+	testConfig := `{
+		"channels": {
+			"matrix": {
+				"enabled": true,
+				"homeserver": "https://matrix.example.com",
+				"userId": "@bot:matrix.example.com",
+				"accessToken": "syt_test_token",
+				"allowFrom": ["@alice:matrix.example.com"]
+			}
+		}
+	}`
+
+	err := os.WriteFile(configPath, []byte(testConfig), 0o644)
+	if err != nil {
+		t.Fatalf("failed to write test config: %v", err)
+	}
+
+	cfg, err := LoadOpenClawConfig(configPath)
+	if err != nil {
+		t.Fatalf("failed to load config: %v", err)
+	}
+
+	picoCfg, warnings, err := cfg.ConvertToPicoClaw("")
+	if err != nil {
+		t.Fatalf("failed to convert config: %v", err)
+	}
+
+	if !picoCfg.Channels.Matrix.Enabled {
+		t.Error("matrix should be enabled")
+	}
+	if picoCfg.Channels.Matrix.Homeserver != "https://matrix.example.com" {
+		t.Errorf("expected matrix homeserver, got %q", picoCfg.Channels.Matrix.Homeserver)
+	}
+	if picoCfg.Channels.Matrix.UserID != "@bot:matrix.example.com" {
+		t.Errorf("expected matrix user_id, got %q", picoCfg.Channels.Matrix.UserID)
+	}
+	if picoCfg.Channels.Matrix.AccessToken != "syt_test_token" {
+		t.Errorf("expected matrix access_token, got %q", picoCfg.Channels.Matrix.AccessToken)
+	}
+	if len(picoCfg.Channels.Matrix.AllowFrom) != 1 ||
+		picoCfg.Channels.Matrix.AllowFrom[0] != "@alice:matrix.example.com" {
+		t.Errorf("unexpected matrix allow_from: %#v", picoCfg.Channels.Matrix.AllowFrom)
+	}
+
+	for _, w := range warnings {
+		if strings.Contains(w, "Channel 'matrix'") {
+			t.Fatalf("matrix should no longer be reported as unsupported, warning=%q", w)
+		}
+	}
+}
+
+func TestConvertToPicoClawWithMatrixDisabled(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+
+	testConfig := `{
+		"channels": {
+			"matrix": {
+				"enabled": false,
+				"homeserver": "https://matrix.example.com",
+				"userId": "@bot:matrix.example.com",
+				"accessToken": "syt_test_token"
+			}
+		}
+	}`
+
+	err := os.WriteFile(configPath, []byte(testConfig), 0o644)
+	if err != nil {
+		t.Fatalf("failed to write test config: %v", err)
+	}
+
+	cfg, err := LoadOpenClawConfig(configPath)
+	if err != nil {
+		t.Fatalf("failed to load config: %v", err)
+	}
+
+	picoCfg, _, err := cfg.ConvertToPicoClaw("")
+	if err != nil {
+		t.Fatalf("failed to convert config: %v", err)
+	}
+
+	if picoCfg.Channels.Matrix.Enabled {
+		t.Error("matrix should respect enabled=false from source config")
+	}
+}
+
 func TestOpenClawAgentModel(t *testing.T) {
 	model := &OpenClawAgentModel{
 		Primary:   strPtr("anthropic/claude-3-opus"),
@@ -425,6 +516,9 @@ func TestChannelEnabled(t *testing.T) {
 	if !cfg.IsChannelEnabled("slack") {
 		t.Error("slack should be enabled (explicitly set)")
 	}
+	if !cfg.IsChannelEnabled("matrix") {
+		t.Error("matrix should be enabled (nil config defaults to enabled)")
+	}
 	if cfg.IsChannelEnabled("line") {
 		t.Error("line should return false (not in switch cases)")
 	}

pkg/providers/factory.go

@@ -153,6 +153,15 @@ func resolveProviderSelection(cfg *config.Config) (providerSelection, error) {
 					sel.apiBase = "https://integrate.api.nvidia.com/v1"
 				}
 			}
+		case "vivgrid":
+			if cfg.Providers.Vivgrid.APIKey != "" {
+				sel.apiKey = cfg.Providers.Vivgrid.APIKey
+				sel.apiBase = cfg.Providers.Vivgrid.APIBase
+				sel.proxy = cfg.Providers.Vivgrid.Proxy
+				if sel.apiBase == "" {
+					sel.apiBase = "https://api.vivgrid.com/v1"
+				}
+			}
 		case "claude-cli", "claude-code", "claudecode":
 			workspace := cfg.WorkspacePath()
 			if workspace == "" {
@@ -199,6 +208,15 @@ func resolveProviderSelection(cfg *config.Config) (providerSelection, error) {
 					sel.apiBase = "https://api.mistral.ai/v1"
 				}
 			}
+		case "minimax":
+			if cfg.Providers.Minimax.APIKey != "" {
+				sel.apiKey = cfg.Providers.Minimax.APIKey
+				sel.apiBase = cfg.Providers.Minimax.APIBase
+				sel.proxy = cfg.Providers.Minimax.Proxy
+				if sel.apiBase == "" {
+					sel.apiBase = "https://api.minimaxi.com/v1"
+				}
+			}
 		case "github_copilot", "copilot":
 			sel.providerType = providerTypeGitHubCopilot
 			if cfg.Providers.GitHubCopilot.APIBase != "" {
@@ -295,6 +313,13 @@ func resolveProviderSelection(cfg *config.Config) (providerSelection, error) {
 			if sel.apiBase == "" {
 				sel.apiBase = "https://integrate.api.nvidia.com/v1"
 			}
+		case strings.HasPrefix(model, "vivgrid/") && cfg.Providers.Vivgrid.APIKey != "":
+			sel.apiKey = cfg.Providers.Vivgrid.APIKey
+			sel.apiBase = cfg.Providers.Vivgrid.APIBase
+			sel.proxy = cfg.Providers.Vivgrid.Proxy
+			if sel.apiBase == "" {
+				sel.apiBase = "https://api.vivgrid.com/v1"
+			}
 		case (strings.Contains(lowerModel, "ollama") || strings.HasPrefix(model, "ollama/")) && cfg.Providers.Ollama.APIKey != "":
 			sel.apiKey = cfg.Providers.Ollama.APIKey
 			sel.apiBase = cfg.Providers.Ollama.APIBase
@@ -309,6 +334,13 @@ func resolveProviderSelection(cfg *config.Config) (providerSelection, error) {
 			if sel.apiBase == "" {
 				sel.apiBase = "https://api.mistral.ai/v1"
 			}
+		case (strings.Contains(lowerModel, "minimax") || strings.HasPrefix(model, "minimax/")) && cfg.Providers.Minimax.APIKey != "":
+			sel.apiKey = cfg.Providers.Minimax.APIKey
+			sel.apiBase = cfg.Providers.Minimax.APIBase
+			sel.proxy = cfg.Providers.Minimax.Proxy
+			if sel.apiBase == "" {
+				sel.apiBase = "https://api.minimaxi.com/v1"
+			}
 		case strings.HasPrefix(model, "avian/") && cfg.Providers.Avian.APIKey != "":
 			sel.apiKey = cfg.Providers.Avian.APIKey
 			sel.apiBase = cfg.Providers.Avian.APIBase

pkg/providers/factory_provider.go

@@ -94,7 +94,8 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 
 	case "litellm", "openrouter", "groq", "zhipu", "gemini", "nvidia",
 		"ollama", "moonshot", "shengsuanyun", "deepseek", "cerebras",
-		"volcengine", "vllm", "qwen", "mistral", "avian":
+		"vivgrid", "volcengine", "vllm", "qwen", "mistral", "avian",
+		"minimax":
 		// All other OpenAI-compatible HTTP providers
 		if cfg.APIKey == "" && cfg.APIBase == "" {
 			return nil, "", fmt.Errorf("api_key or api_base is required for HTTP-based protocol %q", protocol)
@@ -200,6 +201,8 @@ func getDefaultAPIBase(protocol string) string {
 		return "https://api.deepseek.com/v1"
 	case "cerebras":
 		return "https://api.cerebras.ai/v1"
+	case "vivgrid":
+		return "https://api.vivgrid.com/v1"
 	case "volcengine":
 		return "https://ark.cn-beijing.volces.com/api/v3"
 	case "qwen":
@@ -210,6 +213,8 @@ func getDefaultAPIBase(protocol string) string {
 		return "https://api.mistral.ai/v1"
 	case "avian":
 		return "https://api.avian.io/v1"
+	case "minimax":
+		return "https://api.minimaxi.com/v1"
 	default:
 		return ""
 	}

pkg/providers/factory_provider_test.go

@@ -108,6 +108,7 @@ func TestCreateProviderFromConfig_DefaultAPIBase(t *testing.T) {
 		{"groq", "groq"},
 		{"openrouter", "openrouter"},
 		{"cerebras", "cerebras"},
+		{"vivgrid", "vivgrid"},
 		{"qwen", "qwen"},
 		{"vllm", "vllm"},
 		{"deepseek", "deepseek"},

pkg/providers/factory_test.go

@@ -88,6 +88,17 @@ func TestResolveProviderSelection(t *testing.T) {
 			wantAPIBase: "https://integrate.api.nvidia.com/v1",
 			wantProxy:   "http://127.0.0.1:7890",
 		},
+		{
+			name: "explicit vivgrid provider uses defaults",
+			setup: func(cfg *config.Config) {
+				cfg.Agents.Defaults.Provider = "vivgrid"
+				cfg.Providers.Vivgrid.APIKey = "vivgrid-key"
+				cfg.Providers.Vivgrid.Proxy = "http://127.0.0.1:7890"
+			},
+			wantType:    providerTypeHTTPCompat,
+			wantAPIBase: "https://api.vivgrid.com/v1",
+			wantProxy:   "http://127.0.0.1:7890",
+		},
 		{
 			name: "openrouter model uses openrouter defaults",
 			setup: func(cfg *config.Config) {

pkg/providers/openai_compat/provider.go

@@ -439,7 +439,8 @@ func normalizeModel(model, apiBase string) string {
 
 	prefix := strings.ToLower(before)
 	switch prefix {
-	case "litellm", "moonshot", "nvidia", "groq", "ollama", "deepseek", "google", "openrouter", "zhipu", "mistral":
+	case "litellm", "moonshot", "nvidia", "groq", "ollama", "deepseek", "google",
+		"openrouter", "zhipu", "mistral", "vivgrid", "minimax":
 		return after
 	default:
 		return model

pkg/providers/openai_compat/provider_test.go

@@ -382,7 +382,7 @@ func TestProviderChat_StripsMoonshotPrefixAndNormalizesKimiTemperature(t *testin
 	}
 }
 
-func TestProviderChat_StripsGroqAndOllamaPrefixes(t *testing.T) {
+func TestProviderChat_StripsGroqOllamaDeepseekVivgridPrefixes(t *testing.T) {
 	tests := []struct {
 		name      string
 		input     string
@@ -408,6 +408,11 @@ func TestProviderChat_StripsGroqAndOllamaPrefixes(t *testing.T) {
 			input:     "deepseek/deepseek-chat",
 			wantModel: "deepseek-chat",
 		},
+		{
+			name:      "strips vivgrid prefix",
+			input:     "vivgrid/auto",
+			wantModel: "auto",
+		},
 	}
 
 	for _, tt := range tests {
@@ -512,6 +517,12 @@ func TestNormalizeModel_UsesAPIBase(t *testing.T) {
 	if got := normalizeModel("openrouter/auto", "https://openrouter.ai/api/v1"); got != "openrouter/auto" {
 		t.Fatalf("normalizeModel(openrouter) = %q, want %q", got, "openrouter/auto")
 	}
+	if got := normalizeModel("vivgrid/managed", "https://api.vivgrid.com/v1"); got != "managed" {
+		t.Fatalf("normalizeModel(vivgrid) = %q, want %q", got, "managed")
+	}
+	if got := normalizeModel("vivgrid/auto", "https://api.vivgrid.com/v1"); got != "auto" {
+		t.Fatalf("normalizeModel(vivgrid auto) = %q, want %q", got, "auto")
+	}
 }
 
 func TestProvider_RequestTimeoutDefault(t *testing.T) {

pkg/tools/filesystem.go

@@ -2,17 +2,24 @@ package tools
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"io"
 	"io/fs"
+	"math"
 	"os"
 	"path/filepath"
 	"regexp"
+	"strconv"
 	"strings"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/fileutil"
+	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
+const MaxReadFileSize = 64 * 1024 // 64KB limit to avoid context overflow
+
 // validatePath ensures the given path is within the workspace if restrict is true.
 func validatePath(path, workspace string, restrict bool) (string, error) {
 	if workspace == "" {
@@ -85,15 +92,30 @@ func isWithinWorkspace(candidate, workspace string) bool {
 }
 
 type ReadFileTool struct {
-	fs fileSystem
+	fs      fileSystem
+	maxSize int64
 }
 
-func NewReadFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *ReadFileTool {
+func NewReadFileTool(
+	workspace string,
+	restrict bool,
+	maxReadFileSize int,
+	allowPaths ...[]*regexp.Regexp,
+) *ReadFileTool {
 	var patterns []*regexp.Regexp
 	if len(allowPaths) > 0 {
 		patterns = allowPaths[0]
 	}
-	return &ReadFileTool{fs: buildFs(workspace, restrict, patterns)}
+
+	maxSize := int64(maxReadFileSize)
+	if maxSize <= 0 {
+		maxSize = MaxReadFileSize
+	}
+
+	return &ReadFileTool{
+		fs:      buildFs(workspace, restrict, patterns),
+		maxSize: maxSize,
+	}
 }
 
 func (t *ReadFileTool) Name() string {
@@ -101,7 +123,7 @@ func (t *ReadFileTool) Name() string {
 }
 
 func (t *ReadFileTool) Description() string {
-	return "Read the contents of a file"
+	return "Read the contents of a file. Supports pagination via `offset` and `length`."
 }
 
 func (t *ReadFileTool) Parameters() map[string]any {
@@ -110,7 +132,17 @@ func (t *ReadFileTool) Parameters() map[string]any {
 		"properties": map[string]any{
 			"path": map[string]any{
 				"type":        "string",
-				"description": "Path to the file to read",
+				"description": "Path to the file to read.",
+			},
+			"offset": map[string]any{
+				"type":        "integer",
+				"description": "Byte offset to start reading from.",
+				"default":     0,
+			},
+			"length": map[string]any{
+				"type":        "integer",
+				"description": "Maximum number of bytes to read.",
+				"default":     t.maxSize,
 			},
 		},
 		"required": []string{"path"},
@@ -123,11 +155,171 @@ func (t *ReadFileTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 		return ErrorResult("path is required")
 	}
 
-	content, err := t.fs.ReadFile(path)
+	// offset (optional, default 0)
+	offset, err := getInt64Arg(args, "offset", 0)
 	if err != nil {
 		return ErrorResult(err.Error())
 	}
-	return NewToolResult(string(content))
+	if offset < 0 {
+		return ErrorResult("offset must be >= 0")
+	}
+
+	// length (optional, capped at MaxReadFileSize)
+	length, err := getInt64Arg(args, "length", t.maxSize)
+	if err != nil {
+		return ErrorResult(err.Error())
+	}
+	if length <= 0 {
+		return ErrorResult("length must be > 0")
+	}
+	if length > t.maxSize {
+		length = t.maxSize
+	}
+
+	file, err := t.fs.Open(path)
+	if err != nil {
+		return ErrorResult(err.Error())
+	}
+	defer file.Close()
+
+	// measure total size
+	totalSize := int64(-1) // -1 means unknown
+	if info, statErr := file.Stat(); statErr == nil {
+		totalSize = info.Size()
+	}
+
+	// sniff the first 512 bytes to detect binary content before loading
+	// it into the LLM context. Seeking back to 0 afterwards restores state.
+	sniff := make([]byte, 512)
+	sniffN, _ := file.Read(sniff)
+
+	// Reset read position to beginning before applying the caller's offset.
+	if seeker, ok := file.(io.Seeker); ok {
+		_, err = seeker.Seek(0, io.SeekStart)
+		if err != nil {
+			return ErrorResult(fmt.Sprintf("failed to reset file position after sniff: %v", err))
+		}
+	} else {
+		// Non-seekable: we consumed sniffN bytes above; account for them when
+		// discarding to reach the requested offset below.
+		// If offset < sniffN the data we already read covers it, which we
+		// cannot replay on a non-seekable stream — return a clear error.
+		if offset < int64(sniffN) && offset > 0 {
+			return ErrorResult(
+				"non-seekable file: cannot seek to an offset within the first 512 bytes after binary detection",
+			)
+		}
+	}
+
+	// Seek to the requested offset.
+	if seeker, ok := file.(io.Seeker); ok {
+		_, err = seeker.Seek(offset, io.SeekStart)
+		if err != nil {
+			return ErrorResult(fmt.Sprintf("failed to seek to offset %d: %v", offset, err))
+		}
+	} else if offset > 0 {
+		// Fallback for non-seekable streams: discard leading bytes.
+		// sniffN bytes were already consumed above, so subtract them.
+		remaining := offset - int64(sniffN)
+		if remaining > 0 {
+			_, err = io.CopyN(io.Discard, file, remaining)
+			if err != nil {
+				return ErrorResult(fmt.Sprintf("failed to advance to offset %d: %v", offset, err))
+			}
+		}
+	}
+
+	// read length+1 bytes to reliably detect whether more content exists
+	// without relying on totalSize (which may be -1 for non-seekable streams).
+	// This avoids the false-positive TRUNCATED message on the last page.
+	probe := make([]byte, length+1)
+	n, err := io.ReadFull(file, probe)
+	// FIX: io.ReadFull returns io.ErrUnexpectedEOF for partial reads (0 < n < len),
+	// and io.EOF only when n == 0. Both are normal terminal conditions — only
+	// other errors are genuine failures.
+	if err != nil && err != io.EOF && !errors.Is(err, io.ErrUnexpectedEOF) {
+		return ErrorResult(fmt.Sprintf("failed to read file content: %v", err))
+	}
+
+	// hasMore is true only when we actually got the extra probe byte.
+	hasMore := int64(n) > length
+	data := probe[:min(int64(n), length)]
+
+	if len(data) == 0 {
+		return NewToolResult("[END OF FILE - no content at this offset]")
+	}
+
+	// Build metadata header.
+	// use filepath.Base(path) instead of the raw path to avoid leaking
+	// internal filesystem structure into the LLM context.
+	readEnd := offset + int64(len(data))
+	// use ASCII hyphen-minus instead of en-dash (U+2013) to keep the
+	// header parseable by downstream tools and log processors.
+	readRange := fmt.Sprintf("bytes %d-%d", offset, readEnd-1)
+
+	displayPath := filepath.Base(path)
+	var header string
+	if totalSize >= 0 {
+		header = fmt.Sprintf(
+			"[file: %s | total: %d bytes | read: %s]",
+			displayPath, totalSize, readRange,
+		)
+	} else {
+		header = fmt.Sprintf(
+			"[file: %s | read: %s | total size unknown]",
+			displayPath, readRange,
+		)
+	}
+
+	if hasMore {
+		header += fmt.Sprintf(
+			"\n[TRUNCATED - file has more content. Call read_file again with offset=%d to continue.]",
+			readEnd,
+		)
+	} else {
+		header += "\n[END OF FILE - no further content.]"
+	}
+
+	logger.DebugCF("tool", "ReadFileTool execution completed successfully",
+		map[string]any{
+			"path":       path,
+			"bytes_read": len(data),
+			"has_more":   hasMore,
+		})
+
+	return NewToolResult(header + "\n\n" + string(data))
+}
+
+// getInt64Arg extracts an integer argument from the args map, returning the
+// provided default if the key is absent.
+func getInt64Arg(args map[string]any, key string, defaultVal int64) (int64, error) {
+	raw, exists := args[key]
+	if !exists {
+		return defaultVal, nil
+	}
+
+	switch v := raw.(type) {
+	case float64:
+		if v != math.Trunc(v) {
+			return 0, fmt.Errorf("%s must be an integer, got float %v", key, v)
+		}
+		if v > math.MaxInt64 || v < math.MinInt64 {
+			return 0, fmt.Errorf("%s value %v overflows int64", key, v)
+		}
+		return int64(v), nil
+	case int:
+		return int64(v), nil
+	case int64:
+		return v, nil
+	case string:
+		parsed, err := strconv.ParseInt(v, 10, 64)
+		if err != nil {
+			return 0, fmt.Errorf("invalid integer format for %s parameter: %w", key, err)
+		}
+		return parsed, nil
+	default:
+		return 0, fmt.Errorf("unsupported type %T for %s parameter", raw, key)
+	}
 }
 
 type WriteFileTool struct {
@@ -249,6 +441,7 @@ type fileSystem interface {
 	ReadFile(path string) ([]byte, error)
 	WriteFile(path string, data []byte) error
 	ReadDir(path string) ([]os.DirEntry, error)
+	Open(path string) (fs.File, error)
 }
 
 // hostFs is an unrestricted fileReadWriter that operates directly on the host filesystem.
@@ -278,6 +471,20 @@ func (h *hostFs) WriteFile(path string, data []byte) error {
 	return fileutil.WriteFileAtomic(path, data, 0o600)
 }
 
+func (h *hostFs) Open(path string) (fs.File, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, fmt.Errorf("failed to open file: file not found: %w", err)
+		}
+		if os.IsPermission(err) {
+			return nil, fmt.Errorf("failed to open file: access denied: %w", err)
+		}
+		return nil, fmt.Errorf("failed to open file: %w", err)
+	}
+	return f, nil
+}
+
 // sandboxFs is a sandboxed fileSystem that operates within a strictly defined workspace using os.Root.
 type sandboxFs struct {
 	workspace string
@@ -389,6 +596,26 @@ func (r *sandboxFs) ReadDir(path string) ([]os.DirEntry, error) {
 	return entries, err
 }
 
+func (r *sandboxFs) Open(path string) (fs.File, error) {
+	var f fs.File
+	err := r.execute(path, func(root *os.Root, relPath string) error {
+		file, err := root.Open(relPath)
+		if err != nil {
+			if os.IsNotExist(err) {
+				return fmt.Errorf("failed to open file: file not found: %w", err)
+			}
+			if os.IsPermission(err) || strings.Contains(err.Error(), "escapes from parent") ||
+				strings.Contains(err.Error(), "permission denied") {
+				return fmt.Errorf("failed to open file: access denied: %w", err)
+			}
+			return fmt.Errorf("failed to open file: %w", err)
+		}
+		f = file
+		return nil
+	})
+	return f, err
+}
+
 // whitelistFs wraps a sandboxFs and allows access to specific paths outside
 // the workspace when they match any of the provided patterns.
 type whitelistFs struct {
@@ -427,6 +654,13 @@ func (w *whitelistFs) ReadDir(path string) ([]os.DirEntry, error) {
 	return w.sandbox.ReadDir(path)
 }
 
+func (w *whitelistFs) Open(path string) (fs.File, error) {
+	if w.matches(path) {
+		return w.host.Open(path)
+	}
+	return w.sandbox.Open(path)
+}
+
 // buildFs returns the appropriate fileSystem implementation based on restriction
 // settings and optional path whitelist patterns.
 func buildFs(workspace string, restrict bool, patterns []*regexp.Regexp) fileSystem {

pkg/tools/filesystem_test.go

@@ -18,7 +18,7 @@ func TestFilesystemTool_ReadFile_Success(t *testing.T) {
 	testFile := filepath.Join(tmpDir, "test.txt")
 	os.WriteFile(testFile, []byte("test content"), 0o644)
 
-	tool := NewReadFileTool("", false)
+	tool := NewReadFileTool("", false, MaxReadFileSize)
 	ctx := context.Background()
 	args := map[string]any{
 		"path": testFile,
@@ -45,7 +45,7 @@ func TestFilesystemTool_ReadFile_Success(t *testing.T) {
 
 // TestFilesystemTool_ReadFile_NotFound verifies error handling for missing file
 func TestFilesystemTool_ReadFile_NotFound(t *testing.T) {
-	tool := NewReadFileTool("", false)
+	tool := NewReadFileTool("", false, MaxReadFileSize)
 	ctx := context.Background()
 	args := map[string]any{
 		"path": "/nonexistent_file_12345.txt",
@@ -59,7 +59,7 @@ func TestFilesystemTool_ReadFile_NotFound(t *testing.T) {
 	}
 
 	// Should contain error message
-	if !strings.Contains(result.ForLLM, "failed to read") && !strings.Contains(result.ForUser, "failed to read") {
+	if !strings.Contains(result.ForLLM, "failed to open file") && !strings.Contains(result.ForUser, "failed to read") {
 		t.Errorf("Expected error message, got ForLLM: %s, ForUser: %s", result.ForLLM, result.ForUser)
 	}
 }
@@ -271,7 +271,7 @@ func TestFilesystemTool_ReadFile_RejectsSymlinkEscape(t *testing.T) {
 		t.Skipf("symlink not supported in this environment: %v", err)
 	}
 
-	tool := NewReadFileTool(workspace, true)
+	tool := NewReadFileTool(workspace, true, MaxReadFileSize)
 	result := tool.Execute(context.Background(), map[string]any{
 		"path": link,
 	})
@@ -289,7 +289,7 @@ func TestFilesystemTool_ReadFile_RejectsSymlinkEscape(t *testing.T) {
 }
 
 func TestFilesystemTool_EmptyWorkspace_AccessDenied(t *testing.T) {
-	tool := NewReadFileTool("", true) // restrict=true but workspace=""
+	tool := NewReadFileTool("", true, MaxReadFileSize) // restrict=true but workspace=""
 
 	// Try to read a sensitive file (simulated by a temp file outside workspace)
 	tmpDir := t.TempDir()
@@ -499,7 +499,7 @@ func TestWhitelistFs_AllowsMatchingPaths(t *testing.T) {
 	// Pattern allows access to the outsideDir.
 	patterns := []*regexp.Regexp{regexp.MustCompile(`^` + regexp.QuoteMeta(outsideDir))}
 
-	tool := NewReadFileTool(workspace, true, patterns)
+	tool := NewReadFileTool(workspace, true, MaxReadFileSize, patterns)
 
 	// Read from whitelisted path should succeed.
 	result := tool.Execute(context.Background(), map[string]any{"path": outsideFile})
@@ -520,3 +520,127 @@ func TestWhitelistFs_AllowsMatchingPaths(t *testing.T) {
 		t.Errorf("expected non-whitelisted path to be blocked, got: %s", result.ForLLM)
 	}
 }
+
+// TestReadFileTool_ChunkedReading verifies the pagination logic of the tool
+// by reading a file in multiple chunks using 'offset' and 'length'.
+func TestReadFileTool_ChunkedReading(t *testing.T) {
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "pagination_test.txt")
+
+	// Create a test file with exactly 26 bytes of content
+	fullContent := "abcdefghijklmnopqrstuvwxyz"
+	err := os.WriteFile(testFile, []byte(fullContent), 0o644)
+	if err != nil {
+		t.Fatalf("Failed to write test file: %v", err)
+	}
+
+	tool := NewReadFileTool(tmpDir, false, MaxReadFileSize)
+	ctx := context.Background()
+
+	// --- Step 1: Read the first chunk (10 bytes) ---
+	args1 := map[string]any{
+		"path":   testFile,
+		"offset": 0,
+		"length": 10,
+	}
+	result1 := tool.Execute(ctx, args1)
+
+	if result1.IsError {
+		t.Fatalf("Chunk 1 failed: %s", result1.ForLLM)
+	}
+
+	// Expect the first 10 characters
+	if !strings.Contains(result1.ForLLM, "abcdefghij") {
+		t.Errorf("Chunk 1 should contain 'abcdefghij', got: %s", result1.ForLLM)
+	}
+	// Expect the header to indicate the file is truncated
+	if !strings.Contains(result1.ForLLM, "[TRUNCATED") {
+		t.Errorf("Chunk 1 header should indicate truncation, got: %s", result1.ForLLM)
+	}
+	// Expect the header to suggest the next offset (10)
+	if !strings.Contains(result1.ForLLM, "offset=10") {
+		t.Errorf("Chunk 1 header should suggest next offset=10, got: %s", result1.ForLLM)
+	}
+
+	// Step 2: Read the second chunk (10 bytes) ---
+	args2 := map[string]any{
+		"path":   testFile,
+		"offset": 10,
+		"length": 10,
+	}
+	result2 := tool.Execute(ctx, args2)
+
+	if result2.IsError {
+		t.Fatalf("Chunk 2 failed: %s", result2.ForLLM)
+	}
+
+	// Expect the next 10 characters
+	if !strings.Contains(result2.ForLLM, "klmnopqrst") {
+		t.Errorf("Chunk 2 should contain 'klmnopqrst', got: %s", result2.ForLLM)
+	}
+	// Expect the header to suggest the next offset (20)
+	if !strings.Contains(result2.ForLLM, "offset=20") {
+		t.Errorf("Chunk 2 header should suggest next offset=20, got: %s", result2.ForLLM)
+	}
+
+	// Step 3: Read the final chunk (remaining 6 bytes) ---
+	// We ask for 10 bytes, but only 6 are left in the file
+	args3 := map[string]any{
+		"path":   testFile,
+		"offset": 20,
+		"length": 10,
+	}
+	result3 := tool.Execute(ctx, args3)
+
+	if result3.IsError {
+		t.Fatalf("Chunk 3 failed: %s", result3.ForLLM)
+	}
+
+	// Expect the last 6 characters
+	if !strings.Contains(result3.ForLLM, "uvwxyz") {
+		t.Errorf("Chunk 3 should contain 'uvwxyz', got: %s", result3.ForLLM)
+	}
+	// Expect the header to indicate the end of the file
+	if !strings.Contains(result3.ForLLM, "[END OF FILE") {
+		t.Errorf("Chunk 3 header should indicate end of file, got: %s", result3.ForLLM)
+	}
+
+	// Ensure no TRUNCATED message is present in the final chunk
+	if strings.Contains(result3.ForLLM, "[TRUNCATED") {
+		t.Errorf("Chunk 3 header should NOT indicate truncation, got: %s", result3.ForLLM)
+	}
+}
+
+// TestReadFileTool_OffsetBeyondEOF checks the behavior when requesting
+// An offset that exceeds the total file size.
+func TestReadFileTool_OffsetBeyondEOF(t *testing.T) {
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "short.txt")
+
+	// create a file of only 5 bytes
+	err := os.WriteFile(testFile, []byte("12345"), 0o644)
+	if err != nil {
+		t.Fatalf("Failed to write test file: %v", err)
+	}
+
+	tool := NewReadFileTool(tmpDir, false, MaxReadFileSize)
+	ctx := context.Background()
+
+	args := map[string]any{
+		"path":   testFile,
+		"offset": int64(100), // Offset beyond the end of the file
+	}
+
+	result := tool.Execute(ctx, args)
+
+	// It should not be classified as a tool execution error
+	if result.IsError {
+		t.Errorf("A mistake was not expected, obtained IsError=true: %s", result.ForLLM)
+	}
+
+	// Must return EXACTLY the string provided in the code
+	expectedMsg := "[END OF FILE - no content at this offset]"
+	if result.ForLLM != expectedMsg {
+		t.Errorf("The message %q was expected, obtained: %q", expectedMsg, result.ForLLM)
+	}
+}

web/Makefile

@@ -0,0 +1,38 @@
+.PHONY: dev dev-frontend dev-backend build test lint clean
+
+# Run both frontend and backend dev servers
+dev:
+	@if [ ! -f backend/picoclaw-web ] || [ ! -d backend/dist ]; then \
+		echo "Build artifacts not found, building..."; \
+		$(MAKE) build; \
+	fi
+	@echo "Starting backend and frontend dev servers..."
+	@$(MAKE) dev-backend & $(MAKE) dev-frontend
+
+# Start frontend dev server (Vite, with proxy to backend)
+dev-frontend:
+	cd frontend && pnpm dev
+
+# Start backend dev server
+dev-backend:
+	cd backend && go run .
+
+# Build frontend and embed into Go binary
+build:
+	cd frontend && pnpm build:backend
+	cd backend && go build -o picoclaw-web .
+
+# Run all tests
+test:
+	cd backend && go test ./...
+	cd frontend && pnpm lint
+
+# Lint and format
+lint:
+	cd backend && go vet ./...
+	cd frontend && pnpm check
+
+# Clean build artifacts
+clean:
+	rm -rf frontend/dist backend/dist backend/picoclaw-web
+	mkdir -p backend/dist && touch backend/dist/.gitkeep

web/README.md

@@ -0,0 +1,51 @@
+# Picoclaw Web
+
+This directory contains the standalone web service for `picoclaw`.
+It provides a complete unified web interface, acting as a dashboard, configuration center, and interactive console (channel client) for the core `picoclaw` engine.
+
+## Architecture
+
+The service is structured as a monorepo containing both the backend and frontend code to ensure high cohesion and simplify deployment.
+
+*   **`backend/`**: The Go-based web server. It provides RESTful APIs, manages WebSocket connections for chat, and handles the lifecycle of the `picoclaw` process. It eventually embeds the compiled frontend assets into a single executable.
+*   **`frontend/`**: The Vite + React + TanStack Router single-page application (SPA). It provides the interactive user interface.
+
+## Getting Started
+
+### Prerequisites
+
+*   Go 1.25+
+*   Node.js 20+ with pnpm
+
+### Development
+
+Run both the frontend dev server and the Go backend simultaneously:
+
+```bash
+make dev
+```
+
+Or run them separately:
+
+```bash
+make dev-frontend   # Vite dev server
+make dev-backend    # Go backend
+```
+
+### Build
+
+Build the frontend and embed it into a single Go binary:
+
+```bash
+make build
+```
+
+The output binary is `backend/picoclaw-web`.
+
+### Other Commands
+
+```bash
+make test    # Run backend tests and frontend lint
+make lint    # Run go vet and prettier/eslint
+make clean   # Remove all build artifacts
+```

web/backend/.gitignore

@@ -0,0 +1,19 @@
+# Go build output
+*.exe
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+picoclaw-web
+
+# Frontend build artifacts (embedded by Go)
+dist/*
+!dist/.gitkeep
+
+# OS
+.DS_Store
+
+# Editors
+.vscode/
+.idea/

web/backend/api/channels.go

@@ -0,0 +1,47 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+)
+
+type channelCatalogItem struct {
+	Name      string `json:"name"`
+	ConfigKey string `json:"config_key"`
+	Variant   string `json:"variant,omitempty"`
+}
+
+var channelCatalog = []channelCatalogItem{
+	{Name: "telegram", ConfigKey: "telegram"},
+	{Name: "discord", ConfigKey: "discord"},
+	{Name: "slack", ConfigKey: "slack"},
+	{Name: "feishu", ConfigKey: "feishu"},
+	{Name: "dingtalk", ConfigKey: "dingtalk"},
+	{Name: "line", ConfigKey: "line"},
+	{Name: "qq", ConfigKey: "qq"},
+	{Name: "onebot", ConfigKey: "onebot"},
+	{Name: "wecom", ConfigKey: "wecom"},
+	{Name: "wecom_app", ConfigKey: "wecom_app"},
+	{Name: "wecom_aibot", ConfigKey: "wecom_aibot"},
+	{Name: "whatsapp", ConfigKey: "whatsapp", Variant: "bridge"},
+	{Name: "whatsapp_native", ConfigKey: "whatsapp", Variant: "native"},
+	{Name: "pico", ConfigKey: "pico"},
+	{Name: "maixcam", ConfigKey: "maixcam"},
+	{Name: "matrix", ConfigKey: "matrix"},
+	{Name: "irc", ConfigKey: "irc"},
+}
+
+// registerChannelRoutes binds read-only channel catalog endpoints to the ServeMux.
+func (h *Handler) registerChannelRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/channels/catalog", h.handleListChannelCatalog)
+}
+
+// handleListChannelCatalog returns the channels supported by backend.
+//
+//	GET /api/channels/catalog
+func (h *Handler) handleListChannelCatalog(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"channels": channelCatalog,
+	})
+}

web/backend/api/config.go

@@ -0,0 +1,221 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// registerConfigRoutes binds configuration management endpoints to the ServeMux.
+func (h *Handler) registerConfigRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/config", h.handleGetConfig)
+	mux.HandleFunc("PUT /api/config", h.handleUpdateConfig)
+	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()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	if err := json.NewEncoder(w).Encode(cfg); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// handleUpdateConfig updates the complete system configuration.
+//
+//	PUT /api/config
+func (h *Handler) handleUpdateConfig(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	var cfg config.Config
+	if err := json.Unmarshal(body, &cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if errs := validateConfig(&cfg); len(errs) > 0 {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		json.NewEncoder(w).Encode(map[string]any{
+			"status": "validation_error",
+			"errors": errs,
+		})
+		return
+	}
+
+	if err := config.SaveConfig(h.configPath, &cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+}
+
+// handlePatchConfig partially updates the system configuration using JSON Merge Patch (RFC 7396).
+// Only the fields present in the request body will be updated; all other fields remain unchanged.
+//
+//	PATCH /api/config
+func (h *Handler) handlePatchConfig(w http.ResponseWriter, r *http.Request) {
+	patchBody, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	// Validate the patch is valid JSON
+	var patch map[string]any
+	if err = json.Unmarshal(patchBody, &patch); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	// Load existing config and marshal to a map for merging
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	existing, err := json.Marshal(cfg)
+	if err != nil {
+		http.Error(w, "Failed to serialize current config", http.StatusInternalServerError)
+		return
+	}
+
+	var base map[string]any
+	if err = json.Unmarshal(existing, &base); err != nil {
+		http.Error(w, "Failed to parse current config", http.StatusInternalServerError)
+		return
+	}
+
+	// Recursively merge patch into base
+	mergeMap(base, patch)
+
+	// Convert merged map back to Config struct
+	merged, err := json.Marshal(base)
+	if err != nil {
+		http.Error(w, "Failed to serialize merged config", http.StatusInternalServerError)
+		return
+	}
+
+	var newCfg config.Config
+	if err := json.Unmarshal(merged, &newCfg); err != nil {
+		http.Error(w, fmt.Sprintf("Merged config is invalid: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if errs := validateConfig(&newCfg); len(errs) > 0 {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		json.NewEncoder(w).Encode(map[string]any{
+			"status": "validation_error",
+			"errors": errs,
+		})
+		return
+	}
+
+	if err := config.SaveConfig(h.configPath, &newCfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+}
+
+// validateConfig checks the config for common errors before saving.
+// Returns a list of human-readable error strings; empty means valid.
+func validateConfig(cfg *config.Config) []string {
+	var errs []string
+
+	// Validate model_list entries
+	if err := cfg.ValidateModelList(); err != nil {
+		errs = append(errs, err.Error())
+	}
+
+	// Gateway port range
+	if cfg.Gateway.Port != 0 && (cfg.Gateway.Port < 1 || cfg.Gateway.Port > 65535) {
+		errs = append(errs, fmt.Sprintf("gateway.port %d is out of valid range (1-65535)", cfg.Gateway.Port))
+	}
+
+	// Pico channel: token required when enabled
+	if cfg.Channels.Pico.Enabled && cfg.Channels.Pico.Token == "" {
+		errs = append(errs, "channels.pico.token is required when pico channel is enabled")
+	}
+
+	// Telegram: token required when enabled
+	if cfg.Channels.Telegram.Enabled && cfg.Channels.Telegram.Token == "" {
+		errs = append(errs, "channels.telegram.token is required when telegram channel is enabled")
+	}
+
+	// Discord: token required when enabled
+	if cfg.Channels.Discord.Enabled && cfg.Channels.Discord.Token == "" {
+		errs = append(errs, "channels.discord.token is required when discord channel is enabled")
+	}
+
+	return errs
+}
+
+// mergeMap recursively merges src into dst (JSON Merge Patch semantics).
+// - If a key in src has a null value, it is deleted from dst.
+// - If both dst and src have a nested object for the same key, merge recursively.
+// - Otherwise the value from src overwrites dst.
+func mergeMap(dst, src map[string]any) {
+	for key, srcVal := range src {
+		if srcVal == nil {
+			delete(dst, key)
+			continue
+		}
+		srcMap, srcIsMap := srcVal.(map[string]any)
+		dstMap, dstIsMap := dst[key].(map[string]any)
+		if srcIsMap && dstIsMap {
+			mergeMap(dstMap, srcMap)
+		} else {
+			dst[key] = srcVal
+		}
+	}
+}

web/backend/api/events.go

@@ -0,0 +1,62 @@
+package api
+
+import (
+	"encoding/json"
+	"sync"
+)
+
+// GatewayEvent represents a state change event for the gateway process.
+type GatewayEvent struct {
+	Status string `json:"gateway_status"` // "running", "starting", "stopped", "error"
+	PID    int    `json:"pid,omitempty"`
+}
+
+// EventBroadcaster manages SSE client subscriptions and broadcasts events.
+type EventBroadcaster struct {
+	mu      sync.RWMutex
+	clients map[chan string]struct{}
+}
+
+// NewEventBroadcaster creates a new broadcaster.
+func NewEventBroadcaster() *EventBroadcaster {
+	return &EventBroadcaster{
+		clients: make(map[chan string]struct{}),
+	}
+}
+
+// Subscribe adds a new listener channel and returns it.
+// The caller must call Unsubscribe when done.
+func (b *EventBroadcaster) Subscribe() chan string {
+	ch := make(chan string, 8)
+	b.mu.Lock()
+	b.clients[ch] = struct{}{}
+	b.mu.Unlock()
+	return ch
+}
+
+// Unsubscribe removes a listener channel and closes it.
+func (b *EventBroadcaster) Unsubscribe(ch chan string) {
+	b.mu.Lock()
+	delete(b.clients, ch)
+	b.mu.Unlock()
+	close(ch)
+}
+
+// Broadcast sends a GatewayEvent to all connected SSE clients.
+func (b *EventBroadcaster) Broadcast(event GatewayEvent) {
+	data, err := json.Marshal(event)
+	if err != nil {
+		return
+	}
+
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	for ch := range b.clients {
+		// Non-blocking send; drop event if client is slow
+		select {
+		case ch <- string(data):
+		default:
+		}
+	}
+}

web/backend/api/gateway.go

@@ -0,0 +1,555 @@
+package api
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// gateway holds the state for the managed gateway process.
+var gateway = struct {
+	mu     sync.Mutex
+	cmd    *exec.Cmd
+	logs   *LogBuffer
+	events *EventBroadcaster
+}{
+	logs:   NewLogBuffer(200),
+	events: NewEventBroadcaster(),
+}
+
+// registerGatewayRoutes binds gateway lifecycle endpoints to the ServeMux.
+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/start", h.handleGatewayStart)
+	mux.HandleFunc("POST /api/gateway/stop", h.handleGatewayStop)
+	mux.HandleFunc("POST /api/gateway/restart", h.handleGatewayRestart)
+}
+
+// TryAutoStartGateway checks whether gateway start preconditions are met and
+// starts it when possible. Intended to be called by the backend at startup.
+func (h *Handler) TryAutoStartGateway() {
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	if isGatewayProcessAliveLocked() {
+		return
+	}
+	if gateway.cmd != nil && gateway.cmd.Process != nil {
+		gateway.cmd = nil
+	}
+
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		log.Printf("Skip auto-starting gateway: %v", err)
+		return
+	}
+	if !ready {
+		log.Printf("Skip auto-starting gateway: %s", reason)
+		return
+	}
+
+	pid, err := h.startGatewayLocked()
+	if err != nil {
+		log.Printf("Failed to auto-start gateway: %v", err)
+		return
+	}
+	log.Printf("Gateway auto-started (PID: %d)", pid)
+}
+
+// gatewayStartReady validates whether current config can start the gateway.
+func (h *Handler) gatewayStartReady() (bool, string, error) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		return false, "", fmt.Errorf("failed to load config: %w", err)
+	}
+
+	modelName := strings.TrimSpace(cfg.Agents.Defaults.GetModelName())
+	if modelName == "" {
+		return false, "no default model configured", nil
+	}
+
+	modelCfg := lookupModelConfig(cfg, modelName)
+	if modelCfg == nil {
+		return false, fmt.Sprintf("default model %q is invalid", modelName), nil
+	}
+
+	hasCredential := strings.TrimSpace(modelCfg.APIKey) != "" ||
+		strings.TrimSpace(modelCfg.AuthMethod) != ""
+	if !hasCredential {
+		return false, fmt.Sprintf("default model %q has no credentials configured", modelName), nil
+	}
+
+	return true, "", nil
+}
+
+func lookupModelConfig(cfg *config.Config, modelName string) *config.ModelConfig {
+	modelCfg, err := cfg.GetModelConfig(modelName)
+	if err != nil {
+		return nil
+	}
+	return modelCfg
+}
+
+func isGatewayProcessAliveLocked() bool {
+	return isCmdProcessAliveLocked(gateway.cmd)
+}
+
+func isCmdProcessAliveLocked(cmd *exec.Cmd) bool {
+	if cmd == nil || cmd.Process == nil {
+		return false
+	}
+
+	// Wait() sets ProcessState when the process exits; use it when available.
+	if cmd.ProcessState != nil && cmd.ProcessState.Exited() {
+		return false
+	}
+
+	// Windows does not support Signal(0) probing. If we still own cmd and it
+	// has not reported exit, treat it as alive.
+	if runtime.GOOS == "windows" {
+		return true
+	}
+
+	return cmd.Process.Signal(syscall.Signal(0)) == nil
+}
+
+func (h *Handler) startGatewayLocked() (int, error) {
+	// Locate the picoclaw executable
+	execPath := findPicoclawBinary()
+
+	cmd := exec.Command(execPath, "gateway")
+
+	stdoutPipe, err := cmd.StdoutPipe()
+	if err != nil {
+		return 0, fmt.Errorf("failed to create stdout pipe: %w", err)
+	}
+
+	stderrPipe, err := cmd.StderrPipe()
+	if err != nil {
+		return 0, fmt.Errorf("failed to create stderr pipe: %w", err)
+	}
+
+	// Clear old logs for this new run
+	gateway.logs.Reset()
+
+	// Ensure Pico Channel is configured before starting gateway
+	if _, err := h.ensurePicoChannel(); err != nil {
+		log.Printf("Warning: failed to ensure pico channel: %v", err)
+		// Non-fatal: gateway can still start without pico channel
+	}
+
+	if err := cmd.Start(); err != nil {
+		return 0, fmt.Errorf("failed to start gateway: %w", err)
+	}
+
+	gateway.cmd = cmd
+	pid := cmd.Process.Pid
+	log.Printf("Started picoclaw gateway (PID: %d) from %s", pid, execPath)
+
+	// Broadcast starting event
+	gateway.events.Broadcast(GatewayEvent{Status: "starting", PID: pid})
+
+	// Capture stdout/stderr in background
+	go scanPipe(stdoutPipe, gateway.logs)
+	go scanPipe(stderrPipe, gateway.logs)
+
+	// Wait for exit in background and clean up
+	go func() {
+		if err := cmd.Wait(); err != nil {
+			log.Printf("Gateway process exited: %v", err)
+		} else {
+			log.Printf("Gateway process exited normally")
+		}
+
+		gateway.mu.Lock()
+		if gateway.cmd == cmd {
+			gateway.cmd = nil
+		}
+		gateway.mu.Unlock()
+
+		// Broadcast stopped event
+		gateway.events.Broadcast(GatewayEvent{Status: "stopped"})
+	}()
+
+	// Start a goroutine to probe health and broadcast "running" once ready
+	go func() {
+		for i := 0; i < 30; i++ { // try for up to 15 seconds
+			time.Sleep(500 * time.Millisecond)
+			gateway.mu.Lock()
+			stillOurs := gateway.cmd == cmd
+			gateway.mu.Unlock()
+			if !stillOurs {
+				return
+			}
+			cfg, err := config.LoadConfig(h.configPath)
+			if err != nil {
+				continue
+			}
+			healthHost := "127.0.0.1"
+			if cfg.Gateway.Host != "" && cfg.Gateway.Host != "0.0.0.0" {
+				healthHost = cfg.Gateway.Host
+			}
+			healthPort := cfg.Gateway.Port
+			if healthPort == 0 {
+				healthPort = 18790
+			}
+			healthURL := fmt.Sprintf("http://%s/health", net.JoinHostPort(healthHost, strconv.Itoa(healthPort)))
+			client := http.Client{Timeout: 1 * time.Second}
+			resp, err := client.Get(healthURL)
+			if err == nil {
+				resp.Body.Close()
+				if resp.StatusCode == http.StatusOK {
+					gateway.events.Broadcast(GatewayEvent{Status: "running", PID: pid})
+					return
+				}
+			}
+		}
+	}()
+
+	return pid, nil
+}
+
+// handleGatewayStart starts the picoclaw gateway subprocess.
+//
+//	POST /api/gateway/start
+func (h *Handler) handleGatewayStart(w http.ResponseWriter, r *http.Request) {
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	// Prevent duplicate starts
+	if isGatewayProcessAliveLocked() {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusConflict)
+		json.NewEncoder(w).Encode(map[string]any{
+			"status": "already_running",
+			"pid":    gateway.cmd.Process.Pid,
+		})
+		return
+	}
+	if gateway.cmd != nil && gateway.cmd.Process != nil {
+		gateway.cmd = nil
+	}
+
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		http.Error(
+			w,
+			fmt.Sprintf("Failed to validate gateway start conditions: %v", err),
+			http.StatusInternalServerError,
+		)
+		return
+	}
+	if !ready {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		json.NewEncoder(w).Encode(map[string]any{
+			"status":  "precondition_failed",
+			"message": reason,
+		})
+		return
+	}
+
+	pid, err := h.startGatewayLocked()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status": "ok",
+		"pid":    pid,
+	})
+}
+
+// handleGatewayStop stops the running gateway subprocess gracefully.
+//
+//	POST /api/gateway/stop
+func (h *Handler) handleGatewayStop(w http.ResponseWriter, r *http.Request) {
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	if gateway.cmd == nil || gateway.cmd.Process == nil {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"status": "not_running",
+		})
+		return
+	}
+
+	pid := gateway.cmd.Process.Pid
+
+	// Send SIGTERM for graceful shutdown (SIGKILL on Windows)
+	var sigErr error
+	if runtime.GOOS == "windows" {
+		sigErr = gateway.cmd.Process.Kill()
+	} else {
+		sigErr = gateway.cmd.Process.Signal(syscall.SIGTERM)
+	}
+
+	if sigErr != nil {
+		http.Error(w, fmt.Sprintf("Failed to stop gateway (PID %d): %v", pid, sigErr), http.StatusInternalServerError)
+		return
+	}
+
+	log.Printf("Sent stop signal to gateway (PID: %d)", pid)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status": "ok",
+		"pid":    pid,
+	})
+}
+
+// handleGatewayRestart stops the gateway (if running) and starts a new instance.
+//
+//	POST /api/gateway/restart
+func (h *Handler) handleGatewayRestart(w http.ResponseWriter, r *http.Request) {
+	gateway.mu.Lock()
+
+	// Stop existing process if running
+	if gateway.cmd != nil && gateway.cmd.Process != nil {
+		if isCmdProcessAliveLocked(gateway.cmd) {
+			// Process is alive, send SIGTERM
+			if runtime.GOOS == "windows" {
+				gateway.cmd.Process.Kill()
+			} else {
+				gateway.cmd.Process.Signal(syscall.SIGTERM)
+			}
+
+			// Wait briefly for it to exit
+			gateway.mu.Unlock()
+			time.Sleep(2 * time.Second)
+			gateway.mu.Lock()
+		}
+		gateway.cmd = nil
+	}
+
+	gateway.mu.Unlock()
+
+	// Start fresh via the existing handler
+	h.handleGatewayStart(w, r)
+}
+
+// handleGatewayStatus returns the gateway run status, health info, and logs.
+//
+//	GET /api/gateway/status
+func (h *Handler) handleGatewayStatus(w http.ResponseWriter, r *http.Request) {
+	data := map[string]any{}
+
+	// Check process state
+	gateway.mu.Lock()
+	processAlive := isGatewayProcessAliveLocked()
+	if processAlive {
+		data["pid"] = gateway.cmd.Process.Pid
+	}
+	gateway.mu.Unlock()
+
+	if !processAlive {
+		data["gateway_status"] = "stopped"
+	} else {
+		// Process is alive — probe its health endpoint
+		cfg, err := config.LoadConfig(h.configPath)
+		host := "127.0.0.1"
+		port := 18790
+		if err == nil && cfg != nil {
+			if cfg.Gateway.Host != "" && cfg.Gateway.Host != "0.0.0.0" {
+				host = cfg.Gateway.Host
+			}
+			if cfg.Gateway.Port != 0 {
+				port = cfg.Gateway.Port
+			}
+		}
+
+		url := fmt.Sprintf("http://%s/health", net.JoinHostPort(host, strconv.Itoa(port)))
+		client := http.Client{Timeout: 2 * time.Second}
+		resp, err := client.Get(url)
+
+		if err != nil {
+			data["gateway_status"] = "starting"
+		} else {
+			defer resp.Body.Close()
+			if resp.StatusCode != http.StatusOK {
+				data["gateway_status"] = "error"
+				data["status_code"] = resp.StatusCode
+			} else {
+				var healthData map[string]any
+				if decErr := json.NewDecoder(resp.Body).Decode(&healthData); decErr != nil {
+					data["gateway_status"] = "error"
+				} else {
+					for k, v := range healthData {
+						data[k] = v
+					}
+					data["gateway_status"] = "running"
+				}
+			}
+		}
+	}
+
+	ready, reason, readyErr := h.gatewayStartReady()
+	if readyErr != nil {
+		data["gateway_start_allowed"] = false
+		data["gateway_start_reason"] = readyErr.Error()
+	} else {
+		data["gateway_start_allowed"] = ready
+		if !ready {
+			data["gateway_start_reason"] = reason
+		}
+	}
+
+	// Append incremental log data
+	appendGatewayLogs(r, data)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(data)
+}
+
+// appendGatewayLogs reads log_offset and log_run_id query params from the request
+// and populates the response data map with incremental log lines.
+func appendGatewayLogs(r *http.Request, data map[string]any) {
+	clientOffset := 0
+	clientRunID := -1
+
+	if v := r.URL.Query().Get("log_offset"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			clientOffset = n
+		}
+	}
+
+	if v := r.URL.Query().Get("log_run_id"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			clientRunID = n
+		}
+	}
+
+	runID := gateway.logs.RunID()
+
+	if runID == 0 {
+		data["logs"] = []string{}
+		data["log_total"] = 0
+		data["log_run_id"] = 0
+		return
+	}
+
+	// If runID changed, reset offset to get all logs from new run
+	offset := clientOffset
+	if clientRunID != runID {
+		offset = 0
+	}
+
+	lines, total, runID := gateway.logs.LinesSince(offset)
+	if lines == nil {
+		lines = []string{}
+	}
+
+	data["logs"] = lines
+	data["log_total"] = total
+	data["log_run_id"] = runID
+}
+
+// handleGatewayEvents serves an SSE stream of gateway state change events.
+//
+//	GET /api/gateway/events
+func (h *Handler) handleGatewayEvents(w http.ResponseWriter, r *http.Request) {
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		http.Error(w, "SSE not supported", http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Connection", "keep-alive")
+	w.Header().Set("Access-Control-Allow-Origin", "*")
+
+	// Subscribe to gateway events
+	ch := gateway.events.Subscribe()
+	defer gateway.events.Unsubscribe(ch)
+
+	// Send initial status so the client doesn't start blank
+	initial := h.currentGatewayStatus()
+	fmt.Fprintf(w, "data: %s\n\n", initial)
+	flusher.Flush()
+
+	for {
+		select {
+		case <-r.Context().Done():
+			return
+		case data, ok := <-ch:
+			if !ok {
+				return
+			}
+			fmt.Fprintf(w, "data: %s\n\n", data)
+			flusher.Flush()
+		}
+	}
+}
+
+// currentGatewayStatus returns the current gateway status as a JSON string.
+func (h *Handler) currentGatewayStatus() string {
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	data := map[string]any{
+		"gateway_status": "stopped",
+	}
+	if isGatewayProcessAliveLocked() {
+		data["gateway_status"] = "running"
+		data["pid"] = gateway.cmd.Process.Pid
+	}
+
+	ready, reason, readyErr := h.gatewayStartReady()
+	if readyErr != nil {
+		data["gateway_start_allowed"] = false
+		data["gateway_start_reason"] = readyErr.Error()
+	} else {
+		data["gateway_start_allowed"] = ready
+		if !ready {
+			data["gateway_start_reason"] = reason
+		}
+	}
+
+	encoded, _ := json.Marshal(data)
+	return string(encoded)
+}
+
+// findPicoclawBinary locates the picoclaw executable.
+// Tries the same directory as the current executable first, then falls back to $PATH.
+func findPicoclawBinary() string {
+	if exe, err := os.Executable(); err == nil {
+		dir := filepath.Dir(exe)
+		candidate := filepath.Join(dir, "picoclaw")
+		if runtime.GOOS == "windows" {
+			candidate += ".exe"
+		}
+		if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
+			return candidate
+		}
+	}
+	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)
+	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for scanner.Scan() {
+		buf.Append(scanner.Text())
+	}
+}

web/backend/api/gateway_test.go

@@ -0,0 +1,122 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestGatewayStartReady_NoDefaultModel(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	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")
+	}
+	if reason != "no default model configured" {
+		t.Fatalf("gatewayStartReady() reason = %q, want %q", reason, "no default model configured")
+	}
+}
+
+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 {
+		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")
+	}
+	if reason == "" {
+		t.Fatalf("gatewayStartReady() reason is empty")
+	}
+}
+
+func TestGatewayStartReady_ValidDefaultModel(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	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 {
+		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 (reason=%q)", reason)
+	}
+}
+
+func TestGatewayStartReady_DefaultModelWithoutCredential(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
+	cfg.ModelList[0].APIKey = ""
+	cfg.ModelList[0].AuthMethod = ""
+	if err := config.SaveConfig(configPath, cfg); 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")
+	}
+	if !strings.Contains(reason, "no credentials configured") {
+		t.Fatalf("gatewayStartReady() reason = %q, want contains %q", reason, "no credentials configured")
+	}
+}
+
+func TestGatewayStatusIncludesStartConditionWhenNotReady(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/gateway/status", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+
+	allowed, ok := body["gateway_start_allowed"].(bool)
+	if !ok {
+		t.Fatalf("gateway_start_allowed missing or not bool: %#v", body["gateway_start_allowed"])
+	}
+	if allowed {
+		t.Fatalf("gateway_start_allowed = true, want false")
+	}
+	if _, ok := body["gateway_start_reason"].(string); !ok {
+		t.Fatalf("gateway_start_reason missing or not string: %#v", body["gateway_start_reason"])
+	}
+}

web/backend/api/launcher_config.go

@@ -0,0 +1,85 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+)
+
+type launcherConfigPayload struct {
+	Port         int      `json:"port"`
+	Public       bool     `json:"public"`
+	AllowedCIDRs []string `json:"allowed_cidrs"`
+}
+
+func (h *Handler) registerLauncherConfigRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/system/launcher-config", h.handleGetLauncherConfig)
+	mux.HandleFunc("PUT /api/system/launcher-config", h.handleUpdateLauncherConfig)
+}
+
+func (h *Handler) launcherConfigPath() string {
+	return launcherconfig.PathForAppConfig(h.configPath)
+}
+
+func (h *Handler) launcherFallbackConfig() launcherconfig.Config {
+	port := h.serverPort
+	if port <= 0 {
+		port = launcherconfig.DefaultPort
+	}
+	return launcherconfig.Config{
+		Port:         port,
+		Public:       h.serverPublic,
+		AllowedCIDRs: append([]string(nil), h.serverCIDRs...),
+	}
+}
+
+func (h *Handler) loadLauncherConfig() (launcherconfig.Config, error) {
+	return launcherconfig.Load(h.launcherConfigPath(), h.launcherFallbackConfig())
+}
+
+func (h *Handler) handleGetLauncherConfig(w http.ResponseWriter, r *http.Request) {
+	cfg, err := h.loadLauncherConfig()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load launcher config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(launcherConfigPayload{
+		Port:         cfg.Port,
+		Public:       cfg.Public,
+		AllowedCIDRs: append([]string(nil), cfg.AllowedCIDRs...),
+	})
+}
+
+func (h *Handler) handleUpdateLauncherConfig(w http.ResponseWriter, r *http.Request) {
+	var payload launcherConfigPayload
+	if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	cfg := launcherconfig.Config{
+		Port:         payload.Port,
+		Public:       payload.Public,
+		AllowedCIDRs: append([]string(nil), payload.AllowedCIDRs...),
+	}
+	if err := launcherconfig.Validate(cfg); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	if err := launcherconfig.Save(h.launcherConfigPath(), cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save launcher config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(launcherConfigPayload{
+		Port:         cfg.Port,
+		Public:       cfg.Public,
+		AllowedCIDRs: append([]string(nil), cfg.AllowedCIDRs...),
+	})
+}

web/backend/api/launcher_config_test.go

@@ -0,0 +1,115 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+)
+
+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"})
+
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/system/launcher-config", 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 got launcherConfigPayload
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+	if got.Port != 19999 || !got.Public {
+		t.Fatalf("response = %+v, want port=19999 public=true", got)
+	}
+	if len(got.AllowedCIDRs) != 1 || got.AllowedCIDRs[0] != "192.168.1.0/24" {
+		t.Fatalf("response allowed_cidrs = %v, want [192.168.1.0/24]", got.AllowedCIDRs)
+	}
+}
+
+func TestPutLauncherConfigPersists(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPut,
+		"/api/system/launcher-config",
+		strings.NewReader(`{"port":18080,"public":true,"allowed_cidrs":["192.168.1.0/24"]}`),
+	)
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	path := launcherconfig.PathForAppConfig(configPath)
+	cfg, err := launcherconfig.Load(path, launcherconfig.Default())
+	if err != nil {
+		t.Fatalf("launcherconfig.Load() error = %v", err)
+	}
+	if cfg.Port != 18080 || !cfg.Public {
+		t.Fatalf("saved config = %+v, want port=18080 public=true", cfg)
+	}
+	if len(cfg.AllowedCIDRs) != 1 || cfg.AllowedCIDRs[0] != "192.168.1.0/24" {
+		t.Fatalf("saved config allowed_cidrs = %v, want [192.168.1.0/24]", cfg.AllowedCIDRs)
+	}
+}
+
+func TestPutLauncherConfigRejectsInvalidPort(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPut,
+		"/api/system/launcher-config",
+		strings.NewReader(`{"port":70000,"public":false}`),
+	)
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusBadRequest, rec.Body.String())
+	}
+}
+
+func TestPutLauncherConfigRejectsInvalidCIDR(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPut,
+		"/api/system/launcher-config",
+		strings.NewReader(`{"port":18080,"public":false,"allowed_cidrs":["bad-cidr"]}`),
+	)
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusBadRequest, rec.Body.String())
+	}
+}

web/backend/api/log.go

@@ -1,4 +1,4 @@
-package server
+package api
 
 import "sync"
 
@@ -89,11 +89,3 @@ func (b *LogBuffer) RunID() int {
 
 	return b.runID
 }
-
-// Total returns the total number of lines appended in the current run.
-func (b *LogBuffer) Total() int {
-	b.mu.RLock()
-	defer b.mu.RUnlock()
-
-	return b.total
-}

web/backend/api/models.go

@@ -0,0 +1,298 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// registerModelRoutes binds model list management endpoints to the ServeMux.
+func (h *Handler) registerModelRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/models", h.handleListModels)
+	mux.HandleFunc("POST /api/models", h.handleAddModel)
+	mux.HandleFunc("POST /api/models/default", h.handleSetDefaultModel)
+	mux.HandleFunc("PUT /api/models/{index}", h.handleUpdateModel)
+	mux.HandleFunc("DELETE /api/models/{index}", h.handleDeleteModel)
+}
+
+// modelResponse is the JSON structure returned for each model in the list.
+// All ModelConfig fields are included so the frontend can display and edit them.
+type modelResponse struct {
+	Index      int    `json:"index"`
+	ModelName  string `json:"model_name"`
+	Model      string `json:"model"`
+	APIBase    string `json:"api_base,omitempty"`
+	APIKey     string `json:"api_key"`
+	Proxy      string `json:"proxy,omitempty"`
+	AuthMethod string `json:"auth_method,omitempty"`
+	// Advanced fields
+	ConnectMode    string `json:"connect_mode,omitempty"`
+	Workspace      string `json:"workspace,omitempty"`
+	RPM            int    `json:"rpm,omitempty"`
+	MaxTokensField string `json:"max_tokens_field,omitempty"`
+	RequestTimeout int    `json:"request_timeout,omitempty"`
+	ThinkingLevel  string `json:"thinking_level,omitempty"`
+	// Meta
+	Configured bool `json:"configured"`
+	IsDefault  bool `json:"is_default"`
+}
+
+// handleListModels returns all model_list entries with masked API keys.
+//
+//	GET /api/models
+func (h *Handler) handleListModels(w http.ResponseWriter, r *http.Request) {
+	cfg, err := h.loadFilteredConfig()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	defaultModel := cfg.Agents.Defaults.GetModelName()
+
+	models := make([]modelResponse, 0, len(cfg.ModelList))
+	for i, m := range cfg.ModelList {
+		models = append(models, modelResponse{
+			Index:          i,
+			ModelName:      m.ModelName,
+			Model:          m.Model,
+			APIBase:        m.APIBase,
+			APIKey:         maskAPIKey(m.APIKey),
+			Proxy:          m.Proxy,
+			AuthMethod:     m.AuthMethod,
+			ConnectMode:    m.ConnectMode,
+			Workspace:      m.Workspace,
+			RPM:            m.RPM,
+			MaxTokensField: m.MaxTokensField,
+			RequestTimeout: m.RequestTimeout,
+			ThinkingLevel:  m.ThinkingLevel,
+			Configured:     m.APIKey != "" || m.AuthMethod != "",
+			IsDefault:      m.ModelName == defaultModel,
+		})
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"models":        models,
+		"total":         len(models),
+		"default_model": defaultModel,
+	})
+}
+
+// handleAddModel appends a new model configuration entry.
+//
+//	POST /api/models
+func (h *Handler) handleAddModel(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	var mc config.ModelConfig
+	if err = json.Unmarshal(body, &mc); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if err = mc.Validate(); err != nil {
+		http.Error(w, fmt.Sprintf("Validation error: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	cfg.ModelList = append(cfg.ModelList, mc)
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status": "ok",
+		"index":  len(cfg.ModelList) - 1,
+	})
+}
+
+// handleUpdateModel replaces a model configuration entry at the given index.
+// If the request body omits api_key (or sends an empty string), the existing
+// stored key is preserved so callers can update only api_base / proxy without
+// exposing or clearing the secret.
+//
+//	PUT /api/models/{index}
+func (h *Handler) handleUpdateModel(w http.ResponseWriter, r *http.Request) {
+	idx, err := strconv.Atoi(r.PathValue("index"))
+	if err != nil {
+		http.Error(w, "Invalid index", http.StatusBadRequest)
+		return
+	}
+
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	var mc config.ModelConfig
+	if err = json.Unmarshal(body, &mc); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if err = mc.Validate(); err != nil {
+		http.Error(w, fmt.Sprintf("Validation error: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	if idx < 0 || idx >= len(cfg.ModelList) {
+		http.Error(w, fmt.Sprintf("Index %d out of range (0-%d)", idx, len(cfg.ModelList)-1), http.StatusNotFound)
+		return
+	}
+
+	// Preserve the existing API key when the caller omits it (empty string).
+	// This lets the UI update api_base / proxy without clearing the stored secret.
+	if mc.APIKey == "" {
+		mc.APIKey = cfg.ModelList[idx].APIKey
+	}
+
+	cfg.ModelList[idx] = mc
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+}
+
+// handleDeleteModel removes a model configuration entry at the given index.
+//
+//	DELETE /api/models/{index}
+func (h *Handler) handleDeleteModel(w http.ResponseWriter, r *http.Request) {
+	idx, err := strconv.Atoi(r.PathValue("index"))
+	if err != nil {
+		http.Error(w, "Invalid index", http.StatusBadRequest)
+		return
+	}
+
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	if idx < 0 || idx >= len(cfg.ModelList) {
+		http.Error(w, fmt.Sprintf("Index %d out of range (0-%d)", idx, len(cfg.ModelList)-1), http.StatusNotFound)
+		return
+	}
+
+	deletedModelName := cfg.ModelList[idx].ModelName
+
+	cfg.ModelList = append(cfg.ModelList[:idx], cfg.ModelList[idx+1:]...)
+
+	// If the deleted model was the default, clear it.
+	if cfg.Agents.Defaults.ModelName == deletedModelName {
+		cfg.Agents.Defaults.ModelName = ""
+	}
+	if cfg.Agents.Defaults.Model == deletedModelName {
+		cfg.Agents.Defaults.Model = ""
+	}
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+}
+
+// handleSetDefaultModel sets the default model for all agents.
+//
+//	POST /api/models/default
+func (h *Handler) handleSetDefaultModel(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	var req struct {
+		ModelName string `json:"model_name"`
+	}
+	if err = json.Unmarshal(body, &req); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if req.ModelName == "" {
+		http.Error(w, "model_name is required", http.StatusBadRequest)
+		return
+	}
+
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	// Verify the model_name exists in model_list
+	found := false
+	for _, m := range cfg.ModelList {
+		if m.ModelName == req.ModelName {
+			found = true
+			break
+		}
+	}
+	if !found {
+		http.Error(w, fmt.Sprintf("Model %q not found in model_list", req.ModelName), http.StatusNotFound)
+		return
+	}
+
+	cfg.Agents.Defaults.ModelName = req.ModelName
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{
+		"status":        "ok",
+		"default_model": req.ModelName,
+	})
+}
+
+// maskAPIKey returns a masked version of an API key for safe display.
+// Keys longer than 8 chars show prefix + last 4 chars: "sk-****abcd"
+// Shorter keys are fully masked as "****".
+// Empty keys return empty string.
+func maskAPIKey(key string) string {
+	if key == "" {
+		return ""
+	}
+	if len(key) <= 8 {
+		return "****"
+	}
+	// Show first 3 chars and last 4 chars
+	return key[:3] + "****" + key[len(key)-4:]
+}

web/backend/api/oauth.go

@@ -0,0 +1,844 @@
+package api
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"html"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+const (
+	oauthProviderOpenAI            = "openai"
+	oauthProviderAnthropic         = "anthropic"
+	oauthProviderGoogleAntigravity = "google-antigravity"
+
+	oauthMethodBrowser    = "browser"
+	oauthMethodDeviceCode = "device_code"
+	oauthMethodToken      = "token"
+
+	oauthFlowPending = "pending"
+	oauthFlowSuccess = "success"
+	oauthFlowError   = "error"
+	oauthFlowExpired = "expired"
+)
+
+const (
+	oauthBrowserFlowTTL    = 10 * time.Minute
+	oauthDeviceCodeFlowTTL = 15 * time.Minute
+	oauthTerminalFlowGC    = 30 * time.Minute
+)
+
+var oauthProviderOrder = []string{
+	oauthProviderOpenAI,
+	oauthProviderAnthropic,
+	oauthProviderGoogleAntigravity,
+}
+
+var oauthProviderMethods = map[string][]string{
+	oauthProviderOpenAI:            {oauthMethodBrowser, oauthMethodDeviceCode, oauthMethodToken},
+	oauthProviderAnthropic:         {oauthMethodToken},
+	oauthProviderGoogleAntigravity: {oauthMethodBrowser},
+}
+
+var oauthProviderLabels = map[string]string{
+	oauthProviderOpenAI:            "OpenAI",
+	oauthProviderAnthropic:         "Anthropic",
+	oauthProviderGoogleAntigravity: "Google Antigravity",
+}
+
+var (
+	oauthNow                      = time.Now
+	oauthGeneratePKCE             = auth.GeneratePKCE
+	oauthGenerateState            = auth.GenerateState
+	oauthBuildAuthorizeURL        = auth.BuildAuthorizeURL
+	oauthRequestDeviceCode        = auth.RequestDeviceCode
+	oauthPollDeviceCodeOnce       = auth.PollDeviceCodeOnce
+	oauthExchangeCodeForTokens    = auth.ExchangeCodeForTokens
+	oauthGetCredential            = auth.GetCredential
+	oauthSetCredential            = auth.SetCredential
+	oauthDeleteCredential         = auth.DeleteCredential
+	oauthLoadConfig               = config.LoadConfig
+	oauthSaveConfig               = config.SaveConfig
+	oauthFetchAntigravityProject  = providers.FetchAntigravityProjectID
+	oauthFetchGoogleUserEmailFunc = fetchGoogleUserEmail
+)
+
+type oauthFlow struct {
+	ID           string
+	Provider     string
+	Method       string
+	Status       string
+	CreatedAt    time.Time
+	UpdatedAt    time.Time
+	ExpiresAt    time.Time
+	Error        string
+	CodeVerifier string
+	OAuthState   string
+	RedirectURI  string
+	DeviceAuthID string
+	UserCode     string
+	VerifyURL    string
+	Interval     int
+}
+
+type oauthProviderStatus struct {
+	Provider    string   `json:"provider"`
+	DisplayName string   `json:"display_name"`
+	Methods     []string `json:"methods"`
+	LoggedIn    bool     `json:"logged_in"`
+	Status      string   `json:"status"`
+	AuthMethod  string   `json:"auth_method,omitempty"`
+	ExpiresAt   string   `json:"expires_at,omitempty"`
+	AccountID   string   `json:"account_id,omitempty"`
+	Email       string   `json:"email,omitempty"`
+	ProjectID   string   `json:"project_id,omitempty"`
+}
+
+type oauthFlowResponse struct {
+	FlowID    string `json:"flow_id"`
+	Provider  string `json:"provider"`
+	Method    string `json:"method"`
+	Status    string `json:"status"`
+	ExpiresAt string `json:"expires_at,omitempty"`
+	Error     string `json:"error,omitempty"`
+	UserCode  string `json:"user_code,omitempty"`
+	VerifyURL string `json:"verify_url,omitempty"`
+	Interval  int    `json:"interval,omitempty"`
+}
+
+// registerOAuthRoutes binds OAuth login/logout endpoints to the ServeMux.
+func (h *Handler) registerOAuthRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/oauth/providers", h.handleListOAuthProviders)
+	mux.HandleFunc("POST /api/oauth/login", h.handleOAuthLogin)
+	mux.HandleFunc("GET /api/oauth/flows/{id}", h.handleGetOAuthFlow)
+	mux.HandleFunc("POST /api/oauth/flows/{id}/poll", h.handlePollOAuthFlow)
+	mux.HandleFunc("POST /api/oauth/logout", h.handleOAuthLogout)
+	mux.HandleFunc("GET /oauth/callback", h.handleOAuthCallback)
+}
+
+func (h *Handler) handleListOAuthProviders(w http.ResponseWriter, r *http.Request) {
+	providersResp := make([]oauthProviderStatus, 0, len(oauthProviderOrder))
+
+	for _, provider := range oauthProviderOrder {
+		cred, err := oauthGetCredential(provider)
+		if err != nil {
+			http.Error(w, fmt.Sprintf("failed to load credentials: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		item := oauthProviderStatus{
+			Provider:    provider,
+			DisplayName: oauthProviderLabels[provider],
+			Methods:     oauthProviderMethods[provider],
+			Status:      "not_logged_in",
+		}
+		if cred != nil {
+			item.LoggedIn = true
+			item.AuthMethod = cred.AuthMethod
+			item.AccountID = cred.AccountID
+			item.Email = cred.Email
+			item.ProjectID = cred.ProjectID
+			if !cred.ExpiresAt.IsZero() {
+				item.ExpiresAt = cred.ExpiresAt.Format(time.RFC3339)
+			}
+			switch {
+			case cred.IsExpired():
+				item.Status = "expired"
+			case cred.NeedsRefresh():
+				item.Status = "needs_refresh"
+			default:
+				item.Status = "connected"
+			}
+		}
+
+		providersResp = append(providersResp, item)
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"providers": providersResp,
+	})
+}
+
+func (h *Handler) handleOAuthLogin(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	var req struct {
+		Provider string `json:"provider"`
+		Method   string `json:"method"`
+		Token    string `json:"token"`
+	}
+	if err = json.Unmarshal(body, &req); err != nil {
+		http.Error(w, fmt.Sprintf("invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	provider, err := normalizeOAuthProvider(req.Provider)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	method := strings.ToLower(strings.TrimSpace(req.Method))
+	if !isOAuthMethodSupported(provider, method) {
+		http.Error(
+			w,
+			fmt.Sprintf("unsupported login method %q for provider %q", method, provider),
+			http.StatusBadRequest,
+		)
+		return
+	}
+
+	switch method {
+	case oauthMethodToken:
+		token := strings.TrimSpace(req.Token)
+		if token == "" {
+			http.Error(w, "token is required", http.StatusBadRequest)
+			return
+		}
+
+		cred := &auth.AuthCredential{
+			AccessToken: token,
+			Provider:    provider,
+			AuthMethod:  oauthMethodToken,
+		}
+		if err := h.persistCredentialAndConfig(provider, oauthMethodToken, cred); err != nil {
+			http.Error(w, fmt.Sprintf("token login failed: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"status":   "ok",
+			"provider": provider,
+			"method":   method,
+		})
+		return
+
+	case oauthMethodDeviceCode:
+		cfg := auth.OpenAIOAuthConfig()
+		info, err := oauthRequestDeviceCode(cfg)
+		if err != nil {
+			http.Error(w, fmt.Sprintf("failed to request device code: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		now := oauthNow()
+		flow := &oauthFlow{
+			ID:           newOAuthFlowID(),
+			Provider:     provider,
+			Method:       method,
+			Status:       oauthFlowPending,
+			CreatedAt:    now,
+			UpdatedAt:    now,
+			ExpiresAt:    now.Add(oauthDeviceCodeFlowTTL),
+			DeviceAuthID: info.DeviceAuthID,
+			UserCode:     info.UserCode,
+			VerifyURL:    info.VerifyURL,
+			Interval:     info.Interval,
+		}
+		h.storeOAuthFlow(flow)
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"status":     "ok",
+			"provider":   provider,
+			"method":     method,
+			"flow_id":    flow.ID,
+			"user_code":  flow.UserCode,
+			"verify_url": flow.VerifyURL,
+			"interval":   flow.Interval,
+			"expires_at": flow.ExpiresAt.Format(time.RFC3339),
+		})
+		return
+
+	case oauthMethodBrowser:
+		cfg, err := oauthConfigForProvider(provider)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+
+		pkce, err := oauthGeneratePKCE()
+		if err != nil {
+			http.Error(w, fmt.Sprintf("failed to generate PKCE: %v", err), http.StatusInternalServerError)
+			return
+		}
+		state, err := oauthGenerateState()
+		if err != nil {
+			http.Error(w, fmt.Sprintf("failed to generate state: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		redirectURI := buildOAuthRedirectURI(r)
+		authURL := oauthBuildAuthorizeURL(cfg, pkce, state, redirectURI)
+
+		now := oauthNow()
+		flow := &oauthFlow{
+			ID:           newOAuthFlowID(),
+			Provider:     provider,
+			Method:       method,
+			Status:       oauthFlowPending,
+			CreatedAt:    now,
+			UpdatedAt:    now,
+			ExpiresAt:    now.Add(oauthBrowserFlowTTL),
+			CodeVerifier: pkce.CodeVerifier,
+			OAuthState:   state,
+			RedirectURI:  redirectURI,
+		}
+		h.storeOAuthFlow(flow)
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"status":     "ok",
+			"provider":   provider,
+			"method":     method,
+			"flow_id":    flow.ID,
+			"auth_url":   authURL,
+			"expires_at": flow.ExpiresAt.Format(time.RFC3339),
+		})
+		return
+	default:
+		http.Error(w, "unsupported login method", http.StatusBadRequest)
+	}
+}
+
+func (h *Handler) handleGetOAuthFlow(w http.ResponseWriter, r *http.Request) {
+	flowID := strings.TrimSpace(r.PathValue("id"))
+	if flowID == "" {
+		http.Error(w, "missing flow id", http.StatusBadRequest)
+		return
+	}
+
+	flow, ok := h.getOAuthFlow(flowID)
+	if !ok {
+		http.Error(w, "flow not found", http.StatusNotFound)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(flowToResponse(flow))
+}
+
+func (h *Handler) handlePollOAuthFlow(w http.ResponseWriter, r *http.Request) {
+	flowID := strings.TrimSpace(r.PathValue("id"))
+	if flowID == "" {
+		http.Error(w, "missing flow id", http.StatusBadRequest)
+		return
+	}
+
+	flow, ok := h.getOAuthFlow(flowID)
+	if !ok {
+		http.Error(w, "flow not found", http.StatusNotFound)
+		return
+	}
+
+	if flow.Method != oauthMethodDeviceCode {
+		http.Error(w, "flow does not support polling", http.StatusBadRequest)
+		return
+	}
+	if flow.Status != oauthFlowPending {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(flowToResponse(flow))
+		return
+	}
+
+	cfg := auth.OpenAIOAuthConfig()
+	cred, err := oauthPollDeviceCodeOnce(cfg, flow.DeviceAuthID, flow.UserCode)
+	if err != nil {
+		if strings.Contains(strings.ToLower(err.Error()), "pending") {
+			updated, _ := h.getOAuthFlow(flowID)
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(flowToResponse(updated))
+			return
+		}
+		h.setOAuthFlowError(flowID, fmt.Sprintf("device code poll failed: %v", err))
+		updated, _ := h.getOAuthFlow(flowID)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(flowToResponse(updated))
+		return
+	}
+	if cred == nil {
+		updated, _ := h.getOAuthFlow(flowID)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(flowToResponse(updated))
+		return
+	}
+
+	if err := h.persistCredentialAndConfig(flow.Provider, oauthMethodTokenOrOAuth(flow.Method), cred); err != nil {
+		h.setOAuthFlowError(flowID, fmt.Sprintf("failed to save credential: %v", err))
+		updated, _ := h.getOAuthFlow(flowID)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(flowToResponse(updated))
+		return
+	}
+
+	h.setOAuthFlowSuccess(flowID)
+	updated, _ := h.getOAuthFlow(flowID)
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(flowToResponse(updated))
+}
+
+func (h *Handler) handleOAuthCallback(w http.ResponseWriter, r *http.Request) {
+	state := strings.TrimSpace(r.URL.Query().Get("state"))
+	if state == "" {
+		renderOAuthCallbackPage(w, "", oauthFlowError, "Missing state", "missing_state")
+		return
+	}
+
+	flow, ok := h.getOAuthFlowByState(state)
+	if !ok {
+		renderOAuthCallbackPage(w, "", oauthFlowError, "OAuth flow not found", "flow_not_found")
+		return
+	}
+
+	if flow.Status != oauthFlowPending {
+		renderOAuthCallbackPage(w, flow.ID, flow.Status, "Flow already completed", flow.Error)
+		return
+	}
+
+	if errMsg := strings.TrimSpace(r.URL.Query().Get("error")); errMsg != "" {
+		if desc := strings.TrimSpace(r.URL.Query().Get("error_description")); desc != "" {
+			errMsg += ": " + desc
+		}
+		h.setOAuthFlowError(flow.ID, errMsg)
+		renderOAuthCallbackPage(w, flow.ID, oauthFlowError, "Authorization failed", errMsg)
+		return
+	}
+
+	code := strings.TrimSpace(r.URL.Query().Get("code"))
+	if code == "" {
+		h.setOAuthFlowError(flow.ID, "missing authorization code")
+		renderOAuthCallbackPage(w, flow.ID, oauthFlowError, "Missing authorization code", "missing_code")
+		return
+	}
+
+	cfg, err := oauthConfigForProvider(flow.Provider)
+	if err != nil {
+		h.setOAuthFlowError(flow.ID, err.Error())
+		renderOAuthCallbackPage(w, flow.ID, oauthFlowError, "Unsupported provider", err.Error())
+		return
+	}
+
+	cred, err := oauthExchangeCodeForTokens(cfg, code, flow.CodeVerifier, flow.RedirectURI)
+	if err != nil {
+		h.setOAuthFlowError(flow.ID, fmt.Sprintf("token exchange failed: %v", err))
+		renderOAuthCallbackPage(w, flow.ID, oauthFlowError, "Token exchange failed", err.Error())
+		return
+	}
+
+	if err := h.persistCredentialAndConfig(flow.Provider, oauthMethodTokenOrOAuth(flow.Method), cred); err != nil {
+		h.setOAuthFlowError(flow.ID, fmt.Sprintf("failed to save credential: %v", err))
+		renderOAuthCallbackPage(w, flow.ID, oauthFlowError, "Failed to save credential", err.Error())
+		return
+	}
+
+	h.setOAuthFlowSuccess(flow.ID)
+	renderOAuthCallbackPage(w, flow.ID, oauthFlowSuccess, "Authentication successful", "")
+}
+
+func (h *Handler) handleOAuthLogout(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	var req struct {
+		Provider string `json:"provider"`
+	}
+	if err = json.Unmarshal(body, &req); err != nil {
+		http.Error(w, fmt.Sprintf("invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	provider, err := normalizeOAuthProvider(req.Provider)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	if err := oauthDeleteCredential(provider); err != nil {
+		http.Error(w, fmt.Sprintf("failed to delete credential: %v", err), http.StatusInternalServerError)
+		return
+	}
+	if err := h.syncProviderAuthMethod(provider, ""); err != nil {
+		http.Error(w, fmt.Sprintf("failed to update config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"status":   "ok",
+		"provider": provider,
+	})
+}
+
+func renderOAuthCallbackPage(w http.ResponseWriter, flowID, status, title, errMsg string) {
+	payload := map[string]string{
+		"type":   "picoclaw-oauth-result",
+		"flowId": flowID,
+		"status": status,
+	}
+	if errMsg != "" {
+		payload["error"] = errMsg
+	}
+	payloadJSON, _ := json.Marshal(payload)
+
+	message := title
+	if errMsg != "" {
+		message = fmt.Sprintf("%s: %s", title, errMsg)
+	}
+
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	if status == oauthFlowSuccess {
+		w.WriteHeader(http.StatusOK)
+	} else {
+		w.WriteHeader(http.StatusBadRequest)
+	}
+
+	_, _ = fmt.Fprintf(
+		w,
+		"<!doctype html><html><head><meta charset=\"utf-8\"><title>PicoClaw OAuth</title></head><body><script>(function(){var payload=%s;var hasOpener=false;try{if(window.opener&&!window.opener.closed){window.opener.postMessage(payload,window.location.origin);hasOpener=true}}catch(e){}var target='/credentials?oauth_flow_id='+encodeURIComponent(payload.flowId||'')+'&oauth_status='+encodeURIComponent(payload.status||'');setTimeout(function(){if(hasOpener){window.close();return}window.location.replace(target)},800)})();</script><div style=\"font-family:Inter,system-ui,sans-serif;padding:24px\"><h2>%s</h2><p>%s</p><p>You can close this window.</p></div></body></html>",
+		string(payloadJSON),
+		html.EscapeString(title),
+		html.EscapeString(message),
+	)
+}
+
+func normalizeOAuthProvider(raw string) (string, error) {
+	provider := strings.ToLower(strings.TrimSpace(raw))
+	switch provider {
+	case "antigravity":
+		return oauthProviderGoogleAntigravity, nil
+	case oauthProviderOpenAI, oauthProviderAnthropic, oauthProviderGoogleAntigravity:
+		return provider, nil
+	default:
+		return "", fmt.Errorf("unsupported provider %q", raw)
+	}
+}
+
+func isOAuthMethodSupported(provider, method string) bool {
+	methods := oauthProviderMethods[provider]
+	for _, m := range methods {
+		if m == method {
+			return true
+		}
+	}
+	return false
+}
+
+func oauthConfigForProvider(provider string) (auth.OAuthProviderConfig, error) {
+	switch provider {
+	case oauthProviderOpenAI:
+		return auth.OpenAIOAuthConfig(), nil
+	case oauthProviderGoogleAntigravity:
+		return auth.GoogleAntigravityOAuthConfig(), nil
+	default:
+		return auth.OAuthProviderConfig{}, fmt.Errorf("provider %q does not support browser oauth", provider)
+	}
+}
+
+func oauthMethodTokenOrOAuth(method string) string {
+	if method == oauthMethodToken {
+		return oauthMethodToken
+	}
+	return "oauth"
+}
+
+func buildOAuthRedirectURI(r *http.Request) string {
+	scheme := "http"
+	if r.TLS != nil {
+		scheme = "https"
+	}
+	if forwarded := strings.TrimSpace(r.Header.Get("X-Forwarded-Proto")); forwarded != "" {
+		scheme = strings.Split(forwarded, ",")[0]
+	}
+	return fmt.Sprintf("%s://%s/oauth/callback", scheme, r.Host)
+}
+
+func flowToResponse(flow *oauthFlow) oauthFlowResponse {
+	resp := oauthFlowResponse{
+		FlowID:   flow.ID,
+		Provider: flow.Provider,
+		Method:   flow.Method,
+		Status:   flow.Status,
+		Error:    flow.Error,
+	}
+	if !flow.ExpiresAt.IsZero() {
+		resp.ExpiresAt = flow.ExpiresAt.Format(time.RFC3339)
+	}
+	if flow.Method == oauthMethodDeviceCode {
+		resp.UserCode = flow.UserCode
+		resp.VerifyURL = flow.VerifyURL
+		resp.Interval = flow.Interval
+	}
+	return resp
+}
+
+func newOAuthFlowID() string {
+	buf := make([]byte, 16)
+	if _, err := rand.Read(buf); err != nil {
+		return fmt.Sprintf("oauth_%d", time.Now().UnixNano())
+	}
+	return hex.EncodeToString(buf)
+}
+
+func (h *Handler) storeOAuthFlow(flow *oauthFlow) {
+	now := oauthNow()
+	h.oauthMu.Lock()
+	defer h.oauthMu.Unlock()
+
+	h.gcOAuthFlowsLocked(now)
+	h.oauthFlows[flow.ID] = flow
+	if flow.OAuthState != "" {
+		h.oauthState[flow.OAuthState] = flow.ID
+	}
+}
+
+func (h *Handler) getOAuthFlow(flowID string) (*oauthFlow, bool) {
+	now := oauthNow()
+	h.oauthMu.Lock()
+	defer h.oauthMu.Unlock()
+
+	h.gcOAuthFlowsLocked(now)
+	flow, ok := h.oauthFlows[flowID]
+	if !ok {
+		return nil, false
+	}
+	cp := *flow
+	return &cp, true
+}
+
+func (h *Handler) getOAuthFlowByState(state string) (*oauthFlow, bool) {
+	now := oauthNow()
+	h.oauthMu.Lock()
+	defer h.oauthMu.Unlock()
+
+	h.gcOAuthFlowsLocked(now)
+	flowID, ok := h.oauthState[state]
+	if !ok {
+		return nil, false
+	}
+	flow, ok := h.oauthFlows[flowID]
+	if !ok {
+		delete(h.oauthState, state)
+		return nil, false
+	}
+	cp := *flow
+	return &cp, true
+}
+
+func (h *Handler) setOAuthFlowSuccess(flowID string) {
+	now := oauthNow()
+	h.oauthMu.Lock()
+	defer h.oauthMu.Unlock()
+
+	flow, ok := h.oauthFlows[flowID]
+	if !ok {
+		return
+	}
+	flow.Status = oauthFlowSuccess
+	flow.Error = ""
+	flow.UpdatedAt = now
+	if flow.OAuthState != "" {
+		delete(h.oauthState, flow.OAuthState)
+	}
+}
+
+func (h *Handler) setOAuthFlowError(flowID, errMsg string) {
+	now := oauthNow()
+	h.oauthMu.Lock()
+	defer h.oauthMu.Unlock()
+
+	flow, ok := h.oauthFlows[flowID]
+	if !ok {
+		return
+	}
+	flow.Status = oauthFlowError
+	flow.Error = errMsg
+	flow.UpdatedAt = now
+	if flow.OAuthState != "" {
+		delete(h.oauthState, flow.OAuthState)
+	}
+}
+
+func (h *Handler) gcOAuthFlowsLocked(now time.Time) {
+	for id, flow := range h.oauthFlows {
+		if flow.Status == oauthFlowPending && !flow.ExpiresAt.IsZero() && now.After(flow.ExpiresAt) {
+			flow.Status = oauthFlowExpired
+			flow.Error = "flow expired"
+			flow.UpdatedAt = now
+			if flow.OAuthState != "" {
+				delete(h.oauthState, flow.OAuthState)
+			}
+		}
+
+		if flow.Status != oauthFlowPending && now.Sub(flow.UpdatedAt) > oauthTerminalFlowGC {
+			if flow.OAuthState != "" {
+				delete(h.oauthState, flow.OAuthState)
+			}
+			delete(h.oauthFlows, id)
+		}
+	}
+}
+
+func (h *Handler) persistCredentialAndConfig(provider, authMethod string, cred *auth.AuthCredential) error {
+	if cred == nil {
+		return fmt.Errorf("empty credential")
+	}
+
+	cp := *cred
+	cp.Provider = provider
+	if cp.AuthMethod == "" {
+		cp.AuthMethod = authMethod
+	}
+
+	if provider == oauthProviderGoogleAntigravity {
+		if cp.Email == "" {
+			email, err := oauthFetchGoogleUserEmailFunc(cp.AccessToken)
+			if err != nil {
+				log.Printf("oauth warning: could not fetch google email: %v", err)
+			} else {
+				cp.Email = email
+			}
+		}
+		if cp.ProjectID == "" {
+			projectID, err := oauthFetchAntigravityProject(cp.AccessToken)
+			if err != nil {
+				log.Printf("oauth warning: could not fetch antigravity project id: %v", err)
+			} else {
+				cp.ProjectID = projectID
+			}
+		}
+	}
+
+	if err := oauthSetCredential(provider, &cp); err != nil {
+		return fmt.Errorf("saving credential: %w", err)
+	}
+	if err := h.syncProviderAuthMethod(provider, authMethod); err != nil {
+		return fmt.Errorf("syncing provider auth config: %w", err)
+	}
+	return nil
+}
+
+func (h *Handler) syncProviderAuthMethod(provider, authMethod string) error {
+	cfg, err := oauthLoadConfig(h.configPath)
+	if err != nil {
+		return err
+	}
+
+	switch provider {
+	case oauthProviderOpenAI:
+		cfg.Providers.OpenAI.AuthMethod = authMethod
+	case oauthProviderAnthropic:
+		cfg.Providers.Anthropic.AuthMethod = authMethod
+	case oauthProviderGoogleAntigravity:
+		cfg.Providers.Antigravity.AuthMethod = authMethod
+	default:
+		return fmt.Errorf("unsupported provider %q", provider)
+	}
+
+	found := false
+	for i := range cfg.ModelList {
+		if modelBelongsToProvider(provider, cfg.ModelList[i].Model) {
+			cfg.ModelList[i].AuthMethod = authMethod
+			found = true
+		}
+	}
+
+	if !found && authMethod != "" {
+		cfg.ModelList = append(cfg.ModelList, defaultModelConfigForProvider(provider, authMethod))
+	}
+
+	return oauthSaveConfig(h.configPath, cfg)
+}
+
+func modelBelongsToProvider(provider, model string) bool {
+	lower := strings.ToLower(strings.TrimSpace(model))
+	switch provider {
+	case oauthProviderOpenAI:
+		return lower == "openai" || strings.HasPrefix(lower, "openai/")
+	case oauthProviderAnthropic:
+		return lower == "anthropic" || strings.HasPrefix(lower, "anthropic/")
+	case oauthProviderGoogleAntigravity:
+		return lower == "antigravity" ||
+			lower == "google-antigravity" ||
+			strings.HasPrefix(lower, "antigravity/") ||
+			strings.HasPrefix(lower, "google-antigravity/")
+	default:
+		return false
+	}
+}
+
+func defaultModelConfigForProvider(provider, authMethod string) config.ModelConfig {
+	switch provider {
+	case oauthProviderOpenAI:
+		return config.ModelConfig{
+			ModelName:  "gpt-5.2",
+			Model:      "openai/gpt-5.2",
+			AuthMethod: authMethod,
+		}
+	case oauthProviderAnthropic:
+		return config.ModelConfig{
+			ModelName:  "claude-sonnet-4.6",
+			Model:      "anthropic/claude-sonnet-4.6",
+			AuthMethod: authMethod,
+		}
+	case oauthProviderGoogleAntigravity:
+		return config.ModelConfig{
+			ModelName:  "gemini-flash",
+			Model:      "antigravity/gemini-3-flash",
+			AuthMethod: authMethod,
+		}
+	default:
+		return config.ModelConfig{}
+	}
+}
+
+func fetchGoogleUserEmail(accessToken string) (string, error) {
+	req, err := http.NewRequest(http.MethodGet, "https://www.googleapis.com/oauth2/v2/userinfo", nil)
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	body, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("userinfo request failed: %s", string(body))
+	}
+
+	var userInfo struct {
+		Email string `json:"email"`
+	}
+	if err := json.Unmarshal(body, &userInfo); err != nil {
+		return "", err
+	}
+	if userInfo.Email == "" {
+		return "", fmt.Errorf("empty email in userinfo response")
+	}
+	return userInfo.Email, nil
+}

web/backend/api/oauth_test.go

@@ -0,0 +1,293 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestOAuthLoginRejectsUnsupportedMethod(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPost,
+		"/api/oauth/login",
+		strings.NewReader(`{"provider":"anthropic","method":"browser"}`),
+	)
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusBadRequest, rec.Body.String())
+	}
+}
+
+func TestOAuthBrowserFlowCreatedAndQueried(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+
+	oauthGeneratePKCE = func() (auth.PKCECodes, error) {
+		return auth.PKCECodes{CodeVerifier: "verifier-1", CodeChallenge: "challenge-1"}, nil
+	}
+	oauthGenerateState = func() (string, error) { return "state-1", nil }
+	oauthBuildAuthorizeURL = func(cfg auth.OAuthProviderConfig, pkce auth.PKCECodes, state, redirectURI string) string {
+		return "https://example.com/authorize?state=" + state
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPost,
+		"/api/oauth/login",
+		strings.NewReader(`{"provider":"openai","method":"browser"}`),
+	)
+	req.Host = "localhost:18800"
+	req.Header.Set("Content-Type", "application/json")
+	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 loginResp map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &loginResp); err != nil {
+		t.Fatalf("unmarshal login response: %v", err)
+	}
+	flowID, _ := loginResp["flow_id"].(string)
+	if flowID == "" {
+		t.Fatalf("flow_id is empty: %v", loginResp)
+	}
+	if loginResp["auth_url"] != "https://example.com/authorize?state=state-1" {
+		t.Fatalf("unexpected auth_url: %v", loginResp["auth_url"])
+	}
+
+	rec2 := httptest.NewRecorder()
+	req2 := httptest.NewRequest(http.MethodGet, "/api/oauth/flows/"+flowID, nil)
+	mux.ServeHTTP(rec2, req2)
+	if rec2.Code != http.StatusOK {
+		t.Fatalf("flow status code = %d, want %d, body=%s", rec2.Code, http.StatusOK, rec2.Body.String())
+	}
+	var flowResp oauthFlowResponse
+	if err := json.Unmarshal(rec2.Body.Bytes(), &flowResp); err != nil {
+		t.Fatalf("unmarshal flow response: %v", err)
+	}
+	if flowResp.Status != oauthFlowPending {
+		t.Fatalf("flow status = %q, want %q", flowResp.Status, oauthFlowPending)
+	}
+	if flowResp.Method != oauthMethodBrowser {
+		t.Fatalf("flow method = %q, want %q", flowResp.Method, oauthMethodBrowser)
+	}
+}
+
+func TestOAuthFlowExpiresWhenQueried(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+
+	now := time.Date(2026, 3, 6, 12, 0, 0, 0, time.UTC)
+	oauthNow = func() time.Time { return now }
+
+	h := NewHandler(configPath)
+	h.storeOAuthFlow(&oauthFlow{
+		ID:        "expired-flow",
+		Provider:  oauthProviderOpenAI,
+		Method:    oauthMethodBrowser,
+		Status:    oauthFlowPending,
+		CreatedAt: now.Add(-20 * time.Minute),
+		UpdatedAt: now.Add(-20 * time.Minute),
+		ExpiresAt: now.Add(-1 * time.Minute),
+	})
+
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/oauth/flows/expired-flow", 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 flowResp oauthFlowResponse
+	if err := json.Unmarshal(rec.Body.Bytes(), &flowResp); err != nil {
+		t.Fatalf("unmarshal flow response: %v", err)
+	}
+	if flowResp.Status != oauthFlowExpired {
+		t.Fatalf("flow status = %q, want %q", flowResp.Status, oauthFlowExpired)
+	}
+}
+
+func TestOAuthCallbackUnknownState(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/oauth/callback?state=unknown&code=abc", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
+	}
+	if !strings.Contains(rec.Body.String(), "OAuth flow not found") {
+		t.Fatalf("unexpected body: %s", rec.Body.String())
+	}
+}
+
+func TestOAuthLogoutClearsCredentialAndConfig(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig error: %v", err)
+	}
+	cfg.Providers.OpenAI.AuthMethod = "oauth"
+	cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+		ModelName:  "gpt-5.2",
+		Model:      "openai/gpt-5.2",
+		AuthMethod: "oauth",
+	})
+	if err = config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig error: %v", err)
+	}
+	if err = auth.SetCredential(oauthProviderOpenAI, &auth.AuthCredential{
+		AccessToken: "token-before-logout",
+		Provider:    oauthProviderOpenAI,
+		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.MethodPost, "/api/oauth/logout", bytes.NewBufferString(`{"provider":"openai"}`))
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	cred, err := auth.GetCredential(oauthProviderOpenAI)
+	if err != nil {
+		t.Fatalf("GetCredential error: %v", err)
+	}
+	if cred != nil {
+		t.Fatalf("expected credential deleted, got %#v", cred)
+	}
+
+	updated, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig error: %v", err)
+	}
+	if updated.Providers.OpenAI.AuthMethod != "" {
+		t.Fatalf("providers.openai.auth_method = %q, want empty", updated.Providers.OpenAI.AuthMethod)
+	}
+	for _, m := range updated.ModelList {
+		if strings.HasPrefix(m.Model, "openai/") && m.AuthMethod != "" {
+			t.Fatalf("openai model auth_method = %q, want empty", m.AuthMethod)
+		}
+	}
+}
+
+func setupOAuthTestEnv(t *testing.T) (string, func()) {
+	t.Helper()
+
+	tmp := t.TempDir()
+	oldHome := os.Getenv("HOME")
+	oldPicoHome := os.Getenv("PICOCLAW_HOME")
+
+	if err := os.Setenv("HOME", tmp); err != nil {
+		t.Fatalf("set HOME: %v", err)
+	}
+	if err := os.Setenv("PICOCLAW_HOME", filepath.Join(tmp, ".picoclaw")); err != nil {
+		t.Fatalf("set PICOCLAW_HOME: %v", err)
+	}
+
+	cfg := config.DefaultConfig()
+	cfg.ModelList = []config.ModelConfig{{
+		ModelName: "custom-default",
+		Model:     "openai/gpt-4o",
+		APIKey:    "sk-default",
+	}}
+	cfg.Agents.Defaults.ModelName = "custom-default"
+
+	configPath := filepath.Join(tmp, "config.json")
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig error: %v", err)
+	}
+
+	cleanup := func() {
+		_ = os.Setenv("HOME", oldHome)
+		if oldPicoHome == "" {
+			_ = os.Unsetenv("PICOCLAW_HOME")
+		} else {
+			_ = os.Setenv("PICOCLAW_HOME", oldPicoHome)
+		}
+	}
+	return configPath, cleanup
+}
+
+func resetOAuthHooks(t *testing.T) {
+	t.Helper()
+
+	origNow := oauthNow
+	origGeneratePKCE := oauthGeneratePKCE
+	origGenerateState := oauthGenerateState
+	origBuildAuthorizeURL := oauthBuildAuthorizeURL
+	origRequestDeviceCode := oauthRequestDeviceCode
+	origPollDeviceCodeOnce := oauthPollDeviceCodeOnce
+	origExchangeCodeForTokens := oauthExchangeCodeForTokens
+	origGetCredential := oauthGetCredential
+	origSetCredential := oauthSetCredential
+	origDeleteCredential := oauthDeleteCredential
+	origLoadConfig := oauthLoadConfig
+	origSaveConfig := oauthSaveConfig
+	origFetchProject := oauthFetchAntigravityProject
+	origFetchGoogleEmail := oauthFetchGoogleUserEmailFunc
+
+	t.Cleanup(func() {
+		oauthNow = origNow
+		oauthGeneratePKCE = origGeneratePKCE
+		oauthGenerateState = origGenerateState
+		oauthBuildAuthorizeURL = origBuildAuthorizeURL
+		oauthRequestDeviceCode = origRequestDeviceCode
+		oauthPollDeviceCodeOnce = origPollDeviceCodeOnce
+		oauthExchangeCodeForTokens = origExchangeCodeForTokens
+		oauthGetCredential = origGetCredential
+		oauthSetCredential = origSetCredential
+		oauthDeleteCredential = origDeleteCredential
+		oauthLoadConfig = origLoadConfig
+		oauthSaveConfig = origSaveConfig
+		oauthFetchAntigravityProject = origFetchProject
+		oauthFetchGoogleUserEmailFunc = origFetchGoogleEmail
+	})
+}

web/backend/api/pico.go

@@ -0,0 +1,161 @@
+package api
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// registerPicoRoutes binds Pico Channel management endpoints to the ServeMux.
+func (h *Handler) registerPicoRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/pico/token", h.handleGetPicoToken)
+	mux.HandleFunc("POST /api/pico/token", h.handleRegenPicoToken)
+	mux.HandleFunc("POST /api/pico/setup", h.handlePicoSetup)
+}
+
+// handleGetPicoToken returns the current WS token and URL for the frontend.
+//
+//	GET /api/pico/token
+func (h *Handler) handleGetPicoToken(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	wsURL := buildWsURL(r, cfg)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"token":   cfg.Channels.Pico.Token,
+		"ws_url":  wsURL,
+		"enabled": cfg.Channels.Pico.Enabled,
+	})
+}
+
+// handleRegenPicoToken generates a new Pico WebSocket token and saves it.
+//
+//	POST /api/pico/token
+func (h *Handler) handleRegenPicoToken(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	token := generateSecureToken()
+	cfg.Channels.Pico.Token = token
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	wsURL := fmt.Sprintf("ws://%s/pico/ws", net.JoinHostPort(cfg.Gateway.Host, strconv.Itoa(cfg.Gateway.Port)))
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"token":  token,
+		"ws_url": wsURL,
+	})
+}
+
+// ensurePicoChannel checks if the Pico Channel is properly configured and
+// enables it with sensible defaults if not. Returns true if config was changed.
+func (h *Handler) ensurePicoChannel() (bool, error) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		return false, fmt.Errorf("failed to load config: %w", err)
+	}
+
+	changed := false
+
+	if !cfg.Channels.Pico.Enabled {
+		cfg.Channels.Pico.Enabled = true
+		changed = true
+	}
+
+	if cfg.Channels.Pico.Token == "" {
+		cfg.Channels.Pico.Token = generateSecureToken()
+		changed = true
+	}
+
+	if !cfg.Channels.Pico.AllowTokenQuery {
+		cfg.Channels.Pico.AllowTokenQuery = true
+		changed = true
+	}
+
+	// Make sure origins are allowed (frontend might be running on a different port like 5173 during dev)
+	if len(cfg.Channels.Pico.AllowOrigins) == 0 {
+		cfg.Channels.Pico.AllowOrigins = []string{"*"}
+		changed = true
+	}
+
+	if changed {
+		if err := config.SaveConfig(h.configPath, cfg); err != nil {
+			return false, fmt.Errorf("failed to save config: %w", err)
+		}
+	}
+
+	return changed, nil
+}
+
+// handlePicoSetup automatically configures everything needed for the Pico Channel to work.
+//
+//	POST /api/pico/setup
+func (h *Handler) handlePicoSetup(w http.ResponseWriter, r *http.Request) {
+	changed, err := h.ensurePicoChannel()
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	wsURL := buildWsURL(r, cfg)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"token":   cfg.Channels.Pico.Token,
+		"ws_url":  wsURL,
+		"enabled": true,
+		"changed": changed,
+	})
+}
+
+// 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)
+	if _, err := rand.Read(b); err != nil {
+		// Fallback to something pseudo-random if crypto/rand fails
+		return fmt.Sprintf("pico_%x", time.Now().UnixNano())
+	}
+	return hex.EncodeToString(b)
+}

web/backend/api/router.go

@@ -0,0 +1,66 @@
+package api
+
+import (
+	"net/http"
+	"sync"
+
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+)
+
+// Handler serves HTTP API requests.
+type Handler struct {
+	configPath   string
+	serverPort   int
+	serverPublic bool
+	serverCIDRs  []string
+	oauthMu      sync.Mutex
+	oauthFlows   map[string]*oauthFlow
+	oauthState   map[string]string
+}
+
+// NewHandler creates an instance of the API handler.
+func NewHandler(configPath string) *Handler {
+	return &Handler{
+		configPath: configPath,
+		serverPort: launcherconfig.DefaultPort,
+		oauthFlows: make(map[string]*oauthFlow),
+		oauthState: make(map[string]string),
+	}
+}
+
+// SetServerOptions stores current backend listen options for fallback behavior.
+func (h *Handler) SetServerOptions(port int, public bool, allowedCIDRs []string) {
+	h.serverPort = port
+	h.serverPublic = public
+	h.serverCIDRs = append([]string(nil), allowedCIDRs...)
+}
+
+// RegisterRoutes binds all API endpoint handlers to the ServeMux.
+func (h *Handler) RegisterRoutes(mux *http.ServeMux) {
+	// Config CRUD
+	h.registerConfigRoutes(mux)
+
+	// Pico Channel (WebSocket chat)
+	h.registerPicoRoutes(mux)
+
+	// Gateway process lifecycle
+	h.registerGatewayRoutes(mux)
+
+	// Session history
+	h.registerSessionRoutes(mux)
+
+	// OAuth login and credential management
+	h.registerOAuthRoutes(mux)
+
+	// Model list management
+	h.registerModelRoutes(mux)
+
+	// Channel catalog (for frontend navigation/config pages)
+	h.registerChannelRoutes(mux)
+
+	// OS startup / launch-at-login
+	h.registerStartupRoutes(mux)
+
+	// Launcher service parameters (port/public)
+	h.registerLauncherConfigRoutes(mux)
+}

web/backend/api/session.go

@@ -0,0 +1,286 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// registerSessionRoutes binds session list and detail endpoints to the ServeMux.
+func (h *Handler) registerSessionRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/sessions", h.handleListSessions)
+	mux.HandleFunc("GET /api/sessions/{id}", h.handleGetSession)
+	mux.HandleFunc("DELETE /api/sessions/{id}", h.handleDeleteSession)
+}
+
+// sessionFile mirrors the on-disk session JSON structure from pkg/session.
+type sessionFile struct {
+	Key      string              `json:"key"`
+	Messages []providers.Message `json:"messages"`
+	Summary  string              `json:"summary,omitempty"`
+	Created  time.Time           `json:"created"`
+	Updated  time.Time           `json:"updated"`
+}
+
+// sessionListItem is a lightweight summary returned by GET /api/sessions.
+type sessionListItem struct {
+	ID           string `json:"id"`
+	Preview      string `json:"preview"`
+	MessageCount int    `json:"message_count"`
+	Created      string `json:"created"`
+	Updated      string `json:"updated"`
+}
+
+// picoSessionPrefix is the key prefix used by the gateway's routing for Pico
+// channel sessions. The full key format is:
+//
+//	agent:main:pico:direct:pico:<session-uuid>
+//
+// 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:"
+
+// extractPicoSessionID extracts the session UUID from a full session key.
+// Returns the UUID and true if the key matches the Pico session pattern.
+func extractPicoSessionID(key string) (string, bool) {
+	if strings.HasPrefix(key, picoSessionPrefix) {
+		return strings.TrimPrefix(key, picoSessionPrefix), true
+	}
+	return "", false
+}
+
+// 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) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		return "", err
+	}
+
+	workspace := cfg.Agents.Defaults.Workspace
+	if workspace == "" {
+		home, _ := os.UserHomeDir()
+		workspace = filepath.Join(home, ".picoclaw", "workspace")
+	}
+
+	// Expand ~ prefix
+	if len(workspace) > 0 && workspace[0] == '~' {
+		home, _ := os.UserHomeDir()
+		if len(workspace) > 1 && workspace[1] == '/' {
+			workspace = home + workspace[1:]
+		} else {
+			workspace = home
+		}
+	}
+
+	return filepath.Join(workspace, "sessions"), nil
+}
+
+// handleListSessions returns a list of Pico session summaries.
+//
+//	GET /api/sessions
+func (h *Handler) handleListSessions(w http.ResponseWriter, r *http.Request) {
+	dir, err := h.sessionsDir()
+	if err != nil {
+		http.Error(w, "failed to resolve sessions directory", http.StatusInternalServerError)
+		return
+	}
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		// Directory doesn't exist yet = no sessions
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode([]sessionListItem{})
+		return
+	}
+
+	items := []sessionListItem{}
+
+	for _, entry := range entries {
+		if entry.IsDir() || filepath.Ext(entry.Name()) != ".json" {
+			continue
+		}
+
+		data, err := os.ReadFile(filepath.Join(dir, entry.Name()))
+		if err != nil {
+			continue
+		}
+
+		var sess sessionFile
+		if err := json.Unmarshal(data, &sess); err != nil {
+			continue
+		}
+
+		// Only include Pico channel sessions
+		sessionID, ok := extractPicoSessionID(sess.Key)
+		if !ok {
+			continue
+		}
+
+		// Build a preview from the first user message
+		preview := ""
+		for _, msg := range sess.Messages {
+			if msg.Role == "user" && strings.TrimSpace(msg.Content) != "" {
+				preview = msg.Content
+				break
+			}
+		}
+		if len([]rune(preview)) > 60 {
+			preview = string([]rune(preview)[:60]) + "..."
+		}
+		if preview == "" {
+			preview = "(empty)"
+		}
+
+		// Only count non-empty user and assistant messages
+		validMessageCount := 0
+		for _, msg := range sess.Messages {
+			if (msg.Role == "user" || msg.Role == "assistant") && strings.TrimSpace(msg.Content) != "" {
+				validMessageCount++
+			}
+		}
+
+		items = append(items, sessionListItem{
+			ID:           sessionID,
+			Preview:      preview,
+			MessageCount: validMessageCount,
+			Created:      sess.Created.Format(time.RFC3339),
+			Updated:      sess.Updated.Format(time.RFC3339),
+		})
+	}
+
+	// Sort by updated descending (most recent first)
+	sort.Slice(items, func(i, j int) bool {
+		return items[i].Updated > items[j].Updated
+	})
+
+	// Pagination parameters
+	offsetStr := r.URL.Query().Get("offset")
+	limitStr := r.URL.Query().Get("limit")
+
+	offset := 0
+	limit := 20 // Default limit
+
+	if val, err := strconv.Atoi(offsetStr); err == nil && val >= 0 {
+		offset = val
+	}
+	if val, err := strconv.Atoi(limitStr); err == nil && val > 0 {
+		limit = val
+	}
+
+	totalItems := len(items)
+
+	end := offset + limit
+	if offset >= totalItems {
+		items = []sessionListItem{} // Out of bounds, return empty
+	} else {
+		if end > totalItems {
+			end = totalItems
+		}
+		items = items[offset:end]
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(items)
+}
+
+// handleGetSession returns the full message history for a specific session.
+//
+//	GET /api/sessions/{id}
+func (h *Handler) handleGetSession(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	if sessionID == "" {
+		http.Error(w, "missing session id", http.StatusBadRequest)
+		return
+	}
+
+	dir, err := h.sessionsDir()
+	if err != nil {
+		http.Error(w, "failed to resolve sessions directory", http.StatusInternalServerError)
+		return
+	}
+
+	// The sanitized filename replaces ':' with '_':
+	// agent:main:pico:direct:pico:<uuid> -> agent_main_pico_direct_pico_<uuid>.json
+	filename := strings.ReplaceAll(picoSessionPrefix+sessionID, ":", "_") + ".json"
+
+	data, err := os.ReadFile(filepath.Join(dir, filename))
+	if err != nil {
+		http.Error(w, "session not found", http.StatusNotFound)
+		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
+	type chatMessage struct {
+		Role    string `json:"role"`
+		Content string `json:"content"`
+	}
+
+	messages := make([]chatMessage, 0, len(sess.Messages))
+	for _, msg := range sess.Messages {
+		// Only include user and assistant messages that have actual content
+		if (msg.Role == "user" || msg.Role == "assistant") && strings.TrimSpace(msg.Content) != "" {
+			messages = append(messages, chatMessage{
+				Role:    msg.Role,
+				Content: msg.Content,
+			})
+		}
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"id":       sessionID,
+		"messages": messages,
+		"summary":  sess.Summary,
+		"created":  sess.Created.Format(time.RFC3339),
+		"updated":  sess.Updated.Format(time.RFC3339),
+	})
+}
+
+// handleDeleteSession deletes a specific session.
+//
+//	DELETE /api/sessions/{id}
+func (h *Handler) handleDeleteSession(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	if sessionID == "" {
+		http.Error(w, "missing session id", http.StatusBadRequest)
+		return
+	}
+
+	dir, err := h.sessionsDir()
+	if err != nil {
+		http.Error(w, "failed to resolve sessions directory", http.StatusInternalServerError)
+		return
+	}
+
+	// The sanitized filename replaces ':' with '_':
+	// agent:main:pico:direct:pico:<uuid> -> agent_main_pico_direct_pico_<uuid>.json
+	filename := strings.ReplaceAll(picoSessionPrefix+sessionID, ":", "_") + ".json"
+	filePath := filepath.Join(dir, filename)
+
+	if err := os.Remove(filePath); err != nil {
+		if os.IsNotExist(err) {
+			http.Error(w, "session not found", http.StatusNotFound)
+		} else {
+			http.Error(w, "failed to delete session", http.StatusInternalServerError)
+		}
+		return
+	}
+
+	w.WriteHeader(http.StatusNoContent)
+}

web/backend/api/startup.go

@@ -0,0 +1,305 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+const (
+	autoStartEntryName = "PicoClawLauncher"
+	launchAgentLabel   = "io.picoclaw.launcher"
+)
+
+type autoStartRequest struct {
+	Enabled bool `json:"enabled"`
+}
+
+type autoStartResponse struct {
+	Enabled   bool   `json:"enabled"`
+	Supported bool   `json:"supported"`
+	Platform  string `json:"platform"`
+	Message   string `json:"message,omitempty"`
+}
+
+var errAutoStartUnsupported = errors.New("autostart is not supported on this platform")
+
+func (h *Handler) registerStartupRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/system/autostart", h.handleGetAutoStart)
+	mux.HandleFunc("PUT /api/system/autostart", h.handleSetAutoStart)
+}
+
+func (h *Handler) handleGetAutoStart(w http.ResponseWriter, r *http.Request) {
+	enabled, supported, message, err := h.getAutoStartStatus()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to read startup setting: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(autoStartResponse{
+		Enabled:   enabled,
+		Supported: supported,
+		Platform:  runtime.GOOS,
+		Message:   message,
+	})
+}
+
+func (h *Handler) handleSetAutoStart(w http.ResponseWriter, r *http.Request) {
+	var req autoStartRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if err := h.setAutoStart(req.Enabled); err != nil {
+		if errors.Is(err, errAutoStartUnsupported) {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		http.Error(w, fmt.Sprintf("Failed to update startup setting: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	enabled, supported, message, err := h.getAutoStartStatus()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to verify startup setting: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(autoStartResponse{
+		Enabled:   enabled,
+		Supported: supported,
+		Platform:  runtime.GOOS,
+		Message:   message,
+	})
+}
+
+func (h *Handler) resolveLaunchCommand() (string, []string, error) {
+	exePath, err := os.Executable()
+	if err != nil {
+		return "", nil, err
+	}
+
+	args := []string{"-no-browser"}
+	if h.configPath != "" {
+		args = append(args, h.configPath)
+	}
+
+	return exePath, args, nil
+}
+
+func (h *Handler) getAutoStartStatus() (enabled bool, supported bool, message string, err error) {
+	switch runtime.GOOS {
+	case "darwin":
+		exists, err := fileExists(macLaunchAgentPath())
+		return exists, true, "Changes apply on next login.", err
+	case "linux":
+		exists, err := fileExists(linuxAutoStartPath())
+		return exists, true, "Changes apply on next login.", err
+	case "windows":
+		exists, err := windowsRunKeyExists()
+		return exists, true, "Changes apply on next login.", err
+	default:
+		return false, false, "Current platform does not support launch at login.", nil
+	}
+}
+
+func (h *Handler) setAutoStart(enabled bool) error {
+	exePath, args, err := h.resolveLaunchCommand()
+	if err != nil {
+		return err
+	}
+
+	switch runtime.GOOS {
+	case "darwin":
+		return setDarwinAutoStart(enabled, exePath, args)
+	case "linux":
+		return setLinuxAutoStart(enabled, exePath, args)
+	case "windows":
+		return setWindowsAutoStart(enabled, exePath, args)
+	default:
+		return errAutoStartUnsupported
+	}
+}
+
+func fileExists(path string) (bool, error) {
+	_, err := os.Stat(path)
+	if err == nil {
+		return true, nil
+	}
+	if os.IsNotExist(err) {
+		return false, nil
+	}
+	return false, err
+}
+
+func macLaunchAgentPath() string {
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, "Library", "LaunchAgents", launchAgentLabel+".plist")
+}
+
+func setDarwinAutoStart(enabled bool, exePath string, args []string) error {
+	plistPath := macLaunchAgentPath()
+	if enabled {
+		if err := os.MkdirAll(filepath.Dir(plistPath), 0o755); err != nil {
+			return err
+		}
+		content := buildDarwinPlist(exePath, args)
+		return os.WriteFile(plistPath, []byte(content), 0o644)
+	}
+
+	if err := os.Remove(plistPath); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+func xmlEscape(s string) string {
+	var b bytes.Buffer
+	for _, r := range s {
+		switch r {
+		case '&':
+			b.WriteString("&")
+		case '<':
+			b.WriteString("&lt;")
+		case '>':
+			b.WriteString("&gt;")
+		case '"':
+			b.WriteString("&quot;")
+		case '\'':
+			b.WriteString("&apos;")
+		default:
+			b.WriteRune(r)
+		}
+	}
+	return b.String()
+}
+
+func buildDarwinPlist(exePath string, args []string) string {
+	programArgs := make([]string, 0, len(args)+1)
+	programArgs = append(programArgs, exePath)
+	programArgs = append(programArgs, args...)
+
+	var b strings.Builder
+	b.WriteString(`<?xml version="1.0" encoding="UTF-8"?>` + "\n")
+	b.WriteString(
+		`<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">` + "\n",
+	)
+	b.WriteString(`<plist version="1.0">` + "\n")
+	b.WriteString(`<dict>` + "\n")
+	b.WriteString(`  <key>Label</key>` + "\n")
+	b.WriteString(`  <string>` + launchAgentLabel + `</string>` + "\n")
+	b.WriteString(`  <key>ProgramArguments</key>` + "\n")
+	b.WriteString(`  <array>` + "\n")
+	for _, arg := range programArgs {
+		b.WriteString(`    <string>` + xmlEscape(arg) + `</string>` + "\n")
+	}
+	b.WriteString(`  </array>` + "\n")
+	b.WriteString(`  <key>RunAtLoad</key>` + "\n")
+	b.WriteString(`  <true/>` + "\n")
+	b.WriteString(`  <key>ProcessType</key>` + "\n")
+	b.WriteString(`  <string>Background</string>` + "\n")
+	b.WriteString(`</dict>` + "\n")
+	b.WriteString(`</plist>` + "\n")
+	return b.String()
+}
+
+func linuxAutoStartPath() string {
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, ".config", "autostart", "picoclaw-web.desktop")
+}
+
+func shellQuote(s string) string {
+	if s == "" {
+		return "''"
+	}
+	if !strings.ContainsAny(s, " \t\n'\"\\$`") {
+		return s
+	}
+	return "'" + strings.ReplaceAll(s, "'", "'\"'\"'") + "'"
+}
+
+func buildLinuxExecLine(exePath string, args []string) string {
+	parts := make([]string, 0, len(args)+1)
+	parts = append(parts, shellQuote(exePath))
+	for _, arg := range args {
+		parts = append(parts, shellQuote(arg))
+	}
+	return strings.Join(parts, " ")
+}
+
+func setLinuxAutoStart(enabled bool, exePath string, args []string) error {
+	desktopPath := linuxAutoStartPath()
+	if enabled {
+		if err := os.MkdirAll(filepath.Dir(desktopPath), 0o755); err != nil {
+			return err
+		}
+		content := strings.Join([]string{
+			"[Desktop Entry]",
+			"Type=Application",
+			"Version=1.0",
+			"Name=PicoClaw Web",
+			"Comment=Start PicoClaw Web on login",
+			"Exec=" + buildLinuxExecLine(exePath, args),
+			"Terminal=false",
+			"X-GNOME-Autostart-enabled=true",
+			"NoDisplay=true",
+			"",
+		}, "\n")
+		return os.WriteFile(desktopPath, []byte(content), 0o644)
+	}
+
+	if err := os.Remove(desktopPath); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+func windowsCommandLine(exePath string, args []string) string {
+	parts := make([]string, 0, len(args)+1)
+	parts = append(parts, fmt.Sprintf("%q", exePath))
+	for _, arg := range args {
+		parts = append(parts, fmt.Sprintf("%q", arg))
+	}
+	return strings.Join(parts, " ")
+}
+
+func windowsRunKeyExists() (bool, error) {
+	cmd := exec.Command("reg", "query", `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`, "/v", autoStartEntryName)
+	if err := cmd.Run(); err != nil {
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			return false, nil
+		}
+		return false, err
+	}
+	return true, nil
+}
+
+func setWindowsAutoStart(enabled bool, exePath string, args []string) error {
+	key := `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`
+	if enabled {
+		commandLine := windowsCommandLine(exePath, args)
+		cmd := exec.Command("reg", "add", key, "/v", autoStartEntryName, "/t", "REG_SZ", "/d", commandLine, "/f")
+		return cmd.Run()
+	}
+
+	cmd := exec.Command("reg", "delete", key, "/v", autoStartEntryName, "/f")
+	if err := cmd.Run(); err != nil {
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			return nil
+		}
+		return err
+	}
+	return nil
+}

web/backend/api/startup_test.go

@@ -0,0 +1,56 @@
+package api
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+)
+
+func TestResolveLaunchCommandUsesConfigFileDefaults(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	// Persist non-default launcher options to ensure resolveLaunchCommand does not
+	// pin them into autostart args.
+	launcherPath := launcherconfig.PathForAppConfig(configPath)
+	if err := launcherconfig.Save(launcherPath, launcherconfig.Config{
+		Port:   19999,
+		Public: true,
+	}); err != nil {
+		t.Fatalf("launcherconfig.Save() error = %v", err)
+	}
+
+	exePath, args, err := h.resolveLaunchCommand()
+	if err != nil {
+		t.Fatalf("resolveLaunchCommand() error = %v", err)
+	}
+	if exePath == "" {
+		t.Fatal("resolveLaunchCommand() returned empty executable path")
+	}
+	if len(args) != 2 {
+		t.Fatalf("args len = %d, want 2 (got %v)", len(args), args)
+	}
+	if args[0] != "-no-browser" {
+		t.Fatalf("args[0] = %q, want %q", args[0], "-no-browser")
+	}
+	if args[1] != configPath {
+		t.Fatalf("args[1] = %q, want %q", args[1], configPath)
+	}
+	for _, arg := range args {
+		if arg == "-port" || arg == "-public" {
+			t.Fatalf("autostart args should not pin network flags, got %v", args)
+		}
+	}
+}
+
+func TestBuildDarwinPlistIncludesRunAtLoad(t *testing.T) {
+	plist := buildDarwinPlist("/tmp/picoclaw-web", []string{"-no-browser", "/tmp/config.json"})
+	if !strings.Contains(plist, "<key>RunAtLoad</key>") {
+		t.Fatalf("plist missing RunAtLoad key:\n%s", plist)
+	}
+	if !strings.Contains(plist, "<true/>") {
+		t.Fatalf("plist missing RunAtLoad true value:\n%s", plist)
+	}
+}

web/backend/embed.go

@@ -0,0 +1,69 @@
+package main
+
+import (
+	"embed"
+	"io/fs"
+	"log"
+	"net/http"
+	"path"
+	"strings"
+)
+
+//go:embed all:dist
+var frontendFS embed.FS
+
+// registerEmbedRoutes sets up the HTTP handler to serve the embedded frontend files
+func registerEmbedRoutes(mux *http.ServeMux) {
+	// Attempt to get the subdirectory 'dist' where Vite usually builds
+	subFS, err := fs.Sub(frontendFS, "dist")
+	if err != nil {
+		// Log a warning if dist doesn't exist yet (e.g., during development before a frontend build)
+		log.Printf(
+			"Warning: no 'dist' folder found in embedded frontend. " +
+				"Ensure you run `pnpm build:backend` in the frontend directory " +
+				"before building the Go backend.",
+		)
+		return
+	}
+
+	fileServer := http.FileServer(http.FS(subFS))
+
+	// Serve static assets and fallback to index.html for SPA routes.
+	mux.Handle(
+		"/",
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.Method != http.MethodGet && r.Method != http.MethodHead {
+				http.NotFound(w, r)
+				return
+			}
+
+			// Keep unknown API paths as 404 instead of falling back to SPA entry.
+			if r.URL.Path == "/api" || strings.HasPrefix(r.URL.Path, "/api/") {
+				http.NotFound(w, r)
+				return
+			}
+
+			cleanPath := path.Clean(strings.TrimPrefix(r.URL.Path, "/"))
+			if cleanPath == "." {
+				cleanPath = ""
+			}
+
+			// Existing static files/directories should be served directly.
+			if cleanPath != "" {
+				if _, statErr := fs.Stat(subFS, cleanPath); statErr == nil {
+					fileServer.ServeHTTP(w, r)
+					return
+				}
+				// Missing asset-like paths should remain 404.
+				if strings.Contains(path.Base(cleanPath), ".") {
+					fileServer.ServeHTTP(w, r)
+					return
+				}
+			}
+
+			indexReq := r.Clone(r.Context())
+			indexReq.URL.Path = "/"
+			fileServer.ServeHTTP(w, indexReq)
+		}),
+	)
+}

web/backend/embed_test.go

@@ -0,0 +1,33 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestUnknownAPIPathStays404(t *testing.T) {
+	mux := http.NewServeMux()
+	registerEmbedRoutes(mux)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/not-found", nil)
+	rr := httptest.NewRecorder()
+	mux.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want %d", rr.Code, http.StatusNotFound)
+	}
+}
+
+func TestMissingAssetStays404(t *testing.T) {
+	mux := http.NewServeMux()
+	registerEmbedRoutes(mux)
+
+	req := httptest.NewRequest(http.MethodGet, "/assets/not-found.js", nil)
+	rr := httptest.NewRecorder()
+	mux.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want %d", rr.Code, http.StatusNotFound)
+	}
+}

web/backend/launcherconfig/config.go

@@ -0,0 +1,113 @@
+package launcherconfig
+
+import (
+	"encoding/json"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const (
+	// FileName is the launcher-specific settings file name.
+	FileName = "launcher-config.json"
+	// DefaultPort is the default port for the web launcher.
+	DefaultPort = 18800
+)
+
+// Config stores launch parameters for the web backend service.
+type Config struct {
+	Port         int      `json:"port"`
+	Public       bool     `json:"public"`
+	AllowedCIDRs []string `json:"allowed_cidrs,omitempty"`
+}
+
+// Default returns default launcher settings.
+func Default() Config {
+	return Config{Port: DefaultPort, Public: false}
+}
+
+// Validate checks if launcher settings are valid.
+func Validate(cfg Config) error {
+	if cfg.Port < 1 || cfg.Port > 65535 {
+		return fmt.Errorf("port %d is out of range (1-65535)", cfg.Port)
+	}
+	for _, cidr := range cfg.AllowedCIDRs {
+		if _, _, err := net.ParseCIDR(cidr); err != nil {
+			return fmt.Errorf("invalid CIDR %q", cidr)
+		}
+	}
+	return nil
+}
+
+// NormalizeCIDRs trims entries, removes empty values, and deduplicates CIDRs.
+func NormalizeCIDRs(cidrs []string) []string {
+	if len(cidrs) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(cidrs))
+	seen := make(map[string]struct{}, len(cidrs))
+	for _, raw := range cidrs {
+		trimmed := strings.TrimSpace(raw)
+		if trimmed == "" {
+			continue
+		}
+		if _, ok := seen[trimmed]; ok {
+			continue
+		}
+		seen[trimmed] = struct{}{}
+		out = append(out, trimmed)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+// PathForAppConfig returns launcher-config path near the app config file.
+func PathForAppConfig(appConfigPath string) string {
+	dir := filepath.Dir(appConfigPath)
+	if dir == "" || dir == "." {
+		dir = "."
+	}
+	return filepath.Join(dir, FileName)
+}
+
+// Load reads launcher settings; fallback is returned when file does not exist.
+func Load(path string, fallback Config) (Config, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return fallback, nil
+		}
+		return Config{}, err
+	}
+
+	cfg := fallback
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return Config{}, err
+	}
+	cfg.AllowedCIDRs = NormalizeCIDRs(cfg.AllowedCIDRs)
+	if err := Validate(cfg); err != nil {
+		return Config{}, err
+	}
+	return cfg, nil
+}
+
+// Save writes launcher settings to disk.
+func Save(path string, cfg Config) error {
+	cfg.AllowedCIDRs = NormalizeCIDRs(cfg.AllowedCIDRs)
+	if err := Validate(cfg); err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		return err
+	}
+	data = append(data, '\n')
+	return os.WriteFile(path, data, 0o600)
+}

web/backend/launcherconfig/config_test.go

@@ -0,0 +1,89 @@
+package launcherconfig
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLoadReturnsFallbackWhenMissing(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "launcher-config.json")
+	fallback := Config{Port: 19999, Public: true}
+
+	got, err := Load(path, fallback)
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if got.Port != fallback.Port || got.Public != fallback.Public {
+		t.Fatalf("Load() = %+v, want %+v", got, fallback)
+	}
+}
+
+func TestSaveAndLoadRoundTrip(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "launcher-config.json")
+	want := Config{
+		Port:         18080,
+		Public:       true,
+		AllowedCIDRs: []string{"192.168.1.0/24", "10.0.0.0/8"},
+	}
+
+	if err := Save(path, want); err != nil {
+		t.Fatalf("Save() error = %v", err)
+	}
+	got, err := Load(path, Default())
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if got.Port != want.Port || got.Public != want.Public {
+		t.Fatalf("Load() = %+v, want %+v", got, want)
+	}
+	if len(got.AllowedCIDRs) != len(want.AllowedCIDRs) {
+		t.Fatalf("allowed_cidrs len = %d, want %d", len(got.AllowedCIDRs), len(want.AllowedCIDRs))
+	}
+	for i := range want.AllowedCIDRs {
+		if got.AllowedCIDRs[i] != want.AllowedCIDRs[i] {
+			t.Fatalf("allowed_cidrs[%d] = %q, want %q", i, got.AllowedCIDRs[i], want.AllowedCIDRs[i])
+		}
+	}
+
+	stat, err := os.Stat(path)
+	if err != nil {
+		t.Fatalf("Stat() error = %v", err)
+	}
+	if perm := stat.Mode().Perm(); perm != 0o600 {
+		t.Fatalf("file perm = %o, want 600", perm)
+	}
+}
+
+func TestValidateRejectsInvalidPort(t *testing.T) {
+	if err := Validate(Config{Port: 0, Public: false}); err == nil {
+		t.Fatal("Validate() expected error for port 0")
+	}
+	if err := Validate(Config{Port: 65536, Public: false}); err == nil {
+		t.Fatal("Validate() expected error for port 65536")
+	}
+}
+
+func TestValidateRejectsInvalidCIDR(t *testing.T) {
+	err := Validate(Config{
+		Port:         18800,
+		AllowedCIDRs: []string{"192.168.1.0/24", "not-a-cidr"},
+	})
+	if err == nil {
+		t.Fatal("Validate() expected error for invalid CIDR")
+	}
+}
+
+func TestNormalizeCIDRs(t *testing.T) {
+	got := NormalizeCIDRs([]string{" 192.168.1.0/24 ", "", "10.0.0.0/8", "192.168.1.0/24"})
+	want := []string{"192.168.1.0/24", "10.0.0.0/8"}
+	if len(got) != len(want) {
+		t.Fatalf("len(got) = %d, want %d", len(got), len(want))
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("got[%d] = %q, want %q", i, got[i], want[i])
+		}
+	}
+}

web/backend/main.go

@@ -0,0 +1,164 @@
+// PicoClaw Web Console - Web-based chat and management interface
+//
+// Provides a web UI for chatting with PicoClaw via the Pico Channel WebSocket,
+// with configuration management and gateway process control.
+//
+// Usage:
+//
+//	go build -o picoclaw-web ./web/backend/
+//	./picoclaw-web [config.json]
+//	./picoclaw-web -public config.json
+
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"time"
+
+	"github.com/sipeed/picoclaw/web/backend/api"
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+	"github.com/sipeed/picoclaw/web/backend/middleware"
+)
+
+func main() {
+	port := flag.String("port", "18800", "Port to listen on")
+	public := flag.Bool("public", false, "Listen on all interfaces (0.0.0.0) instead of localhost only")
+	noBrowser := flag.Bool("no-browser", false, "Do not auto-open browser on startup")
+
+	flag.Usage = func() {
+		fmt.Fprintf(os.Stderr, "PicoClaw Launcher - A web-based configuration editor\n\n")
+		fmt.Fprintf(os.Stderr, "Usage: %s [options] [config.json]\n\n", os.Args[0])
+		fmt.Fprintf(os.Stderr, "Arguments:\n")
+		fmt.Fprintf(os.Stderr, "  config.json    Path to the configuration file (default: ~/.picoclaw/config.json)\n\n")
+		fmt.Fprintf(os.Stderr, "Options:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(os.Stderr, "\nExamples:\n")
+		fmt.Fprintf(os.Stderr, "  %s                          Use default config path\n", os.Args[0])
+		fmt.Fprintf(os.Stderr, "  %s ./config.json             Specify a config file\n", os.Args[0])
+		fmt.Fprintf(
+			os.Stderr,
+			"  %s -public ./config.json     Allow access from other devices on the network\n",
+			os.Args[0],
+		)
+	}
+	flag.Parse()
+
+	// Resolve config path
+	configPath := getDefaultConfigPath()
+	if flag.NArg() > 0 {
+		configPath = flag.Arg(0)
+	}
+
+	absPath, err := filepath.Abs(configPath)
+	if err != nil {
+		log.Fatalf("Failed to resolve config path: %v", err)
+	}
+
+	var explicitPort bool
+	var explicitPublic bool
+	flag.Visit(func(f *flag.Flag) {
+		switch f.Name {
+		case "port":
+			explicitPort = true
+		case "public":
+			explicitPublic = true
+		}
+	})
+
+	launcherPath := launcherconfig.PathForAppConfig(absPath)
+	launcherCfg, err := launcherconfig.Load(launcherPath, launcherconfig.Default())
+	if err != nil {
+		log.Printf("Warning: Failed to load %s: %v", launcherPath, err)
+		launcherCfg = launcherconfig.Default()
+	}
+
+	effectivePort := *port
+	effectivePublic := *public
+	if !explicitPort {
+		effectivePort = strconv.Itoa(launcherCfg.Port)
+	}
+	if !explicitPublic {
+		effectivePublic = launcherCfg.Public
+	}
+
+	portNum, err := strconv.Atoi(effectivePort)
+	if err != nil || portNum < 1 || portNum > 65535 {
+		if err == nil {
+			err = errors.New("must be in range 1-65535")
+		}
+		log.Fatalf("Invalid port %q: %v", effectivePort, err)
+	}
+
+	// Determine listen address
+	var addr string
+	if effectivePublic {
+		addr = "0.0.0.0:" + effectivePort
+	} else {
+		addr = "127.0.0.1:" + effectivePort
+	}
+
+	// Initialize Server components
+	mux := http.NewServeMux()
+
+	// API Routes (e.g. /api/status)
+	apiHandler := api.NewHandler(absPath)
+	apiHandler.SetServerOptions(portNum, effectivePublic, launcherCfg.AllowedCIDRs)
+	apiHandler.RegisterRoutes(mux)
+
+	// Frontend Embedded Assets
+	registerEmbedRoutes(mux)
+
+	accessControlledMux, err := middleware.IPAllowlist(launcherCfg.AllowedCIDRs, mux)
+	if err != nil {
+		log.Fatalf("Invalid allowed CIDR configuration: %v", err)
+	}
+
+	// Apply middleware stack
+	handler := middleware.Recoverer(
+		middleware.Logger(
+			middleware.JSONContentType(accessControlledMux),
+		),
+	)
+
+	// Print startup banner
+	fmt.Print(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 != "" {
+			fmt.Printf("    >> http://%s:%s <<\n", ip, effectivePort)
+		}
+	}
+	fmt.Println()
+
+	// Auto-open browser
+	if !*noBrowser {
+		go func() {
+			time.Sleep(500 * time.Millisecond)
+			url := "http://localhost:" + effectivePort
+			if err := openBrowser(url); err != nil {
+				log.Printf("Warning: Failed to auto-open browser: %v", err)
+			}
+		}()
+	}
+
+	// Auto-start gateway after backend starts listening.
+	go func() {
+		time.Sleep(1 * time.Second)
+		apiHandler.TryAutoStartGateway()
+	}()
+
+	// Start the Server
+	if err := http.ListenAndServe(addr, handler); err != nil {
+		log.Fatalf("Server failed to start: %v", err)
+	}
+}

web/backend/middleware/access_control.go

@@ -0,0 +1,64 @@
+package middleware
+
+import (
+	"fmt"
+	"net"
+	"net/http"
+	"strings"
+)
+
+// IPAllowlist restricts access to requests from configured CIDR ranges.
+// Loopback addresses are always allowed for local administration.
+// Empty CIDR list means no restriction.
+func IPAllowlist(allowedCIDRs []string, next http.Handler) (http.Handler, error) {
+	if len(allowedCIDRs) == 0 {
+		return next, nil
+	}
+
+	nets := make([]*net.IPNet, 0, len(allowedCIDRs))
+	for _, cidr := range allowedCIDRs {
+		_, ipNet, err := net.ParseCIDR(cidr)
+		if err != nil {
+			return nil, fmt.Errorf("invalid CIDR %q: %w", cidr, err)
+		}
+		nets = append(nets, ipNet)
+	}
+
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		ip := clientIPFromRemoteAddr(r.RemoteAddr)
+		if ip == nil {
+			rejectByPolicy(w, r)
+			return
+		}
+		if ip.IsLoopback() {
+			next.ServeHTTP(w, r)
+			return
+		}
+		for _, ipNet := range nets {
+			if ipNet.Contains(ip) {
+				next.ServeHTTP(w, r)
+				return
+			}
+		}
+
+		rejectByPolicy(w, r)
+	}), nil
+}
+
+func clientIPFromRemoteAddr(remoteAddr string) net.IP {
+	host := remoteAddr
+	if h, _, err := net.SplitHostPort(remoteAddr); err == nil {
+		host = h
+	}
+	return net.ParseIP(host)
+}
+
+func rejectByPolicy(w http.ResponseWriter, r *http.Request) {
+	if strings.HasPrefix(r.URL.Path, "/api/") {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusForbidden)
+		_, _ = w.Write([]byte(`{"error":"access denied by network policy"}`))
+		return
+	}
+	http.Error(w, "Forbidden", http.StatusForbidden)
+}

web/backend/middleware/access_control_test.go

@@ -0,0 +1,86 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestIPAllowlist_EmptyCIDRsAllowsAll(t *testing.T) {
+	h, err := IPAllowlist(nil, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	if err != nil {
+		t.Fatalf("IPAllowlist() error = %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.RemoteAddr = "203.0.113.5:1234"
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+func TestIPAllowlist_RejectsOutsideCIDR(t *testing.T) {
+	h, err := IPAllowlist([]string{"192.168.1.0/24"}, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	if err != nil {
+		t.Fatalf("IPAllowlist() error = %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/config", nil)
+	req.RemoteAddr = "10.0.0.8:1234"
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusForbidden)
+	}
+}
+
+func TestIPAllowlist_AllowsInsideCIDR(t *testing.T) {
+	h, err := IPAllowlist([]string{"192.168.1.0/24"}, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	if err != nil {
+		t.Fatalf("IPAllowlist() error = %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.RemoteAddr = "192.168.1.88:1234"
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+func TestIPAllowlist_AlwaysAllowsLoopback(t *testing.T) {
+	h, err := IPAllowlist([]string{"192.168.1.0/24"}, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	if err != nil {
+		t.Fatalf("IPAllowlist() error = %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.RemoteAddr = "127.0.0.1:1234"
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+func TestIPAllowlist_InvalidCIDR(t *testing.T) {
+	_, err := IPAllowlist([]string{"bad-cidr"}, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
+	if err == nil {
+		t.Fatal("IPAllowlist() expected error for invalid CIDR")
+	}
+}

web/backend/middleware/middleware.go

@@ -0,0 +1,70 @@
+package middleware
+
+import (
+	"log"
+	"net/http"
+	"runtime/debug"
+	"strings"
+	"time"
+)
+
+// JSONContentType sets the Content-Type header to application/json for
+// API requests handled by the wrapped handler.
+// SSE endpoints (text/event-stream) are excluded.
+func JSONContentType(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasPrefix(r.URL.Path, "/api/") && !strings.HasSuffix(r.URL.Path, "/events") {
+			w.Header().Set("Content-Type", "application/json")
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// responseRecorder wraps http.ResponseWriter to capture the status code.
+type responseRecorder struct {
+	http.ResponseWriter
+	statusCode int
+}
+
+func (rr *responseRecorder) WriteHeader(code int) {
+	rr.statusCode = code
+	rr.ResponseWriter.WriteHeader(code)
+}
+
+// Flush delegates to the underlying ResponseWriter if it implements http.Flusher.
+// This is required for SSE (Server-Sent Events) to work through the middleware.
+func (rr *responseRecorder) Flush() {
+	if f, ok := rr.ResponseWriter.(http.Flusher); ok {
+		f.Flush()
+	}
+}
+
+// Unwrap returns the underlying ResponseWriter so that http.ResponseController
+// and interface checks (like http.Flusher) can see through the wrapper.
+func (rr *responseRecorder) Unwrap() http.ResponseWriter {
+	return rr.ResponseWriter
+}
+
+// Logger logs each HTTP request with method, path, status code, and duration.
+func Logger(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		start := time.Now()
+		rec := &responseRecorder{ResponseWriter: w, statusCode: http.StatusOK}
+		next.ServeHTTP(rec, r)
+		log.Printf("%s %s %d %s", r.Method, r.URL.Path, rec.statusCode, time.Since(start))
+	})
+}
+
+// Recoverer recovers from panics in downstream handlers and returns a 500
+// Internal Server Error response.
+func Recoverer(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer func() {
+			if err := recover(); err != nil {
+				log.Printf("panic recovered: %v\n%s", err, debug.Stack())
+				http.Error(w, `{"error":"internal server error"}`, http.StatusInternalServerError)
+			}
+		}()
+		next.ServeHTTP(w, r)
+	})
+}

web/backend/model/status.go

@@ -0,0 +1,8 @@
+package model
+
+// StatusResponse represents the response payload for the GET /api/status endpoint.
+type StatusResponse struct {
+	Status  string `json:"status"`
+	Version string `json:"version"`
+	Uptime  string `json:"uptime"`
+}

web/backend/utils.go

@@ -0,0 +1,61 @@
+package main
+
+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" +
+		colorBlue + "██████╗ ██╗ ██████╗ ██████╗ " + colorRed + " ██████╗██╗      █████╗ ██╗    ██╗\n" +
+		colorBlue + "██╔══██╗██║██╔════╝██╔═══██╗" + colorRed + "██╔════╝██║     ██╔══██╗██║    ██║\n" +
+		colorBlue + "██████╔╝██║██║     ██║   ██║" + colorRed + "██║     ██║     ███████║██║ █╗ ██║\n" +
+		colorBlue + "██╔═══╝ ██║██║     ██║   ██║" + colorRed + "██║     ██║     ██╔══██║██║███╗██║\n" +
+		colorBlue + "██║     ██║╚██████╗╚██████╔╝" + colorRed + "╚██████╗███████╗██║  ██║╚███╔███╔╝\n" +
+		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/frontend/.editorconfig

@@ -0,0 +1,7 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf

web/frontend/.gitignore

@@ -0,0 +1,26 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+.tanstack

web/frontend/.prettierignore

@@ -0,0 +1,5 @@
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+routeTree.gen.ts
+src/components/ui

web/frontend/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-vega",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "tabler",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

web/frontend/eslint.config.js

@@ -0,0 +1,31 @@
+import js from "@eslint/js"
+import eslintConfigPrettier from "eslint-config-prettier"
+import reactHooks from "eslint-plugin-react-hooks"
+import reactRefresh from "eslint-plugin-react-refresh"
+import { defineConfig, globalIgnores } from "eslint/config"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+export default defineConfig([
+  globalIgnores(["dist", "src/components/ui", "src/routeTree.gen.ts"]),
+  {
+    files: ["**/*.{ts,tsx}"],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+      eslintConfigPrettier,
+    ],
+    languageOptions: {
+      ecmaVersion: "latest",
+      globals: globals.browser,
+    },
+    rules: {
+      "react-refresh/only-export-components": [
+        "warn",
+        { allowConstantExport: true },
+      ],
+    },
+  },
+])

web/frontend/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="shortcut icon" href="/favicon.ico" />
+    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
+    <link rel="manifest" href="/site.webmanifest" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>PicoClaw</title>
+  </head>
+
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>