Roles & Access Control

GoClaw provides role-based access control (RBAC) to manage what users can do.

Overview

The access control system has three layers:

1. Users — Who is allowed access (defined in users.json)
2. Roles — What permissions a user has (defined in goclaw.json)
3. Authentication — How users prove their identity

Users

Users are defined in users.json:

{
  "users": [
    {
      "name": "Alice",
      "role": "owner",
      "identities": [
        {"provider": "telegram", "id": "123456789"},
        {"provider": "whatsapp", "id": "1234567890"},
        {"provider": "http", "id": "alice"}
      ],
      "credentials": [
        {"type": "password", "hash": "<argon2-hash>", "label": "web-login"}
      ]
    },
    {
      "name": "Ratpup",
      "role": "user",
      "identities": [
        {"provider": "telegram", "id": "987654321"}
      ],
      "permissions": ["read", "memory_search"]
    }
  ]
}

Identities

Identities link external accounts to GoClaw users:

Built-in Roles

GoClaw recognizes three built-in role names:

Security by default: Only owner has built-in permissions. Both user and guest roles must be explicitly defined in the roles section of goclaw.json or users with those roles will be denied access.

Role Configuration

Define custom role permissions in goclaw.json:

{
  "roles": {
    "owner": {
      "tools": "*",
      "skills": "*",
      "memory": "full",
      "transcripts": "all",
      "commands": true
    },
    "user": {
      "tools": ["read", "memory_search", "transcript"],
      "skills": "*",
      "memory": "full",
      "transcripts": "own",
      "commands": true
    }
  }
}

Note: The guest role is not defined by default (secure by default). See Unknown Users for how to enable guest access.

Authentication

Password Authentication

For web UI access:

goclaw user set-password <username>

This prompts for a password interactively and stores the hash in users.json.

API Key Authentication

For programmatic access:

{
  "credentials": [
    {"type": "apikey", "hash": "<hash>", "label": "automation-key"}
  ]
}

Role Elevation

The user_auth tool allows guests to elevate their role by providing credentials:

{
  "auth": {
    "script": "./scripts/auth.sh",
    "allowedRoles": ["user"],
    "rateLimit": 3,
    "timeout": 10
  }
}

Security rules:

• Elevation to owner is always blocked — Even if the auth script returns owner, GoClaw refuses. Owner access requires being defined in users.json.
• Role must be in allowedRoles — The script can only grant roles explicitly listed.
• Role must be defined — The target role must exist in the roles config.

Supervision

Owners can supervise active sessions — watching, guiding, or ghostwriting agent responses in real-time.

See Session Supervision for full documentation on:

• Real-time session monitoring
• Guidance messages (visible only to agent)
• Ghostwriting mode (respond as the agent)
• Interrupt generation
• Configuration options

Owner-Only Tooling

Some tools are deliberately restricted to owners because they control privileged background work or remote peer activity.

Delegated runs and subagent access

Subagent tooling is owner-only.

This includes:

• subagent_spawn
• subagent_status
• subagent_cancel
• subagent_fanout

How enforcement works:

1. Registration gate (config):
   • Tools are only registered when tools.subagent.enabled=true.
2. Delegated background-work gate (config):
   • Subagents and related background runs are controlled by gateway.delegatedRuns.enabled.
3. Execution authorization (hard check):
   • Each subagent tool checks sessionCtx.User.IsOwner() at execution time.
   • Non-owner calls are rejected even if a role or user tool allowlist includes the tool name.

This means subagent access cannot be granted to non-owner users by role config alone.

A2A tool access

The native a2a tool is also owner-only.

This includes all A2A tool actions:

• status
• peers
• tasks
• pair
• ping
• submit
• resume
• cancel

How enforcement works:

1. Role filtering:
   • Non-owner users do not get the a2a tool in their normal tool list.
2. Execution authorization (hard check):
   • The tool also checks sessionCtx.User.IsOwner() at execution time.
   • Non-owner calls are rejected even if a role or user tool allowlist accidentally includes a2a.

This means A2A peer control cannot be granted to non-owner users by role config alone.

RBAC implications

• Keep normal users on bounded or readonly tools such as read, memory_search, or transcript.
• Treat delegated tooling and A2A peer control as operator capabilities.
• If you need non-owner async or remote-peer workflows, prefer narrowly scoped custom tools rather than exposing subagent or A2A control directly.

Unknown Users and Guest Role

Users not in users.json are treated as guests. By default, no guest role is defined, which means unknown users have no access — this is secure by default.

To allow unknown users (e.g., for a public-facing bot with authentication):

{
  "roles": {
    "guest": {
      "tools": ["read", "user_auth"],
      "skills": [],
      "memory": "none",
      "transcripts": "none",
      "commands": false,
      "systemPrompt": "You are in guest mode. Ask the user for credentials to authenticate."
    }
  }
}

Important: If you define a guest role, consider:

• Keep permissions minimal (read-only, no skills)
• Include user_auth tool if you want guests to authenticate
• Use a system prompt that guides the agent to request credentials
• The agent can then use user_auth to elevate the guest to user role

Unknown users appear in logs:

telegram: unknown user ignored userID=999999999

Examples

Read-only User

{
  "name": "Viewer",
  "role": "user",
  "identities": [{"provider": "telegram", "id": "111111111"}],
  "permissions": ["read"]
}

Power User with Custom Role

In goclaw.json:

{
  "roles": {
    "poweruser": {
      "tools": "*",
      "skills": "*",
      "memory": "full",
      "transcripts": "all",
      "commands": true
    }
  }
}

In users.json:

{
  "name": "PowerUser",
  "role": "poweruser",
  "identities": [{"provider": "telegram", "id": "222222222"}]
}

See Also

• Configuration — Full config reference
• Telegram — Telegram user setup
• WhatsApp — WhatsApp user setup
• Web UI — HTTP authentication
• Tools — Available tools
• Delegated Runs — Delegated/subagent architecture and controls