@swarmclawai/swarmclaw 0.9.9 → 1.0.2

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

@@ -1,31 +1,11 @@
-import { genId } from '@/lib/id'
-import { timingSafeEqual } from 'node:crypto'
 import { NextResponse } from 'next/server'
-import { loadAgents, loadSessions, loadWebhooks, saveSessions, saveWebhooks, appendWebhookLog, upsertWebhookRetry } from '@/lib/server/storage'
-import { WORKSPACE_DIR } from '@/lib/server/data-dir'
-import { enqueueSessionRun } from '@/lib/server/runtime/session-run-manager'
-import { enqueueSystemEvent } from '@/lib/server/runtime/system-events'
-import { requestHeartbeatNow } from '@/lib/server/runtime/heartbeat-wake'
+import { loadWebhooks, saveWebhooks } from '@/lib/server/storage'
 import { mutateItem, deleteItem, notFound, type CollectionOps } from '@/lib/server/collection-helpers'
-import type { WebhookRetryEntry } from '@/types'
-import { triggerWebhookWatchJobs } from '@/lib/server/runtime/watch-jobs'
-import { errorMessage } from '@/lib/shared-utils'
+import { handleWebhookPost } from './helpers'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const ops: CollectionOps<any> = { load: loadWebhooks, save: saveWebhooks }
 
-type WebhookPostDeps = {
-  enqueueRun: typeof enqueueSessionRun
-  enqueueEvent: typeof enqueueSystemEvent
-  requestHeartbeat: typeof requestHeartbeatNow
-}
-
-const defaultWebhookPostDeps: WebhookPostDeps = {
-  enqueueRun: enqueueSessionRun,
-  enqueueEvent: enqueueSystemEvent,
-  requestHeartbeat: requestHeartbeatNow,
-}
-
 function normalizeEvents(value: unknown): string[] {
   if (!Array.isArray(value)) return []
   return value
@@ -34,12 +14,6 @@ function normalizeEvents(value: unknown): string[] {
     .filter(Boolean)
 }
 
-function eventMatches(registered: string[], incoming: string): boolean {
-  if (registered.length === 0) return true
-  if (registered.includes('*')) return true
-  return registered.includes(incoming)
-}
-
 export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const webhooks = loadWebhooks()
@@ -71,221 +45,6 @@ export async function DELETE(_req: Request, { params }: { params: Promise<{ id:
   return NextResponse.json({ ok: true })
 }
 
-export async function handleWebhookPost(
-  req: Request,
-  id: string,
-  deps: WebhookPostDeps = defaultWebhookPostDeps,
-) {
-  const webhooks = loadWebhooks()
-  const webhook = webhooks[id]
-  if (!webhook) return notFound('Webhook not found')
-  if (webhook.isEnabled === false) {
-    appendWebhookLog(genId(8), {
-      id: genId(8), webhookId: id, event: 'unknown',
-      payload: '', status: 'error', error: 'Webhook is disabled', timestamp: Date.now(),
-    })
-    return NextResponse.json({ error: 'Webhook is disabled' }, { status: 409 })
-  }
-
-  const secret = typeof webhook.secret === 'string' ? webhook.secret.trim() : ''
-  if (secret) {
-    const url = new URL(req.url)
-    const provided = req.headers.get('x-webhook-secret') || url.searchParams.get('secret') || ''
-    const secretBuf = Buffer.from(secret)
-    const providedBuf = Buffer.from(provided)
-    // timingSafeEqual requires equal lengths; compare against secretBuf if lengths differ
-    const compareBuf = providedBuf.length === secretBuf.length ? providedBuf : secretBuf
-    const isInvalid = providedBuf.length !== secretBuf.length || !timingSafeEqual(secretBuf, compareBuf)
-    if (isInvalid) {
-      appendWebhookLog(genId(8), {
-        id: genId(8), webhookId: id, event: 'unknown',
-        payload: '', status: 'error', error: 'Invalid webhook secret', timestamp: Date.now(),
-      })
-      return NextResponse.json({ error: 'Invalid webhook secret' }, { status: 401 })
-    }
-  }
-
-  let payload: unknown = null
-  let rawBody = ''
-  const contentType = req.headers.get('content-type') || ''
-  if (contentType.includes('application/json')) {
-    try {
-      payload = await req.json()
-      rawBody = JSON.stringify(payload)
-    } catch {
-      payload = {}
-      rawBody = '{}'
-    }
-  } else {
-    rawBody = await req.text()
-    try {
-      payload = JSON.parse(rawBody)
-    } catch {
-      payload = { raw: rawBody }
-    }
-  }
-
-  const url = new URL(req.url)
-  const incomingEvent = String(
-    (payload as Record<string, unknown> | null)?.type
-      || (payload as Record<string, unknown> | null)?.event
-      || req.headers.get('x-event-type')
-      || url.searchParams.get('event')
-      || 'unknown',
-  )
-  const registeredEvents = normalizeEvents(webhook.events)
-  if (!eventMatches(registeredEvents, incomingEvent)) {
-    return NextResponse.json({
-      ok: true,
-      ignored: true,
-      reason: 'Event does not match webhook filters',
-      event: incomingEvent,
-    })
-  }
-
-  triggerWebhookWatchJobs({
-    webhookId: id,
-    event: incomingEvent,
-    payloadPreview: rawBody,
-  })
-
-  const agents = loadAgents()
-  const agent = webhook.agentId ? agents[webhook.agentId] : null
-  if (!agent) {
-    appendWebhookLog(genId(8), {
-      id: genId(8), webhookId: id, event: incomingEvent,
-      payload: (rawBody || '').slice(0, 2000), status: 'error', error: 'Webhook agent is not configured or missing', timestamp: Date.now(),
-    })
-    return NextResponse.json({ error: 'Webhook agent is not configured or missing' }, { status: 400 })
-  }
-
-  const sessions = loadSessions()
-  const sessionName = `webhook:${id}`
-  let session = Object.values(sessions).find((s: unknown) => {
-    const rec = s as Record<string, unknown>
-    return rec.name === sessionName && rec.agentId === agent.id
-  }) as Record<string, unknown> | undefined
-  if (!session) {
-    const sessionId = genId()
-    const now = Date.now()
-    session = {
-      id: sessionId,
-      name: sessionName,
-      cwd: WORKSPACE_DIR,
-      user: 'system',
-      provider: agent.provider || 'claude-cli',
-      model: agent.model || '',
-      credentialId: agent.credentialId || null,
-      apiEndpoint: agent.apiEndpoint || null,
-      claudeSessionId: null,
-      codexThreadId: null,
-      opencodeSessionId: null,
-      delegateResumeIds: {
-        claudeCode: null,
-        codex: null,
-        opencode: null,
-      },
-      messages: [],
-      createdAt: now,
-      lastActiveAt: now,
-      sessionType: 'human',
-      agentId: agent.id,
-      parentSessionId: null,
-      tools: agent.tools || [],
-      heartbeatEnabled: agent.heartbeatEnabled ?? false,
-      heartbeatIntervalSec: agent.heartbeatIntervalSec ?? null,
-    }
-    sessions[session.id as string] = session
-    saveSessions(sessions)
-  }
-
-  const sid = session.id as string
-  const payloadPreview = (rawBody || '').slice(0, 12_000)
-  const prompt = [
-    'Webhook event received.',
-    `Webhook ID: ${id}`,
-    `Webhook Name: ${webhook.name || id}`,
-    `Source: ${webhook.source || 'custom'}`,
-    `Event: ${incomingEvent}`,
-    `Received At: ${new Date().toISOString()}`,
-    '',
-    'Payload:',
-    payloadPreview || '(empty payload)',
-    '',
-    'Handle this event now. If this requires notifying the user, use configured connector tools.',
-  ].join('\n')
-
-  try {
-    const run = deps.enqueueRun({
-      sessionId: sid,
-      message: prompt,
-      source: 'webhook',
-      internal: false,
-      mode: 'followup',
-    })
-
-    // Enqueue system event + heartbeat wake
-    deps.enqueueEvent(sid, `Webhook received: ${webhook.name || id} (${incomingEvent})`)
-    if (webhook.agentId) {
-      deps.requestHeartbeat({
-        agentId: webhook.agentId,
-        eventId: `webhook:${id}:${incomingEvent}:${Date.now()}`,
-        reason: 'webhook',
-        source: `webhook:${id}`,
-        resumeMessage: `Webhook received: ${webhook.name || id} (${incomingEvent})`,
-        detail: payloadPreview || '(empty payload)',
-      })
-    }
-
-    appendWebhookLog(genId(8), {
-      id: genId(8), webhookId: id, event: incomingEvent,
-      payload: (rawBody || '').slice(0, 2000), status: 'success',
-      sessionId: sid, runId: run.runId, timestamp: Date.now(),
-    })
-
-    return NextResponse.json({
-      ok: true,
-      webhookId: id,
-      event: incomingEvent,
-      sessionId: sid,
-      runId: run.runId,
-    })
-  } catch (err: unknown) {
-    const errorMsg = errorMessage(err)
-
-    // Enqueue for retry with exponential backoff
-    const retryId = genId()
-    const now = Date.now()
-    const retryEntry: WebhookRetryEntry = {
-      id: retryId,
-      webhookId: id,
-      event: incomingEvent,
-      payload: (rawBody || '').slice(0, 12_000),
-      attempts: 1,
-      maxAttempts: 3,
-      nextRetryAt: now + 30_000,
-      deadLettered: false,
-      createdAt: now,
-    }
-    upsertWebhookRetry(retryId, retryEntry)
-
-    appendWebhookLog(genId(8), {
-      id: genId(8), webhookId: id, event: incomingEvent,
-      payload: (rawBody || '').slice(0, 2000), status: 'error',
-      error: `Dispatch failed, queued for retry: ${errorMsg}`, timestamp: Date.now(),
-    })
-
-    return NextResponse.json({
-      ok: true,
-      webhookId: id,
-      event: incomingEvent,
-      retryQueued: true,
-      retryId,
-      error: errorMsg,
-    })
-  }
-}
-
 export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   return handleWebhookPost(req, id)

package/src/app/api/webhooks/route.test.ts

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict'
 import test, { afterEach } from 'node:test'
 
 import { GET as getWebhookHistory } from './[id]/history/route'
-import { handleWebhookPost } from './[id]/route'
+import { handleWebhookPost } from './[id]/helpers'
 import {
   loadAgents,
   loadSessions,
@@ -126,7 +126,9 @@ test('handleWebhookPost creates a session, records success history, and triggers
   assert.match(String(calls.runs[0].message), /Event: build\.completed/)
 
   assert.deepEqual(calls.events, [[sessionId, 'Webhook received: Webhook Smoke (build.completed)']])
-  assert.deepEqual(calls.heartbeats, [{ agentId: 'agent-webhook-smoke', reason: 'webhook' }])
+  assert.equal(calls.heartbeats.length, 1)
+  assert.equal(calls.heartbeats[0].agentId, 'agent-webhook-smoke')
+  assert.equal(calls.heartbeats[0].reason, 'webhook')
 
   const logEntries = Object.values(loadWebhookLogs()) as Array<Record<string, unknown>>
   const successEntry = logEntries.find((entry) => entry.webhookId === webhookId && entry.status === 'success')

package/src/cli/binary.test.js

@@ -119,6 +119,51 @@ test('binary server help exits successfully', () => {
   assert.match(result.stdout, /Usage: swarmclaw server/i)
 })
 
+test('binary run alias routes to server help', () => {
+  const result = runBinary(['run', '--help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw server/i)
+})
+
+test('binary help command shows root help', () => {
+  const result = runBinary(['help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /SwarmClaw CLI/i)
+  assert.match(result.stdout, /swarmclaw help \[command\]/i)
+})
+
+test('binary help command shows command help for run alias', () => {
+  const result = runBinary(['help', 'run'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw server/i)
+})
+
+test('binary help command shows command help for doctor alias', () => {
+  const result = runBinary(['help', 'doctor'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw doctor/i)
+})
+
+test('binary status alias routes to local server status', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-binary-status-'))
+  const result = runBinary(['status'], {
+    env: {
+      SWARMCLAW_HOME: homeDir,
+    },
+  })
+
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Server: not running/i)
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+})
+
+test('binary doctor help exits successfully', () => {
+  const result = runBinary(['doctor', '--help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw doctor/i)
+})
+
 test('binary update help exits successfully', () => {
   const result = runBinary(['update', '--help'])
   assert.equal(result.status, 0, result.stderr)
@@ -131,6 +176,18 @@ test('binary version output matches package version', () => {
   assert.equal(result.stdout.trim(), `${PACKAGE_JSON.name} ${PACKAGE_JSON.version}`)
 })
 
+test('binary bare version alias output matches package version', () => {
+  const result = runBinary(['version'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout.trim(), `${PACKAGE_JSON.name} ${PACKAGE_JSON.version}`)
+})
+
+test('binary -v alias output matches package version', () => {
+  const result = runBinary(['-v'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout.trim(), `${PACKAGE_JSON.name} ${PACKAGE_JSON.version}`)
+})
+
 test('legacy TS launcher falls back to tsx import when strip-types is unavailable', () => {
   const cliPath = path.join(APP_ROOT, 'src', 'cli', 'index.ts')
   const args = buildLegacyTsCliArgs(cliPath, ['runs', 'list'], {

package/src/cli/index.js

@@ -412,6 +412,7 @@ const COMMAND_GROUPS = [
       cmd('skills-install', 'POST', '/openclaw/skills/install', 'Install OpenClaw skill dependencies', { expectsJsonBody: true }),
       cmd('skills-remove', 'POST', '/openclaw/skills/remove', 'Remove OpenClaw skill', { expectsJsonBody: true }),
       cmd('sync', 'POST', '/openclaw/sync', 'Run OpenClaw sync action', { expectsJsonBody: true }),
+      cmd('dashboard-url', 'GET', '/openclaw/dashboard-url', 'Get tokenized OpenClaw dashboard URL for an agent'),
       cmd('doctor', 'GET', '/openclaw/doctor', 'Run OpenClaw doctor check (read-only)'),
       cmd('doctor-fix', 'POST', '/openclaw/doctor', 'Run OpenClaw doctor with auto-fix', { expectsJsonBody: true }),
     ],
@@ -1182,6 +1183,9 @@ function renderGeneralHelp() {
     'SwarmClaw CLI',
     '',
     'Usage:',
+    '  swarmclaw',
+    '  swarmclaw help [command]',
+    '  swarmclaw run|start|stop|status|doctor|update|version',
     '  swarmclaw <group> <command> [args] [options]',
     '',
     'Global options:',
@@ -1198,6 +1202,15 @@ function renderGeneralHelp() {
     '  --help                 Show help',
     '  --version              Show package version',
     '',
+    'Top-level commands:',
+    '  run, start             Start the SwarmClaw server',
+    '  stop                   Stop the detached SwarmClaw server',
+    '  status                 Show local server status',
+    '  doctor                 Show local install/build diagnostics',
+    '  help                   Show root or command help',
+    '  update                 Update this SwarmClaw installation',
+    '  version                Show package version',
+    '',
     'Groups:',
   ]
 
@@ -1209,7 +1222,7 @@ function renderGeneralHelp() {
     }
   }
 
-  lines.push('', 'Use "swarmclaw <group> --help" for group commands.')
+  lines.push('', 'Use "swarmclaw help <command>" or "swarmclaw <group> --help" for more detail.')
   return lines.join('\n')
 }
 

package/src/cli/server-cmd.test.js

@@ -19,41 +19,42 @@ function loadServerCmdForHome(homeDir) {
   return loaded
 }
 
-test('needsBuild returns true when no build marker exists', () => {
+test('needsBuild returns true when standalone output is missing from the package root', () => {
   const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const pkgRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-pkg-'))
   const serverCmd = loadServerCmdForHome(homeDir)
-  assert.equal(serverCmd.needsBuild(false), true)
+
+  assert.equal(serverCmd.needsBuild(false, { pkgRoot }), true)
+
   fs.rmSync(homeDir, { recursive: true, force: true })
+  fs.rmSync(pkgRoot, { recursive: true, force: true })
 })
 
-test('needsBuild returns false when build marker version matches and standalone server exists', () => {
+test('needsBuild returns false when standalone server exists in the package root', () => {
   const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const pkgRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-pkg-'))
   const serverCmd = loadServerCmdForHome(homeDir)
 
-  fs.mkdirSync(path.join(homeDir, '.next', 'standalone'), { recursive: true })
-  fs.writeFileSync(path.join(homeDir, '.next', 'standalone', 'server.js'), 'console.log("ok")\n', 'utf8')
-  fs.writeFileSync(
-    path.join(homeDir, '.built'),
-    JSON.stringify({ builtAt: new Date().toISOString(), version: serverCmd.getVersion() }),
-    'utf8',
-  )
+  fs.mkdirSync(path.join(pkgRoot, '.next', 'standalone'), { recursive: true })
+  fs.writeFileSync(path.join(pkgRoot, '.next', 'standalone', 'server.js'), 'console.log("ok")\n', 'utf8')
+
+  assert.equal(serverCmd.needsBuild(false, { pkgRoot }), false)
 
-  assert.equal(serverCmd.needsBuild(false), false)
   fs.rmSync(homeDir, { recursive: true, force: true })
+  fs.rmSync(pkgRoot, { recursive: true, force: true })
 })
 
-test('needsBuild returns true when build marker version is stale', () => {
+test('findStandaloneServer recursively resolves nested standalone server paths', () => {
   const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const pkgRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-pkg-'))
   const serverCmd = loadServerCmdForHome(homeDir)
 
-  fs.mkdirSync(path.join(homeDir, '.next', 'standalone'), { recursive: true })
-  fs.writeFileSync(path.join(homeDir, '.next', 'standalone', 'server.js'), 'console.log("ok")\n', 'utf8')
-  fs.writeFileSync(
-    path.join(homeDir, '.built'),
-    JSON.stringify({ builtAt: new Date().toISOString(), version: '0.0.0-test' }),
-    'utf8',
-  )
+  const nestedServer = path.join(pkgRoot, '.next', 'standalone', 'Users', 'wayde', 'Dev', 'swarmclaw', 'server.js')
+  fs.mkdirSync(path.dirname(nestedServer), { recursive: true })
+  fs.writeFileSync(nestedServer, 'console.log("ok")\n', 'utf8')
+
+  assert.equal(serverCmd.findStandaloneServer({ pkgRoot }), nestedServer)
 
-  assert.equal(serverCmd.needsBuild(false), true)
   fs.rmSync(homeDir, { recursive: true, force: true })
+  fs.rmSync(pkgRoot, { recursive: true, force: true })
 })

package/src/components/auth/setup-wizard/index.tsx

@@ -339,6 +339,22 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
           agentId = (await api<{ id: string }>('POST', '/agents', payload)).id
         }
 
+        // Push soul and identity files to the OpenClaw gateway (non-fatal)
+        if (draft.provider === 'openclaw') {
+          try {
+            if (draft.soul.trim()) {
+              await api('PUT', '/openclaw/agent-files', { agentId, filename: 'SOUL.md', content: draft.soul.trim() })
+            }
+            const identityLines = [`# ${draft.name.trim()}`, '']
+            if (draft.description.trim()) identityLines.push(draft.description.trim())
+            identityLines.push('')
+            if (draft.capabilities.length) identityLines.push(`- Capabilities: ${draft.capabilities.join(', ')}`)
+            await api('PUT', '/openclaw/agent-files', { agentId, filename: 'IDENTITY.md', content: identityLines.join('\n') })
+          } catch {
+            // Gateway file sync is best-effort during setup
+          }
+        }
+
         created.push({
           id: agentId,
           name: draft.name.trim(),

package/src/components/auth/setup-wizard/step-agents.tsx

@@ -422,34 +422,45 @@ export function StepAgents({
                         focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
                     />
                   </div>
-                  <div>
-                    <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Model</label>
-                    <ModelCombobox
-                      value={draft.model}
-                      provider={matchedProvider}
-                      endpointOverride={draft.apiEndpoint}
-                      onChange={(model) => onUpdateDraft(draft.id, { model })}
-                      modelLibraryUrl={matchedProvider ? SETUP_PROVIDERS.find((sp) => sp.id === matchedProvider.provider)?.modelLibraryUrl : null}
-                    />
-                  </div>
-                  <div>
-                    <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Mode</label>
-                    <select
-                      value={draft.platformAssignScope}
-                      onChange={(e) => onUpdateDraft(draft.id, { platformAssignScope: e.target.value as 'self' | 'all' })}
-                      className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
-                        text-text text-[14px] outline-none transition-all duration-200
-                        focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
-                    >
-                      <option value="self">Focused agent</option>
-                      <option value="all">Delegating orchestrator</option>
-                    </select>
-                  </div>
+                  {matchedProvider?.provider === 'openclaw' ? (
+                    <div className="md:col-span-2">
+                      <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Model</label>
+                      <div className="flex items-center gap-3 px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg">
+                        <span className="text-[13px] text-text-3">Configured on the OpenClaw gateway.</span>
+                        {matchedProvider.dashboardUrl && (
+                          <a
+                            href={matchedProvider.dashboardUrl}
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            className="text-[13px] text-accent-bright hover:underline whitespace-nowrap"
+                          >
+                            Open Dashboard
+                          </a>
+                        )}
+                      </div>
+                    </div>
+                  ) : (
+                    <div className="md:col-span-2">
+                      <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Model</label>
+                      <ModelCombobox
+                        value={draft.model}
+                        provider={matchedProvider}
+                        endpointOverride={draft.apiEndpoint}
+                        onChange={(model) => onUpdateDraft(draft.id, { model })}
+                        modelLibraryUrl={matchedProvider ? SETUP_PROVIDERS.find((sp) => sp.id === matchedProvider.provider)?.modelLibraryUrl : null}
+                      />
+                    </div>
+                  )}
                   <div className="md:col-span-2">
                     <SoulPicker
                       value={draft.soul}
                       onChange={(soul) => onUpdateDraft(draft.id, { soul })}
                     />
+                    {matchedProvider?.provider === 'openclaw' && (
+                      <p className="mt-1.5 ml-1 text-[11px] text-text-3/70">
+                        Synced to the gateway as SOUL.md on save.
+                      </p>
+                    )}
                   </div>
                 </div>
 

package/src/components/auth/setup-wizard/step-connect.tsx

@@ -200,6 +200,13 @@ export function StepConnect({
         resolvedProvider = customConfig.id as typeof provider
       }
 
+      // Build a tokenized dashboard URL for OpenClaw so step-agents can link to it
+      let dashboardUrl: string | null = null
+      if (provider === 'openclaw') {
+        const base = resolveOpenClawDashboardUrl(endpoint.trim() || selectedProvider.defaultEndpoint)
+        dashboardUrl = apiKey.trim() ? `${base}?token=${encodeURIComponent(apiKey.trim())}` : base
+      }
+
       const configured: ConfiguredProvider = {
         id: crypto.randomUUID(),
         provider: resolvedProvider,
@@ -212,6 +219,7 @@ export function StepConnect({
         tags: providerTags,
         deployment: providerDeployment,
         verified: checkState === 'ok',
+        dashboardUrl,
       }
 
       onSaveProvider(configured)

package/src/components/auth/setup-wizard/types.ts

@@ -44,6 +44,8 @@ export interface ConfiguredProvider {
   tags?: string[]
   deployment?: GatewayProfile['deployment'] | null
   verified?: boolean
+  /** Pre-built dashboard URL (with token if available). Only set for OpenClaw. */
+  dashboardUrl?: string | null
 }
 
 export interface StarterDraftAgent {