clawdbot-workspace/memory/lessons-learned.md

Lessons Learned

Cloudflare / Tunnels / DNS (2026-02-12)

• nohup your tunnels: cloudflared processes die when exec sessions close. Always use nohup cloudflared tunnel ... &
• Verify before announcing: Always curl the tunnel URL and confirm 200 before posting to Discord. Got burned 3 times in a row.
• Workers need DNS: Cloudflare Workers with routes need a proxied A record (use 192.0.2.1 RFC 5737 dummy IP)
• http2 > quic: --protocol http2 works more reliably than default quic for cloudflared tunnels
• CF Registrar is dashboard-only: No API for new domain registration. Only management of existing domains.
• Wrangler OAuth vs API Token: The OAuth token (in wrangler config) and CLOUDFLARE_API_TOKEN have different scopes. Check both.

Python / Veo (2026-02-12)

• Unbuffered output: Use python3 -u for scripts running in background — otherwise stdout is buffered and you see no output
• Veo download workaround: client.files.download() returns 404. Instead grab the URI from video.video.uri and download with ?key=API_KEY

Discord Etiquette (2026-02-12)

• Don't spam debug messages: Do work silently, announce clean results. Jake had to tell me to delete 45 messages of debug spam. — Buba's Self-Learning Log

Every mistake is a lesson. Every lesson makes us mega beastly. This file is updated CONSTANTLY whenever I figure something out the hard way. Search this BEFORE attempting anything similar.

---

Gateway & Infrastructure

Gateway logs live at /tmp/clawdbot/ not ~/.clawdbot/logs/

• Date: 2026-02-11
• Mistake: Checked ~/.clawdbot/logs/ and said "nothing since Feb 5" — confused Jake
• Reality: Gateway switched to /tmp/clawdbot/clawdbot-YYYY-MM-DD.log. The old logs dir is stale.
• Rule: Always check /tmp/clawdbot/ for current gateway logs.

tmux death kills the auto-restart loop

• Date: 2026-02-11
• Mistake: Assumed compaction caused silence. Actually the entire tmux session died.
• Reality: run-gateway.sh has a while true loop that only works if tmux survives. If tmux itself dies, no recovery.
• Rule: When diagnosing downtime, check tmux list-sessions and session creation time with tmux display-message -t clawdbot -p '#{session_created}'. If the session is newer than expected, tmux died.

Gateway freeze vs crash — different diagnostics

• Date: 2026-02-11
• Mistake: Initially thought it was an event loop freeze (alive but hung). Was actually a full crash.
• Rule: Check the log timeline for gaps. If there's a gap AND the tmux session is freshly created, it was a crash. If the tmux session is old but logs have a gap, THEN it's a freeze.

Discord API

channel-list needs guildId, not channel ID

• Date: 2026-02-10
• Mistake: Passed channel ID to channel-list, got "Unknown Guild"
• Rule: Guild ID ≠ channel ID. Jake's main guild is 1458233582404501547. Channel IDs are different.

Guild ID reference

• Main server: 1458233582404501547
• Config has all guilds listed under channels.discord.guilds in clawdbot.json

Deleting messages needs the channel as target

• Date: 2026-02-10
• Rule: message delete needs target set to the channel ID where the message lives.

Cron Jobs

Cron job parameter format

• Date: 2026-02-10
• Mistake: Tried multiple wrong formats before getting it right
• Correct format:

{
  "name": "job-name",
  "schedule": {"kind": "cron", "expr": "0 9 * * 1,4"},
  "sessionTarget": "main",
  "payload": {"kind": "systemEvent", "text": "..."},
  "enabled": true
}

• Rule: schedule needs kind + expr. Payload needs kind: "systemEvent" + text. NOT label, NOT message.

File Operations

Edit tool requires EXACT text match

• Date: 2026-02-11 (CREdispo sub-agent)
• Mistake: Multiple edit failures on CREdispo files because oldText didn't match exactly
• Rule: Always read the file first to get exact text before editing. Never guess at whitespace or content.

iMessage / BlueBubbles

Sending images to group chats via AppleScript is unreliable

• Date: 2026-02-10
• Mistake: Tried to send images to iMessage group chats via AppleScript — text sends but images may not deliver
• Rule: For image delivery to group chats, use BlueBubbles API directly or have Jake send manually from Discord.

Group chat ID format

• Date: 2026-02-10
• Rule: iMessage group chat IDs look like chat358249523368699090. The send format is any;+;chat358249523368699090.

Context & Memory

ALWAYS save state to memory before heavy work

• Date: 2026-02-11
• Mistake: Was deep in CREdispo work, context got compacted, lost all working state
• Rule: Before starting any multi-step project, write current state to memory/YYYY-MM-DD.md. Update it at milestones. This survives compaction.

Compaction ≠ crash — don't confuse them

• Date: 2026-02-11
• Mistake: Told Jake compaction caused the silence when it was actually a gateway crash
• Rule: Compaction just compresses context. It doesn't stop me from responding. If I went silent, something else happened.

Image Generation

Nano Banana Pro needs specific iterative prompting for character accuracy

• Date: 2026-02-10
• Mistake: Took 4 iterations to get Caleb's appearance right (white hair → brown, no beard → beard, etc.)
• Rule: When generating character images, be VERY specific about hair color, facial hair, build, and clothing in the first prompt. Don't assume defaults.

Sub-agents

Sub-agent results arrive as system messages after compaction

• Date: 2026-02-11
• Mistake: Didn't realize the CREdispo postgres migration had completed because context was compacted
• Rule: After spawning a sub-agent for heavy work, the result comes back as a user message. If context compacts before I process it, I need to check sessions_list for completed sub-agents.

Security

Cloudflare quick tunnels break HTML form POST (405 Method Not Allowed)

• Date: 2026-02-11
• Mistake: Signup/login forms used native HTML <form method="POST"> which returns 405 through cloudflared quick tunnels
• Reality: Cloudflare quick tunnels can mangle POST form submissions. JSON API calls via fetch() work fine.
• Rule: When serving apps through cloudflared tunnels, use JavaScript fetch() for form submissions instead of native HTML form POSTs. Keep the old form routes for direct access but add /api/ JSON endpoints.

VPN breaks Cloudflare tunnels

• Date: 2026-02-11
• Mistake: Had Mullvad VPN connected to Mexico while trying to create new cloudflared tunnels — tunnels couldn't establish
• Rule: Disconnect VPN before creating new cloudflared tunnels. Existing tunnels may also break when VPN connects.

API tokens must go in gateway config env.vars, not just .env files

• Date: 2026-02-11
• Mistake: Saved Cloudflare token to .env.local but not to gateway config. Gateway couldn't use it.
• Reality: The gateway reads env vars from clawdbot.json → env.vars. A .env.local file is for apps, not the gateway process.
• Rule: When Jake gives a new API token, save it via gateway config.patch to env.vars so the gateway has it. Also save to .env.local for local app use.

NEVER save secrets/tokens in memory/*.md files

• Date: 2026-02-11
• Rule: Memory files are git-backed and could leak. Save tokens/keys to .env.local (which is in .gitignore). Reference them by name in memory, never by value.

Delete messages containing tokens IMMEDIATELY

• Date: 2026-02-11
• Rule: If Jake or anyone pastes a secret in Discord, delete the message FIRST, then save the token. Every second it sits in a channel is a risk.

---

Last updated: 2026-02-11 22:56 EST Total lessons: 16

17. Jake's Preferred Image Style

• Mistake: Used comic book/vibrant cartoon style when Jake asked for "the style I like"
• What happened: Jake corrected — his preferred style is chibi kawaii anime, NOT comic book
• Rule: Jake's go-to image style = chibi/kawaii anime (pastel colors, big eyes, oversized heads, tiny bodies, sparkles, hearts, stars). Same style as Buba's visual identity in IDENTITY.md. Always default to this unless he says otherwise.