From fd0845df0eb5eff0c7efddb1bd1d60ff2ac76a37 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9B=BE=E6=96=87=E9=94=8B0668000834?=
 <zeng.wenfeng@xydigit.com>
Date: Tue, 7 Apr 2026 14:42:58 +0800
Subject: [PATCH] fix(gateway): add stop subcommand to gracefully shutdown
 gateway (fixes #2373)

- Add 'picoclaw gateway stop' command to stop running gateway
- Read PID file and send SIGTERM (Unix) or Kill (Windows) to process
- Cross-platform implementation with build tags
---
 cmd/picoclaw/internal/gateway/command.go      | 39 +++++++++++++++++++
 cmd/picoclaw/internal/gateway/stop_unix.go    | 13 +++++++
 cmd/picoclaw/internal/gateway/stop_windows.go | 12 ++++++
 3 files changed, 64 insertions(+)
 create mode 100644 cmd/picoclaw/internal/gateway/stop_unix.go
 create mode 100644 cmd/picoclaw/internal/gateway/stop_windows.go

diff --git a/cmd/picoclaw/internal/gateway/command.go b/cmd/picoclaw/internal/gateway/command.go
index 7fa588c5c..abc17a2ae 100644
--- a/cmd/picoclaw/internal/gateway/command.go
+++ b/cmd/picoclaw/internal/gateway/command.go
@@ -2,12 +2,14 @@ package gateway
 
 import (
 	"fmt"
+	"os"
 
 	"github.com/spf13/cobra"
 
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/gateway"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/pid"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
@@ -48,5 +50,42 @@ func NewGatewayCommand() *cobra.Command {
 		"Continue starting even when no default model is configured",
 	)
 
+	// Add stop subcommand
+	cmd.AddCommand(newGatewayStopCommand())
+
 	return cmd
 }
+
+func newGatewayStopCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "stop",
+		Short: "Stop the running picoclaw gateway",
+		Long:  "Stop the running picoclaw gateway by reading its PID file and sending a termination signal.",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			homePath := internal.GetPicoclawHome()
+
+			// Read PID file and check if process is running
+			data := pid.ReadPidFileWithCheck(homePath)
+			if data == nil {
+				fmt.Println("gateway is not running")
+				return nil
+			}
+
+			// Find the process
+			process, err := os.FindProcess(data.PID)
+			if err != nil {
+				return fmt.Errorf("failed to find gateway process (PID: %d): %w", data.PID, err)
+			}
+
+			// Send termination signal
+			fmt.Printf("stopping gateway (PID: %d)...\n", data.PID)
+			if err := stopProcess(process); err != nil {
+				return fmt.Errorf("failed to stop gateway (PID: %d): %w", data.PID, err)
+			}
+
+			fmt.Println("gateway stopped successfully")
+			return nil
+		},
+	}
+}
diff --git a/cmd/picoclaw/internal/gateway/stop_unix.go b/cmd/picoclaw/internal/gateway/stop_unix.go
new file mode 100644
index 000000000..e4a5052f9
--- /dev/null
+++ b/cmd/picoclaw/internal/gateway/stop_unix.go
@@ -0,0 +1,13 @@
+//go:build !windows
+
+package gateway
+
+import (
+	"os"
+	"syscall"
+)
+
+// stopProcess sends SIGTERM to the process for graceful shutdown on Unix-like systems.
+func stopProcess(process *os.Process) error {
+	return process.Signal(syscall.SIGTERM)
+}
diff --git a/cmd/picoclaw/internal/gateway/stop_windows.go b/cmd/picoclaw/internal/gateway/stop_windows.go
new file mode 100644
index 000000000..99b3065d1
--- /dev/null
+++ b/cmd/picoclaw/internal/gateway/stop_windows.go
@@ -0,0 +1,12 @@
+//go:build windows
+
+package gateway
+
+import (
+	"os"
+)
+
+// stopProcess kills the process on Windows (SIGTERM is not supported).
+func stopProcess(process *os.Process) error {
+	return process.Kill()
+}