add-agent

add-agent

Quickly add a new isolated Agent with a dedicated Telegram Bot.

Trigger

User says something like: "Add a new agent, ID is marketing, name is Marketing Assistant, telegram Bot Token is xxx, allowFrom is 123456789, responsible for content marketing and social media"

Steps

Once a new agent request is received, execute in the following order:

1. Extract Parameters

Extract the following fields from user input: AGENT_ID: English ID (e.g. marketing) AGENT_NAME: Agent name (e.g. Marketing Assistant, Alice, WorkBot, etc.) BOT_TOKEN: Telegram Bot Token ALLOW_FROM: allowFrom numeric ID (e.g. 123456789) DESCRIPTION: Role description (e.g. responsible for content marketing and social media) If any field is missing, ask the user to provide it before continuing.

2. Detect Installation Directory

Read the current openclaw.json path, extract the actual paths from the existing main agent in agents.list to derive: STATE_DIR: e.g. /home/openclaw/.openclaw MAIN_WORKSPACE: main agent workspace path MAIN_AGENT_DIR: main agent agentDir path NEW_WORKSPACE: ${STATE_DIR}/workspace-${AGENT_ID} NEW_AGENT_DIR: ${STATE_DIR}/agents/${AGENT_ID}/agent

3. Backup Config File

cp ${CONFIG_PATH} ${CONFIG_PATH}.bak.$(date +%Y%m%d%H%M%S)

4. Run openclaw agents add

openclaw agents add ${AGENT_ID} This automatically initializes the workspace directory structure, agentDir, and default files like SOUL.md and AGENTS.md.

5. Copy Auth, Skills and USER.md

# Copy auth profiles cp ${MAIN_AGENT_DIR}/auth-profiles.json \ ${NEW_AGENT_DIR}/auth-profiles.json # Copy skills cp -r ${MAIN_WORKSPACE}/skills/ \ ${NEW_WORKSPACE}/skills/ # Copy USER.md cp ${MAIN_WORKSPACE}/USER.md \ ${NEW_WORKSPACE}/USER.md

6. Generate Persona Files

• Overwrite ${NEW_WORKSPACE}/SOUL.md:
• # ${AGENT_NAME}
• ## Identity
• You are ${AGENT_NAME}, ${DESCRIPTION}.
• Your partner is the main agent. You collaborate together to complete tasks.
• ## Core Responsibilities
• ${DESCRIPTION}
• ## Personality
• Action-oriented: Break down tasks immediately and provide clear execution steps
• Proactive reporting: Report results to main after completing tasks
• Professional: Maintain high standards for all outputs
• ## Rules
• Do not execute high-risk operations without confirmation
• Always notify the user before executing operations that require manual approval
• Overwrite ${NEW_WORKSPACE}/AGENTS.md:
• # ${AGENT_NAME} Agent Configuration
• ## Other Agents in the System
• **main**: Primary agent, responsible for daily conversation, task coordination and decisions
• **${AGENT_ID} (yourself)**: ${DESCRIPTION}
• ## Collaboration Rules
• ### Receiving Tasks from main
• 1. Confirm task goal and priority
• 2. Break down execution steps
• 3. Execute and record results
• 4. Report results back to main upon completion
• ### When to Proactively Contact main
• Operations that require final user confirmation
• Result reporting after task completion
• Escalating anomalies or unexpected situations

7. Update openclaw.json

Read the current config and append the following: Add to agents.list: { "id": "${AGENT_ID}", "name": "${AGENT_NAME}", "workspace": "${NEW_WORKSPACE}", "agentDir": "${NEW_AGENT_DIR}" } Add to bindings: { "agentId": "${AGENT_ID}", "match": { "channel": "telegram", "accountId": "${AGENT_ID}" } } Add to channels.telegram.accounts: "${AGENT_ID}": { "enabled": true, "botToken": "${BOT_TOKEN}", "dmPolicy": "pairing", "allowFrom": ["${ALLOW_FROM}"], "groupPolicy": "allowlist", "streaming": "off" } Handle tools config (check before writing): Check whether the tools field exists: If tools does not exist, add the full block: "tools": { "agentToAgent": { "enabled": true, "allow": ["main", "${AGENT_ID}"] }, "sessions": { "visibility": "all" } } If tools exists but has no agentToAgent, add it: "agentToAgent": { "enabled": true, "allow": ["main", "${AGENT_ID}"] } If agentToAgent already exists, only append "${AGENT_ID}" to the allow array (no duplicates) If sessions.visibility does not exist, add it: "sessions": { "visibility": "all" }

8. Validate JSON

cat ${CONFIG_PATH} | python3 -m json.tool If validation fails, stop immediately and restore from backup: cp ${CONFIG_PATH}.bak.* ${CONFIG_PATH} Report the exact error to the user.

9. Fix File Permissions

chown -R $(stat -c '%U:%G' ${MAIN_WORKSPACE}) ${NEW_WORKSPACE}/ chown -R $(stat -c '%U:%G' ${MAIN_AGENT_DIR}) ${NEW_AGENT_DIR}/

10. Report Completion

• Reply to the user:
• ✅ Agent "${AGENT_NAME}" (${AGENT_ID}) created successfully!
• Completed:
• openclaw agents add initialized
• openclaw.json updated
• Auth, skills and USER.md copied from main
• SOUL.md / AGENTS.md generated
• agentToAgent communication configured
• JSON validation passed
• ⚠️ Manual steps required:
• 1. Restart the Gateway:
• openclaw gateway restart
• 2. Verify bindings:
• openclaw agents list --bindings
• 3. Open Telegram, find the new Bot and send /start to complete pairing