OpenClaw Agent Creator

Create and configure agents for Arch's OpenClaw multi-agent system at

~/.openclaw/

System Context

• Owner: Archit (Arch), Linux user

  archit

  , timezone America/Denver
• Gateway: Single process on port 18789 managing all agents
• Bot: One Telegram bot shared across all agents — routing determines which agent handles which chat
• Existing agents: Check

  ~/.openclaw/openclaw.json

  →

  agents.list[]

  for current roster
• Implementation history: See

  ~/.openclaw/implementation-docs/

  for the Wire agent reference implementation

Agent Creation Workflow

1. Gather Requirements

Before creating anything, clarify with Arch:

• Agent name and ID (lowercase, no spaces for ID)
• Role and responsibilities (specific, not vague)
• Model tier: cheap (Kimi K2.5 only) or full cascade (include Claude Sonnet)
• Whether it needs a Telegram group for Q&A
• Whether it needs cron jobs (what schedule, what tasks)
• Whether heartbeat should be enabled or disabled

2. Stop the Gateway

openclaw gateway stop

MANDATORY before editing

openclaw.json

cron/jobs.json

jobs.json

3. Backup Config

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.$(date +%Y%m%d%H%M%S)

4. Create Directories

mkdir -p ~/.openclaw/workspace-<agent_id>/memory
mkdir -p ~/.openclaw/agents/<agent_id>/agent

NEVER reuse

agentDir

5. Write Workspace Files

Use templates from

assets/templates/

SOUL.md

IDENTITY.md

USER.md

AGENTS.md

HEARTBEAT.md

SOUL.md is the most important file. Be specific about responsibilities. Include behavioral modes if the agent operates differently in different contexts (e.g., briefing mode vs chat mode).

6. Edit openclaw.json — Agent Entry

Add to

agents.list[]

Minimal entry:

{
  "id": "<agent_id>",
  "name": "<Display Name>",
  "workspace": "/home/archit/.openclaw/workspace-<agent_id>",
  "agentDir": "/home/archit/.openclaw/agents/<agent_id>/agent",
  "identity": { "name": "<Display Name>" }
}

Common additions:

• "model"

  — Override the default model cascade. Exclude expensive models for worker agents.

• "heartbeat": { "every": "0" }

  — Disable heartbeat for cron-only agents.

• "groupChat": { "mentionPatterns": ["@<id>", "@<Name>"] }

  — Enable @mentions in groups.

Only ONE agent should have

"default": true

7. Edit openclaw.json — Telegram Routing (if needed)

THREE separate config changes are required. Missing any one causes silent failures. See references/telegram-routing.md for the full explanation.

1. Group config in

   channels.telegram.groups

   :

   "-100XXXXXXXXXX": { "requireMention": false }
   

2. Binding in

   bindings[]

   :

   { "agentId": "<id>", "match": { "channel": "telegram", "peer": { "kind": "group", "id": "-100XXXXXXXXXX" } } }
   

3. Mention patterns on the agent entry (already done in step 6 if

   groupChat

   was added).

8. Create Cron Jobs (if needed)

Edit

cron/jobs.json

• Dynamic group ID resolution preamble (NEVER hardcode Telegram group IDs):

  FIRST: Resolve your Telegram group ID by running:
  jq -r '.bindings[] | select(.agentId == "<agent_id>") | .match.peer.id' ~/.openclaw/openclaw.json
  Use the output as the target for all Telegram messages in this task.
  

• Date injection:

  $(date '+%A, %B %d, %Y')

  after the preamble
• Explicit constraints: source allowlists, recency rules, format templates
• Delivery instructions: use

  target='<AGENT_GROUP_ID>'

  placeholder (resolved by the preamble)

This self-healing pattern ensures cron jobs survive Telegram group ID migrations. See references/prompt-patterns.md for full patterns and references/telegram-routing.md for why this matters.

Critical: If copying files or prompts from another agent's workspace, grep for hardcoded paths and update them.

9. Restart Gateway and Verify

openclaw gateway start

Verify in logs:

• Agent registered:

  agent registered: <id>

• Messages route correctly:

  lane enqueue: lane=session:agent:<id>:...

If messages to a Telegram group show

skip: no-mention

channels.telegram.groups

Reference Files

Template Files

Starter templates for workspace files are in

assets/templates/