Principle:Openclaw Openclaw Agent Creation

Agent Creation

Agent Creation is the principle of provisioning a new isolated agent entry with its own workspace directory, session store, and default configuration. Creating an agent establishes the foundational directory structure and configuration entries required for the agent to operate independently within a shared gateway.

Motivation

Adding a new agent to a multi-agent gateway requires coordinating several concerns: allocating an identity (agentId), creating workspace directories with bootstrap files, setting up a state directory for auth profiles, optionally configuring model preferences and channel bindings, and ensuring the configuration file reflects the new agent without disrupting existing agents.

The agent creation principle encapsulates this coordination into a single operation, whether driven interactively through a wizard or non-interactively through CLI flags.

What Gets Created

When a new agent is provisioned, the following resources are established:

Resource	Default Path	Purpose
Config entry	agents.list[] in ~/.openclaw/openclaw.json	Registers the agent with its id, name, workspace, agentDir, and optional model.
Workspace directory	~/.openclaw/workspace-<agentId>	Contains persona files (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md).
Agent directory	~/.openclaw/agents/<agentId>/agent	Stores per-agent auth profiles (auth-profiles.json) and model registry.
Sessions directory	~/.openclaw/agents/<agentId>/sessions	Holds per-agent chat history and routing state.

Agent Identity Rules

• The agentId is derived by normalizing the agent name to lowercase with hyphens.
• The reserved id main cannot be used for new agents -- it belongs to the implicit default agent.
• If an agent with the same normalized id already exists, the interactive wizard offers to update it; the non-interactive mode rejects the duplicate.
• When the first non-default agent is added to an empty list, the default agent (main) is automatically prepended to maintain consistent ordering.

Provisioning Workflow

The creation workflow follows these steps:

1. Validate the agent name and normalize to an agentId.
2. Resolve workspace and agent directory paths (from flags or defaults).
3. Apply the agent config entry to the configuration file.
4. Parse and apply any binding specifications (channel routing rules).
5. Write the updated config to disk.
6. Ensure the workspace directory exists with bootstrap template files.
7. Optionally copy auth profiles from the default agent.
8. Optionally configure model/auth and channel bindings through the wizard.

Interactive vs Non-Interactive

• Interactive mode (no flags): launches a step-by-step wizard with prompts for name, workspace, auth setup, channel selection, and binding configuration.
• Non-interactive mode (with flags): requires --workspace and --name; accepts --model, --agent-dir, and --bind flags; outputs JSON when --json is set.

Both modes produce the same result: a fully configured agent entry in the config file and a provisioned workspace directory.

Bootstrap Files

New workspaces are seeded with template files from docs/reference/templates:

• AGENTS.md -- Agent behavior instructions
• SOUL.md -- Personality and tone definition
• TOOLS.md -- Tool usage guidelines
• IDENTITY.md -- Name and emoji identity
• USER.md -- User context and preferences
• HEARTBEAT.md -- Heartbeat/scheduled task instructions
• BOOTSTRAP.md -- Initial bootstrap instructions (only for brand-new workspaces)

A git repository is also initialized in the workspace directory if git is available.

Binding During Creation

Agents can be bound to channels at creation time using --bind flags (e.g., --bind whatsapp:personal). The binding system detects conflicts (same match rule already claimed by another agent) and reports them without overwriting.

Implementation

Implementation:Openclaw_Openclaw_AgentsAddCommand