@swarmclawai/swarmclaw 0.7.5 → 0.7.7

package/README.md

@@ -18,6 +18,7 @@ Inspired by [OpenClaw](https://github.com/openclaw).
 
 - [Getting Started](https://swarmclaw.ai/docs/getting-started) - install and first-run setup
 - [Providers](https://swarmclaw.ai/docs/providers) - provider setup and failover options
+- [OpenClaw Setup](https://swarmclaw.ai/docs/openclaw-setup) - local, VPS, and hosted OpenClaw deployment paths
 - [Agents](https://swarmclaw.ai/docs/agents) - agent configuration, tools, and platform capabilities
 - [Tools](https://swarmclaw.ai/docs/tools) - built-in tool reference and guardrails
 - [Orchestration](https://swarmclaw.ai/docs/orchestration) - multi-agent flows, checkpoints, and restore
@@ -39,11 +40,29 @@ SwarmClaw includes the `openclaw` CLI as a bundled dependency, so there is no se
 
 The Providers screen now supports named OpenClaw gateway profiles with discovery, health checks, default-gateway selection, and an External Agent Runtimes view for remote workers that register/heartbeat into SwarmClaw.
 
+SwarmClaw now also includes **Smart Deploy** for OpenClaw in three places:
+
+- **Onboarding** - non-technical users can launch a local OpenClaw runtime or generate a remote bundle before they finish first-run setup
+- **Providers -> OpenClaw Gateways** - operators can deploy or prepare more gateways later without leaving the main app
+- **Gateway editor** - every gateway profile includes the same deploy panel for local restarts, VPS bundles, and hosted repo-backed deployments
+
+The deployment flow stays **in-house and official-only**:
+
+- local deploys run the bundled official `openclaw` CLI directly from SwarmClaw
+- VPS deploys use the official OpenClaw Docker image with prefilled `.env`, `docker-compose.yml`, `bootstrap.sh`, and `cloud-init.yaml`
+- hosted templates target the official OpenClaw repo for Render, Fly.io, and Railway
+
+Supported VPS presets currently include Hetzner, DigitalOcean, Vultr, Linode, Lightsail, Google Cloud, Azure, OCI, and a generic Ubuntu host path. Smart defaults prefill the gateway token, endpoint, storage paths, and copy-paste commands so the resulting gateway can be saved into SwarmClaw with minimal manual editing.
+
+For existing hosts, SwarmClaw can also push the same official-image bundle **over SSH** and then keep remote lifecycle controls attached to that saved gateway profile: start, stop, restart, upgrade, backup, restore, and token rotation.
+
 The OpenClaw Control Plane in SwarmClaw adds:
 - Reload mode switching (`hot`, `hybrid`, `full`)
 - Config issue detection and guided repair
 - Remote history sync
 - Live execution approval handling
+- Gateway import/export JSON, clone flows, and richer external runtime fleet visibility
+- Agent and route-target preferences for steering work toward OpenClaw gateways by tags or use case (`local-dev`, `single-vps`, `private-tailnet`, `browser-heavy`, `team-control`)
 
 The Agent Inspector Panel lets you edit OpenClaw files (`SOUL.md`, `IDENTITY.md`, `USER.md`), tune personality/system behavior, and manage OpenClaw-compatible skills. SwarmClaw also supports importing OpenClaw `SKILL.md` files from URL.
 
@@ -59,6 +78,19 @@ Each agent can point to a **different** OpenClaw gateway profile or direct endpo
 
 URLs without a protocol are auto-prefixed with `http://`. For remote gateways with TLS, use `https://` explicitly.
 
+CLI operators can use the same deploy surface without opening the UI:
+
+```bash
+swarmclaw openclaw deploy-status
+swarmclaw openclaw deploy-local-start --data '{"port":18789}'
+swarmclaw openclaw deploy-local-restart --data '{"port":18789}'
+swarmclaw openclaw deploy-bundle --data '{"template":"docker","provider":"hetzner","target":"openclaw.example.com"}'
+swarmclaw openclaw deploy-ssh --data '{"target":"openclaw.example.com","provider":"hetzner","ssh":{"host":"your-vps-ip"}}'
+swarmclaw openclaw remote-backup --data '{"ssh":{"host":"your-vps-ip"}}'
+swarmclaw openclaw remote-restore --data '{"backupPath":"/opt/openclaw/backups/openclaw-backup-123.tgz","ssh":{"host":"your-vps-ip"}}'
+swarmclaw openclaw deploy-verify --data '{"endpoint":"https://openclaw.example.com/v1"}'
+```
+
 ## SwarmClaw ClawHub Skill
 
 Use the `swarmclaw` ClawHub skill when you want an OpenClaw agent to operate your SwarmClaw control plane directly from chat: list agents, dispatch tasks, check chats, run diagnostics, and coordinate multi-agent work.
@@ -78,7 +110,6 @@ Skill source and runbook: [`swarmclaw/SKILL.md`](swarmclaw/SKILL.md).
 
 ## Requirements
 
-- **Node.js** 22.6+
 - **Node.js** 22.6+
 - One of: **npm** 10+, **pnpm**, **Yarn**, or **Bun**
 - **Claude Code CLI** (optional, for `claude-cli` provider) — [Install](https://docs.anthropic.com/en/docs/claude-code/overview)
@@ -117,7 +148,7 @@ curl -fsSL https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/install.
 ```
 
 The installer resolves the latest stable release tag and installs that version by default.
-To pin a version: `SWARMCLAW_VERSION=v0.7.5 curl ... | bash`
+To pin a version: `SWARMCLAW_VERSION=v0.7.7 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -670,7 +701,7 @@ npm run update:easy     # safe update helper for local installs
 SwarmClaw uses tag-based releases (`vX.Y.Z`) as the stable channel.
 
 ```bash
-# example patch release (v0.7.5 style)
+# example patch release (v0.7.7 style)
 npm version patch
 git push origin main --follow-tags
 ```
@@ -680,15 +711,15 @@ On `v*` tags, GitHub Actions will:
 2. Create a GitHub Release
 3. Build and publish Docker images to `ghcr.io/swarmclawai/swarmclaw` (`:vX.Y.Z`, `:latest`, `:sha-*`)
 
-#### v0.7.5 Release Readiness Notes
+#### v0.7.7 Release Readiness Notes
 
-Before shipping `v0.7.5`, confirm the following user-facing changes are reflected in docs:
+Before shipping `v0.7.7`, confirm the following user-facing changes are reflected in docs:
 
-1. Sandbox docs are updated everywhere to reflect the current Deno-only `sandbox_exec` behavior and the guidance to prefer `http_request` for simple API calls.
-2. OpenClaw docs cover the current gateway/runtime behavior, including per-agent gateway routing, control-plane actions, and inspector-side advanced controls.
-3. Site and README install/version strings are updated to `v0.7.5`, including install snippets, release notes index text, and sidebar/footer labels.
-4. Release notes summarize the user-visible setup/auth/runtime changes from the current worktree, especially gateway/external-agent/setup flow improvements.
-5. CLI and tool docs do not reference removed or non-functional surfaces such as the old `openclaw_sandbox` bridge.
+1. OpenClaw docs cover Smart Deploy end-to-end: onboarding, Providers, gateway editor, official-only SSH/VPS flows, safe exposure presets, and restore/backup lifecycle controls.
+2. Agent and provider docs explain gateway routing by tags/use-case, richer external runtime visibility, and import/export/clone flows for saved gateways.
+3. Site and README install/version strings are updated to `v0.7.7`, including install snippets, release notes index text, and sidebar/footer labels.
+4. Release notes summarize the user-visible operator changes from the current worktree, especially SSH deploy, remote lifecycle controls, routing preferences, and onboarding persistence.
+5. CLI docs include the expanded `openclaw deploy-*`, `openclaw remote-*`, and verify surfaces and do not reference removed or unofficial deployment paths.
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Self-hosted AI agent orchestration dashboard — manage LLM providers, orchestrate agent swarms, schedule tasks, and bridge agents to chat platforms.",
   "license": "MIT",
   "publishConfig": {
@@ -57,7 +57,7 @@
     "lint:baseline:update": "node ./scripts/lint-baseline.mjs update",
     "cli": "node ./bin/swarmclaw.js",
     "test:cli": "node --test src/cli/*.test.js bin/*.test.js",
-    "test:openclaw": "tsx --test src/lib/openclaw-agent-id.test.ts src/lib/openclaw-endpoint.test.ts src/lib/server/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw-agent-resolver.test.ts src/lib/server/openclaw-skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/task-quality-gate.test.ts src/lib/server/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts",
+    "test:openclaw": "tsx --test src/lib/openclaw-agent-id.test.ts src/lib/openclaw-endpoint.test.ts src/lib/server/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw-agent-resolver.test.ts src/lib/server/openclaw-deploy.test.ts src/lib/server/openclaw-skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/task-quality-gate.test.ts src/lib/server/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",
     "postinstall": "node ./scripts/postinstall.mjs"
   },

package/src/app/api/agents/[id]/route.ts

@@ -23,6 +23,16 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
         body.apiEndpoint,
       )
     }
+    if (body.preferredGatewayTags !== undefined) {
+      agent.preferredGatewayTags = Array.isArray(body.preferredGatewayTags)
+        ? body.preferredGatewayTags.filter((tag: unknown): tag is string => typeof tag === 'string' && tag.trim().length > 0)
+        : []
+    }
+    if (body.preferredGatewayUseCase !== undefined) {
+      agent.preferredGatewayUseCase = typeof body.preferredGatewayUseCase === 'string' && body.preferredGatewayUseCase.trim()
+        ? body.preferredGatewayUseCase.trim()
+        : null
+    }
     if (body.routingTargets !== undefined && Array.isArray(body.routingTargets)) {
       agent.routingTargets = body.routingTargets.map((target: Record<string, unknown>, index: number) => ({
         id: typeof target.id === 'string' && target.id.trim() ? target.id.trim() : `route-${index + 1}`,
@@ -37,6 +47,12 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
           typeof target.apiEndpoint === 'string' ? target.apiEndpoint : null,
         ),
         gatewayProfileId: target.gatewayProfileId ?? null,
+        preferredGatewayTags: Array.isArray(target.preferredGatewayTags)
+          ? target.preferredGatewayTags.filter((tag: unknown): tag is string => typeof tag === 'string' && tag.trim().length > 0)
+          : [],
+        preferredGatewayUseCase: typeof target.preferredGatewayUseCase === 'string' && target.preferredGatewayUseCase.trim()
+          ? target.preferredGatewayUseCase.trim()
+          : null,
         priority: typeof target.priority === 'number' ? target.priority : index + 1,
       }))
     }

package/src/app/api/agents/route.ts

@@ -64,6 +64,8 @@ export async function POST(req: Request) {
     fallbackCredentialIds: body.fallbackCredentialIds,
     apiEndpoint: normalizeProviderEndpoint(body.provider, body.apiEndpoint || null),
     gatewayProfileId: body.gatewayProfileId,
+    preferredGatewayTags: body.preferredGatewayTags,
+    preferredGatewayUseCase: body.preferredGatewayUseCase,
     routingStrategy: body.routingStrategy,
     routingTargets: body.routingTargets?.map((target) => ({
       ...target,

package/src/app/api/chats/[id]/route.ts

@@ -18,7 +18,20 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
   }
 
   const linkedAgent = nextAgentId ? loadAgents()[nextAgentId] : null
-  const linkedRoute = linkedAgent ? resolvePrimaryAgentRoute(linkedAgent) : null
+  const routePreferredGatewayTags = updates.routePreferredGatewayTags !== undefined
+    ? (Array.isArray(updates.routePreferredGatewayTags)
+      ? updates.routePreferredGatewayTags.filter((tag: unknown): tag is string => typeof tag === 'string' && tag.trim().length > 0)
+      : [])
+    : (sessions[id].routePreferredGatewayTags || [])
+  const routePreferredGatewayUseCase = updates.routePreferredGatewayUseCase !== undefined
+    ? (typeof updates.routePreferredGatewayUseCase === 'string' && updates.routePreferredGatewayUseCase.trim()
+      ? updates.routePreferredGatewayUseCase.trim()
+      : null)
+    : (sessions[id].routePreferredGatewayUseCase || null)
+  const linkedRoute = linkedAgent ? resolvePrimaryAgentRoute(linkedAgent, undefined, {
+    preferredGatewayTags: routePreferredGatewayTags,
+    preferredGatewayUseCase: routePreferredGatewayUseCase,
+  }) : null
 
   if (updates.name !== undefined) sessions[id].name = updates.name
   if (updates.cwd !== undefined) sessions[id].cwd = updates.cwd
@@ -39,6 +52,13 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
   if (updates.gatewayProfileId !== undefined) sessions[id].gatewayProfileId = updates.gatewayProfileId
   else if (agentIdUpdateProvided && linkedRoute) sessions[id].gatewayProfileId = linkedRoute.gatewayProfileId ?? null
 
+  if (updates.routePreferredGatewayTags !== undefined) {
+    sessions[id].routePreferredGatewayTags = routePreferredGatewayTags
+  }
+  if (updates.routePreferredGatewayUseCase !== undefined) {
+    sessions[id].routePreferredGatewayUseCase = routePreferredGatewayUseCase
+  }
+
   if (updates.plugins !== undefined) sessions[id].plugins = updates.plugins
   else if (agentIdUpdateProvided && linkedAgent) sessions[id].plugins = Array.isArray(linkedAgent.plugins) ? linkedAgent.plugins : []
 

package/src/app/api/chats/route.ts

@@ -61,7 +61,16 @@ export async function POST(req: Request) {
   const id = body.id || genId()
   const sessions = loadSessions()
   const agent = body.agentId ? loadAgents()[body.agentId] : null
-  const resolvedRoute = agent ? resolvePrimaryAgentRoute(agent) : null
+  const routePreferredGatewayTags = Array.isArray(body.routePreferredGatewayTags)
+    ? body.routePreferredGatewayTags.filter((tag: unknown): tag is string => typeof tag === 'string' && tag.trim().length > 0)
+    : []
+  const routePreferredGatewayUseCase = typeof body.routePreferredGatewayUseCase === 'string' && body.routePreferredGatewayUseCase.trim()
+    ? body.routePreferredGatewayUseCase.trim()
+    : null
+  const resolvedRoute = agent ? resolvePrimaryAgentRoute(agent, undefined, {
+    preferredGatewayTags: routePreferredGatewayTags,
+    preferredGatewayUseCase: routePreferredGatewayUseCase,
+  }) : null
   const requestedPlugins = Array.isArray(body.plugins) ? body.plugins : (Array.isArray(body.tools) ? body.tools : null)
   const resolvedPlugins = requestedPlugins ?? (Array.isArray(agent?.plugins) ? agent.plugins : (Array.isArray(agent?.tools) ? agent.tools : []))
 
@@ -83,6 +92,8 @@ export async function POST(req: Request) {
       body.provider || agent?.provider || 'claude-cli',
       body.apiEndpoint || agent?.apiEndpoint || null,
     ),
+    routePreferredGatewayTags,
+    routePreferredGatewayUseCase,
     claudeSessionId: null,
     codexThreadId: null,
     opencodeSessionId: null,

package/src/app/api/external-agents/[id]/heartbeat/route.ts

@@ -15,6 +15,9 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
   runtime.lastSeenAt = now
   runtime.updatedAt = now
   runtime.status = body.status || 'online'
+  if (typeof body.lifecycleState === 'string' && body.lifecycleState) runtime.lifecycleState = body.lifecycleState
+  if (typeof body.version === 'string') runtime.version = body.version || null
+  if (typeof body.lastHealthNote === 'string') runtime.lastHealthNote = body.lastHealthNote || null
   if (body.tokenStats && typeof body.tokenStats === 'object') {
     runtime.tokenStats = {
       ...(runtime.tokenStats || {}),

package/src/app/api/external-agents/[id]/route.ts

@@ -10,12 +10,44 @@ const ops: CollectionOps<any> = { load: loadExternalAgents, save: saveExternalAg
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const body = await req.json().catch(() => ({}))
-  const result = mutateItem(ops, id, (runtime) => ({
-    ...runtime,
-    ...body,
-    id,
-    updatedAt: Date.now(),
-  }))
+  const now = Date.now()
+  const result = mutateItem(ops, id, (runtime) => {
+    const action = typeof body.action === 'string' ? body.action : ''
+    const nextMetadata = body.metadata && typeof body.metadata === 'object'
+      ? { ...(runtime.metadata || {}), ...body.metadata }
+      : runtime.metadata
+
+    const next = {
+      ...runtime,
+      ...body,
+      id,
+      metadata: nextMetadata,
+      updatedAt: now,
+    }
+
+    if (action === 'activate') {
+      next.lifecycleState = 'active'
+      next.lastHealthNote = body.lastHealthNote || 'Runtime returned to active service.'
+    } else if (action === 'drain') {
+      next.lifecycleState = 'draining'
+      next.lastHealthNote = body.lastHealthNote || 'Runtime draining after current work.'
+    } else if (action === 'cordon') {
+      next.lifecycleState = 'cordoned'
+      next.lastHealthNote = body.lastHealthNote || 'Runtime cordoned from new work.'
+    } else if (action === 'restart') {
+      next.metadata = {
+        ...(next.metadata || {}),
+        controlRequest: {
+          action: 'restart',
+          requestedAt: now,
+          source: 'swarmclaw',
+        },
+      }
+      next.lastHealthNote = body.lastHealthNote || 'Restart requested from SwarmClaw.'
+    }
+
+    return next
+  })
   if (!result) return notFound()
   return NextResponse.json(result)
 }

package/src/app/api/external-agents/route.ts

@@ -1,7 +1,7 @@
 import { NextResponse } from 'next/server'
 import { genId } from '@/lib/id'
 import { formatZodError, ExternalAgentRegisterSchema } from '@/lib/validation/schemas'
-import { loadExternalAgents, saveExternalAgents } from '@/lib/server/storage'
+import { loadExternalAgents, loadGatewayProfiles, saveExternalAgents } from '@/lib/server/storage'
 import { notify } from '@/lib/server/ws-hub'
 import type { ExternalAgentRuntime } from '@/types'
 import { z } from 'zod'
@@ -13,9 +13,20 @@ function withDerivedStatus(record: ExternalAgentRuntime): ExternalAgentRuntime {
   const staleMs = 3 * 60_000
   if (!lastSeenAt) return { ...record, status: record.status || 'offline' }
   if (record.status === 'offline') return record
+  const gateways = loadGatewayProfiles()
+  const gateway = record.gatewayProfileId ? gateways[record.gatewayProfileId] as Record<string, unknown> | undefined : undefined
+  const gatewayTags = Array.isArray(gateway?.tags)
+    ? gateway?.tags.filter((tag): tag is string => typeof tag === 'string' && tag.trim().length > 0)
+    : []
+  const gatewayUseCase = gateway?.deployment && typeof gateway.deployment === 'object' && typeof (gateway.deployment as Record<string, unknown>).useCase === 'string'
+    ? (gateway.deployment as Record<string, unknown>).useCase as string
+    : null
   return {
     ...record,
     status: now - lastSeenAt > staleMs ? 'stale' : (record.status || 'online'),
+    lifecycleState: record.lifecycleState || 'active',
+    gatewayTags: record.gatewayTags?.length ? record.gatewayTags : gatewayTags,
+    gatewayUseCase: record.gatewayUseCase || gatewayUseCase,
   }
 }
 
@@ -53,6 +64,11 @@ export async function POST(req: Request) {
     gatewayProfileId: body.gatewayProfileId || null,
     capabilities: body.capabilities,
     labels: body.labels,
+    lifecycleState: body.lifecycleState || existing?.lifecycleState || 'active',
+    gatewayTags: body.gatewayTags,
+    gatewayUseCase: body.gatewayUseCase || null,
+    version: body.version || null,
+    lastHealthNote: body.lastHealthNote || null,
     metadata: body.metadata,
     tokenStats: body.tokenStats,
     lastHeartbeatAt: existing?.lastHeartbeatAt || now,

package/src/app/api/gateways/[id]/health/route.ts

@@ -20,6 +20,14 @@ export async function GET(_req: Request, { params }: { params: Promise<{ id: str
   gateway.lastCheckedAt = Date.now()
   gateway.lastError = result.ok ? null : (result.error || result.hint || 'Gateway health check failed.')
   gateway.lastModelCount = Array.isArray(result.models) ? result.models.length : 0
+  gateway.deployment = {
+    ...(gateway.deployment || {}),
+    lastVerifiedAt: Date.now(),
+    lastVerifiedOk: result.ok,
+    lastVerifiedMessage: result.ok
+      ? `Verified ${Array.isArray(result.models) ? result.models.length : 0} model${result.models?.length === 1 ? '' : 's'}`
+      : (result.error || result.hint || 'Gateway health check failed.'),
+  }
   gateway.updatedAt = Date.now()
   saveGatewayProfiles(gateways)
   notify('gateways')

package/src/app/api/gateways/[id]/route.ts

@@ -2,7 +2,7 @@ import { NextResponse } from 'next/server'
 import { normalizeOpenClawEndpoint } from '@/lib/openclaw-endpoint'
 import { loadAgents, loadGatewayProfiles, saveAgents, saveGatewayProfiles } from '@/lib/server/storage'
 import { mutateItem, notFound, type CollectionOps } from '@/lib/server/collection-helpers'
-import type { Agent, AgentRoutingTarget, GatewayProfile } from '@/types'
+import type { Agent, AgentRoutingTarget, GatewayProfile, OpenClawDeploymentConfig, OpenClawGatewayStats } from '@/types'
 
 const ops: CollectionOps<GatewayProfile> = {
   load: loadGatewayProfiles,
@@ -17,6 +17,56 @@ function normalizeTags(value: unknown): string[] {
     .filter(Boolean)
 }
 
+function normalizeText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+function normalizeNullableNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+function normalizeDeployment(value: unknown): OpenClawDeploymentConfig | null {
+  if (!value || typeof value !== 'object') return null
+  const deployment = value as Record<string, unknown>
+  return {
+    method: normalizeText(deployment.method) as OpenClawDeploymentConfig['method'],
+    provider: normalizeText(deployment.provider) as OpenClawDeploymentConfig['provider'],
+    remoteTarget: normalizeText(deployment.remoteTarget) as OpenClawDeploymentConfig['remoteTarget'],
+    useCase: normalizeText(deployment.useCase) as OpenClawDeploymentConfig['useCase'],
+    exposure: normalizeText(deployment.exposure) as OpenClawDeploymentConfig['exposure'],
+    managedBy: normalizeText(deployment.managedBy) as OpenClawDeploymentConfig['managedBy'],
+    targetHost: normalizeText(deployment.targetHost),
+    sshHost: normalizeText(deployment.sshHost),
+    sshUser: normalizeText(deployment.sshUser),
+    sshPort: normalizeNullableNumber(deployment.sshPort),
+    sshKeyPath: normalizeText(deployment.sshKeyPath),
+    sshTargetDir: normalizeText(deployment.sshTargetDir),
+    image: normalizeText(deployment.image),
+    version: normalizeText(deployment.version),
+    lastDeployAt: normalizeNullableNumber(deployment.lastDeployAt),
+    lastDeployAction: normalizeText(deployment.lastDeployAction),
+    lastDeployProcessId: normalizeText(deployment.lastDeployProcessId),
+    lastDeploySummary: normalizeText(deployment.lastDeploySummary),
+    lastVerifiedAt: normalizeNullableNumber(deployment.lastVerifiedAt),
+    lastVerifiedOk: typeof deployment.lastVerifiedOk === 'boolean' ? deployment.lastVerifiedOk : null,
+    lastVerifiedMessage: normalizeText(deployment.lastVerifiedMessage),
+    lastBackupPath: normalizeText(deployment.lastBackupPath),
+  }
+}
+
+function normalizeStats(value: unknown): OpenClawGatewayStats | null {
+  if (!value || typeof value !== 'object') return null
+  const stats = value as Record<string, unknown>
+  return {
+    nodeCount: normalizeNullableNumber(stats.nodeCount) ?? undefined,
+    connectedNodeCount: normalizeNullableNumber(stats.connectedNodeCount) ?? undefined,
+    pendingNodePairings: normalizeNullableNumber(stats.pendingNodePairings) ?? undefined,
+    pairedDeviceCount: normalizeNullableNumber(stats.pairedDeviceCount) ?? undefined,
+    pendingDevicePairings: normalizeNullableNumber(stats.pendingDevicePairings) ?? undefined,
+    externalRuntimeCount: normalizeNullableNumber(stats.externalRuntimeCount) ?? undefined,
+  }
+}
+
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const body = await req.json().catch(() => ({}))
@@ -39,6 +89,8 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
     if (body.lastModelCount !== undefined) gateway.lastModelCount = body.lastModelCount || null
     if (body.discoveredHost !== undefined) gateway.discoveredHost = body.discoveredHost || null
     if (body.discoveredPort !== undefined) gateway.discoveredPort = body.discoveredPort || null
+    if (body.deployment !== undefined) gateway.deployment = { ...(gateway.deployment || {}), ...(normalizeDeployment(body.deployment) || {}) }
+    if (body.stats !== undefined) gateway.stats = { ...(gateway.stats || {}), ...(normalizeStats(body.stats) || {}) }
     if (body.isDefault !== undefined) gateway.isDefault = body.isDefault === true
     gateway.updatedAt = Date.now()
     return gateway

package/src/app/api/gateways/route.ts

@@ -4,6 +4,7 @@ import { normalizeOpenClawEndpoint } from '@/lib/openclaw-endpoint'
 import { getGatewayProfiles } from '@/lib/server/agent-runtime-config'
 import { loadGatewayProfiles, saveGatewayProfiles } from '@/lib/server/storage'
 import { notify } from '@/lib/server/ws-hub'
+import type { OpenClawDeploymentConfig, OpenClawGatewayStats } from '@/types'
 export const dynamic = 'force-dynamic'
 
 function normalizeTags(value: unknown): string[] {
@@ -13,6 +14,56 @@ function normalizeTags(value: unknown): string[] {
     .filter(Boolean)
 }
 
+function normalizeText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+function normalizeNullableNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+function normalizeDeployment(value: unknown): OpenClawDeploymentConfig | null {
+  if (!value || typeof value !== 'object') return null
+  const deployment = value as Record<string, unknown>
+  return {
+    method: normalizeText(deployment.method) as OpenClawDeploymentConfig['method'],
+    provider: normalizeText(deployment.provider) as OpenClawDeploymentConfig['provider'],
+    remoteTarget: normalizeText(deployment.remoteTarget) as OpenClawDeploymentConfig['remoteTarget'],
+    useCase: normalizeText(deployment.useCase) as OpenClawDeploymentConfig['useCase'],
+    exposure: normalizeText(deployment.exposure) as OpenClawDeploymentConfig['exposure'],
+    managedBy: normalizeText(deployment.managedBy) as OpenClawDeploymentConfig['managedBy'],
+    targetHost: normalizeText(deployment.targetHost),
+    sshHost: normalizeText(deployment.sshHost),
+    sshUser: normalizeText(deployment.sshUser),
+    sshPort: normalizeNullableNumber(deployment.sshPort),
+    sshKeyPath: normalizeText(deployment.sshKeyPath),
+    sshTargetDir: normalizeText(deployment.sshTargetDir),
+    image: normalizeText(deployment.image),
+    version: normalizeText(deployment.version),
+    lastDeployAt: normalizeNullableNumber(deployment.lastDeployAt),
+    lastDeployAction: normalizeText(deployment.lastDeployAction),
+    lastDeployProcessId: normalizeText(deployment.lastDeployProcessId),
+    lastDeploySummary: normalizeText(deployment.lastDeploySummary),
+    lastVerifiedAt: normalizeNullableNumber(deployment.lastVerifiedAt),
+    lastVerifiedOk: typeof deployment.lastVerifiedOk === 'boolean' ? deployment.lastVerifiedOk : null,
+    lastVerifiedMessage: normalizeText(deployment.lastVerifiedMessage),
+    lastBackupPath: normalizeText(deployment.lastBackupPath),
+  }
+}
+
+function normalizeStats(value: unknown): OpenClawGatewayStats | null {
+  if (!value || typeof value !== 'object') return null
+  const stats = value as Record<string, unknown>
+  return {
+    nodeCount: normalizeNullableNumber(stats.nodeCount) ?? undefined,
+    connectedNodeCount: normalizeNullableNumber(stats.connectedNodeCount) ?? undefined,
+    pendingNodePairings: normalizeNullableNumber(stats.pendingNodePairings) ?? undefined,
+    pairedDeviceCount: normalizeNullableNumber(stats.pairedDeviceCount) ?? undefined,
+    pendingDevicePairings: normalizeNullableNumber(stats.pendingDevicePairings) ?? undefined,
+    externalRuntimeCount: normalizeNullableNumber(stats.externalRuntimeCount) ?? undefined,
+  }
+}
+
 export async function GET() {
   return NextResponse.json(getGatewayProfiles('openclaw'))
 }
@@ -46,6 +97,8 @@ export async function POST(req: Request) {
     lastModelCount: null,
     discoveredHost: typeof body.discoveredHost === 'string' ? body.discoveredHost : null,
     discoveredPort: typeof body.discoveredPort === 'number' ? body.discoveredPort : null,
+    deployment: normalizeDeployment(body.deployment),
+    stats: normalizeStats(body.stats),
     isDefault,
     createdAt: now,
     updatedAt: now,