Anatomy of a perfect Openclaw setup
Corey Ganim ยท tweet ยท 2026-04-10 Reader ๐ฅ๏ธ
Agent MemoryAgent SkillsAgent Context Files (CLAUDE.md / AGENTS.md)Long-Running & Managed AgentsOpenClaw
A well-configured OpenClaw workspace โ organized around a set of markdown files (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, TOOLS.md) plus skills, memory, and secrets folders โ is the key to making an AI assistant behave reliably and proactively, with AGENTS.md as the single highest-leverage file.
practical ยท tutorial/guide โ A comprehensive how-to guide for configuring an AI assistant workspace (OpenClaw/Clawdbot). Entirely practical โ focused on what to do and how to organize files.
Structure
| Part | Role |
|---|---|
| Two config layers, not one | Establishes the fundamental architecture: workspace (user customization) vs. global install (core system). |
| AGENTS.md: Your operating instructions | Presents the most important file โ the system prompt that governs all agent behavior. |
| SOUL.md, IDENTITY.md, USER.md | Describes supporting persona and relationship files that complement AGENTS.md. |
| HEARTBEAT.md | Explains scheduled/proactive behavior configuration. |
| TOOLS.md | Documents how external tools are used (conventions, not definitions). |
| skills/ folder | Introduces reusable, self-contained workflows with SKILL.md frontmatter. |
| memory/ folder | Describes persistent context and daily logging. |
| .secrets/ folder | Credential management guidance. |
| Channel configuration | Multi-channel messaging setup. |
| The full picture + practical setup | Synthesizes everything into a complete directory tree and a 6-step onboarding progression. |
Key terms
- AGENTS.md Agent Context Files (CLAUDE.md / AGENTS.md)
The primary configuration file loaded into the system prompt at session start; defines the agent's operating directives, rules, and tool usage conventions. - workspace Agent Context Files (CLAUDE.md / AGENTS.md)
The user's local configuration folder (e.g. ~/clawd/) containing all customization files, skills, memory, and secrets. - skill Agent Skills
A self-contained workflow defined by a SKILL.md file with YAML frontmatter, living in its own subdirectory, that the agent invokes when a task matches the skill's description. - heartbeat Long-Running & Managed Agents
A scheduled polling event where the agent checks if anything needs attention; configured via HEARTBEAT.md. - global install OpenClaw
The system-level installation directory containing core docs, built-in skills, and defaults โ updated but not customized by the user.
Propositions
- explicitAGENTS.md is the single highest-leverage file in an OpenClaw setup; getting it right matters more than everything else.conf: high
- explicitcorroboratedAGENTS.md should be kept under 300 lines because longer files consume too much context and reduce instruction adherence.conf: highsupports โAgent Skills ยท p11 โ Both claim context tokens degrade instruction adherence, motivating small instruction files and progressive disclosure of skills.
- explicitMost users fail to configure their workspace at all, which is a mistake because the workspace is the control center for agent behavior.conf: high
- implicitSeparating configuration into multiple specialized files (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, etc.) is better than a monolithic config because each file serves a different purpose and changes at a different rate.conf: high
- explicitMemory files are essential for cross-session continuity; without them, every conversation starts from zero.conf: high
- explicitA 6-step progressive setup (onboard, AGENTS.md, identity files, first skill, memory, TOOLS.md) covers 95% of use cases.conf: medium
Arguments
You should invest time configuring your OpenClaw workspace rather than using defaults. strength: medium
Explicit premises:
- Most users never open the workspace folder.
- The workspace is the control center for agent behavior.
- Not configuring it is a mistake.
Implicit premises:
- An AI assistant that follows your specific instructions is more valuable than one running on defaults.
- The time invested in configuration pays off through reduced correction and more useful output.
Inferences:
- Clear configuration leads to better agent behavior, which leads to more productive human-agent collaboration.
AGENTS.md should be concise (under 300 lines) rather than comprehensive. strength: medium
Explicit premises:
- Files longer than 300 lines eat too much context.
- Instruction adherence drops with longer files.
Implicit premises:
- LLM context windows have practical limits on how much instruction text remains effective.
- You can link to external documentation rather than inlining it.
Inferences:
- There is a trade-off between completeness and effectiveness in system prompts.
Narratives
- The typical user journey: install OpenClaw, connect a channel, never configure the workspace, and miss out on the tool's real power.
โ Motivates the reader to engage with the guide by framing the default behavior as a missed opportunity.
Questions addressed
- โ
What files and folders make up a complete OpenClaw workspace?
AGENTS.md, SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, TOOLS.md, BOOTSTRAP.md, plus skills/, memory/, .secrets/, and output/ directories. - โ
What is the most important file to configure and why?
AGENTS.md โ it is loaded into the system prompt and governs all agent behavior. - โ
How should you get started if setting up from scratch?
A 6-step progression: onboard, AGENTS.md, identity files, first skill, memory setup, then TOOLS.md. - โ
How does cross-session memory work?
Daily log files in memory/ folder; agent reads today + yesterday on session start.
Gaps
- evidenceThe 300-line threshold for AGENTS.md is asserted without evidence or benchmarks. No data on how instruction adherence degrades with file length.
Read next: LLM prompt engineering research on instruction-following vs. system prompt length.closed byAudit your Agent files โ Provides the missing evidence the earlier gap flagged as absent: a June 2026 study of 100 repositories quantifying how common configuration bloat/smells are (62% lint leakage, 42% context bloat, 35% skill leakage), plus Anthropic's own finding that cutting 80%+ of Claude Code's system prompt produced no measurable loss on internal evals โ direct (if imperfect) data bearing on instruction adherence versus file size. - omissionNo discussion of version control for workspace files, collaboration between multiple users, or backup strategies.
Read next: Best practices for managing AI agent configurations in team settings. - omissionNo mention of cost implications โ longer AGENTS.md means more tokens per session, which affects API costs.
Read next: Token economics of system prompt design. - commercialThe post is partly a lead-generation piece for the author's 'Build With AI' community, which may bias toward presenting OpenClaw as more powerful/important than alternatives.
Read next: Compare with other AI assistant frameworks (e.g., Claude Code's CLAUDE.md, Cursor rules, etc.).
Related documents
- JobRunr Introduces ClawRunr, an Open-Source Java AI Agent
- Audit your Agent files
- 10 Things Developers Want from their Agentic IDEs in 2025
- Paweล Huryn's Post
- Alex Wang's Post
- Developer Newsletter: higher usage limits, dreaming for Claude Managed Agents, and Claude Security
- Building AI Agents For The Enterprise
- Charlie Hills ๐ฆฉ's Post
- How Claude Code works in large codebases: Best practices and where to start
- Encoding Team Standards