Workspace Files, Day 16 of the Free Comprehensive OpenClaw Course

What is the complete OpenClaw workspace files reference?

OpenClaw workspace files are the contract between you and the runtime. Eight files plus a .env make up the entire surface most operators ever touch. The complete list:

• AGENTS.md, the operating manual, see openclaw agents.md.
• HEARTBEAT.md, the proactive automation file, see openclaw heartbeat.md.
• SOUL.md, the personality file, see openclaw soul.md.
• MEMORY.md, the long-term memory, see openclaw memory.md.
• SKILLS.md, index of installed Skills, see openclaw skills.
• TOOLS.md, declares which low-level tools the agent can call.
• KNOWLEDGE.md, reference material the agent can quote verbatim.
• CHANNELS.md, channel bindings and access control.
• .env, secrets (API keys, channel tokens). Never commit this.

That is the whole surface. Once you know what each one does, you can read any OpenClaw deployment in fifteen minutes.

Each file's purpose, format, and common patterns

AGENTS.md, the operating manual. Format: plain markdown with conventional sections (tool gates, sub-agent policies, spending caps, irreversible actions). Loaded on startup, requires restart on change. Common pattern: allowlist tools, gate destructive ones behind confirmation, set spending caps below your provider-side caps, list every irreversible action explicitly. Healthy size 2-4k tokens. See openclaw agents.md.

HEARTBEAT.md, the proactive instruction file. Format: plain markdown with sections per recurring concern. Loaded on every heartbeat tick, hot-reloads on edit. Common pattern: morning briefing, end of day wrap, system checks, deadline reminders, periodic reports. Each section names its schedule and the conditions for the agent to act. Healthy size 1-2k tokens. See openclaw heartbeat.md.

SOUL.md, the personality file. Format: plain markdown with voice, style rules, and boundaries sections. Loaded on every prompt, hot-reloads. Common pattern: rules over adjectives, negative rules over positive, specific habits over general principles. Healthy size 1-2k tokens. See openclaw soul.md.

MEMORY.md, the long-term memory. Format: plain markdown with sections like Identity, People, Active projects, Recurring rules, Recent decisions. Loaded on every prompt, hot-reloads, also subject to dreaming-process updates. Common pattern: durable facts only, prune monthly, let daily notes hold transient context. Healthy size 3-5k tokens. See openclaw memory.md.

SKILLS.md, index of installed Skills. Format: plain markdown with one entry per Skill, version pinned, source URL. Loaded on startup, requires restart on change. Common pattern: maintained automatically by the openclaw skill commands, you rarely edit by hand. See openclaw skills.

TOOLS.md, declares which low-level tools the agent can call. Format: plain markdown with one entry per tool. Loaded on startup, requires restart. Common pattern: lists exec, read, write, fetch, browser, calendar, email, etc. The actual permission for each tool is gated by AGENTS.md. Healthy size under 1k tokens.

KNOWLEDGE.md, reference material the agent can quote verbatim. Format: plain markdown with whatever structure makes sense for your domain (API docs, internal terminology, reference data). Loaded on every prompt, hot-reloads. Common pattern: information that needs exact quotes, not paraphrasing. Healthy size 2-5k tokens, paid on every prompt so curate.

CHANNELS.md, channel bindings and access control. Format: YAML or markdown, the runtime parses both. Loaded on startup, requires restart on change. Common pattern: per-channel enabled flag, allowlist of users, rendering mode, optional internal-channel definitions for multi-agent. See openclaw channels.

What is the OpenClaw bootstrap order?

The runtime loads files in a specific order on startup, and the order matters because some files reference others. The canonical order:

1. .env loads first. Without API keys, the runtime cannot proceed.
2. AGENTS.md loads second. The operating rules need to be in place before any tool can be called.
3. TOOLS.md loads third. Tool grants are gated by AGENTS.md, which is why AGENTS.md has to be loaded first.
4. SKILLS.md loads fourth. Each Skill's manifest is checked against the AGENTS.md tool grants, Skills that ask for ungranted tools are refused.
5. SOUL.md loads fifth. Personality applies to the agent's outputs once the operating rules are in place.
6. MEMORY.md loads sixth. Long-term memory is loaded into the agent's context.
7. HEARTBEAT.md loads seventh. The recurring tick is scheduled.
8. CHANNELS.md loads last. The agent connects to its channels and the runtime is live.

Most file edits do not require a restart, the runtime hot-reloads. The exceptions: tool grants in AGENTS.md, channel bindings in CHANNELS.md, and Skill installs all require a restart. Everything else is hot.

Config reload behavior, hot versus cold

The hot/cold split is worth memorizing because it affects how you operate the agent day to day. Hot reload (no restart needed): SOUL.md, MEMORY.md, HEARTBEAT.md, KNOWLEDGE.md edits. The runtime watches these files and re-loads on save. Useful for live tuning during a conversation, edit SOUL.md, the next prompt picks up the change.

Cold reload (restart required): AGENTS.md tool grants, CHANNELS.md channel bindings, SKILLS.md Skill list, TOOLS.md tool definitions, .env environment variables. The runtime parses these once at startup. Edit, then docker compose restart openclaw or your equivalent. The restart is fast (5 to 15 seconds), the agent picks up the change immediately on next prompt.

The reason for the split is performance and safety. Hot-reloading the tool gates while a tool call is mid-flight could authorize an unauthorized call. Hot-reloading the channels could disconnect the agent from a user mid-conversation. The cold reload contract is "you explicitly restarted, you know what changed". The hot reload contract is "this file change is safe to apply mid-prompt".

Session management and runtime state

Beyond the workspace files, the runtime manages two kinds of state. Conversation state, which lives in the daily notes folder and the embedding index. New conversations append to today's daily note, the embedding index is rebuilt incrementally as files change. This state is rebuildable from the conversation logs but you do not want to lose it routinely.

Cache state, which lives in a runtime-managed folder (typically ~/.openclaw/cache or ./cache inside the workspace). Includes the parsed tool-grant tree, the loaded MEMORY.md tokenization, the prompt cache locator references, the embedding model weights. This state is fully rebuildable, deleting the cache folder forces a clean reload on next startup.

If the agent starts behaving strangely after a config change, deleting the cache folder is the first thing to try. The cache can occasionally hold a stale view of a hot-reloaded file. The rebuild on next start is fast, less than 30 seconds in most setups.

What does the OpenClaw security audit checklist cover?

Before any production deploy, run through the checklist. Every item maps to a real failure I have seen in client work.

• AGENTS.md uses allowlists, not blocklists, for tools and channels.
• Destructive tools (write, exec, browser) are gated behind explicit confirmation, not enabled silently.
• Channel allowlists name specific usernames or numbers, never wildcards.
• The .env file is not in git. git status should not show it as a tracked file.
• Provider spending caps are set on Anthropic, OpenAI, Gemini, every key in your .env, even unused fallbacks.
• The deployment runs in Docker with strict sandbox mode, see openclaw docker.
• SSH key only on the host VPS, password auth disabled, see openclaw vps deployment.
• Liveness ping is wired and pointing at an external monitor.
• Daily cost report is wired and posting to your main channel.
• OpenClaw version pinned in Dockerfile, not :latest.
• Skills installed from ClawHub were each manifest-reviewed before install.

The architecture map

One mental model that ties everything together. The runtime is a loop. The loop reads the workspace files on every tick, reasons over them with a model, and (sometimes) acts. Acts means calling a tool or sending a channel message. The workspace files split into three categories.

Identity, who the agent is: SOUL.md, MEMORY.md.

Rules, what the agent can do: AGENTS.md, TOOLS.md, SKILLS.md, CHANNELS.md.

Behavior, what the agent decides to do on its own: HEARTBEAT.md.

Plus the .env for secrets, and the implicit fourth category, the model on the other end of the wire and the channels on the user-facing side.

If you can hold this map in your head, you can debug anything in the runtime. Almost every problem traces back to one of these files being wrong, and most of the time the wrongness is a missing rule (AGENTS.md), a stale fact (MEMORY.md), or a too-tight heartbeat (HEARTBEAT.md). Read the file, find the issue, edit, restart if needed. That is the whole operations story.

How this connects to your full agent

This finale ties together every previous lesson. What is openclaw on day 1 set the mental model, days 2 through 5 covered install plus the model and channel layer, days 6 through 9 walked the workspace files that give the agent its mind, days 10 and 11 added Skills and integrations, days 12 and 13 covered the production deploy, and days 14 and 15 covered the advanced patterns of agentic coding and multi-agent.

The right post-course path. Spend a week using the agent you built. Edit MEMORY.md and SOUL.md as you spot the agent missing. Add one new Skill from ClawHub. Add one new custom Skill for your specific workflow. Tune the heartbeat interval based on what the log shows. After a month, you will have an agent that feels like it has known you longer than it has, and you will understand the runtime well enough to debug anything that comes up.

The free comprehensive OpenClaw course ends here. If you have walked all 16 lessons, you have everything you need to ship a production agent. If you want help shipping one, the hire openclaw expert page walks how to apply.