OpenClaw Multi-User and Team Management Guide

Introduction

When your OpenClaw instance is no longer for personal use only but needs to serve an entire team, you will need to consider user management, permission control, and resource allocation. This article explains how to upgrade OpenClaw from a personal tool to a team-level AI assistant platform.

1. Multi-User Architecture Overview

OpenClaw's multi-user architecture is based on the following core concepts:

┌──────────────────────────────────────────┐
│            OpenClaw Gateway              │
│                (:18789)                  │
├──────────────────────────────────────────┤
│         User Management Module           │
│  ┌──────┐  ┌──────┐  ┌──────┐           │
│  │Admin │  │User A│  │User B│  ...      │
│  │(admin)│  │(user) │  │(user) │          │
│  └──────┘  └──────┘  └──────┘           │
├──────────────────────────────────────────┤
│  Shared Skill Pool │ Private Skills │ Model Quota Mgmt │
├──────────────────────────────────────────┤
│       Channel Layer (isolated sessions)  │
│  WhatsApp │ Telegram │ Discord │ Slack   │
└──────────────────────────────────────────┘

2. Enabling Multi-User Mode

2.1 Basic Configuration

// ~/.config/openclaw/openclaw.json5
{
  "multiUser": {
    "enabled": true,
    // User data storage directory
    "dataDir": "/var/lib/openclaw/users",
    // User authentication method
    "authMethod": "token",
    // Default user role
    "defaultRole": "user",
    // Allow self-registration
    "selfRegistration": false
  }
}

2.2 Creating an Admin Account

# Initialize multi-user mode
openclaw onboard --multi-user

# Create an administrator
openclaw user create \
  --username admin \
  --role admin \
  --email [email protected]

# The system will generate an API Token -- keep it safe
# Token: oc_admin_a1b2c3d4e5f6...

2.3 Adding Regular Users

# Create a regular user
openclaw user create \
  --username alice \
  --role user \
  --email [email protected]

# List all users
openclaw user list

Example output:

┌──────────┬─────────┬──────────────────────┬─────────┐
│ Username │ Role    │ Email                │ Status  │
├──────────┼─────────┼──────────────────────┼─────────┤
│ admin    │ admin   │ [email protected]    │ active  │
│ alice    │ user    │ [email protected]    │ active  │
│ bob      │ user    │ [email protected]      │ active  │
└──────────┴─────────┴──────────────────────┴─────────┘

3. User Isolation

3.1 Conversation Isolation

Each user's conversation history is completely independent and invisible to others:

{
  "multiUser": {
    "isolation": {
      // Conversation history isolation
      "conversations": true,
      // User preference isolation
      "preferences": true,
      // Custom system prompt isolation
      "systemPrompts": true
    }
  }
}

3.2 Data Storage Structure

/var/lib/openclaw/users/
├── admin/
│   ├── conversations/
│   ├── preferences.json
│   └── skills/           # Private skills
├── alice/
│   ├── conversations/
│   ├── preferences.json
│   └── skills/
└── bob/
    ├── conversations/
    ├── preferences.json
    └── skills/

3.3 Channel-to-User Mapping

Users from different channels need to be mapped to OpenClaw internal users:

{
  "multiUser": {
    "channelMapping": {
      "telegram": {
        // Telegram User ID -> OpenClaw username
        "123456789": "alice",
        "987654321": "bob"
      },
      "whatsapp": {
        // WhatsApp number -> OpenClaw username
        "+8613800138000": "alice",
        "+8613900139000": "bob"
      },
      "discord": {
        // Discord User ID -> OpenClaw username
        "1234567890": "alice"
      }
    },
    // Policy for unmapped users
    "unmappedUserPolicy": "create_auto"  // auto | reject | guest
  }
}

4. Roles and Permission Management

4.1 Built-In Roles

Role	Permissions	Use Case
`admin`	Full access	System administrator
`manager`	User management + configuration	Team lead
`user`	Normal usage	Regular team member
`guest`	Restricted usage	Temporary user

4.2 Detailed Permission List

{
  "roles": {
    "admin": {
      "permissions": [
        "user.create", "user.delete", "user.modify",
        "config.modify", "skill.manage",
        "model.all", "channel.manage",
        "stats.view", "logs.view"
      ]
    },
    "manager": {
      "permissions": [
        "user.create", "user.modify",
        "skill.manage", "model.all",
        "stats.view"
      ]
    },
    "user": {
      "permissions": [
        "chat.send", "chat.history",
        "skill.use", "model.allowed",
        "preference.modify"
      ]
    },
    "guest": {
      "permissions": [
        "chat.send"
      ],
      "restrictions": {
        "maxMessagesPerDay": 50,
        "maxConversationLength": 10
      }
    }
  }
}

4.3 Custom Roles

# Create a custom role
openclaw role create developer \
  --permissions "chat.send,chat.history,skill.use,skill.create,model.all"

# Assign a user to the role
openclaw user modify alice --role developer

5. Model Quota Management

5.1 Setting Quotas per User

{
  "quotas": {
    "default": {
      "dailyMessages": 200,
      "dailyTokens": 500000,
      "maxTokensPerMessage": 4096,
      "allowedModels": ["claude-sonnet-4-20250514", "gpt-4o-mini"]
    },
    "users": {
      "alice": {
        "dailyMessages": 500,
        "dailyTokens": 1000000,
        "allowedModels": ["claude-sonnet-4-20250514", "claude-opus-4-20250514", "gpt-4o"]
      },
      "bob": {
        "dailyMessages": 100,
        "dailyTokens": 200000,
        "allowedModels": ["claude-sonnet-4-20250514"]
      }
    }
  }
}

5.2 Setting Quotas by Role

{
  "quotas": {
    "byRole": {
      "admin": {
        "dailyMessages": -1,     // -1 means unlimited
        "dailyTokens": -1,
        "allowedModels": ["*"]   // All models
      },
      "user": {
        "dailyMessages": 200,
        "dailyTokens": 500000,
        "allowedModels": ["claude-sonnet-4-20250514", "gpt-4o-mini"]
      },
      "guest": {
        "dailyMessages": 20,
        "dailyTokens": 50000,
        "allowedModels": ["gpt-4o-mini"]
      }
    }
  }
}

5.3 Viewing Quota Usage

# View quota usage for all users
openclaw user stats

# Example output:
# ┌──────────┬──────────┬──────────┬─────────────┐
# │ User     │ Messages │ Tokens   │ Quota Used  │
# ├──────────┼──────────┼──────────┼─────────────┤
# │ alice    │ 156/500  │ 342K/1M  │ 34.2%       │
# │ bob      │ 89/100   │ 178K/200K│ 89.0%       │
# └──────────┴──────────┴──────────┴─────────────┘

# View detailed usage statistics for a single user
openclaw user stats alice --detail

5.4 Handling Quota Exceeded

{
  "quotas": {
    "onExceeded": {
      // Reply message when quota is exceeded
      "message": "Your daily usage quota has been reached. Please try again tomorrow. Contact your administrator for additional quota.",
      // Whether to notify the administrator
      "notifyAdmin": true,
      // Whether to allow fallback to a cheaper model
      "fallbackToFreeModel": true,
      "fallbackModel": "gpt-4o-mini"
    }
  }
}

6. Shared Skills vs. Private Skills

6.1 Skill Directory Structure

~/.openclaw/
├── skills/                    # Globally shared skills
│   ├── translator.SKILL.md
│   ├── code-review.SKILL.md
│   └── meeting-notes.SKILL.md
└── users/
    ├── alice/
    │   └── skills/            # Alice's private skills
    │       └── my-custom.SKILL.md
    └── bob/
        └── skills/            # Bob's private skills
            └── data-analysis.SKILL.md

6.2 Skill Permission Configuration

{
  "skills": {
    "shared": {
      "path": "~/.openclaw/skills",
      // Available to all users
      "accessLevel": "all"
    },
    "private": {
      // Each user has their own skill directory
      "pathTemplate": "~/.openclaw/users/{{username}}/skills",
      "accessLevel": "owner"
    },
    // Skill management permissions
    "management": {
      "createShared": ["admin", "manager"],
      "createPrivate": ["admin", "manager", "user"],
      "deleteShared": ["admin"],
      "deletePrivate": ["admin", "owner"]
    }
  }
}

6.3 Team Shared Skill Example

<!-- ~/.openclaw/skills/team-qa.SKILL.md -->
# Team Q&A Assistant

You are the team's internal Q&A assistant, responsible for answering questions about company policies, processes, and technical standards.

## Knowledge Base
- Reference documents in the /data/company-docs/ directory
- Prioritize the latest version of documents

## Response Guidelines
- Cite specific document names and sections
- If unsure, clearly state this and suggest contacting the relevant person
- Do not disclose confidential information in group chats

7. Usage Analytics

7.1 Configuring Analytics Collection

{
  "analytics": {
    "enabled": true,
    "storage": "sqlite",
    "dbPath": "/var/lib/openclaw/analytics.db",
    "retention": "90d",   // Retain data for 90 days
    "collect": {
      "messageCount": true,
      "tokenUsage": true,
      "modelUsage": true,
      "responseTime": true,
      "skillUsage": true,
      "channelUsage": true
    }
  }
}

7.2 Viewing Analytics Reports

# View overall usage summary
openclaw dashboard

# View statistics for a specific time range
openclaw stats --from 2026-04-01 --to 2026-04-08

# Export CSV report
openclaw stats --export csv --output /tmp/openclaw-stats.csv

7.3 Querying Statistics via API

# Get user usage ranking
curl -s http://localhost:18789/api/v1/admin/stats/users \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq .

# Get model usage statistics
curl -s http://localhost:18789/api/v1/admin/stats/models \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq .

8. Team Deployment Best Practices

8.1 Deployment Checklist

□ Enable multi-user mode and create an administrator
□ Create accounts for each team member and assign roles
□ Configure reasonable usage quotas
□ Create team shared skills
□ Set up channel-to-user mapping
□ Configure usage analytics and monitoring
□ Establish usage guidelines and communicate them to the team
□ Regularly review usage patterns and quotas

8.2 Security Recommendations

Measure	Importance	Description
Rotate API Tokens regularly	High	Replace every 90 days
Enable audit logging	High	Log all administrative actions
Principle of least privilege	High	Grant only necessary permissions
Sensitive information filtering	Medium	Prevent AI from leaking sensitive data
Regular user list reviews	Medium	Remove departed personnel promptly
Quota alerting	Medium	Notify admin when usage exceeds 80%

8.3 Capacity Planning

Team Size	Recommended Setup	Monthly Budget Reference
Under 5	1-core 2GB VPS	$50-100
5-20	2-core 4GB VPS	$100-300
20-50	4-core 8GB VPS	$300-800
Over 50	Cluster deployment	$800+

8.4 User Management Command Quick Reference

# Create a user
openclaw user create --username NAME --role ROLE --email EMAIL

# Change user role
openclaw user modify USERNAME --role NEW_ROLE

# Disable a user
openclaw user disable USERNAME

# Enable a user
openclaw user enable USERNAME

# Delete a user
openclaw user delete USERNAME

# Reset a user's Token
openclaw user reset-token USERNAME

# View user details
openclaw user info USERNAME

# Bulk import users
openclaw user import --file users.csv

With the configuration above, you can turn OpenClaw into a secure, efficient team AI assistant platform, allowing every member to harness the power of AI while maintaining proper management and control.