#51 Setup Wizard (/setup)

Context

PocketClaw's initial setup required SSH access, editing openclaw.json with correct JSON syntax, creating an env file with API keys, and restarting the gateway. This process has a dozen failure points and is inaccessible to anyone who isn't comfortable with a terminal.

The setup wizard provides a web-based 4-step flow that generates the configuration files and deploys them automatically. It's served from the same hijack.js HTTP interceptor at /setup.

Implementation

4-step flow served as inline HTML:

// Step 1: Choose messaging channel
// Options: Telegram (+35 MB) or Discord (+60 MB)
// Shows RAM impact of each choice

// Step 2: Choose AI provider
// Options: Kimi (free, 262K ctx), Groq (free tier, 32K ctx), OpenAI (paid, 128K ctx)
// Shows cost and context window for each

// Step 3: Enter credentials
// Telegram: Bot token (from @BotFather)
// Provider: API key
// Live validation as you type

// Step 4: DEPLOY
// Writes openclaw.json + env file
// Restarts gateway
// Shows boot progress

The wizard generates two files:

// openclaw.json generation:
const config = {
  channels: [selectedChannel],
  providers: [{
    name: selectedProvider,
    // ... provider-specific config
  }],
  gateway: { port: 9000 }
};
fs.writeFileSync(configPath, JSON.stringify(config, null, 2));

// env file generation:
const envLines = [
  `${providerKeyName}=${providerApiKey}`,
  `TELEGRAM_BOT_TOKEN=${telegramToken}`,
];
fs.writeFileSync(envPath, envLines.join('\n'), { mode: 0o600 });

Verification

# Access wizard:
curl -s http://localhost:9000/setup | head -10
# Expected: HTML with step 1 (channel selection)

# After completing wizard, verify config:
cat ~/.openclaw/openclaw.json | python -m json.tool
# Expected: valid JSON with channel and provider config

# Verify env file:
ls -la ~/.openclaw/env
# Expected: -rw------- with API keys

# Verify gateway restarted with new config:
curl -s http://localhost:9000/api/status
# Expected: gateway running with configured channel

Gotchas

• The wizard is only shown when no valid config exists. Once configured, /setup redirects to /dashboard
• RAM impact is shown for each channel choice because on a 1 GB device, the difference between Telegram (+35 MB) and Discord (+60 MB) matters
• The DEPLOY step writes files then sends SIGHUP to the gateway process for graceful restart. If the process doesn't respond, it falls back to SIGTERM + start
• Same CRT green theme as all other dashboard pages. Works from phone browser or any device on the same WiFi

Result