agent-architecture

OpenClaw Agent Architecture

When building or modifying an OpenClaw agent, follow this directory structure and these conventions.

Directory Structure

my-agent/
├── SOUL.md              # Agent identity, personality, rules
├── config.json          # Agent metadata and heartbeat config
├── MEMORY.md            # Persistent memory (agent reads/writes this)
├── tools/               # Tool scripts (Node.js, zero npm deps)
│   ├── ga4-report.cjs
│   ├── stripe-report.cjs
│   └── reddit-scan.cjs
├── secrets/             # API keys and credentials (never commit)
│   ├── ga4-credentials.json
│   └── .env
├── TOOLS.md             # Available commands and usage
├── HEARTBEAT.md         # Scheduled task definitions
├── USER.md              # User preferences and context
└── bot-telegram.cjs     # Telegram bot entry point

config.json

{
  "name": "AgentName",
  "role": "Role Description",
  "sessionKey": "agent:name:main",
  "heartbeat": { "interval": 0, "offset": 0 },
  "capabilities": ["list", "of", "capabilities"],
  "personality": {
    "tone": "analytical_concise",
    "verbosity": "moderate",
    "emoji_usage": "none"
  },
  "systemFiles": ["agents/name/SOUL.md"]
}

• heartbeat.interval: 0 means Telegram-only (no scheduled tasks via legacy heartbeat)
• Use ~/.openclaw/cron/jobs.json for scheduled tasks instead
• sessionKey format: agent:{name}:{scope}

Key Conventions

• Zero npm dependencies for tool scripts. Use Node.js built-in https, fs, path, crypto.
• CommonJS format (.cjs) for all scripts. OpenClaw runs scripts directly with node.
• Secrets in environment variables or secrets/ directory. Never hardcode API keys.
• MEMORY.md is the agent's long-term memory. The agent reads it at session start and writes to it when it learns something important. Keep it under 200 lines.
• TOOLS.md lists available commands. The agent reads this to know what scripts it can run.
• Each agent gets its own directory under agents/. Never share config files between agents.