Once OpenClaw runs in production, drifting tone, forgotten preferences, and cross-project bleed usually trace back to personality files rather than model quality. This guide is for teams operating OpenClaw on a VNC remote Mac in 2026: how SOUL, MEMORY, and IDENTITY differ, a practical load and edit order, how they align with SecretRef, multi-project directories, and doctor-driven upgrades, and a VNC-first checklist so you do not miss macOS permission prompts while validating Gateway, editors, and logs side by side. Cross-read our SecretRef audit, multi-project isolation, common errors, and Gateway hardening posts.
What each file solves
Models improve every quarter, but who is speaking, what must never happen, and which facts stay true cannot live only inside a one-off system prompt. Splitting policy into three files is closer to policy-as-code: you can diff, review, and roll back without replaying chat history.
SOUL holds values, tone, and refusal boundaries—rules that should stay true across sessions (never ask for raw passwords, never run destructive shell without explicit approval, never exfiltrate local files without consent).
MEMORY holds durable facts and preferences: default repository roots, release cadence, glossary, on-call aliases. Do not paste API keys or tokens; reference SecretRef identifiers and manage material secrets through openclaw secrets flows described in the audit article.
IDENTITY is the outward-facing name and per-channel persona (Telegram bot label versus web console). Keep it short so you do not duplicate entire SOUL paragraphs.
Mental load order: IDENTITY → SOUL → MEMORY. Exact field names move between releases—run openclaw doctor after upgrades (see the v2026.4.5 migration article on this blog).
Common mistakes: pasting a full product brief into MEMORY (belongs in a wiki; MEMORY should carry a one-line pointer); storing customer legal names and contract values in SOUL (belongs in tickets; MEMORY may keep codenames and communication prefs); sharing one MEMORY across two clients (same failure mode as the multi-project isolation article).
Decision matrix: Skills, SecretRef, multi-project directories
| Topic | Use the three files | Do not substitute files for | Related post |
|---|---|---|---|
| Secrets | MEMORY mentions SecretRef names only | Plaintext tokens | SecretRef audit checklist |
| Skills | SOUL states when tools may run | Pasting full Skill tutorials into MEMORY | Skill marketplace guide |
| Multiple clients | One file set per instance and workdir | Shared MEMORY | Multi-project isolation |
| Incidents | MEMORY keeps a short doctor summary | Whole log files inside SOUL | Ten error solutions |
Triage shortcut: should it be allowed → SOUL; what is true → MEMORY; what name/channel → IDENTITY. Mixing categories in one paragraph makes Git reviews painful and rollbacks risky.
Symptom matrix: which file to edit first
This table targets the “it runs but behaves oddly” phase. It complements the install/runtime troubleshooting article: that one focuses on processes and ports; this one focuses on policy and memory consistency. Keep a VNC session open beside the chat transcript while you edit.
| Symptom | Check first | Typical root cause | Action |
|---|---|---|---|
| Same prompt twice yields different persona or politeness | IDENTITY vs SOUL tone overlap | Conflicting adjectives or one block huge and the other tiny | Move tone into SOUL; keep IDENTITY to name and channel tags |
| Model insists an old path or owner still exists | MEMORY freshness and duplicate copies | Cloned instance dragged an old MEMORY | Search for path strings; keep a single canonical MEMORY |
| Tool calls exceed policy | SOUL tool boundary | Upgrade widened default Skill behavior | Run doctor for enabled list; add explicit confirmation rules in SOUL |
| Suspected secret material in replies | MEMORY for plaintext | Paste from .env into MEMORY | Rotate keys; migrate to SecretRef; MEMORY keeps identifiers only |
Major upgrades: minimal merge and rollback
OpenClaw still ships frequent changes in 2026: canonical paths, enabled flags, and default plugin posture can all move. If you bump binaries without touching the three files, you risk policy drift: the runtime allows a new tool while SOUL still describes the old world. Before each major bump: snapshot SOUL/MEMORY/IDENTITY in Git or a zip; read breaking notes that mention tools, permissions, or Gateway; run openclaw doctor and paste only the lines that reference your policy files into a ticket—never dump full logs into SOUL; update SOUL with new prohibitions or confirmation rules; update MEMORY with ports, console URLs, and agreed paths; regress in VNC with a real account: send a message, trigger one Skill, watch the browser console for network errors.
Rollback discipline: for overreach in conversation, restore the previous SOUL first; for wrong facts leading to wrong commands, restore MEMORY first. Re-run doctor after any rollback. If you use openclaw secrets plan/apply, track policy file revision and secrets revision as separate columns in the ticket so you never roll back only half of the story.
Rented nodes: if the three files live only on a disk that can be reclaimed, personality and memory disappear with the hardware. Mirror the export mindset from our cloud Mac renewal article—small text files belong in a private repo or encrypted object storage, not a lone Desktop copy.
Seven-step auditable loop
Pin version and canonical roots
Run openclaw --version and openclaw doctor; record canonical paths per the v2026.4.5 guide.
Refresh IDENTITY
One-line name plus per-channel deltas; set default reply language if you serve multiple locales.
Author SOUL with refusals before flair
List prohibited actions (unsolicited outbound email, silent file reads) and compliance reminders.
Author MEMORY with facts, not secrets
Repository roots, release windows, glossary; SecretRef names only for credentials.
Save as UTF-8 from a VNC GUI editor
Avoid Windows editors that inject BOM or CRLF into paths and shell snippets.
Regression test
Issue the same prompt twice; tone and factual claims should align.
Ticket the change
Link to PR or attachment; align with secrets plan/apply records for auditors.
VNC verification checklist
On a remote Mac desktop, tile Finder or VS Code, the Gateway browser tab, and reference docs. When macOS shows automation, screen recording, or contacts prompts, you immediately see which workflow step caused it and can encode the decision in SOUL (for example, “never enable screen recording without an explicit user toggle”). SSH-only sessions often miss half-approved privacy states.
- Paths align with the instance root; no stray duplicate copies
- No plaintext keys in MEMORY; secrets audit clean
- SOUL prohibitions match the security policy your org actually enforces
- Browser console shows no config load errors for Gateway
- Multi-project: active working directory matches the MEMORY header you maintain
Principles and FAQ
Can a generator fill MEMORY? Only as a draft—humans must delete sensitive or stale facts or the model will cite them confidently.
Multiple editors? Use Git or a doc repo with PRs; do not email full MEMORY blobs.
Further reading: SecretRef audit, multi-project isolation, ten error solutions, v2026.4.5 upgrade notes, and the Gateway reverse-proxy article if you expose consoles publicly—SOUL should describe the external surface accurately.
Closing
Windows or Linux tunnels can proxy traffic, but they rarely reproduce the same macOS permission, browser, and Keychain behavior as a real desktop. If you want SOUL/MEMORY/IDENTITY to be operational assets instead of disposable prompts, a rented VNC Mac (such as VNCMac) plus our connectivity guides is usually cheaper in time than buying hardware you only need for a few sprints.