New Agent
Add one or more agents to your OpenClaw gateway with dedicated workspaces and messaging channels.
When to Use
- User wants to add a new AI agent or bot
- User wants to connect a bot to a messaging platform
- User wants to create a team of agents at once (batch mode)
Modes
| Mode | When | Script |
|---|
| Single | Add one agent | scripts/setup-agent.sh |
| Batch | Add multiple agents at once | scripts/batch-setup.sh |
⚠️ Always prefer batch mode when creating 2+ agents. Single-agent creation modifies openclaw.json each time, triggering a gateway hot reload per agent. For channels with persistent connections (Feishu WebSocket, Discord gateway), this causes repeated disconnects. Batch mode writes config once and restarts once.
Single Agent Mode
Required Information
| Field | Example |
|---|
| Agent name | "Luna" |
| Channel | telegram / discord / slack / feishu / whatsapp / signal / googlechat |
| Credentials | Bot token, app secret, or QR scan |
Step 1: Workspace + Registration
./scripts/setup-agent.sh {name}
This creates workspace files and registers the agent with openclaw agents add --non-interactive --workspace.
Step 2: Channel Configuration
Each channel needs two things in openclaw.json:
- An account entry under
channels.{channel}.accounts
- A binding in the top-level
bindings array
⚠️ The bindings array is at the root level of openclaw.json, NOT under agents.
Account Entry Templates
Add under channels.{channel}.accounts.{name}:
Telegram:
{
"dmPolicy": "pairing",
"botToken": "YOUR_BOT_TOKEN",
"groupPolicy": "open",
"streaming": "partial"
}
Discord:
{
"token": "YOUR_BOT_TOKEN"
}
Slack:
{
"mode": "socket",
"appToken": "xapp-...",
"botToken": "xoxb-..."
}
Feishu / Lark:
{
"appId": "YOUR_APP_ID",
"appSecret": "YOUR_APP_SECRET"
}
For Lark (global), add "domain": "lark".
WhatsApp / Signal — Use interactive login:
openclaw channels login --channel whatsapp --account {name}
openclaw channels login --channel signal --account {name}
Binding (Top-Level)
{
"agentId": "{name}-agent",
"match": {
"channel": "{channel}",
"accountId": "{name}"
}
}
Agent-to-Agent (Optional)
Add "{name}-agent" to tools.agentToAgent.allow.
Step 3: Verify & Pair
openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe
For DM channels, send /start to the bot, then:
openclaw pairing approve {channel} {CODE}
Batch Mode (Recommended for 2+ Agents)
Why Batch?
When creating multiple agents one-by-one:
- Each
openclaw agents add modifies openclaw.json → triggers hot reload
- Each channel account addition → another hot reload
- Feishu/Discord WebSocket disconnects and reconnects each time
- Messages sent during reload may be lost
Batch mode: all workspaces first, one config write, one restart.
Step 1: Define Agents
Create a JSON manifest file listing all agents:
[
{
"name": "基金经理",
"id": "fund-manager",
"role": "管理投资研究团队",
"emoji": "📈",
"channel": "feishu",
"appId": "cli_xxx",
"appSecret": "xxx"
},
{
"name": "科技研究员",
"id": "tech-researcher",
"role": "科技行业投资研究",
"emoji": "💻",
"channel": "feishu",
"appId": "cli_yyy",
"appSecret": "yyy"
}
]
Fields:
name — Display name (used in IDENTITY.md)id — Agent ID slug (lowercase, used for agent-id, account-id, workspace dir)role — Role description (used in SOUL.md)emoji — Agent emojichannel — Channel type- For Telegram: add
"botToken": "..."
- For Feishu: add
"appId": "..." and "appSecret": "..."
- For Discord: add
"token": "..."
- For Slack: add
"appToken": "..." and "botToken": "..."
Step 2: Run Batch Setup
./scripts/batch-setup.sh agents.json
This will:
- ✅ Create all workspaces (IDENTITY.md, SOUL.md, AGENTS.md, USER.md)
- ✅ Register all agents (
openclaw agents add --non-interactive)
- ✅ Add all channel accounts to
openclaw.json in one write
- ✅ Add all bindings in one write
- ✅ Add all agents to
agentToAgent.allow in one write
- ✅ Restart gateway once
Step 3: Pair
For each agent, send a message in the channel, then approve:
openclaw pairing approve {channel} {CODE}
Shared Channel (Multiple Agents, One Bot)
You can route multiple agents through a single bot using group-based bindings:
{
"agentId": "tech-researcher",
"match": {
"channel": "feishu",
"accountId": "shared-bot",
"groupId": "oc_xxxxx"
}
}
- DM → routes to default agent for that account
- Group messages → route based on
groupId match
- One bot, multiple brains
Notes
- All agents share existing model credentials — no extra API keys needed
- One channel is enough to bring an agent online
- Add more channels later by repeating the single-agent steps
- The default model comes from
agents.defaults.model.primary in your config
- Batch mode prevents hot-reload churn — always use it for 2+ agents
