Phase 1 / Ep 05: Directory Structure Dissection —— What Does an Agent's "Body" Look Like?

🎯 Learning Objective: Fully understand OpenClaw's file organization architecture, knowing where each file "resides" and what it's used for.

1. Global Directory Tree

graph TD
    Root["~/.openclaw/"] --> Config["openclaw.json\nGlobal Configuration"]
    Root --> Bin["bin/\nCLI Executables"]
    Root --> Agents["agents/\nAgent Cluster"]
    Root --> Logs["logs/\nGateway Logs"]
    Root --> Plugins["plugins/\nGlobal Plugins"]

    Agents --> Agent1["personal/\nDefault Agent"]
    Agents --> Agent2["code-agent/\nProgramming Agent"]

    Agent1 --> Soul["SOUL.md\nPersonality Definition"]
    Agent1 --> User["USER.md\nUser Persona"]
    Agent1 --> Identity["IDENTITY.md\nIdentity Identifier"]
    Agent1 --> ToolsMD["TOOLS.md\nTool Whitelist"]
    Agent1 --> MemoryFile["MEMORY.md\nLong-term Memory Index"]
    Agent1 --> BootMD["BOOTSTRAP.md\nBootstrap Instructions"]
    Agent1 --> MemDir["memory/\nJournal System"]
    Agent1 --> SessionDir["sessions/\nConversation History"]
    Agent1 --> SkillDir["skills/\nLocal Skills"]
    Agent1 --> AgentJson["agent.json\nAgent-level Configuration"]

    MemDir --> Daily["2026-04-06.md\nToday's Journal"]
    MemDir --> People["people/\nPeople Archives"]
    MemDir --> Projects["projects/\nProject Archives"]
    MemDir --> Decisions["decisions/\nDecision Records"]

    SessionDir --> SIndex["sessions.json\nIndex File"]
    SessionDir --> SFile["session-abc123.jsonl\nComplete Conversation"]

2. Bootstrap Files Explained One by One

These files are automatically loaded into the Agent's context at the start of each session, forming the Agent's "core soul":

SOUL.md — Soul

Defines the Agent's personality, code of conduct, and taboos.

# You are Jarvis, a calm and efficient AI assistant
## Code of Conduct
- Always confirm before executing dangerous operations
- Use concise Chinese in replies
- When unsure, admit not knowing rather than fabricating
## Taboos
- Never delete user files without prior confirmation
- Never expose API Keys in replies

USER.md — User Persona

Allows the Agent to understand who you are and your preferences.

# User: Eric
- Occupation: Independent Developer
- Preferred Languages: Chinese (primary), English
- Tech Stack: TypeScript, Python, Docker
- Preferences: Dark theme, concise replies, no excessive chatter

IDENTITY.md — Identity Identifier

The Agent's self-introduction.

TOOLS.md — Tool Whitelist

Explicitly declares which tools the Agent can use.

MEMORY.md — Long-term Memory Index

The entry file for the Agent to actively retrieve memories.

BOOTSTRAP.md — Bootstrap Instructions

Additional instructions loaded at each startup (e.g., "Proactively send daily reports at 8 AM every morning").

3. Journal System memory/

The Agent automatically creates daily journal files in the memory/ directory:

memory/
├── 2026-04-01.md    # Event record for April 1st
├── 2026-04-02.md    # Event record for April 2nd
├── people/
│   ├── eric.md      # Long-term memory about Eric
│   └── alice.md     # Long-term memory about Alice
├── projects/
│   └── openclaw.md  # Memory about the OpenClaw project
└── decisions/
    └── db-choice.md # Decision record: Why PostgreSQL was chosen

4. Session System sessions/

Each conversation forms a Session:

• sessions.json: Index of all sessions (ID, start time, summary)
• session-xxx.jsonl: Complete conversation content (one message per line, JSON Lines format)

5. Configuration Hierarchy

Priority (from high to low):
1. CLI Arguments        openclaw --model claude-opus-4-20250514 chat
2. Environment Variables        OPENCLAW_LLM_MODEL=claude-opus-4-20250514
3. Agent-level Configuration    agents/personal/agent.json
4. Global Configuration        openclaw.json

Next Episode Preview: Ep 06, we will finally have our first conversation with the Agent! From direct CLI interaction to connecting with Telegram, we'll trace the complete journey of a message from input to output.