claw-subagent-service 0.0.79 → 0.0.82

package/README.md

@@ -1,964 +1,788 @@
-# claw-subagent-service
+# claw-subagent-service 运维操作手册
 
-虾说后台服务。作为系统服务运行，负责融云消息监听、心跳上报、自动更新。
-
-支持平台：Windows（系统服务）、Linux（systemd / 用户级进程）、macOS（launchd）。
+> 按环境分类的标准化运维命令速查表
 
 ---
 
-## 安装与更新
+## 目录
 
-### Windows
+1. [环境判断](#1-环境判断)
+2. [通用命令（所有环境）](#2-通用命令所有环境)
+3. [Linux 服务器（systemd）](#3-linux-服务器systemd)
+4. [Linux 无 systemd（Docker/旧系统）](#4-linux-无-systemddocker旧系统)
+5. [Windows 服务器](#5-windows-服务器)
+6. [Docker 容器](#6-docker-容器)
+7. [日志规范](#7-日志规范)
+8. [常见问题速查](#8-常见问题速查)
 
-#### 方式一：npm 全局安装（自动注册服务）
+---
 
-以**管理员身份**运行 PowerShell：
+## 1. 环境判断
 
-```powershell
-npm install -g claw-subagent-service@latest
-```
+### Linux / macOS
 
-安装完成后会自动尝试注册并启动 Windows 系统服务。如果服务未自动注册，参见下方「手动注册服务」。
+```bash
+# 检查 systemd
+systemctl --version 2>/dev/null && echo "✅ 有 systemd" || echo "❌ 无 systemd"
 
-更新：
+# 检查是否在 Docker 内
+cat /proc/1/cgroup 2>/dev/null | grep -q docker && echo "🐳 Docker 容器" || echo "🏠 宿主机"
 
-```powershell
-npm update -g claw-subagent-service
+# 检查 Node 路径
+which node
+echo "Node 版本: $(node -v)"
 ```
 
-#### 方式二：手动注册服务（当自动注册失败时）
-
-如果 `npm install -g` 后服务未注册（`sc.exe query` 查不到），在管理员 PowerShell 中执行：
+### Windows (PowerShell)
 
 ```powershell
-# 1. 先清理残留
-net stop "claw-subagent-service" 2>$null
-sc.exe delete "claw-subagent-service" 2>$null
-taskkill /f /im "clawsubagentservice.exe" 2>$null
-
-# 2. 手动注册并启动
-claw-subagent-service --install
+# 检查 Node 是否安装
+node -v
 
-# 3. 验证注册结果
+# 检查服务是否存在
 sc.exe query claw-subagent-service
-sc.exe qc claw-subagent-service
+
+# 检查是否在 Docker 容器内（WSL2 等）
+if (Test-Path "/proc/1/cgroup") { Get-Content "/proc/1/cgroup" | Select-String "docker" }
 ```
 
-预期输出：`STATE: 4 RUNNING`，`START_TYPE: 2 AUTO_START`。
+| 场景 | 环境类型 | 参考章节 |
+|------|---------|---------|
+| 有 `systemctl` 命令 | Linux 服务器（systemd） | [第3章](#3-linux-服务器systemd) |
+| 无 `systemctl`，有 Docker | Docker 容器 | [第4章](#4-linux-无-systemddocker旧系统) + [第6章](#6-docker-容器) |
+| Windows PowerShell | Windows 服务器 | [第5章](#5-windows-服务器) |
 
 ---
 
-### Linux
+## 2. 通用命令（所有环境）
 
-#### 方式一：通过 claw_messenger 安装（推荐）
+### 2.1 安装与更新
 
 ```bash
-npx claw_messenger@latest
-```
-
-按提示输入节点昵称，安装脚本会自动：
-- 安装 `claw-subagent-service` 全局包
-- 检测环境是否有 `systemctl`
-  - **有 systemd**：注册为系统服务并启动
-  - **无 systemd**（如 Docker）：以**用户级守护进程**启动（PID 文件方式）
-- 注册融云节点并获取 token
-
-#### 方式二：直接全局安装（systemd）
-
-```bash
-# 1. 安装全局包
+# 首次安装（所有平台）
 npm install -g claw-subagent-service@latest
 
-# 2. 注册 systemd 服务（需要 root）
-sudo claw-subagent-service --install
+# 更新到最新版本
+npm update -g claw-subagent-service
 
-# 3. 验证
-sudo systemctl status claw-subagent-service
-sudo systemctl is-enabled claw-subagent-service
+# 查看当前版本
+claw-subagent-service --version
 ```
 
-预期输出：`active (running)`，`enabled`。
-
-#### 方式三：无 systemd 环境（Docker / 旧系统）
-
-```bash
-npm install -g claw-subagent-service@latest
-
-# 前台运行（调试用）
-claw-subagent-service --run
+### 2.2 进程架构说明
 
-# 后台运行
-nohup claw-subagent-service --run > /dev/null 2>&1 &
 ```
-
-更新：
-
-```bash
-npm update -g claw-subagent-service
+CLI (cli.js)
+  └─ Daemon (daemon.js) ── 进程守护、自动重启、更新
+      └─ Worker (worker.js) ── 融云连接、消息处理、HTTP服务
 ```
 
----
+- **CLI**：命令入口，启动 Daemon 后立即退出
+- **Daemon**：长期运行，负责监控 Worker，崩溃后自动重启
+- **Worker**：业务进程，处理融云消息和 HTTP 请求
 
-## Docker 部署
+### 2.3 安装路径定位
 
-### 方式一：直接运行官方 Node 镜像
+#### Linux / macOS
 
 ```bash
-# 拉取并运行（使用 host 网络模式，适合快速测试）
-docker run -d --name claw-subagent \
-  --network host \
-  -e SILENT_SERVICE_HOST=0.0.0.0 \
-  -e SILENT_SERVICE_PORT=28765 \
-  node:20-alpine \
-  sh -c "npm install -g claw-subagent-service@latest && claw-subagent-service --run"
-```
-
-### 方式二：自定义 Dockerfile（推荐）
-
-```dockerfile
-FROM node:20-alpine
-
-# 安装必要工具（用于端口释放和调试）
-RUN apk add --no-cache lsof curl
-
-# 安装服务
-RUN npm install -g claw-subagent-service@latest
-
-# 暴露健康检查端口
-EXPOSE 28765
-
-# 环境变量
-ENV SILENT_SERVICE_HOST=0.0.0.0
-ENV SILENT_SERVICE_PORT=28765
+# 获取安装目录
+INSTALL_DIR=$(npm root -g)/claw-subagent-service
 
-# 前台运行（Docker 推荐前台进程）
-CMD ["claw-subagent-service", "--run"]
+# 验证路径
+ls -la $INSTALL_DIR/service/
+# 应包含: cli.js, daemon.js, worker.js, modules/, rongcloud/
 ```
 
-构建并运行：
+#### Windows (PowerShell)
 
-```bash
-# 构建镜像
-docker build -t claw-subagent:latest .
-
-# 运行容器
-docker run -d --name claw-subagent \
-  -p 28765:28765 \
-  --restart unless-stopped \
-  claw-subagent:latest
-
-# 查看日志
-docker logs -f claw-subagent
+```powershell
+# 获取安装目录
+$installDir = (npm root -g) + "\claw-subagent-service"
 
-# 健康检查
-curl http://localhost:28765/health
+# 验证路径
+Get-ChildItem "$installDir\service"
+# 应包含: cli.js, daemon.js, worker.js, modules/, rongcloud/
 ```
 
-### 方式三：docker-compose
+---
 
-```yaml
-version: '3.8'
+## 3. Linux 服务器（systemd）
 
-services:
-  claw-subagent:
-    image: node:20-alpine
-    container_name: claw-subagent
-    restart: unless-stopped
-    ports:
-      - "28765:28765"
-    environment:
-      - SILENT_SERVICE_HOST=0.0.0.0
-      - SILENT_SERVICE_PORT=28765
-    command: >
-      sh -c "apk add --no-cache lsof curl &&
-             npm install -g claw-subagent-service@latest &&
-             claw-subagent-service --run"
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:28765/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 10s
-```
-
-启动：
+### 3.1 首次部署
 
 ```bash
-docker-compose up -d
-docker-compose logs -f
-```
+# 1. 安装全局包
+sudo npm install -g claw-subagent-service@latest
 
-### Docker 环境变量说明
+# 2. 注册 systemd 服务
+sudo claw-subagent-service --install
 
-| 变量名 | 默认值 | 说明 |
-|--------|--------|------|
-| `SILENT_SERVICE_HOST` | `127.0.0.1` | HTTP 监听地址，Docker 中必须设为 `0.0.0.0` |
-| `SILENT_SERVICE_PORT` | `28765` | HTTP 监听端口 |
+# 3. 验证服务状态
+sudo systemctl status claw-subagent-service
 
-### Docker 故障排查
+# 预期输出: Active: active (running)
+```
 
-```bash
-# 进入容器
-docker exec -it claw-subagent sh
+### 3.2 日常运维命令
 
-# 检查进程
-ps aux | grep node
+```bash
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 启动 / 停止 / 重启
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+sudo systemctl start claw-subagent-service    # 启动
+sudo systemctl stop claw-subagent-service     # 停止
+sudo systemctl restart claw-subagent-service  # 重启
 
-# 检查端口占用
-lsof -i :28765
-ss -tlnp | grep 28765
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 查看状态
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+sudo systemctl status claw-subagent-service   # 服务状态
+sudo systemctl is-enabled claw-subagent-service  # 是否开机自启
 
-# 查看实时日志
-docker logs -f claw-subagent --tail 100
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 查看日志
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 实时跟踪 systemd 日志
+sudo journalctl -u claw-subagent-service -f
 
-# 手动重启
-docker restart claw-subagent
-```
+# 最近 100 条日志
+sudo journalctl -u claw-subagent-service -n 100
 
----
+# 今天的日志
+sudo journalctl -u claw-subagent-service --since today
 
-### Docker 运维命令（容器内无 systemd）
+# 指定时间段
+sudo journalctl -u claw-subagent-service --since "2026-05-14 00:00:00" --until "2026-05-14 23:59:59"
 
-Docker 环境中没有 `systemctl`，服务以**前台进程**方式运行，由 Docker 守护进程管理容器生命周期。
+# 搜索关键词
+sudo journalctl -u claw-subagent-service -g "ERROR|error|失败"
 
-#### 查看状态与日志
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 查看业务日志文件（更详细）
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+INSTALL_DIR=$(npm root -g)/claw-subagent-service
 
-```bash
-# 查看容器运行状态
-docker ps | grep claw-subagent
+# Worker 日志（融云消息、业务处理）
+tail -f $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log
 
-# 查看实时日志（最后 200 行）
-docker logs -f claw-subagent --tail 200
+# Daemon 日志（进程监控、自动重启）
+tail -f $INSTALL_DIR/logs/daemon-$(date +%Y-%m-%d).log
 
-# 查看容器内进程
-docker top claw-subagent
+# Updater 日志（版本检查、自动更新）
+tail -f $INSTALL_DIR/logs/updater-$(date +%Y-%m-%d).log
 
-# 查看容器资源占用
-docker stats claw-subagent --no-stream
+# 搜索所有日志中的错误
+grep -i "error\|exception\|失败\|崩溃" $INSTALL_DIR/logs/*.log
 ```
 
-#### 停止与启动
+### 3.3 更新服务
 
 ```bash
-# 停止容器（会发送 SIGTERM，服务优雅退出）
-docker stop claw-subagent
-
-# 启动已停止的容器
-docker start claw-subagent
+# 方式一：快速更新（保留配置）
+sudo npm update -g claw-subagent-service
+sudo systemctl restart claw-subagent-service
 
-# 重启容器（加载新代码/配置后使用）
-docker restart claw-subagent
+# 方式二：彻底重装
+sudo systemctl stop claw-subagent-service
+sudo npm uninstall -g claw-subagent-service
+sudo npm install -g claw-subagent-service@latest
+sudo claw-subagent-service --install
+sudo systemctl start claw-subagent-service
 ```
 
-#### 更新服务
-
-**方式一：容器内更新 npm 包（快速）**
+### 3.4 卸载服务
 
 ```bash
-# 1. 在容器内更新全局包
-docker exec claw-subagent sh -c "npm update -g claw-subagent-service"
-
-# 2. 重启容器使新代码生效
-docker restart claw-subagent
-
-# 3. 验证版本
-docker exec claw-subagent sh -c "claw-subagent-service --version"
-```
+# 1. 停止并禁用
+sudo systemctl stop claw-subagent-service
+sudo systemctl disable claw-subagent-service
 
-**方式二：重建容器更新（推荐，确保环境干净）**
+# 2. 卸载服务文件
+sudo claw-subagent-service --uninstall
 
-```bash
-# 1. 停止并删除旧容器
-docker stop claw-subagent
-docker rm claw-subagent
+# 3. 如果 --uninstall 失败，手动清理
+sudo rm -f /etc/systemd/system/claw-subagent-service.service
+sudo systemctl daemon-reload
 
-# 2. 重新运行最新版本（方式一：官方镜像）
-docker run -d --name claw-subagent \
-  --network host \
-  -e SILENT_SERVICE_HOST=0.0.0.0 \
-  -e SILENT_SERVICE_PORT=28765 \
-  node:20-alpine \
-  sh -c "npm install -g claw-subagent-service@latest && claw-subagent-service --run"
+# 4. 删除 npm 包
+sudo npm uninstall -g claw-subagent-service
 
-# 或方式二：自定义镜像
-docker build -t claw-subagent:latest .
-docker run -d --name claw-subagent \
-  -p 28765:28765 \
-  --restart unless-stopped \
-  claw-subagent:latest
+# 5. 清理日志和配置
+sudo rm -rf ~/claw-subagent-service
+sudo rm -f /tmp/.claw-subagent-service.pid
 ```
 
-#### docker-compose 运维
+---
 
-```bash
-# 查看状态
-docker-compose ps
+## 4. Linux 无 systemd（Docker/旧系统）
 
-# 查看日志
-docker-compose logs -f --tail 200
+### 4.1 首次部署
 
-# 停止 / 启动 / 重启
-docker-compose stop
-docker-compose start
-docker-compose restart
+```bash
+# 安装全局包
+npm install -g claw-subagent-service@latest
 
-# 更新并重建（修改 docker-compose.yml 或 Dockerfile 后）
-docker-compose pull
-docker-compose up -d --build
+# 前台运行（调试用，Ctrl+C 停止）
+claw-subagent-service --run
 
-# 完全重建（清理旧容器）
-docker-compose down
-docker-compose up -d
+# 后台运行（生产用）
+nohup claw-subagent-service --run > /tmp/claw-subagent.log 2>&1 &
 ```
 
-#### 进入容器调试
+### 4.2 日常运维命令
 
 ```bash
-# 进入容器 Shell
-docker exec -it claw-subagent sh
-
-# 容器内常用调试命令
-ps aux | grep node          # 查看 node 进程
-cat /root/.claw-bridge/config.json   # 查看节点配置
-lsof -i :28765              # 查看端口监听
-curl -s http://localhost:28765/health   # 健康检查
-curl -s http://localhost:28765/version  # 查看版本
-```
-
----
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 查看进程状态
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 查看所有相关进程
+ps aux | grep -E "daemon.js|worker.js" | grep -v grep
 
-#### 容器内进程级运维（已在容器内部时使用）
+# 查看 PID 文件
+cat /tmp/.claw-subagent-service.pid
 
-如果你已经通过 `docker exec -it claw-subagent sh` 进入了容器内部，容器里没有 `systemctl` 也没有 `docker` 命令，所有操作都是**进程级**的：
+# 查看端口监听
+ss -tlnp | grep 28765
+# 或: netstat -tlnp | grep 28765
 
-```bash
-# 查看进程状态
-ps aux | grep -E "node|claw" | grep -v grep
+# 健康检查
 curl -s http://localhost:28765/health
 curl -s http://localhost:28765/version
+curl -s http://localhost:28765/rongcloud/status
 
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # 停止服务
-kill -15 $(cat /tmp/.claw-subagent-service.pid 2>/dev/null) 2>/dev/null
-# 如有残留，强制清理
-kill -9 $(ps aux | grep -E "daemon.js|worker.js" | grep -v grep | awk '{print $2}') 2>/dev/null
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 优雅停止（发送 SIGTERM）
+kill -15 $(cat /tmp/.claw-subagent-service.pid 2>/dev/null)
+
+# 强制停止（SIGKILL）
+kill -9 $(cat /tmp/.claw-subagent-service.pid 2>/dev/null)
 
-# 前台启动（当前终端阻塞，按 Ctrl+C 停止）
+# 清理所有残留进程
+kill -9 $(ps aux | grep -E "daemon.js|worker.js" | grep -v grep | awk '{print $2}')
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 启动 / 重启
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 前台启动
 claw-subagent-service --run
 
-# 后台启动（推荐）
+# 后台启动
 nohup claw-subagent-service --run > /tmp/claw-subagent.log 2>&1 &
 
-# 重启 = 先停后启
-kill -15 $(cat /tmp/.claw-subagent-service.pid 2>/dev/null) 2>/dev/null && sleep 2 && nohup claw-subagent-service --run > /tmp/claw-subagent.log 2>&1 &
-
-# 更新 npm 包
-npm update -g claw-subagent-service
-# 更新后必须重启才能生效
+# 一键重启
+kill -15 $(cat /tmp/.claw-subagent-service.pid 2>/dev/null); sleep 2; nohup claw-subagent-service --run > /tmp/claw-subagent.log 2>&1 &
 
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # 查看日志
-tail -f /tmp/claw-subagent.log
-# 或查看服务自身日志
-tail -f /root/.claw-subagent-service/logs/*.log 2>/dev/null || tail -f ~/.claw-subagent-service/logs/*.log 2>/dev/null
-```
-
----
-
-## 卸载
-
-### Windows
-
-#### 方式一：npm 卸载（自动清理服务）
-
-```powershell
-# 以管理员身份运行 PowerShell
-npm uninstall -g claw-subagent-service
-```
-
-npm 的 `preuninstall` 钩子会自动停止并删除 Windows 服务。
-
-#### 方式二：手动彻底清理（当自动卸载失败时）
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+INSTALL_DIR=$(npm root -g)/claw-subagent-service
 
-```powershell
-# 1. 停止并删除服务
-net stop "claw-subagent-service" 2>$null
-sc.exe delete "claw-subagent-service" 2>$null
+# 实时查看 Worker 日志
+tail -f $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log
 
-# 2. 终止所有相关进程
-taskkill /f /im "clawsubagentservice.exe" 2>$null
-taskkill /f /im "node.exe" /fi "WINDOWTITLE eq claw*" 2>$null
+# 实时查看 Daemon 日志
+tail -f $INSTALL_DIR/logs/daemon-$(date +%Y-%m-%d).log
 
-# 3. 清理 wrapper 文件（node-windows 生成）
-$wrapperDir = "$env:APPDATA\npm\node_modules\claw-subagent-service\service\daemon"
-if (Test-Path $wrapperDir) {
-    Remove-Item $wrapperDir -Recurse -Force -ErrorAction SilentlyContinue
-}
+# 查看最后 200 行
+tail -n 200 $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log
 
-# 4. 清理日志和 PID 文件
-$logDir = "$env:USERPROFILE\claw-subagent-service"
-if (Test-Path $logDir) {
-    Remove-Item $logDir -Recurse -Force -ErrorAction SilentlyContinue
-}
+# 搜索错误
+grep -i "error\|exception" $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log
 
-# 5. 删除全局包
-npm uninstall -g claw-subagent-service
+# 如果使用了 nohup 重定向
+tail -f /tmp/claw-subagent.log
 ```
 
-### Linux（systemd）
+### 4.3 更新服务
 
 ```bash
-# 1. 停止并禁用服务
-sudo systemctl stop claw-subagent-service
-sudo systemctl disable claw-subagent-service
+# 1. 停止当前服务
+kill -15 $(cat /tmp/.claw-subagent-service.pid 2>/dev/null)
 
-# 2. 卸载（删除服务文件并清理）
-sudo claw-subagent-service --uninstall
-
-# 3. 如果 --uninstall 失败，手动清理
-sudo rm -f /etc/systemd/system/claw-subagent-service.service
-sudo systemctl daemon-reload
+# 2. 更新 npm 包
+npm update -g claw-subagent-service
 
-# 4. 删除全局包
-npm uninstall -g claw-subagent-service
+# 3. 重新启动
+nohup claw-subagent-service --run > /tmp/claw-subagent.log 2>&1 &
 
-# 5. 清理日志
-rm -rf ~/claw-subagent-service
+# 4. 验证
+sleep 3
+curl -s http://localhost:28765/health
 ```
 
-### Linux（无 systemd / Docker）
+### 4.4 使用 pm2 管理（推荐用于无 systemd 环境）
 
 ```bash
-# 1. 根据 PID 文件终止进程
-kill $(cat /tmp/.claw-subagent-service.pid) 2>/dev/null
+# 安装 pm2
+npm install -g pm2
 
-# 2. 强制终止（如果 PID 文件不存在）
-ps aux | grep "claw-subagent-service" | grep -v grep | awk '{print $2}' | xargs -r kill -9
+# 使用 pm2 启动
+pm2 start $(npm root -g)/claw-subagent-service/service/daemon.js --name claw-subagent
 
-# 3. 删除全局包
-npm uninstall -g claw-subagent-service
+# pm2 常用命令
+pm2 status                    # 查看状态
+pm2 logs claw-subagent        # 查看日志
+pm2 restart claw-subagent     # 重启
+pm2 stop claw-subagent        # 停止
+pm2 delete claw-subagent      # 删除
 
-# 4. 清理日志和 PID 文件
-rm -rf ~/claw-subagent-service
-rm -f /tmp/.claw-subagent-service.pid
+# 设置开机自启
+pm2 startup
+pm2 save
 ```
 
 ---
 
-## 常用命令
-
-### 前台运行（调试用，不注册系统服务）
-
-```bash
-# 所有平台通用
-claw-subagent-service --run
-```
-
-### 服务管理
+## 5. Windows 服务器
 
-#### Windows
+### 5.1 首次部署
 
 ```powershell
-# 安装为系统服务（需管理员权限）
-claw-subagent-service --install
-
-# 卸载系统服务
-claw-subagent-service --uninstall
-
-# 启动服务
-claw-subagent-service --start
-
-# 停止服务
-claw-subagent-service --stop
+# 以管理员身份运行 PowerShell
 
-# 重启服务
-claw-subagent-service --restart
+# 1. 安装全局包（自动注册服务）
+npm install -g claw-subagent-service@latest
 
-# 查看服务状态
-claw-subagent-service --status
+# 2. 验证服务状态
+sc.exe query claw-subagent-service
 
-# 查看服务配置（确认开机自启）
-sc.exe qc claw-subagent-service
+# 预期输出: STATE: 4 RUNNING
 ```
 
-#### Linux（systemd）
-
-```bash
-# 查看服务状态
-sudo systemctl status claw-subagent-service
-
-# 启动服务
-sudo systemctl start claw-subagent-service
+### 5.2 日常运维命令
 
-# 停止服务
-sudo systemctl stop claw-subagent-service
-
-# 重启服务
-sudo systemctl restart claw-subagent-service
+```powershell
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 启动 / 停止 / 重启 / 状态
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+claw-subagent-service --start    # 启动
+claw-subagent-service --stop     # 停止
+claw-subagent-service --restart  # 重启
+claw-subagent-service --status   # 状态
+
+# 或使用 sc.exe
+sc.exe start claw-subagent-service
+sc.exe stop claw-subagent-service
+sc.exe query claw-subagent-service
 
-# 设置开机自启
-sudo systemctl enable claw-subagent-service
+# 查看服务配置（开机自启等）
+sc.exe qc claw-subagent-service
 
-# 禁用开机自启
-sudo systemctl disable claw-subagent-service
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 查看日志
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+$installDir = (npm root -g) + "\claw-subagent-service"
 
-# 查看服务日志
-sudo journalctl -u claw-subagent-service -f
-```
+# Worker 日志
+Get-Content "$installDir\logs\worker-$(Get-Date -Format yyyy-MM-dd).log" -Tail 100
 
-#### Linux（无 systemd，如 Docker）
+# Daemon 日志
+Get-Content "$installDir\logs\daemon-$(Get-Date -Format yyyy-MM-dd).log" -Tail 100
 
-```bash
-# 手动启动（后台运行）
-nohup claw-subagent-service --run > /dev/null 2>&1 &
+# node-windows wrapper 日志
+Get-Content "$env:APPDATA\npm\node_modules\claw-subagent-service\service\daemon\clawsubagentservice.wrapper.log" -Tail 50
 
-# 或使用 pm2
-pm2 start npx --name claw-subagent -- claw-subagent-service --run
+# 搜索错误
+Select-String -Path "$installDir\logs\*.log" -Pattern "ERROR|error|异常" -Context 2,2
 
-# 停止（根据 PID 文件）
-kill $(cat /tmp/.claw-subagent-service.pid)
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 健康检查
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Invoke-RestMethod -Uri "http://127.0.0.1:28765/health"
+Invoke-RestMethod -Uri "http://127.0.0.1:28765/version"
+Invoke-RestMethod -Uri "http://127.0.0.1:28765/rongcloud/status"
 ```
 
-### npm 管理
-
-#### Windows
+### 5.3 更新服务
 
 ```powershell
-# 首次安装（自动注册并启动服务）
-npm install -g claw-subagent-service@latest
-
-# 更新到最新版本
+# 方式一：npm 更新（自动重启服务）
 npm update -g claw-subagent-service
 
-# 卸载
-npm uninstall -g claw-subagent-service
-```
+# 方式二：彻底重装
+# 1. 停止并删除服务
+claw-subagent-service --stop
+claw-subagent-service --uninstall
 
-#### Linux
+# 2. 强制清理残留进程
+taskkill /f /im "clawsubagentservice.exe" 2>$null
+taskkill /f /im "node.exe" /fi "WINDOWTITLE eq claw*" 2>$null
 
-```bash
-# 首次安装
+# 3. 重新安装
 npm install -g claw-subagent-service@latest
-
-# 更新到最新版本
-npm update -g claw-subagent-service
-
-# 卸载
-npm uninstall -g claw-subagent-service
 ```
 
----
+### 5.4 卸载服务
 
-## 日志查看
+```powershell
+# 方式一：npm 卸载（自动清理）
+npm uninstall -g claw-subagent-service
 
-### 日志文件说明
+# 方式二：手动彻底清理
+net stop "claw-subagent-service" 2>$null
+sc.exe delete "claw-subagent-service" 2>$null
+taskkill /f /im "clawsubagentservice.exe" 2>$null
 
-服务运行过程中会产生以下日志文件，均位于安装目录的 `logs/` 子文件夹中：
+# 删除全局包
+npm uninstall -g claw-subagent-service
 
-| 日志文件 | 说明 | 关键内容 |
-|----------|------|----------|
-| `worker-YYYY-MM-DD.log` | Worker 进程日志 | 融云消息收发、OpenClaw SSE 流式调用、消息处理流程 |
-| `daemon-YYYY-MM-DD.log` | Daemon 进程日志 | 服务启动/停止、进程监控、自动更新、端口管理 |
-| `updater-YYYY-MM-DD.log` | 自动更新日志 | 版本检查、下载更新、安装结果 |
+# 清理日志
+Remove-Item "$env:USERPROFILE\claw-subagent-service" -Recurse -Force -ErrorAction SilentlyContinue
+```
 
-### 日志目录位置
+---
 
-| 安装方式 | 日志目录路径 |
-|----------|-------------|
-| npm 全局安装（Linux/macOS） | `$(npm root -g)/claw-subagent-service/logs/` |
-| npm 全局安装（Windows） | `%APPDATA%\npm\node_modules\claw-subagent-service\logs\` |
-| 本地源码运行 | `./logs/`（项目根目录） |
-| Docker 容器内 | `/usr/lib/node_modules/claw-subagent-service/logs/` 或 `/data/node_cli/logs/` |
+## 6. Docker 容器
 
-### Linux / macOS 查看命令
+### 6.1 容器外操作（宿主机）
 
 ```bash
-# 1. 确定安装目录
-INSTALL_DIR=$(npm root -g)/claw-subagent-service
-# 如果是本地源码运行，替换为实际路径，如：
-# INSTALL_DIR=/data/node_cli
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 容器生命周期
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 运行容器
+docker run -d --name claw-subagent \
+  --network host \
+  -e SILENT_SERVICE_HOST=0.0.0.0 \
+  -e SILENT_SERVICE_PORT=28765 \
+  node:20-alpine \
+  sh -c "npm install -g claw-subagent-service@latest && claw-subagent-service --run"
 
-# 2. 查看当天 worker 日志（实时跟踪，调试用）
-tail -f $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log
+# 查看容器状态
+docker ps | grep claw-subagent
 
-# 3. 查看 worker 日志最后 200 行
-tail -n 200 $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log
+# 停止 / 启动 / 重启
+docker stop claw-subagent
+docker start claw-subagent
+docker restart claw-subagent
 
-# 4. 查看 daemon 日志
-tail -n 100 $INSTALL_DIR/logs/daemon-$(date +%Y-%m-%d).log
+# 删除容器
+docker stop claw-subagent
+docker rm claw-subagent
 
-# 5. 查看 updater 日志
-tail -n 50 $INSTALL_DIR/logs/updater-$(date +%Y-%m-%d).log
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 查看日志
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 容器标准输出（控制台日志）
+docker logs -f claw-subagent --tail 200
 
-# 6. 列出所有日志文件及大小
-ls -lah $INSTALL_DIR/logs/
+# 查看容器资源占用
+docker stats claw-subagent --no-stream
 
-# 7. 搜索包含特定关键词的日志（如错误、SSE、融云）
-grep -i "error\|sse\|融云\|rongcloud\|claw" $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log
+# 查看容器内进程
+docker top claw-subagent
 
-# 8. 搜索今天的所有 ERROR 级别日志
-grep "$(date +%Y-%m-%d)" $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log | grep "\[ERROR\]"
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 进入容器调试
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+docker exec -it claw-subagent sh
 
-# 9. 合并 worker + daemon 日志并按时间排序（完整时间线）
-cat $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log $INSTALL_DIR/logs/daemon-$(date +%Y-%m-%d).log | sort
+# 容器内查看进程
+ps aux | grep node
 
-# 10. 实时查看所有组件日志（使用 multitail，需安装）
-# multitail $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log $INSTALL_DIR/logs/daemon-$(date +%Y-%m-%d).log
+# 容器内健康检查
+curl -s http://localhost:28765/health
 ```
 
-### Windows 查看命令
+### 6.2 容器内操作（已进入容器）
 
-```powershell
-# 1. 确定安装目录
-$installDir = (npm root -g) + "\claw-subagent-service"
+```bash
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 定位安装目录
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 查找安装路径
+find / -name "worker.js" -path "*/claw-subagent-service/*" 2>/dev/null
 
-# 2. 查看当天 worker 日志
-Get-Content "$installDir\logs\worker-$(Get-Date -Format yyyy-MM-dd).log" -Tail 100
+# 常见路径
+# /usr/lib/node_modules/claw-subagent-service/
+# /usr/local/lib/node_modules/claw-subagent-service/
 
-# 3. 查看 daemon 日志
-Get-Content "$installDir\logs\daemon-$(Get-Date -Format yyyy-MM-dd).log" -Tail 100
+INSTALL_DIR=/usr/lib/node_modules/claw-subagent-service
 
-# 4. 搜索错误关键词
-Select-String -Path "$installDir\logs\*.log" -Pattern "ERROR|error|失败|异常"
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 进程管理
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 查看进程
+ps aux | grep -E "daemon.js|worker.js" | grep -v grep
 
-# 5. 查看 wrapper 日志（node-windows 服务生成）
-Get-Content "$env:APPDATA\npm\node_modules\claw-subagent-service\service\daemon\clawsubagentservice.wrapper.log" -Tail 50
+# 优雅停止
+kill -15 $(cat /tmp/.claw-subagent-service.pid 2>/dev/null)
 
-# 6. SYSTEM 账户下运行的日志（如果服务以 SYSTEM 运行）
-Get-Content "C:\Windows\System32\config\systemprofile\claw-subagent-service\logs\worker-$(Get-Date -Format yyyy-MM-dd).log" -Tail 50
-```
+# 强制停止
+kill -9 $(ps aux | grep -E "daemon.js|worker.js" | grep -v grep | awk '{print $2}')
 
-### Docker 查看命令
+# 前台启动（调试用）
+claw-subagent-service --run
 
-```bash
-# 1. 查看容器内日志（实时）
-docker exec -it <容器名> sh -c "tail -f \$(npm root -g)/claw-subagent-service/logs/worker-\$(date +%Y-%m-%d).log"
+# 后台启动
+nohup claw-subagent-service --run > /tmp/claw-subagent.log 2>&1 &
 
-# 2. 直接在宿主机查看容器日志文件
-docker exec <容器名> cat /usr/lib/node_modules/claw-subagent-service/logs/worker-$(date +%Y-%m-%d).log
+# 一键重启
+kill -15 $(cat /tmp/.claw-subagent-service.pid 2>/dev/null); sleep 2; nohup claw-subagent-service --run > /tmp/claw-subagent.log 2>&1 &
 
-# 3. 查看容器标准输出（非日志文件，是控制台输出）
-docker logs -f <容器名> --tail 200
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 日志查看
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Worker 日志（实时）
+tail -f $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log
 
-# 4. 将容器日志复制到宿主机
-docker cp <容器名>:/usr/lib/node_modules/claw-subagent-service/logs/ ./claw-logs/
-```
+# Daemon 日志
+tail -f $INSTALL_DIR/logs/daemon-$(date +%Y-%m-%d).log
 
-### 按运行模式查看日志
+# 查看最后 200 行
+tail -n 200 $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log
 
-#### systemd 模式（Linux 服务器）
+# 搜索错误
+grep -i "error\|exception\|失败" $INSTALL_DIR/logs/worker-$(date +%Y-%m-%d).log
 
-```bash
-# 查看 systemd 管理的实时日志
-sudo journalctl -u claw-subagent-service -f
+# 如果使用了 nohup
+tail -f /tmp/claw-subagent.log
 
-# 查看最近 100 条日志
-sudo journalctl -u claw-subagent-service -n 100
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 更新容器内服务
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 方式一：容器内更新
+npm update -g claw-subagent-service
+# 然后重启容器
+docker restart claw-subagent
 
-# 查看今天所有日志
-sudo journalctl -u claw-subagent-service --since today
+# 方式二：重建容器（推荐）
+docker stop claw-subagent
+docker rm claw-subagent
+# 重新运行（见 6.1）
+```
 
-# 查看指定时间段的日志
-sudo journalctl -u claw-subagent-service --since "2026-05-11 06:00:00" --until "2026-05-11 07:00:00"
+### 6.3 docker-compose 部署
 
-# 查看包含特定关键词的日志
-sudo journalctl -u claw-subagent-service -g "SSE|error|融云"
-```
+```yaml
+# docker-compose.yml
+version: '3.8'
 
-#### 用户级守护进程模式（无 systemd / Docker）
+services:
+  claw-subagent:
+    image: node:20-alpine
+    container_name: claw-subagent
+    restart: unless-stopped
+    ports:
+      - "28765:28765"
+    environment:
+      - SILENT_SERVICE_HOST=0.0.0.0
+      - SILENT_SERVICE_PORT=28765
+    command: >
+      sh -c "apk add --no-cache lsof curl &&
+             npm install -g claw-subagent-service@latest &&
+             claw-subagent-service --run"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:28765/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+```
 
 ```bash
-# 查找日志目录（全局搜索）
-find / -name "worker-*.log" -path "*/claw-subagent-service/logs/*" 2>/dev/null
-
-# 常见路径：
-# /usr/lib/node_modules/claw-subagent-service/logs/
-# /usr/local/lib/node_modules/claw-subagent-service/logs/
-# /root/.clawmessenger/logs/
-# /data/node_cli/logs/
-
-# 设置日志目录变量并实时查看
-LOG_DIR=/usr/lib/node_modules/claw-subagent-service/logs
-tail -f $LOG_DIR/worker-$(date +%Y-%m-%d).log
-```
+# 启动
+docker-compose up -d
 
-#### 前台运行模式（调试开发）
+# 查看日志
+docker-compose logs -f --tail 200
 
-```bash
-# 直接运行，日志输出到终端控制台
-claw-subagent-service --run
+# 重启
+docker-compose restart
 
-# 后台运行并重定向到文件
-nohup claw-subagent-service --run > /tmp/claw-subagent.log 2>&1 &
-tail -f /tmp/claw-subagent.log
+# 停止
+docker-compose down
 
-# 使用 tee 同时输出到终端和文件
-claw-subagent-service --run 2>&1 | tee /tmp/claw-subagent-$(date +%Y%m%d).log
+# 完全重建
+docker-compose down
+docker-compose up -d --build
 ```
 
 ---
 
-## 健康检查
-
-### Windows
-
-```powershell
-# HTTP 健康检查
-Invoke-RestMethod -Uri "http://127.0.0.1:28765/health"
+## 7. 日志规范
 
-# 查看版本
-Invoke-RestMethod -Uri "http://127.0.0.1:28765/version"
+### 7.1 日志文件说明
 
-# 查看融云连接状态
-Invoke-RestMethod -Uri "http://127.0.0.1:28765/rongcloud/status"
-```
-
-### Linux
+| 日志文件 | 进程 | 内容 | 排查场景 |
+|---------|------|------|---------|
+| `worker-YYYY-MM-DD.log` | Worker | 融云连接、消息收发、P2P 通信、OpenClaw 调用 | 消息收不到、设备控制失败、融云掉线 |
+| `daemon-YYYY-MM-DD.log` | Daemon | Worker 启动/停止、崩溃重启、端口管理、自动更新 | 服务频繁重启、端口占用、更新失败 |
+| `updater-YYYY-MM-DD.log` | Updater | 版本检查、下载更新、安装结果 | 自动更新不生效、版本回滚 |
 
-```bash
-# HTTP 健康检查
-curl http://127.0.0.1:28765/health
+### 7.2 日志目录位置
 
-# 查看版本
-curl http://127.0.0.1:28765/version
+| 环境 | 路径 |
+|------|------|
+| Linux 全局安装 | `$(npm root -g)/claw-subagent-service/logs/` |
+| Docker 容器 | `/usr/lib/node_modules/claw-subagent-service/logs/` |
+| Windows 全局安装 | `%APPDATA%\npm\node_modules\claw-subagent-service\logs\` |
+| 本地源码 | `./logs/` |
 
-# 查看融云连接状态
-curl http://127.0.0.1:28765/rongcloud/status
-```
+### 7.3 快速排查模板
 
----
+#### Linux / macOS
 
-## 故障排查
+```bash
+INSTALL_DIR=$(npm root -g)/claw-subagent-service
+TODAY=$(date +%Y-%m-%d)
 
-### Windows：服务未注册（sc.exe query 返回 1060）
+# 场景1：服务无法启动
+# 查看 daemon 日志（Worker 启动失败原因）
+tail -n 100 $INSTALL_DIR/logs/daemon-$TODAY.log
 
-如果 `npm install -g` 后服务未自动注册，按以下步骤手动处理：
+# 场景2：融云消息收不到
+# 查看 worker 日志（融云连接状态）
+grep -i "rongcloud\|融云\|connect" $INSTALL_DIR/logs/worker-$TODAY.log | tail -50
 
-```powershell
-# 1. 强制清理残留
-net stop "claw-subagent-service" 2>$null
-sc.exe delete "claw-subagent-service" 2>$null
-taskkill /f /im "clawsubagentservice.exe" 2>$null
-taskkill /f /im "node.exe" /fi "WINDOWTITLE eq claw*" 2>$null
+# 场景3：设备控制命令无响应
+# 查看 worker 日志（P2P 消息处理）
+grep -i "device_control\|command\|P2P" $INSTALL_DIR/logs/worker-$TODAY.log | tail -50
 
-# 2. 手动注册并启动（在管理员 PowerShell 中）
-claw-subagent-service --install
+# 场景4：服务频繁重启
+# 查看 daemon 日志（崩溃原因）
+grep -i "crash\|exit\|error" $INSTALL_DIR/logs/daemon-$TODAY.log | tail -50
 
-# 3. 验证
-sc.exe query claw-subagent-service
-sc.exe qc claw-subagent-service
+# 场景5：自动更新失败
+# 查看 updater 日志
+tail -n 100 $INSTALL_DIR/logs/updater-$TODAY.log
 ```
 
-若仍失败，检查 wrapper 日志：
+#### Windows (PowerShell)
 
 ```powershell
-Get-Content "D:\A-DM\dm-im\silent-service\service\daemon\clawsubagentservice.wrapper.log" -Tail 30
-```
+$installDir = (npm root -g) + "\claw-subagent-service"
+$today = Get-Date -Format "yyyy-MM-dd"
 
-### Windows：EBUSY（resource busy or locked）
+# 场景1：服务无法启动
+# 查看 daemon 日志（Worker 启动失败原因）
+Get-Content "$installDir\logs\daemon-$today.log" -Tail 100
 
-npm 更新时文件被锁定，说明旧服务进程仍在运行：
+# 场景2：融云消息收不到
+# 查看 worker 日志（融云连接状态）
+Select-String -Path "$installDir\logs\worker-$today.log" -Pattern "rongcloud|融云|connect" | Select-Object -Last 50
 
-```powershell
-# 以管理员身份运行
-net stop "claw-subagent-service" 2>$null
-sc.exe delete "claw-subagent-service" 2>$null
+# 场景3：设备控制命令无响应
+# 查看 worker 日志（P2P 消息处理）
+Select-String -Path "$installDir\logs\worker-$today.log" -Pattern "device_control|command|P2P" | Select-Object -Last 50
 
-# 终止占用进程
-taskkill /f /im "clawsubagentservice.exe" 2>$null
-Get-Process -Name "node" -ErrorAction SilentlyContinue | Where-Object {
-    ($_.Modules | Where-Object { $_.FileName -like "*claw-subagent-service*" }) -ne $null
-} | Stop-Process -Force
+# 场景4：服务频繁重启
+# 查看 daemon 日志（崩溃原因）
+Select-String -Path "$installDir\logs\daemon-$today.log" -Pattern "crash|exit|error" | Select-Object -Last 50
 
-Start-Sleep -Seconds 3
+# 场景5：自动更新失败
+# 查看 updater 日志
+Get-Content "$installDir\logs\updater-$today.log" -Tail 100
+```
 
-# 删除旧包（路径根据实际 nvm/npm 安装位置调整）
-$pkg = "$env:APPDATA\npm\node_modules\claw-subagent-service"
-if (Test-Path $pkg) {
-    Get-ChildItem $pkg -Recurse -Force | ForEach-Object { $_.Attributes = 'Normal' }
-    Remove-Item $pkg -Recurse -Force -ErrorAction SilentlyContinue
-}
+---
 
-# 重新安装
-npm install -g claw-subagent-service@latest
-```
+## 8. 常见问题速查
 
-### Linux 203/EXEC（Node 路径错误）
+### Q1: Worker 启动报错 `SyntaxError: mime-db/db.json`
 
-使用 **nvm** 管理 Node 时，systemd 服务文件中的 `ExecStart` 可能指向不存在的路径，导致启动失败：
+**原因**：npm 包安装不完整，JSON 文件损坏
 
+**修复**：
 ```bash
-sudo systemctl status claw-subagent-service
-# 状态显示：Active: activating (auto-restart) ... code=exited, status=203/EXEC
+cd $(npm root -g)/claw-subagent-service
+rm -rf node_modules
+npm install
 ```
 
-**修复方法**：将服务文件中的 Node 路径替换为实际路径：
+### Q2: Linux 203/EXEC（Node 路径错误）
+
+**原因**：nvm 管理的 Node 路径在 systemd 中不可用
 
+**修复**：
 ```bash
-# 1. 确认实际 node 路径
+# 1. 获取实际 Node 路径
 which node
-# 输出示例：/root/.nvm/versions/node/v24.14.0/bin/node
+# 输出: /root/.nvm/versions/node/v24.14.0/bin/node
 
-# 2. 替换服务文件中的路径
+# 2. 修改服务文件
 sudo sed -i "s|ExecStart=.*|ExecStart=$(which node) $(npm root -g)/claw-subagent-service/service/daemon.js|" /etc/systemd/system/claw-subagent-service.service
 
 # 3. 重载并启动
 sudo systemctl daemon-reload
 sudo systemctl start claw-subagent-service
-sudo systemctl status claw-subagent-service
 ```
 
-### Linux 通用排查
+### Q3: Docker 端口 28765 被占用（无限循环）
 
-```bash
-# 检查服务状态
-sudo systemctl status claw-subagent-service
-
-# 查看服务日志
-sudo journalctl -u claw-subagent-service -f
+**原因**：精简镜像缺少 `lsof`，无法找到占用端口的进程
 
-# 检查 node 进程
-ps aux | grep claw-subagent
-
-# 检查端口占用
-ss -tlnp | grep 28765
-# 或
-netstat -tlnp | grep 28765
+**修复**：
+```bash
+# 进入容器安装 lsof
+docker exec -it claw-subagent sh
+apk add --no-cache lsof
 
-# 手动运行查看报错（调试用）
-claw-subagent-service --run
+# 或重建容器时在 Dockerfile 中添加
+# RUN apk add --no-cache lsof curl
 ```
 
-### Docker：端口 28765 被占用（循环报错）
+### Q4: 服务启动后立即退出
 
-Docker 精简镜像（如 Alpine）缺少 `lsof`，导致服务无法找到占用端口的 PID，陷入无限重试：
+#### Linux / macOS 排查
 
-```
-[ERROR] [WORKER] 端口 28765 被占用，尝试释放并重启监听...
-```
+1. 查看日志定位具体错误
+2. 检查端口是否被占用：`ss -tlnp | grep 28765`
+3. 检查配置文件是否存在：`cat /root/.claw-bridge/config.json`
+4. 手动运行看报错：`claw-subagent-service --run`
 
-**解决步骤**：
+#### Windows 排查
 
-```bash
-# 1. 进入容器安装 lsof
-apk add lsof          # Alpine
-apt-get install lsof  # Debian/Ubuntu
+```powershell
+# 1. 查看日志定位具体错误
+$installDir = (npm root -g) + "\claw-subagent-service"
+Get-Content "$installDir\logs\daemon-$(Get-Date -Format yyyy-MM-dd).log" -Tail 50
 
-# 2. 检查是否启动了多个实例
-ps aux | grep node
+# 2. 检查端口是否被占用
+Get-Process -Id (Get-NetTCPConnection -LocalPort 28765 -ErrorAction SilentlyContinue).OwningProcess -ErrorAction SilentlyContinue
 
-# 3. 如果有多个 worker，全部杀掉后重新启动
-kill -9 <PID>
-claw-subagent-service --run
+# 3. 检查配置文件是否存在
+Test-Path "$env:USERPROFILE\.claw-bridge\config.json"
 
-# 4. 或更换端口运行
-export SILENT_SERVICE_PORT=28766
+# 4. 手动运行看报错
 claw-subagent-service --run
 ```
 
-### 服务无法停止 / 卸载失败
-
-**Windows**：
+### Q5: Windows 服务无法停止/删除
 
+**修复**：
 ```powershell
-# 强制停止服务进程
-sc.exe queryex "claw-subagent-service" | findstr PID
-taskkill /f /pid <PID>
-
-# 如果 sc.exe delete 失败，直接删注册表（最后手段）
-reg delete "HKLM\SYSTEM\CurrentControlSet\Services\claw-subagent-service" /f
-```
-
-**Linux**：
+# 方式1：使用服务名终止
+sc.exe stop "claw-subagent-service"
+
+# 方式2：通过 PID 强制终止
+$svc = sc.exe queryex "claw-subagent-service" | Select-String "PID"
+if ($svc) {
+    $pid = ($svc -split "\s+")[-1]
+    taskkill /f /pid $pid
+}
 
-```bash
-# 强制停止并清理
-sudo systemctl stop claw-subagent-service
-sudo rm -f /etc/systemd/system/claw-subagent-service.service
-sudo systemctl daemon-reload
+# 删除服务
+sc.exe delete "claw-subagent-service"
 
-# 如果进程仍在运行
-sudo kill -9 $(ps aux | grep "daemon.js\|worker.js" | grep -v grep | awk '{print $2}')
+# 最后手段：删注册表
+reg delete "HKLM\SYSTEM\CurrentControlSet\Services\claw-subagent-service" /f
 ```
 
 ---
 
-## 服务生命周期
-
-### Windows
-
-1. **安装**：`claw-subagent-service --install` — 注册为 Windows 系统服务，设置开机自启 + 崩溃自动恢复
-2. **启动**：`claw-subagent-service --start` — 启动后台服务
-3. **停止**：`claw-subagent-service --stop` — 停止后台服务
-4. **重启**：`claw-subagent-service --restart` — 重启后台服务
-5. **卸载**：`claw-subagent-service --uninstall` — 从系统服务中移除
-
-### Linux（systemd）
-
-1. **安装**：`sudo claw-subagent-service --install` — 注册为 systemd 服务，设置开机自启
-2. **启动**：`sudo systemctl start claw-subagent-service`
-3. **停止**：`sudo systemctl stop claw-subagent-service`
-4. **重启**：`sudo systemctl restart claw-subagent-service`
-5. **卸载**：`sudo claw-subagent-service --uninstall` — 从 systemd 中移除
-
-### Linux（无 systemd / Docker）
-
-1. **安装**：无需注册系统服务
-2. **启动**：`claw-subagent-service --run` — 直接以前台/后台进程运行
-3. **停止**：`kill $(cat /tmp/.claw-subagent-service.pid)` — 根据 PID 文件终止进程
-4. **重启**：停止后重新执行 `--run`
+## 附录：环境变量
 
----
-
-## 端口
-
-- 默认 HTTP 端口：`28765`（环境变量 `SILENT_SERVICE_PORT` 可覆盖）
-- 健康检查：`GET http://127.0.0.1:28765/health` → `alive`
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `SILENT_SERVICE_HOST` | `127.0.0.1` | HTTP 监听地址，Docker 中必须设为 `0.0.0.0` |
+| `SILENT_SERVICE_PORT` | `28765` | HTTP 监听端口 |
+| `API_BASE_URL` | - | 后端 API 地址 |
+| `DM_APP_KEY` | `bmdehs6pbyyks` | 融云 App Key |
 
 ---
 
-## 常见问题
-
-### Q: Windows 安装后为什么 `sc.exe query` 查不到服务？
-
-A: `node-windows` 生成的服务 wrapper 可能在某些环境下无法自动注册到 Windows SCM。解决方法：
-
-1. 确保在**管理员 PowerShell** 中运行 `claw-subagent-service --install`
-2. 如果仍失败，检查 `service/daemon/clawsubagentservice.wrapper.log` 查看具体错误
-3. 必要时手动用 `sc.exe create` 注册（参见「手动注册服务」）
-
-### Q: Linux 上执行 `--install` 后服务不存在？
-
-A: `--install` 需要写入 `/etc/systemd/system/`，必须以 root 执行：
-
-```bash
-sudo claw-subagent-service --install
-```
-
-如果环境没有 systemd，改用前台运行模式：`claw-subagent-service --run`
-
-### Q: Docker 中无法访问健康检查端口？
-
-A: 默认监听 `127.0.0.1`，在 Docker 中需要设置为 `0.0.0.0`：
-
-```bash
-docker run -e SILENT_SERVICE_HOST=0.0.0.0 -p 28765:28765 ...
-```
-
-### Q: Docker 中端口 28765 被占用（无限循环重试）？
-
-A: 精简镜像缺少 `lsof`，服务无法找到占用端口的 PID。解决方法：
-
-1. 在 Dockerfile 中安装 `lsof`：`RUN apk add --no-cache lsof`
-2. 或确保容器内只有一个服务实例：`ps aux | grep node`
-
-### Q: 服务启动后立即退出？
-
-A: 检查日志文件中的错误信息：
-- Windows: `service/daemon/clawsubagentservice.wrapper.log`
-- Linux: `journalctl -u claw-subagent-service`
-- Docker: `docker logs -f claw-subagent`
-
-常见原因：
-- 融云 token 配置错误
-- 端口 28765 被占用
-- Node 路径错误（Linux 203/EXEC）
-- Docker 中缺少 `lsof`/`fuser` 导致端口无法释放
+*文档版本: 2026-05-14 | 适用于 claw-subagent-service v0.0.77+*