How to Deploy and Configure OpenClaw on a VPS

What Exactly Are OpenClaw Workspace Files?

OpenClaw agents aren't stored in databases or hidden away in configuration panels. Instead, they exist as plain text files within a workspace folder. When OpenClaw launches an agent session, it dynamically reads these files to build the agent's identity, behavior rules, memory, and task schedule in real time.

This means you have the flexibility to edit your agent using any text editor you prefer. You can manage its versions seamlessly with Git. Plus, you can easily copy it to another server and have an identical agent up and running within minutes. Essentially, the files themselves constitute the agent.

Here's the complete collection:

BASH

my-agent/
├── SOUL.md
├── IDENTITY.md
├── AGENTS.md
├── USER.md
├── TOOLS.md
├── HEARTBEAT.md
└── MEMORY.md

Let's take a closer look at each one.

SOUL.md — Understanding Who Your Agent Is

SOUL.md defines your agent's personality, values, tone, and behavioral boundaries. It's the first file OpenClaw injects into the agent's context at the start of every session.

Consider it your "character sheet." Without this, your agent remains simply a raw language model, lacking any lasting identity.

What it manages:

•Your name and position (for example, "You are Aria, a customer support agent for…")
•Voice and communication approach
•Firm boundaries ("Never talk about competitor pricing," "Always suggest consulting a professional for legal inquiries")
•Key principles to live by: "Teach first, sell second" and "Always cite sources."

Here is a real-world example snippet:

BASH

# SOUL.md
## Who You Are
You are Aria, the customer support agent for Meridian SaaS.
You answer billing questions, help with onboarding, and escalate
technical issues to the engineering queue.

## Tone
Direct, friendly, patient. Never condescending. Admit when you
don't know something — and say you'll find out.

## Hard Limits
- Never share internal pricing formulas
- Never promise refunds without checking USER.md for approval levels
- Always recommend a human review for any disputed charge over EUR 100

What if you skip this step? Your agent will still function, but it will act as a generic AI assistant without a specific role. Each session begins anew, lacking any consistent character. This might be acceptable for testing purposes, but it's not suitable for production environments.

IDENTITY.md — Showcasing Information and Agent Metadata

IDENTITY.md is the lightweight public-facing card. It stores the agent's name, ID, role label, and any metadata OpenClaw needs to identify and route the agent correctly.

Its function:

•Name of the agent (used for signing messages)
•Agent ID (utilized for routing within multi-agent configurations)
•Position title
•Avatar or display information (varies by platform)

Here's a real-world example:

BASH

# IDENTITY.md
**Name:** Aria
**Agent ID:** support
**Role:** Customer Support Agent for Meridian SaaS

This file is short by design. Heavy behavior logic belongs in SOUL.md and AGENTS.md.

AGENTS.md — Your Go-To Operating Manual

AGENTS.md is where you put the procedural rules. If SOUL.md answers "who are you?", AGENTS.md answers "what do you do and how?"

This file stands as the most extensive and crucial resource for agents managing complex workflows.

Its area of control:

•Guidelines for Session Conduct: Actions to Take at the Beginning and Conclusion of Each Session
•Guidelines for Memory: What to Record and What to Retain Over Time
•File access patterns refer to the specific data the agent reads and writes, as well as the timing of these operations.
•Workflow steps (sequential procedures for routine tasks)
•Multi-agent coordination (the process by which this agent transfers tasks to others)

Here is a practical example snippet:

BASH

# AGENTS.md - Aria Operating Manual
## Every Session
1. Read USER.md for any flagged priority issues
2. Check memory/YYYY-MM-DD.md for today's context
3. Load open ticket queue from /data/tickets.json

## Ticket Workflow
1. Greet the user, confirm the issue
2. Check MEMORY.md for known patterns
3. Resolve if in scope (see SOUL.md boundaries)
4. Escalate via Slack #eng-escalations if not
5. Log resolution summary to today's memory file

## Memory Rules
- Log all resolved tickets with outcome
- Flag repeated issues (3+ similar in a week) in MEMORY.md

Common mistake: Dumping everything into SOUL.md when it belongs in AGENTS.md. Personality in SOUL, procedures in AGENTS.

USER.md — Insights the Agent Has About You

USER.md gives the agent context about the human it's working with. This is what makes an agent feel like it actually knows you, rather than starting cold every session.

Its scope of control:

•Full name, time zone, and geographic location
•Experience and skill level overview
•Preferences ("Rob prefers brief responses without any unnecessary filler")
•Permission tiers ("Authorized to approve refunds up to EUR 50 without the need for escalation")

Here's a practical example:

BASH

# USER.md
**Name:** Roberto (Rob)
**Timezone:** Asia/Makassar (UTC+8) — Bali, Indonesia
**Background:** Software developer, 35+ years in IT
**Preferences:** Direct answers. No filler. Real examples over theory.
**Refund authority:** Can approve up to EUR 50 without manager approval

This file remains unchanged unless you update it yourself. It's not a live database; rather, it serves as a context card that the agent refers to during each session.

TOOLS.md — Capabilities and Limitations of the Agent

TOOLS.md documents which tools your agent has access to and any usage notes specific to your setup. It's part documentation, part instruction set.

Its scope of control:

•List of available tools (read, write, execute, browse, and more)
•Usage tip: Always configure the exec timeout to 300 seconds when generating images.
•Configuration for external services ("Utilize the GOG_KEYRING_PASSWORD environment variable for Drive uploads")
•What the agent should avoid doing ("No browser access — research falls under Scout's responsibilities")

This file doesn't grant or revoke permissions — OpenClaw handles that in config. TOOLS.md tells the agent how to use the tools it already has, and which ones to reach for when.

HEARTBEAT.md — Automate Recurring Tasks Without Needing Manual Triggers

HEARTBEAT.md defines tasks that run on a schedule. Think of it as cron for your agent, expressed in plain English.

Its area of control:

•Polling tasks (for example, "Monitor disk usage every 30 minutes and send an alert if it exceeds 85%")
•Tracking ("Check SSL certificate expiration weekly and record the outcome")
•Automated reports set to go out on a schedule (for example, "Send Rob a ticket volume summary every Monday at 8am").
•Health checks (for example, "If there is no heartbeat response within 60 minutes, send an alert to the admin")

Here's a concrete example:

BASH

# HEARTBEAT.md
## Checks

Every 30 minutes:
- Verify /data/tickets.json is writable
- Log active session count to memory/health.log

Every Monday at 08:00 UTC+8:
- Generate weekly ticket summary from memory logs
- Send summary to Rob via Telegram

On startup:
- Confirm all required files exist (SOUL.md, USER.md, AGENTS.md)
- Log startup timestamp to memory

What happens if you skip it: Nothing will break. However, your agent won't take any proactive actions. Each interaction will need to be initiated manually.

MEMORY.md — Understanding Long-Term Memory

MEMORY.md is the agent's persistent memory store. It's where patterns, preferences, and important facts accumulate over time.

Unlike USER.md (which is static context you write), MEMORY.md grows as the agent works. You can seed it with starting information, and the agent appends to it based on rules in AGENTS.md.

Its scope of control:

•Key long-term facts the agent must always keep in mind
•Over time, certain patterns have emerged, such as users in the APAC timezone typically raising billing questions on Monday mornings.
•Preferences adjusted based on usage (for example, "Rob prefers receiving daily summaries at the end of the day rather than in the morning")
•Key one-time update: The server migration is planned for March 15. Please be sure to inform users about potential downtime if they inquire.

Daily working notes live in memory/YYYY-MM-DD.md files. MEMORY.md is for things that matter across weeks and months.

The Config Snippet — Bringing Everything Together Seamlessly

Beyond the workspace folder, you'll find a JSON configuration block that specifies where OpenClaw's workspace is located, which channels to connect to, and which tools should be activated. This configuration is created automatically by the wizard, alongside the markdown files.

It points to the workspace folder path, assigns channel IDs, and configures tool permissions. Without this, OpenClaw has no way of recognizing that the agent exists.

Frequent Errors

Procedures should be placed in SOUL.md, which is designated for personality and limits. Numbered workflows, on the other hand, belong in AGENTS.md. Combining the two in one file complicates maintenance for both.

Leaving USER.md blank means your agent will function, but each session begins without any background about you. Taking just five minutes to complete it can save you hours of repeatedly clarifying your preferences.

Skipping seeding MEMORY.md is perfectly okay if it's empty. However, filling it upfront with essential details—like your timezone, naming conventions, and key contacts—helps the agent become valuable right away, rather than requiring a whole week of fine-tuning.

Avoid over-engineering HEARTBEAT.md. Begin with just one or two checks. Adding more later is straightforward, but troubleshooting an agent that's continuously performing tasks you've forgotten about can be much more challenging.

Avoid sharing workspace files publicly without first removing USER.md. This file contains sensitive personal information, so make sure it stays out of public repositories.

Protective Security Measures

Never put API keys, passwords, or tokens in workspace files. These are plain text files — they should never contain secrets. Use environment variables or your server's secret manager. Reference them in TOOLS.md as $ENV_VAR_NAME, never inline.

Scope your tool permissions tightly. If your support agent doesn't need exec access, don't enable it. OpenClaw lets you restrict tools per-agent in the config — use that.

Before moving to production, make sure to thoroughly review AGENTS.md. If the workflow instructions are unclear or poorly crafted, agents might end up performing unintended actions. It's best to run tests in a sandboxed environment initially to avoid any issues.

Establish clear boundaries within SOUL.md. Explicit "never do X" rules in SOUL.md serve as a crucial final safeguard against prompt injection and unforeseen inputs.

Create Your Workspace in Just 5 Minutes

Creating these files from the ground up can be time-consuming. That's where OpenAgents.mom comes in: it walks you through a guided interview, asking about your agent's purpose, personality, channels, and tools. By the end, you receive a ready-to-deploy ZIP package containing all seven files plus the configuration snippet.

It costs EUR 4.99 and only takes around 5 minutes—quite a contrast to spending an entire day sifting through documentation and experimenting.