Troubleshooting Journal

Week 0 — VPS & Setup

Problem: Zeabur OTP wasn't sending during initial sign-up
Fix: Retried several times, eventually worked. Switching to incognito browser also helps.

Problem: SSH button stayed greyed out while server status was "Pending"
Fix: Connected directly via terminal: ssh root@IP instead of using the Zeabur web UI

Problem: Guide says to use google/gemini-2.0-flash but OpenRouter returns 404 "not a valid model ID"
Fix: Correct model is google/gemini-2.0-flash-001 — must include the -001 suffix
Impact: Every workshop member hit this. Flagged to organisers.

Problem: Bot token from BotFather screenshot showed cd0 (zero) but actual token had cdO (letter O) — caused 401 Unauthorized
Fix: Always copy-paste tokens from BotFather, never transcribe from screenshots

Problem: Running curl getUpdates for diagnostic while the ZeroClaw daemon was running caused a 409 conflict — bot stopped responding
Fix: Only one process can poll a bot token. Never run manual API calls while the daemon is active. Clean restart fixes it.

Problem: ZeroClaw service was killed by systemd when the SSH session ended
Fix: loginctl enable-linger root — keeps user services alive permanently even after logout
Lesson: This is needed on every fresh VPS setup.

Setup: API keys stored as api_key = "enc2:..." in config.toml, decrypted by local private key at ~/.zeroclaw/.secret_key
Why: Even if someone reads config.toml, they can't use the API key without physical server access

Key decisions: workspace_only = true, extensive forbidden_paths list, max_cost_per_day_cents = 100
Auto-approve list: Carefully expanded over weeks — started with just file_read and memory_recall, grew to include cron, delegate, shell, youtube tools

Ran the three tests from the workshop guide:

Cron task test — asked the bot via Telegram to set a cron task saying "Security test passed" in 2 minutes. Verified with zeroclaw cron list on the server. Message arrived on time.
Privilege escalation test — asked the agent to read ~/.ssh/id_rsa. It refused — blocked by forbidden_paths and workspace_only = true. Exactly what should happen.
Identity test — the Telegram allowed_users list only has my numeric ID. Anyone else who messages the bot gets no response at all. Deny-by-default works.

Decision: Built a custom MCP server (youtube-mcp-server.js) wrapping a Python fetcher (youtube_fetch.py) instead of using the default npx @anaisbetts/mcp-youtube
Why: More control over search parameters (region, language, result count) and direct YouTube Data API v3 access

Change: Switched from google/gemini-2.0-flash-001 to anthropic/claude-haiku-4.5
Why: Better reasoning for content analysis and delegation tasks

Architecture: ZeroClaw (manager) delegates to Nova (specialist) via the [agents.Nova] config block
Figured out the split: manager calls youtube__get_video_details for thumbnails, Nova just does the content. Both parts needed.