@swarmclawai/swarmclaw 0.2.0 → 0.3.0

package/README.md

@@ -206,7 +206,7 @@ To connect an agent to an OpenClaw gateway:
 2. Toggle **OpenClaw Gateway** ON
 3. Enter the gateway URL (e.g. `http://192.168.1.50:18789` or `https://my-vps:18789`)
 4. Add a gateway token if authentication is enabled on the remote gateway
-5. Click **Test & Save** to verify the connection
+5. Click **Connect** — approve the device in your gateway's dashboard if prompted, then **Retry Connection**
 
 Each agent can point to a **different** OpenClaw gateway — one local, several remote. This is how you manage a **swarm of OpenClaws** from a single dashboard.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Self-hosted AI agent orchestration dashboard — manage LLM providers, orchestrate agent swarms, schedule tasks, and bridge agents to chat platforms.",
   "license": "MIT",
   "repository": {

package/src/app/api/setup/check-provider/route.ts

@@ -1,8 +1,6 @@
 import { NextResponse } from 'next/server'
-import { WebSocket } from 'ws'
-import { randomUUID } from 'crypto'
 import { loadCredentials, decryptKey } from '@/lib/server/storage'
-import { buildOpenClawConnectParams, getDeviceId } from '@/lib/providers/openclaw'
+import { getDeviceId, wsConnect } from '@/lib/providers/openclaw'
 
 type SetupProvider =
   | 'openai'
@@ -159,103 +157,16 @@ async function checkOpenClaw(apiKey: string, endpointRaw: string): Promise<{ ok:
   const token = apiKey || undefined
   const deviceId = getDeviceId()
 
-  // Always connect with device auth — the gateway may accept token-only for
-  // the connect handshake but still require device identity for agent ops.
-  const result = await attemptOpenClawConnect(wsUrl, token, true)
+  const result = await wsConnect(wsUrl, token, true, 10_000)
+  // Close the WebSocket immediately — we only care about the handshake result
+  if (result.ws) try { result.ws.close() } catch {}
+
   if (result.ok) {
     return { ok: true, message: 'Connected to OpenClaw gateway.', normalizedEndpoint, deviceId }
   }
-  if (result.errorCode === 'PAIRING_REQUIRED') {
-    return {
-      ok: false,
-      errorCode: 'PAIRING_REQUIRED',
-      message: 'Device needs approval on your gateway.',
-      normalizedEndpoint,
-      deviceId,
-    }
-  }
-  if (result.errorCode === 'DEVICE_AUTH_INVALID') {
-    return {
-      ok: false,
-      errorCode: 'DEVICE_AUTH_INVALID',
-      message: 'Device signature rejected. Your gateway may be running a different protocol version.',
-      normalizedEndpoint,
-      deviceId,
-    }
-  }
   return { ok: false, message: result.message, normalizedEndpoint, deviceId, errorCode: result.errorCode }
 }
 
-function attemptOpenClawConnect(
-  wsUrl: string,
-  token: string | undefined,
-  useDeviceAuth: boolean,
-): Promise<{ ok: boolean; message: string; errorCode?: string }> {
-  return new Promise((resolve) => {
-    let settled = false
-    const done = (result: { ok: boolean; message: string; errorCode?: string }) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      try { ws.close() } catch {}
-      resolve(result)
-    }
-
-    const timer = setTimeout(() => {
-      done({ ok: false, message: 'Connection timed out. Verify the gateway URL and network access.' })
-    }, 10_000)
-
-    const ws = new WebSocket(wsUrl)
-    let connectId: string | null = null
-
-    ws.on('message', (data) => {
-      try {
-        const msg = JSON.parse(data.toString())
-        if (msg.event === 'connect.challenge') {
-          connectId = randomUUID()
-          ws.send(JSON.stringify({
-            type: 'req',
-            id: connectId,
-            method: 'connect',
-            params: buildOpenClawConnectParams(token, msg.payload?.nonce, { useDeviceAuth }),
-          }))
-          return
-        }
-        if (msg.type === 'res' && msg.id === connectId) {
-          if (msg.ok) {
-            done({ ok: true, message: 'Connected.' })
-          } else {
-            const message = msg.error?.message || 'Gateway rejected the connection.'
-            // Extract error code from structured field or infer from message text
-            let errorCode = (msg.error?.details?.code ?? msg.error?.code) as string | undefined
-            if (!errorCode) {
-              const m = message.toLowerCase()
-              if (m.includes('pairing') || m.includes('not paired') || m.includes('pending approval')) errorCode = 'PAIRING_REQUIRED'
-              else if (m.includes('signature') || m.includes('device') || m.includes('identity')) errorCode = 'DEVICE_AUTH_INVALID'
-            }
-            done({ ok: false, message, errorCode })
-          }
-          return
-        }
-      } catch {
-        done({ ok: false, message: 'Unexpected response from gateway.' })
-      }
-    })
-
-    ws.on('error', (err) => {
-      done({ ok: false, message: `Connection failed: ${err.message}` })
-    })
-
-    ws.on('close', (code, reason) => {
-      if (code === 1008) {
-        done({ ok: false, message: `Unauthorized: ${reason?.toString() || 'invalid token'}` })
-      } else {
-        done({ ok: false, message: `Connection closed (${code})` })
-      }
-    })
-  })
-}
-
 export async function POST(req: Request) {
   const body = parseBody(await req.json().catch(() => ({})))
   const provider = clean(body.provider) as SetupProvider

package/src/app/api/setup/openclaw-device/route.ts

@@ -0,0 +1,11 @@
+import { NextResponse } from 'next/server'
+import { getDeviceId } from '@/lib/providers/openclaw'
+
+export async function GET() {
+  try {
+    const deviceId = getDeviceId()
+    return NextResponse.json({ deviceId })
+  } catch (err: any) {
+    return NextResponse.json({ deviceId: null, error: err?.message }, { status: 500 })
+  }
+}

package/src/components/agents/agent-sheet.tsx

@@ -101,6 +101,8 @@ export function AgentSheet() {
   const [testMessage, setTestMessage] = useState('')
   const [testErrorCode, setTestErrorCode] = useState<string | null>(null)
   const [testDeviceId, setTestDeviceId] = useState<string | null>(null)
+  const [openclawDeviceId, setOpenclawDeviceId] = useState<string | null>(null)
+  const [configCopied, setConfigCopied] = useState(false)
 
   const soulFileRef = useRef<HTMLInputElement>(null)
   const promptFileRef = useRef<HTMLInputElement>(null)
@@ -234,6 +236,16 @@ export function AgentSheet() {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [mcpServerIds.join(',')])
 
+  // Fetch OpenClaw device ID when toggle is enabled
+  useEffect(() => {
+    if (!openclawEnabled) return
+    let cancelled = false
+    api<{ deviceId: string }>('GET', '/setup/openclaw-device').then((res) => {
+      if (!cancelled && res.deviceId) setOpenclawDeviceId(res.deviceId)
+    }).catch(() => {})
+    return () => { cancelled = true }
+  }, [openclawEnabled])
+
   const handleGenerate = async () => {
     if (!aiPrompt.trim()) return
     setGenerating(true)
@@ -380,8 +392,10 @@ export function AgentSheet() {
     if (needsTest) {
       const passed = await handleTestConnection()
       if (!passed) return
-      // Brief pause so the user can see the success state on the button
-      await new Promise((r) => setTimeout(r, 1500))
+      if (!openclawEnabled) {
+        // Brief pause so the user can see the success state on the button
+        await new Promise((r) => setTimeout(r, 1500))
+      }
     }
     setSaving(true)
     await handleSave()
@@ -400,15 +414,44 @@ export function AgentSheet() {
 
   return (
     <BottomSheet open={open} onClose={onClose} wide>
-      <div className="mb-10">
-        <h2 className="font-display text-[28px] font-700 tracking-[-0.03em] mb-2">
-          {editing ? 'Edit Agent' : 'New Agent'}
-        </h2>
-        <p className="text-[14px] text-text-3">Define an AI agent or orchestrator</p>
+      <div className="mb-10 flex items-start justify-between">
+        <div>
+          <h2 className="font-display text-[28px] font-700 tracking-[-0.03em] mb-2">
+            {editing ? 'Edit Agent' : 'New Agent'}
+          </h2>
+          <p className="text-[14px] text-text-3">Define an AI agent or orchestrator</p>
+        </div>
+        <div className="flex items-center gap-3 mt-1.5">
+          <label className="text-[11px] font-600 text-text-3 uppercase tracking-[0.08em]">OpenClaw</label>
+          <button
+            type="button"
+            onClick={() => {
+              if (!openclawEnabled) {
+                setOpenclawEnabled(true)
+                setProvider('openclaw')
+                setModel('default')
+                if (!apiEndpoint) setApiEndpoint('http://localhost:18789')
+              } else {
+                setOpenclawEnabled(false)
+                const first = providers[0]?.id || 'claude-cli'
+                setProvider(first)
+                setModel('')
+                setApiEndpoint(null)
+                setCredentialId(null)
+                setTestStatus('idle')
+                setTestMessage('')
+                setTestErrorCode(null)
+              }
+            }}
+            className={`relative w-11 h-6 rounded-full transition-colors duration-200 cursor-pointer border-none ${openclawEnabled ? 'bg-accent-bright' : 'bg-white/[0.12]'}`}
+          >
+            <span className={`absolute top-0.5 left-0.5 w-5 h-5 rounded-full bg-white transition-transform duration-200 ${openclawEnabled ? 'translate-x-5' : 'translate-x-0'}`} />
+          </button>
+        </div>
       </div>
 
       {/* AI Generation */}
-      {!editing && <AiGenBlock
+      {!editing && !openclawEnabled && <AiGenBlock
         aiPrompt={aiPrompt} setAiPrompt={setAiPrompt}
         generating={generating} generated={generated} genError={genError}
         onGenerate={handleGenerate} appSettings={appSettings}
@@ -425,8 +468,8 @@ export function AgentSheet() {
         <input type="text" value={description} onChange={(e) => setDescription(e.target.value)} placeholder="What does this agent do?" className={inputClass} style={{ fontFamily: 'inherit' }} />
       </div>
 
-      {/* Capabilities */}
-      <div className="mb-8">
+      {/* Capabilities — hidden for OpenClaw (gateway manages its own capabilities) */}
+      {!openclawEnabled && <div className="mb-8">
         <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em] mb-3">
           Capabilities <span className="normal-case tracking-normal font-normal text-text-3">(for agent delegation)</span>
         </label>
@@ -467,7 +510,7 @@ export function AgentSheet() {
           />
         </div>
         <p className="text-[11px] text-text-3/70 mt-1.5">Press Enter or comma to add. Other agents see these when deciding delegation.</p>
-      </div>
+      </div>}
 
       {provider !== 'openclaw' && (
         <div className="mb-8">
@@ -508,35 +551,13 @@ export function AgentSheet() {
         </div>
       )}
 
-      {/* OpenClaw Gateway Toggle */}
-      <div className="mb-8">
-        <div className="flex items-center justify-between">
-          <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em]">OpenClaw Gateway</label>
-          <button
-            type="button"
-            onClick={() => {
-              if (!openclawEnabled) {
-                setOpenclawEnabled(true)
-                setProvider('openclaw')
-                setModel('default')
-                if (!apiEndpoint) setApiEndpoint('http://localhost:18789')
-              } else {
-                setOpenclawEnabled(false)
-                setProvider('claude-cli')
-                setModel('')
-                setApiEndpoint(null)
-                setCredentialId(null)
-              }
-            }}
-            className={`relative w-11 h-6 rounded-full transition-colors duration-200 cursor-pointer border-none ${openclawEnabled ? 'bg-accent-bright' : 'bg-white/[0.12]'}`}
-          >
-            <span className={`absolute top-0.5 left-0.5 w-5 h-5 rounded-full bg-white transition-transform duration-200 ${openclawEnabled ? 'translate-x-5' : 'translate-x-0'}`} />
-          </button>
-        </div>
-        {openclawEnabled && (
-          <div className="mt-4 space-y-4">
+      {/* OpenClaw Gateway Fields */}
+      {openclawEnabled && (
+        <div className="mb-8 space-y-5">
+          {/* Connection fields */}
+          <div className="space-y-4">
             <div>
-              <label className="block text-[12px] text-text-3 mb-2">Gateway URL</label>
+              <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em] mb-2">Gateway URL</label>
               <input
                 type="text"
                 value={apiEndpoint || ''}
@@ -547,7 +568,7 @@ export function AgentSheet() {
               />
             </div>
             <div>
-              <label className="block text-[12px] text-text-3 mb-2">Gateway Token</label>
+              <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em] mb-2">Gateway Token</label>
               {openclawCredentials.length > 0 && !addingKey ? (
                 <div className="flex gap-2">
                   <select value={credentialId || ''} onChange={(e) => {
@@ -559,7 +580,7 @@ export function AgentSheet() {
                       setCredentialId(e.target.value || null)
                     }
                   }} className={`${inputClass} appearance-none cursor-pointer flex-1`} style={{ fontFamily: 'inherit' }}>
-                    <option value="">Select a token...</option>
+                    <option value="">No token (auth disabled)</option>
                     {openclawCredentials.map((c) => (
                       <option key={c.id} value={c.id}>{c.name}</option>
                     ))}
@@ -574,12 +595,12 @@ export function AgentSheet() {
                   </button>
                 </div>
               ) : (
-                <div className="space-y-3 p-4 rounded-[12px] border border-accent-bright/15 bg-accent-soft/20">
+                <div className="space-y-3 p-4 rounded-[12px] border border-accent-bright/15 bg-accent-soft/10">
                   <input
                     type="text"
                     value={newKeyName}
                     onChange={(e) => setNewKeyName(e.target.value)}
-                    placeholder="Token name (optional)"
+                    placeholder="Label (e.g. Local gateway)"
                     className={inputClass}
                     style={{ fontFamily: 'inherit' }}
                   />
@@ -619,85 +640,108 @@ export function AgentSheet() {
                 </div>
               )}
             </div>
-            <p className="text-[11px] text-text-3/70">Enter the URL and token for your local or remote OpenClaw gateway.</p>
-            {/* Insecure connection warning */}
-            {(() => {
-              const url = (apiEndpoint || '').trim().toLowerCase()
-              const isRemote = url && !/localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]/i.test(url)
-              const isSecure = /^(https|wss):\/\//i.test(url)
-              if (isRemote && !isSecure) return (
-                <div className="mt-3 p-3 rounded-[10px] bg-[#fbbf24]/10 border border-[#fbbf24]/30">
-                  <p className="text-[11px] text-[#fbbf24] font-500 leading-[1.5]">
-                    This connection is not encrypted. Credentials and chat data could be intercepted on the network.
-                    For production use, put your gateway behind HTTPS (e.g. Caddy, nginx) or use an SSH tunnel.
-                  </p>
-                </div>
-              )
-              return null
-            })()}
-            {/* OpenClaw troubleshooting — shown on any test failure */}
-            {testStatus === 'fail' && openclawEnabled && (
-              <div className="mt-3 p-4 rounded-[12px] bg-accent-soft/30 border border-accent-bright/20">
-                {testErrorCode === 'PAIRING_REQUIRED' ? (
-                  <div className="space-y-2">
-                    <p className="text-[12px] text-accent-bright font-600 mb-1">Device Pairing Required</p>
-                    <p className="text-[11px] text-text-3 leading-[1.6]">
-                      Your gateway needs to approve this SwarmClaw instance before it can connect. Follow these steps:
-                    </p>
-                    <ol className="text-[11px] text-text-3 leading-[1.8] list-decimal list-inside space-y-1">
-                      <li>Open your OpenClaw control UI at <span className="text-accent-bright font-500">{apiEndpoint || 'http://localhost:18789'}</span></li>
-                      <li>Go to <span className="text-text-2 font-500">Devices</span></li>
-                      <li>Find and approve the pending device {testDeviceId ? <span className="text-text-2 font-mono text-[10px]">({testDeviceId.slice(0, 12)}...)</span> : null}</li>
-                      <li>Come back here and click <span className="text-text-2 font-500">Test &amp; Save</span> again</li>
-                    </ol>
-                  </div>
-                ) : testErrorCode === 'DEVICE_AUTH_INVALID' ? (
-                  <div className="space-y-2">
-                    <p className="text-[12px] text-accent-bright font-600 mb-1">Device Authentication Failed</p>
-                    <p className="text-[11px] text-text-3 leading-[1.6]">
-                      The gateway rejected this device&apos;s signature. This usually means it needs to be paired first, or there&apos;s a protocol mismatch.
-                    </p>
-                    <p className="text-[11px] text-text-3 font-500 mt-2 mb-1">Try these steps:</p>
-                    <ol className="text-[11px] text-text-3 leading-[1.8] list-decimal list-inside space-y-1">
-                      <li>Open your OpenClaw control UI at <span className="text-accent-bright font-500">{apiEndpoint || 'http://localhost:18789'}</span></li>
-                      <li>Go to <span className="text-text-2 font-500">Devices</span> and look for a pending device request</li>
-                      <li>If the device is listed, approve it and click <span className="text-text-2 font-500">Test &amp; Save</span> again</li>
-                      <li>If not listed, update your gateway to the latest version and restart it</li>
-                    </ol>
-                  </div>
-                ) : (
-                  <div className="space-y-2">
-                    <p className="text-[12px] text-accent-bright font-600 mb-1">Connection Failed</p>
-                    <p className="text-[11px] text-text-3 leading-[1.6]">
-                      Could not connect to the OpenClaw gateway. Check the following:
-                    </p>
-                    <ul className="text-[11px] text-text-3 leading-[1.8] list-disc list-inside space-y-1">
-                      <li>The gateway is running and reachable at the URL above</li>
-                      <li>The gateway token matches exactly (if required)</li>
-                      <li>No firewall is blocking the connection</li>
-                    </ul>
-                  </div>
-                )}
-                {testDeviceId && (
-                  <div className="mt-3 pt-3 border-t border-white/[0.06]">
-                    <p className="text-[10px] text-text-3/60">
-                      SwarmClaw Device ID: <span className="font-mono text-text-3/80 select-all">{testDeviceId}</span>
-                    </p>
-                  </div>
-                )}
-              </div>
-            )}
-            {/* Device ID info — shown after any successful OpenClaw test */}
-            {testStatus === 'pass' && openclawEnabled && testDeviceId && (
-              <div className="mt-3 px-3 py-2 rounded-[10px] bg-emerald-500/[0.06] border border-emerald-500/15">
-                <p className="text-[10px] text-text-3/60">
-                  Device ID: <span className="font-mono text-emerald-400/70 select-all">{testDeviceId.slice(0, 16)}...</span>
+          </div>
+
+          {/* Insecure connection warning */}
+          {(() => {
+            const url = (apiEndpoint || '').trim().toLowerCase()
+            const isRemote = url && !/localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]/i.test(url)
+            const isSecure = /^(https|wss):\/\//i.test(url)
+            if (isRemote && !isSecure) return (
+              <div className="px-3 py-2.5 rounded-[10px] bg-[#fbbf24]/[0.06] border border-[#fbbf24]/20">
+                <p className="text-[13px] text-[#fbbf24] leading-[1.5]">
+                  Unencrypted connection. Use HTTPS or an SSH tunnel for production.
                 </p>
               </div>
-            )}
-          </div>
-        )}
-      </div>
+            )
+            return null
+          })()}
+
+          {/* Status feedback — single unified block */}
+          {testStatus === 'pass' && (
+            <div className="p-4 rounded-[12px] bg-emerald-500/[0.06] border border-emerald-500/15 space-y-2">
+              <div className="flex items-center gap-2">
+                <span className="w-2 h-2 rounded-full bg-emerald-400" />
+                <p className="text-[14px] text-emerald-400 font-600">Connected</p>
+              </div>
+              <p className="text-[13px] text-text-2/80 leading-[1.6]">Gateway is reachable and this device is paired. Tools and models are managed by the OpenClaw instance.</p>
+            </div>
+          )}
+          {testStatus === 'fail' && (
+            <div className="p-4 rounded-[12px] border space-y-3"
+              style={{
+                background: testErrorCode === 'PAIRING_REQUIRED' ? 'rgba(34,197,94,0.04)' : 'rgba(var(--accent-bright-rgb,120,100,255),0.06)',
+                borderColor: testErrorCode === 'PAIRING_REQUIRED' ? 'rgba(34,197,94,0.2)' : 'rgba(var(--accent-bright-rgb,120,100,255),0.15)',
+              }}
+            >
+              {testErrorCode === 'PAIRING_REQUIRED' ? (<>
+                <div className="flex items-center gap-2">
+                  <span className="w-2 h-2 rounded-full bg-emerald-400 animate-pulse" />
+                  <p className="text-[14px] text-[#22c55e] font-600">Awaiting Approval</p>
+                </div>
+                <p className="text-[13px] text-text-2/80 leading-[1.6]">
+                  This device is pending approval on your gateway. Go to <span className="text-text-2 font-500">Nodes</span>, approve the device{(testDeviceId || openclawDeviceId) ? <> (<code className="text-[12px] font-mono text-text-2/70">{(testDeviceId || openclawDeviceId)!.slice(0, 12)}...</code>)</> : null}, then click <span className="text-text-2 font-500">Retry Connection</span>.
+                </p>
+                <a
+                  href={(() => { const ep = (apiEndpoint || 'http://localhost:18789').replace(/\/+$/, ''); return /^https?:\/\//i.test(ep) ? ep : `http://${ep}` })()}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center gap-1.5 mt-2 px-4 py-2 rounded-[10px] bg-white/[0.06] border border-white/[0.1] text-[13px] text-text-2 font-500 hover:bg-white/[0.1] transition-colors"
+                >
+                  Approve in Dashboard →
+                </a>
+              </>) : testErrorCode === 'DEVICE_AUTH_INVALID' ? (<>
+                <p className="text-[14px] text-accent-bright font-600">Device Not Paired</p>
+                <p className="text-[13px] text-text-2/80 leading-[1.6]">
+                  The gateway doesn&apos;t recognize this device. Go to <span className="text-text-2 font-500">Nodes</span>, and add or approve this device{(testDeviceId || openclawDeviceId) ? <> (<code className="text-[12px] font-mono text-text-2/70">{(testDeviceId || openclawDeviceId)!.slice(0, 12)}...</code>)</> : null}.
+                </p>
+                <a
+                  href={(() => { const ep = (apiEndpoint || 'http://localhost:18789').replace(/\/+$/, ''); return /^https?:\/\//i.test(ep) ? ep : `http://${ep}` })()}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center gap-1.5 mt-2 px-4 py-2 rounded-[10px] bg-white/[0.06] border border-white/[0.1] text-[13px] text-text-2 font-500 hover:bg-white/[0.1] transition-colors"
+                >
+                  Approve in Dashboard →
+                </a>
+              </>) : testErrorCode === 'AUTH_TOKEN_MISSING' ? (<>
+                <p className="text-[14px] text-accent-bright font-600">Token Required</p>
+                <p className="text-[13px] text-text-2/80 leading-[1.6]">
+                  This gateway requires an auth token. Add one above and try again.
+                </p>
+              </>) : testErrorCode === 'AUTH_TOKEN_INVALID' ? (<>
+                <p className="text-[14px] text-accent-bright font-600">Invalid Token</p>
+                <p className="text-[13px] text-text-2/80 leading-[1.6]">
+                  The gateway rejected this token. Check that it matches the one configured on your OpenClaw instance.
+                </p>
+              </>) : (<>
+                <p className="text-[14px] text-accent-bright font-600">Connection Failed</p>
+                <p className="text-[13px] text-text-2/80 leading-[1.6]">
+                  {testMessage || 'Could not reach the gateway. Check the URL, token, and that the gateway is running.'}
+                </p>
+              </>)}
+              {/* Device ID footer — always shown on failure for debugging */}
+              {(testDeviceId || openclawDeviceId) && testErrorCode !== 'AUTH_TOKEN_MISSING' && testErrorCode !== 'AUTH_TOKEN_INVALID' && (
+                <div className="pt-2 border-t border-white/[0.04]">
+                  <p className="text-[12px] text-text-3/70 flex items-center gap-1.5">
+                    Device <code className="font-mono text-text-2/70 select-all">{(testDeviceId || openclawDeviceId)}</code>
+                    <button
+                      type="button"
+                      onClick={() => {
+                        navigator.clipboard.writeText((testDeviceId || openclawDeviceId)!)
+                        setConfigCopied(true)
+                        setTimeout(() => setConfigCopied(false), 2000)
+                      }}
+                      className="text-[12px] text-text-3/60 hover:text-text-3/80 transition-colors cursor-pointer bg-transparent border-none"
+                    >
+                      {configCopied ? 'copied' : 'copy'}
+                    </button>
+                  </p>
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      )}
 
       {!openclawEnabled && <div className="mb-8">
         <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em] mb-3">Provider</label>
@@ -883,7 +927,7 @@ export function AgentSheet() {
           </label>
           <input type="text" value={apiEndpoint || ''} onChange={(e) => setApiEndpoint(e.target.value || null)} placeholder={currentProvider.defaultEndpoint || 'http://localhost:11434'} className={`${inputClass} font-mono text-[14px]`} />
           {provider === 'openclaw' && (
-            <p className="text-[11px] text-text-3/60 mt-2">The /v1 endpoint of your remote OpenClaw instance</p>
+            <p className="text-[13px] text-text-3/70 mt-2">The URL of your OpenClaw gateway</p>
           )}
         </div>
       )}
@@ -952,17 +996,15 @@ export function AgentSheet() {
         </div>
       )}
 
-      {/* Native capability provider note */}
-      {hasNativeCapabilities && (
+      {/* Native capability provider note — not shown for OpenClaw (covered in connection status) */}
+      {hasNativeCapabilities && !openclawEnabled && (
         <div className="mb-8 p-4 rounded-[14px] bg-white/[0.02] border border-white/[0.06]">
           <p className="text-[13px] text-text-3">
-            {provider === 'openclaw'
-              ? 'OpenClaw manages tools/platform capabilities in the remote OpenClaw instance — no local tool toggles are applied here.'
-              : provider === 'claude-cli'
-                ? 'Claude CLI uses its own built-in capabilities — no additional local tool/platform configuration is needed.'
-                : provider === 'codex-cli'
-                  ? 'OpenAI Codex CLI uses its own built-in tools (shell, files, etc.) — no additional local tool configuration needed.'
-                  : 'OpenCode CLI uses its own built-in tools (shell, files, etc.) — no additional local tool configuration needed.'}
+            {provider === 'claude-cli'
+              ? 'Claude CLI uses its own built-in capabilities — no additional local tool/platform configuration is needed.'
+              : provider === 'codex-cli'
+                ? 'OpenAI Codex CLI uses its own built-in tools (shell, files, etc.) — no additional local tool configuration needed.'
+                : 'OpenCode CLI uses its own built-in tools (shell, files, etc.) — no additional local tool configuration needed.'}
           </p>
         </div>
       )}
@@ -1171,13 +1213,13 @@ export function AgentSheet() {
         </div>
       )}
 
-      {/* Test connection result */}
-      {testStatus === 'fail' && (
+      {/* Test connection result (hidden for OpenClaw — inline status block handles it) */}
+      {!openclawEnabled && testStatus === 'fail' && (
         <div className="mb-4 p-3 rounded-[12px] bg-red-500/[0.08] border border-red-500/20">
           <p className="text-[13px] text-red-400">{testMessage || 'Connection test failed'}</p>
         </div>
       )}
-      {testStatus === 'pass' && (
+      {!openclawEnabled && testStatus === 'pass' && (
         <div className="mb-4 p-3 rounded-[12px] bg-emerald-500/[0.08] border border-emerald-500/20">
           <p className="text-[13px] text-emerald-400">{testMessage || 'Connected successfully'}</p>
         </div>
@@ -1207,12 +1249,18 @@ export function AgentSheet() {
         </button>
         <button
           onClick={handleTestAndSave}
-          disabled={!name.trim() || providerNeedsKey || testStatus === 'testing' || testStatus === 'pass' || saving}
+          disabled={!name.trim() || providerNeedsKey || testStatus === 'testing' || saving || (!openclawEnabled && testStatus === 'pass')}
           className={`flex-1 py-3.5 rounded-[14px] border-none text-white text-[15px] font-600 cursor-pointer active:scale-[0.97] disabled:opacity-60 transition-all hover:brightness-110
             ${testStatus === 'pass' ? 'bg-emerald-600 shadow-[0_4px_20px_rgba(16,185,129,0.25)]' : 'bg-[#6366F1] shadow-[0_4px_20px_rgba(99,102,241,0.25)]'}`}
           style={{ fontFamily: 'inherit' }}
         >
-          {testStatus === 'testing' ? 'Testing...' : testStatus === 'pass' ? (saving ? 'Saving...' : 'Connected!') : needsTest ? 'Test & Save' : editing ? 'Save' : 'Create'}
+          {openclawEnabled
+            ? (testStatus === 'testing' ? 'Connecting...'
+              : testStatus === 'pass' ? (saving ? 'Saving...' : 'Save')
+              : testStatus === 'fail' && testErrorCode === 'PAIRING_REQUIRED' ? 'Retry Connection'
+              : testStatus === 'fail' ? 'Retry'
+              : 'Connect')
+            : (testStatus === 'testing' ? 'Testing...' : testStatus === 'pass' ? (saving ? 'Saving...' : 'Connected!') : needsTest ? 'Test & Save' : editing ? 'Save' : 'Create')}
         </button>
       </div>
     </BottomSheet>

package/src/lib/providers/index.ts

@@ -65,7 +65,8 @@ const PROVIDERS: Record<string, BuiltinProviderConfig> = {
     id: 'openclaw',
     name: 'OpenClaw',
     models: ['default'],
-    requiresApiKey: true,
+    requiresApiKey: false,
+    optionalApiKey: true,
     requiresEndpoint: true,
     defaultEndpoint: 'http://localhost:18789',
     handler: { streamChat: streamOpenClawChat },

package/src/lib/providers/openclaw.ts

@@ -30,23 +30,50 @@ interface DeviceIdentity {
   privateKeyPem: string
 }
 
-function getIdentityPath(): string {
+/** Resolve the openclaw CLI's state directory (~/.openclaw by default). */
+function resolveCliStateDir(): string {
+  const override = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim()
+  if (override) return path.resolve(override.replace(/^~/, process.env.HOME || ''))
+  const home = process.env.HOME || process.env.USERPROFILE || ''
+  // Check new path first, then legacy
+  const newDir = path.join(home, '.openclaw')
+  if (fs.existsSync(newDir)) return newDir
+  const legacyDir = path.join(home, '.clawdbot')
+  if (fs.existsSync(legacyDir)) return legacyDir
+  return newDir
+}
+
+function getSwarmClawIdentityPath(): string {
   const dataDir = path.join(process.cwd(), 'data')
   if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true })
   return path.join(dataDir, 'openclaw-device.json')
 }
 
-function loadOrCreateDeviceIdentity(): DeviceIdentity {
-  const filePath = getIdentityPath()
+function tryLoadIdentityFile(filePath: string): DeviceIdentity | null {
   try {
-    if (fs.existsSync(filePath)) {
-      const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'))
-      if (parsed?.deviceId && parsed?.publicKeyPem && parsed?.privateKeyPem) {
-        return parsed
-      }
+    if (!fs.existsSync(filePath)) return null
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'))
+    if (parsed?.publicKeyPem && parsed?.privateKeyPem) {
+      // Re-derive deviceId from public key (matches CLI behavior)
+      const derivedId = fingerprintPublicKey(parsed.publicKeyPem)
+      return { deviceId: derivedId, publicKeyPem: parsed.publicKeyPem, privateKeyPem: parsed.privateKeyPem }
     }
   } catch {}
+  return null
+}
 
+function loadOrCreateDeviceIdentity(): DeviceIdentity {
+  // 1. Prefer the openclaw CLI's identity — it's likely already paired with the gateway
+  const cliIdentityPath = path.join(resolveCliStateDir(), 'identity', 'device.json')
+  const cliIdentity = tryLoadIdentityFile(cliIdentityPath)
+  if (cliIdentity) return cliIdentity
+
+  // 2. Fall back to SwarmClaw's own identity
+  const swarmClawPath = getSwarmClawIdentityPath()
+  const existing = tryLoadIdentityFile(swarmClawPath)
+  if (existing) return existing
+
+  // 3. Generate a new identity
   const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519')
   const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }) as string
   const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }) as string
@@ -55,7 +82,7 @@ function loadOrCreateDeviceIdentity(): DeviceIdentity {
     publicKeyPem,
     privateKeyPem,
   }
-  fs.writeFileSync(filePath, JSON.stringify({ version: 1, ...identity }, null, 2) + '\n', { mode: 0o600 })
+  fs.writeFileSync(swarmClawPath, JSON.stringify({ version: 1, ...identity }, null, 2) + '\n', { mode: 0o600 })
   return identity
 }
 
@@ -67,7 +94,7 @@ export function getDeviceId(): string {
 // --- Protocol helpers ---
 
 function normalizeWsUrl(raw: string): string {
-  let url = raw.replace(/\/+$/, '').replace(/\/v1$/i, '')
+  let url = raw.replace(/\/+$/, '')
   if (!/^(https?|wss?):\/\//i.test(url)) url = `http://${url}`
   url = url.replace(/^ws:/i, 'http:').replace(/^wss:/i, 'https:')
   return url.replace(/^http:/i, 'ws:').replace(/^https:/i, 'wss:')
@@ -92,7 +119,7 @@ export function buildOpenClawConnectParams(
   const scopes = ['operator.admin']
 
   const params: Record<string, unknown> = {
-    minProtocol: 1,
+    minProtocol: 3,
     maxProtocol: 3,
     auth: token ? { token } : undefined,
     client: {
@@ -134,7 +161,7 @@ export function buildOpenClawConnectParams(
 
 // --- Gateway connection ---
 
-interface ConnectResult {
+export interface ConnectResult {
   ok: boolean
   message: string
   errorCode?: string
@@ -145,7 +172,7 @@ interface ConnectResult {
  * Open a WebSocket and complete the connect handshake.
  * Resolves with { ok, ws } on success or { ok: false, message, errorCode } on failure.
  */
-function wsConnect(
+export function wsConnect(
   wsUrl: string,
   token: string | undefined,
   useDeviceAuth: boolean,
@@ -185,11 +212,16 @@ function wsConnect(
           if (msg.ok) {
             done({ ok: true, message: 'Connected.', ws })
           } else {
-            done({
-              ok: false,
-              message: msg.error?.message || 'Gateway connect failed.',
-              errorCode: msg.error?.details?.code as string | undefined,
-            })
+            const message = msg.error?.message || 'Gateway connect failed.'
+            let errorCode = (msg.error?.details?.code ?? msg.error?.code) as string | undefined
+            if (!errorCode) {
+              const m = message.toLowerCase()
+              if (m.includes('pairing') || m.includes('not paired') || m.includes('pending approval')) errorCode = 'PAIRING_REQUIRED'
+              else if (m.includes('signature') || m.includes('device auth')) errorCode = 'DEVICE_AUTH_INVALID'
+              else if (m.includes('token missing') || m.includes('token required')) errorCode = 'AUTH_TOKEN_MISSING'
+              else if (m.includes('unauthorized') || m.includes('invalid token')) errorCode = 'AUTH_TOKEN_INVALID'
+            }
+            done({ ok: false, message, errorCode })
           }
         }
       } catch {
@@ -202,8 +234,15 @@ function wsConnect(
     })
 
     ws.on('close', (code, reason) => {
+      const reasonStr = reason?.toString() || ''
       if (code === 1008) {
-        done({ ok: false, message: `Unauthorized: ${reason?.toString() || 'invalid token'}` })
+        const m = reasonStr.toLowerCase()
+        let errorCode: string | undefined
+        if (m.includes('pairing') || m.includes('not paired') || m.includes('pending approval')) errorCode = 'PAIRING_REQUIRED'
+        else if (m.includes('signature') || m.includes('device auth') || m.includes('device identity') || m.includes('device nonce')) errorCode = 'DEVICE_AUTH_INVALID'
+        else if (m.includes('token missing') || m.includes('token required')) errorCode = 'AUTH_TOKEN_MISSING'
+        else if (m.includes('unauthorized') || m.includes('invalid token')) errorCode = 'AUTH_TOKEN_INVALID'
+        done({ ok: false, message: reasonStr || 'Unauthorized', errorCode })
       } else {
         done({ ok: false, message: `Connection closed unexpectedly (${code})` })
       }
@@ -228,14 +267,14 @@ async function connectToGateway(
 
 // --- Provider ---
 
-export function streamOpenClawChat({ session, message, imagePath, write, active }: StreamChatOptions): Promise<string> {
+export function streamOpenClawChat({ session, message, imagePath, apiKey, write, active }: StreamChatOptions): Promise<string> {
   let prompt = message
   if (imagePath) {
     prompt = `[The user has shared an image at: ${imagePath}]\n\n${message}`
   }
 
   const wsUrl = session.apiEndpoint ? normalizeWsUrl(session.apiEndpoint) : 'ws://127.0.0.1:18789'
-  const token = session.apiKey || undefined
+  const token = apiKey || session.apiKey || undefined
 
   return new Promise((resolve) => {
     let fullResponse = ''