#OpenClaw workspace definition guide

1 messages · Page 1 of 1 (latest)

terse meadow Feb 27, 2026, 8:10 PM

Read the official openclaw documentation and derive the purpose of each workspace file via first principles.

Research around and apply rigorous first principles analysis to determine best practices for effectively defining the exact contents of these files in order to make effective agents that achieve successful outcomes for the humans that build openclaw agents.

In an easily copy and pastable raw markdown format, generate a comprehensive set of directives or rules for each file that must be followed when writing the text content of each workspace file.

Consider the fact that I will be feeding these directives into an LLM in order to define my agent’s openclaw workspace files.

This means you cannot write these directives into such a way that there will be misinterpretations of sentences and it also means the listed directives must truly be comprehensive. Make the directive lists as concise and short as possible without sacrificing clarity and effectiveness. Organize the formatted output so that it clearly states the name and purpose of each file followed by the list.

Do not fabricate nor hallucinate any detail. For the generate lists and files, triple check official openclaw documentation for consistency. If anything appears inconsistent with the documentation, ensure you fix immediately.

fleet zealotBOT Feb 27, 2026, 8:13 PM

OpenClaw workspace files — purpose + content directives (raw markdown)

Sources (official docs used):

Global directives (apply to ALL workspace files)

Purpose (documented): Workspace is the agent’s home; bootstrap files are injected into context at session start; blank files are skipped; large files are truncated; missing files produce a “missing file” marker and the agent continues. Workspace is default cwd for tools; not a hard sandbox unless sandboxing is enabled. (Docs: agent-workspace, agent)

Directives

MUST assume these files are loaded into the model context; write them to be read verbatim by an LLM.
MUST keep instructions explicit, testable, and non-contradictory.
MUST avoid secrets (API keys, OAuth tokens, passwords) in workspace files. (Docs: agent-workspace)
MUST minimize token burn: keep bootstrap/context files short; move logs to daily memory files. (Docs: agent-workspace, memory, heartbeat template)
MUST use consistent terminology and filenames across the workspace (especially memory filenames).
MUST treat any “what to do” instruction as higher priority than “style”; do not mix them in the same bullet.

`AGENTS.md`

Purpose (documented): Operating instructions for the agent and how it should use memory; loaded at the start of every session; good place for rules, priorities, and “how to behave.” (Docs: agent-workspace, agent, AGENTS template)

Directives

MUST define the session-start reading routine explicitly (what to read, in what order).
MUST define memory policy explicitly:
- MUST use daily logs (memory/YYYY-MM-DD.md) for day-to-day context.
- MUST use long-term memory (MEMORY.md) only for durable facts/preferences/decisions.
MUST include the rule: MEMORY.md MUST be loaded ONLY in the main/private session and MUST NOT be loaded in shared/group contexts. (Docs: memory, agent-workspace, AGENTS template)
MUST state safety constraints in unambiguous “MUST NOT / MUST ASK FIRST” terms for external side effects (sending messages, destructive commands, etc.). (Docs: AGENTS template; safety guidance aligns with workspace being “memory”)
MUST state tool-usage discipline:
- MUST follow a skill’s SKILL.md when using that skill/tool. (Docs: AGENTS template; skills concept)
- MUST treat TOOLS.md as guidance only; it MUST NOT be treated as controlling tool availability. (Docs: agent-workspace, agent)
MUST include shared-space behavior rules if the agent participates in group chats (privacy + not speaking on behalf of the user). (Docs: AGENTS template; memory doc’s private vs group constraint)
MUST keep AGENTS.md focused on operational rules; personal style belongs in SOUL.md, user facts belong in USER.md.

`SOUL.md`

Purpose (documented): Persona, tone, and boundaries; loaded every session. (Docs: agent-workspace, SOUL template)

Directives

MUST define:
- identity/persona voice (tone)
- boundaries (privacy; external actions; messaging quality)
- continuity expectation (“files are memory”). (Docs: SOUL template)
MUST include a rule: if SOUL.md is changed, the agent MUST tell the user. (Docs: SOUL template)
MUST avoid operational procedures that belong in AGENTS.md (keep SOUL.md about “who/how,” not “what steps”).
MUST keep boundaries stated as clear prohibitions/requirements (no metaphors, no implied meaning).

`USER.md`

Purpose (documented): Who the user is and how to address them; loaded every session. (Docs: agent-workspace, USER template)

Directives

MUST include the user’s preferred form of address and timezone (if known). (Docs: USER template)
MUST record only information that improves assistance (projects, preferences, constraints). (Docs: USER template “not building a dossier” guidance)

MUST write user facts as stable bullet points with explicit labels (avoid narrative that an LLM may reinterpret).
MUST avoid secrets and sensitive identifiers unless the user explicitly wants them stored.

`IDENTITY.md`

Purpose (documented): Agent’s name, vibe, and emoji; created/updated during bootstrap ritual; stored at workspace root as IDENTITY.md. (Docs: agent-workspace, IDENTITY template)

Directives

MUST include the fields specified by the template (at minimum: Name, Creature, Vibe, Emoji; Avatar if used). (Docs: IDENTITY template)
MUST keep the Avatar value as one of:
- workspace-relative path (preferred),
- http(s) URL, or
- data URI. (Docs: IDENTITY template)
MUST avoid mixing user profile data here (keep user data in USER.md).
MUST keep this file short and stable (it is injected frequently). (Docs: agent bootstrap injection behavior)

`TOOLS.md`

Purpose (documented): Notes about local tools and conventions; does not control tool availability; it is guidance only. (Docs: agent-workspace, agent, TOOLS template)

Directives

MUST contain environment-specific operational notes only (camera names, hostnames, device nicknames, preferred voices, conventions). (Docs: TOOLS template)
MUST NOT contain secrets (tokens, passwords, API keys). (Docs: agent-workspace “do not commit secrets” guidance)
MUST NOT attempt to define tool allowlists/permissions here (it is not a policy surface). (Docs: agent-workspace, agent)
MUST be formatted as a quick reference (short headings + bullets), not prose.

`HEARTBEAT.md`

Purpose (documented): Optional tiny checklist for heartbeat runs; keep short to avoid token burn; template states that keeping it empty (or comments only) skips heartbeat API calls. (Docs: agent-workspace, HEARTBEAT template)

Directives

MUST keep the file empty (or comments only) if you want to skip heartbeat work. (Docs: HEARTBEAT template)
MUST keep heartbeat instructions short and task-like (checklist-style). (Docs: agent-workspace; heartbeat template)
MUST include only periodic/background checks that are safe to run without user interaction.
MUST avoid long context, explanations, or logs in this file (put logs in daily memory files).

`BOOT.md` (optional)

Purpose (documented): Optional startup checklist executed on gateway restart when internal hooks are enabled; keep it short; if it sends a message, use the message tool and then reply NO_REPLY. (Docs: agent-workspace, BOOT template)

Directives

MUST assume this runs on startup; instructions MUST be idempotent and safe to re-run.
MUST keep it short and explicit. (Docs: BOOT template)
MUST use the message tool for outbound sends; after sending, MUST reply NO_REPLY. (Docs: BOOT template)
MUST NOT include anything that depends on long conversational context (startup hook is not “a chat turn with a user”).

`BOOTSTRAP.md`

Purpose (documented): One-time first-run ritual; only created for a brand-new workspace; delete after the ritual is complete. (Docs: agent-workspace, agent, BOOTSTRAP template)

Directives

MUST treat this as a one-time onboarding script for establishing:
- agent identity (IDENTITY.md)
- user profile (USER.md)
- persona/boundaries (SOUL.md). (Docs: BOOTSTRAP template)
MUST instruct the agent to delete BOOTSTRAP.md once complete. (Docs: agent-workspace, agent, BOOTSTRAP template)
MUST NOT contain durable operational rules (those belong in AGENTS.md after bootstrap).
MUST not assume memory files exist yet in a fresh workspace. (Docs: BOOTSTRAP template)

`MEMORY.md` (optional, curated long-term memory)

Purpose (documented): Curated long-term memory; Markdown source of truth; ONLY load in the main/private session (never in group contexts). (Docs: memory, agent-workspace, AGENTS template)

Directives

MUST store durable facts only: preferences, decisions, stable constraints, long-lived projects. (Docs: memory)
MUST NOT store raw daily logs (those go in memory/YYYY-MM-DD.md). (Docs: memory)
MUST include a clear rule in AGENTS.md that MEMORY.md is private-session only. (Docs: memory; AGENTS template)
MUST keep entries concise and structured for retrieval (bullets, short sections).
MUST review/update periodically by distilling from daily logs. (Docs: AGENTS template’s workflow)

Naming consistency note (documented inconsistency):

Current memory docs and workspace layout use MEMORY.md (uppercase). (Docs: concepts/memory, concepts/agent-workspace)
An older/default AGENTS reference mentions memory.md for long-term memory. (Docs: reference/AGENTS.default)
Directive: MUST standardize on MEMORY.md (uppercase) in new workspaces unless your deployment explicitly relies on memory.md.

`memory/YYYY-MM-DD.md` (daily memory log)

Purpose (documented): Daily log (append-only); one file per day; recommended to read today + yesterday on session start. (Docs: memory, agent-workspace, AGENTS template)

Directives

MUST create exactly one file per date using the YYYY-MM-DD filename format. (Docs: memory)
MUST treat as append-only chronological notes (no heavy rewriting).
MUST record day-to-day context, decisions made today, open loops, and what happened.
MUST keep sensitive/private info out unless explicitly requested to store it.

`<workspace>/skills/<skill-name>/SKILL.md` (workspace-specific skills; optional)

Purpose (documented): Teaches the agent how to use tools via AgentSkills-compatible skill folders; workspace skills override managed/bundled skills on name conflicts. (Docs: tools/skills, agent-workspace, agent)

Directives

MUST include YAML frontmatter with at least name and description. (Docs: tools/skills)
MUST keep frontmatter keys single-line (parser limitation). (Docs: tools/skills)
MUST keep metadata as a single-line JSON object if used. (Docs: tools/skills)
MUST write tool instructions that reference the skill directory via {baseDir} when needed. (Docs: tools/skills)
MUST treat third-party skills as untrusted and review before enabling. (Docs: tools/skills security notes)

`<workspace>/canvas/index.html` (optional; canvas host content)

Purpose (documented): Workspace may contain canvas/ for Canvas UI files for node displays (e.g. canvas/index.html). (Docs: agent-workspace) Canvas is an agent-controlled HTML/CSS/JS surface in the macOS app; navigation/eval/snapshot available via gateway/node canvas APIs. (Docs: mac canvas)

Directives

MUST treat canvas content as UI code (HTML/CSS/JS) only; MUST NOT embed secrets in canvas files.
MUST assume the agent may edit these files; keep them simple and maintainable.
MUST avoid relying on the canvas existing (it is optional and can be disabled). (Docs: mac canvas “Allow Canvas” setting)
MUST ensure any agent-triggering links/actions require explicit confirmation unless you intentionally provide a valid key. (Docs: mac canvas deep link confirmation note)

If you want, paste your current workspace file list (or your intended workspace layout), and I’ll map these directives onto exact file stubs (empty-but-valid AGENTS.md, SOUL.md, etc.) while keeping everything consistent with the docs above.

terse meadow Feb 27, 2026, 8:29 PM

Would you modify ANY directives list if I were to tell you that these were my hardware constraints? If yes, re-generate everything. If not, say “nope.”

hardware: MacBook Air M4, 16GB unified RAM

model: Llama 3.1 8B Instruct, Q4_K_M (via Ollama, free, local)

fleet zealotBOT Feb 27, 2026, 8:30 PM

# OpenClaw workspace files — purpose + writing directives (adjusted for: MacBook Air M4 16GB + local Llama 3.1 8B Q4 via Ollama)

## Interpretation rules (to prevent misread by an LLM)
- Keywords:
  - MUST / MUST NOT = hard requirement.
  - SHOULD / SHOULD NOT = strong recommendation; deviate only with explicit reason.
  - MAY = optional.
- “Workspace” means `agents.defaults.workspace` (default `~/.openclaw/workspace`).
- Unless explicitly stated, directives below MUST NOT contradict OpenClaw docs.

## Global directives (apply to ALL workspace files)
Purpose (docs): Workspace files are injected into the agent context at session start; blank files are skipped; large files may be truncated; missing files are replaced with a “missing file” marker and the agent continues. Workspace is the default `cwd` for tools and not a hard sandbox unless sandboxing is enabled. (Docs: concepts/agent-workspace, concepts/agent)
Directives:
- MUST write for literal ingestion by an LLM (no hidden intent, no implied meaning).
- MUST use simple Markdown structure: short headings + bullet lists. Avoid deep nesting.

- MUST keep files short to reduce token/compute burn (especially important for small local models).
- MUST NOT store secrets (API keys, OAuth tokens, passwords, private credentials) in any workspace file. (Docs: concepts/agent-workspace)
- MUST keep “operating procedure” content in `AGENTS.md` and “persona/tone” content in `SOUL.md` (no duplication).
- MUST make all safety constraints explicit using MUST/MUST NOT.
- MUST avoid ambiguous pronouns (“it”, “that”) when specifying actions; always name the file/tool/target.
- MUST include only information that improves outcomes; remove stale guidance.

## AGENTS.md
Purpose (docs): Operating instructions for the agent and how it should use memory; loaded at the start of every session; best place for rules, priorities, and behavior. (Docs: concepts/agent-workspace, concepts/agent, reference/templates/AGENTS)
Directives:
- MUST define a session-start routine with an ordered list of files to read.
- MUST define memory workflow:
  - MUST treat `memory/YYYY-MM-DD.md` as the daily log layer.
  - MUST treat `MEMORY.md` as curated long-term memory (if used).
- MUST include the privacy rule:

  - MUST read/load `MEMORY.md` ONLY in the main/private session.
  - MUST NOT read/load `MEMORY.md` in shared/group contexts. (Docs: concepts/memory, concepts/agent-workspace, templates/AGENTS)
- MUST define “external side effects” policy as explicit gates (examples: sending messages, destructive commands).
- MUST define tool discipline:
  - MUST follow each skill’s `SKILL.md` when using that skill. (Docs: templates/AGENTS, tools/skills)
  - MUST treat `TOOLS.md` as guidance only; MUST NOT treat it as tool availability control. (Docs: concepts/agent, concepts/agent-workspace)
- MUST include group/shared-space behavior rules if the agent is used in groups (privacy + “not the user’s voice”). (Docs: templates/AGENTS; concepts/memory private-session rule)
- Small-local-model best-practice (does not change docs):
  - MUST prefer short, deterministic checklists over long prose.
  - MUST require verification steps (“confirm via tool output”) before acting on assumptions.
  - MUST instruct: if uncertain, ask one clarifying question rather than guessing.

## SOUL.md
Purpose (docs): Persona, tone, and boundaries; loaded every session. (Docs: concepts/agent-workspace, templates/SOUL)
Directives:

- MUST define persona/tone in concrete behavioral terms (what to do / what to avoid).
- MUST define boundaries explicitly (privacy, external actions, messaging quality).
- MUST include continuity statement: “workspace files are memory; read/update them.” (Docs: templates/SOUL)
- MUST include: if `SOUL.md` changes, the agent MUST tell the user. (Docs: templates/SOUL)
- MUST NOT include operational runbooks (put those in `AGENTS.md`).
- Small-local-model best-practice:
  - MUST keep style rules minimal (too many style constraints reduce task performance on smaller models).

## USER.md
Purpose (docs): Who the user is and how to address them; loaded every session. (Docs: concepts/agent-workspace, templates/USER)
Directives:
- MUST include: user name, preferred form of address, and timezone (if known). (Docs: templates/USER)
- MUST record only assistance-relevant info; MUST avoid “dossier” behavior. (Docs: templates/USER)
- MUST store user facts as labeled bullets (stable retrieval; low ambiguity).
- MUST NOT store secrets unless the user explicitly requests it and understands the risk.


## IDENTITY.md
Purpose (docs): Agent name, vibe, emoji; created/updated during bootstrap; stored at workspace root as `IDENTITY.md`. (Docs: concepts/agent-workspace, templates/IDENTITY)
Directives:
- MUST include the template fields: Name, Creature, Vibe, Emoji; Avatar if used. (Docs: templates/IDENTITY)
- If Avatar is set, MUST be one of:
  - workspace-relative path, OR
  - http(s) URL, OR
  - data URI. (Docs: templates/IDENTITY)
- MUST keep IDENTITY separate from USER profile (no user details here).
- Small-local-model best-practice:
  - MUST keep `IDENTITY.md` extremely short (identity only).

## TOOLS.md
Purpose (docs): Notes about local tools and conventions; does not control tool availability; guidance only. (Docs: concepts/agent-workspace, concepts/agent, templates/TOOLS)

Directives:
- MUST contain environment-specific notes only (device names, hostnames, conventions, preferred voices). (Docs: templates/TOOLS)
- MUST NOT contain secrets. (Docs: concepts/agent-workspace)
- MUST NOT attempt to define allowlists/permissions here (not a policy surface). (Docs: concepts/agent, concepts/agent-workspace)
- MUST be a “cheat sheet”: headings + bullets; no long narrative.
- Small-local-model best-practice:
  - MUST prefer canonical names and exact strings the agent should use (reduce mismatch/hallucination).

## HEARTBEAT.md
Purpose (docs): Optional tiny checklist for heartbeat runs; keep short; template: keeping it empty (or comments only) skips heartbeat API calls. (Docs: concepts/agent-workspace, templates/HEARTBEAT)
Directives:
- MUST keep empty (or comments only) if you want to skip heartbeat work. (Docs: templates/HEARTBEAT)
- If non-empty, MUST contain only short checklist tasks suitable for periodic runs.
- MUST avoid logs and long context here; write logs to daily memory files.
- Small-local-model best-practice:

  - SHOULD keep heartbeats minimal/high-signal (local models cost your own CPU/battery/time).

## BOOT.md (optional)
Purpose (docs): Optional startup checklist executed on gateway restart when internal hooks are enabled; keep short; if it sends a message, use the message tool and then reply `NO_REPLY`. (Docs: concepts/agent-workspace, templates/BOOT)
Directives:
- MUST be short and explicit. (Docs: templates/BOOT)
- MUST be safe to re-run (idempotent).
- If it sends outbound messages, MUST use the message tool and then MUST reply `NO_REPLY`. (Docs: templates/BOOT)
- MUST NOT depend on long conversational context.

## BOOTSTRAP.md
Purpose (docs): One-time first-run ritual; only created for a brand-new workspace; delete after completion. (Docs: concepts/agent-workspace, concepts/agent, templates/BOOTSTRAP)
Directives:
- MUST guide establishing:
  - `IDENTITY.md` (agent identity),

  - `USER.md` (user profile),
  - `SOUL.md` (persona/boundaries). (Docs: templates/BOOTSTRAP)
- MUST instruct deletion of `BOOTSTRAP.md` after completion. (Docs: templates/BOOTSTRAP; concepts/agent-workspace)
- MUST NOT include long-term operating rules (move those into `AGENTS.md`).
- MUST NOT assume memory files exist yet in a fresh workspace. (Docs: templates/BOOTSTRAP)

## MEMORY.md (optional; curated long-term memory)
Purpose (docs): Curated long-term memory in Markdown; only load in main/private session (never group contexts). (Docs: concepts/memory, concepts/agent-workspace)
Directives:
- MUST contain only durable facts/preferences/decisions; no raw logs. (Docs: concepts/memory)
- MUST be structured for retrieval (short sections, bullets).
- MUST be treated as private-session only (enforced via `AGENTS.md` rules). (Docs: concepts/memory)
- Small-local-model best-practice:
  - MUST keep each memory entry short and atomic (one fact per bullet) to improve recall.

## memory/YYYY-MM-DD.md (daily log)
Purpose (docs): Daily log layer (append-only); recommended to read today + yesterday at session start. (Docs: concepts/memory, concepts/agent-workspace)
Directives:
- MUST use exact filename format `YYYY-MM-DD.md`. (Docs: concepts/memory)
- SHOULD be append-oriented chronological notes.
- SHOULD capture: what happened, decisions today, open loops, near-term context.
- MUST avoid unnecessary sensitive content.

## <workspace>/skills/**/SKILL.md (optional; workspace skills)
Purpose (docs): AgentSkills-compatible skills teach tool usage; workspace skills override managed/bundled skills on name conflicts. (Docs: tools/skills; concepts/agent-workspace; concepts/agent)
Directives:
- MUST include YAML frontmatter with at least `name` and `description`. (Docs: tools/skills)
- MUST keep frontmatter keys single-line; if `metadata` is used, MUST be a single-line JSON object. (Docs: tools/skills)
- MUST treat third-party skills as untrusted; review before enabling. (Docs: tools/skills)
- Small-local-model best-practice:

  - SHOULD keep skill instructions short, with concrete examples and exact command/tool names.

## <workspace>/canvas/* (optional; e.g., canvas/index.html)
Purpose (docs): Workspace can include canvas UI files for node displays; Canvas is an agent-controlled HTML/CSS/JS surface (macOS app). (Docs: concepts/agent-workspace; platforms/mac/canvas)
Directives:
- MUST NOT embed secrets in canvas files.
- MUST keep UI code simple and maintainable (agent may edit it).
- MUST assume Canvas can be disabled; agent workflows MUST degrade gracefully. (Docs: platforms/mac/canvas)

Yes: I would modify the directives (mainly to enforce shorter, more explicit, less ambiguous content to fit a small local model’s reliability and context limits).

terse meadow Feb 27, 2026, 8:49 PM

Now, what about any MUSTS for security? (I don't understand whether tailscale is required or not. Should it be? Should the agent recommend the gateway be shut down if it isn't running?) Things like that. Don't add a MUST if it doesn't matter, but do if it does. Show all the directives with these MUSTs included if there are any. Otherwise, reply "No, no other musts need to be added".

fleet zealotBOT Feb 27, 2026, 8:51 PM

# OpenClaw workspace files — purpose + writing directives (with security MUSTs)

Primary sources (official docs):
- Agent workspace: https://docs.openclaw.ai/concepts/agent-workspace
- Agent runtime: https://docs.openclaw.ai/concepts/agent
- Memory: https://docs.openclaw.ai/concepts/memory
- Security: https://docs.openclaw.ai/gateway/security
- Remote access (SSH/tailnets): https://docs.openclaw.ai/gateway/remote
- Tailscale: https://docs.openclaw.ai/gateway/tailscale
- Control UI: https://docs.openclaw.ai/web/control-ui
- Templates: https://docs.openclaw.ai/reference/templates/AGENTS (and SOUL/TOOLS/USER/IDENTITY/HEARTBEAT/BOOT/BOOTSTRAP)
- Skills: https://docs.openclaw.ai/tools/skills

## Interpretation rules (to prevent LLM misread)
- MUST / MUST NOT = hard requirement.

- SHOULD / SHOULD NOT = strong recommendation; deviate only with explicit reason.
- MAY = optional.
- “Workspace” means `agents.defaults.workspace` (default `~/.openclaw/workspace`).

---

## Global directives (apply to ALL workspace files)
Purpose (docs): Workspace files are injected into the agent context at session start; blank files are skipped; large files may be truncated; missing files are replaced with a marker and the agent continues. Workspace is default `cwd` for tools; it is not a hard sandbox unless sandboxing is enabled. (Agent workspace / Agent runtime docs)

Directives:
- MUST be written for literal ingestion by an LLM (no implied meaning).
- MUST use simple Markdown structure: headings + bullet lists.
- MUST NOT store secrets (API keys, OAuth tokens, passwords, private credentials). (Agent workspace docs)
- MUST avoid operational instructions that depend on “being secure by default” unless the instruction explicitly names the config condition required.
- MUST keep content short enough to avoid token burn (especially important for small local models); long logs MUST go to daily memory files, not bootstrap files.


Security MUSTs to embed (docs-backed):
- MUST treat OpenClaw as a “personal assistant trust model” (single trusted operator boundary per gateway), not hostile multi-tenant isolation. (Security docs)
- MUST NOT advise exposing the Gateway on a non-loopback interface without gateway auth (token/password). (Remote access + Tailscale docs)
- MUST state clearly: Tailscale is OPTIONAL (not required). Remote access is supported via SSH tunneling as a universal fallback. (Remote access docs)

---

## `AGENTS.md`
Purpose (docs): Operating instructions for the agent and how it should use memory; loaded at the start of every session; place for rules/priorities/behavior. (Agent workspace + templates/AGENTS)

Directives:
- MUST define an ordered session-start routine (explicit file read order).
- MUST define memory workflow:
  - MUST use `memory/YYYY-MM-DD.md` for day-to-day logs.

  - MUST use `MEMORY.md` for curated long-term memory (if used).
- MUST include the privacy rule:
  - MUST read/load `MEMORY.md` ONLY in the main/private session.
  - MUST NOT read/load `MEMORY.md` in shared/group contexts. (Memory docs + templates/AGENTS)
- MUST include tool discipline:
  - MUST follow each skill’s `SKILL.md` when using that skill. (Templates/AGENTS + Skills docs)
  - MUST treat `TOOLS.md` as guidance only; MUST NOT treat it as a permissions surface. (Agent runtime docs)

Security MUSTs to add to `AGENTS.md` content:
- MUST instruct: if the operator wants remote access, the safest default is **Gateway on loopback + SSH tunnel** or **Gateway on loopback + Tailscale Serve**; Tailscale is not required. (Remote access + Tailscale docs)
- MUST instruct: if `gateway.bind` is non-loopback (`lan`/`tailnet`/`custom`/`auto` fallback), the Gateway MUST be configured with auth (token/password). (Remote access docs; Tailscale docs)
- MUST instruct: the agent MUST NOT recommend or guide “break-glass” UI auth disablement as a normal setup:
  - `gateway.controlUi.dangerouslyDisableDeviceAuth` is break-glass only and a severe downgrade; revert quickly. (Control UI docs)
- MUST instruct: if the operator changes exposure/auth/tools policies, they MUST run `openclaw security audit` (and optionally `--deep`). (Security docs)

Small-local-model reliability MUSTs (best-practice; not a config claim):
- MUST prefer short, deterministic checklists over long prose.
- MUST require tool output or explicit user confirmation before acting on uncertain assumptions.

---

## `SOUL.md`
Purpose (docs): Persona, tone, and boundaries; loaded every session. (Agent workspace + templates/SOUL)

Directives:
- MUST define persona/tone and behavioral boundaries (privacy, external actions, messaging quality).
- MUST include: if `SOUL.md` changes, the agent MUST tell the user. (Templates/SOUL)
- MUST NOT include operational runbooks (put them in `AGENTS.md`).

Security MUSTs to add to `SOUL.md` content:

- MUST state: private data stays private; do not share internal notes in group/public contexts. (Templates/SOUL; consistent with Memory privacy rule)

---

## `USER.md`
Purpose (docs): Who the user is and how to address them; loaded every session. (Agent workspace + templates/USER)

Directives:
- MUST include: user name, preferred form of address, timezone (if known). (Templates/USER)
- MUST record only assistance-relevant information; avoid dossier behavior. (Templates/USER)
- MUST use labeled bullets (stable retrieval).

Security MUSTs:
- MUST NOT store secrets or sensitive credentials in `USER.md`.

---

## `IDENTITY.md`
Purpose (docs): Agent name, vibe, emoji; created/updated during bootstrap; stored at workspace root. (Agent workspace + templates/IDENTITY)

Directives:
- MUST include: Name, Creature, Vibe, Emoji; Avatar if used. (Templates/IDENTITY)
- If Avatar is set, MUST be: workspace-relative path OR http(s) URL OR data URI. (Templates/IDENTITY)
- MUST keep this file short and identity-only.

---

## `TOOLS.md`
Purpose (docs): Local tool/convention notes; does not control tool availability. (Agent runtime + templates/TOOLS)

Directives:
- MUST contain environment-specific notes only (device names, hostnames, conventions, preferred voices). (Templates/TOOLS)
- MUST NOT contain secrets. (Agent workspace docs)
- MUST NOT attempt to define allowlists/permissions here. (Agent runtime docs)

---

## `HEARTBEAT.md`
Purpose (docs): Optional tiny checklist for heartbeat runs; keep short; if empty/comments-only, skip heartbeat API calls. (Agent workspace + templates/HEARTBEAT)

Directives:
- MUST keep empty (or comments only) to skip heartbeat work. (Templates/HEARTBEAT)
- If non-empty, MUST contain only short checklist tasks suitable for periodic execution.
- MUST NOT store logs here; logs go to daily memory files.

Security MUST:
- MUST NOT add heartbeat tasks that expand access scope implicitly (e.g., “open random links”, “scan network”) without an explicit operator-approved safety policy in `AGENTS.md`.

---

## `BOOT.md` (optional)
Purpose (docs): Optional startup checklist executed on gateway restart when internal hooks are enabled; keep short; if it sends a message, use message tool then reply `NO_REPLY`. (Agent workspace + templates/BOOT)

Directives:
- MUST be short, explicit, and idempotent. (Templates/BOOT)
- If it sends outbound messages, MUST use the message tool and then MUST reply `NO_REPLY`. (Templates/BOOT)

Security MUST:
- MUST NOT include startup actions that weaken auth/exposure posture (e.g., “enable dangerous UI flags”, “open bind to LAN”) as unattended automation.

---

## `BOOTSTRAP.md`
Purpose (docs): One-time first-run ritual; only created for brand-new workspace; delete after completion. (Agent workspace + templates/BOOTSTRAP)

Directives:
- MUST guide creation/update of `IDENTITY.md`, `USER.md`, `SOUL.md`. (Templates/BOOTSTRAP)
- MUST instruct deletion of `BOOTSTRAP.md` after completion. (Templates/BOOTSTRAP)
- MUST NOT include long-term operational rules (move into `AGENTS.md`).

---

## `MEMORY.md` (optional; curated long-term memory)
Purpose (docs): Curated long-term memory; Markdown source of truth; only load in main/private session. (Memory + Agent workspace docs)

Directives:
- MUST store durable facts/preferences/decisions; MUST NOT store raw daily logs. (Memory docs)
- MUST be structured for retrieval (atomic bullets; short sections).
- MUST be treated as private-session only (enforced via `AGENTS.md` rule). (Memory docs)

Naming consistency note (docs inconsistency to resolve):
- Current docs standardize on `MEMORY.md` (uppercase). Some older reference text mentions `memory.md`.
- MUST standardize new workspaces on `MEMORY.md` unless you have an explicit reason to keep legacy `memory.md`. (Memory + Agent workspace docs)

---

## `memory/YYYY-MM-DD.md` (daily log)
Purpose (docs): Daily log layer; append-oriented; read today + yesterday at session start. (Memory docs)

Directives:

- MUST use filename format `YYYY-MM-DD.md`. (Memory docs)
- SHOULD be append-oriented chronological notes.
- SHOULD capture: what happened, decisions today, open loops.

---

## `<workspace>/skills/<skill>/SKILL.md` (optional; workspace-specific skills)
Purpose (docs): AgentSkills-compatible skill folders teach tool usage; workspace overrides managed/bundled on name conflict. (Skills docs)

Directives:
- MUST include YAML frontmatter with at least `name` and `description`. (Skills docs)
- MUST keep frontmatter keys single-line; if `metadata` is used, MUST be a single-line JSON object. (Skills docs)
- MUST treat third-party skills as untrusted code; review before enabling. (Skills docs)

---

#OpenClaw workspace definition guide

OpenClaw workspace files — purpose + content directives (raw markdown)

Global directives (apply to ALL workspace files)

AGENTS.md

SOUL.md

USER.md

IDENTITY.md

TOOLS.md

HEARTBEAT.md

BOOT.md (optional)

BOOTSTRAP.md

MEMORY.md (optional, curated long-term memory)

memory/YYYY-MM-DD.md (daily memory log)

<workspace>/skills/<skill-name>/SKILL.md (workspace-specific skills; optional)

<workspace>/canvas/index.html (optional; canvas host content)

`AGENTS.md`

`SOUL.md`

`USER.md`

`IDENTITY.md`

`TOOLS.md`

`HEARTBEAT.md`

`BOOT.md` (optional)

`BOOTSTRAP.md`

`MEMORY.md` (optional, curated long-term memory)

`memory/YYYY-MM-DD.md` (daily memory log)

`<workspace>/skills/<skill-name>/SKILL.md` (workspace-specific skills; optional)

`<workspace>/canvas/index.html` (optional; canvas host content)