API Key Management (Dashboard KEYS Page)

Context

PocketClaw uses multiple API keys: AI providers (Kimi, Groq, OpenAI), messaging (Telegram bot token), and optional services. Initially, changing a key required: SSH into the phone, edit ~/.openclaw/env with vi, save, restart the gateway. This multi-step process was error-prone and inaccessible to anyone who can't use a terminal.

The KEYS page provides a web interface for full API key lifecycle management, accessible from any browser on the same WiFi network.

Implementation

Each provider has a specific test endpoint:

// Test endpoints per provider type:
const testEndpoints = {
  // AI providers — GET /v1/models
  'MOONSHOT_API_KEY': 'https://api.kimi.com/coding/v1/models',
  'OPENAI_API_KEY': 'https://api.openai.com/v1/models',
  'GROQ_API_KEY': 'https://api.groq.com/openai/v1/models',

  // Telegram — GET /botXXX/getMe
  'TELEGRAM_BOT_TOKEN': (key) => `https://api.telegram.org/bot${key}/getMe`,

  // Discord — GET /users/@me
  'DISCORD_BOT_TOKEN': 'https://discord.com/api/v10/users/@me',
};

Key operations:

// GET /api/keys — list all keys (masked)
// Returns: [{ name: "MOONSHOT_API_KEY", value: "sk-...x4f2", set: true }]

// POST /api/keys — save a key
// Body: { name: "MOONSHOT_API_KEY", value: "sk-kimi-full-key-here" }
// Writes to ~/.openclaw/env AND updates process.env (no restart needed)

// POST /api/keys/test — test a key
// Body: { name: "MOONSHOT_API_KEY" }
// Hits the provider's health endpoint, returns { ok: true/false, error?: "..." }

Keys are stored in ~/.openclaw/env with mode 0600:

# ~/.openclaw/env format:
MOONSHOT_API_KEY=sk-kimi-xxx
TELEGRAM_BOT_TOKEN=8360:AAH...
GROQ_API_KEY=gsk_xxx

Verification

# Access KEYS page:
curl -s http://localhost:9000/keys | grep "MOONSHOT"
# Expected: HTML showing MOONSHOT_API_KEY (masked)

# Test a key via API:
curl -s -X POST http://localhost:9000/api/keys/test \
  -H "Content-Type: application/json" \
  -d '{"name":"MOONSHOT_API_KEY"}'
# Expected: {"ok":true} or {"ok":false,"error":"..."}

# Verify env file permissions:
ls -la ~/.openclaw/env
# Expected: -rw------- (mode 600)

Gotchas

Keys are masked in the GET response (showing only last 4 characters). This prevents casual shoulder-surfing on the local network
The POST /api/keys endpoint writes to disk AND updates process.env in the running process — no gateway restart needed
There's no authentication on the KEYS page. It's only accessible on the local network, but anyone on the same WiFi can access it. Consider adding basic auth for shared networks
Telegram bot tokens have a special format (number:hash) — the test endpoint constructs the URL differently than AI providers

Result

Metric	Before	After
Key change method	SSH + vi	Web browser
Key testing	Manual curl	One-tap button
Gateway restart needed	Yes	No (live update)
Time to change a key	2-3 min	10 seconds

Context

Implementation

Verification

Gotchas

Result

One email. Every Thursday.