> agents & sessions
An agent is an isolated persona — its own workspace, model auth, and SQLite session store under ~/.openclaw/agents/<id>. Bindings route each inbound message to an agent by most-specific match (exact peer, then guild/role, then account, then channel, then the default agent), so one gateway can run a fast chat agent on WhatsApp and a deep-thinking one on Telegram. Sessions are the running conversations; you can list them, read redacted history, inject messages, or spawn background runs from the CLI.
// agents & sessions
6 commands$ openclaw agents list$ openclaw agents add work --model anthropic/claude-sonnet-4-6 --bind telegram$ openclaw agents bind work telegram$ openclaw sessions list --agent work$ openclaw sessions send my-session-id "continue where we left off"$ openclaw agent --message "summarize today's incidents" --thinking high// faq
What is the difference between an agent and a session?
An agent is a configured persona with its own workspace, model, auth profiles, and skill allowlist. A session is one running conversation belonging to an agent, stored in that agent's SQLite database. One agent typically owns many sessions — one per peer or group, depending on your dmScope.
How do I route different channels to different agents?
Add agents with openclaw agents add <id> --model ... --bind <channel>, then refine routing with bindings. Matching is most-specific-wins: an exact peer beats a guild plus role, which beats an account, which beats a bare channel. accountId: "*" matches all accounts on a channel; omitting accountId matches only the default account.
Why do two people on my WhatsApp number share the same conversation?
Because DMs collapse to one session per agent by default (session key agent:<id>:main). Set session.dmScope to per-channel-peer so each sender gets an isolated context, or per-peer to isolate a sender across all channels. This matters most on allowlist or open DM channels with multiple people.
Can I trigger an agent from a script without a chat message?
Yes. openclaw agent --message "..." runs the assistant once from the terminal; add --deliver --to <target> to send the reply out to a channel instead of just printing it. For background work, openclaw sessions spawn <agent> --message "..." starts an async run, optionally --to an existing session.
Is it safe to give an agent the sessions tools?
sessions_spawn and sessions_send are control-plane tools that can drive other conversations, so deny them for any agent that handles untrusted content — a prompt-injected message could otherwise message people or spawn runs on your behalf. The secure baseline denies the automation and runtime tool groups for messaging agents.