docs: document agent identity files and backup/restore guidance

[phanisaimunipalli]

Summary

Adds a reference page for the three workspace files OpenClaw creates inside the sandbox: SOUL.md, USER.md, and IDENTITY.md.

• Documents what each file does and its exact path (/sandbox/.openclaw/workspace/)
• Clarifies persistence behavior: files survive sandbox restarts but are lost on gateway destroy
• Provides step-by-step backup and restore commands using openshell sandbox download/upload
• Adds the page to the Reference section of the docs nav

Closes #434.

Pages added

• docs/reference/agent-identity-files.md (new)
• docs/index.md (nav entry added)

Summary by CodeRabbit

• Documentation
  • Added a new reference page describing agent identity files, their role in shaping session responses, where they are stored in the sandbox, persistence across restarts, and how to back up, restore, or edit them so changes take effect in the next agent session. Links to related docs included.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 002848bb-a86e-4dfd-9897-a1ba1eaaff45

📥 Commits

Reviewing files that changed from the base of the PR and between 9b6e9f7 and ba7a351.

📒 Files selected for processing (1)

• docs/reference/agent-identity-files.md

---

📝 Walkthrough

Walkthrough

A new reference page documents OpenClaw agent identity files (SOUL.md, USER.md, IDENTITY.md), their exact workspace paths, persistence semantics, and CLI backup/restore steps; docs/index.md was updated to link the new page.

Changes

Cohort / File(s)	Summary
Documentation Index docs/index.md	Added "Agent Identity Files" entry to the Reference toctree, linking to the new reference page.
Agent Identity Files Reference docs/reference/agent-identity-files.md	Added new reference page describing SOUL.md, USER.md, and IDENTITY.md: purpose, exact storage under /sandbox/.openclaw/workspace/, persistence across sandbox and CLI restarts, loss on gateway destroy, and CLI commands for backing up/restoring individual files or the entire workspace.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 I nibble docs by lantern light,
Three little files kept safe and tight,
SOUL, USER, IDENTITY—my trio bright,
Back them up, restore by night,
Hooray for tidy sandbox delight! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main change: adding documentation for agent identity files and backup/restore guidance, which is the primary objective of this documentation PR.
Linked Issues check	✅ Passed	The PR successfully implements all primary coding objectives from issue #434: documenting the three identity files (SOUL.md, USER.md, IDENTITY.md), their location, persistence behavior across lifecycle events, and manual backup/restore commands.
Out of Scope Changes check	✅ Passed	All changes are within scope: two files are modified (docs/index.md updated with toctree entry, and new docs/reference/agent-identity-files.md created) to fulfill the documentation requirements from issue #434.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

📝 Coding Plan

• Generate coding plan for human review comments

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

docs/reference/agent-identity-files.md (3)

21-21: Align H1 with title.page frontmatter value.

# Agent Identity Files does not match title.page (NemoClaw Agent Identity Files — SOUL.md, USER.md, and IDENTITY.md).
Please make these identical.

As per coding guidelines, "H1 heading matches the title.page frontmatter value."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/agent-identity-files.md` at line 21, Update the document's
top-level H1 so it exactly matches the title.page frontmatter value; replace the
current `# Agent Identity Files` H1 with `# NemoClaw Agent Identity Files —
SOUL.md, USER.md, and IDENTITY.md` (ensure punctuation and casing match the
frontmatter), and verify the `title.page` frontmatter remains unchanged so the
H1 and frontmatter are identical.

---

27-33: Add an introductory sentence immediately under each H2 before table/list content.

These sections start directly with table/list content.
Add a one-line intro sentence after each heading.

As per coding guidelines, "Sections use H2 and H3, each starting with an introductory sentence."

Also applies to: 59-66, 120-124

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/agent-identity-files.md` around lines 27 - 33, Add a one-line
introductory sentence immediately under each H2 heading before any table or list
content (for example the "The Identity Files" H2 that currently jumps straight
into the table listing SOUL.md, USER.md, IDENTITY.md), e.g. a brief sentence
describing the section purpose; apply the same fix to the other H2 sections
noted in the review (the H2s at the other referenced ranges) so every H2 is
followed by a single-line intro before any tables or lists.

---

24-24: Use active voice for persistence behavior sentence.

This line uses passive voice ("are lost when the gateway is destroyed").
Rewrite in active voice.

As per coding guidelines, "Active voice required. Flag passive constructions."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/agent-identity-files.md` at line 24, Change the passive clause
in the persistence behavior sentence to active voice: replace "These files
persist across sandbox restarts but are lost when the gateway is destroyed."
with an active construction such as "These files persist across sandbox
restarts, but the gateway destroys them." Edit the sentence labeled "persistence
behavior" (the line starting "These files persist across sandbox restarts...")
accordingly to use the active verb "destroys."

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/reference/agent-identity-files.md`:
- Around line 42-44: The fenced code blocks in
docs/reference/agent-identity-files.md lack language identifiers; update each
triple-backtick fence shown (the single-line block containing
"/sandbox/.openclaw/workspace/" and the multi-line block listing
SOUL.md/USER.md/IDENTITY.md, plus the similar block at the later 48-52 section)
to include an explicit language tag such as text (e.g., change ``` to ```text)
so the markdown linting and formatting pass; ensure both opening fences are
updated while leaving the fenced content unchanged.

---

Nitpick comments:
In `@docs/reference/agent-identity-files.md`:
- Line 21: Update the document's top-level H1 so it exactly matches the
title.page frontmatter value; replace the current `# Agent Identity Files` H1
with `# NemoClaw Agent Identity Files — SOUL.md, USER.md, and IDENTITY.md`
(ensure punctuation and casing match the frontmatter), and verify the
`title.page` frontmatter remains unchanged so the H1 and frontmatter are
identical.
- Around line 27-33: Add a one-line introductory sentence immediately under each
H2 heading before any table or list content (for example the "The Identity
Files" H2 that currently jumps straight into the table listing SOUL.md, USER.md,
IDENTITY.md), e.g. a brief sentence describing the section purpose; apply the
same fix to the other H2 sections noted in the review (the H2s at the other
referenced ranges) so every H2 is followed by a single-line intro before any
tables or lists.
- Line 24: Change the passive clause in the persistence behavior sentence to
active voice: replace "These files persist across sandbox restarts but are lost
when the gateway is destroyed." with an active construction such as "These files
persist across sandbox restarts, but the gateway destroys them." Edit the
sentence labeled "persistence behavior" (the line starting "These files persist
across sandbox restarts...") accordingly to use the active verb "destroys."

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 73554c83-73b2-4536-bbe9-5d44415c6072

📥 Commits

Reviewing files that changed from the base of the PR and between dbfd78c and 9b6e9f7.

📒 Files selected for processing (2)

• docs/index.md
• docs/reference/agent-identity-files.md

[wscurran]

Thanks for taking the time to document the workspace files OpenClaw creates inside the sandbox, this will definitely help with understanding persistence behavior and backup/restore procedures.

[miyoungc]

Suggested change

	# NemoClaw Agent Identity Files — SOUL.md, USER.md, and IDENTITY.md
	# Agent Identity Files

[miyoungc]

Would you add links to the corresponding identity file doc page in OpenClaw, such as https://docs.openclaw.ai/reference/templates/IDENTITY for IDENTITY.md?

[miyoungc]

Suggested change

	## The Identity Files
	## Identity Files Created by OpenClaw