Add OpenClaw Agent

Create a new isolated OpenClaw agent and configure it (identity + role + task) in its workspace.

When this skill applies

• - User asks to create a new agent (by name).
• User wants to give that agent an identity (display name, emoji, theme, avatar) or a task/purpose (persona, rules, scope).

Workflow (recommended)

0. Ask what the new agent is for (required)

• - Ask the user what they want the new agent to do.
• Ask for any constraints that affect identity and rules (language, tone, safety boundaries, sources allowed, output format, etc.).

Then pick an agent-name based on the purpose. Prefer short, stable ids like:

• - beauty, coding, support, ops, research, INLINECODE6

Notes:

• - OpenClaw normalizes names to an agent id (lowercase; invalid characters collapse to -). The id cannot be main (reserved).
• Use the normalized id in the workspace directory: ~/.openclaw/workspace-<agent-id>.

1. Create the agent with exec (non-interactive, JSON)

Use the exec tool to run the OpenClaw CLI. Non-interactive creation requires --workspace and --non-interactive.

Before creating, check whether it already exists:

CODEBLOCK0

Before running creation, explicitly ask for confirmation, for example:

• - INLINECODE12

Only execute the command after the user confirms.

Create the agent:

CODEBLOCK1

Optional flags you can add when needed:

• - --model <id> – default model for this agent.
• INLINECODE14 – agent state dir (default: ~/.openclaw/agents/<id>/agent).
• INLINECODE16 – route a channel to this agent (repeatable).

2. Configure identity by editing IDENTITY.md (then sync)

Edit the new workspace file:

• - INLINECODE17

The top section is a template with identity key-value lines (examples):

• - INLINECODE18
• INLINECODE19
• INLINECODE20
• INLINECODE21

Supported keys: name, emoji, theme, creature, vibe, avatar.

Hard rule (IDENTITY.md):

• - Only edit the identity field lines (the - **Name:** ... style lines / key-value fields).
• Do not rewrite, delete, or reorder any other template text above the separator.
• Any additional identity/role description must be appended after the --- separator.
• If the file does not contain ---, add a blank line and then a --- line at the end, and append your description after it.
• Tool priority for file changes: prefer edit for targeted append/update; use write only when edit cannot be applied reliably (for example file missing or malformed beyond safe patching).

Short example (append style):

CODEBLOCK2

After editing, sync to config via exec:

CODEBLOCK3

3. Configure role + task + operating rules in AGENTS.md

Edit the new workspace file:

• - INLINECODE35

Put task definition and operating rules here (how to work), based on what the user told you in step 0. Examples of good content:

• - What this agent is responsible for (scope)
• What it must not do (red lines)
• The question-asking checklist before acting
• Output format expectations (bullets, structure, brevity)
• Tooling rules (when to use exec; avoid destructive commands unless asked)

Hard rule (AGENTS.md):

• - Do not rewrite, delete, or reorder the default template content.
• Add all custom “role/task/rules” content only by appending after the --- separator.
• If the file has no ---, add a blank line + --- near the end, then append your custom section after it.
• Tool priority for file changes: prefer edit for targeted append/update; use write only when edit cannot be applied reliably (for example file missing or malformed beyond safe patching).

Short example (append style):

CODEBLOCK4

If you also want a stable persona/tone/boundary file, place that in SOUL.md too, but keep the core “how to operate” rules in AGENTS.md.

End-to-end flow (summary)

1. 1. Ask what the new agent is for (purpose + constraints).
2. Choose <agent-name> (short, stable; will normalize to <agent-id>).
3. INLINECODE46
4. Edit INLINECODE47
5. INLINECODE48
6. Edit ~/.openclaw/workspace-<agent-id>/AGENTS.md with the role/task/rules.

References

• - Multi-agent routing and paths: Multi-Agent Routing, Agent workspace.
• CLI: openclaw agents add, openclaw agents set-identity, openclaw agents bind in agents CLI.