\r \r

add-agent\r

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

Trigger\r

\r User says something like:\r

"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"\r \r

Steps\r

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

1. Extract Parameters\r

\r Extract the following fields from user input:\r

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

2. Detect Installation Directory\r

\r Read the current openclaw.json path, extract the actual paths from the existing main agent in agents.list to derive:\r

• STATE_DIR: e.g. /home/openclaw/.openclaw\r
• MAIN_WORKSPACE: main agent workspace path\r
• MAIN_AGENT_DIR: main agent agentDir path\r
• NEW_WORKSPACE: ${STATE_DIR}/workspace-${AGENT_ID}\r
• NEW_AGENT_DIR: ${STATE_DIR}/agents/${AGENT_ID}/agent\r \r

3. Backup Config File\r

cp ${CONFIG_PATH} ${CONFIG_PATH}.bak.$(date +%Y%m%d%H%M%S)\r
```\r
\r
### 4. Run openclaw agents add\r
```bash\r
openclaw agents add ${AGENT_ID}\r
```\r
\r
This automatically initializes the workspace directory structure, agentDir, and default files like SOUL.md and AGENTS.md.\r
\r
### 5. Copy Auth, Skills and USER.md\r
```bash\r
# Copy auth profiles\r
cp ${MAIN_AGENT_DIR}/auth-profiles.json \\r
   ${NEW_AGENT_DIR}/auth-profiles.json\r
\r
# Copy skills\r
cp -r ${MAIN_WORKSPACE}/skills/ \\r
      ${NEW_WORKSPACE}/skills/\r
\r
# Copy USER.md\r
cp ${MAIN_WORKSPACE}/USER.md \\r
   ${NEW_WORKSPACE}/USER.md\r
```\r
\r
### 6. Generate Persona Files\r
\r
Overwrite `${NEW_WORKSPACE}/SOUL.md`:\r
```markdown\r
# ${AGENT_NAME}\r
\r
## Identity\r
You are ${AGENT_NAME}, ${DESCRIPTION}.\r
Your partner is the main agent. You collaborate together to complete tasks.\r
\r
## Core Responsibilities\r
${DESCRIPTION}\r
\r
## Personality\r
- Action-oriented: Break down tasks immediately and provide clear execution steps\r
- Proactive reporting: Report results to main after completing tasks\r
- Professional: Maintain high standards for all outputs\r
\r
## Rules\r
- Do not execute high-risk operations without confirmation\r
- Always notify the user before executing operations that require manual approval\r
```\r
\r
Overwrite `${NEW_WORKSPACE}/AGENTS.md`:\r
```markdown\r
# ${AGENT_NAME} Agent Configuration\r
\r
## Other Agents in the System\r
\r
- **main**: Primary agent, responsible for daily conversation, task coordination and decisions\r
- **${AGENT_ID} (yourself)**: ${DESCRIPTION}\r
\r
## Collaboration Rules\r
\r
### Receiving Tasks from main\r
1. Confirm task goal and priority\r
2. Break down execution steps\r
3. Execute and record results\r
4. Report results back to main upon completion\r
\r
### When to Proactively Contact main\r
- Operations that require final user confirmation\r
- Result reporting after task completion\r
- Escalating anomalies or unexpected situations\r
```\r
\r
### 7. Update openclaw.json\r
\r
Read the current config and append the following:\r
\r
**Add to agents.list:**\r
```json\r
{\r
  "id": "${AGENT_ID}",\r
  "name": "${AGENT_NAME}",\r
  "workspace": "${NEW_WORKSPACE}",\r
  "agentDir": "${NEW_AGENT_DIR}"\r
}\r
```\r
\r
**Add to bindings:**\r
```json\r
{\r
  "agentId": "${AGENT_ID}",\r
  "match": {\r
    "channel": "telegram",\r
    "accountId": "${AGENT_ID}"\r
  }\r
}\r
```\r
\r
**Add to channels.telegram.accounts:**\r
```json\r
"${AGENT_ID}": {\r
  "enabled": true,\r
  "botToken": "${BOT_TOKEN}",\r
  "dmPolicy": "pairing",\r
  "allowFrom": ["${ALLOW_FROM}"],\r
  "groupPolicy": "allowlist",\r
  "streaming": "off"\r
}\r
```\r
\r
**Handle tools config (check before writing):**\r
\r
Check whether the `tools` field exists:\r
\r
- If `tools` does not exist, add the full block:\r
```json\r
"tools": {\r
  "agentToAgent": {\r
    "enabled": true,\r
    "allow": ["main", "${AGENT_ID}"]\r
  },\r
  "sessions": {\r
    "visibility": "all"\r
  }\r
}\r
```\r
\r
- If `tools` exists but has no `agentToAgent`, add it:\r
```json\r
"agentToAgent": {\r
  "enabled": true,\r
  "allow": ["main", "${AGENT_ID}"]\r
}\r
```\r
\r
- If `agentToAgent` already exists, only append `"${AGENT_ID}"` to the `allow` array (no duplicates)\r
\r
- If `sessions.visibility` does not exist, add it:\r
```json\r
"sessions": {\r
  "visibility": "all"\r
}\r
```\r
\r
### 8. Validate JSON\r
```bash\r
cat ${CONFIG_PATH} | python3 -m json.tool\r
```\r
\r
If validation fails, stop immediately and restore from backup:\r
```bash\r
cp ${CONFIG_PATH}.bak.* ${CONFIG_PATH}\r
```\r
Report the exact error to the user.\r
\r
### 9. Fix File Permissions\r
```bash\r
chown -R $(stat -c '%U:%G' ${MAIN_WORKSPACE}) ${NEW_WORKSPACE}/\r
chown -R $(stat -c '%U:%G' ${MAIN_AGENT_DIR}) ${NEW_AGENT_DIR}/\r
```\r
\r
### 10. Report Completion\r
\r
Reply to the user:\r
```\r
✅ Agent "${AGENT_NAME}" (${AGENT_ID}) created successfully!\r
\r
Completed:\r
- openclaw agents add initialized\r
- openclaw.json updated\r
- Auth, skills and USER.md copied from main\r
- SOUL.md / AGENTS.md generated\r
- agentToAgent communication configured\r
- JSON validation passed\r
\r
⚠️ Manual steps required:\r
1. Restart the Gateway:\r
   openclaw gateway restart\r
\r
2. Verify bindings:\r
   openclaw agents list --bindings\r
\r
3. Open Telegram, find the new Bot and send /start to complete pairing\r