Skip to content

Troubleshooting

Week 2 — Pitfalls, Fixes & Learnings

Overview

Deploying Luna as a sub-agent on ZeroClaw. The core loop — search → synthesise → archive — is now working, but the path was not straightforward.

Pitfall 1 — auto_approve was empty

What happened: The mother agent kept stalling and falling back to conversational mode instead of delegating to Luna. Fix: Added file_write, model_routing_config, tool_search, delegate, shell to the auto_approve list in config.toml. Learning: Always check auto_approve first when the mother agent isn't taking action. An empty list means it will ask for permission on everything and often give up.

Pitfall 2 — Mother agent changed Luna's model

What happened: Every time the mother agent tried to troubleshoot itself via Telegram, it changed Luna's model to meta-llama/llama-3-70b-instruct and also changed the main provider model. This caused persistent "provider authentication conflict" errors. Fix: Manually corrected both [providers.models.openrouter] and [agents.Luna] back to anthropic/claude-3.5-haiku in config.toml. Learning: Never let the mother agent troubleshoot its own configuration. It will make changes that break things. Always edit config.toml manually from the terminal.

Pitfall 3 — Luna's agentic flag was false

What happened: Luna existed in config.toml under [agents.Luna] but was not operational because agentic = false and allowed_tools = []. Fix: Manually set agentic = true and added the correct tools: web_search_tool, file_read, file_write, shell, sessions_send. Learning: When the mother agent registers a sub-agent via Telegram, always verify the [agents.Luna] block manually — it often sets wrong defaults.

Pitfall 4 — SOUL.md content got pasted into config.toml

What happened: When trying to set system_prompt to a file path, the contents of SOUL.md got embedded directly into config.toml, breaking the TOML syntax at line 607. Fix: Opened nano +607 ~/.zeroclaw/config.toml and deleted all the SOUL.md content, leaving system_prompt = "". Learning: Never set system_prompt to a file path. ZeroClaw reads SOUL.md and SKILL.md automatically. The system_prompt field should stay empty.

Pitfall 5 — Duplicate provider section

What happened: The mother agent created a second provider section [providers.models."custom:https://openrouter.ai/api/v1"] while troubleshooting, which caused a zeroclaw doctor error. Fix: Removed the duplicate block from config.toml. Learning: After any Telegram troubleshooting session, always run grep -A 15 'agents.Luna' ~/.zeroclaw/config.toml and zeroclaw doctor to verify nothing was broken.

Golden Rules Learned This Week

  1. Never let the mother agent edit its own config — always do it manually from the terminal
  2. After every config change, run zeroclaw service restart and verify with zeroclaw status
  3. Check auto_approve first when delegation isn't working
  4. zeroclaw doctor is your best diagnostic tool
  5. The archive folder is your proof of life — if files appear there, Luna is working