ClawHub

add-openclaw-agent

Other

Create a new OpenClaw agent via exec (openclaw agents add) and configure its identity + operating rules by editing the new workspace files (IDENTITY.md, AGENTS.md). Use when the user wants a new agent and can describe what they want it to do; this skill asks for the purpose first, chooses an agent-name, runs the non-interactive CLI with --json, then writes the role/task instructions into the workspace.

Install

openclaw skills install add-openclaw-agent

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, personal

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:

openclaw agents list --json

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

  • I am ready to run: openclaw agents add <agent-name> --workspace ~/.openclaw/workspace-<agent-id> --non-interactive --json. Run it now?

Only execute the command after the user confirms.

Create the agent:

openclaw agents add <agent-name> --workspace ~/.openclaw/workspace-<agent-id> --non-interactive --json

Optional flags you can add when needed:

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

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

Edit the new workspace file:

  • ~/.openclaw/workspace-<agent-id>/IDENTITY.md

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

  • name: My Agent
  • emoji: 🦞
  • theme: short theme
  • avatar: path/or/url

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):

... (keep/update existing identity fields)

---

我负责：根据肤质/预算/场景给出 2-3 个可选方案，并说明优缺点与使用顺序。

After editing, sync to config via exec:

openclaw agents set-identity --workspace ~/.openclaw/workspace-<agent-id> --from-identity --json

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

Edit the new workspace file:

  • ~/.openclaw/workspace-<agent-id>/AGENTS.md

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):

... (keep default template unchanged)

---

## 美妆助手工作规范
- 先问：肤质/预算/诉求/过敏史
- 再给：2-3 个方案 + 优缺点 + 价格区间
- 禁止：假装亲测；推荐三无/杂牌

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. Ask what the new agent is for (purpose + constraints).
  2. Choose <agent-name> (short, stable; will normalize to <agent-id>).
  3. openclaw agents add <agent-name> --workspace ~/.openclaw/workspace-<agent-id> --non-interactive --json
  4. Edit ~/.openclaw/workspace-<agent-id>/IDENTITY.md
  5. openclaw agents set-identity --workspace ~/.openclaw/workspace-<agent-id> --from-identity --json
  6. Edit ~/.openclaw/workspace-<agent-id>/AGENTS.md with the role/task/rules.

References