Field Guide
FAQs, Frustrations, and Hard-Won Wisdom
This section exists outside the Trivium stages because it is reference material - the kind of knowledge that is most useful after you have completed the learning path. Think of it as the notes a veteran passes to a new hire on day one: "Here is what the training manual does not tell you."
Frequently Asked Questions
Questions You Should Be Asking But Probably Are Not
Common Frustrations and How to Handle Them
These are real frustrations reported by real users. Understanding them before you encounter them will save you hours of confusion.
"The agent forgot everything after I reset the chat"
What is happening: Session resets wipe the conversation transcript. If important information (credentials, preferences, project context) was only shared in chat and never written to workspace memory files, it is gone.
Prevention: Configure memoryFlush so the agent automatically saves important context before sessions reset. Or instruct the agent in AGENTS.md to always save critical information to MEMORY.md.
"I gave it my API key in chat and now it says it does not have it"
What is happening: Credentials shared in conversation live in the session transcript. When the session resets or compacts, they vanish.
Solution: Credentials should never be shared in chat. Store them in the config file (openclaw.json), in credential files, or in workspace environment files that the agent can read on every session.
"The agent keeps crashing and I do not know how to restart it"
What is happening: The Gateway runs as a daemon (background process). If it crashes, launchd should auto-restart it.
Solution: If that fails, open Terminal and type: openclaw gateway start. If that fails, run: openclaw doctor --fix to diagnose and repair. Check the logs for error messages.
"It randomly forgets things mid-conversation"
What is happening: This is likely compaction. When the session grows too long, older messages are summarized and detail is lost.
Solution: Increase contextTokens in your config, enable memoryFlush to save context before compaction, or install a persistent memory plugin like Mem0 that stores memories outside the context window.
"Messages get lost or duplicated on Discord"
What is happening: Known issues with the Discord channel adapter. Long-running operations (over 2 minutes) can cause the Discord WebSocket to time out, dropping responses. Duplicate messages are a known bug in certain versions.
Solution: Use WebChat for complex tasks, keep Discord for simple interactions, and update to the latest version.
"Setup is overwhelming - too many options"
What is happening: This is normal. OpenClaw has many configuration options.
Solution: Use the onboarding wizard (openclaw onboard) which guides you step by step. Start with the minimal configuration: one AI model, one channel (WhatsApp is the easiest to set up), and bundled skills only. Expand after you have a working baseline.
"I messed up the config and now nothing works"
What is happening: Configuration syntax errors or invalid values can break the Gateway.
Solution: Run: openclaw doctor --fix to attempt auto-repair. If that fails, check if a backup exists at openclaw.json.bak (OpenClaw creates a backup before each config write). You can restore it by copying it over the corrupted file. As a last resort, rename the current config and re-run the onboarding wizard.
"I cannot figure out how to access it from my phone when I am away"
What is happening: By default, the Gateway only listens on localhost - you cannot reach it from outside your home network.
Solution: For remote access, the recommended approach is Tailscale (creates a secure private network) or an SSH tunnel. Never expose the Gateway directly to the internet without authentication.
"The agent changed its own settings and now it behaves differently"
What is happening: By default, the agent can modify its own configuration through channel commands. This is a feature, but it can cause unexpected behavior changes.
Solution: You can disable this with channel-initiated config writes settings in your config file.
"API costs are higher than expected"
What is happening: Heavy use of powerful models (like Claude Opus) with large context windows can cost $30-50/day.
Solution: Monitor your API provider's usage dashboard. Consider using cheaper models for routine tasks and reserving expensive models for complex work. Local models through Ollama have zero API cost but are less capable.
"I lost two days of agent work to silent compaction"
What is happening: This is a known, documented issue (GitHub #5429). By default, compaction happens silently. The agent does not warn you, does not save state before compacting, and does not tell you what was lost afterward.
Solution: You can mitigate this by enabling memoryFlush in your compaction config with a threshold warning, and by instructing the agent in AGENTS.md to proactively save state. Some users configure a pre-compaction save prompt that fires automatically when context reaches 80%.
"The agent claims it completed a task but nothing happened on disk"
What is happening: This is a hallucination issue. The agent 'thinks' it performed an action but did not actually execute the tool call. This is more common with less capable models.
Solution: Check workspace files to verify actions were actually taken. Add instructions in AGENTS.md requiring the agent to verify its own work by reading files after writing them.
"My WhatsApp keeps disconnecting"
What is happening: WhatsApp uses an unofficial library (Baileys) that requires maintaining a persistent session. Phone restarts, WhatsApp updates, or being away too long can break the session.
Solution: You may need to re-scan the QR code. This is a platform limitation, not an OpenClaw bug. Some users report Telegram as more stable for always-on connections.
"I tried to run a task overnight and it killed the session by morning"
What is happening: Long-running tasks can exceed context limits, trigger compaction, or cause the session to reset at the daily reset time.
Solution: For overnight work, use sub-agents or isolated sessions with explicit state-saving instructions. Check your session reset schedule (default is 4 AM) and plan accordingly.
"Multiple onboarding attempts made things messy"
What is happening: Each onboarding attempt can leave behind partial configurations, conflicting instructions, and duplicate settings.
Solution: If your setup feels inconsistent, the cleanest fix is to back up your workspace files, delete ~/.openclaw/, and start fresh with a single clean onboarding run.
Best Practices from the Community
These practices come from experienced users who have learned through trial and error. Following them from the start will save you significant time and frustration.
Back up ~/.openclaw/ regularly
Your agent's entire soul, memory, credentials, and configuration live in this one folder. A simple backup command in Terminal can save you from catastrophic data loss. Exclude credentials/ from cloud backups for security.
Start minimal, expand gradually
One channel, one AI model, bundled skills only. Get that working and stable before adding complexity. Every new integration is a new potential failure point.
Never share credentials in chat
Store API keys, passwords, and tokens in configuration files or workspace environment files. Anything shared in conversation is temporary and vulnerable to session resets and compaction.
Instruct the agent to save important information
Add explicit instructions in AGENTS.md like: "Before any session ends or resets, save all important context, decisions, and action items to MEMORY.md." This compensates for the memory loss problem.
Run openclaw doctor regularly
After any configuration change, after updates, and periodically during normal operation. It catches problems before they become emergencies.
Keep OpenClaw updated
New versions fix bugs and security issues. Run: npm install -g openclaw@latest periodically. But read the release notes first - occasionally, updates introduce breaking changes.
Use a dedicated machine if possible
A Mac Mini or Raspberry Pi dedicated to OpenClaw isolates it from your personal data and reduces the blast radius of security issues.
Set the Gateway token
Even for local-only setups, a token adds a layer of protection in case someone gains local access to your machine.
Review what skills have access to
Periodically audit which skills are installed and what capabilities they have. Remove anything you are not actively using.
Understand session reset timing
Know when your sessions expire (default: 4 AM daily). If you are in the middle of a complex task at 3:55 AM, you are about to lose context. Either wrap up or save state explicitly.
Treat it like a new employee, not a magic wand
The most successful OpenClaw users describe the onboarding process like hiring an employee. You give it clear responsibilities, explicit instructions, defined boundaries, and you supervise it closely at first. Vague instructions like "be my assistant" produce vague results. Specific instructions like "check my email at 8am, summarize new messages, and flag anything from clients" produce specific, reliable behavior.
Use 'openclaw doctor --fix' as your first move
Before Googling, before posting to Discord, before trying random fixes - run the doctor. It catches and fixes the most common issues automatically. It is the single most underused command in the entire system.
Keep credentials out of chat, out of .bash_history, out of Git
If you type an API key in Terminal, it lives in your shell history. If you paste it into chat, it lives in the session transcript. Both are insecure. Store credentials in the config file or in ~/.openclaw/secrets/ with strict file permissions. If a credential leaks, rotate it immediately - do not debate whether it was actually exposed.
Appendix: Learning Path Summary
| Stage | What You Are Doing |
|---|---|
| Grammar (Weeks 1-2) | Learning vocabulary, naming parts, building definitions. Reading this guide, studying the glossary, internalizing the seven core components and file structure. No installation yet. The goal is to be able to define every term and component from memory. |
| Logic (Weeks 3-4) | Understanding relationships. Tracing message flows, understanding security layers, learning configuration logic, grasping how memory and sessions work, building a mental model. Still no installation - you are building the map before walking the territory. The goal is to be able to predict outcomes and explain cause-and-effect. |
| Rhetoric (Weeks 5+) | Applying knowledge. Installing, configuring, customizing, troubleshooting, and teaching. Every action is informed by Grammar and Logic. Problems become puzzles, not crises. The goal is confident, independent operation and the ability to teach others. |
Resources
Official Documentation
docs.openclaw.ai
GitHub Repository
github.com/openclaw/openclaw
DeepWiki (AI-analyzed docs)
deepwiki.com/openclaw/openclaw
Community Discord
Linked from openclaw.ai
Security Best Practices
docs.openclaw.ai (search "security")
OX Security Uninstall Guide
ox.security/blog (search "openclaw")
Mem0 Persistent Memory Plugin
docs.mem0.ai/integrations/openclaw
You Have Completed the Trivium
You now have the vocabulary (Grammar), the mental model (Logic), and the practical knowledge (Rhetoric) to use OpenClaw with confidence and mastery. This field guide will remain accessible as a reference whenever you need it.
"The Trivium does not teach you a subject. It teaches you how to learn a subject."
Compiled by Brad Costanzo of Accelerated Intelligence AI with the help of Claude
Acceleratedintelligence.ai