add-agent

Add a new OpenClaw Agent, automatically configure openclaw.json, create workspace, copy auth and skills.

Security Scan

The skill's claimed purpose (creating a new agent and wiring a Telegram bot) is coherent, but the runtime instructions are vague and include operations that duplicate credentials, perform global config edits, and use unsafe shell patterns — these behaviors increase risk and need careful review before use.

Purpose & Capability

Name/description match the instructions: the SKILL.md details creating workspaces, updating openclaw.json, copying skills/auth and configuring Telegram binding. The meta.json requirement of python3 aligns with using python -m json.tool for validation.

Instruction Scope

Instructions tell the agent to read and modify the global openclaw.json, copy auth-profiles.json (potentially containing secrets), copy the full skills directory, and change ownership. Several important variables (e.g., CONFIG_PATH/where to find openclaw.json) are assumed but not clearly defined. There is no input sanitization (AGENT_ID, BOT_TOKEN, ALLOW_FROM), no protection against path traversal or injection, and restore instructions use a wildcard pattern (cp ${CONFIG_PATH}.bak.* ${CONFIG_PATH}) which is unsafe. These gaps could lead to accidental config corruption or unintended disclosure/duplication of secrets.

Install Mechanism

This is an instruction-only skill with no install actions or external downloads. That's lower risk; the only runtime dependency is python3 (declared in _meta.json) and is justified by the JSON validation step.

Credentials

The skill does not request environment variables or external credentials, which is consistent. However, it instructs copying auth-profiles.json from the main agent into the new agent's directory — effectively duplicating whatever credentials live there. Copying credentials is plausible for convenience but increases attack surface and may be disproportionate unless the user intends the new agent to have identical access. The SKILL.md doesn't offer an option to exclude or filter sensitive entries.

Persistence & Privilege

The skill modifies the global openclaw.json and agent-to-agent bindings (expected for creating a new agent). It does not request always:true or persistent privileges. Still, writing to global config and enabling agentToAgent communication are privileged actions: users should review resulting openclaw.json changes before restarting services.

What to consider before installing

This skill generally does what it says, but proceed carefully. Before running: 1) Ensure you know where your openclaw.json (CONFIG_PATH) actually resides and back it up manually (don't rely on wildcard restores). 2) Inspect main/auth-profiles.json — it may contain tokens/credentials; decide whether the new agent should receive those secrets or if you should copy only a sanitized subset. 3) Enforce a safe AGENT_ID character policy (alphanumeric, hyphen/underscore) to avoid path traversal or injection. 4) Prefer safer JSON edits (jq or a small script) and atomic file writes rather than ad-hoc appends; validate and review the modified openclaw.json before restarting the gateway. 5) Avoid handing BOT_TOKEN through insecure channels; provide it securely when prompted. If possible, test the procedure in a non-production environment first. These changes reduce the chance of accidental credential exposure or configuration corruption.

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