Lesson 880 of 2116
OpenClaw Config And Project Layout
Where files live, what `openclaw.toml` controls, which env vars matter, and how to put the whole thing in version control without leaking secrets. Provider choice, default model, where files live, log level, default heartbeat cadence — all here.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1The default project shape
- 2openclaw.toml
- 3project layout
- 4environment variables
Concept cluster
Terms to connect while reading
Section 1
The default project shape
Every OpenClaw project — a personal one, a team one, a deployed one — converges on roughly the same layout. Knowing it cold lets you read someone else's project in minutes and lets you predict where to put new files without re-reading docs every time.
A canonical layout. souls, skills, and heartbeats are committed; memory and logs are not.
my-openclaw-project/
├── openclaw.toml # the main config — provider, paths, defaults
├── .env # secrets — gitignored, never committed
├── .env.example # safe template — committed, shows what is needed
├── souls/ # one file per soul
│ ├── ada.yaml
│ └── reviewer.yaml
├── skills/ # custom skills the soul can call
│ ├── send_email.py
│ ├── search_notes.py
│ └── manifest.yaml # which skills are enabled
├── heartbeats/ # autonomous loops
│ ├── morning_review.yaml # fires daily at 8am
│ └── slow_compactor.yaml # fires every 6 hours
├── memory/ # local memory store — gitignored
├── logs/ # session logs — gitignored
└── README.md # how to run this projectWhat openclaw.toml actually controls
The config file is the single source of truth for non-secret settings. Provider choice, default model, where files live, log level, default heartbeat cadence — all here. If you find yourself passing the same flag on the command line three times, it probably belongs in the config.
A workable openclaw.toml. Add sections as you need them; you do not need every block on day one.
# openclaw.toml — the project's default config
[provider]
name = "ollama"
base_url = "http://localhost:11434"
model = "qwen3:8b"
[fallback]
name = "anthropic"
model = "claude-sonnet-latest"
# api key comes from ANTHROPIC_API_KEY in .env — never inline here
[paths]
souls = "./souls"
skills = "./skills"
heartbeats = "./heartbeats"
memory = "./memory"
logs = "./logs"
[memory]
store = "local-vector"
retention_days = 30
[heartbeats]
enabled = true
min_interval_seconds = 60
[logging]
level = "info"
format = "jsonl"Environment variables that matter
Compare the options
| Variable | What it sets | Notes |
|---|---|---|
| OPENCLAW_HOME | Default project root | Set per project, not globally |
| ANTHROPIC_API_KEY | Cloud fallback auth | Required only if you set a fallback provider |
| OPENAI_API_KEY | Alternative cloud provider | Same — only if used |
| OPENCLAW_LOG_LEVEL | Override config log level | Useful for one-off debugging without editing config |
| OPENCLAW_MEMORY_DIR | Override memory location | Handy if you want shared memory across machines |
What to commit, what to ignore
- Commit: openclaw.toml, souls/*.yaml, skills/*.py, heartbeats/*.yaml, .env.example, README.md
- Ignore: .env, memory/ (long-term store), logs/, any local model weights that downloaded into the project
- Edge case: short, scrubbed sample memory used for tests can be committed under a tests/fixtures/ folder
- Edge case: shared team souls live in the repo; personal souls stay in `~/.openclaw/souls/` outside the project
Try it: convert your hello-world into a real project
- 1Create a fresh directory and run `git init`
- 2Drop in the canonical layout — empty souls/, skills/, heartbeats/ folders
- 3Move the soul you built last lesson into souls/ and add `openclaw.toml` pointing at it
- 4Write a `.env.example` listing every key your config could need (no real values)
- 5Add `.env`, `memory/`, and `logs/` to `.gitignore`, then make your first commit and inspect what actually landed in the diff
Key terms in this lesson
The big idea: predictable layout plus boring config plus disciplined gitignore equals a project anyone can clone and run. Get those three right on day one and the framework gets out of your way.
End-of-lesson quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “OpenClaw Config And Project Layout”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Creators · 10 min
The CLAUDE.md File: Project Persona And Rules
CLAUDE.md is how you tell Claude Code what your project values, what your team's conventions are, and what it should never do. It is the single highest-leverage config you write.
Creators · 9 min
What Perplexity Is: Search-Augmented LLM, Not A Chatbot
Perplexity is built around the idea that every answer should cite its sources. Treating it like ChatGPT misses the point — and the reliability gap that comes with it.
Creators · 10 min
Spaces: Building Team Knowledge Bases In Perplexity
Spaces are Perplexity's project containers — system prompts, files, and shared chat history. They turn the search engine into a research workspace.