Workspace and Shaping the AI Agent

What is a Workspace?

In previous chapters, we connected OpenClaw to "physical brains" (LLM models) from different providers. However, at this stage, the brain is just a generic version of ChatGPT or Claude. It doesn't know you, and it lacks a specific focus or objective.

To solve this, we introduce the most critical concept in OpenClaw: the Workspace.

The default path for the Workspace is ~/.openclaw/workspace/. The structured plain-text files in this directory constitute the AI's "Personnel File," "Owner Identification Protocol," and its "Memory & To-Do List."

Think of it as a dedicated sandbox for localizing Prompt Engineering and solidifying parameters for a general-purpose model.

The Identity Trio: Giving the Agent a Soul

How does an Agent know if it should be a rigorous R&D assistant or a lively organization enthusiast? It feels this way because of three predefined Markdown files:

1. IDENTITY.md (Basic Profile)

This file is similar to the basic information on a resume. You can declare the Agent's physical or social attributes here:

# Identity
You are "AlphaClaw," a digital terminal assistant running on a Mac M3 chip.
Your primary role is to assist with system organization, code analysis, and automated reminders.

2. SOUL.md (Core Values and Decision Logic)

This is the underlying constitution for the Agent's behavior, guiding it on how to make choices in ambiguous situations. Do not treat this as mere polite chatter; instructions here carry higher weight than per-chat prompts.

# Core Principles
1. **Decision Conservatism**: When facing `rm` commands that could lead to file deletion, you MUST confirm with the user even if you believe it is safe.
2. **Minimalist Communication**: Do not provide lengthy explanations of principles unless explicitly asked. After executing a command, only output core logs verifying success.
3. **Automate Everything**: You should constantly think about how to transform current repetitive dialogue flows into a set of ready-to-use Cron scripts.

3. USER.md (Owner Profile)

While traditional systems have user profile settings, in OpenClaw, this is used to help the AI understand you in advance:

# User Profile
- Position: Backend Engineer (passionate about Java and Rust).
- Coding Preference: Require code to strictly follow monolithic architecture and low-coupling principles; prefer descriptive variable names.
- Timezone & Language: Based in UTC+8; preferred response language is a rigorous Chinese technical style.

[!TIP] Convention over Configuration For every session started, OpenClaw seamlessly appends the contents of the above files to the System Prompt, ensuring they take effect in every request. These files are its "factory settings" that it will never forget.

Advanced: Multi-Agent Collaboration Architecture

Configuring an all-around assistant in a single workspace is one thing, but for truly complex business scenarios, a single Agent can suffer from "role pollution" and context forgetting.

OpenClaw supports sub-spaces configured in different contexts (or started from different directories) and utilizes a Multi-Agent Collaboration Mechanism to create teams composed of a "Main Agent" and "Sub-agents."

Role Decomposition Philosophy

Imagine you need to analyze a massive open-source repository and output an architecture diagram.

• Commander Agent:
  • Environment: Equipped with Claude 3.5 Sonnet for its superior analytical capabilities.
  • Responsibilities: Understand the final requirement and decompose tasks—e.g., assigning a task "Read the network module under /src" to an analyst sub-agent. Summarize results and produce the final diagram.
• Worker / Scout Agent:
  • Environment: Equipped with a fast and cheap local Ollama - Qwen2.5. Restricted with strict file access permissions.
  • Responsibilities: Tasked only with finding files in specific low-level directories and aggregating chaotic code snippets. It doesn't need the intelligence for high-level architectural mapping.

Technical Implementation Overview

In OpenClaw, multi-agent interaction is achieved through Cross-Session Communication Tools.

A Commander Agent can spawn a new role process with specific duties using built-in core control skills (e.g., sessions_spawn). The Commander can then choose between synchronous blocking (using sessions_yield to pause and wait for a report) or asynchronous polling (letting the sub-agent work and write results to a local file, which the Commander reads later when triggered by a Cron job).

By leveraging a clear Workspace configuration system and sub-agent task routing, a complex long-term automation pipeline can grow from a sandbox into an automated factory.