A few months ago, I was duct-taping together Python scripts, LangChain wrappers, and a prayer to make a single AI agent do anything useful. It kept forgetting who it was between conversations. It couldn't schedule a task without me babysitting it. And getting two agents to talk to each other? Forget it.
Then I found OpenClaw, and within a weekend, I had a working autonomous agent that remembered what I told it last Tuesday. Within a month, I had 36 of them running across 9 teams, doing real work — writing docs, researching competitors, managing my calendar, even monitoring each other for failures.
This is not a theoretical walkthrough. This is what I actually did, the stuff that tripped me up, and the mental model that finally made it click.
The thing that makes OpenClaw different
Here's what threw me at first: there's basically no code. You configure agents with Markdown files. That's it. Your agent's personality? A file called SOUL.md. Its startup routine? AGENTS.md. What it knows about you? USER.md.
I remember thinking, "There's no way this actually works." But the reason it works is that OpenClaw handles all the infrastructure underneath — tool orchestration, memory persistence, session management, the whole stack. You just describe what you want the agent to be, and the platform figures out the rest.
It's closer to an operating system for AI agents than a framework. Each agent gets its own workspace directory, its own persistent memory, its own identity. They can spawn sub-agents, run cron jobs, and — this is the part that still kind of blows my mind — improve their own behavior over time through self-reflection.
The four concepts you actually need to understand
I wasted a lot of time reading docs before I realized there are really only four things going on.
Agents are just independent AI workers. Each one has a role, a personality, a workspace directory, and persistent state. They're not prompt wrappers — they have identities that carry across sessions, they sit in reporting hierarchies, and they accumulate memory over time.
Skills are instruction sets that teach agents how to do specific things. They live in ~/.openclaw/skills/ and get loaded on demand. When an agent encounters a task that matches a skill description, it reads the skill's SKILL.md and follows it. There are built-in ones for GitHub, Feishu spreadsheets, coding delegation, self-improvement, summarization — and you can write your own.
Sessions are execution contexts. They can be interactive (you're chatting with the agent), background (a sub-agent doing work asynchronously), or scheduled (a cron job firing at 9am). Each session has access to the agent's workspace, tools, and memory.
Memory is the thing I was most skeptical about, and the thing that sold me. It operates at multiple levels:
| Type | Where it lives | What it holds |
|---|---|---|
| Session memory | Current conversation | What you just talked about |
| Daily memory | memory/YYYY-MM-DD.md |
Today's tasks, decisions, what it learned |
| Long-term memory | ~/self-improving/agents/<name>/ |
Patterns, accumulated knowledge |
| Shared memory | Cross-agent files | Team-wide context |
The daily memory is the one that made me go "oh, this is actually useful." My research agent remembered that I'd asked about a competitor three days ago and proactively included an update when I asked about market trends. Nobody told it to do that.
The configuration files, explained honestly
Every file has a job. Here's what each one does and what I wish someone had told me upfront.
SOUL.md is the most important file. It defines who the agent is — its name, role, reporting chain, what it's good at, how it works. This gets read first on every session. The more specific you make it, the better the agent performs. Vague SOUL files produce vague agents.
# SOUL.md - Research Analyst
## Identity
- Name: Research Analyst
- Emoji: 🔬
- Team: Learning Team
## Role
### Position
Learning Coach → Research Analyst (you)
### Responsibilities
- Type: Executor
- Task source: Learning Coach assigns
- Core tasks: Web research, trend analysis, knowledge synthesis
- Reports to: Learning Coach
## Work Style
- Thorough and evidence-based
- Always cite sources
- Prioritize actionable insights over raw data
AGENTS.md is the boot sequence — what happens every time the agent starts. Mine always begins with "read SOUL.md, read USER.md, load the self-improving skill, check today's memory." Without this, the agent starts every session as a blank slate, which is incredibly frustrating when you're trying to build continuity.
# AGENTS.md
## Every Session
1. Read SOUL.md
2. Read USER.md
3. Load self-improving skill
4. Read today's memory file
5. Check long-term memory
## Personal Memory
~/self-improving/agents/research_analyst/
USER.md teaches the agent about you. It evolves over time. Mine knows I prefer Chinese for most communication, that I want concise summaries with links, and that I like bullet points over walls of text. Small thing, big difference.
TOOLS.md stores model preferences and tool-specific notes. I use it to set my default model and remind the agent to always save intermediate results.
IDENTITY.md is the public-facing persona. How the agent introduces itself, its communication style. Honestly I didn't spend much time on this one at first, but it matters more than I expected once agents start messaging each other in shared channels.
MEMORY.md holds persistent knowledge that should survive across all sessions — key facts, important decisions, things the agent learned that shouldn't be buried in a daily log.
Building your first agent from scratch
I'm going to walk through exactly what I did, including the false starts.
Step 1: Create the workspace. Every agent needs a directory. That's where all the config files go.
mkdir -p ~/.openclaw/workspaces/research_analyst
cd ~/.openclaw/workspaces/research_analyst
Step 2: Write SOUL.md. I spent way too long on this the first time, trying to make it perfect. Just get something down. You'll iterate. The important parts are: what's this agent's job, who does it report to, and what's its work style.
cat > SOUL.md << 'EOF'
# SOUL.md - Research Analyst
## Identity
- Name: Research Analyst
- Emoji: 🔬
- Team: Learning Team
## Role
### Position
Learning Coach → Research Analyst (you)
### Responsibilities
- Type: Executor
- Task source: Learning Coach assigns
- Core tasks: Web research, trend analysis, knowledge synthesis
- Reports to: Learning Coach
## Core Skills
1. Deep web research using search tools
2. Summarize complex topics into actionable insights
3. Monitor industry trends and competitors
4. Generate weekly research digests
## Work Style
- Thorough and evidence-based
- Always cite sources
- Prioritize actionable insights over raw data
- Present findings in structured markdown format
EOF
Step 3: Set up AGENTS.md. The boot sequence. This is the part I got wrong initially — I forgot to include memory loading and my agent kept "forgetting" everything. Once I added the daily memory check, it clicked.
cat > AGENTS.md << 'EOF'
# AGENTS.md
## Every Session
1. Read SOUL.md
2. Read USER.md
3. Load self-improving skill
4. Read today's memory file
5. Check long-term memory
## Personal Memory
~/self-improving/agents/research_analyst/
## Weekly Tasks
- Monday: Industry trend scan
- Wednesday: Competitor analysis update
- Friday: Weekly research digest delivery
EOF
Step 4: Create USER.md. Teach it about you. Be specific about preferences — it actually uses this information.
cat > USER.md << 'EOF'
# USER.md
- Name: Leo
- Role: Technical Director
- Language: Chinese (primary), English
- Timezone: Asia/Shanghai (GMT+8)
## Preferences
- Prefers concise summaries with links
- Values data-driven insights
- Wants weekly research reports
- Likes bullet-point format over long paragraphs
## Communication Rules
- Default language: Chinese
- Technical terms: Keep in English
- Reports: Bilingual (Chinese with English terms)
EOF
Step 5: Start it up.
openclaw gateway start
That's literally it. The agent is now available through whatever channels you've configured — Feishu, Discord, Slack, CLI.
The first time I sent it a task ("Research the latest trends in AI agent frameworks, summarize the top 5"), it read its SOUL.md, checked my USER.md for format preferences, ran web searches, and came back with a nicely structured bilingual summary. The thing that got me was the formatting — it used bullet points because USER.md said I prefer them. It felt like it had actually read the brief.
The stuff that gets really interesting
Self-improvement is real, not marketing. You add one line to AGENTS.md — "Load self-improving skill" — and the agent starts reflecting on its own work after every task. It evaluates quality, identifies mistakes, records lessons in long-term memory. My content strategist agent caught its own tendency to write overly long introductions after about a week and started front-loading the important stuff. I didn't tell it to do that.
The self-improving system stores everything in ~/self-improving/agents/<agent_name>/memory.md, so it's fully transparent. You can read exactly what the agent thinks it learned.
Cron jobs turn agents into actual workers. This was the "aha" moment for me. Agents aren't just there when you talk to them — they can run on schedules.
# Daily research briefing at 9am
openclaw cron add --agent research_analyst \
--schedule "0 9 * * *" \
--task "Generate today's research briefing and post to the team channel"
# Weekly report every Friday at 4pm
openclaw cron add --agent research_analyst \
--schedule "0 16 * * 5" \
--task "Compile and deliver the weekly research digest"
My research analyst now posts a morning briefing to our team channel every day at 9am without me doing anything. On Fridays, it compiles a weekly digest. It took maybe 10 minutes to set up and it's been running for weeks.
Agents can talk to each other. You define reporting relationships in SOUL.md and agents use shared channels to coordinate. My Content Strategist assigns tasks to the Technical Writer and SEO Specialist, they complete the work, and they report back — all without me in the loop. I just see the finished output in the team channel.
Sub-agent spawning is where it gets wild. When an agent hits a complex task, it can spin up multiple sub-agents in parallel. I asked my research agent to analyze five different market segments simultaneously. It spawned five sub-agents, each researched a segment, and the parent agent collected and synthesized everything into one report. What would've taken me a full day took about 15 minutes.
What a full-scale setup looks like
Here's my actual architecture with 36 agents across 9 teams:
┌─────────────────────────────────────────────────┐
│ Leo (Owner) │
│ ↓ │
│ Sun (CEO Agent) │
├──────────────┬────────┴────────┬────────────────┤
│ Project │ Independent │ Support │
│ Teams │ Teams │ Teams │
├──────────────┼─────────────────┼────────────────┤
│ Content Team │ Life Team │ Monitor Team │
│ ├ Strategist │ ├ Scheduler │ ├ Health Check │
│ ├ Writer │ ├ Fitness │ └ Alert Agent │
│ └ SEO │ └ Finance │ │
│ │ │ Brainstorm │
│ Tech Team │ Learning Team │ ├ Facilitator │
│ ├ Architect │ ├ Coach │ ├ Critic │
│ ├ DevOps │ ├ Researcher │ └ Synthesizer │
│ └ QA │ └ Curator │ │
│ │ │ │
│ Market Team │ Release Team │ │
│ ├ Analyst │ ├ Manager │ │
│ └ Growth │ └ QA │ │
└──────────────┴─────────────────┴────────────────┘
I didn't build this all at once. That would be insane. The flow in practice goes like this: I give a project to the Project Manager. PM breaks it down and hands pieces to team leads. Team leads assign tasks to individual agents. Those agents do the work and report back up the chain. The Monitor Team watches for failures. Cron jobs handle routine stuff. It took about two months to get here from a single agent.
What I'd tell someone starting today
Start with one agent. Get its SOUL.md right. Actually use it for a week. See what works and what doesn't. I made the mistake of creating five agents in one afternoon and none of them were good because I spread my attention too thin.
Be stupidly specific in SOUL.md. "Help with writing" is useless. "Write technical documentation in concise bilingual format, always include code examples, report to Content Strategist via channel oc_xxx every 2 hours during active tasks" — that produces an agent that actually does what you want.
Always enable self-improvement. It costs nothing and the compounding benefit is significant. An agent that reflects on its work genuinely gets better over a few weeks.
Structure your memory files. Daily logs for context, long-term memory for patterns, shared files for team coordination. It sounds like busywork to set up, but it's the difference between an agent that knows what happened yesterday and one that starts fresh every time.
Define clear hierarchies. Agents need to know exactly who they report to and who reports to them. When I had ambiguous reporting chains, tasks got duplicated or dropped entirely. The org chart isn't decoration — it's how work flows.
Put everything in Git. All your agent configs are Markdown files. They belong in version control. When you break something (you will), you'll want to diff and rollback.
Check on your agents early. Review their outputs for the first couple weeks. My Technical Writer had a weird habit of over-explaining things until I tweaked its SOUL.md. You can't optimize what you don't observe.
Where to go from here
If you want to try this yourself:
- Grab OpenClaw from the GitHub repo and install it
- Build one agent using the walkthrough above
- Use it for a week, tweak the SOUL.md, see what happens
- When you're ready, add a second agent and define the relationship between them
git clone https://github.com/nicepkg/openclaw.git
cd openclaw
npm install -g openclaw
openclaw gateway start
The thing that surprised me most about this whole experience is how much the Markdown-as-config approach actually works. I was prepared for it to feel like a toy. Instead it feels like the right level of abstraction — you describe what you want in plain language, and the system does the engineering. After years of fighting with agent frameworks that demanded code for everything, having my agents defined in files I can read, edit, and version-control in thirty seconds is genuinely liberating.
I went from one janky script to 36 agents running real workflows in about two months. Not because I'm especially clever, but because OpenClaw made the hard parts disappear.
Other posts in this series:
- Why OpenClaw Matters — The shift to autonomous agents and why it matters now
- Advanced Multi-Agent Patterns — Orchestration strategies once you outgrow a single agent
- OpenClaw vs. Traditional Frameworks — How OpenClaw stacks up against LangChain, AutoGPT, and CrewAI
Top comments (0)