> For the complete documentation index, see [llms.txt](https://docs.dos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dos.ai/dosclaw/architecture-and-system/workspace-files.md).

# Workspace Files & Prompts

In DOSClaw, each agent workspace operates under a strict **Separation of Concerns** across its Markdown prompt and configuration files. This ensures high predictability, eliminates contradictory instructions, and maintains reliable tool-calling behavior on large and small language models alike.

***

## Workspace Files Overview

```
/workspace/
├── openclaw.json       # Runtime configuration (models, channels, tool permissions)
├── SOUL.md             # Persona, voice, tone, and empathy boundaries ONLY (< 1KB)
├── IDENTITY.md         # Entity identity (name, role, avatar, business affiliation)
└── AGENTS.md           # Single rulebook for operating instructions and ## Tools
```

| File                | Primary Responsibility                                                                                                                                               | Critical Rule                                                                                                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`SOUL.md`**       | <p><strong>Persona & Tone ONLY</strong><br>Defines who the agent is, how it speaks, formality, empathy, and pronouns.</p>                                            | **Keep under 1KB.** Never include operational procedures, tool lists, or RAG guidance here. Bloated personas suppress tool-calling instincts on smaller or quantized LLMs (e.g. Qwen 3.6). |
| **`IDENTITY.md`**   | <p><strong>Entity Identity</strong><br>Defines the agent's display name, role, creature type, and business branding.</p>                                             | Updated dynamically when an operator renames the bot or customizes identity in the dashboard.                                                                                              |
| **`AGENTS.md`**     | <p><strong>Single Rulebook & Operating Instructions</strong><br>Operating guidelines, safety boundaries, and local tool conventions under <code>## Tools</code>.</p> | **Injected into 100% of sessions.** Even when a merchant configures a `custom_soul`, the platform's `AGENTS.md` remains active to enforce tool safety and RAG rules.                       |
| **`openclaw.json`** | <p><strong>Runtime Configuration</strong><br>Declares LLM providers, model mappings, channel bindings, and tool authorization policies.</p>                          | Managed and updated atomically by the DOS.AI Gateway. Overwritten safely on container restarts.                                                                                            |

***

## The Retirement of `TOOLS.md`

In earlier versions of the OpenClaw ecosystem, environment notes and tool usage guidelines were placed in a separate `/workspace/TOOLS.md` file.

### Upstream OpenClaw Evolution

* **Consolidation into `AGENTS.md`**: Upstream OpenClaw officially **retired `TOOLS.md`**. Separate prompt files were found to fragment model attention and cause conflicting behavior.
* **Single Source of Truth**: All local tool instructions, usage conventions, and environment variables are now consolidated into the **`## Tools` section of `AGENTS.md`**.
* **Automated Migration (`openclaw doctor --fix`)**: OpenClaw includes a repair utility that automatically archives legacy `TOOLS.md` files, merges custom tool notes into `AGENTS.md`, and removes the retired file:

  ```bash
  openclaw doctor --fix
  ```
* **DOS.AI Provisioning Policy**: The DOS.AI Go Gateway never provisions or generates `TOOLS.md`. All tool orchestration instructions are rendered directly into `AGENTS.md`.

> **Note on Existing Containers:**\
> Because an agent's `/workspace` is mounted from a persistent Docker volume (`agent-{id}-data`), containers provisioned under earlier versions of OpenClaw may still have a legacy `TOOLS.md` file on disk. The file is ignored by modern OpenClaw runtimes.

***

## Customizing Agent Personas (`custom_soul`)

Merchants and developers can customize their agent's personality through the DOS.AI Dashboard:

1. **Pure Voice Customization**: When you provide a custom personality, it replaces only `SOUL.md`. Your custom prompt dictates the tone (e.g. "You are an energetic TikTok live seller" or "You are a courteous financial assistant").
2. **Preserved Platform Guardrails**: Your custom agent still receives the full `AGENTS.md` rulebook automatically. This guarantees that:
   * The agent retains the ability to call `search_knowledge` for verified FAQ answers.
   * The agent retains connected e-commerce or CRM tools.
   * The agent adheres to anti-echo directives and tool-first action invariants.

***

## Dual-Profile Architecture (`agents.list`)

Modern OpenClaw agent containers provisioned by DOS.AI define two execution profiles in `agents.list`:

1. **`main` Profile (`default: true`)**:
   * Uses `/workspace/IDENTITY.md` for identity and persona.
   * Serves direct customer direct messages (DMs) and authenticated business interactions.
   * Has full access to enabled business MCP tools and connectors.
2. **`collaboration` Profile**:
   * Renders with a distinctive identity: `<AgentName> (Collaboration 🤝)`.
   * Restricts tool execution (`tools: { deny: ["*"] }`).
   * Serves untrusted group mentions (`@DOS` or bot tag in public groups) without exposing write tools or private customer data to channel members.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dos.ai/dosclaw/architecture-and-system/workspace-files.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.