Architecture

This page covers the internal architecture of the LogLife plugin — how users are isolated, how configuration is generated, and how the system scales.

​

Multi-user

LogLife supports multiple users on a single OpenClaw instance. Each user gets their own agent, which means fully isolated conversation history, long-term memory, API keys, model selection, and usage tracking. All of this is achieved through configuration — no OpenClaw source modifications are needed.

​

How it works

The multi-user system maps each user to their own OpenClaw agent. When a message arrives, the gateway uses bindings to route it to the correct agent based on the sender’s channel and peer ID. Allow-lists control who can message the bot on each channel.

​

What each user gets

​

Generated configuration

The multi-user system produces a generated.json file that contains:

• agents.list — one agent definition per user (ID, name, model, skills)
• bindings — routing rules mapping {channel, peerId} to an agent
• channels — per-channel allow-lists and DM policies
• session — session scoping settings
• env — shared environment variables (API keys used by all users)

At runtime, the plugin merges this generated structure directly into openclaw.json after register/unregister operations. This avoids relying on $include during hot reload.

​

Session scoping

The default session scope is main, which gives each agent one continuous conversation regardless of which channel the user messages from. This is the correct setting for journaling — your journal is your journal, whether you write from WhatsApp or Telegram. Other OpenClaw session scopes are available but less useful with the multi-user layer: Since each agent only has one user, the agent boundary already provides complete isolation between users. The dmScope setting only affects behavior within each agent.

​

Runtime user registration

New users are added at runtime through the /loglife/register endpoint. The registration flow:

1. The plugin reads users.json (the source of truth for all users)
2. Appends the new user with their phone number as an identifier
3. Calls generateConfig() to rebuild generated.json
4. Merges generated agents, bindings, channels, and session into openclaw.json
5. Writes openclaw.json (no restart required)

The gateway picks up the new agent, binding, and allow-list entry immediately.

​

Runtime user removal

Users can be removed at runtime through /loglife/unregister:

1. The plugin reads users.json
2. Removes the matching user by phone identifier
3. Rebuilds generated.json
4. Merges the updated generated config into openclaw.json
5. Cleans stale allow-list fields when a channel no longer has managed users

This keeps add/remove symmetric and prevents stale access rules.

​

Memory isolation

OpenClaw has six layers of persistent state. Five of them are fully isolated per agent (and therefore per user): The only shared layer is debug logs, which are operational data that no agent reads to inform its responses. For anything that affects what the bot says, remembers, or knows, the isolation is complete.

​

Per-user API keys

By default, all users share API keys configured in shared.env within users.json. When a user needs their own keys (for separate billing, rate limits, or scoped services), their env field in users.json is populated and writeAuthProfiles() writes per-agent credentials to ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. API keys can be stored as 1Password references (op:// URIs) instead of raw values. These are resolved at config generation time via the op read CLI.

​

File structure

The multi-user code lives inside the plugin at plugin/multi-user/: