* delete unused file

fix(ci): normalize notary key secret for rcodesign

Revert "fix(ci): normalize notary key secret for rcodesign"

This reverts commit 34eb5acb5379a039306c04ddbdbd329de58aa9f6.

Revert "fix(ci): use official rcodesign binary in macOS workflows"

This reverts commit a81dcb4f902cdc5930895eb4aee61ff1af91cbac.

Revert "ci: parallel macOS CGO launcher build, lowercase Docker tags, conditional Docker Hub login (#2643)"

This reverts commit 9fba52d0fa.

.dockerignore

@@ -1,3 +1,5 @@
+# Do NOT exclude LICENSE or .github — scripts/copydir.go uses them as repo-root anchors
+# during `go generate`, which runs inside `make build` in the Dockerfile.
 .git
 .gitignore
 build/
@@ -6,5 +8,4 @@ config/
 .env
 .env.example
 *.md
-LICENSE
 assets/

.gitattributes

@@ -0,0 +1,3 @@
+# Ensure shell scripts always use LF line endings regardless of OS.
+*.sh text eol=lf
+docker/entrypoint.sh text eol=lf

.github/workflows/create-tag.yml

@@ -0,0 +1,60 @@
+name: Create Tag
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag name (required, e.g. v0.2.0)"
+        required: true
+        type: string
+      commit:
+        description: "Target commit SHA (leave empty for latest main)"
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  create-tag:
+    name: Create Git Tag
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: main
+
+      - name: Validate commit exists
+        if: ${{ inputs.commit != '' }}
+        shell: bash
+        run: |
+          if ! git cat-file -t "${{ inputs.commit }}" &>/dev/null; then
+            echo "::error::Commit '${{ inputs.commit }}' does not exist."
+            exit 1
+          fi
+
+      - name: Check tag does not already exist
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if gh api "repos/${{ github.repository }}/git/ref/tags/${{ inputs.tag }}" --silent 2>/dev/null; then
+            echo "::error::Tag '${{ inputs.tag }}' already exists."
+            exit 1
+          fi
+
+      - name: Create and push tag
+        shell: bash
+        run: |
+          TARGET="${{ inputs.commit || 'HEAD' }}"
+          COMMIT_SHA=$(git rev-parse "$TARGET")
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "${{ inputs.tag }}" "$COMMIT_SHA" -m "Release ${{ inputs.tag }}"
+          git push origin "${{ inputs.tag }}"
+          echo "### Tag Created" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **Tag:** \`${{ inputs.tag }}\`" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **Commit:** \`${COMMIT_SHA}\`" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **Branch:** \`$(git branch -r --contains "$COMMIT_SHA" | head -1 | xargs)\`" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/release.yml

@@ -1,10 +1,10 @@
-name: Create Tag and Release
+name: Release
 
 on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Release tag (required, e.g. v0.2.0)"
+        description: "Existing tag to release (e.g. v0.2.0)"
         required: true
         type: string
       prerelease:
@@ -24,35 +24,23 @@ on:
         default: true
 
 jobs:
-  create-tag:
-    name: Create Git Tag
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - name: Create and push tag
-        shell: bash
-        env:
-          RELEASE_TAG: ${{ inputs.tag }}
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -a "$RELEASE_TAG" -m "Release $RELEASE_TAG"
-          git push origin "$RELEASE_TAG"
-
   release:
     name: GoReleaser Release
-    needs: create-tag
     runs-on: ubuntu-latest
     permissions:
       contents: write
       packages: write
     steps:
+      - name: Verify tag exists
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if ! gh api "repos/${{ github.repository }}/git/ref/tags/${{ inputs.tag }}" --silent 2>/dev/null; then
+            echo "::error::Tag '${{ inputs.tag }}' does not exist. Create it first using the 'Create Tag' workflow."
+            exit 1
+          fi
+
       - name: Checkout tag
         uses: actions/checkout@v6
         with:

.github/workflows/stale.yml

@@ -0,0 +1,64 @@
+name: Close stale issues and PRs
+
+on:
+  schedule:
+    # Run daily at 03:00 JST (18:00 UTC)
+    - cron: "0 18 * * *"
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Mark and close stale issues and PRs
+        uses: actions/stale@v10
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+          # ── Issue: 7 days inactive → stale; 7 more days → close ──
+          days-before-issue-stale: 7
+          days-before-issue-close: 7
+          stale-issue-label: "stale"
+          stale-issue-message: >
+            This issue has had no activity for 7 days and has been marked as stale.
+            If it is still relevant, please reply or update; otherwise it will be
+            closed automatically in 7 days.
+          close-issue-message: >
+            This issue has been closed after 14 days of inactivity.
+            If it is still needed, feel free to reopen it anytime.
+          close-issue-reason: "not_planned"
+
+          # ── PR: 7 days inactive → stale; 7 more days → close ──
+          days-before-pr-stale: 7
+          days-before-pr-close: 7
+          stale-pr-label: "stale"
+          stale-pr-message: >
+            This PR has had no activity for 7 days and has been marked as stale.
+            If you are still working on it, please push an update or leave a comment;
+            otherwise it will be closed automatically in 7 days.
+          close-pr-message: >
+            This PR has been closed after 14 days of inactivity.
+            If you would like to continue, feel free to reopen it or submit a new PR.
+
+          # ── Protected labels (exempt from stale processing) ──
+          exempt-issue-labels: "pinned,keep-open,wip,do-not-close,type: roadmap"
+          exempt-pr-labels: "pinned,keep-open,wip,do-not-close,type: roadmap"
+
+          # ── Exempt draft PRs ──
+          exempt-draft-pr: true
+
+          # ── Remove stale label when activity resumes ──
+          remove-stale-when-updated: true
+          remove-issue-stale-when-updated: true
+          remove-pr-stale-when-updated: true
+
+          # ── Scan oldest items first so old stale items are not starved ──
+          ascending: true
+
+          # ── Throttle: max operations per run ──
+          operations-per-run: 500

.gitignore

@@ -55,6 +55,10 @@ dist/
 
 # Windows Application Icon/Resource
 *.syso
+.cache/
+web/frontend/.pnpm-store/
+_tmp_*
+web/frontend/_tmp_*
 
 # Test telegram integration
 cmd/telegram/

.goreleaser.yaml

@@ -100,49 +100,6 @@ builds:
       - goos: netbsd
         goarch: arm
 
-  - id: picoclaw-launcher-tui
-    binary: picoclaw-launcher-tui
-    env:
-      - CGO_ENABLED=0
-    tags:
-      - goolm
-      - stdjson
-    ldflags:
-      - -s -w
-      - -X github.com/sipeed/picoclaw/pkg/config.Version={{ .Version }}
-      - -X github.com/sipeed/picoclaw/pkg/config.GitCommit={{ .ShortCommit }}
-      - -X github.com/sipeed/picoclaw/pkg/config.BuildTime={{ .Date }}
-      - -X github.com/sipeed/picoclaw/pkg/config.GoVersion={{ with index .Env "GOVERSION" }}{{ . }}{{ else }}unknown{{ end }}
-    goos:
-      - linux
-      - windows
-      - darwin
-      - freebsd
-      - netbsd
-    goarch:
-      - amd64
-      - arm64
-      - riscv64
-      - loong64
-      - arm
-      - s390x
-      - mipsle
-    goarm:
-      - "6"
-      - "7"
-    gomips:
-      - softfloat
-    main: ./cmd/picoclaw-launcher-tui
-    ignore:
-      - goos: windows
-        goarch: arm
-      - goos: netbsd
-        goarch: s390x
-      - goos: netbsd
-        goarch: mips64
-      - goos: netbsd
-        goarch: arm
-
 dockers_v2:
   - id: picoclaw
     dockerfile: docker/Dockerfile.goreleaser
@@ -166,7 +123,6 @@ dockers_v2:
     ids:
       - picoclaw
       - picoclaw-launcher
-      - picoclaw-launcher-tui
     images:
       - "ghcr.io/{{ .Env.GITHUB_REPOSITORY_OWNER }}/picoclaw"
       - 'docker.io/{{ .Env.DOCKERHUB_IMAGE_NAME }}'
@@ -184,7 +140,6 @@ notarize:
       ids:
         - picoclaw
         - picoclaw-launcher
-        - picoclaw-launcher-tui
       sign:
         certificate: "{{.Env.MACOS_SIGN_P12}}"
         password: "{{.Env.MACOS_SIGN_PASSWORD}}"
@@ -215,7 +170,6 @@ nfpms:
     ids:
       - picoclaw
       - picoclaw-launcher
-      - picoclaw-launcher-tui
     package_name: picoclaw
     file_name_template: >-
       {{ .PackageName }}_

Makefile

@@ -7,19 +7,43 @@ CMD_DIR=cmd/$(BINARY_NAME)
 MAIN_GO=$(CMD_DIR)/main.go
 EXT=
 
+ifeq ($(OS),Windows_NT)
+	POWERSHELL=powershell -NoProfile -Command
+	WINDOWS_GOARCH_RAW:=$(strip $(shell go env GOARCH 2>NUL))
+endif
+
 # Version
-VERSION?=$(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
-GIT_COMMIT=$(shell git rev-parse --short=8 HEAD 2>/dev/null || echo "dev")
-BUILD_TIME=$(shell date +%FT%T%z)
-GO_VERSION=$(shell $(GO) version | awk '{print $$3}')
+ifeq ($(OS),Windows_NT)
+	VERSION_RAW:=$(strip $(shell git describe --tags --always --dirty 2>NUL))
+	GIT_COMMIT_RAW:=$(strip $(shell git rev-parse --short=8 HEAD 2>NUL))
+	BUILD_TIME_RAW:=$(strip $(shell powershell -NoProfile -Command "Get-Date -Format 'yyyy-MM-ddTHH:mm:ssK'"))
+	GO_VERSION_RAW:=$(strip $(shell go env GOVERSION 2>NUL))
+else
+	VERSION_RAW:=$(strip $(shell git describe --tags --always --dirty 2>/dev/null))
+	GIT_COMMIT_RAW:=$(strip $(shell git rev-parse --short=8 HEAD 2>/dev/null))
+	BUILD_TIME_RAW:=$(strip $(shell date +%FT%T%z))
+	GO_VERSION_RAW:=$(strip $(shell go env GOVERSION 2>/dev/null))
+endif
+VERSION?=$(if $(VERSION_RAW),$(VERSION_RAW),dev)
+GIT_COMMIT=$(if $(GIT_COMMIT_RAW),$(GIT_COMMIT_RAW),dev)
+BUILD_TIME=$(if $(BUILD_TIME_RAW),$(BUILD_TIME_RAW),dev)
+GO_VERSION=$(if $(GO_VERSION_RAW),$(GO_VERSION_RAW),unknown)
 CONFIG_PKG=github.com/sipeed/picoclaw/pkg/config
 LDFLAGS=-X $(CONFIG_PKG).Version=$(VERSION) -X $(CONFIG_PKG).GitCommit=$(GIT_COMMIT) -X $(CONFIG_PKG).BuildTime=$(BUILD_TIME) -X $(CONFIG_PKG).GoVersion=$(GO_VERSION) -s -w
 
 # Go variables
-GO?=CGO_ENABLED=0 go
+GO?=go
 WEB_GO?=$(GO)
+CGO_ENABLED?=0
 GO_BUILD_TAGS?=goolm,stdjson
 GOFLAGS?=-v -tags $(GO_BUILD_TAGS)
+GOCACHE?=$(CURDIR)/.cache/go-build
+GOMODCACHE?=$(CURDIR)/.cache/go-mod
+GOTOOLCHAIN?=local
+export CGO_ENABLED
+export GOCACHE
+export GOMODCACHE
+export GOTOOLCHAIN
 comma:=,
 empty:=
 space:=$(empty) $(empty)
@@ -73,8 +97,21 @@ BUILTIN_SKILLS_DIR=$(CURDIR)/skills
 LNCMD=ln -sf
 
 # OS detection
-UNAME_S?=$(shell uname -s)
-UNAME_M?=$(shell uname -m)
+ifeq ($(OS),Windows_NT)
+	UNAME_S=Windows
+	ifeq ($(WINDOWS_GOARCH_RAW),amd64)
+		UNAME_M=x86_64
+	else ifeq ($(WINDOWS_GOARCH_RAW),arm64)
+		UNAME_M=arm64
+	else ifeq ($(WINDOWS_GOARCH_RAW),386)
+		UNAME_M=x86
+	else
+		UNAME_M=$(if $(WINDOWS_GOARCH_RAW),$(WINDOWS_GOARCH_RAW),x86_64)
+	endif
+else
+	UNAME_S?=$(shell uname -s)
+	UNAME_M?=$(shell uname -m)
+endif
 
 # Platform-specific settings
 ifeq ($(UNAME_S),Linux)
@@ -122,6 +159,30 @@ else
 
 endif
 
+ifeq ($(OS),Windows_NT)
+	PLATFORM=windows
+	ifeq ($(UNAME_M),x86_64)
+		ARCH?=amd64
+	else ifeq ($(UNAME_M),arm64)
+		ARCH?=arm64
+	else
+		ARCH?=$(UNAME_M)
+	endif
+	EXT=.exe
+endif
+
+ifneq ($(strip $(GOOS)),)
+	PLATFORM:=$(GOOS)
+endif
+
+ifneq ($(strip $(GOARCH)),)
+	ARCH:=$(GOARCH)
+endif
+
+ifeq ($(PLATFORM),windows)
+	EXT=.exe
+endif
+
 BINARY_PATH=$(BUILD_DIR)/$(BINARY_NAME)-$(PLATFORM)-$(ARCH)
 
 # Default target
@@ -130,41 +191,51 @@ all: build
 ## generate: Run generate
 generate:
 	@echo "Run generate..."
+ifeq ($(OS),Windows_NT)
+	@$(POWERSHELL) "if (Test-Path -LiteralPath './$(CMD_DIR)/workspace') { Remove-Item -LiteralPath './$(CMD_DIR)/workspace' -Recurse -Force }"
+	@$(POWERSHELL) "$$env:GOOS=''; $$env:GOARCH=''; $(GO) generate ./..."
+else
 	@rm -r ./$(CMD_DIR)/workspace 2>/dev/null || true
-	@$(GO) generate ./...
+	@GOOS=$$($(GO) env GOHOSTOS) GOARCH=$$($(GO) env GOHOSTARCH) $(GO) generate ./...
+endif
 	@echo "Run generate complete"
 
 ## build: Build the picoclaw binary for current platform
 build: generate
 	@echo "Building $(BINARY_NAME)$(EXT) for $(PLATFORM)/$(ARCH)..."
+ifeq ($(OS),Windows_NT)
+	@$(POWERSHELL) "New-Item -ItemType Directory -Force -Path '$(BUILD_DIR)' | Out-Null"
+	@$(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BINARY_PATH)$(EXT) ./$(CMD_DIR)
+	@$(POWERSHELL) "Copy-Item -LiteralPath '$(BINARY_PATH)$(EXT)' -Destination '$(BUILD_DIR)/$(BINARY_NAME)$(EXT)' -Force"
+else
 	@mkdir -p $(BUILD_DIR)
-	@GOARCH=${ARCH} $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BINARY_PATH)$(EXT) ./$(CMD_DIR)
+	@GOOS=$(PLATFORM) GOARCH=$(ARCH) $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BINARY_PATH)$(EXT) ./$(CMD_DIR)
 	@echo "Build complete: $(BINARY_PATH)$(EXT)"
 	@$(LNCMD) $(BINARY_NAME)-$(PLATFORM)-$(ARCH)$(EXT) $(BUILD_DIR)/$(BINARY_NAME)$(EXT)
+endif
+	@echo "Build complete: $(BUILD_DIR)/$(BINARY_NAME)$(EXT)"
 
 ## build-launcher: Build the picoclaw-launcher (web console) binary
 build-launcher:
 	@echo "Building picoclaw-launcher for $(PLATFORM)/$(ARCH)..."
+ifeq ($(OS),Windows_NT)
+	@$(POWERSHELL) "New-Item -ItemType Directory -Force -Path '$(BUILD_DIR)' | Out-Null"
+	@$(MAKE) -C web build PLATFORM="$(PLATFORM)" ARCH="$(ARCH)" EXT="$(EXT)" OUTPUT="$(CURDIR)/$(BUILD_DIR)/picoclaw-launcher-$(PLATFORM)-$(ARCH)$(EXT)" GO_BUILD_TAGS="$(GO_BUILD_TAGS)"
+	@$(POWERSHELL) "Copy-Item -LiteralPath '$(BUILD_DIR)/picoclaw-launcher-$(PLATFORM)-$(ARCH)$(EXT)' -Destination '$(BUILD_DIR)/picoclaw-launcher$(EXT)' -Force"
+else
 	@mkdir -p $(BUILD_DIR)
-	@GOARCH=${ARCH} $(MAKE) -C web build \
+	@GOOS=$(PLATFORM) GOARCH=$(ARCH) $(MAKE) -C web build \
 		OUTPUT="$(CURDIR)/$(BUILD_DIR)/picoclaw-launcher-$(PLATFORM)-$(ARCH)$(EXT)" \
 		WEB_GO='$(WEB_GO)' \
 		GO_BUILD_TAGS='$(GO_BUILD_TAGS)' \
 		LDFLAGS='$(LDFLAGS)'
 	@$(LNCMD) picoclaw-launcher-$(PLATFORM)-$(ARCH)$(EXT) $(BUILD_DIR)/picoclaw-launcher$(EXT)
+endif
 	@echo "Build complete: $(BUILD_DIR)/picoclaw-launcher$(EXT)"
 
 build-launcher-frontend:
 	@$(MAKE) -C web build-frontend
 
-## build-launcher-tui: Build the picoclaw-launcher TUI binary
-build-launcher-tui:
-	@echo "Building picoclaw-launcher-tui for $(PLATFORM)/$(ARCH)..."
-	@mkdir -p $(BUILD_DIR)
-	@$(GO) build $(GOFLAGS) -o $(BUILD_DIR)/picoclaw-launcher-tui-$(PLATFORM)-$(ARCH) ./cmd/picoclaw-launcher-tui
-	@ln -sf picoclaw-launcher-tui-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/picoclaw-launcher-tui
-	@echo "Build complete: $(BUILD_DIR)/picoclaw-launcher-tui"
-
 ## 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)..."
@@ -290,7 +361,11 @@ uninstall-all:
 ## clean: Remove build artifacts
 clean:
 	@echo "Cleaning build artifacts..."
+ifeq ($(OS),Windows_NT)
+	@$(POWERSHELL) "if (Test-Path -LiteralPath '$(BUILD_DIR)') { Remove-Item -LiteralPath '$(BUILD_DIR)' -Recurse -Force }"
+else
 	@rm -rf $(BUILD_DIR)
+endif
 	@echo "Clean complete"
 
 ## vet: Run go vet for static analysis

README.md

@@ -291,24 +291,6 @@ After this one-time step, `picoclaw-launcher` will open normally on subsequent l
 
 </details>
 
-### 💻 TUI Launcher (Recommended for Headless / SSH)
-
-The TUI (Terminal UI) Launcher provides a full-featured terminal interface for configuration and management. Ideal for servers, Raspberry Pi, and other headless environments.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Getting started:**
-
-Use the TUI menus to: **1)** Configure a Provider -> **2)** Configure a Channel -> **3)** Start the Gateway -> **4)** Chat!
-
-For detailed TUI documentation, see [docs.picoclaw.io](https://docs.picoclaw.io).
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 
@@ -571,7 +553,20 @@ PicoClaw natively supports [MCP](https://modelcontextprotocol.io/) — connect a
 }
 ```
 
-For full MCP configuration (stdio, SSE, HTTP transports, Tool Discovery), see [Tools Configuration - MCP](docs/reference/tools_configuration.md#mcp-tool).
+You can manage common MCP setups directly from the CLI instead of editing JSON by hand:
+
+```bash
+picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
+picoclaw mcp list
+picoclaw mcp test filesystem
+```
+
+`picoclaw mcp` is a configuration manager: it updates `config.json` under `tools.mcp.servers`, but it does not keep the server process running itself.
+
+Use `picoclaw mcp edit` when you need advanced fields that are not covered by `picoclaw mcp add`.
+For example, `picoclaw mcp add` supports `--deferred` and `--env-file`, while `picoclaw mcp edit` is still useful for direct JSON editing and uncommon MCP settings.
+
+For full MCP configuration (stdio, SSE, HTTP transports, Tool Discovery), see [Tools Configuration - MCP](docs/reference/tools_configuration.md#mcp-tool). For CLI usage and examples, see [MCP Server CLI](docs/reference/mcp-cli.md).
 
 ## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network
 
@@ -591,6 +586,11 @@ Connect PicoClaw to the Agent Social Network simply by sending a single message
 | `picoclaw status`         | Show status                      |
 | `picoclaw version`        | Show version info                |
 | `picoclaw model`          | View or switch the default model |
+| `picoclaw mcp list`       | List configured MCP servers      |
+| `picoclaw mcp add ...`    | Add or update an MCP server entry |
+| `picoclaw mcp test`       | Probe a configured MCP server    |
+| `picoclaw mcp edit`       | Open config for advanced MCP editing |
+| `picoclaw mcp remove`     | Remove an MCP server entry       |
 | `picoclaw cron list`      | List all scheduled jobs          |
 | `picoclaw cron add ...`   | Add a scheduled job              |
 | `picoclaw cron disable`   | Disable a scheduled job          |
@@ -619,6 +619,7 @@ For detailed guides beyond this README:
 | [Docker & Quick Start](docs/guides/docker.md) | Docker Compose setup, Launcher/Agent modes |
 | [Chat Apps](docs/guides/chat-apps.md) | All 17+ channel setup guides |
 | [Configuration](docs/guides/configuration.md) | Environment variables, workspace layout, security sandbox |
+| [MCP Server CLI](docs/reference/mcp-cli.md) | Add, list, test, edit, and remove MCP server entries from the CLI |
 | [Scheduled Tasks and Cron Jobs](docs/reference/cron.md) | Cron schedule types, deliver modes, command gates, job storage |
 | [Providers & Models](docs/guides/providers.md) | 30+ LLM providers, model routing, model_list configuration |
 | [Spawn & Async Tasks](docs/guides/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration |

cmd/picoclaw-launcher-tui/README.md

@@ -1,69 +0,0 @@
-# Picoclaw Launcher TUI
-
-This directory contains the terminal-based TUI launcher for `picoclaw`.
-It provides a lightweight, terminal-native user interface for managing, configuring, and interacting with the core `picoclaw` engine, without requiring a web browser or graphical environment.
-
-## Architecture
-
-The TUI launcher is implemented purely in Go with no external runtime dependencies:
-* **`main.go`**: Application entry point, handles initialization and main event loop
-* **`ui/`**: TUI interface components built on tview + tcell framework:
-  - `home.go`: Main dashboard with navigation menu
-  - `schemes.go`: AI model scheme management
-  - `users.go`: User and API key management for model providers
-  - `channels.go`: Communication channel (Telegram/Discord/WeChat etc.) configuration editor
-  - `gateway.go`: PicoClaw gateway daemon lifecycle management (start/stop/status)
-  - `app.go`: Core TUI application framework and navigation logic
-  - `models.go`: Data structures and state management
-* **`config/`**: Configuration management layer, integrates with the core picoclaw configuration system
-
-## Getting Started
-
-### Prerequisites
-
-* Go 1.25+
-* Terminal with 256-color support (most modern terminals are compatible)
-
-### Development
-
-Run the TUI launcher directly in development mode:
-
-```bash
-# From project root
-go run ./cmd/picoclaw-launcher-tui
-
-# Or from this directory
-go run .
-```
-
-### Build
-
-Build the standalone TUI launcher binary:
-
-```bash
-# From project root (recommended)
-make build-launcher-tui
-
-# Output will be at:
-# build/picoclaw-launcher-tui-<platform>-<arch>
-# with symlink build/picoclaw-launcher-tui
-
-# Or build directly from this directory
-go build -o picoclaw-launcher-tui .
-```
-
-### Key Features
-
-* 🖥️ Terminal-native interface - works over SSH, on headless servers, and in low-resource environments
-* ⚙️ AI model scheme and API key management
-* 📱 Communication channel configuration editor (Telegram/Discord/WeChat etc.)
-* 🔄 PicoClaw gateway daemon management (start/stop/status monitoring)
-* 💬 One-click launch of interactive AI chat session
-* 🎯 Keyboard-first design with intuitive shortcuts
-
-### Other Commands
-
-```bash
-# Run with custom config file path
-go run . /path/to/custom/config.json
-```

cmd/picoclaw-launcher-tui/config/config.go

@@ -1,236 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-// Package config provides types and I/O for ~/.picoclaw/tui.toml.
-package config
-
-import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"os"
-	"path/filepath"
-
-	"github.com/BurntSushi/toml"
-
-	"github.com/sipeed/picoclaw/pkg/fileutil"
-)
-
-// DefaultConfigPath returns the default path to the tui.toml config file.
-func DefaultConfigPath() string {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		home = "."
-	}
-	return filepath.Join(home, ".picoclaw", "tui.toml")
-}
-
-// TUIConfig is the top-level structure of ~/.picoclaw/tui.toml.
-type TUIConfig struct {
-	Version  string   `toml:"version"`
-	Model    Model    `toml:"model"`
-	Provider Provider `toml:"provider"`
-}
-
-type Model struct {
-	Type string `toml:"type"` // "provider" (default) | "manual"
-}
-
-type Provider struct {
-	Schemes []Scheme        `toml:"schemes"`
-	Users   []User          `toml:"users"`
-	Current ProviderCurrent `toml:"current"`
-}
-
-type Scheme struct {
-	Name    string `toml:"name"`    // unique key
-	BaseURL string `toml:"baseURL"` // required
-	Type    string `toml:"type"`    // "openai-compatible" (default) | "anthropic"
-}
-
-type User struct {
-	Name   string `toml:"name"`
-	Scheme string `toml:"scheme"` // references Scheme.Name; (Name+Scheme) is unique
-	Type   string `toml:"type"`   // "key" (default) | "OAuth"
-	Key    string `toml:"key"`
-}
-
-type ProviderCurrent struct {
-	Scheme string `toml:"scheme"` // references Scheme.Name
-	User   string `toml:"user"`   // references User.Name where User.Scheme == Scheme
-	Model  string `toml:"model"`  // from GET <baseURL>/models
-}
-
-// DefaultConfig returns a minimal valid TUIConfig.
-func DefaultConfig() *TUIConfig {
-	return &TUIConfig{
-		Version: "1.0",
-		Model:   Model{Type: "provider"},
-		Provider: Provider{
-			Schemes: []Scheme{},
-			Users:   []User{},
-			Current: ProviderCurrent{},
-		},
-	}
-}
-
-// Load reads the TUI config from path. Returns a default config if the file does not exist.
-func Load(path string) (*TUIConfig, error) {
-	data, err := os.ReadFile(path)
-	if os.IsNotExist(err) {
-		return DefaultConfig(), nil
-	}
-	if err != nil {
-		return nil, fmt.Errorf("failed to read config file %q: %w", path, err)
-	}
-
-	cfg := DefaultConfig()
-	if _, err := toml.Decode(string(data), cfg); err != nil {
-		return nil, fmt.Errorf("failed to parse config file %q: %w", path, err)
-	}
-
-	applyDefaults(cfg)
-	return cfg, nil
-}
-
-// Save writes cfg to path atomically (safe for flash / SD storage).
-func Save(path string, cfg *TUIConfig) error {
-	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
-		return fmt.Errorf("failed to create config directory: %w", err)
-	}
-	var buf bytes.Buffer
-	enc := toml.NewEncoder(&buf)
-	if err := enc.Encode(cfg); err != nil {
-		return fmt.Errorf("failed to encode config: %w", err)
-	}
-	if err := fileutil.WriteFileAtomic(path, buf.Bytes(), 0o600); err != nil {
-		return fmt.Errorf("failed to write config file %q: %w", path, err)
-	}
-	return nil
-}
-
-func applyDefaults(cfg *TUIConfig) {
-	if cfg.Version == "" {
-		cfg.Version = "1.0"
-	}
-	if cfg.Model.Type == "" {
-		cfg.Model.Type = "provider"
-	}
-	for i := range cfg.Provider.Schemes {
-		if cfg.Provider.Schemes[i].Type == "" {
-			cfg.Provider.Schemes[i].Type = "openai-compatible"
-		}
-	}
-	for i := range cfg.Provider.Users {
-		if cfg.Provider.Users[i].Type == "" {
-			cfg.Provider.Users[i].Type = "key"
-		}
-	}
-}
-
-// SchemeByName returns the first Scheme whose Name matches, or nil.
-func (p *Provider) SchemeByName(name string) *Scheme {
-	for i := range p.Schemes {
-		if p.Schemes[i].Name == name {
-			return &p.Schemes[i]
-		}
-	}
-	return nil
-}
-
-// UsersForScheme returns all users whose Scheme field matches schemeName.
-func (p *Provider) UsersForScheme(schemeName string) []User {
-	var out []User
-	for _, u := range p.Users {
-		if u.Scheme == schemeName {
-			out = append(out, u)
-		}
-	}
-	return out
-}
-
-// SyncSelectedModelToMainConfig syncs the currently selected model to ~/.picoclaw/config.json
-// Adds/replaces a "tui-prefer" model entry and sets it as the default model.
-// Preserves all other existing fields in the config file unchanged.
-func SyncSelectedModelToMainConfig(scheme Scheme, user User, modelID string) error {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		home = "."
-	}
-	mainConfigPath := filepath.Join(home, ".picoclaw", "config.json")
-
-	var cfg map[string]any
-	if data, readErr := os.ReadFile(mainConfigPath); readErr == nil {
-		if unmarshalErr := json.Unmarshal(data, &cfg); unmarshalErr != nil {
-			cfg = make(map[string]any)
-		}
-	} else {
-		cfg = make(map[string]any)
-	}
-
-	if _, ok := cfg["agents"]; !ok {
-		cfg["agents"] = make(map[string]any)
-	}
-	agents, ok := cfg["agents"].(map[string]any)
-	if ok {
-		if _, ok := agents["defaults"]; !ok {
-			agents["defaults"] = make(map[string]any)
-		}
-		defaults, ok := agents["defaults"].(map[string]any)
-		if ok {
-			defaults["model"] = "tui-prefer"
-		}
-	}
-
-	tuiModel := map[string]any{
-		"model_name": "tui-prefer",
-		"model":      modelID,
-		"api_key":    user.Key,
-		"api_base":   scheme.BaseURL,
-	}
-
-	modelList := []any{}
-	if ml, ok := cfg["model_list"].([]any); ok {
-		modelList = ml
-	}
-
-	found := false
-	for i, m := range modelList {
-		if entry, ok := m.(map[string]any); ok {
-			if name, ok := entry["model_name"].(string); ok && name == "tui-prefer" {
-				modelList[i] = tuiModel
-				found = true
-				break
-			}
-		}
-	}
-	if !found {
-		modelList = append(modelList, tuiModel)
-	}
-	cfg["model_list"] = modelList
-
-	data, err := json.MarshalIndent(cfg, "", "  ")
-	if err != nil {
-		return err
-	}
-
-	if err := os.MkdirAll(filepath.Dir(mainConfigPath), 0o700); err != nil {
-		return err
-	}
-
-	return os.WriteFile(mainConfigPath, data, 0o600)
-}
-
-func (cfg *TUIConfig) CurrentModelLabel() string {
-	cur := cfg.Provider.Current
-	if cur.Model == "" {
-		return "(not configured)"
-	}
-	label := cur.Scheme
-	if label != "" {
-		label += " / "
-	}
-	return label + cur.Model
-}

cmd/picoclaw-launcher-tui/main.go

@@ -1,48 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package main
-
-import (
-	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-
-	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
-	"github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/ui"
-)
-
-func main() {
-	configPath := tuicfg.DefaultConfigPath()
-	if len(os.Args) > 1 {
-		configPath = os.Args[1]
-	}
-
-	configDir := filepath.Dir(configPath)
-	if _, err := os.Stat(configDir); os.IsNotExist(err) {
-		cmd := exec.Command("picoclaw", "onboard")
-		cmd.Stdin = os.Stdin
-		cmd.Stdout = os.Stdout
-		cmd.Stderr = os.Stderr
-		_ = cmd.Run()
-	}
-
-	cfg, err := tuicfg.Load(configPath)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "picoclaw-launcher-tui: %v\n", err)
-		os.Exit(1)
-	}
-
-	app := ui.New(cfg, configPath)
-	// Bind model selection hook to sync to main config
-	app.OnModelSelected = func(scheme tuicfg.Scheme, user tuicfg.User, modelID string) {
-		_ = tuicfg.SyncSelectedModelToMainConfig(scheme, user, modelID)
-	}
-	if err := app.Run(); err != nil {
-		fmt.Fprintf(os.Stderr, "picoclaw-launcher-tui: %v\n", err)
-		os.Exit(1)
-	}
-}

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

@@ -1,325 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"fmt"
-	"sync"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
-)
-
-// App is the root TUI application.
-type App struct {
-	tapp           *tview.Application
-	pages          *tview.Pages
-	pageStack      []string
-	cfg            *tuicfg.TUIConfig
-	configPath     string
-	pageRefreshFns map[string]func()
-	headerModelTV  *tview.TextView
-	modalOpen      map[string]bool
-
-	// OnModelSelected is called when a model is selected in the UI.
-	// Can be nil to disable.
-	OnModelSelected func(scheme tuicfg.Scheme, user tuicfg.User, modelID string)
-
-	modelCache   map[string][]modelEntry
-	modelCacheMu sync.RWMutex
-	refreshMu    sync.Mutex
-}
-
-// cacheKey returns the map key for a (scheme, user) pair.
-func cacheKey(schemeName, userName string) string {
-	return fmt.Sprintf("%s/%s", schemeName, userName)
-}
-
-// cachedModels returns a defensive copy of the cached model list for a user (may be nil).
-func (a *App) cachedModels(schemeName, userName string) []modelEntry {
-	a.modelCacheMu.RLock()
-	defer a.modelCacheMu.RUnlock()
-	entries := a.modelCache[cacheKey(schemeName, userName)]
-	return append([]modelEntry(nil), entries...)
-}
-
-// refreshModelCache fetches models for every user in the config concurrently.
-// Serialized by refreshMu so concurrent calls don't race on the cache map.
-// When all fetches complete it calls onDone via QueueUpdateDraw.
-func (a *App) refreshModelCache(onDone func()) {
-	go func() {
-		a.refreshMu.Lock()
-		defer a.refreshMu.Unlock()
-
-		users := a.cfg.Provider.Users
-		schemes := a.cfg.Provider.Schemes
-
-		schemeURL := make(map[string]string, len(schemes))
-		for _, s := range schemes {
-			schemeURL[s.Name] = s.BaseURL
-		}
-
-		var wg sync.WaitGroup
-		for _, u := range users {
-			baseURL, ok := schemeURL[u.Scheme]
-			if !ok || baseURL == "" {
-				continue
-			}
-			if u.Key == "" {
-				a.modelCacheMu.Lock()
-				if a.modelCache == nil {
-					a.modelCache = make(map[string][]modelEntry)
-				}
-				a.modelCache[cacheKey(u.Scheme, u.Name)] = nil
-				a.modelCacheMu.Unlock()
-				continue
-			}
-			wg.Add(1)
-			bURL := baseURL
-			go func() {
-				defer wg.Done()
-				entries, err := fetchModels(bURL, u.Key)
-				a.modelCacheMu.Lock()
-				if a.modelCache == nil {
-					a.modelCache = make(map[string][]modelEntry)
-				}
-				if err != nil || len(entries) == 0 {
-					a.modelCache[cacheKey(u.Scheme, u.Name)] = nil
-				} else {
-					a.modelCache[cacheKey(u.Scheme, u.Name)] = entries
-				}
-				a.modelCacheMu.Unlock()
-			}()
-		}
-		wg.Wait()
-
-		if onDone != nil {
-			a.tapp.QueueUpdateDraw(onDone)
-		}
-	}()
-}
-
-// New creates and wires up the TUI application.
-func New(cfg *tuicfg.TUIConfig, configPath string) *App {
-	// Cyberpunk Theme Colors
-	// Dark background
-	tview.Styles.PrimitiveBackgroundColor = tcell.NewHexColor(0x050510) // Deep Void
-	tview.Styles.ContrastBackgroundColor = tcell.NewHexColor(0x1a1a2e)  // Dark Indigo
-	tview.Styles.MoreContrastBackgroundColor = tcell.NewHexColor(0x2a2a40)
-
-	// Borders and Titles
-	tview.Styles.BorderColor = tcell.NewHexColor(0x00f0ff)   // Neon Cyan
-	tview.Styles.TitleColor = tcell.NewHexColor(0x00f0ff)    // Neon Cyan
-	tview.Styles.GraphicsColor = tcell.NewHexColor(0xff00ff) // Neon Magenta
-
-	// Text
-	tview.Styles.PrimaryTextColor = tcell.NewHexColor(0xe0e0e0)           // Off-white
-	tview.Styles.SecondaryTextColor = tcell.NewHexColor(0x00f0ff)         // Neon Cyan
-	tview.Styles.TertiaryTextColor = tcell.NewHexColor(0x39ff14)          // Neon Lime
-	tview.Styles.InverseTextColor = tcell.NewHexColor(0x000000)           // Black
-	tview.Styles.ContrastSecondaryTextColor = tcell.NewHexColor(0xff00ff) // Neon Magenta
-
-	a := &App{
-		tapp:           tview.NewApplication(),
-		pages:          tview.NewPages(),
-		pageStack:      []string{},
-		cfg:            cfg,
-		configPath:     configPath,
-		pageRefreshFns: make(map[string]func()),
-		modalOpen:      make(map[string]bool),
-	}
-
-	a.tapp.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			if len(a.modalOpen) > 0 {
-				return event
-			}
-			return a.goBack()
-		}
-		return event
-	})
-
-	a.buildPages()
-	return a
-}
-
-// Run starts the TUI event loop.
-func (a *App) Run() error {
-	return a.tapp.SetRoot(a.pages, true).EnableMouse(true).Run()
-}
-
-func (a *App) buildPages() {
-	a.pages.AddPage("home", a.newHomePage(), true, true)
-	a.pageStack = []string{"home"}
-}
-
-func (a *App) navigateTo(name string, page tview.Primitive) {
-	a.pages.RemovePage(name)
-	a.pages.AddPage(name, page, true, false)
-	a.pageStack = append(a.pageStack, name)
-	a.pages.SwitchToPage(name)
-}
-
-func (a *App) goBack() *tcell.EventKey {
-	if len(a.pageStack) <= 1 {
-		return nil
-	}
-	popped := a.pageStack[len(a.pageStack)-1]
-	a.pageStack = a.pageStack[:len(a.pageStack)-1]
-	a.pages.RemovePage(popped)
-	prev := a.pageStack[len(a.pageStack)-1]
-	if fn, ok := a.pageRefreshFns[prev]; ok {
-		fn()
-	}
-	if prev == "home" && a.headerModelTV != nil {
-		a.headerModelTV.SetText(a.cfg.CurrentModelLabel() + "  ")
-	}
-	a.pages.SwitchToPage(prev)
-	return nil
-}
-
-func (a *App) showModal(name string, primitive tview.Primitive) {
-	a.modalOpen[name] = true
-	a.pages.AddPage(name, primitive, true, true)
-}
-
-func (a *App) hideModal(name string) {
-	delete(a.modalOpen, name)
-	a.pages.HidePage(name)
-	a.pages.RemovePage(name)
-}
-
-func (a *App) save() {
-	if err := tuicfg.Save(a.configPath, a.cfg); err != nil {
-		a.showError("save failed: " + err.Error())
-	}
-}
-
-func (a *App) showError(msg string) {
-	modal := tview.NewModal().
-		SetText(" [red::b]ERROR[-::-]\n\n" + msg).
-		AddButtons([]string{"OK"}).
-		SetDoneFunc(func(_ int, _ string) {
-			a.hideModal("error")
-		})
-	// Cyberpunk Modal Style
-	modal.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))       // Deep Indigo
-	modal.SetTextColor(tcell.NewHexColor(0xffffff))             // White
-	modal.SetButtonBackgroundColor(tcell.NewHexColor(0xff2a2a)) // Neon Red
-	modal.SetButtonTextColor(tcell.NewHexColor(0xffffff))       // White
-	a.showModal("error", modal)
-}
-
-func (a *App) confirmDelete(label string, onConfirm func()) {
-	modal := tview.NewModal().
-		SetText(" [red::b]DELETE WARNING[-::-]\n\nDelete " + label + "?\n[gray]This action cannot be undone.[-]").
-		AddButtons([]string{"Delete", "Cancel"}).
-		SetDoneFunc(func(_ int, buttonLabel string) {
-			a.hideModal("confirm-delete")
-			if buttonLabel == "Delete" {
-				onConfirm()
-			}
-		})
-	// Cyberpunk Modal Style
-	modal.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))       // Deep Indigo
-	modal.SetTextColor(tcell.NewHexColor(0xffffff))             // White
-	modal.SetButtonBackgroundColor(tcell.NewHexColor(0xff2a2a)) // Neon Red for danger
-	modal.SetButtonTextColor(tcell.NewHexColor(0xffffff))       // White
-	a.showModal("confirm-delete", modal)
-}
-
-func centeredForm(form *tview.Form, widthPct, height int) tview.Primitive {
-	return tview.NewFlex().
-		AddItem(tview.NewBox(), 0, 1, false).
-		AddItem(tview.NewFlex().SetDirection(tview.FlexRow).
-			AddItem(tview.NewBox(), 0, 1, false).
-			AddItem(form, height, 1, true).
-			AddItem(tview.NewBox(), 0, 1, false), 0, widthPct, true).
-		AddItem(tview.NewBox(), 0, 1, false)
-}
-
-func hintBar(text string) *tview.TextView {
-	tv := tview.NewTextView().
-		SetText(text).
-		SetDynamicColors(true).
-		SetTextAlign(tview.AlignCenter).
-		SetTextColor(tcell.NewHexColor(0x00f0ff)) // Neon Cyan
-	tv.SetBackgroundColor(tcell.NewHexColor(0x2a2a40)) // Darker Indigo
-	return tv
-}
-
-func (a *App) buildShell(pageID string, content tview.Primitive, hint string) tview.Primitive {
-	var modelTV *tview.TextView
-	if pageID == "home" {
-		if a.headerModelTV == nil {
-			a.headerModelTV = tview.NewTextView()
-			a.headerModelTV.SetTextAlign(tview.AlignRight).
-				SetTextColor(tcell.NewHexColor(0x39ff14)). // Neon Lime
-				SetDynamicColors(true).
-				SetBackgroundColor(tcell.NewHexColor(0x050510))
-		}
-		modelTV = a.headerModelTV
-		modelTV.SetText("MODEL: " + a.cfg.CurrentModelLabel() + " ")
-	} else {
-		modelTV = tview.NewTextView()
-		modelTV.SetBackgroundColor(tcell.NewHexColor(0x050510))
-	}
-
-	headerLeft := tview.NewTextView().
-		SetText(" [#ff00ff::b]///[#00f0ff] PICOCLAW LAUNCHER [#ff00ff]///").
-		SetDynamicColors(true).
-		SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	header := tview.NewFlex().
-		AddItem(headerLeft, 0, 1, false).
-		AddItem(modelTV, 0, 1, false)
-
-	sidebar := tview.NewTextView().
-		SetDynamicColors(true).
-		SetWrap(false)
-	sidebar.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e)) // Deep Indigo
-
-	// Cyberpunk Sidebar Styling
-	activePrefix := "[#39ff14::b]>> " // Neon Lime arrow
-	activeSuffix := "[-]"
-	inactivePrefix := "[#808080]   "
-	inactiveSuffix := "[-]"
-
-	sbText := "\n\n" // Top padding
-
-	menuItem := func(id, label string) string {
-		if pageID == id {
-			return activePrefix + label + activeSuffix + "\n\n"
-		}
-		return inactivePrefix + label + inactiveSuffix + "\n\n"
-	}
-
-	sbText += menuItem("home", "HOME")
-	sbText += menuItem("schemes", "SCHEMES")
-	sbText += menuItem("users", "USERS")
-	sbText += menuItem("models", "MODELS")
-	sbText += menuItem("channels", "CHANNELS")
-	sbText += menuItem("gateway", "GATEWAY")
-
-	sidebar.SetText(sbText)
-
-	footer := hintBar(hint)
-
-	grid := tview.NewGrid().
-		SetRows(1, 0, 1).
-		SetColumns(20, 0). // Slightly wider sidebar
-		AddItem(header, 0, 0, 1, 2, 0, 0, false).
-		AddItem(sidebar, 1, 0, 1, 1, 0, 0, false).
-		AddItem(content, 1, 1, 1, 1, 0, 0, true).
-		AddItem(footer, 2, 0, 1, 2, 0, 0, false)
-
-	// Add a border around the content area if possible, or ensure content has its own border
-	// grid.SetBorders(false) // Grid borders usually look bad, handled by components
-
-	return grid
-}

cmd/picoclaw-launcher-tui/ui/channels.go

@@ -1,202 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-	"path/filepath"
-	"reflect"
-	"strconv"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-)
-
-func (a *App) newChannelsPage() tview.Primitive {
-	list := tview.NewList()
-	list.SetBorder(true).
-		SetTitle(" [#00f0ff::b] COMMUNICATION CHANNELS ").
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	list.SetMainTextColor(tcell.NewHexColor(0xe0e0e0))
-	list.SetSecondaryTextColor(tcell.NewHexColor(0x808080))
-	list.SetSelectedStyle(
-		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0x050510)),
-	)
-	list.SetHighlightFullLine(true)
-	list.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	rebuild := func() {
-		sel := list.GetCurrentItem()
-		list.Clear()
-
-		home, err := os.UserHomeDir()
-		if err != nil {
-			home = "."
-		}
-		configPath := filepath.Join(home, ".picoclaw", "config.json")
-
-		var cfg map[string]any
-		if data, err := os.ReadFile(configPath); err == nil {
-			_ = json.Unmarshal(data, &cfg)
-		}
-
-		if chRaw, ok := cfg["channels"].(map[string]any); ok {
-			for name, ch := range chRaw {
-				chMap, ok := ch.(map[string]any)
-				enabled := "disabled"
-				if ok {
-					if e, ok := chMap["enabled"].(bool); ok && e {
-						enabled = "enabled"
-					}
-				}
-				list.AddItem(name, fmt.Sprintf("Status: %s", enabled), 0, func() {
-					a.showChannelEditForm(configPath, name, chMap)
-				})
-			}
-		}
-
-		if sel >= 0 && sel < list.GetItemCount() {
-			list.SetCurrentItem(sel)
-		}
-	}
-	rebuild()
-
-	a.pageRefreshFns["channels"] = rebuild
-
-	list.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			return a.goBack()
-		}
-		return event
-	})
-
-	return a.buildShell("channels", list, " [#ff00ff]Enter:[-] edit  [#ff2a2a]ESC:[-] back ")
-}
-
-func (a *App) showChannelEditForm(configPath, channelName string, existing map[string]any) {
-	form := tview.NewForm()
-	form.SetBorder(true).
-		SetTitle(" [::b]EDIT CHANNEL ").
-		SetTitleColor(tcell.NewHexColor(0x39ff14)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
-	form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
-	form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
-	form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
-	form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
-	form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
-
-	fields := make(map[string]*tview.InputField)
-	var nameField *tview.InputField
-
-	if channelName == "" {
-		nameField = tview.NewInputField().
-			SetLabel("Channel Name").
-			SetText("").
-			SetFieldWidth(28)
-		form.AddFormItem(nameField)
-	}
-
-	for k, v := range existing {
-		if reflect.ValueOf(v).Kind() == reflect.Map || reflect.ValueOf(v).Kind() == reflect.Slice {
-			continue
-		}
-		valStr := fmt.Sprintf("%v", v)
-		field := tview.NewInputField().
-			SetLabel(k).
-			SetText(valStr).
-			SetFieldWidth(28)
-		form.AddFormItem(field)
-		fields[k] = field
-	}
-
-	form.AddButton("SAVE", func() {
-		var cfg map[string]any
-		if data, err := os.ReadFile(configPath); err == nil {
-			if err := json.Unmarshal(data, &cfg); err != nil {
-				cfg = make(map[string]any)
-			}
-		} else {
-			cfg = make(map[string]any)
-		}
-
-		if _, ok := cfg["channels"]; !ok {
-			cfg["channels"] = make(map[string]any)
-		}
-		channels, ok := cfg["channels"].(map[string]any)
-		if !ok {
-			channels = make(map[string]any)
-			cfg["channels"] = channels
-		}
-
-		finalName := channelName
-		if channelName == "" {
-			if nameField == nil || nameField.GetText() == "" {
-				a.showError("Channel name is required")
-				return
-			}
-			finalName = nameField.GetText()
-		}
-
-		updated := make(map[string]any)
-		if existing != nil {
-			for k, v := range existing {
-				updated[k] = v
-			}
-		}
-		for k, field := range fields {
-			val := field.GetText()
-			if val == "true" {
-				updated[k] = true
-			} else if val == "false" {
-				updated[k] = false
-			} else if num, err := strconv.Atoi(val); err == nil {
-				updated[k] = num
-			} else {
-				updated[k] = val
-			}
-		}
-
-		if channelName != "" && finalName != channelName {
-			delete(channels, channelName)
-		}
-		channels[finalName] = updated
-
-		data, err := json.MarshalIndent(cfg, "", "  ")
-		if err != nil {
-			a.showError(fmt.Sprintf("Failed to save config: %v", err))
-			return
-		}
-		if err := os.MkdirAll(filepath.Dir(configPath), 0o700); err != nil {
-			a.showError(fmt.Sprintf("Failed to create config directory: %v", err))
-			return
-		}
-		if err := os.WriteFile(configPath, data, 0o600); err != nil {
-			a.showError(fmt.Sprintf("Failed to write config: %v", err))
-			return
-		}
-
-		a.hideModal("channel-edit")
-		a.goBack()
-	})
-
-	form.AddButton("CANCEL", func() {
-		a.hideModal("channel-edit")
-	})
-
-	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			a.hideModal("channel-edit")
-			return nil
-		}
-		return event
-	})
-
-	a.showModal("channel-edit", centeredForm(form, 4, 20))
-}

cmd/picoclaw-launcher-tui/ui/gateway.go

@@ -1,229 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"fmt"
-	"os/exec"
-	"runtime"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	"github.com/sipeed/picoclaw/pkg/config"
-	ppid "github.com/sipeed/picoclaw/pkg/pid"
-)
-
-type gatewayStatus struct {
-	running bool
-	pid     int
-	version string
-}
-
-func picoHome() string {
-	return config.GetHome()
-}
-
-func getGatewayStatus() gatewayStatus {
-	data := ppid.ReadPidFileWithCheck(picoHome())
-	if data == nil {
-		return gatewayStatus{running: false}
-	}
-	return gatewayStatus{
-		running: true,
-		pid:     data.PID,
-		version: data.Version,
-	}
-}
-
-func startGateway() error {
-	status := getGatewayStatus()
-	if status.running {
-		return fmt.Errorf("gateway is already running (PID: %d)", status.pid)
-	}
-
-	var cmd *exec.Cmd
-
-	if runtime.GOOS == "windows" {
-		cmd = exec.Command("cmd", "/C", "start /B picoclaw gateway > NUL 2>&1")
-	} else {
-		cmd = exec.Command("sh", "-c", "nohup picoclaw gateway > /dev/null 2>&1 &")
-	}
-
-	err := cmd.Start()
-	if err != nil {
-		return err
-	}
-
-	time.Sleep(1 * time.Second)
-
-	if runtime.GOOS == "windows" {
-		cmd := exec.Command(
-			"wmic",
-			"process",
-			"where",
-			"name='picoclaw.exe' and commandline like '%gateway%'",
-			"get",
-			"processid",
-		)
-		output, err := cmd.Output()
-		if err != nil {
-			return fmt.Errorf("failed to get gateway PID: %w", err)
-		}
-		lines := strings.Split(string(output), "\n")
-		for _, line := range lines[1:] {
-			line = strings.TrimSpace(line)
-			if line == "" {
-				continue
-			}
-			_, err := strconv.Atoi(line)
-			if err == nil {
-				break
-			}
-		}
-	}
-
-	status = getGatewayStatus()
-	if !status.running {
-		return fmt.Errorf("failed to start gateway")
-	}
-	return nil
-}
-
-func stopGateway() error {
-	status := getGatewayStatus()
-	if !status.running {
-		return fmt.Errorf("gateway is not running")
-	}
-
-	var err error
-	if runtime.GOOS == "windows" {
-		err = exec.Command("taskkill", "/F", "/PID", strconv.Itoa(status.pid)).Run()
-	} else {
-		err = exec.Command("kill", strconv.Itoa(status.pid)).Run()
-	}
-	if err != nil {
-		return err
-	}
-
-	// Wait for process to stop (ReadPidFileWithCheck cleans up stale pid file)
-	for i := 0; i < 5; i++ {
-		if !getGatewayStatus().running {
-			break
-		}
-		time.Sleep(200 * time.Millisecond)
-	}
-
-	return nil
-}
-
-func (a *App) newGatewayPage() tview.Primitive {
-	flex := tview.NewFlex().SetDirection(tview.FlexRow)
-	flex.SetBorder(true).
-		SetTitle(" [#00f0ff::b] GATEWAY MANAGEMENT ").
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	flex.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	statusTV := tview.NewTextView().
-		SetDynamicColors(true).
-		SetTextAlign(tview.AlignCenter).
-		SetText("Checking status...")
-	statusTV.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	var updateStatus func()
-
-	// 使用List作为按钮，保证显示和交互正常
-	buttons := tview.NewList()
-	buttons.SetBackgroundColor(tcell.NewHexColor(0x050510))
-	buttons.SetMainTextColor(tcell.ColorWhite)
-	buttons.SetSelectedBackgroundColor(tcell.NewHexColor(0xff00ff))
-	buttons.SetSelectedTextColor(tcell.ColorBlack)
-
-	buttons.AddItem(" [lime]START[white]   ", "", 0, func() {
-		if !getGatewayStatus().running {
-			err := startGateway()
-			if err != nil {
-				a.showError(err.Error())
-			}
-			updateStatus()
-		}
-	})
-	buttons.AddItem(" [red]STOP[white]    ", "", 0, func() {
-		if getGatewayStatus().running {
-			err := stopGateway()
-			if err != nil {
-				a.showError(err.Error())
-			}
-			updateStatus()
-		}
-	})
-
-	buttonFlex := tview.NewFlex().SetDirection(tview.FlexColumn)
-	buttonFlex.
-		AddItem(tview.NewBox(), 0, 1, false).
-		AddItem(buttons, 20, 1, true).
-		AddItem(tview.NewBox(), 0, 1, false)
-
-	flex.
-		AddItem(tview.NewBox(), 0, 1, false).
-		AddItem(statusTV, 3, 1, false).
-		AddItem(tview.NewBox(), 0, 1, false).
-		AddItem(buttonFlex, 4, 1, true).
-		AddItem(tview.NewBox(), 0, 1, false)
-
-	updateStatus = func() {
-		status := getGatewayStatus()
-		if status.running {
-			versionInfo := ""
-			if status.version != "" {
-				versionInfo = fmt.Sprintf("\nVersion: %s", status.version)
-			}
-			statusTV.SetText(fmt.Sprintf("[#39ff14::b]GATEWAY RUNNING[-]\n\nPID: %d%s", status.pid, versionInfo))
-			buttons.SetItemText(0, " [gray]START[white]   ", "")
-			buttons.SetItemText(1, " [red]STOP[white]    ", "")
-		} else {
-			statusTV.SetText("[#ff2a2a::b]GATEWAY STOPPED[-]\n\nPID: N/A")
-			buttons.SetItemText(0, " [lime]START[white]   ", "")
-			buttons.SetItemText(1, " [gray]STOP[white]    ", "")
-		}
-	}
-
-	updateStatus()
-
-	done := make(chan struct{})
-	go func() {
-		ticker := time.NewTicker(2 * time.Second)
-		defer ticker.Stop()
-		for {
-			select {
-			case <-ticker.C:
-				a.tapp.QueueUpdateDraw(updateStatus)
-			case <-done:
-				return
-			}
-		}
-	}()
-
-	originalInputCapture := flex.GetInputCapture()
-	flex.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			close(done)
-			return a.goBack()
-		}
-		if originalInputCapture != nil {
-			return originalInputCapture(event)
-		}
-		return event
-	})
-
-	a.pageRefreshFns["gateway"] = updateStatus
-
-	return a.buildShell("gateway", flex, " [#39ff14]Enter:[-] select  [#ff2a2a]ESC:[-] back ")
-}

cmd/picoclaw-launcher-tui/ui/home.go

@@ -1,70 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"os"
-	"os/exec"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-)
-
-func (a *App) newHomePage() tview.Primitive {
-	list := tview.NewList()
-	list.SetBorder(true).
-		SetTitle(" [#00f0ff::b] ACTIVE CONFIGURATION ").
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	list.SetMainTextColor(tcell.NewHexColor(0xe0e0e0))
-	list.SetSecondaryTextColor(tcell.NewHexColor(0x808080))
-	list.SetSelectedStyle(
-		tcell.StyleDefault.Background(tcell.NewHexColor(0x39ff14)).Foreground(tcell.NewHexColor(0x050510)),
-	)
-	list.SetHighlightFullLine(true)
-	list.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	rebuildList := func() {
-		sel := list.GetCurrentItem()
-		list.Clear()
-		list.AddItem("MODEL: "+a.cfg.CurrentModelLabel(), "Select to configure AI model", 'm', func() {
-			a.navigateTo("schemes", a.newSchemesPage())
-		})
-		list.AddItem(
-			"CHANNELS: Configure communication channels",
-			"Manage Telegram/Discord/WeChat channels",
-			'n',
-			func() {
-				a.navigateTo("channels", a.newChannelsPage())
-			},
-		)
-		list.AddItem("GATEWAY MANAGEMENT", "Manage PicoClaw gateway daemon", 'g', func() {
-			a.navigateTo("gateway", a.newGatewayPage())
-		})
-		list.AddItem("CHAT: Start AI agent chat", "Launch interactive chat session", 'c', func() {
-			a.tapp.Suspend(func() {
-				cmd := exec.Command("picoclaw", "agent")
-				cmd.Stdin = os.Stdin
-				cmd.Stdout = os.Stdout
-				cmd.Stderr = os.Stderr
-				_ = cmd.Run()
-			})
-		})
-		list.AddItem("QUIT SYSTEM", "Exit PicoClaw Launcher", 'q', func() { a.tapp.Stop() })
-		if sel >= 0 && sel < list.GetItemCount() {
-			list.SetCurrentItem(sel)
-		}
-	}
-	rebuildList()
-
-	a.pageRefreshFns["home"] = rebuildList
-
-	return a.buildShell(
-		"home",
-		list,
-		" [#00f0ff]m:[-] model  [#00f0ff]n:[-] channels  [#00f0ff]g:[-] gateway  [#00f0ff]c:[-] chat  [#ff2a2a]q:[-] quit ",
-	)
-}

cmd/picoclaw-launcher-tui/ui/models.go

@@ -1,200 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-	"time"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
-)
-
-type modelsAPIResponse struct {
-	Data []modelEntry `json:"data"`
-}
-
-type modelEntry struct {
-	ID          string `json:"id"`
-	Name        string `json:"name"`
-	Description string `json:"description"`
-}
-
-func (a *App) newModelsPage(schemeName, userName, baseURL string) tview.Primitive {
-	table := tview.NewTable().
-		SetBorders(false).
-		SetSelectable(true, false).
-		SetFixed(0, 0)
-	table.SetBorder(true).
-		SetTitle(fmt.Sprintf(" [#00f0ff::b] MODELS · %s / %s ", schemeName, userName)).
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	table.SetSelectedStyle(
-		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
-	)
-	table.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	var modelIDs []string
-
-	status := tview.NewTextView().
-		SetTextAlign(tview.AlignCenter).
-		SetDynamicColors(true).
-		SetText("[#ffff00]FETCHING MODELS...[-]")
-	status.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	flex := tview.NewFlex().
-		SetDirection(tview.FlexRow).
-		AddItem(status, 1, 0, false).
-		AddItem(table, 0, 1, false)
-
-	apiKey := a.resolveKey(schemeName, userName)
-
-	go func() {
-		var entries []modelEntry
-		var err error
-		if apiKey == "" {
-			err = fmt.Errorf("key is required")
-		} else {
-			entries, err = fetchModels(baseURL, apiKey)
-		}
-
-		a.modelCacheMu.Lock()
-		if a.modelCache == nil {
-			a.modelCache = make(map[string][]modelEntry)
-		}
-		if err == nil && len(entries) > 0 {
-			a.modelCache[cacheKey(schemeName, userName)] = entries
-		} else {
-			a.modelCache[cacheKey(schemeName, userName)] = nil
-		}
-		a.modelCacheMu.Unlock()
-
-		a.tapp.QueueUpdateDraw(func() {
-			if err != nil {
-				status.SetText(fmt.Sprintf("[#ff2a2a]ERROR: %s[-]", err.Error()))
-				table.SetCell(0, 0, tview.NewTableCell(" (failed to load models)"))
-				a.tapp.SetFocus(table)
-				return
-			}
-			if len(entries) == 0 {
-				status.SetText("[#ff2a2a]NO MODELS RETURNED[-]")
-				table.SetCell(0, 0, tview.NewTableCell(" (no models available)"))
-				a.tapp.SetFocus(table)
-				return
-			}
-
-			status.SetText(fmt.Sprintf("[#39ff14]%d MODEL(S) LOADED[-]", len(entries)))
-			for i, m := range entries {
-				modelIDs = append(modelIDs, m.ID)
-				table.SetCell(i, 0,
-					tview.NewTableCell(fmt.Sprintf("%3d", i+1)).
-						SetAlign(tview.AlignRight).
-						SetTextColor(tcell.NewHexColor(0x808080)).
-						SetSelectable(false),
-				)
-				table.SetCell(i, 1,
-					tview.NewTableCell(" "+m.ID).
-						SetAlign(tview.AlignLeft).
-						SetExpansion(1).
-						SetTextColor(tcell.NewHexColor(0xe0e0e0)),
-				)
-			}
-			a.tapp.SetFocus(table)
-		})
-	}()
-
-	table.SetSelectedFunc(func(row, _ int) {
-		if row < 0 || row >= len(modelIDs) {
-			return
-		}
-		a.cfg.Provider.Current = tuicfg.ProviderCurrent{
-			Scheme: schemeName,
-			User:   userName,
-			Model:  modelIDs[row],
-		}
-		a.save()
-
-		// Trigger model selected callback if set
-		if a.OnModelSelected != nil && a.cfg.Model.Type == "provider" {
-			scheme := a.cfg.Provider.SchemeByName(schemeName)
-			if scheme == nil {
-				a.goBack()
-				return
-			}
-			var user tuicfg.User
-			for _, u := range a.cfg.Provider.Users {
-				if u.Scheme == schemeName && u.Name == userName {
-					user = u
-					break
-				}
-			}
-			a.OnModelSelected(*scheme, user, modelIDs[row])
-		}
-
-		a.goBack()
-	})
-
-	return a.buildShell("models", flex, " [#39ff14]Enter:[-] select  [#ff00ff]ESC:[-] back ")
-}
-
-func (a *App) resolveKey(schemeName, userName string) string {
-	for _, u := range a.cfg.Provider.Users {
-		if u.Scheme == schemeName && u.Name == userName {
-			return u.Key
-		}
-	}
-	return ""
-}
-
-func fetchModels(baseURL, apiKey string) ([]modelEntry, error) {
-	url := strings.TrimRight(baseURL, "/") + "/models"
-
-	client := &http.Client{Timeout: 15 * time.Second}
-	req, err := http.NewRequest(http.MethodGet, url, nil)
-	if err != nil {
-		return nil, fmt.Errorf("build request: %w", err)
-	}
-	if apiKey != "" {
-		req.Header.Set("Authorization", "Bearer "+apiKey)
-	}
-
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("request failed: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
-		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return nil, fmt.Errorf("read response: %w", err)
-	}
-
-	var result modelsAPIResponse
-	if err := json.Unmarshal(body, &result); err == nil && len(result.Data) > 0 {
-		return result.Data, nil
-	}
-
-	var arr []modelEntry
-	if err := json.Unmarshal(body, &arr); err == nil {
-		return arr, nil
-	}
-
-	return nil, fmt.Errorf(
-		"decode response: unrecognized shape: %s",
-		strings.TrimSpace(string(body[:min(len(body), 256)])),
-	)
-}

cmd/picoclaw-launcher-tui/ui/schemes.go

@@ -1,252 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"fmt"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
-)
-
-func (a *App) newSchemesPage() tview.Primitive {
-	table := tview.NewTable().
-		SetBorders(false).
-		SetSelectable(true, false)
-	table.SetBorder(true).
-		SetTitle(" [#00f0ff::b] PROVIDER SCHEMES ").
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	table.SetSelectedStyle(
-		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
-	)
-	table.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	rowToIdx := func(row int) int { return row / 2 }
-
-	selectedSchemeName := func() string {
-		row, _ := table.GetSelection()
-		idx := rowToIdx(row)
-		schemes := a.cfg.Provider.Schemes
-		if idx >= 0 && idx < len(schemes) {
-			return schemes[idx].Name
-		}
-		return ""
-	}
-
-	rebuild := func() {
-		selName := selectedSchemeName()
-		table.Clear()
-		schemes := a.cfg.Provider.Schemes
-		for i, s := range schemes {
-			nameRow := i * 2
-			detailRow := nameRow + 1
-
-			table.SetCell(nameRow, 0,
-				tview.NewTableCell(" "+s.Name).
-					SetTextColor(tcell.NewHexColor(0xe0e0e0)).
-					SetExpansion(1).
-					SetSelectable(true),
-			)
-
-			users := a.cfg.Provider.UsersForScheme(s.Name)
-			n := len(users)
-			m := 0
-			for _, u := range users {
-				if models := a.cachedModels(s.Name, u.Name); len(models) > 0 {
-					m++
-				}
-			}
-			table.SetCell(detailRow, 0,
-				tview.NewTableCell(fmt.Sprintf("  [#808080](%d/%d) %s", m, n, s.BaseURL)).
-					SetTextColor(tcell.NewHexColor(0x808080)).
-					SetExpansion(1).
-					SetSelectable(false),
-			)
-			table.SetCell(detailRow, 1,
-				tview.NewTableCell("[#00f0ff]"+s.Type+"  ").
-					SetAlign(tview.AlignRight).
-					SetSelectable(false),
-			)
-		}
-		if selName != "" {
-			for i, s := range schemes {
-				if s.Name == selName {
-					table.Select(i*2, 0)
-					return
-				}
-			}
-		}
-		if table.GetRowCount() > 0 {
-			table.Select(0, 0)
-		}
-	}
-	rebuild()
-
-	a.refreshModelCache(rebuild)
-	a.pageRefreshFns["schemes"] = func() { a.refreshModelCache(rebuild) }
-
-	table.SetSelectedFunc(func(row, _ int) {
-		idx := rowToIdx(row)
-		schemes := a.cfg.Provider.Schemes
-		if idx < 0 || idx >= len(schemes) {
-			return
-		}
-		name := schemes[idx].Name
-		a.navigateTo("users", a.newUsersPage(name))
-	})
-
-	table.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		row, _ := table.GetSelection()
-		idx := rowToIdx(row)
-		schemes := a.cfg.Provider.Schemes
-		switch event.Rune() {
-		case 'a':
-			a.showSchemeForm(nil, func(s tuicfg.Scheme) {
-				a.cfg.Provider.Schemes = append(a.cfg.Provider.Schemes, s)
-				a.save()
-				a.refreshModelCache(rebuild)
-			})
-			return nil
-		case 'e':
-			if idx < 0 || idx >= len(schemes) {
-				return nil
-			}
-			origName := schemes[idx].Name
-			orig := schemes[idx]
-			a.showSchemeForm(&orig, func(s tuicfg.Scheme) {
-				current := a.cfg.Provider.Schemes
-				for i, sc := range current {
-					if sc.Name == origName {
-						a.cfg.Provider.Schemes[i] = s
-						break
-					}
-				}
-				a.save()
-				a.refreshModelCache(func() {
-					rebuild()
-					for i, sc := range a.cfg.Provider.Schemes {
-						if sc.Name == s.Name {
-							table.Select(i*2, 0)
-							break
-						}
-					}
-				})
-			})
-			return nil
-		case 'd':
-			if idx < 0 || idx >= len(schemes) {
-				return nil
-			}
-			name := schemes[idx].Name
-			a.confirmDelete(fmt.Sprintf("scheme %q", name), func() {
-				current := a.cfg.Provider.Schemes
-				newSchemes := make([]tuicfg.Scheme, 0, len(current))
-				for _, sc := range current {
-					if sc.Name != name {
-						newSchemes = append(newSchemes, sc)
-					}
-				}
-				a.cfg.Provider.Schemes = newSchemes
-
-				existing := a.cfg.Provider.Users
-				filtered := make([]tuicfg.User, 0, len(existing))
-				for _, u := range existing {
-					if u.Scheme != name {
-						filtered = append(filtered, u)
-					}
-				}
-				a.cfg.Provider.Users = filtered
-
-				a.save()
-				a.refreshModelCache(rebuild)
-			})
-			return nil
-		}
-		return event
-	})
-
-	return a.buildShell(
-		"schemes",
-		table,
-		" [#00f0ff]a:[-] add  [#00f0ff]e:[-] edit  [#ff2a2a]d:[-] delete  [#39ff14]Enter:[-] open  [#ff00ff]ESC:[-] back ",
-	)
-}
-
-func (a *App) showSchemeForm(existing *tuicfg.Scheme, onSave func(tuicfg.Scheme)) {
-	name := ""
-	baseURL := ""
-	schemeType := "openai-compatible"
-	title := " ADD SCHEME "
-
-	if existing != nil {
-		name = existing.Name
-		baseURL = existing.BaseURL
-		schemeType = existing.Type
-		title = " EDIT SCHEME "
-	}
-
-	typeOptions := []string{"openai-compatible", "anthropic"}
-	typeIdx := 0
-	for i, t := range typeOptions {
-		if t == schemeType {
-			typeIdx = i
-			break
-		}
-	}
-
-	form := tview.NewForm()
-
-	form.
-		AddInputField("Name", name, 20, nil, func(text string) { name = text }).
-		AddInputField("Base URL", baseURL, 28, nil, func(text string) { baseURL = text }).
-		AddDropDown("Type", typeOptions, typeIdx, func(option string, _ int) { schemeType = option }).
-		AddButton("SAVE", func() {
-			if name == "" {
-				a.showError("Name is required")
-				return
-			}
-			if baseURL == "" {
-				a.showError("Base URL is required")
-				return
-			}
-			if existing == nil {
-				for _, s := range a.cfg.Provider.Schemes {
-					if s.Name == name {
-						a.showError(fmt.Sprintf("Scheme name %q already exists", name))
-						return
-					}
-				}
-			}
-			a.hideModal("scheme-form")
-			onSave(tuicfg.Scheme{Name: name, BaseURL: baseURL, Type: schemeType})
-		}).
-		AddButton("CANCEL", func() {
-			a.hideModal("scheme-form")
-		})
-
-	form.SetBorder(true).
-		SetTitle(" [::b]" + title + " ").
-		SetTitleColor(tcell.NewHexColor(0x39ff14)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
-	form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
-	form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
-	form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
-	form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
-	form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
-	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			a.hideModal("scheme-form")
-			return nil
-		}
-		return event
-	})
-
-	a.showModal("scheme-form", centeredForm(form, 4, 12))
-}

cmd/picoclaw-launcher-tui/ui/users.go

@@ -1,261 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"fmt"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
-)
-
-func (a *App) newUsersPage(schemeName string) tview.Primitive {
-	table := tview.NewTable().
-		SetBorders(false).
-		SetSelectable(true, false)
-	table.SetBorder(true).
-		SetTitle(fmt.Sprintf(" [#00f0ff::b] USERS · %s ", schemeName)).
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	table.SetSelectedStyle(
-		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
-	)
-	table.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	visibleUsers := func() []tuicfg.User {
-		var out []tuicfg.User
-		for _, u := range a.cfg.Provider.Users {
-			if u.Scheme == schemeName {
-				out = append(out, u)
-			}
-		}
-		return out
-	}
-
-	findUserGlobalIdx := func(userName string) int {
-		for i, u := range a.cfg.Provider.Users {
-			if u.Scheme == schemeName && u.Name == userName {
-				return i
-			}
-		}
-		return -1
-	}
-
-	rowToVisIdx := func(row int) int { return row / 2 }
-
-	selectedUserName := func() string {
-		row, _ := table.GetSelection()
-		users := visibleUsers()
-		visIdx := rowToVisIdx(row)
-		if visIdx >= 0 && visIdx < len(users) {
-			return users[visIdx].Name
-		}
-		return ""
-	}
-
-	rebuild := func() {
-		selName := selectedUserName()
-		table.Clear()
-		users := visibleUsers()
-		for i, u := range users {
-			nameRow := i * 2
-			detailRow := nameRow + 1
-
-			table.SetCell(nameRow, 0,
-				tview.NewTableCell(" "+u.Name).
-					SetTextColor(tcell.NewHexColor(0xe0e0e0)).
-					SetExpansion(1).
-					SetSelectable(true),
-			)
-			table.SetCell(nameRow, 1,
-				tview.NewTableCell("").
-					SetSelectable(false),
-			)
-
-			models := a.cachedModels(schemeName, u.Name)
-			var detailText string
-			if len(models) > 0 {
-				detailText = fmt.Sprintf("  [#39ff14]%d models available[-]", len(models))
-			} else {
-				detailText = "  [#ff2a2a]Inactive / No Access[-]"
-			}
-			table.SetCell(detailRow, 0,
-				tview.NewTableCell(detailText).
-					SetTextColor(tcell.NewHexColor(0x808080)).
-					SetExpansion(1).
-					SetSelectable(false),
-			)
-			table.SetCell(detailRow, 1,
-				tview.NewTableCell("[#00f0ff]"+u.Type+"  ").
-					SetAlign(tview.AlignRight).
-					SetSelectable(false),
-			)
-		}
-		if selName != "" {
-			for i, u := range users {
-				if u.Name == selName {
-					table.Select(i*2, 0)
-					return
-				}
-			}
-		}
-		if table.GetRowCount() > 0 {
-			table.Select(0, 0)
-		}
-	}
-	rebuild()
-
-	a.refreshModelCache(rebuild)
-	a.pageRefreshFns["users"] = func() { a.refreshModelCache(rebuild) }
-
-	table.SetSelectedFunc(func(row, _ int) {
-		visIdx := rowToVisIdx(row)
-		users := visibleUsers()
-		if visIdx < 0 || visIdx >= len(users) {
-			return
-		}
-		uName := users[visIdx].Name
-		scheme := a.cfg.Provider.SchemeByName(schemeName)
-		if scheme == nil {
-			a.showError(fmt.Sprintf("Scheme %q not found", schemeName))
-			return
-		}
-		a.navigateTo("models", a.newModelsPage(schemeName, uName, scheme.BaseURL))
-	})
-
-	table.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		row, _ := table.GetSelection()
-		visIdx := rowToVisIdx(row)
-		users := visibleUsers()
-		switch event.Rune() {
-		case 'a':
-			a.showUserForm(schemeName, nil, func(u tuicfg.User) {
-				a.cfg.Provider.Users = append(a.cfg.Provider.Users, u)
-				a.save()
-				a.refreshModelCache(rebuild)
-			})
-			return nil
-		case 'e':
-			if visIdx < 0 || visIdx >= len(users) {
-				return nil
-			}
-			origName := users[visIdx].Name
-			orig := a.cfg.Provider.Users[findUserGlobalIdx(origName)]
-			a.showUserForm(schemeName, &orig, func(u tuicfg.User) {
-				cfgIdx := findUserGlobalIdx(origName)
-				if cfgIdx < 0 {
-					a.showError(fmt.Sprintf("User %q no longer exists", origName))
-					return
-				}
-				a.cfg.Provider.Users[cfgIdx] = u
-				a.save()
-				a.refreshModelCache(func() {
-					rebuild()
-					for i, usr := range visibleUsers() {
-						if usr.Name == u.Name {
-							table.Select(i*2, 0)
-							break
-						}
-					}
-				})
-			})
-			return nil
-		case 'd':
-			if visIdx < 0 || visIdx >= len(users) {
-				return nil
-			}
-			uName := users[visIdx].Name
-			a.confirmDelete(fmt.Sprintf("user %q", uName), func() {
-				cfgIdx := findUserGlobalIdx(uName)
-				if cfgIdx < 0 {
-					return
-				}
-				all := a.cfg.Provider.Users
-				a.cfg.Provider.Users = append(all[:cfgIdx], all[cfgIdx+1:]...)
-				a.save()
-				a.refreshModelCache(rebuild)
-			})
-			return nil
-		}
-		return event
-	})
-
-	return a.buildShell(
-		"users",
-		table,
-		" [#00f0ff]a:[-] add  [#00f0ff]e:[-] edit  [#ff2a2a]d:[-] delete  [#39ff14]Enter:[-] models  [#ff00ff]ESC:[-] back ",
-	)
-}
-
-func (a *App) showUserForm(schemeName string, existing *tuicfg.User, onSave func(tuicfg.User)) {
-	name := ""
-	userType := "key"
-	key := ""
-	title := " ADD USER "
-
-	if existing != nil {
-		name = existing.Name
-		userType = existing.Type
-		key = existing.Key
-		title = " EDIT USER "
-	}
-
-	typeOptions := []string{"key", "OAuth"}
-	typeIdx := 0
-	for i, t := range typeOptions {
-		if t == userType {
-			typeIdx = i
-			break
-		}
-	}
-
-	form := tview.NewForm()
-	form.
-		AddInputField("Name", name, 20, nil, func(text string) { name = text }).
-		AddDropDown("Type", typeOptions, typeIdx, func(option string, _ int) { userType = option }).
-		AddPasswordField("Key", key, 28, '*', func(text string) { key = text }).
-		AddButton("SAVE", func() {
-			if name == "" {
-				a.showError("Name is required")
-				return
-			}
-			if existing == nil {
-				for _, u := range a.cfg.Provider.Users {
-					if u.Scheme == schemeName && u.Name == name {
-						a.showError(fmt.Sprintf("User name %q already exists for this scheme", name))
-						return
-					}
-				}
-			}
-			a.hideModal("user-form")
-			onSave(tuicfg.User{Name: name, Scheme: schemeName, Type: userType, Key: key})
-		}).
-		AddButton("CANCEL", func() {
-			a.hideModal("user-form")
-		})
-
-	form.SetBorder(true).
-		SetTitle(" [::b]" + title + " ").
-		SetTitleColor(tcell.NewHexColor(0x39ff14)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
-	form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
-	form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
-	form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
-	form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
-	form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
-	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			a.hideModal("user-form")
-			return nil
-		}
-		return event
-	})
-
-	a.showModal("user-form", centeredForm(form, 4, 13))
-}

cmd/picoclaw/internal/auth/helpers.go

@@ -59,7 +59,7 @@ func authLoginOpenAI(useDeviceCode bool, noBrowser bool) error {
 		// Update or add openai in ModelList
 		foundOpenAI := false
 		for i := range appCfg.ModelList {
-			if isOpenAIModel(appCfg.ModelList[i].Model) {
+			if isOpenAIModel(appCfg.ModelList[i]) {
 				appCfg.ModelList[i].AuthMethod = "oauth"
 				foundOpenAI = true
 				break
@@ -130,7 +130,7 @@ func authLoginGoogleAntigravity(noBrowser bool) error {
 		// Update or add antigravity in ModelList
 		foundAntigravity := false
 		for i := range appCfg.ModelList {
-			if isAntigravityModel(appCfg.ModelList[i].Model) {
+			if isAntigravityModel(appCfg.ModelList[i]) {
 				appCfg.ModelList[i].AuthMethod = "oauth"
 				foundAntigravity = true
 				break
@@ -206,7 +206,7 @@ func authLoginAnthropicSetupToken() error {
 	if err == nil {
 		found := false
 		for i := range appCfg.ModelList {
-			if isAnthropicModel(appCfg.ModelList[i].Model) {
+			if isAnthropicModel(appCfg.ModelList[i]) {
 				appCfg.ModelList[i].AuthMethod = "oauth"
 				found = true
 				break
@@ -282,7 +282,7 @@ func authLoginPasteToken(provider string) error {
 			// Update ModelList
 			found := false
 			for i := range appCfg.ModelList {
-				if isAnthropicModel(appCfg.ModelList[i].Model) {
+				if isAnthropicModel(appCfg.ModelList[i]) {
 					appCfg.ModelList[i].AuthMethod = "token"
 					found = true
 					break
@@ -300,7 +300,7 @@ func authLoginPasteToken(provider string) error {
 			// Update ModelList
 			found := false
 			for i := range appCfg.ModelList {
-				if isOpenAIModel(appCfg.ModelList[i].Model) {
+				if isOpenAIModel(appCfg.ModelList[i]) {
 					appCfg.ModelList[i].AuthMethod = "token"
 					found = true
 					break
@@ -342,15 +342,15 @@ func authLogoutCmd(provider string) error {
 			for i := range appCfg.ModelList {
 				switch provider {
 				case "openai":
-					if isOpenAIModel(appCfg.ModelList[i].Model) {
+					if isOpenAIModel(appCfg.ModelList[i]) {
 						appCfg.ModelList[i].AuthMethod = ""
 					}
 				case "anthropic":
-					if isAnthropicModel(appCfg.ModelList[i].Model) {
+					if isAnthropicModel(appCfg.ModelList[i]) {
 						appCfg.ModelList[i].AuthMethod = ""
 					}
 				case "google-antigravity", "antigravity":
-					if isAntigravityModel(appCfg.ModelList[i].Model) {
+					if isAntigravityModel(appCfg.ModelList[i]) {
 						appCfg.ModelList[i].AuthMethod = ""
 					}
 				}
@@ -484,22 +484,20 @@ func authModelsCmd() error {
 	return nil
 }
 
-// isAntigravityModel checks if a model string belongs to antigravity provider
-func isAntigravityModel(model string) bool {
-	return model == "antigravity" ||
-		model == "google-antigravity" ||
-		strings.HasPrefix(model, "antigravity/") ||
-		strings.HasPrefix(model, "google-antigravity/")
+// isAntigravityModel checks if a model config belongs to an Antigravity provider.
+func isAntigravityModel(modelCfg *config.ModelConfig) bool {
+	protocol, _ := providers.ExtractProtocol(modelCfg)
+	return protocol == "antigravity" || protocol == "google-antigravity"
 }
 
-// isOpenAIModel checks if a model string belongs to openai provider
-func isOpenAIModel(model string) bool {
-	return model == "openai" ||
-		strings.HasPrefix(model, "openai/")
+// isOpenAIModel checks if a model config belongs to the OpenAI provider.
+func isOpenAIModel(modelCfg *config.ModelConfig) bool {
+	protocol, _ := providers.ExtractProtocol(modelCfg)
+	return protocol == "openai"
 }
 
-// isAnthropicModel checks if a model string belongs to anthropic provider
-func isAnthropicModel(model string) bool {
-	return model == "anthropic" ||
-		strings.HasPrefix(model, "anthropic/")
+// isAnthropicModel checks if a model config belongs to the Anthropic provider.
+func isAnthropicModel(modelCfg *config.ModelConfig) bool {
+	protocol, _ := providers.ExtractProtocol(modelCfg)
+	return protocol == "anthropic"
 }

cmd/picoclaw/internal/auth/wecom_test.go

@@ -3,6 +3,7 @@ package auth
 import (
 	"bytes"
 	"context"
+	"net"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
@@ -19,6 +20,19 @@ import (
 	"github.com/sipeed/picoclaw/pkg/config"
 )
 
+func newIPv4TestServer(t *testing.T, handler http.Handler) *httptest.Server {
+	t.Helper()
+
+	server := httptest.NewUnstartedServer(handler)
+	listener, err := net.Listen("tcp4", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	server.Listener = listener
+	server.Start()
+	t.Cleanup(server.Close)
+	return server
+}
+
 func TestNewWeComCommand(t *testing.T) {
 	cmd := newWeComCommand()
 
@@ -53,7 +67,7 @@ func TestBuildWeComQRCodePageURL(t *testing.T) {
 }
 
 func TestFetchWeComQRCode(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	server := newIPv4TestServer(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		assert.Equal(t, "/generate", r.URL.Path)
 		assert.Equal(t, wecomQRSourceID, r.URL.Query().Get("source"))
 		assert.Equal(t, wecomQRSourceID, r.URL.Query().Get("sourceID"))
@@ -61,7 +75,6 @@ func TestFetchWeComQRCode(t *testing.T) {
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"data":{"scode":"scode-1","auth_url":"https://example.com/qr"}}`))
 	}))
-	defer server.Close()
 
 	opts := normalizeWeComQRFlowOptions(wecomQRFlowOptions{
 		HTTPClient:  server.Client(),
@@ -78,7 +91,7 @@ func TestFetchWeComQRCode(t *testing.T) {
 func TestPollWeComQRCodeResult(t *testing.T) {
 	var calls atomic.Int32
 
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	server := newIPv4TestServer(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		call := calls.Add(1)
 		assert.Equal(t, "/query", r.URL.Path)
 		assert.Equal(t, "scode-1", r.URL.Query().Get("scode"))
@@ -92,7 +105,6 @@ func TestPollWeComQRCodeResult(t *testing.T) {
 			_, _ = w.Write([]byte(`{"data":{"status":"success","bot_info":{"botid":"bot-1","secret":"secret-1"}}}`))
 		}
 	}))
-	defer server.Close()
 
 	var output bytes.Buffer
 	opts := normalizeWeComQRFlowOptions(wecomQRFlowOptions{

cmd/picoclaw/internal/cliui/mcp_show.go

@@ -0,0 +1,384 @@
+package cliui
+
+import (
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/charmbracelet/lipgloss"
+)
+
+// MCPShowServer holds the server metadata for PrintMCPShow.
+type MCPShowServer struct {
+	Name              string
+	Type              string
+	Target            string
+	Enabled           bool
+	EffectiveDeferred bool     // resolved value (per-server override or global default)
+	DeferredExplicit  bool     // true = per-server override set, false = inherited from global
+	EnvKeys           []string // sorted env var names (values intentionally omitted)
+	EnvFile           string
+	Headers           []string // sorted header names
+}
+
+// MCPShowTool holds one tool's info for PrintMCPShow.
+type MCPShowTool struct {
+	Name        string
+	Description string
+	Parameters  []MCPShowParam
+}
+
+// MCPShowParam is one parameter entry.
+type MCPShowParam struct {
+	Name        string
+	Type        string
+	Description string
+	Required    bool
+}
+
+// PrintMCPShow renders the mcp show output (plain or fancy).
+// w is where the output is written; pass cmd.OutOrStdout() from cobra commands.
+func PrintMCPShow(w io.Writer, server MCPShowServer, tools []MCPShowTool, disabled bool) {
+	if !UseFancyLayout() {
+		printMCPShowPlain(w, server, tools, disabled)
+		return
+	}
+	printMCPShowFancy(w, server, tools, disabled)
+}
+
+// ── plain (narrow / non-TTY) ────────────────────────────────────────────────
+
+func printMCPShowPlain(w io.Writer, server MCPShowServer, tools []MCPShowTool, disabled bool) {
+	fmt.Fprintf(w, "Server: %s\n", server.Name)
+	fmt.Fprintf(w, "Type:   %s\n", server.Type)
+	fmt.Fprintf(w, "Target: %s\n", server.Target)
+	fmt.Fprintf(w, "Enabled: %s\n", boolWord(server.Enabled))
+	deferredLabel := boolWord(server.EffectiveDeferred)
+	if !server.DeferredExplicit {
+		deferredLabel += " (default)"
+	}
+	fmt.Fprintf(w, "Deferred: %s\n", deferredLabel)
+	if len(server.EnvKeys) > 0 {
+		fmt.Fprintf(w, "Env vars: %s\n", strings.Join(server.EnvKeys, ", "))
+	}
+	if server.EnvFile != "" {
+		fmt.Fprintf(w, "Env file: %s\n", server.EnvFile)
+	}
+	if len(server.Headers) > 0 {
+		fmt.Fprintf(w, "Headers: %s\n", strings.Join(server.Headers, ", "))
+	}
+	fmt.Fprintln(w)
+
+	if disabled {
+		fmt.Fprintln(w, "Server is disabled; skipping tool discovery.")
+		return
+	}
+	if len(tools) == 0 {
+		fmt.Fprintln(w, "No tools exposed by this server.")
+		return
+	}
+
+	fmt.Fprintf(w, "Tools (%d):\n", len(tools))
+	for _, tool := range tools {
+		fmt.Fprintf(w, "  %s\n", tool.Name)
+		if tool.Description != "" {
+			fmt.Fprintf(w, "    %s\n", truncateDescription(tool.Description, 120))
+		}
+		if len(tool.Parameters) == 0 {
+			fmt.Fprintln(w, "    Parameters: none")
+			continue
+		}
+		for _, p := range tool.Parameters {
+			line := fmt.Sprintf("    - %s", p.Name)
+			if p.Type != "" {
+				line += fmt.Sprintf(" (%s", p.Type)
+				if p.Required {
+					line += ", required"
+				}
+				line += ")"
+			} else if p.Required {
+				line += " (required)"
+			}
+			if p.Description != "" {
+				line += ": " + truncateDescription(p.Description, 80)
+			}
+			fmt.Fprintln(w, line)
+		}
+	}
+}
+
+// ── fancy (wide TTY) ────────────────────────────────────────────────────────
+
+var (
+	mcpToolNameStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(accentBlue).Bold(true)
+	}
+	mcpParamNameStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(accentRed).Bold(true)
+	}
+	mcpTagStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#888888"))
+	}
+	mcpRequiredStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#D54646")).Bold(true)
+	}
+	mcpOptionalStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#6B6B6B"))
+	}
+	mcpDescStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#CCCCCC"))
+	}
+)
+
+func printMCPShowFancy(w io.Writer, server MCPShowServer, tools []MCPShowTool, disabled bool) {
+	inner := InnerWidth()
+	box := borderStyle().Width(inner)
+
+	var b strings.Builder
+
+	// ── server header ──
+	b.WriteString(titleBarStyle().Render("⬡  " + server.Name))
+	b.WriteString("\n\n")
+
+	keyW := 10
+	writeKV := func(key, val string) {
+		k := kvKeyStyle().Width(keyW).Render(key)
+		b.WriteString(k + "  " + val + "\n")
+	}
+
+	writeKV("Type", server.Type)
+	writeKV("Target", server.Target)
+	writeKV("Enabled", coloredBool(server.Enabled))
+	deferredVal := coloredBool(server.EffectiveDeferred)
+	if !server.DeferredExplicit {
+		deferredVal += "  " + mcpTagStyle().Render("(default)")
+	}
+	writeKV("Deferred", deferredVal)
+	if len(server.EnvKeys) > 0 {
+		writeKV("Env vars", mutedStyle().Render(strings.Join(server.EnvKeys, ", ")))
+	}
+	if server.EnvFile != "" {
+		writeKV("Env file", mutedStyle().Render(server.EnvFile))
+	}
+	if len(server.Headers) > 0 {
+		writeKV("Headers", mutedStyle().Render(strings.Join(server.Headers, ", ")))
+	}
+
+	if disabled {
+		b.WriteString("\n")
+		b.WriteString(mutedStyle().Render("Server is disabled; skipping tool discovery."))
+		fmt.Fprintln(w, box.Render(b.String()))
+		return
+	}
+
+	if len(tools) == 0 {
+		b.WriteString("\n")
+		b.WriteString(mutedStyle().Render("No tools exposed by this server."))
+		fmt.Fprintln(w, box.Render(b.String()))
+		return
+	}
+
+	// ── tools section ──
+	b.WriteString("\n")
+	b.WriteString(kvKeyStyle().Render(fmt.Sprintf("Tools (%d)", len(tools))))
+	b.WriteString("\n")
+
+	contentW := inner - 4 // account for box padding
+	for i, tool := range tools {
+		if i > 0 {
+			b.WriteString(strings.Repeat("─", contentW) + "\n")
+		}
+		b.WriteString("\n")
+
+		// Tool name + index badge
+		badge := mcpTagStyle().Render(fmt.Sprintf("[%d/%d]", i+1, len(tools)))
+		b.WriteString("  " + mcpToolNameStyle().Render(tool.Name) + "  " + badge + "\n")
+
+		// Description (wrapped to content width)
+		if tool.Description != "" {
+			desc := truncateDescription(tool.Description, 160)
+			b.WriteString("  " + mcpDescStyle().Render(desc) + "\n")
+		}
+
+		// Parameters
+		if len(tool.Parameters) == 0 {
+			b.WriteString("  " + mcpTagStyle().Render("no parameters") + "\n")
+			continue
+		}
+
+		b.WriteString("\n")
+		for _, p := range tool.Parameters {
+			// name
+			pName := mcpParamNameStyle().Render(p.Name)
+
+			// type tag
+			typeTag := ""
+			if p.Type != "" {
+				typeTag = "  " + mcpTagStyle().Render("<"+p.Type+">")
+			}
+
+			// required / optional badge
+			var reqBadge string
+			if p.Required {
+				reqBadge = "  " + mcpRequiredStyle().Render("required")
+			} else {
+				reqBadge = "  " + mcpOptionalStyle().Render("optional")
+			}
+
+			b.WriteString("    " + pName + typeTag + reqBadge + "\n")
+
+			if p.Description != "" {
+				desc := truncateDescription(p.Description, 120)
+				b.WriteString("      " + mutedStyle().Render(desc) + "\n")
+			}
+		}
+	}
+
+	fmt.Fprintln(w, box.Render(b.String()))
+}
+
+// ── mcp list ────────────────────────────────────────────────────────────────
+
+// MCPListRow is one row in the mcp list output.
+type MCPListRow struct {
+	Name              string
+	Type              string
+	Target            string
+	Status            string // "enabled", "disabled", "ok (N tools)", "error"
+	EffectiveDeferred bool   // resolved value (per-server override or global default)
+	DeferredExplicit  bool   // true = per-server override set, false = inherited from global
+}
+
+// PrintMCPList renders the mcp list output (plain or fancy).
+func PrintMCPList(w io.Writer, rows []MCPListRow) {
+	if !UseFancyLayout() {
+		printMCPListPlain(w, rows)
+		return
+	}
+	printMCPListFancy(w, rows)
+}
+
+func printMCPListPlain(w io.Writer, rows []MCPListRow) {
+	headers := []string{"Name", "Type", "Command", "Status", "Deferred"}
+	tableRows := make([][]string, len(rows))
+	for i, r := range rows {
+		deferred := boolWord(r.EffectiveDeferred)
+		if !r.DeferredExplicit {
+			deferred += " (default)"
+		}
+		tableRows[i] = []string{r.Name, r.Type, r.Target, r.Status, deferred}
+	}
+	// reuse the ASCII table renderer already in helpers.go via the caller
+	// (list.go still uses renderTable for the plain path)
+	widths := make([]int, len(headers))
+	for i, h := range headers {
+		widths[i] = len(h)
+	}
+	for _, row := range tableRows {
+		for i, cell := range row {
+			if len(cell) > widths[i] {
+				widths[i] = len(cell)
+			}
+		}
+	}
+	border := func() {
+		fmt.Fprint(w, "+")
+		for _, width := range widths {
+			fmt.Fprint(w, strings.Repeat("-", width+2)+"+")
+		}
+		fmt.Fprintln(w)
+	}
+	writeRow := func(row []string) {
+		fmt.Fprint(w, "|")
+		for i, cell := range row {
+			fmt.Fprintf(w, " %s%s |", cell, strings.Repeat(" ", widths[i]-len(cell)))
+		}
+		fmt.Fprintln(w)
+	}
+	border()
+	writeRow(headers)
+	border()
+	for _, row := range tableRows {
+		writeRow(row)
+	}
+	border()
+}
+
+func printMCPListFancy(w io.Writer, rows []MCPListRow) {
+	inner := InnerWidth()
+	box := borderStyle().Width(inner)
+
+	var b strings.Builder
+
+	title := fmt.Sprintf("MCP Servers (%d)", len(rows))
+	b.WriteString(titleBarStyle().Render(title))
+	b.WriteString("\n")
+
+	contentW := inner - 4
+	for i, row := range rows {
+		if i > 0 {
+			b.WriteString(strings.Repeat("─", contentW) + "\n")
+		}
+		b.WriteString("\n")
+
+		statusBadge := mcpListStatusStyle(row.Status).Render(row.Status)
+		var deferredBadge string
+		if row.EffectiveDeferred {
+			if row.DeferredExplicit {
+				deferredBadge = "  " + mcpTagStyle().Render("deferred")
+			} else {
+				deferredBadge = "  " + mcpOptionalStyle().Render("deferred (default)")
+			}
+		}
+		b.WriteString("  " + mcpToolNameStyle().Render(row.Name) + "  " + statusBadge + deferredBadge + "\n")
+		b.WriteString("  " + mcpTagStyle().Render(row.Type+"  "+row.Target) + "\n")
+	}
+
+	fmt.Fprintln(w, box.Render(b.String()))
+}
+
+func mcpListStatusStyle(status string) lipgloss.Style {
+	switch {
+	case status == "enabled":
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#2E7D32")).Bold(true)
+	case status == "disabled":
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#6B6B6B"))
+	case strings.HasPrefix(status, "ok"):
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#2E7D32")).Bold(true)
+	case status == "error":
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#D54646")).Bold(true)
+	default:
+		return lipgloss.NewStyle()
+	}
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+func boolWord(v bool) string {
+	if v {
+		return "yes"
+	}
+	return "no"
+}
+
+func coloredBool(v bool) string {
+	if v {
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#2E7D32")).Bold(true).Render("yes")
+	}
+	return lipgloss.NewStyle().Foreground(lipgloss.Color("#D54646")).Render("no")
+}
+
+// truncateDescription strips newlines, collapses whitespace, and caps length.
+func truncateDescription(s string, maxLen int) string {
+	// collapse newlines and repeated spaces into a single space
+	s = strings.Join(strings.Fields(s), " ")
+	if len(s) <= maxLen {
+		return s
+	}
+	// cut at last space before maxLen
+	cut := s[:maxLen]
+	if idx := strings.LastIndex(cut, " "); idx > maxLen/2 {
+		cut = cut[:idx]
+	}
+	return cut + "…"
+}

cmd/picoclaw/internal/mcp/add.go

@@ -0,0 +1,249 @@
+package mcp
+
+import (
+	"fmt"
+	"net/url"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type addOptions struct {
+	Env       []string
+	EnvFile   string
+	Headers   []string
+	Transport string
+	Force     bool
+	Deferred  *bool // nil = not set, true = deferred, false = not deferred
+}
+
+func newAddCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:                "add [flags] <name> <command-or-url> [args...]",
+		Short:              "Add or update an MCP server",
+		DisableFlagParsing: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts, name, target, targetArgs, showHelp, err := parseAddArgs(args)
+			if showHelp {
+				return cmd.Help()
+			}
+			if err != nil {
+				return err
+			}
+
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+			if cfg.Tools.MCP.Servers == nil {
+				cfg.Tools.MCP.Servers = make(map[string]config.MCPServerConfig)
+			}
+
+			if _, exists := cfg.Tools.MCP.Servers[name]; exists && !opts.Force {
+				var overwrite bool
+
+				overwrite, err = confirmOverwrite(cmd.InOrStdin(), cmd.OutOrStdout(), name)
+				if err != nil {
+					return fmt.Errorf("failed to confirm overwrite: %w", err)
+				}
+				if !overwrite {
+					return fmt.Errorf("aborted: MCP server %q already exists", name)
+				}
+			}
+
+			server, err := buildServerConfig(target, targetArgs, opts)
+			if err != nil {
+				return err
+			}
+
+			cfg.Tools.MCP.Enabled = true
+			cfg.Tools.MCP.Servers[name] = server
+
+			if err := saveValidatedConfig(cfg); err != nil {
+				return err
+			}
+
+			fmt.Fprintf(cmd.OutOrStdout(), "✓ MCP server %q saved.\n", name)
+			return nil
+		},
+	}
+
+	flags := cmd.Flags()
+	flags.StringArrayP("env", "e", nil, "Environment variable in KEY=value format (repeatable, saved to config)")
+	flags.String("env-file", "", "Path to an env file for stdio servers (recommended for secrets)")
+	flags.StringArrayP("header", "H", nil, "HTTP header in 'Name: Value' or 'Name=Value' format (repeatable)")
+	flags.StringP("transport", "t", "stdio", "Transport type: stdio, http, or sse")
+	flags.BoolP("force", "f", false, "Overwrite an existing server without prompting")
+	flags.Bool("deferred", false, "Mark server as deferred (tools hidden until explicitly activated)")
+	flags.Bool("no-deferred", false, "Mark server as non-deferred (tools always active)")
+
+	return cmd
+}
+
+func parseAddArgs(args []string) (addOptions, string, string, []string, bool, error) {
+	opts := addOptions{Transport: "stdio"}
+	var positional []string
+	serverArgs := make([]string, 0)
+	explicitCommand := make([]string, 0)
+
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+
+		switch {
+		case arg == "--help" || arg == "-h":
+			return addOptions{}, "", "", nil, true, nil
+		case arg == "--":
+			if i+1 < len(args) {
+				explicitCommand = append(explicitCommand, args[i+1:]...)
+			}
+			i = len(args)
+		case arg == "--force" || arg == "-f":
+			opts.Force = true
+		case arg == "--deferred":
+			t := true
+			opts.Deferred = &t
+		case arg == "--no-deferred":
+			f := false
+			opts.Deferred = &f
+		case arg == "--transport" || arg == "-t":
+			if i+1 >= len(args) {
+				return addOptions{}, "", "", nil, false, fmt.Errorf("missing value for %s", arg)
+			}
+			i++
+			opts.Transport = args[i]
+		case strings.HasPrefix(arg, "--transport="):
+			opts.Transport = strings.TrimPrefix(arg, "--transport=")
+		case arg == "--env" || arg == "-e":
+			if i+1 >= len(args) {
+				return addOptions{}, "", "", nil, false, fmt.Errorf("missing value for %s", arg)
+			}
+			i++
+			opts.Env = append(opts.Env, args[i])
+		case arg == "--env-file":
+			if i+1 >= len(args) {
+				return addOptions{}, "", "", nil, false, fmt.Errorf("missing value for %s", arg)
+			}
+			i++
+			opts.EnvFile = args[i]
+		case strings.HasPrefix(arg, "--env="):
+			opts.Env = append(opts.Env, strings.TrimPrefix(arg, "--env="))
+		case strings.HasPrefix(arg, "--env-file="):
+			opts.EnvFile = strings.TrimPrefix(arg, "--env-file=")
+		case arg == "--header" || arg == "-H":
+			if i+1 >= len(args) {
+				return addOptions{}, "", "", nil, false, fmt.Errorf("missing value for %s", arg)
+			}
+			i++
+			opts.Headers = append(opts.Headers, args[i])
+		case strings.HasPrefix(arg, "--header="):
+			opts.Headers = append(opts.Headers, strings.TrimPrefix(arg, "--header="))
+		case strings.HasPrefix(arg, "-") && len(positional) >= 2:
+			serverArgs = append(serverArgs, args[i:]...)
+			i = len(args)
+		default:
+			positional = append(positional, arg)
+		}
+	}
+
+	if len(explicitCommand) > 0 {
+		if len(positional) != 1 {
+			return addOptions{}, "", "", nil, false, fmt.Errorf(
+				"usage: picoclaw mcp add [flags] <name> <command-or-url> [args...] or picoclaw mcp add [flags] <name> -- <command> [args...]",
+			)
+		}
+		if len(explicitCommand) == 0 {
+			return addOptions{}, "", "", nil, false, fmt.Errorf("missing stdio command after --")
+		}
+		return opts, positional[0], explicitCommand[0], explicitCommand[1:], false, nil
+	}
+
+	if len(positional) < 2 {
+		return addOptions{}, "", "", nil, false, fmt.Errorf(
+			"usage: picoclaw mcp add [flags] <name> <command-or-url> [args...] or picoclaw mcp add [flags] <name> -- <command> [args...]",
+		)
+	}
+
+	targetArgs := make([]string, 0, len(positional)-2+len(serverArgs))
+	targetArgs = append(targetArgs, positional[2:]...)
+	targetArgs = append(targetArgs, serverArgs...)
+
+	return opts, positional[0], positional[1], targetArgs, false, nil
+}
+
+func buildServerConfig(target string, args []string, opts addOptions) (config.MCPServerConfig, error) {
+	transport := strings.ToLower(strings.TrimSpace(opts.Transport))
+	if transport == "" {
+		transport = "stdio"
+	}
+	switch transport {
+	case "stdio", "http", "sse":
+	default:
+		return config.MCPServerConfig{}, fmt.Errorf("unsupported transport %q", opts.Transport)
+	}
+
+	env, err := parseEnvAssignments(opts.Env)
+	if err != nil {
+		return config.MCPServerConfig{}, err
+	}
+	headers, err := parseHeaderAssignments(opts.Headers)
+	if err != nil {
+		return config.MCPServerConfig{}, err
+	}
+
+	server := config.MCPServerConfig{
+		Enabled:  true,
+		Type:     transport,
+		Deferred: opts.Deferred,
+	}
+
+	switch transport {
+	case "http", "sse":
+		if len(env) > 0 {
+			return config.MCPServerConfig{}, fmt.Errorf("--env can only be used with stdio transport")
+		}
+		if strings.TrimSpace(opts.EnvFile) != "" {
+			return config.MCPServerConfig{}, fmt.Errorf("--env-file can only be used with stdio transport")
+		}
+		if len(args) > 0 {
+			return config.MCPServerConfig{}, fmt.Errorf("%s transport does not accept command arguments", transport)
+		}
+		parsedURL, err := url.ParseRequestURI(target)
+		if err != nil || parsedURL.Scheme == "" || parsedURL.Host == "" {
+			return config.MCPServerConfig{}, fmt.Errorf("invalid MCP URL %q", target)
+		}
+		server.URL = target
+		server.Headers = headers
+		return server, nil
+	}
+
+	if len(headers) > 0 {
+		return config.MCPServerConfig{}, fmt.Errorf("--header can only be used with http or sse transport")
+	}
+
+	if looksLikeRemoteURL(target) {
+		return config.MCPServerConfig{}, fmt.Errorf(
+			"target %q looks like a remote MCP URL, but transport is %q. Use --transport http or --transport sse",
+			target,
+			transport,
+		)
+	}
+
+	command := target
+	commandArgs := append([]string(nil), args...)
+
+	if err := validateLocalCommandPath(target); err != nil {
+		return config.MCPServerConfig{}, err
+	}
+	if isLocalCommandPath(command) {
+		command = expandHomePath(command)
+	}
+
+	server.Command = command
+	server.Args = commandArgs
+	server.Env = env
+	server.EnvFile = strings.TrimSpace(opts.EnvFile)
+
+	return server, nil
+}

cmd/picoclaw/internal/mcp/command.go

@@ -0,0 +1,25 @@
+package mcp
+
+import "github.com/spf13/cobra"
+
+func NewMCPCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "mcp",
+		Short: "Manage MCP server configuration",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+	}
+
+	cmd.AddCommand(
+		newAddCommand(),
+		newRemoveCommand(),
+		newListCommand(),
+		newEditCommand(),
+		newTestCommand(),
+		newShowCommand(),
+	)
+
+	return cmd
+}

cmd/picoclaw/internal/mcp/command_test.go

@@ -0,0 +1,619 @@
+package mcp
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestNewMCPCommand(t *testing.T) {
+	cmd := NewMCPCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "mcp", cmd.Use)
+	assert.Equal(t, "Manage MCP server configuration", cmd.Short)
+	assert.True(t, cmd.HasSubCommands())
+
+	allowedCommands := []string{
+		"add",
+		"remove",
+		"list",
+		"edit",
+		"test",
+		"show",
+	}
+
+	subcommands := cmd.Commands()
+	assert.Len(t, subcommands, len(allowedCommands))
+
+	for _, subcmd := range subcommands {
+		found := slices.Contains(allowedCommands, subcmd.Name())
+		assert.True(t, found, "unexpected subcommand %q", subcmd.Name())
+		assert.False(t, subcmd.Hidden)
+	}
+}
+
+func TestMCPAddAddsGenericStdioServer(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{
+		"add",
+		"sqlite",
+		"npx",
+		"-y",
+		"@modelcontextprotocol/server-sqlite",
+		"--db",
+		"./mydb.db",
+	}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, `MCP server "sqlite" saved`)
+
+	cfg := readMCPConfig(t, configPath)
+	require.True(t, cfg.Tools.MCP.Enabled)
+
+	server, ok := cfg.Tools.MCP.Servers["sqlite"]
+	require.True(t, ok)
+	assert.True(t, server.Enabled)
+	assert.Equal(t, "stdio", server.Type)
+	assert.Equal(t, "npx", server.Command)
+	assert.Equal(t, []string{"-y", "@modelcontextprotocol/server-sqlite", "--db", "./mydb.db"}, server.Args)
+}
+
+func TestMCPAddSupportsHeadersAfterURL(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"apify",
+		"https://mcp.apify.com/",
+		"-t",
+		"http",
+		"--header",
+		"Authorization: Bearer OMITTED",
+	}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["apify"]
+	assert.Equal(t, "http", server.Type)
+	assert.Equal(t, "https://mcp.apify.com/", server.URL)
+	assert.Equal(t, map[string]string{"Authorization": "Bearer OMITTED"}, server.Headers)
+}
+
+func TestMCPAddSupportsTransportBeforeName(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"--transport",
+		"sse",
+		"fiscal-ai",
+		"https://api.fiscal.ai/mcp/sse",
+	}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["fiscal-ai"]
+	assert.Equal(t, "sse", server.Type)
+	assert.Equal(t, "https://api.fiscal.ai/mcp/sse", server.URL)
+}
+
+func TestMCPAddSupportsExplicitStdioCommandAfterSeparator(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"--transport",
+		"stdio",
+		"--env",
+		"AIRTABLE_API_KEY=YOUR_KEY",
+		"airtable",
+		"--",
+		"npx",
+		"-y",
+		"airtable-mcp-server",
+	}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["airtable"]
+	assert.Equal(t, "stdio", server.Type)
+	assert.Equal(t, "npx", server.Command)
+	assert.Equal(t, []string{"-y", "airtable-mcp-server"}, server.Args)
+	assert.Equal(t, map[string]string{"AIRTABLE_API_KEY": "YOUR_KEY"}, server.Env)
+}
+
+func TestMCPAddSupportsEnvFileForStdio(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"--env-file",
+		".env.mcp",
+		"filesystem",
+		"npx",
+		"-y",
+		"@modelcontextprotocol/server-filesystem",
+	}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["filesystem"]
+	assert.Equal(t, "stdio", server.Type)
+	assert.Equal(t, "npx", server.Command)
+	assert.Equal(t, []string{"-y", "@modelcontextprotocol/server-filesystem"}, server.Args)
+	assert.Equal(t, ".env.mcp", server.EnvFile)
+}
+
+func TestMCPAddRejectsEnvFileForHTTP(t *testing.T) {
+	setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"--transport",
+		"http",
+		"--env-file",
+		".env.mcp",
+		"context7",
+		"https://mcp.context7.com/mcp",
+	}, "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "--env-file can only be used with stdio transport")
+}
+
+func TestMCPAddRejectsNonExecutableLocalCommand(t *testing.T) {
+	setupMCPConfigEnv(t)
+
+	tmpDir := t.TempDir()
+	localCmd := filepath.Join(tmpDir, "server.sh")
+	require.NoError(t, os.WriteFile(localCmd, []byte("#!/bin/sh\nexit 0\n"), 0o644))
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "local", localCmd}, "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "not executable")
+}
+
+func TestMCPAddExpandsHomeInSavedLocalCommand(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	homeDir := t.TempDir()
+	t.Setenv("HOME", homeDir)
+	t.Setenv("USERPROFILE", homeDir)
+
+	localCmd := filepath.Join(homeDir, "bin", "my-mcp")
+	require.NoError(t, os.MkdirAll(filepath.Dir(localCmd), 0o755))
+	require.NoError(t, os.WriteFile(localCmd, []byte("#!/bin/sh\nexit 0\n"), 0o755))
+
+	tildeCmd := "~" + string(os.PathSeparator) + filepath.Join("bin", "my-mcp")
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "local-home", tildeCmd}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["local-home"]
+	assert.Equal(t, localCmd, server.Command)
+}
+
+func TestMCPAddShowsClearErrorForRemoteURLWithoutTransport(t *testing.T) {
+	setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "apify", "https://mcp.apify.com/"}, "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), `looks like a remote MCP URL`)
+	assert.Contains(t, err.Error(), `Use --transport http or --transport sse`)
+}
+
+func TestMCPAddOverwritePromptDecline(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"filesystem": {
+						Enabled: true,
+						Type:    "stdio",
+						Command: "old",
+					},
+				},
+			},
+		},
+	})
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"add", "filesystem", "new-command"}, "n\n")
+	require.Error(t, err)
+	assert.Contains(t, output, `Overwrite? [y/N]:`)
+	assert.Contains(t, err.Error(), "aborted")
+
+	cfg := readMCPConfig(t, configPath)
+	assert.Equal(t, "old", cfg.Tools.MCP.Servers["filesystem"].Command)
+}
+
+func TestMCPAddOverwriteWithConfirmation(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"filesystem": {
+						Enabled: true,
+						Type:    "stdio",
+						Command: "old",
+					},
+				},
+			},
+		},
+	})
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "filesystem", "new-command"}, "y\n")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	assert.Equal(t, "new-command", cfg.Tools.MCP.Servers["filesystem"].Command)
+}
+
+func TestMCPAddHTTPServer(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"context7",
+		"--transport",
+		"http",
+		"https://mcp.context7.com/mcp",
+	}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["context7"]
+	assert.Equal(t, "http", server.Type)
+	assert.Equal(t, "https://mcp.context7.com/mcp", server.URL)
+	assert.Empty(t, server.Command)
+}
+
+func TestMCPRemoveRemovesLastServerAndDisablesMCP(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"filesystem": {
+						Enabled: true,
+						Type:    "stdio",
+						Command: "npx",
+					},
+				},
+			},
+		},
+	})
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"remove", "filesystem"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, `MCP server "filesystem" removed`)
+
+	cfg := readMCPConfig(t, configPath)
+	assert.False(t, cfg.Tools.MCP.Enabled)
+	assert.Empty(t, cfg.Tools.MCP.Servers)
+}
+
+func TestMCPListPrintsTable(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"context7": {
+						Enabled: true,
+						Type:    "http",
+						URL:     "https://mcp.context7.com/mcp",
+					},
+					"filesystem": {
+						Enabled: false,
+						Type:    "stdio",
+						Command: "npx",
+						Args:    []string{"-y", "@modelcontextprotocol/server-filesystem", "/tmp"},
+					},
+				},
+			},
+		},
+	})
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"list"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, "| Name")
+	assert.Contains(t, output, "context7")
+	assert.Contains(t, output, "filesystem")
+	assert.Contains(t, output, "https://mcp.context7.com/mcp")
+	assert.Contains(t, output, "disabled")
+}
+
+func TestMCPListWithStatusUsesProbe(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"filesystem": {
+						Enabled: true,
+						Type:    "stdio",
+						Command: "npx",
+					},
+				},
+			},
+		},
+	})
+
+	originalProbe := serverProbe
+	defer func() { serverProbe = originalProbe }()
+	serverProbe = func(_ context.Context, name string, server config.MCPServerConfig, workspacePath string) (probeResult, error) {
+		assert.Equal(t, "filesystem", name)
+		assert.Equal(t, readMCPConfig(t, configPath).WorkspacePath(), workspacePath)
+		assert.Equal(t, "npx", server.Command)
+		return probeResult{ToolCount: 3}, nil
+	}
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"list", "--status"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, "ok (3 tools)")
+}
+
+func TestMCPEditUsesEditor(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	originalEditor := editorCommand
+	defer func() { editorCommand = originalEditor }()
+
+	var gotName string
+	var gotArgs []string
+	editorCommand = func(name string, args ...string) *exec.Cmd {
+		gotName = name
+		gotArgs = append([]string(nil), args...)
+		return exec.Command("sh", "-c", "exit 0")
+	}
+
+	t.Setenv("EDITOR", `dummy-editor --wait`)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"edit"}, "")
+	require.NoError(t, err)
+
+	assert.Equal(t, "dummy-editor", gotName)
+	assert.Equal(t, []string{"--wait", configPath}, gotArgs)
+	_, statErr := os.Stat(configPath)
+	assert.NoError(t, statErr)
+}
+
+func TestMCPEditRequiresEditor(t *testing.T) {
+	setupMCPConfigEnv(t)
+	t.Setenv("EDITOR", "")
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"edit"}, "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "$EDITOR is not set")
+}
+
+func TestMCPTestUsesProbe(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"filesystem": {
+						Enabled: false,
+						Type:    "stdio",
+						Command: "npx",
+					},
+				},
+			},
+		},
+	})
+
+	originalProbe := serverProbe
+	defer func() { serverProbe = originalProbe }()
+	serverProbe = func(_ context.Context, name string, _ config.MCPServerConfig, workspacePath string) (probeResult, error) {
+		assert.Equal(t, "filesystem", name)
+		assert.Equal(t, readMCPConfig(t, configPath).WorkspacePath(), workspacePath)
+		return probeResult{ToolCount: 2}, nil
+	}
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"test", "filesystem"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, `MCP server "filesystem" reachable (2 tools)`)
+}
+
+func TestMCPAddDeferredFlag(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "--deferred", "myserver", "npx", "my-mcp"}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["myserver"]
+	require.NotNil(t, server.Deferred)
+	assert.True(t, *server.Deferred)
+}
+
+func TestMCPAddNoDeferredFlag(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "--no-deferred", "myserver", "npx", "my-mcp"}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["myserver"]
+	require.NotNil(t, server.Deferred)
+	assert.False(t, *server.Deferred)
+}
+
+func TestMCPAddNoDeferredByDefault(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "myserver", "npx", "my-mcp"}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["myserver"]
+	assert.Nil(t, server.Deferred)
+}
+
+func TestMCPShowNotFound(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, nil)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"show", "missing"}, "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), `"missing" not found`)
+}
+
+func TestMCPShowDisabledServer(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"myserver": {
+						Enabled: false,
+						Type:    "stdio",
+						Command: "npx",
+					},
+				},
+			},
+		},
+	})
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"show", "myserver"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, "myserver")
+	assert.Contains(t, output, "disabled")
+}
+
+func TestMCPShowUsesProbe(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"myserver": {
+						Enabled: true,
+						Type:    "stdio",
+						Command: "npx",
+					},
+				},
+			},
+		},
+	})
+
+	original := serverShowProbe
+	defer func() { serverShowProbe = original }()
+	serverShowProbe = func(_ context.Context, name string, _ config.MCPServerConfig, _ string) ([]toolDetail, error) {
+		assert.Equal(t, "myserver", name)
+		return []toolDetail{
+			{
+				Name:        "read_file",
+				Description: "Read a file from the filesystem",
+				Parameters: []paramDetail{
+					{Name: "path", Type: "string", Description: "File path", Required: true},
+					{Name: "encoding", Type: "string", Description: "Character encoding", Required: false},
+				},
+			},
+			{
+				Name:        "list_dir",
+				Description: "List directory contents",
+				Parameters:  nil,
+			},
+		}, nil
+	}
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"show", "myserver"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, "myserver")
+	assert.Contains(t, output, "read_file")
+	assert.Contains(t, output, "Read a file from the filesystem")
+	assert.Contains(t, output, "path")
+	assert.Contains(t, output, "string")
+	assert.Contains(t, output, "required")
+	assert.Contains(t, output, "list_dir")
+	assert.Contains(t, output, "none")
+}
+
+func setupMCPConfigEnv(t *testing.T) string {
+	t.Helper()
+
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	t.Setenv(config.EnvConfig, configPath)
+	t.Setenv(config.EnvHome, filepath.Dir(configPath))
+	return configPath
+}
+
+func writeMCPConfig(t *testing.T, path string, cfg *config.Config) {
+	t.Helper()
+
+	if cfg == nil {
+		cfg = config.DefaultConfig()
+	}
+
+	require.NoError(t, config.SaveConfig(path, cfg))
+}
+
+func readMCPConfig(t *testing.T, path string) *config.Config {
+	t.Helper()
+
+	cfg, err := config.LoadConfig(path)
+	require.NoError(t, err)
+	return cfg
+}
+
+func executeCommand(cmd *cobra.Command, args []string, stdin string) (string, error) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	cmd.SetArgs(args)
+	cmd.SetOut(&stdout)
+	cmd.SetErr(&stderr)
+	cmd.SetIn(strings.NewReader(stdin))
+
+	err := cmd.Execute()
+	return stdout.String() + stderr.String(), err
+}

cmd/picoclaw/internal/mcp/edit.go

@@ -0,0 +1,54 @@
+package mcp
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"go.mau.fi/util/shlex"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+)
+
+func newEditCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "edit",
+		Short: "Open the PicoClaw config in $EDITOR",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			editor := strings.TrimSpace(os.Getenv("EDITOR"))
+			if editor == "" {
+				return fmt.Errorf("$EDITOR is not set")
+			}
+
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+			if err = saveValidatedConfig(cfg); err != nil {
+				return err
+			}
+
+			editorArgs, err := shlex.Split(editor)
+			if err != nil {
+				return fmt.Errorf("failed to parse $EDITOR: %w", err)
+			}
+			if len(editorArgs) == 0 {
+				return fmt.Errorf("$EDITOR is empty")
+			}
+
+			editorArgs = append(editorArgs, internal.GetConfigPath())
+			process := editorCommand(editorArgs[0], editorArgs[1:]...)
+			process.Stdin = cmd.InOrStdin()
+			process.Stdout = cmd.OutOrStdout()
+			process.Stderr = cmd.ErrOrStderr()
+
+			if err := process.Run(); err != nil {
+				return fmt.Errorf("failed to start editor: %w", err)
+			}
+
+			return nil
+		},
+	}
+}

cmd/picoclaw/internal/mcp/helpers.go

@@ -0,0 +1,359 @@
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"sort"
+	"strings"
+	"sync"
+
+	"github.com/google/jsonschema-go/jsonschema"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/config"
+	picomcp "github.com/sipeed/picoclaw/pkg/mcp"
+)
+
+type probeResult struct {
+	ToolCount int
+}
+
+var (
+	editorCommand = exec.Command
+	serverProbe   = defaultServerProbe
+
+	mcpConfigSchemaOnce sync.Once
+	mcpConfigSchema     *jsonschema.Resolved
+	errMcpConfigSchema  error
+)
+
+const mcpConfigSchemaJSON = `{
+  "type": "object",
+  "properties": {
+    "tools": {
+      "type": "object",
+      "properties": {
+        "mcp": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "discovery": { "type": "object", "additionalProperties": true },
+            "max_inline_text_chars": { "type": "integer" },
+            "servers": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "enabled": { "type": "boolean" },
+                  "deferred": { "type": "boolean" },
+                  "command": { "type": "string" },
+                  "args": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                  },
+                  "env": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string" }
+                  },
+                  "env_file": { "type": "string" },
+                  "type": {
+                    "type": "string",
+                    "enum": ["stdio", "http", "sse"]
+                  },
+                  "url": { "type": "string" },
+                  "headers": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string" }
+                  }
+                },
+                "required": ["enabled"],
+                "anyOf": [
+                  { "required": ["command"] },
+                  { "required": ["url"] }
+                ],
+                "additionalProperties": false
+              }
+            }
+          },
+          "required": ["enabled"],
+          "additionalProperties": true
+        }
+      },
+      "required": ["mcp"],
+      "additionalProperties": true
+    }
+  },
+  "required": ["tools"],
+  "additionalProperties": true
+}`
+
+func loadConfig() (*config.Config, error) {
+	cfg, err := config.LoadConfig(internal.GetConfigPath())
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+	return cfg, nil
+}
+
+func saveValidatedConfig(cfg *config.Config) error {
+	if cfg == nil {
+		return fmt.Errorf("config is nil")
+	}
+
+	data, err := json.Marshal(cfg)
+	if err != nil {
+		return fmt.Errorf("failed to serialize config: %w", err)
+	}
+
+	if err := validateConfigDocument(data); err != nil {
+		return err
+	}
+
+	if err := config.SaveConfig(internal.GetConfigPath(), cfg); err != nil {
+		return fmt.Errorf("failed to save config: %w", err)
+	}
+
+	return nil
+}
+
+func validateConfigDocument(data []byte) error {
+	var instance map[string]any
+	if err := json.Unmarshal(data, &instance); err != nil {
+		return fmt.Errorf("failed to decode serialized config: %w", err)
+	}
+
+	schema, err := loadMCPConfigSchema()
+	if err != nil {
+		return fmt.Errorf("failed to load MCP config schema: %w", err)
+	}
+
+	if err := schema.Validate(instance); err != nil {
+		return fmt.Errorf("config validation failed: %w", err)
+	}
+
+	return nil
+}
+
+func loadMCPConfigSchema() (*jsonschema.Resolved, error) {
+	mcpConfigSchemaOnce.Do(func() {
+		var schema jsonschema.Schema
+		if err := json.Unmarshal([]byte(mcpConfigSchemaJSON), &schema); err != nil {
+			errMcpConfigSchema = err
+			return
+		}
+		mcpConfigSchema, errMcpConfigSchema = schema.Resolve(nil)
+	})
+
+	return mcpConfigSchema, errMcpConfigSchema
+}
+
+func inferTransportType(server config.MCPServerConfig) string {
+	switch server.Type {
+	case "stdio", "http", "sse":
+		return server.Type
+	}
+	if server.URL != "" {
+		return "sse"
+	}
+	if server.Command != "" {
+		return "stdio"
+	}
+	return "unknown"
+}
+
+func renderServerTarget(server config.MCPServerConfig) string {
+	transport := inferTransportType(server)
+	if transport == "http" || transport == "sse" {
+		if server.URL == "" {
+			return "<missing url>"
+		}
+		return server.URL
+	}
+
+	parts := append([]string{server.Command}, server.Args...)
+	rendered := strings.TrimSpace(strings.Join(parts, " "))
+	if rendered == "" {
+		return "<missing command>"
+	}
+	return rendered
+}
+
+func sortedServerNames(servers map[string]config.MCPServerConfig) []string {
+	names := make([]string, 0, len(servers))
+	for name := range servers {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
+func parseEnvAssignments(values []string) (map[string]string, error) {
+	if len(values) == 0 {
+		return nil, nil
+	}
+
+	env := make(map[string]string, len(values))
+	for _, entry := range values {
+		key, value, found := strings.Cut(entry, "=")
+		if !found {
+			return nil, fmt.Errorf("invalid env assignment %q: expected KEY=value", entry)
+		}
+		key = strings.TrimSpace(key)
+		if key == "" {
+			return nil, fmt.Errorf("invalid env assignment %q: key cannot be empty", entry)
+		}
+		env[key] = value
+	}
+
+	return env, nil
+}
+
+func parseHeaderAssignments(values []string) (map[string]string, error) {
+	if len(values) == 0 {
+		return nil, nil
+	}
+
+	headers := make(map[string]string, len(values))
+	for _, entry := range values {
+		key, value, found := strings.Cut(entry, ":")
+		if !found {
+			key, value, found = strings.Cut(entry, "=")
+		}
+		if !found {
+			return nil, fmt.Errorf("invalid header %q: expected 'Name: Value' or 'Name=Value'", entry)
+		}
+		key = strings.TrimSpace(key)
+		value = strings.TrimSpace(value)
+		if key == "" {
+			return nil, fmt.Errorf("invalid header %q: name cannot be empty", entry)
+		}
+		headers[key] = value
+	}
+
+	return headers, nil
+}
+
+func looksLikeRemoteURL(target string) bool {
+	parsedURL, err := url.ParseRequestURI(target)
+	if err != nil {
+		return false
+	}
+	if parsedURL.Host == "" {
+		return false
+	}
+	switch strings.ToLower(parsedURL.Scheme) {
+	case "http", "https":
+		return true
+	default:
+		return false
+	}
+}
+
+func isLocalCommandPath(command string) bool {
+	if command == "" {
+		return false
+	}
+	if looksLikeRemoteURL(command) {
+		return false
+	}
+	return filepath.IsAbs(command) ||
+		filepath.VolumeName(command) != "" ||
+		strings.HasPrefix(command, "."+string(os.PathSeparator)) ||
+		strings.HasPrefix(command, ".."+string(os.PathSeparator)) ||
+		command == "." ||
+		command == ".." ||
+		strings.ContainsRune(command, os.PathSeparator)
+}
+
+func expandHomePath(path string) string {
+	if path == "" || path[0] != '~' {
+		return path
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return path
+	}
+	if path == "~" {
+		return home
+	}
+	if strings.HasPrefix(path, "~/") || strings.HasPrefix(path, "~\\") {
+		return filepath.Join(home, path[2:])
+	}
+	return path
+}
+
+func validateLocalCommandPath(command string) error {
+	if !isLocalCommandPath(command) {
+		return nil
+	}
+
+	path := expandHomePath(command)
+	info, err := os.Stat(path)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return fmt.Errorf("local command %q does not exist", command)
+		}
+		return fmt.Errorf("failed to stat local command %q: %w", command, err)
+	}
+	if info.IsDir() {
+		return fmt.Errorf("local command %q is a directory", command)
+	}
+	if runtime.GOOS != "windows" && info.Mode()&0o111 == 0 {
+		return fmt.Errorf("local command %q is not executable", command)
+	}
+	return nil
+}
+
+func defaultServerProbe(
+	ctx context.Context,
+	name string,
+	server config.MCPServerConfig,
+	workspacePath string,
+) (probeResult, error) {
+	mgr := picomcp.NewManager()
+	defer func() { _ = mgr.Close() }()
+
+	server.Enabled = true
+	mcpCfg := config.MCPConfig{
+		ToolConfig: config.ToolConfig{Enabled: true},
+		Servers: map[string]config.MCPServerConfig{
+			name: server,
+		},
+	}
+
+	if err := mgr.LoadFromMCPConfig(ctx, mcpCfg, workspacePath); err != nil {
+		return probeResult{}, err
+	}
+
+	conn, ok := mgr.GetServer(name)
+	if !ok {
+		return probeResult{}, fmt.Errorf("server %q did not register a connection", name)
+	}
+
+	return probeResult{ToolCount: len(conn.Tools)}, nil
+}
+
+func confirmOverwrite(r io.Reader, w io.Writer, name string) (bool, error) {
+	if _, err := fmt.Fprintf(w, "MCP server %q already exists. Overwrite? [y/N]: ", name); err != nil {
+		return false, err
+	}
+
+	var answer string
+	if _, err := fmt.Fscanln(r, &answer); err != nil {
+		if errors.Is(err, io.EOF) {
+			return false, nil
+		}
+		return false, err
+	}
+
+	answer = strings.TrimSpace(strings.ToLower(answer))
+	return answer == "y" || answer == "yes", nil
+}

cmd/picoclaw/internal/mcp/list.go

@@ -0,0 +1,78 @@
+package mcp
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cliui"
+)
+
+func newListCommand() *cobra.Command {
+	var (
+		includeStatus bool
+		timeout       time.Duration
+	)
+
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List configured MCP servers",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+
+			if len(cfg.Tools.MCP.Servers) == 0 {
+				fmt.Fprintln(cmd.OutOrStdout(), "No MCP servers configured.")
+				return nil
+			}
+
+			rows := make([]cliui.MCPListRow, 0, len(cfg.Tools.MCP.Servers))
+			for _, name := range sortedServerNames(cfg.Tools.MCP.Servers) {
+				server := cfg.Tools.MCP.Servers[name]
+				status := "disabled"
+				if server.Enabled {
+					status = "enabled"
+				}
+
+				if includeStatus && server.Enabled {
+					ctx, cancel := context.WithTimeout(context.Background(), timeout)
+					result, probeErr := serverProbe(ctx, name, server, cfg.WorkspacePath())
+					cancel()
+					if probeErr != nil {
+						status = "error"
+					} else {
+						status = fmt.Sprintf("ok (%d tools)", result.ToolCount)
+					}
+				}
+
+				effectiveDeferred := cfg.Tools.MCP.Discovery.Enabled
+				deferredExplicit := server.Deferred != nil
+				if deferredExplicit {
+					effectiveDeferred = *server.Deferred
+				}
+
+				rows = append(rows, cliui.MCPListRow{
+					Name:              name,
+					Type:              inferTransportType(server),
+					Target:            renderServerTarget(server),
+					Status:            status,
+					EffectiveDeferred: effectiveDeferred,
+					DeferredExplicit:  deferredExplicit,
+				})
+			}
+
+			cliui.PrintMCPList(cmd.OutOrStdout(), rows)
+			return nil
+		},
+	}
+
+	cmd.Flags().BoolVar(&includeStatus, "status", false, "Ping enabled servers and show live status")
+	cmd.Flags().DurationVar(&timeout, "timeout", 5*time.Second, "Timeout for each live status check")
+
+	return cmd
+}

cmd/picoclaw/internal/mcp/remove.go

@@ -0,0 +1,39 @@
+package mcp
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+func newRemoveCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "remove <name>",
+		Short: "Remove an MCP server from config",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+
+			name := args[0]
+			if _, exists := cfg.Tools.MCP.Servers[name]; !exists {
+				return fmt.Errorf("MCP server %q not found", name)
+			}
+
+			delete(cfg.Tools.MCP.Servers, name)
+			if len(cfg.Tools.MCP.Servers) == 0 {
+				cfg.Tools.MCP.Servers = nil
+				cfg.Tools.MCP.Enabled = false
+			}
+
+			if err := saveValidatedConfig(cfg); err != nil {
+				return err
+			}
+
+			fmt.Fprintf(cmd.OutOrStdout(), "✓ MCP server %q removed.\n", name)
+			return nil
+		},
+	}
+}

cmd/picoclaw/internal/mcp/show.go

@@ -0,0 +1,237 @@
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cliui"
+	"github.com/sipeed/picoclaw/pkg/config"
+	picomcp "github.com/sipeed/picoclaw/pkg/mcp"
+)
+
+type toolDetail struct {
+	Name        string
+	Description string
+	Parameters  []paramDetail
+}
+
+type paramDetail struct {
+	Name        string
+	Type        string
+	Description string
+	Required    bool
+}
+
+var serverShowProbe = defaultServerShowProbe
+
+func defaultServerShowProbe(
+	ctx context.Context,
+	name string,
+	server config.MCPServerConfig,
+	workspacePath string,
+) ([]toolDetail, error) {
+	mgr := picomcp.NewManager()
+	defer func() { _ = mgr.Close() }()
+
+	server.Enabled = true
+	mcpCfg := config.MCPConfig{
+		ToolConfig: config.ToolConfig{Enabled: true},
+		Servers: map[string]config.MCPServerConfig{
+			name: server,
+		},
+	}
+
+	if err := mgr.LoadFromMCPConfig(ctx, mcpCfg, workspacePath); err != nil {
+		return nil, err
+	}
+
+	conn, ok := mgr.GetServer(name)
+	if !ok {
+		return nil, fmt.Errorf("server %q did not register a connection", name)
+	}
+
+	details := make([]toolDetail, 0, len(conn.Tools))
+	for _, tool := range conn.Tools {
+		details = append(details, toolDetail{
+			Name:        tool.Name,
+			Description: tool.Description,
+			Parameters:  extractParameters(tool.InputSchema),
+		})
+	}
+	return details, nil
+}
+
+func extractParameters(schema any) []paramDetail {
+	schemaMap := normalizeSchema(schema)
+	properties, ok := schemaMap["properties"].(map[string]any)
+	if !ok || len(properties) == 0 {
+		return nil
+	}
+
+	required := make(map[string]struct{})
+	switch raw := schemaMap["required"].(type) {
+	case []string:
+		for _, name := range raw {
+			required[name] = struct{}{}
+		}
+	case []any:
+		for _, value := range raw {
+			if name, ok := value.(string); ok {
+				required[name] = struct{}{}
+			}
+		}
+	}
+
+	names := make([]string, 0, len(properties))
+	for name := range properties {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	params := make([]paramDetail, 0, len(names))
+	for _, name := range names {
+		param := paramDetail{Name: name}
+		if propMap, ok := properties[name].(map[string]any); ok {
+			if typeName, ok := propMap["type"].(string); ok {
+				param.Type = strings.TrimSpace(typeName)
+			}
+			if desc, ok := propMap["description"].(string); ok {
+				param.Description = strings.TrimSpace(desc)
+			}
+		}
+		_, param.Required = required[name]
+		params = append(params, param)
+	}
+	return params
+}
+
+func normalizeSchema(schema any) map[string]any {
+	if schema == nil {
+		return map[string]any{}
+	}
+	if schemaMap, ok := schema.(map[string]any); ok {
+		return schemaMap
+	}
+
+	var jsonData []byte
+	switch raw := schema.(type) {
+	case json.RawMessage:
+		jsonData = raw
+	case []byte:
+		jsonData = raw
+	default:
+		var err error
+		jsonData, err = json.Marshal(schema)
+		if err != nil {
+			return map[string]any{}
+		}
+	}
+
+	var result map[string]any
+	if err := json.Unmarshal(jsonData, &result); err != nil {
+		return map[string]any{}
+	}
+	return result
+}
+
+func newShowCommand() *cobra.Command {
+	var timeout time.Duration
+
+	cmd := &cobra.Command{
+		Use:   "show <name>",
+		Short: "Show details and tools for a configured MCP server",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+
+			name := args[0]
+			server, exists := cfg.Tools.MCP.Servers[name]
+			if !exists {
+				return fmt.Errorf("MCP server %q not found", name)
+			}
+
+			serverInfo := buildServerInfo(name, server, cfg.Tools.MCP.Discovery.Enabled)
+
+			if !server.Enabled {
+				cliui.PrintMCPShow(cmd.OutOrStdout(), serverInfo, nil, true)
+				return nil
+			}
+
+			ctx, cancel := context.WithTimeout(context.Background(), timeout)
+			defer cancel()
+
+			details, err := serverShowProbe(ctx, name, server, cfg.WorkspacePath())
+			if err != nil {
+				return fmt.Errorf("failed to connect to MCP server %q: %w", name, err)
+			}
+
+			tools := make([]cliui.MCPShowTool, 0, len(details))
+			for _, d := range details {
+				params := make([]cliui.MCPShowParam, 0, len(d.Parameters))
+				for _, p := range d.Parameters {
+					params = append(params, cliui.MCPShowParam{
+						Name:        p.Name,
+						Type:        p.Type,
+						Description: p.Description,
+						Required:    p.Required,
+					})
+				}
+				tools = append(tools, cliui.MCPShowTool{
+					Name:        d.Name,
+					Description: d.Description,
+					Parameters:  params,
+				})
+			}
+
+			cliui.PrintMCPShow(cmd.OutOrStdout(), serverInfo, tools, false)
+			return nil
+		},
+	}
+
+	cmd.Flags().DurationVar(&timeout, "timeout", 10*time.Second, "Connection timeout")
+
+	return cmd
+}
+
+func buildServerInfo(name string, server config.MCPServerConfig, discoveryEnabled bool) cliui.MCPShowServer {
+	effectiveDeferred := discoveryEnabled
+	deferredExplicit := server.Deferred != nil
+	if deferredExplicit {
+		effectiveDeferred = *server.Deferred
+	}
+	info := cliui.MCPShowServer{
+		Name:              name,
+		Type:              inferTransportType(server),
+		Target:            renderServerTarget(server),
+		Enabled:           server.Enabled,
+		EffectiveDeferred: effectiveDeferred,
+		DeferredExplicit:  deferredExplicit,
+		EnvFile:           server.EnvFile,
+	}
+	if len(server.Env) > 0 {
+		keys := make([]string, 0, len(server.Env))
+		for k := range server.Env {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		info.EnvKeys = keys
+	}
+	if len(server.Headers) > 0 {
+		keys := make([]string, 0, len(server.Headers))
+		for k := range server.Headers {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		info.Headers = keys
+	}
+	return info
+}

cmd/picoclaw/internal/mcp/test.go

@@ -0,0 +1,46 @@
+package mcp
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+func newTestCommand() *cobra.Command {
+	var timeout time.Duration
+
+	cmd := &cobra.Command{
+		Use:   "test <name>",
+		Short: "Test connectivity for a configured MCP server",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+
+			name := args[0]
+			server, exists := cfg.Tools.MCP.Servers[name]
+			if !exists {
+				return fmt.Errorf("MCP server %q not found", name)
+			}
+
+			ctx, cancel := context.WithTimeout(context.Background(), timeout)
+			defer cancel()
+
+			result, err := serverProbe(ctx, name, server, cfg.WorkspacePath())
+			if err != nil {
+				return fmt.Errorf("failed to reach MCP server %q: %w", name, err)
+			}
+
+			fmt.Fprintf(cmd.OutOrStdout(), "✓ MCP server %q reachable (%d tools).\n", name, result.ToolCount)
+			return nil
+		},
+	}
+
+	cmd.Flags().DurationVar(&timeout, "timeout", 5*time.Second, "Connection timeout")
+
+	return cmd
+}

cmd/picoclaw/internal/model/add.go

@@ -0,0 +1,200 @@
+package model
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"strconv"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+const defaultAliasName = "custom-prefer"
+
+func newAddCommand() *cobra.Command {
+	var (
+		apiBase   string
+		apiKey    string
+		modelID   string
+		alias     string
+		modelType string
+	)
+
+	cmd := &cobra.Command{
+		Use:   "add",
+		Short: "Add a model from an OpenAI-compatible endpoint",
+		Long: `Add a model entry by querying an OpenAI-compatible endpoint exposing
+GET <api-base>/models, then setting it as the default model.
+
+If --model is omitted, the available models are listed and you can pick one
+interactively. If --model is provided, the entry is written without contacting
+the server.
+
+Sample interactive session (key shown masked):
+
+    $ picoclaw model add \
+        -b https://ark.cn-beijing.volces.com/api/v3 \
+        -k 7dff****-****-****-****-********e829
+
+    115 model(s) available:
+        1) doubao-lite-128k-240428    (doubao-lite-128k)
+        2) doubao-pro-128k-240515     (doubao-pro-128k)
+        ...
+       48) deepseek-r1-250120          (deepseek-r1)
+       78) kimi-k2-250711              (kimi-k2)
+        ...
+      115) doubao-seed3d-2-0-260328    (doubao-seed3d-2-0)
+    Pick a model (number or id): 48
+    ✓ Saved model 'custom-prefer' (deepseek-r1-250120) and set as default.`,
+		Example: `  picoclaw model add --api-base https://api.openai.com/v1 --api-key sk-...
+  picoclaw model add -b http://localhost:8000/v1 -k dummy -m my-model -n local`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return runAdd(addOptions{
+				apiBase:   strings.TrimSpace(apiBase),
+				apiKey:    strings.TrimSpace(apiKey),
+				modelID:   strings.TrimSpace(modelID),
+				alias:     strings.TrimSpace(alias),
+				modelType: strings.TrimSpace(modelType),
+				stdin:     cmd.InOrStdin(),
+				stdout:    cmd.OutOrStdout(),
+			})
+		},
+	}
+
+	cmd.Flags().StringVarP(&apiBase, "api-base", "b", "",
+		"API base URL (required), e.g. https://api.openai.com/v1")
+	cmd.Flags().StringVarP(&apiKey, "api-key", "k", "", "API key (required)")
+	cmd.Flags().StringVarP(&modelID, "model", "m", "",
+		"Model id; when set, skips the interactive picker and the network call")
+	cmd.Flags().StringVarP(&alias, "name", "n", defaultAliasName,
+		"Local alias written to model_list and used as the default model name")
+	cmd.Flags().StringVar(&modelType, "type", "openai-compatible",
+		"Endpoint type (only 'openai-compatible' is supported today)")
+	_ = cmd.MarkFlagRequired("api-base")
+	_ = cmd.MarkFlagRequired("api-key")
+
+	return cmd
+}
+
+type addOptions struct {
+	apiBase   string
+	apiKey    string
+	modelID   string
+	alias     string
+	modelType string
+	stdin     io.Reader
+	stdout    io.Writer
+}
+
+func runAdd(opt addOptions) error {
+	if opt.modelType != "" && opt.modelType != "openai-compatible" {
+		return fmt.Errorf("unsupported --type %q (only 'openai-compatible' is supported)", opt.modelType)
+	}
+	if opt.alias == "" {
+		opt.alias = defaultAliasName
+	}
+
+	selected := opt.modelID
+	if selected == "" {
+		entries, err := fetchOpenAIModels(opt.apiBase, opt.apiKey)
+		if err != nil {
+			return fmt.Errorf("fetch models: %w", err)
+		}
+		if len(entries) == 0 {
+			return fmt.Errorf("no models returned by %s", opt.apiBase)
+		}
+		selected, err = pickModel(opt.stdin, opt.stdout, entries)
+		if err != nil {
+			return err
+		}
+	}
+
+	return upsertModelDefault(opt.apiBase, opt.apiKey, opt.alias, selected, opt.stdout)
+}
+
+func pickModel(stdin io.Reader, stdout io.Writer, entries []modelEntry) (string, error) {
+	fmt.Fprintf(stdout, "\n%d model(s) available:\n", len(entries))
+	for i, m := range entries {
+		line := m.ID
+		if m.Name != "" && m.Name != m.ID {
+			line = fmt.Sprintf("%s (%s)", m.ID, m.Name)
+		}
+		fmt.Fprintf(stdout, "  %3d) %s\n", i+1, line)
+	}
+
+	scanner := bufio.NewScanner(stdin)
+	for {
+		fmt.Fprint(stdout, "Pick a model (number or id): ")
+		if !scanner.Scan() {
+			if err := scanner.Err(); err != nil {
+				return "", fmt.Errorf("read input: %w", err)
+			}
+			return "", fmt.Errorf("no selection provided")
+		}
+		text := strings.TrimSpace(scanner.Text())
+		if text == "" {
+			continue
+		}
+		if idx, err := strconv.Atoi(text); err == nil {
+			if idx < 1 || idx > len(entries) {
+				fmt.Fprintf(stdout, "Out of range. Enter 1-%d.\n", len(entries))
+				continue
+			}
+			return entries[idx-1].ID, nil
+		}
+		for _, m := range entries {
+			if m.ID == text {
+				return m.ID, nil
+			}
+		}
+		fmt.Fprintln(stdout, "Not a valid number or model id; try again.")
+	}
+}
+
+func upsertModelDefault(apiBase, apiKey, alias, modelID string, stdout io.Writer) error {
+	configPath := internal.GetConfigPath()
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		return fmt.Errorf("failed to load config: %w", err)
+	}
+
+	secureKeys := config.SimpleSecureStrings(apiKey)
+
+	found := false
+	for _, m := range cfg.ModelList {
+		if m == nil {
+			continue
+		}
+		if m.ModelName == alias {
+			m.Model = modelID
+			m.APIBase = apiBase
+			m.APIKeys = secureKeys
+			m.Enabled = true
+			found = true
+			break
+		}
+	}
+	if !found {
+		cfg.ModelList = append(cfg.ModelList, &config.ModelConfig{
+			ModelName: alias,
+			Model:     modelID,
+			APIBase:   apiBase,
+			APIKeys:   secureKeys,
+			Enabled:   true,
+		})
+	}
+
+	cfg.Agents.Defaults.ModelName = alias
+
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		return fmt.Errorf("failed to save config: %w", err)
+	}
+
+	fmt.Fprintf(stdout, "✓ Saved model '%s' (%s) and set as default.\n", alias, modelID)
+	return nil
+}

cmd/picoclaw/internal/model/add_test.go

@@ -0,0 +1,257 @@
+package model
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestFetchOpenAIModels_DataEnvelope(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/models", r.URL.Path)
+		assert.Equal(t, "Bearer secret", r.Header.Get("Authorization"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"data":[{"id":"gpt-foo","name":"Foo"},{"id":"gpt-bar"}]}`))
+	}))
+	defer srv.Close()
+
+	entries, err := fetchOpenAIModels(srv.URL, "secret")
+	require.NoError(t, err)
+	require.Len(t, entries, 2)
+	assert.Equal(t, "gpt-foo", entries[0].ID)
+	assert.Equal(t, "Foo", entries[0].Name)
+	assert.Equal(t, "gpt-bar", entries[1].ID)
+}
+
+func TestFetchOpenAIModels_BareArray(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"id":"a"},{"id":"b"}]`))
+	}))
+	defer srv.Close()
+
+	entries, err := fetchOpenAIModels(srv.URL, "secret")
+	require.NoError(t, err)
+	require.Len(t, entries, 2)
+	assert.Equal(t, "a", entries[0].ID)
+	assert.Equal(t, "b", entries[1].ID)
+}
+
+func TestFetchOpenAIModels_TrimsTrailingSlash(t *testing.T) {
+	var gotPath string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		_, _ = w.Write([]byte(`{"data":[{"id":"x"}]}`))
+	}))
+	defer srv.Close()
+
+	_, err := fetchOpenAIModels(srv.URL+"/", "k")
+	require.NoError(t, err)
+	assert.Equal(t, "/models", gotPath)
+}
+
+func TestFetchOpenAIModels_HTTPError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "nope", http.StatusUnauthorized)
+	}))
+	defer srv.Close()
+
+	_, err := fetchOpenAIModels(srv.URL, "bad")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "HTTP 401")
+}
+
+func TestFetchOpenAIModels_EmptyDataEnvelope(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"data":[]}`))
+	}))
+	defer srv.Close()
+
+	entries, err := fetchOpenAIModels(srv.URL, "k")
+	require.NoError(t, err)
+	assert.Empty(t, entries)
+}
+
+func TestFetchOpenAIModels_EmptyBareArray(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`[]`))
+	}))
+	defer srv.Close()
+
+	entries, err := fetchOpenAIModels(srv.URL, "k")
+	require.NoError(t, err)
+	assert.Empty(t, entries)
+}
+
+func TestFetchOpenAIModels_UnrecognizedShape(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"models":"not-supported"}`))
+	}))
+	defer srv.Close()
+
+	_, err := fetchOpenAIModels(srv.URL, "k")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "unrecognized shape")
+}
+
+func TestFetchOpenAIModels_RequiresInputs(t *testing.T) {
+	_, err := fetchOpenAIModels("", "k")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "api base")
+
+	_, err = fetchOpenAIModels("https://example.com", "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "api key")
+}
+
+func TestPickModel_ByIndex(t *testing.T) {
+	entries := []modelEntry{{ID: "a"}, {ID: "b"}, {ID: "c"}}
+	out := &bytes.Buffer{}
+	got, err := pickModel(strings.NewReader("2\n"), out, entries)
+	require.NoError(t, err)
+	assert.Equal(t, "b", got)
+	assert.Contains(t, out.String(), "3 model(s) available")
+}
+
+func TestPickModel_ByID(t *testing.T) {
+	entries := []modelEntry{{ID: "alpha"}, {ID: "beta"}}
+	out := &bytes.Buffer{}
+	got, err := pickModel(strings.NewReader("beta\n"), out, entries)
+	require.NoError(t, err)
+	assert.Equal(t, "beta", got)
+}
+
+func TestPickModel_RetriesOnInvalid(t *testing.T) {
+	entries := []modelEntry{{ID: "x"}}
+	out := &bytes.Buffer{}
+	got, err := pickModel(strings.NewReader("\n9\nnot-a-model\nx\n"), out, entries)
+	require.NoError(t, err)
+	assert.Equal(t, "x", got)
+	rendered := out.String()
+	assert.Contains(t, rendered, "Out of range")
+	assert.Contains(t, rendered, "Not a valid number")
+}
+
+func TestRunAdd_WithExplicitModel_NoNetwork(t *testing.T) {
+	initTest(t)
+
+	out := &bytes.Buffer{}
+	err := runAdd(addOptions{
+		apiBase:   "https://invalid.invalid/v1",
+		apiKey:    "k",
+		modelID:   "explicit-model",
+		alias:     "myalias",
+		modelType: "openai-compatible",
+		stdout:    out,
+	})
+	require.NoError(t, err)
+	assert.Contains(t, out.String(), "Saved model 'myalias' (explicit-model)")
+
+	cfg, err := config.LoadConfig(configPath)
+	require.NoError(t, err)
+	assert.Equal(t, "myalias", cfg.Agents.Defaults.GetModelName())
+	added := findModelByName(cfg, "myalias")
+	require.NotNil(t, added, "expected model 'myalias' in model_list")
+	assert.Equal(t, "explicit-model", added.Model)
+	assert.Equal(t, "https://invalid.invalid/v1", added.APIBase)
+	assert.True(t, added.Enabled)
+	require.Len(t, added.APIKeys, 1)
+	assert.Equal(t, "k", added.APIKeys[0].String())
+}
+
+func findModelByName(cfg *config.Config, name string) *config.ModelConfig {
+	for _, m := range cfg.ModelList {
+		if m != nil && m.ModelName == name {
+			return m
+		}
+	}
+	return nil
+}
+
+func TestRunAdd_FetchAndPick(t *testing.T) {
+	initTest(t)
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "Bearer my-key", r.Header.Get("Authorization"))
+		_, _ = w.Write([]byte(`{"data":[{"id":"m1"},{"id":"m2"}]}`))
+	}))
+	defer srv.Close()
+
+	out := &bytes.Buffer{}
+	err := runAdd(addOptions{
+		apiBase:   srv.URL,
+		apiKey:    "my-key",
+		alias:     defaultAliasName,
+		modelType: "openai-compatible",
+		stdin:     strings.NewReader("2\n"),
+		stdout:    out,
+	})
+	require.NoError(t, err)
+
+	cfg, err := config.LoadConfig(configPath)
+	require.NoError(t, err)
+	assert.Equal(t, defaultAliasName, cfg.Agents.Defaults.GetModelName())
+	added := findModelByName(cfg, defaultAliasName)
+	require.NotNil(t, added)
+	assert.Equal(t, "m2", added.Model)
+}
+
+func TestRunAdd_UpsertsExistingAlias(t *testing.T) {
+	initTest(t)
+
+	first := &bytes.Buffer{}
+	require.NoError(t, runAdd(addOptions{
+		apiBase: "https://a.example/v1",
+		apiKey:  "k1",
+		modelID: "m1",
+		alias:   "shared",
+		stdout:  first,
+	}))
+
+	second := &bytes.Buffer{}
+	require.NoError(t, runAdd(addOptions{
+		apiBase: "https://b.example/v1",
+		apiKey:  "k2",
+		modelID: "m2",
+		alias:   "shared",
+		stdout:  second,
+	}))
+
+	cfg, err := config.LoadConfig(configPath)
+	require.NoError(t, err)
+	matches := 0
+	for _, m := range cfg.ModelList {
+		if m != nil && m.ModelName == "shared" {
+			matches++
+		}
+	}
+	assert.Equal(t, 1, matches, "alias should be updated, not duplicated")
+
+	updated := findModelByName(cfg, "shared")
+	require.NotNil(t, updated)
+	assert.Equal(t, "m2", updated.Model)
+	assert.Equal(t, "https://b.example/v1", updated.APIBase)
+	assert.Equal(t, "k2", updated.APIKeys[0].String())
+}
+
+func TestRunAdd_RejectsUnsupportedType(t *testing.T) {
+	initTest(t)
+
+	err := runAdd(addOptions{
+		apiBase:   "https://x/v1",
+		apiKey:    "k",
+		modelID:   "m",
+		alias:     "a",
+		modelType: "anthropic",
+		stdout:    &bytes.Buffer{},
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "unsupported --type")
+}

cmd/picoclaw/internal/model/command.go

@@ -21,11 +21,17 @@ func NewModelCommand() *cobra.Command {
 If no argument is provided, shows the current default model.
 If a model name is provided, sets it as the default model.
 
+To onboard a model from a custom OpenAI-compatible endpoint (fetch the
+available list online and pick one), use the 'add' subcommand:
+
+  picoclaw model add --help
+
 Examples:
   picoclaw model                    # Show current default model
   picoclaw model gpt-5.2           # Set gpt-5.2 as default
   picoclaw model claude-sonnet-4.6 # Set claude-sonnet-4.6 as default
   picoclaw model local-model       # Set local VLLM server as default
+  picoclaw model add -b URL -k KEY # Add a model from a custom endpoint
 
 Note: 'local-model' is a special value for using a local VLLM server
 (running at localhost:8000 by default) which does not require an API key.`,
@@ -51,6 +57,8 @@ Note: 'local-model' is a special value for using a local VLLM server
 		},
 	}
 
+	cmd.AddCommand(newAddCommand())
+
 	return cmd
 }
 
@@ -66,6 +74,9 @@ func showCurrentModel(cfg *config.Config) {
 		fmt.Println("\nAvailable models in your config:")
 		listAvailableModels(cfg)
 	}
+
+	fmt.Println("\nTip: 'picoclaw model add -b URL -k KEY' adds a model from a custom")
+	fmt.Println("     OpenAI-compatible endpoint (see 'picoclaw model add --help').")
 }
 
 func listAvailableModels(cfg *config.Config) {

cmd/picoclaw/internal/model/online.go

@@ -0,0 +1,77 @@
+package model
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+type modelEntry struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	Description string `json:"description"`
+}
+
+type modelsAPIResponse struct {
+	Data []modelEntry `json:"data"`
+}
+
+// fetchOpenAIModels GETs <baseURL>/models with Bearer auth and accepts both the
+// {data:[…]} envelope and a bare array shape used by various OpenAI-compatible servers.
+func fetchOpenAIModels(baseURL, apiKey string) ([]modelEntry, error) {
+	if strings.TrimSpace(baseURL) == "" {
+		return nil, fmt.Errorf("api base is required")
+	}
+	if strings.TrimSpace(apiKey) == "" {
+		return nil, fmt.Errorf("api key is required")
+	}
+
+	url := strings.TrimRight(baseURL, "/") + "/models"
+
+	client := &http.Client{Timeout: 15 * time.Second}
+	req, err := http.NewRequest(http.MethodGet, url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("build request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+apiKey)
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	// {"data": [...]} envelope. Distinguish "envelope shape with empty list"
+	// from "object without a data key" via Data being non-nil after unmarshal:
+	// json.Unmarshal sets Data to []modelEntry{} for `{"data":[]}` but leaves
+	// it as nil when "data" is absent or null.
+	var envelope modelsAPIResponse
+	if err := json.Unmarshal(body, &envelope); err == nil && envelope.Data != nil {
+		return envelope.Data, nil
+	}
+
+	// Bare-array shape, including `[]`.
+	var arr []modelEntry
+	if err := json.Unmarshal(body, &arr); err == nil {
+		return arr, nil
+	}
+
+	preview := body
+	if len(preview) > 256 {
+		preview = preview[:256]
+	}
+	return nil, fmt.Errorf("decode response: unrecognized shape: %s", strings.TrimSpace(string(preview)))
+}

cmd/picoclaw/internal/onboard/command.go

@@ -6,7 +6,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-//go:generate cp -r ../../../../workspace .
+//go:generate go run ../../../../scripts/copydir.go ../../../../workspace ./workspace
 //go:embed workspace
 var embeddedFiles embed.FS
 

cmd/picoclaw/internal/status/helpers.go

@@ -3,12 +3,12 @@ package status
 import (
 	"fmt"
 	"os"
-	"strings"
 
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cliui"
 	"github.com/sipeed/picoclaw/pkg/auth"
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
 func statusCmd() {
@@ -44,12 +44,13 @@ func statusCmd() {
 		// not depend on a legacy cfg.Providers field (which may not exist under some
 		// build tags). We infer provider availability from model_list entries.
 		hasProtocolKey := func(protocol string) bool {
-			prefix := protocol + "/"
+			want := providers.NormalizeProvider(protocol)
 			for _, m := range cfg.ModelList {
 				if m == nil {
 					continue
 				}
-				if strings.HasPrefix(m.Model, prefix) && m.APIKey() != "" {
+				got, _ := providers.ExtractProtocol(m)
+				if got == want && m.APIKey() != "" {
 					return true
 				}
 			}
@@ -67,12 +68,13 @@ func statusCmd() {
 			return "", false
 		}
 		findProtocolBase := func(protocol string) (string, bool) {
-			prefix := protocol + "/"
+			want := providers.NormalizeProvider(protocol)
 			for _, m := range cfg.ModelList {
 				if m == nil {
 					continue
 				}
-				if strings.HasPrefix(m.Model, prefix) && m.APIBase != "" {
+				got, _ := providers.ExtractProtocol(m)
+				if got == want && m.APIBase != "" {
 					return m.APIBase, true
 				}
 			}

cmd/picoclaw/internal/status/helpers_test.go

@@ -0,0 +1,89 @@
+package status
+
+import (
+	"bytes"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func captureStdout(t *testing.T, fn func()) string {
+	t.Helper()
+
+	oldStdout := os.Stdout
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatalf("os.Pipe() error = %v", err)
+	}
+	os.Stdout = w
+
+	fn()
+
+	_ = w.Close()
+	os.Stdout = oldStdout
+	defer r.Close()
+
+	var buf bytes.Buffer
+	if _, err := io.Copy(&buf, r); err != nil {
+		t.Fatalf("io.Copy() error = %v", err)
+	}
+	return buf.String()
+}
+
+func TestStatusCmd_RecognizesProviderFieldWithoutModelPrefix(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+	workspace := filepath.Join(tmpDir, "workspace")
+	if err := os.MkdirAll(workspace, 0o755); err != nil {
+		t.Fatalf("os.MkdirAll() error = %v", err)
+	}
+
+	t.Setenv(config.EnvConfig, configPath)
+	t.Setenv(config.EnvHome, tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName:   "gpt-5.4",
+				Workspace:   workspace,
+				Provider:    "openai",
+				MaxTokens:   65536,
+				Temperature: nil,
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{
+				ModelName: "gpt-5.4",
+				Provider:  "openai",
+				Model:     "gpt-5.4",
+				APIBase:   "https://api.openai.com/v1",
+				APIKeys:   config.SimpleSecureStrings("test-key"),
+				Enabled:   true,
+			},
+			{
+				ModelName: "qwen-plus",
+				Provider:  "qwen",
+				Model:     "qwen-plus",
+				APIBase:   "https://dashscope.aliyuncs.com/compatible-mode/v1",
+				APIKeys:   config.SimpleSecureStrings("test-key"),
+				Enabled:   true,
+			},
+		},
+	}
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("config.SaveConfig() error = %v", err)
+	}
+
+	output := captureStdout(t, statusCmd)
+
+	if !strings.Contains(output, "OpenAI API: \u2713") {
+		t.Fatalf("status output missing OpenAI provider: %s", output)
+	}
+	if !strings.Contains(output, "Qwen API: \u2713") {
+		t.Fatalf("status output missing Qwen provider: %s", output)
+	}
+}

cmd/picoclaw/main.go

@@ -19,6 +19,7 @@ import (
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cliui"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cron"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/gateway"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/mcp"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/migrate"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/model"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/onboard"
@@ -87,6 +88,7 @@ picoclaw --no-color status`,
 		gateway.NewGatewayCommand(),
 		status.NewStatusCommand(),
 		cron.NewCronCommand(),
+		mcp.NewMCPCommand(),
 		migrate.NewMigrateCommand(),
 		skills.NewSkillsCommand(),
 		model.NewModelCommand(),

cmd/picoclaw/main_test.go

@@ -41,6 +41,7 @@ func TestNewPicoclawCommand(t *testing.T) {
 		"auth",
 		"cron",
 		"gateway",
+		"mcp",
 		"migrate",
 		"model",
 		"onboard",

config/config.example.json

@@ -13,7 +13,8 @@
       "split_on_marker": false,
       "tool_feedback": {
         "enabled": false,
-        "max_args_length": 300
+        "max_args_length": 300,
+        "separate_messages": false
       }
     }
   },
@@ -436,6 +437,9 @@
       "enabled": true,
       "mode": "bytes"
     },
+    "serial": {
+      "enabled": false
+    },
     "send_tts": {
       "enabled": false
     },

docker/Dockerfile.full

@@ -1,7 +1,7 @@
 # ============================================================
 # Stage 1: Build the picoclaw binary
 # ============================================================
-FROM golang:1.26.0-alpine AS builder
+FROM golang:1.25-alpine AS builder
 
 RUN apk add --no-cache git make
 

docker/Dockerfile.goreleaser.launcher

@@ -6,7 +6,6 @@ RUN apk add --no-cache ca-certificates tzdata
 
 COPY $TARGETPLATFORM/picoclaw /usr/local/bin/picoclaw
 COPY $TARGETPLATFORM/picoclaw-launcher /usr/local/bin/picoclaw-launcher
-COPY $TARGETPLATFORM/picoclaw-launcher-tui /usr/local/bin/picoclaw-launcher-tui
 
 ENTRYPOINT ["picoclaw-launcher"]
 CMD ["-console", "-public", "-no-browser"]

docker/Dockerfile.heavy

@@ -1,7 +1,7 @@
 # ============================================================
 # Stage 1: Build the picoclaw binary
 # ============================================================
-FROM golang:1.26.0-alpine AS builder
+FROM golang:1.25-alpine AS builder
 
 RUN apk add --no-cache git make
 

docker/Dockerfile.launcher

@@ -0,0 +1,65 @@
+# ============================================================
+# Stage 1: Build frontend assets (Node.js + pnpm)
+# ============================================================
+FROM node:24-alpine3.23 AS frontend
+
+RUN corepack enable && corepack prepare pnpm@latest --activate
+
+WORKDIR /src/web/frontend
+
+# Cache frontend dependencies
+COPY web/frontend/package.json web/frontend/pnpm-lock.yaml ./
+RUN CI=true pnpm install --frozen-lockfile
+
+# Build frontend
+COPY web/frontend/ ./
+RUN pnpm build:backend
+
+# ============================================================
+# Stage 2: Build Go binaries (picoclaw + picoclaw-launcher)
+# ============================================================
+FROM golang:1.25-alpine AS builder
+
+RUN apk add --no-cache git make
+
+WORKDIR /src
+
+# Cache Go dependencies
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source
+COPY . .
+
+# Copy pre-built frontend assets into the backend embed directory
+COPY --from=frontend /src/web/backend/dist web/backend/dist
+
+# Build picoclaw binary (includes go generate)
+RUN make build
+
+# Build picoclaw-launcher binary (frontend already built in stage 1)
+# Mirror ldflags from web/Makefile to inject version metadata
+RUN CONFIG_PKG=github.com/sipeed/picoclaw/pkg/config && \
+    VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo dev) && \
+    GIT_COMMIT=$(git rev-parse --short=8 HEAD 2>/dev/null || echo dev) && \
+    BUILD_TIME=$(date +%FT%T%z) && \
+    GO_VERSION=$(go env GOVERSION) && \
+    CGO_ENABLED=0 go build -v -tags goolm,stdjson \
+      -ldflags "-X ${CONFIG_PKG}.Version=${VERSION} -X ${CONFIG_PKG}.GitCommit=${GIT_COMMIT} -X ${CONFIG_PKG}.BuildTime=${BUILD_TIME} -X ${CONFIG_PKG}.GoVersion=${GO_VERSION} -s -w" \
+      -o build/picoclaw-launcher ./web/backend/
+
+# ============================================================
+# Stage 3: Minimal runtime image
+# ============================================================
+FROM alpine:3.23
+
+RUN apk add --no-cache ca-certificates tzdata curl
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget -q --spider http://localhost:18790/health || exit 1
+
+COPY --from=builder /src/build/picoclaw /usr/local/bin/picoclaw
+COPY --from=builder /src/build/picoclaw-launcher /usr/local/bin/picoclaw-launcher
+
+ENTRYPOINT ["picoclaw-launcher"]
+CMD ["-console", "-public", "-no-browser"]

docker/docker-compose.yml

@@ -4,6 +4,9 @@ services:
   #   docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Hello"
   # ─────────────────────────────────────────────
   picoclaw-agent:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
     image: docker.io/sipeed/picoclaw:latest
     container_name: picoclaw-agent
     profiles:
@@ -22,6 +25,9 @@ services:
   #   docker compose -f docker/docker-compose.yml --profile gateway up
   # ─────────────────────────────────────────────
   picoclaw-gateway:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
     image: docker.io/sipeed/picoclaw:latest
     container_name: picoclaw-gateway
     restart: unless-stopped
@@ -38,6 +44,9 @@ services:
   #   docker compose -f docker/docker-compose.yml --profile launcher up
   # ─────────────────────────────────────────────
   picoclaw-launcher:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.launcher
     image: docker.io/sipeed/picoclaw:launcher
     container_name: picoclaw-launcher
     restart: unless-stopped

docker/entrypoint.sh

@@ -12,4 +12,10 @@ if [ ! -d "${HOME}/.picoclaw/workspace" ] && [ ! -f "${HOME}/.picoclaw/config.js
     exit 0
 fi
 
+# Remove stale PID file from a previous container run.
+# After docker kill / OOM / crash the PID file may linger on the bind-mounted
+# volume and block the next gateway start (the recorded PID could collide with
+# an unrelated process inside the new container).
+rm -f "${HOME}/.picoclaw/.picoclaw.pid"
+
 exec picoclaw gateway "$@"

docs/channels/discord/README.md

@@ -8,26 +8,56 @@ Discord is a free voice, video, and text chat application designed for communiti
 
 ```json
 {
+  "agents": {
+    "defaults": {
+      "tool_feedback": {
+        "enabled": true,
+        "max_args_length": 300
+      }
+    }
+  },
   "channel_list": {
     "discord": {
       "enabled": true,
       "type": "discord",
       "token": "YOUR_BOT_TOKEN",
       "allow_from": ["YOUR_USER_ID"],
+      "placeholder": {
+        "enabled": true,
+        "text": ["Thinking... 💭"]
+      },
       "group_trigger": {
         "mention_only": false
-      }
+      },
+      "reasoning_channel_id": ""
     }
   }
 }
 ```
 
-| Field         | Type   | Required | Description                                                                 |
-| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
-| enabled       | bool   | Yes      | Whether to enable the Discord channel                                       |
-| token         | string | Yes      | Discord Bot Token                                                           |
-| allow_from    | array  | No       | Allowlist of user IDs; empty means all users are allowed                    |
-| group_trigger | object | No       | Group trigger settings (example: { "mention_only": false })                 |
+| Field                | Type   | Required | Description                                                                 |
+| -------------------- | ------ | -------- | --------------------------------------------------------------------------- |
+| enabled              | bool   | Yes      | Whether to enable the Discord channel                                       |
+| token                | string | Yes      | Discord Bot Token                                                           |
+| allow_from           | array  | No       | Allowlist of user IDs; empty means all users are allowed                    |
+| placeholder          | object | No       | Placeholder message config shown while the agent is working                 |
+| group_trigger        | object | No       | Group trigger settings (example: { "mention_only": false })                 |
+| reasoning_channel_id | string | No       | Optional target channel ID for reasoning/thinking output                    |
+
+## Visible Execution Feedback
+
+Discord can show three different kinds of "working" feedback:
+
+1. Typing indicator: automatic, no extra config needed.
+2. Placeholder message: enable `channel_list.discord.placeholder.enabled` to send a visible `Thinking...` message that is later edited into the final reply.
+3. Tool execution feedback: enable `agents.defaults.tool_feedback.enabled` to send a short message before each tool call, for example:
+
+```text
+🔧 `web_search`
+Checking the latest PicoClaw release notes before I answer.
+```
+
+If you only see `Bot is typing`, check that `placeholder.enabled` or `tool_feedback.enabled` is actually set in your runtime config.
 
 ## Setup
 

docs/channels/telegram/README.md

@@ -44,6 +44,8 @@ Telegram auto-registers PicoClaw's top-level bot commands at startup, including
 Skill-related commands:
 
 - `/list skills` lists the installed skills visible to the current agent.
+- `/list mcp` lists configured MCP servers and whether they are deferred/connected.
+- `/show mcp <server>` lists the active tools for a connected MCP server.
 - `/use <skill> <message>` forces a skill for a single request.
 - `/use <skill>` arms the skill for your next message in the same chat.
 - `/use clear` clears a pending skill override.
@@ -52,6 +54,8 @@ Examples:
 
 ```text
 /list skills
+/list mcp
+/show mcp github
 /use git explain how to squash the last 3 commits
 /use git
 explain how to squash the last 3 commits

docs/design/current-hardware-support-and-serial.zh.md

@@ -0,0 +1,91 @@
+# 当前硬件支持现状与串口 Tool 方案
+
+## 现状结论
+
+当前项目已有的硬件相关能力主要分为两条线：
+
+1. 设备事件监控
+   - `pkg/devices` 已实现设备事件服务。
+   - 当前只有 Linux USB 热插拔事件源 `pkg/devices/sources/usb_linux.go`。
+   - 能力定位是“发现和通知”，不是“总线读写控制”。
+
+2. 硬件控制 Tool
+   - `pkg/tools/hardware/i2c*.go`：I2C Tool，支持 `detect`、`scan`、`read`、`write`。
+   - `pkg/tools/hardware/spi*.go`：SPI Tool，支持 `list`、`transfer`、`read`。
+   - 这两类 Tool 当前都只在 Linux 主机上启用，直接依赖 `/dev/i2c-*` 与 `/dev/spidev*`。
+
+因此，项目在“硬件支持能力”上已经具备：
+
+- Linux USB 设备插拔感知
+- Linux I2C 总线控制
+- Linux SPI 总线控制
+
+但还缺少：
+
+- 串口/UART 控制
+- macOS / Windows 下可直接使用的硬件控制 Tool
+- 面向统一硬件抽象的跨总线能力模型
+
+## 本次新增
+
+本次新增内建 `serial` Tool，并接入现有 Tool 体系：
+
+- 配置项：`tools.serial.enabled`
+- Tool 注册：`pkg/agent/agent_init.go`
+- Web 工具页：`/api/tools` 能展示与切换 `serial`
+- 前端状态文案：新增 `requires_serial_platform`
+
+## Serial Tool 设计
+
+`serial` 采用无状态调用模型，每次请求都自行打开和关闭端口，避免在 agent 回合之间维护串口会话状态。
+
+支持动作：
+
+- `list`：枚举主机串口
+- `read`：从串口读取指定长度字节
+- `write`：向串口写入字节或文本
+
+公共参数：
+
+- `port`
+- `baud`
+- `data_bits`
+- `parity`
+- `stop_bits`
+- `timeout_ms`
+
+当前波特率实现边界：
+
+- Windows 允许配置工具层接受的范围 `50-4000000`
+- Linux / macOS 当前仅支持标准 termios 波特率，实际支持到 `230400`
+- 因此 `baud` 的跨平台可移植取值应优先使用 `230400` 及以下的常见标准速率
+
+安全约束：
+
+- `write` 必须显式传 `confirm: true`
+- 单次读写负载限制为 `4096` 字节
+- `port` 只接受白名单串口名：
+  - Linux / macOS 仅允许 `/dev/tty*`、`/dev/cu.*` 及对应简写设备名
+  - Windows 仅允许 `COM\d+` 或 `\\.\COM\d+`
+  - 明确拒绝 `..`、普通文件绝对路径、盘符路径等非串口设备路径，避免路径穿越或误打开任意文件
+
+## 跨平台实现边界
+
+- Linux / macOS：
+  - 基于 `golang.org/x/sys/unix` 和 termios 配置串口参数。
+  - 当前仅接入标准 termios 波特率映射，最高到 `230400`，尚未扩展 `460800`、`921600`、`1000000`、`2000000` 等更高速率。
+  - 通过 `/dev/...` 枚举和访问设备。
+
+- Windows：
+  - 基于 `kernel32` 串口 API 配置 `DCB` 和 `COMMTIMEOUTS`。
+  - 当前读写仍使用同步 `ReadFile` / `WriteFile`；一旦 syscall 已进入执行，turn context cancellation 不能立即打断，只能等待 `COMMTIMEOUTS` 触发后返回。
+  - 通过注册表 `HARDWARE\\DEVICEMAP\\SERIALCOMM` 枚举端口。
+
+- 其他平台：
+  - `serial` Tool 显式返回 unsupported，不做静默降级。
+
+## 后续建议
+
+1. 如果需要持续交互式串口会话，建议再增加 session 型 Tool，而不是让 LLM 反复做短连接轮询。
+2. 如果后续要支持 CAN、GPIO、PWM，建议抽出统一的硬件 capability 描述层，而不是继续只靠 Tool 名称区分。
+3. 若需要生产级稳定性，建议补真实串口回环测试，至少覆盖 Linux PTY 和 Windows COM 模拟场景。

docs/guides/chat-apps.md

@@ -67,9 +67,11 @@ Telegram command menu registration remains channel-local discovery UX; generic c
 
 If command registration fails (network/API transient errors), the channel still starts and PicoClaw retries registration in the background.
 
-You can also manage installed skills directly from Telegram:
+You can also inspect skills and MCP servers directly from Telegram:
 
 - `/list skills`
+- `/list mcp`
+- `/show mcp <server>`
 - `/use <skill> <message>`
 - `/use <skill>` and then send the actual request in the next message
 - `/use clear`

docs/guides/configuration.md

@@ -98,9 +98,11 @@ export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
 
 ### Using Skills From Chat Channels
 
-Once skills are installed, you can inspect and force them directly from a chat channel:
+Once skills are installed, and MCP servers are configured, you can inspect and force them directly from a chat channel:
 
 - `/list skills` shows the installed skill names available to the current agent.
+- `/list mcp` shows configured MCP servers with enabled/deferred/connected status.
+- `/show mcp <server>` shows the active tools exposed by a connected MCP server.
 - `/use <skill> <message>` forces a specific skill for a single request.
 - `/use <skill>` arms that skill for your next message in the same chat session.
 - `/use clear` cancels a pending skill override created by `/use <skill>`.
@@ -110,6 +112,8 @@ Examples:
 
 ```text
 /list skills
+/list mcp
+/show mcp github
 /use git explain how to squash the last 3 commits
 /btw remind me what we already decided about the deploy plan
 /use italiapersonalfinance
@@ -494,7 +498,7 @@ The subagent has access to tools (message, web_search, etc.) and can communicate
 
 ### Model Configuration (model_list)
 
-> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers — **zero code changes required!**
+> **What's New?** PicoClaw now prefers explicit `provider` + native `model` configuration (for example `"provider": "zhipu", "model": "glm-4.7"`). The legacy single-field `provider/model` form remains supported for compatibility when `provider` is omitted.
 
 This design also enables **multi-agent support** with flexible provider selection:
 
@@ -547,7 +551,8 @@ chmod 600 ~/.picoclaw/.security.yml
   "model_list": [
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4"
+      "provider": "openai",
+      "model": "gpt-5.4"
       // api_key loaded from .security.yml
     }
   ],
@@ -571,31 +576,31 @@ For complete documentation, see [`../security/security_configuration.md`](../sec
 
 #### All Supported Vendors
 
-| Vendor                  | `model` Prefix    | Default API Base                                    | Protocol  | API Key                                                          |
+| Vendor                  | `provider` Value  | Default API Base                                    | Protocol  | API Key                                                          |
 | ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
-| **OpenAI**              | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [Get Key](https://platform.openai.com)                           |
-| **Anthropic**           | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [Get Key](https://console.anthropic.com)                         |
-| **智谱 AI (GLM)**       | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
-| **DeepSeek**            | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [Get Key](https://platform.deepseek.com)                         |
-| **Google Gemini**       | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | Gemini    | [Get Key](https://aistudio.google.com/api-keys)                  |
-| **Groq**                | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [Get Key](https://console.groq.com)                              |
-| **Moonshot**            | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [Get Key](https://platform.moonshot.cn)                          |
-| **通义千问 (Qwen)**     | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
-| **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)                                            |
-| **LM Studio**           | `lmstudio/`       | `http://localhost:1234/v1`                          | OpenAI    | Optional (local default: no key)                                 |
-| **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                                           |
-| **VLLM**                | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
-| **Cerebras**            | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
-| **VolcEngine (Doubao)** | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
-| **神算云**              | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | —                                                                |
-| **BytePlus**            | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [Get Key](https://www.byteplus.com)                              |
-| **Vivgrid**             | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
-| **LongCat**             | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [Get Key](https://longcat.chat/platform)                         |
-| **ModelScope (魔搭)**   | `modelscope/`     | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [Get Token](https://modelscope.cn/my/tokens)                     |
-| **Antigravity**         | `antigravity/`    | Google Cloud                                        | Custom    | OAuth only                                                       |
-| **GitHub Copilot**      | `github-copilot/` | `localhost:4321`                                    | gRPC      | —                                                                |
+| **OpenAI**              | `openai`          | `https://api.openai.com/v1`                         | OpenAI    | [Get Key](https://platform.openai.com)                           |
+| **Anthropic**           | `anthropic`       | `https://api.anthropic.com/v1`                      | Anthropic | [Get Key](https://console.anthropic.com)                         |
+| **智谱 AI (GLM)**       | `zhipu`           | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek**            | `deepseek`        | `https://api.deepseek.com/v1`                       | OpenAI    | [Get Key](https://platform.deepseek.com)                         |
+| **Google Gemini**       | `gemini`          | `https://generativelanguage.googleapis.com/v1beta`  | Gemini    | [Get Key](https://aistudio.google.com/api-keys)                  |
+| **Groq**                | `groq`            | `https://api.groq.com/openai/v1`                    | OpenAI    | [Get Key](https://console.groq.com)                              |
+| **Moonshot**            | `moonshot`        | `https://api.moonshot.cn/v1`                        | OpenAI    | [Get Key](https://platform.moonshot.cn)                          |
+| **通义千问 (Qwen)**     | `qwen`            | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
+| **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)                                            |
+| **LM Studio**           | `lmstudio`        | `http://localhost:1234/v1`                          | OpenAI    | Optional (local default: no key)                                 |
+| **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                                           |
+| **VLLM**                | `vllm`            | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
+| **Cerebras**            | `cerebras`        | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
+| **VolcEngine (Doubao)** | `volcengine`      | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **神算云**              | `shengsuanyun`    | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | —                                                                |
+| **BytePlus**            | `byteplus`        | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [Get Key](https://www.byteplus.com)                              |
+| **Vivgrid**             | `vivgrid`         | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
+| **LongCat**             | `longcat`         | `https://api.longcat.chat/openai`                   | OpenAI    | [Get Key](https://longcat.chat/platform)                         |
+| **ModelScope (魔搭)**   | `modelscope`      | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [Get Token](https://modelscope.cn/my/tokens)                     |
+| **Antigravity**         | `antigravity`     | Google Cloud                                        | Custom    | OAuth only                                                       |
+| **GitHub Copilot**      | `github-copilot`  | `localhost:4321`                                    | gRPC      | —                                                                |
 
 #### Basic Configuration
 
@@ -604,22 +609,26 @@ For complete documentation, see [`../security/security_configuration.md`](../sec
   "model_list": [
     {
       "model_name": "ark-code-latest",
-      "model": "volcengine/ark-code-latest",
+      "provider": "volcengine",
+      "model": "ark-code-latest",
       "api_keys": ["sk-your-api-key"]
     },
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-your-openai-key"]
     },
     {
       "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
+      "provider": "anthropic",
+      "model": "claude-sonnet-4.6",
       "api_keys": ["sk-ant-your-key"]
     },
     {
       "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
+      "provider": "zhipu",
+      "model": "glm-4.7",
       "api_keys": ["your-zhipu-key"]
     }
   ],
@@ -635,6 +644,13 @@ For complete documentation, see [`../security/security_configuration.md`](../sec
 >
 > **Note**: The `enabled` field can be set to `false` to disable a model entry without removing it. When omitted, it defaults to `true` during migration for models that have API keys.
 
+Resolution rules:
+
+- Prefer explicit `"provider": "openai", "model": "gpt-5.4"`.
+- If `provider` is set, PicoClaw sends `model` unchanged.
+- If `provider` is omitted, PicoClaw treats the first `/` segment in `model` as the provider and everything after that first `/` as the runtime model ID.
+- This means `"model": "openrouter/openai/gpt-5.4"` still works as a compatibility form and sends `openai/gpt-5.4` to OpenRouter.
+
 #### Vendor-Specific Examples
 
 > **Tip**: You can omit `api_key` fields and store them in `.security.yml` for better security. See [Security Configuration](#-security-configuration-recommended).
@@ -645,7 +661,8 @@ For complete documentation, see [`../security/security_configuration.md`](../sec
 ```json
 {
   "model_name": "gpt-5.4",
-  "model": "openai/gpt-5.4"
+  "provider": "openai",
+  "model": "gpt-5.4"
   // api_key: set in .security.yml
 }
 ```
@@ -658,7 +675,8 @@ For complete documentation, see [`../security/security_configuration.md`](../sec
 ```json
 {
   "model_name": "ark-code-latest",
-  "model": "volcengine/ark-code-latest"
+  "provider": "volcengine",
+  "model": "ark-code-latest"
   // api_key: set in .security.yml
 }
 ```
@@ -671,7 +689,8 @@ For complete documentation, see [`../security/security_configuration.md`](../sec
 ```json
 {
   "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7"
+  "provider": "zhipu",
+  "model": "glm-4.7"
   // api_key: set in .security.yml
 }
 ```
@@ -684,7 +703,8 @@ For complete documentation, see [`../security/security_configuration.md`](../sec
 ```json
 {
   "model_name": "deepseek-chat",
-  "model": "deepseek/deepseek-chat"
+  "provider": "deepseek",
+  "model": "deepseek-chat"
   // api_key: set in .security.yml
 }
 ```
@@ -697,7 +717,8 @@ For complete documentation, see [`../security/security_configuration.md`](../sec
 ```json
 {
   "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6"
+  "provider": "anthropic",
+  "model": "claude-sonnet-4.6"
   // api_key: set in .security.yml
 }
 ```
@@ -709,7 +730,8 @@ For direct Anthropic API access or custom endpoints that only support Anthropic'
 ```json
 {
   "model_name": "claude-opus-4-6",
-  "model": "anthropic-messages/claude-opus-4-6",
+  "provider": "anthropic-messages",
+  "model": "claude-opus-4-6",
   "api_keys": ["sk-ant-your-key"],
   "api_base": "https://api.anthropic.com"
 }
@@ -725,7 +747,8 @@ For direct Anthropic API access or custom endpoints that only support Anthropic'
 ```json
 {
   "model_name": "llama3",
-  "model": "ollama/llama3"
+  "provider": "ollama",
+  "model": "llama3"
 }
 ```
 
@@ -737,12 +760,13 @@ For direct Anthropic API access or custom endpoints that only support Anthropic'
 ```json
 {
   "model_name": "lmstudio-local",
-  "model": "lmstudio/openai/gpt-oss-20b"
+  "provider": "lmstudio",
+  "model": "openai/gpt-oss-20b"
 }
 ```
 
 `api_base` defaults to `http://localhost:1234/v1`. API key is optional unless your LM Studio server enables authentication.<br/>
-PicoClaw sends OpenAI-compatible requests to LM Studio, and strips the `lmstudio/` prefix before sending requests, so `lmstudio/openai/gpt-oss-20b` sends `openai/gpt-oss-20b` to the LM Studio server.
+With explicit `provider`, PicoClaw sends `openai/gpt-oss-20b` unchanged to LM Studio. The legacy compatibility form `"model": "lmstudio/openai/gpt-oss-20b"` still resolves to the same upstream model ID when `provider` is omitted.
 
 </details>
 
@@ -752,13 +776,14 @@ PicoClaw sends OpenAI-compatible requests to LM Studio, and strips the `lmstudio
 ```json
 {
   "model_name": "my-custom-model",
-  "model": "openai/custom-model",
+  "provider": "openai",
+  "model": "custom-model",
   "api_base": "https://my-proxy.com/v1"
   // api_key: set in .security.yml
 }
 ```
 
-PicoClaw strips only the outer `litellm/` prefix before sending the request, so `litellm/lite-gpt4` sends `lite-gpt4`, while `litellm/openai/gpt-4o` sends `openai/gpt-4o`.
+With explicit `provider`, PicoClaw sends `model` unchanged. That means `"provider": "litellm", "model": "lite-gpt4"` sends `lite-gpt4`, while `"provider": "litellm", "model": "openai/gpt-4o"` sends `openai/gpt-4o`. The legacy compatibility forms `litellm/lite-gpt4` and `litellm/openai/gpt-4o` still resolve the same way when `provider` is omitted.
 
 </details>
 
@@ -783,7 +808,8 @@ model_list:
   "model_list": [
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_base": "https://api.openai.com/v1"
       // api_keys loaded from .security.yml
     }
@@ -798,13 +824,15 @@ model_list:
   "model_list": [
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_base": "https://api1.example.com/v1",
       "api_keys": ["sk-key1"]
     },
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_base": "https://api2.example.com/v1",
       "api_keys": ["sk-key2"]
     }
@@ -864,7 +892,7 @@ This keeps the runtime lightweight while making new OpenAI-compatible backends m
 {
   "agents": {
     "defaults": {
-      "model": "anthropic/claude-opus-4-5"
+      "model_name": "claude-opus-4-5"
     }
   },
   "session": {

docs/guides/configuration.zh.md

@@ -425,7 +425,7 @@ Agent 读取 HEARTBEAT.md
 
 ### 模型配置 (model_list)
 
-> **新特性：** PicoClaw 现在采用**以模型为中心**的配置方式。只需指定 `vendor/model` 格式（例如 `zhipu/glm-4.7`）即可接入新提供商——**无需修改任何代码！**
+> **新特性：** PicoClaw 现在优先推荐显式 `provider` + 原生 `model` 的配置方式，例如 `"provider": "zhipu", "model": "glm-4.7"`。如果未设置 `provider`，旧的单字段 `provider/model` 写法仍然兼容。
 
 这一设计同时支持**多 Agent**场景，灵活选择提供商：
 
@@ -436,31 +436,31 @@ Agent 读取 HEARTBEAT.md
 
 #### 所有支持的厂商
 
-| 厂商                    | `model` 前缀      | 默认 API Base                                       | 协议      | API Key                                                          |
+| 厂商                    | `provider` 值     | 默认 API Base                                       | 协议      | API Key                                                          |
 | ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
-| **OpenAI**              | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [获取](https://platform.openai.com)                              |
-| **Anthropic**           | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [获取](https://console.anthropic.com)                            |
-| **智谱 AI (GLM)**       | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [获取](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys)    |
-| **DeepSeek**            | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [获取](https://platform.deepseek.com)                            |
-| **Google Gemini**       | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | Gemini    | [获取](https://aistudio.google.com/api-keys)                     |
-| **Groq**                | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [获取](https://console.groq.com)                                 |
-| **Moonshot**            | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [获取](https://platform.moonshot.cn)                             |
-| **通义千问 (Qwen)**     | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [获取](https://dashscope.console.aliyun.com)                     |
-| **NVIDIA**              | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [获取](https://build.nvidia.com)                                 |
-| **Ollama**              | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | 本地（无需 Key）                                                 |
-| **LM Studio**           | `lmstudio/`       | `http://localhost:1234/v1`                          | OpenAI    | 可选（本地默认无需密钥）                                         |
-| **OpenRouter**          | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [获取](https://openrouter.ai/keys)                               |
-| **LiteLLM Proxy**       | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | 你的 LiteLLM 代理 Key                                            |
-| **VLLM**                | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | 本地                                                             |
-| **Cerebras**            | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [获取](https://cerebras.ai)                                      |
-| **火山引擎 (豆包)**     | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [获取](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
-| **神算云**              | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | —                                                                |
-| **BytePlus**            | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [获取](https://www.byteplus.com)                                 |
-| **Vivgrid**             | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [获取](https://vivgrid.com)                                      |
-| **LongCat**             | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [获取](https://longcat.chat/platform)                            |
-| **ModelScope (魔搭)**   | `modelscope/`     | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [获取](https://modelscope.cn/my/tokens)                          |
-| **Antigravity**         | `antigravity/`    | Google Cloud                                        | Custom    | 仅 OAuth                                                         |
-| **GitHub Copilot**      | `github-copilot/` | `localhost:4321`                                    | gRPC      | —                                                                |
+| **OpenAI**              | `openai`          | `https://api.openai.com/v1`                         | OpenAI    | [获取](https://platform.openai.com)                              |
+| **Anthropic**           | `anthropic`       | `https://api.anthropic.com/v1`                      | Anthropic | [获取](https://console.anthropic.com)                            |
+| **智谱 AI (GLM)**       | `zhipu`           | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [获取](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys)    |
+| **DeepSeek**            | `deepseek`        | `https://api.deepseek.com/v1`                       | OpenAI    | [获取](https://platform.deepseek.com)                            |
+| **Google Gemini**       | `gemini`          | `https://generativelanguage.googleapis.com/v1beta`  | Gemini    | [获取](https://aistudio.google.com/api-keys)                     |
+| **Groq**                | `groq`            | `https://api.groq.com/openai/v1`                    | OpenAI    | [获取](https://console.groq.com)                                 |
+| **Moonshot**            | `moonshot`        | `https://api.moonshot.cn/v1`                        | OpenAI    | [获取](https://platform.moonshot.cn)                             |
+| **通义千问 (Qwen)**     | `qwen`            | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [获取](https://dashscope.console.aliyun.com)                     |
+| **NVIDIA**              | `nvidia`          | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [获取](https://build.nvidia.com)                                 |
+| **Ollama**              | `ollama`          | `http://localhost:11434/v1`                         | OpenAI    | 本地（无需 Key）                                                 |
+| **LM Studio**           | `lmstudio`        | `http://localhost:1234/v1`                          | OpenAI    | 可选（本地默认无需密钥）                                         |
+| **OpenRouter**          | `openrouter`      | `https://openrouter.ai/api/v1`                      | OpenAI    | [获取](https://openrouter.ai/keys)                               |
+| **LiteLLM Proxy**       | `litellm`         | `http://localhost:4000/v1`                          | OpenAI    | 你的 LiteLLM 代理 Key                                            |
+| **VLLM**                | `vllm`            | `http://localhost:8000/v1`                          | OpenAI    | 本地                                                             |
+| **Cerebras**            | `cerebras`        | `https://api.cerebras.ai/v1`                        | OpenAI    | [获取](https://cerebras.ai)                                      |
+| **火山引擎 (豆包)**     | `volcengine`      | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [获取](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **神算云**              | `shengsuanyun`    | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | —                                                                |
+| **BytePlus**            | `byteplus`        | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [获取](https://www.byteplus.com)                                 |
+| **Vivgrid**             | `vivgrid`         | `https://api.vivgrid.com/v1`                        | OpenAI    | [获取](https://vivgrid.com)                                      |
+| **LongCat**             | `longcat`         | `https://api.longcat.chat/openai`                   | OpenAI    | [获取](https://longcat.chat/platform)                            |
+| **ModelScope (魔搭)**   | `modelscope`      | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [获取](https://modelscope.cn/my/tokens)                          |
+| **Antigravity**         | `antigravity`     | Google Cloud                                        | Custom    | 仅 OAuth                                                         |
+| **GitHub Copilot**      | `github-copilot`  | `localhost:4321`                                    | gRPC      | —                                                                |
 
 #### 基础配置
 
@@ -469,22 +469,26 @@ Agent 读取 HEARTBEAT.md
   "model_list": [
     {
       "model_name": "ark-code-latest",
-      "model": "volcengine/ark-code-latest",
+      "provider": "volcengine",
+      "model": "ark-code-latest",
       "api_keys": ["sk-your-api-key"]
     },
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-your-openai-key"]
     },
     {
       "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
+      "provider": "anthropic",
+      "model": "claude-sonnet-4.6",
       "api_keys": ["sk-ant-your-key"]
     },
     {
       "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
+      "provider": "zhipu",
+      "model": "glm-4.7",
       "api_keys": ["your-zhipu-key"]
     }
   ],
@@ -496,6 +500,13 @@ Agent 读取 HEARTBEAT.md
 }
 ```
 
+解析规则：
+
+- 推荐显式写成 `"provider": "openai", "model": "gpt-5.4"`。
+- 如果设置了 `provider`，PicoClaw 会将 `model` 原样发送。
+- 如果未设置 `provider`，PicoClaw 会把 `model` 第一个 `/` 之前的字段当作 provider，并把第一个 `/` 之后的全部内容当作最终模型 ID。
+- 这意味着 `"model": "openrouter/openai/gpt-5.4"` 这样的兼容写法仍然可用，并会把 `openai/gpt-5.4` 发送给 OpenRouter。
+
 #### 各厂商配置示例
 
 <details>
@@ -504,7 +515,8 @@ Agent 读取 HEARTBEAT.md
 ```json
 {
   "model_name": "gpt-5.4",
-  "model": "openai/gpt-5.4",
+  "provider": "openai",
+  "model": "gpt-5.4",
   "api_keys": ["sk-..."]
 }
 ```
@@ -517,7 +529,8 @@ Agent 读取 HEARTBEAT.md
 ```json
 {
   "model_name": "ark-code-latest",
-  "model": "volcengine/ark-code-latest",
+  "provider": "volcengine",
+  "model": "ark-code-latest",
   "api_keys": ["sk-..."]
 }
 ```
@@ -530,7 +543,8 @@ Agent 读取 HEARTBEAT.md
 ```json
 {
   "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7",
+  "provider": "zhipu",
+  "model": "glm-4.7",
   "api_keys": ["your-key"]
 }
 ```
@@ -543,7 +557,8 @@ Agent 读取 HEARTBEAT.md
 ```json
 {
   "model_name": "deepseek-chat",
-  "model": "deepseek/deepseek-chat",
+  "provider": "deepseek",
+  "model": "deepseek-chat",
   "api_keys": ["sk-..."]
 }
 ```
@@ -556,7 +571,8 @@ Agent 读取 HEARTBEAT.md
 ```json
 {
   "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6",
+  "provider": "anthropic",
+  "model": "claude-sonnet-4.6",
   "api_keys": ["sk-ant-your-key"]
 }
 ```
@@ -568,7 +584,8 @@ Agent 读取 HEARTBEAT.md
 ```json
 {
   "model_name": "claude-opus-4-6",
-  "model": "anthropic-messages/claude-opus-4-6",
+  "provider": "anthropic-messages",
+  "model": "claude-opus-4-6",
   "api_keys": ["sk-ant-your-key"],
   "api_base": "https://api.anthropic.com"
 }
@@ -584,7 +601,8 @@ Agent 读取 HEARTBEAT.md
 ```json
 {
   "model_name": "llama3",
-  "model": "ollama/llama3"
+  "provider": "ollama",
+  "model": "llama3"
 }
 ```
 
@@ -596,12 +614,13 @@ Agent 读取 HEARTBEAT.md
 ```json
 {
   "model_name": "lmstudio-local",
-  "model": "lmstudio/openai/gpt-oss-20b"
+  "provider": "lmstudio",
+  "model": "openai/gpt-oss-20b"
 }
 ```
 
 `api_base` 默认是 `http://localhost:1234/v1`。除非你在 LM Studio 侧启用了认证，否则不需要配置 API Key。
-PicoClaw 向 LM Studio 的 OpenAI 兼容终结点发送请求，且将移除首个 `lmstudio/` 前缀，因此 `lmstudio/openai/gpt-oss-20b` 会发送 `openai/gpt-oss-20b`。
+显式设置 `provider` 后，PicoClaw 会把 `openai/gpt-oss-20b` 原样发送给 LM Studio。旧的兼容写法 `"model": "lmstudio/openai/gpt-oss-20b"` 在未设置 `provider` 时也会解析成相同的上游模型 ID。
 
 </details>
 
@@ -611,13 +630,14 @@ PicoClaw 向 LM Studio 的 OpenAI 兼容终结点发送请求，且将移除首
 ```json
 {
   "model_name": "my-custom-model",
-  "model": "openai/custom-model",
+  "provider": "openai",
+  "model": "custom-model",
   "api_base": "https://my-proxy.com/v1",
   "api_keys": ["sk-..."]
 }
 ```
 
-PicoClaw 只剥离最外层的 `litellm/` 前缀再发送请求，因此 `litellm/lite-gpt4` 发送 `lite-gpt4`，而 `litellm/openai/gpt-4o` 发送 `openai/gpt-4o`。
+显式设置 `provider` 后，PicoClaw 会将 `model` 原样发送。因此 `"provider": "litellm", "model": "lite-gpt4"` 会发送 `lite-gpt4`，而 `"provider": "litellm", "model": "openai/gpt-4o"` 会发送 `openai/gpt-4o`。旧的兼容写法 `litellm/lite-gpt4` 和 `litellm/openai/gpt-4o` 在未设置 `provider` 时也会得到相同结果。
 
 </details>
 
@@ -630,13 +650,15 @@ PicoClaw 只剥离最外层的 `litellm/` 前缀再发送请求，因此 `litell
   "model_list": [
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_base": "https://api1.example.com/v1",
       "api_keys": ["sk-key1"]
     },
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_base": "https://api2.example.com/v1",
       "api_keys": ["sk-key2"]
     }
@@ -691,7 +713,7 @@ PicoClaw 按协议族路由提供商：
 {
   "agents": {
     "defaults": {
-      "model": "anthropic/claude-opus-4-5"
+      "model_name": "claude-opus-4-5"
     }
   },
   "session": {

docs/guides/docker.fr.md

@@ -36,7 +36,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Mode Launcher (Console Web)
 
-L'image `launcher` inclut les trois binaires (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) et démarre la console web par défaut, qui fournit une interface navigateur pour la configuration et le chat.
+L'image `launcher` inclut les deux binaires (`picoclaw`, `picoclaw-launcher`) et démarre la console web par défaut, qui fournit une interface navigateur pour la configuration et le chat.
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.ja.md

@@ -36,7 +36,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Launcher モード (Web コンソール)
 
-`launcher` イメージには 3 つのバイナリ（`picoclaw`、`picoclaw-launcher`、`picoclaw-launcher-tui`）がすべて含まれており、デフォルトで Web コンソールを起動します。ブラウザベースの設定・チャット画面を提供します。
+`launcher` イメージには 2 つのバイナリ（`picoclaw`、`picoclaw-launcher`）が含まれており、デフォルトで Web コンソールを起動します。ブラウザベースの設定・チャット画面を提供します。
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.md

@@ -39,7 +39,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Launcher Mode (Web Console)
 
-The `launcher` image includes all three binaries (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) and starts the web console by default, which provides a browser-based UI for configuration and chat.
+The `launcher` image includes both binaries (`picoclaw`, `picoclaw-launcher`) and starts the web console by default, which provides a browser-based UI for configuration and chat.
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d
@@ -94,19 +94,22 @@ picoclaw onboard
   "model_list": [
     {
       "model_name": "ark-code-latest",
-      "model": "volcengine/ark-code-latest",
+      "provider": "volcengine",
+      "model": "ark-code-latest",
       "api_keys": ["sk-your-api-key"],
       "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3"
     },
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["your-api-key"],
       "request_timeout": 300
     },
     {
       "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
+      "provider": "anthropic",
+      "model": "claude-sonnet-4.6",
       "api_keys": ["your-anthropic-key"]
     }
   ],

docs/guides/docker.ms.md

@@ -35,7 +35,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Mod Launcher (Konsol Web)
 
-Imej `launcher` merangkumi ketiga-tiga binari (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) dan memulakan konsol web secara lalai, yang menyediakan UI berasaskan pelayar untuk konfigurasi dan sembang.
+Imej `launcher` merangkumi kedua-dua binari (`picoclaw`, `picoclaw-launcher`) dan memulakan konsol web secara lalai, yang menyediakan UI berasaskan pelayar untuk konfigurasi dan sembang.
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.pt-br.md

@@ -36,7 +36,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Modo Launcher (Console Web)
 
-A imagem `launcher` inclui os três binários (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) e inicia o console web por padrão, que fornece uma interface baseada em navegador para configuração e chat.
+A imagem `launcher` inclui ambos os binários (`picoclaw`, `picoclaw-launcher`) e inicia o console web por padrão, que fornece uma interface baseada em navegador para configuração e chat.
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.vi.md

@@ -36,7 +36,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Chế Độ Launcher (Web Console)
 
-Image `launcher` bao gồm cả ba binary (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) và khởi động web console mặc định, cung cấp giao diện trình duyệt để cấu hình và chat.
+Image `launcher` bao gồm cả hai binary (`picoclaw`, `picoclaw-launcher`) và khởi động web console mặc định, cung cấp giao diện trình duyệt để cấu hình và chat.
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.zh.md

@@ -36,7 +36,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Launcher 模式 (Web 控制台)
 
-`launcher` 镜像包含所有三个二进制文件（`picoclaw`、`picoclaw-launcher`、`picoclaw-launcher-tui`），默认启动 Web 控制台，提供基于浏览器的配置和聊天界面。
+`launcher` 镜像包含两个二进制文件（`picoclaw`、`picoclaw-launcher`），默认启动 Web 控制台，提供基于浏览器的配置和聊天界面。
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d
@@ -93,19 +93,22 @@ picoclaw onboard
   "model_list": [
     {
       "model_name": "ark-code-latest",
-      "model": "volcengine/ark-code-latest",
+      "provider": "volcengine",
+      "model": "ark-code-latest",
       "api_keys": ["sk-your-api-key"],
       "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3"
     },
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["your-api-key"],
       "request_timeout": 300
     },
     {
       "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
+      "provider": "anthropic",
+      "model": "claude-sonnet-4.6",
       "api_keys": ["your-anthropic-key"]
     }
   ],

docs/guides/providers.md

@@ -33,7 +33,7 @@
 
 ### Model Configuration (model_list)
 
-> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers—**zero code changes required!**
+> **What's New?** PicoClaw now prefers explicit `provider` + native `model` configuration (for example `"provider": "zhipu", "model": "glm-4.7"`). The legacy single-field `provider/model` form remains supported for compatibility when `provider` is omitted.
 
 For agent dispatch and light-model routing examples, see the [Routing Guide](routing-guide.md).
 
@@ -46,35 +46,35 @@ This design also enables **multi-agent support** with flexible provider selectio
 
 #### 📋 All Supported Vendors
 
-| Vendor              | `model` Prefix    | Default API Base                                    | Protocol  | API Key                                                          |
+| Vendor              | `provider` Value  | Default API Base                                    | Protocol  | API Key                                                          |
 | ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- |
-| **OpenAI**          | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [Get Key](https://platform.openai.com)                           |
-| **Venice AI**       | `venice/`         | `https://api.venice.ai/api/v1`                      | OpenAI    | [Get Key](https://venice.ai)                                     |
-| **Anthropic**       | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [Get Key](https://console.anthropic.com)                         |
-| **智谱 AI (GLM)**   | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
-| **Z.AI Coding Plan** | `openai/`         | `https://api.z.ai/api/coding/paas/v4`              | OpenAI    | [Get Key](https://z.ai/manage-apikey/apikey-list) |
-| **DeepSeek**        | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [Get Key](https://platform.deepseek.com)                         |
-| **Google Gemini**   | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | Gemini    | [Get Key](https://aistudio.google.com/api-keys)                  |
-| **Groq**            | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [Get Key](https://console.groq.com)                              |
-| **Moonshot**        | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [Get Key](https://platform.moonshot.cn)                          |
-| **通义千问 (Qwen)** | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
-| **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)                                            |
-| **LM Studio**       | `lmstudio/`       | `http://localhost:1234/v1`                          | OpenAI    | Optional (local default: no key)                                 |
-| **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                                            |
-| **VLLM**            | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
-| **Cerebras**        | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
-| **VolcEngine (Doubao)** | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                        |
-| **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                |
-| **BytePlus**        | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [Get Key](https://www.byteplus.com)                        |
-| **Vivgrid**         | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
-| **LongCat**         | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [Get Key](https://longcat.chat/platform)                         |
-| **ModelScope (魔搭)**| `modelscope/`    | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [Get Token](https://modelscope.cn/my/tokens)                     |
-| **Xiaomi MiMo**     | `mimo/`           | `https://api.xiaomimimo.com/v1`                     | OpenAI    | [Get Key](https://platform.xiaomimimo.com)                       |
-| **Azure OpenAI**    | `azure/`          | `https://{resource}.openai.azure.com`               | Azure     | [Get Key](https://portal.azure.com)                              |
-| **Antigravity**     | `antigravity/`    | Google Cloud                                        | Custom    | OAuth only                                                       |
-| **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                |
+| **OpenAI**          | `openai`          | `https://api.openai.com/v1`                         | OpenAI    | [Get Key](https://platform.openai.com)                           |
+| **Venice AI**       | `venice`          | `https://api.venice.ai/api/v1`                      | OpenAI    | [Get Key](https://venice.ai)                                     |
+| **Anthropic**       | `anthropic`       | `https://api.anthropic.com/v1`                      | Anthropic | [Get Key](https://console.anthropic.com)                         |
+| **智谱 AI (GLM)**   | `zhipu`           | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **Z.AI Coding Plan** | `openai`         | `https://api.z.ai/api/coding/paas/v4`               | OpenAI    | [Get Key](https://z.ai/manage-apikey/apikey-list)                |
+| **DeepSeek**        | `deepseek`        | `https://api.deepseek.com/v1`                       | OpenAI    | [Get Key](https://platform.deepseek.com)                         |
+| **Google Gemini**   | `gemini`          | `https://generativelanguage.googleapis.com/v1beta`  | Gemini    | [Get Key](https://aistudio.google.com/api-keys)                  |
+| **Groq**            | `groq`            | `https://api.groq.com/openai/v1`                    | OpenAI    | [Get Key](https://console.groq.com)                              |
+| **Moonshot**        | `moonshot`        | `https://api.moonshot.cn/v1`                        | OpenAI    | [Get Key](https://platform.moonshot.cn)                          |
+| **通义千问 (Qwen)** | `qwen`            | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
+| **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)                                            |
+| **LM Studio**       | `lmstudio`        | `http://localhost:1234/v1`                          | OpenAI    | Optional (local default: no key)                                 |
+| **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                                           |
+| **VLLM**            | `vllm`            | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
+| **Cerebras**        | `cerebras`        | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
+| **VolcEngine (Doubao)** | `volcengine`  | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **神算云**          | `shengsuanyun`    | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                |
+| **BytePlus**        | `byteplus`        | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [Get Key](https://www.byteplus.com)                              |
+| **Vivgrid**         | `vivgrid`         | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
+| **LongCat**         | `longcat`         | `https://api.longcat.chat/openai`                   | OpenAI    | [Get Key](https://longcat.chat/platform)                         |
+| **ModelScope (魔搭)**| `modelscope`     | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [Get Token](https://modelscope.cn/my/tokens)                     |
+| **Xiaomi MiMo**     | `mimo`            | `https://api.xiaomimimo.com/v1`                     | OpenAI    | [Get Key](https://platform.xiaomimimo.com)                       |
+| **Azure OpenAI**    | `azure`           | `https://{resource}.openai.azure.com`               | Azure     | [Get Key](https://portal.azure.com)                              |
+| **Antigravity**     | `antigravity`     | Google Cloud                                        | Custom    | OAuth only                                                       |
+| **GitHub Copilot**  | `github-copilot`  | `localhost:4321`                                    | gRPC      | -                                                                |
 
 #### Basic Configuration
 
@@ -83,22 +83,26 @@ This design also enables **multi-agent support** with flexible provider selectio
   "model_list": [
     {
       "model_name": "ark-code-latest",
-      "model": "volcengine/ark-code-latest",
+      "provider": "volcengine",
+      "model": "ark-code-latest",
       "api_keys": ["sk-your-api-key"]
     },
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-your-openai-key"]
     },
     {
       "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
+      "provider": "anthropic",
+      "model": "claude-sonnet-4.6",
       "api_keys": ["sk-ant-your-key"]
     },
     {
       "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
+      "provider": "zhipu",
+      "model": "glm-4.7",
       "api_keys": ["your-zhipu-key"]
     }
   ],
@@ -115,7 +119,8 @@ This design also enables **multi-agent support** with flexible provider selectio
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `model_name` | string | Yes | Unique name used to reference this model in agent config |
-| `model` | string | Yes | Vendor/model identifier (e.g., `openai/gpt-5.4`, `azure/gpt-5.4`, `anthropic/claude-sonnet-4.6`) |
+| `provider` | string | No | Preferred provider identifier. When present, PicoClaw sends `model` unchanged to that provider |
+| `model` | string | Yes | Native model ID when `provider` is set. If `provider` is omitted, the legacy `provider/model` form is still supported |
 | `api_keys` | string[] | Yes* | API key(s) for authentication. Multiple keys enable per-request rotation. Not required for local providers (Ollama, LM Studio, VLLM) |
 | `api_base` | string | No | Override the default API endpoint URL |
 | `proxy` | string | No | HTTP proxy URL for this model entry |
@@ -129,6 +134,22 @@ This design also enables **multi-agent support** with flexible provider selectio
 | `fallbacks` | string[] | No | Fallback model names for automatic failover |
 | `enabled` | bool | No | Whether this model entry is active (default: `true`) |
 
+#### Provider / Model Resolution
+
+PicoClaw resolves `provider` and the runtime model ID using these rules:
+
+- If `provider` is set, `model` is used as-is.
+- If `provider` is omitted, PicoClaw treats the first `/` segment in `model` as the provider and everything after that first `/` as the runtime model ID.
+
+Examples:
+
+| Config | Resolved Provider | Model Sent Upstream |
+| --- | --- | --- |
+| `"provider": "openai", "model": "gpt-5.4"` | `openai` | `gpt-5.4` |
+| `"model": "openai/gpt-5.4"` | `openai` | `gpt-5.4` |
+| `"provider": "openrouter", "model": "openai/gpt-5.4"` | `openrouter` | `openai/gpt-5.4` |
+| `"model": "openrouter/openai/gpt-5.4"` | `openrouter` | `openai/gpt-5.4` |
+
 #### Voice Transcription
 
 You can configure a dedicated model for audio transcription with `voice.model_name`. This lets you reuse existing multimodal providers that support audio input instead of relying only on Groq.
@@ -140,7 +161,8 @@ If `voice.model_name` is not configured, PicoClaw will continue to fall back to
   "model_list": [
     {
       "model_name": "voice-gemini",
-      "model": "gemini/gemini-2.5-flash",
+      "provider": "gemini",
+      "model": "gemini-2.5-flash",
       "api_keys": ["your-gemini-key"]
     }
   ],
@@ -163,7 +185,8 @@ If `voice.model_name` is not configured, PicoClaw will continue to fall back to
 ```json
 {
   "model_name": "gpt-5.4",
-  "model": "openai/gpt-5.4",
+  "provider": "openai",
+  "model": "gpt-5.4",
   "api_keys": ["sk-..."]
 }
 ```
@@ -173,7 +196,8 @@ If `voice.model_name` is not configured, PicoClaw will continue to fall back to
 ```json
 {
   "model_name": "ark-code-latest",
-  "model": "volcengine/ark-code-latest",
+  "provider": "volcengine",
+  "model": "ark-code-latest",
   "api_keys": ["sk-..."]
 }
 ```
@@ -183,7 +207,8 @@ If `voice.model_name` is not configured, PicoClaw will continue to fall back to
 ```json
 {
   "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7",
+  "provider": "zhipu",
+  "model": "glm-4.7",
   "api_keys": ["your-key"]
 }
 ```
@@ -193,7 +218,8 @@ If `voice.model_name` is not configured, PicoClaw will continue to fall back to
 ```json
 {
   "model_name": "glm-4.7",
-  "model": "openai/glm-4.7",
+  "provider": "openai",
+  "model": "glm-4.7",
   "api_keys": ["your-z.ai-key"],
   "api_base": "https://api.z.ai/api/coding/paas/v4"
 }
@@ -204,7 +230,8 @@ If `voice.model_name` is not configured, PicoClaw will continue to fall back to
 ```json
 {
   "model_name": "deepseek-chat",
-  "model": "deepseek/deepseek-chat",
+  "provider": "deepseek",
+  "model": "deepseek-chat",
   "api_keys": ["sk-..."]
 }
 ```
@@ -214,7 +241,8 @@ If `voice.model_name` is not configured, PicoClaw will continue to fall back to
 ```json
 {
   "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6",
+  "provider": "anthropic",
+  "model": "claude-sonnet-4.6",
   "api_keys": ["sk-ant-your-key"]
 }
 ```
@@ -228,7 +256,8 @@ For direct Anthropic API access or custom endpoints that only support Anthropic'
 ```json
 {
   "model_name": "claude-opus-4-6",
-  "model": "anthropic-messages/claude-opus-4-6",
+  "provider": "anthropic-messages",
+  "model": "claude-opus-4-6",
   "api_keys": ["sk-ant-your-key"],
   "api_base": "https://api.anthropic.com"
 }
@@ -246,7 +275,8 @@ For direct Anthropic API access or custom endpoints that only support Anthropic'
 ```json
 {
   "model_name": "llama3",
-  "model": "ollama/llama3"
+  "provider": "ollama",
+  "model": "llama3"
 }
 ```
 
@@ -255,19 +285,21 @@ For direct Anthropic API access or custom endpoints that only support Anthropic'
 ```json
 {
   "model_name": "lmstudio-local",
-  "model": "lmstudio/openai/gpt-oss-20b"
+  "provider": "lmstudio",
+  "model": "openai/gpt-oss-20b"
 }
 ```
 
 `api_base` defaults to `http://localhost:1234/v1`. API key is optional unless your LM Studio server enables authentication.<br/>
-PicoClaw sends OpenAI-compatible requests to LM Studio, and strips the `lmstudio/` prefix before sending requests, so `lmstudio/openai/gpt-oss-20b` sends `openai/gpt-oss-20b` to the LM Studio server.
+With explicit `provider`, PicoClaw sends `openai/gpt-oss-20b` unchanged to the LM Studio server. The legacy compatibility form `"model": "lmstudio/openai/gpt-oss-20b"` still resolves to the same upstream model ID when `provider` is omitted.
 
 **Custom Proxy/API**
 
 ```json
 {
   "model_name": "my-custom-model",
-  "model": "openai/custom-model",
+  "provider": "openai",
+  "model": "custom-model",
   "api_base": "https://my-proxy.com/v1",
   "api_keys": ["sk-..."],
   "user_agent": "MyApp/1.0",
@@ -280,13 +312,14 @@ PicoClaw sends OpenAI-compatible requests to LM Studio, and strips the `lmstudio
 ```json
 {
   "model_name": "lite-gpt4",
-  "model": "litellm/lite-gpt4",
+  "provider": "litellm",
+  "model": "lite-gpt4",
   "api_base": "http://localhost:4000/v1",
   "api_keys": ["sk-..."]
 }
 ```
 
-PicoClaw strips only the outer `litellm/` prefix before sending the request, so proxy aliases like `litellm/lite-gpt4` send `lite-gpt4`, while `litellm/openai/gpt-4o` sends `openai/gpt-4o`.
+With explicit `provider`, PicoClaw sends `model` unchanged. That means `"provider": "litellm", "model": "lite-gpt4"` sends `lite-gpt4`, while `"provider": "litellm", "model": "openai/gpt-4o"` sends `openai/gpt-4o`. The legacy compatibility forms `litellm/lite-gpt4` and `litellm/openai/gpt-4o` still resolve the same way when `provider` is omitted.
 
 **Z.AI Coding Plan**
 
@@ -295,7 +328,8 @@ If the standard Zhipu endpoint (`https://open.bigmodel.cn/api/paas/v4`) returns
 ```json
 {
   "model_name": "glm-4.7",
-  "model": "openai/glm-4.7",
+  "provider": "openai",
+  "model": "glm-4.7",
   "api_keys": ["your-zhipu-api-key"],
   "api_base": "https://api.z.ai/api/coding/paas/v4"
 }
@@ -312,13 +346,15 @@ Configure multiple endpoints for the same model name—PicoClaw will automatical
   "model_list": [
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_base": "https://api1.example.com/v1",
       "api_keys": ["sk-key1"]
     },
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_base": "https://api2.example.com/v1",
       "api_keys": ["sk-key2"]
     }
@@ -337,18 +373,21 @@ It also applies cooldown tracking per candidate to avoid immediately retrying a
   "model_list": [
     {
       "model_name": "qwen-main",
-      "model": "openai/qwen3.5:cloud",
+      "provider": "openai",
+      "model": "qwen3.5:cloud",
       "api_base": "https://api.example.com/v1",
       "api_keys": ["sk-main"]
     },
     {
       "model_name": "deepseek-backup",
-      "model": "deepseek/deepseek-chat",
+      "provider": "deepseek",
+      "model": "deepseek-chat",
       "api_keys": ["sk-backup-1"]
     },
     {
       "model_name": "gemini-backup",
-      "model": "gemini/gemini-2.5-flash",
+      "provider": "gemini",
+      "model": "gemini-2.5-flash",
       "api_keys": ["sk-backup-2"]
     }
   ],
@@ -396,7 +435,8 @@ The old `providers` configuration is **deprecated** and has been removed in V2.
   "model_list": [
     {
       "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
+      "provider": "zhipu",
+      "model": "glm-4.7",
       "api_keys": ["your-key"]
     }
   ],
@@ -465,7 +505,7 @@ picoclaw agent -m "Hello"
 {
   "agents": {
     "defaults": {
-      "model_name": "anthropic/claude-opus-4-5"
+      "model_name": "claude-opus-4-5"
     }
   },
   "session": {

docs/guides/providers.zh.md

@@ -32,7 +32,7 @@
 <a id="模型配置-model_list"></a>
 ### 模型配置 (model_list)
 
-> **新功能！** PicoClaw 现在采用**以模型为中心**的配置方式。只需使用 `厂商/模型` 格式（如 `zhipu/glm-4.7`）即可添加新的 provider——**无需修改任何代码！**
+> **新功能！** PicoClaw 现在优先推荐显式 `provider` + 原生 `model` 的配置方式，例如 `"provider": "zhipu", "model": "glm-4.7"`。如果未设置 `provider`，旧的单字段 `provider/model` 写法仍然兼容。
 
 如果你想看 agent 分发和轻量模型路由的完整示例，请看 [路由使用指南](routing-guide.zh.md)。
 
@@ -45,33 +45,33 @@
 
 #### 📋 所有支持的厂商
 
-| 厂商                | `model` 前缀      | 默认 API Base                                       | 协议      | 获取 API Key                                                      |
+| 厂商                | `provider` 值     | 默认 API Base                                       | 协议      | 获取 API Key                                                      |
 | ------------------- | ----------------- | --------------------------------------------------- | --------- | ----------------------------------------------------------------- |
-| **OpenAI**          | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [获取密钥](https://platform.openai.com)                           |
-| **Venice AI**       | `venice/`         | `https://api.venice.ai/api/v1`                      | OpenAI    | [获取密钥](https://venice.ai)                                     |
-| **Anthropic**       | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [获取密钥](https://console.anthropic.com)                         |
-| **智谱 AI (GLM)**   | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [获取密钥](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
-| **DeepSeek**        | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [获取密钥](https://platform.deepseek.com)                         |
-| **Google Gemini**   | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | Gemini    | [获取密钥](https://aistudio.google.com/api-keys)                  |
-| **Groq**            | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [获取密钥](https://console.groq.com)                              |
-| **Moonshot**        | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [获取密钥](https://platform.moonshot.cn)                          |
-| **通义千问 (Qwen)** | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [获取密钥](https://dashscope.console.aliyun.com)                  |
-| **NVIDIA**          | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [获取密钥](https://build.nvidia.com)                              |
-| **Ollama**          | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | 本地（无需密钥）                                                  |
-| **LM Studio**       | `lmstudio/`       | `http://localhost:1234/v1`                          | OpenAI    | 可选（本地默认无需密钥）                                          |
-| **OpenRouter**      | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [获取密钥](https://openrouter.ai/keys)                            |
-| **LiteLLM Proxy**   | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | 你的 LiteLLM 代理密钥                                             |
-| **VLLM**            | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | 本地                                                              |
-| **Cerebras**        | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [获取密钥](https://cerebras.ai)                                   |
-| **火山引擎（Doubao）** | `volcengine/`  | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [获取密钥](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
-| **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                 |
-| **BytePlus**        | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [获取密钥](https://www.byteplus.com)                              |
-| **Vivgrid**         | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [获取密钥](https://vivgrid.com)                                   |
-| **LongCat**         | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [获取密钥](https://longcat.chat/platform)                         |
-| **ModelScope (魔搭)**| `modelscope/`    | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [获取 Token](https://modelscope.cn/my/tokens)                    |
-| **小米 MiMo**       | `mimo/`           | `https://api.xiaomimimo.com/v1`                     | OpenAI    | [获取密钥](https://platform.xiaomimimo.com)                      |
-| **Antigravity**     | `antigravity/`    | Google Cloud                                        | 自定义    | 仅 OAuth                                                          |
-| **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                 |
+| **OpenAI**          | `openai`          | `https://api.openai.com/v1`                         | OpenAI    | [获取密钥](https://platform.openai.com)                           |
+| **Venice AI**       | `venice`          | `https://api.venice.ai/api/v1`                      | OpenAI    | [获取密钥](https://venice.ai)                                     |
+| **Anthropic**       | `anthropic`       | `https://api.anthropic.com/v1`                      | Anthropic | [获取密钥](https://console.anthropic.com)                         |
+| **智谱 AI (GLM)**   | `zhipu`           | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [获取密钥](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek**        | `deepseek`        | `https://api.deepseek.com/v1`                       | OpenAI    | [获取密钥](https://platform.deepseek.com)                         |
+| **Google Gemini**   | `gemini`          | `https://generativelanguage.googleapis.com/v1beta`  | Gemini    | [获取密钥](https://aistudio.google.com/api-keys)                  |
+| **Groq**            | `groq`            | `https://api.groq.com/openai/v1`                    | OpenAI    | [获取密钥](https://console.groq.com)                              |
+| **Moonshot**        | `moonshot`        | `https://api.moonshot.cn/v1`                        | OpenAI    | [获取密钥](https://platform.moonshot.cn)                          |
+| **通义千问 (Qwen)** | `qwen`            | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [获取密钥](https://dashscope.console.aliyun.com)                  |
+| **NVIDIA**          | `nvidia`          | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [获取密钥](https://build.nvidia.com)                              |
+| **Ollama**          | `ollama`          | `http://localhost:11434/v1`                         | OpenAI    | 本地（无需密钥）                                                  |
+| **LM Studio**       | `lmstudio`        | `http://localhost:1234/v1`                          | OpenAI    | 可选（本地默认无需密钥）                                          |
+| **OpenRouter**      | `openrouter`      | `https://openrouter.ai/api/v1`                      | OpenAI    | [获取密钥](https://openrouter.ai/keys)                            |
+| **LiteLLM Proxy**   | `litellm`         | `http://localhost:4000/v1`                          | OpenAI    | 你的 LiteLLM 代理密钥                                             |
+| **VLLM**            | `vllm`            | `http://localhost:8000/v1`                          | OpenAI    | 本地                                                              |
+| **Cerebras**        | `cerebras`        | `https://api.cerebras.ai/v1`                        | OpenAI    | [获取密钥](https://cerebras.ai)                                   |
+| **火山引擎（Doubao）** | `volcengine`   | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [获取密钥](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **神算云**          | `shengsuanyun`    | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                 |
+| **BytePlus**        | `byteplus`        | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [获取密钥](https://www.byteplus.com)                              |
+| **Vivgrid**         | `vivgrid`         | `https://api.vivgrid.com/v1`                        | OpenAI    | [获取密钥](https://vivgrid.com)                                   |
+| **LongCat**         | `longcat`         | `https://api.longcat.chat/openai`                   | OpenAI    | [获取密钥](https://longcat.chat/platform)                         |
+| **ModelScope (魔搭)**| `modelscope`     | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [获取 Token](https://modelscope.cn/my/tokens)                     |
+| **小米 MiMo**       | `mimo`            | `https://api.xiaomimimo.com/v1`                     | OpenAI    | [获取密钥](https://platform.xiaomimimo.com)                       |
+| **Antigravity**     | `antigravity`     | Google Cloud                                        | 自定义    | 仅 OAuth                                                          |
+| **GitHub Copilot**  | `github-copilot`  | `localhost:4321`                                    | gRPC      | -                                                                 |
 
 #### 基础配置示例
 
@@ -80,22 +80,26 @@
   "model_list": [
     {
       "model_name": "ark-code-latest",
-      "model": "volcengine/ark-code-latest",
+      "provider": "volcengine",
+      "model": "ark-code-latest",
       "api_keys": ["sk-your-api-key"]
     },
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-your-openai-key"]
     },
     {
       "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
+      "provider": "anthropic",
+      "model": "claude-sonnet-4.6",
       "api_keys": ["sk-ant-your-key"]
     },
     {
       "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
+      "provider": "zhipu",
+      "model": "glm-4.7",
       "api_keys": ["your-zhipu-key"]
     }
   ],
@@ -112,7 +116,8 @@
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `model_name` | string | 是 | 在 agent 配置中引用此模型的唯一名称 |
-| `model` | string | 是 | 厂商/模型标识符（如 `openai/gpt-5.4`、`azure/gpt-5.4`、`anthropic/claude-sonnet-4.6`） |
+| `provider` | string | 否 | 推荐的 provider 标识。设置后，PicoClaw 会将 `model` 原样发送给该 provider |
+| `model` | string | 是 | 当设置 `provider` 时，这里填写 provider 原生模型 ID。若未设置 `provider`，仍兼容旧的 `provider/model` 写法 |
 | `api_keys` | string[] | 是* | 认证密钥。多个密钥可按请求轮换。本地 provider（Ollama、LM Studio、VLLM）不需要 |
 | `api_base` | string | 否 | 覆盖默认的 API 端点 URL |
 | `proxy` | string | 否 | 此模型条目的 HTTP 代理 URL |
@@ -126,6 +131,22 @@
 | `fallbacks` | string[] | 否 | 自动故障转移的备用模型名称 |
 | `enabled` | bool | 否 | 是否启用此模型条目（默认：`true`） |
 
+#### `provider` / `model` 解析规则
+
+PicoClaw 按下面的规则解析 `provider` 和最终发给上游的模型 ID：
+
+- 如果设置了 `provider`，则直接使用 `model`。
+- 如果未设置 `provider`，则把 `model` 中第一个 `/` 之前的字段当作 provider，第一个 `/` 之后的全部内容当作最终模型 ID。
+
+示例：
+
+| 配置 | 解析后的 Provider | 实际发送的模型 ID |
+| --- | --- | --- |
+| `"provider": "openai", "model": "gpt-5.4"` | `openai` | `gpt-5.4` |
+| `"model": "openai/gpt-5.4"` | `openai` | `gpt-5.4` |
+| `"provider": "openrouter", "model": "openai/gpt-5.4"` | `openrouter` | `openai/gpt-5.4` |
+| `"model": "openrouter/openai/gpt-5.4"` | `openrouter` | `openai/gpt-5.4` |
+
 #### 语音转录
 
 你可以通过 `voice.model_name` 为语音转录指定一个专用模型。这样可以直接复用已经配置好的、支持音频输入的多模态 provider，而不必只依赖 Groq。
@@ -137,7 +158,8 @@
   "model_list": [
     {
       "model_name": "voice-gemini",
-      "model": "gemini/gemini-2.5-flash",
+      "provider": "gemini",
+      "model": "gemini-2.5-flash",
       "api_keys": ["your-gemini-key"]
     }
   ],
@@ -160,7 +182,8 @@
 ```json
 {
   "model_name": "gpt-5.4",
-  "model": "openai/gpt-5.4",
+  "provider": "openai",
+  "model": "gpt-5.4",
   "api_keys": ["sk-..."]
 }
 ```
@@ -170,7 +193,8 @@
 ```json
 {
   "model_name": "ark-code-latest",
-  "model": "volcengine/ark-code-latest",
+  "provider": "volcengine",
+  "model": "ark-code-latest",
   "api_keys": ["sk-..."]
 }
 ```
@@ -180,7 +204,8 @@
 ```json
 {
   "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7",
+  "provider": "zhipu",
+  "model": "glm-4.7",
   "api_keys": ["your-key"]
 }
 ```
@@ -190,7 +215,8 @@
 ```json
 {
   "model_name": "deepseek-chat",
-  "model": "deepseek/deepseek-chat",
+  "provider": "deepseek",
+  "model": "deepseek-chat",
   "api_keys": ["sk-..."]
 }
 ```
@@ -200,7 +226,8 @@
 ```json
 {
   "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6",
+  "provider": "anthropic",
+  "model": "claude-sonnet-4.6",
   "auth_method": "oauth"
 }
 ```
@@ -214,7 +241,8 @@
 ```json
 {
   "model_name": "claude-opus-4-6",
-  "model": "anthropic-messages/claude-opus-4-6",
+  "provider": "anthropic-messages",
+  "model": "claude-opus-4-6",
   "api_keys": ["sk-ant-your-key"],
   "api_base": "https://api.anthropic.com"
 }
@@ -232,7 +260,8 @@
 ```json
 {
   "model_name": "llama3",
-  "model": "ollama/llama3"
+  "provider": "ollama",
+  "model": "llama3"
 }
 ```
 
@@ -241,19 +270,21 @@
 ```json
 {
   "model_name": "lmstudio-local",
-  "model": "lmstudio/openai/gpt-oss-20b"
+  "provider": "lmstudio",
+  "model": "openai/gpt-oss-20b"
 }
 ```
 
 `api_base` 默认是 `http://localhost:1234/v1`。除非你在 LM Studio 侧启用了认证，否则不需要配置 API Key。
-PicoClaw 向 LM Studio 的 OpenAI 兼容终结点发送请求，且将移除首个 `lmstudio/` 前缀，因此 `lmstudio/openai/gpt-oss-20b` 会发送 `openai/gpt-oss-20b`。
+显式设置 `provider` 后，PicoClaw 会把 `openai/gpt-oss-20b` 原样发送给 LM Studio。旧的兼容写法 `"model": "lmstudio/openai/gpt-oss-20b"` 在未设置 `provider` 时也会解析成相同的上游模型 ID。
 
 **自定义代理/API**
 
 ```json
 {
   "model_name": "my-custom-model",
-  "model": "openai/custom-model",
+  "provider": "openai",
+  "model": "custom-model",
   "api_base": "https://my-proxy.com/v1",
   "api_keys": ["sk-..."],
   "user_agent": "MyApp/1.0",
@@ -266,13 +297,14 @@ PicoClaw 向 LM Studio 的 OpenAI 兼容终结点发送请求，且将移除首
 ```json
 {
   "model_name": "lite-gpt4",
-  "model": "litellm/lite-gpt4",
+  "provider": "litellm",
+  "model": "lite-gpt4",
   "api_base": "http://localhost:4000/v1",
   "api_keys": ["sk-..."]
 }
 ```
 
-PicoClaw 在发送请求前仅去除外层 `litellm/` 前缀，因此 `litellm/lite-gpt4` 会发送 `lite-gpt4`，而 `litellm/openai/gpt-4o` 会发送 `openai/gpt-4o`。
+显式设置 `provider` 后，PicoClaw 会将 `model` 原样发送。因此 `"provider": "litellm", "model": "lite-gpt4"` 会发送 `lite-gpt4`，而 `"provider": "litellm", "model": "openai/gpt-4o"` 会发送 `openai/gpt-4o`。旧的兼容写法 `litellm/lite-gpt4` 和 `litellm/openai/gpt-4o` 在未设置 `provider` 时也会得到相同结果。
 
 #### 负载均衡
 
@@ -283,13 +315,15 @@ PicoClaw 在发送请求前仅去除外层 `litellm/` 前缀，因此 `litellm/l
   "model_list": [
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_base": "https://api1.example.com/v1",
       "api_keys": ["sk-key1"]
     },
     {
       "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_base": "https://api2.example.com/v1",
       "api_keys": ["sk-key2"]
     }
@@ -308,18 +342,21 @@ PicoClaw 在发送请求前仅去除外层 `litellm/` 前缀，因此 `litellm/l
   "model_list": [
     {
       "model_name": "qwen-main",
-      "model": "openai/qwen3.5:cloud",
+      "provider": "openai",
+      "model": "qwen3.5:cloud",
       "api_base": "https://api.example.com/v1",
       "api_keys": ["sk-main"]
     },
     {
       "model_name": "deepseek-backup",
-      "model": "deepseek/deepseek-chat",
+      "provider": "deepseek",
+      "model": "deepseek-chat",
       "api_keys": ["sk-backup-1"]
     },
     {
       "model_name": "gemini-backup",
-      "model": "gemini/gemini-2.5-flash",
+      "provider": "gemini",
+      "model": "gemini-2.5-flash",
       "api_keys": ["sk-backup-2"]
     }
   ],
@@ -367,7 +404,8 @@ PicoClaw 在发送请求前仅去除外层 `litellm/` 前缀，因此 `litellm/l
   "model_list": [
     {
       "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
+      "provider": "zhipu",
+      "model": "glm-4.7",
       "api_keys": ["your-key"]
     }
   ],
@@ -436,7 +474,7 @@ picoclaw agent -m "你好"
 {
   "agents": {
     "defaults": {
-      "model_name": "anthropic/claude-opus-4-5"
+      "model_name": "claude-opus-4-5"
     }
   },
   "session": {

docs/guides/routing-guide.md

@@ -69,12 +69,14 @@ This guide explains how to configure both for real deployments.
   "model_list": [
     {
       "model_name": "gpt-main",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-main"]
     },
     {
       "model_name": "flash-light",
-      "model": "gemini/gemini-2.0-flash-exp",
+      "provider": "gemini",
+      "model": "gemini-2.0-flash-exp",
       "api_keys": ["sk-light"]
     }
   ],

docs/guides/routing-guide.zh.md

@@ -69,12 +69,14 @@ PicoClaw 里用户能直接感知到的“路由”主要有两部分：
   "model_list": [
     {
       "model_name": "gpt-main",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-main"]
     },
     {
       "model_name": "flash-light",
-      "model": "gemini/gemini-2.0-flash-exp",
+      "provider": "gemini",
+      "model": "gemini-2.0-flash-exp",
       "api_keys": ["sk-light"]
     }
   ],

docs/migration/model-list-migration.md

@@ -8,7 +8,7 @@ The new `model_list` configuration offers several advantages:
 
 - **Zero-code provider addition**: Add OpenAI-compatible providers with configuration only
 - **Load balancing**: Configure multiple endpoints for the same model
-- **Protocol-based routing**: Use prefixes like `openai/`, `anthropic/`, etc.
+- **Explicit provider resolution**: Prefer `provider` + native `model`, with legacy `provider/model` compatibility when needed
 - **Cleaner configuration**: Model-centric instead of vendor-centric
 
 ## Timeline
@@ -54,18 +54,21 @@ The new `model_list` configuration offers several advantages:
   "model_list": [
     {
       "model_name": "gpt4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-your-openai-key"],
       "api_base": "https://api.openai.com/v1"
     },
     {
       "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
+      "provider": "anthropic",
+      "model": "claude-sonnet-4.6",
       "api_keys": ["sk-ant-your-key"]
     },
     {
       "model_name": "deepseek",
-      "model": "deepseek/deepseek-chat",
+      "provider": "deepseek",
+      "model": "deepseek-chat",
       "api_keys": ["sk-your-deepseek-key"]
     }
   ],
@@ -79,40 +82,46 @@ The new `model_list` configuration offers several advantages:
 
 > **Note**: The `enabled` field can be omitted — during V1→V2 migration it is auto-inferred (models with API keys or the `local-model` name are enabled by default). For new configs, you can explicitly set `"enabled": false` to disable a model entry without removing it.
 
-## Protocol Prefixes
+## Provider / Model Resolution
 
-The `model` field uses a protocol prefix format: `[protocol/]model-identifier`
+Preferred format:
 
-| Prefix | Description | Example |
-|--------|-------------|---------|
-| `openai/` | OpenAI API (default) | `openai/gpt-5.4` |
-| `anthropic/` | Anthropic API | `anthropic/claude-opus-4` |
-| `antigravity/` | Google via Antigravity OAuth | `antigravity/gemini-2.0-flash` |
-| `gemini/` | Google Gemini API | `gemini/gemini-2.0-flash-exp` |
-| `claude-cli/` | Claude CLI (local) | `claude-cli/claude-sonnet-4.6` |
-| `codex-cli/` | Codex CLI (local) | `codex-cli/codex-4` |
-| `github-copilot/` | GitHub Copilot | `github-copilot/gpt-4o` |
-| `openrouter/` | OpenRouter | `openrouter/anthropic/claude-sonnet-4.6` |
-| `groq/` | Groq API | `groq/llama-3.1-70b` |
-| `deepseek/` | DeepSeek API | `deepseek/deepseek-chat` |
-| `cerebras/` | Cerebras API | `cerebras/llama-3.3-70b` |
-| `qwen/` | Alibaba Qwen | `qwen/qwen-max` |
-| `zhipu/` | Zhipu AI | `zhipu/glm-4` |
-| `nvidia/` | NVIDIA NIM | `nvidia/llama-3.1-nemotron-70b` |
-| `ollama/` | Ollama (local) | `ollama/llama3` |
-| `vllm/` | vLLM (local) | `vllm/my-model` |
-| `moonshot/` | Moonshot AI | `moonshot/moonshot-v1-8k` |
-| `shengsuanyun/` | ShengSuanYun | `shengsuanyun/deepseek-v3` |
-| `volcengine/` | Volcengine | `volcengine/doubao-pro-32k` |
+```json
+{
+  "provider": "openai",
+  "model": "gpt-5.4"
+}
+```
 
-**Note**: If no prefix is specified, `openai/` is used as the default.
+Legacy compatibility format:
+
+```json
+{
+  "model": "openai/gpt-5.4"
+}
+```
+
+Resolution rules:
+
+1. If `provider` is set, PicoClaw sends `model` unchanged.
+2. If `provider` is omitted, PicoClaw treats the first `/` segment in `model` as the provider and everything after that first `/` as the runtime model ID.
+
+Examples:
+
+| Config | Resolved Provider | Model Sent Upstream |
+|--------|-------------------|---------------------|
+| `"provider": "openai", "model": "gpt-5.4"` | `openai` | `gpt-5.4` |
+| `"model": "openai/gpt-5.4"` | `openai` | `gpt-5.4` |
+| `"provider": "openrouter", "model": "google/gemini-2.0-flash-exp:free"` | `openrouter` | `google/gemini-2.0-flash-exp:free` |
+| `"model": "openrouter/google/gemini-2.0-flash-exp:free"` | `openrouter` | `google/gemini-2.0-flash-exp:free` |
 
 ## ModelConfig Fields
 
 | Field | Required | Description |
 |-------|----------|-------------|
 | `model_name` | Yes | User-facing alias for the model |
-| `model` | Yes | Protocol and model identifier (e.g., `openai/gpt-5.4`) |
+| `provider` | No | Preferred provider identifier. When set, `model` is sent unchanged |
+| `model` | Yes | Native model ID when `provider` is set, or legacy `provider/model` when `provider` is omitted |
 | `api_base` | No | API endpoint URL |
 | `api_keys` | No | API authentication keys (array; supports multiple keys for load balancing) |
 | `enabled` | No | Whether this model entry is active. Defaults to `true` during migration for models with API keys or named `local-model`. Set to `false` to disable. |
@@ -136,7 +145,8 @@ There are two ways to configure load balancing:
   "model_list": [
     {
       "model_name": "gpt4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-key1", "sk-key2", "sk-key3"],
       "api_base": "https://api.openai.com/v1"
     }
@@ -162,19 +172,22 @@ model_list:
   "model_list": [
     {
       "model_name": "gpt4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-key1"],
       "api_base": "https://api1.example.com/v1"
     },
     {
       "model_name": "gpt4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-key2"],
       "api_base": "https://api2.example.com/v1"
     },
     {
       "model_name": "gpt4",
-      "model": "openai/gpt-5.4",
+      "provider": "openai",
+      "model": "gpt-5.4",
       "api_keys": ["sk-key3"],
       "api_base": "https://api3.example.com/v1"
     }
@@ -193,7 +206,8 @@ With `model_list`, adding a new provider requires zero code changes:
   "model_list": [
     {
       "model_name": "my-custom-llm",
-      "model": "openai/my-model-v1",
+      "provider": "openai",
+      "model": "my-model-v1",
       "api_keys": ["your-api-key"],
       "api_base": "https://api.your-provider.com/v1"
     }
@@ -201,7 +215,7 @@ With `model_list`, adding a new provider requires zero code changes:
 }
 ```
 
-Just specify `openai/` as the protocol (or omit it for the default), and provide your provider's API base URL.
+Just set `provider` to `openai` (or another supported provider), and provide your provider's API base URL.
 
 ## Backward Compatibility
 
@@ -216,7 +230,7 @@ During the migration period, your existing V0/V1 config will be auto-migrated to
 
 - [ ] Identify all providers you're currently using
 - [ ] Create `model_list` entries for each provider
-- [ ] Use appropriate protocol prefixes
+- [ ] Prefer explicit `provider` values and native model IDs
 - [ ] Update `agents.defaults.model_name` to reference the new `model_name`
 - [ ] Test that all models work correctly
 - [ ] Remove or comment out the old `providers` section
@@ -234,10 +248,10 @@ model "xxx" not found in model_list or providers
 ### Unknown protocol error
 
 ```
-unknown protocol "xxx" in model "xxx/model-name"
+unknown provider "xxx" in model "xxx/model-name"
 ```
 
-**Solution**: Use a supported protocol prefix. See the [Protocol Prefixes](#protocol-prefixes) table above.
+**Solution**: Use a supported `provider` value, or use the legacy `provider/model` compatibility form correctly. See [Provider / Model Resolution](#provider--model-resolution).
 
 ### Missing API key error
 

docs/operations/debug.md

@@ -65,7 +65,8 @@ Debug logs are server-side only. If you want the agent to send a visible notific
     "defaults": {
       "tool_feedback": {
         "enabled": true,
-        "max_args_length": 300
+        "max_args_length": 300,
+        "separate_messages": true
       }
     }
   }
@@ -85,6 +86,7 @@ When `enabled` is `true`, every tool call sends a short message to the chat befo
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `enabled` | bool | `false` | Send a chat notification for each tool call |
+| `separate_messages` | bool | `false` | Keep every tool feedback update as a separate chat message instead of reusing a single placeholder/progress message |
 | `max_args_length` | int | `300` | Maximum characters of the serialised arguments included in the notification |
 
 ### Environment variables

docs/operations/troubleshooting.md

@@ -7,16 +7,22 @@
 - `Error creating provider: model "openrouter/free" not found in model_list`
 - OpenRouter returns 400: `"free is not a valid model ID"`
 
-**Cause:** The `model` field in your `model_list` entry is what gets sent to the API. For OpenRouter you must use the **full** model ID, not a shorthand.
+**Cause:** PicoClaw now resolves provider/model in two steps:
 
-- **Wrong:** `"model": "free"` → OpenRouter receives `free` and rejects it.
-- **Right:** `"model": "openrouter/free"` → OpenRouter receives `openrouter/free` (auto free-tier routing).
+- If `provider` is set, the `model` field is sent to that provider unchanged.
+- If `provider` is omitted, PicoClaw infers the provider from the first `/` segment and sends everything after that first `/` as the runtime model ID.
+
+For OpenRouter free-tier routing, the preferred config is explicit `provider`.
+
+- **Wrong:** `"model": "free"` → no OpenRouter provider is selected, so `free` is not a valid OpenRouter model route.
+- **Right:** `"provider": "openrouter", "model": "free"` → OpenRouter receives `free`.
+- **Also supported:** `"model": "openrouter/free"` → provider resolves to `openrouter`, runtime model ID resolves to `free`.
 
 **Fix:** In `~/.picoclaw/config.json` (or your config path):
 
 1. **agents.defaults.model_name** must match a `model_name` in `model_list` (e.g. `"openrouter-free"`).
-2. That entry’s **model** must be a valid OpenRouter model ID, for example:
-   - `"openrouter/free"` – auto free-tier
+2. That entry should preferably set **provider** to `openrouter`, and **model** should be a valid OpenRouter model ID, for example:
+   - `"free"` – auto free-tier
    - `"google/gemini-2.0-flash-exp:free"`
    - `"meta-llama/llama-3.1-8b-instruct:free"`
 
@@ -32,8 +38,9 @@ Example snippet:
   "model_list": [
     {
       "model_name": "openrouter-free",
-      "model": "openrouter/free",
-      "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
+      "provider": "openrouter",
+      "model": "free",
+      "api_keys": ["sk-or-v1-YOUR_OPENROUTER_KEY"],
       "api_base": "https://openrouter.ai/api/v1"
     }
   ]

docs/operations/troubleshooting.zh.md

@@ -9,16 +9,22 @@
 - `Error creating provider: model "openrouter/free" not found in model_list`
 - OpenRouter 返回 400：`"free is not a valid model ID"`
 
-**原因：** `model_list` 条目中的 `model` 字段是发送给 API 的内容。对于 OpenRouter，你必须使用**完整的**模型 ID，而不是简写。
+**原因：** PicoClaw 现在按两步解析 provider 和 model：
 
-- **错误：** `"model": "free"` → OpenRouter 收到 `free` 并拒绝。
-- **正确：** `"model": "openrouter/free"` → OpenRouter 收到 `openrouter/free`（自动免费层路由）。
+- 如果设置了 `provider`，则会把 `model` 原样发送给该 provider。
+- 如果未设置 `provider`，则会把 `model` 第一个 `/` 之前的字段当作 provider，并把第一个 `/` 之后的全部内容当作最终发送的模型 ID。
+
+对于 OpenRouter 免费层路由，推荐显式设置 `provider`。
+
+- **错误：** `"model": "free"` → 不会选中 OpenRouter，`free` 也不是可直接路由的 OpenRouter 模型配置。
+- **正确：** `"provider": "openrouter", "model": "free"` → OpenRouter 收到 `free`。
+- **也兼容：** `"model": "openrouter/free"` → provider 解析为 `openrouter`，最终模型 ID 解析为 `free`。
 
 **修复方法：** 在 `~/.picoclaw/config.json`（或你的配置路径）中：
 
 1. **agents.defaults.model_name** 必须匹配 `model_list` 中的某个 `model_name`（例如 `"openrouter-free"`）。
-2. 该条目的 **model** 必须是有效的 OpenRouter 模型 ID，例如：
-   - `"openrouter/free"` – 自动免费层
+2. 该条目推荐显式设置 **provider** 为 `openrouter`，并在 **model** 中填写有效的 OpenRouter 模型 ID，例如：
+   - `"free"` – 自动免费层
    - `"google/gemini-2.0-flash-exp:free"`
    - `"meta-llama/llama-3.1-8b-instruct:free"`
 
@@ -34,8 +40,9 @@
   "model_list": [
     {
       "model_name": "openrouter-free",
-      "model": "openrouter/free",
-      "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
+      "provider": "openrouter",
+      "model": "free",
+      "api_keys": ["sk-or-v1-YOUR_OPENROUTER_KEY"],
       "api_base": "https://openrouter.ai/api/v1"
     }
   ]

docs/project/README.fr.md

@@ -292,24 +292,6 @@ Après cette étape unique, `picoclaw-launcher` s'ouvrira normalement lors des l
 
 </details>
 
-### 💻 TUI Launcher (Recommandé pour les environnements sans interface / SSH)
-
-Le TUI (Terminal UI) Launcher fournit une interface terminal complète pour la configuration et la gestion. Idéal pour les serveurs, Raspberry Pi et autres environnements sans interface graphique.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Pour commencer :**
-
-Utilisez les menus TUI pour : **1)** Configurer un Provider -> **2)** Configurer un Channel -> **3)** Démarrer le Gateway -> **4)** Chattez !
-
-Pour la documentation détaillée du TUI, voir [docs.picoclaw.io](https://docs.picoclaw.io).
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 

docs/project/README.id.md

@@ -289,24 +289,6 @@ Setelah langkah satu kali ini, `picoclaw-launcher` akan terbuka secara normal pa
 
 </details>
 
-### 💻 TUI Launcher (Direkomendasikan untuk Headless / SSH)
-
-TUI (Terminal UI) Launcher menyediakan antarmuka terminal lengkap untuk konfigurasi dan manajemen. Ideal untuk server, Raspberry Pi, dan lingkungan headless lainnya.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Memulai:**
-
-Gunakan menu TUI untuk: **1)** Konfigurasi Provider -> **2)** Konfigurasi Channel -> **3)** Mulai Gateway -> **4)** Chat!
-
-Untuk dokumentasi TUI lengkap, lihat [docs.picoclaw.io](https://docs.picoclaw.io).
-
 ### 📱 Android
 
 Berikan kehidupan kedua untuk ponsel lama Anda! Ubah menjadi Asisten AI pintar dengan PicoClaw.

docs/project/README.it.md

@@ -289,24 +289,6 @@ Dopo questo passaggio una tantum, `picoclaw-launcher` si aprirà normalmente ai
 
 </details>
 
-### 💻 TUI Launcher (Consigliato per Headless / SSH)
-
-Il TUI (Terminal UI) Launcher fornisce un'interfaccia terminale completa per la configurazione e la gestione. Ideale per server, Raspberry Pi e altri ambienti headless.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Per iniziare:**
-
-Usa i menu TUI per: **1)** Configurare un Provider -> **2)** Configurare un Channel -> **3)** Avviare il Gateway -> **4)** Chattare!
-
-Per la documentazione dettagliata del TUI, vedi [docs.picoclaw.io](https://docs.picoclaw.io).
-
 ### 📱 Android
 
 Dai una seconda vita al tuo telefono di dieci anni fa! Trasformalo in un assistente IA intelligente con PicoClaw.
@@ -554,7 +536,20 @@ PicoClaw supporta nativamente [MCP](https://modelcontextprotocol.io/) — connet
 }
 ```
 
-Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](../reference/tools_configuration.md#mcp-tool).
+Puoi gestire i casi MCP più comuni direttamente dalla CLI senza modificare a mano il JSON:
+
+```bash
+picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
+picoclaw mcp list
+picoclaw mcp test filesystem
+```
+
+`picoclaw mcp` agisce come configuration manager: aggiorna `config.json` sotto `tools.mcp.servers`, ma non mantiene in esecuzione il processo del server.
+
+Usa `picoclaw mcp edit` quando ti servono campi avanzati che non sono coperti da `picoclaw mcp add`.
+Per esempio, `picoclaw mcp add` supporta `--deferred` e `--env-file`, mentre `picoclaw mcp edit` resta utile per modifiche JSON dirette e opzioni MCP meno comuni.
+
+Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](../reference/tools_configuration.md#mcp-tool). Per la reference della CLI, vedi [MCP Server CLI](../reference/mcp-cli.md).
 
 ## <img src="../../assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Unisciti al Social Network degli Agent
 
@@ -574,6 +569,11 @@ Connetti PicoClaw al Social Network degli Agent semplicemente inviando un singol
 | `picoclaw status`         | Mostra lo stato                    |
 | `picoclaw version`        | Mostra le info sulla versione      |
 | `picoclaw model`          | Visualizza o cambia il modello predefinito |
+| `picoclaw mcp list`       | Elenca i server MCP configurati    |
+| `picoclaw mcp add ...`    | Aggiunge o aggiorna un server MCP  |
+| `picoclaw mcp test`       | Verifica la raggiungibilità di un server MCP |
+| `picoclaw mcp edit`       | Apre la config per modifiche MCP avanzate |
+| `picoclaw mcp remove`     | Rimuove un server MCP dalla config |
 | `picoclaw cron list`      | Elenca tutti i job pianificati     |
 | `picoclaw cron add ...`   | Aggiunge un job pianificato        |
 | `picoclaw cron disable`   | Disabilita un job pianificato      |
@@ -600,6 +600,7 @@ Per guide dettagliate oltre questo README:
 | [Docker & Avvio Rapido](../guides/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent |
 | [App di Chat](../guides/chat-apps.md) | Tutte le guide di configurazione per 17+ channel |
 | [Configurazione](../guides/configuration.md) | Variabili d'ambiente, struttura del workspace, sandbox di sicurezza |
+| [MCP Server CLI](../reference/mcp-cli.md) | Aggiunta, elenco, test, modifica e rimozione dei server MCP da CLI |
 | [Provider & Modelli](../guides/providers.md) | 30+ provider LLM, routing dei modelli, configurazione model_list |
 | [Spawn & Task Asincroni](../guides/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent |
 | [Hooks](../architecture/hooks/README.md) | Sistema di hook event-driven: observer, interceptor, approval hook |

docs/project/README.ja.md

@@ -289,24 +289,6 @@ docker compose -f docker/docker-compose.yml --profile launcher up -d
 
 </details>
 
-### 💻 TUI Launcher（ヘッドレス / SSH 向け推奨）
-
-TUI（Terminal UI）Launcher は設定と管理のためのフル機能ターミナルインターフェースを提供します。サーバー、Raspberry Pi、その他のヘッドレス環境に最適です。
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**始め方:**
-
-TUI メニューを使って：**1)** Provider を設定 → **2)** Channel を設定 → **3)** Gateway を起動 → **4)** チャット！
-
-TUI の詳細なドキュメントは [docs.picoclaw.io](https://docs.picoclaw.io) を参照してください。
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 

docs/project/README.ko.md

@@ -289,24 +289,6 @@ macOS에서는 인터넷에서 다운로드한 앱이고 Mac App Store 공증을
 
 </details>
 
-### 💻 TUI Launcher (헤드리스 / SSH 권장)
-
-TUI(Terminal UI) Launcher는 설정과 관리를 위한 모든 기능을 갖춘 터미널 인터페이스를 제공합니다. 서버, Raspberry Pi, 기타 헤드리스 환경에 적합합니다.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**시작 방법:**
-
-TUI 메뉴를 사용해 다음 순서로 진행하세요. **1)** 프로바이더 설정 -> **2)** 채널 설정 -> **3)** 게이트웨이 시작 -> **4)** 채팅!
-
-자세한 TUI 문서는 [docs.picoclaw.io](https://docs.picoclaw.io)를 참고하세요.
-
 ### 📱 Android
 
 오래된 스마트폰에 새 생명을 불어넣어 보세요! PicoClaw를 설치하면 스마트 AI 어시스턴트로 바꿀 수 있습니다.

docs/project/README.ms.md

@@ -286,24 +286,6 @@ Selepas langkah sekali ini, `picoclaw-launcher` akan dibuka secara normal pada p
 
 </details>
 
-### 💻 Pelancar TUI (Disyorkan untuk Headless / SSH)
-
-Pelancar TUI menyediakan antara muka terminal lengkap untuk konfigurasi dan pengurusan. Sesuai untuk pelayan, Raspberry Pi, dan persekitaran tanpa kepala lain.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="Pelancar TUI" width="600">
-</p>
-
-**Memulakan:**
-
-Gunakan menu TUI untuk: **1)** Konfigurasikan Penyedia -> **2)** Konfigurasikan Saluran -> **3)** Mulakan Gateway -> **4)** Sembang!
-
-Untuk dokumentasi TUI terperinci, lihat [docs.picoclaw.io](https://docs.picoclaw.io).
-
 ### 📱 Android
 
 Berikan telefon lama anda kehidupan baru! Jadikannya Pembantu AI pintar dengan PicoClaw.

docs/project/README.pt-br.md

@@ -289,24 +289,6 @@ Após esta etapa única, o `picoclaw-launcher` abrirá normalmente nos lançamen
 
 </details>
 
-### 💻 TUI Launcher (Recomendado para Headless / SSH)
-
-O TUI (Terminal UI) Launcher fornece uma interface de terminal completa para configuração e gerenciamento. Ideal para servidores, Raspberry Pi e outros ambientes headless.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Primeiros passos:**
-
-Use os menus do TUI para: **1)** Configurar um Provider -> **2)** Configurar um Channel -> **3)** Iniciar o Gateway -> **4)** Conversar!
-
-Para documentação detalhada do TUI, veja [docs.picoclaw.io](https://docs.picoclaw.io).
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 

docs/project/README.vi.md

@@ -289,24 +289,6 @@ Sau bước này, `picoclaw-launcher` sẽ mở bình thường trong các lần
 
 </details>
 
-### 💻 TUI Launcher (Khuyến nghị cho Headless / SSH)
-
-TUI (Terminal UI) Launcher cung cấp giao diện terminal đầy đủ tính năng để cấu hình và quản lý. Lý tưởng cho máy chủ, Raspberry Pi và các môi trường headless khác.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Bắt đầu:**
-
-Sử dụng menu TUI để: **1)** Cấu hình Provider -> **2)** Cấu hình Channel -> **3)** Khởi động Gateway -> **4)** Trò chuyện!
-
-Để biết tài liệu TUI chi tiết, xem [docs.picoclaw.io](https://docs.picoclaw.io).
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 

docs/project/README.zh.md

@@ -289,24 +289,6 @@ macOS 可能会在首次启动时拦截 `picoclaw-launcher`，因为它从互联
 
 </details>
 
-### 💻 TUI Launcher（推荐无头环境 / SSH）
-
-TUI（终端 UI）Launcher 提供功能完整的终端配置与管理界面，适合服务器、树莓派等无显示器环境。
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**开始使用：**
-
-通过 TUI 菜单：**1)** 配置 Provider -> **2)** 配置 Channel -> **3)** 启动 Gateway -> **4)** 开始聊天！
-
-详细 TUI 文档请参阅 [docs.picoclaw.io](https://docs.picoclaw.io)。
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 

docs/reference/README.md

@@ -3,6 +3,7 @@
 Reference docs for precise configuration, runtime behavior, and tool semantics.
 
 - [Tools Configuration](tools_configuration.md): per-tool configuration, execution policies, MCP, and Skills.
+- [MCP Server CLI](mcp-cli.md): add, list, test, edit, and remove MCP server entries from the command line.
 - [Scheduled Tasks and Cron Jobs](cron.md): schedule types, delivery modes, command gates, and storage.
 - [Config Schema Versioning Guide](config-versioning.md): config schema migration and compatibility notes.
 - [Dynamic Rate Limiting](rate-limiting.md): request throttling behavior for LLM providers.

docs/reference/mcp-cli.md

@@ -0,0 +1,361 @@
+# MCP Server CLI
+
+> Back to [README](../README.md)
+
+PicoClaw includes an `mcp` CLI command group for managing MCP server entries in `config.json`.
+
+This CLI acts as a **configuration manager**:
+
+- it adds, updates, removes, and validates entries under `tools.mcp.servers`
+- it does **not** keep MCP servers running itself
+- the gateway / host still starts the configured servers when MCP is enabled
+
+## Where It Writes
+
+The CLI updates the same config file used by the rest of PicoClaw:
+
+- `PICOCLAW_CONFIG` if set
+- otherwise `~/.picoclaw/config.json`
+
+When the CLI writes the file, it:
+
+- saves atomically
+- preserves the standard 2-space JSON formatting used by PicoClaw
+- validates the generated JSON before writing
+
+Behavior notes:
+
+- `picoclaw mcp add ...` enables `tools.mcp.enabled`
+- removing the last server with `picoclaw mcp remove ...` disables `tools.mcp.enabled`
+
+## Quick Start
+
+Add a stdio server via `npx`:
+
+```bash
+picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
+```
+
+Add a stdio server with environment variables saved in config:
+
+```bash
+picoclaw mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github
+```
+
+Add a stdio server using an env file for secrets:
+
+```bash
+picoclaw mcp add github --env-file .env.github -- npx -y @modelcontextprotocol/server-github
+```
+
+Add a remote HTTP server:
+
+```bash
+picoclaw mcp add context7 --transport http https://mcp.context7.com/mcp
+```
+
+Add a remote HTTP server with auth header, even with flags after the URL:
+
+```bash
+picoclaw mcp add apify "https://mcp.apify.com/" -t http --header "Authorization: Bearer OMITTED"
+```
+
+Add a stdio server using an explicit command separator:
+
+```bash
+picoclaw mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server
+```
+
+Inspect the configured entries:
+
+```bash
+picoclaw mcp list
+picoclaw mcp list --status
+```
+
+Inspect one server's full details and its exposed tools:
+
+```bash
+picoclaw mcp show filesystem
+```
+
+Probe a single server entry:
+
+```bash
+picoclaw mcp test filesystem
+```
+
+Open the raw config for advanced editing:
+
+```bash
+picoclaw mcp edit
+```
+
+## Command Summary
+
+| Command | Purpose |
+|---------|---------|
+| `picoclaw mcp add <name> [flags] <command-or-url> [args...]` | Add or update an MCP server entry |
+| `picoclaw mcp remove <name>` | Remove a server entry from config |
+| `picoclaw mcp list` | List configured MCP servers |
+| `picoclaw mcp show <name>` | Show full details and tools for one server |
+| `picoclaw mcp test <name>` | Try connecting to one configured server |
+| `picoclaw mcp edit` | Open `config.json` in `$EDITOR` |
+
+## `picoclaw mcp add`
+
+Syntax:
+
+```bash
+picoclaw mcp add <name> [flags] <command-or-url> [args...]
+```
+
+Supported flags:
+
+| Flag | Meaning |
+|------|---------|
+| `--env`, `-e` | Add a stdio environment variable in `KEY=value` format. Repeatable. Values are saved to config. |
+| `--env-file` | Attach an env file path to a stdio server. Recommended for secrets you do not want stored inline in `config.json`. |
+| `--header`, `-H` | Add an HTTP header in `Name: Value` or `Name=Value` format. Repeatable. |
+| `--transport`, `-t` | Transport type: `stdio` (default), `http`, or `sse`. |
+| `--force`, `-f` | Overwrite an existing server entry without confirmation. |
+| `--deferred` | Mark the server as deferred: tools are hidden and discoverable on demand. |
+| `--no-deferred` | Mark the server as non-deferred: tools are always loaded into context. |
+
+When neither `--deferred` nor `--no-deferred` is passed, the `deferred` field is omitted from the stored config and the global `discovery.enabled` value applies at runtime.
+
+Supported forms:
+
+```bash
+picoclaw mcp add [flags] <name> <command-or-url> [args...]
+picoclaw mcp add [flags] <name> -- <command> [args...]
+```
+
+Parsing behavior:
+
+- CLI flags can appear before the name, between the name and target, or after the URL for remote transports
+- for `stdio`, the most robust form is `-- <command> [args...]`
+- use the `--` separator when the stdio command itself has arguments that may look like PicoClaw CLI flags
+- without `--`, PicoClaw treats the first two non-flag tokens as `<name>` and `<command-or-url>`
+
+Secret handling:
+
+- `--env KEY=value` stores the resolved value directly in `config.json`
+- use `--env-file` instead when the value is sensitive and should stay outside the main config file
+
+Example:
+
+```bash
+picoclaw mcp add sqlite npx -y @modelcontextprotocol/server-sqlite --db ./mydb.db
+```
+
+This stores:
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "sqlite": {
+          "enabled": true,
+          "type": "stdio",
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db", "./mydb.db"]
+        }
+      }
+    }
+  }
+}
+```
+
+Adding the same server with `--deferred` stores the extra field:
+
+```bash
+picoclaw mcp add --deferred sqlite npx -y @modelcontextprotocol/server-sqlite --db ./mydb.db
+```
+
+```json
+{
+  "sqlite": {
+    "enabled": true,
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db", "./mydb.db"],
+    "deferred": true
+  }
+}
+```
+
+### Add Command Rules
+
+For `stdio`:
+
+- `<command-or-url>` is treated as the command
+- `[args...]` are stored in `args`
+- `--env` is supported
+- `--env-file` is supported and stored in `env_file`
+- `--header` is rejected
+- `-- <command> [args...]` is supported and recommended for unambiguous parsing
+
+For `http` / `sse`:
+
+- `<command-or-url>` must be a valid URL
+- extra command args are rejected
+- `--env` is rejected
+- `--env-file` is rejected
+- `--header` is supported and stored in `headers`
+
+Overwrite behavior:
+
+- if `<name>` already exists, PicoClaw asks for confirmation
+- use `--force` to skip the prompt
+
+Local path validation:
+
+- if the command looks like a local path such as `./server.py` or `/opt/mcp/server`
+- PicoClaw checks that the file exists
+- on non-Windows platforms, it also checks that the file is executable
+
+Clear URL/transport error:
+
+- if the target looks like `https://...` but transport is still `stdio`, PicoClaw returns an explicit error telling you to use `--transport http` or `--transport sse`
+
+## `picoclaw mcp remove`
+
+Syntax:
+
+```bash
+picoclaw mcp remove <name>
+```
+
+This removes the named entry from `tools.mcp.servers`.
+
+If the removed server was the last configured MCP server, PicoClaw also disables `tools.mcp.enabled`.
+
+## `picoclaw mcp list`
+
+Syntax:
+
+```bash
+picoclaw mcp list
+picoclaw mcp list --status
+```
+
+On wide terminals the output is a styled box (same look as `mcp show`). On narrow terminals or when stdout is not a TTY, a plain ASCII table is printed instead.
+
+Output fields:
+
+| Field | Meaning |
+|-------|---------|
+| `Name` | Server key inside `tools.mcp.servers` |
+| `Type` | Effective transport: `stdio`, `http`, or `sse` |
+| `Command` / `Target` | Stored command line for stdio servers, or URL for remote servers |
+| `Status` | `enabled` / `disabled` by default; with `--status`: `ok (N tools)` or `error` |
+| `Deferred` | `deferred` if the per-server override is `true`; `eager` if `false`; omitted if not set |
+
+Notes:
+
+- without `--status`, PicoClaw prints configuration state only
+- with `--status`, PicoClaw tries to connect to each enabled server and reports `ok (N tools)` or `error`
+- to see the full list of tools a server exposes, use `picoclaw mcp show <name>`
+
+## `picoclaw mcp show`
+
+Syntax:
+
+```bash
+picoclaw mcp show <name>
+picoclaw mcp show <name> --timeout 15s
+```
+
+This connects to the named server and prints:
+
+- server metadata: name, transport type, target, enabled state, deferred override, env var names, env file, header names
+- every tool the server exposes, with its name, description, and parameters (name, type, required/optional, description)
+
+On wide terminals the output is a styled box matching the `mcp list` look. On narrow terminals or non-TTY stdout, plain text is printed instead.
+
+Example output (wide terminal):
+
+```
+╭──────────────────────────────────────────────────────────╮
+│ ⬡  filesystem                                            │
+│                                                          │
+│ Type        stdio                                        │
+│ Target      npx -y @modelcontextprotocol/server-fs /tmp  │
+│ Enabled     yes                                          │
+│ Deferred    no                                           │
+│                                                          │
+│ Tools (3)                                                │
+│                                                          │
+│   read_file  [1/3]                                       │
+│   Read the complete contents of a file from the disk     │
+│                                                          │
+│     path  <string>  required                             │
+│       Path to the file to read                           │
+│ ──────────────────────────────────────────────────────── │
+│   ...                                                    │
+╰──────────────────────────────────────────────────────────╯
+```
+
+Flags:
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--timeout` | `10s` | Connection timeout |
+
+Notes:
+
+- if the server is disabled in config, `mcp show` prints the metadata only and skips tool discovery
+- `mcp show` always connects live to fetch the tool list; use `mcp test` if you only need a reachability check
+
+## `picoclaw mcp test`
+
+Syntax:
+
+```bash
+picoclaw mcp test <name>
+```
+
+This performs a direct connection test for one configured entry and prints the number of discovered tools when successful.
+
+It is useful when:
+
+- you want to verify a newly added server before starting the gateway
+- you want to debug one server without probing the whole list
+- the entry is currently disabled in config but you still want to validate its definition
+
+## `picoclaw mcp edit`
+
+Syntax:
+
+```bash
+picoclaw mcp edit
+```
+
+This opens the config file in the editor pointed to by `$EDITOR`.
+
+Use it when you need to configure MCP fields that are not exposed directly by `picoclaw mcp add`.
+
+If `$EDITOR` is not set, the command fails with an explicit error.
+
+## Recommended Workflow
+
+For common cases:
+
+1. Add the server with `picoclaw mcp add` (include `--deferred` if you want tools hidden by default).
+2. Verify connectivity and inspect the exposed tools with `picoclaw mcp show <name>`.
+3. Check all servers at a glance with `picoclaw mcp list --status`.
+4. Start PicoClaw normally so the configured MCP server is loaded by the host.
+
+For advanced cases:
+
+1. Add the base entry with `picoclaw mcp add`.
+2. Run `picoclaw mcp edit` to fill in fields that are not exposed as CLI flags.
+3. Run `picoclaw mcp show <name>` to confirm the final configuration and tool list.
+
+## Related Docs
+
+- [Tools Configuration](tools_configuration.md#mcp-tool): MCP config structure, transports, discovery, and examples
+- [README](../README.md): high-level overview

docs/reference/rate-limiting.md

@@ -39,20 +39,23 @@ Set `rpm` on any model in `model_list`:
 ```yaml
 model_list:
   - model_name: gpt-4o-free
-    model: openai/gpt-4o
+    provider: openai
+    model: gpt-4o
     api_base: https://api.openai.com/v1
     rpm: 3          # max 3 requests per minute
     api_keys:
       - sk-...
 
   - model_name: claude-haiku
-    model: anthropic/claude-haiku-4-5
+    provider: anthropic
+    model: claude-haiku-4-5
     rpm: 60         # 60 rpm (Anthropic free tier)
     api_keys:
       - sk-ant-...
 
   - model_name: local-llm
-    model: openai/llama3
+    provider: ollama
+    model: llama3
     api_base: http://localhost:11434/v1
     # no rpm → unrestricted
 ```
@@ -68,7 +71,8 @@ When a model has fallbacks configured, each candidate is rate-limited **independ
 ```yaml
 model_list:
   - model_name: gpt4-with-fallback
-    model: openai/gpt-4o
+    provider: openai
+    model: gpt-4o
     rpm: 5
     fallbacks:
       - gpt-4o-mini   # must also be in model_list; its own rpm applies

docs/reference/tools_configuration.md

@@ -258,6 +258,17 @@ For schedule types, execution modes (`deliver`, agent turn, and command jobs), p
 
 The MCP tool enables integration with external Model Context Protocol servers.
 
+If you prefer not to edit JSON manually, PicoClaw also provides an MCP configuration manager CLI:
+
+- `picoclaw mcp add` — add or update a server (supports `--deferred` / `--no-deferred`)
+- `picoclaw mcp list` — list all configured servers with status and deferred state
+- `picoclaw mcp show <name>` — show full details and the tool list for one server
+- `picoclaw mcp test <name>` — connectivity check for one server
+- `picoclaw mcp remove <name>` — remove a server entry
+- `picoclaw mcp edit` — open `config.json` in `$EDITOR` for advanced edits
+
+These commands manage the same `tools.mcp.servers` section documented below. See [MCP Server CLI](mcp-cli.md) for command syntax, examples, and behavior details.
+
 ### Tool Discovery (Lazy Loading)
 
 When connecting to multiple MCP servers, exposing hundreds of tools simultaneously can exhaust the LLM's context window

go.mod

@@ -4,26 +4,24 @@ go 1.25.9
 
 require (
 	fyne.io/systray v1.12.0
-	github.com/BurntSushi/toml v1.6.0
 	github.com/SevereCloud/vksdk/v3 v3.3.1
 	github.com/adhocore/gronx v1.19.6
 	github.com/anthropics/anthropic-sdk-go v1.26.0
 	github.com/atc0005/go-teams-notify/v2 v2.14.0
-	github.com/aws/aws-sdk-go-v2 v1.41.5
-	github.com/aws/aws-sdk-go-v2/config v1.32.14
-	github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.4
+	github.com/aws/aws-sdk-go-v2 v1.41.6
+	github.com/aws/aws-sdk-go-v2/config v1.32.16
+	github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.5
 	github.com/bwmarrin/discordgo v0.29.0
 	github.com/caarlos0/env/v11 v11.4.0
 	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/creack/pty v1.1.24
 	github.com/ergochat/irc-go v0.6.0
 	github.com/ergochat/readline v0.1.3
-	github.com/gdamore/tcell/v2 v2.13.8
 	github.com/gomarkdown/markdown v0.0.0-20260411013819-759bbc3e3207
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/h2non/filetype v1.1.3
-	github.com/larksuite/oapi-sdk-go/v3 v3.5.3
+	github.com/larksuite/oapi-sdk-go/v3 v3.5.4
 	github.com/mdp/qrterminal/v3 v3.2.1
 	github.com/minio/selfupdate v0.6.0
 	github.com/modelcontextprotocol/go-sdk v1.5.0
@@ -33,8 +31,7 @@ require (
 	github.com/openai/openai-go/v3 v3.22.0
 	github.com/pion/rtp v1.10.1
 	github.com/pion/webrtc/v3 v3.3.6
-	github.com/rivo/tview v0.42.0
-	github.com/rs/zerolog v1.35.0
+	github.com/rs/zerolog v1.35.1
 	github.com/slack-go/slack v0.17.3
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/pflag v1.0.10
@@ -55,19 +52,19 @@ require (
 require (
 	aead.dev/minisign v0.2.0 // indirect
 	filippo.io/edwards25519 v1.2.0 // indirect
-	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 // indirect
-	github.com/aws/aws-sdk-go-v2/credentials v1.19.14 // indirect
-	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.21 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 // indirect
-	github.com/aws/aws-sdk-go-v2/service/signin v1.0.9 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sso v1.30.15 // indirect
-	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.19 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sts v1.41.10 // indirect
-	github.com/aws/smithy-go v1.24.2 // indirect
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.9 // indirect
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.15 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.22 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.22 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.22 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.23 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.8 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.22 // indirect
+	github.com/aws/aws-sdk-go-v2/service/signin v1.0.10 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.30.16 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.20 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.42.0 // indirect
+	github.com/aws/smithy-go v1.25.0 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/beeper/argo-go v1.1.2 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
@@ -79,7 +76,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/gdamore/encoding v1.0.1 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/godbus/dbus/v5 v5.1.0 // indirect
@@ -122,7 +118,7 @@ require (
 	github.com/github/copilot-sdk/go v0.2.0
 	github.com/go-resty/resty/v2 v2.17.1 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/google/jsonschema-go v0.4.2 // indirect
+	github.com/google/jsonschema-go v0.4.2
 	github.com/grbit/go-json v0.11.0 // indirect
 	github.com/klauspost/compress v1.18.4 // indirect
 	github.com/klauspost/cpuid/v2 v2.3.0 // indirect

go.sum

@@ -5,8 +5,6 @@ filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
 filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
 fyne.io/systray v1.12.0 h1:CA1Kk0e2zwFlxtc02L3QFSiIbxJ/P0n582YrZHT7aTM=
 fyne.io/systray v1.12.0/go.mod h1:RVwqP9nYMo7h5zViCBHri2FgjXF7H2cub7MAq4NSoLs=
-github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
-github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
 github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
 github.com/DATA-DOG/go-sqlmock v1.5.2/go.mod h1:88MAG/4G7SMwSE3CeA0ZKzrT5CiOU3OJ+JlNzwDqpNU=
 github.com/SevereCloud/vksdk/v3 v3.3.1 h1:O86zsp5LQnHE+O5acvuXM/s6S1LyxzVTkF6+Lup0Jyg=
@@ -23,38 +21,38 @@ github.com/anthropics/anthropic-sdk-go v1.26.0 h1:oUTzFaUpAevfuELAP1sjL6CQJ9HHAf
 github.com/anthropics/anthropic-sdk-go v1.26.0/go.mod h1:qUKmaW+uuPB64iy1l+4kOSvaLqPXnHTTBKH6RVZ7q5Q=
 github.com/atc0005/go-teams-notify/v2 v2.14.0 h1:7N+xw+COnYANLREaAveQ65rsNQ12nIZJED9nMLyscCo=
 github.com/atc0005/go-teams-notify/v2 v2.14.0/go.mod h1:EECsWM2b0Hvoz7O+QdlsvyN2KCUOFQCGj8bUBXv3A3Q=
-github.com/aws/aws-sdk-go-v2 v1.41.5 h1:dj5kopbwUsVUVFgO4Fi5BIT3t4WyqIDjGKCangnV/yY=
-github.com/aws/aws-sdk-go-v2 v1.41.5/go.mod h1:mwsPRE8ceUUpiTgF7QmQIJ7lgsKUPQOUl3o72QBrE1o=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 h1:eBMB84YGghSocM7PsjmmPffTa+1FBUeNvGvFou6V/4o=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8/go.mod h1:lyw7GFp3qENLh7kwzf7iMzAxDn+NzjXEAGjKS2UOKqI=
-github.com/aws/aws-sdk-go-v2/config v1.32.14 h1:opVIRo/ZbbI8OIqSOKmpFaY7IwfFUOCCXBsUpJOwDdI=
-github.com/aws/aws-sdk-go-v2/config v1.32.14/go.mod h1:U4/V0uKxh0Tl5sxmCBZ3AecYny4UNlVmObYjKuuaiOo=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.14 h1:n+UcGWAIZHkXzYt87uMFBv/l8THYELoX6gVcUvgl6fI=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.14/go.mod h1:cJKuyWB59Mqi0jM3nFYQRmnHVQIcgoxjEMAbLkpr62w=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.21 h1:NUS3K4BTDArQqNu2ih7yeDLaS3bmHD0YndtA6UP884g=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.21/go.mod h1:YWNWJQNjKigKY1RHVJCuupeWDrrHjRqHm0N9rdrWzYI=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 h1:Rgg6wvjjtX8bNHcvi9OnXWwcE0a2vGpbwmtICOsvcf4=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21/go.mod h1:A/kJFst/nm//cyqonihbdpQZwiUhhzpqTsdbhDdRF9c=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 h1:PEgGVtPoB6NTpPrBgqSE5hE/o47Ij9qk/SEZFbUOe9A=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21/go.mod h1:p+hz+PRAYlY3zcpJhPwXlLC4C+kqn70WIHwnzAfs6ps=
-github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6 h1:qYQ4pzQ2Oz6WpQ8T3HvGHnZydA72MnLuFK9tJwmrbHw=
-github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6/go.mod h1:O3h0IK87yXci+kg6flUKzJnWeziQUKciKrLjcatSNcY=
-github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.4 h1:W6tKfa/s37faUnwJ71pGqsBO7/wfUX1L7tVprupQGo4=
-github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.4/go.mod h1:BZ+9thH0QOTDUwE8KAv/ZwUzsNC7CSMJXj/wtnZMs5k=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 h1:5EniKhLZe4xzL7a+fU3C2tfUN4nWIqlLesfrjkuPFTY=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7/go.mod h1:x0nZssQ3qZSnIcePWLvcoFisRXJzcTVvYpAAdYX8+GI=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 h1:c31//R3xgIJMSC8S6hEVq+38DcvUlgFY0FM6mSI5oto=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21/go.mod h1:r6+pf23ouCB718FUxaqzZdbpYFyDtehyZcmP5KL9FkA=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.9 h1:QKZH0S178gCmFEgst8hN0mCX1KxLgHBKKY/CLqwP8lg=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.9/go.mod h1:7yuQJoT+OoH8aqIxw9vwF+8KpvLZ8AWmvmUWHsGQZvI=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.15 h1:lFd1+ZSEYJZYvv9d6kXzhkZu07si3f+GQ1AaYwa2LUM=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.15/go.mod h1:WSvS1NLr7JaPunCXqpJnWk1Bjo7IxzZXrZi1QQCkuqM=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.19 h1:dzztQ1YmfPrxdrOiuZRMF6fuOwWlWpD2StNLTceKpys=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.19/go.mod h1:YO8TrYtFdl5w/4vmjL8zaBSsiNp3w0L1FfKVKenZT7w=
-github.com/aws/aws-sdk-go-v2/service/sts v1.41.10 h1:p8ogvvLugcR/zLBXTXrTkj0RYBUdErbMnAFFp12Lm/U=
-github.com/aws/aws-sdk-go-v2/service/sts v1.41.10/go.mod h1:60dv0eZJfeVXfbT1tFJinbHrDfSJ2GZl4Q//OSSNAVw=
-github.com/aws/smithy-go v1.24.2 h1:FzA3bu/nt/vDvmnkg+R8Xl46gmzEDam6mZ1hzmwXFng=
-github.com/aws/smithy-go v1.24.2/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/aws/aws-sdk-go-v2 v1.41.6 h1:1AX0AthnBQzMx1vbmir3Y4WsnJgiydmnJjiLu+LvXOg=
+github.com/aws/aws-sdk-go-v2 v1.41.6/go.mod h1:dy0UzBIfwSeot4grGvY1AqFWN5zgziMmWGzysDnHFcQ=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.9 h1:adBsCIIpLbLmYnkQU+nAChU5yhVTvu5PerROm+/Kq2A=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.9/go.mod h1:uOYhgfgThm/ZyAuJGNQ5YgNyOlYfqnGpTHXvk3cpykg=
+github.com/aws/aws-sdk-go-v2/config v1.32.16 h1:Q0iQ7quUgJP0F/SCRTieScnaMdXr9h/2+wze1u3cNeM=
+github.com/aws/aws-sdk-go-v2/config v1.32.16/go.mod h1:duCCnJEFqpt2RC6no1iK6q+8HpwOAkiUua0pY507dQc=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.15 h1:fyvgWTszojq8hEnMi8PPBTvZdTtEVmAVyo+NFLHBhH4=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.15/go.mod h1:gJiYyMOjNg8OEdRWOf3CrFQxM2a98qmrtjx1zuiQfB8=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.22 h1:IOGsJ1xVWhsi+ZO7/NW8OuZZBtMJLZbk4P5HDjJO0jQ=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.22/go.mod h1:b+hYdbU+jGKfXE8kKM6g1+h+L/Go3vMvzlxBsiuGsxg=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.22 h1:GmLa5Kw1ESqtFpXsx5MmC84QWa/ZrLZvlJGa2y+4kcQ=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.22/go.mod h1:6sW9iWm9DK9YRpRGga/qzrzNLgKpT2cIxb7Vo2eNOp0=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.22 h1:dY4kWZiSaXIzxnKlj17nHnBcXXBfac6UlsAx2qL6XrU=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.22/go.mod h1:KIpEUx0JuRZLO7U6cbV204cWAEco2iC3l061IxlwLtI=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.23 h1:FPXsW9+gMuIeKmz7j6ENWcWtBGTe1kH8r9thNt5Uxx4=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.23/go.mod h1:7J8iGMdRKk6lw2C+cMIphgAnT8uTwBwNOsGkyOCm80U=
+github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.5 h1:ZGTl4Rxft1uyENAlGESY04hMzE4cLLNUPI7dGw08haw=
+github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.5/go.mod h1:jnugA+VgESQGgXuEKK6zVToET/DtODq7LQYpe+BkKT4=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.8 h1:HtOTYcbVcGABLOVuPYaIihj6IlkqubBwFj10K5fxRek=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.8/go.mod h1:VsK9abqQeGlzPgUr+isNWzPlK2vKe9INMLWnY65f5Xs=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.22 h1:PUmZeJU6Y1Lbvt9WFuJ0ugUK2xn6hIWUBBbKuOWF30s=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.22/go.mod h1:nO6egFBoAaoXze24a2C0NjQCvdpk8OueRoYimvEB9jo=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.10 h1:a1Fq/KXn75wSzoJaPQTgZO0wHGqE9mjFnylnqEPTchA=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.10/go.mod h1:p6+MXNxW7IA6dMgHfTAzljuwSKD0NCm/4lbS4t6+7vI=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.16 h1:x6bKbmDhsgSZwv6q19wY/u3rLk/3FGjJWyqKcIRufpE=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.16/go.mod h1:CudnEVKRtLn0+3uMV0yEXZ+YZOKnAtUJ5DmDhilVnIw=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.20 h1:oK/njaL8GtyEihkWMD4k3VgHCT64RQKkZwh0DG5j8ak=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.20/go.mod h1:JHs8/y1f3zY7U5WcuzoJ/yAYGYtNIVPKLIbp61euvmg=
+github.com/aws/aws-sdk-go-v2/service/sts v1.42.0 h1:ks8KBcZPh3PYISr5dAiXCM5/Thcuxk8l+PG4+A0exds=
+github.com/aws/aws-sdk-go-v2/service/sts v1.42.0/go.mod h1:pFw33T0WLvXU3rw1WBkpMlkgIn54eCB5FYLhjDc9Foo=
+github.com/aws/smithy-go v1.25.0 h1:Sz/XJ64rwuiKtB6j98nDIPyYrV1nVNJ4YU74gttcl5U=
+github.com/aws/smithy-go v1.25.0/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
 github.com/beeper/argo-go v1.1.2 h1:UQI2G8F+NLfGTOmTUI0254pGKx/HUU/etbUGTJv91Fs=
@@ -105,10 +103,6 @@ github.com/ergochat/readline v0.1.3 h1:/DytGTmwdUJcLAe3k3VJgowh5vNnsdifYT6uVaf4p
 github.com/ergochat/readline v0.1.3/go.mod h1:o3ux9QLHLm77bq7hDB21UTm6HlV2++IPDMfIfKDuOgY=
 github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
 github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ=
-github.com/gdamore/encoding v1.0.1 h1:YzKZckdBL6jVt2Gc+5p82qhrGiqMdG/eNs6Wy0u3Uhw=
-github.com/gdamore/encoding v1.0.1/go.mod h1:0Z0cMFinngz9kS1QfMjCP8TY7em3bZYeeklsSDPivEo=
-github.com/gdamore/tcell/v2 v2.13.8 h1:Mys/Kl5wfC/GcC5Cx4C2BIQH9dbnhnkPgS9/wF3RlfU=
-github.com/gdamore/tcell/v2 v2.13.8/go.mod h1:+Wfe208WDdB7INEtCsNrAN6O2m+wsTPk1RAovjaILlo=
 github.com/github/copilot-sdk/go v0.2.0 h1:RnrIIirmtp4wGgqSQFJ2k9phbeveIxOtYZqDogoNEa0=
 github.com/github/copilot-sdk/go v0.2.0/go.mod h1:uGWkjVYcp2DV9DgtqYihh5tEoJjNqxIFaUNnrwY4FxM=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
@@ -138,8 +132,6 @@ github.com/golang/protobuf v1.4.0/go.mod h1:jodUvKwWbYaEsadDk5Fwe5c77LiNKVO9IDvq
 github.com/golang/protobuf v1.4.2/go.mod h1:oDoupMAO8OvCJWAcko0GGGIgR6R6ocIYbsSw735rRwI=
 github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
 github.com/golang/protobuf v1.5.2/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiuN0vRsmY=
-github.com/gomarkdown/markdown v0.0.0-20260217112301-37c66b85d6ab h1:VYNivV7P8IRHUam2swVUNkhIdp0LRRFKe4hXNnoZKTc=
-github.com/gomarkdown/markdown v0.0.0-20260217112301-37c66b85d6ab/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
 github.com/gomarkdown/markdown v0.0.0-20260411013819-759bbc3e3207 h1:p7t34F7K4OCRQblcDhNJnP46Uaarz3z2cLcvOZYxWn8=
 github.com/gomarkdown/markdown v0.0.0-20260411013819-759bbc3e3207/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
 github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
@@ -185,8 +177,8 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/larksuite/oapi-sdk-go/v3 v3.5.3 h1:xvf8Dv29kBXC5/DNDCLhHkAFW8l/0LlQJimO5Zn+JUk=
-github.com/larksuite/oapi-sdk-go/v3 v3.5.3/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
+github.com/larksuite/oapi-sdk-go/v3 v3.5.4 h1:U2S9x9LrfH++ZqJ+YAiUlqzCWJmVXhFdS8Z7rIBH8H0=
+github.com/larksuite/oapi-sdk-go/v3 v3.5.4/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
 github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
 github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
@@ -234,8 +226,6 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
-github.com/rivo/tview v0.42.0 h1:b/ftp+RxtDsHSaynXTbJb+/n/BxDEi+W3UfF5jILK6c=
-github.com/rivo/tview v0.42.0/go.mod h1:cSfIYfhpSGCjp3r/ECJb+GKS7cGJnqV8vfjQPwoXyfY=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
@@ -243,8 +233,8 @@ github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTE
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/rogpeppe/go-internal v1.13.1 h1:KvO1DLK/DRN07sQ1LQKScxyZJuNnedQ5/wKSR38lUII=
 github.com/rogpeppe/go-internal v1.13.1/go.mod h1:uMEvuHeurkdAXX61udpOXGD/AzZDWNMNyH2VO9fmH0o=
-github.com/rs/zerolog v1.35.0 h1:VD0ykx7HMiMJytqINBsKcbLS+BJ4WYjz+05us+LRTdI=
-github.com/rs/zerolog v1.35.0/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
+github.com/rs/zerolog v1.35.1 h1:m7xQeoiLIiV0BCEY4Hs+j2NG4Gp2o2KPKmhnnLiazKI=
+github.com/rs/zerolog v1.35.1/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
 github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=

pkg/agent/adapters/channelmanager.go

@@ -43,3 +43,9 @@ func (a *channelManagerAdapter) SendMedia(ctx context.Context, msg bus.OutboundM
 func (a *channelManagerAdapter) SendPlaceholder(ctx context.Context, channel, chatID string) bool {
 	return a.inner.SendPlaceholder(ctx, channel, chatID)
 }
+
+func (a *channelManagerAdapter) DismissToolFeedback(
+	ctx context.Context, channel, chatID string, outboundCtx *bus.InboundContext,
+) {
+	a.inner.DismissToolFeedback(ctx, channel, chatID, outboundCtx)
+}

pkg/agent/agent.go

@@ -111,7 +111,10 @@ const (
 	sessionKeyAgentPrefix      = "agent:"
 	pendingTurnPrefix          = "pending-"
 	metadataKeyMessageKind     = "message_kind"
+	metadataKeyToolCalls       = "tool_calls"
 	messageKindThought         = "thought"
+	messageKindToolFeedback    = "tool_feedback"
+	messageKindToolCalls       = "tool_calls"
 	metadataKeyAccountID       = "account_id"
 	metadataKeyGuildID         = "guild_id"
 	metadataKeyTeamID          = "team_id"

pkg/agent/agent_command.go

@@ -4,11 +4,15 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
+	"sort"
 	"strings"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/commands"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
@@ -133,6 +137,120 @@ func (al *AgentLoop) buildCommandsRuntime(
 		Config:          cfg,
 		ListAgentIDs:    registry.ListAgentIDs,
 		ListDefinitions: al.cmdRegistry.Definitions,
+		ListMCPServers: func(ctx context.Context) []commands.MCPServerInfo {
+			if cfg == nil {
+				return nil
+			}
+
+			if len(cfg.Tools.MCP.Servers) == 0 {
+				return nil
+			}
+
+			if err := al.ensureMCPInitialized(ctx); err != nil {
+				logger.WarnCF("agent", "Failed to refresh MCP status for command",
+					map[string]any{
+						"error": err.Error(),
+					})
+			}
+
+			connected := make(map[string]int)
+			if manager := al.mcp.getManager(); manager != nil {
+				for serverName, conn := range manager.GetServers() {
+					connected[serverName] = len(conn.Tools)
+				}
+			}
+
+			servers := make([]commands.MCPServerInfo, 0, len(cfg.Tools.MCP.Servers))
+			for serverName, serverCfg := range cfg.Tools.MCP.Servers {
+				toolCount, isConnected := connected[serverName]
+				servers = append(servers, commands.MCPServerInfo{
+					Name:      serverName,
+					Enabled:   serverCfg.Enabled,
+					Deferred:  serverIsDeferred(cfg.Tools.MCP.Discovery.Enabled, serverCfg),
+					Connected: isConnected,
+					ToolCount: toolCount,
+				})
+			}
+
+			sort.Slice(servers, func(i, j int) bool {
+				return strings.ToLower(servers[i].Name) < strings.ToLower(servers[j].Name)
+			})
+
+			return servers
+		},
+		ListMCPTools: func(ctx context.Context, serverName string) ([]commands.MCPToolInfo, error) {
+			if cfg == nil {
+				return nil, fmt.Errorf("command unavailable: config not loaded")
+			}
+
+			serverName = strings.TrimSpace(serverName)
+			if serverName == "" {
+				return nil, fmt.Errorf("server name is required")
+			}
+
+			resolvedName := ""
+			var serverCfg config.MCPServerConfig
+			for name, candidate := range cfg.Tools.MCP.Servers {
+				if strings.EqualFold(name, serverName) {
+					resolvedName = name
+					serverCfg = candidate
+					break
+				}
+			}
+			if resolvedName == "" {
+				return nil, fmt.Errorf("MCP server '%s' is not configured", serverName)
+			}
+			if !serverCfg.Enabled {
+				return nil, fmt.Errorf("MCP server '%s' is configured but disabled", resolvedName)
+			}
+			if !cfg.Tools.IsToolEnabled("mcp") {
+				return nil, fmt.Errorf("MCP integration is disabled")
+			}
+
+			if err := al.ensureMCPInitialized(ctx); err != nil {
+				logger.WarnCF("agent", "Failed to initialize MCP runtime for command",
+					map[string]any{
+						"server": resolvedName,
+						"error":  err.Error(),
+					})
+			}
+
+			manager := al.mcp.getManager()
+			if manager == nil {
+				return nil, fmt.Errorf("MCP server '%s' is configured but not connected", resolvedName)
+			}
+
+			conn, ok := manager.GetServer(resolvedName)
+			if !ok {
+				return nil, fmt.Errorf("MCP server '%s' is configured but not connected", resolvedName)
+			}
+
+			toolInfos := make([]commands.MCPToolInfo, 0, len(conn.Tools))
+			for _, tool := range conn.Tools {
+				if tool == nil {
+					continue
+				}
+				name := strings.TrimSpace(tool.Name)
+				if name == "" {
+					continue
+				}
+
+				description := strings.TrimSpace(tool.Description)
+				if description == "" {
+					description = fmt.Sprintf("MCP tool from %s server", resolvedName)
+				}
+
+				toolInfos = append(toolInfos, commands.MCPToolInfo{
+					Name:        name,
+					Description: description,
+					Parameters:  summarizeMCPToolParameters(tool.InputSchema),
+				})
+			}
+			sort.Slice(toolInfos, func(i, j int) bool {
+				return toolInfos[i].Name < toolInfos[j].Name
+			})
+			return toolInfos, nil
+		},
 		GetEnabledChannels: func() []string {
 			if al.channelManager == nil {
 				return nil
@@ -236,6 +354,96 @@ func (al *AgentLoop) buildCommandsRuntime(
 	return rt
 }
 
+func summarizeMCPToolParameters(schema any) []commands.MCPToolParameterInfo {
+	schemaMap := normalizeMCPSchema(schema)
+	properties, ok := schemaMap["properties"].(map[string]any)
+	if !ok || len(properties) == 0 {
+		return nil
+	}
+
+	required := make(map[string]struct{})
+	switch raw := schemaMap["required"].(type) {
+	case []string:
+		for _, name := range raw {
+			required[name] = struct{}{}
+		}
+	case []any:
+		for _, value := range raw {
+			name, ok := value.(string)
+			if ok {
+				required[name] = struct{}{}
+			}
+		}
+	}
+
+	names := make([]string, 0, len(properties))
+	for name := range properties {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	params := make([]commands.MCPToolParameterInfo, 0, len(names))
+	for _, name := range names {
+		param := commands.MCPToolParameterInfo{Name: name}
+		if propMap, ok := properties[name].(map[string]any); ok {
+			if typeName, ok := propMap["type"].(string); ok {
+				param.Type = strings.TrimSpace(typeName)
+			}
+			if desc, ok := propMap["description"].(string); ok {
+				param.Description = strings.TrimSpace(desc)
+			}
+		}
+		_, param.Required = required[name]
+		params = append(params, param)
+	}
+	return params
+}
+
+func normalizeMCPSchema(schema any) map[string]any {
+	if schema == nil {
+		return map[string]any{
+			"type":       "object",
+			"properties": map[string]any{},
+			"required":   []string{},
+		}
+	}
+
+	if schemaMap, ok := schema.(map[string]any); ok {
+		return schemaMap
+	}
+
+	var jsonData []byte
+	switch raw := schema.(type) {
+	case json.RawMessage:
+		jsonData = raw
+	case []byte:
+		jsonData = raw
+	}
+
+	if jsonData == nil {
+		var err error
+		jsonData, err = json.Marshal(schema)
+		if err != nil {
+			return map[string]any{
+				"type":       "object",
+				"properties": map[string]any{},
+				"required":   []string{},
+			}
+		}
+	}
+
+	var result map[string]any
+	if err := json.Unmarshal(jsonData, &result); err != nil {
+		return map[string]any{
+			"type":       "object",
+			"properties": map[string]any{},
+			"required":   []string{},
+		}
+	}
+
+	return result
+}
+
 func (al *AgentLoop) setPendingSkills(sessionKey string, skillNames []string) {
 	sessionKey = strings.TrimSpace(sessionKey)
 	if sessionKey == "" || len(skillNames) == 0 {

pkg/agent/agent_init.go

@@ -100,33 +100,7 @@ func registerSharedTools(
 		}
 
 		if cfg.Tools.IsToolEnabled("web") {
-			searchTool, err := tools.NewWebSearchTool(tools.WebSearchToolOptions{
-				BraveAPIKeys:          cfg.Tools.Web.Brave.APIKeys.Values(),
-				BraveMaxResults:       cfg.Tools.Web.Brave.MaxResults,
-				BraveEnabled:          cfg.Tools.Web.Brave.Enabled,
-				TavilyAPIKeys:         cfg.Tools.Web.Tavily.APIKeys.Values(),
-				TavilyBaseURL:         cfg.Tools.Web.Tavily.BaseURL,
-				TavilyMaxResults:      cfg.Tools.Web.Tavily.MaxResults,
-				TavilyEnabled:         cfg.Tools.Web.Tavily.Enabled,
-				DuckDuckGoMaxResults:  cfg.Tools.Web.DuckDuckGo.MaxResults,
-				DuckDuckGoEnabled:     cfg.Tools.Web.DuckDuckGo.Enabled,
-				PerplexityAPIKeys:     cfg.Tools.Web.Perplexity.APIKeys.Values(),
-				PerplexityMaxResults:  cfg.Tools.Web.Perplexity.MaxResults,
-				PerplexityEnabled:     cfg.Tools.Web.Perplexity.Enabled,
-				SearXNGBaseURL:        cfg.Tools.Web.SearXNG.BaseURL,
-				SearXNGMaxResults:     cfg.Tools.Web.SearXNG.MaxResults,
-				SearXNGEnabled:        cfg.Tools.Web.SearXNG.Enabled,
-				GLMSearchAPIKey:       cfg.Tools.Web.GLMSearch.APIKey.String(),
-				GLMSearchBaseURL:      cfg.Tools.Web.GLMSearch.BaseURL,
-				GLMSearchEngine:       cfg.Tools.Web.GLMSearch.SearchEngine,
-				GLMSearchMaxResults:   cfg.Tools.Web.GLMSearch.MaxResults,
-				GLMSearchEnabled:      cfg.Tools.Web.GLMSearch.Enabled,
-				BaiduSearchAPIKey:     cfg.Tools.Web.BaiduSearch.APIKey.String(),
-				BaiduSearchBaseURL:    cfg.Tools.Web.BaiduSearch.BaseURL,
-				BaiduSearchMaxResults: cfg.Tools.Web.BaiduSearch.MaxResults,
-				BaiduSearchEnabled:    cfg.Tools.Web.BaiduSearch.Enabled,
-				Proxy:                 cfg.Tools.Web.Proxy,
-			})
+			searchTool, err := tools.NewWebSearchTool(tools.WebSearchToolOptionsFromConfig(cfg))
 			if err != nil {
 				logger.ErrorCF("agent", "Failed to create web search tool", map[string]any{"error": err.Error()})
 			} else if searchTool != nil {
@@ -154,6 +128,9 @@ func registerSharedTools(
 		if cfg.Tools.IsToolEnabled("spi") {
 			agent.Tools.Register(tools.NewSPITool())
 		}
+		if cfg.Tools.IsToolEnabled("serial") {
+			agent.Tools.Register(tools.NewSerialTool())
+		}
 
 		// Message tool
 		if cfg.Tools.IsToolEnabled("message") {

pkg/agent/agent_mcp.go

@@ -67,6 +67,12 @@ func (r *mcpRuntime) hasManager() bool {
 	return r.manager != nil
 }
 
+func (r *mcpRuntime) getManager() *mcp.Manager {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.manager
+}
+
 // ensureMCPInitialized loads MCP servers/tools once so both Run() and direct
 // agent mode share the same initialization path.
 func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {
@@ -100,6 +106,7 @@ func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {
 		}
 
 		if err := mcpManager.LoadFromMCPConfig(ctx, al.cfg.Tools.MCP, workspacePath); err != nil {
+			al.mcp.setInitErr(fmt.Errorf("failed to load MCP servers: %w", err))
 			logger.WarnCF("agent", "Failed to load MCP servers, MCP tools will not be available",
 				map[string]any{
 					"error": err.Error(),
@@ -128,6 +135,25 @@ func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {
 			serverCfg := al.cfg.Tools.MCP.Servers[serverName]
 			registerAsHidden := serverIsDeferred(al.cfg.Tools.MCP.Discovery.Enabled, serverCfg)
 
+			for _, agentID := range agentIDs {
+				agent, ok := al.registry.GetAgent(agentID)
+				if !ok || agent.ContextBuilder == nil {
+					continue
+				}
+				if err := agent.ContextBuilder.RegisterPromptContributor(mcpServerPromptContributor{
+					serverName: serverName,
+					toolCount:  len(conn.Tools),
+					deferred:   registerAsHidden,
+				}); err != nil {
+					logger.WarnCF("agent", "Failed to register MCP prompt contributor",
+						map[string]any{
+							"agent_id": agentID,
+							"server":   serverName,
+							"error":    err.Error(),
+						})
+				}
+			}
+
 			for _, tool := range conn.Tools {
 				for _, agentID := range agentIDs {
 					agent, ok := al.registry.GetAgent(agentID)

pkg/agent/agent_mcp_test.go

@@ -9,6 +9,7 @@ package agent
 import (
 	"context"
 	"errors"
+	"strings"
 	"testing"
 
 	"github.com/sipeed/picoclaw/pkg/config"
@@ -133,3 +134,48 @@ func TestServerIsDeferred(t *testing.T) {
 		})
 	}
 }
+
+func TestEnsureMCPInitialized_LoadFailureSetsInitErr(t *testing.T) {
+	al, cfg, _, _, cleanup := newTestAgentLoop(t)
+	defer cleanup()
+	defer al.Close()
+
+	cfg.Tools = config.ToolsConfig{
+		MCP: config.MCPConfig{
+			ToolConfig: config.ToolConfig{Enabled: true},
+			Servers: map[string]config.MCPServerConfig{
+				"broken": {
+					Enabled: true,
+					Command: "picoclaw-command-that-does-not-exist-for-mcp-tests",
+				},
+			},
+		},
+	}
+
+	err := al.ensureMCPInitialized(context.Background())
+	if err == nil {
+		t.Fatal("ensureMCPInitialized() error = nil, want load failure")
+	}
+	if !strings.Contains(err.Error(), "failed to load MCP servers") {
+		t.Fatalf("ensureMCPInitialized() error = %q, want wrapped load failure", err.Error())
+	}
+
+	initErr := al.mcp.getInitErr()
+	if initErr == nil {
+		t.Fatal("getInitErr() = nil, want cached load failure")
+	}
+	if !strings.Contains(initErr.Error(), "failed to load MCP servers") {
+		t.Fatalf("getInitErr() = %q, want wrapped load failure", initErr.Error())
+	}
+	if al.mcp.getManager() != nil {
+		t.Fatal("expected MCP manager to remain nil after load failure")
+	}
+
+	err = al.ensureMCPInitialized(context.Background())
+	if err == nil {
+		t.Fatal("second ensureMCPInitialized() error = nil, want cached load failure")
+	}
+	if !strings.Contains(err.Error(), "failed to load MCP servers") {
+		t.Fatalf("second ensureMCPInitialized() error = %q, want wrapped load failure", err.Error())
+	}
+}

pkg/agent/agent_media.go

@@ -11,6 +11,7 @@ import (
 	"encoding/base64"
 	"io"
 	"os"
+	"regexp"
 	"strings"
 
 	"github.com/h2non/filetype"
@@ -20,24 +21,59 @@ import (
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
+// genericPlaceholderRegex matches generic media placeholders emitted by various
+// channels: [image], [image: photo], [image: filename.jpg] — but NOT path tags
+// like [image:/path/to/file] (path tags have no space after the colon).
+var (
+	imagePlaceholderRegex = regexp.MustCompile(`\[image(:\s+[^\]]*)?\]`)
+	audioPlaceholderRegex = regexp.MustCompile(`\[audio(:\s+[^\]]*)?\]`)
+	videoPlaceholderRegex = regexp.MustCompile(`\[video(:\s+[^\]]*)?\]`)
+	filePlaceholderRegex  = regexp.MustCompile(`\[file(:\s+[^\]]*)?\]`)
+)
+
 // resolveMediaRefs resolves media:// refs in messages.
-// Images are base64-encoded into the Media array for multimodal LLMs.
-// Non-image files (documents, audio, video) have their local path injected
-// into Content so the agent can access them via file tools like read_file.
+// For user messages: images get path tags only ([image:/path]) so the LLM
+// can decide whether to view them via load_image or operate on the file.
+// For tool messages: images are base64-encoded and appended as a synthetic
+// user message only after the contiguous tool-message block ends, so we don't
+// break the tool-results-must-immediately-follow-assistant constraint that
+// LLM APIs enforce.
+// Non-image files always get path tags regardless of role.
 // Returns a new slice; original messages are not mutated.
 func resolveMediaRefs(messages []providers.Message, store media.MediaStore, maxSize int) []providers.Message {
 	if store == nil {
 		return messages
 	}
 
-	result := make([]providers.Message, len(messages))
-	copy(result, messages)
+	result := make([]providers.Message, 0, len(messages))
+	var pendingToolImages []string
+
+	for idx, m := range messages {
+		// When leaving a tool-message block, flush any accumulated images
+		// as a synthetic user message.
+		if m.Role != "tool" && len(pendingToolImages) > 0 {
+			result = append(result, providers.Message{
+				Role:    "user",
+				Content: "[Loaded image from tool result above]",
+				Media:   pendingToolImages,
+			})
+			pendingToolImages = nil
+		}
 
-	for i, m := range result {
 		if len(m.Media) == 0 {
+			result = append(result, m)
+			if idx == len(messages)-1 && len(pendingToolImages) > 0 {
+				result = append(result, providers.Message{
+					Role:    "user",
+					Content: "[Loaded image from tool result above]",
+					Media:   pendingToolImages,
+				})
+				pendingToolImages = nil
+			}
 			continue
 		}
 
+		msg := m
 		resolved := make([]string, 0, len(m.Media))
 		var pathTags []string
 
@@ -66,58 +102,36 @@ func resolveMediaRefs(messages []providers.Message, store media.MediaStore, maxS
 			}
 
 			mime := detectMIME(localPath, meta)
+			pathTags = append(pathTags, buildPathTag(mime, localPath))
 
-			if strings.HasPrefix(mime, "image/") {
+			if m.Role == "tool" && strings.HasPrefix(mime, "image/") {
 				dataURL := encodeImageToDataURL(localPath, mime, info, maxSize)
 				if dataURL != "" {
-					resolved = append(resolved, dataURL)
+					pendingToolImages = append(pendingToolImages, dataURL)
 				}
-				continue
 			}
-
-			pathTags = append(pathTags, buildPathTag(mime, localPath))
 		}
 
-		result[i].Media = resolved
+		msg.Media = resolved
 		if len(pathTags) > 0 {
-			result[i].Content = injectPathTags(result[i].Content, pathTags)
+			msg.Content = injectPathTags(msg.Content, pathTags)
+		}
+		result = append(result, msg)
+
+		// If this is the last message and we have pending images, flush them.
+		if idx == len(messages)-1 && len(pendingToolImages) > 0 {
+			result = append(result, providers.Message{
+				Role:    "user",
+				Content: "[Loaded image from tool result above]",
+				Media:   pendingToolImages,
+			})
+			pendingToolImages = nil
 		}
 	}
 
 	return result
 }
 
-func buildArtifactTags(store media.MediaStore, refs []string) []string {
-	if store == nil || len(refs) == 0 {
-		return nil
-	}
-
-	tags := make([]string, 0, len(refs))
-	for _, ref := range refs {
-		localPath, meta, err := store.ResolveWithMeta(ref)
-		if err != nil {
-			continue
-		}
-		mime := detectMIME(localPath, meta)
-		tags = append(tags, buildPathTag(mime, localPath))
-	}
-
-	return tags
-}
-
-// detectMIME determines the MIME type from metadata or magic-bytes detection.
-// Returns empty string if detection fails.
-func detectMIME(localPath string, meta media.MediaMeta) string {
-	if meta.ContentType != "" {
-		return meta.ContentType
-	}
-	kind, err := filetype.MatchFile(localPath)
-	if err != nil || kind == filetype.Unknown {
-		return ""
-	}
-	return kind.MIME.Value
-}
-
 // encodeImageToDataURL base64-encodes an image file into a data URL.
 // Returns empty string if the file exceeds maxSize or encoding fails.
 func encodeImageToDataURL(localPath, mime string, info os.FileInfo, maxSize int) string {
@@ -159,10 +173,62 @@ func encodeImageToDataURL(localPath, mime string, info os.FileInfo, maxSize int)
 	return buf.String()
 }
 
+func buildArtifactTags(store media.MediaStore, refs []string) []string {
+	if store == nil || len(refs) == 0 {
+		return nil
+	}
+
+	tags := make([]string, 0, len(refs))
+	for _, ref := range refs {
+		localPath, meta, err := store.ResolveWithMeta(ref)
+		if err != nil {
+			continue
+		}
+		mime := detectMIME(localPath, meta)
+		tags = append(tags, buildPathTag(mime, localPath))
+	}
+
+	return tags
+}
+
+func buildProviderAttachments(store media.MediaStore, refs []string) []providers.Attachment {
+	if store == nil || len(refs) == 0 {
+		return nil
+	}
+
+	attachments := make([]providers.Attachment, 0, len(refs))
+	for _, ref := range refs {
+		attachment := providers.Attachment{Ref: ref}
+		if _, meta, err := store.ResolveWithMeta(ref); err == nil {
+			attachment.Filename = meta.Filename
+			attachment.ContentType = meta.ContentType
+			attachment.Type = inferMediaType(meta.Filename, meta.ContentType)
+		}
+		attachments = append(attachments, attachment)
+	}
+
+	return attachments
+}
+
+// detectMIME determines the MIME type from metadata or magic-bytes detection.
+// Returns empty string if detection fails.
+func detectMIME(localPath string, meta media.MediaMeta) string {
+	if meta.ContentType != "" {
+		return meta.ContentType
+	}
+	kind, err := filetype.MatchFile(localPath)
+	if err != nil || kind == filetype.Unknown {
+		return ""
+	}
+	return kind.MIME.Value
+}
+
 // buildPathTag creates a structured tag exposing the local file path.
-// Tag type is derived from MIME: [audio:/path], [video:/path], or [file:/path].
+// Tag type is derived from MIME: [image:/path], [audio:/path], [video:/path], or [file:/path].
 func buildPathTag(mime, localPath string) string {
 	switch {
+	case strings.HasPrefix(mime, "image/"):
+		return "[image:" + localPath + "]"
 	case strings.HasPrefix(mime, "audio/"):
 		return "[audio:" + localPath + "]"
 	case strings.HasPrefix(mime, "video/"):
@@ -173,22 +239,41 @@ func buildPathTag(mime, localPath string) string {
 }
 
 // injectPathTags replaces generic media tags in content with path-bearing versions,
-// or appends if no matching generic tag is found.
+// or appends if no matching generic tag is found. Channels emit a few different
+// placeholder formats — [image], [image: photo], [image: filename.jpg] — so we
+// match all of them via regex while leaving path tags ([image:/path]) untouched.
+//
+// When content is structured data (e.g., JSON from Feishu interactive cards or
+// post messages), tags are only injected via placeholder replacement — never
+// appended — to avoid corrupting the payload.
 func injectPathTags(content string, tags []string) string {
+	isStructured := looksLikeJSON(content)
 	for _, tag := range tags {
-		var generic string
+		var pattern *regexp.Regexp
 		switch {
+		case strings.HasPrefix(tag, "[image:"):
+			pattern = imagePlaceholderRegex
 		case strings.HasPrefix(tag, "[audio:"):
-			generic = "[audio]"
+			pattern = audioPlaceholderRegex
 		case strings.HasPrefix(tag, "[video:"):
-			generic = "[video]"
+			pattern = videoPlaceholderRegex
 		case strings.HasPrefix(tag, "[file:"):
-			generic = "[file]"
+			pattern = filePlaceholderRegex
 		}
 
-		if generic != "" && strings.Contains(content, generic) {
-			content = strings.Replace(content, generic, tag, 1)
-		} else if content == "" {
+		if pattern != nil {
+			if loc := pattern.FindStringIndex(content); loc != nil {
+				content = content[:loc[0]] + tag + content[loc[1]:]
+				continue
+			}
+		}
+
+		if isStructured {
+			content = tag + "\n" + content
+			continue
+		}
+
+		if content == "" {
 			content = tag
 		} else {
 			content += " " + tag
@@ -196,3 +281,8 @@ func injectPathTags(content string, tags []string) string {
 	}
 	return content
 }
+
+func looksLikeJSON(s string) bool {
+	s = strings.TrimSpace(s)
+	return len(s) > 1 && s[0] == '{'
+}

pkg/agent/agent_outbound.go

@@ -4,13 +4,17 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/tools"
+	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
 func (al *AgentLoop) maybePublishError(ctx context.Context, channel, chatID, sessionKey string, err error) bool {
@@ -123,6 +127,95 @@ func (al *AgentLoop) publishPicoReasoning(ctx context.Context, reasoningContent,
 	}
 }
 
+func (al *AgentLoop) publishPicoToolCallInterim(
+	ctx context.Context,
+	ts *turnState,
+	reasoningContent string,
+	content string,
+	toolCalls []providers.ToolCall,
+) {
+	if ts == nil || ts.chatID == "" || al == nil || al.bus == nil {
+		return
+	}
+
+	if strings.TrimSpace(reasoningContent) != "" {
+		pubCtx, pubCancel := context.WithTimeout(ctx, 3*time.Second)
+		err := al.bus.PublishOutbound(
+			pubCtx,
+			outboundMessageForTurnWithKind(ts, reasoningContent, messageKindThought),
+		)
+		pubCancel()
+		if err != nil && !errors.Is(err, context.DeadlineExceeded) &&
+			!errors.Is(err, context.Canceled) &&
+			!errors.Is(err, bus.ErrBusClosed) {
+			logger.WarnCF("agent", "Failed to publish pico reasoning", map[string]any{
+				"channel": ts.channel,
+				"chat_id": ts.chatID,
+				"error":   err.Error(),
+			})
+		}
+	}
+
+	if !ts.opts.AllowInterimPicoPublish {
+		return
+	}
+
+	visibleToolCalls := utils.BuildVisibleToolCalls(
+		toolCalls,
+		al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength(),
+	)
+	duplicateToolCallContent := len(visibleToolCalls) > 0 &&
+		utils.ToolCallExplanationDuplicatesContent(content, toolCalls)
+
+	if strings.TrimSpace(content) != "" && !duplicateToolCallContent {
+		pubCtx, pubCancel := context.WithTimeout(ctx, 3*time.Second)
+		err := al.bus.PublishOutbound(pubCtx, outboundMessageForTurn(ts, content))
+		pubCancel()
+		if err != nil && !errors.Is(err, context.DeadlineExceeded) &&
+			!errors.Is(err, context.Canceled) &&
+			!errors.Is(err, bus.ErrBusClosed) {
+			logger.WarnCF("agent", "Failed to publish pico interim assistant content", map[string]any{
+				"channel": ts.channel,
+				"chat_id": ts.chatID,
+				"error":   err.Error(),
+			})
+		}
+	}
+
+	if len(visibleToolCalls) == 0 {
+		return
+	}
+
+	rawToolCalls, err := json.Marshal(visibleToolCalls)
+	if err != nil {
+		logger.WarnCF("agent", "Failed to serialize pico tool calls", map[string]any{
+			"channel": ts.channel,
+			"chat_id": ts.chatID,
+			"error":   err.Error(),
+		})
+		return
+	}
+
+	msg := outboundMessageForTurnWithKind(ts, "", messageKindToolCalls)
+	if msg.Context.Raw == nil {
+		msg.Context.Raw = map[string]string{}
+	}
+	msg.Context.Raw[metadataKeyToolCalls] = string(rawToolCalls)
+
+	pubCtx, pubCancel := context.WithTimeout(ctx, 3*time.Second)
+	err = al.bus.PublishOutbound(pubCtx, msg)
+	pubCancel()
+	if err != nil && !errors.Is(err, context.DeadlineExceeded) &&
+		!errors.Is(err, context.Canceled) &&
+		!errors.Is(err, bus.ErrBusClosed) {
+		logger.WarnCF("agent", "Failed to publish pico tool calls", map[string]any{
+			"channel": ts.channel,
+			"chat_id": ts.chatID,
+			"error":   err.Error(),
+		})
+	}
+}
+
 func (al *AgentLoop) handleReasoning(
 	ctx context.Context,
 	reasoningContent, channelName, channelID string,

pkg/agent/agent_utils.go

@@ -4,13 +4,16 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
+	"maps"
 	"path/filepath"
 	"strings"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/commands"
+	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/session"
 	"github.com/sipeed/picoclaw/pkg/utils"
@@ -84,6 +87,108 @@ func outboundMessageForTurn(ts *turnState, content string) bus.OutboundMessage {
 	}
 }
 
+func outboundMessageForTurnWithKind(ts *turnState, content, kind string) bus.OutboundMessage {
+	msg := outboundMessageForTurn(ts, content)
+	if strings.TrimSpace(kind) == "" {
+		return msg
+	}
+	if msg.Context.Raw == nil {
+		msg.Context.Raw = make(map[string]string, 1)
+	}
+	msg.Context.Raw[metadataKeyMessageKind] = kind
+	return msg
+}
+
+func latestUserContent(messages []providers.Message) string {
+	for i := len(messages) - 1; i >= 0; i-- {
+		msg := messages[i]
+		if msg.Role != "user" {
+			continue
+		}
+		if content := strings.TrimSpace(msg.Content); content != "" {
+			return content
+		}
+	}
+	return ""
+}
+
+func toolFeedbackExplanationFromResponse(
+	response *providers.LLMResponse,
+	messages []providers.Message,
+) string {
+	if response == nil {
+		return ""
+	}
+	explanation := strings.TrimSpace(response.Content)
+	if explanation == "" {
+		explanation = toolFeedbackExplanationFromToolCalls(response.ToolCalls)
+	}
+	if explanation == "" {
+		explanation = toolFeedbackExplanationFromMessages(messages)
+	}
+	return explanation
+}
+
+func toolFeedbackExplanationFromToolCalls(toolCalls []providers.ToolCall) string {
+	for _, tc := range toolCalls {
+		if tc.ExtraContent == nil {
+			continue
+		}
+		if explanation := strings.TrimSpace(tc.ExtraContent.ToolFeedbackExplanation); explanation != "" {
+			return explanation
+		}
+	}
+	return ""
+}
+
+func toolFeedbackExplanationForToolCall(
+	response *providers.LLMResponse,
+	toolCall providers.ToolCall,
+	messages []providers.Message,
+) string {
+	if toolCall.ExtraContent != nil {
+		if explanation := strings.TrimSpace(toolCall.ExtraContent.ToolFeedbackExplanation); explanation != "" {
+			return explanation
+		}
+	}
+	if response == nil {
+		return toolFeedbackExplanationFromMessages(messages)
+	}
+
+	explanation := strings.TrimSpace(response.Content)
+	if explanation == "" {
+		explanation = toolFeedbackExplanationFromMessages(messages)
+	}
+	return explanation
+}
+
+func toolFeedbackExplanationFromMessages(messages []providers.Message) string {
+	explanation := latestUserContent(messages)
+	if explanation != "" {
+		return utils.ToolFeedbackContinuationHint + ": " + explanation
+	}
+	return ""
+}
+
+func toolFeedbackArgsPreview(args map[string]any, maxLen int) string {
+	if args == nil {
+		args = map[string]any{}
+	}
+
+	argsJSON, err := json.MarshalIndent(args, "", "  ")
+	if err != nil {
+		return utils.Truncate(fmt.Sprintf("%v", args), maxLen)
+	}
+	return utils.Truncate(string(argsJSON), maxLen)
+}
+
+func shouldPublishToolFeedback(cfg *config.Config, ts *turnState) bool {
+	if ts == nil || ts.channel == "" || ts.opts.SuppressToolFeedback {
+		return false
+	}
+	return cfg != nil && cfg.Agents.Defaults.IsToolFeedbackEnabled()
+}
+
 func cloneEventArguments(args map[string]any) map[string]any {
 	if len(args) == 0 {
 		return nil
@@ -372,17 +477,28 @@ func sideQuestionResponseContent(response *providers.LLMResponse) string {
 	if response == nil {
 		return ""
 	}
-	if response.Content != "" {
+	if strings.TrimSpace(response.Content) != "" {
 		return response.Content
 	}
-	return response.ReasoningContent
+	return responseReasoningContent(response)
+}
+
+func responseReasoningContent(response *providers.LLMResponse) string {
+	if response == nil {
+		return ""
+	}
+	if strings.TrimSpace(response.Reasoning) != "" {
+		return response.Reasoning
+	}
+	if strings.TrimSpace(response.ReasoningContent) != "" {
+		return response.ReasoningContent
+	}
+	return ""
 }
 
 func shallowCloneLLMOptions(opts map[string]any) map[string]any {
 	clone := make(map[string]any, len(opts))
-	for k, v := range opts {
-		clone[k] = v
-	}
+	maps.Copy(clone, opts)
 	return clone
 }
 

pkg/agent/context.go

@@ -1,6 +1,7 @@
 package agent
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"io/fs"
@@ -21,12 +22,11 @@ import (
 )
 
 type ContextBuilder struct {
-	workspace          string
-	skillsLoader       *skills.SkillsLoader
-	memory             *MemoryStore
-	toolDiscoveryBM25  bool
-	toolDiscoveryRegex bool
-	splitOnMarker      bool
+	workspace      string
+	skillsLoader   *skills.SkillsLoader
+	memory         *MemoryStore
+	splitOnMarker  bool
+	promptRegistry *PromptRegistry
 
 	// Cache for system prompt to avoid rebuilding on every call.
 	// This fixes issue #607: repeated reprocessing of the entire context.
@@ -48,8 +48,16 @@ type ContextBuilder struct {
 }
 
 func (cb *ContextBuilder) WithToolDiscovery(useBM25, useRegex bool) *ContextBuilder {
-	cb.toolDiscoveryBM25 = useBM25
-	cb.toolDiscoveryRegex = useRegex
+	if useBM25 || useRegex {
+		if err := cb.RegisterPromptContributor(toolDiscoveryPromptContributor{
+			useBM25:  useBM25,
+			useRegex: useRegex,
+		}); err != nil {
+			logger.WarnCF("agent", "Failed to register tool discovery prompt contributor", map[string]any{
+				"error": err.Error(),
+			})
+		}
+	}
 	return cb
 }
 
@@ -73,15 +81,38 @@ func NewContextBuilder(workspace string) *ContextBuilder {
 	globalSkillsDir := filepath.Join(getGlobalConfigDir(), "skills")
 
 	return &ContextBuilder{
-		workspace:    workspace,
-		skillsLoader: skills.NewSkillsLoader(workspace, globalSkillsDir, builtinSkillsDir),
-		memory:       NewMemoryStore(workspace),
+		workspace:      workspace,
+		skillsLoader:   skills.NewSkillsLoader(workspace, globalSkillsDir, builtinSkillsDir),
+		memory:         NewMemoryStore(workspace),
+		promptRegistry: NewPromptRegistry(),
 	}
 }
 
+func (cb *ContextBuilder) RegisterPromptSource(desc PromptSourceDescriptor) error {
+	err := cb.promptRegistryOrDefault().RegisterSource(desc)
+	if err == nil {
+		cb.InvalidateCache()
+	}
+	return err
+}
+
+func (cb *ContextBuilder) RegisterPromptContributor(contributor PromptContributor) error {
+	err := cb.promptRegistryOrDefault().RegisterContributor(contributor)
+	if err == nil {
+		cb.InvalidateCache()
+	}
+	return err
+}
+
+func (cb *ContextBuilder) promptRegistryOrDefault() *PromptRegistry {
+	if cb.promptRegistry == nil {
+		cb.promptRegistry = NewPromptRegistry()
+	}
+	return cb.promptRegistry
+}
+
 func (cb *ContextBuilder) getIdentity() string {
 	workspacePath, _ := filepath.Abs(filepath.Join(cb.workspace))
-	toolDiscovery := cb.getDiscoveryRule()
 	version := config.FormatVersion()
 
 	return fmt.Sprintf(
@@ -103,22 +134,20 @@ Your workspace is at: %s
 
 3. **Memory** - When interacting with me if something seems memorable, update %s/memory/MEMORY.md
 
-4. **Context summaries** - Conversation summaries provided as context are approximate references only. They may be incomplete or outdated. Always defer to explicit user instructions over summary content.
-
-%s`,
-		version, workspacePath, workspacePath, workspacePath, workspacePath, workspacePath, toolDiscovery)
+4. **Context summaries** - Conversation summaries provided as context are approximate references only. They may be incomplete or outdated. Always defer to explicit user instructions over summary content.`,
+		version, workspacePath, workspacePath, workspacePath, workspacePath, workspacePath)
 }
 
-func (cb *ContextBuilder) getDiscoveryRule() string {
-	if !cb.toolDiscoveryBM25 && !cb.toolDiscoveryRegex {
+func formatToolDiscoveryRule(useBM25, useRegex bool) string {
+	if !useBM25 && !useRegex {
 		return ""
 	}
 
 	var toolNames []string
-	if cb.toolDiscoveryBM25 {
+	if useBM25 {
 		toolNames = append(toolNames, `"tool_search_tool_bm25"`)
 	}
-	if cb.toolDiscoveryRegex {
+	if useRegex {
 		toolNames = append(toolNames, `"tool_search_tool_regex"`)
 	}
 
@@ -129,43 +158,103 @@ func (cb *ContextBuilder) getDiscoveryRule() string {
 }
 
 func (cb *ContextBuilder) BuildSystemPrompt() string {
-	parts := []string{}
+	return renderPromptPartsLegacy(cb.BuildSystemPromptParts())
+}
+
+func (cb *ContextBuilder) BuildSystemPromptParts() []PromptPart {
+	stack := NewPromptStack(cb.promptRegistryOrDefault())
+	add := func(part PromptPart) {
+		if err := stack.Add(part); err != nil {
+			logger.WarnCF("agent", "Skipping invalid prompt part", map[string]any{
+				"id":     part.ID,
+				"layer":  part.Layer,
+				"slot":   part.Slot,
+				"source": part.Source.ID,
+				"error":  err.Error(),
+			})
+		}
+	}
 
 	// Core identity section
-	parts = append(parts, cb.getIdentity())
+	add(PromptPart{
+		ID:      "kernel.identity",
+		Layer:   PromptLayerKernel,
+		Slot:    PromptSlotIdentity,
+		Source:  PromptSource{ID: PromptSourceKernel, Name: "identity"},
+		Title:   "picoclaw identity",
+		Content: cb.getIdentity(),
+		Stable:  true,
+		Cache:   PromptCacheEphemeral,
+	})
 
 	// Bootstrap files
 	bootstrapContent := cb.LoadBootstrapFiles()
 	if bootstrapContent != "" {
-		parts = append(parts, bootstrapContent)
+		add(PromptPart{
+			ID:      "instruction.workspace",
+			Layer:   PromptLayerInstruction,
+			Slot:    PromptSlotWorkspace,
+			Source:  PromptSource{ID: PromptSourceWorkspace, Name: "workspace"},
+			Title:   "workspace instructions",
+			Content: bootstrapContent,
+			Stable:  true,
+			Cache:   PromptCacheEphemeral,
+		})
 	}
 
 	// Skills - show summary, AI can read full content with read_file tool
 	skillsSummary := cb.skillsLoader.BuildSkillsSummary()
 	if skillsSummary != "" {
-		parts = append(parts, fmt.Sprintf(`# Skills
+		add(PromptPart{
+			ID:     "capability.skill_catalog",
+			Layer:  PromptLayerCapability,
+			Slot:   PromptSlotSkillCatalog,
+			Source: PromptSource{ID: PromptSourceSkillCatalog, Name: "skill:index"},
+			Title:  "skill catalog",
+			Content: fmt.Sprintf(`# Skills
 
 The following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool.
 
-%s`, skillsSummary))
+%s`, skillsSummary),
+			Stable: true,
+			Cache:  PromptCacheEphemeral,
+		})
 	}
 
 	// Memory context
 	memoryContext := cb.memory.GetMemoryContext()
 	if memoryContext != "" {
-		parts = append(parts, "# Memory\n\n"+memoryContext)
+		add(PromptPart{
+			ID:      "context.memory",
+			Layer:   PromptLayerContext,
+			Slot:    PromptSlotMemory,
+			Source:  PromptSource{ID: PromptSourceMemory, Name: "memory:workspace"},
+			Title:   "memory",
+			Content: "# Memory\n\n" + memoryContext,
+			Stable:  true,
+			Cache:   PromptCacheEphemeral,
+		})
 	}
 
 	// Multi-Message Sending (if enabled)
 	if cb.splitOnMarker {
-		parts = append(parts, `# MULTI-MESSAGE OUTPUT
+		add(PromptPart{
+			ID:     "context.output_policy.split_on_marker",
+			Layer:  PromptLayerContext,
+			Slot:   PromptSlotOutput,
+			Source: PromptSource{ID: PromptSourceOutputPolicy, Name: "split_on_marker"},
+			Title:  "multi-message output policy",
+			Content: `# MULTI-MESSAGE OUTPUT
 You MUST frequently use <|[SPLIT]|> to break your responses into multiple short messages. NEVER output a single long wall of text. Actively split distinct concepts or parts. Example: Message part 1<|[SPLIT]|>Message part 2<|[SPLIT]|>Message part 3
 
-Each part separated by the marker will be sent as an independent message.`)
+Each part separated by the marker will be sent as an independent message.`,
+			Stable: true,
+			Cache:  PromptCacheEphemeral,
+		})
 	}
 
-	// Join with "---" separator
-	return strings.Join(parts, "\n\n---\n\n")
+	stack.Seal()
+	return stack.Parts()
 }
 
 // BuildSystemPromptWithCache returns the cached system prompt if available
@@ -230,6 +319,19 @@ func (cb *ContextBuilder) EstimateSystemTokens(summary string, activeSkills []st
 		totalChars += 7 // separator \n\n---\n\n
 	}
 
+	if contributedParts, err := cb.promptRegistryOrDefault().Collect(context.Background(), PromptBuildRequest{
+		Summary:      summary,
+		ActiveSkills: append([]string(nil), activeSkills...),
+	}); err == nil {
+		for _, part := range contributedParts {
+			if strings.TrimSpace(part.Content) == "" {
+				continue
+			}
+			totalChars += utf8.RuneCountInString(part.Content)
+			totalChars += 7 // separator
+		}
+	}
+
 	if summary != "" {
 		// Matches the CONTEXT_SUMMARY: prefix added in BuildMessages
 		const summaryPrefix = "CONTEXT_SUMMARY: The following is an approximate summary of prior conversation " +
@@ -548,6 +650,20 @@ func (cb *ContextBuilder) BuildMessages(
 	channel, chatID, senderID, senderDisplayName string,
 	activeSkills ...string,
 ) []providers.Message {
+	return cb.BuildMessagesFromPrompt(PromptBuildRequest{
+		History:           history,
+		Summary:           summary,
+		CurrentMessage:    currentMessage,
+		Media:             media,
+		Channel:           channel,
+		ChatID:            chatID,
+		SenderID:          senderID,
+		SenderDisplayName: senderDisplayName,
+		ActiveSkills:      append([]string(nil), activeSkills...),
+	})
+}
+
+func (cb *ContextBuilder) BuildMessagesFromPrompt(req PromptBuildRequest) []providers.Message {
 	messages := []providers.Message{}
 
 	// The static part (identity, bootstrap, skills, memory) is cached locally to
@@ -562,7 +678,7 @@ func (cb *ContextBuilder) BuildMessages(
 	staticPrompt := cb.BuildSystemPromptWithCache()
 
 	// Build short dynamic context (time, runtime, session) — changes per request
-	dynamicCtx := cb.buildDynamicContext(channel, chatID, senderID, senderDisplayName)
+	dynamicCtx := cb.buildDynamicContext(req.Channel, req.ChatID, req.SenderID, req.SenderDisplayName)
 
 	// Compose a single system message: static (cached) + dynamic + optional summary.
 	// Keeping all system content in one message ensures every provider adapter can
@@ -573,25 +689,77 @@ func (cb *ContextBuilder) BuildMessages(
 	// cache-aware adapters (Anthropic) can set per-block cache_control.
 	// The static block is marked "ephemeral" — its prefix hash is stable
 	// across requests, enabling LLM-side KV cache reuse.
-	stringParts := []string{staticPrompt, dynamicCtx}
+	stringParts := []string{staticPrompt}
 
 	contentBlocks := []providers.ContentBlock{
-		{Type: "text", Text: staticPrompt, CacheControl: &providers.CacheControl{Type: "ephemeral"}},
-		{Type: "text", Text: dynamicCtx},
+		promptContentBlock(PromptPart{
+			ID:      "kernel.static",
+			Layer:   PromptLayerKernel,
+			Slot:    PromptSlotIdentity,
+			Source:  PromptSource{ID: PromptSourceKernel, Name: "static"},
+			Content: staticPrompt,
+		}, &providers.CacheControl{Type: "ephemeral"}),
 	}
 
-	if skillsText := cb.buildActiveSkillsContext(activeSkills); skillsText != "" {
-		stringParts = append(stringParts, skillsText)
-		contentBlocks = append(contentBlocks, providers.ContentBlock{Type: "text", Text: skillsText})
+	promptParts := append([]PromptPart(nil), req.Overlays...)
+	promptParts = append(promptParts, cb.buildActiveSkillsPromptParts(req.ActiveSkills)...)
+	if contributedParts, err := cb.promptRegistryOrDefault().Collect(context.Background(), req); err != nil {
+		logger.WarnCF("agent", "Prompt contributor collection failed", map[string]any{
+			"error": err.Error(),
+		})
+	} else {
+		promptParts = append(promptParts, contributedParts...)
 	}
 
-	if summary != "" {
-		summaryText := fmt.Sprintf(
-			"CONTEXT_SUMMARY: The following is an approximate summary of prior conversation "+
-				"for reference only. It may be incomplete or outdated — always defer to explicit instructions.\n\n%s",
-			summary)
-		stringParts = append(stringParts, summaryText)
-		contentBlocks = append(contentBlocks, providers.ContentBlock{Type: "text", Text: summaryText})
+	if len(promptParts) > 0 {
+		for _, overlay := range sortPromptParts(promptParts) {
+			if strings.TrimSpace(overlay.Content) == "" {
+				continue
+			}
+			if err := cb.promptRegistryOrDefault().ValidatePart(overlay); err != nil {
+				logger.WarnCF("agent", "Skipping invalid prompt overlay", map[string]any{
+					"id":     overlay.ID,
+					"layer":  overlay.Layer,
+					"slot":   overlay.Slot,
+					"source": overlay.Source.ID,
+					"error":  err.Error(),
+				})
+				continue
+			}
+			stringParts = append(stringParts, overlay.Content)
+			contentBlocks = append(contentBlocks, promptContentBlock(overlay, nil))
+		}
+	}
+
+	runtimePart := PromptPart{
+		ID:      "context.runtime",
+		Layer:   PromptLayerContext,
+		Slot:    PromptSlotRuntime,
+		Source:  PromptSource{ID: PromptSourceRuntime, Name: "runtime"},
+		Title:   "runtime context",
+		Content: dynamicCtx,
+		Stable:  false,
+		Cache:   PromptCacheNone,
+	}
+	stringParts = append(stringParts, dynamicCtx)
+	contentBlocks = append(contentBlocks, promptContentBlock(runtimePart, nil))
+
+	if req.Summary != "" {
+		summaryPart := PromptPart{
+			ID:     "context.summary",
+			Layer:  PromptLayerContext,
+			Slot:   PromptSlotSummary,
+			Source: PromptSource{ID: PromptSourceSummary, Name: "context.summary"},
+			Title:  "context summary",
+			Content: fmt.Sprintf(
+				"CONTEXT_SUMMARY: The following is an approximate summary of prior conversation "+
+					"for reference only. It may be incomplete or outdated — always defer to explicit instructions.\n\n%s",
+				req.Summary),
+			Stable: false,
+			Cache:  PromptCacheNone,
+		}
+		stringParts = append(stringParts, summaryPart.Content)
+		contentBlocks = append(contentBlocks, promptContentBlock(summaryPart, nil))
 	}
 
 	fullSystemPrompt := strings.Join(stringParts, "\n\n---\n\n")
@@ -608,7 +776,8 @@ func (cb *ContextBuilder) BuildMessages(
 			"static_chars":  len(staticPrompt),
 			"dynamic_chars": len(dynamicCtx),
 			"total_chars":   len(fullSystemPrompt),
-			"has_summary":   summary != "",
+			"has_summary":   req.Summary != "",
+			"overlays":      len(req.Overlays),
 			"cached":        isCached,
 		})
 
@@ -619,7 +788,7 @@ func (cb *ContextBuilder) BuildMessages(
 			"preview": preview,
 		})
 
-	history = sanitizeHistoryForProvider(history)
+	history := sanitizeHistoryForProvider(req.History)
 
 	// Single system message containing all context — compatible with all providers.
 	// SystemParts enables cache-aware adapters to set per-block cache_control;
@@ -636,15 +805,8 @@ func (cb *ContextBuilder) BuildMessages(
 	// Add current user message. Media-only turns must still be preserved so
 	// multimodal providers receive the uploaded image even when the user sends
 	// no accompanying text.
-	if strings.TrimSpace(currentMessage) != "" || len(media) > 0 {
-		msg := providers.Message{
-			Role:    "user",
-			Content: currentMessage,
-		}
-		if len(media) > 0 {
-			msg.Media = append([]string(nil), media...)
-		}
-		messages = append(messages, msg)
+	if strings.TrimSpace(req.CurrentMessage) != "" || len(req.Media) > 0 {
+		messages = append(messages, userPromptMessage(req.CurrentMessage, req.Media))
 	}
 
 	return messages
@@ -870,6 +1032,26 @@ The following skills are active for this request. Follow them when relevant.
 %s`, content)
 }
 
+func (cb *ContextBuilder) buildActiveSkillsPromptParts(skillNames []string) []PromptPart {
+	skillsText := cb.buildActiveSkillsContext(skillNames)
+	if strings.TrimSpace(skillsText) == "" {
+		return nil
+	}
+
+	return []PromptPart{
+		{
+			ID:      "capability.active_skills",
+			Layer:   PromptLayerCapability,
+			Slot:    PromptSlotActiveSkill,
+			Source:  PromptSource{ID: PromptSourceActiveSkills, Name: "skill:active"},
+			Title:   "active skills",
+			Content: skillsText,
+			Stable:  false,
+			Cache:   PromptCacheNone,
+		},
+	}
+}
+
 func (cb *ContextBuilder) ListSkillNames() []string {
 	if cb.skillsLoader == nil {
 		return nil

pkg/agent/hooks.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"reflect"
 	"sort"
 	"sync"
 	"time"
@@ -325,6 +326,7 @@ func (hm *HookManager) BeforeLLM(ctx context.Context, req *LLMHookRequest) (*LLM
 		switch decision.normalizedAction() {
 		case HookActionContinue, HookActionModify:
 			if next != nil {
+				next = hm.applyBeforeLLMControls(reg.Name, current, next)
 				current = next
 			}
 		case HookActionAbortTurn, HookActionHardAbort:
@@ -367,6 +369,84 @@ func (hm *HookManager) AfterLLM(ctx context.Context, resp *LLMHookResponse) (*LL
 	return current, HookDecision{Action: HookActionContinue}
 }
 
+func (hm *HookManager) applyBeforeLLMControls(
+	hookName string,
+	current *LLMHookRequest,
+	next *LLMHookRequest,
+) *LLMHookRequest {
+	if next == nil || current == nil {
+		return next
+	}
+	if !llmHookSystemMessagesUnchanged(current.Messages, next.Messages) {
+		logger.WarnCF("hooks", "Hook attempted to modify system prompt; preserving original messages", map[string]any{
+			"hook": hookName,
+		})
+		next.Messages = cloneProviderMessages(current.Messages)
+	}
+	if !llmHookToolDefinitionsUnchanged(current.Tools, next.Tools) {
+		logger.WarnCF("hooks", "Hook attempted to modify tool definitions; preserving original tools", map[string]any{
+			"hook": hookName,
+		})
+		next.Tools = cloneToolDefinitions(current.Tools)
+	}
+	return next
+}
+
+func llmHookSystemMessagesUnchanged(before, after []providers.Message) bool {
+	beforeSystem := systemMessageFingerprints(before)
+	afterSystem := systemMessageFingerprints(after)
+	return reflect.DeepEqual(beforeSystem, afterSystem)
+}
+
+type systemMessageFingerprint struct {
+	Index   int
+	Message providers.Message
+}
+
+func systemMessageFingerprints(messages []providers.Message) []systemMessageFingerprint {
+	var fingerprints []systemMessageFingerprint
+	for i, msg := range messages {
+		if msg.Role != "system" {
+			continue
+		}
+		msg = providerVisibleMessage(msg)
+		fingerprints = append(fingerprints, systemMessageFingerprint{
+			Index:   i,
+			Message: cloneProviderMessages([]providers.Message{msg})[0],
+		})
+	}
+	return fingerprints
+}
+
+func llmHookToolDefinitionsUnchanged(before, after []providers.ToolDefinition) bool {
+	return reflect.DeepEqual(providerVisibleToolDefinitions(before), providerVisibleToolDefinitions(after))
+}
+
+func providerVisibleMessage(msg providers.Message) providers.Message {
+	msg.PromptLayer = ""
+	msg.PromptSlot = ""
+	msg.PromptSource = ""
+	if len(msg.SystemParts) > 0 {
+		msg.SystemParts = append([]providers.ContentBlock(nil), msg.SystemParts...)
+		for i := range msg.SystemParts {
+			msg.SystemParts[i].PromptLayer = ""
+			msg.SystemParts[i].PromptSlot = ""
+			msg.SystemParts[i].PromptSource = ""
+		}
+	}
+	return msg
+}
+
+func providerVisibleToolDefinitions(defs []providers.ToolDefinition) []providers.ToolDefinition {
+	cloned := cloneToolDefinitions(defs)
+	for i := range cloned {
+		cloned[i].PromptLayer = ""
+		cloned[i].PromptSlot = ""
+		cloned[i].PromptSource = ""
+	}
+	return cloned
+}
+
 func (hm *HookManager) BeforeTool(
 	ctx context.Context,
 	call *ToolCallHookRequest,
@@ -788,7 +868,7 @@ func cloneLLMResponse(resp *providers.LLMResponse) *providers.LLMResponse {
 
 func cloneStringAnyMap(src map[string]any) map[string]any {
 	if len(src) == 0 {
-		return nil
+		return map[string]any{}
 	}
 
 	cloned := make(map[string]any, len(src))

pkg/agent/hooks_test.go

@@ -2,8 +2,10 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"os"
+	"strings"
 	"sync"
 	"testing"
 	"time"
@@ -148,6 +150,268 @@ func (h *llmObserverHook) AfterLLM(
 	return next, HookDecision{Action: HookActionModify}, nil
 }
 
+type llmSystemRewriteHook struct{}
+
+func (h *llmSystemRewriteHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	next := req.Clone()
+	next.Model = "changed-model"
+	next.Messages[0].Content = "rewritten system"
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *llmSystemRewriteHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	return resp.Clone(), HookDecision{Action: HookActionContinue}, nil
+}
+
+type llmUserAppendHook struct{}
+
+func (h *llmUserAppendHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	next := req.Clone()
+	next.Messages = append(next.Messages, providers.Message{Role: "user", Content: "extra user context"})
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *llmUserAppendHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	return resp.Clone(), HookDecision{Action: HookActionContinue}, nil
+}
+
+type llmJSONRoundTripUserAppendHook struct{}
+
+type jsonRoundTripLLMHookRequest struct {
+	Model    string                     `json:"model"`
+	Messages []providers.Message        `json:"messages,omitempty"`
+	Tools    []providers.ToolDefinition `json:"tools,omitempty"`
+}
+
+func (h *llmJSONRoundTripUserAppendHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	payload := jsonRoundTripLLMHookRequest{
+		Model:    req.Model,
+		Messages: req.Messages,
+		Tools:    req.Tools,
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return nil, HookDecision{}, err
+	}
+	var decoded jsonRoundTripLLMHookRequest
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		return nil, HookDecision{}, err
+	}
+	next := req.Clone()
+	next.Model = decoded.Model
+	next.Messages = decoded.Messages
+	next.Tools = decoded.Tools
+	next.Messages = append(next.Messages, providers.Message{Role: "user", Content: "json extra user context"})
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *llmJSONRoundTripUserAppendHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	return resp.Clone(), HookDecision{Action: HookActionContinue}, nil
+}
+
+type llmToolRewriteHook struct{}
+
+func (h *llmToolRewriteHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	next := req.Clone()
+	next.Model = "changed-model"
+	next.Tools[0].Function.Description = "rewritten tool"
+	next.Tools = append(next.Tools, providers.ToolDefinition{
+		Type: "function",
+		Function: providers.ToolFunctionDefinition{
+			Name:        "hook_tool",
+			Description: "hook tool",
+			Parameters:  map[string]any{"type": "object"},
+		},
+		PromptLayer:  string(PromptLayerCapability),
+		PromptSlot:   string(PromptSlotTooling),
+		PromptSource: "hook:test",
+	})
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *llmToolRewriteHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	return resp.Clone(), HookDecision{Action: HookActionContinue}, nil
+}
+
+func TestHookManager_BeforeLLMControlsSystemPromptMutation(t *testing.T) {
+	hm := NewHookManager(nil)
+	if err := hm.Mount(NamedHook("rewrite-system", &llmSystemRewriteHook{})); err != nil {
+		t.Fatalf("Mount() error = %v", err)
+	}
+
+	req := &LLMHookRequest{
+		Model: "original-model",
+		Messages: []providers.Message{
+			{
+				Role:    "system",
+				Content: "original system",
+				SystemParts: []providers.ContentBlock{
+					{Type: "text", Text: "original system"},
+				},
+			},
+			{Role: "user", Content: "hello"},
+		},
+	}
+
+	got, decision := hm.BeforeLLM(context.Background(), req)
+	if decision.normalizedAction() != HookActionContinue {
+		t.Fatalf("decision = %v, want continue", decision)
+	}
+	if got.Model != "changed-model" {
+		t.Fatalf("model = %q, want changed-model", got.Model)
+	}
+	if got.Messages[0].Content != "original system" {
+		t.Fatalf("system content = %q, want original system", got.Messages[0].Content)
+	}
+	if got.Messages[1].Content != "hello" {
+		t.Fatalf("user content = %q, want hello", got.Messages[1].Content)
+	}
+}
+
+func TestHookManager_BeforeLLMAllowsNonSystemMessageMutation(t *testing.T) {
+	hm := NewHookManager(nil)
+	if err := hm.Mount(NamedHook("append-user", &llmUserAppendHook{})); err != nil {
+		t.Fatalf("Mount() error = %v", err)
+	}
+
+	req := &LLMHookRequest{
+		Model: "model",
+		Messages: []providers.Message{
+			{Role: "system", Content: "system"},
+			{Role: "user", Content: "hello"},
+		},
+	}
+
+	got, _ := hm.BeforeLLM(context.Background(), req)
+	if len(got.Messages) != 3 {
+		t.Fatalf("messages len = %d, want 3", len(got.Messages))
+	}
+	if got.Messages[2].Role != "user" || got.Messages[2].Content != "extra user context" {
+		t.Fatalf("appended message = %#v, want extra user context", got.Messages[2])
+	}
+}
+
+func TestHookManager_BeforeLLMAllowsJSONRoundTripNonSystemMessageMutation(t *testing.T) {
+	hm := NewHookManager(nil)
+	if err := hm.Mount(NamedHook("json-append-user", &llmJSONRoundTripUserAppendHook{})); err != nil {
+		t.Fatalf("Mount() error = %v", err)
+	}
+
+	req := &LLMHookRequest{
+		Model: "model",
+		Messages: []providers.Message{
+			{
+				Role:         "system",
+				Content:      "system",
+				PromptLayer:  string(PromptLayerKernel),
+				PromptSlot:   string(PromptSlotIdentity),
+				PromptSource: string(PromptSourceKernel),
+				SystemParts: []providers.ContentBlock{
+					{
+						Type:         "text",
+						Text:         "system",
+						CacheControl: &providers.CacheControl{Type: "ephemeral"},
+						PromptLayer:  string(PromptLayerKernel),
+						PromptSlot:   string(PromptSlotIdentity),
+						PromptSource: string(PromptSourceKernel),
+					},
+				},
+			},
+			{Role: "user", Content: "hello"},
+		},
+		Tools: []providers.ToolDefinition{
+			{
+				Type: "function",
+				Function: providers.ToolFunctionDefinition{
+					Name:        "mcp_github_create_issue",
+					Description: "create issue",
+					Parameters:  map[string]any{"type": "object"},
+				},
+				PromptLayer:  string(PromptLayerCapability),
+				PromptSlot:   string(PromptSlotMCP),
+				PromptSource: "mcp:github",
+			},
+		},
+	}
+
+	got, _ := hm.BeforeLLM(context.Background(), req)
+	if len(got.Messages) != 3 {
+		t.Fatalf("messages len = %d, want 3", len(got.Messages))
+	}
+	if got.Messages[2].Role != "user" || got.Messages[2].Content != "json extra user context" {
+		t.Fatalf("appended message = %#v, want json extra user context", got.Messages[2])
+	}
+}
+
+func TestHookManager_BeforeLLMControlsToolDefinitionMutation(t *testing.T) {
+	hm := NewHookManager(nil)
+	if err := hm.Mount(NamedHook("rewrite-tool", &llmToolRewriteHook{})); err != nil {
+		t.Fatalf("Mount() error = %v", err)
+	}
+
+	req := &LLMHookRequest{
+		Model: "original-model",
+		Messages: []providers.Message{
+			{Role: "system", Content: "system"},
+			{Role: "user", Content: "hello"},
+		},
+		Tools: []providers.ToolDefinition{
+			{
+				Type: "function",
+				Function: providers.ToolFunctionDefinition{
+					Name:        "mcp_github_create_issue",
+					Description: "create issue",
+					Parameters:  map[string]any{"type": "object"},
+				},
+				PromptLayer:  string(PromptLayerCapability),
+				PromptSlot:   string(PromptSlotMCP),
+				PromptSource: "mcp:github",
+			},
+		},
+	}
+
+	got, decision := hm.BeforeLLM(context.Background(), req)
+	if decision.normalizedAction() != HookActionContinue {
+		t.Fatalf("decision = %v, want continue", decision)
+	}
+	if got.Model != "changed-model" {
+		t.Fatalf("model = %q, want changed-model", got.Model)
+	}
+	if len(got.Tools) != 1 {
+		t.Fatalf("tools len = %d, want original 1", len(got.Tools))
+	}
+	if got.Tools[0].Function.Description != "create issue" {
+		t.Fatalf("tool description = %q, want original", got.Tools[0].Function.Description)
+	}
+	if got.Tools[0].PromptSource != "mcp:github" || got.Tools[0].PromptSlot != string(PromptSlotMCP) {
+		t.Fatalf("tool prompt metadata = %#v, want original mcp metadata", got.Tools[0])
+	}
+}
+
 func TestAgentLoop_Hooks_ObserverAndLLMInterceptor(t *testing.T) {
 	provider := &llmHookTestProvider{}
 	al, agent, cleanup := newHookTestLoop(t, provider)
@@ -403,6 +667,24 @@ func (h *toolRewriteHook) AfterTool(
 	return next, HookDecision{Action: HookActionModify}, nil
 }
 
+type toolRenameHook struct{}
+
+func (h *toolRenameHook) BeforeTool(
+	ctx context.Context,
+	call *ToolCallHookRequest,
+) (*ToolCallHookRequest, HookDecision, error) {
+	next := call.Clone()
+	next.Tool = "echo_text_rewritten"
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *toolRenameHook) AfterTool(
+	ctx context.Context,
+	result *ToolResultHookResponse,
+) (*ToolResultHookResponse, HookDecision, error) {
+	return result.Clone(), HookDecision{Action: HookActionContinue}, nil
+}
+
 func TestAgentLoop_Hooks_ToolInterceptorCanRewrite(t *testing.T) {
 	provider := &toolHookProvider{}
 	al, agent, cleanup := newHookTestLoop(t, provider)
@@ -430,6 +712,75 @@ func TestAgentLoop_Hooks_ToolInterceptorCanRewrite(t *testing.T) {
 	}
 }
 
+type echoTextRewrittenTool struct{}
+
+func (t *echoTextRewrittenTool) Name() string {
+	return "echo_text_rewritten"
+}
+
+func (t *echoTextRewrittenTool) Description() string {
+	return "echo a rewritten text argument"
+}
+
+func (t *echoTextRewrittenTool) Parameters() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"text": map[string]any{
+				"type": "string",
+			},
+		},
+	}
+}
+
+func (t *echoTextRewrittenTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+	text, _ := args["text"].(string)
+	return tools.SilentResult("rewritten:" + text)
+}
+
+func TestAgentLoop_Hooks_ToolFeedbackUsesRewrittenToolName(t *testing.T) {
+	provider := &toolHookProvider{}
+	al, agent, cleanup := newHookTestLoop(t, provider)
+	defer cleanup()
+
+	al.cfg.Agents.Defaults.ToolFeedback.Enabled = true
+	al.RegisterTool(&echoTextTool{})
+	al.RegisterTool(&echoTextRewrittenTool{})
+	if err := al.MountHook(NamedHook("tool-rename", &toolRenameHook{})); err != nil {
+		t.Fatalf("MountHook failed: %v", err)
+	}
+
+	_, err := al.runAgentLoop(context.Background(), agent, processOptions{
+		SessionKey:      "session-1",
+		Channel:         "cli",
+		ChatID:          "direct",
+		UserMessage:     "run tool",
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+
+	msgBus, ok := al.bus.(*bus.MessageBus)
+	if !ok {
+		t.Fatalf("expected concrete MessageBus, got %T", al.bus)
+	}
+
+	select {
+	case outbound := <-msgBus.OutboundChan():
+		if !strings.Contains(outbound.Content, "`echo_text_rewritten`") {
+			t.Fatalf("tool feedback content = %q, want rewritten tool name", outbound.Content)
+		}
+		if strings.Contains(outbound.Content, "`echo_text`") {
+			t.Fatalf("tool feedback content = %q, want no original tool name", outbound.Content)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("expected outbound tool feedback")
+	}
+}
+
 type denyApprovalHook struct{}
 
 func (h *denyApprovalHook) ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error) {
@@ -804,6 +1155,77 @@ func TestAgentLoop_HookRespond_BusFallback(t *testing.T) {
 	}
 }
 
+func TestAgentLoop_HookRespond_ResponseHandledMediaPreservesOutboundContext(t *testing.T) {
+	provider := &multiToolProvider{
+		toolCalls: []providers.ToolCall{
+			{ID: "call-1", Name: "media_tool", Arguments: map[string]any{}},
+		},
+		finalContent: "done",
+	}
+	al, agent, cleanup := newHookTestLoop(t, provider)
+	defer cleanup()
+
+	hook := &respondWithMediaHook{
+		respondTools:    map[string]bool{"media_tool": true},
+		media:           []string{"media://test/image.png"},
+		responseHandled: true,
+		forLLM:          "media sent successfully",
+	}
+	if err := al.MountHook(NamedHook("media-hook", hook)); err != nil {
+		t.Fatalf("MountHook failed: %v", err)
+	}
+
+	telegramChannel := &fakeMediaChannel{fakeChannel: fakeChannel{id: "rid-telegram"}}
+	al.channelManager = newStartedTestChannelManager(t,
+		al.bus.(*bus.MessageBus), al.mediaStore, "telegram", telegramChannel)
+
+	_, err := al.runAgentLoop(context.Background(), agent, processOptions{
+		Dispatch: DispatchRequest{
+			SessionKey: "session-topic-media",
+			SessionScope: &session.SessionScope{
+				Version:    session.ScopeVersionV1,
+				AgentID:    agent.ID,
+				Channel:    "telegram",
+				Dimensions: []string{"chat"},
+				Values: map[string]string{
+					"chat": "forum:-100123/42",
+				},
+			},
+			InboundContext: &bus.InboundContext{
+				Channel:  "telegram",
+				ChatID:   "-100123",
+				TopicID:  "42",
+				ChatType: "group",
+				SenderID: "user1",
+			},
+			UserMessage: "send media",
+		},
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+
+	if len(telegramChannel.sentMedia) != 1 {
+		t.Fatalf("expected exactly 1 sent media message, got %d", len(telegramChannel.sentMedia))
+	}
+	sent := telegramChannel.sentMedia[0]
+	if sent.Context.Channel != "telegram" || sent.Context.ChatID != "-100123" || sent.Context.TopicID != "42" {
+		t.Fatalf("unexpected media context: %+v", sent.Context)
+	}
+	if sent.AgentID != agent.ID {
+		t.Fatalf("sent media agent_id = %q, want %q", sent.AgentID, agent.ID)
+	}
+	if sent.SessionKey != "session-topic-media" {
+		t.Fatalf("sent media session_key = %q, want session-topic-media", sent.SessionKey)
+	}
+	if sent.Scope == nil || sent.Scope.Values["chat"] != "forum:-100123/42" {
+		t.Fatalf("unexpected sent media scope: %+v", sent.Scope)
+	}
+}
+
 type multiToolProvider struct {
 	mu           sync.Mutex
 	callCount    int
@@ -881,7 +1303,11 @@ func TestAgentLoop_HookRespond_InterruptSkipsRemaining(t *testing.T) {
 		resultCh <- result{resp: resp, err: err}
 	}()
 
-	time.Sleep(50 * time.Millisecond)
+	select {
+	case <-tool1ExecCh:
+	case <-time.After(3 * time.Second):
+		t.Fatal("timeout waiting for tool execution to start")
+	}
 
 	if err := al.InterruptGraceful("stop now"); err != nil {
 		t.Fatalf("InterruptGraceful failed: %v", err)
@@ -1005,6 +1431,56 @@ func TestAgentLoop_HookRespond_SteeringSkipsRemaining(t *testing.T) {
 	}
 }
 
+func TestCloneStringAnyMap_EmptyMapReturnsNonNil(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   map[string]any
+		wantNil bool
+		wantLen int
+	}{
+		{
+			name:    "nil input returns empty map",
+			input:   nil,
+			wantNil: false,
+			wantLen: 0,
+		},
+		{
+			name:    "empty map returns empty map",
+			input:   map[string]any{},
+			wantNil: false,
+			wantLen: 0,
+		},
+		{
+			name:    "populated map is cloned",
+			input:   map[string]any{"key": "value"},
+			wantNil: false,
+			wantLen: 1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := cloneStringAnyMap(tt.input)
+			if result == nil {
+				t.Fatal("cloneStringAnyMap returned nil — MCP tool calls " +
+					"with no arguments would send null instead of {}")
+			}
+			if len(result) != tt.wantLen {
+				t.Fatalf("expected len %d, got %d", tt.wantLen, len(result))
+			}
+		})
+	}
+
+	t.Run("clone does not share underlying map", func(t *testing.T) {
+		src := map[string]any{"a": 1}
+		cloned := cloneStringAnyMap(src)
+		cloned["b"] = 2
+		if _, ok := src["b"]; ok {
+			t.Fatal("modifying clone should not affect source")
+		}
+	})
+}
+
 func filterEvents(events []Event, kind EventKind) []Event {
 	var result []Event
 	for _, evt := range events {

pkg/agent/instance.go

@@ -270,8 +270,8 @@ func populateCandidateProvidersFromNames(
 				map[string]any{"name": name, "error": err.Error()})
 			continue
 		}
-		protocol, modelID := providers.ExtractProtocol(strings.TrimSpace(mc.Model))
-		key := providers.ModelKey(providers.NormalizeProvider(protocol), modelID)
+		protocol, modelID := providers.ExtractProtocol(mc)
+		key := providers.ModelKey(protocol, modelID)
 		if _, exists := out[key]; exists {
 			continue
 		}

pkg/agent/instance_test.go

@@ -104,6 +104,7 @@ func TestNewAgentInstance_ResolveCandidatesFromModelListAlias(t *testing.T) {
 		name         string
 		aliasName    string
 		modelName    string
+		provider     string
 		apiBase      string
 		wantProvider string
 		wantModel    string
@@ -124,6 +125,15 @@ func TestNewAgentInstance_ResolveCandidatesFromModelListAlias(t *testing.T) {
 			wantProvider: "openai",
 			wantModel:    "glm-5",
 		},
+		{
+			name:         "explicit provider overrides model prefix",
+			aliasName:    "nvidia-gpt",
+			modelName:    "z-ai/glm-5.1",
+			provider:     "nvidia",
+			apiBase:      "https://integrate.api.nvidia.com/v1",
+			wantProvider: "nvidia",
+			wantModel:    "z-ai/glm-5.1",
+		},
 	}
 
 	for _, tt := range tests {
@@ -145,6 +155,7 @@ func TestNewAgentInstance_ResolveCandidatesFromModelListAlias(t *testing.T) {
 					{
 						ModelName: tt.aliasName,
 						Model:     tt.modelName,
+						Provider:  tt.provider,
 						APIBase:   tt.apiBase,
 					},
 				},
@@ -218,6 +229,43 @@ func TestNewAgentInstance_PreservesDistinctLimiterIdentityForSharedResolvedModel
 	}
 }
 
+func TestNewAgentInstance_PreservesConfigIdentityForExplicitProviderModelRef(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace: tmpDir,
+				ModelName: "nvidia/z-ai/glm-5.1",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{
+				ModelName: "nvidia-glm",
+				Provider:  "nvidia",
+				Model:     "z-ai/glm-5.1",
+				RPM:       7,
+			},
+		},
+	}
+
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{})
+	if len(agent.Candidates) != 1 {
+		t.Fatalf("len(Candidates) = %d, want 1", len(agent.Candidates))
+	}
+
+	candidate := agent.Candidates[0]
+	if candidate.Provider != "nvidia" || candidate.Model != "z-ai/glm-5.1" {
+		t.Fatalf("candidate = %s/%s, want nvidia/z-ai/glm-5.1", candidate.Provider, candidate.Model)
+	}
+	if candidate.IdentityKey != "model_name:nvidia-glm" {
+		t.Fatalf("identity key = %q, want %q", candidate.IdentityKey, "model_name:nvidia-glm")
+	}
+	if candidate.RPM != 7 {
+		t.Fatalf("RPM = %d, want 7", candidate.RPM)
+	}
+}
+
 func TestNewAgentInstance_AllowsMediaTempDirForReadListAndExec(t *testing.T) {
 	workspace := t.TempDir()
 	mediaDir := media.TempDir()