OpenClaw Workspace Files (SOUL.md, MEMORY.md) on Cloud Mac 2026: Team-Safe Configuration

Platform teams running OpenClaw on rented Apple Silicon Macs quickly learn that model choice and gateway uptime are only half the story—the agent’s behavior is steered by markdown files in its workspace. SOUL-style prompts define tone and safety rails; memory files capture durable facts the agent should recall across sessions; companion files describe which tools and sub-agents exist. The 2026 practice is to treat that directory like infrastructure-as-code: version the safe portions, exclude secrets, and document which macOS user owns the LaunchAgent that reads them. This guide explains each core file, gives a seven-step bootstrap, outlines multi-engineer sandbox patterns, adds git hygiene rules, and maps common failure symptoms to fixes, with pointers to gateway and webhook hardening articles when the problem is not markdown at all.

Well-curated workspace text also lowers token spend: concise SOUL paragraphs reduce the need to repeat policy in every chat, and trimmed MEMORY avoids paying to re-ingest obsolete paragraphs on each task.

Schedule a monthly “prompt debt” review the same way you review stale cron jobs—delete experiments, archive superseded tone guidance, and keep only the paragraphs that still match production APIs and brand voice.

Why Workspace Markdown Matters on Headless Cloud Mac

Unlike a chat-only assistant, OpenClaw agents on MacLogin nodes can invoke shell commands, watch folders, and answer webhooks. Without explicit SOUL constraints, a helpful model may delete files, post to the wrong Slack channel, or leak internal hostnames into customer-visible replies. MEMORY, when abused, becomes a dumping ground for stale project rumors that override fresher data in your ticket system. Getting the files right reduces incident volume more than bumping context windows.

Before editing prose, ensure the gateway process is stable using launchd troubleshooting steps; otherwise you will chase ghosts in markdown while Node keeps restarting.

For tamper-evident telemetry around tool calls, add OpenClaw CLI hooks and audit logging so workspace policy and runtime evidence stay aligned.

Core Workspace Files: Reference Table

OpenClaw distributions evolve, but most installations expose a workspace folder under the service user (commonly under a hidden .openclaw tree). Use this table as a contract with your team—adjust filenames only if your build documents otherwise.

File	Purpose	What to avoid storing
SOUL.md (or equivalent)	Persona, refusal patterns, escalation triggers	API keys, customer PII, unvetted third-party instructions
MEMORY.md	Long-lived facts, naming conventions, repo map	Passwords, raw tokens, time-sensitive secrets
AGENTS.md / TOOLS.md	Declared sub-agents and callable tools	Experimental plugins not reviewed for ClawHub-style risk

Seven-Step Workspace Bootstrap

1. Pick the owning user: Match the macOS account that runs the LaunchAgent—mixed ownership causes silent read failures.
2. Snapshot the directory: Copy permissions with ls -la; every markdown file should be group-readable only by intended staff.
3. Draft SOUL.md: Include “never run rm -rf outside workspace roots” and require confirmation for outbound webhooks.
4. Seed MEMORY.md: Add repository URLs, default branches, on-call rotation names, and retire entries older than 90 days during sprint reviews.
5. Align tool manifests: Remove tools your host should not expose publicly—especially on machines with inbound HTTPS from TLS-terminated webhooks.
6. Wire gitignore: Exclude local scratch paths; never commit .env copies sitting beside markdown.
7. Restart and dry-run: Bounce the gateway, send a benign prompt that references MEMORY, and confirm logs show the expected file hashes or load markers.

Team Sandbox Patterns on One Mac mini

When budget keeps you on a single Mac mini M4 in Singapore while engineers sit in Seoul and San Francisco, split contexts rather than sharing one mutable MEMORY. Options include per-project subfolders symlinked into the active workspace during deployments, or Git branches merged through CI that only promotes reviewed markdown. Document handoffs in your internal wiki so weekend on-call knows which branch is live.

Git, Backups, and Secret Hygiene

Even “internal” Git repos leak when contractors clone them. Treat MEMORY like application config: redact customer names when unnecessary, reference ticket IDs instead of pasting transcripts, and run a pre-commit hook that blocks private keys. For backups, encrypt offline copies because markdown frequently contains architecture hints useful to attackers.

Operational targets: keep SOUL + MEMORY combined under roughly 8,000 tokens equivalent unless you implement retrieval; run quarterly reviews deleting obsolete automation references tied to retired microservices.

When multiple humans edit the same markdown over SSH, adopt file locks or pull-request style reviews even if the “repo” is informal—last-write-wins races have caused agents to inherit half-old safety rules and half-new marketing tone in the same session.

Troubleshooting Matrix

Symptom	Likely cause	Fix
Agent ignores new SOUL rule	Gateway not restarted or wrong user path	Verify LaunchAgent plist ProgramArguments and reload
Contradictory answers hour to hour	Stale MEMORY vs live API data	Date-stamp MEMORY bullets; prefer tool calls for volatile state
Tool not found errors	TOOLS.md out of sync with installed plugins	Reconcile manifest with openclaw doctor output
Sensitive text in customer chat	Over-sharing MEMORY without redaction rules	Add SOUL clause requiring scrub before external channels

Frequently Asked Questions

Should SOUL reference company brand voice? Yes—include examples of preferred greetings and forbidden phrases to reduce review cycles.

Can MEMORY pull from Notion automatically? Only through explicit tools you trust; do not paste entire wiki exports into markdown without chunking.

How often to reboot workspace experiments? After major macOS upgrades or when migrating between MacLogin regions (HK, JP, KR, SG, US)—file paths and permissions may shift.

Why Mac mini M4 on MacLogin Fits Rich Workspaces

Large SOUL and MEMORY files load faster when disk and unified memory are not contending with unrelated Xcode indexing jobs. Apple Silicon Mac mini M4 nodes provide predictable single-thread performance for parsing markdown and spawning tool subprocesses. Hosting in Hong Kong, Japan, Korea, Singapore, or the United States keeps latency low for chat operators and webhook senders alike.

Rent separate hosts for production agents versus R&D sandboxes so experimental SOUL drafts never ship by accident. Scale memory and CPU on the pricing page as you add tools, and keep VNC access ready for one-time GUI approvals that headless markdown cannot replace.