| name | agent-deploy |
| description | Deploy a new isolated OpenClaw agent with its own Telegram bot, workspace, and session storage. Use when user asks to create a new agent, add a new bot, or set up multi-agent routing. Uses openclaw config set for safe config updates with doctor validation and auto-rollback. |
Agent Deploy & Isolation Skill
WHEN TO USE THIS SKILL
Use this skill when the user says ANY of the following (or similar):
- "deploy a new agent"
- "add a new agent"
- "create a new agent"
- "set up a new bot"
- "bind a bot to a new agent"
- "add a telegram bot"
- "list agents" or "show agents"
- "remove agent" or "delete agent"
WHAT YOU NEED FROM THE USER
Before running any deploy script, you MUST collect these two values from the user:
| Required | Example | How to get it |
|---|
| agentId | research | Ask: "What should I name this agent?" (lowercase, no spaces, no special chars) |
| botToken | 123456:ABC-xyz | Ask: "What is the Telegram Bot Token?" (user gets this from @BotFather) |
If the user provides both in their message, proceed immediately.
If the user is missing one or both, ask for the missing value(s) before proceeding.
HOW TO EXECUTE
Action: DEPLOY a new agent
Run this exact command, replacing <agentId> and <botToken> with the user's values:
bash {baseDir}/scripts/deploy.sh <agentId> <botToken>
Example: If user says "deploy agent called research with token 123456:ABCdef":
bash {baseDir}/scripts/deploy.sh research 123456:ABCdef
After the script finishes:
- If output contains "SUCCESS": tell the user the agent is deployed.
- If output contains "CONFLICT": tell the user the agent already exists.
- If output contains "ERROR": tell the user what went wrong.
- If output contains "ROLLING BACK": tell the user the change was safely reverted.
DO NOT run systemctl restart unless the script output explicitly says to.
The script handles hot-reload automatically for channels and bindings.
Action: LIST all agents
bash {baseDir}/scripts/list.sh
Show the output table to the user as-is.
Action: REMOVE an agent
Run this exact command, replacing <agentId>:
bash {baseDir}/scripts/remove.sh <agentId>
Example: If user says "remove the research agent":
bash {baseDir}/scripts/remove.sh research
STRICT RULES ??DO NOT VIOLATE
- NEVER edit openclaw.json directly. Do not use
write, edit, apply_patch, or any file editing tool on openclaw.json. The deploy script uses openclaw config set which is the only safe way.
- NEVER skip the pre-flight check. Always run the full deploy.sh script. Do not try to run individual
openclaw config set commands yourself.
- NEVER change the agentId format. It must be lowercase letters, numbers, and hyphens only. No spaces, no uppercase, no special characters.
- NEVER deploy without a valid bot token. The token must match the format:
digits:alphanumeric (e.g., 123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw).
- NEVER modify the main agent. The
remove.sh script refuses to remove the main agent. Do not try to work around this.
WHAT THE SCRIPT DOES AUTOMATICALLY
You do NOT need to do any of these manually. The script handles everything:
- Creates isolated workspace at
~/.openclaw/workspace-<agentId>/
- Adds agent to
agents.list with safe defaults:
tools.deny: ["gateway"] (agent cannot modify core config)sandbox.mode: "non-main" (non-main sessions are sandboxed)sandbox.scope: "agent" (one container per agent)sandbox.workspaceAccess: "none" (sandbox cannot access host workspace)
- Adds routing binding:
<agentId> -> telegram:<agentId>
- Adds Telegram account with the bot token
- Validates with
openclaw doctor
- Auto-rollbacks on any failure
- Merges API keys from BOTH global config (
openclaw.json auth.profiles) AND main agent's auth-profiles.json
- Migrates from single-bot to multi-account mode if needed
TROUBLESHOOTING
If the user says the new bot is not responding after deploy:
- First, check logs:
journalctl --user -u openclaw-gateway --no-pager -n 20
- Look for
[telegram] [<agentId>] starting provider in logs
- If NOT found, restart:
systemctl --user restart openclaw-gateway
- If still not working, run:
bash {baseDir}/scripts/list.sh to verify config
ENVIRONMENT VARIABLES
These are optional. The scripts use sensible defaults:
| Variable | Default | Description |
|---|
OPENCLAW_CONFIG_PATH | ~/.openclaw/openclaw.json | Custom config file path |
OPENCLAW_BIN | openclaw | Custom openclaw CLI path |
