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 progressThe 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 channelGotchas
- The wizard is only shown when no valid config exists. Once configured,
/setupredirects 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
| Metric | Before | After |
|---|---|---|
| Setup method | SSH + JSON editing | Web wizard |
| Steps required | 10+ (manual) | 4 (guided) |
| Skill required | Terminal + JSON | Click buttons |
| Error rate | High (JSON syntax) | Near zero |